@nasebanal/cli 0.5.0 → 0.7.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.
@@ -117,6 +187,20 @@ needed for a registry install.
 > `api-specs-*` packages), it captures this package too. Install with
 > `npm install -g @nasebanal/cli --@nasebanal:registry=https://registry.npmjs.org/`.
 
+### Upgrading
+
+```bash
+nb upgrade           # install the latest published version
+nb upgrade --check   # only report whether a newer version exists
+```
+
+When a newer version is out, interactive runs print a one-line notice on stderr
+(`Update available: 0.5.0 -> 0.6.0`). The registry is checked at most once a day
+and the result is cached in `~/.config/nasebanal/update-check.json`. Nothing is
+printed when stderr is not a terminal or `CI` is set; `NB_NO_UPDATE_NOTIFIER=1`
+turns the notice off. A dev link to a source checkout is never overwritten:
+`nb upgrade` tells you to `git pull && npm run build` instead.
+
 ### Versioning and releases
 
 Versions follow SemVer (0.x until 1.0: breaking changes bump the minor). Each
@@ -190,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
@@ -345,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/config.js

@@ -12,7 +12,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { mkdirSync, readFileSync, writeFileSync, chmodSync, existsSync } from "node:fs";
 import { refreshTokens } from "./oauth.js";
