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

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);