@skhema/cli 0.3.1

package/dist/commands/init.js

@@ -0,0 +1,275 @@
+import chalk from 'chalk';
+import readline from 'readline';
+import { resolveClient } from '../lib/api/client.js';
+import { setApiKeyFlag } from '../lib/api/credential-context.js';
+import { AuthRequiredError, runCommand } from '../lib/api/run-command.js';
+import { getStoredApiKey, storeApiKey } from '../lib/auth/api-key-store.js';
+import { startLocalhostFlow } from '../lib/auth/localhost-flow.js';
+import { MCP_SERVER_URL } from '../lib/config.js';
+import { inspectTarget, registerTarget, } from '../lib/mcp/registrar.js';
+import { detectMcpTargets, MCP_SERVER_NAME } from '../lib/mcp/registry.js';
+import { getGlobalOptions, log, logHeader } from '../lib/output.js';
+import { installSkills } from '../lib/skills/installer.js';
+import { detectPlatforms } from '../lib/skills/platform-detect.js';
+const QUICKSTART = [
+    'skhema auth status',
+    'skhema api routes',
+    'skhema api GET /workspaces',
+];
+function isInteractive() {
+    const opts = getGlobalOptions();
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY) && !opts.json;
+}
+async function confirm(question) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const answer = await new Promise((resolve) => {
+        rl.question(`${question} [y/N]: `, (a) => {
+            rl.close();
+            resolve(a.trim().toLowerCase());
+        });
+    });
+    return answer === 'y' || answer === 'yes';
+}
+/** Step 1 — resolve, verify, and (for an explicit --api-key) persist a credential. */
+async function runCredentialStep(options) {
+    if (options.apiKey)
+        setApiKeyFlag(options.apiKey);
+    let resolved;
+    try {
+        resolved = await resolveClient();
+    }
+    catch (err) {
+        if (err instanceof AuthRequiredError) {
+            // Interactive and not --yes: offer to log in, then retry once.
+            if (!options.yes && isInteractive()) {
+                log(chalk.yellow('No credential found.'));
+                if (await confirm('Log in to Skhema in your browser now?')) {
+                    await startLocalhostFlow();
+                    try {
+                        resolved = await resolveClient();
+                    }
+                    catch {
+                        /* fall through to disconnected */
+                    }
+                }
+            }
+            if (!resolved) {
+                return {
+                    connected: false,
+                    reason: 'No credential. Set SKHEMA_API_KEY / pass --api-key, or run `skhema auth login`.',
+                };
+            }
+        }
+        else {
+            throw err;
+        }
+    }
+    const { client, credential } = resolved;
+    // health() forces the API-key exchange (verifying the key) and is a cheap probe.
+    let verified = false;
+    try {
+        await client.meta.health();
+        verified = true;
+    }
+    catch {
+        verified = false;
+    }
+    const ctx = client.getContext();
+    const organizationId = ctx.organizationId ?? credential.organizationId;
+    let workspaceCount;
+    if (verified) {
+        try {
+            const res = await client.workspaces.list();
+            workspaceCount = Array.isArray(res?.workspaces)
+                ? res.workspaces.length
+                : undefined;
+        }
+        catch {
+            // A read may be denied (e.g. write-only key) — leave the count undefined.
+        }
+    }
+    // Persist only an explicitly-provided --api-key, and never clobber a different
+    // stored key without --force (spec: no silent credential overwrite).
+    let stored;
+    if (options.apiKey && verified) {
+        const existing = getStoredApiKey();
+        if (!existing || existing === options.apiKey || options.force) {
+            storeApiKey(options.apiKey);
+            stored = true;
+        }
+        else {
+            stored = false;
+        }
+    }
+    return {
+        connected: true,
+        lane: credential.lane,
+        source: credential.source,
+        verified,
+        organizationId,
+        permission: ctx.permission,
+        workspaceCount,
+        stored,
+    };
+}
+/** Step 2 — install bundled skills into every detected agent platform. */
+async function runSkillsStep(options) {
+    if (options.skipSkills)
+        return { skipped: true };
+    const platforms = detectPlatforms().filter((p) => p.detected);
+    if (platforms.length === 0) {
+        return { platforms: [], installed: 0, updated: 0, unchanged: 0 };
+    }
+    const results = await installSkills(platforms);
+    return {
+        platforms: platforms.map((p) => p.name),
+        installed: results.filter((r) => r.action === 'installed').length,
+        updated: results.filter((r) => r.action === 'updated').length,
+        unchanged: results.filter((r) => r.action === 'skipped').length,
+    };
+}
+/** Step 3 — register the MCP server, or report what a run would do (safe by default). */
+async function runMcpStep(options) {
+    const targets = detectMcpTargets();
+    const detected = targets.filter((t) => t.detected);
+    if (options.skipMcp || detected.length === 0) {
+        return {
+            serverUrl: MCP_SERVER_URL,
+            mutated: false,
+            targets: detected.map((t) => ({
+                id: t.id,
+                name: t.name,
+                status: options.skipMcp ? 'skipped' : inspectTarget(t),
+                configPath: t.configPath ?? undefined,
+            })),
+        };
+    }
+    // Mutate only with --yes, or after an interactive confirmation. Otherwise we
+    // report the inspected status without touching any file.
+    let willWrite = Boolean(options.yes);
+    if (!willWrite && isInteractive()) {
+        willWrite = await confirm(`Register the Skhema MCP server in ${detected.length} detected client(s)?`);
+    }
+    const targetStates = detected.map((t) => {
+        if (!willWrite) {
+            return {
+                id: t.id,
+                name: t.name,
+                status: inspectTarget(t),
+                configPath: t.configPath ?? undefined,
+                instructions: t.instructions,
+            };
+        }
+        const outcome = registerTarget(t, {
+            force: options.force,
+        });
+        return {
+            id: t.id,
+            name: t.name,
+            status: outcome.status,
+            configPath: outcome.configPath,
+            backupPath: outcome.backupPath,
+            instructions: outcome.instructions,
+        };
+    });
+    return {
+        serverUrl: MCP_SERVER_URL,
+        mutated: willWrite && targetStates.some((s) => s.status === 'registered'),
+        targets: targetStates,
+    };
+}
+/** Orchestrate all init steps and return the machine-readable state. */
+export async function runInit(options) {
+    const credential = await runCredentialStep(options);
+    const skills = await runSkillsStep(options);
+    const mcp = await runMcpStep(options);
+    const state = { credential, skills, mcp, quickstart: QUICKSTART };
+    renderHuman(state);
+    return state;
+}
+function renderHuman(state) {
+    if (getGlobalOptions().json)
+        return;
+    logHeader('Skhema init');
+    // Credential
+    const c = state.credential;
+    if (c.connected) {
+        log(`  Credential:   ${chalk.green('connected')} (${c.source})${c.verified ? '' : chalk.yellow(' — could not verify')}`);
+        if (c.organizationId)
+            log(`  Organization: ${chalk.cyan(c.organizationId)}`);
+        if (c.permission)
+            log(`  Permission:   ${c.permission}`);
+        if (c.stored === true)
+            log(chalk.dim('  Stored API key for future commands.'));
+        if (c.stored === false) {
+            log(chalk.yellow('  A different API key is already stored; kept it (use --force to replace).'));
+        }
+    }
+    else {
+        log(`  Credential:   ${chalk.yellow('not connected')}`);
+        log(chalk.dim(`    ${c.reason}`));
+    }
+    // Skills
+    const s = state.skills;
+    if (s.skipped) {
+        log(`  Skills:       ${chalk.dim('skipped')}`);
+    }
+    else if ((s.platforms?.length ?? 0) === 0) {
+        log(`  Skills:       ${chalk.dim('no agent platforms detected')}`);
+    }
+    else {
+        log(`  Skills:       ${chalk.green('installed')} to ${s.platforms.join(', ')} ` +
+            chalk.dim(`(+${s.installed} new, ${s.updated} updated, ${s.unchanged} unchanged)`));
+    }
+    // MCP
+    const m = state.mcp;
+    log(`  MCP server:   ${chalk.cyan(m.serverUrl)}`);
+    if (m.targets.length === 0) {
+        log(chalk.dim('    No MCP clients detected.'));
+    }
+    for (const t of m.targets) {
+        const label = t.status === 'registered'
+            ? chalk.green('registered')
+            : t.status === 'already'
+                ? chalk.dim('already registered')
+                : t.status === 'writable'
+                    ? chalk.yellow('pending (run with --yes to register)')
+                    : t.status === 'conflict'
+                        ? chalk.yellow('conflict — left untouched')
+                        : chalk.yellow(t.status);
+        log(`    ${t.name}: ${label}`);
+        if (t.backupPath)
+            log(chalk.dim(`      backup: ${t.backupPath}`));
+        if ((t.status === 'manual' ||
+            t.status === 'conflict' ||
+            t.status === 'writable') &&
+            t.instructions) {
+            log(chalk.dim(`      ${t.instructions}`));
+        }
+    }
+    // Quickstart
+    log('');
+    logHeader('Try these');
+    for (const cmd of state.quickstart)
+        log(`  ${chalk.cyan(cmd)}`);
+    if (state.credential.connected) {
+        log('');
+        log(chalk.dim(`  MCP server "${MCP_SERVER_NAME}" authorizes in-browser on first use.`));
+    }
+}
+export function registerInitCommand(program) {
+    program
+        .command('init')
+        .description('One-command onboarding: verify a credential, install skills, register the MCP server')
+        .option('--api-key <key>', 'Use (and store) this API key as the credential')
+        .option('--yes', 'Non-interactive: do everything possible, never prompt')
+        .option('--force', 'Overwrite an existing stored key / conflicting MCP entry')
+        .option('--skip-skills', 'Do not install skills')
+        .option('--skip-mcp', 'Do not register the MCP server')
+        .action(async (options) => {
+        await runCommand('init', () => runInit(options));
+    });
+}

