bareloop 0.24.0 → 0.25.1

package/src/validate.js

@@ -154,6 +154,21 @@ export const SECRET_PATTERNS = [
 ];
 const SECRET_RE = new RegExp(SECRET_PATTERNS.map((r) => r.source).join('|'));
 
+/** Human-readable name for each entry in `SECRET_PATTERNS`, SAME order, SAME
+ * length — for a caller that must name WHICH shape matched (a refusal
+ * message, an audit line) without ever printing the matched text itself. Kept
+ * beside the inventory it describes rather than hand-typed at each call site,
+ * for the same reason `scanSecrets`/`redactSecrets` are: a second, drifting
+ * copy is how a name and its pattern come apart. */
+export const SECRET_PATTERN_NAMES = [
+  'sk- prefixed API key',
+  'GitHub personal access token (ghp_)',
+  'GitHub fine-grained PAT (github_pat_)',
+  'AWS access key ID (AKIA)',
+  'Slack token (xox)',
+  'Google/Gemini API key (AIza)',
+];
+
 /**
  * Scan a RAW text stream (a spine file, a close's output, a transcript) for
  * known secret shapes and return the literal matches. The ONE spelling of the

package/types/index.d.ts

@@ -29,3 +29,4 @@ export { runInterview, authorCloseForJob, assembleSpec, prepareSigning, refusalE
 export { PROMPT_REGISTERS, isPromptFile } from "./promptregisters.js";
 export { exportBundle, bundleHash, readBundle, resolveBundleSpec, checkEnvelope, bless, verifyBlessing, appendHistory, checkBundleDeps } from "./bundle.js";
 export { readCloseScripts, checkCloseAbsolutePaths, absolutePathLiteralsOf, hashCloseScriptBytes, checkCloseByteSignature, checkStageByteSignature, signCloseScripts } from "./close-integrity.js";
+export { prepareSource, proveDestination, copyOut, readSourceManifest, frontDoorFromManifest, datedDestination, pickDelivery } from "./source.js";

package/types/kinds.d.ts

@@ -49,6 +49,32 @@ export function doorOpens(job: any, reviewDoor?: boolean | null): boolean;
  * @returns {any[]}
  */
 export function mechanicalStages(stages: any[] | null | undefined): any[];
