subconscious-cli 0.1.1 → 0.2.1

package/README.md

@@ -1,16 +1,91 @@
-# @subconscious/cli
+# subconscious-cli
 
-Authenticate with Subconscious from your terminal. One command opens your browser, signs you in (or up), and saves your API key locally.
+Log in to Subconscious from your terminal, then launch your favorite coding
+agent against your hosted Subconscious model — no per-agent config required.
 
 ## Quick start
 
 ```bash
-npx @subconscious/cli login
+npx subconscious-cli login          # sign in, saves your API key
+npx subconscious-cli claude-code    # launch Claude Code on Subconscious
 ```
 
-That's it. Your API key is saved to `~/.subcon/config.json` and ready to use.
+Installed globally it's just `subconscious <command>`:
 
-## How it works
+```bash
+npm install -g subconscious-cli
+subconscious login
+subconscious open-code
+```
+
+## Launching coding agents
+
+`subconscious <agent>` resolves your saved API key, injects the env vars that
+point the agent at Subconscious, and exec's the real CLI. Nothing is written to
+the agent's own config — the provider is passed in-memory for that run only.
+
+Install commands are **OS-specific** — the CLI picks the right one for your
+platform automatically. The table below shows the macOS/Linux command; on
+Windows the equivalent native installer is used instead.
+
+| Command                    | Launches    | Requires (install, macOS/Linux)                         |
+| -------------------------- | ----------- | ------------------------------------------------------- |
+| `subconscious claude-code` | Claude Code | `curl -fsSL https://claude.ai/install.sh \| bash`       |
+| `subconscious open-code`   | OpenCode    | `npm i -g opencode-ai`                                  |
+| `subconscious aider`       | Aider       | `python3 -m pip install aider-install && aider-install` |
+| `subconscious codex`       | Codex CLI   | `npm i -g @openai/codex`                                |
+
+Claude Code uses its **native installer** (the `curl`/`irm` script above), with
+`npm i -g @anthropic-ai/claude-code` kept as an automatic fallback if the native
+installer fails.
+
+If the underlying agent isn't installed and you're in an interactive terminal,
+the CLI offers to install it for you (just press Enter), runs the right
+installer for your OS (trying the fallback if the primary fails), and launches
+it once the install succeeds. In a non-interactive context (CI) it instead
+prints the exact install command (and any fallback) and exits without running
+anything.
+
+Freshly-installed binaries (e.g. Aider and Claude Code land in `~/.local/bin`,
+npm globals in the npm prefix) often aren't on your current shell's `PATH` yet.
+The CLI looks in those common locations and launches the agent anyway. If it
+still can't find the binary right after install, it tells you to **open a new
+terminal** (or add the printed dir to `PATH`) and re-run the command — the
+install itself succeeded.
+
+Anything after the agent name is forwarded straight to it:
+
+```bash
+subconscious claude-code --resume
+subconscious codex exec "write a test"
+```
+
+### Choosing a model
+
+Defaults to `subconscious/tim-qwen3.6-27b`. Override per run with `--model`, or
+set `SUBCONSCIOUS_MODEL` in your environment:
+
+```bash
+subconscious open-code --model subconscious/tim-qwen3.6-27b
+export SUBCONSCIOUS_MODEL=subconscious/tim-qwen3.6-27b
+```
+
+### Pointing at a different endpoint
+
+By default the CLI targets `https://api.subconscious.dev`. Override the base URL
+per run (or for a whole session) with `SUBCONSCIOUS_BASE_URL` — it flows to both
+the Anthropic-style base and the OpenAI-compatible `/v1` base:
+
+```bash
+SUBCONSCIOUS_BASE_URL=http://localhost:9999 subconscious claude-code
+```
+
+## Auth commands
+
+### `login`
+
+Opens your browser to sign in (or create an account). After authentication, your
+API key is automatically generated and saved.
 
 ```
 Terminal                          Browser
@@ -19,41 +94,24 @@ Terminal                          Browser
   │  2. Open browser ───────────────►│
   │                                  │  3. Sign in / sign up via Clerk
   │                                  │  4. API key auto-created
-  │  5. Receive key ◄────────────────│  
+  │  5. Receive key ◄────────────────│
   │  6. Save to ~/.subcon/config.json│
   │                                  │  "You can close this tab"
   ✓ Logged in!                       │
 ```
 
-## Commands
-
-### `login`
-
-Opens your browser to sign in (or create an account). After authentication, your API key is automatically generated and saved.
-
-```bash
-npx @subconscious/cli login
-```
-
 ### `logout`
 
 Removes your saved API key.
 
