orizu 0.4.0 → 0.5.0

package/dist/workbench-cli.js

@@ -0,0 +1,493 @@
+/**
+ * Workspace session/run visibility commands (ALI-902 CLI half).
+ *
+ * Pure logic + injected HTTP: command functions do not parse process.argv and
+ * do not print. The thin `workbenchCommand` entry point owns CLI argument
+ * parsing and human/JSON output.
+ */
+import { authedFetch } from './http.js';
+import { getWorkspaceRoot } from './workspace.js';
+import { attachedWorkspaceId, stringOrNull } from './workspace-sync.js';
+const TERMINAL_RUN_STATUSES = new Set(['succeeded', 'failed', 'cancelled']);
+const SESSION_STATUSES = new Set(['active', 'ended']);
+const DEFAULT_TAIL_LIMIT = 100;
+const MAX_TAIL_LIMIT = 500;
+const DEFAULT_TAIL_INTERVAL_SECONDS = 2;
+// Floor for the continuous poll sleep so `--interval 0` (or negatives) cannot
+// hot-spin against the API while a non-terminal run is quiet. Draining full
+// pages intentionally skips the sleep — that is catch-up, not polling.
+const MIN_TAIL_INTERVAL_MS = 500;
+function defaultSleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function numberOrFallback(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+function normalizeTailLimit(limit) {
+    return typeof limit === 'number' && Number.isFinite(limit) && limit > 0
+        ? Math.min(Math.floor(limit), MAX_TAIL_LIMIT)
+        : DEFAULT_TAIL_LIMIT;
+}
+function normalizeProjectSlug(value) {
+    const raw = stringOrNull(value);
+    if (!raw) {
+        return null;
+    }
+    const segments = raw.split('/').map(segment => segment.trim()).filter(Boolean);
+    return segments.length > 0 ? segments[segments.length - 1] : null;
+}
+function resolveAttachedWorkspaceId(opts) {
+    const explicit = stringOrNull(opts.workspaceId ?? undefined);
+    if (explicit) {
+        return explicit;
+    }
+    const root = getWorkspaceRoot(opts.cwd);
+    const attached = attachedWorkspaceId(root);
+    if (!attached) {
+        throw new Error('This workspace is not attached yet; run `orizu workspace sync` first to attach it.');
+    }
+    return attached;
+}
+async function readJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return {};
+    }
+}
+async function responseMessage(response) {
+    try {
+        const data = await response.clone().json();
+        return stringOrNull(data.error) || stringOrNull(data.message) || response.statusText || String(response.status);
+    }
+    catch {
+        try {
+            const text = await response.text();
+            return text.trim() || response.statusText || String(response.status);
+        }
+        catch {
+            return response.statusText || String(response.status);
+        }
+    }
+}
+async function assertOk(response, action) {
+    if (response.ok) {
+        return;
+    }
+    throw new Error(`${action} failed (${response.status}): ${await responseMessage(response)}`);
+}
+function fetcherFrom(opts) {
+    return opts.fetcher ?? authedFetch;
+}
+function requiredBodyObject(data, key, action) {
+    const value = data[key];
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`${action} response did not include ${key}`);
+    }
+    return value;
+}
+function sessionFrom(data, action) {
+    return requiredBodyObject(data, 'session', action);
+}
+function runFrom(data, action) {
+    return requiredBodyObject(data, 'run', action);
+}
+function sessionsFrom(data) {
+    return Array.isArray(data.sessions) ? data.sessions : [];
+}
+function eventsFrom(data) {
+    return Array.isArray(data.events) ? data.events : [];
+}
+export async function runSessionStart(opts = {}) {
+    const fetcher = fetcherFrom(opts);
+    const workspaceId = resolveAttachedWorkspaceId(opts);
+    const projectSlug = normalizeProjectSlug(opts.projectSlug);
+    const body = {};
+    if (projectSlug) {
+        body.projectSlug = projectSlug;
+    }
+    if (opts.clientInfo) {
+        body.clientInfo = opts.clientInfo;
+    }
+    const response = await fetcher(`/api/cli/workspaces/${encodeURIComponent(workspaceId)}/sessions`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    await assertOk(response, 'Session start');
+    const data = await readJson(response);
+    return { session: sessionFrom(data, 'Session start') };
+}
+export async function runSessionStatus(opts = {}) {
+    const fetcher = fetcherFrom(opts);
+    const sessionId = stringOrNull(opts.sessionId ?? undefined);
+    if (sessionId) {
+        const response = await fetcher(`/api/cli/sessions/${encodeURIComponent(sessionId)}`);
+        await assertOk(response, 'Session status');
+        const data = await readJson(response);
+        return { session: sessionFrom(data, 'Session status') };
+    }
+    const workspaceId = resolveAttachedWorkspaceId(opts);
+    const status = stringOrNull(opts.status ?? undefined);
+    const query = status ? `?status=${encodeURIComponent(status)}` : '';
+    const response = await fetcher(`/api/cli/workspaces/${encodeURIComponent(workspaceId)}/sessions${query}`);
+    await assertOk(response, 'Session status');
+    const data = await readJson(response);
+    return { sessions: sessionsFrom(data) };
+}
+export async function runSessionEnd(opts) {
+    const fetcher = fetcherFrom(opts);
+    if (!stringOrNull(opts.sessionId)) {
+        throw new Error('Usage: orizu session end --session <id> [--json]');
+    }
+    const response = await fetcher(`/api/cli/sessions/${encodeURIComponent(opts.sessionId)}`, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ status: 'ended' }),
+    });
+    await assertOk(response, 'Session end');
+    const data = await readJson(response);
+    return {
+        session: sessionFrom(data, 'Session end'),
+        branchStatus: stringOrNull(data.branchStatus) ?? undefined,
+    };
+}
+export async function runSessionFinish(opts) {
+    const fetcher = fetcherFrom(opts);
+    if (!stringOrNull(opts.sessionId)) {
+        throw new Error('Usage: orizu session finish --session <id> [--project <team/project>] [--json]');
+    }
+    const body = {};
+    const projectSlug = normalizeProjectSlug(opts.projectSlug);
+    if (projectSlug) {
+        body.projectSlug = projectSlug;
+    }
+    const response = await fetcher(`/api/cli/sessions/${encodeURIComponent(opts.sessionId)}/finish-branch`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    await assertOk(response, 'Session finish');
+    const data = await readJson(response);
+    const manifest = data.manifest && typeof data.manifest === 'object' && !Array.isArray(data.manifest)
+        ? data.manifest
+        : undefined;
+    return {
+        outcome: stringOrNull(data.outcome) || 'unknown',
+        branch: stringOrNull(data.branch) ?? undefined,
+        branchDeleted: typeof data.branchDeleted === 'boolean' ? data.branchDeleted : undefined,
+        manifest,
+    };
+}
+export async function runWorkbenchRunStart(opts) {
+    const fetcher = fetcherFrom(opts);
+    if (!stringOrNull(opts.sessionId) || !stringOrNull(opts.title)) {
+        throw new Error('Usage: orizu run start --session <id> --title <title> [--project <team/project>] [--json]');
+    }
+    const projectSlug = normalizeProjectSlug(opts.projectSlug);
+    const body = {
+        workspaceSessionId: opts.sessionId,
+        title: opts.title,
+    };
+    if (projectSlug) {
+        body.projectSlug = projectSlug;
+    }
+    const response = await fetcher('/api/cli/workbench-runs', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 409) {
+        // PR #1284 contract: starting a run on an ended session is a 409.
+        const message = await responseMessage(response);
+        const hint = /ended/i.test(message) ? ' Run `orizu session start` to open a new session.' : '';
+        throw new Error(`Run start failed (409): ${message}${hint}`);
+    }
+    await assertOk(response, 'Run start');
+    const data = await readJson(response);
+    return { run: runFrom(data, 'Run start') };
+}
+export async function runWorkbenchRunStatus(opts) {
+    const fetcher = fetcherFrom(opts);
+    if (!stringOrNull(opts.runId)) {
+        throw new Error('Usage: orizu run status --run <id> [--json]');
+    }
+    const response = await fetcher(`/api/cli/workbench-runs/${encodeURIComponent(opts.runId)}`);
+    await assertOk(response, 'Run status');
+    const data = await readJson(response);
+    return { run: runFrom(data, 'Run status') };
+}
+export async function runWorkbenchRunTerminal(opts) {
+    const fetcher = fetcherFrom(opts);
+    if (!stringOrNull(opts.runId) || !TERMINAL_RUN_STATUSES.has(opts.status)) {
+        throw new Error('Usage: orizu run <complete|fail|cancel> --run <id> [--summary <text>] [--json]');
+    }
+    const body = { status: opts.status };
+    if (opts.summary) {
+        body.summary = { note: opts.summary };
+    }
+    if (opts.evidence) {
+        body.evidence = opts.evidence;
+    }
+    const response = await fetcher(`/api/cli/workbench-runs/${encodeURIComponent(opts.runId)}`, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 409) {
+        // PR #1284 contract: "Run already <status>" names the STORED status when a
+        // different terminal status was requested — report it plus a status hint.
+        const message = await responseMessage(response);
+        const alreadyMatch = /^Run already (\S+)/.exec(message);
+        if (alreadyMatch) {
+            throw new Error(`Run update rejected (409): run is already '${alreadyMatch[1]}' (requested '${opts.status}'). Check \`orizu run status --run ${opts.runId}\`.`);
+        }
+        throw new Error(`Run update failed (409): ${message}`);
+    }
+    await assertOk(response, 'Run update');
+    const data = await readJson(response);
+    return { run: runFrom(data, 'Run update') };
+}
+export async function tailOnce(fetcher, runId, cursor, limit = DEFAULT_TAIL_LIMIT) {
+    // The API requires an integer cursor: only send back whole non-negative
+    // sequences (PR #1284 contract — non-numeric/negative `after` is a 400).
+    const safeCursor = Number.isFinite(cursor) && cursor > 0 ? Math.floor(cursor) : 0;
+    const safeLimit = normalizeTailLimit(limit);
+    const response = await fetcher(`/api/cli/workbench-runs/${encodeURIComponent(runId)}/events?after=${safeCursor}&limit=${safeLimit}`);
+    await assertOk(response, 'Run tail');
+    const data = await readJson(response);
+    return {
+        events: eventsFrom(data),
+        cursor: numberOrFallback(data.cursor, safeCursor),
+        runStatus: stringOrNull(data.runStatus) || 'unknown',
+    };
+}
+export async function tailWorkbenchRun(opts) {
+    const fetcher = fetcherFrom(opts);
+    if (!stringOrNull(opts.runId)) {
+        throw new Error('Usage: orizu run tail --run <id> [--after <seq>] [--interval <seconds>] [--once] [--json]  (--once drains all currently persisted events, then exits without following)');
+    }
+    const sleep = opts.sleep ?? defaultSleep;
+    let cursor = typeof opts.after === 'number' && Number.isFinite(opts.after) && opts.after > 0 ? Math.floor(opts.after) : 0;
+    const intervalMs = Math.max(MIN_TAIL_INTERVAL_MS, Math.round((opts.intervalSeconds ?? DEFAULT_TAIL_INTERVAL_SECONDS) * 1000));
+    const pageLimit = normalizeTailLimit(opts.limit);
+    while (true) {
+        const previousCursor = cursor;
+        const result = await tailOnce(fetcher, opts.runId, cursor, opts.limit);
+        cursor = result.cursor;
+        for (const event of result.events) {
+            opts.onEvent?.(event);
+        }
+        // A full page means more events may already be persisted — keep draining
+        // back-to-back (no sleep). Exit conditions are only evaluated on a SHORT
+        // page: a terminal runStatus on a full page would otherwise truncate a
+        // completed run that has more unread pages.
+        if (result.events.length >= pageLimit) {
+            // Protocol invariant: a full page always implies the server advanced
+            // the cursor past what we asked for. If it didn't, draining back-to-back
+            // would spin hot forever on a misbehaving/stalled server. We pick the
+            // simpler of the two acceptable fixes (apply the normal poll sleep
+            // before retrying, rather than failing after one retry) because it
+            // matches this loop's existing backoff-on-no-progress shape (see the
+            // MIN_TAIL_INTERVAL_MS floor above) without introducing a new
+            // retry-count/error path.
+            if (cursor > previousCursor) {
+                continue;
+            }
+            await sleep(intervalMs);
+            continue;
+        }
+        if (opts.once || TERMINAL_RUN_STATUSES.has(result.runStatus)) {
+            return result;
+        }
+        await sleep(intervalMs);
+    }
+}
+function hasFlag(args, flag) {
+    return args.includes(flag);
+}
+function argValue(args, flag) {
+    const index = args.indexOf(flag);
+    if (index === -1 || index + 1 >= args.length || args[index + 1].startsWith('--')) {
+        return null;
+    }
+    return args[index + 1];
+}
+function numberArg(args, flag) {
+    const raw = argValue(args, flag);
+    if (!raw) {
+        return undefined;
+    }
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function positionalArgs(args) {
+    const values = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg.startsWith('--')) {
+            if (argValue(args, arg) !== null) {
+                i += 1;
+            }
+            continue;
+        }
+        values.push(arg);
+    }
+    return values;
+}
+function emit(io, human, payload) {
+    io.print(io.json ? JSON.stringify(payload) : human);
+}
+function formatSessionStatus(result) {
+    if (result.session) {
+        const lines = [`session ${result.session.id}  ${result.session.status}`];
+        for (const run of result.session.runs ?? []) {
+            lines.push(`  run ${run.id}  ${run.status}`);
+        }
+        return lines.join('\n');
+    }
+    const sessions = result.sessions ?? [];
+    return ['workspace sessions', ...sessions.map(session => `${session.id}  ${session.status}`)].join('\n');
+}
+function formatSessionFinish(result) {
+    if (result.outcome === 'no-changes') {
+        const branch = result.branch ?? 'the session branch';
+        return result.branchDeleted === false
+            ? `no changes on ${branch}; branch NOT deleted (delete it manually or retry \`orizu session finish\`)`
+            : `no changes on ${branch}; branch deleted`;
+    }
+    const manifest = result.manifest ?? {};
+    const id = typeof manifest.id === 'string' ? manifest.id : '(unknown)';
+    const status = typeof manifest.status === 'string' ? manifest.status : '(unknown)';
+    const proposed = (manifest.proposedState ?? {});
+    const files = typeof proposed.filesChanged === 'number' ? proposed.filesChanged : 0;
+    const additions = typeof proposed.additions === 'number' ? proposed.additions : 0;
+    const deletions = typeof proposed.deletions === 'number' ? proposed.deletions : 0;
+    return `manifest ${id}  ${status}  repo_merge  (${files} files, +${additions}/-${deletions})`;
+}
+function formatRunStatus(run) {
+    const sequence = typeof run.latestSequence === 'number' ? `  latestSequence=${run.latestSequence}` : '';
+    return `run ${run.id}  ${run.status}${sequence}`;
+}
+function formatEventLine(event) {
+    const payload = event.payload && Object.keys(event.payload).length > 0 ? ` ${JSON.stringify(event.payload)}` : '';
+    return `${event.sequence} ${event.eventType}${payload}`;
+}
+function terminalStatusForCommand(command) {
+    if (command === 'complete')
+        return 'succeeded';
+    if (command === 'fail')
+        return 'failed';
+    if (command === 'cancel')
+        return 'cancelled';
+    return null;
+}
+const USAGE_LINE = 'Usage: orizu session <start|status|end|finish> ... | orizu run <start|status|tail|complete|fail|cancel> ...  (run tail --once drains all currently persisted events, then exits without following)';
+// In --json mode ANY command failure — bad usage, or an operational failure
+// such as a 401/403/404/409/network error surfaced by assertOk — must still
+// land as a single machine-readable document (`{"error": ...}`) on stdout,
+// never human help text and never a plain-text message on stderr. An agent
+// parsing --json stdout should never have to also watch stderr for the most
+// common failure modes. Non-JSON mode is unchanged: the message prints as-is.
+// Stack traces are never printed either way (only `error.message`).
+function emitJsonError(io, message) {
+    io.print(io.json ? JSON.stringify({ error: message }) : message);
+    return 1;
+}
+export async function workbenchCommand(args, io) {
+    try {
+        return await dispatchWorkbenchCommand(args, io);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (io.json) {
+            return emitJsonError(io, message);
+        }
+        throw error;
+    }
+}
+async function dispatchWorkbenchCommand(args, io) {
+    const positional = positionalArgs(args);
+    const group = positional[0];
+    const subcommand = positional[1];
+    const fetcher = io.fetcher;
+    if (group === 'session') {
+        if (subcommand === 'start') {
+            const result = await runSessionStart({
+                fetcher,
+                projectSlug: argValue(args, '--project'),
+                clientInfo: { source: 'orizu-cli' },
+            });
+            emit(io, `session started: ${result.session.id}`, result);
+            return 0;
+        }
+        if (subcommand === 'status') {
+            const status = argValue(args, '--status');
+            if (status && !SESSION_STATUSES.has(status)) {
+                throw new Error('Usage: orizu session status [--session <id> | --status active|ended] [--json]');
+            }
+            const result = await runSessionStatus({ fetcher, sessionId: argValue(args, '--session'), status });
+            emit(io, formatSessionStatus(result), result);
+            return 0;
+        }
+        if (subcommand === 'end') {
+            const result = await runSessionEnd({ fetcher, sessionId: argValue(args, '--session') || '' });
+            const hint = result.branchStatus === 'has-changes'
+                ? '\nsession branch has changes — run `orizu session finish --session ' + result.session.id + '` to promote them'
+                : '';
+            emit(io, `session ended: ${result.session.id}${hint}`, result);
+            return 0;
+        }
+        if (subcommand === 'finish') {
+            const result = await runSessionFinish({
+                fetcher,
+                sessionId: argValue(args, '--session') || '',
+                projectSlug: argValue(args, '--project'),
+            });
+            emit(io, formatSessionFinish(result), result);
+            return 0;
+        }
+    }
+    if (group === 'run') {
+        if (subcommand === 'start') {
+            const result = await runWorkbenchRunStart({
+                fetcher,
+                sessionId: argValue(args, '--session') || '',
+                title: argValue(args, '--title') || '',
+                projectSlug: argValue(args, '--project'),
+            });
+            emit(io, `run started: ${result.run.id}`, result);
+            return 0;
+        }
+        if (subcommand === 'status') {
+            const result = await runWorkbenchRunStatus({ fetcher, runId: argValue(args, '--run') || '' });
+            emit(io, formatRunStatus(result.run), result);
+            return 0;
+        }
+        if (subcommand === 'tail') {
+            await tailWorkbenchRun({
+                fetcher,
+                runId: argValue(args, '--run') || '',
+                after: numberArg(args, '--after'),
+                intervalSeconds: numberArg(args, '--interval'),
+                once: hasFlag(args, '--once'),
+                sleep: io.sleep,
+                onEvent: event => io.print(io.json ? JSON.stringify(event) : formatEventLine(event)),
+            });
+            return 0;
+        }
+        const status = terminalStatusForCommand(subcommand || '');
+        if (status) {
+            const result = await runWorkbenchRunTerminal({
+                fetcher,
+                runId: argValue(args, '--run') || '',
+                status,
+                summary: argValue(args, '--summary'),
+            });
+            emit(io, formatRunStatus(result.run), result);
+            return 0;
+        }
+    }
+    return emitJsonError(io, USAGE_LINE);
+}