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

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;
+}

package/dist/src/commands/runAuditCommand.js

@@ -0,0 +1,132 @@
+import { parseAuditArgs, normalizeAuditConfig } from "../audits/core/auditConfig.js";
+import { resolveAuditTarget } from "../audits/core/auditTarget.js";
+import { runAudit } from "../audits/core/auditRunner.js";
+import { AUDIT_EXIT_CODES } from "../audits/core/auditExitCode.js";
+import { buildAuditReportModel } from "../audits/report/auditReportModel.js";
+import { writeAuditReports } from "../audits/report/writeAuditReports.js";
+import { createLabExecutionContext } from "../runtime/index.js";
+// ---------------------------------------------------------------------------
+// v0.4.6 Batch 3 -- reusable audit command owner.
+//
+// Extracted from scripts/audits/runAudit.ts (formerly a top-level script
+// with inline try/catch + process.exit()) so both the contributor npm
+// script and the installed CLI router (src/cli/) can call the same
+// argument-parsing/target-resolution/report-writing path instead of
+// maintaining two implementations. Detector/severity/report-schema policy
+// is untouched -- this module only owns CLI argument handling, target
+// resolution, the runAudit() call, report writing, and exit-code mapping.
+// ---------------------------------------------------------------------------
+export const AUDIT_USAGE = "Usage: my-dev-kit-lab audit [--target <path>] [--types code-rot,security] " +
+    "[--include docs,tests,package,architecture,cli] [--format text,json] " +
+    "[--fail-on blocker|high|medium|low|none] [--out <path>] [--android]\n" +
+    "\n" +
+    "  --android opts into Batch 2's programmatic Android security integration.\n" +
+    "  Requires --types to include \"security\" (e.g. --types security or --types\n" +
+    "  code-rot,security). Runs the same static, read-only, nineteen-check\n" +
+    "  Android validation security:validate --profile android performs --\n" +
+    "  detection, manifest parsing, and internal advanced security checks --\n" +
+    "  through the existing security adapter, never a subprocess. Confirmed\n" +
+    "  findings are mapped into the normal issue collection; CandidateEvidence\n" +
+    "  remains a separate, bounded summary and is never treated as a confirmed\n" +
+    "  issue. Starts zero Gradle operations, zero external tools, and zero\n" +
+    "  network operations by default; --android does not expose any of those.\n" +
+    "  Example: my-dev-kit-lab audit --target \"<android-project-path>\" --types security --android --format text,json --fail-on none";
+export async function runAuditCommandFromArgs(argv, options = {}) {
+    const context = options.context ?? createLabExecutionContext();
+    const toolRoot = context.packageRoot;
+    const defaultOutRoot = options.defaultOutRoot ?? toolRoot;
+    // Help deliberately wins over every other argument, mirroring
+    // scripts/security/validate.ts -- no config normalization, target
+    // resolution, audit execution, or report write.
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(AUDIT_USAGE);
+        return AUDIT_EXIT_CODES.SUCCESS;
+    }
+    let config;
+    try {
+        const args = parseAuditArgs(argv);
+        config = normalizeAuditConfig(args, defaultOutRoot);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`\nERROR: ${msg}`);
+        console.error(AUDIT_USAGE);
+        return AUDIT_EXIT_CODES.FATAL_ERROR;
+    }
+    let target;
+    try {
+        target = resolveAuditTarget(config.targetPathArg, toolRoot);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`\nERROR: ${msg}`);
+        console.error(AUDIT_USAGE);
+        return AUDIT_EXIT_CODES.FATAL_ERROR;
+    }
+    console.log("=".repeat(60));
+    console.log("my-dev-kit-lab audit");
+    console.log("=".repeat(60));
+    console.log(`Tool root  : ${toolRoot}`);
+    if (!target.isSelf) {
+        console.log(`Target     : ${target.rootPath}`);
+    }
+    else {
+        console.log(`Mode       : self-audit`);
+    }
+    console.log(`Types      : ${config.types.join(", ")}`);
+    console.log(`Include    : ${config.include.join(", ")}`);
+    console.log("");
+    let result;
+    try {
+        result = await runAudit({ config, toolRoot, target });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`\nERROR: audit runtime failure: ${msg}`);
+        return AUDIT_EXIT_CODES.FATAL_ERROR;
+    }
+    const model = buildAuditReportModel(result, { target });
+    const { writtenPaths } = writeAuditReports({ model, config, outDir: config.out });
+    console.log(`Issues found        : ${model.summary.totalIssues}`);
+    console.log(`  blocker=${model.summary.issuesBySeverity.blocker} high=${model.summary.issuesBySeverity.high} medium=${model.summary.issuesBySeverity.medium} low=${model.summary.issuesBySeverity.low} info=${model.summary.issuesBySeverity.info}`);
+    console.log(`Skipped detectors    : ${model.summary.skippedDetectorCount}`);
+    if (model.summary.detectorErrorCount > 0) {
+        console.log(`Detector errors      : ${model.summary.detectorErrorCount}`);
+        for (const e of model.detectorErrors) {
+            console.log(`  [${e.id}] ${e.message}`);
+        }
+    }
+    if (model.summary.noDetectorsRegistered && !model.securitySummary.ran) {
+        console.log(`Note: no code-rot detectors are registered for this run's --types/--include selection -- this run collected inventory/source-of-truth data only.`);
+    }
+    if (model.securitySummary.ran) {
+        console.log(`\nSecurity validation: verdict=${model.securitySummary.verdictLabel} checks=${model.securitySummary.totalChecks} findings(blocker=${model.securitySummary.findingCounts.blocker} major=${model.securitySummary.findingCounts.major} minor=${model.securitySummary.findingCounts.minor} info=${model.securitySummary.findingCounts.informational})`);
+        if (model.securitySummary.reportPaths.text) {
+            console.log(`  Full report: ${model.securitySummary.reportPaths.text}`);
+        }
+    }
+    if (model.androidSecurity.summary.requested) {
+        const android = model.androidSecurity.summary;
+        console.log(`\nAndroid security validation: status=${android.status} applicable=${android.applicable ?? "n/a"} verdict=${android.verdict ?? "(unknown)"} checks=${android.totalChecks} confirmed=${android.confirmedFindingCount} mappedIssues=${android.mappedIssueCount} candidates=${android.candidateSummary.totalCount}`);
+        if (android.reportPaths.text) {
+            console.log(`  Full report: ${android.reportPaths.text}`);
+        }
+    }
+    console.log(`\nInventory: ${model.inventory.totalScannedFileCount} file(s) scanned, ${model.inventory.skippedFileCount} skipped`);
+    console.log(`  source=${model.inventory.filesByCategory.source} tests=${model.inventory.filesByCategory.tests} docs=${model.inventory.filesByCategory.docs} package=${model.inventory.filesByCategory.package} config=${model.inventory.filesByCategory.config} scripts=${model.inventory.filesByCategory.scripts} ci=${model.inventory.filesByCategory.ci}`);
+    console.log(`Source of truth: package=${model.sourceOfTruth.packageName ?? "(none)"}@${model.sourceOfTruth.packageVersion ?? "?"} readme=${model.sourceOfTruth.hasReadme} changelog=${model.sourceOfTruth.hasChangelog} ciWorkflows=${model.sourceOfTruth.ciWorkflowCount}`);
+    console.log(`Source facts: ${model.sourceFacts.totalFilesAnalyzed} file(s) analyzed (parsed=${model.sourceFacts.filesByParseStatus.parsed} file-level-only=${model.sourceFacts.filesByParseStatus["file-level-only"]} unsupported=${model.sourceFacts.filesByParseStatus.unsupported})`);
+    if (writtenPaths.length > 0) {
+        console.log(`\nReports written:`);
+        for (const p of writtenPaths) {
+            console.log(`  ${p}`);
+        }
+    }
+    console.log(`\nHighest severity: ${model.summary.highestSeverity ?? "(none)"}`);
+    console.log(`Verdict: ${model.summary.finalVerdictLabel}`);
+    console.log(`Exit reason: ${model.exit.reason}`);
+    console.log(model.exit.code === AUDIT_EXIT_CODES.SUCCESS
+        ? `Exit 0 -- audit completed.`
+        : `Exit 1 -- fail-on threshold breached.`);
+    return model.exit.code;
+}

