@agentxm/extension-lifecycle 0.28.11 → 0.28.13

package/dist/src/update/root-request.js

@@ -0,0 +1,117 @@
+/**
+ * The grammar a root `update` request is written in.
+ *
+ * Root update names one extension by its Registry identity and nothing else.
+ * A path, URL, or Git source names a package whose identity the workspace
+ * cannot compare against what it already accepted, and a Library is a curated
+ * collection rather than an installed package, so both are refused here with
+ * the per-type route that does accept them. The refusal carries its own
+ * how-to-fix sentence: what a person should type instead depends on what they
+ * typed, and only this grammar knows that.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { ExtensionLifecycleFailed } from "../errors.js";
+import { installableExtensionTypePluralSegments, InstallableExtensionTypePluralSchema, isInstallableExtensionTypePlural, toInstallableExtensionType, } from "@agentxm/extension-model/unstable/extensions/installable-types";
+import { RegistrySourceRefSchema, } from "@agentxm/extension-model/unstable/extensions";
+import { parseInputPattern } from "@agentxm/extension-model/unstable/sources/parser";
+const decodeRegistrySourceRef = Schema.decodeUnknownEffect(RegistrySourceRefSchema);
+export const rootUpdatableTypeSegments = installableExtensionTypePluralSegments;
+export const RootUpdatableTypeSegmentSchema = InstallableExtensionTypePluralSchema;
+const rootUpdateFqnGrammar = "@<handle>/<plural-type>/<name>[@<version>]";
+const supportedRootUpdateTypes = rootUpdatableTypeSegments.join(", ");
+const rootUpdateRegistryOnlyHowToFix = (source) => {
+    const parsed = parseInputPattern(source);
+    if (Option.isNone(parsed)) {
+        return "Use `axm update @<handle>/<plural-type>/<name>[@<version>]`. For path, URL, or git sources, use `axm skills update <source>` or `axm subagents update <source>` instead.";
+    }
+    switch (parsed.value.pattern.pattern) {
+        case "file-path-pattern":
+        case "url-input":
+        case "git-scp-address":
+        case "shorthand-input":
+        case "slash-pattern":
+            return `Root update only accepts registry FQNs. Use \`axm skills update ${source}\` or \`axm subagents update ${source}\` instead.`;
+        case "name-input":
+        case "glob-input":
+            return `Root update only accepts registry FQNs. Use the matching per-type command instead: \`axm skills update ${source}\` or \`axm subagents update ${source}\`.`;
+        case "registry-pattern-input":
+            return "Use `axm update @<handle>/<plural-type>/<name>[@<version>]`.";
+        case "workspace-pattern-input":
+            return "Workspace-sourced extensions are locally authoritative and are not update targets.";
+    }
+};
+/**
+ * Read one root-update request. Fails with the refusal a person can act on;
+ * succeeds with the Registry identity every later step is decided against.
+ */
+export const resolveRootUpdateIntent = Effect.fn("UpdateExtensions.readRootRequest")(function* (input) {
+    const source = input.trim();
+    const segments = source.split("/");
+    const pluralType = segments.length === 3 ? segments[1] : undefined;
+    if (!source.startsWith("@")) {
+        return yield* new ExtensionLifecycleFailed({
+            category: "usage",
+            detail: "Root update only accepts registry FQNs",
+            suggestions: [{ description: rootUpdateRegistryOnlyHowToFix(source) }],
+        });
+    }
+    if (pluralType === "libraries") {
+        return yield* new ExtensionLifecycleFailed({
+            category: "usage",
+            detail: "Libraries are curated registry collections and cannot be updated",
+            suggestions: [
+                {
+                    description: "Update installed extensions individually; Library membership is viewed in AgentXM.",
+                },
+            ],
+        });
+    }
+    const parsed = yield* decodeRegistrySourceRef(source).pipe(Effect.mapError((error) => {
+        if (pluralType !== undefined && !isInstallableExtensionTypePlural(pluralType)) {
+            return new ExtensionLifecycleFailed({
+                category: "not_found",
+                detail: "Update source uses an unsupported plural type",
+                suggestions: [
+                    {
+                        description: `Use ${rootUpdateFqnGrammar}. Supported plural types: ${supportedRootUpdateTypes}.`,
+                    },
+                ],
+                cause: error,
+            });
+        }
+        return new ExtensionLifecycleFailed({
+            category: "validation",
+            detail: "Update source must be a registry FQN",
+            suggestions: [
+                {
+                    description: `Use ${rootUpdateFqnGrammar} with one of: ${supportedRootUpdateTypes}.`,
+                },
+            ],
+            cause: error,
+        });
+    }));
+    if (!isInstallableExtensionTypePlural(parsed.type)) {
+        return yield* new ExtensionLifecycleFailed({
+            category: "usage",
+            detail: "Root update does not support that extension type",
+            suggestions: [
+                {
+                    description: `Use ${rootUpdateFqnGrammar}. Supported plural types: ${supportedRootUpdateTypes}.`,
+                },
+            ],
+        });
+    }
+    return {
+        source,
+        type: toInstallableExtensionType(parsed.type),
+        owner: parsed.owner,
+        name: parsed.name,
+        versionRange: Option.fromUndefinedOr(parsed.versionRange),
+        target: `${parsed.owner}/${parsed.type}/${parsed.name}`,
+    };
+});
+//# sourceMappingURL=root-request.js.map

