@agentxm/extension-authoring 0.28.11 → 0.28.13

package/dist/src/import/import-native-extension.js

@@ -0,0 +1,310 @@
+/**
+ * Importing native, unmanaged content as an authored AXM package.
+ *
+ * Three routes share one decision: a native skill directory or file, a native
+ * subagent document, and a native MCP connection declared in an agent's own
+ * config all become a workspace-authored package that carries the identity the
+ * person asked for, not the identity the native content happened to have. The
+ * native source is never modified — except for an MCP connection, whose native
+ * declaration is retired only after the managed package validates, because
+ * leaving both would give one connection two owners.
+ *
+ * `prepare` settles the identity, the destination, and the activation, and
+ * stages the converted package into a scoped temporary directory; nothing
+ * under the workspace is written. `previewOrApply` resolves that candidate.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { ExtensionManagers, McpSecretStore, buildAuthoredExtensionStep, copyExtensionDirectory, createCanonicalDirectory, materializeAuthoredMcpServer, recoverCanonicalDirectory, retireNativeMcpEntry, } from "@agentxm/extension-materialization";
+import { extensionTypeToPlural, formatFqn, parseFqn, } from "@agentxm/extension-model/unstable/extensions";
+import { MCP_SERVER_MANIFEST_FILENAME, MCP_SERVER_MANIFEST_SCHEMA_URL, MCP_SERVER_REGISTRY_SERVER_SCHEMA_URL, } from "@agentxm/extension-model/unstable/mcps/manifest-schema";
+import { decodeVersionSync } from "@agentxm/extension-model/unstable/version-constraints";
+import { SourceHostProviders, WorkspaceCatalog, acquireExternalSource, resolveSource, } from "@agentxm/extension-sources";
+import { operationPresentation, prepareExecutionCandidate, resolveExecutionCandidate, } from "@agentxm/workspace-operations";
+import { WorkspaceMutations, computePackageContentHash, } from "@agentxm/workspace-state";
+import { authoredDeclaration } from "../authored-declaration.js";
+import { preflightCreateOnly } from "../create-preflight.js";
+import { AuthoringFailed } from "../errors.js";
+import { requireAuthoredOwner, settingsRelativePath } from "../create/authoring-owner.js";
+import { AuthoringScopeUnsupported, } from "../create/errors.js";
+import { importNativeExtensionPackage } from "../import-native-package.js";
+import { authoringStepFailure } from "../step-failure.js";
+/** The version an imported package starts at. */
+const INITIAL_IMPORT_VERSION = decodeVersionSync("0.1.0");
+/** Build the import step with the requirements this use case keeps in `R`. */
+const importStep = (manager, args) => buildAuthoredExtensionStep(manager, args);
+/** The plan a native import resolves. */
+export const importNativeExtensionPlanName = (type) => type === "mcp-server" ? "Import MCP server package" : "Import native extension";
+/**
+ * The one connection a package conversion may represent.
+ *
+ * Converting requires an unambiguous subject: a config the agents disagree
+ * about, a discovery that found no connection or several, and a local command
+ * that no manifest can express are three different refusals, each recoverable
+ * in a different way.
+ */
+const selectNativeMcpCandidate = (discovery) => {
+    if (discovery.conflicts.length > 0) {
+        return Effect.fail(new AuthoringFailed({
+            category: "conflict",
+            detail: `MCP package import has ${discovery.conflicts.length} conflicted native candidate(s)`,
+        }));
+    }
+    const candidate = discovery.candidates[0];
+    if (candidate === undefined || discovery.candidates.length !== 1) {
+        return Effect.fail(new AuthoringFailed({
+            category: "validation",
+            detail: discovery.candidates.length === 0
+                ? "No losslessly importable unmanaged MCP server was found"
+                : "MCP package import requires exactly one unmanaged server candidate",
+        }));
+    }
+    if (Option.isNone(candidate.remote)) {
+        return Effect.fail(new AuthoringFailed({
+            category: "usage",
+            detail: "This MCP command cannot be represented losslessly as a managed package; import it inline without --as",
+        }));
+    }
+    return Effect.succeed({
+        candidate,
+        url: candidate.remote.value.url,
+        headers: candidate.remote.value.headers,
+    });
+};
+/** The manifest a converted native connection is published as. */
+const convertedMcpManifest = (args) => ({
+    $schema: MCP_SERVER_MANIFEST_SCHEMA_URL,
+    owner: args.owner,
+    type: "mcp-server",
+    name: args.name,
+    version: INITIAL_IMPORT_VERSION,
+    description: `Imported MCP server ${args.nativeName}`,
+    server: {
+        $schema: MCP_SERVER_REGISTRY_SERVER_SCHEMA_URL,
+        name: `local.axm/${args.name}`,
+        description: `Imported MCP server ${args.nativeName}`,
+        version: INITIAL_IMPORT_VERSION,
+        remotes: [
+            {
+                type: "streamable-http",
+                url: args.url,
+                ...(Object.keys(args.headers).length === 0
+                    ? {}
+                    : {
+                        headers: Object.entries(args.headers).map(([name, value]) => ({ name, value })),
+                    }),
+            },
+        ],
+    },
+});
+/**
+ * Convert a native skill or subagent by staging the rewritten package now and
+ * pinning its content hash, so content that changes between preview and apply
+ * refuses instead of landing.
+ */
+const nativeConversion = Effect.fn("ImportNativeExtension.nativeConversion")(function* (args) {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const source = yield* resolveSource(args.request.source);
+    const acquired = yield* acquireExternalSource(source);
+    const stagingRoot = yield* fs.makeTempDirectoryScoped({ prefix: "axm-import-" }).pipe(Effect.mapError((cause) => new AuthoringFailed({
+        category: "internal",
+        detail: "Import staging directory could not be created",
+        cause,
+    })));
+    const stagedPackage = path.join(stagingRoot, "package");
+    yield* importNativeExtensionPackage({
+        sourcePath: acquired.directory,
+        targetDir: stagedPackage,
+        target: args.target,
+    });
+    const stagedHash = yield* computePackageContentHash(stagedPackage);
+    return {
+        origin: acquired.origin,
+        env: {},
+        nativeTargets: [],
+        requiredFiles: undefined,
+        populate: (publicationPath) => copyExtensionDirectory(stagedPackage, publicationPath).pipe(Effect.mapError((cause) => new AuthoringFailed({
+            category: "internal",
+            detail: "Prepared import could not be staged",
+            cause,
+        }))),
+        validate: (publicationPath) => computePackageContentHash(publicationPath).pipe(Effect.flatMap((currentHash) => currentHash === stagedHash
+            ? Effect.void
+            : new AuthoringFailed({
+                category: "conflict",
+                detail: "Prepared import content changed before it could be applied",
+            }))),
+        retireNative: Effect.void,
+    };
+});
+/**
+ * Convert one discovered native MCP connection into a manifest, and retire
+ * every native declaration of it once the managed package validates.
+ */
+const mcpConversion = Effect.fn("ImportNativeExtension.mcpConversion")(function* (args) {
+    const { candidate, url, headers } = yield* selectNativeMcpCandidate(args.request.discovery);
+    const manifest = convertedMcpManifest({
+        owner: args.owner,
+        name: args.name,
+        nativeName: candidate.name,
+        url,
+        headers,
+    });
+    const entries = [...candidate.entries].sort((left, right) => left.filePath === right.filePath
+        ? left.name.localeCompare(right.name)
+        : left.filePath.localeCompare(right.filePath));
+    return {
+        origin: candidate.name,
+        env: candidate.env,
+        nativeTargets: Array.from(new Set(entries.map((entry) => entry.filePath))).sort(),
+        requiredFiles: [MCP_SERVER_MANIFEST_FILENAME],
+        populate: (stagingPath) => Effect.gen(function* () {
+            const fs = yield* FileSystem.FileSystem;
+            const path = yield* Path.Path;
+            yield* fs
+                .writeFileString(path.join(stagingPath, MCP_SERVER_MANIFEST_FILENAME), `${JSON.stringify(manifest, null, 2)}\n`)
+                .pipe(Effect.mapError((cause) => new AuthoringFailed({
+                category: "internal",
+                detail: "MCP package manifest could not be staged",
+                cause,
+            })));
+        }),
+        validate: undefined,
+        retireNative: Effect.forEach(entries, retireNativeMcpEntry, { discard: true }),
+    };
+});
+// -----------------------------------------------------------------------------
+// prepare
+// -----------------------------------------------------------------------------
+/** Settle a native import and stage its converted content, writing nothing. */
+export const prepareImportNativeExtension = Effect.fn("ImportNativeExtension.prepare")(function* (request) {
+    const ws = yield* WorkspaceMutations;
+    const path = yield* Path.Path;
+    const managers = yield* ExtensionManagers;
+    const target = yield* Effect.fromResult(parseFqn(request.target));
+    if (target.type !== request.type) {
+        return yield* new AuthoringFailed({
+            category: "validation",
+            detail: `Expected a ${extensionTypeToPlural[request.type]} target FQN, got ${request.target}`,
+        });
+    }
+    yield* requireAuthoredOwner(target.owner, { subject: "package", command: "import" });
+    if (ws.layout.scope !== "project") {
+        return yield* new AuthoringScopeUnsupported({ subject: "import", scope: ws.layout.scope });
+    }
+    const name = target.name;
+    const fqn = formatFqn(target);
+    const targetDir = path.join(ws.layout.authoredRoot(target.type), name);
+    const authoredPath = path.relative(ws.baseDir, targetDir);
+    const settingsPath = settingsRelativePath(path, ws);
+    const subject = request.type === "mcp-server" ? "MCP package" : "Import target";
+    const createOnly = preflightCreateOnly({
+        subject,
+        name,
+        configured: false,
+        destinations: [targetDir],
+    });
+    yield* createOnly;
+    const declaration = authoredDeclaration(ws, target.type, name);
+    const current = yield* declaration.read;
+    const settled = request.type === "mcp-server"
+        ? yield* mcpConversion({ request, owner: target.owner, name })
+        : yield* nativeConversion({ request, target });
+    const enabled = request.type === "mcp-server"
+        ? request.enable
+        : request.enable || Option.getOrElse(current.enabled, () => false);
+    const env = request.type === "mcp-server" ? settled.env : current.env;
+    const artifact = {
+        path: authoredPath,
+        scope: ws.scope,
+        version: INITIAL_IMPORT_VERSION,
+        change: "created",
+        targets: [
+            { path: authoredPath, change: "created" },
+            { path: settingsPath, change: "created" },
+            ...settled.nativeTargets.map((filePath) => ({
+                path: path.relative(ws.baseDir, filePath),
+                change: "updated",
+            })),
+        ],
+    };
+    const common = {
+        toStepFailure: authoringStepFailure,
+        location: targetDir,
+        ...(settled.nativeTargets.length === 0 ? {} : { transactionTargets: settled.nativeTargets }),
+        versionRange: Option.none(),
+        label: `Import ${settled.origin} -> ${fqn}`,
+        message: `Imported ${fqn}`,
+        enabled,
+        allowConfiguredSourceTransition: true,
+        markAuthored: declaration.declare({ enabled: true, env }),
+        finalizeAuthored: declaration
+            .declare({ enabled, env })
+            .pipe(Effect.andThen(settled.retireNative), Effect.asVoid),
+        plannedArtifact: artifact,
+        buildArtifact: () => Effect.succeed(artifact),
+        preflight: Effect.gen(function* () {
+            yield* recoverCanonicalDirectory({ baseDir: ws.baseDir, canonicalPath: targetDir });
+            yield* createOnly;
+        }),
+        scaffold: createCanonicalDirectory({
+            baseDir: ws.baseDir,
+            canonicalPath: targetDir,
+            subject,
+            ...(settled.requiredFiles === undefined ? {} : { requiredFiles: settled.requiredFiles }),
+            populate: settled.populate,
+            ...(settled.validate === undefined ? {} : { validate: settled.validate }),
+        }).pipe(Effect.asVoid),
+    };
+    const step = (() => {
+        switch (request.type) {
+            case "skill":
+                return importStep(managers.skill, { ...common, target: { type: "skill", name } });
+            case "subagent":
+                return importStep(managers.subagent, { ...common, target: { type: "subagent", name } });
+            case "mcp-server":
+                return importStep(managers["mcp-server"], {
+                    ...common,
+                    target: { type: "mcp-server", name },
+                    materializeWhenDisabled: true,
+                    materializeInstall: (ref) => materializeAuthoredMcpServer({ ref, nonInteractive: request.nonInteractive }),
+                });
+        }
+    })();
+    const plan = {
+        _tag: "Plan",
+        name: importNativeExtensionPlanName(request.type),
+        description: Option.some(request.type === "mcp-server"
+            ? `Losslessly convert ${settled.origin} into ${fqn}; native MCP config is replaced only after managed validation`
+            : `Losslessly convert ${settled.origin} into ${fqn}; the native source remains unchanged and the import starts ${enabled ? "enabled" : "disabled"}`),
+        presentation: operationPresentation({ imperative: "import", past: "Imported", gerund: "Importing" }, target.type),
+        jobs: [{ concurrency: 1, steps: [step] }],
+    };
+    return {
+        type: request.type,
+        fqn,
+        owner: target.owner,
+        name,
+        origin: settled.origin,
+        authoredPath,
+        settingsPath,
+        enabled,
+        execution: yield* prepareExecutionCandidate(plan),
+    };
+});
+// -----------------------------------------------------------------------------
+// previewOrApply
+// -----------------------------------------------------------------------------
+/** Preview or apply a settled native import, resolving to one operation outcome. */
+export const previewOrApplyImportNativeExtension = (candidate, execution) => resolveExecutionCandidate(candidate.execution, execution);
+/** The native-import use case: settle a request, then preview or apply it. */
+export const ImportNativeExtension = {
+    prepare: prepareImportNativeExtension,
+    previewOrApply: previewOrApplyImportNativeExtension,
+};
+//# sourceMappingURL=import-native-extension.js.map

