@agentxm/extension-lifecycle 0.28.11 → 0.28.13

package/dist/src/hooks/install/plan.js

@@ -0,0 +1,224 @@
+/**
+ * Installing hooks packages.
+ *
+ * A hook becomes observable through each agent's own hook configuration, so
+ * its planned artifact is the set of configured-agent outcomes, and an agent
+ * that cannot accept the hook blocks the closure rather than failing mid-way.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { HookManager, buildInstallOperation } from "@agentxm/extension-materialization";
+import { parseSourceQualifiedRegistrySourcePatternParts, } from "@agentxm/extension-model/unstable/extensions";
+import { HOOK_EXTENSION_DIR } from "@agentxm/extension-model/unstable/hooks/manifest-schema";
+import { SourceHostProviders, resolveSource } from "@agentxm/extension-sources";
+import { operationPresentation, } from "@agentxm/workspace-operations";
+import { applyPlannedProjections } from "@agentxm/workspace-projection";
+import { ACQUIRED_EXTENSIONS_DIR, WorkspaceMutations, acquiredExtensionDisplayPath, acquiredExtensionDisplayPathFromLockEntry, } from "@agentxm/workspace-state";
+import { lifecycleStepFailure } from "../../step-failure.js";
+import { registryLoginSuggestions } from "../../install/registry-login-suggestion.js";
+import { installRefused, } from "../../install/vocabulary.js";
+const hookLockEntryVersion = (entry) => entry.type === "registry" ? entry.resolvedVersion : undefined;
+const acquiredRoot = (scope) => scope === "project" ? ACQUIRED_EXTENSIONS_DIR : ".axm/workspace/agent_extensions";
+const hookRefArtifactPath = (ref, scope) => ref.refType === "workspace"
+    ? ref.location
+    : acquiredExtensionDisplayPath(acquiredRoot(scope), ref, HOOK_EXTENSION_DIR, ref.name);
+const hookInstallArtifactPath = (entry, scope) => acquiredExtensionDisplayPathFromLockEntry(acquiredRoot(scope), entry, HOOK_EXTENSION_DIR, entry.workspaceName);
+/** The artifact an applied hook install reports, from its accepted lock entry. */
+export const hookInstallArtifact = (args) => {
+    const version = hookLockEntryVersion(args.lockEntry);
+    return {
+        path: hookInstallArtifactPath(args.lockEntry, args.scope),
+        scope: args.scope,
+        agents: args.agents,
+        ...(version === undefined ? {} : { version }),
+        change: args.installedBefore ? "updated" : "created",
+        ...(args.agentOutcomes === undefined ? {} : { agentOutcomes: args.agentOutcomes }),
+        ...(args.targets.length === 0 ? {} : { fileCount: args.targets.length, targets: args.targets }),
+    };
+};
+/** Read the hooks source grammar: which owner, which names, which range. */
+export const parseHookInstallRequest = Effect.fn("InstallExtensions.parseHookRequest")(function* (source) {
+    const input = source.trim();
+    const parsed = parseSourceQualifiedRegistrySourcePatternParts(input);
+    const resolved = yield* resolveSource(input).pipe(Effect.mapError((error) => installRefused({
+        category: "validation",
+        detail: `Invalid hooks source: ${error.message}`,
+        cause: error,
+    })));
+    return {
+        source: resolved,
+        names: parsed?.type === "hooks" && parsed.name !== undefined ? [parsed.name] : [],
+        owner: parsed?.type === "hooks"
+            ? Option.some(parsed.owner)
+            : resolved.type === "registry"
+                ? resolved.owner
+                : Option.none(),
+        versionRange: resolved.type === "registry" && parsed?.type === "hooks"
+            ? Option.fromUndefinedOr(parsed.versionRange)
+            : Option.none(),
+    };
+});
+/** Discover the hooks packages the parsed source offers. */
+export const discoverHookRefs = Effect.fn("InstallExtensions.discoverHooks")(function* (request) {
+    const sources = yield* SourceHostProviders;
+    return yield* sources
+        .find(request.source, {
+        names: request.names,
+        type: "hook",
+        owner: request.owner,
+        versionRange: request.versionRange,
+    })
+        .pipe(Effect.mapError((cause) => installRefused({
+        category: "network",
+        detail: "Hooks packages could not be discovered from the source",
+        cause,
+    })), Effect.map((refs) => refs.filter((ref) => ref.type === "hook")));
+});
+/** Settle which hooks packages this request installs, or refuse when none matched. */
+export const finalizeHookInstallIntent = Effect.fn("InstallExtensions.finalizeHookIntent")(function* (request, refs) {
+    if (refs.length === 0) {
+        const suggestions = request.source.type === "registry"
+            ? yield* registryLoginSuggestions([request.source.location.href])
+            : [];
+        return yield* installRefused({
+            category: "not_found",
+            detail: "No hooks packages found in source",
+            suggestions,
+        });
+    }
+    return {
+        refs: refs.map((ref) => ({
+            ref,
+            versionRange: ref.refType === "registry" ? request.versionRange : Option.none(),
+        })),
+    };
+});
+/** The closures a settled hook intent becomes. */
+export const planHookInstall = Effect.fn("InstallExtensions.planHooks")(function* (intent) {
+    const ws = yield* WorkspaceMutations;
+    const hookManager = yield* HookManager;
+    const deferProjections = intent.deferProjections === true || intent.refs.length > 1;
+    const memberSteps = yield* Effect.forEach(intent.refs, ({ ref, versionRange }) => Effect.gen(function* () {
+        const installedBefore = yield* hookManager.isInstalled({
+            target: { type: "hook", name: ref.hook.name },
+        });
+        const agentOutcomes = hookManager.configuredAgentOutcomesForRef === undefined
+            ? []
+            : yield* hookManager.configuredAgentOutcomesForRef(ref, "projected");
+        const previewPath = hookRefArtifactPath(ref, ws.scope);
+        const previewArtifact = {
+            path: previewPath,
+            scope: ws.scope,
+            agents: agentOutcomes
+                .filter(({ outcome }) => outcome !== "blocked")
+                .map(({ agentId }) => agentId),
+            ...(ref.refType === "registry" || ref.refType === "workspace"
+                ? { version: ref.version }
+                : {}),
+            change: installedBefore ? "updated" : "created",
+            agentOutcomes,
+            targets: Array.from(new Map(agentOutcomes.flatMap((outcome) => outcome.path === undefined
+                ? []
+                : [
+                    [
+                        outcome.path,
+                        {
+                            path: outcome.path,
+                            change: installedBefore ? "updated" : "created",
+                            agentIds: agentOutcomes
+                                .filter(({ path }) => path === outcome.path)
+                                .map(({ agentId }) => agentId),
+                        },
+                    ],
+                ])).values()),
+        };
+        const operation = buildInstallOperation(hookManager, {
+            toStepFailure: lifecycleStepFailure,
+            ref,
+            versionRange,
+            skipProjections: deferProjections,
+            installedBefore: Effect.succeed(installedBefore),
+            message: `Installed ${ref.hook.name}`,
+            buildArtifact: ({ installedBefore }) => Effect.gen(function* () {
+                const materialization = yield* hookManager.aggregateProjectionObservation;
+                const appliedOutcomes = hookManager.configuredAgentOutcomesForRef === undefined
+                    ? []
+                    : yield* hookManager.configuredAgentOutcomesForRef(ref, "current");
+                const currentLockEntry = yield* ws
+                    .getLockedHookEntry(ref.hook.name)
+                    .pipe(Effect.catch(() => Effect.succeed(Option.none())));
+                if (Option.isNone(currentLockEntry)) {
+                    const path = hookRefArtifactPath(ref, ws.scope);
+                    const change = installedBefore ? "updated" : "created";
+                    return {
+                        path,
+                        scope: ws.scope,
+                        ...(ref.refType === "registry" || ref.refType === "workspace"
+                            ? { version: ref.version }
+                            : {}),
+                        agents: materialization.agents,
+                        change,
+                        agentOutcomes: appliedOutcomes,
+                        targets: materialization.targets.length === 0
+                            ? [{ path, change }]
+                            : materialization.targets.map((target) => ({ ...target, change })),
+                    };
+                }
+                return hookInstallArtifact({
+                    lockEntry: currentLockEntry.value,
+                    installedBefore,
+                    scope: ws.scope,
+                    agents: materialization.agents,
+                    agentOutcomes: appliedOutcomes,
+                    targets: materialization.targets.map((target) => ({
+                        ...target,
+                        change: installedBefore ? "updated" : "created",
+                    })),
+                });
+            }),
+        });
+        // An agent that cannot accept this hook is a projection fact, so the
+        // closure is refused before it writes rather than failing part-way.
+        const blocked = agentOutcomes.filter(({ outcome }) => outcome === "blocked");
+        if (blocked.length > 0) {
+            return {
+                ...(operation.key === undefined ? {} : { key: operation.key }),
+                label: operation.label,
+                readiness: "error",
+                errorMessage: blocked.map(({ agentId, reason }) => `${agentId}: ${reason}`).join("; "),
+                artifact: previewArtifact,
+            };
+        }
+        return {
+            ...operation,
+            artifact: previewArtifact,
+        };
+    }).pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: `Hook install planning failed for ${ref.hook.name}`,
+        cause,
+    }))), { concurrency: 1 });
+    const projectionSteps = deferProjections && intent.deferProjections !== true
+        ? [
+            {
+                key: "projection:hook:units",
+                label: "hook projections",
+                readiness: "ready",
+                run: applyPlannedProjections(hookManager).pipe(Effect.mapError(lifecycleStepFailure), Effect.as({
+                    result: "success",
+                    message: "Rendered installed Hooks from the complete contributor set",
+                })),
+            },
+        ]
+        : [];
+    return {
+        _tag: "Plan",
+        name: "Install hooks",
+        description: Option.some("Install hooks package"),
+        presentation: operationPresentation({ imperative: "install", past: "Installed", gerund: "Installing" }, "hook"),
+        jobs: [{ concurrency: 1, steps: [...memberSteps, ...projectionSteps] }],
+    };
+});
+//# sourceMappingURL=plan.js.map

