railcode 0.1.9 → 0.1.11

package/README.md

@@ -20,9 +20,10 @@ on your `PATH`.
 railcode login [--api-url <url>]   Sign in and mint a personal API token
 railcode init <app> [--template static|react]
 railcode deploy                    Build (if configured) and deploy the app here
+railcode db <list|query> ...       List data connectors / run read-only SQL
 ```
 
-- **`login`** prompts for the server URL (default `http://api.127.0.0.1.nip.io`),
+- **`login`** prompts for the server URL (default `https://api.railcode.app`),
   email, and password. It exchanges credentials for a short-lived JWT, mints a
   personal API token, resolves your organization, and saves everything to
   `~/.railcode/config.json` (dir `0700`, file `0600`). The JWT is used once and
@@ -34,6 +35,17 @@ railcode deploy                    Build (if configured) and deploy the app here
 - **`deploy`** reads `railcode.json` (`{ app, build?, dist? }`), runs the resolved
   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.
+  `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
+  table + row count; `--engine <postgres|mysql>` is inferred from the connector
+  list when omitted, `--params '<json-array>'` binds `$1, $2, …` placeholders
+  (SQL is never interpolated), `--file <path>` reads SQL from a file, and
+  `--json` prints the raw `{ columns, rows, rowcount, truncated }` envelope.
 
 ## Configuration
 

package/dist/connectors.js

@@ -0,0 +1,146 @@
+// Pure helpers behind `railcode connector list` / `railcode connector fetch`.
+// Kept free of any I/O or process state so they can be unit-tested directly (see
+// test/connectors.test.mjs); the command layer in index.ts does the HTTP, file
+// reads, and printing. Mirrors db.ts.
+import { formatTable } from "./db.js";
+export class ConnectorError extends Error {
+}
+// What goes in the optional `docs` column: which kinds of documentation a connector
+// exposes (pull the content with `railcode connector docs <name>`).
+function docsCell(c) {
+    const parts = [];
+    if (c.has_docs)
+        parts.push("api");
+    if (c.has_openapi)
+        parts.push("openapi");
+    return parts.join(", ");
+}
+// Render the connector list as a table. The `description` and `docs` columns are each
+// only added when at least one connector actually has that, so the common (bare) case
+// stays narrow.
+export function connectorTable(connectors) {
+    const hasDescription = connectors.some((c) => (c.description ?? "").length > 0);
+    const hasDocs = connectors.some((c) => c.has_docs || c.has_openapi);
+    const columns = ["name", "auth_type", "allowed_methods"];
+    if (hasDescription)
+        columns.push("description");
+    if (hasDocs)
+        columns.push("docs");
+    const rows = connectors.map((c) => {
+        const row = [c.name, c.auth_type, (c.allowed_methods ?? []).join(", ")];
+        if (hasDescription)
+            row.push(c.description ?? "");
+        if (hasDocs)
+            row.push(docsCell(c));
+        return row;
+    });
+    return formatTable(columns, rows);
+}
+// What `--openapi` emits for one connector: the inline spec verbatim if present,
+// otherwise the spec URL, otherwise null (no spec configured).
+export function connectorOpenapiOutput(docs) {
+    if (docs.openapi_spec_inline)
+        return docs.openapi_spec_inline;
+    if (docs.openapi_spec_link)
+        return docs.openapi_spec_link;
+    return null;
+}
+// Human render of a connector's docs bundle: identity line, then usage instructions,
+// API docs (link or inline), and the OpenAPI spec (link or inline) when present.
+export function renderConnectorDocs(docs) {
+    const methods = (docs.allowed_methods ?? []).join(", ") || "(all)";
+    const sections = [`${docs.name} (${docs.auth_type}) — methods: ${methods}`];
+    if (docs.description)
+        sections.push(docs.description);
+    const hasAny = docs.usage_instructions ||
+        docs.api_docs_link ||
+        docs.api_docs_inline ||
+        docs.openapi_spec_link ||
+        docs.openapi_spec_inline;
+    if (!hasAny) {
+        sections.push(`No documentation is configured for connector "${docs.name}".`);
+        return sections.join("\n\n");
+    }
+    if (docs.usage_instructions)
+        sections.push(`Usage instructions:\n${docs.usage_instructions}`);
+    if (docs.api_docs_link)
+        sections.push(`API docs: ${docs.api_docs_link}`);
+    else if (docs.api_docs_inline)
+        sections.push(`API docs (inline):\n${docs.api_docs_inline}`);
+    if (docs.openapi_spec_link)
+        sections.push(`OpenAPI spec: ${docs.openapi_spec_link}`);
+    else if (docs.openapi_spec_inline)
+        sections.push(`OpenAPI spec (inline):\n${docs.openapi_spec_inline}`);
+    return sections.join("\n\n");
+}
+// `--connector <name>` is required for `fetch`. Reject a missing value or a bare
+// flag with a usage message.
+export function parseConnectorOption(raw) {
+    if (raw === undefined) {
+        throw new ConnectorError("--connector <name> is required for `railcode connector fetch`.");
+    }
+    if (typeof raw !== "string")
+        throw new ConnectorError("--connector requires a value.");
+    const name = raw.trim();
+    if (!name)
+        throw new ConnectorError("--connector requires a non-empty connector name.");
+    return name;
+}
+// `--method <verb>` defaults to GET and is normalized to upper-case. The server
+// is the authority on which methods a connector allows (405 otherwise) — here we
+// only reject a bare flag or a non-token value.
+export function parseMethodOption(raw) {
+    if (raw === undefined)
+        return "GET";
+    if (typeof raw !== "string")
+        throw new ConnectorError("--method requires a value (e.g. GET, POST).");
+    const method = raw.trim().toUpperCase();
+    if (!/^[A-Z]+$/.test(method)) {
+        throw new ConnectorError(`Invalid --method "${raw}". Use an HTTP verb like GET or POST.`);
+    }
+    return method;
+}
+// `--body <string>` and `--file <path>` are mutually exclusive; both are optional
+// (a GET needs no body).
+export function pickConnectorBody(bodyOption, fileOption) {
+    if (bodyOption === true)
+        throw new ConnectorError("--body requires a value.");
+    if (fileOption === true)
+        throw new ConnectorError("--file requires a path.");
+    const hasBody = typeof bodyOption === "string";
+    const hasFile = typeof fileOption === "string" && fileOption.length > 0;
+    if (hasBody && hasFile) {
+        throw new ConnectorError("Pass a request body either with --body or --file, not both.");
+    }
+    if (hasFile)
+        return { kind: "file", path: fileOption };
+    if (hasBody)
+        return { kind: "inline", body: bodyOption };
+    return { kind: "none" };
+}
+// Assemble + validate the proxy request payload. `path` comes from the positional
+// argument; `body` is the already-resolved string (or null for no body).
+export function buildConnectorRequest(input) {
+    if (!input.path) {
+        throw new ConnectorError('Provide a path: railcode connector fetch --connector <name> "/v1/charges".');
+    }
+    return {
+        connector: input.connector,
+        method: input.method,
+        path: input.path,
+        body: input.body,
+    };
+}
+// A non-2xx upstream status is the connector's own response (not a CLI failure),
+// but `ok: false` still sets a non-zero exit code.
+export function proxyExitCode(envelope) {
+    return envelope.ok ? 0 : 1;
+}
+// Human output for one proxied call: the upstream status line then the body.
+export function renderProxyResponse(envelope) {
+    const lines = [`HTTP ${envelope.status}`, "", envelope.body];
+    if (envelope.truncated) {
+        lines.push("", "Note: the response body was truncated by the server.");
+    }
+    return lines.join("\n");
+}

package/dist/db.js

@@ -0,0 +1,78 @@
+// Pure helpers behind `railcode db list` / `railcode db query`. Kept free of any
+// I/O or process state so they can be unit-tested directly (see test/db.test.mjs);
+// the command layer in index.ts does the HTTP, file reads, and printing.
+export class DbError extends Error {
+}
+export const DB_ENGINES = ["postgres", "mysql"];
+// `--params '<json-array>'` → the positional $1,$2,… values. Empty when omitted.
+export function parseSqlParams(raw) {
+    if (raw === undefined)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new DbError(`--params must be a JSON array (invalid JSON): ${raw}`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new DbError(`--params must be a JSON array, e.g. --params '[1, "abc"]'.`);
+    }
+    return parsed;
+}
+// Validate the optional --engine override. undefined means "infer from --connection".
+export function parseEngine(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== "string")
+        throw new DbError("--engine requires a value (postgres or mysql).");
+    if (DB_ENGINES.includes(raw))
+        return raw;
+    throw new DbError(`Unknown --engine "${raw}". Use one of: ${DB_ENGINES.join(", ")}.`);
+}
+// SQL comes from the positional arg OR --file, never both, never neither.
+export function pickSqlSource(positional, fileOption) {
+    const hasPositional = typeof positional === "string" && positional.length > 0;
+    if (fileOption === true)
+        throw new DbError("--file requires a path.");
+    const hasFile = typeof fileOption === "string" && fileOption.length > 0;
+    if (hasPositional && hasFile) {
+        throw new DbError("Pass SQL either as the argument or with --file, not both.");
+    }
+    if (!hasPositional && !hasFile) {
+        throw new DbError('Provide SQL: railcode db query "select 1"  (or --file query.sql).');
+    }
+    return hasFile
+        ? { kind: "file", path: fileOption }
+        : { kind: "inline", sql: positional };
+}
+// When --engine is omitted, infer it from the connector list by matching the
+// chosen --connection name. Errors with the configured names if there's no match.
+export function inferEngine(connections, connectionName) {
+    const match = connections.find((c) => c.name === connectionName);
+    if (!match) {
+        const names = connections.map((c) => c.name);
+        const configured = names.length > 0 ? names.join(", ") : "(none configured)";
+        throw new DbError(`No connection named "${connectionName}". Configured: ${configured}. ` +
+            "Pass --engine to skip the lookup.");
+    }
+    return parseEngine(match.engine) ?? "postgres";
+}
+function renderCell(value) {
+    if (value === null || value === undefined)
+        return "NULL";
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}
+// A minimal left-aligned, two-space-gutter table. Trailing padding is trimmed so
+// the output diffs cleanly. Works with zero rows (header + rule only).
+export function formatTable(columns, rows) {
+    const cells = rows.map((row) => columns.map((_, i) => renderCell(row[i])));
+    const widths = columns.map((col, i) => Math.max(col.length, ...cells.map((row) => row[i].length), 0));
+    const line = (values) => values.map((value, i) => value.padEnd(widths[i])).join("  ").replace(/\s+$/, "");
+    const out = [line(columns), line(widths.map((width) => "-".repeat(width)))];
+    for (const row of cells)
+        out.push(line(row));
+    return out.join("\n");
+}

package/dist/index.js

@@ -11,6 +11,8 @@ import process from "node:process";
 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 { ConnectorError, buildConnectorRequest, connectorOpenapiOutput, connectorTable, parseConnectorOption, parseMethodOption, pickConnectorBody, proxyExitCode, renderConnectorDocs, renderProxyResponse, } from "./connectors.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -18,7 +20,7 @@ const RAILCODE_HOME = process.env.RAILCODE_HOME || join(homedir(), ".railcode");
 const CONFIG_PATH = join(RAILCODE_HOME, "config.json");
 const CLI_PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const VERSION = readCliPackageVersion();
-const DEFAULT_API_URL = "http://api.127.0.0.1.nip.io";
+const DEFAULT_API_URL = "https://api.railcode.app";
 const MANIFEST_NAME = "railcode.json";
 const CLI_AUTH_CALLBACK_PATH = "/railcode-cli/callback";
 const CLI_AUTH_TIMEOUT_MS = 5 * 60 * 1000;
@@ -32,6 +34,8 @@ Usage:
   railcode dev [--port <n>] [--reset]  Run the app locally against an emulated /_api
   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 connector <list|docs|fetch> ...  List connectors / show API docs / proxy a call
   railcode --version
   railcode --help
 
@@ -69,6 +73,13 @@ async function main() {
         case "design-system":
             await commandDesignSystem(args);
             return;
+        case "db":
+            await commandDb(args);
+            return;
+        case "connector":
+        case "connectors":
+            await commandConnector(args);
+            return;
         default:
             throw new CliError(`Unknown command: ${args.command}\n\n${HELP}`, 2);
     }
@@ -342,6 +353,17 @@ 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.
@@ -767,6 +789,342 @@ async function commandDesignSystem(args) {
     // Raw markdown straight to stdout so it pipes/feeds cleanly into an agent.
     process.stdout.write(markdown.endsWith("\n") || markdown === "" ? markdown : `${markdown}\n`);
 }
+// ---------------------------------------------------------------------------
+// db — list data connectors + run read-only SQL (`railcode db list|query`)
+//
+// Data connectors are org-wide; the app is only the scoping/attribution context
+// for the SQL route, so we reuse resolveOrCreateApp (same as deploy/dev) and the
+// bearer, app-scoped endpoints `railcode dev` already forwards to.
+// ---------------------------------------------------------------------------
+const DB_HELP = `railcode db — data connectors
+
+Usage:
+  railcode db list                       List this org's data connectors
+  railcode db query "<sql>"              Run read-only SQL against a connector
+
+Aliases: list = ls, connections; query = sql.
+
+List options:
+  --json                                 Print the raw connector array
+
+Query options:
+  --connection <name>                    Connector to query (default: default)
+  --engine <postgres|mysql>              Engine override (inferred from --connection otherwise)
+  --params '<json-array>'                Values for $1, $2, … placeholders
+  --file <path>                          Read SQL from a file instead of the argument
+  --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).
+`;
+async function commandDb(args) {
+    try {
+        const sub = args.rest[0] ?? "";
+        switch (sub) {
+            case "list":
+            case "ls":
+            case "connections":
+                await commandDbList(args);
+                return;
+            case "query":
+            case "sql":
+                await commandDbQuery(args);
+                return;
+            case "":
+            case "help":
+                console.log(DB_HELP);
+                return;
+            default:
+                throw new CliError(`Unknown db command: ${sub}\n\n${DB_HELP}`, 2);
+        }
+    }
+    catch (error) {
+        // Validation helpers throw DbError; surface them as usage errors (exit 2).
+        if (error instanceof DbError)
+            throw new CliError(error.message, 2);
+        throw error;
+    }
+}
+async function commandDbList(args) {
+    assertKnownDbOptions(args, ["json", "apiUrl"]);
+    if (args.rest.length > 1) {
+        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);
+    if (args.options.json) {
+        console.log(JSON.stringify(connections, null, 2));
+        return;
+    }
+    if (connections.length === 0) {
+        console.log("No data connectors configured for this organization.");
+        return;
+    }
+    console.log(formatTable(["name", "engine"], connections.map((connection) => [connection.name, connection.engine])));
+}
+async function commandDbQuery(args) {
+    assertKnownDbOptions(args, ["connection", "engine", "params", "file", "json", "apiUrl"]);
+    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 params = parseSqlParams(optionString(args, "params"));
+    const engineOption = parseEngine(args.options.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 });
+    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.");
+    }
+}
+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`);
+    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`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    return (await readJsonOrThrow(resp, "Run query"));
+}
+function readSqlFile(path) {
+    const resolved = resolve(process.cwd(), path);
+    if (!existsSync(resolved))
+        throw new CliError(`SQL file not found: ${path}`, 2);
+    const sql = readFileSync(resolved, "utf8").trim();
+    if (!sql)
+        throw new CliError(`SQL file is empty: ${path}`, 2);
+    return sql;
+}
+function optionString(args, key) {
+    const value = args.options[key];
+    if (value === true)
+        throw new CliError(`--${camelToKebab(key)} requires a value.`, 2);
+    return typeof value === "string" ? value : undefined;
+}
+function assertKnownDbOptions(args, allowed) {
+    for (const key of Object.keys(args.options)) {
+        if (!allowed.includes(key)) {
+            throw new CliError(`Unknown option --${camelToKebab(key)} for \`railcode db\`.\n\n${DB_HELP}`, 2);
+        }
+    }
+}
+function camelToKebab(value) {
+    return value.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+}
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
+const CONNECTOR_HELP = `railcode connector — service connectors
+
+Usage:
+  railcode connector list                       List this org's service connectors
+  railcode connector docs <name> [opts]         Show how to call a connector's API
+  railcode connector fetch <path> --connector <name> [opts]
+                                                 Proxy one HTTP call through a connector
+
+Aliases: connector = connectors; list = ls, connectors; docs = doc; fetch = request.
+
+List options:
+  --json                                 Print the raw connector array
+
+Docs options:
+  --json                                 Print the raw docs object
+  --openapi                              Print only the OpenAPI spec (inline text, else its URL)
+
+Fetch options:
+  --connector <name>                     Connector to call (required)
+  --method <verb>                        HTTP method (default GET; must be allowed by the connector)
+  --body <string>                        Request body (mutually exclusive with --file)
+  --file <path>                          Read the request body from a file
+  --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).
+`;
+async function commandConnector(args) {
+    try {
+        const sub = args.rest[0] ?? "";
+        switch (sub) {
+            case "list":
+            case "ls":
+            case "connectors":
+                await commandConnectorList(args);
+                return;
+            case "docs":
+            case "doc":
+                await commandConnectorDocs(args);
+                return;
+            case "fetch":
+            case "request":
+                await commandConnectorFetch(args);
+                return;
+            case "":
+            case "help":
+                console.log(CONNECTOR_HELP);
+                return;
+            default:
+                throw new CliError(`Unknown connector command: ${sub}\n\n${CONNECTOR_HELP}`, 2);
+        }
+    }
+    catch (error) {
+        // Validation helpers throw ConnectorError; surface them as usage errors (exit 2).
+        if (error instanceof ConnectorError)
+            throw new CliError(error.message, 2);
+        throw error;
+    }
+}
+async function commandConnectorList(args) {
+    assertKnownConnectorOptions(args, ["json", "apiUrl"]);
+    if (args.rest.length > 1) {
+        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);
+    if (args.options.json) {
+        console.log(JSON.stringify(connectors, null, 2));
+        return;
+    }
+    if (connectors.length === 0) {
+        console.log("No service connectors configured for this organization.");
+        return;
+    }
+    console.log(connectorTable(connectors));
+}
+async function commandConnectorFetch(args) {
+    assertKnownConnectorOptions(args, ["connector", "method", "body", "file", "json", "apiUrl"]);
+    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 body = bodySource.kind === "file"
+        ? readConnectorBodyFile(bodySource.path)
+        : bodySource.kind === "inline"
+            ? bodySource.body
+            : 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);
+    if (args.options.json) {
+        console.log(JSON.stringify(envelope, null, 2));
+    }
+    else {
+        console.log(renderProxyResponse(envelope));
+    }
+    // A non-2xx upstream status is the connector's response, not a CLI error — print
+    // it, but exit non-zero so scripts can tell success from failure.
+    process.exitCode = proxyExitCode(envelope);
+}
+async function commandConnectorDocs(args) {
+    assertKnownConnectorOptions(args, ["json", "openapi", "apiUrl"]);
+    const name = args.rest[1];
+    if (!name) {
+        throw new CliError("Usage: railcode connector docs <name>. Run `railcode connector list` to see names.", 2);
+    }
+    if (args.rest.length > 2) {
+        throw new CliError(`railcode connector docs takes a single connector name (got "${args.rest[2]}").`, 2);
+    }
+    if (args.options.json && args.options.openapi) {
+        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);
+    if (args.options.json) {
+        console.log(JSON.stringify(docs, null, 2));
+        return;
+    }
+    if (args.options.openapi) {
+        const spec = connectorOpenapiOutput(docs);
+        if (spec === null) {
+            throw new CliError(`Connector "${name}" has no OpenAPI spec.`, 1);
+        }
+        console.log(spec);
+        return;
+    }
+    console.log(renderConnectorDocs(docs));
+}
+async function fetchServiceConnectors(config, appUuid) {
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/apps/${appUuid}/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)}`);
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    if (resp.status === 404) {
+        throw new CliError(`Connector "${name}" not found (or not enabled) in your org. Run \`railcode connector list\`.`, 1);
+    }
+    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`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    if (resp.status === 405) {
+        // The connector config didn't allow this method (server-side check).
+        throw new CliError(`Connector "${body.connector}" rejected ${body.method}: ${await errorDetail(resp)}`, 1);
+    }
+    // The proxy envelope is the 200 body; any other non-2xx is a real CLI failure
+    // (bad connector name, auth, misconfig) — surface the server detail.
+    return (await readJsonOrThrow(resp, "Connector request"));
+}
+function readConnectorBodyFile(path) {
+    const resolved = resolve(process.cwd(), path);
+    if (!existsSync(resolved))
+        throw new CliError(`Request body file not found: ${path}`, 2);
+    return readFileSync(resolved, "utf8");
+}
+function assertKnownConnectorOptions(args, allowed) {
+    for (const key of Object.keys(args.options)) {
+        if (!allowed.includes(key)) {
+            throw new CliError(`Unknown option --${camelToKebab(key)} for \`railcode connector\`.\n\n${CONNECTOR_HELP}`, 2);
+        }
+    }
+}
 async function readJsonOrThrow(response, action) {
     if (response.status === 401) {
         throw new CliError(`${action} was rejected (401). Run \`railcode login\` again.`, 1);
@@ -1332,7 +1690,9 @@ async function handleLocalApi(ctx, req, res, url) {
     if (path === "/connections" ||
         path === "/sql" ||
         path === "/llm/generate" ||
-        path === "/llm/stream") {
+        path === "/llm/stream" ||
+        path === "/service-connectors" ||
+        path === "/service-connectors/request") {
         await forwardCompute(ctx, req, res, path, url);
         return;
     }
@@ -1524,8 +1884,9 @@ function devCreds(config) {
 }
 // Resolve the server-side app for proxying — lazily and memoized, so we don't
 // pollute org state on a typo'd `railcode dev`. The app is **created only on the
-// first llm/sql call** (allowCreate); a `GET /connections` (which can fire on page
-// load) resolves an existing app but never creates one.
+// first actual call** (llm/sql/service-connectors request, allowCreate); a
+// load-time list (`GET /connections`, `/service-connectors`) resolves an existing
+// app but never creates one.
 function resolveDevAppUuid(ctx, creds, allowCreate) {
     const base = `${creds.apiUrl}/api/organizations/${creds.orgUuid}/apps`;
     const authed = { Authorization: `Bearer ${creds.token}` };
@@ -1557,7 +1918,7 @@ function resolveDevAppUuid(ctx, creds, allowCreate) {
                     if (!created.ok)
                         return null;
                     const app = (await created.json());
-                    console.log(`  created app "${ctx.app}" on ${creds.apiUrl} (first llm/sql call)`);
+                    console.log(`  created app "${ctx.app}" on ${creds.apiUrl} (first llm/sql/connector call)`);
                     ctx.appUuidPromise = Promise.resolve(app.uuid); // later resolves skip the list
                     return app.uuid;
                 }
@@ -1571,8 +1932,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).
-    // connections degrades to [] so dataConnectors() at load doesn't break.
-    const degradeOk = path === "/connections";
+    // 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";
     const creds = devCreds(ctx.config);
     if (!creds) {
         if (degradeOk)
@@ -1582,7 +1945,8 @@ async function forwardCompute(ctx, req, res, path, url) {
             message: "Run `railcode login` to use LLM and connectors in dev.",
         });
     }
-    // Only llm/sql may create the app server-side; a load-time GET /connections won't.
+    // 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.
     const appUuid = await resolveDevAppUuid(ctx, creds, !degradeOk);
     if (!appUuid) {
         if (degradeOk)

package/package.json

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