@celsian/vura-cli 0.5.2 → 0.5.4

package/dist/commands/deploy.js

@@ -14,9 +14,8 @@
  */
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
-const DEFAULT_API_URL = 'https://api.vura.io';
+import { resolveApiUrl, resolveProjectId, resolveToken } from '../vura-client.js';
 function parseFlags(args) {
     const flags = { production: false };
     for (let i = 0; i < args.length; i++) {
@@ -42,38 +41,6 @@ function parseFlags(args) {
     }
     return flags;
 }
-/** Home directory, honoring HOME/USERPROFILE overrides (e.g. in tests). */
-function resolveHome() {
-    return process.env.HOME || process.env.USERPROFILE || homedir();
-}
-async function resolveToken(flag) {
-    if (flag)
-        return flag;
-    if (process.env.VURA_TOKEN)
-        return process.env.VURA_TOKEN;
-    try {
-        const raw = await readFile(join(resolveHome(), '.vura', 'credentials'), 'utf-8');
-        const creds = JSON.parse(raw);
-        return creds.token ?? null;
-    }
-    catch {
-        return null;
-    }
-}
-async function resolveProjectId(flag, projectRoot) {
-    if (flag)
-        return flag;
-    if (process.env.VURA_PROJECT_ID)
-        return process.env.VURA_PROJECT_ID;
-    try {
-        const raw = await readFile(join(projectRoot, '.vura', 'project.json'), 'utf-8');
-        const link = JSON.parse(raw);
-        return link.projectId ?? null;
-    }
-    catch {
-        return null;
-    }
-}
 export async function deployCommand(args) {
     const projectRoot = process.cwd();
     const flags = parseFlags(args);
@@ -81,7 +48,7 @@ export async function deployCommand(args) {
     // 1. Resolve authentication.
     const token = await resolveToken(flags.token);
     if (!token) {
-        console.error('  Not authenticated. Set VURA_TOKEN, pass --token <token>, or sign in so ~/.vura/credentials exists.');
+        console.error('  Not authenticated. Run `vura login`, set VURA_TOKEN, or pass --token <token>.');
         process.exitCode = 1;
         return;
     }
@@ -89,6 +56,7 @@ export async function deployCommand(args) {
     const projectId = await resolveProjectId(flags.projectId, projectRoot);
     if (!projectId) {
         console.error('  Project not linked. Set VURA_PROJECT_ID, pass --project-id <id>, or create .vura/project.json.');
+        console.error('  Run `vura teams list` to find a team, then `vura projects create <name> --team <id-or-slug>`.');
         process.exitCode = 1;
         return;
     }
@@ -100,7 +68,7 @@ export async function deployCommand(args) {
         process.exitCode = 1;
         return;
     }
-    const apiUrl = flags.apiUrl || process.env.VURA_API_URL || DEFAULT_API_URL;
+    const apiUrl = resolveApiUrl(flags.apiUrl);
     // Attach the built manifest so the platform can classify routes without
     // re-scanning the artifact.
     let manifest;
@@ -117,7 +85,7 @@ export async function deployCommand(args) {
     }
     catch {
         console.error('  Managed Vura deploy support is not installed in this CLI package.');
-        console.error('  The Vura Platform adapter is closed-alpha; use the Vura Platform CLI bundle or self-host adapters until access is granted.');
+        console.error('  Install it with: npm install @celsian/vura-adapter-vura');
         process.exitCode = 1;
         return;
     }

package/dist/commands/dev.js

@@ -263,7 +263,7 @@ export async function startStandaloneServer(manifest, opts) {
         catch { /* not installed — keep default */ }
         const result = await esbuild({
             stdin: {
-                contents: generateClientPageEntry(`./${basename(absPath)}`, page.mode),
+                contents: generateClientPageEntry(`./${basename(absPath)}`, page.mode, { dev: true }),
                 resolveDir: dirname(absPath),
                 sourcefile: '__vura-client-entry__.js',
                 loader: 'js',

package/dist/commands/login.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `vura login` — authenticate the CLI against the Vura Platform.
+ *
+ * Two modes:
+ *   vura login                 Interactive email/password prompt (POST /v1/auth/login)
+ *   vura login --token <t>     Paste an existing token directly ("paste-token" mode)
+ *
+ * Either way, credentials land in ~/.vura/credentials at mode 0600 — the same
+ * file `vura deploy` and `@celsian/vura-adapter-vura` already read (see
+ * `vura-client.ts`), so a successful `vura login` is immediately usable by
+ * every other command without extra configuration.
+ *
+ * Flags:
+ *   --token <t>      Store this token directly instead of prompting for email/password.
+ *                     The token is verified against GET /v1/auth/me before being saved.
+ *   --api-url <url>  API base URL (else VURA_API_URL, else https://api.vura.io)
+ */
+interface LoginPrompts {
+    /** Prompt for plain text input (echoed as typed). */
+    prompt: (question: string) => Promise<string>;
+    /** Prompt for a password (not echoed to the terminal). */
+    promptPassword: (question: string) => Promise<string>;
+}
+/**
+ * @param io Override the interactive prompt functions for testing. Defaults
+ *           to real stdin/stdout prompts.
+ */
+export declare function loginCommand(args: string[], io?: LoginPrompts): Promise<void>;
+export {};
+//# sourceMappingURL=login.d.ts.map

package/dist/commands/login.js

@@ -0,0 +1,155 @@
+/**
+ * `vura login` — authenticate the CLI against the Vura Platform.
+ *
+ * Two modes:
+ *   vura login                 Interactive email/password prompt (POST /v1/auth/login)
+ *   vura login --token <t>     Paste an existing token directly ("paste-token" mode)
+ *
+ * Either way, credentials land in ~/.vura/credentials at mode 0600 — the same
+ * file `vura deploy` and `@celsian/vura-adapter-vura` already read (see
+ * `vura-client.ts`), so a successful `vura login` is immediately usable by
+ * every other command without extra configuration.
+ *
+ * Flags:
+ *   --token <t>      Store this token directly instead of prompting for email/password.
+ *                     The token is verified against GET /v1/auth/me before being saved.
+ *   --api-url <url>  API base URL (else VURA_API_URL, else https://api.vura.io)
+ */
+import * as readline from 'node:readline';
+import { formatApiError, resolveApiUrl, vuraApiRequest, writeCredentials } from '../vura-client.js';
+const CTRL_C = String.fromCharCode(3);
+const CTRL_D = String.fromCharCode(4);
+const BACKSPACE = String.fromCharCode(127);
+function parseFlags(args) {
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        switch (args[i]) {
+            case '--token':
+                flags.token = args[++i];
+                break;
+            case '--api-url':
+                flags.apiUrl = args[++i];
+                break;
+            default:
+                // ignore unknown args (keeps house style: lenient flag parsing)
+                break;
+        }
+    }
+    return flags;
+}
+function prompt(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+/**
+ * Prompt for a password without echoing it to the terminal. Node has no
+ * built-in masked-input prompt, so this puts stdin in raw mode and renders
+ * `*` per keystroke itself, handling backspace and Ctrl-C/Ctrl-D directly.
+ * Requires a real TTY — callers must gate on `process.stdin.isTTY` first.
+ */
+function promptPassword(question) {
+    return new Promise((resolve) => {
+        const stdin = process.stdin;
+        process.stdout.write(question);
+        stdin.resume();
+        stdin.setRawMode?.(true);
+        stdin.setEncoding('utf8');
+        let password = '';
+        const onData = (chunk) => {
+            switch (chunk) {
+                case '\n':
+                case '\r':
+                case CTRL_D:
+                    stdin.setRawMode?.(false);
+                    stdin.pause();
+                    stdin.removeListener('data', onData);
+                    process.stdout.write('\n');
+                    resolve(password);
+                    break;
+                case CTRL_C:
+                    process.stdout.write('\n');
+                    process.exit(1);
+                    break;
+                case BACKSPACE:
+                case '\b':
+                    if (password.length > 0) {
+                        password = password.slice(0, -1);
+                        process.stdout.write('\b \b');
+                    }
+                    break;
+                default:
+                    password += chunk;
+                    process.stdout.write('*'.repeat(chunk.length));
+                    break;
+            }
+        };
+        stdin.on('data', onData);
+    });
+}
+const DEFAULT_PROMPTS = { prompt, promptPassword };
+/**
+ * @param io Override the interactive prompt functions for testing. Defaults
+ *           to real stdin/stdout prompts.
+ */
+export async function loginCommand(args, io = DEFAULT_PROMPTS) {
+    const flags = parseFlags(args);
+    const apiUrl = resolveApiUrl(flags.apiUrl);
+    console.log('\n  vura login\n');
+    if (flags.token) {
+        console.log(`  Verifying token against ${apiUrl}...`);
+        let email;
+        try {
+            const body = (await vuraApiRequest(apiUrl, '/v1/auth/me', { token: flags.token }));
+            email = body?.user?.email;
+        }
+        catch (err) {
+            console.error(`  ${formatApiError(err)}`);
+            process.exitCode = 1;
+            return;
+        }
+        await writeCredentials({ token: flags.token, email });
+        console.log(`  Logged in${email ? ` as ${email}` : ''}.`);
+        return;
+    }
+    if (!process.stdin.isTTY) {
+        console.error('  Interactive login requires a terminal. Use `vura login --token <token>` in CI or non-interactive environments.');
+        process.exitCode = 1;
+        return;
+    }
+    const email = await io.prompt('  Email: ');
+    if (!email) {
+        console.error('  Email is required.');
+        process.exitCode = 1;
+        return;
+    }
+    const password = await io.promptPassword('  Password: ');
+    if (!password) {
+        console.error('  Password is required.');
+        process.exitCode = 1;
+        return;
+    }
+    let result;
+    try {
+        result = (await vuraApiRequest(apiUrl, '/v1/auth/login', {
+            method: 'POST',
+            body: { email, password },
+        }));
+    }
+    catch (err) {
+        console.error(`  ${formatApiError(err)}`);
+        process.exitCode = 1;
+        return;
+    }
+    await writeCredentials({
+        token: result.token,
+        email: result.user?.email ?? email,
+        refreshToken: result.refreshToken,
+    });
+    console.log(`  Logged in as ${result.user?.email ?? email}.`);
+}
+//# sourceMappingURL=login.js.map

package/dist/commands/projects.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `vura projects list|create <name>` — manage Vura Platform projects.
+ *
+ * list    GET  /v1/projects?teamId=<id>       — projects in a team.
+ * create  POST /v1/projects { name, teamId }  — create a project.
+ *
+ * Both need a team. `--team <id-or-slug>` resolves it (see
+ * `team-resolution.ts`); if omitted, the caller's only team is used when
+ * they have exactly one (true for every freshly registered account).
+ *
+ * `create` also links the current directory to the new project by writing
+ * `.vura/project.json` (the same file `vura deploy` reads via
+ * `vura-client.ts`'s `readProjectLink`) — but only when this looks like a
+ * Vura project root (a `vura.config.*` is present) that isn't already linked,
+ * so it never silently overwrites an existing link.
+ *
+ * Flags:
+ *   --token <t>       API token (else VURA_TOKEN, else ~/.vura/credentials)
+ *   --api-url <url>   API base URL (else VURA_API_URL, else https://api.vura.io)
+ *   --team <id|slug>  Team to operate in (else the caller's only team)
+ */
+export declare function projectsCommand(args: string[], projectRoot?: string): Promise<void>;
+//# sourceMappingURL=projects.d.ts.map

package/dist/commands/projects.js

@@ -0,0 +1,136 @@
+/**
+ * `vura projects list|create <name>` — manage Vura Platform projects.
+ *
+ * list    GET  /v1/projects?teamId=<id>       — projects in a team.
+ * create  POST /v1/projects { name, teamId }  — create a project.
+ *
+ * Both need a team. `--team <id-or-slug>` resolves it (see
+ * `team-resolution.ts`); if omitted, the caller's only team is used when
+ * they have exactly one (true for every freshly registered account).
+ *
+ * `create` also links the current directory to the new project by writing
+ * `.vura/project.json` (the same file `vura deploy` reads via
+ * `vura-client.ts`'s `readProjectLink`) — but only when this looks like a
+ * Vura project root (a `vura.config.*` is present) that isn't already linked,
+ * so it never silently overwrites an existing link.
+ *
+ * Flags:
+ *   --token <t>       API token (else VURA_TOKEN, else ~/.vura/credentials)
+ *   --api-url <url>   API base URL (else VURA_API_URL, else https://api.vura.io)
+ *   --team <id|slug>  Team to operate in (else the caller's only team)
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { formatApiError, readProjectLink, resolveApiUrl, resolveToken, vuraApiRequest, writeProjectLink } from '../vura-client.js';
+import { resolveTeam, TeamResolutionError } from './team-resolution.js';
+const CONFIG_FILES = ['vura.config.ts', 'vura.config.js', 'vura.config.mjs'];
+function parseFlags(args) {
+    const flags = {};
+    const positionals = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        switch (arg) {
+            case '--token':
+                flags.token = args[++i];
+                break;
+            case '--api-url':
+                flags.apiUrl = args[++i];
+                break;
+            case '--team':
+                flags.team = args[++i];
+                break;
+            default:
+                if (!arg.startsWith('--'))
+                    positionals.push(arg);
+                break;
+        }
+    }
+    return { flags, positionals };
+}
+function looksLikeProjectRoot(root) {
+    return CONFIG_FILES.some((f) => existsSync(join(root, f)));
+}
+function printProjectsTable(projects) {
+    if (projects.length === 0) {
+        console.log('  No projects found. Run `vura projects create <name>` to create one.');
+        return;
+    }
+    console.log('\n  Projects:\n');
+    const slugWidth = Math.max(4, ...projects.map((p) => p.slug.length));
+    const nameWidth = Math.max(4, ...projects.map((p) => p.name.length));
+    for (const p of projects) {
+        console.log(`    ${p.slug.padEnd(slugWidth)}  ${p.name.padEnd(nameWidth)}  ${p.id}`);
+    }
+    console.log();
+}
+async function listCommand(apiUrl, token, teamFlag) {
+    const team = await resolveTeam(apiUrl, token, teamFlag);
+    const body = (await vuraApiRequest(apiUrl, `/v1/projects?teamId=${encodeURIComponent(team.id)}`, { token }));
+    printProjectsTable(body?.data ?? []);
+}
+async function createCommand(apiUrl, token, name, teamFlag, projectRoot) {
+    const team = await resolveTeam(apiUrl, token, teamFlag);
+    const body = (await vuraApiRequest(apiUrl, '/v1/projects', {
+        method: 'POST',
+        token,
+        body: { name, teamId: team.id },
+    }));
+    const project = body?.data;
+    if (!project) {
+        console.error('  Project creation succeeded but the response was missing project data.');
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`\n  Created project "${project.name}" (${project.slug}) in team ${team.slug}.`);
+    console.log(`  Project id: ${project.id}`);
+    if (looksLikeProjectRoot(projectRoot) && !(await readProjectLink(projectRoot))) {
+        await writeProjectLink(projectRoot, { projectId: project.id, teamId: team.id, teamSlug: team.slug });
+        console.log(`  Linked this directory to ${project.slug} (.vura/project.json).\n`);
+    }
+    else {
+        console.log('');
+    }
+}
+export async function projectsCommand(args, projectRoot = process.cwd()) {
+    const subcommand = args[0];
+    const { flags, positionals } = parseFlags(args.slice(1));
+    const token = await resolveToken(flags.token);
+    if (!token) {
+        console.error('  Not authenticated. Run `vura login`, set VURA_TOKEN, or pass --token <token>.');
+        process.exitCode = 1;
+        return;
+    }
+    const apiUrl = resolveApiUrl(flags.apiUrl);
+    try {
+        if (subcommand === 'list') {
+            await listCommand(apiUrl, token, flags.team);
+            return;
+        }
+        if (subcommand === 'create') {
+            const name = positionals[0];
+            if (!name) {
+                console.error('  Usage: vura projects create <name> [--team <id-or-slug>]');
+                process.exitCode = 1;
+                return;
+            }
+            await createCommand(apiUrl, token, name, flags.team, projectRoot);
+            return;
+        }
+    }
+    catch (err) {
+        if (err instanceof TeamResolutionError) {
+            console.error(`  ${err.message}`);
+        }
+        else {
+            console.error(`  ${formatApiError(err)}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    console.error(`  Unknown subcommand: vura projects ${subcommand ?? ''}`);
+    console.error('  Usage:');
+    console.error('    vura projects list [--team <id-or-slug>]');
+    console.error('    vura projects create <name> [--team <id-or-slug>]');
+    process.exitCode = 1;
+}
+//# sourceMappingURL=projects.js.map

package/dist/commands/runtime-profile.d.ts

@@ -1,5 +1,5 @@
 import type { ApiRoute, PageRoute, RouteManifest } from '@celsian/vura-core';
-export type RuntimeProfile = 'static' | 'cold' | 'hot' | 'task-cold' | 'cron-cold' | 'task-hot' | 'cron-hot';
+export type RuntimeProfile = 'static' | 'cold' | 'hot' | 'streaming-hot' | 'task-cold' | 'cron-cold' | 'task-hot' | 'cron-hot';
 export interface RuntimeRouteInspection {
     type: 'api' | 'page';
     pattern: string;

package/dist/commands/runtime-profile.js

@@ -6,19 +6,24 @@ function configNumber(config, key) {
     const value = config[key];
     return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
 }
+function prefersHotTask(config) {
+    return ['runtime', 'placement', 'target'].some((key) => configString(config, key) === 'hot')
+        || config.hot === true;
+}
 export function taskNameFromPattern(urlPattern) {
     return urlPattern.replace(/^\/api\//, '').replace(/\//g, '.');
 }
 export function profileForApiRoute(route) {
     if (route.kind === 'hot')
-        return 'hot';
+        return route.hasWebsocket ? 'streaming-hot' : 'hot';
     if (route.kind === 'task')
-        return 'task-cold';
+        return prefersHotTask(route.config) ? 'task-hot' : 'task-cold';
     return 'cold';
 }
 export function cronProfileForApiRoute(route) {
-    if (route.kind === 'task' && configString(route.config, 'schedule'))
-        return 'cron-cold';
+    if (route.kind === 'task' && configString(route.config, 'schedule')) {
+        return profileForApiRoute(route) === 'task-hot' ? 'cron-hot' : 'cron-cold';
+    }
     return null;
 }
 export function profileForPageRoute(page) {
@@ -27,9 +32,12 @@ export function profileForPageRoute(page) {
     return 'static';
 }
 function backingTargetForApiRoute(route) {
-    if (route.kind === 'hot')
+    const profile = profileForApiRoute(route);
+    if (profile === 'hot' || profile === 'streaming-hot')
         return 'hot server';
-    if (route.kind === 'task')
+    if (profile === 'task-hot')
+        return 'hot task runtime';
+    if (profile === 'task-cold')
         return 'serverless task function';
     return 'serverless function';
 }
@@ -71,7 +79,9 @@ function inspectApiRoute(route) {
             filePath: route.filePath,
             sourceIntent: `schedule:${schedule}`,
             effectiveProfile: cronProfile,
-            backingTarget: 'control-plane scheduler to task function',
+            backingTarget: cronProfile === 'cron-hot'
+                ? 'control-plane scheduler to hot task runtime'
+                : 'control-plane scheduler to task function',
             methods: route.methods,
             schedule,
             hasWebsocket: false,
@@ -100,6 +110,7 @@ export function inspectRuntime(manifest) {
         static: 0,
         cold: 0,
         hot: 0,
+        'streaming-hot': 0,
         'task-cold': 0,
         'cron-cold': 0,
         'task-hot': 0,
@@ -134,37 +145,43 @@ export function adviseRuntime(manifest) {
                 pattern: route.urlPattern,
                 type: 'api',
                 currentProfile,
-                recommendation: 'hot',
+                recommendation: 'streaming-hot',
                 severity: route.kind === 'hot' ? 'info' : 'warn',
                 reason: route.kind === 'hot'
-                    ? 'WebSocket route is correctly placed on hot runtime.'
-                    : 'WebSocket exports require hot runtime to handle upgrades.',
+                    ? 'WebSocket route is correctly placed on streaming-hot runtime.'
+                    : 'WebSocket exports require streaming-hot runtime to handle upgrades.',
             });
         }
         if (route.kind === 'task') {
+            const taskProfile = profileForApiRoute(route);
             advice.push({
                 pattern: route.urlPattern,
                 type: 'api',
                 currentProfile,
-                recommendation: 'task-cold',
+                recommendation: taskProfile,
                 severity: 'info',
-                reason: schedule
-                    ? 'Scheduled task is a task-cold worker with cron-cold dispatch.'
-                    : 'Task route is a task-cold worker for manual or API-triggered jobs.',
+                reason: taskProfile === 'task-hot'
+                    ? 'Task route is pinned to hot task runtime for long-running or stateful work.'
+                    : schedule
+                        ? 'Scheduled task is a task-cold worker with cron-cold dispatch.'
+                        : 'Task route is a task-cold worker for manual or API-triggered jobs.',
                 nextCommand: `vura tasks run ${taskNameFromPattern(route.urlPattern)}`,
             });
             if (schedule) {
+                const cronProfile = cronProfileForApiRoute(route) ?? 'cron-cold';
                 advice.push({
                     pattern: route.urlPattern,
                     type: 'api',
-                    currentProfile: 'cron-cold',
-                    recommendation: 'cron-cold',
+                    currentProfile: cronProfile,
+                    recommendation: cronProfile,
                     severity: 'info',
-                    reason: `Cron schedule ${schedule} dispatches to the task-cold target.`,
+                    reason: cronProfile === 'cron-hot'
+                        ? `Cron schedule ${schedule} dispatches to the hot task target.`
+                        : `Cron schedule ${schedule} dispatches to the task-cold target.`,
                     nextCommand: 'vura tasks list',
                 });
             }
-            if (typeof timeout === 'number' && timeout > 60_000) {
+            if (typeof timeout === 'number' && timeout > 60_000 && taskProfile !== 'task-hot') {
                 advice.push({
                     pattern: route.urlPattern,
                     type: 'api',

package/dist/commands/team-resolution.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared "which team am I talking about" logic for `vura teams` and
+ * `vura projects`. Both commands accept a `--team <id-or-slug>` flag, and
+ * both need the same fallback when it's omitted: use the caller's only team
+ * if they have exactly one (true for every freshly registered account, which
+ * gets a personal team automatically), otherwise ask them to disambiguate.
+ */
+export interface ResolvedTeam {
+    id: string;
+    slug: string;
+    name: string;
+}
+interface TeamSummary {
+    id: string;
+    name: string;
+    slug: string;
+    role?: string;
+    plan?: string;
+}
+/** Thrown for team-resolution failures the caller should print and exit(1) on. */
+export declare class TeamResolutionError extends Error {
+}
+/**
+ * List the caller's teams via GET /v1/teams.
+ */
+export declare function listTeams(apiUrl: string, token: string): Promise<TeamSummary[]>;
+/**
+ * Resolve a `--team` flag value (or its absence) to a concrete team id.
+ *
+ *   - UUID-shaped input is used directly as the team id (no round trip).
+ *   - Non-UUID input is treated as a slug and looked up via GET /v1/teams/:slug.
+ *   - No input at all falls back to the caller's only team, if they have
+ *     exactly one; otherwise throws {@link TeamResolutionError} listing the
+ *     choices so the CLI can print a helpful "pick one of: a, b, c" error.
+ */
+export declare function resolveTeam(apiUrl: string, token: string, teamFlag: string | undefined): Promise<ResolvedTeam>;
+export {};
+//# sourceMappingURL=team-resolution.d.ts.map

package/dist/commands/team-resolution.js

@@ -0,0 +1,50 @@
+/**
+ * Shared "which team am I talking about" logic for `vura teams` and
+ * `vura projects`. Both commands accept a `--team <id-or-slug>` flag, and
+ * both need the same fallback when it's omitted: use the caller's only team
+ * if they have exactly one (true for every freshly registered account, which
+ * gets a personal team automatically), otherwise ask them to disambiguate.
+ */
+import { vuraApiRequest } from '../vura-client.js';
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Thrown for team-resolution failures the caller should print and exit(1) on. */
+export class TeamResolutionError extends Error {
+}
+/**
+ * List the caller's teams via GET /v1/teams.
+ */
+export async function listTeams(apiUrl, token) {
+    const body = (await vuraApiRequest(apiUrl, '/v1/teams', { token }));
+    return body?.data ?? [];
+}
+/**
+ * Resolve a `--team` flag value (or its absence) to a concrete team id.
+ *
+ *   - UUID-shaped input is used directly as the team id (no round trip).
+ *   - Non-UUID input is treated as a slug and looked up via GET /v1/teams/:slug.
+ *   - No input at all falls back to the caller's only team, if they have
+ *     exactly one; otherwise throws {@link TeamResolutionError} listing the
+ *     choices so the CLI can print a helpful "pick one of: a, b, c" error.
+ */
+export async function resolveTeam(apiUrl, token, teamFlag) {
+    if (teamFlag && UUID_RE.test(teamFlag)) {
+        return { id: teamFlag, slug: teamFlag, name: teamFlag };
+    }
+    if (teamFlag) {
+        const body = (await vuraApiRequest(apiUrl, `/v1/teams/${encodeURIComponent(teamFlag)}`, { token }));
+        if (!body?.data) {
+            throw new TeamResolutionError(`Team "${teamFlag}" not found.`);
+        }
+        return { id: body.data.id, slug: body.data.slug, name: body.data.name };
+    }
+    const teams = await listTeams(apiUrl, token);
+    if (teams.length === 1) {
+        return { id: teams[0].id, slug: teams[0].slug, name: teams[0].name };
+    }
+    if (teams.length === 0) {
+        throw new TeamResolutionError('No teams found. Run `vura teams create <name>` first.');
+    }
+    const choices = teams.map((t) => t.slug).join(', ');
+    throw new TeamResolutionError(`Multiple teams found — pass --team <id-or-slug>. Choices: ${choices}`);
+}
+//# sourceMappingURL=team-resolution.js.map

package/dist/commands/teams.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `vura teams list|create <name>` — manage Vura Platform teams.
+ *
+ * list    GET  /v1/teams  — teams the authenticated user belongs to.
+ * create  POST /v1/teams  — create a team. The API requires a slug, so one is
+ *         derived from the name (matching `vura-client.ts`'s `slugify`,
+ *         which mirrors how the API itself derives slugs) unless --slug is given.
+ *
+ * Flags:
+ *   --token <t>       API token (else VURA_TOKEN, else ~/.vura/credentials)
+ *   --api-url <url>   API base URL (else VURA_API_URL, else https://api.vura.io)
+ *   --slug <slug>     (create only) Explicit slug instead of deriving one from <name>.
+ */
+export declare function teamsCommand(args: string[]): Promise<void>;
+//# sourceMappingURL=teams.d.ts.map

package/dist/commands/teams.js

@@ -0,0 +1,109 @@
+/**
+ * `vura teams list|create <name>` — manage Vura Platform teams.
+ *
+ * list    GET  /v1/teams  — teams the authenticated user belongs to.
+ * create  POST /v1/teams  — create a team. The API requires a slug, so one is
+ *         derived from the name (matching `vura-client.ts`'s `slugify`,
+ *         which mirrors how the API itself derives slugs) unless --slug is given.
+ *
+ * Flags:
+ *   --token <t>       API token (else VURA_TOKEN, else ~/.vura/credentials)
+ *   --api-url <url>   API base URL (else VURA_API_URL, else https://api.vura.io)
+ *   --slug <slug>     (create only) Explicit slug instead of deriving one from <name>.
+ */
+import { formatApiError, resolveApiUrl, resolveToken, slugify, vuraApiRequest } from '../vura-client.js';
+import { listTeams } from './team-resolution.js';
+function parseFlags(args) {
+    const flags = {};
+    const positionals = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        switch (arg) {
+            case '--token':
+                flags.token = args[++i];
+                break;
+            case '--api-url':
+                flags.apiUrl = args[++i];
+                break;
+            case '--slug':
+                flags.slug = args[++i];
+                break;
+            default:
+                if (!arg.startsWith('--'))
+                    positionals.push(arg);
+                break;
+        }
+    }
+    return { flags, positionals };
+}
+function printTeamsTable(teams) {
+    if (teams.length === 0) {
+        console.log('  No teams found. Run `vura teams create <name>` to create one.');
+        return;
+    }
+    console.log('\n  Teams:\n');
+    const slugWidth = Math.max(4, ...teams.map((t) => t.slug.length));
+    const nameWidth = Math.max(4, ...teams.map((t) => t.name.length));
+    for (const t of teams) {
+        console.log(`    ${t.slug.padEnd(slugWidth)}  ${t.name.padEnd(nameWidth)}  ${(t.role ?? '').padEnd(8)} ${t.plan ?? ''}`);
+    }
+    console.log();
+}
+async function listCommand(apiUrl, token) {
+    const teams = await listTeams(apiUrl, token);
+    printTeamsTable(teams);
+}
+async function createCommand(apiUrl, token, name, slugFlag) {
+    const slug = slugFlag || slugify(name);
+    const body = (await vuraApiRequest(apiUrl, '/v1/teams', {
+        method: 'POST',
+        token,
+        body: { name, slug },
+    }));
+    const team = body?.data;
+    if (!team) {
+        console.error('  Team creation succeeded but the response was missing team data.');
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`\n  Created team "${team.name}" (${team.slug}).`);
+    console.log(`  Team id: ${team.id}\n`);
+}
+export async function teamsCommand(args) {
+    const subcommand = args[0];
+    const { flags, positionals } = parseFlags(args.slice(1));
+    const token = await resolveToken(flags.token);
+    if (!token) {
+        console.error('  Not authenticated. Run `vura login`, set VURA_TOKEN, or pass --token <token>.');
+        process.exitCode = 1;
+        return;
+    }
+    const apiUrl = resolveApiUrl(flags.apiUrl);
+    try {
+        if (subcommand === 'list') {
+            await listCommand(apiUrl, token);
+            return;
+        }
+        if (subcommand === 'create') {
+            const name = positionals[0];
+            if (!name) {
+                console.error('  Usage: vura teams create <name> [--slug <slug>]');
+                process.exitCode = 1;
+                return;
+            }
+            await createCommand(apiUrl, token, name, flags.slug);
+            return;
+        }
+    }
+    catch (err) {
+        console.error(`  ${formatApiError(err)}`);
+        process.exitCode = 1;
+        return;
+    }
+    console.error(`  Unknown subcommand: vura teams ${subcommand ?? ''}`);
+    console.error('  Usage:');
+    console.error('    vura teams list');
+    console.error('    vura teams create <name> [--slug <slug>]');
+    process.exitCode = 1;
+}
+//# sourceMappingURL=teams.js.map

package/dist/index.js

@@ -12,6 +12,9 @@ import { adminCommand } from './commands/admin.js';
 import { tasksCommand } from './commands/tasks.js';
 import { routesCommand } from './commands/routes.js';
 import { runtimeCommand } from './commands/runtime.js';
+import { loginCommand } from './commands/login.js';
+import { teamsCommand } from './commands/teams.js';
+import { projectsCommand } from './commands/projects.js';
 const COMMANDS = {
     build: buildCommand,
     manifest: manifestCommand,
@@ -21,6 +24,9 @@ const COMMANDS = {
     tasks: tasksCommand,
     routes: routesCommand,
     runtime: runtimeCommand,
+    login: loginCommand,
+    teams: teamsCommand,
+    projects: projectsCommand,
 };
 export async function run(args) {
     const command = args[0];
@@ -43,7 +49,15 @@ function printHelp() {
   Commands:
     dev         Start local development server
     build       Build the project for deployment
-    deploy      Deploy the built project to the Vura platform
+    login       Authenticate against the Vura Platform
+                  vura login [--token <t>]
+    teams       Manage Vura Platform teams
+                  vura teams list
+                  vura teams create <name> [--slug <slug>]
+    projects    Manage Vura Platform projects
+                  vura projects list [--team <id-or-slug>]
+                  vura projects create <name> [--team <id-or-slug>]
+    deploy      Deploy the built project to the Vura platform (beta)
                   vura deploy [--prod] [--token <t>] [--api-url <u>]
     admin       Launch the admin dashboard
     manifest    Print the route manifest (debug)

package/dist/vura-client.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared credential/config resolution and API client for commands that talk
+ * to the Vura Platform (`vura login`, `vura teams`, `vura projects`,
+ * `vura deploy`).
+ *
+ * Conventions (do not change without updating every command that relies on
+ * them — `deploy.ts` and `@celsian/vura-adapter-vura` read the same files):
+ *   token      : --token flag   > VURA_TOKEN env    > ~/.vura/credentials `token`
+ *   api url    : --api-url flag > VURA_API_URL env  > https://api.vura.io
+ *   project id : --project-id flag > VURA_PROJECT_ID env > <root>/.vura/project.json `projectId`
+ */
+export declare const DEFAULT_API_URL = "https://api.vura.io";
+export interface VuraCredentials {
+    token: string;
+    email?: string;
+    refreshToken?: string;
+}
+export interface VuraProjectLink {
+    projectId: string;
+    teamId?: string;
+    teamSlug?: string;
+}
+/** Home directory, honoring HOME/USERPROFILE overrides (e.g. in tests). */
+export declare function resolveHome(): string;
+/** Read ~/.vura/credentials. Returns null if absent, malformed, or tokenless. */
+export declare function readCredentials(): Promise<VuraCredentials | null>;
+/** Write ~/.vura/credentials at mode 0600 (owner read/write only). */
+export declare function writeCredentials(creds: VuraCredentials): Promise<void>;
+/** Resolve the auth token: --token flag > VURA_TOKEN env > ~/.vura/credentials. */
+export declare function resolveToken(flag?: string): Promise<string | null>;
+/** Resolve the API base URL: --api-url flag > VURA_API_URL env > default. */
+export declare function resolveApiUrl(flag?: string): string;
+/** Read <projectRoot>/.vura/project.json. Returns null if absent/malformed. */
+export declare function readProjectLink(projectRoot: string): Promise<VuraProjectLink | null>;
+/** Write <projectRoot>/.vura/project.json, linking the project for `vura deploy`. */
+export declare function writeProjectLink(projectRoot: string, link: VuraProjectLink): Promise<void>;
+/** Resolve the project id: --project-id flag > VURA_PROJECT_ID env > .vura/project.json. */
+export declare function resolveProjectId(flag: string | undefined, projectRoot: string): Promise<string | null>;
+/** An error response from the Vura API, carrying the HTTP status for callers to branch on (e.g. 401 → suggest `vura login`). */
+export declare class VuraApiError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    constructor(message: string, status: number, code?: string);
+}
+/**
+ * Call the Vura API and return the parsed JSON body. Throws {@link VuraApiError}
+ * on a non-2xx response, using the server's `{ error: { message } }` shape
+ * when present.
+ */
+export declare function vuraApiRequest(apiUrl: string, path: string, init?: {
+    method?: string;
+    token?: string;
+    body?: unknown;
+}): Promise<unknown>;
+/** Format a caught error for CLI display, adding a `vura login` hint on 401s. */
+export declare function formatApiError(err: unknown): string;
+/** Slugify a name the same way the Vura API derives team/project slugs. */
+export declare function slugify(name: string): string;
+//# sourceMappingURL=vura-client.d.ts.map

package/dist/vura-client.js

@@ -0,0 +1,147 @@
+/**
+ * Shared credential/config resolution and API client for commands that talk
+ * to the Vura Platform (`vura login`, `vura teams`, `vura projects`,
+ * `vura deploy`).
+ *
+ * Conventions (do not change without updating every command that relies on
+ * them — `deploy.ts` and `@celsian/vura-adapter-vura` read the same files):
+ *   token      : --token flag   > VURA_TOKEN env    > ~/.vura/credentials `token`
+ *   api url    : --api-url flag > VURA_API_URL env  > https://api.vura.io
+ *   project id : --project-id flag > VURA_PROJECT_ID env > <root>/.vura/project.json `projectId`
+ */
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const DEFAULT_API_URL = 'https://api.vura.io';
+/** Home directory, honoring HOME/USERPROFILE overrides (e.g. in tests). */
+export function resolveHome() {
+    return process.env.HOME || process.env.USERPROFILE || homedir();
+}
+function credentialsPath() {
+    return join(resolveHome(), '.vura', 'credentials');
+}
+/** Read ~/.vura/credentials. Returns null if absent, malformed, or tokenless. */
+export async function readCredentials() {
+    try {
+        const raw = await readFile(credentialsPath(), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed.token === 'string' && parsed.token.length > 0) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Write ~/.vura/credentials at mode 0600 (owner read/write only). */
+export async function writeCredentials(creds) {
+    const dir = join(resolveHome(), '.vura');
+    await mkdir(dir, { recursive: true });
+    const path = credentialsPath();
+    await writeFile(path, `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600 });
+    // `writeFile`'s `mode` only applies when CREATING the file — a pre-existing
+    // credentials file (left at a looser mode by an older CLI or a manual edit)
+    // would keep that mode while now holding a token. Re-tighten explicitly.
+    await chmod(path, 0o600);
+}
+/** Resolve the auth token: --token flag > VURA_TOKEN env > ~/.vura/credentials. */
+export async function resolveToken(flag) {
+    if (flag)
+        return flag;
+    if (process.env.VURA_TOKEN)
+        return process.env.VURA_TOKEN;
+    const creds = await readCredentials();
+    return creds?.token ?? null;
+}
+/** Resolve the API base URL: --api-url flag > VURA_API_URL env > default. */
+export function resolveApiUrl(flag) {
+    return flag || process.env.VURA_API_URL || DEFAULT_API_URL;
+}
+/** Read <projectRoot>/.vura/project.json. Returns null if absent/malformed. */
+export async function readProjectLink(projectRoot) {
+    try {
+        const raw = await readFile(join(projectRoot, '.vura', 'project.json'), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed.projectId === 'string' && parsed.projectId.length > 0) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Write <projectRoot>/.vura/project.json, linking the project for `vura deploy`. */
+export async function writeProjectLink(projectRoot, link) {
+    const dir = join(projectRoot, '.vura');
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'project.json'), `${JSON.stringify(link, null, 2)}\n`);
+}
+/** Resolve the project id: --project-id flag > VURA_PROJECT_ID env > .vura/project.json. */
+export async function resolveProjectId(flag, projectRoot) {
+    if (flag)
+        return flag;
+    if (process.env.VURA_PROJECT_ID)
+        return process.env.VURA_PROJECT_ID;
+    const link = await readProjectLink(projectRoot);
+    return link?.projectId ?? null;
+}
+/** An error response from the Vura API, carrying the HTTP status for callers to branch on (e.g. 401 → suggest `vura login`). */
+export class VuraApiError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.name = 'VuraApiError';
+        this.status = status;
+        this.code = code;
+    }
+}
+/**
+ * Call the Vura API and return the parsed JSON body. Throws {@link VuraApiError}
+ * on a non-2xx response, using the server's `{ error: { message } }` shape
+ * when present.
+ */
+export async function vuraApiRequest(apiUrl, path, init = {}) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (init.token)
+        headers.Authorization = `Bearer ${init.token}`;
+    const res = await fetch(`${apiUrl}${path}`, {
+        method: init.method ?? 'GET',
+        headers,
+        body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
+    });
+    const text = await res.text();
+    let body = null;
+    try {
+        body = text ? JSON.parse(text) : null;
+    }
+    catch {
+        body = text;
+    }
+    if (!res.ok) {
+        const errBody = body;
+        const message = errBody?.error?.message || `Request failed with HTTP ${res.status}`;
+        throw new VuraApiError(message, res.status, errBody?.error?.code);
+    }
+    return body;
+}
+/** Format a caught error for CLI display, adding a `vura login` hint on 401s. */
+export function formatApiError(err) {
+    if (err instanceof VuraApiError) {
+        if (err.status === 401)
+            return `${err.message}. Run \`vura login\` and try again.`;
+        return err.message;
+    }
+    return err instanceof Error ? err.message : String(err);
+}
+/** Slugify a name the same way the Vura API derives team/project slugs. */
+export function slugify(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 64);
+}
+//# sourceMappingURL=vura-client.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celsian/vura-cli",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Vura CLI — build and deploy full-stack apps",
   "type": "module",
   "bin": {
@@ -15,12 +15,12 @@
     "!dist/**/*.map"
   ],
   "dependencies": {
-    "@celsian/vura-core": "0.5.2",
+    "@celsian/vura-core": "0.5.4",
     "esbuild": "^0.28.1",
     "what-framework": "^0.11.1"
   },
   "peerDependencies": {
-    "@celsian/vura-adapter-vura": "0.5.2",
+    "@celsian/vura-adapter-vura": "0.5.4",
     "ws": "^8.0.0"
   },
   "peerDependenciesMeta": {
@@ -32,7 +32,7 @@
     }
   },
   "devDependencies": {
-    "@celsian/vura-adapter-vura": "0.5.2",
+    "@celsian/vura-adapter-vura": "0.5.4",
     "@types/ws": "^8.18.1",
     "ws": "^8.21.0"
   },