@nocville/npc 0.0.0-stage → 0.2.0

package/dist/npcs/cursor/setup.js

@@ -0,0 +1,90 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { maskKey, persistCredentials } from '../../core/user-config.js';
+import { buildShimHookCommand, stableNodePath, readJsonFile, removeHookGroups, resolveCliPath, writeJsonFile, } from '../agent-common/hook-settings.js';
+import { installHookShim } from '../agent-common/shim.js';
+import { ensureStableCliPath } from '../agent-common/runtime.js';
+import { CURSOR_DEFAULTS, cursorHome } from './defaults.js';
+/** Telemetry hooks only; model output and prompt text never enter Nocville. */
+export const CURSOR_HOOK_EVENTS = [
+    'sessionStart',
+    'sessionEnd',
+    'beforeSubmitPrompt',
+    'postToolUse',
+    'postToolUseFailure',
+    'afterFileEdit',
+    'stop',
+    'subagentStop',
+    'preCompact',
+];
+export function cursorSettingsPath() {
+    return join(cursorHome(), 'hooks.json');
+}
+/** Install the nocville group into every Cursor event. Mutates `file`. */
+export function installCursorHooksInto(file, command, opts = {}) {
+    const migrated = removeHookGroups(file);
+    file.version = 1;
+    file.hooks ??= {};
+    for (const event of CURSOR_HOOK_EVENTS) {
+        const existing = Array.isArray(file.hooks[event]) ? file.hooks[event] : [];
+        file.hooks[event] = [
+            ...existing,
+            { command, timeout: opts.timeout ?? CURSOR_DEFAULTS.hookTimeoutSeconds },
+        ];
+    }
+    return { migrated, installed: CURSOR_HOOK_EVENTS.length };
+}
+export function buildCursorHookCommand(_cliPath) {
+    return buildShimHookCommand('cursor');
+}
+function out(opts, msg) {
+    if (!opts.quiet)
+        console.log(msg);
+}
+/** Merge into Cursor settings, preserving user hooks and a one-time backup. */
+export function setupCursorHooks(opts = {}) {
+    const settingsPath = opts.settingsPath ?? cursorSettingsPath();
+    const dir = join(settingsPath, '..');
+    if (!existsSync(dir)) {
+        console.error(`${dir} does not exist — is Cursor installed? Skipping Cursor setup.`);
+        return false;
+    }
+    const file = readJsonFile(settingsPath);
+    if (file === null ||
+        (file.version !== undefined && file.version !== 1) ||
+        (file.hooks !== undefined &&
+            (!file.hooks || typeof file.hooks !== 'object' || Array.isArray(file.hooks)))) {
+        console.error(`Unsupported or invalid Cursor hook settings in ${settingsPath}; no settings changed.`);
+        return false;
+    }
+    const creds = persistCredentials(opts);
+    const resolved = resolveCliPath(opts.cliPath);
+    const cliPath = ensureStableCliPath(resolved);
+    installHookShim(stableNodePath(), cliPath);
+    const { installed } = installCursorHooksInto(file, buildCursorHookCommand(cliPath), {
+        timeout: CURSOR_DEFAULTS.hookTimeoutSeconds,
+    });
+    writeJsonFile(settingsPath, file);
+    out(opts, `✓ Cursor: installed Nocville hooks for ${installed} events in ${settingsPath}`);
+    out(opts, `  Hook runs: ${process.execPath} ${cliPath}`);
+    out(opts, `  API: ${creds.apiUrl ?? 'https://nocville.com'}  key: ${maskKey(creds.apiKey)}`);
+    if (!creds.apiKey) {
+        out(opts, '  ⚠ No API key saved yet — run: nocville-npc init --api-key=<your team key>');
+    }
+    return true;
+}
+/** Remove all Nocville hooks from `~/.cursor/hooks.json`. */
+export function uninstallCursorHooks(opts = {}) {
+    const settingsPath = opts.settingsPath ?? cursorSettingsPath();
+    const file = readJsonFile(settingsPath);
+    if (!file || !existsSync(settingsPath)) {
+        out(opts, 'Cursor: no hooks.json — nothing to remove.');
+        return 0;
+    }
+    const removed = removeHookGroups(file);
+    if (removed > 0)
+        writeJsonFile(settingsPath, file);
+    out(opts, `✓ Cursor: removed ${removed} Nocville hook(s) from ${settingsPath}`);
+    return removed;
+}
+//# sourceMappingURL=setup.js.map

