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

package/dist/src/commands/runSecurityValidationCommand.js

@@ -0,0 +1,271 @@
+import path from "node:path";
+import { runSecurityValidation } from "../securityValidation/validate/runSecurityValidation.js";
+import { resolveValidationTarget, reportFilenamePrefix } from "../securityValidation/validate/resolveTarget.js";
+import { buildSecurityReportFromSummary } from "../securityValidation/report/buildSecurityReport.js";
+import { renderTextReport } from "../securityValidation/report/renderSecurityReport.js";
+import { writeSecurityReportFiles } from "../securityValidation/report/writeSecurityReportFiles.js";
+import { parseSecurityValidateArgs, normalizeSecurityValidateConfig, applyProfileDefaultChecksIfApplicable } from "../securityValidation/validate/cliOptions.js";
+import { resolveAttackProfile } from "../securityValidation/attackScenarios/attackProfile.js";
+import { findingsBreachFailOnThreshold } from "../securityValidation/validate/verdict.js";
+import { validateAndroidTarget } from "../mobile/android/validate/validateAndroidTarget.js";
+import { toAndroidReportModel } from "../mobile/android/report/model.js";
+import { renderAndroidTextReport } from "../mobile/android/report/renderAndroidReport.js";
+import { writeAndroidReportFiles } from "../mobile/android/report/writeAndroidReportFiles.js";
+import { createLabExecutionContext } from "../runtime/index.js";
+// ---------------------------------------------------------------------------
+// v0.4.6 Batch 4 -- reusable security-validation command owner.
+//
+// Extracted from scripts/security/validate.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/) call the same argument-parsing/
+// target-resolution/report-writing/exit-mapping path. Mirrors the audit
+// command extraction in src/commands/runAuditCommand.ts (Batch 3). Detector/
+// verdict/severity policy, the Android validator, and the classic check
+// pipeline are untouched -- this module only owns CLI wiring.
+// ---------------------------------------------------------------------------
+export const SECURITY_VALIDATE_USAGE = "Usage: my-dev-kit-lab security validate [--target <path>] [--out <dir>] [--report-prefix <name>] " +
+    "[--checks deps,package,static,cli-adversarial,fuzz,boundary,subprocess,secrets,network] " +
+    "[--profile node-cli-package|local-tool|npm-package|android] [--format text,json] [--fail-on blocker|high|medium|low] " +
+    "[--android-gradle-operations wrapper-version,tasks,assemble-debug,unit-test-debug,lint-debug] " +
+    "[--android-external-tools semgrep,osv,android-lint,dependency-check] " +
+    "[--android-external-network deny|allow-requested]\n" +
+    "\n" +
+    "Android profile:\n" +
+    "  --profile android performs static, read-only Android project detection, manifest parsing,\n" +
+    "  permission/exported-component/intent-filter/deep-link audits, static Gradle metadata\n" +
+    "  extraction, and (as of v0.4.1 Batch 8) eleven internal advanced security checks (network\n" +
+    "  security config, backup/release configuration, hardcoded secrets, signing configuration,\n" +
+    "  WebView, FileProvider, sensitive storage/logging, clipboard, and Firebase/Google services).\n" +
+    "  Gradle and external tools are never executed by default.\n" +
+    "  --android-gradle-operations explicitly opts into running ONLY the listed allowlisted Gradle\n" +
+    "  operations (wrapper-version, tasks, assemble-debug, unit-test-debug, lint-debug) via the\n" +
+    "  project's own Gradle wrapper. Arbitrary Gradle tasks cannot be passed. This option is only\n" +
+    "  valid together with --profile android.\n" +
+    "  --android-external-tools explicitly opts into running ONLY the listed allowlisted optional\n" +
+    "  external security tools (semgrep, osv, android-lint, dependency-check). No arbitrary tool\n" +
+    "  names, commands, or arguments can be passed. This option is only valid together with\n" +
+    "  --profile android.\n" +
+    "  --android-external-network controls whether a requested tool may use network access.\n" +
+    "  Defaults to deny (osv is skipped unless supported offline data is available; semgrep,\n" +
+    "  android-lint, and dependency-check always run offline/no-update regardless of this flag).\n" +
+    "  allow-requested authorizes network only for an explicitly requested tool whose Batch 7\n" +
+    "  contract supports it (currently only osv). This option is only valid together with\n" +
+    "  --profile android.\n" +
+    "  Example: my-dev-kit-lab security validate --target \"<android-project-path>\" --profile android\n" +
+    "  Example: my-dev-kit-lab security validate --target \"<android-project-path>\" --profile android --android-gradle-operations wrapper-version,tasks\n" +
+    "  Example: my-dev-kit-lab security validate --target \"<android-project-path>\" --profile android --android-external-tools semgrep,android-lint\n" +
+    "  Example: my-dev-kit-lab security validate --target \"<android-project-path>\" --profile android --android-external-tools osv --android-external-network allow-requested";
+export async function runSecurityValidationCommandFromArgs(argv, options = {}) {
+    const context = options.context ?? createLabExecutionContext();
+    const toolRoot = context.packageRoot;
+    const defaultOutRoot = options.defaultOutRoot ?? toolRoot;
+    // Help deliberately wins over every other argument. It must remain a
+    // no-work path: no target/default resolution, option normalization, report
+    // directory creation, validation orchestration, or subprocess execution.
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(SECURITY_VALIDATE_USAGE);
+        return 0;
+    }
+    let args;
+    let config;
+    try {
+        args = parseSecurityValidateArgs(argv);
+        config = normalizeSecurityValidateConfig(args, defaultOutRoot);
+        // v0.2.2 Batch 5: --profile with no --checks uses that profile's declared
+        // default checks. No-op unless the user passed --profile without --checks
+        // (see applyProfileDefaultChecksIfApplicable's guard) -- the true no-flag
+        // case and any explicit --checks case are always unaffected. Skipped for
+        // "android": that profile does not use the classic --checks pipeline.
+        if (config.profile !== "android") {
+            config = applyProfileDefaultChecksIfApplicable(config, resolveAttackProfile(config.profile).defaultCheckIds);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`\nERROR: ${msg}`);
+        console.error(SECURITY_VALIDATE_USAGE);
+        return 2;
+    }
+    // Resolve and validate target early so we can fail fast with a clean error.
+    let target;
+    try {
+        target = resolveValidationTarget(args.target, toolRoot);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`\nERROR: ${msg}`);
+        console.error(SECURITY_VALIDATE_USAGE);
+        return 1;
+    }
+    console.log("=".repeat(60));
+    console.log("my-dev-kit-lab security:validate");
+    console.log("=".repeat(60));
+    console.log(`Tool root  : ${toolRoot}`);
+    if (!target.isSelf) {
+        console.log(`Target     : ${target.targetRoot}`);
+        if (target.packageName)
+            console.log(`Package    : ${target.packageName}${target.packageVersion ? `@${target.packageVersion}` : ""}`);
+    }
+    else {
+        console.log(`Mode       : self-validation`);
+    }
+    console.log(`Profile    : ${config.profile}`);
+    // ---------------------------------------------------------------------------
+    // v0.4.0 Batch 5 -- Android profile path.
+    //
+    // A separate orchestrator (not the classic check-group/attack-scenario
+    // pipeline below) because the Android check/finding/status vocabulary
+    // established in Batches 1-4 does not fit SecurityCheckId/SecurityCheckResult.
+    // Same command, same --profile flag, same reports/security/ output root.
+    // ---------------------------------------------------------------------------
+    if (config.profile === "android") {
+        if (config.androidGradleOperationIds.length > 0) {
+            console.log(`Gradle ops : ${config.androidGradleOperationIds.join(", ")} (explicitly requested — will execute via the target's Gradle wrapper)`);
+        }
+        else {
+            console.log(`Gradle ops : (none requested — static-only validation, zero Gradle process execution)`);
+        }
+        // v0.4.1 Batch 8 -- external tools remain explicit opt-in, mirroring Gradle
+        // operations exactly. "allow-requested" (the CLI-facing value) maps to the
+        // Batch 7 dispatcher's "allow-for-requested-tool" network policy value.
+        const externalNetworkPolicy = config.androidExternalNetworkPolicy === "allow-requested" ? "allow-for-requested-tool" : "deny";
+        if (config.androidExternalToolIds.length > 0) {
+            console.log(`External   : ${config.androidExternalToolIds.join(", ")} (explicitly requested — network policy: ${config.androidExternalNetworkPolicy})`);
+        }
+        else {
+            console.log(`External   : (none requested — zero external-tool process execution)`);
+        }
+        console.log("");
+        const reportsDir = config.out;
+        let result;
+        try {
+            result = await validateAndroidTarget({
+                toolRoot,
+                targetPath: args.target,
+                requestedGradleOperationIds: config.androidGradleOperationIds,
+                requestedExternalToolIds: config.androidExternalToolIds,
+                externalNetworkPolicy: externalNetworkPolicy,
+                externalToolArtifactRoot: path.join(reportsDir, "external-tools")
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`\nERROR: Android validation failed to run: ${msg}`);
+            return 3;
+        }
+        const reportModel = toAndroidReportModel(result, {
+            profile: config.profile,
+            requestedGradleOperations: config.androidGradleOperationIds,
+            requestedExternalTools: config.androidExternalToolIds,
+            externalNetworkPolicy: config.androidExternalNetworkPolicy
+        });
+        const textReport = renderAndroidTextReport(reportModel);
+        const prefix = args.reportPrefix ??
+            reportFilenamePrefix({
+                isSelf: result.target.local.isSelf,
+                packageName: result.target.local.packageName,
+                packageVersion: result.target.local.packageVersion,
+                targetRoot: result.target.local.targetRoot
+            });
+        let writtenPaths;
+        try {
+            ({ writtenPaths } = writeAndroidReportFiles({ outDir: reportsDir, prefix, report: reportModel, formats: config.formats }));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`\nERROR: Failed to write Android report files: ${msg}`);
+            console.error("Validation completed but the report could not be written. The in-memory result was not persisted.");
+            return 4;
+        }
+        console.log(textReport);
+        console.log(`\nReports written:`);
+        for (const p of writtenPaths) {
+            console.log(`  ${p}`);
+        }
+        const blockerExists = result.verdict === "not-ready-security-blocker-remains";
+        const inconclusive = result.verdict === "inconclusive-audit-environment-incomplete";
+        if (blockerExists) {
+            console.error("\nExit 1 — security blocker remains.");
+            return 1;
+        }
+        else if (inconclusive) {
+            console.warn("\nExit 2 — android environment incomplete.");
+            return 2;
+        }
+        else {
+            console.log("\nExit 0 — validation completed.");
+            return 0;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Classic check-group/attack-scenario pipeline (unchanged from prior versions).
+    // ---------------------------------------------------------------------------
+    if (!config.checksWereDefault) {
+        console.log(`Checks     : ${config.checks.join(", ")}`);
+    }
+    if (config.plannedChecksRequested.length > 0) {
+        console.log(`Note       : ${config.plannedChecksRequested.join(", ")} are routed through the attack-scenario framework rather than the classic check-group runners. Review the attack-scenario section in the report for their concrete results.`);
+    }
+    console.log("");
+    const summary = await runSecurityValidation({
+        cwd: toolRoot,
+        targetPath: args.target,
+        fuzzIterations: parseInt(process.env["FUZZ_ITERATIONS"] ?? "50", 10),
+        fuzzSeed: parseInt(process.env["FUZZ_SEED"] ?? "0xDEADBEEF", 16),
+        // Full selection (implemented + planned/attack-scenario ids) -- the runner
+        // gates both implemented check groups and attack-scenario checks off the
+        // same selectedChecks set.
+        selectedChecks: config.checks,
+        profile: config.profile
+    });
+    // v0.2.2 Batch 5: --fail-on breach is additive to (never a substitute for)
+    // the existing verdict-based exit decision below -- it can only escalate
+    // exit 0 to exit 1 (e.g. --fail-on medium/low catching minor/informational
+    // findings the verdict policy doesn't already treat as blocking), never
+    // downgrade an existing blocker.
+    const failOnBreached = findingsBreachFailOnThreshold(summary.findings, config.failOnThreshold);
+    // Build report object
+    const report = buildSecurityReportFromSummary(summary, {
+        profile: config.profile,
+        selectedChecks: config.checks,
+        failOnThreshold: config.failOnThreshold,
+        formats: config.formats,
+        failOnBreached
+    });
+    const textReport = renderTextReport(report);
+    // Determine output directory
+    const reportsDir = config.out;
+    // Determine report filename prefix
+    const prefix = args.reportPrefix ?? reportFilenamePrefix(target);
+    const { writtenPaths } = writeSecurityReportFiles({
+        outDir: reportsDir,
+        prefix,
+        report,
+        formats: config.formats
+    });
+    // Print report to stdout
+    console.log(textReport);
+    console.log(`\nReports written:`);
+    for (const p of writtenPaths) {
+        console.log(`  ${p}`);
+    }
+    // Exit code based on verdict, escalated (never downgraded) by --fail-on.
+    const blockerExists = summary.verdict === "not-ready-security-blocker-remains";
+    const inconclusive = summary.verdict === "inconclusive-audit-environment-incomplete";
+    if (blockerExists) {
+        console.error("\nExit 1 — security blocker remains.");
+        return 1;
+    }
+    else if (inconclusive) {
+        console.warn("\nExit 2 — audit environment incomplete.");
+        return 2;
+    }
+    else if (failOnBreached) {
+        console.error(`\nExit 1 — --fail-on ${config.failOnThreshold} threshold breached.`);
+        return 1;
+    }
+    else {
+        console.log("\nExit 0 — validation completed.");
+        return 0;
+    }
+}

package/dist/src/commands/runTutorialRunCommand.js

@@ -0,0 +1,170 @@
+import { createLabExecutionContext } from "../runtime/index.js";
+import { runTutorial } from "../tutorial/index.js";
+// ---------------------------------------------------------------------------
+// v0.4.7 Batch 2 -- tutorial run command owner.
+//
+// A thin adapter: parse a closed option set, resolve execution roots through
+// LabExecutionContext, delegate to runTutorial(), render a summary, map the run
+// status to an exit code. No tutorial semantics live here.
+// ---------------------------------------------------------------------------
+export const TUTORIAL_CLI_USAGE_EXIT_CODE = 2;
+const RUN_USAGE = "Usage: my-dev-kit-lab tutorial run --scenario <path> --target-contract <path> [--out <dir>] [--json]";
+export async function runTutorialRunCommandFromArgs(argv, options = {}) {
+    const writers = options.writers ?? {
+        stdout: (message) => console.log(message),
+        stderr: (message) => console.error(message)
+    };
+    const parsed = parseRunArgs(argv);
+    if (!parsed.ok) {
+        writers.stderr(parsed.error);
+        return TUTORIAL_CLI_USAGE_EXIT_CODE;
+    }
+    const context = options.context ?? createLabExecutionContext();
+    const execute = options.runTutorialImpl ?? runTutorial;
+    const result = await execute({
+        scenarioPath: parsed.scenarioPath,
+        targetContractPath: parsed.targetContractPath,
+        context,
+        ...(parsed.outDir !== undefined ? { outDir: parsed.outDir } : {}),
+        ...(options.launchBrowser ? { launchBrowser: options.launchBrowser } : {}),
+        ...(options.generateRunId ? { generateRunId: options.generateRunId } : {})
+    });
+    if (parsed.json) {
+        writers.stdout(JSON.stringify(result, null, 2));
+    }
+    else {
+        writers.stdout(renderRunSummary(result));
+    }
+    return result.status === "passed" ? 0 : 1;
+}
+/**
+ * Concise by design: identity, location, outcome, and the first thing that went
+ * wrong. Child-process logs are written to the run's logs directory and are
+ * never dumped to the terminal automatically.
+ */
+function renderRunSummary(result) {
+    const lines = [];
+    lines.push(`Scenario ID: ${result.scenarioId ?? "(not loaded)"}`);
+    lines.push(`Target ID: ${result.targetId ?? "(not loaded)"}`);
+    lines.push(`Run ID: ${result.runId ?? "(not started)"}`);
+    lines.push(`Run root: ${result.paths?.runRoot ?? "(not created)"}`);
+    lines.push(`Status: ${result.status}`);
+    lines.push(`Duration: ${result.durationMs}ms`);
+    const stepCounts = summarizeSteps(result);
+    if (result.steps.length > 0) {
+        lines.push(`Steps: ${result.steps.length} (passed ${stepCounts.passed}, failed ${stepCounts.failed}, not-run ${stepCounts.notRun})`);
+    }
+    const failedStep = result.steps.find((step) => step.status === "failed");
+    if (failedStep) {
+        lines.push(`Failed step: ${failedStep.id}`);
+    }
+    lines.push(...renderArtifactLines(result));
+    if (result.error) {
+        lines.push(`Error: ${result.error}`);
+    }
+    for (const warning of result.warnings) {
+        lines.push(`Warning: ${warning}`);
+    }
+    for (const cleanupError of result.cleanupErrors) {
+        lines.push(`Cleanup error: ${cleanupError}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * One line per canonical artifact that was actually written, plus a screenshot
+ * count. Failed or skipped artifacts are named so a reader sees why, but the
+ * manifest itself is never dumped here -- that is what --json is for.
+ */
+function renderArtifactLines(result) {
+    const artifacts = result.artifacts;
+    const lines = [];
+    const named = [
+        ["Video", artifacts.video],
+        ["SRT", artifacts.srt],
+        ["VTT", artifacts.vtt],
+        ["Markdown", artifacts.markdown],
+        ["Manifest", artifacts.manifest]
+    ];
+    const written = named.filter(([, record]) => record?.status === "written");
+    for (const [label, record] of written) {
+        lines.push(`${label}: ${record.path ?? ""}`);
+    }
+    const writtenScreenshots = artifacts.screenshots.filter((record) => record.status === "written");
+    if (artifacts.screenshots.length > 0) {
+        lines.push(`Screenshots: ${writtenScreenshots.length} of ${artifacts.screenshots.length} written`);
+    }
+    for (const [label, record] of named) {
+        if (record && record.status !== "written") {
+            lines.push(`${label} artifact ${record.status}: ${record.error ?? "no detail"}`);
+        }
+    }
+    for (const record of artifacts.screenshots) {
+        if (record.status !== "written") {
+            lines.push(`Screenshot ${record.id ?? "?"} ${record.status}: ${record.error ?? "no detail"}`);
+        }
+    }
+    return lines;
+}
+function summarizeSteps(result) {
+    let passed = 0;
+    let failed = 0;
+    let notRun = 0;
+    for (const step of result.steps) {
+        if (step.status === "passed")
+            passed += 1;
+        else if (step.status === "failed")
+            failed += 1;
+        else
+            notRun += 1;
+    }
+    return { passed, failed, notRun };
+}
+function parseRunArgs(argv) {
+    let scenarioPath;
+    let targetContractPath;
+    let outDir;
+    let json = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--scenario") {
+            const value = argv[++index];
+            if (value === undefined) {
+                return { ok: false, error: `Missing value for --scenario. ${RUN_USAGE}` };
+            }
+            scenarioPath = value;
+        }
+        else if (arg === "--target-contract") {
+            const value = argv[++index];
+            if (value === undefined) {
+                return { ok: false, error: `Missing value for --target-contract. ${RUN_USAGE}` };
+            }
+            targetContractPath = value;
+        }
+        else if (arg === "--out") {
+            const value = argv[++index];
+            if (value === undefined) {
+                return { ok: false, error: `Missing value for --out. ${RUN_USAGE}` };
+            }
+            outDir = value;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else {
+            return { ok: false, error: `Unknown argument for "tutorial run": ${arg}. ${RUN_USAGE}` };
+        }
+    }
+    if (scenarioPath === undefined) {
+        return { ok: false, error: `Missing required --scenario. ${RUN_USAGE}` };
+    }
+    if (targetContractPath === undefined) {
+        return { ok: false, error: `Missing required --target-contract. ${RUN_USAGE}` };
+    }
+    return {
+        ok: true,
+        scenarioPath,
+        targetContractPath,
+        ...(outDir !== undefined ? { outDir } : {}),
+        json
+    };
+}

package/dist/src/commands/runTutorialValidateCommand.js

@@ -0,0 +1,138 @@
+import { createLabExecutionContext } from "../runtime/index.js";
+import { describeTargetIdMismatch, loadTutorialScenario, loadTutorialTargetContract, tutorialTargetIdsMatch } from "../tutorial/index.js";
+// ---------------------------------------------------------------------------
+// v0.4.7 Batch 2 -- tutorial contract validation command owner.
+//
+// Read-only by construction: it loads and validates contracts and nothing else.
+// No run directory is created, no prepare command runs, no process starts and
+// no browser launches, so this route is safe to run anywhere and needs neither
+// Chromium nor a prepared target.
+// ---------------------------------------------------------------------------
+export const TUTORIAL_CLI_USAGE_EXIT_CODE = 2;
+export async function runTutorialValidateCommandFromArgs(argv, options = {}) {
+    const writers = options.writers ?? {
+        stdout: (message) => console.log(message),
+        stderr: (message) => console.error(message)
+    };
+    const parsed = parseValidateArgs(argv);
+    if (!parsed.ok) {
+        writers.stderr(parsed.error);
+        return TUTORIAL_CLI_USAGE_EXIT_CODE;
+    }
+    const context = options.context ?? createLabExecutionContext();
+    const report = { status: "valid", scenarioPath: parsed.scenarioPath, errors: [] };
+    const loadedScenario = await loadTutorialScenario(context.invocationCwd, parsed.scenarioPath);
+    if (!loadedScenario.ok) {
+        report.status = "invalid";
+        report.errors.push(...loadedScenario.errors);
+    }
+    else {
+        report.scenarioPath = loadedScenario.value.scenarioPath;
+        report.scenarioId = loadedScenario.value.scenario.id;
+        report.scenarioTitle = loadedScenario.value.scenario.title;
+        report.targetIdDeclared = loadedScenario.value.scenario.targetId;
+        report.stepCount = loadedScenario.value.scenario.steps.length;
+    }
+    if (parsed.targetContractPath !== undefined) {
+        const loadedTarget = await loadTutorialTargetContract(context.invocationCwd, parsed.targetContractPath);
+        if (!loadedTarget.ok) {
+            report.status = "invalid";
+            report.targetContractPath = parsed.targetContractPath;
+            report.errors.push(...loadedTarget.errors);
+        }
+        else {
+            report.targetContractPath = loadedTarget.value.targetContractPath;
+            report.targetContractId = loadedTarget.value.targetContract.id;
+            report.processCount = loadedTarget.value.targetContract.processes.length;
+            report.applicationUrl = loadedTarget.value.targetContract.applicationUrl;
+            if (loadedScenario.ok) {
+                const matches = tutorialTargetIdsMatch(loadedScenario.value.scenario.targetId, loadedTarget.value.targetContract.id);
+                report.targetIdMatches = matches;
+                if (!matches) {
+                    report.status = "invalid";
+                    report.errors.push(describeTargetIdMismatch(loadedScenario.value.scenario.targetId, loadedTarget.value.targetContract.id));
+                }
+            }
+        }
+    }
+    if (parsed.json) {
+        writers.stdout(JSON.stringify(report, null, 2));
+    }
+    else {
+        writers.stdout(renderValidateSummary(report));
+    }
+    return report.status === "valid" ? 0 : 1;
+}
+function renderValidateSummary(report) {
+    const lines = [];
+    lines.push(`Scenario: ${report.scenarioPath}`);
+    if (report.scenarioId) {
+        lines.push(`Scenario ID: ${report.scenarioId}`);
+        lines.push(`Title: ${report.scenarioTitle ?? ""}`);
+        lines.push(`Declared target ID: ${report.targetIdDeclared ?? ""}`);
+        lines.push(`Steps: ${report.stepCount ?? 0}`);
+    }
+    if (report.targetContractPath) {
+        lines.push(`Target contract: ${report.targetContractPath}`);
+    }
+    if (report.targetContractId) {
+        lines.push(`Target contract ID: ${report.targetContractId}`);
+        lines.push(`Managed processes: ${report.processCount ?? 0}`);
+        lines.push(`Application URL: ${report.applicationUrl ?? ""}`);
+    }
+    lines.push(`Status: ${report.status}`);
+    if (report.errors.length > 0) {
+        lines.push("");
+        lines.push("Errors:");
+        for (const error of report.errors) {
+            lines.push(`  - ${error}`);
+        }
+    }
+    return lines.join("\n");
+}
+function parseValidateArgs(argv) {
+    let scenarioPath;
+    let targetContractPath;
+    let json = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--scenario") {
+            const value = argv[++index];
+            if (value === undefined) {
+                return { ok: false, error: "Missing value for --scenario. Expected a path to a tutorial scenario JSON file." };
+            }
+            scenarioPath = value;
+        }
+        else if (arg === "--target-contract") {
+            const value = argv[++index];
+            if (value === undefined) {
+                return {
+                    ok: false,
+                    error: "Missing value for --target-contract. Expected a path to a tutorial target contract JSON file."
+                };
+            }
+            targetContractPath = value;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else {
+            return {
+                ok: false,
+                error: `Unknown argument for "tutorial validate": ${arg}. Usage: my-dev-kit-lab tutorial validate --scenario <path> [--target-contract <path>] [--json]`
+            };
+        }
+    }
+    if (scenarioPath === undefined) {
+        return {
+            ok: false,
+            error: "Missing required --scenario. Usage: my-dev-kit-lab tutorial validate --scenario <path> [--target-contract <path>] [--json]"
+        };
+    }
+    return {
+        ok: true,
+        scenarioPath,
+        ...(targetContractPath !== undefined ? { targetContractPath } : {}),
+        json
+    };
+}

package/dist/src/core/processTree.js

@@ -0,0 +1,52 @@
+import { spawn } from "node:child_process";
+/**
+ * Asks a process to terminate normally.
+ *
+ * Sends SIGTERM on every platform. On Windows Node maps SIGTERM to
+ * TerminateProcess, so the named process is terminated but its descendants are
+ * not; this is a best-effort "please stop" step, not a tree operation.
+ *
+ * Never throws: the process may already have exited between the caller's
+ * liveness check and this call.
+ */
+export function requestProcessTermination(pid) {
+    if (!pid) {
+        return;
+    }
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch {
+        // The process may have exited between the liveness check and this signal.
+    }
+}
+/**
+ * Forced cleanup for a process that did not stop on request.
+ *
+ * Windows: `taskkill /pid <pid> /T /F` with shell:false. `/T` makes this a real
+ * descendant-tree termination on Windows.
+ *
+ * Other platforms: a single `process.kill(pid, signal)` on the known process ID.
+ * This deliberately does NOT walk or signal the descendant tree -- no process
+ * group or `pgid` traversal is performed here -- so a child that spawned its own
+ * grandchildren may leave those grandchildren running. The file name reflects
+ * the Windows capability and the shared call site, not a POSIX tree guarantee.
+ *
+ * Never throws.
+ */
+export function forceTerminateProcess(pid, options = {}) {
+    if (!pid) {
+        return;
+    }
+    if (process.platform === "win32") {
+        const killer = spawn("taskkill", ["/pid", String(pid), "/T", "/F"], { shell: false, stdio: "ignore" });
+        killer.on("error", () => undefined);
+        return;
+    }
+    try {
+        process.kill(pid, options.posixSignal ?? "SIGTERM");
+    }
+    catch {
+        // The process may have exited between the liveness check and this signal.
+    }
+}

package/dist/src/core/resolveCommand.js

@@ -159,3 +159,37 @@ function isExecutableFile(candidatePath) {
         return false;
     }
 }
+/**
+ * Builds the spawn-ready invocation for an already-resolved command.
+ *
+ * Exposed separately from `resolveCommandInvocation` so callers that legitimately
+ * bypass PATH resolution (for example `runMeasuredCommand({ resolveCommand: false })`)
+ * still share one argument-assembly rule.
+ *
+ * `windows-cmd-shim` resolutions run `cmd.exe /d /s /c call <resolvedPath> ...`,
+ * so the resolved shim path is inserted after the prefix. Every other resolution
+ * kind (including `windows-powershell-shim`, whose `argsPrefix` already ends with
+ * `-File <resolvedPath>`) only needs prefix + caller arguments.
+ */
+export function buildResolvedCommandInvocation(resolvedCommand, args) {
+    const trailingArgs = [...args];
+    const invocationArgs = resolvedCommand.resolutionKind === "windows-cmd-shim" && resolvedCommand.resolvedPath
+        ? [...resolvedCommand.argsPrefix, resolvedCommand.resolvedPath, ...trailingArgs]
+        : [...resolvedCommand.argsPrefix, ...trailingArgs];
+    return {
+        executable: resolvedCommand.command,
+        args: invocationArgs,
+        resolvedCommand
+    };
+}
+/**
+ * Resolves `executable` through `resolveCommand()` and returns the spawn-ready
+ * executable/argument pair. Never introduces `shell: true`.
+ *
+ * An unavailable command is returned as a structured invocation whose
+ * `resolvedCommand.resolutionKind` is "unavailable"; callers decide whether that
+ * is a skip or a failure.
+ */
+export function resolveCommandInvocation(executable, args, options = {}) {
+    return buildResolvedCommandInvocation(resolveCommand(executable, options), args);
+}