@ivotoby/postgram-cli 1.38.2 → 1.39.0

package/dist/tracking/here.js

@@ -0,0 +1,267 @@
+// cli/src/tracking/here.ts: pgm here — hook and manual workspace/session reports.
+import { appendFile, mkdir, rename, stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { readStdinText, resolvePgmConfig, shortId } from '../shared.js';
+import { createTrackingClient } from './api.js';
+import { loadTrackingConfig, usageExit } from './config.js';
+import { readBootId, readMarker, resolveLocalWorkspace } from './local.js';
+import { AGENT_KINDS } from './types.js';
+const HOOK_EVENTS = {
+    SessionStart: 'start',
+    UserPromptSubmit: 'activity',
+    Stop: 'stop',
+    SessionEnd: 'end'
+};
+const SESSION_EVENTS = ['start', 'activity', 'stop', 'end'];
+const LOG_ROTATE_BYTES = 1_048_576;
+export function parseHookInput(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === '') {
+        return { kind: 'invalid' };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return { kind: 'invalid' };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { kind: 'invalid' };
+    }
+    const obj = parsed;
+    const hookEvent = obj.hook_event_name;
+    if (typeof hookEvent !== 'string') {
+        return { kind: 'invalid' };
+    }
+    const event = HOOK_EVENTS[hookEvent];
+    if (event === undefined) {
+        return { kind: 'ignore' };
+    }
+    const sessionId = typeof obj.session_id === 'string' && obj.session_id !== ''
+        ? obj.session_id
+        : null;
+    const cwd = typeof obj.cwd === 'string' ? obj.cwd : undefined;
+    const transcriptRaw = obj.transcript_path;
+    const transcriptPath = typeof transcriptRaw === 'string' || transcriptRaw === null
+        ? transcriptRaw
+        : undefined;
+    const reasonRaw = hookEvent === 'SessionStart'
+        ? obj.source
+        : hookEvent === 'SessionEnd'
+            ? obj.reason
+            : undefined;
+    const reason = typeof reasonRaw === 'string' && reasonRaw !== '' ? reasonRaw : undefined;
+    return {
+        kind: 'report',
+        event,
+        sessionId,
+        ...(cwd !== undefined ? { cwd } : {}),
+        ...(transcriptPath !== undefined ? { transcriptPath } : {}),
+        ...(reason !== undefined ? { reason } : {}),
+        hookEvent
+    };
+}
+function asAgentKind(value) {
+    if (value !== undefined && AGENT_KINDS.includes(value)) {
+        return value;
+    }
+    return null;
+}
+function asSessionEvent(value) {
+    if (value !== undefined &&
+        SESSION_EVENTS.includes(value)) {
+        return value;
+    }
+    return null;
+}
+function featureLine(feature) {
+    return `Postgram: this worktree belongs to feature ${shortId(feature.id)} "${feature.title}" (stage: ${feature.stage ?? 'building'}).`;
+}
+export async function runHere(options, deps) {
+    let agent;
+    let sessionId;
+    let event;
+    let cwd;
+    let transcriptPath;
+    let reason;
+    let hookEvent = null;
+    if (options.hook) {
+        const parsed = parseHookInput(await deps.stdin());
+        if (parsed.kind === 'invalid') {
+            await deps.log('invalid hook input');
+            return { stdout: '', exitCode: 0 };
+        }
+        if (parsed.kind === 'ignore') {
+            return { stdout: '', exitCode: 0 };
+        }
+        agent = asAgentKind(options.agent) ?? 'claude-code';
+        sessionId = parsed.sessionId ?? options.sessionId ?? null;
+        event = parsed.event;
+        cwd = parsed.cwd ?? options.cwd ?? deps.cwd;
+        transcriptPath = parsed.transcriptPath ?? options.transcript ?? null;
+        reason = parsed.reason ?? options.reason;
+        hookEvent = parsed.hookEvent;
+    }
+    else {
+        if (options.agent !== undefined && asAgentKind(options.agent) === null) {
+            process.stderr.write(`pgm here: invalid --agent '${options.agent}'\n`);
+            return { stdout: '', exitCode: 2 };
+        }
+        if (options.event !== undefined && asSessionEvent(options.event) === null) {
+            process.stderr.write(`pgm here: invalid --event '${options.event}'\n`);
+            return { stdout: '', exitCode: 2 };
+        }
+        agent = asAgentKind(options.agent) ?? 'claude-code';
+        sessionId = options.sessionId ?? null;
+        event = asSessionEvent(options.event);
+        cwd = options.cwd ?? deps.cwd;
+        transcriptPath = options.transcript ?? null;
+        reason = options.reason;
+    }
+    if (deps.config === null) {
+        await deps.log('missing config');
+        return { stdout: '', exitCode: 0 };
+    }
+    const config = deps.config;
+    if (deps.client === null) {
+        await deps.log('missing credentials');
+        return { stdout: '', exitCode: 0 };
+    }
+    const client = deps.client;
+    const start = deps.now();
+    const local = await deps.resolveWorkspace(cwd, 800);
+    if (local.kind === 'timeout') {
+        await deps.log('git timeout');
+        return { stdout: '', exitCode: 0 };
+    }
+    const marker = await deps.readMarker(local.path);
+    const bootId = await deps.bootId();
+    const session = sessionId !== null || event !== null
+        ? {
+            agent_kind: agent,
+            agent_session_id: sessionId,
+            event: event ?? 'activity',
+            ...(reason !== undefined ? { reason } : {}),
+            cwd,
+            transcript_path: transcriptPath
+        }
+        : undefined;
+    const body = {
+        source: 'hook',
+        machine: { alias: config.alias, hostname: deps.hostname, boot_id: bootId },
+        workspace: local.workspace,
+        ...(marker !== null ? { feature_id: marker } : {}),
+        ...(session !== undefined ? { session } : {})
+    };
+    const timeoutMs = Math.max(100, config.hereTimeoutMs - (deps.now() - start) - 100);
+    let feature;
+    try {
+        const response = await client.report(body, { timeoutMs });
+        feature = response.feature;
+    }
+    catch (error) {
+        await deps.log(error instanceof Error ? error.message : 'report failed');
+        return { stdout: '', exitCode: 0 };
+    }
+    if (options.hook) {
+        if (event === 'start' &&
+            hookEvent === 'SessionStart' &&
+            options.quiet === false &&
+            feature !== null) {
+            return { stdout: `${featureLine(feature)}\n`, exitCode: 0 };
+        }
+        return { stdout: '', exitCode: 0 };
+    }
+    const line = feature !== null
+        ? `registered ${config.alias}:${local.path} → feature ${shortId(feature.id)} (${feature.stage ?? 'building'})`
+        : `registered ${config.alias}:${local.path} (unassigned)`;
+    return { stdout: `${line}\n`, exitCode: 0 };
+}
+export async function appendHereLog(homeDir, message, now) {
+    const dir = path.join(homeDir, '.pgm');
+    await mkdir(dir, { recursive: true });
+    const file = path.join(dir, 'here.log');
+    const rotated = path.join(dir, 'here.log.1');
+    try {
+        const existing = await stat(file);
+        if (existing.size >= LOG_ROTATE_BYTES) {
+            await rename(file, rotated);
+        }
+    }
+    catch {
+        // no existing log file
+    }
+    const line = `${(now ?? new Date()).toISOString()} ${message.replace(/\r?\n/g, ' ')}\n`;
+    await appendFile(file, line, 'utf8');
+}
+export function registerHereCommand(program) {
+    const command = usageExit(program
+        .command('here')
+        .description('Report this workspace (and session) to Postgram')
+        .option('--agent <kind>', 'agent kind (claude-code, pi, talon, other)')
+        .option('--session-id <id>', 'agent session id')
+        .option('--event <event>', 'session event (start, activity, stop, end)')
+        .option('--reason <text>', 'reason text')
+        .option('--cwd <dir>', 'working directory to report')
+        .option('--transcript <path>', 'transcript path')
+        .option('--hook', 'read the Claude Code hook JSON from stdin')
+        .option('--quiet', 'suppress the SessionStart feature line')).action(async () => {
+        const opts = command.opts();
+        let config = null;
+        try {
+            config = await loadTrackingConfig();
+        }
+        catch {
+            config = null;
+        }
+        let client = null;
+        try {
+            client = createTrackingClient(await resolvePgmConfig());
+        }
+        catch {
+            client = null;
+        }
+        const homeDir = os.homedir();
+        const deps = {
+            config,
+            client,
+            stdin: readStdinText,
+            cwd: process.cwd(),
+            hostname: os.hostname(),
+            homeDir,
+            now: Date.now,
+            bootId: readBootId,
+            resolveWorkspace: (cwd, budgetMs) => resolveLocalWorkspace(cwd, { budgetMs }),
+            readMarker,
+            log: (line) => appendHereLog(homeDir, line)
+        };
+        try {
+            const result = await runHere({
+                hook: opts.hook === true,
+                quiet: opts.quiet === true,
+                ...(opts.agent !== undefined ? { agent: opts.agent } : {}),
+                ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
+                ...(opts.event !== undefined ? { event: opts.event } : {}),
+                ...(opts.reason !== undefined ? { reason: opts.reason } : {}),
+                ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+                ...(opts.transcript !== undefined ? { transcript: opts.transcript } : {})
+            }, deps);
+            if (result.stdout !== '') {
+                process.stdout.write(result.stdout);
+            }
+            if (result.exitCode !== 0) {
+                process.exitCode = result.exitCode;
+            }
+        }
+        catch (error) {
+            try {
+                await appendHereLog(homeDir, error instanceof Error ? error.message : 'here failed');
+            }
+            catch {
+                // the hook must still exit 0
+            }
+        }
+    });
+}

