@agentxm/extension-authoring 0.28.11 → 0.28.13

package/dist/src/step-failure.js

@@ -0,0 +1,253 @@
+/**
+ * How an authoring closure serializes a failure into the plan-step vocabulary.
+ *
+ * The feature owns this: an authoring step that failed must report the same
+ * category, sentence, and recovery whether the failure came from authoring's
+ * own policy, from the canonical-materialization machinery underneath it, or
+ * from the workspace transaction around it. Nothing is supplied by the
+ * application, so no authoring operation carries a failure adapter in its
+ * requirements.
+ *
+ * Categories and detail sentences are the serialized contract of machine
+ * output; they are reproduced here verbatim from the families that construct
+ * them.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import { OPERATION_ERROR_CATEGORIES, StepFailure, restorationIncompleteToStepFailure, workspaceStateReadFailureToStepFailure, workspaceTransactionFailureToStepFailure, } from "@agentxm/workspace-operations";
+import { ArchiveIntegrityMismatch, CanonicalPackageProbeFailed, CreateDestinationExists, LifecyclePostconditionViolated, NativeMcpEntryRetirementFailed, PackageCopyFailed, PackageMaterializationFailed, ScaffoldedExtensionUnresolved, StagedPackageInvalid, } from "@agentxm/extension-materialization";
+import { WorkspaceRestorationIncomplete, } from "@agentxm/workspace-transactions";
+import { AuthoringFailed } from "./errors.js";
+import { CreateDestinationInspectionFailed, CreateNameConfigured, ForkPackageConflict, ForkPackageFailed, ForkPackageInvalid, NativeImportConflict, NativeImportFailed, NativeImportInvalid, NativeImportUnsupported, } from "./authored-package-errors.js";
+const CATEGORIES = new Set(OPERATION_ERROR_CATEGORIES);
+const isCategory = (value) => typeof value === "string" && CATEGORIES.has(value);
+const property = (failure, key) => key in failure ? Reflect.get(failure, key) : undefined;
+/**
+ * A failure family this conversion does not name yet still carries its own
+ * decision: producers in the kernel record a category and a fact sentence, so
+ * both survive rather than being replaced with a generic sentence, and the
+ * failure itself stays in `cause` for the diagnostic chain.
+ */
+const carriedFailure = (failure) => {
+    const carriedCategory = property(failure, "category");
+    const carriedDetail = property(failure, "detail");
+    return new StepFailure({
+        category: isCategory(carriedCategory) ? carriedCategory : "internal",
+        detail: typeof carriedDetail === "string"
+            ? carriedDetail
+            : `The authoring step failed with ${failure._tag}`,
+        cause: failure,
+    });
+};
+const materializationDetail = (failure) => {
+    switch (failure.step) {
+        case "recover":
+            return `Failed to recover interrupted canonical materialization at ${failure.path}`;
+        case "prepare-parent":
+            return `Failed to prepare canonical package parent for ${failure.path}`;
+        case "prepare-staging":
+            return `Failed to prepare canonical package staging at ${failure.path}`;
+        case "inspect":
+            return `Failed to inspect canonical package at ${failure.path}`;
+        case "replace":
+            return `Failed to replace canonical package at ${failure.path}`;
+        case "inspect-create-destination":
+            return `Failed to inspect create-only destination: ${failure.path}`;
+    }
+};
+const postconditionDetail = (failure) => {
+    switch (failure.postcondition) {
+        case "install-observable":
+            return `Installed ${failure.targetType} "${failure.targetName}" did not satisfy its observable contract`;
+        case "install-declared":
+            return `Installed ${failure.targetType} "${failure.targetName}" has no desired-state declaration`;
+        case "new-observable":
+            return `New ${failure.targetType} "${failure.targetName}" did not satisfy its observable contract`;
+        case "new-declared":
+            return `New ${failure.targetType} "${failure.targetName}" has no desired-state declaration`;
+        case "materialize-observable":
+            return `Reconciled ${failure.targetType} "${failure.targetName}" did not satisfy its observable contract`;
+        case "uninstall-remains-declared":
+            return `Uninstalled ${failure.targetType} "${failure.targetName}" remains declared`;
+        case "uninstall-observed-state":
+            return `Uninstalled ${failure.targetType} "${failure.targetName}" has an invalid observed postcondition`;
+    }
+};
+const WORKSPACE_STATE_READ_TAGS = new Set([
+    "SettingsDecodeError",
+    "SettingsParseError",
+    "SettingsIoError",
+    "LockfileIoError",
+    "LockfileParseError",
+    "LockfileDecodeError",
+    "LockfileVersionUnsupported",
+    "WorkspaceRootEscape",
+]);
+const WORKSPACE_TRANSACTION_TAGS = new Set([
+    "WorkspaceSnapshotError",
+    "WorkspaceDirectoryError",
+    "TransitionLockError",
+    "TransitionLockUnavailable",
+    "WorkspaceTransitionCompromised",
+]);
+const isWorkspaceStateReadFailure = (failure) => WORKSPACE_STATE_READ_TAGS.has(failure._tag);
+const isWorkspaceTransactionFailure = (failure) => WORKSPACE_TRANSACTION_TAGS.has(failure._tag);
+/**
+ * Serialize one authoring-closure failure into the plan-step vocabulary.
+ *
+ * Families this feature or the machinery beneath it constructs are rendered
+ * exactly; families the kernel already serializes are delegated to it; and
+ * anything else carries its producer's own category and sentence through.
+ */
+export const authoringStepFailure = (failure) => {
+    if (failure instanceof StepFailure)
+        return failure;
+    if (failure instanceof AuthoringFailed) {
+        return new StepFailure({
+            category: failure.category,
+            detail: failure.detail,
+            ...(failure.recover === undefined && failure.suggestions === undefined
+                ? {}
+                : {
+                    suggestions: [
+                        ...(failure.recover === undefined ? [] : [{ description: failure.recover }]),
+                        ...(failure.suggestions ?? []),
+                    ],
+                }),
+            ...(failure.cause === undefined ? {} : { cause: failure.cause }),
+        });
+    }
+    if (failure instanceof CreateNameConfigured) {
+        return new StepFailure({
+            category: "conflict",
+            detail: `${failure.subject} '${failure.name}' already exists in settings`,
+            suggestions: [
+                {
+                    description: `Choose a different name or remove the existing ${failure.subject.toLowerCase()} first`,
+                },
+            ],
+        });
+    }
+    if (failure instanceof CreateDestinationExists) {
+        return new StepFailure({
+            category: "conflict",
+            detail: `${failure.subject} destination already exists: ${failure.path}`,
+            suggestions: [
+                { description: "Choose a different name or remove the existing directory first" },
+            ],
+        });
+    }
+    if (failure instanceof CreateDestinationInspectionFailed) {
+        return new StepFailure({
+            category: "internal",
+            detail: `Failed to inspect create destination: ${failure.path}`,
+            cause: failure.cause,
+        });
+    }
+    if (failure instanceof ScaffoldedExtensionUnresolved) {
+        return new StepFailure({
+            category: "not_found",
+            detail: `Newly scaffolded ${failure.targetType} "${failure.targetName}" could not be resolved from its workspace source`,
+        });
+    }
+    if (failure instanceof LifecyclePostconditionViolated) {
+        return new StepFailure({ category: "internal", detail: postconditionDetail(failure) });
+    }
+    if (failure instanceof PackageMaterializationFailed) {
+        return new StepFailure({
+            category: "internal",
+            detail: materializationDetail(failure),
+            cause: failure.cause,
+        });
+    }
+    if (failure instanceof StagedPackageInvalid) {
+        return new StepFailure({
+            category: "validation",
+            detail: failure.kind === "missing"
+                ? `Staged package is missing required file: ${failure.file}`
+                : `Staged package path is not a file: ${failure.file}`,
+            ...(failure.cause === undefined ? {} : { cause: failure.cause }),
+        });
+    }
+    if (failure instanceof CanonicalPackageProbeFailed) {
+        return new StepFailure({
+            category: "internal",
+            detail: failure.detail,
+            cause: failure.cause,
+        });
+    }
+    if (failure instanceof PackageCopyFailed) {
+        return new StepFailure({
+            category: failure.severity,
+            detail: failure.detail,
+            cause: failure.cause,
+        });
+    }
+    if (failure instanceof NativeMcpEntryRetirementFailed) {
+        return new StepFailure({
+            category: failure.category,
+            detail: failure.detail,
+            ...(failure.cause === undefined ? {} : { cause: failure.cause }),
+        });
+    }
+    if (failure instanceof ArchiveIntegrityMismatch) {
+        return new StepFailure({
+            category: "validation",
+            detail: `${failure.subject} — the fetched archive does not match the accepted integrity. Verify the source and rerun, or update to accept a republished version.`,
+        });
+    }
+    if (failure instanceof ForkPackageInvalid) {
+        return new StepFailure({
+            category: "validation",
+            detail: failure.detail,
+            ...(failure.cause === undefined ? {} : { cause: failure.cause }),
+        });
+    }
+    if (failure instanceof ForkPackageConflict) {
+        return new StepFailure({ category: "conflict", detail: failure.detail });
+    }
+    if (failure instanceof ForkPackageFailed) {
+        return new StepFailure({
+            category: "internal",
+            detail: failure.detail,
+            cause: failure.cause,
+        });
+    }
+    if (failure instanceof NativeImportUnsupported) {
+        return new StepFailure({
+            category: "usage",
+            detail: `Native package import is not supported for ${failure.type}`,
+        });
+    }
+    if (failure instanceof NativeImportInvalid) {
+        return new StepFailure({
+            category: "validation",
+            detail: failure.detail,
+            ...(failure.cause === undefined ? {} : { cause: failure.cause }),
+        });
+    }
+    if (failure instanceof NativeImportConflict) {
+        return new StepFailure({
+            category: "conflict",
+            detail: `Import target already exists: ${failure.targetDir}`,
+        });
+    }
+    if (failure instanceof NativeImportFailed) {
+        return new StepFailure({
+            category: "internal",
+            detail: failure.detail,
+            cause: failure.cause,
+        });
+    }
+    if (failure instanceof WorkspaceRestorationIncomplete) {
+        return restorationIncompleteToStepFailure(failure);
+    }
+    if (isWorkspaceTransactionFailure(failure)) {
+        return workspaceTransactionFailureToStepFailure(failure);
+    }
+    if (isWorkspaceStateReadFailure(failure)) {
+        return workspaceStateReadFailureToStepFailure(failure);
+    }
+    return carriedFailure(failure);
+};
+//# sourceMappingURL=step-failure.js.map

