@askrjs/cli 0.0.10 → 0.0.11

package/README.md

@@ -41,6 +41,10 @@ unless you opt out with `--no-skills`.
 - `askr create [template] <name> [--prompt <text>] [--no-install] [--no-skills]`
 - `askr add page <name> [--branch app|public]`
 - `askr add action <name> --route <path>`
+- `askr analyze [--cwd <dir>] [--workspace <pattern>]... [--json] [--check]`
+- `askr doctor [--cwd <dir>] [--workspace <pattern>]... [--json]`
+- `askr repair [--cwd <dir>] [--workspace <pattern>]... [--json]`
+- `askr check [--cwd <dir>] [--workspace <pattern>]... [--json]`
 - `askr skills list`
 - `askr skills install [--cwd <dir>] [--force]`
 - `askr skills sync [--cwd <dir>]`
@@ -53,6 +57,50 @@ unless you opt out with `--no-skills`.
 The installed command is `askr`. Subcommands are intentionally not published
 as compatibility binaries.
 
+## Static analysis
+
+`askr analyze` discovers the containing npm or pnpm workspace, builds a
+TypeScript compiler program for every selected workspace, and checks current
+Askr state, lifecycle, data, control-flow, routing, boot, SSR/SSG, action, and
+configuration contracts.
+
+```bash
+askr analyze
+askr analyze --workspace "@scope/web"
+askr analyze --check
+askr analyze --json --check
+```
+
+All diagnostics include a stable rule ID and workspace-relative source
+location. The analyzer distinguishes canonical Askr imports from unrelated
+same-named functions and only recommends `<For>` for state-backed reactive JSX
+collections, so static transforms with `.map()` remain valid.
+
+By default it transactionally applies only mechanical route-parameter and
+plain-JSON JSX configuration fixes. `--check` is read-only for CI. Semantic
+rewrites, including `.map()` to `<For>`, conditional primitives, and key
+changes, are always report-only. See the
+[analyze command reference](./docs/analyze.md) for rules and configuration.
+
+## Project recovery loop
+
+Every generated project uses the same guardrail loop:
+
+```bash
+askr doctor
+askr repair
+askr check
+```
+
+`doctor` performs a read-only environment, package-manager, framework, skills,
+and static-analysis inspection. `repair` transactionally applies only safe
+mechanical fixes and reports remaining semantic work. `check` requires clean
+analysis before running the project's declared lint, typecheck, test, and build
+scripts in order. Generated projects expose that final gate as `npm run check`.
+
+See the [project guardrails reference](./docs/guardrails.md) for command and JSON
+contracts.
+
 ## Static sitemap generation
 
 `askr ssg` writes `sitemap.xml` from the concrete routes generated during the

package/dist/add.d.ts

@@ -1,13 +1,4 @@
-//#region src/file-changes.d.ts
-interface FileChange {
-  readonly filePath: string;
-  readonly content: string;
-}
-interface FileChangeWriterOptions {
-  readonly replace?: (temporaryPath: string, filePath: string) => Promise<void>;
-}
-declare function writeFileChanges(changes: readonly FileChange[], options?: FileChangeWriterOptions): Promise<void>;
-//#endregion
+import { n as writeFileChanges } from "./file-changes-cmFN-rF8.js";
 //#region src/bin/add.d.ts
 type CliIo = Pick<Console, "error" | "log">;
 type WriteChanges = typeof writeFileChanges;

package/dist/add.js

@@ -1,70 +1,8 @@
 #!/usr/bin/env node
 import { t as isDirectExecution } from "./is-direct-execution-Cdlr-ZUl.js";
