@lmzhen/dsh-evolution-io-fs 0.0.0 → 0.24.0

package/lib/index.js

@@ -0,0 +1,106 @@
+import { nodeEvolutionIo } from "@lmzhen/dsh-evolution-core";
+//#region lib/types/index.js
+/** Provider name in the `evolutionIo` registry. */
+const PROVIDER_NAME = "fs";
+/** The seam methods the platform FileSystem cannot serve yet (contract C2 fallback list). */
+const PLATFORM_IO_FALLBACKS = [
+	"remove",
+	"rename",
+	"copy"
+];
+/** The two platform error codes a guarded write reports when another writer won the race. */
+const VERSION_CONFLICT_CODES = new Set(["FS_STALE_VERSION", "FS_NOT_OBSERVED"]);
+/** @returns whether the error is the platform's optimistic-concurrency conflict. */
+function isVersionConflict(error) {
+	const code = error?.code;
+	return typeof code === "string" && VERSION_CONFLICT_CODES.has(code);
+}
+/** A missing file is `null` on this seam; a real read failure must stay an error. */
+async function readTextThrough(fs, path) {
+	const target = await fs.resolve(path);
+	try {
+		return await fs.readText(target);
+	} catch (error) {
+		if (await fs.stat(target).catch(() => void 0) === void 0) return null;
+		throw error;
+	}
+}
+/** Build the seam implementation on top of `ctx.fs`, falling back to the node backend for the gaps. */
+/**
+* @param ctx - the plugin context (needs the platform `fs` service).
+* @param options.attempts - how many times a conflicted RMW is re-run before the conflict surfaces.
+* @returns the seam implementation backed by the platform filesystem.
+*/
+function platformEvolutionIo(ctx, options = {}) {
+	const attempts = options.attempts ?? 3;
+	const fs = ctx.get("fs");
+	if (fs === void 0 || typeof fs.resolve !== "function" || typeof fs.writeText !== "function") throw new Error("evolution-io-fs: the platform fs service is not mounted — the platform provider cannot be built");
+	const fallback = nodeEvolutionIo();
+	return {
+		readText: (path) => readTextThrough(fs, path),
+		async writeText(path, content) {
+			await fs.writeText(await fs.resolve(path), content);
+		},
+		async exists(path) {
+			return await fs.stat(await fs.resolve(path)).catch(() => void 0) !== void 0;
+		},
+		async size(path) {
+			const info = await fs.stat(await fs.resolve(path)).catch(() => void 0);
+			if (info === void 0) return null;
+			return typeof info.size === "number" ? info.size : null;
+		},
+		async list(path) {
+			const target = await fs.resolve(path);
+			return (await fs.listDir(target).catch(() => [])).map((entry) => entry.name);
+		},
+		async isSymlink(path) {
+			const info = await fs.lstat(path).catch(() => void 0);
+			if (info === void 0) return null;
+			return info.symlink === true;
+		},
+		async transact(path, task) {
+			const target = await fs.resolve(path);
+			for (let attempt = 1;; attempt += 1) {
+				const info = await fs.stat(target).catch(() => void 0);
+				const current = info === void 0 ? null : await readTextThrough(fs, path);
+				const next = await task(current);
+				if (next === null) {
+					await fallback.remove(path);
+					return;
+				}
+				if (next === current) return;
+				const intent = info === void 0 ? { kind: "createIfAbsent" } : {
+					kind: "replaceIfVersion",
+					version: info.version
+				};
+				try {
+					await fs.writeText(target, next, intent);
+					return;
+				} catch (error) {
+					if (!isVersionConflict(error) || attempt >= attempts) throw error;
+				}
+			}
+		},
+		remove: (path) => fallback.remove(path),
+		rename: (path, destination) => fallback.rename(path, destination),
+		copy: (path, destination) => fallback.copy(path, destination)
+	};
+}
+function providerFor(ctx) {
+	return {
+		name: "fs",
+		...platformEvolutionIo(ctx)
+	};
+}
+const name = "evolution-io-fs";
+const inject = ["evolutionIo"];
+/**
+* S0: register the platform provider as an ALTERNATIVE. No default: true — the node backend stays
+* the default until S3 flips it, so mounting this row changes no behaviour by itself.
+*/
+function apply(ctx) {
+	const view = ctx;
+	ctx.effect(() => ctx.evolutionIo.registerProvider(providerFor(view)), "evolution-io-fs.provider");
+}
+//#endregion
+export { PLATFORM_IO_FALLBACKS, PROVIDER_NAME, apply, inject, name, platformEvolutionIo, providerFor };

