railcode 0.1.24 → 0.1.25

package/dist/index.js

@@ -47,6 +47,8 @@ Usage:
                                       Service connectors: call them, or manage them (admin)
   railcode connections <list|create|delete> ...  Manage org data connectors (admin)
   railcode llm <providers|models>      List the LLM providers/models apps can call
+  railcode personal-connectors <list|tools|connect|call> ...
+                                      Your own connected accounts (Gmail, ...): discover + test
   railcode manifest <validate|show> ...  Validate ${APP_MANIFEST_NAME} locally / show an app's ratified manifest
   railcode agent <list|show|create|update|delete|run|schedule> ...
                                       Manage org-scoped managed agents
@@ -112,6 +114,11 @@ async function main() {
         case "llm":
             await commandLlm(args);
             return;
+        case "personal-connectors":
+        case "personal-connector":
+        case "pc":
+            await commandPersonalConnectors(args);
+            return;
         case "member":
         case "members":
             await commandMembers(args);
@@ -5103,6 +5110,164 @@ function assertKnownLlmOptions(args, allowed) {
     }
 }
 // ---------------------------------------------------------------------------
+// Personal connectors: your OWN connected accounts (Gmail, Slack, ...).
+//
+// Everything here hits the NON-org-scoped `/api/personal-connections/*` plane —
+// a personal connection belongs to the human, not the org. It's the same
+// resource the console's Connectors tab drives. `call` executes as YOU against
+// YOUR own connection (an identity op, not an app), so it's how you smoke-test a
+// tool from the terminal before wiring it into an app or agent.
+// ---------------------------------------------------------------------------
+const PC_HELP = `railcode personal-connectors — your own connected accounts (Gmail, Slack, ...)
+
+Usage:
+  railcode personal-connectors list            Toolkits this deployment brokers + your status
+  railcode personal-connectors tools <toolkit> The callable tools of a toolkit (and their inputs)
+  railcode personal-connectors connect <toolkit>  Print the OAuth URL to connect it (open in a browser)
+  railcode personal-connectors call <tool> [--args '<json>']  Run one tool on your own account
+
+Aliases: personal-connector, pc
+
+Discovery is what you build against: \`tools <toolkit> --json\` shows each tool's
+input schema, so you know what to put in an app's \`personal_connectors:\` and what
+\`personalConnections.call('<tool>', {...})\` expects.
+
+Options:
+  --json                                 Print raw JSON instead of a table
+  --args '<json>'                        Arguments object for \`call\` (default {})
+`;
+async function commandPersonalConnectors(args) {
+    const sub = args.rest[0] ?? "";
+    switch (sub) {
+        case "list":
+            await commandPcList(args);
+            return;
+        case "tools":
+            await commandPcTools(args);
+            return;
+        case "connect":
+            await commandPcConnect(args);
+            return;
+        case "call":
+            await commandPcCall(args);
+            return;
+        case "":
+        case "help":
+            console.log(PC_HELP);
+            return;
+        default:
+            throw new CliError(`Unknown personal-connectors command: ${sub}\n\n${PC_HELP}`, 2);
+    }
+}
+// A 503 here means the DEPLOYMENT has personal connectors turned off — a state to
+// report plainly, not a failure. Anything else is a real error.
+function pcUnavailable(status) {
+    return status === 503;
+}
+async function commandPcList(args) {
+    rejectUnknownOptions(args, ["json", "apiUrl"], "personal-connectors list", PC_HELP);
+    const config = requireLogin(args);
+    const resp = await authedFetch(config, `/api/personal-connections/toolkits`);
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    if (pcUnavailable(resp.status)) {
+        console.log("Personal connectors are not enabled on this deployment.");
+        return;
+    }
+    const toolkits = (await readJsonOrThrow(resp, "List toolkits"));
+    if (args.options.json) {
+        console.log(JSON.stringify(toolkits, null, 2));
+        return;
+    }
+    if (toolkits.length === 0) {
+        console.log("No connectors are available yet.");
+        return;
+    }
+    console.log(formatTable(["TOOLKIT", "NAME", "STATUS"], toolkits.map((t) => [t.slug, t.name, t.connected ? "connected" : t.status ?? "not connected"])));
+}
+async function commandPcTools(args) {
+    rejectUnknownOptions(args, ["json", "apiUrl"], "personal-connectors tools", PC_HELP);
+    const toolkit = args.rest[1];
+    if (!toolkit)
+        throw new CliError("Usage: railcode personal-connectors tools <toolkit>", 2);
+    const config = requireLogin(args);
+    const resp = await authedFetch(config, `/api/personal-connections/toolkits/${encodeURIComponent(toolkit)}/tools`);
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    if (pcUnavailable(resp.status)) {
+        console.log("Personal connectors are not enabled on this deployment.");
+        return;
+    }
+    const tools = (await readJsonOrThrow(resp, `List ${toolkit} tools`));
+    if (args.options.json) {
+        // --json carries the input_schema, which is what you actually build against.
+        console.log(JSON.stringify(tools, null, 2));
+        return;
+    }
+    if (tools.length === 0) {
+        console.log(`No tools found for "${toolkit}".`);
+        return;
+    }
+    console.log(formatTable(["TOOL", "DESCRIPTION"], tools.map((t) => [t.slug, t.description])));
+    console.log(`\n${tools.length} tool(s). Add \`--json\` to see each tool's input schema.`);
+}
+async function commandPcConnect(args) {
+    rejectUnknownOptions(args, ["json", "apiUrl"], "personal-connectors connect", PC_HELP);
+    const toolkit = args.rest[1];
+    if (!toolkit)
+        throw new CliError("Usage: railcode personal-connectors connect <toolkit>", 2);
+    const config = requireLogin(args);
+    // Connecting is browser-bound OAuth; the CLI can't complete it. It prints the
+    // URL and leaves opening it to you — the same handoff `railcode login` uses.
+    const resp = await authedFetch(config, `/api/personal-connections/${encodeURIComponent(toolkit)}/connect`, { method: "POST" });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    if (pcUnavailable(resp.status)) {
+        console.log("Personal connectors are not enabled on this deployment.");
+        return;
+    }
+    const body = (await readJsonOrThrow(resp, `Connect ${toolkit}`));
+    if (args.options.json) {
+        console.log(JSON.stringify(body, null, 2));
+        return;
+    }
+    console.log(`Open this URL to connect ${toolkit}, then re-run your command:\n\n  ${body.redirect_url}\n`);
+}
+async function commandPcCall(args) {
+    rejectUnknownOptions(args, ["json", "args", "apiUrl"], "personal-connectors call", PC_HELP);
+    const tool = args.rest[1];
+    if (!tool)
+        throw new CliError("Usage: railcode personal-connectors call <tool> [--args '<json>']", 2);
+    let toolArgs = {};
+    if (typeof args.options.args === "string") {
+        try {
+            toolArgs = JSON.parse(args.options.args);
+        }
+        catch {
+            throw new CliError(`--args must be a JSON object (got: ${args.options.args})`, 2);
+        }
+    }
+    const config = requireLogin(args);
+    const resp = await authedFetch(config, `/api/personal-connections/call`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ tool, arguments: toolArgs }),
+    });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    if (pcUnavailable(resp.status)) {
+        console.log("Personal connectors are not enabled on this deployment.");
+        return;
+    }
+    // A 409 means "connect this toolkit first" — surface the server's hint verbatim
+    // rather than a generic failure, since it names the exact command to run.
+    if (resp.status === 409) {
+        throw new CliError(await errorDetail(resp), 1);
+    }
+    const body = await readJsonOrThrow(resp, `Call ${tool}`);
+    console.log(JSON.stringify(body, null, 2));
+}
+// ---------------------------------------------------------------------------
 // Shared admin helpers (members / roles / apps / analytics / logs / connections)
 //
 // All of these hit the org-scoped `/api/organizations/{org}/...` management APIs
