@spekn/cli 1.0.0

package/dist/export.d.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { CredentialsStore } from './auth/credentials-store';
+type ExportFormat = 'agents-md' | 'claude-md' | 'cursorrules' | 'gemini-md';
+type ExportMode = 'global' | 'scoped';
+type ExportDeliveryMode = 'download' | 'copy' | 'commit' | 'pr';
+type ExportCommand = 'generate' | 'status' | 'discover' | 'preview';
+interface CLIOptions {
+    command: ExportCommand;
+    projectId?: string;
+    format?: ExportFormat;
+    output?: string;
+    anchors?: string[];
+    mode: ExportMode;
+    scope?: string;
+    delivery: ExportDeliveryMode;
+    json: boolean;
+    branch?: string;
+    baseBranch?: string;
+    commitMessage?: string;
+    prTitle?: string;
+    prBody?: string;
+    apiUrl: string;
+}
+interface Deps {
+    createClient: (apiUrl: string, organizationId: string, authToken?: string) => any;
+    writeFile: (filePath: string, content: string) => void;
+    stdout: (content: string) => void;
+    stderr: (content: string) => void;
+    credentialsStore: CredentialsStore;
+}
+declare function normalizeTrpcUrl(apiUrl: string): string;
+declare function parseArgs(args: string[]): CLIOptions;
+export declare function runExportCli(args: string[], deps?: Deps): Promise<number>;
+declare function main(): Promise<void>;
+export { main, parseArgs, normalizeTrpcUrl };

package/dist/export.js

