@agentxm/extension-authoring 0.28.4-bootstrap.0

package/dist/src/packs/new-pack.d.ts

@@ -0,0 +1,37 @@
+/**
+ * New pack operation — scaffolds a new pack directory with manifest.
+ *
+ * @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";
+/**
+ * Args for the new pack operation.
+ */
+export interface NewPackOperationArgs {
+    /** Pack name (without owner). */
+    readonly name: string;
+    /** Profile (e.g., "@myorg"). */
+    readonly owner: Handle;
+}
+/**
+ * Scaffold a new pack in the workspace.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type NewPackOperation = Operation<"new-pack", NewPackOperationArgs>;
+/**
+ * New pack operation handler.
+ *
+ * 1. Compute pack directory path
+ * 2. Check if pack manifest already exists
+ * 3. Create pack directory
+ * 4. Write pack.json manifest
+ */
+export declare const newPack: OperationHandler<NewPackOperation, FileSystem.FileSystem | Path.Path | WorkspaceMutations | AuthoringFailureAdapter>;
+//# sourceMappingURL=new-pack.d.ts.map

package/dist/src/packs/new-pack.js

@@ -0,0 +1,90 @@
+/**
+ * New pack operation — scaffolds a new pack directory with manifest.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import { AuthoringFailed } from "../errors.js";
+import { AuthoringFailureAdapter, withAdaptedStepFailures } from "../failure-adapter.js";
+import { createCanonicalDirectory, recoverCanonicalDirectory } from "@agentxm/extension-workspace";
+import { preflightCreateOnly } from "../create-preflight.js";
+import { decodeExtensionNameSync, formatFqn } from "@agentxm/extension-model/unstable/extensions";
+import { PACK_MANIFEST_FILENAME, PACK_MANIFEST_SCHEMA_URL, } from "@agentxm/extension-model/unstable/packs/manifest-schema";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { decodeVersionSync } from "@agentxm/extension-model/unstable/version-constraints";
+// -----------------------------------------------------------------------------
+// Public API
+// -----------------------------------------------------------------------------
+/**
+ * New pack operation handler.
+ *
+ * 1. Compute pack directory path
+ * 2. Check if pack manifest already exists
+ * 3. Create pack directory
+ * 4. Write pack.json manifest
+ */
+export const newPack = (op) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const ws = yield* WorkspaceMutations;
+    const base = ws.baseDir;
+    if (ws.layout.scope !== "project") {
+        return yield* new AuthoringFailed({
+            category: "validation",
+            detail: "New packs can only be scaffolded in a project workspace",
+        });
+    }
+    const initialVersion = decodeVersionSync("0.0.1");
+    const { name, owner } = op.args;
+    const extensionName = decodeExtensionNameSync(name);
+    const fqn = formatFqn({ owner, type: "pack", name: extensionName });
+    // 1. Compute pack directory path
+    const canonicalPath = path.join(ws.layout.authoredRoot("pack"), name);
+    const configuredPacks = yield* ws.getConfiguredPackEntries();
+    yield* recoverCanonicalDirectory({
+        baseDir: base,
+        canonicalPath,
+    });
+    yield* preflightCreateOnly({
+        subject: "Pack",
+        name,
+        configured: Object.hasOwn(configuredPacks, name),
+        destinations: [canonicalPath],
+    });
+    const manifest = {
+        $schema: PACK_MANIFEST_SCHEMA_URL,
+        owner,
+        type: "pack",
+        name: extensionName,
+        version: initialVersion,
+        dependencies: {},
+    };
+    yield* createCanonicalDirectory({
+        baseDir: base,
+        canonicalPath,
+        subject: "Pack",
+        requiredFiles: [PACK_MANIFEST_FILENAME],
+        populate: (stagingPath) => {
+            const manifestPath = path.join(stagingPath, PACK_MANIFEST_FILENAME);
+            return Effect.gen(function* () {
+                yield* fs.makeDirectory(stagingPath, { recursive: true }).pipe(Effect.mapError((e) => new AuthoringFailed({
+                    category: "internal",
+                    detail: `Failed to create pack directory: ${stagingPath}`,
+                    cause: e,
+                })));
+                yield* fs.writeFileString(manifestPath, JSON.stringify(manifest, null, 2) + "\n").pipe(Effect.mapError((e) => new AuthoringFailed({
+                    category: "internal",
+                    detail: `Failed to write pack manifest: ${manifestPath}`,
+                    cause: e,
+                })));
+            });
+        },
+    });
+    return {
+        result: "success",
+        message: `Created pack ${fqn}`,
+    };
+}).pipe(withAdaptedStepFailures);
+//# sourceMappingURL=new-pack.js.map

