@agentxm/extension-lifecycle 0.28.4-bootstrap.0

package/dist/src/skills/operations/disable.js

@@ -0,0 +1,110 @@
+/**
+ * Disable skill executor — removes agent symlinks but preserves canonical files.
+ *
+ * Materialized artifacts are observed directly. Accepted-resolution rows identify
+ * source content but do not prove that canonical or projected files exist.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Array from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Layer from "effect/Layer";
+import { DefaultCodingAgentRepository } from "@agentxm/extension-workspace";
+import { ExtensionLifecycleFailed } from "../../errors.js";
+import { LifecycleFailureAdapter, withAdaptedStepFailures } from "../../failure-adapter.js";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { sanitizeName } from "@agentxm/workspace-state";
+import { skillArtifactFromTargets, } from "@agentxm/extension-workspace";
+import { installedRowsByName } from "@agentxm/workspace-state";
+import { removeSkillAgentArtifact } from "../materialization.js";
+// -----------------------------------------------------------------------------
+// Public API
+// -----------------------------------------------------------------------------
+/**
+ * Disable-skill operation handler.
+ *
+ * Determines lifecycle from the workspace read model, removes observable
+ * materialized targets, and promotes implicit pack members to a direct disabled
+ * preference. Canonical files are preserved for later re-enablement.
+ */
+export const disableSkill = (op) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const ws = yield* WorkspaceMutations;
+    const base = ws.baseDir;
+    const fsPathLayer = Layer.mergeAll(Layer.succeed(FileSystem.FileSystem, fs), Layer.succeed(Path.Path, path));
+    // Read lifecycle to determine promotion needs
+    const installedSkills = yield* ws.records.rows("skill").pipe(Effect.map(installedRowsByName));
+    const installed = installedSkills[op.args.skillName];
+    const isImplicit = installed !== undefined && installed.lifecycle === "implicit";
+    const graph = yield* ws.getDesiredStateGraph();
+    if (!graph.complete) {
+        return yield* new ExtensionLifecycleFailed({
+            category: "conflict",
+            detail: "Cannot disable the skill while pack-derived desired state is unresolved.",
+        });
+    }
+    const desiredBeforeDisable = graph.nodes.find((node) => node.type === "skill" && node.name === op.args.skillName);
+    const sanitizedName = sanitizeName(op.args.skillName);
+    const materializationAgents = yield* DefaultCodingAgentRepository.getMaterializationAgents().pipe(Effect.provideService(WorkspaceMutations, ws));
+    const installableTargetOptions = yield* ws.runTransaction({
+        transition: Effect.gen(function* () {
+            if (isImplicit) {
+                const source = desiredBeforeDisable?.source ?? Option.getOrElse(installed.source, () => undefined);
+                if (source === undefined) {
+                    return yield* new ExtensionLifecycleFailed({
+                        category: "internal",
+                        detail: `Cannot determine source for implicit skill "${op.args.skillName}"`,
+                        suggestions: [{ description: "Provide a source when disabling this skill" }],
+                    });
+                }
+                yield* ws.setSkillEntry(op.args.skillName, { source, enabled: false });
+            }
+            else {
+                yield* ws.updateSkillEntry(op.args.skillName, (entry) => ({
+                    ...entry,
+                    enabled: false,
+                }));
+            }
+            return yield* Effect.forEach(materializationAgents, (agent) => agent.resolveEffectiveSkillsDir({ workspaceRoot: base }).pipe(Effect.provide(fsPathLayer), Effect.flatMap((outcome) => outcome._tag === "supported"
+                ? Effect.gen(function* () {
+                    const targetDir = path.normalize(outcome.dir);
+                    yield* removeSkillAgentArtifact({
+                        fs,
+                        pathService: path,
+                        targetDir,
+                        sanitizedName,
+                    });
+                    return Option.some({
+                        agentId: agent.id,
+                        targetDir,
+                    });
+                })
+                : Effect.succeed(Option.none()))), { concurrency: "unbounded" });
+        }).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path)),
+        validate: () => Effect.void,
+    });
+    const installableTargets = Array.getSomes(installableTargetOptions);
+    const artifact = yield* skillArtifactFromTargets({
+        targets: installableTargets,
+        workspaceRoot: base,
+        sanitizedName,
+        scope: ws.scope,
+        change: "removed",
+        workspaceTargets: [
+            {
+                path: ws.scope === "project" ? "axm.json" : ".axm/workspace/axm.json",
+                change: "updated",
+            },
+        ],
+    }).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path));
+    return {
+        result: "success",
+        message: `Disabled ${op.args.skillName}`,
+        artifact,
+    };
+}).pipe(withAdaptedStepFailures);
+//# sourceMappingURL=disable.js.map

