@telora/daemon 0.22.189 → 0.22.208

package/dist/migrations/migration-inventory.js

@@ -0,0 +1,253 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: packages/daemon/src/focus/migration-claim-pass.test.ts,
+//   packages/daemon/src/migrations/migration-claim-lifecycle.test.ts,
+//   packages/daemon/src/migrations/migration-inventory.test.ts
+// PINNED-BY-END
+/**
+ * What a git REF holds in a product's declared migration namespace.
+ *
+ * WHY IT READS THE GIT TREE AND NEVER A WORKING TREE
+ * --------------------------------------------------
+ * The whole point of this module is to answer the question for a branch that is
+ * NOT checked out. Two focuses are armed concurrently on one product, each in
+ * its own worktree; the allocator that grants a migration number has to know
+ * what the OTHER focus's branch already holds, and the daemon never checks that
+ * branch out. So every read here is `git ls-tree` / `git show` against a ref.
+ *
+ * A reader that looked at a working tree could only ever see the branch it is
+ * standing on -- which is exactly the blind spot that lets two teams take the
+ * same number.
+ *
+ * WHY THE OUTCOMES ARE KEPT DISTINCT
+ * ----------------------------------
+ * This reader answers with one of five things, and collapsing any pair of them
+ * breaks a consumer:
+ *
+ *   - `undeclared`          -- the product ships no `telora.migrations.json`.
+ *                              It opted out. Its teams keep numbering as they
+ *                              do today; nothing should hold or refuse.
+ *   - `declarationUnreadable` -- a declaration EXISTS and is broken. A claim
+ *                              against this product must be REFUSED with the
+ *                              reason, not granted a guessed number.
+ *   - `refAbsent`           -- the ref does not exist (a deleted branch, a stale
+ *                              `branch_name`). It CLAIMS NOTHING. Holding here
+ *                              would let one stale row block every future claim
+ *                              on the product.
+ *   - `refUnreadable`       -- the ref exists and could not be read. It PROVES
+ *                              NOTHING. This is the one that must hold: read as
+ *                              an empty inventory it would say "every number is
+ *                              free", failing open on precisely the question
+ *                              this reader exists to answer.
+ *   - `read`                -- the ordinals, tags and journal entries the ref
+ *                              holds. Possibly EMPTY, which is a real answer:
+ *                              "this ref holds no migrations".
+ *
+ * The last two are the load-bearing pair. `refAbsent` and `refUnreadable` are
+ * both "git said no", and a reader that returned one kind for both would force
+ * its caller either to hold on a deleted branch forever or to treat an I/O
+ * failure as proof of absence. So absence is POSITIVELY ESTABLISHED rather than
+ * inferred from a non-zero exit: `probeRefExists` is three-valued, and only a
+ * healthy repository that still cannot resolve the ref yields `refAbsent`.
+ * Everything else -- including a probe that itself failed -- is `refUnreadable`.
+ * Both probes run only on the failure path, so the happy path pays nothing.
+ *
+ * SCOPE: THIS IS A READER
+ * -----------------------
+ * It answers "what does this ref hold?" for ONE ref. It does not compare two
+ * refs, judge a merge, or render a notice -- a comparison at the merge is the
+ * shape this focus abandoned (two teams told to renumber from the same union at
+ * the same moment collide again). The allocator consumes this to compute a
+ * candidate; nothing here decides anything.
+ *
+ * WHY THE GIT PRIMITIVE COMES FROM daemon-core
+ * --------------------------------------------
+ * `runGit` is taken from `@telora/daemon-core` rather than the daemon's own
+ * `git/types.ts` wrapper: this area is a rank-0 leaf in
+ * `scripts/daemon-layer-ranks.json` and `git/` sits above it, so importing the
+ * wrapper would be an upward import. The wrapper adds only a default timeout,
+ * which is passed explicitly here.
+ *
+ * @module migration-inventory
+ */
+import { runGit, DEFAULT_GIT_TIMEOUT_MS, } from '@telora/daemon-core';
+import { readMigrationManifest, } from './migration-manifest.js';
+/** Real git + real declaration reader. */
+export function defaultMigrationInventoryDeps() {
+    return {
+        runGit: (args, repoPath) => runGit(args, repoPath, DEFAULT_GIT_TIMEOUT_MS),
+        readManifest: (repoPath, fs) => readMigrationManifest(repoPath, fs),
+    };
+}
+/**
+ * Parse a journal document into its entries.
+ *
+ * Accepts the two shapes the hand-written products ship: a bare array of
+ * entries, or an object carrying an `entries` array. Anything else -- including
+ * an entry missing `idx` or `tag` -- is a parse FAILURE, because a journal we
+ * cannot read is the unreadable state, never an empty registration.
+ */
+export function parseJournal(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        return { error: `not valid JSON (${String(err?.message ?? err)})` };
+    }
+    const rawEntries = Array.isArray(parsed)
+        ? parsed
+        : typeof parsed === 'object' && parsed !== null
+            ? parsed.entries
+            : undefined;
+    if (!Array.isArray(rawEntries)) {
+        return { error: 'expected an array of entries, or an object with an "entries" array' };
+    }
+    const entries = [];
+    for (const [position, raw] of rawEntries.entries()) {
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            return { error: `entry ${position} is not an object` };
+        }
+        const entry = raw;
+        const { idx, tag } = entry;
+        if (typeof idx !== 'number' && typeof idx !== 'string') {
+            return { error: `entry ${position} has no usable "idx" (got ${typeof idx})` };
+        }
+        if (typeof tag !== 'string' || tag.trim() === '') {
+            return { error: `entry ${position} has no usable "tag"` };
+        }
+        entries.push({ idx: String(idx), tag });
+    }
+    return { entries };
+}
+/**
+ * Which of a ref's listed files are migrations, read through the declared
+ * pattern. Pure.
+ *
+ * A file in the migration dir that does NOT match the pattern is not a
+ * migration (a README, a .gitkeep, a `meta/` subdirectory) -- not a failure.
+ */
+export function readMigrationsFromPaths(paths, manifest) {
+    const pattern = new RegExp(manifest.filePattern);
+    const migrations = [];
+    for (const path of paths) {
+        const basename = path.slice(path.lastIndexOf('/') + 1);
+        const match = pattern.exec(basename);
+        const ordinal = match?.groups?.ordinal;
+        const tag = match?.groups?.tag;
+        if (ordinal === undefined || tag === undefined)
+            continue;
+        migrations.push({ ordinal, tag, path });
+    }
+    return migrations;
+}
+/**
+ * Does `ref` name a commit in this repo -- and could we even tell?
+ *
+ * THREE-VALUED ON PURPOSE. `git rev-parse --verify --quiet` exits non-zero for
+ * BOTH a missing ref and an operational failure (a corrupt object store, a
+ * timeout, a repo that is not there). Collapsing those to a boolean is a
+ * fail-OPEN: an unreadable branch is reported as holding nothing, the held set
+ * still reads complete, and the allocator grants a number that branch already
+ * holds -- which is the exact failure the reader exists to prevent.
+ *
+ * ABSENCE MUST BE POSITIVELY ESTABLISHED, and that takes two facts: the
+ * REPOSITORY answers, and the REF does not. So a failed ref probe is followed
+ * by a repo-health probe; only a healthy repo that still cannot resolve the ref
+ * proves the ref is gone. Anything else is `indeterminate`, and the caller
+ * treats that as unreadable.
+ *
+ * `--quiet` suppresses git's missing-ref message, so a genuine absence writes
+ * NOTHING to stderr. Output on stderr is therefore a second, independent signal
+ * that something operational went wrong, and is honoured even if the health
+ * probe happens to pass.
+ *
+ * Called ONLY after a read of the ref has already failed, so the happy path
+ * pays nothing for the distinction.
+ */
+export function probeRefExists(repoPath, ref, deps) {
+    const probe = deps.runGit(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], repoPath);
+    if (probe.success)
+        return 'present';
+    // Under --quiet a missing ref is silent; anything git said is operational.
+    if (probe.error.trim() !== '')
+        return 'indeterminate';
+    // The ref did not resolve. Can the REPOSITORY still answer at all?
+    const health = deps.runGit(['rev-parse', '--git-dir'], repoPath);
+    return health.success ? 'absent' : 'indeterminate';
+}
+/** Everything git printed about a failure, or a generic note when it printed nothing. */
+function gitFailureText(result) {
+    return result.error.trim() || result.output.trim() || 'git failed with no output';
+}
+/** Read the journal the declaration names at `ref`; undefined when none is declared. */
+function readJournalAtRef(repoPath, ref, manifest, deps) {
+    if (manifest.journal === undefined)
+        return { entries: undefined };
+    const journalPath = manifest.journal.path;
+    const shown = deps.runGit(['show', `${ref}:${journalPath}`], repoPath);
+    if (!shown.success) {
+        return {
+            error: `the journal ${journalPath} could not be read at ${ref} (${gitFailureText(shown)})`,
+        };
+    }
+    const parsed = parseJournal(shown.output);
+    if ('error' in parsed) {
+        return { error: `the journal ${journalPath} at ${ref} could not be parsed: ${parsed.error}` };
+    }
+    return { entries: parsed.entries };
+}
+/**
+ * What `ref` holds in `repoPath`'s declared migration namespace.
+ *
+ * Never throws. A malformed declaration, a missing ref, a failed git call and an
+ * unparseable journal each come back as their OWN kind, so a caller can refuse
+ * on a broken declaration, ignore an absent ref, and hold on an unreadable one
+ * without having to guess which it got.
+ *
+ * @param repoPath The product's repo root (`config.products[].repoPath`).
+ * @param ref      Any git ref -- a branch name or a sha. Need not be checked out.
+ * @param deps     Injectable git + declaration seams; defaults to the real ones.
+ */
+export function readMigrationInventory(repoPath, ref, deps = defaultMigrationInventoryDeps()) {
+    let manifest;
+    try {
+        manifest = deps.readManifest(repoPath);
+    }
+    catch (err) {
+        return { kind: 'declarationUnreadable', reason: String(err?.message ?? err) };
+    }
+    if (manifest === undefined)
+        return { kind: 'undeclared' };
+    const listed = deps.runGit(['ls-tree', '-r', '--name-only', ref, '--', manifest.dir], repoPath);
+    if (!listed.success) {
+        // git said no. Which no? A branch that is gone holds nothing; a branch that
+        // could not be read proves nothing. Only the second may hold a caller -- and
+        // ONLY a positively established absence takes the first path. An
+        // indeterminate probe is a failure, never an absence.
+        const probe = probeRefExists(repoPath, ref, deps);
+        if (probe === 'absent')
+            return { kind: 'refAbsent', ref };
+        return {
+            kind: 'refUnreadable',
+            ref,
+            reason: probe === 'indeterminate'
+                ? `${ref} could not be read, and whether it exists could not be established `
+                    + `(${gitFailureText(listed)})`
+                : `the migrations under ${manifest.dir} could not be listed at ${ref} `
+                    + `(${gitFailureText(listed)})`,
+        };
+    }
+    const paths = listed.output.split('\n').map((line) => line.trim()).filter(Boolean);
+    const journal = readJournalAtRef(repoPath, ref, manifest, deps);
+    if ('error' in journal)
+        return { kind: 'refUnreadable', ref, reason: journal.error };
+    return {
+        kind: 'read',
+        inventory: {
+            ref,
+            migrations: readMigrationsFromPaths(paths, manifest),
+            journal: journal.entries,
+        },
+    };
+}
+//# sourceMappingURL=migration-inventory.js.map

