@ivotoby/postgram-cli 1.39.0 → 1.40.1

package/dist/tracking/scan.js

@@ -1,15 +1,26 @@
 // 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 { slug, usageExit, UsageError } from './config.js';
-import { readMarker, resolveLocalWorkspace, writeMarker } from './local.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})(?:-|$)/;
+/** Keeps the feature tasks of a task listing, so plain tasks are never offered or linked. */
+export function featureTasks(items) {
+    return items
+        .filter((item) => item.metadata.kind === 'feature')
+        .map((item) => ({
+        id: item.id,
+        title: firstLineTitle(item.content),
+        done: item.status === 'done'
+    }));
+}
 const DEFAULT_DEPTH = 3;
 function parseDepth(raw) {
     if (raw === undefined) {
@@ -56,7 +67,9 @@ async function buildProposals(worktree, deps, tasks, yesExact) {
             catch {
                 hits = [];
             }
-            for (const hit of hits.slice(0, 3)) {
+            // Search covers every task; only open features are worth proposing.
+            const open = new Set(tasks.filter((task) => task.done !== true).map((task) => task.id));
+            for (const hit of hits.filter((h) => open.has(h.id)).slice(0, 3)) {
                 proposals.push({ kind: 'search', featureId: hit.id, title: hit.title });
             }
         }
@@ -69,13 +82,51 @@ function sessionsFor(worktree, claude, pi) {
         ...(pi.get(worktree.path) ?? [])
     ];
 }
-export async function runScan(options, deps) {
+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
@@ -88,15 +139,8 @@ export async function runScan(options, deps) {
         });
     }
     const known = new Set(knownResponse.workspaces.map((workspace) => workspace.path));
-    const worktrees = await deps.discover(roots, depth);
-    const paths = worktrees.map((worktree) => worktree.path);
-    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);
+    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) {
@@ -158,25 +202,264 @@ export async function runScan(options, deps) {
             lines.push(`skipped ${worktree.path} (git timeout)`);
             continue;
         }
-        const body = {
-            source: 'scan',
-            machine: {
-                alias: deps.config.alias,
-                hostname: deps.hostname,
-                boot_id: null
-            },
-            workspace: local.workspace,
-            feature_id: id,
-            sessions: sessionsFor(worktree, claude.sessions, pi)
-        };
-        await deps.client.report(body);
-        if ((await deps.readMarker(worktree.path)) !== id) {
-            await deps.writeMarker(worktree.path, id);
-        }
+        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() ?? '';
 }
@@ -203,6 +486,21 @@ function askLine(question) {
         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')
@@ -210,52 +508,82 @@ export function registerScanCommand(program) {
         .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')).action(async () => {
+        .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, (context) => runScan({
-            root: opts.root ?? [],
-            ...(opts.depth !== undefined ? { depth: opts.depth } : {}),
-            yesExact: opts.yesExact === true,
-            dryRun: opts.dryRun === true
-        }, {
-            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) });
+        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 });
+                        items.push(...featureTasks(page.items));
+                        if (page.items.length < 100) {
+                            break;
+                        }
                     }
-                    if (page.items.length < 100) {
-                        break;
+                    return items;
+                },
+                search: async (query) => {
+                    const response = await context.pgm.searchEntities({
+                        query,
+                        type: 'task',
+                        limit: 10
+                    });
+                    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 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,
-            info: (line) => process.stderr.write(`${line}\n`)
-        }));
+                return context.json ? applied : formatApplyResults(applied.results);
+            }
+            if (context.json && !scanOptions.yesExact) {
+                return runScanInventory(scanOptions, deps);
+            }
+            return runScan(scanOptions, deps);
+        });
     });
 }