@overaihq/cli 0.4.0 → 0.6.0

package/README.md

@@ -24,7 +24,7 @@ overai clone <workspaceId>      # materialize resources and WORKSPACE.md
 # ...edit files...
 overai status                   # local edits + remote drift
 overai diff                     # what changed
-overai review                   # validation + best-practice review packet
+overai review                   # local checks + authenticated TypeScript lint + guides
 overai report bug "<details>"    # report broken or unexplained behavior
 overai report feature "<details>" # request a missing platform capability
 overai push -m "why"            # create new versions (not live yet)

package/dist/index.js

@@ -26690,26 +26690,6 @@ var readValue = async (value, label) => {
   }
 };
 
-// src/gql.ts
-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("; "));
-  }
-  if (!res.ok || body?.data == null) {
-    throw new Error(`graphql failed (${String(res.status)})`);
-  }
-  return body.data;
-};
-
 // src/output.ts
 var resolveFormat = (explicit) => {
   if (explicit === "json" || explicit === "csv" || explicit === "table") {
@@ -26764,6 +26744,43 @@ var printResult = (data, format2) => {
 `);
 };
 
+// src/commands/agent.ts
+var runAgent = async (args) => {
+  const [operation, id] = args;
+  if (operation !== "generate" || id == null) throw new Error("Usage: overai agent generate <id> --message <text|@file|@->");
+  const message = await readValue(flagValue(args, "--message", "-m"), "--message");
+  if (message == null) throw new Error("Agent generate requires --message.");
+  const { organizationId } = await getAccessToken();
+  const response = await v2Fetch(`/v2/agents/${organizationId}/${id}/generate/text`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ message })
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok) throw new Error(body == null ? `Agent generate failed (${String(response.status)}).` : JSON.stringify(body));
+  printResult(body, resolveFormat(flagValue(args, "-o", "--output")));
+};
+
+// src/gql.ts
+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("; "));
+  }
+  if (!res.ok || body?.data == null) {
+    throw new Error(`graphql failed (${String(res.status)})`);
+  }
+  return body.data;
+};
+
 // src/commands/automation.ts
 var runRuns = async (automationId, args) => {
   const limit2 = Number(flagValue(args, "--limit") ?? 20);
@@ -26854,23 +26871,6 @@ var runAutomation = async (args) => {
   process.exitCode = 1;
 };
 
-// src/commands/agent.ts
-var runAgent = async (args) => {
-  const [operation, id] = args;
-  if (operation !== "generate" || id == null) throw new Error("Usage: overai agent generate <id> --message <text|@file|@->");
-  const message = await readValue(flagValue(args, "--message", "-m"), "--message");
-  if (message == null) throw new Error("Agent generate requires --message.");
-  const { organizationId } = await getAccessToken();
-  const response = await v2Fetch(`/v2/agents/${organizationId}/${id}/generate/text`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ message })
-  });
-  const body = await response.json().catch(() => null);
-  if (!response.ok) throw new Error(body == null ? `Agent generate failed (${String(response.status)}).` : JSON.stringify(body));
-  printResult(body, resolveFormat(flagValue(args, "-o", "--output")));
-};
-
 // src/workspace/manifest.ts
 import { existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
 import { dirname, join as join2, resolve } from "path";
@@ -33428,6 +33428,92 @@ import {
   writeFileSync as writeFileSync4
 } from "fs";
 import { join as join4, resolve as resolve3 } from "path";
+
+// ../common/src/lint/schema.ts
+var lintSurfaceSchema = external_exports.enum([
+  "webPage",
+  // React/TSX page — gets rules-of-hooks
+  "automationCode",
+  // automation TS-code node (globals STATE/env/OUTPUT)
+  "function"
+  // Web-standard-runtime TS module (export default handler)
+]);
+var lintDiagnosticSchema = external_exports.object({
+  line: external_exports.number(),
+  column: external_exports.number(),
+  /** ESLint rule id, or null for a fatal parse error. */
+  ruleId: external_exports.string().nullable(),
+  message: external_exports.string(),
+  severity: external_exports.enum(["error", "warning"])
+});
+var lintRequestSchema = external_exports.object({
+  code: external_exports.string(),
+  surface: lintSurfaceSchema,
+  // The workspace the code is being authored in. Used to (a) authorize the
+  // caller as a builder in that workspace and (b) resolve its real resources so
+  // env id references are type-narrowed. A user token carries no workspace, so
+  // this rides the request body.
+  workspaceId: external_exports.string(),
+  // The linted function's own declared output schema (function surface only),
+  // enabling the handler return-vs-schema compliance check. Client-supplied
+  // because the draft being linted lives in the editor, unsaved; advisory, so
+  // nothing is trusted from it. '' or omitted skips the check.
+  functionOutputSchema: external_exports.string().optional()
+});
+var lintResponseSchema = external_exports.object({
+  diagnostics: external_exports.array(lintDiagnosticSchema)
+});
+var functionDeployImpactRequestSchema = external_exports.object({
+  // Authorizes the builder-in-workspace gate, like the lint request.
+  workspaceId: external_exports.string(),
+  functionId: external_exports.string(),
+  /** The saved version being deployed; its schema pair is read server-side. */
+  versionNumber: external_exports.number().int()
+});
+var functionDeployDependentSchema = external_exports.object({
+  kind: external_exports.enum(["webPage", "printablePage", "function", "automation"]),
+  id: external_exports.string(),
+  name: external_exports.string()
+});
+var functionDeployImpactResponseSchema = external_exports.object({
+  /** True only when the contract is incompatible AND deployed callers exist. */
+  breaking: external_exports.boolean(),
+  /** Human-readable type mismatches, one per broken direction. */
+  reasons: external_exports.array(external_exports.string()),
+  /** Deployed resources whose code references this function's handle. */
+  dependents: external_exports.array(functionDeployDependentSchema)
+});
+
+// src/deployImpact.ts
+var NOT_BREAKING = {
+  breaking: false,
+  reasons: [],
+  dependents: []
+};
+var fetchFunctionDeployImpact = async (workspaceId, functionId, versionNumber) => {
+  try {
+    const res = await v2Fetch("/v2/architect/functionDeployImpact", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ workspaceId, functionId, versionNumber })
+    });
+    if (!res.ok) return NOT_BREAKING;
+    const parsed = functionDeployImpactResponseSchema.safeParse(
+      await res.json()
+    );
+    return parsed.success ? parsed.data : NOT_BREAKING;
+  } catch {
+    return NOT_BREAKING;
+  }
+};
+var breakingDeployMessage = (name2, versionNumber, impact) => [
+  `SKIP ${name2}: v${String(versionNumber)}'s declared input/output schemas are incompatible with deployed callers:`,
+  ...impact.dependents.map((d) => `  ${d.name} (${d.kind}, ${d.id})`),
+  ...impact.reasons.map((r) => `  ${r}`),
+  `Fix the callers (or the schemas) first, or pass --allow-breaking to deploy anyway.`
+].join("\n");
+
+// src/commands/sync.ts
 var toManifestResource = (type, remote) => ({
   type,
   name: remote.name,
@@ -33665,6 +33751,7 @@ var runPush = async (args) => {
   const message = flagValue(args, "-m", "--message") ?? "Pushed via overai CLI";
   const deploy = args.includes("--deploy");
   const force = args.includes("--force");
+  const allowBreaking = args.includes("--allow-breaking");
   const pathFilter = positionals(args)[0];
   let pushed = 0;
   for (const [id, resource] of resourcesMatching(manifest, pathFilter)) {
@@ -33709,6 +33796,20 @@ var runPush = async (args) => {
 `
     );
     if (deploy) {
+      if (resource.type === "function" && !allowBreaking) {
+        const impact = await fetchFunctionDeployImpact(
+          manifest.workspaceId,
+          id,
+          versionNumber
+        );
+        if (impact.breaking) {
+          process.stdout.write(
+            `${breakingDeployMessage(resource.name, versionNumber, impact)}
+`
+          );
+          continue;
+        }
+      }
       await adapter.deploy(id, versionNumber);
       resource.deployedVersion = versionNumber;
       writeManifest(root, manifest);
@@ -33726,6 +33827,7 @@ var runPush = async (args) => {
 var runDeploy = async (args) => {
   const { root, manifest } = openClone();
   const pathFilter = positionals(args)[0];
+  const allowBreaking = args.includes("--allow-breaking");
   const pending = resourcesMatching(manifest, pathFilter).filter(
     ([, r]) => r.deployedVersion !== r.baseVersion
   );
@@ -33749,6 +33851,20 @@ Pass a filter to deploy one, or --all to deploy everything.`
       );
       continue;
     }
+    if (resource.type === "function" && !allowBreaking) {
+      const impact = await fetchFunctionDeployImpact(
+        manifest.workspaceId,
+        id,
+        resource.baseVersion
+      );
+      if (impact.breaking) {
+        process.stdout.write(
+          `${breakingDeployMessage(resource.name, resource.baseVersion, impact)}
+`
+        );
+        continue;
+      }
+    }
     await adapterFor(resource.type).deploy(id, resource.baseVersion);
     resource.deployedVersion = resource.baseVersion;
     writeManifest(root, manifest);
@@ -34146,30 +34262,6 @@ var runOpen = async (args) => {
   openBrowser(url);
 };
 
-// src/commands/printablePage.ts
-var runPrintablePage = async (args) => {
-  const [operation, id] = args;
-  if (operation !== "render" || id == null) throw new Error("Usage: overai printable-page render <id> [--search-params <json|@file>] [--timeout <ms>]");
-  const data = await gqlRequest(
-    `query CliPrintablePageWorkspace($id: String!) { printablePage(id: $id) { workspaceId } }`,
-    { id }
-  );
-  if (data.printablePage == null) throw new Error(`Printable page ${id} not found.`);
-  const searchParams = await readValue(flagValue(args, "--search-params"), "--search-params") ?? "{}";
-  JSON.parse(searchParams);
-  const { organizationId } = await getAccessToken();
-  const timeoutMs = Number(flagValue(args, "--timeout") ?? 6e4);
-  const response = await v2Fetch(`/v2/actions/${organizationId}/${data.printablePage.workspaceId}/run`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ actionId: "PRINTABLE_PAGE_TO_PDF", inputs: { printablePageId: id, searchParams, includeDiagnostics: true } }),
-    signal: AbortSignal.timeout(timeoutMs)
-  });
-  const body = await response.json().catch(() => null);
-  if (!response.ok) throw new Error(JSON.stringify(body));
-  printResult(body, resolveFormat(flagValue(args, "-o", "--output")));
-};
-
 // src/commands/org.ts
 var USER_ORGS_QUERY = `
   query UserOrganizations($identityId: String!) {
@@ -34235,6 +34327,30 @@ ${result.redirectUrl}
 `);
 };
 
