@agentxm/extension-authoring 0.28.4-bootstrap.0

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2025-2026 AgentXM, Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,12 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import { CreateDestinationExists, CreateDestinationInspectionFailed, CreateNameConfigured } from "@agentxm/extension-workspace";
+export interface CreateOnlyPreflightArgs {
+    readonly subject: string;
+    readonly name: string;
+    readonly configured: boolean;
+    readonly destinations: ReadonlyArray<string>;
+}
+/** Refuse every declared identity/path collision before a create operation mutates the workspace. */
+export declare const preflightCreateOnly: (args: CreateOnlyPreflightArgs) => Effect.Effect<undefined, CreateNameConfigured | CreateDestinationExists | CreateDestinationInspectionFailed, FileSystem.FileSystem>;
+//# sourceMappingURL=create-preflight.d.ts.map

package/dist/src/create-preflight.js

@@ -0,0 +1,19 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import { CreateDestinationExists, CreateDestinationInspectionFailed, CreateNameConfigured, } from "@agentxm/extension-workspace";
+/** Refuse every declared identity/path collision before a create operation mutates the workspace. */
+export const preflightCreateOnly = Effect.fn("Extensions.preflightCreateOnly")(function* (args) {
+    if (args.configured) {
+        return yield* new CreateNameConfigured({ subject: args.subject, name: args.name });
+    }
+    const fs = yield* FileSystem.FileSystem;
+    for (const destination of args.destinations) {
+        const exists = yield* fs
+            .exists(destination)
+            .pipe(Effect.mapError((cause) => new CreateDestinationInspectionFailed({ path: destination, cause })));
+        if (exists) {
+            return yield* new CreateDestinationExists({ subject: args.subject, path: destination });
+        }
+    }
+});
+//# sourceMappingURL=create-preflight.js.map

package/dist/src/desired-identity.d.ts

@@ -0,0 +1,19 @@
+import { type ExtensionName, type ExtensionType } from "@agentxm/extension-model/unstable/extensions/common";
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+export type DesiredPackageAuthority = "registry" | "workspace";
+export interface DecodedDesiredExtensionIdentity {
+    readonly authority: DesiredPackageAuthority;
+    readonly owner: Handle;
+    readonly type: ExtensionType;
+    readonly name: ExtensionName;
+    readonly fqn: string;
+}
+/**
+ * Decode the source-qualified identity stored in the desired-state graph.
+ *
+ * This is deliberately narrower than source-locator parsing: desired graph
+ * identities are either validated Registry FQNs or `workspace:` followed by a
+ * validated FQN. Unknown authorities fail closed.
+ */
+export declare const decodeDesiredExtensionIdentity: (identity: string) => DecodedDesiredExtensionIdentity | undefined;
+//# sourceMappingURL=desired-identity.d.ts.map

package/dist/src/desired-identity.js

@@ -0,0 +1,26 @@
+import { parseExtensionFqnParts, } from "@agentxm/extension-model/unstable/extensions/common";
+const workspacePrefix = "workspace:";
+/**
+ * Decode the source-qualified identity stored in the desired-state graph.
+ *
+ * This is deliberately narrower than source-locator parsing: desired graph
+ * identities are either validated Registry FQNs or `workspace:` followed by a
+ * validated FQN. Unknown authorities fail closed.
+ */
+export const decodeDesiredExtensionIdentity = (identity) => {
+    const authority = identity.startsWith(workspacePrefix)
+        ? "workspace"
+        : "registry";
+    const fqn = authority === "workspace" ? identity.slice(workspacePrefix.length) : identity;
+    const parsed = parseExtensionFqnParts(fqn);
+    if (parsed === undefined)
+        return undefined;
+    return {
+        authority,
+        owner: parsed.owner,
+        type: parsed.type,
+        name: parsed.name,
+        fqn,
+    };
+};
+//# sourceMappingURL=desired-identity.js.map

