@solidnumber/cli 1.9.30 → 1.10.0

package/dist/lib/list-envelope.d.ts

@@ -0,0 +1,67 @@
+/**
+ * List-envelope normalization (Sprint 1 T1.4).
+ *
+ * Backend list endpoints return an inconsistent bag of keys:
+ *   { pages: [...], total: N }
+ *   { results: [...] }
+ *   { logs: [...], has_more: true }
+ *   { agents: [...] }
+ *   { api_keys: [...] }
+ *   { items: [...] }
+ *   ...
+ *
+ * That's fine for humans but forces agents to write `d.pages || d.items
+ * || d.results || d.logs || ...` fallbacks before they can loop. This
+ * module adds a stable `.items` alias + `total / page / has_more`
+ * siblings on every response whose body looks like a list envelope.
+ * Original keys are preserved so existing callers never break.
+ *
+ * Pure — no HTTP, no axios. Wired into the response interceptor in
+ * api-client.ts; unit-tested with synthetic inputs.
+ *
+ * Opt-out: `SOLID_LEGACY_LIST_SHAPES=1` disables normalization for one
+ * minor release while consumers migrate (per T1.7 two-step rollout).
+ */
+/**
+ * Keys backend responses use to expose a list of rows, in preference
+ * order. The FIRST key found on the response body whose value is an
+ * array is promoted to `.items`. Order matters: when multiple keys
+ * coexist (rare), the earlier one wins.
+ */
+export declare const KNOWN_LIST_KEYS: readonly string[];
+export interface NormalizedEnvelope {
+    items: unknown[];
+    total: number | null;
+    page: number | string | null;
+    has_more: boolean | null;
+    /** Which source key the alias came from ("items" when already canonical). */
+    _source_key: string | null;
+}
+/** Truthy values for the SOLID_LEGACY_LIST_SHAPES opt-out. */
+export declare function legacyListShapesEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Detect which known list key (if any) holds the array payload.
+ * Returns null when the body is not shaped like a list response.
+ * Pure.
+ */
+export declare function detectListKey(body: unknown, knownKeys?: readonly string[]): string | null;
+/**
+ * Produce a canonical {items, total, page, has_more} view of a list
+ * response. Returns null when the body isn't a list envelope, so callers
+ * can short-circuit without mutating.
+ */
+export declare function normalizeListEnvelope(body: unknown): NormalizedEnvelope | null;
+/**
+ * Apply the normalization in-place on a response body, adding the
+ * aliased keys without removing existing ones. Returns the body back
+ * for easy chaining in the axios response interceptor.
+ *
+ * No-op when:
+ *  - body is not a list envelope
+ *  - body already has `items` (then we just ensure `total` is present)
+ *  - SOLID_LEGACY_LIST_SHAPES is truthy
+ *
+ * Pure wrt env: caller can pass its own env map for tests.
+ */
+export declare function applyListEnvelope<T>(body: T, env?: NodeJS.ProcessEnv): T;
+//# sourceMappingURL=list-envelope.d.ts.map

package/dist/lib/list-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-envelope.d.ts","sourceRoot":"","sources":["../../src/lib/list-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EA4B5C,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,8DAA8D;AAC9D,wBAAgB,uBAAuB,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAGxE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,OAAO,EACb,SAAS,GAAE,SAAS,MAAM,EAAoB,GAC7C,MAAM,GAAG,IAAI,CAOf;AAsBD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,kBAAkB,GAAG,IAAI,CAuB9E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,IAAI,EAAE,CAAC,EACP,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GACtB,CAAC,CAoBH"}

