@agentxm/extension-content 0.28.14-preview.1789139351.5cd4595aa

package/dist/src/packaging/manifest-policy.js

@@ -0,0 +1,196 @@
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+import { ExtensionNameSchema, ExtensionTypeSchema, } from "@agentxm/extension-model/unstable/extensions/common";
+import { HookManifestSchema, HOOK_MANIFEST_FILENAME, } from "@agentxm/extension-model/unstable/hooks/manifest-schema";
+import { HandleSchema } from "@agentxm/extension-model/unstable/extensions/handle";
+import { KnowledgeManifestSchema, KNOWLEDGE_MANIFEST_FILENAME, } from "@agentxm/extension-model/unstable/knowledge/manifest-schema";
+import { McpServerManifestSchema, MCP_SERVER_MANIFEST_FILENAME, } from "@agentxm/extension-model/unstable/mcps/manifest-schema";
+import { PACK_MANIFEST_FILENAME, PackManifestSchema, } from "@agentxm/extension-model/unstable/packs/manifest-schema";
+import { RuleManifestSchema, RULE_MANIFEST_FILENAME, } from "@agentxm/extension-model/unstable/rules/manifest-schema";
+import { SkillManifestSchema, MANIFEST_FILENAME as SKILL_MANIFEST_FILENAME, } from "@agentxm/extension-model/unstable/skills/manifest-schema";
+import { SubagentManifestSchema, MANIFEST_FILENAME as SUBAGENT_MANIFEST_FILENAME, } from "@agentxm/extension-model/unstable/subagents/manifest-schema";
+import { VersionSchema } from "@agentxm/extension-model/unstable/version-constraints";
+export class ManifestError extends Data.TaggedError("ManifestError") {
+}
+export const MANIFEST_FILENAME_BY_TYPE = {
+    skill: SKILL_MANIFEST_FILENAME,
+    "mcp-server": MCP_SERVER_MANIFEST_FILENAME,
+    subagent: SUBAGENT_MANIFEST_FILENAME,
+    pack: PACK_MANIFEST_FILENAME,
+    rule: RULE_MANIFEST_FILENAME,
+    hook: HOOK_MANIFEST_FILENAME,
+    knowledge: KNOWLEDGE_MANIFEST_FILENAME,
+};
+export const manifestFilenameForType = (type) => MANIFEST_FILENAME_BY_TYPE[type];
+export const ManifestIdentitySchema = Schema.Struct({
+    owner: HandleSchema.pipe(Schema.annotateKey({ messageMissingKey: "owner is required" })),
+    type: ExtensionTypeSchema.pipe(Schema.annotateKey({ messageMissingKey: "type is required" })),
+    name: ExtensionNameSchema.pipe(Schema.annotateKey({ messageMissingKey: "name is required" })),
+    version: VersionSchema.pipe(Schema.annotateKey({ messageMissingKey: "version is required" })),
+}).annotate({
+    identifier: "ManifestIdentity",
+    title: "Manifest Identity",
+    description: "The key identity fields from a manifest: who owns it, what type, its name, and version.",
+});
+const MANIFEST_SCHEMA_BY_TYPE = {
+    skill: SkillManifestSchema,
+    "mcp-server": McpServerManifestSchema,
+    subagent: SubagentManifestSchema,
+    pack: PackManifestSchema,
+    rule: RuleManifestSchema,
+    hook: HookManifestSchema,
+    knowledge: KnowledgeManifestSchema,
+};
+export const manifestSchemaForType = (type) => MANIFEST_SCHEMA_BY_TYPE[type];
+const hasOwnField = (value, field) => typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.hasOwn(value, field);
+const purlHasVersion = (value) => {
+    const queryStart = value.search(/[?#]/);
+    const comparable = queryStart === -1 ? value : value.slice(0, queryStart);
+    const lastSlash = comparable.lastIndexOf("/");
+    return lastSlash >= 0 && comparable.indexOf("@", lastSlash + 1) !== -1;
+};
+const purlType = (value) => {
+    const match = /^pkg:([^/]+)\//i.exec(value);
+    return match?.[1]?.toLowerCase();
+};
+const versScheme = (value) => {
+    const match = /^vers:([^/]+)\//i.exec(value);
+    return match?.[1]?.toLowerCase();
+};
+const classifyCompanionPackageManifestError = (raw) => {
+    if (typeof raw !== "object" || raw === null || !("packages" in raw)) {
+        return undefined;
+    }
+    const packages = Reflect.get(raw, "packages");
+    if (!Array.isArray(packages)) {
+        return {
+            code: "companion_package_invalid",
+            detail: "Manifest packages must be an array of companion package objects.",
+        };
+    }
+    for (const entry of packages) {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            return {
+                code: "companion_package_invalid",
+                detail: "Manifest packages entries must be objects with purl and optional versionRange fields.",
+            };
+        }
+        const purl = Reflect.get(entry, "purl");
+        if (typeof purl !== "string") {
+            return {
+                code: "companion_package_invalid",
+                detail: "Manifest packages entries must include a purl string.",
+            };
+        }
+        if (purlHasVersion(purl)) {
+            return {
+                code: "companion_package_purl_has_version",
+                detail: "Companion package purls are identities, not pins. Move versions into versionRange.",
+            };
+        }
+        const versionRange = Reflect.get(entry, "versionRange");
+        if (versionRange !== undefined && typeof versionRange !== "string") {
+            return {
+                code: "companion_package_invalid",
+                detail: "Manifest packages versionRange must be a VERS string.",
+            };
+        }
+        const packageType = purlType(purl);
+        const rangeScheme = typeof versionRange === "string" ? versScheme(versionRange) : undefined;
+        if (packageType !== undefined && rangeScheme !== undefined && packageType !== rangeScheme) {
+            return {
+                code: "companion_package_scheme_mismatch",
+                detail: "Companion package purl ecosystem must match the versionRange VERS scheme.",
+            };
+        }
+    }
+    // No concrete companion-package problem found: the schema decode failed for an
+    // unrelated reason, so let the caller fall back to a generic manifest error
+    // rather than misreporting it as companion_package_invalid.
+    return undefined;
+};
+export const validateManifestHasNoAgentsField = (fileName, raw) => {
+    if (!hasOwnField(raw, "agents"))
+        return Result.void;
+    return Result.fail(new ManifestError({
+        code: "manifest_schema_invalid",
+        detail: `Manifest file "${fileName}" must not include "agents"; express targeting in settings.agents.`,
+    }));
+};
+export const resolveManifest = (input) => Effect.gen(function* () {
+    const expectedFilename = manifestFilenameForType(input.type);
+    const [manifestEntry, ...rest] = input.entries.filter((entry) => {
+        const normalized = entry.fileName.replace(/\\/g, "/");
+        return (normalized === expectedFilename ||
+            normalized.toLowerCase() === expectedFilename.toLowerCase());
+    });
+    if (manifestEntry === undefined) {
+        return yield* new ManifestError({
+            code: "manifest_missing",
+            detail: `Expected manifest file "${expectedFilename}" not found in archive root.`,
+        });
+    }
+    if (rest.length > 0) {
+        const allCandidates = [manifestEntry, ...rest];
+        return yield* new ManifestError({
+            code: "manifest_multiple",
+            detail: `Multiple manifest candidates found for type "${input.type}": ${allCandidates.map((candidate) => candidate.fileName).join(", ")}.`,
+        });
+    }
+    const rawBytes = yield* input.readEntry(manifestEntry.fileName);
+    const text = new TextDecoder().decode(rawBytes);
+    const parsed = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown))(text).pipe(Effect.mapError(() => new ManifestError({
+        code: "manifest_invalid_json",
+        detail: `Manifest file "${manifestEntry.fileName}" contains invalid JSON.`,
+    })));
+    yield* Effect.fromResult(validateManifestHasNoAgentsField(manifestEntry.fileName, parsed));
+    const schema = manifestSchemaForType(input.type);
+    yield* Schema.decodeUnknownEffect(schema)(parsed).pipe(Effect.mapError((error) => {
+        const companionPackageError = classifyCompanionPackageManifestError(parsed);
+        return new ManifestError({
+            code: companionPackageError?.code ?? "manifest_schema_invalid",
+            detail: companionPackageError?.detail ??
+                `Manifest file "${manifestEntry.fileName}" does not conform to the ${input.type} manifest schema.`,
+            details: SchemaIssue.makeFormatterDefault()(error.issue),
+        });
+    }));
+    const identity = yield* Schema.decodeUnknownEffect(ManifestIdentitySchema)(parsed).pipe(Effect.mapError(() => new ManifestError({
+        code: "manifest_schema_invalid",
+        detail: `Manifest file "${manifestEntry.fileName}" is missing required identity fields (owner, type, name, version).`,
+    })));
+    return {
+        identity,
+        raw: parsed,
+        fileName: manifestEntry.fileName,
+    };
+});
+export const validateDeclaredManifestAlignment = (declaredIdentity, manifest) => {
+    const mismatches = [];
+    if (declaredIdentity.name !== manifest.name) {
+        mismatches.push(`name: declared="${declaredIdentity.name}" manifest="${manifest.name}"`);
+    }
+    if (declaredIdentity.owner !== manifest.owner) {
+        mismatches.push(`owner: declared="${declaredIdentity.owner}" manifest="${manifest.owner}"`);
+    }
+    if (declaredIdentity.type !== manifest.type) {
+        mismatches.push(`type: declared="${declaredIdentity.type}" manifest="${manifest.type}"`);
+    }
+    if (declaredIdentity.version !== manifest.version) {
+        mismatches.push(`version: declared="${declaredIdentity.version}" manifest="${manifest.version}"`);
+    }
+    if (mismatches.length > 0) {
+        return Result.fail(new ManifestError({
+            code: "declared_manifest_mismatch",
+            detail: `Declared publish identity and manifest identity disagree: ${mismatches.join(", ")}.`,
+            details: { declaredIdentity, manifest },
+        }));
+    }
+    return Result.void;
+};
+//# sourceMappingURL=manifest-policy.js.map

