@llblab/pi-actors 0.45.1 → 0.46.1

package/skills/actors/scripts/run-utils.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+
+/** Actor-owned Run summary utilities. */
+
+// @ts-nocheck
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function usage() {
+  console.error(`Usage:
+  run-utils.mjs run-summary <state-root>
+  run-utils.mjs run-ops-snapshot <state-root> <run-id> [lines] [stale-minutes]`);
+}
+
+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 collectRunSummary(rootValue) {
+  const root = resolve(rootValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+  const files = walkFiles(root, 2).filter((file) => basename(file) === "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(sep)[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}`));
+  return rows;
+}
+
+function tailJsonl(fileValue, linesValue = "80") {
+  const file = resolve(fileValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+  if (!existsSync(file)) return [];
+  const lines = Number.parseInt(linesValue, 10);
+  const count = Number.isFinite(lines) && lines > 0 ? lines : 80;
+  return readFileSync(file, "utf8")
+    .trimEnd()
+    .split("\n")
+    .filter(Boolean)
+    .slice(-count)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return { raw: line };
+      }
+    });
+}
+
+function runOpsSnapshot(
+  rootValue,
+  runIdValue = "music",
+  linesValue = "80",
+  staleMinutesValue = "60",
+) {
+  const runs = collectRunSummary(rootValue);
+  const root = resolve(rootValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+  const inspectedRun = String(runIdValue || "music");
+  const staleMs = Number(staleMinutesValue) * 60 * 1000;
+  const now = Date.now();
+  const recommendations = runs.flatMap((run) => {
+    const updatedMs = Date.parse(run.updated || "");
+    const stale =
+      Number.isFinite(updatedMs) &&
+      Number.isFinite(staleMs) &&
+      now - updatedMs > staleMs;
+    if (run.status === "running" && stale) {
+      return [{
+        run: run.run,
+        reason: "running-stale",
+        suggested_inspect: { target: `run:${run.run}`, view: "control" },
+      }];
+    }
+    if (["failed", "exited", "killed"].includes(run.status)) {
+      return [{
+        run: run.run,
+        reason: `terminal-${run.status}`,
+        suggested_inspect: { target: `run:${run.run}`, view: "trace" },
+      }];
+    }
+    return [];
+  });
+  console.log(JSON.stringify({
+    runs,
+    inspectedRun,
+    trace: tailJsonl(join(root, inspectedRun, "trace.jsonl"), linesValue),
+    recommendations,
+  }, null, 2));
+}
+
+function runSummary(rootValue) {
+  console.log(JSON.stringify(collectRunSummary(rootValue), null, 2));
+}
+
+function run(argv = process.argv.slice(2)) {
+  const [command, ...args] = argv;
+  if (command === "run-summary") {
+    runSummary(args[0] ?? "~/.pi/agent/tmp/pi-actors/runs");
+    return;
+  }
+  if (command === "run-ops-snapshot") {
+    runOpsSnapshot(
+      args[0] ?? "~/.pi/agent/tmp/pi-actors/runs",
+      args[1] ?? "music",
+      args[2],
+      args[3],
+    );
+    return;
+  }
+  usage();
+  fail(`Unknown command: ${command ?? ""}`);
+}
+
+try {
+  run();
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error));
+}

package/{dist → skills/actors}/scripts/validate-recipe.mjs

@@ -9,27 +9,49 @@
 
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 function packageRoot() {
-  return dirname(dirname(fileURLToPath(import.meta.url)));
+  return dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))));
 }
 
 async function importRuntimeModule(name) {
   const root = packageRoot();
-  const compiled = join(root, "dist", "lib", `${name}.js`);
+  const localCompiled = join(root, "lib", `${name}.js`);
+  const installedCompiled = join(root, "dist", "lib", `${name}.js`);
   const source = join(root, "lib", `${name}.ts`);
-  return await import(pathToFileURL(existsSync(compiled) ? compiled : source).href);
+  const module = existsSync(localCompiled)
+    ? localCompiled
+    : root.includes(`${sep}node_modules${sep}`) && existsSync(installedCompiled)
+      ? installedCompiled
+      : source;
+  return await import(pathToFileURL(module).href);
 }
 
