@detergent-software/atk 8.1.2-dev.3 → 8.1.2-dev.30

package/build/lib/errors.d.ts

@@ -45,6 +45,8 @@ export declare abstract class ApiCodeError extends GuidedError {
 export declare class SetupRequiredError extends GuidedError {
     name: string;
 }
+/** Text as a sentence: a period is added only when it doesn't already end with one. */
+export declare function asSentence(text: string): string;
 /**
  * Read `code`, `command` and `hint` off any thrown value (ApiRequestError,
  * AuthError, SetupRequiredError, ...), keeping each only when it is a string.
@@ -52,4 +54,11 @@ export declare class SetupRequiredError extends GuidedError {
  * error state and JSON payload; rewraps and failure entries carry it on.
  */
 export declare function errorGuidance(err: unknown): ErrorGuidance;
+/** The message of a thrown value: an Error's `message`, anything else as a string. */
+export declare function errorMessage(err: unknown): string;
+/**
+ * Whether a failure's API code fails every asset of a run, so bulk update and sync
+ * stop at it instead of repeating the same failure for each remaining asset.
+ */
+export declare function isRunWideFailure({ code }: ErrorGuidance): boolean;
 //# sourceMappingURL=errors.d.ts.map

package/build/lib/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,MAAM,WAAW,aAAc,SAAQ,gBAAgB;IACrD,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,gBAAgB,GAAG;IAAE,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAErE,yFAAyF;AACzF,8BAAsB,WAAY,SAAQ,KAAK;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;gBAEF,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;CAK9D;AAED;;;GAGG;AACH,8BAAsB,YAAa,SAAQ,WAAW;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;gBAEF,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB;CAIzD;AAED;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;IACxC,IAAI,SAAwB;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CAWzD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,MAAM,WAAW,aAAc,SAAQ,gBAAgB;IACrD,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,gBAAgB,GAAG;IAAE,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAErE,yFAAyF;AACzF,8BAAsB,WAAY,SAAQ,KAAK;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;gBAEF,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;CAK9D;AAED;;;GAGG;AACH,8BAAsB,YAAa,SAAQ,WAAW;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;gBAEF,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB;CAIzD;AAED;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;IACxC,IAAI,SAAwB;CACtC;AAED,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CAWzD;AAiBD,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAEjD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,IAAI,EAAE,EAAE,aAAa,GAAG,OAAO,CAEjE"}

package/build/lib/errors.js

@@ -29,6 +29,10 @@ export class ApiCodeError extends GuidedError {
 export class SetupRequiredError extends GuidedError {
     name = 'SetupRequiredError';
 }
+/** Text as a sentence: a period is added only when it doesn't already end with one. */
+export function asSentence(text) {
+    return /[.!?]$/.test(text) ? text : `${text}.`;
+}
 /**
  * Read `code`, `command` and `hint` off any thrown value (ApiRequestError,
  * AuthError, SetupRequiredError, ...), keeping each only when it is a string.
@@ -43,4 +47,29 @@ export function errorGuidance(err) {
         ...(typeof hint === 'string' ? { hint } : {}),
     };
 }
+/**
+ * API codes that fail every request of a run the same way, whatever the asset: an
+ * outdated CLI, a rejected credential, or a caller outside the org.
+ */
+const RUN_WIDE_CODES = new Set([
+    'cli_outdated',
+    'github_auth_retired',
+    'guest_not_allowed',
+    'invalid_token',
+    'not_org_member',
+    'org_membership_unverifiable',
+    'unauthenticated',
+    'unsupported_token',
+]);
+/** The message of a thrown value: an Error's `message`, anything else as a string. */
+export function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Whether a failure's API code fails every asset of a run, so bulk update and sync
+ * stop at it instead of repeating the same failure for each remaining asset.
+ */
+export function isRunWideFailure({ code }) {
+    return code !== undefined && RUN_WIDE_CODES.has(code);
+}
 //# sourceMappingURL=errors.js.map

package/build/lib/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAwBA,yFAAyF;AACzF,MAAM,OAAgB,WAAY,SAAQ,KAAK;IAC7C,OAAO,CAAU;IACjB,IAAI,CAAU;IAEd,YAAY,OAAe,EAAE,UAA8B,EAAE;QAC3D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACjC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAgB,YAAa,SAAQ,WAAW;IACpD,IAAI,CAAU;IAEd,YAAY,OAAe,EAAE,UAAyB,EAAE;QACtD,KAAK,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QACjE,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,kBAAmB,SAAQ,WAAW;IACxC,IAAI,GAAG,oBAAoB,CAAC;CACtC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,GAAY;IACxC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAIlF,CAAC;IACF,OAAO;QACL,GAAG,CAAC,GAAG,YAAY,YAAY,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,GAAG,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9C,CAAC;AACJ,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAwBA,yFAAyF;AACzF,MAAM,OAAgB,WAAY,SAAQ,KAAK;IAC7C,OAAO,CAAU;IACjB,IAAI,CAAU;IAEd,YAAY,OAAe,EAAE,UAA8B,EAAE;QAC3D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACjC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAgB,YAAa,SAAQ,WAAW;IACpD,IAAI,CAAU;IAEd,YAAY,OAAe,EAAE,UAAyB,EAAE;QACtD,KAAK,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QACjE,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,kBAAmB,SAAQ,WAAW;IACxC,IAAI,GAAG,oBAAoB,CAAC;CACtC;AAED,uFAAuF;AACvF,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,GAAY;IACxC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAIlF,CAAC;IACF,OAAO;QACL,GAAG,CAAC,GAAG,YAAY,YAAY,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,GAAG,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC;IAClD,cAAc;IACd,qBAAqB;IACrB,mBAAmB;IACnB,eAAe;IACf,gBAAgB;IAChB,6BAA6B;IAC7B,iBAAiB;IACjB,mBAAmB;CACpB,CAAC,CAAC;AAEH,sFAAsF;AACtF,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAE,IAAI,EAAiB;IACtD,OAAO,IAAI,KAAK,SAAS,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACxD,CAAC"}

package/build/lib/file-snapshot.d.ts

@@ -0,0 +1,17 @@
+/** The bytes and mode of files captured before a change, by absolute path. */
+export type FileSnapshot = ReadonlyMap<string, {
+    content: Buffer;
+    mode: number;
+}>;
+/**
+ * Write every file of a snapshot back as it was, recreating its directory and mode (a hook
+ * script keeps its exec bit). Files created since the snapshot are left alone. A file that
+ * can't be written doesn't stop the others; the first error is thrown once all were tried.
+ */
+export declare function restoreFiles(snapshot: FileSnapshot): Promise<void>;
+/**
+ * Capture the bytes and mode of each file in `paths` that exists. A missing path is skipped,
+ * including one under a file where a directory would be (`ENOTDIR` on POSIX, `ENOENT` on Windows).
+ */
+export declare function snapshotFiles(paths: Iterable<string>): Promise<FileSnapshot>;
+//# sourceMappingURL=file-snapshot.d.ts.map

package/build/lib/file-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-snapshot.d.ts","sourceRoot":"","sources":["../../src/lib/file-snapshot.ts"],"names":[],"mappings":"AAIA,8EAA8E;AAC9E,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAElF;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAWxE;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAYlF"}

package/build/lib/file-snapshot.js

@@ -0,0 +1,41 @@
+import { chmod, readFile, stat } from 'node:fs/promises';
+import { writeBinaryFile } from './write-file.js';
+/**
+ * Write every file of a snapshot back as it was, recreating its directory and mode (a hook
+ * script keeps its exec bit). Files created since the snapshot are left alone. A file that
+ * can't be written doesn't stop the others; the first error is thrown once all were tried.
+ */
+export async function restoreFiles(snapshot) {
+    const errors = [];
+    for (const [path, { content, mode }] of snapshot) {
+        try {
+            await writeBinaryFile(path, content);
+            await chmod(path, mode);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    if (errors.length > 0)
+        throw errors[0];
+}
+/**
+ * Capture the bytes and mode of each file in `paths` that exists. A missing path is skipped,
+ * including one under a file where a directory would be (`ENOTDIR` on POSIX, `ENOENT` on Windows).
+ */
+export async function snapshotFiles(paths) {
+    const snapshot = new Map();
+    for (const path of new Set(paths)) {
+        const stats = await stat(path).catch((error) => {
+            const code = error.code;
+            if (code === 'ENOENT' || code === 'ENOTDIR')
+                return undefined;
+            throw error;
+        });
+        if (!stats?.isFile())
+            continue;
+        snapshot.set(path, { content: await readFile(path), mode: stats.mode });
+    }
+    return snapshot;
+}
+//# sourceMappingURL=file-snapshot.js.map

package/build/lib/file-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-snapshot.js","sourceRoot":"","sources":["../../src/lib/file-snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAEzD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAKlD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,QAAsB;IACvD,MAAM,MAAM,GAAc,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC;QACjD,IAAI,CAAC;YACH,MAAM,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YACrC,MAAM,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,MAAM,CAAC,CAAC,CAAC,CAAC;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAuB;IACzD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA6C,CAAC;IACtE,KAAK,MAAM,IAAI,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACtD,MAAM,IAAI,GAAI,KAA+B,CAAC,IAAI,CAAC;YACnD,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAC9D,MAAM,KAAK,CAAC;QACd,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE;YAAE,SAAS;QAC/B,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/build/lib/installer.d.ts

@@ -1,6 +1,9 @@
 import type { InstallPlan } from './resolver.js';
 import type { Adapter } from './schemas/adapter.js';
+import type { RegistryAsset } from './schemas/index.js';
+import type { Lockfile } from './schemas/lockfile.js';
 import { ApiCodeError } from './errors.js';
+import { type AssetIdentity } from './lockfile.js';
 export interface InstallOptions {
     /** Adapter for the target tool. */
     adapter: Adapter;
@@ -10,8 +13,16 @@ export interface InstallOptions {
         org?: string;
         version: string;
     };
+    /** Files already downloaded with {@link fetchPlanFiles}, for every entry this tool can place. */
+    files?: PlanFiles;
     /** Skip file conflict detection, allowing overwrite of non-ATK files. */
     force?: boolean;
+    /**
+     * The lockfile as this tool has it, for deciding which files are ATK-managed. In a multi-tool
+     * update the shared lockfile can already list the files of a version an earlier tool installed,
+     * which a later tool does not have yet. Defaults to the lockfile on disk.
+     */
+    managedFrom?: Lockfile;
     /** Callback for progress updates. */
     onProgress?: (message: string) => void;
     /** Pin the asset at the installed version. */
@@ -47,9 +58,46 @@ export interface InstallResult {
     type: string;
     version: string;
 }
+/** The downloaded files of a plan's entries, keyed by {@link planEntryKey}. */
+export type PlanFiles = Map<string, AssetFiles>;
+interface AssetFile {
+    /** Raw file bytes — asset files may be binary (images, spreadsheets), never assume text. */
+    content: Buffer;
+    relativePath: string;
+}
+interface AssetFiles {
+    entrypoint?: string;
+    files: AssetFile[];
+}
 export declare class InstallerError extends ApiCodeError {
     name: string;
 }
+/**
+ * A file the install would place at `path` exists and is not ATK-managed, or belongs to `owner`,
+ * another installed asset; nothing was written there.
+ */
+export declare class FileConflictError extends InstallerError {
+    name: string;
+    readonly owner?: AssetIdentity;
+    readonly path: string;
+    constructor(path: string, owner?: AssetIdentity);
+}
+/**
+ * An install plan that failed at `asset` with `cause`, after rolling back the
+ * `rolledBack` assets it had already installed. Keeps the cause's API code and
+ * guidance, so callers that name the asset themselves can quote just the cause.
+ */
+export declare class InstallPlanError extends InstallerError {
+    readonly asset: Pick<RegistryAsset, 'name' | 'org' | 'type'>;
+    readonly cause: unknown;
+    name: string;
+    constructor(asset: Pick<RegistryAsset, 'name' | 'org' | 'type'>, cause: unknown, rolledBack: number);
+}
+/** A plan whose files for `asset` could not be downloaded; nothing was written. */
+export declare class PlanDownloadError extends InstallPlanError {
+    name: string;
+    constructor(asset: Pick<RegistryAsset, 'name' | 'org' | 'type'>, cause: unknown);
+}
 /**
  * Guard for multi-tool installs run with `skipUnsupported`. Each tool skips the asset
  * types it cannot place, which is fine as long as some tool placed something. If every
@@ -67,4 +115,17 @@ export declare function assertInstalledByAnyTool(plan: InstallPlan, toolResults:
  * an inconsistent state.
  */
 export declare function executeInstallPlan(plan: InstallPlan, options: InstallOptions): Promise<InstallResult[]>;
+/**
+ * Download the files of every plan entry this tool can place, without writing anything. A
+ * caller that replaces an installed asset downloads first, so a refused download leaves the
+ * installed version in place, then passes the result to {@link executeInstallPlan} as `files`.
+ */
+export declare function fetchPlanFiles(plan: InstallPlan, adapter: Adapter): Promise<PlanFiles>;
+/**
+ * The message of an install failure for `asset`, for a caller whose own message already names
+ * it: a plan that failed at that asset gives just its cause; one that failed at another asset
+ * keeps the installer's message, which names that asset.
+ */
+export declare function installFailureMessage(error: unknown, asset: Pick<RegistryAsset, 'name' | 'org' | 'type'>): string;
+export {};
 //# sourceMappingURL=installer.d.ts.map

package/build/lib/installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../src/lib/installer.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAoB,MAAM,eAAe,CAAC;AACnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAiBpD,OAAO,EAAE,YAAY,EAAiB,MAAM,aAAa,CAAC;AAS1D,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,kEAAkE;IAClE,YAAY,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,yEAAyE;IACzE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qCAAqC;IACrC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,8CAA8C;IAC9C,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,oBAAoB,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/F,WAAW,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5D,aAAa,EAAE,YAAY,GAAG,QAAQ,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAQD,qBAAa,cAAe,SAAQ,YAAY;IACrC,IAAI,SAAoB;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,WAAW,EACjB,WAAW,EAAE,KAAK,CAAC;IAAE,OAAO,EAAE,aAAa,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7D,IAAI,CAUN;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAiH7G"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../src/lib/installer.ts"],"names":[],"mappings":"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"}

package/build/lib/installer.js

@@ -6,17 +6,59 @@ import { carryExcludedTools } from './asset-tools.js';
 import { computeConfigEntryChecksum, computeHookGroupChecksum, hashBytes } from './checksum.js';
 import { mergeConfigEntriesForTool } from './config-entries.js';
 import { detectConfigFormat, normalizeForFormat, readConfigFile, resolveConfigFormat, writeConfigFile, } from './config-file.js';
-import { ApiCodeError, errorGuidance } from './errors.js';
+import { ApiCodeError, errorGuidance, errorMessage } from './errors.js';
 import { ensureGitignoreEntries } from './gitignore.js';
 import { buildHookGroup, deriveHookCommand, hookGroupOwnsCommand, removeHookGroup } from './hook-config.js';
 import { hookScriptPath, makeExecutable } from './hook-script.js';
-import { addAssetToLockfile, readLockfile, removeAssetFromLockfile, writeLockfile } from './lockfile.js';
+import { addAssetToLockfile, readLockfile, removeAssetFromLockfile, writeLockfile, } from './lockfile.js';
+import { formatOrgName } from './org.js';
+import { pathsOwnedByOthers } from './owned-paths.js';
 import { toRelativePosix } from './paths.js';
 import { fetchAssetFileBytes, fetchAssetManifest, listAssetFiles } from './registry.js';
 import { writeBinaryFile, writeTextFile } from './write-file.js';
 export class InstallerError extends ApiCodeError {
     name = 'InstallerError';
 }
+/**
+ * A file the install would place at `path` exists and is not ATK-managed, or belongs to `owner`,
+ * another installed asset; nothing was written there.
+ */
+export class FileConflictError extends InstallerError {
+    name = 'FileConflictError';
+    owner;
+    path;
+    constructor(path, owner) {
+        super(owner
+            ? `File conflict: "${path}" belongs to the installed ${owner.type} "${formatOrgName(owner.org, owner.name)}".`
+            : `File conflict: "${path}" already exists and was not installed by ATK. Use --force to overwrite.`, owner ? { hint: 'Uninstall it first if you want this one instead.' } : {});
+        this.owner = owner;
+        this.path = path;
+    }
+}
+/**
+ * An install plan that failed at `asset` with `cause`, after rolling back the
+ * `rolledBack` assets it had already installed. Keeps the cause's API code and
+ * guidance, so callers that name the asset themselves can quote just the cause.
+ */
+export class InstallPlanError extends InstallerError {
+    asset;
+    cause;
+    name = 'InstallPlanError';
+    constructor(asset, cause, rolledBack) {
+        const rollback = rolledBack > 0 ? ` and ${rolledBack} previously installed asset(s) were rolled back` : '';
+        super(`Install failed at asset "${formatOrgName(asset.org, asset.name)}"${rollback}: ${errorMessage(cause)}`, errorGuidance(cause));
+        this.asset = asset;
+        this.cause = cause;
+    }
+}
+/** A plan whose files for `asset` could not be downloaded; nothing was written. */
+export class PlanDownloadError extends InstallPlanError {
+    name = 'PlanDownloadError';
+    constructor(asset, cause) {
+        super(asset, cause, 0);
+        this.message = `Download failed for asset "${formatOrgName(asset.org, asset.name)}": ${errorMessage(cause)}`;
+    }
+}
 /**
  * Guard for multi-tool installs run with `skipUnsupported`. Each tool skips the asset
  * types it cannot place, which is fine as long as some tool placed something. If every
@@ -52,8 +94,8 @@ export async function executeInstallPlan(plan, options) {
     // Read lockfile once — used for both conflict detection and per-asset install logic
     let lockfile = await readLockfile(options.projectDir);
     const initialLockfile = lockfile;
-    // Build set of ATK-managed file paths from the lockfile for conflict detection
-    const managedPaths = buildManagedPathsSet(lockfile, options.projectDir, options.adapter);
+    // Map each ATK-managed file path to the assets that installed it, for conflict detection
+    const managedPaths = buildManagedPaths(options.managedFrom ?? lockfile, options.projectDir, options.adapter);
     // In multi-tool projects the same plan runs once per tool. A tool that has no
     // placement for an asset type (e.g. Codex CLI has no `rule` placement) skips
     // those entries instead of aborting the whole run for that tool. When the tool
@@ -75,6 +117,9 @@ export async function executeInstallPlan(plan, options) {
         for (const entry of supportedEntries) {
             const { lockfile: updatedLockfile, result } = await installAsset(entry, options, managedPaths, lockfile);
             results.push(result);
+            // A later entry of this plan may land on these files, and must see whose they are.
+            for (const file of result.filesPlaced)
+                addManagedPath(managedPaths, file.destination, entry.asset);
             lockfile = updatedLockfile;
         }
     }
@@ -84,16 +129,21 @@ export async function executeInstallPlan(plan, options) {
             options.onProgress?.(`Install failed, rolling back ${results.length} installed asset(s)...`);
             for (let i = results.length - 1; i >= 0; i--) {
                 const result = results[i];
+                const rolledBack = supportedEntries[i].asset;
                 options.onProgress?.(`Rolling back ${result.name}...`);
-                // Delete placed files (best-effort)
+                // Delete placed files (best-effort), except one another asset installed before this plan
+                // also owns: a global and an org asset of one name and type can share a placement.
+                const ownedByOthers = pathsOwnedByOthers(initialLockfile, rolledBack, options.adapter, options.projectDir);
                 for (const file of result.filesPlaced) {
+                    if (ownedByOthers.has(file.destination))
+                        continue;
                     try {
                         if (existsSync(file.destination)) {
                             await unlink(file.destination);
                         }
                     }
                     catch (error) {
-                        options.onProgress?.(`Warning: Failed to delete file during rollback: ${file.destination} — ${error instanceof Error ? error.message : String(error)}`);
+                        options.onProgress?.(`Warning: Failed to delete file during rollback: ${file.destination} — ${errorMessage(error)}`);
                     }
                 }
                 // Revert config file entries (best-effort)
@@ -104,7 +154,7 @@ export async function executeInstallPlan(plan, options) {
                         await revertConfigEntry(configPath, entry.key, entry.command, format, options.onProgress);
                     }
                     catch (error) {
-                        options.onProgress?.(`Warning: Failed to revert config entry ${entry.key} during rollback — ${error instanceof Error ? error.message : String(error)}`);
+                        options.onProgress?.(`Warning: Failed to revert config entry ${entry.key} during rollback — ${errorMessage(error)}`);
                     }
                 }
                 // Revert the lockfile entry using the in-memory lockfile (best-effort). An asset that
@@ -112,7 +162,6 @@ export async function executeInstallPlan(plan, options) {
                 // tool's pass in a multi-tool install) gets its previous entry back, so other tools'
                 // config entries survive; a newly added asset is removed.
                 try {
-                    const rolledBack = supportedEntries[i].asset;
                     const previousEntry = (initialLockfile.assets ?? []).find((a) => a.name === rolledBack.name && a.type === rolledBack.type && a.org === rolledBack.org);
                     lockfile = previousEntry
                         ? addAssetToLockfile(lockfile, previousEntry)
@@ -120,19 +169,58 @@ export async function executeInstallPlan(plan, options) {
                     await writeLockfile(options.projectDir, lockfile);
                 }
                 catch (error) {
-                    options.onProgress?.(`Warning: Failed to remove lockfile entry during rollback for ${result.name} — ${error instanceof Error ? error.message : String(error)}`);
+                    options.onProgress?.(`Warning: Failed to remove lockfile entry during rollback for ${result.name} — ${errorMessage(error)}`);
                 }
             }
             options.onProgress?.(`Rollback complete.`);
         }
-        // Re-throw the original error wrapped in InstallerError with rollback context,
-        // keeping any API error code and recovery hint/command (e.g. from an API auth failure).
-        const originalMessage = error instanceof Error ? error.message : String(error);
-        throw new InstallerError(`Install failed at asset "${supportedEntries[results.length]?.asset.name ?? 'unknown'}" ` +
-            `and ${results.length} previously installed asset(s) were rolled back: ${originalMessage}`, errorGuidance(error));
+        // Re-throw the original error with rollback context, keeping any API error code and
+        // recovery hint/command (e.g. from an API auth failure).
+        throw new InstallPlanError(supportedEntries[results.length].asset, error, results.length);
     }
     return results;
 }
+/**
+ * Download the files of every plan entry this tool can place, without writing anything. A
+ * caller that replaces an installed asset downloads first, so a refused download leaves the
+ * installed version in place, then passes the result to {@link executeInstallPlan} as `files`.
+ */
+export async function fetchPlanFiles(plan, adapter) {
+    const files = new Map();
+    for (const entry of plan.entries) {
+        if (!getPlacement(adapter, entry.asset.type))
+            continue;
+        try {
+            files.set(planEntryKey(entry), await fetchAssetFiles(entry.asset, entry.version, entry.asset.org));
+        }
+        catch (error) {
+            throw new PlanDownloadError(entry.asset, error);
+        }
+    }
+    return files;
+}
+/**
+ * The message of an install failure for `asset`, for a caller whose own message already names
+ * it: a plan that failed at that asset gives just its cause; one that failed at another asset
+ * keeps the installer's message, which names that asset.
+ */
+export function installFailureMessage(error, asset) {
+    const atAsset = error instanceof InstallPlanError &&
+        error.asset.name === asset.name &&
+        error.asset.type === asset.type &&
+        error.asset.org === asset.org;
+    return errorMessage(atAsset ? error.cause : error);
+}
+/** Record `owner` as one of the assets that placed the file at `path`. */
+function addManagedPath(paths, path, owner) {
+    const owners = paths.get(path);
+    if (owners) {
+        owners.push(owner);
+    }
+    else {
+        paths.set(path, [owner]);
+    }
+}
 /**
  * Append entry names to a string-array key in a config file (e.g., `enabledMcpjsonServers`
  * in `.claude/settings.local.json`), creating the file/array as needed and de-duplicating.
@@ -167,37 +255,39 @@ async function addToEnabledList(enabledListFilePath, enabledListKey, names, onPr
     }
     catch (error) {
         // Non-fatal — log but don't fail the install
-        onProgress?.(`Warning: Failed to update enabled list ${enabledListFilePath} — ${error instanceof Error ? error.message : String(error)}`);
+        onProgress?.(`Warning: Failed to update enabled list ${enabledListFilePath} — ${errorMessage(error)}`);
     }
 }
 /**
- * Build a set of all file paths managed by ATK from the given lockfile.
- * Used for conflict detection — files in this set can be safely overwritten.
+ * Map every file path managed by ATK in the given lockfile to the assets that installed it.
+ * Used for conflict detection — an asset may overwrite only the files it installed itself.
  * Resolves installed paths dynamically via the adapter rather than reading them from the lockfile.
  */
-function buildManagedPathsSet(lockfile, projectDir, adapter) {
-    const paths = new Set();
+function buildManagedPaths(lockfile, projectDir, adapter) {
+    const paths = new Map();
     for (const asset of lockfile.assets ?? []) {
         const resolved = resolveInstalledPaths(asset, adapter, projectDir);
         for (const file of resolved.files) {
-            paths.add(join(projectDir, file.installedPath));
+            addManagedPath(paths, join(projectDir, file.installedPath), asset);
         }
     }
     return paths;
 }
 /**
- * Check if a file at the destination path would conflict with an existing non-ATK file.
- * Throws InstallerError if the file exists and is not tracked in the lockfile.
- * ATK-managed files (in the lockfile) can be safely overwritten (e.g., reinstall/update).
+ * Check if a file at the destination path would conflict with a file `asset` didn't install.
+ * Throws FileConflictError if the file exists and is not tracked in the lockfile, or is tracked
+ * only for other assets (a global and an org asset of one name and type share a placement).
+ * The asset's own files can be safely overwritten (e.g., reinstall/update).
  */
-async function checkFileConflict(destPath, managedPaths) {
+async function checkFileConflict(destPath, managedPaths, asset) {
     if (!existsSync(destPath)) {
         return;
     }
-    if (managedPaths.has(destPath)) {
+    const owners = managedPaths.get(destPath) ?? [];
+    if (owners.some((o) => o.name === asset.name && o.type === asset.type && o.org === asset.org)) {
         return;
     }
-    throw new InstallerError(`File conflict: "${destPath}" already exists and was not installed by ATK. Use --force to overwrite.`);
+    throw new FileConflictError(destPath, owners[0]);
 }
 /**
  * Fetch all files for an asset version from the ATK API, plus its
@@ -225,7 +315,7 @@ async function fetchAssetFiles(asset, version, org) {
         if (error instanceof InstallerError) {
             throw error;
         }
-        const message = error instanceof Error ? error.message : String(error);
+        const message = errorMessage(error);
         throw new InstallerError(message, errorGuidance(error));
     }
 }
@@ -259,8 +349,14 @@ async function installAsset(entry, options, managedPaths, lockfile) {
     }
     // Determine base path
     const basePath = projectDir;
-    // Fetch asset files from the ATK API (version-aware, org-aware)
-    const { entrypoint: declaredEntrypoint, files: assetFiles } = await fetchAssetFiles(asset, entry.version, entry.asset.org);
+    // Fetch asset files from the ATK API (version-aware, org-aware), unless the caller already did.
+    // A caller that downloaded first may have removed the installed files since, so a gap in its
+    // download must not turn into a fresh request that can be refused.
+    const prefetched = options.files?.get(planEntryKey(entry));
+    if (options.files && !prefetched) {
+        throw new InstallerError(`The files of "${asset.name}"@${entry.version} were not downloaded before the install.`);
+    }
+    const { entrypoint: declaredEntrypoint, files: assetFiles } = prefetched ?? (await fetchAssetFiles(asset, entry.version, entry.asset.org));
     // Find the entrypoint file
     const entrypointFile = assetFiles.find((f) => isEntrypoint(f.relativePath, asset.type, declaredEntrypoint));
     // Branch on placement type
@@ -298,12 +394,15 @@ async function installAsset(entry, options, managedPaths, lockfile) {
     }
     else if (placement.entrypointName) {
         // Directory-based placement (e.g., skills)
-        for (const file of assetFiles) {
-            const destPath = resolveFilePath(placement.path, asset.name, basePath, file.relativePath, asset.type, placement.entrypointName, declaredEntrypoint);
+        const destinations = assetFiles.map((file) => resolveFilePath(placement.path, asset.name, basePath, file.relativePath, asset.type, placement.entrypointName, declaredEntrypoint));
+        // Check every destination before writing any, so a conflict leaves none of the asset's files behind.
+        if (!force) {
+            for (const destPath of destinations)
+                await checkFileConflict(destPath, managedPaths, asset);
+        }
+        for (const [index, file] of assetFiles.entries()) {
+            const destPath = destinations[index];
             const destDir = dirname(destPath);
-            if (!force) {
-                await checkFileConflict(destPath, managedPaths);
-            }
             if (!existsSync(destDir)) {
                 await mkdir(destDir, { recursive: true });
             }
@@ -322,12 +421,14 @@ async function installAsset(entry, options, managedPaths, lockfile) {
     }
     else {
         // Default single-file placement
-        for (const file of assetFiles) {
-            const destPath = resolveFilePath(placement.path, asset.name, basePath, file.relativePath, asset.type, undefined, declaredEntrypoint);
+        const destinations = assetFiles.map((file) => resolveFilePath(placement.path, asset.name, basePath, file.relativePath, asset.type, undefined, declaredEntrypoint));
+        if (!force) {
+            for (const destPath of destinations)
+                await checkFileConflict(destPath, managedPaths, asset);
+        }
+        for (const [index, file] of assetFiles.entries()) {
+            const destPath = destinations[index];
             const destDir = dirname(destPath);
-            if (!force) {
-                await checkFileConflict(destPath, managedPaths);
-            }
             if (!existsSync(destDir)) {
                 await mkdir(destDir, { recursive: true });
             }
@@ -502,7 +603,7 @@ async function mergeFragmentConfig(configFilePath, configKey, format, projectDir
     }
     catch (error) {
         // Non-fatal — log but don't fail the install
-        onProgress?.(`Warning: Failed to merge config fragment into ${configFilePath} — ${error instanceof Error ? error.message : String(error)}`);
+        onProgress?.(`Warning: Failed to merge config fragment into ${configFilePath} — ${errorMessage(error)}`);
         return empty;
     }
 }
@@ -557,10 +658,14 @@ async function mergeHookConfig(configFilePath, configKey, format, hookConfig, co
     }
     catch (error) {
         // Non-fatal — log but don't fail the install
-        onProgress?.(`Warning: Failed to merge hook config into ${configFilePath} — ${error instanceof Error ? error.message : String(error)}`);
+        onProgress?.(`Warning: Failed to merge hook config into ${configFilePath} — ${errorMessage(error)}`);
         return [];
     }
 }
+/** The {@link PlanFiles} key of a plan entry: one asset version. */
+function planEntryKey(entry) {
+    return `${entry.asset.type}:${entry.asset.org ?? ''}:${entry.asset.name}@${entry.version}`;
+}
 /**
  * Resolve the destination file path for an asset file.
  * For directory-based placement (entrypointName set), the path is a directory template.
@@ -622,7 +727,7 @@ async function revertConfigEntry(configFilePath, keyPath, command, format, onPro
         await writeConfigFile(configFilePath, config, format, onProgress);
     }
     catch (error) {
-        onProgress?.(`Warning: Failed to revert config entry ${keyPath} in ${configFilePath} — ${error instanceof Error ? error.message : String(error)}`);
+        onProgress?.(`Warning: Failed to revert config entry ${keyPath} in ${configFilePath} — ${errorMessage(error)}`);
     }
 }
 /**
@@ -680,7 +785,7 @@ async function updateConfigFile(configFilePath, configKey, format, assetName, as
     }
     catch (error) {
         // Non-fatal — log but don't fail the install
-        onProgress?.(`Warning: Failed to update config file ${configFilePath} — ${error instanceof Error ? error.message : String(error)}`);
+        onProgress?.(`Warning: Failed to update config file ${configFilePath} — ${errorMessage(error)}`);
         return null;
     }
 }