@norbix.ai/cli 0.1.0 → 0.2.0

package/dist/commands/raw.js

@@ -0,0 +1,86 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../base.js';
+import { readJsonInput } from '../lib/json.js';
+/**
+ * Raw escape hatch (like `gh api`): call ANY Norbix endpoint, including the
+ * ones this CLI has no dedicated command for yet. Sends the same auth and
+ * scope headers the SDK transport sends.
+ */
+export default class Raw extends BaseCommand {
+    static description = `Low-level escape hatch: call a raw HTTP path on the hub (default) or API.
+
+Prefer \`norbix hub ...\` / \`norbix api ...\` — they take plain words.
+Use this only for endpoints the SDK does not know yet. Sends your auth token
+plus project/account/env/region headers automatically. Use {version} in the
+path and it becomes v2.`;
+    static examples = [
+        '<%= config.bin %> api /v2/logs/settings --hub',
+        `<%= config.bin %> api '/{version}/database/collections/orders/count' --query filter='{"status":"paid"}'`,
+        `<%= config.bin %> api /v2/scheduler/tasks --hub --method POST --body '{"name":"nightly",...}'`,
+    ];
+    static args = {
+        path: Args.string({ required: true, description: 'Endpoint path, e.g. /v2/logs or /{version}/logs' }),
+    };
+    static flags = {
+        api: Flags.boolean({ description: 'Call the data-plane API service instead of the hub (hub is the default)', default: false }),
+        method: Flags.string({ char: 'X', description: 'HTTP method', default: 'GET', options: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] }),
+        body: Flags.string({ char: 'b', description: 'JSON request body (or `-` for stdin)' }),
+        query: Flags.string({ char: 'q', description: 'Query parameter key=value (repeatable)', multiple: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Raw);
+        const ctx = this.resolveContext(flags);
+        this.assertEndpoints(ctx);
+        if (!ctx.projectId)
+            this.error('No project ID configured. Run `norbix login` or pass --project.');
+        const token = ctx.bearerToken ?? ctx.apiKey;
+        if (!token)
+            this.error('Not authenticated. Run `norbix login` or pass --api-key.');
+        // resolveContext already applied profile overrides, defaults (.ai) and
+        // the region subdomain.
+        const base = flags.api ? ctx.apiUrl : ctx.hubUrl;
+        const path = args.path.replace('{version}', 'v2');
+        const url = new URL(base.replace(/\/$/, '') + (path.startsWith('/') ? path : `/${path}`));
+        for (const pair of flags.query ?? []) {
+            const eq = pair.indexOf('=');
+            if (eq < 1)
+                this.error(`--query must be key=value, got "${pair}"`);
+            url.searchParams.append(pair.slice(0, eq), pair.slice(eq + 1));
+        }
+        const headers = {
+            Accept: 'application/json',
+            Authorization: `Bearer ${token}`,
+            'norbix-project-id': ctx.projectId,
+            'X-CM-ProjectId': ctx.projectId,
+        };
+        if (ctx.accountId) {
+            headers['norbix-account-id'] = ctx.accountId;
+            headers['X-CM-AccountId'] = ctx.accountId;
+        }
+        if (ctx.env && ctx.env !== 'PROD')
+            headers['norbix-env'] = ctx.env;
+        if (ctx.region)
+            headers['nb-region'] = ctx.region;
+        let body;
+        if (flags.body) {
+            body = await readJsonInput(flags.body, 'body');
+            headers['Content-Type'] = 'application/json';
+        }
+        const res = await fetch(url, { method: flags.method, headers, body });
+        const text = await res.text();
+        let data;
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            data = text;
+        }
+        if (!res.ok) {
+            this.warn(`HTTP ${res.status} ${res.statusText}`);
+            this.print(data);
+            this.exit(1);
+        }
+        this.print(data);
+        return data;
+    }
+}

package/dist/commands/whoami.js

@@ -1,17 +1,31 @@
 import { BaseCommand } from '../base.js';
