stylegallery 0.1.0

package/scripts/test-json-cli-output.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptPath = fileURLToPath(import.meta.url);
+const root = path.resolve(path.dirname(scriptPath), "..");
+const cases = [
+  { kind: "validator", script: "validate-consumer-reference.mjs" },
+  { kind: "harness", script: "test-validate-consumer-reference.mjs" },
+];
+
+function reportIsComplete(kind, report) {
+  if (!report || typeof report !== "object" || report.ok !== true) return false;
+  if (kind === "validator") {
+    return Number.isInteger(report.checkedItems)
+      && report.checkedItems > 0
+      && Array.isArray(report.profiles);
+  }
+  return kind === "harness" && Array.isArray(report.results) && report.results.length > 30;
+}
+
+function readStream(stream) {
+  return new Promise((resolve, reject) => {
+    stream.setEncoding("utf8");
+    let output = "";
+    stream.on("data", (chunk) => { output += chunk; });
+    stream.once("end", () => resolve(output));
+    stream.once("error", reject);
+  });
+}
+
+function waitForClose(child, label) {
+  return new Promise((resolve, reject) => {
+    child.once("error", (error) => reject(new Error(`${label} failed to start: ${error.message}`, { cause: error })));
+    child.once("close", (status, signal) => resolve({ signal, status }));
+  });
+}
+
+async function parsePipe(kind) {
+  try {
+    const output = await readStream(process.stdin);
+    const report = JSON.parse(output);
+    const complete = reportIsComplete(kind, report);
+    const summary = {
+      bytes: Buffer.byteLength(output),
+      complete,
+      digest: createHash("sha256").update(output).digest("hex"),
+    };
+    process.stdout.write(`${JSON.stringify(summary)}\n`);
+    process.exitCode = complete ? 0 : 1;
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}
+
+async function runPipeCase(testCase, run) {
+  const producer = spawn(process.execPath, [path.join(root, "scripts", testCase.script), "--json"], {
+    cwd: root,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  const parser = spawn(process.execPath, [scriptPath, "--pipe-parser", testCase.kind], {
+    cwd: root,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  const directOutputPromise = readStream(producer.stdout);
+  const producerStderrPromise = readStream(producer.stderr);
+  const parserOutputPromise = readStream(parser.stdout);
+  const parserStderrPromise = readStream(parser.stderr);
+  let pipeError = null;
+  parser.stdin.once("error", (error) => { pipeError = error; });
+  producer.stdout.pipe(parser.stdin);
+
+  const [producerClose, parserClose, directOutput, producerStderr, parserOutput, parserStderr] = await Promise.all([
+    waitForClose(producer, `${testCase.kind} producer`),
+    waitForClose(parser, `${testCase.kind} parser`),
+    directOutputPromise,
+    producerStderrPromise,
+    parserOutputPromise,
+    parserStderrPromise,
+  ]);
+
+  let directReport;
+  let pipeReport;
+  try {
+    directReport = JSON.parse(directOutput);
+    pipeReport = JSON.parse(parserOutput);
+  } catch (error) {
+    return {
+      actual: {
+        parserStatus: parserClose.status,
+        parserStderr: parserStderr.trim(),
+        pipeError: pipeError?.message ?? "",
+        producerStatus: producerClose.status,
+        producerStderr: producerStderr.trim(),
+      },
+      expected: "complete parseable JSON through a real Node stream pipe",
+      name: `${testCase.kind}_pipe_run_${run}`,
+      ok: false,
+      reason: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  const directBytes = Buffer.byteLength(directOutput);
+  const directDigest = createHash("sha256").update(directOutput).digest("hex");
+  const equivalent = pipeReport.bytes === directBytes && pipeReport.digest === directDigest;
+  const complete = reportIsComplete(testCase.kind, directReport) && pipeReport.complete === true;
+  return {
+    actual: {
+      complete,
+      directBytes,
+      equivalent,
+      parserSignal: parserClose.signal,
+      parserStatus: parserClose.status,
+      parserStderr: parserStderr.trim(),
+      pipeBytes: pipeReport.bytes,
+      pipeError: pipeError?.message ?? "",
+      producerSignal: producerClose.signal,
+      producerStatus: producerClose.status,
+      producerStderr: producerStderr.trim(),
+    },
+    expected: "complete parseable JSON through a real Node stream pipe",
+    name: `${testCase.kind}_pipe_run_${run}`,
+    ok: producerClose.status === 0
+      && producerClose.signal === null
+      && parserClose.status === 0
+      && parserClose.signal === null
+      && producerStderr.length === 0
+      && parserStderr.length === 0
+      && pipeError === null
+      && directBytes > 512
+      && complete
+      && equivalent,
+  };
+}
+
+async function main() {
+  const results = [];
+  for (const testCase of cases) {
+    for (const run of [1, 2]) results.push(await runPipeCase(testCase, run));
+  }
+  const report = { ok: results.every((result) => result.ok), results };
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  process.exitCode = report.ok ? 0 : 1;
+}
+
+if (process.argv[2] === "--pipe-parser") await parsePipe(process.argv[3]);
+else await main();

package/scripts/test-json-schema-formats.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import Ajv2020 from "ajv/dist/2020.js";
+import { addDateTimeFormat, isRfc3339DateTime } from "./json-schema-formats.mjs";
+
+test("rejects RFC3339 values whose calendar date would normalize", () => {
+  for (const value of [
+    "2023-02-29T12:00:00Z",
+    "2023-02-30T12:00:00Z",
+    "2024-04-31T12:00:00+05:30",
+  ]) {
+    assert.equal(isRfc3339DateTime(value), false, value);
+  }
+});
+
+test("preserves valid RFC3339 offsets and fractional seconds", () => {
+  for (const value of [
+    "2024-02-29T23:59:59Z",
+    "2024-02-29T23:59:59.123456789+05:30",
+    "2024-02-29T00:00:00-04:00",
+  ]) {
+    assert.equal(isRfc3339DateTime(value), true, value);
+  }
+});
+
+test("uses the strict validator for the AJV date-time format", () => {
+  const ajv = new Ajv2020({ allErrors: true, strict: true });
+  addDateTimeFormat(ajv);
+  const validate = ajv.compile({
+    additionalProperties: false,
+    properties: { at: { format: "date-time", type: "string" } },
+    required: ["at"],
+    type: "object",
+  });
+
+  assert.equal(validate({ at: "2024-02-29T23:59:59.123Z" }), true);
+  assert.equal(validate({ at: "2023-02-29T23:59:59.123Z" }), false);
+});

package/scripts/test-reference-adapters.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const builder = path.join(repositoryRoot, "scripts", "build-reference-artifacts.mjs");
+const validator = path.join(repositoryRoot, "scripts", "validate-reference-artifacts.mjs");
+const schema = JSON.parse(fs.readFileSync(path.join(repositoryRoot, "consumer-reference/schema/portable-tokens.schema.json"), "utf8"));
+
+function parseJson(child) {
+  try {
+    return JSON.parse(child.stdout);
+  } catch (error) {
+    return { failures: [{ code: "invalid_json_output", message: error instanceof Error ? error.message : String(error) }], ok: false };
+  }
+}
+
+function codes(output) {
+  return Array.isArray(output.failures)
+    ? output.failures.flatMap((failure) => typeof failure?.code === "string" ? [failure.code] : [])
+    : [];
+}
+
+const tempRoot = fs.mkdtempSync(path.join(repositoryRoot, ".tmp-stylegallery-reference-adapter-"));
+const results = [];
+
+function run(command, args) {
+  const child = spawnSync(process.execPath, [command, ...args, "--json"], { cwd: repositoryRoot, encoding: "utf8" });
+  return { child, output: parseJson(child) };
+}
+
+function recordAccepted(name, execution, predicate = () => true) {
+  const actualCodes = codes(execution.output);
+  const accepted = execution.child.status === 0 && execution.output.ok === true && execution.output.scaffold !== true;
+  results.push({
+    actual: { codes: actualCodes, ok: execution.output.ok, scaffold: execution.output.scaffold === true, status: execution.child.status },
+    expected: "ok:true and exit:0",
+    name,
+    ok: accepted && predicate(),
+  });
+}
+
+function recordRejected(name, execution, expectedCode) {
+  const actualCodes = codes(execution.output);
+  results.push({
+    actual: { codes: actualCodes, ok: execution.output.ok, scaffold: execution.output.scaffold === true, status: execution.child.status },
+    expected: expectedCode,
+    name,
+    ok: execution.child.status !== 0 && execution.output.ok === false && actualCodes.includes(expectedCode),
+  });
+}
+
+try {
+  const groupPattern = new RegExp(Object.keys(schema.$defs.group.patternProperties)[0]);
+  const rootPattern = new RegExp(Object.keys(schema.patternProperties)[0]);
+  const unsafeSegments = ["__proto__", "prototype", "constructor"];
+  results.push({
+    actual: {
+      groupDescription: schema.$defs.group.properties.$description.type,
+      tokenDescription: schema.$defs.token.properties.$description.type,
+      unsafeGroupMatches: unsafeSegments.filter((segment) => groupPattern.test(segment)),
+      unsafeRootMatches: unsafeSegments.filter((segment) => rootPattern.test(segment)),
+    },
+    expected: "string descriptions and no unsafe path segments",
+    name: "schema_runtime_boundary_parity",
+    ok: schema.$defs.group.properties.$description.type === "string"
+      && schema.$defs.token.properties.$description.type === "string"
+      && unsafeSegments.every((segment) => !groupPattern.test(segment) && !rootPattern.test(segment)),
+  });
+  const output = path.join(tempRoot, "tokens.css");
+  const manifest = path.join(tempRoot, "manifest.json");
+  const validBuild = run(builder, ["--source", "consumer-reference/fixtures/token-portability/valid-reference.json", "--output", output, "--manifest", manifest, "--adapter", "style-dictionary", "--fail-on-warning"]);
+  recordAccepted("valid_reference_build", validBuild, () => {
+    const css = fs.readFileSync(output, "utf8");
+    return css.includes("var(--color-accent)") && css.includes("var(--space-small)") && !css.includes("[object Object]");
+  });
+  recordAccepted("valid_reference_manifest", run(validator, ["--manifest", manifest]));
+
+  for (const fixture of ["valid-whole-alias.json", "valid-border.json"]) {
+    recordAccepted(fixture.replace(".json", ""), run(builder, ["--source", `consumer-reference/fixtures/token-portability/${fixture}`, "--output", output, "--manifest", manifest, "--fail-on-warning"]));
+  }
+  const invalidFixtures = [
+    ["invalid-extends.json", "token_extends_forbidden"],
+    ["invalid-json-pointer.json", "token_json_pointer_forbidden"],
+    ["invalid-resolver.json", "token_resolver_forbidden"],
+    ["invalid-unknown-reserved.json", "token_unknown_reserved"],
+    ["invalid-untested-type.json", "token_type_unsupported"],
+    ["invalid-dangling-alias.json", "alias_dangling"],
+    ["invalid-cycle.json", "alias_cycle"],
+    ["invalid-type-mismatch.json", "alias_type_mismatch"],
+  ];
+  for (const [fixture, expected] of invalidFixtures) {
+    recordRejected(fixture.replace(".json", ""), run(builder, ["--source", `consumer-reference/fixtures/token-portability/${fixture}`, "--output", output, "--manifest", manifest, "--fail-on-warning"]), expected);
+  }
+
+  const invalidUnit = path.join(tempRoot, "invalid-unit.json");
+  fs.writeFileSync(invalidUnit, '{"space":{"$type":"dimension","bad":{"$value":{"value":1,"unit":"vh"}}}}\n');
+  recordRejected("invalid_untested_unit", run(builder, ["--source", invalidUnit, "--output", output, "--manifest", manifest, "--fail-on-warning"]), "token_unit_unsupported");
+  const partialAlias = path.join(tempRoot, "invalid-partial-alias.json");
+  fs.writeFileSync(partialAlias, '{"space":{"$type":"dimension","bad":{"$value":"calc({space.base} * 2)"}}}\n');
+  recordRejected("invalid_partial_alias", run(builder, ["--source", partialAlias, "--output", output, "--manifest", manifest, "--fail-on-warning"]), "alias_whole_required");
+  const invalidGroupDescription = path.join(tempRoot, "invalid-group-description.json");
+  fs.writeFileSync(invalidGroupDescription, '{"space":{"$description":{"unsafe":true},"$type":"dimension","small":{"$value":{"value":1,"unit":"px"}}}}\n');
+  recordRejected("invalid_group_description", run(builder, ["--source", invalidGroupDescription, "--output", output, "--manifest", manifest, "--fail-on-warning"]), "token_description_invalid");
+  const invalidTokenDescription = path.join(tempRoot, "invalid-token-description.json");
+  fs.writeFileSync(invalidTokenDescription, '{"space":{"$type":"dimension","small":{"$description":42,"$value":{"value":1,"unit":"px"}}}}\n');
+  recordRejected("invalid_token_description", run(builder, ["--source", invalidTokenDescription, "--output", output, "--manifest", manifest, "--fail-on-warning"]), "token_description_invalid");
+  const duplicateSourceProperty = path.join(tempRoot, "invalid-duplicate-source-property.json");
+  fs.writeFileSync(duplicateSourceProperty, '{"space":{"$type":"dimension","$type":"dimension","small":{"$value":{"value":1,"unit":"px"}}}}\n');
+  recordRejected("duplicate_source_property", run(builder, ["--source", duplicateSourceProperty, "--output", output, "--manifest", manifest, "--fail-on-warning"]), "token_json_invalid");
+  for (const [name, sourceText] of [
+    ["constructor", '{"constructor":{"$type":"dimension","small":{"$value":{"value":1,"unit":"px"}}}}\n'],
+    ["prototype", '{"prototype":{"$type":"dimension","small":{"$value":{"value":1,"unit":"px"}}}}\n'],
+    ["__proto__", '{"__proto__":{"$type":"dimension","small":{"$value":{"value":1,"unit":"px"}}}}\n'],
+  ]) {
+    const unsafePath = path.join(tempRoot, `invalid-path-${name}.json`);
+    fs.writeFileSync(unsafePath, sourceText);
+    recordRejected(`invalid_path_${name}`, run(builder, ["--source", unsafePath, "--output", output, "--manifest", manifest, "--fail-on-warning"]), "token_path_segment_unsafe");
+  }
+
+  const baselineSource = fs.readFileSync(path.join(repositoryRoot, "consumer-reference/fixtures/token-portability/valid-reference.json"), "utf8");
+  fs.writeFileSync(path.join(tempRoot, "source.json"), baselineSource);
+  const baselineBuild = run(builder, ["--source", path.join(tempRoot, "source.json"), "--output", output, "--manifest", manifest, "--fail-on-warning"]);
+  recordAccepted("artifact_baseline", baselineBuild);
+  const baselineCss = fs.readFileSync(output, "utf8");
+  const baselineManifest = fs.readFileSync(manifest, "utf8");
+  fs.writeFileSync(manifest, baselineManifest.replace('"schemaVersion": "1.0",', '"schemaVersion": "1.0",\n  "schemaVersion": "1.0",'));
+  recordRejected("duplicate_manifest_property", run(validator, ["--manifest", manifest]), "artifact_manifest_invalid");
+  const duplicateValidatorSource = baselineSource.replace('"$type": "color",', '"$type": "color",\n    "$type": "color",');
+  fs.writeFileSync(path.join(tempRoot, "source.json"), duplicateValidatorSource);
+  const duplicateSourceManifest = JSON.parse(baselineManifest);
+  duplicateSourceManifest.inputHash = `sha256:${crypto.createHash("sha256").update(duplicateValidatorSource).digest("hex")}`;
+  fs.writeFileSync(manifest, `${JSON.stringify(duplicateSourceManifest, null, 2)}\n`);
+  recordRejected("duplicate_validator_source_property", run(validator, ["--manifest", manifest]), "artifact_source_invalid");
+  fs.writeFileSync(path.join(tempRoot, "source.json"), baselineSource);
+  fs.writeFileSync(manifest, baselineManifest);
+  const symlinkSource = path.join(tempRoot, "symlink-source.json");
+  fs.symlinkSync(path.join(tempRoot, "source.json"), symlinkSource);
+  recordRejected("symlink_source", run(builder, ["--source", symlinkSource, "--output", output, "--manifest", manifest, "--fail-on-warning"]), "token_source_untrusted");
+  const realOutput = path.join(tempRoot, "real-tokens.css");
+  fs.renameSync(output, realOutput);
+  fs.symlinkSync(realOutput, output);
+  recordRejected("symlink_validator_output", run(validator, ["--manifest", manifest]), "artifact_output_untrusted");
+  recordRejected("symlink_builder_output", run(builder, ["--source", path.join(tempRoot, "source.json"), "--output", output, "--manifest", manifest, "--fail-on-warning"]), "artifact_output_untrusted");
+  fs.rmSync(output);
+  fs.renameSync(realOutput, output);
+  const realManifest = path.join(tempRoot, "real-manifest.json");
+  fs.renameSync(manifest, realManifest);
+  fs.symlinkSync(realManifest, manifest);
+  recordRejected("symlink_validator_manifest", run(validator, ["--manifest", manifest]), "artifact_manifest_untrusted");
+  recordRejected("symlink_builder_manifest", run(builder, ["--source", path.join(tempRoot, "source.json"), "--output", output, "--manifest", manifest, "--fail-on-warning"]), "artifact_manifest_untrusted");
+  fs.rmSync(manifest);
+  fs.renameSync(realManifest, manifest);
+  const outsideRoot = fs.mkdtempSync(path.join(os.tmpdir(), "stylegallery-reference-escape-"));
+  const escapedSource = path.join(outsideRoot, "source.json");
+  fs.writeFileSync(escapedSource, baselineSource);
+  recordRejected("escaped_source", run(builder, ["--source", escapedSource, "--output", output, "--manifest", manifest, "--fail-on-warning"]), "token_source_untrusted");
+  const escapedOutput = path.join(outsideRoot, "tokens.css");
+  recordRejected("escaped_output", run(builder, ["--source", path.join(tempRoot, "source.json"), "--output", escapedOutput, "--manifest", manifest, "--fail-on-warning"]), "artifact_output_untrusted");
+  const escapedManifest = path.join(outsideRoot, "manifest.json");
+  recordRejected("escaped_manifest", run(builder, ["--source", path.join(tempRoot, "source.json"), "--output", output, "--manifest", escapedManifest, "--fail-on-warning"]), "artifact_manifest_untrusted");
+  fs.rmSync(outsideRoot, { force: true, recursive: true });
+  const artifactCases = [
+    ["no_output", "artifact_output_missing", () => fs.rmSync(output)],
+    ["zero_count", "artifact_zero_count", (item) => { item.sourceCount = 0; item.outputCount = 0; item.declarations = []; }],
+    ["warning", "artifact_warning", (item) => { item.warnings = ["synthetic warning"]; }],
+    ["missing_declaration", "artifact_declaration_missing", (item) => { item.declarations = item.declarations.slice(1); }],
+    ["duplicate_declaration", "artifact_declaration_duplicate", (item) => { item.declarations.push(item.declarations[0]); }],
+    ["object_sentinel", "artifact_object_sentinel", () => fs.writeFileSync(output, baselineCss.replace("120ms", "[object Object]"))],
+    ["unresolved_alias", "artifact_unresolved_value", () => fs.writeFileSync(output, baselineCss.replace("120ms", "{duration.quick}"))],
+    ["count_mismatch", "artifact_count_mismatch", (item) => { item.outputCount += 1; }],
+    ["scaffold_manifest", "artifact_scaffold_forbidden", (item) => { item.scaffold = true; }],
+    ["forged_value", "artifact_source_output_mismatch", (item) => {
+      const changed = baselineCss.replace("120ms", "999999s !important");
+      fs.writeFileSync(output, changed);
+      item.outputHash = `sha256:${crypto.createHash("sha256").update(changed).digest("hex")}`;
+      item.declarations.find((declaration) => declaration.name === "--duration-quick").value = "999999s !important";
+    }],
+  ];
+  for (const [name, expected, mutate] of artifactCases) {
+    fs.writeFileSync(output, baselineCss);
+    const item = JSON.parse(baselineManifest);
+    mutate(item);
+    fs.writeFileSync(manifest, `${JSON.stringify(item, null, 2)}\n`);
+    recordRejected(name, run(validator, ["--manifest", manifest]), expected);
+  }
+} finally {
+  fs.rmSync(tempRoot, { force: true, recursive: true });
+}
+
+const failures = results.filter((result) => !result.ok).map((result) => `missing_semantic:${result.name}:${result.expected}`);
+const report = { failures, ok: failures.length === 0, results };
+console.log(JSON.stringify(report, null, 2));
+process.exitCode = report.ok ? 0 : 1;

package/scripts/test-renderer-purity.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const validator = path.join(repositoryRoot, "scripts", "validate-renderer-purity.mjs");
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "stylegallery-pr4-renderer-"));
+const cases = [];
+
+function run(renderer) {
+  const child = spawnSync(process.execPath, [validator, "--renderer", renderer, "--json"], { cwd: repositoryRoot, encoding: "utf8" });
+  return { child, output: JSON.parse(child.stdout) };
+}
+
+try {
+  const valid = run("tests/helpers/render-consumer-reference.mjs");
+  cases.push({ actual: { codes: valid.output.failures.map((failure) => failure.code), status: valid.child.status }, expected: "pure import and exit:0", name: "canonical_renderer_import", ok: valid.child.status === 0 && valid.output.ok === true });
+  const mutation = path.join(tempRoot, "render-consumer-reference.mjs");
+  fs.writeFileSync(mutation, 'import fs from "node:fs";\nimport { patterns } from "../../scripts/pattern-data.mjs";\nfs.appendFileSync("CATALOG.md", "mutation");\nexport { patterns };\n');
+  const invalid = run(mutation);
+  const codes = invalid.output.failures.map((failure) => failure.code);
+  cases.push({ actual: { codes, status: invalid.child.status }, expected: "renderer_side_effect_capability", name: "renderer_side_effect", ok: invalid.child.status !== 0 && codes.includes("renderer_side_effect_capability") });
+} finally {
+  fs.rmSync(tempRoot, { force: true, recursive: true });
+}
+
+const failures = cases.filter((testCase) => !testCase.ok).map((testCase) => `missing_semantic:${testCase.name}:${testCase.expected}`);
+const result = { failures, ok: failures.length === 0, results: cases };
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+if (!result.ok) process.exitCode = 1;

package/scripts/test-sg-cli.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { agentNativeFixture } from "./agent-native/fixture.mjs";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const cli = path.join(repositoryRoot, "scripts", "sg.mjs");
+const profileRef = "sg:profile/editorial-reference-profile";
+const versionRef = agentNativeFixture.records.find(({ stable_ref }) => stable_ref === profileRef)?.version_id;
+
+const successCases = [
+  { command: "discover", baseArgs: ["discover"] },
+  { command: "resolve", baseArgs: ["resolve", profileRef] },
+  { command: "resolve", baseArgs: ["resolve", versionRef], name: "resolve_version_id" },
+  { command: "claims", baseArgs: ["claims", profileRef] },
+  { command: "context", baseArgs: ["context", profileRef] },
+  { command: "ops", baseArgs: ["ops"] },
+];
+
+const failureCases = [
+  { args: ["--format", "json"], code: "argument_value_required", name: "missing_command" },
+  { args: ["resolve", "--format", "json"], code: "argument_value_required", name: "resolve_missing_stable_ref" },
+  { args: ["claims", "--format", "json"], code: "argument_value_required", name: "claims_missing_stable_ref" },
+  { args: ["resolve", "not-a-stable-ref", "--format", "json"], code: "stable_ref_malformed", name: "malformed_stable_ref" },
+  { args: ["resolve", "sg:profile/unknown-profile", "--format", "json"], code: "stable_ref_unknown", name: "unknown_stable_ref" },
+  { args: ["unknown-command", "--format", "json"], code: "command_unknown", name: "unknown_command" },
+  { args: ["discover", "--unknown", "--format", "json"], code: "argument_unknown", name: "unknown_option" },
+  { args: ["--format", "json", "discover", "--format"], code: "argument_value_required", name: "format_missing_value" },
+  { args: ["--format", "json", "discover", "--format", "yaml"], code: "format_unsupported", name: "unsupported_format" },
+];
+
+function run(args) {
+  return spawnSync(process.execPath, [cli, ...args], {
+    cwd: repositoryRoot,
+    encoding: "utf8",
+  });
+}
+
+function parseJson(child) {
+  if (typeof child.stdout !== "string" || child.stdout.length === 0) return null;
+  try {
+    return JSON.parse(child.stdout);
+  } catch {
+    return null;
+  }
+}
+
+function summarize(child, report) {
+  return {
+    report,
+    signal: child.signal,
+    status: child.status,
+    stderr: child.stderr,
+    stdout: child.stdout,
+  };
+}
+
+function hasSuccessContract(child, report, command) {
+  return child.status === 0
+    && child.signal === null
+    && child.stderr.length === 0
+    && report !== null
+    && report.ok === true
+    && report.operation === command
+    && report.result !== null
+    && typeof report.result === "object";
+}
+
+function formatVariants(baseArgs) {
+  const command = baseArgs[0];
+  const operands = baseArgs.slice(1);
+  return [
+    [...baseArgs, "--format", "json"],
+    ["--format", "json", ...baseArgs],
+    [command, "--format", "json", ...operands],
+  ];
+}
+
+function runSuccessCase(testCase) {
+  const variants = formatVariants(testCase.baseArgs);
+  const runs = variants.map((args) => {
+    const child = run(args);
+    return { args, child, report: parseJson(child) };
+  });
+  const reference = runs[0];
+  const equivalent = runs.every(({ child, report }) => (
+    hasSuccessContract(child, report, testCase.command)
+      && child.stdout === reference.child.stdout
+  ));
+  const repeated = run(testCase.baseArgs.concat(["--format", "json"]));
+  const repeatedReport = parseJson(repeated);
+  const deterministic = hasSuccessContract(repeated, repeatedReport, testCase.command)
+    && repeated.stdout === reference.child.stdout;
+  return {
+    actual: runs.map(({ args, child, report }) => ({ args, ...summarize(child, report) })),
+    expected: "all --format json positions produce one stdout-only success JSON document with identical bytes",
+    name: `${testCase.name ?? testCase.command}_format_order_and_stdout_contract`,
+    ok: equivalent && deterministic,
+  };
+}
+
+function runFailureCase(testCase) {
+  const child = run(testCase.args);
+  const report = parseJson(child);
+  const codes = Array.isArray(report?.failures)
+    ? report.failures.map((failure) => failure?.code)
+    : [];
+  return {
+    actual: { codes, ...summarize(child, report) },
+    expected: `nonzero stdout-only JSON failure containing stable code ${testCase.code}`,
+    name: testCase.name,
+    ok: child.status !== 0
+      && child.signal === null
+      && child.stderr.length === 0
+      && report?.ok === false
+      && codes.length > 0
+      && codes.includes(testCase.code),
+  };
+}
+
+const results = [
+  ...successCases.map(runSuccessCase),
+  ...failureCases.map(runFailureCase),
+];
+const report = { ok: results.every((result) => result.ok), results };
+process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+process.exitCode = report.ok ? 0 : 1;