railcode 0.1.22 → 0.1.23

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 = ["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.23",
   "description": "Developer CLI for the multi-tenant Railcode platform: log in, scaffold, and deploy static apps.",
   "license": "MIT",
   "type": "module",