@nasebanal/cli 0.3.0 → 0.5.0

package/README.md

@@ -10,7 +10,7 @@ Contract-Driven Development (CDD) pipeline, alongside the web frontends.
 
 ```console
 $ nb account me get
-$ nb recorder records list
+$ nb record records list
 $ nb target shares accept <id>
 $ nb account me tokens create --data '{"name":"ci"}'
 ```
@@ -45,7 +45,17 @@ export NB_TOKEN=nbpat_…        # a PAT or service-account token (no browser ne
 
 # JUnit XML: vitest (--reporter=junit), pytest (--junitxml), Specmatic, Playwright (--reporter=junit)
 nb assurance report upload --file report/junit.xml --kind unit --tool pytest
-nb assurance report upload --file results/junit.xml --kind e2e --tool playwright --suite web
+nb assurance report upload --file results/junit.xml --kind e2e --tool playwright --component web
+
+# Two scans of one tool on the same components (ZAP's baseline and full scan): a label tells them apart
+nb assurance report upload --file report/baseline-junit.xml --kind security --tool zap --component frontend --label baseline
+nb assurance report upload --file report/full-scan-junit.xml --kind security --tool zap --component frontend --label full-scan
+
+# The tool's own version is informational and optional
+nb assurance report upload --file report/junit.xml --kind unit --tool pytest --tool-version 9.1.0
+
+# A result may be about several components: repeat the flag (new names are created in the project; none = `default`)
+nb assurance report upload --file results/junit.xml --kind e2e --tool playwright --component frontend --component backend
 
 # Specmatic: the JUnit XML, plus its HTML report for the API coverage (coverage_pct = operations exercised / operations in the spec)
 nb assurance report upload --file specmatic/junit/TEST-junit-jupiter.xml --kind contract --tool specmatic \

package/dist/apis.js

@@ -1,7 +1,6 @@
 export const API_CATALOG = [
     { name: "account", spec: "account.yaml", summary: "User profiles, subscriptions, billing, and API tokens" },
-    { name: "recorder", spec: "recorder.yaml", summary: "Records and tags (NASEBANAL Recorder)" },
+    { name: "record", spec: "recorder.yaml", summary: "Records and tags (NASEBANAL Recorder)" },
     { name: "target", spec: "target.yaml", summary: "Targets, cells, and shares (NASEBANAL Target)" },
     { name: "assurance", spec: "assurance.yaml", summary: "Monitors, projects and CI/CD test results (NASEBANAL Assurance)" },
-    { name: "app-template", spec: "app-template.yaml", summary: "Reference API surface (App Template)" },
 ];

package/dist/reports/locust.js

@@ -7,6 +7,20 @@
  * task exception, or a failure ratio above the allowed one, fails the run.
  */
 import { toRecords } from "./csv.js";
