@pruddiman/hem 0.0.1-beta-5671db0

package/dist/output.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Destination directory management and structural document generation
+ * for Hem.
+ *
+ * Provides utilities for:
+ *   - Creating and resolving output paths within the destination directory
+ *   - Scanning actual files on disk for TOC generation (no LLM)
+ *   - Writing the table of contents (`index.md`)
+ *   - Writing the architecture overview (`architecture.md`)
+ *
+ * Architecture (v2):
+ *   - TOC is generated programmatically by scanning files on disk.
+ *   - No more `DocumentationPlan`, `HierarchyNode`, or `PlannedTopic`.
+ *   - Agents write files directly; this module only handles structural
+ *     navigation documents and path utilities.
+ *
+ * All writes are strictly confined to the destination directory to
+ * ensure source files are never modified (US2 safety guarantee).
+ *
+ * Reference: spec.md US2 & US6, FR-007, FR-010.
+ */
+/**
+ * Ensures the destination directory exists, creating it if necessary.
+ * Subdirectories are created dynamically by the doc agents.
+ *
+ * @param destinationPath - Path to the destination directory.
+ */
+export declare function ensureDestinationDir(destinationPath: string): Promise<void>;
+/**
+ * Scans the destination directory for all `.md` files.
+ *
+ * Used by the TOC generator and post-processing agents to discover
+ * what documentation files actually exist on disk.
+ *
+ * @param destinationPath - Absolute path to the destination directory.
+ * @returns Array of relative paths (e.g., `["features/auth.md", "layers/services.md"]`).
+ */
+export declare function scanDocFiles(destinationPath: string): Promise<string[]>;
+/**
+ * Generates the Markdown content for the table of contents (`index.md`).
+ *
+ * Scans the provided file list and produces a navigable index grouped by
+ * subdirectory. Directory names are auto-converted to section headers
+ * (e.g., `auth/` → "## Auth"). Top-level files (excluding `index.md` and
+ * `architecture.md`) are listed under "## Overview" if present.
+ *
+ * @param projectName     - The project name for the title.
+ * @param docFiles        - Relative paths of all documentation files.
+ * @returns The full Markdown content for `index.md`.
+ */
+export declare function generateTableOfContents(projectName: string, docFiles: string[]): string;
+/**
+ * Generates only the navigable link-list portion of the table of contents.
+ *
+ * This is the body that gets inserted into an AI-generated index.md via
+ * the `<!-- TOC -->` placeholder, or appended to the procedural fallback
+ * header by `generateTableOfContents()`.
+ *
+ * Produces:
+ *   - Quick Navigation (link to architecture.md, if present)
+ *   - Subdirectory sections (alphabetical)
+ *   - Overview section (top-level non-special files)
+ *
+ * @param projectName - The project name (unused currently, reserved for future heading customization).
+ * @param docFiles    - Relative paths of all documentation files.
+ * @returns Markdown string containing only the sectioned link list.
+ */
+export declare function generateTocLinkList(_projectName: string, docFiles: string[]): string;
+/**
+ * Replaces the `<!-- TOC -->` placeholder in AI-generated index content
+ * with the procedurally generated table of contents link list.
+ *
+ * If the placeholder is not found, the link list is appended at the end
+ * as a safety fallback.
+ *
+ * @param agentContent - The AI-generated index.md content containing `<!-- TOC -->`.
+ * @param tocLinkList  - The procedural link list from `generateTocLinkList()`.
+ * @returns The final index.md content with the placeholder replaced.
+ */
+export declare function replaceTocPlaceholder(agentContent: string, tocLinkList: string): string;
+/**
+ * Writes the table of contents to `{destinationPath}/index.md`.
+ *
+ * @param destinationPath - Path to the destination directory.
+ * @param content - The Markdown content to write.
+ */
+export declare function writeTableOfContents(destinationPath: string, content: string): Promise<void>;
+/**
+ * Writes the architecture overview to `{destinationPath}/architecture.md`.
+ *
+ * @param destinationPath - Path to the destination directory.
+ * @param content - The Markdown content to write.
+ */
+export declare function writeArchitectureOverview(destinationPath: string, content: string): Promise<void>;
+/**
+ * Recursively removes empty subdirectories within `destinationPath`.
+ *
+ * Walks bottom-up so that nested empty directories are pruned first,
+ * allowing their parent to become empty and be pruned in turn.
+ * The root `destinationPath` itself is never removed.
+ *
+ * Silently ignores errors (permission issues, race conditions, etc.).
+ *
+ * @param destinationPath - Absolute path to the destination directory.
+ */
+export declare function removeEmptyDirs(destinationPath: string): Promise<void>;