package/dist/tracking/hooks.js

@@ -0,0 +1,375 @@
+// cli/src/tracking/hooks.ts: pgm hooks install / uninstall.
+import { realpathSync } from 'node:fs';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { handleCliFailure, isJsonMode, printHuman, printJson } from '../shared.js';
+import { UsageError, shq, usageExit } from './config.js';
+export const HOOK_EVENTS = [
+    'SessionStart',
+    'UserPromptSubmit',
+    'Stop',
+    'SessionEnd'
+];
+export function hookCommand(nodePath, scriptPath) {
+    return `${shq(nodePath)} ${shq(scriptPath)} here --hook`;
+}
+export function isPostgramHook(command) {
+    return command.includes('pgm') && /\bhere --hook\b/.test(command);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isOurHook(hook) {
+    return (isRecord(hook) &&
+        typeof hook.command === 'string' &&
+        isPostgramHook(hook.command));
+}
+function withoutPostgramHooks(entries) {
+    const kept = [];
+    if (!Array.isArray(entries)) {
+        return kept;
+    }
+    for (const entry of entries) {
+        if (!isRecord(entry) || !Array.isArray(entry.hooks)) {
+            kept.push(entry);
+            continue;
+        }
+        const hooks = entry.hooks.filter((hook) => !isOurHook(hook));
+        if (hooks.length === 0) {
+            continue;
+        }
+        kept.push({ ...entry, hooks });
+    }
+    return kept;
+}
+export function installHooks(settings, command, keepTranscripts) {
+    const next = structuredClone(settings);
+    const hooks = isRecord(next.hooks) ? next.hooks : {};
+    for (const event of HOOK_EVENTS) {
+        const kept = withoutPostgramHooks(hooks[event]);
+        kept.push({ hooks: [{ type: 'command', command, timeout: 5 }] });
+        hooks[event] = kept;
+    }
+    next.hooks = hooks;
+    if (typeof keepTranscripts === 'number') {
+        const current = next.cleanupPeriodDays;
+        if (!(typeof current === 'number' && current >= keepTranscripts)) {
+            next.cleanupPeriodDays = keepTranscripts;
+        }
+    }
+    return next;
+}
+export function uninstallHooks(settings) {
+    const next = structuredClone(settings);
+    const hooks = isRecord(next.hooks) ? next.hooks : {};
+    for (const event of HOOK_EVENTS) {
+        hooks[event] = withoutPostgramHooks(hooks[event]);
+    }
+    next.hooks = hooks;
+    return next;
+}
+export function unifiedDiff(before, after, label) {
+    if (before === after) {
+        return '';
+    }
+    const a = before.split('\n');
+    const b = after.split('\n');
+    const n = a.length;
+    const m = b.length;
+    const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--) {
+        const row = lcs[i];
+        const below = lcs[i + 1];
+        if (row === undefined || below === undefined) {
+            continue;
+        }
+        for (let j = m - 1; j >= 0; j--) {
+            const ai = a[i];
+            const bj = b[j];
+            if (ai !== undefined && bj !== undefined && ai === bj) {
+                row[j] = (below[j + 1] ?? 0) + 1;
+            }
+            else {
+                row[j] = Math.max(row[j + 1] ?? 0, below[j] ?? 0);
+            }
+        }
+    }
+    const lines = [`--- ${label}`, `+++ ${label}`];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        const ai = a[i];
+        const bj = b[j];
+        if (ai !== undefined && bj !== undefined && ai === bj) {
+            i += 1;
+            j += 1;
+            continue;
+        }
+        const down = lcs[i + 1]?.[j] ?? 0;
+        const right = lcs[i]?.[j + 1] ?? 0;
+        if (down >= right) {
+            if (ai !== undefined) {
+                lines.push(`-${ai}`);
+            }
+            i += 1;
+        }
+        else {
+            if (bj !== undefined) {
+                lines.push(`+${bj}`);
+            }
+            j += 1;
+        }
+    }
+    while (i < n) {
+        const ai = a[i];
+        if (ai !== undefined) {
+            lines.push(`-${ai}`);
+        }
+        i += 1;
+    }
+    while (j < m) {
+        const bj = b[j];
+        if (bj !== undefined) {
+            lines.push(`+${bj}`);
+        }
+        j += 1;
+    }
+    return lines.join('\n');
+}
+export function renderPiExtension(template, nodePath, scriptPath) {
+    return template
+        .replaceAll("'__PGM_NODE__'", JSON.stringify(nodePath))
+        .replaceAll("'__PGM_SCRIPT__'", JSON.stringify(scriptPath));
+}
+export function settingsPath(input) {
+    if (input.flag !== undefined) {
+        return input.flag;
+    }
+    const configDir = input.env.CLAUDE_CONFIG_DIR;
+    if (configDir !== undefined && configDir !== '') {
+        return path.join(configDir, 'settings.json');
+    }
+    return path.join(input.homeDir, '.claude', 'settings.json');
+}
+export function piExtensionPath(env, homeDir) {
+    const piDir = env.PI_CODING_AGENT_DIR;
+    const base = piDir !== undefined && piDir !== ''
+        ? piDir
+        : path.join(homeDir, '.pi', 'agent');
+    return path.join(base, 'extensions', 'postgram.ts');
+}
+function isEnoent(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        error.code === 'ENOENT');
+}
+export async function runHooksInstall(options, deps) {
+    let keep = null;
+    if (options.keepTranscripts !== undefined) {
+        const value = Number(options.keepTranscripts);
+        if (!Number.isInteger(value) || value <= 0) {
+            throw new UsageError('--keep-transcripts must be a positive integer');
+        }
+        keep = value;
+    }
+    if (options.pi) {
+        const target = piExtensionPath(deps.env, deps.homeDir);
+        const template = await readFile(deps.piTemplatePath, 'utf8');
+        await mkdir(path.dirname(target), { recursive: true });
+        await writeFile(target, renderPiExtension(template, deps.nodePath, deps.scriptPath), 'utf8');
+        return [`installed pi extension ${target}`];
+    }
+    const target = settingsPath({
+        ...(options.settings !== undefined
+            ? { flag: options.settings }
+            : {}),
+        env: deps.env,
+        homeDir: deps.homeDir
+    });
+    let settings = {};
+    try {
+        const text = await readFile(target, 'utf8');
+        const parsed = JSON.parse(text);
+        if (!isRecord(parsed)) {
+            throw new UsageError(`settings file ${target} must contain a JSON object`);
+        }
+        settings = parsed;
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            throw error;
+        }
+        if (!isEnoent(error)) {
+            throw new UsageError(`cannot read settings ${target}: ${error instanceof Error ? error.message : 'read failed'}`);
+        }
+        settings = {};
+    }
+    const next = installHooks(settings, hookCommand(deps.nodePath, deps.scriptPath), keep ?? (options.yes ? null : 365));
+    const diff = unifiedDiff(JSON.stringify(settings, null, 2), JSON.stringify(next, null, 2), target);
+    if (diff !== '') {
+        process.stderr.write(`${diff}\n`);
+    }
+    if (!options.yes) {
+        const confirmed = await deps.confirm(`Write ${target}?`);
+        if (!confirmed) {
+            throw new UsageError('aborted');
+        }
+    }
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    if (!(await deps.hasCredentials())) {
+        process.stderr.write('Warning: ~/.pgmrc has no api_url or api_key; hooks may not inherit PGM_API_*.\n');
+    }
+    return [`installed hooks in ${target}`];
+}
+export async function runHooksUninstall(options, deps) {
+    if (options.pi) {
+        const target = piExtensionPath(deps.env, deps.homeDir);
+        try {
+            await rm(target);
+        }
+        catch (error) {
+            if (!isEnoent(error)) {
+                throw error;
+            }
+        }
+        return [`removed pi extension ${target}`];
+    }
+    const target = settingsPath({
+        ...(options.settings !== undefined
+            ? { flag: options.settings }
+            : {}),
+        env: deps.env,
+        homeDir: deps.homeDir
+    });
+    try {
+        const text = await readFile(target, 'utf8');
+        const parsed = JSON.parse(text);
+        if (!isRecord(parsed)) {
+            throw new UsageError(`settings file ${target} must contain a JSON object`);
+        }
+        await writeFile(target, `${JSON.stringify(uninstallHooks(parsed), null, 2)}\n`, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            throw error;
+        }
+        if (!isEnoent(error)) {
+            throw error;
+        }
+    }
+    return [`removed hooks in ${target}`];
+}
+async function hasCredentials(homeDir) {
+    try {
+        const text = await readFile(path.join(homeDir, '.pgmrc'), 'utf8');
+        const parsed = JSON.parse(text);
+        if (!isRecord(parsed)) {
+            return false;
+        }
+        return (typeof parsed.api_url === 'string' &&
+            parsed.api_url !== '' &&
+            typeof parsed.api_key === 'string' &&
+            parsed.api_key !== '');
+    }
+    catch {
+        return false;
+    }
+}
+function confirmStdin(question) {
+    process.stderr.write(`${question} [y/N] `);
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            terminal: false
+        });
+        let settled = false;
+        const done = (value) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            rl.close();
+            resolve(value);
+        };
+        rl.on('line', (line) => {
+            const answer = line.trim().toLowerCase();
+            done(answer === 'y' || answer === 'yes');
+        });
+        rl.on('close', () => done(false));
+    });
+}
+function realDeps() {
+    const homeDir = os.homedir();
+    return {
+        homeDir,
+        env: process.env,
+        nodePath: process.execPath,
+        scriptPath: realpathSync(process.argv[1] ?? ''),
+        piTemplatePath: fileURLToPath(new URL('../../integrations/pi/postgram.ts', import.meta.url)),
+        confirm: confirmStdin,
+        hasCredentials: () => hasCredentials(homeDir)
+    };
+}
+async function runHooksCommand(command, run) {
+    const json = isJsonMode(command);
+    try {
+        const lines = await run();
+        if (json) {
+            printJson(lines);
+        }
+        else {
+            printHuman(lines);
+        }
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            process.stderr.write(`${error.message}\n`);
+            process.exitCode = 2;
+            return;
+        }
+        await handleCliFailure(error, json);
+    }
+}
+export function registerHooksCommands(program) {
+    const hooks = usageExit(program
+        .command('hooks')
+        .description('Install and remove Postgram agent hooks'));
+    const install = hooks
+        .command('install')
+        .description('Install the Claude Code settings hooks (or the pi extension with --pi)')
+        .option('--settings <path>', 'path to the Claude Code settings file')
+        .option('--yes', 'write without confirming')
+        .option('--keep-transcripts <days>', 'set cleanupPeriodDays to this many days')
+        .option('--pi', 'install only the pi extension');
+    usageExit(install);
+    install.action(async (options, command) => {
+        await runHooksCommand(command, () => runHooksInstall({
+            yes: options.yes === true,
+            pi: options.pi === true,
+            ...(options.settings !== undefined
+                ? { settings: options.settings }
+                : {}),
+            ...(options.keepTranscripts !== undefined
+                ? { keepTranscripts: options.keepTranscripts }
+                : {})
+        }, realDeps()));
+    });
+    const uninstall = hooks
+        .command('uninstall')
+        .description('Remove the Postgram hooks (or the pi extension with --pi)')
+        .option('--settings <path>', 'path to the Claude Code settings file')
+        .option('--pi', 'remove the pi extension');
+    usageExit(uninstall);
+    uninstall.action(async (options, command) => {
+        await runHooksCommand(command, () => runHooksUninstall({
+            pi: options.pi === true,
+            ...(options.settings !== undefined
+                ? { settings: options.settings }
+                : {})
+        }, realDeps()));
+    });
+}