jorgex-stack 1.4.0 → 1.5.0

package/dist/cli.js

@@ -2,6 +2,7 @@
 
 // src/cli.ts
 import * as p6 from "@clack/prompts";
+import fs24 from "fs";
 import { pathToFileURL as pathToFileURL2 } from "url";
 
 // src/install.ts
@@ -5192,7 +5193,7 @@ function readOptional(file, fallback) {
 }
 function hashPiTarball(file) {
   const descriptor = fs23.openSync(file, "r");
-  const sha256 = createHash("sha256");
+  const sha2562 = createHash("sha256");
   const sha512 = createHash("sha512");
   const buffer = Buffer.allocUnsafe(1024 * 1024);
   let bytes = 0;
@@ -5202,13 +5203,13 @@ function hashPiTarball(file) {
       if (read === 0) break;
       bytes += read;
       const chunk = buffer.subarray(0, read);
-      sha256.update(chunk);
+      sha2562.update(chunk);
       sha512.update(chunk);
     }
   } finally {
     fs23.closeSync(descriptor);
   }
-  return { path: file, bytes, sha256: sha256.digest("hex"), sha512: sha512.digest("hex") };
+  return { path: file, bytes, sha256: sha2562.digest("hex"), sha512: sha512.digest("hex") };
 }
 async function acquirePiTarball(destination) {
   const existing = fs23.statSync(destination, { throwIfNoEntry: false });
@@ -5443,9 +5444,848 @@ async function runManagedPiSystem(input) {
   });
 }
 