+/**
+ * The CSV's column names changed between Locust versions: 1.x wrote "# requests" / "# failures" / "Median response
+ * time" (and named the aggregate row "Total"), 2.x writes "Request Count" / "Failure Count" / "Median Response Time"
+ * ("Aggregated"). Each value is read under every name it has had, the first present one winning.
+ */
+const COLUMNS = {
+    requests: ["Request Count", "# requests"],
+    failures: ["Failure Count", "# failures"],
+    median: ["Median Response Time", "Median response time"],
+    average: ["Average Response Time", "Average response time"],
+    max: ["Max Response Time", "Max response time"],
+};
+const has = (row, names) => names.some((n) => n in row);
+const read = (row, names) => num(row[names.find((n) => n in row) ?? ""]);
 function num(value) {
     if (value === undefined || value === "" || value === "N/A")
         return null;
@@ -16,21 +30,26 @@ function num(value) {
 const round = (n, digits = 2) => Math.round(n * 10 ** digits) / 10 ** digits;
 export function summariseLocust(files, maxFailRatio) {
     const stats = toRecords(files.stats);
-    const total = stats.find((r) => r.Name === "Aggregated");
+    // The row of all requests together: "Aggregated" (2.x) or "Total" (1.x).
+    const total = stats.find((r) => r.Name === "Aggregated" || r.Name === "Total");
     if (!total)
-        throw new Error('No "Aggregated" row in the stats CSV - is this a Locust *_stats.csv file?');
-    const requests = num(total["Request Count"]) ?? 0;
-    const failed = num(total["Failure Count"]) ?? 0;
+        throw new Error('No "Aggregated" (or "Total") row in the stats CSV - is this a Locust *_stats.csv file?');
+    // Without the counts the numbers below would silently be 0, a green result for a report nobody understood: refuse it.
+    if (!has(total, COLUMNS.requests) || !has(total, COLUMNS.failures)) {
+        throw new Error(`The stats CSV has no request / failure count column (looked for ${[...COLUMNS.requests, ...COLUMNS.failures].map((n) => `"${n}"`).join(", ")}; found: ${Object.keys(total).join(", ")}) - is it from a Locust version this nb does not know?`);
+    }
+    const requests = read(total, COLUMNS.requests) ?? 0;
+    const failed = read(total, COLUMNS.failures) ?? 0;
     const metrics = { requests, failures: failed };
     const put = (key, value) => {
         if (value !== null)
             metrics[key] = round(value);
     };
-    put("avg_ms", num(total["Average Response Time"]));
-    put("p50_ms", num(total["50%"]) ?? num(total["Median Response Time"]));
+    put("avg_ms", read(total, COLUMNS.average));
+    put("p50_ms", num(total["50%"]) ?? read(total, COLUMNS.median));
     put("p95_ms", num(total["95%"]));
     put("p99_ms", num(total["99%"]));
-    put("max_ms", num(total["Max Response Time"]));
+    put("max_ms", read(total, COLUMNS.max));
     put("rps", num(total["Requests/s"]));
     const ratio = requests > 0 ? failed / requests : 0;
     metrics.error_rate_pct = round(ratio * 100);

package/dist/reports/upload.js

@@ -127,7 +127,13 @@ function locustSibling(statsFile, suffix) {
 }
 export function parseReport(opts) {
     const text = readFileSync(opts.file, "utf8");
-    const base = { kind: opts.kind, tool: opts.tool, ...(opts.suiteName ? { name: opts.suiteName } : {}) };
+    const base = {
+        kind: opts.kind,
+        tool: opts.tool,
+        ...(opts.components && opts.components.length > 0 ? { components: opts.components } : {}),
+        ...(opts.label ? { label: opts.label } : {}),
+        ...(opts.toolVersion ? { tool_version: opts.toolVersion } : {}),
+    };
     if (opts.format === "junit") {
         const j = parseJunit(text);
         const status = opts.status ?? (j.failed === 0 ? "passed" : "failed");
@@ -214,6 +220,49 @@ function statsFileIn(dir) {
         fail(`No *_stats.csv file in ${dir}`);
     return join(dir, files.sort()[files.length - 1]);
 }
+/** At most this many components per result (the API's limit) and this many characters in a name. */
+const MAX_COMPONENTS = 20;
+const MAX_COMPONENT_LENGTH = 100;
+/** The `--label`: trimmed, not empty, within the API's limit. */
+function checkLabel(raw) {
+    if (raw === undefined)
+        return undefined;
+    const label = raw.trim();
+    if (label === "")
+        fail("--label must not be empty");
+    if (label.length > MAX_COMPONENT_LENGTH)
+        fail(`--label must be ${MAX_COMPONENT_LENGTH} characters or fewer`);
+    return label;
+}
+/** The `--tool-version`: trimmed, not empty, within the API's limit. */
+function checkToolVersion(raw) {
+    if (raw === undefined)
+        return undefined;
+    const version = raw.trim();
+    if (version === "")
+        fail("--tool-version must not be empty");
+    if (version.length > 50)
+        fail("--tool-version must be 50 characters or fewer");
+    return version;
+}
+/** The `--component` names: trimmed, no empty one, no two alike ignoring case, within the API's limits. */
+function checkComponents(raw) {
+    if (raw === undefined)
+        return undefined;
+    const out = [];
+    for (const value of raw) {
+        const name = value.trim();
+        if (name === "")
+            fail("--component must not be empty");
+        if (name.length > MAX_COMPONENT_LENGTH)
+            fail(`--component must be ${MAX_COMPONENT_LENGTH} characters or fewer: ${name.slice(0, 20)}…`);
+        if (!out.some((o) => o.toLowerCase() === name.toLowerCase()))
+            out.push(name);
+    }
+    if (out.length > MAX_COMPONENTS)
+        fail(`At most ${MAX_COMPONENTS} --component values`);
+    return out;
+}
 function resolveFormat(opts, file) {
     if (opts.format !== undefined) {
         if (opts.format !== "junit" && opts.format !== "locust")
@@ -235,9 +284,11 @@ export function buildReportUploadCommand() {
         .option("--format <format>", "junit | locust (default: from the file name)")
         .option("--kind <kind>", `what the suite proves: ${SUITE_KINDS.join(" | ")} (locust: load)`)
         .option("--tool <label>", "the producing tool, a free label, e.g. vitest, pytest, playwright, specmatic, zap, trivy (locust: locust)")
-        .option("--suite <name>", "tells apart several suites of one kind in a run (e.g. api, web)")
+        .option("--component <name>", "a component the result is for (e.g. frontend, backend), repeatable when it covers several (e.g. an end-to-end test: --component frontend --component backend); new names are created in the project; leave it out for the component `default`", (v, all = []) => [...all, v])
+        .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 suite's identity next to its kind and name; 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")
         .option("--project <name>", "project name (CI: the repository); found, or created if missing")
         .option("--repo <repo>", "repository recorded on a newly created project (CI: detected)")
         .option("--run-key <key>", "identity of the pipeline run (CI: detected); all jobs of a run share it")
@@ -272,7 +323,9 @@ export function buildReportUploadCommand() {
             format,
             kind,
             tool: checkedTool,
-            suiteName: opts.suite,
+            components: checkComponents(opts.component),
+            label: checkLabel(opts.label),
+            toolVersion: checkToolVersion(opts.toolVersion),
             status: opts.status,
             maxFailRatio,
             file,

package/package.json

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

package/specs/account.yaml

@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
   title: NASEBANAL Account API
   description: Centralized user and billing management API for NASEBANAL applications. Manages user profiles, per-service subscriptions, Stripe billing, and Personal Access Tokens (PAT).
-  version: 1.5.1
+  version: 1.6.0
   contact:
     name: NASEBANAL
     url: https://www.nasebanal.com

package/specs/app-template.yaml

@@ -1,488 +0,0 @@
-openapi: 3.0.3
-info:
-  title: NASEBANAL - App Template API
-  description: |-
-    A template API for NASEBANAL applications. Provides sample CRUD endpoints, user authentication via Auth0 JWT and Personal Access Tokens (PAT), and integration with the Account API.
-
-    All responses use a uniform envelope: successful responses are `{ "success": true, "data": ... }` and failures are `{ "success": false, "error": { "code", "message" } }`. This mirrors `successResponse()` / `errorResponse()` in the implementation. The `success` discriminator is pinned with `enum` so both Specmatic stub generation and contract tests treat it as a fixed value per response class.
-  version: 1.1.1
-  contact:
-    name: NASEBANAL
-    url: https://www.nasebanal.com
-servers:
-  - url: http://localhost:8789
-    description: Local dev (wrangler dev)
-  - url: https://api.app-template.nasebanal.com
-    description: Production
-security:
-  - BearerAuth: []
-paths:
-  /api/v1/health:
-    get:
-      operationId: getHealth
-      tags:
-        - Health
-      summary: Health check
-      description: Returns the health status of the API.
-      security: []
-      responses:
-        "200":
-          description: API is healthy
-          content:
-            application/json:
-              schema:
-                type: object
-                required:
-                  - success
-                  - data
-                properties:
-                  success:
-                    type: boolean
-                    enum:
-                      - true
-                  data:
-                    type: object
-                    required:
-                      - status
-                      - timestamp
-                    properties:
-                      status:
-                        type: string
-                      timestamp:
-                        type: string
-                        format: date-time
-              examples:
-                valid:
-                  value:
-                    success: true
-                    data:
-                      status: ok
-                      timestamp: 2026-05-14T12:00:00Z
-  /api/v1/me:
-    get:
-      operationId: getCurrentUser
-      tags:
-        - User
-      summary: Get current user profile
-      description: Returns the authenticated user's profile information from the Account API.
-      responses:
-        "200":
-          description: User profile
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/UserResponse"
-              examples:
-                valid:
-                  value:
-                    success: true
-                    data:
-                      id: 42
-                      auth0_sub: auth0|0123456789abcdef
-                      email: user@example.com
-                      name: Sample User
-                      language: ja
-                      plan: pro
-                      subscription_status: active
-                      subscription_expires_at: 2026-12-31T23:59:59Z
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-  /api/v1/items:
-    get:
-      operationId: listItems
-      tags:
-        - Items
-      summary: List items
-      description: Returns all items belonging to the authenticated user.
-      responses:
-        "200":
-          description: List of items
-          content:
-            application/json:
-              schema:
-                type: object
-                required:
-                  - success
-                  - data
-                properties:
-                  success:
-                    type: boolean
-                    enum:
-                      - true
-                  data:
-                    type: object
-                    required:
-                      - data
-                      - total
-                    properties:
-                      data:
-                        type: array
-                        items:
-                          $ref: "#/components/schemas/Item"
-                      total:
-                        type: integer
-              examples:
-                valid:
-                  value:
-                    success: true
-                    data:
-                      data:
-                        - id: itm_a1b2c3d4
-                          user_id: 42
-                          name: My Item
-                          description: A sample item description
-                          created_at: 2026-05-14T12:00:00Z
-                          updated_at: 2026-05-14T12:00:00Z
-                      total: 1
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-    post:
-      operationId: createItem
-      tags:
-        - Items
-      summary: Create item
-      description: Creates a new item for the authenticated user.
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/CreateItemInput"
-            examples:
-              valid:
-                value:
-                  name: My Item
-                  description: A sample item description
-      responses:
-        "201":
-          description: Item created
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ItemResponse"
-              examples:
-                valid:
-                  value:
-                    success: true
-                    data:
-                      id: itm_a1b2c3d4
-                      user_id: 42
-                      name: My Item
-                      description: A sample item description
-                      created_at: 2026-05-14T12:00:00Z
-                      updated_at: 2026-05-14T12:00:00Z
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-  /api/v1/items/{id}:
-    get:
-      operationId: getItem
-      tags:
-        - Items
-      summary: Get item
-      description: Returns a single item by ID.
-      parameters:
-        - name: id
-          in: path
-          required: true
-          schema:
-            type: string
-          examples:
-            valid:
-              value: itm_a1b2c3d4
-      responses:
-        "200":
-          description: Item details
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ItemResponse"
-              examples:
-                valid:
-                  value:
-                    success: true
-                    data:
-                      id: itm_a1b2c3d4
-                      user_id: 42
-                      name: My Item
-                      description: A sample item description
-                      created_at: 2026-05-14T12:00:00Z
-                      updated_at: 2026-05-14T12:00:00Z
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-        "404":
-          $ref: "#/components/responses/NotFound"
-    put:
-      operationId: updateItem
-      tags:
-        - Items
-      summary: Update item
-      description: Updates an existing item.
-      parameters:
-        - name: id
-          in: path
-          required: true
-          schema:
-            type: string
-          examples:
-            valid:
-              value: itm_a1b2c3d4
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/UpdateItemInput"
-            examples:
-              valid:
-                value:
-                  name: Updated Item
-                  description: An updated item description
-      responses:
-        "200":
-          description: Item updated
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ItemResponse"
-              examples:
-                valid:
-                  value:
-                    success: true
-                    data:
-                      id: itm_a1b2c3d4
-                      user_id: 42
-                      name: Updated Item
-                      description: An updated item description
-                      created_at: 2026-05-14T12:00:00Z
-                      updated_at: 2026-05-15T09:30:00Z
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-        "404":
-          $ref: "#/components/responses/NotFound"
-    delete:
-      operationId: deleteItem
-      tags:
-        - Items
-      summary: Delete item
-      description: Deletes an item by ID.
-      parameters:
-        - name: id
-          in: path
-          required: true
-          schema:
-            type: string
-          examples:
-            valid:
-              value: itm_a1b2c3d4
-      responses:
-        "200":
-          description: Item deleted
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/SuccessResponse"
-              examples:
-                valid:
-                  value:
-                    success: true
-                    data:
-                      success: true
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-        "404":
-          $ref: "#/components/responses/NotFound"
-components:
-  securitySchemes:
-    BearerAuth:
-      type: http
-      scheme: bearer
-      bearerFormat: JWT or PAT
-      description: Use either an Auth0 JWT token or a Personal Access Token (PAT) starting with `nbpat_`.
-  schemas:
-    User:
-      type: object
-      required:
-        - id
-        - auth0_sub
-        - email
-        - name
-        - language
-        - plan
-      properties:
-        id:
-          type: integer
-        auth0_sub:
-          type: string
-        email:
-          type: string
-          format: email
-        name:
-          type: string
-        language:
-          type: string
-          enum:
-            - ja
-            - en
-        plan:
-          type: string
-          enum:
-            - free
-            - pro
-            - family
-            - enterprise
-        subscription_status:
-          type: string
-          enum:
-            - active
-            - canceled
-            - past_due
-            - trialing
-            - null
-          nullable: true
-        subscription_expires_at:
-          type: string
-          format: date-time
-          nullable: true
-    UserResponse:
-      type: object
-      required:
-        - success
-        - data
-      properties:
-        success:
-          type: boolean
-          enum:
-            - true
-        data:
-          $ref: "#/components/schemas/User"
-    Item:
-      type: object
-      required:
-        - id
-        - user_id
-        - name
-        - created_at
-        - updated_at
-      properties:
-        id:
-          type: string
-        user_id:
-          type: integer
-        name:
-          type: string
-        description:
-          type: string
-          nullable: true
-        created_at:
-          type: string
-          format: date-time
-        updated_at:
-          type: string
-          format: date-time
-    ItemResponse:
-      type: object
-      required:
-        - success
-        - data
-      properties:
-        success:
-          type: boolean
-          enum:
-            - true
-        data:
-          $ref: "#/components/schemas/Item"
-    CreateItemInput:
-      type: object
-      required:
-        - name
-      properties:
-        name:
-          type: string
-          minLength: 1
-          maxLength: 200
-        description:
-          type: string
-          maxLength: 1000
-    UpdateItemInput:
-      type: object
-      properties:
-        name:
-          type: string
-          minLength: 1
-          maxLength: 200
-        description:
-          type: string
-          maxLength: 1000
-    SuccessResponse:
-      type: object
-      required:
-        - success
-        - data
-      properties:
-        success:
-          type: boolean
-          enum:
-            - true
-        data:
-          type: object
-          required:
-            - success
-          properties:
-            success:
-              type: boolean
-              enum:
-                - true
-    Error:
-      type: object
-      required:
-        - success
-        - error
-      properties:
-        success:
-          type: boolean
-          enum:
-            - false
-        error:
-          type: object
-          required:
-            - code
-            - message
-          properties:
-            code:
-              type: string
-            message:
-              type: string
-  responses:
-    Unauthorized:
-      description: Authentication required or invalid token
-      content:
-        application/json:
-          schema:
-            $ref: "#/components/schemas/Error"
-          examples:
-            unauthorized:
-              value:
-                success: false
-                error:
-                  code: AUTH_ERROR
-                  message: No authentication token provided
-    NotFound:
-      description: Resource not found
-      content:
-        application/json:
-          schema:
-            $ref: "#/components/schemas/Error"
-          examples:
-            not_found:
-              value:
-                success: false
-                error:
-                  code: NOT_FOUND
-                  message: Resource not found
-tags:
-  - name: Health
-    description: Health check endpoints
-  - name: User
-    description: User profile endpoints
-  - name: Items
-    description: Sample CRUD endpoints (replace with your domain)