@on-par/factory-cli 0.0.0-stage → 0.9.0

package/dist/cli/stop-sentinel.js

@@ -0,0 +1,61 @@
+// packages/cli/src/cli/stop-sentinel.ts — `.factory/STOP` presence as pure
+// state, shared by `factory run`'s skip-and-log path and `factory doctor`'s
+// explicit status row. STOP is never written or deleted from this module.
+import { existsSync, statSync } from 'node:fs';
+export function defaultStopFileDeps() {
+    return {
+        pathExists: (p) => existsSync(p),
+        statMtimeMs: (p) => statSync(p).mtimeMs,
+        now: () => Date.now(),
+    };
+}
+export function readStopFileStatus(paths, deps = {}) {
+    const { pathExists, statMtimeMs, now } = { ...defaultStopFileDeps(), ...deps };
+    if (!pathExists(paths.stop))
+        return { present: false };
+    try {
+        const mtimeMs = statMtimeMs(paths.stop);
+        return { present: true, ageMs: Math.max(0, now() - mtimeMs), writtenAt: new Date(mtimeMs).toISOString() };
+    }
+    catch {
+        return { present: true, ageMs: 0, writtenAt: 'unknown' };
+    }
+}
+/** Human-readable age like "3h 12m", "45s", or "820ms". */
+export function formatStopFileAge(ms) {
+    if (ms < 1000)
+        return `${Math.max(0, Math.round(ms))}ms`;
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ${s % 60}s`;
+    const h = Math.floor(m / 60);
+    return `${h}h ${m % 60}m`;
+}
+/** Message logged/printed by `factory run` when it skips a pass because STOP is present. */
+export function stopSentinelRunSkipMessage(status) {
+    if (!status.present)
+        return '';
+    return (`.factory/STOP present (age ${formatStopFileAge(status.ageMs)}, written ${status.writtenAt}) — ` +
+        `factory run is skipping this pass and claiming no new work. ` +
+        `Remove .factory/STOP (or run \`factory resume\`) to continue.`);
+}
+export function stopSentinelCheck(status) {
+    if (!status.present) {
+        return {
+            name: 'STOP sentinel',
+            ok: true,
+            detail: '.factory/STOP not present — factory run will claim work normally',
+        };
+    }
+    return {
+        name: 'STOP sentinel',
+        ok: false,
+        optional: true,
+        detail: `.factory/STOP present (age ${formatStopFileAge(status.ageMs)}, written ${status.writtenAt}) — repo is intentionally paused`,
+        fix: 'rm .factory/STOP, or run `factory resume`, to let factory run claim work again',
+    };
+}
+//# sourceMappingURL=stop-sentinel.js.map

package/dist/cli/stop-sentinel.js.map

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

package/dist/cli/sweep-heartbeat.d.ts

@@ -0,0 +1,33 @@
+import type { DoctorCheck } from './doctor.js';
+export interface SweepHeartbeatPolicy {
+    heartbeatFile?: string;
+    loopIntervalSeconds: number;
+    staleThresholdMultiplier: number;
+}
+export interface SweepHeartbeatDeps {
+    exists: (p: string) => boolean;
+    mtimeMs: (p: string) => number;
+    now: () => number;
+}
+export declare function defaultSweepHeartbeatDeps(): SweepHeartbeatDeps;
+export declare function resolveSweepHeartbeatFile(policy: SweepHeartbeatPolicy, env: NodeJS.ProcessEnv): string | undefined;
+export type SweepHeartbeatStatus = {
+    status: 'unconfigured';
+} | {
+    status: 'missing';
+    file: string;
+} | {
+    status: 'fresh';
+    file: string;
+    ageSeconds: number;
+    thresholdSeconds: number;
+} | {
+    status: 'stale';
+    file: string;
+    ageSeconds: number;
+    thresholdSeconds: number;
+};
+export declare function checkSweepHeartbeat(policy: SweepHeartbeatPolicy, env: NodeJS.ProcessEnv, deps: SweepHeartbeatDeps): SweepHeartbeatStatus;
+export declare function sweepHeartbeatCheck(status: SweepHeartbeatStatus): DoctorCheck | null;
+export declare function formatSweepHeartbeatStatusLine(status: SweepHeartbeatStatus): string;
+//# sourceMappingURL=sweep-heartbeat.d.ts.map

