@skhema/cli 0.3.1

package/dist/commands/strategy.js

@@ -0,0 +1,143 @@
+import chalk from 'chalk';
+import { resolveClient } from '../lib/api/client.js';
+import { assertExportOutput, reportExport } from '../lib/api/export-cli.js';
+import { assertFormat, DOCUMENT_FORMATS } from '../lib/api/formats.js';
+import { resolveBody } from '../lib/api/payload.js';
+import { runCommand } from '../lib/api/run-command.js';
+import { resolveWorkspaceId } from '../lib/api/scope.js';
+import { performExport } 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 renderStrategies(strategies = []) {
+    if (strategies.length === 0) {
+        log(chalk.dim('No strategies.'));
+        return;
+    }
+    logHeader(`Strategies (${strategies.length})`);
+    logTable(['id', 'name', 'version', 'status'], strategies.map((s) => [
+        s.id,
+        s.name ?? '',
+        s.version === undefined ? '' : String(s.version),
+        s.status ?? '',
+    ]));
+}
+export function registerStrategyCommands(program) {
+    const strategy = program.command('strategy').description('Strategy commands');
+    withWorkspace(strategy.command('list'))
+        .description('List strategies in a workspace')
+        .action(async (opts) => {
+        await runCommand('strategy list', async () => {
+            const { client } = await resolveClient();
+            const ws = resolveWorkspaceId(opts.workspace);
+            const data = await client.strategies.list(ws);
+            renderStrategies(data.strategies);
+            return data;
+        });
+    });
+    withWorkspace(strategy.command('get <strategyId>'))
+        .description('Get a strategy with its committed elements')
+        .action(async (strategyId, opts) => {
+        await runCommand('strategy get', async () => {
+            const { client } = await resolveClient();
+            const ws = resolveWorkspaceId(opts.workspace);
+            const data = await client.strategies.get(ws, strategyId);
+            if (data.strategy) {
+                logHeader(data.strategy.name ?? strategyId);
+                log(chalk.dim(`status: ${data.strategy.status ?? '—'}  version: ${data.strategy.version ?? '—'}`));
+            }
+            return data;
+        });
+    });
+    withWorkspace(strategy.command('create'))
+        .description('Create a strategy')
+        .option('--name <name>', 'Strategy name')
+        .option('--description <text>', 'Description')
+        .option('--file <path>', 'JSON payload file (or - for stdin)')
+        .action(async (opts) => {
+        await runCommand('strategy create', async () => {
+            const { client } = await resolveClient();
+            const ws = resolveWorkspaceId(opts.workspace);
+            const body = resolveBody({
+                file: opts.file,
+                fields: { name: opts.name, description: opts.description },
+            });
+            const data = await client.strategies.create(ws, body);
+            log(chalk.green(`Created strategy ${chalk.cyan(data.strategy?.id)}`));
+            return data;
+        });
+    });
+    withWorkspace(strategy.command('update <strategyId>'))
+        .description('Update a strategy')
+        .option('--name <name>', 'New name')
+        .option('--description <text>', 'New description')
+        .option('--file <path>', 'JSON payload file (or - for stdin)')
+        .action(async (strategyId, opts) => {
+        await runCommand('strategy update', async () => {
+            const { client } = await resolveClient();
+            const ws = resolveWorkspaceId(opts.workspace);
+            const fields = {};
+            if (opts.name !== undefined)
+                fields.name = opts.name;
+            if (opts.description !== undefined)
+                fields.description = opts.description;
+            const body = resolveBody({ file: opts.file, fields });
+            const data = await client.strategies.update(ws, strategyId, body);
+            log(chalk.green(`Updated strategy ${chalk.cyan(strategyId)}`));
+            return data;
+        });
+    });
+    withWorkspace(strategy.command('commit <strategyId>'))
+        .description('Commit elements/components into a strategy')
+        .option('--component <id>', 'Commit all elements in this component')
+        .option('--file <path>', 'JSON payload file (or - for stdin)')
+        .action(async (strategyId, opts) => {
+        await runCommand('strategy commit', async () => {
+            const { client } = await resolveClient();
+            const ws = resolveWorkspaceId(opts.workspace);
+            const body = resolveBody({
+                file: opts.file,
+                fields: { componentId: opts.component },
+            });
+            const data = await client.strategies.commit(ws, strategyId, body);
+            log(chalk.green(`Committed to strategy ${chalk.cyan(strategyId)}`));
+            return data;
+        });
+    });
+    withWorkspace(strategy.command('activate <strategyId>'))
+        .description('Activate a strategy')
+        .action(async (strategyId, opts) => {
+        await runCommand('strategy activate', async () => {
+            const { client } = await resolveClient();
+            const ws = resolveWorkspaceId(opts.workspace);
+            const data = await client.strategies.activate(ws, strategyId);
+            log(chalk.green(`Activated strategy ${chalk.cyan(strategyId)}`));
+            return data;
+        });
+    });
+    withWorkspace(strategy.command('export <strategyId>'))
+        .description('Export a strategy (pdf/docx/md/json)')
+        .requiredOption('--format <format>', 'pdf | docx | md | json')
+        .option('--out <path>', 'Write to this path (- for stdout; default: server filename in cwd)')
+        .option('--email <recipient>', 'Email the export to an org member instead of downloading')
+        .action(async (strategyId, opts) => {
+        await runCommand('strategy export', async () => {
+            const { client } = await resolveClient();
+            const ws = resolveWorkspaceId(opts.workspace);
+            const format = assertFormat(opts.format, DOCUMENT_FORMATS);
+            assertExportOutput(opts);
+            const result = await performExport({
+                out: opts.email ? undefined : opts.out,
+                exec: () => client.strategies.export(ws, strategyId, {
+                    format,
+                    ...(opts.email
+                        ? { delivery: 'email', recipientEmail: opts.email }
+                        : {}),
+                }),
+            });
+            reportExport(result);
+            return result;
+        });
+    });
+}