+// src/commands/printablePage.ts
+var runPrintablePage = async (args) => {
+  const [operation, id] = args;
+  if (operation !== "render" || id == null) throw new Error("Usage: overai printable-page render <id> [--search-params <json|@file>] [--timeout <ms>]");
+  const data = await gqlRequest(
+    `query CliPrintablePageWorkspace($id: String!) { printablePage(id: $id) { workspaceId } }`,
+    { id }
+  );
+  if (data.printablePage == null) throw new Error(`Printable page ${id} not found.`);
+  const searchParams = await readValue(flagValue(args, "--search-params"), "--search-params") ?? "{}";
+  JSON.parse(searchParams);
+  const { organizationId } = await getAccessToken();
+  const timeoutMs = Number(flagValue(args, "--timeout") ?? 6e4);
+  const response = await v2Fetch(`/v2/actions/${organizationId}/${data.printablePage.workspaceId}/run`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ actionId: "PRINTABLE_PAGE_TO_PDF", inputs: { printablePageId: id, searchParams, includeDiagnostics: true } }),
+    signal: AbortSignal.timeout(timeoutMs)
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok) throw new Error(JSON.stringify(body));
+  printResult(body, resolveFormat(flagValue(args, "-o", "--output")));
+};
+
 // src/commands/update.ts
 import { spawnSync } from "child_process";
 import { existsSync as existsSync4, readFileSync as readFileSync8 } from "fs";