package/dist/cli/sweep-heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sweep-heartbeat.d.ts","sourceRoot":"","sources":["../../src/cli/sweep-heartbeat.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,WAAW,oBAAoB;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,wBAAwB,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;IAC/B,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/B,GAAG,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,wBAAgB,yBAAyB,IAAI,kBAAkB,CAM9D;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,oBAAoB,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,GAAG,SAAS,CAElH;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,MAAM,EAAE,cAAc,CAAA;CAAE,GAC1B;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,GAC/E;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpF,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,oBAAoB,EAC5B,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,IAAI,EAAE,kBAAkB,GACvB,oBAAoB,CAWtB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,WAAW,GAAG,IAAI,CA0BpF;AAED,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAWnF"}

package/dist/cli/sweep-heartbeat.js

@@ -0,0 +1,65 @@
+// packages/cli/src/cli/sweep-heartbeat.ts — detect a dead auto-merge-sweep loop from its
+// heartbeat file's mtime, so `factory doctor`/`status` catch it instead of it rotting silently.
+import { existsSync, statSync } from 'node:fs';
+export function defaultSweepHeartbeatDeps() {
+    return {
+        exists: (p) => existsSync(p),
+        mtimeMs: (p) => statSync(p).mtimeMs,
+        now: () => Date.now(),
+    };
+}
+export function resolveSweepHeartbeatFile(policy, env) {
+    return policy.heartbeatFile || env.HEARTBEAT_FILE || undefined;
+}
+export function checkSweepHeartbeat(policy, env, deps) {
+    const file = resolveSweepHeartbeatFile(policy, env);
+    if (!file)
+        return { status: 'unconfigured' };
+    if (!deps.exists(file))
+        return { status: 'missing', file };
+    const ageSeconds = Math.max(0, Math.round((deps.now() - deps.mtimeMs(file)) / 1000));
+    const thresholdSeconds = Math.round(policy.loopIntervalSeconds * policy.staleThresholdMultiplier);
+    return ageSeconds > thresholdSeconds
+        ? { status: 'stale', file, ageSeconds, thresholdSeconds }
+        : { status: 'fresh', file, ageSeconds, thresholdSeconds };
+}
+export function sweepHeartbeatCheck(status) {
+    const NAME = 'auto-merge sweep heartbeat';
+    switch (status.status) {
+        case 'unconfigured':
+            return null;
+        case 'missing':
+            return {
+                name: NAME,
+                ok: false,
+                detail: `${status.file} not found — the sweep has never written a heartbeat`,
+                fix: 'confirm the sweep loop is running and HEARTBEAT_FILE / sweep.heartbeatFile point at the right path',
+            };
+        case 'stale':
+            return {
+                name: NAME,
+                ok: false,
+                detail: `${status.file} last updated ${status.ageSeconds}s ago (> ${status.thresholdSeconds}s threshold) — the sweep looks dead`,
+                fix: 'check the sweep loop / launchd job (see docs/runbooks/sweep-heartbeat.md) and restart it',
+            };
+        case 'fresh':
+            return {
+                name: NAME,
+                ok: true,
+                detail: `${status.file} updated ${status.ageSeconds}s ago (threshold ${status.thresholdSeconds}s)`,
+            };
+    }
+}
+export function formatSweepHeartbeatStatusLine(status) {
+    switch (status.status) {
+        case 'unconfigured':
+            return 'not configured (sweep.heartbeatFile / HEARTBEAT_FILE unset)';
+        case 'missing':
+            return `MISSING — ${status.file} not found`;
+        case 'stale':
+            return `STALE — ${status.file}, last updated ${status.ageSeconds}s ago (threshold ${status.thresholdSeconds}s)`;
+        case 'fresh':
+            return `OK — ${status.file}, last updated ${status.ageSeconds}s ago (threshold ${status.thresholdSeconds}s)`;
+    }
+}
+//# sourceMappingURL=sweep-heartbeat.js.map

package/dist/cli/sweep-heartbeat.js.map

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

package/dist/cli/unpark.d.ts

