stage-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Liv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# stage-cli
+
+> CLI client for [Stage](https://github.com/the-shift-dev/stage) — a sandboxed React runtime for AI agents.
+
+Write files, run commands, and render React components in Stage's virtual filesystem. From the terminal. From any agent.
+
+## Install
+
+```bash
+npm install -g stage-cli
+```
+
+## Quick Start
+
+```bash
+# Create a session
+stage new
+# ✓ Session created: abc123
+#   URL: http://localhost:3000/s/abc123
+
+# Write a component
+stage write /app/App.tsx ./App.tsx --session abc123
+
+# Render it
+stage render --session abc123
+
+# Push a whole project
+stage push ./my-app /app --session abc123
+```
+
+Every command requires `--session <id>`. Create one with `stage new`.
+
+## Commands
+
+### `stage new`
+
+Create a new session. Each session gets its own isolated virtual filesystem.
+
+```bash
+stage new
+stage new --json    # { "id": "abc123", "url": "http://localhost:3000/s/abc123" }
+stage new -q        # prints just the ID
+```
+
+### `stage write <remote-path> [local-file] --session <id>`
+
+Write a file to Stage's virtual FS. Reads from a local file or stdin (`-`).
+
+```bash
+stage write /app/App.tsx ./App.tsx --session abc123
+echo '<h1>Hi</h1>' | stage write /app/App.tsx - --session abc123
+```
+
+### `stage read <remote-path> --session <id>`
+
+Read a file from Stage.
+
+```bash
+stage read /app/App.tsx --session abc123
+```
+
+### `stage exec <command> --session <id>`
+
+Run a bash command in Stage's virtual filesystem.
+
+```bash
+stage exec "ls /app" --session abc123
+stage exec "cat /app/App.tsx | grep import" --session abc123
+```
+
+### `stage render [entry] --session <id>`
+
+Trigger Stage to render a component. Defaults to `/app/App.tsx`.
+
+```bash
+stage render --session abc123                     # renders /app/App.tsx
+stage render /app/Dashboard.tsx --session abc123   # renders specific entry
+```
+
+### `stage ls [path] --session <id>`
+
+List files in Stage's virtual FS.
+
+```bash
+stage ls --session abc123            # list /app
+stage ls /app/src --session abc123   # list subdirectory
+```
+
+### `stage push <local-dir> [remote-dir] --session <id>`
+
+Push a local directory to Stage and auto-render.
+
+```bash
+stage push ./my-app --session abc123                    # push to /app
+stage push ./src /app/src --session abc123              # push to specific dir
+stage push ./my-app -e /app/Main.tsx --session abc123   # custom entry point
+stage push ./my-app --no-render --session abc123        # skip auto-render
+```
+
+### `stage onboard`
+
+Add Stage instructions to `CLAUDE.md` or `AGENTS.md` so agents know how to use it.
+
+```bash
+stage onboard
+```
+
+## For Agents
+
+Every command supports `--json` for structured output:
+
+```bash
+stage ls --json --session abc123
+# { "path": "/app", "files": ["/app/App.tsx"], "count": 1, "session": "abc123" }
+
+stage exec "ls /app" --json --session abc123
+# { "stdout": "App.tsx\n", "stderr": "", "exitCode": 0, "session": "abc123" }
+```
+
+Run `stage onboard` in your project to teach agents the commands.
+
+## Configuration
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `STAGE_URL` | `http://localhost:3000` | Stage server URL |
+
+## Available Libraries in Stage
+
+Components rendered in Stage have access to:
+
+- React (hooks, JSX)
+- [shadcn/ui](https://ui.shadcn.com/) (Card, Button, Badge, Tabs, etc.)
+- [Recharts](https://recharts.org/) (BarChart, LineChart, PieChart, etc.)
+- [Lodash](https://lodash.com/)
+- [PapaParse](https://www.papaparse.com/) (CSV parsing)
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Stage API client.
+ * Talks to the Stage server over HTTP.
+ */
+export declare function setBaseUrl(url: string): void;
+export declare function getBaseUrl(): string;
+export declare function stagePost(path: string, body: unknown, sessionId?: string): Promise<any>;
+export declare function stageGet(path: string, sessionId?: string): Promise<any>;
+export declare function stageDelete(path: string): Promise<any>;

package/dist/client.js

@@ -0,0 +1,54 @@
+/**
+ * Stage API client.
+ * Talks to the Stage server over HTTP.
+ */
+let _urlOverride;
+export function setBaseUrl(url) {
+    _urlOverride = url;
+}
+export function getBaseUrl() {
+    return _urlOverride || process.env.STAGE_URL || "http://localhost:3000";
+}
+function sessionHeaders(sessionId) {
+    return {
+        "Content-Type": "application/json",
+        "X-Stage-Session": sessionId,
+    };
+}
+export async function stagePost(path, body, sessionId) {
+    const url = `${getBaseUrl()}${path}`;
+    const headers = sessionId
+        ? sessionHeaders(sessionId)
+        : { "Content-Type": "application/json" };
+    const res = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Stage ${res.status}: ${text}`);
+    }
+    return res.json();
+}
+export async function stageGet(path, sessionId) {
+    const url = `${getBaseUrl()}${path}`;
+    const headers = sessionId
+        ? { "X-Stage-Session": sessionId }
+        : {};
+    const res = await fetch(url, { headers });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Stage ${res.status}: ${text}`);
+    }
+    return res.json();
+}
+export async function stageDelete(path) {
+    const url = `${getBaseUrl()}${path}`;
+    const res = await fetch(url, { method: "DELETE" });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Stage ${res.status}: ${text}`);
+    }
+    return res.json();
+}

package/dist/commands/exec.d.ts

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

package/dist/commands/exec.js

@@ -0,0 +1,34 @@
+import { stagePost } from "../client.js";
+import { error, output } 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);
+    }
+}

package/dist/commands/ls.d.ts

@@ -0,0 +1,4 @@
+import type { OutputOptions } from "../utils/output.js";
+export declare function ls(remotePath: string | undefined, options: OutputOptions & {
+    session?: string;
+}): Promise<void>;

package/dist/commands/ls.js

@@ -0,0 +1,32 @@
+import { stagePost } from "../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") : [];
+        output(options, {
+            json: () => ({ path: dir, files: list, count: list.length, session: sessionId }),
+            quiet: () => {
+                if (files)
+                    process.stdout.write(files + "\n");
+            },
+            human: () => {
+                if (!list.length) {
+                    console.log("(empty)");
+                    return;
+                }
+                for (const f of list) {
+                    console.log(f);
+                }
+            },
+        });
+    }
+    catch (e) {
+        error(e.message);
+        process.exit(EXIT_ERROR);
+    }
+}

package/dist/commands/new.d.ts

@@ -0,0 +1,2 @@
+import type { OutputOptions } from "../utils/output.js";
+export declare function newSession(options: OutputOptions): Promise<void>;

package/dist/commands/new.js

@@ -0,0 +1,21 @@
+import { getBaseUrl, stagePost } from "../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}`;
+        output(options, {
+            json: () => ({ id: result.id, url }),
+            quiet: () => process.stdout.write(result.id),
+            human: () => {
+                success(`Session created: ${result.id}`);
+                hint(`URL: ${url}`);
+            },
+        });
+    }
+    catch (e) {
+        error(e.message);
+        process.exit(EXIT_ERROR);
+    }
+}

package/dist/commands/onboard.d.ts

@@ -0,0 +1,2 @@
+import type { OutputOptions } from "../utils/output.js";
+export declare function onboard(_args: string[], options: OutputOptions): Promise<void>;

package/dist/commands/onboard.js

@@ -0,0 +1,69 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { output, success } from "../utils/output.js";
+const INSTRUCTIONS = `
+<stage>
+Use \`stage\` to write, read, and render files in Stage — a sandboxed React runtime.
+Stage renders React components live in the browser. No build step, no deploy.
+
+<commands>
+- \`stage new\` — create a new session, returns session ID
+- \`stage write <remote-path> <local-file> --session <id>\` — write a local file to Stage's virtual FS
+- \`stage read <remote-path> --session <id>\` — read a file from Stage
+- \`stage exec "<command>" --session <id>\` — run a bash command in Stage's virtual FS
+- \`stage render [entry] --session <id>\` — trigger Stage to render (default: /app/App.tsx)
+- \`stage ls [path] --session <id>\` — list files in Stage's virtual FS
+- \`stage push <local-dir> [remote-dir] --session <id>\` — push a directory to Stage and render
+</commands>
+
+<rules>
+- ALWAYS pass \`--session <id>\` on every command (create one with \`stage new\`)
+- Use \`--json\` for structured output
+- Remote paths are absolute (e.g. /app/App.tsx)
+- Entry point must default-export a React component
+- Available libraries: React, shadcn/ui, recharts, lodash, papaparse
+- Set server with \`-u <url>\` flag or STAGE_URL env var (default: http://localhost:3000)
+</rules>
+</stage>
+`.trim();
+const MARKER = "<stage>";
+export async function onboard(_args, options) {
+    const cwd = process.cwd();
+    const claudeMd = join(cwd, "CLAUDE.md");
+    const agentsMd = join(cwd, "AGENTS.md");
+    let targetFile;
+    if (existsSync(claudeMd)) {
+        targetFile = claudeMd;
+    }
+    else if (existsSync(agentsMd)) {
+        targetFile = agentsMd;
+    }
+    else {
+        targetFile = claudeMd;
+    }
+    let existingContent = "";
+    if (existsSync(targetFile)) {
+        existingContent = readFileSync(targetFile, "utf-8");
+    }
+    if (existingContent.includes(MARKER)) {
+        output(options, {
+            json: () => ({
+                success: true,
+                file: targetFile,
+                message: "already_onboarded",
+            }),
+            human: () => success(`Already onboarded (${targetFile})`),
+        });
+        return;
+    }
+    if (existingContent) {
+        writeFileSync(targetFile, `${existingContent.trimEnd()}\n\n${INSTRUCTIONS}\n`);
+    }
+    else {
+        writeFileSync(targetFile, `${INSTRUCTIONS}\n`);
+    }
+    output(options, {
+        json: () => ({ success: true, file: targetFile }),
+        human: () => success(`Added stage instructions to ${targetFile}`),
+    });
+}

package/dist/commands/push.d.ts

@@ -0,0 +1,6 @@
+import type { OutputOptions } from "../utils/output.js";
+export declare function push(localDir: string, remoteDir: string | undefined, options: OutputOptions & {
+    session?: string;
+    entry?: string;
+    render?: boolean;
+}): Promise<void>;

package/dist/commands/push.js

@@ -0,0 +1,82 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, posix } from "node:path";
+import { stagePost } from "../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) {
+    const results = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.name === "node_modules" || entry.name.startsWith("."))
+            continue;
+        if (entry.isDirectory()) {
+            results.push(...walkDir(full));
+        }
+        else {
+            results.push(full);
+        }
+    }
+    return results;
+}
+export async function push(localDir, remoteDir, options) {
+    const sessionId = options.session;
+    const targetDir = remoteDir || "/app";
+    let stat;
+    try {
+        stat = statSync(localDir);
+    }
+    catch {
+        error(`Cannot read ${localDir}`);
+        process.exit(EXIT_USER_ERROR);
+    }
+    const files = {};
+    if (stat.isFile()) {
+        const name = localDir.split("/").pop();
+        const remotePath = posix.join(targetDir, name);
+        files[remotePath] = readFileSync(localDir, "utf-8");
+    }
+    else if (stat.isDirectory()) {
+        for (const localPath of walkDir(localDir)) {
+            const rel = relative(localDir, localPath);
+            const remotePath = posix.join(targetDir, ...rel.split("/"));
+            files[remotePath] = readFileSync(localPath, "utf-8");
+        }
+    }
+    if (!Object.keys(files).length) {
+        error("No files found");
+        process.exit(EXIT_USER_ERROR);
+    }
+    try {
+        await stagePost("/api/stage/files", { files }, sessionId);
+        let version;
+        if (options.render !== false) {
+            const entry = options.entry || `${targetDir}/App.tsx`;
+            const renderResult = await stagePost("/api/stage/render", { entry }, sessionId);
+            version = renderResult.version;
+        }
+        const paths = Object.keys(files);
+        output(options, {
+            json: () => ({
+                success: true,
+                files: paths,
+                count: paths.length,
+                version,
+                session: sessionId,
+            }),
+            quiet: () => { },
+            human: () => {
+                success(`Pushed ${paths.length} file${paths.length === 1 ? "" : "s"} to ${targetDir}`);
+                for (const p of paths) {
+                    bullet(dim(p));
+                }
+                if (version !== undefined) {
+                    success(`Rendered ${dim(`(v${version})`)}`);
+                }
+            },
+        });
+    }
+    catch (e) {
+        error(e.message);
+        process.exit(EXIT_ERROR);
+    }
+}

