@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5682

package/dist/home/version-log.js

@@ -0,0 +1,216 @@
+import { createHash } from 'node:crypto';
+import { linkSync, readFileSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+import { registryCount } from './registry-content.js';
+import { assertHomePath } from './boundary.js';
+import { atomicTmpPath, replacePrivate, syncDirectory } from './private-files.js';
+const hashSchema = z.string().regex(/^[a-f0-9]{64}$/).nullable();
+const versionSchema = z.object({ hash: hashSchema });
+const acceptedSchema = versionSchema.extend({ empty: z.boolean().optional() });
+const outsideSchema = z.object({ restoreHash: hashSchema, observedHash: hashSchema, detectedAt: z.iso.datetime() });
+const resetSchema = outsideSchema.extend({ pending: z.boolean().optional() });
+export const OUTSIDE_WRITE_ENFORCEMENT = true;
+export function readBytes(path) {
+    try {
+        return readFileSync(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+export function digest(bytes) {
+    return bytes === null ? null : createHash('sha256').update(bytes).digest('hex');
+}
+/** A journal belongs to the root that owns the live file, independent of runtime/env paths. */
+export class VersionLog {
+    root;
+    relativePath;
+    privacy;
+    directory;
+    /** Report-only journals run the same interpretation and keep every record change in memory. */
+    overlay;
+    constructor(root, relativePath, privacy = {}, reportOnly = false) {
+        this.root = root;
+        this.relativePath = relativePath;
+        this.privacy = privacy;
+        this.directory = join(root, '.versions', relativePath);
+        if (reportOnly)
+            this.overlay = new Map();
+    }
+    readEntry(name) {
+        if (this.overlay?.has(name))
+            return this.overlay.get(name);
+        return readBytes(join(this.directory, name));
+    }
+    writeEntry(name, bytes) {
+        if (this.overlay)
+            this.overlay.set(name, bytes);
+        else if (bytes !== null)
+            replacePrivate(join(this.directory, name), bytes, this.privacy);
+        else {
+            rmSync(join(this.directory, name), { force: true });
+            syncDirectory(this.directory);
+        }
+    }
+    assertWritable() {
+        if (this.overlay)
+            throw new Error(`Report-only HomeStore journal cannot replace ${this.relativePath}`);
+    }
+    record(name) {
+        const bytes = this.readEntry(name);
+        return bytes === null ? undefined : JSON.parse(bytes.toString('utf8'));
+    }
+    setRecord(name, record) {
+        this.writeEntry(name, Buffer.from(`${JSON.stringify(record)}\n`));
+    }
+    store(bytes) {
+        const hash = digest(bytes);
+        if (bytes !== null)
+            this.writeEntry(hash, bytes);
+        return hash;
+    }
+    clearPending() {
+        this.writeEntry('PENDING', null);
+    }
+    /** Caller owns write.lock. Seed old installs without changing even one live byte. */
+    inspect(bytes) {
+        const record = this.record('HEAD');
+        if (record === undefined) {
+            this.setRecord('HEAD', { hash: this.store(bytes) });
+            return;
+        }
+        const head = versionSchema.parse(record).hash;
+        const actual = digest(bytes);
+        const pendingRecord = this.record('PENDING');
+        const pending = pendingRecord === undefined ? undefined : versionSchema.parse(pendingRecord);
+        if (pending && (actual === pending.hash || actual === head)) {
+            // Old bytes: crash before replacement. New bytes: crash after replacement. Both are ours.
+            if (actual === pending.hash)
+                this.setRecord('HEAD', { hash: pending.hash });
+            this.clearPending();
+        }
+        else if (actual !== head) {
+            if (this.record('OUTSIDE') === undefined)
+                this.setRecord('OUTSIDE', {
+                    restoreHash: head, observedHash: actual, detectedAt: new Date().toISOString(),
+                });
+        }
+        return this.outside();
+    }
+    outside() {
+        const record = this.record('OUTSIDE');
+        return record === undefined ? undefined : outsideSchema.parse(record);
+    }
+    /** Crash-safe journal order: durable bytes, PENDING, replace, HEAD, clear PENDING. */
+    replace(path, bytes) {
+        this.assertWritable();
+        const hash = this.store(bytes);
+        this.setRecord('PENDING', { hash });
+        if (bytes === null) {
+            rmSync(path, { force: true });
+            // Removing an already absent file must also work before its parent directory exists.
+            try {
+                syncDirectory(dirname(path));
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        else
+            replacePrivate(path, bytes, this.privacy);
+        this.setRecord('HEAD', { hash });
+        this.clearPending();
+    }
+    /** Install locks must also exclude older binaries, which create their lock with wx. */
+    createExclusive(path, bytes) {
+        this.assertWritable();
+        const hash = this.store(bytes);
+        this.setRecord('PENDING', { hash });
+        const stage = atomicTmpPath(path);
+        try {
+            replacePrivate(stage, bytes, this.privacy);
+            linkSync(stage, path);
+            syncDirectory(dirname(path));
+            this.setRecord('HEAD', { hash });
+            this.clearPending();
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                this.clearPending();
+            throw error;
+        }
+        finally {
+            rmSync(stage, { force: true });
+        }
+    }
+    reset() {
+        const record = this.record('RESET');
+        if (record === undefined)
+            return;
+        const reset = resetSchema.parse(record);
+        // A crash before replacement must not turn an unchanged registry into a reset.
+        if (reset.pending) {
+            if (versionSchema.parse(this.record('HEAD')).hash !== reset.observedHash)
+                return;
+            this.setRecord('RESET', { ...reset, pending: false });
+        }
+        return reset;
+    }
+    flagReset(previous, observed, pending = false) {
+        if (this.reset())
+            return;
+        this.setRecord('RESET', { restoreHash: this.store(previous), observedHash: digest(observed), detectedAt: new Date().toISOString(), pending });
+    }
+    accepted(bytes) {
+        const record = this.record('ACCEPTED');
+        if (record === undefined)
+            return false;
+        const accepted = acceptedSchema.parse(record);
+        return accepted.hash === digest(bytes) || (accepted.empty === true && registryCount(this.relativePath, bytes) === 0);
+    }
+    /** Migration retains an operator's exact acceptance, never pending writes or recovery flags. */
+    copyAcceptanceFrom(source, bytes) {
+        assertHomePath(source.root, join(source.directory, 'ACCEPTED'));
+        const record = source.record('ACCEPTED');
+        const accepted = record === undefined ? undefined : acceptedSchema.parse(record);
+        if (accepted && accepted.hash === digest(bytes))
+            this.setRecord('ACCEPTED', accepted);
+        else
+            this.writeEntry('ACCEPTED', null);
+    }
+    /** Resolve without rewriting the operator's bytes or changing their mtime. */
+    accept(path) {
+        const bytes = readBytes(path);
+        this.setRecord('HEAD', { hash: this.store(bytes) });
+        this.clearPending();
+        this.clearRecovery(bytes);
+    }
+    clearRecovery(bytes, keepReset = false) {
+        this.assertWritable();
+        // Record acceptance before clearing flags: an empty accepted registry must not re-alert.
+        if (!keepReset)
+            this.setRecord('ACCEPTED', { hash: digest(bytes), empty: registryCount(this.relativePath, bytes) === 0 });
+        for (const name of keepReset ? ['OUTSIDE'] : ['OUTSIDE', 'RESET'])
+            rmSync(join(this.directory, name), { force: true });
+        syncDirectory(this.directory);
+    }
+    recoveryBytes(flag) {
+        const bytes = flag.restoreHash === null ? null : this.readEntry(flag.restoreHash);
+        if (digest(bytes) !== flag.restoreHash)
+            throw new Error(`Missing or corrupt pinned HomeStore version: ${this.relativePath}`);
+        return bytes;
+    }
+    restore(path) {
+        const outside = this.outside();
+        if (!outside)
+            return;
+        const bytes = this.recoveryBytes(outside);
+        this.replace(path, bytes);
+        this.clearRecovery(bytes);
+    }
+}
+//# sourceMappingURL=version-log.js.map

package/dist/home/version-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-log.js","sourceRoot":"","sources":["../../src/home/version-log.ts"],"names":[],"mappings":"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"}

package/dist/home/write-lock.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Short per-root lock, using atomic Lamport bakery claims in write.lock/. Unlike a shared
+ * stale pid file, unique claims cannot be stolen by two simultaneous stale-lock reclaimers.
+ * The callback is synchronous: no task in this process can wait on a lock across an await.
+ */
+export declare function withHomeLock<T>(root: string, operation: () => T): T;

package/dist/home/write-lock.js

@@ -0,0 +1,96 @@
+import { randomUUID } from 'node:crypto';
+import { readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { processStartToken, recordedProcessLive } from '../delegation/process-liveness.js';
+import { privateDirectory } from './private-files.js';
+import { ownProcessStartToken } from './process-identity.js';
+import { assertHomeMetadata, assertHomePath } from './boundary.js';
+const held = new Set();
+const pause = new Int32Array(new SharedArrayBuffer(4));
+/** Claims need atomic visibility, not persistence. A crash makes the recorded owner stale. */
+function publishClaim(path, claim) {
+    const stage = `${path}.tmp`;
+    try {
+        writeFileSync(stage, JSON.stringify(claim), { flag: 'wx', mode: 0o600 });
+        renameSync(stage, path);
+    }
+    finally {
+        rmSync(stage, { force: true });
+    }
+}
+/** Bound recovery after PID reuse when either side cannot supply a start token. */
+function unconfirmedClaimExpired(mtimeMs, claim) {
+    if (Date.now() - mtimeMs <= 30_000)
+        return false;
+    return claim.startToken === undefined || processStartToken(claim.pid) === undefined;
+}
+function readClaim(path) {
+    let value;
+    let mtimeMs;
+    try {
+        value = JSON.parse(readFileSync(path, 'utf8'));
+        mtimeMs = statSync(path).mtimeMs;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (!Number.isSafeInteger(value.pid) || value.pid <= 0 || !Number.isSafeInteger(value.ticket) || value.ticket < 0) {
+        throw new Error(`Invalid HomeStore lock claim: ${path}`);
+    }
+    if (recordedProcessLive(value) && !unconfirmedClaimExpired(mtimeMs, value))
+        return value;
+    // A unique claim name cannot be reused by a later owner. Recovery never unlinks its lock.
+    rmSync(path, { force: true });
+    return;
+}
+/**
+ * Short per-root lock, using atomic Lamport bakery claims in write.lock/. Unlike a shared
+ * stale pid file, unique claims cannot be stolen by two simultaneous stale-lock reclaimers.
+ * The callback is synchronous: no task in this process can wait on a lock across an await.
+ */
+export function withHomeLock(root, operation) {
+    const canonical = assertHomePath(root, root);
+    if (held.has(canonical))
+        return operation();
+    assertHomeMetadata(root);
+    privateDirectory(root);
+    const directory = join(canonical, '.locks', 'write.lock');
+    privateDirectory(directory);
+    const name = `${process.pid}-${randomUUID()}.json`;
+    const path = join(directory, name);
+    const claim = { pid: process.pid, startToken: ownProcessStartToken(), ticket: 0 };
+    const peers = () => readdirSync(directory).filter(entry => entry.endsWith('.json') && entry !== name);
+    try {
+        publishClaim(path, claim);
+        let ticket = 1;
+        for (const entry of peers())
+            ticket = Math.max(ticket, (readClaim(join(directory, entry))?.ticket ?? 0) + 1);
+        claim.ticket = ticket;
+        publishClaim(path, claim);
+        const deadline = Date.now() + 10_000;
+        for (;;) {
+            const blocked = peers().some(entry => {
+                const peer = readClaim(join(directory, entry));
+                return peer && (peer.ticket === 0 || peer.ticket < ticket || (peer.ticket === ticket && entry < name));
+            });
+            if (!blocked)
+                break;
+            if (Date.now() >= deadline)
+                throw new Error(`Timed out waiting for HomeStore write.lock in ${root}`);
+            Atomics.wait(pause, 0, 0, 10);
+        }
+        held.add(canonical);
+        try {
+            return operation();
+        }
+        finally {
+            held.delete(canonical);
+        }
+    }
+    finally {
+        rmSync(path, { force: true });
+    }
+}
+//# sourceMappingURL=write-lock.js.map

package/dist/home/write-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-lock.js","sourceRoot":"","sources":["../../src/home/write-lock.ts"],"names":[],"mappings":"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"}

package/dist/hsq.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import './index.ts';

package/dist/hsq.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import './index.js';
+//# sourceMappingURL=hsq.js.map

package/dist/hsq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hsq.js","sourceRoot":"","sources":["../src/hsq.ts"],"names":[],"mappings":";AACA,OAAO,YAAY,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { logPrefix } from './home/display.js';
+import { projectPaths } from './project-paths.js';
+import { commandText } from './home/command.js';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { RunStore } from './runs/store.js';
+import { RunStoreOpenError } from './runs/store-open-error.js';
+import { initCommand, openStore } from './project-commands.js';
+import { warnLegacyEnv } from './home/deprecation.js';
+import { resolveHome } from './home/resolve.js';
+import { runMigrations } from './workspace/migrations.js';
+import { registerProject, shouldRegisterProject } from './workspace/projects.js';
+import { main, defaultCliDeps } from './cli-dispatch.js';
+import { serverCommand } from './server-command.js';
+import { runHeadless, defaultHeadlessDeps } from './headless-run.js';
+import { serveCommand, defaultServeDeps } from './serve-command.js';
+import { onTerminal } from './serve-listener.js';
+warnLegacyEnv(process.env);
+// ---- workspace boot ----------------------------------------------------------
+/**
+ * Boot-time workspace bookkeeping (spec 2026-07-20-multi-project-workspace,
+ * "Boot flow"): run pending `~/.cezar` migrations first, then register the
+ * boot repo in the per-user project registry. Registration is suppressed for
+ * task worktrees and `$HOME` itself (`shouldRegisterProject`) — the process
+ * still serves those folders normally. Strictly non-fatal: the zero-config
+ * law says a broken or read-only home degrades to a smaller cockpit, never a
+ * failed boot, so any workspace error logs one warning and boot continues.
+ *
+ * Returns the boot project's registry id when registration happened —
+ * `serveCommand` plumbs it into the server (`ServerDeps.bootProjectId`) so
+ * `/api/projects` and `/api/v1/health` can name the boot project without a
+ * lookup. Undefined when registration was suppressed or the workspace is
+ * unavailable; the server then derives a fallback on its own.
+ */
+async function initWorkspace(repoRoot, home) {
+    try {
+        await runMigrations({ bootRepoRoot: repoRoot, home });
+        if (await shouldRegisterProject(repoRoot))
+            return (await registerProject(repoRoot, 'local', home)).id;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`${logPrefix()} workspace registry unavailable (${message}) — continuing without it`);
+    }
+    return undefined;
+}
+// ---- run (headless) ----------------------------------------------------------
+/**
+ * The "a cockpit is running" hint for headless `run` (task-cli/hint.ts). Loaded lazily, never
+ * awaited: discovery overlaps the run (hearsay-tools/cezarion#1039), and the returned stop
+ * abandons it when the run ends, so it can neither delay the run nor keep the process alive.
+ */
+function hintRunningCockpit(repoRoot) {
+    let stopped = false;
+    let stop;
+    void import('./task-cli/hint.js').then(({ startCockpitHint }) => {
+        if (!stopped)
+            stop = startCockpitHint(repoRoot);
+    }, () => { });
+    return () => { stopped = true; stop?.(); };
+}
+async function runCommand(home, repoRoot, task, workflowName, model, access) {
+    if (!task) {
+        console.error(commandText('usage: cez run "<task>" [--workflow name] [--model model] [--no-workers] [--no-messaging]'));
+        process.exitCode = 1;
+        return;
+    }
+    const stopHint = hintRunningCockpit(repoRoot);
+    try {
+        await runHeadless(home, repoRoot, task, workflowName, model, access, { ...defaultHeadlessDeps, initWorkspace, openStore, onTerminal });
+    }
+    finally {
+        stopHint();
+    }
+}
+// ---- helpers -----------------------------------------------------------------
+/**
+ * The boot project's store for `serve` (#779, plan step 4). One that cannot open does not stop the
+ * cockpit: the boot project answers every route with the reason (`RunStore.unavailable`), the
+ * other projects work, and a restart once the cause is gone opens it.
+ */
+function openBootStore(repoRoot) {
+    try {
+        return openStore(repoRoot, { keepLive: true });
+    }
+    catch (error) {
+        if (!(error instanceof RunStoreOpenError))
+            throw error;
+        console.error(`\n  ✗ ${error.message}\n`);
+        return RunStore.unavailable(projectPaths(repoRoot).write, error);
+    }
+}
+/** Own package name — for the npm-registry update check (#368). */
+function readOwnName() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+        return pkg.name ?? '@wjarka/cezarion';
+    }
+    catch {
+        return '@wjarka/cezarion';
+    }
+}
+function readOwnVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+main({
+    ...defaultCliDeps, resolveCliHome: () => resolveHome({ purpose: 'cli' }), readOwnName, readOwnVersion, runCommand, initCommand, initWorkspace, serverCommand,
+    serveCommand: (...args) => serveCommand(...args, { ...defaultServeDeps, initWorkspace, openBootStore, readOwnName, readOwnVersion }),
+}).catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/install-as-command.d.ts

@@ -0,0 +1,32 @@
+/** Scoped package name — both install flavors register globally under it, so
+ *  uninstall is a single `npm rm --global` of this name regardless of flavor. */
+export declare const PACKAGE_NAME: "@hearsay-tools/squawk" | "@wjarka/cezarion";
+/** Every bin the main package installs. `cezarion` matches the unscoped npm
+ *  alias, so a single link / global-install exposes the same name as
+ *  `npx cezarion`; `cez` is the short form. */
+export declare const BIN_NAMES: readonly ["cezarion", "cez", "hsq"];
+export declare const COMMAND_NAME: "cez" | "hsq";
+export type InstallMode = 'link' | 'global' | 'uninstall';
+/** One npm invocation: `args` are passed straight to npm (no shell). */
+export interface NpmStep {
+    args: string[];
+    label: string;
+}
+export interface InstallPlan {
+    /** Run `npm run build` before the npm steps (link/global need a fresh dist). */
+    build: boolean;
+    steps: NpmStep[];
+}
+/** Decide the build + npm steps for a mode. `build` defaults to true for the
+ *  install flavors and is forced false for uninstall (nothing to rebuild). */
+export declare function planInstall(opts: {
+    mode: InstallMode;
+    build?: boolean;
+}): InstallPlan;
+/** Expected shim paths for every published bin under an `npm prefix -g` value.
+ *  npm drops POSIX shims in `<prefix>/bin/<name>` and Windows shims directly in
+ *  `<prefix>\<name>.cmd`. `platform` is passed in (not read from `process`) so
+ *  the mapping is deterministic and testable for either OS. */
+export declare function globalShimPaths(prefix: string, platform?: NodeJS.Platform): string[];
+/** The directory the shims live in (for the post-install PATH hint). */
+export declare function globalBinDir(prefix: string, platform?: NodeJS.Platform): string;

package/dist/install-as-command.js

@@ -0,0 +1,55 @@
+import { BINARY_NAMES, productIdentity } from './home/identity.js';
+/** The pure half of `scripts/install-as-command.mjs` (spec 013).
+ *
+ *  `npm run install-as-command` builds this checkout and puts a global
+ *  `cezarion`/`cez` command on PATH pointing at THIS working tree —
+ *  the local-dev equivalent of `npx cezarion`, with no publish. This module
+ *  owns the *decisions* (which npm command runs, where the shims land) so they
+ *  are unit-testable; the `.mjs` script owns the spawning and exit codes.
+ *  Kept dependency-free and side-effect-free (mirrors `pack-check.ts`).
+ */
+import path from 'node:path';
+/** Scoped package name — both install flavors register globally under it, so
+ *  uninstall is a single `npm rm --global` of this name regardless of flavor. */
+// Local builds retain the source workspace name in both switch states (D17).
+export const PACKAGE_NAME = productIdentity(false).npmPackage;
+/** Every bin the main package installs. `cezarion` matches the unscoped npm
+ *  alias, so a single link / global-install exposes the same name as
+ *  `npx cezarion`; `cez` is the short form. */
+export const BIN_NAMES = BINARY_NAMES;
+export const COMMAND_NAME = productIdentity().command;
+/** Decide the build + npm steps for a mode. `build` defaults to true for the
+ *  install flavors and is forced false for uninstall (nothing to rebuild). */
+export function planInstall(opts) {
+    switch (opts.mode) {
+        case 'uninstall':
+            return {
+                build: false,
+                steps: [{ args: ['rm', '--global', PACKAGE_NAME], label: `remove global ${PACKAGE_NAME}` }],
+            };
+        case 'link':
+            return {
+                build: opts.build ?? true,
+                steps: [{ args: ['link'], label: 'link this checkout into the global prefix' }],
+            };
+        case 'global':
+            return {
+                build: opts.build ?? true,
+                steps: [{ args: ['install', '--global', '.'], label: 'install this checkout globally (snapshot)' }],
+            };
+    }
+}
+/** Expected shim paths for every published bin under an `npm prefix -g` value.
+ *  npm drops POSIX shims in `<prefix>/bin/<name>` and Windows shims directly in
+ *  `<prefix>\<name>.cmd`. `platform` is passed in (not read from `process`) so
+ *  the mapping is deterministic and testable for either OS. */
+export function globalShimPaths(prefix, platform = process.platform) {
+    const p = platform === 'win32' ? path.win32 : path.posix;
+    return BIN_NAMES.map((name) => platform === 'win32' ? p.join(prefix, `${name}.cmd`) : p.join(prefix, 'bin', name));
+}
+/** The directory the shims live in (for the post-install PATH hint). */
+export function globalBinDir(prefix, platform = process.platform) {
+    const p = platform === 'win32' ? path.win32 : path.posix;
+    return platform === 'win32' ? prefix : p.join(prefix, 'bin');
+}
+//# sourceMappingURL=install-as-command.js.map

package/dist/install-as-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-as-command.js","sourceRoot":"","sources":["../src/install-as-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACnE;;;;;;;;GAQG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;iFACiF;AACjF,6EAA6E;AAC7E,MAAM,CAAC,MAAM,YAAY,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC;AAE9D;;+CAE+C;AAC/C,MAAM,CAAC,MAAM,SAAS,GAAG,YAAY,CAAC;AACtC,MAAM,CAAC,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC,OAAO,CAAC;AAgBtD;8EAC8E;AAC9E,MAAM,UAAU,WAAW,CAAC,IAA4C;IACtE,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,WAAW;YACd,OAAO;gBACL,KAAK,EAAE,KAAK;gBACZ,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,YAAY,CAAC,EAAE,KAAK,EAAE,iBAAiB,YAAY,EAAE,EAAE,CAAC;aAC5F,CAAC;QACJ,KAAK,MAAM;YACT,OAAO;gBACL,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI;gBACzB,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,2CAA2C,EAAE,CAAC;aAChF,CAAC;QACJ,KAAK,QAAQ;YACX,OAAO;gBACL,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI;gBACzB,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,2CAA2C,EAAE,CAAC;aACpG,CAAC;IACN,CAAC;AACH,CAAC;AAED;;;+DAG+D;AAC/D,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,QAAQ,GAAoB,OAAO,CAAC,QAAQ;IAC1F,MAAM,CAAC,GAAG,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;IACzD,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAC5B,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CACnF,CAAC;AACJ,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,QAAQ,GAAoB,OAAO,CAAC,QAAQ;IACvF,MAAM,CAAC,GAAG,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;IACzD,OAAO,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAC/D,CAAC"}

package/dist/jobs/cli.d.ts

@@ -0,0 +1,2 @@
+/** `cez job`: one JSON object on stdout for a result and on stderr for an error; help is text. */
+export declare function runJobCommand(argv: string[], env: NodeJS.ProcessEnv): Promise<number>;

package/dist/jobs/cli.js

@@ -0,0 +1,53 @@
+import { parseArgs } from 'node:util';
+import { commandText } from '../home/command.js';
+import { JobError, SUPERVISE, jobDirectory, jobStatus, startJob, superviseJob, tellStarter } from './job.js';
+const HELP = commandText(`Usage: cez job start <name> [--dir <dir>] -- <command> [args...]
+       cez job status <name> [--dir <dir>]
+
+start   Run a long command so that it outlives this shell call, the turn and the
+        agent session. Writes its output to a log file and its exit code to an
+        exit file in <dir>; each start has files of its own. Prints JSON with
+        the long-lived "pid", "log" and "exitFile": pass "pid" and "exitFile"
+        to a process wait. Exits 1 and names the running PID while a job of
+        that name still runs. A name whose job ended starts again.
+status  Print JSON: "state" is "running" or "exited", with "pid", "log",
+        "exitFile", and "exitCode" when the exit file holds one.
+
+--dir <dir>  Where the job's files live. Default: $TMPDIR, the task's temp
+             directory, which Cezar removes when the task ends. For a job that
+             must outlive the task, name a git-ignored directory in the worktree.
+-h, --help   Show this help.
+
+The command runs without a shell. For a pipeline, pass: -- sh -c '<pipeline>'.`);
+/** `cez job`: one JSON object on stdout for a result and on stderr for an error; help is text. */
+export async function runJobCommand(argv, env) {
+    if (argv[0] === SUPERVISE)
+        return superviseJob(argv[1], argv[2], argv.slice(4), tellStarter);
+    const split = argv.indexOf('--');
+    const own = split === -1 ? argv : argv.slice(0, split);
+    const command = split === -1 ? [] : argv.slice(split + 1);
+    if (own.includes('--help') || own.includes('-h')) {
+        console.log(HELP);
+        return 0;
+    }
+    try {
+        const { values, positionals } = parseArgs({ args: own, options: { dir: { type: 'string' } }, allowPositionals: true });
+        const [action, name, ...rest] = positionals;
+        if (!name || rest.length > 0 || (action !== 'start' && action !== 'status'))
+            throw new JobError(HELP);
+        const dir = jobDirectory(values.dir, env);
+        if (action === 'status') {
+            if (command.length > 0)
+                throw new JobError(HELP);
+            console.log(JSON.stringify(jobStatus(dir, name)));
+            return 0;
+        }
+        console.log(JSON.stringify(await startJob({ name, dir, command, env })));
+        return 0;
+    }
+    catch (error) {
+        console.error(JSON.stringify({ error: error instanceof Error ? error.message : 'The job command failed' }));
+        return 1;
+    }
+}
+//# sourceMappingURL=cli.js.map