railcode 0.1.22 → 0.1.24

package/dist/observability.js

@@ -0,0 +1,220 @@
+// Pure helpers behind `railcode logs` (observability streams) and
+// `railcode analytics` (per-app pageviews). No I/O or process state — the command
+// layer in index.ts does the HTTP and printing. Mirrors connectors.ts / db.ts.
+import { formatTable } from "./db.js";
+export class ObservabilityError extends Error {
+}
+function fmtTime(iso) {
+    if (!iso)
+        return "-";
+    return iso.slice(0, 16).replace("T", " ");
+}
+function num(value) {
+    return value === null || value === undefined ? "-" : String(value);
+}
+function str(value) {
+    return value === null || value === undefined ? "-" : String(value);
+}
+function refLabel(ref) {
+    if (!ref)
+        return "-";
+    return ref.email ?? ref.name ?? ref.uuid;
+}
+export const LOG_STREAMS = [
+    {
+        key: "connector",
+        aliases: ["connectors", "sql", "connection", "connections", "db"],
+        path: "/connections/logs",
+        label: "data-connection SQL queries",
+        capability: "connection:manage",
+        filters: ["app", "user", "connector", "status"],
+        statuses: ["success", "error"],
+        columns: ["request_id", "connector", "engine", "status", "ms", "rows", "user", "when"],
+        map: (r) => [
+            str(r.request_id),
+            str(r.connection_name),
+            str(r.engine),
+            str(r.status),
+            num(r.duration_ms),
+            num(r.rowcount),
+            refLabel(r.user),
+            fmtTime(r.created_at),
+        ],
+    },
+    {
+        key: "service-connector",
+        aliases: ["service-connectors", "sc", "proxy"],
+        path: "/service-connectors/logs",
+        label: "service-connector HTTP proxy calls",
+        capability: "service-connector:manage",
+        filters: ["app", "user", "connector", "status"],
+        statuses: ["success", "error"],
+        columns: ["request_id", "connector", "method", "path", "status", "resp", "ms", "when"],
+        map: (r) => [
+            str(r.request_id),
+            str(r.connector_name),
+            str(r.method),
+            str(r.path),
+            str(r.status),
+            num(r.response_status),
+            num(r.duration_ms),
+            fmtTime(r.created_at),
+        ],
+    },
+    {
+        key: "llm",
+        aliases: ["ai"],
+        path: "/llm/logs",
+        label: "LLM gateway calls",
+        capability: "llm:manage",
+        filters: ["app", "user", "status", "source"],
+        statuses: ["success", "provider_error", "validation_error", "cancelled", "timeout"],
+        sources: ["app", "agent"],
+        columns: ["request_id", "provider", "model", "status", "in_tok", "out_tok", "ms", "when"],
+        map: (r) => [
+            str(r.request_id),
+            str(r.provider),
+            str(r.model),
+            str(r.status),
+            num(r.input_tokens),
+            num(r.output_tokens),
+            num(r.latency_ms),
+            fmtTime(r.created_at),
+        ],
+    },
+    {
+        key: "email",
+        aliases: ["emails", "mail"],
+        path: "/email/logs",
+        label: "email gateway sends",
+        capability: "email:manage",
+        filters: ["app", "user", "status"],
+        statuses: ["success", "provider_error", "validation_error", "suppressed"],
+        columns: ["request_id", "subject", "recipients", "status", "when"],
+        map: (r) => [
+            str(r.request_id),
+            str(r.subject),
+            num(r.recipient_count),
+            str(r.status),
+            fmtTime(r.created_at),
+        ],
+    },
+    {
+        key: "agent",
+        aliases: ["agents", "runs"],
+        path: "/agents/runs",
+        label: "managed-agent runs",
+        capability: "agent:manage",
+        filters: ["agent", "app", "user", "status"],
+        statuses: ["running", "success", "failed", "cancelled", "limit_exceeded"],
+        columns: ["request_id", "agent", "status", "trigger", "started", "finished"],
+        map: (r) => [
+            str(r.request_id),
+            refLabel(r.agent),
+            str(r.status),
+            str(r.trigger_type),
+            fmtTime(r.started_at),
+            fmtTime(r.finished_at),
+        ],
+    },
+];
+export function resolveLogStream(name) {
+    const needle = (name ?? "").trim().toLowerCase();
+    if (!needle) {
+        throw new ObservabilityError(`Pick a log stream: ${LOG_STREAMS.map((s) => s.key).join(", ")}.`);
+    }
+    const found = LOG_STREAMS.find((s) => s.key === needle || s.aliases.includes(needle));
+    if (!found) {
+        throw new ObservabilityError(`Unknown log stream "${name}". One of: ${LOG_STREAMS.map((s) => s.key).join(", ")}.`);
+    }
+    return found;
+}
+export function validateLogStatus(stream, value) {
+    const v = value.trim().toLowerCase();
+    if (!stream.statuses.includes(v)) {
+        throw new ObservabilityError(`--status for ${stream.key} must be one of: ${stream.statuses.join(", ")}.`);
+    }
+    return v;
+}
+export function validateLogSource(stream, value) {
+    const v = value.trim().toLowerCase();
+    if (!stream.sources || !stream.sources.includes(v)) {
+        throw new ObservabilityError(`--source is only valid for llm logs (${(stream.sources ?? []).join(", ") || "n/a"}).`);
+    }
+    return v;
+}
+export function parseLimit(value) {
+    if (value === undefined)
+        return undefined;
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1 || n > 500) {
+        throw new ObservabilityError("--limit must be an integer between 1 and 500.");
+    }
+    return n;
+}
+// Build the `GET /logs` query string from resolved filter values (app/user/agent
+// are already UUIDs). Only non-empty values are appended; order is stable for tests.
+export function buildLogQuery(params) {
+    const qs = new URLSearchParams();
+    if (params.agent)
+        qs.set("agent", params.agent);
+    if (params.app)
+        qs.set("app", params.app);
+    if (params.user)
+        qs.set("user", params.user);
+    if (params.connector)
+        qs.set("connector", params.connector);
+    if (params.source)
+        qs.set("source", params.source);
+    if (params.status)
+        qs.set("status", params.status);
+    if (params.limit !== undefined)
+        qs.set("limit", String(params.limit));
+    const s = qs.toString();
+    return s ? `?${s}` : "";
+}
+export function logTable(stream, rows) {
+    return formatTable(stream.columns, rows.map((r) => stream.map(r)));
+}
+// ── Analytics (per-app pageviews) ───────────────────────────────────────────
+export const ANALYTICS_RANGES = ["1d", "7d", "30d", "90d"];
+export function parseRange(value) {
+    if (value === undefined)
+        return undefined;
+    const v = value.trim().toLowerCase();
+    if (!ANALYTICS_RANGES.includes(v)) {
+        throw new ObservabilityError(`--range must be one of: ${ANALYTICS_RANGES.join(", ")}.`);
+    }
+    return v;
+}
+export function renderAnalytics(slug, data) {
+    const lines = [];
+    lines.push(`Analytics for ${slug} — ${data.range} (${data.from} → ${data.to})`);
+    lines.push(`  views: ${data.totals.views}   unique users: ${data.totals.uniques}`);
+    lines.push("");
+    if (data.daily.length > 0) {
+        lines.push("Daily");
+        lines.push(indent(formatTable(["day", "views", "uniques"], data.daily.map((d) => [d.day, String(d.views), String(d.uniques)]))));
+        lines.push("");
+    }
+    if (data.top_paths.length > 0) {
+        lines.push("Top paths");
+        lines.push(indent(formatTable(["path", "views"], data.top_paths.map((p) => [p.path, String(p.views)]))));
+        lines.push("");
+    }
+    if (data.users.length > 0) {
+        lines.push("Top users");
+        lines.push(indent(formatTable(["user", "views"], data.users.map((u) => [u.display_name, String(u.views)]))));
+        lines.push("");
+    }
+    if (data.totals.views === 0) {
+        lines.push("No pageviews recorded in this window.");
+    }
+    return lines.join("\n").replace(/\n+$/, "");
+}
+function indent(block) {
+    return block
+        .split("\n")
+        .map((l) => `  ${l}`)
+        .join("\n");
+}

