@agentxm/workspace-sync 0.28.4-bootstrap.0

package/dist/src/rendered-file-cleanup.js

@@ -0,0 +1,381 @@
+/**
+ * Destructive sweep of AXM-managed rendered files across agent surfaces:
+ * stale skill and subagent projections, managed MCP server entries, and
+ * managed hook groups. Read-only discovery primitives live in
+ * `extension-workspace/managed-file-discovery.ts`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { WorkspaceSyncFailed } from "./errors.js";
+import { CodingAgentRepository, pruneManagedMcpServersForAgent, extensionNameFromFilename, hasAxmManagedMarker, safeReadDirectory, safeReadFileString, readAmbiguousHookCommands, stripManagedHooksFromJson, } from "@agentxm/extension-workspace";
+import { AGENTS as CAPABILITY_AGENTS } from "@agentxm/extension-model/unstable/agent-capabilities";
+import { PER_AGENT_EXTENSION_TYPES, } from "@agentxm/extension-model/unstable/extensions/common";
+import { ACQUIRED_EXTENSIONS_DIR } from "@agentxm/workspace-state";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { protectWorkspacePath } from "@agentxm/workspace-state";
+import { recordFootprint } from "@agentxm/workspace-state";
+const isWithin = (path, parent, child) => {
+    const relative = path.relative(path.resolve(parent), path.resolve(child));
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+};
+const removePath = (fs, filePath, dryRun) => dryRun
+    ? Effect.void
+    : protectWorkspacePath(filePath).pipe(Effect.andThen(fs.remove(filePath, { recursive: true })), Effect.andThen(recordFootprint({ path: filePath, change: "removed" })), Effect.mapError((error) => new WorkspaceSyncFailed({
+        category: "internal",
+        detail: `Failed to remove managed agent artifact: ${filePath}`,
+        cause: error,
+    })));
+const hasManagedSkillCopyMarker = (fs, path, artifactPath) => safeReadFileString(fs, path.join(artifactPath, "SKILL.md")).pipe(Effect.map(hasAxmManagedMarker));
+const cleanupSkillArtifactsInDir = (args) => Effect.gen(function* () {
+    const removedPaths = [];
+    const preservedPaths = [];
+    const entries = yield* safeReadDirectory(args.fs, args.skillsDir);
+    const configuredRoots = args.ownershipRoots ?? [
+        args.path.join(args.baseDir, ACQUIRED_EXTENSIONS_DIR),
+    ];
+    const ownershipRoots = yield* Effect.forEach(configuredRoots, (root) => args.fs.realPath(root).pipe(Effect.orElseSucceed(() => root)));
+    for (const entry of entries) {
+        if (args.expectedNames?.has(entry) === true)
+            continue;
+        const artifactPath = args.path.join(args.skillsDir, entry);
+        const linkTarget = yield* args.fs.readLink(artifactPath).pipe(Effect.option);
+        if (linkTarget._tag === "Some") {
+            const resolvedTarget = args.path.resolve(args.skillsDir, linkTarget.value);
+            const canonicalTarget = yield* args.fs.realPath(resolvedTarget).pipe(Effect.option);
+            const ownershipTarget = canonicalTarget._tag === "Some" ? canonicalTarget.value : resolvedTarget;
+            if (!ownershipRoots.some((root) => isWithin(args.path, root, ownershipTarget))) {
+                preservedPaths.push(artifactPath);
+                continue;
+            }
+            yield* removePath(args.fs, artifactPath, args.dryRun);
+            removedPaths.push(artifactPath);
+            continue;
+        }
+        const stat = yield* args.fs.stat(artifactPath).pipe(Effect.option);
+        if (stat._tag === "None")
+            continue;
+        if (stat.value.type !== "Directory") {
+            preservedPaths.push(artifactPath);
+            continue;
+        }
+        const managedCopy = yield* hasManagedSkillCopyMarker(args.fs, args.path, artifactPath);
+        if (!managedCopy) {
+            preservedPaths.push(artifactPath);
+            continue;
+        }
+        yield* removePath(args.fs, artifactPath, args.dryRun);
+        removedPaths.push(artifactPath);
+    }
+    return { removedPaths, preservedPaths };
+});
+/** Remove AXM-owned skill projections whose package is no longer desired. */
+export const cleanupStaleManagedSkillDirectories = (args) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const ws = yield* WorkspaceMutations;
+    const agentRepo = yield* CodingAgentRepository;
+    const configuredAgentIds = new Set(yield* ws.getConfiguredAgents());
+    const agents = yield* agentRepo.all;
+    const removedPaths = [];
+    const ownershipRoots = ws.layout.scope === "project"
+        ? [ws.layout.acquiredRoot, ws.layout.authoredRoot("skill")]
+        : [ws.layout.acquiredRoot];
+    for (const agent of agents) {
+        if (!configuredAgentIds.has(agent.id))
+            continue;
+        const resolved = yield* agent.resolveEffectiveSkillsDir({ workspaceRoot: ws.baseDir });
+        if (resolved._tag !== "supported")
+            continue;
+        const result = yield* cleanupSkillArtifactsInDir({
+            fs,
+            path,
+            baseDir: ws.baseDir,
+            skillsDir: resolved.dir,
+            dryRun: args.dryRun === true,
+            ownershipRoots,
+            expectedNames: args.expectedSkillNames,
+        });
+        removedPaths.push(...result.removedPaths);
+    }
+    return { removedPaths: [...new Set(removedPaths)] };
+});
+const cleanupSubagentArtifactsInDir = (args) => Effect.gen(function* () {
+    const removedPaths = [];
+    const preservedPaths = [];
+    const entries = yield* safeReadDirectory(args.fs, args.subagentsDir);
+    for (const entry of entries) {
+        const filePath = args.path.join(args.subagentsDir, entry);
+        const stat = yield* args.fs.stat(filePath).pipe(Effect.option);
+        if (stat._tag === "None" || stat.value.type !== "File")
+            continue;
+        const content = yield* safeReadFileString(args.fs, filePath);
+        if (!hasAxmManagedMarker(content)) {
+            preservedPaths.push(filePath);
+            continue;
+        }
+        yield* removePath(args.fs, filePath, args.dryRun);
+        removedPaths.push(filePath);
+    }
+    return { removedPaths, preservedPaths };
+});
+const NO_PATHS = { removedPaths: [], preservedPaths: [] };
+const cleanupAgentSkills = (context) => Effect.gen(function* () {
+    const skillsDir = yield* context.agent.resolveEffectiveSkillsDir({
+        workspaceRoot: context.workspaceRoot,
+    });
+    if (skillsDir._tag !== "supported")
+        return NO_PATHS;
+    return yield* cleanupSkillArtifactsInDir({
+        fs: context.fs,
+        path: context.path,
+        baseDir: context.workspaceRoot,
+        skillsDir: skillsDir.dir,
+        dryRun: context.dryRun,
+        ownershipRoots: context.skillOwnershipRoots,
+    });
+});
+const cleanupAgentSubagents = (context) => Effect.gen(function* () {
+    const subagentsDir = yield* context.agent.resolveEffectiveSubagentsDir({
+        workspaceRoot: context.workspaceRoot,
+        scope: context.scope,
+    });
+    if (subagentsDir._tag !== "supported")
+        return NO_PATHS;
+    return yield* cleanupSubagentArtifactsInDir({
+        fs: context.fs,
+        path: context.path,
+        subagentsDir: subagentsDir.dir,
+        dryRun: context.dryRun,
+    });
+});
+/**
+ * Drop every `x-axm`-tagged server from the agent's MCP config. An empty
+ * declared set means "nothing should remain", so only managed entries go and
+ * user-authored servers stay.
+ */
+const cleanupAgentMcpServers = (context) => Effect.gen(function* () {
+    const outcome = yield* pruneManagedMcpServersForAgent(context.agent.id, {
+        workspaceRoot: context.workspaceRoot,
+        declaredServerNames: new Set(),
+        scope: context.scope,
+        dryRun: context.dryRun,
+    });
+    if (outcome._tag !== "success")
+        return NO_PATHS;
+    return {
+        removedPaths: (outcome.targets ?? []).map((target) => target.path),
+        preservedPaths: [],
+    };
+});
+/**
+ * Strip AXM-rendered hook groups from the agent's settings files. Edits go
+ * through jsonc-parser so user-authored groups, comments, and formatting in
+ * these user-owned files survive.
+ */
+const cleanupAgentHooks = (context) => Effect.gen(function* () {
+    const capabilityAgent = CAPABILITY_AGENTS.find((candidate) => candidate.id === context.agent.id);
+    const writer = capabilityAgent?.capabilities.hook.axm.writer;
+    if (writer === undefined || writer === null)
+        return NO_PATHS;
+    const removedPaths = [];
+    const configFiles = writer.configFiles.filter((file) => file.scope === "project" && file.format === "json");
+    for (const file of configFiles) {
+        const configPath = context.path.resolve(context.workspaceRoot, file.path);
+        const exists = yield* context.fs
+            .exists(configPath)
+            .pipe(Effect.catch(() => Effect.succeed(false)));
+        if (!exists)
+            continue;
+        const raw = yield* safeReadFileString(context.fs, configPath);
+        const next = yield* stripManagedHooksFromJson(configPath, writer.settingsKey, raw);
+        if (next === raw)
+            continue;
+        if (!context.dryRun) {
+            yield* protectWorkspacePath(configPath);
+            yield* context.fs.writeFileString(configPath, next).pipe(Effect.mapError((error) => new WorkspaceSyncFailed({
+                category: "internal",
+                detail: `Failed to strip managed hooks from: ${configPath}`,
+                cause: error,
+            })));
+        }
+        removedPaths.push(configPath);
+    }
+    return { removedPaths, preservedPaths: [] };
+});
+/**
+ * Cleanup keyed on the placement axis: every extension type that renders into a
+ * directory the agent owns needs removal behavior here, and adding a per-agent
+ * type fails to compile until that behavior is decided.
+ *
+ * Workspace-placed types are deliberately absent rather than mapped to a no-op.
+ * Workspace-placed extensions live in shared workspace content and are not
+ * keyed to a single agent, so removing one agent must not delete them.
+ */
+const cleanupByExtensionType = {
+    skill: cleanupAgentSkills,
+    subagent: cleanupAgentSubagents,
+    "mcp-server": cleanupAgentMcpServers,
+    hook: cleanupAgentHooks,
+};
+/**
+ * Remove AXM-managed artifacts for agents that are no longer configured for a
+ * workspace: rendered skill and subagent files, plus the agent's
+ * managed MCP server entries and hook groups. Only content carrying an
+ * AXM-managed signal is removed; user-authored files and entries are left
+ * untouched.
+ */
+export const cleanupManagedArtifactsForRemovedAgents = (args) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const ws = yield* WorkspaceMutations;
+    const agentRepo = yield* CodingAgentRepository;
+    const agents = yield* agentRepo.all;
+    const removedPaths = [];
+    const preservedPaths = [];
+    for (const agent of agents) {
+        if (!args.removedAgentIds.has(agent.id))
+            continue;
+        const context = {
+            fs,
+            path,
+            agent,
+            workspaceRoot: ws.baseDir,
+            scope: ws.scope,
+            skillOwnershipRoots: ws.layout.scope === "project"
+                ? [ws.layout.acquiredRoot, ws.layout.authoredRoot("skill")]
+                : [ws.layout.acquiredRoot],
+            dryRun: args.dryRun === true,
+        };
+        for (const type of PER_AGENT_EXTENSION_TYPES) {
+            const result = yield* cleanupByExtensionType[type](context);
+            removedPaths.push(...result.removedPaths);
+            preservedPaths.push(...result.preservedPaths);
+        }
+    }
+    return {
+        removedPaths: [...new Set(removedPaths)],
+        preservedPaths: [...new Set(preservedPaths)],
+    };
+});
+/** Inspect ownership proofs without mutating any agent-native artifact. */
+export const inspectWorkspaceOwnership = () => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const ws = yield* WorkspaceMutations;
+    const agentRepo = yield* CodingAgentRepository;
+    const configured = new Set(yield* ws.getConfiguredAgents());
+    const agents = yield* agentRepo.all;
+    const issues = [];
+    for (const agent of agents) {
+        if (!configured.has(agent.id))
+            continue;
+        const skillsDir = yield* agent.resolveEffectiveSkillsDir({ workspaceRoot: ws.baseDir });
+        if (skillsDir._tag === "supported") {
+            const result = yield* cleanupSkillArtifactsInDir({
+                fs,
+                path,
+                baseDir: ws.baseDir,
+                skillsDir: skillsDir.dir,
+                dryRun: true,
+                ownershipRoots: ws.layout.scope === "project"
+                    ? [ws.layout.acquiredRoot, ws.layout.authoredRoot("skill")]
+                    : [ws.layout.acquiredRoot],
+            });
+            issues.push(...result.preservedPaths.map((artifactPath) => ({
+                kind: "managed-file-unowned",
+                path: artifactPath,
+                detail: "Agent skill artifact has no AXM symlink or structured file ownership proof.",
+            })));
+        }
+        const subagentsDir = yield* agent.resolveEffectiveSubagentsDir({
+            workspaceRoot: ws.baseDir,
+            scope: ws.scope,
+        });
+        if (subagentsDir._tag === "supported") {
+            const result = yield* cleanupSubagentArtifactsInDir({
+                fs,
+                path,
+                subagentsDir: subagentsDir.dir,
+                dryRun: true,
+            });
+            issues.push(...result.preservedPaths.map((artifactPath) => ({
+                kind: "managed-file-unowned",
+                path: artifactPath,
+                detail: "Agent subagent artifact has no structured file ownership proof.",
+            })));
+        }
+        const capabilityAgent = CAPABILITY_AGENTS.find((candidate) => candidate.id === agent.id);
+        const writer = capabilityAgent?.capabilities.hook.axm.writer;
+        if (writer === undefined || writer === null)
+            continue;
+        for (const file of writer.configFiles.filter((candidate) => candidate.scope === ws.scope && candidate.format === "json")) {
+            const configPath = path.resolve(ws.baseDir, file.path);
+            if (!(yield* fs.exists(configPath).pipe(Effect.catch(() => Effect.succeed(false)))))
+                continue;
+            const raw = yield* safeReadFileString(fs, configPath);
+            const commands = yield* readAmbiguousHookCommands(configPath, writer.settingsKey, raw);
+            issues.push(...commands.map((command) => ({
+                kind: "hook-ownership-ambiguous",
+                path: configPath,
+                detail: `Hook command targets an AXM canonical extension path without x-axm ownership metadata: ${command}`,
+            })));
+        }
+    }
+    return issues.filter((issue, index) => issues.findIndex((candidate) => candidate.kind === issue.kind &&
+        candidate.path === issue.path &&
+        candidate.detail === issue.detail) === index);
+});
+export const cleanupStaleManagedSubagentFiles = (args) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const ws = yield* WorkspaceMutations;
+    const agentRepo = yield* CodingAgentRepository;
+    const configuredAgentIds = new Set(yield* ws.getConfiguredAgents());
+    const agents = yield* agentRepo.all;
+    const removedPaths = [];
+    for (const agent of agents) {
+        const resolved = yield* agent.resolveEffectiveSubagentsDir({
+            workspaceRoot: ws.baseDir,
+            scope: ws.scope,
+        });
+        if (resolved._tag !== "supported")
+            continue;
+        const exists = yield* fs.exists(resolved.dir).pipe(Effect.catch(() => Effect.succeed(false)));
+        if (!exists)
+            continue;
+        const entries = yield* fs
+            .readDirectory(resolved.dir)
+            .pipe(Effect.catch(() => Effect.succeed([])));
+        for (const entry of entries) {
+            const filePath = path.join(resolved.dir, entry);
+            const stat = yield* fs.stat(filePath).pipe(Effect.option);
+            if (stat._tag === "None" || stat.value.type !== "File")
+                continue;
+            const content = yield* fs
+                .readFileString(filePath)
+                .pipe(Effect.catch(() => Effect.succeed("")));
+            if (!hasAxmManagedMarker(content))
+                continue;
+            const expected = configuredAgentIds.has(agent.id) &&
+                args.expectedSubagentNames.has(extensionNameFromFilename(entry));
+            if (expected)
+                continue;
+            if (args.dryRun !== true) {
+                yield* protectWorkspacePath(filePath);
+                yield* fs.remove(filePath).pipe(Effect.mapError((error) => new WorkspaceSyncFailed({
+                    category: "internal",
+                    detail: `Failed to remove stale managed subagent file: ${filePath}`,
+                    cause: error,
+                })));
+                yield* recordFootprint({ path: filePath, change: "removed" });
+            }
+            removedPaths.push(filePath);
+        }
+    }
+    return { removedPaths };
+});
+//# sourceMappingURL=rendered-file-cleanup.js.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@agentxm/workspace-sync",
+  "version": "0.28.4-bootstrap.0",
+  "description": "AXM workspace-sync feature: desired-state reconciliation planning, projection realization, and reconciliation outcomes for the axm CLI. Unstable and unsupported — use the axm.sh CLI.",
+  "type": "module",
+  "license": "FSL-1.1-MIT",
+  "homepage": "https://axm.sh",
+  "bugs": {
+    "url": "https://github.com/agentxm/axm/issues"
+  },
+  "author": "AgentXM <hello@agentxm.ai> (https://agentxm.ai)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentxm/axm.git",
+    "directory": "packages/workspace-sync"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/src/",
+    "!**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "nx": {
+    "includedScripts": []
+  },
+  "dependencies": {
+    "effect": "4.0.0-rc.112",
+    "semver": "^7.8.5",
+    "@agentxm/extension-model": "^0.28.4-bootstrap.0",
+    "@agentxm/extension-workspace": "^0.28.4-bootstrap.0",
+    "@agentxm/registry-protocol": "^0.28.4-bootstrap.0",
+    "@agentxm/workspace-state": "^0.28.4-bootstrap.0",
+    "@agentxm/workspace-operations": "^0.28.4-bootstrap.0"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.0.0-rc.112",
+    "@effect/vitest": "4.0.0-rc.112",
+    "@types/bun": "^1.3.14",
+    "@types/semver": "^7.5.8",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^4.1.10"
+  }
+}