+// src/lib/quality-runner.ts
+import path33 from "path";
+import { spawn, spawnSync as spawnSync2 } from "child_process";
+
+// src/lib/quality-policy.ts
+var QUALITY_PROFILES = ["routine", "elevated", "high", "release"];
+function hasText(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function isQualityProfile(value) {
+  return typeof value === "string" && QUALITY_PROFILES.includes(value);
+}
+function mergeStatus(current, next) {
+  if (current === "fail" || next === "fail") return "fail";
+  if (current === "incomplete" || next === "incomplete") return "incomplete";
+  return "pass";
+}
+function resultStatus(result) {
+  switch (result.status) {
+    case "fail":
+      return "fail";
+    case "incomplete":
+      return "incomplete";
+    case "not-applicable":
+      return "pass";
+    case "pass":
+      return hasText(result.evidence) ? "pass" : "incomplete";
+    default:
+      return "incomplete";
+  }
+}
+function evaluateQualityPolicy(input) {
+  const requestedProfile = input.profile === void 0 ? "routine" : input.profile;
+  if (!isQualityProfile(requestedProfile)) {
+    throw new Error(`Unknown quality profile: ${String(requestedProfile)}`);
+  }
+  const controls = /* @__PURE__ */ new Map();
+  let status = "pass";
+  let hasRequired = false;
+  for (const control of input.controls) {
+    if (!hasText(control.id) || control.requirement !== "required" && control.requirement !== "optional" || controls.has(control.id)) {
+      status = mergeStatus(status, "incomplete");
+      continue;
+    }
+    controls.set(control.id, control);
+    if (control.requirement === "required") hasRequired = true;
+  }
+  const results = /* @__PURE__ */ new Map();
+  for (const result of input.results) {
+    const control = controls.get(result.controlId);
+    if (!control || results.has(result.controlId)) {
+      status = mergeStatus(status, "incomplete");
+    }
+    if (control && !results.has(result.controlId)) {
+      results.set(result.controlId, result);
+    }
+    if (control && result.status === "not-applicable") {
+      const validException = control.requirement === "optional" && control.notApplicable === true && hasText(result.reason);
+      status = mergeStatus(status, validException ? "pass" : "incomplete");
+      continue;
+    }
+    if (control) status = mergeStatus(status, resultStatus(result));
+  }
+  if (!hasRequired) status = mergeStatus(status, "incomplete");
+  for (const control of controls.values()) {
+    if (control.requirement !== "required") continue;
+    const result = results.get(control.id);
+    if (!result) {
+      status = mergeStatus(status, "incomplete");
+      continue;
+    }
+    if (result.status === "not-applicable") {
+      status = mergeStatus(status, "incomplete");
+    } else {
+      status = mergeStatus(status, resultStatus(result));
+    }
+  }
+  return { profile: requestedProfile, status };
+}
+
+// src/lib/quality-receipt.ts
+import { createHash as createHash2 } from "crypto";
+var QUALITY_RECEIPT_NAMESPACE = "jorgex.quality.receipt";
+var QUALITY_RECEIPT_VERSION = 1;
+var COMMIT_SHA_PATTERN = /^[0-9a-f]{40}$/i;
+var SHA256_PATTERN = /^[0-9a-f]{64}$/i;
+var MAX_EXCERPT_LENGTH = 512;
+var REDACTED = "[REDACTED]";
+var QUALITY_RESULT_STATUSES = [
+  "pass",
+  "fail",
+  "incomplete",
+  "not-applicable"
+];
+var SENSITIVE_FLAG_PATTERN = /^(?:-{1,2})(?:(?:[a-z][a-z0-9_.-]*[-_]?)?(?:access[-_]?token|api[-_]?key|auth(?:orization)?|client[-_]?secret|credential|pass(?:word|wd)?|refresh[-_]?token|secret|token))$/i;
+var SENSITIVE_ASSIGNMENT_PATTERN = /^(?:-{0,2})(?:(?:[a-z][a-z0-9_.-]*[-_]?)?(?:access[-_]?token|api[-_]?key|auth(?:orization)?|client[-_]?secret|credential|pass(?:word|wd)?|refresh[-_]?token|secret|token))\s*[=:]\s*.+$/i;
+var SENSITIVE_OUTPUT_PATTERN = /((?:authorization\s*:\s*bearer\s+|bearer\s+))[^\s,;]+/gi;
+var SENSITIVE_KEY_VALUE_PATTERN = /((?:^|(?<=[^\w.-]))(?:-{0,2})(?:(?:[a-z][a-z0-9_.-]*[-_]?)?(?:access[-_]?token|api[-_]?key|auth(?:orization)?|client[-_]?secret|credential|pass(?:word|wd)?|refresh[-_]?token|secret|token))\s*[=:]\s*)(?:"[^"]*"|'[^']*'|[^\r\n,;]+)/gi;
+var SENSITIVE_SEPARATE_FLAG_PATTERN = /((?:^|(?<=[^\w.-]))-{1,2}(?:(?:[a-z][a-z0-9_.-]*[-_]?)?(?:access[-_]?token|api[-_]?key|auth(?:orization)?|client[-_]?secret|credential|pass(?:word|wd)?|refresh[-_]?token|secret|token))[ \t]+)(?:"[^"]*"|'[^']*'|[^\r\n,;]+)/gi;
+var SENSITIVE_STRUCTURED_VALUE_PATTERN = /((?:"|')?(?:token|password|api[-_]?key|access[-_]?token|_?auth(?:orization)?(?:[-_.]?token)?|aws[-_]?secret[-_]?access[-_]?key|private[-_]?key)(?:"|')?\s*:\s*)("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*')/gi;
+function isRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+function isDenseStringArray(value) {
+  if (!Array.isArray(value)) return false;
+  for (let index = 0; index < value.length; index += 1) {
+    if (!hasOwn(value, String(index)) || typeof value[index] !== "string") return false;
+  }
+  return true;
+}
+function assertExactKeys(value, allowed, label) {
+  const allowedKeys = new Set(allowed);
+  const unexpected = Object.keys(value).find((key) => !allowedKeys.has(key));
+  if (unexpected !== void 0) {
+    throw new Error(`Unexpected ${label} field: ${unexpected}`);
+  }
+}
+function requireRecord(value, label) {
+  if (!isRecord2(value)) throw new Error(`Invalid ${label}`);
+  return value;
+}
+function requireText(value, label) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`Invalid ${label}`);
+  }
+  return value;
+}
+function isQualityProfile2(value) {
+  return QUALITY_PROFILES.includes(value);
+}
+function isQualityReceiptResultStatus(value) {
+  return QUALITY_RESULT_STATUSES.includes(value);
+}
+function requireSha(value, label, pattern) {
+  const text2 = requireText(value, label);
+  if (!pattern.test(text2)) throw new Error(`Invalid ${label}`);
+  return text2;
+}
+function redactText(value) {
+  return value.replace(SENSITIVE_STRUCTURED_VALUE_PATTERN, (_match, prefix, quotedValue) => {
+    const quote = quotedValue[0];
+    return `${prefix}${quote}${REDACTED}${quote}`;
+  }).replace(SENSITIVE_OUTPUT_PATTERN, (_match, prefix) => {
+    const normalizedPrefix = prefix.toLowerCase().startsWith("authorization") ? prefix.slice(0, prefix.toLowerCase().indexOf("bearer") + "bearer".length) : "Bearer ";
+    return `${normalizedPrefix}${REDACTED}`;
+  }).replace(SENSITIVE_KEY_VALUE_PATTERN, `$1${REDACTED}`).replace(SENSITIVE_SEPARATE_FLAG_PATTERN, `$1${REDACTED}`);
+}
+function redactAssignment(value) {
+  const separator = value.indexOf("=") >= 0 ? "=" : ":";
+  const name = value.slice(0, value.indexOf(separator));
+  return `${name}${separator}${REDACTED}`;
+}
+function redactArgv(argv) {
+  if (!isDenseStringArray(argv)) throw new Error("Invalid argv: sparse or non-string array");
+  let redactNext = false;
+  return argv.map((argument) => {
+    if (redactNext) {
+      redactNext = false;
+      return REDACTED;
+    }
+    if (SENSITIVE_FLAG_PATTERN.test(argument)) {
+      redactNext = true;
+      return argument;
+    }
+    if (SENSITIVE_ASSIGNMENT_PATTERN.test(argument)) {
+      return redactAssignment(argument);
+    }
+    return redactText(argument);
+  });
+}
+function excerptFor(output) {
+  const stdout = redactText(output.stdout);
+  const stderr = redactText(output.stderr);
+  const combined = [stdout, stderr].filter((part) => part !== "").join("\n");
+  return Array.from(combined).slice(0, MAX_EXCERPT_LENGTH).join("");
+}
+function outputDigestFor(output) {
+  const sanitized = {
+    stdout: redactText(output.stdout),
+    stderr: redactText(output.stderr)
+  };
+  return sha256(canonicalJson(sanitized));
+}
+function normalizeCommand(command) {
+  return {
+    commandId: command.commandId,
+    executable: command.executable,
+    argv: redactArgv(command.argv),
+    exitCode: command.exitCode,
+    durationMs: command.durationMs,
+    excerpt: excerptFor(command.output),
+    outputDigest: outputDigestFor(command.output)
+  };
+}
+function normalizeResult(result) {
+  if (result.status === "pass") {
+    return {
+      controlId: result.controlId,
+      status: "pass",
+      evidence: result.evidence,
+      ...result.reason === void 0 ? {} : { reason: result.reason }
+    };
+  }
+  return {
+    controlId: result.controlId,
+    status: result.status,
+    ...result.evidence === void 0 ? {} : { evidence: result.evidence },
+    ...result.reason === void 0 ? {} : { reason: result.reason }
+  };
+}
+function normalizeProvenance(provenance) {
+  return {
+    issuer: provenance.issuer,
+    executionId: provenance.executionId,
+    evidenceLocator: provenance.evidenceLocator,
+    evidenceDigest: provenance.evidenceDigest
+  };
+}
+function canonicalValue(value) {
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "string": {
+      const result = JSON.stringify(value);
+      if (result === void 0) throw new Error("Unable to canonicalize string");
+      return result;
+    }
+    case "boolean":
+      return value ? "true" : "false";
+    case "number": {
+      if (!Number.isFinite(value)) throw new Error("Cannot canonicalize non-finite number");
+      const result = JSON.stringify(value);
+      if (result === void 0) throw new Error("Unable to canonicalize number");
+      return result;
+    }
+    case "object": {
+      if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index += 1) {
+          if (!hasOwn(value, String(index))) {
+            throw new Error("Cannot canonicalize sparse array");
+          }
+        }
+        return `[${value.map((item) => canonicalValue(item)).join(",")}]`;
+      }
+      const prototype = Object.getPrototypeOf(value);
+      if (prototype !== Object.prototype && prototype !== null) {
+        throw new Error("Cannot canonicalize non-plain object");
+      }
+      const object = value;
+      return `{${Object.keys(object).sort().map((key) => {
+        return `${JSON.stringify(key)}:${canonicalValue(object[key])}`;
+      }).join(",")}}`;
+    }
+    default:
+      throw new Error(`Cannot canonicalize ${typeof value}`);
+  }
+}
+function canonicalJson(value) {
+  return canonicalValue(value);
+}
+function sha256(value) {
+  return createHash2("sha256").update(value, "utf8").digest("hex");
+}
+function validateIdentity(value, expected) {
+  const identity = requireRecord(value, "identity");
+  assertExactKeys(identity, ["profile", "baseSha", "headSha", "policyDigest"], "identity");
+  const profile = requireText(identity.profile, "identity.profile");
+  if (!isQualityProfile2(profile)) throw new Error(`Invalid identity.profile: ${profile}`);
+  const baseSha = requireSha(identity.baseSha, "identity.baseSha", COMMIT_SHA_PATTERN);
+  const headSha = requireSha(identity.headSha, "identity.headSha", COMMIT_SHA_PATTERN);
+  const policyDigest = requireSha(identity.policyDigest, "identity.policyDigest", SHA256_PATTERN);
+  const actual = { profile, baseSha, headSha, policyDigest };
+  if (expected !== void 0) {
+    for (const field of ["profile", "baseSha", "headSha", "policyDigest"]) {
+      if (actual[field] !== expected[field]) {
+        throw new Error(`Quality receipt identity mismatch: ${field}`);
+      }
+    }
+  }
+  return actual;
+}
+function validateProvenance(value) {
+  const provenance = requireRecord(value, "provenance");
+  assertExactKeys(provenance, ["issuer", "executionId", "evidenceLocator", "evidenceDigest"], "provenance");
+  const issuer = requireText(provenance.issuer, "provenance.issuer");
+  const executionId = requireText(provenance.executionId, "provenance.executionId");
+  const evidenceLocator = requireText(provenance.evidenceLocator, "provenance.evidenceLocator");
+  if (!/^https?:\/\/\S+$/.test(evidenceLocator)) {
+    throw new Error("Invalid provenance.evidenceLocator");
+  }
+  try {
+    const parsed = new URL(evidenceLocator);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      throw new Error("unsupported locator protocol");
+    }
+  } catch {
+    throw new Error("Invalid provenance.evidenceLocator");
+  }
+  const evidenceDigest = requireSha(provenance.evidenceDigest, "provenance.evidenceDigest", SHA256_PATTERN);
+  return { issuer, executionId, evidenceLocator, evidenceDigest };
+}
+function validateCommand(value, index) {
+  const command = requireRecord(value, `commands[${index}]`);
+  assertExactKeys(
+    command,
+    ["commandId", "executable", "argv", "exitCode", "durationMs", "excerpt", "outputDigest"],
+    `commands[${index}]`
+  );
+  const commandId = requireText(command.commandId, `commands[${index}].commandId`);
+  const executable = requireText(command.executable, `commands[${index}].executable`);
+  if (!isDenseStringArray(command.argv)) {
+    throw new Error(`Invalid commands[${index}].argv`);
+  }
+  if (typeof command.exitCode !== "number" || !Number.isInteger(command.exitCode)) {
+    throw new Error(`Invalid commands[${index}].exitCode`);
+  }
+  if (typeof command.durationMs !== "number" || !Number.isFinite(command.durationMs) || command.durationMs < 0) {
+    throw new Error(`Invalid commands[${index}].durationMs`);
+  }
+  if (!hasOwn(command, "excerpt") || typeof command.excerpt !== "string") {
+    throw new Error(`Invalid commands[${index}].excerpt`);
+  }
+  const excerpt = command.excerpt;
+  if (Array.from(excerpt).length > MAX_EXCERPT_LENGTH) throw new Error(`Invalid commands[${index}].excerpt`);
+  if (redactText(excerpt) !== excerpt) {
+    throw new Error(`Invalid commands[${index}].excerpt: contains an unredacted secret`);
+  }
+  const argv = [...command.argv];
+  const sanitizedArgv = redactArgv(argv);
+  if (sanitizedArgv.some((argument, argumentIndex) => argument !== argv[argumentIndex])) {
+    throw new Error(`Invalid commands[${index}].argv: contains an unredacted secret`);
+  }
+  const outputDigest = requireSha(command.outputDigest, `commands[${index}].outputDigest`, SHA256_PATTERN);
+  return {
+    commandId,
+    executable,
+    argv,
+    exitCode: command.exitCode,
+    durationMs: command.durationMs,
+    excerpt,
+    outputDigest
+  };
+}
+function validateResult(value, index) {
+  const result = requireRecord(value, `results[${index}]`);
+  assertExactKeys(result, ["controlId", "status", "evidence", "reason"], `results[${index}]`);
+  const controlId = requireText(result.controlId, `results[${index}].controlId`);
+  const status = result.status;
+  if (typeof status !== "string" || !isQualityReceiptResultStatus(status)) {
+    throw new Error(`Invalid results[${index}].status`);
+  }
+  let evidence;
+  if (hasOwn(result, "evidence")) {
+    if (typeof result.evidence !== "string") {
+      throw new Error(`Invalid results[${index}].evidence`);
+    }
+    evidence = result.evidence;
+  }
+  let reason;
+  if (hasOwn(result, "reason")) {
+    if (typeof result.reason !== "string") {
+      throw new Error(`Invalid results[${index}].reason`);
+    }
+    reason = result.reason;
+  }
+  if (status === "pass") {
+    if (evidence === void 0 || evidence.trim() === "") {
+      throw new Error(`Invalid results[${index}].evidence: pass requires evidence`);
+    }
+    return {
+      controlId,
+      status,
+      evidence,
+      ...reason === void 0 ? {} : { reason }
+    };
+  }
+  return {
+    controlId,
+    status,
+    ...evidence === void 0 ? {} : { evidence },
+    ...reason === void 0 ? {} : { reason }
+  };
+}
+function validateQualityReceipt(value, expectedIdentity) {
+  const receipt = requireRecord(value, "quality receipt");
+  if (receipt.namespace !== QUALITY_RECEIPT_NAMESPACE) {
+    throw new Error(`Invalid quality receipt namespace: ${String(receipt.namespace)}`);
+  }
+  if (receipt.version !== QUALITY_RECEIPT_VERSION) {
+    throw new Error(`Unsupported quality receipt version: ${String(receipt.version)}`);
+  }
+  assertExactKeys(receipt, ["namespace", "version", "authority", "identity", "commands", "results", "provenance"], "receipt");
+  if (receipt.authority !== "local" && receipt.authority !== "enforced") {
+    throw new Error(`Invalid quality receipt authority: ${String(receipt.authority)}`);
+  }
+  const identity = validateIdentity(receipt.identity, expectedIdentity);
+  if (!Array.isArray(receipt.commands)) throw new Error("Invalid quality receipt commands");
+  if (!Array.isArray(receipt.results)) throw new Error("Invalid quality receipt results");
+  for (let index = 0; index < receipt.commands.length; index += 1) {
+    validateCommand(receipt.commands[index], index);
+  }
+  for (let index = 0; index < receipt.results.length; index += 1) {
+    validateResult(receipt.results[index], index);
+  }
+  const hasProvenance = hasOwn(receipt, "provenance");
+  if (receipt.authority === "enforced" && (!hasProvenance || receipt.provenance === void 0)) {
+    throw new Error("Enforced quality receipts require provenance");
+  }
+  if (hasProvenance) {
+    if (receipt.provenance === void 0) throw new Error("Invalid quality receipt provenance");
+    validateProvenance(receipt.provenance);
+  }
+  void identity;
+}
+function createQualityReceipt(input) {
+  const authority = input.authority;
+  if (authority !== "local" && authority !== "enforced") {
+    throw new Error(`Invalid quality receipt authority: ${String(authority)}`);
+  }
+  if (input.authority === "enforced" && input.provenance === void 0) {
+    throw new Error("Enforced quality receipts require provenance");
+  }
+  const base = {
+    namespace: QUALITY_RECEIPT_NAMESPACE,
+    version: QUALITY_RECEIPT_VERSION,
+    identity: {
+      profile: input.identity.profile,
+      baseSha: input.identity.baseSha,
+      headSha: input.identity.headSha,
+      policyDigest: input.identity.policyDigest
+    },
+    commands: input.commands.map(normalizeCommand),
+    results: input.results.map(normalizeResult)
+  };
+  let receipt;
+  if (input.authority === "enforced") {
+    const provenance = input.provenance;
+    if (provenance === void 0) throw new Error("Enforced quality receipts require provenance");
+    receipt = {
+      ...base,
+      authority: "enforced",
+      provenance: normalizeProvenance(provenance)
+    };
+  } else {
+    receipt = {
+      ...base,
+      authority: "local",
+      ...input.provenance === void 0 ? {} : { provenance: normalizeProvenance(input.provenance) }
+    };
+  }
+  validateQualityReceipt(receipt);
+  return receipt;
+}
+function serializeQualityReceipt(receipt) {
+  validateQualityReceipt(receipt);
+  return canonicalJson(receipt);
+}
+
+// src/lib/quality-runner.ts
+function normalizeLimit(value, name) {
+  if (value === void 0) return void 0;
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`${name} must be a non-negative safe integer`);
+  }
+  return value;
+}
+var MAX_NODE_TIMEOUT_MS = 2147483647;
+var TERMINATION_GRACE_MS = 250;
+var TASKKILL_TIMEOUT_MS = 2e3;
+function normalizeTimeout(value) {
+  const timeoutMs = normalizeLimit(value, "timeoutMs");
+  if (timeoutMs !== void 0 && timeoutMs > MAX_NODE_TIMEOUT_MS) {
+    throw new Error(`timeoutMs must not exceed ${MAX_NODE_TIMEOUT_MS}`);
+  }
+  return timeoutMs;
+}
+var COMMIT_SHA_PATTERN2 = /^[0-9a-f]{40}$/i;
+function isRecord3(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function hasText2(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function isDenseStringArray2(value) {
+  if (!Array.isArray(value)) return false;
+  for (let index = 0; index < value.length; index += 1) {
+    if (!Object.prototype.hasOwnProperty.call(value, String(index)) || typeof value[index] !== "string") return false;
+  }
+  return true;
+}
+function isNonNegativeSafeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isQualityProfile3(value) {
+  return typeof value === "string" && QUALITY_PROFILES.includes(value);
+}
+function assertValidEnvironment(value, label) {
+  if (!isRecord3(value)) throw new Error(`Invalid ${label}`);
+  for (const [key, entry] of Object.entries(value)) {
+    if (typeof entry !== "string") throw new Error(`Invalid ${label}.${key}`);
+  }
+}
+function assertQualityPlanInput(value) {
+  if (!isRecord3(value)) throw new Error("Invalid quality plan");
+  if (!isRecord3(value.identity)) throw new Error("Invalid quality plan identity");
+  if (typeof value.identity.baseSha !== "string" || !COMMIT_SHA_PATTERN2.test(value.identity.baseSha)) {
+    throw new Error("Invalid quality plan identity.baseSha");
+  }
+  if (typeof value.identity.headSha !== "string" || !COMMIT_SHA_PATTERN2.test(value.identity.headSha)) {
+    throw new Error("Invalid quality plan identity.headSha");
+  }
+  if (!isQualityProfile3(value.profile)) throw new Error("Invalid quality plan profile");
+  if (!Array.isArray(value.controls)) throw new Error("Invalid quality plan controls");
+  const controlIds = /* @__PURE__ */ new Set();
+  for (let index = 0; index < value.controls.length; index += 1) {
+    const control = value.controls[index];
+    if (!isRecord3(control) || !hasText2(control.id) || control.requirement !== "required" && control.requirement !== "optional") {
+      throw new Error(`Invalid quality plan controls[${index}]`);
+    }
+    if (controlIds.has(control.id)) {
+      throw new Error(`Duplicate quality plan control id: ${control.id}`);
+    }
+    controlIds.add(control.id);
+    if (Object.prototype.hasOwnProperty.call(control, "notApplicable") && typeof control.notApplicable !== "boolean") {
+      throw new Error(`Invalid quality plan controls[${index}].notApplicable`);
+    }
+  }
+  if (!Array.isArray(value.commands)) throw new Error("Invalid quality plan commands");
+  const commandIds = /* @__PURE__ */ new Set();
+  const commandControlIds = /* @__PURE__ */ new Set();
+  for (let index = 0; index < value.commands.length; index += 1) {
+    const command = value.commands[index];
+    if (!isRecord3(command)) throw new Error(`Invalid quality plan commands[${index}]`);
+    const timeoutMs = command.timeoutMs;
+    if (!hasText2(command.controlId) || !hasText2(command.commandId) || !hasText2(command.executable) || !isDenseStringArray2(command.argv) || !isNonNegativeSafeInteger(timeoutMs)) {
+      throw new Error(`Invalid quality plan commands[${index}]`);
+    }
+    if (timeoutMs > MAX_NODE_TIMEOUT_MS) {
+      throw new Error(`Invalid quality plan commands[${index}].timeoutMs: maximum is ${MAX_NODE_TIMEOUT_MS}`);
+    }
+    if (!controlIds.has(command.controlId)) {
+      throw new Error(`Unknown quality plan command control id: ${command.controlId}`);
+    }
+    if (commandIds.has(command.commandId)) {
+      throw new Error(`Duplicate quality plan command id: ${command.commandId}`);
+    }
+    if (commandControlIds.has(command.controlId)) {
+      throw new Error(`Multiple quality plan commands for control id: ${command.controlId}`);
+    }
+    commandIds.add(command.commandId);
+    commandControlIds.add(command.controlId);
+    if (command.maxOutputBytes !== void 0 && !isNonNegativeSafeInteger(command.maxOutputBytes)) {
+      throw new Error(`Invalid quality plan commands[${index}].maxOutputBytes`);
+    }
+    if (command.env !== void 0) assertValidEnvironment(command.env, `quality plan commands[${index}].env`);
+  }
+}
+function appendOutput(captured, stream, chunk, maxOutputBytes) {
+  if (maxOutputBytes === void 0) {
+    captured[stream].push(chunk);
+    return false;
+  }
+  const remaining = maxOutputBytes - captured.bytes;
+  if (remaining <= 0) return chunk.length > 0;
+  if (chunk.length > remaining) {
+    captured[stream].push(chunk.subarray(0, remaining));
+    captured.bytes += remaining;
+    return true;
+  }
+  captured[stream].push(chunk);
+  captured.bytes += chunk.length;
+  return captured.bytes >= maxOutputBytes;
+}
+function decodeOutput(chunks, maxOutputBytes) {
+  const output = Buffer.concat(chunks);
+  if (maxOutputBytes === void 0 || output.length === 0) return output.toString("utf8");
+  let end = output.length;
+  let decoded = output.subarray(0, end).toString("utf8");
+  while (Buffer.byteLength(decoded, "utf8") > maxOutputBytes && end > 0) {
+    end -= 1;
+    decoded = output.subarray(0, end).toString("utf8");
+  }
+  return decoded;
+}
+function killProcessTree(child) {
+  const pid = child.pid;
+  if (pid === void 0) return;
+  if (process.platform === "win32") {
+    const systemRoot = process.env.SystemRoot ?? process.env.WINDIR ?? "C:\\Windows";
+    const taskkill = path33.join(systemRoot, "System32", "taskkill.exe");
+    const result = spawnSync2(taskkill, ["/pid", String(pid), "/t", "/f"], {
+      shell: false,
+      stdio: "ignore",
+      timeout: TASKKILL_TIMEOUT_MS,
+      windowsHide: true
+    });
+    if (result.error !== void 0 || result.status !== 0) {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+      }
+    }
+    return;
+  }
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+    }
+  }
+}
+function resultFromCaptured(input, status, exitCode, startedAt, captured, maxOutputBytes, reason) {
+  return {
+    commandId: input.commandId,
+    status,
+    exitCode,
+    durationMs: Math.max(0, Date.now() - startedAt),
+    output: {
+      stdout: decodeOutput(captured.stdout, maxOutputBytes),
+      stderr: decodeOutput(captured.stderr, maxOutputBytes)
+    },
+    ...reason === void 0 ? {} : { reason }
+  };
+}
+async function runQualityCommand(input, deps = { terminate: killProcessTree }) {
+  const timeoutMs = normalizeTimeout(input.timeoutMs);
+  const maxOutputBytes = normalizeLimit(input.maxOutputBytes, "maxOutputBytes");
+  if (timeoutMs === void 0) throw new Error("timeoutMs is required");
+  const planned = planDetectedBinCommand(input.executable, [...input.argv]);
+  const startedAt = Date.now();
+  const captured = { stdout: [], stderr: [], bytes: 0 };
+  if (planned === null) {
+    return resultFromCaptured(input, "error", null, startedAt, captured, maxOutputBytes, "unsafe-command");
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    let terminationReason;
+    let spawnError;
+    let timeout;
+    let terminationDeadline;
+    let child;
+    let cleanedUp = false;
+    let onStdoutData = (_chunk) => {
+    };
+    let onStderrData = (_chunk) => {
+    };
+    let onError = (_error) => {
+    };
+    const onErrorSink = () => {
+    };
+    let onClose = (_exitCode) => {
+    };
+    const cleanupChild = () => {
+      if (cleanedUp || child === void 0) return;
+      cleanedUp = true;
+      child.removeListener("close", onClose);
+      child.removeListener("error", onError);
+      child.on("error", onErrorSink);
+      child.stdout?.removeListener("data", onStdoutData);
+      child.stderr?.removeListener("data", onStderrData);
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      child.unref();
+    };
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timeout !== void 0) clearTimeout(timeout);
+      if (terminationDeadline !== void 0) clearTimeout(terminationDeadline);
+      cleanupChild();
+      resolve(result);
+    };
+    try {
+      child = spawn(planned.command, planned.args, {
+        detached: true,
+        env: input.env === void 0 ? {} : { ...input.env },
+        shell: false,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true
+      });
+    } catch (error) {
+      settle(resultFromCaptured(input, "unavailable", null, startedAt, captured, maxOutputBytes, "spawn-error"));
+      return;
+    }
+    const stopFor = (reason) => {
+      if (settled || terminationReason !== void 0) return;
+      terminationReason = reason;
+      try {
+        deps.terminate(child);
+      } catch {
+      }
+      if (settled) return;
+      terminationDeadline = setTimeout(() => {
+        try {
+          deps.terminate(child);
+        } catch {
+        }
+        cleanupChild();
+        settle(resultFromCaptured(input, "error", null, startedAt, captured, maxOutputBytes, "termination-timeout"));
+      }, TERMINATION_GRACE_MS);
+    };
+    const onOutput = (stream, chunk) => {
+      if (settled || appendOutput(captured, stream, chunk, maxOutputBytes)) {
+        if (!settled && maxOutputBytes !== void 0) stopFor("output-limit");
+      }
+    };
+    onStdoutData = (chunk) => onOutput("stdout", chunk);
+    onStderrData = (chunk) => onOutput("stderr", chunk);
+    onError = (error) => {
+      spawnError = error;
+      if (terminationReason === void 0 && (error.code === "ENOENT" || error.code === "EACCES")) {
+        settle(resultFromCaptured(input, "unavailable", null, startedAt, captured, maxOutputBytes, "spawn-error"));
+      }
+    };
+    onClose = (exitCode) => {
+      if (terminationReason === "timeout") {
+        settle(resultFromCaptured(input, "timeout", exitCode, startedAt, captured, maxOutputBytes));
+        return;
+      }
+      if (terminationReason === "output-limit") {
+        settle(resultFromCaptured(input, "error", exitCode, startedAt, captured, maxOutputBytes, "output-limit"));
+        return;
+      }
+      if (spawnError !== void 0) {
+        settle(resultFromCaptured(input, "unavailable", null, startedAt, captured, maxOutputBytes, "spawn-error"));
+        return;
+      }
+      settle(resultFromCaptured(
+        input,
+        exitCode === 0 ? "pass" : "fail",
+        exitCode,
+        startedAt,
+        captured,
+        maxOutputBytes
+      ));
+    };
+    child.stdout?.on("data", onStdoutData);
+    child.stderr?.on("data", onStderrData);
+    child.once("error", onError);
+    child.once("close", onClose);
+    timeout = setTimeout(() => stopFor("timeout"), timeoutMs);
+  });
+}
+function resultEvidence(result) {
+  const exitCode = result.exitCode === null ? "none" : String(result.exitCode);
+  return `exit=${exitCode}; status=${result.status}; durationMs=${result.durationMs}`;
+}
+function resultReason(result) {
+  switch (result.status) {
+    case "pass":
+      return void 0;
+    case "fail":
+      return "nonzero-exit";
+    case "timeout":
+      return "timeout";
+    case "unavailable":
+      return result.reason ?? "unavailable";
+    case "error":
+      return result.reason ?? "error";
+  }
+}
+function receiptResultFor(controlId, result) {
+  const evidence = resultEvidence(result);
+  if (result.status === "pass") return { controlId, status: "pass", evidence };
+  return {
+    controlId,
+    status: result.status === "fail" ? "fail" : "incomplete",
+    evidence,
+    reason: resultReason(result)
+  };
+}
+function missingRequiredResults(controls, commands) {
+  const commandControlIds = new Set(commands.map((command) => command.controlId));
+  const missing = /* @__PURE__ */ new Set();
+  for (const control of controls) {
+    if (control.requirement !== "required" || !hasText2(control.id) || commandControlIds.has(control.id)) continue;
+    missing.add(control.id);
+  }
+  return [...missing].map((controlId) => ({
+    controlId,
+    status: "incomplete",
+    evidence: "required control has no declared command",
+    reason: "required-control-missing"
+  }));
+}
+function receiptCommandFor(command, result) {
+  return {
+    commandId: command.commandId,
+    executable: command.executable,
+    argv: command.argv,
+    exitCode: result.exitCode ?? -1,
+    durationMs: result.durationMs,
+    output: result.output
+  };
+}
+async function runQualityPlan(input) {
+  assertQualityPlanInput(input);
+  const policy = { controls: input.controls, profile: input.profile };
+  const policyDigest = sha256(canonicalJson(policy));
+  const identity = {
+    profile: input.profile,
+    baseSha: input.identity.baseSha,
+    headSha: input.identity.headSha,
+    policyDigest
+  };
+  const commands = [];
+  const results = [];
+  for (const command of input.commands) {
+    const result = await runQualityCommand(command);
+    commands.push(receiptCommandFor(command, result));
+    results.push(receiptResultFor(command.controlId, result));
+  }
+  results.push(...missingRequiredResults(input.controls, input.commands));
+  const evaluation = evaluateQualityPolicy({
+    profile: input.profile,
+    controls: input.controls,
+    results
+  });
+  const receipt = createQualityReceipt({
+    authority: "local",
+    identity,
+    commands,
+    results
+  });
+  validateQualityReceipt(receipt, identity);
+  return { evaluation, receipt };
+}
+
 // src/cli.ts
 var VERSION = readPackageVersion();
