railcode 0.1.21 → 0.1.23

package/dist/index.js

@@ -16,6 +16,9 @@ import { QueryCmdError, paramSignature, parseParamDecls, parseRunParams, pickAut
 import { APP_MANIFEST_NAME, ManifestParseError, documentOperations, parseManifestYaml, renderManifestDeployOutcome, renderManifestSummary, } from "./manifest.js";
 import { ConnectorError, buildConnectorRequest, connectorOpenapiOutput, connectorTable, parseConnectorOption, parseMethodOption, pickConnectorBody, proxyExitCode, renderConnectorDocs, renderProxyResponse, } from "./connectors.js";
 import { llmModelTable, llmProviderTable } from "./llm.js";
+import { OrgAdminError, appTable, parseAccessMode, parseAssignableRole, parseGrantSubject, parseMemberList, parseResourceIds, parseResourceType, grantSubjectLabel, grantTable, memberTable, renderAppAccess, renderEffective, resolveAppRef, resolveMemberRef, resolveRoleRef, roleTable, } from "./orgadmin.js";
+import { ObservabilityError, buildLogQuery, logTable, parseLimit, parseRange, renderAnalytics, resolveLogStream, validateLogSource, validateLogStatus, } from "./observability.js";
+import { ConnectionAdminError, buildConnectionCreateBody, buildServiceConnectorCreateBody, connectionTable, nativeConnectorTable, parseAuthType, parseConnectionEngine, parseJsonObject, parseMethodList, resolveConnectionRef, resolveServiceConnectorRef, serviceConnectorAdminTable, } from "./connections.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -40,11 +43,20 @@ Usage:
   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)
-  railcode connector <list|docs|fetch> ...  List connectors / show API docs / proxy a call
+  railcode connector <list|docs|fetch|create|native|enable|delete> ...
+                                      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 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
+  railcode members <list|set-role|remove|add> ...  Org members + system roles (list: any; mutations: admin)
+  railcode roles <list|create|update|delete|add-member|remove-member|grants|grant|revoke|materialize|effective|catalog> ...
+                                      Manage org roles + the granular grants table (admin)
+  railcode apps <list|show|access|set-access|transfer|delete> ...  Manage apps + access policy
+  railcode analytics <app> [--range 7d|30d|90d]  Per-app pageview analytics (admin/owner)
+  railcode logs <connector|service-connector|llm|email|agent> [filters]
+                                      Read org observability logs (admin)
   railcode --version
   railcode --help
 
