@clossys/launcher 0.3.1 → 0.5.0

package/src/change-set-digest.ts

@@ -0,0 +1,70 @@
+// The change-set and bundle digests (issue #1178), implemented from their
+// one definition, docs/contracts/apply-change-set-digest.md, and tested
+// against its corpus, apply-change-set-digest.fixture.json beside it. Both
+// files are in the public repository, not shipped in this package. Both
+// digests reuse the plan digest's canonical step, canonicalDigest(); nothing
+// here serializes JSON a second way.
+
+import { canonicalDigest } from "./plan-digest.js";
+
+/** The top-level change-set members the digest leaves out: each is computed from the digest or from what it covers, or (tooling) records the machine rather than the change. */
+export const CHANGE_SET_DIGEST_EXCLUDED_FIELDS: readonly string[] = ["changeSetDigest", "branch", "bundle", "pullRequest", "inverse", "tooling", "texts"];
+
+/** The members a derived file keeps in the digest's subject; its `before` and `after` are left out. */
+export const DERIVED_FILE_DIGEST_FIELDS: readonly string[] = ["path", "mode", "derived", "item", "invariants"];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * The value the change-set digest is computed over: the set without its
+ * excluded members, with every file whose `derived` is `true` reduced to
+ * DERIVED_FILE_DIGEST_FIELDS. Everything else is kept as it is, arrays in
+ * order. Throws when `changeSet` is not an object or its `files` is not an
+ * array of objects, because then there is nothing well defined to digest.
+ */
+export function changeSetDigestSubject(changeSet: unknown): Record<string, unknown> {
+  if (!isRecord(changeSet)) throw new TypeError("a change set must be an object to have a digest");
+  const files = changeSet.files;
+  if (!Array.isArray(files) || !files.every(isRecord)) throw new TypeError("a change set's files must be an array of objects to have a digest");
+  const subject: Record<string, unknown> = {};
+  for (const [key, member] of Object.entries(changeSet)) if (!CHANGE_SET_DIGEST_EXCLUDED_FIELDS.includes(key)) subject[key] = member;
+  subject.files = files.map((file) => {
+    if (file.derived !== true) return file;
+    const reduced: Record<string, unknown> = {};
+    for (const key of DERIVED_FILE_DIGEST_FIELDS) if (Object.hasOwn(file, key)) reduced[key] = file[key];
+    return reduced;
+  });
+  return subject;
+}
+
+/** `canonicalDigest(changeSetDigestSubject(changeSet))`: the same digest for the same change, whatever the excluded members hold. */
+export function changeSetDigest(changeSet: unknown): string {
+  return canonicalDigest(changeSetDigestSubject(changeSet));
+}
+
+/** One repository's part in the bundle digest. */
+export interface BundleDigestEntry {
+  readonly id: string;
+  readonly changeSetDigest: string;
+}
+
+/** Orders two strings by their UTF-16 code units, as the digest page requires for repository ids. */
+function compareCodeUnits(left: string, right: string): number {
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}
+
+/**
+ * The bundle digest an approval binds: `canonicalDigest({ planDigest,
+ * repositories })`, with `repositories` holding the id and change-set digest
+ * of every repository that has a change set, sorted by id. Nothing else is
+ * covered -- no authorization, time, check or verdict -- so it can be
+ * recomputed from digests alone.
+ */
+export function bundleDigest(planDigest: string, repositories: readonly BundleDigestEntry[]): string {
+  const entries = repositories.map(({ id, changeSetDigest: digest }) => ({ id, changeSetDigest: digest }));
+  entries.sort((left, right) => compareCodeUnits(left.id, right.id));
+  return canonicalDigest({ planDigest, repositories: entries });
+}

package/src/check-cli.ts

@@ -34,13 +34,16 @@ function parseInventoryObservation(value: unknown): InventoryObservation | undef
   if (!isRecord(value)) {
     throw new LauncherCheckInputError("observation.cwd.inventory must be an object");
   }
