@openagentsy/ledger 0.0.0-stage → 0.2.1

package/dist/db.d.ts

@@ -0,0 +1,44 @@
+import { Database } from 'bun:sqlite';
+/**
+ * The ledger's database wiring.
+ *
+ * bun:sqlite is the driver because the OpenCode plugin runtime is Bun: the
+ * adapter and the CLI read the same file the board writes, and a driver one
+ * runtime lacks breaks the other.
+ */
+/** The state directory the ledger lives in (§6.1). */
+export declare const STATE_DIR = ".openagentsy";
+/** The database file, inside the state directory. */
+export declare const LEDGER_FILE = "ledger.db";
+/** How long SQLite waits for a lock before it reports the database busy. */
+export declare const BUSY_TIMEOUT_MS = 250;
+/** How many times a busy write is retried (REV3 §6.1). */
+export declare const BUSY_RETRIES = 5;
+/** The first backoff, doubled per attempt, capped at the last one. */
+export declare const BUSY_BACKOFF_MS = 1;
+export declare const BUSY_BACKOFF_MAX_MS = 64;
+/** The path of the ledger at a root. */
+export declare function ledgerPath(root: string): string;
+/**
+ * Open the ledger at a root.
+ *
+ * The root is injected: the state root of §3.9 is resolved by the caller,
+ * so a worktree and its main repository share one ledger, and a test can
+ * point at a temporary directory.
+ */
+export declare function openLedger(root: string): Database;
+/** Close the ledger. */
+export declare function closeLedger(db: Database): void;
+/** Whether an error is the busy one. */
+export declare function isBusyError(error: unknown): boolean;
+/**
+ * Run a write, and try again while the database is busy.
+ *
+ * SQLite reports a locked database as SQLITE_BUSY; the worktree case is the
+ * common one, where a builder in a worktree and the Lead in the main
+ * repository write the same file. The retry is bounded: five attempts, with
+ * the wait doubling from a millisecond to a cap of sixty-four, so a write
+ * never hangs and a locked database is reported rather than waited out.
+ */
+export declare function withBusyRetry<T>(operation: () => T, retries?: number): T;
+//# sourceMappingURL=db.d.ts.map

package/dist/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAKtC;;;;;;GAMG;AAEH,sDAAsD;AACtD,eAAO,MAAM,SAAS,iBAAiB,CAAC;AACxC,qDAAqD;AACrD,eAAO,MAAM,WAAW,cAAc,CAAC;AACvC,4EAA4E;AAC5E,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,0DAA0D;AAC1D,eAAO,MAAM,YAAY,IAAI,CAAC;AAC9B,sEAAsE;AACtE,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,wCAAwC;AACxC,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAYjD;AAED,wBAAwB;AACxB,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAE9C;AAeD,wCAAwC;AACxC,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,OAAO,SAAe,GAAG,CAAC,CAa9E"}

package/dist/db.js