package/dist/commands/read.d.ts

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

package/dist/commands/read.js

@@ -0,0 +1,22 @@
+import { stageGet } from "../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);
+            process.exit(EXIT_NOT_FOUND);
+        }
+        output(options, {
+            json: () => ({ path: remotePath, content: result.content, session: sessionId }),
+            quiet: () => process.stdout.write(result.content),
+            human: () => process.stdout.write(result.content),
+        });
+    }
+    catch (e) {
+        error(e.message);
+        process.exit(EXIT_ERROR);
+    }
+}

package/dist/commands/render.d.ts

@@ -0,0 +1,4 @@
+import type { OutputOptions } from "../utils/output.js";
+export declare function render(entry: string | undefined, options: OutputOptions & {
+    session?: string;
+}): Promise<void>;

package/dist/commands/render.js

@@ -0,0 +1,24 @@
+import { stagePost } from "../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);
+        output(options, {
+            json: () => ({
+                success: true,
+                entry: entryPoint,
+                version: result.version,
+                session: sessionId,
+            }),
+            quiet: () => { },
+            human: () => success(`Rendered ${entryPoint} ${dim(`(v${result.version})`)}`),
+        });
+    }
+    catch (e) {
+        error(e.message);
+        process.exit(EXIT_ERROR);
+    }
+}

