railcode 0.1.26 → 0.1.28

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)
@@ -32,6 +34,10 @@ railcode roles <list|create|update|delete|add-member|remove-member|grants|grant|
                                    Org roles + the granular grants table (admin)
 railcode apps <list|show|access|set-access|transfer|delete> ...
                                    Apps + access policy (owner/admin)
+railcode app kv <collections|list|get|set|delete|drop> ...
+                                   Manage an app's KV store (owner)
+railcode app files <list|download|upload|delete> ...
+                                   Manage an app's files (owner)
 railcode analytics <app> [--range 1d|7d|30d|90d]    Per-app pageview analytics
 railcode logs <connector|service-connector|llm|email|agent> [filters]
                                    Org observability logs (admin)
@@ -54,7 +60,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 +90,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 +106,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 +114,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
@@ -125,6 +135,33 @@ API URL resolution: `--api-url` > `RAILCODE_API_URL` > saved config > prompt.
 Set `RAILCODE_API_TOKEN` to override the saved token in CI. On a `401`, the saved
 token is cleared and you're prompted to `railcode login` again.
 
+## Staying up to date
+
+The CLI keeps itself current. When you run a command in an interactive terminal it
+checks the npm registry — at most once every 6 hours — for a newer `railcode`
+release **within your current major** and, if there is one, installs it globally
+(with whichever package manager it detects: npm/pnpm/yarn/bun) and tells you:
+
+```
+railcode: a new version is available — 0.1.26 → 0.1.27. Updating…
+railcode: updated to 0.1.27. It takes effect on your next command.
+```
+
+It never jumps across a major version (a breaking `2.0.0` is left for you to
+install deliberately), the check is best-effort (a registry/network hiccup is
+silently ignored — it never blocks your command), and it's skipped in
+non-interactive/CI runs so automation never self-mutates a global install. The
+`last_checked_for_updates` timestamp lives in `~/.railcode/update-check.json`, and
+all of the above is printed to **stderr** so `--json` output stays clean.
+
+Environment overrides:
+
+- `RAILCODE_NO_UPDATE=1` — turn auto-update off entirely.
+- `RAILCODE_UPDATE_DRY_RUN=1` — check and print the command it *would* run, without
+  installing (also forces the check even off-TTY; handy for scripts and testing).
+- `RAILCODE_REGISTRY_URL` (falls back to `npm_config_registry`) — point the check
+  at a different npm-compatible registry.
+
 ## `railcode.json`
 
 ```json

package/dist/app-storage.js

@@ -0,0 +1,154 @@
+// Pure helpers behind `railcode app kv ...` / `railcode app files ...`. Kept free
+// of I/O and process state so they unit-test directly (see test/app-storage.test.mjs);
+// the command layer in index.ts does the HTTP, file reads, and printing.
+export class StorageError extends Error {
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// Parse + validate the shared scope flags. `allowAll` gates the cross-scope `all`
+// selector to the listing commands (a record/file mutation must name one namespace).
+export function parseScopeSelector(scope, user, role, opts) {
+    const kind = (scope ?? "shared").toLowerCase();
+    const allowed = opts.allowAll ? "shared, user, role, all" : "shared, user, role";
+    if (!["shared", "user", "role", "all"].includes(kind)) {
+        throw new StorageError(`Unknown --scope "${scope}". Use one of: ${allowed}.`);
+    }
+    if (kind === "all") {
+        if (!opts.allowAll) {
+            throw new StorageError("--scope all only lists (kv collections, kv list, files list); a record/file " +
+                "operation must target one scope.");
+        }
+        if (user || role)
+            throw new StorageError("--scope all takes no --user or --role.");
+        return { scope: "all" };
+    }
+    if (kind === "shared") {
+        if (user || role)
+            throw new StorageError("--scope shared takes no --user or --role.");
+        return { scope: "shared" };
+    }
+    if (kind === "user") {
+        if (role)
+            throw new StorageError("--scope user takes no --role.");
+        if (!user)
+            throw new StorageError("--scope user requires --user <member-uuid>.");
+        if (!UUID_RE.test(user))
+            throw new StorageError("--user must be a member UUID.");
+        return { scope: "user", user };
+    }
+    // role
+    if (user)
+        throw new StorageError("--scope role takes no --user.");
+    if (!role)
+        throw new StorageError("--scope role requires --role <role-uuid>.");
+    if (!UUID_RE.test(role))
+        throw new StorageError("--role must be a role UUID.");
+    return { scope: "role", role };
+}
+// The scope selectors as a query string, echoed onto every storage request.
+export function scopeQuery(sel) {
+    const params = new URLSearchParams();
+    params.set("scope", sel.scope);
+    if (sel.user)
+        params.set("user", sel.user);
+    if (sel.role)
+        params.set("role", sel.role);
+    return params.toString();
+}
+// The value for `kv set` — inline JSON or from --file, never both, never neither.
+// A KV value is JSON of any shape: an object, array, string, number, or bool.
+export function parseKvValue(positional, fileText) {
+    const hasPos = typeof positional === "string" && positional.length > 0;
+    const hasFile = typeof fileText === "string";
+    if (hasPos && hasFile) {
+        throw new StorageError("Pass the value inline OR with --file, not both.");
+    }
+    if (!hasPos && !hasFile) {
+        throw new StorageError('Provide a JSON value: railcode app kv set <collection> <key> \'{"n":1}\'  (or --file v.json).');
+    }
+    const raw = hasFile ? fileText : positional;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new StorageError("Value must be valid JSON — an object, array, string, number, or bool " +
+            "(e.g. '{\"n\":1}', '\"hello\"', 42, true).");
+    }
+}
+// --query is a KV `where` clause: a JSON array of [field, op, value] triples, passed
+// through to the same query engine the data plane exposes. Validated here for a clean
+// local error; the server re-validates authoritatively.
+export function parseWhere(raw) {
+    if (raw === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new StorageError('--query must be JSON, e.g. --query \'[["n","gt",1]]\'.');
+    }
+    if (!Array.isArray(parsed)) {
+        throw new StorageError('--query must be a JSON array of [field, op, value] clauses.');
+    }
+    return raw;
+}
+// --limit/--offset → the API's page/size. offset must be a whole number of pages so
+// the translation is exact (the API pages, it doesn't offset).
+export function pageParams(limit, offset) {
+    const out = {};
+    if (limit !== undefined) {
+        if (!Number.isInteger(limit) || limit <= 0) {
+            throw new StorageError("--limit must be a positive integer.");
+        }
+        out.size = limit;
+    }
+    if (offset !== undefined) {
+        if (!Number.isInteger(offset) || offset < 0) {
+            throw new StorageError("--offset must be a non-negative integer.");
+        }
+        if (limit === undefined)
+            throw new StorageError("--offset requires --limit.");
+        if (offset % limit !== 0) {
+            throw new StorageError("--offset must be a whole multiple of --limit.");
+        }
+        out.page = Math.floor(offset / limit) + 1;
+    }
+    return out;
+}
+// A best-effort content type from a filename extension (upload default:
+// application/octet-stream). The backend forces download on serve regardless.
+export function guessContentType(name) {
+    const ext = name.toLowerCase().split(".").pop() ?? "";
+    const map = {
+        txt: "text/plain",
+        md: "text/markdown",
+        csv: "text/csv",
+        json: "application/json",
+        html: "text/html",
+        css: "text/css",
+        js: "text/javascript",
+        svg: "image/svg+xml",
+        png: "image/png",
+        jpg: "image/jpeg",
+        jpeg: "image/jpeg",
+        gif: "image/gif",
+        webp: "image/webp",
+        pdf: "application/pdf",
+        zip: "application/zip",
+    };
+    return map[ext] ?? "application/octet-stream";
+}
+// Percent-encode each segment of a file name while keeping the `/` separators the
+// scope-aware `{name:path}` route expects.
+export function encodeFilePath(name) {
+    return name
+        .split("/")
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+}
+// The owner label (member email / role name) for a listing row, or a dash.
+export function ownerCell(scope, ownerLabel) {
+    if (scope === "shared")
+        return "-";
+    return ownerLabel ?? "-";
+}