railcode 0.1.22 → 0.1.24

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 1d|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;
@@ -4700,9 +4735,27 @@ 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>]
+                        [--content-type <type>] [--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.
 
+Create options:
+  --content-type <type>                  Content-Type sent with request bodies
+                                         (default application/json; e.g.
+                                         application/x-www-form-urlencoded for a form API)
+
 List options:
+  --admin                                Manage view: base_url, credential + enabled
+                                         state, content type, native key
+                                         (service-connector:manage)
   --json                                 Print the raw connector array
 
 Docs options:
@@ -4737,6 +4790,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);
@@ -4747,17 +4813,100 @@ 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",
+        "contentType",
+        "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"),
+        contentType: optionString(args, "contentType"),
+        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));
@@ -4954,6 +5103,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 1d|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() {