@ctxr/skill-llm-wiki 1.0.1 → 1.1.0

package/scripts/lib/json-envelope.mjs

@@ -0,0 +1,190 @@
+// json-envelope.mjs — shared JSON stdout shape for consumer-facing
+// operational subcommands that use the envelope (validate, init,
+// heal, rollback). Those commands emit exactly one envelope object
+// on stdout; no surrounding prose, no multiple envelopes per
+// invocation. stderr stays free-form for logs.
+//
+// Probe-style commands — `contract --json` and `where --json` —
+// intentionally return their own non-envelope JSON shapes because
+// they pre-date the envelope contract and have stable consumer
+// schemas of their own (skill-llm-wiki/contract/v1 and
+// skill-llm-wiki/where/v1).
+//
+// Consumers validate the `schema` discriminator as their first
+// check. See guide/consumers/recipes/post-write-heal.md and
+// recipes/ci-gate.md for canonical parsing patterns.
+//
+// Envelope shape (format_version 1):
+//   {
+//     "schema": "skill-llm-wiki/v1",
+//     "command": "validate",
+//     "target": "/abs/path" | null,
+//     "verdict": "ok" | "fixable" | "needs-rebuild" | "broken"
+//              | "built" | "extended" | "healed" | "initialised"
+//              | "aborted" | "ambiguous",
+//     "exit": <integer>,
+//     "diagnostics": [
+//       { "code": "IDX-01", "severity": "warning", "path": "...", "message": "..." }
+//     ],
+//     "artifacts": { "created": [...], "modified": [...], "deleted": [...] },
+//     "timing_ms": <integer>,
+//     "next": null | { "command": "skill-llm-wiki", "args": ["fix", "/wiki", "--json"] }
+//   }
+//
+// `next` is present only when the subcommand wants to hand the
+// consumer a machine-readable follow-up command (init emits the
+// build invocation; heal emits the fix or rebuild invocation).
+// Consumers that receive `verdict: "fixable"` / `"needs-rebuild"`
+// should invoke `next.command` with `next.args` rather than parse
+// the `NEXT-01` info diagnostic's free-text message.
+
+export const ENVELOPE_SCHEMA = "skill-llm-wiki/v1";
+
+// Every known verdict string. Consumers can switch on these without
+// fearing a surprise value; adding a new verdict is a format_version
+// bump.
+export const VERDICTS = Object.freeze([
+  "ok",
+  "fixable",
+  "needs-rebuild",
+  "broken",
+  "built",
+  "extended",
+  "healed",
+  "initialised",
+  "aborted",
+  "ambiguous",
+]);
+
+// Diagnostic severity levels. Consumers gate their CI on `error`.
+export const SEVERITIES = Object.freeze(["error", "warning", "info"]);
+
+// Build an envelope from a minimal set of inputs. Missing artifact
+// buckets default to empty arrays so consumers never have to
+// defensively check for undefined.
+//
+// `next` is an optional structured hint for consumers that also
+// carries a human-readable form in an info diagnostic. It is the
+// machine-readable sibling of the NEXT-01 diagnostic consumers may
+// still parse today.
+export function makeEnvelope({
+  command,
+  target = null,
+  verdict,
+  exit,
+  diagnostics = [],
+  artifacts = {},
+  timing_ms = 0,
+  next = null,
+} = {}) {
+  if (!command || typeof command !== "string") {
+    throw new Error("makeEnvelope: command is required");
+  }
+  if (!verdict || typeof verdict !== "string") {
+    throw new Error("makeEnvelope: verdict is required");
+  }
+  if (!VERDICTS.includes(verdict)) {
+    throw new Error(
+      `makeEnvelope: unknown verdict "${verdict}". Known: ${VERDICTS.join(", ")}`,
+    );
+  }
+  if (!Number.isInteger(exit)) {
+    throw new Error("makeEnvelope: exit must be an integer");
+  }
+  const envelope = {
+    schema: ENVELOPE_SCHEMA,
+    command,
+    target,
+    verdict,
+    exit,
+    diagnostics: Array.isArray(diagnostics) ? diagnostics : [],
+    artifacts: {
+      created: artifacts.created ?? [],
+      modified: artifacts.modified ?? [],
+      deleted: artifacts.deleted ?? [],
+    },
+    timing_ms: Number.isInteger(timing_ms) ? timing_ms : 0,
+  };
+  if (next !== null) {
+    if (
+      typeof next !== "object" ||
+      typeof next.command !== "string" ||
+      !Array.isArray(next.args)
+    ) {
+      throw new Error(
+        "makeEnvelope: next must be { command: string, args: string[] } or null",
+      );
+    }
+    envelope.next = { command: next.command, args: next.args.slice() };
+  }
+  return envelope;
+}
+
+// Shared error-envelope builder used by consumer subcommands that
+// need to surface a structured failure without reinventing the
+// envelope shape. Verdict defaults to "ambiguous" (the canonical
+// error verdict) and exit defaults to 2 (validation / ambiguity per
+// the skill-wide scheme). Usage-error callers pass exit=1 explicitly.
+export function makeErrorEnvelope({
+  command,
+  code,
+  message,
+  target = null,
+  verdict = "ambiguous",
+  exit = 2,
+} = {}) {
+  if (!command || typeof command !== "string") {
+    throw new Error("makeErrorEnvelope: command is required");
+  }
+  if (!code || typeof code !== "string") {
+    throw new Error("makeErrorEnvelope: code is required");
+  }
+  return makeEnvelope({
+    command,
+    target,
+    verdict,
+    exit,
+    diagnostics: [
+      { code, severity: "error", path: target, message: message ?? "" },
+    ],
+  });
+}
+
+// Write an envelope to stdout as one line of JSON followed by a
+// newline. Single-line output is easier to pipe through `jq` and
+// also to `grep`-assert in test harnesses.
+export function writeEnvelope(envelope, stream = process.stdout) {
+  stream.write(JSON.stringify(envelope) + "\n");
+}
+
+// Detect whether --json or --json-errors (legacy alias) was passed.
+// Returns true on the first positive match. `--json-errors`
+// predates the envelope; we accept it as an alias rather than
+// deprecating it loudly, because every existing consumer passes it
+// to get structured intent errors.
+//
+// Only the bare flag forms are supported. `--json=1` / `--json=true`
+// are NOT accepted: the skill's shared arg parser (parseSubArgv)
+// rejects inline values on boolean flags, and hasJsonFlag would
+// otherwise diverge from that contract and silently accept an
+// argument shape that build/extend/rebuild/... reject.
+export function hasJsonFlag(args) {
+  if (!Array.isArray(args)) return false;
+  for (const tok of args) {
+    if (typeof tok !== "string") continue;
+    if (tok === "--json" || tok === "--json-errors") return true;
+  }
+  return false;
+}
+
+// Convert a validate-style finding (code, severity, target, message)
+// into a diagnostic object in the envelope's canonical shape. Shared
+// so consumers see the same field names everywhere.
+export function findingToDiagnostic(finding) {
+  return {
+    code: finding.code ?? "UNKNOWN",
+    severity: finding.severity ?? "info",
+    path: finding.target ?? null,
+    message: finding.message ?? "",
+  };
+}