@nocville/npc 0.0.0-stage → 0.2.1

package/dist/npcs/cursor/normalize.d.ts

@@ -0,0 +1,6 @@
+import type { AgentHookEvent } from '../agent-common/hook-runner.js';
+export declare const CURSOR_TO_CANON: Record<string, string>;
+export declare function isCursorInvocation(event: AgentHookEvent): boolean;
+/** Copy only telemetry fields; never retain prompts, model responses or tool output. */
+export declare function normalizeCursorEvent(event: AgentHookEvent): AgentHookEvent;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/npcs/cursor/normalize.js

@@ -0,0 +1,49 @@
+export const CURSOR_TO_CANON = {
+    sessionStart: 'SessionStart',
+    sessionEnd: 'SessionEnd',
+    beforeSubmitPrompt: 'UserPromptSubmit',
+    preToolUse: 'PreToolUse',
+    postToolUse: 'PostToolUse',
+    postToolUseFailure: 'PostToolUseFailure',
+    beforeShellExecution: 'PreToolUse',
+    afterFileEdit: 'PostToolUse',
+    stop: 'Stop',
+    subagentStart: 'SubagentStart',
+    subagentStop: 'SubagentStop',
+    preCompact: 'PreCompact',
+};
+export function isCursorInvocation(event) {
+    const transcript = typeof event['transcript_path'] === 'string'
+        ? event['transcript_path'].replace(/\\/g, '/')
+        : '';
+    return (typeof event['cursor_version'] === 'string' ||
+        (typeof event['conversation_id'] === 'string' && !/(?:^|\/)\.claude(?:\/|$)/.test(transcript)));
+}
+/** Copy only telemetry fields; never retain prompts, model responses or tool output. */
+export function normalizeCursorEvent(event) {
+    const name = event.hook_event_name ?? event.event ?? '';
+    const roots = event['workspace_roots'];
+    const shell = name === 'beforeShellExecution';
+    const tools = {
+        Shell: 'Bash',
+        ReadFile: 'Read',
+        Write: 'Write',
+        StrReplace: 'Edit',
+        Grep: 'Grep',
+        Delete: 'Delete',
+        Task: 'Task',
+    };
+    return {
+        session_id: typeof event['conversation_id'] === 'string' ? event['conversation_id'] : event.session_id,
+        cwd: Array.isArray(roots) && typeof roots[0] === 'string' ? roots[0] : event.cwd,
+        hook_event_name: CURSOR_TO_CANON[name] ?? name,
+        tool_name: shell
+            ? 'Bash'
+            : event.tool_name?.startsWith('MCP:')
+                ? `mcp__cursor__${event.tool_name.slice(4)}`
+                : (tools[event.tool_name ?? ''] ?? event.tool_name),
+        tool_input: shell ? { command: event['command'] } : event.tool_input,
+        generation_id: typeof event['generation_id'] === 'string' ? event['generation_id'] : undefined,
+    };
+}
+//# sourceMappingURL=normalize.js.map

package/dist/npcs/cursor/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 CURSOR_HOOK_EVENTS: string[];
+export declare function cursorSettingsPath(): string;
+export interface CursorSetupOptions {
+    apiUrl?: string;
+    apiKey?: string;
+    map?: string;
+    cliPath?: string;
+    /** Override ~/.cursor/hooks.json (tests). */
+    settingsPath?: string;
+    quiet?: boolean;
+}
+/** Install the nocville group into every Cursor event. Mutates `file`. */
+export declare function installCursorHooksInto(file: HooksFile, command: string, opts?: {
+    timeout?: number;
+}): {
+    migrated: number;
+    installed: number;
+};
+export declare function buildCursorHookCommand(_cliPath: string): string;
+/** Merge into Cursor settings, preserving user hooks and a one-time backup. */
+export declare function setupCursorHooks(opts?: CursorSetupOptions): boolean;
+/** Remove all Nocville hooks from `~/.cursor/hooks.json`. */
+export declare function uninstallCursorHooks(opts?: {
+    settingsPath?: string;
+    quiet?: boolean;
+}): number;
+//# sourceMappingURL=setup.d.ts.map

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