@agentproto/define-doctype 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1 @@
+MIT License — Copyright (c) 2026 agentproto contributors

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @agentproto/define-doctype — meta-factory for AIP `defineX` constructors.
+ *
+ * Every AIP that defines a markdown-with-frontmatter doctype ships a
+ * `defineX(definition)` constructor (`defineTool` for AIP-14, `defineDriver`
+ * for AIP-30, future `defineSkill` / `defineKnowledge` / …). Those
+ * constructors share a small invariant prologue: validate the `id`
+ * against a regex, validate `description` length, throw with a canonical
+ * error prefix, freeze the returned handle.
+ *
+ * `createDoctype` lifts that prologue to one place. Each per-AIP
+ * package supplies the spec-specific bits via `validate(def)` and
+ * `build(def)`; the factory wires them together with the shared rules.
+ *
+ * Recommended scaffold for new AIPs (referenced from AIP-1).
+ */
+/**
+ * Default shape every AIP definition is assumed to satisfy when no
+ * custom `readIdentity` / `readDescription` extractors are passed.
+ *
+ * Most AIPs (AIP-14 TOOL, AIP-30 DRIVER, AIP-3 SKILL, …) carry
+ * `id` + `description`. AIPs that depart from this convention (e.g.
+ * AIP-7 POLICY uses `slug` + `name`, with `description` optional)
+ * supply their own extractors via `DoctypeOptions`.
+ */
+interface DoctypeDefinitionBase {
+    id: string;
+    description: string;
+}
+interface DoctypeOptions<TDef, THandle> {
+    /**
+     * AIP number — surfaces in error messages so a thrown stack frame
+     * inside a framework adapter still tells you which spec rejected
+     * the definition.
+     */
+    aip: number;
+    /**
+     * Doctype name (lower-case singular). Used to build the error
+     * prefix: `name = "tool"` → "defineTool: …".
+     */
+    name: string;
+    /**
+     * Extract the identity string (kebab-id, slug, …) to validate against
+     * `idPattern`. Default: `(def) => (def as { id: string }).id` —
+     * works for any AIP whose definition has an `id` field. AIPs whose
+     * identity field has a different name (e.g. AIP-7 POLICY's `slug`)
+     * supply their own reader.
+     */
+    readIdentity?: (def: TDef) => string;
+    /**
+     * Override the default identity pattern. Default:
+     * `/^[a-z0-9][a-z0-9._-]{1,79}$/` — kebab/snake/dot separated,
+     * 2-80 chars, leading alphanumeric. AIPs with stricter rules
+     * (AIP-7 POLICY uses `^[a-z0-9][a-z0-9-]*$`, no dots) override.
+     */
+    idPattern?: RegExp;
+    /**
+     * Extract the LLM-facing prose used by the length check. Default:
+     * `(def) => (def as { description: string }).description`. Pass
+     * `false` to skip the length validation (e.g. AIPs where
+     * description is optional, or where the human-readable string lives
+     * in a different field).
+     */
+    readDescription?: ((def: TDef) => string | undefined) | false;
+    /**
+     * Override the maximum prose length. Default 2000. AIPs whose
+     * doctypes carry longer normative text on the doctype itself can
+     * raise this; most should keep the default for prompt-injection
+     * resistance.
+     */
+    maxDescriptionLen?: number;
+    /**
+     * Spec-specific validations that run AFTER the default id and
+     * description checks. Throw on failure. Stays out of `build()` so
+     * the build path can assume a validated definition.
+     */
+    validate?: (def: TDef) => void;
+    /**
+     * Build the immutable handle from a validated definition. Apply
+     * defaults, freeze nested arrays/objects per the spec's freezing
+     * rules, return the handle. The factory takes care of the
+     * top-level `Object.freeze`.
+     */
+    build: (def: TDef) => THandle;
+}
+/**
+ * Build a `defineX(definition)` constructor that enforces the
+ * cross-AIP invariants and delegates spec-specific behaviour to
+ * `validate` / `build`.
+ *
+ * Usage (from `@agentproto/tool/src/define-tool.ts`):
+ *
+ *     export const defineTool = createDoctype<ToolDefinition, ToolHandle>({
+ *       aip: 14,
+ *       name: "tool",
+ *       validate(def) { ...spec-14 checks... },
+ *       build(def) { ...defaulting + nested freezing... },
+ *     })
+ */
+declare function createDoctype<TDef, THandle>(opts: DoctypeOptions<TDef, THandle>): (def: TDef) => THandle;
+declare const DOCTYPE_DEFAULT_ID_PATTERN: RegExp;
+declare const DOCTYPE_MAX_DESCRIPTION_LEN = 2000;
+/**
+ * Filter a value to its YAML-serialisable subset:
+ *  - functions removed (e.g. driver `execute[id]: ExecuteFn`)
+ *  - zod schemas removed (e.g. tool `inputSchema`, `outputSchema`,
+ *    `contextSchema` — they live in TS, not in frontmatter)
+ *  - `undefined` values dropped from objects (so the YAML output
+ *    doesn't carry empty keys; `null` is preserved as a real value)
+ *
+ * Used by per-AIP `createX(params, opts)` to project a validated
+ * definition into a manifest-shaped object before writing to disk.
+ * Pure function; no I/O.
+ */
+declare function filterSerializable(value: unknown): unknown;
+
+export { DOCTYPE_DEFAULT_ID_PATTERN, DOCTYPE_MAX_DESCRIPTION_LEN, type DoctypeDefinitionBase, type DoctypeOptions, createDoctype, filterSerializable };