-const { readResolvedRecipeConfig } = await importRuntimeModule("recipes-references");
+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] [--qa] [--summary]
+  validate-recipe.mjs <recipe-file-or-dir> [--all] [--skills] [--qa] [--summary]
 
-Validates one template recipe file, or all *.json/*.md files in a directory when --all is set. Add --qa for packaged-recipe quality checks, where diagnostics and warnings fail validation. Add --summary for compact CLI output.`;
+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) {
@@ -63,6 +85,79 @@ function recipeFiles(target, all) {
     .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();
+    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);
+      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);
+    }
+  }
+  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));
@@ -105,24 +200,35 @@ function validateArtifactDeclarations(config) {
 
 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: helper scripts must be referenced through {repo}/scripts for installed packages");
-    for (const match of template.matchAll(/\{repo\}\/scripts\/([^\s"']+\.mjs)/g)) {
-      const scriptPath = join(packageRoot(), "scripts", match[1]);
-      if (!existsSync(scriptPath))
-        diagnostics.push(`template: referenced helper script not found: scripts/${match[1]}`);
+      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");
   diagnostics.push(...validateArtifactDeclarations(config));
+  diagnostics.push(...validatePortablePaths(config));
   diagnostics.push(...validateHelperPaths(file, config));
   const platformSpecificTemplate = collectTemplateStrings(config.template).some(
     (template) =>
@@ -139,12 +245,16 @@ function qaOk(qaReport) {
   return qaReport.diagnostics.length === 0 && qaReport.warnings.length === 0;
 }
 
-function validateFile(file, qa = false) {
+function validateFile(file, qa = false, skillContext = packageSkillContext) {
   try {
-    const config = readResolvedRecipeConfig(file);
+    const rawConfig = readRawRecipeConfig(file);
+    const config = readResolvedRecipeConfig(file, [], { skillContext });
     if (!config?.template)
       throw new Error("Recipe must define a non-empty template.");
-    const qaReport = qa ? qaDiagnostics(file, config) : { diagnostics: [], warnings: [] };
+    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),
@@ -183,12 +293,19 @@ function validateFile(file, qa = false) {
 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 files = recipeFiles(expandPath(targetArg), all);
-  const results = files.map((file) => validateFile(file, qa));
+  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,

package/skills/artifacts/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: artifacts
+description: Deterministic artifact writing, reporting, manifests, and bundles for reusable actor workflows.
+---
+
+# Artifacts
+
+Own reusable capabilities that turn bounded input or prior command output into declared files, reports, manifests, and artifact bundles.
+
+## Scope
+
+- Write or assemble caller-declared artifacts with explicit paths and overwrite policy.
+- Produce bounded human-readable reports and machine-readable manifests.
+- Compose validation evidence into artifact outputs without owning the validation policy.
+
+This Skill does not own repository workflow, multi-agent review methodology, Run lifecycle, retention policy, or transport delivery. Its Recipe identity is `artifacts/<filename stem>`; Recipe files have no top-level `name`. Cross-capability composition uses exact `<skill>/<recipe>` references; helper-backed Recipes use only this Skill's `scripts/` through `{skill_dir}`.

package/{dist/recipes/pipeline-artifact-bundle.json → skills/artifacts/recipes/bundle.json}

@@ -1,10 +1,10 @@
 {
   "async": true,
   "imports": {
-    "artifactWrite": "pipeline-artifact-write.json",
-    "manifest": "utility-artifact-manifest.json",
-    "manifestWrite": "utility-artifact-write.json",
-    "validation": "utility-validation-wrapper.json"
+    "artifactWrite": "artifacts/write",
+    "manifest": "artifacts/manifest",
+    "manifestWrite": "artifacts/file-write",
+    "validation": "actors/command-validate"
   },
   "args": [
     "input:string",

package/{recipes/utility-artifact-write.json → skills/artifacts/recipes/file-write.json}

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

package/{recipes/utility-artifact-manifest.json → skills/artifacts/recipes/manifest.json}

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

package/{dist/recipes/pipeline-artifact-report.json → skills/artifacts/recipes/report.json}

@@ -1,8 +1,8 @@
 {
   "async": true,
   "imports": {
-    "normalizer": "subagent-normalize.json",
-    "artifact": "subagent-artifact.json"
+    "normalizer": "swarm/subagent-normalize",
+    "artifact": "swarm/subagent-artifact"
   },
   "args": [
     "input:string",

package/{recipes/pipeline-artifact-write.json → skills/artifacts/recipes/write.json}

@@ -1,9 +1,9 @@
 {
   "async": true,
   "imports": {
-    "normalizer": "subagent-normalize.json",
-    "artifact": "subagent-artifact.json",
-    "writer": "utility-artifact-write.json"
+    "normalizer": "swarm/subagent-normalize",
+    "artifact": "swarm/subagent-artifact",
+    "writer": "artifacts/file-write"
   },
   "args": [
     "input:string",

package/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));
+}

package/skills/media/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: media
+description: Local media discovery, playlist construction, and controllable playback capabilities.
+---
+
+# Media
+
+Own reusable local media workflows and services.
+
+## Scope
+
+- Scan caller-selected media sources and build bounded playlists.
+- Run controllable playback when the local player implements declared actions.
+- Emit canonical Trace and consume canonical Control without inventing media-specific runtime nouns.
+
+This Skill does not own the Run kernel, user media, transport delivery, or general artifact policy. Its Recipe identity is `media/<filename stem>`; Recipe files have no top-level `name`. Helper-backed Recipes locate only co-located scripts through `{skill_dir}`, and cross-capability composition uses exact `<skill>/<recipe>` references.

package/{recipes/pipeline-media-library.json → skills/media/recipes/library.json}

@@ -1,8 +1,8 @@
 {
   "async": true,
   "imports": {
-    "playlist": "utility-playlist-build.json",
-    "artifact": "pipeline-artifact-report.json"
+    "playlist": "media/playlist-build",
+    "artifact": "artifacts/report"
   },
   "args": [
     "source_dir:path",

package/{dist/recipes/music-player.json → skills/media/recipes/player.json}

@@ -1,7 +1,6 @@
 {
   "async": true,
   "args": [
-    "repo:path",
     "command:enum(play,pause,resume,toggle,next,previous,stop,status)",
     "source:string",
     "loop:bool",
@@ -10,7 +9,6 @@
     "state_dir:path"
   ],
   "defaults": {
-    "repo": "~/.pi/agent/extensions/pi-actors",
     "command": "play",
     "loop": "true",
     "volume": "70",
@@ -26,5 +24,5 @@
     "stop",
     "status"
   ],
-  "template": "{repo}/scripts/music-player.mjs {command} {source} {loop} {volume} {player} {state_dir}"
+  "template": "{skill_dir}/scripts/music-player.mjs {command} {source} {loop} {volume} {player} {state_dir}"
 }

package/{recipes/utility-playlist-build.json → skills/media/recipes/playlist-build.json}

@@ -1,17 +1,15 @@
 {
   "args": [
-    "repo:path",
     "source_dir:path",
     "extensions:string",
     "max_depth:int",
     "output_mode:enum(paths,m3u,inline)"
   ],
   "defaults": {
-    "repo": "~/.pi/agent/extensions/pi-actors",
     "source_dir": "~/Music",
     "extensions": ".mp3,.ogg,.wav,.flac,.m4a",
     "max_depth": "2",
     "output_mode": "paths"
   },
-  "template": "{repo}/scripts/recipe-utils.mjs playlist {source_dir} {extensions} {max_depth} {output_mode}"
+  "template": "{skill_dir}/scripts/media-utils.mjs playlist {source_dir} {extensions} {max_depth} {output_mode}"
 }

package/skills/media/scripts/media-utils.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+/** Media-owned playlist construction helper. */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { extname, join, resolve } from "node:path";
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+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 playlist(
+  sourceValue,
+  extensionsValue = ".mp3,.ogg,.wav,.flac,.m4a",
+  maxDepthValue = "2",
+  outputMode = "paths",
+) {
+  const source = resolve(String(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"));
+}
+
+const [command, ...args] = process.argv.slice(2);
+try {
+  if (command === "playlist") playlist(args[0] ?? "~/Music", args[1], args[2], args[3]);
+  else fail(`Unknown media command: ${command ?? ""}`);
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error));
+}