@agentxm/extension-lifecycle 0.28.11 → 0.28.13

package/dist/src/update/selector.js

@@ -0,0 +1,120 @@
+/**
+ * Resolving what a `<type> update` selector names.
+ *
+ * A person narrows a configured sweep two ways: a positional that may be an
+ * installed name or a source, and repeated `--name` filters that may be exact
+ * names or globs. Deciding which configured entries those name is update's
+ * own question — it re-reads the configured entries, re-resolves their
+ * declared sources, and compares origins — so it is settled here, beside the
+ * sweep it narrows, rather than by whichever surface parsed the flags.
+ *
+ * A selector that matches nothing is a settled answer, not a failure: the
+ * sweep reports it as nothing to advance, in the same shape as a workspace
+ * with nothing configured.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { extensionTypeSentenceLabels, extensionTypePluralSentenceLabels, parseSourceQualifiedRegistrySourcePatternParts, toExtensionTypePlural, } from "@agentxm/extension-model/unstable/extensions";
+import { isCatalogExtensionType } from "@agentxm/extension-model/unstable/extension-types";
+import { SourceHostProviders, resolveInstalledIdentifierNameOrInput, resolveSource, } from "@agentxm/extension-sources";
+import { WorkspaceRecords, configuredRowsByName, enabledConfiguredEntries, } from "@agentxm/workspace-state";
+import { expandGlobs } from "../glob.js";
+/** The flag spelling reported when a `--name` filter matches nothing. */
+export const UPDATE_NAME_FILTER_FLAG = "--name";
+const sourceMatchesEntrySource = (sourceValue, entrySource) => Effect.gen(function* () {
+    if (entrySource === undefined)
+        return false;
+    const requestedRegistry = parseSourceQualifiedRegistrySourcePatternParts(sourceValue);
+    const configuredRegistry = parseSourceQualifiedRegistrySourcePatternParts(entrySource);
+    if (requestedRegistry !== undefined || configuredRegistry !== undefined) {
+        return (requestedRegistry !== undefined &&
+            configuredRegistry !== undefined &&
+            requestedRegistry.sourceName === configuredRegistry.sourceName &&
+            requestedRegistry.owner === configuredRegistry.owner &&
+            requestedRegistry.type === configuredRegistry.type &&
+            requestedRegistry.name === configuredRegistry.name);
+    }
+    const sources = yield* SourceHostProviders;
+    const sourceArgResult = yield* Effect.result(resolveSource(sourceValue));
+    if (sourceArgResult._tag === "Failure") {
+        return false;
+    }
+    const entrySourceResult = yield* Effect.result(resolveSource(entrySource));
+    if (entrySourceResult._tag === "Failure") {
+        return false;
+    }
+    return sources.origin(entrySourceResult.success) === sources.origin(sourceArgResult.success);
+});
+const filterBySource = (entries, sourceValue, sourceMayMatchName) => Effect.gen(function* () {
+    const nameMatchedEntries = sourceMayMatchName
+        ? entries.filter(([name]) => name === sourceValue)
+        : [];
+    if (nameMatchedEntries.length > 0) {
+        return nameMatchedEntries;
+    }
+    const sourceMatches = yield* Effect.forEach(entries, (entry) => Effect.map(sourceMatchesEntrySource(sourceValue, entry[1]), (matches) => matches ? Option.some(entry) : Option.none()), { concurrency: "unbounded" });
+    return sourceMatches.filter(Option.isSome).map((match) => match.value);
+});
+const filterByNameFilters = (entries, nameFilters, resourceType) => Effect.gen(function* () {
+    if (nameFilters.length === 0) {
+        return entries;
+    }
+    // A container has no per-type lock map of its own, so a bare name cannot
+    // be resolved to an installed identifier for it; the filter then matches
+    // the spelling the person gave, which is what identifier resolution
+    // returns for an unresolvable name anyway.
+    const resolvedNameFilters = yield* Effect.forEach(nameFilters, (name) => name.includes("*") || !isCatalogExtensionType(resourceType)
+        ? Effect.succeed(name)
+        : resolveInstalledIdentifierNameOrInput({
+            input: name,
+            resourceType,
+        }));
+    const allNames = entries.map(([name]) => name);
+    const matchedNames = expandGlobs(resolvedNameFilters, allNames);
+    const matchedSet = new Set(matchedNames);
+    return entries.filter(([name]) => matchedSet.has(name));
+});
+/**
+ * Resolve a selector against the type's configured, enabled entries.
+ *
+ * Returns `All` when no selector was given, so a workspace with nothing
+ * configured still reports through the sweep's own "no configured …" message
+ * rather than a selector no-op.
+ */
+export const resolveConfiguredUpdateSelection = Effect.fn("UpdateExtensions.resolveSelection")(function* (selector) {
+    if (Option.isNone(selector.source) && selector.nameFilters.length === 0) {
+        return { _tag: "All" };
+    }
+    const records = yield* WorkspaceRecords;
+    const configured = yield* records
+        .rows(selector.resourceType)
+        .pipe(Effect.map(configuredRowsByName));
+    const entries = enabledConfiguredEntries(configured).map(([name, entry]) => [name, entry.source]);
+    const sourceValue = Option.getOrUndefined(selector.source);
+    const sourceMayMatchName = selector.sourceMayMatchName ?? true;
+    const sourceFiltered = sourceValue === undefined
+        ? entries
+        : yield* filterBySource(entries, sourceValue, sourceMayMatchName);
+    if (sourceValue !== undefined && sourceFiltered.length === 0) {
+        const label = extensionTypeSentenceLabels[selector.resourceType];
+        return {
+            _tag: "NoMatch",
+            message: `No installed ${label} matched "${sourceValue}"${sourceMayMatchName ? " as a name or source" : " as a source"}.`,
+        };
+    }
+    const nameFiltered = yield* filterByNameFilters(sourceFiltered, selector.nameFilters, selector.resourceType);
+    if (selector.nameFilters.length > 0 && nameFiltered.length === 0) {
+        const pluralLabel = extensionTypePluralSentenceLabels[toExtensionTypePlural(selector.resourceType)];
+        return {
+            _tag: "NoMatch",
+            message: `No installed ${pluralLabel} match the ${UPDATE_NAME_FILTER_FLAG} filter.`,
+        };
+    }
+    return {
+        _tag: "Names",
+        names: nameFiltered.map(([name]) => name),
+    };
+});
+//# sourceMappingURL=selector.js.map

