@spekn/cli 1.0.0

package/dist/repo-detach.js

@@ -0,0 +1,102 @@
+#!/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"));
+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');
+        if (!fs.existsSync(localContextPath)) {
+            process.stdout.write('No local .spekn context file found. Nothing to detach.\n');
+            return 0;
+        }
+        fs.unlinkSync(localContextPath);
+        process.stdout.write(`Detached repository context (${localContextPath}).\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/repo-ingest.d.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * repo ingest CLI command
+ *
+ * Scans the current (or specified) git repository for governance files
+ * (CLAUDE.md, AGENTS.md, .cursorrules, specs/*.md, etc.) and ingests
+ * them into a Spekn project via the ingestion API.
+ *
+ * Usage: spekn repo ingest --project-id <uuid> [--path <dir>] [--dry-run] [--api-url <url>]
+ */
+import { CredentialsStore } from "./auth/credentials-store";
+interface CLIOptions {
+    projectId: string;
+    repoPath: string;
+    dryRun: boolean;
+    apiUrl: string;
+}
+interface Deps {
+    stdout: (content: string) => void;
+    stderr: (content: string) => void;
+    credentialsStore: CredentialsStore;
+    readFile: (filePath: string) => string;
+    fileExists: (filePath: string) => boolean;
+    readDir: (dirPath: string) => string[];
+}
+declare function parseArgs(args: string[]): CLIOptions;
+export declare function runRepoIngestCli(args: string[], deps?: Deps): Promise<number>;
+declare function main(): Promise<void>;
+export { main, parseArgs };

package/dist/repo-ingest.js

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * repo ingest CLI command
+ *
+ * Scans the current (or specified) git repository for governance files
+ * (CLAUDE.md, AGENTS.md, .cursorrules, specs/*.md, etc.) and ingests
+ * them into a Spekn project via the ingestion API.
+ *
+ * Usage: spekn repo ingest --project-id <uuid> [--path <dir>] [--dry-run] [--api-url <url>]
+ */
+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.runRepoIngestCli = runRepoIngestCli;
+exports.main = main;
+exports.parseArgs = parseArgs;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const client_1 = require("@trpc/client");
+const credentials_store_1 = require("./auth/credentials-store");
+const trpc_url_1 = require("./utils/trpc-url");
+const help_error_1 = require("./utils/help-error");
+// ── Governance file patterns ────────────────────────────────────────
+/** Well-known governance files to look for at the repo root. */
+const ROOT_FILES = [
+    "CLAUDE.md",
+    ".claude/CLAUDE.md",
+    "AGENTS.md",
+    ".cursorrules",
+    ".github/copilot-instructions.md",
+];
+/** Directories to scan recursively for markdown governance files. */
+const SCAN_DIRS = ["specs", "decisions", "ADR"];
+/** Directories to always skip during recursive scanning. */
+const IGNORE_DIRS = new Set([
+    "node_modules",
+    "dist",
+    ".git",
+    "build",
+    "coverage",
+    ".next",
+    ".nuxt",
+    "__pycache__",
+    ".venv",
+]);
+const defaultDeps = {
+    stdout: (content) => process.stdout.write(content),
+    stderr: (content) => process.stderr.write(content),
+    credentialsStore: new credentials_store_1.CredentialsStore(),
+    readFile: (filePath) => fs.readFileSync(filePath, "utf-8"),
+    fileExists: (filePath) => fs.existsSync(filePath) && fs.statSync(filePath).isFile(),
+    readDir: (dirPath) => {
+        if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory())
+            return [];
+        return collectMarkdownFiles(dirPath);
+    },
+};
+// ── Helpers ─────────────────────────────────────────────────────────
+function collectMarkdownFiles(dirPath) {
+    const results = [];
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        if (IGNORE_DIRS.has(entry.name))
+            continue;
+        const full = path.join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...collectMarkdownFiles(full));
+        }
+        else if (entry.isFile() && /\.mdx?$/.test(entry.name)) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+function printHelp(stderr) {
+    stderr(`
+repo ingest - Ingest local governance files into a Spekn project
+
+USAGE:
+  spekn repo ingest --project-id <uuid> [options]
+
+OPTIONS:
+  --project-id <uuid>   Project ID to ingest into (required)
+  --path <dir>          Repository root path (default: current directory)
+  --dry-run             Analyze files without persisting to the server
+  --api-url <url>       API base URL (default: SPEKN_API_URL or http://localhost:3000)
+  --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
+
+DETECTED FILES:
+  Root: CLAUDE.md, .claude/CLAUDE.md, AGENTS.md, .cursorrules,
+        .github/copilot-instructions.md
+  Dirs: specs/**/*.md, decisions/**/*.md, ADR/**/*.md
+
+EXAMPLES:
+  spekn repo ingest --project-id 11111111-1111-4111-8111-111111111111
+  spekn repo ingest --project-id 11111111-1111-4111-8111-111111111111 --dry-run
+  spekn repo ingest --project-id 11111111-1111-4111-8111-111111111111 --path /path/to/repo
+`);
+}
+function parseArgs(args) {
+    let projectId = "";
+    let repoPath = ".";
+    let dryRun = false;
+    let apiUrl = process.env.SPEKN_API_URL ?? "http://localhost:3000";
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--help" || arg === "-h") {
+            throw new help_error_1.HelpRequestedError();
+        }
+        if (arg === "--project-id" && args[index + 1]) {
+            projectId = args[++index];
+            continue;
+        }
+        if (arg?.startsWith("--project-id=")) {
+            projectId = arg.slice("--project-id=".length);
+            continue;
+        }
+        if (arg === "--path" && args[index + 1]) {
+            repoPath = args[++index];
+            continue;
+        }
+        if (arg?.startsWith("--path=")) {
+            repoPath = arg.slice("--path=".length);
+            continue;
+        }
+        if (arg === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (arg === "--api-url" && args[index + 1]) {
+            apiUrl = args[++index];
+            continue;
+        }
+        if (arg?.startsWith("--api-url=")) {
+            apiUrl = arg.slice("--api-url=".length);
+            continue;
+        }
+    }
+    if (!projectId) {
+        throw new Error("Missing required argument: --project-id <uuid>");
+    }
+    return { projectId, repoPath: path.resolve(repoPath), dryRun, apiUrl };
+}
+// ── Main ────────────────────────────────────────────────────────────
+async function runRepoIngestCli(args, deps = defaultDeps) {
+    try {
+        const options = parseArgs(args);
+        // Resolve auth
+        const storedToken = await deps.credentialsStore.getValidToken();
+        const authToken = storedToken ?? process.env.SPEKN_AUTH_TOKEN;
+        const storedCreds = deps.credentialsStore.load();
+        const organizationId = storedCreds?.organizationId ?? process.env.SPEKN_ORGANIZATION_ID ?? "";
+        if (!authToken) {
+            deps.stderr("Error: Not authenticated. Run 'spekn auth login' first.\n");
+            return 1;
+        }
+        if (!organizationId) {
+            deps.stderr("Error: No organization ID. Re-run 'spekn auth login' or set SPEKN_ORGANIZATION_ID.\n");
+            return 1;
+        }
+        // Discover governance files
+        const discovered = [];
+        for (const file of ROOT_FILES) {
+            const abs = path.join(options.repoPath, file);
+            if (deps.fileExists(abs)) {
+                discovered.push({ relativePath: file, absolutePath: abs });
+            }
+        }
+        for (const dir of SCAN_DIRS) {
+            const abs = path.join(options.repoPath, dir);
+            const files = deps.readDir(abs);
+            for (const file of files) {
+                const rel = path.relative(options.repoPath, file);
+                discovered.push({ relativePath: rel, absolutePath: file });
+            }
+        }
+        // Also check for .claude/rules/*.md
+        const rulesDir = path.join(options.repoPath, ".claude", "rules");
+        const ruleFiles = deps.readDir(rulesDir);
+        for (const file of ruleFiles) {
+            const rel = path.relative(options.repoPath, file);
+            discovered.push({ relativePath: rel, absolutePath: file });
+        }
+        if (discovered.length === 0) {
+            deps.stdout("No governance files found in " + options.repoPath + "\n");
+            return 0;
+        }
+        deps.stdout(`Found ${discovered.length} governance file(s) in ${options.repoPath}\n\n`);
+        // Create tRPC client
+        const client = (0, client_1.createTRPCProxyClient)({
+            links: [
+                (0, client_1.httpBatchLink)({
+                    url: (0, trpc_url_1.normalizeTrpcUrl)(options.apiUrl),
+                    headers: {
+                        "x-organization-id": organizationId,
+                        authorization: `Bearer ${authToken}`,
+                    },
+                }),
+            ],
+        });
+        let successCount = 0;
+        let failCount = 0;
+        for (const file of discovered) {
+            deps.stdout(`  ${file.relativePath}`);
+            const content = deps.readFile(file.absolutePath);
+            if (!content.trim()) {
+                deps.stdout(" ... skipped (empty)\n");
+                continue;
+            }
+            try {
+                // Analyze content via server
+                const result = await client.ingestion.analyzeContent.mutate({
+                    content,
+                    filename: path.basename(file.relativePath),
+                });
+                const meta = result.metadata;
+                const layerCounts = {
+                    constraints: result.layers.constraints.length,
+                    requirements: result.layers.requirements.length,
+                    technicalContext: result.layers.technicalContext.length,
+                    implementationGuidance: result.layers.implementationGuidance.length,
+                };
+                const totalSections = Object.values(layerCounts).reduce((a, b) => a + b, 0);
+                deps.stdout(` ... ${meta.sourceFormat} (confidence: ${(meta.confidence * 100).toFixed(0)}%, ${totalSections} sections)`);
+                if (meta.warnings.length > 0) {
+                    deps.stdout(`\n    Warnings: ${meta.warnings.join(", ")}`);
+                }
+                if (options.dryRun) {
+                    deps.stdout(" [dry-run]\n");
+                    successCount++;
+                    continue;
+                }
+                // Persist to project
+                await client.ingestion.confirmIngestion.mutate({
+                    projectId: options.projectId,
+                    result,
+                });
+                deps.stdout(" ... ingested\n");
+                successCount++;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                deps.stdout(` ... FAILED: ${message}\n`);
+                failCount++;
+            }
+        }
+        deps.stdout(`\nDone: ${successCount} ingested, ${failCount} failed` +
+            (options.dryRun ? " (dry-run)" : "") +
+            "\n");
+        return failCount > 0 ? 1 : 0;
+    }
+    catch (error) {
+        if (error instanceof help_error_1.HelpRequestedError) {
+            printHelp(deps.stderr);
+            return 0;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        deps.stderr(`Error: ${message}\n`);
+        return 1;
+    }
+}
+async function main() {
+    const exitCode = await runRepoIngestCli(process.argv.slice(2));
+    process.exit(exitCode);
+}
+if (require.main === module) {
+    void main();
+}

package/dist/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 "./repo-common";
+export { repoNameFromUrl, resolveDefaultBranch, discoverFiles, buildAnalysisPrompt, executeAcpSession, runAnalysisWithAgent, verifyMcpServer, } from "./repo-common";
+export type { DiscoveredFile } from "./repo-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/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 repo_common_1 = require("./repo-common");
+const project_context_1 = require("./project-context");
+const structured_log_1 = require("./utils/structured-log");
+// Re-export shared utilities for backward compatibility
+var repo_common_2 = require("./repo-common");
+Object.defineProperty(exports, "repoNameFromUrl", { enumerable: true, get: function () { return repo_common_2.repoNameFromUrl; } });
+Object.defineProperty(exports, "resolveDefaultBranch", { enumerable: true, get: function () { return repo_common_2.resolveDefaultBranch; } });
+Object.defineProperty(exports, "discoverFiles", { enumerable: true, get: function () { return repo_common_2.discoverFiles; } });
+Object.defineProperty(exports, "buildAnalysisPrompt", { enumerable: true, get: function () { return repo_common_2.buildAnalysisPrompt; } });
+Object.defineProperty(exports, "executeAcpSession", { enumerable: true, get: function () { return repo_common_2.executeAcpSession; } });
+Object.defineProperty(exports, "runAnalysisWithAgent", { enumerable: true, get: function () { return repo_common_2.runAnalysisWithAgent; } });
+Object.defineProperty(exports, "verifyMcpServer", { enumerable: true, get: function () { return repo_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, repo_common_1.commonDefaults)(true), primary: false };
+    for (let i = 0; i < args.length;) {
+        const consumed = (0, repo_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, repo_common_1.finalizeOptions)(opts);
+}
+// ── Main ────────────────────────────────────────────────────────────
+async function runRepoRegisterCli(args, deps = repo_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, repo_common_1.resolveAuth)(deps, {
+            projectId: options.projectId,
+            repoPath: options.repoPath,
+        });
+        // ── Phase 1: Register repository metadata ──────────────────────
+        const git = (0, repo_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, repo_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, repo_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 repo_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/repo-sync.d.ts

@@ -0,0 +1,16 @@
+#!/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.
+ * Optionally runs AI analysis (same as repo register --analyze).
+ * Must be run from inside a local git clone.
+ *
+ * Usage: spekn repo sync --project-id <uuid> [--analyze] [--agent <name>] [--api-url <url>]
+ */
+import { type CommonOptions, type Deps } from "./repo-common";
+declare function parseArgs(args: string[]): CommonOptions;
+export declare function runRepoSyncCli(args: string[], deps?: Deps): Promise<number>;
+declare function main(): Promise<void>;
+export { main, parseArgs };