@zuvo/cli 0.1.0

package/README.md

@@ -0,0 +1,15 @@
+# @zuvo/cli
+
+Login, link a project, deploy Edge Functions, and `db push` against [Zuvo](https://studio.zuvodev.com).
+
+```bash
+npm i -g @zuvo/cli
+zuvo login
+zuvo projects list
+zuvo link --project <ref>
+zuvo functions deploy
+zuvo db push
+```
+
+Token: Studio → Account → Access Tokens, or `zuvo login --token zpat_…`.  
+API override: `ZUVO_API_URL` / `--api-url` (default `https://api.zuvodev.com`).

package/bin/zuvo.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js'

package/dist/api.js

@@ -0,0 +1,47 @@
+import { loadAccessToken } from './config.js';
+export class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'ApiError';
+    }
+}
+export async function apiRequest(apiUrl, method, pathname, opts = {}) {
+    const token = opts.token ?? (await loadAccessToken());
+    const url = new URL(pathname.replace(/^\//, ''), `${apiUrl}/`);
+    for (const [key, value] of Object.entries(opts.query || {})) {
+        if (value)
+            url.searchParams.set(key, value);
+    }
+    const headers = {
+        authorization: `Bearer ${token}`,
+        accept: 'application/json',
+    };
+    let body;
+    if (opts.form) {
+        body = opts.form;
+    }
+    else if (opts.json !== undefined) {
+        headers['content-type'] = 'application/json';
+        body = JSON.stringify(opts.json);
+    }
+    const response = await fetch(url, { method, headers, body });
+    const text = await response.text();
+    let parsed = text;
+    if (text) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = text;
+        }
+    }
+    if (!response.ok) {
+        const message = parsed && typeof parsed === 'object' && parsed !== null && 'message' in parsed
+            ? String(parsed.message)
+            : text || `HTTP ${response.status}`;
+        throw new ApiError(response.status, message);
+    }
+    return parsed;
+}

package/dist/config.js

