@noctcore/harness 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# @noctcore/harness
+
+A **portable Structure-Lock runner**. It reads a repo's `.nightcore/harness.json` and runs each
+declared check, reddening the build on any violation — so a project's structure lock is enforced in
+its **own CI**, with no Nightcore install, no server, and no account.
+
+```bash
+npx @noctcore/harness check
+```
+
+Run it from the repo root (or pass `--dir <path>`). If there is no `.nightcore/harness.json`, the
+runner exits `0` — the lock is opt-in-by-presence.
+
+## What it does
+
+For every enabled check that declares a `command`, the runner prints the command, runs it in the
+target directory (bounded by the check's `timeoutMs`, default 5 minutes), and records the outcome.
+It runs **all** checks (it does not stop at the first failure), so one CI run shows the whole
+failure set. It exits `0` when every check passed and `1` when any failed (printing a fix
+instruction that lists each failed check with its command and captured output). `--json` emits a
+machine-readable result to stdout instead.
+
+```
+harness [check] [--dir <path>] [--json] [--version] [--help]
+```
+
+## What it is NOT
+
+- **Not a SaaS or telemetry.** The runner makes zero network calls at run time. Everything it reads
+  is committed in your repo. It has zero runtime dependencies.
+- **Not an integrity attestation.** It enforces **whatever checks are present** in your
+  `.nightcore/harness.json` and your committed rule files. It does **not** verify that those files
+  match what Nightcore originally generated — the artifacts are yours to edit. A weakened rule is
+  enforced in its weakened form. The control against silent weakening is **PR review of the diff**
+  (a re-export or a hand-edit shows up in `git diff`), not a signature or hash check.
+
+The `command` strings in `.nightcore/harness.json` are executed. In your own CI this is the same
+trust level as any `package.json` script or workflow step — your own committed, PR-reviewed config.
+The runner prints every command before running it so a reviewer reading CI logs sees exactly what
+executed.
+
+## Requirements
+
+Node ≥ 22.

package/dist/cli.cjs

@@ -0,0 +1,506 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cli.ts
+var cli_exports = {};
+__export(cli_exports, {
+  nodeIO: () => nodeIO,
+  runCli: () => runCli
+});
+module.exports = __toCommonJS(cli_exports);
+var import_node_child_process2 = require("child_process");
+var import_node_fs2 = require("fs");
+var import_node_path3 = __toESM(require("path"), 1);
+var import_node_process = __toESM(require("process"), 1);
+var import_node_url2 = require("url");
+
+// src/lint-meta/ctx.ts
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
+var import_node_path = __toESM(require("path"), 1);
+function toPosixRel(rel) {
+  return rel.replace(/\\/g, "/");
+}
+function normalizeText(text) {
+  return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+var EXEC_MAX_BUFFER = 16 * 1024 * 1024;
+function createNodeCtx(root) {
+  return {
+    root,
+    read(rel) {
+      const abs = import_node_path.default.join(root, toPosixRel(rel));
+      if (!(0, import_node_fs.existsSync)(abs)) return null;
+      return normalizeText((0, import_node_fs.readFileSync)(abs, "utf8"));
+    },
+    exists(rel) {
+      return (0, import_node_fs.existsSync)(import_node_path.default.join(root, toPosixRel(rel)));
+    },
+    glob(pattern) {
+      return Array.from((0, import_node_fs.globSync)(pattern, { cwd: root })).map(toPosixRel);
+    },
+    exec(cmd) {
+      const res = (0, import_node_child_process.spawnSync)(cmd, {
+        cwd: root,
+        shell: true,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        maxBuffer: EXEC_MAX_BUFFER
+      });
+      return {
+        code: typeof res.status === "number" ? res.status : 1,
+        stdout: res.stdout ?? "",
+        stderr: res.stderr ?? ""
+      };
+    }
+  };
+}
+
+// src/lint-meta/registry.ts
+var import_node_url = require("url");
+var DEFAULT_REGISTRY_RELATIVE_PATH = ".nightcore/lint-meta/registry.js";
+var defaultImporter = (absPath) => import((0, import_node_url.pathToFileURL)(absPath).href);
+function isMetaRule(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const r = v;
+  return typeof r.id === "string" && typeof r.run === "function";
+}
+function extractRules(mod) {
+  if (typeof mod !== "object" || mod === null) return null;
+  const m = mod;
+  const def = m.default;
+  const candidates = [
+    m.META_RULES,
+    def?.META_RULES,
+    m.default
+  ];
+  for (const candidate of candidates) {
+    if (Array.isArray(candidate) && candidate.every(isMetaRule)) return candidate;
+  }
+  return null;
+}
+async function loadRegistry(absRegistryPath, importer = defaultImporter) {
+  let mod;
+  try {
+    mod = await importer(absRegistryPath);
+  } catch (err) {
+    return { rules: [], error: err instanceof Error ? err.message : String(err) };
+  }
+  const rules = extractRules(mod);
+  if (rules === null) {
+    return {
+      rules: [],
+      error: "the registry must export `META_RULES` (a named export, or the default) as an array of { id, run } rule objects"
+    };
+  }
+  return { rules };
+}
+
+// src/lint-meta/run.ts
+function runMetaRules(rules, ctx, onRule) {
+  const outcomes = [];
+  for (const rule of rules) {
+    onRule?.(rule);
+    const ciCritical = rule.ciCritical === true;
+    try {
+      outcomes.push({ id: rule.id, ciCritical, violations: rule.run(ctx), threw: null });
+    } catch (err) {
+      outcomes.push({
+        id: rule.id,
+        ciCritical,
+        violations: [],
+        threw: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  return outcomes;
+}
+function reportMetaOutcomes(outcomes) {
+  let criticalCount = 0;
+  let totalViolations = 0;
+  const lines = [];
+  for (const outcome of outcomes) {
+    if (outcome.threw !== null) {
+      lines.push(`[ERROR] ${outcome.id}: rule threw \u2014 ${outcome.threw}`);
+      criticalCount += 1;
+      continue;
+    }
+    for (const v of outcome.violations) {
+      totalViolations += 1;
+      const tag = outcome.ciCritical ? "ERROR" : "info";
+      lines.push(`[${tag}] ${v.rule} (${v.file}): ${v.message}`);
+      if (outcome.ciCritical) criticalCount += 1;
+    }
+  }
+  return { criticalCount, totalViolations, lines };
+}
+function exitCodeFor(report) {
+  return report.criticalCount > 0 ? 1 : 0;
+}
+
+// src/manifest.ts
+var import_node_path2 = __toESM(require("path"), 1);
+var MANIFEST_RELATIVE_PATH = import_node_path2.default.join(".nightcore", "harness.json");
+var DEFAULT_CHECK_TIMEOUT_MS = 3e5;
+var SUPPORTED_SCHEMA_MAJOR = 1;
+function manifestPath(dir) {
+  return import_node_path2.default.join(dir, MANIFEST_RELATIVE_PATH);
+}
+function resolveSchema(raw) {
+  if (raw === void 0 || raw === null) return { tooNew: false, found: SUPPORTED_SCHEMA_MAJOR };
+  const n = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(n)) return { tooNew: true, found: Number.NaN };
+  const major = Math.floor(n);
+  return { tooNew: major > SUPPORTED_SCHEMA_MAJOR, found: major };
+}
+function planCheck(entry) {
+  if (typeof entry !== "object" || entry === null) return null;
+  const cfg = entry;
+  if (typeof cfg.name !== "string" || cfg.name.trim() === "") return null;
+  if (cfg.enabled === false) return null;
+  const kind = typeof cfg.kind === "string" ? cfg.kind : "";
+  if (kind === "shell") return null;
+  const command = typeof cfg.command === "string" ? cfg.command.trim() : "";
+  if (command === "") return null;
+  const tokens = command.split(/\s+/).filter((t) => t.length > 0);
+  const program = tokens[0];
+  if (program === void 0) return null;
+  const args = tokens.slice(1);
+  const declared = cfg.timeoutMs;
+  const timeoutMs = typeof declared === "number" && Number.isFinite(declared) && declared > 0 ? Math.floor(declared) : DEFAULT_CHECK_TIMEOUT_MS;
+  return { name: cfg.name, kind, command, program, args, timeoutMs };
+}
+function loadChecks(dir, read) {
+  const raw = read(manifestPath(dir));
+  if (raw === null) return { kind: "no-config" };
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return { kind: "no-config" };
+  }
+  if (typeof value !== "object" || value === null) return { kind: "no-config" };
+  const root = value;
+  const schema = resolveSchema(root.schemaVersion);
+  if (schema.tooNew) return { kind: "schema-too-new", found: schema.found };
+  const entries = root.checks;
+  if (!Array.isArray(entries)) return { kind: "no-config" };
+  const checks = [];
+  for (const entry of entries) {
+    const planned = planCheck(entry);
+    if (planned !== null) checks.push(planned);
+  }
+  return { kind: "ready", checks };
+}
+
+// src/run.ts
+var TAIL_LIMIT = 4e3;
+function tailOutput(stdout, stderr) {
+  let combined = stdout;
+  if (stderr.length > 0) combined += `
+${stderr}`;
+  if (combined.length > TAIL_LIMIT) {
+    return `\u2026${combined.slice(combined.length - TAIL_LIMIT)}`;
+  }
+  return combined;
+}
+function timeoutMessage(timeoutMs) {
+  return `timed out after ${timeoutMs}ms (the check was killed; it may hang or need a higher timeoutMs)`;
+}
+function interpret(res, timeoutMs) {
+  const timedOut = res.error?.code === "ETIMEDOUT" || res.signal != null;
+  if (timedOut) {
+    return { status: "failed", output: timeoutMessage(timeoutMs) };
+  }
+  if (res.error) {
+    const detail = res.error.message ?? res.error.code ?? "unknown error";
+    return { status: "failed", output: `failed to launch: ${detail}` };
+  }
+  if (res.status === 0) {
+    return { status: "passed", exitCode: 0 };
+  }
+  return {
+    status: "failed",
+    exitCode: res.status ?? void 0,
+    output: tailOutput(res.stdout, res.stderr)
+  };
+}
+function emptyPass() {
+  return { passed: true, checks: [] };
+}
+function runChecks(planned, runDir, spawn, onCommand) {
+  if (planned.length === 0) return emptyPass();
+  const checks = [];
+  let failedCheck;
+  for (const check of planned) {
+    onCommand?.(check);
+    const start = Date.now();
+    const res = spawn(check.program, check.args, {
+      cwd: runDir,
+      timeoutMs: check.timeoutMs
+    });
+    const durationMs = Date.now() - start;
+    const outcome = interpret(res, check.timeoutMs);
+    if (outcome.status === "failed" && failedCheck === void 0) {
+      failedCheck = check.name;
+    }
+    checks.push({
+      name: check.name,
+      kind: check.kind,
+      command: check.command,
+      status: outcome.status,
+      exitCode: outcome.exitCode,
+      output: outcome.output,
+      durationMs
+    });
+  }
+  const result = { passed: failedCheck === void 0, checks };
+  if (failedCheck !== void 0) result.failedCheck = failedCheck;
+  return result;
+}
+function fixInstruction(result) {
+  const failed = result.checks.filter((c) => c.status === "failed");
+  if (failed.length === 0) {
+    return "The Structure-Lock check failed. Fix the project's harness checks before this work can be verified or merged.";
+  }
+  let out = `The Structure-Lock check failed: ${failed.length} project harness check${failed.length === 1 ? "" : "s"} did not pass. They MUST all pass before this work can be verified or merged. Re-run each one locally and fix every violation it reports:`;
+  for (const c of failed) {
+    out += `
+
+--- \`${c.name}\` ---
+Command: ${c.command}
+
+Output:
+${c.output ?? "(no output captured)"}`;
+  }
+  return out;
+}
+
+// src/cli.ts
+var import_meta = {};
+var HELP = `@noctcore/harness \u2014 portable Structure-Lock runner
+
+Usage:
+  harness [check] [options]      Run the checks declared in .nightcore/harness.json
+  harness lint-meta [options]    Run the portable lint-meta rules from the enumerated registry
+
+Options:
+  --dir <path>        Target directory to operate in (default: current directory)
+  --registry <path>   lint-meta only: the rule registry to load
+                      (default: ${DEFAULT_REGISTRY_RELATIVE_PATH}, relative to --dir)
+  --json              check only: emit the machine-readable result to stdout instead of a summary
+  --version           Print the runner version and exit
+  --help              Print this help and exit
+
+Exit codes:
+  0  every check/rule passed (or nothing is configured to enforce)
+  1  a check failed, a rule reported a critical violation or threw, or the manifest requires a newer runner
+  2  a usage error`;
+function parseArgs(argv, cwd) {
+  let command = "check";
+  let sawCommand = false;
+  let dir = cwd;
+  let registry;
+  let json = false;
+  let help = false;
+  let version = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === void 0) continue;
+    if (arg === "--json") {
+      json = true;
+    } else if (arg === "--help" || arg === "-h") {
+      help = true;
+    } else if (arg === "--version" || arg === "-v") {
+      version = true;
+    } else if (arg === "--dir") {
+      const next = argv[i + 1];
+      if (next !== void 0) {
+        dir = next;
+        i += 1;
+      }
+    } else if (arg.startsWith("--dir=")) {
+      dir = arg.slice("--dir=".length);
+    } else if (arg === "--registry") {
+      const next = argv[i + 1];
+      if (next !== void 0) {
+        registry = next;
+        i += 1;
+      }
+    } else if (arg.startsWith("--registry=")) {
+      registry = arg.slice("--registry=".length);
+    } else if (!arg.startsWith("-") && !sawCommand) {
+      command = arg;
+      sawCommand = true;
+    }
+  }
+  return { command, dir: import_node_path3.default.resolve(cwd, dir), registry, json, help, version };
+}
+function readVersion() {
+  try {
+    const raw = (0, import_node_fs2.readFileSync)(new URL("../package.json", import_meta.url), "utf8");
+    const pkg = JSON.parse(raw);
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+function nodeIO() {
+  return {
+    cwd: import_node_process.default.cwd(),
+    read(absolutePath) {
+      try {
+        return (0, import_node_fs2.readFileSync)(absolutePath, "utf8");
+      } catch {
+        return null;
+      }
+    },
+    spawn(program, args, options) {
+      const res = (0, import_node_child_process2.spawnSync)(program, args, {
+        cwd: options.cwd,
+        timeout: options.timeoutMs,
+        killSignal: "SIGKILL",
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        maxBuffer: 16 * 1024 * 1024
+      });
+      const err = res.error;
+      return {
+        status: res.status,
+        signal: res.signal,
+        stdout: res.stdout ?? "",
+        stderr: res.stderr ?? "",
+        error: err ? { code: err.code, message: err.message } : void 0
+      };
+    },
+    stdout: (line) => import_node_process.default.stdout.write(`${line}
+`),
+    stderr: (line) => import_node_process.default.stderr.write(`${line}
+`),
+    importModule: defaultImporter
+  };
+}
+function runCheck(parsed, io) {
+  const outcome = loadChecks(parsed.dir, io.read);
+  if (outcome.kind === "no-config") {
+    if (parsed.json) {
+      io.stdout(JSON.stringify(emptyPass()));
+    } else {
+      io.stdout("No structure lock configured \u2014 nothing to enforce.");
+    }
+    return 0;
+  }
+  if (outcome.kind === "schema-too-new") {
+    const label = Number.isFinite(outcome.found) ? String(outcome.found) : "an unrecognized value";
+    io.stderr(
+      `This .nightcore/harness.json declares schemaVersion ${label}, which this runner does not understand. This bundle was authored by a newer Nightcore \u2014 upgrade @noctcore/harness.`
+    );
+    return 1;
+  }
+  const result = runChecks(outcome.checks, parsed.dir, io.spawn, (check) => {
+    const line = `\u2192 ${check.name}: ${check.command}`;
+    if (parsed.json) io.stderr(line);
+    else io.stdout(line);
+  });
+  if (parsed.json) {
+    io.stdout(JSON.stringify(result));
+    return result.passed ? 0 : 1;
+  }
+  for (const check of result.checks) {
+    const mark = check.status === "passed" ? "\u2713" : "\u2717";
+    const exit = check.exitCode != null ? ` (exit ${check.exitCode})` : "";
+    io.stdout(`${mark} ${check.name}${exit}`);
+  }
+  if (result.passed) {
+    const n = result.checks.length;
+    io.stdout(`
+Structure lock passed (${n} check${n === 1 ? "" : "s"}).`);
+    return 0;
+  }
+  io.stderr(`
+${fixInstruction(result)}`);
+  return 1;
+}
+async function runLintMeta(parsed, io) {
+  const registryPath = parsed.registry ? import_node_path3.default.resolve(parsed.dir, parsed.registry) : import_node_path3.default.join(parsed.dir, DEFAULT_REGISTRY_RELATIVE_PATH);
+  if (io.read(registryPath) === null) {
+    io.stdout(
+      `No lint-meta registry at ${registryPath} \u2014 nothing to enforce. (Point --registry at your rule registry, or commit one at ${DEFAULT_REGISTRY_RELATIVE_PATH}.)`
+    );
+    return 0;
+  }
+  const loaded = await loadRegistry(registryPath, io.importModule ?? defaultImporter);
+  if (loaded.error !== void 0) {
+    io.stderr(`Failed to load the lint-meta registry at ${registryPath}: ${loaded.error}`);
+    return 1;
+  }
+  const n = loaded.rules.length;
+  io.stdout(`lint-meta: running ${n} rule${n === 1 ? "" : "s"} from ${registryPath}`);
+  const ctx = createNodeCtx(parsed.dir);
+  const outcomes = runMetaRules(loaded.rules, ctx, (rule) => io.stdout(`\u2192 ${rule.id}`));
+  const report = reportMetaOutcomes(outcomes);
+  for (const line of report.lines) io.stderr(line);
+  if (report.lines.length === 0) io.stdout("lint-meta: no violations");
+  return exitCodeFor(report);
+}
+function runCli(argv, io = nodeIO()) {
+  const parsed = parseArgs(argv, io.cwd);
+  if (parsed.help) {
+    io.stdout(HELP);
+    return 0;
+  }
+  if (parsed.version) {
+    io.stdout(readVersion());
+    return 0;
+  }
+  if (parsed.command === "check") return runCheck(parsed, io);
+  if (parsed.command === "lint-meta") return runLintMeta(parsed, io);
+  io.stderr(`Unknown command: ${parsed.command}. Run \`harness --help\`.`);
+  return 2;
+}
+function isMainModule() {
+  try {
+    const entry = import_node_process.default.argv[1];
+    if (entry === void 0) return false;
+    return (0, import_node_fs2.realpathSync)(entry) === (0, import_node_fs2.realpathSync)((0, import_node_url2.fileURLToPath)(import_meta.url));
+  } catch {
+    return false;
+  }
+}
+if (isMainModule()) {
+  void Promise.resolve(runCli(import_node_process.default.argv.slice(2))).then((code) => {
+    import_node_process.default.exit(code);
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  nodeIO,
+  runCli
+});

package/dist/cli.d.cts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { F as FileReader, S as SpawnFn } from './run-B6_KI2bV.cjs';
+
+/** Imports the module at an ABSOLUTE path. Real or faked (bounded-eval tests). */
+type ModuleImporter = (absPath: string) => Promise<unknown>;
+
+/** The side-effecting surface `runCli` depends on — real or faked in tests. */
+interface CliIO {
+    cwd: string;
+    read: FileReader;
+    spawn: SpawnFn;
+    stdout: (line: string) => void;
+    stderr: (line: string) => void;
+    /**
+     * Dynamic module import for the `lint-meta` bounded eval — real (`defaultImporter`)
+     * or a recording fake in tests. Optional: the `check` path never imports, and
+     * `runLintMeta` falls back to {@link defaultImporter} when it is absent.
+     */
+    importModule?: ModuleImporter;
+}
+/** The real Node-backed IO: `node:fs` reads and `node:child_process` spawns. */
+declare function nodeIO(): CliIO;
+/**
+ * Parse argv and dispatch. Returns the process exit code (never exits). The
+ * `check` path stays synchronous (`number`); the `lint-meta` path is async
+ * (bounded dynamic import), so the return type is `number | Promise<number>` and
+ * the bin entry awaits it.
+ */
+declare function runCli(argv: string[], io?: CliIO): number | Promise<number>;
+
+export { type CliIO, nodeIO, runCli };

package/dist/cli.d.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { F as FileReader, S as SpawnFn } from './run-B6_KI2bV.js';
+
+/** Imports the module at an ABSOLUTE path. Real or faked (bounded-eval tests). */
+type ModuleImporter = (absPath: string) => Promise<unknown>;
+
+/** The side-effecting surface `runCli` depends on — real or faked in tests. */
+interface CliIO {
+    cwd: string;
+    read: FileReader;
+    spawn: SpawnFn;
+    stdout: (line: string) => void;
+    stderr: (line: string) => void;
+    /**
+     * Dynamic module import for the `lint-meta` bounded eval — real (`defaultImporter`)
+     * or a recording fake in tests. Optional: the `check` path never imports, and
+     * `runLintMeta` falls back to {@link defaultImporter} when it is absent.
+     */
+    importModule?: ModuleImporter;
+}
+/** The real Node-backed IO: `node:fs` reads and `node:child_process` spawns. */
+declare function nodeIO(): CliIO;
+/**
+ * Parse argv and dispatch. Returns the process exit code (never exits). The
+ * `check` path stays synchronous (`number`); the `lint-meta` path is async
+ * (bounded dynamic import), so the return type is `number | Promise<number>` and
+ * the bin entry awaits it.
+ */
+declare function runCli(argv: string[], io?: CliIO): number | Promise<number>;
+
+export { type CliIO, nodeIO, runCli };