package/dist/src/hooks/uninstall/plan.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Uninstalling a hooks package.
+ *
+ * A hooks package whose canonical content is kept on disk is reported as
+ * retained, from the settlement the removal returns rather than from the
+ * sentence it printed.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { HookManager } from "@agentxm/extension-materialization";
+import type { Plan } from "@agentxm/workspace-operations";
+import type { ExtensionLifecycleFailed } from "../../errors.js";
+import { type InstallStepRequirements } from "../../install/vocabulary.js";
+import type { HookUninstallIntent } from "../../uninstall/vocabulary.js";
+/** Settle whether this hooks package has anything to remove. */
+export declare const parseHookUninstallRequest: (selector: string) => Effect.Effect<HookUninstallIntent, ExtensionLifecycleFailed, InstallStepRequirements | HookManager>;
+/** The closures a settled hooks-package removal becomes. */
+export declare const planHookUninstall: (intent: HookUninstallIntent) => Effect.Effect<Plan<InstallStepRequirements>, ExtensionLifecycleFailed, InstallStepRequirements | HookManager>;
+//# sourceMappingURL=plan.d.ts.map

package/dist/src/hooks/uninstall/plan.js

@@ -0,0 +1,77 @@
+/**
+ * Uninstalling a hooks package.
+ *
+ * A hooks package whose canonical content is kept on disk is reported as
+ * retained, from the settlement the removal returns rather than from the
+ * sentence it printed.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { HookManager, buildUninstallOperation } from "@agentxm/extension-materialization";
+import { WorkspaceMutations, acquiredExtensionDisplayPathFromLockEntry, } from "@agentxm/workspace-state";
+import { lifecycleStepFailure } from "../../step-failure.js";
+import { installRefused } from "../../install/vocabulary.js";
+import { makeWorkspaceRetentionPolicy } from "../../uninstall/retention-policy.js";
+import { workspaceCanonicalRoot, workspaceLockfilePath, workspaceSettingsPath, } from "../../workspace-paths.js";
+const hookUninstallArtifactTargets = (entry, retained, targetName, scope) => {
+    if (Option.isNone(entry))
+        return [];
+    const sourcePath = acquiredExtensionDisplayPathFromLockEntry(workspaceCanonicalRoot(scope), entry.value, "hooks", targetName);
+    return [
+        { path: workspaceLockfilePath(scope), change: "updated" },
+        { path: workspaceSettingsPath(scope), change: "updated" },
+        { path: sourcePath, change: retained ? "unchanged" : "removed" },
+    ];
+};
+/** Settle whether this hooks package has anything to remove. */
+export const parseHookUninstallRequest = Effect.fn("UninstallExtensions.parseHookRequest")(function* (selector) {
+    const hookManager = yield* HookManager;
+    const target = { type: "hook", name: selector.trim() };
+    return yield* Effect.gen(function* () {
+        const configured = hookManager.getConfiguredSource === undefined
+            ? Option.none()
+            : yield* hookManager.getConfiguredSource({ target });
+        const installed = yield* hookManager.isInstalled({ target });
+        return Option.isNone(configured) && !installed
+            ? { targets: [] }
+            : { targets: [target] };
+    }).pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: `Hooks package "${target.name}" declaration could not be read`,
+        cause,
+    })));
+});
+/** The closures a settled hooks-package removal becomes. */
+export const planHookUninstall = Effect.fn("UninstallExtensions.planHooks")(function* (intent) {
+    const ws = yield* WorkspaceMutations;
+    const hookManager = yield* HookManager;
+    const retentionPolicy = makeWorkspaceRetentionPolicy(ws);
+    const steps = yield* Effect.forEach(intent.targets, (target) => Effect.gen(function* () {
+        const lockEntry = yield* ws
+            .getLockedHookEntry(target.name)
+            .pipe(Effect.catch(() => Effect.succeed(Option.none())));
+        return buildUninstallOperation(hookManager, retentionPolicy, {
+            target,
+            toStepFailure: lifecycleStepFailure,
+            buildArtifact: ({ settlement }) => {
+                const retained = settlement.canonical !== "removed";
+                const targets = hookUninstallArtifactTargets(lockEntry, retained, target.name, ws.scope);
+                return Effect.succeed({
+                    path: retained ? workspaceSettingsPath(ws.scope) : workspaceLockfilePath(ws.scope),
+                    scope: ws.scope,
+                    change: retained ? "updated" : "removed",
+                    ...(targets.length === 0 ? {} : { fileCount: targets.length, targets }),
+                });
+            },
+        });
+    }));
+    return {
+        _tag: "Plan",
+        name: "Uninstall hooks",
+        description: Option.some("Uninstall hooks package"),
+        jobs: [{ concurrency: 1, steps }],
+    };
+});
+//# sourceMappingURL=plan.js.map