package/dist/commands/link.d.ts

@@ -0,0 +1,8 @@
+import { Command } from 'commander';
+/**
+ * Element link commands — typed relationships between elements. All are
+ * workspace-scoped via `--workspace`. There is no `list` verb: links come back
+ * embedded in element/workspace payloads, not on a dedicated route.
+ */
+export declare function registerLinkCommands(program: Command): void;
+//# sourceMappingURL=link.d.ts.map

package/dist/commands/link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../src/commands/link.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAWnC;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8F3D"}

package/dist/commands/link.js

@@ -0,0 +1,70 @@
+import chalk from 'chalk';
+import { resolveClient } from '../lib/api/client.js';
+import { asRecord, buildBody, readPayloadFile, resolveWorkspaceId, } from '../lib/api/command-helpers.js';
+import { runCommand, UsageError } from '../lib/api/run-command.js';
+import { getGlobalOptions, log } from '../lib/output.js';
+/**
+ * Element link commands — typed relationships between elements. All are
+ * workspace-scoped via `--workspace`. There is no `list` verb: links come back
+ * embedded in element/workspace payloads, not on a dedicated route.
+ */
+export function registerLinkCommands(program) {
+    const link = program.command('link').description('Element link commands');
+    const withWorkspace = (cmd) => cmd.option('--workspace <id>', 'Workspace id (defaults to `skhema workspace use`)');
+    withWorkspace(link
+        .command('create')
+        .description('Create an element link')
+        .option('--source <element-id>', 'Source element id')
+        .option('--target <element-id>', 'Target element id')
+        .option('--type <link-type>', 'Link type')
+        .option('--file <path>', 'JSON payload file for the full body ("-" for stdin)')).action(async (options) => {
+        await runCommand('link create', async () => {
+            const workspaceId = resolveWorkspaceId(options.workspace);
+            const body = buildBody(readPayloadFile(options.file), {
+                sourceElementId: options.source,
+                targetElementId: options.target,
+                linkType: options.type,
+            });
+            if (Object.keys(body).length === 0) {
+                throw new UsageError('Nothing to create. Pass --source/--target/--type or a --file payload.');
+            }
+            const { client } = await resolveClient();
+            const data = await client.links.create(workspaceId, body);
+            if (!getGlobalOptions().json) {
+                const l = asRecord(asRecord(data).link ?? data);
+                log(chalk.green(`Link created${l.id ? ` (${String(l.id)})` : ''}.`));
+            }
+            return data;
+        });
+    });
+    withWorkspace(link
+        .command('update <link-id>')
+        .description('Update an element link')
+        .option('--type <link-type>', 'Link type')
+        .option('--file <path>', 'JSON payload file for the full body ("-" for stdin)')).action(async (linkId, options) => {
+        await runCommand('link update', async () => {
+            const workspaceId = resolveWorkspaceId(options.workspace);
+            const body = buildBody(readPayloadFile(options.file), {
+                linkType: options.type,
+            });
+            if (Object.keys(body).length === 0) {
+                throw new UsageError('Nothing to update. Pass --type or a --file payload.');
+            }
+            const { client } = await resolveClient();
+            const data = await client.links.update(workspaceId, linkId, body);
+            if (!getGlobalOptions().json)
+                log(chalk.green('Link updated.'));
+            return data;
+        });
+    });
+    withWorkspace(link.command('delete <link-id>').description('Delete an element link')).action(async (linkId, options) => {
+        await runCommand('link delete', async () => {
+            const workspaceId = resolveWorkspaceId(options.workspace);
+            const { client } = await resolveClient();
+            const data = await client.links.delete(workspaceId, linkId);
+            if (!getGlobalOptions().json)
+                log(chalk.green(`Deleted link ${linkId}.`));
+            return data;
+        });
+    });
+}