package/dist/src/packs/remove-from-pack.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Remove-from-pack operation — applies a precomputed manifest-remove delta to a pack manifest.
+ *
+ * Validates manifest precondition (stale check) before writing.
+ *
+ * @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";
+import type { OperationHandler } from "@agentxm/workspace-operations";
+import type { Operation } from "@agentxm/workspace-operations";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+/**
+ * Args for the remove-from-pack operation.
+ */
+export interface RemoveFromPackOperationArgs {
+    /** Pack name (without owner). */
+    readonly packName: string;
+    /** Pack owner (e.g., "@myorg"). */
+    readonly packOwner: Handle;
+    /** Precomputed manifest delta: extension names to remove. */
+    readonly removals: ReadonlyArray<string>;
+    /** Manifest content hash at plan time for stale-check. */
+    readonly manifestHash: string;
+}
+/**
+ * Remove extensions from a pack manifest.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type RemoveFromPackOperation = Operation<"remove-from-pack", RemoveFromPackOperationArgs>;
+/**
+ * Remove-from-pack operation handler.
+ *
+ * 1. Short-circuit if removals list is empty (no-op)
+ * 2. Read current manifest and compute hash
+ * 3. Compare hash with args.manifestHash (stale check)
+ * 4. Apply removals to manifest
+ * 5. Write updated manifest
+ */
+export declare const removeFromPack: OperationHandler<RemoveFromPackOperation, FileSystem.FileSystem | Path.Path | WorkspaceMutations | AuthoringFailureAdapter>;
+//# sourceMappingURL=remove-from-pack.d.ts.map

package/dist/src/packs/remove-from-pack.js

@@ -0,0 +1,145 @@
+/**
+ * Remove-from-pack operation — applies a precomputed manifest-remove delta to a pack manifest.
+ *
+ * Validates manifest precondition (stale check) before writing.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { AuthoringFailed } from "../errors.js";
+import { AuthoringFailureAdapter, withAdaptedStepFailures } from "../failure-adapter.js";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { isWorkspaceSourceLocator } from "@agentxm/extension-model/unstable/sources/workspace";
+import { PACK_MANIFEST_FILENAME, PackManifestSchema, } from "@agentxm/extension-model/unstable/packs/manifest-schema";
+import { packManifestArtifact } from "./artifact.js";
+import { hashContent } from "./hash-content.js";
+// -----------------------------------------------------------------------------
+// Public API
+// -----------------------------------------------------------------------------
+/**
+ * Remove-from-pack operation handler.
+ *
+ * 1. Short-circuit if removals list is empty (no-op)
+ * 2. Read current manifest and compute hash
+ * 3. Compare hash with args.manifestHash (stale check)
+ * 4. Apply removals to manifest
+ * 5. Write updated manifest
+ */
+export const removeFromPack = (op) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const ws = yield* WorkspaceMutations;
+    if (ws.layout.scope !== "project") {
+        return yield* new AuthoringFailed({
+            category: "validation",
+            detail: "Authored packs can only be edited in a project workspace",
+        });
+    }
+    const { packName, packOwner, removals, manifestHash } = op.args;
+    const configured = (yield* ws.getConfiguredPackEntries())[packName];
+    if (configured === undefined || !isWorkspaceSourceLocator(configured.source)) {
+        return yield* new AuthoringFailed({
+            category: "conflict",
+            detail: `Pack "${packName}" is not an authored workspace pack`,
+            recover: "Only workspace-authored packs can be edited in place.",
+        });
+    }
+    // 1. Short-circuit if nothing to remove
+    if (removals.length === 0) {
+        return { result: "success", message: "No pack entries removed" };
+    }
+    // 2. Read current manifest
+    const manifestPath = path.join(ws.layout.authoredRoot("pack"), packName, PACK_MANIFEST_FILENAME);
+    yield* ws.runTransaction({
+        targets: [manifestPath],
+        transition: Effect.gen(function* () {
+            const manifestContent = yield* fs.readFileString(manifestPath).pipe(Effect.mapError((e) => new AuthoringFailed({
+                category: "not_found",
+                detail: `Pack manifest not found at ${manifestPath}`,
+                suggestions: [{ description: "Ensure the pack exists on disk" }],
+                cause: e,
+            })));
+            // 3. Stale-check: compare content hash
+            const currentHash = hashContent(manifestContent);
+            if (currentHash !== manifestHash) {
+                return yield* new AuthoringFailed({
+                    category: "conflict",
+                    detail: `Pack manifest is stale — it was modified since the plan was created`,
+                    suggestions: [{ description: "Re-run the command to create a fresh plan" }],
+                });
+            }
+            // 4. Parse and apply removals
+            const json = yield* Effect.try({
+                try: () => {
+                    const parsed = JSON.parse(manifestContent);
+                    return parsed;
+                },
+                catch: (e) => new AuthoringFailed({
+                    category: "validation",
+                    detail: `Failed to parse pack manifest: ${manifestPath}`,
+                    cause: e,
+                }),
+            });
+            const manifest = yield* Schema.decodeUnknownEffect(PackManifestSchema)(json).pipe(Effect.mapError((e) => new AuthoringFailed({
+                category: "validation",
+                detail: `Invalid pack manifest: ${manifestPath}`,
+                cause: e,
+            })));
+            const removalSet = new Set(removals);
+            const dependencies = Object.fromEntries(Object.entries(manifest.dependencies).filter(([name]) => !removalSet.has(name)));
+            const updatedManifest = {
+                ...manifest,
+                owner: manifest.owner,
+                type: manifest.type,
+                name: manifest.name,
+                version: manifest.version,
+                dependencies,
+            };
+            const validatedUpdatedManifest = yield* Schema.decodeUnknownEffect(PackManifestSchema)(updatedManifest).pipe(Effect.mapError((cause) => new AuthoringFailed({
+                category: "validation",
+                detail: `Updated pack manifest is invalid: ${manifestPath}`,
+                cause,
+            })));
+            // 5. Write updated manifest
+            yield* fs
+                .writeFileString(manifestPath, JSON.stringify(validatedUpdatedManifest, null, 2) + "\n")
+                .pipe(Effect.mapError((e) => new AuthoringFailed({
+                category: "internal",
+                detail: `Failed to write pack manifest: ${manifestPath}`,
+                cause: e,
+            })));
+        }),
+        validate: () => fs.readFileString(manifestPath).pipe(Effect.flatMap((content) => Effect.try({
+            try: () => JSON.parse(content),
+            catch: (cause) => new AuthoringFailed({
+                category: "validation",
+                detail: `Updated pack manifest could not be parsed: ${manifestPath}`,
+                cause,
+            }),
+        })), Effect.flatMap(Schema.decodeUnknownEffect(PackManifestSchema)), Effect.flatMap((manifest) => removals.every((fqn) => manifest.dependencies[fqn] === undefined)
+            ? Effect.void
+            : new AuthoringFailed({
+                category: "internal",
+                detail: `Updated pack manifest retained a removed dependency`,
+            })), Effect.mapError((cause) => new AuthoringFailed({
+            category: "validation",
+            detail: `Updated pack manifest failed postcondition validation`,
+            cause,
+        }))),
+    });
+    return {
+        result: "success",
+        message: `Removed ${removals.length} extension${removals.length === 1 ? "" : "s"} from pack`,
+        artifact: packManifestArtifact({
+            owner: packOwner,
+            name: packName,
+            scope: ws.scope,
+            change: "updated",
+            fileCount: 1,
+        }),
+    };
+}).pipe(withAdaptedStepFailures);
+//# sourceMappingURL=remove-from-pack.js.map

