@pruddiman/hem 0.0.1-beta-5671db0

package/dist/broadcast-mcp.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Standalone stdio-based MCP server for inter-agent broadcast communication.
+ *
+ * Exposes a single tool: `broadcast({ message: string })`
+ *
+ * This server is intentionally minimal. The real broadcast relay logic lives
+ * in the Hem orchestrator, which intercepts broadcast tool calls via SSE
+ * events and relays messages to peer agent sessions using `promptAsync()`.
+ *
+ * The server simply returns `{ status: "sent" }` to satisfy the agent's tool
+ * call — the orchestrator handles the actual message routing.
+ *
+ * Architecture:
+ *   Agent calls broadcast() → MCP server returns "sent" →
+ *   Orchestrator sees tool call in SSE → promptAsync() to all peers
+ *
+ * Registered in OpenCode via config.mcp as:
+ *   { type: "local", command: ["node", "dist/broadcast-mcp.js"], enabled: true }
+ */
+export {};

package/dist/broadcast-mcp.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * Standalone stdio-based MCP server for inter-agent broadcast communication.
+ *
+ * Exposes a single tool: `broadcast({ message: string })`
+ *
+ * This server is intentionally minimal. The real broadcast relay logic lives
+ * in the Hem orchestrator, which intercepts broadcast tool calls via SSE
+ * events and relays messages to peer agent sessions using `promptAsync()`.
+ *
+ * The server simply returns `{ status: "sent" }` to satisfy the agent's tool
+ * call — the orchestrator handles the actual message routing.
+ *
+ * Architecture:
+ *   Agent calls broadcast() → MCP server returns "sent" →
+ *   Orchestrator sees tool call in SSE → promptAsync() to all peers
+ *
+ * Registered in OpenCode via config.mcp as:
+ *   { type: "local", command: ["node", "dist/broadcast-mcp.js"], enabled: true }
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod/v4";
+const server = new McpServer({
+    name: "hem-broadcast",
+    version: "1.0.0",
+});
+server.registerTool("broadcast", {
+    description: "Broadcast a message to all other parallel organization workers. " +
+        "Use this to communicate file renames, deletions, structural conventions, " +
+        "and brief acknowledgements. Messages should be short and actionable.",
+    inputSchema: {
+        message: z
+            .string()
+            .describe("The message to broadcast. Use structured prefixes: " +
+            "RENAMED:, DELETED:, CONVENTION:, ACK:, SUGGESTION:"),
+    },
+}, async ({ message }) => {
+    // The actual relay is handled by the orchestrator via SSE interception.
+    // This tool just needs to return success so the agent can continue.
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ status: "sent", message }),
+            },
+        ],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout is the MCP transport — use stderr for logging
+    console.error("[hem-broadcast] MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("[hem-broadcast] Fatal:", err);
+    process.exit(1);
+});