package/dist/src/packaging/test-zip-helpers.d.ts

@@ -0,0 +1,13 @@
+interface ZipFileEntry {
+    fileName: string;
+    content: Uint8Array;
+    compressionMethod?: number;
+    externalAttributes?: number;
+}
+export declare const buildZip: (entries: ZipFileEntry[]) => Uint8Array;
+export declare const buildSymlinkZip: (symlinkName: string, targetPath: string) => Uint8Array;
+export declare const buildDecompressionBombZip: (uncompressedSize: number, compressedSize: number, entryName?: string) => Uint8Array;
+export declare const buildMalformedZip: () => Uint8Array;
+export declare const textContent: (text: string) => Uint8Array;
+export {};
+//# sourceMappingURL=test-zip-helpers.d.ts.map

package/dist/src/packaging/test-zip-helpers.js

@@ -0,0 +1,117 @@
+import * as zlib from "node:zlib";
+const textEncoder = new TextEncoder();
+const LOCAL_FILE_HEADER_SIG = 0x04034b50;
+const CENTRAL_DIR_SIG = 0x02014b50;
+const EOCD_SIG = 0x06054b50;
+const writeUint32LE = (buf, offset, value) => buf.setUint32(offset, value, true);
+const writeUint16LE = (buf, offset, value) => buf.setUint16(offset, value, true);
+const concatBytes = (arrays) => {
+    const totalLength = arrays.reduce((sum, array) => sum + array.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const array of arrays) {
+        result.set(array, offset);
+        offset += array.length;
+    }
+    return result;
+};
+export const buildZip = (entries) => {
+    const centralDirs = [];
+    let currentOffset = 0;
+    const localParts = [];
+    for (const entry of entries) {
+        const fileNameBytes = textEncoder.encode(entry.fileName);
+        const compressionMethod = entry.compressionMethod ?? 0;
+        let compressedData;
+        if (compressionMethod === 8) {
+            const deflated = zlib.deflateRawSync(entry.content);
+            compressedData = new Uint8Array(deflated.buffer, deflated.byteOffset, deflated.byteLength);
+        }
+        else {
+            compressedData = entry.content;
+        }
+        const localBuf = new ArrayBuffer(30);
+        const localView = new DataView(localBuf);
+        writeUint32LE(localView, 0, LOCAL_FILE_HEADER_SIG);
+        writeUint16LE(localView, 4, 20);
+        writeUint16LE(localView, 6, 0);
+        writeUint16LE(localView, 8, compressionMethod);
+        writeUint16LE(localView, 10, 0);
+        writeUint16LE(localView, 12, 0);
+        writeUint32LE(localView, 14, 0);
+        writeUint32LE(localView, 18, compressedData.length);
+        writeUint32LE(localView, 22, entry.content.length);
+        writeUint16LE(localView, 26, fileNameBytes.length);
+        writeUint16LE(localView, 28, 0);
+        const localHeaderBytes = new Uint8Array(localBuf);
+        const localRecord = concatBytes([localHeaderBytes, fileNameBytes, compressedData]);
+        localParts.push(localRecord);
+        const cdirBuf = new ArrayBuffer(46);
+        const cdirView = new DataView(cdirBuf);
+        writeUint32LE(cdirView, 0, CENTRAL_DIR_SIG);
+        writeUint16LE(cdirView, 4, 20);
+        writeUint16LE(cdirView, 6, 20);
+        writeUint16LE(cdirView, 8, 0);
+        writeUint16LE(cdirView, 10, compressionMethod);
+        writeUint16LE(cdirView, 12, 0);
+        writeUint16LE(cdirView, 14, 0);
+        writeUint32LE(cdirView, 16, 0);
+        writeUint32LE(cdirView, 20, compressedData.length);
+        writeUint32LE(cdirView, 24, entry.content.length);
+        writeUint16LE(cdirView, 28, fileNameBytes.length);
+        writeUint16LE(cdirView, 30, 0);
+        writeUint16LE(cdirView, 32, 0);
+        writeUint16LE(cdirView, 34, 0);
+        writeUint16LE(cdirView, 36, 0);
+        writeUint32LE(cdirView, 38, entry.externalAttributes ?? 0);
+        writeUint32LE(cdirView, 42, currentOffset);
+        centralDirs.push(concatBytes([new Uint8Array(cdirBuf), fileNameBytes]));
+        currentOffset += localRecord.length;
+    }
+    const cdirStartOffset = currentOffset;
+    const allCdir = concatBytes(centralDirs);
+    const eocdBuf = new ArrayBuffer(22);
+    const eocdView = new DataView(eocdBuf);
+    writeUint32LE(eocdView, 0, EOCD_SIG);
+    writeUint16LE(eocdView, 4, 0);
+    writeUint16LE(eocdView, 6, 0);
+    writeUint16LE(eocdView, 8, entries.length);
+    writeUint16LE(eocdView, 10, entries.length);
+    writeUint32LE(eocdView, 12, allCdir.length);
+    writeUint32LE(eocdView, 16, cdirStartOffset);
+    writeUint16LE(eocdView, 20, 0);
+    return concatBytes([...localParts, allCdir, new Uint8Array(eocdBuf)]);
+};
+export const buildSymlinkZip = (symlinkName, targetPath) => {
+    const symlinkAttrs = (0xa000 | 0o777) << 16;
+    return buildZip([
+        {
+            fileName: symlinkName,
+            content: textEncoder.encode(targetPath),
+            externalAttributes: symlinkAttrs,
+        },
+    ]);
+};
+export const buildDecompressionBombZip = (uncompressedSize, compressedSize, entryName = "bomb.bin") => {
+    const content = new Uint8Array(compressedSize);
+    const zip = buildZip([
+        {
+            fileName: entryName,
+            content,
+            compressionMethod: 0,
+        },
+    ]);
+    const view = new DataView(zip.buffer, zip.byteOffset, zip.byteLength);
+    view.setUint32(22, uncompressedSize, true);
+    for (let i = zip.length - 22; i >= 0; i--) {
+        if (view.getUint32(i, true) === EOCD_SIG) {
+            const cdirOffset = view.getUint32(i + 16, true);
+            view.setUint32(cdirOffset + 24, uncompressedSize, true);
+            break;
+        }
+    }
+    return zip;
+};
+export const buildMalformedZip = () => new Uint8Array([0x00, 0x01, 0x02, 0x03, 0x04, 0x05]);
+export const textContent = (text) => textEncoder.encode(text);
+//# sourceMappingURL=test-zip-helpers.js.map

