@spekn/cli 1.0.0

package/dist/commands/repo/sync.js

@@ -0,0 +1,873 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * 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>]
+ */
+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.runRepoSyncCli = runRepoSyncCli;
+exports.main = main;
+exports.parseArgs = parseArgs;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const common_1 = require("./common");
+const project_context_1 = require("../../project-context");
+const structured_log_1 = require("../../utils/structured-log");
+const prompt_loader_1 = require("../../resources/prompt-loader");
+const interaction_1 = require("../../utils/interaction");
+const check_1 = require("@spekn/check");
+function normalizeText(value) {
+    return value.replace(/\s+/g, " ").trim().toLowerCase();
+}
+function flattenIngestionText(result) {
+    const layers = result.layers ?? {};
+    const groups = [
+        layers.constraints ?? [],
+        layers.requirements ?? [],
+        layers.technicalContext ?? [],
+        layers.implementationGuidance ?? [],
+    ];
+    const lines = [];
+    for (const group of groups) {
+        for (const item of group) {
+            const text = normalizeText(`${item.title ?? ""} ${item.content ?? ""}`);
+            if (text.length >= 24)
+                lines.push(text);
+        }
+    }
+    return lines;
+}
+function decideImport(analyzed, findings, latestSpecContent) {
+    const hasHighConflict = findings.some((finding) => finding?.type === "conflict" && finding?.severity === "high");
+    if (hasHighConflict) {
+        return { shouldImport: false, reason: "high-conflict" };
+    }
+    const localEntries = flattenIngestionText(analyzed);
+    if (localEntries.length === 0) {
+        return { shouldImport: false, reason: "duplicate" };
+    }
+    // Normalized line-level comparison for deduplication awareness
+    const existingNormalized = new Set(latestSpecContent
+        .split("\n")
+        .map((line) => line.toLowerCase().trim())
+        .filter(Boolean));
+    let novelItems = 0;
+    for (const entry of localEntries) {
+        if (!existingNormalized.has(entry))
+            novelItems++;
+    }
+    const noveltyRatio = localEntries.length > 0 ? novelItems / localEntries.length : 0;
+    // Only import if >30% novel content
+    return noveltyRatio > 0.3
+        ? { shouldImport: true, reason: "new-content", noveltyRatio }
+        : { shouldImport: false, reason: "duplicate", noveltyRatio };
+}
+function buildSyncAnalysisPrompt(projectId, repoPath, files, commitContext, 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-sync-analysis.prompt.md");
+    return template
+        .replaceAll("{{PROJECT_ID}}", projectId)
+        .replaceAll("{{ORG_INSTRUCTION}}", orgIdInstruction)
+        .replaceAll("{{REPO_PATH}}", repoPath)
+        .replaceAll("{{COMMIT_CONTEXT}}", commitContext)
+        .replaceAll("{{FILE_LIST}}", fileList);
+}
+function loadGlobalContextLike() {
+    return (0, project_context_1.loadGlobalContext)() ?? {};
+}
+function getProjectsFromContext(globalContext) {
+    return Array.isArray(globalContext.projects) ? globalContext.projects : [];
+}
+function loadRepoSyncState(repoPath, projectId) {
+    const repoKey = path.resolve(repoPath);
+    const globalContext = loadGlobalContextLike();
+    const projects = getProjectsFromContext(globalContext);
+    const projectCheckpoint = projects.find((project) => project.id === projectId)?.repoSync
+        ?.checkpoints?.[repoKey];
+    if (projectCheckpoint && typeof projectCheckpoint === "object") {
+        return projectCheckpoint;
+    }
+    return {};
+}
+function saveRepoSyncState(repoPath, projectId, organizationId, state) {
+    const repoKey = path.resolve(repoPath);
+    const globalContext = loadGlobalContextLike();
+    const projects = getProjectsFromContext(globalContext);
+    const now = new Date().toISOString();
+    const projectIndex = projects.findIndex((project) => project.id === projectId);
+    const nextProjects = [...projects];
+    if (projectIndex >= 0) {
+        const project = nextProjects[projectIndex];
+        nextProjects[projectIndex] = {
+            ...project,
+            organizationId: project.organizationId || organizationId,
+            repoSync: {
+                ...(project.repoSync ?? {}),
+                checkpoints: {
+                    ...(project.repoSync?.checkpoints ?? {}),
+                    [repoKey]: state,
+                },
+            },
+            lastUsed: project.lastUsed || now,
+            repoPaths: Array.from(new Set([...(project.repoPaths ?? []), repoPath])),
+        };
+    }
+    else {
+        nextProjects.unshift({
+            id: projectId,
+            organizationId,
+            lastUsed: now,
+            repoPaths: [repoPath],
+            repoSync: {
+                checkpoints: {
+                    [repoKey]: state,
+                },
+            },
+        });
+    }
+    (0, project_context_1.saveGlobalContext)({
+        ...globalContext,
+        projects: nextProjects.slice(0, 10),
+        repoSync: undefined,
+    });
+}
+function readHeadCommit(repoPath, deps) {
+    try {
+        return deps.execGit(["-C", repoPath, "rev-parse", "HEAD"]);
+    }
+    catch {
+        return null;
+    }
+}
+function readChangedFilesSince(repoPath, fromCommit, toCommit, deps) {
+    try {
+        const raw = deps.execGit([
+            "-C",
+            repoPath,
+            "diff",
+            "--name-only",
+            `${fromCommit}..${toCommit}`,
+        ]);
+        return raw
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+function looksLikeCodeFile(relativePath) {
+    const lower = relativePath.toLowerCase();
+    if (lower.endsWith(".md") || lower.endsWith(".mdx") || lower.endsWith(".txt")) {
+        return false;
+    }
+    if (lower.includes("/specs/") ||
+        lower.includes("/decisions/") ||
+        lower.includes("spec") ||
+        lower.includes("decision") ||
+        lower.includes("/docs/")) {
+        return false;
+    }
+    return true;
+}
+function looksLikeSpecOrDecisionUpdate(relativePath) {
+    const lower = relativePath.toLowerCase();
+    return (lower.includes("/specs/") ||
+        lower.includes("/decisions/") ||
+        lower.includes("spec") ||
+        lower.includes("decision") ||
+        lower.endsWith(".md") ||
+        lower.endsWith(".mdx"));
+}
+async function approveLowConfidenceImport(input) {
+    const selected = await (0, interaction_1.requestSelectionFromController)({
+        title: "Approve low-confidence sync import?",
+        message: `${input.filePath} has score=${input.score}, findings=${input.findingCount}, high=${input.highCount}. ` +
+            "Approve import into SaaS spec/decision context?",
+        options: [
+            { value: "approve", label: "Approve import" },
+            { value: "skip", label: "Skip import" },
+        ],
+        allowSkip: true,
+        timeoutMs: 45_000,
+    });
+    if (selected === "approve")
+        return true;
+    if (selected === "skip")
+        return false;
+    input.stderr(`[warn] No explicit approval for low-confidence change (${input.filePath}); skipping import.\n`);
+    return false;
+}
+async function requestReviewNotesApproval(input) {
+    const hasLowConfidence = /\blow-confidence\b/i.test(input.analysisText) ||
+        /^\s*REVIEW_NOTES\b/im.test(input.analysisText);
+    if (!hasLowConfidence)
+        return "approve";
+    const selected = await (0, interaction_1.requestSelectionFromController)({
+        title: "ACP review notes detected",
+        message: "ACP analysis reported low-confidence review notes. Apply sync result now or stop for manual review?",
+        options: [
+            { value: "approve", label: "Apply now" },
+            { value: "review-later", label: "Apply and review later" },
+            { value: "cancel", label: "Cancel sync" },
+        ],
+        allowSkip: true,
+        timeoutMs: 45_000,
+    });
+    if (selected === "approve" || selected === "review-later" || selected === "cancel") {
+        return selected;
+    }
+    input.stderr("[warn] No explicit review decision received for low-confidence notes; defaulting to review-later.\n");
+    return "review-later";
+}
+function printDiscoveredSummary(files, stdout) {
+    const byCat = {
+        governance: files.filter((f) => f.category === "governance"),
+        spec: files.filter((f) => f.category === "spec"),
+        decision: files.filter((f) => f.category === "decision"),
+        config: files.filter((f) => f.category === "config"),
+    };
+    stdout(`\nDiscovered ${files.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`);
+}
+const INGESTION_CONCURRENCY = 5;
+async function mapWithConcurrency(items, concurrency, fn) {
+    const results = [];
+    let index = 0;
+    async function worker() {
+        while (index < items.length) {
+            const i = index++;
+            results[i] = await fn(items[i]);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => worker()));
+    return results;
+}
+function runGovernanceHealthCheck(repoPath, deps) {
+    try {
+        const config = (0, check_1.loadConfig)(repoPath);
+        const scan = (0, check_1.scanRepo)(repoPath, config);
+        const checkResults = check_1.checks.map((check) => check.run({ repoPath, config, scan }));
+        const score = (0, check_1.calculateScore)(checkResults);
+        const grade = (0, check_1.assignGrade)(score);
+        const allFindings = [];
+        for (const result of checkResults) {
+            allFindings.push(...result.findings);
+        }
+        // Sort findings by potential points (most impactful first)
+        const actionableFindings = allFindings
+            .filter((f) => f.speknCta)
+            .sort((a, b) => {
+            const severityOrder = { error: 3, warning: 2, info: 1 };
+            return (severityOrder[b.severity] ?? 0) - (severityOrder[a.severity] ?? 0);
+        });
+        // Render the health report
+        const maxScore = checkResults.reduce((sum, r) => sum + r.maxScore, 0);
+        deps.stdout(`\n\u{1F4CA} Governance Health: ${grade} (${score}/100, raw ${checkResults.reduce((s, r) => s + r.score, 0)}/${maxScore})\n`);
+        const passedChecks = checkResults.filter((r) => r.score === r.maxScore);
+        const failedChecks = checkResults.filter((r) => r.score < r.maxScore);
+        for (const finding of actionableFindings.slice(0, 5)) {
+            const icon = finding.severity === "error" ? "\u{26A0}" : finding.severity === "warning" ? "\u{26A0}" : "\u{2139}";
+            deps.stdout(`  ${icon} ${finding.message}\n`);
+        }
+        for (const check of passedChecks) {
+            deps.stdout(`  \u{2713} ${check.name}\n`);
+        }
+        if (failedChecks.length > 0 && actionableFindings.length > 5) {
+            deps.stdout(`  ... and ${actionableFindings.length - 5} more recommendation(s)\n`);
+        }
+        return { grade, score, findings: allFindings, checkResults };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        deps.stderr(`[warn] Governance health check failed: ${msg}\n`);
+        return null;
+    }
+}
+async function runIngestionEngine(params) {
+    const { client, projectId, options, changedFileSet, hasBaselineCommit, deps } = params;
+    deps.stdout("\nScanning repository for spec-like files...\n");
+    const discoveredBase = (0, common_1.discoverFiles)(options.repoPath).filter((file) => /\.(md|mdx|rules|cursorrules)$/i.test(file.relativePath));
+    const discovered = hasBaselineCommit
+        ? discoveredBase.filter((file) => changedFileSet.has(file.relativePath))
+        : discoveredBase;
+    const scopedDiscovered = discovered.slice(0, options.maxFiles);
+    if (scopedDiscovered.length === 0) {
+        deps.stdout("No spec-like files found to analyze.\n");
+        return true;
+    }
+    if (options.dryRun) {
+        deps.stdout(`[dry-run] Found ${scopedDiscovered.length} analyzable file(s):\n`);
+        for (const file of scopedDiscovered) {
+            deps.stdout(`  - ${file.relativePath}\n`);
+        }
+        deps.stdout("[dry-run] Skipping ingestion analysis and import.\n");
+        return true;
+    }
+    // Run governance health check before file-level analysis
+    const healthReport = runGovernanceHealthCheck(options.repoPath, deps);
+    deps.stdout(`Analyzing ${scopedDiscovered.length} file(s) for drift against SaaS spec storage...\n`);
+    const clientAny = client;
+    const latestSpecs = await clientAny.specification.list.query({
+        projectId,
+        limit: 1,
+        offset: 0,
+    });
+    const latestSpecContent = String(latestSpecs?.[0]?.content ?? "");
+    let scannedCount = 0;
+    let importedCount = 0;
+    let skippedDuplicateCount = 0;
+    let skippedConflictCount = 0;
+    let skippedUnapprovedCount = 0;
+    let totalScore = 0;
+    let totalFindings = 0;
+    let highSeverityFindings = 0;
+    const fileResults = await mapWithConcurrency(scopedDiscovered, INGESTION_CONCURRENCY, async (file) => {
+        let content = "";
+        try {
+            content = fs.readFileSync(file.absolutePath, "utf-8");
+        }
+        catch {
+            deps.stderr(`[warn] Could not read ${file.relativePath}, skipping.\n`);
+            return null;
+        }
+        if (content.trim().length === 0)
+            return null;
+        try {
+            const analyzed = await clientAny.ingestion.analyzeContent.mutate({
+                content,
+                filename: file.relativePath,
+            });
+            const alignment = await clientAny.ingestion.analyzeAlignment.mutate({
+                projectId,
+                result: analyzed,
+            });
+            const score = Number(alignment?.score ?? 100);
+            const findings = Array.isArray(alignment?.findings)
+                ? alignment.findings
+                : [];
+            const perFileHigh = findings.filter((finding) => finding?.severity === "high").length;
+            const importDecision = decideImport(analyzed, findings, latestSpecContent);
+            const importLabel = options.importToProject
+                ? importDecision.shouldImport
+                    ? "import=applied"
+                    : `import=skipped(${importDecision.reason})`
+                : "import=disabled";
+            deps.stdout(`  - ${file.relativePath}: score=${score}, findings=${findings.length}, high=${perFileHigh}, ${importLabel}\n`);
+            const result = {
+                scanned: true,
+                imported: false,
+                skippedDuplicate: false,
+                skippedConflict: false,
+                skippedUnapproved: false,
+                score,
+                findings: findings.length,
+                highFindings: perFileHigh,
+            };
+            if (options.importToProject && importDecision.shouldImport) {
+                const lowConfidence = score < 85 || perFileHigh > 0 || findings.length >= 8;
+                const approved = lowConfidence
+                    ? await approveLowConfidenceImport({
+                        filePath: file.relativePath,
+                        score,
+                        findingCount: findings.length,
+                        highCount: perFileHigh,
+                        stderr: deps.stderr,
+                    })
+                    : true;
+                if (approved) {
+                    await clientAny.ingestion.confirmIngestion.mutate({
+                        projectId,
+                        result: analyzed,
+                    });
+                    result.imported = true;
+                }
+                else {
+                    result.skippedUnapproved = true;
+                }
+            }
+            else if (options.importToProject &&
+                importDecision.reason === "duplicate") {
+                result.skippedDuplicate = true;
+            }
+            else if (options.importToProject &&
+                importDecision.reason === "high-conflict") {
+                result.skippedConflict = true;
+            }
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            deps.stderr(`[warn] Analysis failed for ${file.relativePath}: ${message}\n`);
+            return null;
+        }
+    });
+    for (const r of fileResults) {
+        if (!r || !r.scanned)
+            continue;
+        scannedCount += 1;
+        totalScore += r.score;
+        totalFindings += r.findings;
+        highSeverityFindings += r.highFindings;
+        if (r.imported)
+            importedCount += 1;
+        if (r.skippedDuplicate)
+            skippedDuplicateCount += 1;
+        if (r.skippedConflict)
+            skippedConflictCount += 1;
+        if (r.skippedUnapproved)
+            skippedUnapprovedCount += 1;
+    }
+    if (scannedCount > 0) {
+        const averageScore = Math.round(totalScore / scannedCount);
+        deps.stdout("\nDrift report summary:\n");
+        deps.stdout(`  Files analyzed : ${scannedCount}\n`);
+        deps.stdout(`  Avg score      : ${averageScore}\n`);
+        deps.stdout(`  Findings       : ${totalFindings}\n`);
+        deps.stdout(`  High severity  : ${highSeverityFindings}\n`);
+        if (healthReport) {
+            deps.stdout(`  Gov. health    : ${healthReport.grade} (${healthReport.score}/100)\n`);
+        }
+        if (options.importToProject) {
+            deps.stdout(`  Imported       : ${importedCount}\n`);
+            deps.stdout(`  Skipped (dup)  : ${skippedDuplicateCount}\n`);
+            deps.stdout(`  Skipped (conf) : ${skippedConflictCount}\n`);
+            deps.stdout(`  Skipped (approval) : ${skippedUnapprovedCount}\n`);
+        }
+        else {
+            deps.stdout("  Imported       : 0 (use --import-to-project to apply updates to SaaS specs/decisions)\n");
+        }
+    }
+    else {
+        deps.stdout("No readable files analyzed.\n");
+    }
+    return true;
+}
+async function runAcpEngine(params) {
+    const { projectId, options, organizationId, authToken, changedFileSet, hasBaselineCommit, commitContext, deps } = params;
+    deps.stdout("\nRunning ACP repo analysis for missing/conflicting specs...\n");
+    deps.stdout("\nScanning repository for analysis...\n");
+    const discoveredAll = (0, common_1.discoverFiles)(options.repoPath);
+    const discovered = hasBaselineCommit
+        ? discoveredAll.filter((file) => changedFileSet.has(file.relativePath))
+        : discoveredAll;
+    if (discovered.length > 0) {
+        printDiscoveredSummary(discovered, deps.stdout);
+    }
+    if (discovered.length === 0) {
+        deps.stdout("No changed files matched discovery filters for ACP analysis.\n");
+        return true;
+    }
+    if (options.dryRun) {
+        deps.stdout("\n[dry-run] Skipping ACP analysis.\n");
+        return true;
+    }
+    deps.stdout("\nResolving AI agent...\n");
+    const prompt = buildSyncAnalysisPrompt(projectId, options.repoPath, discovered, commitContext, organizationId);
+    const result = await (0, common_1.runAnalysisWithAgent)({
+        apiUrl: options.apiUrl,
+        agentName: options.agent,
+        prompt,
+        repoPath: options.repoPath,
+        mcpUrl: options.mcpUrl,
+        authToken,
+        organizationId,
+        requiredTools: [
+            "spekn_spec_list",
+            "spekn_spec_update",
+            "spekn_decision_update",
+        ],
+        stdout: deps.stdout,
+        stderr: deps.stderr,
+        debug: options.debug,
+        acpTimeoutMs: options.acpTimeoutMs,
+    });
+    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 false;
+    }
+    const reviewDecision = await requestReviewNotesApproval({
+        analysisText: result.text,
+        stderr: deps.stderr,
+    });
+    if (reviewDecision === "cancel") {
+        deps.stderr("Sync cancelled by reviewer due to ACP low-confidence review notes.\n");
+        return false;
+    }
+    deps.stdout("\nSync ACP analysis complete.\n");
+    return true;
+}
+function printHelp(stderr) {
+    stderr(`
+repo sync - Sync git repository metadata with Spekn
+
+USAGE:
+  spekn repo sync --project-id <uuid> [options]
+
+OPTIONS:
+  --project-id <uuid>   Project ID that owns the repository (optional if .spekn/context is present)
+  --analyze             Run ingestion drift analysis after syncing metadata (default: true)
+  --no-analyze          Skip ingestion drift analysis
+  --import-to-project   Import analyzed files with novel content into project specs/decisions
+  --max-files <n>       Maximum files to analyze during drift scan (default: 50)
+  --analysis-engine <mode>  Analysis mode: ingestion | acp | both (default: both)
+  --agent <name>        ACP agent for prompt analysis (codex, claude, opencode, ...)
+  --acp-timeout <ms>    ACP session timeout in milliseconds (0 = infinite, default: 0)
+  --path <dir>          Repository root path (default: current directory)
+  --api-url <url>       API base URL (default: SPEKN_API_URL or https://app.spekn.com)
+  --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
+  ACP_AGENT_TIMEOUT_MS  ACP session timeout in milliseconds (default: 0 = infinite)
+
+DESCRIPTION:
+  Reads the 'origin' remote URL from the current git repository, looks up the
+  matching registered repository in the project, and updates its name and
+  default branch to match the local git state.
+
+  With analysis enabled (default), repo sync runs:
+  - ingestion drift scan (local files vs SaaS specs), and
+  - ACP prompt analysis for missing/conflicting specs and decisions.
+  Use --analysis-engine to limit to one mode.
+
+EXAMPLES:
+  spekn repo sync --project-id 11111111-1111-4111-8111-111111111111
+  spekn repo sync --project-id 11111111-1111-4111-8111-111111111111 --analyze
+  spekn repo sync --project-id 11111111-1111-4111-8111-111111111111 --import-to-project
+`);
+}
+function parseArgs(args) {
+    const opts = {
+        ...(0, common_1.commonDefaults)(true),
+        importToProject: false,
+        maxFiles: 50,
+        analysisEngine: "both",
+    };
+    for (let i = 0; i < args.length;) {
+        const consumed = (0, common_1.parseCommonFlag)(args, i, opts);
+        if (consumed > 0) {
+            i += consumed;
+            continue;
+        }
+        const arg = args[i];
+        if (arg === "--import-to-project") {
+            opts.importToProject = true;
+            i += 1;
+            continue;
+        }
+        if (arg === "--max-files" && args[i + 1]) {
+            const parsed = Number(args[i + 1]);
+            if (Number.isFinite(parsed) && parsed > 0) {
+                opts.maxFiles = Math.min(500, Math.floor(parsed));
+            }
+            i += 2;
+            continue;
+        }
+        if (arg?.startsWith("--max-files=")) {
+            const parsed = Number(arg.slice("--max-files=".length));
+            if (Number.isFinite(parsed) && parsed > 0) {
+                opts.maxFiles = Math.min(500, Math.floor(parsed));
+            }
+            i += 1;
+            continue;
+        }
+        if (arg === "--analysis-engine" && args[i + 1]) {
+            const value = args[i + 1]?.toLowerCase();
+            if (value === "ingestion" || value === "acp" || value === "both") {
+                opts.analysisEngine = value;
+            }
+            i += 2;
+            continue;
+        }
+        if (arg?.startsWith("--analysis-engine=")) {
+            const value = arg.slice("--analysis-engine=".length).toLowerCase();
+            if (value === "ingestion" || value === "acp" || value === "both") {
+                opts.analysisEngine = value;
+            }
+            i += 1;
+            continue;
+        }
+        i++; // skip unknown
+    }
+    return (0, common_1.finalizeOptions)(opts);
+}
+// ── Main ────────────────────────────────────────────────────────────
+async function runRepoSyncCli(args, deps = common_1.defaultDeps) {
+    try {
+        const options = parseArgs(args);
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.repo.sync",
+            level: "info",
+            message: "Starting repo sync",
+            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: Sync repository metadata ──────────────────────────
+        const git = (0, common_1.readGitMetadata)(options.repoPath, deps);
+        if (!git)
+            return 1;
+        deps.stdout(`Syncing repository "${git.name}" (${git.remoteUrl})\n`);
+        deps.stdout(`  Default branch : ${git.defaultBranch}\n`);
+        deps.stdout(`  Project        : ${projectId}\n`);
+        const client = (0, common_1.createApiClient)(options.apiUrl, authToken, organizationId);
+        // Find matching repository
+        const repos = 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        await client.gitRepository.list.query({
+            projectId,
+            limit: 100,
+            offset: 0,
+        });
+        const match = repos.find((r) => r.repositoryUrl === git.remoteUrl);
+        if (!match) {
+            deps.stderr(`Error: No registered repository found for URL "${git.remoteUrl}" in project ${projectId}.\n` +
+                "Use 'spekn repo register' to register this repository first.\n");
+            return 1;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        await client.gitRepository.update.mutate({
+            projectId,
+            id: match.id,
+            data: { name: git.name, defaultBranch: git.defaultBranch },
+        });
+        (0, project_context_1.persistProjectContextWithoutRepoPath)(options.repoPath, {
+            projectId,
+            organizationId: organizationId || undefined,
+        });
+        deps.stdout(`Repository synced successfully. ID: ${match.id}\n`);
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.repo.sync",
+            level: "info",
+            message: "Repository metadata synced",
+            details: { projectId, repositoryId: match.id },
+        });
+        const headCommit = readHeadCommit(options.repoPath, deps);
+        const previousState = loadRepoSyncState(options.repoPath, projectId);
+        const lastSyncCommit = previousState.lastHeadCommit;
+        const hasBaselineCommit = typeof lastSyncCommit === "string" && lastSyncCommit.length > 0;
+        const changedFilesSinceLast = hasBaselineCommit && headCommit && lastSyncCommit !== headCommit
+            ? readChangedFilesSince(options.repoPath, lastSyncCommit, headCommit, deps)
+            : [];
+        const changedFileSet = new Set(changedFilesSinceLast);
+        const commitContext = hasBaselineCommit
+            ? headCommit && lastSyncCommit !== headCommit
+                ? `LAST_SYNC_COMMIT: ${lastSyncCommit}\nCURRENT_HEAD_COMMIT: ${headCommit}\nCHANGED_FILES_COUNT: ${changedFilesSinceLast.length}`
+                : `LAST_SYNC_COMMIT: ${lastSyncCommit}\nCURRENT_HEAD_COMMIT: ${headCommit ?? "unknown"}\nCHANGED_FILES_COUNT: 0`
+            : `LAST_SYNC_COMMIT: (none)\nCURRENT_HEAD_COMMIT: ${headCommit ?? "unknown"}\nCHANGED_FILES_COUNT: full-scan`;
+        if (hasBaselineCommit) {
+            deps.stdout(`Change scope: ${lastSyncCommit}..${headCommit ?? "HEAD"} (${changedFilesSinceLast.length} file(s))\n`);
+        }
+        else {
+            deps.stdout("No previous sync checkpoint found. Running full repository scan.\n");
+        }
+        // ── Phase 2: Analysis (optional) ─────────────────────────────────
+        if (!options.analyze) {
+            if (headCommit) {
+                saveRepoSyncState(options.repoPath, projectId, organizationId, {
+                    lastHeadCommit: headCommit,
+                    syncedAt: new Date().toISOString(),
+                });
+            }
+            return 0;
+        }
+        if (hasBaselineCommit && changedFilesSinceLast.length === 0) {
+            deps.stdout("No changes detected since last sync commit. Skipping analysis.\n");
+            if (headCommit) {
+                saveRepoSyncState(options.repoPath, projectId, organizationId, {
+                    lastHeadCommit: headCommit,
+                    syncedAt: new Date().toISOString(),
+                });
+            }
+            return 0;
+        }
+        const engine = options.analysisEngine;
+        let ingestionOk = true;
+        let acpOk = true;
+        if (hasBaselineCommit && changedFilesSinceLast.length > 0) {
+            const changedCodeFiles = changedFilesSinceLast.filter(looksLikeCodeFile);
+            const changedSpecDecisionFiles = changedFilesSinceLast.filter(looksLikeSpecOrDecisionUpdate);
+            deps.stdout(`Changed scope review: code=${changedCodeFiles.length}, spec/decision-docs=${changedSpecDecisionFiles.length}\n`);
+            if (changedCodeFiles.length > 0 &&
+                changedSpecDecisionFiles.length === 0) {
+                deps.stderr("[warn] Code changed since last sync but no spec/decision documentation files changed.\n");
+                const selected = await (0, interaction_1.requestSelectionFromController)({
+                    title: "Spec/decision coverage check",
+                    message: "Code changed since last sync but no spec/decision docs changed. Continue sync anyway?",
+                    options: [
+                        { value: "continue", label: "Continue sync" },
+                        { value: "cancel", label: "Cancel sync for manual review" },
+                    ],
+                    allowSkip: true,
+                    timeoutMs: 45_000,
+                });
+                if (selected === "cancel" || selected === "skip") {
+                    deps.stderr("Sync cancelled by reviewer due to missing spec/decision updates.\n");
+                    return 1;
+                }
+            }
+        }
+        const ingestionParams = {
+            client,
+            projectId,
+            options,
+            changedFileSet,
+            hasBaselineCommit,
+            deps,
+        };
+        const canRunAcp = Boolean(organizationId && authToken);
+        if ((engine === "acp" || engine === "both") && !canRunAcp) {
+            if (!organizationId) {
+                deps.stderr("Warning: No organization ID. Skipping ACP analysis. Re-run 'spekn auth login' or set SPEKN_ORGANIZATION_ID.\n");
+            }
+            else {
+                deps.stderr("Warning: Not authenticated. Skipping ACP analysis. Run 'spekn auth login' first.\n");
+            }
+            acpOk = false;
+        }
+        const acpParams = (engine === "acp" || engine === "both") && canRunAcp
+            ? {
+                projectId,
+                options: options,
+                organizationId: organizationId,
+                authToken: authToken,
+                changedFileSet,
+                hasBaselineCommit,
+                commitContext,
+                deps,
+            }
+            : null;
+        if (engine === "both" && acpParams) {
+            const [ingestionResult, acpResult] = await Promise.all([
+                runIngestionEngine(ingestionParams),
+                runAcpEngine({ ...acpParams, options: { ...acpParams.options, acpTimeoutMs: options.acpTimeoutMs } }),
+            ]);
+            ingestionOk = ingestionResult;
+            acpOk = acpResult;
+        }
+        else if (engine === "ingestion" || (engine === "both" && !acpParams)) {
+            ingestionOk = await runIngestionEngine(ingestionParams);
+        }
+        else if (engine === "acp" && acpParams) {
+            acpOk = await runAcpEngine({ ...acpParams, options: { ...acpParams.options, acpTimeoutMs: options.acpTimeoutMs } });
+        }
+        const analysisOk = options.analysisEngine === "both"
+            ? ingestionOk || acpOk
+            : options.analysisEngine === "ingestion"
+                ? ingestionOk
+                : acpOk;
+        if (options.analysisEngine === "both" && ingestionOk && !acpOk) {
+            deps.stderr("Warning: ACP analysis failed, but ingestion sync succeeded. Treating sync as completed with warnings.\n");
+        }
+        const exitCode = analysisOk ? 0 : 1;
+        if (exitCode === 0 && headCommit) {
+            saveRepoSyncState(options.repoPath, projectId, organizationId, {
+                lastHeadCommit: headCommit,
+                syncedAt: new Date().toISOString(),
+            });
+        }
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.repo.sync",
+            level: exitCode === 0 ? "info" : "error",
+            message: "Repo sync completed",
+            details: {
+                exitCode,
+                analyzed: options.analyze,
+                projectId,
+                analysisEngine: options.analysisEngine,
+                ingestionOk,
+                acpOk,
+            },
+        });
+        return exitCode;
+    }
+    catch (error) {
+        if (error instanceof common_1.HelpRequestedError) {
+            printHelp(deps.stderr);
+            return 0;
+        }
+        deps.stderr(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+        (0, structured_log_1.appendCliStructuredLog)({
+            source: "cli.repo.sync",
+            level: "error",
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return 1;
+    }
+}
+async function main() {
+    const exitCode = await runRepoSyncCli(process.argv.slice(2));
+    process.exit(exitCode);
+}
+if (require.main === module) {
+    void main();
+}