package/dist/changelog.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Changelog generation and git-based diff scoping for Hem.
+ *
+ * Manages `changelog.md` in the documentation destination directory.
+ * Each Hem run appends a single entry recording the commit SHA, timestamp,
+ * and which doc files were created or updated.
+ *
+ * On subsequent runs, the previous SHA is extracted from `changelog.md`
+ * to compute which source files changed, enabling incremental generation.
+ *
+ * Reference: specs/004-changelog-diff-scope.
+ */
+/**
+ * Reads the most recent commit SHA from the changelog file.
+ *
+ * Parses `{destinationPath}/changelog.md` for the first occurrence of
+ * `<!-- hem-sha: <SHA> -->`. Since entries are prepended (newest first),
+ * the first match is the most recent.
+ *
+ * @param destinationPath - Absolute or relative path to the docs directory.
+ * @returns The SHA string, or `null` if the file doesn't exist or has no marker.
+ */
+export declare function readLastSHA(destinationPath: string): Promise<string | null>;
+/**
+ * Computes which source files changed between a previous commit and HEAD.
+ *
+ * Runs `git diff --name-only <prevSHA>..HEAD` scoped to the source
+ * directory. Returns paths relative to `sourceRoot`. Downstream callers
+ * (e.g., `scopeToChangedFiles`) apply glob-level filtering, so this
+ * function returns all changed paths under `sourceRoot`.
+ *
+ * @param sourceRoot - Absolute path to the source directory.
+ * @param prevSHA   - The commit SHA from the previous Hem run.
+ * @returns Array of relative paths of changed source files.
+ * @throws If git is not available, the repo is not a git repo, or the SHA is invalid.
+ */
+export declare function computeChangedFiles(sourceRoot: string, prevSHA: string): string[];
+/**
+ * Returns the current HEAD commit SHA.
+ *
+ * @param sourceRoot - Absolute path to a directory within the git repo.
+ * @returns The full commit SHA string.
+ * @throws If git is not available or the directory is not in a git repo.
+ */
+export declare function getCurrentSHA(sourceRoot: string): string;
+/**
+ * Determines which doc files were created or modified during this Hem run.
+ *
+ * Uses `git status --porcelain` on the destination directory to find
+ * untracked (new) and modified files. This captures changes made by
+ * doc agents, post-processing agents, and structural file writes.
+ *
+ * @param destinationPath - Absolute path to the docs directory.
+ * @returns Array of relative paths of new/modified `.md` files.
+ */
+export declare function detectChangedDocs(destinationPath: string): string[];
+/**
+ * Writes (or appends to) the changelog file with a new entry.
+ *
+ * Entries are prepended after the `# Changelog` heading so the most
+ * recent entry is always first. If the file doesn't exist, it is created
+ * with the heading.
+ *
+ * ### Entry format
+ *
+ * ```markdown
+ * ## 2026-02-21T15:30:00.000Z
+ * <!-- hem-sha: abc1234 -->
+ * - Updated: features/auth.md
+ * - Created: layers/database.md
+ * ```
+ *
+ * For initial runs:
+ * ```markdown
+ * ## 2026-02-21T15:30:00.000Z
+ * <!-- hem-sha: abc1234 -->
+ * - Initial documentation generation
+ * ```
+ *
+ * @param destinationPath - Absolute path to the docs directory.
+ * @param commitSHA       - The HEAD commit SHA at the time of this run.
+ * @param docPaths        - Relative paths of docs that were created/updated.
+ * @param isInitial       - Whether this is the first Hem run (no prior changelog).
+ */
+export declare function writeChangelogEntry(destinationPath: string, commitSHA: string, docPaths: string[], isInitial: boolean): Promise<void>;

package/dist/changelog.js

