ultimate-pi 0.20.0 → 0.22.1

package/.pi/scripts/harness-git-churn.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * Optional git churn map (path → commit count) for Sentrux hotspot scoring.
+ *
+ * Usage:
+ *   node harness-git-churn.mjs [--root <PROJECT_ROOT>] [--days 14]
+ */
+
+import { spawn } from "node:child_process";
+import { resolveSentruxProjectRoot, takeRootArg } from "../lib/harness-sentrux-root.mjs";
+
+function runGit(args, cwd) {
+	return new Promise((resolve, reject) => {
+		const child = spawn("git", args, { cwd, env: process.env });
+		let stdout = "";
+		let stderr = "";
+		child.stdout?.on("data", (c) => {
+			stdout += c.toString();
+		});
+		child.stderr?.on("data", (c) => {
+			stderr += c.toString();
+		});
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code !== 0) {
+				reject(new Error(stderr.trim() || `git exit ${code}`));
+				return;
+			}
+			resolve(stdout);
+		});
+	});
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {{ days?: number }} opts
+ * @returns {Promise<Record<string, number>>}
+ */
+export async function loadGitChurn(projectRoot, opts = {}) {
+	const days = opts.days ?? 14;
+	const since = `${days} days ago`;
+	const stdout = await runGit(
+		[
+			"log",
+			`--since=${since}`,
+			"--name-only",
+			"--pretty=format:",
+		],
+		projectRoot,
+	);
+	const counts = {};
+	for (const line of stdout.split(/\r?\n/)) {
+		const path = line.trim();
+		if (!path || path.startsWith(".")) continue;
+		counts[path] = (counts[path] || 0) + 1;
+	}
+	return counts;
+}
+
+async function main() {
+	const { args, explicitRoot } = takeRootArg(process.argv.slice(2));
+	let days = 14;
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === "--days") days = Number.parseInt(args[++i] || "14", 10);
+	}
+	const root = await resolveSentruxProjectRoot(explicitRoot);
+	const map = await loadGitChurn(root, { days });
+	process.stdout.write(`${JSON.stringify(map, null, 2)}\n`);
+}
+
+const isMain = process.argv[1]?.endsWith("harness-git-churn.mjs");
+if (isMain) {
+	main().catch((err) => {
+		console.error(err.message || err);
+		process.exit(1);
+	});
+}

