railcode 0.1.12 → 0.1.14

package/README.md

@@ -36,9 +36,9 @@ railcode db <list|query> ...       List data connectors / run read-only SQL
   build command when needed, then uploads the output dir. The app is
   created-or-resolved by slug in your saved org, and the live URL is printed.
 - **`db`** inspects the org's **data connectors** (per-org Postgres) and runs
-  ad-hoc read-only SQL. Run from an app dir for an app you've already deployed;
-  it resolves the existing app by slug (it won't create one) and uses the same
-  bearer, app-scoped routes the `dev` proxy forwards to.
+  ad-hoc read-only SQL. It works straight after `railcode login` — **no app and no
+  `railcode.json` required** — since connectors are org-scoped; it hits the app-less
+  `/api/organizations/{org}/data/*` plane with your login token.
   `railcode db list` (aliases `ls`, `connections`) prints each connector's
   `name` + `engine` (`--json` for the raw array). `railcode db query "<sql>"`
   (alias `sql`) runs SQL against `--connection` (default `default`) and prints a

package/dist/index.js

@@ -12,6 +12,7 @@ import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { KvQueryError, kvCount, kvQuery, } from "./dev/kv-query.js";
 import { DbError, formatTable, inferEngine, parseEngine, parseSqlParams, pickSqlSource, } from "./db.js";
+import { QueryCmdError, paramSignature, parseParamDecls, parseRunParams, pickAuthoringSql, } from "./query.js";
 import { ConnectorError, buildConnectorRequest, connectorOpenapiOutput, connectorTable, parseConnectorOption, parseMethodOption, pickConnectorBody, proxyExitCode, renderConnectorDocs, renderProxyResponse, } from "./connectors.js";
 // ---------------------------------------------------------------------------
 // Constants
@@ -35,6 +36,7 @@ Usage:
   railcode init <app> [--template static|react]
   railcode design-system               Print your org's design-system guidance (markdown)
   railcode db <list|query> ...         List data connectors / run read-only SQL
+  railcode query <list|run|create|update|delete> ...  Saved queries: invoke by name / author (admin)
   railcode connector <list|docs|fetch> ...  List connectors / show API docs / proxy a call
   railcode --version
   railcode --help
@@ -76,6 +78,10 @@ async function main() {
         case "db":
             await commandDb(args);
             return;
+        case "query":
+        case "queries":
+            await commandQuery(args);
+            return;
         case "connector":
         case "connectors":
             await commandConnector(args);
@@ -101,13 +107,13 @@ function parseArgs(argv) {
         const withoutPrefix = item.slice(2);
         const eq = withoutPrefix.indexOf("=");
         if (eq !== -1) {
-            options[toCamel(withoutPrefix.slice(0, eq))] = withoutPrefix.slice(eq + 1);
+            setOption(options, toCamel(withoutPrefix.slice(0, eq)), withoutPrefix.slice(eq + 1));
             continue;
         }
         const key = toCamel(withoutPrefix);
         const next = tail[i + 1];
         if (next && !next.startsWith("--")) {
-            options[key] = next;
+            setOption(options, key, next);
             i += 1;
         }
         else {
@@ -116,6 +122,20 @@ function parseArgs(argv) {
     }
     return { command, rest, options };
 }
+// A string option given twice accumulates into an array (optionString then
+// rejects it with "can only be given once"); a repeated flag just stays true.
+function setOption(options, key, value) {
+    const existing = options[key];
+    if (typeof existing === "string") {
+        options[key] = [existing, value];
+    }
+    else if (Array.isArray(existing)) {
+        existing.push(value);
+    }
+    else {
+        options[key] = value;
+    }
+}
 function toCamel(input) {
     return input.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 }
@@ -174,9 +194,15 @@ async function authorizeCliWithBrowser(apiUrl) {
             redirect_uri: callback.redirectUri,
             state,
         })}`;
-        console.log("Open this link to authorize the Railcode CLI:");
-        console.log(authorizeUrl);
         console.log("");
+        printUrlBox("Railcode login", authorizeUrl);
+        console.log("");
+        if (openBrowser(authorizeUrl)) {
+            console.log("Opening your browser. If it does not open, paste the URL above.");
+        }
+        else {
+            console.log("Paste the URL above into your browser to continue.");
+        }
         console.log("Waiting for browser authorization...");
         const code = await callback.code;
         return await exchangeCliAuthCode(apiUrl, code);
@@ -267,6 +293,25 @@ async function startCliAuthCallback(expectedState) {
         },
     };
 }
+function openBrowser(url) {
+    const opener = process.platform === "darwin"
+        ? { command: "open", args: [url] }
+        : process.platform === "win32"
+            ? { command: "cmd", args: ["/c", "start", "", url] }
+            : { command: "xdg-open", args: [url] };
+    try {
+        const child = spawn(opener.command, opener.args, {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.on("error", () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function sendBrowserCallback(response, status, message) {
     response.writeHead(status, { "Content-Type": "text/html" });
     response.end(`<!doctype html><title>Railcode CLI</title><p>${escapeHtml(message)}</p>`);
@@ -353,17 +398,6 @@ async function resolveOrCreateApp(config, slug) {
     });
     return (await readJsonOrThrow(created, "Create app"));
 }
-// Resolve an existing app by slug WITHOUT creating it — for read-only commands
-// (e.g. `railcode db`) that must not spawn a phantom app as a side effect.
-async function resolveExistingApp(config, slug) {
-    const orgPath = `/api/organizations/${config.orgUuid}/apps`;
-    const list = (await readJsonOrThrow(await authedFetch(config, orgPath), "List apps"));
-    const existing = list.find((app) => app.app_slug === slug);
-    if (!existing) {
-        throw new CliError(`App "${slug}" hasn't been created in your org yet. Run \`railcode deploy\` first.`, 1);
-    }
-    return existing;
-}
 async function postDeploy(config, appUuid, files) {
     // The deploy API is multipart: one part named "files" per file, with the
     // relative path carried as the part filename.
@@ -815,7 +849,7 @@ Query options:
   --json                                 Print the raw { columns, rows, rowcount, truncated } envelope
 
 SQL is sent read-only with bound parameters — values are never interpolated into
-the query. Run from an app directory (a ${MANIFEST_NAME} with an "app" slug).
+the query. Works right after \`railcode login\` — no app or ${MANIFEST_NAME} required.
 `;
 async function commandDb(args) {
     try {
@@ -851,8 +885,7 @@ async function commandDbList(args) {
         throw new CliError(`railcode db list takes no arguments (got "${args.rest[1]}").`, 2);
     }
     const config = requireLogin(args);
-    const app = await resolveExistingApp(config, requireAppSlug());
-    const connections = await fetchDbConnections(config, app.uuid);
+    const connections = await fetchDbConnections(config);
     if (args.options.json) {
         console.log(JSON.stringify(connections, null, 2));
         return;
@@ -868,16 +901,15 @@ async function commandDbQuery(args) {
     if (args.rest.length > 2) {
         throw new CliError('railcode db query takes a single SQL string — quote it: railcode db query "select 1".', 2);
     }
-    const source = pickSqlSource(args.rest[1], args.options.file);
+    const source = pickSqlSource(args.rest[1], singleOption(args, "file"));
     const params = parseSqlParams(optionString(args, "params"));
-    const engineOption = parseEngine(args.options.engine);
+    const engineOption = parseEngine(singleOption(args, "engine"));
     const connection = optionString(args, "connection") ?? "default";
     const query = source.kind === "file" ? readSqlFile(source.path) : source.sql;
     const config = requireLogin(args);
-    const app = await resolveExistingApp(config, requireAppSlug());
     // --engine wins; otherwise look the engine up from the connector list.
-    const engine = engineOption ?? inferEngine(await fetchDbConnections(config, app.uuid), connection);
-    const result = await runDbQuery(config, app.uuid, { engine, connection, query, params });
+    const engine = engineOption ?? inferEngine(await fetchDbConnections(config), connection);
+    const result = await runDbQuery(config, { engine, connection, query, params });
     if (args.options.json) {
         console.log(JSON.stringify(result, null, 2));
         return;
@@ -889,22 +921,14 @@ async function commandDbQuery(args) {
         console.log("Note: results were truncated by the server.");
     }
 }
-function requireAppSlug() {
-    const manifest = readManifest(process.cwd());
-    if (!manifest?.app) {
-        throw new CliError(`No ${MANIFEST_NAME} with an "app" slug here. Run \`railcode init <app>\` first, or add ${MANIFEST_NAME}.`, 2);
-    }
-    assertAppName(manifest.app);
-    return manifest.app;
-}
-async function fetchDbConnections(config, appUuid) {
-    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/apps/${appUuid}/connections`);
+async function fetchDbConnections(config) {
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/data/connections`);
     if (resp.status === 401)
         await reLoginOrThrow();
     return (await readJsonOrThrow(resp, "List connections"));
 }
-async function runDbQuery(config, appUuid, body) {
-    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/apps/${appUuid}/sql`, {
+async function runDbQuery(config, body) {
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/data/sql`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(body),
@@ -926,8 +950,20 @@ function optionString(args, key) {
     const value = args.options[key];
     if (value === true)
         throw new CliError(`--${camelToKebab(key)} requires a value.`, 2);
+    if (Array.isArray(value)) {
+        throw new CliError(`--${camelToKebab(key)} can only be given once.`, 2);
+    }
     return typeof value === "string" ? value : undefined;
 }
+// A single-valued option that may legitimately be a bare flag (the db/connector
+// parsers handle `true` themselves) — only a REPEATED option is rejected here.
+function singleOption(args, key) {
+    const value = args.options[key];
+    if (Array.isArray(value)) {
+        throw new CliError(`--${camelToKebab(key)} can only be given once.`, 2);
+    }
+    return value;
+}
 function assertKnownDbOptions(args, allowed) {
     for (const key of Object.keys(args.options)) {
         if (!allowed.includes(key)) {
@@ -939,13 +975,260 @@ function camelToKebab(value) {
     return value.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
 }
 // ---------------------------------------------------------------------------
+// query — saved queries (`railcode query list|run|create|delete`)
+//
+// list/run hit the org-scoped `/data/queries` plane with the personal token
+// (subject to `saved_query` grants; `_ctx_*` binds resolve to YOU). create/delete
+// hit the admin management API (`/saved-queries`, connection:manage required).
+// ---------------------------------------------------------------------------
+const QUERY_HELP = `railcode query — saved queries
+
+Usage:
+  railcode query list                          List this org's saved queries
+  railcode query run <name> [--params <json>]  Invoke a saved query by name
+  railcode query create --name <n> --connection <c> (--sql <sql> | --sql-file <f>)
+                        [--params <json>] [--description <d>]
+                                               Author a saved query (admin)
+  railcode query update <name> [--sql <sql> | --sql-file <f>] [--params <json>]
+                        [--clear-params] [--connection <c>] [--description <d>]
+                                               Edit a saved query in place (admin;
+                                               omitted fields keep their value)
+  railcode query delete <name>                 Delete a saved query (admin)
+
+Aliases: query = queries; list = ls; run = invoke.
+
+Run options:
+  --params '<json-object>'               Caller params, exactly as the API takes
+                                         them: '{"region":"emea","limit":5}'.
+                                         Params declared with a default may be
+                                         omitted (the server binds the default).
+  --json                                 Print the raw { columns, rows, ... } envelope
+
+Create / update options:
+  --name <name>                          Invoke handle ([a-z0-9_], unique per org)
+  --connection <name>                    Data connection the query runs against
+  --sql <sql>                            The SQL template inline (:param style);
+                                         quote it, or use --sql="..." if it starts
+                                         with a -- comment
+  --sql-file <path>                      File holding the SQL template
+  --params '<json-array>'                Declared params in the API shape:
+                                         '[{"name":"region","type":"string","default":"emea"},
+                                           {"name":"limit","type":"int"}]'
+                                         Types: string, int, float, bool. A "default"
+                                         makes the param optional at invoke time.
+                                         On update the array REPLACES the params
+  --clear-params                         (update only) declare no params
+  --description <text>                   Shown to members next to the name
+
+Editing the SQL or params bumps the query's version; grants naming the query are
+untouched (unlike delete + recreate, which removes them).
+
+Templates may reference :_ctx_user_id, :_ctx_user_email and :_ctx_org — the server
+injects those from whoever invokes (they can never be passed as params), so a
+query like "where rep_email = :_ctx_user_email" is row-scoped per caller.
+`;
+async function commandQuery(args) {
+    try {
+        const sub = args.rest[0] ?? "";
+        switch (sub) {
+            case "list":
+            case "ls":
+                await commandQueryList(args);
+                return;
+            case "run":
+            case "invoke":
+                await commandQueryRun(args);
+                return;
+            case "create":
+                await commandQueryCreate(args);
+                return;
+            case "update":
+                await commandQueryUpdate(args);
+                return;
+            case "delete":
+                await commandQueryDelete(args);
+                return;
+            case "":
+            case "help":
+                console.log(QUERY_HELP);
+                return;
+            default:
+                throw new CliError(`Unknown query command: ${sub}\n\n${QUERY_HELP}`, 2);
+        }
+    }
+    catch (error) {
+        if (error instanceof QueryCmdError)
+            throw new CliError(error.message, 2);
+        throw error;
+    }
+}
+async function commandQueryList(args) {
+    assertKnownQueryOptions(args, ["json", "apiUrl"]);
+    if (args.rest.length > 1) {
+        throw new CliError(`railcode query list takes no arguments (got "${args.rest[1]}").`, 2);
+    }
+    const config = requireLogin(args);
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/data/queries`);
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    const queries = (await readJsonOrThrow(resp, "List saved queries"));
+    if (args.options.json) {
+        console.log(JSON.stringify(queries, null, 2));
+        return;
+    }
+    if (queries.length === 0) {
+        console.log("No saved queries in this organization.");
+        return;
+    }
+    console.log(formatTable(["name", "params", "version", "description"], queries.map((query) => [
+        query.name,
+        paramSignature(query.params),
+        `v${query.version}`,
+        query.description || "-",
+    ])));
+}
+async function commandQueryRun(args) {
+    assertKnownQueryOptions(args, ["params", "json", "apiUrl"]);
+    const name = args.rest[1];
+    if (!name || args.rest.length > 2) {
+        throw new CliError(`Usage: railcode query run <name> [--params '{"k":"v"}']`, 2);
+    }
+    const params = parseRunParams(optionString(args, "params"));
+    const config = requireLogin(args);
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/data/queries/${encodeURIComponent(name)}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ params }),
+    });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    const result = (await readJsonOrThrow(resp, `Run saved query "${name}"`));
+    if (args.options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(formatTable(result.columns, result.rows));
+    console.log("");
+    console.log(`(${result.rowcount} row${result.rowcount === 1 ? "" : "s"})`);
+    if (result.truncated) {
+        console.log("Note: results were truncated by the server.");
+    }
+}
+async function commandQueryCreate(args) {
+    assertKnownQueryOptions(args, [
+        "name",
+        "connection",
+        "sql",
+        "sqlFile",
+        "params",
+        "description",
+        "apiUrl",
+    ]);
+    const name = optionString(args, "name");
+    const connection = optionString(args, "connection");
+    if (!name || !connection) {
+        throw new CliError("railcode query create requires --name and --connection.\n\n" + QUERY_HELP, 2);
+    }
+    // required=true: pickAuthoringSql throws rather than return null here.
+    const source = pickAuthoringSql(optionString(args, "sql"), optionString(args, "sqlFile"), true);
+    const params = parseParamDecls(optionString(args, "params"));
+    const sql = source.kind === "file" ? readSqlFile(source.path) : source.sql;
+    const config = requireLogin(args);
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/saved-queries`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            name,
+            connection,
+            sql,
+            params,
+            description: optionString(args, "description") ?? "",
+        }),
+    });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    const created = (await readJsonOrThrow(resp, `Create saved query "${name}"`));
+    console.log(`Saved query "${created.name}" created (v${created.version}).`);
+    console.log(`Invoke it: railcode query run ${created.name}`);
+}
+async function commandQueryUpdate(args) {
+    assertKnownQueryOptions(args, [
+        "sql",
+        "sqlFile",
+        "params",
+        "clearParams",
+        "connection",
+        "description",
+        "apiUrl",
+    ]);
+    const name = args.rest[1];
+    if (!name || args.rest.length > 2) {
+        throw new CliError("Usage: railcode query update <name> [--sql ... | --sql-file ...]", 2);
+    }
+    const source = pickAuthoringSql(optionString(args, "sql"), optionString(args, "sqlFile"), false);
+    const sql = source ? (source.kind === "file" ? readSqlFile(source.path) : source.sql) : undefined;
+    const paramsJson = optionString(args, "params");
+    const clearParams = args.options.clearParams === true;
+    if (clearParams && paramsJson !== undefined) {
+        throw new CliError("--clear-params cannot be combined with --params.", 2);
+    }
+    const params = clearParams ? [] : paramsJson !== undefined ? parseParamDecls(paramsJson) : undefined;
+    const connection = optionString(args, "connection");
+    const description = optionString(args, "description");
+    // PATCH semantics: only the fields present in the body change; params replace
+    // the whole declared list (the backend re-validates them against the SQL).
+    const body = {};
+    if (connection !== undefined)
+        body.connection = connection;
+    if (sql !== undefined)
+        body.sql = sql;
+    if (params !== undefined)
+        body.params = params;
+    if (description !== undefined)
+        body.description = description;
+    if (Object.keys(body).length === 0) {
+        throw new CliError("Nothing to update. Pass --sql/--sql-file, --params/--clear-params, --connection or --description.", 2);
+    }
+    const config = requireLogin(args);
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/saved-queries/${encodeURIComponent(name)}`, {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    const updated = (await readJsonOrThrow(resp, `Update saved query "${name}"`));
+    console.log(`Saved query "${updated.name}" updated (v${updated.version}).`);
+}
+async function commandQueryDelete(args) {
+    assertKnownQueryOptions(args, ["apiUrl"]);
+    const name = args.rest[1];
+    if (!name || args.rest.length > 2) {
+        throw new CliError("Usage: railcode query delete <name>", 2);
+    }
+    const config = requireLogin(args);
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/saved-queries/${encodeURIComponent(name)}`, { method: "DELETE" });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    if (!resp.ok) {
+        throw new CliError(`Delete saved query "${name}" failed (${resp.status}): ${await errorDetail(resp)}`, 1);
+    }
+    console.log(`Saved query "${name}" deleted (its grants were removed too).`);
+}
+function assertKnownQueryOptions(args, allowed) {
+    for (const key of Object.keys(args.options)) {
+        if (!allowed.includes(key)) {
+            throw new CliError(`Unknown option --${camelToKebab(key)} for \`railcode query\`.\n\n${QUERY_HELP}`, 2);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
 // connector — list service connectors + proxy one call
 // (`railcode connector list|fetch`)
 //
 // Service connectors are org-configured HTTP proxies to downstream SaaS APIs.
-// The app is the scoping/attribution context, so — like `railcode db` — we
-// resolve (never create) the app by slug and use the bearer, app-scoped routes
-// `railcode dev` forwards to.
+// Like `railcode db`, these one-shot commands hit the org-scoped `/data/*` plane
+// with the login bearer token — no app (and no railcode.json) required.
 // ---------------------------------------------------------------------------
 const CONNECTOR_HELP = `railcode connector — service connectors
 
@@ -972,8 +1255,8 @@ Fetch options:
   --json                                 Print the raw { status, ok, headers, body, truncated } envelope
 
 The connector holds the credential; you control only method/path/body. A non-2xx
-upstream status is still printed but exits non-zero. Run from an app directory (a
-${MANIFEST_NAME} with an "app" slug).
+upstream status is still printed but exits non-zero. Works right after
+\`railcode login\` — no app or ${MANIFEST_NAME} required.
 `;
 async function commandConnector(args) {
     try {
@@ -1013,8 +1296,7 @@ async function commandConnectorList(args) {
         throw new CliError(`railcode connector list takes no arguments (got "${args.rest[1]}").`, 2);
     }
     const config = requireLogin(args);
-    const app = await resolveExistingApp(config, requireAppSlug());
-    const connectors = await fetchServiceConnectors(config, app.uuid);
+    const connectors = await fetchServiceConnectors(config);
     if (args.options.json) {
         console.log(JSON.stringify(connectors, null, 2));
         return;
@@ -1030,9 +1312,9 @@ async function commandConnectorFetch(args) {
     if (args.rest.length > 2) {
         throw new CliError('railcode connector fetch takes a single path — quote it: railcode connector fetch "/v1/charges".', 2);
     }
-    const connector = parseConnectorOption(args.options.connector);
-    const method = parseMethodOption(args.options.method);
-    const bodySource = pickConnectorBody(args.options.body, args.options.file);
+    const connector = parseConnectorOption(singleOption(args, "connector"));
+    const method = parseMethodOption(singleOption(args, "method"));
+    const bodySource = pickConnectorBody(singleOption(args, "body"), singleOption(args, "file"));
     const body = bodySource.kind === "file"
         ? readConnectorBodyFile(bodySource.path)
         : bodySource.kind === "inline"
@@ -1040,8 +1322,7 @@ async function commandConnectorFetch(args) {
             : null;
     const payload = buildConnectorRequest({ connector, method, path: args.rest[1] ?? "", body });
     const config = requireLogin(args);
-    const app = await resolveExistingApp(config, requireAppSlug());
-    const envelope = await runConnectorRequest(config, app.uuid, payload);
+    const envelope = await runConnectorRequest(config, payload);
     if (args.options.json) {
         console.log(JSON.stringify(envelope, null, 2));
     }
@@ -1065,8 +1346,7 @@ async function commandConnectorDocs(args) {
         throw new CliError("Pass either --json or --openapi, not both.", 2);
     }
     const config = requireLogin(args);
-    const app = await resolveExistingApp(config, requireAppSlug());
-    const docs = await fetchServiceConnectorDocs(config, app.uuid, name);
+    const docs = await fetchServiceConnectorDocs(config, name);
     if (args.options.json) {
         console.log(JSON.stringify(docs, null, 2));
         return;
@@ -1081,14 +1361,14 @@ async function commandConnectorDocs(args) {
     }
     console.log(renderConnectorDocs(docs));
 }
-async function fetchServiceConnectors(config, appUuid) {
-    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/apps/${appUuid}/service-connectors`);
+async function fetchServiceConnectors(config) {
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/data/service-connectors`);
     if (resp.status === 401)
         await reLoginOrThrow();
     return (await readJsonOrThrow(resp, "List service connectors"));
 }
-async function fetchServiceConnectorDocs(config, appUuid, name) {
-    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/apps/${appUuid}/service-connectors/${encodeURIComponent(name)}`);
+async function fetchServiceConnectorDocs(config, name) {
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/data/service-connectors/${encodeURIComponent(name)}`);
     if (resp.status === 401)
         await reLoginOrThrow();
     if (resp.status === 404) {
@@ -1096,8 +1376,8 @@ async function fetchServiceConnectorDocs(config, appUuid, name) {
     }
     return (await readJsonOrThrow(resp, "Connector docs"));
 }
-async function runConnectorRequest(config, appUuid, body) {
-    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/apps/${appUuid}/service-connectors/request`, {
+async function runConnectorRequest(config, body) {
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/data/service-connectors/request`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(body),
@@ -1849,6 +2129,8 @@ async function handleLocalApi(ctx, req, res, url) {
     }
     // Proxied surfaces → forward to the real instance with the saved token.
     if (path === "/connections" ||
+        path === "/queries" ||
+        path.startsWith("/queries/") ||
         path === "/sql" ||
         path === "/llm/generate" ||
         path === "/llm/stream" ||
@@ -2093,10 +2375,10 @@ function resolveDevAppUuid(ctx, creds, allowCreate) {
 }
 async function forwardCompute(ctx, req, res, path, url) {
     // Never reply 401 to the browser — the SDK reloads the page on 401 (loop).
-    // Load-time list calls degrade to [] so dataConnectors()/serviceConnectors() at
-    // load don't break; the actual call surfaces (/sql, /llm, /service-connectors/request)
-    // return 503 instead.
-    const degradeOk = path === "/connections" || path === "/service-connectors";
+    // Load-time list calls degrade to [] so dataConnectors()/savedQueries()/
+    // serviceConnectors() at load don't break; actual call surfaces
+    // (/queries/{name}, /sql, /llm, /service-connectors/request) return 503 instead.
+    const degradeOk = path === "/connections" || path === "/queries" || path === "/service-connectors";
     const creds = devCreds(ctx.config);
     if (!creds) {
         if (degradeOk)
@@ -2106,8 +2388,8 @@ async function forwardCompute(ctx, req, res, path, url) {
             message: "Run `railcode login` to use LLM and connectors in dev.",
         });
     }
-    // Only the actual call surfaces (llm/sql/service-connectors/request) may create
-    // the app server-side; a load-time list (GET /connections, /service-connectors) won't.
+    // Only the actual call surfaces (saved-query invoke / llm / sql /
+    // service-connectors/request) may create the app server-side; load-time lists won't.
     const appUuid = await resolveDevAppUuid(ctx, creds, !degradeOk);
     if (!appUuid) {
         if (degradeOk)

package/dist/query.js

@@ -0,0 +1,94 @@
+// Pure helpers behind `railcode query list|run|create|delete`. Kept free of any
+// I/O or process state so they can be unit-tested directly (see
+// test/query.test.mjs); the command layer in index.ts does the HTTP and printing.
+export class QueryCmdError extends Error {
+}
+// Matches the backend's declared param types (schemas/saved_query.py).
+export const QUERY_PARAM_TYPES = ["string", "int", "float", "bool"];
+// `query run --params` — the caller params as ONE JSON object. The CLI is
+// mostly driven by agents, and agents speak JSON natively: no name=value
+// mini-grammar, the flag takes exactly what the API takes.
+export function parseRunParams(json) {
+    if (json === undefined)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        throw new QueryCmdError(`--params must be valid JSON. Example: --params '{"region":"emea","limit":5}'`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new QueryCmdError(`--params must be a JSON object, e.g. '{"region":"emea"}'.`);
+    }
+    return parsed;
+}
+// `query create|update --params` — the declared params as a JSON array in the
+// exact API shape: [{"name","type","default"?}]. A "default" makes the param
+// optional at invoke time (the server binds it when a caller omits the param);
+// the backend re-validates it against the declared type at save.
+export function parseParamDecls(json) {
+    if (json === undefined)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        throw new QueryCmdError(`--params must be valid JSON. Example: --params '[{"name":"region","type":"string","default":"emea"}]'`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new QueryCmdError(`--params must be a JSON array of {"name","type","default"?} objects.`);
+    }
+    return parsed.map((item, i) => {
+        if (item === null || typeof item !== "object" || Array.isArray(item)) {
+            throw new QueryCmdError(`--params[${i}] must be an object like {"name":"region","type":"string"}.`);
+        }
+        const { name, type, default: def, ...extra } = item;
+        if (typeof name !== "string" || name === "") {
+            throw new QueryCmdError(`--params[${i}] needs a non-empty string "name".`);
+        }
+        if (typeof type !== "string" || !QUERY_PARAM_TYPES.includes(type)) {
+            throw new QueryCmdError(`--params[${i}] ("${name}") needs "type": one of ${QUERY_PARAM_TYPES.join(", ")}.`);
+        }
+        const extraKeys = Object.keys(extra);
+        if (extraKeys.length > 0) {
+            throw new QueryCmdError(`--params[${i}] ("${name}") has unknown key(s): ${extraKeys.join(", ")}.`);
+        }
+        const decl = { name, type: type };
+        if (def !== undefined) {
+            if (def === null || !["string", "number", "boolean"].includes(typeof def)) {
+                throw new QueryCmdError(`--params[${i}] ("${name}") "default" must be a string, number or boolean — omit it to make the param required.`);
+            }
+            decl.default = def;
+        }
+        return decl;
+    });
+}
+export function pickAuthoringSql(sql, sqlFile, required) {
+    if (sql !== undefined && sqlFile !== undefined) {
+        throw new QueryCmdError("Pass the SQL template with --sql or --sql-file, not both.");
+    }
+    if (sql !== undefined) {
+        const trimmed = sql.trim();
+        if (!trimmed)
+            throw new QueryCmdError("--sql is empty.");
+        return { kind: "inline", sql: trimmed };
+    }
+    if (sqlFile !== undefined) {
+        return { kind: "file", path: sqlFile };
+    }
+    if (required) {
+        throw new QueryCmdError('Provide the SQL template: --sql "select ..." or --sql-file query.sql.');
+    }
+    return null;
+}
+// Render one saved query's signature for the list table, e.g.
+// "region?: string = "emea", limit: int" — `?` marks optional (defaulted) params.
+export function paramSignature(params) {
+    return (params
+        .map((p) => p.default === undefined
+        ? `${p.name}: ${p.type}`
+        : `${p.name}?: ${p.type} = ${JSON.stringify(p.default)}`)
+        .join(", ") || "-");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "railcode",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Developer CLI for the multi-tenant Railcode platform: log in, scaffold, and deploy static apps.",
   "license": "MIT",
   "type": "module",

package/static/sdk.js

@@ -120,10 +120,10 @@
       this.name = "ApiError";
     }
   };
-  function buildUrl(path, query) {
+  function buildUrl(path, query2) {
     const url2 = new URL(BASE + path, location.origin);
-    if (query) {
-      for (const [key, value] of Object.entries(query)) {
+    if (query2) {
+      for (const [key, value] of Object.entries(query2)) {
         if (value !== void 0) url2.searchParams.set(key, String(value));
       }
     }
@@ -148,8 +148,8 @@
     if (resp.status === 204) return void 0;
     return await resp.json();
   }
-  async function getOrNull(path, query) {
-    const resp = await send(buildUrl(path, query), { credentials: "include" });
+  async function getOrNull(path, query2) {
+    const resp = await send(buildUrl(path, query2), { credentials: "include" });
     if (resp.status === 404) return null;
     if (!resp.ok) throw new ApiError(resp.status, await resp.text());
     return await resp.json();
@@ -232,8 +232,8 @@
     rows.truncated = r.truncated;
     return rows;
   };
-  var runSQL = (engine, connection, query, params) => {
-    const trimmed = shorten(query.replace(/\s+/g, " ").trim(), QUERY_LABEL_MAX);
+  var runSQL = (engine, connection, query2, params) => {
+    const trimmed = shorten(query2.replace(/\s+/g, " ").trim(), QUERY_LABEL_MAX);
     const label2 = `${engine ?? "data"}(${q(connection)}).runSQL(${q(trimmed)}${params && params.length ? `, ${shorten(JSON.stringify(params), PARAMS_LABEL_MAX)}` : ""})`;
     return track(
       "sql",
@@ -241,16 +241,16 @@
       () => call("POST", "/sql", {
         // engine is advisory; omit it for the generic data() namespace so the backend
         // dispatches on the connection's stored kind. postgres() pins engine="postgres".
-        body: { ...engine ? { engine } : {}, connection, query, params: params || [] }
+        body: { ...engine ? { engine } : {}, connection, query: query2, params: params || [] }
       }).then(toSqlRows)
     );
   };
   var namespace = (engine) => {
     const handle = (connection) => ({
-      runSQL: (query, params) => runSQL(engine, connection, query, params)
+      runSQL: (query2, params) => runSQL(engine, connection, query2, params)
     });
     const ns = handle;
-    ns.runSQL = (query, params) => runSQL(engine, "default", query, params);
+    ns.runSQL = (query2, params) => runSQL(engine, "default", query2, params);
     return ns;
   };
   var data = namespace();
@@ -499,6 +499,20 @@
   }
   var llm = { generate, stream };
 
+  // ../sdk/src/queries.ts
+  var PARAMS_LABEL_MAX2 = 40;
+  var query = (name, params) => {
+    const label2 = `query(${q(name)}${params && Object.keys(params).length ? `, ${shorten(JSON.stringify(params), PARAMS_LABEL_MAX2)}` : ""})`;
+    return track(
+      "sql",
+      label2,
+      () => call("POST", `/queries/${encPath(name)}`, {
+        body: { params: params || {} }
+      }).then(toSqlRows)
+    );
+  };
+  var savedQueries = () => track("queries", "savedQueries()", () => call("GET", "/queries"));
+
   // ../sdk/src/service-connectors.ts
   var PATH_LABEL_MAX = 60;
   var toResponse = (env) => {
@@ -547,4 +561,6 @@
   target.dataConnectors = dataConnectors;
   target.connector = connector;
   target.serviceConnectors = serviceConnectors;
+  target.query = query;
+  target.savedQueries = savedQueries;
 })();