@agentproto/manifest 0.1.0-alpha.1

package/LICENSE

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

package/README.md

@@ -0,0 +1,26 @@
+# @agentproto/manifest
+
+Generic verbs for AIP doctypes. See [AIP-1](https://agentproto.sh/docs/aip-1).
+
+```ts
+import { createVerbs } from "@agentproto/manifest"
+
+const verbs = createVerbs({
+  name: "tool",
+  aip: 14,
+  schemaLiteral: "agentproto/tool/v1",
+  pathOf: (h) => `${h.id}/TOOL.md`,
+  define: defineTool,
+  parse: parseToolManifest,
+})
+
+await verbs.create({ id: "echo", ... }, { dir: "tools" })
+const echo = await verbs.load("tools/echo/TOOL.md")
+const all = await verbs.list("tools")
+await verbs.update("tools/echo/TOOL.md", (p) => ({ ...p, version: "1.0.1" }))
+const resolved = await verbs.resolve({ ref: "@agentik/runners/python" }, ctx)
+await verbs.delete("tools/echo/TOOL.md")
+```
+
+## License
+MIT

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @agentproto/manifest — generic verbs for AIP doctypes.
+ *
+ * Every per-AIP package (`@agentproto/tool`, `@agentproto/driver`, …)
+ * supplies a `DoctypeSpec` describing the per-package knobs (name,
+ * AIP number, schema literal, path convention, validator, parser).
+ * `createVerbs(spec)` returns the full lifecycle:
+ *
+ *   create(params, opts)            params → .md on disk
+ *   load(path)                      .md on disk → handle
+ *   list(dir, filter?)              walk → handle[]
+ *   update(path, mutator)           load → patch → write back
+ *   resolve(block, ctx?)            { inline | ref | file } → handle
+ *   delete(path)                    fs.unlink
+ *
+ * Adding a new verb is a single place; every package picks it up
+ * automatically — same model as `createDoctype` for the validation
+ * pipeline.
+ */
+/**
+ * Per-package descriptor consumed by `createVerbs`.
+ *
+ * Generic over the params shape (input to `define`) and the handle
+ * shape (output of `define`). For most AIPs `THandle` extends
+ * `TParams` — handles are just frozen, defaulted definitions.
+ */
+interface DoctypeSpec<TParams extends {
+    id?: string;
+    slug?: string;
+    name?: string;
+}, THandle> {
+    /** Lower-case singular: "tool", "driver", "operator". Used in errors. */
+    name: string;
+    /** AIP number — surfaces in error messages for provenance. */
+    aip: number;
+    /** Frontmatter `schema:` literal (e.g. "agentproto/tool/v1"). */
+    schemaLiteral: string;
+    /**
+     * Filename of the doctype's manifest. By default `<DOCTYPE>.md`,
+     * derived from `name.toUpperCase()`. Override only when the
+     * doctype's filename diverges from convention.
+     */
+    filename?: string;
+    /**
+     * Path-of-handle convention. Given a validated handle, return the
+     * workspace-relative path the manifest lives at. Examples:
+     *   tool:     `(h) => `${h.id}/TOOL.md``
+     *   policy:   `(h) => `policies/${h.slug}/POLICY.md``
+     *   operator: `(h) => `${h.id}/OPERATOR.md``
+     */
+    pathOf(handle: THandle): string;
+    /** TS authoring path: validates params + applies defaults. */
+    define(params: TParams): THandle;
+    /** MD authoring path: parses YAML+body. Throws on invalid frontmatter. */
+    parse(source: string): {
+        frontmatter: Record<string, unknown>;
+        body: string;
+    };
+    /**
+     * Optional projection: handle → manifest-shaped frontmatter object.
+     * Default: pass the params through `filterSerializable` (drops zod
+     * schemas + functions). Override when the handle and frontmatter
+     * shapes diverge non-trivially.
+     */
+    toFrontmatter?(params: TParams): Record<string, unknown>;
+}
+interface CreateOptions {
+    /** Workspace-relative or absolute base directory. */
+    dir: string;
+    /** Body markdown after the frontmatter. Defaults to a one-line stub. */
+    body?: string;
+    /** Render only — don't write. Returns the rendered string. */
+    dryRun?: boolean;
+}
+interface VerbResult<THandle> {
+    path: string;
+    handle: THandle;
+    rendered: string;
+}
+interface ListOptions {
+    /** Filter the discovered handles. Receives the loaded handle. */
+    filter?: <H>(handle: H) => boolean;
+    /** Skip subdirectories matching these names. Default: ["node_modules", ".git", "dist", ".next"]. */
+    skipDirs?: readonly string[];
+}
+type RefBlock<TParams> = {
+    inline: TParams;
+} | {
+    ref: string;
+} | {
+    file: string;
+};
+interface ResolveContext {
+    /** Base dir for `file:` references. Required when resolving file blocks. */
+    baseDir?: string;
+    /**
+     * Registry resolver for `ref:` strings (e.g. `@agentik/runners/python-3.12`
+     * → handle). Optional; throws when an unresolvable ref is encountered.
+     */
+    resolveRef?: (ref: string) => Promise<unknown> | unknown;
+}
+interface Verbs<TParams, THandle> {
+    /** TS-authored params → write `<dir>/<pathOf(handle)>` on disk. */
+    create(params: TParams, opts: CreateOptions): Promise<VerbResult<THandle>>;
+    /** Read a manifest from disk → handle. */
+    load(path: string): Promise<{
+        path: string;
+        handle: THandle;
+        body: string;
+    }>;
+    /** Walk `dir` for the doctype's `*.md` files; return loaded handles. */
+    list(dir: string, opts?: ListOptions): Promise<THandle[]>;
+    /** Load → mutate → write back. Mutator receives the loaded params. */
+    update(path: string, mutator: (params: TParams, ctx: {
+        handle: THandle;
+        body: string;
+    }) => TParams | Promise<TParams>, opts?: {
+        body?: string;
+        dryRun?: boolean;
+    }): Promise<VerbResult<THandle>>;
+    /**
+     * Resolve a `{ inline | ref | file }` block to a handle. Used by
+     * doctypes that compose other doctypes (AIP-17/30/36 pattern).
+     */
+    resolve(block: RefBlock<TParams>, ctx?: ResolveContext): Promise<THandle>;
+    /** Remove the manifest file. Does NOT recurse into the containing dir. */
+    delete(path: string): Promise<void>;
+}
+declare function createVerbs<TParams extends {
+    id?: string;
+    slug?: string;
+    name?: string;
+}, THandle>(spec: DoctypeSpec<TParams, THandle>): Verbs<TParams, THandle>;
+
+export { type CreateOptions, type DoctypeSpec, type ListOptions, type RefBlock, type ResolveContext, type VerbResult, type Verbs, createVerbs };

package/dist/index.mjs

@@ -0,0 +1,128 @@
+import { filterSerializable } from '@agentproto/define-doctype';
+import matter from 'gray-matter';
+import { mkdir, writeFile, readFile, rm, readdir } from 'fs/promises';
+import { join, dirname, isAbsolute } from 'path';
+
+/**
+ * @agentproto/manifest v0.1.0-alpha
+ * Generic verbs for AIP doctypes (create, load, list, update, resolve, …).
+ */
+
+var DEFAULT_SKIP_DIRS = [
+  "node_modules",
+  ".git",
+  "dist",
+  ".next",
+  ".turbo"
+];
+function createVerbs(spec) {
+  const filename = spec.filename ?? `${spec.name.toUpperCase()}.md`;
+  const toFrontmatter = spec.toFrontmatter ?? ((params) => filterSerializable({
+    schema: spec.schemaLiteral,
+    ...params
+  }));
+  async function create(params, opts) {
+    const handle = spec.define(params);
+    const relativePath = spec.pathOf(handle);
+    const path = join(opts.dir, relativePath);
+    const frontmatter = toFrontmatter(params);
+    const rendered = matter.stringify(
+      opts.body ?? defaultBody(spec, frontmatter),
+      frontmatter
+    );
+    if (!opts.dryRun) {
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, rendered, "utf8");
+    }
+    return { path, handle, rendered };
+  }
+  async function load(path) {
+    const source = await readFile(path, "utf8");
+    const { frontmatter, body } = spec.parse(source);
+    const handle = spec.define(frontmatter);
+    return { path, handle, body };
+  }
+  async function list(dir, opts = {}) {
+    const skip = new Set(opts.skipDirs ?? DEFAULT_SKIP_DIRS);
+    const out = [];
+    async function walk(current) {
+      let entries;
+      try {
+        entries = await readdir(current, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        const entryName = String(entry.name);
+        if (entry.isDirectory()) {
+          if (skip.has(entryName)) continue;
+          await walk(join(current, entryName));
+          continue;
+        }
+        if (!entry.isFile()) continue;
+        if (entryName !== filename) continue;
+        try {
+          const { handle } = await load(join(current, entryName));
+          if (!opts.filter || opts.filter(handle)) out.push(handle);
+        } catch {
+        }
+      }
+    }
+    await walk(dir);
+    return out;
+  }
+  async function update(path, mutator, opts = {}) {
+    const { handle, body } = await load(path);
+    const source = await readFile(path, "utf8");
+    const { frontmatter } = spec.parse(source);
+    const params = frontmatter;
+    const mutated = await mutator(params, { handle, body });
+    const newHandle = spec.define(mutated);
+    const newFrontmatter = toFrontmatter(mutated);
+    const rendered = matter.stringify(
+      opts.body ?? body,
+      newFrontmatter
+    );
+    if (!opts.dryRun) {
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, rendered, "utf8");
+    }
+    return { path, handle: newHandle, rendered };
+  }
+  async function resolve(block, ctx = {}) {
+    if ("inline" in block) {
+      return spec.define(block.inline);
+    }
+    if ("file" in block) {
+      const baseDir = ctx.baseDir ?? ".";
+      const path = isAbsolute(block.file) ? block.file : join(baseDir, block.file);
+      const { handle } = await load(path);
+      return handle;
+    }
+    if ("ref" in block) {
+      if (!ctx.resolveRef) {
+        throw new Error(
+          `${spec.name}.resolve (AIP-${spec.aip}): block has \`ref: '${block.ref}'\` but no resolveRef provided in context \u2014 registries must inject their own resolver`
+        );
+      }
+      const resolved = await ctx.resolveRef(block.ref);
+      return spec.define(resolved);
+    }
+    throw new Error(
+      `${spec.name}.resolve (AIP-${spec.aip}): block must have one of inline | ref | file`
+    );
+  }
+  async function deleteFn(path) {
+    await rm(path, { force: true });
+  }
+  return { create, load, list, update, resolve, delete: deleteFn };
+}
+function defaultBody(spec, frontmatter) {
+  const id = typeof frontmatter.name === "string" ? frontmatter.name : typeof frontmatter.id === "string" ? frontmatter.id : typeof frontmatter.slug === "string" ? frontmatter.slug : spec.name;
+  return `# ${id}
+`;
+}
+
+export { createVerbs };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;AAoIA,IAAM,iBAAA,GAAuC;AAAA,EAC3C,cAAA;AAAA,EACA,MAAA;AAAA,EACA,MAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF,CAAA;AAEO,SAAS,YAGd,IAAA,EAA8D;AAC9D,EAAA,MAAM,WAAW,IAAA,CAAK,QAAA,IAAY,GAAG,IAAA,CAAK,IAAA,CAAK,aAAa,CAAA,GAAA,CAAA;AAC5D,EAAA,MAAM,aAAA,GACJ,IAAA,CAAK,aAAA,KACJ,CAAC,WACA,kBAAA,CAAmB;AAAA,IACjB,QAAQ,IAAA,CAAK,aAAA;AAAA,IACb,GAAG;AAAA,GACJ,CAAA,CAAA;AAEL,EAAA,eAAe,MAAA,CACb,QACA,IAAA,EAC8B;AAC9B,IAAA,MAAM,MAAA,GAAS,IAAA,CAAK,MAAA,CAAO,MAAM,CAAA;AACjC,IAAA,MAAM,YAAA,GAAe,IAAA,CAAK,MAAA,CAAO,MAAM,CAAA;AACvC,IAAA,MAAM,IAAA,GAAO,IAAA,CAAK,IAAA,CAAK,GAAA,EAAK,YAAY,CAAA;AACxC,IAAA,MAAM,WAAA,GAAc,cAAc,MAAM,CAAA;AACxC,IAAA,MAAM,WAAW,MAAA,CAAO,SAAA;AAAA,MACtB,IAAA,CAAK,IAAA,IAAQ,WAAA,CAAY,IAAA,EAAM,WAAW,CAAA;AAAA,MAC1C;AAAA,KACF;AACA,IAAA,IAAI,CAAC,KAAK,MAAA,EAAQ;AAChB,MAAA,MAAM,MAAM,OAAA,CAAQ,IAAI,GAAG,EAAE,SAAA,EAAW,MAAM,CAAA;AAC9C,MAAA,MAAM,SAAA,CAAU,IAAA,EAAM,QAAA,EAAU,MAAM,CAAA;AAAA,IACxC;AACA,IAAA,OAAO,EAAE,IAAA,EAAM,MAAA,EAAQ,QAAA,EAAS;AAAA,EAClC;AAEA,EAAA,eAAe,KACb,IAAA,EAC0D;AAC1D,IAAA,MAAM,MAAA,GAAS,MAAM,QAAA,CAAS,IAAA,EAAM,MAAM,CAAA;AAC1C,IAAA,MAAM,EAAE,WAAA,EAAa,IAAA,EAAK,GAAI,IAAA,CAAK,MAAM,MAAM,CAAA;AAI/C,IAAA,MAAM,MAAA,GAAS,IAAA,CAAK,MAAA,CAAO,WAAiC,CAAA;AAC5D,IAAA,OAAO,EAAE,IAAA,EAAM,MAAA,EAAQ,IAAA,EAAK;AAAA,EAC9B;AAEA,EAAA,eAAe,IAAA,CACb,GAAA,EACA,IAAA,GAAoB,EAAC,EACD;AACpB,IAAA,MAAM,IAAA,GAAO,IAAI,GAAA,CAAI,IAAA,CAAK,YAAY,iBAAiB,CAAA;AACvD,IAAA,MAAM,MAAiB,EAAC;AAExB,IAAA,eAAe,KAAK,OAAA,EAAgC;AAKlD,MAAA,IAAI,OAAA;AACJ,MAAA,IAAI;AACF,QAAA,OAAA,GAAW,MAAM,OAAA,CAAQ,OAAA,EAAS,EAAE,aAAA,EAAe,MAAM,CAAA;AAAA,MAC3D,CAAA,CAAA,MAAQ;AACN,QAAA;AAAA,MACF;AACA,MAAA,KAAA,MAAW,SAAS,OAAA,EAAS;AAC3B,QAAA,MAAM,SAAA,GAAY,MAAA,CAAO,KAAA,CAAM,IAAI,CAAA;AACnC,QAAA,IAAI,KAAA,CAAM,aAAY,EAAG;AACvB,UAAA,IAAI,IAAA,CAAK,GAAA,CAAI,SAAS,CAAA,EAAG;AACzB,UAAA,MAAM,IAAA,CAAK,IAAA,CAAK,OAAA,EAAS,SAAS,CAAC,CAAA;AACnC,UAAA;AAAA,QACF;AACA,QAAA,IAAI,CAAC,KAAA,CAAM,MAAA,EAAO,EAAG;AACrB,QAAA,IAAI,cAAc,QAAA,EAAU;AAC5B,QAAA,IAAI;AACF,UAAA,MAAM,EAAE,QAAO,GAAI,MAAM,KAAK,IAAA,CAAK,OAAA,EAAS,SAAS,CAAC,CAAA;AACtD,UAAA,IAAI,CAAC,KAAK,MAAA,IAAU,IAAA,CAAK,OAAO,MAAM,CAAA,EAAG,GAAA,CAAI,IAAA,CAAK,MAAM,CAAA;AAAA,QAC1D,CAAA,CAAA,MAAQ;AAAA,QAGR;AAAA,MACF;AAAA,IACF;AAEA,IAAA,MAAM,KAAK,GAAG,CAAA;AACd,IAAA,OAAO,GAAA;AAAA,EACT;AAEA,EAAA,eAAe,MAAA,CACb,IAAA,EACA,OAAA,EAIA,IAAA,GAA4C,EAAC,EACf;AAC9B,IAAA,MAAM,EAAE,MAAA,EAAQ,IAAA,EAAK,GAAI,MAAM,KAAK,IAAI,CAAA;AAGxC,IAAA,MAAM,MAAA,GAAS,MAAM,QAAA,CAAS,IAAA,EAAM,MAAM,CAAA;AAC1C,IAAA,MAAM,EAAE,WAAA,EAAY,GAAI,IAAA,CAAK,MAAM,MAAM,CAAA;AACzC,IAAA,MAAM,MAAA,GAAS,WAAA;AACf,IAAA,MAAM,UAAU,MAAM,OAAA,CAAQ,QAAQ,EAAE,MAAA,EAAQ,MAAM,CAAA;AACtD,IAAA,MAAM,SAAA,GAAY,IAAA,CAAK,MAAA,CAAO,OAAO,CAAA;AACrC,IAAA,MAAM,cAAA,GAAiB,cAAc,OAAO,CAAA;AAC5C,IAAA,MAAM,WAAW,MAAA,CAAO,SAAA;AAAA,MACtB,KAAK,IAAA,IAAQ,IAAA;AAAA,MACb;AAAA,KACF;AACA,IAAA,IAAI,CAAC,KAAK,MAAA,EAAQ;AAChB,MAAA,MAAM,MAAM,OAAA,CAAQ,IAAI,GAAG,EAAE,SAAA,EAAW,MAAM,CAAA;AAC9C,MAAA,MAAM,SAAA,CAAU,IAAA,EAAM,QAAA,EAAU,MAAM,CAAA;AAAA,IACxC;AACA,IAAA,OAAO,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAA,EAAW,QAAA,EAAS;AAAA,EAC7C;AAEA,EAAA,eAAe,OAAA,CACb,KAAA,EACA,GAAA,GAAsB,EAAC,EACL;AAClB,IAAA,IAAI,YAAY,KAAA,EAAO;AACrB,MAAA,OAAO,IAAA,CAAK,MAAA,CAAO,KAAA,CAAM,MAAM,CAAA;AAAA,IACjC;AACA,IAAA,IAAI,UAAU,KAAA,EAAO;AACnB,MAAA,MAAM,OAAA,GAAU,IAAI,OAAA,IAAW,GAAA;AAC/B,MAAA,MAAM,IAAA,GAAO,UAAA,CAAW,KAAA,CAAM,IAAI,CAAA,GAAI,MAAM,IAAA,GAAO,IAAA,CAAK,OAAA,EAAS,KAAA,CAAM,IAAI,CAAA;AAC3E,MAAA,MAAM,EAAE,MAAA,EAAO,GAAI,MAAM,KAAK,IAAI,CAAA;AAClC,MAAA,OAAO,MAAA;AAAA,IACT;AACA,IAAA,IAAI,SAAS,KAAA,EAAO;AAClB,MAAA,IAAI,CAAC,IAAI,UAAA,EAAY;AACnB,QAAA,MAAM,IAAI,KAAA;AAAA,UACR,CAAA,EAAG,KAAK,IAAI,CAAA,cAAA,EAAiB,KAAK,GAAG,CAAA,qBAAA,EAAwB,MAAM,GAAG,CAAA,0FAAA;AAAA,SACxE;AAAA,MACF;AACA,MAAA,MAAM,QAAA,GAAW,MAAM,GAAA,CAAI,UAAA,CAAW,MAAM,GAAG,CAAA;AAC/C,MAAA,OAAO,IAAA,CAAK,OAAO,QAAmB,CAAA;AAAA,IACxC;AACA,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,EAAG,IAAA,CAAK,IAAI,CAAA,cAAA,EAAiB,KAAK,GAAG,CAAA,6CAAA;AAAA,KACvC;AAAA,EACF;AAEA,EAAA,eAAe,SAAS,IAAA,EAA6B;AACnD,IAAA,MAAM,EAAA,CAAG,IAAA,EAAM,EAAE,KAAA,EAAO,MAAM,CAAA;AAAA,EAChC;AAEA,EAAA,OAAO,EAAE,MAAA,EAAQ,IAAA,EAAM,MAAM,MAAA,EAAQ,OAAA,EAAS,QAAQ,QAAA,EAAS;AACjE;AAEA,SAAS,WAAA,CACP,MACA,WAAA,EACQ;AACR,EAAA,MAAM,KACJ,OAAO,WAAA,CAAY,SAAS,QAAA,GACxB,WAAA,CAAY,OACZ,OAAO,WAAA,CAAY,OAAO,QAAA,GACxB,WAAA,CAAY,KACZ,OAAO,WAAA,CAAY,SAAS,QAAA,GAC1B,WAAA,CAAY,OACZ,IAAA,CAAK,IAAA;AACf,EAAA,OAAO,KAAK,EAAE;AAAA,CAAA;AAChB","file":"index.mjs","sourcesContent":["/**\n * @agentproto/manifest — generic verbs for AIP doctypes.\n *\n * Every per-AIP package (`@agentproto/tool`, `@agentproto/driver`, …)\n * supplies a `DoctypeSpec` describing the per-package knobs (name,\n * AIP number, schema literal, path convention, validator, parser).\n * `createVerbs(spec)` returns the full lifecycle:\n *\n *   create(params, opts)            params → .md on disk\n *   load(path)                      .md on disk → handle\n *   list(dir, filter?)              walk → handle[]\n *   update(path, mutator)           load → patch → write back\n *   resolve(block, ctx?)            { inline | ref | file } → handle\n *   delete(path)                    fs.unlink\n *\n * Adding a new verb is a single place; every package picks it up\n * automatically — same model as `createDoctype` for the validation\n * pipeline.\n */\n\nimport { filterSerializable } from \"@agentproto/define-doctype\"\nimport matter from \"gray-matter\"\nimport type { Dirent } from \"node:fs\"\nimport { mkdir, readFile, readdir, rm, writeFile } from \"node:fs/promises\"\nimport { dirname, isAbsolute, join } from \"node:path\"\n\n/**\n * Per-package descriptor consumed by `createVerbs`.\n *\n * Generic over the params shape (input to `define`) and the handle\n * shape (output of `define`). For most AIPs `THandle` extends\n * `TParams` — handles are just frozen, defaulted definitions.\n */\nexport interface DoctypeSpec<\n  TParams extends { id?: string; slug?: string; name?: string },\n  THandle,\n> {\n  /** Lower-case singular: \"tool\", \"driver\", \"operator\". Used in errors. */\n  name: string\n  /** AIP number — surfaces in error messages for provenance. */\n  aip: number\n  /** Frontmatter `schema:` literal (e.g. \"agentproto/tool/v1\"). */\n  schemaLiteral: string\n  /**\n   * Filename of the doctype's manifest. By default `<DOCTYPE>.md`,\n   * derived from `name.toUpperCase()`. Override only when the\n   * doctype's filename diverges from convention.\n   */\n  filename?: string\n  /**\n   * Path-of-handle convention. Given a validated handle, return the\n   * workspace-relative path the manifest lives at. Examples:\n   *   tool:     `(h) => `${h.id}/TOOL.md``\n   *   policy:   `(h) => `policies/${h.slug}/POLICY.md``\n   *   operator: `(h) => `${h.id}/OPERATOR.md``\n   */\n  pathOf(handle: THandle): string\n  /** TS authoring path: validates params + applies defaults. */\n  define(params: TParams): THandle\n  /** MD authoring path: parses YAML+body. Throws on invalid frontmatter. */\n  parse(source: string): { frontmatter: Record<string, unknown>; body: string }\n  /**\n   * Optional projection: handle → manifest-shaped frontmatter object.\n   * Default: pass the params through `filterSerializable` (drops zod\n   * schemas + functions). Override when the handle and frontmatter\n   * shapes diverge non-trivially.\n   */\n  toFrontmatter?(params: TParams): Record<string, unknown>\n}\n\nexport interface CreateOptions {\n  /** Workspace-relative or absolute base directory. */\n  dir: string\n  /** Body markdown after the frontmatter. Defaults to a one-line stub. */\n  body?: string\n  /** Render only — don't write. Returns the rendered string. */\n  dryRun?: boolean\n}\n\nexport interface VerbResult<THandle> {\n  path: string\n  handle: THandle\n  rendered: string\n}\n\nexport interface ListOptions {\n  /** Filter the discovered handles. Receives the loaded handle. */\n  filter?: <H>(handle: H) => boolean\n  /** Skip subdirectories matching these names. Default: [\"node_modules\", \".git\", \"dist\", \".next\"]. */\n  skipDirs?: readonly string[]\n}\n\nexport type RefBlock<TParams> =\n  | { inline: TParams }\n  | { ref: string }\n  | { file: string }\n\nexport interface ResolveContext {\n  /** Base dir for `file:` references. Required when resolving file blocks. */\n  baseDir?: string\n  /**\n   * Registry resolver for `ref:` strings (e.g. `@agentik/runners/python-3.12`\n   * → handle). Optional; throws when an unresolvable ref is encountered.\n   */\n  resolveRef?: (ref: string) => Promise<unknown> | unknown\n}\n\nexport interface Verbs<TParams, THandle> {\n  /** TS-authored params → write `<dir>/<pathOf(handle)>` on disk. */\n  create(params: TParams, opts: CreateOptions): Promise<VerbResult<THandle>>\n  /** Read a manifest from disk → handle. */\n  load(path: string): Promise<{ path: string; handle: THandle; body: string }>\n  /** Walk `dir` for the doctype's `*.md` files; return loaded handles. */\n  list(dir: string, opts?: ListOptions): Promise<THandle[]>\n  /** Load → mutate → write back. Mutator receives the loaded params. */\n  update(\n    path: string,\n    mutator: (params: TParams, ctx: { handle: THandle; body: string }) => TParams | Promise<TParams>,\n    opts?: { body?: string; dryRun?: boolean },\n  ): Promise<VerbResult<THandle>>\n  /**\n   * Resolve a `{ inline | ref | file }` block to a handle. Used by\n   * doctypes that compose other doctypes (AIP-17/30/36 pattern).\n   */\n  resolve(\n    block: RefBlock<TParams>,\n    ctx?: ResolveContext,\n  ): Promise<THandle>\n  /** Remove the manifest file. Does NOT recurse into the containing dir. */\n  delete(path: string): Promise<void>\n}\n\nconst DEFAULT_SKIP_DIRS: readonly string[] = [\n  \"node_modules\",\n  \".git\",\n  \"dist\",\n  \".next\",\n  \".turbo\",\n]\n\nexport function createVerbs<\n  TParams extends { id?: string; slug?: string; name?: string },\n  THandle,\n>(spec: DoctypeSpec<TParams, THandle>): Verbs<TParams, THandle> {\n  const filename = spec.filename ?? `${spec.name.toUpperCase()}.md`\n  const toFrontmatter =\n    spec.toFrontmatter ??\n    ((params: TParams) =>\n      filterSerializable({\n        schema: spec.schemaLiteral,\n        ...params,\n      }) as Record<string, unknown>)\n\n  async function create(\n    params: TParams,\n    opts: CreateOptions,\n  ): Promise<VerbResult<THandle>> {\n    const handle = spec.define(params)\n    const relativePath = spec.pathOf(handle)\n    const path = join(opts.dir, relativePath)\n    const frontmatter = toFrontmatter(params)\n    const rendered = matter.stringify(\n      opts.body ?? defaultBody(spec, frontmatter),\n      frontmatter,\n    )\n    if (!opts.dryRun) {\n      await mkdir(dirname(path), { recursive: true })\n      await writeFile(path, rendered, \"utf8\")\n    }\n    return { path, handle, rendered }\n  }\n\n  async function load(\n    path: string,\n  ): Promise<{ path: string; handle: THandle; body: string }> {\n    const source = await readFile(path, \"utf8\")\n    const { frontmatter, body } = spec.parse(source)\n    // The frontmatter is already zod-validated by `parse` (each per-\n    // package parser runs the schema). Cast through `define` so the\n    // cross-AIP invariants run too — same path the TS authoring uses.\n    const handle = spec.define(frontmatter as unknown as TParams)\n    return { path, handle, body }\n  }\n\n  async function list(\n    dir: string,\n    opts: ListOptions = {},\n  ): Promise<THandle[]> {\n    const skip = new Set(opts.skipDirs ?? DEFAULT_SKIP_DIRS)\n    const out: THandle[] = []\n\n    async function walk(current: string): Promise<void> {\n      // The Dirent overload returns `Dirent<NonSharedBuffer>[]` in\n      // Node 22+'s @types/node when called with non-string buffer\n      // input. Coerce by typing the entries as `Dirent[]` (string\n      // names by default) since we always pass a string path.\n      let entries: Dirent[]\n      try {\n        entries = (await readdir(current, { withFileTypes: true })) as Dirent[]\n      } catch {\n        return\n      }\n      for (const entry of entries) {\n        const entryName = String(entry.name)\n        if (entry.isDirectory()) {\n          if (skip.has(entryName)) continue\n          await walk(join(current, entryName))\n          continue\n        }\n        if (!entry.isFile()) continue\n        if (entryName !== filename) continue\n        try {\n          const { handle } = await load(join(current, entryName))\n          if (!opts.filter || opts.filter(handle)) out.push(handle)\n        } catch {\n          // Malformed manifests skip the list — `load` will throw the\n          // useful diagnostic when a caller wants to see it.\n        }\n      }\n    }\n\n    await walk(dir)\n    return out\n  }\n\n  async function update(\n    path: string,\n    mutator: (\n      params: TParams,\n      ctx: { handle: THandle; body: string },\n    ) => TParams | Promise<TParams>,\n    opts: { body?: string; dryRun?: boolean } = {},\n  ): Promise<VerbResult<THandle>> {\n    const { handle, body } = await load(path)\n    // Reconstruct params from the frontmatter — the load path already\n    // validated, so this is just a reverse projection.\n    const source = await readFile(path, \"utf8\")\n    const { frontmatter } = spec.parse(source)\n    const params = frontmatter as unknown as TParams\n    const mutated = await mutator(params, { handle, body })\n    const newHandle = spec.define(mutated)\n    const newFrontmatter = toFrontmatter(mutated)\n    const rendered = matter.stringify(\n      opts.body ?? body,\n      newFrontmatter,\n    )\n    if (!opts.dryRun) {\n      await mkdir(dirname(path), { recursive: true })\n      await writeFile(path, rendered, \"utf8\")\n    }\n    return { path, handle: newHandle, rendered }\n  }\n\n  async function resolve(\n    block: RefBlock<TParams>,\n    ctx: ResolveContext = {},\n  ): Promise<THandle> {\n    if (\"inline\" in block) {\n      return spec.define(block.inline)\n    }\n    if (\"file\" in block) {\n      const baseDir = ctx.baseDir ?? \".\"\n      const path = isAbsolute(block.file) ? block.file : join(baseDir, block.file)\n      const { handle } = await load(path)\n      return handle\n    }\n    if (\"ref\" in block) {\n      if (!ctx.resolveRef) {\n        throw new Error(\n          `${spec.name}.resolve (AIP-${spec.aip}): block has \\`ref: '${block.ref}'\\` but no resolveRef provided in context — registries must inject their own resolver`,\n        )\n      }\n      const resolved = await ctx.resolveRef(block.ref)\n      return spec.define(resolved as TParams)\n    }\n    throw new Error(\n      `${spec.name}.resolve (AIP-${spec.aip}): block must have one of inline | ref | file`,\n    )\n  }\n\n  async function deleteFn(path: string): Promise<void> {\n    await rm(path, { force: true })\n  }\n\n  return { create, load, list, update, resolve, delete: deleteFn }\n}\n\nfunction defaultBody<P, H>(\n  spec: DoctypeSpec<P extends { id?: string; slug?: string; name?: string } ? P : never, H>,\n  frontmatter: Record<string, unknown>,\n): string {\n  const id =\n    typeof frontmatter.name === \"string\"\n      ? frontmatter.name\n      : typeof frontmatter.id === \"string\"\n        ? frontmatter.id\n        : typeof frontmatter.slug === \"string\"\n          ? frontmatter.slug\n          : spec.name\n  return `# ${id}\\n`\n}\n\n"]}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@agentproto/manifest",
+  "version": "0.1.0-alpha.1",
+  "description": "agentproto/manifest — generic verbs for AIP doctypes (create, load, list, update, resolve, delete). Each per-AIP package supplies a DoctypeSpec describing its name / AIP number / schema literal / path convention / validator+parser; createVerbs(spec) returns the full lifecycle. Adding a new verb (hash, sign, migrate, …) is one place; every package picks it up automatically.",
+  "keywords": [
+    "agentproto",
+    "manifest",
+    "io",
+    "verbs",
+    "createX",
+    "loadX",
+    "listX",
+    "open-standard"
+  ],
+  "homepage": "https://agentproto.sh",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts",
+    "directory": "packages/manifest"
+  },
+  "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"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "@agentproto/define-doctype": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "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"
+  }
+}