package/.pi/scripts/harness-git-commit.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * Git commit with merged .pi/auto-commit.json message format + co-author trailer.
+ *
+ * Usage:
+ *   node "$UP_PKG/.pi/scripts/harness-git-commit.mjs" \
+ *     --subject "..." [--type fix] [--scope app] [--body "..."] \
+ *     [--message "full body"] [--amend] [--print-message] [--root DIR] \
+ *     [--dry-run] [--no-verify] [--signoff]
+ *
+ * Does not run git add — stage files first.
+ */
+
+import { writeFile, unlink, mkdtemp, access, constants } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import {
+	buildFullCommitMessage,
+	resolveAutoCommitConfig,
+} from "../lib/harness-auto-commit-config.mjs";
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const UP_PKG = join(SCRIPT_DIR, "..", "..");
+
+function parseArgs(argv) {
+	const flags = new Set();
+	const opts = {};
+	const positional = [];
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--dry-run") flags.add("dry-run");
+		else if (a === "--print-message") flags.add("print-message");
+		else if (a === "--amend") flags.add("amend");
+		else if (a === "--no-verify") flags.add("no-verify");
+		else if (a === "--signoff") flags.add("signoff");
+		else if (a === "--subject" && argv[i + 1]) opts.subject = argv[++i];
+		else if (a === "--type" && argv[i + 1]) opts.type = argv[++i];
+		else if (a === "--scope" && argv[i + 1]) opts.scope = argv[++i];
+		else if (a === "--body" && argv[i + 1]) opts.body = argv[++i];
+		else if (a === "--message" && argv[i + 1]) opts.message = argv[++i];
+		else if (a === "--root" && argv[i + 1]) opts.root = argv[++i];
+		else if (a.startsWith("-")) {
+			console.error(`harness-git-commit: unknown flag ${a}`);
+			process.exit(1);
+		} else positional.push(a);
+	}
+	return { flags, opts, positional };
+}
+
+function runGit(args, cwd) {
+	return new Promise((resolve, reject) => {
+		const child = spawn("git", args, {
+			cwd,
+			env: process.env,
+			shell: false,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		let stdout = "";
+		let stderr = "";
+		child.stdout?.on("data", (c) => {
+			stdout += c.toString();
+		});
+		child.stderr?.on("data", (c) => {
+			stderr += c.toString();
+		});
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code !== 0) {
+				reject(new Error(stderr.trim() || stdout.trim() || `git exit ${code}`));
+				return;
+			}
+			resolve(stdout);
+		});
+	});
+}
+
+async function fileExists(path) {
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function resolveUpPkg() {
+	const resolver = join(SCRIPT_DIR, "harness-resolve-up-pkg.mjs");
+	if (await fileExists(resolver)) {
+		const { spawnSync } = await import("node:child_process");
+		const r = spawnSync(process.execPath, [resolver], {
+			encoding: "utf-8",
+			shell: false,
+		});
+		if (r.status === 0 && r.stdout?.trim()) {
+			return r.stdout.trim();
+		}
+	}
+	return UP_PKG;
+}
+
+async function main() {
+	const { flags, opts, positional } = parseArgs(process.argv.slice(2));
+	const projectRoot = opts.root ?? positional[0] ?? process.cwd();
+	const upPkg = await resolveUpPkg();
+
+	const projectConfigPath = join(projectRoot, ".pi", "auto-commit.json");
+	if (!(await fileExists(projectConfigPath))) {
+		console.warn(
+			"harness-git-commit: hint — run node \"$UP_PKG/.pi/scripts/harness-auto-commit-bootstrap.mjs\" to seed .pi/auto-commit.json",
+		);
+	}
+
+	const config = await resolveAutoCommitConfig(projectRoot, upPkg);
+	if (config.dryRun === true && !flags.has("dry-run")) {
+		console.warn(
+			"harness-git-commit: warning — dryRun is true in config; pass --dry-run explicitly to preview without committing",
+		);
+	}
+
+	const dryRun =
+		flags.has("dry-run") ||
+		process.env.HARNESS_GIT_COMMIT_DRY_RUN === "1";
+
+	let input = {
+		type: opts.type,
+		scope: opts.scope,
+		subject: opts.subject,
+		body: opts.body,
+		message: opts.message,
+	};
+
+	if (flags.has("amend") && !input.message) {
+		const prior = await runGit(
+			["log", "-1", "--format=%B"],
+			projectRoot,
+		).catch(() => "");
+		if (prior.trim()) {
+			input = { message: prior.trim() };
+		}
+	}
+
+	const fullMessage = buildFullCommitMessage(config, input);
+
+	if (flags.has("print-message") || dryRun) {
+		process.stdout.write(`${fullMessage}\n`);
+		return;
+	}
+
+	await runGit(["rev-parse", "--git-dir"], projectRoot);
+
+	const tmpDir = await mkdtemp(join(tmpdir(), "harness-git-commit-"));
+	const msgFile = join(tmpDir, "COMMIT_EDITMSG");
+	try {
+		await writeFile(msgFile, `${fullMessage}\n`, "utf-8");
+		const gitArgs = ["commit", "-F", msgFile];
+		if (flags.has("amend")) gitArgs.push("--amend");
+		if (flags.has("no-verify")) gitArgs.push("--no-verify");
+		if (flags.has("signoff")) gitArgs.push("--signoff");
+
+		const out = await runGit(gitArgs, projectRoot);
+		if (out.trim()) process.stdout.write(out);
+		console.log("harness-git-commit: committed with co-author trailer");
+	} finally {
+		await unlink(msgFile).catch(() => {});
+	}
+}
+
+main().catch((err) => {
+	console.error(`harness-git-commit: ${err.message}`);
+	process.exit(1);
+});

package/.pi/scripts/harness-ls-lint-bootstrap.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * Idempotent ls-lint naming bootstrap for harness projects.
+ *
+ * 1. Seeds `.pi/harness/ls-lint/naming.manifest.json` from the package template when missing
+ * 2. Personalizes `project` on first seed from target package.json / directory name
+ * 3. Runs `ls-lint-rules-sync.mjs` (merge-safe; preserves custom YAML outside managed markers)
+ *
+ * Usage:
+ *   node "$UP_PKG/.pi/scripts/harness-ls-lint-bootstrap.mjs" [PROJECT_ROOT] [--force] [--check]
+ */
+
+import { readFile, writeFile, mkdir, access, copyFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { join, dirname, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const UP_PKG = join(SCRIPT_DIR, "..", "..");
+
+const args = process.argv.slice(2).filter((a) => !a.startsWith("-"));
+const flags = process.argv.slice(2).filter((a) => a.startsWith("-"));
+const force = flags.includes("--force");
+const checkOnly = flags.includes("--check");
+
+const PROJECT_ROOT = args[0] || process.cwd();
+const MANIFEST = join(
+	PROJECT_ROOT,
+	".pi",
+	"harness",
+	"ls-lint",
+	"naming.manifest.json",
+);
+const MANIFEST_TEMPLATE = join(
+	UP_PKG,
+	".pi",
+	"harness",
+	"ls-lint",
+	"naming.manifest.json",
+);
+const SYNC_SCRIPT = join(SCRIPT_DIR, "ls-lint-rules-sync.mjs");
+
+async function fileExists(path) {
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function resolveProjectName(root) {
+	const pkgPath = join(root, "package.json");
+	if (await fileExists(pkgPath)) {
+		try {
+			const pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
+			if (typeof pkg.name === "string" && pkg.name.trim()) {
+				return pkg.name.trim();
+			}
+		} catch {
+			/* ignore */
+		}
+	}
+	return basename(root) || "project";
+}
+
+async function seedManifestIfMissing() {
+	if (await fileExists(MANIFEST)) {
+		return { seeded: false };
+	}
+	if (!(await fileExists(MANIFEST_TEMPLATE))) {
+		console.error(
+			"harness-ls-lint-bootstrap: missing package template",
+			MANIFEST_TEMPLATE,
+		);
+		process.exit(1);
+	}
+	await mkdir(dirname(MANIFEST), { recursive: true });
+	await copyFile(MANIFEST_TEMPLATE, MANIFEST);
+	const projectName = await resolveProjectName(PROJECT_ROOT);
+	const manifest = JSON.parse(await readFile(MANIFEST, "utf-8"));
+	manifest.project = projectName;
+	await writeFile(MANIFEST, `${JSON.stringify(manifest, null, 2)}\n`, "utf-8");
+	console.log(
+		`harness-ls-lint-bootstrap: seeded manifest -> ${MANIFEST} (project: ${projectName})`,
+	);
+	return { seeded: true, projectName };
+}
+
+function runSync(extraArgs) {
+	return new Promise((resolve) => {
+		const child = spawn(
+			process.execPath,
+			[SYNC_SCRIPT, ...extraArgs, PROJECT_ROOT],
+			{
+				cwd: PROJECT_ROOT,
+				stdio: ["ignore", "pipe", "pipe"],
+				env: process.env,
+			},
+		);
+		let out = "";
+		child.stdout?.on("data", (d) => {
+			out += d.toString();
+		});
+		child.stderr?.on("data", (d) => {
+			out += d.toString();
+		});
+		child.on("close", (code) => resolve({ code: code ?? 1, out: out.trim() }));
+		child.on("error", (err) =>
+			resolve({ code: 1, out: String(err.message) }),
+		);
+	});
+}
+
+async function main() {
+	const { seeded } = await seedManifestIfMissing();
+	if (!seeded) {
+		console.log(
+			"harness-ls-lint-bootstrap: manifest present (edit naming rules there, then re-run with --force)",
+		);
+	}
+
+	const syncArgs = [];
+	if (checkOnly) syncArgs.push("--check");
+	else if (force) syncArgs.push("--force");
+
+	const { code, out } = await runSync(syncArgs);
+	if (out) console.log(out);
+	if (code !== 0) process.exit(code);
+
+	if (!checkOnly && !force) {
+		console.log(
+			'harness-ls-lint-bootstrap: done (idempotent). After manifest edits: node "$UP_PKG/.pi/scripts/harness-ls-lint-bootstrap.mjs" --force',
+		);
+	}
+}
+
+main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});

package/.pi/scripts/harness-ls-lint-cli.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+/**
+ * Run ls-lint against the harness project root.
+ *
+ * ls-lint reads `.ls-lint.yml` from the working directory. Harness commands must
+ * find the nearest ancestor with harness naming config and run from that root.
+ *
+ * Usage:
+ *   node "$UP_PKG/.pi/scripts/harness-ls-lint-cli.mjs" [--root <PROJECT_ROOT>]
+ *   node "$UP_PKG/.pi/scripts/harness-ls-lint-cli.mjs" --print-root
+ *   node "$UP_PKG/.pi/scripts/harness-ls-lint-cli.mjs" --json
+ */
+
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { spawn, execSync } from "node:child_process";
+
+const ROOT_MARKERS = [
+	".ls-lint.yml",
+	join(".pi", "harness", "ls-lint", "naming.manifest.json"),
+];
+
+async function fileExists(path) {
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function hasRootMarker(dir) {
+	for (const marker of ROOT_MARKERS) {
+		if (await fileExists(join(dir, marker))) return true;
+	}
+	return false;
+}
+
+async function findProjectRoot(startDir) {
+	let dir = resolve(startDir || process.cwd());
+	while (true) {
+		if (await hasRootMarker(dir)) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+function takeRootArg(args) {
+	const next = [];
+	let explicitRoot = process.env.HARNESS_PROJECT_ROOT || "";
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--root") {
+			explicitRoot = args[i + 1] || "";
+			i++;
+			continue;
+		}
+		if (arg.startsWith("--root=")) {
+			explicitRoot = arg.slice("--root=".length);
+			continue;
+		}
+		next.push(arg);
+	}
+	return { args: next, explicitRoot };
+}
+
+async function resolveProjectRoot(explicitRoot) {
+	if (explicitRoot) {
+		const root = isAbsolute(explicitRoot)
+			? resolve(explicitRoot)
+			: resolve(process.cwd(), explicitRoot);
+		if (!(await hasRootMarker(root))) {
+			console.error(
+				`harness-ls-lint-cli: ${root} has no .ls-lint.yml or .pi/harness/ls-lint/naming.manifest.json`,
+			);
+			process.exit(1);
+		}
+		return root;
+	}
+
+	const root = await findProjectRoot(process.cwd());
+	if (!root) {
+		console.error(
+			"harness-ls-lint-cli: could not find a harness project root above the current directory",
+		);
+		process.exit(1);
+	}
+	return root;
+}
+
+function countViolations(output) {
+	const m = output.match(/(\d+)\s+violations?/i);
+	if (m) return Number.parseInt(m[1], 10);
+	if (/0\s+violations/i.test(output) || /no\s+violations/i.test(output)) {
+		return 0;
+	}
+	return output ? 1 : 0;
+}
+
+function lintPathEnv() {
+	const extra = [
+		process.env.PATH,
+		`${process.env.HOME || ""}/.local/bin`,
+	].filter(Boolean);
+	try {
+		const npmBin = execSync("npm prefix -g", { encoding: "utf-8" }).trim();
+		extra.push(`${npmBin}/bin`);
+	} catch {
+		/* ignore */
+	}
+	return { ...process.env, PATH: extra.join(":") };
+}
+
+async function runLsLint(projectRoot) {
+	return new Promise((resolve) => {
+		const child = spawn("ls-lint", [], {
+			cwd: projectRoot,
+			stdio: ["ignore", "pipe", "pipe"],
+			env: lintPathEnv(),
+		});
+		let out = "";
+		child.stdout?.on("data", (d) => {
+			out += d.toString();
+		});
+		child.stderr?.on("data", (d) => {
+			out += d.toString();
+		});
+		child.on("close", (code) => {
+			resolve({ code: code ?? 1, out: out.trim() });
+		});
+		child.on("error", (err) => {
+			if (err?.code === "ENOENT") {
+				resolve({ code: 127, out: "ls-lint not installed" });
+				return;
+			}
+			resolve({ code: 1, out: String(err.message) });
+		});
+	});
+}
+
+async function main() {
+	const parsed = takeRootArg(process.argv.slice(2));
+	const printRoot = parsed.args.includes("--print-root");
+	const jsonOut = parsed.args.includes("--json");
+	const projectRoot = await resolveProjectRoot(parsed.explicitRoot);
+
+	if (printRoot) {
+		console.log(projectRoot);
+		return;
+	}
+
+	const { code, out } = await runLsLint(projectRoot);
+
+	if (jsonOut) {
+		const payload = {
+			lint_pass: code === 0,
+			violation_count: code === 0 ? 0 : countViolations(out),
+			status:
+				code === 127
+					? "not_installed"
+					: code === 0
+						? "pass"
+						: "fail",
+			quality_signal_summary: out.slice(0, 500) || (code === 0 ? "pass" : "fail"),
+			project_root: projectRoot,
+		};
+		console.log(JSON.stringify(payload));
+		process.exit(code === 127 ? 0 : code);
+	}
+
+	if (out) {
+		if (code === 0) console.log(out);
+		else console.error(out);
+	}
+
+	process.exit(code === 127 ? 127 : code);
+}
+
+main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});

package/.pi/scripts/harness-seed-project-contracts.mjs

@@ -15,6 +15,7 @@ import { copyFile, mkdir, readdir, access } from "node:fs/promises";
 import { constants } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
 
 const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
 const UP_PKG = join(SCRIPT_DIR, "..", "..");
@@ -26,6 +27,13 @@ const SENTRUX_TEMPLATE = join(
 	"sentrux",
 	"architecture.manifest.json",
 );
+const LS_LINT_TEMPLATE = join(
+	UP_PKG,
+	".pi",
+	"harness",
+	"ls-lint",
+	"naming.manifest.json",
+);
 
 const projectRoot = process.argv[2] || process.cwd();
 const specDest = join(projectRoot, ".pi", "harness", "specs");
@@ -36,6 +44,13 @@ const sentruxDest = join(
 	"sentrux",
 	"architecture.manifest.json",
 );
+const lsLintDest = join(
+	projectRoot,
+	".pi",
+	"harness",
+	"ls-lint",
+	"naming.manifest.json",
+);
 
 async function fileExists(path) {
 	try {
@@ -73,6 +88,38 @@ async function main() {
 			`harness-seed-project-contracts: seeded Sentrux manifest -> ${sentruxDest} (run harness-sentrux-bootstrap.mjs to sync rules.toml)`,
 		);
 	}
+
+	if (!(await fileExists(lsLintDest)) && (await fileExists(LS_LINT_TEMPLATE))) {
+		await mkdir(dirname(lsLintDest), { recursive: true });
+		await copyFile(LS_LINT_TEMPLATE, lsLintDest);
+		console.log(
+			`harness-seed-project-contracts: seeded ls-lint manifest -> ${lsLintDest} (run harness-ls-lint-bootstrap.mjs to sync .ls-lint.yml)`,
+		);
+	}
+
+	const autoCommitBootstrap = join(
+		UP_PKG,
+		".pi",
+		"scripts",
+		"harness-auto-commit-bootstrap.mjs",
+	);
+	const autoCommitDest = join(projectRoot, ".pi", "auto-commit.json");
+	if (
+		!(await fileExists(autoCommitDest)) &&
+		(await fileExists(autoCommitBootstrap))
+	) {
+		await new Promise((resolve, reject) => {
+			const child = spawn(
+				process.execPath,
+				[autoCommitBootstrap, projectRoot],
+				{ cwd: projectRoot, stdio: "inherit", env: process.env },
+			);
+			child.on("error", reject);
+			child.on("close", (code) =>
+				code === 0 ? resolve() : reject(new Error(`bootstrap exit ${code}`)),
+			);
+		});
+	}
 }
 
 main().catch((err) => {