@agentxm/extension-authoring 0.28.12 → 0.28.14-preview.1789139351.5cd4595aa

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

@@ -0,0 +1,71 @@
+/**
+ * Adopting an acquired package into workspace authorship.
+ *
+ * Adoption moves rather than copies: the canonical package the workspace
+ * acquired becomes the authored package, its accepted external resolution is
+ * retired, and its declaration is rewritten to name the workspace as its
+ * source. The activation it already carried is preserved, and a package that
+ * was never declared becomes enabled — adopting content you cannot see would
+ * leave the workspace holding authored work it never materializes.
+ *
+ * `prepare` settles the identity, the destination, and the activation, and
+ * writes nothing. `previewOrApply` resolves that same candidate inside the
+ * workspace transaction, so a failed move restores both directories.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import * as Path from "effect/Path";
+import { ExtensionManagers, McpSecretStore, type ManagerRequirements, type RecipeRequirements } from "@agentxm/extension-materialization";
+import { type ExtensionType, type FqnInvalidError, type Handle } from "@agentxm/extension-model/unstable/extensions";
+import { type CandidateFingerprintFailed, type ExecutionCandidate, type PlanExecution } from "@agentxm/workspace-operations";
+import type { CodingAgentRepository } from "@agentxm/workspace-projection";
+import { WorkspaceMutations, type ConfiguredAgentOutcomesProvider, type LockfileValidationError, type WorkspaceLockfileReadFailure, type WorkspaceSettingsReadFailure } from "@agentxm/workspace-state";
+import type { AuthoredPackageError } from "../authored-package-errors.js";
+import { AuthoringFailed } from "../errors.js";
+import { AuthoringScopeUnsupported, type AuthoringOwnerMismatch, type AuthoringOwnerRequired } from "../create/errors.js";
+export interface AdoptExtensionRequest {
+    /** Canonical, owner-qualified identity of the package being adopted. */
+    readonly fqn: string;
+    /**
+     * Whether the invoking surface can prompt for a connection input an MCP
+     * server's manifest requires.
+     */
+    readonly nonInteractive: boolean;
+}
+/** What every step in an adoption may require when it runs. */
+export type AdoptExtensionRequirements = ManagerRequirements | RecipeRequirements | WorkspaceMutations | CodingAgentRepository | McpSecretStore;
+/** A settled adoption: every decision is made and nothing is written. */
+export interface AdoptExtensionCandidate {
+    readonly type: ExtensionType;
+    readonly fqn: string;
+    readonly owner: Handle;
+    readonly name: string;
+    /** Workspace-relative directory the package is moved out of. */
+    readonly acquiredPath: string;
+    /** Workspace-relative directory the package is moved into. */
+    readonly authoredPath: string;
+    /** Workspace-relative settings file the declaration is rewritten in. */
+    readonly settingsPath: string;
+    /** The activation the adopted package keeps. */
+    readonly enabled: boolean;
+    readonly execution: ExecutionCandidate<AdoptExtensionRequirements>;
+}
+/** Every failure settling an adoption can surface before anything is written. */
+export type AdoptExtensionFailure = AuthoringFailed | AuthoredPackageError | AuthoringOwnerRequired | AuthoringOwnerMismatch | AuthoringScopeUnsupported | LockfileValidationError | WorkspaceLockfileReadFailure | WorkspaceSettingsReadFailure | CandidateFingerprintFailed | FqnInvalidError;
+/** Everything settling an adoption reads before it freezes a candidate. */
+export type PrepareAdoptExtensionRequirements = FileSystem.FileSystem | Path.Path | HttpClient.HttpClient | WorkspaceMutations | ExtensionManagers | ConfiguredAgentOutcomesProvider;
+/** The plan an adoption resolves. */
+export declare const adoptExtensionPlanName = "Adopt workspace extension";
+/** Settle an adoption without writing anything. */
+export declare const prepareAdoptExtension: (request: AdoptExtensionRequest) => Effect.Effect<AdoptExtensionCandidate, AdoptExtensionFailure, PrepareAdoptExtensionRequirements>;
+/** Preview or apply a settled adoption, resolving to one operation outcome. */
+export declare const previewOrApplyAdoptExtension: (candidate: AdoptExtensionCandidate, 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, ConfiguredAgentOutcomesProvider | import("@agentxm/workspace-operations").OperationJournal | import("@agentxm/workspace-operations").ResolvePlanInteraction | import("@agentxm/workspace-transactions").FootprintRecorder | AdoptExtensionRequirements>;
+/** The adoption use case: settle a request, then preview or apply it. */
+export declare const AdoptExtension: {
+    readonly prepare: (request: AdoptExtensionRequest) => Effect.Effect<AdoptExtensionCandidate, AdoptExtensionFailure, PrepareAdoptExtensionRequirements>;
+    readonly previewOrApply: (candidate: AdoptExtensionCandidate, 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, ConfiguredAgentOutcomesProvider | import("@agentxm/workspace-operations").OperationJournal | import("@agentxm/workspace-operations").ResolvePlanInteraction | import("@agentxm/workspace-transactions").FootprintRecorder | AdoptExtensionRequirements>;
+};
+//# sourceMappingURL=adopt-extension.d.ts.map

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

@@ -0,0 +1,174 @@
+/**
+ * Adopting an acquired package into workspace authorship.
+ *
+ * Adoption moves rather than copies: the canonical package the workspace
+ * acquired becomes the authored package, its accepted external resolution is
+ * retired, and its declaration is rewritten to name the workspace as its
+ * source. The activation it already carried is preserved, and a package that
+ * was never declared becomes enabled — adopting content you cannot see would
+ * leave the workspace holding authored work it never materializes.
+ *
+ * `prepare` settles the identity, the destination, and the activation, and
+ * writes nothing. `previewOrApply` resolves that same candidate inside the
+ * workspace transaction, so a failed move restores both directories.
+ *
+ * @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, materializeAuthoredMcpServer, } from "@agentxm/extension-materialization";
+import { extensionTypeToPlural, formatFqn, parseFqn, } from "@agentxm/extension-model/unstable/extensions";
+import { operationPresentation, prepareExecutionCandidate, resolveExecutionCandidate, } from "@agentxm/workspace-operations";
+import { WorkspaceMutations, resolveWorkspaceExtensionRef, } from "@agentxm/workspace-state";
+import { protectCreatedAncestors } from "@agentxm/workspace-transactions";
+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 { authoringStepFailure } from "../step-failure.js";
+/**
+ * Build the adoption step with the requirements this use case keeps in `R`.
+ */
+const adoptStep = (manager, args) => buildAuthoredExtensionStep(manager, args);
+/** The plan an adoption resolves. */
+export const adoptExtensionPlanName = "Adopt workspace extension";
+// -----------------------------------------------------------------------------
+// prepare
+// -----------------------------------------------------------------------------
+/** Settle an adoption without writing anything. */
+export const prepareAdoptExtension = Effect.fn("AdoptExtension.prepare")(function* (request) {
+    const ws = yield* WorkspaceMutations;
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const managers = yield* ExtensionManagers;
+    const parsed = yield* Effect.fromResult(parseFqn(request.fqn));
+    if (ws.layout.scope !== "project") {
+        return yield* new AuthoringScopeUnsupported({ subject: "adoption", scope: ws.layout.scope });
+    }
+    yield* requireAuthoredOwner(parsed.owner, { subject: "package", command: "adopt" });
+    const name = parsed.name;
+    const fqn = formatFqn(parsed);
+    const sourceDir = path.join(ws.layout.acquiredRoot, "agentxm", parsed.owner, extensionTypeToPlural[parsed.type], name);
+    const targetDir = path.join(ws.layout.authoredRoot(parsed.type), name);
+    const acquiredPath = path.relative(ws.baseDir, sourceDir);
+    const authoredPath = path.relative(ws.baseDir, targetDir);
+    const settingsPath = settingsRelativePath(path, ws);
+    // Refuse an occupied authoring destination here, so a preview refuses it
+    // too; the closure repeats the check under the transaction lock.
+    const createOnly = preflightCreateOnly({
+        subject: "Adopt target",
+        name,
+        configured: false,
+        destinations: [targetDir],
+    });
+    yield* createOnly;
+    const declaration = authoredDeclaration(ws, parsed.type, name);
+    const current = yield* declaration.read;
+    // A package the workspace never declared becomes enabled: adopting content
+    // that stays invisible is not what adoption was asked for.
+    const enabled = Option.getOrElse(current.enabled, () => true);
+    const artifact = {
+        path: authoredPath,
+        scope: ws.scope,
+        change: "created",
+        targets: [
+            { path: acquiredPath, change: "removed" },
+            { path: authoredPath, change: "created" },
+            { path: settingsPath, change: "updated" },
+        ],
+    };
+    const common = {
+        toStepFailure: authoringStepFailure,
+        location: targetDir,
+        transactionTargets: [sourceDir],
+        versionRange: Option.none(),
+        label: `Adopt ${fqn}`,
+        message: `Adopted ${fqn}`,
+        enabled,
+        allowConfiguredSourceTransition: true,
+        markAuthored: Effect.andThen(declaration.retireExternalResolution, declaration.declare({ enabled: true, env: current.env })),
+        finalizeAuthored: declaration.declare({ enabled, env: current.env }),
+        plannedArtifact: artifact,
+        buildArtifact: () => Effect.succeed(artifact),
+        preflight: Effect.gen(function* () {
+            yield* createOnly;
+            // The acquired directory must already hold a resolvable package: a move
+            // that lands unreadable content would leave the workspace authoring
+            // something it cannot materialize.
+            yield* resolveWorkspaceExtensionRef({
+                settingsName: name,
+                source: "workspace",
+                expectedType: parsed.type,
+                layout: ws.layout,
+                scope: ws.scope,
+                staticPackage: { owner: parsed.owner, name, root: sourceDir },
+            });
+        }).pipe(Effect.asVoid),
+        scaffold: Effect.gen(function* () {
+            yield* protectCreatedAncestors(fs, path, path.dirname(targetDir));
+            yield* fs.makeDirectory(path.dirname(targetDir), { recursive: true });
+            yield* fs.rename(sourceDir, targetDir);
+        }).pipe(Effect.mapError((cause) => new AuthoringFailed({
+            category: "internal",
+            detail: `Could not move ${fqn} into authored package storage`,
+            cause,
+        }))),
+    };
+    const step = (() => {
+        switch (parsed.type) {
+            case "skill":
+                return adoptStep(managers.skill, { ...common, target: { type: "skill", name } });
+            case "subagent":
+                return adoptStep(managers.subagent, { ...common, target: { type: "subagent", name } });
+            case "rule":
+                return adoptStep(managers.rule, { ...common, target: { type: "rule", name } });
+            case "hook":
+                return adoptStep(managers.hook, { ...common, target: { type: "hook", name } });
+            case "knowledge":
+                return adoptStep(managers.knowledge, { ...common, target: { type: "knowledge", name } });
+            case "pack":
+                return adoptStep(managers.pack, {
+                    ...common,
+                    target: { type: "pack", owner: parsed.owner, name },
+                });
+            case "mcp-server":
+                return adoptStep(managers["mcp-server"], {
+                    ...common,
+                    target: { type: "mcp-server", name },
+                    materializeInstall: (ref) => materializeAuthoredMcpServer({ ref, nonInteractive: request.nonInteractive }),
+                });
+        }
+    })();
+    const plan = {
+        _tag: "Plan",
+        name: adoptExtensionPlanName,
+        description: Option.some("Adopt the canonical package as authoritative workspace source content"),
+        presentation: operationPresentation({ imperative: "adopt", past: "Adopted", gerund: "Adopting" }, parsed.type),
+        jobs: [{ concurrency: 1, steps: [step] }],
+    };
+    return {
+        type: parsed.type,
+        fqn,
+        owner: parsed.owner,
+        name,
+        acquiredPath,
+        authoredPath,
+        settingsPath,
+        enabled,
+        execution: yield* prepareExecutionCandidate(plan),
+    };
+});
+// -----------------------------------------------------------------------------
+// previewOrApply
+// -----------------------------------------------------------------------------
+/** Preview or apply a settled adoption, resolving to one operation outcome. */
+export const previewOrApplyAdoptExtension = (candidate, execution) => resolveExecutionCandidate(candidate.execution, execution);
+/** The adoption use case: settle a request, then preview or apply it. */
+export const AdoptExtension = {
+    prepare: prepareAdoptExtension,
+    previewOrApply: previewOrApplyAdoptExtension,
+};
+//# sourceMappingURL=adopt-extension.js.map

package/dist/src/authored-declaration.d.ts

@@ -0,0 +1,49 @@
+/**
+ * How a workspace declares that it authors a package, for every extension
+ * type.
+ *
+ * Creating, forking, adopting, and importing all answer the same three
+ * questions — is this name already declared, what activation does it carry,
+ * and what accepted external resolution does becoming authored retire — and
+ * every one of them answers it per type. Deciding it once here is what keeps
+ * the four use cases from repeating a seven-way table each, and what makes a
+ * new extension type a compile error in one place instead of four.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import type { ExtensionType } from "@agentxm/extension-model/unstable/extensions";
+import { type WorkspaceLockfileMutationFailure, type WorkspaceMutationsService, type WorkspaceSettingsMutationFailure, type WorkspaceSettingsReadFailure, type WorkspaceStateMutationFailure } from "@agentxm/workspace-state";
+/** What the workspace currently declares about one name of one type. */
+export interface AuthoredDeclarationState {
+    /** Whether any entry of this type carries this name. */
+    readonly configured: boolean;
+    /** The activation the existing entry carries, or none when undeclared. */
+    readonly enabled: Option.Option<boolean>;
+    /** The source the entry names, or none when undeclared or sourceless. */
+    readonly source: Option.Option<string>;
+    /**
+     * Connection inputs an existing MCP declaration carries. Empty for every
+     * other type, which declares no inputs.
+     */
+    readonly env: Readonly<Record<string, string>>;
+}
+/** Reading and writing one workspace declaration. */
+export interface AuthoredDeclaration {
+    readonly read: Effect.Effect<AuthoredDeclarationState, WorkspaceSettingsReadFailure>;
+    /** Declare the name as workspace-authored with the given activation. */
+    readonly declare: (args: {
+        readonly enabled: boolean;
+        /** Inputs to preserve on an MCP declaration; ignored by other types. */
+        readonly env?: Readonly<Record<string, string>>;
+    }) => Effect.Effect<void, WorkspaceSettingsMutationFailure>;
+    /**
+     * Retire the accepted external resolution the name held before the
+     * workspace took authorship of it.
+     */
+    readonly retireExternalResolution: Effect.Effect<void, WorkspaceLockfileMutationFailure | WorkspaceStateMutationFailure>;
+}
+/** The declaration surface for one extension type and name. */
+export declare const authoredDeclaration: (ws: WorkspaceMutationsService, type: ExtensionType, name: string) => AuthoredDeclaration;
+//# sourceMappingURL=authored-declaration.d.ts.map

package/dist/src/authored-declaration.js

@@ -0,0 +1,86 @@
+/**
+ * How a workspace declares that it authors a package, for every extension
+ * type.
+ *
+ * Creating, forking, adopting, and importing all answer the same three
+ * questions — is this name already declared, what activation does it carry,
+ * and what accepted external resolution does becoming authored retire — and
+ * every one of them answers it per type. Deciding it once here is what keeps
+ * the four use cases from repeating a seven-way table each, and what makes a
+ * new extension type a compile error in one place instead of four.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import {} from "@agentxm/workspace-state";
+const WORKSPACE_SOURCE = "workspace";
+const entrySource = (entry) => {
+    if (typeof entry === "string")
+        return Option.some(entry);
+    if (typeof entry !== "object" || entry === null || !("source" in entry))
+        return Option.none();
+    return typeof entry.source === "string" ? Option.some(entry.source) : Option.none();
+};
+const state = (entry, env = {}) => ({
+    configured: entry !== undefined,
+    enabled: entry === undefined
+        ? Option.none()
+        : Option.some(typeof entry === "string" ? true : (entry.enabled ?? true)),
+    source: entrySource(entry),
+    env,
+});
+/** The declaration surface for one extension type and name. */
+export const authoredDeclaration = (ws, type, name) => {
+    switch (type) {
+        case "skill":
+            return {
+                read: ws.getConfiguredSkillEntries().pipe(Effect.map((entries) => state(entries[name]))),
+                declare: ({ enabled }) => ws.setSkillEntry(name, { source: WORKSPACE_SOURCE, enabled }),
+                retireExternalResolution: ws.removeSkillLock(name),
+            };
+        case "subagent":
+            return {
+                read: ws.getConfiguredSubagentEntries().pipe(Effect.map((entries) => state(entries[name]))),
+                declare: ({ enabled }) => ws.setSubagentEntry(name, { source: WORKSPACE_SOURCE, enabled }),
+                retireExternalResolution: ws.removeSubagentLock(name),
+            };
+        case "rule":
+            return {
+                read: ws.getConfiguredRuleEntries().pipe(Effect.map((entries) => state(entries[name]))),
+                declare: ({ enabled }) => ws.setRuleEntry(name, { source: WORKSPACE_SOURCE, enabled }),
+                retireExternalResolution: ws.removeRuleLock(name),
+            };
+        case "hook":
+            return {
+                read: ws.getConfiguredHookEntries().pipe(Effect.map((entries) => state(entries[name]))),
+                declare: ({ enabled }) => ws.setHookEntry(name, { source: WORKSPACE_SOURCE, enabled }),
+                retireExternalResolution: ws.removeHookLock(name),
+            };
+        case "knowledge":
+            return {
+                read: ws
+                    .getConfiguredKnowledgeEntries()
+                    .pipe(Effect.map((entries) => state(entries[name]))),
+                declare: ({ enabled }) => ws.setKnowledgeEntry(name, { source: WORKSPACE_SOURCE, enabled }),
+                retireExternalResolution: ws.removeKnowledgeLock(name),
+            };
+        case "pack":
+            return {
+                read: ws.getConfiguredPackEntries().pipe(Effect.map((entries) => state(entries[name]))),
+                declare: ({ enabled }) => ws.setPackEntry(name, { source: WORKSPACE_SOURCE, enabled }),
+                retireExternalResolution: ws.removePackLock(name),
+            };
+        case "mcp-server":
+            return {
+                read: ws
+                    .getConfiguredMcpServerEntries()
+                    .pipe(Effect.map((entries) => state(entries[name], entries[name]?.env ?? {}))),
+                declare: ({ enabled, env }) => ws.setMcpServerEntry(name, { source: WORKSPACE_SOURCE, enabled, env: env ?? {} }),
+                // Resolve the old connection before its workspace declaration replaces
+                // it, preserving any resolution still shared by another connection.
+                retireExternalResolution: ws.removeMcpServer(name),
+            };
+    }
+};
+//# sourceMappingURL=authored-declaration.js.map

package/dist/src/authored-package-errors.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Typed failure family for authored-package creation: create preflight, fork,
+ * and native import. Fields are domain facts; the application error boundary
+ * owns rendering, codes, and suggestions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type { CreateDestinationExists } from "@agentxm/extension-materialization";
+import type { ExtensionType } from "@agentxm/extension-model/unstable/extensions/common";
+declare const CreateNameConfigured_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CreateNameConfigured";
+} & Readonly<A>;
+/** A create operation's name is already declared in workspace settings. */
+export declare class CreateNameConfigured extends CreateNameConfigured_base<{
+    readonly subject: string;
+    readonly name: string;
+}> {
+}
+declare const CreateDestinationInspectionFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CreateDestinationInspectionFailed";
+} & Readonly<A>;
+/** Inspecting a create destination before scaffolding failed. */
+export declare class CreateDestinationInspectionFailed extends CreateDestinationInspectionFailed_base<{
+    readonly path: string;
+    readonly cause: unknown;
+}> {
+}
+declare const ForkPackageInvalid_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ForkPackageInvalid";
+} & Readonly<A>;
+/** Fork input content or identity did not validate. */
+export declare class ForkPackageInvalid extends ForkPackageInvalid_base<{
+    readonly detail: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const ForkPackageConflict_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ForkPackageConflict";
+} & Readonly<A>;
+/** Fork found conflicting workspace or source state. */
+export declare class ForkPackageConflict extends ForkPackageConflict_base<{
+    readonly detail: string;
+}> {
+}
+declare const ForkPackageFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ForkPackageFailed";
+} & Readonly<A>;
+/** A fork filesystem step failed. */
+export declare class ForkPackageFailed extends ForkPackageFailed_base<{
+    readonly detail: string;
+    readonly cause: unknown;
+}> {
+}
+declare const NativeImportUnsupported_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NativeImportUnsupported";
+} & Readonly<A>;
+/** Native package import does not support the requested extension type. */
+export declare class NativeImportUnsupported extends NativeImportUnsupported_base<{
+    readonly type: ExtensionType;
+}> {
+}
+declare const NativeImportInvalid_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NativeImportInvalid";
+} & Readonly<A>;
+/** Native import input content did not validate. */
+export declare class NativeImportInvalid extends NativeImportInvalid_base<{
+    readonly detail: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const NativeImportConflict_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NativeImportConflict";
+} & Readonly<A>;
+/** Native import found existing state at its target directory. */
+export declare class NativeImportConflict extends NativeImportConflict_base<{
+    readonly targetDir: string;
+}> {
+}
+declare const NativeImportFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NativeImportFailed";
+} & Readonly<A>;
+/** A native-import filesystem step failed. */
+export declare class NativeImportFailed extends NativeImportFailed_base<{
+    readonly detail: string;
+    readonly cause: unknown;
+}> {
+}
+/** Every failure the authored-package creation operations construct. */
+export type AuthoredPackageError = CreateDestinationExists | CreateNameConfigured | CreateDestinationInspectionFailed | ForkPackageInvalid | ForkPackageConflict | ForkPackageFailed | NativeImportUnsupported | NativeImportInvalid | NativeImportConflict | NativeImportFailed;
+export {};
+//# sourceMappingURL=authored-package-errors.d.ts.map