package/lib/types/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Platform-`ctx.fs` IO provider — the seam's SECOND backend (G2 S0).
+ *
+ * Why this package exists: the family's durable IO used to be one hand-written node stack
+ * (core's `nodeEvolutionIo`) with its own lock protocol and its own atomic write. The platform
+ * already ships all of it (`ctx.fs` with per-target locking and `writeText(target, text, expected)`
+ * version CAS), and two families of implementation is exactly how invariants drift. This provider
+ * maps the family seam onto the platform one, so `evolution-io-node` becomes one of two choices
+ * instead of the only medium.
+ *
+ * S0 (this step) ADDS the provider and does NOT enable it: `apply()` registers it WITHOUT
+ * `default: true`, so `provider()` still resolves the node backend and no behaviour changes.
+ * `evolution-io-node` remains the default until S3 flips it.
+ *
+ * Gaps are declared, not hidden (contract C2): the platform `FileSystem` has no
+ * `mkdir/remove/rename/copy` (upstream request ①) and its `FsInfo` carries no wall-clock mtime
+ * (request ②). Those methods therefore FALL BACK to the node backend and are listed in
+ * {@link PLATFORM_IO_FALLBACKS}; when upstream lands them the list shrinks to empty, which is the
+ * measurable 'delete the temporary shape' condition.
+ *
+ * @module @lmzhen/dsh-evolution-io-fs
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import type { EvolutionIo } from '@lmzhen/dsh-evolution-io';
+/** Provider name in the `evolutionIo` registry. */
+export declare const PROVIDER_NAME = "fs";
+/** The seam methods the platform FileSystem cannot serve yet (contract C2 fallback list). */
+export declare const PLATFORM_IO_FALLBACKS: readonly ["remove", "rename", "copy"];
+/** Build the seam implementation on top of `ctx.fs`, falling back to the node backend for the gaps. */
+/**
+ * @param ctx - the plugin context (needs the platform `fs` service).
+ * @param options.attempts - how many times a conflicted RMW is re-run before the conflict surfaces.
+ * @returns the seam implementation backed by the platform filesystem.
+ */
+export declare function platformEvolutionIo(ctx: {
+    get(name: string): unknown;
+}, options?: {
+    attempts?: number;
+}): EvolutionIoLike;
+export declare function providerFor(ctx: {
+    get(name: string): unknown;
+}): EvolutionIo;
+export declare const name = "evolution-io-fs";
+export declare const inject: string[];
+/**
+ * S0: register the platform provider as an ALTERNATIVE. No default: true — the node backend stays
+ * the default until S3 flips it, so mounting this row changes no behaviour by itself.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,9 +1,35 @@
 {
   "name": "@lmzhen/dsh-evolution-io-fs",
-  "version": "0.0.0",
-  "description": "Placeholder that claims the name; the real package ships from the evolution release workflow (OIDC trusted publishing).",
-  "license": "MIT",
+  "description": "Platform ctx.fs IO provider (the seam's second backend) (community build)",
+  "version": "0.24.0",
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lmzhen/dsh-evolution.git",
+    "directory": "packages/evolution-io-fs"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@lmzhen/dsh-evolution-core": "^0.24.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@lmzhen/dsh-evolution-io": "^0.24.0"
   }
 }