@@ -0,0 +1,28 @@
+import type { QueueGitHubClient } from '@on-par/factory-core/internal';
+export type UnparkErrorCode = 'not-parked' | 'lane-required' | 'unpark-failed';
+export declare class UnparkError extends Error {
+    readonly code: UnparkErrorCode;
+    constructor(code: UnparkErrorCode, message: string);
+}
+/** `factory unpark --json` payload (#2277). Additive changes only; bump schemaVersion on a breaking change. */
+export interface UnparkJson {
+    schemaVersion: 1;
+    ok: true;
+    action: 'unpark';
+    issue: number;
+    /** Slug actually routed to (the factory:lane:<slug> suffix). */
+    lane: string;
+    /** The one order position assigned. */
+    order: number;
+    labelsBefore: string[];
+    labelsAfter: string[];
+}
+export interface UnparkInput {
+    client: QueueGitHubClient;
+    owner: string;
+    repo: string;
+    issue: number;
+    lane?: string;
+}
+export declare function runUnpark(input: UnparkInput): Promise<UnparkJson>;
+//# sourceMappingURL=unpark.d.ts.map

package/dist/cli/unpark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unpark.d.ts","sourceRoot":"","sources":["../../src/cli/unpark.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AASvE,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,eAAe,GAAG,eAAe,CAAC;AAE/E,qBAAa,WAAY,SAAQ,KAAK;IAElC,QAAQ,CAAC,IAAI,EAAE,eAAe;IADhC,YACW,IAAI,EAAE,eAAe,EAC9B,OAAO,EAAE,MAAM,EAIhB;CACF;AAED,+GAA+G;AAC/G,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,CAAC,CAAC;IACjB,EAAE,EAAE,IAAI,CAAC;IACT,MAAM,EAAE,QAAQ,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD,wBAAsB,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAwDvE"}

package/dist/cli/unpark.js

@@ -0,0 +1,68 @@
+import { createGithubQueue, LANE_LABEL_PREFIX, laneLabel, PARKED_LABEL, QUEUE_ORDER_LABEL_PREFIX, } from '@on-par/factory-core/internal';
+export class UnparkError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'UnparkError';
+    }
+}
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export async function runUnpark(input) {
+    const { client, owner, repo, issue } = input;
+    const ref = { owner, repo, issue_number: issue };
+    try {
+        const labelsBefore = await client.getIssueLabels(ref);
+        if (!labelsBefore.includes(PARKED_LABEL)) {
+            throw new UnparkError('not-parked', `#${issue} is not labelled ${PARKED_LABEL}`);
+        }
+        const existing = labelsBefore
+            .filter((l) => l.startsWith(LANE_LABEL_PREFIX))
+            .map((l) => l.slice(LANE_LABEL_PREFIX.length))
+            .filter((s) => s !== '');
+        let lane;
+        if (input.lane !== undefined && input.lane.trim() !== '') {
+            lane = laneLabel(input.lane.trim()).slice(LANE_LABEL_PREFIX.length);
+        }
+        else if (existing.length === 1) {
+            lane = existing[0];
+        }
+        else if (existing.length === 0) {
+            throw new UnparkError('lane-required', `#${issue} has no ${LANE_LABEL_PREFIX}* label; pass --lane <lane>`);
+        }
+        else {
+            throw new UnparkError('lane-required', `#${issue} has several lane labels (${existing.join(', ')}); pass --lane <lane>`);
+        }
+        const keepLane = laneLabel(lane);
+        for (const name of labelsBefore) {
+            if (name.startsWith(QUEUE_ORDER_LABEL_PREFIX) || (name.startsWith(LANE_LABEL_PREFIX) && name !== keepLane)) {
+                await client.removeLabel({ ...ref, name });
+            }
+        }
+        const [r] = await createGithubQueue({ client, owner, repo }).enqueue(lane, [issue]);
+        if (r === undefined || r.outcome !== 'queued' || r.position === undefined) {
+            throw new UnparkError('unpark-failed', r?.detail ?? `enqueue returned ${r?.outcome}`);
+        }
+        // Remove the parked label last so a failed run can simply be repeated.
+        await client.removeLabel({ ...ref, name: PARKED_LABEL });
+        const labelsAfter = await client.getIssueLabels(ref);
+        return {
+            schemaVersion: 1,
+            ok: true,
+            action: 'unpark',
+            issue,
+            lane,
+            order: r.position,
+            labelsBefore: [...labelsBefore],
+            labelsAfter,
+        };
+    }
+    catch (err) {
+        if (err instanceof UnparkError)
+            throw err;
+        throw new UnparkError('unpark-failed', message(err));
+    }
+}
+//# sourceMappingURL=unpark.js.map

