tubeless 0.2.4 → 0.2.6

package/dist/project/project.d.ts

@@ -0,0 +1,3 @@
+export { definePipelineProject, type PipelineProjectCommandModule, type PipelineProjectManifest, type PipelineProjectManifestInput, } from "./project-manifest.js";
+export { validatePipelineDocument, type PipelineDocumentMetadata } from "./project-document.js";
+export { compilePipelineDocument, PipelineDocumentError, type PipelineDocument, type PipelineDocumentDefinition, type PipelineDocumentFinalizer, type PipelineDocumentHandler, type PipelineDocumentRegistry, type PipelineDocumentStep, } from "./project-compiler.js";

package/dist/project/project.js

@@ -0,0 +1,4 @@
+export { definePipelineProject, } from "./project-manifest.js";
+export { validatePipelineDocument } from "./project-document.js";
+export { compilePipelineDocument, PipelineDocumentError, } from "./project-compiler.js";
+//# sourceMappingURL=project.js.map

package/dist/project/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../../src/project/project.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,GAItB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,wBAAwB,EAAiC,MAAM,uBAAuB,CAAC;AAEhG,OAAO,EACL,uBAAuB,EACvB,qBAAqB,GAOtB,MAAM,uBAAuB,CAAC","sourcesContent":["export {\n  definePipelineProject,\n  type PipelineProjectCommandModule,\n  type PipelineProjectManifest,\n  type PipelineProjectManifestInput,\n} from \"./project-manifest.js\";\n\nexport { validatePipelineDocument, type PipelineDocumentMetadata } from \"./project-document.js\";\n\nexport {\n  compilePipelineDocument,\n  PipelineDocumentError,\n  type PipelineDocument,\n  type PipelineDocumentDefinition,\n  type PipelineDocumentFinalizer,\n  type PipelineDocumentHandler,\n  type PipelineDocumentRegistry,\n  type PipelineDocumentStep,\n} from \"./project-compiler.js\";\n"]}

package/dist/workbench/workbench-project-loader.d.ts

@@ -1,5 +1,5 @@
 import { type WorkbenchPipeline, type WorkbenchPipelineCommand } from "./pipeline-module.js";
-import { type PipelineProjectManifest } from "./workbench-project.js";
+import { type PipelineProjectManifest } from "../project/project-manifest.js";
 import { type WorkbenchCliIo } from "./workbench-shared.js";
 /** Default project manifest checked in the invocation directory. No parent search is performed. */
 export declare const DEFAULT_PIPELINE_PROJECT_MANIFEST = "tubeless.project.ts";

package/dist/workbench/workbench-project-loader.js

@@ -1,7 +1,7 @@
 import { stat } from "node:fs/promises";
 import * as path from "node:path";
 import { importModuleNamespace, selectUniqueExport, } from "./pipeline-module.js";
-import { isPipelineProjectManifest, } from "./workbench-project.js";
+import { isPipelineProjectManifest, } from "../project/project-manifest.js";
 import { errorMessage, loadPipelineCommand, loadPlanSource, TUBELESS_WORKBENCH_EXIT_CODE, writeUsageError, } from "./workbench-shared.js";
 /** Default project manifest checked in the invocation directory. No parent search is performed. */
 export const DEFAULT_PIPELINE_PROJECT_MANIFEST = "tubeless.project.ts";

