@vwork/cli 0.1.0

package/dist/oclif-command.js

@@ -0,0 +1,357 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command, Flags } from "@oclif/core";
+import { PlatformClient } from "@vwork/platform-client";
+import { runAppCommand } from "./apps.js";
+import { FileCredentialStore, loadDefaultCredentials } from "./auth/store.js";
+import { runCodegenCommand } from "./codegen.js";
+import { resolveCliConfigFromFlags } from "./config.js";
+import { runDbCommand } from "./db.js";
+import { runFunctionCommand } from "./functions.js";
+import { runLoginCommand, runWhoamiCommand } from "./login.js";
+import { runKvCommand } from "./kv.js";
+import { runMigrationCommand } from "./migrations.js";
+import { runObservabilityCommand } from "./observability.js";
+import { renderJson, renderTable } from "./output.js";
+import { runQueueCommand } from "./queues.js";
+import { runRuntimeCommand } from "./runtime.js";
+import { runSecretCommand } from "./secrets.js";
+const COMMAND_ROOTS = new Set(["apps", "db", "migrations", "functions", "codegen", "secrets", "kv", "queues", "runtime", "observability", "login", "whoami"]);
+export class VWorkCliCommand extends Command {
+    static description = "Manage VWork apps, database rows, migrations, and functions.";
+    static strict = false;
+    static flags = {
+        "api-url": Flags.string({ description: "Platform API base URL" }),
+        app: Flags.string({ description: "App id or slug" }),
+        schema: Flags.string({ description: "Database schema" }),
+        format: Flags.string({ description: "Output format", options: ["table", "json"] }),
+        name: Flags.string({ description: "App display name" }),
+        slug: Flags.string({ description: "App slug" }),
+        host: Flags.string({ description: "App API host" }),
+        "data-source": Flags.string({ description: "Data source id" }),
+        isolation: Flags.string({ description: "Data isolation mode" }),
+        sql: Flags.string({ description: "Inline SQL" }),
+        filter: Flags.string({ description: "Row filter expression", multiple: true }),
+        limit: Flags.string({ description: "Result limit" }),
+        offset: Flags.string({ description: "Result offset" }),
+        order: Flags.string({ description: "Order as column.asc or column.desc" }),
+        data: Flags.string({ description: "JSON object payload" }),
+        pk: Flags.string({ description: "Primary key as column=value" }),
+        up: Flags.string({ description: "Migration up SQL file" }),
+        "up-sql": Flags.string({ description: "Inline migration up SQL" }),
+        down: Flags.string({ description: "Migration down SQL file" }),
+        "down-sql": Flags.string({ description: "Inline migration down SQL" }),
+        reason: Flags.string({ description: "Reason for migration down" }),
+        file: Flags.string({ description: "Runtime-ready JavaScript source file path" }),
+        bundle: Flags.string({ description: "Runtime-ready JavaScript bundle file path" }),
+        "source-code": Flags.string({ description: "Inline function source code" }),
+        function: Flags.string({ description: "Function name" }),
+        binding: Flags.string({ description: "Function binding name for code generation context", multiple: true }),
+        route: Flags.string({ description: "Function route path prefix" }),
+        artifact: Flags.string({ description: "Function artifact id" }),
+        body: Flags.string({ description: "JSON request body" }),
+        ttl: Flags.string({ description: "Preview TTL, such as 30m or 1h" }),
+        preview: Flags.string({ description: "Preview id" }),
+        table: Flags.string({ description: "Table name for schema-scoped codegen", multiple: true }),
+        prompt: Flags.string({ description: "Code generation prompt" }),
+        run: Flags.string({ description: "Code generation run id" }),
+        title: Flags.string({ description: "KV namespace display title" }),
+        namespace: Flags.string({ description: "KV namespace id" }),
+        prefix: Flags.string({ description: "KV key prefix filter" }),
+        cursor: Flags.string({ description: "Pagination cursor" }),
+        range: Flags.string({ description: "Metrics range" }),
+        step: Flags.string({ description: "Metrics step" }),
+        granularity: Flags.string({ description: "Metrics granularity" }),
+        from: Flags.string({ description: "Custom metrics window start ISO timestamp" }),
+        to: Flags.string({ description: "Custom metrics window end ISO timestamp" }),
+        source: Flags.string({ description: "Access log source" }),
+        "base-url": Flags.string({ description: "Raw repository base URL for skill install curl output" }),
+        workspace: Flags.string({ description: "Workspace path used by local MCP server snippets" }),
+        queue: Flags.string({ description: "Queue binding as <queue_id>[:producer|consumer|producer_consumer]", multiple: true }),
+        "batch-size": Flags.string({ description: "Queue batch size" }),
+        "wait-seconds": Flags.string({ description: "Queue wait or visibility timeout seconds" }),
+        "retry-attempts": Flags.string({ description: "Queue retry attempts" }),
+        "max-delay-seconds": Flags.string({ description: "Queue max delay seconds" }),
+        "queue-length": Flags.string({ description: "Queue max message count" }),
+        "message-bytes": Flags.string({ description: "Queue max message size in bytes" }),
+        "dead-letter-enabled": Flags.string({ description: "Enable dead letter handling: true or false" }),
+        out: Flags.string({ description: "Output path" }),
+        yes: Flags.boolean({ description: "Confirm the operation" }),
+        verbose: Flags.boolean({ description: "Enable verbose output" }),
+        "no-auth": Flags.boolean({ description: "Disable function auth requirement" }),
+        repair: Flags.boolean({ description: "Enable codegen repair attempts" }),
+        "draft-invoke-body": Flags.string({ description: "Draft invocation request body JSON object for codegen validation" }),
+        "draft-invoke-bindings": Flags.string({ description: "Draft invocation binding overrides JSON object for codegen validation" }),
+        version: Flags.boolean({ char: "v", description: "Show CLI version" }),
+        help: Flags.boolean({ char: "h", description: "Show CLI help" })
+    };
+    async run() {
+        const parsed = await this.parse(VWorkCliCommand);
+        const command = parsedCommandFromOclif(parsed.argv.map(String), parsedFlags(parsed.flags));
+        if (command.flags.version === true) {
+            this.log(packageVersion());
+            return;
+        }
+        if (command.flags.help === true) {
+            this.log(command.path.length === 1 ? resourceHelpText(command.path[0] ?? "") : helpText());
+            return;
+        }
+        if (command.path.length === 0) {
+            this.log(helpText());
+            return;
+        }
+        if (command.path[0] === "login") {
+            const config = resolveCliConfigFromFlags(command.flags, process.env, process.cwd());
+            const root = process.env.VWORK_HOME ?? join(homedir(), ".vwork");
+            const store = new FileCredentialStore(root);
+            const output = await runLoginCommand({
+                apiUrl: config.apiUrl,
+                openBrowser: async (url) => {
+                    this.log(`Open this URL to continue login: ${url}`);
+                },
+                saveApiKey: (input) => store.saveApiKey(input)
+            });
+            process.stdout.write(output);
+            return;
+        }
+        if (command.path[0] === "whoami") {
+            const credentials = await loadDefaultCredentials(process.env, homedir());
+            if (!credentials)
+                throw new Error("Not logged in. Run vwork login first.");
+            const config = resolveCliConfigFromFlags(command.flags, process.env, process.cwd(), credentials.base_url);
+            assertStoredCredentialsMatchApiUrl(credentials, config.apiUrl);
+            process.stdout.write(await runWhoamiCommand({ apiUrl: config.apiUrl, credentials }));
+            return;
+        }
+        if (command.path.length === 1) {
+            this.log(resourceHelpText(command.path[0] ?? ""));
+            return;
+        }
+        const credentials = await loadDefaultCredentials(process.env, homedir());
+        const config = resolveCliConfigFromFlags(command.flags, process.env, process.cwd(), credentials?.base_url);
+        if (credentials)
+            assertStoredCredentialsMatchApiUrl(credentials, config.apiUrl);
+        const client = new PlatformClient({
+            apiUrl: config.apiUrl,
+            trustedUserId: credentials ? null : config.trustedUserId,
+            apiKey: credentials?.api_key ?? null
+        });
+        const result = await dispatchCommand(command, client, config, process.cwd());
+        if (!result)
+            throw new Error(`Unknown command: ${command.path.join(" ")}`);
+        const output = result.rows ?? (result.value === undefined ? [] : [result.value]);
+        const rendered = config.output === "json" ? renderJson(result.rows ?? result.value ?? null) : renderTable(output);
+        process.stdout.write(rendered);
+    }
+}
+export async function runOclifCli(argv) {
+    await VWorkCliCommand.run([...argv], { root: packageRoot() });
+}
+export function parsedCommandFromOclif(argv, flags) {
+    const path = [];
+    const positionals = [];
+    let commandStarted = false;
+    for (const token of argv) {
+        if (!commandStarted) {
+            if (COMMAND_ROOTS.has(token)) {
+                commandStarted = true;
+                path.push(token);
+            }
+            else {
+                positionals.push(token);
+            }
+            continue;
+        }
+        if (path.length < maxPathLength(path)) {
+            path.push(token);
+        }
+        else {
+            positionals.push(token);
+        }
+    }
+    return { path, positionals, flags };
+}
+function parsedFlags(flags) {
+    const result = {};
+    for (const [key, value] of Object.entries(flags)) {
+        if (value === undefined || value === false)
+            continue;
+        if (Array.isArray(value)) {
+            if (value.length > 0)
+                result[key] = value.map(String);
+            continue;
+        }
+        if (typeof value === "string" || typeof value === "boolean")
+            result[key] = value;
+    }
+    return result;
+}
+async function dispatchCommand(command, client, config, cwd) {
+    if (command.path[0] === "apps")
+        return runAppCommand(command, client);
+    if (command.path[0] === "codegen")
+        return runCodegenCommand(command, client, config);
+    if (command.path[0] === "db")
+        return runDbCommand(command, client, config);
+    if (command.path[0] === "kv")
+        return runKvCommand(command, client, config);
+    if (command.path[0] === "migrations")
+        return runMigrationCommand(command, client, config, cwd);
+    if (command.path[0] === "functions")
+        return runFunctionCommand(command, client, config, cwd);
+    if (command.path[0] === "observability")
+        return runObservabilityCommand(command, client);
+    if (command.path[0] === "queues")
+        return runQueueCommand(command, client, config);
+    if (command.path[0] === "runtime")
+        return runRuntimeCommand(command, client);
+    if (command.path[0] === "secrets")
+        return runSecretCommand(command, client, config);
+    return null;
+}
+function assertStoredCredentialsMatchApiUrl(credentials, apiUrl) {
+    if (normalizeApiBaseUrl(credentials.base_url) === normalizeApiBaseUrl(apiUrl))
+        return;
+    throw new Error(`Stored credentials are for ${normalizeApiBaseUrl(credentials.base_url)}. Run vwork login for ${normalizeApiBaseUrl(apiUrl)} before using that API URL.`);
+}
+function normalizeApiBaseUrl(value) {
+    return value.replace(/\/+$/, "");
+}
+function maxPathLength(path) {
+    if (path[0] === "db")
+        return 3;
+    if (path[0] === "codegen")
+        return 3;
+    if (path[0] === "kv")
+        return 3;
+    if (path[0] === "functions" && path[1] === "previews")
+        return 3;
+    if (path[0] === "functions" && path[1] === "queue-bindings")
+        return 3;
+    return 2;
+}
+function helpText() {
+    return [
+        "VWork CLI",
+        "",
+        "Usage: vwork <resource> <command> [flags]",
+        "",
+        "Resources:",
+        "  apps         list, inspect, create, delete, bind-data-source",
+        "  db           tables list, sql exec, sql preview, rows select|insert|update|delete",
+        "  migrations   list, runs, create, up, down, delete",
+        "  functions    list, inspect, create, deploy, invoke, artifacts, artifact, publish, rollback, metrics, previews, validate",
+        "  codegen      mobile from-schema, function generate, runs list|download|verify, skill install-curl",
+        "  secrets      list",
+        "  kv           namespaces list|create, entries list, stats, metrics",
+        "  queues       list, create, update, delete",
+        "  runtime      latest, publish",
+        "  observability access-logs",
+        "  login        authenticate with VWork",
+        "  whoami       show the authenticated VWork user",
+        ""
+    ].join("\n");
+}
+function resourceHelpText(resource) {
+    const commands = {
+        apps: [
+            "list",
+            "inspect <app>",
+            "create --name <name> --slug <slug> [--host <host>] --data-source <id>",
+            "delete <app>",
+            "bind-data-source <app> --data-source <id>"
+        ],
+        db: [
+            "tables list --app <app>",
+            "sql exec --app <app> --sql <sql>",
+            "sql preview --app <app> --sql <sql>",
+            "rows select <table> --app <app>",
+            "rows insert <table> --app <app> --data <json>",
+            "rows update <table> --app <app> --pk <column=value> --data <json>",
+            "rows delete <table> --app <app> --pk <column=value>"
+        ],
+        migrations: [
+            "list --app <app>",
+            "runs --app <app>",
+            "create <version> --app <app> --up <file>",
+            "up <version> --app <app> --up <file>",
+            "down <version> --app <app> --reason <reason>",
+            "delete <version> --app <app>"
+        ],
+        functions: [
+            "list --app <app>",
+            "inspect <name> --app <app>",
+            "create <name> --app <app> --file <path>",
+            "deploy <name> --app <app> --bundle <path>",
+            "invoke <name> --app <app> --file <path>",
+            "artifact <name> --app <app> --file <path>",
+            "artifacts <name> --app <app>",
+            "publish <name> --app <app> --artifact <id>",
+            "rollback <name> --app <app> --artifact <id>",
+            "metrics <name> --app <app>",
+            "previews create <name> --app <app> --artifact <id>",
+            "queue-bindings list <name> --app <app>",
+            "queue-bindings replace <name> --app <app> --queue <queue_id:mode>",
+            "validate --file <path>"
+        ],
+        codegen: [
+            "mobile from-schema --app <app> [--schema <schema>] [--table <table>] [--prompt <text>]",
+            "function generate --app <app> --function <name> --prompt <text> [--source-code <code>] [--binding <name>...] [--repair] [--draft-invoke-body <json>] [--draft-invoke-bindings <json>]",
+            "skill install-curl [--base-url <raw-base-url>]",
+            "mcp config-snippet [--workspace <repo-path>] [--api-url <url>] [--app <app>] [--schema <schema>]",
+            "runs list --app <app>",
+            "runs download --app <app> --run <id> --out <zip>",
+            "runs verify --app <app> --run <id>"
+        ],
+        secrets: [
+            "list --app <app>"
+        ],
+        kv: [
+            "namespaces list --app <app>",
+            "namespaces create --app <app> --title <title>",
+            "entries list --app <app> --namespace <id> [--prefix <prefix>] [--limit <n>] [--cursor <cursor>]",
+            "stats --app <app> --namespace <id>",
+            "metrics --app <app> --namespace <id> [--range <range>] [--step <step>]"
+        ],
+        queues: [
+            "list --app <app>",
+            "create --app <app> --name <name> [--batch-size <n>] [--wait-seconds <n>]",
+            "update <queue-id> --app <app> [--batch-size <n>] [--dead-letter-enabled true|false]",
+            "delete <queue-id> --app <app>"
+        ],
+        runtime: [
+            "latest",
+            "publish"
+        ],
+        observability: [
+            "access-logs [--source <source>] [--app <app>] [--limit <n>]"
+        ],
+        login: [
+            "login"
+        ],
+        whoami: [
+            "whoami"
+        ]
+    };
+    const resourceCommands = commands[resource];
+    if (!resourceCommands)
+        return helpText();
+    return [
+        "VWork CLI",
+        "",
+        `Usage: vwork ${resource} <command> [flags]`,
+        "",
+        "Commands:",
+        ...resourceCommands.map((command) => `  ${command}`),
+        ""
+    ].join("\n");
+}
+function packageRoot() {
+    return fileURLToPath(new URL("..", import.meta.url));
+}
+function packageVersion() {
+    const parsed = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    return parsed.version ?? "0.0.0";
+}