@@ -0,0 +1,101 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+export const DEFAULT_API_URL = 'https://api.zuvodev.com';
+export const DEFAULT_STUDIO_URL = 'https://studio.zuvodev.com';
+const TOKEN_RE = /^zpat_[0-9a-fA-F]{64}$/;
+export function homeDir() {
+    return process.env.ZUVO_HOME || path.join(homedir(), '.zuvo');
+}
+export function tokenPath() {
+    return path.join(homeDir(), 'access-token');
+}
+export function apiUrlFromEnv(flag) {
+    return (flag || process.env.ZUVO_API_URL || DEFAULT_API_URL).replace(/\/$/, '');
+}
+export function studioUrlFromEnv(flag) {
+    return (flag || process.env.ZUVO_STUDIO_URL || DEFAULT_STUDIO_URL).replace(/\/$/, '');
+}
+export function isAccessToken(value) {
+    return TOKEN_RE.test(value.trim());
+}
+export async function saveAccessToken(token) {
+    const dir = homeDir();
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await writeFile(tokenPath(), `${token.trim()}\n`, { mode: 0o600 });
+}
+export async function deleteAccessToken() {
+    try {
+        await rm(tokenPath());
+        return true;
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+export async function loadAccessToken() {
+    const fromEnv = (process.env.ZUVO_ACCESS_TOKEN || '').trim();
+    if (fromEnv)
+        return fromEnv;
+    try {
+        return (await readFile(tokenPath(), 'utf8')).trim();
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ENOENT') {
+            throw new Error('Not logged in. Run `zuvo login` or set ZUVO_ACCESS_TOKEN.');
+        }
+        throw error;
+    }
+}
+function parseTomlRef(text) {
+    const match = text.match(/^\s*(?:project_id|project_ref)\s*=\s*["']([^"']+)["']\s*$/m);
+    return match?.[1] || null;
+}
+export async function loadLinkedRef(cwd = process.cwd()) {
+    const flag = process.env.ZUVO_PROJECT_REF?.trim();
+    if (flag)
+        return flag;
+    try {
+        const fromFile = (await readFile(path.join(cwd, '.zuvo', 'project-ref'), 'utf8')).trim();
+        if (fromFile)
+            return fromFile;
+    }
+    catch {
+        // fall through
+    }
+    try {
+        const toml = await readFile(path.join(cwd, 'zuvo.toml'), 'utf8');
+        return parseTomlRef(toml);
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveLinkedRef(ref, cwd = process.cwd()) {
+    const dir = path.join(cwd, '.zuvo');
+    await mkdir(dir, { recursive: true });
+    await writeFile(path.join(dir, 'project-ref'), `${ref}\n`, 'utf8');
+    const tomlPath = path.join(cwd, 'zuvo.toml');
+    try {
+        const existing = await readFile(tomlPath, 'utf8');
+        if (/^\s*(?:project_id|project_ref)\s*=/m.test(existing)) {
+            await writeFile(tomlPath, existing.replace(/^\s*(?:project_id|project_ref)\s*=\s*["'][^"']*["']\s*$/m, `project_id = "${ref}"`), 'utf8');
+            return;
+        }
+        await writeFile(tomlPath, `${existing.trimEnd()}\nproject_id = "${ref}"\n`, 'utf8');
+    }
+    catch {
+        await writeFile(tomlPath, `project_id = "${ref}"\n`, 'utf8');
+    }
+}
+export async function requireLinkedRef(cwd = process.cwd()) {
+    const ref = await loadLinkedRef(cwd);
+    if (!ref) {
+        throw new Error('No project linked. Run `zuvo link --project <ref>`.');
+    }
+    return ref;
+}

package/dist/crypto.js

@@ -0,0 +1,26 @@
+import { createDecipheriv, createECDH } from 'node:crypto';
+export function generateLoginKeyPair() {
+    const ecdh = createECDH('prime256v1');
+    ecdh.generateKeys();
+    return { ecdh, publicKeyHex: ecdh.getPublicKey('hex', 'uncompressed') };
+}
+/** Decrypt the Management API CLI login payload (AES-256-GCM, tag appended). */
+export function decryptCliAccessToken(ecdh, payload) {
+    const sharedSecret = ecdh.computeSecret(Buffer.from(payload.public_key, 'hex'));
+    const ciphertextHex = payload.access_token.slice(0, -32);
+    const authTagHex = payload.access_token.slice(-32);
+    const decipher = createDecipheriv('aes-256-gcm', sharedSecret, Buffer.from(payload.nonce, 'hex'));
+    decipher.setAuthTag(Buffer.from(authTagHex, 'hex'));
+    return Buffer.concat([
+        decipher.update(Buffer.from(ciphertextHex, 'hex')),
+        decipher.final(),
+    ]).toString('utf8');
+}
+export function defaultTokenName() {
+    const ts = Math.floor(Date.now() / 1000);
+    const user = process.env.USER || process.env.USERNAME || '';
+    const host = process.env.HOSTNAME || '';
+    if (user && host)
+        return `cli_${user}@${host}_${ts}`;
+    return `cli_${ts}`;
+}

package/dist/functions.js

@@ -0,0 +1,72 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+async function walkFiles(dir, prefix = '') {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const out = [];
+    for (const ent of entries) {
+        if (ent.name.startsWith('.'))
+            continue;
+        const rel = prefix ? `${prefix}/${ent.name}` : ent.name;
+        const full = path.join(dir, ent.name);
+        if (ent.isDirectory()) {
+            out.push(...(await walkFiles(full, rel)));
+        }
+        else if (ent.isFile()) {
+            out.push({ name: rel, content: await readFile(full, 'utf8') });
+        }
+    }
+    return out;
+}
+export async function listFunctionSlugs(cwd = process.cwd()) {
+    const root = path.join(cwd, 'supabase', 'functions');
+    try {
+        const entries = await readdir(root, { withFileTypes: true });
+        return entries
+            .filter((ent) => ent.isDirectory() && !ent.name.startsWith('_') && !ent.name.startsWith('.'))
+            .map((ent) => ent.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+export async function loadFunctionBundle(cwd, slug) {
+    const dir = path.join(cwd, 'supabase', 'functions', slug);
+    const info = await stat(dir).catch(() => null);
+    if (!info?.isDirectory()) {
+        throw new Error(`Function directory not found: supabase/functions/${slug}`);
+    }
+    const files = await walkFiles(dir);
+    if (!files.length)
+        throw new Error(`No files in supabase/functions/${slug}`);
+    let verifyJwt = true;
+    const config = files.find((f) => f.name === 'config.toml' || f.name.endsWith('/config.toml'));
+    if (config) {
+        const match = config.content.match(/^\s*verify_jwt\s*=\s*(true|false)\s*$/m);
+        if (match)
+            verifyJwt = match[1] === 'true';
+    }
+    const entry = files.find((f) => f.name === 'index.ts') ||
+        files.find((f) => f.name.endsWith('/index.ts')) ||
+        files[0];
+    return {
+        slug,
+        name: slug,
+        verifyJwt,
+        entrypointPath: entry.name,
+        files: files.filter((f) => f.name !== 'config.toml' && !f.name.endsWith('/config.toml')),
+    };
+}
+export function encodeFunctionForm(input) {
+    const form = new FormData();
+    form.set('metadata', JSON.stringify({
+        name: input.name,
+        slug: input.slug,
+        verify_jwt: input.verifyJwt,
+        entrypoint_path: input.entrypointPath,
+    }));
+    for (const file of input.files) {
+        form.append('file', new Blob([file.content], { type: 'text/plain' }), file.name);
+    }
+    return form;
+}

package/dist/index.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { apiRequest, ApiError } from './api.js';
+import { apiUrlFromEnv, deleteAccessToken, isAccessToken, requireLinkedRef, saveLinkedRef, } from './config.js';
+import { encodeFunctionForm, listFunctionSlugs, loadFunctionBundle } from './functions.js';
+import { loginBrowser, loginWithToken } from './login.js';
+import { loadLocalMigrations, pendingMigrations } from './migrations.js';
+function usage() {
+    return `Usage: zuvo <command>
+
+Commands:
+  login [--token <zpat_…>] [--name <token-name>] [--no-browser]
+  logout
+  projects list
+  link --project <ref>
+  functions list
+  functions deploy [slug]
+  db push
+
+Global:
+  --api-url <url>     Default https://api.zuvodev.com (or ZUVO_API_URL)
+`;
+}
+function fail(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exit(1);
+}
+function parseGlobal(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: {
+            'api-url': { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+        },
+        allowPositionals: true,
+        strict: false,
+    });
+    return {
+        apiUrl: apiUrlFromEnv(typeof values['api-url'] === 'string' ? values['api-url'] : undefined),
+        help: Boolean(values.help),
+        positionals,
+    };
+}
+async function cmdLogin(apiUrl, argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            token: { type: 'string' },
+            name: { type: 'string' },
+            'no-browser': { type: 'boolean' },
+            'api-url': { type: 'string' },
+        },
+        allowPositionals: true,
+        strict: false,
+    });
+    const token = typeof values.token === 'string' ? values.token : '';
+    if (token) {
+        await loginWithToken(token);
+    }
+    else if (!process.stdin.isTTY) {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        const piped = Buffer.concat(chunks).toString('utf8').trim();
+        if (!piped || !isAccessToken(piped)) {
+            throw new Error('Non-interactive login requires --token or a zpat_ token on stdin.');
+        }
+        await loginWithToken(piped);
+    }
+    else {
+        await loginBrowser({
+            apiUrl,
+            tokenName: typeof values.name === 'string' ? values.name : undefined,
+            openBrowser: values['no-browser'] !== true,
+        });
+    }
+    console.log('You are now logged in. Happy coding!');
+}
+async function cmdLogout() {
+    const removed = await deleteAccessToken();
+    if (!removed) {
+        console.error('You were not logged in, nothing to do.');
+        return;
+    }
+    console.log('Logged out.');
+}
+async function cmdProjectsList(apiUrl) {
+    const projects = await apiRequest(apiUrl, 'GET', '/v1/projects');
+    if (!projects.length) {
+        console.log('No projects.');
+        return;
+    }
+    for (const project of projects) {
+        const ref = project.ref || project.id || '';
+        console.log([ref, project.name || '', project.region || '', project.status || '']
+            .filter(Boolean)
+            .join('\t'));
+    }
+}
+async function cmdLink(apiUrl, argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            project: { type: 'string' },
+            'api-url': { type: 'string' },
+        },
+        allowPositionals: true,
+        strict: false,
+    });
+    const ref = typeof values.project === 'string' ? values.project.trim() : '';
+    if (!ref)
+        throw new Error('Missing --project <ref>');
+    const project = await apiRequest(apiUrl, 'GET', `/v1/projects/${ref}`);
+    const linked = project.ref || project.id || ref;
+    await saveLinkedRef(linked);
+    console.log(`Linked to project ${linked}`);
+}
+async function cmdFunctionsList(apiUrl) {
+    const ref = await requireLinkedRef();
+    const fns = await apiRequest(apiUrl, 'GET', `/v1/projects/${ref}/functions`);
+    if (!Array.isArray(fns) || !fns.length) {
+        console.log('No functions.');
+        return;
+    }
+    for (const fn of fns) {
+        console.log([fn.slug || fn.name, fn.status, fn.version != null ? `v${fn.version}` : '']
+            .filter(Boolean)
+            .join('\t'));
+    }
+}
+async function deployOne(apiUrl, ref, slug) {
+    const bundle = await loadFunctionBundle(process.cwd(), slug);
+    const form = encodeFunctionForm(bundle);
+    const meta = await apiRequest(apiUrl, 'POST', `/v1/projects/${ref}/functions/deploy`, { form, query: { slug: bundle.slug } });
+    console.log(`Deployed ${meta.slug || bundle.slug}${meta.version != null ? ` (v${meta.version})` : ''}`);
+}
+async function cmdFunctionsDeploy(apiUrl, argv) {
+    const ref = await requireLinkedRef();
+    const slug = argv.find((arg) => !arg.startsWith('-'));
+    const slugs = slug ? [slug] : await listFunctionSlugs();
+    if (!slugs.length) {
+        throw new Error('No functions to deploy (expected supabase/functions/<slug>).');
+    }
+    for (const name of slugs) {
+        await deployOne(apiUrl, ref, name);
+    }
+}
+async function cmdDbPush(apiUrl) {
+    const ref = await requireLinkedRef();
+    const local = await loadLocalMigrations();
+    if (!local.length) {
+        console.log('No migrations in supabase/migrations.');
+        return;
+    }
+    const applied = await apiRequest(apiUrl, 'GET', `/v1/projects/${ref}/database/migrations`);
+    const pending = pendingMigrations(local, Array.isArray(applied) ? applied : []);
+    if (!pending.length) {
+        console.log('Remote database is up to date.');
+        return;
+    }
+    for (const migration of pending) {
+        await apiRequest(apiUrl, 'PUT', `/v1/projects/${ref}/database/migrations`, {
+            json: {
+                version: migration.version,
+                name: migration.name,
+                query: migration.query,
+            },
+        });
+        console.log(`Applied ${migration.filename}`);
+    }
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const global = parseGlobal(argv);
+    if (global.help || global.positionals[0] === 'help') {
+        console.log(usage());
+        return;
+    }
+    const [command, sub, ...rest] = global.positionals;
+    const apiUrl = global.apiUrl;
+    try {
+        if (command === 'login')
+            await cmdLogin(apiUrl, argv);
+        else if (command === 'logout')
+            await cmdLogout();
+        else if (command === 'projects' && (sub === 'list' || !sub))
+            await cmdProjectsList(apiUrl);
+        else if (command === 'link')
+            await cmdLink(apiUrl, argv);
+        else if (command === 'functions' && sub === 'list')
+            await cmdFunctionsList(apiUrl);
+        else if (command === 'functions' && sub === 'deploy')
+            await cmdFunctionsDeploy(apiUrl, rest);
+        else if (command === 'db' && sub === 'push')
+            await cmdDbPush(apiUrl);
+        else {
+            console.error(usage());
+            process.exit(command ? 1 : 0);
+        }
+    }
+    catch (error) {
+        if (error instanceof ApiError && error.status === 403) {
+            fail('Forbidden. Deploy and db push require owner, admin, or developer.');
+        }
+        fail(error);
+    }
+}
+void main();

