@ivotoby/postgram-cli 1.38.2 → 1.39.0

package/README.md

@@ -121,6 +121,32 @@ provenance, decisions, dependencies, blockers, ownership, involvement,
 discussion participants, connected context, or ambiguous search hits. Do not
 expand when the compact result already answers a direct fact.
 
+## Workspace tracking
+
+Track features, machines, workspaces and agent sessions across worktrees:
+
+```bash
+pgm here                       # report the current workspace and session
+pgm hooks install              # install the Claude Code hooks (--pi installs the pi extension)
+pgm hooks uninstall            # remove the installed hooks
+pgm where                      # features and workspaces grouped by stage
+pgm feature add "my feature"   # create a feature (also: stage, pr, link, unlink)
+pgm machine set --alias codebox # set this machine's alias or connect target (also: pgm machine list)
+pgm repo set <remote> --release-on-merge true|false  # record the repository for this worktree
+pgm worktree new 1234abcd      # create a worktree for a feature (UUID, 8-hex short id or title; --create creates the feature)
+pgm scan --root ~/src          # discover worktrees and record their features (needs --root <dir> or scan_roots; --yes-exact, --dry-run)
+```
+
+New `~/.pgmrc` keys (read alongside `api_url`/`api_key`):
+
+| Key | Default |
+|-----|---------|
+| `machine` | `{ "alias": <hostname>, "connect_target": <alias> }` |
+| `scan_roots` | `[]` |
+| `worktree_root` | `null` (meaning `<repo_root>.worktrees`) |
+| `here_timeout_ms` | `2000` |
+| `resume` | per-agent-kind `with_id`/`without_id` command templates |
+
 ## Memory Roles
 
 Store durable memory:

package/dist/client.js

@@ -12,7 +12,7 @@ function normalizeErrorBody(body) {
     }
     return body;
 }