+import { PROFILES_PATH, SESSION_PATH } from '../lib/profiles.js';
 import { redact } from '../lib/store.js';
 export default class Whoami extends BaseCommand {
-    static description = 'Show the current CLI context and verify it against the server';
-    static examples = ['<%= config.bin %> whoami', '<%= config.bin %> whoami --json'];
+    static description = 'Show the resolved context (profile, auth source, endpoints) and verify it against the server';
+    static examples = [
+        '<%= config.bin %> whoami',
+        '<%= config.bin %> whoami --profile fitskin-prod',
+        '<%= config.bin %> whoami --json',
+    ];
     async run() {
         const { flags } = await this.parse(Whoami);
         const ctx = this.resolveContext(flags);
         const summary = {
+            profile: ctx.profileName ?? '(none)',
+            auth: ctx.authSource === 'session' ? `session (${ctx.userName ?? 'user'})` : ctx.authSource,
+            apiKey: ctx.apiKey ? redact(ctx.apiKey) : undefined,
             projectId: ctx.projectId,
+            accountId: ctx.accountId,
             env: ctx.env ?? 'PROD',
-            region: ctx.region ?? '(project default)',
-            auth: ctx.bearerToken ? `login token (${ctx.stored.userName ?? ctx.stored.userId ?? 'user'})` : ctx.apiKey ? `api key ${redact(ctx.apiKey)}` : 'none',
-            configFile: this.config.configDir,
+            region: ctx.region ??
+                (ctx.usesDefaultEndpoints
+                    ? '(NOT SET — required with default endpoints!)'
+                    : '(not set — optional with custom endpoints)'),
+            apiUrl: ctx.apiUrl,
+            hubUrl: ctx.hubUrl,
+            profilesFile: PROFILES_PATH,
+            sessionFile: SESSION_PATH,
         };
         let verified = false;
         let environments;
@@ -21,7 +35,7 @@ export default class Whoami extends BaseCommand {
                 const client = this.client(flags);
                 const res = await client.hub.environments.list();
                 const item = res.item;
-                environments = (item?.environments ?? []).map((e) => (typeof e === 'string' ? e : (e.name ?? String(e))));
+                environments = (item?.environments ?? []).map((e) => typeof e === 'string' ? e : (e.name ?? String(e)));
                 verified = true;
             }
             catch (error) {
@@ -29,11 +43,14 @@ export default class Whoami extends BaseCommand {
             }
         }
         this.print([
+            `Profile:  ${summary.profile}`,
+            `Auth:     ${summary.auth}${summary.apiKey ? ` (${summary.apiKey})` : ''}`,
             `Project:  ${summary.projectId ?? '(not set)'}`,
+            `Account:  ${summary.accountId ?? '(not set)'}`,
             `Env:      ${summary.env}`,
             `Region:   ${summary.region}`,
-            `Auth:     ${summary.auth}`,
-            `Config:   ${summary.configFile}`,
+            `API:      ${summary.apiUrl}`,
+            `Hub:      ${summary.hubUrl}`,
             verified
                 ? `Server:   OK${environments?.length ? ` — environments: ${environments.join(', ')}` : ''}`
                 : `Server:   not verified${verifyError ? ` (${verifyError})` : ''}`,

package/dist/help.js

@@ -0,0 +1,18 @@
+import { Help } from '@oclif/core';
+/**
+ * Custom help router. oclif intercepts --help before a command runs, which
+ * would hide the scoped help of the dynamic namespaces. For
+ * `norbix hub <words...> --help` (and `api`), delegate back to the command
+ * with an internal marker so it can print help for exactly that scope.
+ */
+export default class NorbixHelp extends Help {
+    async showHelp(argv) {
+        const words = argv.filter((a) => a !== '--help' && a !== '-h');
+        const [first, ...rest] = words;
+        if ((first === 'hub' || first === 'api') && rest.length > 0) {
+            await this.config.runCommand(first, [...rest, '--scope-help']);
+            return;
+        }
+        return super.showHelp(argv);
+    }
+}

package/dist/lib/device-login.js

@@ -0,0 +1,76 @@
+import { spawn } from 'node:child_process';
+export class DeviceFlowUnsupportedError extends Error {
+}
+export async function startDeviceFlow(hubUrl, projectId) {
+    let res;
+    try {
+        res = await fetch(`${hubUrl.replace(/\/$/, '')}/v2/auth/device/start`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+            body: JSON.stringify({ clientName: 'norbix-cli', projectId }),
+        });
+    }
+    catch (error) {
+        throw new DeviceFlowUnsupportedError(`Could not reach ${hubUrl}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // 404/405/501 → the hub does not implement browser login (yet).
+    if ([404, 405, 501].includes(res.status)) {
+        throw new DeviceFlowUnsupportedError(`Hub returned HTTP ${res.status} for the device flow.`);
+    }
+    if (!res.ok)
+        throw new Error(`Device login start failed: HTTP ${res.status}`);
+    const data = (await res.json());
+    if (!data.deviceCode || !data.userCode || !data.verificationUri) {
+        throw new Error('Device login start returned an unexpected response.');
+    }
+    return data;
+}
+/** Poll until the user approves in the browser (or the code expires). */
+export async function pollDeviceToken(hubUrl, start, log) {
+    const deadline = Date.now() + (start.expiresIn ?? 600) * 1000;
+    let intervalMs = (start.interval ?? 5) * 1000;
+    while (Date.now() < deadline) {
+        await sleep(intervalMs);
+        const res = await fetch(`${hubUrl.replace(/\/$/, '')}/v2/auth/device/token`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+            body: JSON.stringify({ deviceCode: start.deviceCode }),
+        });
+        if (res.status === 428)
+            continue; // still pending
+        const data = (await res.json().catch(() => ({})));
+        if (data.error === 'authorization_pending')
+            continue;
+        if (data.error === 'slow_down') {
+            intervalMs += 5000;
+            continue;
+        }
+        if (data.error === 'access_denied')
+            throw new Error('Login was denied in the browser.');
+        if (data.error === 'expired_token')
+            break;
+        if (!res.ok)
+            throw new Error(`Device login failed: HTTP ${res.status}`);
+        if (data.bearerToken)
+            return data;
+        log('Unexpected response while waiting — retrying...');
+    }
+    throw new Error('The login code expired. Run `norbix login` again.');
+}
+/** Open a URL in the default browser — macOS, Linux, Windows. */
+export function openBrowser(url) {
+    const [cmd, args] = process.platform === 'darwin'
+        ? ['open', [url]]
+        : process.platform === 'win32'
+            ? ['cmd', ['/c', 'start', '', url]]
+            : ['xdg-open', [url]];
+    try {
+        spawn(cmd, args, { detached: true, stdio: 'ignore' }).unref();
+    }
+    catch {
+        // Browser could not be opened — the URL is printed anyway.
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/lib/dispatch.js

@@ -0,0 +1,151 @@
+/**
+ * Dynamic dispatcher: turns
+ *
+ *   norbix hub database aggregates delete maggr_123 --schemaId sch_456
+ *
+ * into `client.hub.database.deleteDatabaseAggregate({id, schemaId})`.
+ *
+ * Grammar:  norbix {hub|api} {module} {words...} {positional id} {--field value}
+ *
+ * The SDK namespaces are auto-generated and uniform (every method takes one
+ * request object), so the CLI can discover modules and methods at runtime —
+ * every current AND future SDK method is callable without new command files.
+ */
+/** Split leftover argv into words, positional values and --field values. */
+export function parseArgv(argv) {
+    const words = [];
+    const positionals = [];
+    const fields = {};
+    let yes = false;
+    let dryRun = false;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--yes' || token === '-y') {
+            yes = true;
+        }
+        else if (token === '--dry-run') {
+            dryRun = true;
+        }
+        else if (token.startsWith('--')) {
+            const body = token.slice(2);
+            const eq = body.indexOf('=');
+            if (eq > 0) {
+                // --field=value syntax
+                fields[body.slice(0, eq)] = coerce(body.slice(eq + 1));
+            }
+            else {
+                const next = argv[i + 1];
+                if (next !== undefined && !next.startsWith('--')) {
+                    fields[body] = coerce(next);
+                    i++;
+                }
+                else {
+                    fields[body] = true;
+                }
+            }
+        }
+        else if (/^[a-z][a-z-]*$/i.test(token) && !looksLikeId(token)) {
+            words.push(token);
+        }
+        else {
+            positionals.push(token);
+        }
+    }
+    return { words, positionals, fields, yes, dryRun };
+}
+/** IDs look like maggr_..., sch_..., 66b2f0a1..., UPPER env names, etc. */
+function looksLikeId(token) {
+    return /[_0-9]/.test(token) || token === token.toUpperCase();
+}
+function coerce(value) {
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    if (/^-?\d+$/.test(value))
+        return Number(value);
+    return value;
+}
+function camelSplit(name) {
+    const tokens = name
+        .replaceAll(/([a-z])([A-Z])/g, '$1 $2')
+        .toLowerCase()
+        .split(' ');
+    // unArchive → "unarchive", one verb.
+    const merged = [];
+    for (let i = 0; i < tokens.length; i++) {
+        if (tokens[i] === 'un' && tokens[i + 1]) {
+            merged.push('un' + tokens[++i]);
+        }
+        else {
+            merged.push(tokens[i]);
+        }
+    }
+    return merged;
+}
+export { camelSplit };
+function singular(word) {
+    if (word.endsWith('ies'))
+        return word.slice(0, -3) + 'y';
+    if (word.endsWith('s') && !word.endsWith('ss'))
+        return word.slice(0, -1);
+    return word;
+}
+/**
+ * Match user words against SDK method names. "aggregates get" prefers
+ * getDatabaseAggregates (plural = list); "aggregate get" (or a positional id)
+ * prefers getDatabaseAggregate.
+ */
+export function matchMethods(methods, words, moduleName) {
+    const userWords = words.map((w) => w.toLowerCase().replaceAll('-', ''));
+    const moduleTokens = new Set(camelSplit(moduleName));
+    const matches = [];
+    for (const method of methods) {
+        // Exact camelCase method name typed by the user.
+        if (words.length === 1 && words[0] === method)
+            return [{ method, exact: 99, extra: 0 }];
+        const tokens = camelSplit(method);
+        let exact = 0;
+        let ok = true;
+        for (const w of userWords) {
+            if (tokens.includes(w)) {
+                exact++;
+            }
+            else if (tokens.some((t) => singular(t) === singular(w))) {
+                // singular/plural tolerant match
+            }
+            else {
+                ok = false;
+                break;
+            }
+        }
+        if (!ok)
+            continue;
+        const extra = tokens.filter((t) => !moduleTokens.has(t) && !userWords.some((w) => singular(w) === singular(t))).length;
+        matches.push({ method, exact, extra });
+    }
+    matches.sort((a, b) => b.exact - a.exact || a.extra - b.extra || a.method.localeCompare(b.method));
+    // Keep only the best-scoring group so callers can detect ambiguity.
+    if (matches.length > 1) {
+        const best = matches[0];
+        return matches.filter((m) => m.exact === best.exact && m.extra === best.extra);
+    }
+    return matches;
+}
+const DESTRUCTIVE_VERBS = new Set(['delete', 'remove', 'clean', 'regenerate', 'rotate', 'stop']);
+export function isDestructive(method) {
+    return DESTRUCTIVE_VERBS.has(camelSplit(method)[0]);
+}
+/**
+ * Module aliases so daily language works: `norbix hub db ...`, and
+ * `norbix hub email templates get` routes into the notifications module
+ * with "email" injected as a matching word.
+ */
+export const MODULE_ALIASES = {
+    db: { module: 'database' },
+    email: { module: 'notifications', injectWord: 'email' },
+    envs: { module: 'environments' },
+    fs: { module: 'files' },
+    push: { module: 'notifications', injectWord: 'push' },
+    sms: { module: 'notifications', injectWord: 'sms' },
+};

package/dist/lib/namespace-command.js

@@ -0,0 +1,148 @@
+import { confirm } from '@inquirer/prompts';
+import { Norbix } from '@norbix.ai/ts';
+import { BaseCommand } from '../base.js';
+import { MODULE_ALIASES, camelSplit, isDestructive, matchMethods, parseArgv } from './dispatch.js';
+/**
+ * Shared engine for `norbix hub ...` and `norbix api ...` — resolves the
+ * module and method from plain words and calls the SDK.
+ */
+export class NamespaceCommand extends BaseCommand {
+    /**
+     * oclif rejects unknown flags even in non-strict mode, but here unknown
+     * flags ARE the request fields (--schemaId ...). Split the raw argv:
+     * known global flags go to oclif, everything else goes to the dispatcher.
+     */
+    splitArgv() {
+        const VALUE_FLAGS = new Set(['--project', '--env', '--region', '--api-key', '--account', '--profile']);
+        const BOOL_FLAGS = new Set(['--json']);
+        const flagArgv = [];
+        const rest = [];
+        let help = false;
+        const raw = this.argv;
+        for (let i = 0; i < raw.length; i++) {
+            const token = raw[i];
+            const name = token.split('=')[0];
+            if (name === '--help' || name === '-h' || name === '--scope-help') {
+                help = true;
+            }
+            else if (VALUE_FLAGS.has(name)) {
+                flagArgv.push(token);
+                if (!token.includes('=') && raw[i + 1] !== undefined)
+                    flagArgv.push(raw[++i]);
+            }
+            else if (BOOL_FLAGS.has(name)) {
+                flagArgv.push(token);
+            }
+            else {
+                rest.push(token);
+            }
+        }
+        return { flagArgv, rest, help };
+    }
+    /** camelCase method → the plain-word form of this CLI (noun first, verb last). */
+    wordForm(method, moduleName, hide = new Set()) {
+        const tokens = camelSplit(method);
+        const moduleTokens = new Set(camelSplit(moduleName));
+        const [verb, ...rest] = tokens;
+        const nouns = rest.filter((t) => !moduleTokens.has(t) && !hide.has(t));
+        return [...nouns, verb].join(' ');
+    }
+    /** Scoped help: everything callable under `norbix {target} {module} {words...}`. */
+    scopeHelp(moduleWord, moduleName, methods, words, labelWords = words, hideWord) {
+        const scoped = words.length === 0
+            ? methods
+            : methods.filter((m) => matchMethods([m], words, moduleName).length > 0);
+        // The alias word (email/sms/push) is implied by the module word — hide it
+        // from the printed forms so `hub email ...` reads naturally.
+        const hide = new Set(hideWord ? [hideWord] : []);
+        const list = scoped.length > 0 ? scoped : methods;
+        const rows = list
+            .map((m) => {
+            const form = this.wordForm(m, moduleName, hide);
+            const marker = isDestructive(m) ? '  (asks confirmation)' : '';
+            return `  norbix ${this.target} ${moduleWord} ${form}${marker}`;
+        })
+            .join('\n');
+        this.print(`Commands in scope "${this.target} ${moduleWord}${labelWords.length > 0 ? ' ' + labelWords.join(' ') : ''}"` +
+            `${scoped.length === 0 ? ' (no exact scope match — showing the whole module)' : ''}:\n\n${rows}\n\n` +
+            `Add an ID as a plain value and request fields as flags:\n` +
+            `  norbix ${this.target} ${moduleWord} ${this.wordForm(list[0], moduleName, hide)} <id> --someField value\n\n` +
+            `Useful extras: --dry-run (preview the call), --yes (skip confirmation),\n` +
+            `--json (machine output), --profile/--env/--region/--project (context).`);
+        return { scope: `${this.target}.${moduleName}`, commands: list.map((m) => this.wordForm(m, moduleName, hide)) };
+    }
+    async dispatch(argv, flags, help = false) {
+        const parsed = parseArgv(argv);
+        const [moduleWord, ...restWords] = parsed.words;
+        // Introspection client — never used for requests.
+        const probe = new Norbix({ projectId: 'introspect', apiKey: 'introspect' }, { envSource: {} });
+        const namespace = probe[this.target];
+        const moduleNames = Object.keys(namespace).sort();
+        if (!moduleWord) {
+            this.print(`Usage: norbix ${this.target} <module> <words...> [id] [--field value]\n\nModules:\n  ${moduleNames.join('\n  ')}\n\n` +
+                `Get help at any level:\n  norbix ${this.target} <module> --help\n  norbix ${this.target} <module> <words...> --help\n\n` +
+                `Example: norbix ${this.target} database aggregates delete maggr_123 --schemaId sch_456`);
+            return { modules: moduleNames };
+        }
+        const alias = MODULE_ALIASES[moduleWord];
+        const moduleName = alias && namespace[alias.module] ? alias.module : moduleWord;
+        const sdkModule = namespace[moduleName];
+        if (!sdkModule) {
+            this.error(`Unknown module "${moduleWord}" on ${this.target}.\nAvailable: ${moduleNames.join(', ')}`);
+        }
+        // Only real SDK methods — internals like `transport` are not callable.
+        const methods = Object.keys(sdkModule)
+            .filter((k) => typeof sdkModule[k] === 'function')
+            .sort();
+        if (help) {
+            const injected = alias?.injectWord && moduleName !== moduleWord ? alias.injectWord : undefined;
+            const helpWords = injected ? [injected, ...restWords] : [...restWords];
+            return this.scopeHelp(moduleWord, moduleName, methods, helpWords, restWords, injected);
+        }
+        if (restWords.length === 0 && parsed.positionals.length === 0) {
+            this.print(`Methods of ${this.target}.${moduleName}:\n  ${methods.join('\n  ')}\n\nCall one with plain words, e.g.:\n  norbix ${this.target} ${moduleWord} aggregates get\n  norbix ${this.target} ${moduleWord} aggregates delete <id>`);
+            return { module: moduleName, methods };
+        }
+        const words = [...restWords];
+        if (alias?.injectWord && moduleName !== moduleWord)
+            words.unshift(alias.injectWord);
+        const matches = matchMethods(methods, words, moduleName);
+        if (matches.length === 0) {
+            // Show only methods sharing at least one word — the full list can be 100+.
+            const lower = words.map((w) => w.toLowerCase().replace(/s$/, ''));
+            const related = methods.filter((m) => lower.some((w) => m.toLowerCase().includes(w)));
+            const shown = (related.length > 0 ? related : methods).slice(0, 25);
+            this.error(`No ${this.target}.${moduleName} method matches "${words.join(' ')}".\n` +
+                `${related.length > 0 ? 'Close methods' : 'Methods'}:\n  ${shown.join('\n  ')}` +
+                `${shown.length < methods.length ? `\n  … run \`norbix ${this.target} ${moduleWord}\` for the full list` : ''}`);
+        }
+        if (matches.length > 1) {
+            this.error(`"${words.join(' ')}" is ambiguous — did you mean:\n  ${matches.map((m) => m.method).join('\n  ')}\nAdd a word (e.g. the verb) to be specific.`);
+        }
+        const method = matches[0].method;
+        const request = { ...parsed.fields };
+        if (parsed.positionals.length > 0 && request.id === undefined) {
+            request.id = parsed.positionals[0];
+            if (parsed.positionals.length > 1) {
+                this.error(`Only one positional value is allowed (became "id"). Pass the rest as flags, e.g. --schemaId ${parsed.positionals[1]}`);
+            }
+        }
+        if (parsed.dryRun) {
+            this.print({ wouldCall: `${this.target}.${moduleName}.${method}`, request });
+            return { method: `${this.target}.${moduleName}.${method}`, request, dryRun: true };
+        }
+        if (isDestructive(method) && !parsed.yes && process.stdout.isTTY) {
+            const ok = await confirm({
+                message: `Run ${method}(${JSON.stringify(request)})?`,
+                default: false,
+            });
+            if (!ok)
+                return this.print('Cancelled.');
+        }
+        const client = this.client(flags);
+        const liveModule = client[this.target][moduleName];
+        const res = await liveModule[method](request);
+        this.print(res);
+        return res;
+    }
+}

package/dist/lib/profiles.js

@@ -0,0 +1,138 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Profile storage — one INI file, AWS-style but simpler:
+ *
+ *   ~/.norbix/config          (mode 600, secrets + settings together)
+ *   ---------------------------------------------------------------
+ *   [default]
+ *   api_key = nbk_live_...
+ *   project_id = 5f1a...
+ *
+ *   [fitskin-prod]
+ *   api_key = nbk_live_...
+ *   project_id = 64ff...
+ *   account_id = ...
+ *   env = TEST
+ *   api_url = https://api.norbix.ai
+ *   hub_url = https://hub.norbix.ai
+ *
+ * Browser/password login sessions live in ~/.norbix/session.json —
+ * separate on purpose: sessions rotate and are machine-managed, the
+ * config file is edited by people.
+ */
+export const NORBIX_DIR = join(homedir(), '.norbix');
+export const PROFILES_PATH = join(NORBIX_DIR, 'config');
+export const SESSION_PATH = join(NORBIX_DIR, 'session.json');
+export const DEFAULT_API_URL = 'https://api.norbix.ai';
+export const DEFAULT_HUB_URL = 'https://hub.norbix.ai';
+export const PROFILE_KEYS = [
+    'api_key',
+    'project_id',
+    'account_id',
+    'env',
+    'region',
+    'api_url',
+    'hub_url',
+    'files_integration_id',
+];
+// ---------- tiny INI reader/writer (no dependency) ----------
+export function parseIni(text) {
+    const out = {};
+    let section = 'default';
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#') || line.startsWith(';'))
+            continue;
+        const sec = line.match(/^\[(.+)\]$/);
+        if (sec) {
+            section = sec[1].trim();
+            out[section] ??= {};
+            continue;
+        }
+        const eq = line.indexOf('=');
+        if (eq > 0) {
+            out[section] ??= {};
+            out[section][line.slice(0, eq).trim()] = line.slice(eq + 1).trim();
+        }
+    }
+    return out;
+}
+export function stringifyIni(data) {
+    const parts = [];
+    for (const [section, values] of Object.entries(data)) {
+        parts.push(`[${section}]`);
+        for (const [k, v] of Object.entries(values)) {
+            if (v !== undefined && v !== '')
+                parts.push(`${k} = ${v}`);
+        }
+        parts.push('');
+    }
+    return parts.join('\n');
+}
+// ---------- profiles ----------
+export function readProfiles() {
+    try {
+        return parseIni(readFileSync(PROFILES_PATH, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeProfile(name, profile) {
+    mkdirSync(NORBIX_DIR, { recursive: true });
+    const all = readProfiles();
+    const clean = Object.fromEntries(Object.entries(profile).filter(([, v]) => v !== undefined && v !== ''));
+    all[name] = clean;
+    writeFileSync(PROFILES_PATH, stringifyIni(all), { mode: 0o600 });
+    try {
+        chmodSync(PROFILES_PATH, 0o600); // enforce even when the file pre-existed
+    }
+    catch {
+        /* windows: no-op */
+    }
+}
+export function deleteProfile(name) {
+    const all = readProfiles();
+    if (!(name in all))
+        return false;
+    delete all[name];
+    mkdirSync(NORBIX_DIR, { recursive: true });
+    writeFileSync(PROFILES_PATH, stringifyIni(all), { mode: 0o600 });
+    return true;
+}
+export function readSession() {
+    try {
+        const s = JSON.parse(readFileSync(SESSION_PATH, 'utf8'));
+        return s.bearerToken ? s : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeSession(session) {
+    mkdirSync(NORBIX_DIR, { recursive: true });
+    writeFileSync(SESSION_PATH, JSON.stringify(session, null, 2) + '\n', { mode: 0o600 });
+}
+export function clearSession() {
+    if (existsSync(SESSION_PATH))
+        unlinkSync(SESSION_PATH);
+}
+/** Decode a JWT `exp` claim (ms). Returns undefined when not decodable. */
+export function jwtExpiryMs(token) {
+    try {
+        const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString());
+        return typeof payload.exp === 'number' ? payload.exp * 1000 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A session is usable when it has a token that is not (provably) expired. */
+export function isSessionValid(session) {
+    if (!session?.bearerToken)
+        return false;
+    const exp = jwtExpiryMs(session.bearerToken);
+    return exp === undefined || exp > Date.now() + 30_000;
+}