package/dist/src/skills/new-skill.d.ts

@@ -0,0 +1,40 @@
+/**
+ * New skill operation — scaffolds a new skill directory with manifest and SKILL.md.
+ *
+ * @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";
+/**
+ * Args for the new-skill operation.
+ */
+export interface NewSkillOperationArgs {
+    /** Skill name (validated, lowercase with hyphens). */
+    readonly name: string;
+    /** Profile (e.g., "@myorg"). */
+    readonly owner: Handle;
+    /** Agent IDs selected by the CLI. Install/materialization consumes workspace configuration. */
+    readonly agents: ReadonlyArray<string>;
+}
+/**
+ * Scaffold a new skill in the workspace.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type NewSkillOperation = Operation<"new-skill", NewSkillOperationArgs>;
+/**
+ * New-skill operation handler.
+ *
+ * 1. Compute paths from the resolved workspace layout
+ * 2. Check if skill already exists in settings
+ * 3. Create skill directory (src/)
+ * 4. Write skill.json manifest
+ * 5. Write starter SKILL.md
+ */
+export declare const newSkill: OperationHandler<NewSkillOperation, FileSystem.FileSystem | Path.Path | WorkspaceMutations | AuthoringFailureAdapter>;
+//# sourceMappingURL=new-skill.d.ts.map

package/dist/src/skills/new-skill.js