package/dist/src/errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Typed failures for the extension-authoring feature. The producer owns the
+ * category choice and user-facing wording; the application boundary converts
+ * the carried fields into its error envelope verbatim.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+declare const AuthoringFailed_base: Schema.Class<AuthoringFailed, Schema.TaggedStruct<"AuthoringFailed", {
+    readonly category: Schema.Literals<readonly ["conflict", "internal", "not_found", "validation"]>;
+    readonly detail: Schema.String;
+    readonly recover: Schema.optional<Schema.String>;
+    readonly suggestions: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly description: Schema.String;
+        readonly cmd: Schema.optional<Schema.String>;
+        readonly url: Schema.optional<Schema.String>;
+    }>>>;
+    readonly cause: Schema.optional<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * An authoring policy step could not proceed. The carried fields mirror the
+ * application error envelope's inputs 1:1: `category` selects the code,
+ * `recover` folds into the leading suggested action, and `detail`,
+ * `suggestions`, and `cause` carry over verbatim.
+ */
+export declare class AuthoringFailed extends AuthoringFailed_base {
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/errors.js

@@ -0,0 +1,28 @@
+/**
+ * Typed failures for the extension-authoring feature. The producer owns the
+ * category choice and user-facing wording; the application boundary converts
+ * the carried fields into its error envelope verbatim.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+const CarriedSuggestedActionSchema = Schema.Struct({
+    description: Schema.String,
+    cmd: Schema.optional(Schema.String),
+    url: Schema.optional(Schema.String),
+});
+/**
+ * An authoring policy step could not proceed. The carried fields mirror the
+ * application error envelope's inputs 1:1: `category` selects the code,
+ * `recover` folds into the leading suggested action, and `detail`,
+ * `suggestions`, and `cause` carry over verbatim.
+ */
+export class AuthoringFailed extends Schema.TaggedError()("AuthoringFailed", {
+    category: Schema.Literals(["conflict", "internal", "not_found", "validation"]),
+    detail: Schema.String,
+    recover: Schema.optional(Schema.String),
+    suggestions: Schema.optional(Schema.Array(CarriedSuggestedActionSchema)),
+    cause: Schema.optional(Schema.Unknown),
+}) {
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/failure-adapter.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The application-supplied conversion from authoring failures to the plan
+ * step vocabulary. Error rendering is application-owned: the CLI implements
+ * this with the same dispatcher it uses at its output boundary, so step
+ * categories and details inside authoring operations stay byte-identical
+ * with rendered errors. The feature keeps only the requirement, never the
+ * mapping.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Effect from "effect/Effect";
+import type { StepFailure } from "@agentxm/workspace-operations";
+export interface AuthoringFailureAdapterService {
+    /**
+     * Serialize any failure an authoring operation can surface — kernel
+     * failures and the feature's own typed failures — into the plan-step
+     * vocabulary.
+     */
+    readonly toStepFailure: (failure: unknown) => StepFailure;
+}
+declare const AuthoringFailureAdapter_base: ServiceMap.ServiceClass<AuthoringFailureAdapter, "@agentxm/extension-authoring/failure-adapter/AuthoringFailureAdapter", AuthoringFailureAdapterService>;
+export declare class AuthoringFailureAdapter extends AuthoringFailureAdapter_base {
+}
+/**
+ * Serialize every failure of one authoring operation into the plan-step
+ * vocabulary through the application-supplied adapter.
+ */
+export declare const withAdaptedStepFailures: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, StepFailure, R | AuthoringFailureAdapter>;
+export {};
+//# sourceMappingURL=failure-adapter.d.ts.map

package/dist/src/failure-adapter.js

@@ -0,0 +1,23 @@
+/**
+ * The application-supplied conversion from authoring failures to the plan
+ * step vocabulary. Error rendering is application-owned: the CLI implements
+ * this with the same dispatcher it uses at its output boundary, so step
+ * categories and details inside authoring operations stay byte-identical
+ * with rendered errors. The feature keeps only the requirement, never the
+ * mapping.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Effect from "effect/Effect";
+export class AuthoringFailureAdapter extends ServiceMap.Service()("@agentxm/extension-authoring/failure-adapter/AuthoringFailureAdapter") {
+}
+/**
+ * Serialize every failure of one authoring operation into the plan-step
+ * vocabulary through the application-supplied adapter.
+ */
+export const withAdaptedStepFailures = (effect) => Effect.gen(function* () {
+    const adapter = yield* AuthoringFailureAdapter;
+    return yield* effect.pipe(Effect.mapError((failure) => adapter.toStepFailure(failure)));
+});
+//# sourceMappingURL=failure-adapter.js.map

package/dist/src/fork-package.d.ts

@@ -0,0 +1,20 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { ForkPackageConflict, ForkPackageFailed, ForkPackageInvalid } from "@agentxm/extension-workspace";
+import { type FrontmatterParseFailure } from "@agentxm/registry-protocol/unstable/content/frontmatter";
+import type { ExtensionFqnParts, ExtensionName, ExtensionType } from "@agentxm/extension-model/unstable/extensions/common";
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+export interface ForkExtensionPackageArgs {
+    readonly sourceDir: string;
+    readonly targetDir: string;
+    readonly sourceIdentity: {
+        readonly owner: Handle;
+        readonly type: ExtensionType;
+        readonly name: ExtensionName;
+        readonly version: string;
+    };
+    readonly target: ExtensionFqnParts;
+}
+export declare const forkExtensionPackage: (args: ForkExtensionPackageArgs) => Effect.Effect<void, ForkPackageInvalid | ForkPackageConflict | ForkPackageFailed | FrontmatterParseFailure, FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=fork-package.d.ts.map

package/dist/src/fork-package.js

@@ -0,0 +1,155 @@
+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 * as Schema from "effect/Schema";
+import YAML from "yaml";
+import { ForkPackageConflict, ForkPackageFailed, ForkPackageInvalid, } from "@agentxm/extension-workspace";
+import { ManifestIdentitySchema, manifestFilenameForType, manifestSchemaForType, } from "@agentxm/registry-protocol/unstable/publish/manifest-policy";
+import { copyExtensionDirectory } from "@agentxm/extension-workspace";
+import { parseFrontmatterEffect, } from "@agentxm/registry-protocol/unstable/content/frontmatter";
+const INITIAL_FORK_VERSION = "0.1.0";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const readJson = (filePath) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const text = yield* fs
+        .readFileString(filePath)
+        .pipe(Effect.mapError((cause) => new ForkPackageInvalid({ detail: `Manifest could not be read: ${filePath}`, cause })));
+    return yield* Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown))(text).pipe(Effect.mapError((cause) => new ForkPackageInvalid({ detail: `Manifest contains invalid JSON: ${filePath}`, cause })));
+});
+const validateSourceIdentity = (actual, expected) => actual.owner === expected.owner &&
+    actual.type === expected.type &&
+    actual.name === expected.name &&
+    actual.version === expected.version
+    ? Effect.void
+    : new ForkPackageConflict({
+        detail: `Fork source changed after it was resolved; expected ${expected.owner}/${expected.type}/${expected.name}@${expected.version}`,
+    });
+const validateContainedSymlinks = (sourceRoot) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const realRoot = yield* fs.realPath(sourceRoot).pipe(Effect.mapError((cause) => new ForkPackageInvalid({
+        detail: `Fork source could not be resolved: ${sourceRoot}`,
+        cause,
+    })));
+    const entries = yield* fs.readDirectory(sourceRoot, { recursive: true }).pipe(Effect.mapError((cause) => new ForkPackageInvalid({
+        detail: `Fork source could not be inspected: ${sourceRoot}`,
+        cause,
+    })));
+    yield* Effect.forEach(entries, (relativePath) => Effect.gen(function* () {
+        const entry = path.join(sourceRoot, relativePath);
+        const link = yield* fs.readLink(entry).pipe(Effect.option);
+        if (Option.isNone(link))
+            return;
+        const realTarget = yield* fs.realPath(entry).pipe(Effect.mapError((cause) => new ForkPackageInvalid({
+            detail: `Fork source contains an unresolved symlink: ${entry}`,
+            cause,
+        })));
+        const contained = realTarget === realRoot || realTarget.startsWith(`${realRoot}${path.sep}`);
+        if (!contained) {
+            return yield* new ForkPackageInvalid({
+                detail: `Fork source symlink escapes the package root: ${entry}`,
+            });
+        }
+    }), { concurrency: 16, discard: true });
+});
+const rewriteFrontmatterName = (filePath, targetName) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const content = yield* fs.readFileString(filePath).pipe(Effect.mapError((cause) => new ForkPackageInvalid({
+        detail: `Extension content could not be read: ${filePath}`,
+        cause,
+    })));
+    const parsed = yield* parseFrontmatterEffect(content);
+    if (!isRecord(parsed.frontmatter)) {
+        return yield* new ForkPackageInvalid({
+            detail: `Extension content must have YAML frontmatter: ${filePath}`,
+        });
+    }
+    const frontmatter = { ...parsed.frontmatter, name: targetName };
+    const yaml = YAML.stringify(frontmatter, { lineWidth: 0 }).trim();
+    const body = parsed.body.startsWith("\n") ? parsed.body : `\n${parsed.body}`;
+    yield* fs.writeFileString(filePath, `---\n${yaml}\n---${body}`).pipe(Effect.mapError((cause) => new ForkPackageFailed({
+        detail: `Extension frontmatter could not be rewritten: ${filePath}`,
+        cause,
+    })));
+});
+const rewriteTypeSpecificIdentity = (targetDir, source, target) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    switch (target.type) {
+        case "skill":
+            yield* rewriteFrontmatterName(path.join(targetDir, "src", "SKILL.md"), target.name).pipe(Effect.provideService(FileSystem.FileSystem, fs));
+            return;
+        case "subagent": {
+            const sourcePath = path.join(targetDir, "src", `${source.name}.md`);
+            const targetPath = path.join(targetDir, "src", `${target.name}.md`);
+            yield* rewriteFrontmatterName(sourcePath, target.name).pipe(Effect.provideService(FileSystem.FileSystem, fs));
+            if (sourcePath !== targetPath) {
+                yield* fs.rename(sourcePath, targetPath).pipe(Effect.mapError((cause) => new ForkPackageFailed({
+                    detail: `Subagent content could not be renamed to ${target.name}.md`,
+                    cause,
+                })));
+            }
+            return;
+        }
+        case "mcp-server":
+        case "rule":
+        case "hook":
+        case "knowledge":
+        case "pack":
+            return;
+    }
+});
+export const forkExtensionPackage = (args) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    if (args.sourceIdentity.type !== args.target.type) {
+        return yield* new ForkPackageInvalid({
+            detail: `Cannot fork ${args.sourceIdentity.type} as ${args.target.type}; source and target types must match`,
+        });
+    }
+    const targetExists = yield* fs.exists(args.targetDir).pipe(Effect.mapError((cause) => new ForkPackageFailed({
+        detail: `Fork target could not be inspected: ${args.targetDir}`,
+        cause,
+    })));
+    if (targetExists) {
+        return yield* new ForkPackageConflict({
+            detail: `Fork target already exists: ${args.targetDir}`,
+        });
+    }
+    const sourceManifestPath = path.join(args.sourceDir, manifestFilenameForType(args.sourceIdentity.type));
+    const raw = yield* readJson(sourceManifestPath).pipe(Effect.provideService(FileSystem.FileSystem, fs));
+    const identity = yield* Schema.decodeUnknownEffect(ManifestIdentitySchema)(raw).pipe(Effect.mapError((cause) => new ForkPackageInvalid({
+        detail: `Fork source manifest identity is invalid: ${sourceManifestPath}`,
+        cause,
+    })));
+    yield* validateSourceIdentity(identity, args.sourceIdentity);
+    if (!isRecord(raw)) {
+        return yield* new ForkPackageInvalid({
+            detail: `Fork source manifest must contain a JSON object: ${sourceManifestPath}`,
+        });
+    }
+    yield* validateContainedSymlinks(args.sourceDir).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path));
+    yield* copyExtensionDirectory(args.sourceDir, args.targetDir).pipe(Effect.mapError((cause) => new ForkPackageFailed({
+        detail: `Failed to copy AXM package from ${args.sourceDir} to ${args.targetDir}`,
+        cause,
+    })), Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path));
+    const targetManifestPath = path.join(args.targetDir, manifestFilenameForType(args.target.type));
+    const rewritten = {
+        ...raw,
+        owner: args.target.owner,
+        type: args.target.type,
+        name: args.target.name,
+        version: INITIAL_FORK_VERSION,
+    };
+    yield* fs.writeFileString(targetManifestPath, `${JSON.stringify(rewritten, null, 2)}\n`).pipe(Effect.mapError((cause) => new ForkPackageFailed({
+        detail: `Fork target manifest could not be written: ${targetManifestPath}`,
+        cause,
+    })));
+    yield* rewriteTypeSpecificIdentity(args.targetDir, args.sourceIdentity, args.target).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path));
+    yield* Schema.decodeUnknownEffect(manifestSchemaForType(args.target.type))(rewritten).pipe(Effect.mapError((cause) => new ForkPackageInvalid({
+        detail: `Fork target manifest is invalid: ${targetManifestPath}`,
+        cause,
+    })));
+});
+//# sourceMappingURL=fork-package.js.map

