@detergent-software/atk 8.1.2-dev.9 → 8.1.3-dev.1

package/build/lib/installer.d.ts

@@ -1,6 +1,9 @@
-import type { InstallPlan } from './resolver.js';
+import type { InstallPlan, InstallPlanEntry } 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,22 @@ 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 from before the command, for deciding which assets this tool already had in
+     * place, which a failed plan keeps. A multi-tool install passes it, since an earlier tool's pass
+     * has rewritten the shared lockfile by then. Defaults to `managedFrom`, then the lockfile on disk.
+     */
+    installedBefore?: Lockfile;
+    /**
+     * 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. */
@@ -27,6 +44,15 @@ export interface InstallOptions {
     skipUnsupported?: boolean;
 }
 export interface InstallResult {
+    /**
+     * The memory-template block the install wrote into `file` (relative, like `configFilesCreated`),
+     * the block of that name it `replaced`, and whether it `created` the file; a rollback undoes it.
+     */
+    blockWritten?: {
+        created: boolean;
+        file: string;
+        replaced?: string;
+    };
     bundleOrigin?: {
         name: string;
         org?: string;
@@ -38,18 +64,65 @@ export interface InstallResult {
         file: string;
         key: string;
     }>;
+    /** The config files the install created, relative like `configEntriesCreated[].file`; a rollback deletes them once empty. */
+    configFilesCreated?: string[];
+    /** The names the install added to its placement's enabled list (e.g. `enabledMcpjsonServers`). */
+    enabledListAdded?: string[];
     filesPlaced: Array<{
         destination: string;
         source: string;
     }>;
     installReason: 'dependency' | 'direct';
     name: string;
+    org?: string;
     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. With `entry`, the conflict is that part of
+ * the file (a memory-template's block, a config entry), which `owner` wrote.
+ */
+export declare class FileConflictError extends InstallerError {
+    name: string;
+    readonly owner?: AssetIdentity;
+    readonly path: string;
+    /** What conflicts, quoted for a message: `"<path>"`, or `the <entry> in "<path>"`. */
+    readonly where: string;
+    constructor(path: string, owner?: AssetIdentity, entry?: string);
+}
+/**
+ * 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;
+    /** The plan kept what it installed before `asset`, because it moved an installed asset to another version. */
+    readonly keptInstall: boolean;
+    name: string;
+    constructor(asset: Pick<RegistryAsset, 'name' | 'org' | 'type'>, cause: unknown, rolledBack: number, keptInstall?: boolean);
+}
+/** 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
@@ -62,9 +135,41 @@ export declare function assertInstalledByAnyTool(plan: InstallPlan, toolResults:
 }>): void;
 /**
  * Execute a full install plan — install all assets in order.
- * On partial failure, rolls back previously installed assets (deletes placed files,
- * reverts config entries, removes lockfile entries) so the system is not left in
- * an inconsistent state.
+ * On partial failure, deletes the files the failing asset wrote where no file was before placing
+ * its files failed, and rolls back the assets the plan added before it (deletes placed files,
+ * reverts config entries and memory-template blocks, removes lockfile entries) so the system is not
+ * left in an inconsistent state. An asset the tool already had in place keeps what the plan placed,
+ * since rolling it back would delete its working copy, and gets its lockfile entry back. When the
+ * plan moved such an asset to another version, which may need the assets the plan added, nothing is
+ * rolled back ({@link InstallPlanError.keptInstall}).
  */
 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;
+/** The entries of `plan` the adapter's tool has a placement for, in plan order. */
+export declare function placeableEntries(plan: InstallPlan, adapter: Adapter): InstallPlanEntry[];
+/**
+ * Undo the installs of `installed` for the adapter's tool, in reverse order (best-effort): delete
+ * their placed files, revert their config entries (deleting a config file they created once it is
+ * empty), put back the memory-template block they replaced or take out the one they added (deleting
+ * a file they created once it is empty), take the names they added out of an enabled list, and give
+ * each asset its lockfile entry from `before`, or remove it. A file or config entry an asset of
+ * `before` also owns is kept.
+ * Returns `lockfile` with the entries reverted, as written.
+ */
+export declare function rollBackInstalledAssets(installed: Array<{
+    asset: Pick<RegistryAsset, 'name' | 'org' | 'type'>;
+    result: InstallResult;
+}>, before: Lockfile, lockfile: Lockfile, options: Pick<InstallOptions, 'adapter' | 'onProgress' | 'projectDir'>): Promise<Lockfile>;
+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,EAA+B,MAAM,aAAa,CAAC;AASxE,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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"}