package/dist/workbench/workbench-project-loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"workbench-project-loader.js","sourceRoot":"","sources":["../../src/workbench/workbench-project-loader.ts"],"names":[],"mappings":"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","sourcesContent":["import { stat } from \"node:fs/promises\";\nimport * as path from \"node:path\";\nimport {\n  importModuleNamespace,\n  selectUniqueExport,\n  type WorkbenchPipeline,\n  type WorkbenchPipelineCommand,\n} from \"./pipeline-module.js\";\nimport {\n  isPipelineProjectManifest,\n  type PipelineProjectCommandModule,\n  type PipelineProjectManifest,\n} from \"./workbench-project.js\";\nimport {\n  errorMessage,\n  loadPipelineCommand,\n  loadPlanSource,\n  TUBELESS_WORKBENCH_EXIT_CODE,\n  writeUsageError,\n  type WorkbenchCliIo,\n} from \"./workbench-shared.js\";\n\n/** Default project manifest checked in the invocation directory. No parent search is performed. */\nexport const DEFAULT_PIPELINE_PROJECT_MANIFEST = \"tubeless.project.ts\";\n\nexport interface LoadedPipelineProjectManifest {\n  filePath: string;\n  manifest: PipelineProjectManifest;\n}\n\nexport interface ResolvedPipelineProjectCommand {\n  cwd: string;\n  exportName?: string;\n  filePath: string;\n  id: string;\n  name?: string;\n}\n\ntype LoadFailure = { exitCode: number };\n\nconst EXPORT_PROJECT_MUTEX_ERROR =\n  \"--export cannot be combined with --project; the manifest owns export selection.\";\n\ninterface ResolvedTargetLoad {\n  exportName: string | undefined;\n  fileArgument: string;\n  loadIo: WorkbenchCliIo;\n  registration?: ResolvedPipelineProjectCommand;\n}\n\nasync function pathExists(filePath: string): Promise<boolean> {\n  try {\n    await stat(filePath);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/** Load one explicitly named project manifest without searching parent directories. */\nexport async function loadPipelineProjectManifest(\n  fileArgument: string,\n  io: WorkbenchCliIo\n): Promise<LoadedPipelineProjectManifest | LoadFailure> {\n  const filePath = path.resolve(io.cwd, fileArgument);\n  try {\n    const fileStat = await stat(filePath);\n    if (!fileStat.isFile()) throw new Error(`${filePath} is not a file.`);\n    const manifest = selectUniqueExport(\n      await importModuleNamespace(filePath),\n      undefined,\n      isPipelineProjectManifest,\n      \"project manifest\",\n      { hintExport: false }\n    ).value;\n    const moduleIdentities = new Set<string>();\n    for (const command of manifest.commands) {\n      const moduleIdentity = `${path.resolve(path.dirname(filePath), command.file)}\\0${command.export ?? \"\"}`;\n      if (moduleIdentities.has(moduleIdentity)) {\n        throw new Error(\n          `Project manifest command ${JSON.stringify(command.file)}${command.export ? ` export ${JSON.stringify(command.export)}` : \"\"} resolves to a duplicate module registration.`\n        );\n      }\n      moduleIdentities.add(moduleIdentity);\n    }\n    return { filePath, manifest };\n  } catch (error) {\n    io.stderr.write(`Error: ${errorMessage(error)}\\n`);\n    return { exitCode: TUBELESS_WORKBENCH_EXIT_CODE.load };\n  }\n}\n\n/** Resolve one stable command id from a loaded manifest. */\nfunction resolvePipelineProjectCommand(\n  loaded: LoadedPipelineProjectManifest,\n  id: string,\n  io: WorkbenchCliIo\n): ResolvedPipelineProjectCommand | LoadFailure {\n  const command = loaded.manifest.commands.find((candidate) => candidate.id === id);\n  if (!command) {\n    io.stderr.write(\n      `Error: Project manifest ${loaded.filePath} does not register command ${JSON.stringify(id)}.\\n`\n    );\n    return { exitCode: TUBELESS_WORKBENCH_EXIT_CODE.load };\n  }\n  return resolveProjectCommandModule(loaded, command);\n}\n\nfunction resolveProjectCommandModule(\n  loaded: LoadedPipelineProjectManifest,\n  command: PipelineProjectCommandModule\n): ResolvedPipelineProjectCommand {\n  const manifestDirectory = path.dirname(loaded.filePath);\n  const resolved: ResolvedPipelineProjectCommand = {\n    cwd: path.resolve(manifestDirectory, loaded.manifest.cwd ?? \".\"),\n    filePath: path.resolve(manifestDirectory, command.file),\n    id: command.id,\n  };\n  if (command.export !== undefined) resolved.exportName = command.export;\n  if (command.name !== undefined) resolved.name = command.name;\n  return resolved;\n}\n\nasync function resolveRegisteredTarget(\n  target: string,\n  projectFile: string,\n  io: WorkbenchCliIo\n): Promise<ResolvedPipelineProjectCommand | LoadFailure> {\n  const loaded = await loadPipelineProjectManifest(projectFile, io);\n  if (\"exitCode\" in loaded) return loaded;\n  return resolvePipelineProjectCommand(loaded, target, io);\n}\n\nfunction isPathLike(target: string): boolean {\n  return (\n    path.isAbsolute(target) ||\n    target.startsWith(\".\") ||\n    target.includes(\"/\") ||\n    path.extname(target).length > 0\n  );\n}\n\nasync function projectFileForTarget(\n  target: string,\n  explicitProjectFile: string | undefined,\n  io: WorkbenchCliIo\n): Promise<string | undefined> {\n  if (explicitProjectFile !== undefined) return explicitProjectFile;\n  if (isPathLike(target) || (await pathExists(path.resolve(io.cwd, target)))) return undefined;\n  const defaultFile = path.resolve(io.cwd, DEFAULT_PIPELINE_PROJECT_MANIFEST);\n  return (await pathExists(defaultFile)) ? defaultFile : undefined;\n}\n\nasync function resolveTargetLoad(\n  target: string,\n  exportName: string | undefined,\n  projectFile: string | undefined,\n  io: WorkbenchCliIo,\n  usage: string\n): Promise<ResolvedTargetLoad | LoadFailure> {\n  if (exportName !== undefined && projectFile !== undefined) {\n    return { exitCode: writeUsageError(io, EXPORT_PROJECT_MUTEX_ERROR, usage) };\n  }\n\n  const resolvedProjectFile = await projectFileForTarget(target, projectFile, io);\n  if (resolvedProjectFile === undefined) {\n    return { exportName, fileArgument: target, loadIo: io };\n  }\n\n  const registration = await resolveRegisteredTarget(target, resolvedProjectFile, io);\n  if (\"exitCode\" in registration) return registration;\n  return {\n    exportName: registration.exportName,\n    fileArgument: registration.filePath,\n    loadIo: { ...io, cwd: registration.cwd },\n    registration,\n  };\n}\n\nexport async function loadPipelineCommandTarget(\n  target: string,\n  exportName: string | undefined,\n  projectFile: string | undefined,\n  io: WorkbenchCliIo,\n  usage: string\n): Promise<\n  | {\n      command: WorkbenchPipelineCommand;\n      commandIo: WorkbenchCliIo;\n      exportName: string;\n      registration?: ResolvedPipelineProjectCommand;\n    }\n  | LoadFailure\n> {\n  const resolved = await resolveTargetLoad(target, exportName, projectFile, io, usage);\n  if (\"exitCode\" in resolved) return resolved;\n  const loaded = await loadPipelineCommand(\n    resolved.fileArgument,\n    resolved.exportName,\n    resolved.loadIo\n  );\n  if (\"exitCode\" in loaded) return loaded;\n  return { ...loaded, commandIo: resolved.loadIo, registration: resolved.registration };\n}\n\nexport async function loadPlanSourceTarget(\n  target: string,\n  exportName: string | undefined,\n  projectFile: string | undefined,\n  io: WorkbenchCliIo,\n  usage: string\n): Promise<\n  | {\n      registration?: ResolvedPipelineProjectCommand;\n      view: WorkbenchPipeline;\n    }\n  | LoadFailure\n> {\n  const resolved = await resolveTargetLoad(target, exportName, projectFile, io, usage);\n  if (\"exitCode\" in resolved) return resolved;\n  const loaded = await loadPlanSource(resolved.fileArgument, resolved.exportName, resolved.loadIo);\n  if (\"exitCode\" in loaded) return loaded;\n  return {\n    view: loaded.source.kind === \"command\" ? loaded.source.command : loaded.source.pipeline,\n    registration: resolved.registration,\n  };\n}\n"]}
+{"version":3,"file":"workbench-project-loader.js","sourceRoot":"","sources":["../../src/workbench/workbench-project-loader.ts"],"names":[],"mappings":"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","sourcesContent":["import { stat } from \"node:fs/promises\";\nimport * as path from \"node:path\";\nimport {\n  importModuleNamespace,\n  selectUniqueExport,\n  type WorkbenchPipeline,\n  type WorkbenchPipelineCommand,\n} from \"./pipeline-module.js\";\nimport {\n  isPipelineProjectManifest,\n  type PipelineProjectCommandModule,\n  type PipelineProjectManifest,\n} from \"../project/project-manifest.js\";\nimport {\n  errorMessage,\n  loadPipelineCommand,\n  loadPlanSource,\n  TUBELESS_WORKBENCH_EXIT_CODE,\n  writeUsageError,\n  type WorkbenchCliIo,\n} from \"./workbench-shared.js\";\n\n/** Default project manifest checked in the invocation directory. No parent search is performed. */\nexport const DEFAULT_PIPELINE_PROJECT_MANIFEST = \"tubeless.project.ts\";\n\nexport interface LoadedPipelineProjectManifest {\n  filePath: string;\n  manifest: PipelineProjectManifest;\n}\n\nexport interface ResolvedPipelineProjectCommand {\n  cwd: string;\n  exportName?: string;\n  filePath: string;\n  id: string;\n  name?: string;\n}\n\ntype LoadFailure = { exitCode: number };\n\nconst EXPORT_PROJECT_MUTEX_ERROR =\n  \"--export cannot be combined with --project; the manifest owns export selection.\";\n\ninterface ResolvedTargetLoad {\n  exportName: string | undefined;\n  fileArgument: string;\n  loadIo: WorkbenchCliIo;\n  registration?: ResolvedPipelineProjectCommand;\n}\n\nasync function pathExists(filePath: string): Promise<boolean> {\n  try {\n    await stat(filePath);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/** Load one explicitly named project manifest without searching parent directories. */\nexport async function loadPipelineProjectManifest(\n  fileArgument: string,\n  io: WorkbenchCliIo\n): Promise<LoadedPipelineProjectManifest | LoadFailure> {\n  const filePath = path.resolve(io.cwd, fileArgument);\n  try {\n    const fileStat = await stat(filePath);\n    if (!fileStat.isFile()) throw new Error(`${filePath} is not a file.`);\n    const manifest = selectUniqueExport(\n      await importModuleNamespace(filePath),\n      undefined,\n      isPipelineProjectManifest,\n      \"project manifest\",\n      { hintExport: false }\n    ).value;\n    const moduleIdentities = new Set<string>();\n    for (const command of manifest.commands) {\n      const moduleIdentity = `${path.resolve(path.dirname(filePath), command.file)}\\0${command.export ?? \"\"}`;\n      if (moduleIdentities.has(moduleIdentity)) {\n        throw new Error(\n          `Project manifest command ${JSON.stringify(command.file)}${command.export ? ` export ${JSON.stringify(command.export)}` : \"\"} resolves to a duplicate module registration.`\n        );\n      }\n      moduleIdentities.add(moduleIdentity);\n    }\n    return { filePath, manifest };\n  } catch (error) {\n    io.stderr.write(`Error: ${errorMessage(error)}\\n`);\n    return { exitCode: TUBELESS_WORKBENCH_EXIT_CODE.load };\n  }\n}\n\n/** Resolve one stable command id from a loaded manifest. */\nfunction resolvePipelineProjectCommand(\n  loaded: LoadedPipelineProjectManifest,\n  id: string,\n  io: WorkbenchCliIo\n): ResolvedPipelineProjectCommand | LoadFailure {\n  const command = loaded.manifest.commands.find((candidate) => candidate.id === id);\n  if (!command) {\n    io.stderr.write(\n      `Error: Project manifest ${loaded.filePath} does not register command ${JSON.stringify(id)}.\\n`\n    );\n    return { exitCode: TUBELESS_WORKBENCH_EXIT_CODE.load };\n  }\n  return resolveProjectCommandModule(loaded, command);\n}\n\nfunction resolveProjectCommandModule(\n  loaded: LoadedPipelineProjectManifest,\n  command: PipelineProjectCommandModule\n): ResolvedPipelineProjectCommand {\n  const manifestDirectory = path.dirname(loaded.filePath);\n  const resolved: ResolvedPipelineProjectCommand = {\n    cwd: path.resolve(manifestDirectory, loaded.manifest.cwd ?? \".\"),\n    filePath: path.resolve(manifestDirectory, command.file),\n    id: command.id,\n  };\n  if (command.export !== undefined) resolved.exportName = command.export;\n  if (command.name !== undefined) resolved.name = command.name;\n  return resolved;\n}\n\nasync function resolveRegisteredTarget(\n  target: string,\n  projectFile: string,\n  io: WorkbenchCliIo\n): Promise<ResolvedPipelineProjectCommand | LoadFailure> {\n  const loaded = await loadPipelineProjectManifest(projectFile, io);\n  if (\"exitCode\" in loaded) return loaded;\n  return resolvePipelineProjectCommand(loaded, target, io);\n}\n\nfunction isPathLike(target: string): boolean {\n  return (\n    path.isAbsolute(target) ||\n    target.startsWith(\".\") ||\n    target.includes(\"/\") ||\n    path.extname(target).length > 0\n  );\n}\n\nasync function projectFileForTarget(\n  target: string,\n  explicitProjectFile: string | undefined,\n  io: WorkbenchCliIo\n): Promise<string | undefined> {\n  if (explicitProjectFile !== undefined) return explicitProjectFile;\n  if (isPathLike(target) || (await pathExists(path.resolve(io.cwd, target)))) return undefined;\n  const defaultFile = path.resolve(io.cwd, DEFAULT_PIPELINE_PROJECT_MANIFEST);\n  return (await pathExists(defaultFile)) ? defaultFile : undefined;\n}\n\nasync function resolveTargetLoad(\n  target: string,\n  exportName: string | undefined,\n  projectFile: string | undefined,\n  io: WorkbenchCliIo,\n  usage: string\n): Promise<ResolvedTargetLoad | LoadFailure> {\n  if (exportName !== undefined && projectFile !== undefined) {\n    return { exitCode: writeUsageError(io, EXPORT_PROJECT_MUTEX_ERROR, usage) };\n  }\n\n  const resolvedProjectFile = await projectFileForTarget(target, projectFile, io);\n  if (resolvedProjectFile === undefined) {\n    return { exportName, fileArgument: target, loadIo: io };\n  }\n\n  const registration = await resolveRegisteredTarget(target, resolvedProjectFile, io);\n  if (\"exitCode\" in registration) return registration;\n  return {\n    exportName: registration.exportName,\n    fileArgument: registration.filePath,\n    loadIo: { ...io, cwd: registration.cwd },\n    registration,\n  };\n}\n\nexport async function loadPipelineCommandTarget(\n  target: string,\n  exportName: string | undefined,\n  projectFile: string | undefined,\n  io: WorkbenchCliIo,\n  usage: string\n): Promise<\n  | {\n      command: WorkbenchPipelineCommand;\n      commandIo: WorkbenchCliIo;\n      exportName: string;\n      registration?: ResolvedPipelineProjectCommand;\n    }\n  | LoadFailure\n> {\n  const resolved = await resolveTargetLoad(target, exportName, projectFile, io, usage);\n  if (\"exitCode\" in resolved) return resolved;\n  const loaded = await loadPipelineCommand(\n    resolved.fileArgument,\n    resolved.exportName,\n    resolved.loadIo\n  );\n  if (\"exitCode\" in loaded) return loaded;\n  return { ...loaded, commandIo: resolved.loadIo, registration: resolved.registration };\n}\n\nexport async function loadPlanSourceTarget(\n  target: string,\n  exportName: string | undefined,\n  projectFile: string | undefined,\n  io: WorkbenchCliIo,\n  usage: string\n): Promise<\n  | {\n      registration?: ResolvedPipelineProjectCommand;\n      view: WorkbenchPipeline;\n    }\n  | LoadFailure\n> {\n  const resolved = await resolveTargetLoad(target, exportName, projectFile, io, usage);\n  if (\"exitCode\" in resolved) return resolved;\n  const loaded = await loadPlanSource(resolved.fileArgument, resolved.exportName, resolved.loadIo);\n  if (\"exitCode\" in loaded) return loaded;\n  return {\n    view: loaded.source.kind === \"command\" ? loaded.source.command : loaded.source.pipeline,\n    registration: resolved.registration,\n  };\n}\n"]}

