arceus-s 1.6.4

package/dist/cli/optional-grammars.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Optional grammar availability check.
+ *
+ * tree-sitter-dart and tree-sitter-proto are optionalDependencies that
+ * require a `node-gyp rebuild` at install time. The build can be skipped
+ * via ARC_SKIP_OPTIONAL_GRAMMARS=1 (postinstall scripts), or it can
+ * silently soft-fail when the C++ toolchain is missing.
+ *
+ * Either path produces the same observable: the .node binding is absent
+ * at runtime. This helper detects that condition and surfaces a single
+ * stderr line per missing grammar so users learn why .dart/.proto support
+ * is unavailable instead of silently getting a degraded index.
+ */
+export interface MissingGrammar {
+    name: string;
+    extensions: string[];
+}
+/**
+ * Returns the list of optional grammars whose native binding cannot be
+ * loaded. Actually `require()`s the package — `require.resolve` would
+ * locate the entry path even when the `.node` binding is absent (the
+ * `file:` package directory is installed regardless of postinstall
+ * outcome), giving false negatives for the exact users we want to warn:
+ * those who installed with `ARC_SKIP_OPTIONAL_GRAMMARS=1` or whose
+ * native rebuild soft-failed for missing toolchain.
+ *
+ * Node's module cache memoizes `require()` for us — calling this multiple
+ * times is cheap. The catch distinguishes "missing" (MODULE_NOT_FOUND or
+ * the typical node-gyp-build "could not find any binding" pattern) from
+ * "broken" (SyntaxError, EACCES, native crash). Broken bindings surface a
+ * separate stderr line so users get an actionable message instead of a
+ * misleading "reinstall" hint.
+ */
+export declare function detectMissingOptionalGrammars(): MissingGrammar[];
+/**
+ * Log a one-line stderr warning for each missing grammar. Safe to call
+ * unconditionally — silent if all grammars are present.
+ *
+ * `relevantExtensions`, if provided, filters the warning to grammars whose
+ * extensions appear in the set (e.g. an analyze run can pass the set of
+ * extensions actually present in the target repo so users without any
+ * .dart/.proto files don't see noise).
+ */
+export declare function warnMissingOptionalGrammars(opts?: {
+    context?: string;
+    relevantExtensions?: ReadonlySet<string>;
+}): void;

package/dist/cli/optional-grammars.js