package/dist/npcs/gemini/defaults.d.ts

@@ -0,0 +1,9 @@
+export declare const GEMINI_DEFAULTS: {
+    stateDir: string;
+    stateFileMaxAge: number;
+    heartbeatSeconds: number;
+    minPushGapMs: number;
+    hookTimeoutMs: number;
+};
+export declare const geminiHome: () => string;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/npcs/gemini/defaults.js

@@ -0,0 +1,11 @@
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+export const GEMINI_DEFAULTS = {
+    stateDir: join(tmpdir(), 'nocville-gemini'),
+    stateFileMaxAge: 24 * 60 * 60 * 1000,
+    heartbeatSeconds: 90,
+    minPushGapMs: 1500,
+    hookTimeoutMs: 5000,
+};
+export const geminiHome = () => join(homedir(), '.gemini');
+//# sourceMappingURL=defaults.js.map

package/dist/npcs/gemini/hook-handler.d.ts

@@ -0,0 +1,10 @@
+import type { NpcConfig } from '../../core/types.js';
+import type { AgentHookEvent, AgentHookSpec, HookRunOptions } from '../agent-common/hook-runner.js';
+import type { AgentAdapter, AgentSessionState, AgentTransition } from '../agent-common/session.js';
+export declare const GEMINI_ADAPTER: AgentAdapter;
+export declare function geminiServiceId(sessionId: string, cwd: string): string;
+/** Only phase and tool metadata are used; prompts/responses/transcripts are never read. */
+export declare function geminiTransition(event: AgentHookEvent, prev: AgentSessionState | null): AgentTransition;
+export declare const GEMINI_HOOK_SPEC: AgentHookSpec;
+export declare function handleGeminiHookEvent(config: NpcConfig, rawInput?: string, opts?: HookRunOptions): Promise<void>;
+//# sourceMappingURL=hook-handler.d.ts.map

package/dist/npcs/gemini/hook-handler.js

@@ -0,0 +1,87 @@
+import { THINKING, describeToolUse, failureText } from '../agent-common/activity.js';
+import { hookEventName, readStdin, runAgentHook } from '../agent-common/hook-runner.js';
+import { projectNameOf, sanitizeServiceId } from '../agent-common/session.js';
+import { GEMINI_DEFAULTS } from './defaults.js';
+export const GEMINI_ADAPTER = {
+    command: 'gemini',
+    label: 'Gemini',
+    family: 'gemini',
+    stateDir: GEMINI_DEFAULTS.stateDir,
+    heartbeatSeconds: GEMINI_DEFAULTS.heartbeatSeconds,
+    processNames: ['gemini', 'node'],
+    nodeCommandPattern: /[\/\\](?:@google[\/\\])?gemini(?:-cli[\/\\]|(?:\.[cm]?js)?(?:\s|$))/i,
+};
+export function geminiServiceId(sessionId, cwd) {
+    return sanitizeServiceId(`gemini-${projectNameOf(cwd)}-${sessionId.slice(0, 8)}`);
+}
+const idle = (activity) => ({
+    state: 'IDLE',
+    activity,
+    status: 'healthy',
+    mood: 'idle',
+});
+const working = (activity, warning = false) => ({
+    state: 'WORKING',
+    activity,
+    status: warning ? 'warning' : 'healthy',
+    mood: warning ? 'concerned' : 'happy',
+});
+/** Only phase and tool metadata are used; prompts/responses/transcripts are never read. */
+export function geminiTransition(event, prev) {
+    const cwd = typeof event.cwd === 'string' ? event.cwd : prev?.projectDir;
+    switch (hookEventName(event)) {
+        case 'SessionStart':
+            return idle('Ready for a task');
+        case 'BeforeAgent':
+            return working(THINKING);
+        case 'BeforeTool':
+            return working(describeToolUse(event.tool_name, event.tool_input, cwd));
+        case 'AfterTool': {
+            const response = event['tool_response'];
+            if (response && typeof response === 'object' && 'error' in response && response.error)
+                return working(failureText(event.tool_name), true);
+            return { ...working(), quiet: prev?.state === 'WORKING' };
+        }
+        case 'Notification':
+            if (event['notification_type'] === 'ToolPermission')
+                return {
+                    state: 'WAITING',
+                    status: 'warning',
+                    mood: 'concerned',
+                    activity: 'Needs your approval',
+                };
+            break;
+        case 'AfterAgent':
+            return idle('Done — waiting for next task');
+        case 'PreCompress':
+            return working('Compacting context');
+        case 'SessionEnd':
+            return {
+                state: 'IDLE',
+                activity: 'Session ended',
+                status: 'unknown',
+                mood: 'idle',
+                offline: true,
+            };
+    }
+    return {
+        state: prev?.state ?? 'IDLE',
+        status: prev?.status ?? 'healthy',
+        mood: prev?.mood ?? 'idle',
+        quiet: true,
+    };
+}
+export const GEMINI_HOOK_SPEC = {
+    adapter: GEMINI_ADAPTER,
+    serviceIdFor: geminiServiceId,
+    transition: geminiTransition,
+    stdoutOnSuccess: '{}',
+    statsEvents: ['AfterAgent'],
+};
+export async function handleGeminiHookEvent(config, rawInput, opts = {}) {
+    await runAgentHook(GEMINI_HOOK_SPEC, config, rawInput ?? readStdin(), {
+        minPushGapMs: GEMINI_DEFAULTS.minPushGapMs,
+        ...opts,
+    });
+}
+//# sourceMappingURL=hook-handler.js.map