package/dist/cli/unpark.js.map

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

package/dist/cli/usage-json.d.ts

@@ -0,0 +1,20 @@
+import type { SubscriptionUsage } from '@on-par/factory-core';
+/** Hours in the trailing usage window `factory usage` reports on. */
+export declare const USAGE_WINDOW_HOURS: number;
+export type UsageJsonSource = 'subscription' | 'heuristic' | 'unavailable';
+/** `factory usage --json` payload (#2270). Absent readings are null, never 0 (ADR-0099).
+ *  Additive changes only; bump schemaVersion on a breaking change. */
+export interface UsageJson {
+    schemaVersion: 1;
+    source: UsageJsonSource;
+    /** Percent of the window used, 0-100 scale. */
+    utilizationPct: number | null;
+    resetsAt: string | null;
+    windowHours: number;
+    /** Trailing-window list-price estimate in USD. */
+    estimateUsd: number | null;
+}
+/** Builds the `factory usage --json` payload: the real subscription reading when present, else the
+ *  list-price heuristic against `cap`, else an explicit `unavailable` record. Numbers are not rounded. */
+export declare function buildUsageJson(subscription: SubscriptionUsage | null, estimateUsd: number | null, cap: number): UsageJson;
+//# sourceMappingURL=usage-json.d.ts.map

package/dist/cli/usage-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-json.d.ts","sourceRoot":"","sources":["../../src/cli/usage-json.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG9D,qEAAqE;AACrE,eAAO,MAAM,kBAAkB,QAAiC,CAAC;AAEjE,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,WAAW,GAAG,aAAa,CAAC;AAE3E;sEACsE;AACtE,MAAM,WAAW,SAAS;IACxB,aAAa,EAAE,CAAC,CAAC;IACjB,MAAM,EAAE,eAAe,CAAC;IACxB,+CAA+C;IAC/C,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;0GAC0G;AAC1G,wBAAgB,cAAc,CAC5B,YAAY,EAAE,iBAAiB,GAAG,IAAI,EACtC,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,GAAG,EAAE,MAAM,GACV,SAAS,CA6BX"}

package/dist/cli/usage-json.js

@@ -0,0 +1,36 @@
+import { TRAILING_WINDOW_MS } from '@on-par/factory-core/internal';
+/** Hours in the trailing usage window `factory usage` reports on. */
+export const USAGE_WINDOW_HOURS = TRAILING_WINDOW_MS / 3_600_000;
+/** Builds the `factory usage --json` payload: the real subscription reading when present, else the
+ *  list-price heuristic against `cap`, else an explicit `unavailable` record. Numbers are not rounded. */
+export function buildUsageJson(subscription, estimateUsd, cap) {
+    if (subscription !== null) {
+        return {
+            schemaVersion: 1,
+            source: 'subscription',
+            utilizationPct: subscription.fiveHourUtilization,
+            resetsAt: subscription.fiveHourResetsAt,
+            windowHours: USAGE_WINDOW_HOURS,
+            estimateUsd,
+        };
+    }
+    if (estimateUsd !== null) {
+        return {
+            schemaVersion: 1,
+            source: 'heuristic',
+            utilizationPct: (estimateUsd / cap) * 100,
+            resetsAt: null,
+            windowHours: USAGE_WINDOW_HOURS,
+            estimateUsd,
+        };
+    }
+    return {
+        schemaVersion: 1,
+        source: 'unavailable',
+        utilizationPct: null,
+        resetsAt: null,
+        windowHours: USAGE_WINDOW_HOURS,
+        estimateUsd: null,
+    };
+}
+//# sourceMappingURL=usage-json.js.map