@@ -0,0 +1,87 @@
+/**
+ * Optional grammar availability check.
+ *
+ * tree-sitter-dart and tree-sitter-proto are optionalDependencies that
+ * require a `node-gyp rebuild` at install time. The build can be skipped
+ * via ARC_SKIP_OPTIONAL_GRAMMARS=1 (postinstall scripts), or it can
+ * silently soft-fail when the C++ toolchain is missing.
+ *
+ * Either path produces the same observable: the .node binding is absent
+ * at runtime. This helper detects that condition and surfaces a single
+ * stderr line per missing grammar so users learn why .dart/.proto support
+ * is unavailable instead of silently getting a degraded index.
+ */
+import { createRequire } from 'module';
+import { cliWarn } from './cli-message.js';
+const _require = createRequire(import.meta.url);
+const OPTIONAL_GRAMMARS = [
+    { name: 'tree-sitter-dart', pkg: 'tree-sitter-dart', extensions: ['.dart'] },
+    { name: 'tree-sitter-proto', pkg: 'tree-sitter-proto', extensions: ['.proto'] },
+];
+/**
+ * Returns the list of optional grammars whose native binding cannot be
+ * loaded. Actually `require()`s the package — `require.resolve` would
+ * locate the entry path even when the `.node` binding is absent (the
+ * `file:` package directory is installed regardless of postinstall
+ * outcome), giving false negatives for the exact users we want to warn:
+ * those who installed with `ARC_SKIP_OPTIONAL_GRAMMARS=1` or whose
+ * native rebuild soft-failed for missing toolchain.
+ *
+ * Node's module cache memoizes `require()` for us — calling this multiple
+ * times is cheap. The catch distinguishes "missing" (MODULE_NOT_FOUND or
+ * the typical node-gyp-build "could not find any binding" pattern) from
+ * "broken" (SyntaxError, EACCES, native crash). Broken bindings surface a
+ * separate stderr line so users get an actionable message instead of a
+ * misleading "reinstall" hint.
+ */
+export function detectMissingOptionalGrammars() {
+    const missing = [];
+    for (const g of OPTIONAL_GRAMMARS) {
+        try {
+            _require(g.pkg);
+        }
+        catch (err) {
+            const code = err?.code;
+            const msg = err instanceof Error ? err.message : String(err);
+            const looksMissing = code === 'MODULE_NOT_FOUND' ||
+                code === 'ERR_MODULE_NOT_FOUND' ||
+                /could not find|no native build|prebuilds/i.test(msg);
+            if (!looksMissing) {
+                // Present but broken — surface so the user doesn't get a misleading
+                // "reinstall" recovery message that wouldn't actually help. cliWarn
+                // writes plain text to stderr AND tees a structured logger.warn
+                // record; the merged repo-wide ESLint pino-migration rule forbids
+                // direct `console.error` in CLI code (only `console.log` is allowed
+                // there for tool-data stdout output).
+                cliWarn(`Arceus: optional grammar "${g.name}" is installed but failed to load (${msg.slice(0, 200)}). ${g.extensions.join('/')} files will not be parsed.`, { grammar: g.name, extensions: g.extensions, error: msg });
+            }
+            missing.push({ name: g.name, extensions: g.extensions });
+        }
+    }
+    return missing;
+}
+/**
+ * Log a one-line stderr warning for each missing grammar. Safe to call
+ * unconditionally — silent if all grammars are present.
+ *
+ * `relevantExtensions`, if provided, filters the warning to grammars whose
+ * extensions appear in the set (e.g. an analyze run can pass the set of
+ * extensions actually present in the target repo so users without any
+ * .dart/.proto files don't see noise).
+ */
+export function warnMissingOptionalGrammars(opts) {
+    const missing = detectMissingOptionalGrammars();
+    if (missing.length === 0)
+        return;
+    const ctx = opts?.context ? ` [${opts.context}]` : '';
+    // Hoist the optional set into a local so the closure below can narrow
+    // its type; references to `opts?.relevantExtensions` inside `.some()`
+    // lose the outer null-check narrowing and require a non-null assertion.
+    const relevantExtensions = opts?.relevantExtensions;
+    for (const g of missing) {
+        if (relevantExtensions && !g.extensions.some((e) => relevantExtensions.has(e))) {
+            continue;
+        }
+        cliWarn(`Arceus${ctx}: optional grammar "${g.name}" is unavailable — ${g.extensions.join('/')} files will not be parsed. Reinstall without ARC_SKIP_OPTIONAL_GRAMMARS=1 (and ensure python3, make, g++) to enable.`, { grammar: g.name, extensions: g.extensions, context: opts?.context });
+    }
+}

package/dist/cli/publish.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `arc publish` — opt-in ping to the understand-quickly registry.
+ *
+ * Fires a single `repository_dispatch` event at
+ * `looptech-ai/understand-quickly` so the registry knows to refresh its
+ * entry for the current repo. Does NOT upload anything: per the
+ * understand-quickly protocol, the registry pulls the graph from a
+ * raw-GitHub URL the user controls.
+ *
+ *   https://github.com/looptech-ai/understand-quickly/blob/main/docs/integrations/protocol.md
+ *
+ * Defaults:
+ *   - Without `UNDERSTAND_QUICKLY_TOKEN` in the env, this is a no-op
+ *     (prints one informational line, exit 0). Same shape as the
+ *     `--publish` patterns in sibling tools.
+ *   - With the token, fires the dispatch and reports the response code.
+ *
+ * The `id` is derived from the repo's `origin` remote unless the caller
+ * passes `--id <owner/repo>` explicitly. We deliberately do NOT auto-add
+ * the repo to the registry — registration is one-time and uses the
+ * `npx @understand-quickly/cli add` path documented in the protocol.
+ */
+export interface PublishOptions {
+    /** Override the auto-derived `owner/repo` id. */
+    id?: string;
+    /** Treat the cwd as the repo root (skip git-root walk). */
+    skipGit?: boolean;
+}
+export declare const publishCommand: (inputPath?: string, options?: PublishOptions) => Promise<void>;

package/dist/cli/publish.js

