@gonvex/cli 0.4.0 → 0.5.0

package/README.md

@@ -2,9 +2,9 @@
 
 The Gonvex CLI for app-local development with the Gonvex runtime.
 
-Gonvex gives you a Convex-style workflow with TypeScript backend functions,
-generated TypeScript bindings, React hooks, realtime subscriptions,
-and a local runtime backed by Postgres.
+Gonvex provides TypeScript backend functions, generated TypeScript bindings,
+React hooks, transaction-ordered realtime delivery, and a persistent Local
+Replica backed by Postgres.
 
 ## Install
 
@@ -88,6 +88,21 @@ Run a one-shot sync for CI or Docker builds:
 npx gonvex dev --once
 ```
 
+Emit or verify the deterministic interactive-function catalog used by agent
+orchestration:
+
+```bash
+npx gonvex functions emit --format ndjson --output agent-api.ndjson
+npx gonvex functions emit --format typescript --output agent-api.d.ts
+npx gonvex functions check
+```
+
+Both files are derived from the compiled module artifact, sorted by public
+function path, and contain the artifact hash. The NDJSON format stores one
+complete function contract per line. The TypeScript declaration renders the
+same schemas, classification, offline policy, optimistic transaction,
+description, tags, and confirmation requirement as literal types.
+
 By default, `gonvex dev` streams only runtime warnings and errors to the
 terminal. To tail every Query, Reducer, and Action:
 

package/dist/function-catalog.d.ts

@@ -0,0 +1,19 @@
+import type { JsonValue, ModuleArtifact, ModuleFunction, ModuleSchema } from "./manifest-types.js";
+export type FunctionCatalogFormat = "ndjson" | "typescript";
+export type FunctionCatalogEntry = {
+    path: string;
+    kind: ModuleFunction["kind"];
+    artifactHash: string;
+    args: ModuleSchema;
+    result: ModuleSchema;
+    classification: "interactive";
+    interactive: true;
+    offline: JsonValue | null;
+    optimistic: JsonValue | null;
+    description: string;
+    tags: string[];
+    confirmation: "none" | "required" | "destructive";
+};
+export declare function functionCatalogEntries(artifact: ModuleArtifact): FunctionCatalogEntry[];
+export declare function renderFunctionCatalog(artifact: ModuleArtifact, format: FunctionCatalogFormat): string;
+export declare function renderPortableSchema(schema: ModuleSchema, indent?: number): string;

package/dist/function-catalog.js

@@ -0,0 +1,107 @@
+const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+export function functionCatalogEntries(artifact) {
+    return Object.entries(artifact.functions)
+        .filter(([, definition]) => !definition.internal && (definition.classification === "interactive" || (definition.classification === undefined
+        && (definition.interactive === true || (definition.interactive === undefined && definition.kind !== "action")))))
+        .sort(([left], [right]) => compareText(left, right))
+        .map(([path, definition]) => ({
+        path,
+        kind: definition.kind,
+        artifactHash: artifact.hash,
+        args: definition.args ?? { kind: "object", fields: {} },
+        result: definition.result ?? { kind: "any" },
+        classification: "interactive",
+        interactive: true,
+        offline: definition.offline ?? null,
+        optimistic: definition.optimistic ?? null,
+        description: definition.description ?? "",
+        tags: [...(definition.agent?.tags ?? [])].sort(),
+        confirmation: definition.agent?.confirmation ?? "none",
+    }));
+}
+export function renderFunctionCatalog(artifact, format) {
+    const entries = functionCatalogEntries(artifact);
+    if (format === "ndjson") {
+        return entries.map((entry) => JSON.stringify(entry)).join("\n") + (entries.length > 0 ? "\n" : "");
+    }
+    const lines = [
+        "// Generated by Gonvex. Do not edit.",
+        `export declare const artifactHash: ${JSON.stringify(artifact.hash)};`,
+        "export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };",
+        "export type Id<Entity extends string> = string & { readonly __gonvexEntity: Entity };",
+        "export interface GonvexAgentAPI {",
+    ];
+    for (const entry of entries) {
+        lines.push(`  ${JSON.stringify(entry.path)}: {`);
+        lines.push(`    kind: ${JSON.stringify(entry.kind)};`);
+        lines.push('    classification: "interactive";');
+        lines.push("    interactive: true;");
+        lines.push(`    args: ${renderPortableSchema(entry.args, 4)};`);
+        lines.push(`    result: ${renderPortableSchema(entry.result, 4)};`);
+        lines.push(`    offline: ${renderJsonLiteralType(entry.offline)};`);
+        lines.push(`    optimistic: ${renderJsonLiteralType(entry.optimistic)};`);
+        lines.push(`    description: ${JSON.stringify(entry.description)};`);
+        lines.push(`    tags: readonly [${entry.tags.map((tag) => JSON.stringify(tag)).join(", ")}];`);
+        lines.push(`    confirmation: ${JSON.stringify(entry.confirmation)};`);
+        lines.push("  };");
+    }
+    lines.push("}", "");
+    return lines.join("\n");
+}
+export function renderPortableSchema(schema, indent = 0) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        return "unknown";
+    const value = schema;
+    switch (value.kind) {
+        case "string": return "string";
+        case "number": return "number";
+        case "boolean": return "boolean";
+        case "null": return "null";
+        case "any": return "JsonValue";
+        case "id": return `Id<${JSON.stringify(String(value.entity ?? ""))}>`;
+        case "literal": return renderLiteral(value.value);
+        case "array": return `Array<${renderPortableSchema(value.items, indent)}>`;
+        case "record": return `Record<string, ${renderPortableSchema(value.values, indent)}>`;
+        case "optional": return `${renderPortableSchema(value.value, indent)} | undefined`;
+        case "object": {
+            const fields = value.fields && typeof value.fields === "object" && !Array.isArray(value.fields)
+                ? Object.entries(value.fields).sort(([left], [right]) => compareText(left, right))
+                : [];
+            if (fields.length === 0)
+                return "Record<string, never>";
+            const padding = " ".repeat(indent);
+            const childPadding = " ".repeat(indent + 2);
+            const rendered = fields.map(([name, field]) => {
+                const optional = field?.kind === "optional";
+                const actual = field.kind === "optional" ? field.value : field;
+                return `${childPadding}${renderProperty(name)}${optional ? "?" : ""}: ${renderPortableSchema(actual, indent + 2)};`;
+            });
+            if (value.allowUnknown === true)
+                rendered.push(`${childPadding}[key: string]: JsonValue;`);
+            return `{\n${rendered.join("\n")}\n${padding}}`;
+        }
+        default: return "unknown";
+    }
+}
+function renderProperty(value) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(value) ? value : JSON.stringify(value);
+}
+function renderLiteral(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+        return JSON.stringify(value);
+    }
+    return "JsonValue";
+}
+function renderJsonLiteralType(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `readonly [${value.map(renderJsonLiteralType).join(", ")}]`;
+    }
+    const fields = Object.entries(value)
+        .sort(([left], [right]) => compareText(left, right))
+        .map(([name, field]) => `readonly ${renderProperty(name)}: ${renderJsonLiteralType(field)};`);
+    return `{ ${fields.join(" ")} }`;
+}
+//# sourceMappingURL=function-catalog.js.map

package/dist/function-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-catalog.js","sourceRoot":"","sources":["../src/function-catalog.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 export type * from "./manifest-types.js";
 export type { ProjectLanguage } from "./module-artifact.js";
+export * from "./function-catalog.js";
 export declare function main(argv?: string[]): Promise<void>;
 export declare function runCreate(argv: string[]): Promise<void>;
 export declare function runAuth(argv: string[]): Promise<void>;

package/dist/index.js

@@ -9,6 +9,8 @@ import { dirname, join, relative, resolve } from "node:path";
 import { Writable } from "node:stream";
 import { fileURLToPath } from "node:url";
 import { buildModuleArtifact, detectProjectLanguage, moduleManifestFunctions, moduleSourceFiles, isModuleSchema, } from "./module-artifact.js";
+import { renderFunctionCatalog } from "./function-catalog.js";
+export * from "./function-catalog.js";
 const defaultRuntimeURL = "http://localhost:8080";
 const runtimeSyncRetryMs = 5000;
 const runtimeStateCheckMs = 2500;
@@ -57,6 +59,10 @@ export async function main(argv = process.argv.slice(2)) {
         await runCodegen(argv.slice(1));
         return;
     }
+    if (command === "functions") {
+        await runFunctions(argv.slice(1));
+        return;
+    }
     if (command === "init") {
         await runInit(argv.slice(1));
         return;
@@ -96,6 +102,42 @@ export async function main(argv = process.argv.slice(2)) {
     printHelp();
     throw new Error(`unknown command ${command}`);
 }
+async function runFunctions(argv) {
+    const action = argv[0];
+    if (!action || !["emit", "check"].includes(action)) {
+        throw new Error("usage: gonvex functions <emit|check> [--format ndjson|typescript] [--output FILE] [--project PATH]");
+    }
+    const root = resolve(valueFor(argv, "--project") ?? ".");
+    const sources = await collectBackendSources(root);
+    const settings = await loadSettings(root, {});
+    const manifest = await buildManifest(root, sources, settings.projectID);
+    const targets = action === "check"
+        ? [
+            { format: "ndjson", output: resolve(root, "agent-api.ndjson") },
+            { format: "typescript", output: resolve(root, "agent-api.d.ts") },
+        ]
+        : [{
+                format: normalizeCatalogFormat(valueFor(argv, "--format") ?? "ndjson"),
+                output: resolve(root, valueFor(argv, "--output") ?? (valueFor(argv, "--format") === "typescript" ? "agent-api.d.ts" : "agent-api.ndjson")),
+            }];
+    for (const target of targets) {
+        const expected = renderFunctionCatalog(manifest.module, target.format);
+        if (action === "check") {
+            const actual = await readFile(target.output, "utf8").catch(() => "");
+            if (actual !== expected)
+                throw new Error(`${relative(root, target.output)} is stale; run gonvex functions emit --format ${target.format} --output ${relative(root, target.output)}`);
+            continue;
+        }
+        await mkdir(dirname(target.output), { recursive: true });
+        await writeFile(target.output, expected);
+        console.log(`[gonvex] wrote ${relative(root, target.output)} for artifact ${manifest.module.hash}`);
+    }
+}
+function normalizeCatalogFormat(value) {
+    if (value === "ndjson" || value === "typescript")
+        return value;
+    throw new Error("--format must be ndjson or typescript");
+}
 export async function runCreate(argv) {
     const optionNames = ["--template", "--runtime-url", "--runtime", "--database-mode", "--origin", "--callback-path", "--signup-mode", "--owner"];
     const target = positionalArgs(argv, optionNames)[0] ?? "my-gonvex-app";
@@ -1186,7 +1228,7 @@ function renderAPI(manifest) {
     const internalRoot = {};
     const optimisticTransactions = {};
     const functionTypes = [];
-    for (const [path, entry] of Object.entries(manifest.functions).sort(([a], [b]) => a.localeCompare(b))) {
+    for (const [path, entry] of Object.entries(manifest.functions).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
         const parts = path.split(".").filter(Boolean);
         if (parts.length === 0)
             continue;
@@ -1417,7 +1459,7 @@ function renderSchemaObject(scope, tables, depth) {
 function renderObject(value, depth) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return JSON.stringify(value);
-    const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+    const entries = Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
     if (isFunctionRef(value)) {
         const visible = Object.fromEntries(entries.filter(([key]) => !key.startsWith("__")));
         return `${renderObject(visible, depth)} as unknown as FunctionReference<${JSON.stringify(value.kind)}, ${value.__argsType}, ${value.__resultType}>`;
@@ -2177,9 +2219,11 @@ function sleep(ms, signal) {
     });
 }
 function printHelp() {
-    console.log("Usage: gonvex <dev|codegen|init|create|env|auth|login|logout|whoami|project|token> [options]");
+    console.log("Usage: gonvex <dev|codegen|functions|init|create|env|auth|login|logout|whoami|project|token> [options]");
     console.log("  gonvex dev [--project <path>] [--runtime-url <url>] [--project-id <id>] [--key <key>] [--once] [--verbose-logs] [-- <command>]");
     console.log("  gonvex codegen [--project <path>] [--project-id <id>]");
+    console.log("  gonvex functions emit --format ndjson|typescript [--output FILE] [--project <path>]");
+    console.log("  gonvex functions check [--project <path>]");
     console.log("  gonvex init [--template vite-react] [--project <id>] [--runtime <url>]");
     console.log("  gonvex create <app-name> [--runtime-url <url>] [--provision] [--database-mode single|multiTenant] [--google-auth] [--origin <url>]... [--signup-mode personal|inviteOnly] [--owner <email>]");
     console.log("  gonvex env <list|get|set|push|remove> [--project <path>] [--runtime-url <url>] [--project-id <id>] [--key <key>]");