package/dist/cli/usage-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-json.js","sourceRoot":"","sources":["../../src/cli/usage-json.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAEnE,qEAAqE;AACrE,MAAM,CAAC,MAAM,kBAAkB,GAAG,kBAAkB,GAAG,SAAS,CAAC;AAiBjE;0GAC0G;AAC1G,MAAM,UAAU,cAAc,CAC5B,YAAsC,EACtC,WAA0B,EAC1B,GAAW;IAEX,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;QAC1B,OAAO;YACL,aAAa,EAAE,CAAC;YAChB,MAAM,EAAE,cAAc;YACtB,cAAc,EAAE,YAAY,CAAC,mBAAmB;YAChD,QAAQ,EAAE,YAAY,CAAC,gBAAgB;YACvC,WAAW,EAAE,kBAAkB;YAC/B,WAAW;SACZ,CAAC;IACJ,CAAC;IACD,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;QACzB,OAAO;YACL,aAAa,EAAE,CAAC;YAChB,MAAM,EAAE,WAAW;YACnB,cAAc,EAAE,CAAC,WAAW,GAAG,GAAG,CAAC,GAAG,GAAG;YACzC,QAAQ,EAAE,IAAI;YACd,WAAW,EAAE,kBAAkB;YAC/B,WAAW;SACZ,CAAC;IACJ,CAAC;IACD,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,MAAM,EAAE,aAAa;QACrB,cAAc,EAAE,IAAI;QACpB,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,kBAAkB;QAC/B,WAAW,EAAE,IAAI;KAClB,CAAC;AACJ,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// packages/cli/src/cli.ts — CLI entry point
+import { main } from './cli/index.js';
+import { runEntry } from './entry.js';
+void runEntry(main);
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,4CAA4C;AAE5C,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,KAAK,QAAQ,CAAC,IAAI,CAAC,CAAC"}

package/dist/entry.d.ts

@@ -0,0 +1,6 @@
+export interface EntryIo {
+    error(msg: string): void;
+    exit(code: number): void;
+}
+export declare function runEntry(main: () => Promise<void>, io?: EntryIo): Promise<void>;
+//# sourceMappingURL=entry.d.ts.map

package/dist/entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.d.ts","sourceRoot":"","sources":["../src/entry.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAKD,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,GAAE,OAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhG"}

package/dist/entry.js

@@ -0,0 +1,13 @@
+// packages/cli/src/entry.ts — bin-entry runner: awaits main and exits 1 on rejection (#2031).
+// References, not wrappers: Node's console methods are bound and process.exit ignores `this`.
+const defaultIo = { error: console.error, exit: process.exit };
+export async function runEntry(main, io = defaultIo) {
+    try {
+        await main();
+    }
+    catch (err) {
+        io.error(err.message);
+        io.exit(1);
+    }
+}
+//# sourceMappingURL=entry.js.map

package/dist/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../src/entry.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAO9F,8FAA8F;AAC9F,MAAM,SAAS,GAAY,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;AAExE,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAyB,EAAE,EAAE,GAAY,SAAS;IAC/E,IAAI,CAAC;QACH,MAAM,IAAI,EAAE,CAAC;IACf,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,EAAE,CAAC,KAAK,CAAE,GAAa,CAAC,OAAO,CAAC,CAAC;QACjC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACb,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@on-par/factory-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.0",
+  "description": "CLI for the Software Factory — ships verified GitHub issues via boss-worker-checker orchestration.",
+  "type": "module",
+  "main": "dist/cli.js",
+  "bin": {
+    "factory": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/on-par/software-factory.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/on-par/software-factory#readme",
+  "bugs": {
+    "url": "https://github.com/on-par/software-factory/issues"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsx src/cli.ts",
+    "start": "node dist/cli.js",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build",
+    "prepack": "node ../../scripts/pack-hygiene-cli.ts prepack"
+  },
+  "dependencies": {
+    "@octokit/plugin-retry": "^8.1.1",
+    "@octokit/plugin-throttling": "^11.0.5",
+    "@octokit/rest": "^22.0.0",
+    "@on-par/factory-core": "0.9.0",
+    "@on-par/factory-tui": "0.9.0",
+    "commander": "^15.0.0"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^26.6.4"
+  }
+}