@nebutra/play-loader 0.1.0

package/README.md

@@ -0,0 +1,20 @@
+# @nebutra/play-loader
+
+Status: WIP — Not yet integrated into any production app.
+
+`@nebutra/play-loader` owns declarative Play loading, SKILL.md-compatible play
+schema parsing, dependency planning, version checks, and the seam that hands a
+validated play to the runtime.
+
+It does not own tool implementation, model/provider execution, or durable
+Thread/Turn/Item storage. Those are injected through the runtime, registry, and
+execution capability packages.
+
+## Commands
+
+```bash
+pnpm play:list
+pnpm play:new <name>
+pnpm play:test <name>
+pnpm play:debug <thread_id>
+```

package/dist/chunk-7JPGPQKB.js

@@ -0,0 +1,233 @@
+// src/index.ts
+import { mkdir, readdir, readFile, writeFile } from "fs/promises";
+import { dirname, join, relative } from "path";
+import { CapabilityError } from "@nebutra/errors";
+import { parseSkillFrontmatter, parseSkillMarkdown } from "@nebutra/tool-registry";
+async function walk(dir) {
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  const files = [];
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...await walk(full));
+    else files.push(full);
+  }
+  return files;
+}
+function asString(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function asStringArray(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function normalizePlayName(name) {
+  return name.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "_").replace(/^_+|_+$/g, "");
+}
+function playDebugPath() {
+  return join(process.cwd(), ".nebutra", "debug", "play-loader.jsonl");
+}
+async function appendPlayDebug(entry) {
+  const path = playDebugPath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), ...entry })}
+`, {
+    flag: "a"
+  });
+}
+async function readPlayDebug(limit = 10) {
+  try {
+    const raw = await readFile(playDebugPath(), "utf8");
+    return raw.trim().split("\n").filter(Boolean).slice(-limit).map((line) => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}
+function parseSubagents(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((item) => {
+    const record = asRecord(item);
+    const role = asString(record?.role);
+    if (!record || !role) return [];
+    return [{ role, allowedSkills: asStringArray(record.allowed_skills) }];
+  });
+}
+function parsePlayDependencies(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((item) => {
+    if (typeof item === "string") return [{ play: item, outputs: [] }];
+    const record = asRecord(item);
+    const play = asString(record?.play);
+    if (!record || !play) return [];
+    return [{ play, outputs: asStringArray(record.outputs) }];
+  });
+}
+function parsePlayMarkdown(markdown) {
+  const loaded = parseSkillMarkdown(markdown);
+  const { frontmatter } = parseSkillFrontmatter(markdown);
+  if (frontmatter.kind !== "play") {
+    throw new CapabilityError("play-loader", "Play SKILL.md must set kind: play", {
+      suggestion: "Set `kind: play` in frontmatter or keep this document in tool-registry only.",
+      statusCode: 400,
+      metadata: { name: loaded.meta.name, kind: frontmatter.kind }
+    });
+  }
+  return {
+    meta: { ...loaded.meta, kind: "play" },
+    body: loaded.body,
+    requiredSkills: asStringArray(frontmatter.required_skills),
+    subAgents: parseSubagents(frontmatter.sub_agents),
+    dependsOnPlays: parsePlayDependencies(frontmatter.depends_on_plays)
+  };
+}
+function resolvePlayChain(nodes) {
+  const byName = new Map(nodes.map((node) => [node.name, node]));
+  const visited = /* @__PURE__ */ new Set();
+  const visiting = /* @__PURE__ */ new Set();
+  const ordered = [];
+  const visit = (name) => {
+    if (visited.has(name)) return;
+    if (visiting.has(name)) {
+      throw new CapabilityError("play-loader", "Play dependency cycle detected", {
+        suggestion: "Remove the cycle or merge mutually dependent plays into one declaration.",
+        statusCode: 400,
+        metadata: { name }
+      });
+    }
+    visiting.add(name);
+    const node = byName.get(name);
+    for (const dependency of node?.dependsOn ?? []) visit(dependency);
+    visiting.delete(name);
+    visited.add(name);
+    ordered.push(name);
+  };
+  for (const node of nodes) visit(node.name);
+  return ordered;
+}
+var PlayLoader = class _PlayLoader {
+  #root;
+  #plays = /* @__PURE__ */ new Map();
+  constructor(root) {
+    this.#root = root;
+  }
+  static async open(root) {
+    const loader = new _PlayLoader(root);
+    await mkdir(loader.playsRoot(), { recursive: true });
+    await loader.reload();
+    return loader;
+  }
+  playsRoot() {
+    return join(this.#root, "plays");
+  }
+  async writePlay(name, markdown) {
+    const normalized = normalizePlayName(name);
+    const parsed = parsePlayMarkdown(markdown);
+    if (parsed.meta.name !== normalized) {
+      throw new CapabilityError("play-loader", "Play name does not match path", {
+        suggestion: "Use the same lowercase codename in the path and SKILL.md frontmatter.",
+        metadata: { pathName: normalized, playName: parsed.meta.name },
+        statusCode: 400
+      });
+    }
+    const path = join(this.playsRoot(), normalized, "SKILL.md");
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, markdown, "utf8");
+    await this.reload();
+    await appendPlayDebug({ type: "write", play: normalized });
+  }
+  async newPlay(name) {
+    const normalized = normalizePlayName(name);
+    const markdown = [
+      "---",
+      `name: ${normalized}`,
+      "kind: play",
+      "version: 1.0.0",
+      `description: ${normalized.replaceAll("_", " ")} play`,
+      "required_skills: []",
+      "sub_agents: []",
+      "depends_on_plays: []",
+      "---",
+      "",
+      "## What this play does",
+      "",
+      "Describe the user story and expected output."
+    ].join("\n");
+    await this.writePlay(normalized, markdown);
+    return this.load(normalized);
+  }
+  async reload() {
+    this.#plays.clear();
+    for (const file of await walk(this.playsRoot())) {
+      if (!file.endsWith("SKILL.md")) continue;
+      const raw = await readFile(file, "utf8");
+      const play = parsePlayMarkdown(raw);
+      this.#plays.set(play.meta.name, { meta: play.meta, path: relative(this.#root, file) });
+    }
+    await appendPlayDebug({ type: "reload", plays: this.#plays.size });
+  }
+  async list() {
+    return [...this.#plays.values()].map((entry) => entry.meta).sort((left, right) => left.name.localeCompare(right.name));
+  }
+  async load(name) {
+    const play = this.#plays.get(normalizePlayName(name));
+    if (!play) {
+      throw new CapabilityError("play-loader", "Play not found", {
+        suggestion: "Run `pnpm play:list` or create it with `pnpm play:new <name>`.",
+        metadata: { name },
+        statusCode: 404
+      });
+    }
+    const loaded = parsePlayMarkdown(await readFile(join(this.#root, play.path), "utf8"));
+    await appendPlayDebug({ type: "load", play: loaded.meta.name });
+    return loaded;
+  }
+  async install(source) {
+    if (!source.startsWith("file:")) {
+      throw new CapabilityError("play-loader", "Only file installs are enabled locally", {
+        suggestion: "Download remote plays through a reviewed distribution workflow, then install with file:<path>.",
+        metadata: { source },
+        statusCode: 400
+      });
+    }
+    const raw = await readFile(source.slice("file:".length), "utf8");
+    const play = parsePlayMarkdown(raw);
+    await this.writePlay(play.meta.name, raw);
+    return this.load(play.meta.name);
+  }
+  async test(name) {
+    try {
+      const play = await this.load(name);
+      return {
+        name: play.meta.name,
+        ok: play.body.length > 0,
+        checks: ["frontmatter", "kind:play", "body", "dependency-dag"],
+        ...!play.body ? { suggestion: "Add a markdown body after the frontmatter." } : {}
+      };
+    } catch (error) {
+      return {
+        name,
+        ok: false,
+        checks: [],
+        suggestion: error instanceof CapabilityError ? "Create the play with `pnpm play:new <name>` or fix its SKILL.md metadata." : "Run `pnpm play:list` and verify the play directory exists."
+      };
+    }
+  }
+  async doctor() {
+    const plays = this.#plays.size;
+    return {
+      ok: plays > 0,
+      plays,
+      root: this.#root,
+      ...plays === 0 ? { suggestion: "Create a play with `pnpm play:new <name>`." } : {}
+    };
+  }
+};
+
+export {
+  readPlayDebug,
+  parsePlayMarkdown,
+  resolvePlayChain,
+  PlayLoader
+};
+//# sourceMappingURL=chunk-7JPGPQKB.js.map

package/dist/chunk-7JPGPQKB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { mkdir, readdir, readFile, writeFile } from \"node:fs/promises\";\nimport { dirname, join, relative } from \"node:path\";\nimport { CapabilityError } from \"@nebutra/errors\";\nimport { parseSkillFrontmatter, parseSkillMarkdown, type SkillMeta } from \"@nebutra/tool-registry\";\n\nexport interface PlayDependency {\n  readonly play: string;\n  readonly outputs: readonly string[];\n}\n\nexport interface PlaySubagent {\n  readonly role: string;\n  readonly allowedSkills: readonly string[];\n}\n\nexport interface PlayMeta extends SkillMeta {\n  readonly kind: \"play\";\n}\n\nexport interface LoadedPlay {\n  readonly meta: PlayMeta;\n  readonly body: string;\n  readonly requiredSkills: readonly string[];\n  readonly subAgents: readonly PlaySubagent[];\n  readonly dependsOnPlays: readonly PlayDependency[];\n}\n\nexport interface PlayNode {\n  readonly name: string;\n  readonly dependsOn: readonly string[];\n}\n\nexport interface PlayTestReport {\n  readonly name: string;\n  readonly ok: boolean;\n  readonly checks: readonly string[];\n  readonly suggestion?: string;\n}\n\nexport interface PlayLoaderDoctorReport {\n  readonly ok: boolean;\n  readonly plays: number;\n  readonly root: string;\n  readonly suggestion?: string;\n}\n\nasync function walk(dir: string): Promise<string[]> {\n  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);\n  const files: string[] = [];\n  for (const entry of entries) {\n    const full = join(dir, entry.name);\n    if (entry.isDirectory()) files.push(...(await walk(full)));\n    else files.push(full);\n  }\n  return files;\n}\n\nfunction asString(value: unknown): string | undefined {\n  return typeof value === \"string\" ? value : undefined;\n}\n\nfunction asStringArray(value: unknown): string[] {\n  return Array.isArray(value)\n    ? value.filter((item): item is string => typeof item === \"string\")\n    : [];\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | undefined {\n  return value && typeof value === \"object\" && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined;\n}\n\nfunction normalizePlayName(name: string): string {\n  return name\n    .trim()\n    .toLowerCase()\n    .replace(/[^a-z0-9_-]+/g, \"_\")\n    .replace(/^_+|_+$/g, \"\");\n}\n\nfunction playDebugPath(): string {\n  return join(process.cwd(), \".nebutra\", \"debug\", \"play-loader.jsonl\");\n}\n\nasync function appendPlayDebug(entry: Record<string, unknown>): Promise<void> {\n  const path = playDebugPath();\n  await mkdir(dirname(path), { recursive: true });\n  await writeFile(path, `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\\n`, {\n    flag: \"a\",\n  });\n}\n\nexport async function readPlayDebug(limit = 10): Promise<unknown[]> {\n  try {\n    const raw = await readFile(playDebugPath(), \"utf8\");\n    return raw\n      .trim()\n      .split(\"\\n\")\n      .filter(Boolean)\n      .slice(-limit)\n      .map((line) => JSON.parse(line) as unknown);\n  } catch {\n    return [];\n  }\n}\n\nfunction parseSubagents(value: unknown): PlaySubagent[] {\n  if (!Array.isArray(value)) return [];\n  return value.flatMap((item): PlaySubagent[] => {\n    const record = asRecord(item);\n    const role = asString(record?.role);\n    if (!record || !role) return [];\n    return [{ role, allowedSkills: asStringArray(record.allowed_skills) }];\n  });\n}\n\nfunction parsePlayDependencies(value: unknown): PlayDependency[] {\n  if (!Array.isArray(value)) return [];\n  return value.flatMap((item): PlayDependency[] => {\n    if (typeof item === \"string\") return [{ play: item, outputs: [] }];\n    const record = asRecord(item);\n    const play = asString(record?.play);\n    if (!record || !play) return [];\n    return [{ play, outputs: asStringArray(record.outputs) }];\n  });\n}\n\nexport function parsePlayMarkdown(markdown: string): LoadedPlay {\n  const loaded = parseSkillMarkdown(markdown);\n  const { frontmatter } = parseSkillFrontmatter(markdown);\n  if (frontmatter.kind !== \"play\") {\n    throw new CapabilityError(\"play-loader\", \"Play SKILL.md must set kind: play\", {\n      suggestion: \"Set `kind: play` in frontmatter or keep this document in tool-registry only.\",\n      statusCode: 400,\n      metadata: { name: loaded.meta.name, kind: frontmatter.kind },\n    });\n  }\n\n  return {\n    meta: { ...loaded.meta, kind: \"play\" },\n    body: loaded.body,\n    requiredSkills: asStringArray(frontmatter.required_skills),\n    subAgents: parseSubagents(frontmatter.sub_agents),\n    dependsOnPlays: parsePlayDependencies(frontmatter.depends_on_plays),\n  };\n}\n\nexport function resolvePlayChain(nodes: readonly PlayNode[]): readonly string[] {\n  const byName = new Map(nodes.map((node) => [node.name, node]));\n  const visited = new Set<string>();\n  const visiting = new Set<string>();\n  const ordered: string[] = [];\n\n  const visit = (name: string): void => {\n    if (visited.has(name)) return;\n    if (visiting.has(name)) {\n      throw new CapabilityError(\"play-loader\", \"Play dependency cycle detected\", {\n        suggestion: \"Remove the cycle or merge mutually dependent plays into one declaration.\",\n        statusCode: 400,\n        metadata: { name },\n      });\n    }\n    visiting.add(name);\n    const node = byName.get(name);\n    for (const dependency of node?.dependsOn ?? []) visit(dependency);\n    visiting.delete(name);\n    visited.add(name);\n    ordered.push(name);\n  };\n\n  for (const node of nodes) visit(node.name);\n  return ordered;\n}\n\nexport class PlayLoader {\n  readonly #root: string;\n  readonly #plays = new Map<string, { readonly meta: PlayMeta; readonly path: string }>();\n\n  private constructor(root: string) {\n    this.#root = root;\n  }\n\n  static async open(root: string): Promise<PlayLoader> {\n    const loader = new PlayLoader(root);\n    await mkdir(loader.playsRoot(), { recursive: true });\n    await loader.reload();\n    return loader;\n  }\n\n  playsRoot(): string {\n    return join(this.#root, \"plays\");\n  }\n\n  async writePlay(name: string, markdown: string): Promise<void> {\n    const normalized = normalizePlayName(name);\n    const parsed = parsePlayMarkdown(markdown);\n    if (parsed.meta.name !== normalized) {\n      throw new CapabilityError(\"play-loader\", \"Play name does not match path\", {\n        suggestion: \"Use the same lowercase codename in the path and SKILL.md frontmatter.\",\n        metadata: { pathName: normalized, playName: parsed.meta.name },\n        statusCode: 400,\n      });\n    }\n    const path = join(this.playsRoot(), normalized, \"SKILL.md\");\n    await mkdir(dirname(path), { recursive: true });\n    await writeFile(path, markdown, \"utf8\");\n    await this.reload();\n    await appendPlayDebug({ type: \"write\", play: normalized });\n  }\n\n  async newPlay(name: string): Promise<LoadedPlay> {\n    const normalized = normalizePlayName(name);\n    const markdown = [\n      \"---\",\n      `name: ${normalized}`,\n      \"kind: play\",\n      \"version: 1.0.0\",\n      `description: ${normalized.replaceAll(\"_\", \" \")} play`,\n      \"required_skills: []\",\n      \"sub_agents: []\",\n      \"depends_on_plays: []\",\n      \"---\",\n      \"\",\n      \"## What this play does\",\n      \"\",\n      \"Describe the user story and expected output.\",\n    ].join(\"\\n\");\n    await this.writePlay(normalized, markdown);\n    return this.load(normalized);\n  }\n\n  async reload(): Promise<void> {\n    this.#plays.clear();\n    for (const file of await walk(this.playsRoot())) {\n      if (!file.endsWith(\"SKILL.md\")) continue;\n      const raw = await readFile(file, \"utf8\");\n      const play = parsePlayMarkdown(raw);\n      this.#plays.set(play.meta.name, { meta: play.meta, path: relative(this.#root, file) });\n    }\n    await appendPlayDebug({ type: \"reload\", plays: this.#plays.size });\n  }\n\n  async list(): Promise<PlayMeta[]> {\n    return [...this.#plays.values()]\n      .map((entry) => entry.meta)\n      .sort((left, right) => left.name.localeCompare(right.name));\n  }\n\n  async load(name: string): Promise<LoadedPlay> {\n    const play = this.#plays.get(normalizePlayName(name));\n    if (!play) {\n      throw new CapabilityError(\"play-loader\", \"Play not found\", {\n        suggestion: \"Run `pnpm play:list` or create it with `pnpm play:new <name>`.\",\n        metadata: { name },\n        statusCode: 404,\n      });\n    }\n    const loaded = parsePlayMarkdown(await readFile(join(this.#root, play.path), \"utf8\"));\n    await appendPlayDebug({ type: \"load\", play: loaded.meta.name });\n    return loaded;\n  }\n\n  async install(source: string): Promise<LoadedPlay> {\n    if (!source.startsWith(\"file:\")) {\n      throw new CapabilityError(\"play-loader\", \"Only file installs are enabled locally\", {\n        suggestion:\n          \"Download remote plays through a reviewed distribution workflow, then install with file:<path>.\",\n        metadata: { source },\n        statusCode: 400,\n      });\n    }\n    const raw = await readFile(source.slice(\"file:\".length), \"utf8\");\n    const play = parsePlayMarkdown(raw);\n    await this.writePlay(play.meta.name, raw);\n    return this.load(play.meta.name);\n  }\n\n  async test(name: string): Promise<PlayTestReport> {\n    try {\n      const play = await this.load(name);\n      return {\n        name: play.meta.name,\n        ok: play.body.length > 0,\n        checks: [\"frontmatter\", \"kind:play\", \"body\", \"dependency-dag\"],\n        ...(!play.body ? { suggestion: \"Add a markdown body after the frontmatter.\" } : {}),\n      };\n    } catch (error) {\n      return {\n        name,\n        ok: false,\n        checks: [],\n        suggestion:\n          error instanceof CapabilityError\n            ? \"Create the play with `pnpm play:new <name>` or fix its SKILL.md metadata.\"\n            : \"Run `pnpm play:list` and verify the play directory exists.\",\n      };\n    }\n  }\n\n  async doctor(): Promise<PlayLoaderDoctorReport> {\n    const plays = this.#plays.size;\n    return {\n      ok: plays > 0,\n      plays,\n      root: this.#root,\n      ...(plays === 0 ? { suggestion: \"Create a play with `pnpm play:new <name>`.\" } : {}),\n    };\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/cli.js

@@ -0,0 +1,71 @@
+import {
+  PlayLoader,
+  parsePlayMarkdown,
+  readPlayDebug,
+  resolvePlayChain
+} from "./chunk-7JPGPQKB.js";
+
+// src/cli.ts
+import { readFile } from "fs/promises";
+var command = process.argv[2] ?? "list";
+var root = process.env.PLAY_LOADER_ROOT ?? ".nebutra";
+if (command === "parse") {
+  const file = process.argv[3];
+  if (!file) throw new Error("Missing play file path");
+  const play = parsePlayMarkdown(await readFile(file, "utf8"));
+  process.stdout.write(`${JSON.stringify({ capability: "play-loader", play }, null, 2)}
+`);
+} else if (command === "chain") {
+  const raw = process.argv[3] ?? "[]";
+  const nodes = JSON.parse(raw);
+  process.stdout.write(
+    `${JSON.stringify({ capability: "play-loader", order: resolvePlayChain(nodes) }, null, 2)}
+`
+  );
+} else if (command === "list") {
+  const loader = await PlayLoader.open(root);
+  process.stdout.write(
+    `${JSON.stringify({ capability: "play-loader", plays: await loader.list() }, null, 2)}
+`
+  );
+} else if (command === "new") {
+  const name = process.argv[3];
+  if (!name) throw new Error("Missing play name");
+  const loader = await PlayLoader.open(root);
+  process.stdout.write(
+    `${JSON.stringify({ capability: "play-loader", play: await loader.newPlay(name) }, null, 2)}
+`
+  );
+} else if (command === "test") {
+  const name = process.argv[3];
+  if (!name) throw new Error("Missing play name");
+  const loader = await PlayLoader.open(root);
+  process.stdout.write(
+    `${JSON.stringify({ capability: "play-loader", report: await loader.test(name) }, null, 2)}
+`
+  );
+} else if (command === "install") {
+  const source = process.argv[3];
+  if (!source) throw new Error("Missing play source");
+  const loader = await PlayLoader.open(root);
+  process.stdout.write(
+    `${JSON.stringify({ capability: "play-loader", play: await loader.install(source) }, null, 2)}
+`
+  );
+} else if (command === "doctor") {
+  const loader = await PlayLoader.open(root);
+  process.stdout.write(
+    `${JSON.stringify({ capability: "play-loader", ...await loader.doctor() }, null, 2)}
+`
+  );
+} else if (command === "debug") {
+  process.stdout.write(
+    `${JSON.stringify({ capability: "play-loader", entries: await readPlayDebug() }, null, 2)}
+`
+  );
+} else {
+  process.stderr.write(`Unknown play-loader command: ${command}
+`);
+  process.exitCode = 1;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { PlayLoader, parsePlayMarkdown, readPlayDebug, resolvePlayChain } from \"./index\";\n\nconst command = process.argv[2] ?? \"list\";\nconst root = process.env.PLAY_LOADER_ROOT ?? \".nebutra\";\n\nif (command === \"parse\") {\n  const file = process.argv[3];\n  if (!file) throw new Error(\"Missing play file path\");\n  const play = parsePlayMarkdown(await readFile(file, \"utf8\"));\n  process.stdout.write(`${JSON.stringify({ capability: \"play-loader\", play }, null, 2)}\\n`);\n} else if (command === \"chain\") {\n  const raw = process.argv[3] ?? \"[]\";\n  const nodes = JSON.parse(raw) as Array<{ name: string; dependsOn: string[] }>;\n  process.stdout.write(\n    `${JSON.stringify({ capability: \"play-loader\", order: resolvePlayChain(nodes) }, null, 2)}\\n`,\n  );\n} else if (command === \"list\") {\n  const loader = await PlayLoader.open(root);\n  process.stdout.write(\n    `${JSON.stringify({ capability: \"play-loader\", plays: await loader.list() }, null, 2)}\\n`,\n  );\n} else if (command === \"new\") {\n  const name = process.argv[3];\n  if (!name) throw new Error(\"Missing play name\");\n  const loader = await PlayLoader.open(root);\n  process.stdout.write(\n    `${JSON.stringify({ capability: \"play-loader\", play: await loader.newPlay(name) }, null, 2)}\\n`,\n  );\n} else if (command === \"test\") {\n  const name = process.argv[3];\n  if (!name) throw new Error(\"Missing play name\");\n  const loader = await PlayLoader.open(root);\n  process.stdout.write(\n    `${JSON.stringify({ capability: \"play-loader\", report: await loader.test(name) }, null, 2)}\\n`,\n  );\n} else if (command === \"install\") {\n  const source = process.argv[3];\n  if (!source) throw new Error(\"Missing play source\");\n  const loader = await PlayLoader.open(root);\n  process.stdout.write(\n    `${JSON.stringify({ capability: \"play-loader\", play: await loader.install(source) }, null, 2)}\\n`,\n  );\n} else if (command === \"doctor\") {\n  const loader = await PlayLoader.open(root);\n  process.stdout.write(\n    `${JSON.stringify({ capability: \"play-loader\", ...(await loader.doctor()) }, null, 2)}\\n`,\n  );\n} else if (command === \"debug\") {\n  process.stdout.write(\n    `${JSON.stringify({ capability: \"play-loader\", entries: await readPlayDebug() }, null, 2)}\\n`,\n  );\n} else {\n  process.stderr.write(`Unknown play-loader command: ${command}\\n`);\n  process.exitCode = 1;\n}\n"],"mappings":";;;;;;;;AAAA,SAAS,gBAAgB;AAGzB,IAAM,UAAU,QAAQ,KAAK,CAAC,KAAK;AACnC,IAAM,OAAO,QAAQ,IAAI,oBAAoB;AAE7C,IAAI,YAAY,SAAS;AACvB,QAAM,OAAO,QAAQ,KAAK,CAAC;AAC3B,MAAI,CAAC,KAAM,OAAM,IAAI,MAAM,wBAAwB;AACnD,QAAM,OAAO,kBAAkB,MAAM,SAAS,MAAM,MAAM,CAAC;AAC3D,UAAQ,OAAO,MAAM,GAAG,KAAK,UAAU,EAAE,YAAY,eAAe,KAAK,GAAG,MAAM,CAAC,CAAC;AAAA,CAAI;AAC1F,WAAW,YAAY,SAAS;AAC9B,QAAM,MAAM,QAAQ,KAAK,CAAC,KAAK;AAC/B,QAAM,QAAQ,KAAK,MAAM,GAAG;AAC5B,UAAQ,OAAO;AAAA,IACb,GAAG,KAAK,UAAU,EAAE,YAAY,eAAe,OAAO,iBAAiB,KAAK,EAAE,GAAG,MAAM,CAAC,CAAC;AAAA;AAAA,EAC3F;AACF,WAAW,YAAY,QAAQ;AAC7B,QAAM,SAAS,MAAM,WAAW,KAAK,IAAI;AACzC,UAAQ,OAAO;AAAA,IACb,GAAG,KAAK,UAAU,EAAE,YAAY,eAAe,OAAO,MAAM,OAAO,KAAK,EAAE,GAAG,MAAM,CAAC,CAAC;AAAA;AAAA,EACvF;AACF,WAAW,YAAY,OAAO;AAC5B,QAAM,OAAO,QAAQ,KAAK,CAAC;AAC3B,MAAI,CAAC,KAAM,OAAM,IAAI,MAAM,mBAAmB;AAC9C,QAAM,SAAS,MAAM,WAAW,KAAK,IAAI;AACzC,UAAQ,OAAO;AAAA,IACb,GAAG,KAAK,UAAU,EAAE,YAAY,eAAe,MAAM,MAAM,OAAO,QAAQ,IAAI,EAAE,GAAG,MAAM,CAAC,CAAC;AAAA;AAAA,EAC7F;AACF,WAAW,YAAY,QAAQ;AAC7B,QAAM,OAAO,QAAQ,KAAK,CAAC;AAC3B,MAAI,CAAC,KAAM,OAAM,IAAI,MAAM,mBAAmB;AAC9C,QAAM,SAAS,MAAM,WAAW,KAAK,IAAI;AACzC,UAAQ,OAAO;AAAA,IACb,GAAG,KAAK,UAAU,EAAE,YAAY,eAAe,QAAQ,MAAM,OAAO,KAAK,IAAI,EAAE,GAAG,MAAM,CAAC,CAAC;AAAA;AAAA,EAC5F;AACF,WAAW,YAAY,WAAW;AAChC,QAAM,SAAS,QAAQ,KAAK,CAAC;AAC7B,MAAI,CAAC,OAAQ,OAAM,IAAI,MAAM,qBAAqB;AAClD,QAAM,SAAS,MAAM,WAAW,KAAK,IAAI;AACzC,UAAQ,OAAO;AAAA,IACb,GAAG,KAAK,UAAU,EAAE,YAAY,eAAe,MAAM,MAAM,OAAO,QAAQ,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC;AAAA;AAAA,EAC/F;AACF,WAAW,YAAY,UAAU;AAC/B,QAAM,SAAS,MAAM,WAAW,KAAK,IAAI;AACzC,UAAQ,OAAO;AAAA,IACb,GAAG,KAAK,UAAU,EAAE,YAAY,eAAe,GAAI,MAAM,OAAO,OAAO,EAAG,GAAG,MAAM,CAAC,CAAC;AAAA;AAAA,EACvF;AACF,WAAW,YAAY,SAAS;AAC9B,UAAQ,OAAO;AAAA,IACb,GAAG,KAAK,UAAU,EAAE,YAAY,eAAe,SAAS,MAAM,cAAc,EAAE,GAAG,MAAM,CAAC,CAAC;AAAA;AAAA,EAC3F;AACF,OAAO;AACL,UAAQ,OAAO,MAAM,gCAAgC,OAAO;AAAA,CAAI;AAChE,UAAQ,WAAW;AACrB;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { SkillMeta } from '@nebutra/tool-registry';
+
+interface PlayDependency {
+    readonly play: string;
+    readonly outputs: readonly string[];
+}
+interface PlaySubagent {
+    readonly role: string;
+    readonly allowedSkills: readonly string[];
+}
+interface PlayMeta extends SkillMeta {
+    readonly kind: "play";
+}
+interface LoadedPlay {
+    readonly meta: PlayMeta;
+    readonly body: string;
+    readonly requiredSkills: readonly string[];
+    readonly subAgents: readonly PlaySubagent[];
+    readonly dependsOnPlays: readonly PlayDependency[];
+}
+interface PlayNode {
+    readonly name: string;
+    readonly dependsOn: readonly string[];
+}
+interface PlayTestReport {
+    readonly name: string;
+    readonly ok: boolean;
+    readonly checks: readonly string[];
+    readonly suggestion?: string;
+}
+interface PlayLoaderDoctorReport {
+    readonly ok: boolean;
+    readonly plays: number;
+    readonly root: string;
+    readonly suggestion?: string;
+}
+declare function readPlayDebug(limit?: number): Promise<unknown[]>;
+declare function parsePlayMarkdown(markdown: string): LoadedPlay;
+declare function resolvePlayChain(nodes: readonly PlayNode[]): readonly string[];
+declare class PlayLoader {
+    #private;
+    private constructor();
+    static open(root: string): Promise<PlayLoader>;
+    playsRoot(): string;
+    writePlay(name: string, markdown: string): Promise<void>;
+    newPlay(name: string): Promise<LoadedPlay>;
+    reload(): Promise<void>;
+    list(): Promise<PlayMeta[]>;
+    load(name: string): Promise<LoadedPlay>;
+    install(source: string): Promise<LoadedPlay>;
+    test(name: string): Promise<PlayTestReport>;
+    doctor(): Promise<PlayLoaderDoctorReport>;
+}
+
+export { type LoadedPlay, type PlayDependency, PlayLoader, type PlayLoaderDoctorReport, type PlayMeta, type PlayNode, type PlaySubagent, type PlayTestReport, parsePlayMarkdown, readPlayDebug, resolvePlayChain };

package/dist/index.js

@@ -0,0 +1,13 @@
+import {
+  PlayLoader,
+  parsePlayMarkdown,
+  readPlayDebug,
+  resolvePlayChain
+} from "./chunk-7JPGPQKB.js";
+export {
+  PlayLoader,
+  parsePlayMarkdown,
+  readPlayDebug,
+  resolvePlayChain
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/examples/chain-plays.ts

@@ -0,0 +1,11 @@
+import { resolvePlayChain } from "../src";
+
+process.stdout.write(
+  `${JSON.stringify(
+    resolvePlayChain([
+      { name: "pitch", dependsOn: ["brand", "demo"] },
+      { name: "brand", dependsOn: [] },
+      { name: "demo", dependsOn: ["brand"] },
+    ]),
+  )}\n`,
+);

package/examples/local-registry.ts

@@ -0,0 +1,14 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PlayLoader } from "../src";
+
+const root = await mkdtemp(join(tmpdir(), "play-loader-"));
+try {
+  const loader = await PlayLoader.open(root);
+  await loader.newPlay("demo_play");
+  process.stdout.write(`${JSON.stringify(await loader.list())}\n`);
+  process.stdout.write(`${JSON.stringify(await loader.test("demo_play"))}\n`);
+} finally {
+  await rm(root, { recursive: true, force: true });
+}

package/examples/parse-play.ts

@@ -0,0 +1,18 @@
+import { parsePlayMarkdown } from "../src";
+
+const play = parsePlayMarkdown(`---
+name: launch_page
+kind: play
+version: 1.0.0
+description: Build a launch page
+required_skills: [content_store.write]
+sub_agents: []
+depends_on_plays: []
+---
+
+## What this play does
+
+Create a page from a concise brief.
+`);
+
+process.stdout.write(`${JSON.stringify({ name: play.meta.name, skills: play.requiredSkills })}\n`);

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@nebutra/play-loader",
+  "version": "0.1.0",
+  "description": "Declarative SKILL.md play loader and dependency planner",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "nebutra": {
+    "status": "wip",
+    "productionReady": false,
+    "requires": [
+      "@nebutra/tool-registry for SKILL.md parsing",
+      "@nebutra/agent-runtime for execution"
+    ],
+    "gaps": [
+      "Runtime runner delegates are interface-only",
+      "Remote install and migration APIs are not production-backed"
+    ],
+    "featureId": "play-loader",
+    "category": "ai",
+    "summary": "SKILL.md play parser, dependency-chain planner, and agent-runtime runner seam"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@nebutra/errors": "0.1.0",
+    "@nebutra/tool-registry": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.4"
+  },
+  "homepage": "https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/ai/play-loader#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nebutra/Nebutra-Sailor.git",
+    "directory": "packages/ai/play-loader"
+  },
+  "bugs": {
+    "url": "https://github.com/Nebutra/Nebutra-Sailor/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,56 @@
+import { readFile } from "node:fs/promises";
+import { PlayLoader, parsePlayMarkdown, readPlayDebug, resolvePlayChain } from "./index";
+
+const command = process.argv[2] ?? "list";
+const root = process.env.PLAY_LOADER_ROOT ?? ".nebutra";
+
+if (command === "parse") {
+  const file = process.argv[3];
+  if (!file) throw new Error("Missing play file path");
+  const play = parsePlayMarkdown(await readFile(file, "utf8"));
+  process.stdout.write(`${JSON.stringify({ capability: "play-loader", play }, null, 2)}\n`);
+} else if (command === "chain") {
+  const raw = process.argv[3] ?? "[]";
+  const nodes = JSON.parse(raw) as Array<{ name: string; dependsOn: string[] }>;
+  process.stdout.write(
+    `${JSON.stringify({ capability: "play-loader", order: resolvePlayChain(nodes) }, null, 2)}\n`,
+  );
+} else if (command === "list") {
+  const loader = await PlayLoader.open(root);
+  process.stdout.write(
+    `${JSON.stringify({ capability: "play-loader", plays: await loader.list() }, null, 2)}\n`,
+  );
+} else if (command === "new") {
+  const name = process.argv[3];
+  if (!name) throw new Error("Missing play name");
+  const loader = await PlayLoader.open(root);
+  process.stdout.write(
+    `${JSON.stringify({ capability: "play-loader", play: await loader.newPlay(name) }, null, 2)}\n`,
+  );
+} else if (command === "test") {
+  const name = process.argv[3];
+  if (!name) throw new Error("Missing play name");
+  const loader = await PlayLoader.open(root);
+  process.stdout.write(
+    `${JSON.stringify({ capability: "play-loader", report: await loader.test(name) }, null, 2)}\n`,
+  );
+} else if (command === "install") {
+  const source = process.argv[3];
+  if (!source) throw new Error("Missing play source");
+  const loader = await PlayLoader.open(root);
+  process.stdout.write(
+    `${JSON.stringify({ capability: "play-loader", play: await loader.install(source) }, null, 2)}\n`,
+  );
+} else if (command === "doctor") {
+  const loader = await PlayLoader.open(root);
+  process.stdout.write(
+    `${JSON.stringify({ capability: "play-loader", ...(await loader.doctor()) }, null, 2)}\n`,
+  );
+} else if (command === "debug") {
+  process.stdout.write(
+    `${JSON.stringify({ capability: "play-loader", entries: await readPlayDebug() }, null, 2)}\n`,
+  );
+} else {
+  process.stderr.write(`Unknown play-loader command: ${command}\n`);
+  process.exitCode = 1;
+}