package/dist/commands/write.d.ts

@@ -0,0 +1,4 @@
+import type { OutputOptions } from "../utils/output.js";
+export declare function write(remotePath: string, localPath: string | undefined, options: OutputOptions & {
+    session?: string;
+}): Promise<void>;

package/dist/commands/write.js

@@ -0,0 +1,40 @@
+import { readFileSync } from "node:fs";
+import { stagePost } from "../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) {
+    const sessionId = options.session;
+    let content;
+    if (localPath === "-" || (!localPath && !process.stdin.isTTY)) {
+        const chunks = [];
+        for await (const chunk of process.stdin) {
+            chunks.push(chunk);
+        }
+        content = Buffer.concat(chunks).toString("utf-8");
+    }
+    else if (localPath) {
+        try {
+            content = readFileSync(localPath, "utf-8");
+        }
+        catch (e) {
+            error(`Cannot read ${localPath}: ${e.message}`);
+            process.exit(EXIT_USER_ERROR);
+        }
+    }
+    else {
+        error("Provide a local file path or pipe content via stdin");
+        process.exit(EXIT_USER_ERROR);
+    }
+    try {
+        await stagePost("/api/stage/files", { files: { [remotePath]: content } }, sessionId);
+        output(options, {
+            json: () => ({ success: true, path: remotePath, bytes: content.length, session: sessionId }),
+            quiet: () => { },
+            human: () => success(`${remotePath} (${content.length} bytes)`),
+        });
+    }
+    catch (e) {
+        error(e.message);
+        process.exit(EXIT_ERROR);
+    }
+}

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { Command } from "commander";
+import { setBaseUrl } from "./client.js";
+import { newSession } from "./commands/new.js";
+import { write } from "./commands/write.js";
+import { read } from "./commands/read.js";
+import { exec } from "./commands/exec.js";
+import { render } from "./commands/render.js";
+import { ls } from "./commands/ls.js";
+import { push } from "./commands/push.js";
+import { onboard } from "./commands/onboard.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+const program = new Command();
+program
+    .name("stage")
+    .description("CLI client for Stage — a sandboxed React runtime for AI agents")
+    .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)");
+program
+    .command("new")
+    .description("Create a new session")
+    .action(async (_opts, cmd) => {
+    const root = cmd.optsWithGlobals();
+    await newSession({ json: root.json, quiet: root.quiet });
+});
+program
+    .command("write <remote-path> [local-file]")
+    .description("Write a file to Stage (from local file or stdin)")
+    .requiredOption("-s, --session <id>", "Session ID")
+    .action(async (remotePath, localFile, opts, cmd) => {
+    const root = cmd.optsWithGlobals();
+    await write(remotePath, localFile, { json: root.json, quiet: root.quiet, session: opts.session });
+});
+program
+    .command("read <remote-path>")
+    .description("Read a file from Stage")
+    .requiredOption("-s, --session <id>", "Session ID")
+    .action(async (remotePath, opts, cmd) => {
+    const root = cmd.optsWithGlobals();
+    await read(remotePath, { json: root.json, quiet: root.quiet, session: opts.session });
+});
+program
+    .command("exec <command>")
+    .description("Run a bash command in Stage's virtual FS")
+    .requiredOption("-s, --session <id>", "Session ID")
+    .action(async (command, opts, cmd) => {
+    const root = cmd.optsWithGlobals();
+    await exec(command, { json: root.json, quiet: root.quiet, session: opts.session });
+});
+program
+    .command("render [entry]")
+    .description("Trigger Stage to render a component (default: /app/App.tsx)")
+    .requiredOption("-s, --session <id>", "Session ID")
+    .action(async (entry, opts, cmd) => {
+    const root = cmd.optsWithGlobals();
+    await render(entry, { json: root.json, quiet: root.quiet, session: opts.session });
+});
+program
+    .command("ls [path]")
+    .description("List files in Stage's virtual FS")
+    .requiredOption("-s, --session <id>", "Session ID")
+    .action(async (path, opts, cmd) => {
+    const root = cmd.optsWithGlobals();
+    await ls(path, { json: root.json, quiet: root.quiet, session: opts.session });
+});
+program
+    .command("push <local-dir> [remote-dir]")
+    .description("Push a local directory to Stage and render")
+    .requiredOption("-s, --session <id>", "Session ID")
+    .option("-e, --entry <path>", "Entry point to render")
+    .option("--no-render", "Skip auto-render after push")
+    .action(async (localDir, remoteDir, opts, cmd) => {
+    const root = cmd.optsWithGlobals();
+    await push(localDir, remoteDir, {
+        json: root.json,
+        quiet: root.quiet,
+        session: opts.session,
+        entry: opts.entry,
+        render: opts.render,
+    });
+});
+program
+    .command("onboard")
+    .description("Add stage instructions to CLAUDE.md or AGENTS.md")
+    .action(async (_opts, cmd) => {
+    const root = cmd.optsWithGlobals();
+    await onboard([], { json: root.json, quiet: root.quiet });
+});
+program.hook("preAction", (_thisCommand, actionCommand) => {
+    const root = actionCommand.optsWithGlobals();
+    if (root.url)
+        setBaseUrl(root.url);
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error("Fatal error:", err.message);
+    process.exit(1);
+});