package/dist/src/import-native-package.d.ts

@@ -2,8 +2,8 @@ import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
 import type { ExtensionFqnParts } from "@agentxm/extension-model/unstable/extensions/common";
-import { type FrontmatterParseFailure } from "@agentxm/registry-protocol/unstable/content/frontmatter";
-import { NativeImportConflict, NativeImportFailed, NativeImportInvalid, NativeImportUnsupported } from "@agentxm/extension-workspace";
+import { type FrontmatterParseFailure } from "@agentxm/extension-content";
+import { NativeImportConflict, NativeImportFailed, NativeImportInvalid, NativeImportUnsupported } from "./authored-package-errors.js";
 export interface ImportNativeExtensionPackageArgs {
     readonly sourcePath: string;
     readonly targetDir: string;

package/dist/src/import-native-package.js

@@ -3,10 +3,10 @@ import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
 import * as Schema from "effect/Schema";
 import YAML from "yaml";
-import { manifestFilenameForType, manifestSchemaForType, } from "@agentxm/registry-protocol/unstable/publish/manifest-policy";
-import { parseFrontmatterEffect, } from "@agentxm/registry-protocol/unstable/content/frontmatter";
-import { copyExtensionDirectory } from "@agentxm/extension-workspace";
-import { NativeImportConflict, NativeImportFailed, NativeImportInvalid, NativeImportUnsupported, } from "@agentxm/extension-workspace";
+import { manifestFilenameForType, manifestSchemaForType } from "@agentxm/extension-content";
+import { parseFrontmatterEffect } from "@agentxm/extension-content";
+import { copyExtensionDirectory } from "@agentxm/extension-materialization";
+import { NativeImportConflict, NativeImportFailed, NativeImportInvalid, NativeImportUnsupported, } from "./authored-package-errors.js";
 const NATIVE_IMPORT_VERSION = "0.1.0";
 const MANIFEST_FILENAMES = new Set([
     "skill.json",

package/dist/src/index.d.ts

@@ -1,22 +1,31 @@
 /**
- * Extension-authoring feature: new-extension scaffolding, fork, native
- * import, authored identity decoding, and authored pack membership. The
- * application supplies the failure adapter that serializes authoring
- * failures into the plan-step vocabulary.
+ * Extension-authoring feature: creating new authored packages, forking and
+ * importing existing ones, authored identity decoding, and authored pack
+ * membership. Every use case settles its decisions in a `prepare` phase that
+ * writes nothing and resolves them in `previewOrApply`; failures are typed
+ * and carry the facts a person needs to recover.
  *
  * @experimental All exports from this module are unstable and may change without notice.
  * @packageDocumentation
  */
 export { AuthoringFailed } from "./errors.js";
-export { AuthoringFailureAdapter, withAdaptedStepFailures, type AuthoringFailureAdapterService, } from "./failure-adapter.js";
-export { decodeDesiredExtensionIdentity, type DecodedDesiredExtensionIdentity, type DesiredPackageAuthority, } from "./desired-identity.js";
+export { CreateDestinationInspectionFailed, CreateNameConfigured, ForkPackageConflict, ForkPackageFailed, ForkPackageInvalid, NativeImportConflict, NativeImportFailed, NativeImportInvalid, NativeImportUnsupported, type AuthoredPackageError, } from "./authored-package-errors.js";
+export { authoringStepFailure, type AuthoringStepFailure } from "./step-failure.js";
 export { forkExtensionPackage, type ForkExtensionPackageArgs } from "./fork-package.js";
 export { importNativeExtensionPackage, type ImportNativeExtensionPackageArgs, type NativeImportError, } from "./import-native-package.js";
 export { preflightCreateOnly, type CreateOnlyPreflightArgs } from "./create-preflight.js";
+export { authoredDeclaration, type AuthoredDeclaration, type AuthoredDeclarationState, } from "./authored-declaration.js";
 export { markerFqnForRef, type MarkerFqnRef } from "./marker-fqn.js";
-export { newSkill, type NewSkillOperation, type NewSkillOperationArgs, } from "./skills/new-skill.js";
-export { newHook, type NewHookOperation, type NewHookOperationArgs } from "./hooks/new-hook.js";
-export { newPack, type NewPackOperation, type NewPackOperationArgs } from "./packs/new-pack.js";
-export { addToPack, type AddToPackOperation, type AddToPackOperationArgs, } from "./packs/add-to-pack.js";
-export { removeFromPack, type RemoveFromPackOperation, type RemoveFromPackOperationArgs, } from "./packs/remove-from-pack.js";
+export { CreateExtension, createExtensionPlanName, prepareCreateExtension, previewOrApplyCreateExtension, type CreatableExtensionType, type CreateExtensionCandidate, type CreateExtensionFailure, type CreateExtensionRequest, type CreateExtensionRequirements, type CreateHookRequest, type CreateKnowledgeRequest, type CreateMcpServerRequest, type CreatePackRequest, type CreateRuleRequest, type CreateSkillRequest, type CreateSubagentRequest, type PrepareCreateExtensionRequirements, } from "./create/create-extension.js";
+export { AuthoringOwnerMismatch, AuthoringOwnerRequired, AuthoringScopeUnsupported, ScaffoldNameInvalid, } from "./create/errors.js";
+export { requireAuthoredOwner, resolveAuthoringOwner, settingsRelativePath, type AuthoringOwner, type AuthoringTarget, } from "./create/authoring-owner.js";
+export { SCAFFOLD_NAME_MAX_LENGTH, SCAFFOLD_NAME_PATTERN, isValidScaffoldName, normalizeScaffoldOwner, } from "./create/scaffold-name.js";
+export { hookEntrypointFilename } from "./create/scaffolds/hook.js";
+export { ChangePackMembership, packMembershipPlanName, preparePackMembership, previewOrApplyPackMembership, type PackMembershipCandidate, type PackMembershipChange, type PackMembershipRequest, type PackMembershipRequirements, type PackMembershipUnchanged, } from "./packs/change-pack-membership.js";
+export { PackGraphInvalid, PackManifestUnavailable, PackMemberAmbiguous, PackMemberNotDeclared, PackMemberNotFound, PackMemberUnmanaged, PackNotAuthored, PackNotConfigured, PackOwnerUnconfigured, PackSelectorAmbiguous, PackSelectorNotAPack, PackSourceMissing, type PackMembershipError, } from "./packs/membership-errors.js";
+export { ForkExtension, forkExtensionPlanName, prepareForkExtension, previewOrApplyForkExtension, type ForkExtensionCandidate, type ForkExtensionFailure, type ForkExtensionRequest, type ForkExtensionRequirements, type PrepareForkExtensionRequirements, } from "./fork/fork-extension.js";
+export { AdoptExtension, adoptExtensionPlanName, prepareAdoptExtension, previewOrApplyAdoptExtension, type AdoptExtensionCandidate, type AdoptExtensionFailure, type AdoptExtensionRequest, type AdoptExtensionRequirements, type PrepareAdoptExtensionRequirements, } from "./adopt/adopt-extension.js";
+export { ImportNativeExtension, importNativeExtensionPlanName, prepareImportNativeExtension, previewOrApplyImportNativeExtension, type ImportNativeExtensionCandidate, type ImportNativeExtensionFailure, type ImportNativeExtensionRequest, type ImportNativeExtensionRequirements, type ImportNativeMcpServerRequest, type ImportNativeSkillRequest, type ImportNativeSubagentRequest, type NativeImportType, type NativeMcpCandidate, type NativeMcpDiscovery, type PrepareImportNativeExtensionRequirements, } from "./import/import-native-extension.js";
+export { ChangeAuthoredVersion, changeAuthoredVersionPlanName, prepareChangeAuthoredVersion, previewOrApplyChangeAuthoredVersion, type AuthoredVersionChange, type ChangeAuthoredVersionCandidate, type ChangeAuthoredVersionFailure, type ChangeAuthoredVersionRequest, type ChangeAuthoredVersionRequirements, type PrepareChangeAuthoredVersionRequirements, type VersionBumpRule, } from "./version/change-authored-version.js";
+export { AuthoredManifestUnavailable, VersionTargetIdentityMismatch, VersionTargetInvalid, VersionTargetNotAuthored, type AuthoredVersionError, } from "./version/errors.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -1,24 +1,37 @@
 /**
- * Extension-authoring feature: new-extension scaffolding, fork, native
- * import, authored identity decoding, and authored pack membership. The
- * application supplies the failure adapter that serializes authoring
- * failures into the plan-step vocabulary.
+ * Extension-authoring feature: creating new authored packages, forking and
+ * importing existing ones, authored identity decoding, and authored pack
+ * membership. Every use case settles its decisions in a `prepare` phase that
+ * writes nothing and resolves them in `previewOrApply`; failures are typed
+ * and carry the facts a person needs to recover.
  *
  * @experimental All exports from this module are unstable and may change without notice.
  * @packageDocumentation
  */
 export { AuthoringFailed } from "./errors.js";
-export { AuthoringFailureAdapter, withAdaptedStepFailures, } from "./failure-adapter.js";
-export { decodeDesiredExtensionIdentity, } from "./desired-identity.js";
+export { CreateDestinationInspectionFailed, CreateNameConfigured, ForkPackageConflict, ForkPackageFailed, ForkPackageInvalid, NativeImportConflict, NativeImportFailed, NativeImportInvalid, NativeImportUnsupported, } from "./authored-package-errors.js";
+export { authoringStepFailure } from "./step-failure.js";
 export { forkExtensionPackage } from "./fork-package.js";
 export { importNativeExtensionPackage, } from "./import-native-package.js";
 export { preflightCreateOnly } from "./create-preflight.js";
+export { authoredDeclaration, } from "./authored-declaration.js";
 export { markerFqnForRef } from "./marker-fqn.js";
-// Scaffolding operations
-export { newSkill, } from "./skills/new-skill.js";
-export { newHook } from "./hooks/new-hook.js";
-export { newPack } from "./packs/new-pack.js";
-// Authored pack membership operations
-export { addToPack, } from "./packs/add-to-pack.js";
-export { removeFromPack, } from "./packs/remove-from-pack.js";
+// Creating a new authored extension
+export { CreateExtension, createExtensionPlanName, prepareCreateExtension, previewOrApplyCreateExtension, } from "./create/create-extension.js";
+export { AuthoringOwnerMismatch, AuthoringOwnerRequired, AuthoringScopeUnsupported, ScaffoldNameInvalid, } from "./create/errors.js";
+export { requireAuthoredOwner, resolveAuthoringOwner, settingsRelativePath, } from "./create/authoring-owner.js";
+export { SCAFFOLD_NAME_MAX_LENGTH, SCAFFOLD_NAME_PATTERN, isValidScaffoldName, normalizeScaffoldOwner, } from "./create/scaffold-name.js";
+export { hookEntrypointFilename } from "./create/scaffolds/hook.js";
+// Changing an authored pack's membership
+export { ChangePackMembership, packMembershipPlanName, preparePackMembership, previewOrApplyPackMembership, } from "./packs/change-pack-membership.js";
+export { PackGraphInvalid, PackManifestUnavailable, PackMemberAmbiguous, PackMemberNotDeclared, PackMemberNotFound, PackMemberUnmanaged, PackNotAuthored, PackNotConfigured, PackOwnerUnconfigured, PackSelectorAmbiguous, PackSelectorNotAPack, PackSourceMissing, } from "./packs/membership-errors.js";
+// Forking a managed package into workspace authorship
+export { ForkExtension, forkExtensionPlanName, prepareForkExtension, previewOrApplyForkExtension, } from "./fork/fork-extension.js";
+// Adopting an acquired package into workspace authorship
+export { AdoptExtension, adoptExtensionPlanName, prepareAdoptExtension, previewOrApplyAdoptExtension, } from "./adopt/adopt-extension.js";
+// Importing native content as an authored package
+export { ImportNativeExtension, importNativeExtensionPlanName, prepareImportNativeExtension, previewOrApplyImportNativeExtension, } from "./import/import-native-extension.js";
+// Changing an authored manifest's version
+export { ChangeAuthoredVersion, changeAuthoredVersionPlanName, prepareChangeAuthoredVersion, previewOrApplyChangeAuthoredVersion, } from "./version/change-authored-version.js";
+export { AuthoredManifestUnavailable, VersionTargetIdentityMismatch, VersionTargetInvalid, VersionTargetNotAuthored, } from "./version/errors.js";
 //# sourceMappingURL=index.js.map

package/dist/src/packs/add-to-pack.d.ts

@@ -7,11 +7,11 @@
  */
 import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
-import { AuthoringFailureAdapter } from "../failure-adapter.js";
 import type { Handle } from "@agentxm/extension-model/unstable/extensions";
 import type { OperationHandler } from "@agentxm/workspace-operations";
 import type { Operation } from "@agentxm/workspace-operations";
 import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { WorkspaceTransactionScope } from "@agentxm/workspace-transactions";
 /**
  * Args for the add-to-pack operation.
  */
@@ -40,5 +40,5 @@ export type AddToPackOperation = Operation<"add-to-pack", AddToPackOperationArgs
  * 4. Apply additions to manifest
  * 5. Write updated manifest
  */
-export declare const addToPack: OperationHandler<AddToPackOperation, FileSystem.FileSystem | Path.Path | WorkspaceMutations | AuthoringFailureAdapter>;
+export declare const addToPack: OperationHandler<AddToPackOperation, FileSystem.FileSystem | Path.Path | WorkspaceMutations | WorkspaceTransactionScope>;
 //# sourceMappingURL=add-to-pack.d.ts.map

package/dist/src/packs/add-to-pack.js

@@ -10,8 +10,9 @@ import * as Path from "effect/Path";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import { AuthoringFailed } from "../errors.js";
-import { AuthoringFailureAdapter, withAdaptedStepFailures } from "../failure-adapter.js";
+import { authoringStepFailure } from "../step-failure.js";
 import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { WorkspaceTransactionScope, runWorkspaceTransaction, } from "@agentxm/workspace-transactions";
 import { isWorkspaceSourceLocator } from "@agentxm/extension-model/unstable/sources/workspace";
 import { PACK_MANIFEST_FILENAME, PackManifestSchema, } from "@agentxm/extension-model/unstable/packs/manifest-schema";
 import { packManifestArtifact } from "./artifact.js";
@@ -52,7 +53,7 @@ export const addToPack = (op) => Effect.gen(function* () {
         return { result: "success", message: "No pack entries added" };
     }
     const manifestPath = path.join(ws.layout.authoredRoot("pack"), packName, PACK_MANIFEST_FILENAME);
-    yield* ws.runTransaction({
+    yield* runWorkspaceTransaction({
         targets: [manifestPath],
         transition: Effect.gen(function* () {
             // Read and stale-check under the workspace lock.
@@ -143,5 +144,5 @@ export const addToPack = (op) => Effect.gen(function* () {
             fileCount: 1,
         }),
     };
-}).pipe(withAdaptedStepFailures);
+}).pipe(Effect.mapError(authoringStepFailure));
 //# sourceMappingURL=add-to-pack.js.map

package/dist/src/packs/change-pack-membership.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Changing which extensions an authored pack declares.
+ *
+ * A pack's membership is a manifest an author owns, so both directions share
+ * one use case: find the pack the selector names, confirm the workspace
+ * authors it, read the manifest under a plan-time hash, decide which members
+ * the selector resolves to, and reduce that to a delta. An empty delta is a
+ * settled outcome, not a failure.
+ *
+ * @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 ExecutionCandidate, type PlanExecution } from "@agentxm/workspace-operations";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import type { WorkspaceTransactionScope } from "@agentxm/workspace-transactions";
+import { PackGraphInvalid, PackManifestUnavailable, PackMemberAmbiguous, PackMemberNotDeclared, PackMemberNotFound, PackMemberUnmanaged, PackNotAuthored, PackOwnerUnconfigured, PackSourceMissing } from "./membership-errors.js";
+export interface PackMembershipRequest {
+    /** Which direction the membership changes. */
+    readonly change: "add" | "remove";
+    /** Configured pack name, or an owner-qualified pack identity. */
+    readonly pack: string;
+    /** A member name, an owner-qualified identity, or a glob pattern. */
+    readonly selector: string;
+}
+/** What a membership step requires when it runs. */
+export type PackMembershipRequirements = FileSystem.FileSystem | Path.Path | WorkspaceMutations | WorkspaceTransactionScope;
+export interface PackMembershipChange {
+    readonly _tag: "Change";
+    readonly change: "add" | "remove";
+    /** Configured name of the pack being edited. */
+    readonly pack: string;
+    /** Owner-qualified identities the manifest gains or loses, sorted. */
+    readonly members: ReadonlyArray<string>;
+    readonly execution: ExecutionCandidate<PackMembershipRequirements>;
+}
+export interface PackMembershipUnchanged {
+    readonly _tag: "NoChange";
+    readonly change: "add" | "remove";
+    readonly pack: string;
+}
+/** A settled membership request: either a delta to resolve, or nothing to do. */
+export type PackMembershipCandidate = PackMembershipChange | PackMembershipUnchanged;
+/** Settle a membership change without writing anything. */
+export declare const preparePackMembership: (request: PackMembershipRequest) => Effect.Effect<PackMembershipChange | PackMembershipUnchanged, import("@agentxm/workspace-state").SettingsIoError | import("@agentxm/workspace-state").SettingsParseError | import("@agentxm/workspace-state").SettingsDecodeError | import("@agentxm/workspace-state").WorkspaceRootEscape | import("@agentxm/workspace-state").LockfileIoError | import("@agentxm/workspace-state").LockfileParseError | import("@agentxm/workspace-state").LockfileDecodeError | import("@agentxm/workspace-state").LockfileVersionUnsupported | import("@agentxm/workspace-state").LockfileValidationError | import("@agentxm/workspace-state").PathTraversalDetected | import("@agentxm/workspace-state").LockEntrySourceMissing | import("@agentxm/workspace-state").LockEntryUrlInvalid | import("@agentxm/workspace-state").LockEntryNameInvalid | import("@agentxm/workspace-state").LockEntryEndpointConflict | import("@agentxm/workspace-state").LockEntrySourceTypeConflict | import("@agentxm/workspace-state").AcceptedResolutionMissing | import("@agentxm/workspace-state").InlineExtensionSourceMissing | import("@agentxm/workspace-state").PackageContentHashFailed | import("@agentxm/workspace-state").WorkspaceSourceInvalid | import("@agentxm/workspace-operations").CandidateFingerprintFailed | import("./membership-errors.js").PackSelectorNotAPack | import("./membership-errors.js").PackNotConfigured | import("./membership-errors.js").PackSelectorAmbiguous | PackSourceMissing | PackNotAuthored | PackOwnerUnconfigured | PackManifestUnavailable | PackGraphInvalid | PackMemberAmbiguous | PackMemberUnmanaged | PackMemberNotFound | PackMemberNotDeclared, FileSystem.FileSystem | Path.Path | WorkspaceMutations | import("@agentxm/workspace-state").ConfiguredAgentOutcomesProvider>;
+/** The plan a membership change of this direction resolves. */
+export declare const packMembershipPlanName: (change: "add" | "remove") => string;
+/** Preview or apply a settled membership change. */
+export declare const previewOrApplyPackMembership: (candidate: PackMembershipChange, execution: PlanExecution) => Effect.Effect<import("@agentxm/workspace-operations").OperationResolution<never>, import("@agentxm/workspace-state").WorkspaceSettingsReadFailure | import("@agentxm/workspace-operations").ApprovalRecoveryMissing | import("@agentxm/workspace-operations").PlanInteractionFailed | import("@agentxm/workspace-transactions").WorkspaceTransitionAcquireFailure, import("@agentxm/workspace-state").ConfiguredAgentOutcomesProvider | import("@agentxm/workspace-operations").OperationJournal | import("@agentxm/workspace-operations").ResolvePlanInteraction | import("@agentxm/workspace-transactions").FootprintRecorder | PackMembershipRequirements>;
+/** The pack-membership use case: settle a request, then preview or apply it. */
+export declare const ChangePackMembership: {
+    readonly prepare: (request: PackMembershipRequest) => Effect.Effect<PackMembershipChange | PackMembershipUnchanged, import("@agentxm/workspace-state").SettingsIoError | import("@agentxm/workspace-state").SettingsParseError | import("@agentxm/workspace-state").SettingsDecodeError | import("@agentxm/workspace-state").WorkspaceRootEscape | import("@agentxm/workspace-state").LockfileIoError | import("@agentxm/workspace-state").LockfileParseError | import("@agentxm/workspace-state").LockfileDecodeError | import("@agentxm/workspace-state").LockfileVersionUnsupported | import("@agentxm/workspace-state").LockfileValidationError | import("@agentxm/workspace-state").PathTraversalDetected | import("@agentxm/workspace-state").LockEntrySourceMissing | import("@agentxm/workspace-state").LockEntryUrlInvalid | import("@agentxm/workspace-state").LockEntryNameInvalid | import("@agentxm/workspace-state").LockEntryEndpointConflict | import("@agentxm/workspace-state").LockEntrySourceTypeConflict | import("@agentxm/workspace-state").AcceptedResolutionMissing | import("@agentxm/workspace-state").InlineExtensionSourceMissing | import("@agentxm/workspace-state").PackageContentHashFailed | import("@agentxm/workspace-state").WorkspaceSourceInvalid | import("@agentxm/workspace-operations").CandidateFingerprintFailed | import("./membership-errors.js").PackSelectorNotAPack | import("./membership-errors.js").PackNotConfigured | import("./membership-errors.js").PackSelectorAmbiguous | PackSourceMissing | PackNotAuthored | PackOwnerUnconfigured | PackManifestUnavailable | PackGraphInvalid | PackMemberAmbiguous | PackMemberUnmanaged | PackMemberNotFound | PackMemberNotDeclared, FileSystem.FileSystem | Path.Path | WorkspaceMutations | import("@agentxm/workspace-state").ConfiguredAgentOutcomesProvider>;
+    readonly previewOrApply: (candidate: PackMembershipChange, execution: PlanExecution) => Effect.Effect<import("@agentxm/workspace-operations").OperationResolution<never>, import("@agentxm/workspace-state").WorkspaceSettingsReadFailure | import("@agentxm/workspace-operations").ApprovalRecoveryMissing | import("@agentxm/workspace-operations").PlanInteractionFailed | import("@agentxm/workspace-transactions").WorkspaceTransitionAcquireFailure, import("@agentxm/workspace-state").ConfiguredAgentOutcomesProvider | import("@agentxm/workspace-operations").OperationJournal | import("@agentxm/workspace-operations").ResolvePlanInteraction | import("@agentxm/workspace-transactions").FootprintRecorder | PackMembershipRequirements>;
+};
+//# sourceMappingURL=change-pack-membership.d.ts.map