@nasebanal/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NASEBANAL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,237 @@
+# NASEBANAL CLI
+
+`nb` — a gcloud-style command-line interface for the NASEBANAL APIs.
+
+The command tree is **generated from the OpenAPI contracts** published by
+[`nb-api-specs`](https://github.com/nasebanal/nb-api-specs). Every endpoint
+becomes a `nb <api> <resource> <verb>` command, so the CLI stays a pure function
+of the API contracts — it is the command-line consumer in the NASEBANAL
+Contract-Driven Development (CDD) pipeline, alongside the web frontends.
+
+```console
+$ nb account me get
+$ nb recorder records list
+$ nb target shares accept <id>
+$ nb account me tokens create --data '{"name":"ci"}'
+```
+
+## Tech Stack
+
+- **Language:** TypeScript (ESM, Node ≥ 20)
+- **CLI framework:** commander
+- **Spec parsing:** yaml
+- **Contracts:** `@nasebanal/api-specs-*` (OpenAPI 3.0) — the same packages backends and frontends consume
+- **Authentication:** browser/device-code Auth0 login, or a NASEBANAL Personal Access Token (`nbpat_…`)
+- **Testing:** Vitest
+- **Distribution:** npm (`npx @nasebanal/cli`); single-binary builds are a planned follow-up
+
+## Installation
+
+The CLI installs the `nb` command. Node ≥ 20 is required.
+
+### From the npm registry (end users)
+
+`@nasebanal/cli` is published to the public npm registry — no `git clone`, no
+registry configuration, no token:
+
+```bash
+npm install -g @nasebanal/cli   # global: the `nb` command on your PATH
+nb --version
+nb --help
+
+# or run without installing (pin a version for reproducible scripts)
+npx @nasebanal/cli@0.1.0 account me get
+```
+
+The published package bundles the OpenAPI specs, so no `nb-api-specs` checkout is
+needed for a registry install.
+
+> **NASEBANAL developers:** if your `~/.npmrc` maps `@nasebanal:registry` to
+> GitHub Packages (needed for the private `@nasebanal/shared-navigation` /
+> `api-specs-*` packages), it captures this package too. Install with
+> `npm install -g @nasebanal/cli --@nasebanal:registry=https://registry.npmjs.org/`.
+
+### Versioning and releases
+
+Versions follow SemVer (0.x until 1.0: breaking changes bump the minor). Each
+release bundles a fixed set of API contract versions, recorded in
+[`spec-versions.json`](spec-versions.json). A release is cut by pushing a
+`vX.Y.Z` tag that matches `package.json`; the `Release` workflow publishes it to
+npm with provenance.
+
+### From source (contributors)
+
+Requires a sibling `nb-api-specs` checkout (the build syncs specs from it):
+
+```bash
+git clone https://github.com/nasebanal/nb-cli.git
+cd nb-cli
+npm install
+npm run build          # sync specs + compile to dist/
+npm link               # symlink the `nb` command onto your PATH
+nb --help
+
+# undo later with:  npm unlink -g @nasebanal/cli
+```
+
+Without linking, you can always run the compiled binary directly
+(`node dist/index.js …`) or from source via `npm run dev -- …` (see
+[Local Development](#local-development)).
+
+### First run
+
+```bash
+nb auth login          # browser login (see Authentication below)
+nb account me get      # verify the token works against a real API
+```
+
+## Command Mapping
+
+The specs carry no `operationId` yet, so commands are derived deterministically
+from each path + method:
+
+| OpenAPI operation | Command |
+|-------------------|---------|
+| `GET /api/v1/me` (singleton) | `nb account me get` |
+| `GET /api/v1/me/tokens` (collection) | `nb account me tokens list` |
+| `POST /api/v1/me/tokens` | `nb account me tokens create --data '…'` |
+| `DELETE /api/v1/me/tokens/{id}` | `nb account me tokens delete <id>` |
+| `POST /api/v1/shares/{id}/accept` (action) | `nb target shares accept <id>` |
+| `POST /api/v1/stripe/checkout` | `nb account stripe checkout --data '…'` |
+
+Rules: a path ending in a plural noun is a collection (`list` / `create`); a
+singular noun is a singleton (`get`) or, for write methods, an action whose
+segment becomes the verb. Path parameters become positional arguments; query
+parameters become `--flags`; a request body is `--data <json>` (or `--data @file`).
+When two operations collapse to the same command (e.g. `/shares/accept` and
+`/shares/{id}/accept`), the more specific one — more path parameters — wins.
+
+> When the specs gain `operationId` / `x-cli-name` hints, `src/spec/build.ts` is
+> the single place that consumes them. Adding those hints is the recommended way
+> to refine command names without touching the CLI.
+
+## Authentication
+
+`nb auth login` opens a browser, you log in with Auth0, and control returns to
+the terminal automatically — the same experience as `gcloud auth login`.
+
+```bash
+nb auth login                 # browser login (loopback OAuth + PKCE)
+nb auth login --no-launch-browser  # device-code flow (SSH / headless boxes)
+nb auth status                # show active credential source + environment
+nb auth logout                # remove stored credentials
+```
+
+Under the hood this is OAuth 2.0 Authorization Code + PKCE against a shared
+Auth0 **Native** application. On login the CLI stores the access token and a
+refresh token; expired access tokens are refreshed automatically on the next
+command, so you rarely need to log in again.
+
+**PAT / CI auth** is still supported for scripting:
+
+```bash
+nb auth login --token nbpat_… # store a Personal Access Token non-interactively
+nb auth login --token-stdin   # paste a PAT from stdin (no shell history)
+NB_TOKEN=nbpat_… nb …         # env override (wins over everything; no login needed)
+```
+
+Create a PAT in the web app under **Settings → API tokens** (Account API).
+
+- Credentials live at `~/.config/nasebanal/config.json` with `0600` permissions.
+- Precedence on each request: `NB_TOKEN` env → OAuth tokens → stored PAT.
+
+### Auth0 setup (one time, tenant admin)
+
+The browser flow needs a public **Native** application in Auth0:
+
+1. Create an Application of type **Native** (PKCE, no client secret).
+2. Grant types: **Authorization Code**, **Refresh Token**, **Device Code**.
+3. Allowed Callback URLs — this tenant validates the port, so register every
+   loopback port the CLI may use (the CLI binds the first free one):
+   `http://localhost:8085/callback, http://localhost:8086/callback, http://localhost:8087/callback, http://localhost:8088/callback, http://localhost:8089/callback`
+   (`NB_AUTH0_REDIRECT_PORT` pins a single port if you prefer.)
+4. Enable **Allow Offline Access** on the NASEBANAL API (for refresh tokens).
+5. Put the resulting **Client ID** (public, not a secret) into `AUTH0_CLIENT_ID`
+   in `src/oauth.ts`, or set `NB_AUTH0_CLIENT_ID` to test before baking it in.
+
+Overridable env vars: `NB_AUTH0_DOMAIN`, `NB_AUTH0_AUDIENCE`,
+`NB_AUTH0_CLIENT_ID`, `NB_AUTH0_REDIRECT_PORT`.
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--env <production\|local>` | Target environment; picks the matching `servers` entry from the spec. Also `NB_ENV`. |
+| `--token <token>` | Override stored credentials with a PAT for one invocation. |
+| `-V, --version` | Print the CLI version. |
+
+The active environment defaults to `production`; `--env local` targets the
+`wrangler dev` servers declared in each spec.
+
+## Adding a New API
+
+1. Publish/own its spec in `nb-api-specs` (it ships as `@nasebanal/api-specs-<api>`).
+2. Add an entry to `API_CATALOG` in `src/apis.ts` and to the list in `scripts/sync-specs.mjs`.
+3. `npm run sync-specs && npm run build` — the command group appears automatically.
+
+## Project Structure
+
+```
+nb-cli/
+├── src/
+│   ├── index.ts            # Entry: global options, auth group, one group per API (★)
+│   ├── apis.ts             # API catalog (★ register new APIs here)
+│   ├── auth.ts             # `nb auth login | logout | status`
+│   ├── oauth.ts            # Auth0 loopback + device-code login, PKCE, token refresh
+│   ├── config.ts           # credentials + environment persisted to ~/.config/nasebanal/config.json
+│   ├── http.ts             # base-URL resolution + bearer request layer
+│   ├── output.ts           # JSON / error formatting
+│   └── spec/
+│       ├── loader.ts       # read + parse spec YAML from specs/
+│       ├── build.ts        # ★ OpenAPI -> commander command tree (the core mapping)
+│       └── build.test.ts   # command-mapping tests
+├── scripts/
+│   └── sync-specs.mjs      # Copy specs into specs/ (local dev convenience)
+├── specs/                  # ★ Generated: OpenAPI specs, not committed (see below)
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+Files marked with ★ are the usual customization targets.
+
+## Development
+
+### Local Development
+
+```bash
+npm install
+npm run sync-specs      # copy specs from a sibling nb-api-specs checkout into specs/
+npm run dev -- --help   # run from source (tsx), e.g. `npm run dev -- account me get`
+npm run build           # sync specs + type-check + emit dist/
+npm test                # Vitest
+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).
+
+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
+sibling repo so contract edits are visible without a publish (mirroring how
+`@nasebanal/shared-navigation` has both a published and a local-copy path).
+
+### Conventions
+
+- **The command surface is generated, not hand-written** — refine commands by
+  improving the contract (e.g. add `operationId`), not by special-casing the CLI.
+- **Specs are dependencies, not source** — `specs/` is git-ignored; production
+  pins the published `@nasebanal/api-specs-*` packages.
+- **Never commit a PAT** — config lives outside the repo; CI uses `NB_TOKEN`.
+- **Deploy/release via PR merge and CI** — never publish from a local machine.
+
+## License
+
+MIT

package/dist/apis.js

@@ -0,0 +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: "target", spec: "target.yaml", summary: "Targets, cells, and shares (NASEBANAL Target)" },
+    { name: "app-template", spec: "app-template.yaml", summary: "Reference API surface (App Template)" },
+];

package/dist/auth.js

@@ -0,0 +1,98 @@
+/**
+ * `nb auth` commands.
+ *
+ * The default `nb auth login` is an interactive Auth0 login (gcloud-style): it
+ * opens a browser, you log in, and control returns to the terminal automatically
+ * (loopback flow), falling back to a device code on headless boxes. For CI and
+ * scripting a NASEBANAL Personal Access Token (`nbpat_…`) is still supported via
+ * `--token` / `--token-stdin`, or the `NB_TOKEN` env var (which overrides both).
+ */
+import { Command } from "commander";
+import { createInterface } from "node:readline";
+import { loadConfig, saveConfig, resolveToken, resolveEnv, configFilePath } from "./config.js";
+import { login } from "./oauth.js";
+function readSecretLine(promptText) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+    process.stdout.write(promptText);
+    return new Promise((resolve) => {
+        rl.once("line", (line) => {
+            rl.close();
+            resolve(line.trim());
+        });
+    });
+}
+function storePat(config, token) {
+    if (!token) {
+        process.stderr.write("No token provided.\n");
+        process.exitCode = 1;
+        return;
+    }
+    if (!token.startsWith("nbpat_")) {
+        process.stderr.write("warning: token does not start with 'nbpat_'; storing anyway.\n");
+    }
+    config.token = token;
+    delete config.auth;
+    saveConfig(config);
+    process.stdout.write(`Token saved to ${configFilePath()}\n`);
+}
+export function buildAuthCommand() {
+    const auth = new Command("auth").description("Manage CLI authentication");
+    auth
+        .command("login")
+        .description("Log in via the browser (or store a PAT with --token / --token-stdin)")
+        .option("--no-launch-browser", "use the device-code flow instead of opening a browser")
+        .option("--token <token>", "store a Personal Access Token (nbpat_…) non-interactively")
+        .option("--token-stdin", "read a Personal Access Token from stdin")
+        .action(async (opts) => {
+        const config = loadConfig();
+        if (opts.token !== undefined) {
+            storePat(config, opts.token);
+            return;
+        }
+        if (opts.tokenStdin) {
+            storePat(config, await readSecretLine("Paste your NASEBANAL PAT (nbpat_…): "));
+            return;
+        }
+        const tokens = await login({ launchBrowser: opts.launchBrowser !== false });
+        config.auth = tokens;
+        delete config.token;
+        saveConfig(config);
+        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`);
+    });
+    auth
+        .command("logout")
+        .description("Remove stored credentials")
+        .action(() => {
+        const config = loadConfig();
+        delete config.token;
+        delete config.auth;
+        saveConfig(config);
+        process.stdout.write("Credentials removed.\n");
+    });
+    auth
+        .command("status")
+        .description("Show the active credential source and target environment")
+        .action(() => {
+        const config = loadConfig();
+        const token = resolveToken(config);
+        const source = process.env.NB_TOKEN
+            ? "NB_TOKEN env"
+            : config.auth
+                ? "OAuth login"
+                : config.token
+                    ? "stored PAT"
+                    : "none";
+        const masked = token ? `${token.slice(0, 10)}…${token.slice(-4)}` : "(not set)";
+        process.stdout.write(`Environment: ${resolveEnv(config)}\n`);
+        process.stdout.write(`Token:       ${masked}  [source: ${source}]\n`);
+        if (config.auth?.expires_at) {
+            const expired = config.auth.expires_at <= Date.now();
+            process.stdout.write(`Expires:     ${new Date(config.auth.expires_at).toLocaleString()}` +
+                `${expired ? config.auth.refresh_token ? " (expired — will refresh)" : " (expired)" : ""}\n`);
+        }
+        process.stdout.write(`Config file: ${configFilePath()}\n`);
+    });
+    return auth;
+}

