@idapt/cli 1.9.0 → 1.11.0

package/dist/bin.js

@@ -1,15 +1,687 @@
 #!/usr/bin/env node
-import { createFetchTransport, execute, autoMode, commandsForResource, findCommand, renderHelp, listResources, renderInstructions, quoteToken } from './chunk-TYSHO65D.js';
-import { readFileSync, mkdirSync, writeFileSync, chmodSync, rmSync } from 'fs';
+import { createFetchTransport, execute, autoMode, commandsForResource, findCommand, renderHelp, listResources, renderInstructions, quoteToken, commandCatalog, executeCommand } from './chunk-3CWHRMLZ.js';
+import { readFileSync, mkdirSync, writeFileSync, chmodSync, rmSync, readdirSync, existsSync } from 'fs';
+import { dirname, resolve, join, relative, sep } from 'path';
 import { spawn } from 'child_process';
-import { dirname, join } from 'path';
 import { homedir } from 'os';
 import { createServer } from 'http';
 import { randomBytes, createHash } from 'crypto';
 
 // src/version.ts
-var VERSION = "1.9.0";
+var VERSION = "1.11.0";
 var USER_AGENT = `idapt-cli/${VERSION}`;
+var MAX_BUNDLE_FILES = 500;
+var MAX_BUNDLE_FILE_BYTES = 25 * 1024 * 1024;
+var MAX_BUNDLE_TOTAL_BYTES = 100 * 1024 * 1024;
+function parseDeployArgs(args) {
+  let dir;
+  let app;
+  let workspace;
+  let name;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--app") app = args[++i];
+    else if (a.startsWith("--app=")) app = a.slice("--app=".length);
+    else if (a === "--workspace" || a === "--workspace-id")
+      workspace = args[++i];
+    else if (a.startsWith("--workspace="))
+      workspace = a.slice("--workspace=".length);
+    else if (a.startsWith("--workspace-id="))
+      workspace = a.slice("--workspace-id=".length);
+    else if (a === "--name") name = args[++i];
+    else if (a.startsWith("--name=")) name = a.slice("--name=".length);
+    else if (!a.startsWith("-") && dir === void 0) dir = a;
+  }
+  return { dir: dir ?? "", app, workspace, name };
+}
+function buildDeployPayload(files) {
+  if (files.length === 0) {
+    return { ok: false, error: "no files found to deploy" };
+  }
+  if (files.length > MAX_BUNDLE_FILES) {
+    return {
+      ok: false,
+      error: `too many files: ${files.length} (max ${MAX_BUNDLE_FILES})`
+    };
+  }
+  const out = [];
+  let totalBytes = 0;
+  for (const f of files) {
+    const size = f.bytes.byteLength;
+    if (size > MAX_BUNDLE_FILE_BYTES) {
+      return {
+        ok: false,
+        error: `file too large: ${f.path} (${size} bytes, max ${MAX_BUNDLE_FILE_BYTES})`
+      };
+    }
+    totalBytes += size;
+    if (totalBytes > MAX_BUNDLE_TOTAL_BYTES) {
+      return {
+        ok: false,
+        error: `bundle too large: exceeds ${MAX_BUNDLE_TOTAL_BYTES} bytes total`
+      };
+    }
+    out.push({
+      path: f.path,
+      content_b64: Buffer.from(f.bytes).toString("base64")
+    });
+  }
+  return { ok: true, files: out };
+}
+function rowId(data) {
+  if (typeof data !== "object" || data === null) return void 0;
+  const r = data;
+  const id = r.id ?? r.resource_id ?? r.resourceId;
+  return typeof id === "string" ? id : void 0;
+}
+function rowUrl(data) {
+  if (typeof data !== "object" || data === null) return void 0;
+  const r = data;
+  const url = r.url ?? r.origin;
+  return typeof url === "string" ? url : void 0;
+}
+async function resolveExistingApp(exec, app, workspace) {
+  const got = await exec("browser-app get", { app });
+  if (got.ok) {
+    const id = rowId(got.data);
+    if (id) return { appId: id, url: rowUrl(got.data) };
+  }
+  const listed = await exec(
+    "browser-app list",
+    workspace ? { workspace_id: workspace } : {}
+  );
+  if (listed.ok && Array.isArray(listed.data)) {
+    const match = listed.data.find((row) => {
+      const r = row;
+      return r?.name === app || rowId(r) === app;
+    });
+    const id = match ? rowId(match) : void 0;
+    if (id) return { appId: id, url: rowUrl(match) };
+  }
+  return null;
+}
+async function deployBundle(opts, files, exec) {
+  const built = buildDeployPayload(files);
+  if (!built.ok) return { ok: false, error: built.error };
+  let appId;
+  let url;
+  let created = false;
+  if (opts.app) {
+    const existing = await resolveExistingApp(exec, opts.app, opts.workspace);
+    if (existing) {
+      appId = existing.appId;
+      url = existing.url;
+    }
+  }
+  if (!appId) {
+    const createArgs = {
+      name: opts.name ?? opts.app ?? defaultAppName(opts.dir)
+    };
+    if (opts.workspace) createArgs.workspace_id = opts.workspace;
+    const createdRes = await exec("browser-app create", createArgs);
+    if (!createdRes.ok) {
+      return {
+        ok: false,
+        error: createdRes.error ?? "failed to create app"
+      };
+    }
+    appId = rowId(createdRes.data);
+    url = rowUrl(createdRes.data) ?? url;
+    created = true;
+    if (!appId) {
+      return { ok: false, error: "create succeeded but returned no app id" };
+    }
+  }
+  const deployed = await exec("browser-app deploy", {
+    app: appId,
+    files: built.files
+  });
+  if (!deployed.ok) {
+    return {
+      ok: false,
+      appId,
+      url,
+      created,
+      error: deployed.error ?? "deploy failed"
+    };
+  }
+  const data = deployed.data;
+  const written = typeof data?.written === "number" ? data.written : built.files.length;
+  const deploymentId = typeof data?.id === "string" ? data.id : void 0;
+  return { ok: true, appId, deploymentId, url, created, written };
+}
+function defaultAppName(dir) {
+  const norm = resolve(dir).split(sep).filter(Boolean);
+  const base = norm.at(-1);
+  if ((base === "dist" || base === "build") && norm.length >= 2) {
+    return norm.at(-2) ?? "My App";
+  }
+  return base ?? "My App";
+}
+function collectDir(dir) {
+  const root = resolve(dir);
+  const out = [];
+  const walk = (abs) => {
+    for (const entry of readdirSync(abs, { withFileTypes: true })) {
+      const child = join(abs, entry.name);
+      if (entry.isDirectory()) {
+        walk(child);
+      } else if (entry.isFile()) {
+        const rel = relative(root, child).split(sep).join("/");
+        out.push({ path: rel, bytes: readFileSync(child) });
+      }
+    }
+  };
+  walk(root);
+  return out;
+}
+async function runAppDeploy(ctx, args, exec, io = { collect: collectDir }) {
+  const opts = parseDeployArgs(args);
+  if (!opts.dir) {
+    ctx.out(
+      "idapt app deploy: missing <dir> \u2014 pass the built bundle, e.g. `idapt app deploy ./dist`."
+    );
+    return 1;
+  }
+  let files;
+  try {
+    files = io.collect(opts.dir);
+  } catch (err) {
+    ctx.out(
+      `idapt app deploy: cannot read "${opts.dir}": ${err.message}`
+    );
+    return 1;
+  }
+  const result = await deployBundle(opts, files, exec);
+  if (!result.ok) {
+    ctx.out(`idapt app deploy: ${result.error}`);
+    return 1;
+  }
+  ctx.print(
+    [
+      `Deployed ${result.written} file${result.written === 1 ? "" : "s"} to ${result.appId}${result.created ? " (new app)" : ""} \u2014 now live${result.deploymentId ? ` (deployment ${result.deploymentId})` : ""}.`,
+      result.url ? `Open: ${result.url}` : ""
+    ].filter(Boolean).join("\n")
+  );
+  return 0;
+}
+
+// ../../shared/browser-app-sdk-version.ts
+var BROWSER_APP_SDK_DEP_RANGE = "^0.1.0";
+
+// src/app/templates.ts
+function normalize(opts) {
+  return {
+    name: (opts.name || "My App").trim() || "My App",
+    icon: (opts.icon || "\u{1F4E6}").trim() || "\u{1F4E6}",
+    description: opts.description?.trim() || void 0
+  };
+}
+function idaptManifest(n) {
+  const manifest = {
+    entrypoint: "dist/index.html",
+    name: n.name,
+    icon: n.icon,
+    version: "0.1.0",
+    permissions: []
+  };
+  if (n.description) manifest.description = n.description;
+  return manifest;
+}
+var VITEST_CONFIG = `import { defineConfig } from "vitest/config";
+
+// Unit tests run in Node \u2014 the mock Idapt SDK needs no DOM. Add
+// \`environment: "jsdom"\` + @testing-library if you render components in tests.
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.ts", "src/**/*.test.tsx"],
+  },
+});
+`;
+var EXAMPLE_UNIT_TEST = `/**
+ * Example unit test \u2014 runs WITHOUT a live Idapt origin via the mock harness.
+ *
+ * \`createMockIdapt()\` returns a fake Idapt client whose \`data\` is an in-memory
+ * KV and whose \`app\` reads from a fixture map, so app logic built on
+ * \`client.data\` / \`client.app\` is unit-testable offline (the real \`connect()\`
+ * throws when run off an Idapt app subdomain).
+ */
+import { createMockIdapt } from "@idapt/browser-app-sdk/testing";
+import { describe, expect, it } from "vitest";
+
+describe("idapt mock harness", () => {
+  it("round-trips per-user state through the in-memory data KV", async () => {
+    const idapt = createMockIdapt();
+    await idapt.data.setJSON("prefs.json", { theme: "dark" });
+    expect(await idapt.data.getJSON("prefs.json")).toEqual({ theme: "dark" });
+    expect(await idapt.data.get("missing.json")).toBeNull();
+  });
+
+  it("reads the app's own bundle from the fixture map", async () => {
+    const idapt = createMockIdapt({
+      files: { "idapt.json": JSON.stringify({ name: "Demo" }) },
+    });
+    const names = (await idapt.app.list()).map((f) => f.name);
+    expect(names).toContain("idapt.json");
+  });
+});
+`;
+var PLAYWRIGHT_CONFIG = `import { defineConfig } from "@playwright/test";
+
+// Point PREVIEW_URL at a deployment's preview (or a local \`vite preview\`) and run
+// \`npm run test:e2e\`. The specs assert against the accessibility tree, so they
+// read the app exactly as assistive tech and \`browser-app snapshot\` do.
+export default defineConfig({
+  testDir: "./e2e",
+  use: { baseURL: process.env.PREVIEW_URL ?? "http://localhost:4173" },
+});
+`;
+var E2E_SPEC = `import { expect, test } from "@playwright/test";
+
+// Accessibility-first assertions: querying by ROLE (not a brittle CSS selector)
+// is robust AND proves the app exposes a semantic tree \u2014 the same tree the agent
+// sees via \`browser-app snapshot\`.
+test("renders an accessible top-level heading", async ({ page }) => {
+  await page.goto("/");
+  await expect(page.getByRole("heading", { level: 1 })).toBeVisible();
+});
+`;
+var IDAPT_CI_YML = `version: 1
+jobs:
+  test:
+    executor: cloud
+    steps:
+      - npm install
+      - npm test
+  build:
+    executor: cloud
+    needs: [test]
+    steps:
+      - npm install
+      - npm run build
+    output:
+      paths:
+        - dist/**
+deploy:
+  target: browser-app
+  app: __APP_NAME__
+  artifacts: build
+`;
+var ESLINT_A11Y_CONFIG = `import jsxA11y from "eslint-plugin-jsx-a11y";
+
+// Accessibility-first: the SAME semantic tree powers assistive tech, the e2e
+// specs, and the agent's \`browser-app snapshot\`. jsx-a11y flags missing labels,
+// alt text, and invalid roles so inaccessible markup fails lint, not review.
+export default [
+  {
+    files: ["src/**/*.{ts,tsx}"],
+    plugins: { "jsx-a11y": jsxA11y },
+    rules: jsxA11y.flatConfigs.recommended.rules,
+  },
+];
+`;
+var REACT_INDEX_HTML = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>__APP_NAME__</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <!-- npm-only: the app bundles @idapt/browser-app-sdk itself (a dependency).
+         The SDK auto-connects via the app-key cookie; no script tag needed. -->
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+`;
+var REACT_PKG = "react";
+var REACT_DOM_CLIENT_PKG = "react-dom/client";
+var REACT_MAIN_TSX = `import { StrictMode } from "${REACT_PKG}";
+import { createRoot } from "${REACT_DOM_CLIENT_PKG}";
+import { App } from "./App";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
+`;
+var REACT_APP_TSX = `import { connect } from "@idapt/browser-app-sdk";
+import { useEffect, useState } from "${REACT_PKG}";
+
+export function App() {
+  const [status, setStatus] = useState("Connecting\u2026");
+
+  useEffect(() => {
+    // On an idapt app subdomain the app-key cookie auto-connects \u2014 no args.
+    connect()
+      .then(() => setStatus("Connected."))
+      .catch(() => setStatus("Could not connect to idapt."));
+  }, []);
+
+  return (
+    <main style={{ maxWidth: "36rem", margin: "0 auto", padding: "2rem 1.25rem" }}>
+      <h1>__APP_NAME__</h1>
+      <p>{status}</p>
+    </main>
+  );
+}
+`;
+var REACT_VITE_CONFIG = `import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+// Build to dist/ (the served bundle). Relative base so assets resolve on the
+// app subdomain regardless of mount path.
+export default defineConfig({
+  base: "./",
+  plugins: [react()],
+  build: { outDir: "dist" },
+});
+`;
+var REACT_TSCONFIG = `{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}
+`;
+function getReactScaffold(opts) {
+  const n = normalize(opts);
+  const pkg = {
+    name: "idapt-react-app",
+    private: true,
+    version: "0.1.0",
+    type: "module",
+    scripts: {
+      build: "vite build",
+      dev: "vite",
+      test: "vitest run",
+      "test:e2e": "playwright test",
+      lint: "eslint ."
+    },
+    dependencies: {
+      "@idapt/browser-app-sdk": BROWSER_APP_SDK_DEP_RANGE,
+      react: "^18.3.1",
+      "react-dom": "^18.3.1"
+    },
+    devDependencies: {
+      "@playwright/test": "^1.48.0",
+      "@vitejs/plugin-react": "^4.3.1",
+      eslint: "^9.13.0",
+      "eslint-plugin-jsx-a11y": "^6.10.0",
+      typescript: "^5.5.4",
+      vite: "^5.4.0",
+      vitest: "^2.1.0"
+    },
+    idapt: idaptManifest(n)
+  };
+  return [
+    { path: "package.json", content: `${JSON.stringify(pkg, null, 2)}
+` },
+    {
+      path: "index.html",
+      content: REACT_INDEX_HTML.replaceAll("__APP_NAME__", n.name)
+    },
+    { path: "vite.config.ts", content: REACT_VITE_CONFIG },
+    { path: "vitest.config.ts", content: VITEST_CONFIG },
+    { path: "playwright.config.ts", content: PLAYWRIGHT_CONFIG },
+    { path: "eslint.config.js", content: ESLINT_A11Y_CONFIG },
+    {
+      path: "idapt-ci.yml",
+      content: IDAPT_CI_YML.replaceAll("__APP_NAME__", n.name)
+    },
+    { path: "tsconfig.json", content: REACT_TSCONFIG },
+    { path: "src/main.tsx", content: REACT_MAIN_TSX },
+    {
+      path: "src/App.tsx",
+      content: REACT_APP_TSX.replaceAll("__APP_NAME__", n.name)
+    },
+    { path: "src/example.test.ts", content: EXAMPLE_UNIT_TEST },
+    { path: "e2e/app.spec.ts", content: E2E_SPEC }
+  ];
+}
+var VANILLA_INDEX_HTML = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>__APP_NAME__</title>
+    <link rel="stylesheet" href="main.css" />
+  </head>
+  <body>
+    <main class="app">
+      <h1>__APP_ICON__ __APP_NAME__</h1>
+      <p id="status">Connecting\u2026</p>
+    </main>
+    <!-- npm-only: the app bundles @idapt/browser-app-sdk itself (a dependency). -->
+    <script type="module" src="main.js"></script>
+  </body>
+</html>
+`;
+var VANILLA_MAIN_TS = `// __APP_NAME__ \u2014 a buildable idapt browser-app (esbuild).
+import { connect } from "@idapt/browser-app-sdk";
+
+const statusEl = document.getElementById("status");
+function setStatus(text: string) {
+  if (statusEl) statusEl.textContent = text;
+}
+
+// On an idapt app subdomain the app-key cookie auto-connects \u2014 no args.
+connect()
+  .then(() => setStatus("Connected."))
+  .catch(() => setStatus("Could not connect to idapt."));
+
+export {};
+`;
+var VANILLA_MAIN_CSS = `body {
+  margin: 0;
+  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  background: #0b0b0f;
+  color: #f4f4f5;
+}
+.app {
+  max-width: 36rem;
+  margin: 0 auto;
+  padding: 2rem 1.25rem;
+}
+`;
+var VANILLA_BUILD_SH = `set -e
+mkdir -p dist
+node_modules/.bin/esbuild src/main.ts --bundle --format=esm --outfile=dist/main.js
+cp index.html dist/index.html
+cp src/main.css dist/main.css
+`;
+function getVanillaScaffold(opts) {
+  const n = normalize(opts);
+  const pkg = {
+    name: "idapt-vanilla-app",
+    private: true,
+    version: "0.1.0",
+    type: "module",
+    scripts: {
+      // The build step runs build.sh so it can bundle + copy static assets.
+      build: "sh build.sh",
+      test: "vitest run",
+      "test:e2e": "playwright test"
+    },
+    dependencies: {
+      "@idapt/browser-app-sdk": BROWSER_APP_SDK_DEP_RANGE
+    },
+    devDependencies: {
+      "@playwright/test": "^1.48.0",
+      esbuild: "^0.23.0",
+      typescript: "^5.5.4",
+      vitest: "^2.1.0"
+    },
+    idapt: idaptManifest(n)
+  };
+  return [
+    { path: "package.json", content: `${JSON.stringify(pkg, null, 2)}
+` },
+    { path: "build.sh", content: VANILLA_BUILD_SH },
+    { path: "vitest.config.ts", content: VITEST_CONFIG },
+    { path: "playwright.config.ts", content: PLAYWRIGHT_CONFIG },
+    {
+      path: "idapt-ci.yml",
+      content: IDAPT_CI_YML.replaceAll("__APP_NAME__", n.name)
+    },
+    {
+      path: "index.html",
+      content: VANILLA_INDEX_HTML.replaceAll("__APP_NAME__", n.name).replaceAll(
+        "__APP_ICON__",
+        n.icon
+      )
+    },
+    {
+      path: "src/main.ts",
+      content: VANILLA_MAIN_TS.replaceAll("__APP_NAME__", n.name)
+    },
+    { path: "src/main.css", content: VANILLA_MAIN_CSS },
+    { path: "src/example.test.ts", content: EXAMPLE_UNIT_TEST },
+    { path: "e2e/app.spec.ts", content: E2E_SPEC }
+  ];
+}
+function getScaffoldFiles(template, opts) {
+  return template === "react" ? getReactScaffold(opts) : getVanillaScaffold(opts);
+}
+
+// src/app/init.ts
+function parseInitArgs(args) {
+  let name;
+  let template = "react";
+  let dir = ".";
+  let force = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--template" || a === "-t") {
+      template = normTemplate(args[++i]);
+    } else if (a.startsWith("--template=")) {
+      template = normTemplate(a.slice("--template=".length));
+    } else if (a === "--dir" || a === "-d") {
+      dir = args[++i] ?? ".";
+    } else if (a.startsWith("--dir=")) {
+      dir = a.slice("--dir=".length) || ".";
+    } else if (a === "--force" || a === "-f") {
+      force = true;
+    } else if (!a.startsWith("-") && name === void 0) {
+      name = a;
+    }
+  }
+  return { name, template, dir, force };
+}
+function normTemplate(v) {
+  return v === "vanilla" ? "vanilla" : "react";
+}
+function planInit(opts, io) {
+  if (opts.template !== "react" && opts.template !== "vanilla") {
+    return {
+      ok: false,
+      written: [],
+      error: `unknown template "${opts.template}" (use react or vanilla)`
+    };
+  }
+  if (!opts.force && io.dirIsNonEmpty(opts.dir)) {
+    return {
+      ok: false,
+      written: [],
+      error: `target "${opts.dir}" is not empty \u2014 pass --force to scaffold into it anyway`
+    };
+  }
+  const files = getScaffoldFiles(opts.template, {
+    name: opts.name ?? "My App"
+  });
+  const written = [];
+  for (const f of files) {
+    io.writeFile(join(opts.dir, f.path), f.content);
+    written.push(f.path);
+  }
+  return { ok: true, written };
+}
+function runAppInit(ctx, args) {
+  const opts = parseInitArgs(args);
+  const io = {
+    dirIsNonEmpty: (p) => {
+      const abs = resolve(p);
+      if (!existsSync(abs)) return false;
+      try {
+        return readdirSync(abs).length > 0;
+      } catch {
+        return false;
+      }
+    },
+    writeFile: (p, content) => {
+      const abs = resolve(p);
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, content, "utf-8");
+    }
+  };
+  const result = planInit(opts, io);
+  if (!result.ok) {
+    ctx.out(`idapt app init: ${result.error}`);
+    return 1;
+  }
+  ctx.print(
+    `Scaffolded a ${opts.template} browser-app in ${opts.dir} (${result.written.length} files).`
+  );
+  ctx.out(
+    [
+      "",
+      "Next steps:",
+      `  cd ${opts.dir}`,
+      "  npm install && npm run build",
+      "  idapt app deploy ./dist"
+    ].join("\n")
+  );
+  return 0;
+}
+
+// src/app/index.ts
+var APP_USAGE = `idapt app \u2014 local browser-app developer loop
+
+Usage:
+  idapt app init [name] [--template react|vanilla] [--dir .] [--force]
+  idapt app deploy <dir> [--app <id|name>] [--workspace <id>] [--name <name>]
+
+  init    Scaffold an npm browser-app project locally (then npm install && npm run build)
+  deploy  Upload a locally-built dist/ to a browser-app (creates one if --app is absent/unknown)`;
+async function runApp(ctx, args) {
+  const sub = args[0];
+  const rest = args.slice(1);
+  if (sub === "init") {
+    return runAppInit(ctx, rest);
+  }
+  if (sub === "deploy") {
+    if (!ctx.token) {
+      ctx.out(
+        "idapt app deploy: not signed in. Run `idapt login` (or set IDAPT_API_KEY)."
+      );
+      return 1;
+    }
+    const transport = createFetchTransport({
+      baseUrl: ctx.baseUrl,
+      token: ctx.token,
+      userAgent: USER_AGENT
+    });
+    const exec = (commandName, cmdArgs) => executeCommand(commandName, cmdArgs, { transport, mode: "json" });
+    return runAppDeploy(ctx, rest, exec);
+  }
+  if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
+    ctx.print(APP_USAGE);
+    return sub ? 0 : 1;
+  }
+  ctx.out(`idapt app: unknown subcommand "${sub}".
+
+${APP_USAGE}`);
+  return 1;
+}
 function canOpenBrowser(env, isTty) {
   if (!isTty) return false;
   if (env.SSH_CONNECTION || env.SSH_TTY) return false;
@@ -157,7 +829,7 @@ function loginAuthCode(io) {
   const base = trimRight(io.baseUrl);
   const { verifier, challenge } = generatePkce();
   const state = randomState();
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve3, reject) => {
     let settled = false;
     const finish = (fn) => {
       if (settled) return;
@@ -216,7 +888,7 @@ function loginAuthCode(io) {
         },
         io.userAgent
       ).then(
-        (tok) => finish(() => resolve(tok)),
+        (tok) => finish(() => resolve3(tok)),
         (e) => finish(() => reject(e))
       );
     });