package/dist/lib/list-envelope.js

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * List-envelope normalization (Sprint 1 T1.4).
+ *
+ * Backend list endpoints return an inconsistent bag of keys:
+ *   { pages: [...], total: N }
+ *   { results: [...] }
+ *   { logs: [...], has_more: true }
+ *   { agents: [...] }
+ *   { api_keys: [...] }
+ *   { items: [...] }
+ *   ...
+ *
+ * That's fine for humans but forces agents to write `d.pages || d.items
+ * || d.results || d.logs || ...` fallbacks before they can loop. This
+ * module adds a stable `.items` alias + `total / page / has_more`
+ * siblings on every response whose body looks like a list envelope.
+ * Original keys are preserved so existing callers never break.
+ *
+ * Pure — no HTTP, no axios. Wired into the response interceptor in
+ * api-client.ts; unit-tested with synthetic inputs.
+ *
+ * Opt-out: `SOLID_LEGACY_LIST_SHAPES=1` disables normalization for one
+ * minor release while consumers migrate (per T1.7 two-step rollout).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWN_LIST_KEYS = void 0;
+exports.legacyListShapesEnabled = legacyListShapesEnabled;
+exports.detectListKey = detectListKey;
+exports.normalizeListEnvelope = normalizeListEnvelope;
+exports.applyListEnvelope = applyListEnvelope;
+/**
+ * Keys backend responses use to expose a list of rows, in preference
+ * order. The FIRST key found on the response body whose value is an
+ * array is promoted to `.items`. Order matters: when multiple keys
+ * coexist (rare), the earlier one wins.
+ */
+exports.KNOWN_LIST_KEYS = [
+    // Already canonical — nothing to alias.
+    'items',
+    // CMS / CRM / commerce
+    'pages',
+    'results',
+    'leads',
+    'agents',
+    'templates',
+    'companies',
+    'sites',
+    'api_keys',
+    'logs',
+    'rows',
+    'records',
+    'entries',
+    'products',
+    'services',
+    'contacts',
+    'customers',
+    'orders',
+    'invoices',
+    'transactions',
+    'webhooks',
+    'chains',
+    'flows',
+    'modules',
+    'domains',
+];
+/** Truthy values for the SOLID_LEGACY_LIST_SHAPES opt-out. */
+function legacyListShapesEnabled(env) {
+    const v = (env ?? process.env).SOLID_LEGACY_LIST_SHAPES;
+    return typeof v === 'string' && /^(1|true|yes|on)$/i.test(v);
+}
+/**
+ * Detect which known list key (if any) holds the array payload.
+ * Returns null when the body is not shaped like a list response.
+ * Pure.
+ */
+function detectListKey(body, knownKeys = exports.KNOWN_LIST_KEYS) {
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        return null;
+    const record = body;
+    for (const k of knownKeys) {
+        if (Array.isArray(record[k]))
+            return k;
+    }
+    return null;
+}
+function safeNumber(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    if (typeof v === 'string' && v.trim() !== '' && !Number.isNaN(Number(v))) {
+        return Number(v);
+    }
+    return null;
+}
+function safePage(v) {
+    if (v == null)
+        return null;
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    if (typeof v === 'string' && v.trim() !== '')
+        return v;
+    return null;
+}
+function safeBool(v) {
+    if (typeof v === 'boolean')
+        return v;
+    return null;
+}
+/**
+ * Produce a canonical {items, total, page, has_more} view of a list
+ * response. Returns null when the body isn't a list envelope, so callers
+ * can short-circuit without mutating.
+ */
+function normalizeListEnvelope(body) {
+    const key = detectListKey(body);
+    if (!key)
+        return null;
+    const record = body;
+    const items = record[key] ?? [];
+    const total = safeNumber(record.total) ??
+        safeNumber(record.count) ??
+        items.length;
+    const page = safePage(record.page) ??
+        safePage(record.cursor) ??
+        safePage(record.next_cursor) ??
+        null;
+    const has_more = safeBool(record.has_more) ?? safeBool(record.hasMore) ?? null;
+    return {
+        items,
+        total,
+        page,
+        has_more,
+        _source_key: key,
+    };
+}
+/**
+ * Apply the normalization in-place on a response body, adding the
+ * aliased keys without removing existing ones. Returns the body back
+ * for easy chaining in the axios response interceptor.
+ *
+ * No-op when:
+ *  - body is not a list envelope
+ *  - body already has `items` (then we just ensure `total` is present)
+ *  - SOLID_LEGACY_LIST_SHAPES is truthy
+ *
+ * Pure wrt env: caller can pass its own env map for tests.
+ */
+function applyListEnvelope(body, env) {
+    if (legacyListShapesEnabled(env))
+        return body;
+    const normalized = normalizeListEnvelope(body);
+    if (!normalized)
+        return body;
+    const record = body;
+    // Only fill in what's missing; never clobber a caller-supplied field.
+    if (!('items' in record) || record.items === undefined) {
+        record.items = normalized.items;
+    }
+    if (!('total' in record) || record.total === undefined || record.total === null) {
+        record.total = normalized.total;
+    }
+    if (!('page' in record) || record.page === undefined) {
+        record.page = normalized.page;
+    }
+    if (!('has_more' in record) || record.has_more === undefined) {
+        record.has_more = normalized.has_more;
+    }
+    return body;
+}
+//# sourceMappingURL=list-envelope.js.map

package/dist/lib/list-envelope.js.map

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

package/dist/lib/mcp-client-config.d.ts

@@ -0,0 +1,57 @@
+export type McpClient = 'claude' | 'cursor' | 'windsurf';
+export declare const SUPPORTED_CLIENTS: McpClient[];
+/** Returns true if the string is a known supported client. */
+export declare function isSupportedClient(value: string | undefined | null): value is McpClient;
+export interface ServerEntry {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+export interface McpConfigFile {
+    mcpServers?: Record<string, ServerEntry>;
+    [k: string]: unknown;
+}
+/**
+ * Per-OS default path for each supported client. Returns the path
+ * relative to `homeDir` so callers can pass their own for testing.
+ */
+export declare function configPathForClient(client: McpClient, opts?: {
+    platform?: NodeJS.Platform;
+    homeDir?: string;
+}): string;
+export interface BuildEntryInput {
+    /** API key or token the MCP server will use to call the backend. */
+    apiKey?: string;
+    /** Base URL for the backend. Defaults to api.solidnumber.com. */
+    apiUrl?: string;
+    /** Npm package to invoke via npx. Defaults to @solidnumber/mcp. */
+    packageName?: string;
+    /** Optional extra env vars (merged in). */
+    extraEnv?: Record<string, string>;
+    /** Company-id pin (adds X-Company-Id via SOLID_COMPANY_ID env). */
+    companyId?: number | string;
+}
+/** Default package that ships the stdio MCP server. */
+export declare const DEFAULT_MCP_PACKAGE = "@solidnumber/mcp";
+/**
+ * Build the `mcpServers.solid` entry. Pure — no I/O, no env reads.
+ */
+export declare function buildServerEntry(input?: BuildEntryInput): ServerEntry;
+/**
+ * Merge a new `solid` server entry into an existing config file.
+ * Preserves any other mcpServers keys and any top-level keys we don't
+ * recognize. Returns a NEW object — input is not mutated.
+ */
+export declare function mergeIntoConfig(existing: McpConfigFile | null | undefined, entry: ServerEntry, serverKey?: string): McpConfigFile;
+/**
+ * Remove the `solid` entry from a config, preserving other keys.
+ * Returns the NEW config (unmutated input). When only `solid` existed
+ * in mcpServers, keeps an empty `mcpServers: {}` to be explicit.
+ */
+export declare function removeFromConfig(existing: McpConfigFile | null | undefined, serverKey?: string): McpConfigFile;
+/**
+ * Pretty-print a config with stable key order + 2-space indent. Writes
+ * this string is the caller's responsibility.
+ */
+export declare function serializeConfig(cfg: McpConfigFile): string;
+//# sourceMappingURL=mcp-client-config.d.ts.map

package/dist/lib/mcp-client-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client-config.d.ts","sourceRoot":"","sources":["../../src/lib/mcp-client-config.ts"],"names":[],"mappings":"AAwBA,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEzD,eAAO,MAAM,iBAAiB,EAAE,SAAS,EAAqC,CAAC;AAE/E,8DAA8D;AAC9D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,KAAK,IAAI,SAAS,CAEtF;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAEzC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1D,MAAM,CAiCR;AAED,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AAED,uDAAuD;AACvD,eAAO,MAAM,mBAAmB,qBAAqB,CAAC;AAEtD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,GAAE,eAAoB,GAAG,WAAW,CAkBzE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,EAC1C,KAAK,EAAE,WAAW,EAClB,SAAS,GAAE,MAAgB,GAC1B,aAAa,CAMf;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,EAC1C,SAAS,GAAE,MAAgB,GAC1B,aAAa,CAOf;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAE1D"}

package/dist/lib/mcp-client-config.js

@@ -0,0 +1,166 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MCP_PACKAGE = exports.SUPPORTED_CLIENTS = void 0;
+exports.isSupportedClient = isSupportedClient;
+exports.configPathForClient = configPathForClient;
+exports.buildServerEntry = buildServerEntry;
+exports.mergeIntoConfig = mergeIntoConfig;
+exports.removeFromConfig = removeFromConfig;
+exports.serializeConfig = serializeConfig;
+/**
+ * MCP client config helpers (Sprint 1 T1.5).
+ *
+ * Write/update the client-side JSON that tells Claude Desktop / Cursor /
+ * Windsurf how to launch the Solid# MCP server. All pure — no fs here,
+ * no network. Callers in src/commands/mcp.ts handle I/O.
+ *
+ * Supported client shapes (as of 2026-04):
+ *
+ *   Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
+ *     {
+ *       "mcpServers": {
+ *         "solid": { "command": "npx", "args": ["@solidnumber/mcp"],
+ *                     "env": { "SOLID_API_KEY": "sk_..." } }
+ *       }
+ *     }
+ *
+ *   Cursor (~/.cursor/mcp.json): same shape as Claude Desktop
+ *
+ *   Windsurf (~/.codeium/windsurf/mcp_config.json): same shape
+ */
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+exports.SUPPORTED_CLIENTS = ['claude', 'cursor', 'windsurf'];
+/** Returns true if the string is a known supported client. */
+function isSupportedClient(value) {
+    return !!value && exports.SUPPORTED_CLIENTS.includes(value);
+}
+/**
+ * Per-OS default path for each supported client. Returns the path
+ * relative to `homeDir` so callers can pass their own for testing.
+ */
+function configPathForClient(client, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const home = opts.homeDir ?? os.homedir();
+    switch (client) {
+        case 'claude':
+            if (platform === 'darwin') {
+                return path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+            }
+            if (platform === 'win32') {
+                // %APPDATA% → fall back to ~/AppData/Roaming when not set
+                const appdata = opts.platform === undefined ? process.env.APPDATA : undefined;
+                const base = appdata ?? path.join(home, 'AppData', 'Roaming');
+                return path.join(base, 'Claude', 'claude_desktop_config.json');
+            }
+            // Linux — Claude Desktop isn't officially supported there but keep
+            // a sane default so tests have something to assert.
+            return path.join(home, '.config', 'Claude', 'claude_desktop_config.json');
+        case 'cursor':
+            return path.join(home, '.cursor', 'mcp.json');
+        case 'windsurf':
+            if (platform === 'darwin' || platform === 'linux') {
+                return path.join(home, '.codeium', 'windsurf', 'mcp_config.json');
+            }
+            if (platform === 'win32') {
+                const appdata = opts.platform === undefined ? process.env.APPDATA : undefined;
+                const base = appdata ?? path.join(home, 'AppData', 'Roaming');
+                return path.join(base, 'Codeium', 'Windsurf', 'mcp_config.json');
+            }
+            return path.join(home, '.codeium', 'windsurf', 'mcp_config.json');
+    }
+}
+/** Default package that ships the stdio MCP server. */
+exports.DEFAULT_MCP_PACKAGE = '@solidnumber/mcp';
+/**
+ * Build the `mcpServers.solid` entry. Pure — no I/O, no env reads.
+ */
+function buildServerEntry(input = {}) {
+    const env = {};
+    if (input.apiKey)
+        env.SOLID_API_KEY = input.apiKey;
+    if (input.apiUrl)
+        env.SOLID_API_URL = input.apiUrl;
+    if (input.companyId !== undefined && input.companyId !== null && input.companyId !== '') {
+        env.SOLID_COMPANY_ID = String(input.companyId);
+    }
+    if (input.extraEnv) {
+        for (const [k, v] of Object.entries(input.extraEnv)) {
+            if (typeof v === 'string' && v.length > 0)
+                env[k] = v;
+        }
+    }
+    const entry = {
+        command: 'npx',
+        args: ['-y', input.packageName ?? exports.DEFAULT_MCP_PACKAGE],
+    };
+    if (Object.keys(env).length > 0)
+        entry.env = env;
+    return entry;
+}
+/**
+ * Merge a new `solid` server entry into an existing config file.
+ * Preserves any other mcpServers keys and any top-level keys we don't
+ * recognize. Returns a NEW object — input is not mutated.
+ */
+function mergeIntoConfig(existing, entry, serverKey = 'solid') {
+    const base = existing && typeof existing === 'object' ? { ...existing } : {};
+    const servers = { ...(base.mcpServers ?? {}) };
+    servers[serverKey] = entry;
+    base.mcpServers = servers;
+    return base;
+}
+/**
+ * Remove the `solid` entry from a config, preserving other keys.
+ * Returns the NEW config (unmutated input). When only `solid` existed
+ * in mcpServers, keeps an empty `mcpServers: {}` to be explicit.
+ */
+function removeFromConfig(existing, serverKey = 'solid') {
+    const base = existing && typeof existing === 'object' ? { ...existing } : {};
+    if (base.mcpServers && typeof base.mcpServers === 'object') {
+        const { [serverKey]: _, ...rest } = base.mcpServers;
+        base.mcpServers = rest;
+    }
+    return base;
+}
+/**
+ * Pretty-print a config with stable key order + 2-space indent. Writes
+ * this string is the caller's responsibility.
+ */
+function serializeConfig(cfg) {
+    return JSON.stringify(cfg, null, 2) + '\n';
+}
+//# sourceMappingURL=mcp-client-config.js.map

package/dist/lib/mcp-client-config.js.map

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

package/dist/lib/program-registry.d.ts

@@ -0,0 +1,19 @@
+/**
+ * program-registry — lazy handle on the root Commander program so any
+ * command module can introspect the full verb tree without creating an
+ * import cycle with index.ts.
+ *
+ * Sprint 1 T1.3: `solid schema verbs --json` needs to walk every
+ * subcommand. Without this registry, schema.ts would have to import
+ * program from index.ts, which already imports schemaCommand from
+ * schema.ts — cycle.
+ *
+ * Pure module state: one writer (index.ts) + many readers (schema,
+ * doctor, etc.). No async, no I/O.
+ */
+import type { Command } from 'commander';
+export declare function setProgram(p: Command): void;
+export declare function getProgram(): Command | null;
+/** Reset for tests. */
+export declare function resetProgramForTest(): void;
+//# sourceMappingURL=program-registry.d.ts.map

package/dist/lib/program-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program-registry.d.ts","sourceRoot":"","sources":["../../src/lib/program-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAE3C;AAED,wBAAgB,UAAU,IAAI,OAAO,GAAG,IAAI,CAE3C;AAED,uBAAuB;AACvB,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}

package/dist/lib/program-registry.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setProgram = setProgram;
+exports.getProgram = getProgram;
+exports.resetProgramForTest = resetProgramForTest;
+let _program = null;
+function setProgram(p) {
+    _program = p;
+}
+function getProgram() {
+    return _program;
+}
+/** Reset for tests. */
+function resetProgramForTest() {
+    _program = null;
+}
+//# sourceMappingURL=program-registry.js.map

package/dist/lib/program-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"program-registry.js","sourceRoot":"","sources":["../../src/lib/program-registry.ts"],"names":[],"mappings":";;AAiBA,gCAEC;AAED,gCAEC;AAGD,kDAEC;AAbD,IAAI,QAAQ,GAAmB,IAAI,CAAC;AAEpC,SAAgB,UAAU,CAAC,CAAU;IACnC,QAAQ,GAAG,CAAC,CAAC;AACf,CAAC;AAED,SAAgB,UAAU;IACxB,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,uBAAuB;AACvB,SAAgB,mBAAmB;IACjC,QAAQ,GAAG,IAAI,CAAC;AAClB,CAAC"}

package/dist/lib/scope-diagnostic.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Scope/feature-gap diagnostic (Sprint 1 T1.6).
+ *
+ * Compares the scopes currently granted on an API key against the scopes
+ * the tenant's enabled features *should* grant (per backend service
+ * services/scope_expansion.py, Sprint 0 T0.5). Surfaces mismatches so
+ * `solid doctor` can tell the operator: "your key is missing agents:read
+ * because your tenant enabled the agents feature after the key was
+ * issued — rotate the key and you'll pick up the new scopes."
+ *
+ * Pure — takes primitives, returns primitives. No HTTP, no fs. The
+ * backend has the same map in services/scope_expansion.py; this is a
+ * narrow client-side mirror so operators see drift without a round-trip.
+ * Kept small on purpose: if it diverges from the backend map, the only
+ * impact is a diagnostic miss — enforcement is still server-side.
+ */
+/**
+ * Feature key → scopes it should grant on issuance.
+ * MUST stay in lock-step with solid-backend/services/scope_expansion.py
+ * FEATURE_TO_SCOPES. Keep small — every entry is a permission decision.
+ */
+export declare const FEATURE_TO_SCOPES: Readonly<Record<string, readonly string[]>>;
+/**
+ * Given the key's current scopes and the tenant's feature flags, return
+ * a sorted list of scopes that SHOULD be granted but aren't.
+ *
+ * Pure — no I/O.
+ */
+export declare function computeScopeGap(currentScopes: readonly string[] | null | undefined, featureSettings: Record<string, unknown> | null | undefined, featureToScopes?: Readonly<Record<string, readonly string[]>>): string[];
+export interface ScopeDiagnosticFinding {
+    severity: 'ok' | 'warn' | 'fail';
+    code: 'SCOPE_GAP' | 'NO_FEATURES' | 'NO_SCOPES' | 'ALL_GRANTED';
+    message: string;
+    missing_scopes: string[];
+    hint?: string;
+}
+/**
+ * Wrap computeScopeGap with a pre-canned diagnostic payload — the shape
+ * `solid doctor` surfaces to the operator. Pure.
+ */
+export declare function diagnoseScopeGap(currentScopes: readonly string[] | null | undefined, featureSettings: Record<string, unknown> | null | undefined): ScopeDiagnosticFinding;
+//# sourceMappingURL=scope-diagnostic.d.ts.map

package/dist/lib/scope-diagnostic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-diagnostic.d.ts","sourceRoot":"","sources":["../../src/lib/scope-diagnostic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAGzE,CAAC;AASF;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,EACnD,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAC3D,eAAe,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAqB,GAC/E,MAAM,EAAE,CAgBV;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;IACjC,IAAI,EAAE,WAAW,GAAG,aAAa,GAAG,WAAW,GAAG,aAAa,CAAC;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,EACnD,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAC1D,sBAAsB,CAkCxB"}