@@ -6182,6 +6347,7 @@ async function commandDev(args) {
         fileStores: new Map(),
         port: requestedPort,
         config,
+        personalConnectors: readAppPersonalConnectors(cwd),
     };
     // Asset mode needs its deps before we bind anything; the check is cheap and
     // failing early avoids leaving the proxy port bound on a misconfigured app.
@@ -6682,6 +6848,10 @@ async function handleLocalApi(ctx, req, res, url) {
         await handleFiles(ctx, req, res, path, url);
         return;
     }
+    if (path === "/personal-connections" || path.startsWith("/personal-connections/")) {
+        await handlePersonalConnections(ctx, req, res, path, url);
+        return;
+    }
     // Proxied surfaces → forward to the real instance with the saved token.
     if (path === "/connections" ||
         path === "/queries" ||
@@ -7030,6 +7200,172 @@ export function devUpstreamAuthFallback(status, degradeOk) {
         },
     };
 }
+// ── personal connectors in dev ────────────────────────────────────────────────
+//
+// The SDK's `personalConnections.*` methods hit the app plane in prod, which is
+// bounded by the app's ratified manifest. `railcode dev` has no ratified app, so
+// it reproduces that bound HERE from the local manifest.yaml and forwards the
+// actual work to the USER plane (`/api/personal-connections/*`) as the signed-in
+// developer — the same "run as you, not as a deployed app" model dev uses for
+// SQL and LLM. The result: declared tools run against your real connection,
+// undeclared ones are refused exactly as they will be in prod, so a bad call
+// fails locally instead of only after deploy.
+function readAppPersonalConnectors(cwd) {
+    const path = join(cwd, APP_MANIFEST_NAME);
+    if (!existsSync(path))
+        return [];
+    try {
+        return parseManifestYaml(readFileSync(path, "utf8")).personal_connectors ?? [];
+    }
+    catch {
+        // A malformed manifest is caught (loudly) at deploy; dev must not crash on it.
+        // Treating it as "nothing declared" makes personal-connector calls 403 here,
+        // which is the safe direction.
+        return [];
+    }
+}
+// The toolkit slugs an app declared (any tool scope). Mirrors the server's
+// `manifest.personal_connector_toolkits`.
+function pcDeclaredToolkits(entries) {
+    return new Set(entries.map((e) => e.split(":", 1)[0]));
+}
+// May this app call `tool` of `toolkit`? Mirrors the server's
+// `manifest.personal_connector_allowed`: a bare/`*` entry covers the whole
+// toolkit, else the tool must match exactly.
+function pcAllows(entries, toolkit, tool) {
+    for (const entry of entries) {
+        const idx = entry.indexOf(":");
+        const entryToolkit = idx === -1 ? entry : entry.slice(0, idx);
+        if (entryToolkit !== toolkit)
+            continue;
+        const entryTool = idx === -1 ? "" : entry.slice(idx + 1);
+        if (entryTool === "" || entryTool === "*" || entryTool === tool)
+            return true;
+    }
+    return false;
+}
+// Forward one request to the USER plane and return its parsed body. Kept separate
+// from forwardCompute because these need post-filtering by the local manifest,
+// not a raw pass-through.
+async function pcForward(ctx, method, apiPath, body) {
+    const creds = devCreds(ctx.config);
+    if (!creds) {
+        return {
+            status: 503,
+            body: {
+                error: "not_logged_in",
+                message: "Run `railcode login` to use personal connectors in dev.",
+            },
+        };
+    }
+    const headers = {
+        Authorization: `Bearer ${creds.token}`,
+        "X-Railcode-Source": "local-dev",
+    };
+    if (body !== undefined)
+        headers["Content-Type"] = "application/json";
+    let upstream;
+    try {
+        upstream = await fetch(`${creds.apiUrl}/api${apiPath}`, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+            redirect: "manual",
+        });
+    }
+    catch {
+        return { status: 503, body: { error: "unreachable", message: `Could not reach ${creds.apiUrl}.` } };
+    }
+    const text = await upstream.text();
+    let parsed = null;
+    try {
+        parsed = text ? JSON.parse(text) : null;
+    }
+    catch {
+        parsed = text;
+    }
+    return { status: upstream.status, body: parsed };
+}
+// Which declared toolkit owns `tool` — asked of the user-plane catalog, scanning
+// only the app's declared toolkits (as the server's app-plane resolver does).
+async function pcResolveToolkit(ctx, entries, tool) {
+    for (const toolkit of pcDeclaredToolkits(entries)) {
+        const { status, body } = await pcForward(ctx, "GET", `/personal-connections/toolkits/${encodeURIComponent(toolkit)}/tools`);
+        if (status === 200 && Array.isArray(body) && body.some((t) => t.slug === tool)) {
+            return toolkit;
+        }
+    }
+    return null;
+}
+const PC_NOT_IN_MANIFEST = (label) => ({
+    detail: `personal connector "${label}" was not in the manifest`,
+});
+async function handlePersonalConnections(ctx, req, res, path, url) {
+    const entries = ctx.personalConnectors;
+    const declared = pcDeclaredToolkits(entries);
+    const rest = path.slice("/personal-connections".length); // "", "/gmail/tools", "/call", ...
+    // list() — forward, then filter to the toolkits this app declared (the app
+    // plane never shows an app the user's OTHER connected accounts).
+    if (rest === "" && req.method === "GET") {
+        const { status, body } = await pcForward(ctx, "GET", "/personal-connections");
+        const filtered = Array.isArray(body)
+            ? body.filter((c) => declared.has(c.toolkit))
+            : body;
+        return sendJson(res, status === 200 ? 200 : status, status === 200 ? filtered : body);
+    }
+    // tools(toolkit) — require the toolkit is declared, then filter to the declared
+    // tool subset. Both mirror the app plane.
+    const toolsMatch = rest.match(/^\/([^/]+)\/tools$/);
+    if (toolsMatch && req.method === "GET") {
+        const toolkit = decodeURIComponent(toolsMatch[1]);
+        if (!declared.has(toolkit))
+            return sendJson(res, 403, PC_NOT_IN_MANIFEST(toolkit));
+        const { status, body } = await pcForward(ctx, "GET", `/personal-connections/toolkits/${encodeURIComponent(toolkit)}/tools`);
+        const filtered = status === 200 && Array.isArray(body)
+            ? body.filter((t) => pcAllows(entries, toolkit, t.slug))
+            : body;
+        return sendJson(res, status, status === 200 ? filtered : body);
+    }
+    // connect(toolkit) — require declared (an app shouldn't walk you through
+    // connecting an account it can never use), then forward.
+    const connectMatch = rest.match(/^\/([^/]+)\/connect$/);
+    if (connectMatch && req.method === "POST") {
+        const toolkit = decodeURIComponent(connectMatch[1]);
+        if (!declared.has(toolkit))
+            return sendJson(res, 403, PC_NOT_IN_MANIFEST(toolkit));
+        const { status, body } = await pcForward(ctx, "POST", `/personal-connections/${encodeURIComponent(toolkit)}/connect`);
+        return sendJson(res, status, body);
+    }
+    // call(tool, args) — the load-bearing gate: resolve the tool's toolkit, require
+    // both that toolkit declared AND this specific tool permitted, else 403 (never
+    // forwarded). No declaration at all ⇒ nothing resolves ⇒ refused, matching the
+    // prod chokepoint's "no manifest = refuse".
+    if (rest === "/call" && req.method === "POST") {
+        const raw = await readBody(req);
+        let payload;
+        try {
+            payload = raw ? JSON.parse(raw.toString("utf8")) : {};
+        }
+        catch {
+            return sendJson(res, 400, { detail: "body must be JSON" });
+        }
+        const tool = payload.tool;
+        if (!tool)
+            return sendJson(res, 400, { detail: '"tool" is required' });
+        if (entries.length === 0)
+            return sendJson(res, 403, PC_NOT_IN_MANIFEST(tool));
+        const toolkit = await pcResolveToolkit(ctx, entries, tool);
+        if (!toolkit || !pcAllows(entries, toolkit, tool)) {
+            return sendJson(res, 403, PC_NOT_IN_MANIFEST(tool));
+        }
+        const { status, body } = await pcForward(ctx, "POST", "/personal-connections/call", {
+            tool,
+            arguments: payload.arguments ?? {},
+        });
+        return sendJson(res, status, body);
+    }
+    sendJson(res, 404, { detail: "not found" });
+}
 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()/savedQueries()/