package/dist/src/authored-package-errors.js

@@ -0,0 +1,36 @@
+/**
+ * Typed failure family for authored-package creation: create preflight, fork,
+ * and native import. Fields are domain facts; the application error boundary
+ * owns rendering, codes, and suggestions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Data from "effect/Data";
+/** A create operation's name is already declared in workspace settings. */
+export class CreateNameConfigured extends Data.TaggedError("CreateNameConfigured") {
+}
+/** Inspecting a create destination before scaffolding failed. */
+export class CreateDestinationInspectionFailed extends Data.TaggedError("CreateDestinationInspectionFailed") {
+}
+/** Fork input content or identity did not validate. */
+export class ForkPackageInvalid extends Data.TaggedError("ForkPackageInvalid") {
+}
+/** Fork found conflicting workspace or source state. */
+export class ForkPackageConflict extends Data.TaggedError("ForkPackageConflict") {
+}
+/** A fork filesystem step failed. */
+export class ForkPackageFailed extends Data.TaggedError("ForkPackageFailed") {
+}
+/** Native package import does not support the requested extension type. */
+export class NativeImportUnsupported extends Data.TaggedError("NativeImportUnsupported") {
+}
+/** Native import input content did not validate. */
+export class NativeImportInvalid extends Data.TaggedError("NativeImportInvalid") {
+}
+/** Native import found existing state at its target directory. */
+export class NativeImportConflict extends Data.TaggedError("NativeImportConflict") {
+}
+/** A native-import filesystem step failed. */
+export class NativeImportFailed extends Data.TaggedError("NativeImportFailed") {
+}
+//# sourceMappingURL=authored-package-errors.js.map