package/dist/src/skills/operations/enable.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Enable skill executor — re-creates agent symlinks for a previously disabled skill.
+ *
+ * Enabling requires desired canonical content aligned with its accepted
+ * external resolution when one is required.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { LifecycleFailureAdapter } from "../../failure-adapter.js";
+import type { OperationHandler } from "@agentxm/workspace-operations";
+import type { Operation } from "@agentxm/workspace-operations";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+/**
+ * Enable a previously disabled skill (re-install files and update state).
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type EnableSkillOperation = Operation<"enable-skill", {
+    readonly skillName: string;
+}>;
+/**
+ * Enable-skill operation handler.
+ *
+ * 1. Resolve usable canonical content from desired state, accepted resolution, and observation.
+ * 2. Create agent artifacts.
+ * 3. Update settings to set enabled: true.
+ */
+export declare const enableSkill: OperationHandler<EnableSkillOperation, FileSystem.FileSystem | Path.Path | WorkspaceMutations | LifecycleFailureAdapter>;
+//# sourceMappingURL=enable.d.ts.map

package/dist/src/skills/operations/enable.js

@@ -0,0 +1,113 @@
+/**
+ * Enable skill executor — re-creates agent symlinks for a previously disabled skill.
+ *
+ * Enabling requires desired canonical content aligned with its accepted
+ * external resolution when one is required.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Layer from "effect/Layer";
+import { DefaultCodingAgentRepository } from "@agentxm/extension-workspace";
+import { ExtensionLifecycleFailed } from "../../errors.js";
+import { LifecycleFailureAdapter, withAdaptedStepFailures } from "../../failure-adapter.js";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { sanitizeName } from "@agentxm/workspace-state";
+import { ensureSkillAgentArtifact } from "../materialization.js";
+import { skillArtifactFromTargets, } from "@agentxm/extension-workspace";
+import { usableAcceptedCanonicalObservation } from "@agentxm/workspace-state";
+// -----------------------------------------------------------------------------
+// Public API
+// -----------------------------------------------------------------------------
+/**
+ * Enable-skill operation handler.
+ *
+ * 1. Resolve usable canonical content from desired state, accepted resolution, and observation.
+ * 2. Create agent artifacts.
+ * 3. Update settings to set enabled: true.
+ */
+export const enableSkill = (op) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const ws = yield* WorkspaceMutations;
+    const base = ws.baseDir;
+    const fsPathLayer = Layer.mergeAll(Layer.succeed(FileSystem.FileSystem, fs), Layer.succeed(Path.Path, path));
+    const provide = (effect) => Effect.provide(effect, fsPathLayer);
+    const canonical = yield* usableAcceptedCanonicalObservation({
+        workspace: ws,
+        type: "skill",
+        name: op.args.skillName,
+    });
+    if (Option.isNone(canonical)) {
+        return yield* new ExtensionLifecycleFailed({
+            category: "not_found",
+            detail: `Accepted skill content for "${op.args.skillName}" is not usable`,
+            suggestions: [
+                {
+                    description: "Try reinstalling the skill.",
+                    cmd: "axm skills install <source>",
+                },
+            ],
+        });
+    }
+    const sanitizedName = sanitizeName(op.args.skillName);
+    const materializationAgents = yield* DefaultCodingAgentRepository.getMaterializationAgents().pipe(Effect.provideService(WorkspaceMutations, ws));
+    const skillSrcPath = canonical.value.observation.path;
+    const installableTargets = yield* ws.runTransaction({
+        transition: Effect.gen(function* () {
+            const resolvedTargets = yield* Effect.forEach(materializationAgents, (agent) => agent.resolveEffectiveSkillsDir({ workspaceRoot: base }).pipe(Effect.provide(fsPathLayer), Effect.map((outcome) => ({ agent, outcome }))), { concurrency: "unbounded" });
+            const targets = resolvedTargets.flatMap(({ agent, outcome }) => outcome._tag === "supported"
+                ? [{ agentId: agent.id, targetDir: path.normalize(outcome.dir) }]
+                : []);
+            const locations = new Map();
+            for (const target of targets) {
+                const current = locations.get(target.targetDir);
+                if (current === undefined) {
+                    locations.set(target.targetDir, {
+                        targetDir: target.targetDir,
+                        agentIds: [target.agentId],
+                    });
+                }
+                else if (!current.agentIds.includes(target.agentId)) {
+                    current.agentIds.push(target.agentId);
+                }
+            }
+            yield* Effect.forEach([...locations.values()], (location) => ensureSkillAgentArtifact({
+                canonicalSkillSrcPath: skillSrcPath,
+                targetDir: location.targetDir,
+                sanitizedName,
+                pathService: path,
+                baseDir: base,
+                provide,
+            }), { concurrency: "unbounded" });
+            yield* ws.updateSkillEntry(op.args.skillName, (entry) => ({
+                ...entry,
+                enabled: true,
+            }));
+            return targets;
+        }).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path)),
+        validate: () => Effect.void,
+    });
+    const artifact = yield* skillArtifactFromTargets({
+        targets: installableTargets,
+        workspaceRoot: base,
+        sanitizedName,
+        scope: ws.scope,
+        change: "created",
+        workspaceTargets: [
+            {
+                path: ws.scope === "project" ? "axm.json" : ".axm/workspace/axm.json",
+                change: "updated",
+            },
+        ],
+    }).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path));
+    return {
+        result: "success",
+        message: `Enabled ${op.args.skillName}`,
+        artifact,
+    };
+}).pipe(withAdaptedStepFailures);
+//# sourceMappingURL=enable.js.map