package/dist/workbench/workbench-validate.d.ts

@@ -0,0 +1,2 @@
+import { type WorkbenchCliIo } from "./workbench-shared.js";
+export declare function runValidate(argv: readonly string[], io: WorkbenchCliIo): Promise<number>;

package/dist/workbench/workbench-validate.js

@@ -0,0 +1,76 @@
+import { readFile } from "node:fs/promises";
+import { extname, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { PipelineDocumentError, validatePipelineDocument } from "../project/project.js";
+import { errorMessage, TUBELESS_WORKBENCH_EXIT_CODE, } from "./workbench-shared.js";
+import { runWorkbenchSubcommand } from "./workbench-subcommand.js";
+const VALIDATE_USAGE = `Usage: tubeless validate [--json] <document.yaml|document.yml|document.json>
+
+Check pipeline document structure and metadata without importing handlers.
+Does not check graph semantics, registered names, or domain values. Use inspect
+or plan on the compiled command module for engine validation.
+YAML uses Bun's parser; duplicate mapping keys may be overwritten during parsing.
+
+Options:
+      --json   Emit a structured validation result
+  -h, --help   Show this help
+`;
+export async function runValidate(argv, io) {
+    return runWorkbenchSubcommand({
+        usage: VALIDATE_USAGE,
+        parse: (args) => parseArgs({
+            args: [...args],
+            allowPositionals: true,
+            strict: true,
+            options: {
+                help: { type: "boolean", short: "h" },
+                json: { type: "boolean" },
+            },
+        }),
+        positionalCountError: { count: 1, message: "Pass exactly one YAML or JSON document." },
+        async run(parsed, commandIo) {
+            const file = resolve(commandIo.cwd, parsed.positionals[0]);
+            try {
+                const extension = extname(file).toLowerCase();
+                if (![".yaml", ".yml", ".json"].includes(extension)) {
+                    throw new Error("Expected a .yaml, .yml, or .json document");
+                }
+                const source = await readFile(file, "utf8");
+                let value;
+                if (extension === ".json")
+                    value = JSON.parse(source);
+                else {
+                    // The executable runs under Bun; keep its parser out of library entrypoints.
+                    const specifier = "bun";
+                    // SAFETY: Bun's documented YAML.parse API returns parsed, untrusted data.
+                    const { YAML } = (await import(specifier));
+                    value = YAML.parse(source);
+                }
+                const document = validatePipelineDocument(value);
+                const pipelines = Object.keys(document.pipelines);
+                commandIo.stdout.write(parsed.values.json
+                    ? `${JSON.stringify({ ok: true, file, version: document.version, metadata: document.metadata, pipelines })}\n`
+                    : `Valid pipeline document: ${file} (${pipelines.length} pipeline(s))\n`);
+                return TUBELESS_WORKBENCH_EXIT_CODE.success;
+            }
+            catch (error) {
+                if (parsed.values.json) {
+                    commandIo.stdout.write(`${JSON.stringify({
+                        ok: false,
+                        file,
+                        error: {
+                            message: errorMessage(error),
+                            ...(error instanceof PipelineDocumentError
+                                ? { code: error.code, path: error.path }
+                                : {}),
+                        },
+                    })}\n`);
+                }
+                else
+                    commandIo.stderr.write(`${errorMessage(error)}\n`);
+                return TUBELESS_WORKBENCH_EXIT_CODE.validation;
+            }
+        },
+    }, argv, io);
+}
+//# sourceMappingURL=workbench-validate.js.map

package/dist/workbench/workbench-validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbench-validate.js","sourceRoot":"","sources":["../../src/workbench/workbench-validate.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { extname, resolve } from \"node:path\";\nimport { parseArgs } from \"node:util\";\nimport { PipelineDocumentError, validatePipelineDocument } from \"../project/project.js\";\nimport {\n  errorMessage,\n  TUBELESS_WORKBENCH_EXIT_CODE,\n  type WorkbenchCliIo,\n} from \"./workbench-shared.js\";\nimport { runWorkbenchSubcommand } from \"./workbench-subcommand.js\";\n\nconst VALIDATE_USAGE = `Usage: tubeless validate [--json] <document.yaml|document.yml|document.json>\n\nCheck pipeline document structure and metadata without importing handlers.\nDoes not check graph semantics, registered names, or domain values. Use inspect\nor plan on the compiled command module for engine validation.\nYAML uses Bun's parser; duplicate mapping keys may be overwritten during parsing.\n\nOptions:\n      --json   Emit a structured validation result\n  -h, --help   Show this help\n`;\n\nexport async function runValidate(argv: readonly string[], io: WorkbenchCliIo): Promise<number> {\n  return runWorkbenchSubcommand(\n    {\n      usage: VALIDATE_USAGE,\n      parse: (args) =>\n        parseArgs({\n          args: [...args],\n          allowPositionals: true,\n          strict: true,\n          options: {\n            help: { type: \"boolean\", short: \"h\" },\n            json: { type: \"boolean\" },\n          },\n        }),\n      positionalCountError: { count: 1, message: \"Pass exactly one YAML or JSON document.\" },\n      async run(parsed, commandIo) {\n        const file = resolve(commandIo.cwd, parsed.positionals[0]!);\n        try {\n          const extension = extname(file).toLowerCase();\n          if (![\".yaml\", \".yml\", \".json\"].includes(extension)) {\n            throw new Error(\"Expected a .yaml, .yml, or .json document\");\n          }\n          const source = await readFile(file, \"utf8\");\n          let value: unknown;\n          if (extension === \".json\") value = JSON.parse(source);\n          else {\n            // The executable runs under Bun; keep its parser out of library entrypoints.\n            const specifier = \"bun\";\n            // SAFETY: Bun's documented YAML.parse API returns parsed, untrusted data.\n            const { YAML } = (await import(specifier)) as {\n              YAML: { parse(text: string): unknown };\n            };\n            value = YAML.parse(source);\n          }\n          const document = validatePipelineDocument(value);\n          const pipelines = Object.keys(document.pipelines);\n          commandIo.stdout.write(\n            parsed.values.json\n              ? `${JSON.stringify({ ok: true, file, version: document.version, metadata: document.metadata, pipelines })}\\n`\n              : `Valid pipeline document: ${file} (${pipelines.length} pipeline(s))\\n`\n          );\n          return TUBELESS_WORKBENCH_EXIT_CODE.success;\n        } catch (error) {\n          if (parsed.values.json) {\n            commandIo.stdout.write(\n              `${JSON.stringify({\n                ok: false,\n                file,\n                error: {\n                  message: errorMessage(error),\n                  ...(error instanceof PipelineDocumentError\n                    ? { code: error.code, path: error.path }\n                    : {}),\n                },\n              })}\\n`\n            );\n          } else commandIo.stderr.write(`${errorMessage(error)}\\n`);\n          return TUBELESS_WORKBENCH_EXIT_CODE.validation;\n        }\n      },\n    },\n    argv,\n    io\n  );\n}\n"]}

