@nasebanal/cli 0.6.0 → 0.8.0

package/README.md

@@ -64,6 +64,10 @@ nb assurance report upload --file specmatic/junit/TEST-junit-jupiter.xml --kind
 # One repository, several API versions: label the result (the version is part of the suite's identity, so v1 and v2 of the same name sit side by side)
 nb assurance report upload --file specmatic/v2/junit.xml --kind contract --tool specmatic --api-version v2
 # unit tests hold for every version: leave --api-version out
+# set NB_API_VERSION once (a CI variable per job or branch) instead of repeating the flag; the flag wins, an empty variable means none
+NB_API_VERSION=v2 nb assurance report upload --file specmatic/v2/junit.xml --kind contract --tool specmatic
+# a project may require a version for some kinds of result (Assurance > Projects > the project's settings): a result of such a kind
+# without one is refused with 422 API_VERSION_REQUIRED (the message says to pass --api-version or set NB_API_VERSION)
 
 # Extra numbers for the suite (repeatable), e.g. ZAP's findings by severity - what the Assurance security gate reads
 nb assurance report upload --file zap/report/baseline-junit.xml --kind security --tool zap --metric high=0 --metric medium=3 --metric low=2
@@ -74,12 +78,54 @@ nb assurance report upload --dir locust/logs/20261001_090000
 
 - **Project:** found by name, created when missing (`--no-create-project` to fail
   instead). In CI the name defaults to the repository (`GITHUB_REPOSITORY` /
-  `CI_PROJECT_PATH`); elsewhere pass `--project`.
+  `CI_PROJECT_PATH`); elsewhere pass `--project`. That is the zero-configuration
+  start; once the project exists, **pin it by id** (`--project-id <id>` or
+  `NB_ASSURANCE_PROJECT_ID`): the upload then goes straight to that project, nothing
+  is looked up by name or created, so renaming the project, a typo, or a renamed
+  repository can no longer send results elsewhere. An unknown id is an error, never a
+  new project. The id is printed after every upload (and, in GitHub Actions, written
+  to `$GITHUB_OUTPUT` as `project_id`). Keep one id per environment (`--env`), and
+  take care when copying a workflow to another repository: its id goes with it.
+- **Link to the report in the repository:** the CLI also sends the CI `--provider`
+  (`github` | `gitlab` | `other`, detected) and, when the report file is **committed**
+  (tracked, unchanged since `HEAD`, and `HEAD` is the reported commit), its path
+  relative to the repository root, so Assurance can link to the file at that commit.
+  A report that CI has just generated is not in the commit, so no path is sent;
+  override with `--report-path`.
+- **Tie the project to its API in the catalog (`--spec-id`, `--spec-environment`):**
+  `--spec-id <id>` links the project to a spec of the API catalog (its id in Assurance /
+  Specs), `--spec-environment production` says which environment of it the project covers
+  (needs `--spec-id`). A new project is created already linked; an existing one is
+  changed **only when it differs**, so a pipeline that runs on every commit writes nothing
+  once the link is right. Pointing it at another spec clears the old environment unless one
+  is given too. The id is not looked up in the catalog (it is another service): a typo shows
+  as "no spec" on the project. The link is set after the result is in, so a failure there
+  leaves the result reported and says so. `--spec-file <openapi.yaml>` does the whole chain in one command (see below).
+- **Register the spec file and tie the project to it in one command (`--spec-file`):**
+  `nb assurance report upload ... --spec-file openapi.yaml [--spec-name N] [--spec-group G]
+  [--spec-org ID] [--spec-environment production]` first runs `nb specs push` on the file,
+  then creates / links the project to the spec it returns, then reports the result. The
+  catalog's answer never costs the result: if registering the spec fails (a plan without the
+  catalog, the limit of specs), the result is still reported, without the link, and the command
+  ends with the reason and a non-zero exit. Exclusive with `--spec-id`.
 - **Run:** every job of one pipeline run shares a run key (CI: `GITHUB_RUN_ID` +
   attempt, `CI_PIPELINE_ID`; locally `local-<sha>-<day>`), so a unit job and an e2e
   job land in the same run, and re-running a job replaces its own result.
   Commit, branch and CI URL are detected the same way; override with `--run-key`,
   `--commit`, `--branch`, `--ci-url`.
