@spekn/cli 1.0.0

package/dist/repo-common.js

@@ -0,0 +1,671 @@
+"use strict";
+/**
+ * Shared utilities for repo register / repo sync CLI commands.
+ *
+ * Extracts common concerns: deps, auth, git metadata, tRPC client,
+ * file discovery display, and the full analysis phase.
+ */
+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.HelpRequestedError = exports.defaultDeps = void 0;
+exports.parseCommonFlag = parseCommonFlag;
+exports.commonDefaults = commonDefaults;
+exports.finalizeOptions = finalizeOptions;
+exports.resolveAuth = resolveAuth;
+exports.createApiClient = createApiClient;
+exports.repoNameFromUrl = repoNameFromUrl;
+exports.resolveDefaultBranch = resolveDefaultBranch;
+exports.readGitMetadata = readGitMetadata;
+exports.discoverFiles = discoverFiles;
+exports.discoverAndDisplay = discoverAndDisplay;
+exports.buildAnalysisPrompt = buildAnalysisPrompt;
+exports.validateAnalysisReport = validateAnalysisReport;
+exports.verifyMcpServer = verifyMcpServer;
+exports.executeAcpSession = executeAcpSession;
+exports.runAnalysisWithAgent = runAnalysisWithAgent;
+exports.runAnalysisPhase = runAnalysisPhase;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+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");
+Object.defineProperty(exports, "HelpRequestedError", { enumerable: true, get: function () { return help_error_1.HelpRequestedError; } });
+const interaction_1 = require("./utils/interaction");
+const project_context_1 = require("./project-context");
+const prompt_loader_1 = require("./resources/prompt-loader");
+exports.defaultDeps = {
+    execGit: (args) => (0, node_child_process_1.execFileSync)("git", args, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim(),
+    stdout: (content) => process.stdout.write(content),
+    stderr: (content) => process.stderr.write(content),
+    credentialsStore: new credentials_store_1.CredentialsStore(),
+};
+/**
+ * Parse flags shared by both register and sync. Returns consumed arg
+ * count (0 if the flag was not recognized). Mutates `out` in place.
+ */
+function parseCommonFlag(args, index, out) {
+    const arg = args[index];
+    if (arg === "--help" || arg === "-h")
+        throw new help_error_1.HelpRequestedError();
+    if (arg === "--project-id" && args[index + 1]) {
+        out.projectId = args[index + 1];
+        return 2;
+    }
+    if (arg?.startsWith("--project-id=")) {
+        out.projectId = arg.slice("--project-id=".length);
+        return 1;
+    }
+    if (arg === "--api-url" && args[index + 1]) {
+        out.apiUrl = args[index + 1];
+        return 2;
+    }
+    if (arg?.startsWith("--api-url=")) {
+        out.apiUrl = arg.slice("--api-url=".length);
+        return 1;
+    }
+    if (arg === "--agent" && args[index + 1]) {
+        out.agent = args[index + 1];
+        return 2;
+    }
+    if (arg?.startsWith("--agent=")) {
+        out.agent = arg.slice("--agent=".length);
+        return 1;
+    }
+    if (arg === "--path" && args[index + 1]) {
+        out.repoPath = args[index + 1];
+        return 2;
+    }
+    if (arg?.startsWith("--path=")) {
+        out.repoPath = arg.slice("--path=".length);
+        return 1;
+    }
+    if (arg === "--mcp-url" && args[index + 1]) {
+        out.mcpUrl = args[index + 1];
+        return 2;
+    }
+    if (arg?.startsWith("--mcp-url=")) {
+        out.mcpUrl = arg.slice("--mcp-url=".length);
+        return 1;
+    }
+    if (arg === "--dry-run") {
+        out.dryRun = true;
+        return 1;
+    }
+    if (arg === "--debug") {
+        out.debug = true;
+        return 1;
+    }
+    if (arg === "--analyze") {
+        out.analyze = true;
+        return 1;
+    }
+    if (arg === "--no-analyze") {
+        out.analyze = false;
+        return 1;
+    }
+    return 0; // not consumed
+}
+function commonDefaults(analyzeDefault) {
+    return {
+        projectId: "",
+        apiUrl: process.env.SPEKN_API_URL ?? "https://app.spekn.com",
+        analyze: analyzeDefault,
+        agent: null,
+        repoPath: ".",
+        dryRun: false,
+        mcpUrl: process.env.MCP_HTTP_URL ?? "https://app.spekn.com/mcp",
+        debug: false,
+    };
+}
+function finalizeOptions(opts) {
+    opts.repoPath = path.resolve(opts.repoPath);
+    return opts;
+}
+// ── Auth ────────────────────────────────────────────────────────────
+async function resolveAuth(deps, options) {
+    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 || undefined,
+        repoPath: options?.repoPath,
+        credentialsOrganizationId: storedCreds?.organizationId,
+        envOrganizationId: process.env.SPEKN_ORGANIZATION_ID,
+    });
+    return {
+        authToken: authToken ?? undefined,
+        organizationId: context.organizationId,
+        projectId: context.projectId,
+    };
+}
+// ── tRPC Client ─────────────────────────────────────────────────────
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function createApiClient(apiUrl, authToken, organizationId) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (0, client_1.createTRPCProxyClient)({
+        links: [
+            (0, client_1.httpBatchLink)({
+                url: (0, trpc_url_1.normalizeTrpcUrl)(apiUrl),
+                headers: {
+                    "x-organization-id": organizationId,
+                    authorization: authToken ? `Bearer ${authToken}` : "",
+                },
+            }),
+        ],
+    });
+}
+// ── Git Helpers ─────────────────────────────────────────────────────
+function repoNameFromUrl(url) {
+    const withoutGit = url.replace(/\.git$/, "");
+    const parts = withoutGit.split(/[/:]/).filter(Boolean);
+    return parts[parts.length - 1] ?? "unknown";
+}
+function resolveDefaultBranch(execGit) {
+    try {
+        const ref = execGit(["symbolic-ref", "refs/remotes/origin/HEAD"]);
+        const parts = ref.split("/");
+        return parts[parts.length - 1] ?? "main";
+    }
+    catch {
+        return "main";
+    }
+}
+function readGitMetadata(repoPath, deps) {
+    let remoteUrl;
+    try {
+        remoteUrl = deps.execGit(["-C", repoPath, "remote", "get-url", "origin"]);
+    }
+    catch {
+        deps.stderr("Error: Could not read git remote URL. Make sure the path is a git repository with an 'origin' remote.\n");
+        return null;
+    }
+    const name = repoNameFromUrl(remoteUrl);
+    const defaultBranch = resolveDefaultBranch((gitArgs) => deps.execGit(["-C", repoPath, ...gitArgs]));
+    return { remoteUrl, name, defaultBranch };
+}
+// ── File Discovery ──────────────────────────────────────────────────
+const IGNORE_DIRS = new Set([
+    "node_modules", "dist", ".git", "build", "coverage",
+    ".next", ".nuxt", "__pycache__", ".venv", "target",
+]);
+function collectMarkdownFiles(dirPath) {
+    if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory())
+        return [];
+    const results = [];
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        if (IGNORE_DIRS.has(entry.name))
+            continue;
+        if (entry.name.startsWith(".") && entry.name !== ".cursorrules" && entry.name !== ".github")
+            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 discoverFiles(repoPath) {
+    const files = [];
+    const governanceFiles = [
+        "CLAUDE.md", ".claude/CLAUDE.md", "AGENTS.md", ".cursorrules",
+        ".github/copilot-instructions.md", "README.md",
+    ];
+    for (const file of governanceFiles) {
+        const abs = path.join(repoPath, file);
+        if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
+            files.push({ relativePath: file, absolutePath: abs, category: "governance" });
+        }
+    }
+    const rulesDir = path.join(repoPath, ".claude", "rules");
+    for (const f of collectMarkdownFiles(rulesDir)) {
+        files.push({ relativePath: path.relative(repoPath, f), absolutePath: f, category: "governance" });
+    }
+    const allMd = collectMarkdownFiles(repoPath);
+    for (const f of allMd) {
+        const rel = path.relative(repoPath, f);
+        if (files.some((d) => d.relativePath === rel))
+            continue;
+        const lower = rel.toLowerCase();
+        if (lower.includes("decision") || lower.includes("/adr/")) {
+            files.push({ relativePath: rel, absolutePath: f, category: "decision" });
+        }
+        else if (lower.includes("spec") || lower.includes("design") || lower.includes("rfc")) {
+            files.push({ relativePath: rel, absolutePath: f, category: "spec" });
+        }
+        else {
+            files.push({ relativePath: rel, absolutePath: f, category: "config" });
+        }
+    }
+    return files;
+}
+/** Discover files, print summary. Returns files or null if empty. */
+function discoverAndDisplay(repoPath, stdout) {
+    stdout("\nScanning repository for analysis...\n");
+    const discovered = discoverFiles(repoPath);
+    if (discovered.length === 0) {
+        stdout("No files found in " + repoPath + "\n");
+        return null;
+    }
+    const byCat = {
+        governance: discovered.filter((f) => f.category === "governance"),
+        spec: discovered.filter((f) => f.category === "spec"),
+        decision: discovered.filter((f) => f.category === "decision"),
+        config: discovered.filter((f) => f.category === "config"),
+    };
+    stdout(`\nDiscovered ${discovered.length} files:\n`);
+    if (byCat.governance.length > 0)
+        stdout(`  Governance: ${byCat.governance.map((f) => f.relativePath).join(", ")}\n`);
+    if (byCat.spec.length > 0)
+        stdout(`  Specs:      ${byCat.spec.map((f) => f.relativePath).join(", ")}\n`);
+    if (byCat.decision.length > 0)
+        stdout(`  Decisions:  ${byCat.decision.map((f) => f.relativePath).join(", ")}\n`);
+    if (byCat.config.length > 0)
+        stdout(`  Other:      ${byCat.config.length} markdown files\n`);
+    return discovered;
+}
+// ── Prompt Builder ──────────────────────────────────────────────────
+function buildAnalysisPrompt(projectId, repoPath, files, organizationId) {
+    const fileList = files.map((f) => `  - ${f.relativePath} [${f.category}]`).join("\n");
+    const orgIdInstruction = organizationId
+        ? `\nORGANIZATION ID: ${organizationId}\nIMPORTANT: You MUST include "organizationId": "${organizationId}" as a parameter in EVERY Spekn MCP tool call.\n`
+        : "";
+    const template = (0, prompt_loader_1.loadPromptTemplate)("repo-analysis.prompt.md");
+    return template
+        .replaceAll("{{PROJECT_ID}}", projectId)
+        .replaceAll("{{ORG_INSTRUCTION}}", orgIdInstruction)
+        .replaceAll("{{REPO_PATH}}", repoPath)
+        .replaceAll("{{FILE_LIST}}", fileList);
+}
+const REQUIRED_ANALYSIS_SECTIONS = [
+    "FEATURE_COVERAGE",
+    "MISSING_PLAN_FEATURES",
+    "DECISIONS_CREATED",
+];
+function validateAnalysisReport(text) {
+    const missing = REQUIRED_ANALYSIS_SECTIONS.filter((section) => {
+        const pattern = new RegExp(`^\\s*${section}\\b`, "mi");
+        return !pattern.test(text);
+    });
+    return { ok: missing.length === 0, missing: [...missing] };
+}
+// ── MCP Server Verification ─────────────────────────────────────────
+/**
+ * Connect to the MCP HTTP server via raw JSON-RPC, perform the MCP
+ * initialize handshake, then list tools and verify Spekn tools exist.
+ * Returns tool names on success or null on failure.
+ */
+async function verifyMcpServer(mcpUrl, authToken, stderr, debug, sessionPurpose = "ingestion_sync") {
+    const dbg = (msg) => { if (debug)
+        stderr(`  [debug] ${msg}\n`); };
+    const headers = {
+        "Content-Type": "application/json",
+        Accept: "application/json, text/event-stream",
+        Authorization: `Bearer ${authToken}`,
+        "x-spekn-mcp-purpose": sessionPurpose,
+    };
+    dbg(`MCP URL: ${mcpUrl}`);
+    dbg(`Auth token (first 20 chars): ${authToken.slice(0, 20)}...`);
+    dbg(`Auth token length: ${authToken.length}`);
+    try {
+        // Step 1: MCP initialize handshake
+        const initBody = JSON.stringify({
+            jsonrpc: "2.0",
+            method: "initialize",
+            params: {
+                protocolVersion: "2025-03-26",
+                capabilities: {},
+                clientInfo: { name: "spekn-cli", version: "1.0.0" },
+            },
+            id: 1,
+        });
+        dbg(`POST initialize: ${initBody}`);
+        const initRes = await fetch(mcpUrl, {
+            method: "POST",
+            headers,
+            body: initBody,
+            signal: AbortSignal.timeout(10_000),
+        });
+        const initResBody = await initRes.text();
+        const sessionId = initRes.headers.get("mcp-session-id");
+        dbg(`initialize response: HTTP ${initRes.status}`);
+        dbg(`initialize content-type: ${initRes.headers.get("content-type") ?? ""}`);
+        dbg(`initialize mcp-session-id: ${sessionId ?? "(none)"}`);
+        dbg(`initialize response headers: ${JSON.stringify(Object.fromEntries(initRes.headers.entries()))}`);
+        dbg(`initialize body: ${initResBody.slice(0, 500)}`);
+        if (!initRes.ok) {
+            stderr(`  MCP initialize failed: HTTP ${initRes.status} — ${initResBody.slice(0, 200)}\n`);
+            return null;
+        }
+        if (!sessionId) {
+            stderr("  MCP initialize succeeded but no session ID returned.\n");
+            return null;
+        }
+        // Step 2: Send initialized notification
+        const sessionHeaders = { ...headers, "mcp-session-id": sessionId };
+        dbg(`POST notifications/initialized (session: ${sessionId})`);
+        const notifRes = await fetch(mcpUrl, {
+            method: "POST",
+            headers: sessionHeaders,
+            body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
+            signal: AbortSignal.timeout(5_000),
+        });
+        dbg(`notifications/initialized response: HTTP ${notifRes.status}`);
+        const notifResBody = await notifRes.text();
+        dbg(`notifications/initialized body: ${notifResBody.slice(0, 300)}`);
+        // Step 3: List tools
+        dbg(`POST tools/list (session: ${sessionId})`);
+        const toolsRes = await fetch(mcpUrl, {
+            method: "POST",
+            headers: sessionHeaders,
+            body: JSON.stringify({ jsonrpc: "2.0", method: "tools/list", params: {}, id: 2 }),
+            signal: AbortSignal.timeout(10_000),
+        });
+        const toolsResBody = await toolsRes.text();
+        const toolsContentType = toolsRes.headers.get("content-type") ?? "";
+        dbg(`tools/list response: HTTP ${toolsRes.status}`);
+        dbg(`tools/list content-type: ${toolsContentType}`);
+        dbg(`tools/list response headers: ${JSON.stringify(Object.fromEntries(toolsRes.headers.entries()))}`);
+        dbg(`tools/list body (first 500): ${toolsResBody.slice(0, 500)}`);
+        if (!toolsRes.ok) {
+            stderr(`  MCP tools/list failed: HTTP ${toolsRes.status} — ${toolsResBody.slice(0, 200)}\n`);
+            // Try to parse error response for better diagnostics
+            try {
+                const errorObj = JSON.parse(toolsResBody);
+                if (errorObj.error && errorObj.error.message) {
+                    const errorMsg = errorObj.error.message;
+                    if (errorMsg.includes("Authentication failed")) {
+                        stderr(`  Authentication issue: ${errorMsg}\n`);
+                        stderr(`  Please check your auth token and ensure the MCP server is properly configured.\n`);
+                    }
+                    else if (errorMsg.includes("Server not initialized")) {
+                        stderr(`  MCP server initialization failed. This may indicate a database connection issue.\n`);
+                    }
+                }
+            }
+            catch {
+                // Ignore JSON parse errors
+            }
+            return null;
+        }
+        // Parse tools response (may be SSE or JSON)
+        let toolsParseable;
+        if (toolsContentType.includes("text/event-stream")) {
+            const dataLine = toolsResBody.split("\n").find((l) => l.startsWith("data: "));
+            toolsParseable = dataLine ? dataLine.slice(6) : toolsResBody;
+        }
+        else {
+            toolsParseable = toolsResBody;
+        }
+        dbg(`tools/list parsed payload: ${toolsParseable.slice(0, 500)}`);
+        const toolsResult = JSON.parse(toolsParseable);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const tools = (toolsResult.result?.tools ?? []).map((t) => t.name);
+        dbg(`tools found: ${tools.length} — ${tools.join(", ")}`);
+        // Step 4: Clean up — terminate session
+        await fetch(mcpUrl, {
+            method: "DELETE",
+            headers: sessionHeaders,
+            signal: AbortSignal.timeout(5_000),
+        }).catch(() => { });
+        if (tools.length === 0) {
+            stderr(`  MCP server at ${mcpUrl}: connected but no tools available.\n`);
+            return null;
+        }
+        const speknTools = tools.filter((n) => n.startsWith("spekn_"));
+        stderr(`  MCP server verified: ${speknTools.length} Spekn tools available (${tools.length} total)\n`);
+        return tools;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        stderr(`  MCP server verification failed at ${mcpUrl}: ${msg}\n`);
+        dbg(`Full error: ${err instanceof Error ? err.stack ?? msg : msg}`);
+        return null;
+    }
+}
+// ── ACP Session Execution ───────────────────────────────────────────
+async function executeAcpSession(agent, prompt, repoPath, mcpUrl, authToken, stderr, organizationId, sessionPurpose = "ingestion_sync") {
+    const { executeAcpSession: sharedExecuteAcpSession } = await Promise.resolve().then(() => __importStar(require("@spekn/check")));
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mcpHeaders = [
+        { name: "Authorization", value: `Bearer ${authToken}` },
+        { name: "x-spekn-mcp-purpose", value: sessionPurpose },
+    ];
+    if (organizationId) {
+        mcpHeaders.push({ name: "x-organization-id", value: organizationId });
+    }
+    const DEFAULT_ACP_TIMEOUT_MS = 5 * 60 * 1000;
+    const timeoutMs = Number(process.env.ACP_AGENT_TIMEOUT_MS) || DEFAULT_ACP_TIMEOUT_MS;
+    const result = await sharedExecuteAcpSession({
+        command: agent.command,
+        args: agent.args,
+        prompt,
+        cwd: repoPath,
+        timeoutMs,
+        mcpServers: [{
+                type: "http",
+                name: "spekn",
+                url: mcpUrl,
+                headers: mcpHeaders,
+            }],
+        requireHttpMcp: true,
+        onChunk: (text) => process.stderr.write(text),
+        onStderr: (text) => stderr(`[agent] ${text.slice(0, 200)}\n`),
+        onSpawnError: (err) => stderr(`ACP agent spawn error: ${err.message}\n`),
+        onSessionStart: (sessionId) => {
+            stderr(`  Session created: ${sessionId}\n`);
+            stderr("\nAgent session started. Analyzing repository...\n\n");
+        },
+    });
+    // Map agentCapabilities info for caller
+    if (result.error === "no-http-mcp") {
+        stderr(`  Agent "${agent.command}" does not advertise HTTP MCP support.\n`);
+    }
+    return { text: result.text, error: result.error };
+}
+async function issuePurposeToken(apiUrl, authToken, organizationId, purpose) {
+    if (!organizationId) {
+        throw new Error("Organization context is required to issue purpose-scoped MCP tokens");
+    }
+    const client = createApiClient(apiUrl, authToken, organizationId);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const result = await client.auth.issueMcpToken.mutate({
+        purpose,
+        ttlSeconds: 600,
+    });
+    if (!result?.token || typeof result.token !== "string") {
+        throw new Error("Failed to issue MCP purpose token");
+    }
+    return result.token;
+}
+/**
+ * Verify MCP server, resolve an agent, run the ACP session.
+ * Retries with the next agent if one doesn't support HTTP MCP.
+ */
+async function runAnalysisWithAgent(options) {
+    const { apiUrl, agentName, prompt, repoPath, mcpUrl, authToken, organizationId, stdout, stderr, debug } = options;
+    const mcpPurpose = "ingestion_sync";
+    let mcpAuthToken;
+    try {
+        mcpAuthToken = await issuePurposeToken(apiUrl, authToken, organizationId, mcpPurpose);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        stderr(`Error: Could not issue MCP purpose token (${mcpPurpose}): ${message}\n`);
+        stderr("Run 'spekn auth login' and ensure an organization is selected.\n");
+        return { text: "", error: "purpose-token-issue-failed" };
+    }
+    // Step 1: Verify MCP server before spawning any agent
+    stderr("Verifying MCP server...\n");
+    const mcpTools = await verifyMcpServer(mcpUrl, mcpAuthToken, stderr, debug, mcpPurpose);
+    if (!mcpTools) {
+        stderr("Error: Cannot proceed with analysis — MCP server not available.\n");
+        stderr(`  Make sure the MCP HTTP server is running at ${mcpUrl}\n`);
+        stderr("  Start it with: npm run dev:mcp\n");
+        stderr("\n");
+        stderr("Troubleshooting steps:\n");
+        stderr(`  1. Check if MCP server is running: curl ${mcpUrl}/health\n`);
+        stderr("  2. Enable debug logging: MCP_DEBUG=true npm run dev:mcp\n");
+        stderr("  3. Verify your auth token is valid: spekn auth status\n");
+        stderr("  4. Check Keycloak client configuration for spekn-cli\n");
+        return { text: "", error: "MCP server not available" };
+    }
+    // Step 2: Detect installed agents
+    const { detectInstalledAgents, promptForAgentSelection, resolveFromRegistry } = await Promise.resolve().then(() => __importStar(require("@spekn/check")));
+    const detected = await detectInstalledAgents();
+    const installed = detected.filter((a) => a.installed);
+    if (installed.length === 0) {
+        stderr("Error: No ACP agents found. Install claude, codex, or opencode.\n");
+        return { text: "", error: "No agents available" };
+    }
+    const agentArgsEnv = process.env.AGENT_ARGS ?? process.env.ACP_ARGS;
+    // env override — try only that one agent
+    if (agentName && agentArgsEnv !== undefined) {
+        const agent = { command: agentName, args: agentArgsEnv ? agentArgsEnv.split(" ") : [] };
+        stdout(`Using agent: ${agentName} (AGENT_ARGS override)\n`);
+        return executeAcpSession(agent, prompt, repoPath, mcpUrl, mcpAuthToken, stderr, organizationId, mcpPurpose);
+    }
+    // Determine initial agent selection
+    let firstChoice = null;
+    if (agentName) {
+        firstChoice = agentName;
+    }
+    else if (installed.length === 1) {
+        firstChoice = installed[0].name;
+        stderr(`Using detected agent: ${firstChoice}\n`);
+    }
+    else {
+        let selected = null;
+        if (process.stdin.isTTY && process.stdout.isTTY) {
+            selected = await promptForAgentSelection(detected);
+        }
+        else {
+            selected = await (0, interaction_1.requestSelectionFromController)({
+                title: "Agent selection required",
+                message: "Multiple ACP agents are installed. Select one for repository analysis.",
+                options: installed.map((agent) => ({
+                    value: agent.name,
+                    label: agent.name,
+                })),
+                allowSkip: true,
+            });
+        }
+        if (selected === "skip") {
+            return { text: "", error: "No agent selected" };
+        }
+        if (!selected) {
+            firstChoice = installed[0].name;
+            stderr(`No interactive selection available. Defaulting to detected agent: ${firstChoice}\n`);
+        }
+        else {
+            firstChoice = selected;
+        }
+    }
+    // Try user's choice first, then remaining agents
+    const remaining = [firstChoice, ...installed.map((a) => a.name).filter((n) => n !== firstChoice)];
+    for (const candidateName of remaining) {
+        const resolved = await resolveFromRegistry(candidateName);
+        const agent = resolved
+            ? { command: resolved.command, args: resolved.args }
+            : { command: candidateName, args: [] };
+        stdout(`Trying agent: ${candidateName}...\n`);
+        const result = await executeAcpSession(agent, prompt, repoPath, mcpUrl, mcpAuthToken, stderr, organizationId, mcpPurpose);
+        if (result.error === "no-http-mcp") {
+            stderr(`Agent "${candidateName}" does not support HTTP MCP servers. Trying next...\n`);
+            continue;
+        }
+        return result;
+    }
+    return { text: "", error: "No agents with HTTP MCP support available" };
+}
+// ── Full Analysis Phase ─────────────────────────────────────────────
+/**
+ * Complete analysis phase: discover files → build prompt → run agent.
+ * Returns exit code (0 = success, 1 = error).
+ */
+async function runAnalysisPhase(options, authToken, deps, organizationId) {
+    if (!authToken) {
+        deps.stderr("Warning: Not authenticated. Skipping AI analysis. Run 'spekn auth login' first.\n");
+        return 0;
+    }
+    const discovered = discoverAndDisplay(options.repoPath, deps.stdout);
+    if (!discovered)
+        return 0;
+    if (options.dryRun) {
+        deps.stdout("\n[dry-run] Skipping AI analysis.\n");
+        return 0;
+    }
+    deps.stdout("\nResolving AI agent...\n");
+    const prompt = buildAnalysisPrompt(options.projectId, options.repoPath, discovered, organizationId);
+    const result = await runAnalysisWithAgent({
+        apiUrl: options.apiUrl,
+        agentName: options.agent,
+        prompt,
+        repoPath: options.repoPath,
+        mcpUrl: options.mcpUrl,
+        authToken,
+        organizationId,
+        stdout: deps.stdout,
+        stderr: deps.stderr,
+        debug: options.debug,
+    });
+    if (result.error) {
+        const errorMessage = typeof result.error === "string"
+            ? result.error
+            : (() => {
+                try {
+                    return JSON.stringify(result.error);
+                }
+                catch {
+                    return String(result.error);
+                }
+            })();
+        deps.stderr(`\nAgent error: ${errorMessage}\n`);
+        return 1;
+    }
+    const reportValidation = validateAnalysisReport(result.text);
+    if (!reportValidation.ok) {
+        deps.stderr(`\nAnalysis failed quality gate: missing required report sections: ${reportValidation.missing.join(", ")}\n`);
+        deps.stderr("The ingestion report must include FEATURE_COVERAGE, MISSING_PLAN_FEATURES, and DECISIONS_CREATED sections.\n");
+        return 1;
+    }
+    deps.stdout("\nAnalysis complete.\n");
+    return 0;
+}

package/dist/repo-detach.d.ts

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