@lotics/cli 0.18.0 → 0.20.0

package/dist/src/app_commands.d.ts

@@ -0,0 +1,45 @@
+import { LoticsClient } from "./client.js";
+/**
+ * `lotics app create <name> [path]`
+ *
+ * Creates the app server-side, scaffolds a Vite+React+TS project locally
+ * from the embedded starter template, runs `npm install` + `npm run build`,
+ * then deploys the result as v1. After this returns, `lotics app deploy`
+ * works end-to-end on the same directory.
+ *
+ * Why scaffold + deploy rather than pull-from-server-starter: the deploy
+ * pipeline requires a built dist tree, and v1 doesn't run builds server-side.
+ * Doing the build locally on first create keeps the platform infrastructure
+ * minimal — the starter template is embedded in the CLI binary and bumps
+ * with CLI releases. (Server-side build is the v2 path.)
+ */
+export declare function appCreate(client: LoticsClient, args: {
+    name: string;
+    targetPath?: string;
+}): Promise<void>;
+/**
+ * `lotics app pull <app_id> [path]`
+ *
+ * Bootstraps a full local dev environment for an existing app:
+ *   1. Fetch the current version's source archive from R2 (presigned URL).
+ *   2. Extract into the target directory.
+ *   3. Write package.json's `lotics` field with app_id + version metadata.
+ *   4. Run `npm install`.
+ *   5. (TODO) Generate `.lotics/types.ts` with workspace-typed augmentations.
+ */
+export declare function appPull(client: LoticsClient, args: {
+    app_id: string;
+    targetPath?: string;
+}): Promise<void>;
+/**
+ * `lotics app deploy [-m <message>]`
+ *
+ * Builds the project locally with `npm run build`, tars source + dist, and
+ * uploads to the deploy endpoint. The endpoint validates structure, stores
+ * both archives in R2, creates an app_versions row, and atomically advances
+ * the app's current_version pointer.
+ */
+export declare function appDeploy(client: LoticsClient, args: {
+    projectDir?: string;
+    message?: string;
+}): Promise<void>;

package/dist/src/app_commands.js