package/dist/manifest.js

@@ -41,9 +41,14 @@ const ALLOWED_KEYS = [
     "email",
     "adhoc_sql",
     "agents",
+    "personal_connectors",
 ];
 const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
 const SAVED_QUERY_NAME = /^[a-z0-9_]{1,80}$/;
+// Mirrors the server's _PERSONAL_CONNECTOR_RE exactly. The server is
+// authoritative; this exists so `railcode deploy` can reject a bad manifest
+// locally instead of after a round trip.
+const PERSONAL_CONNECTOR = /^[a-z0-9][a-z0-9_]{0,63}(?::(?:\*|[A-Z0-9_]{1,120}))?$/;
 // PyYAML's YAML 1.1 plain-scalar resolver: a bare (unquoted) scalar matching one
 // of these resolves to a non-string (bool/null/int/float/timestamp), and the
 // server rejects a non-string wherever the manifest wants a name. The quirks are
@@ -396,6 +401,7 @@ export function parseManifestYaml(source) {
         email: false,
         adhoc_sql: [],
         agents: [],
+        personal_connectors: [],
     };
     for (const [key, entry] of entries) {
         if (key === "run_as") {
@@ -415,12 +421,14 @@ export function parseManifestYaml(source) {
             doc.connectors = parseConnectors(entry);
         }
         else {
-            // saved_queries / adhoc_sql / agents: a list of names.
+            // saved_queries / adhoc_sql / agents / personal_connectors: a list of names.
             const items = parseStringList(entry, key);
             if (key === "saved_queries")
                 doc.saved_queries = items;
             else if (key === "agents")
                 doc.agents = items;
+            else if (key === "personal_connectors")
+                doc.personal_connectors = items;
             else
                 doc.adhoc_sql = items;
         }
@@ -643,6 +651,12 @@ function validateDoc(doc, lines) {
     doc.saved_queries = [...new Set(doc.saved_queries)].sort();
     doc.adhoc_sql = [...new Set(doc.adhoc_sql)].sort();
     doc.agents = [...new Set(doc.agents)].sort();
+    for (const entry of doc.personal_connectors) {
+        if (!PERSONAL_CONNECTOR.test(entry)) {
+            throw new ManifestParseError(`"${entry}" is not a valid personal_connectors entry — use "gmail", "gmail:*", or "gmail:GMAIL_SEND_EMAIL"`, lineOf(entry));
+        }
+    }
+    doc.personal_connectors = [...new Set(doc.personal_connectors)].sort();
     for (const name of Object.keys(doc.connectors)) {
         doc.connectors[name] = [...new Set(doc.connectors[name])].sort();
     }

package/package.json

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

package/static/sdk.js

@@ -261,7 +261,7 @@
     window.addEventListener("railcode:inspector", sync);
   }
   me().then((who) => {
-    if (who.user.is_admin) mount2();
+    if (who.user.is_admin || who.user.is_app_owner) mount2();
   }).catch(() => {
   });
 
@@ -711,6 +711,42 @@
   var llm = { generate, stream };
   var llmProviders = () => track("llm", "llmProviders()", () => call("GET", "/llm/providers"));
 
+  // ../sdk/src/personal-connections.ts
+  function list2() {
+    return track(
+      "personalConnections",
+      "personalConnections.list()",
+      () => call("GET", "/personal-connections")
+    );
+  }
+  function connect(toolkit) {
+    return track(
+      "personalConnections",
+      `personalConnections.connect(${q(toolkit)})`,
+      () => call(
+        "POST",
+        `/personal-connections/${encodeURIComponent(toolkit)}/connect`
+      )
+    );
+  }
+  function tools(toolkit) {
+    return track(
+      "personalConnections",
+      `personalConnections.tools(${q(toolkit)})`,
+      () => call("GET", `/personal-connections/${encodeURIComponent(toolkit)}/tools`)
+    );
+  }
+  function callTool(tool, args = {}) {
+    return track(
+      "personalConnections",
+      `personalConnections.call(${q(tool)})`,
+      () => call("POST", "/personal-connections/call", {
+        body: { tool, arguments: args }
+      })
+    );
+  }
+  var personalConnections = { list: list2, connect, tools, call: callTool };
+
   // ../sdk/src/queries.ts
   var PARAMS_LABEL_MAX2 = 40;
   var query = (name, params) => {
@@ -769,6 +805,7 @@
   target.email = email;
   target.llm = llm;
   target.llmProviders = llmProviders;
+  target.personalConnections = personalConnections;
   target.data = data;
   target.postgres = postgres;
   target.bigquery = bigquery;