package/dist/config.js

@@ -0,0 +1,97 @@
+/**
+ * Persistent CLI configuration (credentials, target environment).
+ *
+ * Stored as JSON at `$XDG_CONFIG_HOME/nasebanal/config.json` (falling back to
+ * `~/.config/nasebanal/config.json`). Two credential shapes can live here:
+ *   - `auth` — OAuth tokens from `nb auth login` (browser / device-code flow).
+ *   - `token` — a Personal Access Token (`nbpat_…`) for manual / scripted use.
+ * `NB_TOKEN` in the environment always overrides both, which is the supported
+ * path for CI.
+ */
+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() {
+    const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+    return join(base, "nasebanal");
+}
+function configPath() {
+    return join(configDir(), "config.json");
+}
+export function loadConfig() {
+    const path = configPath();
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function saveConfig(config) {
+    const dir = configDir();
+    mkdirSync(dir, { recursive: true });
+    const path = configPath();
+    writeFileSync(path, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+    // Tighten perms in case the file already existed with a looser mode.
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        /* best effort */
+    }
+}
+/**
+ * Resolve the active token synchronously, WITHOUT refreshing — for display only
+ * (`nb auth status`). Precedence: `NB_TOKEN` env, OAuth access token, stored PAT.
+ */
+export function resolveToken(config = loadConfig()) {
+    return process.env.NB_TOKEN || config.auth?.access_token || config.token;
+}
+/** Refresh OAuth tokens in-place when the access token is expired (or close to). */
+async function ensureFreshAuth(config) {
+    const auth = config.auth;
+    if (!auth)
+        return undefined;
+    const skewMs = 60_000;
+    if (!auth.expires_at || auth.expires_at - skewMs > Date.now())
+        return auth;
+    if (!auth.refresh_token)
+        return auth; // can't refresh; let the request 401
+    try {
+        const next = await refreshTokens(auth.refresh_token);
+        // Token rotation may not return a new refresh token — keep the old one.
+        const merged = { ...next, refresh_token: next.refresh_token ?? auth.refresh_token };
+        config.auth = merged;
+        saveConfig(config);
+        return merged;
+    }
+    catch {
+        return auth; // refresh failed; surface as a 401 on the actual request
+    }
+}
+/**
+ * Resolve the token to send on API requests, refreshing an expired OAuth access
+ * token first. Precedence: `NB_TOKEN` env, OAuth (refreshed), stored PAT.
+ */
+export async function resolveAccessToken(config = loadConfig()) {
+    if (process.env.NB_TOKEN)
+        return process.env.NB_TOKEN;
+    if (config.auth) {
+        const fresh = await ensureFreshAuth(config);
+        return fresh?.access_token;
+    }
+    return config.token;
+}
+/** Resolve the active environment: `NB_ENV` env wins, else stored, else production. */
+export function resolveEnv(config = loadConfig()) {
+    const fromEnv = process.env.NB_ENV;
+    if (fromEnv === "local" || fromEnv === "production")
+        return fromEnv;
+    return config.env ?? "production";
+}
+export function configFilePath() {
+    return configPath();
+}

package/dist/http.js

@@ -0,0 +1,55 @@
+export class ApiError extends Error {
+    status;
+    data;
+    constructor(message, status, data) {
+        super(message);
+        this.status = status;
+        this.data = data;
+        this.name = "ApiError";
+    }
+}
+/** Pick the server URL matching the active environment. */
+export function resolveBaseUrl(servers, env) {
+    if (!servers || servers.length === 0) {
+        throw new Error("Spec declares no servers; cannot resolve a base URL.");
+    }
+    const isLocal = (s) => /localhost|127\.0\.0\.1/.test(s.url);
+    const match = env === "local" ? servers.find(isLocal) : servers.find((s) => !isLocal(s));
+    return (match ?? servers[0]).url.replace(/\/$/, "");
+}
+export async function request(opts) {
+    const url = new URL(opts.baseUrl + opts.path);
+    for (const [key, value] of Object.entries(opts.query ?? {})) {
+        if (value !== undefined)
+            url.searchParams.set(key, value);
+    }
+    const headers = { Accept: "application/json" };
+    if (opts.token)
+        headers.Authorization = `Bearer ${opts.token}`;
+    const init = { method: opts.method.toUpperCase(), headers };
+    if (opts.body !== undefined) {
+        headers["Content-Type"] = "application/json";
+        init.body = JSON.stringify(opts.body);
+    }
+    let res;
+    try {
+        res = await fetch(url, init);
+    }
+    catch (err) {
+        throw new Error(`Request to ${url.host} failed: ${err.message}`);
+    }
+    const text = await res.text();
+    let data = text;
+    if (text) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            /* leave as raw text */
+        }
+    }
+    if (!res.ok) {
+        throw new ApiError(`${res.status} ${res.statusText}`, res.status, data);
+    }
+    return { status: res.status, ok: true, data };
+}

