@pruddiman/hem 0.0.1-beta-5671db0

package/dist/session.js

@@ -0,0 +1,370 @@
+/**
+ * OpenCode session utilities for Hem.
+ *
+ * Provides the `SessionClient` interface, the centralized `SessionTracker`
+ * for monitoring session completion, the shared `promptAndWait()` helper
+ * for sending prompts, and JSON extraction helpers used by agent classes.
+ *
+ * `promptAndWait()` uses the async prompt flow:
+ *   1. `session.promptAsync()` — fire the prompt without blocking
+ *   2. Register the session with the centralized `SessionTracker`
+ *   3. Wait for the tracker to resolve (session disappears from the
+ *      server's status map, meaning it has completed)
+ *   4. Read `session.messages()` to extract the response
+ *
+ * LLM-specific prompt building and session orchestration have been
+ * extracted into dedicated agent classes under `src/agents/`.
+ */
+import { isAuthExpired, AuthExpiredError } from "./auth.js";
+// ── Constants ───────────────────────────────────────────────────────────
+/** How often the tracker polls session status (ms). */
+export const POLL_INTERVAL_MS = 250;
+/** Hard ceiling timeout — if a session hasn't completed after this long,
+ *  give up and recover from tool history (ms). */
+export const MAX_PROMPT_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+/** Tighter timeout for exploration sessions — they typically finish in 2-3 min.
+ *  Surfaces hangs 25 minutes earlier than the default ceiling. */
+export const EXPLORATION_TIMEOUT_MS = 5 * 60 * 1_000; // 5 minutes
+/** Timeout for documentation generation sessions — more complex than
+ *  exploration but still bounded; surfaces hangs 20 minutes earlier. */
+export const DOCUMENTATION_TIMEOUT_MS = 10 * 60 * 1_000; // 10 minutes
+/**
+ * Format elapsed time as a compact human-readable string.
+ * @internal
+ */
+function formatElapsedCompact(ms) {
+    const totalSeconds = Math.round(ms / 1000);
+    if (totalSeconds < 60)
+        return `${totalSeconds}s`;
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    return `${minutes}m ${seconds}s`;
+}
+/**
+ * Creates a centralized session tracker with subagent awareness.
+ *
+ * The tracker subscribes to SSE `session.created` events to detect child
+ * sessions spawned by tracked parents. A parent is only resolved as "done"
+ * when both the parent and all its descendants have completed.
+ *
+ * If the SSE subscription fails, the tracker gracefully degrades to the
+ * original poll-only behavior (no child tracking).
+ *
+ * @param client  - The OpenCode SDK client (for `session.status()` and `event.subscribe()`).
+ * @param options - Configuration: verbose logger, poll interval, per-session timeout.
+ * @returns A `SessionTracker` instance.
+ */
+export function createSessionTracker(client, options) {
+    const verbose = options?.verbose;
+    const interval = options?.pollIntervalMs ?? POLL_INTERVAL_MS;
+    const ceiling = options?.maxTimeoutMs ?? MAX_PROMPT_TIMEOUT_MS;
+    const tracked = new Map();
+    /**
+     * Maps a child session ID to the root tracked parent session ID.
+     * This covers both direct children and nested descendants.
+     */
+    const childToRoot = new Map();
+    let intervalHandle = null;
+    let sseStopped = false;
+    /** Resolves when the SSE loop exits (for clean shutdown). */
+    let sseLoopDone = null;
+    // ── SSE subscription for session.created events ──────────────────
+    function startSseSubscription() {
+        // Fire-and-forget — errors are non-fatal
+        void (async () => {
+            try {
+                const { stream } = await client.event.subscribe();
+                for await (const event of stream) {
+                    if (sseStopped)
+                        break;
+                    if (event.type === "session.created") {
+                        const props = event.properties;
+                        const childId = props.session?.id;
+                        const parentId = props.session?.parentID;
+                        if (!childId || !parentId)
+                            continue;
+                        // Case 1: Parent is a directly tracked session
+                        if (tracked.has(parentId)) {
+                            childToRoot.set(childId, parentId);
+                            tracked.get(parentId).children.add(childId);
+                            if (verbose) {
+                                const parentLabel = tracked.get(parentId).label;
+                                verbose(`[tracker] · Subagent ${childId.slice(0, 8)}… spawned by "${parentLabel}"`);
+                            }
+                            continue;
+                        }
+                        // Case 2: Parent is a known child — trace to root
+                        if (childToRoot.has(parentId)) {
+                            const rootId = childToRoot.get(parentId);
+                            const rootEntry = tracked.get(rootId);
+                            if (rootEntry) {
+                                childToRoot.set(childId, rootId);
+                                rootEntry.children.add(childId);
+                                if (verbose) {
+                                    verbose(`[tracker] · Nested subagent ${childId.slice(0, 8)}… (root: "${rootEntry.label}")`);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                // SSE subscription failure is non-fatal — degrade to poll-only
+                if (!sseStopped && verbose) {
+                    verbose(`[tracker] ⚠ SSE subscription error (degrading to poll-only): ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            finally {
+                sseLoopDone?.();
+            }
+        })();
+    }
+    // Start SSE immediately so we catch child sessions from the very first prompt
+    startSseSubscription();
+    function startLoop() {
+        if (intervalHandle !== null)
+            return;
+        intervalHandle = setInterval(pollOnce, interval);
+    }
+    function stopLoop() {
+        if (intervalHandle !== null) {
+            clearInterval(intervalHandle);
+            intervalHandle = null;
+        }
+    }
+    /**
+     * Check whether all descendants of a tracked parent have completed
+     * (i.e., are absent from the status map).
+     */
+    function allChildrenDone(entry, statusMap) {
+        for (const childId of entry.children) {
+            if (statusMap[childId] !== undefined) {
+                return false;
+            }
+        }
+        return true;
+    }
+    async function pollOnce() {
+        if (tracked.size === 0) {
+            stopLoop();
+            return;
+        }
+        let statusMap = {};
+        try {
+            const result = await client.session.status();
+            if (result.error) {
+                if (isAuthExpired(result.error)) {
+                    // Auth expired — reject ALL tracked sessions
+                    const err = new AuthExpiredError("the configured provider", result.error);
+                    for (const [id, entry] of tracked) {
+                        entry.reject(err);
+                        tracked.delete(id);
+                    }
+                    stopLoop();
+                    return;
+                }
+                // Transient error — skip this poll cycle
+                if (verbose)
+                    verbose(`[tracker] Status poll error: ${String(result.error)}`);
+                return;
+            }
+            statusMap = result.data ?? {};
+        }
+        catch (err) {
+            if (isAuthExpired(err)) {
+                const authErr = new AuthExpiredError("the configured provider", err);
+                for (const [id, entry] of tracked) {
+                    entry.reject(authErr);
+                    tracked.delete(id);
+                }
+                stopLoop();
+                return;
+            }
+            // Transient error — skip this poll cycle
+            if (verbose)
+                verbose(`[tracker] Status poll error: ${String(err)}`);
+            return;
+        }
+        const now = Date.now();
+        for (const [sessionId, entry] of tracked) {
+            // Check timeout first
+            if (now >= entry.deadline) {
+                const elapsed = formatElapsedCompact(now - entry.startedAt);
+                if (verbose) {
+                    const childCount = entry.children.size;
+                    const childSuffix = childCount > 0 ? `, ${childCount} subagent(s)` : "";
+                    verbose(`[tracker] \u2717 "${entry.label}" timed out (${tracked.size - 1} active, ${elapsed}${childSuffix})`);
+                }
+                // Clean up child mappings
+                for (const childId of entry.children) {
+                    childToRoot.delete(childId);
+                }
+                entry.resolve("timeout");
+                tracked.delete(sessionId);
+                continue;
+            }
+            // Parent is done when it's absent from status map AND all children are too
+            const parentDone = statusMap[sessionId] === undefined;
+            if (parentDone && allChildrenDone(entry, statusMap)) {
+                const elapsed = formatElapsedCompact(now - entry.startedAt);
+                if (verbose) {
+                    const childCount = entry.children.size;
+                    const childSuffix = childCount > 0 ? ` (${childCount} subagent(s) completed)` : "";
+                    verbose(`[tracker] \u2713 "${entry.label}" done (${tracked.size - 1} active, ${elapsed})${childSuffix}`);
+                }
+                // Clean up child mappings
+                for (const childId of entry.children) {
+                    childToRoot.delete(childId);
+                }
+                entry.resolve("done");
+                tracked.delete(sessionId);
+            }
+            // If parent or any child is still busy — do nothing
+        }
+        // Pause poll loop if no sessions remain
+        if (tracked.size === 0) {
+            stopLoop();
+        }
+    }
+    return {
+        track(sessionId, label) {
+            const displayLabel = label ?? sessionId.slice(0, 20) + "...";
+            return new Promise((resolve, reject) => {
+                tracked.set(sessionId, {
+                    label: displayLabel,
+                    startedAt: Date.now(),
+                    deadline: Date.now() + ceiling,
+                    resolve,
+                    reject,
+                    children: new Set(),
+                });
+                if (verbose) {
+                    verbose(`[tracker] \u00B7 Tracking "${displayLabel}" (${tracked.size} active)`);
+                }
+                startLoop();
+            });
+        },
+        stop() {
+            sseStopped = true;
+            stopLoop();
+            // Resolve any remaining tracked sessions as timeout
+            for (const [id, entry] of tracked) {
+                // Clean up child mappings
+                for (const childId of entry.children) {
+                    childToRoot.delete(childId);
+                }
+                entry.resolve("timeout");
+                tracked.delete(id);
+            }
+        },
+    };
+}
+// ── Prompt helper ────────────────────────────────────────────────────────
+/**
+ * Sends a prompt to an OpenCode session and returns the complete response.
+ *
+ * Uses the async prompt flow:
+ *   1. `session.promptAsync()` fires the prompt without blocking.
+ *   2. Registers the session with the centralized `SessionTracker` and
+ *      waits for it to complete (disappear from the status map).
+ *   3. Reads `session.messages()` to extract the assistant's response.
+ *   4. If the hard ceiling is hit, recovers file paths from tool history.
+ *
+ * @param client    - The OpenCode SDK client.
+ * @param sessionId - The session to prompt.
+ * @param parts     - The message parts to send.
+ * @param options   - Settings: tracker (required), verbose callback, agent selection.
+ * @returns The response parts from the assistant message.
+ * @throws {AuthExpiredError} If auth expires during the API call.
+ * @throws {Error} If the prompt fails to be accepted.
+ */
+export async function promptAndWait(client, sessionId, parts, options) {
+    const verbose = options.verbose;
+    // ── Step 1: Fire the prompt asynchronously ─────────────────────────
+    if (verbose)
+        verbose(`[opencode] Sending prompt to session ${sessionId}...`);
+    try {
+        const asyncResult = await client.session.promptAsync({
+            path: { id: sessionId },
+            body: { parts, agent: options.agent },
+        });
+        if (asyncResult.error) {
+            if (isAuthExpired(asyncResult.error)) {
+                throw new AuthExpiredError("the configured provider", asyncResult.error);
+            }
+            throw new Error(`Prompt rejected: ${String(asyncResult.error)}`);
+        }
+    }
+    catch (err) {
+        if (err instanceof AuthExpiredError)
+            throw err;
+        if (isAuthExpired(err)) {
+            throw new AuthExpiredError("the configured provider", err);
+        }
+        throw err;
+    }
+    // ── Step 2: Wait for session to complete via centralized tracker ────
+    const trackResult = await options.tracker.track(sessionId, options.label);
+    // ── Step 3: Read messages ──────────────────────────────────────────
+    const messages = await readSessionMessages(client, sessionId);
+    const lastAssistant = findLastAssistantMessage(messages);
+    if (!lastAssistant) {
+        if (verbose)
+            verbose(`[opencode] No assistant message found in session ${sessionId}`);
+        return [];
+    }
+    const responseParts = lastAssistant.parts;
+    if (trackResult === "timeout") {
+        if (verbose) {
+            verbose(`[opencode] Session ${sessionId} timed out`);
+        }
+        // No files recovered — return whatever response parts exist (may be empty)
+    }
+    if (verbose) {
+        const textLen = responseParts
+            .filter((p) => p.type === "text")
+            .reduce((sum, p) => sum + (p.text?.length ?? 0), 0);
+        verbose(`[opencode] Response received (${textLen} chars)`);
+    }
+    return responseParts;
+}
+// ── Message reading helpers ─────────────────────────────────────────────
+/**
+ * Reads all messages from a session.
+ *
+ * @throws {AuthExpiredError} If auth expires during the API call.
+ */
+async function readSessionMessages(client, sessionId) {
+    let result;
+    try {
+        result = await client.session.messages({ path: { id: sessionId } });
+    }
+    catch (err) {
+        if (isAuthExpired(err)) {
+            throw new AuthExpiredError("the configured provider", err);
+        }
+        throw err;
+    }
+    if (result.error) {
+        if (isAuthExpired(result.error)) {
+            throw new AuthExpiredError("the configured provider", result.error);
+        }
+        throw new Error(`Failed to read messages: ${String(result.error)}`);
+    }
+    return result.data ?? [];
+}
+/**
+ * Finds the last assistant message in a message list.
+ */
+function findLastAssistantMessage(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].info.role === "assistant") {
+            return messages[i];
+        }
+    }
+    return undefined;
+}
+// ── Sleep helper ────────────────────────────────────────────────────────
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/types.d.ts

@@ -0,0 +1,272 @@
+/**
+ * Shared type definitions for Hem.
+ * All interfaces mirror the data model in specs/001-hem-cli/data-model.md.
+ */
+/** Represents the current authentication state detected at startup. */
+export interface AuthState {
+    /** Whether any LLM provider credentials exist. */
+    hasCredentials: boolean;
+    /** List of providers with active credentials. */
+    connectedProviders: ConnectedProvider[];
+    /** Currently resolved model (from --model flag, preferences, or default). */
+    activeModel: ModelSelection | undefined;
+    /** True if no preferences file exists and no credentials detected. */
+    isFirstRun: boolean;
+}
+/** A provider with active credentials. */
+export interface ConnectedProvider {
+    /** Provider identifier (e.g., `anthropic`, `opencode`, `github-copilot`). */
+    id: string;
+    /** Display name (e.g., "Anthropic", "Opencode"). */
+    name: string;
+    /** How the provider was authenticated. */
+    authMethod: "oauth" | "api-key" | "env-var";
+}
+/** The resolved model to use for documentation generation. */
+export interface ModelSelection {
+    /** Provider identifier (e.g., `opencode`, `anthropic`). */
+    providerID: string;
+    /** Model identifier (e.g., `gpt-5-nano`, `claude-sonnet-4`). */
+    modelID: string;
+}
+/** Persisted user preferences stored in `~/.config/hem/preferences.json`. */
+export interface UserPreferences {
+    /** Preferred model selection. */
+    model: ModelSelection | undefined;
+    /** Whether user acknowledged data security warnings for free models. */
+    agreedToFreeModelTerms: boolean;
+    /** ISO 8601 timestamp of last successful run. */
+    lastUsedAt: string | undefined;
+}
+/** Project-local configuration stored in `{cwd}/.hem/config.json`. */
+export interface ProjectConfig {
+    /** Selected provider and model for this project. */
+    model: ModelSelection;
+}
+/** A free model fetched from the Opencode catalog. */
+export interface FreeModelInfo {
+    /** Model identifier in Zen (e.g., `gpt-5-nano`). */
+    id: string;
+    /** Display name (e.g., "GPT-5 Nano"). */
+    name: string;
+    /** Always `"opencode"` for Zen models. */
+    providerID: string;
+    /** Data security classification. */
+    dataRetention: "zero-retention" | "may-train" | "unknown";
+    /** Human-readable data security note. */
+    retentionNote: string;
+}
+/** Represents a single discovered source file. */
+export interface FileInfo {
+    /** Relative path from source root (e.g., `user/controller.ts`). */
+    path: string;
+    /** Absolute filesystem path. */
+    absolutePath: string;
+    /** File extension including dot (e.g., `.ts`). */
+    extension: string;
+    /** File size in bytes. */
+    size: number;
+    /** Whether the file was detected as binary. */
+    isBinary: boolean;
+}
+/** A collection of related source files to be documented together. */
+export interface FileGroup {
+    /** Unique group identifier (e.g., `user-feature`, `controllers-layer`). */
+    id: string;
+    /** Human-readable group name (e.g., "User Feature", "Controllers"). */
+    label: string;
+    /** Whether grouped by feature slice or architectural layer. */
+    type: "vertical" | "horizontal";
+    /** The files in this group (2-5 files typically). */
+    files: FileInfo[];
+    /** Common parent directory of the grouped files. */
+    directory: string;
+}
+/**
+ * Result of a single doc-agent run for one file group.
+ * The agent writes files directly to disk; the pipeline discovers
+ * what was produced by scanning the destination directory.
+ */
+export interface GenerationResult {
+    /** The `FileGroup.id` this result corresponds to. */
+    groupId: string;
+    /** Current status. */
+    status: "generated" | "failed";
+    /** Error message if generation failed. */
+    error: string | undefined;
+}
+/** Tracks the state of a single OpenCode documentation session. */
+export interface GenerationSession {
+    /** OpenCode session ID. */
+    sessionId: string;
+    /** The `FileGroup.id` being documented. */
+    groupId: string;
+    /** Session status. */
+    status: "pending" | "active" | "completed" | "failed" | "retrying";
+    /** Unix timestamp when session started. */
+    startedAt: number | undefined;
+    /** Unix timestamp when session completed. */
+    completedAt: number | undefined;
+    /** Number of retry attempts (max 1). */
+    retryCount: number;
+    /** Error message if failed. */
+    error: string | undefined;
+}
+/** Shared context passed to each doc-agent session. */
+export interface GenerationContext {
+    /** Name of the project being documented. */
+    projectName: string;
+    /** Absolute path to the source root directory. */
+    sourceRoot: string;
+    /** Absolute path to the documentation destination directory. */
+    destinationPath: string;
+    /** Summary of all groups (for cross-reference awareness). */
+    allGroups: {
+        id: string;
+        label: string;
+        files: string[];
+    }[];
+    /** All exploration findings from the exploration phase. */
+    explorationFindings: ExplorationFindings[];
+    /** This specific group's exploration findings. */
+    groupFindings?: ExplorationFindings;
+    /** Existing documentation files found in destination (for merge-in-place). */
+    existingDocs: Array<{
+        path: string;
+        content: string;
+    }>;
+    /**
+     * Paths of existing docs that were not selected as highly relevant but
+     * still exist in the destination directory. Provided for awareness only
+     * (agents know these paths exist but do NOT receive their content).
+     */
+    mentionedDocPaths?: string[];
+}
+/** Terminal progress display state, used as React state in the Ink dashboard component. */
+export interface ProgressState {
+    /** Current pipeline phase. */
+    phase: "discovery" | "grouping" | "exploration" | "generation" | "organization" | "crossref" | "architecture" | "indexing" | "complete" | "error";
+    /** Display label for the active model (e.g., `anthropic/claude-sonnet-4`). */
+    modelLabel: string;
+    /** Human-readable provider display name (e.g., "Anthropic", "Opencode"). */
+    providerLabel: string;
+    /** Total files discovered. */
+    totalFiles: number;
+    /** Number of binary files skipped. */
+    binaryFilesSkipped: number;
+    /** Total file groups. */
+    totalGroups: number;
+    /** Number of feature (vertical) groups. */
+    featureGroups: number;
+    /** Number of layer (horizontal) groups. */
+    layerGroups: number;
+    /** Total file groups to generate docs for. */
+    totalPages: number;
+    /** Per-group status for the generation dashboard. */
+    groupStatuses: GroupStatus[];
+    /** Files generated in the indexing phase. */
+    indexFiles: string[];
+    /** Finished sessions. */
+    completedSessions: number;
+    /** Failed sessions. */
+    failedSessions: number;
+    /** Pipeline start timestamp. */
+    startedAt: number;
+    /** Pipeline completion timestamp. */
+    completedAt: number | undefined;
+    /** Warnings to display in the summary. */
+    warnings: string[];
+    /** Per-group status for the exploration dashboard. */
+    explorationStatuses: GroupStatus[];
+    /** Whether all exploration work has finished (all groups settled). */
+    explorationComplete: boolean;
+}
+/** Per-group status for the Ink generation dashboard. */
+export interface GroupStatus {
+    /** References `FileGroup.id`. */
+    groupId: string;
+    /** Human-readable group label (e.g., "User Feature"). */
+    label: string;
+    /** Current status. */
+    status: "queued" | "generating" | "completed" | "failed";
+    /** Failure reason (populated when `status` is `"failed"`). */
+    error?: string;
+    /**
+     * Sub-agent progress for multi-agent exploration/generation.
+     * Present when the project exceeds the large-project threshold and
+     * multiple agents are used per group. `total` is the number of
+     * sub-agents assigned to this group; `completed` tracks how many
+     * have finished successfully.
+     */
+    subAgentProgress?: {
+        completed: number;
+        total: number;
+    };
+}
+/** Parsed command-line arguments. */
+export interface CLIOptions {
+    /** Source directory path. Default: `"./src"`. */
+    source: string;
+    /** Destination directory path. Default: `"./docs"`. */
+    destination: string;
+    /** Glob pattern for file matching. Default: `"**\/*"`. */
+    files: string;
+    /** Max parallel sessions. Default: auto-detected from system resources via `computeMaxConcurrency()`. */
+    concurrency: number;
+    /** Model override (e.g., `"opencode/gpt-5-nano"`). */
+    model: string | undefined;
+    /** API key for the provider in `model`. Requires `model` to be set. */
+    apiKey: string | undefined;
+    /**
+     * Explicit project name override (`--name` flag).
+     * When set, skips auto-detection from manifest files.
+     */
+    name: string | undefined;
+    /** Which subcommand was invoked. Default: `"generate"`. */
+    command: "generate" | "auth" | "config";
+    /** Auth subcommand action. */
+    authAction: "login" | "list" | "logout" | undefined;
+    /** Provider ID for `auth logout <id>`. */
+    authTarget: string | undefined;
+    /** Enable verbose logging to stderr. */
+    verbose: boolean;
+    /**
+     * Force full re-generation even when a changelog exists.
+     * Bypasses diff-scoping and re-documents all source files.
+     * Behavior may be unpredictable when docs already exist.
+     */
+    full: boolean;
+    /**
+     * Run the pipeline in an isolated git worktree on a new branch, then commit
+     * and push the branch for review. The worktree is created at `.hem/worktree/`
+     * and removed after the run.
+     */
+    worktree: boolean;
+}
+/**
+ * Output of the ExplorationAgent for a single file group.
+ *
+ * The exploration agent writes a natural-language report covering:
+ * summary, questions to answer, integrations discovered, complexity
+ * signals, style guides found, and cross-group dependencies.
+ * Downstream agents (doc, arch) consume `text` directly in their prompts.
+ */
+export interface ExplorationFindings {
+    /** The `FileGroup.id` this exploration covers. */
+    groupId: string;
+    /** Natural-language exploration report produced by the explore agent. */
+    text: string;
+}
+/**
+ * Permission configuration for a single agent class.
+ */
+export interface AgentPermissionConfig {
+    /** OpenCode agent name (e.g., `"hem-explore"`). */
+    agentName: string;
+    /** Edit permission. */
+    edit: "allow" | "deny";
+    /** Bash permission — glob-pattern allowlist or simple allow/deny. */
+    bash: Record<string, "allow" | "deny"> | "allow" | "deny";
+    /** Webfetch permission. */
+    webfetch: "allow" | "deny";
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared type definitions for Hem.
+ * All interfaces mirror the data model in specs/001-hem-cli/data-model.md.
+ */
+export {};