@ivotoby/postgram-cli 1.38.3 → 1.40.0

package/dist/tracking/feature-commands.js

@@ -0,0 +1,298 @@
+// 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 { formatSync, runFeatureSync, runGhPrState } from './feature-sync.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 FULL_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SHORT_HEX = /^[0-9a-f]{8}$/i;
+async function resolveTaskId(id, deps) {
+    if (FULL_UUID.test(id)) {
+        return id.toLowerCase();
+    }
+    if (!SHORT_HEX.test(id)) {
+        throw new UsageError('feature id must be a full UUID or an 8-hex short id');
+    }
+    const prefix = id.toLowerCase();
+    const matches = [];
+    for (let offset = 0;; offset += 100) {
+        const page = await deps.pgm.listTasks({ limit: 100, offset });
+        for (const item of page.items) {
+            if (item.id.startsWith(prefix)) {
+                matches.push(item.id);
+            }
+        }
+        if (page.items.length < 100) {
+            break;
+        }
+    }
+    if (matches.length > 1) {
+        throw new AppError(ErrorCode.CONFLICT, `feature id ${id} is ambiguous`);
+    }
+    const [match] = matches;
+    if (match === undefined) {
+        throw new AppError(ErrorCode.NOT_FOUND, `no feature matches ${id}`);
+    }
+    return match;
+}
+/**
+ * Marks the feature's task done. `pgm where` already hides done tasks unless
+ * --all is given, so a feature needs no stage of its own for this.
+ */
+export async function runFeatureDone(id, deps) {
+    const taskId = await resolveTaskId(id, deps);
+    const current = await deps.pgm.recallEntity(taskId);
+    if (current.entity.status === 'done') {
+        return deps.json
+            ? { id: taskId, status: 'done', changed: false }
+            : [`${shortId(taskId)} already done`];
+    }
+    const completed = await deps.pgm.completeTask(taskId, current.entity.version);
+    return deps.json
+        ? { id: taskId, status: completed.entity.status, changed: true }
+        : [`${shortId(taskId)} done`];
+}
+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('done')
+        .description('Mark a feature done so pgm where hides it (pgm where --all shows it)')
+        .argument('<id>', 'feature id (UUID or 8-hex)')).action(async (id, _options, command) => {
+        await runTrackingCommand(command, (context) => runFeatureDone(id, { pgm: context.pgm, json: context.json }));
+    });
+    usageExit(feature
+        .command('sync')
+        .description('Update PR states from GitHub (needs gh) and apply the stage rules')
+        .argument('[id]', 'only this feature (UUID or 8-hex)')).action(async (id, _options, command) => {
+        await runTrackingCommand(command, async (context) => {
+            const result = await runFeatureSync(id, {
+                client: context.client,
+                gh: (url) => runGhPrState(url)
+            });
+            if (result.errors.length > 0) {
+                process.exitCode = 1;
+            }
+            return context.json ? result : formatSync(result);
+        });
+    });
+    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)));
+    });
+}

package/dist/tracking/feature-sync.js

