@pruddiman/hem 0.0.1-beta-1aff12a → 0.0.1-beta-95d42fc

package/dist/agents/base-agent.js

@@ -14,7 +14,7 @@
  *   - Low-level session ops (`promptAsync`, `session.abort`, `event.subscribe`)
  *     are accessed via `this.provider.session.*` and `this.provider.event.*`.
  */
-import { isAuthExpired, AuthExpiredError } from "../auth.js";
+import { wrapAuthError } from "../auth.js";
 // ── Base Agent ──────────────────────────────────────────────────────────
 /**
  * Abstract base class providing shared session lifecycle management
@@ -44,14 +44,6 @@ export class BaseAgent {
      * @throws {Error} If creation fails for any other reason.
      */
     async createSession(_title) {
-        try {
-            return await this.provider.createSession();
-        }
-        catch (err) {
-            if (isAuthExpired(err)) {
-                throw new AuthExpiredError("the configured provider", err);
-            }
-            throw err;
-        }
+        return wrapAuthError(() => this.provider.createSession());
     }
 }

package/dist/agents/base-arbiter.js

@@ -21,7 +21,7 @@
  * `BaseArbiter` factors out the lifecycle skeleton; subclasses provide
  * the four configuration values above.
  */
-import { isAuthExpired, AuthExpiredError } from "../auth.js";
+import { wrapAuthError } from "../auth.js";
 import { BaseAgent } from "./base-agent.js";
 /**
  * Abstract base for arbiter coordinator agents. Concrete subclasses
@@ -51,21 +51,13 @@ export class BaseArbiter extends BaseAgent {
         if (verbose) {
             verbose(`[${this.tag}] session ${sessionId}`);
         }
-        try {
-            await this.provider.session.promptAsync({
-                path: { id: sessionId },
-                body: {
-                    parts: [{ type: "text", text: prompt }],
-                    agent: this.agentField,
-                },
-            });
-        }
-        catch (err) {
-            if (isAuthExpired(err)) {
-                throw new AuthExpiredError("the configured provider", err);
-            }
-            throw err;
-        }
+        await wrapAuthError(() => this.provider.session.promptAsync({
+            path: { id: sessionId },
+            body: {
+                parts: [{ type: "text", text: prompt }],
+                agent: this.agentField,
+            },
+        }));
         if (verbose) {
             verbose(`[${this.tag}] initial prompt sent (listening for broadcasts)`);
         }

package/dist/auth.d.ts

@@ -162,6 +162,14 @@ export declare class AuthExpiredError extends Error {
     readonly providerName: string;
     constructor(providerName: string, cause?: unknown);
 }
+/**
+ * Run an async operation, converting auth-expiry failures into
+ * {@link AuthExpiredError}. Other errors propagate unchanged.
+ *
+ * Used by call sites that perform a single provider API call and want
+ * uniform auth-error handling.
+ */
+export declare function wrapAuthError<T>(op: () => Promise<T>): Promise<T>;
 /**
  * Determine whether an error indicates expired or invalid authentication.
  *
@@ -364,7 +372,12 @@ export declare function handleAuthLogin(client: OpencodeClient, configDir?: stri
  *
  * Reference: FR-021, contracts/cli-interface.md lines 132-143.
  */