-  if (value.status !== "missing" && value.status !== "empty" && value.status !== "populated") {
-    throw new LauncherCheckInputError("observation.cwd.inventory.status must be missing, empty, or populated");
+  if (value.status !== "missing" && value.status !== "empty" && value.status !== "populated" && value.status !== "invalid") {
+    throw new LauncherCheckInputError("observation.cwd.inventory.status must be missing, empty, populated, or invalid");
   }
   if (typeof value.count !== "number" || !Number.isInteger(value.count) || value.count < 0) {
     throw new LauncherCheckInputError("observation.cwd.inventory.count must be a nonnegative integer");
   }
-  return { status: value.status, count: value.count };
+  if (value.reason !== undefined && !isText(value.reason)) {
+    throw new LauncherCheckInputError("observation.cwd.inventory.reason must be a nonempty string when present");
+  }
+  return { status: value.status, count: value.count, ...(isText(value.reason) ? { reason: value.reason } : {}) };
 }
 
 function parseCwd(value: unknown): CwdObservation {
@@ -86,6 +89,9 @@ export function parseObservation(value: unknown): WorkspaceObservation {
   if (value.advisorVersion !== undefined && !isText(value.advisorVersion)) {
     throw new LauncherCheckInputError("observation.advisorVersion must be a string");
   }
+  if (value.integratorVersion !== undefined && !isText(value.integratorVersion)) {
+    throw new LauncherCheckInputError("observation.integratorVersion must be a string");
+  }
   return {
     cwd: parseCwd(value.cwd),
     ownerCandidates: value.ownerCandidates,
@@ -93,6 +99,7 @@ export function parseObservation(value: unknown): WorkspaceObservation {
     gitAvailable: value.gitAvailable,
     ...(isText(value.envOwner) ? { envOwner: value.envOwner } : {}),
     ...(isText(value.advisorVersion) ? { advisorVersion: value.advisorVersion } : {}),
+    ...(isText(value.integratorVersion) ? { integratorVersion: value.integratorVersion } : {}),
   };
 }
 
@@ -111,9 +118,13 @@ export function planningHost(): WorkspaceHost {
     isDirectory: () => false,
     isSymlink: () => false,
     readText: () => null,
+    readBytes: () => null,
     writeText: () => {
       throw new Error("launcher-check does not write");
     },
+    writeBytes: () => {
+      throw new Error("launcher-check does not write");
+    },
     mkdirp: () => {
       throw new Error("launcher-check does not write");
     },

package/src/cli.ts

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import {
   applyWorkspacePlan,
   cloneMissingInventoryRepositories,
+  inventoryPositionLabel,
   observeWorkspace,
   planWorkspace,
   launcherPackageRootFromModule,
@@ -14,7 +15,7 @@ import {
 import { createNodeHost } from "./host.js";
 import type { WorkspaceHost } from "./types.js";
 
-export const USAGE = `Usage: launcher [--inventory <path>] [--clone-missing]
+export const USAGE = `Usage: launcher [--repositories <owner/name>[,<owner/name>...] [--replace-inventory]] [--inventory <path>] [--clone-missing]
 
 Create, resume, or appoint a GitHub repository as the account workspace hub.
 
@@ -23,16 +24,30 @@ hub to resume. Run from any GitHub repository you want to own the account-level
 hub to appoint it — it does not have to be a new exclusive repo, and it keeps
 its current name and files.
 
-Appointing requires a populated generated hub inventory (packed template
-skeleton/clossys/.state/inventory.json; the generated path does not ship), or
---inventory <path> pointing at one. Resume refreshes composed skills and
-stale hub guidance, and migrates a legacy .clossys/ hub state to
-clossys/.state/ automatically. Create may write an empty inventory.
+Appointing needs the repositories the hub covers. Choose them on Advisor's
+repository card (npx -p @clossys/advisor advisor-repository-card), built
+from the repositories GitHub lists for your sign-in, then pass the chosen ids
+to --repositories: Launcher writes clossys/.state/inventory.json for you,
+when appointing or on an existing hub. It never merges into or overwrites an
+inventory that lists a different set of repositories; it reports the
+difference, and --replace-inventory is the explicit approval to replace it.
+--inventory <path> still accepts a prepared inventory document when
+appointing. Resume refreshes composed skills and stale hub guidance, pins
+the hub's @clossys/advisor and @clossys/integrator at their live versions,
+and migrates a legacy .clossys/ hub state to clossys/.state/ automatically.
+Create may write an empty inventory. A run composes skills into the hub only
+and changes nothing in an inventoried repository's checkout beside it: once
+a product repository is staffed in an approved plan, its team arrives with
+that plan's setup pull request. When a run changes an engine pin, it says
+what changed: run the hub's package manager install, then commit
+package.json together with its lockfile.
 
 By default launcher never \`gh repo clone\`s a missing inventory entry --
 that is not how you talk to the team. --clone-missing is the one explicit,
 approved exception (#1179): on resume only, it clones every inventoried
-repository not yet sitting beside the hub, and only those.
+repository not yet sitting beside the hub, and only those. Cloning is not
+composing: a cloned repository receives its team only once it is staffed in
+an approved plan, with that plan's setup pull request.
 
 GitHub-only. Owner is inferred from \`gh\` and git remotes. Public npm reads
 need no token.
@@ -45,20 +60,57 @@ function exitCodeFor(state: "satisfied" | "violated" | "indeterminate"): number
   return state === "satisfied" ? 0 : state === "violated" ? 1 : 2;
 }
 
-export function parseLauncherArgs(argv: readonly string[]): { help: boolean; inventoryPath?: string; cloneMissing: boolean } {
-  if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) return { help: true, cloneMissing: false };
-  const rest = [...argv];
+export interface LauncherArgs {
+  readonly help: boolean;
+  readonly inventoryPath?: string;
+  /** `--repositories`: the comma-separated ids, split but not yet validated (planWorkspace validates them against the inventory contract). */
+  readonly repositories?: readonly string[];
+  readonly replaceInventory: boolean;
+  readonly cloneMissing: boolean;
+}
+
+const ARGUMENT_ERROR =
+  "launcher takes no arguments except optional --inventory <path>, --repositories <owner/name>[,<owner/name>...], --replace-inventory, and --clone-missing, each at most once; run it from the directory to create or appoint";
+
+/**
+ * Parses launcher's flags. Each flag may appear once, in any order; a
+ * value flag takes the next argument. `--repositories` is one argument of
+ * comma-separated ids -- a repository id never contains a comma -- so an
+ * empty id (a doubled or trailing comma) reaches the contract check as an
+ * empty string and is refused there, by position.
+ */
+export function parseLauncherArgs(argv: readonly string[]): LauncherArgs {
+  if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) return { help: true, replaceInventory: false, cloneMissing: false };
+  const seen = new Set<string>();
+  let inventoryPath: string | undefined;
+  let repositories: readonly string[] | undefined;
+  let replaceInventory = false;
   let cloneMissing = false;
-  const cloneIndex = rest.indexOf("--clone-missing");
-  if (cloneIndex !== -1) {
-    cloneMissing = true;
-    rest.splice(cloneIndex, 1);
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    if (flag === undefined || seen.has(flag)) throw new LauncherInputError(ARGUMENT_ERROR);
+    seen.add(flag);
+    if (flag === "--clone-missing") {
+      cloneMissing = true;
+    } else if (flag === "--replace-inventory") {
+      replaceInventory = true;
+    } else if (flag === "--inventory" || flag === "--repositories") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("--")) throw new LauncherInputError(ARGUMENT_ERROR);
+      index += 1;
+      if (flag === "--inventory") inventoryPath = value;
+      else repositories = value.split(",");
+    } else {
+      throw new LauncherInputError(ARGUMENT_ERROR);
+    }
   }
-  if (rest.length === 0) return { help: false, cloneMissing };
-  if (rest.length === 2 && rest[0] === "--inventory" && rest[1]) return { help: false, inventoryPath: rest[1], cloneMissing };
-  throw new LauncherInputError(
-    "launcher takes no arguments except optional --inventory <path> and/or --clone-missing; run it from the directory to create or appoint",
-  );
+  return {
+    help: false,
+    ...(inventoryPath === undefined ? {} : { inventoryPath }),
+    ...(repositories === undefined ? {} : { repositories }),
+    replaceInventory,
+    cloneMissing,
+  };
 }
 
 /** Testable CLI dispatcher. Unknown arguments throw; the executable maps them to exit 2. */
@@ -69,7 +121,16 @@ export function main(argv: readonly string[], host: WorkspaceHost, skeletonRoot:
     return 0;
   }
   const observation = observeWorkspace(host);
+  // A bare `launcher`, with no flags at all, in a directory that is none of
+  // empty, a git repository, an existing hub, or the Foundry supplier tree
+  // itself: there is nothing to plan, so show usage and exit 0 -- that is
+  // someone finding out what this command does, not a refused request. But
+  // when a flag IS present (--inventory, --repositories, ...), the caller
+  // asked for something specific here; fall through to planWorkspace()
+  // instead, which refuses it with exit 1 and says why, the same as any
+  // other unsatisfiable request (#1179).
   if (
+    argv.length === 0 &&
     !observation.cwd.empty &&
     !observation.cwd.git &&
     observation.cwd.hub === undefined &&
@@ -78,14 +139,20 @@ export function main(argv: readonly string[], host: WorkspaceHost, skeletonRoot:
     console.log(USAGE);
     return 0;
   }
-  const decision = planWorkspace(observation, host, { inventoryPath: parsed.inventoryPath });
+  const decision = planWorkspace(observation, host, {
+    ...(parsed.inventoryPath === undefined ? {} : { inventoryPath: parsed.inventoryPath }),
+    ...(parsed.repositories === undefined ? {} : { repositories: parsed.repositories }),
+    ...(parsed.replaceInventory ? { replaceInventory: true } : {}),
+  });
   if (decision.action === "refuse") {
     console.error(`launcher: ${decision.message}`);
     return exitCodeFor(decision.state);
   }
   if (parsed.inventoryPath !== undefined && decision.action !== "adopt") {
     if (decision.action === "resume") {
-      console.error("launcher: this hub is already appointed; edit clossys/.state/inventory.json to change its inventory");
+      console.error(
+        "launcher: this hub is already appointed; to change the repositories it covers, choose them again on Advisor's repository card and run launcher --repositories <owner/name>[,<owner/name>...] -- never hand-edit clossys/.state/inventory.json",
+      );
     } else {
       console.error("launcher: --inventory is only valid when appointing a GitHub repository");
     }
@@ -104,7 +171,8 @@ export function main(argv: readonly string[], host: WorkspaceHost, skeletonRoot:
     const outcomes = cloneMissingInventoryRepositories(host, decision.directory, decision.owner);
     for (const outcome of outcomes) {
       if (outcome.result === "skipped-other-reason") continue;
-      console.log(`clone-missing (${outcome.inventoryId}): ${outcome.result} -- ${outcome.note}`);
+      // Named by position, never by outcome.inventoryId itself: that id came from the stored inventory, an agent-read document (see core.ts's classifyInventoriedSiblings).
+      console.log(`clone-missing (${inventoryPositionLabel(outcome.inventoryId, outcome.position)}): ${outcome.result} -- ${outcome.note}`);
     }
   }
   return 0;