@elliotsystems/eai 0.1.0

package/README.md

@@ -0,0 +1,101 @@
+# `eai` — Elliot AI CLI
+
+The Elliot AI CLI entry point. It resolves the OpenCode runtime binary and hands
+over to it, forwarding every argument verbatim.
+
+```
+eai                  ->  <runtime>              (TUI)
+eai --version        ->  <runtime> --version
+eai --help           ->  <runtime> --help
+eai models           ->  <runtime> models
+eai mcp list         ->  <runtime> mcp list
+eai run "..."        ->  <runtime> run "..."
+```
+
+## Why it parses nothing
+
+Any flag this launcher understands is a flag it can disagree with the runtime
+about. By forwarding `process.argv.slice(2)` untouched, every current and future
+runtime command works on day one and cannot drift. There is no argument schema
+here on purpose.
+
+Arguments are passed **without a shell**, so quoting, spaces and shell
+metacharacters in a prompt arrive exactly as typed. Exit codes are propagated,
+signal deaths are re-raised rather than flattened, and stdio is inherited (which
+is what makes the TUI work).
+
+## How the runtime is located
+
+In precedence order (`lib/resolve.js`):
+
+| # | Source | Path |
+|---|---|---|
+| 1 | `ELLIOT_OPENCODE_BIN` | the binary itself |
+| 2 | bundled runtime | `vendor/opencode-<platform>-<arch>/bin/opencode[.exe]` |
+| 3 | `ELLIOT_OPENCODE_HOME` | `<home>/packages/opencode/dist/…` or `<home>/opencode-<platform>-<arch>/…` |
+| 4 | sibling fork checkout | **development only**, last resort |
+
+Two deliberate rules:
+
+- **Explicit configuration is strict.** If `ELLIOT_OPENCODE_BIN` or
+  `ELLIOT_OPENCODE_HOME` is set, development fallbacks are skipped entirely.
+  Silently running a different build than the operator configured is worse than
+  not running: the results look legitimate and nobody suspects the path.
+- **No PATH lookup.** Falling back to whatever `opencode` happens to be on PATH
+  would let an unrelated or upstream build answer as the Elliot runtime, with no
+  version guarantee.
+
+Platform/arch directory names mirror upstream's own dist naming, so bundling a
+runtime later is a file copy, not a translation.
+
+Set `ELLIOT_LAUNCHER_DEBUG=1` to print the resolved path to **stderr** (stdout
+stays clean for piping).
+
+## Command name
+
+`eai` is a new, unused command name. It deliberately does **not** collide with
+`elliot-ai`, which is the bin name of the shipped legacy CLI
+(`@elliotsystems/elliot-ai`, currently on PATH). Both can coexist, so the legacy
+CLI keeps working untouched and its retirement stays a separate, later decision.
+
+The package is still `private: true` — packaging, publishing and global install
+are out of scope until approved. Run it locally with `node bin/eai`.
+
+## Install
+
+```
+npm i -g @elliotsystems/eai
+```
+
+The platform-specific OpenCode binary is delivered automatically via the package's `optionalDependencies` (`@elliotsystems/eai-<os>-<arch>`). There is no build or toolchain step required on the user's machine.
+
+## Supported platforms (v1)
+
+- `darwin-arm64` (macOS, Apple Silicon)
+- `darwin-x64` (macOS, Intel)
+- `linux-x64` (Linux, x86-64)
+- `linux-arm64` (Linux, ARM64)
+- `windows-x64` (Windows, x86-64)
+
+## Release process (maintainers)
+
+To publish a new release to npm:
+
+1. Ensure the GitHub Actions secret `NPM_TOKEN` is configured (an npm automation/granular token with read+write permissions to the `@elliotsystems` scope) and you are a member of the `@elliotsystems` npm organization.
+
+2. Run the **`publish-eai`** GitHub Actions workflow via `workflow_dispatch`:
+   - Set `dryRun: true` **first** to verify the build and package assembly on CI.
+   - After verifying the dry-run succeeds, trigger again with `dryRun: false` to publish to npm.
+   - Alternatively, push a tag matching `eai-v*` (e.g., `eai-v1.0.0`) to publish directly; the tag triggers a live publish (dry-run is skipped).
+
+3. The workflow cross-compiles all platforms on a single Ubuntu runner (using Bun), assembles per-platform npm packages (`@elliotsystems/eai-<os>-<arch>`), and publishes them along with the meta package. The publish is idempotent—versions already on npm are skipped.
+
+4. Bump `elliot-launcher/package.json` `version` for a new release; all per-platform packages inherit that version.
+
+**Note:** The terminal project-screen `eai` install command currently uses the local vendor + `npm i -g <checkout>` flow. Repointing it to `npm i -g @elliotsystems/eai` is a follow-up task once the first publish succeeds.
+
+## Tests
+
+```
+npm test        # node --test, no dependencies
+```

