@nasebanal/cli 0.1.0

package/dist/oauth.js

@@ -0,0 +1,265 @@
+/**
+ * Interactive Auth0 login for the CLI (gcloud-style).
+ *
+ * Two flows, sharing one Auth0 "Native" application (PKCE, no client secret):
+ *
+ *   1. Loopback (default) — start a throwaway HTTP server on localhost, open the
+ *      browser to Auth0 `/authorize`, capture the redirected `?code=…`, and
+ *      exchange it for tokens. This is what `gcloud auth login` does.
+ *   2. Device code (fallback / `--no-launch-browser`) — print a short user code
+ *      and a verification URL, then poll `/oauth/token` until the user finishes
+ *      in any browser. For SSH / headless boxes with no local browser.
+ *
+ * This module is pure transport: it talks to Auth0 and returns tokens. It never
+ * reads or writes the on-disk config — persistence lives in `config.ts`, which
+ * is also the only caller of `refreshTokens()`.
+ *
+ * Auth0 setup required (one time, by a tenant admin):
+ *   - Create an Application of type **Native** (PKCE, public client).
+ *   - Grant types: Authorization Code, Refresh Token, Device Code.
+ *   - Allowed Callback URLs: this tenant validates the port, so register every
+ *     port in LOOPBACK_PORTS as `http://localhost:<port>/callback`. The CLI binds
+ *     the first free one (or the single NB_AUTH0_REDIRECT_PORT if set).
+ *   - Enable "Allow Offline Access" on the NASEBANAL API (for refresh tokens).
+ *   - Put the resulting Client ID in AUTH0_CLIENT_ID below (it is public — a
+ *     native-app client ID is not a secret), or pass NB_AUTH0_CLIENT_ID.
+ */
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { randomBytes, createHash } from "node:crypto";
+const AUTH0_DOMAIN = process.env.NB_AUTH0_DOMAIN || "dev-bv0p1636dyofjbmg.us.auth0.com";
+const AUTH0_AUDIENCE = process.env.NB_AUTH0_AUDIENCE || "https://api.nasebanal.com";
+/** Public Client ID of the Native app (not a secret for public PKCE clients). */
+const AUTH0_CLIENT_ID = "EkdU317qo2fXg2DF3n2vUo7NWpUi9Dt2";
+const SCOPE = "openid profile email offline_access";
+/**
+ * Fixed loopback ports the CLI will bind, in order. This tenant validates the
+ * callback URL by exact match (port included), so EVERY port listed here must be
+ * registered in Auth0 Allowed Callback URLs as `http://localhost:<port>/callback`.
+ * The CLI uses the first one that is free. `NB_AUTH0_REDIRECT_PORT` pins one.
+ */
+const LOOPBACK_PORTS = [8085, 8086, 8087, 8088, 8089];
+/** Thrown when the loopback flow can't even start, so the caller can fall back. */
+export class LoopbackUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LoopbackUnavailableError";
+    }
+}
+function clientId() {
+    const id = process.env.NB_AUTH0_CLIENT_ID || AUTH0_CLIENT_ID;
+    if (!id) {
+        throw new Error("Auth0 client ID is not configured. Set NB_AUTH0_CLIENT_ID, or bake the " +
+            "Native app's Client ID into AUTH0_CLIENT_ID in src/oauth.ts.");
+    }
+    return id;
+}
+const base64url = (buf) => buf.toString("base64url");
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function generatePkce() {
+    const verifier = base64url(randomBytes(32));
+    const challenge = base64url(createHash("sha256").update(verifier).digest());
+    return { verifier, challenge };
+}
+/** Best-effort browser launch. Always also print the URL so manual paste works. */
+function openBrowser(url) {
+    const { platform } = process;
+    const [cmd, args] = platform === "darwin"
+        ? ["open", [url]]
+        : platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = spawn(cmd, [...args], { stdio: "ignore", detached: true });
+        child.on("error", () => {
+            /* no browser available — manual URL is already printed */
+        });
+        child.unref();
+    }
+    catch {
+        /* ignore — manual URL is already printed */
+    }
+}
+function toTokens(data) {
+    return {
+        access_token: data.access_token,
+        refresh_token: data.refresh_token,
+        id_token: data.id_token,
+        token_type: data.token_type,
+        scope: data.scope,
+        expires_at: typeof data.expires_in === "number" ? Date.now() + data.expires_in * 1000 : undefined,
+    };
+}
+async function postForm(path, body) {
+    const res = await fetch(`https://${AUTH0_DOMAIN}${path}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+        body: new URLSearchParams(body).toString(),
+    });
+    return (await res.json().catch(() => ({})));
+}
+function tokenError(data, fallback) {
+    return new Error(`${fallback}: ${data.error ?? "unknown"}${data.error_description ? ` — ${data.error_description}` : ""}`);
+}
+// ---------------------------------------------------------------------------
+// Loopback flow
+// ---------------------------------------------------------------------------
+const SUCCESS_HTML = `<!doctype html><meta charset="utf-8"><title>NASEBANAL CLI</title>
+<body style="font-family:system-ui;max-width:32rem;margin:4rem auto;text-align:center">
+<h1>✓ Logged in</h1><p>You can close this tab and return to your terminal.</p></body>`;
+function listen(server, port) {
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, "127.0.0.1", () => {
+            server.removeListener("error", reject);
+            resolve();
+        });
+    });
+}
+/** Resolve with the auth `code` once Auth0 redirects to our loopback server. */
+function waitForCode(server, expectedState, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error("Timed out waiting for the browser login to complete."));
+        }, timeoutMs);
+        server.on("request", (req, res) => {
+            const url = new URL(req.url ?? "/", "http://localhost");
+            if (url.pathname !== "/callback") {
+                res.writeHead(404).end();
+                return;
+            }
+            const error = url.searchParams.get("error");
+            const code = url.searchParams.get("code");
+            const state = url.searchParams.get("state");
+            res.writeHead(error ? 400 : 200, { "Content-Type": "text/html; charset=utf-8" });
+            res.end(error ? `Login failed: ${error}. You can close this tab.` : SUCCESS_HTML);
+            clearTimeout(timer);
+            if (error)
+                return reject(tokenError({ error }, "Authorization failed"));
+            if (state !== expectedState)
+                return reject(new Error("State mismatch — possible CSRF; aborting."));
+            if (!code)
+                return reject(new Error("No authorization code in the callback."));
+            resolve(code);
+        });
+    });
+}
+export async function loopbackLogin() {
+    const { verifier, challenge } = generatePkce();
+    const state = base64url(randomBytes(16));
+    const server = createServer();
+    const pinned = Number(process.env.NB_AUTH0_REDIRECT_PORT) || 0;
+    const candidates = pinned ? [pinned] : LOOPBACK_PORTS;
+    let bound = false;
+    for (const candidate of candidates) {
+        try {
+            await listen(server, candidate);
+            bound = true;
+            break;
+        }
+        catch {
+            /* port busy — try the next one */
+        }
+    }
+    if (!bound) {
+        throw new LoopbackUnavailableError(`Could not bind any loopback callback port (tried ${candidates.join(", ")}).`);
+    }
+    const port = server.address().port;
+    const redirectUri = `http://localhost:${port}/callback`;
+    const authorizeUrl = new URL(`https://${AUTH0_DOMAIN}/authorize`);
+    authorizeUrl.search = new URLSearchParams({
+        response_type: "code",
+        client_id: clientId(),
+        redirect_uri: redirectUri,
+        scope: SCOPE,
+        audience: AUTH0_AUDIENCE,
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        state,
+    }).toString();
+    process.stderr.write(`Opening your browser to log in. If it doesn't open, visit this URL:\n\n  ${authorizeUrl.toString()}\n\n`);
+    openBrowser(authorizeUrl.toString());
+    try {
+        const code = await waitForCode(server, state, 5 * 60_000);
+        const data = await postForm("/oauth/token", {
+            grant_type: "authorization_code",
+            client_id: clientId(),
+            code,
+            redirect_uri: redirectUri,
+            code_verifier: verifier,
+        });
+        if (!data.access_token)
+            throw tokenError(data, "Token exchange failed");
+        return toTokens(data);
+    }
+    finally {
+        server.close();
+    }
+}
+export async function deviceCodeLogin() {
+    const res = await fetch(`https://${AUTH0_DOMAIN}/oauth/device/code`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+        body: new URLSearchParams({ client_id: clientId(), scope: SCOPE, audience: AUTH0_AUDIENCE }).toString(),
+    });
+    const data = (await res.json().catch(() => ({})));
+    if (!res.ok || !data.device_code)
+        throw tokenError(data, "Could not start device login");
+    process.stderr.write(`\nTo log in, visit:\n\n  ${data.verification_uri}\n\nand enter the code:\n\n  ${data.user_code}\n\n`);
+    if (data.verification_uri_complete) {
+        process.stderr.write(`Or open this URL directly (code pre-filled):\n\n  ${data.verification_uri_complete}\n\n`);
+        openBrowser(data.verification_uri_complete);
+    }
+    process.stderr.write("Waiting for you to finish in the browser…\n");
+    let intervalMs = (data.interval ?? 5) * 1000;
+    const deadline = Date.now() + data.expires_in * 1000;
+    while (Date.now() < deadline) {
+        await sleep(intervalMs);
+        const token = await postForm("/oauth/token", {
+            grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+            client_id: clientId(),
+            device_code: data.device_code,
+        });
+        if (token.access_token)
+            return toTokens(token);
+        switch (token.error) {
+            case "authorization_pending":
+                break;
+            case "slow_down":
+                intervalMs += 5_000;
+                break;
+            default:
+                throw tokenError(token, "Device login failed");
+        }
+    }
+    throw new Error("Device login expired before it was approved. Run `nb auth login` again.");
+}
+// ---------------------------------------------------------------------------
+// Public entry points
+// ---------------------------------------------------------------------------
+/** Interactive login. Tries loopback; falls back to device code when it can't. */
+export async function login(opts) {
+    if (!opts.launchBrowser)
+        return deviceCodeLogin();
+    try {
+        return await loopbackLogin();
+    }
+    catch (err) {
+        if (err instanceof LoopbackUnavailableError) {
+            process.stderr.write(`${err.message}\nFalling back to device-code login.\n`);
+            return deviceCodeLogin();
+        }
+        throw err;
+    }
+}
+/** Exchange a refresh token for a fresh access token. Called by config.ts. */
+export async function refreshTokens(refreshToken) {
+    const data = await postForm("/oauth/token", {
+        grant_type: "refresh_token",
+        client_id: clientId(),
+        refresh_token: refreshToken,
+    });
+    if (!data.access_token)
+        throw tokenError(data, "Token refresh failed");
+    return toTokens(data);
+}

