@cairn-tool/cairn 2.1.0 → 3.0.0

package/dist/agent/install/index.d.ts

@@ -52,11 +52,14 @@ export interface InstallRegistration {
  * A manifest written before collections carries only `pluginKey`.
  */
 export declare function registeredPluginKeys(registration: InstallRegistration): string[];
-export interface InstallManifest {
-    generator: {
-        name: string;
-        version: string;
-    };
+/**
+ * One install recorded in a destination's manifest.
+ *
+ * A destination may hold several: every target declares the same project-scope
+ * merge root, so a repository installing for two hosts, or two bundles, records
+ * them side by side. {@link installKey} is what tells them apart.
+ */
+export interface InstallRecord {
     /**
      * What was installed here: a single bundle, or a collection of them. Absent
      * means `"bundle"`, so every manifest written before collections still parses.
@@ -89,6 +92,45 @@ export interface InstallManifest {
     materialized?: string;
     registration?: InstallRegistration;
 }
+/**
+ * The `.cairn-install.json` document: which build wrote it, and every install
+ * it accounts for.
+ *
+ * Serialized in one of two shapes — see {@link serializeDocument}. Both parse,
+ * and a document that fails to parse in full is `malformed` rather than
+ * partially trusted: its job is to be an *exhaustive* statement of what cairn
+ * owns here, and a dropped entry would make that entry's files look unowned to
+ * the occupancy check and to `retirePrior`, which is the destruction this shape
+ * exists to prevent.
+ */
+export interface InstallDocument {
+    generator: {
+        name: string;
+        version: string;
+    };
+    installs: InstallRecord[];
+}
+/**
+ * An install's identity within one destination.
+ *
+ * Keyed on the bundle **and** the target, which is the whole fix: keyed on the
+ * bundle name alone, a second target's install read the first's inventory as
+ * its own stale files and deleted them.
+ *
+ * NUL-separated for the reason `artifactKey` and `sessionKey` are — no half can
+ * contain one. `profile` is redundant while `locationFor(target, scope)` fixes
+ * it, and is included so a future target declaring two locations for one scope
+ * does not silently collide. `destination` is deliberately absent: the key is
+ * only ever compared within one manifest file.
+ */
+export declare function installKey(record: {
+    bundle: {
+        name: string;
+    };
+    target: AgentTarget;
+    profile: AgentProfile;
+    scope: InstallScope;
+}): string;
 export interface InstallContext {
     home?: string;
     cwd?: string;
@@ -111,7 +153,24 @@ export interface InstallPlan {
     mode: InstallMode;
     destination: string;
     artifacts: Artifact[];
-    manifest: InstallManifest;
+    /** This install's own record. */
+    record: InstallRecord;
+    /**
+     * The whole document this plan writes, siblings included. Byte-identical for
+     * every plan sharing a destination in one batch.
+     */
+    document: InstallDocument;
+    /**
+     * The document as it stood when the plan was made.
+     *
+     * `retirePrior` prunes against this snapshot and never against a re-read at
+     * commit time: every plan in a destination group writes the same merged
+     * document, so once the first has committed, the file already lists the
+     * second's record — a re-read would make the second find itself, compute an
+     * empty stale set, and silently never prune. It also closes the window
+     * between planning and committing.
+     */
+    prior: InstallDocument | "missing" | "malformed";
     diagnostics: AgentDiagnostic[];
     register: boolean;
     settings?: InstallRegistration;
@@ -128,23 +187,45 @@ export declare function locationFor(target: AgentTarget, scope: InstallScope): I
  * absolute path is enough, matching the overlay boundary.
  */
 export declare function pathEscapesRoot(root: string, relative: string): boolean;
-export declare function readInstallManifest(destination: string): InstallManifest | "missing" | "malformed";
+export declare function readInstallDocument(destination: string): InstallDocument | "missing" | "malformed";
+/** The record matching `key` at `destination`, if the document records one. */
+export declare function readInstallRecord(destination: string, key: string): InstallRecord | "missing" | "malformed";
 export declare function resolveInstallDestination(target: AgentTarget, scope: InstallScope, name: string, options?: {
     into?: string;
 } & InstallContext): ResolvedInstall | AgentDiagnostic;
 export declare function installIsCurrent(plan: InstallPlan): boolean;
-/**
- * Plans an install: renders and packages in memory, resolves the destination
- * from profile data, and records AB8xx findings. Nothing is written.
- */
-export declare function planInstall(bundle: AgentBundle, target: AgentTarget, options: {
+/** Options shared by every install plan in one run. */
+export interface PlanInstallOptions extends InstallContext {
     scope?: string;
     into?: string;
     profile?: string;
     link?: boolean;
     register?: boolean;
     force?: boolean;
-} & InstallContext): InstallPlan;
+}
+/** One bundle to install for one target. */
+export interface InstallRequest {
+    bundle: AgentBundle;
+    target: AgentTarget;
+}
+export interface InstallBatch {
+    plans: InstallPlan[];
+    /** Batch-level findings — the in-run AB808. Per-plan findings stay on the plan. */
+    diagnostics: AgentDiagnostic[];
+}
+/**
+ * Plans every requested install, grouped by destination.
+ *
+ * Nothing is written here, and the caller must treat the batch as all-or-nothing:
+ * committing a subset of a run whose remainder is blocked is how a destination
+ * ends up half-populated with no record of it.
+ */
+export declare function planInstalls(requests: InstallRequest[], options: PlanInstallOptions): InstallBatch;
+/**
+ * Plans a single install: renders and packages in memory, resolves the
+ * destination from profile data, and records AB8xx findings. Nothing is written.
+ */
+export declare function planInstall(bundle: AgentBundle, target: AgentTarget, options: PlanInstallOptions): InstallPlan;
 /** What a collection places at one destination. */
 export interface CollectionInstall {
     /** The collection's name; also the marketplace key hosts index by. */
@@ -190,7 +271,7 @@ export interface UninstallPlan {
     name: string;
     target: AgentTarget;
     destination: string;
-    manifest: InstallManifest | null;
+    manifest: InstallRecord | null;
     diagnostics: AgentDiagnostic[];
     missing: boolean;
 }