@hasna/hooks 0.2.19 → 0.3.0

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/pre-bash/README.md

@@ -0,0 +1,17 @@
+# pre-bash
+
+Codewith-native hook installed as `hooks run pre-bash`.
+
+This hook is OSS-safe: optional Hasna CLIs are best-effort and missing CLIs fail open with concise warnings. Security gates only fail closed when a guarded commit/push scan runs successfully and finds possible secrets.
+
+## Install for Codewith
+
+Prefer renderer-managed configuration through open-configs. @hasna/hooks can emit the TOML fragment:
+
+```bash
+hooks install pre-bash --target codewith
+```
+
+## License
+
+Apache-2.0

package/hooks/pre-bash/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "pre-bash",
+  "version": "0.1.0",
+  "description": "Codewith-native Pre Bash hook for @hasna/hooks",
+  "type": "module",
+  "main": "./src/hook.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Hasna",
+  "license": "Apache-2.0"
+}

package/hooks/pre-bash/src/hook.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env bun
+
+import {
+  commandExists,
+  gitCommandInfo,
+  getCommand,
+  isBashPreToolUse,
+  isRiskyOperation,
+  readCache,
+  readInput,
+  redactGitleaksOutput,
+  respond,
+  runCommand,
+  warn,
+  type CodewithHookInput,
+} from "../../codewith-native-common";
+
+interface SessionDigest {
+  context: string;
+  warnings: string[];
+}
+
+async function runStagedSecretsScan(cwd: string): Promise<{ block: boolean; reason?: string; warning?: string }> {
+  if (!commandExists("gitleaks")) {
+    return { block: false, warning: "gitleaks unavailable; staged secrets scan skipped fail-open." };
+  }
+
+  const result = await runCommand([
+    "gitleaks", "git", "--staged", "--no-banner", "--redact", "--report-format", "json", "--report-path", "-", ".",
+  ], { cwd, timeoutMs: 15_000 });
+
+  if (result.exitCode === 0) return { block: false };
+  if (result.exitCode === 1) {
+    return { block: true, reason: redactGitleaksOutput(result.stdout, result.stderr) };
+  }
+  return { block: false, warning: `gitleaks scan did not complete cleanly (exit ${result.exitCode ?? "unknown"}${result.timedOut ? ", timed out" : ""}); fail-open.` };
+}
+
+function riskyCommsBlock(): string | null {
+  const cached = readCache<SessionDigest>("session-start-digest", 5 * 60_000);
+  if (!cached) return null;
+  const context = cached.context || "";
+  if (/\[FREEZE\]/i.test(context)) return "Cached announcements contain a [FREEZE]. Re-check conversations before running risky operations.";
+  if (/Unread blockers JSON:\n\s*\[(?!\s*\])/i.test(context)) return "Cached conversations blockers are non-empty. Resolve or verify blockers before risky operations.";
+  if (/"message_ids"\s*:\s*\[(?!\s*\])/i.test(context) && /blockers/i.test(context)) return "Cached blocker digest appears non-empty. Re-check conversations before risky operations.";
+  return null;
+}
+
+export async function evaluate(input: CodewithHookInput): Promise<{ output: Record<string, unknown>; warnings: string[] }> {
+  const warnings: string[] = [];
+  if (!isBashPreToolUse(input)) return { output: { continue: true }, warnings };
+  const command = getCommand(input);
+  if (!command) return { output: { continue: true }, warnings };
+  const cwd = input.cwd || process.cwd();
+  const gitInfo = gitCommandInfo(command, cwd);
+
+  if (gitInfo) {
+    const scan = await runStagedSecretsScan(gitInfo.targetCwd);
+    if (scan.warning) warnings.push(scan.warning);
+    if (scan.block) {
+      return { output: { decision: "block", reason: scan.reason }, warnings };
+    }
+  }
+
+  if (isRiskyOperation(command)) {
+    const reason = riskyCommsBlock();
+    if (reason) return { output: { decision: "block", reason }, warnings };
+    if (!readCache<SessionDigest>("session-start-digest", 5 * 60_000)) {
+      warnings.push("No fresh session-start comms cache; risky operation allowed fail-open, but manually re-check blockers/announcements first.");
+    }
+  }
+
+  if (warnings.length > 0) {
+    return {
+      output: {
+        continue: true,
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          additionalContext: warnings.map((w) => `[pre-bash] ${w}`).join("\n"),
+        },
+      },
+      warnings,
+    };
+  }
+
+  return { output: { continue: true }, warnings };
+}
+
+export async function run(): Promise<void> {
+  const input = readInput();
+  try {
+    const { output, warnings } = await evaluate(input);
+    for (const message of warnings) warn(message);
+    respond(output);
+  } catch (error) {
+    warn(`pre-bash failed open: ${error instanceof Error ? error.message : String(error)}`);
+    respond({ continue: true });
+  }
+}
+
+if (import.meta.main) {
+  await run();
+}

package/hooks/prompt-guard/README.md

@@ -0,0 +1,17 @@
+# prompt-guard
+
+Codewith-native hook installed as `hooks run prompt-guard`.
+
+This hook is OSS-safe: optional Hasna CLIs are best-effort and missing CLIs fail open with concise warnings. Security gates only fail closed when a guarded commit/push scan runs successfully and finds possible secrets.
+
+## Install for Codewith
+
+Prefer renderer-managed configuration through open-configs. @hasna/hooks can emit the TOML fragment:
+
+```bash
+hooks install prompt-guard --target codewith
+```
+
+## License
+
+Apache-2.0

package/hooks/prompt-guard/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "prompt-guard",
+  "version": "0.1.0",
+  "description": "Codewith-native Prompt Guard hook for @hasna/hooks",
+  "type": "module",
+  "main": "./src/hook.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Hasna",
+  "license": "Apache-2.0"
+}