package/dist/src/index.d.ts

@@ -1,38 +1,70 @@
 /**
  * Extension-lifecycle feature: install, update, uninstall, enable, and
  * disable policy across root and type-specific command forms — configured
- * entry resolution, the shared install/uninstall command workflows, and the
- * per-type lifecycle operations. The environment-backed per-type manager
+ * entry resolution, the install and uninstall use cases every command
+ * spelling routes through, and the per-type lifecycle operations. The environment-backed per-type manager
  * layers live behind `./live`.
  *
  * @experimental All exports from this module are unstable and may change without notice.
  * @packageDocumentation
  */
 export { ExtensionLifecycleFailed } from "./errors.js";
-export { ReleaseAgePosture, type ReleaseAgePostureValue } from "./release-age-posture.js";
-export { LifecycleFailureAdapter, withAdaptedStepFailures, type LifecycleFailureAdapterService, } from "./failure-adapter.js";
-export { makeConfiguredReleaseAgeEvaluation, resolveConfiguredHook, resolveConfiguredKnowledge, resolveConfiguredMcpServer, resolveConfiguredPack, resolveConfiguredRegistryEntry, resolveConfiguredRule, resolveConfiguredSkill, resolveConfiguredSubagent, } from "./configured-entry-resolution.js";
-export { CONFIGURED_ENTRY_RESOLUTION_TIMEOUT, withConfiguredEntryResolutionTimeout, } from "./resolution-timeout.js";
-export { PUBLISHER_CHANGE_CONDITION_ID, classifyPublisherBindingTransition, publisherChangeRiskCondition, publisherTransitionWarning, registryBindingProposal, withPublisherTrust, withPublisherTrustConditions, type PublisherBindingTransition, } from "./publisher-binding.js";
-export { buildInstallCommandPlan, runInstallCommandWorkflow, type InstallExtensionCommandWorkflowActions, } from "./workflows/install-command/workflow.js";
-export { runUninstallCommandWorkflow, type UninstallExtensionCommandWorkflowActions, type UninstallWorkflowFlags, } from "./workflows/uninstall-command/workflow.js";
-export { materializeRegistryPackage, materializeRegistryPackageWithTreeIntegrity, type MaterializeRegistryPackageArgs, type RegistryPackageMaterializationMessages, } from "./registry-materialization.js";
-export { ensureSkillAgentArtifact, removeSkillAgentArtifact } from "./skills/materialization.js";
+export { StepFailureConversion, withAdaptedStepFailures, type LifecycleFailure, type StepFailureConversionService, } from "./step-failure-conversion.js";
+export { prepareSetActivation, previewOrApplySetActivation, SetActivation, type ActivationTransition, type ActivationUnchanged, type SetActivationCandidate, type SetActivationFailure, type SetActivationRequest, type SetActivationRequirements, } from "./activation/set-activation.js";
+export type { SetActivationExecutionFailure } from "./activation/errors.js";
+export { PUBLISHER_CHANGE_CONDITION_ID, publisherChangeRiskCondition, withPublisherTrust, withPublisherTrustConditions, } from "./publisher-binding.js";
+export { InstallExtensions, prepareInstallExtensions, previewOrApplyInstallExtensions, type InstallDiagnostics, type InstallExtensionsCandidate, type InstallExtensionsFailure, type InstallExtensionsRequest, type InstallSubject, } from "./install/install-extensions.js";
+export { installRefused, type HookInstallIntent, type InstallStepRequirements, type KnowledgeInstallIntent, type McpServerInstallIntent, type PackInstallIntent, type PackRecoveryDependencyResolver, type PrepareInstallRequirements, type ResolveInstallRequirements, type RuleInstallIntent, type SkillInstallIntent, type SubagentInstallIntent, } from "./install/vocabulary.js";
+export { ExtensionSelectionCancelled, ExtensionSelectionInteraction, type ExtensionSelectionFailure, type ExtensionSelectionInteractionService, } from "./install/selection-interaction.js";
+export { resolveRootInstallIntent, rootInstallableTypeSegments, RootInstallableTypeSegmentSchema, type RootInstallIntent, type RootInstallableType, type RootInstallableTypeSegment, } from "./install/root-intent.js";
+export { installCommandFor, perTypeInstallPluralSegments } from "./install/per-type-install.js";
+export { buildConfiguredInstallPlan, buildConfiguredPackInstallPlan, type ConfiguredInstallPlanResult, type ConfiguredInstallRequirements, type ConfiguredInstallableType, } from "./install/configured.js";
+export { buildAggregateProjectionStep } from "./install/aggregate-projection-step.js";
+export { inlineMcpNotApplicablePlan } from "./install/inline-mcp-operation.js";
+export { formatRegistryProbe, type RegistryLookupProbe, } from "./install/registry-source-resolution.js";
+export { planHookInstall } from "./hooks/install/plan.js";
+export { planKnowledgeInstall } from "./knowledge/install/plan.js";
+export { parseMcpEnvInputs, planMcpServerInstall } from "./mcps/install/plan.js";
+export { planPackInstall, type PackInstallRequirements } from "./packs/install/plan.js";
+export { planRuleInstall } from "./rules/install/plan.js";
+export { planSkillInstall } from "./skills/install/plan.js";
+export { planSubagentInstall } from "./subagents/install/plan.js";
+export { BUNDLED_AXM_SKILL_AUTHORED_BLOCKER, BundledAxmSkillAsset, bundledAxmSkillCanonicalPath, inspectBundledAxmSkillReadiness, installBundledAxmSkill, type BundledAxmSkillAssetService, type BundledAxmSkillReadiness, type BundledAxmSkillSourceFile, } from "./skills/install/bundled.js";
+export { buildAtomicPackGraphStep, validatePackGraphPostcondition, type AtomicPackGraphChild, } from "./packs/graph-transition.js";
+export { buildPackMemberInstallStep, type PackMemberRef } from "./packs/member-install-step.js";
+export { configuredPackConstraintBlockPlan, prospectivePackConstraintProblems, relevantPackConstraintProblems, } from "./packs/constraint-gate.js";
+export { UninstallExtensions, prepareUninstallExtensions, previewOrApplyUninstallExtensions, type PrepareUninstallRequirements, type UninstallExtensionsCandidate, type UninstallExtensionsFailure, type UninstallExtensionsRequest, } from "./uninstall/uninstall-extensions.js";
+export { resolveRootUninstallIntent, rootUninstallableTypeSegments, type RootUninstallIntent, type RootUninstallableType, } from "./uninstall/root-intent.js";
+export { exclusiveMemberRetentionPolicy, makeWorkspaceRetentionPolicy, } from "./uninstall/retention-policy.js";
+export { PACK_UNINSTALL_GRAPH_BLOCKER_ID, packUninstallRecoveryIdentifiers, planPackUninstallGraphReadiness, type PackRetirement, type PackUninstallGraphReadiness, } from "./packs/uninstall/readiness.js";
+export { type PackUninstallIntent, type PackUninstallRequirements, type ResolvedPackUninstallTarget, } from "./packs/uninstall/plan.js";
 export { getSkillDisplayName } from "./skills/utils.js";