package/dist/index.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * `nb` — gcloud-style CLI for NASEBANAL APIs.
+ *
+ * The command tree under each API group is generated at startup from the
+ * OpenAPI specs in `specs/` (synced from nb-api-specs). This file only wires up
+ * the global options, the `auth` group, and one command group per catalog entry.
+ */
+import { createRequire } from "node:module";
+import { Command } from "commander";
+import { API_CATALOG } from "./apis.js";
+import { buildApiCommand } from "./spec/build.js";
+import { buildAuthCommand } from "./auth.js";
+import { specExists } from "./spec/loader.js";
+import { printError } from "./output.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");
+const program = new Command();
+program
+    .name("nb")
+    .description("Command-line interface for NASEBANAL APIs (generated from OpenAPI contracts).")
+    .version(version)
+    .option("--env <env>", "target environment: production | local")
+    .option("--token <token>", "override the stored PAT for this invocation")
+    .showHelpAfterError();
+program.addCommand(buildAuthCommand());
+for (const api of API_CATALOG) {
+    if (!specExists(api.spec)) {
+        // Spec not synced yet — register a stub that explains how to fix it rather
+        // than crashing the whole CLI.
+        program
+            .command(api.name)
+            .description(`${api.summary} (spec not loaded)`)
+            .allowUnknownOption()
+            .action(() => {
+            printError(new Error(`Spec '${api.spec}' is missing. Run \`npm run sync-specs\` (local dev) or reinstall the package.`));
+            process.exitCode = 1;
+        });
+        continue;
+    }
+    program.addCommand(buildApiCommand(api));
+}
+async function main() {
+    try {
+        await program.parseAsync(process.argv);
+    }
+    catch (err) {
+        printError(err);
+        process.exitCode = 1;
+    }
+}
+void main();