package/dist/index.mjs

@@ -0,0 +1,64 @@
+/**
+ * @agentproto/define-doctype v0.1.0-alpha
+ * Meta-factory for AIP defineX(definition) constructors.
+ */
+
+// src/index.ts
+var DEFAULT_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{1,79}$/;
+var MAX_DESCRIPTION_LEN = 2e3;
+function createDoctype(opts) {
+  const idPattern = opts.idPattern ?? DEFAULT_ID_PATTERN;
+  const readIdentity = opts.readIdentity ?? ((def) => def.id);
+  const readDescription = opts.readDescription === false ? null : opts.readDescription ?? ((def) => def.description);
+  const maxLen = opts.maxDescriptionLen ?? MAX_DESCRIPTION_LEN;
+  const prefix = `define${capitalize(opts.name)}`;
+  const aipTag = `(AIP-${opts.aip})`;
+  return function constructDoctype(def) {
+    const identity = readIdentity(def);
+    if (typeof identity !== "string" || !idPattern.test(identity)) {
+      throw new Error(
+        `${prefix} ${aipTag}: invalid id '${String(
+          identity
+        )}' \u2014 must match ${idPattern}`
+      );
+    }
+    if (readDescription) {
+      const description = readDescription(def);
+      if (typeof description !== "string" || description.length === 0 || description.length > maxLen) {
+        throw new Error(
+          `${prefix} ${aipTag}: id='${identity}' description must be 1\u2013${maxLen} chars`
+        );
+      }
+    }
+    opts.validate?.(def);
+    return Object.freeze(opts.build(def));
+  };
+}
+function capitalize(s) {
+  return s.length === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1);
+}
+var DOCTYPE_DEFAULT_ID_PATTERN = DEFAULT_ID_PATTERN;
+var DOCTYPE_MAX_DESCRIPTION_LEN = MAX_DESCRIPTION_LEN;
+function filterSerializable(value) {
+  if (value === null || value === void 0) return value;
+  if (typeof value === "function") return void 0;
+  if (typeof value === "object" && value !== null && Object.prototype.hasOwnProperty.call(value, "_def") && "parse" in value && typeof value.parse === "function") {
+    return void 0;
+  }
+  if (Array.isArray(value)) {
+    return value.map(filterSerializable).filter((v) => v !== void 0);
+  }
+  if (typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      const filtered = filterSerializable(v);
+      if (filtered !== void 0) out[k] = filtered;
+    }
+    return out;
+  }
+  return value;
+}
+
+export { DOCTYPE_DEFAULT_ID_PATTERN, DOCTYPE_MAX_DESCRIPTION_LEN, createDoctype, filterSerializable };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * @agentproto/define-doctype — meta-factory for AIP `defineX` constructors.\n *\n * Every AIP that defines a markdown-with-frontmatter doctype ships a\n * `defineX(definition)` constructor (`defineTool` for AIP-14, `defineDriver`\n * for AIP-30, future `defineSkill` / `defineKnowledge` / …). Those\n * constructors share a small invariant prologue: validate the `id`\n * against a regex, validate `description` length, throw with a canonical\n * error prefix, freeze the returned handle.\n *\n * `createDoctype` lifts that prologue to one place. Each per-AIP\n * package supplies the spec-specific bits via `validate(def)` and\n * `build(def)`; the factory wires them together with the shared rules.\n *\n * Recommended scaffold for new AIPs (referenced from AIP-1).\n */\n\n/**\n * Default shape every AIP definition is assumed to satisfy when no\n * custom `readIdentity` / `readDescription` extractors are passed.\n *\n * Most AIPs (AIP-14 TOOL, AIP-30 DRIVER, AIP-3 SKILL, …) carry\n * `id` + `description`. AIPs that depart from this convention (e.g.\n * AIP-7 POLICY uses `slug` + `name`, with `description` optional)\n * supply their own extractors via `DoctypeOptions`.\n */\nexport interface DoctypeDefinitionBase {\n  id: string\n  description: string\n}\n\nexport interface DoctypeOptions<TDef, THandle> {\n  /**\n   * AIP number — surfaces in error messages so a thrown stack frame\n   * inside a framework adapter still tells you which spec rejected\n   * the definition.\n   */\n  aip: number\n  /**\n   * Doctype name (lower-case singular). Used to build the error\n   * prefix: `name = \"tool\"` → \"defineTool: …\".\n   */\n  name: string\n  /**\n   * Extract the identity string (kebab-id, slug, …) to validate against\n   * `idPattern`. Default: `(def) => (def as { id: string }).id` —\n   * works for any AIP whose definition has an `id` field. AIPs whose\n   * identity field has a different name (e.g. AIP-7 POLICY's `slug`)\n   * supply their own reader.\n   */\n  readIdentity?: (def: TDef) => string\n  /**\n   * Override the default identity pattern. Default:\n   * `/^[a-z0-9][a-z0-9._-]{1,79}$/` — kebab/snake/dot separated,\n   * 2-80 chars, leading alphanumeric. AIPs with stricter rules\n   * (AIP-7 POLICY uses `^[a-z0-9][a-z0-9-]*$`, no dots) override.\n   */\n  idPattern?: RegExp\n  /**\n   * Extract the LLM-facing prose used by the length check. Default:\n   * `(def) => (def as { description: string }).description`. Pass\n   * `false` to skip the length validation (e.g. AIPs where\n   * description is optional, or where the human-readable string lives\n   * in a different field).\n   */\n  readDescription?: ((def: TDef) => string | undefined) | false\n  /**\n   * Override the maximum prose length. Default 2000. AIPs whose\n   * doctypes carry longer normative text on the doctype itself can\n   * raise this; most should keep the default for prompt-injection\n   * resistance.\n   */\n  maxDescriptionLen?: number\n  /**\n   * Spec-specific validations that run AFTER the default id and\n   * description checks. Throw on failure. Stays out of `build()` so\n   * the build path can assume a validated definition.\n   */\n  validate?: (def: TDef) => void\n  /**\n   * Build the immutable handle from a validated definition. Apply\n   * defaults, freeze nested arrays/objects per the spec's freezing\n   * rules, return the handle. The factory takes care of the\n   * top-level `Object.freeze`.\n   */\n  build: (def: TDef) => THandle\n}\n\nconst DEFAULT_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{1,79}$/\nconst MAX_DESCRIPTION_LEN = 2000\n\n/**\n * Build a `defineX(definition)` constructor that enforces the\n * cross-AIP invariants and delegates spec-specific behaviour to\n * `validate` / `build`.\n *\n * Usage (from `@agentproto/tool/src/define-tool.ts`):\n *\n *     export const defineTool = createDoctype<ToolDefinition, ToolHandle>({\n *       aip: 14,\n *       name: \"tool\",\n *       validate(def) { ...spec-14 checks... },\n *       build(def) { ...defaulting + nested freezing... },\n *     })\n */\nexport function createDoctype<TDef, THandle>(\n  opts: DoctypeOptions<TDef, THandle>,\n): (def: TDef) => THandle {\n  const idPattern = opts.idPattern ?? DEFAULT_ID_PATTERN\n  const readIdentity =\n    opts.readIdentity ?? ((def: TDef) => (def as { id: string }).id)\n  const readDescription =\n    opts.readDescription === false\n      ? null\n      : (opts.readDescription ??\n        ((def: TDef) => (def as { description: string }).description))\n  const maxLen = opts.maxDescriptionLen ?? MAX_DESCRIPTION_LEN\n  const prefix = `define${capitalize(opts.name)}`\n  const aipTag = `(AIP-${opts.aip})`\n\n  return function constructDoctype(def: TDef): THandle {\n    const identity = readIdentity(def)\n    if (typeof identity !== \"string\" || !idPattern.test(identity)) {\n      throw new Error(\n        `${prefix} ${aipTag}: invalid id '${String(\n          identity,\n        )}' — must match ${idPattern}`,\n      )\n    }\n    if (readDescription) {\n      const description = readDescription(def)\n      if (\n        typeof description !== \"string\" ||\n        description.length === 0 ||\n        description.length > maxLen\n      ) {\n        throw new Error(\n          `${prefix} ${aipTag}: id='${identity}' description must be 1–${maxLen} chars`,\n        )\n      }\n    }\n    opts.validate?.(def)\n    return Object.freeze(opts.build(def)) as THandle\n  }\n}\n\nfunction capitalize(s: string): string {\n  return s.length === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1)\n}\n\nexport const DOCTYPE_DEFAULT_ID_PATTERN = DEFAULT_ID_PATTERN\nexport const DOCTYPE_MAX_DESCRIPTION_LEN = MAX_DESCRIPTION_LEN\n\n/**\n * Filter a value to its YAML-serialisable subset:\n *  - functions removed (e.g. driver `execute[id]: ExecuteFn`)\n *  - zod schemas removed (e.g. tool `inputSchema`, `outputSchema`,\n *    `contextSchema` — they live in TS, not in frontmatter)\n *  - `undefined` values dropped from objects (so the YAML output\n *    doesn't carry empty keys; `null` is preserved as a real value)\n *\n * Used by per-AIP `createX(params, opts)` to project a validated\n * definition into a manifest-shaped object before writing to disk.\n * Pure function; no I/O.\n */\nexport function filterSerializable(value: unknown): unknown {\n  if (value === null || value === undefined) return value\n  if (typeof value === \"function\") return undefined\n  if (\n    typeof value === \"object\" &&\n    value !== null &&\n    Object.prototype.hasOwnProperty.call(value, \"_def\") &&\n    \"parse\" in value &&\n    typeof (value as { parse?: unknown }).parse === \"function\"\n  ) {\n    return undefined\n  }\n  if (Array.isArray(value)) {\n    return value.map(filterSerializable).filter((v) => v !== undefined)\n  }\n  if (typeof value === \"object\") {\n    const out: Record<string, unknown> = {}\n    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {\n      const filtered = filterSerializable(v)\n      if (filtered !== undefined) out[k] = filtered\n    }\n    return out\n  }\n  return value\n}\n"]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@agentproto/define-doctype",
+  "version": "0.1.0-alpha.0",
+  "description": "agentproto/define-doctype — meta-factory for AIP `defineX(definition)` constructors. Centralises the cross-spec invariants every define-* shares (id shape, description length, top-level freeze, error-message prefix); leaves spec-specific defaulting + nested freezing to per-AIP `build()`. Used by @agentproto/tool, @agentproto/driver, and any future AIP doctype implementation.",
+  "keywords": [
+    "agentproto",
+    "aip-1",
+    "doctype",
+    "defineX",
+    "scaffold",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentproto.sh/docs/aip-1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts"
+  },
+  "bugs": {
+    "url": "https://github.com/agentproto/ts/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}