@overaihq/cli 0.1.0 → 0.2.0

package/dist/index.js

@@ -48,15 +48,7 @@ var appBaseUrl = trimSlash(
 
 // src/api.ts
 var apiBaseUrl = () => apiBaseUrlOverride ?? readConfig()?.apiBaseUrl ?? DEFAULT_API_BASE_URL;
-var trpcMutation = async (procedure, input) => {
-  const res = await fetch(
-    `${apiBaseUrl()}/v1/utils/trpc/unauthenticated/${procedure}`,
-    {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(input)
-    }
-  );
+var trpcResult = async (res, procedure) => {
   const body = await res.json().catch(() => null);
   if (body != null && "error" in body) {
     throw new Error(
@@ -68,6 +60,17 @@ var trpcMutation = async (procedure, input) => {
   }
   return body.result.data;
 };
+var trpcMutation = async (procedure, input) => {
+  const res = await fetch(
+    `${apiBaseUrl()}/v1/utils/trpc/unauthenticated/${procedure}`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input)
+    }
+  );
+  return trpcResult(res, procedure);
+};
 var exchangeCliAuthCode = (code, codeVerifier) => trpcMutation("exchangeCliAuthCode", { code, codeVerifier });
 var exchangeSessionToken = (refreshToken, destinationOrgId) => trpcMutation("exchangeSessionToken", {
   refreshToken,
@@ -136,6 +139,14 @@ var v2Fetch = async (path, init) => {
   headers.set("Authorization", `Bearer ${auth.token}`);
   return fetch(`${apiBaseUrl()}${path}`, { ...init, headers });
 };
+var userTrpcMutation = async (procedure, input) => {
+  const res = await v2Fetch(`/v1/utils/trpc/${procedure}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(input)
+  });
+  return trpcResult(res, procedure);
+};
 
 // src/browser.ts
 import { spawn } from "child_process";
@@ -284,6 +295,7 @@ var whoami = () => {
 };
 
 // src/args.ts
+import { readFileSync as readFileSync2 } from "fs";
 var flagValue = (args, ...names) => {
   for (const name of names) {
     const i = args.indexOf(name);
@@ -291,21 +303,44 @@ var flagValue = (args, ...names) => {
   }
   return void 0;
 };
-var readStdin = async () => {
+var stdinClaimedBy = null;
+var readStdin = async (claimant = "stdin") => {
+  if (stdinClaimedBy != null) {
+    throw new Error(
+      `Only one value can be read from stdin; ${stdinClaimedBy} already consumed it.`
+    );
+  }
+  stdinClaimedBy = claimant;
   const chunks = [];
   for await (const chunk of process.stdin) {
     chunks.push(chunk);
   }
   return Buffer.concat(chunks).toString("utf8");
 };
+var readValue = async (value, label) => {
+  if (value?.startsWith("@") !== true) return value;
+  if (value.startsWith("@@")) return value.slice(1);
+  const path = value.slice(1);
+  if (path === "-") return (await readStdin(`${label} @-`)).trim();
+  try {
+    return readFileSync2(path, "utf8").trim();
+  } catch {
+    throw new Error(
+      `${label}: could not read file "${path}". Write "@@" to send a literal value starting with "@".`
+    );
+  }
+};
 
 // src/gql.ts
-var gqlRequest = async (query, variables) => {
-  const res = await v2Fetch("/v2/graphql", {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ query, variables })
-  });
+var gqlRequest = async (query, variables, options) => {
+  const res = await v2Fetch(
+    options?.v1 === true ? "/v1/graphql" : "/v2/graphql",
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ query, variables })
+    }
+  );
   const body = await res.json().catch(() => null);
   if (body?.errors != null && body.errors.length > 0) {
     throw new Error(body.errors.map((e) => e.message).join("; "));
@@ -467,7 +502,7 @@ import { createServer as createServer2 } from "http";
 import { dirname as dirname2, join as join4 } from "path";
 
 // src/workspace/manifest.ts
-import { existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
 import { dirname, join as join2, resolve } from "path";
 var MANIFEST_DIR = ".overai";
 var MANIFEST_FILE = "manifest.json";
@@ -486,7 +521,7 @@ var findWorkspaceRoot = (from = process.cwd()) => {
   }
 };
 var readManifest = (root) => JSON.parse(
-  readFileSync2(join2(root, MANIFEST_DIR, MANIFEST_FILE), "utf8")
+  readFileSync3(join2(root, MANIFEST_DIR, MANIFEST_FILE), "utf8")
 );
 var openClone = () => {
   const root = findWorkspaceRoot();
@@ -511,14 +546,14 @@ var writeSynced = (root, relPath, content) => {
 };
 var readWorkingFile = (root, relPath) => {
   try {
-    return readFileSync2(join2(root, relPath), "utf8");
+    return readFileSync3(join2(root, relPath), "utf8");
   } catch {
     return null;
   }
 };
 var readBaseFile = (root, relPath) => {
   try {
-    return readFileSync2(basePath(root, relPath), "utf8");
+    return readFileSync3(basePath(root, relPath), "utf8");
   } catch {
     return null;
   }
@@ -542,10 +577,14 @@ var localState = (root, resource) => {
 };
 
 // src/workspace/validateElements.ts
+var findings = (parsed) => parsed.success ? [] : parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`);
 var validateAutomationElements = async (elements) => {
-  const { automationNodesSchema } = await import("./types-5J3QQFGH.js");
-  const parsed = automationNodesSchema.safeParse(elements);
-  return parsed.success ? [] : parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`);
+  const { automationNodesSchema } = await import("./types-7F2H2ASS.js");
+  return findings(automationNodesSchema.safeParse(elements));
+};
+var validateWebPageConfig = async (config) => {
+  const { webPageConfigWriteSchema } = await import("./webPage-FN3A45OT.js");
+  return findings(webPageConfigWriteSchema.safeParse(config));
 };
 
 // src/workspace/adapters.ts
@@ -633,7 +672,7 @@ var functionAdapter = {
   push: async (id, files, message) => {
     const meta = JSON.parse(fileBySuffix(files, ".meta.json"));
     const data = await gqlRequest(
-      `mutation CliCreateFunctionVersion($functionId: String!, $code: String!, $message: String, $inputSchema: JSON, $executionTimeout: Int, $executionMemory: Int) {
+      `mutation CliCreateFunctionVersion($functionId: String!, $code: String!, $message: String, $inputSchema: String, $executionTimeout: Int, $executionMemory: Int) {
         createFunctionVersion(input: { functionVersion: {
           functionId: $functionId, code: $code, message: $message,
           inputSchema: $inputSchema, executionTimeout: $executionTimeout, executionMemory: $executionMemory
@@ -643,8 +682,9 @@ var functionAdapter = {
         functionId: id,
         code: fileBySuffix(files, ".ts"),
         message,
-        inputSchema: meta.inputSchema,
-        // Match the webapp's save defaults so a missing meta doesn't zero out limits.
+        // Match the webapp's save defaults so a missing meta doesn't zero out
+        // limits, and so an explicit null doesn't hit the NOT NULL column.
+        inputSchema: meta.inputSchema ?? "",
         executionTimeout: meta.executionTimeout ?? 1e4,
         executionMemory: meta.executionMemory ?? 512
       }
@@ -757,6 +797,13 @@ var pageAdapter = (opts) => {
     },
     push: async (id, files, message) => {
       const config = pageConfigFromFiles(files);
+      const findings2 = await opts.validateConfig?.(config) ?? [];
+      if (findings2.length > 0) {
+        throw new Error(
+          `Invalid page config:
+${findings2.map((f) => `  ${f}`).join("\n")}`
+        );
+      }
       const data = await gqlRequest(
         `mutation CliCreatePageVersion($id: String!, $message: String, $config: JSON!) {
           create${capitalized}Version(input: { ${gqlName}Version: { ${idArg}: $id, message: $message, config: $config } }) {
@@ -860,11 +907,11 @@ var automationAdapter = {
   },
   push: async (id, files, message) => {
     const doc = JSON.parse(fileBySuffix(files, ".json"));
-    const findings = await validateAutomationElements(doc.elements);
-    if (findings.length > 0) {
+    const findings2 = await validateAutomationElements(doc.elements);
+    if (findings2.length > 0) {
       throw new Error(
         `Invalid automation elements:
-${findings.map((f) => `  ${f}`).join("\n")}`
+${findings2.map((f) => `  ${f}`).join("\n")}`
       );
     }
     const data = await gqlRequest(
@@ -908,7 +955,8 @@ ${findings.map((f) => `  ${f}`).join("\n")}`
 var webPageAdapter = pageAdapter({
   type: "webPage",
   dir: "web-pages",
-  gqlName: "webPage"
+  gqlName: "webPage",
+  validateConfig: validateWebPageConfig
 });
 var printablePageAdapter = pageAdapter({
   type: "printablePage",
@@ -1443,16 +1491,29 @@ var runFn = async (args) => {
   const functionId = args[0];
   if (functionId == null || functionId.startsWith("-")) {
     throw new Error(
-      "Usage: overai fn <functionId> [--input key=value ... | -]\n       overai fn logs <functionId> [--limit N] [--execution <id>]"
+      "Usage: overai fn <functionId> [--method GET] [--path /features/123] [--input key=value ... | -]\n       overai fn logs <functionId> [--limit N] [--execution <id>]"
+    );
+  }
+  const method = (flagValue(args, "--method") ?? "POST").toUpperCase();
+  const rawPath = flagValue(args, "--path") ?? "";
+  const subPath = rawPath && !rawPath.startsWith("/") ? `/${rawPath}` : rawPath;
+  const sendsBody = !["GET", "HEAD", "DELETE"].includes(method);
+  if (!sendsBody && (args.includes("--input") || args.includes("-"))) {
+    process.stderr.write(
+      `warning: ${method} sends no request body, so --input is ignored. Pass values as a query string on --path instead, e.g. --path '/search?a=1'.
+`
     );
   }
-  const input = await collectInput(args);
+  const input = sendsBody ? await collectInput(args) : void 0;
   const { organizationId } = await getAccessToken();
-  const res = await v2Fetch(`/v2/functions/${organizationId}/${functionId}`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(input)
-  });
+  const res = await v2Fetch(
+    `/v2/functions/${organizationId}/${functionId}${subPath}`,
+    {
+      method,
+      headers: sendsBody ? { "Content-Type": "application/json" } : {},
+      body: sendsBody ? JSON.stringify(input) : void 0
+    }
+  );
   const executionId = res.headers.get("x-execution-id");
   if (executionId != null) {
     process.stderr.write(`execution: ${executionId}
@@ -1476,21 +1537,32 @@ var runFn = async (args) => {
 };
 
 // src/commands/graphql.ts
-import { readFileSync as readFileSync3 } from "fs";
+import { readFileSync as readFileSync4 } from "fs";
 var runGraphql = async (args) => {
-  const inline = flagValue(args, "-q", "--query");
+  const inline = await readValue(flagValue(args, "-q", "--query"), "-q");
   const file = flagValue(args, "-f", "--file");
-  const query = inline ?? (file != null ? readFileSync3(file, "utf8") : process.stdin.isTTY ? "" : (await readStdin()).trim());
+  const query = inline ?? (file != null ? readFileSync4(file, "utf8") : process.stdin.isTTY ? "" : (await readStdin("the query")).trim());
   if (query.length === 0) {
-    throw new Error("Provide a query with -q '<query>', -f <file>, or stdin.");
+    throw new Error(
+      "Provide a query with -q '<query>', -q @<file>, -f <file>, or stdin."
+    );
   }
-  const variablesJson = flagValue(args, "--variables");
+  const variablesArg = flagValue(args, "--variables");
+  const variablesJson = await readValue(variablesArg, "--variables");
   const variables = (() => {
     if (variablesJson == null) return void 0;
     try {
       return JSON.parse(variablesJson);
-    } catch {
-      throw new Error(`--variables must be valid JSON. Got: ${variablesJson}`);
+    } catch (error) {
+      throw new Error(
+        [
+          `--variables is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+          `Got ${String(variablesJson.length)} chars starting: ${variablesJson.slice(0, 200)}`,
+          ...variablesArg?.startsWith("@") === true ? [] : [
+            `Pass --variables @<file.json> instead \u2014 an inline value is re-read by the shell, which expands $names and drops quotes.`
+          ]
+        ].join("\n")
+      );
     }
   })();
   const res = await v2Fetch(
@@ -1636,6 +1708,154 @@ ${result.redirectUrl}
 `);
 };
 
+// src/commands/update.ts
+import { spawnSync } from "child_process";
+import { existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
+import { fileURLToPath } from "url";
+var PACKAGE_NAME = "@overaihq/cli";
+var packageRootUrl = () => {
+  for (const up of ["..", "../..", "../../.."]) {
+    if (existsSync3(new URL(`${up}/package.json`, import.meta.url))) {
+      return new URL(`${up}/`, import.meta.url);
+    }
+  }
+  throw new Error("package.json not found relative to the CLI bundle");
+};
+var cliVersion = () => {
+  const pkg = JSON.parse(
+    readFileSync5(new URL("package.json", packageRootUrl()), "utf8")
+  );
+  return pkg.version;
+};
+var detectInstaller = () => {
+  const path = fileURLToPath(import.meta.url);
+  if (path.includes("_npx") || path.includes("dlx-")) return "ephemeral";
+  if (path.includes(".pnpm") || /[\\/]pnpm[\\/]/.test(path)) return "pnpm";
+  if (path.includes(".bun")) return "bun";
+  return "npm";
+};
+var runUpdate = async () => {
+  const current = cliVersion();
+  if (existsSync3(new URL("src", packageRootUrl()))) {
+    process.stdout.write(
+      "Development build \u2014 rebuild from the repo instead of updating from npm.\n"
+    );
+    return;
+  }
+  const res = await fetch(
+    `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}/latest`,
+    // Bound the lookup so a slow/unreachable registry can't hang the command.
+    { signal: AbortSignal.timeout(1e4) }
+  );
+  if (!res.ok) {
+    throw new Error(`npm registry lookup failed (HTTP ${String(res.status)})`);
+  }
+  const body = await res.json();
+  const latest = typeof body.version === "string" ? body.version : null;
+  if (latest == null) {
+    throw new Error("npm registry returned an unexpected response");
+  }
+  if (latest === current) {
+    process.stdout.write(`overai ${current} is up to date.
+`);
+    return;
+  }
+  const cur = current.split(".").map(Number);
+  const lat = latest.split(".").map(Number);
+  const cmp = cur.map((n, i) => n - (lat[i] ?? 0)).find((d) => d !== 0) ?? 0;
+  if (cmp > 0) {
+    process.stdout.write(
+      `overai ${current} is ahead of latest (${latest}) \u2014 likely a @next install; nothing to do.
+`
+    );
+    return;
+  }
+  const installer = detectInstaller();
+  if (installer === "ephemeral") {
+    process.stdout.write(
+      `Running from an npx/dlx cache (current ${current}, latest ${latest}) \u2014 invoke as \`npx ${PACKAGE_NAME}@latest\` to always get the newest release.
+`
+    );
+    return;
+  }
+  const spec = `${PACKAGE_NAME}@${latest}`;
+  const argsByInstaller = {
+    npm: ["npm", "install", "-g", spec],
+    pnpm: ["pnpm", "add", "-g", spec],
+    bun: ["bun", "add", "-g", spec]
+  };
+  const [cmd, ...args] = argsByInstaller[installer];
+  process.stdout.write(
+    `Updating overai ${current} \u2192 ${latest} via ${installer}\u2026
+`
+  );
+  const result = spawnSync(cmd, args, {
+    stdio: "inherit",
+    // npm/pnpm are .cmd shims on Windows; a shell is required to resolve them.
+    shell: process.platform === "win32"
+  });
+  if (result.status !== 0) {
+    throw new Error(
+      `${[cmd, ...args].join(" ")} failed (exit ${String(result.status ?? "?")})`
+    );
+  }
+  process.stdout.write(`Updated to ${latest}.
+`);
+};
+
+// src/commands/report.ts
+var reportInput = async (args, stdin = readStdin) => {
+  const [type, ...bodyArgs] = args;
+  if (type !== "bug" && type !== "feature") {
+    throw new Error(
+      'Usage: overai report bug|feature "<details>" (or pass - to read stdin)'
+    );
+  }
+  const detailedBugReport = (bodyArgs.length === 1 && bodyArgs[0] === "-" ? await stdin() : bodyArgs.join(" ")).trim();
+  if (detailedBugReport.length === 0) {
+    throw new Error(
+      `${type === "bug" ? "Bug report" : "Feature request"} details cannot be empty.`
+    );
+  }
+  if (detailedBugReport.length > 8e3) {
+    throw new Error("Report details cannot exceed 8000 characters.");
+  }
+  return { feedbackType: type, detailedBugReport };
+};
+var runReport = async (args) => {
+  const input = await reportInput(args);
+  const manifest = (() => {
+    try {
+      return openClone().manifest;
+    } catch {
+      return null;
+    }
+  })();
+  const resources = manifest ? Object.entries(manifest.resources) : [];
+  await userTrpcMutation("architectIssues.report", {
+    ...input,
+    source: "cli",
+    cliContext: {
+      cliVersion: cliVersion(),
+      nodeVersion: process.version,
+      platform: process.platform,
+      architecture: process.arch,
+      workspaceId: manifest?.workspaceId.slice(0, 200),
+      workspaceName: manifest?.workspaceName.slice(0, 500),
+      resources: manifest ? resources.slice(0, 500).map(([id, resource]) => ({
+        id: id.slice(0, 200),
+        name: resource.name.slice(0, 500),
+        type: resource.type.slice(0, 100)
+      })) : void 0,
+      omittedResourceCount: Math.max(0, resources.length - 500)
+    }
+  });
+  process.stdout.write(
+    `${input.feedbackType === "bug" ? "Bug report" : "Feature request"} sent to OverAI.
+`
+  );
+};
+
 // src/docs/bestPractices.ts
 var platform2 = `# OverAI platform primer
 
@@ -1651,11 +1871,23 @@ deploy\` makes it live. Pick primitives by trigger:
   **Data Files** (env.DFxxx) for versioned single-file datasets. Prefer
   first-class platform features over third-party integrations.
 
+When broken or unexplained platform behavior blocks progress, send a detailed
+report with \`overai report bug -\`. When a missing platform capability forces
+a significant workaround, use \`overai report feature -\`. Include the goal,
+actual limitation, desired behavior, and relevant errors or resource IDs. Do
+not report speculative niceties or every failed attempt; no separate user
+confirmation is needed because invoking the command explicitly submits it.
+
 The env SDK is the same in pages, functions, and automation code nodes:
 env.TBSxxx.sql\`...\` (postgres.js tagged template \u2014 interpolations are
-auto-parameterized, never string-concatenate user input), env.FNxxx.call(),
+auto-parameterized, never string-concatenate user input), env.FNxxx.call()
+(pass \`path\` to hit a sub-path of a function that routes internally),
 env.ATxxx.start(inputs?) (fire-and-forget), env.DFxxx.read.json()/.saveVersion(),
-env.STORAGE, env.AI.generateText/generateObject, env.GRAPHQL.request().`;
+env.STORAGE (incl. zipTree/zipExtract to list a zip without decompressing it and
+pull out only the entries you need; upload and zipExtract shorten stored names over
+128 characters in the middle while preserving their ends),
+env.AI.generateText/generateObject,
+env.GRAPHQL.request().`;
 var automations = `# Automation best practices
 
 An automation's elements document is the node graph: an array of nodes, each
@@ -1673,6 +1905,10 @@ Rules that keep graphs healthy:
   {{S1.field}}). After renaming/removing a node, grep the document for its
   variableId \u2014 dangling references fail at runtime, not at push.
 - Bring IF_ELSE branches back together with an ALWAYS node.
+- A loop (LOOP_ARRAY/LOOP_RANGE) always resolves to its success handle once all
+  iterations finish, even if some or all iterations error \u2014 it never takes a
+  failure path. Handle errors on the child nodes inside the loop, or inspect
+  \`iterations\`, to catch per-iteration failures.
 - Activation requires a deployed version with an EVENT trigger node \u2014
   activating without one silently no-ops.
 
@@ -1709,6 +1945,31 @@ language, customTitle, hideTopBar, ...). Push reassembles them.
 - For guest-facing workspaces, add page-to-page navigation (guests land on the
   workspace homepage and can only follow links). "Hide Top Bar" gives an
   app-like experience.
+- Public pages (/public/:id) have no viewer identity \u2014 useCurrentUser() is
+  null. Identity-scoped features degrade: useAgentChat streams but persists
+  nothing (conversationId stays null, useAgentConversations is empty, the
+  conversation helpers throw), and author-requiring writes like
+  env.DFxxx.saveVersion 401. Reads use the workspace's own access, so treat
+  anything the page can query as public.
+- Write meta.json flags (noSandbox, hideTopBar) as JSON booleans. A page cloned
+  before the shape settled may hold the strings "true"/"false" \u2014 those still
+  push, anything else is rejected. noSandbox drops the iframe sandbox, which
+  localStorage/sessionStorage, cookies, form submission and
+  alert/confirm/prompt all require.
+- dataSourceUrl and filter in meta.json are legacy: they populate the \`data\` and
+  \`items\` globals, frozen at render start, and filter reads the old
+  item/attribute model. For new pages load data in the page instead \u2014 web pages
+  via env.TBSxxx.sql / env.DFxxx, printable pages via fetch with the \`token\`
+  global (no env proxy there). Don't rewrite a working page just to migrate it.
+- dataSourceUrl in meta.json is fetched verbatim and its response becomes the
+  \`data\` global. It is a static URL, not a template \u2014 search params are NOT
+  substituted into it (neither {x} nor Liquid {{ x }}). If the data depends on
+  a search param, fetch it in the page instead. To clear it use JSON null; the
+  string "null" is a four-character URL that fails at fetch time.
+- Printable page PDFs render in a headless browser that waits for network idle,
+  so useEffect fetches DO resolve before capture. Load data in the page \u2014 you
+  don't need to pre-fetch it into searchParams or stage it in storage. A blank
+  PDF is far more often an undeployed version than a timing problem.
 - Console logs are visible in the webapp editor; use them to verify behavior
   after deploying.`;
 var functions = `# Function best practices
@@ -1718,10 +1979,14 @@ esm.sh imports allowed. The CLI materializes <slug>.<id>.ts (code) and
 <slug>.<id>.meta.json (inputSchema, executionTimeout ms, executionMemory MB).
 
 - Functions are full HTTP apps: method + sub-path are forwarded to your code,
-  and each execution records requestMethod/requestPath.
+  and each execution records requestMethod/requestPath. Callers reach a route
+  with env.FNxxx.call({ method, path: "/features/123" }) \u2014 path defaults to the
+  base path and method to POST.
 - Keep the inputSchema in sync with what the code actually reads \u2014 callers
-  (agents, pages, automations) rely on it.
-- Verify with \`overai fn <id> --input k=v\` (invokes the DEPLOYED version) and
+  (agents, pages, automations) rely on it. It is a JSON-encoded string, so it
+  appears escaped inside meta.json.
+- Verify with \`overai fn <id> --input k=v\` (invokes the DEPLOYED version;
+  add \`--method\`/\`--path\` to exercise one route of a router) and
   \`overai fn logs <id>\` / \`--execution <FEX id>\` for status, timing, logs,
   and input/output bodies.
 - Version discipline: function_execution.versionNumber tells you exactly which
@@ -1729,7 +1994,10 @@ esm.sh imports allowed. The CLI materializes <slug>.<id>.ts (code) and
   failure.`;
 var workflow = `# CLI editing workflow
 
-1. \`overai clone <workspaceId>\` (or \`overai pull\` in an existing clone).
+1. \`overai workspace list\` to find the id, then \`overai clone <workspaceId>\`
+   (or \`overai pull\` in an existing clone). Workspaces nest, and clone pulls
+   ONE workspace \u2014 a parent's clone does not include its children, so clone
+   each nested workspace you need separately.
 2. Edit files. The id in each filename is authoritative; slugs are cosmetic.
 3. \`overai status\` / \`overai diff\` \u2014 review what changed.
 4. \`overai review\` \u2014 validation + these guides; fix findings first.
@@ -1772,7 +2040,7 @@ var runBestPractices = (args) => {
 var runReview = async () => {
   const root = findWorkspaceRoot();
   const manifest = readManifest(root);
-  const findings = [];
+  const findings2 = [];
   const touchedTypes = /* @__PURE__ */ new Set();
   const changed = [];
   for (const [id, resource] of Object.entries(manifest.resources)) {
@@ -1789,14 +2057,14 @@ var runReview = async () => {
         try {
           JSON.parse(content);
         } catch (error) {
-          findings.push(
+          findings2.push(
             `${relPath}: invalid JSON \u2014 ${error instanceof Error ? error.message : String(error)}`
           );
           continue;
         }
       }
       if (!relPath.endsWith(".meta.json") && content.trim().length === 0) {
-        findings.push(
+        findings2.push(
           `${relPath}: file is empty \u2014 push would blank the resource.`
         );
       }
@@ -1805,17 +2073,17 @@ var runReview = async () => {
         for (const match of content.matchAll(importRe)) {
           const specifier = match[1];
           if (specifier == null || specifier.startsWith("https://")) continue;
-          findings.push(
+          findings2.push(
             /^react(-dom)?(\/|$)/.test(specifier) ? `${relPath}: imports "${specifier}" \u2014 React and its hooks are already in scope; remove the import or the page renders blank.` : `${relPath}: imports "${specifier}" \u2014 the page sandbox can only import https URLs (use https://esm.sh/...).`
           );
         }
         if (/^\s*export\s+default\b/m.test(content)) {
-          findings.push(
+          findings2.push(
             `${relPath}: uses \`export default\` \u2014 declare a plain \`function App() {}\`; the runtime appends the render call.`
           );
         }
         if (!/\b(function|const|let)\s+App\b/.test(content)) {
-          findings.push(
+          findings2.push(
             `${relPath}: no App component found \u2014 page code must declare \`function App() {}\`.`
           );
         }
@@ -1827,7 +2095,7 @@ var runReview = async () => {
       if (docFile != null && raw != null) {
         try {
           const doc = JSON.parse(raw);
-          findings.push(
+          findings2.push(
             ...(await validateAutomationElements(doc.elements)).map(
               (f) => `${docFile} elements.${f}`
             )
@@ -1849,7 +2117,7 @@ var runReview = async () => {
       ...changed.map((c) => `- ${c}`),
       "",
       "## Validation findings",
-      findings.length > 0 ? findings.map((f) => `- ${f}`).join("\n") : "- none (mechanical checks passed \u2014 still review the diff against the guides below)",
+      findings2.length > 0 ? findings2.map((f) => `- ${f}`).join("\n") : "- none (mechanical checks passed \u2014 still review the diff against the guides below)",
       "",
       "## Review guides",
       "Review `overai diff` output against these before pushing:",
@@ -1860,6 +2128,155 @@ var runReview = async () => {
   );
 };
 
+// src/commands/runner.ts
+var runCreate = async (workspaceId, args) => {
+  const name = flagValue(args, "--name") ?? "Action Runner";
+  const identityResult = await gqlRequest(
+    `mutation CliCreateMachineIdentity($name: String!) {
+      identityInsert(object: { name: $name, type: "machine" }) { id }
+    }`,
+    { name },
+    { v1: true }
+  );
+  const identityId = identityResult.identityInsert?.id;
+  if (identityId == null) throw new Error("Failed to create machine identity");
+  await gqlRequest(
+    `mutation CliCreateIdentityOrganization($identityId: String!) {
+      createIdentityOrganization(
+        input: { identityOrganization: { identityId: $identityId } }
+      ) { identityOrganization { identityId } }
+    }`,
+    { identityId }
+  );
+  const runnerResult = await gqlRequest(
+    `mutation CliCreateActionRunner($identityId: String!, $workspaceId: String!) {
+      createActionRunner(
+        input: { actionRunner: { identityId: $identityId, workspaceId: $workspaceId } }
+      ) { actionRunner { id } }
+    }`,
+    { identityId, workspaceId }
+  );
+  const actionRunnerId = runnerResult.createActionRunner?.actionRunner?.id;
+  if (actionRunnerId == null) throw new Error("Failed to create action runner");
+  printResult(
+    { actionRunnerId, identityId, name, workspaceId },
+    resolveFormat(flagValue(args, "-o", "--output"))
+  );
+};
+var runToken = async (runnerId, args) => {
+  const note = flagValue(args, "--note") ?? "cli";
+  const result = await gqlRequest(
+    `mutation CliCreateActionRunnerToken($actionRunnerId: String!, $note: String) {
+      createActionRunnerToken(
+        input: { actionRunnerId: $actionRunnerId, note: $note }
+      ) { result }
+    }`,
+    { actionRunnerId: runnerId, note }
+  );
+  const secret = result.createActionRunnerToken?.result;
+  if (secret == null) throw new Error("Failed to mint runner token");
+  printResult(
+    { runnerId, secret },
+    resolveFormat(flagValue(args, "-o", "--output"))
+  );
+};
+var resolveWorkspaceId = async (runnerId) => {
+  const data = await gqlRequest(
+    `query CliResolveRunner($id: String!) {
+      actionRunners(condition: { id: $id }, first: 1) { nodes { workspaceId } }
+    }`,
+    { id: runnerId }
+  );
+  const workspaceId = data.actionRunners.nodes[0]?.workspaceId;
+  if (workspaceId == null) {
+    throw new Error(
+      `Unknown runner ${runnerId} (or it has no workspace). Try: overai runner list`
+    );
+  }
+  return workspaceId;
+};
+var enqueueAction = async (runnerId, actionId, inputs, args) => {
+  const { organizationId } = await getAccessToken();
+  const workspaceId = await resolveWorkspaceId(runnerId);
+  const res = await v2Fetch(
+    `/v2/actions/${organizationId}/${workspaceId}/run`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ actionId, inputs, actionRunnerId: runnerId })
+    }
+  );
+  const body = await res.json().catch(() => null);
+  if (!res.ok) {
+    throw new Error(body?.error ?? `run failed (${String(res.status)})`);
+  }
+  printResult(body, resolveFormat(flagValue(args, "-o", "--output")));
+};
+var runRun = async (runnerId, args) => {
+  const code = await readValue(flagValue(args, "--code"), "--code") ?? (process.stdin.isTTY ? "" : (await readStdin("the code")).trim());
+  if (code.length === 0) {
+    throw new Error(
+      "Provide a command with --code '<code>', --code @<file>, or piped stdin."
+    );
+  }
+  const interpreter = flagValue(args, "--interpreter") ?? "shell";
+  if (interpreter !== "shell" && interpreter !== "powershell") {
+    throw new Error("--interpreter must be 'shell' or 'powershell'.");
+  }
+  await enqueueAction(
+    runnerId,
+    "RUNNER_RUN_COMMAND",
+    { actionRunnerId: runnerId, interpreter, code },
+    args
+  );
+};
+var runUpload = async (runnerId, args) => {
+  const path = flagValue(args, "--path");
+  if (path == null || path.length === 0) {
+    throw new Error("Provide a file with --path '<path>'.");
+  }
+  await enqueueAction(
+    runnerId,
+    "RUNNER_UPLOAD_FILE",
+    { actionRunnerId: runnerId, filePath: path },
+    args
+  );
+};
+var runList = async (args) => {
+  const workspaceId = args.find((a) => !a.startsWith("-"));
+  const limit = Number(flagValue(args, "--limit") ?? 50);
+  const data = await gqlRequest(
+    `query CliRunnerList($workspaceId: String, $first: Int!) {
+      actionRunners(condition: { workspaceId: $workspaceId }, first: $first) {
+        nodes { id identity { name } workspaceId isCloud isArchived createdAt }
+      }
+    }`,
+    { workspaceId: workspaceId ?? null, first: limit }
+  );
+  printResult(
+    data.actionRunners.nodes.map((r) => ({
+      id: r.id,
+      name: r.identity?.name ?? null,
+      workspaceId: r.workspaceId,
+      kind: r.isCloud ? "cloud" : "self-hosted",
+      archived: r.isArchived,
+      createdAt: r.createdAt
+    })),
+    resolveFormat(flagValue(args, "-o", "--output"))
+  );
+};
+var USAGE = "Usage: overai runner create <workspaceId> [--name <name>]\n       overai runner token <runnerId> [--note <note>]\n       overai runner run <runnerId> [--interpreter shell|powershell] --code '<code>'\n       overai runner upload <runnerId> --path '<path>'\n       overai runner list [workspaceId] [--limit <n>]\n";
+var runRunner = async (args) => {
+  const [sub, id, ...rest] = args;
+  if (sub === "create" && id != null) return runCreate(id, rest);
+  if (sub === "token" && id != null) return runToken(id, rest);
+  if (sub === "run" && id != null) return runRun(id, rest);
+  if (sub === "upload" && id != null) return runUpload(id, rest);
+  if (sub === "list") return runList([id, ...rest].filter((a) => a != null));
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+};
+
 // src/commands/sql.ts
 import { createInterface } from "readline";
 var runQuery = async (organizationId, tableSpaceId, query, params) => {
@@ -2032,7 +2449,11 @@ var runSql = async (args) => {
     return void 0;
   })();
   if (query == null) return runRepl(organizationId, tableSpaceId, format);
-  const result = await runQuery(organizationId, tableSpaceId, query);
+  const result = await runQuery(
+    organizationId,
+    tableSpaceId,
+    await readValue(query, "the query") ?? query
+  );
   printResult(result.rows, format);
   if (process.stderr.isTTY) {
     process.stderr.write(`${summarize(result)}
@@ -2040,101 +2461,6 @@ var runSql = async (args) => {
   }
 };
 
-// src/commands/update.ts
-import { spawnSync } from "child_process";
-import { existsSync as existsSync3, readFileSync as readFileSync4 } from "fs";
-import { fileURLToPath } from "url";
-var PACKAGE_NAME = "@overaihq/cli";
-var packageRootUrl = () => {
-  for (const up of ["..", "../..", "../../.."]) {
-    if (existsSync3(new URL(`${up}/package.json`, import.meta.url))) {
-      return new URL(`${up}/`, import.meta.url);
-    }
-  }
-  throw new Error("package.json not found relative to the CLI bundle");
-};
-var cliVersion = () => {
-  const pkg = JSON.parse(
-    readFileSync4(new URL("package.json", packageRootUrl()), "utf8")
-  );
-  return pkg.version;
-};
-var detectInstaller = () => {
-  const path = fileURLToPath(import.meta.url);
-  if (path.includes("_npx") || path.includes("dlx-")) return "ephemeral";
-  if (path.includes(".pnpm") || /[\\/]pnpm[\\/]/.test(path)) return "pnpm";
-  if (path.includes(".bun")) return "bun";
-  return "npm";
-};
-var runUpdate = async () => {
-  const current = cliVersion();
-  if (existsSync3(new URL("src", packageRootUrl()))) {
-    process.stdout.write(
-      "Development build \u2014 rebuild from the repo instead of updating from npm.\n"
-    );
-    return;
-  }
-  const res = await fetch(
-    `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}/latest`,
-    // Bound the lookup so a slow/unreachable registry can't hang the command.
-    { signal: AbortSignal.timeout(1e4) }
-  );
-  if (!res.ok) {
-    throw new Error(`npm registry lookup failed (HTTP ${String(res.status)})`);
-  }
-  const body = await res.json();
-  const latest = typeof body.version === "string" ? body.version : null;
-  if (latest == null) {
-    throw new Error("npm registry returned an unexpected response");
-  }
-  if (latest === current) {
-    process.stdout.write(`overai ${current} is up to date.
-`);
-    return;
-  }
-  const cur = current.split(".").map(Number);
-  const lat = latest.split(".").map(Number);
-  const cmp = cur.map((n, i) => n - (lat[i] ?? 0)).find((d) => d !== 0) ?? 0;
-  if (cmp > 0) {
-    process.stdout.write(
-      `overai ${current} is ahead of latest (${latest}) \u2014 likely a @next install; nothing to do.
-`
-    );
-    return;
-  }
-  const installer = detectInstaller();
-  if (installer === "ephemeral") {
-    process.stdout.write(
-      `Running from an npx/dlx cache (current ${current}, latest ${latest}) \u2014 invoke as \`npx ${PACKAGE_NAME}@latest\` to always get the newest release.
-`
-    );
-    return;
-  }
-  const spec = `${PACKAGE_NAME}@${latest}`;
-  const argsByInstaller = {
-    npm: ["npm", "install", "-g", spec],
-    pnpm: ["pnpm", "add", "-g", spec],
-    bun: ["bun", "add", "-g", spec]
-  };
-  const [cmd, ...args] = argsByInstaller[installer];
-  process.stdout.write(
-    `Updating overai ${current} \u2192 ${latest} via ${installer}\u2026
-`
-  );
-  const result = spawnSync(cmd, args, {
-    stdio: "inherit",
-    // npm/pnpm are .cmd shims on Windows; a shell is required to resolve them.
-    shell: process.platform === "win32"
-  });
-  if (result.status !== 0) {
-    throw new Error(
-      `${[cmd, ...args].join(" ")} failed (exit ${String(result.status ?? "?")})`
-    );
-  }
-  process.stdout.write(`Updated to ${latest}.
-`);
-};
-
 // src/commands/versions.ts
 import { spawnSync as spawnSync2 } from "child_process";
 import { mkdirSync as mkdirSync4, mkdtempSync, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "fs";
@@ -2270,19 +2596,59 @@ var runDiff = async (args) => {
   }
 };
 
+// src/commands/workspace.ts
+var listWorkspaces = async (args) => {
+  const archived = args.includes("--archived");
+  const limit = Number(flagValue(args, "--limit") ?? 200);
+  const data = await gqlRequest(
+    `query CliWorkspaceList($first: Int!, $includeArchived: IncludeArchivedOption!) {
+      workspaces(first: $first, includeArchived: $includeArchived) {
+        nodes { id name isArchived workspaceWorkspace { parentWorkspaceId } }
+      }
+      myWorkspaceRoles { nodes { workspaceId role } }
+    }`,
+    { first: limit, includeArchived: archived ? "YES" : "NO" }
+  );
+  const roles = new Map(
+    data.myWorkspaceRoles.nodes.map((r) => [r.workspaceId, r.role])
+  );
+  printResult(
+    data.workspaces.nodes.map((w) => ({
+      id: w.id,
+      name: w.name,
+      role: roles.get(w.id) ?? "",
+      ...archived ? { archived: w.isArchived } : {},
+      parentId: w.workspaceWorkspace?.parentWorkspaceId ?? ""
+    })).sort((a, b) => a.name.localeCompare(b.name)),
+    resolveFormat(flagValue(args, "-o", "--output"))
+  );
+};
+var USAGE2 = "Usage: overai workspace list [--archived] [--limit <n>]\n";
+var runWorkspace = async (args) => {
+  if (args[0] !== "list") {
+    process.stderr.write(USAGE2);
+    process.exitCode = 1;
+    return;
+  }
+  await listWorkspaces(args.slice(1));
+};
+
 // src/index.ts
 var HELP = `overai \u2014 OverAI command-line interface
 
 Usage:
-  overai signin                        Sign in via your browser
+  overai signin                        Sign in via your browser; choose your
+                                       organization there to complete SSO
   overai signout                       Sign out and revoke this session
   overai whoami                        Show the current identity and org
   overai org list                      List your organizations
   overai org switch <orgId>            Switch the active org
-  overai graphql -q '<query>' | -f <file> [--v1]
+  overai workspace list [--archived]   List workspaces you can see in this org
+  overai graphql -q '<query>' | -f <file> [--variables <json>] [--v1]
                                        Run a GraphQL operation (/v2; --v1 = legacy Hasura)
-  overai fn <functionId> [--input k=v ... | -]
-                                       Invoke a function
+  overai fn <functionId> [--method GET] [--path /features/123] [--input k=v ... | -]
+                                       Invoke a function; --path reaches a
+                                       sub-path of one that routes internally
   overai fn logs <functionId> [--limit N] [--execution <id>]
                                        Execution history / logs
   overai sql <tableSpaceId> ["<SQL>"]  Run SQL against a tablespace; no query
@@ -2306,6 +2672,8 @@ Workspace sync (edit resources as local files):
                                        Live-preview a web page from local files
   overai review                        Validation + best-practice review packet
   overai best-practices [topic]        Print bundled guides
+  overai report bug|feature "<details>"
+                                       Send product feedback (use - for stdin)
   overai update                        Update the global install to the latest release
   overai version                       Print the CLI version
 
@@ -2314,8 +2682,21 @@ Automations:
   overai automation state <runId> [--node <variableId>]
   overai automation run <automationId> [--input k=v ... | -]
 
+Self-hosted runners (enabling remote access stays on-device \u2014 not a CLI action):
+  overai runner create <workspaceId> [--name <name>]
+  overai runner token <runnerId> [--note <note>]   Mint a pairing secret (shown once)
+  overai runner run <runnerId> [--interpreter shell|powershell] --code '<code>'
+  overai runner upload <runnerId> --path '<path>'
+  overai runner list [workspaceId]
+
+Arguments that carry a document \u2014 the graphql query and --variables, the sql
+statement, runner --code \u2014 also take @<file> to read it from disk, or @- to read
+it from stdin. Prefer that for anything long or quote-heavy: an inline value is
+parsed by your shell first, and one apostrophe inside it silently truncates the
+rest. Write @@ to send a literal value that starts with "@".
+
 Output: table on a TTY, JSON when piped; -o json|table|csv to force.
-Aliases: login = signin, logout = signout.
+Aliases: login = signin, logout = signout, ws = workspace.
 Env: OVERAI_API_URL, OVERAI_APP_URL override the target deployment.
 `;
 process.stdout.on("error", (error) => {
@@ -2348,6 +2729,10 @@ var run = async () => {
       process.stderr.write("Usage: overai org list | org switch <orgId>\n");
       process.exitCode = 1;
       return;
+    case "workspace":
+    case "ws":
+      await runWorkspace(rest);
+      return;
     case "graphql":
       await runGraphql(rest);
       return;
@@ -2393,9 +2778,15 @@ var run = async () => {
     case "best-practices":
       runBestPractices(rest);
       return;
+    case "report":
+      await runReport(rest);
+      return;
     case "automation":
       await runAutomation(rest);
       return;
+    case "runner":
+      await runRunner(rest);
+      return;
     case "update":
     case "upgrade":
       await runUpdate();