@@ -0,0 +1,102 @@
+/**
+ * New skill operation — scaffolds a new skill directory with manifest and SKILL.md.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import { AuthoringFailed } from "../errors.js";
+import { AuthoringFailureAdapter, withAdaptedStepFailures } from "../failure-adapter.js";
+import { createCanonicalDirectory, recoverCanonicalDirectory } from "@agentxm/extension-workspace";
+import { preflightCreateOnly } from "../create-preflight.js";
+import { decodeExtensionNameSync } from "@agentxm/extension-model/unstable/extensions";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { MANIFEST_FILENAME, MANIFEST_SCHEMA_URL, } from "@agentxm/extension-model/unstable/skills/manifest-schema";
+import { decodeVersionSync } from "@agentxm/extension-model/unstable/version-constraints";
+// -----------------------------------------------------------------------------
+// Helpers
+// -----------------------------------------------------------------------------
+const makeSkillMd = (name) => `---
+name: ${name}
+description: Describe when this skill should be triggered by the agent
+---
+
+Describe what this skill does and when to use it.
+`;
+const INITIAL_SKILL_VERSION = decodeVersionSync("0.0.1");
+// -----------------------------------------------------------------------------
+// Public API
+// -----------------------------------------------------------------------------
+/**
+ * New-skill operation handler.
+ *
+ * 1. Compute paths from the resolved workspace layout
+ * 2. Check if skill already exists in settings
+ * 3. Create skill directory (src/)
+ * 4. Write skill.json manifest
+ * 5. Write starter SKILL.md
+ */
+export const newSkill = (op) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const ws = yield* WorkspaceMutations;
+    const base = ws.baseDir;
+    if (ws.layout.scope !== "project") {
+        return yield* new AuthoringFailed({
+            category: "validation",
+            detail: "New skills can only be scaffolded in a project workspace",
+        });
+    }
+    const { name, owner } = op.args;
+    const fqn = `${owner}/skills/${name}`;
+    const configuredSkills = yield* ws.getConfiguredSkillEntries();
+    const canonicalPath = path.join(ws.layout.authoredRoot("skill"), name);
+    yield* recoverCanonicalDirectory({ baseDir: base, canonicalPath });
+    yield* preflightCreateOnly({
+        subject: "Skill",
+        name,
+        configured: Object.hasOwn(configuredSkills, name),
+        destinations: [canonicalPath],
+    });
+    const manifest = {
+        $schema: MANIFEST_SCHEMA_URL,
+        owner,
+        type: "skill",
+        name: decodeExtensionNameSync(name),
+        version: INITIAL_SKILL_VERSION,
+    };
+    yield* createCanonicalDirectory({
+        baseDir: base,
+        canonicalPath,
+        subject: "Skill",
+        requiredFiles: [MANIFEST_FILENAME, "src/SKILL.md"],
+        populate: (stagingPath) => {
+            const skillSrcPath = path.join(stagingPath, "src");
+            return Effect.gen(function* () {
+                yield* fs.makeDirectory(skillSrcPath, { recursive: true }).pipe(Effect.mapError((e) => new AuthoringFailed({
+                    category: "validation",
+                    detail: `Failed to create skill directory: ${skillSrcPath}`,
+                    cause: e,
+                })));
+                yield* fs
+                    .writeFileString(path.join(stagingPath, MANIFEST_FILENAME), JSON.stringify(manifest, null, 2) + "\n")
+                    .pipe(Effect.mapError((e) => new AuthoringFailed({
+                    category: "validation",
+                    detail: "Skill manifest could not be written",
+                    cause: e,
+                })));
+                yield* fs.writeFileString(path.join(skillSrcPath, "SKILL.md"), makeSkillMd(name)).pipe(Effect.mapError((e) => new AuthoringFailed({
+                    category: "validation",
+                    detail: "Failed to write SKILL.md",
+                    cause: e,
+                })));
+            });
+        },
+    });
+    return {
+        result: "success",
+        message: `Created skill ${fqn}`,
+    };
+}).pipe(withAdaptedStepFailures);
+//# sourceMappingURL=new-skill.js.map

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@agentxm/extension-authoring",
+  "version": "0.28.4-bootstrap.0",
+  "description": "AXM extension-authoring feature: new-extension scaffolding, fork, native import, adopt/demote identity policy, and authored pack membership for the axm CLI. Unstable and unsupported — use the axm.sh CLI.",
+  "type": "module",
+  "license": "FSL-1.1-MIT",
+  "homepage": "https://axm.sh",
+  "bugs": {
+    "url": "https://github.com/agentxm/axm/issues"
+  },
+  "author": "AgentXM <hello@agentxm.ai> (https://agentxm.ai)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentxm/axm.git",
+    "directory": "packages/extension-authoring"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/src/",
+    "!**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "nx": {
+    "includedScripts": []
+  },
+  "dependencies": {
+    "effect": "4.0.0-rc.112",
+    "yaml": "^2.9.0",
+    "@agentxm/extension-model": "^0.28.4-bootstrap.0",
+    "@agentxm/registry-protocol": "^0.28.4-bootstrap.0",
+    "@agentxm/workspace-state": "^0.28.4-bootstrap.0",
+    "@agentxm/workspace-operations": "^0.28.4-bootstrap.0",
+    "@agentxm/extension-workspace": "^0.28.4-bootstrap.0"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.0.0-rc.112",
+    "@effect/vitest": "4.0.0-rc.112",
+    "@types/bun": "^1.3.14",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^4.1.10"
+  }
+}