-export declare function handleAuthList(client: OpencodeClient, configDir?: string, writeFn?: (msg: string) => void): Promise<void>;
+/** Per-backbone availability map injected into {@link handleAuthList}. */
+export interface AuthListBackboneAvailability {
+    opencode: boolean;
+    copilot: boolean;
+}
+export declare function handleAuthList(client: OpencodeClient, configDir?: string, writeFn?: (msg: string) => void, availability?: AuthListBackboneAvailability): Promise<void>;
 /**
  * Handle `hem auth logout` — remove credentials.
  *

package/dist/auth.js

@@ -430,6 +430,24 @@ export class AuthExpiredError extends Error {
         }
     }
 }
+/**
+ * Run an async operation, converting auth-expiry failures into
+ * {@link AuthExpiredError}. Other errors propagate unchanged.
+ *
+ * Used by call sites that perform a single provider API call and want
+ * uniform auth-error handling.
+ */
+export async function wrapAuthError(op) {
+    try {
+        return await op();
+    }
+    catch (err) {
+        if (isAuthExpired(err)) {
+            throw new AuthExpiredError("the configured provider", err);
+        }
+        throw err;
+    }
+}
 /**
  * Determine whether an error indicates expired or invalid authentication.
  *
@@ -1007,29 +1025,7 @@ function formatAuthMethod(authMethod) {
             return "(env var)";
     }
 }
-/**
- * Handle `hem auth list` — show connected providers with status.
- *
- * Calls `client.config.providers()`, formats and prints connected providers
- * with status (checkmark + name + auth method) per `contracts/cli-interface.md`
- * lines 132-143, also shows the default model from preferences.
- *
- * Output format:
- * ```
- *   Connected providers:
- *     ✓ anthropic    Claude Pro/Max (OAuth)
- *     ✓ opencode     Zen API Key
- *
- *   Default model: anthropic/claude-sonnet-4
- * ```
- *
- * @param client — OpenCode SDK client instance.
- * @param configDir — Override for the config directory (used in tests).
- * @param writeFn — Override for the output function (used in tests).
- *
- * Reference: FR-021, contracts/cli-interface.md lines 132-143.
- */
-export async function handleAuthList(client, configDir, writeFn = (msg) => process.stdout.write(msg)) {
+export async function handleAuthList(client, configDir, writeFn = (msg) => process.stdout.write(msg), availability) {
     // Query the SDK for connected providers.
     const result = await client.config.providers();
     const sdkProviders = result.data?.providers ?? [];
@@ -1057,7 +1053,17 @@ export async function handleAuthList(client, configDir, writeFn = (msg) => proce
         for (const provider of connectedProviders) {
             const padding = " ".repeat(Math.max(1, maxIdLen - provider.id.length + 4));
             const method = formatAuthMethod(provider.authMethod);
-            writeFn(`    \u2713 ${provider.id}${padding}${provider.name} ${method}\n`);
+            // Annotate copilot-backed providers as ✗ when the copilot CLI is
+            // missing so the user knows the credential alone won't get them
+            // through generation. Opencode-backed providers are always reachable
+            // here because handleAuthList only runs when opencode is present.
+            const isCopilot = provider.id === "github-copilot" || provider.id === "copilot";
+            const reachable = !isCopilot || availability?.copilot !== false;
+            const icon = reachable ? "\u2713" : "\u2717";
+            const suffix = reachable
+                ? ""
+                : "  (copilot CLI not installed — npm install -g @github/copilot)";
+            writeFn(`    ${icon} ${provider.id}${padding}${provider.name} ${method}${suffix}\n`);
         }
     }
     writeFn("\n");

package/dist/grouping.js

@@ -66,7 +66,9 @@ export function matchDocFolder(filePath, priors) {
     if (priors.length === 0)
         return null;
     const segments = filePath.split("/").map((s) => s.toLowerCase());
-    const fileStem = extractStem(segments[segments.length - 1] ?? "");
+    const lastSegment = segments[segments.length - 1] ?? "";
+    const dotIndex = lastSegment.indexOf(".");
+    const fileStem = (dotIndex === -1 ? lastSegment : lastSegment.substring(0, dotIndex)).toLowerCase();
     // Prefer the prior with the longest key match to avoid `auth` stealing
     // files that should go to `authentication`.
     let best = null;
@@ -90,10 +92,6 @@ export function normalizeFolderKey(name) {
         .replace(/-+/g, "-")
         .replace(/^-|-$/g, "");
 }
-function extractStem(basename) {
-    const dotIndex = basename.indexOf(".");
-    return (dotIndex === -1 ? basename : basename.substring(0, dotIndex)).toLowerCase();
-}
 /**
  * Scoring:
  *   - 3 for a directory-segment match (strongest signal).
@@ -244,17 +242,6 @@ export function commonDirectory(files) {
     }
     return common.length === 0 ? "." : common.join("/");
 }
-/**
- * Returns the "name" portion of the file without known layer suffixes
- * and without the actual file extension.
- * E.g. `user.controller.ts` → the layer suffix is `.controller` → stem `user`.
- * `helpers.ts` → no layer suffix → stem `helpers`.
- */
-function fileNameWithoutExtension(relativePath) {
-    const base = relativePath.split("/").pop() ?? "";
-    const lastDot = base.lastIndexOf(".");
-    return lastDot === -1 ? base : base.substring(0, lastDot);
-}
 /**
  * Detects the architectural layer for a file by checking its name
  * against known suffixes.
@@ -262,7 +249,9 @@ function fileNameWithoutExtension(relativePath) {
  * @returns The layer label (e.g., "Controllers") or `undefined`.
  */
 function detectLayer(relativePath) {
-    const nameNoExt = fileNameWithoutExtension(relativePath).toLowerCase();
+    const base = relativePath.split("/").pop() ?? "";
+    const lastDot = base.lastIndexOf(".");
+    const nameNoExt = (lastDot === -1 ? base : base.substring(0, lastDot)).toLowerCase();
     for (const { suffix, label } of LAYER_SUFFIXES) {
         if (nameNoExt.endsWith(suffix)) {
             return label;

package/dist/helpers/parsing.d.ts

@@ -1,20 +1,6 @@
 /**
  * Text extraction and parsing utilities for Hem.
- *
- * Provides helpers for extracting structured content (Markdown, JSON,
- * file lists, concepts) from LLM response text.
  */
-import type { MessagePart } from "../session.js";
-/**
- * Extracts the Markdown content from the OpenCode prompt response.
- *
- * Concatenates all text parts from the response, stripping any wrapping
- * code fences if the LLM returned the content inside a fenced block.
- *
- * @param parts - The response parts from `promptAndWait()`.
- * @returns The extracted Markdown string.
- */
-export declare function extractMarkdown(parts: Array<MessagePart>): string;
 /**
  * Extracts a JSON string from an LLM response that may contain preamble text.
  *
@@ -31,22 +17,3 @@ export declare function extractMarkdown(parts: Array<MessagePart>): string;
  * @returns The extracted JSON substring (not yet parsed).
  */
 export declare function extractJSON(response: string): string;
-/**
- * Extracts `relatedFiles` from generated Markdown content.
- *
- * Looks for the "Source Files" or "Related Files" section and extracts file
- * paths from backtick-quoted entries (e.g., `` `src/user/controller.ts` ``).
- *
- * @param content - The generated Markdown content.
- * @returns Array of relative file paths found in the Source Files section.
- */
-export declare function parseRelatedFiles(content: string): string[];
-/**
- * Extracts key concept names from section content.
- *
- * Looks for backtick-quoted identifiers as a heuristic for concepts.
- *
- * @param content - The section body text.
- * @returns Array of unique concept strings.
- */
-export declare function extractConcepts(content: string): string[];

package/dist/helpers/parsing.js

@@ -1,36 +1,6 @@
 /**
  * Text extraction and parsing utilities for Hem.
- *
- * Provides helpers for extracting structured content (Markdown, JSON,
- * file lists, concepts) from LLM response text.
  */
-/**
- * Extracts the Markdown content from the OpenCode prompt response.
- *
- * Concatenates all text parts from the response, stripping any wrapping
- * code fences if the LLM returned the content inside a fenced block.
- *
- * @param parts - The response parts from `promptAndWait()`.
- * @returns The extracted Markdown string.
- */
-export function extractMarkdown(parts) {
-    const textParts = parts.filter((p) => p.type === "text" && typeof p.text === "string");
-    let content = textParts.map((p) => p.text).join("\n");
-    // Strip wrapping ```markdown ... ``` fences if present
-    const fencePattern = /^```(?:markdown|md)?\s*\n([\s\S]*?)\n```\s*$/;
-    const match = content.match(fencePattern);
-    if (match) {
-        content = match[1];
-    }
-    // Strip preamble text before the first Markdown heading.
-    // LLMs sometimes produce commentary like "Now I have a thorough
-    // understanding of the codebase..." before the actual document.
-    const h1Match = content.search(/^# .+/m);
-    if (h1Match > 0) {
-        content = content.slice(h1Match);
-    }
-    return content.trim();
-}
 /**
  * Extracts a JSON string from an LLM response that may contain preamble text.
  *
@@ -76,53 +46,3 @@ export function extractJSON(response) {
     // Strategy 3: return full string (caller's JSON.parse will validate)
     return response;
 }
-/**
- * Extracts `relatedFiles` from generated Markdown content.
- *
- * Looks for the "Source Files" or "Related Files" section and extracts file
- * paths from backtick-quoted entries (e.g., `` `src/user/controller.ts` ``).
- *
- * @param content - The generated Markdown content.
- * @returns Array of relative file paths found in the Source Files section.
- */
-export function parseRelatedFiles(content) {
-    const files = [];
-    const lines = content.split("\n");
-    let inSection = false;
-    for (const line of lines) {
-        // Detect start of Source Files / Related Files section
-        if (/^##\s+(Source|Related) Files/i.test(line)) {
-            inSection = true;
-            continue;
-        }
-        // End section at next heading
-        if (inSection && /^##\s+/.test(line)) {
-            break;
-        }
-        // Extract file paths from backtick-quoted list items
-        if (inSection) {
-            const match = line.match(/`([^`]+)`/);
-            if (match) {
-                files.push(match[1]);
-            }
-        }
-    }
-    return files;
-}
-/**
- * Extracts key concept names from section content.
- *
- * Looks for backtick-quoted identifiers as a heuristic for concepts.
- *
- * @param content - The section body text.
- * @returns Array of unique concept strings.
- */
-export function extractConcepts(content) {
-    const matches = content.match(/`([^`]+)`/g);
-    if (!matches)
-        return [];
-    const unique = new Set(matches
-        .map((m) => m.slice(1, -1))
-        .filter((c) => c.length > 0 && !/^\s|\s$/.test(c) && !c.includes("  ")));
-    return Array.from(unique);
-}

package/dist/helpers/paths.d.ts

@@ -29,13 +29,3 @@ export declare function isPathWithin(child: string, parent: string): boolean;
  * @throws If the resolved path falls outside the destination directory.
  */
 export declare function resolveOutputPath(destinationPath: string, relativePath: string): string;
-/**
- * Validates the relationship between destination and source paths.
- *
- * When the destination directory is inside the source directory, logs
- * a note that destination files will be excluded from scanning.
- *
- * @param destinationPath - Path to the destination directory.
- * @param sourcePath - Path to the source directory.
- */
-export declare function validateDestinationPath(destinationPath: string, sourcePath: string): void;

package/dist/helpers/paths.js

@@ -48,20 +48,3 @@ export function resolveOutputPath(destinationPath, relativePath) {
     }
     return resolved;
 }
-/**
- * Validates the relationship between destination and source paths.
- *
- * When the destination directory is inside the source directory, logs
- * a note that destination files will be excluded from scanning.
- *
- * @param destinationPath - Path to the destination directory.
- * @param sourcePath - Path to the source directory.
- */
-export function validateDestinationPath(destinationPath, sourcePath) {
-    const absoluteDestination = resolve(destinationPath);
-    const absoluteSource = resolve(sourcePath);
-    if (isPathWithin(absoluteDestination, absoluteSource)) {
-        console.log(`Note: Destination "${absoluteDestination}" is inside source "${absoluteSource}". ` +
-            `Destination files will be excluded from scanning.`);
-    }
-}

package/dist/helpers/strings.d.ts

@@ -13,13 +13,6 @@
  * @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.
  *

package/dist/helpers/strings.js

@@ -21,20 +21,6 @@ export function toKebabCase(input) {
         .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.
  *

package/dist/import-graph.d.ts

@@ -45,19 +45,6 @@ export declare function buildImportGraph(files: FileInfo[]): Promise<ImportAnaly
  * isolated nodes appear as singleton components.
  */
 export declare function connectedComponents(universe: readonly string[], localEdges: Map<string, string[]>): string[][];
-/**
- * Compute fan-in (how many files import this file) and fan-out (how many
- * files this file imports) for every node in `universe`.
- */
-export declare function computeDegrees(universe: readonly string[], localEdges: Map<string, string[]>): Map<string, {
-    fanIn: number;
-    fanOut: number;
-}>;
-/**
- * Identify files participating in an import cycle. Uses iterative Tarjan's
- * SCC; any SCC with ≥2 members or a self-loop marks its members as cyclic.
- */
-export declare function nodesInCycles(localEdges: Map<string, string[]>): Set<string>;
 /**
  * Yield every import specifier found in `content` along with the 1-based
  * line number it appears on.

package/dist/import-graph.js

@@ -130,110 +130,6 @@ export function connectedComponents(universe, localEdges) {
     }
     return [...components.values()].map((c) => c.slice().sort((a, b) => a.localeCompare(b)));
 }
-/**
- * Compute fan-in (how many files import this file) and fan-out (how many
- * files this file imports) for every node in `universe`.
- */
-export function computeDegrees(universe, localEdges) {
-    const degrees = new Map();
-    for (const node of universe) {
-        degrees.set(node, { fanIn: 0, fanOut: 0 });
-    }
-    for (const [from, tos] of localEdges) {
-        const d = degrees.get(from);
-        if (!d)
-            continue;
-        d.fanOut = tos.length;
-        for (const to of tos) {
-            const td = degrees.get(to);
-            if (td)
-                td.fanIn += 1;
-        }
-    }
-    return degrees;
-}
-/**
- * Identify files participating in an import cycle. Uses iterative Tarjan's
- * SCC; any SCC with ≥2 members or a self-loop marks its members as cyclic.
- */
-export function nodesInCycles(localEdges) {
-    const index = new Map();
-    const lowlink = new Map();
-    const onStack = new Set();
-    const stack = [];
-    const result = new Set();
-    let counter = 0;
-    const nodes = new Set();
-    for (const [from, tos] of localEdges) {
-        nodes.add(from);
-        for (const to of tos)
-            nodes.add(to);
-    }
-    const strongConnect = (start) => {
-        const frames = [];
-        index.set(start, counter);
-        lowlink.set(start, counter);
-        counter++;
-        stack.push(start);
-        onStack.add(start);
-        frames.push({
-            node: start,
-            iter: (localEdges.get(start) ?? [])[Symbol.iterator](),
-        });
-        while (frames.length > 0) {
-            const frame = frames[frames.length - 1];
-            const next = frame.iter.next();
-            if (next.done) {
-                // Finished with frame.node — check if it's an SCC root.
-                if (lowlink.get(frame.node) === index.get(frame.node)) {
-                    const component = [];
-                    let w;
-                    do {
-                        w = stack.pop();
-                        onStack.delete(w);
-                        component.push(w);
-                    } while (w !== frame.node);
-                    const neighbours = localEdges.get(frame.node) ?? [];
-                    const hasSelfLoop = neighbours.includes(frame.node);
-                    if (component.length >= 2 || hasSelfLoop) {
-                        for (const m of component)
-                            result.add(m);
-                    }
-                }
-                frames.pop();
-                // Propagate lowlink to parent.
-                if (frames.length > 0) {
-                    const parentFrame = frames[frames.length - 1];
-                    const pl = lowlink.get(parentFrame.node);
-                    const cl = lowlink.get(frame.node);
-                    if (cl < pl)
-                        lowlink.set(parentFrame.node, cl);
-                }
-                continue;
-            }
-            const w = next.value;
-            if (!index.has(w)) {
-                index.set(w, counter);
-                lowlink.set(w, counter);
-                counter++;
-                stack.push(w);
-                onStack.add(w);
-                frames.push({ node: w, iter: (localEdges.get(w) ?? [])[Symbol.iterator]() });
-            }
-            else if (onStack.has(w)) {
-                const cur = lowlink.get(frame.node);
-                const wIndex = index.get(w);
-                if (wIndex < cur)
-                    lowlink.set(frame.node, wIndex);
-            }
-        }
-    };
-    for (const node of nodes) {
-        if (!index.has(node))
-            strongConnect(node);
-    }
-    return result;
-}
 // ── Internal helpers ────────────────────────────────────────────────────
 /**
  * Yield every import specifier found in `content` along with the 1-based

package/dist/index.d.ts

@@ -28,6 +28,7 @@ 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 { getBackboneAvailability } from "./providers/index.js";
 import { generateDocumentation, getExitCode } from "./orchestrator.js";
 export { getExitCode };
 import { renderDashboard } from "./progress.js";
@@ -78,15 +79,16 @@ export interface Dependencies {
     detectChangedDocs: typeof detectChangedDocs;
     writeChangelogEntry: typeof writeChangelogEntry;
     scopeToChangedFiles: typeof scopeToChangedFiles;
+    getBackboneAvailability: typeof getBackboneAvailability;
 }
 /**
  * Subset of {@link Dependencies} actually needed by `handleAuth`.
  * Narrower types document what each entry-point actually depends on
  * and let test mocks omit unrelated fields without TypeScript errors.
  */
-export type AuthDeps = Pick<Dependencies, "startWithRetry" | "findFreePort" | "createOpencode" | "handleAuthLogin" | "handleAuthList" | "handleAuthLogout">;
+export type AuthDeps = Pick<Dependencies, "startWithRetry" | "findFreePort" | "createOpencode" | "handleAuthLogin" | "handleAuthList" | "handleAuthLogout" | "getBackboneAvailability">;
 /** Subset of {@link Dependencies} actually needed by `handleConfig`. */
-export type ConfigDeps = Pick<Dependencies, "startWithRetry" | "findFreePort" | "createOpencode" | "detectAuthState" | "handleFirstRun" | "saveProjectConfig" | "renderAndWait" | "listProviderModels">;
+export type ConfigDeps = Pick<Dependencies, "startWithRetry" | "findFreePort" | "createOpencode" | "detectAuthState" | "handleFirstRun" | "saveProjectConfig" | "renderAndWait" | "listProviderModels" | "getBackboneAvailability">;
 /** Default (production) dependency bag. */
 export declare const defaultDeps: Dependencies;
 /**
@@ -132,13 +134,29 @@ export declare function handleGenerate(opts: {
 }, deps?: Dependencies): Promise<GenerateCLIOptions | null>;
 /**
  * Handle the `auth` subcommand.
+ *
+ * Gracefully degrades when the opencode CLI is missing: rather than
+ * crashing with `spawn opencode ENOENT`, prints a backbone-availability
+ * report so the user knows what to install. Login/logout require opencode
+ * today (the auth flows are opencode-managed); copilot uses GitHub
+ * authentication outside hem (`$GITHUB_TOKEN` or `gh auth login`).
  */
 export declare function handleAuth(action: string | undefined, target: string | undefined, deps?: AuthDeps): Promise<AuthCLIOptions | null>;
 /**
  * Handle the `config` subcommand.
  *
- * Interactively prompts the user to select a provider/model and saves
- * the configuration to `{cwd}/.hem/config.json`.
+ * Always opens with a backbone picker that lists every supported
+ * provider backbone (currently opencode and copilot) with a green \u2713
+ * "installed" or red \u2717 "not installed" indicator alongside an
+ * install hint. The user picks an installed backbone; uninstalled ones
+ * are visible but not selectable.
+ *
+ *   - Pick `opencode` → start the opencode server, run the existing
+ *     auth-detect + sub-provider/model selection flow.
+ *   - Pick `copilot`  → save `{providerID: "github-copilot", modelID: "default"}`
+ *     directly (no opencode server needed).
+ *   - No backbones installed → print install hints for all of them and
+ *     exit non-zero.
  */
 export declare function handleConfig(deps?: ConfigDeps): Promise<ConfigCLIOptions | null>;
 /**