@clossys/launcher 0.3.0 → 0.4.0

package/dist/inventory-choice.js

@@ -0,0 +1,156 @@
+// Writing the hub inventory from the repositories a founder chose on
+// Advisor's repository-choice card (issue #1179), so a founder never
+// hand-writes JSON. `launcher --repositories` is the command; this module
+// decides what that command may write, and never writes anything itself.
+//
+// The chosen ids and the document built from them are validated against
+// docs/contracts/repository-inventory.json (in the public repository;
+// that exact path does not ship in this package, but this package's
+// build packs and ships its own copy of the contract) through the shared
+// contract checker (./inventory-contract.ts) -- the same check every later read of
+// the stored inventory applies, so what this writes, Launcher reads back.
+//
+// An inventory already on disk that names a different set of repositories
+// is never merged into or overwritten silently: the choice is refused, with
+// the difference in counts and positions, unless the caller passes an
+// explicit replace approval (`--replace-inventory`).
+//
+// Every message this module builds -- the refusal and the success line
+// alike -- names a repository only by its position, never by its id: a
+// stored inventory file, and the `--repositories` argument, are both
+// document-shaped input an agent may relay verbatim, and a repository id is
+// exactly the kind of short string a hostile entry could shape as
+// prompt-injection text (see ./inventory-contract.ts's own header). The
+// caller looks the reported position up in its own copy of the inventory
+// file or its own `--repositories` argument to learn which repository it
+// names.
+import { inventoryKey } from "./identity.js";
+import { readInventoryDocument, renderInventoryDocument, validateInventoryDocument, validateInventoryValue } from "./inventory-contract.js";
+/** The command a refusal names for an explicit replace approval. */
+export const REPLACE_INVENTORY_FLAG = "--replace-inventory";
+function repositories(count) {
+    return `${count} ${count === 1 ? "repository" : "repositories"}`;
+}
+/** Added ids are named by their position in the `--repositories` argument, never by the id itself. */
+function listAddedPositions(positions) {
+    return positions.length === 0 ? "" : ` (${positions.map((index) => `--repositories[${index}]`).join(", ")})`;
+}
+/**
+ * Removed ids are named by their position in an inventory's `repositories`
+ * array, never by the id itself. `label` distinguishes which file that
+ * position indexes into: `"stored inventory"` for the refusal, where the
+ * file on disk is still the one the positions were computed against, and
+ * `"replaced inventory"` for the success line after `--replace-inventory`
+ * writes -- by the time that line prints, the file on disk is already the
+ * new one, so reusing "stored inventory" there would point a reader at the
+ * wrong document (#1179).
+ */
+function listRemovedPositions(positions, label) {
+    return positions.length === 0 ? "" : ` (${positions.map((index) => `repositories[${index}] in the ${label}`).join(", ")})`;
+}
+/**
+ * Decides what `launcher --repositories` writes into a hub whose stored
+ * inventory is `onDisk` -- the file's exact bytes, or `null` when there is
+ * none.
+ *
+ * Every comparison uses `inventoryKey(id, hubOwner)`: a bare id names a
+ * repository of the hub's own owner, and letter case is ignored.
+ *
+ * - The chosen ids must form a valid inventory on their own: at least one
+ *   id, each one satisfying the contract's repository id rule, and no two
+ *   naming the same repository. A refusal names positions only.
+ * - The stored inventory is read by the same strict reader, with the same
+ *   owner: one that fails its contract, including one listing a repository
+ *   twice (for example `app` and `<hubOwner>/app`), is replaced only with
+ *   `replace`, and then with the chosen ids alone. It is never merged.
+ * - No inventory, or an empty one: the chosen repositories are written.
+ * - An inventory naming exactly the same repositories: nothing is written.
+ * - An inventory naming a different set: refused, reporting how many
+ *   repositories each side has and the positions that would be added and
+ *   removed (never the ids themselves), unless `replace` is true. A
+ *   replacement keeps each kept repository's existing entry as it was (its
+ *   `packages` included).
+ *
+ * The document to write is checked again by the same reader every later
+ * read uses, before it is returned.
+ */
+export function resolveChosenInventory(onDisk, chosenIds, hubOwner, replace) {
+    if (chosenIds.length === 0) {
+        return { kind: "refuse", message: "--repositories must name at least one repository" };
+    }
+    const chosenCheck = validateInventoryValue({ schemaVersion: 1, repositories: chosenIds.map((id) => ({ id })) }, { hubOwner });
+    if (!chosenCheck.valid)
+        return { kind: "refuse", message: `--repositories is not a valid inventory: ${chosenCheck.reason}` };
+    let entries;
+    let added = chosenIds;
+    let removed = [];
+    let addedPositions = chosenIds.map((_, index) => index);
+    let removedPositions = [];
+    let replaced = "nothing";
+    let previousCount = 0;
+    if (onDisk === null) {
+        entries = chosenIds.map((id) => ({ id }));
+    }
+    else {
+        const stored = readInventoryDocument(onDisk, { hubOwner });
+        if (!stored.valid) {
+            if (!replace) {
+                return {
+                    kind: "refuse",
+                    message: `the hub inventory ${stored.reason}; to replace it with the ${repositories(chosenIds.length)} chosen, run again with ${REPLACE_INVENTORY_FLAG}`,
+                };
+            }
+            entries = chosenIds.map((id) => ({ id }));
+            replaced = "invalid";
+        }
+        else {
+            previousCount = stored.ids.length;
+            // Keys are unique on both sides: the reader and the chosen-id check above both refuse two ids with one key.
+            const storedByKey = new Map(stored.entries.map((entry) => [inventoryKey(entry.id, hubOwner), entry]));
+            const chosenKeys = new Set(chosenIds.map((id) => inventoryKey(id, hubOwner)));
+            added = chosenIds.filter((id) => !storedByKey.has(inventoryKey(id, hubOwner)));
+            removed = stored.ids.filter((id) => !chosenKeys.has(inventoryKey(id, hubOwner)));
+            // Positions, not ids: `added` indexes into the --repositories argument the caller passed; `removed` indexes into the stored inventory's own `repositories` array.
+            addedPositions = added.map((id) => chosenIds.indexOf(id));
+            removedPositions = removed.map((id) => stored.ids.indexOf(id));
+            if (stored.ids.length > 0 && added.length === 0 && removed.length === 0) {
+                return { kind: "resolved", chosen: { kind: "unchanged", count: stored.ids.length } };
+            }
+            if (stored.ids.length > 0) {
+                if (!replace) {
+                    return {
+                        kind: "refuse",
+                        message: `the hub inventory already lists ${repositories(stored.ids.length)} and the choice has ${chosenIds.length}: ` +
+                            `${added.length} to add${listAddedPositions(addedPositions)}, ${removed.length} to remove${listRemovedPositions(removedPositions, "stored inventory")}. ` +
+                            `Launcher never merges or overwrites an inventory silently; to replace it with the choice, run again with ${REPLACE_INVENTORY_FLAG}`,
+                    };
+                }
+                replaced = "differing";
+            }
+            entries = chosenIds.map((id) => storedByKey.get(inventoryKey(id, hubOwner)) ?? { id });
+        }
+    }
+    const document = renderInventoryDocument(entries);
+    const written = validateInventoryDocument(document, { hubOwner });
+    if (!written.valid)
+        return { kind: "refuse", message: `the inventory to write ${written.reason}` };
+    return {
+        kind: "resolved",
+        chosen: { kind: "write", document, count: written.ids.length, previousCount, added, removed, addedPositions, removedPositions, replaced },
+    };
+}
+/** One line for the apply message saying what happened to the inventory. */
+export function describeChosenInventory(chosen) {
+    if (chosen.kind === "unchanged") {
+        return `inventory: unchanged -- it already lists the ${repositories(chosen.count)} you chose`;
+    }
+    const count = repositories(chosen.count);
+    if (chosen.replaced === "invalid")
+        return `inventory: replaced one that failed its contract with the ${count} you chose`;
+    if (chosen.replaced === "differing") {
+        return (`inventory: replaced ${chosen.previousCount} with the ${count} you chose -- ` +
+            `${chosen.added.length} added${listAddedPositions(chosen.addedPositions)}, ${chosen.removed.length} removed${listRemovedPositions(chosen.removedPositions, "replaced inventory")}`);
+    }
+    return `inventory: wrote the ${count} you chose`;
+}
+//# sourceMappingURL=inventory-choice.js.map