package/dist/output.js

@@ -0,0 +1,12 @@
+export function renderJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+export function renderTable(rows) {
+    if (rows.length === 0)
+        return "No rows\n";
+    const headers = Object.keys(rows[0] ?? {});
+    const widths = headers.map((header) => Math.max(header.length, ...rows.map((row) => String(row[header] ?? "").length)));
+    const line = headers.map((header, index) => header.padEnd(widths[index] ?? header.length)).join("  ");
+    const body = rows.map((row) => headers.map((header, index) => String(row[header] ?? "").padEnd(widths[index] ?? header.length)).join("  "));
+    return `${[line, ...body].join("\n")}\n`;
+}

package/dist/queues.js

@@ -0,0 +1,71 @@
+import { stringFlag } from "./config.js";
+export async function runQueueCommand(command, client, config) {
+    const action = command.path[1];
+    const app = await resolveApp(command, client, config);
+    const basePath = `/apps/${encodeURIComponent(String(app.id))}/queues`;
+    if (action === "list") {
+        const body = await client.request("GET", basePath);
+        return { rows: body.queues };
+    }
+    if (action === "create") {
+        return { value: await client.request("POST", basePath, queueMutationBody(command, true)) };
+    }
+    if (action === "update") {
+        const queueId = requiredPosition(command, 0, "queue id");
+        return { value: await client.request("PATCH", `${basePath}/${encodeURIComponent(queueId)}`, queueMutationBody(command, false)) };
+    }
+    if (action === "delete") {
+        const queueId = requiredPosition(command, 0, "queue id");
+        return { value: await client.request("DELETE", `${basePath}/${encodeURIComponent(queueId)}`) };
+    }
+    throw new Error(`Unknown queues command: ${action ?? ""}`);
+}
+async function resolveApp(command, client, config) {
+    const target = stringFlag(command.flags.app) ?? config.appId;
+    if (!target)
+        throw new Error("Missing --app");
+    return client.request("GET", `/apps/lookup/${encodeURIComponent(target)}`);
+}
+function queueMutationBody(command, requireName) {
+    const body = {};
+    const name = stringFlag(command.flags.name);
+    if (name)
+        body.name = name;
+    if (requireName && !name)
+        throw new Error("Missing --name");
+    copyNumberFlag(command, body, "max-messages", "max_messages");
+    copyNumberFlag(command, body, "queue-length", "max_messages");
+    copyNumberFlag(command, body, "max-message-bytes", "max_message_bytes");
+    copyNumberFlag(command, body, "message-bytes", "max_message_bytes");
+    copyNumberFlag(command, body, "max-delay-seconds", "max_delay_seconds");
+    copyNumberFlag(command, body, "max-delivery-attempts", "max_delivery_attempts");
+    copyNumberFlag(command, body, "retry-attempts", "max_delivery_attempts");
+    copyNumberFlag(command, body, "batch-size", "batch_size");
+    copyNumberFlag(command, body, "visibility-timeout-seconds", "visibility_timeout_seconds");
+    copyNumberFlag(command, body, "wait-seconds", "visibility_timeout_seconds");
+    copyBooleanFlag(command, body, "dead-letter-enabled", "dead_letter_enabled");
+    return body;
+}
+function copyNumberFlag(command, body, flag, key) {
+    const value = stringFlag(command.flags[flag]);
+    if (value === undefined)
+        return;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed))
+        throw new Error(`--${flag} must be an integer`);
+    body[key] = parsed;
+}
+function copyBooleanFlag(command, body, flag, key) {
+    const value = stringFlag(command.flags[flag]);
+    if (value === undefined)
+        return;
+    if (value !== "true" && value !== "false")
+        throw new Error(`--${flag} must be true or false`);
+    body[key] = value === "true";
+}
+function requiredPosition(command, index, label) {
+    const value = command.positionals[index];
+    if (!value)
+        throw new Error(`Missing ${label}`);
+    return value;
+}

