@codyswann/lisa 2.345.1 → 2.348.0

package/all/copy-overwrite/scripts/lisa-command-envelope.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/**
+ * lisa-command-envelope — the standard result every capability adapter returns.
+ *
+ * Governed by the `reset-seed-coverage` rule. One validated JSON object on
+ * stdout, human narration on stderr, and an exit code that means exactly one
+ * thing: **0 = the operation completed AND verified**. Every other outcome is
+ * nonzero and says which in `status`.
+ *
+ * The point of the envelope is that "every repo answers the same interface the
+ * same way" becomes checkable. In particular a declared noop is machine-readable
+ * (`mode: "declared-noop"` plus reason, owner and capability-manifest
+ * reference) — a bare `exit 0` with no output is indistinguishable from a
+ * successful destructive run and is never an acceptable answer.
+ *
+ * CLI:
+ *   node scripts/lisa-command-envelope.mjs --print-schema
+ *   node scripts/lisa-command-envelope.mjs --validate <file>   # "-" reads stdin
+ * @module scripts/lisa-command-envelope
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { validateAgainstSchema } from "./lisa-schema-validate.mjs";
+
+/** Pinned envelope schema version. */
+export const COMMAND_ENVELOPE_SCHEMA_VERSION = "lisa-command-envelope-v1";
+
+const SCHEMA_PATH = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "schemas",
+  "lisa-command-envelope.v1.schema.json"
+);
+
+/** The published envelope schema, read from the shipped JSON document. */
+export const COMMAND_ENVELOPE_SCHEMA = JSON.parse(
+  fs.readFileSync(SCHEMA_PATH, "utf8")
+);
+
+/**
+ * Statuses that may exit 0.
+ *
+ * `detection-only` is deliberately NOT here: it means the adapter could not
+ * observe authoritative state, so its findings are non-authoritative, and exit
+ * 0 must never mean "I could not look."
+ */
+export const SUCCESS_STATUSES = Object.freeze([
+  "completed",
+  "no-op",
+  "not-adopted",
+]);
+
+/**
+ * Exit code implied by a status.
+ * @param {string} status - Envelope status
+ * @returns {number} 0 when the operation completed and verified, else 1
+ */
+export function exitCodeForStatus(status) {
+  return SUCCESS_STATUSES.includes(status) ? 0 : 1;
+}
+
+/**
+ * Validate an envelope against the published schema, plus the conditional
+ * requirements the schema alone cannot express.
+ * @param {unknown} envelope - Candidate envelope
+ * @returns {{ valid: boolean, errors: string[] }} Validation outcome
+ */
+export function validateEnvelope(envelope) {
+  const base = validateAgainstSchema(envelope, COMMAND_ENVELOPE_SCHEMA);
+  if (!base.valid) {
+    return base;
+  }
+  const errors = [];
+  const declarative =
+    envelope.mode === "declared-noop" || envelope.mode === "not-applicable";
+  if (declarative) {
+    for (const field of ["reason", "owner", "capabilityManifest"]) {
+      if (!envelope[field]) {
+        errors.push(
+          `mode "${envelope.mode}" requires "${field}" — a bare success is indistinguishable from a real run`
+        );
+      }
+    }
+  }
+  if (!SUCCESS_STATUSES.includes(envelope.status) && !envelope.reason) {
+    errors.push(`status "${envelope.status}" requires "reason"`);
+  }
+  if (envelope.mode === "declared-noop" && envelope.status !== "no-op") {
+    errors.push('mode "declared-noop" requires status "no-op"');
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Build a validated envelope, filling in the invariant fields.
+ * @param {object} fields - Envelope fields (see the published schema)
+ * @returns {object} A frozen, validated envelope
+ * @throws {Error} When the resulting envelope is invalid
+ */
+export function buildEnvelope(fields) {
+  const { summary = {}, ...rest } = fields;
+  const envelope = {
+    schemaVersion: COMMAND_ENVELOPE_SCHEMA_VERSION,
+    dryRun: false,
+    ...rest,
+    summary: { deleted: 0, created: 0, preserved: 0, ...summary },
+  };
+  const { valid, errors } = validateEnvelope(envelope);
+  if (!valid) {
+    throw new Error(`invalid command envelope: ${errors.join("; ")}`);
+  }
+  return Object.freeze(envelope);
+}
+
+/**
+ * Redact obvious secrets and personal data from a line bound for stderr.
+ *
+ * Best-effort by design: it is the last line of defence, not a substitute for
+ * not logging the value. Adapters must not put credentials in their narration.
+ * @param {string} text - Human-readable narration
+ * @returns {string} The same text with likely secrets and PII masked
+ */
+export function redact(text) {
+  return String(text)
+    .replace(
+      /\b[\w.%+-]+@[\w-]+\.[A-Za-z]{2,}\b/gu,
+      match => `${match.slice(0, 2)}***@***`
+    )
+    .replace(
+      /((?:password|passwd|secret|token|api[-_]?key|authorization|bearer)["'\s:=]+)\S+/giu,
+      "$1***"
+    )
+    .replace(/\b(?:\d[ -]?){12,19}\b/gu, "***")
+    .replace(/\b\+?\d{10,15}\b/gu, "***");
+}
+
+/**
+ * Write the envelope to stdout as the process's single machine-readable result.
+ * @param {object} envelope - A built envelope
+ * @param {{ stdout?: { write: (chunk: string) => unknown } }} [io] - Injectable stream
+ * @returns {number} The exit code implied by the envelope's status
+ */
+export function emitEnvelope(envelope, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  stdout.write(`${JSON.stringify(envelope)}\n`);
+  return exitCodeForStatus(envelope.status);
+}
+
+/**
+ * CLI entry point.
+ * @param {string[]} argv - Arguments after the script name
+ * @returns {number} Process exit code
+ */
+export function main(argv) {
+  if (argv.includes("--print-schema")) {
+    process.stdout.write(
+      `${JSON.stringify(COMMAND_ENVELOPE_SCHEMA, null, 2)}\n`
+    );
+    return 0;
+  }
+  const index = argv.indexOf("--validate");
+  if (index === -1) {
+    process.stderr.write(
+      "usage: lisa-command-envelope.mjs [--print-schema] [--validate <file|->]\n"
+    );
+    return 1;
+  }
+  const source = argv[index + 1] ?? "-";
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(source === "-" ? 0 : source, "utf8"));
+  } catch (error) {
+    process.stderr.write(`[command-envelope] FAIL: ${redact(error.message)}\n`);
+    return 1;
+  }
+  const { valid, errors } = validateEnvelope(parsed);
+  if (!valid) {
+    process.stderr.write(
+      `[command-envelope] FAIL:\n${errors.map(entry => `  - ${entry}`).join("\n")}\n`
+    );
+    return 1;
+  }
+  process.stderr.write("[command-envelope] OK\n");
+  return 0;
+}
+
+// Run only when invoked directly — importing for tests must have no side effects.
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  process.exitCode = main(process.argv.slice(2));
+}

package/all/copy-overwrite/scripts/lisa-schema-validate.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * lisa-schema-validate — dependency-free validator for the JSON Schema subset
+ * Lisa's shipped contract schemas use.
+ *
+ * Lisa's copy-overwrite scripts run in every adopter repo before that repo has
+ * installed anything, so they cannot depend on a schema library. This module
+ * implements exactly the keywords the shipped schemas use and **rejects any
+ * keyword it does not implement**, so a schema can never silently validate less
+ * than it claims: an unsupported keyword is a validator error, not a pass.
+ *
+ * Supported: `type`, `const`, `enum`, `required`, `properties`,
+ * `additionalProperties` (boolean), `items`, `minLength`, `minimum`, `pattern`,
+ * `$ref` (local `#/$defs/<name>` only), `$defs`, plus the annotation-only
+ * keywords `$schema`, `$id`, `title`, `description`.
+ * @module scripts/lisa-schema-validate
+ */
+
+/** Keywords that carry no validation semantics and are ignored. */
+const ANNOTATION_KEYWORDS = new Set([
+  "$schema",
+  "$id",
+  "title",
+  "description",
+  "$defs",
+  "examples",
+  "default",
+]);
+
+/** Keywords this validator implements. Anything else is an error. */
+const SUPPORTED_KEYWORDS = new Set([
+  "type",
+  "const",
+  "enum",
+  "required",
+  "properties",
+  "additionalProperties",
+  "items",
+  "minLength",
+  "minimum",
+  "pattern",
+  "$ref",
+]);
+
+/**
+ * JSON type name for a value, using JSON Schema's vocabulary.
+ * @param {unknown} value - Value to classify
+ * @returns {string} One of null/array/integer/number/string/boolean/object
+ */
+export function jsonTypeOf(value) {
+  if (value === null) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    return "array";
+  }
+  if (typeof value === "number") {
+    return Number.isInteger(value) ? "integer" : "number";
+  }
+  return typeof value;
+}
+
+/**
+ * Resolve a local `#/$defs/<name>` reference against the root schema.
+ * @param {string} ref - The `$ref` string
+ * @param {object} root - Root schema document
+ * @returns {object} The referenced subschema
+ * @throws {Error} When the reference is not a supported local $defs pointer
+ */
+function resolveRef(ref, root) {
+  const match = /^#\/\$defs\/([^/]+)$/u.exec(ref);
+  const target = match ? root.$defs?.[match[1]] : undefined;
+  if (!target) {
+    throw new Error(
+      `unsupported or unresolvable $ref "${ref}" (only #/$defs/<name> is supported)`
+    );
+  }
+  return target;
+}
+
+/**
+ * Validate one value against one subschema, appending human-readable errors.
+ * @param {unknown} value - Value under validation
+ * @param {object} schema - Subschema to apply
+ * @param {object} root - Root schema document (for `$ref` resolution)
+ * @param {string} instancePath - JSON-pointer-ish path for messages
+ * @param {string[]} errors - Accumulator, mutated in place
+ * @returns {void}
+ */
+function validateNode(value, schema, root, instancePath, errors) {
+  for (const keyword of Object.keys(schema)) {
+    if (!SUPPORTED_KEYWORDS.has(keyword) && !ANNOTATION_KEYWORDS.has(keyword)) {
+      throw new Error(
+        `schema at ${instancePath || "/"} uses unsupported keyword "${keyword}"`
+      );
+    }
+  }
+
+  if (typeof schema.$ref === "string") {
+    validateNode(
+      value,
+      resolveRef(schema.$ref, root),
+      root,
+      instancePath,
+      errors
+    );
+    return;
+  }
+
+  const where = instancePath || "(root)";
+  const actualType = jsonTypeOf(value);
+
+  if (typeof schema.type === "string") {
+    const ok =
+      schema.type === actualType ||
+      (schema.type === "number" && actualType === "integer");
+    if (!ok) {
+      errors.push(`${where}: expected type ${schema.type}, got ${actualType}`);
+      return;
+    }
+  }
+
+  if ("const" in schema && value !== schema.const) {
+    errors.push(
+      `${where}: expected constant ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}`
+    );
+  }
+
+  if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+    errors.push(
+      `${where}: ${JSON.stringify(value)} is not one of ${schema.enum.map(entry => JSON.stringify(entry)).join(", ")}`
+    );
+  }
+
+  if (typeof value === "string") {
+    if (
+      typeof schema.minLength === "number" &&
+      value.length < schema.minLength
+    ) {
+      errors.push(`${where}: shorter than minLength ${schema.minLength}`);
+    }
+    if (
+      typeof schema.pattern === "string" &&
+      !new RegExp(schema.pattern, "u").test(value)
+    ) {
+      errors.push(`${where}: does not match pattern ${schema.pattern}`);
+    }
+  }
+
+  if (typeof value === "number" && typeof schema.minimum === "number") {
+    if (value < schema.minimum) {
+      errors.push(`${where}: below minimum ${schema.minimum}`);
+    }
+  }
+
+  if (actualType === "array" && schema.items) {
+    value.forEach((entry, index) => {
+      validateNode(entry, schema.items, root, `${where}[${index}]`, errors);
+    });
+  }
+
+  if (actualType !== "object") {
+    return;
+  }
+
+  for (const key of schema.required ?? []) {
+    if (!(key in value)) {
+      errors.push(`${where}: missing required property "${key}"`);
+    }
+  }
+
+  const properties = schema.properties ?? {};
+  for (const [key, subschema] of Object.entries(properties)) {
+    if (key in value) {
+      validateNode(
+        value[key],
+        subschema,
+        root,
+        `${instancePath}.${key}`,
+        errors
+      );
+    }
+  }
+
+  if (schema.additionalProperties === false) {
+    for (const key of Object.keys(value)) {
+      if (!(key in properties)) {
+        errors.push(`${where}: unexpected property "${key}"`);
+      }
+    }
+  }
+}
+
+/**
+ * Validate a document against a schema.
+ * @param {unknown} document - The value to validate
+ * @param {object} schema - The schema document
+ * @returns {{ valid: boolean, errors: string[] }} Validation outcome
+ */
+export function validateAgainstSchema(document, schema) {
+  const errors = [];
+  try {
+    validateNode(document, schema, schema, "", errors);
+  } catch (error) {
+    return { valid: false, errors: [`schema error: ${error.message}`] };
+  }
+  return { valid: errors.length === 0, errors };
+}