@@ -34629,6 +34745,10 @@ executionMemory MB).
   responds with \u2014 no request envelope) so env.FNxxx.call() is typed for
   callers: the deployed version's schemas become FunctionHandle<In, Out> in
   the editor and lint. Leave it "" when the response shape is unspecified.
+- That contract is checked at deploy time: \`overai deploy\` and
+  \`overai push --deploy\` skip a function whose declared schema change is
+  incompatible with deployed callers, printing the affected resources. Fix the
+  callers (or the schemas) first, or pass \`--allow-breaking\` to deploy anyway.
 - 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,
@@ -34644,7 +34764,8 @@ var workflow = `# CLI editing workflow
    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.
+4. \`overai review\` \u2014 local checks, authenticated TypeScript lint against the
+   live workspace, and these guides; fix findings first.
 5. \`overai push -m "why"\` \u2014 creates NEW versions (not live). Fast-forward
    only: if the resource moved remotely, pull, re-apply, retry. Write commit
    messages like PR titles \u2014 they're the version history.
@@ -34682,11 +34803,11 @@ var runBestPractices = (args) => {
   );
 };
 var runReview = async () => {
-  const root = findWorkspaceRoot();
-  const manifest = readManifest(root);
+  const { root, manifest } = openClone();
   const findings2 = [];
   const touchedTypes = /* @__PURE__ */ new Set();
   const changed = [];
+  const lintTargets = [];
   for (const [id, resource] of Object.entries(manifest.resources)) {
     const { state, changedFiles } = localState(root, resource);
     if (state !== "modified") continue;
@@ -34733,6 +34854,37 @@ var runReview = async () => {
         }
       }
     }
+    if (resource.type === "webPage") {
+      changedFiles.filter((relPath) => relPath.endsWith(".tsx")).forEach((relPath) => {
+        const code = readWorkingFile(root, relPath);
+        if (code != null) {
+          lintTargets.push({ label: relPath, code, surface: "webPage" });
+        }
+      });
+    }
+    if (resource.type === "function") {
+      const codeFile = resource.files.find((path) => path.endsWith(".ts"));
+      const metaFile = resource.files.find(
+        (path) => path.endsWith(".meta.json")
+      );
+      const code = codeFile == null ? null : readWorkingFile(root, codeFile);
+      const meta = metaFile == null ? null : readWorkingFile(root, metaFile);
+      if (codeFile != null && code != null) {
+        const parsedMeta = (() => {
+          try {
+            return JSON.parse(meta ?? "null");
+          } catch {
+            return null;
+          }
+        })();
+        lintTargets.push({
+          label: codeFile,
+          code,
+          surface: "function",
+          functionOutputSchema: parsedMeta != null && typeof parsedMeta === "object" && "outputSchema" in parsedMeta && typeof parsedMeta.outputSchema === "string" ? parsedMeta.outputSchema : void 0
+        });
+      }
+    }
     if (resource.type === "automation") {
       const docFile = resource.files.find((f) => f.endsWith(".json"));
       const raw2 = docFile == null ? null : readWorkingFile(root, docFile);
@@ -34744,6 +34896,25 @@ var runReview = async () => {
               (f) => `${docFile} elements.${f}`
             )
           );
+          const nodes = Array.isArray(doc.elements) ? [...doc.elements] : [];
+          for (const node of nodes) {
+            if (node == null || typeof node !== "object") continue;
+            const nodeRecord = node;
+            if (Array.isArray(nodeRecord.elements)) {
+              nodes.push(...nodeRecord.elements);
+            }
+            const inputs = nodeRecord.inputs;
+            if (nodeRecord.nodeTypeId !== "TYPESCRIPT_CODE" || inputs == null || typeof inputs !== "object") {
+              continue;
+            }
+            const code = inputs.code;
+            if (typeof code !== "string") continue;
+            lintTargets.push({
+              label: `${docFile} ${typeof nodeRecord.variableId === "string" ? nodeRecord.variableId : "unknown node"}`,
+              code,
+              surface: "automationCode"
+            });
+          }
         } catch {
         }
       }
@@ -34753,6 +34924,47 @@ var runReview = async () => {
     process.stdout.write("Nothing modified locally \u2014 nothing to review.\n");
     return;
   }
+  for (const target of lintTargets) {
+    try {
+      const response = await v2Fetch("/v2/architect/lint", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          code: target.code,
+          surface: target.surface,
+          workspaceId: manifest.workspaceId,
+          functionOutputSchema: target.functionOutputSchema
+        })
+      });
+      const responseText = await response.text();
+      if (!response.ok) {
+        throw new Error(
+          `${target.label}: HTTP ${String(response.status)}${responseText ? ` \u2014 ${responseText}` : ""}`
+        );
+      }
+      const parsed = lintResponseSchema.safeParse(
+        (() => {
+          try {
+            return JSON.parse(responseText);
+          } catch {
+            return null;
+          }
+        })()
+      );
+      if (!parsed.success) {
+        throw new Error(`${target.label}: invalid response from lint service`);
+      }
+      findings2.push(
+        ...parsed.data.diagnostics.map(
+          (diagnostic) => `${target.label}:${String(diagnostic.line)}:${String(diagnostic.column)}: ${diagnostic.severity}: ${diagnostic.message}${diagnostic.ruleId == null ? "" : ` (${diagnostic.ruleId})`}`
+        )
+      );
+    } catch (error) {
+      findings2.push(
+        `${target.label}: remote lint could not run \u2014 ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
   const guides = ["workflow", ...touchedTypes].map((t) => t === "webPage" || t === "printablePage" ? "pages" : t).map((t) => t === "automation" ? "automations" : t).map((t) => t === "function" ? "functions" : t);
   const guideDocs = [...new Set(guides)].map((t) => BEST_PRACTICES[t]).filter((d) => d != null);
   process.stdout.write(
@@ -35410,14 +35622,17 @@ Workspace sync (edit resources as local files):
   overai outline <filter>[@ref]        Top-level declarations with their line
                                        ranges and doc comments
   overai pull                          Fast-forward clean resources to remote
-  overai push [filter] -m <msg> [--deploy] [--force]
+  overai push [filter] -m <msg> [--deploy] [--force] [--allow-breaking]
                                        Create new versions from local edits
-  overai deploy [filter | --all]       Point deployed versions at pushed ones
+  overai deploy [filter | --all]       Point deployed versions at pushed ones;
+                                       a function whose schema change breaks
+                                       deployed callers is skipped unless
+                                       --allow-breaking
   overai restore <filter | --all>      Discard local edits (back to base)
   overai open [filter | id]            Open a resource (or the workspace) in the webapp
   overai dev <filter> [--port N] [--open]
                                        Live-preview a web page from local files
-  overai review                        Validation + best-practice review packet
+  overai review                        Local checks + authenticated TypeScript lint + guides
   overai best-practices [topic]        Print bundled guides
   overai report bug|feature "<details>"
                                        Send product feedback (use - for stdin)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overaihq/cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Create, edit, deploy, and run OverAI workspace resources from the command line",
   "type": "module",
   "homepage": "https://overai.com",
@@ -30,7 +30,7 @@
     "lint": "echo 'Run lint from the root of the repo'",
     "ts-check": "tsc --noEmit",
     "build": "tsup",
-    "build:watch": "tsc -w",
+    "build:watch": "tsup --watch",
     "start": "node dist/index.js",
     "test": "vitest",
     "test:localhost": "vitest --run --config vitest.localhost.config.js"