package/dist/inventory-choice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inventory-choice.js","sourceRoot":"","sources":["../src/inventory-choice.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,qEAAqE;AACrE,0EAA0E;AAC1E,yEAAyE;AACzE,EAAE;AACF,wEAAwE;AACxE,sEAAsE;AACtE,oEAAoE;AACpE,yEAAyE;AACzE,mFAAmF;AACnF,0EAA0E;AAC1E,EAAE;AACF,0EAA0E;AAC1E,4EAA4E;AAC5E,sEAAsE;AACtE,qDAAqD;AACrD,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AACvE,qEAAqE;AACrE,4EAA4E;AAC5E,kEAAkE;AAClE,wEAAwE;AACxE,yEAAyE;AACzE,yEAAyE;AACzE,SAAS;AAET,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,sBAAsB,EAAuB,MAAM,yBAAyB,CAAC;AAOjK,oEAAoE;AACpE,MAAM,CAAC,MAAM,sBAAsB,GAAG,qBAAqB,CAAC;AAE5D,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,GAAG,KAAK,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC;AACnE,CAAC;AAED,sGAAsG;AACtG,SAAS,kBAAkB,CAAC,SAA4B;IACtD,OAAO,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,kBAAkB,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;AAC/G,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,oBAAoB,CAAC,SAA4B,EAAE,KAAgD;IAC1G,OAAO,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,gBAAgB,KAAK,YAAY,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;AAC7H,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAkC,EAClC,SAA4B,EAC5B,QAAgB,EAChB,OAAgB;IAEhB,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,kDAAkD,EAAE,CAAC;IACzF,CAAC;IACD,MAAM,WAAW,GAAG,sBAAsB,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,YAAY,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC9H,IAAI,CAAC,WAAW,CAAC,KAAK;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,4CAA4C,WAAW,CAAC,MAAM,EAAE,EAAE,CAAC;IAE7H,IAAI,OAAyB,CAAC;IAC9B,IAAI,KAAK,GAAsB,SAAS,CAAC;IACzC,IAAI,OAAO,GAAsB,EAAE,CAAC;IACpC,IAAI,cAAc,GAAsB,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;IAC3E,IAAI,gBAAgB,GAAsB,EAAE,CAAC;IAC7C,IAAI,QAAQ,GAA4D,SAAS,CAAC;IAClF,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAC5C,CAAC;SAAM,CAAC;QACN,MAAM,MAAM,GAAG,qBAAqB,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC3D,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAClB,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO;oBACL,IAAI,EAAE,QAAQ;oBACd,OAAO,EAAE,qBAAqB,MAAM,CAAC,MAAM,4BAA4B,YAAY,CAAC,SAAS,CAAC,MAAM,CAAC,2BAA2B,sBAAsB,EAAE;iBACzJ,CAAC;YACJ,CAAC;YACD,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;YAC1C,QAAQ,GAAG,SAAS,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,aAAa,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;YAClC,4GAA4G;YAC5G,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,EAAE,QAAQ,CAAC,EAAE,KAAK,CAAU,CAAC,CAAC,CAAC;YAC/G,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC9E,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC/E,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;YACjF,kKAAkK;YAClK,cAAc,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;YAC1D,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;YAC/D,IAAI,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACxE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC;YACvF,CAAC;YACD,IAAI,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC1B,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,OAAO;wBACL,IAAI,EAAE,QAAQ;wBACd,OAAO,EACL,mCAAmC,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,uBAAuB,SAAS,CAAC,MAAM,IAAI;4BAC7G,GAAG,KAAK,CAAC,MAAM,UAAU,kBAAkB,CAAC,cAAc,CAAC,KAAK,OAAO,CAAC,MAAM,aAAa,oBAAoB,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,IAAI;4BACzJ,4GAA4G,sBAAsB,EAAE;qBACvI,CAAC;gBACJ,CAAC;gBACD,QAAQ,GAAG,WAAW,CAAC;YACzB,CAAC;YACD,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QACzF,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,uBAAuB,CAAC,OAAO,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,yBAAyB,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;IAClE,IAAI,CAAC,OAAO,CAAC,KAAK;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,0BAA0B,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IACnG,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,QAAQ,EAAE;KAC1I,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,uBAAuB,CAAC,MAAuB;IAC7D,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAChC,OAAO,gDAAgD,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC;IAChG,CAAC;IACD,MAAM,KAAK,GAAG,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACzC,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO,6DAA6D,KAAK,YAAY,CAAC;IACzH,IAAI,MAAM,CAAC,QAAQ,KAAK,WAAW,EAAE,CAAC;QACpC,OAAO,CACL,uBAAuB,MAAM,CAAC,aAAa,aAAa,KAAK,gBAAgB;YAC7E,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,SAAS,kBAAkB,CAAC,MAAM,CAAC,cAAc,CAAC,KAAK,MAAM,CAAC,OAAO,CAAC,MAAM,WAAW,oBAAoB,CAAC,MAAM,CAAC,gBAAgB,EAAE,oBAAoB,CAAC,EAAE,CACnL,CAAC;IACJ,CAAC;IACD,OAAO,wBAAwB,KAAK,YAAY,CAAC;AACnD,CAAC"}