package/dist/src/testing.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Deterministic archive builders for tests that exercise archive guardrails
+ * and publish input normalization without a zip tool.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+export { buildDecompressionBombZip, buildMalformedZip, buildSymlinkZip, buildZip, textContent, } from "./packaging/test-zip-helpers.js";
+//# sourceMappingURL=testing.d.ts.map

package/dist/src/testing.js

@@ -0,0 +1,9 @@
+/**
+ * Deterministic archive builders for tests that exercise archive guardrails
+ * and publish input normalization without a zip tool.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+export { buildDecompressionBombZip, buildMalformedZip, buildSymlinkZip, buildZip, textContent, } from "./packaging/test-zip-helpers.js";
+//# sourceMappingURL=testing.js.map

package/package.json

@@ -0,0 +1,65 @@
+{
+  "author": "AgentXM <hello@agentxm.ai> (https://agentxm.ai)",
+  "bugs": {
+    "url": "https://github.com/agentxm/axm/issues"
+  },
+  "dependencies": {
+    "@agentxm/extension-model": "^0.28.14-preview.1789139351.5cd4595aa",
+    "effect": "4.0.0-rc.112",
+    "yaml": "^2.9.0"
+  },
+  "description": "AXM extension content behavior: skill and subagent content parsing, Knowledge bundle inspection and search, the lint rule catalog, and archive and manifest validation shared by the axm CLI and the AgentXM Registry. Unstable and unsupported — use the axm.sh CLI.",
+  "devDependencies": {
+    "@effect/platform-node": "4.0.0-rc.112",
+    "@effect/vitest": "4.0.0-rc.112",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "exports": {
+    ".": {
+      "axm-source": "./src/index.ts",
+      "default": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    },
+    "./knowledge": {
+      "axm-source": "./src/knowledge/index.ts",
+      "default": "./dist/src/knowledge/index.js",
+      "types": "./dist/src/knowledge/index.d.ts"
+    },
+    "./lint": {
+      "axm-source": "./src/lint/index.ts",
+      "default": "./dist/src/lint/index.js",
+      "types": "./dist/src/lint/index.d.ts"
+    },
+    "./testing": {
+      "axm-source": "./src/testing.ts",
+      "default": "./dist/src/testing.js",
+      "types": "./dist/src/testing.d.ts"
+    }
+  },
+  "files": [
+    "dist/src/",
+    "!**/*.map"
+  ],
+  "homepage": "https://axm.sh",
+  "license": "FSL-1.1-MIT",
+  "name": "@agentxm/extension-content",
+  "nx": {
+    "includedScripts": []
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "packages/core/extension-content",
+    "type": "git",
+    "url": "https://github.com/agentxm/axm.git"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "version": "0.28.14-preview.1789139351.5cd4595aa"
+}