@agentxm/extension-lifecycle 0.28.4-bootstrap.0

package/dist/src/registry-materialization.js

@@ -0,0 +1,67 @@
+/**
+ * Registry-backed canonical package materialization.
+ *
+ * The canonical-directory staging/swap machinery lives in
+ * `@agentxm/extension-workspace`; this module owns only the registry
+ * fetch/verify/extract path.
+ *
+ * @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 * as HttpClient from "effect/unstable/http/HttpClient";
+import { createRegistryClient, extractZip } from "@agentxm/registry-client";
+import { computeIntegrity } from "./internal/integrity.js";
+import { ArchiveIntegrityMismatch, recoverCanonicalDirectory, replaceCanonicalDirectoryWithInspection, } from "@agentxm/extension-workspace";
+import { CoupledDependencyFailure } from "@agentxm/extension-workspace";
+import { coupleLifecycleDependencyFailure } from "./errors.js";
+import { computeMaterializedTreeIntegrity, } from "@agentxm/workspace-state";
+const registryLocationForClient = (location) => location.protocol === "file:" ? location.pathname : location.href;
+/**
+ * Fetch, verify, and extract a registry package into `destinationPath`.
+ *
+ * Always writes. Whether new bytes are needed at all is
+ * `canReuseInstalledPackage`'s decision, which the caller makes against the
+ * canonical installed path before choosing a destination.
+ *
+ * Registry client and archive-extraction failures travel opaquely as coupled
+ * dependency failures; the application boundary restores and converts them.
+ */
+export const materializeRegistryPackageWithTreeIntegrity = (args) => Effect.gen(function* () {
+    yield* recoverCanonicalDirectory({
+        baseDir: args.baseDir,
+        canonicalPath: args.destinationPath,
+    });
+    const client = yield* createRegistryClient(registryLocationForClient(args.sourceLocation));
+    const { archive } = yield* client
+        .getExtensionPackage({
+        owner: args.owner,
+        type: args.type,
+        name: args.name,
+        version: Option.some(args.version),
+    })
+        .pipe(Effect.mapError(coupleLifecycleDependencyFailure));
+    if (Option.isSome(args.integrity)) {
+        const actualIntegrity = yield* computeIntegrity(archive);
+        if (actualIntegrity !== args.integrity.value) {
+            return yield* new ArchiveIntegrityMismatch({
+                subject: args.messages.integrityMismatchDetail,
+            });
+        }
+    }
+    const result = yield* replaceCanonicalDirectoryWithInspection({
+        baseDir: args.baseDir,
+        canonicalPath: args.destinationPath,
+        populate: (stagingPath) => extractZip(archive, stagingPath).pipe(Effect.mapError(coupleLifecycleDependencyFailure)),
+        ...(args.validate === undefined ? {} : { validate: args.validate }),
+        inspect: computeMaterializedTreeIntegrity,
+    });
+    return {
+        canonicalPath: result.canonicalPath,
+        treeIntegrity: result.inspection,
+    };
+});
+export const materializeRegistryPackage = (args) => materializeRegistryPackageWithTreeIntegrity(args).pipe(Effect.map(({ canonicalPath }) => canonicalPath));
+//# sourceMappingURL=registry-materialization.js.map

package/dist/src/resolution-progress.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Presentation port for the source-resolution phase of lifecycle workflows.
+ * The feature marks where progress feedback belongs; the application owns the
+ * mechanism and wording (the CLI renders a spinner around the phase).
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+import type * as Effect from "effect/Effect";
+export interface LifecycleResolutionProgressService {
+    /** Surround the source-resolution phase with the application's progress feedback. */
+    readonly withSourceResolution: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+}
+declare const LifecycleResolutionProgress_base: ServiceMap.ServiceClass<LifecycleResolutionProgress, "@agentxm/extension-lifecycle/resolution-progress/LifecycleResolutionProgress", LifecycleResolutionProgressService>;
+export declare class LifecycleResolutionProgress extends LifecycleResolutionProgress_base {
+}
+export {};
+//# sourceMappingURL=resolution-progress.d.ts.map