-export { computeSkillSourceHash, gitHostedSkillArtifactSource, installSkill, type InstallSkillOperation, type InstallSkillOperationArgs, } from "./skills/operations/install.js";
+export { gitHostedSkillArtifactSource, installSkill, type InstallSkillOperation, type InstallSkillOperationArgs, } from "./skills/operations/install.js";
 export type { InstallResult } from "./skills/operations/install-result.js";
 export { enableSkill, type EnableSkillOperation } from "./skills/operations/enable.js";
 export { disableSkill, type DisableSkillOperation } from "./skills/operations/disable.js";
-export { collectSecretInputNames, deleteMcpSecrets, installMcpServer, mcpSecretAccount, readMcpServerManifest, type InstallMcpServerOperation, type InstallMcpServerOperationArgs, } from "./mcps/operations/install.js";
 export { uninstallMcpServer, type UninstallMcpServerOperation, type UninstallMcpServerOperationArgs, } from "./mcps/operations/uninstall.js";
 export { enableMcpServer, type EnableMcpServerOperation } from "./mcps/operations/enable.js";
 export { disableMcpServer, type DisableMcpServerOperation } from "./mcps/operations/disable.js";
-export { mcpServerArtifact, mcpSettingsTarget, mcpSourceTarget, } from "./mcps/operations/artifact.js";
 export { SUBAGENT_CONFIG_SURFACE, renderedSubagentTargets, subagentConfigTarget, subagentLifecycleArtifact, } from "./subagents/operations/artifact.js";
 export { enableSubagent, type EnableSubagentOperation } from "./subagents/operations/enable.js";
 export { disableSubagent, type DisableSubagentOperation } from "./subagents/operations/disable.js";
