@12ui/design 0.2.15 → 0.2.16

package/dist/conversion-receipt-store.js

@@ -0,0 +1,143 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, rm, writeFile, } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * Where a user's conversion receipts live, and the only code that touches those
+ * files.
+ *
+ * The records are per USER, not per image: the same approved design converted
+ * from a downloads folder, a run directory, and a project checkout is the same
+ * bytes and the same paid conversion, and a receipt written beside each copy
+ * both litters the user's directories and misses every copy it was not written
+ * beside. So the store is keyed by what actually identifies the work — the
+ * digest of the submitted bytes and the model that converted them — and lives
+ * under the 12ui home.
+ *
+ * `~/.12ui` is that home. Credentials sit in the config root
+ * (`~/.config/12ui/credentials.json`) because they are configuration, and the
+ * managed CLI installs itself into the data root (`~/.local/share/12ui`)
+ * because it is installed software; a receipt is neither. It is per-user
+ * runtime evidence the CLI can always re-buy, and `~/.12ui` is where this
+ * codebase already keeps per-user 12ui runtime state (`legacy-codex-cleanup.ts`
+ * reads `~/.12ui/codex-design`). `TWELVE_UI_HOME` overrides it wholesale, which
+ * is what a test — or a user with a shared home — points somewhere else.
+ *
+ * Shape: one small JSON file per key, never one appended log. A point lookup
+ * reads exactly the record it wants instead of the whole history; a withdrawal
+ * unlinks one file instead of rewriting the log; and two CLI invocations
+ * running at once — the common case, since branch runs are launched in
+ * parallel — never contend for a single file, so no lock is needed. Every write
+ * lands through a temp file and a rename, so a reader either sees the previous
+ * record or the new one and never a half-written one.
+ */
+export const TWELVE_UI_HOME_ENV = 'TWELVE_UI_HOME';
+export const TWELVE_UI_HOME_DIRECTORY_NAME = '.12ui';
+export const CONVERSION_RECEIPT_STORE_DIRECTORY_NAME = 'conversions';
+/** How many records one invocation is willing to inspect while pruning. */
+export const CONVERSION_RECEIPT_PRUNE_LIMIT = 64;
+export const resolveTwelveUiHome = (environment = process.env, homeDirectory = os.homedir()) => {
+    const explicit = environment[TWELVE_UI_HOME_ENV]?.trim();
+    return explicit
+        ? path.resolve(explicit)
+        : path.join(homeDirectory, TWELVE_UI_HOME_DIRECTORY_NAME);
+};
+export const resolveConversionReceiptStore = (environment = process.env, homeDirectory = os.homedir()) => path.join(resolveTwelveUiHome(environment, homeDirectory), CONVERSION_RECEIPT_STORE_DIRECTORY_NAME);
+/**
+ * The key, as a filename. The digest is already filename-safe and is checked
+ * before it is used; the model is whatever the server called itself, so it is
+ * reduced to the same alphabet rather than trusted to be one path segment.
+ */
+export const conversionReceiptRecordName = (key) => {
+    if (!/^[a-f0-9]{64}$/u.test(key.sha256)) {
+        throw new Error('A conversion receipt key needs the sha256 of the bytes that were submitted');
+    }
+    const model = key.model.replace(/[^A-Za-z0-9._-]/gu, '_');
+    if (!model)
+        throw new Error('A conversion receipt key needs the model that converted the bytes');
+    return `${key.sha256}.${model}.json`;
+};
+export const conversionReceiptRecordPath = (store, key) => path.join(store, conversionReceiptRecordName(key));
+/** A missing, unreadable, or unparseable record is simply no record. */
+export const readConversionReceiptRecord = async (store, key) => {
+    try {
+        return JSON.parse(await readFile(conversionReceiptRecordPath(store, key), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Atomic replace. The temp file is created exclusively under a unique name so
+ * two invocations writing the same key at the same time cannot land in each
+ * other's buffer, and the rename is what any concurrent reader observes.
+ */
+export const writeConversionReceiptRecord = async (store, key, record) => {
+    const target = conversionReceiptRecordPath(store, key);
+    await mkdir(store, { recursive: true, mode: 0o700 });
+    const temporary = path.join(store, `.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, {
+            encoding: 'utf8',
+            flag: 'wx',
+            mode: 0o600,
+        });
+        await rename(temporary, target);
+        return target;
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+};
+/** Null when there was nothing to remove; removal is never an error. */
+export const removeConversionReceiptRecord = async (store, key) => {
+    const target = conversionReceiptRecordPath(store, key);
+    try {
+        await rm(target);
+        return target;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Bounded expiry hygiene, run on the invocations that already touch the store.
+ *
+ * A conversion lives about a day and a store record outlives it by however long
+ * the user goes without converting, so without this the store only grows. It
+ * inspects at most `limit` records per call, starting at a rotating offset, so
+ * a large store costs the same as a small one per invocation and is still swept
+ * completely over several. Only records the caller's predicate calls expired
+ * are removed — anything this version cannot read is left alone, because an
+ * unreadable record is as likely to belong to a newer CLI as to be junk.
+ */
+export const pruneConversionReceiptRecords = async (args) => {
+    let names;
+    try {
+        names = (await readdir(args.store)).filter((name) => name.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    if (names.length === 0)
+        return [];
+    const limit = Math.max(1, args.limit ?? CONVERSION_RECEIPT_PRUNE_LIMIT);
+    const start = names.length <= limit ? 0 : Math.floor(Math.random() * names.length);
+    const sampled = Array.from({ length: Math.min(limit, names.length) }, (_unused, index) => names[(start + index) % names.length]);
+    const removed = await Promise.all(sampled.map(async (name) => {
+        const file = path.join(args.store, name);
+        try {
+            const record = JSON.parse(await readFile(file, 'utf8'));
+            if (!args.expired(record))
+                return null;
+            await rm(file, { force: true });
+            return file;
+        }
+        catch {
+            return null;
+        }
+    }));
+    return removed.filter((entry) => entry !== null);
+};
+//# sourceMappingURL=conversion-receipt-store.js.map

package/dist/conversion-receipt-store.js.map

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

package/dist/conversion-receipt.d.ts

@@ -1,5 +1,7 @@
 import type { ConversionOperation } from './conversion-client.js';
 import type { ConversionOutput } from './conversion-outputs.js';
+import { type ConversionReceiptKey } from './conversion-receipt-store.js';
+import type { PackageSubmissionResult } from './package-submission.js';
 /**
  * The single owner of "an image's conversion was already bought, and here is
  * the proof".
@@ -14,14 +16,30 @@ import type { ConversionOutput } from './conversion-outputs.js';
  * the upload — so a false claim is a failed page, not a cheap win.
  *
  * This is therefore a receipt of a proved fact, not a cache: it records the
- * digest of the exact bytes a succeeded conversion was admitted with, next to
- * the image those bytes came from. A later run reuses it only when the bytes it
- * is about to submit hash identically. Absent proof it converts fresh.
+ * digest of the exact bytes a succeeded conversion was admitted with. A later
+ * run reuses it only when the bytes it is about to submit hash identically.
+ * Absent proof it converts fresh.
  *
- * Both `12ui convert` and `12ui branch execute --convert` write it, and only
- * this module decides what counts as proof.
+ * The records live in the per-user store (`conversion-receipt-store.ts`), keyed
+ * by that digest and the model, because the fact is about bytes and not about
+ * where a copy of them happens to sit. `12ui convert`, `12ui convert package`,
+ * and `12ui branch execute --convert` write them, `12ui branch execute
+ * --convert` reads them, and only this module decides what counts as proof.
+ *
+ * SUNSET — legacy sidecars. Receipts shipped in 0.2.15 as
+ * `<image>.conversion.json` written beside the input image. Those files are
+ * still READ beside a winner image for one release cycle and migrated into the
+ * store the first time they are seen, so an upgrade never re-buys a conversion
+ * a 0.2.15 convert already paid for. Nothing writes them any more. Delete the
+ * legacy read path — `LEGACY_CONVERSION_RECEIPT_SUFFIX`,
+ * `legacyConversionReceiptPath`, `readLegacyConversionReceipts`, and the
+ * `legacyImagePaths` argument of `invalidateConversionReceipts` — one release
+ * after 0.2.16; by then every receipt a 0.2.15 convert wrote has long outlived
+ * the ~24h conversion it names.
  */
-export declare const CONVERSION_RECEIPT_SUFFIX = ".conversion.json";
+export declare const LEGACY_CONVERSION_RECEIPT_SUFFIX = ".conversion.json";
+export type { ConversionReceiptKey } from './conversion-receipt-store.js';
+export { resolveConversionReceiptStore } from './conversion-receipt-store.js';
 /**
  * The output an attachable conversion must have produced. A package converts
  * every viewport to a LayerDoc and buys the page export separately, so the
@@ -34,8 +52,9 @@ export declare const REUSABLE_CONVERSION_OUTPUT: ConversionOutput;
  * attachment expiring within this window (`PACKAGE_SOURCE_MINIMUM_REMAINING_MS`)
  * because composition reads the source run at the END of a package drive, and
  * that refusal fails the page after its screens are already paid for.
- * Conversions live 24h while a receipt sits beside a user's image indefinitely,
- * so an expiry that is not checked here is a page failure waiting for day two.
+ * Conversions live 24h while a stored receipt sits in the user's home
+ * indefinitely, so an expiry that is not checked here is a page failure waiting
+ * for day two.
  */
 export declare const CONVERSION_REUSE_MINIMUM_REMAINING_MS: number;
 export type ConversionReceipt = {
@@ -46,11 +65,12 @@ export type ConversionReceipt = {
     /** A reused conversion must have run the model the package declares. */
     model: string;
     /**
-     * The operation that bought it: a branch run id, or for `12ui convert` the
-     * conversion's own id. An operation never reuses its own receipt — a branch
-     * package key is derived per run and page, so attaching a reuse on a resume
-     * would change the request body under a key the server already settled, which
-     * is `409 idempotency_conflict` on a page that was already paid for.
+     * The operation that bought it: a branch run id, a package id, or for
+     * `12ui convert` the conversion's own id. An operation never reuses its own
+     * receipt — a branch package key is derived per run and page, so attaching a
+     * reuse on a resume would change the request body under a key the server
+     * already settled, which is `409 idempotency_conflict` on a page that was
+     * already paid for.
      */
     boughtBy: string;
     /** When the referenced conversion stops being attachable at all. */
@@ -58,41 +78,50 @@ export type ConversionReceipt = {
     createdAt: string;
 };
 export type ConversionReceiptWrite = {
-    written: string[];
-    failures: {
+    /** Where the record landed, or null when nothing was written. */
+    path: string | null;
+    failure?: {
         path: string;
         detail: string;
-    }[];
+    };
 };
-export declare const conversionReceiptPath: (imagePath: string) => string;
-/** A missing or unreadable receipt is simply no proof, never an error. */
-export declare const readConversionReceipt: (imagePath: string) => Promise<ConversionReceipt | undefined>;
-export declare const readConversionReceipts: (imagePaths: readonly string[]) => Promise<ConversionReceipt[]>;
+/** Where 0.2.15 wrote a receipt. Read for one release cycle, never written. */
+export declare const legacyConversionReceiptPath: (imagePath: string) => string;
+export declare const conversionReceiptKey: (receipt: ConversionReceipt) => ConversionReceiptKey;
 /**
- * Written next to every local copy of the bytes it describes, so the next run
- * that starts from the same approved design finds it wherever it reads that
- * design from. A write that fails is not a command failure: the receipt is an
- * optimisation, and its absence only costs one conversion. Callers that can say
- * so report the failures; the rest ignore them.
+ * The stored record for exactly these bytes and this model, or nothing.
+ *
+ * An expired record is removed as it is read: it is the one expired record this
+ * invocation is certain about, and leaving it would have the next run read it
+ * again to reach the same conclusion.
  */
-export declare const writeConversionReceipts: (imagePaths: readonly string[], receipt: ConversionReceipt) => Promise<ConversionReceiptWrite>;
+export declare const readStoredConversionReceipt: (key: ConversionReceiptKey, options?: {
+    store?: string;
+    now?: Date;
+}) => Promise<ConversionReceipt | undefined>;
 /**
- * Withdraw a receipt the SERVER disproved, so the next run does not repeat the
- * dance the last one already paid a retry for.
- *
- * The bar is deliberately narrow: only an explicit refusal of the attachment at
- * admission — the server having read the referenced conversion's durable
- * evidence and rejected the claim — is proof that this receipt is no longer
- * proof of anything. A network error, a timeout, or any other transient failure
- * says nothing about the referenced conversion, and deleting on one of those
- * would throw away a live receipt and buy its conversion again for nothing.
+ * Record a proved conversion. A write that fails is not a command failure: the
+ * receipt is an optimisation, and its absence only costs one conversion.
+ * Callers that can say so report the failure; the rest ignore it.
+ */
+export declare const recordConversionReceipt: (receipt: ConversionReceipt, options?: {
+    store?: string;
+    now?: Date;
+}) => Promise<ConversionReceiptWrite>;
+/**
+ * The 0.2.15 sidecars beside these images, carried forward.
  *
- * Only receipts naming the disproven conversion are removed: a newer receipt
- * beside the same image describes different work and is untouched. Removal is
- * best-effort, because a receipt that cannot be deleted only costs the next run
- * one refused attachment and one retry — the same price this run paid.
+ * Every one that is still live is copied into the store the moment it is seen,
+ * so the upgrade costs nothing and the next run finds the proof by digest no
+ * matter which copy of the image it starts from. An existing store record wins:
+ * it was written by a later command about the same bytes, and overwriting it
+ * with the sidecar would replace a fresher expiry with an older one. Migration
+ * is best-effort — the receipt is still honoured this run either way.
  */
-export declare const invalidateConversionReceipts: (imagePaths: readonly string[], conversionId: string) => Promise<string[]>;
+export declare const readLegacyConversionReceipts: (imagePaths: readonly string[], options?: {
+    store?: string;
+    now?: Date;
+}) => Promise<ConversionReceipt[]>;
 /**
  * The proof gate. Every condition is a fact about the bytes in hand, never an
  * assumption about what an earlier command probably did.
@@ -106,22 +135,89 @@ export declare const reusableConversionId: (args: {
     boughtBy: string;
     now?: Date;
 }) => string | undefined;
+/**
+ * The gate, over the store and over whatever the caller already holds.
+ *
+ * The store is consulted first because it is the record every command writes;
+ * the in-hand receipts are the 0.2.15 sidecars this run read beside the winner,
+ * which stay proof for one release cycle even if their migration failed.
+ */
+export declare const findReusableConversionId: (args: {
+    sha256: string;
+    model: string;
+    boughtBy: string;
+    receipts?: readonly ConversionReceipt[];
+    store?: string;
+    now?: Date;
+}) => Promise<string | undefined>;
+/**
+ * Withdraw a receipt the SERVER disproved, so the next run does not repeat the
+ * dance the last one already paid a retry for.
+ *
+ * The bar is deliberately narrow: only an explicit refusal of the attachment at
+ * admission — the server having read the referenced conversion's durable
+ * evidence and rejected the claim — is proof that this receipt is no longer
+ * proof of anything. A network error, a timeout, or any other transient failure
+ * says nothing about the referenced conversion, and deleting on one of those
+ * would throw away a live receipt and buy its conversion again for nothing.
+ *
+ * Only records naming the disproven conversion are withdrawn: a newer record
+ * under the same key describes different work and is untouched. Removal is
+ * best-effort, because a receipt that cannot be deleted only costs the next run
+ * one refused attachment and one retry — the same price this run paid.
+ */
+export declare const invalidateConversionReceipts: (args: {
+    conversionId: string;
+    /** The keys the disproven claim could have come from. */
+    keys?: readonly ConversionReceiptKey[];
+    /** Sunset: 0.2.15 sidecars beside these images, if they name it. */
+    legacyImagePaths?: readonly string[];
+    store?: string;
+}) => Promise<string[]>;
 /**
  * What `12ui convert` leaves behind for the branch run that follows it.
  *
  * Only a succeeded image-to-LayerDoc conversion can stand in for a package
- * viewport, so anything else writes nothing at all: a receipt for an `html`
+ * viewport, so anything else records nothing at all: a receipt for an `html`
  * conversion would be a claim the server refuses, and the refusal costs a whole
  * page. The digest is of the bytes actually submitted, which is what `--width`
  * normalization changes and what the server admitted the run with.
  */
 export declare const recordConvertedImageReceipt: (args: {
-    /** The file the caller converted; the branch run looks for the receipt here. */
-    imagePath: string;
     /** The EXACT bytes submitted, after any `--width` normalization. */
     bytes: Uint8Array;
     operation: Pick<ConversionOperation, "id" | "status" | "output" | "model" | "expires_at" | "input_kind">;
+    store?: string;
     warn?: (message: string) => void;
     now?: Date;
 }) => Promise<ConversionReceipt | undefined>;
+/**
+ * What `12ui convert package` leaves behind: one receipt per viewport whose own
+ * child conversion the package bought.
+ *
+ * A package converts each viewport to a LayerDoc and composes the page from
+ * those children, so every viewport of a submitted page is exactly the artifact
+ * a later package can attach instead of buying — the same fact the branch path
+ * records for the winner, for every screenshot the user named.
+ *
+ * A viewport that ATTACHED a conversion bought nothing, so it records nothing.
+ * The expiry reported is the package's own, which its children cannot outlive
+ * backwards, and the model is the one the server says it ran; without either
+ * fact nothing here proves a conversion is still attachable, so nothing is
+ * recorded and the caller is told once.
+ */
+export declare const recordPackageConversionReceipts: (args: {
+    pages: readonly {
+        id: string;
+        viewports: readonly {
+            id: string;
+            bytes: Uint8Array;
+            sourceConversionId?: string;
+        }[];
+    }[];
+    result: Pick<PackageSubmissionResult, "packageId" | "model" | "expiresAt" | "pages">;
+    store?: string;
+    warn?: (message: string) => void;
+    now?: Date;
+}) => Promise<ConversionReceipt[]>;
 //# sourceMappingURL=conversion-receipt.d.ts.map

package/dist/conversion-receipt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conversion-receipt.d.ts","sourceRoot":"","sources":["../src/conversion-receipt.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,eAAO,MAAM,yBAAyB,qBAAqB,CAAC;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,gBAA6B,CAAC;AAEvE;;;;;;;GAOG;AACH,eAAO,MAAM,qCAAqC,QAAc,CAAC;AAEjE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,CAAC,CAAC;IACX,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC9C,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,WAAW,MAAM,KAAG,MAEzD,CAAC;AAiBF,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,GAChC,WAAW,MAAM,KAChB,OAAO,CAAC,iBAAiB,GAAG,SAAS,CASvC,CAAC;AAEF,eAAO,MAAM,sBAAsB,GACjC,YAAY,SAAS,MAAM,EAAE,KAC5B,OAAO,CAAC,iBAAiB,EAAE,CAG7B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GAClC,YAAY,SAAS,MAAM,EAAE,EAC7B,SAAS,iBAAiB,KACzB,OAAO,CAAC,sBAAsB,CA+BhC,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,GACvC,YAAY,SAAS,MAAM,EAAE,EAC7B,cAAc,MAAM,KACnB,OAAO,CAAC,MAAM,EAAE,CAalB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM;IACzC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACvC,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ,KAAG,MAAM,GAAG,SAQZ,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,GAAU,MAAM;IACtD,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,EAAE,IAAI,CACb,mBAAmB,EACnB,IAAI,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,GAAG,YAAY,CACnE,CAAC;IACF,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ,KAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CA6BxC,CAAC"}
+{"version":3,"file":"conversion-receipt.d.ts","sourceRoot":"","sources":["../src/conversion-receipt.ts"],"names":[],"mappings":"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"}