@llblab/pi-actors 0.12.0

package/scripts/recipe-utils.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, extname, join, relative, resolve } from "node:path";
+
+function usage() {
+  console.error(`Usage:
+  recipe-utils.mjs run-summary <state-root>
+  recipe-utils.mjs playlist <source-dir> [extensions] [max-depth] [paths|m3u|inline]
+  recipe-utils.mjs changelog-section <file> <version>
+  recipe-utils.mjs artifact-manifest <artifact-path> <title> <status> [summary]
+  recipe-utils.mjs artifact-write <artifact-path> [create|overwrite|append]
+  recipe-utils.mjs actor-message <type> [to] [from] [summary] [metadata-json] [correlation-id] [reply-to]
+  recipe-utils.mjs package-summary <package-json>`);
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+const ADDRESS_PATTERN = /^[A-Za-z0-9_.-]+$/;
+const MESSAGE_TYPE_PATTERN = /^[A-Za-z][A-Za-z0-9_.:-]*$/;
+function assertToken(value, label) {
+  const normalized = String(value ?? "").trim();
+  if (!normalized) fail(`${label} is required`);
+  if (!ADDRESS_PATTERN.test(normalized)) fail(`${label} contains unsupported characters: ${value}`);
+  return normalized;
+}
+
+function validateActorAddress(address, label) {
+  const value = String(address ?? "").trim();
+  if (value === "coordinator") return value;
+  const separator = value.indexOf(":");
+  if (separator < 0) fail(`${label} must include an actor kind: ${address}`);
+  const kind = value.slice(0, separator);
+  const rest = value.slice(separator + 1);
+  if (kind === "branch") {
+    const [run, branch, ...extra] = rest.split("/");
+    if (extra.length > 0) fail(`${label} branch address has too many parts: ${address}`);
+    return `branch:${assertToken(run, `${label} branch run`)}/${assertToken(branch, `${label} branch id`)}`;
+  }
+  if (["run", "session", "tool"].includes(kind)) return `${kind}:${assertToken(rest, label)}`;
+  fail(`${label} has unsupported actor kind: ${kind}`);
+}
+
+function validateMessageType(type) {
+  const value = String(type ?? "").trim();
+  if (!MESSAGE_TYPE_PATTERN.test(value)) fail(`Invalid actor message type: ${type}`);
+  return value;
+}
+
+function walkFiles(dir, maxDepth = 2, depth = 0, out = []) {
+  if (depth > maxDepth || !existsSync(dir)) return out;
+  for (const entry of readdirSync(dir)) {
+    const path = join(dir, entry);
+    const stat = statSync(path);
+    if (stat.isDirectory()) walkFiles(path, maxDepth, depth + 1, out);
+    else if (stat.isFile()) out.push(path);
+  }
+  return out;
+}
+
+function readJson(file) {
+  if (!existsSync(file)) return undefined;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function getRunStatus(run, progress, result) {
+  if (progress?.phase) return progress.phase;
+  if (result?.code !== undefined) return result.code === 0 ? "done" : "failed";
+  return run.status ?? "unknown";
+}
+
+function runSummary(rootValue) {
+  const root = resolve(
+    rootValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  const files = walkFiles(root, 2).filter((file) => file.endsWith("/run.json"));
+  const rows = [];
+  for (const file of files) {
+    const run = readJson(file);
+    if (!run) {
+      rows.push({
+        run: relative(root, file),
+        status: "invalid-json",
+        recipe: "",
+        updated: "",
+      });
+      continue;
+    }
+    const runDir = dirname(file);
+    const progress = readJson(join(runDir, "progress.json"));
+    const result = readJson(join(runDir, "result.json"));
+    rows.push({
+      run: run.run_id ?? run.run ?? relative(root, file).split("/")[0],
+      status: getRunStatus(run, progress, result),
+      recipe: run.recipe ?? run.recipe_file ?? "",
+      updated: progress?.updatedAt ?? result?.completedAt ?? run.updated_at ?? run.completed_at ?? run.started_at ?? "",
+    });
+  }
+  rows.sort((a, b) =>
+    `${a.status}:${a.run}`.localeCompare(`${b.status}:${b.run}`),
+  );
+  console.log(JSON.stringify(rows, null, 2));
+}
+
+function playlist(
+  sourceValue,
+  extensionsValue = ".mp3,.ogg,.wav,.flac,.m4a",
+  maxDepthValue = "2",
+  outputMode = "paths",
+) {
+  const source = resolve(
+    sourceValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
+  );
+  const maxDepth = Number.parseInt(maxDepthValue, 10);
+  const extensions = new Set(
+    extensionsValue
+      .split(",")
+      .map((item) => item.trim().toLowerCase())
+      .filter(Boolean),
+  );
+  const files = walkFiles(source, Number.isFinite(maxDepth) ? maxDepth : 2)
+    .filter((file) => extensions.has(extname(file).toLowerCase()))
+    .sort((a, b) => a.localeCompare(b));
+  if (outputMode === "m3u") console.log(["#EXTM3U", ...files].join("\n"));
+  else if (outputMode === "inline") console.log(files.join("|"));
+  else console.log(files.join("\n"));
+}
+
+function artifactManifest(pathValue, title = "Artifact", status = "draft", summary = "") {
+  const path = resolve(pathValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+  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 artifactWrite(pathValue, mode = "create") {
+  const path = resolve(pathValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+  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");
+  const stat = statSync(path);
+  console.log(JSON.stringify({ path, mode, bytes: stat.size, written: true }, null, 2));
+}
+
+function actorMessage(type = "event", to = "coordinator", from = "run:{run_id}", summary = "", metadataValue = "", correlationId = "", replyTo = "") {
+  const messageType = validateMessageType(type);
+  const messageTo = validateActorAddress(to, "message.to");
+  const messageFrom = validateActorAddress(from, "message.from");
+  let metadata = {};
+  if (metadataValue) {
+    try {
+      const parsed = JSON.parse(metadataValue);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) metadata = parsed;
+      else fail("Actor message metadata must be a JSON object");
+    } catch (error) {
+      fail(`Invalid actor message metadata JSON: ${error.message}`);
+    }
+  }
+  const bodyText = readFileSync(0, "utf8");
+  const trimmed = bodyText.trim();
+  let body = bodyText;
+  if (trimmed) {
+    try {
+      body = JSON.parse(trimmed);
+    } catch {
+      body = bodyText;
+    }
+  }
+  console.log(JSON.stringify({
+    to: messageTo,
+    from: messageFrom,
+    type: messageType,
+    summary: summary || messageType,
+    body,
+    ...(correlationId ? { correlation_id: correlationId } : {}),
+    ...(replyTo ? { reply_to: replyTo } : {}),
+    metadata,
+  }, null, 2));
+}
+
+function packageSummary(fileValue = "package.json") {
+  const file = resolve(fileValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+  const pkg = readJson(file);
+  if (!pkg) fail(`Package JSON not found or invalid: ${fileValue}`);
+  const scripts = pkg.scripts && typeof pkg.scripts === "object"
+    ? Object.keys(pkg.scripts).sort()
+    : [];
+  const dependencies = pkg.dependencies && typeof pkg.dependencies === "object"
+    ? Object.keys(pkg.dependencies).sort()
+    : [];
+  const devDependencies = pkg.devDependencies && typeof pkg.devDependencies === "object"
+    ? Object.keys(pkg.devDependencies).sort()
+    : [];
+  console.log(JSON.stringify({
+    name: pkg.name ?? "",
+    version: pkg.version ?? "",
+    type: pkg.type ?? "",
+    private: Boolean(pkg.private),
+    packageManager: pkg.packageManager ?? "",
+    files: Array.isArray(pkg.files) ? pkg.files : [],
+    bin: pkg.bin ?? null,
+    main: pkg.main ?? "",
+    exports: pkg.exports ?? null,
+    scripts,
+    dependencyCount: dependencies.length,
+    devDependencyCount: devDependencies.length,
+    dependencies,
+    devDependencies,
+  }, null, 2));
+}
+
+function changelogSection(fileValue, version) {
+  const file = resolve(fileValue);
+  const lines = readFileSync(file, "utf8").split(/\r?\n/);
+  const start = lines.findIndex(
+    (line) => line.startsWith("## ") && line.includes(version),
+  );
+  if (start < 0) fail(`Version section not found: ${version}`);
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (lines[index].startsWith("## ")) {
+      end = index;
+      break;
+    }
+  }
+  console.log(lines.slice(start, end).join("\n").trimEnd());
+}
+
+const [command, ...args] = process.argv.slice(2);
+if (!command) {
+  usage();
+  process.exit(1);
+}
+
+if (command === "run-summary")
+  runSummary(args[0] ?? "~/.pi/agent/tmp/pi-actors/runs");
+else if (command === "playlist")
+  playlist(args[0] ?? "~/Music", args[1], args[2], args[3]);
+else if (command === "changelog-section")
+  changelogSection(args[0] ?? "CHANGELOG.md", args[1] ?? "Unreleased");
+else if (command === "artifact-manifest")
+  artifactManifest(args[0] ?? "artifact.md", args[1], args[2], args[3]);
+else if (command === "artifact-write")
+  artifactWrite(args[0] ?? "artifact.md", args[1] ?? "create");
+else if (command === "actor-message")
+  actorMessage(args[0], args[1], args[2], args[3], args[4], args[5], args[6]);
+else if (command === "package-summary")
+  packageSummary(args[0] ?? "package.json");
+else {
+  usage();
+  fail(`Unknown command: ${command}`);
+}

package/scripts/validate-recipe.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env -S node --experimental-strip-types
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+import { readResolvedRecipeConfig } from "../lib/recipe-references.ts";
+
+function usage() {
+  console.error(`Usage:
+  validate-recipe.mjs <recipe-file-or-dir> [--all]
+
+Validates one template recipe file, or all *.json files in a directory when --all is set.`);
+}
+
+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") {
+    if (typeof template.template === "string") return "leaf";
+    if (Array.isArray(template.template)) return template.parallel === true ? "parallel" : "sequence";
+    if (template.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"))
+    .sort((a, b) => a.localeCompare(b))
+    .map((file) => resolve(target, file));
+}
+
+function validateFile(file) {
+  try {
+    const config = readResolvedRecipeConfig(file);
+    if (!config?.template) throw new Error("Recipe must define a non-empty template.");
+    return {
+      file,
+      ok: true,
+      name: config.name ?? "",
+      async: Boolean(config.async),
+      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() : [],
+      mailbox: config.mailbox && typeof config.mailbox === "object" ? {
+        accepts: Array.isArray(config.mailbox.accepts) ? config.mailbox.accepts : [],
+        emits: Array.isArray(config.mailbox.emits) ? config.mailbox.emits : [],
+      } : undefined,
+      template: templateKind(config.template),
+    };
+  } catch (error) {
+    return {
+      file,
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+const args = process.argv.slice(2);
+const targetArg = args.find((arg) => !arg.startsWith("-"));
+const all = args.includes("--all");
+if (!targetArg || args.includes("--help") || args.includes("-h")) {
+  usage();
+  process.exit(targetArg ? 0 : 1);
+}
+
+const files = recipeFiles(expandPath(targetArg), all);
+const results = files.map(validateFile);
+const failed = results.filter((result) => !result.ok).length;
+const report = {
+  ok: failed === 0,
+  total: results.length,
+  passed: results.length - failed,
+  failed,
+  results,
+};
+console.log(JSON.stringify(report, null, 2));
+process.exit(report.ok ? 0 : 1);