+export { WORKSPACE_UPDATE_ATOMICITY, WORKSPACE_UPDATE_EXECUTION_CAPABILITIES, } from "./update/atomicity.js";
 export { expandPackInstallRefs, expandPackInstallRefsWithReleaseAge, type ReleaseAgeAwarePackExpansion, } from "./packs/expansion.js";
-export { resolvePackDependenciesWithReleaseAge, type PackDependencyRefResolver, type ReleaseAgeAwarePackDependencyResolution, type WorkspacePackDependencyResolution, type WorkspacePackDependencyResolver, } from "./packs/dependency-resolution.js";
-export { ResolvedPackDependencyMapSchema, ResolvedPackDependencySchema, validateExactPackDependencyVersions, type ResolvedPackDependency, type ResolvedPackDependencyMap, } from "./packs/resolved-dependency.js";
+export { validateExactPackDependencyVersions } from "./packs/resolved-dependency.js";
 export { installPack, type InstallPackOperation, type InstallPackOperationArgs, } from "./packs/operations/install.js";
+export { lifecycleStepFailure, type LifecycleStepFailure } from "./step-failure.js";
+export { UpdateExtensions, prepareUpdate, previewOrApplyUpdate, contextForResolution, type BlockedUpdateCandidate, type ConfiguredUpdateRequest, type NothingConfiguredUpdateCandidate, type PlannedUpdateCandidate, type PrepareUpdateRequirements, type PreservedUpdateCandidate, type TargetedUpdateRequest, type UpdateCandidate, type UpdateFailure, type UpdateRequest, type UpdateRequirements, type UpdateSubjectType, } from "./update/update-extensions.js";
+export { UPDATE_NAME_FILTER_FLAG, type ConfiguredUpdateSelection, type ConfiguredUpdateSelector, type ConfiguredUpdateSelectorType, } from "./update/selector.js";
+export { resolveRootUpdateIntent, rootUpdatableTypeSegments, RootUpdatableTypeSegmentSchema, type RootUpdatableType, type RootUpdatableTypeSegment, type RootUpdateIntent, } from "./update/root-request.js";
+export { TARGETED_UPDATE_STALE_DETAIL } from "./update/targeted-plan.js";
+export { SelectiveUpdate, prepareSelectiveUpdate, type SelectiveUpdateRequest, } from "./update/selective/use-case.js";
+export { previewOrApplySelectiveUpdate, selectiveUpdatePlanName, type NothingSelectiveUpdateCandidate, type PlannedSelectiveUpdateCandidate, type SelectiveUpdateCandidate, type SelectiveUpdateSubjectType, } from "./update/selective/vocabulary.js";
+export type { SelectiveUpdateNothingReason } from "./update/selective/selection.js";
+export type { SelectiveSkillUpdateRequest } from "./update/selective/skills.js";
+export type { SelectiveSubagentUpdateRequest } from "./update/selective/subagents.js";
+export type { SelectiveUpdateStepRequirements } from "./update/selective/requirements.js";
+export { makeWorkspaceUpdatePlan, type ConfiguredUpdateFailure, type WorkspaceUpdatableType, type WorkspaceUpdatePlanRequest, type WorkspaceUpdatePlanResult, } from "./update/configured.js";
+export { PromoteAuthoredPack, preparePromoteAuthoredPack, previewOrApplyPromoteAuthoredPack, type PreparePromoteAuthoredPackRequirements, type PromoteAuthoredPackCandidate, type PromoteAuthoredPackFailure, type PromoteAuthoredPackRequest, type PromoteAuthoredPackRequirements, type PromotedPackMember, } from "./packs/promote-authored-pack.js";
+export { DEMOTE_RISK_CONDITION_ID, DemoteToExternalSource, prepareDemote, previewOrApplyDemote, type DemoteCandidate, type DemoteFailure, type DemoteRequest, type DemoteRequirements, type PrepareDemoteRequirements, } from "./demote/demote-to-external-source.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -1,41 +1,84 @@
 /**
  * Extension-lifecycle feature: install, update, uninstall, enable, and
  * disable policy across root and type-specific command forms — configured
- * entry resolution, the shared install/uninstall command workflows, and the
- * per-type lifecycle operations. The environment-backed per-type manager
+ * entry resolution, the install and uninstall use cases every command
+ * spelling routes through, and the per-type lifecycle operations. The environment-backed per-type manager
  * layers live behind `./live`.
  *
  * @experimental All exports from this module are unstable and may change without notice.
  * @packageDocumentation
  */
 export { ExtensionLifecycleFailed } from "./errors.js";
