@spekn/cli 1.0.0

package/dist/commands/repo/detach.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function runRepoDetachCli(args: string[]): Promise<number>;

package/dist/commands/repo/detach.js

@@ -0,0 +1,120 @@
+#!/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.runRepoDetachCli = runRepoDetachCli;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const project_context_1 = require("../../project-context");
+function printHelp(stderr) {
+    stderr(`
+repo detach - Detach the current repository from local Spekn project context
+
+USAGE:
+  spekn repo detach [options]
+
+OPTIONS:
+  --path <dir>   Repository root path (default: current directory)
+  --help         Show this help message
+
+EXAMPLES:
+  spekn repo detach
+  spekn repo detach --path /path/to/repo
+`);
+}
+function parseArgs(args) {
+    let repoPath = process.cwd();
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--help') {
+            throw new Error('HELP_REQUESTED');
+        }
+        if (arg === '--path' && args[index + 1]) {
+            repoPath = path.resolve(args[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg?.startsWith('--path=')) {
+            repoPath = path.resolve(arg.slice('--path='.length));
+        }
+    }
+    return { repoPath };
+}
+async function runRepoDetachCli(args) {
+    try {
+        const options = parseArgs(args);
+        const localContextPath = path.join(options.repoPath, '.spekn');
+        const localContext = (0, project_context_1.loadLocalContext)(options.repoPath);
+        const globalCleanup = (0, project_context_1.clearRepoFromGlobalContext)(options.repoPath, localContext?.projectId);
+        const hasLocalContext = fs.existsSync(localContextPath);
+        if (hasLocalContext) {
+            fs.unlinkSync(localContextPath);
+            process.stdout.write(`Detached repository context (${localContextPath}).\n`);
+        }
+        else {
+            process.stdout.write('No local .spekn context file found.\n');
+        }
+        if (globalCleanup.removedProjectRefs > 0 ||
+            globalCleanup.removedSyncCheckpoints > 0 ||
+            globalCleanup.removedProjects > 0 ||
+            globalCleanup.clearedLastUsedProjectId) {
+            process.stdout.write(`Cleared global repo context references: ` +
+                `${globalCleanup.removedProjectRefs} project path(s), ` +
+                `${globalCleanup.removedSyncCheckpoints} sync checkpoint(s), ` +
+                `${globalCleanup.removedProjects} project record(s)` +
+                `${globalCleanup.clearedLastUsedProjectId ? ', lastUsedProjectId cleared' : ''}.\n`);
+        }
+        else {
+            process.stdout.write('No global repo context references found.\n');
+        }
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message === 'HELP_REQUESTED') {
+            printHelp(process.stderr.write.bind(process.stderr));
+            return 0;
+        }
+        process.stderr.write(`Error: ${message}\n`);
+        return 1;
+    }
+}
+async function main() {
+    const exitCode = await runRepoDetachCli(process.argv.slice(2));
+    process.exit(exitCode);
+}
+if (require.main === module) {
+    void main();
+}

package/dist/commands/repo/register.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * repo-register CLI command
+ *
+ * Registers the current git repository with a Spekn project and optionally
+ * runs AI-powered analysis to discover specs, assess governance, and create
+ * improvement specifications.
+ *
+ * Usage: spekn repo register --project-id <uuid> [--primary] [--analyze] [--no-analyze]
+ *        [--agent <name>] [--path <dir>] [--dry-run] [--api-url <url>]
+ */
+import { type CommonOptions, type Deps } from "./common";
+export { repoNameFromUrl, resolveDefaultBranch, discoverFiles, buildAnalysisPrompt, executeAcpSession, runAnalysisWithAgent, verifyMcpServer, } from "./common";
+export type { DiscoveredFile } from "./common";
+interface RegisterOptions extends CommonOptions {
+    primary: boolean;
+}
+declare function parseArgs(args: string[]): RegisterOptions;
+export declare function runRepoRegisterCli(args: string[], deps?: Deps): Promise<number>;
+declare function main(): Promise<void>;
+export { main, parseArgs };

