opensquid 0.5.395

package/dist/setup/cli/limits.js

@@ -0,0 +1,102 @@
+/**
+ * `opensquid limits` CLI verb group (CLI.8) — thin commander wiring.
+ *
+ * Two verbs, both backed by `RateLimiter` state (AUTO.2):
+ *
+ *   (default)     — per-pack per-trigger budget table (max + used + remaining).
+ *                   Joins pack-declared `rate_limits:` blocks with live bucket
+ *                   rows. Unconfigured triggers contribute no rows (runtime
+ *                   treats them as unlimited; CLI mirrors that).
+ *   reset <pack>  — atomic `DELETE FROM rate_limit_buckets WHERE pack_id = ?`.
+ *                   Confirmation required: `--yes` flag OR interactive y/N.
+ *                   Non-TTY without `--yes` refuses with exit 1.
+ *
+ * Pure handlers live in `./limits_state.ts` (enumerate + read + reset +
+ * render); this file owns commander wiring + libsql client lifecycle.
+ *
+ * Imports from: commander, @libsql/client, ./audit_state.js, ./limits_state.js.
+ * Imported by: src/cli.ts, src/setup/cli/limits.test.ts.
+ */
+import { createClient } from '@libsql/client';
+import { defaultAuditDbPath } from './audit_state.js';
+import { buildLimitRows, defaultPacksDir, enumeratePackRateLimits, readAllBuckets, renderLimitsTable, resetPackBuckets, } from './limits_state.js';
+function defaultOpen(dbPath) {
+    const url = dbPath.startsWith('file:') || dbPath === ':memory:' ? dbPath : `file:${dbPath}`;
+    return createClient({ url });
+}
+function buildDeps(deps) {
+    return {
+        open: deps.openClient ?? defaultOpen,
+        out: deps.stdout ?? ((s) => process.stdout.write(s)),
+        err: deps.stderr ?? ((s) => process.stderr.write(s)),
+        isTty: deps.isTty ?? (() => process.stdout.isTTY === true),
+    };
+}
+async function confirmTty(question, isTty) {
+    if (!isTty())
+        return false;
+    const rl = (await import('node:readline/promises')).createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = (await rl.question(question)).trim().toLowerCase();
+        return answer === 'y' || answer === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}
+async function actDefault(deps, opts) {
+    const decls = await enumeratePackRateLimits(opts.packsDir);
+    const client = deps.open(opts.db);
+    try {
+        const buckets = await readAllBuckets(client);
+        const rows = buildLimitRows(decls, buckets);
+        if (rows.length === 0) {
+            deps.out('(no pack-declared rate limits)\n');
+            return;
+        }
+        deps.out(renderLimitsTable(rows) + '\n');
+    }
+    finally {
+        client.close();
+    }
+}
+async function actReset(deps, pack, opts) {
+    if (!opts.yes && !deps.isTty()) {
+        deps.err(`opensquid limits reset: refusing to reset "${pack}" without --yes in non-interactive context\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (!opts.yes &&
+        !(await confirmTty(`Reset rate-limit usage for "${pack}"? [y/N] `, deps.isTty))) {
+        deps.out('aborted\n');
+        return;
+    }
+    const client = deps.open(opts.db);
+    try {
+        const removed = await resetPackBuckets(client, pack);
+        deps.out(`reset ${String(removed)} bucket row${removed === 1 ? '' : 's'} for "${pack}"\n`);
+    }
+    finally {
+        client.close();
+    }
+}
+/** Register `opensquid limits` on the parent program. */
+export function registerLimits(parent, deps = {}) {
+    const r = buildDeps(deps);
+    const l = parent.command('limits').description('Pack rate-limit state');
+    const db = defaultAuditDbPath();
+    const packsDir = defaultPacksDir();
+    l.option('--db <path>', 'Path to the libsql DB', db)
+        .option('--packs-dir <path>', 'Path to the packs directory', packsDir)
+        .action((opts) => actDefault(r, opts));
+    l.command('reset <pack>')
+        .description('Clear usage window for a pack (admin override)')
+        .option('--db <path>', 'Path to the libsql DB', db)
+        .option('--yes', 'skip confirmation', false)
+        .action((pack, opts) => actReset(r, pack, opts));
+    return l;
+}
+//# sourceMappingURL=limits.js.map

package/dist/setup/cli/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../../src/setup/cli/limits.ts"],"names":[],"mappings":"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"}

package/dist/setup/cli/limits_state.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Limits-CLI persistence helpers (CLI.8) — split out of limits.ts for the
+ * file-size budget.
+ *
+ * Two concerns:
+ *
+ *   1. `enumeratePackRateLimits` — walk a packs directory (default
+ *      `~/.opensquid/packs/`), load each pack's `manifest.yaml` via the
+ *      Manifest schema, and surface the `rate_limits:` block per pack.
+ *      Unconfigured packs (no `rate_limits:`) contribute zero rows — the
+ *      limits CLI surface mirrors the runtime: only declared (pack,
+ *      trigger) pairs have caps, everything else is unlimited.
+ *
+ *   2. `readBuckets` / `resetPackBuckets` — direct libsql access to the
+ *      AUTO.2 `rate_limit_buckets` table (the runtime state owned by
+ *      `RateLimiter`). The CLI deliberately reads rows directly rather
+ *      than instantiating a `RateLimiter` because the limiter API exposes
+ *      `check` / `release` (single-key mutations) — not enumerate. Reset
+ *      uses a single `DELETE FROM ... WHERE pack_id = ?` so post-reset
+ *      `check()` on any (trigger, key) pair starts from a fresh bucket
+ *      (no row → defaults to `max` tokens per the limiter's read path).
+ *
+ * Pack-side data: only the schema-validated `rate_limits` block; the
+ * runtime Pack type strips it (see `src/runtime/types.ts`), so we re-parse
+ * manifest.yaml here rather than hooking the loader. Same precedent as
+ * `triggers_state.enumeratePacks` re-loading via `loadPack`.
+ *
+ * Imports from: node:fs/promises, node:path, @libsql/client,
+ *   ../../packs/schemas/manifest, ../../packs/yaml, ../../runtime/paths.
+ * Imported by: src/setup/cli/limits.ts + src/setup/cli/limits.test.ts.
+ */
+import type { Client } from '@libsql/client';
+import type { RateLimits as RateLimitsType } from '../../packs/schemas/manifest.js';
+import type { TriggerKind } from '../../packs/schemas/skill.js';
+export declare const defaultPacksDir: () => string;
+/** One pack's declared rate-limit block. `rateLimits` is the
+ *  manifest-parsed map (trigger kind → config); empty when the pack
+ *  omits the block (i.e. unlimited across triggers). */
+export interface PackRateLimitDecl {
+    packId: string;
+    rateLimits: RateLimitsType;
+}
+/** Walk packs/ and pull each pack's `rate_limits:` block. Packs without
+ *  a manifest.yaml are skipped (matches `triggers_state` posture). */
+export declare function enumeratePackRateLimits(packsDir: string): Promise<PackRateLimitDecl[]>;
+/** One row from `rate_limit_buckets`. `tokens` is the current refilled
+ *  count; `lastRefillMs` is the last-touch timestamp used for continuous
+ *  refill math. */
+export interface BucketRow {
+    packId: string;
+    triggerKind: TriggerKind;
+    key: string;
+    tokens: number;
+    lastRefillMs: number;
+    concurrentCount: number;
+}
+/** Read ALL buckets across packs. Used by the default `limits` verb to
+ *  enumerate runtime state when joined against pack-declared caps. */
+export declare function readAllBuckets(db: Client): Promise<BucketRow[]>;
+/** Atomic delete of all buckets for one pack. Returns the deleted row
+ *  count so the CLI can confirm action. */
+export declare function resetPackBuckets(db: Client, packId: string): Promise<number>;
+/** Joined per-pack per-trigger row surfaced by the default `limits` verb. */
+export interface LimitRow {
+    pack: string;
+    trigger: TriggerKind;
+    max: number;
+    used: number;
+    remaining: number;
+}
+/** Aggregate buckets by (pack, trigger) — worst-case (lowest tokens) wins
+ *  so the CLI surfaces "what's about to throttle". Trigger-keys other
+ *  than the default `<pack>::<trigger>` (per-skill, per-event) collapse
+ *  into one row per (pack, trigger). */
+export declare function buildLimitRows(decls: readonly PackRateLimitDecl[], buckets: readonly BucketRow[]): LimitRow[];
+export declare function renderLimitsTable(rows: readonly LimitRow[]): string;
+//# sourceMappingURL=limits_state.d.ts.map

package/dist/setup/cli/limits_state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits_state.d.ts","sourceRoot":"","sources":["../../../src/setup/cli/limits_state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AASH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,IAAI,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACpF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEhE,eAAO,MAAM,eAAe,QAAO,MAAyC,CAAC;AAE7E;;wDAEwD;AACxD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,cAAc,CAAC;CAC5B;AAED;sEACsE;AACtE,wBAAsB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAiC5F;AAED;;mBAEmB;AACnB,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,WAAW,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACzB;AAcD;sEACsE;AACtE,wBAAsB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAkBrE;AAED;2CAC2C;AAC3C,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOlF;AAOD,6EAA6E;AAC7E,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,WAAW,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;wCAGwC;AACxC,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,iBAAiB,EAAE,EACnC,OAAO,EAAE,SAAS,SAAS,EAAE,GAC5B,QAAQ,EAAE,CAyBZ;AAOD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,CAcnE"}

package/dist/setup/cli/limits_state.js

@@ -0,0 +1,170 @@
+/**
+ * Limits-CLI persistence helpers (CLI.8) — split out of limits.ts for the
+ * file-size budget.
+ *
+ * Two concerns:
+ *
+ *   1. `enumeratePackRateLimits` — walk a packs directory (default
+ *      `~/.opensquid/packs/`), load each pack's `manifest.yaml` via the
+ *      Manifest schema, and surface the `rate_limits:` block per pack.
+ *      Unconfigured packs (no `rate_limits:`) contribute zero rows — the
+ *      limits CLI surface mirrors the runtime: only declared (pack,
+ *      trigger) pairs have caps, everything else is unlimited.
+ *
+ *   2. `readBuckets` / `resetPackBuckets` — direct libsql access to the
+ *      AUTO.2 `rate_limit_buckets` table (the runtime state owned by
+ *      `RateLimiter`). The CLI deliberately reads rows directly rather
+ *      than instantiating a `RateLimiter` because the limiter API exposes
+ *      `check` / `release` (single-key mutations) — not enumerate. Reset
+ *      uses a single `DELETE FROM ... WHERE pack_id = ?` so post-reset
+ *      `check()` on any (trigger, key) pair starts from a fresh bucket
+ *      (no row → defaults to `max` tokens per the limiter's read path).
+ *
+ * Pack-side data: only the schema-validated `rate_limits` block; the
+ * runtime Pack type strips it (see `src/runtime/types.ts`), so we re-parse
+ * manifest.yaml here rather than hooking the loader. Same precedent as
+ * `triggers_state.enumeratePacks` re-loading via `loadPack`.
+ *
+ * Imports from: node:fs/promises, node:path, @libsql/client,
+ *   ../../packs/schemas/manifest, ../../packs/yaml, ../../runtime/paths.
+ * Imported by: src/setup/cli/limits.ts + src/setup/cli/limits.test.ts.
+ */
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Manifest } from '../../packs/schemas/manifest.js';
+import { parseYamlFile } from '../../packs/yaml.js';
+import { OPENSQUID_HOME } from '../../runtime/paths.js';
+export const defaultPacksDir = () => join(OPENSQUID_HOME(), 'packs');
+/** Walk packs/ and pull each pack's `rate_limits:` block. Packs without
+ *  a manifest.yaml are skipped (matches `triggers_state` posture). */
+export async function enumeratePackRateLimits(packsDir) {
+    let entries;
+    try {
+        entries = await readdir(packsDir);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return [];
+        throw e;
+    }
+    entries.sort();
+    const out = [];
+    for (const e of entries) {
+        if (e.startsWith('.'))
+            continue;
+        const dir = join(packsDir, e);
+        let st;
+        try {
+            st = await stat(dir);
+        }
+        catch {
+            continue;
+        }
+        if (!st.isDirectory())
+            continue;
+        const manifestPath = join(dir, 'manifest.yaml');
+        let parsed;
+        try {
+            parsed = await parseYamlFile(manifestPath, Manifest);
+        }
+        catch {
+            continue;
+        }
+        out.push({
+            packId: parsed.data.name,
+            rateLimits: parsed.data.rate_limits ?? {},
+        });
+    }
+    return out;
+}
+const CREATE_TABLE_SQL = `
+  CREATE TABLE IF NOT EXISTS rate_limit_buckets (
+    pack_id TEXT NOT NULL,
+    trigger_kind TEXT NOT NULL,
+    key TEXT NOT NULL,
+    tokens REAL NOT NULL,
+    last_refill_ms INTEGER NOT NULL,
+    concurrent_count INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (pack_id, trigger_kind, key)
+  );
+`;
+/** Read ALL buckets across packs. Used by the default `limits` verb to
+ *  enumerate runtime state when joined against pack-declared caps. */
+export async function readAllBuckets(db) {
+    await db.execute(CREATE_TABLE_SQL);
+    const rs = await db.execute(`SELECT pack_id, trigger_kind, key, tokens, last_refill_ms, concurrent_count
+     FROM rate_limit_buckets
+     ORDER BY pack_id ASC, trigger_kind ASC, key ASC`);
+    return rs.rows.map((r) => {
+        const row = r;
+        return {
+            packId: String(row.pack_id),
+            triggerKind: String(row.trigger_kind),
+            key: String(row.key),
+            tokens: Number(row.tokens),
+            lastRefillMs: Number(row.last_refill_ms),
+            concurrentCount: Number(row.concurrent_count),
+        };
+    });
+}
+/** Atomic delete of all buckets for one pack. Returns the deleted row
+ *  count so the CLI can confirm action. */
+export async function resetPackBuckets(db, packId) {
+    await db.execute(CREATE_TABLE_SQL);
+    const rs = await db.execute({
+        sql: `DELETE FROM rate_limit_buckets WHERE pack_id = ?`,
+        args: [packId],
+    });
+    return Number(rs.rowsAffected);
+}
+/** Aggregate buckets by (pack, trigger) — worst-case (lowest tokens) wins
+ *  so the CLI surfaces "what's about to throttle". Trigger-keys other
+ *  than the default `<pack>::<trigger>` (per-skill, per-event) collapse
+ *  into one row per (pack, trigger). */
+export function buildLimitRows(decls, buckets) {
+    const bucketByKey = new Map();
+    for (const b of buckets) {
+        const k = `${b.packId}::${b.triggerKind}`;
+        const existing = bucketByKey.get(k);
+        if (existing === undefined || b.tokens < existing.tokens)
+            bucketByKey.set(k, b);
+    }
+    const rows = [];
+    for (const decl of decls) {
+        for (const [trigger, cfg] of Object.entries(decl.rateLimits)) {
+            if (cfg === undefined)
+                continue;
+            const bucket = bucketByKey.get(`${decl.packId}::${trigger}`);
+            const tokens = bucket?.tokens ?? cfg.max;
+            const remaining = Math.max(0, Math.floor(tokens));
+            const used = Math.max(0, cfg.max - remaining);
+            rows.push({
+                pack: decl.packId,
+                trigger: trigger,
+                max: cfg.max,
+                used,
+                remaining,
+            });
+        }
+    }
+    return rows;
+}
+function pad(s, w) {
+    if (s.length >= w)
+        return s.slice(0, w - 1) + ' ';
+    return s + ' '.repeat(w - s.length);
+}
+export function renderLimitsTable(rows) {
+    const lines = [
+        pad('PACK', 24) + pad('TRIGGER', 18) + pad('MAX', 8) + pad('USED', 8) + pad('REMAINING', 10),
+    ];
+    for (const r of rows) {
+        lines.push(pad(r.pack, 24) +
+            pad(r.trigger, 18) +
+            pad(String(r.max), 8) +
+            pad(String(r.used), 8) +
+            pad(String(r.remaining), 10));
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=limits_state.js.map

package/dist/setup/cli/limits_state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits_state.js","sourceRoot":"","sources":["../../../src/setup/cli/limits_state.ts"],"names":[],"mappings":"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"}

package/dist/setup/cli/mcp.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `opensquid setup wizard mcp` — register opensquid MCP servers at the
+ * USER level (`~/.claude.json` mcpServers) so the central brain is
+ * reachable from EVERY Claude Code project automatically, without per-
+ * project `.mcp.json` setup.
+ *
+ * Companion to G.1's `setup wizard hooks` — same shape, same `@opensquid`
+ * marker contract, same `.bak` semantics. See `mcp-writer.ts` header for
+ * the file-level details.
+ *
+ * Flow:
+ *   1. Resolve `opensquidRepoRoot` (cwd-walk for the opensquid package.json,
+ *      or explicit `--opensquid-root <path>` override).
+ *   2. Dry-run: project the change, print counts, exit. No mutation.
+ *   3. Commit: write `~/.claude.json` + `.bak`, print counts.
+ *   4. Project cleanup advisory: if `<cwd>/.mcp.json` exists with opensquid
+ *      entries, print them with offer-to-remove guidance (we do NOT auto-
+ *      remove in this task; doing so is a follow-up). For non-TTY, default
+ *      to leaving them alone with a stderr note. Suppress entirely with
+ *      `--no-detect-project-cleanup`.
+ *
+ * Flags:
+ *   --dry-run                          Preview without writing.
+ *   --opensquid-root <path>            Override auto-detected repo root.
+ *   --no-detect-project-cleanup        Skip the project `.mcp.json` advisory.
+ *
+ * Imports from: commander, node:fs, node:os, node:path, ../wizard/mcp-writer.
+ * Imported by: src/cli.ts (via `registerSetupWizardMcp`).
+ */
+import { type McpWriteResult } from '../wizard/mcp-writer.js';
+import type { Command } from 'commander';
+export interface McpCliFlags {
+    dryRun?: boolean;
+    opensquidRoot?: string;
+    detectProjectCleanup?: boolean;
+    /** Comma-list of host ids or `all`; default (undefined) = claude-code only. */
+    hosts?: string;
+}
+export interface McpCliDeps {
+    writer?: (path: string, root: string) => Promise<McpWriteResult>;
+    reader?: (path: string) => Promise<unknown>;
+    cwd?: () => string;
+    home?: () => string;
+    stdout?: (s: string) => void;
+    stderr?: (s: string) => void;
+    isTty?: () => boolean;
+    /** Does this path exist? (used to skip a host whose app dir is absent). */
+    dirExists?: (path: string) => Promise<boolean>;
+    /** Platform for host-path resolution (injected for deterministic tests). */
+    platform?: () => NodeJS.Platform;
+}
+/**
+ * Walk up from `start` looking for a `package.json` whose `name` field
+ * starts with `opensquid` (covers `opensquid` proper + future scoped
+ * packages). Returns the directory containing that file, or null if not
+ * found before reaching `/`.
+ */
+export declare function detectOpensquidRoot(start: string): Promise<string | null>;
+/** Report opensquid entries in `<cwd>/.mcp.json` (if any) — read-only. */
+export declare function detectProjectMcpCleanup(cwd: string): Promise<{
+    path: string;
+    opensquidKeys: string[];
+} | null>;
+/** Pulled out of the commander action so tests can drive it directly. */
+export declare function runMcpWizard(flags: McpCliFlags, deps?: McpCliDeps): Promise<void>;
+/**
+ * Register the `wizard mcp` subcommand under the supplied `wizard` group.
+ * Caller is responsible for creating the `wizard` group (G.1 does it via
+ * `registerSetupWizard`); G.8 reuses that node by calling `.command('mcp')`
+ * on the same `wizard` instance.
+ */
+export declare function registerSetupWizardMcp(wizard: Command, deps?: McpCliDeps): Command;
+//# sourceMappingURL=mcp.d.ts.map

package/dist/setup/cli/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/setup/cli/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAQH,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,yBAAyB,CAAC;AASjC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACjE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC;IACtB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC,QAAQ,CAAC;CAClC;AAiCD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAe/E;AAMD,0EAA0E;AAC1E,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAAC,CAa3D;AAED,yEAAyE;AACzE,wBAAsB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA+E3F;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAiBtF"}

package/dist/setup/cli/mcp.js

@@ -0,0 +1,175 @@
+/**
+ * `opensquid setup wizard mcp` — register opensquid MCP servers at the
+ * USER level (`~/.claude.json` mcpServers) so the central brain is
+ * reachable from EVERY Claude Code project automatically, without per-
+ * project `.mcp.json` setup.
+ *
+ * Companion to G.1's `setup wizard hooks` — same shape, same `@opensquid`
+ * marker contract, same `.bak` semantics. See `mcp-writer.ts` header for
+ * the file-level details.
+ *
+ * Flow:
+ *   1. Resolve `opensquidRepoRoot` (cwd-walk for the opensquid package.json,
+ *      or explicit `--opensquid-root <path>` override).
+ *   2. Dry-run: project the change, print counts, exit. No mutation.
+ *   3. Commit: write `~/.claude.json` + `.bak`, print counts.
+ *   4. Project cleanup advisory: if `<cwd>/.mcp.json` exists with opensquid
+ *      entries, print them with offer-to-remove guidance (we do NOT auto-
+ *      remove in this task; doing so is a follow-up). For non-TTY, default
+ *      to leaving them alone with a stderr note. Suppress entirely with
+ *      `--no-detect-project-cleanup`.
+ *
+ * Flags:
+ *   --dry-run                          Preview without writing.
+ *   --opensquid-root <path>            Override auto-detected repo root.
+ *   --no-detect-project-cleanup        Skip the project `.mcp.json` advisory.
+ *
+ * Imports from: commander, node:fs, node:os, node:path, ../wizard/mcp-writer.
+ * Imported by: src/cli.ts (via `registerSetupWizardMcp`).
+ */
+import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { stat } from 'node:fs/promises';
+import { buildDesiredEntries, projectOpensquidMcp, readClaudeUserConfig, writeOpensquidMcp, } from '../wizard/mcp-writer.js';
+import { ALL_HOSTS, parseHosts, resolveHost, } from '../wizard/mcp-hosts.js';
+function buildDeps(deps) {
+    return {
+        writer: deps.writer ?? writeOpensquidMcp,
+        reader: deps.reader ?? readClaudeUserConfig,
+        cwd: deps.cwd ?? (() => process.cwd()),
+        home: deps.home ?? homedir,
+        out: deps.stdout ?? ((s) => void process.stdout.write(s)),
+        err: deps.stderr ?? ((s) => void process.stderr.write(s)),
+        isTty: deps.isTty ?? (() => process.stdout.isTTY === true),
+        dirExists: deps.dirExists ??
+            ((p) => stat(p)
+                .then(() => true)
+                .catch(() => false)),
+        platform: deps.platform ?? (() => process.platform),
+    };
+}
+/**
+ * Walk up from `start` looking for a `package.json` whose `name` field
+ * starts with `opensquid` (covers `opensquid` proper + future scoped
+ * packages). Returns the directory containing that file, or null if not
+ * found before reaching `/`.
+ */
+export async function detectOpensquidRoot(start) {
+    let cur = resolve(start);
+    for (;;) {
+        const pkgPath = join(cur, 'package.json');
+        try {
+            const raw = await fs.readFile(pkgPath, 'utf-8');
+            const pkg = JSON.parse(raw);
+            if (typeof pkg.name === 'string' && pkg.name.startsWith('opensquid'))
+                return cur;
+        }
+        catch {
+            /* keep walking */
+        }
+        const parent = dirname(cur);
+        if (parent === cur)
+            return null;
+        cur = parent;
+    }
+}
+/** Report opensquid entries in `<cwd>/.mcp.json` (if any) — read-only. */
+export async function detectProjectMcpCleanup(cwd) {
+    const path = join(cwd, '.mcp.json');
+    try {
+        const raw = await fs.readFile(path, 'utf-8');
+        const cfg = JSON.parse(raw);
+        const keys = Object.keys(cfg.mcpServers ?? {}).filter((k) => k === 'opensquid' || k === 'opensquid-chat');
+        if (keys.length === 0)
+            return null;
+        return { path, opensquidKeys: keys };
+    }
+    catch {
+        return null;
+    }
+}
+/** Pulled out of the commander action so tests can drive it directly. */
+export async function runMcpWizard(flags, deps = {}) {
+    const r = buildDeps(deps);
+    const root = flags.opensquidRoot ?? (await detectOpensquidRoot(r.cwd()));
+    if (root === null || root === undefined || root === '') {
+        r.err('opensquid setup wizard mcp: could not auto-detect opensquid repo root from cwd; pass --opensquid-root <path>\n');
+        process.exitCode = 1;
+        return;
+    }
+    // D1: default = claude-code only; opt into others via --hosts.
+    const hostIds = parseHosts(flags.hosts, r.err);
+    if (hostIds.length === 0) {
+        r.err(`opensquid setup wizard mcp: no valid hosts selected (valid: ${ALL_HOSTS.join(', ')})\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const env = { platform: r.platform(), home: r.home(), env: process.env };
+    // D2: skip a non-Code host whose app dir is absent (don't fabricate its tree).
+    // Claude Code's dir is the home dir — always present.
+    const hostPresent = async (id, configPath) => id === 'claude-code' || (await r.dirExists(dirname(configPath)));
+    if (flags.dryRun === true) {
+        r.out('opensquid setup wizard mcp — DRY RUN (no files written)\n');
+        for (const id of hostIds) {
+            const t = resolveHost(id, env);
+            if (!(await hostPresent(id, t.configPath))) {
+                r.out(`  ${t.label}: not detected (${dirname(t.configPath)}) — would skip\n`);
+                continue;
+            }
+            const input = (await r.reader(t.configPath));
+            const { added, replaced, preserved } = projectOpensquidMcp(input, root);
+            r.out(`  ${t.label} (${t.configPath}): would add [${added.join(', ')}], replace [${replaced.join(', ')}], preserve ${String(preserved)} unrelated mcpServer(s)\n`);
+        }
+        const desired = buildDesiredEntries(root);
+        r.out(`  opensquid       → node ${desired.opensquid.args?.[0] ?? ''}\n`);
+        r.out(`  opensquid-chat  → node ${desired['opensquid-chat'].args?.[0] ?? ''}\n`);
+    }
+    else {
+        r.out('opensquid setup wizard mcp — writing entries\n');
+        for (const id of hostIds) {
+            const t = resolveHost(id, env);
+            if (!(await hostPresent(id, t.configPath))) {
+                r.out(`  ${t.label}: not detected (${dirname(t.configPath)}) — skipped\n`);
+                continue;
+            }
+            const result = await r.writer(t.configPath, root);
+            r.out(`  ${t.label} (${t.configPath}): added [${result.added.join(', ')}], replaced [${result.replaced.join(', ')}], preserved ${String(result.preserved)} unrelated mcpServer(s) (backup: ${result.backupPath})\n`);
+            if (t.needsRestart)
+                r.out(`  ↳ restart ${t.label} to load the servers.\n`);
+        }
+    }
+    if (flags.detectProjectCleanup !== false) {
+        const advisory = await detectProjectMcpCleanup(r.cwd());
+        if (advisory !== null) {
+            r.out(`\nproject-level .mcp.json contains opensquid entries: ${advisory.path}\n`);
+            r.out(`  keys: ${advisory.opensquidKeys.join(', ')}\n`);
+            if (r.isTty()) {
+                r.out('  ↳ user-level registration is now authoritative; consider removing these to avoid double-loading.\n');
+            }
+            else {
+                r.err('opensquid setup wizard mcp: non-TTY — leaving project-level .mcp.json untouched; re-run interactively to clean up.\n');
+            }
+        }
+    }
+}
+/**
+ * Register the `wizard mcp` subcommand under the supplied `wizard` group.
+ * Caller is responsible for creating the `wizard` group (G.1 does it via
+ * `registerSetupWizard`); G.8 reuses that node by calling `.command('mcp')`
+ * on the same `wizard` instance.
+ */
+export function registerSetupWizardMcp(wizard, deps = {}) {
+    wizard
+        .command('mcp')
+        .description('Register opensquid MCP servers into Claude-ecosystem hosts (default: Claude Code)')
+        .option('--dry-run', 'preview the projected changes without writing any file', false)
+        .option('--opensquid-root <path>', 'override the auto-detected opensquid repo root')
+        .option('--no-detect-project-cleanup', 'skip the project-level .mcp.json cleanup advisory')
+        .option('--hosts <list>', 'comma-list of hosts (claude-code, claude-desktop, cursor) or "all"; default: claude-code')
+        .action(async (flags) => {
+        await runMcpWizard(flags, deps);
+    });
+    return wizard;
+}
+//# sourceMappingURL=mcp.js.map

package/dist/setup/cli/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../../src/setup/cli/mcp.ts"],"names":[],"mappings":"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"}