-async function request(options, path, requestOptions = {}) {
+export async function request(options, path, requestOptions = {}) {
     const headers = {
         Authorization: `Bearer ${options.apiKey}`,
         ...(requestOptions.body === undefined
@@ -28,6 +28,9 @@ async function request(options, path, requestOptions = {}) {
     if (requestOptions.body !== undefined) {
         init.body = JSON.stringify(requestOptions.body);
     }
+    if (requestOptions.signal !== undefined) {
+        init.signal = requestOptions.signal;
+    }
     const response = await fetch(`${options.apiUrl}${path}`, init);
     if (!response.ok) {
         const body = normalizeErrorBody(await parseResponse(response));

package/dist/pgm.js

@@ -8,6 +8,12 @@ import { pipeline } from 'node:stream/promises';
 import { createPgmClient } from './client.js';
 import { handleCliFailure, isJsonMode, parseCommaList, parseJsonObject, printHuman, printJson, readStdinText, resolvePgmConfig, shortId } from './shared.js';
 import { AppError, ErrorCode } from './errors.js';
+import { registerFeatureCommands } from './tracking/feature-commands.js';
+import { registerHereCommand } from './tracking/here.js';
+import { registerHooksCommands } from './tracking/hooks.js';
+import { registerScanCommand } from './tracking/scan.js';
+import { registerWhereCommand } from './tracking/where.js';
+import { registerWorktreeCommand } from './tracking/worktree.js';
 import { buildSyncManifest } from './sync-walk.js';
 import { compactEdgeResponse, compactEntityListResponse, compactGraphResponse, compactSearchResponse, compactStoredEntityResponse, entityListResponseToToon, graphResponseToToon, searchResponseToToon } from './search-output.js';
 function readCliVersion() {
@@ -908,4 +914,10 @@ program
         return lines;
     });
 });
+registerHereCommand(program);
+registerHooksCommands(program);
+registerWhereCommand(program);
+registerFeatureCommands(program);
+registerWorktreeCommand(program);
+registerScanCommand(program);
 await program.parseAsync(process.argv);

package/dist/tracking/api.js

@@ -0,0 +1,139 @@
+// cli/src/tracking/api.ts
+import os from 'node:os';
+import { createPgmClient, request } from '../client.js';
+import { handleCliFailure, isJsonMode, printHuman, printJson, resolvePgmConfig } from '../shared.js';
+import { UsageError, loadTrackingConfig } from './config.js';
+function toQuery(params) {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        query.set(key, value);
+    }
+    const text = query.toString();
+    return text ? `?${text}` : '';
+}
+export function createTrackingClient(options) {
+    return {
+        report(body, reportOptions) {
+            return request(options, '/api/workspaces/report', {
+                method: 'POST',
+                body,
+                ...(reportOptions?.timeoutMs !== undefined
+                    ? { signal: AbortSignal.timeout(reportOptions.timeoutMs) }
+                    : {})
+            });
+        },
+        patchWorkspace(id, body) {
+            return request(options, `/api/workspaces/${encodeURIComponent(id)}`, { method: 'PATCH', body });
+        },
+        putMachine(alias, connectTarget) {
+            return request(options, `/api/machines/${encodeURIComponent(alias)}`, { method: 'PUT', body: { connect_target: connectTarget } });
+        },
+        listMachines() {
+            return request(options, '/api/machines');
+        },
+        putRepository(remote, releaseOnMerge) {
+            return request(options, '/api/repositories', {
+                method: 'PUT',
+                body: { remote, release_on_merge: releaseOnMerge }
+            });
+        },
+        createFeature(input) {
+            return request(options, '/api/features', {
+                method: 'POST',
+                body: input
+            });
+        },
+        setStage(id, stage) {
+            return request(options, `/api/features/${encodeURIComponent(id)}/stage`, { method: 'POST', body: { stage } });
+        },
+        addPullRequest(id, input) {
+            return request(options, `/api/features/${encodeURIComponent(id)}/pull-requests`, {
+                method: 'POST',
+                body: input
+            });
+        },
+        lookup(machine, path) {
+            return request(options, `/api/workspaces/lookup${toQuery({ machine, path })}`);
+        },
+        listWorkspaces(query) {
+            const params = {};
+            if (query.machine !== undefined) {
+                params.machine = query.machine;
+            }
+            if (query.repo !== undefined) {
+                params.repo = query.repo;
+            }
+            if (query.featureId !== undefined) {
+                params.feature_id = query.featureId;
+            }
+            if (query.unassigned) {
+                params.unassigned = 'true';
+            }
+            if (query.includeEnded) {
+                params.include_ended = 'true';
+            }
+            return request(options, `/api/workspaces${toQuery(params)}`);
+        },
+        where(query) {
+            const params = {};
+            if (query.view !== undefined) {
+                params.view = query.view;
+            }
+            if (query.machine !== undefined) {
+                params.machine = query.machine;
+            }
+            if (query.repo !== undefined) {
+                params.repo = query.repo;
+            }
+            if (query.includeReleased) {
+                params.include_released = 'true';
+            }
+            if (query.includeDone) {
+                params.include_done = 'true';
+            }
+            if (query.includeEnded) {
+                params.include_ended = 'true';
+            }
+            return request(options, `/api/where${toQuery(params)}`);
+        }
+    };
+}
+export async function runTrackingCommand(command, handler) {
+    const json = isJsonMode(command);
+    let result;
+    try {
+        const homeDir = os.homedir();
+        const config = await loadTrackingConfig();
+        const credentials = await resolvePgmConfig();
+        result = await handler({
+            json,
+            config,
+            client: createTrackingClient(credentials),
+            pgm: createPgmClient(credentials),
+            homeDir
+        });
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            process.stderr.write(`${error.message}\n`);
+            process.exitCode = 2;
+            return;
+        }
+        await handleCliFailure(error, json);
+        return;
+    }
+    if (result === undefined) {
+        return;
+    }
+    if (Array.isArray(result)) {
+        if (json) {
+            printJson(result);
+        }
+        else {
+            printHuman(result.map(String));
+        }
+    }
+    else {
+        printJson(result);
+    }
+}

package/dist/tracking/config.js

@@ -0,0 +1,148 @@
+// cli/src/tracking/config.ts
+import { chmod, readFile, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { AGENT_KINDS } from './types.js';
+export const DEFAULT_RESUME = {
+    'claude-code': { with_id: 'claude --resume {session_id}', without_id: 'claude' },
+    pi: { with_id: 'pi --session {session_id}', without_id: 'pi' },
+    talon: { with_id: null, without_id: null },
+    other: { with_id: null, without_id: null }
+};
+export class UsageError extends Error {
+}
+export function shq(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+export function slug(title) {
+    return (title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 40)
+        .replace(/-+$/, '') || 'feature');
+}
+export function defaultAlias(hostname) {
+    const head = hostname.toLowerCase().split('.')[0] ?? '';
+    return head.replace(/[^a-z0-9._-]/g, '-') || 'machine';
+}
+export function expandHome(value, homeDir) {
+    if (value === '~') {
+        return homeDir;
+    }
+    if (value.startsWith('~/')) {
+        return path.join(homeDir, value.slice(2));
+    }
+    return value;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value !== '' ? value : null;
+}
+function cloneResume(templates) {
+    const result = {};
+    for (const kind of AGENT_KINDS) {
+        const base = templates[kind];
+        result[kind] = { with_id: base.with_id, without_id: base.without_id };
+    }
+    return result;
+}
+export function parseTrackingConfig(raw, input) {
+    const machine = isRecord(raw) ? (isRecord(raw.machine) ? raw.machine : {}) : {};
+    const alias = nonEmptyString(machine.alias) ?? defaultAlias(input.hostname);
+    const connectTarget = nonEmptyString(machine.connect_target) ?? alias;
+    const scanRoots = [];
+    if (isRecord(raw) && Array.isArray(raw.scan_roots)) {
+        for (const entry of raw.scan_roots) {
+            if (typeof entry === 'string') {
+                scanRoots.push(expandHome(entry, input.homeDir));
+            }
+        }
+    }
+    const worktreeRoot = isRecord(raw) && typeof raw.worktree_root === 'string'
+        ? expandHome(raw.worktree_root, input.homeDir)
+        : null;
+    const timeout = isRecord(raw) ? raw.here_timeout_ms : undefined;
+    const hereTimeoutMs = typeof timeout === 'number' && Number.isFinite(timeout) && timeout > 0
+        ? timeout
+        : 2000;
+    const resume = cloneResume(DEFAULT_RESUME);
+    const rawResume = isRecord(raw) && isRecord(raw.resume) ? raw.resume : {};
+    for (const kind of AGENT_KINDS) {
+        const kindConfig = rawResume[kind];
+        if (!isRecord(kindConfig)) {
+            continue;
+        }
+        if (typeof kindConfig.with_id === 'string' || kindConfig.with_id === null) {
+            resume[kind].with_id = kindConfig.with_id;
+        }
+        if (typeof kindConfig.without_id === 'string' ||
+            kindConfig.without_id === null) {
+            resume[kind].without_id = kindConfig.without_id;
+        }
+    }
+    return { alias, connectTarget, scanRoots, worktreeRoot, hereTimeoutMs, resume };
+}
+export async function loadTrackingConfig(input) {
+    const homeDir = input?.homeDir ?? os.homedir();
+    const hostname = input?.hostname ?? os.hostname();
+    let raw = {};
+    try {
+        const text = await readFile(path.join(homeDir, '.pgmrc'), 'utf8');
+        raw = JSON.parse(text);
+    }
+    catch {
+        raw = {};
+    }
+    return parseTrackingConfig(raw, { homeDir, hostname });
+}
+export async function writeMachineConfig(input) {
+    const homeDir = input.homeDir ?? os.homedir();
+    const rcPath = path.join(homeDir, '.pgmrc');
+    let doc = {};
+    let text = null;
+    try {
+        text = await readFile(rcPath, 'utf8');
+    }
+    catch (error) {
+        const code = error instanceof Error && 'code' in error
+            ? error.code
+            : undefined;
+        if (code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    if (text !== null) {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (error) {
+            throw new UsageError(`~/.pgmrc contains invalid JSON: ${error instanceof Error ? error.message : 'parse failed'}`);
+        }
+        if (!isRecord(parsed)) {
+            throw new UsageError('~/.pgmrc must be a JSON object');
+        }
+        doc = parsed;
+    }
+    const machine = isRecord(doc.machine) ? doc.machine : {};
+    const previousAlias = nonEmptyString(machine.alias);
+    const alias = nonEmptyString(input.alias) ??
+        previousAlias ??
+        defaultAlias(os.hostname());
+    const connectTarget = nonEmptyString(input.connectTarget) ??
+        nonEmptyString(machine.connect_target) ??
+        alias;
+    doc.machine = { ...machine, alias, connect_target: connectTarget };
+    await writeFile(rcPath, `${JSON.stringify(doc, null, 2)}\n`, 'utf8');
+    await chmod(rcPath, 0o600);
+    return { previousAlias, alias, connectTarget };
+}
+export function usageExit(command) {
+    command.exitOverride((error) => {
+        process.exit(error.exitCode === 0 ? 0 : 2);
+    });
+    return command;
+}

package/dist/tracking/feature-commands.js

@@ -0,0 +1,228 @@
+// cli/src/tracking/feature-commands.ts: pgm feature, pgm machine, pgm repo.
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import { AppError, ErrorCode } from '../errors.js';
+import { parseCommaList, shortId } from '../shared.js';
+import { runTrackingCommand } from './api.js';
+import { UsageError, usageExit, writeMachineConfig } from './config.js';
+import { readBootId, removeMarker, resolveLocalWorkspace, writeMarker } from './local.js';
+import { FEATURE_STAGES } from './types.js';
+export async function runFeatureAdd(title, options, deps) {
+    const tags = parseCommaList(options.tags);
+    const response = await deps.client.createFeature({
+        content: title,
+        ...(tags !== undefined ? { tags } : {}),
+        ...(options.visibility !== undefined ? { visibility: options.visibility } : {})
+    });
+    return deps.json ? response : [response.entity.id];
+}
+export async function runFeatureStage(id, stage, deps) {
+    if (!FEATURE_STAGES.includes(stage)) {
+        throw new UsageError(`invalid stage '${stage}'. Use one of: ${FEATURE_STAGES.join(', ')}`);
+    }
+    const response = await deps.client.setStage(id, stage);
+    return deps.json
+        ? response
+        : [`${shortId(response.entity.id)} ${response.previous_stage ?? '-'} → ${stage}`];
+}
+const PR_STATES = ['open', 'merged', 'closed'];
+export async function runFeaturePr(id, url, options, deps) {
+    const state = options.state ?? 'open';
+    if (!PR_STATES.includes(state)) {
+        throw new UsageError(`invalid --state '${state}'. Use one of: ${PR_STATES.join(', ')}`);
+    }
+    const response = await deps.client.addPullRequest(id, {
+        url,
+        state: state
+    });
+    return deps.json
+        ? response
+        : [`${shortId(response.entity.id)} PR ${state}, stage ${response.to}`];
+}
+export async function runFeatureLink(id, options, deps) {
+    if (options.workspace !== undefined) {
+        const patched = await deps.client.patchWorkspace(options.workspace, {
+            feature_id: id
+        });
+        const workspace = patched.workspace;
+        if (workspace.machine === deps.config.alias && deps.exists(workspace.path)) {
+            if (id !== null) {
+                await deps.writeMarker(workspace.path, workspace.feature_id ?? id);
+            }
+            else {
+                await deps.removeMarker(workspace.path);
+            }
+        }
+        else {
+            deps.warn(`warning: ${workspace.machine} may have a feature marker; its next registration will restore the marker's link`);
+        }
+        return deps.json
+            ? patched
+            : [
+                id !== null
+                    ? `linked ${workspace.path} → ${shortId(id)}`
+                    : `unlinked ${workspace.path}`
+            ];
+    }
+    const target = options.path ?? deps.cwd;
+    const local = await deps.resolveWorkspace(target);
+    if (local.kind === 'timeout') {
+        throw new AppError(ErrorCode.INTERNAL, 'git timeout');
+    }
+    const looked = await deps.client.lookup(deps.config.alias, local.path);
+    let workspaceId;
+    if (looked.workspace !== null && looked.workspace.path === local.path) {
+        workspaceId = looked.workspace.id;
+    }
+    else {
+        const report = await deps.client.report({
+            source: 'hook',
+            machine: {
+                alias: deps.config.alias,
+                hostname: deps.hostname,
+                boot_id: await deps.bootId()
+            },
+            workspace: local.workspace
+        });
+        if (report.workspace === null) {
+            throw new AppError(ErrorCode.INTERNAL, 'workspace registration returned no workspace');
+        }
+        workspaceId = report.workspace.id;
+    }
+    const patched = await deps.client.patchWorkspace(workspaceId, {
+        feature_id: id
+    });
+    if (id !== null) {
+        await deps.writeMarker(local.path, patched.workspace.feature_id ?? id);
+    }
+    else {
+        await deps.removeMarker(local.path);
+    }
+    return deps.json
+        ? patched
+        : [
+            id !== null
+                ? `linked ${local.path} → ${shortId(id)}`
+                : `unlinked ${local.path}`
+        ];
+}
+export async function runMachineSet(options, deps) {
+    const written = await deps.writeConfig({
+        ...(options.alias !== undefined ? { alias: options.alias } : {}),
+        ...(options.connect !== undefined ? { connectTarget: options.connect } : {}),
+        homeDir: deps.homeDir
+    });
+    if (written.previousAlias !== null && written.previousAlias !== written.alias) {
+        deps.warn(`warning: history stays under the old alias '${written.previousAlias}'`);
+    }
+    await deps.client.report({
+        source: 'hook',
+        machine: {
+            alias: written.alias,
+            hostname: deps.hostname,
+            boot_id: await deps.bootId()
+        }
+    });
+    const result = await deps.client.putMachine(written.alias, written.connectTarget);
+    return deps.json
+        ? result
+        : [`machine ${written.alias} → ${written.connectTarget}`];
+}
+export async function runMachineList(deps) {
+    const result = await deps.client.listMachines();
+    return deps.json
+        ? result
+        : result.machines.map((machine) => `${machine.alias}  ${machine.connect_target ?? machine.alias}  ${machine.last_seen_at}`);
+}
+export async function runRepoSet(remote, options, deps) {
+    if (options.releaseOnMerge !== 'true' && options.releaseOnMerge !== 'false') {
+        throw new UsageError(`--release-on-merge must be 'true' or 'false'`);
+    }
+    const releaseOnMerge = options.releaseOnMerge === 'true';
+    const result = await deps.client.putRepository(remote, releaseOnMerge);
+    return deps.json ? result : [`${remote} release_on_merge=${releaseOnMerge}`];
+}
+function featureDeps(context) {
+    return {
+        client: context.client,
+        config: context.config,
+        json: context.json,
+        cwd: process.cwd(),
+        hostname: os.hostname(),
+        homeDir: context.homeDir,
+        bootId: readBootId,
+        resolveWorkspace: (cwd) => resolveLocalWorkspace(cwd),
+        writeMarker: (worktree, featureId) => writeMarker(worktree, featureId, new Date()),
+        removeMarker,
+        exists: existsSync,
+        warn: (line) => process.stderr.write(`${line}\n`)
+    };
+}
+export function registerFeatureCommands(program) {
+    const feature = usageExit(program
+        .command('feature')
+        .description('Manage features'));
+    usageExit(feature
+        .command('add')
+        .description('Create a feature')
+        .argument('<title>', 'feature title')
+        .option('--tags <tags>', 'comma-separated tags')
+        .option('--visibility <visibility>', 'personal, work or shared')).action(async (title, options, command) => {
+        await runTrackingCommand(command, (context) => runFeatureAdd(title, options, featureDeps(context)));
+    });
+    usageExit(feature
+        .command('stage')
+        .description('Set a feature stage')
+        .argument('<id>', 'feature id (UUID or 8-hex)')
+        .argument('<stage>', `one of: ${FEATURE_STAGES.join(', ')}`)).action(async (id, stage, _options, command) => {
+        await runTrackingCommand(command, (context) => runFeatureStage(id, stage, featureDeps(context)));
+    });
+    usageExit(feature
+        .command('pr')
+        .description('Attach a pull request to a feature')
+        .argument('<id>', 'feature id (UUID or 8-hex)')
+        .argument('<url>', 'pull request URL')
+        .option('--state <state>', 'open, merged or closed', 'open')).action(async (id, url, options, command) => {
+        await runTrackingCommand(command, (context) => runFeaturePr(id, url, options, featureDeps(context)));
+    });
+    usageExit(feature
+        .command('link')
+        .description('Link a workspace to a feature')
+        .argument('<id>', 'feature id (UUID or 8-hex)')
+        .option('--path <dir>', 'workspace directory (default: cwd)')
+        .option('--workspace <workspace-uuid>', 'link by workspace id instead')).action(async (id, options, command) => {
+        await runTrackingCommand(command, (context) => runFeatureLink(id, options, featureDeps(context)));
+    });
+    usageExit(feature
+        .command('unlink')
+        .description('Unlink a workspace from its feature')
+        .option('--path <dir>', 'workspace directory (default: cwd)')
+        .option('--workspace <workspace-uuid>', 'unlink by workspace id instead')).action(async (options, command) => {
+        await runTrackingCommand(command, (context) => runFeatureLink(null, options, featureDeps(context)));
+    });
+    const machine = usageExit(program
+        .command('machine')
+        .description('Machine settings'));
+    usageExit(machine
+        .command('set')
+        .description('Write ~/.pgmrc and register the machine')
+        .option('--alias <alias>', 'machine alias')
+        .option('--connect <target>', 'connect target')).action(async (options, command) => {
+        await runTrackingCommand(command, (context) => runMachineSet(options, { ...featureDeps(context), writeConfig: writeMachineConfig }));
+    });
+    usageExit(machine
+        .command('list')
+        .description('List machines')).action(async (_options, command) => {
+        await runTrackingCommand(command, (context) => runMachineList(featureDeps(context)));
+    });
+    const repo = usageExit(program
+        .command('repo')
+        .description('Repository settings'));
+    usageExit(repo
+        .command('set')
+        .description('Set repository settings')
+        .argument('<remote>', 'repository remote')
+        .option('--release-on-merge <bool>', 'true or false')).action(async (remote, options, command) => {
+        await runTrackingCommand(command, (context) => runRepoSet(remote, options, featureDeps(context)));
+    });
+}