package/bin/eai

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * `eai` — Elliot AI's CLI entry point.
+ *
+ * This is a LAUNCHER, not a CLI. It deliberately parses nothing: every argument
+ * is forwarded verbatim to the OpenCode runtime, so `--version`, `--help`,
+ * `models`, `run "..."` and the bare TUI all behave exactly as that runtime
+ * defines them, and stay correct as it gains commands. The moment this file
+ * starts interpreting flags, it starts drifting from them.
+ *
+ * The spawn/signal/exit-code handling mirrors upstream's own `bin/opencode`
+ * (v1.18.19) — that shape is already proven against this binary, so copying it
+ * is cheaper and safer than rediscovering it.
+ */
+"use strict"
+
+const childProcess = require("child_process")
+const fs = require("fs")
+const path = require("path")
+
+const {
+  DEV_FALLBACK,
+  candidates,
+  isExplicitlyConfigured,
+  resolveOpencodeBin,
+} = require("../lib/resolve.js")
+
+/**
+ * Resolve symlinks before deriving the package root.
+ *
+ * `npm link` (and `npm i -g` from a path on some setups) puts a symlink — a
+ * junction on Windows — in the global node_modules. Without realpath, __dirname
+ * stays inside that junction, so every path derived from it points at the global
+ * install tree instead of the checkout: the bundled-runtime candidate is empty
+ * there and the dev-checkout candidate resolves to a directory that does not
+ * exist, and `eai` dies with "could not locate the OpenCode runtime" the moment
+ * it is run from outside the repo.
+ *
+ * Upstream's own `bin/opencode` does exactly this (`fs.realpathSync(__filename)`)
+ * for the same reason. Falls back to the unresolved path if realpath fails, so a
+ * broken link degrades to the old behaviour rather than crashing here.
+ */
+function packageRoot() {
+  try {
+    return path.resolve(path.dirname(fs.realpathSync(__filename)), "..")
+  } catch {
+    return path.resolve(__dirname, "..")
+  }
+}
+
+const PACKAGE_ROOT = packageRoot()
+const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"]
+
+function fail(message) {
+  process.stderr.write(`eai: ${message}\n`)
+  process.exit(127) // conventional "command not found"
+}
+
+const resolved = resolveOpencodeBin({ packageRoot: PACKAGE_ROOT })
+
+if (!resolved) {
+  // Report exactly what was consulted. Under explicit configuration the dev
+  // fallback is skipped, so listing it would send a person debugging this down
+  // a path the launcher never actually tried.
+  const strict = isExplicitlyConfigured(process.env)
+  const tried = candidates({ packageRoot: PACKAGE_ROOT })
+    .filter((c) => !(strict && c.source === DEV_FALLBACK))
+    .map((c) => `  - ${c.source}: ${c.path}`)
+    .join("\n")
+  fail(
+    "could not locate the OpenCode runtime binary.\n" +
+      `Tried, in order:\n${tried}\n` +
+      (strict ? "Explicit configuration is set; development fallbacks were skipped.\n" : "") +
+      "Set ELLIOT_OPENCODE_BIN to the binary, or ELLIOT_OPENCODE_HOME to the fork checkout.",
+  )
+}
+
+if (process.env.ELLIOT_LAUNCHER_DEBUG) {
+  // Opt-in only: the resolved path helps when a launch goes wrong, but it is
+  // noise on every normal run, and stdout must stay clean for piped output.
+  process.stderr.write(`eai: launching ${resolved.path} (via ${resolved.source})\n`)
+}
+
+// argv passes through untouched and WITHOUT a shell, so quoting, spaces and
+// shell metacharacters in a prompt reach the runtime as the user typed them and
+// are never re-interpreted by an intermediate shell.
+const child = childProcess.spawn(resolved.path, process.argv.slice(2), { stdio: "inherit" })
+
+child.on("error", (error) => fail(error.message))
+
+const forwarders = {}
+for (const signal of FORWARDED_SIGNALS) {
+  forwarders[signal] = () => {
+    try {
+      child.kill(signal)
+    } catch {
+      // Already exited; nothing to signal.
+    }
+  }
+  process.on(signal, forwarders[signal])
+}
+
+child.on("exit", (code, signal) => {
+  for (const s of FORWARDED_SIGNALS) process.removeListener(s, forwarders[s])
+
+  // Re-raise rather than translating to an exit code, so callers can still tell
+  // "killed by signal" from "exited non-zero" — scripts and CI depend on that.
+  if (signal) {
+    process.kill(process.pid, signal)
+    return
+  }
+  process.exit(typeof code === "number" ? code : 0)
+})