@@ -0,0 +1,174 @@
+/**
+ * `arc publish` — opt-in ping to the understand-quickly registry.
+ *
+ * Fires a single `repository_dispatch` event at
+ * `looptech-ai/understand-quickly` so the registry knows to refresh its
+ * entry for the current repo. Does NOT upload anything: per the
+ * understand-quickly protocol, the registry pulls the graph from a
+ * raw-GitHub URL the user controls.
+ *
+ *   https://github.com/looptech-ai/understand-quickly/blob/main/docs/integrations/protocol.md
+ *
+ * Defaults:
+ *   - Without `UNDERSTAND_QUICKLY_TOKEN` in the env, this is a no-op
+ *     (prints one informational line, exit 0). Same shape as the
+ *     `--publish` patterns in sibling tools.
+ *   - With the token, fires the dispatch and reports the response code.
+ *
+ * The `id` is derived from the repo's `origin` remote unless the caller
+ * passes `--id <owner/repo>` explicitly. We deliberately do NOT auto-add
+ * the repo to the registry — registration is one-time and uses the
+ * `npx @understand-quickly/cli add` path documented in the protocol.
+ */
+import path from 'path';
+import { UNDERSTAND_QUICKLY_DISPATCH_URL, UNDERSTAND_QUICKLY_TOKEN_ENV, buildUqDispatchPayload, isValidOwnerRepo, parseOwnerRepoFromRemote, } from '../_shared/index.js';
+import { getGitRoot, getRemoteOriginUrl, getCurrentCommit } from '../storage/git.js';
+import { hasIndex } from '../storage/repo-manager.js';
+import { cliInfo, cliError } from './cli-message.js';
+const REGISTER_HINT = 'Register your repo once with: npx @understand-quickly/cli add\n' +
+    'Or use the wizard: https://looptech-ai.github.io/understand-quickly/add.html';
+/**
+ * Hard cap on the dispatch fetch to keep CI publish steps from stalling
+ * for the OS TCP timeout (~2 min) when api.github.com is unreachable.
+ * Matches the pattern used in `src/core/embeddings/http-client.ts`.
+ */
+const DISPATCH_TIMEOUT_MS = 15_000;
+export const publishCommand = async (inputPath, options = {}) => {
+    // ── 0. Token gate FIRST — guarantees true no-op without the token. ──
+    // The README, CLI --help, and PR body all promise "exit 0 without
+    // UNDERSTAND_QUICKLY_TOKEN". Doing the index/repo-root checks before
+    // the token gate would make those promises false for users who haven't
+    // run `arc analyze` yet but want to verify the command is wired.
+    const token = process.env[UNDERSTAND_QUICKLY_TOKEN_ENV];
+    if (!token) {
+        cliInfo(`[understand-quickly] ${UNDERSTAND_QUICKLY_TOKEN_ENV} is not set — skipping dispatch.\n` +
+            `Set it to a fine-grained PAT with "Repository dispatches: write" on ` +
+            `looptech-ai/understand-quickly to enable instant resync.\n` +
+            `(Without the token, the registry's nightly sync still picks up your entry.)`, { skipped: 'no-token' });
+        return;
+    }
+    // ── 1. Resolve the repo root (same precedence as `analyze`) ──────────
+    let repoPath;
+    if (inputPath) {
+        repoPath = path.resolve(inputPath);
+    }
+    else if (options.skipGit) {
+        repoPath = path.resolve(process.cwd());
+    }
+    else {
+        const gitRoot = getGitRoot(process.cwd());
+        if (!gitRoot) {
+            cliError('[understand-quickly] not inside a git repository.\n' +
+                'Run from a repo, or pass --skip-git to publish from the current directory.');
+            process.exitCode = 1;
+            return;
+        }
+        repoPath = gitRoot;
+    }
+    // ── 2. Confirm a Arceus index exists ───────────────────────────────
+    // Publishing without an index is almost always a mistake — the
+    // registry's nightly sync would fetch a stale or missing graph file
+    // and mark the entry `missing`. Refuse loudly with a fix-it hint.
+    if (!(await hasIndex(repoPath))) {
+        cliError(`[understand-quickly] no Arceus index found at ${repoPath}/.arc.\n` +
+            'Run `arc analyze` first, then re-run `arc publish`.');
+        process.exitCode = 1;
+        return;
+    }
+    // ── 3. Derive the registry id ─────────────────────────────────────────
+    const id = options.id ?? parseOwnerRepoFromRemote(getRemoteOriginUrl(repoPath) ?? undefined) ?? null;
+    if (!id || !isValidOwnerRepo(id)) {
+        cliError(`[understand-quickly] could not derive a registry id from this repo.\n` +
+            `Pass --id <owner/repo> explicitly (e.g. --id looptech-ai/${path.basename(repoPath)}).\n` +
+            REGISTER_HINT);
+        process.exitCode = 1;
+        return;
+    }
+    // ── 4. Fire the dispatch ─────────────────────────────────────────────
+    const payload = buildUqDispatchPayload(id);
+    let response;
+    try {
+        response = await fetch(UNDERSTAND_QUICKLY_DISPATCH_URL, {
+            method: 'POST',
+            headers: {
+                Accept: 'application/vnd.github+json',
+                Authorization: `Bearer ${token}`,
+                'X-GitHub-Api-Version': '2022-11-28',
+                'Content-Type': 'application/json',
+                'User-Agent': 'arc-cli',
+            },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(DISPATCH_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        // `AbortSignal.timeout()` throws a `DOMException` with `name ===
+        // 'TimeoutError'` on Node 18.14+ (and on browsers/Bun). It is NOT
+        // a plain `AbortError`. Match the pattern used in
+        // arc/src/core/embeddings/http-client.ts so the user sees the
+        // targeted "timed out" message instead of a generic "operation
+        // was aborted".
+        const isTimeout = err instanceof DOMException && err.name === 'TimeoutError';
+        if (isTimeout) {
+            cliError(`[understand-quickly] dispatch timed out after ${DISPATCH_TIMEOUT_MS}ms. ` +
+                `Check network access to api.github.com and retry.`, { id });
+        }
+        else {
+            const msg = err instanceof Error ? err.message : String(err);
+            cliError(`[understand-quickly] dispatch network error: ${msg}`, { id });
+        }
+        process.exitCode = 1;
+        return;
+    }
+    // GitHub returns 204 on success. Distinct branches for 401/403/404/422
+    // so users debug without checking the docs.
+    if (response.status === 204) {
+        await response.body?.cancel().catch(() => { });
+        // `getCurrentCommit` is only meaningful in the success path — moving
+        // it inside this branch removes a wasted child-process spawn on every
+        // error response (LOW 7).
+        const commit = getCurrentCommit(repoPath);
+        cliInfo(`[understand-quickly] dispatched sync-entry for ${id}` +
+            (commit ? ` @ ${commit.slice(0, 7)}` : '') +
+            '.\n' +
+            `Note: a 204 only confirms GitHub accepted the dispatch. Whether the ` +
+            `registry workflow finds an entry for "${id}" is logged at ` +
+            `https://github.com/looptech-ai/understand-quickly/actions/workflows/sync.yml`, { id, commit, status: response.status });
+        return;
+    }
+    if (response.status === 401) {
+        cliError(`[understand-quickly] dispatch returned 401 — the ${UNDERSTAND_QUICKLY_TOKEN_ENV} value is invalid or expired.\n` +
+            `Regenerate a fine-grained PAT at https://github.com/settings/personal-access-tokens ` +
+            `with Repository access scoped to looptech-ai/understand-quickly and the ` +
+            `"Repository dispatches: write" permission, then retry.`, { id, status: response.status });
+        process.exitCode = 1;
+        return;
+    }
+    if (response.status === 403) {
+        cliError(`[understand-quickly] dispatch returned 403 — the token authenticated but ` +
+            `lacks the "Repository dispatches: write" permission on ` +
+            `looptech-ai/understand-quickly. Edit the PAT scopes and retry.`, { id, status: response.status });
+        process.exitCode = 1;
+        return;
+    }
+    if (response.status === 404) {
+        cliError(`[understand-quickly] dispatch returned 404 — the token cannot reach ` +
+            `looptech-ai/understand-quickly. Verify the PAT has Repository access to ` +
+            `that exact repo (not just your own org).`, { id, status: response.status });
+        process.exitCode = 1;
+        return;
+    }
+    if (response.status === 422) {
+        // Malformed event_type / client_payload — a code bug in this CLI,
+        // not a user mistake. Surface so we get bug reports.
+        const body422 = await response.text().catch(() => '');
+        cliError(`[understand-quickly] dispatch returned 422 (this is a CLI bug; please report).\n` +
+            `Body: ${body422 || '(empty)'}`, { id, status: response.status });
+        process.exitCode = 1;
+        return;
+    }
+    // 5xx and anything else → bubble the body so the user has something to act on.
+    const body = await response.text().catch(() => '');
+    cliError(`[understand-quickly] dispatch failed with HTTP ${response.status}: ${body || '(empty body)'}`, { id, status: response.status });
+    process.exitCode = 1;
+};

package/dist/cli/remove.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Remove Command (#664)
+ *
+ * Delete the `.arc/` index for a registered repo and unregister it
+ * from the global registry (~/.arc/registry.json). The target is
+ * identified by alias / basename-derived name / remote-inferred name /
+ * absolute path — no `--repo` flag, just a positional argument so the
+ * destructive-command ergonomics match `clean` (which is also
+ * destructive but scoped to `process.cwd()`).
+ *
+ * Compared to `clean`:
+ *   - `clean`  acts on the repo discovered by walking up from cwd.
+ *   - `remove` acts on any registered repo identified by name or path.
+ *
+ * Behaviour notes:
+ *   - Idempotent on unknown targets: exits 0 with a warning so that
+ *     `remove X && analyze Y` keeps working in scripts. Per #664:
+ *     "behave atomically and idempotently so retries are safe".
+ *   - Atomic order mirrors `clean`: fs.rm FIRST, then unregister. A
+ *     partial failure leaves the registry pointing at a missing dir
+ *     (recoverable by `listRegisteredRepos({ validate: true })` on
+ *     next read) rather than the opposite, which would orphan
+ *     .arc/ directories on disk.
+ *   - `-f` / `--force` matches the confirmation-skip semantics of
+ *     `clean -f`. (Distinct from `analyze --force`, which re-indexes;
+ *     here there is no pipeline, so no conflation.)
+ */
+export declare const removeCommand: (target: string, options?: {
+    force?: boolean;
+}) => Promise<void>;

package/dist/cli/remove.js

@@ -0,0 +1,102 @@
+/**
+ * Remove Command (#664)
+ *
+ * Delete the `.arc/` index for a registered repo and unregister it
+ * from the global registry (~/.arc/registry.json). The target is
+ * identified by alias / basename-derived name / remote-inferred name /
+ * absolute path — no `--repo` flag, just a positional argument so the
+ * destructive-command ergonomics match `clean` (which is also
+ * destructive but scoped to `process.cwd()`).
+ *
+ * Compared to `clean`:
+ *   - `clean`  acts on the repo discovered by walking up from cwd.
+ *   - `remove` acts on any registered repo identified by name or path.
+ *
+ * Behaviour notes:
+ *   - Idempotent on unknown targets: exits 0 with a warning so that
+ *     `remove X && analyze Y` keeps working in scripts. Per #664:
+ *     "behave atomically and idempotently so retries are safe".
+ *   - Atomic order mirrors `clean`: fs.rm FIRST, then unregister. A
+ *     partial failure leaves the registry pointing at a missing dir
+ *     (recoverable by `listRegisteredRepos({ validate: true })` on
+ *     next read) rather than the opposite, which would orphan
+ *     .arc/ directories on disk.
+ *   - `-f` / `--force` matches the confirmation-skip semantics of
+ *     `clean -f`. (Distinct from `analyze --force`, which re-indexes;
+ *     here there is no pipeline, so no conflation.)
+ */
+import fs from 'fs/promises';
+import { logger } from '../core/logger.js';
+import { cliError } from './cli-message.js';
+import { readRegistry, resolveRegistryEntry, assertSafeStoragePath, unregisterRepo, RegistryNotFoundError, RegistryAmbiguousTargetError, UnsafeStoragePathError, } from '../storage/repo-manager.js';
+export const removeCommand = async (target, options) => {
+    // Read the registry snapshot once and pass it to the resolver — this
+    // lets us render the "before" state in the dry-run path without a
+    // second disk read.
+    const entries = await readRegistry();
+    let entry;
+    try {
+        entry = resolveRegistryEntry(entries, target);
+    }
+    catch (err) {
+        if (err instanceof RegistryNotFoundError) {
+            // Idempotent: missing target is a no-op warning, not an error.
+            // The `availableNames` hint comes from the error itself so users
+            // can see what they might have meant.
+            logger.warn(`Nothing to remove: ${err.message}`);
+            return;
+        }
+        if (err instanceof RegistryAmbiguousTargetError) {
+            // Duplicate aliases are allowed via --allow-duplicate-name (#829);
+            // refuse to guess which one the user meant — surface the full list
+            // and exit non-zero so scripts don't silently pick the wrong repo.
+            cliError(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    // Confirmation gate — same shape as `clean`. Default is a dry-run
+    // that describes what would be deleted; `--force` actually deletes.
+    if (!options?.force) {
+        console.log(`This will delete the Arceus index for: ${entry.name}`);
+        console.log(`   Path:    ${entry.path}`);
+        console.log(`   Storage: ${entry.storagePath}`);
+        console.log('\nRun with --force to confirm deletion.');
+        return;
+    }
+    // Safety guard (#1003 review — @magyargergo): refuse to proceed if
+    // the registry entry's `storagePath` isn't the canonical
+    // `<entry.path>/.arc` subfolder. `~/.arc/registry.json` is
+    // user-writable, so a corrupted or hand-edited entry could point
+    // storagePath at the repo root, an empty string (→ cwd), a parent
+    // dir, or anywhere else; `fs.rm(recursive: true, force: true)` on
+    // any of those would be a runtime disaster. Bail before touching
+    // disk, with an actionable hint for recovering a broken registry.
+    try {
+        assertSafeStoragePath(entry);
+    }
+    catch (err) {
+        if (err instanceof UnsafeStoragePathError) {
+            cliError(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    // Deletion order: fs.rm first, then unregister. If fs.rm fails mid-way,
+    // the registry entry stays so the user can retry. If fs.rm succeeds but
+    // unregister throws (e.g. ENOSPC on registry write), the entry becomes
+    // orphaned — `listRegisteredRepos({ validate: true })` prunes those on
+    // next read, so the failure is self-healing.
+    try {
+        await fs.rm(entry.storagePath, { recursive: true, force: true });
+        await unregisterRepo(entry.path);
+        console.log(`Removed: ${entry.name}`);
+        console.log(`   Path:    ${entry.path}`);
+        console.log(`   Storage: ${entry.storagePath}`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        cliError(`Failed to remove ${entry.name}: ${msg}`, { err });
+        process.exit(1);
+    }
+};

package/dist/cli/serve.d.ts

@@ -0,0 +1,4 @@
+export declare const serveCommand: (options?: {
+    port?: string;
+    host?: string;
+}) => Promise<void>;

package/dist/cli/serve.js

@@ -0,0 +1,55 @@
+import { createServer } from '../server/api.js';
+import { logger, flushLoggerSync } from '../core/logger.js';
+import { cliError } from './cli-message.js';
+// Catch anything that would cause a silent exit. Pino v10's default
+// destination is `sync: false` (SonicBoom buffered) — call
+// `flushLoggerSync()` between the log and `process.exit(1)` so the crash
+// record is not lost to the unflushed buffer. Worker-thread transports
+// (pino-pretty under TTY) handle their own flush on process exit in v10,
+// so no separate `pino.final` integration is needed (the API was removed
+// in v10 because the transport architecture made it unnecessary).
+//
+// We pass the Error itself in `{ err }` so pino's built-in err serializer
+// captures `type`, `message`, and `stack` as structured fields.
+process.on('uncaughtException', (err) => {
+    logger.error({ err }, '[arc serve] Uncaught exception');
+    flushLoggerSync();
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    const err = reason instanceof Error ? reason : new Error(String(reason));
+    logger.error({ err }, '[arc serve] Unhandled rejection');
+    flushLoggerSync();
+    process.exit(1);
+});
+export const serveCommand = async (options) => {
+    const port = Number(options?.port ?? 4747);
+    // Default to 'localhost' so the OS decides whether to bind to 127.0.0.1 or
+    // ::1 based on system configuration, avoiding spurious CORS errors when the
+    // hosted frontend at arc.vercel.app connects to localhost.
+    const host = options?.host ?? 'localhost';
+    try {
+        await createServer(port, host);
+    }
+    catch (err) {
+        if (err.code === 'EADDRINUSE') {
+            cliError(`\nFailed to start Arceus server:\n` +
+                `  ${err.message || err}\n\n` +
+                `  Port ${port} is already in use. Either:\n` +
+                `    1. Stop the other process using port ${port}\n` +
+                `    2. Use a different port: arc serve --port 4748\n`, { code: err.code, port, host });
+        }
+        else {
+            cliError(`\nFailed to start Arceus server:\n  ${err.message || err}\n`, {
+                code: err.code,
+                port,
+                host,
+            });
+        }
+        if (err.stack && process.env.DEBUG) {
+            logger.debug({ stack: err.stack }, 'serve start error stack');
+        }
+        flushLoggerSync();
+        process.exit(1);
+    }
+};

package/dist/cli/setup.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Setup Command
+ *
+ * One-time global MCP configuration writer.
+ * Detects installed AI editors and writes the appropriate MCP config
+ * so the Arceus MCP server is available in all projects.
+ */
+export declare const setupCommand: () => Promise<void>;