package/dist/runtime.js

@@ -0,0 +1,11 @@
+export async function runRuntimeCommand(command, client) {
+    const action = command.path[1];
+    if (action === "latest") {
+        const body = await client.request("GET", "/runtime-config/latest");
+        return { value: body.runtime_config };
+    }
+    if (action === "publish") {
+        return { value: await client.request("POST", "/runtime-config/publish") };
+    }
+    throw new Error(`Unknown runtime command: ${action ?? ""}`);
+}

package/dist/secrets.js

@@ -0,0 +1,16 @@
+import { stringFlag } from "./config.js";
+export async function runSecretCommand(command, client, config) {
+    const action = command.path[1];
+    if (action === "list") {
+        const app = await resolveApp(command, client, config);
+        const body = await client.request("GET", `/apps/${encodeURIComponent(String(app.id))}/secrets`);
+        return { rows: body.secrets };
+    }
+    throw new Error(`Unknown secrets command: ${action ?? ""}`);
+}
+async function resolveApp(command, client, config) {
+    const target = stringFlag(command.flags.app) ?? config.appId;
+    if (!target)
+        throw new Error("Missing --app");
+    return client.request("GET", `/apps/lookup/${encodeURIComponent(target)}`);
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@vwork/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist/*.js",
+    "dist/auth/*.js",
+    "package.json"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "bin": {
+    "vwork": "dist/index.js"
+  },
+  "dependencies": {
+    "@oclif/core": "^4.11.7",
+    "@vwork/platform-client": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc -p tsconfig.json",
+    "test": "pnpm --filter @vwork/platform-client build && tsx --test src/test/*.test.ts",
+    "typecheck": "pnpm --filter @vwork/platform-client build && tsc -p tsconfig.json --noEmit"
+  }
+}