package/dist/login.js

@@ -0,0 +1,88 @@
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { promisify } from 'node:util';
+import { apiRequest } from './api.js';
+import { isAccessToken, saveAccessToken, studioUrlFromEnv, } from './config.js';
+import { decryptCliAccessToken, defaultTokenName, generateLoginKeyPair, } from './crypto.js';
+const execFileAsync = promisify(execFile);
+const POLL_MS = 2000;
+const POLL_TIMEOUT_MS = 5 * 60 * 1000;
+async function openBrowser(url) {
+    const platform = process.platform;
+    if (platform === 'darwin') {
+        await execFileAsync('open', [url]);
+        return;
+    }
+    if (platform === 'win32') {
+        await execFileAsync('cmd', ['/c', 'start', '', url]);
+        return;
+    }
+    await execFileAsync('xdg-open', [url]);
+}
+async function promptDeviceCode() {
+    const rl = createInterface({ input, output });
+    try {
+        const raw = await rl.question('Enter the 8-character code shown in the browser: ');
+        return raw.trim().toLowerCase();
+    }
+    finally {
+        rl.close();
+    }
+}
+async function pollSession(apiUrl, sessionId, deviceCode) {
+    const started = Date.now();
+    let lastError = 'timed out waiting for login';
+    while (Date.now() - started < POLL_TIMEOUT_MS) {
+        const url = `${apiUrl}/platform/cli/login/${sessionId}?device_code=${encodeURIComponent(deviceCode)}`;
+        try {
+            const response = await fetch(url, { headers: { accept: 'application/json' } });
+            if (response.status === 200) {
+                return (await response.json());
+            }
+            lastError = `HTTP ${response.status}`;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+        }
+        await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+    }
+    throw new Error(`Login did not complete (${lastError})`);
+}
+export async function loginWithToken(token) {
+    const trimmed = token.trim();
+    if (!isAccessToken(trimmed)) {
+        throw new Error('Invalid access token format. Expected zpat_ followed by 64 hex characters.');
+    }
+    await saveAccessToken(trimmed);
+}
+export async function loginBrowser(opts) {
+    const { ecdh, publicKeyHex } = generateLoginKeyPair();
+    const sessionId = randomUUID();
+    const tokenName = opts.tokenName || defaultTokenName();
+    const studio = studioUrlFromEnv(opts.studioUrl);
+    const loginUrl = `${studio}/cli/login?session_id=${encodeURIComponent(sessionId)}` +
+        `&public_key=${encodeURIComponent(publicKeyHex)}` +
+        `&token_name=${encodeURIComponent(tokenName)}`;
+    console.log('Open this URL to authorize the CLI:');
+    console.log(loginUrl);
+    if (opts.openBrowser) {
+        try {
+            await openBrowser(loginUrl);
+        }
+        catch {
+            console.error('Could not open a browser automatically.');
+        }
+    }
+    const deviceCode = await promptDeviceCode();
+    if (!/^[0-9a-f]{8}$/.test(deviceCode)) {
+        throw new Error('Device code must be the first 8 characters shown in Studio.');
+    }
+    const payload = await pollSession(opts.apiUrl, sessionId, deviceCode);
+    const token = decryptCliAccessToken(ecdh, payload);
+    await loginWithToken(token);
+}
+export async function verifyToken(apiUrl) {
+    return apiRequest(apiUrl, 'GET', '/v1/projects');
+}