package/dist/utils/exit-codes.d.ts

@@ -0,0 +1,5 @@
+export declare const EXIT_SUCCESS = 0;
+export declare const EXIT_ERROR = 1;
+export declare const EXIT_USER_ERROR = 2;
+export declare const EXIT_NOT_FOUND = 3;
+export declare const EXIT_CONNECTION = 4;

package/dist/utils/exit-codes.js

@@ -0,0 +1,5 @@
+export const EXIT_SUCCESS = 0;
+export const EXIT_ERROR = 1;
+export const EXIT_USER_ERROR = 2;
+export const EXIT_NOT_FOUND = 3;
+export const EXIT_CONNECTION = 4; // Stage server unreachable

package/dist/utils/output.d.ts

@@ -0,0 +1,22 @@
+export interface OutputOptions {
+    json?: boolean;
+    quiet?: boolean;
+}
+export declare const success: (msg: string) => void;
+export declare const info: (msg: string) => void;
+export declare const warn: (msg: string) => void;
+export declare const error: (msg: string) => void;
+export declare const bold: (s: string) => string;
+export declare const dim: (s: string) => string;
+export declare const cmd: (s: string) => string;
+export declare const bullet: (msg: string) => void;
+export declare const bulletDim: (msg: string) => void;
+export declare const hint: (msg: string) => void;
+export declare const nextStep: (command: string) => void;
+export declare const header: (title: string) => void;
+export declare function jsonOutput(data: object): void;
+export declare function output(options: OutputOptions, handlers: {
+    json?: () => object;
+    quiet?: () => void;
+    human: () => void;
+}): void;

