@hasna/hooks 0.2.20 → 0.3.1

package/hooks/hook-fleet-catchup/src/hook.test.ts

@@ -0,0 +1,156 @@
+import { describe, test, expect } from "bun:test";
+import {
+  parseJsonList,
+  hasJsonList,
+  resolveSince,
+  formatCatchup,
+  truncate,
+  safeIdentifier,
+  safeSince,
+} from "./hook";
+
+describe("hook-fleet-catchup", () => {
+  describe("parseJsonList", () => {
+    test("parses a bare array", () => {
+      expect(parseJsonList('[1,2]')).toEqual([1, 2]);
+    });
+
+    test("unwraps named keys in order", () => {
+      expect(parseJsonList('{"blockers":[1]}', "blockers", "messages")).toEqual([1]);
+      expect(parseJsonList('{"messages":[2]}', "blockers", "messages")).toEqual([2]);
+    });
+
+    test("returns empty for garbage and null", () => {
+      expect(parseJsonList("nope")).toEqual([]);
+      expect(parseJsonList(null)).toEqual([]);
+      expect(parseJsonList('{"other":true}')).toEqual([]);
+    });
+  });
+
+  describe("hasJsonList", () => {
+    test("accepts bare arrays and configured array envelopes", () => {
+      expect(hasJsonList("[]", "notifications", "messages")).toBe(true);
+      expect(hasJsonList('{"notifications":[]}', "notifications", "messages")).toBe(true);
+      expect(hasJsonList('{"messages":[1]}', "notifications", "messages")).toBe(true);
+    });
+
+    test("rejects invalid JSON and unexpected envelopes", () => {
+      expect(hasJsonList(null, "notifications", "messages")).toBe(false);
+      expect(hasJsonList("not json", "notifications", "messages")).toBe(false);
+      expect(hasJsonList('{"other":[]}', "notifications", "messages")).toBe(false);
+    });
+  });
+
+  describe("resolveSince", () => {
+    const now = new Date("2026-07-06T12:00:00.000Z");
+
+    test("uses the stored timestamp when valid and in the past", () => {
+      expect(resolveSince(now, "2026-07-06T09:30:00.000Z")).toBe("2026-07-06T09:30:00.000Z");
+    });
+
+    test("falls back to 24h lookback when state is missing", () => {
+      expect(resolveSince(now, null)).toBe("2026-07-05T12:00:00.000Z");
+    });
+
+    test("falls back when state is garbage", () => {
+      expect(resolveSince(now, "not-a-date")).toBe("2026-07-05T12:00:00.000Z");
+    });
+
+    test("falls back when state is in the future (clock skew)", () => {
+      expect(resolveSince(now, "2027-01-01T00:00:00.000Z")).toBe("2026-07-05T12:00:00.000Z");
+    });
+  });
+
+  describe("formatCatchup", () => {
+    test("returns null when everything is empty", () => {
+      expect(formatCatchup([], [], null)).toBeNull();
+      expect(formatCatchup([], [], '{"messages":[]}')).toBeNull();
+    });
+
+    test("includes blockers section with read-duty reminder", () => {
+      const out = formatCatchup(
+        [{ from: "chief", content: "[FREEZE] hold publishes", created_at: "2026-07-06T10:00:00Z" }],
+        [],
+        null
+      );
+      expect(out).toContain("UNREAD BLOCKING MESSAGES (1)");
+      expect(out).toContain("[FREEZE] hold publishes");
+      expect(out).toContain("stop and escalate");
+    });
+
+    test("includes notifications and digest sections", () => {
+      const out = formatCatchup(
+        [],
+        [{ from: "bot", channel: "git-releases", preview: "released x@1.0.0" }],
+        JSON.stringify({ messages: [{ from: "chief", content: "[POLICY] HACP v1.1" }] })
+      );
+      expect(out).toContain("CHANNEL NOTIFICATIONS since last catchup (1)");
+      expect(out).toContain("#git-releases");
+      expect(out).toContain("ANNOUNCEMENTS digest");
+      expect(out).toContain("[POLICY] HACP v1.1");
+    });
+
+    test("skips digest section when digest JSON is invalid", () => {
+      const out = formatCatchup([{ content: "x" }], [], "garbage");
+      expect(out).toContain("UNREAD BLOCKING MESSAGES");
+      expect(out).not.toContain("ANNOUNCEMENTS digest");
+    });
+
+    test("caps listed blockers at 10", () => {
+      const blockers = Array.from({ length: 25 }, (_, i) => ({ content: `blocker-${i}` }));
+      const out = formatCatchup(blockers, [], null)!;
+      expect(out).toContain("UNREAD BLOCKING MESSAGES (25)");
+      expect(out).toContain("blocker-9");
+      expect(out).not.toContain("blocker-10");
+      expect(out.split("\n").filter((l) => l.startsWith("- ")).length).toBe(10);
+    });
+  });
+
+  describe("truncate", () => {
+    test("passes short strings through", () => {
+      expect(truncate("abc", 10)).toBe("abc");
+    });
+
+    test("truncates long strings with ellipsis", () => {
+      const out = truncate("a".repeat(50), 10);
+      expect(out.length).toBe(10);
+      expect(out.endsWith("…")).toBe(true);
+    });
+  });
+
+  describe("safeIdentifier", () => {
+    test("accepts normal agent names", () => {
+      expect(safeIdentifier("chief")).toBe("chief");
+      expect(safeIdentifier("build-hooks_01.a")).toBe("build-hooks_01.a");
+    });
+
+    test("rejects shell metacharacters", () => {
+      expect(safeIdentifier("$(rm -rf /)")).toBeNull();
+      expect(safeIdentifier("a;b")).toBeNull();
+      expect(safeIdentifier("a b")).toBeNull();
+      expect(safeIdentifier("`x`")).toBeNull();
+    });
+
+    test("rejects empty/undefined", () => {
+      expect(safeIdentifier(undefined)).toBeNull();
+      expect(safeIdentifier("")).toBeNull();
+    });
+  });
+
+  describe("safeSince", () => {
+    test("accepts relative durations", () => {
+      expect(safeSince("7d", "1d")).toBe("7d");
+      expect(safeSince("24h", "1d")).toBe("24h");
+    });
+
+    test("accepts ISO timestamps", () => {
+      expect(safeSince("2026-07-06T00:00:00Z", "1d")).toBe("2026-07-06T00:00:00Z");
+    });
+
+    test("falls back on anything else", () => {
+      expect(safeSince("; rm -rf /", "7d")).toBe("7d");
+      expect(safeSince("$(x)", "7d")).toBe("7d");
+      expect(safeSince(undefined, "7d")).toBe("7d");
+    });
+  });
+});