package/dist/migrations.js

@@ -0,0 +1,38 @@
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+const FILE_RE = /^(\d+)(?:_(.+))?\.sql$/i;
+export function parseMigrationFilename(filename) {
+    const base = filename.split(/[/\\]/).pop() || filename;
+    const match = base.match(FILE_RE);
+    if (!match)
+        return null;
+    return {
+        version: match[1],
+        name: (match[2] || base.replace(/\.sql$/i, '')).replace(/-/g, '_'),
+    };
+}
+export async function loadLocalMigrations(cwd = process.cwd()) {
+    const dir = path.join(cwd, 'supabase', 'migrations');
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const filename of names.sort()) {
+        const parsed = parseMigrationFilename(filename);
+        if (!parsed)
+            continue;
+        const query = await readFile(path.join(dir, filename), 'utf8');
+        if (!query.trim())
+            continue;
+        out.push({ ...parsed, filename, query });
+    }
+    return out;
+}
+export function pendingMigrations(local, applied) {
+    const have = new Set(applied.map((row) => row.version));
+    return local.filter((row) => !have.has(row.version));
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@zuvo/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Zuvo CLI — login, link, functions deploy, and db push",
+  "license": "MIT",
+  "bin": {
+    "zuvo": "bin/zuvo.js"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://studio.zuvodev.com",
+  "keywords": [
+    "zuvo",
+    "cli",
+    "baas",
+    "supabase"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "NODE_ENV=test node --import tsx --test src/**/*.test.ts"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsx": "^4.20.3",
+    "typescript": "^5"
+  }
+}