railcode 0.1.26 → 0.1.27

package/README.md

@@ -19,7 +19,9 @@ on your `PATH`.
 ```
 railcode login [--api-url <url>]   Sign in and mint a personal API token
 railcode login --setup-token <token>  Sign in with a one-time onboarding setup token
-railcode init <app> [--template react|static]
+railcode init <app> [dir] [--template react|static] [--force]
+                                   Scaffold an app. dir defaults to ./<app>;
+                                   pass "." to scaffold into the current dir
 railcode deploy                    Build (if configured) and deploy the app here
 railcode db <list|query> ...       List data connectors / run read-only SQL
 railcode connections <list|create|delete> ...   Manage org data connectors (admin)
@@ -54,7 +56,11 @@ your saved org and are gated server-side by the same capabilities as the console
   a personal API token: the CLI exchanges it once for a personal API token and
   writes the same config as a browser login. If it's expired or already used,
   generate a fresh prompt from the dashboard.
-- **`init <app>`** scaffolds a directory. By default it creates a React + Vite +
+- **`init <app> [dir]`** scaffolds a directory. `dir` is optional and defaults to
+  `./<app>`; pass `.` to scaffold into the current directory, or any path to
+  scaffold into it. The target need not be empty (same-named files are
+  overwritten), but an existing `railcode.json` is preserved unless you pass
+  `--force`. By default it creates a React + Vite +
   Zustand starter — a personalized "Welcome to Railcode, `<name>`" home wired to
   every SDK capability: identity/team, a live to-dos list and file uploads (work
   with zero setup), and SQL, saved queries, service connectors, and LLM cards that
@@ -80,15 +86,15 @@ your saved org and are gated server-side by the same capabilities as the console
   (SQL is never interpolated), `--file <path>` reads SQL from a file, and
   `--json` prints the raw `{ columns, rows, rowcount, truncated }` envelope.
 - **`agent`** manages org-scoped managed agents when your permissions allow it.
-  Manifests are JSON files in the same shape the API stores under
+  Manifests are JSON or YAML files in the same shape the API stores under
   `agent.manifest`.
   - `railcode agent list` lists agents; `--json` prints raw `AgentOut[]`.
   - `railcode agent show <name|uuid>` prints one agent; `--manifest` prints only
     its manifest JSON.
   - `railcode agent pull <name|uuid> --output agent.json` writes the existing
     manifest for editing.
-  - `railcode agent create --file agent.json` creates an agent; `update <agent>
-    --file agent.json` replaces an existing agent manifest; `delete <agent> --yes`
+  - `railcode agent create --file agent.yaml` creates an agent; `update <agent>
+    --file agent.yaml` replaces an existing agent manifest; `delete <agent> --yes`
     archives it. `--visibility <org|personal>` on `create`/`update`/`test` sets or
     changes who the agent belongs to (default `org` on create; omitted on `update`
     leaves it alone). A `personal` agent is invokable and manageable by its
@@ -96,7 +102,7 @@ your saved org and are gated server-side by the same capabilities as the console
     once created. Requires `agent:create` (personal) or `agent:create_org` (org).
     `agent show`/`list` print `visibility`, and `show` prints `Owner:` for a
     personal agent.
-  - `railcode agent test --file agent.json --input '{"k":"v"}'` runs a draft
+  - `railcode agent test --file agent.yaml --input '{"k":"v"}'` runs a draft
     manifest without saving; `railcode agent run <agent> --input '{"k":"v"}'`
     invokes a saved agent and prints the result. Use `--trace` for the step trace
     and `--json` for the raw run detail.
@@ -104,7 +110,7 @@ your saved org and are gated server-side by the same capabilities as the console
     creates or updates the agent's one schedule. `schedule show`, `pause`,
     `resume`, `delete --yes`, and `run-now` operate on that single schedule.
 - **`personal-connectors`** (aliases `personal-connector`, `pc`) manages **your
-  own** connected third-party accounts (Gmail, Slack, …), brokered by Composio —
+  own** connected third-party accounts (Gmail, Slack, …), brokered by railcode (in-house) —
   distinct from org-admin **service connectors** and from an agent's
   `tools.personal_connectors`. `list` shows toolkits this deployment brokers and
   your connection status; `tools <toolkit>` prints that toolkit's callable tools

package/dist/index.js

@@ -10,6 +10,7 @@ import { dirname, join, relative, resolve, sep } from "node:path";
 import process from "node:process";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
 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";
@@ -35,11 +36,13 @@ const HELP = `railcode ${VERSION}
 Developer CLI for the multi-tenant Railcode platform.
 
 Usage:
