railcode 0.1.10 → 0.1.11

package/README.md

@@ -23,7 +23,7 @@ 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

package/dist/connectors.js

@@ -5,20 +5,74 @@
 import { formatTable } from "./db.js";
 export class ConnectorError extends Error {
 }
-// Render the connector list as a table. The `description` column is only added
-// when at least one connector actually has one, so the common (description-less)
-// case stays narrow.
+// 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 columns = hasDescription
-        ? ["name", "auth_type", "allowed_methods", "description"]
-        : ["name", "auth_type", "allowed_methods"];
+    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 base = [c.name, c.auth_type, (c.allowed_methods ?? []).join(", ")];
-        return hasDescription ? [...base, c.description ?? ""] : base;
+        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) {

package/dist/index.js

@@ -12,7 +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 { ConnectorError, buildConnectorRequest, connectorTable, parseConnectorOption, parseMethodOption, pickConnectorBody, proxyExitCode, renderProxyResponse, } from "./connectors.js";
+import { ConnectorError, buildConnectorRequest, connectorOpenapiOutput, connectorTable, parseConnectorOption, parseMethodOption, pickConnectorBody, proxyExitCode, renderConnectorDocs, renderProxyResponse, } from "./connectors.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -20,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;
@@ -35,7 +35,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 connector <list|fetch> ...  List service connectors / proxy one call
+  railcode connector <list|docs|fetch> ...  List connectors / show API docs / proxy a call
   railcode --version
   railcode --help
 
@@ -951,14 +951,19 @@ 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; fetch = request.
+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)
@@ -979,6 +984,10 @@ async function commandConnector(args) {
             case "connectors":
                 await commandConnectorList(args);
                 return;
+            case "docs":
+            case "doc":
+                await commandConnectorDocs(args);
+                return;
             case "fetch":
             case "request":
                 await commandConnectorFetch(args);
@@ -1043,12 +1052,50 @@ async function commandConnectorFetch(args) {
     // 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",

package/package.json

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