package/dist/migrations/migration-inventory.js.map

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

package/dist/migrations/migration-manifest.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Filename of the repo-committed migration declaration, at the REPO ROOT.
+ *
+ * Repo-root for the same reason `telora.verify.json` is: `.gitignore` excludes
+ * `.telora/` wholesale and git cannot re-include a file whose parent directory
+ * is excluded, so a declaration nested there could never be tracked.
+ */
+export declare const MIGRATION_MANIFEST_FILENAME = "telora.migrations.json";
+/**
+ * How a product's migration numbers are chosen -- the field the allocator
+ * branches on.
+ *
+ * `sequential`: the number IS the position in a strictly ordered sequence; the
+ * next free one is the highest held plus one.
+ * `timestamp`: the number is the moment the migration was authored; the next
+ * one is the current time in the declared format.
+ */
+export type MigrationScheme = 'sequential' | 'timestamp';
+/** Every scheme this reader accepts, in the order an error message lists them. */
+export declare const MIGRATION_SCHEMES: readonly MigrationScheme[];
+/**
+ * How a journal file registers migrations, when the repo has one.
+ *
+ * `path` is repo-relative. The file's CONTENT shape is the drizzle journal the
+ * hand-written products already use: either a bare array of entries, or an
+ * object with an `entries` array, each entry carrying an `idx` and a `tag`.
+ * Reading that content is the ref reader's job, not this module's -- here the
+ * repo only says WHERE the journal is.
+ */
+export interface MigrationJournalDeclaration {
+    /** Repo-relative path of the journal file. */
+    path: string;
+}
+/** A repo's declared migration numbering. */
+export interface MigrationManifest {
+    /** Repo-relative directory holding the migration files. */
+    dir: string;
+    /**
+     * Pattern matched against each migration's BASENAME, with two named capture
+     * groups: `ordinal` (the migration's number) and `tag` (its name).
+     */
+    filePattern: string;
+    /** Whether numbers are positions in a sequence or authoring timestamps. */
+    scheme: MigrationScheme;
+    /** The journal that registers migrations, when the repo keeps one. */
+    journal?: MigrationJournalDeclaration;
+}
+/**
+ * Injectable file-system seam (existence + read), mirroring
+ * `verification-manifest.ts`. Tests pass fakes; no consumer has to touch a real
+ * repo to exercise the reader.
+ */
+export interface MigrationManifestFs {
+    /** True iff a readable declaration exists at `path`. */
+    exists(path: string): boolean;
+    /** Read `path` as UTF-8 text. May throw (an unreadable declaration is loud). */
+    readText(path: string): string;
+}
+/** Real-fs default for {@link MigrationManifestFs}. */
+export declare const defaultMigrationManifestFs: MigrationManifestFs;
+/** Absolute path of the migration declaration for a repo. */
+export declare function resolveMigrationManifestPath(repoPath: string): string;
+/**
+ * Thrown when a declaration EXISTS and cannot be read.
+ *
+ * A distinct class, not a bare Error, because the difference between "this
+ * product declared nothing" and "this product's declaration is broken" has to
+ * survive all the way to the team that asked for a number: the first is a
+ * product that opted out, the second is a bug someone must fix. A consumer that
+ * cannot tell them apart can only collapse both into a guess.
+ */
+export declare class MigrationManifestError extends Error {
+    /** Absolute path of the declaration that could not be read. */
+    readonly manifestPath: string;
+    constructor(manifestPath: string, problem: string);
+}
+/**
+ * Read the repo's migration declaration.
+ *
+ * @param repoPath Product repo root (`configForProduct` sets this per product).
+ *                 Undefined => no repo to read => `undefined`.
+ * @param fs       Injectable fs seam; defaults to real fs.
+ * @returns The parsed declaration, or `undefined` when the repo declares no
+ *          migration numbering at all.
+ * @throws  {@link MigrationManifestError} naming the file path when the
+ *          declaration exists but is unreadable / not JSON / not an object /
+ *          missing `dir`, `scheme` or a `filePattern` carrying both named
+ *          groups / carrying a malformed `journal`.
+ */
+export declare function readMigrationManifest(repoPath: string | undefined, fs?: MigrationManifestFs): MigrationManifest | undefined;
+/**
+ * The ordinal width the DECLARATION fixes, or null when it fixes none.
+ *
+ * WHY THE DECLARATION IS ASKED THIS AT ALL. A journal registers `idx` as a bare
+ * number (351) while the filename carries it padded (`0351`), so unioning the
+ * two needs a width to normalise to. The filenames were the only source of one
+ * -- and a ref whose only surviving evidence is a journal entry (files removed,
+ * a journal written ahead of them) has no filenames. The raw `351` then went
+ * into the held set, the candidate rule read the width of what it was given,
+ * derived 3, and proposed `352` on a product whose migrations must match
+ * `^\d{4}`. A number that cannot be the name of a migration on this product is
+ * worse than a refusal: it is granted, written, and discovered by whoever runs
+ * the migrations.
+ *
+ * The declaration knew the width the whole time. `^(?<ordinal>\d{4})_` says
+ * four digits, and it says it authoritatively: a filename of any other width
+ * does not match the pattern, so no inventoried file can disagree with it.
+ *
+ * Null when the pattern does not FIX a width (`\d+`, a character class, an
+ * alternation). Then the filenames are the authority, as they were -- this adds
+ * a source, it does not replace one.
+ */
+export declare function declaredOrdinalWidth(filePattern: string): number | null;
+//# sourceMappingURL=migration-manifest.d.ts.map

package/dist/migrations/migration-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-manifest.d.ts","sourceRoot":"","sources":["../../src/migrations/migration-manifest.ts"],"names":[],"mappings":"AA4FA;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,2BAA2B,CAAC;AAEpE;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,WAAW,CAAC;AAEzD,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,EAAE,SAAS,eAAe,EAAgC,CAAC;AAEzF;;;;;;;;GAQG;AACH,MAAM,WAAW,2BAA2B;IAC1C,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,MAAM,EAAE,eAAe,CAAC;IACxB,sEAAsE;IACtE,OAAO,CAAC,EAAE,2BAA2B,CAAC;CACvC;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC;AAED,uDAAuD;AACvD,eAAO,MAAM,0BAA0B,EAAE,mBAGxC,CAAC;AAEF,6DAA6D;AAC7D,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAElB,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAWlD;AAiGD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,EAAE,GAAE,mBAAgD,GACnD,iBAAiB,GAAG,SAAS,CAkC/B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWvE"}