-export { ReleaseAgePosture } from "./release-age-posture.js";
-export { LifecycleFailureAdapter, withAdaptedStepFailures, } from "./failure-adapter.js";
-export { makeConfiguredReleaseAgeEvaluation, resolveConfiguredHook, resolveConfiguredKnowledge, resolveConfiguredMcpServer, resolveConfiguredPack, resolveConfiguredRegistryEntry, resolveConfiguredRule, resolveConfiguredSkill, resolveConfiguredSubagent, } from "./configured-entry-resolution.js";
-export { CONFIGURED_ENTRY_RESOLUTION_TIMEOUT, withConfiguredEntryResolutionTimeout, } from "./resolution-timeout.js";
-export { PUBLISHER_CHANGE_CONDITION_ID, classifyPublisherBindingTransition, publisherChangeRiskCondition, publisherTransitionWarning, registryBindingProposal, withPublisherTrust, withPublisherTrustConditions, } from "./publisher-binding.js";
-export { buildInstallCommandPlan, runInstallCommandWorkflow, } from "./workflows/install-command/workflow.js";
-export { runUninstallCommandWorkflow, } from "./workflows/uninstall-command/workflow.js";
-export { materializeRegistryPackage, materializeRegistryPackageWithTreeIntegrity, } from "./registry-materialization.js";
+export { StepFailureConversion, withAdaptedStepFailures, } from "./step-failure-conversion.js";
+// Activation: enable and disable for every extension type, as one use case.
+export { prepareSetActivation, previewOrApplySetActivation, SetActivation, } from "./activation/set-activation.js";
+export { PUBLISHER_CHANGE_CONDITION_ID, publisherChangeRiskCondition, withPublisherTrust, withPublisherTrustConditions, } from "./publisher-binding.js";
+// Install: acquiring extensions a request names, or the ones the workspace
+// already declares, as one use case behind every command spelling.
+export { InstallExtensions, prepareInstallExtensions, previewOrApplyInstallExtensions, } from "./install/install-extensions.js";
+export { installRefused, } from "./install/vocabulary.js";
+export { ExtensionSelectionCancelled, ExtensionSelectionInteraction, } from "./install/selection-interaction.js";
+export { resolveRootInstallIntent, rootInstallableTypeSegments, RootInstallableTypeSegmentSchema, } from "./install/root-intent.js";
+export { installCommandFor, perTypeInstallPluralSegments } from "./install/per-type-install.js";
+export { buildConfiguredInstallPlan, buildConfiguredPackInstallPlan, } from "./install/configured.js";
+export { buildAggregateProjectionStep } from "./install/aggregate-projection-step.js";
+export { inlineMcpNotApplicablePlan } from "./install/inline-mcp-operation.js";
+export { formatRegistryProbe, } from "./install/registry-source-resolution.js";
+// The per-type install planners every install and update route shares.
+export { planHookInstall } from "./hooks/install/plan.js";
+export { planKnowledgeInstall } from "./knowledge/install/plan.js";
+export { parseMcpEnvInputs, planMcpServerInstall } from "./mcps/install/plan.js";
+export { planPackInstall } from "./packs/install/plan.js";
+export { planRuleInstall } from "./rules/install/plan.js";
+export { planSkillInstall } from "./skills/install/plan.js";
+export { planSubagentInstall } from "./subagents/install/plan.js";
+// The bundled official AXM skill, and the asset port the application fills.
+export { BUNDLED_AXM_SKILL_AUTHORED_BLOCKER, BundledAxmSkillAsset, bundledAxmSkillCanonicalPath, inspectBundledAxmSkillReadiness, installBundledAxmSkill, } from "./skills/install/bundled.js";
+// Pack graph transitions: the atomic step and its desired-state predicate.
+export { buildAtomicPackGraphStep, validatePackGraphPostcondition, } from "./packs/graph-transition.js";
+export { buildPackMemberInstallStep } from "./packs/member-install-step.js";
+export { configuredPackConstraintBlockPlan, prospectivePackConstraintProblems, relevantPackConstraintProblems, } from "./packs/constraint-gate.js";
+// Uninstall: withdrawing extensions, as one use case behind every spelling.
+export { UninstallExtensions, prepareUninstallExtensions, previewOrApplyUninstallExtensions, } from "./uninstall/uninstall-extensions.js";
+export { resolveRootUninstallIntent, rootUninstallableTypeSegments, } from "./uninstall/root-intent.js";
+export { exclusiveMemberRetentionPolicy, makeWorkspaceRetentionPolicy, } from "./uninstall/retention-policy.js";
+export { PACK_UNINSTALL_GRAPH_BLOCKER_ID, packUninstallRecoveryIdentifiers, planPackUninstallGraphReadiness, } from "./packs/uninstall/readiness.js";
+export {} from "./packs/uninstall/plan.js";
 // Skill lifecycle operations