-function configDir() {
+export function configDir() {
     const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
     return join(base, "nasebanal");
 }

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,8 @@ 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.
 const { version } = createRequire(import.meta.url)("../package.json");
@@ -26,6 +28,8 @@ program
     .option("--token <token>", "override the stored PAT for this invocation")
     .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
@@ -50,8 +54,10 @@ for (const api of API_CATALOG) {
     program.addCommand(group);
 }
 async function main() {
+    const notifier = startUpdateNotifier(version, process.argv);
     try {
         await program.parseAsync(process.argv);
+        await notifier.refresh();
     }
     catch (err) {
         printError(err);

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}`);
     });
 }

package/dist/reports/zip.js

@@ -0,0 +1,128 @@
+/**
+ * A minimal zip writer for `--attach <folder>`: regular files only, deflate, no dependency.
+ *
+ * What it will not do is as deliberate as what it does: a symbolic link is never followed (a report folder must
+ * not smuggle in a file from elsewhere), nothing is stored under a name that climbs out of the folder, and the
+ * size and file count are checked BEFORE anything is read, so a huge folder fails fast instead of eating memory.
+ * The server never unzips what it receives, so these are the only checks on the way in.
+ */
+import { lstatSync, readdirSync, readFileSync } from "node:fs";
+import { join, posix, sep } from "node:path";
+import { deflateRawSync } from "node:zlib";
+export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+export const MAX_ATTACHMENT_FILES = 2000;
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+export function crc32(data) {
+    let c = 0xffffffff;
+    for (let i = 0; i < data.length; i++)
+        c = CRC_TABLE[(c ^ data[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+/** MS-DOS date and time, which is what a zip entry carries (2-second resolution, from 1980). */
+function dosDateTime(d) {
+    const year = Math.max(d.getFullYear(), 1980);
+    return {
+        date: ((year - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate(),
+        time: (d.getHours() << 11) | (d.getMinutes() << 5) | (d.getSeconds() >> 1),
+    };
+}
+/** Every regular file under `dir`, as `{ name, abs, size, mtime }`, in a stable order. Links and special files are skipped. */
+export function listFiles(dir) {
+    const out = [];
+    const walk = (abs, rel) => {
+        for (const entry of readdirSync(abs).sort()) {
+            const full = join(abs, entry);
+            const stat = lstatSync(full);
+            if (stat.isSymbolicLink())
+                continue;
+            if (stat.isDirectory())
+                walk(full, [...rel, entry]);
+            else if (stat.isFile())
+                out.push({ name: [...rel, entry].join(posix.sep), abs: full, size: stat.size, mtime: stat.mtime });
+            if (out.length > MAX_ATTACHMENT_FILES)
+                throw new Error(`--attach: more than ${MAX_ATTACHMENT_FILES} files in the folder`);
+        }
+    };
+    walk(dir, []);
+    return out;
+}
+export function buildZip(entries) {
+    const parts = [];
+    const central = [];
+    let offset = 0;
+    for (const e of entries) {
+        if (e.name === "" || e.name.startsWith("/") || e.name.includes("\\") || e.name.split("/").some((s) => s === ".." || s === "")) {
+            throw new Error(`--attach: refusing the path '${e.name}'`);
+        }
+        const name = Buffer.from(e.name, "utf8");
+        const raw = Buffer.from(e.data.buffer, e.data.byteOffset, e.data.byteLength);
+        const packed = deflateRawSync(raw);
+        // Store as is when deflate does not help (already-compressed images and the like).
+        const useDeflate = packed.length < raw.length;
+        const body = useDeflate ? packed : raw;
+        const method = useDeflate ? 8 : 0;
+        const crc = crc32(raw);
+        const { date, time } = dosDateTime(e.mtime);
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(0x04034b50, 0);
+        local.writeUInt16LE(20, 4); // version needed
+        local.writeUInt16LE(0x0800, 6); // flag: names are UTF-8
+        local.writeUInt16LE(method, 8);
+        local.writeUInt16LE(time, 10);
+        local.writeUInt16LE(date, 12);
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(body.length, 18);
+        local.writeUInt32LE(raw.length, 22);
+        local.writeUInt16LE(name.length, 26);
+        local.writeUInt16LE(0, 28); // extra length
+        parts.push(local, name, body);
+        const dir = Buffer.alloc(46);
+        dir.writeUInt32LE(0x02014b50, 0);
+        dir.writeUInt16LE(20, 4); // version made by
+        dir.writeUInt16LE(20, 6); // version needed
+        dir.writeUInt16LE(0x0800, 8);
+        dir.writeUInt16LE(method, 10);
+        dir.writeUInt16LE(time, 12);
+        dir.writeUInt16LE(date, 14);
+        dir.writeUInt32LE(crc, 16);
+        dir.writeUInt32LE(body.length, 20);
+        dir.writeUInt32LE(raw.length, 24);
+        dir.writeUInt16LE(name.length, 28);
+        dir.writeUInt32LE(offset, 42);
+        central.push(dir, name);
+        offset += local.length + name.length + body.length;
+    }
+    const centralBytes = Buffer.concat(central);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(centralBytes.length, 12);
+    end.writeUInt32LE(offset, 16);
+    return Buffer.concat([...parts, centralBytes, end]);
+}
+/** A folder as a zip, or a refusal: too many files, or more than the server takes. */
+export function zipDirectory(dir, limit = MAX_ATTACHMENT_BYTES) {
+    const files = listFiles(dir);
+    if (files.length === 0)
+        throw new Error(`--attach: no files in ${dir}`);
+    // Before reading anything: a folder this much bigger than the limit cannot shrink to it (deflate rarely does better than 10:1 on reports).
+    const total = files.reduce((n, f) => n + f.size, 0);
+    if (total > limit * 20)
+        throw new Error(`--attach: ${dir} is ${Math.round(total / 1048576)} MiB; attach only the report (at most ${limit / 1048576} MiB zipped)`);
+    const zip = buildZip(files.map((f) => ({ name: f.name, data: readFileSync(f.abs), mtime: f.mtime })));
+    if (zip.length > limit)
+        throw new Error(`--attach: the zip of ${dir} is ${(zip.length / 1048576).toFixed(1)} MiB, more than the ${limit / 1048576} MiB the server takes`);
+    return zip;
+}
+/** The platform's separator never reaches the zip. */
+export const toPosix = (p) => p.split(sep).join(posix.sep);

package/dist/specs/command.js

@@ -0,0 +1,44 @@
+/**
+ * `nb specs` - the API catalog (your own OpenAPI documents) from the command line. Hand-written: the CLI's generated
+ * command tree comes from the pinned contracts, and the catalog's is not among them.
+ */
+import { Command } from "commander";
+import { resolveAccessToken, resolveEnv } from "../config.js";
+import { exportGithubOutput, printJson } from "../output.js";
+import { detectCi } from "../reports/ci.js";
+import { checkOrg, ciNote, pushSpec, specsBaseUrl } from "./push.js";
+export function buildPushCommand() {
+    return new Command("push")
+        .description("Register an OpenAPI file in the API catalog: a new spec, or a new version when its content changed. Safe to run on every commit: a file that is already the latest version uploads nothing")
+        .requiredOption("--file <path>", "the OpenAPI document (YAML or JSON, up to 2 MiB)")
+        .option("--name <name>", "the spec's name in the catalog (default: the document's info.title, then the file's name)")
+        .option("--id <id>", "push to this spec by id: a rename cannot make a second one")
+        .option("--group <name>", "file a NEW spec in this group (made when missing); default none. An existing spec is never moved by a push")
+        .option("--description <text>", "a new spec's description")
+        .option("--note <text>", "what changed, shown in the version list (default: the commit, branch and CI run)")
+        .option("--org <id>", "the organization whose catalog it is (an id), or 'personal' (default; or $NB_SPECS_ORG)")
+        .option("--dry-run", "read the catalog and say what would happen; write nothing")
+        .action(async (_flags, command) => {
+        const opts = command.optsWithGlobals();
+        const env = opts.env || resolveEnv();
+        const token = opts.token || (await resolveAccessToken());
+        const ci = detectCi(process.env);
+        const result = await pushSpec({
+            conn: { baseUrl: specsBaseUrl(env), token, org: checkOrg(opts.org ?? process.env.NB_SPECS_ORG) },
+            file: opts.file,
+            name: opts.name,
+            group: opts.group,
+            description: opts.description,
+            note: opts.note ?? ciNote(ci, undefined),
+            id: opts.id,
+            dryRun: opts.dryRun,
+        });
+        printJson(result);
+        exportGithubOutput("spec_id", result.id);
+        const what = { created: "created (v1)", new_version: `new version v${result.version}`, unchanged: `unchanged (already v${result.version}: nothing uploaded)` }[result.action];
+        process.stderr.write(`${opts.dryRun ? "(dry run) " : ""}✓ ${result.name} -> ${what}\n`);
+    });
+}
+export function buildSpecsCommand() {
+    return new Command("specs").description("The API catalog: your own OpenAPI documents (NASEBANAL Evolution)").addCommand(buildPushCommand());
+}

package/dist/specs/push.js

@@ -0,0 +1,188 @@
+/**
+ * `nb specs push` - register an OpenAPI document in the API catalog (nb-specs-api) from a file, the way a pipeline
+ * wants it: no group has to exist, nothing is uploaded when the file is already the latest version, and running it on
+ * every commit is safe.
+ *
+ *   - the spec is found by name (or by `--id`); new -> created with its first version, known -> a new version
+ *   - the document's SHA-256 is compared with the latest version's `content_hash` BEFORE anything is sent: the same
+ *     bytes mean "unchanged", and the 2 MiB stay where they are. (The server refuses an identical upload with
+ *     409 UNCHANGED too; that is treated as "unchanged", for two jobs racing.)
+ *   - a group is optional: `--group <name>` files a NEW spec in that group (made when missing); a spec that already
+ *     exists is never moved by a push (moving is the catalog's job).
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, extname } from "node:path";
+import { parse } from "yaml";
+import { ApiError, request } from "../http.js";
+import { envTokenHint } from "../output.js";
+/** The catalog takes documents up to this size (2 MiB); the CLI refuses a larger one before sending anything. */
+export const MAX_SPEC_BYTES = 2 * 1024 * 1024;
+const MAX_NOTE = 500;
+/** The catalog's host for the active environment (`NB_SPECS_BASE_URL` overrides; the CLI ships no spec for this API). */
+export function specsBaseUrl(env) {
+    const override = process.env.NB_SPECS_BASE_URL?.replace(/\/$/, "");
+    if (override)
+        return override;
+    return env === "local" ? "http://localhost:8792" : "https://api.specs.nasebanal.com";
+}
+/** `--org` / `NB_SPECS_ORG`: `personal`, or an organization's numeric id. Unset or empty (a CI variable left blank) is `personal`. */
+export function checkOrg(raw) {
+    const v = raw?.trim() || "personal";
+    if (v === "personal" || /^[1-9]\d{0,17}$/.test(v))
+        return v;
+    throw new Error(`--org '${raw}' must be 'personal' or an organization id (a number)`);
+}
+/** SHA-256 (hex) of the document as text - what the catalog stores as `content_hash`. */
+export function hashText(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+/** What a pipeline says about a version it pushes: the commit, the branch and the CI run, so "which commit made v7" has an answer. */
+export function ciNote(ci, commit) {
+    const sha = (commit ?? ci.commitSha)?.slice(0, 7);
+    const parts = [ci.repo && sha ? `${ci.repo}@${sha}` : (sha ?? ci.repo), ci.branch ? `(${ci.branch})` : null, ci.ciUrl].filter((p) => !!p);
+    return parts.length > 0 ? parts.join(" ").slice(0, MAX_NOTE) : undefined;
+}
+export function readSpecFile(file) {
+    if (!existsSync(file))
+        throw new Error(`--file: not found: ${file}`);
+    const stat = statSync(file);
+    if (!stat.isFile())
+        throw new Error(`--file: ${file} is not a file`);
+    if (stat.size === 0)
+        throw new Error(`--file: ${file} is empty`);
+    if (stat.size > MAX_SPEC_BYTES)
+        throw new Error(`--file: ${file} is ${(stat.size / 1048576).toFixed(1)} MiB, more than the ${MAX_SPEC_BYTES / 1048576} MiB the catalog takes`);
+    return readFileSync(file, "utf8");
+}
+/** `info.title` of the document, or null (not parseable, or no title): the server decides whether it is a valid OpenAPI. */
+export function titleOf(text) {
+    try {
+        const doc = parse(text);
+        const title = doc?.info?.title;
+        return typeof title === "string" && title.trim() !== "" ? title.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The name a spec is registered under: asked for, else its title, else its file's name. At most 100 characters. */
+export function specNameFor(text, file, asked) {
+    const name = (asked ?? titleOf(text) ?? basename(file, extname(file))).trim();
+    if (name === "")
+        throw new Error("The spec has no name: pass --name");
+    return name.slice(0, 100);
+}
+function headersOf(conn) {
+    return { baseUrl: conn.baseUrl, token: conn.token, headers: { "X-Active-Organization-Id": conn.org } };
+}
+function reasonOf(err) {
+    if (err instanceof ApiError)
+        return err.data?.error?.message ?? err.message;
+    return err.message;
+}
+const codeOf = (err) => (err instanceof ApiError ? err.data?.error?.code : undefined);
+async function findSpec(conn, name, id) {
+    if (id) {
+        try {
+            const res = await request({ ...headersOf(conn), method: "GET", path: `/api/v1/specs/${encodeURIComponent(id)}` });
+            return res.data.data;
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.status === 404)
+                throw new Error(`No spec with id '${id}' in the catalog (check --id, and --org: the catalog is per owner).`);
+            throw err;
+        }
+    }
+    const res = await request({ ...headersOf(conn), method: "GET", path: "/api/v1/specs" });
+    const list = res.data.data.data;
+    return list.find((s) => s.name.toLowerCase() === name.toLowerCase()) ?? null;
+}
+/** The id of the owner's group of that name, made when there is none. Refuses (with the catalog's reason) at the limit. */
+async function groupIdFor(conn, name, create) {
+    const res = await request({ ...headersOf(conn), method: "GET", path: "/api/v1/groups" });
+    const groups = res.data.data.data;
+    const hit = groups.find((g) => g.name.toLowerCase() === name.toLowerCase());
+    if (hit)
+        return hit.id;
+    if (!create)
+        return null;
+    const made = await request({ ...headersOf(conn), method: "POST", path: "/api/v1/groups", body: { name } });
+    return made.data.data.id;
+}
+/**
+ * Push a file to the catalog. Whatever the catalog refuses - at the first read as much as at a write (a plan without the
+ * catalog is a 403 on the very first call) - comes back with the catalog's own reason, not a bare "403 Forbidden".
+ */
+export async function pushSpec(p) {
+    try {
+        return await pushSpecInner(p);
+    }
+    catch (err) {
+        if (err instanceof ApiError) {
+            const hint = err.status === 401 ? envTokenHint() : null;
+            throw new Error(`The catalog refused the request: ${reasonOf(err)}${hint ? `\n${hint}` : ""}`);
+        }
+        throw err;
+    }
+}
+async function pushSpecInner(p) {
+    const text = readSpecFile(p.file);
+    const hash = hashText(text);
+    const name = specNameFor(text, p.file, p.name);
+    const note = p.note !== undefined ? p.note.trim().slice(0, MAX_NOTE) || undefined : undefined;
+    const existing = await findSpec(p.conn, name, p.id);
+    if (existing) {
+        // Nothing to upload when the file is already the latest version: the hash settles it without sending the document.
+        const versions = await request({ ...headersOf(p.conn), method: "GET", path: `/api/v1/specs/${encodeURIComponent(existing.id)}/versions` });
+        const latest = versions.data.data.data[0];
+        if (latest?.content_hash === hash) {
+            return { id: existing.id, name: existing.name, version: latest.version, group_id: existing.group_id, action: "unchanged", content_hash: hash };
+        }
+        if (p.dryRun)
+            return { id: existing.id, name: existing.name, version: existing.latest_version + 1, group_id: existing.group_id, action: "new_version", content_hash: hash };
+        try {
+            const res = await request({
+                ...headersOf(p.conn),
+                method: "POST",
+                path: `/api/v1/specs/${encodeURIComponent(existing.id)}/versions`,
+                body: { content: text, ...(note ? { note } : {}) },
+            });
+            const version = res.data.data.version;
+            return { id: existing.id, name: existing.name, version, group_id: existing.group_id, action: "new_version", content_hash: hash };
+        }
+        catch (err) {
+            // Another job pushed the same document between our comparison and our upload: the catalog says so, and that is the goal.
+            if (codeOf(err) === "UNCHANGED")
+                return { id: existing.id, name: existing.name, version: existing.latest_version, group_id: existing.group_id, action: "unchanged", content_hash: hash };
+            throw new Error(`The catalog refused the new version: ${reasonOf(err)}`);
+        }
+    }
+    // A new spec. The group is by name and made on the way; none asked = in no group.
+    if (p.dryRun) {
+        const gid = p.group ? await groupIdFor(p.conn, p.group, false) : null;
+        return { id: "(new)", name, version: 1, group_id: gid, action: "created", content_hash: hash };
+    }
+    let groupId = null;
+    try {
+        if (p.group)
+            groupId = await groupIdFor(p.conn, p.group, true);
+        const res = await request({
+            ...headersOf(p.conn),
+            method: "POST",
+            path: "/api/v1/specs",
+            body: { name, content: text, ...(groupId ? { group_id: groupId } : {}), ...(p.description ? { description: p.description } : {}) },
+        });
+        const created = res.data.data;
+        return { id: created.id, name: created.name, version: 1, group_id: created.group_id ?? null, action: "created", content_hash: hash };
+    }
+    catch (err) {
+        if (codeOf(err) === "NAME_TAKEN") {
+            // Two jobs creating the same spec: the loser pushes to the winner's.
+            const raced = await findSpec(p.conn, name);
+            if (raced)
+                return pushSpecInner({ ...p, id: raced.id });
+        }
+        throw new Error(`The catalog refused the spec: ${reasonOf(err)}`);
+    }
+}

package/dist/update.js

@@ -0,0 +1,127 @@
+/**
+ * Self-update: a passive "new version available" notice and `nb upgrade`.
+ *
+ * Follows the usual CLI convention (npm, gh, gcloud): the notice is a single
+ * line on stderr, shown at most once a day from a cached registry lookup, and
+ * silent for non-interactive use (pipes, CI) so scripted output never changes.
+ * `NB_NO_UPDATE_NOTIFIER=1` turns it off.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { Command } from "commander";
+import { configDir } from "./config.js";
+const PACKAGE = "@nasebanal/cli";
+const REGISTRY = "https://registry.npmjs.org";
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 1500;
+/** 1 if a > b, -1 if a < b, 0 if equal (plain `x.y.z`; pre-release tags are ignored). */
+export function compareVersions(a, b) {
+    const pa = a.split("-")[0].split(".").map(Number);
+    const pb = b.split("-")[0].split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        const d = (pa[i] || 0) - (pb[i] || 0);
+        if (d !== 0)
+            return d > 0 ? 1 : -1;
+    }
+    return 0;
+}
+function cachePath() {
+    return join(configDir(), "update-check.json");
+}
+function readCache() {
+    try {
+        return JSON.parse(readFileSync(cachePath(), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeCache(cache) {
+    try {
+        mkdirSync(configDir(), { recursive: true });
+        writeFileSync(cachePath(), JSON.stringify(cache) + "\n");
+    }
+    catch {
+        /* best effort */
+    }
+}
+/** Latest published version. Goes to the public registry directly, so a `~/.npmrc` scope mapping cannot hide it. */
+export async function fetchLatest(timeoutMs = FETCH_TIMEOUT_MS) {
+    try {
+        const res = await fetch(`${REGISTRY}/${PACKAGE.replace("/", "%2F")}/latest`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return undefined;
+        return (await res.json()).version;
+    }
+    catch {
+        return undefined;
+    }
+}
+function notifierEnabled() {
+    return !process.env.NB_NO_UPDATE_NOTIFIER && !process.env.CI && !!process.stderr.isTTY;
+}
+/**
+ * Arrange for the update notice to print when the process exits. Reads the
+ * cache synchronously; when it is older than a day, refreshes it afterwards
+ * (bounded by a short timeout) so the notice appears from the next run on.
+ */
+export function startUpdateNotifier(current, argv) {
+    const noop = { refresh: async () => { } };
+    if (!notifierEnabled() || argv.slice(2).some((a) => a === "upgrade" || a === "--version" || a === "-V"))
+        return noop;
+    const cache = readCache();
+    if (cache?.latest && compareVersions(cache.latest, current) > 0) {
+        const latest = cache.latest;
+        process.on("exit", () => {
+            process.stderr.write(`\nUpdate available: ${current} -> ${latest}. Run \`nb upgrade\` to install it.\n`);
+        });
+    }
+    const stale = !cache || Date.now() - cache.checkedAt > CHECK_INTERVAL_MS;
+    return {
+        refresh: async () => {
+            if (!stale)
+                return;
+            const latest = await fetchLatest();
+            // Record the attempt even on failure so an offline machine is not retried on every command.
+            writeCache({ checkedAt: Date.now(), latest: latest ?? cache?.latest });
+        },
+    };
+}
+/** True when `nb` is a dev link to a checkout rather than an npm-installed copy. */
+function isLinkedCheckout() {
+    try {
+        return !realpathSync(process.argv[1]).includes("node_modules");
+    }
+    catch {
+        return false;
+    }
+}
+export function buildUpgradeCommand(current) {
+    return new Command("upgrade")
+        .description("Upgrade nb to the latest published version")
+        .option("--check", "only report whether a newer version exists")
+        .action(async (opts) => {
+        const latest = await fetchLatest(5000);
+        if (!latest)
+            throw new Error("Could not reach the npm registry to look up the latest version.");
+        writeCache({ checkedAt: Date.now(), latest });
+        if (compareVersions(latest, current) <= 0) {
+            process.stdout.write(`nb ${current} is up to date.\n`);
+            return;
+        }
+        process.stdout.write(`Update available: ${current} -> ${latest}\n`);
+        if (opts.check)
+            return;
+        if (isLinkedCheckout()) {
+            process.stdout.write("This nb is linked to a source checkout: `git pull && npm run build` there instead.\n");
+            return;
+        }
+        const r = spawnSync("npm", ["install", "-g", `${PACKAGE}@${latest}`, `--@nasebanal:registry=${REGISTRY}/`], { stdio: "inherit" });
+        if (r.status !== 0) {
+            throw new Error(`npm install failed. Run it yourself: npm install -g ${PACKAGE}@latest --@nasebanal:registry=${REGISTRY}/`);
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nasebanal/cli",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "gcloud-style command-line interface for NASEBANAL APIs, generated from nb-api-specs OpenAPI contracts.",
   "license": "MIT",
   "type": "module",