package/lib/resolve.js

@@ -0,0 +1,132 @@
+/**
+ * Locate the OpenCode runtime binary that `eai` should launch.
+ *
+ * Kept as a pure, dependency-free module so the resolution ORDER — the only real
+ * logic in this launcher — is testable without spawning anything.
+ *
+ * Platform/arch names deliberately mirror upstream's own dist naming
+ * (`opencode-<platform>-<arch>`, see packages/opencode/bin/opencode @ v1.18.19).
+ * That is what makes future bundling a file COPY rather than a translation.
+ */
+"use strict"
+
+const fs = require("fs")
+const path = require("path")
+const os = require("os")
+
+const DEV_FALLBACK = "in-repo fork checkout (dev)"
+const SIBLING_FALLBACK = "sibling fork checkout (dev)"
+
+const PLATFORM_MAP = { darwin: "darwin", linux: "linux", win32: "windows" }
+const ARCH_MAP = { x64: "x64", arm64: "arm64", arm: "arm" }
+
+function platformTriple(platform = os.platform(), arch = os.arch()) {
+  const p = PLATFORM_MAP[platform] || platform
+  const a = ARCH_MAP[arch] || arch
+  return {
+    dir: `opencode-${p}-${a}`,
+    binary: p === "windows" ? "opencode.exe" : "opencode",
+  }
+}
+
+/**
+ * Candidate paths in precedence order, each with a human-readable source so a
+ * failure can explain what was tried instead of just "not found".
+ *
+ * @param {{packageRoot: string, env?: NodeJS.ProcessEnv, platform?: string, arch?: string}} opts
+ */
+function candidates(opts) {
+  const env = opts.env || process.env
+  const { dir, binary } = platformTriple(opts.platform, opts.arch)
+  const platform = PLATFORM_MAP[opts.platform || os.platform()] || opts.platform || os.platform()
+  const arch = ARCH_MAP[opts.arch || os.arch()] || opts.arch || os.arch()
+  const requireResolve = opts.requireResolve || require.resolve
+  const root = opts.packageRoot
+  const out = []
+
+  // 1. Explicit override. Highest precedence, always: this is how CI, tests and
+  //    a developer pointing at a locally built fork get a deterministic answer.
+  if (env.ELLIOT_OPENCODE_BIN) {
+    out.push({ source: "ELLIOT_OPENCODE_BIN", path: env.ELLIOT_OPENCODE_BIN })
+  }
+
+  // 2. Per-platform npm optionalDependency package — the shape a published,
+  //    `npm install`-ed `@elliotsystems/eai` gets its runtime from. Resolved via
+  //    `require.resolve` so it works no matter where npm hoisted node_modules.
+  try {
+    const p = requireResolve(`@elliotsystems/eai-${platform}-${arch}/package.json`)
+    out.push({ source: "platform package (optionalDependency)", path: path.join(path.dirname(p), "bin", binary) })
+  } catch {
+    // Platform package not installed (e.g. running from a dev checkout).
+  }
+
+  // 3. Bundled runtime — the shape a published/installed Elliot package will
+  //    have. Nothing populates this yet; packaging is a later, approved phase.
+  out.push({ source: "bundled vendor runtime", path: path.join(root, "vendor", dir, "bin", binary) })
+
+  // 4. A configured fork location. Accepts either a checkout root or a dist
+  //    root, because both are things a person reasonably points this at.
+  if (env.ELLIOT_OPENCODE_HOME) {
+    const home = env.ELLIOT_OPENCODE_HOME
+    out.push({
+      source: "ELLIOT_OPENCODE_HOME (checkout)",
+      path: path.join(home, "packages", "opencode", "dist", dir, "bin", binary),
+    })
+    out.push({ source: "ELLIOT_OPENCODE_HOME (dist)", path: path.join(home, dir, "bin", binary) })
+  }
+
+  // 5. Development convenience ONLY: the fork lives in this repo at `opencode/`
+  //    (subtree), so from the launcher package root that is one level up. Kept
+  //    explicitly last before PATH so a dev build can never silently win over an
+  //    override or a packaged runtime.
+  out.push({
+    source: DEV_FALLBACK,
+    path: path.join(root, "..", "opencode", "packages", "opencode", "dist", dir, "bin", binary),
+  })
+
+  // The same checkout one level higher: the fork cloned BESIDE Elliot-AI rather
+  // than inside it. Both layouts exist in practice, and looking only in-repo
+  // fails confusingly -- an empty `Elliot-AI/opencode` directory matches the path
+  // above, so resolution reports "no built runtime" while a freshly built binary
+  // sits in the sibling checkout. Cheap to try both; the first that has a real
+  // file wins.
+  out.push({
+    source: SIBLING_FALLBACK,
+    path: path.join(root, "..", "..", "opencode", "packages", "opencode", "dist", dir, "bin", binary),
+  })
+
+  return out
+}
+
+/** True when the operator explicitly told us where the runtime is. */
+function isExplicitlyConfigured(env) {
+  return Boolean(env.ELLIOT_OPENCODE_BIN || env.ELLIOT_OPENCODE_HOME)
+}
+
+/**
+ * First candidate that exists on disk, or null.
+ *
+ * Explicit configuration is STRICT: if ELLIOT_OPENCODE_BIN or
+ * ELLIOT_OPENCODE_HOME is set, the dev-only fallbacks are not consulted at all.
+ * Silently launching a different runtime than the operator configured is worse
+ * than not launching — it produces results attributed to the wrong build, and
+ * the person debugging has no reason to suspect the path.
+ */
+function resolveOpencodeBin(opts) {
+  const env = opts.env || process.env
+  const strict = isExplicitlyConfigured(env)
+
+  for (const candidate of candidates({ ...opts, env })) {
+    if (strict && (candidate.source === DEV_FALLBACK || candidate.source === SIBLING_FALLBACK)) continue
+    try {
+      if (fs.statSync(candidate.path).isFile()) {
+        return { ...candidate, path: path.resolve(candidate.path) }
+      }
+    } catch {
+      // Missing or unreadable — try the next candidate.
+    }
+  }
+  return null
+}
+
+module.exports = { DEV_FALLBACK, SIBLING_FALLBACK, candidates, isExplicitlyConfigured, platformTriple, resolveOpencodeBin }

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@elliotsystems/eai",
+  "version": "0.1.0",
+  "description": "Elliot AI CLI entry point (eai) - launches the Elliot runtime with arguments forwarded verbatim.",
+  "bin": {
+    "eai": "./bin/eai"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "vendor": "node scripts/vendor.js",
+    "assemble": "node scripts/assemble.js",
+    "publish:npm": "node scripts/publish.js",
+    "build:runtime": "bun run --cwd ../opencode/packages/opencode script/build.ts --skip-embed-web-ui"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "optionalDependencies": {
+    "@elliotsystems/eai-darwin-arm64": "0.1.0",
+    "@elliotsystems/eai-darwin-x64": "0.1.0",
+    "@elliotsystems/eai-linux-x64": "0.1.0",
+    "@elliotsystems/eai-linux-arm64": "0.1.0",
+    "@elliotsystems/eai-windows-x64": "0.1.0"
+  }
+}