@agentxm/workspace-state 0.28.4-bootstrap.0

package/dist/src/workspace/footprint-recorder.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Footprint recorder — observed durable changes.
+ *
+ * The layers that touch durable state record what they actually committed,
+ * removed, or restored here; the operation resolution's footprint is these
+ * observations, not planner-claimed artifact paths. Recording is a no-op when
+ * no recorder is provided, so the writers stay usable outside an operation
+ * boundary.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Ref from "effect/Ref";
+import * as ServiceMap from "effect/Context";
+export interface FootprintObservation {
+    /** Absolute path of the durable change. */
+    readonly path: string;
+    readonly change: "created" | "modified" | "removed" | "restored";
+}
+declare const FootprintRecorder_base: ServiceMap.ServiceClass<FootprintRecorder, "@agentxm/workspace-state/workspace/footprint-recorder/FootprintRecorder", {
+    readonly ref: Ref.Ref<ReadonlyArray<FootprintObservation>>;
+}>;
+export declare class FootprintRecorder extends FootprintRecorder_base {
+}
+/** Record one observed durable change. No-op without a recorder. */
+export declare const recordFootprint: (observation: FootprintObservation) => Effect.Effect<void>;
+export declare const readFootprint: Effect.Effect<ReadonlyArray<FootprintObservation>>;
+export declare const makeFootprintRecorder: Effect.Effect<ServiceMap.Service.Shape<typeof FootprintRecorder>>;
+export {};
+//# sourceMappingURL=footprint-recorder.d.ts.map

package/dist/src/workspace/footprint-recorder.js

@@ -0,0 +1,32 @@
+/**
+ * Footprint recorder — observed durable changes.
+ *
+ * The layers that touch durable state record what they actually committed,
+ * removed, or restored here; the operation resolution's footprint is these
+ * observations, not planner-claimed artifact paths. Recording is a no-op when
+ * no recorder is provided, so the writers stay usable outside an operation
+ * boundary.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import * as ServiceMap from "effect/Context";
+export class FootprintRecorder extends ServiceMap.Service()("@agentxm/workspace-state/workspace/footprint-recorder/FootprintRecorder") {
+}
+/** Record one observed durable change. No-op without a recorder. */
+export const recordFootprint = (observation) => Effect.gen(function* () {
+    const service = yield* Effect.serviceOption(FootprintRecorder);
+    if (Option.isNone(service))
+        return;
+    yield* Ref.update(service.value.ref, (entries) => [...entries, observation]);
+});
+export const readFootprint = Effect.gen(function* () {
+    const service = yield* Effect.serviceOption(FootprintRecorder);
+    if (Option.isNone(service))
+        return [];
+    return yield* Ref.get(service.value.ref);
+});
+export const makeFootprintRecorder = Ref.make([]).pipe(Effect.map((ref) => ({ ref })));
+//# sourceMappingURL=footprint-recorder.js.map

package/dist/src/workspace/layout.d.ts

@@ -0,0 +1,43 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { WorkspaceLayoutError } from "./errors.js";
+import type { ExtensionType } from "@agentxm/extension-model/unstable/extensions/common";
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import type { Settings } from "../settings/schema.js";
+import { type AbsolutePath } from "@agentxm/extension-model/unstable/path-types";
+export { LOCK_FILENAME } from "./constants.js";
+export declare const RUNTIME_DIRECTORY = ".axm";
+export interface ProjectWorkspaceLayout {
+    readonly scope: "project";
+    readonly workspaceRoot: AbsolutePath;
+    readonly projectRoot: AbsolutePath;
+    readonly settingsPath: AbsolutePath;
+    readonly lockPath: AbsolutePath;
+    readonly runtimeDir: AbsolutePath;
+    readonly acquiredRoot: AbsolutePath;
+    readonly owner?: Handle;
+    readonly authoredRoot: (type: ExtensionType) => AbsolutePath;
+}
+export interface UserWorkspaceLayout {
+    readonly scope: "user";
+    readonly userHome: AbsolutePath;
+    readonly axmHome: AbsolutePath;
+    readonly workspaceRoot: AbsolutePath;
+    readonly settingsPath: AbsolutePath;
+    readonly lockPath: AbsolutePath;
+    readonly runtimeDir: AbsolutePath;
+    readonly acquiredRoot: AbsolutePath;
+    readonly owner?: Handle;
+}
+export type WorkspaceLayout = ProjectWorkspaceLayout | UserWorkspaceLayout;
+export declare const resolveProjectWorkspaceStatePaths: (path: Path.Path, projectRoot: AbsolutePath) => {
+    settingsPath: string & import("effect/Brand").Brand<"AbsolutePath">;
+    lockPath: string & import("effect/Brand").Brand<"AbsolutePath">;
+    runtimeDir: string & import("effect/Brand").Brand<"AbsolutePath">;
+    acquiredRoot: string & import("effect/Brand").Brand<"AbsolutePath">;
+};
+export declare const configuredAuthoredDirectory: (settings: Settings, type: ExtensionType) => string;
+export declare const resolveProjectWorkspaceLayout: (projectRoot: AbsolutePath, settings: Settings) => Effect.Effect<ProjectWorkspaceLayout, WorkspaceLayoutError, FileSystem.FileSystem | Path.Path>;
+export declare const resolveUserWorkspaceLayout: (userHome: AbsolutePath, settings?: Settings) => Effect.Effect<UserWorkspaceLayout, never, Path.Path>;
+//# sourceMappingURL=layout.d.ts.map