package/dist/src/testing.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @agentxm/extension-authoring deterministic test fixtures.
+ *
+ * A throwaway project workspace on a temporary directory, and the per-type
+ * creation request an authoring command is admitted with.
+ *
+ * The fixture is deliberately platform-free: composing the file system, the
+ * transport and the managers is the consumer's job, exactly as it is the
+ * application's, so this module stays importable from a published package
+ * rather than dragging a Node-only platform layer behind it. What it does own
+ * is the shape of an authored workspace on disk and the byte-exact snapshot a
+ * purity example compares against — two snapshots are equal only when every
+ * path and every byte is unchanged, so a preview that wrote anything at all
+ * fails rather than passing on a coarse comparison.
+ *
+ * Production source never imports this module.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Option from "effect/Option";
+import type { CreatableExtensionType, CreateExtensionRequest } from "./create/create-extension.js";
+/** Settings an authoring example seeds its workspace with. */
+export interface AuthoringWorkspaceSettings {
+    readonly owner?: string;
+    readonly agents?: ReadonlyArray<string>;
+}
+export interface AuthoringWorkspace {
+    /** Absolute project root the workspace is anchored to. */
+    readonly root: string;
+    /** Read a workspace-relative file, or `undefined` when it is absent. */
+    readonly read: (relativePath: string) => string | undefined;
+    /** Write a workspace-relative file, creating parents. */
+    readonly write: (relativePath: string, contents: string) => void;
+    /** Whether a workspace-relative path exists. */
+    readonly exists: (relativePath: string) => boolean;
+    /** The decoded settings document. */
+    readonly settings: () => unknown;
+    /** Replace the settings document wholesale. */
+    readonly writeSettings: (value: unknown) => void;
+    /** The lockfile text, or an empty string when there is none. */
+    readonly lockfileText: () => string;
+    /** Every workspace-relative path that exists, sorted. */
+    readonly tree: () => ReadonlyArray<string>;
+    /**
+     * Byte-exact content of a subtree: workspace-relative path mapped to
+     * `"directory"` or `"file:<base64>"`. A missing root snapshots empty.
+     */
+    readonly snapshot: (relativePath?: string) => Readonly<Record<string, string>>;
+    readonly cleanup: () => void;
+}
+/**
+ * A temporary project workspace whose settings name an owner and the agents
+ * it configures, initialized the way `axm setup` leaves a project.
+ */
+export declare const makeAuthoringWorkspace: (settings?: AuthoringWorkspaceSettings) => AuthoringWorkspace;
+/**
+ * The creation request for one extension type, with the per-type options an
+ * example does not vary.
+ *
+ * The rules that sweep every type — create-only refusal, workspace ownership —
+ * are about what creation shares, not about what each scaffold takes, so the
+ * type-specific fields are supplied once here rather than in every example.
+ */
+export declare const createRequestFor: (type: CreatableExtensionType, name: string, owner?: Option.Option<string>) => CreateExtensionRequest;
+/** Every extension type a person can author in a workspace. */
+export declare const CREATABLE_TYPES: readonly ["skill", "mcp-server", "subagent", "rule", "hook", "knowledge", "pack"];
+//# sourceMappingURL=testing.d.ts.map

