@skhema/cli 0.4.5 → 0.4.7

package/README.md

@@ -57,6 +57,21 @@ skhema api routes                                # every live route from the Ope
 `--data` takes a JSON literal, `@file`, or `-` (stdin). `--query k=v` repeats. The
 passthrough refuses any host other than the Skhema gateway.
 
+### Strategy document imports
+
+Import a local strategy document or public URL through the same reviewable
+proposal used by the web and MCP surfaces:
+
+```sh
+skhema import start --file ./strategy.pdf --wait
+skhema import get imp_...                       # inspect the mapped proposal
+skhema import decide imp_... --file decisions.json
+skhema import apply imp_... --workspace-name "Imported strategy" --yes
+```
+
+Use `--json` for a stable machine envelope. Applying or discarding requires an
+interactive confirmation, or an explicit `--yes` in scripts and CI.
+
 ## Credential lanes
 
 The CLI accepts **two kinds** of credential and resolves them in a fixed

package/dist/commands/import.d.ts

@@ -0,0 +1,4 @@
+import { Command } from 'commander';
+/** Register the complete proposal-first import session lifecycle. */
+export declare function registerImportCommands(program: Command): void;
+//# sourceMappingURL=import.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["../../src/commands/import.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAkHnC,qEAAqE;AACrE,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA6L7D"}

package/dist/commands/import.js

