@graftland/package-manager 0.0.0-stage → 0.2.0-beta.0

package/README.zh-TW.md

@@ -0,0 +1,184 @@
+# @graftland/package-manager
+
+[English](https://github.com/graftland/graft/blob/main/packages/package-manager/README.md)
+|
+[简体中文](https://github.com/graftland/graft/blob/main/packages/package-manager/README.zh-CN.md)
+| 繁體中文
+
+使用 npm、pnpm 或 Yarn 安裝相依套件，並在失敗時還原。
+
+支援的最低 Node.js 版本是 22.19。Windows 依現況提供。Windows 上的行程樹清理和還原沒有經過驗證，也不作承諾。
+
+```sh
+npm install @graftland/package-manager effect
+```
+
+`make` 會偵測專案所用的套件管理器。它的 `install`
+可以新增、更新或移除相依套件。如果安裝失敗，它會還原 `package.json`
+和鎖定檔。`graft add` 和 `graft remove` 使用它。
+
+## 安裝的所有權與復原
+
+每個專案只使用一個管理器。呼叫端必須讓管理器及其子行程獨占專案的寫入權限。這從一次
+`install` 呼叫開始，持續到它結束，包括復原階段。
+
+- 在此期間，不要編輯專案檔案。
+- 不要同時執行另一個安裝程式。
+- 同一個管理器內的呼叫是循序的。Graft 不會在多個管理器、編輯器或行程之間強制加鎖。
+
+在 POSIX 上，行程清理只涵蓋安裝程式最初的行程群組。安裝腳本和復原腳本不得建立不受管理的寫入者。例如，處於獨立行程群組的子行程，以及持續寫入專案檔案的常駐程式。Graft 不提供作業系統層級的隔離，也不會發現逃逸的寫入者。確認最初的行程群組已經停止，並不能證明所有可能的後代都已經停止。違反這條規則的腳本不在還原保證的範圍內。
+
+受管理的路徑必須是一般檔案，或者不存在。`make` 和每次 `install` 都使用 `lstat`
+檢查快照集合。快照集合包括
+`package.json`、鎖定檔，以及被追蹤的設定檔和安裝狀態檔。
+
+- 符號連結會被拒絕，包括懸空連結。其他檔案類型也會被拒絕。
+- 錯誤是
+  `UnsupportedFileTypeError`。它在任何交易寫入之前、任何安裝程式啟動之前擲出。
+- 錯誤會給出 `path` 和 `fileType`。連結及其目標保持不變。
+- 在交易開始之前的拒絕，不需要復原，也不會讓管理器無法使用。
+
+### 還原
+
+當安裝在提交之前失敗或被中斷時，會執行還原。還原需要先確認最初的行程群組已經停止。然後它會做這些事：
+
+- 把已備份的套件檔案逐位元組還原，並保留它們記錄下來的權限位元和擁有者。
+- 移除安裝之前不存在的被追蹤檔案。
+
+被追蹤的檔案包括
+`package.json`、鎖定檔，以及管理器所追蹤的套件管理器設定檔和安裝狀態檔。
+
+還原會覆蓋安裝期間所做的變更。它不會偵測衝突，也不會合併編輯。
+
+如果專案已經有所選套件管理器的鎖定檔，復原階段還會嘗試修復
+`node_modules`。復原錯誤會與原始失敗一起保留。不承諾在行程當機之後復原。
+
+### 檔案寫入與行程清理
+
+已接受的檔案寫入有一個完成邊界。取消會等待原生操作完成，然後才進行還原、清理快照，以及釋放管理器的鎖。交易會追蹤它自己的檔案寫入以及最初的安裝程式行程群組。建立快照和還原寫入也有同樣的完成保證。
+
+每個安裝行程和每個復原行程都有十分鐘的結束等待時間。取消或逾時會在還原檔案之前關閉它的行程 scope。
+
+- 行程會收到 SIGTERM。
+- 如果五秒後它還沒有停止，就會收到 SIGKILL。
+- 在 POSIX 上，即使 kill 成功，也必須確認原行程群組已不存在。每 20 毫秒檢查一次，最多追加 100 次檢查（等待兩秒），給短暫殘留的殭屍行程群組留出回收時間。EPERM 視為仍然存在，不視為已消失。
+- 如果行程群組仍存在或檢查失敗，則終止未獲確認：管理器保留快照，不執行回復和復原安裝，並進入
+  `RecoveryRequired`。
+- 行程清理失敗會與安裝和復原的失敗一起保留在回傳的 cause 中。
+- 結束逾時不包括行程清理和檔案還原，也不是整個「安裝並復原」操作的截止時間。
+
+Node 轉接器可能會把原始的作業系統 errno 取代為通用的 kill 失敗。只有 POSIX 檢查確認行程群組不存在後，PackageManager 才消解帶有 ESRCH 的訊號失敗，或轉接器特定的
+`Unknown` kill 錯誤（cause 為
+`Failed to kill child process`）。同一 Cause 中的其他原因仍然保留，包括 join 失敗、其他 kill 錯誤、defect 和中斷。行程群組仍存在時保留原始 Cause；檢查失敗時保留兩個完整 Cause。
+
+## 已提交的安裝與快照清理
+
+`install` 成功的結果表示相依套件的變更已經提交。
+
+`result.snapshotCleanupFailure` 是 `Option<SnapshotCleanupFailure>`：
+
+- `None` 表示快照刪除成功。
+- `Some` 包含 `snapshotDirectory` 和完整的清理 `cause`，包括 defect。
+
+提交之後刪除快照失敗，不會讓這次安裝變成失敗，也不會觸發還原。管理器仍然可用，`recoveryRequired`
+仍然是 `None`。
+
+呼叫端應該這樣做：
+
+- 檢查這個欄位，回報或記錄它的 Cause。
+- 在檔案系統問題解決之後，重試刪除該快照目錄。該目錄可能已被部分刪除。
+- 不要還原舊的快照，也不要僅僅因為快照刪除失敗就重複安裝。那些變更已經提交了。
+- 保留下來的資料可能包含憑證，所以要確保它最終被刪除。
+
+提交之前的失敗仍然會使操作失敗並執行還原。任何快照清理失敗都會與原始失敗合併。
+
+取消可能會使提交之後的結果無法送達。這並不能證明變更已被撤銷。這種情況下，清理失敗會保留在被中斷的 Cause 中。
+
+## 何時需要手動復原
+
+在安裝變更專案檔案之前，會先儲存一份快照。快照位於作業系統暫存目錄中一個私有的
+`graft-recovery-*` 目錄裡。
+
+- 只有成功的安裝或完整的還原，才允許刪除快照並執行下一次安裝。
+- 已提交但快照刪除失敗的安裝，依上文所述回報。
+- 行程終止和交易完成是兩個獨立的條件。停止寫入者，還原才能開始，但這並不證明還原成功。
+
+只要有任何一個還原步驟失敗，管理器就會保留快照，並需要手動復原。這包括在復原之前或之後還原檔案，以及執行復原安裝程式。即使最後的檔案還原成功，這條規則也適用，因為失敗的復原可能讓
+`node_modules` 不完整。
+
+管理器如何還原一個檔案：
+
+1. 在目標目錄中以獨占方式建立暫存檔，模式為 `0600`。
+2. 當平台回報了儲存的 uid/gid 時，先還原它們，然後還原權限位元。
+3. 對檔案執行 sync 並關閉。
+4. 把該檔案重新命名覆蓋到目標上。
+
+中繼資料失敗和暫存檔清理失敗同樣需要手動復原，並保留在 Cause 中。時間戳記、ACL 和擴充屬性不會被記錄。
+
+如果無法確認行程已經終止，就不會再進行任何還原或復原。這是為了避免與可能仍在寫入的行程發生衝突。
+
+### 復原錯誤
+
+失敗呼叫的 Cause 會保留原始失敗以及所有還原和終止的失敗。它包含一個
+`RecoveryRequiredError`，其欄位如下：
+
+- `snapshotDirectory` 給出儲存的位置。
+- `directory` 識別專案。
+- `recoveryCause` 保留完整的原始 Cause 和復原 Cause。
+- `operation`：在寫入者已停止但還原不完整時是 `rollback`；在無法確認終止時是
+  `install` 或 `recover`，此時 `processId` 和 `terminationCause`
+  給出行程的詳細資訊。
+
+取消之後，呼叫端還可以讀取 `manager.recoveryRequired`。它是一個產出
+`Option<RecoveryRequiredError>` 的 Effect。呼叫端不需要去攔截被中斷的呼叫。
+
+管理器會永久拒絕之後所有的 `install`
+呼叫，並回傳這個帶型別的錯誤。這包括已經排隊的呼叫，以及變更集為空的呼叫。`readState`
+仍然是唯讀的診斷操作。在專案檔案不完整時，它可能失敗。
+
+### 手動復原的步驟
+
+1. 找出失敗的安裝程式及其所有後代，並停止它們。記錄下來的行程 ID 只用於診斷，不能證明之後具有相同 ID 的行程屬於這次安裝。在所有寫入者停止之前，不要還原檔案，也不要啟動另一個安裝程式。
+2. 解決阻止還原的檔案系統問題，例如檔案權限。然後還原檔案：
+   - 開啟 `snapshotDirectory` 中的 `snapshot.json`。檢查其中的專案 `directory`
+     和 `agent`。
+   - 對每個 `files` 項目，把指定的 `backup` 中的位元組複製到專案 `name`
+     旁邊的暫存檔中。以私有、獨占的方式建立該暫存檔。
+   - 當 `uid` 和 `gid` 不為 null 時，還原記錄下來的值，然後還原
+     `mode`。請在取代目標之前完成這些。
+   - 這些中繼資料值是 JSON 整數。`mode`
+     是數值形式的權限位元遮罩，不是八進位格式的字串。
+   - 視需要建立父目錄。
+   - `backup` 為 null 表示該檔案原本不存在。如果它現在存在，就刪除它。
+3. 使用所選的套件管理器，基於已還原的清單檔和鎖定檔修復
+   `node_modules`。該行程停止之後，如果它重寫了快照中的檔案，請再次還原這些檔案。快照不包含
+   `node_modules`。
+4. 驗證專案。然後刪除快照，並用 `make`
+   建立一個新的管理器。舊的管理器沒有重設操作。
+
+快照可能包含來自套件管理器設定檔的憑證。請保持私有。它們在管理器和 Effect
+scope 關閉之後依然存在。但是作業系統可能會清理暫存目錄。如果手動復原會被延後，請把保留的快照複製到一個安全的私有位置。
+
+這個機制不是當機復原，也不是跨行程的專案鎖。建立新的管理器，並不會讓仍在執行的安裝程式變得安全。
+
+## 文件
+
+- [命令列](https://graftland.github.io/graft/zh-tw/cli/)
+
+屬於 [Graft](https://github.com/graftland/graft)。依
+[Apache 2.0](https://github.com/graftland/graft/blob/main/LICENSE) 授權。
+
+## 套件管理器宣告
+
+共用的 `PackageManagerDeclaration` Schema 接受 `npm`、`pnpm` 或
+`yarn`，後接精確的 SemVer 版本（版本部分最多 256 個字元），可包含預發布識別碼。它拒絕空後綴、版本及預發布數字識別碼的前置零、版本範圍、標籤、URL 和首尾空白。
+
+`+` 後綴僅用於
+[Corepack hash](https://github.com/nodejs/corepack#when-authoring-packages)：支援
+`sha224`、`sha256`、`sha384`、`sha512`，後接點號及分別為 56、64、96、128 個字元的小寫十六進位摘要。不支援一般 SemVer
+build metadata。這裡只檢查宣告語法，不下載或驗證套件管理器壓縮檔的真實性。
+
+建立專案與偵測套件管理器使用同一個 Schema，可從
+`@graftland/package-manager/PackageManagerDeclaration`
+匯入。建立時完整保留傳入的宣告；偵測時明確指定的 `agent`
+仍優先於 manifest 宣告。

package/dist/PackageManagerDeclaration.d.ts

@@ -0,0 +1,6 @@
+import { Schema } from "effect";
+export declare const PackageManagerName: Schema.Literals<readonly ["npm", "pnpm", "yarn"]>;
+/** Exact SemVer with optional prerelease and Corepack hash; ranges, URLs and arbitrary build metadata are unsupported. */
+export declare const PackageManagerDeclaration: Schema.TemplateLiteralParser<readonly [Schema.Literals<readonly ["npm", "pnpm", "yarn"]>, "@", Schema.decodeTo<Schema.SemVerFromString, Schema.String, never, never>]>;
+export type PackageManagerDeclaration = typeof PackageManagerDeclaration.Type;
+//# sourceMappingURL=PackageManagerDeclaration.d.ts.map

package/dist/PackageManagerDeclaration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PackageManagerDeclaration.d.ts","names":[],"sources":["../src/PackageManagerDeclaration.ts"],"mappings":";qBAEa,oBAAkB,OAAA;;qBAkClB,2BAAyB,OAAA,gCAAA,OAAA,iDAAA,OAAA,SAAA,OAAA,kBAAA,OAAA;YAK1B,mCAAmC,0BAA0B"}

package/dist/PackageManagerDeclaration.js

@@ -0,0 +1,24 @@
+import { Schema } from "effect";
+// src/PackageManagerDeclaration.ts
+const PackageManagerName = Schema.Literals([
+	"npm",
+	"pnpm",
+	"yarn"
+]);
+const CorepackHash = Schema.Union([
+	Schema.Tuple([Schema.Literal("sha224"), Schema.String.check(Schema.isPattern(/^[0-9a-f]{56}$/))]),
+	Schema.Tuple([Schema.Literal("sha256"), Schema.String.check(Schema.isPattern(/^[0-9a-f]{64}$/))]),
+	Schema.Tuple([Schema.Literal("sha384"), Schema.String.check(Schema.isPattern(/^[0-9a-f]{96}$/))]),
+	Schema.Tuple([Schema.Literal("sha512"), Schema.String.check(Schema.isPattern(/^[0-9a-f]{128}$/))])
+]);
+const isCorepackHash = Schema.is(CorepackHash);
+const Version = Schema.String.check(Schema.isMaxLength(256)).pipe(Schema.decodeTo(Schema.SemVerFromString)).check(Schema.makeFilter((version) => version.build.length === 0 || isCorepackHash(version.build), { expected: "no build metadata, or a Corepack sha224/sha256/sha384/sha512 lowercase hexadecimal hash" }));
+/** Exact SemVer with optional prerelease and Corepack hash; ranges, URLs and arbitrary build metadata are unsupported. */
+const PackageManagerDeclaration = Schema.TemplateLiteralParser([
+	PackageManagerName,
+	"@",
+	Version
+]);
+export { PackageManagerDeclaration, PackageManagerName };
+
+//# sourceMappingURL=PackageManagerDeclaration.js.map

package/dist/PackageManagerDeclaration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PackageManagerDeclaration.js","names":[],"sources":["../src/PackageManagerDeclaration.ts"],"sourcesContent":["import { Schema } from \"effect\"\n\nexport const PackageManagerName = Schema.Literals([\"npm\", \"pnpm\", \"yarn\"])\n\nconst CorepackHash = Schema.Union([\n\tSchema.Tuple([\n\t\tSchema.Literal(\"sha224\"),\n\t\tSchema.String.check(Schema.isPattern(/^[0-9a-f]{56}$/)),\n\t]),\n\tSchema.Tuple([\n\t\tSchema.Literal(\"sha256\"),\n\t\tSchema.String.check(Schema.isPattern(/^[0-9a-f]{64}$/)),\n\t]),\n\tSchema.Tuple([\n\t\tSchema.Literal(\"sha384\"),\n\t\tSchema.String.check(Schema.isPattern(/^[0-9a-f]{96}$/)),\n\t]),\n\tSchema.Tuple([\n\t\tSchema.Literal(\"sha512\"),\n\t\tSchema.String.check(Schema.isPattern(/^[0-9a-f]{128}$/)),\n\t]),\n])\nconst isCorepackHash = Schema.is(CorepackHash)\nconst Version = Schema.String.check(Schema.isMaxLength(256))\n\t.pipe(Schema.decodeTo(Schema.SemVerFromString))\n\t.check(\n\t\tSchema.makeFilter(\n\t\t\t(version) => version.build.length === 0 || isCorepackHash(version.build),\n\t\t\t{\n\t\t\t\texpected:\n\t\t\t\t\t\"no build metadata, or a Corepack sha224/sha256/sha384/sha512 lowercase hexadecimal hash\",\n\t\t\t},\n\t\t),\n\t)\n\n/** Exact SemVer with optional prerelease and Corepack hash; ranges, URLs and arbitrary build metadata are unsupported. */\nexport const PackageManagerDeclaration = Schema.TemplateLiteralParser([\n\tPackageManagerName,\n\t\"@\",\n\tVersion,\n])\nexport type PackageManagerDeclaration = typeof PackageManagerDeclaration.Type\n"],"mappings":";;AAEA,MAAa,qBAAqB,OAAO,SAAS;CAAC;CAAO;CAAQ;AAAM,CAAC;AAEzE,MAAM,eAAe,OAAO,MAAM;CACjC,OAAO,MAAM,CACZ,OAAO,QAAQ,QAAQ,GACvB,OAAO,OAAO,MAAM,OAAO,UAAU,gBAAgB,CAAC,CACvD,CAAC;CACD,OAAO,MAAM,CACZ,OAAO,QAAQ,QAAQ,GACvB,OAAO,OAAO,MAAM,OAAO,UAAU,gBAAgB,CAAC,CACvD,CAAC;CACD,OAAO,MAAM,CACZ,OAAO,QAAQ,QAAQ,GACvB,OAAO,OAAO,MAAM,OAAO,UAAU,gBAAgB,CAAC,CACvD,CAAC;CACD,OAAO,MAAM,CACZ,OAAO,QAAQ,QAAQ,GACvB,OAAO,OAAO,MAAM,OAAO,UAAU,iBAAiB,CAAC,CACxD,CAAC;AACF,CAAC;AACD,MAAM,iBAAiB,OAAO,GAAG,YAAY;AAC7C,MAAM,UAAU,OAAO,OAAO,MAAM,OAAO,YAAY,GAAG,CAAC,CAAC,CAC1D,KAAK,OAAO,SAAS,OAAO,gBAAgB,CAAC,CAAC,CAC9C,MACA,OAAO,YACL,YAAY,QAAQ,MAAM,WAAW,KAAK,eAAe,QAAQ,KAAK,GACvE,EACC,UACC,0FACF,CACD,CACD;;AAGD,MAAa,4BAA4B,OAAO,sBAAsB;CACrE;CACA;CACA;AACD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+import { PackageManagerDeclaration } from "./PackageManagerDeclaration.js";
+import { SnapshotCleanupFailure, UnsupportedFileTypeError } from "./snapshot.js";
+import { Changes, PackageName } from "./manifest.js";
+import { Cause, Effect, FileSystem, HashMap, Option, Path, PlatformError, Schema } from "effect";
+import { ChildProcessSpawner } from "effect/process";
+export declare const Agent: Schema.Literals<readonly ["npm", "pnpm", "yarn-classic", "yarn-berry"]>;
+export type Agent = typeof Agent.Type;
+declare const PackageManagerError_base: Schema.Class<PackageManagerError, Schema.TaggedStruct<"PackageManagerError", {
+  readonly operation: Schema.Literals<readonly ["detect", "install", "recover", "state"]>;
+  readonly message: Schema.String;
+  readonly exitCode: Schema.optionalKey<Schema.Int>;
+}>, Cause.YieldableError & {
+  readonly brand: unique symbol;
+}>;
+export declare class PackageManagerError extends PackageManagerError_base {}
+declare const RecoveryRequiredError_base: Schema.Class<RecoveryRequiredError, Schema.TaggedStruct<"RecoveryRequiredError", {
+  readonly directory: Schema.String;
+  readonly snapshotDirectory: Schema.String;
+  readonly operation: Schema.Literals<readonly ["install", "recover", "rollback"]>;
+  readonly processId: Schema.optionalKey<Schema.Int>;
+  readonly message: Schema.String;
+  readonly terminationCause: Schema.optionalKey<Schema.Cause<Schema.Unknown, Schema.Unknown>>;
+  readonly recoveryCause: Schema.Cause<Schema.Unknown, Schema.Unknown>;
+}>, Cause.YieldableError & {
+  readonly brand: unique symbol;
+}>;
+export declare class RecoveryRequiredError extends RecoveryRequiredError_base {}
+export type Error = PackageManagerError | UnsupportedFileTypeError | RecoveryRequiredError | PlatformError.PlatformError | Schema.SchemaError;
+export interface Options {
+  /** Project directory, containing package.json. Use the workspace root for workspace installs. */
+  readonly directory: string;
+  /** Explicit selection takes precedence over detection. */
+  readonly agent?: Agent;
+  /** Optional npm_config_user_agent supplied by the caller; used only as a fallback. */
+  readonly userAgent?: string;
+}
+/** packageManager, then lockfile, then caller user-agent, then npm. Conflicting lockfiles fail. */
+export declare const detectAgent: (options: Options) => Effect.Effect<"npm" | "pnpm" | "yarn-berry" | "yarn-classic", PackageManagerError | PlatformError.PlatformError | Schema.SchemaError, FileSystem.FileSystem | Path.Path>;
+export interface PackageState {
+  readonly spec: string;
+  /** Missing optional or not-yet-installed dependencies have no version/path. */
+  readonly version: string | undefined;
+  readonly path: string | undefined;
+}
+/** Direct dependencies only, keyed by their manifest names (including aliases). */
+export type State = HashMap.HashMap<string, PackageState>;
+export interface PackageChange {
+  readonly name: string;
+  readonly before: PackageState | undefined;
+  readonly after: PackageState | undefined;
+}
+export interface StateDiff {
+  readonly added: ReadonlyArray<PackageChange>;
+  readonly removed: ReadonlyArray<PackageChange>;
+  readonly updated: ReadonlyArray<PackageChange>;
+}
+export declare const diffState: (before: State, after: State) => StateDiff;
+export interface InstallResult extends StateDiff {
+  readonly agent: Agent;
+  /** The install committed; retry only snapshot deletion, not installation. */
+  readonly snapshotCleanupFailure: Option.Option<SnapshotCleanupFailure>;
+}
+export interface PackageManager {
+  readonly directory: string;
+  readonly agent: Agent;
+  readonly readState: Effect.Effect<State, Error>;
+  /** Present when manual recovery is required; the manager cannot be reused. */
+  readonly recoveryRequired: Effect.Effect<Option.Option<RecoveryRequiredError>>;
+  /** Serialized per manager. Empty changes installs the current manifest, including first installs. */
+  readonly install: (changes: Changes) => Effect.Effect<InstallResult, Error>;
+}
+/**
+ * Own one manager per project. The caller must give this manager and its child
+ * processes exclusive write access to the project for each install, including
+ * recovery. Do not edit project files or run another installer concurrently.
+ * Calls are serialized only within this manager; no cross-process lock is taken.
+ * Managed paths must be regular files or absent. make and install reject symbolic
+ * links and other file types with UnsupportedFileTypeError before any write.
+ *
+ * Accepted file writes finish before cancellation can start rollback or release
+ * the lock. File writes and the original process group participate in the transaction.
+ * Scripts must not create escaped writers in independent groups or daemons.
+ * Failed or interrupted installs before commit restore backed-up package files byte-for-byte
+ * with recorded permissions and ownership, and remove tracked files that did not
+ * exist before installation. Writes made
+ * during installation are overwritten by rollback, never merged. When a lockfile
+ * existed, recovery also attempts to repair node_modules. Recovery failures are
+ * combined with the original cause. If process termination cannot be confirmed,
+ * no further restoration or recovery runs. Any failed rollback step also requires
+ * manual recovery, even if all writers stopped. Only successful installation or
+ * complete rollback permits snapshot deletion and reuse. RecoveryRequiredError
+ * and recoveryRequired expose the retained snapshot directory and complete cause;
+ * this manager rejects
+ * all later installs. Complete manual recovery before making a new manager.
+ * Committed installs report snapshot deletion failures in snapshotCleanupFailure
+ * rather than failing or rolling back. No crash recovery is promised.
+ */
+export declare const make: (options: Options) => Effect.Effect<PackageManager, Error, FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner>;
+export { Changes, PackageManagerDeclaration, PackageName, type SnapshotCleanupFailure, UnsupportedFileTypeError };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;qBA+Ca,OAAK,OAAA;YAMN,eAAe,MAAM;;;;;;WAGd;;qBAFN,4BAA4B;;;;;;;;;;WAUtB;;qBAFN,8BAA8B;YAoC/B,QACT,sBACA,2BACA,wBACA,cAAc,gBACd,OAAO;iBACO;;WAEP;;WAEA,QAAQ;;WAER;;;qBAqDG,cAAW,SAAA,YAAA,OAAA,uDAAA,sBAAA,cAAA,gBAAA,OAAA,aAAA,WAAA,aAAA,KAAA;iBAkDP;WACP;;WAEA;WACA;;;YAGE,QAAQ,QAAQ,gBAAgB;iBAC3B;WACP;WACA,QAAQ;WACR,OAAO;;iBAEA;WACP,OAAO,cAAc;WACrB,SAAS,cAAc;WACvB,SAAS,cAAc;;qBAEpB,YAAS,QAAY,OAAK,OAAS,UAAQ;iBA0BvC,sBAAsB;WAC7B,OAAO;;WAEP,wBAAwB,OAAO,OAAO;;iBAE/B;WACP;WACA,OAAO;WACP,WAAW,OAAO,OAAO,OAAO;;WAEhC,kBAAkB,OAAO,OAAO,OAAO,OAAO;;WAE9C,UAAU,SAAS,YAAY,OAAO,OAAO,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA6BzD,OAAI,SACP,YACP,OAAO,OACT,gBACA,OACA,WAAW,aAAa,KAAK,OAAO,oBAAoB"}

package/dist/index.js

@@ -0,0 +1,324 @@
+import { PackageManagerDeclaration, PackageManagerName } from "./PackageManagerDeclaration.js";
+import { terminateProcess } from "./process.js";
+import { UnsupportedFileTypeError, inspectManagedFiles, withSnapshot, writeSnapshot } from "./snapshot.js";
+import { Changes, PackageName, applyChanges, decodeManifest, encodeManifest, fields } from "./manifest.js";
+import { Array, Data, Effect, Exit, FileSystem, HashMap, Option, Path, PlatformError, Record, Ref, Schema, Semaphore, String } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
+// src/index.ts
+/** Non-interactive package installation. Provide platform services at the application boundary. */
+const Agent = Schema.Literals([
+	"npm",
+	"pnpm",
+	"yarn-classic",
+	"yarn-berry"
+]);
+var PackageManagerError = class extends Schema.TaggedError()("PackageManagerError", {
+	operation: Schema.Literals([
+		"detect",
+		"install",
+		"recover",
+		"state"
+	]),
+	message: Schema.String,
+	exitCode: Schema.optionalKey(Schema.Int)
+}) {};
+var RecoveryRequiredError = class extends Schema.TaggedError()("RecoveryRequiredError", {
+	directory: Schema.String,
+	snapshotDirectory: Schema.String,
+	operation: Schema.Literals([
+		"install",
+		"recover",
+		"rollback"
+	]),
+	processId: Schema.optionalKey(Schema.Int),
+	message: Schema.String,
+	terminationCause: Schema.optionalKey(Schema.Cause(Schema.Unknown, Schema.Unknown)),
+	recoveryCause: Schema.Cause(Schema.Unknown, Schema.Unknown)
+}) {};
+const WriterState = Data.taggedEnum();
+const ManagerState = Data.taggedEnum();
+const lockfiles = [
+	"package-lock.json",
+	"npm-shrinkwrap.json",
+	"pnpm-lock.yaml",
+	"yarn.lock"
+];
+const backupFiles = [
+	"package.json",
+	...lockfiles,
+	".npmrc",
+	"pnpm-workspace.yaml",
+	".yarnrc",
+	".yarnrc.yml",
+	".yarn/install-state.gz",
+	".pnp.cjs",
+	".pnp.loader.mjs"
+];
+const executable = (agent) => String.startsWith("yarn")(agent) ? "yarn" : agent;
+const readSource = Effect.fnUntraced(function* (fs, file) {
+	const bytes = yield* fs.readFile(file);
+	return yield* Effect.try({
+		try: () => new TextDecoder("utf-8", {
+			ignoreBOM: true,
+			fatal: true
+		}).decode(bytes),
+		catch: (cause) => PlatformError.badArgument({
+			module: "FileSystem",
+			method: "readManifest",
+			description: "The manifest must contain valid UTF-8",
+			cause
+		})
+	});
+});
+const Executable = PackageManagerName;
+const Digits = Schema.String.check(Schema.isPattern(/^\d+$/));
+const decodePackageManager = Schema.decodeUnknownOption(PackageManagerDeclaration);
+/** `name/version ...`, as package managers set `npm_config_user_agent`. */
+const decodeUserAgent = Schema.decodeUnknownOption(Schema.TemplateLiteralParser([
+	Executable,
+	"/",
+	Digits,
+	Schema.String
+]));
+const agentOf = (name, major) => name === "yarn" ? major === "1" ? "yarn-classic" : "yarn-berry" : name;
+/** packageManager, then lockfile, then caller user-agent, then npm. Conflicting lockfiles fail. */
+const detectAgent = Effect.fnUntraced(function* (options) {
+	if (options.agent !== void 0) return yield* Schema.decodeEffect(Agent)(options.agent);
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const manifest = yield* readSource(fs, path.join(options.directory, "package.json")).pipe(Effect.flatMap(decodeManifest));
+	if (manifest.packageManager !== void 0) return yield* Option.match(decodePackageManager(manifest.packageManager), {
+		onNone: () => PackageManagerError.make({
+			operation: "detect",
+			message: `Unsupported packageManager: ${manifest.packageManager}`
+		}),
+		onSome: ([name, , version]) => Effect.succeed(agentOf(name, `${version.major}`))
+	});
+	const found = yield* Effect.filter(lockfiles, (file) => fs.exists(path.join(options.directory, file)));
+	const kinds = Array.dedupe(Array.map(found, (file) => file === "pnpm-lock.yaml" ? "pnpm" : file === "yarn.lock" ? "yarn" : "npm"));
+	if (kinds.length > 1) return yield* PackageManagerError.make({
+		operation: "detect",
+		message: "Conflicting lockfiles; select an agent explicitly"
+	});
+	if (kinds[0] === "yarn") {
+		const lock = yield* fs.readFileString(path.join(options.directory, "yarn.lock"));
+		return /^__metadata:/m.test(lock) ? "yarn-berry" : "yarn-classic";
+	}
+	if (kinds[0] !== void 0) return kinds[0];
+	return Option.match(decodeUserAgent(options.userAgent ?? ""), {
+		onNone: () => "npm",
+		onSome: ([name, , major]) => agentOf(name, major)
+	});
+});
+const diffState = (before, after) => {
+	const changes = Array.map(Array.sort(Array.dedupe([...HashMap.keys(before), ...HashMap.keys(after)]), String.Order), (name) => ({
+		name,
+		before: Option.getOrUndefined(HashMap.get(before, name)),
+		after: Option.getOrUndefined(HashMap.get(after, name))
+	}));
+	return {
+		added: Array.filter(changes, (change) => change.before === void 0),
+		removed: Array.filter(changes, (change) => change.after === void 0),
+		updated: Array.filter(changes, ({ before, after }) => before !== void 0 && after !== void 0 && (before.spec !== after.spec || before.version !== after.version || before.path !== after.path))
+	};
+};
+/**
+* Own one manager per project. The caller must give this manager and its child
+* processes exclusive write access to the project for each install, including
+* recovery. Do not edit project files or run another installer concurrently.
+* Calls are serialized only within this manager; no cross-process lock is taken.
+* Managed paths must be regular files or absent. make and install reject symbolic
+* links and other file types with UnsupportedFileTypeError before any write.
+*
+* Accepted file writes finish before cancellation can start rollback or release
+* the lock. File writes and the original process group participate in the transaction.
+* Scripts must not create escaped writers in independent groups or daemons.
+* Failed or interrupted installs before commit restore backed-up package files byte-for-byte
+* with recorded permissions and ownership, and remove tracked files that did not
+* exist before installation. Writes made
+* during installation are overwritten by rollback, never merged. When a lockfile
+* existed, recovery also attempts to repair node_modules. Recovery failures are
+* combined with the original cause. If process termination cannot be confirmed,
+* no further restoration or recovery runs. Any failed rollback step also requires
+* manual recovery, even if all writers stopped. Only successful installation or
+* complete rollback permits snapshot deletion and reuse. RecoveryRequiredError
+* and recoveryRequired expose the retained snapshot directory and complete cause;
+* this manager rejects
+* all later installs. Complete manual recovery before making a new manager.
+* Committed installs report snapshot deletion failures in snapshotCleanupFailure
+* rather than failing or rolling back. No crash recovery is promised.
+*/
+const make = (options) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+	const directory = path.resolve(options.directory);
+	yield* inspectManagedFiles(fs, path, directory, backupFiles);
+	const agent = yield* detectAgent({
+		...options,
+		directory
+	});
+	const lock = yield* Semaphore.make(1);
+	const transaction = yield* Ref.make(ManagerState.Ready());
+	const manifestFile = path.join(directory, "package.json");
+	const readManifest = readSource(fs, manifestFile).pipe(Effect.flatMap(decodeManifest));
+	const installed = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Struct({ version: Schema.optionalKey(Schema.String) })));
+	const stateOf = Effect.fnUntraced(function* (manifest) {
+		if (yield* fs.exists(path.join(directory, ".pnp.cjs"))) return yield* PackageManagerError.make({
+			operation: "state",
+			message: "Plug'n'Play is not supported; configure Yarn with nodeLinker: node-modules"
+		});
+		const deps = Array.reduce(fields, {}, (all, field) => ({
+			...all,
+			...manifest[field]
+		}));
+		const entries = yield* Effect.forEach(Record.toEntries(deps), ([name, spec]) => Effect.gen(function* () {
+			const file = path.join(directory, "node_modules", name, "package.json");
+			if (!(yield* fs.exists(file))) return [name, {
+				spec,
+				version: void 0,
+				path: void 0
+			}];
+			return [name, {
+				spec,
+				version: (yield* fs.readFileString(file).pipe(Effect.flatMap(installed))).version,
+				path: yield* fs.realPath(path.dirname(file))
+			}];
+		}));
+		return HashMap.fromIterable(entries);
+	});
+	const readState = Effect.flatMap(readManifest, stateOf);
+	const termination = { forceKillAfter: "5 seconds" };
+	const run = Effect.fnUntraced(function* (operation) {
+		const recovery = operation === "recover";
+		const args = agent === "npm" ? [
+			"install",
+			"--no-audit",
+			"--no-fund",
+			...recovery ? ["--prefer-offline"] : []
+		] : agent === "pnpm" ? [
+			"install",
+			recovery ? "--frozen-lockfile" : "--no-frozen-lockfile",
+			"--config.confirmModulesPurge=false"
+		] : agent === "yarn-classic" ? [
+			"install",
+			"--non-interactive",
+			...recovery ? ["--frozen-lockfile", "--prefer-offline"] : []
+		] : ["install", ...recovery ? ["--immutable"] : []];
+		return yield* Effect.acquireUseRelease(spawner.spawn(ChildProcess.make(executable(agent), args, {
+			cwd: directory,
+			extendEnv: true,
+			stdin: "ignore",
+			stdout: "inherit",
+			stderr: "inherit",
+			detached: true,
+			...termination,
+			env: {
+				CI: "true",
+				...agent === "yarn-berry" ? {
+					YARN_ENABLE_IMMUTABLE_INSTALLS: recovery ? "true" : "false",
+					YARN_NODE_LINKER: "node-modules"
+				} : {}
+			}
+		})).pipe(Effect.tap(() => Ref.set(transaction, ManagerState.Active({ writer: WriterState.Running() })))), (process) => Effect.gen(function* () {
+			const code = yield* process.exitCode.pipe(Effect.timeoutOrElse({
+				duration: "10 minutes",
+				orElse: () => PackageManagerError.make({
+					operation,
+					message: `${executable(agent)} ${operation} timed out`
+				})
+			}));
+			if (code !== 0) return yield* PackageManagerError.make({
+				operation,
+				exitCode: code,
+				message: `${executable(agent)} ${operation} exited with code ${code}`
+			});
+		}), (process) => Effect.gen(function* () {
+			const result = yield* terminateProcess(process, termination);
+			yield* Ref.set(transaction, ManagerState.Active({ writer: result._tag === "OriginalGroupStopped" ? WriterState.ManagedWritersIdle() : WriterState.Unconfirmed({
+				operation,
+				processId: process.pid,
+				cause: result.cause
+			}) }));
+			if (result._tag === "Unconfirmed") return yield* Effect.failCause(result.cause);
+		}));
+	}, Effect.scoped);
+	const withFileWriter = (effect) => Effect.acquireUseRelease(Ref.set(transaction, ManagerState.Active({ writer: WriterState.FileWrite() })), () => effect, () => Ref.set(transaction, ManagerState.Active({ writer: WriterState.ManagedWritersIdle() }))).pipe(Effect.uninterruptible);
+	const install = (changes) => lock.withPermits(1)(Effect.gen(function* () {
+		const state = yield* Ref.get(transaction);
+		if (state._tag === "RecoveryRequired") return yield* state.error;
+		const validated = yield* Schema.decodeEffect(Changes)(changes);
+		const inspected = yield* inspectManagedFiles(fs, path, directory, backupFiles);
+		const backups = yield* Effect.forEach(inspected, ({ name, file, metadata }) => Effect.gen(function* () {
+			return {
+				name,
+				file,
+				contents: yield* Option.match(metadata, {
+					onNone: () => Effect.succeedNone,
+					onSome: (info) => fs.readFile(file).pipe(Effect.map((bytes) => Option.some({
+						...info,
+						bytes
+					})))
+				})
+			};
+		}));
+		const original = yield* readSource(fs, manifestFile);
+		const manifest = yield* decodeManifest(original);
+		const before = yield* stateOf(manifest);
+		const text = yield* encodeManifest(applyChanges(manifest, validated), original);
+		const agentLocks = agent === "npm" ? ["package-lock.json", "npm-shrinkwrap.json"] : agent === "pnpm" ? ["pnpm-lock.yaml"] : ["yarn.lock"];
+		const hasLock = Array.some(backups, ({ name, contents }) => Array.contains(agentLocks, name) && Option.isSome(contents));
+		const completed = yield* withSnapshot(fs, Ref.get(transaction).pipe(Effect.map((state) => state._tag === "Ready")), (snapshotDirectory) => Effect.gen(function* () {
+			const snapshot = yield* writeSnapshot(fs, path, snapshotDirectory, directory, agent, backups);
+			const restore = Effect.flatMap(Ref.get(transaction), (state) => state._tag === "Active" && state.writer._tag === "ManagedWritersIdle" ? withFileWriter(snapshot.restore(state.writer)) : Effect.void);
+			return yield* Effect.acquireUseRelease(Ref.set(transaction, ManagerState.Active({ writer: WriterState.ManagedWritersIdle() })), () => Effect.gen(function* () {
+				yield* withFileWriter(fs.writeFileString(manifestFile, text));
+				yield* run("install");
+				const after = yield* readState;
+				return {
+					agent,
+					...diffState(before, after)
+				};
+			}), (_, exit) => Effect.gen(function* () {
+				if (Exit.isFailure(exit)) {
+					const state = yield* Ref.get(transaction);
+					if (state._tag !== "Active" || state.writer._tag !== "ManagedWritersIdle") return;
+					yield* withFileWriter(snapshot.restore(state.writer));
+					if (hasLock) yield* run("recover").pipe(Effect.onExit(() => restore));
+				}
+				yield* Ref.set(transaction, ManagerState.Ready());
+			})).pipe(Effect.onExit((exit) => Effect.gen(function* () {
+				const state = yield* Ref.get(transaction);
+				if (Exit.isSuccess(exit) || state._tag !== "Active") return;
+				const writer = state.writer;
+				const error = RecoveryRequiredError.make({
+					directory,
+					snapshotDirectory,
+					operation: writer._tag === "Unconfirmed" ? writer.operation : "rollback",
+					...writer._tag === "Unconfirmed" ? {
+						processId: writer.processId,
+						terminationCause: writer.cause
+					} : {},
+					message: `Manual recovery is required. Stop all writers before restoring the snapshot at ${snapshotDirectory}`,
+					recoveryCause: exit.cause
+				});
+				yield* Ref.set(transaction, ManagerState.RecoveryRequired({ error }));
+				return yield* error;
+			})));
+		}));
+		return {
+			...completed.value,
+			snapshotCleanupFailure: completed.snapshotCleanupFailure
+		};
+	}));
+	return {
+		directory,
+		agent,
+		recoveryRequired: Ref.get(transaction).pipe(Effect.map((state) => state._tag === "RecoveryRequired" ? Option.some(state.error) : Option.none())),
+		readState: lock.withPermits(1)(readState),
+		install
+	};
+});
+export { Agent, Changes, PackageManagerDeclaration, PackageManagerError, PackageName, RecoveryRequiredError, UnsupportedFileTypeError, detectAgent, diffState, make };
+
+//# sourceMappingURL=index.js.map