package/dist/src/hooks/new-hook.d.ts

@@ -0,0 +1,46 @@
+/**
+ * New hook operation — scaffolds a new hook directory with the manifest and a
+ * starter entrypoint.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+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/handle";
+import type { OperationHandler } from "@agentxm/workspace-operations";
+import type { Operation } from "@agentxm/workspace-operations";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { type HookEvent, type HookRuntime } from "@agentxm/extension-model/unstable/hooks/manifest-schema";
+/**
+ * Args for the new-hook operation.
+ */
+export interface NewHookOperationArgs {
+    /** Hook name (validated, lowercase with hyphens). */
+    readonly name: string;
+    /** Owner (e.g., "@myorg"). */
+    readonly owner: Handle;
+    /** Interpreter family for the entrypoint. */
+    readonly runtime: HookRuntime;
+    /** Canonical hook event the scaffold binds to. */
+    readonly event: HookEvent;
+    /** Optional raw matcher (only meaningful for tool.pre/tool.post). */
+    readonly matcher: string | undefined;
+}
+/**
+ * Scaffold a new hook in the workspace.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type NewHookOperation = Operation<"new-hook", NewHookOperationArgs>;
+/**
+ * New-hook operation handler.
+ *
+ * 1. Compute managed extension directory path
+ * 2. Check if the hook already exists (directory or settings entry)
+ * 3. Create the managed extension + src directories
+ * 4. Write hook.json manifest
+ * 5. Write starter entrypoint in src/
+ */
+export declare const newHook: OperationHandler<NewHookOperation, FileSystem.FileSystem | Path.Path | WorkspaceMutations | AuthoringFailureAdapter>;
+//# sourceMappingURL=new-hook.d.ts.map