@pruddiman/hem 0.0.1-beta-5671db0

package/dist/helpers/strings.d.ts

@@ -0,0 +1,45 @@
+/**
+ * String transformation utilities for Hem.
+ *
+ * Consolidated from output.ts, grouping.ts, and session.ts to eliminate
+ * duplication and improve discoverability.
+ */
+/**
+ * Converts a string to kebab-case.
+ *
+ * Handles camelCase splitting, underscores, spaces, and special characters.
+ *
+ * @param input - The string to convert.
+ * @returns kebab-cased string.
+ */
+export declare function toKebabCase(input: string): string;
+/**
+ * Converts a heading string to a URL-friendly slug.
+ *
+ * @param heading - The heading text.
+ * @returns A kebab-case slug (e.g., "Related Files" → "related-files").
+ */
+export declare function toSlug(heading: string): string;
+/**
+ * Converts a directory name to a section heading.
+ *
+ * Converts kebab-case directory names to Title Case:
+ *   `user-auth` → `User Auth`
+ *   `api` → `Api`
+ *
+ * @param dir - The directory name (without trailing slash).
+ * @returns A human-readable heading string.
+ */
+export declare function dirToHeading(dir: string): string;
+/**
+ * Derives a display title from a file path.
+ *
+ * Converts kebab-case filenames to Title Case with acronym awareness:
+ *   `features/user-authentication.md` → `User Authentication`
+ *   `llm-grouping-agent.md`          → `LLM Grouping Agent`
+ *   `sse-relay-lifecycle.md`          → `SSE Relay Lifecycle`
+ *
+ * @param filePath - Relative file path.
+ * @returns A human-readable title.
+ */
+export declare function fileToTitle(filePath: string): string;

package/dist/helpers/strings.js