package/dist/utils/output.js

@@ -0,0 +1,31 @@
+import chalk from "chalk";
+export const success = (msg) => console.log(chalk.green("✓"), msg);
+export const info = (msg) => console.log(chalk.blue("ℹ"), msg);
+export const warn = (msg) => console.log(chalk.yellow("⚠"), msg);
+export const error = (msg) => console.error(chalk.red("✗"), msg);
+export const bold = (s) => chalk.bold(s);
+export const dim = (s) => chalk.dim(s);
+export const cmd = (s) => chalk.cyan(s);
+export const bullet = (msg) => console.log(chalk.green("●"), msg);
+export const bulletDim = (msg) => console.log(chalk.dim("●"), msg);
+export const hint = (msg) => console.log(chalk.dim(`  ${msg}`));
+export const nextStep = (command) => console.log(`  ${cmd(command)}`);
+export const header = (title) => {
+    console.log();
+    console.log(chalk.bold(title));
+    console.log();
+};
+export function jsonOutput(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+export function output(options, handlers) {
+    if (options.json && handlers.json) {
+        jsonOutput(handlers.json());
+    }
+    else if (options.quiet && handlers.quiet) {
+        handlers.quiet();
+    }
+    else {
+        handlers.human();
+    }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "stage-ai",
+  "version": "0.1.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"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "dev": "bun run src/main.ts",
+    "build:bun": "bun build --compile src/main.ts --outfile stage",
+    "build:bun-linux": "bun build --compile --target=bun-linux-x64 src/main.ts --outfile stage-linux-x64",
+    "build:bun-mac-arm": "bun build --compile --target=bun-darwin-arm64 src/main.ts --outfile stage-darwin-arm64",
+    "build:bun-mac-x64": "bun build --compile --target=bun-darwin-x64 src/main.ts --outfile stage-darwin-x64",
+    "test": "bun test",
+    "format": "bunx biome format --write src/",
+    "lint": "bunx biome lint src/",
+    "check": "bunx biome check src/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/the-shift-dev/stage-cli.git"
+  },
+  "homepage": "https://github.com/the-shift-dev/stage-cli#readme",
+  "bugs": {
+    "url": "https://github.com/the-shift-dev/stage-cli/issues"
+  },
+  "keywords": ["ai", "agent", "sandbox", "react", "runtime", "cli", "stage"],
+  "license": "MIT",
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "typescript": "^5.8.0"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3"
+  }
+}