package/dist/commands/webhook.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/commands/webhook.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAgCnC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwE9D"}

package/dist/commands/webhook.js

@@ -0,0 +1,77 @@
+import chalk from 'chalk';
+import { resolveClient } from '../lib/api/client.js';
+import { runCommand, UsageError } from '../lib/api/run-command.js';
+import { log, logHeader, logTable } from '../lib/output.js';
+function renderEndpoints(endpoints = []) {
+    if (endpoints.length === 0) {
+        log(chalk.dim('No webhook subscriptions.'));
+        return;
+    }
+    logHeader(`Webhook subscriptions (${endpoints.length})`);
+    logTable(['id', 'url', 'events', 'secret', 'status'], endpoints.map((e) => [
+        e.id,
+        e.url ?? '',
+        (e.subscribedEvents ?? []).join(',') || '*',
+        e.secretLast4 ? `••••${e.secretLast4}` : '',
+        e.status ?? '',
+    ]));
+}
+export function registerWebhookCommands(program) {
+    const webhook = program
+        .command('webhook')
+        .description('Outbound webhook subscription commands');
+    webhook
+        .command('create')
+        .description('Create a webhook subscription (signing secret shown once)')
+        .requiredOption('--url <url>', 'Destination URL')
+        .option('--events <list>', 'Comma-separated event types (default: all)')
+        .option('--name <name>', 'Display name')
+        .option('--description <text>', 'Description')
+        .action(async (opts) => {
+        await runCommand('webhook create', async () => {
+            const { client } = await resolveClient();
+            const body = { url: opts.url };
+            if (opts.events) {
+                body.subscribedEvents = opts.events
+                    .split(',')
+                    .map((e) => e.trim())
+                    .filter(Boolean);
+            }
+            if (opts.name)
+                body.displayName = opts.name;
+            if (opts.description)
+                body.description = opts.description;
+            const data = await client.webhooks.create(body);
+            log(chalk.green(`Created webhook ${chalk.cyan(data.endpoint?.id)}`));
+            log('');
+            log(chalk.yellow.bold('Signing secret (shown once — store it now):'));
+            log(chalk.bold(data.secret));
+            log(chalk.dim('It cannot be retrieved again; rotate if lost.'));
+            return data;
+        });
+    });
+    webhook
+        .command('list')
+        .description('List webhook subscriptions (secrets masked)')
+        .action(async () => {
+        await runCommand('webhook list', async () => {
+            const { client } = await resolveClient();
+            const data = await client.webhooks.list();
+            renderEndpoints(data.endpoints);
+            return data;
+        });
+    });
+    webhook
+        .command('delete <endpointId>')
+        .description('Delete a webhook subscription (idempotent)')
+        .action(async (endpointId) => {
+        await runCommand('webhook delete', async () => {
+            if (!endpointId)
+                throw new UsageError('endpointId is required.');
+            const { client } = await resolveClient();
+            const data = await client.webhooks.delete(endpointId);
+            log(chalk.green(`Deleted webhook ${chalk.cyan(endpointId)}`));
+            return data;
+        });
+    });
+}

