@nasebanal/cli 0.4.0 → 0.6.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"}'
 ```
@@ -117,6 +117,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

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/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/index.js

@@ -14,6 +14,7 @@ import { buildAuthCommand } from "./auth.js";
 import { specExists } from "./spec/loader.js";
 import { printError } from "./output.js";
 import { buildReportUploadCommand } from "./reports/upload.js";
+import { 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 +27,7 @@ program
     .option("--token <token>", "override the stored PAT for this invocation")
     .showHelpAfterError();
 program.addCommand(buildAuthCommand());
+program.addCommand(buildUpgradeCommand(version));
 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 +52,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/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.4.0",
+  "version": "0.6.0",
   "description": "gcloud-style command-line interface for NASEBANAL APIs, generated from nb-api-specs OpenAPI contracts.",
   "license": "MIT",
   "type": "module",

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)