@@ -0,0 +1,485 @@
+#!/usr/bin/env node
+"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.runExportCli = runExportCli;
+exports.main = main;
+exports.parseArgs = parseArgs;
+exports.normalizeTrpcUrl = normalizeTrpcUrl;
+const client_1 = require("@trpc/client");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const credentials_store_1 = require("./auth/credentials-store");
+const project_context_1 = require("./project-context");
+const structured_log_1 = require("./utils/structured-log");
+const defaultDeps = {
+    createClient: (apiUrl, organizationId, authToken) => (0, client_1.createTRPCProxyClient)({
+        links: [
+            (0, client_1.httpBatchLink)({
+                url: normalizeTrpcUrl(apiUrl),
+                headers: {
+                    'x-organization-id': organizationId,
+                    authorization: authToken ? `Bearer ${authToken}` : '',
+                },
+            }),
+        ],
+    }),
+    writeFile: (filePath, content) => {
+        const dir = path.dirname(filePath);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(filePath, content, 'utf-8');
+    },
+    stdout: (content) => process.stdout.write(content),
+    stderr: (content) => process.stderr.write(content),
+    credentialsStore: new credentials_store_1.CredentialsStore(),
+};
+function normalizeTrpcUrl(apiUrl) {
+    if (apiUrl.endsWith('/trpc')) {
+        return apiUrl;
+    }
+    if (apiUrl.endsWith('/')) {
+        return `${apiUrl}trpc`;
+    }
+    return `${apiUrl}/trpc`;
+}
+function printHelp(stderr) {
+    stderr(`
+export - Generate and deliver agent context exports
+
+USAGE:
+  spekn export discover --project <uuid> [options]
+  spekn export preview --project <uuid> --format <agents-md|claude-md|cursorrules|gemini-md> [options]
+  spekn export --project <uuid> --format <agents-md|claude-md|cursorrules|gemini-md> [options]
+  spekn export status --project <uuid> --format <agents-md|claude-md|cursorrules|gemini-md> [options]
+
+OPTIONS:
+  --project <uuid>      Project ID (optional if .spekn/context is present)
+  --format <format>     Export format: agents-md | claude-md | cursorrules | gemini-md (required)
+  --output <path>       Write output to file (generate-only backward-compat mode)
+  --anchors <a,b,c>     Comma-separated anchor list
+  --mode <mode>         Export mode: global | scoped (default: global)
+  --scope <path>        Scope folder path when mode=scoped
+  --delivery <mode>     Delivery: download | copy | commit | pr (default: download)
+  --branch <name>       Target branch for commit/pr delivery
+  --base-branch <name>  Base branch for branch creation
+  --commit-message <m>  Commit message override
+  --pr-title <title>    PR title (delivery=pr)
+  --pr-body <body>      PR body (delivery=pr)
+  --json                Output machine-readable JSON
+  --api-url <url>       API base URL (default: SPEKN_API_URL or https://app.spekn.com)
+  --help                Show help
+`);
+}
+function parseArgs(args) {
+    const command = args[0] === 'status' ? 'status' : args[0] === 'discover' ? 'discover' : args[0] === 'preview' ? 'preview' : 'generate';
+    const parseArgs = command === 'generate' ? args : args.slice(1);
+    let projectId = '';
+    let format = '';
+    let output;
+    let anchors;
+    let mode = 'global';
+    let scope;
+    let delivery = 'download';
+    let json = false;
+    let branch;
+    let baseBranch;
+    let commitMessage;
+    let prTitle;
+    let prBody;
+    let apiUrl = process.env.SPEKN_API_URL || 'https://app.spekn.com';
+    for (let index = 0; index < parseArgs.length; index++) {
+        const arg = parseArgs[index];
+        if (arg === '--help' || arg === '-h') {
+            throw new Error('__HELP__');
+        }
+        if (arg === '--json') {
+            json = true;
+            continue;
+        }
+        if (arg === '--project' && parseArgs[index + 1]) {
+            projectId = parseArgs[++index];
+            continue;
+        }
+        if (arg.startsWith('--project=')) {
+            projectId = arg.slice('--project='.length);
+            continue;
+        }
+        if (arg === '--format' && parseArgs[index + 1]) {
+            format = parseArgs[++index];
+            continue;
+        }
+        if (arg.startsWith('--format=')) {
+            format = arg.slice('--format='.length);
+            continue;
+        }
+        if (arg === '--output' && parseArgs[index + 1]) {
+            output = parseArgs[++index];
+            continue;
+        }
+        if (arg.startsWith('--output=')) {
+            output = arg.slice('--output='.length);
+            continue;
+        }
+        if (arg === '--anchors' && parseArgs[index + 1]) {
+            anchors = parseArgs[++index]
+                .split(',')
+                .map((entry) => entry.trim())
+                .filter(Boolean);
+            continue;
+        }
+        if (arg.startsWith('--anchors=')) {
+            anchors = arg
+                .slice('--anchors='.length)
+                .split(',')
+                .map((entry) => entry.trim())
+                .filter(Boolean);
+            continue;
+        }
+        if (arg === '--mode' && parseArgs[index + 1]) {
+            mode = parseArgs[++index];
+            continue;
+        }
+        if (arg.startsWith('--mode=')) {
+            mode = arg.slice('--mode='.length);
+            continue;
+        }
+        if (arg === '--scope' && parseArgs[index + 1]) {
+            scope = parseArgs[++index];
+            continue;
+        }
+        if (arg.startsWith('--scope=')) {
+            scope = arg.slice('--scope='.length);
+            continue;
+        }
+        if (arg === '--delivery' && parseArgs[index + 1]) {
+            delivery = parseArgs[++index];
+            continue;
+        }
+        if (arg.startsWith('--delivery=')) {
+            delivery = arg.slice('--delivery='.length);
+            continue;
+        }
+        if (arg === '--branch' && parseArgs[index + 1]) {
+            branch = parseArgs[++index];
+            continue;
+        }
+        if (arg.startsWith('--branch=')) {
+            branch = arg.slice('--branch='.length);
+            continue;
+        }
+        if (arg === '--base-branch' && parseArgs[index + 1]) {
+            baseBranch = parseArgs[++index];
+            continue;
+        }
+        if (arg.startsWith('--base-branch=')) {
+            baseBranch = arg.slice('--base-branch='.length);
+            continue;
+        }
+        if (arg === '--commit-message' && parseArgs[index + 1]) {
+            commitMessage = parseArgs[++index];
+            continue;
+        }
+        if (arg.startsWith('--commit-message=')) {
+            commitMessage = arg.slice('--commit-message='.length);
+            continue;
+        }
+        if (arg === '--pr-title' && parseArgs[index + 1]) {
+            prTitle = parseArgs[++index];
+            continue;
+        }
+        if (arg.startsWith('--pr-title=')) {
+            prTitle = arg.slice('--pr-title='.length);
+            continue;
+        }
+        if (arg === '--pr-body' && parseArgs[index + 1]) {
+            prBody = parseArgs[++index];
+            continue;
+        }
+        if (arg.startsWith('--pr-body=')) {
+            prBody = arg.slice('--pr-body='.length);
+            continue;
+        }
+        if (arg === '--api-url' && parseArgs[index + 1]) {
+            apiUrl = parseArgs[++index];
+            continue;
+        }
+        if (arg.startsWith('--api-url=')) {
+            apiUrl = arg.slice('--api-url='.length);
+            continue;
+        }
+    }
+    if (command !== 'discover' && !['agents-md', 'claude-md', 'cursorrules', 'gemini-md'].includes(format)) {
+        throw new Error('Missing or invalid --format. Allowed values: agents-md, claude-md, cursorrules, gemini-md');
+    }
+    if (!['global', 'scoped'].includes(mode)) {
+        throw new Error('Invalid --mode. Allowed values: global, scoped');
+    }
+    if (mode === 'scoped' && !scope) {
+        throw new Error('Missing --scope when --mode=scoped');
+    }
+    if (!['download', 'copy', 'commit', 'pr'].includes(delivery)) {
+        throw new Error('Invalid --delivery. Allowed values: download, copy, commit, pr');
+    }
+    return {
+        command,
+        projectId,
+        format: format,
+        output,
+        anchors,
+        mode,
+        scope,
+        delivery,
+        json,
+        branch,
+        baseBranch,
+        commitMessage,
+        prTitle,
+        prBody,
+        apiUrl,
+    };
+}
+async function runExportCli(args, deps = defaultDeps) {
+    try {
+        const options = parseArgs(args);
+        const emit = (payload) => {
+            deps.stdout(`${JSON.stringify(payload, null, 2)}\n`);
+        };
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: 'cli.export',
+            level: 'info',
+            message: `Starting export ${options.command}`,
+            details: {
+                format: options.format,
+                mode: options.mode,
+                delivery: options.delivery,
+                output: options.output,
+                apiUrl: options.apiUrl,
+            },
+        });
+        const storedToken = await deps.credentialsStore.getValidToken();
+        const authToken = storedToken ?? process.env.SPEKN_AUTH_TOKEN;
+        const storedCreds = deps.credentialsStore.load();
+        const context = (0, project_context_1.resolveProjectContext)({
+            explicitProjectId: options.projectId,
+            repoPath: process.cwd(),
+            credentialsOrganizationId: storedCreds?.organizationId,
+            envOrganizationId: process.env.SPEKN_ORGANIZATION_ID,
+        });
+        const client = deps.createClient(options.apiUrl, context.organizationId, authToken ?? undefined);
+        if (options.command === 'discover') {
+            const result = await client.export.discover.query({
+                projectId: context.projectId,
+            });
+            if (options.json) {
+                emit(result);
+            }
+            else {
+                deps.stdout(`Plan: ${result.plan}\n`);
+                deps.stdout(`Modes: ${result.modes.join(', ')}\n`);
+                deps.stdout('Formats:\n');
+                for (const format of result.formats) {
+                    deps.stdout(`- ${format.id} (${format.filename})\n`);
+                }
+                deps.stdout('Delivery:\n');
+                for (const delivery of result.delivery) {
+                    deps.stdout(`- ${delivery.mode}: ${delivery.available ? 'available' : `unavailable (${delivery.reason})`}\n`);
+                }
+            }
+            return 0;
+        }
+        if (options.command === 'preview') {
+            const result = await client.export.preview.query({
+                projectId: context.projectId,
+                formatId: options.format,
+                anchorFilter: options.anchors,
+                mode: options.mode,
+                scopePath: options.scope,
+            });
+            if (options.json) {
+                emit(result);
+            }
+            else {
+                deps.stdout(result.content);
+                deps.stdout('\n');
+            }
+            return 0;
+        }
+        if (options.command === 'status') {
+            const result = await client.export.delivery.status.query({
+                projectId: context.projectId,
+                formatId: options.format,
+                mode: options.mode,
+                scopePath: options.scope,
+                anchorFilter: options.anchors,
+            });
+            if (options.json) {
+                emit(result);
+            }
+            else {
+                deps.stdout(`Status: ${result.overall}\n`);
+                for (const target of result.targets) {
+                    deps.stdout(`- ${target.path} [${target.kind}] -> ${target.status}\n`);
+                }
+            }
+            return 0;
+        }
+        // Backward-compatible single output mode.
+        if (options.output && options.delivery === 'download') {
+            const result = await client.export.generate.mutate({
+                projectId: context.projectId,
+                formatId: options.format,
+                anchorFilter: options.anchors,
+                mode: options.mode,
+                scopePath: options.scope,
+            });
+            const resolvedPath = path.resolve(process.cwd(), options.output);
+            deps.writeFile(resolvedPath, result.content);
+            if (options.json) {
+                emit({
+                    delivery: 'download',
+                    targets: [{ path: resolvedPath, kind: 'entrypoint' }],
+                    anchorCount: result.anchorCount,
+                    specVersion: result.specVersion,
+                    warnings: result.warnings ?? [],
+                });
+            }
+            else {
+                deps.stdout(`Exported ${result.anchorCount} anchors to ${resolvedPath}\n`);
+            }
+            return 0;
+        }
+        if (options.delivery === 'commit') {
+            const result = await client.export.delivery.commit.mutate({
+                projectId: context.projectId,
+                formatId: options.format,
+                mode: options.mode,
+                scopePath: options.scope,
+                branch: options.branch,
+                baseBranch: options.baseBranch,
+                commitMessage: options.commitMessage,
+                anchorFilter: options.anchors,
+            });
+            if (options.json) {
+                emit(result);
+            }
+            else {
+                deps.stdout(`Committed to ${result.branch}: ${result.commitSha}\n`);
+                for (const fileUrl of result.fileUrls || [])
+                    deps.stdout(`- ${fileUrl}\n`);
+            }
+            return 0;
+        }
+        if (options.delivery === 'pr') {
+            const result = await client.export.delivery.createPr.mutate({
+                projectId: context.projectId,
+                formatId: options.format,
+                mode: options.mode,
+                scopePath: options.scope,
+                branch: options.branch,
+                baseBranch: options.baseBranch,
+                commitMessage: options.commitMessage,
+                prTitle: options.prTitle,
+                prBody: options.prBody,
+                anchorFilter: options.anchors,
+            });
+            if (options.json) {
+                emit(result);
+            }
+            else {
+                deps.stdout(`PR #${result.prNumber}: ${result.prUrl}\n`);
+                deps.stdout(`Commit: ${result.commitSha} on ${result.branch}\n`);
+            }
+            return 0;
+        }
+        const plan = await client.export.delivery.previewTarget.query({
+            projectId: context.projectId,
+            formatId: options.format,
+            mode: options.mode,
+            scopePath: options.scope,
+            anchorFilter: options.anchors,
+        });
+        if (options.delivery === 'copy') {
+            if (options.json) {
+                emit(plan);
+            }
+            else {
+                for (const target of plan.targets) {
+                    deps.stdout(`\n### ${target.path}\n\n`);
+                    deps.stdout(target.content);
+                    deps.stdout('\n');
+                }
+            }
+            return 0;
+        }
+        const writtenTargets = [];
+        for (const target of plan.targets) {
+            const resolvedPath = path.resolve(process.cwd(), target.path);
+            deps.writeFile(resolvedPath, target.content);
+            writtenTargets.push({ path: resolvedPath, kind: target.kind });
+            if (!options.json) {
+                deps.stdout(`Wrote ${target.kind} -> ${resolvedPath}\n`);
+            }
+        }
+        if (options.json) {
+            emit({ delivery: 'download', targets: writtenTargets, warnings: plan.warnings ?? [] });
+        }
+        else if (plan.warnings?.length) {
+            for (const warning of plan.warnings)
+                deps.stdout(`Warning: ${warning}\n`);
+        }
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === '__HELP__') {
+            printHelp(deps.stderr);
+            return 0;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        deps.stderr(`Error: ${message}\n`);
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: 'cli.export',
+            level: 'error',
+            message,
+        });
+        return 1;
+    }
+}
+async function main() {
+    const exitCode = await runExportCli(process.argv.slice(2));
+    process.exit(exitCode);
+}
+if (require.main === module) {
+    void main();
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * spekn - CLI tools for SDD platform
+ *
+ * This package provides command-line tools for working with specifications and backlog management.
+ */
+export { main as specParse } from "./commands/spec/parse";
+export { main as specLint } from "./commands/spec/lint";
+export { main as backlogGenerate } from "./commands/backlog/generate";
+export { main as backlogHealth } from "./commands/backlog/health";
+export { main as specDriftCheck } from "./commands/spec/drift-check";
+export { runExportCli as exportContext } from "./commands/export";

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * spekn - CLI tools for SDD platform
+ *
+ * This package provides command-line tools for working with specifications and backlog management.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportContext = exports.specDriftCheck = exports.backlogHealth = exports.backlogGenerate = exports.specLint = exports.specParse = void 0;
+var parse_1 = require("./commands/spec/parse");
+Object.defineProperty(exports, "specParse", { enumerable: true, get: function () { return parse_1.main; } });
+var lint_1 = require("./commands/spec/lint");
+Object.defineProperty(exports, "specLint", { enumerable: true, get: function () { return lint_1.main; } });
+var generate_1 = require("./commands/backlog/generate");
+Object.defineProperty(exports, "backlogGenerate", { enumerable: true, get: function () { return generate_1.main; } });
+var health_1 = require("./commands/backlog/health");
+Object.defineProperty(exports, "backlogHealth", { enumerable: true, get: function () { return health_1.main; } });
+var drift_check_1 = require("./commands/spec/drift-check");
+Object.defineProperty(exports, "specDriftCheck", { enumerable: true, get: function () { return drift_check_1.main; } });
+var export_1 = require("./commands/export");
+Object.defineProperty(exports, "exportContext", { enumerable: true, get: function () { return export_1.runExportCli; } });
+// TUI is ESM-only (ink v5) — use `spekn tui` or import the .mjs bundle directly

package/dist/main.d.ts

@@ -0,0 +1 @@
+export {};