@agentxm/extension-materialization 0.29.2 → 0.30.1

package/dist/src/testing.d.ts

@@ -1,71 +1,5 @@
-/**
- * In-memory materialization doubles for feature tests: a manager whose
- * surfaces are recorded rather than written, a retention policy that never
- * retains, and a structural serialization of a recipe's typed failure into the
- * plan-step vocabulary.
- *
- * These are deliberately behavioural, not mocks of a shape: a test asserts on
- * what the recorder observed, so a contract change that stops calling a
- * surface fails the test rather than passing silently.
- *
- * @experimental This API is unstable and may change without notice.
- * @packageDocumentation
- */
 import * as Layer from "effect/Layer";
-import * as Option from "effect/Option";
-import { StepFailure } from "@agentxm/workspace-operations";
-import type { ExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/extension-ref";
-import type { ExtensionTarget } from "@agentxm/workspace-state";
-import type { ExtensionManager, ManagerRequirements, MaterializationFacts } from "./manager-contract.js";
-import type { CallerStepFailure, UninstallRetentionPolicy } from "./extensions/operations.js";
 import { McpSecretStore } from "./mcps/secret-store.js";
-/** The manager surfaces one recipe touched, in the order it touched them. */
-export type RecordedManagerSurface = "materializeInstall" | "materializeUninstall" | "materializeDeactivate" | "upsertSettingsEntry" | "removeSettingsEntry" | "upsertLockfileEntry" | "removeLockfileEntry" | "listMaterializable" | "projectionPlans";
-/** What an in-memory manager observed while a recipe ran against it. */
-export interface RecordedManager<TRef extends ExtensionRef> {
-    readonly manager: ExtensionManager<TRef, MaterializationFacts, ManagerRequirements>;
-    /** Every surface the recipe touched, in call order. */
-    readonly surfaces: ReadonlyArray<RecordedManagerSurface>;
-    /** Targets currently declared in the recorder's settings. */
-    readonly configured: ReadonlySet<string>;
-    /** Targets currently observable as installed. */
-    readonly installed: ReadonlySet<string>;
-}
-/**
- * A materialization that observed nothing and acquired nothing. It satisfies
- * every per-type facts shape, so a feature test that never asserts on content
- * identity uses one value for any manager.
- */
-export declare const NO_MATERIALIZATION_FACTS: {
-    readonly observation: import("./manager-contract.js").MaterializationObservation;
-    readonly treeIntegrity: Option.Option<never>;
-    readonly sourceHash: Option.Option<never>;
-    readonly acquired: Option.Option<never>;
-    readonly removal: Option.Option<never>;
-};
-/**
- * A manager whose authoritative surfaces are in-memory sets. `materializable`
- * is what `listMaterializable` answers; anything installed through the
- * recorder becomes both configured and observable.
- */
-export declare const makeRecordedManager: <TRef extends ExtensionRef>(args: {
-    readonly type: TRef["type"];
-    readonly materializable: ReadonlyArray<TRef>;
-    /** Targets already installed and declared before the recipe runs. */
-    readonly installed?: ReadonlyArray<string>;
-}) => RecordedManager<TRef>;
-/** A retention policy that never retains a package for an installed Pack. */
-export declare const noUninstallRetention: UninstallRetentionPolicy;
-/** A retention policy that always retains, for the retained-by-pack settlement. */
-export declare const alwaysUninstallRetention: UninstallRetentionPolicy;
-/**
- * A structural serialization of a recipe's typed failure: the producing
- * family's own detail sentence under an `internal` category. Assertions bind
- * to this mapping, not to the application boundary's wording.
- */
-export declare const structuralStepFailure: <F>(failure: CallerStepFailure<F>) => StepFailure;
-/** A retention target's plan-step identity, for assertions on recorded steps. */
-export declare const recordedTargetName: (target: ExtensionTarget) => string;
 /** What an in-memory credential store recorded, and the layer that backs it. */
 export interface MemoryMcpSecretStore {
     readonly layer: Layer.Layer<McpSecretStore>;

package/dist/src/testing.js

@@ -1,96 +1,8 @@
-/**
- * In-memory materialization doubles for feature tests: a manager whose
- * surfaces are recorded rather than written, a retention policy that never
- * retains, and a structural serialization of a recipe's typed failure into the
- * plan-step vocabulary.
- *
- * These are deliberately behavioural, not mocks of a shape: a test asserts on
- * what the recorder observed, so a contract change that stops calling a
- * surface fails the test rather than passing silently.
- *
- * @experimental This API is unstable and may change without notice.
- * @packageDocumentation
- */
+/** Deterministic credential storage for materialization consumers. */
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
-import { StepFailure } from "@agentxm/workspace-operations";
-import { NO_MATERIALIZATION_OBSERVATION } from "./manager-contract.js";
-import { targetFromRef } from "./extensions/operations.js";
 import { McpSecretStore } from "./mcps/secret-store.js";
-/**
- * A materialization that observed nothing and acquired nothing. It satisfies
- * every per-type facts shape, so a feature test that never asserts on content
- * identity uses one value for any manager.
- */
-export const NO_MATERIALIZATION_FACTS = {
-    observation: NO_MATERIALIZATION_OBSERVATION,
-    treeIntegrity: Option.none(),
-    sourceHash: Option.none(),
-    acquired: Option.none(),
-    removal: Option.none(),
-};
-const NO_FACTS = NO_MATERIALIZATION_FACTS;
-/**
- * A manager whose authoritative surfaces are in-memory sets. `materializable`
- * is what `listMaterializable` answers; anything installed through the
- * recorder becomes both configured and observable.
- */
-export const makeRecordedManager = (args) => {
-    const surfaces = [];
-    const configured = new Set(args.installed ?? []);
-    const installed = new Set(args.installed ?? []);
-    const record = (surface, effect) => Effect.sync(() => surfaces.push(surface)).pipe(Effect.andThen(effect));
-    const manager = {
-        type: args.type,
-        isInstalled: ({ target }) => Effect.succeed(installed.has(target.name)),
-        materializeInstall: ({ ref }) => record("materializeInstall", Effect.sync(() => {
-            installed.add(targetFromRef(ref).name);
-            return NO_FACTS;
-        })),
-        materializeUninstall: ({ target }) => record("materializeUninstall", Effect.sync(() => {
-            installed.delete(target.name);
-            return NO_FACTS;
-        })),
-        materializeDeactivate: () => record("materializeDeactivate", Effect.succeed(NO_FACTS)),
-        getConfiguredSource: ({ target }) => Effect.succeed(configured.has(target.name) ? Option.some("workspace:") : Option.none()),
-        isConfigured: ({ target }) => Effect.succeed(configured.has(target.name)),
-        listMaterializable: () => record("listMaterializable", Effect.succeed(args.materializable)),
-        upsertSettingsEntry: ({ ref }) => record("upsertSettingsEntry", Effect.sync(() => {
-            configured.add(targetFromRef(ref).name);
-        })),
-        removeSettingsEntry: ({ target }) => record("removeSettingsEntry", Effect.sync(() => {
-            configured.delete(target.name);
-        })),
-        upsertLockfileEntry: () => record("upsertLockfileEntry", Effect.void),
-        removeLockfileEntry: () => record("removeLockfileEntry", Effect.void),
-    };
-    return { manager, surfaces, configured, installed };
-};
-/** A retention policy that never retains a package for an installed Pack. */
-export const noUninstallRetention = {
-    isRequiredByInstalledPack: () => Effect.succeed(false),
-};
-/** A retention policy that always retains, for the retained-by-pack settlement. */
-export const alwaysUninstallRetention = {
-    isRequiredByInstalledPack: () => Effect.succeed(true),
-};
-/**
- * A structural serialization of a recipe's typed failure: the producing
- * family's own detail sentence under an `internal` category. Assertions bind
- * to this mapping, not to the application boundary's wording.
- */
-export const structuralStepFailure = (failure) => {
-    const detail = typeof failure === "object" &&
-        failure !== null &&
-        "detail" in failure &&
-        typeof failure.detail === "string"
-        ? failure.detail
-        : String(failure);
-    return new StepFailure({ category: "internal", detail, cause: failure });
-};
-/** A retention target's plan-step identity, for assertions on recorded steps. */
-export const recordedTargetName = (target) => target.name;
 /**
  * An in-memory credential store for MCP install tests.
  *

package/package.json

@@ -4,16 +4,17 @@
     "url": "https://github.com/agentxm/axm/issues"
   },
   "dependencies": {
-    "@agentxm/agent-integration": "^0.29.2",
-    "@agentxm/extension-content": "^0.29.2",
-    "@agentxm/extension-model": "^0.29.2",
-    "@agentxm/extension-resolution": "^0.29.2",
-    "@agentxm/extension-sources": "^0.29.2",
-    "@agentxm/registry-client": "^0.29.2",
-    "@agentxm/workspace-operations": "^0.29.2",
-    "@agentxm/workspace-projection": "^0.29.2",
-    "@agentxm/workspace-state": "^0.29.2",
-    "@agentxm/workspace-transactions": "^0.29.2",
+    "@agentxm/agent-integration": "^0.30.1",
+    "@agentxm/cli-maintenance": "^0.30.1",
+    "@agentxm/extension-content": "^0.30.1",
+    "@agentxm/extension-model": "^0.30.1",
+    "@agentxm/extension-resolution": "^0.30.1",
+    "@agentxm/extension-sources": "^0.30.1",
+    "@agentxm/registry-client": "^0.30.1",
+    "@agentxm/workspace-operations": "^0.30.1",
+    "@agentxm/workspace-projection": "^0.30.1",
+    "@agentxm/workspace-state": "^0.30.1",
+    "@agentxm/workspace-transactions": "^0.30.1",
     "@napi-rs/keyring": "^1.3.0",
     "effect": "4.0.0-rc.115"
   },
@@ -24,27 +25,23 @@
     "@fast-check/vitest": "^0.5.0",
     "@typescript/native": "npm:typescript@^7.0.2",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "vitest": "^5.0.0",
-    "yaml": "^2.9.0"
+    "vitest": "^5.0.0"
   },
   "engines": {
     "node": ">=22.19.0"
   },
   "exports": {
     ".": {
-      "axm-source": "./src/index.ts",
-      "default": "./dist/src/index.js",
-      "types": "./dist/src/index.d.ts"
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
     },
     "./live": {
-      "axm-source": "./src/live.ts",
-      "default": "./dist/src/live.js",
-      "types": "./dist/src/live.d.ts"
+      "types": "./dist/src/live.d.ts",
+      "default": "./dist/src/live.js"
     },
     "./testing": {
-      "axm-source": "./src/testing.ts",
-      "default": "./dist/src/testing.js",
-      "types": "./dist/src/testing.d.ts"
+      "types": "./dist/src/testing.d.ts",
+      "default": "./dist/src/testing.js"
     }
   },
   "files": [
@@ -67,5 +64,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.29.2"
+  "version": "0.30.1"
 }

package/dist/src/desired-state/errors.d.ts

@@ -1,22 +0,0 @@
-/**
- * Failures deciding a retained re-materialization.
- *
- * @experimental This API is unstable and may change without notice.
- */
-import * as Schema from "effect/Schema";
-declare const RetainedContentUnusable_base: Schema.Class<RetainedContentUnusable, Schema.TaggedStruct<"RetainedContentUnusable", {
-    readonly extensionType: Schema.String;
-    readonly name: Schema.String;
-    /** The canonical observation status that made restoration impossible. */
-    readonly status: Schema.String;
-}>, import("effect/Cause").YieldableError>;
-/**
- * A retained transition asked to restore content the workspace accepted, and
- * that content is not usable. The transition refuses rather than re-resolving
- * the source, because re-acquiring is a different decision than restoring.
- */
-export declare class RetainedContentUnusable extends RetainedContentUnusable_base {
-    get detail(): string;
-}
-export {};
-//# sourceMappingURL=errors.d.ts.map

package/dist/src/desired-state/errors.js

@@ -1,22 +0,0 @@
-/**
- * Failures deciding a retained re-materialization.
- *
- * @experimental This API is unstable and may change without notice.
- */
-import * as Schema from "effect/Schema";
-/**
- * A retained transition asked to restore content the workspace accepted, and
- * that content is not usable. The transition refuses rather than re-resolving
- * the source, because re-acquiring is a different decision than restoring.
- */
-export class RetainedContentUnusable extends Schema.TaggedError()("RetainedContentUnusable", {
-    extensionType: Schema.String,
-    name: Schema.String,
-    /** The canonical observation status that made restoration impossible. */
-    status: Schema.String,
-}) {
-    get detail() {
-        return `Cannot rematerialize retained ${this.extensionType} ${this.name}: canonical content is ${this.status}`;
-    }
-}
-//# sourceMappingURL=errors.js.map

package/dist/src/desired-state/retained-materialization.d.ts

@@ -1,58 +0,0 @@
-/**
- * Re-materializing what desired state already accepted.
- *
- * A retained transition — re-enabling a Pack whose members were left on disk
- * — must never re-resolve a source. The accepted resolution and the canonical
- * content it names are the only inputs: if that content is not usable the
- * transition refuses rather than silently reaching for the network, because
- * "enable what you already have" and "acquire something new" are different
- * decisions with different risk.
- *
- * This lives in the materialization capability, not in a feature, because
- * both the workspace sync sweep and Pack activation re-materialize accepted
- * content, and a feature may not import a peer feature.
- *
- * @experimental This API is unstable and may change without notice.
- */
-import * as Effect from "effect/Effect";
-import * as FileSystem from "effect/FileSystem";
-import * as Path from "effect/Path";
-import type { ExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/extension-ref";
-import type { McpServerExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/mcp-server";
-import { CodingAgentRepository, type ProjectionParticipantRequirements } from "@agentxm/workspace-projection";
-import { WorkspaceMutations, type DesiredExtensionNode } from "@agentxm/workspace-state";
-import type { JobStepResult, PlannedJobStep, StepFailure } from "@agentxm/workspace-operations";
-import { RetainedContentUnusable } from "./errors.js";
-import type { ExtensionManagerFailure } from "../errors.js";
-import { ExtensionManagers } from "../manager-registry.js";
-import type { ManagerRequirements } from "../manager-contract.js";
-import { type RecipeRequirements, type StepFailureAdapter } from "../extensions/operations.js";
-import { SubagentManager } from "../managers.js";
-/** Services a retained materialize step needs when it runs. */
-export type RetainedMaterializeRequirements = CodingAgentRepository | ExtensionManagers | ManagerRequirements | RecipeRequirements | SubagentManager | WorkspaceMutations;
-/**
- * How an MCP server member is re-projected. MCP servers are realized into
- * each agent's native configuration rather than into a canonical tree, so the
- * caller hands in the install operation it already owns.
- */
-export type RunRetainedMcpServerInstall<R> = (args: {
-    readonly ref: McpServerExtensionRef;
-}) => Effect.Effect<JobStepResult, StepFailure, R>;
-export interface RetainedMaterializeSteps<R> {
-    /** Every accepted ref the selection covers, whether or not it needs work. */
-    readonly refs: ReadonlyArray<ExtensionRef>;
-    readonly steps: ReadonlyArray<PlannedJobStep<R | RetainedMaterializeRequirements>>;
-}
-/** Every failure deciding retained re-materialization can surface. */
-export type RetainedMaterializeFailure = RetainedContentUnusable | ExtensionManagerFailure;
-/**
- * Build the steps that bring the given desired nodes back to their accepted
- * materialization. Nodes whose projections are already current contribute no
- * step, so a retained transition that changes nothing plans nothing.
- */
-export declare const collectRetainedMaterializeSteps: <R = never>(args: {
-    readonly nodes: ReadonlyArray<DesiredExtensionNode>;
-    readonly runMcpServerInstall: RunRetainedMcpServerInstall<R>;
-    readonly adapter: StepFailureAdapter;
-}) => Effect.Effect<RetainedMaterializeSteps<R>, RetainedMaterializeFailure, CodingAgentRepository | ExtensionManagers | FileSystem.FileSystem | Path.Path | ProjectionParticipantRequirements | SubagentManager | WorkspaceMutations>;
-//# sourceMappingURL=retained-materialization.d.ts.map

package/dist/src/desired-state/retained-materialization.js

@@ -1,119 +0,0 @@
-/**
- * Re-materializing what desired state already accepted.
- *
- * A retained transition — re-enabling a Pack whose members were left on disk
- * — must never re-resolve a source. The accepted resolution and the canonical
- * content it names are the only inputs: if that content is not usable the
- * transition refuses rather than silently reaching for the network, because
- * "enable what you already have" and "acquire something new" are different
- * decisions with different risk.
- *
- * This lives in the materialization capability, not in a feature, because
- * both the workspace sync sweep and Pack activation re-materialize accepted
- * content, and a feature may not import a peer feature.
- *
- * @experimental This API is unstable and may change without notice.
- */
-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 { CodingAgentRepository, isObservedMaterializationCurrent, } from "@agentxm/workspace-projection";
-import { acceptedCanonicalObservation, acceptedResolutionRef, isSourcedDesiredExtension, usableAcceptedCanonical, WorkspaceMutations, } from "@agentxm/workspace-state";
-import { RetainedContentUnusable } from "./errors.js";
-import { ExtensionManagers } from "../manager-registry.js";
-import { buildMaterializeOperation, targetFromRef, toStepKey, } from "../extensions/operations.js";
-import { SubagentManager } from "../managers.js";
-/**
- * Build the steps that bring the given desired nodes back to their accepted
- * materialization. Nodes whose projections are already current contribute no
- * step, so a retained transition that changes nothing plans nothing.
- */
-export const collectRetainedMaterializeSteps = (args) => Effect.gen(function* () {
-    const ws = yield* WorkspaceMutations;
-    const fs = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const agentRepo = yield* CodingAgentRepository;
-    const managers = yield* ExtensionManagers;
-    const subagentManager = yield* SubagentManager;
-    const configuredAgentIds = yield* ws.getConfiguredAgents();
-    const selected = args.nodes
-        .filter(isSourcedDesiredExtension)
-        .filter((node) => node.enabled && node.type !== "pack");
-    const reconciled = yield* Effect.forEach(selected, (node) => Effect.gen(function* () {
-        const canonical = yield* acceptedCanonicalObservation({
-            workspace: ws,
-            type: node.type,
-            name: node.name,
-        });
-        const status = Option.isSome(canonical)
-            ? canonical.value.observation.status
-            : "missing-resolution";
-        const usable = status === "usable"
-            ? yield* usableAcceptedCanonical({
-                workspace: ws,
-                type: node.type,
-                name: node.name,
-            })
-            : Option.none();
-        const ref = Option.isSome(usable)
-            ? Option.some(usable.value.ref)
-            : yield* acceptedResolutionRef({
-                workspace: ws,
-                type: node.type,
-                name: node.name,
-            });
-        if (Option.isNone(ref)) {
-            return yield* new RetainedContentUnusable({
-                extensionType: node.type,
-                name: node.name,
-                status,
-            });
-        }
-        const current = yield* isObservedMaterializationCurrent({
-            workspace: ws,
-            node,
-            configuredAgentIds,
-            agents: agentRepo,
-            subagents: subagentManager,
-            resolvedRef: ref.value,
-            fs,
-            path,
-        });
-        return { node, ref: ref.value, materialize: status !== "usable" || !current };
-    }), { concurrency: "unbounded" });
-    const steps = reconciled
-        .filter(({ materialize }) => materialize)
-        .map(({ node, ref }) => {
-        if (ref.type === "mcp-server") {
-            const target = targetFromRef(ref);
-            return {
-                key: toStepKey(target),
-                label: `${node.type} ${node.name}`,
-                readiness: "ready",
-                run: args.runMcpServerInstall({ ref }),
-            };
-        }
-        const common = {
-            toStepFailure: args.adapter.toStepFailure,
-            label: `${node.type} ${node.name}`,
-            message: `Restored ${node.type} ${node.name}`,
-        };
-        switch (ref.type) {
-            case "skill":
-                return buildMaterializeOperation(managers.skill, { ...common, ref });
-            case "subagent":
-                return buildMaterializeOperation(managers.subagent, { ...common, ref });
-            case "rule":
-                return buildMaterializeOperation(managers.rule, { ...common, ref });
-            case "hook":
-                return buildMaterializeOperation(managers.hook, { ...common, ref });
-            case "knowledge":
-                return buildMaterializeOperation(managers.knowledge, { ...common, ref });
-            case "pack":
-                return buildMaterializeOperation(managers.pack, { ...common, ref });
-        }
-    });
-    return { refs: reconciled.map(({ ref }) => ref), steps };
-});
-//# sourceMappingURL=retained-materialization.js.map