@@ -0,0 +1,246 @@
+/**
+ * `lotics app *` subcommands — create / pull / deploy.
+ *
+ * Apps are user-owned npm projects. Source-of-truth during editing is the
+ * local filesystem; the server stores deployed bundles (source.tar.gz + dist)
+ * in R2 keyed per version. These commands are the only sanctioned lifecycle
+ * surface — everything else (validate, logs, watch) folds into a flag on
+ * deploy or lives in the web UI.
+ *
+ * Tarball handling shells out to the system `tar` command. CLI users are
+ * developers; macOS/Linux/WSL all ship a working tar. Avoids adding a
+ * runtime dep to the published @lotics/cli package.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+import { buildStarterTemplate } from "./starter_template.js";
+/** Run `tar` and resolve when it exits cleanly. Throws with stderr on failure. */
+function runTar(args, cwd) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn("tar", args, { cwd, stdio: ["ignore", "ignore", "pipe"] });
+        let stderr = "";
+        proc.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        proc.on("error", reject);
+        proc.on("exit", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`tar ${args.join(" ")} failed with exit ${code}: ${stderr}`));
+        });
+    });
+}
+/** Run `npm` (run/install/etc.) inheriting stdio so the user sees progress. */
+function runNpm(args, cwd) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn("npm", args, { cwd, stdio: "inherit" });
+        proc.on("error", reject);
+        proc.on("exit", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`npm ${args.join(" ")} exited with code ${code}`));
+        });
+    });
+}
+function readAppMeta(projectDir) {
+    const pkgPath = path.join(projectDir, "package.json");
+    if (!fs.existsSync(pkgPath)) {
+        throw new Error(`No package.json found at ${projectDir}. Run 'lotics app create' first.`);
+    }
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    if (!pkg.lotics?.app_id || !pkg.lotics.workspace_id) {
+        throw new Error(`package.json is missing the 'lotics' field with app_id and workspace_id. ` +
+            `Was this folder created with 'lotics app create'?`);
+    }
+    return {
+        app_id: pkg.lotics.app_id,
+        workspace_id: pkg.lotics.workspace_id,
+        current_version_id: pkg.lotics.current_version_id ?? null,
+        version_number: pkg.lotics.version_number ?? null,
+        workflows: pkg.lotics.workflows ?? {},
+    };
+}
+function writeAppMeta(projectDir, meta) {
+    const pkgPath = path.join(projectDir, "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    pkg.lotics = meta;
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+}
+async function downloadToFile(url, destPath) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to download ${url}: ${response.status}`);
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    fs.writeFileSync(destPath, buffer);
+}
+/**
+ * `lotics app create <name> [path]`
+ *
+ * Creates the app server-side, scaffolds a Vite+React+TS project locally
+ * from the embedded starter template, runs `npm install` + `npm run build`,
+ * then deploys the result as v1. After this returns, `lotics app deploy`
+ * works end-to-end on the same directory.
+ *
+ * Why scaffold + deploy rather than pull-from-server-starter: the deploy
+ * pipeline requires a built dist tree, and v1 doesn't run builds server-side.
+ * Doing the build locally on first create keeps the platform infrastructure
+ * minimal — the starter template is embedded in the CLI binary and bumps
+ * with CLI releases. (Server-side build is the v2 path.)
+ */
+export async function appCreate(client, args) {
+    const targetPath = path.resolve(args.targetPath ?? args.name);
+    if (fs.existsSync(targetPath)) {
+        const entries = fs.readdirSync(targetPath);
+        if (entries.length > 0) {
+            throw new Error(`Target directory ${targetPath} is not empty.`);
+        }
+    }
+    fs.mkdirSync(targetPath, { recursive: true });
+    // Server-side row first — if this fails, no local files have been touched.
+    const app = await client.createApp({ name: args.name });
+    console.error(`Created app: ${app.name} (${app.id})`);
+    // Scaffold the starter into the target directory.
+    const files = buildStarterTemplate({
+        app_name: args.name,
+        app_id: app.id,
+        workspace_id: app.workspace_id,
+    });
+    for (const file of files) {
+        const fullPath = path.join(targetPath, file.path);
+        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+        fs.writeFileSync(fullPath, file.content);
+    }
+    console.error(`Scaffolded ${files.length} files into ${targetPath}`);
+    console.error("Installing npm dependencies...");
+    await runNpm(["install"], targetPath);
+    console.error("Building initial version...");
+    await appDeploy(client, {
+        projectDir: targetPath,
+        message: "Initial version",
+    });
+    console.error(`\nReady. Next steps:`);
+    console.error(`  cd ${path.relative(process.cwd(), targetPath) || "."}`);
+    console.error(`  # edit src/App.tsx, then:`);
+    console.error(`  lotics app deploy`);
+}
+/**
+ * `lotics app pull <app_id> [path]`
+ *
+ * Bootstraps a full local dev environment for an existing app:
+ *   1. Fetch the current version's source archive from R2 (presigned URL).
+ *   2. Extract into the target directory.
+ *   3. Write package.json's `lotics` field with app_id + version metadata.
+ *   4. Run `npm install`.
+ *   5. (TODO) Generate `.lotics/types.ts` with workspace-typed augmentations.
+ */
+export async function appPull(client, args) {
+    const app = await client.getApp(args.app_id);
+    if (!app.current_version_id) {
+        throw new Error(`App ${app.id} has no published version yet. Deploy from another machine first, or use 'lotics app create' to scaffold a new app.`);
+    }
+    const version = await client.getAppVersion(app.id, app.current_version_id);
+    const sourceUrl = await client.getAppVersionSourceUrl(app.id, version.id);
+    const targetPath = path.resolve(args.targetPath ?? app.name);
+    fs.mkdirSync(targetPath, { recursive: true });
+    // Download to a temp file because `tar -xz` reads from a real path.
+    const tmpFile = path.join(tmpdir(), `lotics-app-${app.id}-${Date.now()}.tar.gz`);
+    console.error(`Downloading source archive...`);
+    await downloadToFile(sourceUrl, tmpFile);
+    try {
+        console.error(`Extracting to ${targetPath}...`);
+        await runTar(["-xzf", tmpFile, "-C", targetPath], targetPath);
+    }
+    finally {
+        if (fs.existsSync(tmpFile))
+            fs.unlinkSync(tmpFile);
+    }
+    writeAppMeta(targetPath, {
+        app_id: app.id,
+        workspace_id: app.workspace_id,
+        current_version_id: app.current_version_id,
+        version_number: version.version,
+    });
+    console.error(`Installing npm dependencies...`);
+    await runNpm(["install"], targetPath);
+    console.error(`\nReady. Next steps:`);
+    console.error(`  cd ${path.relative(process.cwd(), targetPath) || "."}`);
+    console.error(`  # edit src/App.tsx`);
+    console.error(`  lotics app deploy`);
+}
+/**
+ * `lotics app deploy [-m <message>]`
+ *
+ * Builds the project locally with `npm run build`, tars source + dist, and
+ * uploads to the deploy endpoint. The endpoint validates structure, stores
+ * both archives in R2, creates an app_versions row, and atomically advances
+ * the app's current_version pointer.
+ */
+export async function appDeploy(client, args) {
+    const projectDir = path.resolve(args.projectDir ?? process.cwd());
+    const meta = readAppMeta(projectDir);
+    // Build locally so the server doesn't need a build sandbox in v1.
+    console.error("Building...");
+    await runNpm(["run", "build"], projectDir);
+    const distDir = path.join(projectDir, "dist");
+    if (!fs.existsSync(distDir)) {
+        throw new Error(`Build did not produce a dist/ directory in ${projectDir}. ` +
+            `Check that 'npm run build' is configured correctly (Vite/etc. defaults to dist/).`);
+    }
+    const tmpSource = path.join(tmpdir(), `lotics-source-${Date.now()}.tar.gz`);
+    const tmpDist = path.join(tmpdir(), `lotics-dist-${Date.now()}.tar.gz`);
+    try {
+        console.error("Packaging source...");
+        await runTar([
+            "-czf",
+            tmpSource,
+            "--exclude=node_modules",
+            "--exclude=dist",
+            "--exclude=.lotics",
+            "--exclude=*.tsbuildinfo",
+            "--exclude=.git",
+            ".",
+        ], projectDir);
+        console.error("Packaging dist...");
+        await runTar(["-czf", tmpDist, "-C", distDir, "."], projectDir);
+        console.error("Uploading...");
+        try {
+            const result = await client.deployAppVersion({
+                app_id: meta.app_id,
+                source_archive: fs.readFileSync(tmpSource),
+                dist_archive: fs.readFileSync(tmpDist),
+                prev_version_id: meta.current_version_id,
+                message: args.message,
+                // Sync apps.workflows from the manifest. Server validates each
+                // workflow_id exists in the workspace before committing.
+                workflows: meta.workflows ?? {},
+            });
+            writeAppMeta(projectDir, {
+                ...meta,
+                current_version_id: result.version_id,
+                version_number: result.version_number,
+            });
+            console.error(`Deployed v${result.version_number} (${result.version_id})`);
+            console.error(`Bundle size: ${(result.bundle_size_bytes / 1024).toFixed(1)} KB`);
+        }
+        catch (err) {
+            const e = err;
+            if (e.code === "VERSION_CONFLICT") {
+                throw new Error(`Deploy conflict: server is at version ${e.current_version_id ?? "unknown"} ` +
+                    `but local copy is based on ${meta.current_version_id ?? "no version"}. ` +
+                    `Pull the latest before redeploying:\n  lotics app pull ${meta.app_id}`);
+            }
+            throw err;
+        }
+    }
+    finally {
+        if (fs.existsSync(tmpSource))
+            fs.unlinkSync(tmpSource);
+        if (fs.existsSync(tmpDist))
+            fs.unlinkSync(tmpDist);
+    }
+}