package/dist/commands/resource.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerResourceCommands(program: Command): void;
+//# sourceMappingURL=resource.d.ts.map

package/dist/commands/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/commands/resource.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAuCnC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoF/D"}

package/dist/commands/resource.js

@@ -0,0 +1,88 @@
+import chalk from 'chalk';
+import { resolveClient } from '../lib/api/client.js';
+import { assertExportOutput } from '../lib/api/export-cli.js';
+import { runCommand } from '../lib/api/run-command.js';
+import { resolveWorkspaceId } from '../lib/api/scope.js';
+import { downloadResource, uploadResource } from '../lib/api/transfer.js';
+import { log, logHeader, logTable } from '../lib/output.js';
+function withWorkspace(cmd) {
+    return cmd.option('--workspace <id>', 'Workspace id (defaults to `skhema workspace use`)');
+}
+function renderResources(resources = []) {
+    if (resources.length === 0) {
+        log(chalk.dim('No resources.'));
+        return;
+    }
+    logHeader(`Resources (${resources.length})`);
+    logTable(['id', 'kind', 'ref'], resources.map((r) => {
+        const kind = r.filePath ? 'file' : r.url ? 'url' : 'citation';
+        const ref = r.filePath ?? r.url ?? (r.citation ? '(citation)' : '');
+        return [r.id, kind, String(ref ?? '')];
+    }));
+}
+export function registerResourceCommands(program) {
+    const resource = program
+        .command('resource')
+        .description('Element resource commands (files, URLs, citations)');
+    withWorkspace(resource.command('list'))
+        .description('List resources on an element')
+        .requiredOption('--element <id>', 'Element id')
+        .action(async (opts) => {
+        await runCommand('resource list', async () => {
+            const { client } = await resolveClient();
+            const ws = resolveWorkspaceId(opts.workspace);
+            const data = await client.elements.resources.list(ws, opts.element);
+            renderResources(data.resources);
+            return data;
+        });
+    });
+    withWorkspace(resource.command('upload <file>'))
+        .description('Upload a file as a resource on an element')
+        .requiredOption('--element <id>', 'Element id to attach the file to')
+        .option('--attribution <text>', 'Attribution note')
+        .action(async (file, opts) => {
+        await runCommand('resource upload', async () => {
+            const { client } = await resolveClient();
+            const ws = resolveWorkspaceId(opts.workspace);
+            const data = await uploadResource({
+                client,
+                workspaceId: ws,
+                elementId: opts.element,
+                filePath: file,
+                attribution: opts.attribution,
+            });
+            log(chalk.green(`Uploaded ${file}`));
+            return data;
+        });
+    });
+    withWorkspace(resource.command('download <resourceId>'))
+        .description('Download a resource file')
+        .option('--out <path>', 'Write to this path (- for stdout; default: original filename in cwd)')
+        .action(async (resourceId, opts) => {
+        await runCommand('resource download', async () => {
+            // `--out -` streams binary; incompatible with --json.
+            assertExportOutput({ out: opts.out });
+            const { client } = await resolveClient();
+            const ws = resolveWorkspaceId(opts.workspace);
+            const result = await downloadResource({
+                client,
+                workspaceId: ws,
+                resourceId,
+                out: opts.out,
+            });
+            log(chalk.green(`Wrote ${result.bytes} bytes to ${result.path}`));
+            return result;
+        });
+    });
+    withWorkspace(resource.command('delete <resourceId>'))
+        .description('Delete a resource')
+        .action(async (resourceId, opts) => {
+        await runCommand('resource delete', async () => {
+            const { client } = await resolveClient();
+            const ws = resolveWorkspaceId(opts.workspace);
+            const data = await client.elements.resources.delete(ws, resourceId);
+            log(chalk.green(`Deleted resource ${chalk.cyan(resourceId)}`));
+            return data;
+        });
+    });
+}