+import { t as writeFileChanges } from "./file-changes-BAFLhEHZ.js";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { randomUUID } from "node:crypto";
-//#region src/file-changes.ts
-async function remove(paths) {
-	await Promise.all(paths.map((filePath) => fs.rm(filePath, { force: true }).catch(() => void 0)));
-}
-async function restore(changes) {
-	let complete = true;
-	for (const change of [...changes].reverse()) try {
-		if (change.original === null) {
-			await fs.rm(change.filePath, { force: true });
-			continue;
-		}
-		const rollbackPath = path.join(path.dirname(change.filePath), `.${path.basename(change.filePath)}.askr-rollback-${randomUUID()}`);
-		await fs.writeFile(rollbackPath, change.original, {
-			flag: "wx",
-			mode: change.mode
-		});
-		await fs.rename(rollbackPath, change.filePath);
-	} catch {
-		complete = false;
-	}
-	return complete;
-}
-async function writeFileChanges(changes, options = {}) {
-	const ordered = [...changes].sort((left, right) => left.filePath.localeCompare(right.filePath));
-	if (new Set(ordered.map((change) => change.filePath)).size !== ordered.length) throw new Error("File changes contain duplicate target paths.");
-	const replace = options.replace ?? fs.rename;
-	const staged = [];
-	try {
-		for (const change of ordered) {
-			await fs.mkdir(path.dirname(change.filePath), { recursive: true });
-			const stat = await fs.stat(change.filePath).catch(() => null);
-			const original = stat ? await fs.readFile(change.filePath) : null;
-			const temporaryPath = path.join(path.dirname(change.filePath), `.${path.basename(change.filePath)}.askr-change-${randomUUID()}`);
-			const mode = stat?.mode ?? 420;
-			await fs.writeFile(temporaryPath, change.content, {
-				flag: "wx",
-				mode
-			});
-			staged.push({
-				...change,
-				original,
-				mode,
-				temporaryPath
-			});
-		}
-	} catch (error) {
-		await remove(staged.map((change) => change.temporaryPath));
-		throw error;
-	}
-	const replaced = [];
-	try {
-		for (const change of staged) {
-			await replace(change.temporaryPath, change.filePath);
-			replaced.push(change);
-		}
-	} catch {
-		const complete = await restore(replaced);
-		await remove(staged.map((change) => change.temporaryPath));
-		throw new Error(complete ? "File replacement failed; completed changes were rolled back." : "File replacement failed and rollback was incomplete.");
-	}
-}
-//#endregion
 //#region src/bin/add.ts
 const BRANCH_CONFIG = {
 	app: {

package/dist/analyze.d.ts

@@ -0,0 +1,88 @@
+import { t as FileChange } from "./file-changes-cmFN-rF8.js";
+import ts from "typescript";
+//#region src/analyze/types.d.ts
+declare const ANALYZE_SCHEMA_VERSION = 1;
+type AnalyzeSeverity = "error" | "warning" | "info";
+type AnalyzeCategory = "correctness" | "performance" | "configuration";
+interface AnalyzeFix {
+  readonly description: string;
+  readonly filePath: string;
+  readonly start: number;
+  readonly end: number;
+  readonly replacement: string;
+}
+interface AnalyzeDiagnostic {
+  readonly ruleId: string;
+  readonly category: AnalyzeCategory;
+  readonly severity: AnalyzeSeverity;
+  readonly message: string;
+  readonly workspace: string;
+  readonly file: string;
+  readonly line: number;
+  readonly column: number;
+  readonly remediation?: string;
+  readonly fix?: AnalyzeFix;
+}
+interface PublicDiagnostic extends Omit<AnalyzeDiagnostic, "fix"> {
+  readonly fix?: {
+    readonly description: string;
+    readonly safe: true;
+  };
+}
+interface AnalyzeWorkspaceResult {
+  readonly name: string;
+  readonly path: string;
+  readonly tsconfig: string | null;
+  readonly files: number;
+}
+interface AnalyzeFixResult {
+  readonly ruleId: string;
+  readonly workspace: string;
+  readonly file: string;
+  readonly description: string;
+  readonly reason?: string;
+}
+interface AnalyzeSummary {
+  readonly errors: number;
+  readonly warnings: number;
+  readonly info: number;
+  readonly diagnostics: number;
+  readonly appliedFixes: number;
+  readonly skippedFixes: number;
+}
+interface AnalyzeReport {
+  readonly schemaVersion: typeof ANALYZE_SCHEMA_VERSION;
+  readonly root: string;
+  readonly discoveredWorkspaces: readonly string[];
+  readonly selectedWorkspaces: readonly string[];
+  readonly workspaces: readonly AnalyzeWorkspaceResult[];
+  readonly appliedFixes: readonly AnalyzeFixResult[];
+  readonly skippedFixes: readonly AnalyzeFixResult[];
+  readonly diagnostics: readonly PublicDiagnostic[];
+  readonly summary: AnalyzeSummary;
+}
+//#endregion
+//#region src/analyze/runner.d.ts
+interface RunAnalysisOptions {
+  readonly cwd: string;
+  readonly workspacePatterns: string[];
+  readonly check: boolean;
+  readonly writer?: (changes: readonly FileChange[]) => Promise<void>;
+}
+//#endregion
+//#region src/bin/analyze.d.ts
+type CliIo = Pick<Console, "error" | "log">;
+interface ParsedAnalyzeArgs {
+  cwd: string;
+  workspacePatterns: string[];
+  json: boolean;
+  check: boolean;
+  help: boolean;
+}
+interface AnalyzeRuntime {
+  readonly analyze?: (options: RunAnalysisOptions) => Promise<AnalyzeReport>;
+}
+declare function parseAnalyzeArgs(args: readonly string[]): ParsedAnalyzeArgs;
+declare function runAnalyzeCli(args?: string[], io?: CliIo, runtime?: AnalyzeRuntime): Promise<number>;
+//#endregion
+export { parseAnalyzeArgs, runAnalyzeCli };

package/dist/analyze.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { t as isDirectExecution } from "./is-direct-execution-Cdlr-ZUl.js";
+import path from "node:path";
+//#region src/bin/analyze.ts
+const helpText = `askr analyze - Analyze Askr correctness and performance
+
+Usage:
+  askr analyze [--cwd <dir>] [--workspace <pattern>]... [--json] [--check]
+
+Options:
+  --cwd <dir>             Resolve a project from another directory
+  --workspace <pattern>   Select workspace names (repeatable)
+  --json                  Emit one deterministic JSON object on stdout
+  --check                 Report safe fixes without writing files
+  --help, -h              Show this help message
+
+By default every declared workspace is scanned and explicitly safe fixes are
+applied transactionally. Semantic rewrites are always report-only.
+`;
+function optionValue(args, index, option) {
+	const value = args[index + 1];
+	if (!value || value.startsWith("-")) throw new Error(`${option} requires a value`);
+	return value;
+}
+function parseAnalyzeArgs(args) {
+	const parsed = {
+		cwd: process.cwd(),
+		workspacePatterns: [],
+		json: false,
+		check: false,
+		help: false
+	};
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--help" || argument === "-h") parsed.help = true;
+		else if (argument === "--json") parsed.json = true;
+		else if (argument === "--check") parsed.check = true;
+		else if (argument === "--cwd") {
+			parsed.cwd = path.resolve(optionValue(args, index, "--cwd"));
+			index += 1;
+		} else if (argument.startsWith("--cwd=")) {
+			const value = argument.slice(6);
+			if (!value) throw new Error("--cwd requires a value");
+			parsed.cwd = path.resolve(value);
+		} else if (argument === "--workspace") {
+			parsed.workspacePatterns.push(optionValue(args, index, "--workspace"));
+			index += 1;
+		} else if (argument.startsWith("--workspace=")) {
+			const value = argument.slice(12);
+			if (!value) throw new Error("--workspace requires a value");
+			parsed.workspacePatterns.push(value);
+		} else throw new Error(`Unknown option: ${argument}`);
+	}
+	return parsed;
+}
+function formatDiagnostic(diagnostic) {
+	const severity = diagnostic.severity.toUpperCase();
+	const remedy = diagnostic.remediation ? `\n  ${diagnostic.remediation}` : "";
+	return `${diagnostic.workspace}:${diagnostic.file}:${diagnostic.line}:${diagnostic.column} ${severity} ${diagnostic.ruleId} ${diagnostic.message}${remedy}`;
+}
+function printHuman(report, io) {
+	for (const fix of report.appliedFixes) io.log(`fixed ${fix.file} ${fix.ruleId}: ${fix.description}`);
+	for (const diagnostic of report.diagnostics) io.log(formatDiagnostic(diagnostic));
+	io.log(`Analyzed ${report.workspaces.length} workspace(s), ${report.workspaces.reduce((count, workspace) => count + workspace.files, 0)} file(s): ${report.summary.errors} error(s), ${report.summary.warnings} warning(s), ${report.summary.info} info, ${report.summary.appliedFixes} fix(es) applied.`);
+}
+async function runAnalyzeCli(args = process.argv.slice(2), io = console, runtime = {}) {
+	const wantsJson = args.includes("--json");
+	try {
+		const parsed = parseAnalyzeArgs(args);
+		if (parsed.help) {
+			io.log(helpText.trimEnd());
+			return 0;
+		}
+		const report = await (runtime.analyze ?? (await import("./runner-42nqhW9u.js")).runAnalysis)({
+			cwd: parsed.cwd,
+			workspacePatterns: parsed.workspacePatterns,
+			check: parsed.check
+		});
+		if (parsed.json) io.log(JSON.stringify(report));
+		else printHuman(report, io);
+		return report.summary.errors > 0 || report.summary.warnings > 0 ? 1 : 0;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		io.error(wantsJson ? JSON.stringify({
+			schemaVersion: 1,
+			status: "error",
+			error: message
+		}) : message);
+		return 1;
+	}
+}
+async function main() {
+	process.exit(await runAnalyzeCli(process.argv.slice(2)));
+}
+if (isDirectExecution(import.meta.url)) main();
+//#endregion
+export { parseAnalyzeArgs, runAnalyzeCli };

package/dist/cli.js

@@ -33,12 +33,16 @@ function printHelp(io = console) {
 	io.log("");
 	io.log("Commands:");
 	io.log("  add        Generate pages or declared actions into an Askr project");
+	io.log("  analyze    Analyze Askr correctness and performance");
+	io.log("  check      Run the complete project validation path");
 	io.log("  create     Create a new Askr app from a template or product prompt");
+	io.log("  doctor     Diagnose environment and Askr project health");
 	io.log("  generate   Generate an @askrjs/fetch client from OpenAPI");
 	io.log("  openapi    Generate or check an OpenAPI YAML artifact");
 	io.log("  skills     Install or sync Askr agent skills");
 	io.log("  ssg        Run static-site generation");
 	io.log("  outdated   List available dependency updates");
+	io.log("  repair     Apply safe fixes and identify remaining semantic work");
 	io.log("  update     Apply safe dependency updates");
 	io.log("  upgrade    Apply latest peer-compatible dependency upgrades");
 	io.log("");
@@ -51,6 +55,10 @@ function printHelp(io = console) {
 	io.log("  askr create --prompt \"Agent workflow console with approvals\"");
 	io.log("  askr add page audit-log");
 	io.log("  askr add action approve-request --route /requests/{id}");
+	io.log("  askr analyze --check");
+	io.log("  askr doctor");
+	io.log("  askr repair");
+	io.log("  askr check");
 	io.log("  askr skills install");
 	io.log("  askr openapi --check");
 	io.log("  askr skills review foundation --cwd ./candidate-app");
@@ -77,6 +85,14 @@ async function runCli(args = process.argv.slice(2), io = console) {
 		const { runAddCli } = await import("./add.js");
 		return runAddCli(args.slice(1), io);
 	}
+	if (command === "analyze") {
+		const { runAnalyzeCli } = await import("./analyze.js");
+		return runAnalyzeCli(args.slice(1), io);
+	}
+	if (command === "check" || command === "doctor" || command === "repair") {
+		const { runGuardrailCli } = await import("./guardrails-vH9lYg05.js");
+		return runGuardrailCli(command, args.slice(1), io);
+	}
 	if (command === "generate") {
 		const { runGenerateCli } = await import("./generate.js");
 		return runGenerateCli(args.slice(1), io);

package/dist/create.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { t as isDirectExecution } from "./is-direct-execution-Cdlr-ZUl.js";
-import { t as installBundledSkills } from "./skills-C2KzfTl9.js";
+import { n as installBundledSkills } from "./skills-CSGdAZHN.js";
 import { n as publishStagedDirectory, t as createSiblingStage } from "./directory-swap-DWoHtx7C.js";
 import fs from "node:fs/promises";
 import path from "node:path";

package/dist/{discovery-BX-lnFRK.js → discovery-DUDrZCIC.js}

@@ -301,11 +301,20 @@ function collectOccurrences(root, workspaces, localNames, policy, packagePattern
 	occurrences.sort((left, right) => left.package.localeCompare(right.package) || left.workspace.localeCompare(right.workspace) || left.relativeManifestPath.localeCompare(right.relativeManifestPath) || sectionOrder.get(left.section) - sectionOrder.get(right.section));
 	return occurrences;
 }
-async function discoverProject(options) {
+async function discoverWorkspaceProject(options) {
 	const root = await findProjectRoot(options.cwd);
 	const { policy, workspaces } = await discoverWorkspaces(root);
 	const selectedWorkspaces = options.workspacePatterns.length === 0 ? workspaces : workspaces.filter((workspace) => matchesAny(workspace.name, options.workspacePatterns));
 	if (selectedWorkspaces.length === 0) throw new Error("No discovered workspace matches the requested --workspace filters.");
+	return {
+		root,
+		workspaces,
+		selectedWorkspaces,
+		policy
+	};
+}
+async function discoverProject(options) {
+	const { root, workspaces, selectedWorkspaces, policy } = await discoverWorkspaceProject(options);
 	const localNames = new Set(workspaces.map((workspace) => workspace.name));
 	const localVersions = new Map(workspaces.flatMap((workspace) => typeof workspace.manifest.version === "string" && semver.valid(workspace.manifest.version) ? [[workspace.name, workspace.manifest.version]] : []));
 	return {
@@ -322,4 +331,4 @@ async function discoverProject(options) {
 	};
 }
 //#endregion
-export { discoverProject };
+export { discoverProject, discoverWorkspaceProject };

package/dist/file-changes-BAFLhEHZ.js

@@ -0,0 +1,66 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+//#region src/file-changes.ts
+async function remove(paths) {
+	await Promise.all(paths.map((filePath) => fs.rm(filePath, { force: true }).catch(() => void 0)));
+}
+async function restore(changes) {
+	let complete = true;
+	for (const change of [...changes].reverse()) try {
+		if (change.original === null) {
+			await fs.rm(change.filePath, { force: true });
+			continue;
+		}
+		const rollbackPath = path.join(path.dirname(change.filePath), `.${path.basename(change.filePath)}.askr-rollback-${randomUUID()}`);
+		await fs.writeFile(rollbackPath, change.original, {
+			flag: "wx",
+			mode: change.mode
+		});
+		await fs.rename(rollbackPath, change.filePath);
+	} catch {
+		complete = false;
+	}
+	return complete;
+}
+async function writeFileChanges(changes, options = {}) {
+	const ordered = [...changes].sort((left, right) => left.filePath.localeCompare(right.filePath));
+	if (new Set(ordered.map((change) => change.filePath)).size !== ordered.length) throw new Error("File changes contain duplicate target paths.");
+	const replace = options.replace ?? fs.rename;
+	const staged = [];
+	try {
+		for (const change of ordered) {
+			await fs.mkdir(path.dirname(change.filePath), { recursive: true });
+			const stat = await fs.stat(change.filePath).catch(() => null);
+			const original = stat ? await fs.readFile(change.filePath) : null;
+			const temporaryPath = path.join(path.dirname(change.filePath), `.${path.basename(change.filePath)}.askr-change-${randomUUID()}`);
+			const mode = stat?.mode ?? 420;
+			await fs.writeFile(temporaryPath, change.content, {
+				flag: "wx",
+				mode
+			});
+			staged.push({
+				...change,
+				original,
+				mode,
+				temporaryPath
+			});
+		}
+	} catch (error) {
+		await remove(staged.map((change) => change.temporaryPath));
+		throw error;
+	}
+	const replaced = [];
+	try {
+		for (const change of staged) {
+			await replace(change.temporaryPath, change.filePath);
+			replaced.push(change);
+		}
+	} catch {
+		const complete = await restore(replaced);
+		await remove(staged.map((change) => change.temporaryPath));
+		throw new Error(complete ? "File replacement failed; completed changes were rolled back." : "File replacement failed and rollback was incomplete.");
+	}
+}
+//#endregion
+export { writeFileChanges as t };

package/dist/file-changes-cmFN-rF8.d.ts

@@ -0,0 +1,11 @@
+//#region src/file-changes.d.ts
+interface FileChange {
+  readonly filePath: string;
+  readonly content: string;
+}
+interface FileChangeWriterOptions {
+  readonly replace?: (temporaryPath: string, filePath: string) => Promise<void>;
+}
+declare function writeFileChanges(changes: readonly FileChange[], options?: FileChangeWriterOptions): Promise<void>;
+//#endregion
+export { writeFileChanges as n, FileChange as t };

package/dist/guardrails-vH9lYg05.js

@@ -0,0 +1,121 @@
+import path from "node:path";
+//#region src/bin/guardrails.ts
+const descriptions = {
+	check: "Run analysis, lint, typecheck, tests, and build",
+	doctor: "Diagnose environment and Askr project health",
+	repair: "Apply safe fixes and report remaining semantic work"
+};
+function helpText(command) {
+	return `askr ${command} - ${descriptions[command]}
+
+Usage:
+  askr ${command} [--cwd <dir>] [--workspace <pattern>]... [--json]
+
+Options:
+  --cwd <dir>             Resolve a project from another directory
+  --workspace <pattern>   Select workspace names for analysis (repeatable)
+  --json                  Emit one deterministic JSON object
+  --help, -h              Show this help message
+`;
+}
+function optionValue(args, index, option) {
+	const value = args[index + 1];
+	if (!value || value.startsWith("-")) throw new Error(`${option} requires a value`);
+	return value;
+}
+function parseGuardrailArgs(args) {
+	let cwd = process.cwd();
+	const workspacePatterns = [];
+	let json = false;
+	let help = false;
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--help" || argument === "-h") help = true;
+		else if (argument === "--json") json = true;
+		else if (argument === "--cwd") {
+			cwd = path.resolve(optionValue(args, index, "--cwd"));
+			index += 1;
+		} else if (argument.startsWith("--cwd=")) {
+			const value = argument.slice(6);
+			if (!value) throw new Error("--cwd requires a value");
+			cwd = path.resolve(value);
+		} else if (argument === "--workspace") {
+			workspacePatterns.push(optionValue(args, index, "--workspace"));
+			index += 1;
+		} else if (argument.startsWith("--workspace=")) {
+			const value = argument.slice(12);
+			if (!value) throw new Error("--workspace requires a value");
+			workspacePatterns.push(value);
+		} else throw new Error(`Unknown option: ${argument}`);
+	}
+	return {
+		cwd,
+		workspacePatterns,
+		json,
+		help
+	};
+}
+function formatDiagnostic(diagnostic) {
+	const remediation = diagnostic.remediation ? `\n  ${diagnostic.remediation}` : "";
+	return `${diagnostic.workspace}:${diagnostic.file}:${diagnostic.line}:${diagnostic.column} ${diagnostic.severity.toUpperCase()} ${diagnostic.ruleId} ${diagnostic.message}${remediation}`;
+}
+function printDiagnostics(analysis, io) {
+	for (const diagnostic of analysis.diagnostics) io.log(formatDiagnostic(diagnostic));
+}
+function formatFinding(finding) {
+	return `${finding.status === "pass" ? "PASS" : finding.status === "warning" ? "WARN" : "FAIL"} ${finding.id} ${finding.message}${finding.remediation ? `\n  ${finding.remediation}` : ""}`;
+}
+function printDoctor(report, io) {
+	for (const finding of report.findings) io.log(formatFinding(finding));
+	printDiagnostics(report.analysis, io);
+	io.log(`Doctor: ${report.summary.passed} passed, ${report.summary.warnings} warning(s), ${report.summary.errors} error(s).`);
+}
+function printRepair(report, io) {
+	for (const fix of report.analysis.appliedFixes) io.log(`fixed ${fix.file} ${fix.ruleId}: ${fix.description}`);
+	printDiagnostics(report.analysis, io);
+	io.log(`Repair: ${report.analysis.summary.appliedFixes} safe fix(es) applied, ${report.analysis.summary.diagnostics} finding(s) remain.`);
+	io.log(report.nextAction);
+}
+function printCheck(report, io) {
+	printDiagnostics(report.analysis, io);
+	for (const script of report.scripts) {
+		if (script.stdout.trim()) io.log(script.stdout.trimEnd());
+		if (script.stderr.trim()) io.error(script.stderr.trimEnd());
+		const marker = script.status === "passed" ? "PASS" : script.status === "failed" ? "FAIL" : "SKIP";
+		io.log(`${marker} ${script.command}${script.reason ? ` (${script.reason})` : ""}`);
+	}
+	io.log(`Check ${report.status}: ${report.analysis.summary.errors} analysis error(s), ${report.analysis.summary.warnings} warning(s), ${report.scripts.filter((entry) => entry.status === "passed").length} script(s) passed.`);
+}
+async function runGuardrailCli(command, args = process.argv.slice(2), io = console, runtime = {}) {
+	const wantsJson = args.includes("--json");
+	try {
+		const parsed = parseGuardrailArgs(args);
+		if (parsed.help) {
+			io.log(helpText(command).trimEnd());
+			return 0;
+		}
+		const options = {
+			cwd: parsed.cwd,
+			workspacePatterns: parsed.workspacePatterns
+		};
+		const { runCheck, runDoctor, runRepair } = await import("./runner-tPGn2CQC.js");
+		const report = command === "doctor" ? await runDoctor(options, runtime) : command === "repair" ? await runRepair(options) : await runCheck(options, runtime);
+		if (parsed.json) io.log(JSON.stringify(report));
+		else if (report.command === "doctor") printDoctor(report, io);
+		else if (report.command === "repair") printRepair(report, io);
+		else printCheck(report, io);
+		if (report.command === "doctor") return report.summary.errors > 0 ? 1 : 0;
+		if (report.command === "repair") return report.status === "clean" ? 0 : 1;
+		return report.status === "passed" ? 0 : 1;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		io.error(wantsJson ? JSON.stringify({
+			schemaVersion: 1,
+			status: "error",
+			error: message
+		}) : message);
+		return 1;
+	}
+}
+//#endregion
+export { runGuardrailCli };

package/dist/{planner-BDfYDKnI.js → planner-BEfWRd0x.js}

@@ -296,8 +296,8 @@ function solveWorkspace(workspace, selectedOccurrences, context, packuments, tag
 			const next = remaining.map((name) => [name, pruned.get(name)]).sort(([leftName, left], [rightName, right]) => left.length - right.length || leftName.localeCompare(rightName))[0];
 			const signature = component.map((name) => {
 				const assignedVersion = assigned.get(name);
-				if (assignedVersion !== void 0) return `${name}=assigned:${assignedVersion}`;
-				return `${name}=domain:${(pruned.get(name) ?? []).join(",")}`;
+				const domain = pruned.get(name) ?? [];
+				return `${name}:assigned=${JSON.stringify(assignedVersion ?? null)}:domain=${JSON.stringify(domain)}`;
 			}).join("|");
 			if (memo.has(signature)) return;
 			memo.add(signature);
@@ -352,7 +352,7 @@ function summarize(decisions) {
 function planUpdates(options) {
 	const failures = options.failures ?? /* @__PURE__ */ new Map();
 	const tags = options.tags ?? {};
-	const mode = options.mode ?? "update";
+	const mode = options.mode ?? (options.force ? "upgrade" : "update");
 	const context = options.contextOccurrences ?? options.occurrences;
 	const workspaceSolutions = /* @__PURE__ */ new Map();
 	if (mode !== "force") for (const workspace of new Set(options.occurrences.map((entry) => entry.workspace))) workspaceSolutions.set(workspace, solveWorkspace(workspace, options.occurrences.filter((entry) => entry.workspace === workspace), context, options.packuments, tags, options.cliTag, options.localVersions ?? /* @__PURE__ */ new Map(), mode));