package/dist/src/testing.js

@@ -0,0 +1,135 @@
+/**
+ * @agentxm/extension-authoring deterministic test fixtures.
+ *
+ * A throwaway project workspace on a temporary directory, and the per-type
+ * creation request an authoring command is admitted with.
+ *
+ * The fixture is deliberately platform-free: composing the file system, the
+ * transport and the managers is the consumer's job, exactly as it is the
+ * application's, so this module stays importable from a published package
+ * rather than dragging a Node-only platform layer behind it. What it does own
+ * is the shape of an authored workspace on disk and the byte-exact snapshot a
+ * purity example compares against — two snapshots are equal only when every
+ * path and every byte is unchanged, so a preview that wrote anything at all
+ * fails rather than passing on a coarse comparison.
+ *
+ * Production source never imports this module.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as nodePath from "node:path";
+import * as Option from "effect/Option";
+const walk = (root, directory) => {
+    const entries = fs.existsSync(directory)
+        ? fs.readdirSync(directory, { withFileTypes: true })
+        : [];
+    return entries.flatMap((entry) => {
+        const absolute = nodePath.join(directory, entry.name);
+        const relative = nodePath.relative(root, absolute);
+        return entry.isDirectory() ? walk(root, absolute) : [relative];
+    });
+};
+/**
+ * A temporary project workspace whose settings name an owner and the agents
+ * it configures, initialized the way `axm setup` leaves a project.
+ */
+export const makeAuthoringWorkspace = (settings = {}) => {
+    const root = fs.realpathSync(fs.mkdtempSync(nodePath.join(os.tmpdir(), "axm-authoring-")));
+    const absolute = (relativePath) => nodePath.join(root, relativePath);
+    const writeSettings = (value) => {
+        fs.writeFileSync(absolute("axm.json"), `${JSON.stringify(value, null, 2)}\n`);
+    };
+    writeSettings({
+        ...(settings.owner === undefined ? {} : { owner: settings.owner }),
+        agents: settings.agents ?? [],
+    });
+    const snapshot = (relativePath = ".") => {
+        const target = absolute(relativePath);
+        const entries = {};
+        if (!fs.existsSync(target))
+            return entries;
+        if (!fs.statSync(target).isDirectory()) {
+            entries["."] = `file:${fs.readFileSync(target).toString("base64")}`;
+            return entries;
+        }
+        const visit = (directory) => {
+            for (const entry of fs
+                .readdirSync(directory, { withFileTypes: true })
+                .sort((left, right) => left.name.localeCompare(right.name, "en"))) {
+                const child = nodePath.join(directory, entry.name);
+                const relative = nodePath.relative(target, child);
+                if (entry.isDirectory()) {
+                    entries[relative] = "directory";
+                    visit(child);
+                }
+                else {
+                    entries[relative] = `file:${fs.readFileSync(child).toString("base64")}`;
+                }
+            }
+        };
+        visit(target);
+        return entries;
+    };
+    return {
+        root,
+        read: (relativePath) => fs.existsSync(absolute(relativePath))
+            ? fs.readFileSync(absolute(relativePath), "utf-8")
+            : undefined,
+        write: (relativePath, contents) => {
+            const target = absolute(relativePath);
+            fs.mkdirSync(nodePath.dirname(target), { recursive: true });
+            fs.writeFileSync(target, contents);
+        },
+        exists: (relativePath) => fs.existsSync(absolute(relativePath)),
+        settings: () => JSON.parse(fs.readFileSync(absolute("axm.json"), "utf-8")),
+        writeSettings,
+        lockfileText: () => fs.existsSync(absolute("axm-lock.yaml"))
+            ? fs.readFileSync(absolute("axm-lock.yaml"), "utf-8")
+            : "",
+        tree: () => [...walk(root, root)].sort(),
+        snapshot,
+        cleanup: () => {
+            fs.rmSync(root, { recursive: true, force: true });
+        },
+    };
+};
+/**
+ * The creation request for one extension type, with the per-type options an
+ * example does not vary.
+ *
+ * The rules that sweep every type — create-only refusal, workspace ownership —
+ * are about what creation shares, not about what each scaffold takes, so the
+ * type-specific fields are supplied once here rather than in every example.
+ */
+export const createRequestFor = (type, name, owner = Option.none()) => {
+    switch (type) {
+        case "skill":
+            return { type, name, owner };
+        case "subagent":
+            return { type, name, owner };
+        case "pack":
+            return { type, name, owner };
+        case "rule":
+            return { type, name, owner, title: Option.none() };
+        case "knowledge":
+            return { type, name, owner, description: Option.none() };
+        case "hook":
+            return { type, name, owner, runtime: "bash", event: "tool.pre", matcher: Option.none() };
+        case "mcp-server":
+            return { type, name, owner, description: Option.none(), nonInteractive: true };
+    }
+};
+/** Every extension type a person can author in a workspace. */
+export const CREATABLE_TYPES = [
+    "skill",
+    "mcp-server",
+    "subagent",
+    "rule",
+    "hook",
+    "knowledge",
+    "pack",
+];
+//# sourceMappingURL=testing.js.map