package/dist/orgadmin.js

@@ -0,0 +1,227 @@
+// Pure helpers behind the org-admin CLI surfaces — `railcode members`,
+// `railcode roles`, and the access half of `railcode apps`. Kept free of any I/O
+// or process state so they can be unit-tested directly (see test/orgadmin.test.mjs);
+// the command layer in index.ts does the HTTP and printing. Mirrors connectors.ts.
+import { formatTable } from "./db.js";
+export class OrgAdminError extends Error {
+}
+// Trim an ISO 8601 timestamp to a compact "YYYY-MM-DD HH:MM" for table display.
+export function fmtTime(iso) {
+    if (!iso)
+        return "-";
+    return iso.slice(0, 16).replace("T", " ");
+}
+function splitList(value) {
+    return value
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+}
+export function memberTable(members) {
+    return formatTable(["email", "name", "role", "verified"], members.map((m) => [m.email, m.name, m.role, m.email_verified ? "yes" : "no"]));
+}
+// Resolve a member reference — a UUID or an email (case-insensitive) — against a
+// fetched member list. Throws OrgAdminError when it matches nothing/ambiguously.
+export function resolveMemberRef(members, ref) {
+    const needle = ref.trim();
+    if (!needle)
+        throw new OrgAdminError("Expected a member (email or UUID).");
+    const byUuid = members.find((m) => m.uuid === needle);
+    if (byUuid)
+        return byUuid;
+    const lower = needle.toLowerCase();
+    const byEmail = members.filter((m) => m.email.toLowerCase() === lower);
+    if (byEmail.length === 1)
+        return byEmail[0];
+    if (byEmail.length > 1) {
+        throw new OrgAdminError(`Multiple members match "${ref}" — use the UUID.`);
+    }
+    throw new OrgAdminError(`No member matches "${ref}" (try an email or UUID).`);
+}
+// The two assignable system roles (the owner tier can't be assigned/reassigned via
+// the API — it's the org creator, transferred through a separate flow).
+export function parseAssignableRole(value) {
+    const v = (value ?? "").trim().toLowerCase();
+    if (v === "admin" || v === "member")
+        return v;
+    throw new OrgAdminError('--role must be "admin" or "member".');
+}
+export function roleTable(roles) {
+    return formatTable(["name", "members", "description", "uuid"], roles.map((r) => [
+        r.name,
+        String(r.member_uuids.length),
+        r.description || "-",
+        r.uuid,
+    ]));
+}
+// Resolve an org-role reference — a UUID or a name (case-insensitive) — against a
+// fetched role list.
+export function resolveRoleRef(roles, ref) {
+    const needle = ref.trim();
+    if (!needle)
+        throw new OrgAdminError("Expected a role (name or UUID).");
+    const byUuid = roles.find((r) => r.uuid === needle);
+    if (byUuid)
+        return byUuid;
+    const lower = needle.toLowerCase();
+    const byName = roles.filter((r) => r.name.toLowerCase() === lower);
+    if (byName.length === 1)
+        return byName[0];
+    if (byName.length > 1) {
+        throw new OrgAdminError(`Multiple roles named "${ref}" — use the UUID.`);
+    }
+    throw new OrgAdminError(`No role matches "${ref}" (try a name or UUID).`);
+}
+// How the subject label is resolved for display: org → "everyone"; role/user/app →
+// looked up by uuid in the provided maps, else the raw type.
+export function grantTable(grants, roleNames, userEmails, appSlugs = new Map()) {
+    return formatTable(["id", "subject", "action", "resource_type", "resource_id"], grants.map((g) => [
+        String(g.id),
+        grantSubjectLabel(g, roleNames, userEmails, appSlugs),
+        g.action,
+        g.resource_type,
+        g.resource_id,
+    ]));
+}
+export function grantSubjectLabel(g, roleNames, userEmails, appSlugs = new Map()) {
+    if (g.subject_type === "org")
+        return "everyone";
+    if (!g.subject_uuid)
+        return g.subject_type;
+    if (g.subject_type === "role")
+        return `role:${roleNames.get(g.subject_uuid) ?? g.subject_uuid}`;
+    if (g.subject_type === "user")
+        return `user:${userEmails.get(g.subject_uuid) ?? g.subject_uuid}`;
+    if (g.subject_type === "app")
+        return `app:${appSlugs.get(g.subject_uuid) ?? g.subject_uuid}`;
+    return `${g.subject_type}:${g.subject_uuid}`;
+}
+export function parseGrantSubject(value) {
+    const raw = (value ?? "").trim();
+    if (!raw) {
+        throw new OrgAdminError("--subject is required: org | role:<name|uuid> | user:<email|uuid>.");
+    }
+    if (raw.toLowerCase() === "org" || raw.toLowerCase() === "everyone")
+        return { kind: "org" };
+    const idx = raw.indexOf(":");
+    if (idx === -1) {
+        throw new OrgAdminError(`Bad --subject "${value}". Use org | role:<name|uuid> | user:<email|uuid>.`);
+    }
+    const kind = raw.slice(0, idx).toLowerCase();
+    const ref = raw.slice(idx + 1).trim();
+    if (!ref)
+        throw new OrgAdminError(`--subject ${kind}: is missing a value.`);
+    if (kind === "role")
+        return { kind: "role", ref };
+    if (kind === "user")
+        return { kind: "user", ref };
+    throw new OrgAdminError(`Unknown --subject kind "${kind}". Use org, role: or user:.`);
+}
+// The grant resource types the management API accepts (the implied action is
+// stored server-side). `app` grants are manifest-managed, not settable here.
+export const GRANT_RESOURCE_TYPES = [
+    "app",
+    "llm",
+    "email",
+    "sc_endpoint",
+    "connector",
+    "saved_query",
+    "agent",
+];
+export function parseResourceType(value) {
+    const v = (value ?? "").trim();
+    if (!v) {
+        throw new OrgAdminError(`--resource is required (${GRANT_RESOURCE_TYPES.join(" | ")}).`);
+    }
+    if (!GRANT_RESOURCE_TYPES.includes(v)) {
+        throw new OrgAdminError(`Unknown --resource "${value}". One of: ${GRANT_RESOURCE_TYPES.join(", ")}.`);
+    }
+    return v;
+}
+export function parseResourceIds(value) {
+    const ids = value === undefined ? [] : splitList(value);
+    if (ids.length === 0) {
+        throw new OrgAdminError('--ids is required (comma-separated, e.g. "*" or a name).');
+    }
+    return ids;
+}
+export function renderEffective(eff, who) {
+    const lines = [`Effective access for ${who}`];
+    if (eff.admin) {
+        lines.push("  admin/owner tier — full access to everything (bypasses grants).");
+        return lines.join("\n");
+    }
+    const keys = Object.keys(eff.sections);
+    const hasContent = eff.apps.length > 0 ||
+        keys.some((k) => eff.sections[k].all || eff.sections[k].items.length > 0);
+    if (!hasContent) {
+        lines.push("  (no grants — org defaults only)");
+        return lines.join("\n");
+    }
+    for (const key of keys) {
+        const s = eff.sections[key];
+        if (s.all) {
+            lines.push(`  ${key}: all${s.via ? ` (via ${s.via})` : ""}`);
+        }
+        else if (s.items.length > 0) {
+            // Skip empty sections — the server sends every section key even when the
+            // member has no grant there; printing "key: -" for each is just noise.
+            const items = s.items.map((i) => `${i.resource_id} (${i.via})`).join(", ");
+            lines.push(`  ${key}: ${items}`);
+        }
+    }
+    if (eff.apps.length > 0) {
+        lines.push("  apps:");
+        for (const a of eff.apps)
+            lines.push(`    ${a.name} (${a.via})`);
+    }
+    return lines.join("\n");
+}
+export function appTable(apps) {
+    return formatTable(["slug", "name", "status", "access", "your_role", "manage"], apps.map((a) => [
+        a.app_slug,
+        a.name,
+        a.status,
+        a.access_mode,
+        a.your_role ?? "-",
+        a.can_manage ? "yes" : "no",
+    ]));
+}
+// Resolve an app reference — a slug (preferred) or a UUID — against a fetched app
+// list.
+export function resolveAppRef(apps, ref) {
+    const needle = ref.trim();
+    if (!needle)
+        throw new OrgAdminError("Expected an app (slug or UUID).");
+    const bySlug = apps.find((a) => a.app_slug === needle);
+    if (bySlug)
+        return bySlug;
+    const byUuid = apps.find((a) => a.uuid === needle);
+    if (byUuid)
+        return byUuid;
+    throw new OrgAdminError(`No app matches "${ref}" (try a slug or UUID).`);
+}
+export const ACCESS_MODES = ["organization", "private", "restricted"];
+export function parseAccessMode(value) {
+    const v = (value ?? "").trim().toLowerCase();
+    if (ACCESS_MODES.includes(v)) {
+        return v;
+    }
+    throw new OrgAdminError(`--mode must be one of: ${ACCESS_MODES.join(", ")}.`);
+}
+export function renderAppAccess(slug, access) {
+    const lines = [`Access for ${slug}: ${access.mode}`];
+    if (access.grants.length === 0) {
+        lines.push("  (no per-user grants)");
+        return lines.join("\n");
+    }
+    lines.push(formatTable(["email", "name", "role"], access.grants.map((g) => [g.email, g.name, g.role]))
+        .split("\n")
+        .map((l) => `  ${l}`)
+        .join("\n"));
+    return lines.join("\n");
+}
+// Comma-separated member refs (emails/uuids) for `--members` in restricted mode.
+export function parseMemberList(value) {
+    return value === undefined ? [] : splitList(value);
+}