package/dist/npcs/gemini/index.d.ts

@@ -0,0 +1,17 @@
+import type { NpcConfig } from '../../core/types.js';
+export { GEMINI_DEFAULTS } from './defaults.js';
+export { GEMINI_ADAPTER, geminiTransition, geminiServiceId, handleGeminiHookEvent, } from './hook-handler.js';
+export { setupGeminiHooks, uninstallGeminiHooks, installGeminiHooksInto, GEMINI_HOOK_EVENTS, } from './setup.js';
+export type { GeminiSetupOptions } from './setup.js';
+export interface GeminiSubcommandOptions {
+    subcommand: string;
+    config: NpcConfig;
+    flags: Record<string, string | boolean>;
+    args?: string[];
+}
+/**
+ * gemini subcommands: setup | uninstall | hook | flush | watchdog | cleanup.
+ * `hook` always emits {}; detached helpers stay silent.
+ */
+export declare function handleGeminiCommand(opts: GeminiSubcommandOptions): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/npcs/gemini/index.js

@@ -0,0 +1,56 @@
+import { numberFlag, stringFlag } from '../../core/config.js';
+import { readStdin, runFlushCommand } from '../agent-common/hook-runner.js';
+import { runWatchdog } from '../agent-common/watchdog.js';
+import { cleanupSessionStates } from '../agent-common/session.js';
+import { GEMINI_DEFAULTS } from './defaults.js';
+import { GEMINI_ADAPTER, handleGeminiHookEvent } from './hook-handler.js';
+import { setupGeminiHooks, uninstallGeminiHooks } from './setup.js';
+export { GEMINI_DEFAULTS } from './defaults.js';
+export { GEMINI_ADAPTER, geminiTransition, geminiServiceId, handleGeminiHookEvent, } from './hook-handler.js';
+export { setupGeminiHooks, uninstallGeminiHooks, installGeminiHooksInto, GEMINI_HOOK_EVENTS, } from './setup.js';
+/**
+ * gemini subcommands: setup | uninstall | hook | flush | watchdog | cleanup.
+ * `hook` always emits {}; detached helpers stay silent.
+ */
+export async function handleGeminiCommand(opts) {
+    const { subcommand, config, flags } = opts;
+    switch (subcommand) {
+        case 'setup': {
+            if (flags['uninstall']) {
+                uninstallGeminiHooks();
+                break;
+            }
+            const ok = setupGeminiHooks({
+                apiUrl: stringFlag(flags, 'api-url') ?? process.env['NOCVILLE_API_URL'],
+                apiKey: stringFlag(flags, 'api-key') ?? process.env['NOCVILLE_API_KEY'],
+                map: stringFlag(flags, 'map'),
+                cliPath: process.argv[1],
+            });
+            if (!ok)
+                process.exitCode = 1;
+            break;
+        }
+        case 'uninstall':
+            uninstallGeminiHooks();
+            break;
+        case 'hook':
+            await handleGeminiHookEvent(config, readStdin(), { mode: 'detach' });
+            break;
+        case 'watchdog':
+            await runWatchdog(GEMINI_ADAPTER, config, opts.args?.[0]);
+            break;
+        case 'flush':
+            await runFlushCommand(GEMINI_ADAPTER, config, opts.args?.[0], numberFlag(flags, 'delay'), flags['stats'] === true);
+            break;
+        case 'cleanup': {
+            const removed = await cleanupSessionStates(GEMINI_DEFAULTS.stateDir, GEMINI_DEFAULTS.stateFileMaxAge);
+            console.log(`Cleanup complete: ${removed} stale file(s) removed`);
+            break;
+        }
+        default:
+            console.error(`Unknown gemini subcommand: ${subcommand}`);
+            console.error('Available subcommands: setup, uninstall, hook, cleanup');
+            process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/npcs/gemini/setup.d.ts

@@ -0,0 +1,29 @@
+import type { HooksFile } from '../agent-common/hook-settings.js';
+/** Telemetry hooks only; model output and prompt text never enter Nocville. */
+export declare const GEMINI_HOOK_EVENTS: readonly ["SessionStart", "SessionEnd", "BeforeAgent", "BeforeTool", "AfterTool", "Notification", "AfterAgent", "PreCompress"];
+export declare function geminiSettingsPath(): string;
+export interface GeminiSetupOptions {
+    apiUrl?: string;
+    apiKey?: string;
+    map?: string;
+    cliPath?: string;
+    /** Override ~/.gemini/settings.json (tests). */
+    settingsPath?: string;
+    quiet?: boolean;
+}
+/** Install the nocville group into every Gemini event. Mutates `file`. */
+export declare function installGeminiHooksInto(file: HooksFile, command: string, opts?: {
+    timeout?: number;
+}): {
+    migrated: number;
+    installed: number;
+};
+export declare function buildGeminiHookCommand(_cliPath: string): string;
+/** Merge into Gemini settings, preserving user hooks and a one-time backup. */
+export declare function setupGeminiHooks(opts?: GeminiSetupOptions): boolean;
+/** Remove all Nocville hooks from `~/.gemini/settings.json`. */
+export declare function uninstallGeminiHooks(opts?: {
+    settingsPath?: string;
+    quiet?: boolean;
+}): number;
+//# sourceMappingURL=setup.d.ts.map

package/dist/npcs/gemini/setup.js

@@ -0,0 +1,90 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { maskKey, persistCredentials } from '../../core/user-config.js';
+import { buildShimHookCommand, stableNodePath, installHookGroups, readJsonFile, removeHookGroups, resolveCliPath, writeJsonFile, } from '../agent-common/hook-settings.js';
+import { installHookShim } from '../agent-common/shim.js';
+import { ensureStableCliPath } from '../agent-common/runtime.js';
+import { GEMINI_DEFAULTS, geminiHome } from './defaults.js';
+/** Telemetry hooks only; model output and prompt text never enter Nocville. */
+export const GEMINI_HOOK_EVENTS = [
+    'SessionStart',
+    'SessionEnd',
+    'BeforeAgent',
+    'BeforeTool',
+    'AfterTool',
+    'Notification',
+    'AfterAgent',
+    'PreCompress',
+];
+export function geminiSettingsPath() {
+    return join(geminiHome(), 'settings.json');
+}
+/** Install the nocville group into every Gemini event. Mutates `file`. */
+export function installGeminiHooksInto(file, command, opts = {}) {
+    const result = installHookGroups(file, command, GEMINI_HOOK_EVENTS, {
+        perEvent: Object.fromEntries(GEMINI_HOOK_EVENTS.map((event) => [
+            event,
+            {
+                name: 'nocville',
+                timeout: opts.timeout ?? GEMINI_DEFAULTS.hookTimeoutMs,
+            },
+        ])),
+    });
+    // Omit the optional matcher so lifecycle sources/reasons are all observed too.
+    for (const event of GEMINI_HOOK_EVENTS) {
+        const group = file.hooks[event].at(-1);
+        delete group.matcher;
+    }
+    return result;
+}
+export function buildGeminiHookCommand(_cliPath) {
+    return buildShimHookCommand('gemini');
+}
+function out(opts, msg) {
+    if (!opts.quiet)
+        console.log(msg);
+}
+/** Merge into Gemini settings, preserving user hooks and a one-time backup. */
+export function setupGeminiHooks(opts = {}) {
+    const settingsPath = opts.settingsPath ?? geminiSettingsPath();
+    const dir = join(settingsPath, '..');
+    if (!existsSync(dir)) {
+        console.error(`${dir} does not exist — is Gemini installed? Skipping Gemini setup.`);
+        return false;
+    }
+    const file = readJsonFile(settingsPath);
+    if (file === null) {
+        console.error(`Could not parse ${settingsPath}; fix it (or move it aside) and re-run setup.`);
+        return false;
+    }
+    const creds = persistCredentials(opts);
+    const resolved = resolveCliPath(opts.cliPath);
+    const cliPath = ensureStableCliPath(resolved);
+    installHookShim(stableNodePath(), cliPath);
+    const { installed } = installGeminiHooksInto(file, buildGeminiHookCommand(cliPath), {
+        timeout: GEMINI_DEFAULTS.hookTimeoutMs,
+    });
+    writeJsonFile(settingsPath, file);
+    out(opts, `✓ Gemini: installed Nocville hooks for ${installed} events in ${settingsPath}`);
+    out(opts, `  Hook runs: ${process.execPath} ${cliPath}`);
+    out(opts, `  API: ${creds.apiUrl ?? 'https://nocville.com'}  key: ${maskKey(creds.apiKey)}`);
+    if (!creds.apiKey) {
+        out(opts, '  ⚠ No API key saved yet — run: nocville-npc init --api-key=<your team key>');
+    }
+    return true;
+}
+/** Remove all Nocville hooks from `~/.gemini/settings.json`. */
+export function uninstallGeminiHooks(opts = {}) {
+    const settingsPath = opts.settingsPath ?? geminiSettingsPath();
+    const file = readJsonFile(settingsPath);
+    if (!file || !existsSync(settingsPath)) {
+        out(opts, 'Gemini: no settings.json — nothing to remove.');
+        return 0;
+    }
+    const removed = removeHookGroups(file);
+    if (removed > 0)
+        writeJsonFile(settingsPath, file);
+    out(opts, `✓ Gemini: removed ${removed} Nocville hook(s) from ${settingsPath}`);
+    return removed;
+}
+//# sourceMappingURL=setup.js.map

package/dist/npcs/github-watcher/defaults.d.ts

@@ -0,0 +1,8 @@
+export declare const DEFAULTS: {
+    pollInterval: number;
+    fetchTimeoutMs: number;
+    perPage: number;
+    /** Polls to keep the 'new-commit' sub-status active after a fresh commit. */
+    newCommitPolls: number;
+};
+//# sourceMappingURL=defaults.d.ts.map

package/dist/npcs/github-watcher/defaults.js

@@ -0,0 +1,8 @@
+export const DEFAULTS = {
+    pollInterval: 60000, // 60s
+    fetchTimeoutMs: 5000,
+    perPage: 10,
+    /** Polls to keep the 'new-commit' sub-status active after a fresh commit. */
+    newCommitPolls: 2,
+};
+//# sourceMappingURL=defaults.js.map

package/dist/npcs/github-watcher/format.d.ts

@@ -0,0 +1,3 @@
+/** Short relative-time string like "3m ago", "2h ago", "1d ago". */
+export declare function relativeTime(iso: string, now?: number): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/npcs/github-watcher/format.js

@@ -0,0 +1,18 @@
+/** Short relative-time string like "3m ago", "2h ago", "1d ago". */
+export function relativeTime(iso, now = Date.now()) {
+    const t = Date.parse(iso);
+    if (!Number.isFinite(t))
+        return 'unknown';
+    const secs = Math.max(0, Math.round((now - t) / 1000));
+    if (secs < 60)
+        return `${secs}s ago`;
+    const mins = Math.round(secs / 60);
+    if (mins < 60)
+        return `${mins}m ago`;
+    const hrs = Math.round(mins / 60);
+    if (hrs < 24)
+        return `${hrs}h ago`;
+    const days = Math.round(hrs / 24);
+    return `${days}d ago`;
+}
+//# sourceMappingURL=format.js.map

package/dist/npcs/github-watcher/github-api.d.ts

@@ -0,0 +1,55 @@
+export interface CommitInfo {
+    sha: string;
+    author: string;
+    message: string;
+    date: string;
+}
+export interface FetchCommitsResult {
+    /** 304 Not Modified — the ETag matched, nothing changed, no rate-limit cost. */
+    notModified: boolean;
+    commits: CommitInfo[];
+    etag: string | null;
+    rateRemaining: number | null;
+    status: number;
+}
+/** Minimal fetch signature so tests can inject a stub. */
+export type FetchFn = (url: string, init?: {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}>;
+export interface FetchOptions {
+    token?: string;
+    etag?: string | null;
+    branch?: string;
+    timeoutMs?: number;
+    perPage?: number;
+    /** Injectable fetch (defaults to the global fetch). */
+    fetchFn?: FetchFn;
+}
+/** Look up a repo's default branch (one call at startup). Null on failure. */
+export declare function fetchDefaultBranch(repo: string, opts?: FetchOptions): Promise<string | null>;
+/**
+ * Fetch recent commits from the GitHub REST API using conditional requests.
+ * Passing the previous ETag yields a 304 (which does not count against the
+ * unauthenticated 60/hour limit) when nothing has changed. Never throws —
+ * network errors surface as `status: 0`.
+ */
+export declare function fetchCommits(repo: string, opts?: FetchOptions): Promise<FetchCommitsResult>;
+/** Count how many commits landed within the last `hours`. */
+export declare function commitsWithin(commits: CommitInfo[], hours: number, now?: number): number;
+/**
+ * Return the commits newer than `lastSeenSha`, newest-first. When the sha isn't
+ * present in the window (more than a page of new commits, or rewritten history)
+ * every fetched commit is treated as new. An undefined sha means "not seeded
+ * yet" — returns empty so the caller can seed without a spurious announcement.
+ */
+export declare function newCommitsSince(commits: CommitInfo[], lastSeenSha: string | null): CommitInfo[];
+//# sourceMappingURL=github-api.d.ts.map

package/dist/npcs/github-watcher/github-api.js

@@ -0,0 +1,120 @@
+function toNum(v) {
+    if (v === null)
+        return null;
+    const n = Number(v);
+    return Number.isNaN(n) ? null : n;
+}
+function ghHeaders(opts) {
+    const headers = {
+        Accept: 'application/vnd.github+json',
+        'User-Agent': 'nocville-npc',
+        'X-GitHub-Api-Version': '2022-11-28',
+    };
+    if (opts.token)
+        headers['Authorization'] = `Bearer ${opts.token}`;
+    return headers;
+}
+/** Look up a repo's default branch (one call at startup). Null on failure. */
+export async function fetchDefaultBranch(repo, opts = {}) {
+    const doFetch = opts.fetchFn ?? globalThis.fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 5000);
+    try {
+        const res = await doFetch(`https://api.github.com/repos/${repo}`, {
+            headers: ghHeaders(opts),
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return body.default_branch ?? null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Fetch recent commits from the GitHub REST API using conditional requests.
+ * Passing the previous ETag yields a 304 (which does not count against the
+ * unauthenticated 60/hour limit) when nothing has changed. Never throws —
+ * network errors surface as `status: 0`.
+ */
+export async function fetchCommits(repo, opts = {}) {
+    const perPage = opts.perPage ?? 10;
+    const doFetch = opts.fetchFn ?? globalThis.fetch;
+    let url = `https://api.github.com/repos/${repo}/commits?per_page=${perPage}`;
+    if (opts.branch)
+        url += `&sha=${encodeURIComponent(opts.branch)}`;
+    const headers = ghHeaders(opts);
+    if (opts.etag)
+        headers['If-None-Match'] = opts.etag;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 5000);
+    try {
+        const res = await doFetch(url, { headers, signal: controller.signal });
+        const rateRemaining = toNum(res.headers.get('x-ratelimit-remaining'));
+        const etag = res.headers.get('etag');
+        if (res.status === 304) {
+            return {
+                notModified: true,
+                commits: [],
+                etag: opts.etag ?? null,
+                rateRemaining,
+                status: 304,
+            };
+        }
+        if (!res.ok) {
+            await res.text().catch(() => undefined);
+            return { notModified: false, commits: [], etag, rateRemaining, status: res.status };
+        }
+        const body = (await res.json());
+        const commits = body.map((c) => parseCommit(c));
+        return { notModified: false, commits, etag, rateRemaining, status: res.status };
+    }
+    catch {
+        return { notModified: false, commits: [], etag: null, rateRemaining: null, status: 0 };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function parseCommit(c) {
+    const commit = c['commit'] ?? {};
+    const commitAuthor = commit['author'] ?? {};
+    const ghAuthor = c['author'] ?? {};
+    const message = String(commit['message'] ?? '').split('\n')[0] ?? '';
+    return {
+        sha: String(c['sha'] ?? ''),
+        author: String(commitAuthor['name'] ?? ghAuthor['login'] ?? 'unknown'),
+        message,
+        date: String(commitAuthor['date'] ?? ''),
+    };
+}
+/** Count how many commits landed within the last `hours`. */
+export function commitsWithin(commits, hours, now = Date.now()) {
+    const cutoff = now - hours * 3600_000;
+    return commits.filter((c) => {
+        const t = Date.parse(c.date);
+        return Number.isFinite(t) && t >= cutoff;
+    }).length;
+}
+/**
+ * Return the commits newer than `lastSeenSha`, newest-first. When the sha isn't
+ * present in the window (more than a page of new commits, or rewritten history)
+ * every fetched commit is treated as new. An undefined sha means "not seeded
+ * yet" — returns empty so the caller can seed without a spurious announcement.
+ */
+export function newCommitsSince(commits, lastSeenSha) {
+    if (!lastSeenSha)
+        return [];
+    const idx = commits.findIndex((c) => c.sha === lastSeenSha);
+    if (idx === 0)
+        return []; // newest is already seen
+    if (idx === -1)
+        return commits; // fell out of the window — treat all as new
+    return commits.slice(0, idx);
+}
+//# sourceMappingURL=github-api.js.map

package/dist/npcs/github-watcher/index.d.ts

@@ -0,0 +1,35 @@
+import { PollingNPC } from '../../core/polling-npc.js';
+import type { PollingNpcConfig } from '../../core/polling-npc.js';
+import type { CollectedMetrics, Archetype, CompanionDecl } from '../../core/types.js';
+import type { FetchFn } from './github-api.js';
+export interface GitHubWatcherConfig extends PollingNpcConfig {
+    /** "owner/name" */
+    repo: string;
+    token?: string;
+    branch?: string;
+    /** Injectable fetch (for tests). */
+    fetchFn?: FetchFn;
+}
+export declare class GitHubWatcherNPC extends PollingNPC {
+    private repo;
+    private token?;
+    private branch?;
+    private fetchFn?;
+    private etag;
+    private lastSeenSha;
+    private commits;
+    private rateRemaining;
+    private newCommitPollsLeft;
+    constructor(config: GitHubWatcherConfig);
+    get name(): string;
+    protected get defaultDisplayName(): string;
+    get archetype(): Archetype;
+    get companion(): CompanionDecl;
+    protected onStart(): Promise<void>;
+    protected collect(): Promise<CollectedMetrics>;
+    private reportNewCommits;
+    private reportIdle;
+    private report;
+    private buildBoard;
+}
+//# sourceMappingURL=index.d.ts.map