package/dist/src/create/authoring-owner.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The owner every authored package is created under.
+ *
+ * The selected workspace scope is the only silent source. An explicitly
+ * requested owner must match a configured one, and establishes ownership when
+ * the scope configures none. When neither is present the refusal names the
+ * owners the person could have meant rather than resolving one for them:
+ * creating under an owner the scope does not record leaves the workspace
+ * failing its own desired-state invariant.
+ *
+ * @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 type { Handle } from "@agentxm/extension-model/unstable/extensions";
+import { CredentialStore } from "@agentxm/registry-auth";
+import { RegistryUrl } from "@agentxm/registry-client";
+import { WorkspaceMutations, type WorkspaceMutationsService, type WorkspaceSettingsMutationFailure, type WorkspaceSettingsReadFailure } from "@agentxm/workspace-state";
+import { AuthoringOwnerMismatch, AuthoringOwnerRequired } from "./errors.js";
+/** The `axm <type> new <name>` invocation named in an ownership refusal. */
+export interface AuthoringTarget {
+    /** Subject named in the refusal, e.g. `skill`. */
+    readonly subject: string;
+    /** Command route named in the recovery action, e.g. `skills new`. */
+    readonly command: string;
+    /** Name being created, so the recovery action is a runnable command. */
+    readonly name: string;
+}
+export interface AuthoringOwner {
+    /** The owner the new package and its workspace declaration carry. */
+    readonly owner: Handle;
+    /**
+     * Record `owner` in the selected scope's settings, or `Effect.void` when
+     * the scope already names it. It runs inside the authoring transaction, so
+     * establishment is atomic with the desired-state entry and absent from
+     * preview.
+     */
+    readonly establish: Effect.Effect<void, WorkspaceSettingsMutationFailure>;
+}
+/** The settings file that records ownership, relative to the workspace root. */
+export declare const settingsRelativePath: (path: Path.Path, ws: WorkspaceMutationsService) => string;
+/**
+ * Resolve the owner an authoring command creates under, or refuse with the
+ * facts that make the refusal recoverable.
+ */
+export declare const resolveAuthoringOwner: (target: AuthoringTarget, explicit: Option.Option<string>) => Effect.Effect<AuthoringOwner, AuthoringOwnerRequired | AuthoringOwnerMismatch | WorkspaceSettingsReadFailure, WorkspaceMutations | Path.Path | CredentialStore | RegistryUrl>;
+/**
+ * Require an already-authored package's identity to agree with the selected
+ * workspace. Fork, adopt, and native import carry an owner in the identity
+ * they were given, so they confirm rather than resolve.
+ */
+export declare const requireAuthoredOwner: (owner: Handle, target: Pick<AuthoringTarget, "subject" | "command">) => Effect.Effect<void, AuthoringOwnerRequired | AuthoringOwnerMismatch, WorkspaceMutations | Path.Path>;
+//# sourceMappingURL=authoring-owner.d.ts.map