package/dist/output.js

@@ -0,0 +1,26 @@
+/**
+ * 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 { ApiError } from "./http.js";
+export function printJson(data) {
+    if (typeof data === "string") {
+        process.stdout.write(data + "\n");
+        return;
+    }
+    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+}
+export function printError(err) {
+    if (err instanceof ApiError) {
+        process.stderr.write(`Error: ${err.message}\n`);
+        if (err.data !== undefined && err.data !== "") {
+            const body = typeof err.data === "string" ? err.data : JSON.stringify(err.data, null, 2);
+            process.stderr.write(body + "\n");
+        }
+        if (err.status === 401) {
+            process.stderr.write("\nHint: run `nb auth login` or set NB_TOKEN to authenticate.\n");
+        }
+        return;
+    }
+    process.stderr.write(`Error: ${err.message ?? String(err)}\n`);
+}

package/dist/spec/build.js

@@ -0,0 +1,185 @@
+/**
+ * Turns an OpenAPI spec into a gcloud-style commander command tree.
+ *
+ * Mapping (deterministic, since the specs carry no operationId yet):
+ *   - The URL path, minus a leading `/api/v1`, becomes a noun hierarchy.
+ *   - Path parameters (`{id}`) become positional arguments, not command names.
+ *   - A path ending in a plural noun is a collection; a singular noun is either a
+ *     singleton resource or an action. The HTTP method + that distinction picks
+ *     the leaf verb:
+ *       GET   collection -> list      GET   singleton -> get
+ *       GET/…/{id}       -> get       DELETE/…/{id}   -> delete
+ *       POST  collection -> create    PUT -> replace   PATCH -> update
+ *       write singular segment        -> the segment itself is the verb (action)
+ *   - Query parameters become `--flag` options; a request body is `--data <json>`.
+ *
+ * e.g.  GET    /api/v1/me                -> nb account me get
+ *       GET    /api/v1/me/tokens         -> 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-> nb target shares accept <id>
+ *       POST   /api/v1/stripe/checkout   -> nb account stripe checkout --data '…'
+ *
+ * When two operations collapse to the same command (e.g. `/shares/accept` and
+ * `/shares/{id}/accept`), the more specific one — more path parameters — wins,
+ * deterministically, regardless of spec order.
+ *
+ * When the specs gain operationId / x-cli-name hints, this is the single place
+ * that consumes them — the command surface stays a pure function of the contract.
+ */
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { loadSpec } from "./loader.js";
+import { resolveBaseUrl, request } from "../http.js";
+import { resolveAccessToken, resolveEnv } from "../config.js";
+import { printJson } from "../output.js";
+const METHODS = ["get", "post", "put", "patch", "delete"];
+function stripBasePath(path) {
+    return path.replace(/^\/api\/v1(?=\/|$)/, "") || "/";
+}
+function pathParams(path) {
+    return [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
+}
+/** Rough plurality test — good enough to tell collections from singletons/actions. */
+function isPlural(segment) {
+    return /s$/.test(segment) && !/ss$/.test(segment);
+}
+const PLURAL_VERB = {
+    get: "list",
+    post: "create",
+    put: "replace",
+    patch: "update",
+    delete: "delete",
+};
+/** Command-name chain for an operation, e.g. ["me", "tokens", "list"]. */
+function commandChain(method, path) {
+    const segments = stripBasePath(path).split("/").filter(Boolean);
+    const nonParam = segments.filter((s) => !s.startsWith("{"));
+    const last = segments[segments.length - 1] ?? "";
+    // Item access by path parameter: /records/{id}, /me/tokens/{id}
+    if (last.startsWith("{")) {
+        const verb = method === "get" ? "get" : PLURAL_VERB[method];
+        return [...nonParam, verb];
+    }
+    const leafSegment = nonParam[nonParam.length - 1] ?? "";
+    const prefix = nonParam.slice(0, -1);
+    if (method === "get") {
+        return [...nonParam, isPlural(leafSegment) ? "list" : "get"];
+    }
+    // Write methods on a collection -> CRUD verb; on a singular segment -> action.
+    if (isPlural(leafSegment)) {
+        return [...nonParam, PLURAL_VERB[method]];
+    }
+    return [...prefix, leafSegment];
+}
+/** Find or create an intermediate group command under `parent`. */
+function group(parent, name) {
+    const existing = parent.commands.find((c) => c.name() === name);
+    if (existing)
+        return existing;
+    const cmd = new Command(name).description(`${name} commands`);
+    parent.addCommand(cmd);
+    return cmd;
+}
+function readData(value) {
+    const raw = value.startsWith("@") ? readFileSync(value.slice(1), "utf8") : value;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`--data must be valid JSON (or @file containing JSON); got: ${value}`);
+    }
+}
+function attachLeaf(parent, name, pathTemplate, method, op, servers) {
+    const leaf = new Command(name);
+    leaf.description(op.summary || `${method.toUpperCase()} ${pathTemplate}`);
+    const params = pathParams(pathTemplate);
+    for (const p of params)
+        leaf.argument(`<${p}>`, `path parameter: ${p}`);
+    const queryParams = (op.parameters ?? []).filter((p) => p.in === "query");
+    for (const q of queryParams) {
+        leaf.option(`--${q.name} <value>`, q.description || `query parameter: ${q.name}`);
+    }
+    const acceptsBody = method !== "get" && method !== "delete";
+    if (acceptsBody || op.requestBody) {
+        leaf.option("--data <json>", "request body as JSON (or @file to read from a file)");
+    }
+    leaf.action(async (...args) => {
+        // commander passes: ...positionalArgs, options, command
+        const command = args[args.length - 1];
+        const positionals = args.slice(0, params.length);
+        const opts = command.optsWithGlobals();
+        const env = opts.env || resolveEnv();
+        const token = opts.token || (await resolveAccessToken());
+        // NB_BASE_URL overrides server resolution entirely (origin only — the spec
+        // path is still appended). Used by the CDD contract test to point the CLI at
+        // a Specmatic stub, and available for advanced/self-hosted setups.
+        const override = process.env.NB_BASE_URL?.replace(/\/$/, "");
+        const baseUrl = override ?? resolveBaseUrl(servers, env);
+        let realPath = pathTemplate;
+        params.forEach((p, i) => {
+            realPath = realPath.replace(`{${p}}`, encodeURIComponent(positionals[i]));
+        });
+        const query = {};
+        for (const q of queryParams)
+            query[q.name] = opts[q.name];
+        const body = opts.data !== undefined ? readData(opts.data) : undefined;
+        const res = await request({ baseUrl, path: realPath, method, query, body, token });
+        printJson(res.data);
+    });
+    parent.addCommand(leaf);
+}
+/** Build the top-level command group for one API from its spec. */
+export function buildApiCommand(api) {
+    const spec = loadSpec(api.spec);
+    const root = new Command(api.name).description(api.summary || spec.info.title);
+    // Collect, then dedupe by command chain so the most specific operation (the
+    // one with the most path parameters) wins regardless of declaration order.
+    const byChain = new Map();
+    for (const [path, item] of Object.entries(spec.paths)) {
+        for (const method of METHODS) {
+            const op = item[method];
+            if (!op)
+                continue;
+            const entry = { chain: commandChain(method, path), path, method, op };
+            const key = entry.chain.join(" ");
+            const existing = byChain.get(key);
+            if (!existing || pathParams(path).length > pathParams(existing.path).length) {
+                byChain.set(key, entry);
+            }
+        }
+    }
+    // A write on a singular segment is named after the segment itself, so that
+    // `POST /me/accept-terms` reads as `me accept-terms`. That breaks down when
+    // the same segment is ALSO a group: `DELETE /api/v1/me` wants the leaf `me`
+    // while `GET /api/v1/me` and `GET /api/v1/me/tokens` want a group `me`, and
+    // commander rejects the second registration outright ("cannot add command
+    // 'me' as already have command 'me'"). Account deletion introduced exactly
+    // that shape in account 1.2.0 and took the whole CLI build down with it.
+    //
+    // Any chain that is a strict prefix of another chain is such a case; give it
+    // its verb back (`me delete`), which is what the non-colliding paths already
+    // look like. An entry is only re-keyed if the verb form is still free, so a
+    // real operation already sitting there is never displaced.
+    const chains = [...byChain.keys()].map((k) => k.split(" "));
+    const isGroupElsewhere = (chain) => chains.some((other) => other.length > chain.length && chain.every((s, i) => other[i] === s));
+    for (const entry of [...byChain.values()]) {
+        if (!isGroupElsewhere(entry.chain))
+            continue;
+        const verb = entry.method === "get" ? "get" : PLURAL_VERB[entry.method];
+        const renamed = [...entry.chain, verb];
+        const key = renamed.join(" ");
+        if (byChain.has(key))
+            continue;
+        byChain.delete(entry.chain.join(" "));
+        byChain.set(key, { ...entry, chain: renamed });
+    }
+    for (const { chain, path, method, op } of byChain.values()) {
+        const leafName = chain[chain.length - 1];
+        let parent = root;
+        for (const segment of chain.slice(0, -1))
+            parent = group(parent, segment);
+        attachLeaf(parent, leafName, path, method, op, spec.servers);
+    }
+    return root;
+}