-var COMMANDS = ["install", "sync", "models", "update", "doctor", "restore", "uninstall"];
+var COMMANDS = ["install", "sync", "models", "update", "doctor", "restore", "uninstall", "quality"];
+var QUALITY_REJECTED_VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "--agents",
+  "-a",
+  "--target-dir",
+  "--mode",
+  "--subagent-concurrency"
+]);
 async function ensureOpenCodeModelsForInstall(command, flags, runtimes) {
   if (!runtimes.includes("opencode") || loadModelMap().opencode) return true;
   const canPrompt = command === "install" && !flags.yes && !flags.dryRun && process.stdout.isTTY;
@@ -5458,7 +6298,7 @@ async function ensureOpenCodeModelsForInstall(command, flags, runtimes) {
   );
   return false;
 }
-function parseFlags(args) {
+function parseFlags(args, allowReceipt = false) {
   const flags = {
     agents: [],
     dryRun: false,
@@ -5474,6 +6314,7 @@ function parseFlags(args) {
     removePlaywright: false,
     devtools: false,
     noDevtools: false,
+    receipt: void 0,
     positional: [],
     unknownFlags: []
   };
@@ -5484,6 +6325,26 @@ function parseFlags(args) {
   };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
+    if (allowReceipt) {
+      if (arg === "--help" || arg === "-h") flags.help = true;
+      else if (arg === "--version" || arg === "-v") flags.version = true;
+      else if (arg === "--receipt") {
+        const [value, nextIndex] = readValue(i);
+        if (value === void 0 || value === "") flags.unknownFlags.push(arg);
+        else flags.receipt = value;
+        i = nextIndex;
+      } else if (arg.startsWith("--receipt=")) {
+        const value = arg.slice(10);
+        if (value === "") flags.unknownFlags.push(arg);
+        else flags.receipt = value;
+      } else if (QUALITY_REJECTED_VALUE_FLAGS.has(arg)) {
+        flags.unknownFlags.push(arg);
+        const [, nextIndex] = readValue(i);
+        i = nextIndex;
+      } else if (arg.startsWith("-")) flags.unknownFlags.push(arg);
+      else flags.positional.push(arg);
+      continue;
+    }
     if (arg === "--agents" || arg === "-a") {
       const [value, nextIndex] = readValue(i);
       flags.agents = (value ?? "").split(",").filter(Boolean);
@@ -5635,7 +6496,7 @@ function parseCliArgs(argv) {
     };
   }
   const command = isCommand ? first ?? "install" : "install";
-  const flags = parseFlags(isCommand ? rest : argv);
+  const flags = parseFlags(isCommand ? rest : argv, command === "quality");
   if (first === "--help" || first === "-h" || flags.help) return { action: "help", command, flags };
   if (first === "--version" || first === "-v" || flags.version) return { action: "version", command, flags };
   if (flags.unknownFlags.length > 0) return { action: "unknown-flags", command, flags };
@@ -5727,8 +6588,9 @@ Comandos:
   doctor      Estado: Engram, drift de config, hooks de Codex, key de context7
   restore     --list para ver backups \xB7 'restore <id>' para restaurar
   uninstall   Retira SOLO lo gestionado por el stack (con backup).
-              Engram se CONSERVA por defecto (memorias, binario y registro);
-              desregistrarlo exige --remove-engram o el s\xED expl\xEDcito
+               Engram se CONSERVA por defecto (memorias, binario y registro);
+               desregistrarlo exige --remove-engram o el s\xED expl\xEDcito
+  quality     Ejecuta un plan JSON expl\xEDcito y emite un receipt local
 
 Opciones:
   --agents, -a opencode,claude-code,codex,pi   Runtimes destino (default: detectados)
@@ -5744,6 +6606,7 @@ Opciones:
                         memorias y binario quedan intactos igualmente
   --remove-playwright   (uninstall) retira solo el paquete global de Playwright;
                         nunca perfiles, cach\xE9 ni navegadores
+  --receipt <path>      (quality) escribe el receipt en ese path de forma at\xF3mica
 
 Ver PRD.md para el dise\xF1o completo.`);
 }
@@ -5770,12 +6633,43 @@ Flags disponibles: jorgex-stack --help`
     return;
   }
   const { command, flags } = parsed;
-  if (flags.targetDir !== void 0 && flags.agents.length !== 1) {
+  if (command !== "quality" && flags.targetDir !== void 0 && flags.agents.length !== 1) {
     console.error("--target-dir requiere exactamente un runtime en --agents.");
     process.exitCode = 1;
     return;
   }
   switch (command) {
+    case "quality": {
+      if (flags.targetDir !== void 0 || flags.agents.length > 0 || flags.dryRun || flags.yes || flags.mode !== void 0 || flags.subagentConcurrency !== void 0 || flags.list || flags.check || flags.removeEngram || flags.playwright || flags.removePlaywright || flags.devtools || flags.noDevtools) {
+        console.error("quality solo admite <plan.json> y, opcionalmente, --receipt <path>.");
+        process.exitCode = 1;
+        return;
+      }
+      if (flags.positional.length !== 1) {
+        console.error("Uso: jorgex-stack quality <plan.json> [--receipt <path>]");
+        process.exitCode = 1;
+        return;
+      }
+      if (flags.receipt !== void 0 && flags.receipt.trim() === "") {
+        console.error("--receipt requiere un path no vac\xEDo.");
+        process.exitCode = 1;
+        return;
+      }
+      try {
+        const plan = JSON.parse(fs24.readFileSync(flags.positional[0], "utf8"));
+        const result = await runQualityPlan(plan);
+        const serialized = serializeQualityReceipt(result.receipt);
+        if (flags.receipt === void 0) process.stdout.write(`${serialized}
+`);
+        else writeText(flags.receipt, `${serialized}
+`);
+        process.exitCode = result.evaluation.status === "pass" ? 0 : 1;
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+      }
+      return;
+    }
     case "install":
     case "sync": {
       const runtimes = await resolveRuntimes(flags, command === "install");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jorgex-stack",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Harness multi-agente portable: instala la config JorgeX (agentes, skills, hooks, Engram, MCPs) en Claude Code, Codex CLI, OpenCode y Pi",
   "type": "module",
   "license": "MIT",