@@ -0,0 +1,238 @@
+import chalk from 'chalk';
+import readline from 'readline';
+import { resolveClient } from '../lib/api/client.js';
+import { startFileImport, waitForImport } from '../lib/api/import-transfer.js';
+import { parseJsonFile } from '../lib/api/payload.js';
+import { runCommand, UsageError } from '../lib/api/run-command.js';
+import { getGlobalOptions, log, logHeader, logTable } from '../lib/output.js';
+function printSession(session) {
+    logHeader(session.proposalPayload?.summary.title ?? `Import ${session.id}`);
+    log(`  Id:       ${chalk.cyan(session.id)}`);
+    log(`  Status:   ${session.status}`);
+    const source = session.sourceFilename ?? session.sourceUrl;
+    if (source)
+        log(`  Source:   ${source}`);
+    if (session.progressStage) {
+        const count = session.progressCurrent !== null && session.progressTotal !== null
+            ? ` ${session.progressCurrent}/${session.progressTotal}`
+            : '';
+        log(`  Progress: ${session.progressStage}${count}`);
+    }
+    if (session.error)
+        log(`  Error:    ${session.error}`);
+    if (session.workspaceId)
+        log(`  Workspace: ${session.workspaceId}`);
+    const proposal = session.proposalPayload;
+    if (!proposal)
+        return;
+    log('');
+    log(`${proposal.items.length} mapped item${proposal.items.length === 1 ? '' : 's'}, ` +
+        `${proposal.orphans.length} unmapped.`);
+    if (proposal.items.length > 0) {
+        logTable(['Id', 'Component', 'Type', 'Confidence', 'Content'], proposal.items.map((item) => [
+            item.id,
+            item.componentType,
+            item.elementType,
+            item.confidence,
+            item.proposed.content.length > 60
+                ? `${item.proposed.content.slice(0, 57)}...`
+                : item.proposed.content,
+        ]));
+    }
+}
+function organizationFor(explicit, credential) {
+    const organizationId = explicit ?? credential.organizationId;
+    if (credential.kind === 'oauth' && !organizationId) {
+        throw new UsageError('No organization is available for this OAuth session. Pass --organization <id>.');
+    }
+    return organizationId;
+}
+function interactiveTerminal() {
+    return (Boolean(process.stdin.isTTY && process.stdout.isTTY) &&
+        !getGlobalOptions().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]: `, (value) => {
+            rl.close();
+            resolve(value.trim().toLowerCase());
+        });
+    });
+    return answer === 'y' || answer === 'yes';
+}
+async function authorizeMutation(question, yes) {
+    if (yes)
+        return true;
+    if (!interactiveTerminal()) {
+        throw new UsageError('This command requires --yes when run non-interactively.');
+    }
+    return confirm(question);
+}
+function decisionsFrom(source) {
+    const parsed = parseJsonFile(source);
+    const candidate = parsed.decisions &&
+        typeof parsed.decisions === 'object' &&
+        !Array.isArray(parsed.decisions)
+        ? parsed.decisions
+        : parsed;
+    return candidate;
+}
+async function maybeWait(client, response, wait) {
+    if (!wait)
+        return response;
+    return waitForImport({ client, sessionId: response.session.id });
+}
+/** Register the complete proposal-first import session lifecycle. */
+export function registerImportCommands(program) {
+    const imports = program
+        .command('import')
+        .description('Import a strategy document through a reviewable proposal');
+    imports
+        .command('start')
+        .description('Start an import from a local file or public URL')
+        .option('--file <path>', 'Local PDF, DOCX, Markdown, text, CSV, XLSX, or JSON')
+        .option('--url <url>', 'Public http(s) URL to import')
+        .option('--organization <id>', 'Organization id (OAuth user lane)')
+        .option('--wait', 'Poll until the proposal is ready or analysis fails')
+        .action(async (options) => {
+        await runCommand('import start', async () => {
+            if (Boolean(options.file) === Boolean(options.url)) {
+                throw new UsageError('Pass exactly one of --file <path> or --url <url>.');
+            }
+            if (options.url && !/^https?:\/\//i.test(options.url)) {
+                throw new UsageError('--url must be an http(s) URL.');
+            }
+            const { client, credential } = await resolveClient();
+            const organizationId = organizationFor(options.organization, credential);
+            let response = options.file
+                ? await startFileImport({
+                    client,
+                    filePath: options.file,
+                    organizationId,
+                })
+                : await client.imports.create({
+                    sourceType: 'url',
+                    ...(organizationId ? { organizationId } : {}),
+                    url: options.url,
+                });
+            response = await maybeWait(client, response, options.wait);
+            if (!getGlobalOptions().json)
+                printSession(response.session);
+            return response;
+        });
+    });
+    imports
+        .command('list')
+        .description('List recent import sessions')
+        .option('--organization <id>', 'Organization id (OAuth user lane)')
+        .action(async (options) => {
+        await runCommand('import list', async () => {
+            const { client, credential } = await resolveClient();
+            const organizationId = organizationFor(options.organization, credential);
+            const response = await client.imports.list(organizationId);
+            if (!getGlobalOptions().json) {
+                logHeader(`Imports (${response.sessions.length})`);
+                if (response.sessions.length === 0)
+                    log(chalk.dim('  No imports.'));
+                else
+                    logTable(['Status', 'Source', 'Updated', 'Id'], response.sessions.map((session) => [
+                        session.status,
+                        session.sourceFilename ?? session.sourceUrl ?? '—',
+                        session.updatedAt,
+                        session.id,
+                    ]));
+            }
+            return response;
+        });
+    });
+    imports
+        .command('get <session-id>')
+        .description('Inspect an import session and its proposal')
+        .option('--wait', 'Poll until the proposal is ready or analysis fails')
+        .action(async (sessionId, options) => {
+        await runCommand('import get', async () => {
+            const { client } = await resolveClient();
+            let response = await client.imports.get(sessionId);
+            response = await maybeWait(client, response, options.wait);
+            if (!getGlobalOptions().json)
+                printSession(response.session);
+            return response;
+        });
+    });
+    imports
+        .command('decide <session-id>')
+        .description('Replace proposal decisions from a JSON object')
+        .requiredOption('--file <path|->', 'Decisions JSON file, or - for stdin')
+        .action(async (sessionId, options) => {
+        await runCommand('import decide', async () => {
+            const { client } = await resolveClient();
+            const response = await client.imports.updateDecisions(sessionId, decisionsFrom(options.file));
+            if (!getGlobalOptions().json) {
+                log(chalk.green('Import decisions saved.'));
+                printSession(response.session);
+            }
+            return response;
+        });
+    });
+    imports
+        .command('apply <session-id>')
+        .description('Apply a reviewed proposal into a new workspace')
+        .requiredOption('--workspace-name <name>', 'Name for the new workspace')
+        .option('--visibility <visibility>', 'global | restricted', 'global')
+        .option('--yes', 'Confirm without prompting (required when non-interactive)')
+        .action(async (sessionId, options) => {
+        await runCommand('import apply', async () => {
+            if (options.visibility !== 'global' &&
+                options.visibility !== 'restricted') {
+                throw new UsageError('--visibility must be global or restricted.');
+            }
+            const authorized = await authorizeMutation(`Apply import ${sessionId} and create workspace "${options.workspaceName}"?`, options.yes ?? false);
+            if (!authorized)
+                return { cancelled: true, sessionId };
+            const { client } = await resolveClient();
+            const response = await client.imports.apply(sessionId, {
+                workspaceName: options.workspaceName,
+                visibility: options.visibility,
+            });
+            if (!getGlobalOptions().json) {
+                log(chalk.green('Import applied.'));
+                printSession(response.session);
+            }
+            return response;
+        });
+    });
+    imports
+        .command('discard <session-id>')
+        .description('Discard an eligible import session')
+        .option('--yes', 'Confirm without prompting (required when non-interactive)')
+        .action(async (sessionId, options) => {
+        await runCommand('import discard', async () => {
+            const authorized = await authorizeMutation(`Discard import ${sessionId}?`, options.yes ?? false);
+            if (!authorized)
+                return { cancelled: true, sessionId };
+            const { client } = await resolveClient();
+            const response = await client.imports.discard(sessionId);
+            if (!getGlobalOptions().json)
+                log(chalk.green('Import discarded.'));
+            return response;
+        });
+    });
+    imports
+        .command('retry <session-id>')
+        .description('Retry a failed or stale import analysis')
+        .option('--wait', 'Poll until the proposal is ready or analysis fails')
+        .action(async (sessionId, options) => {
+        await runCommand('import retry', async () => {
+            const { client } = await resolveClient();
+            let response = await client.imports.retry(sessionId);
+            response = await maybeWait(client, response, options.wait);
+            if (!getGlobalOptions().json)
+                printSession(response.session);
+            return response;
+        });
+    });
+}

package/dist/lib/api/import-transfer.d.ts

@@ -0,0 +1,22 @@
+import type { ImportSessionResponse, SkhemaClient } from '@skhema/sdk';
+/** Resolve the backend-supported import MIME for a local file. */
+export declare function importMimeFor(filePath: string): string;
+/**
+ * Start a file import, stream the bytes to its signed URL, and confirm upload.
+ * The file is never buffered in memory.
+ */
+export declare function startFileImport(options: {
+    client: SkhemaClient;
+    filePath: string;
+    organizationId?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<ImportSessionResponse>;
+/** Poll the canonical session until it reaches a reviewable or terminal state. */
+export declare function waitForImport(options: {
+    client: SkhemaClient;
+    sessionId: string;
+    intervalMs?: number;
+    maxWaitMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<ImportSessionResponse>;
+//# sourceMappingURL=import-transfer.d.ts.map

package/dist/lib/api/import-transfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-transfer.d.ts","sourceRoot":"","sources":["../../../src/lib/api/import-transfer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAgBtE,kEAAkE;AAClE,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAStD;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE;IAC7C,MAAM,EAAE,YAAY,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;IAChB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA4CjC;AAUD,kFAAkF;AAClF,wBAAsB,aAAa,CAAC,OAAO,EAAE;IAC3C,MAAM,EAAE,YAAY,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtC,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAkBjC"}

package/dist/lib/api/import-transfer.js

@@ -0,0 +1,89 @@
+import fs from 'fs';
+import path from 'path';
+import { Readable } from 'stream';
+import { UsageError } from './run-command.js';
+const IMPORT_MIME_BY_EXTENSION = {
+    pdf: 'application/pdf',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    md: 'text/markdown',
+    txt: 'text/plain',
+    csv: 'text/csv',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    json: 'application/json',
+};
+/** Resolve the backend-supported import MIME for a local file. */
+export function importMimeFor(filePath) {
+    const extension = path.extname(filePath).slice(1).toLowerCase();
+    const mime = IMPORT_MIME_BY_EXTENSION[extension];
+    if (!mime) {
+        throw new UsageError('Unsupported import file. Use PDF, DOCX, Markdown, text, CSV, XLSX, or JSON.');
+    }
+    return mime;
+}
+/**
+ * Start a file import, stream the bytes to its signed URL, and confirm upload.
+ * The file is never buffered in memory.
+ */
+export async function startFileImport(options) {
+    let sizeBytes;
+    try {
+        const stat = fs.statSync(options.filePath);
+        if (!stat.isFile())
+            throw new Error('not a file');
+        sizeBytes = stat.size;
+    }
+    catch {
+        throw new UsageError(`Cannot read import file: ${options.filePath}`);
+    }
+    const filename = path.basename(options.filePath);
+    const mime = importMimeFor(filename);
+    const created = await options.client.imports.create({
+        sourceType: 'file',
+        ...(options.organizationId
+            ? { organizationId: options.organizationId }
+            : {}),
+        filename,
+        mime,
+        sizeBytes,
+    });
+    if (!created.uploadUrl) {
+        throw new Error('The import service did not return an upload URL.');
+    }
+    const response = await (options.fetchImpl ?? globalThis.fetch)(created.uploadUrl, {
+        method: 'PUT',
+        headers: {
+            'Content-Type': mime,
+            'Content-Length': String(sizeBytes),
+        },
+        body: Readable.toWeb(fs.createReadStream(options.filePath)),
+        duplex: 'half',
+    });
+    if (!response.ok) {
+        throw new Error(`Uploading import file failed (HTTP ${response.status}).`);
+    }
+    return options.client.imports.confirmUpload(created.session.id);
+}
+const TERMINAL_IMPORT_STATUSES = new Set([
+    'proposed',
+    'applied',
+    'partially_applied',
+    'failed',
+    'discarded',
+]);
+/** Poll the canonical session until it reaches a reviewable or terminal state. */
+export async function waitForImport(options) {
+    const intervalMs = options.intervalMs ?? 2000;
+    const maxWaitMs = options.maxWaitMs ?? 30 * 60000;
+    const sleep = options.sleep ??
+        ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const startedAt = Date.now();
+    while (true) {
+        const response = await options.client.imports.get(options.sessionId);
+        if (TERMINAL_IMPORT_STATUSES.has(response.session.status))
+            return response;
+        if (Date.now() - startedAt >= maxWaitMs) {
+            throw new Error(`Timed out waiting for import ${options.sessionId}; inspect it with "skhema import get ${options.sessionId}".`);
+        }
+        await sleep(intervalMs);
+    }
+}

package/dist/lib/auth/token-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-store.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/token-store.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAoFnD,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,iBAAiB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAuC9E;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAGtD;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAQ3C"}
+{"version":3,"file":"token-store.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/token-store.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAoFnD,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,iBAAiB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CA6D9E;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAGtD;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAQ3C"}

package/dist/lib/auth/token-store.js

@@ -90,28 +90,51 @@ export async function getStoredCredentials() {
         const credentials = JSON.parse(data);
         // Auto-refresh if within buffer of expiry
         if (credentials.expires_at - Date.now() < TOKEN_REFRESH_BUFFER) {
+            let newTokens;
+            try {
+                newTokens = await refreshAccessToken(credentials.refresh_token);
+            }
+            catch {
+                // Refresh failed. If the access token is still valid (refresh was just
+                // the pre-expiry buffer, e.g. a network blip), the credentials remain
+                // usable. If it has ALREADY expired, the session is dead (refresh
+                // tokens live 7 days) — returning it would present an unusable bearer
+                // downstream as a "valid session" and surface as a bare 401 far from
+                // the cause. Treat as unauthenticated instead.
+                if (credentials.expires_at > Date.now()) {
+                    return credentials;
+                }
+                return null;
+            }
+            // Refresh succeeded — the session is alive. Nothing past this point is
+            // allowed to discard it: userinfo is cosmetic (keep the prior identity
+            // on failure) and a persist failure still leaves the tokens usable for
+            // this invocation.
+            const refreshed = {
+                ...credentials,
+                access_token: newTokens.access_token,
+                refresh_token: newTokens.refresh_token,
+                expires_at: Date.now() + newTokens.expires_in * 1000,
+                scope: newTokens.scope,
+            };
             try {
-                const newTokens = await refreshAccessToken(credentials.refresh_token);
                 const userInfo = await fetchUserInfo(newTokens.access_token);
-                const refreshed = {
-                    ...credentials,
-                    access_token: newTokens.access_token,
-                    refresh_token: newTokens.refresh_token,
-                    expires_at: Date.now() + newTokens.expires_in * 1000,
-                    scope: newTokens.scope,
-                    user: {
-                        id: userInfo.sub,
-                        email: userInfo.email,
-                        name: userInfo.name,
-                    },
+                refreshed.user = {
+                    id: userInfo.sub,
+                    email: userInfo.email,
+                    name: userInfo.name,
                 };
+            }
+            catch {
+                /* keep the previously stored user */
+            }
+            try {
                 await storeCredentials(refreshed);
-                return refreshed;
             }
             catch {
-                // Refresh failed - return stale credentials, caller can handle
-                return credentials;
+                /* still return the in-memory refreshed session */
             }
+            return refreshed;
         }
         return credentials;
     }

package/dist/program.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../src/program.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAoBnC;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAgDrD"}
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../src/program.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAqBnC;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAiDrD"}

package/dist/program.js

@@ -7,6 +7,7 @@ import { registerContributeCommands } from './commands/contribute.js';
 import { registerDocumentCommands } from './commands/document.js';
 import { registerElementCommands } from './commands/element.js';
 import { registerWorkspaceExportCommand } from './commands/export.js';
+import { registerImportCommands } from './commands/import.js';
 import { registerInitCommand } from './commands/init.js';
 import { registerLinkCommands } from './commands/link.js';
 import { registerResourceCommands } from './commands/resource.js';
@@ -47,6 +48,7 @@ export function buildProgram(version) {
         program.help();
     });
     registerInitCommand(program);
+    registerImportCommands(program);
     registerAuthCommands(program);
     registerWorkspaceCommands(program);
     registerElementCommands(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skhema/cli",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Skhema CLI - Authentication and AI skills management for agent platforms",
   "type": "module",
   "main": "dist/index.js",
@@ -43,14 +43,14 @@
   "dependencies": {
     "@skhema/agent-sdk": "0.1.4",
     "@skhema/method": "0.3.0",
-    "@skhema/sdk": "0.2.2",
+    "@skhema/sdk": "0.2.3",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "ora": "^8.0.0"
   },
   "devDependencies": {
     "@mdx-js/mdx": "3.1.1",
-    "@skhema/linter": "2.2.0",
+    "@skhema/linter": "2.3.0",
     "@skhema/prettier-config": "1.0.0",
     "@types/node": "^22.0.0",
     "eslint": "^9.0.0",