package/package.json

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

package/static/sdk.js

@@ -82,6 +82,7 @@
     localStorage.setItem("__sdk_open", v ? "1" : "0");
     root.getElementById("panel").style.display = v ? "flex" : "none";
     applyWidth();
+    window.dispatchEvent(new CustomEvent("railcode:inspector", { detail: { open: v } }));
   }
   var escMap = { "&": "&amp;", "<": "&lt;", ">": "&gt;" };
   var escHtml = (s) => String(s == null ? "" : s).replace(/[&<>]/g, (c) => escMap[c]);
@@ -106,7 +107,9 @@
       if (entries.length > 100) entries.shift();
       render();
     },
-    update: render
+    update: render,
+    toggle: () => setOpen(!isOpen),
+    isOpen: () => isOpen
   };
 
   // ../sdk/src/config.ts
@@ -219,14 +222,84 @@
     }();
   }
 
+  // ../sdk/src/identity.ts
+  var me = () => track("me", "me()", () => call("GET", "/me"));
+  var appUsers = () => track("app-users", "appUsers()", () => call("GET", "/app-users"));
+  var roles = () => track("roles", "roles()", () => call("GET", "/roles"));
+
+  // ../sdk/src/debug-fab.ts
+  function mount2() {
+    const host2 = document.createElement("div");
+    host2.id = "__sdk_debug_fab";
+    const root2 = host2.attachShadow({ mode: "open" });
+    root2.innerHTML = `
+    <style>
+      :host { all: initial; }
+      button {
+        box-sizing: border-box; position: fixed; right: 16px; bottom: 16px;
+        width: 36px; height: 36px; border-radius: 50%; display: flex;
+        align-items: center; justify-content: center; cursor: pointer; padding: 0;
+        background: #14171c; color: #d6d9de; border: 1px solid #2c333d;
+        box-shadow: 0 2px 10px rgba(0,0,0,.35); z-index: 2147483001;
+      }
+      button:hover { background: #1c2128; color: #fff; }
+      svg { width: 16px; height: 16px; }
+    </style>
+    <button title="SDK activity (Ctrl+\`)" aria-label="Toggle SDK activity">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"
+        stroke-linecap="round" stroke-linejoin="round">
+        <path d="M12 19h8"></path>
+        <path d="m4 17 6-6-6-6"></path>
+      </svg>
+    </button>`;
+    root2.querySelector("button").onclick = () => Inspector.toggle();
+    (document.body || document.documentElement).appendChild(host2);
+    const sync = () => {
+      host2.style.display = Inspector.isOpen() ? "none" : "";
+    };
+    sync();
+    window.addEventListener("railcode:inspector", sync);
+  }
+  me().then((who) => {
+    if (who.user.is_admin) mount2();
+  }).catch(() => {
+  });
+
   // ../sdk/src/agents.ts