@@ -0,0 +1,97 @@
+/**
+ * String transformation utilities for Hem.
+ *
+ * Consolidated from output.ts, grouping.ts, and session.ts to eliminate
+ * duplication and improve discoverability.
+ */
+/**
+ * Converts a string to kebab-case.
+ *
+ * Handles camelCase splitting, underscores, spaces, and special characters.
+ *
+ * @param input - The string to convert.
+ * @returns kebab-cased string.
+ */
+export function toKebabCase(input) {
+    return input
+        .replace(/([a-z])([A-Z])/g, "$1-$2")
+        .replace(/[\s_]+/g, "-")
+        .replace(/[^a-zA-Z0-9-]/g, "")
+        .toLowerCase()
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+/**
+ * Converts a heading string to a URL-friendly slug.
+ *
+ * @param heading - The heading text.
+ * @returns A kebab-case slug (e.g., "Related Files" → "related-files").
+ */
+export function toSlug(heading) {
+    return heading
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, "")
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+/**
+ * Converts a directory name to a section heading.
+ *
+ * Converts kebab-case directory names to Title Case:
+ *   `user-auth` → `User Auth`
+ *   `api` → `Api`
+ *
+ * @param dir - The directory name (without trailing slash).
+ * @returns A human-readable heading string.
+ */
+export function dirToHeading(dir) {
+    return dir
+        .split("-")
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
+}
+/**
+ * Known acronyms and special-cased words for title generation.
+ *
+ * When converting kebab-case filenames to Title Case, these words are
+ * replaced with their canonical casing rather than naive first-letter
+ * capitalization (e.g., `llm` → `LLM`, not `Llm`).
+ */
+const ACRONYM_MAP = {
+    llm: "LLM",
+    cli: "CLI",
+    sdk: "SDK",
+    sse: "SSE",
+    mcp: "MCP",
+    api: "API",
+    ui: "UI",
+    opencode: "OpenCode",
+};
+/**
+ * Derives a display title from a file path.
+ *
+ * Converts kebab-case filenames to Title Case with acronym awareness:
+ *   `features/user-authentication.md` → `User Authentication`
+ *   `llm-grouping-agent.md`          → `LLM Grouping Agent`
+ *   `sse-relay-lifecycle.md`          → `SSE Relay Lifecycle`
+ *
+ * @param filePath - Relative file path.
+ * @returns A human-readable title.
+ */
+export function fileToTitle(filePath) {
+    // Extract filename without extension and directory
+    const parts = filePath.split("/");
+    const filename = parts[parts.length - 1] ?? filePath;
+    const stem = filename.replace(/\.md$/, "");
+    // Convert kebab-case to Title Case with acronym awareness
+    return stem
+        .split("-")
+        .map((word) => {
+        const lower = word.toLowerCase();
+        if (ACRONYM_MAP[lower])
+            return ACRONYM_MAP[lower];
+        return word.charAt(0).toUpperCase() + word.slice(1);
+    })
+        .join(" ");
+}

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+#!/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 type { CLIOptions, ProgressState } from "./types.js";
+import { loadPreferences, loadProjectConfig, saveProjectConfig, detectAuthState, injectApiKey, handleFirstRun, renderAndWait, handleAuthLogin, handleAuthList, handleAuthLogout, validateStoredModel, resolveActualModel, listProviderModels } from "./auth.js";
+import { createOpencode } from "@opencode-ai/sdk";
+import { findFreePort, startWithRetry } from "./server-utils.js";
+import { discoverFiles, detectProjectName } from "./discovery.js";
+import { groupFiles } from "./grouping.js";
+import type { Provider } from "./providers/types.js";
+import { generateDocumentation, getExitCode } from "./orchestrator.js";
+export { getExitCode };
+import { renderDashboard } from "./progress.js";
+import { generateTableOfContents, writeTableOfContents, writeArchitectureOverview, scanDocFiles, ensureDestinationDir, removeEmptyDirs } from "./output.js";
+import { readLastSHA, computeChangedFiles, getCurrentSHA, detectChangedDocs, writeChangelogEntry } from "./changelog.js";
+import { scopeToChangedFiles } from "./diff-scope.js";
+/**
+ * Dependencies injected into `handleGenerate` and `handleAuth` for testability.
+ * Production code uses the real implementations; tests can substitute mocks.
+ */
+export interface Dependencies {
+    createOpencode: typeof createOpencode;
+    findFreePort: typeof findFreePort;
+    startWithRetry: typeof startWithRetry;
+    loadPreferences: typeof loadPreferences;
+    detectAuthState: typeof detectAuthState;
+    injectApiKey: typeof injectApiKey;
+    handleFirstRun: typeof handleFirstRun;
+    handleAuthLogin: typeof handleAuthLogin;
+    handleAuthList: typeof handleAuthList;
+    handleAuthLogout: typeof handleAuthLogout;
+    loadProjectConfig: typeof loadProjectConfig;
+    saveProjectConfig: typeof saveProjectConfig;
+    renderAndWait: typeof renderAndWait;
+    validateStoredModel: typeof validateStoredModel;
+    resolveActualModel: typeof resolveActualModel;
+    listProviderModels: typeof listProviderModels;
+    checkSourceExists: (path: string) => Promise<void>;
+    discoverFiles: typeof discoverFiles;
+    detectProjectName: typeof detectProjectName;
+    groupFiles: typeof groupFiles;
+    createProvider: (config: import("./providers/types.js").ProviderConfig) => Promise<Provider>;
+    generateDocumentation: typeof generateDocumentation;
+    renderDashboard: (initialState: ProgressState, verbose?: boolean) => ReturnType<typeof renderDashboard>;
+    generateTableOfContents: typeof generateTableOfContents;
+    writeTableOfContents: typeof writeTableOfContents;
+    writeArchitectureOverview: typeof writeArchitectureOverview;
+    scanDocFiles: typeof scanDocFiles;
+    ensureDestinationDir: typeof ensureDestinationDir;
+    removeEmptyDirs: typeof removeEmptyDirs;
+    readLastSHA: typeof readLastSHA;
+    computeChangedFiles: typeof computeChangedFiles;
+    getCurrentSHA: typeof getCurrentSHA;
+    detectChangedDocs: typeof detectChangedDocs;
+    writeChangelogEntry: typeof writeChangelogEntry;
+    scopeToChangedFiles: typeof scopeToChangedFiles;
+}
+/** Default (production) dependency bag. */
+export declare const defaultDeps: Dependencies;
+/**
+ * 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 declare function handleGenerate(opts: {
+    source: string;
+    destination: string;
+    files: string;
+    concurrency: number;
+    model?: string;
+    apiKey?: string;
+    name?: string;
+    verbose?: boolean;
+    full?: boolean;
+    worktree?: boolean;
+}, deps?: Dependencies): Promise<CLIOptions | null>;
+/**
+ * Handle the `auth` subcommand.
+ */
+export declare function handleAuth(action: string | undefined, target: string | undefined, deps?: Dependencies): Promise<CLIOptions | null>;
+/**
+ * Handle the `config` subcommand.
+ *
+ * Interactively prompts the user to select a provider/model and saves
+ * the configuration to `{cwd}/.hem/config.json`.
+ */
+export declare function handleConfig(deps?: Dependencies): Promise<CLIOptions | null>;
+/**
+ * Build and return a configured Commander program.
+ */
+export declare function buildProgram(deps?: Dependencies): Command;