-export { ensureSkillAgentArtifact, removeSkillAgentArtifact } from "./skills/materialization.js";
 export { getSkillDisplayName } from "./skills/utils.js";
-export { computeSkillSourceHash, gitHostedSkillArtifactSource, installSkill, } from "./skills/operations/install.js";
+export { gitHostedSkillArtifactSource, installSkill, } from "./skills/operations/install.js";
 export { enableSkill } from "./skills/operations/enable.js";
 export { disableSkill } from "./skills/operations/disable.js";
-// MCP server lifecycle operations
-export { collectSecretInputNames, deleteMcpSecrets, installMcpServer, mcpSecretAccount, readMcpServerManifest, } from "./mcps/operations/install.js";
+// MCP server lifecycle operations. Installation itself is a materialization
+// capability (`@agentxm/extension-materialization`) because the authoring
+// routes need it too and a feature may not import a peer feature.
 export { uninstallMcpServer, } from "./mcps/operations/uninstall.js";
 export { enableMcpServer } from "./mcps/operations/enable.js";
 export { disableMcpServer } from "./mcps/operations/disable.js";
-export { mcpServerArtifact, mcpSettingsTarget, mcpSourceTarget, } from "./mcps/operations/artifact.js";
 // Subagent lifecycle operations
 export { SUBAGENT_CONFIG_SURFACE, renderedSubagentTargets, subagentConfigTarget, subagentLifecycleArtifact, } from "./subagents/operations/artifact.js";
 export { enableSubagent } from "./subagents/operations/enable.js";
 export { disableSubagent } from "./subagents/operations/disable.js";
+// Update: the atomicity a workspace-wide sweep declares.
+export { WORKSPACE_UPDATE_ATOMICITY, WORKSPACE_UPDATE_EXECUTION_CAPABILITIES, } from "./update/atomicity.js";
 // Pack lifecycle operations
 export { expandPackInstallRefs, expandPackInstallRefsWithReleaseAge, } from "./packs/expansion.js";