package/dist/inventory-contract.d.ts

@@ -0,0 +1,89 @@
+/** The contract's file name, as packed. */
+export declare const INVENTORY_CONTRACT = "repository-inventory.json";
+/** Points a refusal at the one place the shape is written down. */
+export declare const INVENTORY_CONTRACT_POINTER = "see docs/contracts/repository-inventory.json";
+/**
+ * The result of checking one inventory document: its repository ids, in
+ * document order, or the reason it is refused. `reason` names every field
+ * at fault, separated by `; `, and ends with a pointer to the contract.
+ */
+export type InventoryValidation = {
+    readonly valid: true;
+    readonly ids: readonly string[];
+} | {
+    readonly valid: false;
+    readonly reason: string;
+};
+/** One inventory entry, exactly as the contract allows it. */
+export interface InventoryEntry {
+    readonly id: string;
+    readonly packages?: readonly {
+        readonly name: string;
+        readonly version?: string;
+        readonly wiring?: string;
+    }[];
+}
+/**
+ * The first id, if any, that names the same repository as an earlier one
+ * under `inventoryKey()`: its position and the earlier position.
+ */
+export declare function firstRepeatedRepository(ids: readonly string[], hubOwner?: string): {
+    readonly index: number;
+    readonly earlier: number;
+} | undefined;
+/** Options for reading an inventory document. */
+export interface InventoryReadOptions {
+    /**
+     * The hub's owner, whenever the caller knows it. A bare id and
+     * `<hubOwner>/<id>` then name the same repository, so a document listing
+     * both is refused instead of carrying two entries for one repository.
+     */
+    readonly hubOwner?: string;
+}
+/** A valid document's entries, as internal readers need them; `InventoryValidation` exposes only the ids. */
+export type InventoryRead = {
+    readonly valid: true;
+    readonly ids: readonly string[];
+    readonly entries: readonly InventoryEntry[];
+} | {
+    readonly valid: false;
+    readonly reason: string;
+};
+/**
+ * Validates an already-parsed value against the inventory contract through
+ * the shared checker, then applies the duplicate rule. Never throws for a
+ * bad value.
+ */
+export declare function validateInventoryValue(value: unknown, options?: InventoryReadOptions): InventoryValidation;
+/**
+ * Reads and checks one inventory document. Bytes -- as every file read
+ * passes them, from `WorkspaceHost.readBytes()` -- go straight to the
+ * shared strict reader, so bytes that are not valid UTF-8 are refused
+ * rather than silently replaced. Text is accepted for a document built in
+ * memory, and one holding a lone surrogate is refused before encoding.
+ */
+export declare function readInventoryDocument(raw: string | Uint8Array, options?: InventoryReadOptions): InventoryRead;
+/**
+ * Strictly validates an inventory document against
+ * docs/contracts/repository-inventory.json. It is read as strict JSON by the
+ * shared reader -- bytes that are not valid UTF-8, a syntax error (reported
+ * by position only), a key repeated in any object, or a leading byte order
+ * mark is refused -- and the value is then checked by the shared contract
+ * checker and the duplicate rule. Every read of an inventory file passes
+ * its exact bytes: `--inventory`, the stored `clossys/.state/inventory.json`
+ * on every run, `readInventoryRepositories()`, and the document
+ * `launcher --repositories` writes, before it writes it. The contract's
+ * source path does not ship in this package -- this package's build packs
+ * and ships its own copy of it -- and the stored inventory path is
+ * generated on the hub at runtime and is not part of this package at all.
+ */
+export declare function validateInventoryDocument(raw: string | Uint8Array, options?: InventoryReadOptions): InventoryValidation;
+/**
+ * Whether one id satisfies the contract's `definitions/repositoryId` -- a
+ * bare repository name or `owner/name`, by the same GitHub owner and
+ * repository rules Launcher applies when it resolves a sibling clone.
+ */
+export declare function isValidInventoryId(id: string): boolean;
+/** The inventory document text Launcher writes for these entries: two-space JSON and a final newline. */
+export declare function renderInventoryDocument(entries: readonly InventoryEntry[]): string;
+//# sourceMappingURL=inventory-contract.d.ts.map

