@dailephd/my-dev-kit-lab 0.4.4 → 0.4.6

package/dist/src/audits/core/typescriptJavaScriptAnalyzer.js

@@ -1,4 +1,3 @@
-import ts from "typescript";
 // ---------------------------------------------------------------------------
 // v0.3.1 Batch 3 -- TypeScript/JavaScript source analyzer.
 //
@@ -36,7 +35,25 @@ export const TYPESCRIPT_JAVASCRIPT_ANALYZER = {
     supportedExtensions: SUPPORTED_EXTENSIONS,
     analyzeFile,
 };
-function analyzeFile(input) {
+// v0.4.6 Batch 5 -- the `typescript` package is a devDependency, not a
+// runtime dependency: an installed my-dev-kit-lab consumer does not have it.
+// The compiler API is loaded lazily (once, memoized) only when a file is
+// actually analyzed, rather than imported at module scope, so merely
+// loading this module (which happens on every CLI invocation, since the
+// language analyzer registry is wired in unconditionally) never requires
+// `typescript` to be present. Only the *type* import above is needed at the
+// top level -- type-only imports are erased entirely at compile time.
+let cachedTypeScriptModule;
+async function loadTypeScript() {
+    if (!cachedTypeScriptModule) {
+        const imported = await import("typescript");
+        cachedTypeScriptModule =
+            imported.default ??
+                imported;
+    }
+    return cachedTypeScriptModule;
+}
+async function analyzeFile(input) {
     const { relativePath, language, role, content, inventoryEntry } = input;
     if (Buffer.byteLength(content, "utf8") > MAX_ANALYZABLE_BYTES) {
         return {
@@ -61,17 +78,18 @@ function analyzeFile(input) {
             ],
         };
     }
-    const scriptKind = resolveScriptKind(inventoryEntry.extension);
+    const ts = await loadTypeScript();
+    const scriptKind = resolveScriptKind(ts, inventoryEntry.extension);
     const sourceFile = ts.createSourceFile(relativePath, content, ts.ScriptTarget.Latest, true, scriptKind);
-    const diagnostics = getSyntaxDiagnostics(relativePath, sourceFile);
+    const diagnostics = getSyntaxDiagnostics(ts, relativePath, sourceFile);
     const imports = [];
     const exports = [];
     const declarations = [];
     const references = [];
     const lineOf = (node) => sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
     function pushDeclaration(node, name, kind) {
-        const isExported = hasModifier(node, ts.SyntaxKind.ExportKeyword);
-        const isDefault = hasModifier(node, ts.SyntaxKind.DefaultKeyword);
+        const isExported = hasModifier(ts, node, ts.SyntaxKind.ExportKeyword);
+        const isDefault = hasModifier(ts, node, ts.SyntaxKind.DefaultKeyword);
         if (name) {
             declarations.push({ name, kind, exported: isExported, line: lineOf(node) });
         }
@@ -141,7 +159,7 @@ function analyzeFile(input) {
         exports.push({ name, kind: "default", line: lineOf(node) });
     }
     function handleVariableStatement(node) {
-        const isExported = hasModifier(node, ts.SyntaxKind.ExportKeyword);
+        const isExported = hasModifier(ts, node, ts.SyntaxKind.ExportKeyword);
         const isConst = (node.declarationList.flags & ts.NodeFlags.Const) !== 0;
         for (const decl of node.declarationList.declarations) {
             // Destructuring patterns (`const { a, b } = x`) are conservatively
@@ -247,7 +265,7 @@ function analyzeFile(input) {
         diagnostics,
     };
 }
-function resolveScriptKind(extension) {
+function resolveScriptKind(ts, extension) {
     switch (extension) {
         case ".tsx":
             return ts.ScriptKind.TSX;
@@ -264,7 +282,7 @@ function resolveScriptKind(extension) {
             return ts.ScriptKind.TS;
     }
 }
-function hasModifier(node, kind) {
+function hasModifier(ts, node, kind) {
     if (!ts.canHaveModifiers(node))
         return false;
     const modifiers = ts.getModifiers(node);
@@ -280,11 +298,11 @@ function hasModifier(node, kind) {
 // transpileModule() over this repo's own ~375 TS/JS files, which matters
 // because collectSourceFacts.ts calls this analyzer once per eligible file
 // on every audit run (including this repo's own self-audit).
-function getSyntaxDiagnostics(relativePath, sourceFile) {
+function getSyntaxDiagnostics(ts, relativePath, sourceFile) {
     const parseDiagnostics = sourceFile.parseDiagnostics ?? [];
-    return parseDiagnostics.map((diagnostic) => toSourceFactDiagnostic(relativePath, diagnostic));
+    return parseDiagnostics.map((diagnostic) => toSourceFactDiagnostic(ts, relativePath, diagnostic));
 }
-function toSourceFactDiagnostic(relativePath, diagnostic) {
+function toSourceFactDiagnostic(ts, relativePath, diagnostic) {
     const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
     const line = diagnostic.file && diagnostic.start !== undefined
         ? diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start).line + 1

package/dist/src/cli/help.js

@@ -0,0 +1,300 @@
+export function renderTopLevelHelp() {
+    return [
+        "my-dev-kit-lab - benchmark, evidence, and evaluation companion for my-dev-kit.",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab --help",
+        "  my-dev-kit-lab --version",
+        "  my-dev-kit-lab [--workspace <path>] security validate [options]",
+        "  my-dev-kit-lab [--workspace <path>] audit [options]",
+        "  my-dev-kit-lab [--workspace <path>] experiment list",
+        "  my-dev-kit-lab [--workspace <path>] experiment describe --experiment <id>",
+        "  my-dev-kit-lab [--workspace <path>] experiment run --experiment <id> [options]",
+        "  my-dev-kit-lab [--workspace <path>] experiment controlled --cases <path> --out <dir> [options]",
+        "  my-dev-kit-lab [--workspace <path>] report render --experiment <dir> --out <dir> [options]",
+        "  my-dev-kit-lab [--workspace <path>] plots generate --experiment <dir> --out <dir>",
+        "  my-dev-kit-lab [--workspace <path>] gallery build --out <dir> [options]",
+        "  my-dev-kit-lab demo final --cases <path> --out <dir> --kit-command <command> [options]",
+        "",
+        "Options:",
+        "  -h, --help           Show this help message",
+        "  -V, --version        Show the installed my-dev-kit-lab package version",
+        "  --workspace <path>   Writable my-dev-kit-lab workspace root (default: <home>/.my-dev-kit-lab).",
+        "                       Must appear before the command when used.",
+        "",
+        "Commands:",
+        "  security validate        Run security validation",
+        "  audit                    Run a project audit",
+        "  experiment list           List registered experiment plugins",
+        "  experiment describe       Describe a registered experiment plugin",
+        "  experiment run             Run a registered experiment plugin",
+        "  experiment controlled    Run a controlled context-strategy-comparison experiment",
+        "  report render             Render an experiment report from controlled-experiment artifacts",
+        "  plots generate             Generate experiment plot artifacts",
+        "  gallery build              Build a gallery manifest/index",
+        "  demo final                 Run the full final demo workflow",
+        "",
+        "Run \"my-dev-kit-lab <command> --help\" (or \"my-dev-kit-lab <family> <command> --help\") for details.",
+        "",
+        "Note: the historical direct invocation form (flags without \"demo final\", e.g.",
+        "\"my-dev-kit-lab --cases <path> --out <dir> --kit-command <command>\") remains",
+        "supported for backward compatibility."
+    ].join("\n");
+}
+export function renderDemoHelp() {
+    return [
+        "my-dev-kit-lab demo - demo command family",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab demo final [options]",
+        "  my-dev-kit-lab demo --help",
+        "",
+        "Commands:",
+        "  final   Run the full final demo. Run \"my-dev-kit-lab demo final --help\" for details."
+    ].join("\n");
+}
+export function renderFinalDemoHelp() {
+    return [
+        "my-dev-kit-lab demo final - run the full final demo workflow",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab demo final --cases <path> --out <dir> --kit-command <command> [options]",
+        "",
+        "Required:",
+        "  --cases <path>            Path to the evaluation cases file",
+        "  --out <dir>               Output directory for demo artifacts",
+        "  --kit-command <command>   Command used to invoke my-dev-kit for the visualization demos",
+        "",
+        "Options:",
+        "  --agents <list>                                    Comma-separated agent ids (default: fake-agent)",
+        "  --strategies <list>                                Comma-separated strategies: raw-full-file,my-dev-kit-guided (default: both)",
+        "  --complexities <list>                               Comma-separated complexity levels: short,medium,long,multi-step (default: short)",
+        "  --case <ids>                                       Comma-separated case ids to run",
+        "  --benchmark-project <ids>                          Comma-separated benchmark project ids to run",
+        "  --max-runs <n>                                     Maximum number of runs",
+        "  --screenshot / --no-screenshot                     Enable/disable report screenshot capture (default: disabled)",
+        "  --include-real-agents                              Allow real agent ids (codex, claude)",
+        "  --continue-on-failure / --no-continue-on-failure   Continue after a failed run (default: continue-on-failure)",
+        "  --timeout-ms <ms>                                  Per-run timeout in milliseconds",
+        "",
+        "The legacy direct invocation form (the same flags without a leading \"demo final\")",
+        "remains supported for backward compatibility."
+    ].join("\n");
+}
+export function renderExperimentHelp() {
+    return [
+        "my-dev-kit-lab experiment - experiment command family",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab experiment list",
+        "  my-dev-kit-lab experiment describe --experiment <id>",
+        "  my-dev-kit-lab experiment run --experiment <id> [options]",
+        "  my-dev-kit-lab experiment controlled [options]",
+        "  my-dev-kit-lab experiment --help",
+        "",
+        "Commands:",
+        "  list         List registered experiment plugins.",
+        "               Run \"my-dev-kit-lab experiment list --help\" for details.",
+        "  describe     Describe a registered experiment plugin.",
+        "               Run \"my-dev-kit-lab experiment describe --help\" for details.",
+        "  run          Run a registered experiment plugin through the generic runner.",
+        "               Run \"my-dev-kit-lab experiment run --help\" for details.",
+        "  controlled   Run a controlled context-strategy-comparison experiment.",
+        "               Run \"my-dev-kit-lab experiment controlled --help\" for details."
+    ].join("\n");
+}
+export function renderExperimentListHelp() {
+    return [
+        "my-dev-kit-lab experiment list - list registered experiment plugins",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab experiment list [--json]",
+        "",
+        "Options:",
+        "  --json   Print the experiment list as JSON instead of a human-readable summary"
+    ].join("\n");
+}
+export function renderExperimentDescribeHelp() {
+    return [
+        "my-dev-kit-lab experiment describe - describe a registered experiment plugin",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab experiment describe --experiment <id> [--json]",
+        "",
+        "Required:",
+        "  --experiment <id>   Registered experiment plugin id (see \"my-dev-kit-lab experiment list\")",
+        "",
+        "Options:",
+        "  --json   Print the description as JSON instead of a human-readable summary"
+    ].join("\n");
+}
+export function renderExperimentRunHelp() {
+    return [
+        "my-dev-kit-lab experiment run - run a registered experiment plugin through the generic runner",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab experiment run --experiment <id> [options]",
+        "",
+        "Required:",
+        "  --experiment <id>   Registered experiment plugin id (see \"my-dev-kit-lab experiment list\")",
+        "",
+        "Options:",
+        "  --target <path>                                    Local target project path (default: self)",
+        "  --out <dir>                                         Output directory for experiment artifacts",
+        "                                                      (default: beneath the workspace when installed)",
+        "  --cases <path>                                      Path to the evaluation cases file",
+        "                                                      (default: the bundled package resource)",
+        "  --project-profiles <path>                          Path to the benchmark project profiles file",
+        "                                                      (default: the bundled package resource)",
+        "  --case <ids>                                       Comma-separated case ids to run",
+        "  --benchmark-project <ids>                          Comma-separated benchmark project ids to run",
+        "  --agents <list>                                    Comma-separated agent ids (default: fake-agent)",
+        "  --strategies <list>                                Comma-separated strategies: raw-full-file,my-dev-kit-guided",
+        "  --complexities <list>                               Comma-separated complexity levels: short,medium,long,multi-step",
+        "  --timeout-ms <ms>                                  Per-run timeout in milliseconds",
+        "  --max-runs <n>                                     Maximum number of runs",
+        "  --continue-on-failure / --no-continue-on-failure   Continue after a failed run (default: continue-on-failure)",
+        "  --require-agents                                   Fail if no real agent command templates are configured",
+        "  --include-real-agents                              Allow real agent ids (codex, claude)",
+        "  --command-template-codex <template>                Command template used to invoke the codex agent",
+        "  --command-template-claude <template>               Command template used to invoke the claude agent",
+        "  --no-screenshot                                     Accepted for compatibility; the plugin-aware report",
+        "                                                      path does not capture screenshots yet"
+    ].join("\n");
+}
+export function renderExperimentControlledHelp() {
+    return [
+        "my-dev-kit-lab experiment controlled - run a controlled context-strategy-comparison experiment",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab experiment controlled --cases <path> --out <dir> [options]",
+        "",
+        "Required:",
+        "  --cases <path>   Path to the evaluation cases file",
+        "  --out <dir>      Output directory for experiment artifacts",
+        "",
+        "Options:",
+        "  --project-profiles <path>                          Path to the benchmark project profiles file",
+        "                                                      (default: the bundled package resource)",
+        "  --case <ids>                                       Comma-separated case ids to run",
+        "  --benchmark-project <ids>                          Comma-separated benchmark project ids to run",
+        "  --agents <list>                                    Comma-separated agent ids (default: fake-agent)",
+        "  --strategies <list>                                Comma-separated strategies: raw-full-file,my-dev-kit-guided",
+        "  --complexities <list>                               Comma-separated complexity levels: short,medium,long,multi-step",
+        "  --timeout-ms <ms>                                  Per-run timeout in milliseconds",
+        "  --max-runs <n>                                     Maximum number of runs",
+        "  --continue-on-failure / --no-continue-on-failure   Continue after a failed run (default: continue-on-failure)",
+        "  --require-agents                                   Fail if no real agent command templates are configured",
+        "  --include-real-agents                              Allow real agent ids (codex, claude)",
+        "  --command-template-codex <template>                Command template used to invoke the codex agent",
+        "  --command-template-claude <template>               Command template used to invoke the claude agent"
+    ].join("\n");
+}
+export function renderReportHelp() {
+    return [
+        "my-dev-kit-lab report - report command family",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab report render [options]",
+        "  my-dev-kit-lab report --help",
+        "",
+        "Commands:",
+        "  render   Render an HTML/JSON experiment report from controlled-experiment artifacts.",
+        "           Run \"my-dev-kit-lab report render --help\" for details."
+    ].join("\n");
+}
+export function renderReportRenderHelp() {
+    return [
+        "my-dev-kit-lab report render - render an HTML/JSON experiment report from controlled-experiment artifacts",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab report render --experiment <dir> --out <dir> [options]",
+        "",
+        "Required:",
+        "  --experiment <dir>   Path to a controlled-experiment output directory",
+        "  --out <dir>          Output directory for the rendered report",
+        "",
+        "Options:",
+        "  --title <title>                    Report title",
+        "  --subtitle <subtitle>               Report subtitle",
+        "  --screenshot / --no-screenshot      Enable/disable PNG screenshot capture (default: disabled)",
+        "  --require-screenshot                Fail unless a screenshot was captured (implies --screenshot)",
+        "  --max-prompt-chars <n>              Maximum characters of prompt text to include",
+        "  --max-file-tree-entries <n>         Maximum file tree entries to include",
+        "  --plots <dir>                       Optional plots directory to include in the report",
+        "  --visualizations <dir>              Optional visualization-demos directory to include in the report"
+    ].join("\n");
+}
+export function renderPlotsHelp() {
+    return [
+        "my-dev-kit-lab plots - plots command family",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab plots generate [options]",
+        "  my-dev-kit-lab plots --help",
+        "",
+        "Commands:",
+        "  generate   Generate experiment plot artifacts from controlled-experiment artifacts.",
+        "             Run \"my-dev-kit-lab plots generate --help\" for details."
+    ].join("\n");
+}
+export function renderPlotsGenerateHelp() {
+    return [
+        "my-dev-kit-lab plots generate - generate chart/plot artifacts from controlled-experiment artifacts",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab plots generate --experiment <dir> --out <dir>",
+        "",
+        "Required:",
+        "  --experiment <dir>   Path to a controlled-experiment output directory",
+        "  --out <dir>          Output directory for plot artifacts"
+    ].join("\n");
+}
+export function renderGalleryHelp() {
+    return [
+        "my-dev-kit-lab gallery - gallery command family",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab gallery build [options]",
+        "  my-dev-kit-lab gallery --help",
+        "",
+        "Commands:",
+        "  build   Build a gallery manifest/index from report, plots, and visualization artifacts.",
+        "          Run \"my-dev-kit-lab gallery build --help\" for details."
+    ].join("\n");
+}
+export function renderGalleryBuildHelp() {
+    return [
+        "my-dev-kit-lab gallery build - build a gallery manifest/index from existing artifacts",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab gallery build --out <dir> [options]",
+        "",
+        "Required:",
+        "  --out <dir>   Output directory for the gallery manifest and index",
+        "",
+        "Options:",
+        "  --report <dir>           Path to a rendered report directory",
+        "  --plots <dir>            Path to a plots output directory",
+        "  --visualizations <dir>   Path to a visualization-demos output directory",
+        "  --experiment <dir>       Path to a controlled-experiment output directory"
+    ].join("\n");
+}
+export function renderSecurityHelp() {
+    return [
+        "my-dev-kit-lab security - security command family",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab security validate [options]",
+        "  my-dev-kit-lab security --help",
+        "",
+        "Commands:",
+        "  validate   Run security validation. Run \"my-dev-kit-lab security validate --help\" for details."
+    ].join("\n");
+}
+export function renderUnknownCommandError(command) {
+    return [
+        `Unknown command: ${command}`,
+        "Run \"my-dev-kit-lab --help\" for usage."
+    ].join("\n");
+}

package/dist/src/cli/index.js

@@ -0,0 +1,2 @@
+export * from "./runLabCli.js";
+export * from "./help.js";

package/dist/src/cli/runLabCli.js

@@ -0,0 +1,229 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { runFinalDemoCommand } from "../commands/runFinalDemoCommand.js";
+import { runAuditCommandFromArgs } from "../commands/runAuditCommand.js";
+import { runSecurityValidationCommandFromArgs } from "../commands/runSecurityValidationCommand.js";
+import { runControlledExperimentCommand } from "../commands/runControlledExperimentCommand.js";
+import { runExperimentListCommandFromArgs } from "../commands/runExperimentListCommand.js";
+import { runExperimentDescribeCommandFromArgs } from "../commands/runExperimentDescribeCommand.js";
+import { runExperimentRunCommandFromArgs } from "../commands/runExperimentRunCommand.js";
+import { runRenderExperimentReportCommand } from "../commands/renderExperimentReportCommand.js";
+import { runGenerateExperimentPlotsCommand } from "../commands/generateExperimentPlotsCommand.js";
+import { runBuildGalleryCommand } from "../commands/buildGalleryCommand.js";
+import { createLabExecutionContext, discoverPackageRoot } from "../runtime/index.js";
+import { renderDemoHelp, renderExperimentControlledHelp, renderExperimentDescribeHelp, renderExperimentHelp, renderExperimentListHelp, renderExperimentRunHelp, renderFinalDemoHelp, renderGalleryBuildHelp, renderGalleryHelp, renderPlotsGenerateHelp, renderPlotsHelp, renderReportHelp, renderReportRenderHelp, renderSecurityHelp, renderTopLevelHelp, renderUnknownCommandError } from "./help.js";
+export const CLI_USAGE_EXIT_CODE = 2;
+/**
+ * Recognized legacy final-demo flag tokens (mirrors parseRunFinalDemoArgs in
+ * src/commands/runFinalDemoCommand.ts). Used only to detect the historical
+ * direct invocation form; the legacy argument list itself is delegated to the
+ * existing final-demo parser unchanged, never reinterpreted here.
+ */
+const LEGACY_FINAL_DEMO_FLAGS = new Set([
+    "--cases",
+    "--out",
+    "--kit-command",
+    "--agents",
+    "--strategies",
+    "--complexities",
+    "--case",
+    "--benchmark-project",
+    "--max-runs",
+    "--screenshot",
+    "--no-screenshot",
+    "--include-real-agents",
+    "--continue-on-failure",
+    "--no-continue-on-failure",
+    "--timeout-ms"
+]);
+const DEFAULT_WRITERS = {
+    stdout: (message) => {
+        console.log(message);
+    },
+    stderr: (message) => {
+        console.error(message);
+    }
+};
+export async function runLabCli(argv, options = {}) {
+    const writers = options.writers ?? DEFAULT_WRITERS;
+    const globalOptions = parseGlobalOptions(argv);
+    if (!globalOptions.ok) {
+        writers.stderr(globalOptions.error);
+        return CLI_USAGE_EXIT_CODE;
+    }
+    const remaining = globalOptions.remaining;
+    const context = createLabExecutionContext(globalOptions.workspaceRoot !== undefined ? { workspaceRoot: globalOptions.workspaceRoot } : {});
+    const [command, ...rest] = remaining;
+    if (remaining.length === 0 || command === "--help" || command === "-h") {
+        writers.stdout(renderTopLevelHelp());
+        return 0;
+    }
+    if (command === "--version" || command === "-V") {
+        writers.stdout(readPackageVersion());
+        return 0;
+    }
+    if (command === "security") {
+        return runSecurityFamily(rest, writers, context);
+    }
+    if (command === "audit") {
+        return runAuditCommandFromArgs(rest, { context, defaultOutRoot: context.workspaceRoot });
+    }
+    if (command === "experiment") {
+        return runExperimentFamily(rest, writers, context);
+    }
+    if (command === "report") {
+        return runReportFamily(rest, writers);
+    }
+    if (command === "plots") {
+        return runPlotsFamily(rest, writers);
+    }
+    if (command === "gallery") {
+        return runGalleryFamily(rest, writers);
+    }
+    if (command === "demo") {
+        return runDemoCommand(rest, writers);
+    }
+    if (LEGACY_FINAL_DEMO_FLAGS.has(command)) {
+        return runFinalDemoCommand(remaining);
+    }
+    writers.stderr(renderUnknownCommandError(command));
+    return CLI_USAGE_EXIT_CODE;
+}
+/**
+ * Only recognizes a leading "--workspace <path>" pair (must be argv[0]).
+ * A --workspace token appearing anywhere else is left untouched for normal
+ * command/legacy routing to handle (or reject), per the batch requirement
+ * that global options must precede the command.
+ */
+function parseGlobalOptions(argv) {
+    if (argv[0] !== "--workspace") {
+        return { ok: true, remaining: argv };
+    }
+    const value = argv[1];
+    if (value === undefined) {
+        return { ok: false, error: "Missing value for --workspace. Expected a path after --workspace." };
+    }
+    return { ok: true, workspaceRoot: value, remaining: argv.slice(2) };
+}
+async function runDemoCommand(argv, writers) {
+    const [subcommand, ...rest] = argv;
+    if (argv.length === 0 || subcommand === "--help" || subcommand === "-h") {
+        writers.stdout(renderDemoHelp());
+        return 0;
+    }
+    if (subcommand === "final") {
+        if (rest[0] === "--help" || rest[0] === "-h") {
+            writers.stdout(renderFinalDemoHelp());
+            return 0;
+        }
+        return runFinalDemoCommand(rest);
+    }
+    writers.stderr(renderUnknownCommandError(`demo ${subcommand}`));
+    return CLI_USAGE_EXIT_CODE;
+}
+async function runSecurityFamily(argv, writers, context) {
+    const [subcommand, ...rest] = argv;
+    if (argv.length === 0 || subcommand === "--help" || subcommand === "-h") {
+        writers.stdout(renderSecurityHelp());
+        return 0;
+    }
+    if (subcommand === "validate") {
+        return runSecurityValidationCommandFromArgs(rest, { context, defaultOutRoot: context.workspaceRoot });
+    }
+    writers.stderr(renderUnknownCommandError(`security ${subcommand}`));
+    return CLI_USAGE_EXIT_CODE;
+}
+async function runExperimentFamily(argv, writers, context) {
+    const [subcommand, ...rest] = argv;
+    if (argv.length === 0 || subcommand === "--help" || subcommand === "-h") {
+        writers.stdout(renderExperimentHelp());
+        return 0;
+    }
+    if (subcommand === "list") {
+        if (rest[0] === "--help" || rest[0] === "-h") {
+            writers.stdout(renderExperimentListHelp());
+            return 0;
+        }
+        return runExperimentListCommandFromArgs(rest);
+    }
+    if (subcommand === "describe") {
+        if (rest[0] === "--help" || rest[0] === "-h") {
+            writers.stdout(renderExperimentDescribeHelp());
+            return 0;
+        }
+        return runExperimentDescribeCommandFromArgs(rest);
+    }
+    if (subcommand === "run") {
+        if (rest[0] === "--help" || rest[0] === "-h") {
+            writers.stdout(renderExperimentRunHelp());
+            return 0;
+        }
+        return runExperimentRunCommandFromArgs(rest, { context, installedDefaultOutputRoot: context.workspaceRoot });
+    }
+    if (subcommand === "controlled") {
+        if (rest[0] === "--help" || rest[0] === "-h") {
+            writers.stdout(renderExperimentControlledHelp());
+            return 0;
+        }
+        return runControlledExperimentCommand(rest);
+    }
+    writers.stderr(renderUnknownCommandError(`experiment ${subcommand}`));
+    return CLI_USAGE_EXIT_CODE;
+}
+async function runReportFamily(argv, writers) {
+    const [subcommand, ...rest] = argv;
+    if (argv.length === 0 || subcommand === "--help" || subcommand === "-h") {
+        writers.stdout(renderReportHelp());
+        return 0;
+    }
+    if (subcommand === "render") {
+        if (rest[0] === "--help" || rest[0] === "-h") {
+            writers.stdout(renderReportRenderHelp());
+            return 0;
+        }
+        return runRenderExperimentReportCommand(rest);
+    }
+    writers.stderr(renderUnknownCommandError(`report ${subcommand}`));
+    return CLI_USAGE_EXIT_CODE;
+}
+async function runPlotsFamily(argv, writers) {
+    const [subcommand, ...rest] = argv;
+    if (argv.length === 0 || subcommand === "--help" || subcommand === "-h") {
+        writers.stdout(renderPlotsHelp());
+        return 0;
+    }
+    if (subcommand === "generate") {
+        if (rest[0] === "--help" || rest[0] === "-h") {
+            writers.stdout(renderPlotsGenerateHelp());
+            return 0;
+        }
+        return runGenerateExperimentPlotsCommand(rest);
+    }
+    writers.stderr(renderUnknownCommandError(`plots ${subcommand}`));
+    return CLI_USAGE_EXIT_CODE;
+}
+async function runGalleryFamily(argv, writers) {
+    const [subcommand, ...rest] = argv;
+    if (argv.length === 0 || subcommand === "--help" || subcommand === "-h") {
+        writers.stdout(renderGalleryHelp());
+        return 0;
+    }
+    if (subcommand === "build") {
+        if (rest[0] === "--help" || rest[0] === "-h") {
+            writers.stdout(renderGalleryBuildHelp());
+            return 0;
+        }
+        return runBuildGalleryCommand(rest);
+    }
+    writers.stderr(renderUnknownCommandError(`gallery ${subcommand}`));
+    return CLI_USAGE_EXIT_CODE;
+}
+function readPackageVersion() {
+    const packageRoot = discoverPackageRoot();
+    const packageJsonPath = path.join(packageRoot, "package.json");
+    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    if (typeof parsed.version !== "string" || parsed.version.length === 0) {
+        throw new Error(`Unable to read a valid version from ${packageJsonPath}`);
+    }
+    return parsed.version;
+}