β.1: amico-run thin process orchestrator (closes #1)

.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: ci
+on:
+  push: { branches: [main] }
+  pull_request:
+jobs:
+  fast:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4   # version pinned by packageManager in package.json
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm -r run build
+      - run: pnpm -r run typecheck
+      - run: pnpm --filter @amicode/amico-run test   # includes the S31 grep-rule test

.vscode/launch.json

@@ -5,8 +5,8 @@
       "name": "Run Extension (amicode-v2)",
       "type": "extensionHost",
       "request": "launch",
-      "args": ["--extensionDevelopmentPath=${workspaceFolder}"],
-      "outFiles": ["${workspaceFolder}/dist/**/*.js"]
+      "args": ["--extensionDevelopmentPath=${workspaceFolder}/packages/extension"],
+      "outFiles": ["${workspaceFolder}/packages/extension/dist/**/*.js"]
     }
   ]
 }

package.json

@@ -1,85 +1,10 @@
 {
-  "name": "amicode-v2",
-  "displayName": "Amicode v2",
-  "description": "Amico research IDE — opencode-backed chat + native VS Code surfaces for vault, catalog, and live solve inspection.",
-  "version": "0.0.1",
-  "publisher": "harmoniqs",
-  "license": "Apache-2.0",
+  "name": "amicode-workspace",
   "private": true,
-  "engines": {
-    "vscode": "^1.95.0"
-  },
-  "categories": ["Other"],
-  "activationEvents": [
-    "onCommand:amicode.openChat",
-    "onCommand:amicode.openInspector",
-    "onView:amicode.runInspector",
-    "onView:amicode.vault",
-    "onStartupFinished"
-  ],
-  "main": "./dist/extension.js",
-  "contributes": {
-    "viewsContainers": {
-      "activitybar": [
-        {
-          "id": "amicode",
-          "title": "Amicode",
-          "icon": "media/amico.svg"
-        }
-      ],
-      "panel": [
-        {
-          "id": "amicode-panel",
-          "title": "Amicode",
-          "icon": "media/amico.svg"
-        }
-      ]
-    },
-    "views": {
-      "amicode": [
-        { "id": "amicode.vault",    "name": "Vault",    "type": "tree" },
-        { "id": "amicode.catalog",  "name": "Catalog",  "type": "tree" },
-        { "id": "amicode.armonia",  "name": "Armonia",  "type": "tree" }
-      ],
-      "amicode-panel": [
-        { "id": "amicode.runInspector", "name": "Run Inspector", "type": "webview" }
-      ]
-    },
-    "commands": [
-      { "command": "amicode.openChat",      "title": "Amicode: Open Chat" },
-      { "command": "amicode.openInspector", "title": "Amicode: Open Run Inspector" },
-      { "command": "amicode.restartServer", "title": "Amicode: Restart opencode server" }
-    ],
-    "configuration": {
-      "title": "Amicode",
-      "properties": {
-        "amicode.opencodeBinary": {
-          "type": "string",
-          "default": "opencode",
-          "description": "Path or command name for the opencode CLI."
-        },
-        "amicode.juliaProject": {
-          "type": "string",
-          "default": "/tmp/amicode-spike-julia",
-          "description": "Julia project root (--project=...) the run_julia tool will use."
-        },
-        "amicode.juliaScript": {
-          "type": "string",
-          "default": "",
-          "description": "Absolute path to spike_solve.jl. If empty, looks up via the extensionPath/../amicode/julia/spike_solve.jl convention."
-        }
-      }
-    }
-  },
   "scripts": {
-    "build":     "node esbuild.config.mjs",
-    "watch":     "node esbuild.config.mjs --watch",
-    "typecheck": "tsc --noEmit"
+    "build": "pnpm -r run build",
+    "typecheck": "pnpm -r run typecheck",
+    "test": "pnpm -r run test"
   },
-  "devDependencies": {
-    "@types/node":   "^22.0.0",
-    "@types/vscode": "^1.95.0",
-    "esbuild":       "^0.24.0",
-    "typescript":    "^5.6.0"
-  }
+  "packageManager": "pnpm@9.15.9"
 }

packages/amico-run/esbuild.config.mjs

@@ -0,0 +1,17 @@
+import { build } from 'esbuild'
+import { chmodSync } from 'node:fs'
+
+await build({
+  entryPoints: ['src/cli.ts'],
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  // ESM, not CJS: the package is "type": "module", so node executes dist/amico-run.js
+  // as ESM — a CJS bundle would die on `require is not defined in ES module scope`.
+  format: 'esm',
+  outfile: 'dist/amico-run.js',
+  banner: { js: '#!/usr/bin/env node' },
+  sourcemap: true,
+  logLevel: 'info',
+})
+chmodSync('dist/amico-run.js', 0o755)

packages/amico-run/launcher/amico-run

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Thin launcher: resolve node, exec the bundled orchestrator. No logic lives here.
+set -euo pipefail
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do                       # resolve symlink chains (node_modules/.bin)
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+if ! command -v node >/dev/null 2>&1; then
+  echo "amico-run: node >= 20 not found on PATH (install node or fix PATH; see provisioning runbook)" >&2
+  exit 64
+fi
+exec node "$DIR/../dist/amico-run.js" "$@"

packages/amico-run/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@amicode/amico-run",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": { "amico-run": "./launcher/amico-run" },
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "build": "node esbuild.config.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests --exclude '**/slow/**'",
+    "test:slow": "vitest run test/slow"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.24.0",
+    "smol-toml": "^1.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

packages/amico-run/src/cli.ts

@@ -0,0 +1,82 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { LocalExecutor } from './local_executor.js'
+import { ConfigError, type Finished, type SubmitOpts } from './types.js'
+
+const USAGE = `usage: amico-run <script.jl> [--executor local] [--lab <id-or-path>]
+                 [--runs-root <path>] [--julia <path>] [--project <path>] [--sysimage <path>]`
+
+export async function main(argv: string[]): Promise<number> {
+  let script: string | undefined
+  let executor = 'local'
+  const opts: SubmitOpts = { julia: {} }
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    const next = (): string => {
+      const v = argv[++i]
+      if (v === undefined) throw new ConfigError(`flag ${a} requires a value`)
+      return v
+    }
+    try {
+      switch (a) {
+        case '--help': case '-h': console.log(USAGE); return 0
+        case '--executor': executor = next(); break
+        case '--lab': opts.lab = next(); break
+        case '--runs-root': opts.runsRoot = next(); break
+        case '--julia': opts.julia!.julia = next(); break
+        case '--project': opts.julia!.project = next(); break
+        case '--sysimage': opts.julia!.sysimage = next(); break
+        default:
+          if (a.startsWith('-')) { console.error(`amico-run: unknown flag ${a}\n${USAGE}`); return 64 }
+          if (script) { console.error(`amico-run: multiple scripts given`); return 64 }
+          script = a
+      }
+    } catch (e) {
+      if (e instanceof ConfigError) { console.error(`amico-run: ${e.message}`); return 64 }
+      throw e
+    }
+  }
+  if (!script) { console.error(`amico-run: no script given\n${USAGE}`); return 64 }
+  if (executor !== 'local') { console.error(`amico-run: only --executor local is supported in β`); return 64 }
+
+  let handle
+  try {
+    handle = await new LocalExecutor().submit(script, opts)
+  } catch (e) {
+    if (e instanceof ConfigError) { console.error(`amico-run: ${e.message}`); return 64 }
+    throw e
+  }
+
+  const onSignal = (): void => { void handle.abort() }
+  process.on('SIGINT', onSignal)
+  process.on('SIGTERM', onSignal)
+
+  let fin: Finished | undefined
+  for await (const ev of handle.events) {
+    if (ev.kind === 'iter' || ev.kind === 'done') console.log(ev.raw)
+    else if (ev.kind === 'log') console.log(ev.line)
+    else fin = { status: ev.status, exitCode: ev.exitCode }
+  }
+  const f = fin ?? await handle.finished
+
+  // FINISHED-write failure lane (spec §6 last row): verdict file must exist on disk
+  if (!existsSync(join(handle.runDir, 'FINISHED'))) {
+    console.error(`amico-run: FINISHED missing in ${handle.runDir} (write fault)`)
+    return 64
+  }
+  // stdout protocol line — camelCase by design (spec §4)
+  console.log(`AMICODE_FINISHED status=${f.status} exitCode=${f.exitCode} runDir=${handle.runDir}`)
+  if (f.status === 'aborted') return 130
+  if (f.status === 'completed') return 0
+  return f.exitCode === 0 ? 1 : f.exitCode
+}
+
+main(process.argv.slice(2)).then(
+  c => { process.exitCode = c },
+  e => {
+    // Any unexpected throw is an orchestrator fault, not a solve failure → 64.
+    console.error(`amico-run: unexpected error: ${e instanceof Error ? e.stack ?? e.message : e}`)
+    process.exitCode = 64
+  },
+)