@ivotoby/postgram-cli 1.38.3 → 1.40.0

package/README.md

@@ -121,6 +121,94 @@ 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.
+For onboarding and daily use, see [docs/workspace-tracking.md](../docs/workspace-tracking.md).
+
+```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, one summary per feature (--expand lists every workspace, --all includes done and released)
+pgm feature add "my feature"   # create a feature (also: stage, pr, link, unlink)
+pgm feature done 1234abcd      # mark the feature task done; pgm where hides it unless --all
+pgm feature sync [1234abcd]    # update PR states from GitHub with gh and apply the stage rules
+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)
+pgm scan --json                # read-only inventory for agents: one entry per worktree, nothing is sent
+pgm scan --apply plan.json     # apply an approved plan (--dry-run validates and shows the result only)
+pgm worktree rm <path>         # remove a clean, pushed worktree and unregister it (no force flag)
+pgm workspace prune            # remove registrations of this machine whose directory is gone (--dry-run, --ignored)
+```
+
+The interactive `pgm scan` needs a terminal. Without one it exits with a
+message that points to `--json`, `--apply` and `--yes-exact`.
+
+### Scan inventory and plan
+
+`pgm scan --json` prints:
+
+```json
+{
+  "machine": "codebox",
+  "generated_at": "2026-11-01T10:00:00.000Z",
+  "roots": ["/home/me/workspace"],
+  "worktrees": [
+    {
+      "path": "/home/me/workspace/app.worktrees/1a2b3c4d-kw-rank",
+      "repo_remote": "git@github.com:owner/app.git",
+      "branch": "feat/1a2b3c4d-kw-rank",
+      "last_commit": { "date": "2026-10-30T09:12:00+00:00", "subject": "fix: ranking" },
+      "git": { "dirty_count": 0, "unpushed_count": 1, "has_upstream": true },
+      "workspace_id": null,
+      "feature": null,
+      "marker_feature_id": null,
+      "sessions": { "count": 2, "last_activity_at": "2026-10-30T10:00:00.000Z" },
+      "candidates": [
+        { "kind": "short-id", "feature_id": "1a2b3c4d-...", "title": "Keyword rank fusion" }
+      ]
+    }
+  ]
+}
+```
+
+`feature` is the link Postgram already has. `candidates` (marker, short-id,
+search) are only computed for worktrees without a link. `git` is `null` when
+git timed out (then `note` says so).
+
+`pgm scan --apply plan.json` takes one entry per worktree path:
+
+```json
+{
+  "entries": [
+    { "path": "/home/me/workspace/app.worktrees/1a2b3c4d-kw-rank", "action": "link", "feature_id": "1a2b3c4d" },
+    { "path": "/home/me/workspace/app.worktrees/spike", "action": "create", "title": "Spike: new cache" },
+    { "path": "/home/me/workspace/app.worktrees/old", "action": "skip" }
+  ]
+}
+```
+
+The whole plan is validated before anything is written: paths must be
+absolute, unique, existing worktree roots outside `ignore_paths`; `link` needs
+a feature id (UUID or 8-hex) that exists; `create` needs a title. One invalid
+entry rejects the plan. Entries then run one by one and the result lists
+`linked`, `created`, `skipped` or `failed` per path (exit code 1 when any
+failed). With `--json` the result is `{ "results": [...], "failed": n }`.
+
+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` |
+| `ignore_paths` | `[]`. Directories `pgm here`, the hooks and `pgm scan` skip. An entry matches that directory exactly; an entry ending in `/**` matches everything below it. `~` is expanded. Example: `["~/workspace"]` skips the workspace root but not the repos in it. |
+| `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,13 @@ 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 { registerWorkspaceCommands } from './tracking/workspace-commands.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 +915,11 @@ program
         return lines;
     });
 });
+registerHereCommand(program);
+registerHooksCommands(program);
+registerWhereCommand(program);
+registerFeatureCommands(program);
+registerWorktreeCommand(program);
+registerScanCommand(program);
+registerWorkspaceCommands(program);
 await program.parseAsync(process.argv);

package/dist/tracking/api.js

@@ -0,0 +1,142 @@
+// 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 });
+        },
+        deleteWorkspace(id) {
+            return request(options, `/api/workspaces/${encodeURIComponent(id)}`, { method: 'DELETE' });
+        },
+        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,181 @@
+// 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 trimTrailingSlashes(value) {
+    return value.length > 1 ? value.replace(/\/+$/, '') || '/' : value;
+}
+/**
+ * An entry matches that directory exactly. An entry ending in `/**` matches
+ * everything below the directory, but not the directory itself.
+ */
+export function isIgnoredPath(target, ignorePaths) {
+    const candidate = trimTrailingSlashes(target);
+    return ignorePaths.some((entry) => {
+        if (entry.endsWith('/**')) {
+            const base = trimTrailingSlashes(entry.slice(0, -3));
+            return candidate.startsWith(base === '/' ? '/' : `${base}/`);
+        }
+        return candidate === trimTrailingSlashes(entry);
+    });
+}
+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 ignorePaths = [];
+    if (isRecord(raw) && Array.isArray(raw.ignore_paths)) {
+        for (const entry of raw.ignore_paths) {
+            if (typeof entry === 'string' && entry !== '') {
+                ignorePaths.push(expandHome(entry, input.homeDir));
+            }
+        }
+    }
+    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,
+        ignorePaths,
+        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;
+}