stage-ai 0.1.0 → 0.2.0

package/dist/commands/exec.d.ts

@@ -1,4 +1,4 @@
 import type { OutputOptions } from "../utils/output.js";
-export declare function exec(command: string, options: OutputOptions & {
+export declare function exec(_command: string, _options: OutputOptions & {
     session?: string;
 }): Promise<void>;

package/dist/commands/exec.js

@@ -1,34 +1,7 @@
-import { stagePost } from "../client.js";
-import { error, output } from "../utils/output.js";
+import { error } from "../utils/output.js";
 import { EXIT_ERROR } from "../utils/exit-codes.js";
-export async function exec(command, options) {
-    const sessionId = options.session;
-    try {
-        const result = await stagePost("/api/stage/exec", { command }, sessionId);
-        output(options, {
-            json: () => ({
-                stdout: result.stdout,
-                stderr: result.stderr,
-                exitCode: result.exitCode,
-                session: sessionId,
-            }),
-            quiet: () => {
-                if (result.stdout)
-                    process.stdout.write(result.stdout);
-                process.exit(result.exitCode);
-            },
-            human: () => {
-                if (result.stdout)
-                    process.stdout.write(result.stdout);
-                if (result.stderr)
-                    process.stderr.write(result.stderr);
-                if (result.exitCode !== 0)
-                    process.exit(result.exitCode);
-            },
-        });
-    }
-    catch (e) {
-        error(e.message);
-        process.exit(EXIT_ERROR);
-    }
+export async function exec(_command, _options) {
+    error("exec command is not supported with Convex backend");
+    error("Use 'stage ls' to list files, or write/read files directly");
+    process.exit(EXIT_ERROR);
 }

package/dist/commands/ls.js

@@ -1,25 +1,28 @@
-import { stagePost } from "../client.js";
+import { getAllFiles } from "../convex-client.js";
 import { error, output } from "../utils/output.js";
 import { EXIT_ERROR } from "../utils/exit-codes.js";
 export async function ls(remotePath, options) {
     const sessionId = options.session;
     const dir = remotePath || "/app";
     try {
-        const result = await stagePost("/api/stage/exec", { command: `find ${dir} -type f 2>/dev/null | sort` }, sessionId);
-        const files = (result.stdout || "").trim();
-        const list = files ? files.split("\n") : [];
+        const files = await getAllFiles(sessionId);
+        // Filter by directory if specified
+        const filtered = files
+            .filter(f => f.path.startsWith(dir))
+            .map(f => f.path)
+            .sort();
         output(options, {
-            json: () => ({ path: dir, files: list, count: list.length, session: sessionId }),
+            json: () => ({ path: dir, files: filtered, count: filtered.length, session: sessionId }),
             quiet: () => {
-                if (files)
-                    process.stdout.write(files + "\n");
+                if (filtered.length)
+                    process.stdout.write(filtered.join("\n") + "\n");
             },
             human: () => {
-                if (!list.length) {
+                if (!filtered.length) {
                     console.log("(empty)");
                     return;
                 }
-                for (const f of list) {
+                for (const f of filtered) {
                     console.log(f);
                 }
             },

package/dist/commands/new.js

@@ -1,15 +1,34 @@
-import { getBaseUrl, stagePost } from "../client.js";
+import { createSession, getConvexConfig } from "../convex-client.js";
 import { error, output, success, hint } from "../utils/output.js";
 import { EXIT_ERROR } from "../utils/exit-codes.js";
 export async function newSession(options) {
     try {
-        const result = await stagePost("/api/stage/sessions", {});
-        const url = `${getBaseUrl()}/s/${result.id}`;
+        const sessionId = await createSession();
+        const config = getConvexConfig();
+        // Determine Stage UI URL
+        // For cloud: derive from Convex URL or use STAGE_URL
+        // For self-hosted: use STAGE_URL or default localhost
+        let stageUrl = process.env.STAGE_URL;
+        if (!stageUrl) {
+            if (config.isSelfHosted) {
+                stageUrl = "http://localhost:3000";
+            }
+            else {
+                // For cloud, try to derive from Convex URL or use a default
+                stageUrl = process.env.NEXT_PUBLIC_STAGE_URL || "http://localhost:3000";
+            }
+        }
+        const url = `${stageUrl}/s/${sessionId}`;
         output(options, {
-            json: () => ({ id: result.id, url }),
-            quiet: () => process.stdout.write(result.id),
+            json: () => ({
+                id: sessionId,
+                url,
+                convexUrl: config.url,
+                mode: config.isSelfHosted ? "self-hosted" : "cloud",
+            }),
+            quiet: () => process.stdout.write(sessionId),
             human: () => {
-                success(`Session created: ${result.id}`);
+                success(`Session created: ${sessionId}`);
                 hint(`URL: ${url}`);
             },
         });

package/dist/commands/push.js

@@ -1,6 +1,6 @@
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join, relative, posix } from "node:path";
-import { stagePost } from "../client.js";
+import { writeFile, triggerRender } from "../convex-client.js";
 import { error, output, success, dim, bullet } from "../utils/output.js";
 import { EXIT_ERROR, EXIT_USER_ERROR } from "../utils/exit-codes.js";
 function walkDir(dir) {
@@ -47,14 +47,17 @@ export async function push(localDir, remoteDir, options) {
         process.exit(EXIT_USER_ERROR);
     }
     try {
-        await stagePost("/api/stage/files", { files }, sessionId);
+        // Write all files to Convex
+        const paths = Object.keys(files);
+        for (const remotePath of paths) {
+            await writeFile(sessionId, remotePath, files[remotePath]);
+        }
         let version;
         if (options.render !== false) {
             const entry = options.entry || `${targetDir}/App.tsx`;
-            const renderResult = await stagePost("/api/stage/render", { entry }, sessionId);
+            const renderResult = await triggerRender(sessionId, entry);
             version = renderResult.version;
         }
-        const paths = Object.keys(files);
         output(options, {
             json: () => ({
                 success: true,

package/dist/commands/read.js

@@ -1,16 +1,16 @@
-import { stageGet } from "../client.js";
+import { readFile } from "../convex-client.js";
 import { error, output } from "../utils/output.js";
 import { EXIT_ERROR, EXIT_NOT_FOUND } from "../utils/exit-codes.js";
 export async function read(remotePath, options) {
     const sessionId = options.session;
     try {
-        const result = await stageGet(`/api/stage/files?path=${encodeURIComponent(remotePath)}`, sessionId);
-        if (result.error) {
-            error(result.error);
+        const result = await readFile(sessionId, remotePath);
+        if (!result) {
+            error(`File not found: ${remotePath}`);
             process.exit(EXIT_NOT_FOUND);
         }
         output(options, {
-            json: () => ({ path: remotePath, content: result.content, session: sessionId }),
+            json: () => ({ path: remotePath, content: result.content, version: result.version, session: sessionId }),
             quiet: () => process.stdout.write(result.content),
             human: () => process.stdout.write(result.content),
         });

package/dist/commands/render.js

@@ -1,20 +1,20 @@
-import { stagePost } from "../client.js";
+import { triggerRender } from "../convex-client.js";
 import { error, output, success, dim } from "../utils/output.js";
 import { EXIT_ERROR } from "../utils/exit-codes.js";
 export async function render(entry, options) {
     const sessionId = options.session;
     const entryPoint = entry || "/app/App.tsx";
     try {
-        const result = await stagePost("/api/stage/render", { entry: entryPoint }, sessionId);
+        const result = await triggerRender(sessionId, entryPoint);
         output(options, {
             json: () => ({
                 success: true,
-                entry: entryPoint,
+                entry: result.entry,
                 version: result.version,
                 session: sessionId,
             }),
             quiet: () => { },
-            human: () => success(`Rendered ${entryPoint} ${dim(`(v${result.version})`)}`),
+            human: () => success(`Rendered ${result.entry} ${dim(`(v${result.version})`)}`),
         });
     }
     catch (e) {

package/dist/commands/write.js

@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-import { stagePost } from "../client.js";
+import { writeFile } from "../convex-client.js";
 import { error, output, success } from "../utils/output.js";
 import { EXIT_ERROR, EXIT_USER_ERROR } from "../utils/exit-codes.js";
 export async function write(remotePath, localPath, options) {
@@ -26,11 +26,11 @@ export async function write(remotePath, localPath, options) {
         process.exit(EXIT_USER_ERROR);
     }
     try {
-        await stagePost("/api/stage/files", { files: { [remotePath]: content } }, sessionId);
+        const result = await writeFile(sessionId, remotePath, content);
         output(options, {
-            json: () => ({ success: true, path: remotePath, bytes: content.length, session: sessionId }),
+            json: () => ({ success: true, path: remotePath, bytes: content.length, version: result.version, session: sessionId }),
             quiet: () => { },
-            human: () => success(`${remotePath} (${content.length} bytes)`),
+            human: () => success(`${remotePath} (${content.length} bytes, v${result.version})`),
         });
     }
     catch (e) {

package/dist/convex-client.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Convex client for Stage CLI.
+ * Supports both Convex Cloud and self-hosted deployments.
+ *
+ * Environment variables:
+ *   Convex Cloud:
+ *     CONVEX_URL - Deployment URL (e.g., https://xxx.convex.cloud)
+ *
+ *   Self-hosted:
+ *     CONVEX_SELF_HOSTED_URL - Backend URL (e.g., http://127.0.0.1:3210)
+ *     CONVEX_SELF_HOSTED_ADMIN_KEY - Admin key for auth
+ */
+interface ConvexConfig {
+    url: string;
+    adminKey?: string;
+    isSelfHosted: boolean;
+}
+export declare function setConvexConfig(config: Partial<ConvexConfig>): void;
+export declare function getConvexConfig(): ConvexConfig;
+export declare function getConvexUrl(): string;
+export declare function setConvexUrl(url: string): void;
+export declare function createSession(): Promise<string>;
+export declare function writeFile(sessionId: string, path: string, content: string): Promise<{
+    path: string;
+    version: number;
+    size: number;
+}>;
+export declare function readFile(sessionId: string, path: string): Promise<{
+    path: string;
+    content: string;
+    version?: number;
+} | null>;
+export declare function getAllFiles(sessionId: string): Promise<Array<{
+    path: string;
+    content: string;
+    version?: number;
+}>>;
+export declare function triggerRender(sessionId: string, entry?: string): Promise<{
+    entry: string;
+    version: number;
+}>;
+export declare function getRenderState(sessionId: string): Promise<{
+    entry: string;
+    version: number;
+} | null>;
+export declare function createSnapshot(sessionId: string, name?: string): Promise<string>;
+export declare function getSnapshots(sessionId: string): Promise<Array<{
+    name?: string;
+    createdAt: number;
+}>>;
+export declare function getFileHistory(sessionId: string, path: string): Promise<Array<{
+    version?: number;
+    createdAt?: number;
+}>>;
+export declare function printConfig(): void;
+export {};

package/dist/convex-client.js

@@ -0,0 +1,144 @@
+/**
+ * Convex client for Stage CLI.
+ * Supports both Convex Cloud and self-hosted deployments.
+ *
+ * Environment variables:
+ *   Convex Cloud:
+ *     CONVEX_URL - Deployment URL (e.g., https://xxx.convex.cloud)
+ *
+ *   Self-hosted:
+ *     CONVEX_SELF_HOSTED_URL - Backend URL (e.g., http://127.0.0.1:3210)
+ *     CONVEX_SELF_HOSTED_ADMIN_KEY - Admin key for auth
+ */
+let _configOverride = null;
+export function setConvexConfig(config) {
+    _configOverride = config;
+}
+export function getConvexConfig() {
+    // Check for overrides first
+    if (_configOverride?.url) {
+        return {
+            url: _configOverride.url,
+            adminKey: _configOverride.adminKey,
+            isSelfHosted: _configOverride.isSelfHosted ?? true,
+        };
+    }
+    // Check for Convex Cloud
+    const cloudUrl = process.env.CONVEX_URL;
+    if (cloudUrl) {
+        return {
+            url: cloudUrl,
+            isSelfHosted: false,
+        };
+    }
+    // Check for self-hosted
+    const selfHostedUrl = process.env.CONVEX_SELF_HOSTED_URL;
+    const selfHostedKey = process.env.CONVEX_SELF_HOSTED_ADMIN_KEY;
+    if (selfHostedUrl) {
+        return {
+            url: selfHostedUrl,
+            adminKey: selfHostedKey,
+            isSelfHosted: true,
+        };
+    }
+    // Default to local self-hosted
+    return {
+        url: "http://127.0.0.1:3210",
+        isSelfHosted: true,
+    };
+}
+export function getConvexUrl() {
+    return getConvexConfig().url;
+}
+// For backwards compatibility
+export function setConvexUrl(url) {
+    setConvexConfig({ url, isSelfHosted: true });
+}
+// Generic mutation/query helpers
+async function mutation(path, args) {
+    const config = getConvexConfig();
+    const url = `${config.url}/api/mutation`;
+    const headers = {
+        "Content-Type": "application/json"
+    };
+    // Add admin key for self-hosted
+    if (config.isSelfHosted && config.adminKey) {
+        headers["Authorization"] = `Convex ${config.adminKey}`;
+    }
+    const res = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ path: `stage:${path}`, args }),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Convex error ${res.status}: ${text}`);
+    }
+    const data = await res.json();
+    if (data.status === "error") {
+        throw new Error(data.errorMessage || "Unknown error");
+    }
+    return data.value;
+}
+async function query(path, args) {
+    const config = getConvexConfig();
+    const url = `${config.url}/api/query`;
+    const headers = {
+        "Content-Type": "application/json"
+    };
+    // Add admin key for self-hosted
+    if (config.isSelfHosted && config.adminKey) {
+        headers["Authorization"] = `Convex ${config.adminKey}`;
+    }
+    const res = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ path: `stage:${path}`, args }),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Convex error ${res.status}: ${text}`);
+    }
+    const data = await res.json();
+    if (data.status === "error") {
+        throw new Error(data.errorMessage || "Unknown error");
+    }
+    return data.value;
+}
+// Stage API
+export async function createSession() {
+    return await mutation("createSession", {});
+}
+export async function writeFile(sessionId, path, content) {
+    return await mutation("writeFile", { sessionId, path, content });
+}
+export async function readFile(sessionId, path) {
+    return await query("readFile", { sessionId, path });
+}
+export async function getAllFiles(sessionId) {
+    return await query("getAllFiles", { sessionId });
+}
+export async function triggerRender(sessionId, entry) {
+    return await mutation("triggerRender", { sessionId, entry });
+}
+export async function getRenderState(sessionId) {
+    return await query("getRenderState", { sessionId });
+}
+export async function createSnapshot(sessionId, name) {
+    return await mutation("createSnapshot", { sessionId, name });
+}
+export async function getSnapshots(sessionId) {
+    return await query("getSnapshots", { sessionId });
+}
+export async function getFileHistory(sessionId, path) {
+    return await query("getFileHistory", { sessionId, path });
+}
+// Helper to show current config
+export function printConfig() {
+    const config = getConvexConfig();
+    console.log(`Mode: ${config.isSelfHosted ? "self-hosted" : "cloud"}`);
+    console.log(`URL: ${config.url}`);
+    if (config.isSelfHosted && config.adminKey) {
+        console.log(`Admin key: ${config.adminKey.slice(0, 20)}...`);
+    }
+}

package/dist/main.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 import { Command } from "commander";
-import { setBaseUrl } from "./client.js";
+import { setConvexConfig, printConfig } from "./convex-client.js";
 import { newSession } from "./commands/new.js";
 import { write } from "./commands/write.js";
 import { read } from "./commands/read.js";
@@ -15,11 +15,25 @@ const { version } = require("../package.json");
 const program = new Command();
 program
     .name("stage")
-    .description("CLI client for Stage — a sandboxed React runtime for AI agents")
+    .description(`CLI client for Stage — a sandboxed React runtime for AI agents
+
+Environment variables:
+  CONVEX_URL                    Convex Cloud deployment URL
+  CONVEX_SELF_HOSTED_URL        Self-hosted Convex URL
+  CONVEX_SELF_HOSTED_ADMIN_KEY  Self-hosted admin key
+  STAGE_URL                     Stage frontend URL (for session links)`)
     .version(`stage ${version}`, "-v, --version")
     .option("--json", "Output as JSON")
     .option("-q, --quiet", "Suppress output")
-    .option("-u, --url <url>", "Stage server URL (default: $STAGE_URL or http://localhost:3000)");
+    .option("-u, --url <url>", "Convex URL (overrides env vars)")
+    .option("--self-hosted", "Force self-hosted mode")
+    .option("--cloud", "Force cloud mode");
+program
+    .command("config")
+    .description("Show current Convex configuration")
+    .action(() => {
+    printConfig();
+});
 program
     .command("new")
     .description("Create a new session")
@@ -45,7 +59,7 @@ program
 });
 program
     .command("exec <command>")
-    .description("Run a bash command in Stage's virtual FS")
+    .description("[DEPRECATED] Not supported with Convex backend")
     .requiredOption("-s, --session <id>", "Session ID")
     .action(async (command, opts, cmd) => {
     const root = cmd.optsWithGlobals();
@@ -61,7 +75,7 @@ program
 });
 program
     .command("ls [path]")
-    .description("List files in Stage's virtual FS")
+    .description("List files in session")
     .requiredOption("-s, --session <id>", "Session ID")
     .action(async (path, opts, cmd) => {
     const root = cmd.optsWithGlobals();
@@ -92,8 +106,21 @@ program
 });
 program.hook("preAction", (_thisCommand, actionCommand) => {
     const root = actionCommand.optsWithGlobals();
-    if (root.url)
-        setBaseUrl(root.url);
+    // Configure Convex client based on flags
+    if (root.url) {
+        const isSelfHosted = root.selfHosted || (!root.cloud && !root.url.includes("convex.cloud"));
+        setConvexConfig({
+            url: root.url,
+            isSelfHosted,
+            adminKey: process.env.CONVEX_SELF_HOSTED_ADMIN_KEY,
+        });
+    }
+    else if (root.cloud) {
+        setConvexConfig({ isSelfHosted: false });
+    }
+    else if (root.selfHosted) {
+        setConvexConfig({ isSelfHosted: true });
+    }
 });
 program.parseAsync(process.argv).catch((err) => {
     console.error("Fatal error:", err.message);

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "stage-ai",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI client for Stage — a sandboxed React runtime for AI-generated applications",
   "type": "module",
   "main": "dist/main.js",
   "bin": {
     "stage": "./dist/main.js"
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build",
@@ -29,14 +31,24 @@
   "bugs": {
     "url": "https://github.com/the-shift-dev/stage-cli/issues"
   },
-  "keywords": ["ai", "agent", "sandbox", "react", "runtime", "cli", "stage"],
+  "keywords": [
+    "ai",
+    "agent",
+    "sandbox",
+    "react",
+    "runtime",
+    "cli",
+    "stage"
+  ],
   "license": "MIT",
   "devDependencies": {
     "@biomejs/biome": "^2.3.14",
+    "@types/node": "^25.3.3",
     "typescript": "^5.8.0"
   },
   "dependencies": {
     "chalk": "^5.6.2",
-    "commander": "^14.0.3"
+    "commander": "^14.0.3",
+    "convex": "^1.32.0"
   }
 }