@spekn/cli 1.0.0 → 1.0.1

package/dist/commands/repo/common.js

@@ -1,775 +0,0 @@
-"use strict";
-/**
- * Shared utilities for repo register / repo sync CLI commands.
- *
- * Extracts common concerns: deps, auth, git metadata, tRPC client, and
- * file discovery. ACP prompt-driven analysis utilities are used by
- * `repo register`; `repo sync` runs ingestion drift analysis via API calls.
- */
-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 === "--acp-timeout" && args[index + 1]) {
-        const parsed = Number(args[index + 1]);
-        if (Number.isFinite(parsed) && parsed >= 0) {
-            out.acpTimeoutMs = Math.floor(parsed);
-        }
-        return 2;
-    }
-    if (arg?.startsWith("--acp-timeout=")) {
-        const value = arg.slice("--acp-timeout=".length);
-        const parsed = Number(value);
-        if (Number.isFinite(parsed) && parsed >= 0) {
-            out.acpTimeoutMs = Math.floor(parsed);
-        }
-        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 collectFiles(dirPath, extPattern) {
-    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(...collectFiles(full, extPattern));
-        }
-        else if (entry.isFile() && extPattern.test(entry.name)) {
-            results.push(full);
-        }
-    }
-    return results;
-}
-function collectMarkdownFiles(dirPath) {
-    return collectFiles(dirPath, /\.mdx?$/);
-}
-function collectPdfFiles(dirPath) {
-    return collectFiles(dirPath, /\.pdf$/i);
-}
-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" });
-        }
-    }
-    const MAX_PDF_SIZE = 50 * 1024 * 1024; // 50 MB
-    const allPdf = collectPdfFiles(repoPath);
-    for (const f of allPdf) {
-        const rel = path.relative(repoPath, f);
-        try {
-            const stat = fs.statSync(f);
-            if (stat.size <= MAX_PDF_SIZE) {
-                files.push({ relativePath: rel, absolutePath: f, category: "pdf" });
-            }
-        }
-        catch {
-            // skip unreadable PDFs
-        }
-    }
-    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"),
-        pdf: discovered.filter((f) => f.category === "pdf"),
-    };
-    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.pdf.length > 0)
-        stdout(`  PDFs:       ${byCat.pdf.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) {
-    // First try flexible pattern matching for explicit sections
-    const missing = REQUIRED_ANALYSIS_SECTIONS.filter((section) => {
-        const pattern = new RegExp(`(?:\\s*[#:]\\s*|^\\s*)${section.replace(/_/g, '\\s*')}\\b`, "mi");
-        return !pattern.test(text);
-    });
-    // If we're missing sections, check if the content contains equivalent information
-    if (missing.length > 0) {
-        const hasFeatureCoverage = /feature[\s-]coverage|implementation[\s-]status|status.*evidence/gi.test(text);
-        const hasMissingFeatures = /missing[\s-]plan[\s-]features|not[\s-]yet[\s-]implemented|planned.*not/gi.test(text);
-        const hasDecisionsCreated = /decisions[\s-]created|decision[\s-]log|extracted.*decisions/gi.test(text);
-        if (hasFeatureCoverage) {
-            const index = missing.indexOf("FEATURE_COVERAGE");
-            if (index !== -1)
-                missing.splice(index, 1);
-        }
-        if (hasMissingFeatures) {
-            const index = missing.indexOf("MISSING_PLAN_FEATURES");
-            if (index !== -1)
-                missing.splice(index, 1);
-        }
-        if (hasDecisionsCreated) {
-            const index = missing.indexOf("DECISIONS_CREATED");
-            if (index !== -1)
-                missing.splice(index, 1);
-        }
-    }
-    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", acpTimeoutMs) {
-    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 = 0; // Infinite session
-    const timeoutMs = acpTimeoutMs ?? 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: acpTimeoutMs,
-        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`),
-        onInteractiveRequest: async (request) => {
-            stderr(`[interaction] ${request.title}\n`);
-            const selected = await (0, interaction_1.requestSelectionFromController)({
-                title: request.title,
-                message: request.message,
-                options: request.options,
-                allowSkip: request.allowSkip,
-                timeoutMs: request.timeoutMs,
-            });
-            if (!selected) {
-                stderr("[interaction] No interactive selection available.\n");
-            }
-            return selected;
-        },
-        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, requiredTools = [], 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" };
-    }
-    if (requiredTools.length > 0) {
-        const missing = requiredTools.filter((tool) => !mcpTools.includes(tool));
-        if (missing.length > 0) {
-            stderr(`Error: MCP session purpose "${mcpPurpose}" is missing required tools: ${missing.join(", ")}\n`);
-            stderr("Check organization role/permissions and MCP allowlist for ingestion_sync scope.\n");
-            return { text: "", error: "missing-required-tools" };
-        }
-    }
-    // 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" };
-        }
-        const pickPreferredAgent = (names) => {
-            const lower = names.map((name) => name.toLowerCase());
-            const order = ["codex", "claude", "opencode"];
-            for (const preferred of order) {
-                const index = lower.findIndex((name) => name === preferred);
-                if (index >= 0)
-                    return names[index];
-            }
-            return names[0];
-        };
-        if (!selected) {
-            firstChoice = pickPreferredAgent(installed.map((agent) => agent.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)];
-    let lastError;
-    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, options.acpTimeoutMs);
-        if (result.error === "no-http-mcp") {
-            stderr(`Agent "${candidateName}" does not support HTTP MCP servers. Trying next...\n`);
-            continue;
-        }
-        if (result.error) {
-            lastError = typeof result.error === "string" ? result.error : String(result.error);
-            stderr(`Agent "${candidateName}" failed (${lastError}). Trying next...\n`);
-            continue;
-        }
-        return result;
-    }
-    return {
-        text: "",
-        error: lastError ?? "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;
-    }
-    // Validate report format but never fail - only report warnings
-    const reportValidation = validateAnalysisReport(result.text);
-    if (!reportValidation.ok) {
-        deps.stderr(`\nAnalysis validation notice: report format varies from expected structure.\n`);
-        deps.stderr(`Sections not found in expected format: ${reportValidation.missing.join(", ")}\n`);
-        deps.stderr("This is informational only. The analysis completed successfully with valid results.\n");
-        deps.stderr("Review the analysis output above for the actual findings and recommendations.\n");
-    }
-    deps.stdout("\nAnalysis complete.\n");
-    return 0;
-}