@@ -93,9 +105,32 @@ async function main() {
         case "connectors":
             await commandConnector(args);
             return;
+        case "connection":
+        case "connections":
+            await commandConnections(args);
+            return;
         case "llm":
             await commandLlm(args);
             return;
+        case "member":
+        case "members":
+            await commandMembers(args);
+            return;
+        case "role":
+        case "roles":
+            await commandRoles(args);
+            return;
+        case "app":
+        case "apps":
+            await commandApps(args);
+            return;
+        case "analytics":
+            await commandAnalytics(args);
+            return;
+        case "logs":
+        case "log":
+            await commandLogs(args);
+            return;
         case "manifest":
             await commandManifest(args);
             return;
@@ -983,13 +1018,27 @@ 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;
@@ -4686,9 +4735,20 @@ Usage:
   railcode connector fetch <path> --connector <name> [opts]
                                                  Proxy one HTTP call through a connector
 
+Admin (service-connector:manage):
+  railcode connector native                     List native presets + enabled state
+  railcode connector enable <key> --credentials '{...}'
+                                                 One-click enable/rotate a native preset
+  railcode connector create --name <n> --base-url <url> [--auth-type <t>]
+                        [--auth-config '{...}'] [--methods GET,POST] [--description <d>] [--disabled]
+                                                 Create/replace a custom connector
+  railcode connector delete <name|uuid>          Delete a service connector
+
 Aliases: connector = connectors; list = ls, connectors; docs = doc; fetch = request.
 
 List options:
+  --admin                                Manage view: base_url, credential + enabled
+                                         state, native key (service-connector:manage)
   --json                                 Print the raw connector array
 
 Docs options:
@@ -4723,6 +4783,19 @@ async function commandConnector(args) {
             case "request":
                 await commandConnectorFetch(args);
                 return;
+            case "native":
+                await commandConnectorNative(args);
+                return;
+            case "enable":
+                await commandConnectorEnable(args);
+                return;
+            case "create":
+                await commandConnectorCreate(args);
+                return;
+            case "delete":
+            case "rm":
+                await commandConnectorDelete(args);
+                return;
             case "":
             case "help":
                 console.log(CONNECTOR_HELP);
@@ -4733,17 +4806,98 @@ async function commandConnector(args) {
     }
     catch (error) {
         // Validation helpers throw ConnectorError; surface them as usage errors (exit 2).
-        if (error instanceof ConnectorError)
+        if (error instanceof ConnectorError || error instanceof ConnectionAdminError) {
             throw new CliError(error.message, 2);
+        }
         throw error;
     }
 }
-async function commandConnectorList(args) {
+// Admin list of service connectors (with uuids, for delete/update) — distinct from
+// the member-facing `connector list`, which reads the caller-scoped data plane.
+async function fetchServiceConnectorsAdmin(config) {
+    return (await authedJson(config, `/api/organizations/${config.orgUuid}/service-connectors`, "List service connectors"));
+}
+async function commandConnectorNative(args) {
     assertKnownConnectorOptions(args, ["json", "apiUrl"]);
+    const config = requireLogin(args);
+    const natives = (await authedJson(config, `/api/organizations/${config.orgUuid}/service-connectors/native`, "List native presets"));
+    if (args.options.json) {
+        console.log(JSON.stringify(natives, null, 2));
+        return;
+    }
+    console.log(nativeConnectorTable(natives));
+}
+async function commandConnectorEnable(args) {
+    assertKnownConnectorOptions(args, ["credentials", "credentialsFile", "apiUrl"]);
+    const key = args.rest[1];
+    if (!key) {
+        throw new CliError("Usage: railcode connector enable <key> --credentials '{...}'. See `railcode connector native`.", 2);
+    }
+    const credentials = readJsonObjectOption(args, "credentials", "credentialsFile", "--credentials");
+    const config = requireLogin(args);
+    const created = (await authedJson(config, `/api/organizations/${config.orgUuid}/service-connectors/native/${encodeURIComponent(key)}/enable`, `Enable native connector "${key}"`, jsonBody({ credentials })));
+    console.log(`Native connector "${created.name}" enabled.`);
+}
+async function commandConnectorCreate(args) {
+    assertKnownConnectorOptions(args, [
+        "name",
+        "baseUrl",
+        "authType",
+        "authConfig",
+        "authConfigFile",
+        "description",
+        "methods",
+        "disabled",
+        "apiUrl",
+    ]);
+    const authType = parseAuthType(optionString(args, "authType"));
+    const authConfig = authType === "none"
+        ? {}
+        : readJsonObjectOption(args, "authConfig", "authConfigFile", "--auth-config");
+    const body = buildServiceConnectorCreateBody({
+        name: optionString(args, "name"),
+        baseUrl: optionString(args, "baseUrl"),
+        authType,
+        authConfig,
+        description: optionString(args, "description"),
+        allowedMethods: parseMethodList(optionString(args, "methods")),
+        enabled: args.options.disabled !== true,
+    });
+    const config = requireLogin(args);
+    const created = (await authedJson(config, `/api/organizations/${config.orgUuid}/service-connectors`, "Create service connector", jsonBody(body)));
+    console.log(`Service connector "${created.name}" → ${created.base_url}.`);
+}
+async function commandConnectorDelete(args) {
+    assertKnownConnectorOptions(args, ["apiUrl"]);
+    const ref = args.rest[1];
+    if (!ref)
+        throw new CliError("Usage: railcode connector delete <name|uuid>", 2);
+    const config = requireLogin(args);
+    const conn = resolveServiceConnectorRef(await fetchServiceConnectorsAdmin(config), ref);
+    await authedNoContent(config, `/api/organizations/${config.orgUuid}/service-connectors/${conn.uuid}`, `Delete service connector "${conn.name}"`, { method: "DELETE" });
+    console.log(`Service connector "${conn.name}" deleted.`);
+}
+async function commandConnectorList(args) {
+    assertKnownConnectorOptions(args, ["json", "admin", "apiUrl"]);
     if (args.rest.length > 1) {
         throw new CliError(`railcode connector list takes no arguments (got "${args.rest[1]}").`, 2);
     }
     const config = requireLogin(args);
+    // --admin: the manage view (base_url, credential + enabled state, native key),
+    // gated by service-connector:manage. Default is the caller-facing list.
+    if (args.options.admin === true) {
+        const connectors = await fetchServiceConnectorsAdmin(config);
+        if (args.options.json) {
+            console.log(JSON.stringify(connectors, null, 2));
+            return;
+        }
+        if (connectors.length === 0) {
+            console.log("No service connectors configured for this organization.");
+            return;
+        }
+        console.log(serviceConnectorAdminTable(connectors));
+        return;
+    }
     const connectors = await fetchServiceConnectors(config);
     if (args.options.json) {
         console.log(JSON.stringify(connectors, null, 2));
@@ -4940,6 +5094,859 @@ function assertKnownLlmOptions(args, allowed) {
     }
 }
 // ---------------------------------------------------------------------------
+// Shared admin helpers (members / roles / apps / analytics / logs / connections)
+//
+// All of these hit the org-scoped `/api/organizations/{org}/...` management APIs
+// with the personal token. They mirror the web console's admin surfaces so an
+// operator can do everything from the CLI. Most are owner/admin-gated server-side
+// (403 for plain members); a couple (apps list/show/access of your own apps) work
+// for any member per the app access policy.
+// ---------------------------------------------------------------------------
+function rejectUnknownOptions(args, allowed, cmd, help) {
+    for (const key of Object.keys(args.options)) {
+        if (!allowed.includes(key)) {
+            throw new CliError(`Unknown option --${camelToKebab(key)} for \`railcode ${cmd}\`.\n\n${help}`, 2);
+        }
+    }
+}
+// GET/POST/PATCH that returns a parsed JSON body (drops a rejected token first).
+async function authedJson(config, path, action, init = {}) {
+    const resp = await authedFetch(config, path, init);
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    return readJsonOrThrow(resp, action);
+}
+// A 204/no-body mutation (DELETE, membership add/remove). Surfaces the server
+// detail on any non-2xx.
+async function authedNoContent(config, path, action, init = {}) {
+    const resp = await authedFetch(config, path, init);
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    if (!resp.ok) {
+        throw new CliError(`${action} failed (${resp.status}): ${await errorDetail(resp)}`, 1);
+    }
+}
+function jsonBody(body) {
+    return {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    };
+}
+async function fetchMembers(config) {
+    return (await authedJson(config, `/api/organizations/${config.orgUuid}/members`, "List members"));
+}
+async function fetchApps(config) {
+    return (await authedJson(config, `/api/organizations/${config.orgUuid}/apps`, "List apps"));
+}
+async function fetchPermissions(config) {
+    return (await authedJson(config, `/api/organizations/${config.orgUuid}/permissions`, "List roles + grants"));
+}
+// Resolve a subject spec (org | role:x | user:x) to the API's {subject_type,
+// subject_uuid} shape, resolving names/emails against the org's roles + members.
+async function resolveGrantSubject(config, spec) {
+    if (spec.kind === "org")
+        return { subject_type: "org", subject_uuid: null };
+    if (spec.kind === "role") {
+        const { roles } = await fetchPermissions(config);
+        return { subject_type: "role", subject_uuid: resolveRoleRef(roles, spec.ref).uuid };
+    }
+    const members = await fetchMembers(config);
+    return { subject_type: "user", subject_uuid: resolveMemberRef(members, spec.ref).uuid };
+}
+// ---------------------------------------------------------------------------
+// members — org members + system roles (`railcode members`)
+// ---------------------------------------------------------------------------
+const MEMBERS_HELP = `railcode members — org members + system roles
+
+Usage:
+  railcode members list                        List everyone in your org (any member)
+  railcode members set-role <email|uuid> --role admin|member
+                                               Change a member's system role (admin)
+  railcode members remove <email|uuid>         Detach a member from the org (admin)
+  railcode members add --email <e> --name <n> --password <p> --role admin|member
+                        [--no-password-change]  Provision a member (admin; self-hosted only)
+
+list is available to any member; set-role/remove/add require admin.
+
+Options:
+  --json                                 Print raw JSON (list)
+`;
+async function commandMembers(args) {
+    try {
+        const sub = args.rest[0] ?? "";
+        switch (sub) {
+            case "list":
+            case "ls":
+                await commandMembersList(args);
+                return;
+            case "set-role":
+                await commandMembersSetRole(args);
+                return;
+            case "remove":
+            case "rm":
+                await commandMembersRemove(args);
+                return;
+            case "add":
+            case "provision":
+                await commandMembersAdd(args);
+                return;
+            case "":
+            case "help":
+                console.log(MEMBERS_HELP);
+                return;
+            default:
+                throw new CliError(`Unknown members command: ${sub}\n\n${MEMBERS_HELP}`, 2);
+        }
+    }
+    catch (error) {
+        if (error instanceof OrgAdminError)
+            throw new CliError(error.message, 2);
+        throw error;
+    }
+}
+async function commandMembersList(args) {
+    rejectUnknownOptions(args, ["json", "apiUrl"], "members", MEMBERS_HELP);
+    const config = requireLogin(args);
+    const members = await fetchMembers(config);
+    if (args.options.json) {
+        console.log(JSON.stringify(members, null, 2));
+        return;
+    }
+    if (members.length === 0) {
+        console.log("No members (that shouldn't happen).");
+        return;
+    }
+    console.log(memberTable(members));
+}
+async function commandMembersSetRole(args) {
+    rejectUnknownOptions(args, ["role", "apiUrl"], "members", MEMBERS_HELP);
+    const ref = args.rest[1];
+    if (!ref)
+        throw new CliError("Usage: railcode members set-role <email|uuid> --role admin|member", 2);
+    const role = parseAssignableRole(optionString(args, "role"));
+    const config = requireLogin(args);
+    const member = resolveMemberRef(await fetchMembers(config), ref);
+    const updated = (await authedJson(config, `/api/organizations/${config.orgUuid}/members/${member.uuid}`, "Update member role", { method: "PATCH", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ role }) }));
+    console.log(`${updated.email} is now ${updated.role}.`);
+}
+async function commandMembersRemove(args) {
+    rejectUnknownOptions(args, ["apiUrl"], "members", MEMBERS_HELP);
+    const ref = args.rest[1];
+    if (!ref)
+        throw new CliError("Usage: railcode members remove <email|uuid>", 2);
+    const config = requireLogin(args);
+    const member = resolveMemberRef(await fetchMembers(config), ref);
+    await authedNoContent(config, `/api/organizations/${config.orgUuid}/members/${member.uuid}`, `Remove member ${member.email}`, { method: "DELETE" });
+    console.log(`Removed ${member.email} from the organization.`);
+}
+async function commandMembersAdd(args) {
+    rejectUnknownOptions(args, ["email", "name", "password", "role", "noPasswordChange", "apiUrl"], "members", MEMBERS_HELP);
+    const email = optionString(args, "email");
+    const name = optionString(args, "name");
+    const password = optionString(args, "password");
+    const roleOpt = optionString(args, "role");
+    if (!email || !name || !password || !roleOpt) {
+        throw new CliError("railcode members add requires --email, --name, --password and --role.\n\n" + MEMBERS_HELP, 2);
+    }
+    const role = parseAssignableRole(roleOpt);
+    const body = { email, name, password, role };
+    if (args.options.noPasswordChange === true)
+        body.must_change_password = false;
+    const config = requireLogin(args);
+    const created = (await authedJson(config, `/api/organizations/${config.orgUuid}/members`, "Provision member", jsonBody(body)));
+    console.log(`Provisioned ${created.email} (${created.role}).`);
+}
+// ---------------------------------------------------------------------------
+// roles — org roles + the granular grants table (`railcode roles`)
+// ---------------------------------------------------------------------------
+const ROLES_HELP = `railcode roles — org roles + the granular grants table (admin)
+
+Roles:
+  railcode roles list                          List org roles (with member counts)
+  railcode roles create --name <n> [--description <d>]
+  railcode roles update <role> [--name <n>] [--description <d>]
+  railcode roles delete <role>
+  railcode roles add-member <role> <email|uuid>
+  railcode roles remove-member <role> <email|uuid>
+
+Grants (additive permissions):
+  railcode roles grants                         List every grant row
+  railcode roles grant --subject <org|role:X|user:X> --resource <type> --ids <a,b>
+  railcode roles revoke <grant_id>
+  railcode roles materialize --subject <...> --resource <type>
+                                                Expand a "*" wildcard into explicit rows
+  railcode roles effective <email|uuid>         A member's computed effective access
+  railcode roles catalog                        Grantable resources (apps/connectors/…)
+
+<role> is a role name or UUID. --resource ∈ app|llm|email|sc_endpoint|connector|saved_query|agent.
+
+Options:
+  --json                                 Print raw JSON (list/grants/catalog)
+`;
+async function commandRoles(args) {
+    try {
+        const sub = args.rest[0] ?? "";
+        switch (sub) {
+            case "list":
+            case "ls":
+                await commandRolesList(args);
+                return;
+            case "create":
+                await commandRolesCreate(args);
+                return;
+            case "update":
+                await commandRolesUpdate(args);
+                return;
+            case "delete":
+            case "rm":
+                await commandRolesDelete(args);
+                return;
+            case "add-member":
+                await commandRolesMember(args, true);
+                return;
+            case "remove-member":
+                await commandRolesMember(args, false);
+                return;
+            case "grants":
+                await commandRolesGrants(args);
+                return;
+            case "grant":
+                await commandRolesGrant(args);
+                return;
+            case "revoke":
+                await commandRolesRevoke(args);
+                return;
+            case "materialize":
+                await commandRolesMaterialize(args);
+                return;
+            case "effective":
+                await commandRolesEffective(args);
+                return;
+            case "catalog":
+                await commandRolesCatalog(args);
+                return;
+            case "":
+            case "help":
+                console.log(ROLES_HELP);
+                return;
+            default:
+                throw new CliError(`Unknown roles command: ${sub}\n\n${ROLES_HELP}`, 2);
+        }
+    }
+    catch (error) {
+        if (error instanceof OrgAdminError)
+            throw new CliError(error.message, 2);
+        throw error;
+    }
+}
+async function commandRolesList(args) {
+    rejectUnknownOptions(args, ["json", "apiUrl"], "roles", ROLES_HELP);
+    const config = requireLogin(args);
+    const { roles } = await fetchPermissions(config);
+    if (args.options.json) {
+        console.log(JSON.stringify(roles, null, 2));
+        return;
+    }
+    if (roles.length === 0) {
+        console.log("No org roles defined. Create one: railcode roles create --name <name>.");
+        return;
+    }
+    console.log(roleTable(roles));
+}
+async function commandRolesCreate(args) {
+    rejectUnknownOptions(args, ["name", "description", "apiUrl"], "roles", ROLES_HELP);
+    const name = optionString(args, "name");
+    if (!name)
+        throw new CliError("railcode roles create requires --name.", 2);
+    const config = requireLogin(args);
+    const role = (await authedJson(config, `/api/organizations/${config.orgUuid}/roles`, "Create role", jsonBody({ name, description: optionString(args, "description") ?? "" })));
+    console.log(`Role "${role.name}" created (${role.uuid}).`);
+}
+async function commandRolesUpdate(args) {
+    rejectUnknownOptions(args, ["name", "description", "apiUrl"], "roles", ROLES_HELP);
+    const ref = args.rest[1];
+    if (!ref)
+        throw new CliError("Usage: railcode roles update <role> [--name <n>] [--description <d>]", 2);
+    const body = {};
+    const name = optionString(args, "name");
+    const description = optionString(args, "description");
+    if (name !== undefined)
+        body.name = name;
+    if (description !== undefined)
+        body.description = description;
+    if (Object.keys(body).length === 0) {
+        throw new CliError("Nothing to update. Pass --name and/or --description.", 2);
+    }
+    const config = requireLogin(args);
+    const role = resolveRoleRef((await fetchPermissions(config)).roles, ref);
+    const updated = (await authedJson(config, `/api/organizations/${config.orgUuid}/roles/${role.uuid}`, "Update role", { method: "PATCH", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) }));
+    console.log(`Role "${updated.name}" updated.`);
+}
+async function commandRolesDelete(args) {
+    rejectUnknownOptions(args, ["apiUrl"], "roles", ROLES_HELP);
+    const ref = args.rest[1];
+    if (!ref)
+        throw new CliError("Usage: railcode roles delete <role>", 2);
+    const config = requireLogin(args);
+    const role = resolveRoleRef((await fetchPermissions(config)).roles, ref);
+    await authedNoContent(config, `/api/organizations/${config.orgUuid}/roles/${role.uuid}`, `Delete role "${role.name}"`, { method: "DELETE" });
+    console.log(`Role "${role.name}" deleted (its memberships + grants were removed too).`);
+}
+async function commandRolesMember(args, add) {
+    rejectUnknownOptions(args, ["apiUrl"], "roles", ROLES_HELP);
+    const roleRef = args.rest[1];
+    const userRef = args.rest[2];
+    if (!roleRef || !userRef) {
+        throw new CliError(`Usage: railcode roles ${add ? "add-member" : "remove-member"} <role> <email|uuid>`, 2);
+    }
+    const config = requireLogin(args);
+    const role = resolveRoleRef((await fetchPermissions(config)).roles, roleRef);
+    const member = resolveMemberRef(await fetchMembers(config), userRef);
+    const base = `/api/organizations/${config.orgUuid}/roles/${role.uuid}/members`;
+    if (add) {
+        await authedNoContent(config, base, `Add ${member.email} to "${role.name}"`, jsonBody({ user_uuid: member.uuid }));
+        console.log(`Added ${member.email} to role "${role.name}".`);
+    }
+    else {
+        await authedNoContent(config, `${base}/${member.uuid}`, `Remove ${member.email} from "${role.name}"`, {
+            method: "DELETE",
+        });
+        console.log(`Removed ${member.email} from role "${role.name}".`);
+    }
+}
+async function commandRolesGrants(args) {
+    rejectUnknownOptions(args, ["json", "apiUrl"], "roles", ROLES_HELP);
+    const config = requireLogin(args);
+    const { roles, grants } = await fetchPermissions(config);
+    if (args.options.json) {
+        console.log(JSON.stringify(grants, null, 2));
+        return;
+    }
+    if (grants.length === 0) {
+        console.log("No grants configured.");
+        return;
+    }
+    const roleNames = new Map(roles.map((r) => [r.uuid, r.name]));
+    const members = await fetchMembers(config);
+    const userEmails = new Map(members.map((m) => [m.uuid, m.email]));
+    const apps = await fetchApps(config);
+    const appSlugs = new Map(apps.map((a) => [a.uuid, a.app_slug]));
+    console.log(grantTable(grants, roleNames, userEmails, appSlugs));
+}
+async function commandRolesGrant(args) {
+    rejectUnknownOptions(args, ["subject", "resource", "ids", "apiUrl"], "roles", ROLES_HELP);
+    const spec = parseGrantSubject(optionString(args, "subject"));
+    const resourceType = parseResourceType(optionString(args, "resource"));
+    const resourceRefs = parseResourceIds(optionString(args, "ids"));
+    const config = requireLogin(args);
+    const subject = await resolveGrantSubject(config, spec);
+    let resourceIds = resourceRefs;
+    if (resourceType === "app") {
+        if (resourceRefs.includes("*")) {
+            throw new CliError("Apps have no wildcard — grant them one by one.", 2);
+        }
+        const apps = await fetchApps(config);
+        resourceIds = resourceRefs.map((ref) => resolveAppRef(apps, ref).uuid);
+    }
+    const created = (await authedJson(config, `/api/organizations/${config.orgUuid}/permissions/grants`, "Create grant", jsonBody({ ...subject, resource_type: resourceType, resource_ids: resourceIds })));
+    if (created.length === 0) {
+        console.log("No new grants created (they already existed).");
+        return;
+    }
+    console.log(`Granted ${resourceType} [${resourceRefs.join(", ")}] (${created.length} row(s) added).`);
+}
+async function commandRolesRevoke(args) {
+    rejectUnknownOptions(args, ["apiUrl"], "roles", ROLES_HELP);
+    const id = args.rest[1];
+    if (!id || !/^\d+$/.test(id)) {
+        throw new CliError("Usage: railcode roles revoke <grant_id> (see `railcode roles grants`).", 2);
+    }
+    const config = requireLogin(args);
+    await authedNoContent(config, `/api/organizations/${config.orgUuid}/permissions/grants/${id}`, `Revoke grant ${id}`, { method: "DELETE" });
+    console.log(`Grant ${id} revoked.`);
+}
+async function commandRolesMaterialize(args) {
+    rejectUnknownOptions(args, ["subject", "resource", "apiUrl"], "roles", ROLES_HELP);
+    const spec = parseGrantSubject(optionString(args, "subject"));
+    const resourceType = parseResourceType(optionString(args, "resource"));
+    const config = requireLogin(args);
+    const subject = await resolveGrantSubject(config, spec);
+    const created = (await authedJson(config, `/api/organizations/${config.orgUuid}/permissions/grants/materialize`, "Materialize wildcard", jsonBody({ ...subject, resource_type: resourceType })));
+    console.log(`Materialized ${resourceType} wildcard into ${created.length} explicit grant(s).`);
+}
+async function commandRolesEffective(args) {
+    rejectUnknownOptions(args, ["json", "apiUrl"], "roles", ROLES_HELP);
+    const ref = args.rest[1];
+    if (!ref)
+        throw new CliError("Usage: railcode roles effective <email|uuid>", 2);
+    const config = requireLogin(args);
+    const member = resolveMemberRef(await fetchMembers(config), ref);
+    const eff = (await authedJson(config, `/api/organizations/${config.orgUuid}/permissions/effective/${member.uuid}`, "Effective access"));
+    if (args.options.json) {
+        console.log(JSON.stringify(eff, null, 2));
+        return;
+    }
+    console.log(renderEffective(eff, member.email));
+}
+async function commandRolesCatalog(args) {
+    rejectUnknownOptions(args, ["json", "apiUrl"], "roles", ROLES_HELP);
+    const config = requireLogin(args);
+    const catalog = (await authedJson(config, `/api/organizations/${config.orgUuid}/permissions/catalog`, "Grant catalog"));
+    if (args.options.json) {
+        console.log(JSON.stringify(catalog, null, 2));
+        return;
+    }
+    const line = (label, items) => console.log(`${label}: ${items.length ? items.join(", ") : "-"}`);
+    line("apps", catalog.apps.map((a) => a.app_slug));
+    line("connections", catalog.connections.map((c) => c.name));
+    line("service_connectors", catalog.service_connectors.map((c) => c.name));
+    line("saved_queries", catalog.saved_queries.map((q) => q.name));
+    line("agents", catalog.agents.map((a) => a.name));
+}
+// ---------------------------------------------------------------------------
+// apps — app management + access policy (`railcode apps`)
+// ---------------------------------------------------------------------------
+const APPS_HELP = `railcode apps — apps + access policy
+
+Usage:
+  railcode apps list                           List apps you can see
+  railcode apps show <app>                      Show one app's details
+  railcode apps access <app>                    Show an app's access policy + grants
+  railcode apps set-access <app> --mode organization|private|restricted
+                        [--members <email,email>]  Set the policy (members: restricted only)
+  railcode apps transfer <app> --to <email|uuid>  Transfer ownership
+  railcode apps delete <app> [--yes]            Delete an app (deploys + data, irreversible)
+
+<app> is an app slug or UUID. set-access/transfer/delete need manage rights
+(owner or org admin). delete prompts for confirmation on a TTY; pass --yes to skip
+(required in non-interactive sessions).
+
+Options:
+  --json                                 Print raw JSON
+  --yes                                  Skip the delete confirmation prompt
+`;
+async function commandApps(args) {
+    try {
+        const sub = args.rest[0] ?? "";
+        switch (sub) {
+            case "list":
+            case "ls":
+                await commandAppsList(args);
+                return;
+            case "show":
+            case "get":
+                await commandAppsShow(args);
+                return;
+            case "access":
+                await commandAppsAccess(args);
+                return;
+            case "set-access":
+                await commandAppsSetAccess(args);
+                return;
+            case "transfer":
+                await commandAppsTransfer(args);
+                return;
+            case "delete":
+            case "rm":
+                await commandAppsDelete(args);
+                return;
+            case "":
+            case "help":
+                console.log(APPS_HELP);
+                return;
+            default:
+                throw new CliError(`Unknown apps command: ${sub}\n\n${APPS_HELP}`, 2);
+        }
+    }
+    catch (error) {
+        if (error instanceof OrgAdminError)
+            throw new CliError(error.message, 2);
+        throw error;
+    }
+}
+async function commandAppsList(args) {
+    rejectUnknownOptions(args, ["json", "apiUrl"], "apps", APPS_HELP);
+    const config = requireLogin(args);
+    const apps = await fetchApps(config);
+    if (args.options.json) {
+        console.log(JSON.stringify(apps, null, 2));
+        return;
+    }
+    if (apps.length === 0) {
+        console.log("No apps yet. Scaffold one: railcode init <app>.");
+        return;
+    }
+    console.log(appTable(apps));
+}
+async function commandAppsShow(args) {
+    rejectUnknownOptions(args, ["json", "apiUrl"], "apps", APPS_HELP);
+    const ref = args.rest[1];
+    if (!ref)
+        throw new CliError("Usage: railcode apps show <app>", 2);
+    const config = requireLogin(args);
+    const app = resolveAppRef(await fetchApps(config), ref);
+    const full = (await authedJson(config, `/api/organizations/${config.orgUuid}/apps/${app.uuid}`, "Get app"));
+    if (args.options.json) {
+        console.log(JSON.stringify(full, null, 2));
+        return;
+    }
+    const row = (label, value) => `  ${`${label}:`.padEnd(14)}${value}`;
+    console.log(`${full.app_slug} (${full.name})`);
+    console.log(row("uuid", String(full.uuid)));
+    console.log(row("status", String(full.status)));
+    console.log(row("access", String(full.access_mode)));
+    console.log(row("your role", full.your_role ?? "-"));
+    console.log(row("can manage", full.can_manage ? "yes" : "no"));
+    console.log(row("has manifest", full.has_manifest ? "yes" : "no"));
+    if (full.last_deployed_at)
+        console.log(row("deployed", String(full.last_deployed_at)));
+}
+async function commandAppsAccess(args) {
+    rejectUnknownOptions(args, ["json", "apiUrl"], "apps", APPS_HELP);
+    const ref = args.rest[1];
+    if (!ref)
+        throw new CliError("Usage: railcode apps access <app>", 2);
+    const config = requireLogin(args);
+    const app = resolveAppRef(await fetchApps(config), ref);
+    const access = (await authedJson(config, `/api/organizations/${config.orgUuid}/apps/${app.uuid}/access`, "Get app access"));
+    // App access has two sources: the app's own policy (mode + per-user grants,
+    // above) AND grant-substrate rows (`roles grant --resource app`, plus the
+    // access granted to apps/agents). The policy view alone is incomplete, so also
+    // surface any org_grants that open THIS app.
+    const { roles, grants } = await fetchPermissions(config);
+    const substrate = grants.filter((g) => g.resource_type === "app" && g.resource_id === app.uuid);
+    if (args.options.json) {
+        console.log(JSON.stringify({ ...access, grants: access.grants, org_grants: substrate }, null, 2));
+        return;
+    }
+    console.log(renderAppAccess(app.app_slug, access));
+    if (substrate.length > 0) {
+        const roleNames = new Map(roles.map((r) => [r.uuid, r.name]));
+        const members = await fetchMembers(config);
+        const userEmails = new Map(members.map((m) => [m.uuid, m.email]));
+        console.log("  also granted access via roles/grants:");
+        for (const g of substrate) {
+            console.log(`    ${grantSubjectLabel(g, roleNames, userEmails)}`);
+        }
+    }
+}
+async function commandAppsSetAccess(args) {
+    rejectUnknownOptions(args, ["mode", "members", "json", "apiUrl"], "apps", APPS_HELP);
+    const ref = args.rest[1];
+    if (!ref)
+        throw new CliError("Usage: railcode apps set-access <app> --mode <mode> [--members ...]", 2);
+    const mode = parseAccessMode(optionString(args, "mode"));
+    const memberRefs = parseMemberList(optionString(args, "members"));
+    if (mode !== "restricted" && memberRefs.length > 0) {
+        throw new CliError("--members only applies to --mode restricted.", 2);
+    }
+    const config = requireLogin(args);
+    const app = resolveAppRef(await fetchApps(config), ref);
+    let members = [];
+    if (mode === "restricted" && memberRefs.length > 0) {
+        const all = await fetchMembers(config);
+        members = memberRefs.map((r) => resolveMemberRef(all, r).uuid);
+    }
+    const access = (await authedJson(config, `/api/organizations/${config.orgUuid}/apps/${app.uuid}/access`, "Set app access", { method: "PUT", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ mode, members }) }));
+    if (args.options.json) {
+        console.log(JSON.stringify(access, null, 2));
+        return;
+    }
+    console.log(renderAppAccess(app.app_slug, access));
+}
+async function commandAppsTransfer(args) {
+    rejectUnknownOptions(args, ["to", "apiUrl"], "apps", APPS_HELP);
+    const ref = args.rest[1];
+    const to = optionString(args, "to");
+    if (!ref || !to)
+        throw new CliError("Usage: railcode apps transfer <app> --to <email|uuid>", 2);
+    const config = requireLogin(args);
+    const app = resolveAppRef(await fetchApps(config), ref);
+    const newOwner = resolveMemberRef(await fetchMembers(config), to);
+    await authedJson(config, `/api/organizations/${config.orgUuid}/apps/${app.uuid}/owner`, "Transfer app owner", { method: "PUT", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ user_uuid: newOwner.uuid }) });
+    console.log(`${app.app_slug} is now owned by ${newOwner.email}.`);
+}
+async function commandAppsDelete(args) {
+    rejectUnknownOptions(args, ["yes", "apiUrl"], "apps", APPS_HELP);
+    const ref = args.rest[1];
+    if (!ref)
+        throw new CliError("Usage: railcode apps delete <app>", 2);
+    const config = requireLogin(args);
+    const app = resolveAppRef(await fetchApps(config), ref);
+    if (args.options.yes !== true) {
+        if (!process.stdin.isTTY) {
+            throw new CliError("Pass --yes to delete an app in a non-interactive session.", 2);
+        }
+        const answer = await prompt(`Delete app "${app.app_slug}"? This removes its deploys + data and cannot be undone. [y/N] `);
+        if (!["y", "yes"].includes(answer.trim().toLowerCase())) {
+            throw new CliError("Delete cancelled.", 1);
+        }
+    }
+    await authedNoContent(config, `/api/organizations/${config.orgUuid}/apps/${app.uuid}`, `Delete app "${app.app_slug}"`, { method: "DELETE" });
+    console.log(`App "${app.app_slug}" deleted.`);
+}
+// ---------------------------------------------------------------------------
+// analytics — per-app pageviews (`railcode analytics <app>`)
+// ---------------------------------------------------------------------------
+const ANALYTICS_HELP = `railcode analytics — per-app pageview analytics (admin/owner)
+
+Usage:
+  railcode analytics <app> [--range 7d|30d|90d]   Views, uniques, daily, top paths/users
+
+<app> is an app slug or UUID. Default range 30d.
+
+Options:
+  --json                                 Print the raw analytics object
+`;
+async function commandAnalytics(args) {
+    try {
+        const ref = args.rest[0];
+        if (!ref || ref === "help") {
+            console.log(ANALYTICS_HELP);
+            return;
+        }
+        rejectUnknownOptions(args, ["range", "json", "apiUrl"], "analytics", ANALYTICS_HELP);
+        const range = parseRange(optionString(args, "range"));
+        const config = requireLogin(args);
+        const app = resolveAppRef(await fetchApps(config), ref);
+        const qs = range ? `?range=${range}` : "";
+        const data = (await authedJson(config, `/api/organizations/${config.orgUuid}/apps/${app.uuid}/analytics${qs}`, "Get analytics"));
+        if (args.options.json) {
+            console.log(JSON.stringify(data, null, 2));
+            return;
+        }
+        console.log(renderAnalytics(app.app_slug, data));
+    }
+    catch (error) {
+        if (error instanceof OrgAdminError || error instanceof ObservabilityError) {
+            throw new CliError(error.message, 2);
+        }
+        throw error;
+    }
+}
+// ---------------------------------------------------------------------------
+// logs — org observability streams (`railcode logs <stream>`)
+// ---------------------------------------------------------------------------
+const LOGS_HELP = `railcode logs — org observability (admin)
+
+Usage:
+  railcode logs <stream> [filters]              Recent log rows (newest first)
+  railcode logs <stream> <request_id>           Full detail for one entry
+
+Streams:
+  connector           data-connection SQL queries      (connection:manage)
+  service-connector   service-connector proxy calls    (service-connector:manage)
+  llm                 LLM gateway calls                (llm:manage)
+  email               email gateway sends              (email:manage)
+  agent               managed-agent runs               (agent:manage)
+
+Filters (each optional; unsupported ones are rejected per stream):
+  --app <slug|uuid>       Only rows for this app
+  --user <email|uuid>     Only rows for this user
+  --connector <name>      Only this connector (connector/service-connector)
+  --agent <uuid>          Only this agent (agent stream)
+  --source app|agent      LLM source (llm stream)
+  --status <value>        Stream-specific status (e.g. success|error)
+  --limit <1..500>        Max rows (default 100)
+  --json                  Print raw JSON
+`;
+async function commandLogs(args) {
+    try {
+        const streamName = args.rest[0] ?? "";
+        if (streamName === "" || streamName === "help") {
+            console.log(LOGS_HELP);
+            return;
+        }
+        rejectUnknownOptions(args, ["app", "user", "connector", "agent", "source", "status", "limit", "json", "apiUrl"], "logs", LOGS_HELP);
+        const stream = resolveLogStream(streamName);
+        const requestId = args.rest[1];
+        if (args.rest.length > 2) {
+            throw new CliError(`railcode logs ${stream.key} takes at most one request id.`, 2);
+        }
+        const config = requireLogin(args);
+        if (requestId) {
+            await logsShowDetail(config, stream, requestId, args);
+            return;
+        }
+        await logsList(config, stream, args);
+    }
+    catch (error) {
+        if (error instanceof ObservabilityError || error instanceof OrgAdminError) {
+            throw new CliError(error.message, 2);
+        }
+        throw error;
+    }
+}
+// Turn --app/--user/--agent references into UUIDs the API expects. Slugs/emails are
+// resolved against the org's apps/members; a bare UUID passes through unchanged.
+async function resolveLogFilters(config, stream, args) {
+    const out = {};
+    const appRef = optionString(args, "app");
+    const userRef = optionString(args, "user");
+    const agentRef = optionString(args, "agent");
+    const connector = optionString(args, "connector");
+    const source = optionString(args, "source");
+    const status = optionString(args, "status");
+    const ensure = (key) => {
+        if (!stream.filters.includes(key)) {
+            throw new ObservabilityError(`--${key} is not a valid filter for ${stream.key} logs.`);
+        }
+    };
+    if (appRef !== undefined) {
+        ensure("app");
+        out.app = /^[0-9a-f-]{36}$/i.test(appRef) ? appRef : resolveAppRef(await fetchApps(config), appRef).uuid;
+    }
+    if (userRef !== undefined) {
+        ensure("user");
+        out.user = /^[0-9a-f-]{36}$/i.test(userRef) ? userRef : resolveMemberRef(await fetchMembers(config), userRef).uuid;
+    }
+    if (agentRef !== undefined) {
+        ensure("agent");
+        out.agent = agentRef;
+    }
+    if (connector !== undefined) {
+        ensure("connector");
+        out.connector = connector;
+    }
+    if (source !== undefined) {
+        ensure("source");
+        out.source = validateLogSource(stream, source);
+    }
+    if (status !== undefined) {
+        ensure("status");
+        out.status = validateLogStatus(stream, status);
+    }
+    out.limit = parseLimit(optionString(args, "limit"));
+    return out;
+}
+async function logsList(config, stream, args) {
+    const filters = await resolveLogFilters(config, stream, args);
+    const rows = (await authedJson(config, `/api/organizations/${config.orgUuid}${stream.path}${buildLogQuery(filters)}`, `List ${stream.key} logs`));
+    if (args.options.json) {
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
+    if (rows.length === 0) {
+        console.log(`No ${stream.label} logged (matching your filters).`);
+        return;
+    }
+    console.log(logTable(stream, rows));
+}
+async function logsShowDetail(config, stream, requestId, args) {
+    const detail = await authedJson(config, `/api/organizations/${config.orgUuid}${stream.path}/${encodeURIComponent(requestId)}`, `Get ${stream.key} log`);
+    // Detail payloads vary a lot per stream; JSON is the faithful, complete view.
+    console.log(JSON.stringify(detail, null, 2));
+    void args;
+}
+// ---------------------------------------------------------------------------
+// connections — org data connectors (`railcode connections`)
+// ---------------------------------------------------------------------------
+const CONNECTIONS_HELP = `railcode connections — org data connectors (admin)
+
+Usage:
+  railcode connections list                     List data connectors
+  railcode connections create --name <n> --kind postgres|bigquery|turso
+                        --config <json> --credentials <json>
+                        [--config-file <f>] [--credentials-file <f>]
+                                                Create/replace a connector (dials before saving)
+  railcode connections delete <name|uuid>       Delete a connector
+
+Config/credentials fields per engine:
+  postgres    config {host,database,username,port?,sslmode?}  credentials {password}
+  bigquery    config {project_id,dataset}                     credentials {service_account_json}
+  turso       config {url}                                    credentials {auth_token}
+
+Options:
+  --json                                 Print raw JSON (list)
+`;
+async function commandConnections(args) {
+    try {
+        const sub = args.rest[0] ?? "";
+        switch (sub) {
+            case "list":
+            case "ls":
+                await commandConnectionsList(args);
+                return;
+            case "create":
+                await commandConnectionsCreate(args);
+                return;
+            case "delete":
+            case "rm":
+                await commandConnectionsDelete(args);
+                return;
+            case "":
+            case "help":
+                console.log(CONNECTIONS_HELP);
+                return;
+            default:
+                throw new CliError(`Unknown connections command: ${sub}\n\n${CONNECTIONS_HELP}`, 2);
+        }
+    }
+    catch (error) {
+        if (error instanceof ConnectionAdminError)
+            throw new CliError(error.message, 2);
+        throw error;
+    }
+}
+async function fetchConnections(config) {
+    return (await authedJson(config, `/api/organizations/${config.orgUuid}/connections`, "List connections"));
+}
+async function commandConnectionsList(args) {
+    rejectUnknownOptions(args, ["json", "apiUrl"], "connections", CONNECTIONS_HELP);
+    const config = requireLogin(args);
+    const conns = await fetchConnections(config);
+    if (args.options.json) {
+        console.log(JSON.stringify(conns, null, 2));
+        return;
+    }
+    if (conns.length === 0) {
+        console.log("No data connectors configured for this organization.");
+        return;
+    }
+    console.log(connectionTable(conns));
+}
+async function commandConnectionsCreate(args) {
+    rejectUnknownOptions(args, ["name", "kind", "config", "configFile", "credentials", "credentialsFile", "apiUrl"], "connections", CONNECTIONS_HELP);
+    const kind = parseConnectionEngine(optionString(args, "kind"));
+    const configObj = readJsonObjectOption(args, "config", "configFile", "--config");
+    const credentials = readJsonObjectOption(args, "credentials", "credentialsFile", "--credentials");
+    const body = buildConnectionCreateBody({
+        name: optionString(args, "name"),
+        kind,
+        config: configObj,
+        credentials,
+    });
+    const config = requireLogin(args);
+    const created = (await authedJson(config, `/api/organizations/${config.orgUuid}/connections`, "Create connection", jsonBody(body)));
+    console.log(`Connection "${created.name}" (${created.kind}) → ${created.target}.`);
+}
+async function commandConnectionsDelete(args) {
+    rejectUnknownOptions(args, ["apiUrl"], "connections", CONNECTIONS_HELP);
+    const ref = args.rest[1];
+    if (!ref)
+        throw new CliError("Usage: railcode connections delete <name|uuid>", 2);
+    const config = requireLogin(args);
+    const conn = resolveConnectionRef(await fetchConnections(config), ref);
+    await authedNoContent(config, `/api/organizations/${config.orgUuid}/connections/${conn.uuid}`, `Delete connection "${conn.name}"`, { method: "DELETE" });
+    console.log(`Connection "${conn.name}" deleted (its saved queries + grants were removed too).`);
+}
+// Read a JSON-object option from an inline `--foo` value or a `--foo-file` path.
+function readJsonObjectOption(args, inlineKey, fileKey, label) {
+    const inline = optionString(args, inlineKey);
+    const file = optionString(args, fileKey);
+    if (inline !== undefined && file !== undefined) {
+        throw new CliError(`Pass either ${label} or ${label}-file, not both.`, 2);
+    }
+    if (file !== undefined) {
+        const resolved = resolve(process.cwd(), file);
+        if (!existsSync(resolved))
+            throw new CliError(`${label}-file not found: ${file}`, 2);
+        return parseJsonObject(readFileSync(resolved, "utf8"), `${label}-file`);
+    }
+    return parseJsonObject(inline, label);
+}
+// ---------------------------------------------------------------------------
 // Config persistence
 // ---------------------------------------------------------------------------
 function loadConfig() {
@@ -5121,9 +6128,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;
@@ -5160,8 +6168,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,
     };
@@ -5564,15 +6573,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();
@@ -5675,7 +6690,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("/");
@@ -5695,7 +6782,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) });
@@ -5713,7 +6800,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
@@ -5734,11 +6821,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;
     }
@@ -5776,8 +6863,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") {
@@ -5795,10 +6918,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,
@@ -5817,7 +6942,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/")) {
@@ -5827,7 +6952,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;
@@ -5844,7 +6969,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;
         }
@@ -6042,6 +7167,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) {