railcode 0.1.20 → 0.1.22

package/README.md

@@ -58,7 +58,7 @@ railcode agent <list|show|create|update|delete|run|schedule> ...
   `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|bigquery|snowflake>` is inferred from the connector
+  table + row count; `--engine <postgres|bigquery|turso>` 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.

package/dist/db.js

@@ -3,7 +3,7 @@
 // the command layer in index.ts does the HTTP, file reads, and printing.
 export class DbError extends Error {
 }
-export const DB_ENGINES = ["postgres", "bigquery", "snowflake"];
+export const DB_ENGINES = ["postgres", "bigquery", "turso"];
 // `--params '<json-array>'` → the positional $1,$2,… values. Empty when omitted.
 export function parseSqlParams(raw) {
     if (raw === undefined)

package/dist/index.js

@@ -826,7 +826,7 @@ export default defineConfig({
 }
 function reactRailcodeTypes() {
     return `type Me = {
-  user: { uuid: string; name: string; email: string };
+  user: { uuid: string; name: string; email: string; is_admin: boolean; roles: RoleRef[] };
   app: { uuid: string; slug: string; name: string };
   org: { uuid: string; slug: string; name: string };
 };
@@ -835,9 +835,12 @@ type AppUser = {
   uuid: string;
   name: string;
   email: string;
-  role: string | null;
+  is_admin: boolean;
 };
 
+type RoleRef = { uuid: string; name: string };
+type OrgRole = RoleRef & { description: string; is_member: boolean };
+
 type KvRecord<T = unknown> = {
   key: string;
   value: T;
@@ -881,7 +884,7 @@ type SqlRows = Array<Record<string, unknown>> & {
 };
 
 type DataConnectorInfo = {
-  engine: "postgres" | "bigquery" | "snowflake" | string;
+  engine: "postgres" | "bigquery" | "turso" | string;
   name: string;
 };
 
@@ -960,20 +963,50 @@ type LlmModelInfo = { model: string; default: boolean };
 
 type LlmProviderInfo = { provider: string; default: boolean; models: LlmModelInfo[] };
 
+type EmailSendOptions = {
+  to: string | string[];
+  subject: string;
+  html?: string;
+  text?: string;
+  cc?: string | string[];
+  bcc?: string | string[];
+  replyTo?: string;
+};
+
+type EmailSendResult = {
+  id: string;
+  status: string;
+  requestId: string;
+};
+
 declare const me: () => Promise<Me>;
 declare const appUsers: () => Promise<AppUser[]>;
+declare const roles: () => Promise<OrgRole[]>;
 declare const designSystem: () => Promise<string>;
-declare const db: { collection<T = unknown>(name: string): Collection<T> };
-declare const files: {
+type DbNamespace = { collection<T = unknown>(name: string): Collection<T> };
+type FilesNamespace = {
   upload(name: string, data: Blob | ArrayBuffer | ArrayBufferView, contentType?: string): Promise<FileMeta>;
   url(name: string): string;
   list(): Promise<FileMeta[]>;
   delete(name: string): Promise<void>;
 };
+// Storage scopes. Bare db/files are aliases for \`.shared\` (app-wide). \`.user\` is the
+// signed-in caller's own private namespace; \`.role(uuid)\` is one org role's namespace
+// (the caller must be a live member of that role — owner/admin may reach any). The same
+// (collection,key) / file name never collides across scopes.
+declare const db: DbNamespace & {
+  shared: DbNamespace;
+  user: DbNamespace;
+  role(uuid: string): DbNamespace;
+};
+declare const files: FilesNamespace & {
+  shared: FilesNamespace;
+  user: FilesNamespace;
+  role(uuid: string): FilesNamespace;
+};
 declare const data: DatabaseNamespace;
 declare const postgres: DatabaseNamespace;
 declare const bigquery: DatabaseNamespace;
-declare const snowflake: DatabaseNamespace;
 declare const dataConnectors: () => Promise<DataConnectorInfo[]>;
 declare const savedQueries: () => Promise<SavedQueryInfo[]>;
 declare const query: (name: string, params?: Record<string, unknown>) => Promise<SqlRows>;
@@ -986,6 +1019,7 @@ declare const llm: {
   stream(input: string | LlmMessage[], opts?: LlmOptions): AsyncIterable<LlmStreamEvent>;
 };
 declare const llmProviders: () => Promise<LlmProviderInfo[]>;
+declare const email: { send(opts: EmailSendOptions): Promise<EmailSendResult> };
 `;
 }
 function reactViteEnvTypes() {
@@ -1060,6 +1094,14 @@ function message(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+function httpStatus(error: unknown): number | null {
+  if (typeof error === "object" && error !== null && "status" in error) {
+    const status = (error as { status?: unknown }).status;
+    return typeof status === "number" ? status : null;
+  }
+  return null;
+}
+
 function truncate(value: string, max: number): string {
   return value.length > max ? value.slice(0, max - 1) + "…" : value;
 }
@@ -1361,7 +1403,7 @@ function Hero() {
             </div>
           ) : null}
           {teammates.slice(0, 4).map((user) => (
-            <div className="avatar" key={user.uuid} title={user.name + (user.role ? " · " + user.role : "")}>
+            <div className="avatar" key={user.uuid} title={user.name + (user.is_admin ? " · admin" : "")}>
               {initials(user.name)}
             </div>
           ))}
@@ -1867,9 +1909,124 @@ function ConnectorsCard() {
   );
 }
 
+function emailFailureMessage(error: unknown): string {
+  const status = httpStatus(error);
+  if (status === 403) return "Email is not granted for this app or user yet.";
+  if (status === 429) return "The daily email recipient limit has been reached.";
+  if (status === 503) return "Email is not configured for this Railcode instance.";
+  return message(error);
+}
+
+function EmailCard() {
+  const { identity } = useAppStore();
+  const [to, setTo] = useState("");
+  const [subject, setSubject] = useState("Hello from " + APP_SLUG);
+  const [body, setBody] = useState(
+    "This message was sent by the Railcode starter app through the platform email gateway.",
+  );
+  const [busy, setBusy] = useState(false);
+  const [status, setStatus] = useState<{ kind: "sent" | "error"; text: string } | null>(null);
+
+  useEffect(() => {
+    if (!to && identity?.user.email) setTo(identity.user.email);
+  }, [identity, to]);
+
+  async function sendMessage(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const recipient = to.trim();
+    const trimmedSubject = subject.trim() || "Hello from " + APP_SLUG;
+    const text = body.trim() || "Sent from a Railcode starter app.";
+    if (!recipient) {
+      setStatus({ kind: "error", text: "Add a recipient email address first." });
+      return;
+    }
+
+    setBusy(true);
+    setStatus(null);
+    try {
+      const result = await email.send({ to: recipient, subject: trimmedSubject, text });
+      setStatus({
+        kind: "sent",
+        text: "Sent with status " + result.status + " · " + result.requestId,
+      });
+    } catch (error) {
+      setStatus({ kind: "error", text: emailFailureMessage(error) });
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <article className="card">
+      <div className="card-head">
+        <div>
+          <div className="card-title-row">
+            <Icon name="mail" />
+            <span className="card-title">
+              <Reveal code="await email.send(message)">Email</Reveal>
+            </span>
+          </div>
+        </div>
+      </div>
+
+      <form className="email-form" onSubmit={sendMessage}>
+        <label className="control-field">
+          <span>Recipient</span>
+          <input
+            className="field"
+            type="email"
+            autoComplete="email"
+            value={to}
+            onChange={(event) => setTo(event.target.value)}
+          />
+        </label>
+        <label className="control-field">
+          <span>Subject</span>
+          <input
+            className="field"
+            type="text"
+            value={subject}
+            onChange={(event) => setSubject(event.target.value)}
+          />
+        </label>
+        <label className="json-editor">
+          <span>Message</span>
+          <textarea
+            className="field"
+            rows={4}
+            value={body}
+            onChange={(event) => setBody(event.target.value)}
+          />
+        </label>
+        <ActionTip code={\`await email.send({
+  to,
+  subject,
+  text
+})\`} className="upload-tip">
+          <button className="btn btn-primary" type="submit" disabled={busy}>
+            {busy ? <span className="spinner" /> : <Icon name="mail" />}
+            {busy ? "Sending..." : "Send test email"}
+          </button>
+        </ActionTip>
+      </form>
+
+      <div className="email-state">
+        <div className="result-status">
+          <span>Delivery</span>
+          <span>{status?.kind === "sent" ? "Sent" : status?.kind === "error" ? "Needs setup" : "Ready"}</span>
+        </div>
+        <p className={status?.kind === "error" ? "email-note is-error" : "email-note"}>
+          {status?.text ||
+            "Email uses the platform sender and requires an email grant or app manifest approval."}
+        </p>
+      </div>
+    </article>
+  );
+}
+
 const AI_SAMPLE_PROMPT = "Summarize what this Railcode template demonstrates in one sentence.";
 const AI_SAMPLE_RESPONSE =
-  "This template shows a live Railcode app reading identity, storing notes in KV, uploading files, querying Postgres, invoking a saved query, calling Stripe through a service connector, and generating text — all without handling a single credential in the browser.";
+  "This template shows a live Railcode app reading identity, storing notes in KV, uploading files, querying Postgres, invoking a saved query, calling Stripe through a service connector, sending email, and generating text — all without handling a single credential in the browser.";
 
 function AiCard() {
   const [prompt, setPrompt] = useState(AI_SAMPLE_PROMPT);
@@ -2010,6 +2167,10 @@ function IconSprite() {
       <symbol id="i-chat" viewBox="0 0 24 24">
         <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" />
       </symbol>
+      <symbol id="i-mail" viewBox="0 0 24 24">
+        <rect x="3" y="5" width="18" height="14" rx="2" />
+        <path d="m3 7 9 6 9-6" />
+      </symbol>
       <symbol id="i-code" viewBox="0 0 24 24">
         <polyline points="16 18 22 12 16 6" />
         <polyline points="8 6 2 12 8 18" />
@@ -2076,11 +2237,18 @@ export function App() {
 
           <GuideSection
             title="They can connect to external services"
-            body="Railcode apps can securely connect to your SaaS services so you can manage refunds, send emails, view data, and anything else you need."
+            body="Railcode apps can securely connect to your SaaS services so you can manage refunds, sync tickets, enrich records, and anything else you need."
           >
             <ConnectorsCard />
           </GuideSection>
 
+          <GuideSection
+            title="They can send email"
+            body="Send transactional email through the Railcode gateway without putting provider credentials in browser code."
+          >
+            <EmailCard />
+          </GuideSection>
+
           <GuideSection
             title="They can use AI"
             body="Build AI-native apps that use LLMs to enable powerful workflows."
@@ -3101,6 +3269,41 @@ th:first-child {
   }
 }
 
+/* ---------- email card ---------- */
+
+.email-form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+}
+
+.email-form .field {
+  width: 100%;
+}
+
+.email-state {
+  margin-top: var(--space-4);
+  padding: 12px 14px;
+  border: 1px solid var(--line);
+  border-radius: var(--radius-md);
+  background: var(--bg-inset);
+}
+
+.email-state .result-status {
+  margin-bottom: 6px;
+}
+
+.email-note {
+  color: var(--ink-3);
+  font-size: 12.5px;
+  line-height: 1.55;
+  overflow-wrap: anywhere;
+}
+
+.email-note.is-error {
+  color: #b42318;
+}
+
 /* ---------- reveal + action tooltips ---------- */
 
 .reveal {
@@ -4102,7 +4305,7 @@ List options:
 
 Query options:
   --connection <name>                    Connector to query (default: default)
-  --engine <postgres|mysql>              Engine override (inferred from --connection otherwise)
+  --engine <postgres|bigquery|turso>      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
@@ -4932,9 +5135,10 @@ class CliError extends Error {
 // dev — local development server (`railcode dev`)
 //
 // Serves the app on a single loopback origin and emulates the /_api/* data plane:
-// identity is synthetic, KV + files live on local disk. llm/sql/queries/connectors/email
-// proxy to the real instance as the signed-in user (their token + org grants) via the
-// org/user-scoped routes — no deploy needed. Mirrors railcode-core's dev.
+// identity is synthetic, KV + files live on local disk (isolated per storage scope —
+// shared/user/role — so `db.user`/`files.role(uuid)` behave like prod). llm/sql/queries/
+// connectors/email proxy to the real instance as the signed-in user (their token + org
+// grants) via the org/user-scoped routes — no deploy needed. Mirrors railcode-core's dev.
 // ---------------------------------------------------------------------------
 const DEFAULT_DEV_PORT = 7331;
 const DEFAULT_ASSET_PORT = 5173;
@@ -4971,8 +5175,9 @@ async function commandDev(args) {
         app: manifest.app,
         root: plan.root,
         sdkPath,
-        kv: new DevKvStore(join(stateDir, "kv.json")),
-        files: new DevFileStore(stateDir),
+        stateDir,
+        kvStores: new Map(),
+        fileStores: new Map(),
         port: requestedPort,
         config,
     };
@@ -5375,15 +5580,21 @@ class DevKvStore {
 }
 // ── local file store (bytes on disk, metadata in files.json) ──────────────────
 class DevFileStore {
-    dir;
-    constructor(dir) {
-        this.dir = dir;
+    blobRoot;
+    metaFile;
+    // Scope-aware, mirroring the backend's physical layout: shared keeps the legacy
+    // `files/` blob dir + `files.json` meta (byte-compatible with pre-scopes dev state);
+    // user/role nest under a per-scope blob dir + meta so namespaces never collide.
+    constructor(dir, scopeSlug) {
+        this.blobRoot = scopeSlug ? join(dir, `files-${scopeSlug}`) : join(dir, "files");
+        this.metaFile = scopeSlug ? join(dir, `files.${scopeSlug}.json`) : join(dir, "files.json");
+        mkdirSync(this.blobRoot, { recursive: true });
     }
     metaPath() {
-        return join(this.dir, "files.json");
+        return this.metaFile;
     }
     blobPath(name) {
-        return join(this.dir, "files", encodeURIComponent(name));
+        return join(this.blobRoot, encodeURIComponent(name));
     }
     readMeta() {
         const p = this.metaPath();
@@ -5453,6 +5664,10 @@ async function handleLocalApi(ctx, req, res, url) {
         sendJson(res, 200, [appUserEnvelope()]);
         return;
     }
+    if (path === "/roles") {
+        sendJson(res, 200, []);
+        return;
+    }
     if (path === "/config/design-system") {
         await handleDevDesignSystem(ctx, res);
         return;
@@ -5482,7 +5697,79 @@ async function handleLocalApi(ctx, req, res, url) {
     }
     sendJson(res, 404, { detail: "not found" });
 }
+// role/user selectors are UUIDs on the backend (it resolves them to FK ids). Enforce
+// the same here so a selector can NEVER reach the filesystem as a path segment — the
+// slug feeds kv.<slug>.json / files-<slug>/, so an unvalidated "../.." would traverse
+// out of the dev state dir. UUIDs contain only hex + hyphens, so this closes it.
+const DEV_UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+function resolveDevScope(url) {
+    const scope = (url.searchParams.get("scope") || "shared").toLowerCase();
+    const role = url.searchParams.get("role");
+    const user = url.searchParams.get("user");
+    if (scope === "shared") {
+        if (role || user) {
+            return { ok: false, status: 400, detail: "shared scope takes no role or user selector" };
+        }
+        return { ok: true, scope: { key: "shared", slug: "shared" } };
+    }
+    if (scope === "user") {
+        if (role)
+            return { ok: false, status: 400, detail: "user scope takes no role selector" };
+        if (user !== null && !DEV_UUID_RE.test(user)) {
+            return { ok: false, status: 400, detail: "malformed user id" };
+        }
+        const uuid = user || DEV_USER_UUID;
+        return { ok: true, scope: { key: `user:${uuid}`, slug: `users-${uuid}` } };
+    }
+    if (scope === "role") {
+        if (user)
+            return { ok: false, status: 400, detail: "role scope takes no user selector" };
+        if (!role)
+            return { ok: false, status: 400, detail: "role scope requires a role id" };
+        if (!DEV_UUID_RE.test(role))
+            return { ok: false, status: 400, detail: "malformed role id" };
+        return { ok: true, scope: { key: `role:${role}`, slug: `roles-${role}` } };
+    }
+    return { ok: false, status: 400, detail: `invalid scope: ${scope}` };
+}
+function kvForScope(ctx, scope) {
+    let store = ctx.kvStores.get(scope.key);
+    if (!store) {
+        const path = scope.key === "shared"
+            ? join(ctx.stateDir, "kv.json")
+            : join(ctx.stateDir, `kv.${scope.slug}.json`);
+        store = new DevKvStore(path);
+        ctx.kvStores.set(scope.key, store);
+    }
+    return store;
+}
+function filesForScope(ctx, scope) {
+    let store = ctx.fileStores.get(scope.key);
+    if (!store) {
+        store = new DevFileStore(ctx.stateDir, scope.key === "shared" ? undefined : scope.slug);
+        ctx.fileStores.set(scope.key, store);
+    }
+    return store;
+}
+// Re-attach the request's scope selectors to a same-origin /_api URL (the local-proxy
+// blob upload URL, download URLs) so the follow-up call resolves the identical scope —
+// mirrors the backend's _scoped_url.
+function scopeQuerySuffix(url) {
+    const parts = [];
+    for (const k of ["scope", "role", "user"]) {
+        const v = url.searchParams.get(k);
+        if (v)
+            parts.push(`${k}=${encodeURIComponent(v)}`);
+    }
+    return parts.length ? `&${parts.join("&")}` : "";
+}
 async function handleKv(ctx, req, res, path, url) {
+    const resolved = resolveDevScope(url);
+    if (!resolved.ok) {
+        sendJson(res, resolved.status, { detail: resolved.detail });
+        return;
+    }
+    const kv = kvForScope(ctx, resolved.scope);
     // path: /kv/{collection} | /kv/{collection}/{key...}
     const rest = path.slice("/kv/".length);
     const slash = rest.indexOf("/");
@@ -5502,7 +5789,7 @@ async function handleKv(ctx, req, res, path, url) {
             return;
         }
         try {
-            const records = ctx.kv.records(collection);
+            const records = kv.records(collection);
             const params = parseKvParams(url);
             if (url.searchParams.get("count") === "true") {
                 sendJson(res, 200, { count: kvCount(records, params) });
@@ -5520,7 +5807,7 @@ async function handleKv(ctx, req, res, path, url) {
         return;
     }
     if (req.method === "GET") {
-        const rec = ctx.kv.get(collection, key);
+        const rec = kv.get(collection, key);
         if (!rec)
             sendJson(res, 404, { detail: "Key not found" });
         else
@@ -5541,11 +5828,11 @@ async function handleKv(ctx, req, res, path, url) {
             sendJson(res, 413, { detail: "Value too large" });
             return;
         }
-        sendJson(res, 200, ctx.kv.put(collection, key, payload.value));
+        sendJson(res, 200, kv.put(collection, key, payload.value));
         return;
     }
     if (req.method === "DELETE") {
-        ctx.kv.delete(collection, key);
+        kv.delete(collection, key);
         sendStatus(res, 204);
         return;
     }
@@ -5583,8 +5870,44 @@ function parseKvParams(url) {
     };
 }
 async function handleFiles(ctx, req, res, path, url) {
+    const resolved = resolveDevScope(url);
+    if (!resolved.ok) {
+        sendJson(res, resolved.status, { detail: resolved.detail });
+        return;
+    }
+    const files = filesForScope(ctx, resolved.scope);
+    const scopeSuffix = scopeQuerySuffix(url);
     if (path === "/files" && req.method === "GET") {
-        sendJson(res, 200, { items: ctx.files.list() });
+        sendJson(res, 200, { items: files.list() });
+        return;
+    }
+    if (path === "/files/urls" && req.method === "POST") {
+        const body = await readBody(req);
+        let payload;
+        try {
+            payload = JSON.parse(body.toString("utf8") || "{}");
+        }
+        catch {
+            sendJson(res, 400, { detail: "invalid JSON body" });
+            return;
+        }
+        const names = Array.isArray(payload.names)
+            ? payload.names.filter((n) => typeof n === "string")
+            : [];
+        // Local proxy: download URLs carry the scope so a later GET re-resolves it.
+        const scopeQuery = scopeSuffix ? `?${scopeSuffix.slice(1)}` : "";
+        const items = [];
+        const missing = [];
+        for (const name of [...new Set(names)]) {
+            const safe = devSafeName(name);
+            if (safe && files.get(safe)) {
+                items.push({ name, url: `/_api/files/${encodeURIComponent(safe)}${scopeQuery}`, expires_in: null });
+            }
+            else {
+                missing.push(name);
+            }
+        }
+        sendJson(res, 200, { items, missing });
         return;
     }
     if (path === "/files" && req.method === "POST") {
@@ -5602,10 +5925,12 @@ async function handleFiles(ctx, req, res, path, url) {
             sendJson(res, 400, { detail: "Invalid file name" });
             return;
         }
+        // The blob URL carries the scope selectors so the follow-up PUT lands in the
+        // same scope (mirrors the backend's _scoped_url on the proxy path).
         sendJson(res, 200, {
             mode: "proxy",
             method: "PUT",
-            url: `/_api/files/blob?name=${encodeURIComponent(safe)}`,
+            url: `/_api/files/blob?name=${encodeURIComponent(safe)}${scopeSuffix}`,
             object_key: safe,
             headers: {},
             expires_in: null,
@@ -5624,7 +5949,7 @@ async function handleFiles(ctx, req, res, path, url) {
             return;
         }
         const contentType = req.headers["content-type"] || "application/octet-stream";
-        sendJson(res, 200, ctx.files.put(safe, body, contentType));
+        sendJson(res, 200, files.put(safe, body, contentType));
         return;
     }
     if (path.startsWith("/files/")) {
@@ -5634,7 +5959,7 @@ async function handleFiles(ctx, req, res, path, url) {
             return;
         }
         if (req.method === "GET") {
-            const found = ctx.files.get(name);
+            const found = files.get(name);
             if (!found) {
                 sendJson(res, 404, { detail: "File not found" });
                 return;
@@ -5651,7 +5976,7 @@ async function handleFiles(ctx, req, res, path, url) {
             return;
         }
         if (req.method === "DELETE") {
-            ctx.files.delete(name);
+            files.delete(name);
             sendStatus(res, 204);
             return;
         }
@@ -5803,13 +6128,19 @@ async function handleDevDesignSystem(ctx, res) {
 // ── envelopes + http helpers ──────────────────────────────────────────────────
 function meEnvelope(ctx) {
     return {
-        user: { uuid: DEV_USER_UUID, name: "Local Dev", email: "dev@localhost" },
+        user: {
+            uuid: DEV_USER_UUID,
+            name: "Local Dev",
+            email: "dev@localhost",
+            is_admin: true,
+            roles: [],
+        },
         app: { uuid: DEV_APP_UUID, slug: ctx.app, name: titleCase(ctx.app) },
         org: { uuid: DEV_ORG_UUID, slug: "local", name: "Local" },
     };
 }
 function appUserEnvelope() {
-    return { uuid: DEV_USER_UUID, name: "Local Dev", email: "dev@localhost", role: "owner" };
+    return { uuid: DEV_USER_UUID, name: "Local Dev", email: "dev@localhost", is_admin: true };
 }
 function isLoopbackHost(host) {
     if (!host)
@@ -5843,6 +6174,12 @@ function devSafeName(name) {
         return null;
     if (name.split("/").some((seg) => seg === "" || seg === "." || seg === ".."))
         return null;
+    // `users`/`roles` are reserved as the first path segment (mirrors the backend's
+    // _safe_name): the user/role file subtrees nest under the shared prefix, so a
+    // shared-scope name beginning with them would alias another scope's object.
+    const first = name.split("/", 1)[0].toLowerCase();
+    if (first === "users" || first === "roles")
+        return null;
     return name;
 }
 function readBody(req) {

package/package.json

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

package/static/sdk.js

@@ -35,7 +35,7 @@
       padding:2px 6px; border-radius:4px; white-space:nowrap; align-self:start; margin-top:2px; }
     .k-sql { background:#1e3a5f; color:#7cc4ff; } .k-db { background:#3a2752; color:#c79bff; }
     .k-files { background:#13413c; color:#5fd6c4; } .k-llm { background:#4a2b16; color:#f6b26b; }
-    .k-me, .k-connections, .k-app-users { background:#2a2f38; color:#9aa4b2; }
+    .k-me, .k-connections, .k-app-users, .k-roles { background:#2a2f38; color:#9aa4b2; }
     .body { min-width:0; }
     code { font-family: ui-monospace, "SF Mono", Menlo, monospace; font-size:11.5px; color:#e6e8eb;
       word-break:break-word; display:block; line-height:1.45; }
@@ -54,7 +54,7 @@
       <button id="collapse">Hide \u203A</button>
     </header>
     <div class="log" id="log"></div>
-    <footer>Calls made via <code>postgres()</code>, <code>llm</code>, <code>db</code>, <code>files</code>, <code>me()</code>, <code>appUsers()</code></footer>
+    <footer>Calls made via <code>postgres()</code>, <code>llm</code>, <code>db</code>, <code>files</code>, <code>me()</code>, <code>appUsers()</code>, <code>roles()</code></footer>
   </div>`;
   function mount() {
     (document.body || document.documentElement).appendChild(host);
@@ -265,7 +265,7 @@
   var data = namespace();
   var postgres = namespace("postgres");
   var bigquery = namespace("bigquery");
-  var snowflake = namespace("snowflake");
+  var turso = namespace("turso");
   var dataConnectors = () => track("connections", "dataConnectors()", () => call("GET", "/connections"));
 
   // ../sdk/src/util.ts
@@ -277,9 +277,18 @@
   }
 
   // ../sdk/src/db.ts
+  function scopeParams(s) {
+    return { scope: s.scope, role: s.role };
+  }
+  function scopeLabel(s) {
+    if (s.scope === "user") return "db.user";
+    if (s.scope === "role") return `db.role(${q(s.role ?? "")})`;
+    return "db.shared";
+  }
   var Query = class {
-    constructor(collection) {
+    constructor(collection, scope) {
       this.collection = collection;
+      this.scope = scope;
       this._where = [];
     }
     where(field, op, value) {
@@ -309,11 +318,12 @@
         prefix: this._prefix,
         updated_since: this._since,
         updated_before: this._before,
+        ...scopeParams(this.scope),
         ...extra
       };
     }
     label(method) {
-      return `db.collection(${q(this.collection)}).${method}`;
+      return `${scopeLabel(this.scope)}.collection(${q(this.collection)}).${method}`;
     }
     async fetchPage(page, size) {
       const resp = await call("GET", `/kv/${encPath(this.collection)}`, {
@@ -340,16 +350,20 @@
     }
   };
   var Collection = class {
-    constructor(name) {
+    constructor(name, scope) {
       this.name = name;
+      this.scope = scope;
     }
     label(method) {
-      return `db.collection(${q(this.name)}).${method}`;
+      return `${scopeLabel(this.scope)}.collection(${q(this.name)}).${method}`;
     }
     /** The stored value for ``key``, or null if absent. */
     get(key) {
       return track("db", this.label(`get(${q(key)})`), async () => {
-        const record = await getOrNull(`/kv/${encPath(this.name)}/${encPath(key)}`);
+        const record = await getOrNull(
+          `/kv/${encPath(this.name)}/${encPath(key)}`,
+          scopeParams(this.scope)
+        );
         return record ? record.value : null;
       });
     }
@@ -357,7 +371,8 @@
     put(key, value) {
       return track("db", this.label(`put(${q(key)}, ${shorten(JSON.stringify(value), 40)})`), async () => {
         const record = await call("PUT", `/kv/${encPath(this.name)}/${encPath(key)}`, {
-          body: { value }
+          body: { value },
+          query: scopeParams(this.scope)
         });
         return record.value;
       });
@@ -366,18 +381,22 @@
       return track(
         "db",
         this.label(`delete(${q(key)})`),
-        () => call("DELETE", `/kv/${encPath(this.name)}/${encPath(key)}`)
+        () => call("DELETE", `/kv/${encPath(this.name)}/${encPath(key)}`, {
+          query: scopeParams(this.scope)
+        })
       );
     }
     /** All records in the collection (first page). */
     list() {
       return track("db", this.label("list()"), async () => {
-        const resp = await call("GET", `/kv/${encPath(this.name)}`);
+        const resp = await call("GET", `/kv/${encPath(this.name)}`, {
+          query: scopeParams(this.scope)
+        });
         return resp.items;
       });
     }
     query() {
-      return new Query(this.name);
+      return new Query(this.name, this.scope);
     }
     where(field, op, value) {
       return this.query().where(field, op, value);
@@ -386,8 +405,15 @@
       return this.query().prefix(value);
     }
   };
+  function namespace2(scope) {
+    return { collection: (name) => new Collection(name, scope) };
+  }
+  var shared = namespace2({});
   var db = {
-    collection: (name) => new Collection(name)
+    shared,
+    user: namespace2({ scope: "user" }),
+    role: (roleUuid) => namespace2({ scope: "role", role: roleUuid }),
+    collection: shared.collection
   };
 
   // ../sdk/src/design-system.ts
@@ -423,18 +449,41 @@
   var email = { send: send2 };
 
   // ../sdk/src/files.ts
+  var URL_EXPIRY_MARGIN_MS = 15e3;
+  var urlCache = /* @__PURE__ */ new Map();
+  function scopeParams2(s) {
+    return { scope: s.scope, role: s.role };
+  }
+  function scopeKey(s) {
+    if (s.scope === "user") return "user";
+    if (s.scope === "role") return `role:${s.role ?? ""}`;
+    return "shared";
+  }
+  function scopeLabel2(s) {
+    if (s.scope === "user") return "files.user";
+    if (s.scope === "role") return `files.role(${q(s.role ?? "")})`;
+    return "files.shared";
+  }
+  function cacheKey(s, name) {
+    return `${scopeKey(s)} ${name}`;
+  }
   function contentTypeOf(data2, explicit) {
     if (explicit) return explicit;
     if (data2 instanceof Blob && data2.type) return data2.type;
     return "application/octet-stream";
   }
-  function upload(name, data2, contentType) {
-    return track("files", `files.upload(${q(name)}, <blob>)`, () => doUpload(name, data2, contentType));
+  function upload(scope, name, data2, contentType) {
+    return track("files", `${scopeLabel2(scope)}.upload(${q(name)}, <blob>)`, async () => {
+      const result = await doUpload(scope, name, data2, contentType);
+      urlCache.delete(cacheKey(scope, name));
+      return result;
+    });
   }
-  async function doUpload(name, data2, contentType) {
+  async function doUpload(scope, name, data2, contentType) {
     const ct = contentTypeOf(data2, contentType);
     const target2 = await call("POST", "/files", {
-      body: { name, content_type: ct }
+      body: { name, content_type: ct },
+      query: scopeParams2(scope)
     });
     const headers = { "Content-Type": ct, ...target2.headers };
     if (target2.mode === "proxy") {
@@ -449,21 +498,79 @@
     }
     const resp = await fetch(target2.url, { method: target2.method, body: data2, headers });
     if (!resp.ok) throw new Error(`upload failed: ${resp.status}`);
-    return call("POST", "/files/finalize", { body: { name } });
+    return call("POST", "/files/finalize", { body: { name }, query: scopeParams2(scope) });
   }
-  function url(name) {
-    return buildUrl(`/files/${encPath(name)}`);
+  function url(scope, name) {
+    return buildUrl(`/files/${encPath(name)}`, scopeParams2(scope));
   }
-  var list = () => track("files", "files.list()", async () => {
-    const resp = await call("GET", "/files");
-    return resp.items;
-  });
-  var remove = (name) => track("files", `files.delete(${q(name)})`, () => call("DELETE", `/files/${encPath(name)}`));
-  var files = { upload, url, list, delete: remove };
+  async function urls(scope, names) {
+    return track("files", `${scopeLabel2(scope)}.urls(<${names.length} names>)`, async () => {
+      const unique = [...new Set(names)];
+      const now = Date.now();
+      const items = /* @__PURE__ */ new Map();
+      const unresolved = [];
+      for (const name of unique) {
+        const cached = urlCache.get(cacheKey(scope, name));
+        if (cached && cached.expiresAt > now + URL_EXPIRY_MARGIN_MS) items.set(name, cached.item);
+        else {
+          urlCache.delete(cacheKey(scope, name));
+          unresolved.push(name);
+        }
+      }
+      let missing = [];
+      if (unresolved.length) {
+        const resolved = await call("POST", "/files/urls", {
+          body: { names: unresolved },
+          query: scopeParams2(scope)
+        });
+        missing = resolved.missing;
+        for (const item of resolved.items) {
+          const normalized = { ...item, url: new URL(item.url, location.origin).toString() };
+          const expiresAt = item.expires_in === null ? Number.POSITIVE_INFINITY : now + item.expires_in * 1e3;
+          urlCache.set(cacheKey(scope, item.name), { item: normalized, expiresAt });
+          items.set(item.name, normalized);
+        }
+      }
+      return { items: unique.flatMap((name) => items.has(name) ? [items.get(name)] : []), missing };
+    });
+  }
+  function list(scope) {
+    return track("files", `${scopeLabel2(scope)}.list()`, async () => {
+      const resp = await call("GET", "/files", { query: scopeParams2(scope) });
+      return resp.items;
+    });
+  }
+  function remove(scope, name) {
+    return track("files", `${scopeLabel2(scope)}.delete(${q(name)})`, async () => {
+      await call("DELETE", `/files/${encPath(name)}`, { query: scopeParams2(scope) });
+      urlCache.delete(cacheKey(scope, name));
+    });
+  }
+  function fileNamespace(scope) {
+    return {
+      upload: (name, data2, contentType) => upload(scope, name, data2, contentType),
+      url: (name) => url(scope, name),
+      urls: (names) => urls(scope, names),
+      list: () => list(scope),
+      delete: (name) => remove(scope, name)
+    };
+  }
+  var shared2 = fileNamespace({});
+  var files = {
+    shared: shared2,
+    user: fileNamespace({ scope: "user" }),
+    role: (roleUuid) => fileNamespace({ scope: "role", role: roleUuid }),
+    upload: shared2.upload,
+    url: shared2.url,
+    urls: shared2.urls,
+    list: shared2.list,
+    delete: shared2.delete
+  };
 
   // ../sdk/src/identity.ts
   var me = () => track("me", "me()", () => call("GET", "/me"));
   var appUsers = () => track("app-users", "appUsers()", () => call("GET", "/app-users"));
+  var roles = () => track("roles", "roles()", () => call("GET", "/roles"));
 
   // ../sdk/src/llm.ts
   function label2(method, input, opts = {}) {
@@ -589,6 +696,7 @@
   target.files = files;
   target.me = me;
   target.appUsers = appUsers;
+  target.roles = roles;
   target.designSystem = designSystem;
   target.email = email;
   target.llm = llm;
@@ -596,7 +704,7 @@
   target.data = data;
   target.postgres = postgres;
   target.bigquery = bigquery;
-  target.snowflake = snowflake;
+  target.turso = turso;
   target.dataConnectors = dataConnectors;
   target.connector = connector;
   target.serviceConnectors = serviceConnectors;