package/dist/commands/repo/register.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * repo-register CLI command
+ *
+ * Registers the current git repository with a Spekn project and optionally
+ * runs AI-powered analysis to discover specs, assess governance, and create
+ * improvement specifications.
+ *
+ * Usage: spekn repo register --project-id <uuid> [--primary] [--analyze] [--no-analyze]
+ *        [--agent <name>] [--path <dir>] [--dry-run] [--api-url <url>]
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyMcpServer = exports.runAnalysisWithAgent = exports.executeAcpSession = exports.buildAnalysisPrompt = exports.discoverFiles = exports.resolveDefaultBranch = exports.repoNameFromUrl = void 0;
+exports.runRepoRegisterCli = runRepoRegisterCli;
+exports.main = main;
+exports.parseArgs = parseArgs;
+const common_1 = require("./common");
+const project_context_1 = require("../../project-context");
+const structured_log_1 = require("../../utils/structured-log");
+// Re-export shared utilities for backward compatibility
+var common_2 = require("./common");
+Object.defineProperty(exports, "repoNameFromUrl", { enumerable: true, get: function () { return common_2.repoNameFromUrl; } });
+Object.defineProperty(exports, "resolveDefaultBranch", { enumerable: true, get: function () { return common_2.resolveDefaultBranch; } });
+Object.defineProperty(exports, "discoverFiles", { enumerable: true, get: function () { return common_2.discoverFiles; } });
+Object.defineProperty(exports, "buildAnalysisPrompt", { enumerable: true, get: function () { return common_2.buildAnalysisPrompt; } });
+Object.defineProperty(exports, "executeAcpSession", { enumerable: true, get: function () { return common_2.executeAcpSession; } });
+Object.defineProperty(exports, "runAnalysisWithAgent", { enumerable: true, get: function () { return common_2.runAnalysisWithAgent; } });
+Object.defineProperty(exports, "verifyMcpServer", { enumerable: true, get: function () { return common_2.verifyMcpServer; } });
+// ── Help & Args ─────────────────────────────────────────────────────
+function printHelp(stderr) {
+    stderr(`
+repo register - Register the current git repository with a Spekn project
+
+USAGE:
+  spekn repo register --project-id <uuid> [options]
+
+OPTIONS:
+  --project-id <uuid>   Project ID to register the repo under (optional if .spekn/context is present)
+  --primary             Set this repository as the primary repo for the project
+  --analyze             Run AI analysis after registration (default: true)
+  --no-analyze          Skip AI analysis (metadata-only registration)
+  --agent <name>        Force a specific agent (claude, codex, opencode, etc.)
+  --path <dir>          Repository root path (default: current directory)
+  --dry-run             Discover files only, skip AI analysis
+  --api-url <url>       API base URL (default: SPEKN_API_URL or https://app.spekn.com)
+  --mcp-url <url>       MCP HTTP server URL (default: MCP_HTTP_URL or https://app.spekn.com/mcp)
+  --debug               Show detailed debug output (tokens, HTTP exchanges)
+  --help                Show this help message
+
+ENVIRONMENT:
+  SPEKN_API_URL         API base URL
+  SPEKN_AUTH_TOKEN      Bearer token for authentication
+  SPEKN_ORGANIZATION_ID Organization ID header
+  MCP_HTTP_URL          MCP HTTP server URL (default: https://app.spekn.com/mcp)
+  AGENT_ARGS            Override agent CLI args (skips ACP registry resolution)
+
+EXAMPLES:
+  spekn repo register --project-id 11111111-1111-4111-8111-111111111111
+  spekn repo register --project-id 11111111-1111-4111-8111-111111111111 --primary
+  spekn repo register --project-id 11111111-1111-4111-8111-111111111111 --no-analyze
+  spekn repo register --project-id 11111111-1111-4111-8111-111111111111 --dry-run
+  spekn repo register --project-id 11111111-1111-4111-8111-111111111111 --agent claude
+  spekn repo register --project-id 11111111-1111-4111-8111-111111111111 --path /path/to/repo
+`);
+}
+function parseArgs(args) {
+    const opts = { ...(0, common_1.commonDefaults)(true), primary: false };
+    for (let i = 0; i < args.length;) {
+        const consumed = (0, common_1.parseCommonFlag)(args, i, opts);
+        if (consumed > 0) {
+            i += consumed;
+            continue;
+        }
+        if (args[i] === "--primary") {
+            opts.primary = true;
+            i++;
+            continue;
+        }
+        i++; // skip unknown
+    }
+    return (0, common_1.finalizeOptions)(opts);
+}
+// ── Main ────────────────────────────────────────────────────────────
+async function runRepoRegisterCli(args, deps = common_1.defaultDeps) {
+    try {
+        const options = parseArgs(args);
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.repo.register",
+            level: "info",
+            message: "Starting repo register",
+            details: { repoPath: options.repoPath, analyze: options.analyze, apiUrl: options.apiUrl },
+        });
+        const { authToken, organizationId, projectId } = await (0, common_1.resolveAuth)(deps, {
+            projectId: options.projectId,
+            repoPath: options.repoPath,
+        });
+        // ── Phase 1: Register repository metadata ──────────────────────
+        const git = (0, common_1.readGitMetadata)(options.repoPath, deps);
+        if (!git)
+            return 1;
+        deps.stdout(`Registering repository "${git.name}" (${git.remoteUrl})\n`);
+        deps.stdout(`  Default branch : ${git.defaultBranch}\n`);
+        deps.stdout(`  Project        : ${projectId}\n`);
+        if (options.primary)
+            deps.stdout("  Primary        : yes\n");
+        const client = (0, common_1.createApiClient)(options.apiUrl, authToken, organizationId);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const result = await client.gitRepository.create.mutate({
+            projectId,
+            name: git.name,
+            repositoryUrl: git.remoteUrl,
+            defaultBranch: git.defaultBranch,
+            isPrimary: options.primary,
+        });
+        deps.stdout(`Repository registered successfully. ID: ${result.id}\n`);
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.repo.register",
+            level: "info",
+            message: "Repository metadata registered",
+            details: { projectId, organizationId, repositoryId: result.id },
+        });
+        (0, project_context_1.persistProjectContext)(options.repoPath, { projectId, organizationId: organizationId || undefined });
+        (0, project_context_1.ensureGitignoreHasSpekn)(options.repoPath);
+        // ── Phase 2: AI analysis (optional) ─────────────────────────────
+        if (!options.analyze)
+            return 0;
+        if (!organizationId) {
+            deps.stderr("Warning: No organization ID. Skipping AI analysis. Re-run 'spekn auth login' or set SPEKN_ORGANIZATION_ID.\n");
+            return 0;
+        }
+        const exitCode = await (0, common_1.runAnalysisPhase)({ ...options, projectId }, authToken ?? "", deps, organizationId);
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.repo.register",
+            level: exitCode === 0 ? "info" : "error",
+            message: "Repo register completed",
+            details: { exitCode, analyzed: options.analyze, projectId },
+        });
+        return exitCode;
+    }
+    catch (error) {
+        if (error instanceof common_1.HelpRequestedError) {
+            printHelp(deps.stderr);
+            return 0;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        deps.stderr(`Error: ${message}\n`);
+        // Provide specific guidance for common errors
+        if (message.includes('organization') || message.includes('Organization')) {
+            deps.stderr(`\n`);
+            deps.stderr(`Organization context is required. Try one of:\n`);
+            deps.stderr(`  1. Run 'spekn auth login' to authenticate and select an organization\n`);
+            deps.stderr(`  2. Set SPEKN_ORGANIZATION_ID environment variable\n`);
+            deps.stderr(`  3. Pass --organization-id explicitly (if supported)\n`);
+        }
+        else if (message.includes('credentials') || message.includes('auth') || message.includes('token')) {
+            deps.stderr(`\n`);
+            deps.stderr(`Authentication required. Run:\n`);
+            deps.stderr(`  spekn auth login\n`);
+        }
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.repo.register",
+            level: "error",
+            message: message,
+        });
+        return 1;
+    }
+}
+async function main() {
+    const exitCode = await runRepoRegisterCli(process.argv.slice(2));
+    process.exit(exitCode);
+}
+if (require.main === module) {
+    void main();
+}

package/dist/commands/repo/sync.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * repo-sync CLI command
+ *
+ * Syncs metadata for the current git repository with Spekn.
+ * Looks up the repo by its remote URL and updates name and default branch.
+ * By default, also runs ingestion drift analysis against project spec storage.
+ * Must be run from inside a local git clone.
+ *
+ * Usage: spekn repo sync --project-id <uuid> [--analyze|--no-analyze] [--import-to-project] [--api-url <url>]
+ */
+import { type CommonOptions, type Deps } from "./common";
+interface SyncOptions extends CommonOptions {
+    importToProject: boolean;
+    maxFiles: number;
+    analysisEngine: "ingestion" | "acp" | "both";
+    acpTimeoutMs?: number;
+}
+declare function parseArgs(args: string[]): SyncOptions;
+export declare function runRepoSyncCli(args: string[], deps?: Deps): Promise<number>;
+declare function main(): Promise<void>;
+export { main, parseArgs };