package/all/copy-overwrite/scripts/schemas/lisa-command-envelope.v1.schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://lisa.codyswann.dev/schemas/lisa-command-envelope.v1.schema.json",
+  "title": "Lisa standard command envelope (v1)",
+  "description": "The single JSON result every capability adapter (reset, seed, verify, inventory, classification) writes to stdout. Exit 0 means the operation completed AND verified; any other outcome exits nonzero and says which in `status`. Human-readable narration goes to stderr, redacted of secrets and personal data.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "capability",
+    "mode",
+    "operation",
+    "environment",
+    "contractVersion",
+    "dryRun",
+    "status",
+    "correlationId",
+    "summary"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "lisa-command-envelope-v1",
+      "description": "Pinned envelope schema version. A bump is a deliberate migration, never an incidental edit."
+    },
+    "capability": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Which standard interface answered, e.g. reset, seed, reset-verify, state-inventory, state-classification."
+    },
+    "mode": {
+      "enum": ["real", "declared-noop", "not-applicable"],
+      "description": "real = the adapter does the thing. declared-noop = the repo deliberately has nothing to do here and says so machine-readably. not-applicable = the capability does not apply to this repo kind."
+    },
+    "operation": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The concrete operation performed, in the adapter's own vocabulary."
+    },
+    "environment": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The SERVER-RESOLVED environment identity the operation ran against. Never the caller-supplied --stage, which is only a request to be checked against this value."
+    },
+    "contractVersion": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The project's own contract version for the state this adapter acts on, so evidence from one run cannot be read as evidence for a different contract."
+    },
+    "dryRun": {
+      "type": "boolean",
+      "description": "True when the adapter enumerated intended mutations without performing them. Mandatory support on every destructive adapter."
+    },
+    "status": {
+      "enum": [
+        "completed",
+        "no-op",
+        "not-adopted",
+        "detection-only",
+        "denied",
+        "invalid",
+        "failed",
+        "verification-mismatch"
+      ],
+      "description": "completed = did it and verified it. no-op = nothing to do (declared noop). not-adopted = the capability is not wired in this repo yet. detection-only = could not observe authoritative state, findings are non-authoritative. denied = refused by a guard. invalid = bad input or malformed contract. failed = attempted and failed. verification-mismatch = mutated but the post-state did not verify."
+    },
+    "correlationId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable id joining this envelope to the audit record and the CI log for the same run."
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["deleted", "created", "preserved"],
+      "description": "Counts describing what the run did. Additional adapter-specific counters are allowed; these three are always present so a reader can compare runs across repos.",
+      "properties": {
+        "deleted": { "type": "integer", "minimum": 0 },
+        "created": { "type": "integer", "minimum": 0 },
+        "preserved": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "reason": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Required when mode is declared-noop or not-applicable, and whenever status is not a success status. Explains the outcome in one operator-readable sentence."
+    },
+    "owner": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Required when mode is declared-noop or not-applicable. The team or role accountable for the declaration."
+    },
+    "capabilityManifest": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Required when mode is declared-noop or not-applicable. Reference to the capability-matrix entry that records this declaration."
+    },
+    "idempotencyKey": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Required in CI for destructive adapters so a retried invocation is recognized rather than repeated."
+    },
+    "findings": {
+      "type": "array",
+      "description": "Machine-readable findings. Each names the entity or subject, the rule violated, and a one-line message.",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["code", "subject", "message"],
+        "properties": {
+          "code": { "type": "string", "minLength": 1 },
+          "subject": { "type": "string", "minLength": 1 },
+          "message": { "type": "string", "minLength": 1 },
+          "severity": { "enum": ["error", "warning"] }
+        }
+      }
+    }
+  }
+}