@ivotoby/postgram-cli 1.38.3 → 1.40.0

package/dist/tracking/scan.js

@@ -0,0 +1,579 @@
+// cli/src/tracking/scan.ts: pgm scan — discover worktrees and record their features.
+import { existsSync } from 'node:fs';
+import { readFile, realpath } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+import { shortId } from '../shared.js';
+import { runTrackingCommand } from './api.js';
+import { expandHome, isIgnoredPath, slug, usageExit, UsageError } from './config.js';
+import { readMarker, resolveLocalWorkspace, runGit, writeMarker } from './local.js';
+import { discoverWorktrees, findClaudeSessions, findPiSessions } from './scan-discovery.js';
+import { syncMissing } from './where.js';
+export const BRANCH_SHORT_ID = /(?:^|\/)([0-9a-f]{8})(?:-|$)/;
+const DEFAULT_DEPTH = 3;
+function parseDepth(raw) {
+    if (raw === undefined) {
+        return DEFAULT_DEPTH;
+    }
+    if (!/^[1-9][0-9]*$/.test(raw)) {
+        throw new UsageError(`invalid --depth '${raw}': must be a positive integer`);
+    }
+    return Number.parseInt(raw, 10);
+}
+function withoutFeatPrefix(branch) {
+    return branch.startsWith('feat/') ? branch.slice('feat/'.length) : branch;
+}
+function newFeatureTitle(branch, dirName) {
+    if (branch === null || branch === '') {
+        return dirName;
+    }
+    return withoutFeatPrefix(branch).replaceAll('-', ' ');
+}
+async function buildProposals(worktree, deps, tasks, yesExact) {
+    const proposals = [];
+    const titleFor = (id) => tasks.find((task) => task.id === id)?.title ?? '';
+    const marker = await deps.readMarker(worktree.path);
+    if (marker !== null) {
+        proposals.push({ kind: 'marker', featureId: marker, title: titleFor(marker) });
+    }
+    if (worktree.branch !== null) {
+        const match = BRANCH_SHORT_ID.exec(worktree.branch);
+        const short = match?.[1];
+        if (short !== undefined) {
+            const hits = tasks.filter((task) => task.id.startsWith(short));
+            if (hits.length === 1) {
+                const hit = hits[0];
+                if (hit !== undefined) {
+                    proposals.push({ kind: 'short-id', featureId: hit.id, title: hit.title });
+                }
+            }
+        }
+        if (!yesExact) {
+            let hits = [];
+            try {
+                hits = await deps.search(slug(withoutFeatPrefix(worktree.branch)));
+            }
+            catch {
+                hits = [];
+            }
+            for (const hit of hits.slice(0, 3)) {
+                proposals.push({ kind: 'search', featureId: hit.id, title: hit.title });
+            }
+        }
+    }
+    return proposals;
+}
+function sessionsFor(worktree, claude, pi) {
+    return [
+        ...(claude.get(worktree.path) ?? []),
+        ...(pi.get(worktree.path) ?? [])
+    ];
+}
+function scanRoots(options, deps) {
+    const roots = options.root.length > 0
+        ? options.root.map((root) => path.resolve(root))
+        : deps.config.scanRoots;
+    if (roots.length === 0) {
+        throw new UsageError('no scan roots: pass --root <dir> or set scan_roots in ~/.pgmrc');
+    }
+    return roots;
+}
+async function discoverNotIgnored(roots, depth, deps) {
+    const worktrees = await deps.discover(roots, depth);
+    return worktrees.filter((worktree) => !isIgnoredPath(worktree.path, deps.config.ignorePaths));
+}
+async function findSessions(paths, deps) {
+    const claudeDir = deps.env.CLAUDE_CONFIG_DIR ?? path.join(deps.homeDir, '.claude');
+    const piDir = deps.env.PI_CODING_AGENT_DIR ?? path.join(deps.homeDir, '.pi', 'agent');
+    const claude = await deps.claudeSessions(paths, claudeDir);
+    for (const note of claude.notes) {
+        deps.info(note);
+    }
+    const pi = await deps.piSessions(paths, piDir);
+    return { claude: claude.sessions, pi };
+}
+async function recordLocal(local, featureId, sessions, deps) {
+    const body = {
+        source: 'scan',
+        machine: {
+            alias: deps.config.alias,
+            hostname: deps.hostname,
+            boot_id: null
+        },
+        workspace: local.workspace,
+        feature_id: featureId,
+        sessions
+    };
+    await deps.client.report(body);
+    if ((await deps.readMarker(local.path)) !== featureId) {
+        await deps.writeMarker(local.path, featureId);
+    }
+}
+export async function runScan(options, deps) {
+    if (!options.yesExact && !deps.isTty()) {
+        throw new UsageError('pgm scan needs a terminal for its interactive flow. Without one, use `pgm scan --json` to list worktrees, `pgm scan --apply <plan.json>` to apply a plan, or `pgm scan --yes-exact`.');
+    }
+    const roots = scanRoots(options, deps);
+    const depth = parseDepth(options.depth);
+    const knownResponse = await deps.client.listWorkspaces({
+        machine: deps.config.alias
+    });
+    if (!options.dryRun) {
+        await syncMissing(knownResponse.workspaces, {
+            localAlias: deps.config.alias,
+            exists: deps.exists,
+            patch: (id, missing) => deps.client.patchWorkspace(id, { missing })
+        });
+    }
+    const known = new Set(knownResponse.workspaces.map((workspace) => workspace.path));
+    const worktrees = await discoverNotIgnored(roots, depth, deps);
+    const { claude, pi } = await findSessions(worktrees.map((worktree) => worktree.path), deps);
+    const tasks = await deps.tasks();
+    const lines = [];
+    for (const worktree of worktrees) {
+        if (known.has(worktree.path)) {
+            lines.push(`known ${worktree.path}`);
+            continue;
+        }
+        const proposals = await buildProposals(worktree, deps, tasks, options.yesExact);
+        let featureId = null;
+        if (options.yesExact) {
+            const first = proposals[0];
+            if (first !== undefined &&
+                (first.kind === 'marker' || first.kind === 'short-id')) {
+                featureId = first.featureId;
+            }
+            else {
+                lines.push(`skipped ${worktree.path}`);
+                continue;
+            }
+        }
+        else {
+            deps.info(`${worktree.path}${worktree.branch !== null ? ` (${worktree.branch})` : ''}`);
+            proposals.forEach((proposal, index) => {
+                deps.info(`  ${index + 1}. ${proposal.kind}: ${proposal.title !== '' ? proposal.title : proposal.featureId}`);
+            });
+            const answer = (await deps.ask('[a]ccept, [1-3] pick, [n]ew feature, [s]kip'))
+                .trim()
+                .toLowerCase();
+            if (answer === 'a') {
+                const first = proposals[0];
+                if (first !== undefined) {
+                    featureId = first.featureId;
+                }
+            }
+            else if (/^[1-9]$/.test(answer)) {
+                const picked = proposals[Number.parseInt(answer, 10) - 1];
+                if (picked !== undefined) {
+                    featureId = picked.featureId;
+                }
+            }
+            else if (answer === 'n') {
+                const created = await deps.client.createFeature({
+                    content: newFeatureTitle(worktree.branch, path.basename(worktree.path))
+                });
+                featureId = created.entity.id;
+            }
+            if (featureId === null) {
+                lines.push(`skipped ${worktree.path}`);
+                continue;
+            }
+        }
+        const id = featureId;
+        if (options.dryRun) {
+            lines.push(`would record ${worktree.path} → ${shortId(id)}`);
+            continue;
+        }
+        const local = await deps.resolveWorkspace(worktree.path);
+        if (local.kind === 'timeout') {
+            lines.push(`skipped ${worktree.path} (git timeout)`);
+            continue;
+        }
+        await recordLocal(local, id, sessionsFor(worktree, claude, pi), deps);
+        lines.push(`recorded ${worktree.path} → ${shortId(id)}`);
+    }
+    return lines;
+}
+const INVENTORY_CONCURRENCY = 6;
+function sessionSummary(sessions) {
+    if (sessions.length === 0) {
+        return null;
+    }
+    let latest = '';
+    for (const session of sessions) {
+        const observed = session.observed_at ?? '';
+        if (observed > latest) {
+            latest = observed;
+        }
+    }
+    return { count: sessions.length, last_activity_at: latest };
+}
+/** Read-only: lists what is on disk and what Postgram knows. Sends nothing. */
+export async function runScanInventory(options, deps) {
+    const roots = scanRoots(options, deps);
+    const depth = parseDepth(options.depth);
+    const known = new Map((await deps.client.listWorkspaces({ machine: deps.config.alias })).workspaces.map((workspace) => [workspace.path, workspace]));
+    const worktrees = await discoverNotIgnored(roots, depth, deps);
+    const { claude, pi } = await findSessions(worktrees.map((worktree) => worktree.path), deps);
+    const tasks = await deps.tasks();
+    const titleFor = (id) => tasks.find((task) => task.id === id)?.title ?? '';
+    const describe = async (worktree) => {
+        const [local, lastCommit] = await Promise.all([
+            deps.resolveWorkspace(worktree.path),
+            deps.lastCommit(worktree.path)
+        ]);
+        const workspace = known.get(worktree.path) ?? null;
+        const linkedId = workspace?.feature_id ?? null;
+        const marker = await deps.readMarker(worktree.path);
+        const candidates = (linkedId === null
+            ? await buildProposals(worktree, deps, tasks, false)
+            : []).map((proposal) => ({
+            kind: proposal.kind,
+            feature_id: proposal.featureId,
+            title: proposal.title
+        }));
+        const entry = {
+            path: worktree.path,
+            repo_remote: local.kind === 'ok'
+                ? (local.workspace.repo_remote ?? workspace?.repo_remote ?? null)
+                : (workspace?.repo_remote ?? null),
+            branch: local.kind === 'ok'
+                ? (local.workspace.branch ?? worktree.branch)
+                : worktree.branch,
+            last_commit: lastCommit,
+            git: local.kind === 'ok' ? (local.workspace.git ?? null) : null,
+            workspace_id: workspace?.id ?? null,
+            feature: linkedId !== null ? { id: linkedId, title: titleFor(linkedId) } : null,
+            marker_feature_id: marker,
+            sessions: sessionSummary(sessionsFor(worktree, claude, pi)),
+            candidates
+        };
+        if (local.kind === 'timeout') {
+            entry.note = 'git timeout';
+        }
+        return entry;
+    };
+    const entries = [];
+    for (let i = 0; i < worktrees.length; i += INVENTORY_CONCURRENCY) {
+        entries.push(...(await Promise.all(worktrees.slice(i, i + INVENTORY_CONCURRENCY).map(describe))));
+    }
+    return {
+        machine: deps.config.alias,
+        generated_at: new Date().toISOString(),
+        roots,
+        worktrees: entries
+    };
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SHORT_ID_RE = /^[0-9a-f]{8}$/i;
+function isRecordValue(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function resolveTaskId(raw, tasks) {
+    const lower = raw.toLowerCase();
+    let hits = [];
+    if (UUID_RE.test(lower)) {
+        hits = tasks.filter((task) => task.id === lower);
+    }
+    else if (SHORT_ID_RE.test(lower)) {
+        hits = tasks.filter((task) => task.id.startsWith(lower));
+    }
+    const hit = hits[0];
+    if (hit === undefined) {
+        return { error: `no feature matches ${raw}` };
+    }
+    if (hits.length > 1) {
+        return { error: `feature id ${raw} is ambiguous` };
+    }
+    return { id: hit.id };
+}
+/** Validates the whole plan; nothing is written while this runs. */
+async function validatePlan(plan, deps) {
+    const rawEntries = Array.isArray(plan)
+        ? plan
+        : isRecordValue(plan) && Array.isArray(plan.entries)
+            ? plan.entries
+            : null;
+    if (rawEntries === null) {
+        throw new UsageError('plan must be {"entries": [...]} or a JSON array of entries');
+    }
+    const tasks = await deps.tasks();
+    const errors = [];
+    const valid = [];
+    const seen = new Set();
+    for (const [index, raw] of rawEntries.entries()) {
+        if (!isRecordValue(raw) || typeof raw.path !== 'string' || raw.path === '') {
+            errors.push(`entry ${index + 1}: path is required`);
+            continue;
+        }
+        const expanded = expandHome(raw.path, deps.homeDir);
+        if (!path.isAbsolute(expanded)) {
+            errors.push(`${raw.path}: path must be absolute`);
+            continue;
+        }
+        const target = path.resolve(expanded);
+        if (seen.has(target)) {
+            errors.push(`duplicate path ${target}`);
+            continue;
+        }
+        seen.add(target);
+        const action = raw.action;
+        if (action === 'skip') {
+            valid.push({ entry: { path: target, action: 'skip' } });
+            continue;
+        }
+        let item;
+        if (action === 'link') {
+            if (typeof raw.feature_id !== 'string' || raw.feature_id === '') {
+                errors.push(`${target}: link needs feature_id`);
+                continue;
+            }
+            const resolved = resolveTaskId(raw.feature_id, tasks);
+            if ('error' in resolved) {
+                errors.push(`${target}: ${resolved.error}`);
+                continue;
+            }
+            item = {
+                entry: { path: target, action: 'link', feature_id: raw.feature_id },
+                featureId: resolved.id
+            };
+        }
+        else if (action === 'create') {
+            const title = typeof raw.title === 'string' ? raw.title.trim() : '';
+            if (title === '') {
+                errors.push(`${target}: create needs a non-empty title`);
+                continue;
+            }
+            item = { entry: { path: target, action: 'create', title } };
+        }
+        else {
+            errors.push(`${target}: unknown action '${String(action)}'`);
+            continue;
+        }
+        if (isIgnoredPath(target, deps.config.ignorePaths)) {
+            errors.push(`${target}: path is in ignore_paths`);
+            continue;
+        }
+        if (!deps.exists(target)) {
+            errors.push(`${target}: path does not exist`);
+            continue;
+        }
+        const local = await deps.resolveWorkspace(target);
+        if (local.kind === 'timeout') {
+            errors.push(`${target}: git timed out`);
+            continue;
+        }
+        if (local.repoRoot === null) {
+            errors.push(`${target}: not a git worktree`);
+            continue;
+        }
+        if (local.path !== (await deps.realpath(target))) {
+            errors.push(`${target}: not the root of a worktree (${local.path})`);
+            continue;
+        }
+        if (isIgnoredPath(local.path, deps.config.ignorePaths)) {
+            errors.push(`${target}: path is in ignore_paths`);
+            continue;
+        }
+        valid.push({ ...item, local });
+    }
+    if (errors.length > 0) {
+        throw new UsageError(`plan rejected, nothing was written:\n${errors.map((line) => `  ${line}`).join('\n')}`);
+    }
+    return valid;
+}
+export async function runScanApply(plan, options, deps) {
+    const valid = await validatePlan(plan, deps);
+    const paths = valid
+        .filter((item) => item.entry.action !== 'skip')
+        .map((item) => item.entry.path);
+    const sessions = options.dryRun || paths.length === 0
+        ? { claude: new Map(), pi: new Map() }
+        : await findSessions(paths, deps);
+    const results = [];
+    for (const item of valid) {
+        const { entry } = item;
+        if (entry.action === 'skip') {
+            results.push({ path: entry.path, action: 'skip', status: 'skipped' });
+            continue;
+        }
+        if (options.dryRun) {
+            results.push({
+                path: entry.path,
+                action: entry.action,
+                status: entry.action === 'link' ? 'would link' : 'would create',
+                ...(item.featureId !== undefined ? { feature_id: item.featureId } : {})
+            });
+            continue;
+        }
+        let featureId = item.featureId;
+        try {
+            if (entry.action === 'create') {
+                const created = await deps.client.createFeature({ content: entry.title });
+                featureId = created.entity.id;
+            }
+            if (featureId === undefined || item.local === undefined) {
+                throw new Error('internal: unresolved plan entry');
+            }
+            await recordLocal(item.local, featureId, sessionsFor({ path: entry.path, branch: null }, sessions.claude, sessions.pi), deps);
+            results.push({
+                path: entry.path,
+                action: entry.action,
+                status: entry.action === 'link' ? 'linked' : 'created',
+                feature_id: featureId
+            });
+        }
+        catch (error) {
+            results.push({
+                path: entry.path,
+                action: entry.action,
+                status: 'failed',
+                ...(featureId !== undefined ? { feature_id: featureId } : {}),
+                error: error instanceof Error ? error.message : 'unknown error'
+            });
+        }
+    }
+    return {
+        results,
+        failed: results.filter((result) => result.status === 'failed').length
+    };
+}
+export function formatApplyResults(results) {
+    return results.map((result) => {
+        const target = result.feature_id !== undefined ? ` → ${shortId(result.feature_id)}` : '';
+        if (result.status === 'failed') {
+            return `failed ${result.path}${target}: ${result.error ?? 'unknown error'}`;
+        }
+        return `${result.status} ${result.path}${target}`;
+    });
+}
+function firstLineTitle(content) {
+    return (content ?? '').split('\n')[0]?.trim() ?? '';
+}
+function collectRoot(value, previous) {
+    return [...previous, value];
+}
+function askLine(question) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stderr
+        });
+        const finish = (answer) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            rl.close();
+            resolve(answer.trim());
+        };
+        rl.question(question, (answer) => finish(answer));
+        rl.on('close', () => finish(''));
+        rl.on('SIGINT', () => finish(''));
+    });
+}
+async function readPlan(file) {
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        throw new UsageError(`cannot read plan ${file}: ${error instanceof Error ? error.message : 'read failed'}`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new UsageError(`plan ${file} is not valid JSON: ${error instanceof Error ? error.message : 'parse failed'}`);
+    }
+}
+export function registerScanCommand(program) {
+    const command = usageExit(program
+        .command('scan')
+        .description('Discover worktrees under the scan roots and record their features')
+        .option('--root <dir>', 'scan root (repeatable)', collectRoot, [])
+        .option('--depth <n>', `directory depth below each root (default ${DEFAULT_DEPTH})`)
+        .option('--yes-exact', 'accept marker and short-id proposals, skip the rest')
+        .option('--dry-run', 'show what would be recorded without sending')
+        .option('--apply <plan.json>', 'apply an approved plan (link, create or skip per worktree path)')).action(async () => {
+        const opts = command.opts();
+        await runTrackingCommand(command, async (context) => {
+            const scanOptions = {
+                root: opts.root ?? [],
+                ...(opts.depth !== undefined ? { depth: opts.depth } : {}),
+                yesExact: opts.yesExact === true,
+                dryRun: opts.dryRun === true
+            };
+            if (opts.apply !== undefined && scanOptions.yesExact) {
+                throw new UsageError('--apply cannot be combined with --yes-exact');
+            }
+            const deps = {
+                client: context.client,
+                config: context.config,
+                hostname: os.hostname(),
+                env: process.env,
+                homeDir: context.homeDir,
+                tasks: async () => {
+                    const items = [];
+                    for (let offset = 0;; offset += 100) {
+                        const page = await context.pgm.listTasks({ limit: 100, offset });
+                        for (const item of page.items) {
+                            items.push({ id: item.id, title: firstLineTitle(item.content) });
+                        }
+                        if (page.items.length < 100) {
+                            break;
+                        }
+                    }
+                    return items;
+                },
+                search: async (query) => {
+                    const response = await context.pgm.searchEntities({
+                        query,
+                        type: 'task',
+                        limit: 3
+                    });
+                    return response.results.map((result) => ({
+                        id: result.entity.id,
+                        title: firstLineTitle(result.entity.content)
+                    }));
+                },
+                ask: askLine,
+                discover: discoverWorktrees,
+                claudeSessions: findClaudeSessions,
+                piSessions: findPiSessions,
+                resolveWorkspace: (p) => resolveLocalWorkspace(p),
+                readMarker,
+                writeMarker: (worktree, featureId) => writeMarker(worktree, featureId, new Date()),
+                exists: existsSync,
+                isTty: () => process.stdin.isTTY === true,
+                realpath: (p) => realpath(p),
+                lastCommit: async (worktree) => {
+                    const result = await runGit(['log', '-1', '--format=%cI%n%s'], {
+                        cwd: worktree,
+                        timeoutMs: 5000
+                    });
+                    if (!result.ok || result.stdout === '') {
+                        return null;
+                    }
+                    const [date = '', ...subject] = result.stdout.split('\n');
+                    return { date, subject: subject.join('\n') };
+                },
+                info: (line) => process.stderr.write(`${line}\n`)
+            };
+            if (opts.apply !== undefined) {
+                const plan = await readPlan(opts.apply);
+                const applied = await runScanApply(plan, { dryRun: scanOptions.dryRun }, deps);
+                if (applied.failed > 0) {
+                    process.exitCode = 1;
+                }
+                return context.json ? applied : formatApplyResults(applied.results);
+            }
+            if (context.json && !scanOptions.yesExact) {
+                return runScanInventory(scanOptions, deps);
+            }
+            return runScan(scanOptions, deps);
+        });
+    });
+}

package/dist/tracking/types.js

@@ -0,0 +1,14 @@
+export const AGENT_KINDS = [
+    'claude-code',
+    'pi',
+    'talon',
+    'other'
+];
+export const FEATURE_STAGES = [
+    'building',
+    'review',
+    'functional_test',
+    'ready_to_merge',
+    'awaiting_release',
+    'released'
+];