package/dist/spec/loader.js

@@ -0,0 +1,23 @@
+/**
+ * Loads and minimally types the OpenAPI specs that drive the command tree.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { parse } from "yaml";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// dist/spec/loader.js  -> ../../specs ; src/spec/loader.ts -> ../../specs
+const SPECS_DIR = join(__dirname, "..", "..", "specs");
+export function specPath(file) {
+    return join(SPECS_DIR, file);
+}
+export function specExists(file) {
+    return existsSync(specPath(file));
+}
+export function loadSpec(file) {
+    const path = specPath(file);
+    if (!existsSync(path)) {
+        throw new Error(`Spec not found: ${path}\nRun \`npm run sync-specs\` (local dev) to populate the specs/ directory.`);
+    }
+    return parse(readFileSync(path, "utf8"));
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@nasebanal/cli",
+  "version": "0.1.0",
+  "description": "gcloud-style command-line interface for NASEBANAL APIs, generated from nb-api-specs OpenAPI contracts.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "nb": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "specs"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "sync-specs": "node scripts/sync-specs.mjs",
+    "build": "npm run sync-specs && tsc -p tsconfig.json",
+    "dev": "node --import tsx src/index.ts",
+    "start": "node dist/index.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "yaml": "^2.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.8"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nasebanal/nb-cli.git"
+  },
+  "keywords": [
+    "nasebanal",
+    "cli",
+    "openapi",
+    "cdd",
+    "api-client"
+  ],
+  "overrides": {
+    "postcss": "^8.5.18",
+    "brace-expansion@<=1.1.17": "1.1.18",
+    "brace-expansion@2.0.0 - 2.1.3": "2.1.4",
+    "brace-expansion@4.0.0 - 5.0.8": "5.0.9",
+    "nanoid@<3.3.17": "3.3.18"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public",
+    "@nasebanal:registry": "https://registry.npmjs.org/"
+  }
+}