package/dist/inventory-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inventory-contract.d.ts","sourceRoot":"","sources":["../src/inventory-contract.ts"],"names":[],"mappings":"AAoBA,2CAA2C;AAC3C,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAE9D,mEAAmE;AACnE,eAAO,MAAM,0BAA0B,iDAAiD,CAAC;AAEzF;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/G;AAMD;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,SAAS,MAAM,EAAE,EACtB,QAAQ,CAAC,EAAE,MAAM,GAChB;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CASlE;AAED,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,6GAA6G;AAC7G,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAA;CAAE,GACtG;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AA2BvD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,oBAAyB,GAAG,mBAAmB,CAE9G;AAKD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,OAAO,GAAE,oBAAyB,GAAG,aAAa,CAWjH;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,OAAO,GAAE,oBAAyB,GAAG,mBAAmB,CAE3H;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,yGAAyG;AACzG,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,CAElF"}

package/dist/inventory-contract.js

@@ -0,0 +1,121 @@
+// The hub repository inventory (issues #996, #1334 and #1179), validated
+// against the shared contract docs/contracts/repository-inventory.json (in
+// the public repository; that exact path does not ship in this package,
+// but this package's build packs and ships its own copy of the contract).
+// This package's build packs that file into src/generated/ beside the plan
+// and brief contracts, and checks it with the generated copy of the one
+// contract checker @clossys/advisor also uses -- so an inventory Launcher
+// writes, an inventory Launcher reads back, and a repository id Advisor
+// offers on its repository-choice card are all judged by one definition.
+//
+// Refusals follow the checker's conventions: they name a field by its
+// position (for example `repositories[2].id`), never quote a repository id
+// or any other value from the document, and report a JSON syntax error by
+// position only.
+import { readContractDocument, validateAgainstContract } from "./generated/contract-schema.generated.js";
+import { inventoryKey } from "./identity.js";
+import { loadContract } from "./plan-contract.js";
+/** The contract's file name, as packed. */
+export const INVENTORY_CONTRACT = "repository-inventory.json";
+/** Points a refusal at the one place the shape is written down. */
+export const INVENTORY_CONTRACT_POINTER = "see docs/contracts/repository-inventory.json";
+function describeViolation(violation) {
+    return violation.path === "" ? violation.message : `${violation.path} ${violation.message}`;
+}
+/**
+ * The first id, if any, that names the same repository as an earlier one
+ * under `inventoryKey()`: its position and the earlier position.
+ */
+export function firstRepeatedRepository(ids, hubOwner) {
+    const seen = new Map();
+    for (const [index, id] of ids.entries()) {
+        const key = inventoryKey(id, hubOwner);
+        const earlier = seen.get(key);
+        if (earlier !== undefined)
+            return { index, earlier };
+        seen.set(key, index);
+    }
+    return undefined;
+}
+function checkInventoryValue(value, options) {
+    const violations = validateAgainstContract(loadContract(INVENTORY_CONTRACT), value, loadContract);
+    if (violations.length > 0) {
+        return { valid: false, reason: `${violations.map(describeViolation).join("; ")} (${INVENTORY_CONTRACT_POINTER})` };
+    }
+    const entries = value.repositories;
+    const ids = entries.map((entry) => entry.id);
+    const repeated = firstRepeatedRepository(ids, options.hubOwner);
+    if (repeated !== undefined) {
+        const rule = options.hubOwner === undefined
+            ? "repository ids are compared case-insensitively"
+            : "repository ids are compared case-insensitively, and a bare id names a repository of the hub's own owner";
+        return {
+            valid: false,
+            reason: `repositories[${repeated.index}].id names the same repository as repositories[${repeated.earlier}].id (${rule}; ${INVENTORY_CONTRACT_POINTER})`,
+        };
+    }
+    return { valid: true, ids, entries };
+}
+function withoutEntries(read) {
+    return read.valid ? { valid: true, ids: read.ids } : read;
+}
+/**
+ * Validates an already-parsed value against the inventory contract through
+ * the shared checker, then applies the duplicate rule. Never throws for a
+ * bad value.
+ */
+export function validateInventoryValue(value, options = {}) {
+    return withoutEntries(checkInventoryValue(value, options));
+}
+/** A lone surrogate in a JS string, which has no UTF-8 encoding; TextEncoder would silently replace it. */
+const LONE_SURROGATE = /[\uD800-\uDFFF]/u;
+/**
+ * Reads and checks one inventory document. Bytes -- as every file read
+ * passes them, from `WorkspaceHost.readBytes()` -- go straight to the
+ * shared strict reader, so bytes that are not valid UTF-8 are refused
+ * rather than silently replaced. Text is accepted for a document built in
+ * memory, and one holding a lone surrogate is refused before encoding.
+ */
+export function readInventoryDocument(raw, options = {}) {
+    if (typeof raw === "string" && LONE_SURROGATE.test(raw)) {
+        return { valid: false, reason: `is not well-formed Unicode: it contains a lone surrogate, which has no UTF-8 encoding (${INVENTORY_CONTRACT_POINTER})` };
+    }
+    let value;
+    try {
+        value = readContractDocument(typeof raw === "string" ? new TextEncoder().encode(raw) : raw);
+    }
+    catch (cause) {
+        return { valid: false, reason: `${cause instanceof Error ? cause.message : String(cause)} (${INVENTORY_CONTRACT_POINTER})` };
+    }
+    return checkInventoryValue(value, options);
+}
+/**
+ * Strictly validates an inventory document against
+ * docs/contracts/repository-inventory.json. It is read as strict JSON by the
+ * shared reader -- bytes that are not valid UTF-8, a syntax error (reported
+ * by position only), a key repeated in any object, or a leading byte order
+ * mark is refused -- and the value is then checked by the shared contract
+ * checker and the duplicate rule. Every read of an inventory file passes
+ * its exact bytes: `--inventory`, the stored `clossys/.state/inventory.json`
+ * on every run, `readInventoryRepositories()`, and the document
+ * `launcher --repositories` writes, before it writes it. The contract's
+ * source path does not ship in this package -- this package's build packs
+ * and ships its own copy of it -- and the stored inventory path is
+ * generated on the hub at runtime and is not part of this package at all.
+ */
+export function validateInventoryDocument(raw, options = {}) {
+    return withoutEntries(readInventoryDocument(raw, options));
+}
+/**
+ * Whether one id satisfies the contract's `definitions/repositoryId` -- a
+ * bare repository name or `owner/name`, by the same GitHub owner and
+ * repository rules Launcher applies when it resolves a sibling clone.
+ */
+export function isValidInventoryId(id) {
+    return validateAgainstContract({ $ref: `${INVENTORY_CONTRACT}#/definitions/repositoryId` }, id, loadContract).length === 0;
+}
+/** The inventory document text Launcher writes for these entries: two-space JSON and a final newline. */
+export function renderInventoryDocument(entries) {
+    return `${JSON.stringify({ schemaVersion: 1, repositories: entries }, null, 2)}\n`;
+}
+//# sourceMappingURL=inventory-contract.js.map