package/dist/src/workspace/layout.js

@@ -0,0 +1,164 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { AGENTS } from "@agentxm/extension-model/unstable/agents/registry";
+import { WorkspaceLayoutError } from "./errors.js";
+import { ACQUIRED_EXTENSIONS_DIR, AXM_DIR_NAME, LOCK_FILENAME, USER_WORKSPACE_DIRECTORY, } from "./constants.js";
+import { makeAbsolutePath } from "@agentxm/extension-model/unstable/path-types";
+import { SETTINGS_FILENAME } from "@agentxm/extension-model/unstable/workspace-files";
+export { LOCK_FILENAME } from "./constants.js";
+export const RUNTIME_DIRECTORY = AXM_DIR_NAME;
+const DEFAULT_AUTHORED_DIRECTORIES = {
+    skill: "skills",
+    "mcp-server": "mcps",
+    subagent: "subagents",
+    rule: "rules",
+    hook: "hooks",
+    knowledge: "knowledge",
+    pack: "packs",
+};
+const EXTENSION_TYPES = [
+    "skill",
+    "mcp-server",
+    "subagent",
+    "rule",
+    "hook",
+    "knowledge",
+    "pack",
+];
+export const resolveProjectWorkspaceStatePaths = (path, projectRoot) => ({
+    settingsPath: makeAbsolutePath(path, path.join(projectRoot, SETTINGS_FILENAME)),
+    lockPath: makeAbsolutePath(path, path.join(projectRoot, LOCK_FILENAME)),
+    runtimeDir: makeAbsolutePath(path, path.join(projectRoot, RUNTIME_DIRECTORY)),
+    acquiredRoot: makeAbsolutePath(path, path.join(projectRoot, ACQUIRED_EXTENSIONS_DIR)),
+});
+export const configuredAuthoredDirectory = (settings, type) => {
+    switch (type) {
+        case "skill":
+            return settings.skillsConfig?.dir ?? DEFAULT_AUTHORED_DIRECTORIES.skill;
+        case "mcp-server":
+            return settings.mcpServersConfig?.dir ?? DEFAULT_AUTHORED_DIRECTORIES["mcp-server"];
+        case "subagent":
+            return settings.subagentsConfig?.dir ?? DEFAULT_AUTHORED_DIRECTORIES.subagent;
+        case "rule":
+            return settings.rulesConfig?.dir ?? DEFAULT_AUTHORED_DIRECTORIES.rule;
+        case "hook":
+            return settings.hooksConfig?.dir ?? DEFAULT_AUTHORED_DIRECTORIES.hook;
+        case "knowledge":
+            return settings.knowledgeConfig?.dir ?? DEFAULT_AUTHORED_DIRECTORIES.knowledge;
+        case "pack":
+            return settings.packsConfig?.dir ?? DEFAULT_AUTHORED_DIRECTORIES.pack;
+    }
+};
+const layoutError = (detail, cause) => new WorkspaceLayoutError({ detail, ...(cause === undefined ? {} : { cause }) });
+const overlaps = (path, left, right) => {
+    const relative = path.relative(left, right);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+};
+const validateLexicalDirectory = (path, projectRoot, type, configured, reservedRoots) => {
+    if (path.isAbsolute(configured) ||
+        configured === "." ||
+        path.normalize(configured) !== configured ||
+        configured.split(/[\\/]/u).some((segment) => segment === ".." || segment === ".")) {
+        return Effect.fail(layoutError(`Invalid ${type} authored directory "${configured}": expected a normalized workspace-relative path`));
+    }
+    const resolved = path.resolve(projectRoot, configured);
+    if (!overlaps(path, projectRoot, resolved)) {
+        return Effect.fail(layoutError(`Invalid ${type} authored directory "${configured}": path escapes the workspace`));
+    }
+    const collision = reservedRoots.find((reserved) => overlaps(path, reserved, resolved));
+    if (collision !== undefined) {
+        return Effect.fail(layoutError(`Invalid ${type} authored directory "${configured}": overlaps reserved path ${collision}`));
+    }
+    return Effect.succeed(makeAbsolutePath(path, resolved));
+};
+const validateExistingAuthoredRoot = (fs, path, projectRoot, type, root) => Effect.gen(function* () {
+    const exists = yield* fs
+        .exists(root)
+        .pipe(Effect.mapError((cause) => layoutError(`Failed to inspect ${type} authored root ${root}`, cause)));
+    if (!exists)
+        return;
+    const link = yield* fs.readLink(root).pipe(Effect.option);
+    if (Option.isSome(link)) {
+        return yield* layoutError(`Invalid ${type} authored root ${root}: authored roots cannot be symlinks`);
+    }
+    const info = yield* fs
+        .stat(root)
+        .pipe(Effect.mapError((cause) => layoutError(`Failed to inspect ${type} authored root ${root}`, cause)));
+    if (info.type !== "Directory") {
+        return yield* layoutError(`Invalid ${type} authored root ${root}: expected a directory`);
+    }
+    const realProjectRoot = yield* fs
+        .realPath(projectRoot)
+        .pipe(Effect.orElseSucceed(() => path.resolve(projectRoot)));
+    const realRoot = yield* fs
+        .realPath(root)
+        .pipe(Effect.mapError((cause) => layoutError(`Failed to resolve ${type} authored root ${root}`, cause)));
+    if (!overlaps(path, realProjectRoot, realRoot)) {
+        return yield* layoutError(`Invalid ${type} authored root ${root}: real path escapes the workspace`);
+    }
+    const children = yield* fs
+        .readDirectory(root)
+        .pipe(Effect.mapError((cause) => layoutError(`Failed to inspect ${type} authored root ${root}`, cause)));
+    for (const child of children) {
+        const childPath = path.join(root, child);
+        const childLink = yield* fs.readLink(childPath).pipe(Effect.option);
+        if (Option.isSome(childLink)) {
+            return yield* layoutError(`Invalid ${type} authored package ${childPath}: direct package directories cannot be symlinks`);
+        }
+    }
+});
+export const resolveProjectWorkspaceLayout = (projectRoot, settings) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const statePaths = resolveProjectWorkspaceStatePaths(path, projectRoot);
+    const { runtimeDir, acquiredRoot } = statePaths;
+    const agentRoots = Object.values(AGENTS).flatMap((agent) => agent.rootDir === undefined ? [] : [path.join(projectRoot, agent.rootDir)]);
+    const reservedRoots = [runtimeDir, acquiredRoot, ...agentRoots];
+    const roots = new Map();
+    for (const extensionType of EXTENSION_TYPES) {
+        const root = yield* validateLexicalDirectory(path, projectRoot, extensionType, configuredAuthoredDirectory(settings, extensionType), reservedRoots);
+        for (const [otherType, otherRoot] of roots) {
+            if (overlaps(path, otherRoot, root) || overlaps(path, root, otherRoot)) {
+                return yield* layoutError(`Invalid ${extensionType} authored directory ${root}: overlaps ${otherType} authored root ${otherRoot}`);
+            }
+        }
+        yield* validateExistingAuthoredRoot(fs, path, projectRoot, extensionType, root);
+        roots.set(extensionType, root);
+    }
+    const authoredRoot = (type) => {
+        const root = roots.get(type);
+        if (root !== undefined)
+            return root;
+        return makeAbsolutePath(path, path.join(projectRoot, DEFAULT_AUTHORED_DIRECTORIES[type]));
+    };
+    return {
+        scope: "project",
+        workspaceRoot: projectRoot,
+        projectRoot,
+        settingsPath: statePaths.settingsPath,
+        lockPath: statePaths.lockPath,
+        runtimeDir,
+        acquiredRoot,
+        ...(settings.owner === undefined ? {} : { owner: settings.owner }),
+        authoredRoot,
+    };
+});
+export const resolveUserWorkspaceLayout = (userHome, settings = {}) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const axmHome = makeAbsolutePath(path, path.join(userHome, AXM_DIR_NAME));
+    const workspaceRoot = makeAbsolutePath(path, path.join(axmHome, USER_WORKSPACE_DIRECTORY));
+    return {
+        scope: "user",
+        userHome,
+        axmHome,
+        workspaceRoot,
+        settingsPath: makeAbsolutePath(path, path.join(workspaceRoot, SETTINGS_FILENAME)),
+        lockPath: makeAbsolutePath(path, path.join(workspaceRoot, LOCK_FILENAME)),
+        runtimeDir: makeAbsolutePath(path, path.join(workspaceRoot, RUNTIME_DIRECTORY)),
+        acquiredRoot: makeAbsolutePath(path, path.join(workspaceRoot, ACQUIRED_EXTENSIONS_DIR)),
+        ...(settings.owner === undefined ? {} : { owner: settings.owner }),
+    };
+});
+//# sourceMappingURL=layout.js.map

