@quatronic/sdk 0.6.1-rc.4 → 0.7.0-rc.6

package/README.md

@@ -23,6 +23,32 @@ app runs against its own proxy, and `@quatronic/sdk/eslint` for the fourteen
 `qdc/*` lint rules —
 [`docs/security-rules.md`](docs/security-rules.md).
 
+## Claude Code skills
+
+The SDK ships the app's managed Claude Code skills (`skills/`, one entry per
+skill in `skills/catalog.json`), and `qore-skills sync` writes them into the
+app's `.claude/skills/qore-*`, with `.claude/qore/manifest.json` recording the
+SDK version and a hash per file. The app commits the result.
+
+Installing or bumping the SDK runs the sync by itself. The package's
+`postinstall` syncs when the manifest records a different SDK version, and
+prints what it changed so it lands in the same commit as the bump. It never
+fails an install, and it skips CI, `QORE_SKILLS_SYNC=0`, a directory that is not
+a git checkout, and any bump where a file it would overwrite holds an
+uncommitted hand edit. pnpm 11 runs a dependency's script only when the app
+allows it, so each app's `pnpm-workspace.yaml` needs:
+
+```yaml
+allowBuilds:
+  "@quatronic/sdk": true
+```
+
+Without it, pnpm 11 fails the install with `ERR_PNPM_IGNORED_BUILDS`. pnpm only
+runs the script when the installed version changes, so after a skipped sync run
+`pnpm exec qore-skills sync` yourself; `qore-skills check` exits 1 while the
+skills are behind. How a team extends, replaces or turns off a managed skill is
+in the app's `.claude/qore/README.md` and the `/qore-author-skill` skill.
+
 ## Permissions
 
 The SDK ships a hybrid role/permission layer. Roles come from the Keycloak JWT;