@@ -0,0 +1,97 @@
+import { Database } from 'bun:sqlite';
+import { mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { applySchema } from './schema.js';
+/**
+ * The ledger's database wiring.
+ *
+ * bun:sqlite is the driver because the OpenCode plugin runtime is Bun: the
+ * adapter and the CLI read the same file the board writes, and a driver one
+ * runtime lacks breaks the other.
+ */
+/** The state directory the ledger lives in (§6.1). */
+export const STATE_DIR = '.openagentsy';
+/** The database file, inside the state directory. */
+export const LEDGER_FILE = 'ledger.db';
+/** How long SQLite waits for a lock before it reports the database busy. */
+export const BUSY_TIMEOUT_MS = 250;
+/** How many times a busy write is retried (REV3 §6.1). */
+export const BUSY_RETRIES = 5;
+/** The first backoff, doubled per attempt, capped at the last one. */
+export const BUSY_BACKOFF_MS = 1;
+export const BUSY_BACKOFF_MAX_MS = 64;
+/** The path of the ledger at a root. */
+export function ledgerPath(root) {
+    return join(root, STATE_DIR, LEDGER_FILE);
+}
+/**
+ * Open the ledger at a root.
+ *
+ * The root is injected: the state root of §3.9 is resolved by the caller,
+ * so a worktree and its main repository share one ledger, and a test can
+ * point at a temporary directory.
+ */
+export function openLedger(root) {
+    const path = ledgerPath(root);
+    mkdirSync(dirname(path), { recursive: true });
+    const db = new Database(path, { create: true });
+    // WAL so a reader never blocks the writer, a short busy timeout so a
+    // blocked write fails fast, and a retry on top of that (REV3 §6.1).
+    db.exec('PRAGMA journal_mode = WAL');
+    db.exec('PRAGMA foreign_keys = ON');
+    db.exec('PRAGMA synchronous = NORMAL');
+    db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+    applySchema(db);
+    return db;
+}
+/** Close the ledger. */
+export function closeLedger(db) {
+    db.close();
+}
+/** The flag the retry loop waits on. A shared buffer, so the wait is a wait. */
+const WAKE = new Int32Array(new SharedArrayBuffer(4));
+/**
+ * Sleep without spinning the CPU.
+ *
+ * `Atomics.wait` parks the thread until the timeout, which is what a backoff
+ * wants: the alternative is a loop that burns a core to wait for a lock.
+ */
+function sleepSync(ms) {
+    Atomics.wait(WAKE, 0, 0, ms);
+}
+/** Whether an error is the busy one. */
+export function isBusyError(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const code = error.code;
+    if (typeof code === 'string' && code.startsWith('SQLITE_BUSY'))
+        return true;
+    const message = error instanceof Error ? error.message : String(error.message ?? '');
+    return message.includes('SQLITE_BUSY') || message.includes('database is locked');
+}
+/**
+ * Run a write, and try again while the database is busy.
+ *
+ * SQLite reports a locked database as SQLITE_BUSY; the worktree case is the
+ * common one, where a builder in a worktree and the Lead in the main
+ * repository write the same file. The retry is bounded: five attempts, with
+ * the wait doubling from a millisecond to a cap of sixty-four, so a write
+ * never hangs and a locked database is reported rather than waited out.
+ */
+export function withBusyRetry(operation, retries = BUSY_RETRIES) {
+    let attempt = 0;
+    let delay = BUSY_BACKOFF_MS;
+    for (;;) {
+        try {
+            return operation();
+        }
+        catch (error) {
+            if (!isBusyError(error) || attempt >= retries)
+                throw error;
+            attempt += 1;
+            sleepSync(delay);
+            delay = Math.min(delay * 2, BUSY_BACKOFF_MAX_MS);
+        }
+    }
+}
+//# sourceMappingURL=db.js.map

package/dist/db.js.map

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

package/dist/export.d.ts

@@ -0,0 +1,71 @@
+import { Database } from 'bun:sqlite';
+/**
+ * The export (§6.6).
+ *
+ * Counters only. No prompt, no completion, no code, no message id and no
+ * session id: the export is a set of numbers with the names of a role and a
+ * task, so a person can read what the work cost without reading the work.
+ * Nothing is uploaded, and there is no leaderboard.
+ */
+/** The version of the export shape. */
+export declare const EXPORT_SCHEMA = "openagentsy.ledger/v1";
+export type LedgerExport = {
+    schema: string;
+    generatedAt: string;
+    totals: {
+        messages: number;
+        tokens: number;
+        input: number;
+        output: number;
+        reasoning: number;
+        cacheRead: number;
+        cacheWrite: number;
+        usd: number | null;
+        unpricedMessages: number;
+    };
+    byRole: {
+        role: string;
+        messages: number;
+        tokens: number;
+        usd: number | null;
+        unpriced: number;
+    }[];
+    byTask: {
+        taskId: string;
+        messages: number;
+        tokens: number;
+        usd: number | null;
+    }[];
+    waste: {
+        tokens: number;
+        percentage: number;
+    };
+    outcomes: {
+        tasksCompleted: number;
+        tasksScrapped: number;
+        commits: number;
+        prsMerged: number;
+    };
+    /** The mean tokens of a completed task, when there is one. */
+    tokensPerCompletedTask: number | null;
+    offload: {
+        messages: number;
+        tokens: number;
+        usd: number | null;
+    };
+};
+export type ExportOptions = {
+    /** The clock, so a test can pin the stamp. */
+    generatedAt?: string;
+};
+/** The counters of the ledger, ready to be written as JSON. */
+export declare function ledgerExport(db: Database, options?: ExportOptions): LedgerExport;
+/**
+ * The export of a ledger with nothing in it.
+ *
+ * A project that has no ledger yet has nothing to show, and reading it
+ * should not create one, so the zeros come from a database that lives only
+ * for the length of the call.
+ */
+export declare function emptyLedgerExport(generatedAt?: string): LedgerExport;
+//# sourceMappingURL=export.d.ts.map

package/dist/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../src/export.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAYtC;;;;;;;GAOG;AAEH,uCAAuC;AACvC,eAAO,MAAM,aAAa,0BAA0B,CAAC;AAErD,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE;QACN,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QACnB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;KAClB,EAAE,CAAC;IACJ,MAAM,EAAE;QACN,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;KACpB,EAAE,CAAC;IACJ,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,QAAQ,EAAE;QACR,cAAc,EAAE,MAAM,CAAC;QACvB,aAAa,EAAE,MAAM,CAAC;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,8DAA8D;IAC9D,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CACnE,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,GAAE,aAAkB,GAAG,YAAY,CA+CpF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,YAAY,CAQpE"}

package/dist/export.js

@@ -0,0 +1,78 @@
+import { Database } from 'bun:sqlite';
+import { ledgerTotals, offloadRows, outcomeTotals, perRoleTotals, perTaskTotals, tokensPerCompletedTask, wasteTotals, } from './query.js';
+import { applySchema } from './schema.js';
+/**
+ * The export (§6.6).
+ *
+ * Counters only. No prompt, no completion, no code, no message id and no
+ * session id: the export is a set of numbers with the names of a role and a
+ * task, so a person can read what the work cost without reading the work.
+ * Nothing is uploaded, and there is no leaderboard.
+ */
+/** The version of the export shape. */
+export const EXPORT_SCHEMA = 'openagentsy.ledger/v1';
+/** The counters of the ledger, ready to be written as JSON. */
+export function ledgerExport(db, options = {}) {
+    const totals = ledgerTotals(db);
+    const roles = perRoleTotals(db);
+    const tasks = perTaskTotals(db);
+    const waste = wasteTotals(db);
+    const outcomes = outcomeTotals(db);
+    const offload = offloadRows(db);
+    const completed = tokensPerCompletedTask(db);
+    const offloadTokens = offload.reduce((sum, row) => sum + row.tokens, 0);
+    const offloadUsd = offload.some((row) => row.usd !== null)
+        ? offload.reduce((sum, row) => sum + (row.usd ?? 0), 0)
+        : null;
+    const completedTokens = completed.reduce((sum, row) => sum + row.tokens, 0);
+    return {
+        schema: EXPORT_SCHEMA,
+        generatedAt: options.generatedAt ?? new Date().toISOString(),
+        totals: {
+            messages: totals.messages,
+            tokens: totals.tokens,
+            input: totals.input,
+            output: totals.output,
+            reasoning: totals.reasoning,
+            cacheRead: totals.cacheRead,
+            cacheWrite: totals.cacheWrite,
+            usd: totals.usd,
+            unpricedMessages: totals.unpricedMessages,
+        },
+        byRole: roles.map((row) => ({
+            role: row.role,
+            messages: row.messages,
+            tokens: row.tokens,
+            usd: row.usd,
+            unpriced: row.unpriced,
+        })),
+        byTask: tasks.map((row) => ({
+            taskId: row.taskId,
+            messages: row.messages,
+            tokens: row.tokens,
+            usd: row.usd,
+        })),
+        waste: { tokens: waste.tokens, percentage: waste.percentage },
+        outcomes,
+        tokensPerCompletedTask: completed.length > 0 ? completedTokens / completed.length : null,
+        offload: { messages: offload.length, tokens: offloadTokens, usd: offloadUsd },
+    };
+}
+/**
+ * The export of a ledger with nothing in it.
+ *
+ * A project that has no ledger yet has nothing to show, and reading it
+ * should not create one, so the zeros come from a database that lives only
+ * for the length of the call.
+ */
+export function emptyLedgerExport(generatedAt) {
+    const db = new Database(':memory:');
+    try {
+        applySchema(db);
+        return ledgerExport(db, generatedAt === undefined ? {} : { generatedAt });
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=export.js.map

package/dist/export.js.map

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

package/dist/footprint.d.ts

@@ -0,0 +1,24 @@
+import type { Database } from 'bun:sqlite';
+import { type Impact } from '@openagentsy/footprint';
+/**
+ * The footprint rows.
+ *
+ * The ledger does not compute an impact: it stores the one it is given, with
+ * the bounds the estimator produced, and the version of the methodology that
+ * produced them, so a number is never read without the method behind it.
+ */
+/**
+ * The methodology the numbers came from.
+ *
+ * The estimator pins EcoLogits 0.11.3 (see `packages/footprint/data/SOURCES.md`);
+ * the string lives here so the row says which method it was written under.
+ */
+export declare const FOOTPRINT_METHOD_VERSION = "ecologits-0.11.3";
+/**
+ * Record the footprint of one message.
+ *
+ * The row is written once per message and the bounds are ordered, because a
+ * range that reads backwards is a range nobody can use.
+ */
+export declare function recordFootprint(db: Database, messageId: string, impact: Impact): void;
+//# sourceMappingURL=footprint.d.ts.map

package/dist/footprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"footprint.d.ts","sourceRoot":"","sources":["../src/footprint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,KAAK,MAAM,EAAK,MAAM,wBAAwB,CAAC;AAGxD;;;;;;GAMG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,qBAAqB,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAqBrF"}

package/dist/footprint.js

@@ -0,0 +1,33 @@
+import { r } from '@openagentsy/footprint';
+import { withBusyRetry } from './db.js';
+/**
+ * The footprint rows.
+ *
+ * The ledger does not compute an impact: it stores the one it is given, with
+ * the bounds the estimator produced, and the version of the methodology that
+ * produced them, so a number is never read without the method behind it.
+ */
+/**
+ * The methodology the numbers came from.
+ *
+ * The estimator pins EcoLogits 0.11.3 (see `packages/footprint/data/SOURCES.md`);
+ * the string lives here so the row says which method it was written under.
+ */
+export const FOOTPRINT_METHOD_VERSION = 'ecologits-0.11.3';
+/**
+ * Record the footprint of one message.
+ *
+ * The row is written once per message and the bounds are ordered, because a
+ * range that reads backwards is a range nobody can use.
+ */
+export function recordFootprint(db, messageId, impact) {
+    const energy = r(impact.energyWh[0], impact.energyWh[1]);
+    const water = r(impact.waterL[0], impact.waterL[1]);
+    const co2 = r(impact.co2Kg[0], impact.co2Kg[1]);
+    withBusyRetry(() => {
+        db.query(`INSERT OR REPLACE INTO footprint
+          (message_id, energy_lo, energy_hi, water_lo, water_hi, co2_lo, co2_hi, method_version)
+          VALUES (?,?,?,?,?,?,?,?)`).run(messageId, energy[0], energy[1], water[0], water[1], co2[0], co2[1], FOOTPRINT_METHOD_VERSION);
+    });
+}
+//# sourceMappingURL=footprint.js.map

package/dist/footprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"footprint.js","sourceRoot":"","sources":["../src/footprint.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExC;;;;;;GAMG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,kBAAkB,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,EAAY,EAAE,SAAiB,EAAE,MAAc;IAC7E,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAEhD,aAAa,CAAC,GAAG,EAAE;QACjB,EAAE,CAAC,KAAK,CACN;;mCAE6B,CAC9B,CAAC,GAAG,CACH,SAAS,EACT,MAAM,CAAC,CAAC,CAAC,EACT,MAAM,CAAC,CAAC,CAAC,EACT,KAAK,CAAC,CAAC,CAAC,EACR,KAAK,CAAC,CAAC,CAAC,EACR,GAAG,CAAC,CAAC,CAAC,EACN,GAAG,CAAC,CAAC,CAAC,EACN,wBAAwB,CACzB,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/git.d.ts

@@ -0,0 +1,44 @@
+/** The result of one git command. */
+export type GitResult = {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+};
+/**
+ * Run a git command and read what it says.
+ *
+ * The command never throws: a directory that is not a repository, or a git
+ * that is not installed, comes back as `ok: false` with the reason, and the
+ * scanner treats it as "nothing found" rather than as a crash. A scanner that
+ * cannot read a repository must not take the command down with it.
+ */
+export declare function runGit(cwd: string, args: string[]): GitResult;
+/** The output of a git command, or null when the command failed. */
+export declare function gitText(cwd: string, args: string[]): string | null;
+/** A commit, as the scanners read it. */
+export type GitCommit = {
+    /** The full sha. */
+    sha: string;
+    /** Seconds since the epoch, the way git reports a commit time. */
+    at: number;
+    /** The whole message, without the format placeholders. */
+    message: string;
+};
+/**
+ * The commits of a repository, newest first.
+ *
+ * `git log` is asked for the sha, the timestamp and the body of the message
+ * in one pass. The three are separated by characters that cannot occur in
+ * them, so a message with a blank line in it survives the round trip.
+ */
+export declare function gitCommits(cwd: string, since: string): GitCommit[];
+/**
+ * The task ids of the `Refs:` trailers of a message.
+ *
+ * The trailer is the link between a commit and the work it did (§6.5): the
+ * pre-commit hook asks for it on an agent commit, and the outcome scanners
+ * read it back. A message with no trailer names no task, and a trailer that
+ * names nothing is not a trailer.
+ */
+export declare function refsTrailers(message: string): string[];
+//# sourceMappingURL=git.d.ts.map

package/dist/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAiDA,qCAAqC;AACrC,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,CAe7D;AAED,oEAAoE;AACpE,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAGlE;AAED,yCAAyC;AACzC,MAAM,MAAM,SAAS,GAAG;IACtB,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,CAqBlE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAQtD"}

package/dist/git.js

@@ -0,0 +1,126 @@
+import { spawnSync } from 'node:child_process';
+/**
+ * The git commands the scanners run.
+ *
+ * The scanners are commands and not daemons (§6.4): they read a repository
+ * on demand and write what they find into the ledger. Every call here is a
+ * read — `git log`, `git show` — and none of them writes to the repository.
+ */
+/** The separator between the fields of one commit. */
+const UNIT = '\u001f';
+/** The separator between two commits. */
+const RECORD = '\u001e';
+/**
+ * The git variables that point a command at a repository.
+ *
+ * A git that runs a hook sets these in the environment of the hook, and a
+ * command spawned inside that hook inherits them. The child then addresses
+ * the repository of the hook instead of the one it was asked about: it
+ * writes to the outer index and fights the process that holds the lock —
+ * "fatal: Unable to create .../index.lock: File exists" is what that looks
+ * like. The child gets these removed, so the repository is the one the
+ * caller named.
+ */
+const GIT_REPOSITORY_VARS = [
+    'GIT_DIR',
+    'GIT_WORK_TREE',
+    'GIT_INDEX_FILE',
+    'GIT_COMMON_DIR',
+    'GIT_OBJECT_DIRECTORY',
+    'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+    'GIT_CEILING_DIRECTORIES',
+    'GIT_PREFIX',
+    'GIT_NAMESPACE',
+];
+/** The environment a git child gets: the caller's, without the git variables. */
+function cleanEnv() {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value === undefined)
+            continue;
+        if (GIT_REPOSITORY_VARS.includes(key))
+            continue;
+        env[key] = value;
+    }
+    return env;
+}
+/**
+ * Run a git command and read what it says.
+ *
+ * The command never throws: a directory that is not a repository, or a git
+ * that is not installed, comes back as `ok: false` with the reason, and the
+ * scanner treats it as "nothing found" rather than as a crash. A scanner that
+ * cannot read a repository must not take the command down with it.
+ */
+export function runGit(cwd, args) {
+    const result = spawnSync('git', args, {
+        cwd,
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+        env: cleanEnv(),
+    });
+    if (result.error !== undefined) {
+        return { ok: false, stdout: '', stderr: result.error.message };
+    }
+    return {
+        ok: result.status === 0,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+    };
+}
+/** The output of a git command, or null when the command failed. */
+export function gitText(cwd, args) {
+    const result = runGit(cwd, args);
+    return result.ok ? result.stdout : null;
+}
+/**
+ * The commits of a repository, newest first.
+ *
+ * `git log` is asked for the sha, the timestamp and the body of the message
+ * in one pass. The three are separated by characters that cannot occur in
+ * them, so a message with a blank line in it survives the round trip.
+ */
+export function gitCommits(cwd, since) {
+    const output = gitText(cwd, [
+        'log',
+        `--since=${since}`,
+        `--format=%H${UNIT}%at${UNIT}%B${RECORD}`,
+    ]);
+    if (output === null)
+        return [];
+    const commits = [];
+    for (const block of output.split(RECORD)) {
+        const trimmed = block.trim();
+        if (trimmed.length === 0)
+            continue;
+        const parts = trimmed.split(UNIT);
+        const sha = parts[0];
+        const at = parts[1];
+        if (sha === undefined || at === undefined)
+            continue;
+        const timestamp = Number(at);
+        if (!Number.isFinite(timestamp))
+            continue;
+        commits.push({ sha, at: timestamp, message: parts.slice(2).join(UNIT) });
+    }
+    return commits;
+}
+/**
+ * The task ids of the `Refs:` trailers of a message.
+ *
+ * The trailer is the link between a commit and the work it did (§6.5): the
+ * pre-commit hook asks for it on an agent commit, and the outcome scanners
+ * read it back. A message with no trailer names no task, and a trailer that
+ * names nothing is not a trailer.
+ */
+export function refsTrailers(message) {
+    const refs = [];
+    for (const line of message.split('\n')) {
+        const match = /^\s*Refs:\s*(\S+)\s*$/.exec(line);
+        const taskId = match?.[1];
+        if (taskId !== undefined)
+            refs.push(taskId);
+    }
+    return refs;
+}
+//# sourceMappingURL=git.js.map

package/dist/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C;;;;;;GAMG;AAEH,sDAAsD;AACtD,MAAM,IAAI,GAAG,QAAQ,CAAC;AACtB,yCAAyC;AACzC,MAAM,MAAM,GAAG,QAAQ,CAAC;AAExB;;;;;;;;;;GAUG;AACH,MAAM,mBAAmB,GAAG;IAC1B,SAAS;IACT,eAAe;IACf,gBAAgB;IAChB,gBAAgB;IAChB,sBAAsB;IACtB,kCAAkC;IAClC,yBAAyB;IACzB,YAAY;IACZ,eAAe;CAChB,CAAC;AAEF,iFAAiF;AACjF,SAAS,QAAQ;IACf,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvD,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,IAAI,mBAAmB,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,SAAS;QAChD,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACnB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AASD;;;;;;;GAOG;AACH,MAAM,UAAU,MAAM,CAAC,GAAW,EAAE,IAAc;IAChD,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE;QACpC,GAAG;QACH,QAAQ,EAAE,MAAM;QAChB,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;QAC3B,GAAG,EAAE,QAAQ,EAAE;KAChB,CAAC,CAAC;IACH,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;IACjE,CAAC;IACD,OAAO;QACL,EAAE,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;QAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;KAC5B,CAAC;AACJ,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,OAAO,CAAC,GAAW,EAAE,IAAc;IACjD,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1C,CAAC;AAYD;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,KAAa;IACnD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE;QAC1B,KAAK;QACL,WAAW,KAAK,EAAE;QAClB,cAAc,IAAI,MAAM,IAAI,KAAK,MAAM,EAAE;KAC1C,CAAC,CAAC;IACH,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAE/B,MAAM,OAAO,GAAgB,EAAE,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACnC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAClC,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACrB,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,GAAG,KAAK,SAAS,IAAI,EAAE,KAAK,SAAS;YAAE,SAAS;QACpD,MAAM,SAAS,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;QAC7B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC;YAAE,SAAS;QAC1C,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;QAC1B,IAAI,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/git.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=git.test.d.ts.map

package/dist/git.test.d.ts.map

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