package/dist/src/version/change-authored-version.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Changing the version an authored manifest declares.
+ *
+ * A version is one field of one manifest the workspace authors, so this use
+ * case decides three things: that the named package really is authored here,
+ * what the next version is, and that nothing else in the manifest moves. The
+ * write runs inside the workspace transaction like every other authoring
+ * change, so an interrupted or failed bump restores the manifest rather than
+ * leaving a half-written file, and the operation reports the real resolution
+ * the transaction settled with.
+ *
+ * `prepare` reads the manifest, settles `from` and `to`, and writes nothing.
+ * `previewOrApply` resolves that candidate; a bump to the version the manifest
+ * already carries settles as unchanged rather than rewriting the file.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { type ExtensionType, type FqnInvalidError } from "@agentxm/extension-model/unstable/extensions";
+import { type Version } from "@agentxm/extension-model/unstable/version-constraints";
+import { type CandidateFingerprintFailed, type ExecutionCandidate, type PlanExecution } from "@agentxm/workspace-operations";
+import { WorkspaceMutations, type ConfiguredAgentOutcomesProvider, type LockfileValidationError, type WorkspaceLockfileReadFailure, type WorkspaceSettingsReadFailure } from "@agentxm/workspace-state";
+import { type WorkspaceTransactionScope } from "@agentxm/workspace-transactions";
+import { AuthoringScopeUnsupported } from "../create/errors.js";
+import { type AuthoredVersionError } from "./errors.js";
+/** The relative bumps a manifest version can take. */
+export type VersionBumpRule = "patch" | "minor" | "major" | "prerelease";
+/** How the next version is decided: by rule, or stated exactly. */
+export type AuthoredVersionChange = {
+    readonly _tag: "Increment";
+    readonly rule: VersionBumpRule;
+} | {
+    readonly _tag: "Exact";
+    readonly version: string;
+};
+export interface ChangeAuthoredVersionRequest {
+    /** Owner-qualified identity of the authored package, as the person typed it. */
+    readonly fqn: string;
+    readonly change: AuthoredVersionChange;
+}
+/** What the version step requires when it runs. */
+export type ChangeAuthoredVersionRequirements = FileSystem.FileSystem | Path.Path | WorkspaceTransactionScope;
+/** A settled version change: the manifest is read, the next version decided, nothing written. */
+export interface ChangeAuthoredVersionCandidate {
+    readonly type: ExtensionType;
+    /** Owner-qualified identity, canonically formatted. */
+    readonly fqn: string;
+    /** Workspace-relative path of the manifest that carries the version. */
+    readonly manifestPath: string;
+    readonly from: Version;
+    readonly to: Version;
+    /** Whether the request asks for a version the manifest already declares. */
+    readonly unchanged: boolean;
+    readonly execution: ExecutionCandidate<ChangeAuthoredVersionRequirements>;
+}
+/** Every failure settling a version change can surface before anything is written. */
+export type ChangeAuthoredVersionFailure = AuthoredVersionError | AuthoringScopeUnsupported | LockfileValidationError | WorkspaceLockfileReadFailure | WorkspaceSettingsReadFailure | CandidateFingerprintFailed | FqnInvalidError;
+/** Everything settling a version change reads before it freezes a candidate. */
+export type PrepareChangeAuthoredVersionRequirements = FileSystem.FileSystem | Path.Path | WorkspaceMutations | ConfiguredAgentOutcomesProvider;
+/** The plan a version change resolves. */
+export declare const changeAuthoredVersionPlanName = "Update extension version";
+/** Settle a version change without writing anything. */
+export declare const prepareChangeAuthoredVersion: (request: ChangeAuthoredVersionRequest) => Effect.Effect<ChangeAuthoredVersionCandidate, ChangeAuthoredVersionFailure, PrepareChangeAuthoredVersionRequirements>;
+/** Preview or apply a settled version change, resolving to one operation outcome. */
+export declare const previewOrApplyChangeAuthoredVersion: (candidate: ChangeAuthoredVersionCandidate, execution: PlanExecution) => Effect.Effect<import("@agentxm/workspace-operations").OperationResolution<never>, WorkspaceSettingsReadFailure | import("@agentxm/workspace-operations").ApprovalRecoveryMissing | import("@agentxm/workspace-operations").PlanInteractionFailed | import("@agentxm/workspace-transactions").WorkspaceTransitionAcquireFailure, WorkspaceMutations | ConfiguredAgentOutcomesProvider | import("@agentxm/workspace-operations").OperationJournal | import("@agentxm/workspace-operations").ResolvePlanInteraction | import("@agentxm/workspace-transactions").FootprintRecorder | ChangeAuthoredVersionRequirements>;
+/** The version-change use case: settle a request, then preview or apply it. */
+export declare const ChangeAuthoredVersion: {
+    readonly prepare: (request: ChangeAuthoredVersionRequest) => Effect.Effect<ChangeAuthoredVersionCandidate, ChangeAuthoredVersionFailure, PrepareChangeAuthoredVersionRequirements>;
+    readonly previewOrApply: (candidate: ChangeAuthoredVersionCandidate, execution: PlanExecution) => Effect.Effect<import("@agentxm/workspace-operations").OperationResolution<never>, WorkspaceSettingsReadFailure | import("@agentxm/workspace-operations").ApprovalRecoveryMissing | import("@agentxm/workspace-operations").PlanInteractionFailed | import("@agentxm/workspace-transactions").WorkspaceTransitionAcquireFailure, WorkspaceMutations | ConfiguredAgentOutcomesProvider | import("@agentxm/workspace-operations").OperationJournal | import("@agentxm/workspace-operations").ResolvePlanInteraction | import("@agentxm/workspace-transactions").FootprintRecorder | ChangeAuthoredVersionRequirements>;
+};
+//# sourceMappingURL=change-authored-version.d.ts.map