+/**
+ * git, in a repository (reads by every caller in this file; `src/source.js`
+ * also uses it for the hidden-git seed's `init`/`add`/`commit`). Faults come
+ * back as `ok:false` with the stderr — a caller decides whether that is a
+ * stop.
+ *
+ * Exported (PRD item 33/M2, `src/source.js`) so the hidden-git seed a plain
+ * folder/file/URL job runs against goes through the SAME spawn primitive as
+ * every other git call in this file — a second `spawn('git', …)` for the
+ * source front door would be a second instrument with its own timeout and
+ * buffer ceiling to keep in sync with this one.
+ * @param {string} cwd @param {string[]} args
+ */
+export function git(cwd: string, args: string[]): Promise<{
+    ok: boolean;
+    out: string;
+    err: string;
+    code: null;
+    fault: string;
+} | {
+    ok: boolean;
+    out: string;
+    err: string;
+    code: number;
+    fault: "failed";
+}>;
 /**
  * D8's seed, READ rather than typed: HEAD at run start. A close stores the
  * counting rule and never the number (D12), so which commit the run is measured

package/types/source.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Build the frozen source tree — `<into>/tree/input/…` (the copy), `<into>/tree/output/`
+ * (empty, where the run writes), `<into>/source.json` (the manifest, OUTSIDE
+ * the tree so no worker can read or edit it). One hidden git commit seeds the
+ * tree with a neutralized identity; the seed sha rides in the manifest and is
+ * what every close in this run measures against (`seedAtHead`, src/kinds.js).
+ *
+ * `destination`, when given, is recorded in the manifest (never in a signed
+ * job spec — a job spec is a repeatable SHAPE, source/destination a PER-RUN
+ * value, see `readSourceManifest`'s own comment) as the run's declared
+ * drop-off point. D3 rework (hamr's ruling, 2026-09-12, condensed in
+ * `docs/product/ITEM33-BUILD.md`): **destination is a DIRECTORY, never a
+ * filename** — it may already exist (need not be empty), and it may sit
+ * inside the source itself (the same-dir case: "i can limit your actions to
+ * a certain fix in a certain dir and your output will also be there"). A job
+ * may produce more than one file; the agent names them, and `copyOut`
+ * delivers every non-empty file it finds under `output/`, each under its own
+ * dated name. There is therefore no separate `output` field any more — the
+ * old single-file `output-invalid` guard existed only to stop a
+ * manifest-declared path from escaping the tree, and that vector is closed
+ * structurally now: `copyOut` always reads `output/` itself, never a path a
+ * manifest could have been hand-edited to name.
+ *
+ * A `kind: 'repo'` source's `destination` is a DIFFERENT thing entirely
+ * (hamr: "destination if for code on a green then that would be the place
+ * agent allowed to do changes") — it names the WRITE FENCE inside the copied
+ * repo, the signed `writeScope` field's job (`src/job.js:363`), not a
+ * filesystem drop-off point this door proves or copies into. It is recorded
+ * as declared, unvalidated by `proveDestination`, and `frontDoorFromManifest`
+ * never hands a repo source's destination to `copyOut` — wiring it into
+ * `writeScope` is M3/M4's job, not this one.
+ * @param {{source: string, into: string, destination?: string,
+ *   fetchTimeoutMs?: number}} args `fetchTimeoutMs` is test-only — production
+ *   callers omit it and get `PROVIDER_TIMEOUT_MS`.
+ * @returns {Promise<{stop: null, into: string, tree: string, manifestPath: string, manifest: object}|SourceRefusal>}
+ */
+export function prepareSource({ source, into, destination, fetchTimeoutMs }: {
+    source: string;
+    into: string;
+    destination?: string;
+    fetchTimeoutMs?: number;
+}): Promise<{
+    stop: null;
+    into: string;
+    tree: string;
+    manifestPath: string;
+    manifest: object;
+} | SourceRefusal>;
+/**
+ * The delivered name (M2b fix 4, kept under D3): a destination FILE of
+ * `/home/me/profile.md` lands as `/home/me/profile-2026-09-12.md`, and a
+ * SECOND delivery of the same name the same day as
+ * `profile-2026-09-12-2.md`, `-3`, … (the work-branch collision rule, the same
+ * spelling `prepareWorkBranch` uses). The date is the delivery's, not the
+ * run's: what a person wants to know opening the folder later is when the file
+ * arrived. D3: `destination` here is a FULL FILE PATH inside the destination
+ * DIRECTORY (`copyOut` builds one per output file it delivers) — this
+ * function itself is unchanged from M2b, it is just no longer handed the
+ * bare top-level destination directly.
+ *
+ * Nothing is ever overwritten, which is why the name is computed rather than
+ * taken: a plain `profile.md` would eventually collide with the person's own
+ * file or a previous run's, and the only honest answers to a collision are
+ * "refuse" or "a new name" — hamr picked a new name.
+ * @param {string} destination the absolute FILE path as declared
+ * @param {Date} now
+ * @param {number} n 1 = the plain dated name, 2+ = the same-day suffix
+ * @returns {string}
+ */
+export function datedDestination(destination: string, now: Date, n: number): string;
+/**
+ * The first dated name that is free, or a refusal when every same-day slot up
+ * to `MAX_SAME_DAY` is taken. Used by `copyOut` at delivery time (per output
+ * file) so a same-day repeat delivery of the same name never disagrees with
+ * what "landable" means.
+ * @param {string} destination an absolute FILE path
+ * @param {Date} [now]
+ * @returns {{stop: null, path: string}|SourceRefusal}
+ */
+export function pickDelivery(destination: string, now?: Date): {
+    stop: null;
+    path: string;
+} | SourceRefusal;
+/**
+ * Prove a destination DIRECTORY is landable — $0, mechanical, before any
+ * token spends (PRD item 33 ruling: "source and destination are proven at
+ * job start"). D3 rework (hamr's ruling, 2026-09-12): **destination is a
+ * directory, never a filename** — it may already exist, and need not be
+ * empty (a job may write into a folder that already holds other files, or
+ * even sit inside the source itself, the same-dir case). What this proves is
+ * narrower than the M2/M2b version: only that the directory is USABLE
+ * (exists as a directory and is writable, or can be created) — it can say
+ * nothing about individual delivered FILE names, because those are not known
+ * until the run actually produces them (the agent names its own output
+ * files); per-file same-day collisions are handled at delivery time, inside
+ * `copyOut`, via `pickDelivery`.
+ * @param {unknown} destination absolute directory path
+ * @param {{into: string}} o `into` — the run's own scratch root (prepared by
+ *   `prepareSource`, or a run's own `workdir` when there is no source door);
+ *   the destination may never sit inside it.
+ * @returns {Promise<{stop: null}|SourceRefusal>}
+ */
+export function proveDestination(destination: unknown, { into }: {
+    into: string;
+}): Promise<{
+    stop: null;
+} | SourceRefusal>;
+/**
+ * Copy the run's own output to the proven destination DIRECTORY — once per
+ * file, never overwriting (`COPYFILE_EXCL`, so even a file that appears
+ * between `proveDestination` and here refuses rather than clobbers), on a
+ * minted green only. This function renders no verdict and changes none: a
+ * refusal here is reported beside the green it could not deliver, never
+ * folded back into it.
+ *
+ * D3 rework (hamr's ruling, 2026-09-12): a job may produce MORE THAN ONE
+ * file (his example: a flight search producing one sheet for "SFO→LAX
+ * red-eye" and another for "SFO under $700") — the agent names them
+ * meaningfully, and EVERY non-empty file under `tree/output/` (excluding
+ * `output/.gitkeep`) is delivered, each under its own dated name
+ * (`datedDestination`/`pickDelivery`, M2b fix 4, unchanged). An empty file is
+ * silently skipped (not a delivered result, same judgment M2b made for the
+ * single-file case) rather than refusing the whole batch over one empty
+ * file; the refusal is reserved for the case where NOTHING is left to
+ * deliver at all.
+ *
+ * `into`, when given, is the run's own SCRATCH ROOT (`prepareSource`'s
+ * `into`, of which `tree` is the `tree/` subdirectory) — review finding #3:
+ * a destination sitting inside `<into>` but outside `tree` (e.g. dropped
+ * straight in the scratch area, never inside the frozen tree) must still
+ * refuse `destination-contained`, which a containment check against `tree`
+ * alone cannot see. Omitted, it defaults to `tree` (the pre-fix behaviour),
+ * for direct callers that only ever had a tree, never an `into`.
+ * @param {{tree: string, into?: string, destination: string}} o
+ * @returns {Promise<{stop: null, files: {path: string, bytes: number, sha256: string}[]}|SourceRefusal>}
+ */
+export function copyOut({ tree, into, destination }: {
+    tree: string;
+    into?: string;
+    destination: string;
+}): Promise<{
+    stop: null;
+    files: {
+        path: string;
+        bytes: number;
+        sha256: string;
+    }[];
+} | SourceRefusal>;
+/**
+ * Read a source-door manifest, if one is there. mid-build spec correction
+ * (2026-09-11, the main session, on hamr's question about export): a job
+ * spec is a SHAPE, signed once — source and destination are a PER-RUN value,
+ * the way `bareloop run <bundle> --repo <path>` varies the repo instance
+ * without touching the bundle's signature. Baking an absolute destination
+ * path into `job.js`/`jobSpecHash` would sign one instance where the spec is
+ * meant to describe a repeatable shape, so the run instance lives HERE
+ * instead — the manifest `prepareSource` already writes outside the tree —
+ * and nothing was added to the job schema.
+ *
+ * Absence is reported as absence: a patient the JOBS table points at
+ * directly, never having gone through `prepareSource`, has no manifest, and
+ * that IS "repo jobs untouched" — nothing here invents a destination for a
+ * job that never declared one. A manifest that EXISTS but cannot be read or
+ * parsed is a named stop, never a silent skip: the run has evidence
+ * something is there and wrong, and hiding that is worse than refusing on it.
+ * @param {string} into the manifest's own directory — `<into>/source.json`
+ *   (a run-u-style caller passes `dirname(workdir)`, since `workdir` IS
+ *   `<into>/tree`)
+ * @returns {Promise<{stop: null, present: false, manifest: null}|{stop: null, present: true, manifest: Record<string, any>}|SourceRefusal>}
+ */
+export function readSourceManifest(into: string): Promise<{
+    stop: null;
+    present: false;
+    manifest: null;
+} | {
+    stop: null;
+    present: true;
+    manifest: Record<string, any>;
+} | SourceRefusal>;
+/**
+ * Reduce a `readSourceManifest` success result to the `{destination}` a
+ * runner acts on, or `null` when there is none to act on (no manifest, one
+ * that never declared a destination, or — D3 — a `kind: 'repo'` manifest,
+ * whose `destination` names the WRITE FENCE inside the copied repo, never a
+ * filesystem drop-off point this door proves or copies into: "repo jobs
+ * UNCHANGED", `writeScope` already does that job, `src/job.js:363`). Pure
+ * extraction of the one piece of `run-u.mjs`'s front-door reading that has
+ * any logic in it (the rest is spine emits and control flow) —
+ * unit-testable apart from the script, which is otherwise unreachable
+ * without a live provider key.
+ * @param {{present: boolean, manifest: Record<string, any>|null}} read
+ * @returns {{destination: string}|null}
+ */
+export function frontDoorFromManifest(read: {
+    present: boolean;
+    manifest: Record<string, any> | null;
+}): {
+    destination: string;
+} | null;
+/**
+ * a named, non-throwing stop
+ */
+export type SourceRefusal = {
+    stop: string;
+    code: string;
+};

package/types/validate.d.ts

@@ -226,3 +226,10 @@ export function sweepNestedQuantifiers(root: any, red: (code: string, path: stri
  */
 export const CLOSE_SCRIPT_INTERPRETERS: readonly string[];
 export const SECRET_PATTERNS: RegExp[];
+/** Human-readable name for each entry in `SECRET_PATTERNS`, SAME order, SAME
+ * length — for a caller that must name WHICH shape matched (a refusal
+ * message, an audit line) without ever printing the matched text itself. Kept
+ * beside the inventory it describes rather than hand-typed at each call site,
+ * for the same reason `scanSecrets`/`redactSecrets` are: a second, drifting
+ * copy is how a name and its pattern come apart. */
+export const SECRET_PATTERN_NAMES: string[];