@@ -0,0 +1,223 @@
+/**
+ * Changelog generation and git-based diff scoping for Hem.
+ *
+ * Manages `changelog.md` in the documentation destination directory.
+ * Each Hem run appends a single entry recording the commit SHA, timestamp,
+ * and which doc files were created or updated.
+ *
+ * On subsequent runs, the previous SHA is extracted from `changelog.md`
+ * to compute which source files changed, enabling incremental generation.
+ *
+ * Reference: specs/004-changelog-diff-scope.
+ */
+import { resolve, join, relative } from "node:path";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { execSync } from "node:child_process";
+// ── SHA Marker ─────────────────────────────────────────────────────────
+/**
+ * HTML comment pattern used to embed commit SHAs in changelog entries.
+ *
+ * Example: `<!-- hem-sha: abc1234def5678 -->`
+ */
+const SHA_MARKER_RE = /<!-- hem-sha: ([0-9a-f]+) -->/;
+// ── Read Previous SHA ─────────────────────────────────────────────────
+/**
+ * Reads the most recent commit SHA from the changelog file.
+ *
+ * Parses `{destinationPath}/changelog.md` for the first occurrence of
+ * `<!-- hem-sha: <SHA> -->`. Since entries are prepended (newest first),
+ * the first match is the most recent.
+ *
+ * @param destinationPath - Absolute or relative path to the docs directory.
+ * @returns The SHA string, or `null` if the file doesn't exist or has no marker.
+ */
+export async function readLastSHA(destinationPath) {
+    const changelogPath = join(resolve(destinationPath), "changelog.md");
+    let content;
+    try {
+        content = await readFile(changelogPath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    const match = SHA_MARKER_RE.exec(content);
+    return match?.[1] ?? null;
+}
+// ── Compute Changed Files ─────────────────────────────────────────────
+/**
+ * Computes which source files changed between a previous commit and HEAD.
+ *
+ * Runs `git diff --name-only <prevSHA>..HEAD` scoped to the source
+ * directory. Returns paths relative to `sourceRoot`. Downstream callers
+ * (e.g., `scopeToChangedFiles`) apply glob-level filtering, so this
+ * function returns all changed paths under `sourceRoot`.
+ *
+ * @param sourceRoot - Absolute path to the source directory.
+ * @param prevSHA   - The commit SHA from the previous Hem run.
+ * @returns Array of relative paths of changed source files.
+ * @throws If git is not available, the repo is not a git repo, or the SHA is invalid.
+ */
+export function computeChangedFiles(sourceRoot, prevSHA) {
+    const absoluteSource = resolve(sourceRoot);
+    // Scope git diff to the source directory via `-- .`.
+    const cmd = `git diff --name-only ${prevSHA}..HEAD -- .`;
+    const output = execSync(cmd, {
+        cwd: absoluteSource,
+        encoding: "utf-8",
+        timeout: 15_000,
+    });
+    // `git diff --name-only` always returns paths relative to the repo root,
+    // regardless of cwd. We need to strip the source directory prefix so the
+    // returned paths are relative to sourceRoot (matching FileInfo.path).
+    const repoRoot = execSync("git rev-parse --show-toplevel", {
+        cwd: absoluteSource,
+        encoding: "utf-8",
+        timeout: 5_000,
+    }).trim();
+    const sourceRel = relative(repoRoot, absoluteSource).replace(/\\/g, "/");
+    return output
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => {
+        const normalized = line.replace(/\\/g, "/");
+        if (sourceRel && normalized.startsWith(sourceRel + "/")) {
+            return normalized.slice(sourceRel.length + 1);
+        }
+        return normalized;
+    });
+}
+// ── Get Current SHA ───────────────────────────────────────────────────
+/**
+ * Returns the current HEAD commit SHA.
+ *
+ * @param sourceRoot - Absolute path to a directory within the git repo.
+ * @returns The full commit SHA string.
+ * @throws If git is not available or the directory is not in a git repo.
+ */
+export function getCurrentSHA(sourceRoot) {
+    return execSync("git rev-parse HEAD", {
+        cwd: resolve(sourceRoot),
+        encoding: "utf-8",
+        timeout: 5_000,
+    }).trim();
+}
+// ── Detect Changed Doc Files ──────────────────────────────────────────
+/**
+ * Determines which doc files were created or modified during this Hem run.
+ *
+ * Uses `git status --porcelain` on the destination directory to find
+ * untracked (new) and modified files. This captures changes made by
+ * doc agents, post-processing agents, and structural file writes.
+ *
+ * @param destinationPath - Absolute path to the docs directory.
+ * @returns Array of relative paths of new/modified `.md` files.
+ */
+export function detectChangedDocs(destinationPath) {
+    const absoluteDest = resolve(destinationPath);
+    let output;
+    try {
+        output = execSync("git status --porcelain .", {
+            cwd: absoluteDest,
+            encoding: "utf-8",
+            timeout: 10_000,
+        });
+    }
+    catch {
+        // Not a git repo or git not available — return empty
+        return [];
+    }
+    const structural = new Set(["index.md", "architecture.md", "changelog.md"]);
+    return output
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => {
+        // git status --porcelain format: "XY <path>" or "XY <path> -> <path>"
+        // We want the path portion, which starts at index 3.
+        const pathPart = line.slice(3).trim();
+        // Handle renames: "old -> new"
+        const arrowIdx = pathPart.indexOf(" -> ");
+        return arrowIdx >= 0 ? pathPart.slice(arrowIdx + 4) : pathPart;
+    })
+        .filter((p) => p.endsWith(".md") && !structural.has(p));
+}
+// ── Write Changelog Entry ─────────────────────────────────────────────
+/**
+ * Writes (or appends to) the changelog file with a new entry.
+ *
+ * Entries are prepended after the `# Changelog` heading so the most
+ * recent entry is always first. If the file doesn't exist, it is created
+ * with the heading.
+ *
+ * ### Entry format
+ *
+ * ```markdown
+ * ## 2026-02-21T15:30:00.000Z
+ * <!-- hem-sha: abc1234 -->
+ * - Updated: features/auth.md
+ * - Created: layers/database.md
+ * ```
+ *
+ * For initial runs:
+ * ```markdown
+ * ## 2026-02-21T15:30:00.000Z
+ * <!-- hem-sha: abc1234 -->
+ * - Initial documentation generation
+ * ```
+ *
+ * @param destinationPath - Absolute path to the docs directory.
+ * @param commitSHA       - The HEAD commit SHA at the time of this run.
+ * @param docPaths        - Relative paths of docs that were created/updated.
+ * @param isInitial       - Whether this is the first Hem run (no prior changelog).
+ */
+export async function writeChangelogEntry(destinationPath, commitSHA, docPaths, isInitial) {
+    const absoluteDest = resolve(destinationPath);
+    const changelogPath = join(absoluteDest, "changelog.md");
+    const timestamp = new Date().toISOString();
+    // Build the new entry
+    const entryLines = [
+        `## ${timestamp}`,
+        `<!-- hem-sha: ${commitSHA} -->`,
+    ];
+    if (isInitial) {
+        entryLines.push("- Initial documentation generation");
+    }
+    else {
+        for (const docPath of docPaths.sort()) {
+            entryLines.push(`- ${docPath}`);
+        }
+        if (docPaths.length === 0) {
+            entryLines.push("- No documentation changes");
+        }
+    }
+    const entry = entryLines.join("\n");
+    // Read existing content (or start fresh)
+    let existing = "";
+    try {
+        existing = await readFile(changelogPath, "utf-8");
+    }
+    catch {
+        // File doesn't exist — will be created
+    }
+    let newContent;
+    if (existing.length === 0) {
+        // Brand new file
+        newContent = `# Changelog\n\n${entry}\n`;
+    }
+    else {
+        // Prepend after the "# Changelog" heading line
+        const headingEnd = existing.indexOf("\n");
+        if (headingEnd >= 0) {
+            const heading = existing.slice(0, headingEnd);
+            const rest = existing.slice(headingEnd + 1);
+            newContent = `${heading}\n\n${entry}\n${rest}`;
+        }
+        else {
+            // File has content but no newline (unusual) — just prepend
+            newContent = `# Changelog\n\n${entry}\n`;
+        }
+    }
+    await mkdir(absoluteDest, { recursive: true });
+    await writeFile(changelogPath, newContent, "utf-8");
+}