@@ -256,8 +928,8 @@ If it doesn't open, visit:
     });
   });
 }
-var sleep = (ms, signal) => new Promise((resolve, reject) => {
-  const t = setTimeout(resolve, ms);
+var sleep = (ms, signal) => new Promise((resolve3, reject) => {
+  const t = setTimeout(resolve3, ms);
   signal?.addEventListener("abort", () => {
     clearTimeout(t);
     reject(new AuthError("sign-in cancelled"));
@@ -516,6 +1188,10 @@ async function runStatus(ctx) {
 }
 
 // src/doc.ts
+function dumpJson(resource) {
+  const entries = resource ? commandCatalog.filter((c) => c.resource === resource) : commandCatalog;
+  return JSON.stringify(entries, null, 2);
+}
 function helpIndex() {
   const resources = listResources().sort().join(", ");
   return [
@@ -525,6 +1201,7 @@ function helpIndex() {
     "  idapt <resource> <verb> [args]     Run a command (e.g. idapt drive list)",
     "  idapt help [resource [verb]]       Show a command's contract",
     "  idapt instructions [resource]      Show a resource's playbook",
+    "  idapt app init | deploy            Scaffold + ship a local browser-app",
     "  idapt login | logout | whoami      Authenticate",
     "  idapt upgrade                      Update to the latest version",
     "",
@@ -552,9 +1229,11 @@ function resourceHelp(resource, cmds) {
   ].join("\n");
 }
 function renderHelpDoc(tokens) {
-  if (tokens.length === 0) return helpIndex();
-  if (tokens.length === 1) {
-    const resource = tokens[0];
+  const positional = tokens.filter((t) => !t.startsWith("-"));
+  if (tokens.includes("--dump-json")) return dumpJson(positional[0]);
+  if (positional.length === 0) return helpIndex();
+  if (positional.length === 1) {
+    const resource = positional[0];
     const cmds2 = commandsForResource(resource);
     if (cmds2.length === 0) {
       return `Unknown resource "${resource}".
@@ -563,14 +1242,14 @@ ${helpIndex()}`;
     }
     return resourceHelp(resource, cmds2);
   }
-  const command = `${tokens[0]} ${tokens[1]}`;
+  const command = `${positional[0]} ${positional[1]}`;
   const spec = findCommand(command);
   if (spec) return renderHelp(spec);
-  const cmds = commandsForResource(tokens[0]);
+  const cmds = commandsForResource(positional[0]);
   if (cmds.length > 0) {
     return `Unknown command "${command}".
 
-${resourceHelp(tokens[0], cmds)}`;
+${resourceHelp(positional[0], cmds)}`;
   }
   return `Unknown command "${command}".
 
@@ -703,12 +1382,12 @@ function detectManager(scriptPath, env, channel) {
   };
 }
 function spawnInherit(cmd, args) {
-  return new Promise((resolve) => {
+  return new Promise((resolve3) => {
     const child = process.platform === "win32" ? spawn(process.env.ComSpec || "cmd.exe", ["/c", cmd, ...args], {
       stdio: "inherit"
     }) : spawn(cmd, args, { stdio: "inherit" });
-    child.on("error", () => resolve(127));
-    child.on("close", (code) => resolve(code ?? 0));
+    child.on("error", () => resolve3(127));
+    child.on("close", (code) => resolve3(code ?? 0));
   });
 }
 async function runUpgrade(io, opts) {
@@ -798,6 +1477,31 @@ function extractValueFlag(argv, name) {
 function buildCommandFromArgv(argv) {
   return ["idapt", ...argv.map(quoteToken)].join(" ");
 }
+function resolveJsonArgSource(argv, io) {
+  const resolveVal = (val) => {
+    if (val === "-") return io.readStdin();
+    if (val.startsWith("@")) return io.readFile(val.slice(1));
+    return null;
+  };
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (tok.startsWith("--json=")) {
+      const resolved = resolveVal(tok.slice("--json=".length));
+      out.push(resolved === null ? tok : `--json=${resolved}`);
+      continue;
+    }
+    if (tok === "--json" && i + 1 < argv.length) {
+      out.push(tok);
+      const resolved = resolveVal(argv[i + 1]);
+      out.push(resolved === null ? argv[i + 1] : resolved);
+      i++;
+      continue;
+    }
+    out.push(tok);
+  }
+  return out;
+}
 function isDocCommand(rest) {
   if (rest[0] === "help" || rest[0] === "instructions") return true;
   return rest.some(
@@ -865,6 +1569,23 @@ async function run(io) {
     );
     return 1;
   }
+  if (cmd === "app") {
+    const appCred = await resolveCredential({
+      apiKeyFlag,
+      env: io.env,
+      baseUrl,
+      userAgent: USER_AGENT
+    }).catch(() => null);
+    return runApp(
+      {
+        out: io.stderr,
+        print: io.stdout,
+        baseUrl,
+        token: appCred?.token
+      },
+      rest.slice(1)
+    );
+  }
   const doc = isDocCommand(rest);
   let token;
   const resolved = await resolveCredential({
@@ -887,7 +1608,11 @@ async function run(io) {
     token,
     userAgent: USER_AGENT
   });
-  const result = await execute(buildCommandFromArgv(rest), {
+  const restWithJson = resolveJsonArgSource(rest, {
+    readFile: (p) => readFileSync(p, "utf-8"),
+    readStdin: () => readFileSync(0, "utf-8")
+  });
+  const result = await execute(buildCommandFromArgv(restWithJson), {
     transport,
     mode: autoMode(io.isTty, requested)
   });
@@ -923,6 +1648,6 @@ if (typeof process !== "undefined" && isCliEntrypoint(process.argv[1])) {
   void main();
 }
 
-export { buildCommandFromArgv, extractOutputMode, extractValueFlag, isCliEntrypoint, isDocCommand, run };
+export { buildCommandFromArgv, extractOutputMode, extractValueFlag, isCliEntrypoint, isDocCommand, resolveJsonArgSource, run };
 //# sourceMappingURL=bin.js.map
 //# sourceMappingURL=bin.js.map