package/dist/src/commands/runControlledExperimentCommand.js

@@ -4,9 +4,11 @@ import { parseAgentId } from "../agents/agentRegistry.js";
 import { readBenchmarkProjectProfiles, readEvaluationCases } from "../evaluation/index.js";
 import { contextStrategyComparisonPlugin, resolveExperimentTarget } from "../experiments/index.js";
 import { parsePromptComplexityLevel, parsePromptStrategy } from "../prompts/index.js";
+import { createLabExecutionContext, resolvePackageResource } from "../runtime/index.js";
+const DEFAULT_PROJECT_PROFILES_RESOURCE = "benchmarks/contracts/benchmark-project-profiles.json";
 export function parseRunControlledExperimentArgs(argv) {
     let casesPath = "";
-    let projectProfilesPath = "benchmarks/contracts/benchmark-project-profiles.json";
+    let projectProfilesPath;
     let outDir = "";
     const caseIds = [];
     const benchmarkProjects = [];
@@ -109,8 +111,10 @@ export function parseRunControlledExperimentArgs(argv) {
         includeRealAgents
     };
 }
-export async function runControlledExperimentFromArgs(args, repoRoot = process.cwd()) {
-    const projectProfilesPath = path.resolve(repoRoot, args.projectProfilesPath ?? "benchmarks/contracts/benchmark-project-profiles.json");
+export async function runControlledExperimentFromArgs(args, repoRoot = process.cwd(), context) {
+    const projectProfilesPath = args.projectProfilesPath
+        ? path.resolve(repoRoot, args.projectProfilesPath)
+        : resolvePackageResource(context ?? createLabExecutionContext(), DEFAULT_PROJECT_PROFILES_RESOURCE);
     const casesPath = path.resolve(repoRoot, args.casesPath);
     const projectProfiles = await readBenchmarkProjectProfiles(projectProfilesPath, repoRoot);
     const cases = await readEvaluationCases(casesPath, repoRoot, {

package/dist/{scripts/experiments/describeExperiment.js → src/commands/runExperimentDescribeCommand.js}

@@ -1,5 +1,12 @@
-import { createDefaultExperimentPluginRegistry } from "../../src/experiments/index.js";
-async function main(argv) {
+import { createDefaultExperimentPluginRegistry } from "../experiments/index.js";
+// ---------------------------------------------------------------------------
+// v0.4.6 Batch 4 -- reusable experiment-describe command owner.
+//
+// Extracted from scripts/experiments/describeExperiment.ts so both the npm
+// script and the installed CLI router call the same registry-lookup and
+// description-building path. Read-only: no filesystem writes.
+// ---------------------------------------------------------------------------
+export async function runExperimentDescribeCommandFromArgs(argv) {
     try {
         const args = parseDescribeArgs(argv);
         const registry = createDefaultExperimentPluginRegistry();
@@ -50,7 +57,7 @@ function buildDescription(plugin) {
         optionalConfigFields: readConfigFields(plugin, false),
         targetBehavior: describeTargetBehavior(plugin),
         expectedReports: describeExpectedReports(plugin),
-        examples: describeExamples(plugin),
+        examples: describeExamples(plugin)
     };
 }
 function printDescription(plugin) {
@@ -95,7 +102,7 @@ function readConfigFields(plugin, required) {
         .filter((field) => Boolean(field.required) === required)
         .map((field) => ({
         ...field,
-        defaultValue: readDefaultValue(plugin.defaultConfig, field.name),
+        defaultValue: readDefaultValue(plugin.defaultConfig, field.name)
     }));
 }
 function readSupportedVariants(plugin) {
@@ -133,11 +140,8 @@ function describeExpectedReports(plugin) {
 }
 function describeExamples(plugin) {
     return [
-        `npm run experiment:describe -- --experiment ${plugin.metadata.id}`,
-        `npm run experiment:run -- --experiment ${plugin.metadata.id} --agents fake-agent --complexities short`,
-        `npm run experiment:run -- --experiment ${plugin.metadata.id} --target "Z:\\Users\\newuser\\Projects\\my-dev-kit-v1" --agents fake-agent --complexities short --no-screenshot`,
+        `my-dev-kit-lab experiment describe --experiment ${plugin.metadata.id}`,
+        `my-dev-kit-lab experiment run --experiment ${plugin.metadata.id} --agents fake-agent --complexities short`,
+        `my-dev-kit-lab experiment run --experiment ${plugin.metadata.id} --target "Z:\\Users\\newuser\\Projects\\my-dev-kit-v1" --agents fake-agent --complexities short --no-screenshot`
     ];
 }
-if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replaceAll("\\", "/"))) {
-    process.exitCode = await main(process.argv.slice(2));
-}

package/dist/{scripts/experiments/listExperiments.js → src/commands/runExperimentListCommand.js}

@@ -1,5 +1,5 @@
-import { createDefaultExperimentPluginRegistry } from "../../src/experiments/index.js";
-async function main(argv) {
+import { createDefaultExperimentPluginRegistry } from "../experiments/index.js";
+export async function runExperimentListCommandFromArgs(argv) {
     const json = argv.includes("--json");
     const registry = createDefaultExperimentPluginRegistry();
     const plugins = registry.list().map((metadata) => {
@@ -25,7 +25,7 @@ async function main(argv) {
 function toListedExperiment(metadata, plugin) {
     return {
         ...metadata,
-        supportedVariants: readSupportedVariants(plugin),
+        supportedVariants: readSupportedVariants(plugin)
     };
 }
 function readSupportedVariants(plugin) {
@@ -39,6 +39,3 @@ function readArrayField(value, key) {
     const field = value[key];
     return Array.isArray(field) ? field : [];
 }
-if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replaceAll("\\", "/"))) {
-    process.exitCode = await main(process.argv.slice(2));
-}

package/dist/{scripts/experiments/runExperiment.js → src/commands/runExperimentRunCommand.js}

@@ -1,30 +1,65 @@
 import path from "node:path";
-import { parseAgentCommandTemplate } from "../../src/agents/index.js";
-import { parseAgentId } from "../../src/agents/agentRegistry.js";
-import { readBenchmarkProjectProfiles, readEvaluationCases } from "../../src/evaluation/index.js";
-import { createDefaultExperimentPluginRegistry, runExperiment } from "../../src/experiments/index.js";
-import { contextStrategyComparisonPlugin } from "../../src/experiments/plugins/contextStrategyComparison/index.js";
-import { parsePromptComplexityLevel, parsePromptStrategy } from "../../src/prompts/index.js";
-import { writePluginExperimentReports } from "../../src/report/index.js";
-async function main(argv) {
+import { parseAgentCommandTemplate } from "../agents/index.js";
+import { parseAgentId } from "../agents/agentRegistry.js";
+import { readBenchmarkProjectProfiles, readEvaluationCases } from "../evaluation/index.js";
+import { contextStrategyComparisonPlugin, createDefaultExperimentPluginRegistry, resolveExperimentTarget, runExperiment } from "../experiments/index.js";
+import { buildDefaultExperimentOutputRoot } from "../experiments/outputPaths.js";
+import { parsePromptComplexityLevel, parsePromptStrategy } from "../prompts/index.js";
+import { writePluginExperimentReports } from "../report/index.js";
+import { createLabExecutionContext, resolvePackageResource } from "../runtime/index.js";
+// ---------------------------------------------------------------------------
+// v0.4.6 Batch 4 -- reusable experiment-run command owner.
+//
+// Extracted from scripts/experiments/runExperiment.ts. Reuses the existing
+// generic runner (src/experiments/runner.ts) and the registered
+// context-strategy-comparison plugin unchanged. Two things move relative to
+// the source-checkout script:
+//
+// 1. Bundled resource lookup (the default cases/project-profiles files) goes
+//    through Batch 1's resolvePackageResource() instead of a
+//    process.cwd()-relative path, so it no longer depends on the checkout.
+// 2. The implicit (no --out) output root, for installed execution only, is
+//    rooted under workspaceRoot instead of the tool/package root -- computed
+//    with the same buildDefaultExperimentOutputRoot() helper the runner
+//    itself uses internally, so the plugin/target/run subdirectory shape is
+//    unchanged, only the root differs. Explicit --out is pre-resolved
+//    against invocationCwd so its resolution base never changes.
+//
+// Self-target fallback (no --target) and relative --target resolution are
+// untouched -- both still go through the shared toolRoot (packageRoot),
+// matching runAuditCommand.ts / runSecurityValidationCommand.ts.
+// ---------------------------------------------------------------------------
+const DEFAULT_CASES_RESOURCE = "examples/token-savings-cases.json";
+const DEFAULT_PROJECT_PROFILES_RESOURCE = "benchmarks/contracts/benchmark-project-profiles.json";
+export async function runExperimentRunCommandFromArgs(argv, options = {}) {
     try {
         const args = parseRunExperimentArgs(argv);
-        const toolRoot = process.cwd();
+        const context = options.context ?? createLabExecutionContext();
+        const toolRoot = context.packageRoot;
         const registry = createDefaultExperimentPluginRegistry();
-        const inputs = await loadPluginInputs(args, toolRoot);
+        const inputs = await loadPluginInputs(args, toolRoot, context);
+        const runId = generateExperimentRunId(args.experimentId);
+        const outputRoot = resolveOutputRoot(args, {
+            toolRoot,
+            invocationCwd: context.invocationCwd,
+            installedDefaultOutputRoot: options.installedDefaultOutputRoot,
+            experimentId: args.experimentId,
+            runId
+        });
         const result = await runExperiment({
             pluginId: args.experimentId,
             registry,
             targetPath: args.targetPath,
-            outputRoot: args.outDir,
+            outputRoot,
             config: args.config,
             inputs,
             toolRoot,
+            runId
         });
         const reports = await writePluginExperimentReports({
             run: result,
             plugin: registry.describe(result.pluginId),
-            outputRoot: String(result.metadata?.outputRoot ?? ""),
+            outputRoot: String(result.metadata?.outputRoot ?? "")
         });
         console.log([
             `Experiment: ${result.pluginId}`,
@@ -35,7 +70,7 @@ async function main(argv) {
             `Target root: ${result.target.targetRoot}`,
             `Output: ${String(result.metadata?.outputRoot ?? "")}`,
             `Report JSON: ${reports.outputPaths.jsonPath}`,
-            `Report HTML: ${reports.outputPaths.htmlPath}`,
+            `Report HTML: ${reports.outputPaths.htmlPath}`
         ].join("\n"));
         return result.status === "failed" ? 1 : 0;
     }
@@ -150,11 +185,33 @@ export function parseRunExperimentArgs(argv) {
             continueOnFailure,
             requireAgents,
             includeRealAgents,
-            commandTemplates: Object.keys(commandTemplates).length > 0 ? commandTemplates : undefined,
-        }),
+            commandTemplates: Object.keys(commandTemplates).length > 0 ? commandTemplates : undefined
+        })
     };
 }
-async function loadPluginInputs(args, toolRoot) {
+function resolveOutputRoot(args, params) {
+    if (args.outDir) {
+        // Pre-resolve to an absolute path against invocationCwd so its
+        // resolution base never depends on toolRoot/packageRoot.
+        return path.resolve(params.invocationCwd, args.outDir);
+    }
+    if (!params.installedDefaultOutputRoot) {
+        // Preserve the runner's own internal toolRoot-relative default.
+        return undefined;
+    }
+    const target = resolveExperimentTarget(args.targetPath, params.toolRoot);
+    return buildDefaultExperimentOutputRoot({
+        toolRoot: params.installedDefaultOutputRoot,
+        pluginId: params.experimentId,
+        target,
+        runId: params.runId
+    });
+}
+function generateExperimentRunId(pluginId) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return `${pluginId}-${timestamp}`;
+}
+async function loadPluginInputs(args, toolRoot, context) {
     if (args.experimentId !== contextStrategyComparisonPlugin.metadata.id) {
         return undefined;
     }
@@ -162,12 +219,16 @@ async function loadPluginInputs(args, toolRoot) {
     if (!validation.valid || !validation.config) {
         throw new Error(`Invalid context strategy comparison config: ${validation.errors.join("; ")}`);
     }
-    const projectProfilesPath = path.resolve(toolRoot, validation.config.projectProfilesPath ?? "benchmarks/contracts/benchmark-project-profiles.json");
-    const casesPath = path.resolve(toolRoot, validation.config.casesPath);
+    const projectProfilesPath = args.config.projectProfilesPath
+        ? path.resolve(toolRoot, args.config.projectProfilesPath)
+        : resolvePackageResource(context, DEFAULT_PROJECT_PROFILES_RESOURCE);
+    const casesPath = args.config.casesPath
+        ? path.resolve(toolRoot, args.config.casesPath)
+        : resolvePackageResource(context, DEFAULT_CASES_RESOURCE);
     const projectProfiles = await readBenchmarkProjectProfiles(projectProfilesPath, toolRoot);
     const cases = await readEvaluationCases(casesPath, toolRoot, {
         projectProfiles,
-        requireProjectProfileRef: true,
+        requireProjectProfileRef: true
     });
     return { cases, projectProfiles, env: process.env };
 }
@@ -194,6 +255,3 @@ function parsePositiveInteger(label, value) {
 function withoutUndefined(value) {
     return Object.fromEntries(Object.entries(value).filter(([, entryValue]) => entryValue !== undefined));
 }
-if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replaceAll("\\", "/"))) {
-    process.exitCode = await main(process.argv.slice(2));
-}

package/dist/src/commands/runFinalDemoCommand.js

@@ -72,7 +72,7 @@ export function parseRunFinalDemoArgs(argv) {
         throw new Error("Usage: --cases <path> --out <dir> --kit-command <command>");
     return { casesPath, outDir, kitCommand, agents, strategies, complexities, caseIds, benchmarkProjects, maxRuns, screenshot, includeRealAgents, continueOnFailure, timeoutMs };
 }
-export async function runFinalDemoFromArgs(args, repoRoot = process.cwd()) {
+export async function runFinalDemoFromArgs(args, repoRoot = process.cwd(), context) {
     const rootOut = path.resolve(repoRoot, args.outDir);
     const experimentDir = path.join(rootOut, "controlled-experiment");
     const plotsDir = path.join(rootOut, "plots");
@@ -81,7 +81,6 @@ export async function runFinalDemoFromArgs(args, repoRoot = process.cwd()) {
     const galleryDir = path.join(rootOut, "gallery");
     const experiment = await runControlledExperimentFromArgs({
         casesPath: args.casesPath,
-        projectProfilesPath: "benchmarks/contracts/benchmark-project-profiles.json",
         outDir: experimentDir,
         agents: args.agents,
         strategies: args.strategies,
@@ -92,7 +91,7 @@ export async function runFinalDemoFromArgs(args, repoRoot = process.cwd()) {
         includeRealAgents: args.includeRealAgents,
         continueOnFailure: args.continueOnFailure,
         timeoutMs: args.timeoutMs
-    }, repoRoot);
+    }, repoRoot, context);
     const plots = await runGenerateExperimentPlotsFromArgs({ experimentDir, outDir: plotsDir }, repoRoot);
     const firstProject = experiment.projectProfiles[0]?.rootPath ?? "benchmarks/projects/todo-ts";
     const visualization = await runVisualizationDemosFromArgs({ projectPath: firstProject, kitCommand: args.kitCommand, outDir: visualizationsDir, timeoutMs: args.timeoutMs }, repoRoot);