-  railcode login [--api-url <url>]   Sign in and mint a personal API token
+  railcode login [--api-url <url>] [--paste]   Sign in and mint a personal API token
+                                      (--paste / --no-browser: skip the localhost
+                                      callback, paste a code instead — for SSH/headless)
   railcode login --setup-token <token>  Sign in with a one-time onboarding setup token
   railcode deploy [--private]         Build (if configured) and deploy the app here
   railcode dev [--port <n>] [--reset]  Run the app locally against an emulated /_api
-  railcode init <app> [--template react|static]
+  railcode init <app> [dir] [--template react|static] [--force]
   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)
@@ -63,7 +66,8 @@ Usage:
   railcode --help
 
 Config: ~/.railcode/config.json
-API URL resolves from --api-url, then RAILCODE_API_URL, then saved config.
+API URL resolves from --api-url, then RAILCODE_API_URL, then saved config, then
+the default (${DEFAULT_API_URL}) — never prompted.
 `;
 // ---------------------------------------------------------------------------
 // Entry point
@@ -212,9 +216,12 @@ async function commandLogin(args) {
         await loginWithSetupToken(args, saved, setupToken);
         return;
     }
-    const apiUrl = await resolveLoginApiUrl(args, saved);
+    const apiUrl = resolveLoginApiUrl(args, saved);
+    // --paste / --no-browser: skip the localhost callback entirely and go straight
+    // to "open this URL, paste the code" — the right default for headless/SSH.
+    const pasteMode = args.options.paste === true || args.options.noBrowser === true;
     const serverConfig = (await readJsonOrThrow(await apiFetch(apiUrl, "/api/config", {}), "Server config"));
-    const minted = await authorizeCliWithBrowser(apiUrl);
+    const minted = await authorizeCliWithBrowser(apiUrl, pasteMode);
     // Resolve the caller's identity + organization.
     const me = (await readJsonOrThrow(await apiFetch(apiUrl, "/api/auth/me", {
         headers: { Authorization: `Bearer ${minted.token}` },
@@ -282,10 +289,16 @@ async function loginWithSetupToken(args, saved, setupToken) {
     }
     console.log(`Token ${redeemed.token_prefix}... saved to ${CONFIG_PATH}.`);
 }
-async function authorizeCliWithBrowser(apiUrl) {
+async function authorizeCliWithBrowser(apiUrl, pasteMode) {
     if (!process.stdin.isTTY) {
         throw new CliError("Browser login requires a TTY. Set RAILCODE_API_TOKEN in non-interactive environments.", 2);
     }
+    if (pasteMode) {
+        return authorizeCliByPaste(apiUrl);
+    }
+    // Happy path: a localhost callback server catches the code automatically. We
+    // also print a code-mode URL so login still completes when the browser is on a
+    // different machine and can't reach this box's localhost (the common SSH case).
     const state = randomBytes(16).toString("hex");
     const callback = await startCliAuthCallback(state);
     try {
@@ -293,23 +306,80 @@ async function authorizeCliWithBrowser(apiUrl) {
             redirect_uri: callback.redirectUri,
             state,
         })}`;
-        console.log("");
-        printUrlBox("Railcode login", authorizeUrl);
+        const manualUrl = `${apiUrl}/api/auth/cli/authorize?${new URLSearchParams({ mode: "code" })}`;
         console.log("");
         if (openBrowser(authorizeUrl)) {
-            console.log("Opening your browser. If it does not open, paste the URL above.");
+            console.log("Opening your browser to authorize Railcode.");
         }
         else {
-            console.log("Paste the URL above into your browser to continue.");
+            console.log("Open this URL in your browser to authorize Railcode:");
+            console.log(`  ${authorizeUrl}`);
         }