package/dist/commands/workspace.d.ts

@@ -0,0 +1,8 @@
+import { Command } from 'commander';
+/**
+ * Workspace commands. `use` sets the default workspace consumed by scoped
+ * commands; the domain read/write verbs (list/get/create/update) and the
+ * `member` group wrap the `@skhema/sdk` workspaces resource.
+ */
+export declare function registerWorkspaceCommands(program: Command): void;
+//# sourceMappingURL=workspace.d.ts.map

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

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

package/dist/commands/workspace.js

@@ -0,0 +1,219 @@
+import chalk from 'chalk';
+import { resolveClient } from '../lib/api/client.js';
+import { asRecord, buildBody, coerceList, readPayloadFile, resolveWorkspaceId, } from '../lib/api/command-helpers.js';
+import { runCommand, UsageError } from '../lib/api/run-command.js';
+import { getConfigLocation, getDefaultWorkspaceId, setDefaultWorkspaceId, } from '../lib/config-store.js';
+import { getGlobalOptions, log, logHeader, logTable } from '../lib/output.js';
+/** Print a single workspace as a label block (human output only). */
+function printWorkspace(workspace) {
+    const w = asRecord(workspace);
+    logHeader(String(w.name ?? w.id ?? 'Workspace'));
+    log(`  Id:          ${chalk.cyan(String(w.id ?? '—'))}`);
+    if (w.visibility)
+        log(`  Visibility:  ${String(w.visibility)}`);
+    if (w.strategicContext)
+        log(`  Context:     ${String(w.strategicContext)}`);
+}
+/**
+ * Workspace commands. `use` sets the default workspace consumed by scoped
+ * commands; the domain read/write verbs (list/get/create/update) and the
+ * `member` group wrap the `@skhema/sdk` workspaces resource.
+ */
+export function registerWorkspaceCommands(program) {
+    const workspace = program
+        .command('workspace')
+        .description('Workspace commands');
+    workspace
+        .command('use [workspace-id]')
+        .description('Set (or, with --clear, unset) the default workspace')
+        .option('--clear', 'Clear the stored default workspace')
+        .action(async (workspaceId, options) => {
+        await runCommand('workspace use', async () => {
+            if (options.clear) {
+                setDefaultWorkspaceId(undefined);
+                log(chalk.green('Cleared the default workspace.'));
+                return { defaultWorkspaceId: null };
+            }
+            if (!workspaceId) {
+                const current = getDefaultWorkspaceId();
+                if (!current) {
+                    throw new UsageError('Provide a workspace id, e.g. `skhema workspace use <id>` (or --clear).');
+                }
+                log(`Default workspace: ${chalk.cyan(current)}`);
+                return { defaultWorkspaceId: current };
+            }
+            setDefaultWorkspaceId(workspaceId);
+            log(chalk.green(`Default workspace set to ${chalk.cyan(workspaceId)}.`));
+            log(chalk.dim(`  Stored in ${getConfigLocation()}`));
+            return { defaultWorkspaceId: workspaceId };
+        });
+    });
+    workspace
+        .command('list')
+        .description('List workspaces')
+        .action(async () => {
+        await runCommand('workspace list', async () => {
+            const { client } = await resolveClient();
+            const data = await client.workspaces.list();
+            const rows = coerceList(data, 'workspaces');
+            if (!getGlobalOptions().json) {
+                logHeader(`Workspaces (${rows.length})`);
+                if (rows.length === 0)
+                    log(chalk.dim('  No workspaces.'));
+                else
+                    logTable(['Id', 'Name', 'Visibility'], rows.map((r) => {
+                        const w = asRecord(r);
+                        return [
+                            String(w.id ?? '—'),
+                            String(w.name ?? '—'),
+                            String(w.visibility ?? '—'),
+                        ];
+                    }));
+            }
+            return data;
+        });
+    });
+    workspace
+        .command('get <workspace-id>')
+        .description('Get a workspace by id')
+        .action(async (workspaceId) => {
+        await runCommand('workspace get', async () => {
+            const { client } = await resolveClient();
+            const data = await client.workspaces.get(workspaceId);
+            if (!getGlobalOptions().json)
+                printWorkspace(asRecord(data).workspace ?? data);
+            return data;
+        });
+    });
+    workspace
+        .command('create')
+        .description('Create a workspace')
+        .option('--name <name>', 'Workspace name')
+        .option('--visibility <visibility>', 'Workspace visibility (e.g. global | restricted)')
+        .option('--file <path>', 'JSON payload file for the full body ("-" for stdin)')
+        .action(async (options) => {
+        await runCommand('workspace create', async () => {
+            const body = buildBody(readPayloadFile(options.file), {
+                name: options.name,
+                visibility: options.visibility,
+            });
+            if (!body.name) {
+                throw new UsageError('A workspace name is required. Pass --name <name> or include it in --file.');
+            }
+            const { client } = await resolveClient();
+            const data = await client.workspaces.create(body);
+            if (!getGlobalOptions().json) {
+                log(chalk.green('Workspace created.'));
+                printWorkspace(asRecord(data).workspace ?? data);
+            }
+            return data;
+        });
+    });
+    workspace
+        .command('update <workspace-id>')
+        .description('Update a workspace')
+        .option('--name <name>', 'Workspace name')
+        .option('--visibility <visibility>', 'Workspace visibility')
+        .option('--file <path>', 'JSON payload file for the full body ("-" for stdin)')
+        .action(async (workspaceId, options) => {
+        await runCommand('workspace update', async () => {
+            const body = buildBody(readPayloadFile(options.file), {
+                name: options.name,
+                visibility: options.visibility,
+            });
+            if (Object.keys(body).length === 0) {
+                throw new UsageError('Nothing to update. Pass --name/--visibility or a --file payload.');
+            }
+            const { client } = await resolveClient();
+            const data = await client.workspaces.update(workspaceId, body);
+            if (!getGlobalOptions().json) {
+                log(chalk.green('Workspace updated.'));
+                printWorkspace(asRecord(data).workspace ?? data);
+            }
+            return data;
+        });
+    });
+    registerMemberCommands(workspace);
+}
+/**
+ * `skhema workspace member …` — the workspace membership verbs. All are
+ * workspace-scoped via `--workspace` (falling back to the default workspace).
+ */
+function registerMemberCommands(workspace) {
+    const member = workspace
+        .command('member')
+        .description('Manage workspace members');
+    member
+        .command('list')
+        .description('List workspace members')
+        .option('--workspace <id>', 'Workspace id (defaults to `skhema workspace use`)')
+        .action(async (options) => {
+        await runCommand('workspace member list', async () => {
+            const workspaceId = resolveWorkspaceId(options.workspace);
+            const { client } = await resolveClient();
+            const data = await client.workspaces.listMembers(workspaceId);
+            const rows = coerceList(data, 'members');
+            if (!getGlobalOptions().json) {
+                logHeader(`Members (${rows.length})`);
+                if (rows.length === 0)
+                    log(chalk.dim('  No members.'));
+                else
+                    logTable(['User', 'Role'], rows.map((r) => {
+                        const m = asRecord(r);
+                        return [String(m.userId ?? m.id ?? '—'), String(m.role ?? '—')];
+                    }));
+            }
+            return data;
+        });
+    });
+    member
+        .command('add')
+        .description('Add a member to a workspace')
+        .requiredOption('--user <user-id>', 'User id to add')
+        .requiredOption('--role <role>', 'Role to grant')
+        .option('--workspace <id>', 'Workspace id (defaults to `skhema workspace use`)')
+        .action(async (options) => {
+        await runCommand('workspace member add', async () => {
+            const workspaceId = resolveWorkspaceId(options.workspace);
+            const { client } = await resolveClient();
+            const data = await client.workspaces.addMember(workspaceId, {
+                userId: options.user,
+                role: options.role,
+            });
+            if (!getGlobalOptions().json)
+                log(chalk.green(`Added ${options.user} as ${options.role}.`));
+            return data;
+        });
+    });
+    member
+        .command('remove')
+        .description('Remove a member from a workspace')
+        .requiredOption('--user <user-id>', 'User id to remove')
+        .option('--workspace <id>', 'Workspace id (defaults to `skhema workspace use`)')
+        .action(async (options) => {
+        await runCommand('workspace member remove', async () => {
+            const workspaceId = resolveWorkspaceId(options.workspace);
+            const { client } = await resolveClient();
+            const data = await client.workspaces.removeMember(workspaceId, options.user);
+            if (!getGlobalOptions().json)
+                log(chalk.green(`Removed ${options.user}.`));
+            return data;
+        });
+    });
+    member
+        .command('set-role')
+        .description("Update a member's role")
+        .requiredOption('--user <user-id>', 'User id to update')
+        .requiredOption('--role <role>', 'New role')
+        .option('--workspace <id>', 'Workspace id (defaults to `skhema workspace use`)')
+        .action(async (options) => {
+        await runCommand('workspace member set-role', async () => {
+            const workspaceId = resolveWorkspaceId(options.workspace);
+            const { client } = await resolveClient();
+            const data = await client.workspaces.updateMemberRole(workspaceId, options.user, { role: options.role });
+            if (!getGlobalOptions().json)
+                log(chalk.green(`Set ${options.user} to ${options.role}.`));
+            return data;
+        });
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { AUTH_BASE_URL, CLI_CLIENT_ID, OAUTH_SCOPES } from './lib/config.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export { AUTH_BASE_URL, CLI_CLIENT_ID, OAUTH_SCOPES } from './lib/config.js';

package/dist/lib/api/client.d.ts

@@ -0,0 +1,27 @@
+import { SkhemaClient } from '@skhema/sdk';
+/** Which credential source, in precedence order, is backing the client. */
+export type CredentialLane = 'flag' | 'env' | 'stored-key' | 'oauth';
+export interface CredentialDescriptor {
+    lane: CredentialLane;
+    /** `api-key` for the three key lanes; `oauth` for the stored session. */
+    kind: 'api-key' | 'oauth';
+    /** Masked key (`sk_live_...last4`), present for api-key lanes only. */
+    maskedKey?: string;
+    /** Organization id, when known without a network round-trip (OAuth lane). */
+    organizationId?: string;
+    /** Human-friendly source description for `auth status`. */
+    source: string;
+}
+export interface ResolvedClient {
+    client: SkhemaClient;
+    credential: CredentialDescriptor;
+}
+/** Mask a raw key to `sk_live_...abcd` — the only safe form to ever print. */
+export declare function maskApiKey(rawKey: string): string;
+/**
+ * Resolve the active credential using the fixed precedence (spec §3.1):
+ * `--api-key` flag → `SKHEMA_API_KEY` env → stored key → stored OAuth session.
+ * Throws {@link AuthRequiredError} (exit 3) when none is available.
+ */
+export declare function resolveClient(): Promise<ResolvedClient>;
+//# sourceMappingURL=client.d.ts.map

package/dist/lib/api/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/api/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,YAAY,EAAE,MAAM,aAAa,CAAA;AAO9D,2EAA2E;AAC3E,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,KAAK,GAAG,YAAY,GAAG,OAAO,CAAA;AAEpE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,cAAc,CAAA;IACpB,yEAAyE;IACzE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAA;IACzB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,YAAY,CAAA;IACpB,UAAU,EAAE,oBAAoB,CAAA;CACjC;AAED,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGjD;AASD;;;;GAIG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,cAAc,CAAC,CA4D7D"}

package/dist/lib/api/client.js

@@ -0,0 +1,71 @@
+import { createSkhemaClient } from '@skhema/sdk';
+import { getStoredApiKey } from '../auth/api-key-store.js';
+import { getStoredCredentials } from '../auth/token-store.js';
+import { API_BASE_URL, API_KEY_ENV_VAR, AUTH_BASE_URL } from '../config.js';
+import { getApiKeyFlag } from './credential-context.js';
+import { AuthRequiredError } from './run-command.js';
+/** Mask a raw key to `sk_live_...abcd` — the only safe form to ever print. */
+export function maskApiKey(rawKey) {
+    const last4 = rawKey.slice(-4);
+    return `sk_live_...${last4}`;
+}
+function apiKeyClient(rawKey) {
+    return createSkhemaClient({ apiKey: rawKey }, { baseUrl: API_BASE_URL, authBaseUrl: AUTH_BASE_URL });
+}
+/**
+ * Resolve the active credential using the fixed precedence (spec §3.1):
+ * `--api-key` flag → `SKHEMA_API_KEY` env → stored key → stored OAuth session.
+ * Throws {@link AuthRequiredError} (exit 3) when none is available.
+ */
+export async function resolveClient() {
+    const flagKey = getApiKeyFlag();
+    if (flagKey) {
+        return {
+            client: apiKeyClient(flagKey),
+            credential: {
+                lane: 'flag',
+                kind: 'api-key',
+                maskedKey: maskApiKey(flagKey),
+                source: '--api-key flag',
+            },
+        };
+    }
+    const envKey = process.env[API_KEY_ENV_VAR];
+    if (envKey) {
+        return {
+            client: apiKeyClient(envKey),
+            credential: {
+                lane: 'env',
+                kind: 'api-key',
+                maskedKey: maskApiKey(envKey),
+                source: `${API_KEY_ENV_VAR} environment variable`,
+            },
+        };
+    }
+    const storedKey = getStoredApiKey();
+    if (storedKey) {
+        return {
+            client: apiKeyClient(storedKey),
+            credential: {
+                lane: 'stored-key',
+                kind: 'api-key',
+                maskedKey: maskApiKey(storedKey),
+                source: 'stored API key (skhema auth key use)',
+            },
+        };
+    }
+    const creds = await getStoredCredentials();
+    if (creds?.access_token) {
+        return {
+            client: createSkhemaClient({ token: creds.access_token }, { baseUrl: API_BASE_URL, authBaseUrl: AUTH_BASE_URL }),
+            credential: {
+                lane: 'oauth',
+                kind: 'oauth',
+                organizationId: creds.organization?.id,
+                source: 'OAuth session (skhema auth login)',
+            },
+        };
+    }
+    throw new AuthRequiredError('No credentials found. Run `skhema auth login` for interactive use, or set ' +
+        `${API_KEY_ENV_VAR}=sk_live_… (or run \`skhema auth key use <key>\`) for headless/CI use.`);
+}

package/dist/lib/api/command-helpers.d.ts

@@ -0,0 +1,27 @@
+import { RequestBody } from '@skhema/sdk';
+/**
+ * Resolve the target workspace for a workspace-scoped command: the explicit
+ * `--workspace` flag wins, else the stored default (`skhema workspace use`).
+ * Throws a {@link UsageError} (exit 2) when neither is set.
+ */
+export declare function resolveWorkspaceId(flag?: string): string;
+/**
+ * Read a full JSON request payload from `--file <path>` (or `-` for stdin).
+ * Returns `undefined` when no path is given. A malformed file is a usage error.
+ */
+export declare function readPayloadFile(filePath?: string): RequestBody | undefined;
+/**
+ * Build a request body from an optional `--file` base merged with field flags.
+ * Flag values that are `undefined` are dropped, so explicit flags override the
+ * file and unset flags leave the file's value intact.
+ */
+export declare function buildBody(base: RequestBody | undefined, fields: Record<string, unknown>): RequestBody;
+/** Narrow an unknown value to a plain record for defensive field access. */
+export declare function asRecord(value: unknown): Record<string, unknown>;
+/**
+ * Coerce a list-shaped API response to an array. The gateway wraps collections
+ * under a resource key (`{ workspaces: [...] }`); fall back to the first array
+ * property, or the value itself when it is already an array.
+ */
+export declare function coerceList(value: unknown, key?: string): unknown[];
+//# sourceMappingURL=command-helpers.d.ts.map

package/dist/lib/api/command-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-helpers.d.ts","sourceRoot":"","sources":["../../../src/lib/api/command-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAKzC;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAQxD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAsB1E;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,WAAW,CAMb;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIhE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,EAAE,CAQlE"}