package/dist/src/workspace/lock-entry-to-ref.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Reconstruct extension refs from lockfile entries.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import type * as Path from "effect/Path";
+import { LockEntryEndpointConflict, LockEntryNameInvalid, LockEntrySourceMissing, LockEntrySourceTypeConflict, LockEntryUrlInvalid } from "./errors.js";
+import type { SettingsReadError, WorkspaceRootEscape } from "./read-model/errors.js";
+import type { KnowledgeLockEntry, HookLockEntry, PackLockEntry, McpServerLockEntry, RuleLockEntry, SkillLockEntry, SubagentLockEntry } from "../lockfile/index.js";
+import type { SourceHostConfig } from "../settings/index.js";
+import type { PackRef } from "@agentxm/extension-model/unstable/extensions/refs/pack";
+import type { McpServerExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/mcp-server";
+import type { SkillExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/skill";
+import type { SubagentExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/subagent";
+import type { KnowledgeExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/knowledge";
+import type { RuleExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/rule";
+import type { HookExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/hook";
+import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
+/** Failure of the caller-supplied configured-source lookup. */
+export type LockEntrySourceLookupError = SettingsReadError | WorkspaceRootEscape;
+/** Every failure a lock-entry-to-ref translation can produce. */
+export type LockEntryToRefError = LockEntrySourceMissing | LockEntryUrlInvalid | LockEntryNameInvalid | LockEntryEndpointConflict | LockEntrySourceTypeConflict | LockEntrySourceLookupError;
+interface LockEntryToRefDeps {
+    readonly baseDir: string;
+    readonly path: Path.Path;
+    readonly scope: WorkspaceScope;
+    readonly getConfiguredSourceByName: (name: string) => Effect.Effect<Option.Option<SourceHostConfig>, LockEntrySourceLookupError>;
+}
+export declare const skillLockEntryToRef: (name: string, entry: SkillLockEntry, deps: LockEntryToRefDeps) => Effect.Effect<SkillExtensionRef, LockEntryToRefError>;
+export declare const mcpServerLockEntryToRef: (name: string, entry: McpServerLockEntry, deps: LockEntryToRefDeps) => Effect.Effect<McpServerExtensionRef, LockEntryToRefError>;
+export declare const subagentLockEntryToRef: (name: string, entry: SubagentLockEntry, deps: LockEntryToRefDeps) => Effect.Effect<SubagentExtensionRef, LockEntryToRefError>;
+export declare const ruleLockEntryToRef: (name: string, entry: RuleLockEntry, deps: LockEntryToRefDeps) => Effect.Effect<RuleExtensionRef, LockEntryToRefError>;
+export declare const hookLockEntryToRef: (name: string, entry: HookLockEntry, deps: LockEntryToRefDeps) => Effect.Effect<HookExtensionRef, LockEntryToRefError>;
+export declare const knowledgeLockEntryToRef: (name: string, entry: KnowledgeLockEntry, deps: LockEntryToRefDeps) => Effect.Effect<KnowledgeExtensionRef, LockEntryToRefError>;
+export declare const packLockEntryToRef: (name: string, entry: PackLockEntry, deps: LockEntryToRefDeps) => Effect.Effect<PackRef, LockEntryToRefError>;
+export {};
+//# sourceMappingURL=lock-entry-to-ref.d.ts.map