-```bash
-npx @subconscious/cli logout
-```
-
 ### `whoami`
 
 Shows your current authentication status and which key is active.
 
-```bash
-npx @subconscious/cli whoami
-```
-
 ## Where keys are stored
 
-Keys are saved to `~/.subcon/config.json` with `600` permissions (owner-read-only). The file looks like:
+Keys are saved to `~/.subcon/config.json` with `600` permissions
+(owner-read-only). The file looks like:
 
 ```json
 {
@@ -61,13 +119,5 @@ Keys are saved to `~/.subcon/config.json` with `600` permissions (owner-read-onl
 }
 ```
 
-Environment variable `SUBCONSCIOUS_API_KEY` takes precedence over the config file.
-
-## Global install
-
-If you prefer a persistent command:
-
-```bash
-npm install -g @subconscious/cli
-subconscious login
-```
+Environment variable `SUBCONSCIOUS_API_KEY` takes precedence over the config
+file — handy for CI or temporary overrides.

package/bin/agents.js

@@ -0,0 +1,360 @@
+/**
+ * Coding-agent launcher.
+ *
+ * `subconscious <agent>` resolves your saved API key, injects the env vars that
+ * point the agent at your hosted Subconscious model, and exec's the real CLI —
+ * nothing is written to the agent's own config.
+ *
+ * There is NO hardcoded agent data here: everything is read from
+ * `registry.generated.json` (shipped under `bin/`), which is generated from the
+ * single source of truth `agents/registry.json`. Run `pnpm generate` to update.
+ */
+
+import { spawn, execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+import { c } from './colors.js';
+import { getApiKey } from './auth.js';
+
+// --- Registry (single source of truth, generated copy shipped in the package).
+const registry = JSON.parse(
+  readFileSync(new URL('./registry.generated.json', import.meta.url), 'utf-8'),
+);
+const DEFAULTS = registry.defaults;
+
+// --- Token substitution — same rules as scripts/lib/registry.js.
+// Replaces {apiKey}, {model}, {baseUrl}, {baseUrlV1}. NEVER touches {env:...}.
+const TOKENS = ['apiKey', 'model', 'baseUrl', 'baseUrlV1'];
+
+function substituteString(str, ctx) {
+  let out = str;
+  for (const token of TOKENS) {
+    if (ctx[token] === undefined) continue;
+    out = out.split(`{${token}}`).join(ctx[token]);
+  }
+  return out;
+}
+
+function substitute(value, ctx) {
+  if (typeof value === 'string') return substituteString(value, ctx);
+  if (Array.isArray(value)) return value.map((v) => substitute(v, ctx));
+  if (value && typeof value === 'object') {
+    const keys = Object.keys(value);
+    if (keys.length === 1 && keys[0] === '$json') {
+      return JSON.stringify(substitute(value.$json, ctx));
+    }
+    const out = {};
+    for (const key of keys) out[substituteString(key, ctx)] = substitute(value[key], ctx);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Resolve the install command for the current OS from a per-OS install object.
+ * Falls back to the linux command, then any string value present, if the exact
+ * `process.platform` key is missing. Tolerates a legacy plain-string `install`.
+ * Returns `{ command, fallback }` where `fallback` may be undefined.
+ */
+function resolveInstall(install) {
+  if (typeof install === 'string') return { command: install, fallback: undefined };
+  if (!install || typeof install !== 'object') return { command: undefined, fallback: undefined };
+  const command =
+    install[process.platform] ||
+    install.linux ||
+    Object.values(install).find((v) => typeof v === 'string');
+  return { command, fallback: install.fallback };
+}
+
+// --- Build the in-memory registry + alias index.
+// Each agent gets a resolved per-OS `install` (string) plus optional
+// `installFallback`, while keeping the original per-OS object available.
+const AGENTS = registry.agents.map((agent) => {
+  const { command, fallback } = resolveInstall(agent.install);
+  return { ...agent, install: command, installFallback: fallback };
+});
+const BY_ALIAS = new Map();
+for (const agent of AGENTS) {
+  BY_ALIAS.set(agent.id, agent);
+  for (const alias of agent.aliases || []) BY_ALIAS.set(alias, agent);
+}
+
+export function resolveAgent(name) {
+  return BY_ALIAS.get(name) ?? null;
+}
+
+export function agentList() {
+  return AGENTS.map((a) => ({ name: a.name, alias: a.id }));
+}
+
+/**
+ * Resolve the substitution context for a launch:
+ *   model     — --model flag → SUBCONSCIOUS_MODEL → registry default
+ *   baseUrl   — SUBCONSCIOUS_BASE_URL → registry default
+ *   baseUrlV1 — `${baseUrl}/v1` (so an override flows to both)
+ */
+function buildContext(apiKey, model) {
+  const baseUrl = process.env.SUBCONSCIOUS_BASE_URL?.trim() || DEFAULTS.baseUrl;
+  return { apiKey, model, baseUrl, baseUrlV1: `${baseUrl}/v1` };
+}
+
+/**
+ * Pull a `--model <value>` / `--model=<value>` flag out of the passthrough
+ * args (so it sets the Subconscious model rather than reaching the agent).
+ * Falls back to SUBCONSCIOUS_MODEL, then the registry default.
+ */
+function extractModel(argv) {
+  let model = process.env.SUBCONSCIOUS_MODEL?.trim() || DEFAULTS.model;
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--model') {
+      const v = argv[i + 1];
+      if (v && !v.startsWith('-')) {
+        model = v;
+        i++;
+      }
+      continue;
+    }
+    if (a.startsWith('--model=')) {
+      model = a.slice('--model='.length);
+      continue;
+    }
+    rest.push(a);
+  }
+  return { model, rest };
+}
+
+/**
+ * Common locations a freshly-installed coding-agent binary lands in but which
+ * are often NOT on the current process's PATH (e.g. aider/claude install into
+ * `~/.local/bin`; npm globals into the npm prefix bin). Best-effort, deduped.
+ */
+function candidateBinDirs() {
+  const home = os.homedir();
+  const dirs = [];
+
+  if (process.platform === 'win32') {
+    if (process.env.APPDATA) dirs.push(path.join(process.env.APPDATA, 'npm'));
+    if (process.env.USERPROFILE) {
+      dirs.push(path.join(process.env.USERPROFILE, '.local', 'bin'));
+    }
+    if (home) dirs.push(path.join(home, '.local', 'bin'));
+  } else {
+    dirs.push(path.join(home, '.local', 'bin'));
+    dirs.push('/opt/homebrew/bin');
+    dirs.push('/usr/local/bin');
+  }
+
+  // npm global bin (best-effort — npm may be absent).
+  try {
+    const prefix = execFileSync('npm', ['prefix', '-g'], {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (prefix) {
+      dirs.push(process.platform === 'win32' ? prefix : path.join(prefix, 'bin'));
+    }
+  } catch {
+    // npm not available — skip.
+  }
+
+  // Dedupe, drop empties.
+  return [...new Set(dirs.filter(Boolean))];
+}
+
+/** Executable extensions to probe (Windows uses PATHEXT). */
+function binExts() {
+  return process.platform === 'win32'
+    ? (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';')
+    : [''];
+}
+
+/**
+ * Resolve `bin` against PATH plus the candidate bin dirs. Returns the directory
+ * containing the executable if found, otherwise null. Searching the candidate
+ * dirs lets us find binaries installed this session that aren't on PATH yet.
+ */
+async function resolveBinPath(bin) {
+  const pathDirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  const dirs = [...pathDirs, ...candidateBinDirs()];
+  const exts = binExts();
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, bin + ext);
+      try {
+        await fs.access(candidate, fsConstants.F_OK);
+        return dir;
+      } catch {
+        // keep scanning
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Build a PATH string with `extraDirs` prepended (deduped against PATH).
+ * Returns the augmented PATH value for use in a child env.
+ */
+function augmentPath(extraDirs) {
+  const current = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  const seen = new Set(current);
+  const prepend = extraDirs.filter((d) => d && !seen.has(d));
+  return [...prepend, ...current].join(path.delimiter);
+}
+
+/** Ask a yes/no question on the TTY. Empty answer counts as yes. */
+function askYesNo(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      const a = answer.trim().toLowerCase();
+      resolve(a === '' || a === 'y' || a === 'yes');
+    });
+  });
+}
+
+/** Run the agent's install command (may contain `&&`, so shell:true). */
+function runInstaller(install) {
+  return new Promise((resolve) => {
+    const child = spawn(install, { shell: true, stdio: 'inherit' });
+    child.on('error', () => resolve(false));
+    child.on('exit', (code) => resolve(code === 0));
+  });
+}
+
+/** Print the resolved install command (plus any fallback) for an agent. */
+function printInstallCommands(agent) {
+  console.error(`    ${c.cyan}${agent.install}${c.reset}`);
+  if (agent.installFallback) {
+    console.error(`  ${c.dim}or, as a fallback:${c.reset}`);
+    console.error(`    ${c.cyan}${agent.installFallback}${c.reset}`);
+  }
+  console.error('');
+}
+
+/**
+ * Ensure the agent's binary is resolvable. If missing:
+ *   - interactive TTY: offer to run the per-OS installer (with fallback), then
+ *     re-resolve against PATH + candidate dirs.
+ *   - non-interactive: print the resolved install command (+ fallback) and
+ *     exit 127 without running anything.
+ *
+ * Returns the directory containing the bin (to prepend to the child's PATH) on
+ * success. May exit the process on failure or when manual action is needed.
+ */
+async function ensureInstalled(agent) {
+  const existing = await resolveBinPath(agent.bin);
+  if (existing) return existing;
+
+  const interactive = process.stdin.isTTY && process.stdout.isTTY;
+
+  if (!interactive) {
+    console.error(
+      `\n  ${c.red}${agent.name} isn't installed${c.reset} ${c.dim}(\`${agent.bin}\` not found on PATH).${c.reset}`,
+    );
+    console.error(`  Install it with:\n`);
+    printInstallCommands(agent);
+    process.exit(127);
+  }
+
+  console.error(`\n  ${c.bold}${agent.name}${c.reset} isn't installed.`);
+  const ok = await askYesNo(`  Install it now? ${c.dim}[Y/n]${c.reset} `);
+  if (!ok) {
+    console.error(`\n  No problem. Install it yourself with:\n`);
+    printInstallCommands(agent);
+    process.exit(127);
+  }
+
+  console.error(`\n  ${c.dim}Running ${c.reset}${c.cyan}${agent.install}${c.reset}\n`);
+  let installed = await runInstaller(agent.install);
+
+  // Primary failed and a fallback exists — try it once.
+  if (!installed && agent.installFallback) {
+    console.error(
+      `\n  ${c.dim}That didn't work. Trying the fallback: ${c.reset}${c.cyan}${agent.installFallback}${c.reset}\n`,
+    );
+    installed = await runInstaller(agent.installFallback);
+  }
+
+  if (!installed) {
+    console.error(`\n  ${c.red}Install failed.${c.reset} Try it manually:\n`);
+    printInstallCommands(agent);
+    process.exit(127);
+  }
+
+  // PATH hardening: the freshly-installed binary is often not on the current
+  // process's PATH. Re-resolve against PATH + candidate dirs.
+  const found = await resolveBinPath(agent.bin);
+  if (found) return found;
+
+  console.error(
+    `\n  ${c.dim}Installed ${agent.name}, but it isn't on this shell's PATH yet. ` +
+      `Open a new terminal (or add a bin dir to PATH) and re-run \`subconscious ${agent.id}\`.${c.reset}\n`,
+  );
+  process.exit(0);
+}
+
+/**
+ * Launch a coding agent against Subconscious. `argv` is everything after the
+ * agent name; unknown flags pass straight through to the underlying CLI.
+ */
+export async function runAgent(agent, argv) {
+  const { model, rest } = extractModel(argv);
+
+  const auth = await getApiKey();
+  if (!auth) {
+    console.error(`\n  ${c.red}Not logged in.${c.reset}`);
+    console.error(
+      `  Run ${c.cyan}subconscious login${c.reset} (or set ${c.dim}SUBCONSCIOUS_API_KEY${c.reset}) first.\n`,
+    );
+    process.exit(1);
+  }
+
+  const binDir = await ensureInstalled(agent);
+
+  const ctx = buildContext(auth.key, model);
+  const launch = substituteString(agent.launch, ctx);
+  const [bin, ...launchArgs] = launch.split(' ').filter(Boolean);
+  const envMap = substitute(agent.env, ctx);
+
+  // Prepend the resolved bin dir + candidate dirs to the child's PATH so the
+  // agent (and any subprocess it spawns) resolves correctly this session, even
+  // if it was installed into a dir not yet on the parent shell's PATH.
+  const extraDirs = [binDir, ...candidateBinDirs()].filter(Boolean);
+  const env = { ...process.env, ...envMap, PATH: augmentPath(extraDirs) };
+  const args = [...launchArgs, ...rest];
+
+  console.log(
+    `  ${c.dim}Launching ${c.reset}${c.bold}${agent.name}${c.reset} ${c.dim}on Subconscious ${c.reset}${c.dim}(${model})${c.reset}\n`,
+  );
+
+  const child = spawn(bin, args, { stdio: 'inherit', env });
+
+  child.on('error', (err) => {
+    if (err.code === 'ENOENT') {
+      console.error(
+        `\n  ${c.red}Could not launch \`${bin}\`.${c.reset} Install it with:\n`,
+      );
+      printInstallCommands(agent);
+      process.exit(127);
+    }
+    console.error(`\n  ${c.red}${err.message}${c.reset}\n`);
+    process.exit(1);
+  });
+
+  // Mirror the child's exit status so callers/scripts see the real result.
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 0);
+  });
+}