@nasebanal/cli 0.6.0 → 0.8.0

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/package.json

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