package/dist/src/update/targeted-plan.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Wrapping a targeted update in one atomic ownership transition.
+ *
+ * A targeted update moves a declaration whose ownership the workspace already
+ * settled. Between settling that ownership and applying the advance, the
+ * workspace could change underneath: a Pack could be installed, removed, or
+ * re-accepted, or the direct declaration could gain or lose a constraint. So
+ * the step rechecks the ownership fingerprint under the transition before it
+ * writes anything, and validates the ownership it must leave behind before it
+ * commits. A context that moved resolves as a stale candidate — a blocked
+ * outcome a person reruns — rather than as an error, because nothing is wrong
+ * except that the answer is out of date.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import type * as Path from "effect/Path";
+import type * as FileSystem from "effect/FileSystem";
+import { type Plan } from "@agentxm/workspace-operations";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import type { WorkspaceTransactionScope } from "@agentxm/workspace-transactions";
+import { type TargetedUpdateContext, type TargetedUpdateContextFailure } from "@agentxm/extension-resolution";
+import type { InstallStepRequirements } from "../install/vocabulary.js";
+export declare const TARGETED_UPDATE_STALE_DETAIL = "The targeted update ownership context became stale before apply.";
+export declare const wrapTargetedUpdatePlan: (args: {
+    readonly plan: Plan<InstallStepRequirements>;
+    readonly context: TargetedUpdateContext;
+    readonly explicitRange?: string;
+}) => Effect.Effect<Plan<InstallStepRequirements>, TargetedUpdateContextFailure, WorkspaceMutations | WorkspaceTransactionScope | FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=targeted-plan.d.ts.map

