@agentxm/extension-authoring 0.28.12 → 0.28.13

package/dist/src/create/create-extension.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Creating a new authored extension.
+ *
+ * One use case for every extension type: the owner the package is created
+ * under, the name it may carry, the canonical location it occupies, the
+ * create-only refusal that protects existing content, the desired-state
+ * entry that declares it, and the projection that makes it observable are all
+ * decided here. What differs per type — the manifest and starter body — is a
+ * scaffold; what differs per command — flags, wording, exit codes — stays in
+ * the application.
+ *
+ * `prepare` decides everything and writes nothing: it settles ownership,
+ * naming, and collisions, then freezes an execution candidate. `previewOrApply`
+ * resolves that same candidate, so preview and apply describe one decision
+ * rather than two.
+ *
+ * @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 * as Path from "effect/Path";
+import { ExtensionManagers, type ManagerRequirements, type RecipeRequirements } from "@agentxm/extension-materialization";
+import { McpSecretStore } from "@agentxm/extension-materialization";
+import { type Handle } from "@agentxm/extension-model/unstable/extensions";
+import type { HookEvent, HookRuntime } from "@agentxm/extension-model/unstable/hooks/manifest-schema";
+import { type ExecutionCandidate, type PlanExecution } from "@agentxm/workspace-operations";
+import { CodingAgentRepository } from "@agentxm/workspace-projection";
+import type { CredentialStore } from "@agentxm/registry-auth";
+import type { RegistryUrl } from "@agentxm/registry-client";
+import type { FqnInvalidError } from "@agentxm/extension-model/unstable/extensions";
+import type { CandidateFingerprintFailed } from "@agentxm/workspace-operations";
+import { WorkspaceMutations, type ConfiguredAgentOutcomesProvider } from "@agentxm/workspace-state";
+import { type AuthoringStepFailure } from "../step-failure.js";
+import { AuthoringScopeUnsupported, ScaffoldNameInvalid, type AuthoringOwnerMismatch, type AuthoringOwnerRequired } from "./errors.js";
+interface CreateRequestBase {
+    /** Name without owner, as the person typed it. */
+    readonly name: string;
+    /** An explicitly requested owner, if the person named one. */
+    readonly owner: Option.Option<string>;
+}
+export interface CreateSkillRequest extends CreateRequestBase {
+    readonly type: "skill";
+}
+export interface CreateSubagentRequest extends CreateRequestBase {
+    readonly type: "subagent";
+}
+export interface CreateRuleRequest extends CreateRequestBase {
+    readonly type: "rule";
+    readonly title: Option.Option<string>;
+}
+export interface CreateHookRequest extends CreateRequestBase {
+    readonly type: "hook";
+    readonly runtime: HookRuntime;
+    readonly event: HookEvent;
+    readonly matcher: Option.Option<string>;
+}
+export interface CreateKnowledgeRequest extends CreateRequestBase {
+    readonly type: "knowledge";
+    readonly description: Option.Option<string>;
+}
+export interface CreatePackRequest extends CreateRequestBase {
+    readonly type: "pack";
+}
+export interface CreateMcpServerRequest extends CreateRequestBase {
+    readonly type: "mcp-server";
+    readonly description: Option.Option<string>;
+    /**
+     * Whether the invoking surface can prompt for a connection input the
+     * manifest requires. A new server scaffolds a placeholder package with no
+     * required inputs, so this only decides how a hand-edited manifest behaves
+     * on a second run.
+     */
+    readonly nonInteractive: boolean;
+}
+/** What an author asked to create. */
+export type CreateExtensionRequest = CreateSkillRequest | CreateSubagentRequest | CreateRuleRequest | CreateHookRequest | CreateKnowledgeRequest | CreatePackRequest | CreateMcpServerRequest;
+/** The extension types `CreateExtension` scaffolds. */
+export type CreatableExtensionType = CreateExtensionRequest["type"];
+/** What every step in this creation may require when it runs. */
+export type CreateExtensionRequirements = ManagerRequirements | RecipeRequirements | WorkspaceMutations | CodingAgentRepository | McpSecretStore;
+/**
+ * A settled creation: every decision is made and nothing is written. The
+ * execution candidate carries the frozen plan; the identity fields answer
+ * what the application renders around it.
+ */
+export interface CreateExtensionCandidate {
+    readonly type: CreatableExtensionType;
+    /** Owner-qualified identity of the package being created. */
+    readonly fqn: string;
+    readonly owner: Handle;
+    readonly name: string;
+    /** Workspace-relative directory the package occupies. */
+    readonly authoredPath: string;
+    /** Workspace-relative file the author edits next. */
+    readonly entryPath: string;
+    /** Workspace-relative settings file the declaration is written to. */
+    readonly settingsPath: string;
+    readonly execution: ExecutionCandidate<CreateExtensionRequirements>;
+}
+/** Every failure settling a creation can surface before anything is written. */
+export type CreateExtensionFailure = AuthoringStepFailure | AuthoringOwnerRequired | AuthoringOwnerMismatch | ScaffoldNameInvalid | AuthoringScopeUnsupported | CandidateFingerprintFailed | FqnInvalidError;
+/** Everything settling a creation reads before it freezes a candidate. */
+export type PrepareCreateExtensionRequirements = FileSystem.FileSystem | Path.Path | CredentialStore | RegistryUrl | WorkspaceMutations | CodingAgentRepository | ConfiguredAgentOutcomesProvider | ExtensionManagers;
+/**
+ * The plan a creation of this type resolves. It names the operation in
+ * previews, in machine output, and in an interruption report, so the feature
+ * that builds the plan owns it rather than each command restating it.
+ */
+export declare const createExtensionPlanName: (type: CreatableExtensionType) => string;
+/**
+ * Settle a creation without writing anything.
+ *
+ * The create-only refusal runs here so a preview refuses an occupied name,
+ * and again inside the transaction so a candidate that went stale between
+ * preview and apply writes nothing.
+ */
+export declare const prepareCreateExtension: (request: CreateExtensionRequest) => Effect.Effect<CreateExtensionCandidate, CreateExtensionFailure, PrepareCreateExtensionRequirements>;
+/** Preview or apply a settled creation, resolving to one operation outcome. */
+export declare const previewOrApplyCreateExtension: (candidate: CreateExtensionCandidate, 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, CreateExtensionRequirements | ConfiguredAgentOutcomesProvider | import("@agentxm/workspace-operations").OperationJournal | import("@agentxm/workspace-operations").ResolvePlanInteraction | import("@agentxm/workspace-transactions").FootprintRecorder>;
+/** The creation use case: settle a request, then preview or apply it. */
+export declare const CreateExtension: {
+    readonly prepare: (request: CreateExtensionRequest) => Effect.Effect<CreateExtensionCandidate, CreateExtensionFailure, PrepareCreateExtensionRequirements>;
+    readonly previewOrApply: (candidate: CreateExtensionCandidate, 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, CreateExtensionRequirements | ConfiguredAgentOutcomesProvider | import("@agentxm/workspace-operations").OperationJournal | import("@agentxm/workspace-operations").ResolvePlanInteraction | import("@agentxm/workspace-transactions").FootprintRecorder>;
+};
+export {};
+//# sourceMappingURL=create-extension.d.ts.map

package/dist/src/create/create-extension.js

@@ -0,0 +1,440 @@
+/**
+ * Creating a new authored extension.
+ *
+ * One use case for every extension type: the owner the package is created
+ * under, the name it may carry, the canonical location it occupies, the
+ * create-only refusal that protects existing content, the desired-state
+ * entry that declares it, and the projection that makes it observable are all
+ * decided here. What differs per type — the manifest and starter body — is a
+ * scaffold; what differs per command — flags, wording, exit codes — stays in
+ * the application.
+ *
+ * `prepare` decides everything and writes nothing: it settles ownership,
+ * naming, and collisions, then freezes an execution candidate. `previewOrApply`
+ * resolves that same candidate, so preview and apply describe one decision
+ * rather than two.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { ExtensionManagers, buildAuthoredExtensionStep, buildNewExtensionStep, createCanonicalDirectory, groupInstallTargetsByDirectory, recoverCanonicalDirectory, artifactAgentIdsFromTargets, artifactTargetAgentIds, } from "@agentxm/extension-materialization";
+import { McpSecretStore, materializeAuthoredMcpServer } from "@agentxm/extension-materialization";
+import { CONFIGURABLE_AGENTS_BY_ID } from "@agentxm/extension-model/unstable/agent-capabilities";
+import { toExtensionTypePlural, formatFqn, decodeExtensionNameSync, } from "@agentxm/extension-model/unstable/extensions";
+import { operationPresentation, prepareExecutionCandidate, resolveExecutionCandidate, } from "@agentxm/workspace-operations";
+import { CodingAgentRepository } from "@agentxm/workspace-projection";
+import { WorkspaceMutations, computeExtensionPathsForLayout, computePackPathsForLayout, computeSourceHash, } from "@agentxm/workspace-state";
+import { authoredDeclaration } from "../authored-declaration.js";
+import { preflightCreateOnly } from "../create-preflight.js";
+import { authoringStepFailure } from "../step-failure.js";
+import { resolveAuthoringOwner, settingsRelativePath } from "./authoring-owner.js";
+import { AuthoringScopeUnsupported, ScaffoldNameInvalid, } from "./errors.js";
+import { hookScaffold } from "./scaffolds/hook.js";
+import { knowledgeScaffold } from "./scaffolds/knowledge.js";
+import { mcpServerScaffold } from "./scaffolds/mcp-server.js";
+import { packScaffold } from "./scaffolds/pack.js";
+import { ruleScaffold } from "./scaffolds/rule.js";
+import { skillScaffold } from "./scaffolds/skill.js";
+import { subagentScaffold } from "./scaffolds/subagent.js";
+import { SCAFFOLD_NAME_MAX_LENGTH, SCAFFOLD_NAME_PATTERN, isValidScaffoldName, } from "./scaffold-name.js";
+// -----------------------------------------------------------------------------
+// Per-type facts
+// -----------------------------------------------------------------------------
+/** How each type reads its declarations and writes the one it creates. */
+const declaration = (ws, type, name) => {
+    const target = authoredDeclaration(ws, type, name);
+    return {
+        isConfigured: target.read.pipe(Effect.map((current) => current.configured)),
+        declare: target.declare({ enabled: true }),
+    };
+};
+const scaffoldFor = (request, owner) => {
+    switch (request.type) {
+        case "skill":
+            return skillScaffold({ name: request.name, owner });
+        case "subagent":
+            return subagentScaffold({ name: request.name, owner });
+        case "rule":
+            return ruleScaffold({ name: request.name, owner, title: request.title });
+        case "hook":
+            return hookScaffold({
+                name: request.name,
+                owner,
+                runtime: request.runtime,
+                event: request.event,
+                matcher: request.matcher,
+            });
+        case "knowledge":
+            return knowledgeScaffold({ name: request.name, owner, description: request.description });
+        case "pack":
+            return packScaffold({ name: request.name, owner });
+        case "mcp-server":
+            return mcpServerScaffold({
+                name: request.name,
+                owner,
+                description: Option.getOrElse(request.description, () => ""),
+            });
+    }
+};
+/** The subject and command route a refusal names, per type. */
+const route = (type) => {
+    switch (type) {
+        case "skill":
+            return { subject: "skill", command: "skills new" };
+        case "subagent":
+            return { subject: "subagent", command: "subagents new" };
+        case "rule":
+            return { subject: "rule", command: "rules new" };
+        case "hook":
+            return { subject: "hook", command: "hooks new" };
+        case "knowledge":
+            return { subject: "knowledge bundle", command: "knowledge new" };
+        case "pack":
+            return { subject: "pack", command: "packs new" };
+        case "mcp-server":
+            return { subject: "MCP server", command: "mcps new" };
+    }
+};
+/**
+ * The plan a creation of this type resolves. It names the operation in
+ * previews, in machine output, and in an interruption report, so the feature
+ * that builds the plan owns it rather than each command restating it.
+ */
+export const createExtensionPlanName = (type) => `New ${route(type).subject}`;
+/** The canonical directory an authored package of this type occupies. */
+const canonicalLocation = (path, ws, type, owner, name) => type === "pack"
+    ? computePackPathsForLayout(path.join, ws.layout, "workspace", owner, name).canonicalPath
+    : computeExtensionPathsForLayout(path.join, ws.layout, { refType: "workspace", owner }, toExtensionTypePlural(type), name).canonicalPath;
+/**
+ * Where a skill becomes observable: the universal location and every
+ * configured agent that can represent one. Preview and apply read the same
+ * function, so a preview lists exactly the locations an apply writes.
+ */
+const skillTargetLocations = Effect.fn("CreateExtension.skillTargetLocations")(function* () {
+    const ws = yield* WorkspaceMutations;
+    const path = yield* Path.Path;
+    const agents = yield* (yield* CodingAgentRepository).getMaterializationAgents();
+    const resolved = yield* Effect.forEach(agents, (agent) => agent
+        .resolveEffectiveSkillsDir({ workspaceRoot: ws.baseDir })
+        .pipe(Effect.map((outcome) => ({ agentId: agent.id, outcome }))), { concurrency: "unbounded" });
+    const installable = [];
+    for (const { agentId, outcome } of resolved) {
+        if (outcome._tag === "supported") {
+            installable.push({ agentId, targetDir: path.normalize(outcome.dir) });
+        }
+    }
+    return { installable, locations: yield* groupInstallTargetsByDirectory(installable, ws.baseDir) };
+});
+/**
+ * Where a newly declared MCP connection becomes observable: the MCP config
+ * every configured agent reads for the selected scope. Preview and apply read
+ * the same forecast, so a preview lists exactly the files an apply writes.
+ */
+const mcpAgentConfigTargets = Effect.fn("CreateExtension.mcpAgentConfigTargets")(function* () {
+    const ws = yield* WorkspaceMutations;
+    const path = yield* Path.Path;
+    const configuredAgentIds = yield* ws.getConfiguredAgents();
+    const catalogAgents = Object.values(CONFIGURABLE_AGENTS_BY_ID);
+    const agentsByConfigPath = new Map();
+    for (const agentId of configuredAgentIds) {
+        const agent = catalogAgents.find((candidate) => candidate.id === agentId);
+        const capability = agent?.capabilities["mcp-server"];
+        if (capability === undefined || capability.axm.writer === null)
+            continue;
+        for (const target of capability.axm.writer.config.targets) {
+            if (target.scope !== ws.scope)
+                continue;
+            const configPath = path.relative(ws.baseDir, path.resolve(ws.baseDir, target.path));
+            const agentIds = agentsByConfigPath.get(configPath) ?? new Set();
+            agentIds.add(agentId);
+            agentsByConfigPath.set(configPath, agentIds);
+        }
+    }
+    return Array.from(agentsByConfigPath.entries())
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([configPath, agentIds]) => ({
+        path: configPath,
+        change: "created",
+        agentIds: Array.from(agentIds).sort(),
+    }));
+});
+/**
+ * Build the authored-creation step for a type whose canonical content is
+ * realized by an installer rather than by its own manager.
+ */
+const authoredPackageStep = (manager, args) => buildAuthoredExtensionStep(manager, args);
+/**
+ * Build the authored-creation step with the requirements this use case keeps
+ * in `R`. The recipe pins one requirement set across the manager and the
+ * closures, so naming it here is what lets the workspace facade and the agent
+ * repository stay requirements instead of captured values.
+ */
+const authoredStep = (manager, args) => buildNewExtensionStep(manager, args);
+// -----------------------------------------------------------------------------
+// prepare
+// -----------------------------------------------------------------------------
+/**
+ * Settle a creation without writing anything.
+ *
+ * The create-only refusal runs here so a preview refuses an occupied name,
+ * and again inside the transaction so a candidate that went stale between
+ * preview and apply writes nothing.
+ */
+export const prepareCreateExtension = Effect.fn("CreateExtension.prepare")(function* (request) {
+    const ws = yield* WorkspaceMutations;
+    const path = yield* Path.Path;
+    const managers = yield* ExtensionManagers;
+    const { subject, command } = route(request.type);
+    const { owner, establish } = yield* resolveAuthoringOwner({ subject, command, name: request.name }, request.owner);
+    if (!isValidScaffoldName(request.name)) {
+        return yield* new ScaffoldNameInvalid({
+            subject,
+            name: request.name,
+            pattern: SCAFFOLD_NAME_PATTERN.source,
+            maxLength: SCAFFOLD_NAME_MAX_LENGTH,
+        });
+    }
+    // Authored packages live in a project workspace; the user scope holds
+    // acquired content only.
+    if (ws.layout.scope !== "project") {
+        return yield* new AuthoringScopeUnsupported({ subject, scope: ws.layout.scope });
+    }
+    const name = request.name;
+    const scaffold = scaffoldFor(request, owner);
+    const location = canonicalLocation(path, ws, request.type, owner, name);
+    const authoredPath = path.relative(ws.baseDir, location);
+    const settingsPath = settingsRelativePath(path, ws);
+    const extensionName = decodeExtensionNameSync(name);
+    const fqn = formatFqn({ owner, type: request.type, name: extensionName });
+    const { isConfigured, declare } = declaration(ws, request.type, name);
+    const createOnly = Effect.gen(function* () {
+        yield* preflightCreateOnly({
+            subject: scaffold.subject,
+            name,
+            configured: yield* isConfigured,
+            destinations: [location],
+        });
+    });
+    yield* createOnly;
+    const contentTargets = scaffold.contentFiles.map((file) => ({
+        path: path.join(authoredPath, ...file.split("/")),
+        change: "created",
+    }));
+    const settingsTarget = { path: settingsPath, change: "created" };
+    const projected = request.type === "skill" ? yield* skillTargetLocations() : { installable: [], locations: [] };
+    const projectionTargets = projected.locations.map((target) => {
+        const agentIds = artifactTargetAgentIds(target.agentIds);
+        return {
+            path: path.relative(ws.baseDir, path.join(target.targetDir, name)),
+            change: "created",
+            ...(agentIds.length > 0 ? { agentIds } : {}),
+        };
+    });
+    const agentConfigTargets = request.type === "mcp-server" ? yield* mcpAgentConfigTargets() : [];
+    const plannedArtifact = {
+        path: authoredPath,
+        scope: ws.scope,
+        version: scaffold.version,
+        change: "created",
+        fileCount: scaffold.contentFiles.length,
+        targets: [...contentTargets, settingsTarget, ...projectionTargets, ...agentConfigTargets],
+    };
+    const common = {
+        toStepFailure: authoringStepFailure,
+        versionRange: Option.none(),
+        label: fqn,
+        message: `Created ${subject} ${fqn}`,
+        plannedArtifact,
+        preflight: Effect.gen(function* () {
+            yield* recoverCanonicalDirectory({ baseDir: ws.baseDir, canonicalPath: location });
+            yield* createOnly;
+        }),
+        scaffold: createCanonicalDirectory({
+            baseDir: ws.baseDir,
+            canonicalPath: location,
+            subject: scaffold.subject,
+            requiredFiles: scaffold.contentFiles,
+            populate: scaffold.populate,
+        }),
+        markAuthored: establish.pipe(Effect.andThen(declare)),
+    };
+    const sourceRef = {
+        refType: "workspace",
+        source: { type: "workspace", owner, extensionType: request.type, name: extensionName },
+        scope: ws.scope,
+        owner,
+        name: extensionName,
+        version: scaffold.version,
+        sourceHash: computeSourceHash("scaffold"),
+        location,
+    };
+    const step = (() => {
+        switch (request.type) {
+            case "skill":
+                return authoredStep(managers.skill, {
+                    ...common,
+                    ref: {
+                        ...sourceRef,
+                        type: "skill",
+                        source: { ...sourceRef.source, extensionType: "skill" },
+                        skill: { name: extensionName, description: Option.none(), metadata: Option.none() },
+                    },
+                    target: { type: "skill", name },
+                    buildArtifact: ({ installedBefore }) => Effect.gen(function* () {
+                        const change = installedBefore ? "updated" : "created";
+                        const { installable, locations } = yield* skillTargetLocations();
+                        const agents = artifactAgentIdsFromTargets(installable);
+                        return {
+                            path: authoredPath,
+                            scope: ws.scope,
+                            ...(agents.length > 0 ? { agents } : {}),
+                            version: scaffold.version,
+                            change,
+                            targets: [
+                                { path: authoredPath, change },
+                                { path: settingsPath, change },
+                                ...locations.map((target) => {
+                                    const agentIds = artifactTargetAgentIds(target.agentIds);
+                                    return {
+                                        path: path.relative(ws.baseDir, path.join(target.targetDir, name)),
+                                        change,
+                                        ...(agentIds.length > 0 ? { agentIds } : {}),
+                                    };
+                                }),
+                            ],
+                        };
+                    }),
+                });
+            case "subagent":
+                return authoredStep(managers.subagent, {
+                    ...common,
+                    ref: {
+                        ...sourceRef,
+                        type: "subagent",
+                        source: { ...sourceRef.source, extensionType: "subagent" },
+                        subagent: { name: extensionName, description: Option.none() },
+                    },
+                    target: { type: "subagent", name },
+                    buildArtifact: () => Effect.succeed(plannedArtifact),
+                });
+            case "rule":
+                return authoredStep(managers.rule, {
+                    ...common,
+                    ref: {
+                        ...sourceRef,
+                        type: "rule",
+                        source: { ...sourceRef.source, extensionType: "rule" },
+                        rule: { name: extensionName },
+                    },
+                    target: { type: "rule", name },
+                    buildArtifact: () => Effect.succeed(plannedArtifact),
+                });
+            case "hook":
+                return authoredStep(managers.hook, {
+                    ...common,
+                    ref: {
+                        ...sourceRef,
+                        type: "hook",
+                        source: { ...sourceRef.source, extensionType: "hook" },
+                        hook: { name: extensionName },
+                    },
+                    target: { type: "hook", name },
+                    buildArtifact: () => Effect.gen(function* () {
+                        // A hook becomes observable through the shared agent hook
+                        // configurations, so its realized targets are the aggregate
+                        // projection's, not the package's own files.
+                        const observation = yield* managers.hook.aggregateProjectionObservation;
+                        const targets = observation.targets.map((target) => ({
+                            ...target,
+                            change: "created",
+                        }));
+                        return {
+                            path: authoredPath,
+                            scope: ws.scope,
+                            version: scaffold.version,
+                            change: "created",
+                            ...(targets.length === 0 ? {} : { fileCount: targets.length, targets }),
+                        };
+                    }),
+                });
+            case "knowledge":
+                return authoredStep(managers.knowledge, {
+                    ...common,
+                    ref: {
+                        ...sourceRef,
+                        type: "knowledge",
+                        source: { ...sourceRef.source, extensionType: "knowledge" },
+                        knowledge: { name: extensionName },
+                    },
+                    target: { type: "knowledge", name },
+                    buildArtifact: () => Effect.succeed(plannedArtifact),
+                });
+            case "pack":
+                return authoredStep(managers.pack, {
+                    ...common,
+                    ref: {
+                        ...sourceRef,
+                        type: "pack",
+                        source: { ...sourceRef.source, extensionType: "pack" },
+                        pack: { name: extensionName, dependencies: {} },
+                    },
+                    target: { type: "pack", owner, name },
+                    buildArtifact: () => Effect.succeed(plannedArtifact),
+                });
+            case "mcp-server": {
+                // An MCP server's canonical content is realized by the install
+                // operation rather than by its manager, so the authored closure names
+                // that realization instead of the manager's default.
+                const nonInteractive = request.nonInteractive;
+                return authoredPackageStep(managers["mcp-server"], {
+                    ...common,
+                    target: { type: "mcp-server", name },
+                    location,
+                    enabled: true,
+                    materializeInstall: (ref) => materializeAuthoredMcpServer({ ref, nonInteractive }),
+                    buildArtifact: () => Effect.succeed(plannedArtifact),
+                });
+            }
+        }
+    })();
+    // A description is the one piece of package content a creation flag
+    // controls, so the operation says what it will record rather than leaving
+    // the author to read it back out of the written manifest.
+    const authoredSummary = request.type === "knowledge" || request.type === "mcp-server"
+        ? request.description
+        : Option.none();
+    const plan = {
+        _tag: "Plan",
+        name: createExtensionPlanName(request.type),
+        description: Option.some(Option.match(authoredSummary, {
+            onNone: () => `Create ${fqn}`,
+            onSome: (summary) => `Create ${fqn}: ${summary}`,
+        })),
+        presentation: operationPresentation({ imperative: "create", past: "Created", gerund: "Creating" }, request.type),
+        jobs: [{ concurrency: 1, steps: [step] }],
+    };
+    const execution = yield* prepareExecutionCandidate(plan);
+    return {
+        type: request.type,
+        fqn,
+        owner,
+        name,
+        authoredPath,
+        entryPath: path.join(authoredPath, ...scaffold.entryFile.split("/")),
+        settingsPath,
+        execution,
+    };
+});
+// -----------------------------------------------------------------------------
+// previewOrApply
+// -----------------------------------------------------------------------------
+/** Preview or apply a settled creation, resolving to one operation outcome. */
+export const previewOrApplyCreateExtension = (candidate, execution) => resolveExecutionCandidate(candidate.execution, execution);
+/** The creation use case: settle a request, then preview or apply it. */
+export const CreateExtension = {
+    prepare: prepareCreateExtension,
+    previewOrApply: previewOrApplyCreateExtension,
+};
+//# sourceMappingURL=create-extension.js.map

package/dist/src/create/errors.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Typed refusals the authoring request phase can settle with.
+ *
+ * Each one carries the facts a person needs to recover — the owners they
+ * could have meant, the settings file that records ownership, the name rule
+ * their name broke — and none of them carries rendered prose. The
+ * application boundary owns the sentence; the feature owns the decision.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+declare const AuthoringOwnerRequired_base: Schema.Class<AuthoringOwnerRequired, Schema.TaggedStruct<"AuthoringOwnerRequired", {
+    /** The thing being authored, e.g. `skill`. */
+    readonly subject: Schema.String;
+    /** The command route, so a recovery action is a runnable command. */
+    readonly command: Schema.String;
+    /** The name the person asked to create. */
+    readonly name: Schema.String;
+    /** Owners the person could have meant, most local first. */
+    readonly candidates: Schema.$Array<Schema.String>;
+    /** Workspace-relative settings file that would record the owner. */
+    readonly settingsPath: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * No owner is configured for the selected workspace and none was named, so
+ * the package has no authorship to carry. `candidates` are the owners the
+ * person could plausibly have meant, most local first; it may be empty.
+ */
+export declare class AuthoringOwnerRequired extends AuthoringOwnerRequired_base {
+}
+declare const AuthoringOwnerMismatch_base: Schema.Class<AuthoringOwnerMismatch, Schema.TaggedStruct<"AuthoringOwnerMismatch", {
+    readonly requested: Schema.String;
+    readonly configured: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** An explicitly named owner disagrees with the one the workspace records. */
+export declare class AuthoringOwnerMismatch extends AuthoringOwnerMismatch_base {
+}
+declare const ScaffoldNameInvalid_base: Schema.Class<ScaffoldNameInvalid, Schema.TaggedStruct<"ScaffoldNameInvalid", {
+    readonly subject: Schema.String;
+    readonly name: Schema.String;
+    /** The pattern source every authored name matches. */
+    readonly pattern: Schema.String;
+    readonly maxLength: Schema.Number;
+}>, import("effect/Cause").YieldableError>;
+/** The requested name is not a name an authored package can carry. */
+export declare class ScaffoldNameInvalid extends ScaffoldNameInvalid_base {
+}
+declare const AuthoringScopeUnsupported_base: Schema.Class<AuthoringScopeUnsupported, Schema.TaggedStruct<"AuthoringScopeUnsupported", {
+    readonly subject: Schema.String;
+    readonly scope: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Authoring was requested in a workspace scope that does not hold authored
+ * packages. Only the project workspace does.
+ */
+export declare class AuthoringScopeUnsupported extends AuthoringScopeUnsupported_base {
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map