copillm 0.2.8 → 0.3.0-beta.1

package/dist/cli/shared/devMode.js

@@ -0,0 +1,98 @@
+import os from "node:os";
+import path from "node:path";
+/**
+ * Dev-mode isolation.
+ *
+ * Running a locally-built copillm against the SAME `~/.copillm` home and port as
+ * a globally-installed production daemon is a footgun: `stop` reads
+ * `~/.copillm/copillm.pid` and would kill the production daemon, and `start`
+ * sees the production lock and reports "already running" instead of launching
+ * your dev code.
+ *
+ * Dev mode redirects the runtime onto a separate `COPILLM_HOME` (and a distinct
+ * default port) so a dev daemon and a production daemon can run side by side
+ * without ever touching each other's lock, config, model cache, or port. This
+ * is the mechanism that lets you develop copillm WHILE using copillm.
+ *
+ * The override is implemented by setting the same `COPILLM_HOME` / `COPILLM_PORT`
+ * env vars the rest of the codebase already reads (see `src/config/home.ts` and
+ * `src/config/config.ts`). Because detached daemons and spawned agents inherit
+ * `process.env`, the isolation propagates to every child process for free.
+ *
+ * Activated by the global `--dev` flag or by exporting `COPILLM_DEV=1`. The
+ * concrete locations are overridable via `COPILLM_DEV_HOME` / `COPILLM_DEV_PORT`.
+ * An explicitly-set `COPILLM_HOME` / `COPILLM_PORT` always wins — dev mode never
+ * clobbers a home or port the user pinned on purpose.
+ */
+export const DEV_HOME_DIRNAME = ".copillm-dev";
+export const DEFAULT_DEV_PORT = 4142;
+// Set once dev mode has been applied for this process, so command surfaces
+// (start banner, status) can annotate output without re-deriving intent.
+let devModeActive = false;
+/** Whether dev mode has been applied to this process. */
+export function isDevModeActive() {
+    return devModeActive;
+}
+function isTruthyEnv(value) {
+    if (value === undefined) {
+        return false;
+    }
+    return /^(1|true|yes|on)$/i.test(value.trim());
+}
+function nonEmptyEnv(value) {
+    if (value === undefined) {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Whether dev mode was requested, via the `--dev` flag (passed in) or the
+ * `COPILLM_DEV` env var.
+ */
+export function isDevModeRequested(flag) {
+    return Boolean(flag) || isTruthyEnv(process.env.COPILLM_DEV);
+}
+/** The isolated dev home: `COPILLM_DEV_HOME` if set, else `~/.copillm-dev`. */
+export function resolveDevHome() {
+    const override = nonEmptyEnv(process.env.COPILLM_DEV_HOME);
+    if (override) {
+        return path.resolve(override);
+    }
+    return path.join(os.homedir(), DEV_HOME_DIRNAME);
+}
+/** The isolated dev port: `COPILLM_DEV_PORT` if set, else `4142`. */
+export function resolveDevPort() {
+    const override = nonEmptyEnv(process.env.COPILLM_DEV_PORT);
+    if (override) {
+        return override;
+    }
+    return String(DEFAULT_DEV_PORT);
+}
+/**
+ * Apply dev-mode isolation to `process.env` when requested. Idempotent and
+ * safe to call multiple times.
+ *
+ * - No-op when dev mode is not requested.
+ * - Sets `COPILLM_HOME` to the dev home ONLY when it is not already set, so an
+ *   explicit `COPILLM_HOME` always wins.
+ * - Sets `COPILLM_PORT` to the dev port ONLY when it is not already set, so an
+ *   explicit `COPILLM_PORT` always wins.
+ */
+export function applyDevModeEnv(flag) {
+    if (!isDevModeRequested(flag)) {
+        return { active: false, home: null, port: null };
+    }
+    if (!nonEmptyEnv(process.env.COPILLM_HOME)) {
+        process.env.COPILLM_HOME = resolveDevHome();
+    }
+    if (!nonEmptyEnv(process.env.COPILLM_PORT)) {
+        process.env.COPILLM_PORT = resolveDevPort();
+    }
+    devModeActive = true;
+    return {
+        active: true,
+        home: process.env.COPILLM_HOME ?? null,
+        port: process.env.COPILLM_PORT ?? null
+    };
+}

package/dist/config/accountId.js

@@ -0,0 +1,44 @@
+/**
+ * Account-id validation, shared by the `auth` layer (which writes the accounts
+ * index) and the `models` layer (which embeds the id in a per-account model
+ * cache filename). Lives in `config` so both layers can import it without
+ * crossing a forbidden import boundary.
+ *
+ * An account id is embedded in filenames (`credentials.<id>.json`,
+ * `models.cache.<id>.json`) and in a keychain account string, so it must be a
+ * safe single path segment. GitHub logins are `[A-Za-z0-9-]`; copillm also
+ * permits `.` and `_` for synthetic ids.
+ */
+export const ACCOUNT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export const MAX_ACCOUNT_ID_LENGTH = 64;
+export class InvalidAccountIdError extends Error {
+    accountId;
+    constructor(accountId, reason) {
+        super(`Invalid account id "${accountId}": ${reason}`);
+        this.accountId = accountId;
+        this.name = "InvalidAccountIdError";
+    }
+}
+/**
+ * Validate an account id before it is used in a filename or keychain key.
+ * Throws `InvalidAccountIdError` on anything that isn't a safe path segment.
+ */
+export function assertValidAccountId(accountId) {
+    if (accountId.length === 0) {
+        throw new InvalidAccountIdError(accountId, "id must not be empty.");
+    }
+    if (accountId.length > MAX_ACCOUNT_ID_LENGTH) {
+        throw new InvalidAccountIdError(accountId, `id must be at most ${MAX_ACCOUNT_ID_LENGTH} characters.`);
+    }
+    if (!ACCOUNT_ID_PATTERN.test(accountId)) {
+        throw new InvalidAccountIdError(accountId, "id may only contain letters, digits, '.', '_' and '-', and must start with a letter or digit.");
+    }
+}
+/**
+ * Non-throwing variant for hot paths (e.g. parsing an optional account prefix
+ * out of a request URL) where an invalid id should just mean "not an account
+ * prefix" rather than an error.
+ */
+export function isValidAccountId(accountId) {
+    return accountId.length > 0 && accountId.length <= MAX_ACCOUNT_ID_LENGTH && ACCOUNT_ID_PATTERN.test(accountId);
+}

package/dist/config/config.js

@@ -23,7 +23,7 @@ export function loadConfig() {
     const file = configReadPath();
     if (!fs.existsSync(file)) {
         saveConfig(DEFAULT_CONFIG);
-        return DEFAULT_CONFIG;
+        return applyEnvOverrides(DEFAULT_CONFIG);
     }
     const raw = readFileSync(file, "utf8");
     let parsed;
@@ -33,7 +33,7 @@ export function loadConfig() {
     catch (error) {
         throw new Error(`Invalid YAML in config file: ${file}`, { cause: error });
     }
-    return parseConfigValue(parsed, file);
+    return applyEnvOverrides(parseConfigValue(parsed, file));
 }
 export function saveConfig(config) {
     ensureAppHome();
@@ -49,3 +49,14 @@ function parseConfigValue(value, source) {
     const issues = result.error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ");
     throw new Error(`Invalid config schema in ${source}: ${issues}`);
 }
+function applyEnvOverrides(config) {
+    const port = process.env.COPILLM_PORT;
+    if (port === undefined || port.trim().length === 0) {
+        return config;
+    }
+    const parsedPort = Number(port.trim());
+    if (!Number.isInteger(parsedPort) || parsedPort < 1 || parsedPort > 65535) {
+        throw new Error("Invalid COPILLM_PORT: expected an integer between 1 and 65535.");
+    }
+    return { ...config, preferredPort: parsedPort };
+}

package/dist/config/home.js

@@ -20,6 +20,29 @@ export function credentialsPath() {
 export function credentialsReadPath() {
     return resolveReadablePath("credentials.json");
 }
+/**
+ * Path to the multi-account index (`accounts.json`). Metadata only — never
+ * holds a token. Absent on single-account installs, which keep using the
+ * legacy `credentials.json` / keychain entry as the implicit default account.
+ */
+export function accountsIndexPath() {
+    return path.join(getCopillmHome(), "accounts.json");
+}
+export function accountsIndexReadPath() {
+    return resolveReadablePath("accounts.json");
+}
+/**
+ * Plaintext-fallback credential file for a *named* (non-default) account. The
+ * default account keeps the legacy `credentials.json` path for backward
+ * compatibility; additional accounts are namespaced by id so their tokens
+ * never collide with — or overwrite — the pre-existing default.
+ */
+export function accountCredentialsPath(accountId) {
+    return path.join(getCopillmHome(), `credentials.${accountId}.json`);
+}
+export function accountCredentialsReadPath(accountId) {
+    return resolveReadablePath(`credentials.${accountId}.json`);
+}
 export function lockPath() {
     return path.join(getCopillmHome(), "copillm.pid");
 }
@@ -32,9 +55,55 @@ export function modelsCachePath() {
 export function modelsCacheReadPath() {
     return resolveReadablePath("models.cache.json");
 }
+/**
+ * Per-account model-discovery cache. Different accounts can be entitled to
+ * different model catalogs, so each named account caches into its own
+ * `models.cache.<id>.json`. The primary/legacy account keeps the shared
+ * `models.cache.json` (above), so single-account installs are unaffected.
+ */
+export function accountModelsCachePath(accountId) {
+    return path.join(getCopillmHome(), `models.cache.${accountId}.json`);
+}
+export function accountModelsCacheReadPath(accountId) {
+    return resolveReadablePath(`models.cache.${accountId}.json`);
+}
 export function debugLogPath() {
     return path.join(getCopillmHome(), "debug.log");
 }
+/**
+ * The directory pi (`@earendil-works/pi-coding-agent`) reads its config from.
+ *
+ * pi exposes this via the `PI_CODING_AGENT_DIR` env var — its own `getAgentDir()`
+ * treats the value as the agent dir directly (equivalent to `~/.pi/agent`).
+ * copillm owns this path: it defaults to `<COPILLM_HOME>/pi/agent` so copillm
+ * never writes into the user's real `~/.pi`, and dev mode relocates it for free
+ * via COPILLM_HOME. An explicitly-set `PI_CODING_AGENT_DIR` always wins.
+ */
+export function piAgentDir() {
+    const overridden = process.env.PI_CODING_AGENT_DIR;
+    if (overridden && overridden.trim().length > 0) {
+        return path.resolve(overridden.trim());
+    }
+    return path.join(getCopillmHome(), "pi", "agent");
+}
+/**
+ * The config home Claude Code reads (its `~/.claude` equivalent), exposed by
+ * Claude Code as the `CLAUDE_CONFIG_DIR` env var.
+ *
+ * copillm owns this path: it defaults to `<COPILLM_HOME>/claude/home` and copillm
+ * exports `CLAUDE_CONFIG_DIR` to it when launching Claude (see
+ * `buildClaudeEnvBundle`). This keeps copillm out of the user's real `~/.claude`
+ * — copillm-launched Claude gets a deterministic, copillm-owned config home, and
+ * dev mode relocates it for free via COPILLM_HOME. An explicitly-set
+ * `CLAUDE_CONFIG_DIR` always wins.
+ */
+export function claudeConfigDir() {
+    const overridden = process.env.CLAUDE_CONFIG_DIR;
+    if (overridden && overridden.trim().length > 0) {
+        return path.resolve(overridden.trim());
+    }
+    return path.join(getCopillmHome(), "claude", "home");
+}
 function resolveReadablePath(fileName) {
     const canonical = path.join(getCopillmHome(), fileName);
     if (fs.existsSync(canonical)) {

package/dist/integrations/claude/cache.js

@@ -1,8 +1,11 @@
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
+import { claudeConfigDir } from "../../config/home.js";
 export function claudeGatewayCachePath() {
-    return path.join(os.homedir(), ".claude", "cache", "gateway-models.json");
+    // Claude stores the gateway model-picker cache under its config home
+    // (CLAUDE_CONFIG_DIR). copillm owns that home, so we clear the copillm-owned
+    // copy — never the user's real ~/.claude.
+    return path.join(claudeConfigDir(), "cache", "gateway-models.json");
 }
 export function clearClaudeGatewayCache() {
     const target = claudeGatewayCachePath();

package/dist/integrations/claude/settingsConflict.js

@@ -1,8 +1,11 @@
 import fs from "node:fs";
-import os from "node:os";
+import { claudeConfigDir } from "../../config/home.js";
 import path from "node:path";
 export function claudeSettingsPath() {
-    return path.join(os.homedir(), ".claude", "settings.json");
+    // copillm-launched Claude reads settings from its copillm-owned config home
+    // (CLAUDE_CONFIG_DIR), so the conflict check inspects that file — not the
+    // user's real ~/.claude/settings.json.
+    return path.join(claudeConfigDir(), "settings.json");
 }
 export function detectClaudeSettingsConflicts(launcherEnv, settingsPathOverride) {
     const settingsPath = settingsPathOverride ?? claudeSettingsPath();

package/dist/integrations/codex/init.js

@@ -1,6 +1,5 @@
 import fs from "node:fs";
 import path from "node:path";
-import { CopilotTokenManager } from "../../auth/copilotToken.js";
 import { loadStoredCredential } from "../../auth/credentials.js";
 import { loadConfig } from "../../config/config.js";
 import { listModelsUnion } from "../../models/discovery.js";
@@ -8,20 +7,14 @@ import { ensureSecureDirectory, writeFileSecureAtomic } from "../../config/fsSec
 import { buildCodexCatalog } from "../../server/codexSchema.js";
 import { inspectLock } from "../../server/lock.js";
 export async function generateCodexHome(options) {
-    const config = loadConfig();
-    const creds = await loadStoredCredential();
-    if (!creds) {
-        throw new Error("Not authenticated. Run `copillm login` first.");
-    }
-    const tokenManager = new CopilotTokenManager(creds.token);
-    await tokenManager.ensureToken(false);
-    const discovery = await listModelsUnion(config.accountType, creds.token, 3);
+    const { discovery } = await resolveStartContext(options.precomputed, options.account);
     const catalog = buildCodexCatalog(discovery.models);
     if (catalog.models.length === 0) {
         throw new Error("No Codex-eligible models found in the live catalog.");
     }
     const port = options.port;
-    const proxyUrl = `http://127.0.0.1:${port}/codex/v1`;
+    const prefix = options.pathPrefix ?? "";
+    const proxyUrl = `http://127.0.0.1:${port}${prefix}/codex/v1`;
     const baseUrl = proxyUrl;
     const defaultModel = options.model ?? pickDefaultModel(catalog.models.map((model) => model.slug));
     if (!catalog.models.some((model) => model.slug === defaultModel)) {
@@ -47,6 +40,34 @@ export async function generateCodexHome(options) {
         exportCommand: `CODEX_HOME=${absOutDir} codex`
     };
 }
+/**
+ * Load credentials / config / model discovery once. When the caller has
+ * already done this work (e.g. `copillm start` orchestrating multiple init
+ * steps), it can pass them in via `precomputed` to skip the work.
+ *
+ * Exported so `generatePiHome` (and any future agent init) can use the
+ * same loader and the same "if precomputed, reuse it" contract.
+ */
+export async function resolveStartContext(precomputed, account) {
+    if (precomputed) {
+        return precomputed;
+    }
+    const config = loadConfig();
+    if (account) {
+        const discovery = await listModelsUnion(account.accountType, account.githubToken, 3, undefined, account.cacheId);
+        return {
+            config,
+            creds: { token: account.githubToken, accountType: account.accountType, source: "session" },
+            discovery
+        };
+    }
+    const creds = await loadStoredCredential();
+    if (!creds) {
+        throw new Error("Not authenticated. Run `copillm login` first.");
+    }
+    const discovery = await listModelsUnion(config.accountType, creds.token, 3);
+    return { config, creds, discovery };
+}
 function pickDefaultModel(slugs) {
     const preferred = ["gpt-5.3-codex", "gpt-5.2-codex", "gpt-5.4", "gpt-5.2", "claude-opus-4.5", "claude-sonnet-4.6"];
     for (const candidate of preferred) {

package/dist/integrations/pi/init.js

@@ -1,20 +1,10 @@
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
-import { CopilotTokenManager } from "../../auth/copilotToken.js";
-import { loadStoredCredential } from "../../auth/credentials.js";
-import { loadConfig } from "../../config/config.js";
-import { listModelsUnion } from "../../models/discovery.js";
 import { ensureSecureDirectory, writeFileSecureAtomic } from "../../config/fsSecurity.js";
+import { piAgentDir } from "../../config/home.js";
+import { resolveStartContext } from "../codex/init.js";
 export async function generatePiHome(options) {
-    const config = loadConfig();
-    const creds = await loadStoredCredential();
-    if (!creds) {
-        throw new Error("Not authenticated. Run `copillm login` first.");
-    }
-    const tokenManager = new CopilotTokenManager(creds.token);
-    await tokenManager.ensureToken(false);
-    const discovery = await listModelsUnion(config.accountType, creds.token, 3);
+    const { discovery } = await resolveStartContext(options.precomputed, options.account);
     const eligible = discovery.models.filter(isPickerEligible);
     // Split the catalog by which upstream endpoint each model supports. Models
     // that advertise `/chat/completions` flow through copillm's Anthropic surface
@@ -30,9 +20,10 @@ export async function generatePiHome(options) {
     if (anthropicEligible.length === 0 && responsesEligible.length === 0) {
         throw new Error("No models discovered for pi config.");
     }
-    const proxyUrl = `http://127.0.0.1:${options.port}/anthropic`;
+    const prefix = options.pathPrefix ?? "";
+    const proxyUrl = `http://127.0.0.1:${options.port}${prefix}/anthropic`;
     // OpenAI SDK posts to `<baseUrl>/responses`, so the baseUrl must include `/v1`.
-    const responsesProxyUrl = `http://127.0.0.1:${options.port}/codex/v1`;
+    const responsesProxyUrl = `http://127.0.0.1:${options.port}${prefix}/codex/v1`;
     const providerId = options.providerId.trim().length > 0 ? options.providerId : "copillm";
     const responsesProviderId = `${providerId}-responses`;
     const providers = {};
@@ -79,9 +70,9 @@ export async function generatePiHome(options) {
 export function defaultOutputDir(home) {
     return path.join(home, "pi");
 }
-/** Absolute path to `~/.pi/agent/models.json`. Honors $HOME for tests. */
+/** Absolute path to pi's `models.json`, under the copillm-owned pi agent dir. */
 export function piModelsJsonPath() {
-    return path.join(os.homedir(), ".pi", "agent", "models.json");
+    return path.join(piAgentDir(), "models.json");
 }
 /**
  * Eligibility filter shared by both pi providers. Mirrors the gating in

package/dist/models/anthropicDefaults.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import { z } from "zod";
-import { modelsCacheReadPath } from "../config/home.js";
+import { accountModelsCacheReadPath, modelsCacheReadPath } from "../config/home.js";
+import { assertValidAccountId } from "../config/accountId.js";
 export const ANTHROPIC_FAMILIES = ["opus", "sonnet", "haiku"];
 const SUFFIX_BLOCKLIST = [
     "-high",
@@ -32,8 +33,15 @@ export function computeAnthropicDefaults(modelIds) {
         haiku: pickPlainLatest(byFamily.haiku)
     };
 }
-export function readModelIdsFromCache() {
-    const file = modelsCacheReadPath();
+export function readModelIdsFromCache(accountId) {
+    let file;
+    if (accountId === undefined) {
+        file = modelsCacheReadPath();
+    }
+    else {
+        assertValidAccountId(accountId);
+        file = accountModelsCacheReadPath(accountId);
+    }
     if (!fs.existsSync(file)) {
         return [];
     }
@@ -51,8 +59,9 @@ export function readModelIdsFromCache() {
 }
 export function buildClaudeExportCommand(input) {
     const token = input.callerSecret ?? "copillm-local";
+    const prefix = input.pathPrefix ?? "";
     const parts = [
-        `ANTHROPIC_BASE_URL=http://127.0.0.1:${input.port}/anthropic`,
+        `ANTHROPIC_BASE_URL=http://127.0.0.1:${input.port}${prefix}/anthropic`,
         `ANTHROPIC_AUTH_TOKEN=${token}`
     ];
     if (input.defaults.opus) {