package/dist/src/cli.js

@@ -5,6 +5,7 @@ import readline from "node:readline";
 import { LoticsClient, API_BASE_URL } from "./client.js";
 import { resolveAuth, loadConfig, saveConfig, deleteConfig, checkForUpdate } from "./config.js";
 import { VERSION } from "./version.js";
+import { appCreate, appPull, appDeploy } from "./app_commands.js";
 function printHelp() {
     console.log(`Lotics CLI v${VERSION} — AI agent interface for Lotics
 
@@ -43,6 +44,9 @@ COMMANDS
   lotics download <file_id>            Download a file by ID
   lotics download record <record_id> <field_key>
                                        Download all files on a record file field
+  lotics app create <name> [path]      Create a new custom-code app + scaffold locally
+  lotics app pull <app_id> [path]      Bootstrap full local env (source + npm install + types)
+  lotics app deploy [-m <message>]     Build + upload current dir as a new version
 
 FLAGS
   --json             Full JSON output (default is human-readable text)
@@ -389,11 +393,18 @@ async function main() {
         return;
     }
     // --- Validate command before auth ---
-    if (command !== "tools" && command !== "upload" && command !== "run" && command !== "download" && command !== "workspace") {
+    if (command !== "tools" && command !== "upload" && command !== "run" && command !== "download" && command !== "workspace" && command !== "app") {
         console.error(`Unknown command: ${command}`);
         console.error('Run "lotics --help" for usage.');
         process.exit(1);
     }
+    if (command === "app" && !subcommand) {
+        console.error("Usage:");
+        console.error("  lotics app create <name> [path]      Scaffold a new app locally");
+        console.error("  lotics app pull <app_id> [path]      Pull an existing app for local editing");
+        console.error("  lotics app deploy [-m <message>]     Build + upload the current directory");
+        process.exit(1);
+    }
     if (command === "run" && !subcommand) {
         console.error('Usage: lotics run <tool> \'<json_args>\'');
         console.error('Run "lotics tools" to see available tools.');
@@ -482,6 +493,39 @@ async function main() {
     }
     // Ensure workspace is resolved for all remaining commands
     await resolveWorkspace(client);
+    // lotics app create / pull / deploy
+    if (command === "app") {
+        if (subcommand === "create") {
+            const name = toolArgs;
+            if (!name) {
+                console.error("Usage: lotics app create <name> [path]");
+                process.exit(1);
+            }
+            const targetPath = restArgs[0];
+            await appCreate(client, { name, targetPath });
+            return;
+        }
+        if (subcommand === "pull") {
+            const appId = toolArgs;
+            if (!appId) {
+                console.error("Usage: lotics app pull <app_id> [path]");
+                process.exit(1);
+            }
+            const targetPath = restArgs[0];
+            await appPull(client, { app_id: appId, targetPath });
+            return;
+        }
+        if (subcommand === "deploy") {
+            // -m / --message can be passed via toolArgs or after a flag-like delimiter.
+            // Keep it simple: any positional arg after `deploy` is treated as the message.
+            const message = toolArgs;
+            await appDeploy(client, { message });
+            return;
+        }
+        console.error(`Unknown app subcommand: ${subcommand}`);
+        console.error("Run 'lotics app' for usage.");
+        process.exit(1);
+    }
     // lotics tools / lotics tools <name>
     if (command === "tools") {
         if (subcommand) {

package/dist/src/client.d.ts

@@ -67,6 +67,49 @@ export declare class LoticsClient {
         format?: "json" | "text";
         timeoutMs?: number;
     }): Promise<ToolExecuteResult>;
+    getApp(app_id: string): Promise<{
+        id: string;
+        name: string;
+        workspace_id: string;
+        current_version_id: string | null;
+    }>;
+    createApp(body: {
+        name: string;
+        description?: string;
+        icon?: string;
+    }): Promise<{
+        id: string;
+        name: string;
+        workspace_id: string;
+        current_version_id: string | null;
+    }>;
+    getAppVersion(app_id: string, version_id: string): Promise<{
+        id: string;
+        app_id: string;
+        version: number;
+        r2_prefix: string;
+        entry_html_path: string;
+        build_status: string;
+    }>;
+    getAppVersionSourceUrl(app_id: string, version_id: string): Promise<string>;
+    deployAppVersion(args: {
+        app_id: string;
+        source_archive: Buffer;
+        dist_archive: Buffer;
+        prev_version_id?: string | null;
+        message?: string | null;
+        /**
+         * Alias → workflow_id map from the app's package.json `lotics.workflows`.
+         * Always sent (empty object when none declared) so the server can
+         * overwrite apps.workflows authoritatively. Deleting an alias from the
+         * manifest removes it from the DB on next deploy.
+         */
+        workflows?: Record<string, string>;
+    }): Promise<{
+        version_id: string;
+        version_number: number;
+        bundle_size_bytes: number;
+    }>;
     downloadFile(url: string, outputPath: string): Promise<string>;
     downloadFileById(fileId: string, outputDir?: string, options?: {
         reserved?: Set<string>;

package/dist/src/client.js

@@ -139,6 +139,55 @@ export class LoticsClient {
         }
         return this.request("POST", "/v1/tools/execute", body);
     }
+    // --- Apps ---
+    async getApp(app_id) {
+        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}`);
+    }
+    async createApp(body) {
+        return this.request("POST", "/v1/apps", { ...body, ui: { type: "custom_code" } });
+    }
+    async getAppVersion(app_id, version_id) {
+        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/versions/${encodeURIComponent(version_id)}`);
+    }
+    async getAppVersionSourceUrl(app_id, version_id) {
+        const result = await this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/versions/${encodeURIComponent(version_id)}/source`);
+        return result.url;
+    }
+    async deployAppVersion(args) {
+        const formData = new FormData();
+        // Wrap Buffers as Uint8Array views so the Blob constructor accepts them
+        // (Node Buffer's `ArrayBufferLike` underlying buffer doesn't match the
+        // BlobPart contract directly under strict TS).
+        formData.append("source", new Blob([new Uint8Array(args.source_archive)], { type: "application/gzip" }), "source.tar.gz");
+        formData.append("dist", new Blob([new Uint8Array(args.dist_archive)], { type: "application/gzip" }), "dist.tar.gz");
+        if (args.prev_version_id) {
+            formData.append("prev_version_id", args.prev_version_id);
+        }
+        if (args.message) {
+            formData.append("message", args.message);
+        }
+        // Always send workflows — empty object is meaningful (clears any
+        // previously-declared aliases). Server validates each entry.
+        formData.append("workflows", JSON.stringify(args.workflows ?? {}));
+        const url = `${this.baseUrl}/v1/apps/${encodeURIComponent(args.app_id)}/versions`;
+        const response = await fetch(url, {
+            method: "POST",
+            headers: this.buildHeaders(), // no Content-Type — fetch sets multipart boundary
+            body: formData,
+        });
+        if (response.status === 409) {
+            const conflict = (await response.json());
+            const err = new Error(conflict.message ?? "Deploy conflict — pull required");
+            err.code = "VERSION_CONFLICT";
+            err.current_version_id =
+                conflict.current_version_id ?? null;
+            throw err;
+        }
+        if (!response.ok) {
+            await this.throwResponseError(response);
+        }
+        return response.json();
+    }
     async downloadFile(url, outputPath) {
         const response = await fetch(url);
         if (!response.ok) {

package/dist/src/starter_template.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Starter template for `lotics app create`.
+ *
+ * The CLI scaffolds these files into the user's target directory, then runs
+ * `npm install` + `npm run build` + `lotics app deploy` to populate v1.
+ *
+ * Embedded as string literals here (rather than packaged as files alongside
+ * the CLI) so the CLI binary is self-contained and the starter survives
+ * `npm publish` cleanly. Updates to the starter ship in CLI releases.
+ *
+ * Conventions (locked decisions):
+ *   - Vite + React + TypeScript (strict mode).
+ *   - Entry: src/App.tsx with `export default`. main.tsx wires `mount(<App/>)`
+ *     and imports @lotics/ui/index.css for the base style reset.
+ *   - Vite default `base: "/"` so emitted asset URLs are absolute; the render
+ *     endpoint rewrites root-relative paths to `/v1/apps/{id}/asset/...`.
+ *     Don't switch to `base: "./"` without updating `rewriteAssetPaths`.
+ *   - react-native aliased to react-native-web so @lotics/ui's RN primitives
+ *     render in a pure-web environment. `.web.tsx` is prioritized in the
+ *     resolve.extensions list.
+ *   - @lotics/app-sdk + @lotics/ui peer-supplied; user installs both via npm.
+ *   - oxlint + vitest + tsc out of the box, plus a GitHub Actions CI
+ *     workflow that runs all three on every PR.
+ */
+export interface StarterFile {
+    path: string;
+    content: string;
+}
+export declare function buildStarterTemplate(args: {
+    app_name: string;
+    app_id: string;
+    workspace_id: string;
+}): StarterFile[];

package/dist/src/starter_template.js

@@ -0,0 +1,297 @@
+/**
+ * Starter template for `lotics app create`.
+ *
+ * The CLI scaffolds these files into the user's target directory, then runs
+ * `npm install` + `npm run build` + `lotics app deploy` to populate v1.
+ *
+ * Embedded as string literals here (rather than packaged as files alongside
+ * the CLI) so the CLI binary is self-contained and the starter survives
+ * `npm publish` cleanly. Updates to the starter ship in CLI releases.
+ *
+ * Conventions (locked decisions):
+ *   - Vite + React + TypeScript (strict mode).
+ *   - Entry: src/App.tsx with `export default`. main.tsx wires `mount(<App/>)`
+ *     and imports @lotics/ui/index.css for the base style reset.
+ *   - Vite default `base: "/"` so emitted asset URLs are absolute; the render
+ *     endpoint rewrites root-relative paths to `/v1/apps/{id}/asset/...`.
+ *     Don't switch to `base: "./"` without updating `rewriteAssetPaths`.
+ *   - react-native aliased to react-native-web so @lotics/ui's RN primitives
+ *     render in a pure-web environment. `.web.tsx` is prioritized in the
+ *     resolve.extensions list.
+ *   - @lotics/app-sdk + @lotics/ui peer-supplied; user installs both via npm.
+ *   - oxlint + vitest + tsc out of the box, plus a GitHub Actions CI
+ *     workflow that runs all three on every PR.
+ */
+export function buildStarterTemplate(args) {
+    const sanitizedPkgName = args.app_name
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 64) || "lotics-app";
+    return [
+        {
+            path: "package.json",
+            content: JSON.stringify({
+                name: sanitizedPkgName,
+                version: "0.0.1",
+                private: true,
+                type: "module",
+                scripts: {
+                    dev: "vite",
+                    build: "vite build",
+                    preview: "vite preview",
+                    typecheck: "tsc --noEmit",
+                    // Scope to src/ — oxlint's default scan walks node_modules too.
+                    lint: "oxlint src",
+                    test: "vitest run",
+                },
+                dependencies: {
+                    "@lotics/app-sdk": "^0.2.0",
+                    "@lotics/ui": "^0.2.0",
+                    "@react-native-picker/picker": "^2.7.0",
+                    "expo-image": "~3.0.9",
+                    "lucide-react": "^0.562.0",
+                    "lucide-react-native": "^0.562.0",
+                    react: "^19.0.0",
+                    "react-dom": "^19.0.0",
+                    "react-native": "0.81.0",
+                    "react-native-svg": "^15.0.0",
+                    "react-native-web": "^0.21.0",
+                },
+                devDependencies: {
+                    "@testing-library/react": "^16.1.0",
+                    "@types/react": "^19.0.0",
+                    "@types/react-dom": "^19.0.0",
+                    "@vitejs/plugin-react": "^4.3.0",
+                    jsdom: "^25.0.0",
+                    oxlint: "^0.13.0",
+                    typescript: "^5.6.0",
+                    vite: "^5.4.0",
+                    vitest: "^2.1.0",
+                },
+                lotics: {
+                    app_id: args.app_id,
+                    workspace_id: args.workspace_id,
+                    current_version_id: null,
+                    version_number: null,
+                },
+            }, null, 2) + "\n",
+        },
+        {
+            path: "tsconfig.json",
+            content: JSON.stringify({
+                compilerOptions: {
+                    target: "ES2022",
+                    useDefineForClassFields: true,
+                    lib: ["ES2022", "DOM", "DOM.Iterable"],
+                    module: "ESNext",
+                    skipLibCheck: true,
+                    moduleResolution: "Bundler",
+                    allowImportingTsExtensions: true,
+                    resolveJsonModule: true,
+                    isolatedModules: true,
+                    noEmit: true,
+                    jsx: "react-jsx",
+                    strict: true,
+                    noUnusedLocals: true,
+                    noUnusedParameters: true,
+                    noFallthroughCasesInSwitch: true,
+                },
+                include: ["src", ".lotics"],
+            }, null, 2) + "\n",
+        },
+        {
+            path: "vite.config.ts",
+            content: `/// <reference types="vitest" />
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+// Vite default base (/) emits absolute asset URLs in index.html. Lotics's
+// render endpoint rewrites those to /v1/apps/{id}/asset/... so the bundle
+// loads via the platform's asset proxy. Don't change \`base\` unless you
+// also adjust the rewrite logic in backend/api/apps.ts:rewriteAssetPaths.
+//
+// react-native → react-native-web alias lets @lotics/ui's RN primitives
+// (View, Text, Pressable, StyleSheet, etc.) render in a pure-web environment.
+// .web.tsx is prioritized in resolve.extensions so per-target variants
+// (avatar.web.tsx, wave_avatar.web.tsx) win over the native .tsx file.
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      "react-native": "react-native-web",
+    },
+    extensions: [".web.tsx", ".web.ts", ".tsx", ".ts", ".jsx", ".js"],
+  },
+  build: {
+    outDir: "dist",
+    sourcemap: true,
+  },
+  test: {
+    environment: "jsdom",
+  },
+});
+`,
+        },
+        {
+            path: "index.html",
+            content: `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${escapeHtml(args.app_name)}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+`,
+        },
+        {
+            path: "src/main.tsx",
+            content: `import "@lotics/ui/index.css";
+import { mount } from "@lotics/app-sdk";
+import App from "./App";
+
+mount(<App />);
+`,
+        },
+        {
+            path: "src/App.tsx",
+            // Static welcome screen using @lotics/ui primitives — no useTable call
+            // so the freshly-deployed v1 renders cleanly without needing a real
+            // table id. The user's first edit is to replace this with their app.
+            content: `import { View } from "react-native";
+import { Stack } from "@lotics/ui/stack";
+import { Card } from "@lotics/ui/card";
+import { Text } from "@lotics/ui/text";
+import { Button } from "@lotics/ui/button";
+
+export default function App() {
+  return (
+    <View style={{ padding: 24, maxWidth: 640, marginHorizontal: "auto" }}>
+      <Stack gap={16}>
+        <Text size="xl" weight="semibold">${escapeHtml(args.app_name)}</Text>
+        <Card>
+          <Stack gap={8} style={{ padding: 16 }}>
+            <Text>This is your new Lotics app.</Text>
+            <Text color="muted">
+              Edit <Text weight="medium">src/App.tsx</Text> and run{" "}
+              <Text weight="medium">lotics app deploy</Text> to publish.
+            </Text>
+          </Stack>
+        </Card>
+        <Text color="muted" size="sm">
+          Hooks from @lotics/app-sdk: useTable, useMutate, useAction, useQuery, useWorkflow.
+        </Text>
+        <Button title="Get started" onPress={() => {}} color="primary" />
+      </Stack>
+    </View>
+  );
+}
+`,
+        },
+        {
+            path: "src/App.test.tsx",
+            content: `import { describe, test, expect } from "vitest";
+import { render } from "@testing-library/react";
+import App from "./App";
+
+describe("App", () => {
+  test("renders without crashing", () => {
+    const { container } = render(<App />);
+    expect(container).not.toBeNull();
+  });
+});
+`,
+        },
+        {
+            path: ".github/workflows/ci.yml",
+            content: `name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run lint
+      - run: npm test
+      - run: npm run build
+`,
+        },
+        {
+            path: ".gitignore",
+            content: `node_modules
+dist
+*.tsbuildinfo
+.DS_Store
+.lotics
+coverage
+`,
+        },
+        {
+            path: "README.md",
+            content: `# ${args.app_name}
+
+A Lotics custom-code app. Authored locally, deployed via CLI.
+
+## Develop
+
+\`\`\`bash
+npm install            # already done by 'lotics app create'
+npm run dev            # local Vite dev server (UI only — real data needs deploy)
+\`\`\`
+
+## Quality
+
+\`\`\`bash
+npm run typecheck      # tsc --noEmit
+npm run lint           # oxlint
+npm test               # vitest run
+\`\`\`
+
+CI runs all three on every PR via \`.github/workflows/ci.yml\`.
+
+## Deploy
+
+\`\`\`bash
+lotics app deploy              # build + upload as a new version
+lotics app deploy -m "what"    # with a commit-message-style note
+\`\`\`
+
+## SDK + UI components
+
+\`\`\`tsx
+import { mount, useTable, useMutate, useAction, useQuery, useWorkflow } from "@lotics/app-sdk";
+import { Stack } from "@lotics/ui/stack";
+import { Card } from "@lotics/ui/card";
+import { Button } from "@lotics/ui/button";
+import { Text } from "@lotics/ui/text";
+// ... and Grid, Dialog, DatePicker, FormPicker, BarChart, LineChart, PieChart, Metric, ProgressBar, etc.
+\`\`\`
+
+@lotics/ui ships React Native primitives that render via react-native-web
+in this Vite app (the alias is preconfigured in \`vite.config.ts\`). See
+the full export list at https://www.npmjs.com/package/@lotics/ui.
+
+See https://lotics.ai/docs/app-sdk for the SDK reference.
+`,
+        },
+    ];
+}
+function escapeHtml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {