cueline 0.2.2 → 0.3.0

package/schemas/cli-runs-prune.schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cueline.dev/schemas/cli-runs-prune.schema.json",
+  "title": "cueline runs prune --json output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "version",
+    "home",
+    "apply",
+    "olderThanMs",
+    "cutoff",
+    "states",
+    "decisions",
+    "prunedRuns",
+    "eligibleRuns",
+    "keptRuns",
+    "removedJobRecords",
+    "errors"
+  ],
+  "properties": {
+    "schema": { "const": "cueline-runs-prune/1" },
+    "version": { "type": "string", "minLength": 1 },
+    "home": { "type": "string", "minLength": 1 },
+    "apply": { "type": "boolean" },
+    "olderThanMs": { "type": "integer", "minimum": 0 },
+    "cutoff": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$"
+    },
+    "states": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "enum": ["complete", "blocked", "cancelled"] }
+    },
+    "decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["runId", "decision"],
+        "allOf": [
+          {
+            "if": {
+              "properties": { "decision": { "const": "kept" } },
+              "required": ["decision"]
+            },
+            "then": { "required": ["reason"], "properties": { "reason": {} } },
+            "else": { "not": { "required": ["reason"], "properties": { "reason": {} } } }
+          }
+        ],
+        "properties": {
+          "runId": { "type": "string", "minLength": 1 },
+          "decision": { "enum": ["pruned", "eligible", "kept"] },
+          "reason": {
+            "enum": [
+              "unreadable",
+              "non_terminal",
+              "state_excluded",
+              "runtime_active",
+              "active_jobs",
+              "too_recent",
+              "delete_failed"
+            ]
+          },
+          "status": { "type": "string", "minLength": 1 },
+          "lastEventAt": {
+            "type": "string",
+            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$"
+          }
+        }
+      }
+    },
+    "prunedRuns": { "type": "integer", "minimum": 0 },
+    "eligibleRuns": { "type": "integer", "minimum": 0 },
+    "keptRuns": { "type": "integer", "minimum": 0 },
+    "removedJobRecords": { "type": "integer", "minimum": 0 },
+    "errors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["runId", "message"],
+        "properties": {
+          "runId": { "type": "string", "minLength": 1 },
+          "message": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/scripts/artifact-integrity.mjs

@@ -0,0 +1,114 @@
+import { createHash } from "node:crypto";
+import { execFile as execFileCallback } from "node:child_process";
+import { createReadStream } from "node:fs";
+import { lstat, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+
+const execFile = promisify(execFileCallback);
+const SCHEMA = "cueline-artifact-manifest/1";
+
+export async function sha256File(file) {
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(file)) hash.update(chunk);
+  return hash.digest("hex");
+}
+
+function isInside(parent, candidate) {
+  return candidate.startsWith(`${parent}${path.sep}`);
+}
+
+export async function prepareOutputDirectory(root, requested = "release-artifacts") {
+  const rootReal = await realpath(root);
+  const output = path.resolve(rootReal, requested);
+  if (!isInside(rootReal, output)) {
+    throw new Error("artifact output must be a child directory of the repository");
+  }
+  await mkdir(output, { recursive: true });
+  if ((await lstat(output)).isSymbolicLink()) {
+    throw new Error("artifact output directory must not be a symbolic link");
+  }
+  const outputReal = await realpath(output);
+  if (!isInside(rootReal, outputReal)) {
+    throw new Error("artifact output resolved outside the repository");
+  }
+  return outputReal;
+}
+
+function safeArtifactName(value) {
+  return typeof value === "string" && value !== "" && value === path.basename(value) && !value.includes("..") && value.endsWith(".tgz");
+}
+
+export async function verifyArtifactManifest(manifestPath) {
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  if (manifest.schema !== SCHEMA) throw new Error("unsupported artifact manifest schema");
+  if (!safeArtifactName(manifest.artifact?.filename)) throw new Error("unsafe artifact filename");
+  if (!/^[0-9a-f]{64}$/.test(manifest.artifact.sha256)) throw new Error("invalid artifact sha256");
+  const directory = path.dirname(manifestPath);
+  const artifactPath = path.join(directory, manifest.artifact.filename);
+  const checksumPath = `${artifactPath}.sha256`;
+  const actual = await sha256File(artifactPath);
+  if (actual !== manifest.artifact.sha256) throw new Error("artifact sha256 mismatch");
+  const checksum = await readFile(checksumPath, "utf8");
+  if (checksum !== `${actual}  ${manifest.artifact.filename}\n`) throw new Error("checksum file mismatch");
+  const size = (await lstat(artifactPath)).size;
+  if (size !== manifest.artifact.size) throw new Error("artifact size mismatch");
+  return { schema: SCHEMA, status: "ok", filename: manifest.artifact.filename, sha256: actual, size };
+}
+
+export async function buildArtifact(root, requestedOutput = "release-artifacts") {
+  const output = await prepareOutputDirectory(root, requestedOutput);
+  const { stdout } = await execFile("npm", ["pack", "--json", "--pack-destination", output], {
+    cwd: root,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  const report = JSON.parse(stdout)[0];
+  if (!safeArtifactName(report?.filename)) throw new Error("npm pack returned an unsafe filename");
+  const artifactPath = path.join(output, report.filename);
+  const sha256 = await sha256File(artifactPath);
+  const files = [...(report.files ?? [])]
+    .map(({ path: file, size, mode }) => ({ path: file, size, mode }))
+    .sort((left, right) => left.path.localeCompare(right.path));
+  const manifest = {
+    schema: SCHEMA,
+    package: { name: report.name, version: report.version },
+    artifact: {
+      filename: report.filename,
+      sha256,
+      npmShasum: report.shasum,
+      npmIntegrity: report.integrity,
+      size: report.size,
+      unpackedSize: report.unpackedSize,
+      fileCount: files.length,
+    },
+    files,
+  };
+  const manifestPath = `${artifactPath}.manifest.json`;
+  await writeFile(`${artifactPath}.sha256`, `${sha256}  ${report.filename}\n`, { mode: 0o600 });
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+  const verification = await verifyArtifactManifest(manifestPath);
+  return { ...verification, manifestPath, checksumPath: `${artifactPath}.sha256`, fileCount: files.length };
+}
+
+function parseArguments(args) {
+  const [command, value] = args;
+  if (command === "build" && args.length <= 2) return { command, output: value ?? "release-artifacts" };
+  if (command === "verify" && args.length === 2) return { command, manifest: value };
+  throw new Error("usage: artifact-integrity.mjs build [output-directory] | verify <manifest-path>");
+}
+
+const invokedPath = process.argv[1] === undefined ? "" : path.resolve(process.argv[1]);
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  try {
+    const root = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
+    const args = parseArguments(process.argv.slice(2));
+    const report = args.command === "build"
+      ? await buildArtifact(root, args.output)
+      : await verifyArtifactManifest(path.resolve(root, args.manifest));
+    console.log(JSON.stringify(report, null, 2));
+  } catch (error) {
+    console.error(JSON.stringify({ schema: SCHEMA, status: "error", message: error instanceof Error ? error.message : "artifact operation failed" }));
+    process.exitCode = 1;
+  }
+}

package/scripts/release-check.mjs

@@ -0,0 +1,118 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const execFile = promisify(execFileCallback);
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const REQUIRED_FILES = [
+  ".claude-plugin/plugin.json",
+  ".codex-plugin/plugin.json",
+  "CHANGELOG.md",
+  "LICENSE",
+  "README.md",
+  "bin/cueline",
+  "config/routing.default.json",
+  "dist/src/api.d.ts",
+  "dist/src/api.js",
+  "skills/cueline/SKILL.md",
+];
+const FORBIDDEN_PACKAGE_PATH = /(^|\/)(?:\.env(?:\..*)?|events\.jsonl|runtime\.json|snapshot\.json|cancel\.json|[^/]+\.(?:pem|key|p12))$/;
+
+function finding(code, surface, message) {
+  return { code, surface, message };
+}
+
+export function evaluateReleaseCandidate(input) {
+  const findings = [];
+  const version = input.packageJson.version;
+  if (typeof version !== "string" || !SEMVER.test(version)) {
+    findings.push(finding("VERSION_INVALID", "package", "package version must be strict semver"));
+  }
+  if (input.packageJson.private !== false) {
+    findings.push(finding("PACKAGE_NOT_PUBLIC", "package", "package must explicitly set private to false"));
+  }
+  for (const [surface, candidate] of [
+    ["package-lock", input.packageLockVersion],
+    ["codex-plugin", input.codexPluginVersion],
+    ["claude-plugin", input.claudePluginVersion],
+  ]) {
+    if (candidate !== version) {
+      findings.push(finding("VERSION_MISMATCH", surface, `${surface} version must match package.json`));
+    }
+  }
+  if (typeof version === "string" && !input.changelog.includes(`## ${version} - `)) {
+    findings.push(finding("CHANGELOG_ENTRY_MISSING", "changelog", "current package version needs a dated changelog heading"));
+  }
+  if (!input.allowDirty && input.gitStatus.trim() !== "") {
+    findings.push(finding("GIT_DIRTY", "git", "release check requires a clean worktree"));
+  }
+  const packaged = new Set(input.packFiles);
+  for (const required of REQUIRED_FILES) {
+    if (!packaged.has(required)) {
+      findings.push(finding("PACKAGE_FILE_MISSING", "package", `required package file is missing: ${required}`));
+    }
+  }
+  for (const file of packaged) {
+    if (FORBIDDEN_PACKAGE_PATH.test(file) || file.startsWith("node_modules/") || file.startsWith(".git/")) {
+      findings.push(finding("PACKAGE_FILE_FORBIDDEN", "package", `forbidden package file: ${file}`));
+    }
+  }
+  return findings;
+}
+
+async function readJson(root, relativePath) {
+  return JSON.parse(await readFile(path.join(root, relativePath), "utf8"));
+}
+
+export async function collectReleaseReadiness(root, options = {}) {
+  const [packageJson, packageLock, codexPlugin, claudePlugin, changelog, git, pack] = await Promise.all([
+    readJson(root, "package.json"),
+    readJson(root, "package-lock.json"),
+    readJson(root, ".codex-plugin/plugin.json"),
+    readJson(root, ".claude-plugin/plugin.json"),
+    readFile(path.join(root, "CHANGELOG.md"), "utf8"),
+    execFile("git", ["status", "--porcelain"], { cwd: root }),
+    execFile("npm", ["pack", "--dry-run", "--json"], { cwd: root, maxBuffer: 10 * 1024 * 1024 }),
+  ]);
+  const packReport = JSON.parse(pack.stdout)[0];
+  const packFiles = Array.isArray(packReport?.files) ? packReport.files.map((entry) => entry.path) : [];
+  const findings = evaluateReleaseCandidate({
+    packageJson,
+    packageLockVersion: packageLock?.packages?.[""]?.version,
+    codexPluginVersion: codexPlugin.version,
+    claudePluginVersion: claudePlugin.version,
+    changelog,
+    gitStatus: git.stdout,
+    packFiles,
+    allowDirty: options.allowDirty === true,
+  });
+  return {
+    schema: "cueline-release-check/1",
+    version: packageJson.version,
+    status: findings.length === 0 ? "ok" : "blocked",
+    package: {
+      filename: packReport?.filename ?? null,
+      files: packFiles.length,
+      size: packReport?.size ?? null,
+      unpackedSize: packReport?.unpackedSize ?? null,
+    },
+    findings,
+  };
+}
+
+const invokedPath = process.argv[1] === undefined ? "" : path.resolve(process.argv[1]);
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  const root = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
+  const allowed = new Set(["--allow-dirty"]);
+  const unknown = process.argv.slice(2).filter((arg) => !allowed.has(arg));
+  if (unknown.length > 0) {
+    console.error(JSON.stringify({ schema: "cueline-release-check/1", status: "error", code: "USAGE", message: "usage: npm run release:check -- [--allow-dirty]" }));
+    process.exitCode = 2;
+  } else {
+    const report = await collectReleaseReadiness(root, { allowDirty: process.argv.includes("--allow-dirty") });
+    console.log(JSON.stringify(report, null, 2));
+    if (report.status !== "ok") process.exitCode = 1;
+  }
+}

package/scripts/validate-cli-contracts.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+import Ajv2020 from "ajv/dist/2020.js";
+
+import { main } from "../dist/src/cli/main.js";
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+const contracts = [
+  { id: "doctor", args: ["doctor", "--json"], schema: "cli-doctor.schema.json" },
+  { id: "routing", args: ["routing", "--json"], schema: "cli-routing.schema.json" },
+  {
+    id: "routing-explain",
+    args: ["routing", "explain", "--json"],
+    schema: "cli-routing-explain.schema.json",
+  },
+];
+
+async function invoke(args, environment) {
+  const stdout = [];
+  const stderr = [];
+  const exitCode = await main(args, environment, {
+    stdout: (line) => stdout.push(line),
+    stderr: (line) => stderr.push(line),
+  });
+  if (stdout.length !== 1 || stderr.length !== 0) {
+    throw new Error("CLI contract command did not emit one clean JSON document");
+  }
+  return { exitCode, value: JSON.parse(stdout[0]) };
+}
+
+const environment = {
+  ...process.env,
+  CUELINE_CONFIG: `${root}/config/routing.default.json`,
+};
+const ajv = new Ajv2020({ allErrors: true, strict: true });
+const results = [];
+for (const contract of contracts) {
+  const schema = JSON.parse(
+    await readFile(`${root}/schemas/${contract.schema}`, "utf8"),
+  );
+  const validate = ajv.compile(schema);
+  const invocation = await invoke(contract.args, environment);
+  const valid = validate(invocation.value);
+  results.push({ id: contract.id, valid, exitCode: invocation.exitCode });
+}
+const passed = results.filter((result) => result.valid).length;
+const report = {
+  schema: "cueline-cli-contract-validation/1",
+  status: passed === results.length ? "passed" : "failed",
+  total: results.length,
+  passed,
+  failed: results.length - passed,
+  commands: results,
+};
+console.log(JSON.stringify(report, null, 2));
+process.exitCode = report.status === "passed" ? 0 : 1;

package/scripts/validate-doc-versions.mjs

@@ -0,0 +1,79 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const README_FILES = [
+  "README.md",
+  "README.zh-TW.md",
+  "README.zh-CN.md",
+  "README.ja.md",
+  "README.ko.md",
+];
+
+function collectVersions(text, pattern) {
+  return [...text.matchAll(pattern)].map((match) => match[1]);
+}
+
+function requireCurrentVersion(issues, file, label, versions, expected) {
+  if (versions.length === 0) {
+    issues.push(`${file}: missing ${label}`);
+    return;
+  }
+  for (const version of versions) {
+    if (version !== expected) {
+      issues.push(`${file}: ${label} uses ${version}; expected ${expected}`);
+    }
+  }
+}
+
+export async function validateDocVersions(root) {
+  const manifest = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+  const expected = manifest.version;
+  const issues = [];
+
+  for (const file of README_FILES) {
+    const text = await readFile(path.join(root, file), "utf8");
+    requireCurrentVersion(
+      issues,
+      file,
+      "npm install command",
+      collectVersions(text, /npm install -g cueline@(\d+\.\d+\.\d+)/g),
+      expected,
+    );
+    requireCurrentVersion(
+      issues,
+      file,
+      "release tarball URL",
+      collectVersions(text, /releases\/download\/v\d+\.\d+\.\d+\/cueline-(\d+\.\d+\.\d+)\.tgz/g),
+      expected,
+    );
+    requireCurrentVersion(
+      issues,
+      file,
+      "doctor output",
+      collectVersions(text, /^CueLine (\d+\.\d+\.\d+)$/gm),
+      expected,
+    );
+  }
+
+  const compatibility = await readFile(path.join(root, "docs/compatibility.md"), "utf8");
+  for (const pattern of [/v0\.\d+ status/, /^## Supported in v0\.\d+$/m, /^## Not supported in v0\.\d+$/m]) {
+    if (pattern.test(compatibility)) {
+      issues.push(`docs/compatibility.md: release-specific contract heading ${pattern}`);
+    }
+  }
+  return issues;
+}
+
+const invokedPath = process.argv[1] === undefined ? "" : path.resolve(process.argv[1]);
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  const root = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
+  const manifest = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+  const issues = await validateDocVersions(root);
+  if (issues.length > 0) {
+    for (const issue of issues) console.error(issue);
+    process.exitCode = 1;
+  } else {
+    console.log(`Documentation versions match package ${manifest.version}`);
+  }
+}

package/scripts/validate-node-support.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const EXPECTED_NODE_MAJORS = [22, 24, 26];
+const README_FILES = [
+  "README.md",
+  "README.zh-TW.md",
+  "README.zh-CN.md",
+  "README.ja.md",
+  "README.ko.md",
+];
+
+function parseArgs(args) {
+  let root = fileURLToPath(new URL("..", import.meta.url));
+  let json = false;
+  let rootSeen = false;
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--json" && !json) {
+      json = true;
+    } else if (
+      args[index] === "--root" &&
+      !rootSeen &&
+      typeof args[index + 1] === "string"
+    ) {
+      root = path.resolve(args[index + 1]);
+      rootSeen = true;
+      index += 1;
+    } else {
+      throw new Error("usage: node scripts/validate-node-support.mjs [--root <path>] [--json]");
+    }
+  }
+  return { root, json };
+}
+
+function sameNumbers(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+export async function validateNodeSupport(root) {
+  const findings = [];
+  const manifest = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+  const engine = manifest.engines?.node ?? null;
+  if (engine !== ">=22") {
+    findings.push({
+      code: "ENGINE_REQUIREMENT_MISMATCH",
+      file: "package.json",
+      message: "engines.node must remain >=22.",
+    });
+  }
+
+  const workflow = await readFile(path.join(root, ".github/workflows/ci.yml"), "utf8");
+  const nodeMatrix = /node:\s*\[([^\]]+)\]/.exec(workflow)?.[1]
+    ?.split(",")
+    .map((value) => Number(value.trim())) ?? [];
+  if (!sameNumbers(nodeMatrix, EXPECTED_NODE_MAJORS)) {
+    findings.push({
+      code: "CI_NODE_MATRIX_MISMATCH",
+      file: ".github/workflows/ci.yml",
+      message: "CI Node matrix must be exactly 22, 24, 26.",
+    });
+  }
+  const osMatrix = /os:\s*\[([^\]]+)\]/.exec(workflow)?.[1]
+    ?.split(",")
+    .map((value) => value.trim()) ?? [];
+  if (!sameNumbers(osMatrix, ["ubuntu-latest", "macos-latest"])) {
+    findings.push({
+      code: "CI_OS_MATRIX_MISMATCH",
+      file: ".github/workflows/ci.yml",
+      message: "CI OS matrix must cover Ubuntu and macOS.",
+    });
+  }
+
+  for (const file of README_FILES) {
+    const content = await readFile(path.join(root, file), "utf8");
+    if (!/CI[^\n]*Node[^\n]*22[^\n]*24[^\n]*26/.test(content)) {
+      findings.push({
+        code: "README_NODE_MATRIX_STALE",
+        file,
+        message: "README CI support line must name Node 22, 24, and 26.",
+      });
+    }
+  }
+
+  const compatibility = await readFile(path.join(root, "docs/compatibility.md"), "utf8");
+  if (!/Node\.js 22\+ ESM[^\n]*CI: 22, 24, 26/.test(compatibility)) {
+    findings.push({
+      code: "COMPATIBILITY_NODE_MATRIX_STALE",
+      file: "docs/compatibility.md",
+      message: "Compatibility matrix must name the tested Node majors.",
+    });
+  }
+
+  return {
+    schema: "cueline-node-support-validation/1",
+    status: findings.length === 0 ? "passed" : "failed",
+    engine,
+    ciNodeMajors: nodeMatrix,
+    ciOperatingSystems: osMatrix,
+    currentNode: process.versions.node,
+    findings,
+  };
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2));
+  const report = await validateNodeSupport(options.root);
+  if (options.json) console.log(JSON.stringify(report, null, 2));
+  else console.log(`Node support contract ${report.status}: ${report.ciNodeMajors.join(", ")}`);
+  process.exitCode = report.status === "passed" ? 0 : 1;
+} catch (error) {
+  console.error(
+    `Node support validation failed: ${error instanceof Error ? error.message : "unknown error"}`,
+  );
+  process.exitCode = 1;
+}