-        console.log("Waiting for browser authorization...");
-        const code = await callback.code;
+        console.log("");
+        console.log("On a remote/SSH box? If the browser can't reach this machine, open the");
+        console.log("URL below to get a code, then paste it here:");
+        console.log("");
+        printUrlBox("Railcode login", manualUrl);
+        console.log("");
+        const code = await waitForCallbackOrPastedCode(callback.code);
         return await exchangeCliAuthCode(apiUrl, code);
     }
     finally {
         await callback.close();
     }
 }
+// Paste-only flow (--paste / --no-browser): no localhost server, no waiting on a
+// callback. Show the code-mode URL and read the pasted code back.
+async function authorizeCliByPaste(apiUrl) {
+    const manualUrl = `${apiUrl}/api/auth/cli/authorize?${new URLSearchParams({ mode: "code" })}`;
+    console.log("");
+    printUrlBox("Railcode login", manualUrl);
+    console.log("");
+    if (openBrowser(manualUrl)) {
+        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("");
+    const code = (await prompt("Paste the code from your browser: ")).trim();
+    if (!code) {
+        throw new CliError("No code entered.", 1);
+    }
+    return exchangeCliAuthCode(apiUrl, code);
+}
+// Race the localhost callback against a pasted line — whichever yields a code
+// first wins. An empty line means "keep waiting", so we re-prompt. When the
+// callback wins, the abort signal cancels the pending readline question.
+async function waitForCallbackOrPastedCode(callbackCode) {
+    const controller = new AbortController();
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const fromCallback = callbackCode.then((code) => {
+        controller.abort();
+        return code;
+    }, (error) => {
+        controller.abort();
+        throw error;
+    });
+    const fromPaste = (async () => {
+        for (;;) {
+            const answer = (await rl.question("Paste the code from your browser (or press Enter to keep waiting): ", {
+                signal: controller.signal,
+            })).trim();
+            if (answer)
+                return answer;
+        }
+    })();
+    try {
+        return await Promise.race([fromCallback, fromPaste]);
+    }
+    finally {
+        controller.abort();
+        rl.close();
+        fromCallback.catch(() => { });
+        fromPaste.catch(() => { });
+    }
+}
 async function startCliAuthCallback(expectedState) {
     let resolveCode = () => { };
     let rejectCode = () => { };
@@ -443,13 +513,12 @@ function escapeHtml(value) {
         .replaceAll('"', "&quot;")
         .replaceAll("'", "&#39;");
 }
-async function resolveLoginApiUrl(args, saved) {
-    const explicit = optionApiUrl(args) || process.env.RAILCODE_API_URL;
-    if (explicit)
-        return normalizeApiOrigin(explicit);
-    const fallback = saved.apiUrl || DEFAULT_API_URL;
-    const answer = await prompt(`Server URL [${fallback}]: `);
-    return normalizeApiOrigin(answer.trim() || fallback);
+// Resolve the API URL non-interactively — no prompt. Precedence:
+//   --api-url flag → RAILCODE_API_URL env → saved config → DEFAULT_API_URL.
+// The default "just works"; override it only with --api-url (env/saved kept for
+// continuity). Mirrors the setup-token path's resolution in loginWithSetupToken.
+function resolveLoginApiUrl(args, saved) {
+    return normalizeApiOrigin(optionApiUrl(args) || process.env.RAILCODE_API_URL || saved.apiUrl || DEFAULT_API_URL);
 }
 // ---------------------------------------------------------------------------
 // deploy
@@ -700,12 +769,19 @@ function packageBuildCommand(root) {
 async function commandInit(args) {
     const app = args.rest[0];
     if (!app)
-        throw new CliError("Usage: railcode init <app>", 2);
+        throw new CliError("Usage: railcode init <app> [dir]", 2);
     assertAppName(app);
     const template = initTemplate(args);
-    const target = resolve(process.cwd(), app);
-    if (existsSync(target) && readdirSync(target).length > 0) {
-        throw new CliError(`Refusing to scaffold into a non-empty directory: ${target}`, 1);
+    // Optional second positional: the directory to scaffold into. Defaults to a
+    // new "<app>/" subdir. Passing "." scaffolds into the current directory. The
+    // target need not be empty — same-named files are overwritten.
+    const dir = args.rest[1];
+    const target = resolve(process.cwd(), dir ?? app);
+    // Light-touch guard: never clobber an existing app manifest without --force.
+    const manifestPath = join(target, MANIFEST_NAME);
+    if (existsSync(manifestPath) && !args.options.force) {
+        throw new CliError(`A ${MANIFEST_NAME} already exists in ${relativeLabel(process.cwd(), target)}/. ` +
+            "Re-run with --force to overwrite it.", 1);
     }
     mkdirSync(target, { recursive: true });
     if (template === "static") {
@@ -716,7 +792,10 @@ async function commandInit(args) {
     }
     console.log(`Created ${template} Railcode app "${app}" in ${relativeLabel(process.cwd(), target)}/`);
     console.log("Next:");
-    console.log(`  cd ${app}`);
+    // Only prompt a `cd` when the files landed somewhere other than the cwd.
+    if (resolve(target) !== resolve(process.cwd())) {
+        console.log(`  cd ${relativeLabel(process.cwd(), target)}`);
+    }
     if (template === "react") {
         console.log("  npm install");
     }
@@ -970,7 +1049,6 @@ type LlmOptions = {
   provider?: string;
   system?: string;
   output?: LlmOutputSpec;
-  temperature?: number;
   maxOutputTokens?: number;
   metadata?: Record<string, unknown>;
 };
@@ -3794,8 +3872,8 @@ Usage:
   railcode agent show <agent>                 Show one agent
   railcode agent pull <agent> [--output <path>]
                                              Write the agent manifest as JSON
-  railcode agent create --file <path>         Create an agent from a JSON manifest
-  railcode agent update <agent> --file <path> Update an agent from a JSON manifest
+  railcode agent create --file <path>         Create an agent from a JSON or YAML manifest
+  railcode agent update <agent> --file <path> Update an agent from a JSON or YAML manifest
   railcode agent delete <agent> [--yes]       Delete/archive an agent
   railcode agent test --file <path> [opts]    Run a draft manifest without saving
   railcode agent run <agent> [opts]           Trigger a saved agent and print results
@@ -3803,7 +3881,7 @@ Usage:
 
 Agent options:
   --json                                Print the raw API response
-  --file <path>                         JSON manifest file
+  --file <path>                         JSON or YAML manifest file
   --output <path>                       Output path for pull (default stdout)
   --input '<json>'                      Invoke/test input JSON (default null)
   --input-file <path>                   Read invoke/test input JSON from a file
@@ -3823,7 +3901,7 @@ Schedule options:
   --timezone <iana>                     IANA timezone (default: UTC on create)
   --enabled / --disabled                Initial or updated enabled state
 
-Manifests are JSON files in the same shape the API stores under agent.manifest.
+Manifests are JSON or YAML files in the same shape the API stores under agent.manifest.
 Schedules are currently one per agent, so "set" creates the schedule if missing
 or updates the existing one.
 `;
@@ -4185,8 +4263,9 @@ async function requireSingleSchedule(config, ref) {
 function readAgentManifest(args) {
     const path = optionString(args, "file");
     if (!path)
-        throw new CliError("Pass --file <agent-manifest.json>.", 2);
-    return readJsonObjectFile(path, "Agent manifest");
+        throw new CliError("Pass --file <agent-manifest.json|yaml|yml>.", 2);
+    const format = /\.ya?ml$/i.test(path) ? "YAML" : "JSON";
+    return readObjectFile(path, "Agent manifest", format);
 }
 // Omitted means "use the server default" on create/test (org) and "leave alone"
 // on update — never send the key unless the caller passed it explicitly.
@@ -4200,18 +4279,22 @@ function agentVisibilityOption(args) {
     return value;
 }
 function readJsonObjectFile(path, label) {
+    return readObjectFile(path, label, "JSON");
+}
+function readObjectFile(path, label, format) {
     const resolved = resolve(process.cwd(), path);
     if (!existsSync(resolved))
         throw new CliError(`${label} file not found: ${path}`, 2);
     let parsed;
     try {
-        parsed = JSON.parse(readFileSync(resolved, "utf8"));
+        const raw = readFileSync(resolved, "utf8");
+        parsed = format === "YAML" ? parseYaml(raw) : JSON.parse(raw);
     }
     catch (error) {
-        throw new CliError(`${label} file is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, 2);
+        throw new CliError(`${label} file is not valid ${format}: ${error instanceof Error ? error.message : String(error)}`, 2);
     }
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new CliError(`${label} file must contain a JSON object.`, 2);
+        throw new CliError(`${label} file must contain a ${format} object.`, 2);
     }
     return parsed;
 }
@@ -5148,7 +5231,9 @@ const PC_HELP = `railcode personal-connectors — your own connected accounts (G
 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 connect <toolkit>  Start connecting it: prints the OAuth URL, or
+                                                  reports if it needs a token
+  railcode personal-connectors connect <toolkit> --token '<value>'  Link a token-auth connector (e.g. a GitHub PAT)
   railcode personal-connectors call <toolkit> <tool> [--args '<json>']  Run one tool on your own account
 
 Aliases: personal-connector, pc
@@ -5159,6 +5244,7 @@ input schema, so you know what to put in an app's \`personal_connectors:\` and w
 
 Options:
   --json                                 Print raw JSON instead of a table
+  --token '<value>'                      Token/key for \`connect\` on a token-auth connector
   --args '<json>'                        Arguments object for \`call\` (default {})
 `;
 async function commandPersonalConnectors(args) {
@@ -5237,13 +5323,31 @@ async function commandPcTools(args) {
     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);
+    rejectUnknownOptions(args, ["json", "token", "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.
+    // A token-auth connector (e.g. a GitHub PAT): `--token <value>` submits it
+    // directly, otherwise we tell the caller a token is needed.
+    if (typeof args.options.token === "string") {
+        const tokResp = await authedFetch(config, `/api/personal-connections/${encodeURIComponent(toolkit)}/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ token: args.options.token }),
+        });
+        if (tokResp.status === 401)
+            await reLoginOrThrow();
+        if (pcUnavailable(tokResp.status)) {
+            console.log("Personal connectors are not enabled on this deployment.");
+            return;
+        }
+        await readJsonOrThrow(tokResp, `Connect ${toolkit}`);
+        console.log(`Connected ${toolkit}.`);
+        return;
+    }
+    // Otherwise start the flow. OAuth is browser-bound (the CLI can't complete it),
+    // so it prints the URL; a token connector reports that a token is required.
     const resp = await authedFetch(config, `/api/personal-connections/${encodeURIComponent(toolkit)}/connect`, { method: "POST" });
     if (resp.status === 401)
         await reLoginOrThrow();
@@ -5256,6 +5360,11 @@ async function commandPcConnect(args) {
         console.log(JSON.stringify(body, null, 2));
         return;
     }
+    if (body.mode === "token") {
+        console.log(`${toolkit} connects with a ${body.token_label ?? "token"}. ` +
+            `Re-run with --token '<value>' to link it:\n\n  railcode personal-connectors connect ${toolkit} --token '<value>'\n`);
+        return;
+    }
     console.log(`Open this URL to connect ${toolkit}, then re-run your command:\n\n  ${body.redirect_url}\n`);
 }
 async function commandPcCall(args) {

package/dist/manifest.js

@@ -48,7 +48,7 @@ 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}))?$/;
+const PERSONAL_CONNECTOR = /^[a-z0-9][a-z0-9_]{0,63}(?::(?:\*|[A-Za-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
@@ -653,7 +653,7 @@ function validateDoc(doc, lines) {
     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));
+            throw new ManifestParseError(`"${entry}" is not a valid personal_connectors entry — use "gmail", "gmail:*", or "gmail:send_email"`, lineOf(entry));
         }
     }
     doc.personal_connectors = [...new Set(doc.personal_connectors)].sort();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "railcode",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "description": "Developer CLI for the multi-tenant Railcode platform: log in, scaffold, and deploy static apps.",
   "license": "MIT",
   "type": "module",
@@ -27,5 +27,8 @@
   "devDependencies": {
     "@types/node": "^24.0.0",
     "typescript": "^5.9.0"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
   }
 }