-  async function doInvoke(name, input) {
+  var TERMINAL = ["success", "failed", "cancelled", "limit_exceeded"];
+  var POLL_MIN_MS = 400;
+  var POLL_MAX_MS = 2e3;
+  var POLL_BACKOFF = 1.4;
+  function isFinished(run) {
+    return TERMINAL.includes(run.status);
+  }
+  async function doStart(name, input) {
     return call("POST", `/agents/${encodeURIComponent(name)}`, { body: { input } });
   }
+  async function doGet(requestId) {
+    return call("GET", `/agents/runs/${encodeURIComponent(requestId)}`);
+  }
+  var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  async function doInvoke(name, input) {
+    let run = await doStart(name, input);
+    let wait = POLL_MIN_MS;
+    while (!isFinished(run)) {
+      await sleep(wait);
+      wait = Math.min(wait * POLL_BACKOFF, POLL_MAX_MS);
+      run = await doGet(run.request_id);
+    }
+    return run;
+  }
+  function start(name, input) {
+    return track("agents", `agents.start(${q(name)})`, () => doStart(name, input));
+  }
+  function get(requestId) {
+    return doGet(requestId);
+  }
   function invoke(name, input) {
     return track("agents", `agents.invoke(${q(name)})`, () => doInvoke(name, input));
   }
-  var agents = { invoke };
+  var agents = { invoke, start, get };
 
   // ../sdk/src/databases.ts
   var QUERY_LABEL_MAX = 80;
@@ -567,11 +640,6 @@
     delete: shared2.delete
   };
 
-  // ../sdk/src/identity.ts
-  var me = () => track("me", "me()", () => call("GET", "/me"));
-  var appUsers = () => track("app-users", "appUsers()", () => call("GET", "/app-users"));
-  var roles = () => track("roles", "roles()", () => call("GET", "/roles"));
-
   // ../sdk/src/llm.ts
   function label2(method, input, opts = {}) {
     const preview = typeof input === "string" ? shorten(input.replace(/\s+/g, " ").trim(), 70) : `${input.length} message${input.length === 1 ? "" : "s"}`;