package/dist/workbench/workbench.js

@@ -6,6 +6,7 @@ import { runPlan } from "./workbench-plan.js";
 import { runCommand } from "./workbench-run.js";
 import { TUBELESS_WORKBENCH_EXIT_CODE, writeUsageError, } from "./workbench-shared.js";
 import { runUi } from "./workbench-ui.js";
+import { runValidate } from "./workbench-validate.js";
 export { TUBELESS_WORKBENCH_EXIT_CODE } from "./workbench-shared.js";
 const WORKBENCH_USAGE = `Usage: tubeless <command> [options] <registered-id|pipeline-or-command-file>
 
@@ -13,6 +14,7 @@ Inspect, plan, visualize, or safely run exported tubeless workflows.
 
 Commands:
   tubeless list      List commands explicitly registered in the project manifest
+  tubeless validate  Check a YAML or JSON pipeline document without loading handlers
   tubeless inspect   Show pipeline identity and the default structural plan
   tubeless plan      Preview step selection without executing the pipeline
   tubeless graph     Generate Mermaid flowchart source
@@ -34,6 +36,8 @@ export async function runWorkbenchCli(argv, io) {
     }
     if (command === "list")
         return runList(commandArgs, io);
+    if (command === "validate")
+        return runValidate(commandArgs, io);
     if (command === "inspect")
         return runInspect(commandArgs, io);
     if (command === "plan")

package/dist/workbench/workbench.js.map

@@ -1 +1 @@
-{"version":3,"file":"workbench.js","sourceRoot":"","sources":["../../src/workbench/workbench.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EACL,4BAA4B,EAC5B,eAAe,GAEhB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE1C,OAAO,EAAE,4BAA4B,EAAuB,MAAM,uBAAuB,CAAC;AAE1F,MAAM,eAAe,GAAG;;;;;;;;;;;;;;CAcvB,CAAC;AAEF,mGAAmG;AACnG,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAuB,EACvB,EAAkB;IAElB,MAAM,CAAC,OAAO,EAAE,GAAG,WAAW,CAAC,GAAG,IAAI,CAAC;IACvC,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACnE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;QACjC,OAAO,4BAA4B,CAAC,OAAO,CAAC;IAC9C,CAAC;IACD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,eAAe,CAAC,EAAE,EAAE,iBAAiB,EAAE,eAAe,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACxD,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC9D,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACxD,IAAI,OAAO,KAAK,OAAO;QAAE,OAAO,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC1D,IAAI,OAAO,KAAK,KAAK;QAAE,OAAO,UAAU,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC1D,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC9D,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACpD,OAAO,eAAe,CAAC,EAAE,EAAE,mBAAmB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;AAC7F,CAAC","sourcesContent":["import { runGraph } from \"./workbench-graph.js\";\nimport { runHistory } from \"./workbench-history.js\";\nimport { runInspect } from \"./workbench-inspect.js\";\nimport { runList } from \"./workbench-list.js\";\nimport { runPlan } from \"./workbench-plan.js\";\nimport { runCommand } from \"./workbench-run.js\";\nimport {\n  TUBELESS_WORKBENCH_EXIT_CODE,\n  writeUsageError,\n  type WorkbenchCliIo,\n} from \"./workbench-shared.js\";\nimport { runUi } from \"./workbench-ui.js\";\n\nexport { TUBELESS_WORKBENCH_EXIT_CODE, type WorkbenchCliIo } from \"./workbench-shared.js\";\n\nconst WORKBENCH_USAGE = `Usage: tubeless <command> [options] <registered-id|pipeline-or-command-file>\n\nInspect, plan, visualize, or safely run exported tubeless workflows.\n\nCommands:\n  tubeless list      List commands explicitly registered in the project manifest\n  tubeless inspect   Show pipeline identity and the default structural plan\n  tubeless plan      Preview step selection without executing the pipeline\n  tubeless graph     Generate Mermaid flowchart source\n  tubeless run       Execute an exported definePipelineCommand\n  tubeless history   Show recorded runs from the local SQLite store\n  tubeless ui        Open the optional local run studio\n\nRun tubeless <command> --help for command-specific options.\n`;\n\n/** Run the `tubeless` development workbench. Execution requires a definePipelineCommand export. */\nexport async function runWorkbenchCli(\n  argv: readonly string[],\n  io: WorkbenchCliIo\n): Promise<number> {\n  const [command, ...commandArgs] = argv;\n  if (command === \"--help\" || command === \"-h\" || command === \"help\") {\n    io.stdout.write(WORKBENCH_USAGE);\n    return TUBELESS_WORKBENCH_EXIT_CODE.success;\n  }\n  if (command === undefined) {\n    return writeUsageError(io, \"Pass a command.\", WORKBENCH_USAGE);\n  }\n  if (command === \"list\") return runList(commandArgs, io);\n  if (command === \"inspect\") return runInspect(commandArgs, io);\n  if (command === \"plan\") return runPlan(commandArgs, io);\n  if (command === \"graph\") return runGraph(commandArgs, io);\n  if (command === \"run\") return runCommand(commandArgs, io);\n  if (command === \"history\") return runHistory(commandArgs, io);\n  if (command === \"ui\") return runUi(commandArgs, io);\n  return writeUsageError(io, `Unknown command ${JSON.stringify(command)}.`, WORKBENCH_USAGE);\n}\n"]}
+{"version":3,"file":"workbench.js","sourceRoot":"","sources":["../../src/workbench/workbench.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EACL,4BAA4B,EAC5B,eAAe,GAEhB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,4BAA4B,EAAuB,MAAM,uBAAuB,CAAC;AAE1F,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;CAevB,CAAC;AAEF,mGAAmG;AACnG,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAuB,EACvB,EAAkB;IAElB,MAAM,CAAC,OAAO,EAAE,GAAG,WAAW,CAAC,GAAG,IAAI,CAAC;IACvC,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACnE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;QACjC,OAAO,4BAA4B,CAAC,OAAO,CAAC;IAC9C,CAAC;IACD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,eAAe,CAAC,EAAE,EAAE,iBAAiB,EAAE,eAAe,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACxD,IAAI,OAAO,KAAK,UAAU;QAAE,OAAO,WAAW,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAChE,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC9D,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACxD,IAAI,OAAO,KAAK,OAAO;QAAE,OAAO,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC1D,IAAI,OAAO,KAAK,KAAK;QAAE,OAAO,UAAU,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC1D,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC9D,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACpD,OAAO,eAAe,CAAC,EAAE,EAAE,mBAAmB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;AAC7F,CAAC","sourcesContent":["import { runGraph } from \"./workbench-graph.js\";\nimport { runHistory } from \"./workbench-history.js\";\nimport { runInspect } from \"./workbench-inspect.js\";\nimport { runList } from \"./workbench-list.js\";\nimport { runPlan } from \"./workbench-plan.js\";\nimport { runCommand } from \"./workbench-run.js\";\nimport {\n  TUBELESS_WORKBENCH_EXIT_CODE,\n  writeUsageError,\n  type WorkbenchCliIo,\n} from \"./workbench-shared.js\";\nimport { runUi } from \"./workbench-ui.js\";\nimport { runValidate } from \"./workbench-validate.js\";\n\nexport { TUBELESS_WORKBENCH_EXIT_CODE, type WorkbenchCliIo } from \"./workbench-shared.js\";\n\nconst WORKBENCH_USAGE = `Usage: tubeless <command> [options] <registered-id|pipeline-or-command-file>\n\nInspect, plan, visualize, or safely run exported tubeless workflows.\n\nCommands:\n  tubeless list      List commands explicitly registered in the project manifest\n  tubeless validate  Check a YAML or JSON pipeline document without loading handlers\n  tubeless inspect   Show pipeline identity and the default structural plan\n  tubeless plan      Preview step selection without executing the pipeline\n  tubeless graph     Generate Mermaid flowchart source\n  tubeless run       Execute an exported definePipelineCommand\n  tubeless history   Show recorded runs from the local SQLite store\n  tubeless ui        Open the optional local run studio\n\nRun tubeless <command> --help for command-specific options.\n`;\n\n/** Run the `tubeless` development workbench. Execution requires a definePipelineCommand export. */\nexport async function runWorkbenchCli(\n  argv: readonly string[],\n  io: WorkbenchCliIo\n): Promise<number> {\n  const [command, ...commandArgs] = argv;\n  if (command === \"--help\" || command === \"-h\" || command === \"help\") {\n    io.stdout.write(WORKBENCH_USAGE);\n    return TUBELESS_WORKBENCH_EXIT_CODE.success;\n  }\n  if (command === undefined) {\n    return writeUsageError(io, \"Pass a command.\", WORKBENCH_USAGE);\n  }\n  if (command === \"list\") return runList(commandArgs, io);\n  if (command === \"validate\") return runValidate(commandArgs, io);\n  if (command === \"inspect\") return runInspect(commandArgs, io);\n  if (command === \"plan\") return runPlan(commandArgs, io);\n  if (command === \"graph\") return runGraph(commandArgs, io);\n  if (command === \"run\") return runCommand(commandArgs, io);\n  if (command === \"history\") return runHistory(commandArgs, io);\n  if (command === \"ui\") return runUi(commandArgs, io);\n  return writeUsageError(io, `Unknown command ${JSON.stringify(command)}.`, WORKBENCH_USAGE);\n}\n"]}

package/docs/README.md

@@ -22,13 +22,16 @@ adapt in your project.
 
 Install the [agent skill pack](./agent-skills.md) to author pipelines or convert existing code.
 
-| Document                    | Use it for                                                           |
-| --------------------------- | -------------------------------------------------------------------- |
-| [CLI](./cli.md)             | `list`, `inspect`, `plan`, `graph`, `run`, `history`, and exit codes |
-| [Local studio](./studio.md) | Optional run history, `tubeless ui`, and catalogs                    |
+| Document                                              | Use it for                                                           |
+| ----------------------------------------------------- | -------------------------------------------------------------------- |
+| [CLI](./cli.md)                                       | `list`, `inspect`, `plan`, `graph`, `run`, `history`, and exit codes |
+| [Local studio](./studio.md)                           | Optional run history, `tubeless ui`, and catalogs                    |
+| [YAML and JSON pipelines](./declarative-pipelines.md) | Compile documents with registered application functions              |
 
 ## Deeper reference
 
+For agent or editor validation, use the [pipeline document JSON Schema](./pipeline-document.schema.json).
+
 | Document                                                                                         | Use it for                                         |
 | ------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
 | [Child-pipeline composition](./child-pipeline-composition.md)                                    | Running a reusable pipeline once or for many items |

package/docs/agent-guide.md

@@ -22,6 +22,21 @@ dry runs with fake I/O. The general `tubeless` skill supports ongoing authoring.
 
 ## Choose pipeline features
 
+- For YAML or JSON authoring, read [declarative pipelines](./declarative-pipelines.md)
+  and adapt [the YAML recipe](../examples/yaml-pipelines.ts). Parse at the
+  application edge, then use `compilePipelineDocument` from `tubeless/project`
+  with explicitly registered handlers and schemas. Keep command registration
+  explicit for CLI and Studio. Unknown fields and references fail compilation;
+  plans still do not validate domain inputs. Dynamic wiring does not infer
+  TypeScript output types, so validate or narrow unknown values in handlers.
+  Use [YAML Peloton](../examples/yaml-peloton.ts) for a larger example with
+  progress, retrying concurrent handlers, dry-run policies, and failure gates.
+  Its per-rider progress is ordinary step detail, not child-pipeline fan-out.
+  Use `tubeless validate --json <document.yaml>` for a handler-free structure
+  check, and the [document JSON Schema](./pipeline-document.schema.json) for
+  editor or agent validation. Optional document metadata is descriptive only.
+  `inspect` or `plan` on a compiled command still checks graph semantics.
+
 - Use `createSteps<TDomainOptions>()` once per pipeline and `definePipeline` once
   after declaring its steps. Domain option types contain domain input only;
   callers pass those options and optional built-in controls to
@@ -71,7 +86,7 @@ dry runs with fake I/O. The general `tubeless` skill supports ongoing authoring.
 - Use `runConcurrent` for bounded lightweight functions that do not need child
   lifecycle events. Use `runConcurrentSettled` when the caller needs completed
   results and the first failure instead of a throw.
-- Use `definePipelineCommand` from `tubeless/workbench` for scripts centered on
+- Use `definePipelineCommand` from `tubeless/cli` for scripts centered on
   a pipeline. Do not parse `process.argv` manually or redeclare built-in dry-run,
   `--step`, or `--target` flags. `mapOptions`, validation, and hooks receive `stepIds` and `targets`,
   not `step` or `target`. Omit `mapOptions` when validated flags already satisfy
@@ -81,6 +96,10 @@ dry runs with fake I/O. The general `tubeless` skill supports ongoing authoring.
   render those parameter definitions instead of parsing help text.
   Use `command.plan()` or `tubeless plan` for a selection-only preview. Do not
   simulate planning with `--plan`.
+- Use `defineCommand` from `tubeless/cli` for standalone scripts. Declare command
+  catalogs with `definePipelineProject` from `tubeless/project`; the catalog
+  works with the CLI before Studio is added. Keep application-specific prompts
+  in the consumer.
 - Use `pipeline.toMermaid()` or `command.toMermaid()` when documentation needs
   the static graph; do not duplicate dependency edges by hand.
 - Use `tubeless list` for the explicit project command inventory. Use
@@ -113,6 +132,13 @@ dry runs with fake I/O. The general `tubeless` skill supports ongoing authoring.
 - Call `context.reportProgress` for long loops and `context.reportAttempt` for
   retries that operators should see.
 - Resolve relative files from `context.cwd` with `node:path`.
+- Import optional Node helpers from `tubeless/node`: `definePaths` resolves named
+  paths against each run's `context.cwd`; `writeJson` creates parents and atomically
+  replaces JSON files, rejecting unserializable top-level values before touching
+  disk; `readJson<T>` parses trusted JSON without schema validation;
+  `resetDir` deletes and recreates generated output directories; `requireEnv`
+  checks required environment values when called. Mark writes and resets with
+  `dryRun: "skip"`; these helpers do not inspect pipeline controls themselves.
 - Use `runOrThrow` when every step must succeed and the caller expects a value.
   It always throws for an unsuccessful run, including `continueOnError` runs.
   Use `run` when the caller must inspect failures, skips, timings, or best-effort

package/docs/api-reference.md

@@ -6,16 +6,17 @@ Package: `tubeless`
 
 ## Public entrypoints
 
-| Entrypoint            | Declaration                             | Surface hash                                                       | Exported symbols |
-| --------------------- | --------------------------------------- | ------------------------------------------------------------------ | ---------------: |
-| `tubeless`            | `./dist/core/pipeline.d.ts`             | `abb2f1fca6d2e21eda1bc1cf72921fee3110f474660834202d223f805300c8d9` |               65 |
-| `tubeless/batch`      | `./dist/utilities/batch.d.ts`           | `6b7fe7d6eec6532cc835505517c3481e4290a2a606c2fddf6c80367f5c76c5f5` |                7 |
-| `tubeless/node`       | `./dist/node/node.d.ts`                 | `1bf8549ca953a11e7202dbda8013db2a8f1d56286f1618bad929efbbb2efd302` |                3 |
-| `tubeless/rate-limit` | `./dist/utilities/rate-limit.d.ts`      | `5cd093bb780a19e44b087b01e2b38e06f07e7233c9920988ba399036e319c368` |                1 |
-| `tubeless/retry`      | `./dist/utilities/retry.d.ts`           | `f91f83f8e31e3e629ed90d1b04656110572ea970187a92369f0908cd75ae8f00` |                4 |
-| `tubeless/workbench`  | `./dist/workbench/workbench-entry.d.ts` | `494aa61a6345d9a798f2e1f084a69cc7859439237c6614280a96421eb0f17ffd` |                2 |
-| `tubeless/testing`    | `./dist/testing/testing.d.ts`           | `9510932b8aec600ecf2bcfdb1a188257dad48a3108087c974689c6e6ec3ad5c9` |                7 |
-| `tubeless/tracing`    | `./dist/tracing/tracing.d.ts`           | `c272c955aab09dcd8cc334ffcea3af5cfda420cecc2881a01e3316e3a38801dd` |                3 |
+| Entrypoint            | Declaration                        | Surface hash                                                       | Exported symbols |
+| --------------------- | ---------------------------------- | ------------------------------------------------------------------ | ---------------: |
+| `tubeless`            | `./dist/core/pipeline.d.ts`        | `abb2f1fca6d2e21eda1bc1cf72921fee3110f474660834202d223f805300c8d9` |               65 |
+| `tubeless/cli`        | `./dist/cli/cli.d.ts`              | `996eeba686bb2a3124c21f30e4c5b5d36873c1a30cbba89ef2b9629206feef48` |               33 |
+| `tubeless/batch`      | `./dist/utilities/batch.d.ts`      | `6b7fe7d6eec6532cc835505517c3481e4290a2a606c2fddf6c80367f5c76c5f5` |                7 |
+| `tubeless/node`       | `./dist/node/node.d.ts`            | `06411eb43b8d1b5aca5d51d70e68553cb9065447b250c29382e6036ad9eac52c` |                8 |
+| `tubeless/rate-limit` | `./dist/utilities/rate-limit.d.ts` | `5cd093bb780a19e44b087b01e2b38e06f07e7233c9920988ba399036e319c368` |                1 |
+| `tubeless/retry`      | `./dist/utilities/retry.d.ts`      | `f91f83f8e31e3e629ed90d1b04656110572ea970187a92369f0908cd75ae8f00` |                4 |
+| `tubeless/project`    | `./dist/project/project.d.ts`      | `464f5d94a3533c4050c32d902badafa4fabfdec176152bb36bb738cf52ce6e81` |               14 |
+| `tubeless/testing`    | `./dist/testing/testing.d.ts`      | `9510932b8aec600ecf2bcfdb1a188257dad48a3108087c974689c6e6ec3ad5c9` |                7 |
+| `tubeless/tracing`    | `./dist/tracing/tracing.d.ts`      | `c272c955aab09dcd8cc334ffcea3af5cfda420cecc2881a01e3316e3a38801dd` |                3 |
 
 ## Symbols
 
@@ -87,6 +88,42 @@ Package: `tubeless`
 - `StepFactory`
 - `StepSkipDecision`
 
+### `tubeless/cli`
+
+- `CliBooleanParam`
+- `CliCheckpointConfig`
+- `CliCommand`
+- `CliCommandConfig`
+- `CliCommandDescriptor`
+- `CliContext`
+- `CliHelpRequested`
+- `CliNumberParam`
+- `CliParam`
+- `CliParameterDescriptor`
+- `CliParams`
+- `CliParamsSchema`
+- `CliParamType`
+- `CliParseResult`
+- `CliPathParam`
+- `CliStringParam`
+- `CliValidationError`
+- `defineCommand`
+- `definePipelineCommand`
+- `DefinePipelineCommandConfig`
+- `PipelineCliParseResult`
+- `PipelineCliValues`
+- `PipelineCommand`
+- `PipelineCommandHookConfig`
+- `PipelineCommandHookContext`
+- `PipelineCommandHookSets`
+- `PipelineReporterConfig`
+- `PipelineReporterMode`
+- `ReporterColorMode`
+- `ReporterOutput`
+- `ReporterSymbolMode`
+- `ReporterTerminalCapabilities`
+- `RunReporterConfig`
+
 ### `tubeless/batch`
 
 - `chunk`
@@ -100,8 +137,13 @@ Package: `tubeless`
 ### `tubeless/node`
 
 - `CheckpointStore`
+- `definePaths`
 - `openCheckpoint`
+- `readJson`
+- `requireEnv`
+- `resetDir`
 - `withCheckpointedBatch`
+- `writeJson`
 
 ### `tubeless/rate-limit`
 
@@ -114,10 +156,22 @@ Package: `tubeless`
 - `RetryOptions`
 - `withRetry`
 
-### `tubeless/workbench`
+### `tubeless/project`
 
-- `definePipelineCommand`
+- `compilePipelineDocument`
 - `definePipelineProject`
+- `PipelineDocument`
+- `PipelineDocumentDefinition`
+- `PipelineDocumentError`
+- `PipelineDocumentFinalizer`
+- `PipelineDocumentHandler`
+- `PipelineDocumentMetadata`
+- `PipelineDocumentRegistry`
+- `PipelineDocumentStep`
+- `PipelineProjectCommandModule`
+- `PipelineProjectManifest`
+- `PipelineProjectManifestInput`
+- `validatePipelineDocument`
 
 ### `tubeless/testing`
 

package/docs/api-report.json

@@ -72,6 +72,46 @@
       "sha256": "abb2f1fca6d2e21eda1bc1cf72921fee3110f474660834202d223f805300c8d9",
       "specifier": "tubeless"
     },
+    {
+      "declaration": "./dist/cli/cli.d.ts",
+      "exports": [
+        "CliBooleanParam",
+        "CliCheckpointConfig",
+        "CliCommand",
+        "CliCommandConfig",
+        "CliCommandDescriptor",
+        "CliContext",
+        "CliHelpRequested",
+        "CliNumberParam",
+        "CliParam",
+        "CliParameterDescriptor",
+        "CliParams",
+        "CliParamsSchema",
+        "CliParamType",
+        "CliParseResult",
+        "CliPathParam",
+        "CliStringParam",
+        "CliValidationError",
+        "defineCommand",
+        "definePipelineCommand",
+        "DefinePipelineCommandConfig",
+        "PipelineCliParseResult",
+        "PipelineCliValues",
+        "PipelineCommand",
+        "PipelineCommandHookConfig",
+        "PipelineCommandHookContext",
+        "PipelineCommandHookSets",
+        "PipelineReporterConfig",
+        "PipelineReporterMode",
+        "ReporterColorMode",
+        "ReporterOutput",
+        "ReporterSymbolMode",
+        "ReporterTerminalCapabilities",
+        "RunReporterConfig"
+      ],
+      "sha256": "996eeba686bb2a3124c21f30e4c5b5d36873c1a30cbba89ef2b9629206feef48",
+      "specifier": "tubeless/cli"
+    },
     {
       "declaration": "./dist/utilities/batch.d.ts",
       "exports": [
@@ -88,8 +128,17 @@
     },
     {
       "declaration": "./dist/node/node.d.ts",
-      "exports": ["CheckpointStore", "openCheckpoint", "withCheckpointedBatch"],
-      "sha256": "1bf8549ca953a11e7202dbda8013db2a8f1d56286f1618bad929efbbb2efd302",
+      "exports": [
+        "CheckpointStore",
+        "definePaths",
+        "openCheckpoint",
+        "readJson",
+        "requireEnv",
+        "resetDir",
+        "withCheckpointedBatch",
+        "writeJson"
+      ],
+      "sha256": "06411eb43b8d1b5aca5d51d70e68553cb9065447b250c29382e6036ad9eac52c",
       "specifier": "tubeless/node"
     },
     {
@@ -105,10 +154,25 @@
       "specifier": "tubeless/retry"
     },
     {
-      "declaration": "./dist/workbench/workbench-entry.d.ts",
-      "exports": ["definePipelineCommand", "definePipelineProject"],
-      "sha256": "494aa61a6345d9a798f2e1f084a69cc7859439237c6614280a96421eb0f17ffd",
-      "specifier": "tubeless/workbench"
+      "declaration": "./dist/project/project.d.ts",
+      "exports": [
+        "compilePipelineDocument",
+        "definePipelineProject",
+        "PipelineDocument",
+        "PipelineDocumentDefinition",
+        "PipelineDocumentError",
+        "PipelineDocumentFinalizer",
+        "PipelineDocumentHandler",
+        "PipelineDocumentMetadata",
+        "PipelineDocumentRegistry",
+        "PipelineDocumentStep",
+        "PipelineProjectCommandModule",
+        "PipelineProjectManifest",
+        "PipelineProjectManifestInput",
+        "validatePipelineDocument"
+      ],
+      "sha256": "464f5d94a3533c4050c32d902badafa4fabfdec176152bb36bb738cf52ce6e81",
+      "specifier": "tubeless/project"
     },
     {
       "declaration": "./dist/testing/testing.d.ts",

package/docs/cli.md

@@ -17,15 +17,67 @@ can run on Node.js 22 or later without Bun.
 
 ## Commands
 
-| Command            | Accepts                             | Does                                                                  |
-| ------------------ | ----------------------------------- | --------------------------------------------------------------------- |
-| `tubeless list`    | A project manifest                  | Lists explicitly registered command IDs without loading their modules |
-| `tubeless inspect` | A pipeline or command export        | Shows the pipeline ID, available targets, steps, and default plan     |
-| `tubeless plan`    | A pipeline or command export        | Previews selection without executing or requiring domain options      |
-| `tubeless graph`   | A pipeline or command export        | Writes Mermaid flowchart source                                       |
-| `tubeless run`     | A `definePipelineCommand` export    | Validates command arguments and runs the pipeline                     |
-| `tubeless history` | An optional run id                  | Lists or shows recorded runs from SQLite or a finished NDJSON trace   |
-| `tubeless ui`      | An optional project/Studio manifest | Serves the local run studio; see [studio](./studio.md)                |
+### Authoring API
+
+Import terminal commands from `tubeless/cli` and project declarations from
+`tubeless/project`:
+
+```ts
+import { defineCommand, definePipelineCommand } from "tubeless/cli";
+import { definePipelineProject } from "tubeless/project";
+```
+
+Use `defineCommand` for a standalone script and `definePipelineCommand` for a
+pipeline-backed command with built-in selection, dry runs and terminal reporting.
+Both expose typed parsing, validation, descriptors and execution. Their public
+configuration, parameter, result and hook types live on the CLI subpath.
+Import `PipelineReporterConfig` from `tubeless/cli` to share reporter settings
+between commands. Its mode, output stream, color, symbols and terminal-capability
+types are exported there too. CLI declarations do not require `@types/node`;
+`CliContext.env` accepts a record of string or undefined values.
+
+Use `definePipelineProject` in `tubeless.project.ts` to register command modules
+with stable IDs. A project catalog is shared by the terminal and Studio; declaring
+one does not load its command modules or start either interface.
+
+| Layer   | Public entry       | Responsibility                                                       |
+| ------- | ------------------ | -------------------------------------------------------------------- |
+| Core    | `tubeless`         | Typed graphs, planning, execution, hooks and run reports             |
+| CLI     | `tubeless/cli`     | Standalone and pipeline commands, typed flags and terminal execution |
+| Project | `tubeless/project` | Project catalogs, command IDs and module registrations               |
+| Studio  | `tubeless ui`      | Optional browser interface for recorded runs and registered commands |
+
+Users interact with a project through the `tubeless` executable: `list` shows its
+commands, `plan` previews work, and `run` executes a command. `ui` opens Studio
+against the same catalog. There is no separate workbench application to start.
+Core pipelines and standalone CLI commands do not need a project catalog.
+
+Each authoring API has one public entrypoint. Neither the CLI nor the project
+catalog import loads storage or Studio. The executable supplies those optional
+integrations. Storage readers, Studio's server/protocol, terminal renderer
+internals and argument-parser internals remain private.
+
+Import optional filesystem, environment and checkpoint helpers from `tubeless/node`;
+see the [Node helpers recipe](./recipes.md#node-helpers). Application-specific
+selection prompts belong in the application.
+
+### Executable commands
+
+| Command             | Accepts                             | Does                                                                  |
+| ------------------- | ----------------------------------- | --------------------------------------------------------------------- |
+| `tubeless list`     | A project manifest                  | Lists explicitly registered command IDs without loading their modules |
+| `tubeless validate` | A YAML or JSON pipeline document    | Checks document structure and metadata without loading handlers       |
+| `tubeless inspect`  | A pipeline or command export        | Shows the pipeline ID, available targets, steps, and default plan     |
+| `tubeless plan`     | A pipeline or command export        | Previews selection without executing or requiring domain options      |
+| `tubeless graph`    | A pipeline or command export        | Writes Mermaid flowchart source                                       |
+| `tubeless run`      | A `definePipelineCommand` export    | Validates command arguments and runs the pipeline                     |
+| `tubeless history`  | An optional run id                  | Lists or shows recorded runs from SQLite or a finished NDJSON trace   |
+| `tubeless ui`       | An optional project/Studio manifest | Serves the local run studio; see [studio](./studio.md)                |
+
+Use `tubeless validate [--json] pipelines.yaml` for a fast document-only check.
+It supports `.yaml`, `.yml`, and `.json`; it does not resolve handlers, check the
+graph, or run domain schemas. See [declarative pipelines](./declarative-pipelines.md)
+for the downloadable JSON Schema and validation levels.
 
 Use a checked-in `tubeless.project.ts` to address commands by stable project ID: