@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-actors/skills/actors/scripts/validate-recipe.mjs

@@ -0,0 +1,370 @@
+#!/usr/bin/env node
+
+/**
+ * Template recipe validator CLI.
+ *
+ * Owns CLI parsing and report formatting directly. Recipe parsing remains in
+ * the reusable recipe-reference domain.
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+function packageRoot() {
+  return dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))));
+}
+
+async function importRuntimeModule(name) {
+  const root = packageRoot();
+  const localCompiled = join(root, "lib", `${name}.js`);
+  const installedCompiled = join(root, "dist", "lib", `${name}.js`);
+  const source = join(root, "lib", `${name}.ts`);
+  const module = existsSync(localCompiled)
+    ? localCompiled
+    : root.includes(`${sep}node_modules${sep}`) && existsSync(installedCompiled)
+      ? installedCompiled
+      : source;
+  return await import(pathToFileURL(module).href);
+}
+
+const {
+  createActiveSkillRecipeContext,
+  readRawRecipeConfig,
+  readResolvedRecipeConfig,
+} = await importRuntimeModule("recipes-references");
+
+const skillsDir = join(packageRoot(), "skills");
+const packageSkillContext = createActiveSkillRecipeContext(
+  existsSync(skillsDir)
+    ? readdirSync(skillsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => ({
+          name: entry.name,
+          baseDir: join(skillsDir, entry.name),
+        }))
+    : [],
+);
+
+export function validateRecipeUsage() {
+  return `Usage:
+  validate-recipe.mjs <recipe-file-or-dir> [--all] [--skills] [--qa] [--summary]
+
+Validates one template Recipe file or all direct *.json/*.md files in a directory with --all. Use --skills on a Skills root to validate every direct <skill>/recipes component and reject nested files or duplicate stems. Add --qa for shipped-component capability checks, where diagnostics and warnings fail validation. Add --summary for compact CLI output.`;
+}
+
+function expandPath(value) {
+  return resolve(String(value).replace(/^~(?=\/|$)/, process.env.HOME ?? homedir()));
+}
+
+function templateKind(template) {
+  if (typeof template === "string") return "leaf";
+  if (Array.isArray(template)) return "sequence";
+  if (template && typeof template === "object") {
+    const node = template;
+    if (typeof node.template === "string") return "leaf";
+    if (Array.isArray(node.template))
+      return node.parallel === true ? "parallel" : "sequence";
+    if (node.parallel === true) return "parallel";
+    return "object";
+  }
+  return "unknown";
+}
+
+function recipeFiles(target, all) {
+  if (!existsSync(target)) throw new Error(`Recipe path not found: ${target}`);
+  const stat = statSync(target);
+  if (stat.isFile()) return [target];
+  if (!stat.isDirectory())
+    throw new Error(`Recipe path is not a file or directory: ${target}`);
+  if (!all) throw new Error("Directory validation requires --all.");
+  return readdirSync(target)
+    .filter((file) => file.endsWith(".json") || file.endsWith(".md"))
+    .sort((a, b) => a.localeCompare(b))
+    .map((file) => resolve(target, file));
+}
+
+function nestedRecipeFiles(root) {
+  return readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) return nestedRecipeFiles(path);
+    return entry.isFile() && /\.(?:json|md)$/.test(entry.name) ? [path] : [];
+  });
+}
+
+function scanSkillRecipes(target) {
+  if (!existsSync(target) || !statSync(target).isDirectory())
+    throw new Error(`Skills root is not a directory: ${target}`);
+  const skills = readdirSync(target, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .sort((a, b) => a.name.localeCompare(b.name));
+  const files = [];
+  const failures = [];
+  for (const skill of skills) {
+    const recipeDir = join(target, skill.name, "recipes");
+    if (!existsSync(recipeDir)) continue;
+    const direct = readdirSync(recipeDir, { withFileTypes: true });
+    const byStem = new Map();
+    const singletonFiles = [];
+    for (const entry of direct) {
+      const path = join(recipeDir, entry.name);
+      if (entry.isDirectory()) {
+        for (const nested of nestedRecipeFiles(path)) {
+          failures.push({
+            file: nested,
+            ok: false,
+            error: `Nested Skill Recipe files are not allowed: ${relative(recipeDir, nested)}`,
+          });
+        }
+        continue;
+      }
+      if (!entry.isFile() || !/\.(?:json|md)$/.test(entry.name)) continue;
+      files.push(path);
+      if (readRawRecipeConfig(path)?.singleton === true) singletonFiles.push(path);
+      const stem = basename(entry.name, extname(entry.name));
+      const previous = byStem.get(stem);
+      if (previous) {
+        failures.push({
+          file: path,
+          ok: false,
+          error: `Skill Recipe stem collision: ${skill.name}/${stem} has both ${extname(previous)} and ${extname(path)} files`,
+        });
+      } else byStem.set(stem, path);
+    }
+    if (singletonFiles.length > 1) {
+      failures.push({
+        file: recipeDir,
+        ok: false,
+        error: `Skill ${skill.name} declares more than one singleton Recipe: ${singletonFiles.map((file) => basename(file)).join(", ")}`,
+      });
+    }
+  }
+  let skillContext = packageSkillContext;
+  try {
+    skillContext = createActiveSkillRecipeContext(
+      skills.map((entry) => ({ name: entry.name, baseDir: join(target, entry.name) })),
+    );
+  } catch (error) {
+    failures.push({
+      file: target,
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+  return {
+    files: files.sort((a, b) => a.localeCompare(b)),
+    failures,
+    skillContext,
+  };
+}
+
+function collectStrings(value, out = []) {
+  if (typeof value === "string") out.push(value);
+  else if (Array.isArray(value)) value.forEach((item) => collectStrings(item, out));
+  else if (value && typeof value === "object")
+    Object.values(value).forEach((item) => collectStrings(item, out));
+  return out;
+}
+
+function collectTemplateStrings(value, out = []) {
+  if (typeof value === "string") out.push(value);
+  else if (Array.isArray(value)) value.forEach((item) => collectTemplateStrings(item, out));
+  else if (value && typeof value === "object") {
+    collectTemplateStrings(value.template, out);
+    collectTemplateStrings(value.recover, out);
+  }
+  return out;
+}
+
+function hasPlatformNote(config) {
+  const text = [
+    config.description,
+    config.platforms,
+    config.platform_notes,
+    config.requirements,
+  ]
+    .filter(Boolean)
+    .join(" ");
+  return /linux|macos|darwin|windows|win32|unix|wsl|cross-platform|portable/i.test(text);
+}
+
+function validateArtifactDeclarations(config) {
+  const diagnostics = [];
+  const artifacts = config.artifacts;
+  if (artifacts === undefined) return diagnostics;
+  if (!artifacts || typeof artifacts !== "object" || Array.isArray(artifacts)) {
+    diagnostics.push("artifacts: must be an object of named artifact paths");
+    return diagnostics;
+  }
+  for (const [name, value] of Object.entries(artifacts)) {
+    const path = typeof value === "string" ? value : value?.path;
+    if (typeof path !== "string" || !path.trim())
+      diagnostics.push(`artifacts.${name}: must declare a non-empty path`);
+    if (typeof path === "string" && /^\/home\//.test(path))
+      diagnostics.push(`artifacts.${name}: must not use a machine-local absolute path`);
+  }
+  return diagnostics;
+}
+
+function validateHelperPaths(file, config) {
+  const diagnostics = [];
+  const skillDir = dirname(dirname(file));
+  for (const template of collectTemplateStrings(config.template)) {
+    if (/(^|\s)(?:node\s+)?scripts\/[\w.-]+\.mjs/.test(template))
+      diagnostics.push("template: Skill helper scripts must be referenced through {skill_dir}/scripts");
+    for (const match of template.matchAll(/\{skill_dir\}\/([^\s"']+)/g)) {
+      const target = match[1].replace(/[),;]+$/, "");
+      if (!existsSync(join(skillDir, target)))
+        diagnostics.push(`template: referenced Skill helper not found: ${target}`);
+    }
+  }
+  return diagnostics;
+}
+
+function validatePortablePaths(config) {
+  const diagnostics = [];
+  for (const value of collectStrings(config)) {
+    if (/^(?:\/home\/|\/Users\/|[A-Za-z]:[\\/])/.test(value))
+      diagnostics.push(`recipe: must not use a machine-local absolute path: ${value}`);
+  }
+  return diagnostics;
+}
+
+function qaDiagnostics(file, config) {
+  const diagnostics = [];
+  const warnings = [];
+  if (config.mailbox !== undefined)
+    diagnostics.push("recipe.mailbox was removed; use control actions and Trace events");
+  if (config.singleton === true && config.async !== true)
+    diagnostics.push("singleton: requires async: true");
+  diagnostics.push(...validateArtifactDeclarations(config));
+  diagnostics.push(...validatePortablePaths(config));
+  diagnostics.push(...validateHelperPaths(file, config));
+  const platformSpecificTemplate = collectTemplateStrings(config.template).some(
+    (template) =>
+      /(^|\s)(?:systemctl|launchctl|osascript|powershell|pwsh|cmd\.exe|apt|apt-get|dnf|yum|brew|pacman|apk)(\s|$)/i.test(
+        template,
+      ),
+  );
+  if (platformSpecificTemplate && !hasPlatformNote(config))
+    diagnostics.push("platform: platform-specific templates must document platform scope");
+  return { diagnostics, warnings };
+}
+
+function qaOk(qaReport) {
+  return qaReport.diagnostics.length === 0 && qaReport.warnings.length === 0;
+}
+
+function validateFile(file, qa = false, skillContext = packageSkillContext) {
+  try {
+    const rawConfig = readRawRecipeConfig(file);
+    const config = readResolvedRecipeConfig(file, [], { skillContext });
+    if (!config?.template)
+      throw new Error("Recipe must define a non-empty template.");
+    const expectedName = basename(file, extname(file));
+    if (config.name !== expectedName)
+      throw new Error(`Recipe identity mismatch: expected ${expectedName}, received ${config.name ?? "<none>"}`);
+    const qaReport = qa ? qaDiagnostics(file, rawConfig) : { diagnostics: [], warnings: [] };
+    return {
+      file,
+      ok: qaOk(qaReport),
+      name: config.name ?? "",
+      async: Boolean(config.async),
+      singleton: Boolean(config.singleton),
+      args: Array.isArray(config.args) ? config.args : [],
+      defaults:
+        config.defaults && typeof config.defaults === "object"
+          ? Object.keys(config.defaults).sort()
+          : [],
+      imports:
+        config.imports && typeof config.imports === "object"
+          ? Object.keys(config.imports).sort()
+          : [],
+      control: Array.isArray(config.control) ? config.control : undefined,
+      ...(qa
+        ? {
+            qa: {
+              ok: qaOk(qaReport),
+              diagnostics: qaReport.diagnostics,
+              warnings: qaReport.warnings,
+            },
+          }
+        : {}),
+      template: templateKind(config.template),
+    };
+  } catch (error) {
+    return {
+      file,
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export function validateRecipes(argv) {
+  const targetArg = argv.find((arg) => !arg.startsWith("-"));
+  const all = argv.includes("--all");
+  const skills = argv.includes("--skills");
+  const qa = argv.includes("--qa");
+  if (!targetArg || argv.includes("--help") || argv.includes("-h")) {
+    return { help: true, ok: Boolean(targetArg), usage: validateRecipeUsage() };
+  }
+  const target = expandPath(targetArg);
+  const scan = skills
+    ? scanSkillRecipes(target)
+    : { files: recipeFiles(target, all), failures: [], skillContext: packageSkillContext };
+  const results = [
+    ...scan.failures,
+    ...scan.files.map((file) => validateFile(file, qa, scan.skillContext)),
+  ];
+  const failed = results.filter((result) => !result.ok).length;
+  return {
+    ok: failed === 0,
+    total: results.length,
+    passed: results.length - failed,
+    failed,
+    results,
+  };
+}
+
+function summarizeReport(report) {
+  const results = Array.isArray(report.results) ? report.results : [];
+  return {
+    ok: report.ok,
+    total: report.total,
+    passed: report.passed,
+    failed: report.failed,
+    diagnostics: results.reduce(
+      (total, result) => total + (result.qa?.diagnostics?.length ?? 0),
+      0,
+    ),
+    warnings: results.reduce(
+      (total, result) => total + (result.qa?.warnings?.length ?? 0),
+      0,
+    ),
+    failed_files: results
+      .filter((result) => !result.ok)
+      .map((result) => ({
+        file: result.file,
+        ...(result.error ? { error: result.error } : {}),
+        ...(result.qa?.diagnostics?.length
+          ? { diagnostics: result.qa.diagnostics }
+          : {}),
+        ...(result.qa?.warnings?.length
+          ? { warnings: result.qa.warnings }
+          : {}),
+      })),
+  };
+}
+
+try {
+  const argv = process.argv.slice(2);
+  const report = validateRecipes(argv);
+  if (report.help) console.error(report.usage);
+  else console.log(JSON.stringify(argv.includes("--summary") ? summarizeReport(report) : report, null, 2));
+  process.exit(report.ok ? 0 : 1);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/node_modules/@llblab/pi-actors/skills/artifacts/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: artifacts
+description: Use when an actor workflow must write reusable files, reports, manifests, or bundles with deterministic paths and declared outputs.
+---
+
+# Artifacts
+
+Use this Skill after the desired durable-output outcome is known. For generic Recipe execution, Runs, persistence, or diagnosis, follow `actors`; this Skill only selects artifact behavior.
+
+## Choose the outcome
+
+| Desired outcome | Recipe | Result |
+| --- | --- | --- |
+| Write one generated artifact and a machine-readable manifest, with optional validation first | `artifacts/bundle` | Primary artifact plus manifest |
+| Generate bounded normalized report content without committing a filesystem write | `artifacts/report` | Report content for review or later composition |
+| Generate and write one artifact | `artifacts/write` | Declared artifact path written with explicit mode |
+| Describe one existing or intended artifact | `artifacts/manifest` | Manifest JSON on stdout; no write |
+| Write prior pipeline output exactly | `artifacts/file-write` | Supporting stdin-to-file write; normally use inside composition |
+
+Prefer `bundle` when both durable content and inventory evidence are required. Prefer `write` for one accepted file. Use `report` while content still needs review. Do not use `file-write` as a content generator. If one selected outcome should become a recurring named tool, use the persistent-capability workflow in `actors`; do not copy its graph.
+
+## Inputs and boundaries
+
+- Keep `input` bounded and evidence-based; choose the current model explicitly where the Recipe requires `model`.
+- Supply caller-owned `artifact_path` and, for `bundle`, a distinct `manifest_path`.
+- `write_mode=create` is the safe default and stops if the target exists. Use `overwrite` or `append` only when the requested mutation is explicit.
+- Parent directories are created by the writer. `~` is resolved for artifact paths.
+- `manifest` reports existence, size, and modification evidence; it does not validate artifact meaning.
+- Validation in `bundle` runs only when `run_validation=true` and uses the caller-supplied trusted command and scope.
+
+## Stop rules
+
+Stop rather than guessing when the target path, overwrite policy, accepted content, model, or validation command is unclear. Do not claim a durable artifact from `report` or `manifest` alone. After a Run starts, use the `actors` evidence and lifecycle protocol; this Skill does not redefine it.

package/node_modules/@llblab/pi-actors/skills/artifacts/recipes/bundle.json

@@ -0,0 +1,77 @@
+{
+  "async": true,
+  "imports": {
+    "artifactWrite": "artifacts/write",
+    "manifest": "artifacts/manifest",
+    "manifestWrite": "artifacts/file-write",
+    "validation": "actors/command-validate"
+  },
+  "args": [
+    "input:string",
+    "artifact_path:path",
+    "manifest_path:path",
+    "artifact_title:string",
+    "artifact_format:string",
+    "artifact_status:enum(draft,ready,blocked,accepted)",
+    "write_mode:enum(create,overwrite,append)",
+    "run_validation:bool",
+    "validation_command:string",
+    "validation_scope:string",
+    "validation_timeout_ms:int",
+    "model:string",
+    "tools:string"
+  ],
+  "defaults": {
+    "artifact_title": "Artifact Bundle",
+    "artifact_format": "Markdown sections: Summary, Findings, Evidence, Risks, Next Actions.",
+    "artifact_status": "ready",
+    "write_mode": "create",
+    "run_validation": "false",
+    "validation_command": "true",
+    "validation_scope": ".",
+    "validation_timeout_ms": "300000",
+    "tools": ""
+  },
+  "artifacts": {
+    "artifact": "{artifact_path}",
+    "manifest": "{manifest_path}"
+  },
+  "template": [
+    {
+      "when": "run_validation",
+      "name": "validation",
+      "values": {
+        "command": "{validation_command}",
+        "scope": "{validation_scope}",
+        "timeout_ms": "{validation_timeout_ms}"
+      }
+    },
+    {
+      "name": "artifactWrite",
+      "values": {
+        "input": "{input}",
+        "artifact_path": "{artifact_path}",
+        "artifact_format": "{artifact_format}",
+        "write_mode": "{write_mode}",
+        "model": "{model}",
+        "tools": "{tools}"
+      }
+    },
+    {
+      "name": "manifest",
+      "values": {
+        "artifact_path": "{artifact_path}",
+        "title": "{artifact_title}",
+        "status": "{artifact_status}",
+        "summary": "Artifact bundle manifest for {artifact_path}."
+      }
+    },
+    {
+      "name": "manifestWrite",
+      "values": {
+        "artifact_path": "{manifest_path}",
+        "mode": "{write_mode}"
+      }
+    }
+  ]
+}

package/node_modules/@llblab/pi-actors/skills/artifacts/recipes/file-write.json

@@ -0,0 +1,14 @@
+{
+  "async": false,
+  "args": [
+    "artifact_path:path",
+    "mode:enum(create,overwrite,append)"
+  ],
+  "defaults": {
+    "mode": "create"
+  },
+  "template": {
+    "template": "{skill_dir}/scripts/artifact-utils.mjs write {artifact_path} {mode}",
+    "output": "stdout"
+  }
+}

package/node_modules/@llblab/pi-actors/skills/artifacts/recipes/manifest.json

@@ -0,0 +1,14 @@
+{
+  "args": [
+    "artifact_path:path",
+    "title:string",
+    "status:enum(draft,ready,blocked,accepted)",
+    "summary:string"
+  ],
+  "defaults": {
+    "title": "Artifact",
+    "status": "draft",
+    "summary": "Machine-readable artifact manifest."
+  },
+  "template": "{skill_dir}/scripts/artifact-utils.mjs manifest {artifact_path} {title} {status} {summary}"
+}

package/node_modules/@llblab/pi-actors/skills/artifacts/recipes/report.json

@@ -0,0 +1,39 @@
+{
+  "async": true,
+  "imports": {
+    "normalizer": "swarm/subagent-normalize",
+    "artifact": "swarm/subagent-artifact"
+  },
+  "args": [
+    "input:string",
+    "artifact_path:path",
+    "artifact_format:string",
+    "model:string",
+    "tools:string"
+  ],
+  "defaults": {
+    "artifact_format": "Markdown sections: Summary, Findings, Evidence, Risks, Next Actions.",
+    "tools": ""
+  },
+  "template": [
+    {
+      "name": "normalizer",
+      "values": {
+        "input": "{input}",
+        "format": "{artifact_format}",
+        "model": "{model}",
+        "tools": "{tools}"
+      }
+    },
+    {
+      "name": "artifact",
+      "values": {
+        "input": "Use normalized report from stdin.",
+        "artifact_path": "{artifact_path}",
+        "artifact_format": "{artifact_format}",
+        "model": "{model}",
+        "tools": "{tools}"
+      }
+    }
+  ]
+}

package/node_modules/@llblab/pi-actors/skills/artifacts/recipes/write.json

@@ -0,0 +1,53 @@
+{
+  "async": true,
+  "imports": {
+    "normalizer": "swarm/subagent-normalize",
+    "artifact": "swarm/subagent-artifact",
+    "writer": "artifacts/file-write"
+  },
+  "args": [
+    "input:string",
+    "artifact_path:path",
+    "artifact_format:string",
+    "write_mode:enum(create,overwrite,append)",
+    "model:string",
+    "tools:string"
+  ],
+  "defaults": {
+    "artifact_format": "Markdown sections: Summary, Findings, Evidence, Risks, Next Actions.",
+    "write_mode": "create",
+    "tools": ""
+  },
+  "artifacts": {
+    "artifact": "{artifact_path}"
+  },
+  "template": [
+    {
+      "name": "normalizer",
+      "values": {
+        "input": "{input}",
+        "format": "{artifact_format}",
+        "model": "{model}",
+        "tools": "{tools}"
+      }
+    },
+    {
+      "name": "artifact",
+      "values": {
+        "input": "Use normalized report from stdin.",
+        "artifact_path": "{artifact_path}",
+        "artifact_format": "{artifact_format}",
+        "write_policy": "The caller selected deterministic write mode {write_mode}; produce only the artifact content that should be written, with no surrounding commentary outside the artifact body.",
+        "model": "{model}",
+        "tools": "{tools}"
+      }
+    },
+    {
+      "name": "writer",
+      "values": {
+        "artifact_path": "{artifact_path}",
+        "mode": "{write_mode}"
+      }
+    }
+  ]
+}

package/node_modules/@llblab/pi-actors/skills/artifacts/scripts/artifact-utils.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+/** Artifact-owned deterministic manifest and write helpers. */
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, resolve } from "node:path";
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function pathOf(value) {
+  return resolve(String(value).replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+}
+
+function manifest(pathValue, title = "Artifact", status = "draft", summary = "") {
+  const path = pathOf(pathValue);
+  const exists = existsSync(path);
+  const stat = exists ? statSync(path) : undefined;
+  console.log(JSON.stringify({
+    title,
+    status,
+    path,
+    exists,
+    bytes: stat?.size ?? 0,
+    modified: stat?.mtime?.toISOString?.() ?? null,
+    summary,
+  }, null, 2));
+}
+
+function write(pathValue, mode = "create") {
+  const path = pathOf(pathValue);
+  if (!["create", "overwrite", "append"].includes(mode))
+    fail(`Invalid artifact write mode: ${mode}`);
+  if (mode === "create" && existsSync(path)) fail(`Artifact already exists: ${path}`);
+  const content = readFileSync(0, "utf8");
+  mkdirSync(dirname(path), { recursive: true });
+  if (mode === "append") appendFileSync(path, content);
+  else writeFileSync(path, content, "utf8");
+  console.log(JSON.stringify({
+    path,
+    mode,
+    bytes: statSync(path).size,
+    written: true,
+  }, null, 2));
+}
+
+const [command, ...args] = process.argv.slice(2);
+try {
+  if (command === "manifest") manifest(args[0] ?? "artifact.md", args[1], args[2], args[3]);
+  else if (command === "write") write(args[0] ?? "artifact.md", args[1]);
+  else fail(`Unknown artifact command: ${command ?? ""}`);
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error));
+}