package/hooks/hook-fleet-catchup/src/hook.ts

@@ -0,0 +1,283 @@
+#!/usr/bin/env bun
+
+/**
+ * Claude Code Hook: fleet-catchup
+ *
+ * SessionStart hook that catches an agent up on fleet communications:
+ * - `conversations blockers -j`                     → unread blocking messages
+ * - `conversations notifications --since <last>`    → channel notifications since last catchup
+ * - `conversations digest announcements --unread --since 7d` → bounded announcements digest
+ *
+ * All reads are deterministic CLI calls against the local conversations
+ * service. Every step is fail-open: a missing CLI, timeout, or parse error
+ * skips that section and never blocks the session. Output is injected via
+ * SessionStart's `hookSpecificOutput.additionalContext`.
+ *
+ * Environment:
+ * - HOOKS_FLEET_CATCHUP_DISABLE=1   → skip entirely
+ * - HOOKS_FLEET_AGENT=<name>        → identity passed as --from
+ * - HOOKS_FLEET_TIMEOUT_MS=<n>      → per-command exec timeout (default 1500)
+ * - HOOKS_FLEET_SINCE=<duration>    → announcements digest window (default 7d)
+ */
+
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { exec } from "child_process";
+
+interface HookInput {
+  session_id: string;
+  cwd: string;
+  hook_event_name: string;
+  source?: string;
+}
+
+interface HookOutput {
+  continue: boolean;
+  hookSpecificOutput?: {
+    hookEventName: "SessionStart";
+    additionalContext: string;
+  };
+}
+
+const DEFAULT_TIMEOUT_MS = 1500;
+const DEFAULT_LOOKBACK_MS = 24 * 60 * 60 * 1000; // 24h when no last-seen state
+const STATE_DIR = join(homedir(), ".hasna", "hooks", "state");
+const LAST_SEEN_FILE = join(STATE_DIR, "fleet-catchup.last_seen");
+
+function readStdinJson(): HookInput | null {
+  try {
+    const input = readFileSync(0, "utf-8").trim();
+    if (!input) return null;
+    return JSON.parse(input);
+  } catch {
+    return null;
+  }
+}
+
+function respond(output: HookOutput): void {
+  console.log(JSON.stringify(output));
+}
+
+function timeoutMs(): number {
+  const raw = Number(process.env.HOOKS_FLEET_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TIMEOUT_MS;
+}
+
+/** Only pass through shell-safe identifier values (defense against env-borne injection). */
+export function safeIdentifier(value: string | undefined): string | null {
+  if (!value) return null;
+  return /^[A-Za-z0-9._-]{1,64}$/.test(value) ? value : null;
+}
+
+/** Only accept relative durations (7d, 24h) or ISO-ish timestamps for --since. */
+export function safeSince(value: string | undefined, fallback: string): string {
+  if (!value) return fallback;
+  if (/^[0-9]{1,4}[smhdw]$/.test(value)) return value;
+  if (/^[0-9]{4}-[0-9]{2}-[0-9]{2}[T0-9:.Z+-]*$/.test(value)) return value;
+  return fallback;
+}
+
+function fromFlag(): string {
+  const agent = safeIdentifier(process.env.HOOKS_FLEET_AGENT);
+  return agent ? ` --from ${agent}` : "";
+}
+
+/**
+ * Run a CLI command, resolving stdout or null on any failure (fail-open).
+ * Async so the three catchup reads run in parallel — worst-case session-start
+ * cost is one timeout, not the sum of three.
+ */
+function tryExec(command: string): Promise<string | null> {
+  return new Promise((resolve) => {
+    try {
+      exec(command, { encoding: "utf-8", timeout: timeoutMs() }, (err, stdout) => {
+        resolve(err ? null : (stdout ?? "").trim() || null);
+      });
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+/** Parse CLI JSON that may be an array or an object wrapping an array. */
+export function parseJsonList(raw: string | null, ...wrapperKeys: string[]): unknown[] {
+  if (!raw) return [];
+  try {
+    const data = JSON.parse(raw);
+    if (Array.isArray(data)) return data;
+    if (data && typeof data === "object") {
+      for (const key of wrapperKeys) {
+        const inner = (data as Record<string, unknown>)[key];
+        if (Array.isArray(inner)) return inner;
+      }
+    }
+    return [];
+  } catch {
+    return [];
+  }
+}
+
+/** True when raw CLI output was parseable as the expected list shape. */
+export function hasJsonList(raw: string | null, ...wrapperKeys: string[]): boolean {
+  if (!raw) return false;
+  try {
+    const data = JSON.parse(raw);
+    if (Array.isArray(data)) return true;
+    if (data && typeof data === "object") {
+      return wrapperKeys.some((key) => Array.isArray((data as Record<string, unknown>)[key]));
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/** Read the last catchup timestamp; fall back to a bounded 24h lookback. */
+export function resolveSince(now: Date, stored: string | null): string {
+  if (stored) {
+    const parsed = new Date(stored.trim());
+    if (!Number.isNaN(parsed.getTime()) && parsed.getTime() <= now.getTime()) {
+      return parsed.toISOString();
+    }
+  }
+  return new Date(now.getTime() - DEFAULT_LOOKBACK_MS).toISOString();
+}
+
+function readLastSeen(): string | null {
+  try {
+    if (!existsSync(LAST_SEEN_FILE)) return null;
+    return readFileSync(LAST_SEEN_FILE, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+function writeLastSeen(now: Date): void {
+  try {
+    mkdirSync(STATE_DIR, { recursive: true });
+    writeFileSync(LAST_SEEN_FILE, now.toISOString());
+  } catch {
+    // fail-open: state is an optimization, not a requirement
+  }
+}
+
+function describeItem(item: unknown): string {
+  if (!item || typeof item !== "object") return String(item);
+  const m = item as Record<string, unknown>;
+  const from = typeof m.from === "string" ? m.from : typeof m.sender === "string" ? m.sender : "unknown";
+  const channel = typeof m.channel === "string" ? m.channel : typeof m.channel_name === "string" ? m.channel_name : null;
+  const body =
+    typeof m.preview === "string" ? m.preview :
+    typeof m.content === "string" ? m.content :
+    typeof m.message === "string" ? m.message : JSON.stringify(m).slice(0, 200);
+  const time = typeof m.created_at === "string" ? m.created_at : typeof m.timestamp === "string" ? m.timestamp : "";
+  const where = channel ? ` #${channel}` : "";
+  return `- [${time}]${where} ${from}: ${truncate(body, 300)}`;
+}
+
+export function truncate(text: string, max: number): string {
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+/** Build the injected context from the three catchup sections. */
+export function formatCatchup(
+  blockers: unknown[],
+  notifications: unknown[],
+  digestRaw: string | null
+): string | null {
+  const sections: string[] = [];
+
+  if (blockers.length > 0) {
+    sections.push(
+      `UNREAD BLOCKING MESSAGES (${blockers.length}) — resolve before starting work:\n` +
+        blockers.slice(0, 10).map(describeItem).join("\n")
+    );
+  }
+
+  if (notifications.length > 0) {
+    sections.push(
+      `CHANNEL NOTIFICATIONS since last catchup (${notifications.length}):\n` +
+        notifications.slice(0, 15).map(describeItem).join("\n")
+    );
+  }
+
+  if (digestRaw) {
+    try {
+      const digest = JSON.parse(digestRaw) as Record<string, unknown>;
+      const messages = Array.isArray(digest.messages) ? digest.messages : [];
+      if (messages.length > 0) {
+        sections.push(
+          `ANNOUNCEMENTS digest (unread, last 7d, ${messages.length} shown):\n` +
+            messages.slice(0, 15).map(describeItem).join("\n")
+        );
+      }
+    } catch {
+      // unparseable digest → skip section
+    }
+  }
+
+  if (sections.length === 0) return null;
+
+  return (
+    `[hook-fleet-catchup] Fleet communications catchup:\n\n` +
+    sections.join("\n\n") +
+    `\n\nRead-duty: handle blockers before claiming work; an unread [FREEZE] means stop and escalate to #help.`
+  );
+}
+
+export async function run(): Promise<void> {
+  if (process.env.HOOKS_FLEET_CATCHUP_DISABLE === "1") {
+    respond({ continue: true });
+    return;
+  }
+
+  const input = readStdinJson();
+  if (!input) {
+    respond({ continue: true });
+    return;
+  }
+
+  const now = new Date();
+  const from = fromFlag();
+  const since = resolveSince(now, readLastSeen());
+  const window = safeSince(process.env.HOOKS_FLEET_SINCE, "7d");
+
+  // The three catchup reads run in parallel — all fail-open independently:
+  // 1. unread blocking messages
+  // 2. channel notifications since last catchup (bounded lookback)
+  // 3. bounded announcements digest (never hands a session full history)
+  const [blockersRaw, notificationsRaw, digestRaw] = await Promise.all([
+    tryExec(`conversations blockers -j${from}`),
+    tryExec(`conversations notifications --since ${since} -j${from}`),
+    tryExec(`conversations digest announcements --unread --since ${window} -j${from}`),
+  ]);
+
+  const blockers = parseJsonList(blockersRaw, "blockers", "messages");
+  const notifications = parseJsonList(notificationsRaw, "notifications", "messages");
+
+  // Advance the last-seen cursor ONLY when the notifications read succeeded
+  // and returned the expected JSON shape. Otherwise bad output at session
+  // start would silently swallow the window.
+  if (hasJsonList(notificationsRaw, "notifications", "messages")) {
+    writeLastSeen(now);
+  }
+
+  const context = formatCatchup(blockers, notifications, digestRaw);
+  if (context) {
+    respond({
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: context,
+      },
+    });
+    return;
+  }
+
+  respond({ continue: true });
+}
+
+if (import.meta.main) {
+  void run();
+}

package/hooks/hook-fleet-catchup/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "lib": ["ESNext"],
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/hooks/hook-knowledge-context/README.md

@@ -0,0 +1,53 @@
+# hook-knowledge-context
+
+Codewith lifecycle hook that injects deterministic Knowledge context packs.
+
+## Installation
+
+```bash
+hooks install knowledge-context --target codewith
+```
+
+By default this prints a Codewith TOML fragment and does not mutate managed
+Codewith config. Apply that fragment through `open-configs` or the managed
+config renderer. For explicit local testing only:
+
+```bash
+hooks install knowledge-context --target codewith --apply-codewith --codewith-config /tmp/codewith-config.toml
+```
+
+## How it works
+
+On `SessionStart`, `UserPromptSubmit`, and `SubagentStart`, the hook builds a
+small redacted query from the hook input and runs:
+
+```bash
+knowledge context pack <query> --from search --max-items <n> --max-tokens <n> --json
+```
+
+The hook intentionally does not pass `--semantic`, does not call web search,
+does not call ask/build/generate flows, and does not crawl raw stores directly.
+When Knowledge returns a nonempty context pack, the hook redacts credential-like
+text from that pack and emits Codewith-native
+`hookSpecificOutput.additionalContext` with the same event name.
+
+All failures are fail-open: missing CLI, timeout, nonzero exit, malformed JSON,
+bad stdin, or empty packs return `{"continue":true}` without context.
+
+## Configuration
+
+```bash
+export HOOKS_KNOWLEDGE_CONTEXT_DISABLE=1    # Kill switch
+export HOOKS_KNOWLEDGE_COMMAND=knowledge    # CLI command/path
+export HOOKS_KNOWLEDGE_TIMEOUT_MS=1500      # Per-call timeout
+export HOOKS_KNOWLEDGE_MAX_ITEMS=6          # Context pack item budget
+export HOOKS_KNOWLEDGE_MAX_TOKENS=1200      # Context pack token budget
+export HOOKS_KNOWLEDGE_MAX_QUERY_CHARS=1200 # Redacted query bound
+export HOOKS_KNOWLEDGE_MAX_OUTPUT_CHARS=8000
+```
+
+## Events
+
+- `SessionStart`
+- `UserPromptSubmit`
+- `SubagentStart`

package/hooks/hook-knowledge-context/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@hasna/hook-knowledge-context",
+  "version": "0.1.0",
+  "description": "Codewith hook that injects deterministic Knowledge context packs into lifecycle events",
+  "type": "module",
+  "main": "./dist/hook.js",
+  "exports": {
+    ".": {
+      "import": "./dist/hook.js",
+      "types": "./dist/hook.d.ts"
+    }
+  },
+  "files": [
+    "dist/hook.js",
+    "dist/hook.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun build ./src/hook.ts --outdir ./dist --target node && tsc -p tsconfig.json --emitDeclarationOnly --declaration --declarationMap false --noEmit false",
+    "prepublishOnly": "bun run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "codewith",
+    "hook",
+    "knowledge",
+    "context",
+    "deterministic",
+    "session-start",
+    "user-prompt-submit",
+    "subagent-start"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hasna/hooks.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.8",
+    "@types/node": "^20",
+    "typescript": "^5.0.0"
+  }
+}