package/dist/decision-queue.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Decision queue for Hem's parallel organization pass.
+ *
+ * Solves the race condition where the arbiter issues a MERGE and a DELETE
+ * for the same source file simultaneously.  The MERGE must complete (worker
+ * reads source → writes merged target) before the DELETE removes the source.
+ *
+ * ## How it works
+ *
+ * 1. **MERGE src INTO dst** — relayed immediately.  The queue records that
+ *    `src` has a pending read (the merge worker needs to read it).
+ *    A filesystem watcher on `dst` waits for the merged file to appear.
+ *
+ * 2. **DELETE filepath** — if `filepath` has a pending MERGE read, the
+ *    DELETE is queued.  Otherwise it's relayed immediately.
+ *
+ * 3. **UPDATE-LINKS / free-form** — always relayed immediately (graceful
+ *    degradation for unparsed decisions).
+ *
+ * ## Release triggers
+ *
+ * - **Filesystem watcher** (`fs.watch`) detects when the merge target file
+ *   is written, releasing queued DELETEs for the corresponding source.
+ * - **Worker completion** — when a worker's `promptAndWait` resolves, any
+ *   decisions still blocked on that worker's actions are released.
+ * - **Timeout** — queued decisions are released after a configurable
+ *   deadline (default 60 s) to prevent permanent blocking.
+ *
+ * The watcher uses `node:fs` callback-based `watch()` (not the async
+ * iterator from `node:fs/promises`) so we can `.close()` it cleanly.
+ */
+/** Default timeout (ms) after which a queued decision is released regardless. */
+export declare const QUEUE_TIMEOUT_MS = 60000;
+/**
+ * Parsed DECISION variants.
+ *
+ * - `merge`        — MERGE <src> INTO <dst>
+ * - `delete`       — DELETE <filepath>
+ * - `update-links` — UPDATE-LINKS <filepath>
+ * - `freeform`     — anything else addressed to @org-worker-N
+ */
+export type DecisionAction = {
+    kind: "merge";
+    worker: string;
+    src: string;
+    dst: string;
+} | {
+    kind: "delete";
+    worker: string;
+    filePath: string;
+} | {
+    kind: "update-links";
+    worker: string;
+    filePath: string;
+} | {
+    kind: "freeform";
+    worker: string;
+};
+/**
+ * Parse a DECISION message into a structured action.
+ * Returns `undefined` if the message is not a DECISION.
+ *
+ * NOTE: `@all-workers` decisions intentionally return `undefined` here
+ * because the regex only matches `@org-worker-\d+`. This is correct —
+ * `@all-workers` decisions are broadcast to all workers by the SSE relay
+ * routing logic and do not need file-based sequencing via DecisionQueue.
+ */
+export declare function parseDecision(message: string): DecisionAction | undefined;
+/** A DELETE decision waiting for a MERGE to complete. */
+export interface QueuedDecision {
+    /** Relay target (worker session). */
+    target: {
+        id: string;
+        label: string;
+    };
+    /** Full relay text to send when released. */
+    relayText: string;
+    /** Always "DELETE" — only DELETEs are queued. */
+    action: "DELETE";
+    /** The file this DELETE operates on (the merge source). */
+    filePath: string;
+    /** The merge target file we're waiting to see written. */
+    blockedBy: string;
+    /** Timestamp (ms) when the decision was queued. */
+    queuedAt: number;
+    /** Timeout handle — cleared when the decision is released. */
+    timer: ReturnType<typeof setTimeout>;
+}
+/**
+ * Callback that the queue invokes to relay a decision to a worker.
+ * The caller provides the actual `promptAsync` call.
+ */
+export type RelayFn = (target: {
+    id: string;
+    label: string;
+}, relayText: string) => Promise<void>;
+/**
+ * Filesystem-watched decision queue.
+ *
+ * Instantiated once per `runParallel()` invocation.  Call `start()` before
+ * the SSE relay loop and `stop()` in the `finally` block.
+ */
+export declare class DecisionQueue {
+    /** Files that have a pending MERGE read (source → merge-target). */
+    private pendingReads;
+    /** Queued DELETE decisions blocked on a pending MERGE. */
+    private queue;
+    /** The filesystem watcher (recursive), or null if not started. */
+    private watcher;
+    /** Absolute path to the documentation destination directory. */
+    private readonly destPath;
+    /** Timeout in ms for queued decisions. */
+    private readonly timeoutMs;
+    /** Relay callback provided by the caller. */
+    private readonly relay;
+    /** Optional verbose logger. */
+    private readonly verbose?;
+    constructor(opts: {
+        destPath: string;
+        relay: RelayFn;
+        timeoutMs?: number;
+        verbose?: (msg: string) => void;
+    });
+    /**
+     * Start the filesystem watcher on the destination directory.
+     * Must be called before processing any decisions.
+     */
+    start(): void;
+    /**
+     * Stop the filesystem watcher and release all queued decisions.
+     * Call in the `finally` block of `runParallel()`.
+     */
+    stop(): void;
+    /**
+     * Process a parsed DECISION and either relay it immediately or queue it.
+     *
+     * @param action    - Parsed decision action.
+     * @param target    - The worker session to relay to.
+     * @param relayText - Full relay text string.
+     */
+    handleDecision(action: DecisionAction, target: {
+        id: string;
+        label: string;
+    }, relayText: string): Promise<void>;
+    /**
+     * Called when a worker completes.  Releases any queued decisions that
+     * were blocked on actions by that worker (identified by label match
+     * in the target).
+     */
+    releaseForWorker(workerLabel: string): void;
+    /**
+     * Returns the number of currently queued (blocked) decisions.
+     */
+    get pendingCount(): number;
+    /**
+     * Returns a snapshot of pending reads (source → merge-target).
+     * Useful for testing.
+     */
+    get pendingReadSnapshot(): ReadonlyMap<string, string>;
+    /** Enqueue a blocked DELETE decision. */
+    private enqueue;
+    /**
+     * Release a single queued decision — relay it and remove from queue.
+     */
+    private release;
+    /** Release all queued decisions (used during stop/cleanup). */
+    private releaseAll;
+    /**
+     * Filesystem watcher callback.  When a file in the destination directory
+     * changes, check if it matches a merge target and release blocked DELETEs.
+     */
+    private onFileChange;
+}