@agentxm/workspace-state 0.28.4-bootstrap.0

package/dist/src/lockfile/lockfile.js

@@ -0,0 +1,235 @@
+/**
+ * Lockfile module for managing project-root `axm-lock.yaml` or the user-scope
+ * `axm-lock.yaml` (YAML format).
+ *
+ * Provides functions to read, write, and update accepted external resolutions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import { LOCKFILE_NAME } from "@agentxm/extension-model/unstable/workspace-files";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Semaphore from "effect/Semaphore";
+import YAML from "yaml";
+import { recordFootprint } from "../workspace/footprint-recorder.js";
+import { sweepStaleAtomicWriteTemps, writeFileAtomic } from "../utils/atomic-write.js";
+import { LockfileValidationError, LockfileWriteError } from "./errors.js";
+import { LOCKFILE_VERSION, LockfileSchema } from "./schema.js";
+// -----------------------------------------------------------------------------
+// Constants
+// -----------------------------------------------------------------------------
+/**
+ * Filename for the lockfile.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+// eslint-disable-next-line no-restricted-syntax -- Process-owned keys are bounded by lockfiles touched during this one CLI invocation.
+const lockSemaphores = new Map();
+// -----------------------------------------------------------------------------
+// Internal Helpers
+// -----------------------------------------------------------------------------
+const lockfilePathFor = (path, axmDir) => path.join(axmDir, LOCKFILE_NAME);
+const inProcessSemaphoreFor = (key) => {
+    const existing = lockSemaphores.get(key);
+    if (existing !== undefined)
+        return existing;
+    const created = Semaphore.makeUnsafe(1);
+    lockSemaphores.set(key, created);
+    return created;
+};
+const ensureLockfileParent = (lockfilePath) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const parent = path.dirname(lockfilePath);
+    yield* fs
+        .makeDirectory(parent, { recursive: true })
+        .pipe(Effect.mapError((cause) => new LockfileWriteError({ path: parent, step: "mkdir", cause })));
+});
+const encodeLockfileYaml = (lockfilePath, lockfile) => Effect.gen(function* () {
+    const encoded = yield* Effect.try({
+        try: () => Schema.encodeSync(LockfileSchema)(lockfile),
+        catch: (cause) => new LockfileWriteError({ path: lockfilePath, step: "encode", cause }),
+    });
+    return yield* Effect.try({
+        try: () => YAML.stringify(encoded),
+        catch: (cause) => new LockfileWriteError({ path: lockfilePath, step: "serialize", cause }),
+    });
+});
+const patchOptionalMap = (fresh, base, next) => {
+    if (base === undefined && next === undefined)
+        return fresh === undefined ? undefined : { ...fresh };
+    const patched = { ...(fresh ?? {}) };
+    for (const key of Object.keys(base ?? {})) {
+        if (!Object.hasOwn(next ?? {}, key)) {
+            delete patched[key];
+        }
+    }
+    for (const [key, value] of Object.entries(next ?? {})) {
+        patched[key] = value;
+    }
+    return Object.keys(patched).length === 0 ? undefined : patched;
+};
+const patchRequiredMap = (fresh, base, next) => {
+    const patched = { ...fresh };
+    for (const key of Object.keys(base)) {
+        if (!Object.hasOwn(next, key)) {
+            delete patched[key];
+        }
+    }
+    for (const [key, value] of Object.entries(next)) {
+        patched[key] = value;
+    }
+    return patched;
+};
+const applyLockfileSnapshotPatch = (fresh, base, next) => {
+    const subagents = patchOptionalMap(fresh.subagents, base.subagents, next.subagents);
+    const mcpServers = patchOptionalMap(fresh.mcpServers, base.mcpServers, next.mcpServers);
+    const rules = patchOptionalMap(fresh.rules, base.rules, next.rules);
+    const hooks = patchOptionalMap(fresh.hooks, base.hooks, next.hooks);
+    const knowledge = patchOptionalMap(fresh.knowledge, base.knowledge, next.knowledge);
+    const packs = patchOptionalMap(fresh.packs, base.packs, next.packs);
+    return {
+        lockfileVersion: LOCKFILE_VERSION,
+        skills: patchRequiredMap(fresh.skills, base.skills, next.skills),
+        ...(subagents !== undefined ? { subagents } : {}),
+        ...(mcpServers !== undefined ? { mcpServers } : {}),
+        ...(rules !== undefined ? { rules } : {}),
+        ...(hooks !== undefined ? { hooks } : {}),
+        ...(knowledge !== undefined ? { knowledge } : {}),
+        ...(packs !== undefined ? { packs } : {}),
+    };
+};
+const readLockfileIfPresent = (lockfilePath) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const exists = yield* fs
+        .exists(lockfilePath)
+        .pipe(Effect.mapError((cause) => new LockfileValidationError({ path: lockfilePath, step: "check", cause })));
+    if (!exists)
+        return undefined;
+    const raw = yield* fs
+        .readFileString(lockfilePath)
+        .pipe(Effect.mapError((cause) => new LockfileValidationError({ path: lockfilePath, step: "read", cause })));
+    const parsed = yield* Effect.try({
+        try: () => YAML.parse(raw),
+        catch: (cause) => new LockfileValidationError({ path: lockfilePath, step: "parse", cause }),
+    });
+    const decoded = yield* Schema.decodeUnknownEffect(LockfileSchema)(parsed, {
+        onExcessProperty: "error",
+    }).pipe(Effect.mapError((cause) => new LockfileValidationError({ path: lockfilePath, step: "decode", cause })));
+    return decoded;
+});
+const withLockfileLock = (lockfilePath, effect) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const key = path.resolve(lockfilePath);
+    const semaphore = inProcessSemaphoreFor(key);
+    // Cross-process exclusion belongs to the workspace transaction. This
+    // semaphore only serializes multiple updates in one runtime so the
+    // read/patch/write helper cannot race with itself.
+    return yield* semaphore.withPermits(1)(effect);
+});
+const writeLockfileUnlocked = (lockfilePath, lockfile) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const yamlContent = yield* encodeLockfileYaml(lockfilePath, lockfile);
+    const existed = yield* fs.exists(lockfilePath).pipe(Effect.orElseSucceed(() => true));
+    yield* sweepStaleAtomicWriteTemps(fs, lockfilePath);
+    const written = yield* writeFileAtomic(fs, {
+        targetPath: lockfilePath,
+        content: yamlContent,
+        skipIfUnchanged: "fail-on-read-error",
+        mapError: (failure) => new LockfileWriteError({
+            path: failure.step === "write-temp" ? failure.tempPath : lockfilePath,
+            step: failure.step,
+            cause: failure.cause,
+        }),
+    });
+    if (written === "written") {
+        yield* recordFootprint({ path: lockfilePath, change: existed ? "modified" : "created" });
+    }
+});
+// -----------------------------------------------------------------------------
+// Public Functions
+// -----------------------------------------------------------------------------
+/**
+ * Writes the lockfile to the selected scope's `axm-lock.yaml` in YAML format.
+ *
+ * Creates the containing directory if it does not exist. Writes are serialized by
+ * an in-process keyed semaphore plus a best-effort local advisory lock file.
+ * Temporary files are removed by scoped finalizer on interruption, and stale
+ * temp files from older crashed writers are swept before each write. When the
+ * encoded bytes already match, the existing lockfile is left untouched.
+ *
+ * `writeLockfile` remains a full replacement operation. Call
+ * `commitLockfileUpdates` when applying deltas that must reread the latest
+ * lockfile state under the advisory lock.
+ *
+ * @param axmDir - Directory containing the selected scope's lockfile
+ * @param lockfile - The lockfile object to write
+ * @returns Effect yielding void on success
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const writeLockfileAtPath = (lockfilePath, lockfile) => Effect.gen(function* () {
+    yield* ensureLockfileParent(lockfilePath);
+    yield* withLockfileLock(lockfilePath, Effect.gen(function* () {
+        yield* writeLockfileUnlocked(lockfilePath, lockfile);
+    }));
+});
+export const writeLockfile = (axmDir, lockfile) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    yield* writeLockfileAtPath(lockfilePathFor(path, axmDir), lockfile);
+});
+/**
+ * Applies lockfile updates in order without writing to disk.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const applyLockfileUpdates = (lockfile, updates) => updates.reduce((current, update) => update(current), lockfile);
+/**
+ * Applies a batch of lockfile updates and writes the result once.
+ *
+ * This is intended for sync flows that discover multiple render-hash changes
+ * while reconciling managed package targets.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const commitLockfileUpdates = (axmDir, lockfile, updates) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const lockfilePath = lockfilePathFor(path, axmDir);
+    yield* ensureLockfileParent(lockfilePath);
+    const updated = yield* withLockfileLock(lockfilePath, Effect.gen(function* () {
+        const current = yield* readLockfileIfPresent(lockfilePath);
+        const updated = applyLockfileUpdates(current ?? lockfile, updates);
+        yield* writeLockfileUnlocked(lockfilePath, updated);
+        return updated;
+    }));
+    return updated;
+});
+/**
+ * Commits a caller-computed lockfile snapshot as an entry-level patch.
+ *
+ * The caller supplies the base snapshot it read and the next snapshot it
+ * computed. The helper rereads the current on-disk lockfile under the advisory
+ * lock, applies only the base→next entry changes, then writes once. This keeps
+ * independent concurrent updates from dropping each other while preserving
+ * explicit entry deletions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const commitLockfileSnapshotUpdateAtPath = (lockfilePath, base, next) => Effect.gen(function* () {
+    yield* ensureLockfileParent(lockfilePath);
+    const updated = yield* withLockfileLock(lockfilePath, Effect.gen(function* () {
+        const current = yield* readLockfileIfPresent(lockfilePath);
+        const updated = applyLockfileSnapshotPatch(current ?? base, base, next);
+        yield* writeLockfileUnlocked(lockfilePath, updated);
+        return updated;
+    }));
+    return updated;
+});
+export const commitLockfileSnapshotUpdate = (axmDir, base, next) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    return yield* commitLockfileSnapshotUpdateAtPath(lockfilePathFor(path, axmDir), base, next);
+});
+//# sourceMappingURL=lockfile.js.map

package/dist/src/lockfile/resolved-version.d.ts

@@ -0,0 +1,4 @@
+import * as Effect from "effect/Effect";
+import { LockfileResolvedVersionInvalid } from "./errors.js";
+export declare const validateExactResolvedVersion: (field: string, value: string) => Effect.Effect<void, LockfileResolvedVersionInvalid, never>;
+//# sourceMappingURL=resolved-version.d.ts.map

package/dist/src/lockfile/resolved-version.js

@@ -0,0 +1,7 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { VersionSchema } from "@agentxm/extension-model/unstable/version-constraints";
+import { LockfileResolvedVersionInvalid } from "./errors.js";
+const decodeVersion = Schema.decodeUnknownEffect(VersionSchema);
+export const validateExactResolvedVersion = (field, value) => decodeVersion(value).pipe(Effect.asVoid, Effect.mapError((cause) => new LockfileResolvedVersionInvalid({ field, value, cause })));
+//# sourceMappingURL=resolved-version.js.map