@clossys/launcher 0.3.1 → 0.5.0

package/src/types.ts

@@ -21,8 +21,18 @@ export interface WorkspaceHost {
   isDirectory(path: string): boolean;
   /** True when path exists and is a symlink (lstat; does not follow). Missing path is false. */
   isSymlink(path: string): boolean;
+  /** Decodes a file as UTF-8 text. Missing or unreadable is null. Not for contract documents: invalid bytes are silently replaced. */
   readText(path: string): string | null;
+  /**
+   * A file's exact bytes, never decoded. Missing or unreadable is null. Every
+   * inventory document is read this way and handed to the shared strict
+   * reader, so bytes that are not valid UTF-8 are refused rather than
+   * silently replaced with U+FFFD before anything checks them (#1179).
+   */
+  readBytes(path: string): Uint8Array | null;
   writeText(path: string, contents: string): void;
+  /** Writes these exact bytes, so a copied document stays byte-identical. */
+  writeBytes(path: string, contents: Uint8Array): void;
   mkdirp(path: string): void;
   /** Creates a relative symlink at linkPath pointing at relativeTarget (directory link). */
   symlink(relativeTarget: string, linkPath: string): void;
@@ -75,18 +85,29 @@ export interface SkillsManifestSummary {
 }
 
 export interface InventoryObservation {
-  readonly status: "missing" | "empty" | "populated";
+  /**
+   * "invalid" means a document was found but does not conform to the
+   * inventory schema (bad JSON, wrong shape, an unrecognized field, or a
+   * duplicate repository id) -- distinct from "empty" (a well-formed,
+   * zero-entry document) so a malformed document is reported, never
+   * silently treated as if it were merely empty.
+   */
+  readonly status: "missing" | "empty" | "populated" | "invalid";
   readonly count: number;
+  /** Present only when status is "invalid"; names the offending field. */
+  readonly reason?: string;
 }
 
-/** A package.json dependency bucket scanned for the advisor pin. */
+/** A package.json dependency bucket scanned for the hub engine pins. */
 export type DependencyBucket = "dependencies" | "devDependencies" | "optionalDependencies" | "peerDependencies";
 
-/** Staleness verdict for one pinned advisor version against the live registry version. */
+/** Staleness verdict for one pinned engine version against the live registry version. */
 export type PinGrade = "stale" | "current" | "indeterminate";
 
-/** One graded advisor pin in one dependency bucket. */
+/** One graded hub engine pin (`@clossys/advisor` or `@clossys/integrator`) in one dependency bucket. */
 export interface PinFinding {
+  /** The engine package this finding grades. */
+  readonly package: string;
   readonly bucket: DependencyBucket;
   readonly pinned: string;
   readonly grade: PinGrade;
@@ -107,20 +128,59 @@ export interface InventoryValidationReport {
   readonly note?: string;
 }
 
+/** Where one hub engine is pinned, by dependency bucket, and its live registry version when known. */
+export interface HubEnginePin {
+  readonly dependencies?: string;
+  readonly devDependencies?: string;
+  readonly optionalDependencies?: string;
+  readonly peerDependencies?: string;
+  readonly live?: string;
+}
+
+/** One change a run made to a hub engine pin in the hub's `package.json`. */
+export interface EnginePinChange {
+  /** The engine package: `@clossys/advisor` or `@clossys/integrator`. */
+  readonly package: string;
+  /** The version pinned before the run; absent when the engine was not pinned at all. */
+  readonly from?: string;
+  /** The version pinned in `devDependencies` after the run. */
+  readonly to: string;
+  /** The dependency bucket the pin was moved out of, when it was not in `devDependencies`. */
+  readonly movedFrom?: DependencyBucket;
+}
+
+/**
+ * The hub's lockfile does not resolve its engine pins yet (`kind`
+ * `engine-pins-changed-install-needed`): the hub's package manager install
+ * has to run, and `package.json` be committed together with the lockfile,
+ * before a frozen install (`npm ci`, `pnpm install --frozen-lockfile`,
+ * `yarn install --immutable`) accepts the hub again. Marks the report degraded.
+ */
+export interface EngineInstallFinding {
+  readonly kind: "engine-pins-changed-install-needed";
+  /** The lockfile found in the hub, e.g. `package-lock.json`. */
+  readonly lockfile: string;
+  /** The install command for that lockfile's package manager, e.g. `npm install`. */
+  readonly command: string;
+  /** The engines the lockfile does not resolve at their pinned version, or, for a lockfile Launcher does not read, the engines this run changed. */
+  readonly packages: readonly string[];
+  readonly note: string;
+}
+
 /** Read-only pin and inventory report after adopt or resume. Never uninstalls. */
 export interface HubHealthReport {
   readonly marker: "present" | "missing";
   readonly inventory: InventoryObservation;
-  readonly advisorPin: {
-    readonly dependencies?: string;
-    readonly devDependencies?: string;
-    readonly optionalDependencies?: string;
-    readonly peerDependencies?: string;
-    readonly live?: string;
-  };
+  readonly advisorPin: HubEnginePin;
+  readonly integratorPin: HubEnginePin;
+  /** True when either engine is pinned in more than one dependency bucket. */
   readonly dualPin: boolean;
   readonly extraClossys: readonly string[];
   readonly pinFindings: readonly PinFinding[];
+  /** Present when this run changed a hub engine pin in `package.json`: what changed, and the one next step (install, then commit `package.json` with its lockfile). */
+  readonly enginePins?: { readonly changed: readonly EnginePinChange[]; readonly nextStep: string };
+  /** Present when a lockfile in the hub does not resolve the engine pins yet; marks the report degraded. */
+  readonly installNeeded?: EngineInstallFinding;
   readonly degraded: boolean;
   /** Coding-agent hosts this apply found already linked for skill discovery here, recorded before compose ran (#1180). Always present after apply. */
   readonly linkedHosts?: readonly DiscoveredHost[];
@@ -129,9 +189,33 @@ export interface HubHealthReport {
   readonly skillComposition?: {
     readonly composed: readonly string[];
     readonly skipped: readonly { readonly packageDir: string; readonly note: string }[];
+    /** The checkouts this run composed skills into: the hub. */
     readonly rosterTargets?: readonly string[];
-    readonly rosterSkipped?: readonly { readonly inventoryId: string; readonly note: string }[];
+    /**
+     * Each inventoried repository other than the hub, with what this run found
+     * for it (for example, a checkout beside the hub whose team arrives only
+     * once it is staffed in an approved plan, with that plan's setup pull
+     * request). Report-only: a hub run never writes into one, and no entry
+     * marks the report degraded. `inventoryId` is already a stored-inventory
+     * position label (e.g. `repositories[0] in the stored inventory`), never
+     * the raw id: this whole report is JSON-dumped into the apply message
+     * (see `formatHubHealth`'s `health:` line), so a raw id kept here would
+     * still reach that message even though no prose line built from it names
+     * the id either.
+     */
+    readonly siblings?: readonly { readonly inventoryId: string; readonly note: string }[];
     readonly retired?: readonly string[];
+    /**
+     * Composed skills in the hub left exactly as found because their on-disk
+     * content is not provably what Launcher last wrote (#1473). Any entry
+     * marks the report degraded.
+     */
+    readonly preserved?: readonly {
+      readonly packageDir: string;
+      readonly action: "rewrite" | "retire";
+      readonly path: string;
+      readonly note: string;
+    }[];
   };
   /** Present only on the run that performed the `.clossys/` -> `clossys/.state/` migration. */
   readonly migration?: { readonly status: "migrated"; readonly from: string; readonly to: string };
@@ -168,6 +252,8 @@ export interface WorkspaceObservation {
   readonly envOwner?: string;
   readonly remoteDefaultHub?: { readonly owner: string; readonly repository: string };
   readonly advisorVersion?: string;
+  /** The public `@clossys/integrator` registry version, read the same way as `advisorVersion`. */
+  readonly integratorVersion?: string;
   readonly ghAvailable: boolean;
   readonly gitAvailable: boolean;
 }
@@ -178,18 +264,50 @@ export interface WorkspacePlanCreate {
   readonly repository: string;
   readonly directory: string;
   readonly advisorVersion: string;
+  readonly integratorVersion: string;
 }
 
+/**
+ * What `launcher --repositories` does to the hub inventory (#1179): write
+ * the chosen repositories, or leave an inventory that already lists exactly
+ * those repositories as it is. Decided by `resolveChosenInventory()`.
+ */
+export type ChosenInventory =
+  | { readonly kind: "unchanged"; readonly count: number }
+  | {
+      readonly kind: "write";
+      /** The exact document text to write to `clossys/.state/inventory.json` (a generated hub path, not shipped in this package), already validated against the inventory contract. */
+      readonly document: string;
+      /** Repositories in the written document. */
+      readonly count: number;
+      /** Repositories the inventory listed before; 0 when there was none, it was empty, or it failed its contract. */
+      readonly previousCount: number;
+      /** Chosen ids the previous inventory did not list. Never put in a message text; see `addedPositions`. */
+      readonly added: readonly string[];
+      /** Previous ids the choice leaves out. Never put in a message text; see `removedPositions`. */
+      readonly removed: readonly string[];
+      /** Each `added` id's 0-based position in the `--repositories` argument, in the same order as `added`. What a message names instead of the id. */
+      readonly addedPositions: readonly number[];
+      /** Each `removed` id's 0-based position in the stored inventory's own `repositories` array, in the same order as `removed`. What a message names instead of the id. */
+      readonly removedPositions: readonly number[];
+      /** What the write replaces: nothing (no inventory, or an empty one), a differing valid inventory, or one that failed its contract. The last two happen only with an explicit replace approval. */
+      readonly replaced: "nothing" | "differing" | "invalid";
+    };
+
 export interface WorkspacePlanResume {
   readonly action: "resume";
   readonly owner: string;
   readonly repository: string;
   readonly directory: string;
   readonly clone: boolean;
-  /** Live registry Advisor version, when observeWorkspace could read one. Used only to grade health. */
+  /** Live registry Advisor version, when observeWorkspace could read one. Apply pins it in the hub and grades health against it. */
   readonly advisorVersion?: string;
+  /** Live registry Integrator version, when observeWorkspace could read one. Apply pins it in the hub and grades health against it. */
+  readonly integratorVersion?: string;
   /** Set when the hub marker was found only at the legacy `.clossys/` path; apply migrates it. */
   readonly migrateFrom?: "legacy";
+  /** Set by `--repositories`: the inventory apply writes before it composes skills, or confirms is unchanged. */
+  readonly chosenInventory?: ChosenInventory;
 }
 
 export interface WorkspacePlanAdopt {
@@ -198,10 +316,27 @@ export interface WorkspacePlanAdopt {
   readonly repository: string;
   readonly directory: string;
   readonly advisorVersion: string;
+  readonly integratorVersion: string;
   /** Absolute path of a populated inventory document to copy. Absent when cwd already has one. */
   readonly inventorySource?: string;
   /** Merged repository ids (on-disk first, then new ids from --inventory) written when both sources are populated. */
   readonly mergedInventoryIds?: readonly string[];
+  /**
+   * The merged entries themselves (each entry's `packages` kept), in the same order as `mergedInventoryIds` (#1334).
+   * Apply writes them when the plan carries no `mergedInventoryDocument`.
+   */
+  readonly mergedInventoryRepositories?: readonly { readonly id: string; readonly packages?: unknown }[];
+  /**
+   * The merged inventory document to write, when both sources are populated: every kept entry whole, its `packages`
+   * included, each repository once by Launcher's one identity rule (#1179) -- `mergedInventoryRepositories`, rendered.
+   * Preferred over `mergedInventoryRepositories` and `mergedInventoryIds`, which a hand-built plan may still carry
+   * without it; with ids alone, each id is written without packages.
+   */
+  readonly mergedInventoryDocument?: string;
+  /** Set when `inventorySource` is about to replace an on-disk inventory that failed schema validation, so the apply message can say it was replaced rather than merely written (#1334). */
+  readonly replacesInvalidInventory?: boolean;
+  /** Set by `--repositories`: the inventory apply writes, or confirms is unchanged (#1179). */
+  readonly chosenInventory?: ChosenInventory;
 }
 
 export type WorkspacePlan = WorkspacePlanCreate | WorkspacePlanResume | WorkspacePlanAdopt;