package/dist/commands/skills.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerSkillsCommands(program: Command): void;
+//# sourceMappingURL=skills.d.ts.map

package/dist/commands/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/commands/skills.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAanC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA4I7D"}

package/dist/commands/skills.js

@@ -0,0 +1,113 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { getGlobalOptions, log, logHeader, logTable, outputError, outputSuccess, } from '../lib/output.js';
+import { installSkills, updateSkills } from '../lib/skills/installer.js';
+import { detectPlatforms } from '../lib/skills/platform-detect.js';
+export function registerSkillsCommands(program) {
+    const skills = program.command('skills').description('AI skills management');
+    skills
+        .command('install')
+        .description('Install Skhema skills to detected agent platforms')
+        .option('--platform <id>', 'Install to a specific platform only')
+        .action(async (options) => {
+        const opts = getGlobalOptions();
+        const spinner = opts.json || opts.quiet
+            ? null
+            : ora('Detecting agent platforms...').start();
+        try {
+            const platforms = detectPlatforms();
+            const detected = platforms.filter((p) => p.detected);
+            if (detected.length === 0) {
+                spinner?.warn('No agent platforms detected.');
+                log(chalk.dim('Supported platforms: Claude Code, Codex, Warp, Antigravity'));
+                return;
+            }
+            // Filter to specific platform if requested
+            const targets = options.platform
+                ? detected.filter((p) => p.id === options.platform)
+                : detected;
+            if (targets.length === 0) {
+                spinner?.fail(`Platform "${options.platform}" not detected.`);
+                return;
+            }
+            spinner?.succeed(`Detected ${targets.length} platform(s): ${targets.map((p) => p.name).join(', ')}`);
+            const results = await installSkills(targets);
+            if (opts.json) {
+                outputSuccess(results, 'skills install');
+                return;
+            }
+            // Display results as table
+            const rows = results.map((r) => [
+                r.platform.name,
+                r.skill,
+                r.action === 'installed'
+                    ? chalk.green(r.action)
+                    : r.action === 'updated'
+                        ? chalk.yellow(r.action)
+                        : chalk.dim(r.action),
+            ]);
+            logHeader('Installation Results');
+            logTable(['Platform', 'Skill', 'Status'], rows);
+        }
+        catch (error) {
+            spinner?.fail('Installation failed');
+            outputError(error instanceof Error ? error.message : 'Unknown error', 'skills install');
+            process.exit(1);
+        }
+    });
+    skills
+        .command('list')
+        .description('Show detected platforms and installed skills')
+        .action(async () => {
+        try {
+            const platforms = detectPlatforms();
+            if (getGlobalOptions().json) {
+                outputSuccess(platforms, 'skills list');
+                return;
+            }
+            logHeader('Agent Platforms');
+            const rows = platforms.map((p) => [
+                p.name,
+                p.detected ? chalk.green('Detected') : chalk.dim('Not found'),
+                p.detected ? p.skillsDir : '-',
+            ]);
+            logTable(['Platform', 'Status', 'Skills Directory'], rows);
+        }
+        catch (error) {
+            outputError(error instanceof Error ? error.message : 'Unknown error', 'skills list');
+            process.exit(1);
+        }
+    });
+    skills
+        .command('update')
+        .description('Update installed skills to latest bundled versions')
+        .action(async () => {
+        const opts = getGlobalOptions();
+        const spinner = opts.json || opts.quiet ? null : ora('Checking for updates...').start();
+        try {
+            const platforms = detectPlatforms().filter((p) => p.detected);
+            if (platforms.length === 0) {
+                spinner?.warn('No agent platforms detected.');
+                return;
+            }
+            spinner?.succeed(`Found ${platforms.length} platform(s)`);
+            const results = await updateSkills(platforms);
+            if (opts.json) {
+                outputSuccess(results, 'skills update');
+                return;
+            }
+            const rows = results.map((r) => [
+                r.platform.name,
+                r.skill,
+                r.action === 'updated' ? chalk.yellow(r.action) : chalk.dim(r.action),
+            ]);
+            logHeader('Update Results');
+            logTable(['Platform', 'Skill', 'Status'], rows);
+        }
+        catch (error) {
+            spinner?.fail('Update failed');
+            outputError(error instanceof Error ? error.message : 'Unknown error', 'skills update');
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/strategy.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerStrategyCommands(program: Command): void;
+//# sourceMappingURL=strategy.d.ts.map

package/dist/commands/strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.d.ts","sourceRoot":"","sources":["../../src/commands/strategy.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAyCnC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA+K/D"}