@pruddiman/hem 0.0.1-beta-5671db0

package/dist/index.js

@@ -0,0 +1,1087 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for Hem.
+ *
+ * Configures Commander.js with all options, the `auth` subcommand, and
+ * dispatches to either auth handling or the main generation pipeline.
+ *
+ * Pipeline (v2):
+ *   1. Parse CLI args
+ *   2. If auth subcommand -> dispatch and exit
+ *   3. If --api-key without --model -> exit with error
+ *   4. Load preferences
+ *   5. If --model flag -> override preferences
+ *   6. Start OpenCode server via createOpencode()
+ *   7. If --api-key -> inject via injectApiKey()
+ *   8. detectAuthState()
+ *   9. If no credentials and no model override -> handleFirstRun()
+ *  10. Pipeline: discovery -> grouping -> exploration -> generation
+ *      -> organization -> crossref -> architecture -> TOC -> complete
+ *
+ * Reference: FR-001, FR-022a.
+ */
+import { Command } from "commander";
+import { createRequire } from "node:module";
+import { resolve, join } from "node:path";
+import { realpathSync } from "node:fs";
+import { access, readFile } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import fg from "fast-glob";
+import { fileURLToPath } from "node:url";
+import { loadPreferences, loadProjectConfig, saveProjectConfig, detectAuthState, injectApiKey, handleFirstRun, renderAndWait, handleAuthLogin, handleAuthList, handleAuthLogout, validateStoredModel, resolveActualModel, listProviderModels, INVALID_MODEL_WARNING, AuthExpiredError, INVALID_API_KEY_ERROR, ZenCatalogError, PROJECT_CONFIG_DIR, } from "./auth.js";
+import { createOpencode } from "@opencode-ai/sdk";
+import { findFreePort, trackServer, untrackServer, startWithRetry } from "./server-utils.js";
+import { discoverFiles, detectProjectName } from "./discovery.js";
+import { groupFiles } from "./grouping.js";
+import { GroupingAgent } from "./agents/grouping-agent.js";
+import { DocumentationAgent } from "./agents/documentation-agent.js";
+import { ArchitectureAgent } from "./agents/architecture-agent.js";
+import { IndexAgent } from "./agents/index-agent.js";
+import { OrganizationAgent } from "./agents/organization-agent.js";
+import { CrossRefAgent } from "./agents/crossref-agent.js";
+import { ExplorationAgent } from "./agents/exploration-agent.js";
+import { OpenCodeProvider } from "./providers/opencode.js";
+import { CopilotProvider } from "./providers/copilot.js";
+import { generateDocumentation, getExitCode } from "./orchestrator.js";
+import { SearchIndex } from "./search-index.js";
+import { computeMaxConcurrency, describeResourceLimits, LARGE_PROJECT_THRESHOLD, computeAgentsPerGroup } from "./resources.js";
+// Re-export getExitCode so existing imports from index.ts continue to work.
+export { getExitCode };
+import { renderDashboard, ConfigPrompt } from "./progress.js";
+import { generateTableOfContents, generateTocLinkList, replaceTocPlaceholder, writeTableOfContents, writeArchitectureOverview, scanDocFiles, ensureDestinationDir, removeEmptyDirs, } from "./output.js";
+import { readLastSHA, computeChangedFiles, getCurrentSHA, detectChangedDocs, writeChangelogEntry, } from "./changelog.js";
+import { scopeToChangedFiles } from "./diff-scope.js";
+import { getRepoRoot, getCurrentBranch, generateWorktreeBranch, ensureGitignored, setupWorktree, commitWorktree, pushWorktree, cleanupWorktree, } from "./worktree.js";
+import React from "react";
+// ── Version ────────────────────────────────────────────────────────────
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+/** Default (production) dependency bag. */
+export const defaultDeps = {
+    createOpencode,
+    findFreePort,
+    startWithRetry,
+    loadPreferences,
+    detectAuthState,
+    injectApiKey,
+    handleFirstRun,
+    handleAuthLogin,
+    handleAuthList,
+    handleAuthLogout,
+    loadProjectConfig,
+    saveProjectConfig,
+    renderAndWait,
+    validateStoredModel,
+    resolveActualModel,
+    listProviderModels,
+    checkSourceExists: (path) => access(path),
+    discoverFiles,
+    detectProjectName,
+    groupFiles,
+    createProvider: async (config) => {
+        const pid = config.model.providerID;
+        if (pid === "github-copilot" || pid === "copilot") {
+            return CopilotProvider.create(config);
+        }
+        return OpenCodeProvider.create(config);
+    },
+    generateDocumentation,
+    renderDashboard,
+    generateTableOfContents,
+    writeTableOfContents,
+    writeArchitectureOverview,
+    scanDocFiles,
+    ensureDestinationDir,
+    removeEmptyDirs,
+    readLastSHA,
+    computeChangedFiles,
+    getCurrentSHA,
+    detectChangedDocs,
+    writeChangelogEntry,
+    scopeToChangedFiles,
+};
+// ── Search index helpers ────────────────────────────────────────────────
+/**
+ * Build/update the FTS search index from `.md` files in `destinationPath`.
+ *
+ * Uses a two-pass strategy:
+ *  1. **Git-diff fast path**: if the destination is tracked by git, only
+ *     re-index files that changed since HEAD (falls back to hash scan on error).
+ *  2. **Hash scan**: glob all `*.md` files, call `SearchIndex.upsertDoc` for
+ *     each — the method is a no-op when the SHA-256 hash is unchanged.
+ *  3. **Deletion sweep**: remove index entries for paths no longer on disk.
+ */
+async function updateSearchIndex(index, destinationPath, verbose) {
+    let mdFiles;
+    try {
+        mdFiles = await fg("**/*.md", {
+            cwd: destinationPath,
+            absolute: false,
+            onlyFiles: true,
+            dot: false,
+        });
+    }
+    catch {
+        return; // destination doesn't exist yet
+    }
+    if (mdFiles.length === 0)
+        return;
+    // Try git-diff fast path: only re-index files that changed since HEAD
+    let changedPaths = null;
+    try {
+        const output = execFileSync("git", ["-C", destinationPath, "diff", "--name-only", "HEAD", "--", "*.md"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+        const changed = output.trim().split("\n").filter(Boolean);
+        // Only use git fast path when it returns a strict subset (otherwise full scan is equally cheap)
+        if (changed.length < mdFiles.length) {
+            changedPaths = new Set(changed);
+        }
+    }
+    catch {
+        // git unavailable or no HEAD — fall through to full hash scan
+    }
+    const toIndex = changedPaths ? mdFiles.filter((p) => changedPaths.has(p)) : mdFiles;
+    let indexed = 0;
+    let skipped = 0;
+    for (const relPath of toIndex) {
+        try {
+            const content = await readFile(join(destinationPath, relPath), "utf-8");
+            const wasUpdated = index.upsertDoc(relPath, content);
+            if (wasUpdated)
+                indexed++;
+            else
+                skipped++;
+        }
+        catch {
+            // file unreadable — skip
+        }
+    }
+    // Deletion sweep: remove index entries for docs no longer on disk
+    const currentPaths = new Set(mdFiles);
+    let removed = 0;
+    for (const [path] of index.getAllHashes()) {
+        if (!currentPaths.has(path)) {
+            index.removeDoc(path);
+            removed++;
+        }
+    }
+    if (verbose) {
+        verbose(`[search-index] Updated: ${indexed} indexed, ${skipped} unchanged, ${removed} removed` +
+            (changedPaths ? " (git-diff fast path)" : " (full hash scan)"));
+    }
+}
+/**
+ * Records source-file → doc-file mappings in the search index.
+ *
+ * For each group, finds doc files whose path shares a segment with the
+ * group's directory or file paths, then maps the group's source files
+ * to those docs.
+ *
+ * This is a best-effort heuristic; paths without clear overlap are skipped.
+ */
+function buildSourceDocMappings(index, docFiles, groups, _destinationPath) {
+    for (const group of groups) {
+        const groupSegments = new Set([
+            group.id,
+            ...group.id.split(/[-_/]+/).filter((s) => s.length > 2),
+            ...group.files.flatMap((f) => f.path.split(/[/\\]+/)).filter((s) => s.length > 2),
+        ]);
+        const matchingDocs = docFiles.filter((docPath) => {
+            const docSegments = docPath.replace(/\.md$/, "").split(/[/\\]+/);
+            return docSegments.some((seg) => groupSegments.has(seg));
+        });
+        const sourcePaths = group.files.map((f) => f.path);
+        for (const docPath of matchingDocs) {
+            index.setSourceMappings(docPath, sourcePaths);
+        }
+    }
+}
+// ── Handlers ───────────────────────────────────────────────────────────
+/**
+ * Handle the default generate command.
+ *
+ * Implements the full startup sequence and v2 pipeline:
+ *   1. Parse CLI flags, validate constraints.
+ *   2. Load preferences.
+ *   3. Resolve model.
+ *   4. Start OpenCode server for auth.
+ *   5. Inject API key if provided.
+ *   6. Detect auth state.
+ *   7. First-run flow if needed.
+ *   8. Resolve absolute paths.
+ *   9. Start Ink dashboard.
+ *  10. Pipeline:
+ *      a. Discovery
+ *      b. Start orchestrator
+ *      c. Grouping (LLM + heuristic fallback)
+ *      d. Exploration (parallel)
+ *      e. Documentation (parallel — agents write files directly)
+ *      f. Organization (post-processing)
+ *      g. Cross-references (post-processing)
+ *      h. Architecture overview (post-processing)
+ *      i. TOC generation (programmatic, scans disk)
+ *  11. Exit with appropriate exit code.
+ *
+ * @param opts - Parsed CLI flags from Commander.
+ * @param deps - Injectable dependencies.
+ * @returns The resolved `CLIOptions`, or `null` if the user exited early.
+ */
+export async function handleGenerate(opts, deps = defaultDeps) {
+    // ── Step 1: Validate --api-key requires --model ────────────────────
+    if (opts.apiKey && !opts.model) {
+        process.stderr.write("--api-key requires --model to specify which provider to use.\n" +
+            "  Example: npx @pruddiman/hem --model anthropic/claude-sonnet-4 --api-key sk-ant-xxx\n");
+        process.exitCode = 2;
+        return null;
+    }
+    const cliOptions = {
+        source: opts.source,
+        destination: opts.destination,
+        files: opts.files,
+        concurrency: opts.concurrency,
+        model: opts.model,
+        apiKey: opts.apiKey,
+        name: opts.name,
+        verbose: opts.verbose ?? false,
+        full: opts.full ?? false,
+        worktree: opts.worktree ?? false,
+        command: "generate",
+        authAction: undefined,
+        authTarget: undefined,
+    };
+    // ── Step 1b: Exit if project not configured ────────────────────────
+    const projectConfig = await deps.loadProjectConfig();
+    if (!projectConfig && !cliOptions.model && !cliOptions.apiKey) {
+        process.stderr.write("This project has not been configured for Hem.\n" +
+            "Run `hem config` to select a provider and model for this project.\n");
+        process.exitCode = 2;
+        return null;
+    }
+    // ── Step 2: Load preferences ───────────────────────────────────────
+    const preferences = await deps.loadPreferences();
+    // ── Step 3: Resolve model (--model flag > project config > preferences) ─
+    let resolvedModel;
+    let modelFromPreferences = false;
+    if (cliOptions.model) {
+        const slashIndex = cliOptions.model.indexOf("/");
+        if (slashIndex > 0) {
+            resolvedModel = {
+                providerID: cliOptions.model.slice(0, slashIndex),
+                modelID: cliOptions.model.slice(slashIndex + 1),
+            };
+        }
+        else {
+            resolvedModel = { providerID: cliOptions.model, modelID: "default" };
+        }
+    }
+    else if (projectConfig?.model) {
+        resolvedModel = projectConfig.model;
+    }
+    else if (preferences?.model) {
+        resolvedModel = preferences.model;
+        modelFromPreferences = true;
+    }
+    // ── Step 4: Start OpenCode server ──────────────────────────────────
+    const { client, server } = await deps.startWithRetry(async () => {
+        const port = await deps.findFreePort();
+        return deps.createOpencode({ port });
+    });
+    trackServer(() => server.close());
+    let authState;
+    let modelLabel = "default";
+    let providerLabel = "Default";
+    try {
+        // ── Step 5: Inject API key if provided ─────────────────────────────
+        if (cliOptions.apiKey && cliOptions.model) {
+            await deps.injectApiKey(client, cliOptions.model, cliOptions.apiKey);
+        }
+        // ── Step 6: Detect auth state ──────────────────────────────────────
+        authState = await deps.detectAuthState(client);
+        if (cliOptions.verbose) {
+            const providers = authState.connectedProviders.length > 0
+                ? authState.connectedProviders.map((p) => `${p.id} (${p.authMethod})`).join(", ")
+                : "none";
+            process.stderr.write(`[auth] Detected providers: ${providers}\n`);
+            process.stderr.write(`[auth] Has credentials: ${authState.hasCredentials}\n`);
+        }
+        // ── T045: Edge case — stored model no longer available ─────────────
+        if (modelFromPreferences && resolvedModel && preferences) {
+            const isValid = await deps.validateStoredModel(client, preferences);
+            if (!isValid) {
+                const warning = INVALID_MODEL_WARNING
+                    .replace("{providerID}", resolvedModel.providerID)
+                    .replace("{modelID}", resolvedModel.modelID);
+                process.stderr.write(warning);
+                resolvedModel = undefined;
+            }
+        }
+        // ── Step 7: First-run flow if needed ───────────────────────────────
+        if ((!authState.hasCredentials && !resolvedModel) ||
+            (modelFromPreferences && !resolvedModel)) {
+            let firstRunResult;
+            try {
+                firstRunResult = await deps.handleFirstRun(client);
+            }
+            catch (firstRunError) {
+                if (firstRunError instanceof ZenCatalogError) {
+                    process.stderr.write(firstRunError.message);
+                }
+                else {
+                    const errorMsg = firstRunError instanceof Error
+                        ? firstRunError.message
+                        : String(firstRunError);
+                    process.stderr.write(errorMsg + "\n");
+                }
+                process.exitCode = 2;
+                return null;
+            }
+            if (firstRunResult === null) {
+                process.exitCode = 0;
+                return null;
+            }
+            resolvedModel = firstRunResult;
+        }
+        // ── Fallback model assignment ──────────────────────────────────────
+        if (!resolvedModel) {
+            resolvedModel = { providerID: "opencode", modelID: "default" };
+        }
+        // ── Resolve actual model/provider labels ────────────────────────────
+        const labels = await deps.resolveActualModel(client, resolvedModel);
+        modelLabel = labels.modelLabel;
+        providerLabel = labels.providerLabel;
+    }
+    finally {
+        server.close();
+        untrackServer();
+    }
+    if (cliOptions.verbose) {
+        const modelDesc = resolvedModel.modelID === "default"
+            ? `${resolvedModel.providerID} (server default)`
+            : `${resolvedModel.providerID}/${resolvedModel.modelID}`;
+        process.stderr.write(`[auth] Provider: ${resolvedModel.providerID}, Model: ${modelDesc}\n`);
+    }
+    // ── Worktree setup (--worktree flag) ────────────────────────────────
+    let worktreeState;
+    if (cliOptions.worktree) {
+        let repoRoot;
+        try {
+            repoRoot = getRepoRoot(process.cwd());
+        }
+        catch {
+            process.stderr.write("Error: --worktree requires a git repository. " +
+                "Run hem from inside a git repo.\n");
+            process.exitCode = 2;
+            return null;
+        }
+        const currentBranch = getCurrentBranch(repoRoot);
+        const branch = generateWorktreeBranch(currentBranch);
+        await ensureGitignored(repoRoot, ".hem/worktree/");
+        const wtPath = setupWorktree(repoRoot, branch);
+        worktreeState = { repoRoot, path: wtPath, branch };
+        if (cliOptions.verbose) {
+            process.stderr.write(`[worktree] Created branch ${branch} at ${wtPath}\n`);
+        }
+    }
+    // ── Step 8: Resolve absolute paths ─────────────────────────────────
+    const base = worktreeState?.path ?? process.cwd();
+    const absoluteSource = resolve(base, cliOptions.source);
+    const absoluteDestination = resolve(base, cliOptions.destination);
+    const projectName = cliOptions.name ?? await deps.detectProjectName(absoluteSource);
+    // Propagate resolved name so downstream code (orchestrator) never re-derives it.
+    cliOptions.name = projectName;
+    // ── T043: Edge case — source directory doesn't exist ─────────────
+    try {
+        await deps.checkSourceExists(absoluteSource);
+    }
+    catch {
+        process.stderr.write(`Source directory ${absoluteSource} does not exist.\n`);
+        process.exitCode = 2;
+        return null;
+    }
+    // ── Step 9: Start Ink dashboard ────────────────────────────────────
+    const startedAt = Date.now();
+    const initialState = {
+        phase: "discovery",
+        modelLabel,
+        providerLabel,
+        totalFiles: 0,
+        binaryFilesSkipped: 0,
+        totalGroups: 0,
+        featureGroups: 0,
+        layerGroups: 0,
+        totalPages: 0,
+        groupStatuses: [],
+        explorationStatuses: [],
+        explorationComplete: false,
+        indexFiles: [],
+        completedSessions: 0,
+        failedSessions: 0,
+        startedAt,
+        completedAt: undefined,
+        warnings: [],
+    };
+    const { updateState, waitUntilExit } = deps.renderDashboard(initialState, cliOptions.verbose);
+    try {
+        // ── Step 10a: Discovery phase ──────────────────────────────────────
+        const allFiles = await deps.discoverFiles(absoluteSource, cliOptions.files, absoluteDestination);
+        let textFiles = allFiles.filter((f) => !f.isBinary);
+        const binaryCount = allFiles.length - textFiles.length;
+        if (textFiles.length === 0) {
+            process.stderr.write(`No files found matching pattern "${cliOptions.files}" in ${absoluteSource}\n` +
+                "  Check your --source and --files options.\n");
+            process.exitCode = 2;
+            await waitUntilExit();
+            return null;
+        }
+        if (cliOptions.verbose) {
+            process.stderr.write(`[discovery] Found ${allFiles.length} files (${binaryCount} binary skipped)\n`);
+        }
+        // ── Step 10a′: Diff-scoped incremental generation ──────────────────
+        // When a previous run's SHA exists in changelog.md (and --full is not
+        // set), narrow textFiles to only those that changed since the last run.
+        let prevSHA = null;
+        try {
+            prevSHA = await deps.readLastSHA(absoluteDestination);
+        }
+        catch {
+            // changelog.md unreadable — treat as first run
+        }
+        if (cliOptions.full) {
+            // Check if docs already exist to warn about unpredictable behavior
+            const existingDocs = await deps.scanDocFiles(absoluteDestination);
+            if (existingDocs.length > 0) {
+                process.stderr.write("Warning: --full forces complete re-generation. " +
+                    "Behavior may be unpredictable when docs already exist.\n");
+            }
+        }
+        else if (prevSHA) {
+            try {
+                const changedPaths = deps.computeChangedFiles(absoluteSource, prevSHA);
+                if (changedPaths.length === 0) {
+                    process.stderr.write("No source changes since last run — skipping generation.\n");
+                    process.exitCode = 0;
+                    await waitUntilExit();
+                    return cliOptions;
+                }
+                textFiles = deps.scopeToChangedFiles(textFiles, changedPaths);
+                if (cliOptions.verbose) {
+                    process.stderr.write(`[diff-scope] ${changedPaths.length} source files changed since ${prevSHA.slice(0, 8)}; ` +
+                        `${textFiles.length} match discovery filter\n`);
+                }
+                // If all changed files were binary or outside the glob, skip
+                if (textFiles.length === 0) {
+                    process.stderr.write("Changed files do not match the discovery filter — skipping generation.\n");
+                    process.exitCode = 0;
+                    await waitUntilExit();
+                    return cliOptions;
+                }
+            }
+            catch (diffError) {
+                // Git failure (e.g., SHA no longer exists after rebase) — fall back to full scan
+                const msg = diffError instanceof Error ? diffError.message : String(diffError);
+                process.stderr.write(`Warning: Could not compute diff (${msg}). Falling back to full generation.\n`);
+            }
+        }
+        updateState({
+            phase: "grouping",
+            totalFiles: allFiles.length,
+            binaryFilesSkipped: binaryCount,
+        });
+        const verboseLog = cliOptions.verbose
+            ? (msg) => {
+                const ts = new Date().toISOString().slice(11, 23);
+                process.stderr.write(`[${ts}] ${msg}\n`);
+            }
+            : undefined;
+        // ── Step 10b: Start provider ─────────────────────────────────────
+        const hemDir = PROJECT_CONFIG_DIR;
+        const searchDbPath = join(hemDir, "search-index.db");
+        let provider;
+        try {
+            provider = await deps.createProvider({
+                model: resolvedModel,
+                destinationPath: absoluteDestination,
+                verbose: verboseLog,
+                searchDbPath,
+            });
+        }
+        catch (orchError) {
+            const errorMessage = orchError instanceof Error ? orchError.message : String(orchError);
+            process.stderr.write(errorMessage + "\n");
+            process.exitCode = 2;
+            await waitUntilExit();
+            return null;
+        }
+        // ── Step 10c: Grouping phase (LLM with heuristic fallback) ─────────
+        const groupingAgent = new GroupingAgent(provider, projectName);
+        let groups = await groupingAgent.run(textFiles, verboseLog, PROJECT_CONFIG_DIR);
+        if (!groups) {
+            if (cliOptions.verbose) {
+                verboseLog(`[grouping] LLM grouping unavailable, using heuristic fallback`);
+            }
+            groups = deps.groupFiles(textFiles);
+        }
+        const featureGroups = groups.filter((g) => g.type === "vertical").length;
+        const layerGroups = groups.filter((g) => g.type === "horizontal").length;
+        if (cliOptions.verbose) {
+            process.stderr.write(`[grouping] ${groups.length} groups (${featureGroups} feature, ${layerGroups} layer)\n`);
+        }
+        // Ensure destination directory exists before agents write to it
+        await deps.ensureDestinationDir(absoluteDestination);
+        // ── Open search index + update from existing docs ────────────────
+        // Build/refresh the FTS index over any existing .md files in the
+        // destination directory. This runs quickly on second+ runs because
+        // unchanged files are skipped via SHA-256 hash comparison.
+        const searchIndex = SearchIndex.open(searchDbPath);
+        await updateSearchIndex(searchIndex, absoluteDestination, verboseLog);
+        updateState({
+            phase: "generation",
+            totalGroups: groups.length,
+            featureGroups,
+            layerGroups,
+            totalPages: groups.length,
+            groupStatuses: groups.map((group) => ({
+                groupId: group.id,
+                label: group.label,
+                status: "queued",
+            })),
+        });
+        // ── Scaling detection ──────────────────────────────────────────────
+        const totalFileCount = textFiles.length;
+        const isLargeProject = totalFileCount > LARGE_PROJECT_THRESHOLD;
+        if (cliOptions.verbose) {
+            const agentsPerGroup = isLargeProject
+                ? computeAgentsPerGroup(totalFileCount)
+                : 1;
+            const maxConcurrency = computeMaxConcurrency(cliOptions.concurrency);
+            process.stderr.write(`[scaling] ${totalFileCount} source files, threshold=${LARGE_PROJECT_THRESHOLD}` +
+                ` → ${isLargeProject ? "multi-agent" : "single-agent"} mode\n`);
+            if (isLargeProject) {
+                process.stderr.write(`[scaling] Exploration & documentation: ${agentsPerGroup} agents per group, ` +
+                    `${groups.length} groups, concurrency=${maxConcurrency}\n`);
+                process.stderr.write(`[scaling] Post-processing: organization (dynamic workers), ` +
+                    `cross-references (parallel if >8 docs), ` +
+                    `architecture & index (chunked if needed)\n`);
+            }
+        }
+        // ── Step 10d+e: Exploration + Documentation phases ──────────────────
+        let results;
+        let explorationFindings = [];
+        try {
+            const docAgent = new DocumentationAgent(provider);
+            const exploreAgent = new ExplorationAgent(provider);
+            const genResult = await deps.generateDocumentation(docAgent, groups, cliOptions, (partial) => updateState(partial), exploreAgent, searchIndex);
+            results = genResult.results;
+            explorationFindings = genResult.explorationFindings;
+            // Collect all doc files from disk (not from agent results, which may
+            // under-report when sessions time out but still write files).
+            let allDocFiles = await deps.scanDocFiles(absoluteDestination);
+            allDocFiles = allDocFiles.filter(f => f !== "index.md" && f !== "architecture.md" && f !== "changelog.md");
+            // ── Update index with newly written docs + source-doc mappings ───
+            // Re-index any docs written during this run (hash check skips unchanged).
+            // Then record source-file → doc-file mappings for each group.
+            await updateSearchIndex(searchIndex, absoluteDestination, verboseLog);
+            buildSourceDocMappings(searchIndex, allDocFiles, groups, absoluteDestination);
+            // ── Step 10f: Organization phase ──────────────────────────────────
+            try {
+                updateState({ phase: "organization" });
+                const orgAgent = new OrganizationAgent(provider);
+                await orgAgent.run({
+                    projectName,
+                    destinationPath: absoluteDestination,
+                    allDocFiles,
+                }, verboseLog);
+                // Re-scan disk to discover what files exist after organization
+                allDocFiles = await deps.scanDocFiles(absoluteDestination);
+                allDocFiles = allDocFiles.filter(f => f !== "index.md" && f !== "architecture.md" && f !== "changelog.md");
+            }
+            catch (orgError) {
+                if (orgError instanceof AuthExpiredError) {
+                    throw orgError;
+                }
+                const orgMessage = orgError instanceof Error ? orgError.message : String(orgError);
+                updateState({
+                    warnings: [`Organization phase failed: ${orgMessage}`],
+                });
+            }
+            // ── Step 10g: Cross-references phase ──────────────────────────────
+            try {
+                updateState({ phase: "crossref" });
+                const xrefAgent = new CrossRefAgent(provider);
+                await xrefAgent.run({
+                    projectName,
+                    destinationPath: absoluteDestination,
+                    allDocFiles,
+                }, verboseLog);
+                // Re-scan disk to discover what files exist after cross-referencing
+                allDocFiles = await deps.scanDocFiles(absoluteDestination);
+                allDocFiles = allDocFiles.filter(f => f !== "index.md" && f !== "architecture.md" && f !== "changelog.md");
+            }
+            catch (xrefError) {
+                if (xrefError instanceof AuthExpiredError) {
+                    throw xrefError;
+                }
+                const xrefMessage = xrefError instanceof Error ? xrefError.message : String(xrefError);
+                updateState({
+                    warnings: [`Cross-reference phase failed: ${xrefMessage}`],
+                });
+            }
+            // ── Steps 10h+10i: Architecture overview + Index page (parallel) ───
+            // Both agents write independent files (architecture.md and index.md)
+            // and neither reads the other's output, so they can run concurrently.
+            updateState({ phase: "architecture" });
+            const archAgent = new ArchitectureAgent(provider);
+            const indexAgent = new IndexAgent(provider);
+            // The index agent's context mirrors what it would see in the sequential
+            // pipeline (where arch ran first): include architecture.md in the list
+            // even though it may not be written yet when index starts.
+            const allDocFilesWithArch = [...allDocFiles, "architecture.md"];
+            const [archSettled, indexSettled] = await Promise.allSettled([
+                archAgent.run({
+                    projectName,
+                    sourceRoot: resolve(cliOptions.source),
+                    destinationPath: absoluteDestination,
+                    allFindings: explorationFindings,
+                    allGroupSummaries: groups.map((group) => ({
+                        id: group.id,
+                        label: group.label,
+                        files: group.files.map((f) => f.path),
+                    })),
+                    allDocFiles,
+                }, verboseLog),
+                indexAgent.run({
+                    projectName,
+                    destinationPath: absoluteDestination,
+                    allDocFiles: allDocFilesWithArch,
+                    allFindings: explorationFindings,
+                    allGroupSummaries: groups.map((group) => ({
+                        id: group.id,
+                        label: group.label,
+                        files: group.files.map((f) => f.path),
+                    })),
+                }, verboseLog),
+            ]);
+            // Handle architecture result
+            if (archSettled.status === "rejected") {
+                if (archSettled.reason instanceof AuthExpiredError) {
+                    throw archSettled.reason;
+                }
+                const msg = archSettled.reason instanceof Error
+                    ? archSettled.reason.message
+                    : String(archSettled.reason);
+                updateState({
+                    warnings: [`Architecture overview generation failed: ${msg}`],
+                });
+            }
+            // Handle index result + TOC post-processing
+            {
+                updateState({ phase: "indexing" });
+                const indexFiles = [];
+                try {
+                    // Scan disk AFTER both agents complete so the TOC includes architecture.md
+                    const diskFiles = await deps.scanDocFiles(absoluteDestination);
+                    let indexWritten = false;
+                    if (indexSettled.status === "fulfilled") {
+                        try {
+                            // Read back what the agent wrote
+                            const indexPath = join(absoluteDestination, "index.md");
+                            const agentContent = await readFile(indexPath, "utf-8");
+                            // Replace <!-- TOC --> placeholder with procedural link list
+                            const tocLinkList = generateTocLinkList(projectName, diskFiles);
+                            const finalContent = replaceTocPlaceholder(agentContent, tocLinkList);
+                            await deps.writeTableOfContents(absoluteDestination, finalContent);
+                            indexWritten = true;
+                        }
+                        catch (agentErr) {
+                            if (agentErr instanceof AuthExpiredError) {
+                                throw agentErr;
+                            }
+                            const msg = agentErr instanceof Error ? agentErr.message : String(agentErr);
+                            if (verboseLog) {
+                                verboseLog(`[index-agent] Failed to post-process index.md, falling back to procedural TOC: ${msg}`);
+                            }
+                            updateState({
+                                warnings: [`Index page post-processing failed (using fallback): ${msg}`],
+                            });
+                        }
+                    }
+                    else {
+                        if (indexSettled.reason instanceof AuthExpiredError) {
+                            throw indexSettled.reason;
+                        }
+                        const msg = indexSettled.reason instanceof Error
+                            ? indexSettled.reason.message
+                            : String(indexSettled.reason);
+                        if (verboseLog) {
+                            verboseLog(`[index-agent] Failed, falling back to procedural TOC: ${msg}`);
+                        }
+                        updateState({
+                            warnings: [`Index page agent failed (using fallback): ${msg}`],
+                        });
+                    }
+                    // Fallback: procedural TOC generation
+                    if (!indexWritten) {
+                        const tocContent = deps.generateTableOfContents(projectName, diskFiles);
+                        await deps.writeTableOfContents(absoluteDestination, tocContent);
+                    }
+                    indexFiles.push("index.md");
+                }
+                catch (tocErr) {
+                    if (tocErr instanceof AuthExpiredError) {
+                        throw tocErr;
+                    }
+                    const msg = tocErr instanceof Error ? tocErr.message : String(tocErr);
+                    updateState({
+                        warnings: [`Table of contents generation failed: ${msg}`],
+                    });
+                }
+                if (indexFiles.length > 0) {
+                    updateState({ indexFiles });
+                }
+            }
+            // ── Step 10j: Remove empty directories left behind by agents ─────
+            await deps.removeEmptyDirs(absoluteDestination);
+        }
+        finally {
+            try {
+                await provider.cleanup();
+            }
+            catch (cleanupErr) {
+                console.error("Provider cleanup failed:", cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr));
+            }
+            try {
+                searchIndex.close();
+            }
+            catch (closeErr) {
+                console.error("Search index close failed:", closeErr instanceof Error ? closeErr.message : String(closeErr));
+            }
+        }
+        // ── Step 10k: Complete phase ──────────────────────────────────────
+        // Final disk scan to get the actual page count (includes all agent output).
+        // This runs AFTER orchestrator shutdown — it's just a filesystem call.
+        const finalDocFiles = await deps.scanDocFiles(absoluteDestination);
+        // ── Step 10l: Write changelog entry ────────────────────────────────
+        // Detect which doc files were created/updated via git status, then
+        // record a changelog entry with the current HEAD SHA.
+        try {
+            const currentSHA = deps.getCurrentSHA(absoluteSource);
+            const changedDocs = deps.detectChangedDocs(absoluteDestination);
+            await deps.writeChangelogEntry(absoluteDestination, currentSHA, changedDocs, prevSHA === null);
+            if (cliOptions.verbose) {
+                process.stderr.write(`[changelog] Recorded entry at ${currentSHA.slice(0, 8)} ` +
+                    `(${changedDocs.length} doc${changedDocs.length === 1 ? "" : "s"} changed)\n`);
+            }
+        }
+        catch (changelogError) {
+            // Changelog is best-effort — don't fail the pipeline
+            const msg = changelogError instanceof Error ? changelogError.message : String(changelogError);
+            if (cliOptions.verbose) {
+                process.stderr.write(`[changelog] Warning: Could not write changelog (${msg})\n`);
+            }
+        }
+        const totalPages = finalDocFiles.filter((f) => f !== "index.md" && f !== "changelog.md").length;
+        const completedAt = Date.now();
+        const failedResults = results.filter((r) => r.status === "failed");
+        const warnings = failedResults.map((r) => `Failed to generate: ${r.groupId}${r.error ? ` (${r.error})` : ""}`);
+        updateState({
+            phase: "complete",
+            completedAt,
+            totalPages,
+            completedSessions: results.length - failedResults.length,
+            failedSessions: failedResults.length,
+            warnings,
+        });
+        await waitUntilExit();
+        // ── Step 11: Set exit code ─────────────────────────────────────────
+        const exitCode = getExitCode(results);
+        if (exitCode !== 0) {
+            process.exitCode = exitCode;
+        }
+        // ── Worktree: commit, push, and clean up ───────────────────────────
+        if (worktreeState) {
+            try {
+                commitWorktree(worktreeState.path, "docs: generated by hem");
+                pushWorktree(worktreeState.path, worktreeState.branch);
+                process.stdout.write(`\n  Branch pushed: ${worktreeState.branch}\n` +
+                    `  Review and merge when ready.\n`);
+            }
+            catch (wtErr) {
+                const msg = wtErr instanceof Error ? wtErr.message : String(wtErr);
+                process.stderr.write(`Warning: worktree commit/push failed: ${msg}\n`);
+            }
+            finally {
+                cleanupWorktree(worktreeState.repoRoot, worktreeState.path);
+            }
+        }
+        return cliOptions;
+    }
+    catch (pipelineError) {
+        if (worktreeState) {
+            cleanupWorktree(worktreeState.repoRoot, worktreeState.path);
+        }
+        if (pipelineError instanceof AuthExpiredError && cliOptions.apiKey) {
+            const providerID = cliOptions.model
+                ? cliOptions.model.split("/")[0]
+                : pipelineError.providerName;
+            const message = INVALID_API_KEY_ERROR.replace("{providerID}", providerID);
+            process.stderr.write(message);
+            process.exitCode = 2;
+            await waitUntilExit();
+            return null;
+        }
+        if (pipelineError instanceof AuthExpiredError) {
+            process.stderr.write(pipelineError.message);
+            process.exitCode = 2;
+            await waitUntilExit();
+            return null;
+        }
+        const completedAt = Date.now();
+        const errorMessage = pipelineError instanceof Error
+            ? pipelineError.message
+            : String(pipelineError);
+        updateState({
+            phase: "error",
+            completedAt,
+            warnings: [errorMessage],
+        });
+        await waitUntilExit();
+        process.exitCode = 2;
+        return null;
+    }
+}
+/**
+ * Handle the `auth` subcommand.
+ */
+export async function handleAuth(action, target, deps = defaultDeps) {
+    const validActions = ["login", "list", "logout"];
+    if (action && !validActions.includes(action)) {
+        process.stderr.write(`Unknown auth action: "${action}". Valid actions: login, list, logout\n`);
+        process.exitCode = 2;
+        return null;
+    }
+    const cliOptions = {
+        source: "./src",
+        destination: "./docs",
+        files: "**/*",
+        concurrency: computeMaxConcurrency(),
+        model: undefined,
+        apiKey: undefined,
+        name: undefined,
+        verbose: false,
+        full: false,
+        worktree: false,
+        command: "auth",
+        authAction: action ?? undefined,
+        authTarget: target,
+    };
+    const { client, server } = await deps.startWithRetry(async () => {
+        const port = await deps.findFreePort();
+        return deps.createOpencode({ port });
+    });
+    trackServer(() => server.close());
+    try {
+        const resolvedAction = cliOptions.authAction ?? "login";
+        switch (resolvedAction) {
+            case "login":
+                await deps.handleAuthLogin(client);
+                break;
+            case "list":
+                await deps.handleAuthList(client);
+                break;
+            case "logout":
+                await deps.handleAuthLogout(client, cliOptions.authTarget);
+                break;
+        }
+    }
+    finally {
+        server.close();
+        untrackServer();
+    }
+    return cliOptions;
+}
+/**
+ * Two-step interactive provider + model selection used by handleConfig.
+ * Step 1: Select a provider from the list of connected providers.
+ * Step 2: If the provider has models, select one; otherwise use "default".
+ * @internal
+ */
+async function selectProviderAndModel(deps, client, providers) {
+    const providerOptions = providers.map((p) => ({
+        value: { providerID: p.id, modelID: "default" },
+        label: p.id === "opencode" ? "OpenCode" : p.name,
+        description: `(${p.authMethod})`,
+    }));
+    const providerSelection = await deps.renderAndWait((resolve) => React.createElement(ConfigPrompt, {
+        options: providerOptions,
+        onSelect: resolve,
+        title: "Select a provider:",
+    }));
+    const availableModels = await deps.listProviderModels(client, providerSelection.providerID);
+    if (availableModels.length === 0) {
+        return providerSelection;
+    }
+    const modelOptions = [
+        {
+            value: { providerID: providerSelection.providerID, modelID: "default" },
+            label: "Default",
+            description: "(let provider decide)",
+        },
+        ...availableModels.map((m) => ({
+            value: {
+                providerID: providerSelection.providerID,
+                // When a sub-provider is present (opencode meta-provider case), encode it
+                // in the modelID so OpenCodeProvider can route correctly. Without this,
+                // m.providerID ("github-copilot") would replace "opencode" as the top-level
+                // provider, causing CopilotProvider to be used instead of OpenCodeProvider.
+                modelID: m.providerID && m.providerID !== providerSelection.providerID
+                    ? `${m.providerID}/${m.id}`
+                    : m.id,
+            },
+            label: m.name,
+        })),
+    ];
+    return deps.renderAndWait((resolve) => React.createElement(ConfigPrompt, {
+        options: modelOptions,
+        onSelect: resolve,
+        title: "Select a model:",
+    }));
+}
+/** Print the confirmation message after saving config. @internal */
+function printConfigSaved(model) {
+    console.log(`\n  \u2713 Configuration saved to .hem/config.json\n`);
+    console.log(`    Provider: ${model.providerID}`);
+    console.log(`    Model:    ${model.modelID}\n`);
+}
+/**
+ * Handle the `config` subcommand.
+ *
+ * Interactively prompts the user to select a provider/model and saves
+ * the configuration to `{cwd}/.hem/config.json`.
+ */
+export async function handleConfig(deps = defaultDeps) {
+    const cliOptions = {
+        source: "./src",
+        destination: "./docs",
+        files: "**/*",
+        concurrency: computeMaxConcurrency(),
+        model: undefined,
+        apiKey: undefined,
+        name: undefined,
+        verbose: false,
+        full: false,
+        worktree: false,
+        command: "config",
+        authAction: undefined,
+        authTarget: undefined,
+    };
+    const { client, server } = await deps.startWithRetry(async () => {
+        const port = await deps.findFreePort();
+        return deps.createOpencode({ port });
+    });
+    trackServer(() => server.close());
+    try {
+        // Detect auth state to find connected providers.
+        const authState = await deps.detectAuthState(client);
+        // If no providers are connected, run auth first.
+        if (authState.connectedProviders.length === 0) {
+            const firstRunResult = await deps.handleFirstRun(client);
+            if (firstRunResult === null) {
+                // User chose to exit.
+                process.exitCode = 0;
+                return null;
+            }
+            // Re-detect auth state after first-run flow.
+            const updatedAuthState = await deps.detectAuthState(client);
+            if (updatedAuthState.connectedProviders.length === 0) {
+                process.stderr.write("No providers connected. Run `npx @pruddiman/hem auth login` to set up authentication.\n");
+                process.exitCode = 2;
+                return null;
+            }
+            // Present config prompt with updated providers.
+            const updatedModel = await selectProviderAndModel(deps, client, updatedAuthState.connectedProviders);
+            await deps.saveProjectConfig({ model: updatedModel });
+            printConfigSaved(updatedModel);
+            return cliOptions;
+        }
+        // Present config prompt with connected providers.
+        const model = await selectProviderAndModel(deps, client, authState.connectedProviders);
+        await deps.saveProjectConfig({ model });
+        printConfigSaved(model);
+        return cliOptions;
+    }
+    finally {
+        server.close();
+        untrackServer();
+    }
+}
+// ── Program builder ────────────────────────────────────────────────────
+/**
+ * Build and return a configured Commander program.
+ */
+export function buildProgram(deps = defaultDeps) {
+    const prog = new Command();
+    prog
+        .name("hem")
+        .description("AI-powered documentation generator. Scans your source code and produces a complete, cross-referenced documentation site.")
+        .version(version, "-V, --version")
+        .option("-s, --source <path>", "Source directory to scan for files", "./src")
+        .option("-d, --destination <path>", "Output directory for generated documentation", "./docs")
+        .option("-f, --files <glob>", "Glob pattern to match source files", "**/*")
+        .option("-c, --concurrency <n>", "Maximum parallel documentation sessions (auto-detected from system resources if omitted)", (v) => {
+        const n = parseInt(v, 10);
+        if (Number.isNaN(n) || n < 1) {
+            throw new Error("concurrency must be a positive integer");
+        }
+        const effective = computeMaxConcurrency(n);
+        if (effective < n) {
+            process.stderr.write(`Warning: requested concurrency ${n} exceeds resource limit. ` +
+                `Clamping to ${effective} (${describeResourceLimits(n)}).\n`);
+        }
+        return effective;
+    }, computeMaxConcurrency())
+        .option("-m, --model <id>", "Model to use (e.g., opencode/gpt-5-nano, anthropic/claude-sonnet-4). Overrides stored preferences.")
+        .option("-k, --api-key <key>", "API key for the provider specified in --model. Bypasses OAuth and interactive prompts.")
+        .option("-n, --name <name>", "Project name (used in page titles and headings). Auto-detected from package.json / Cargo.toml / etc. if omitted.")
+        .option("-v, --verbose", "Show detailed logs and LLM output on stderr", false)
+        .option("--full", "Force full re-generation of all docs (behavior may be unpredictable when docs already exist)", false)
+        .option("--worktree", "Run in an isolated git worktree on a new branch, then commit and push for review", false)
+        .action(async (opts) => {
+        await handleGenerate(opts, deps);
+    });
+    prog
+        .command("auth [action] [target]")
+        .description("Manage authentication. Actions: login, list, logout. Use 'logout <id>' to remove a specific provider.")
+        .action(async (action, target) => {
+        await handleAuth(action, target, deps);
+    });
+    prog
+        .command("config")
+        .description("Configure Hem for this project. Interactively select a provider/model and save to .hem/config.json.")
+        .action(async () => {
+        await handleConfig(deps);
+    });
+    return prog;
+}
+// ── Parse & run ────────────────────────────────────────────────────────
+const scriptPath = fileURLToPath(import.meta.url);
+const isDirectRun = process.argv[1] !== undefined &&
+    (() => {
+        try {
+            return realpathSync(process.argv[1]) === scriptPath;
+        }
+        catch {
+            // Fallback for broken symlinks or permission errors
+            return process.argv[1] === scriptPath;
+        }
+    })();
+if (isDirectRun) {
+    const prog = buildProgram();
+    prog
+        .parseAsync(process.argv)
+        .then(() => {
+        process.exit(process.exitCode ?? 0);
+    })
+        .catch((err) => {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    });
+}