package/dist/src/create/authoring-owner.js

@@ -0,0 +1,93 @@
+/**
+ * The owner every authored package is created under.
+ *
+ * The selected workspace scope is the only silent source. An explicitly
+ * requested owner must match a configured one, and establishes ownership when
+ * the scope configures none. When neither is present the refusal names the
+ * owners the person could have meant rather than resolving one for them:
+ * creating under an owner the scope does not record leaves the workspace
+ * failing its own desired-state invariant.
+ *
+ * @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 { CredentialStore, getCurrentUserHandle } from "@agentxm/registry-auth";
+import { RegistryUrl } from "@agentxm/registry-client";
+import { WorkspaceMutations, } from "@agentxm/workspace-state";
+import { AuthoringOwnerMismatch, AuthoringOwnerRequired } from "./errors.js";
+import { normalizeScaffoldOwner } from "./scaffold-name.js";
+/** The settings file that records ownership, relative to the workspace root. */
+export const settingsRelativePath = (path, ws) => path.relative(ws.baseDir, ws.layout.settingsPath);
+/**
+ * Owners the person could plausibly have meant, most local first.
+ *
+ * These are named in the refusal only. Neither the user-scope owner nor the
+ * signed-in handle silently supplies authorship for the selected scope.
+ */
+const ownerCandidates = (ws) => Effect.gen(function* () {
+    const configured = yield* ws.getConfiguredOwner();
+    const registryUrl = yield* RegistryUrl;
+    // A keychain that cannot be read must not mask the ownership refusal that
+    // this lookup only decorates.
+    const loggedIn = yield* getCurrentUserHandle(registryUrl).pipe(Effect.catch(() => Effect.succeed(Option.none())));
+    const candidates = new Set();
+    if (Option.isSome(configured))
+        candidates.add(configured.value);
+    if (Option.isSome(loggedIn))
+        candidates.add(loggedIn.value);
+    return Array.from(candidates);
+});
+/**
+ * Resolve the owner an authoring command creates under, or refuse with the
+ * facts that make the refusal recoverable.
+ */
+export const resolveAuthoringOwner = (target, explicit) => Effect.gen(function* () {
+    const ws = yield* WorkspaceMutations;
+    const path = yield* Path.Path;
+    const configured = ws.layout.owner;
+    if (Option.isNone(explicit)) {
+        if (configured === undefined) {
+            return yield* new AuthoringOwnerRequired({
+                subject: target.subject,
+                command: target.command,
+                name: target.name,
+                candidates: yield* ownerCandidates(ws),
+                settingsPath: settingsRelativePath(path, ws),
+            });
+        }
+        return { owner: configured, establish: Effect.void };
+    }
+    const requested = normalizeScaffoldOwner(explicit.value);
+    if (configured === undefined) {
+        return { owner: requested, establish: ws.setOwner(requested) };
+    }
+    if (configured !== requested) {
+        return yield* new AuthoringOwnerMismatch({ requested, configured });
+    }
+    return { owner: requested, establish: Effect.void };
+});
+/**
+ * Require an already-authored package's identity to agree with the selected
+ * workspace. Fork, adopt, and native import carry an owner in the identity
+ * they were given, so they confirm rather than resolve.
+ */
+export const requireAuthoredOwner = (owner, target) => Effect.gen(function* () {
+    const ws = yield* WorkspaceMutations;
+    const path = yield* Path.Path;
+    const configured = ws.layout.owner;
+    if (configured === undefined) {
+        return yield* new AuthoringOwnerRequired({
+            subject: target.subject,
+            command: target.command,
+            name: owner,
+            candidates: [owner],
+            settingsPath: settingsRelativePath(path, ws),
+        });
+    }
+    if (configured !== owner) {
+        return yield* new AuthoringOwnerMismatch({ requested: owner, configured });
+    }
+});
+//# sourceMappingURL=authoring-owner.js.map