package/dist/src/skills/operations/install-result.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Structured per-agent installation result.
+ *
+ * Captures the outcome of installing a skill for a single agent,
+ * including success/failure state and symlink fallback information.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type * as Option from "effect/Option";
+/**
+ * Result of installing a skill for a single agent.
+ *
+ * - `success: true, mode: "symlink"` — installed via symlink
+ * - `success: true, mode: "copy"` — symlink failed, fell back to copy
+ * - `success: false` — installation failed
+ */
+export interface InstallResult {
+    /** Whether the installation succeeded for this agent. */
+    readonly success: boolean;
+    /** Installation mode used ("symlink" or "copy"). */
+    readonly mode: "symlink" | "copy";
+    /** Whether symlink creation was attempted and failed (triggering copy fallback). */
+    readonly symlinkFailed: boolean;
+    /** Error message if installation failed. */
+    readonly error: Option.Option<string>;
+    /** Agent-specific skill directory path. */
+    readonly path: string;
+    /** Exact source-qualified canonical skill location. */
+    readonly canonicalPath: string;
+    /** User-visible change at the agent-specific skill path. */
+    readonly change?: "created" | "updated" | "unchanged";
+}
+//# sourceMappingURL=install-result.d.ts.map

package/dist/src/skills/operations/install-result.js

@@ -0,0 +1,10 @@
+/**
+ * Structured per-agent installation result.
+ *
+ * Captures the outcome of installing a skill for a single agent,
+ * including success/failure state and symlink fallback information.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export {};
+//# sourceMappingURL=install-result.js.map

package/dist/src/skills/operations/install.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Install skill executor — orchestrates the full per-skill installation pipeline.
+ *
+ * Dispatches to a per-refType install function via `switch(ref.refType)`, then
+ * runs shared post-install steps (agent symlinks, lockfile/settings writes).
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import * as Path from "effect/Path";
+import * as Option from "effect/Option";
+import type { AgentId } from "@agentxm/extension-model/unstable/agents/types";
+import { type RenderedFilesMap } from "@agentxm/workspace-state";
+import type { SkillExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/skill";
+import { SourceHostProviders } from "@agentxm/extension-sources";
+import { CodingAgentRepository } from "@agentxm/extension-workspace";
+import { LifecycleFailureAdapter } from "../../failure-adapter.js";
+import type { OperationHandler } from "@agentxm/workspace-operations";
+import type { Operation } from "@agentxm/workspace-operations";
+import type { JobStepArtifactSource } from "@agentxm/workspace-operations";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import type { InstallResult } from "./install-result.js";
+/**
+ * Args for the install-skill operation.
+ */
+export type InstallSkillOperationArgs = {
+    readonly ref: SkillExtensionRef;
+    readonly force: boolean;
+    /** Version constraint from the original input when available. */
+    readonly versionRange: Option.Option<string>;
+    /** When true, write to lockfile only (skip settings). Used for pack dependencies. */
+    readonly skipSettings: Option.Option<boolean>;
+    /** When true, fail on unknown configured agents instead of warning+skip. */
+    readonly strictUnknownAgents: Option.Option<boolean>;
+    /** Named registry source that provided the ref (written to lockfile for registry skills). */
+    readonly sourceName: Option.Option<string>;
+};
+/**
+ * Add a skill to the workspace.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type InstallSkillOperation = Operation<"install-skill", InstallSkillOperationArgs>;
+export declare const gitHostedSkillArtifactSource: (ref: SkillExtensionRef) => JobStepArtifactSource | undefined;
+export { computeSkillSourceHash } from "./source-hash.js";
+/**
+ * Build a RenderedFilesMap from per-agent copy-mode install results.
+ * Only includes agents where mode === "copy" and success === true.
+ *
+ * @internal Exported for testing only.
+ */
+export declare const buildRenderedFilesFromResults: (installableTargets: ReadonlyArray<{
+    agentId: AgentId;
+    targetDir: string;
+}>, agentResults: ReadonlyArray<InstallResult>, toWorkspaceRelativePath: (path: string) => string) => RenderedFilesMap;
+/**
+ * Install-skill operation handler.
+ *
+ * Dispatches to a per-refType install function producing a MaterializedSkill,
+ * then runs shared post-install steps:
+ * 1. Create symlinks from each agent's skills dir (concurrent)
+ * 2. Update lockfile/settings entry (failures logged as warnings)
+ * 3. Compute and return overall result
+ */
+export declare const installSkill: OperationHandler<InstallSkillOperation, FileSystem.FileSystem | HttpClient.HttpClient | Path.Path | WorkspaceMutations | SourceHostProviders | CodingAgentRepository | LifecycleFailureAdapter>;
+//# sourceMappingURL=install.d.ts.map