package/dist/src/resolution-progress.js

@@ -0,0 +1,11 @@
+/**
+ * Presentation port for the source-resolution phase of lifecycle workflows.
+ * The feature marks where progress feedback belongs; the application owns the
+ * mechanism and wording (the CLI renders a spinner around the phase).
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+export class LifecycleResolutionProgress extends ServiceMap.Service()("@agentxm/extension-lifecycle/resolution-progress/LifecycleResolutionProgress") {
+}
+//# sourceMappingURL=resolution-progress.js.map

package/dist/src/resolution-timeout.d.ts

@@ -0,0 +1,5 @@
+import * as Effect from "effect/Effect";
+import { ExtensionLifecycleFailed } from "./errors.js";
+export declare const CONFIGURED_ENTRY_RESOLUTION_TIMEOUT = "2 seconds";
+export declare const withConfiguredEntryResolutionTimeout: (_source: string) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, ExtensionLifecycleFailed | E, R>;
+//# sourceMappingURL=resolution-timeout.d.ts.map

package/dist/src/resolution-timeout.js

@@ -0,0 +1,11 @@
+import * as Effect from "effect/Effect";
+import { ExtensionLifecycleFailed } from "./errors.js";
+export const CONFIGURED_ENTRY_RESOLUTION_TIMEOUT = "2 seconds";
+export const withConfiguredEntryResolutionTimeout = (_source) => (effect) => effect.pipe(Effect.timeoutOrElse({
+    duration: CONFIGURED_ENTRY_RESOLUTION_TIMEOUT,
+    orElse: () => Effect.fail(new ExtensionLifecycleFailed({
+        category: "network",
+        detail: "Timed out while resolving a configured extension source",
+    })),
+}));
+//# sourceMappingURL=resolution-timeout.js.map

package/dist/src/rules/manager.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Rule manager service.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import { RuleManager } from "@agentxm/extension-workspace";
+import { SourceHostProviders, WorkspaceCatalog } from "@agentxm/extension-sources";
+import type { MaterializationObservation } from "@agentxm/extension-workspace";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { LifecycleFailureAdapter } from "../failure-adapter.js";
+export declare const ruleMaterializationObservation: (managedTarget: string, instructionItems: ReadonlyArray<{
+    readonly agentId: string;
+    readonly health: string;
+}>) => MaterializationObservation;
+export declare const RuleManagerLive: Layer.Layer<RuleManager, never, LifecycleFailureAdapter | SourceHostProviders | WorkspaceCatalog | WorkspaceMutations | FileSystem.FileSystem | HttpClient.HttpClient | Path.Path>;
+//# sourceMappingURL=manager.d.ts.map

package/dist/src/rules/manager.js

@@ -0,0 +1,475 @@
+/**
+ * Rule manager service.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import { RuleDefinitionInvalid, RuleInstallStateMissing, activeContributors, applyProjectionPlans, planAggregateProjection, reconcileManagedRegionFile, MARKER_KIND_POINT, MARKER_VERSION, parseMarker, serializeMarker, assertInstructionTargetsSafe, assertInstructionsGitignoreSafe, observeInstructionProjection, reconcileInstructionTargets, resolveInstructionsConfig, } from "@agentxm/extension-workspace";
+import { decodeExtensionNameSync, formatFqn } from "@agentxm/extension-model/unstable/extensions";
+import { canReuseInstalledPackage, enabledConfiguredEntries, materializeExternalPackageWithTreeIntegrity, } from "@agentxm/extension-workspace";
+import { materializeRegistryPackageWithTreeIntegrity } from "../registry-materialization.js";
+import { computeExtensionPathsForLayout } from "@agentxm/workspace-state";
+import { RULES_REGION_OWNER, RuleManager } from "@agentxm/extension-workspace";
+import { parseFrontmatterEffect } from "@agentxm/registry-protocol/unstable/content/frontmatter";
+import { computePackageContentHash } from "@agentxm/workspace-state";
+import { computeMaterializedTreeIntegrity } from "@agentxm/workspace-state";
+import {} from "@agentxm/extension-model/unstable/sources/source-hash";
+import { acceptedRegistryVersionForRef, validateExactResolvedVersion, } from "@agentxm/workspace-state";
+import { MaterializedFileTargetSchema } from "@agentxm/workspace-state";
+import { gitSourceLockFields } from "@agentxm/workspace-state";
+import { SourceHostProviders, WorkspaceCatalog } from "@agentxm/extension-sources";
+import { stripFileProtocol } from "../internal/fs-helpers.js";
+import { makeWorkspaceRelativeSourcePath } from "@agentxm/extension-model/unstable/path-types";
+import { removeIfExists } from "@agentxm/workspace-state";
+import { makeWorkspaceRelativePath } from "@agentxm/extension-model/unstable/path-types";
+import { decodeVersionSync } from "@agentxm/extension-model/unstable/version-constraints";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { makeConfiguredReleaseAgeEvaluation, resolveConfiguredRule, } from "../configured-entry-resolution.js";
+import { coupleLifecycleDependencyFailure } from "../errors.js";
+import { LifecycleFailureAdapter } from "../failure-adapter.js";
+import { isObservedInstalled } from "@agentxm/workspace-state";
+import { acceptedCanonicalObservation, prepareAcceptedCanonicalTransition, removableAcceptedCanonicalPath, } from "@agentxm/workspace-state";
+import { RULE_BODY_FILENAME, RULE_EXTENSION_DIR, RULE_MANIFEST_FILENAME, RuleManifestSchema, } from "@agentxm/extension-model/unstable/rules/manifest-schema";
+import {} from "@agentxm/extension-model/unstable/extensions/refs/rule";
+const RULES_REGION = "rules";
+const decodeRuleManifest = Schema.decodeUnknownEffect(RuleManifestSchema);
+const decodeMaterializedTarget = Schema.decodeUnknownSync(MaterializedFileTargetSchema);
+const registryRuleLockEntry = (ref, treeIntegrity) => ({
+    type: "registry",
+    sourceType: "registry",
+    packageFormat: "agentxm",
+    endpoint: ref.source.location,
+    extensionType: "rule",
+    workspaceName: ref.rule.name,
+    owner: ref.owner,
+    name: ref.name,
+    resolvedVersion: decodeVersionSync(ref.version),
+    integrity: Option.getOrElse(ref.integrity, () => ""),
+    sourceName: ref.source.name,
+    publisherBindingId: ref.publisherBindingId,
+    treeIntegrity,
+});
+const gitRuleLockEntry = (ref, contentIdentity, treeIntegrity) => ({
+    ...gitSourceLockFields(ref.source, "rule", ref.rule.name, Option.fromUndefinedOr(ref.sourcePath), ref.gitCommitSha, ref.gitTreeSha, contentIdentity, ref.owner, ref.name, treeIntegrity),
+});
+const localRuleLockEntry = (ref, workspaceRelativeLocalSourcePath, contentIdentity, treeIntegrity) => ({
+    type: "local",
+    sourceType: "local",
+    sourceName: "local",
+    extensionType: "rule",
+    workspaceName: ref.rule.name,
+    packageFormat: "agentxm",
+    packageOwner: ref.owner,
+    packageName: ref.name,
+    path: Option.getOrElse(workspaceRelativeLocalSourcePath, () => ref.source.path),
+    contentIdentity,
+    treeIntegrity,
+});
+const normalizeMarkdown = (content) => content
+    .replace(/\r\n?/g, "\n")
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .join("\n")
+    .trim();
+export const ruleMaterializationObservation = (managedTarget, instructionItems) => {
+    const agents = Array.from(new Set(instructionItems
+        .filter(({ agentId, health }) => health === "ok" && agentId !== "universal")
+        .map(({ agentId }) => agentId)));
+    return {
+        agents,
+        targets: [
+            {
+                path: managedTarget,
+                ...(agents.length === 0 ? {} : { agentIds: agents }),
+            },
+        ],
+    };
+};
+export const RuleManagerLive = Layer.effect(RuleManager, Effect.gen(function* () {
+    const ws = yield* WorkspaceMutations;
+    const fs = yield* FileSystem.FileSystem;
+    const httpClient = yield* HttpClient.HttpClient;
+    const path = yield* Path.Path;
+    const sources = yield* SourceHostProviders;
+    const catalog = yield* WorkspaceCatalog;
+    const adapter = yield* LifecycleFailureAdapter;
+    const baseDir = ws.baseDir;
+    const workspaceScope = ws.scope;
+    const fsPathLayer = Layer.mergeAll(Layer.succeed(FileSystem.FileSystem, fs), Layer.succeed(HttpClient.HttpClient, httpClient), Layer.succeed(Path.Path, path));
+    const envLayer = Layer.mergeAll(fsPathLayer, Layer.succeed(WorkspaceMutations, ws), Layer.succeed(SourceHostProviders, sources), Layer.succeed(WorkspaceCatalog, catalog), Layer.succeed(LifecycleFailureAdapter, adapter));
+    const provide = (effect) => Effect.provide(effect, envLayer);
+    const lastInstallState = new Map();
+    let lastProjection;
+    const materializeFromRegistry = (ref, force) => Effect.gen(function* () {
+        const canonicalPath = computeExtensionPathsForLayout(path.join, ws.layout, ref, RULE_EXTENSION_DIR, ref.name).canonicalPath;
+        const lockedEntry = yield* ws.getLockedRuleEntry(ref.rule.name);
+        const lockedVersion = acceptedRegistryVersionForRef(lockedEntry, ref);
+        const reuse = yield* provide(canReuseInstalledPackage({
+            installedPath: canonicalPath,
+            force,
+            refVersion: ref.version,
+            hasIntegrity: Option.isSome(ref.integrity),
+            ...(lockedVersion === undefined ? {} : { lockedVersion }),
+            existsFailureDetail: (target) => `Failed to check if canonical rule package path exists: ${target}`,
+        }));
+        if (reuse && Option.isSome(lockedEntry)) {
+            const observedTree = yield* provide(computeMaterializedTreeIntegrity(canonicalPath));
+            if (observedTree === lockedEntry.value.treeIntegrity) {
+                return { packageRoot: canonicalPath, treeIntegrity: lockedEntry.value.treeIntegrity };
+            }
+        }
+        const materialized = yield* provide(materializeRegistryPackageWithTreeIntegrity({
+            baseDir,
+            destinationPath: canonicalPath,
+            sourceLocation: ref.source.location,
+            owner: ref.owner,
+            type: "rule",
+            name: ref.name,
+            version: ref.version,
+            integrity: ref.integrity,
+            messages: {
+                integrityMismatchDetail: `Integrity mismatch for rule:${ref.name}@${ref.version}`,
+            },
+        }));
+        return {
+            packageRoot: materialized.canonicalPath,
+            treeIntegrity: materialized.treeIntegrity,
+        };
+    });
+    const materializeFromExternal = (ref) => provide(materializeExternalPackageWithTreeIntegrity({
+        baseDir,
+        canonicalPath: computeExtensionPathsForLayout(path.join, ws.layout, ref, RULE_EXTENSION_DIR, ref.rule.name).canonicalPath,
+        sourceLocation: ref.location,
+        copyFailureCode: "validation",
+        copyFailureDetail: (canonicalPath) => `Failed to copy rule package files to ${canonicalPath}`,
+    }).pipe(Effect.map((materialized) => ({
+        packageRoot: materialized.canonicalPath,
+        treeIntegrity: materialized.treeIntegrity,
+    }))));
+    const materializePackage = (ref, force = false) => Effect.gen(function* () {
+        switch (ref.refType) {
+            case "registry":
+                return yield* materializeFromRegistry(ref, force);
+            case "git-hosted":
+            case "local":
+                return yield* materializeFromExternal(ref);
+            case "workspace": {
+                const expectedPath = computeExtensionPathsForLayout(path.join, ws.layout, ref, RULE_EXTENSION_DIR, ref.name).canonicalPath;
+                if (ref.scope !== ws.scope ||
+                    path.resolve(ref.location) !== path.resolve(expectedPath)) {
+                    return yield* new RuleDefinitionInvalid({
+                        detail: `Invalid workspace rule source location: ${ref.location}`,
+                    });
+                }
+                return {
+                    packageRoot: ref.location,
+                    treeIntegrity: yield* provide(computeMaterializedTreeIntegrity(ref.location)),
+                };
+            }
+        }
+    });
+    const readManifest = (packageRoot) => fs.readFileString(path.join(packageRoot, RULE_MANIFEST_FILENAME)).pipe(Effect.flatMap((content) => Effect.try({
+        try: () => JSON.parse(content),
+        catch: (error) => new RuleDefinitionInvalid({
+            detail: `Failed to parse ${RULE_MANIFEST_FILENAME}`,
+            cause: error,
+        }),
+    })), Effect.flatMap((content) => decodeRuleManifest(content)), Effect.mapError((error) => new RuleDefinitionInvalid({
+        detail: `Failed to read ${RULE_MANIFEST_FILENAME}`,
+        cause: error,
+    })));
+    const sourceFileTarget = () => Effect.gen(function* () {
+        const config = yield* ws.getInstructionsConfig();
+        const resolved = resolveInstructionsConfig(Option.isSome(config) && config.value !== false ? config.value : undefined);
+        const relative = makeWorkspaceRelativePath(path, baseDir, resolved.fileName);
+        if (Option.isNone(relative)) {
+            return yield* new RuleDefinitionInvalid({
+                detail: `Rule instruction source escapes workspace: ${resolved.fileName}`,
+            });
+        }
+        return {
+            relative: relative.value,
+            absolute: path.resolve(baseDir, relative.value),
+        };
+    });
+    const activeInstructions = () => Effect.gen(function* () {
+        const config = yield* ws.getInstructionsConfig();
+        if (Option.isNone(config) || config.value === false) {
+            return Option.none();
+        }
+        return Option.some({
+            config: resolveInstructionsConfig(config.value),
+            agents: yield* ws.getConfiguredAgents(),
+        });
+    });
+    const readRuleBody = (packageRoot) => fs.readFileString(path.join(packageRoot, "src", RULE_BODY_FILENAME)).pipe(Effect.flatMap((content) => parseFrontmatterEffect(content)), Effect.map((parsed) => normalizeMarkdown(parsed.body)), Effect.mapError((error) => new RuleDefinitionInvalid({
+        detail: `Failed to read src/${RULE_BODY_FILENAME}`,
+        cause: error,
+    })));
+    const renderRuleBlock = (args) => {
+        const header = args.manifest.title !== undefined && !args.body.startsWith("#")
+            ? `# ${args.manifest.title}\n\n`
+            : "";
+        const marker = serializeMarker({
+            kind: MARKER_KIND_POINT,
+            v: MARKER_VERSION,
+            pointKind: "rule",
+            ext: `${args.marker}@${args.manifest.version}`,
+        }, { kind: "block", open: "<!--", close: "-->" });
+        return `${marker}\n\n${header}${args.body}`;
+    };
+    const selectRuleContributors = (args) => provide(activeContributors({
+        layout: ws.layout,
+        path,
+        type: "rule",
+        extensionDir: RULE_EXTENSION_DIR,
+        graph: args.graph,
+        locked: args.locked,
+    })).pipe(Effect.flatMap((contributors) => Effect.forEach(contributors, (contributor) => Effect.gen(function* () {
+        const manifest = yield* readManifest(contributor.packageRoot);
+        const body = yield* readRuleBody(contributor.packageRoot);
+        const marker = Option.match(contributor.identityOwner, {
+            onSome: (owner) => formatFqn({
+                owner,
+                type: "rule",
+                name: decodeExtensionNameSync(contributor.node.name),
+            }),
+            onNone: () => formatFqn({ owner: manifest.owner, type: "rule", name: manifest.name }),
+        });
+        return { name: contributor.node.name, marker, manifest, body };
+    }), { concurrency: "unbounded" })), Effect.map((resolved) => {
+        const sorted = [...resolved].sort((a, b) => {
+            const byPriority = (a.manifest.priority ?? 100) - (b.manifest.priority ?? 100);
+            if (byPriority !== 0)
+                return byPriority;
+            return a.marker.localeCompare(b.marker);
+        });
+        return sorted;
+    }));
+    const observedRuleContributors = (content) => content.split(/\r?\n/u).flatMap((line) => {
+        const parsed = parseMarker(line, { kind: "block", open: "<!--", close: "-->" });
+        if (parsed.state !== "complete" ||
+            parsed.marker.kind !== MARKER_KIND_POINT ||
+            parsed.marker.pointKind !== "rule") {
+            return [];
+        }
+        const separator = parsed.marker.ext.lastIndexOf("@");
+        return separator > 0 ? [parsed.marker.ext.slice(0, separator)] : [];
+    });
+    const reconcileRulesRegion = (args) => Effect.gen(function* () {
+        const { target } = args;
+        const contributors = args.input.contributors;
+        const rendered = contributors.map(renderRuleBlock).join("\n\n");
+        const instructions = args.instructions;
+        if (args.dryRun !== true && Option.isSome(instructions)) {
+            yield* provide(Effect.gen(function* () {
+                const snapshot = yield* observeInstructionProjection({
+                    workspaceRoot: baseDir,
+                    scope: workspaceScope,
+                    configuredAgents: instructions.value.agents,
+                    config: instructions.value.config,
+                });
+                yield* assertInstructionTargetsSafe(snapshot.status);
+                yield* assertInstructionsGitignoreSafe(baseDir);
+            }));
+        }
+        const reconciliation = yield* provide(reconcileManagedRegionFile({
+            targetPath: target.absolute,
+            displayPath: target.relative,
+            region: RULES_REGION,
+            owner: RULES_REGION_OWNER,
+            rendered,
+            ...(args.dryRun === undefined ? {} : { dryRun: args.dryRun }),
+            writeWhenMissing: true,
+            unsupportedTargetDetail: `Instruction source does not support managed regions: ${target.relative}`,
+        }));
+        const { changed, observedRegion } = reconciliation;
+        const materializedTarget = decodeMaterializedTarget({
+            target: target.relative,
+            mode: "managed-region",
+            region: RULES_REGION,
+        });
+        const projectionUnitObservation = {
+            unitId: "rule:instructions-region",
+            path: `${target.relative}#${RULES_REGION}`,
+            owner: RULES_REGION_OWNER,
+            present: Option.isSome(observedRegion),
+            current: !changed,
+            expectedContributors: contributors.map(({ marker }) => marker),
+            observedContributors: Option.match(observedRegion, {
+                onNone: () => [],
+                onSome: observedRuleContributors,
+            }),
+        };
+        if (args.dryRun === true) {
+            return {
+                materializedTarget,
+                materialization: ruleMaterializationObservation(target.relative, []),
+                changed,
+                projectionUnitObservation,
+            };
+        }
+        const instructionItems = Option.isSome(instructions)
+            ? (yield* provide(reconcileInstructionTargets({
+                workspaceRoot: baseDir,
+                scope: workspaceScope,
+                configuredAgents: instructions.value.agents,
+                config: instructions.value.config,
+            }))).snapshot.status.items
+            : [];
+        const materialization = ruleMaterializationObservation(target.relative, instructionItems);
+        lastProjection = materialization;
+        return { materializedTarget, materialization, changed, projectionUnitObservation };
+    });
+    const makeRulesProjectionPlan = () => Effect.gen(function* () {
+        const target = yield* sourceFileTarget();
+        const instructions = yield* activeInstructions();
+        const graph = yield* ws.getDesiredStateGraph();
+        const locked = yield* ws.getLockedRules();
+        return yield* planAggregateProjection({
+            unitId: "rule:instructions-region",
+            targetFile: target.absolute,
+            graph,
+            select: (completeGraph) => selectRuleContributors({ graph: completeGraph, locked }),
+            adapter: {
+                observe: (input) => reconcileRulesRegion({ input, target, instructions, dryRun: true }).pipe(Effect.map(({ projectionUnitObservation }) => projectionUnitObservation)),
+                apply: (input) => reconcileRulesRegion({ input, target, instructions }).pipe(Effect.asVoid),
+            },
+        });
+    });
+    const projectionPlans = () => makeRulesProjectionPlan().pipe(Effect.map((plan) => [plan]));
+    const applyRulesProjection = projectionPlans().pipe(Effect.flatMap(applyProjectionPlans));
+    const materializeInstall = Effect.fn("RuleManager.materializeInstall")(function* ({ ref, force }) {
+        const materialized = yield* materializePackage(ref, force === true);
+        const packageRoot = materialized.packageRoot;
+        yield* readManifest(packageRoot);
+        const workspaceRelativeLocalSourcePath = ref.refType === "local"
+            ? makeWorkspaceRelativeSourcePath(path, baseDir, ref.sourcePath ?? stripFileProtocol(ref.location))
+            : Option.none();
+        if (ref.refType === "local" && Option.isNone(workspaceRelativeLocalSourcePath)) {
+            return yield* new RuleDefinitionInvalid({
+                detail: `Local rule source path must stay within the workspace root: ${ref.source.path}`,
+            });
+        }
+        const sourceHash = yield* provide(computePackageContentHash(packageRoot));
+        lastInstallState.set(ref.rule.name, {
+            ref,
+            workspaceRelativeLocalSourcePath,
+            sourceHash,
+            treeIntegrity: materialized.treeIntegrity,
+        });
+    }, Effect.asVoid);
+    const buildLockEntry = (ref) => Effect.gen(function* () {
+        const state = lastInstallState.get(ref.rule.name);
+        switch (ref.refType) {
+            case "registry":
+                return state === undefined
+                    ? yield* new RuleInstallStateMissing({ name: ref.rule.name, kind: "tree-integrity" })
+                    : Option.some(registryRuleLockEntry(ref, state.treeIntegrity));
+            case "git-hosted":
+                return state === undefined
+                    ? yield* new RuleInstallStateMissing({
+                        name: ref.rule.name,
+                        kind: "content-identity",
+                    })
+                    : Option.some(gitRuleLockEntry(ref, state.sourceHash, state.treeIntegrity));
+            case "local":
+                return state === undefined
+                    ? yield* new RuleInstallStateMissing({
+                        name: ref.rule.name,
+                        kind: "content-identity",
+                    })
+                    : Option.some(localRuleLockEntry(ref, state.workspaceRelativeLocalSourcePath, state.sourceHash, state.treeIntegrity));
+            case "workspace":
+                return Option.none();
+        }
+    });
+    // Canonical removal only. The shared operation flow re-renders the region
+    // after settings and lock removal, once the target has left the graph.
+    const materializeUninstall = Effect.fn("RuleManager.materializeUninstall")(function* ({ target }) {
+        const canonical = yield* provide(acceptedCanonicalObservation({
+            workspace: ws,
+            type: "rule",
+            name: target.name,
+        }));
+        const packageRoot = removableAcceptedCanonicalPath(canonical);
+        if (Option.isSome(packageRoot)) {
+            yield* removeIfExists(fs, packageRoot.value);
+        }
+    }, Effect.asVoid);
+    // Deactivation retains canonical content; the caller updates settings
+    // first, so re-rendering the whole region drops this rule's contribution.
+    const materializeDeactivate = Effect.fn("RuleManager.materializeDeactivate")(() => applyRulesProjection);
+    return {
+        type: "rule",
+        projectionPlans,
+        runTransaction: ws.runTransaction,
+        isInstalled: ({ target }) => isObservedInstalled(ws, "rule", target.name).pipe(Effect.withSpan("RuleManager.isInstalled")),
+        materializeInstall,
+        prepareSourceTransition: ({ ref }) => provide(prepareAcceptedCanonicalTransition({
+            workspace: ws,
+            type: "rule",
+            name: ref.rule.name,
+            ref,
+        })),
+        getLastMaterialization: () => Effect.succeed(lastProjection ?? { agents: [], targets: [] }),
+        getConfiguredSource: Effect.fn("RuleManager.getConfiguredSource")(function* ({ target }) {
+            const configured = yield* ws.getConfiguredRuleEntries();
+            return Option.fromUndefinedOr(configured[target.name]?.source);
+        }),
+        listMaterializable: Effect.fn("RuleManager.listMaterializable")(function* () {
+            const configured = yield* ws.getConfiguredRuleEntries();
+            const releaseAgeEvaluation = yield* provide(makeConfiguredReleaseAgeEvaluation("enforce")).pipe(Effect.mapError(coupleLifecycleDependencyFailure));
+            const refs = yield* Effect.scoped(Effect.forEach(enabledConfiguredEntries(configured), ([name, entry]) => provide(resolveConfiguredRule(name, entry.source, releaseAgeEvaluation)).pipe(Effect.mapError(coupleLifecycleDependencyFailure), Effect.map(({ ref }) => ref)), { concurrency: "unbounded" }));
+            return refs;
+        }),
+        materializeUninstall,
+        materializeDeactivate,
+        upsertSettingsEntry: Effect.fn("RuleManager.upsertSettingsEntry")(function* ({ ref, versionRange, }) {
+            const lockEntry = yield* buildLockEntry(ref);
+            if (Option.isNone(lockEntry)) {
+                yield* ws.setRuleEntry(ref.rule.name, {
+                    source: "workspace",
+                    enabled: true,
+                });
+                return;
+            }
+            if (lockEntry.value.type === "registry") {
+                yield* validateExactResolvedVersion(`rules.${ref.rule.name}.resolvedVersion`, lockEntry.value.resolvedVersion);
+            }
+            yield* ws.setRule({
+                name: ref.rule.name,
+                lockEntry: lockEntry.value,
+                versionRange,
+            });
+        }),
+        removeSettingsEntry: Effect.fn("RuleManager.removeSettingsEntry")(function* ({ target }) {
+            yield* ws.removeRuleSettings(target.name);
+        }),
+        upsertLockfileEntry: Effect.fn("RuleManager.upsertLockfileEntry")(function* ({ ref }) {
+            const lockEntry = yield* buildLockEntry(ref);
+            if (Option.isNone(lockEntry)) {
+                yield* ws.removeRuleLock(ref.rule.name);
+                return;
+            }
+            if (lockEntry.value.type === "registry") {
+                yield* validateExactResolvedVersion(`rules.${ref.rule.name}.resolvedVersion`, lockEntry.value.resolvedVersion);
+            }
+            yield* ws.setRuleLock({
+                name: ref.rule.name,
+                lockEntry: lockEntry.value,
+                versionRange: Option.none(),
+            });
+        }),
+        removeLockfileEntry: Effect.fn("RuleManager.removeLockfileEntry")(function* ({ target }) {
+            yield* ws.removeRuleLock(target.name);
+        }),
+    };
+}));
+//# sourceMappingURL=manager.js.map

package/dist/src/skills/manager.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Skill extension manager service.
+ *
+ * Implements ExtensionManager<SkillExtensionRef> with native/non-native
+ * branching in materializeInstall and agent symlink creation for all
+ * configured agents.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as Path from "effect/Path";
+import * as Layer from "effect/Layer";
+import { SourceHostProviders } from "@agentxm/extension-sources";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { CodingAgentRepository, SkillManager } from "@agentxm/extension-workspace";
+export declare const SkillManagerLive: Layer.Layer<SkillManager, never, SourceHostProviders | WorkspaceMutations | FileSystem.FileSystem | HttpClient.HttpClient | Path.Path | CodingAgentRepository>;
+//# sourceMappingURL=manager.d.ts.map