@@ -0,0 +1,151 @@
+// cli/src/tracking/feature-sync.ts: pgm feature sync — follow GitHub PR state.
+import { execFile } from 'node:child_process';
+import { AppError, ErrorCode } from '../errors.js';
+import { shortId } from '../shared.js';
+import { UsageError } from './config.js';
+const GH_STATES = {
+    OPEN: 'open',
+    MERGED: 'merged',
+    CLOSED: 'closed'
+};
+export function parseGhState(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    const state = parsed.state;
+    return typeof state === 'string' ? (GH_STATES[state] ?? null) : null;
+}
+export function classifyGhFailure(error) {
+    const stderr = error.stderr ?? '';
+    if (error.code === 'ENOENT') {
+        return { ok: false, kind: 'missing', message: 'gh is not installed' };
+    }
+    if (/gh auth login|not logged in|not logged into|authentication/i.test(stderr)) {
+        return { ok: false, kind: 'unauthenticated', message: 'gh is not logged in' };
+    }
+    const first = stderr.split('\n').find((line) => line.trim() !== '');
+    return { ok: false, kind: 'error', message: first?.trim() ?? 'gh failed' };
+}
+const defaultExec = (cmd, args) => new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: 20_000 }, (error, stdout, stderr) => {
+        if (error !== null) {
+            reject(Object.assign(error, { stderr }));
+        }
+        else {
+            resolve({ stdout });
+        }
+    });
+});
+export async function runGhPrState(url, exec = defaultExec) {
+    let stdout;
+    try {
+        ({ stdout } = await exec('gh', ['pr', 'view', url, '--json', 'state']));
+    }
+    catch (error) {
+        const failure = error;
+        return classifyGhFailure({ code: failure.code, stderr: failure.stderr });
+    }
+    const state = parseGhState(stdout);
+    return state === null
+        ? { ok: false, kind: 'error', message: 'unexpected output from gh pr view' }
+        : { ok: true, state };
+}
+function collectFeatures(response) {
+    const features = [];
+    for (const group of response.groups) {
+        if ('features' in group) {
+            features.push(...group.features);
+        }
+    }
+    return features;
+}
+/**
+ * Asks gh for the state of every PR that is not merged yet and sends changes
+ * through the feature PR endpoint, so the server's derived-stage rules apply.
+ * A merged PR is final and is not asked again.
+ */
+export async function runFeatureSync(id, deps) {
+    const response = await deps.client.where(id === undefined
+        ? { view: 'stage' }
+        : { view: 'stage', includeReleased: true, includeDone: true });
+    let features = collectFeatures(response);
+    if (id !== undefined) {
+        const wanted = id.toLowerCase();
+        features = features.filter((feature) => feature.id === wanted || feature.id.startsWith(wanted));
+        if (features.length === 0) {
+            throw new AppError(ErrorCode.NOT_FOUND, `no feature matches ${id}`);
+        }
+    }
+    const result = { checked: 0, unchanged: 0, changed: [], errors: [] };
+    const answers = new Map();
+    for (const feature of features) {
+        for (const pull of feature.pull_requests) {
+            if (pull.state === 'merged') {
+                continue;
+            }
+            let answer = answers.get(pull.url);
+            if (answer === undefined) {
+                answer = await deps.gh(pull.url);
+                answers.set(pull.url, answer);
+            }
+            if (!answer.ok && answer.kind === 'missing') {
+                throw new UsageError('gh (GitHub CLI) was not found on PATH. Install it from https://cli.github.com to use `pgm feature sync`.');
+            }
+            if (!answer.ok && answer.kind === 'unauthenticated') {
+                throw new UsageError('gh is not logged in. Run `gh auth login`, then retry `pgm feature sync`.');
+            }
+            result.checked += 1;
+            if (!answer.ok) {
+                result.errors.push({
+                    feature_id: feature.id,
+                    url: pull.url,
+                    error: answer.message
+                });
+                continue;
+            }
+            if (answer.state === pull.state) {
+                result.unchanged += 1;
+                continue;
+            }
+            try {
+                const updated = await deps.client.addPullRequest(feature.id, {
+                    url: pull.url,
+                    state: answer.state
+                });
+                result.changed.push({
+                    feature_id: feature.id,
+                    url: pull.url,
+                    from: pull.state,
+                    to: answer.state,
+                    stage_from: updated.from,
+                    stage_to: updated.to
+                });
+            }
+            catch (error) {
+                result.errors.push({
+                    feature_id: feature.id,
+                    url: pull.url,
+                    error: error instanceof Error ? error.message : 'update failed'
+                });
+            }
+        }
+    }
+    return result;
+}
+export function formatSync(result) {
+    const lines = result.changed.map((change) => `${shortId(change.feature_id)} ${change.url} ${change.from} → ${change.to}${change.stage_from !== change.stage_to
+        ? `, stage ${change.stage_from} → ${change.stage_to}`
+        : ''}`);
+    for (const error of result.errors) {
+        lines.push(`error ${shortId(error.feature_id)} ${error.url}: ${error.error}`);
+    }
+    lines.push(`checked ${result.checked} pull requests: ${result.changed.length} changed, ${result.unchanged} unchanged, ${result.errors.length} failed`);
+    return lines;
+}