package/dist/inventory-contract.js.map

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

package/dist/key-editor.d.ts

@@ -0,0 +1,30 @@
+/** One JSON-pointer edit. `remove` deletes the value the pointer addresses; otherwise `value` is written there. */
+export interface JsonPointerEdit {
+    readonly pointer: string;
+    readonly value?: unknown;
+    readonly remove?: boolean;
+}
+/** What `valueAtJsonPointer` found. `found` is false when any token along the pointer is absent. */
+export interface JsonPointerValue {
+    readonly found: boolean;
+    readonly value: unknown;
+}
+/** Thrown when an edit would rewrite bytes outside the edited tokens. */
+export declare class JsonEditUnstableError extends TypeError {
+    constructor();
+}
+/**
+ * The value a JSON pointer addresses in `text`, or `{ found: false }` when
+ * a token along the pointer is absent. The text must be JSON; a parse
+ * failure throws a TypeError that does not quote the text.
+ */
+export declare function valueAtJsonPointer(text: string, pointer: string): JsonPointerValue;
+/**
+ * Applies `edits` to `text` and returns the edited document. An empty edit
+ * list returns `text` unchanged. Indent, the order of existing keys, and
+ * whether the text ended in a newline are taken from `text` and used for
+ * the render. The render is parsed and rendered a second time, and the two
+ * results must be the same bytes.
+ */
+export declare function editJsonPointer(text: string, edits: readonly JsonPointerEdit[]): string;
+//# sourceMappingURL=key-editor.d.ts.map

package/dist/key-editor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-editor.d.ts","sourceRoot":"","sources":["../src/key-editor.ts"],"names":[],"mappings":"AASA,mHAAmH;AACnH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAUD,oGAAoG;AACpG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,yEAAyE;AACzE,qBAAa,qBAAsB,SAAQ,SAAS;;CAInD;AAgWD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAmBlF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,CAyBvF"}