package/dist/output.js

@@ -0,0 +1,243 @@
+/**
+ * Destination directory management and structural document generation
+ * for Hem.
+ *
+ * Provides utilities for:
+ *   - Creating and resolving output paths within the destination directory
+ *   - Scanning actual files on disk for TOC generation (no LLM)
+ *   - Writing the table of contents (`index.md`)
+ *   - Writing the architecture overview (`architecture.md`)
+ *
+ * Architecture (v2):
+ *   - TOC is generated programmatically by scanning files on disk.
+ *   - No more `DocumentationPlan`, `HierarchyNode`, or `PlannedTopic`.
+ *   - Agents write files directly; this module only handles structural
+ *     navigation documents and path utilities.
+ *
+ * All writes are strictly confined to the destination directory to
+ * ensure source files are never modified (US2 safety guarantee).
+ *
+ * Reference: spec.md US2 & US6, FR-007, FR-010.
+ */
+import { resolve, join } from "node:path";
+import { mkdir, writeFile, readdir, rmdir } from "node:fs/promises";
+import fg from "fast-glob";
+import { dirToHeading, fileToTitle } from "./helpers/strings.js";
+// ── Path Utilities ──────────────────────────────────────────────────────
+/**
+ * Ensures the destination directory exists, creating it if necessary.
+ * Subdirectories are created dynamically by the doc agents.
+ *
+ * @param destinationPath - Path to the destination directory.
+ */
+export async function ensureDestinationDir(destinationPath) {
+    const absoluteDestination = resolve(destinationPath);
+    await mkdir(absoluteDestination, { recursive: true });
+}
+// ── Disk Scanning ──────────────────────────────────────────────────────
+/**
+ * Scans the destination directory for all `.md` files.
+ *
+ * Used by the TOC generator and post-processing agents to discover
+ * what documentation files actually exist on disk.
+ *
+ * @param destinationPath - Absolute path to the destination directory.
+ * @returns Array of relative paths (e.g., `["features/auth.md", "layers/services.md"]`).
+ */
+export async function scanDocFiles(destinationPath) {
+    const absoluteDestination = resolve(destinationPath);
+    try {
+        const files = await fg("**/*.md", {
+            cwd: absoluteDestination,
+            absolute: false,
+            onlyFiles: true,
+            dot: false,
+        });
+        // Sort for deterministic output
+        return files.sort();
+    }
+    catch {
+        return [];
+    }
+}
+// ── Table of Contents ─────────────────────────────────────────────────
+/**
+ * Generates the Markdown content for the table of contents (`index.md`).
+ *
+ * Scans the provided file list and produces a navigable index grouped by
+ * subdirectory. Directory names are auto-converted to section headers
+ * (e.g., `auth/` → "## Auth"). Top-level files (excluding `index.md` and
+ * `architecture.md`) are listed under "## Overview" if present.
+ *
+ * @param projectName     - The project name for the title.
+ * @param docFiles        - Relative paths of all documentation files.
+ * @returns The full Markdown content for `index.md`.
+ */
+export function generateTableOfContents(projectName, docFiles) {
+    const lines = [];
+    // H1 title
+    lines.push(`# ${projectName} Documentation`);
+    lines.push("");
+    // Intro paragraph
+    const pageCount = docFiles.filter((f) => f !== "index.md").length;
+    lines.push(`This documentation covers ${pageCount} pages.`);
+    lines.push("");
+    // Append the navigable link list
+    lines.push(generateTocLinkList(projectName, docFiles));
+    return lines.join("\n");
+}
+/**
+ * Generates only the navigable link-list portion of the table of contents.
+ *
+ * This is the body that gets inserted into an AI-generated index.md via
+ * the `<!-- TOC -->` placeholder, or appended to the procedural fallback
+ * header by `generateTableOfContents()`.
+ *
+ * Produces:
+ *   - Quick Navigation (link to architecture.md, if present)
+ *   - Subdirectory sections (alphabetical)
+ *   - Overview section (top-level non-special files)
+ *
+ * @param projectName - The project name (unused currently, reserved for future heading customization).
+ * @param docFiles    - Relative paths of all documentation files.
+ * @returns Markdown string containing only the sectioned link list.
+ */
+export function generateTocLinkList(_projectName, docFiles) {
+    const lines = [];
+    // Navigation links
+    const hasArch = docFiles.includes("architecture.md");
+    if (hasArch) {
+        lines.push("## Quick navigation");
+        lines.push("");
+        lines.push("- [Architecture Overview](./architecture.md) — High-level system design and component interactions");
+        lines.push("");
+    }
+    // Bucket files by top-level directory (or "" for root-level files)
+    const buckets = new Map();
+    const reserved = new Set(["index.md", "architecture.md"]);
+    for (const file of docFiles) {
+        if (reserved.has(file))
+            continue;
+        const slashIdx = file.indexOf("/");
+        const bucket = slashIdx === -1 ? "" : file.slice(0, slashIdx);
+        if (!buckets.has(bucket)) {
+            buckets.set(bucket, []);
+        }
+        buckets.get(bucket).push(file);
+    }
+    // Sort each bucket's files
+    for (const files of buckets.values()) {
+        files.sort();
+    }
+    // Render subdirectories alphabetically, then top-level files last.
+    const topLevel = buckets.get("") ?? [];
+    const otherDirs = [...buckets.keys()]
+        .filter((k) => k !== "")
+        .sort();
+    // Subdirectory sections (alphabetical)
+    for (const dir of otherDirs) {
+        const files = buckets.get(dir);
+        lines.push(`## ${dirToHeading(dir)}`);
+        lines.push("");
+        for (const file of files) {
+            const name = fileToTitle(file);
+            lines.push(`- [${name}](./${file})`);
+        }
+        lines.push("");
+    }
+    // Top-level files
+    if (topLevel.length > 0) {
+        lines.push("## Overview");
+        lines.push("");
+        for (const file of topLevel) {
+            const name = fileToTitle(file);
+            lines.push(`- [${name}](./${file})`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Replaces the `<!-- TOC -->` placeholder in AI-generated index content
+ * with the procedurally generated table of contents link list.
+ *
+ * If the placeholder is not found, the link list is appended at the end
+ * as a safety fallback.
+ *
+ * @param agentContent - The AI-generated index.md content containing `<!-- TOC -->`.
+ * @param tocLinkList  - The procedural link list from `generateTocLinkList()`.
+ * @returns The final index.md content with the placeholder replaced.
+ */
+export function replaceTocPlaceholder(agentContent, tocLinkList) {
+    const placeholder = "<!-- TOC -->";
+    if (agentContent.includes(placeholder)) {
+        return agentContent.replace(placeholder, tocLinkList);
+    }
+    // Fallback: append TOC at the end
+    return agentContent.trimEnd() + "\n\n" + tocLinkList;
+}
+/**
+ * Writes the table of contents to `{destinationPath}/index.md`.
+ *
+ * @param destinationPath - Path to the destination directory.
+ * @param content - The Markdown content to write.
+ */
+export async function writeTableOfContents(destinationPath, content) {
+    const absoluteDestination = resolve(destinationPath);
+    const outputPath = join(absoluteDestination, "index.md");
+    await mkdir(absoluteDestination, { recursive: true });
+    await writeFile(outputPath, content, "utf-8");
+}
+// ── Architecture Overview ─────────────────────────────────────────────
+/**
+ * Writes the architecture overview to `{destinationPath}/architecture.md`.
+ *
+ * @param destinationPath - Path to the destination directory.
+ * @param content - The Markdown content to write.
+ */
+export async function writeArchitectureOverview(destinationPath, content) {
+    const absoluteDestination = resolve(destinationPath);
+    const outputPath = join(absoluteDestination, "architecture.md");
+    await writeFile(outputPath, content, "utf-8");
+}
+// ── Cleanup ───────────────────────────────────────────────────────────
+/**
+ * Recursively removes empty subdirectories within `destinationPath`.
+ *
+ * Walks bottom-up so that nested empty directories are pruned first,
+ * allowing their parent to become empty and be pruned in turn.
+ * The root `destinationPath` itself is never removed.
+ *
+ * Silently ignores errors (permission issues, race conditions, etc.).
+ *
+ * @param destinationPath - Absolute path to the destination directory.
+ */
+export async function removeEmptyDirs(destinationPath) {
+    const root = resolve(destinationPath);
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        // Recurse into subdirectories first (bottom-up)
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                await walk(join(dir, entry.name));
+            }
+        }
+        // After recursing, try to remove this dir if it's now empty
+        // (but never the root destination itself)
+        if (dir !== root) {
+            try {
+                await rmdir(dir); // throws ENOTEMPTY if not empty
+            }
+            catch {
+                // Not empty or other error — ignore
+            }
+        }
+    }
+    await walk(root);
+}

package/dist/progress.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Ink React components for terminal UI — auth prompts, dashboard, phase display.
+ *
+ * Components:
+ *   - AuthPrompt           — First-run 4-option select menu
+ *   - ApiKeyInput          — Provider select + API key text entry
+ *   - FreeModelPicker      — Free model list with data security annotations
+ *   - ConfigPrompt         — Project config provider/model selection
+ *   - App                  — Root dashboard component holding ProgressState
+ *   - Header               — Version + model display
+ *   - PhaseRow             — Single pipeline phase with status indicator
+ *   - GenerationDashboard  — Multi-line group status during generation phase
+ *   - GroupRow             — Single file group with spinner/status/label
+ *   - Summary              — Final success/failure report with timing
+ *
+ * Reference: plan.md lines 310-351 (Terminal UI Architecture),
+ *            contracts/cli-interface.md lines 93-127, 148-189.
+ */
+import React from "react";
+import type { FreeModelInfo, ModelSelection, ProgressState, GroupStatus } from "./types.js";
+/** Possible choices from the first-run auth prompt. */
+export type AuthChoice = "oauth" | "api-key" | "free" | "exit";
+/** Props for the AuthPrompt component. */
+export interface AuthPromptProps {
+    /** Callback invoked when the user selects an option. */
+    onSelect: (choice: AuthChoice) => void;
+}
+/**
+ * First-run authentication prompt.
+ *
+ * Renders a 4-option interactive select menu using arrow keys + Enter.
+ */
+export declare function AuthPrompt({ onSelect }: AuthPromptProps): React.ReactElement;
+/** Props for the ApiKeyInput component. */
+export interface ApiKeyInputProps {
+    /** List of provider IDs the user can choose from. */
+    providers: string[];
+    /** Callback invoked when the user submits a provider + key. */
+    onSubmit: (providerId: string, key: string) => void;
+}
+/**
+ * API key entry component.
+ *
+ * Two-step flow:
+ * 1. Select a provider from a list using arrow keys + Enter.
+ * 2. Type/paste the API key and press Enter to submit.
+ */
+export declare function ApiKeyInput({ providers, onSubmit, }: ApiKeyInputProps): React.ReactElement;
+/** A provider available for OAuth authentication. */
+export interface OAuthProviderOption {
+    /** Provider identifier (e.g., `"anthropic"`, `"openai"`). */
+    id: string;
+    /** Display name (e.g., `"Anthropic"`, `"OpenAI"`). */
+    name: string;
+}
+/** Props for the OAuthProviderSelect component. */
+export interface OAuthProviderSelectProps {
+    /** List of providers available for OAuth login. */
+    providers: OAuthProviderOption[];
+    /** Callback invoked when the user selects a provider. */
+    onSelect: (provider: OAuthProviderOption) => void;
+}
+/**
+ * OAuth provider selection component.
+ */
+export declare function OAuthProviderSelect({ providers, onSelect, }: OAuthProviderSelectProps): React.ReactElement;
+/** Props for the OAuthWaiting component. */
+export interface OAuthWaitingProps {
+    /** The provider the user is authenticating with. */
+    providerName: string;
+    /** The URL the user should visit to complete authentication. */
+    url: string;
+}
+/**
+ * OAuth waiting indicator component.
+ */
+export declare function OAuthWaiting({ providerName, url, }: OAuthWaitingProps): React.ReactElement;
+/** Props for the FreeModelPicker component. */
+export interface FreeModelPickerProps {
+    /** Available free models from the Opencode catalog. */
+    models: FreeModelInfo[];
+    /** Callback invoked when the user selects a model. */
+    onSelect: (model: FreeModelInfo) => void;
+}
+/**
+ * Free model selection component.
+ */
+export declare function FreeModelPicker({ models, onSelect, }: FreeModelPickerProps): React.ReactElement;
+/** A single option shown in the config prompt. */
+export interface ConfigOption {
+    /** The model selection this option represents. */
+    value: ModelSelection;
+    /** Display label (e.g., "Anthropic — claude-sonnet-4"). */
+    label: string;
+    /** Optional description shown below the label. */
+    description?: string;
+}
+/** Props for the ConfigPrompt component. */
+export interface ConfigPromptProps {
+    /** Available provider/model options to choose from. */
+    options: ConfigOption[];
+    /** Callback invoked when the user selects an option. */
+    onSelect: (selection: ModelSelection) => void;
+    /** Heading text shown above the option list. Defaults to "Select a provider and model for this project:". */
+    title?: string;
+    /** @internal Override auto-detected max visible items (for testing). */
+    maxVisible?: number;
+}
+/**
+ * Interactive provider/model selection prompt for project configuration.
+ *
+ * Renders a list of provider/model options using arrow keys + Enter,
+ * following the same navigation pattern as AuthPrompt.
+ */
+export declare function ConfigPrompt({ options, onSelect, title, maxVisible, }: ConfigPromptProps): React.ReactElement;
+/** Props for the Header component. */
+export interface HeaderProps {
+    /** Display label for the active model. */
+    modelLabel: string;
+    /** Human-readable provider display name (e.g., "Anthropic", "Opencode"). */
+    providerLabel: string;
+}
+/**
+ * Header component.
+ */
+export declare function Header({ modelLabel, providerLabel }: HeaderProps): React.ReactElement;
+/** Props for the PhaseRow component. */
+export interface PhaseRowProps {
+    /** Display label shown in brackets. */
+    label: string;
+    /** Description text shown after the label. */
+    description: string;
+    /** Status of this phase. */
+    status: "pending" | "active" | "done";
+}
+/**
+ * Renders a single pipeline phase row with status indicator.
+ */
+export declare function PhaseRow({ label, description, status, }: PhaseRowProps): React.ReactElement;
+/** Props for the GroupRow component. */
+export interface GroupRowProps {
+    /** The group status to render. */
+    group: GroupStatus;
+}
+/**
+ * Renders a single file group row within the generation dashboard.
+ *
+ * Uses `groupId` as the display identifier and `label` as the description.
+ */
+export declare function GroupRow({ group }: GroupRowProps): React.ReactElement;
+/** Props for the ExplorationDashboard component. */
+export interface ExplorationDashboardProps {
+    /** Per-group status entries for exploration. */
+    explorationStatuses: GroupStatus[];
+}
+/**
+ * Renders the exploration phase dashboard showing per-group exploration progress.
+ */
+export declare function ExplorationDashboard({ explorationStatuses, }: ExplorationDashboardProps): React.ReactElement;
+/** Props for the GenerationDashboard component. */
+export interface GenerationDashboardProps {
+    /** Per-group status entries. */
+    groupStatuses: GroupStatus[];
+    /** Number of completed sessions. */
+    completedSessions: number;
+    /** Total number of pages to generate. */
+    totalPages: number;
+}
+/**
+ * Renders the generation phase dashboard showing progress for each group.
+ */
+export declare function GenerationDashboard({ groupStatuses, completedSessions, totalPages, }: GenerationDashboardProps): React.ReactElement;
+/** Props for the Summary component. */
+export interface SummaryProps {
+    /** Total number of pages generated. */
+    totalPages: number;
+    /** Number of failed sessions. */
+    failedSessions: number;
+    /** Pipeline start timestamp (ms since epoch). */
+    startedAt: number;
+    /** Pipeline completion timestamp (ms since epoch), or undefined if not complete. */
+    completedAt: number | undefined;
+    /** Warnings to display. */
+    warnings: string[];
+}
+/**
+ * Renders the final summary after pipeline completion.
+ */
+export declare function Summary({ totalPages, failedSessions, startedAt, completedAt, warnings, }: SummaryProps): React.ReactElement;
+/** Props for the App component. */
+export interface AppProps {
+    /** Initial progress state. */
+    initialState: ProgressState;
+    /** Callback to expose the setState function to the pipeline. */
+    onStateRef: (setter: (partial: Partial<ProgressState>) => void) => void;
+}
+/**
+ * Root dashboard component.
+ */
+export declare function App({ initialState, onStateRef }: AppProps): React.ReactElement;
+/**
+ * Non-interactive log-style dashboard for piped output and CI environments.
+ */
+export declare class LogDashboard {
+    private state;
+    private log;
+    private verbose;
+    private loggedGroupStarts;
+    private loggedGroupCompletions;
+    private loggedExplorationStarts;
+    private loggedExplorationCompletions;
+    constructor(initialState: ProgressState, log?: (message: string) => void, verbose?: boolean);
+    updateState(partial: Partial<ProgressState>): void;
+    private logPhaseTransition;
+    private logGroupChanges;
+    private logExplorationChanges;
+    waitUntilExit(): Promise<void>;
+}
+/** Return type for both Ink and log-style dashboards. */
+export interface DashboardHandle {
+    updateState: (partial: Partial<ProgressState>) => void;
+    waitUntilExit: () => Promise<void>;
+}
+/**
+ * Creates the progress dashboard and returns a state updater function
+ * and a `waitUntilExit` promise.
+ */
+export declare function renderDashboard(initialState: ProgressState, verbose?: boolean): DashboardHandle;