package/dist/src/update/selective/plan.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Which selected entries a selective update actually advances.
+ *
+ * Every selected entry has already been re-resolved against its source. This
+ * decides, per entry, whether the resolution differs from the accepted one:
+ * a Git resolution compares tree hashes, a Registry resolution compares
+ * versions and publisher bindings, a local resolution always advances, and an
+ * entry the person forced advances regardless. An entry that matches what is
+ * already accepted is reported as unchanged rather than reinstalled.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import type * as Option from "effect/Option";
+import type { JobStepResult, Plan, StepFailure } from "@agentxm/workspace-operations";
+import type { SkillExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/skill";
+import type { SubagentExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/subagent";
+import type { SkillLockEntry, SubagentLockEntry } from "@agentxm/workspace-state";
+/** The accepted resolution shape both lock maps share for this comparison. */
+type AcceptedEntry = SkillLockEntry | SubagentLockEntry;
+/**
+ * The facts the comparison reads off a resolved ref. Every ref kind either
+ * carries a version, a tree hash, or neither; a workspace-authored ref names
+ * no remote resolution at all and always advances.
+ */
+interface ResolvedRefFacts {
+    readonly refType: SkillExtensionRef["refType"] | SubagentExtensionRef["refType"];
+    readonly version?: string;
+    readonly gitTreeSha?: string;
+}
+/** One entry the plan may advance, with the identity the comparison uses. */
+export interface SelectiveUpdateUnit<TOperation> {
+    readonly name: string;
+    readonly ref: ResolvedRefFacts;
+    readonly force: boolean;
+    readonly operation: TOperation;
+}
+/**
+ * Build the advance plan for one selective update: one unbounded job whose
+ * steps are the selected entries, each either unchanged or dispatched to the
+ * install operation that advances it.
+ */
+export declare const buildSelectiveUpdatePlan: <TOperation, R>(units: ReadonlyArray<SelectiveUpdateUnit<TOperation>>, acceptedResolutions: Readonly<Record<string, AcceptedEntry | undefined>>, name: string, description: Option.Option<string>, makeRunClosure: (operation: TOperation) => Effect.Effect<JobStepResult, StepFailure, R>) => Plan<R>;
+export {};
+//# sourceMappingURL=plan.d.ts.map

package/dist/src/update/selective/plan.js

@@ -0,0 +1,61 @@
+/**
+ * Which selected entries a selective update actually advances.
+ *
+ * Every selected entry has already been re-resolved against its source. This
+ * decides, per entry, whether the resolution differs from the accepted one:
+ * a Git resolution compares tree hashes, a Registry resolution compares
+ * versions and publisher bindings, a local resolution always advances, and an
+ * entry the person forced advances regardless. An entry that matches what is
+ * already accepted is reported as unchanged rather than reinstalled.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+/**
+ * Whether a resolution differs from what the workspace already accepted.
+ */
+const hasChanged = (ref, accepted) => {
+    if (ref.refType === "git-hosted") {
+        return !(accepted.type !== "registry" &&
+            accepted.type !== "local" &&
+            accepted.resolvedTree === ref.gitTreeSha);
+    }
+    if (ref.refType === "registry") {
+        return accepted.type !== "registry" || ref.version !== accepted.resolvedVersion;
+    }
+    // Local and workspace sources carry no resolution to compare against, so
+    // they always advance.
+    return true;
+};
+const unchangedStep = (label) => ({
+    readiness: "ready",
+    label,
+    run: Effect.succeed({
+        result: "success",
+        disposition: "unchanged",
+        message: "already up to date",
+    }),
+});
+/**
+ * Build the advance plan for one selective update: one unbounded job whose
+ * steps are the selected entries, each either unchanged or dispatched to the
+ * install operation that advances it.
+ */
+export const buildSelectiveUpdatePlan = (units, acceptedResolutions, name, description, makeRunClosure) => ({
+    _tag: "Plan",
+    name,
+    description,
+    jobs: [
+        {
+            concurrency: "unbounded",
+            steps: units.map((unit) => {
+                const accepted = acceptedResolutions[unit.name];
+                const needsUpdate = accepted === undefined || unit.force || hasChanged(unit.ref, accepted);
+                return needsUpdate
+                    ? { readiness: "ready", label: unit.name, run: makeRunClosure(unit.operation) }
+                    : unchangedStep(unit.name);
+            }),
+        },
+    ],
+});
+//# sourceMappingURL=plan.js.map

package/dist/src/update/selective/requirements.d.ts

@@ -0,0 +1,17 @@
+/**
+ * What a selective update's plan steps declare at execution time.
+ *
+ * A selective advance runs the same install operation the install routes run,
+ * so its steps carry the install step requirements plus the two services that
+ * operation reaches for directly: the source providers it re-fetches through,
+ * and the boundary's failure conversion. Those requirements travel with the
+ * step and are composed once at the application's runtime boundary — nothing
+ * is captured into a step's closure on the way.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type { SourceHostProviders } from "@agentxm/extension-sources";
+import type { InstallStepRequirements } from "../../install/vocabulary.js";
+import type { StepFailureConversion } from "../../step-failure-conversion.js";
+export type SelectiveUpdateStepRequirements = InstallStepRequirements | SourceHostProviders | StepFailureConversion;
+//# sourceMappingURL=requirements.d.ts.map

package/dist/src/update/selective/requirements.js

@@ -0,0 +1,14 @@
+/**
+ * What a selective update's plan steps declare at execution time.
+ *
+ * A selective advance runs the same install operation the install routes run,
+ * so its steps carry the install step requirements plus the two services that
+ * operation reaches for directly: the source providers it re-fetches through,
+ * and the boundary's failure conversion. Those requirements travel with the
+ * step and are composed once at the application's runtime boundary — nothing
+ * is captured into a step's closure on the way.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export {};
+//# sourceMappingURL=requirements.js.map

package/dist/src/update/selective/selection.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Which configured entries a selective update is about.
+ *
+ * `skills update` and `subagents update` accept two selectors: a positional
+ * that names either an installed extension or the source it came from, and a
+ * repeated name filter that accepts globs. Both narrow the configured,
+ * enabled entries of one type; neither resolves anything from a Registry.
+ * A selector that matches nothing is not a failure — it is a settled no-op
+ * with the reason the application renders.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { SourceHostProviders, type IdentifierResourceType } from "@agentxm/extension-sources";
+/** One configured entry a selective update may advance. */
+export type SelectiveUpdateEntry = readonly [name: string, source: string];
+/** Why a selective update settled without a plan. */
+export type SelectiveUpdateNothingReason = "none-installed" | "no-source-match" | "no-name-match";
+export type SelectiveUpdateSelection = {
+    readonly kind: "targets";
+    readonly entries: ReadonlyArray<SelectiveUpdateEntry>;
+} | {
+    readonly kind: "nothing";
+    readonly reason: SelectiveUpdateNothingReason;
+    readonly message: string;
+};
+export interface SelectiveUpdateSelectors {
+    /** Positional selector: an installed name, or the source an entry declares. */
+    readonly source: Option.Option<string>;
+    /** Repeated name filter; entries may be globs. */
+    readonly nameFilters: ReadonlyArray<string>;
+    /** The flag spelling the application registered, quoted in the no-op reason. */
+    readonly nameFilterFlag: string;
+}
+interface SelectionRequest extends SelectiveUpdateSelectors {
+    readonly entries: ReadonlyArray<SelectiveUpdateEntry>;
+    readonly resourceType: IdentifierResourceType;
+    readonly resourceLabel: string;
+    readonly resourceLabelPlural: string;
+}
+/**
+ * Narrow the configured entries to the ones both selectors admit, or say
+ * which selector admitted nothing.
+ */
+export declare const selectUpdateTargets: (request: SelectionRequest) => Effect.Effect<{
+    kind: "nothing";
+    reason: "no-source-match";
+    message: string;
+    entries?: never;
+} | {
+    kind: "nothing";
+    reason: "no-name-match";
+    message: string;
+    entries?: never;
+} | {
+    kind: "targets";
+    entries: readonly SelectiveUpdateEntry[];
+    reason?: never;
+    message?: never;
+}, import("@agentxm/extension-sources").SourceSyntaxInvalid | import("@agentxm/extension-sources").SourceHostNotConfigured | import("@agentxm/extension-sources").SourceNotResolvable | import("@agentxm/extension-sources").SourceNetworkFailure | import("@agentxm/extension-sources").GitOperationFailed | import("@agentxm/extension-sources").WorkspaceCatalogUnavailable | import("@agentxm/extension-sources").AxmSkillGateUnavailable | import("@agentxm/registry-client").RegistryProblem | import("@agentxm/registry-client").RegistryRequestFailed | import("@agentxm/registry-client").RegistryOperationFailed, import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("effect/unstable/http/HttpClient").HttpClient | SourceHostProviders | import("@agentxm/extension-sources").WorkspaceCatalog>;
+export {};
+//# sourceMappingURL=selection.d.ts.map

package/dist/src/update/selective/selection.js

@@ -0,0 +1,85 @@
+/**
+ * Which configured entries a selective update is about.
+ *
+ * `skills update` and `subagents update` accept two selectors: a positional
+ * that names either an installed extension or the source it came from, and a
+ * repeated name filter that accepts globs. Both narrow the configured,
+ * enabled entries of one type; neither resolves anything from a Registry.
+ * A selector that matches nothing is not a failure — it is a settled no-op
+ * with the reason the application renders.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { parseSourceQualifiedRegistrySourcePatternParts } from "@agentxm/extension-model/unstable/extensions";
+import { resolveInstalledIdentifierNameOrInput, resolveSource, SourceHostProviders, } from "@agentxm/extension-sources";
+import { expandGlobs } from "../../glob.js";
+/**
+ * Whether a positional selector names the same origin an entry declares.
+ * Two Registry patterns compare by their parsed parts; anything else
+ * compares by the canonical origin its source resolves to.
+ */
+const sourceMatchesEntrySource = (sourceValue, entrySource) => Effect.gen(function* () {
+    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) => Effect.gen(function* () {
+    const nameMatched = entries.filter(([name]) => name === sourceValue);
+    if (nameMatched.length > 0)
+        return nameMatched;
+    const matches = yield* Effect.forEach(entries, (entry) => Effect.map(sourceMatchesEntrySource(sourceValue, entry[1]), (matched) => matched ? Option.some(entry) : Option.none()), { concurrency: "unbounded" });
+    return matches.filter(Option.isSome).map((match) => match.value);
+});
+const filterByNameFilters = (entries, nameFilters, resourceType) => Effect.gen(function* () {
+    if (nameFilters.length === 0)
+        return entries;
+    const resolved = yield* Effect.forEach(nameFilters, (name) => name.includes("*")
+        ? Effect.succeed(name)
+        : resolveInstalledIdentifierNameOrInput({ input: name, resourceType }));
+    const matched = new Set(expandGlobs(resolved, entries.map(([name]) => name)));
+    return entries.filter(([name]) => matched.has(name));
+});
+/**
+ * Narrow the configured entries to the ones both selectors admit, or say
+ * which selector admitted nothing.
+ */
+export const selectUpdateTargets = Effect.fn("SelectiveUpdate.selectTargets")(function* (request) {
+    const sourceValue = Option.getOrUndefined(request.source);
+    const sourceFiltered = sourceValue === undefined
+        ? request.entries
+        : yield* filterBySource(request.entries, sourceValue);
+    if (sourceValue !== undefined && sourceFiltered.length === 0) {
+        return {
+            kind: "nothing",
+            reason: "no-source-match",
+            message: `No installed ${request.resourceLabel} matched "${sourceValue}" as a name or source.`,
+        };
+    }
+    const nameFiltered = yield* filterByNameFilters(sourceFiltered, request.nameFilters, request.resourceType);
+    if (request.nameFilters.length > 0 && nameFiltered.length === 0) {
+        return {
+            kind: "nothing",
+            reason: "no-name-match",
+            message: `No installed ${request.resourceLabelPlural} match the ${request.nameFilterFlag} filter.`,
+        };
+    }
+    return { kind: "targets", entries: nameFiltered };
+});
+//# sourceMappingURL=selection.js.map

package/dist/src/update/selective/skills.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Advancing the skills a workspace selected.
+ *
+ * `skills update` re-resolves each selected, enabled skill against the source
+ * the workspace declared, then advances the ones whose resolution differs
+ * from what was accepted. Two constraints govern the version it lands on: the
+ * range the workspace itself recorded, and the ranges every Pack that owns
+ * the skill declares. Precedence, not intersection, decides between them —
+ * `@agentxm/extension-resolution`'s constraint precedence owns that rule, and
+ * this module supplies it the visible version list and carries its warnings
+ * onto the plan. A skill that cannot be re-resolved is reported as a skipped
+ * unit rather than failing the sweep, so one unreachable source does not stop
+ * every other advance.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { SourceHostProviders } from "@agentxm/extension-sources";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { ExtensionLifecycleFailed } from "../../errors.js";
+import type { SelectiveUpdateStepRequirements } from "./requirements.js";
+import { type SelectiveUpdateSelectors } from "./selection.js";
+/** Everything `skills update` needs beyond the workspace it runs in. */
+export interface SelectiveSkillUpdateRequest extends SelectiveUpdateSelectors {
+    readonly kind: "selective-skills";
+    /** Advance outside the version ranges installed Packs declare. */
+    readonly ignoreVersionConstraints: boolean;
+}
+/** Settle a `skills update` request: decide everything, write nothing. */
+export declare const prepareSelectiveSkillUpdate: (request: SelectiveSkillUpdateRequest) => Effect.Effect<{
+    outcome: "nothing";
+    reason: "none-installed";
+    message: string;
+    subjectType: "skill";
+    planName: string;
+    planDescription: string;
+    execution?: never;
+} | {
+    outcome: "nothing";
+    reason: "no-source-match" | "no-name-match";
+    message: string;
+    subjectType: "skill";
+    planName: string;
+    planDescription: string;
+    execution?: never;
+} | {
+    outcome: "planned";
+    subjectType: "skill";
+    planName: string;
+    execution: import("@agentxm/workspace-operations").ExecutionCandidate<SelectiveUpdateStepRequirements, never>;
+    reason?: never;
+    message?: never;
+    planDescription?: never;
+}, ExtensionLifecycleFailed | import("@agentxm/extension-sources").SourceSyntaxInvalid | import("@agentxm/extension-sources").SourceHostNotConfigured | import("@agentxm/extension-sources").SourceNotResolvable | import("@agentxm/extension-sources").SourceNetworkFailure | import("@agentxm/extension-sources").GitOperationFailed | import("@agentxm/extension-sources").WorkspaceCatalogUnavailable | import("@agentxm/extension-sources").AxmSkillGateUnavailable | import("@agentxm/registry-client").RegistryProblem | import("@agentxm/registry-client").RegistryRequestFailed | import("@agentxm/registry-client").RegistryOperationFailed | import("@agentxm/workspace-state").SettingsIoError | import("@agentxm/workspace-state").SettingsParseError | import("@agentxm/workspace-state").SettingsDecodeError | import("@agentxm/workspace-state").LockfileIoError | import("@agentxm/workspace-state").LockfileParseError | import("@agentxm/workspace-state").LockfileDecodeError | import("@agentxm/workspace-state").LockfileVersionUnsupported | import("@agentxm/workspace-state").WorkspaceRootEscape | import("@agentxm/workspace-state").LockfileValidationError | import("@agentxm/extension-resolution").ExtensionResolutionFailed | import("@agentxm/workspace-operations").CandidateFingerprintFailed, import("effect/FileSystem").FileSystem | import("effect/Path").Path | WorkspaceMutations | import("@agentxm/workspace-state").ConfiguredAgentOutcomesProvider | import("effect/unstable/http/HttpClient").HttpClient | import("@agentxm/extension-resolution").ReleaseAgePosture | import("effect/Scope").Scope | SourceHostProviders | import("@agentxm/extension-sources").WorkspaceCatalog>;
+//# sourceMappingURL=skills.d.ts.map