+- **Keep the tool's own report (`--attach <file|folder>`):** a CI runner is thrown away
+  when the job ends, and the summary above is not the tool's report (Playwright's HTML
+  report, Specmatic's report, a JUnit file with everything in it). `--attach` sends the
+  original with the result: a file as it is, a folder as a zip made by the CLI (regular
+  files only, symbolic links are never followed). Up to 20 MiB per result and 200 MiB per
+  project; the CLI checks the size before anything is sent. It is **opt-in twice** - nothing is
+  attached unless you pass it, and the server refuses it (403 `ATTACHMENTS_DISABLED`) until
+  the project has turned on "Attaching original reports" in its settings in Assurance (off by
+  default). Make sure the report holds no secrets or personal data.
+  The server only stores it (next to the result's cases, deleted with the result and by
+  the project's retention) and offers it as a **download** to the project's members in
+  Assurance; it is never opened, unzipped or shown in the browser. A failed attachment
+  leaves the result reported and the command exits non-zero with the reason.
 - **Pass / fail:** JUnit - any failed or errored test fails the suite. Locust - an
   unhandled task exception, or a failure ratio above `--max-fail-ratio` (default
   `$LOCUST_MAX_FAIL_RATIO`, else 0), fails it - the same rule as nb-quickstarts'
@@ -91,6 +137,30 @@ nb assurance report upload --dir locust/logs/20261001_090000
   is sent in total (names and outcomes always stay). Locust reports have no cases.
 - `--dry-run` prints what would be sent and calls nothing.
 
+## The API catalog from a pipeline (`nb specs push`)
+
+`nb specs push --file openapi.yaml` registers an OpenAPI document in the catalog (your own
+specs, Evolution): a new spec, or a new version of the one that has the same name (or `--id`).
+It is made to run on **every commit**:
+
+- **Nothing is uploaded when the file is already the latest version.** The CLI compares the
+  document's SHA-256 with the `content_hash` the catalog keeps for the latest version before it
+  sends anything; the same bytes print `unchanged (already vN: nothing uploaded)`. (The catalog
+  refuses an identical upload itself, `409 UNCHANGED`, which is also taken as "unchanged", for two
+  jobs racing.) The comparison is of bytes: a generator that writes a timestamp into the
+  document makes a new version every run, so keep the output stable.
+- **No group has to exist.** A spec is registered in no group unless `--group <name>` is given
+  (the group is made when missing); an existing spec is never moved by a push (the catalog
+  moves it, by drag and drop or the select on its page).
+- The name is `--name`, else the document's `info.title`, else the file's name. A new version
+  carries a note made from the commit, the branch and the CI run (`--note` replaces it), so
+  "which commit made v7" has an answer.
+- `--org <id|personal>` (or `$NB_SPECS_ORG`) says whose catalog it is: the catalog is per
+  owner and needs `X-Active-Organization-Id`; `personal` (the default) is your own, an
+  organization's needs its Enterprise plan. `--dry-run` reads the catalog and says what would
+  happen. `NB_SPECS_BASE_URL` points it at another host (local: `http://localhost:8792`).
+- In GitHub Actions the spec's id is written to `$GITHUB_OUTPUT` as `spec_id`.
+
 ## Installation
 
 The CLI installs the `nb` command. Node ≥ 20 is required.
@@ -204,7 +274,10 @@ Notes:
 
 ### From source (contributors)
 
-Requires a sibling `nb-api-specs` checkout (the build syncs specs from it):
+No registry token and no sibling checkout needed: the build fetches the pinned,
+public API contracts from `api-specs.nasebanal.com` (see
+[Local Development](#local-development)). Contributing: see
+[CONTRIBUTING.md](CONTRIBUTING.md).
 
 ```bash
 git clone https://github.com/nasebanal/nb-cli.git
@@ -359,7 +432,9 @@ npm run typecheck       # tsc --noEmit
 `sync-specs` resolves each spec from, in order:
 
 1. `node_modules/@nasebanal/api-specs-<api>/spec.yaml` (installed package), then
-2. `../nb-api-specs/packages/<api>/spec.yaml` (local monorepo checkout).
+2. `../nb-api-specs/packages/<api>/spec.yaml` (local monorepo checkout), then
+3. the version pinned in `spec-versions.json`, fetched from the public specs host
+   (the only source under CI, and what an outside contributor gets).
 
 In production the published `@nasebanal/api-specs-*` packages are pinned as
 dependencies — the consumer side of CDD. In local dev we copy straight from the

package/dist/auth.js

@@ -11,6 +11,7 @@ import { Command } from "commander";
 import { createInterface } from "node:readline";
 import { loadConfig, saveConfig, resolveToken, resolveEnv, configFilePath } from "./config.js";
 import { login } from "./oauth.js";
+import { envTokenHint } from "./output.js";
 function readSecretLine(promptText) {
     const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: false });
     process.stdout.write(promptText);
@@ -60,6 +61,10 @@ export function buildAuthCommand() {
         const expiry = tokens.expires_at ? new Date(tokens.expires_at).toLocaleString() : "n/a";
         process.stdout.write(`\n✓ Logged in. Credentials saved to ${configFilePath()}\n`);
         process.stdout.write(`  Access token expires: ${expiry}${tokens.refresh_token ? " (auto-refreshes)" : ""}\n`);
+        // The login is saved, but a token exported in this shell still wins: say so now, not after a confusing 401 later.
+        const shadowed = envTokenHint();
+        if (shadowed)
+            process.stderr.write(`\n! ${shadowed.replace("takes priority over `nb auth login`.", "takes priority over this login.")}\n`);
     });
     auth
         .command("logout")

package/dist/http.js

@@ -26,11 +26,16 @@ export async function request(opts) {
     const headers = { Accept: "application/json" };
     if (opts.token)
         headers.Authorization = `Bearer ${opts.token}`;
+    Object.assign(headers, opts.headers);
     const init = { method: opts.method.toUpperCase(), headers };
     if (opts.body !== undefined) {
         headers["Content-Type"] = "application/json";
         init.body = JSON.stringify(opts.body);
     }
+    else if (opts.rawBody !== undefined) {
+        headers["Content-Type"] = opts.contentType ?? "application/octet-stream";
+        init.body = opts.rawBody;
+    }
     let res;
     try {
         res = await fetch(url, init);

package/dist/index.js

@@ -14,6 +14,7 @@ import { buildAuthCommand } from "./auth.js";
 import { specExists } from "./spec/loader.js";
 import { printError } from "./output.js";
 import { buildReportUploadCommand } from "./reports/upload.js";
+import { buildSpecsCommand } from "./specs/command.js";
 import { buildUpgradeCommand, startUpdateNotifier } from "./update.js";
 // Single source of truth for the version: package.json (dist/ and src/ both sit
 // next to it). A hard-coded string here drifts from the release tag.
@@ -28,6 +29,7 @@ program
     .showHelpAfterError();
 program.addCommand(buildAuthCommand());
 program.addCommand(buildUpgradeCommand(version));
+program.addCommand(buildSpecsCommand());
 for (const api of API_CATALOG) {
     if (!specExists(api.spec)) {
         // Spec not synced yet — register a stub that explains how to fix it rather

package/dist/output.js

@@ -2,7 +2,28 @@
  * Output helpers. Default output is pretty JSON to stdout; errors go to stderr.
  * A future iteration can add `--format table` once command metadata is richer.
  */
+import { appendFileSync } from "node:fs";
 import { ApiError } from "./http.js";
+/** In GitHub Actions, make a value available to later steps as `steps.<id>.outputs.<key>`. A missing output file never fails a command that succeeded. */
+export function exportGithubOutput(key, value) {
+    const file = process.env.GITHUB_OUTPUT;
+    if (!file)
+        return;
+    try {
+        appendFileSync(file, `${key}=${value}\n`);
+    }
+    catch {
+        // The command succeeded; its output file is a convenience.
+    }
+}
+/**
+ * Why a 401 may come from the shell and not from the login: `NB_TOKEN` in the environment always wins over `nb auth login`
+ * (the CI path), so a token left exported - typically a PAT made for production - is what gets sent, and a local server has
+ * never heard of it. Null when `NB_TOKEN` is not set (then the hint to log in is the whole story).
+ */
+export function envTokenHint() {
+    return process.env.NB_TOKEN ? "NB_TOKEN is set in this shell and takes priority over `nb auth login`. If it is not valid for this server (a PAT made for production is unknown to a local one), run `unset NB_TOKEN` and try again." : null;
+}
 export function printJson(data) {
     if (typeof data === "string") {
         process.stdout.write(data + "\n");
@@ -19,6 +40,9 @@ export function printError(err) {
         }
         if (err.status === 401) {
             process.stderr.write("\nHint: run `nb auth login` or set NB_TOKEN to authenticate.\n");
+            const envHint = envTokenHint();
+            if (envHint)
+                process.stderr.write(`${envHint}\n`);
         }
         return;
     }

package/dist/reports/ci.js

@@ -5,6 +5,7 @@
  * piles up). Every value can still be overridden on the command line.
  */
 import { execFileSync } from "node:child_process";
+import { basename, dirname, resolve } from "node:path";
 export function readGit() {
     const git = (...args) => {
         try {
@@ -16,6 +17,36 @@ export function readGit() {
     };
     return { sha: git("rev-parse", "HEAD"), branch: git("branch", "--show-current") };
 }
+const runGit = (args, cwd) => {
+    try {
+        return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * The path of a report file inside the repository, relative to its root (`reports/junit.xml`), for a
+ * link to the file at the run's commit. Only a file that is COMMITTED qualifies: tracked, identical to
+ * HEAD, and HEAD is the commit being reported. A report that CI just generated is none of those, and a
+ * link to a file that is not in the commit would be a dead one, so the answer is then null.
+ */
+export function readReportPath(file, commitSha, git = runGit) {
+    const abs = resolve(file);
+    const cwd = dirname(abs);
+    const name = basename(abs);
+    const path = git(["ls-files", "--full-name", "--", name], cwd);
+    if (!path)
+        return null;
+    if (git(["diff", "--quiet", "HEAD", "--", name], cwd) === null)
+        return null;
+    if (commitSha) {
+        const head = git(["rev-parse", "HEAD"], cwd);
+        if (!head || !(head === commitSha || head.startsWith(commitSha) || commitSha.startsWith(head)))
+            return null;
+    }
+    return path.replace(/\\/g, "/");
+}
 const nonEmpty = (v) => (v && v.trim() !== "" ? v : null);
 export function detectCi(env, git = readGit, now = new Date()) {
     if (env.GITHUB_ACTIONS === "true") {

package/dist/reports/upload.js

@@ -12,17 +12,62 @@
  * instead of a megabyte of report.
  */
 import { Command } from "commander";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { resolveAccessToken, resolveEnv } from "../config.js";
 import { request, resolveBaseUrl, ApiError } from "../http.js";
 import { loadSpec } from "../spec/loader.js";
-import { printJson } from "../output.js";
-import { detectCi } from "./ci.js";
+import { exportGithubOutput, printJson } from "../output.js";
+import { detectCi, readReportPath } from "./ci.js";
 import { parseJunit } from "./junit.js";
 import { summariseLocust } from "./locust.js";
 import { parseSpecmaticCoverage } from "./specmatic.js";
+import { MAX_ATTACHMENT_BYTES, zipDirectory } from "./zip.js";
+import { checkOrg, ciNote, pushSpec, readSpecFile, specNameFor, hashText, specsBaseUrl } from "../specs/push.js";
 export const SUITE_KINDS = ["unit", "e2e", "load", "contract", "security"];
+export const RUN_PROVIDERS = ["github", "gitlab", "other"];
+/** What the API's ids look like (12 letters and digits); anything else is a typo, not a project. */
+const PROJECT_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/** A spec's id in the API catalog (nb-specs-api): letters, digits, `_` and `-`, up to 64. */
+const SPEC_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+const MAX_SPEC_ENVIRONMENT = 40;
+/** `--spec-id`: trimmed; it is never looked up here (the catalog is another service; a typo shows as "no spec" in the project). */
+export function checkSpecId(raw) {
+    const v = raw.trim();
+    if (!SPEC_ID_PATTERN.test(v))
+        throw new Error(`--spec-id '${raw}' is not a catalog spec id (letters, digits, '-' and '_', up to 64)`);
+    return v;
+}
+/** `--spec-environment`: which environment of the API the project covers (production, staging, ...). */
+export function checkSpecEnvironment(raw) {
+    const v = raw.trim();
+    if (v === "" || v.length > MAX_SPEC_ENVIRONMENT)
+        throw new Error(`--spec-environment must be 1 to ${MAX_SPEC_ENVIRONMENT} characters`);
+    return v;
+}
+/** `--project-id` / `NB_ASSURANCE_PROJECT_ID`: trimmed; empty is none. */
+export function checkProjectId(raw) {
+    const v = raw?.trim();
+    if (!v)
+        return undefined;
+    if (!PROJECT_ID_PATTERN.test(v))
+        throw new Error(`--project-id '${raw}' is not a project id (letters, digits, '-' and '_'): copy it from the project's page or from a previous upload's output`);
+    return v;
+}
+export function checkProvider(raw) {
+    const v = raw.trim().toLowerCase();
+    if (!RUN_PROVIDERS.includes(v))
+        throw new Error(`--provider must be one of ${RUN_PROVIDERS.join(" | ")}`);
+    return v;
+}
+/** `--report-path`: a path relative to the repository root, as the API accepts it. */
+export function checkReportPath(raw) {
+    const v = raw.trim();
+    if (v === "" || v.length > 512 || v.startsWith("/") || v.includes("\\") || v.split("/").some((s) => s === ".." || s === "")) {
+        throw new Error("--report-path must be a path relative to the repository root, e.g. reports/junit.xml");
+    }
+    return v;
+}
 /**
  * The tool is a label (nb-assurance-api `TOOL_PATTERN`): what a result means is carried by its kind and its
  * numbers, so any scanner or runner can be reported without a change here, as long as its report is
@@ -72,7 +117,7 @@ export function parseMetrics(pairs) {
 export function checkApiVersion(label) {
     const v = label.trim();
     if (!API_VERSION_PATTERN.test(v)) {
-        throw new Error(`--api-version '${label}' is not a version label: use letters, digits, '.', '_' and '-' (up to 32), e.g. v1 or 2026-10`);
+        throw new Error(`--api-version / NB_API_VERSION '${label}' is not a version label: use letters, digits, '.', '_' and '-' (up to 32), e.g. v1 or 2026-10`);
     }
     return v;
 }
@@ -168,15 +213,16 @@ export function parseReport(opts) {
     };
 }
 /** Find the project by name, or create it (unless told not to). Returns its id. */
-export async function ensureProject(conn, name, repo, create) {
+export async function ensureProject(conn, name, repo, create, spec) {
     const find = async () => {
         const res = await request({ ...conn, method: "GET", path: "/api/v1/projects", query: { name } });
         const list = res.data.data.data;
-        return list[0]?.id ?? null;
+        const hit = list[0];
+        return hit ? { id: hit.id, created: false, spec: { id: hit.spec_id ?? null, environment: hit.spec_environment ?? null } } : null;
     };
     const existing = await find();
     if (existing)
-        return { id: existing, created: false };
+        return existing;
     if (!create) {
         throw new Error(`No project named '${name}' (create it first, or drop --no-create-project).`);
     }
@@ -185,30 +231,78 @@ export async function ensureProject(conn, name, repo, create) {
             ...conn,
             method: "POST",
             path: "/api/v1/projects",
-            body: { name, ...(repo ? { repo } : {}) },
+            // A new project is born linked: nothing to compare, nothing to patch afterwards.
+            body: { name, ...(repo ? { repo } : {}), ...(spec ? { spec_id: spec.id, ...(spec.environment ? { spec_environment: spec.environment } : {}) } : {}) },
         });
-        return { id: res.data.data.id, created: true };
+        return { id: res.data.data.id, created: true, spec: spec ? { id: spec.id, environment: spec.environment ?? null } : undefined, specLinked: !!spec };
     }
     catch (err) {
         // Another job of the same pipeline created it between our lookup and our create.
         if (err instanceof ApiError && err.status === 409) {
             const raced = await find();
             if (raced)
-                return { id: raced, created: false };
+                return raced;
         }
         throw err;
     }
 }
+/**
+ * Bring the project's link to the catalog in line with what the CI says. Only what differs is written, so a pipeline that
+ * runs on every commit leaves the project untouched once it is linked. Pointing at another spec clears the environment
+ * unless one is given too (the API's rule: the old environment belonged to the old spec).
+ */
+async function syncSpecLink(conn, project, spec) {
+    const want = spec.environment ?? null;
+    if (project.specLinked)
+        return { id: spec.id, environment: want, changed: true, was: null };
+    let current = project.spec;
+    if (!current) {
+        const res = await request({ ...conn, method: "GET", path: `/api/v1/projects/${encodeURIComponent(project.id)}` });
+        const row = res.data.data;
+        current = { id: row.spec_id ?? null, environment: row.spec_environment ?? null };
+    }
+    const sameId = current.id === spec.id;
+    const patch = {};
+    if (!sameId)
+        patch.spec_id = spec.id;
+    if (spec.environment !== undefined && (!sameId || current.environment !== want))
+        patch.spec_environment = spec.environment;
+    if (Object.keys(patch).length === 0)
+        return { id: spec.id, environment: current.environment, changed: false, was: current.id };
+    await request({ ...conn, method: "PATCH", path: `/api/v1/projects/${encodeURIComponent(project.id)}`, body: patch });
+    return { id: spec.id, environment: spec.environment ?? (sameId ? current.environment : null), changed: true, was: current.id };
+}
 export async function uploadReport(p) {
-    const project = await ensureProject(p.conn, p.project, p.repo, p.createProject);
-    const res = await request({
-        ...p.conn,
-        method: "POST",
-        path: `/api/v1/projects/${encodeURIComponent(project.id)}/results`,
-        body: p.payload,
-    });
+    const project = p.projectId ? { id: p.projectId, created: false } : await ensureProject(p.conn, p.project, p.repo, p.createProject, p.spec);
+    let res;
+    try {
+        res = await request({
+            ...p.conn,
+            method: "POST",
+            path: `/api/v1/projects/${encodeURIComponent(project.id)}/results`,
+            body: p.payload,
+        });
+    }
+    catch (err) {
+        // A pinned id that is not found (or not yours) is a wrong id, not a project to create.
+        if (p.projectId && err instanceof ApiError && err.status === 404) {
+            throw new Error(`No project with id '${p.projectId}' (check --project-id / NB_ASSURANCE_PROJECT_ID, and --env).`);
+        }
+        throw err;
+    }
     const data = res.data.data;
-    return { project_id: project.id, project_created: project.created, ...data };
+    const done = { project_id: project.id, project_created: project.created, ...data };
+    if (p.spec) {
+        // The result is in; a link that fails now leaves it as it is and says so.
+        try {
+            done.spec = await syncSpecLink(p.conn, project, p.spec);
+        }
+        catch (err) {
+            const detail = err instanceof ApiError ? (err.data?.error?.message ?? err.message) : err.message;
+            throw new Error(`The result was reported, but the project could not be linked to the catalog: ${detail}`);
+        }
+    }
+    return done;
 }
 function fail(message) {
     throw new Error(message);
@@ -275,6 +369,40 @@ function resolveFormat(opts, file) {
         return "junit";
     return fail("Cannot tell the report format from the file name; pass --format junit|locust");
 }
+/** `--attach`: a file as it is, or a folder as a zip. Refuses before anything is sent: missing, empty, or too big for the server. */
+export function prepareAttachment(path, limit = MAX_ATTACHMENT_BYTES) {
+    if (!existsSync(path))
+        throw new Error(`--attach: not found: ${path}`);
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink())
+        throw new Error(`--attach: ${path} is a symbolic link; pass the real path`);
+    if (stat.isDirectory())
+        return { name: `${basename(path.replace(/[\\/]+$/, "")) || "report"}.zip`, bytes: zipDirectory(path, limit) };
+    if (!stat.isFile())
+        throw new Error(`--attach: ${path} is not a file or a folder`);
+    if (stat.size === 0)
+        throw new Error(`--attach: ${path} is empty`);
+    if (stat.size > limit)
+        throw new Error(`--attach: ${path} is ${(stat.size / 1048576).toFixed(1)} MiB, more than the ${limit / 1048576} MiB the server takes`);
+    return { name: basename(path), bytes: readFileSync(path) };
+}
+/** Keep the original report with a result that was just reported. A failure here leaves the result as it is. */
+export async function uploadAttachment(conn, ids, a) {
+    try {
+        await request({
+            ...conn,
+            method: "PUT",
+            path: `/api/v1/projects/${encodeURIComponent(ids.project_id)}/runs/${encodeURIComponent(ids.run_id)}/suites/${encodeURIComponent(ids.suite_id)}/attachment`,
+            query: { name: a.name },
+            rawBody: a.bytes,
+            contentType: a.name.endsWith(".zip") ? "application/zip" : "application/octet-stream",
+        });
+    }
+    catch (err) {
+        const detail = err instanceof ApiError ? (err.data?.error?.message ?? err.message) : err.message;
+        throw new Error(`The result was reported, but the attached report was not kept: ${detail}`);
+    }
+}
 export function buildReportUploadCommand() {
     return new Command("upload")
         .description("Report a test result file (JUnit XML or Locust CSV) to an Assurance project")
@@ -288,9 +416,19 @@ export function buildReportUploadCommand() {
         .option("--label <name>", "tells apart results that are otherwise the same, such as two scans of one tool on the same components (e.g. --label baseline, --label full-scan); part of the result's identity, so the same label again replaces the result; optional")
         .option("--tool-version <version>", "the version of the tool that produced the report (e.g. 9.1.0): informational, shown next to the tool, handy when a tool's new version changes its layout; optional")
         .option("--metric <key=value>", "an extra number for the suite, repeatable (e.g. --metric high=0 --metric medium=3; for security: critical, high, medium, low, info)", (v, all = []) => [...all, v])
-        .option("--api-version <label>", "the API version the result is for (e.g. v1, v2), part of the result's identity next to its kind and components; leave it out for results that hold for every version, such as unit tests")
+        .option("--api-version <label>", "the API version the result is for (e.g. v1, v2), part of the result's identity next to its kind and components; leave it out for results that hold for every version, such as unit tests. Default: the NB_API_VERSION environment variable (set it once per CI job or branch). A project can require a version for some kinds of result, and then refuses one without it")
         .option("--project <name>", "project name (CI: the repository); found, or created if missing")
+        .option("--attach <path>", "keep the tool's own report with the result: a file as it is, or a folder as a zip (up to 20 MiB). The server only stores it and offers it for download; nothing opens it. Nothing is attached unless you pass this, so check the report holds no secrets")
+        .option("--spec-id <id>", "tie the project to this API of the catalog (the spec's id in Assurance / Specs): set when it differs, so a pipeline that runs on every commit leaves it alone once it is linked. A new project is created already linked. The id is not looked up here")
+        .option("--spec-file <path>", "register this OpenAPI file in the API catalog first (a new spec, or a new version when its content changed; nothing is uploaded when it is already the latest) and tie the project to it: the whole chain in one command. Needs the catalog (Evolution) access of the account. Exclusive with --spec-id")
+        .option("--spec-name <name>", "with --spec-file: the spec's name in the catalog (default: the document's info.title)")
+        .option("--spec-group <name>", "with --spec-file: file a NEW spec in this group (made when missing); default none. An existing spec is never moved")
+        .option("--spec-org <id>", "with --spec-file: the organization whose catalog it is (an id), or 'personal' (default; or $NB_SPECS_ORG)")
+        .option("--spec-environment <name>", "which environment of that API the project covers (production, staging, ...); needs --spec-id")
+        .option("--project-id <id>", "send to this project by id (or $NB_ASSURANCE_PROJECT_ID): no lookup by name and nothing is created, so a rename never moves the results; recommended for a pipeline once the project exists")
         .option("--repo <repo>", "repository recorded on a newly created project (CI: detected)")
+        .option("--provider <provider>", `the CI provider: ${RUN_PROVIDERS.join(" | ")} (CI: detected)`)
+        .option("--report-path <path>", "the report file's path in the repository, relative to its root (default: detected, and only for a file committed at the reported commit)")
         .option("--run-key <key>", "identity of the pipeline run (CI: detected); all jobs of a run share it")
         .option("--commit <sha>", "commit SHA (CI: detected)")
         .option("--branch <name>", "branch (CI: detected)")
@@ -318,7 +456,9 @@ export function buildReportUploadCommand() {
         const maxFailRatio = Number(ratioRaw);
         if (!Number.isFinite(maxFailRatio) || maxFailRatio < 0 || maxFailRatio > 1)
             fail("--max-fail-ratio must be a number between 0 and 1");
-        const apiVersion = opts.apiVersion === undefined ? undefined : checkApiVersion(opts.apiVersion);
+        // The flag wins; NB_API_VERSION (a CI variable) is the default, and an empty one (a CI that declares it but does not set it) is none.
+        const versionRaw = opts.apiVersion ?? (process.env.NB_API_VERSION || undefined);
+        const apiVersion = versionRaw === undefined ? undefined : checkApiVersion(versionRaw);
         const parsed = parseReport({
             format,
             kind,
@@ -351,22 +491,44 @@ export function buildReportUploadCommand() {
         }
         const ci = detectCi(process.env);
         const runKey = opts.runKey ?? ci.runKey ?? fail("Cannot determine the run key; pass --run-key");
-        const project = opts.project ?? ci.project ?? fail("Cannot determine the project name; pass --project <name>");
+        const attachment = opts.attach !== undefined ? prepareAttachment(opts.attach) : undefined;
+        if (opts.specId !== undefined && opts.specFile !== undefined)
+            fail("--spec-id and --spec-file are exclusive: one names a spec of the catalog, the other registers a file");
+        if (opts.specEnvironment !== undefined && opts.specId === undefined && opts.specFile === undefined)
+            fail("--spec-environment needs --spec-id or --spec-file");
+        for (const [flag, value] of [["--spec-name", opts.specName], ["--spec-group", opts.specGroup], ["--spec-org", opts.specOrg]]) {
+            if (value !== undefined && opts.specFile === undefined)
+                fail(`${flag} needs --spec-file`);
+        }
+        const specEnvironment = opts.specEnvironment !== undefined ? checkSpecEnvironment(opts.specEnvironment) : undefined;
+        let spec = opts.specId !== undefined ? { id: checkSpecId(opts.specId), ...(specEnvironment !== undefined ? { environment: specEnvironment } : {}) } : undefined;
+        // The file is read and its name settled before anything is sent, so a bad path fails the command while nothing has happened yet.
+        const specText = opts.specFile !== undefined ? readSpecFile(opts.specFile) : undefined;
+        const specOrg = opts.specFile !== undefined ? checkOrg(opts.specOrg ?? process.env.NB_SPECS_ORG) : undefined;
+        const projectId = checkProjectId(opts.projectId ?? process.env.NB_ASSURANCE_PROJECT_ID);
+        const project = opts.project ?? ci.project ?? projectId ?? fail("Cannot determine the project name; pass --project <name> or --project-id <id>");
+        if (projectId && opts.project)
+            process.stderr.write("--project is ignored: --project-id decides where the result goes\n");
         const commit = opts.commit ?? ci.commitSha;
         const branch = opts.branch ?? ci.branch;
         const ciUrl = opts.ciUrl ?? ci.ciUrl;
+        const provider = opts.provider !== undefined ? checkProvider(opts.provider) : ci.provider === "local" ? undefined : ci.provider;
+        const reportPath = opts.reportPath !== undefined ? checkReportPath(opts.reportPath) : readReportPath(file, commit);
+        if (reportPath)
+            parsed.suite.report_path = reportPath;
         const payload = {
             run: {
                 key: runKey,
                 ...(commit ? { commit_sha: commit } : {}),
                 ...(branch ? { branch } : {}),
                 ...(ciUrl ? { ci_url: ciUrl } : {}),
+                ...(provider ? { provider } : {}),
             },
             suite: parsed.suite,
         };
         const repo = opts.repo ?? ci.repo;
         if (opts.dryRun) {
-            printJson({ project, repo, payload });
+            printJson({ project, ...(projectId ? { project_id: projectId } : {}), repo, payload, ...(spec ? { spec } : {}), ...(specText !== undefined && opts.specFile !== undefined ? { spec_file: { file: opts.specFile, name: specNameFor(specText, opts.specFile, opts.specName), content_hash: hashText(specText), ...(opts.specGroup ? { group: opts.specGroup } : {}) } } : {}), ...(attachment ? { attachment: { name: attachment.name, size_bytes: attachment.bytes.length } } : {}) });
             process.stderr.write(`(dry run) ${basename(dirname(file)) || "."}/${basename(file)}: ${parsed.note}\n`);
             return;
         }
@@ -374,15 +536,49 @@ export function buildReportUploadCommand() {
         const override = process.env.NB_BASE_URL?.replace(/\/$/, "");
         const baseUrl = override ?? resolveBaseUrl(loadSpec("assurance.yaml").servers, env);
         const token = opts.token || (await resolveAccessToken());
+        // The catalog comes first: the project is tied to the spec it returns. It must not cost the result: a failure here is
+        // kept, the result is reported without the link, and the command says so at the end.
+        let pushed;
+        let specError;
+        if (opts.specFile !== undefined && specOrg !== undefined) {
+            try {
+                pushed = await pushSpec({
+                    conn: { baseUrl: specsBaseUrl(env), token, org: specOrg },
+                    file: opts.specFile,
+                    name: opts.specName,
+                    group: opts.specGroup,
+                    note: ciNote(ci, commit),
+                });
+                spec = { id: pushed.id, ...(specEnvironment !== undefined ? { environment: specEnvironment } : {}) };
+            }
+            catch (err) {
+                specError = err;
+            }
+        }
         const result = await uploadReport({
             conn: { baseUrl, token },
             project,
+            projectId,
             repo,
             createProject: opts.createProject,
             payload,
+            spec,
         });
-        printJson(result);
-        process.stderr.write(`✓ ${kind}/${checkedTool} ${payload.suite.status}: ${parsed.note} -> project '${project}'` +
-            `${result.project_created ? " (created)" : ""}, run '${runKey}'${result.replaced ? " (replaced)" : ""}\n`);
+        if (attachment)
+            await uploadAttachment({ baseUrl, token }, result, attachment);
+        printJson({ ...result, ...(attachment ? { attachment: { name: attachment.name, size_bytes: attachment.bytes.length } } : {}), ...(pushed ? { catalog: pushed } : {}) });
+        exportGithubOutput("project_id", result.project_id);
+        if (pushed)
+            exportGithubOutput("spec_id", pushed.id);
+        process.stderr.write(`✓ ${kind}/${checkedTool} ${payload.suite.status}: ${parsed.note} -> project '${project}' (id ${result.project_id})` +
+            `${result.project_created ? " (created)" : ""}, run '${runKey}'${result.replaced ? " (replaced)" : ""}` +
+            `${attachment ? `, attached ${attachment.name} (${(attachment.bytes.length / 1024).toFixed(0)} KiB)` : ""}` +
+            `${pushed ? `, spec ${pushed.name} v${pushed.version} (${pushed.action.replace("_", " ")})` : ""}` +
+            `${result.spec ? `, catalog ${result.spec.id}${result.spec.environment ? ` (${result.spec.environment})` : ""} ${result.spec.changed ? (result.spec.was ? `(changed from ${result.spec.was})` : "(linked)") : "(already linked)"}` : ""}\n`);
+        if (!projectId) {
+            process.stderr.write(`  Pin it so a rename or a typo cannot send results elsewhere: --project-id ${result.project_id} (or NB_ASSURANCE_PROJECT_ID=${result.project_id})\n`);
+        }
+        if (specError)
+            throw new Error(`The result was reported, but the spec could not be registered in the catalog (the project is not tied to it): ${specError.message}`);
     });
 }