-export { resolvePackDependenciesWithReleaseAge, } from "./packs/dependency-resolution.js";
-export { ResolvedPackDependencyMapSchema, ResolvedPackDependencySchema, validateExactPackDependencyVersions, } from "./packs/resolved-dependency.js";
+export { validateExactPackDependencyVersions } from "./packs/resolved-dependency.js";
 export { installPack, } from "./packs/operations/install.js";
+// How a lifecycle closure serializes its own failures into a plan step.
+export { lifecycleStepFailure } from "./step-failure.js";
+// Update: advancing what the workspace already accepted, for a named
+// extension or for the configured entries as a whole.
+export { UpdateExtensions, prepareUpdate, previewOrApplyUpdate, contextForResolution, } from "./update/update-extensions.js";
+export { UPDATE_NAME_FILTER_FLAG, } from "./update/selector.js";
+export { resolveRootUpdateIntent, rootUpdatableTypeSegments, RootUpdatableTypeSegmentSchema, } from "./update/root-request.js";
+export { TARGETED_UPDATE_STALE_DETAIL } from "./update/targeted-plan.js";
+// Update: advancing the entries a person selected by name or by source.
+export { SelectiveUpdate, prepareSelectiveUpdate, } from "./update/selective/use-case.js";
+export { previewOrApplySelectiveUpdate, selectiveUpdatePlanName, } from "./update/selective/vocabulary.js";
+export { makeWorkspaceUpdatePlan, } from "./update/configured.js";
+// Unpack: promoting a Pack's members to direct declarations.
+export { PromoteAuthoredPack, preparePromoteAuthoredPack, previewOrApplyPromoteAuthoredPack, } from "./packs/promote-authored-pack.js";
+// Demote: returning a workspace-authored package to an external source.
+export { DEMOTE_RISK_CONDITION_ID, DemoteToExternalSource, prepareDemote, previewOrApplyDemote, } from "./demote/demote-to-external-source.js";
 //# sourceMappingURL=index.js.map

package/dist/src/install/aggregate-projection-step.d.ts

@@ -0,0 +1,16 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import type { ExtensionType } from "@agentxm/extension-model/unstable/extensions";
+import type { PlannedJobStep } from "@agentxm/workspace-operations";
+import { HookManager, KnowledgeManager, RuleManager } from "@agentxm/extension-materialization";
+import type { InstallStepRequirements } from "./vocabulary.js";
+/**
+ * One trailing projection write per semantic closure. Member steps commit
+ * canonical, settings, and lock state without touching shared aggregate units;
+ * this step then renders each affected unit exactly once from the complete
+ * desired-state contributor set.
+ */
+export declare const buildAggregateProjectionStep: (args: {
+    readonly types: ReadonlySet<ExtensionType>;
+}) => Effect.Effect<Option.Option<PlannedJobStep<InstallStepRequirements>>, never, HookManager | KnowledgeManager | RuleManager>;
+//# sourceMappingURL=aggregate-projection-step.d.ts.map

package/dist/src/install/aggregate-projection-step.js

@@ -0,0 +1,49 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { HookManager, KnowledgeManager, RuleManager, } from "@agentxm/extension-materialization";
+import { applyProjectionPlans, projectionPlanExclusionWarnings, } from "@agentxm/workspace-projection";
+import { lifecycleStepFailure } from "../step-failure.js";
+/**
+ * One trailing projection write per semantic closure. Member steps commit
+ * canonical, settings, and lock state without touching shared aggregate units;
+ * this step then renders each affected unit exactly once from the complete
+ * desired-state contributor set.
+ */
+export const buildAggregateProjectionStep = (args) => Effect.gen(function* () {
+    if (!args.types.has("rule") && !args.types.has("hook") && !args.types.has("knowledge")) {
+        return Option.none();
+    }
+    const ruleManager = args.types.has("rule")
+        ? Option.some(yield* RuleManager)
+        : Option.none();
+    const hookManager = args.types.has("hook")
+        ? Option.some(yield* HookManager)
+        : Option.none();
+    const knowledgeManager = args.types.has("knowledge")
+        ? Option.some(yield* KnowledgeManager)
+        : Option.none();
+    return Option.some({
+        key: "projection:aggregate-units",
+        label: "instruction files",
+        readiness: "ready",
+        run: Effect.gen(function* () {
+            const plans = [];
+            if (Option.isSome(ruleManager)) {
+                plans.push(...(yield* ruleManager.value.projectionPlans()));
+            }
+            if (Option.isSome(hookManager)) {
+                plans.push(...(yield* hookManager.value.projectionPlans()));
+            }
+            if (Option.isSome(knowledgeManager)) {
+                plans.push(...(yield* knowledgeManager.value.projectionPlans()));
+            }
+            yield* applyProjectionPlans(plans);
+            return projectionPlanExclusionWarnings(plans);
+        }).pipe(Effect.mapError(lifecycleStepFailure), Effect.map((warnings) => ({
+            result: "success",
+            message: "Rendered shared aggregate units from the complete contributor set",
+            ...(warnings.length === 0 ? {} : { warnings }),
+        }))),
+    });
+});
+//# sourceMappingURL=aggregate-projection-step.js.map