package/dist/cli/legacy/qdc-sourcemaps.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+
+// src/cli/legacy/notice.ts
+import { basename } from "path";
+function renamedNotice(oldName, newName) {
+  return `\u26A0 ${oldName} is renamed to ${newName}; the old name keeps working until the next major release.`;
+}
+var invoked = basename(process.argv[1] ?? "", ".js");
+if (invoked.startsWith("qdc-")) console.warn(renamedNotice(invoked, `qore-${invoked.slice(4)}`));
+
+// src/cli/sourcemaps.ts
+import { execFile } from "child_process";
+import { copyFileSync, existsSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { fileURLToPath } from "url";
+import { promisify } from "util";
+
+// src/cli/sourcemaps-core.ts
+import { posix } from "path";
+var SHA = /^[0-9a-f]{40}$/;
+var BUNDLE = /^[a-z0-9][a-z0-9-]{0,31}$/;
+var SCRIPT = /\.(js|mjs|cjs)$/;
+var MAPPING_URL = /^\/\/# sourceMappingURL=(\S+)[ \t]*$/gm;
+var STANDALONE_SERVER = "standalone/.next/server/";
+function parseArgs(argv) {
+  const [cmd, dir, ...rest] = argv;
+  if (cmd !== "upload" || !dir) return { error: "usage: qore-sourcemaps upload <dir> [--bundle <name>]" };
+  let bundle = "app";
+  if (rest[0] === "--bundle") bundle = rest[1] ?? "";
+  if (!BUNDLE.test(bundle)) return { error: `invalid bundle name: ${bundle}` };
+  return { dir, bundle };
+}
+function nextRoots(has) {
+  if (!has("BUILD_ID") || !has("server")) return null;
+  return ["static", "server"].filter(has);
+}
+function underNodeModules(p) {
+  return p.split("/").includes("node_modules");
+}
+function inRoots(p, roots) {
+  if (underNodeModules(p)) return false;
+  if (roots) return roots.some((r) => p.startsWith(`${r}/`));
+  return !p.startsWith("standalone/");
+}
+function lastMappingUrl(src) {
+  return [...src.matchAll(MAPPING_URL)].at(-1);
+}
+function fixMappingUrl(src) {
+  const m = lastMappingUrl(src);
+  if (!m?.[1] || !/%(5b|5d|40)/i.test(m[1])) return null;
+  const fixed = m[1].replace(/%5b/gi, "[").replace(/%5d/gi, "]").replace(/%40/g, "@");
+  const at = m.index ?? 0;
+  return src.slice(0, at) + `//# sourceMappingURL=${fixed}` + src.slice(at + m[0].length);
+}
+function mapFor(js, src) {
+  const url = lastMappingUrl(src)?.[1];
+  if (!url || url.startsWith("data:") || /^[a-z]+:/i.test(url)) return null;
+  let decoded = url;
+  try {
+    decoded = decodeURIComponent(url);
+  } catch {
+  }
+  const target = posix.normalize(posix.join(posix.dirname(js), decoded));
+  return target.startsWith("../") || posix.isAbsolute(target) ? null : target;
+}
+function listMaps(paths) {
+  return paths.filter((p) => p.endsWith(".map") && !underNodeModules(p));
+}
+function hasDebugId(text) {
+  try {
+    const map = JSON.parse(text);
+    const id = map?.debugId ?? map?.debug_id;
+    return typeof id === "string" && id.length > 0;
+  } catch {
+    return false;
+  }
+}
+function listArtifacts(dir, walk, readText, roots) {
+  const all = walk(dir);
+  const set = new Set(all);
+  const used = /* @__PURE__ */ new Set();
+  const files = [];
+  let dropped = 0;
+  for (const js of all) {
+    if (!SCRIPT.test(js) || !inRoots(js, roots)) continue;
+    const map = mapFor(js, readText(js));
+    if (!map) continue;
+    if (!map.endsWith(".map") || !set.has(map) || !inRoots(map, roots) || used.has(map) || !hasDebugId(readText(map))) {
+      dropped++;
+      continue;
+    }
+    used.add(map);
+    files.push(js, map);
+  }
+  return { maps: listMaps(all), files, dropped };
+}
+function standaloneTwins(paths) {
+  const set = new Set(paths);
+  return paths.filter((p) => p.startsWith("server/") && SCRIPT.test(p)).map((p) => [p, `${STANDALONE_SERVER}${p.slice("server/".length)}`]).filter(([, twin]) => set.has(twin));
+}
+function uploadUrl(base, sha, bundle) {
+  return `${base.replace(/\/+$/, "")}/${sha}/${bundle}`;
+}
+function skipReason(env) {
+  for (const k of ["QORE_BUILD_UPLOAD_URL", "QORE_BUILD_UPLOAD_TOKEN", "NF_GIT_SHA"]) {
+    if (!env[k]) return `${k} is not set`;
+  }
+  if (!SHA.test(env.NF_GIT_SHA ?? "")) return "NF_GIT_SHA is not a commit sha";
+  return null;
+}
+
+// src/cli/sourcemaps.ts
+var execFileP = promisify(execFile);
+var UPLOAD_TIMEOUT_MS = 5 * 6e4;
+var RUN_TIMEOUT_MS = 12e4;
+var SCRIPT2 = /\.(js|mjs|cjs)$/;
+async function runCommand(cmd, args) {
+  await execFileP(cmd, args, {
+    timeout: RUN_TIMEOUT_MS,
+    maxBuffer: 16 * 1024 * 1024,
+    env: { ...process.env, COPYFILE_DISABLE: "1" }
+  });
+}
+function walkDir(dir, prefix = "") {
+  const out = [];
+  for (const d of readdirSync(join(dir, prefix), { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${d.name}` : d.name;
+    if (d.isDirectory() && d.name !== "node_modules") out.push(...walkDir(dir, rel));
+    else if (d.isFile()) out.push(rel);
+  }
+  return out;
+}
+var defaultIo = () => ({
+  env: process.env,
+  walk: (dir) => walkDir(dir),
+  exists: existsSync,
+  readText: (p) => readFileSync(p, "utf8"),
+  writeText: (p, t) => writeFileSync(p, t),
+  copyFile: copyFileSync,
+  run: runCommand,
+  readFile: (p) => readFileSync(p),
+  remove: (p) => rmSync(p, { force: true }),
+  fetch,
+  tmpFile: () => join(tmpdir(), `qdc-maps-${process.pid}.tgz`)
+});
+function describe(err, token) {
+  const msg = (err instanceof Error ? err.message : String(err)).slice(0, 500);
+  return token ? msg.split(token).join("***") : msg;
+}
+function tryRemove(io, path) {
+  try {
+    io.remove(path);
+  } catch {
+  }
+}
+async function main(argv = process.argv.slice(2), io = defaultIo()) {
+  const args = parseArgs(argv);
+  if ("error" in args) {
+    console.warn(`qore-sourcemaps: ${args.error}`);
+    const dir2 = argv[0] === "upload" ? argv[1] : void 0;
+    if (dir2 && !dir2.startsWith("-")) {
+      try {
+        for (const m of listMaps(io.walk(dir2))) tryRemove(io, join(dir2, m));
+      } catch (err) {
+        console.warn(`qore-sourcemaps: cleanup skipped: ${describe(err, io.env.QORE_BUILD_UPLOAD_TOKEN)}`);
+      }
+    }
+    return;
+  }
+  const { dir, bundle } = args;
+  const at = (rel) => join(dir, rel);
+  let maps = [];
+  const scratch = [];
+  try {
+    const paths = io.walk(dir);
+    maps = listMaps(paths);
+    const skip = skipReason(io.env);
+    if (skip) {
+      console.log(`qore-sourcemaps: skipped (${skip})`);
+      return;
+    }
+    const roots = nextRoots((rel) => io.exists(at(rel)));
+    if (roots) {
+      for (const p of paths) {
+        if (!SCRIPT2.test(p) || !roots.some((r) => p.startsWith(`${r}/`))) continue;
+        const fixed = fixMappingUrl(io.readText(at(p)));
+        if (fixed !== null) io.writeText(at(p), fixed);
+      }
+      await io.run("sentry-cli", ["sourcemaps", "inject", ...roots.map(at)]);
+      for (const [src, twin] of standaloneTwins(paths)) io.copyFile(at(src), at(twin));
+    } else {
+      await io.run("sentry-cli", ["sourcemaps", "inject", dir]);
+    }
+    const { files, dropped } = listArtifacts(dir, () => paths, (rel) => io.readText(at(rel)), roots);
+    if (dropped > 0) console.log(`qore-sourcemaps: dropped ${dropped} source maps the uploader would reject`);
+    if (files.length === 0) {
+      console.log("qore-sourcemaps: no source maps found, nothing to upload");
+      return;
+    }
+    const tgz = io.tmpFile();
+    const list = `${tgz}.list`;
+    scratch.push(list, tgz);
+    io.writeText(list, `${files.join("\n")}
+`);
+    await io.run("tar", ["-czf", tgz, "-C", dir, "-T", list]);
+    const body = io.readFile(tgz);
+    const res = await io.fetch(uploadUrl(io.env.QORE_BUILD_UPLOAD_URL, io.env.NF_GIT_SHA, bundle), {
+      method: "PUT",
+      headers: {
+        Authorization: `Bearer ${io.env.QORE_BUILD_UPLOAD_TOKEN}`,
+        "Content-Type": "application/gzip",
+        "Content-Length": String(body.byteLength)
+      },
+      body: new Uint8Array(body),
+      signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS)
+    });
+    if (res.ok) console.log(`qore-sourcemaps: handed off ${files.length / 2} source maps (${body.byteLength} bytes)`);
+    else console.warn(`qore-sourcemaps: upload refused, broker answered ${res.status}`);
+  } catch (err) {
+    console.warn(`qore-sourcemaps: upload skipped: ${describe(err, io.env.QORE_BUILD_UPLOAD_TOKEN)}`);
+  } finally {
+    for (const m of maps) tryRemove(io, at(m));
+    for (const s of scratch) tryRemove(io, s);
+  }
+}
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+}
+if (isMainModule()) {
+  void main();
+}

package/dist/cli/legacy/qdc-test-report.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+// src/cli/legacy/notice.ts
+import { basename } from "path";
+function renamedNotice(oldName, newName) {
+  return `\u26A0 ${oldName} is renamed to ${newName}; the old name keeps working until the next major release.`;
+}
+var invoked = basename(process.argv[1] ?? "", ".js");
+if (invoked.startsWith("qdc-")) console.warn(renamedNotice(invoked, `qore-${invoked.slice(4)}`));
+
+// src/cli/test-report.ts
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+
+// src/cli/test-report-core.ts
+var SCHEMA_VERSION = 1;
+function asRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  return value;
+}
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function nonNegative(value) {
+  return value !== null && value >= 0 ? value : 0;
+}
+function countAssertions(testResults) {
+  let passed = 0;
+  let failed = 0;
+  let skipped = 0;
+  for (const file of testResults) {
+    const rec = asRecord(file);
+    const assertions = rec?.assertionResults;
+    if (!Array.isArray(assertions)) continue;
+    for (const assertion of assertions) {
+      const status = asRecord(assertion)?.status;
+      if (status === "passed") passed += 1;
+      else if (status === "failed") failed += 1;
+      else if (status === "pending" || status === "todo" || status === "skipped") skipped += 1;
+    }
+  }
+  return { passed, failed, skipped };
+}
+function spanMs(testResults) {
+  let earliest = null;
+  let latest = null;
+  for (const file of testResults) {
+    const rec = asRecord(file);
+    if (!rec) continue;
+    const start = finiteNumber(rec.startTime);
+    const end = finiteNumber(rec.endTime);
+    if (start !== null && (earliest === null || start < earliest)) earliest = start;
+    if (end !== null && (latest === null || end > latest)) latest = end;
+  }
+  if (earliest === null || latest === null || latest < earliest) return 0;
+  return Math.round(latest - earliest);
+}
+function summarizeVitestJson(raw) {
+  const root = asRecord(raw);
+  if (!root) return null;
+  const testResults = Array.isArray(root.testResults) ? root.testResults : [];
+  const topPassed = finiteNumber(root.numPassedTests);
+  const topFailed = finiteNumber(root.numFailedTests);
+  const topPending = finiteNumber(root.numPendingTests);
+  const topTodo = finiteNumber(root.numTodoTests);
+  const hasTopLevelCounts = topPassed !== null || topFailed !== null;
+  if (!hasTopLevelCounts && testResults.length === 0) {
+    return null;
+  }
+  const counted = hasTopLevelCounts ? {
+    passed: nonNegative(topPassed),
+    failed: nonNegative(topFailed),
+    skipped: nonNegative(topPending) + nonNegative(topTodo)
+  } : countAssertions(testResults);
+  return { ...counted, durationMs: spanMs(testResults) };
+}
+function summarizeCoverage(raw) {
+  const total = asRecord(asRecord(raw)?.total);
+  if (!total) return null;
+  const lines = finiteNumber(asRecord(total.lines)?.pct);
+  const branches = finiteNumber(asRecord(total.branches)?.pct);
+  if (lines === null && branches === null) return null;
+  return { linesPct: lines, branchesPct: branches };
+}
+function buildReport(input) {
+  const suites = {};
+  if (input.unit.kind === "ok") suites.unit = input.unit.summary;
+  if (input.integration.kind === "ok") suites.integration = input.integration.summary;
+  const measured = Object.keys(suites).length > 0;
+  const anyParseFailure = input.unit.kind === "parse_failed" || input.integration.kind === "parse_failed";
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    commitSha: input.commitSha,
+    ranAt: input.ranAt,
+    measured,
+    reason: measured ? null : anyParseFailure ? "parse_failed" : "no_results",
+    suites,
+    coverage: input.coverage
+  };
+}
+function unmeasuredReport(commitSha, ranAt, reason) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    commitSha,
+    ranAt,
+    measured: false,
+    reason,
+    suites: {},
+    coverage: null
+  };
+}
+
+// src/cli/test-report.ts
+var DEFAULT_OUT = ".qdc/test-report.json";
+function parseArgs(argv) {
+  const args = argv.slice();
+  const opts = {
+    unit: null,
+    integration: null,
+    coverage: null,
+    commitSha: null,
+    out: DEFAULT_OUT
+  };
+  while (args.length) {
+    const arg = args.shift();
+    if (arg === "--unit") opts.unit = args.shift() ?? null;
+    else if (arg === "--integration") opts.integration = args.shift() ?? null;
+    else if (arg === "--coverage") opts.coverage = args.shift() ?? null;
+    else if (arg === "--commit-sha") opts.commitSha = args.shift() ?? null;
+    else if (arg === "--out") opts.out = args.shift() ?? opts.out;
+  }
+  return opts;
+}
+function readJson(path) {
+  if (!path) return { kind: "absent" };
+  const resolved = resolve(path);
+  if (!existsSync(resolved)) return { kind: "absent" };
+  try {
+    return { kind: "ok", value: JSON.parse(readFileSync(resolved, "utf8")) };
+  } catch {
+    return { kind: "bad" };
+  }
+}
+function readSuite(path) {
+  const read = readJson(path);
+  if (read.kind === "absent") return { kind: "absent" };
+  if (read.kind === "bad") return { kind: "parse_failed" };
+  const summary = summarizeVitestJson(read.value);
+  return summary ? { kind: "ok", summary } : { kind: "parse_failed" };
+}
+function readCoverage(path) {
+  const read = readJson(path);
+  return read.kind === "ok" ? summarizeCoverage(read.value) : null;
+}
+function writeReport(out, report) {
+  const resolved = resolve(out);
+  mkdirSync(dirname(resolved), { recursive: true });
+  writeFileSync(resolved, `${JSON.stringify(report, null, 2)}
+`);
+}
+function main(argv = process.argv.slice(2)) {
+  let out = DEFAULT_OUT;
+  let commitSha = null;
+  const ranAt = (/* @__PURE__ */ new Date()).toISOString();
+  try {
+    const opts = parseArgs(argv);
+    out = opts.out;
+    commitSha = opts.commitSha;
+    const report = buildReport({
+      commitSha: opts.commitSha,
+      ranAt,
+      unit: readSuite(opts.unit),
+      integration: readSuite(opts.integration),
+      coverage: readCoverage(opts.coverage)
+    });
+    writeReport(out, report);
+    const summary = report.measured ? Object.entries(report.suites).map(([name, s]) => `${name}: ${s.passed} passed, ${s.failed} failed, ${s.skipped} skipped`).join("; ") : `unmeasured (${report.reason})`;
+    console.log(`qore-test-report \u2192 ${out} \u2014 ${summary}`);
+  } catch (err) {
+    console.warn(
+      `qore-test-report could not build a report: ${err instanceof Error ? err.message : String(err)}`
+    );
+    try {
+      writeReport(out, unmeasuredReport(commitSha, ranAt, "parse_failed"));
+    } catch {
+    }
+  }
+}
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+}
+if (isMainModule()) {
+  main();
+}