package/dist/src/update/targeted-plan.js

@@ -0,0 +1,113 @@
+/**
+ * Wrapping a targeted update in one atomic ownership transition.
+ *
+ * A targeted update moves a declaration whose ownership the workspace already
+ * settled. Between settling that ownership and applying the advance, the
+ * workspace could change underneath: a Pack could be installed, removed, or
+ * re-accepted, or the direct declaration could gain or lose a constraint. So
+ * the step rechecks the ownership fingerprint under the transition before it
+ * writes anything, and validates the ownership it must leave behind before it
+ * commits. A context that moved resolves as a stale candidate — a blocked
+ * outcome a person reruns — rather than as an error, because nothing is wrong
+ * except that the answer is out of date.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { operationPresentation, } from "@agentxm/workspace-operations";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { resolveTargetedUpdateContext, } from "@agentxm/extension-resolution";
+import { ExtensionLifecycleFailed } from "../errors.js";
+import { buildAtomicPackGraphStep } from "../packs/graph-transition.js";
+export const TARGETED_UPDATE_STALE_DETAIL = "The targeted update ownership context became stale before apply.";
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const validatePostcondition = (args) => {
+    if (args.explicitRange === undefined) {
+        return args.actual.fingerprint === args.expected.fingerprint
+            ? Effect.void
+            : Effect.fail(new ExtensionLifecycleFailed({
+                category: "internal",
+                detail: "Targeted update changed desired ownership or owning pack evidence",
+            }));
+    }
+    const expectedPublic = args.expected.public;
+    const actualPublic = args.actual.public;
+    const preserved = actualPublic.blocker === undefined &&
+        actualPublic.ownership === expectedPublic.ownership &&
+        actualPublic.activation === expectedPublic.activation &&
+        actualPublic.authority === expectedPublic.authority &&
+        actualPublic.direct?.source === expectedPublic.direct?.source &&
+        actualPublic.direct?.enabled === expectedPublic.direct?.enabled &&
+        actualPublic.direct?.constraint === args.explicitRange &&
+        actualPublic.effectiveConstraint === expectedPublic.effectiveConstraint &&
+        same(actualPublic.packs, expectedPublic.packs) &&
+        same(actualPublic.memberClosure, expectedPublic.memberClosure) &&
+        args.actual.packEvidenceFingerprint === args.expected.packEvidenceFingerprint;
+    return preserved
+        ? Effect.void
+        : Effect.fail(new ExtensionLifecycleFailed({
+            category: "internal",
+            detail: "Targeted update did not preserve its desired ownership postcondition",
+        }));
+};
+export const wrapTargetedUpdatePlan = (args) => Effect.gen(function* () {
+    const workspace = yield* WorkspaceMutations;
+    const children = args.plan.jobs.flatMap((job) => job.steps.map((step) => ({
+        step,
+        coverage: args.context.public.target.type === "knowledge" ? "ineligible" : "eligible",
+    })));
+    const firstArtifact = children.find((child) => child.step.artifact !== undefined)?.step
+        .artifact;
+    const artifact = firstArtifact ?? {
+        path: args.context.public.target.fqn,
+        scope: workspace.scope,
+        change: "updated",
+    };
+    const builtStep = yield* buildAtomicPackGraphStep({
+        label: args.context.public.target.fqn,
+        message: `Updated ${args.context.public.target.fqn}`,
+        artifact,
+        children,
+        reportUnchangedWhenChildrenUnchanged: true,
+        preTransition: resolveTargetedUpdateContext({
+            target: args.context.public.target,
+            ...(args.explicitRange === undefined ? {} : { explicitRange: args.explicitRange }),
+        }).pipe(Effect.flatMap((fresh) => fresh.fingerprint === args.context.fingerprint
+            ? Effect.void
+            : Effect.fail(new ExtensionLifecycleFailed({
+                category: "conflict",
+                detail: TARGETED_UPDATE_STALE_DETAIL,
+            })))),
+        validate: resolveTargetedUpdateContext({
+            target: args.context.public.target,
+            ...(args.explicitRange === undefined ? {} : { explicitRange: args.explicitRange }),
+        }).pipe(Effect.flatMap((actual) => validatePostcondition({
+            expected: args.context,
+            actual,
+            ...(args.explicitRange === undefined ? {} : { explicitRange: args.explicitRange }),
+        }))),
+    });
+    // Ownership-context staleness resolves as typed blocking rather than as a
+    // step failure, so the operation terminates blocked/stale-candidate.
+    const graphStep = builtStep.readiness === "error"
+        ? builtStep
+        : {
+            ...builtStep,
+            run: builtStep.run.pipe(Effect.catch((error) => error.category === "conflict" && error.detail === TARGETED_UPDATE_STALE_DETAIL
+                ? Effect.succeed({
+                    result: "error",
+                    message: TARGETED_UPDATE_STALE_DETAIL,
+                    error,
+                    blocking: { class: "stale-candidate" },
+                })
+                : Effect.fail(error))),
+        };
+    return {
+        ...args.plan,
+        name: `Update ${args.context.public.target.fqn}`,
+        description: args.plan.description,
+        presentation: operationPresentation({ imperative: "update", past: "Updated", gerund: "Updating" }, args.context.public.target.type),
+        jobs: [{ concurrency: 1, steps: [graphStep] }],
+    };
+});
+//# sourceMappingURL=targeted-plan.js.map

package/dist/src/update/update-extensions.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Advancing what the workspace already accepted.
+ *
+ * Update is one use case with two shapes of request. A person can name one
+ * extension by its Registry identity, or ask the workspace to sweep every
+ * configured entry — optionally narrowed to one type, or to a selection of
+ * installed names. Both shapes answer the same question: within the intent
+ * the workspace recorded, is there a newer version its source is willing to
+ * offer, and may this workspace accept it?
+ *
+ * Everything that decides the answer lives here. A named update is classified
+ * against the desired graph first, so a refusal is reported before any
+ * Registry is contacted: an extension the workspace never asked for is not
+ * installed on its behalf, a Pack-owned member is not forked into direct
+ * intent, and a bundled or workspace-authored source is never replaced from
+ * the Registry. A sweep resolves each configured entry independently, so one
+ * unreachable source blocks one unit rather than the operation.
+ *
+ * `prepare` settles all of it and writes nothing: it produces either a frozen
+ * execution candidate or the settled reason there is nothing to execute.
+ * `previewOrApply` resolves that same candidate, so the preview a person
+ * reads and the apply that follows describe one decision.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import type * as Path from "effect/Path";
+import type * as Scope from "effect/Scope";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import { HookManager, KnowledgeManager, McpServerManager, PackManager, RuleManager, SkillManager, SubagentManager } from "@agentxm/extension-materialization";
+import { ReleaseAgePosture, type ExtensionResolutionFailed, type ReleaseAgeOperationEvidence, type TargetedUpdateContext, type TargetedUpdatePublicContext } from "@agentxm/extension-resolution";
+import { SourceHostProviders, WorkspaceCatalog, type SourceResolutionFailure } from "@agentxm/extension-sources";
+import { type CandidateFingerprintFailed, type ExecutionCandidate, type OperationResolution, type PlanExecution } from "@agentxm/workspace-operations";
+import { WorkspaceRecords, type AcceptedCanonicalRefError, type ConfiguredAgentOutcomesProvider, type LockfileValidationError } from "@agentxm/workspace-state";
+import type { WorkspaceTransactionScope } from "@agentxm/workspace-transactions";
+import { ExtensionLifecycleFailed } from "../errors.js";
+import type { InstallStepRequirements } from "../install/vocabulary.js";
+import type { StepFailureConversion } from "../step-failure-conversion.js";
+import { blockerClass } from "./blockers.js";
+import { type WorkspaceUpdatableType } from "./configured.js";
+import { type ConfiguredUpdateSelector } from "./selector.js";
+/** Advance one extension the person named by its Registry identity. */
+export interface TargetedUpdateRequest {
+    readonly kind: "targeted";
+    /** The Registry FQN, optionally carrying a version range. */
+    readonly source: string;
+    /** Whether prompts may be asked while the plan is built. */
+    readonly nonInteractive: boolean;
+}
+/** Sweep the configured entries, optionally narrowed by type and selection. */
+export interface ConfiguredUpdateRequest {
+    readonly kind: "configured";
+    /** Restrict the sweep to one extension type. */
+    readonly type: Option.Option<WorkspaceUpdatableType>;
+    /**
+     * A selector to resolve against the type's configured entries; omit to
+     * sweep every entry. Resolving it is part of settling the request, so a
+     * selector that matches nothing settles as nothing to advance.
+     */
+    readonly selector?: ConfiguredUpdateSelector;
+    readonly planName: string;
+    readonly planDescription: Option.Option<string>;
+    readonly nonInteractive: boolean;
+}
+/** Everything `axm update` and every `<type> update` can ask for. */
+export type UpdateRequest = TargetedUpdateRequest | ConfiguredUpdateRequest;
+/** What every step in an update may require when it runs. */
+export type UpdateRequirements = InstallStepRequirements;
+/** The seven manager services a planned update may reach for. */
+type UpdateManagers = SkillManager | SubagentManager | RuleManager | HookManager | KnowledgeManager | McpServerManager | PackManager;
+/** What an update outcome is about: one extension type, or several. */
+export type UpdateSubjectType = WorkspaceUpdatableType | "mixed";
+/** A settled update that has work to execute. */
+export interface PlannedUpdateCandidate {
+    readonly outcome: "planned";
+    /** The type this advance is about, or `mixed` when a sweep spans types. */
+    readonly subjectType: UpdateSubjectType;
+    readonly execution: ExecutionCandidate<UpdateRequirements>;
+    /**
+     * The installed names a sweep's selector resolved to; absent when the sweep
+     * was not narrowed. A rerun that must reproduce this exact settlement names
+     * these rather than the selector that found them.
+     */
+    readonly selectedNames?: ReadonlyArray<string>;
+    /** Release-age evidence resolution collected before the plan existed. */
+    readonly releaseAge?: ReleaseAgeOperationEvidence;
+    /** The ownership context a targeted update was classified against. */
+    readonly targetedContext?: TargetedUpdatePublicContext;
+    readonly fingerprintedContext?: TargetedUpdateContext;
+}
+/** A settled update that is refused, with the fact that refuses it. */
+export interface BlockedUpdateCandidate {
+    readonly outcome: "blocked";
+    readonly name: string;
+    readonly detail: string;
+    readonly subject: string;
+    readonly subjectType: WorkspaceUpdatableType;
+    readonly blockingClass: ReturnType<typeof blockerClass>;
+    /** The classified blocker, which the application renders recovery from. */
+    readonly reference?: string;
+    readonly releaseAge?: ReleaseAgeOperationEvidence;
+    readonly targetedContext?: TargetedUpdatePublicContext;
+}
+/** A settled update whose current version is preserved by release-age policy. */
+export interface PreservedUpdateCandidate {
+    readonly outcome: "preserved";
+    readonly name: string;
+    readonly description: string;
+    readonly subjectType: WorkspaceUpdatableType;
+    readonly releaseAge: ReleaseAgeOperationEvidence;
+    readonly targetedContext?: TargetedUpdatePublicContext;
+}
+/** A settled sweep that found nothing configured to advance. */
+export interface NothingConfiguredUpdateCandidate {
+    readonly outcome: "nothing-configured";
+    readonly message: string;
+    readonly subjectType: UpdateSubjectType;
+    readonly planDescription: Option.Option<string>;
+}
+/**
+ * A settled update: every decision is made and nothing is written. Three of
+ * the four shapes carry no plan because there is nothing to execute — the
+ * reason itself is the outcome.
+ */
+export type UpdateCandidate = PlannedUpdateCandidate | BlockedUpdateCandidate | PreservedUpdateCandidate | NothingConfiguredUpdateCandidate;
+/**
+ * Every failure settling an update can surface before anything is written:
+ * the feature's own refusal and the fingerprint a frozen candidate could not
+ * take; the resolution policy's refusal of a named or configured entry;
+ * whatever routing a declared source locator and reaching its Registry
+ * surfaced; everything reading settings, the lockfile, and the accepted
+ * canonical resolution behind one entry can produce; and the lockfile-health
+ * probe an update consults before it decides anything.
+ */
+export type UpdateFailure = ExtensionLifecycleFailed | CandidateFingerprintFailed | ExtensionResolutionFailed | SourceResolutionFailure | AcceptedCanonicalRefError | LockfileValidationError;
+/** Everything settling an update reads before it freezes a candidate. */
+export type PrepareUpdateRequirements = UpdateRequirements | UpdateManagers | ConfiguredAgentOutcomesProvider | StepFailureConversion | FileSystem.FileSystem | Path.Path | HttpClient.HttpClient | Scope.Scope | ReleaseAgePosture | SourceHostProviders | WorkspaceCatalog | WorkspaceRecords | WorkspaceTransactionScope;
+/**
+ * Settle an update: read the request, decide what may advance, and freeze
+ * either the execution candidate or the reason there is nothing to execute.
+ */
+export declare const prepareUpdate: (request: UpdateRequest) => Effect.Effect<UpdateCandidate, UpdateFailure, PrepareUpdateRequirements>;
+/**
+ * Preview or apply a settled update, resolving to one operation outcome.
+ *
+ * A sweep that found nothing configured has no operation to resolve: the
+ * application reports it as the no-op it is, so this takes only the
+ * candidates that do describe an operation.
+ */
+export declare const previewOrApplyUpdate: (candidate: Exclude<UpdateCandidate, NothingConfiguredUpdateCandidate>, execution: PlanExecution) => Effect.Effect<OperationResolution<never>, import("@agentxm/workspace-state").WorkspaceSettingsReadFailure | import("@agentxm/workspace-operations").ApprovalRecoveryMissing | import("@agentxm/workspace-operations").PlanInteractionFailed | import("@agentxm/workspace-transactions").WorkspaceTransitionAcquireFailure, ConfiguredAgentOutcomesProvider | import("@agentxm/workspace-transactions").FootprintRecorder | import("@agentxm/workspace-operations").OperationJournal | import("@agentxm/workspace-operations").ResolvePlanInteraction | InstallStepRequirements>;
+/**
+ * The ownership context an outcome reports: a stale-candidate outcome says
+ * nothing moved, whatever the classification said before the transition.
+ */
+export declare const contextForResolution: (context: TargetedUpdatePublicContext, resolution: OperationResolution) => TargetedUpdatePublicContext;
+/** The update use case: settle a request, then preview or apply it. */
+export declare const UpdateExtensions: {
+    readonly prepare: (request: UpdateRequest) => Effect.Effect<UpdateCandidate, UpdateFailure, PrepareUpdateRequirements>;
+    readonly previewOrApply: (candidate: Exclude<UpdateCandidate, NothingConfiguredUpdateCandidate>, execution: PlanExecution) => Effect.Effect<OperationResolution<never>, import("@agentxm/workspace-state").WorkspaceSettingsReadFailure | import("@agentxm/workspace-operations").ApprovalRecoveryMissing | import("@agentxm/workspace-operations").PlanInteractionFailed | import("@agentxm/workspace-transactions").WorkspaceTransitionAcquireFailure, ConfiguredAgentOutcomesProvider | import("@agentxm/workspace-transactions").FootprintRecorder | import("@agentxm/workspace-operations").OperationJournal | import("@agentxm/workspace-operations").ResolvePlanInteraction | InstallStepRequirements>;
+};
+export {};
+//# sourceMappingURL=update-extensions.d.ts.map