chapterhouse 0.1.1 → 0.2.0

package/dist/squad/discovery.test.js

@@ -90,4 +90,65 @@ test("invalidateProjectSquad marks agents stale — next loadProjectSquad re-res
     // Both should have agents (content integrity survives invalidation + re-resolve)
     assert.ok(after && typeof after === "object" && "agents" in after, "re-resolved context should include agents");
 });
+// ---------------------------------------------------------------------------
+// S5-02: agent count from filesystem is always authoritative
+// These tests guard the fix: GET /api/projects must count agents from disk,
+// not from the SQLite squad_agents cache (which is never populated on a fresh
+// registration, causing the badge to show 0).
+// ---------------------------------------------------------------------------
+test("S5-02: resolveProjectSquad counts 0 agents for an empty agents dir", async () => {
+    const m = await loadDiscovery();
+    const dir = join(repoRoot, ".test-work", `s502-empty-${process.pid}`);
+    mkdirSync(join(dir, ".squad", "agents"), { recursive: true });
+    try {
+        const result = await m.resolveProjectSquad(dir);
+        assert.ok(result !== null, "should return context even with no agents");
+        assert.equal(result.agents.length, 0, "empty agents dir → 0 agents");
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("S5-02: resolveProjectSquad counts N agents matching charter-bearing subdirs", async () => {
+    const m = await loadDiscovery();
+    const dir = join(repoRoot, ".test-work", `s502-n-agents-${process.pid}`);
+    // Create 3 agents (with charter.md) and 1 directory without charter.md
+    for (const slug of ["alpha", "beta", "gamma"]) {
+        mkdirSync(join(dir, ".squad", "agents", slug), { recursive: true });
+        const { writeFileSync } = await import("node:fs");
+        writeFileSync(join(dir, ".squad", "agents", slug, "charter.md"), `# ${slug}\n\n**Role:** Specialist\n`);
+    }
+    mkdirSync(join(dir, ".squad", "agents", "no-charter"), { recursive: true }); // no charter.md
+    try {
+        const result = await m.resolveProjectSquad(dir);
+        assert.ok(result !== null, "should return context");
+        assert.equal(result.agents.length, 3, "only dirs with charter.md count as agents");
+        const slugs = result.agents.map((a) => a.slug).sort();
+        assert.deepEqual(slugs, ["alpha", "beta", "gamma"]);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("S5-02: resolveProjectSquad re-reads filesystem after agent added (no stale count)", async () => {
+    const m = await loadDiscovery();
+    const dir = join(repoRoot, ".test-work", `s502-refresh-${process.pid}`);
+    const { writeFileSync } = await import("node:fs");
+    // Start with 1 agent
+    mkdirSync(join(dir, ".squad", "agents", "first"), { recursive: true });
+    writeFileSync(join(dir, ".squad", "agents", "first", "charter.md"), "# first\n\n**Role:** Scout\n");
+    try {
+        const before = await m.resolveProjectSquad(dir);
+        assert.equal(before.agents.length, 1, "before: 1 agent on disk");
+        // Add a second agent to disk
+        mkdirSync(join(dir, ".squad", "agents", "second"), { recursive: true });
+        writeFileSync(join(dir, ".squad", "agents", "second", "charter.md"), "# second\n\n**Role:** Recon\n");
+        // resolveProjectSquad always reads from disk (no TTL — direct filesystem read)
+        const after = await m.resolveProjectSquad(dir);
+        assert.equal(after.agents.length, 2, "after adding agent to disk: 2 agents");
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
 //# sourceMappingURL=discovery.test.js.map

package/dist/store/db.js

@@ -146,6 +146,17 @@ export function getDb() {
         if (!taskCols.some((c) => c.name === 'session_key')) {
             db.exec(`ALTER TABLE agent_tasks ADD COLUMN session_key TEXT NOT NULL DEFAULT 'default'`);
         }
+        // Migrate: add source column to agent_tasks ('adhoc' | 'squad') if not present
+        if (!taskCols.some((c) => c.name === 'source')) {
+            db.exec(`ALTER TABLE agent_tasks ADD COLUMN source TEXT NOT NULL DEFAULT 'adhoc'`);
+        }
+        // Migrate: add last_used_at column to project_squads (epoch ms, nullable)
+        const projectCols = db.prepare(`PRAGMA table_info(project_squads)`).all();
+        if (!projectCols.some((c) => c.name === 'last_used_at')) {
+            db.exec(`ALTER TABLE project_squads ADD COLUMN last_used_at INTEGER`);
+            // Backfill from loaded_at so sidebar is not empty for existing projects
+            db.exec(`UPDATE project_squads SET last_used_at = CAST((julianday(loaded_at) - 2440587.5) * 86400000 AS INTEGER) WHERE last_used_at IS NULL`);
+        }
         // Prune conversation log at startup — keep more history for better recovery
         db.prepare(`DELETE FROM conversation_log WHERE id NOT IN (SELECT id FROM conversation_log ORDER BY id DESC LIMIT 1000)`).run();
         // Set up FTS5 for memory search (graceful fallback if not available)
@@ -276,11 +287,42 @@ export function getRecentConversation(limit, sessionKey) {
         return `${tag}: ${content}`;
     }).join("\n\n");
 }
+const MAX_SESSION_MESSAGES_LIMIT = 500;
+const DEFAULT_SESSION_MESSAGES_LIMIT = 100;
+/**
+ * Return conversation_log rows for a specific session as structured JSON,
+ * suitable for seeding the frontend Zustand store on mount.
+ *
+ * Unlike `getRecentConversation()`, this returns structured objects (not a
+ * formatted string) and omits system messages (role = 'system') because the
+ * UI only renders user/assistant turns.
+ */
+export function getSessionMessages(sessionKey, limit) {
+    const db = getDb();
+    const effectiveLimit = Math.min(limit ?? DEFAULT_SESSION_MESSAGES_LIMIT, MAX_SESSION_MESSAGES_LIMIT);
+    const rows = db
+        .prepare(`SELECT role, content, ts FROM conversation_log
+       WHERE session_key = ? AND role IN ('user', 'assistant')
+       ORDER BY id DESC LIMIT ?`)
+        .all(sessionKey, effectiveLimit);
+    // Reverse so oldest is first (chronological order for the UI)
+    rows.reverse();
+    return rows.map((r) => ({
+        role: r.role,
+        content: r.content,
+        ts: r.ts,
+    }));
+}
 // ---------------------------------------------------------------------------
 // SQLite memory functions removed — wiki is the single source of truth.
 // The memories table and FTS5 index are preserved in the schema for safety
 // (existing data is not deleted), but no code reads or writes to them.
 // ---------------------------------------------------------------------------
+export function bumpProjectLastUsed(projectRoot) {
+    getDb()
+        .prepare(`UPDATE project_squads SET last_used_at = ? WHERE project_root = ?`)
+        .run(Date.now(), projectRoot);
+}
 export function closeDb() {
     if (db) {
         db.close();

package/dist/store/db.test.js

@@ -123,4 +123,92 @@ test("getDb prunes oversized conversation logs on startup and during inserts", a
         dbModule.closeDb();
     }
 });
+test("getSessionMessages returns empty array for unknown session", async () => {
+    const dbModule = await loadDbModule();
+    try {
+        dbModule.getDb();
+        const result = dbModule.getSessionMessages("nonexistent-session");
+        assert.deepEqual(result, []);
+    }
+    finally {
+        dbModule.closeDb();
+    }
+});
+test("getSessionMessages returns structured messages in chronological order, excludes system rows, respects limit", async () => {
+    const dbModule = await loadDbModule();
+    try {
+        dbModule.getDb();
+        dbModule.logConversation("user", "hello", "web", "test-session");
+        dbModule.logConversation("assistant", "hi there", "web", "test-session");
+        dbModule.logConversation("system", "system noise", "worker", "test-session");
+        dbModule.logConversation("user", "second message", "web", "test-session");
+        dbModule.logConversation("user", "from other session", "web", "other-session");
+        const all = dbModule.getSessionMessages("test-session");
+        assert.equal(all.length, 3, "3 user/assistant rows, system excluded");
+        assert.equal(all[0].role, "user");
+        assert.equal(all[0].content, "hello");
+        assert.equal(all[1].role, "assistant");
+        assert.equal(all[1].content, "hi there");
+        assert.equal(all[2].role, "user");
+        assert.equal(all[2].content, "second message");
+        // Limit clamping
+        const limited = dbModule.getSessionMessages("test-session", 2);
+        assert.equal(limited.length, 2, "limit=2 returns 2 most recent rows");
+        // After reversal, these should be the 2 most-recent (assistant + second user)
+        assert.equal(limited[0].content, "hi there");
+        assert.equal(limited[1].content, "second message");
+        // Other session not leaked
+        const other = dbModule.getSessionMessages("other-session");
+        assert.equal(other.length, 1);
+        assert.equal(other[0].content, "from other session");
+    }
+    finally {
+        dbModule.closeDb();
+    }
+});
+// ---------------------------------------------------------------------------
+// #26 — bumpProjectLastUsed
+// ---------------------------------------------------------------------------
+test("migration adds last_used_at column to project_squads when absent", async () => {
+    const dbModule = await loadDbModule();
+    try {
+        const db = dbModule.getDb();
+        const cols = db.prepare(`PRAGMA table_info(project_squads)`).all();
+        assert.equal(cols.some((c) => c.name === "last_used_at"), true, "last_used_at column should exist after migration");
+    }
+    finally {
+        dbModule.closeDb();
+    }
+});
+test("bumpProjectLastUsed updates last_used_at for the given project_root", async () => {
+    const dbModule = await loadDbModule();
+    try {
+        const db = dbModule.getDb();
+        db.prepare(`INSERT INTO project_squads (project_root, squad_dir, team_dir, mode, registered) VALUES (?, ?, ?, 'local', 1)`).run("/home/user/test-proj", "/home/user/test-proj/.squad", "/home/user/test-proj/.squad");
+        const before = db
+            .prepare(`SELECT last_used_at FROM project_squads WHERE project_root = ?`)
+            .get("/home/user/test-proj");
+        const beforeTs = before.last_used_at ?? 0;
+        await new Promise((r) => setTimeout(r, 5));
+        dbModule.bumpProjectLastUsed("/home/user/test-proj");
+        const after = db
+            .prepare(`SELECT last_used_at FROM project_squads WHERE project_root = ?`)
+            .get("/home/user/test-proj");
+        assert.ok(after.last_used_at !== null, "last_used_at should not be null after bump");
+        assert.ok(after.last_used_at > beforeTs, "last_used_at should advance after bump");
+    }
+    finally {
+        dbModule.closeDb();
+    }
+});
+test("bumpProjectLastUsed is a no-op for unknown project_root (no throw)", async () => {
+    const dbModule = await loadDbModule();
+    try {
+        dbModule.getDb();
+        dbModule.bumpProjectLastUsed("/does/not/exist");
+    }
+    finally {
+        dbModule.closeDb();
+    }
+});
 //# sourceMappingURL=db.test.js.map

package/dist/update.js

@@ -1,5 +1,5 @@
 import { readFileSync, existsSync } from "fs";
-import { join, dirname } from "path";
+import { join, dirname, basename } from "path";
 import { fileURLToPath } from "url";
 import { execSync } from "child_process";
 import { homedir } from "os";
@@ -7,6 +7,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const GITHUB_INSTALL_SOURCE = "bketelsen/chapterhouse";
 const GITHUB_REPO_URL = "https://github.com/bketelsen/chapterhouse.git";
 const GITHUB_TAGS_API_URL = "https://api.github.com/repos/bketelsen/chapterhouse/tags?per_page=100";
+const NPM_REGISTRY_URL = "https://registry.npmjs.org/chapterhouse";
+const NPM_PACKAGE_NAME = "chapterhouse";
 const SOURCE_DIR = join(homedir(), ".chapterhouse", "src");
 function getLocalVersion() {
     try {
@@ -20,15 +22,113 @@ function getLocalVersion() {
 function normalizeVersion(v) {
     return v.startsWith("v") ? v.slice(1) : v;
 }
+function parseVersionTuple(v) {
+    const parts = normalizeVersion(v).split(".").map(Number);
+    return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+}
+function compareVersions(a, b) {
+    const [aMaj, aMin, aPat] = parseVersionTuple(a);
+    const [bMaj, bMin, bPat] = parseVersionTuple(b);
+    if (aMaj !== bMaj)
+        return aMaj - bMaj;
+    if (aMin !== bMin)
+        return aMin - bMin;
+    return aPat - bPat;
+}
+/**
+ * Determine how chapterhouse was installed.
+ *
+ * Detection order:
+ * 1. git/legacy  — pkgDir is under SOURCE_DIR (~/.chapterhouse/src)
+ * 2. dev         — pkgDir contains a .git directory (working tree, not SOURCE_DIR)
+ * 3. registry    — parent of pkgDir is named "node_modules"
+ * 4. registry    — npm ls -g confirms it
+ * 5. unknown     — default
+ */
+export function detectInstallSource() {
+    const pkgDir = join(__dirname, "..");
+    if (pkgDir.startsWith(SOURCE_DIR)) {
+        return "git";
+    }
+    if (existsSync(join(pkgDir, ".git"))) {
+        return "dev";
+    }
+    if (basename(join(pkgDir, "..")) === "node_modules") {
+        return "registry";
+    }
+    try {
+        const out = execSync("npm ls -g chapterhouse --json 2>/dev/null", {
+            encoding: "utf-8",
+            timeout: 10_000,
+        });
+        const data = JSON.parse(out);
+        if (data?.dependencies?.chapterhouse) {
+            return "registry";
+        }
+    }
+    catch {
+        // ignore — npm ls failure is not fatal
+    }
+    return "unknown";
+}
+/** Check that Node ≥ 24 and npm ≥ 11.5.1 are available. */
+export function checkPreconditions() {
+    const nodeVer = process.version.replace("v", "");
+    let npmVer = "0.0.0";
+    try {
+        npmVer = execSync("npm --version", { encoding: "utf-8", timeout: 5_000 }).trim();
+    }
+    catch {
+        // leave npmVer as 0.0.0 so the check fails gracefully
+    }
+    const [nodeMaj] = parseVersionTuple(nodeVer);
+    const npmOk = compareVersions(npmVer, "11.5.1") >= 0;
+    if (nodeMaj < 24 || !npmOk) {
+        return {
+            ok: false,
+            nodeVersion: nodeVer,
+            npmVersion: npmVer,
+            message: `Node 24+ / npm 11.5.1+ recommended for chapterhouse updates (current Node: ${nodeVer}, npm: ${npmVer}). Update Node and try again.`,
+        };
+    }
+    return { ok: true, nodeVersion: nodeVer, npmVersion: npmVer };
+}
+// ─── Install command builders ──────────────────────────────────────────────
+/** Returns the legacy GitHub install source (kept for deprecation messages). */
 export function getInstallSource() {
     return GITHUB_INSTALL_SOURCE;
 }
+/** Build the npm registry install command (default path post-S5-03). */
 export function buildInstallCommand(ref) {
+    const suffix = ref?.trim() ? `@${ref.trim()}` : "@latest";
+    return `npm install -g ${NPM_PACKAGE_NAME}${suffix}`;
+}
+/** Build the legacy git-based install command. Used only in deprecation messages. */
+export function buildLegacyGitInstallCommand(ref) {
     const suffix = ref?.trim() ? `#${ref.trim()}` : "";
-    return `npm install -g ${getInstallSource()}${suffix}`;
+    return `npm install -g ${GITHUB_INSTALL_SOURCE}${suffix}`;
 }
-/** Fetch the latest tagged release from GitHub. */
-export async function getLatestVersion() {
+/** Fetch the latest version from the npm registry (primary source). */
+async function getLatestVersionFromNpm() {
+    try {
+        const response = await fetch(NPM_REGISTRY_URL, {
+            headers: {
+                Accept: "application/json",
+                "User-Agent": "chapterhouse-updater",
+            },
+        });
+        if (!response.ok)
+            return { version: null, reachable: false };
+        const data = (await response.json());
+        const latest = (data?.["dist-tags"] ?? {})?.latest ?? null;
+        return { version: latest ? normalizeVersion(latest) : null, reachable: true };
+    }
+    catch {
+        return { version: null, reachable: false };
+    }
+}
+/** Fallback: fetch the latest tagged release from GitHub. */
+async function getLatestVersionFromGitHub() {
     try {
         const response = await fetch(GITHUB_TAGS_API_URL, {
             headers: {
@@ -38,40 +138,32 @@ export async function getLatestVersion() {
         });
         if (!response.ok)
             return { version: null, reachable: false };
-        const tags = await response.json();
+        const tags = (await response.json());
         const versions = tags
             .map((tag) => tag.name?.trim() || "")
             .filter((name) => /^v?\d+\.\d+\.\d+$/.test(name))
             .map(normalizeVersion);
         if (versions.length === 0)
             return { version: null, reachable: true };
-        const latest = versions.sort((a, b) => {
-            const [aMaj, aMin, aPat] = a.split(".").map(Number);
-            const [bMaj, bMin, bPat] = b.split(".").map(Number);
-            if (aMaj !== bMaj)
-                return bMaj - aMaj;
-            if (aMin !== bMin)
-                return bMin - aMin;
-            return bPat - aPat;
-        })[0] || null;
+        const latest = versions.sort((a, b) => compareVersions(b, a))[0] ?? null;
         return { version: latest, reachable: true };
     }
     catch {
         return { version: null, reachable: false };
     }
 }
+/** Get the latest version: npm registry first, GitHub tags as fallback. */
+export async function getLatestVersion() {
+    const npmResult = await getLatestVersionFromNpm();
+    if (npmResult.reachable)
+        return npmResult;
+    return getLatestVersionFromGitHub();
+}
 /** Compare two semver strings. Returns true if remote is newer. */
 function isNewer(local, remote) {
-    const parse = (v) => normalizeVersion(v).split(".").map(Number);
-    const [lMaj, lMin, lPat] = parse(local);
-    const [rMaj, rMin, rPat] = parse(remote);
-    if (rMaj !== lMaj)
-        return rMaj > lMaj;
-    if (rMin !== lMin)
-        return rMin > lMin;
-    return rPat > lPat;
-}
-/** Check whether a newer tagged release is available on GitHub. */
+    return compareVersions(remote, local) > 0;
+}
+/** Check whether a newer version is available (npm registry first, GitHub fallback). */
 export async function checkForUpdate() {
     const current = getLocalVersion();
     const result = await getLatestVersion();
@@ -82,12 +174,16 @@ export async function checkForUpdate() {
         checkSucceeded: result.reachable,
     };
 }
-/** Run a git pull + rebuild to update the local installation. */
-export async function performUpdate(ref) {
+// ─── Update execution ──────────────────────────────────────────────────────
+/** Run a git pull + rebuild for legacy (~/.chapterhouse/src) installs. */
+async function performLegacyGitUpdate(ref) {
     try {
-        const opts = { encoding: "utf-8", timeout: 120_000, stdio: ["ignore", "pipe", "pipe"] };
+        const opts = {
+            encoding: "utf-8",
+            timeout: 120_000,
+            stdio: ["ignore", "pipe", "pipe"],
+        };
         if (!existsSync(join(SOURCE_DIR, ".git"))) {
-            // Fresh install — clone the repo
             execSync(`git clone --depth 1 ${GITHUB_REPO_URL} "${SOURCE_DIR}"`, opts);
         }
         else {
@@ -109,4 +205,42 @@ export async function performUpdate(ref) {
         return { ok: false, output: msg };
     }
 }
+/** Run an npm registry update (post-S5-03 default path). */
+async function performRegistryUpdate(ref) {
+    try {
+        const cmd = buildInstallCommand(ref);
+        const output = execSync(cmd, {
+            encoding: "utf-8",
+            timeout: 120_000,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return { ok: true, output: output.trim() };
+    }
+    catch (err) {
+        const msg = err.stderr?.trim() || err.message || "Unknown error";
+        return { ok: false, output: msg };
+    }
+}
+/**
+ * Perform the update based on the detected install source.
+ *
+ * - registry / unknown → npm install -g chapterhouse[@<ref>]
+ * - git/legacy         → git pull + build + link (with deprecation warning printed)
+ * - dev                → no-op with friendly message
+ */
+export async function performUpdate(ref) {
+    const source = detectInstallSource();
+    if (source === "dev") {
+        return {
+            ok: true,
+            output: "Dev mode — use git pull manually.",
+            source,
+        };
+    }
+    if (source === "git") {
+        return { ...(await performLegacyGitUpdate(ref)), source };
+    }
+    // registry or unknown — default to npm registry path
+    return { ...(await performRegistryUpdate(ref)), source };
+}
 //# sourceMappingURL=update.js.map

package/dist/update.test.js

@@ -1,25 +1,104 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-test("uses the GitHub repo for direct installs", async () => {
+// ─── Legacy compatibility ──────────────────────────────────────────────────
+test("getInstallSource returns the GitHub repo for legacy/deprecation messages", async () => {
     const updateModule = await import("./update.js");
     assert.equal(typeof updateModule.getInstallSource, "function", "getInstallSource should be exported");
     const source = updateModule.getInstallSource();
     assert.equal(source, "bketelsen/chapterhouse");
 });
-test("buildInstallCommand pins to a Git tag when provided", async () => {
+// ─── buildInstallCommand (npm registry path) ───────────────────────────────
+test("buildInstallCommand defaults to npm registry @latest", async () => {
     const updateModule = await import("./update.js");
     assert.equal(typeof updateModule.buildInstallCommand, "function", "buildInstallCommand should be exported");
+    const command = updateModule.buildInstallCommand(null);
+    assert.equal(command, "npm install -g chapterhouse@latest");
+});
+test("buildInstallCommand pins to a specific version when ref provided", async () => {
+    const updateModule = await import("./update.js");
+    const command = updateModule.buildInstallCommand("0.1.5");
+    assert.equal(command, "npm install -g chapterhouse@0.1.5");
+});
+test("buildInstallCommand handles v-prefixed ref", async () => {
+    const updateModule = await import("./update.js");
     const command = updateModule.buildInstallCommand("v2.0.0");
+    assert.equal(command, "npm install -g chapterhouse@v2.0.0");
+});
+test("buildInstallCommand uses @latest when ref is empty string", async () => {
+    const updateModule = await import("./update.js");
+    const command = updateModule.buildInstallCommand("");
+    assert.equal(command, "npm install -g chapterhouse@latest");
+});
+// ─── buildLegacyGitInstallCommand ─────────────────────────────────────────
+test("buildLegacyGitInstallCommand pins to a Git tag when provided", async () => {
+    const updateModule = await import("./update.js");
+    assert.equal(typeof updateModule.buildLegacyGitInstallCommand, "function");
+    const command = updateModule.buildLegacyGitInstallCommand("v2.0.0");
     assert.equal(command, "npm install -g bketelsen/chapterhouse#v2.0.0");
 });
-test("buildInstallCommand falls back to default branch when no tag provided", async () => {
+test("buildLegacyGitInstallCommand falls back to default branch when no tag provided", async () => {
     const updateModule = await import("./update.js");
-    assert.equal(typeof updateModule.buildInstallCommand, "function", "buildInstallCommand should be exported");
-    const command = updateModule.buildInstallCommand(null);
+    const command = updateModule.buildLegacyGitInstallCommand(null);
     assert.equal(command, "npm install -g bketelsen/chapterhouse");
 });
+// ─── detectInstallSource ──────────────────────────────────────────────────
+test("detectInstallSource returns a valid InstallSource value", async () => {
+    const updateModule = await import("./update.js");
+    assert.equal(typeof updateModule.detectInstallSource, "function", "detectInstallSource should be exported");
+    const source = updateModule.detectInstallSource();
+    const valid = ["registry", "git", "dev", "unknown"];
+    assert.ok(valid.includes(source), `Expected one of ${valid.join("|")}, got: ${source}`);
+});
+// During test runs the package lives in a git working tree → should be "dev"
+test("detectInstallSource detects dev mode when running from source checkout", async () => {
+    const { detectInstallSource } = await import("./update.js");
+    const { existsSync } = await import("fs");
+    const { join, dirname } = await import("path");
+    const { fileURLToPath } = await import("url");
+    const pkgDir = join(dirname(fileURLToPath(import.meta.url)), "..");
+    // Only assert dev if there really is a .git in pkgDir (guards CI environments)
+    if (existsSync(join(pkgDir, ".git"))) {
+        assert.equal(detectInstallSource(), "dev");
+    }
+});
+// ─── checkPreconditions ───────────────────────────────────────────────────
+test("checkPreconditions is exported as a function", async () => {
+    const updateModule = await import("./update.js");
+    assert.equal(typeof updateModule.checkPreconditions, "function", "checkPreconditions should be exported");
+});
+test("checkPreconditions returns ok:true for Node 24+", async () => {
+    const { checkPreconditions } = await import("./update.js");
+    // The test runner must be Node 24+ per the project requirement — so this asserts both the shape and the pass case.
+    const result = checkPreconditions();
+    assert.equal(typeof result.ok, "boolean");
+    assert.equal(typeof result.nodeVersion, "string");
+    assert.equal(typeof result.npmVersion, "string");
+    const [major] = result.nodeVersion.split(".").map(Number);
+    if (major >= 24) {
+        assert.equal(result.ok, true, "Should pass on Node 24+");
+        assert.equal(result.message, undefined);
+    }
+});
+test("checkPreconditions message contains node and npm versions on failure", async () => {
+    // We construct the precondition result shape manually to test the message template
+    const fakeNode = "22.0.0";
+    const fakeNpm = "10.0.0";
+    const expected = `Node 24+ / npm 11.5.1+ recommended for chapterhouse updates (current Node: ${fakeNode}, npm: ${fakeNpm}). Update Node and try again.`;
+    // Verify the message format by reconstructing it (mirrors the implementation)
+    const msg = `Node 24+ / npm 11.5.1+ recommended for chapterhouse updates (current Node: ${fakeNode}, npm: ${fakeNpm}). Update Node and try again.`;
+    assert.equal(msg, expected);
+});
+// ─── performUpdate ────────────────────────────────────────────────────────
 test("performUpdate is exported as async function", async () => {
     const updateModule = await import("./update.js");
     assert.equal(typeof updateModule.performUpdate, "function", "performUpdate should be exported");
 });
+test("performUpdate result includes source field", async () => {
+    // We cannot run the real network/exec path in unit tests.
+    // Verify only the shape contract by importing and checking the return type annotation exists.
+    const updateModule = await import("./update.js");
+    const fn = updateModule.performUpdate;
+    assert.equal(typeof fn, "function");
+    // Shape is validated via TypeScript at build time; this test confirms the export is present.
+});
 //# sourceMappingURL=update.test.js.map

package/dist/util/logger.js

@@ -0,0 +1,41 @@
+// ---------------------------------------------------------------------------
+// Structured logger — pino singleton
+//
+// Configuration:
+//   LOG_LEVEL env var controls verbosity. Default: "info".
+//   Valid levels: trace | debug | info | warn | error | fatal | silent
+//
+// Usage:
+//   import { logger } from "../util/logger.js";
+//   logger.info("Server started");
+//   logger.debug({ direction: "in", source: "web", text: msg }, "chat");
+//   logger.error({ err }, "Something blew up");
+//
+// Chat message content should always be logged at debug or trace — never info.
+// System events (startup, sessions, agent dispatch, DB) go at info.
+// ---------------------------------------------------------------------------
+import pino from "pino";
+const VALID_LEVELS = new Set(["trace", "debug", "info", "warn", "error", "fatal", "silent"]);
+export function resolveLevel(envOverride) {
+    const raw = (envOverride ?? process.env.LOG_LEVEL ?? "info").toLowerCase();
+    return VALID_LEVELS.has(raw) ? raw : "info";
+}
+/** Create a fresh pino logger for the given level. Useful in tests. */
+export function createLogger(level) {
+    return pino({ level });
+}
+// In test environments (CHAPTERHOUSE_DISABLE_DOTENV=1), default to silent so
+// test output stays clean. An explicit LOG_LEVEL env var overrides this.
+const defaultLevel = process.env.CHAPTERHOUSE_DISABLE_DOTENV === "1" && !process.env.LOG_LEVEL
+    ? "silent"
+    : resolveLevel();
+export const logger = pino({
+    level: defaultLevel,
+    // Output is JSON (machine-readable). Pipe to `pino-pretty` for dev:
+    //   node ... | npx pino-pretty
+});
+/** Convenience child logger pre-tagged with a module name. */
+export function childLogger(module) {
+    return logger.child({ module });
+}
+//# sourceMappingURL=logger.js.map