brains-mcp 1.61.2

package/README.md

@@ -0,0 +1,95 @@
+# Brains
+
+A personal second-brain HTTP API and MCP (Model Context Protocol) server backed by Supabase Storage with Postgres full-text search. Designed for ChatGPT Actions, Claude integrations, and any MCP-compatible agent.
+
+---
+
+## Quickstart: init a project
+
+Run this once per project from any MCP-connected agent:
+
+```
+init_project({
+  projectSlug: "my-project",
+  projectName: "My Project",
+  platform: "claude",
+  execute: true
+})
+```
+
+This single call idempotently:
+
+1. Creates `projects/my-project/readme.md` (project registry page).
+2. Generates and saves `projects/my-project/instructions/claude.md` (platform-specific instruction file).
+3. Seeds the three foundation pages (`instructions/agent-instruction-schema-v1.md`, `instructions/agent-instruction-template-v1.md`, `instructions/brain-routing.md`) if they are missing.
+4. Creates stub cross-project tracking pages at the brain root (`active-open-loops.md`, `active-unanswered-questions.md`, `active-next-actions.md`, `decisions/core-decisions-log.md`) if they are missing. Wikis that already carry the pre-#455 copies at `projects/active-*.md` keep using those — no duplicate is created.
+
+The response includes two artifacts:
+- `instructionMarkdown` — the full wiki instruction file saved to `projects/my-project/instructions/claude.md`. This is the canonical reference document an agent reads at session start.
+- `systemPromptMarkdown` — a short pointer block to paste into your Claude Project system prompt (or `CLAUDE.md`). It contains the identity, brain-first rule, activation gate, and a single boot sequence that ends with "read `projects/my-project/instructions/claude.md` and follow it."
+
+Paste `systemPromptMarkdown` into your system prompt. The instruction file handles all domain context and write-back rules — keep the system prompt short.
+
+### Preview before applying
+
+```
+init_project({
+  projectSlug: "my-project",
+  projectName: "My Project",
+  execute: false
+})
+```
+
+Returns the full operation plan with no writes.
+
+---
+
+> **Why not `pull_wiki`?** It returns a base64-encoded ZIP inline in the tool response, which overflows MCP tool-result token caps at modest scale (~30 pages). `pull_session_bundle` returns plain text sized to fit in a single response and paginates via `nextCursor`. `pull_wiki` remains available for filesystem-equipped clients (e.g. Claude Desktop with filesystem access) and full-archive backup workflows.
+
+---
+
+## Architecture
+
+- **HTTP server** (`src/httpServer.ts`) — REST API with OAuth 2.0, designed for ChatGPT Actions and Claude integrations.
+- **MCP server** (`src/server.ts`) — MCP tool registry over stdio or HTTP transport.
+- **Storage** (`src/storage/client.ts`) — Local filesystem or Supabase Storage backend.
+- **Search** (`src/search/postgresIndex.ts`) — Postgres full-text search index (Supabase) or local scan fallback.
+
+See [API-FIRST-ARCHITECTURE.md](./API-FIRST-ARCHITECTURE.md), [STORAGE.md](./STORAGE.md), and [WIKI-SCHEMA.md](./WIKI-SCHEMA.md) for deeper documentation.
+
+---
+
+## Observability
+
+Every HTTP response carries an `X-Response-Time` header (e.g. `X-Response-Time: 43ms`) indicating server-side processing time. Every request also emits a single log line to stdout:
+
+**Plain format (default):**
+```
+[req] GET /api/v1/search 200 43ms backend=sqlite-fts queryMs=12
+[req] POST /api/v1/pages 200 11ms
+[req] GET /api/v1/search 200 8ms zero-results=true
+```
+
+**Structured JSON (`LOG_FORMAT=json`):**
+```json
+{"ts":"2026-04-17T10:00:00.000Z","method":"GET","path":"/api/v1/search","status":200,"durationMs":43,"backend":"sqlite-fts","queryMs":12}
+```
+
+Set `LOG_FORMAT=json` to enable structured logging for log-shipping (e.g. Datadog, Logtail). Search requests additionally log `backend` and `queryMs` when available, and `zero-results=true` when a search returns no results.
+
+---
+
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+Set `BRAINS_TRANSPORT=stdio` to run as an MCP stdio server.
+
+## Testing
+
+```bash
+npm test
+```

package/dist/access/projectShares.d.ts

@@ -0,0 +1,48 @@
+/**
+ * projectShares.ts
+ *
+ * CRUD for the `project_shares` Postgres table via Supabase PostgREST.
+ * Backs the internal-only `share_project` MCP tool (BRA-368): lets an owner
+ * account grant a named grantee account read+write access to one project
+ * (folder prefix) of the owner's own wiki storage namespace.
+ *
+ * Table: scripts/project-shares.sql
+ */
+export interface ProjectShareGrant {
+    owner_subject: string;
+    project_path: string;
+}
+/**
+ * Normalizes a project identity into a folder-prefix path, e.g. 'projects/5280'.
+ * Matches the segment rules storage/client.ts enforces for wiki paths.
+ */
+export declare function normalizeProjectPath(input: string): string;
+/**
+ * Resolves a grantee identifier (email or existing subject/UUID) to a Supabase
+ * user id. Per BRA-368 v0 decision: the grantee must already have a Brains
+ * account — no pending/email-based invite support yet. Returns null if no
+ * matching user exists.
+ */
+export declare function resolveGranteeSubject(input: string): Promise<string | null>;
+export declare function upsertProjectShare(params: {
+    owner_subject: string;
+    project_path: string;
+    grantee_subject: string;
+    enabled: boolean;
+}): Promise<void>;
+/** Drop cached grants for one grantee, or all of them when called bare. */
+export declare function invalidateGrantCache(granteeSubject?: string): void;
+export declare function listActiveGrantsForGrantee(granteeSubject: string): Promise<ProjectShareGrant[]>;
+/**
+ * Returns the subjects of everyone who currently holds an active (non-revoked)
+ * grant on the given owner+project_path. Used to re-render the "Shared
+ * Workspace" note in project instructions whenever a grant is created or
+ * revoked (BRA-388).
+ */
+export declare function listActiveGranteesForProject(ownerSubject: string, projectPath: string): Promise<string[]>;
+/**
+ * Best-effort reverse lookup of a Supabase user's email from their subject/UUID.
+ * Returns null if unavailable — callers should fall back to the raw subject.
+ */
+export declare function resolveSubjectEmail(subject: string): Promise<string | null>;
+//# sourceMappingURL=projectShares.d.ts.map

package/dist/access/projectShares.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectShares.d.ts","sourceRoot":"","sources":["../../src/access/projectShares.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB;AAkBD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAa1D;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA8BjF;AAED,wBAAsB,kBAAkB,CAAC,MAAM,EAAE;IAC/C,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BhB;AAwBD,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAGlE;AAED,wBAAsB,0BAA0B,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAwBrG;AAED;;;;;GAKG;AACH,wBAAsB,4BAA4B,CAChD,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,EAAE,CAAC,CAanB;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASjF"}

package/dist/access/projectShares.js

@@ -0,0 +1,203 @@
+/**
+ * projectShares.ts
+ *
+ * CRUD for the `project_shares` Postgres table via Supabase PostgREST.
+ * Backs the internal-only `share_project` MCP tool (BRA-368): lets an owner
+ * account grant a named grantee account read+write access to one project
+ * (folder prefix) of the owner's own wiki storage namespace.
+ *
+ * Table: scripts/project-shares.sql
+ */
+function config() {
+    const supabaseUrl = (process.env.SUPABASE_URL ?? "").trim().replace(/\/$/, "");
+    const serviceRoleKey = (process.env.SUPABASE_SERVICE_ROLE_KEY ?? "").trim();
+    if (!supabaseUrl || !serviceRoleKey)
+        return null;
+    return { supabaseUrl, serviceRoleKey };
+}
+function headers(serviceRoleKey, extra) {
+    return {
+        "content-type": "application/json",
+        apikey: serviceRoleKey,
+        authorization: `Bearer ${serviceRoleKey}`,
+        ...extra,
+    };
+}
+/**
+ * Normalizes a project identity into a folder-prefix path, e.g. 'projects/5280'.
+ * Matches the segment rules storage/client.ts enforces for wiki paths.
+ */
+export function normalizeProjectPath(input) {
+    const trimmed = input.trim().replace(/^\/+|\/+$/g, "");
+    if (!trimmed)
+        throw new Error("project_path is required");
+    const segments = trimmed.split("/");
+    if (segments[0] !== "projects" || segments.length < 2) {
+        throw new Error("project_path must be a folder prefix under 'projects/', e.g. 'projects/5280'");
+    }
+    for (const segment of segments) {
+        if (!/^[a-z0-9-]+$/.test(segment)) {
+            throw new Error(`Unsafe project_path segment: '${segment}'`);
+        }
+    }
+    return segments.join("/");
+}
+/**
+ * Resolves a grantee identifier (email or existing subject/UUID) to a Supabase
+ * user id. Per BRA-368 v0 decision: the grantee must already have a Brains
+ * account — no pending/email-based invite support yet. Returns null if no
+ * matching user exists.
+ */
+export async function resolveGranteeSubject(input) {
+    const cfg = config();
+    if (!cfg)
+        throw new Error("share_project requires Supabase auth to be configured");
+    const { supabaseUrl, serviceRoleKey } = cfg;
+    const trimmed = input.trim();
+    if (!trimmed)
+        return null;
+    if (trimmed.includes("@")) {
+        const email = trimmed.toLowerCase();
+        let page = 1;
+        // Small user bases in practice; cap pagination as a sane upper bound.
+        while (page <= 20) {
+            const url = `${supabaseUrl}/auth/v1/admin/users?page=${page}&per_page=1000`;
+            const res = await fetch(url, { headers: headers(serviceRoleKey) });
+            if (!res.ok)
+                return null;
+            const body = (await res.json().catch(() => null));
+            const batch = body?.users ?? [];
+            const match = batch.find((u) => (u.email ?? "").toLowerCase() === email);
+            if (match)
+                return match.id;
+            if (batch.length < 1000)
+                break;
+            page++;
+        }
+        return null;
+    }
+    const url = `${supabaseUrl}/auth/v1/admin/users/${encodeURIComponent(trimmed)}`;
+    const res = await fetch(url, { headers: headers(serviceRoleKey) });
+    if (!res.ok)
+        return null;
+    const user = (await res.json().catch(() => null));
+    return user?.id ?? null;
+}
+export async function upsertProjectShare(params) {
+    const cfg = config();
+    if (!cfg)
+        throw new Error("share_project requires Supabase to be configured");
+    const { supabaseUrl, serviceRoleKey } = cfg;
+    const now = new Date().toISOString();
+    const url = `${supabaseUrl}/rest/v1/project_shares` +
+        `?on_conflict=owner_subject,project_path,grantee_subject`;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: headers(serviceRoleKey, { prefer: "resolution=merge-duplicates,return=minimal" }),
+        body: JSON.stringify({
+            id: `${params.owner_subject}:${params.project_path}:${params.grantee_subject}`,
+            owner_subject: params.owner_subject,
+            project_path: params.project_path,
+            grantee_subject: params.grantee_subject,
+            permissions: "read_write",
+            revoked_at: params.enabled ? null : now,
+            updated_at: now,
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`upsertProjectShare failed (${res.status}): ${body}`);
+    }
+    // Both granting and revoking flow through here (via `enabled`), so dropping
+    // the grantee's cache entry keeps revocation effective on the next request
+    // rather than up to a TTL later — the property BRA-377 exists to guarantee.
+    invalidateGrantCache(params.grantee_subject);
+}
+/**
+ * Short-lived cache for grant lookups.
+ *
+ * The drive is re-resolved on every request and every MCP tool call so a
+ * revoked grant stops working immediately (BRA-377). That correctness property
+ * is worth keeping, but it made this an uncached Supabase round trip on every
+ * authenticated request — measured at roughly a third of the ~570ms floor for
+ * even the cheapest authenticated endpoint (GH #412).
+ *
+ * Correctness is preserved by invalidating on mutation rather than relying on
+ * expiry: upsertProjectShare() drops the grantee's entry, so a grant or
+ * revocation still takes effect on the very next request. The TTL is only a
+ * backstop for rows changed out of band (direct SQL, another instance).
+ */
+const GRANT_CACHE_TTL_MS = 30_000;
+const grantCache = new Map();
+function grantCacheTtlMs() {
+    const raw = parseInt(process.env.BRAINS_GRANT_CACHE_TTL_MS ?? "", 10);
+    return Number.isFinite(raw) && raw >= 0 ? raw : GRANT_CACHE_TTL_MS;
+}
+/** Drop cached grants for one grantee, or all of them when called bare. */
+export function invalidateGrantCache(granteeSubject) {
+    if (granteeSubject)
+        grantCache.delete(granteeSubject);
+    else
+        grantCache.clear();
+}
+export async function listActiveGrantsForGrantee(granteeSubject) {
+    const cfg = config();
+    if (!cfg)
+        return [];
+    const ttl = grantCacheTtlMs();
+    const cached = grantCache.get(granteeSubject);
+    if (cached && ttl > 0 && Date.now() - cached.at < ttl)
+        return cached.grants;
+    const { supabaseUrl, serviceRoleKey } = cfg;
+    const url = `${supabaseUrl}/rest/v1/project_shares` +
+        `?grantee_subject=eq.${encodeURIComponent(granteeSubject)}&revoked_at=is.null` +
+        `&select=owner_subject,project_path`;
+    const res = await fetch(url, { headers: headers(serviceRoleKey) });
+    // Do not cache failures. On this deployment the table may be missing
+    // entirely (GH #409), and caching a 404's empty result would turn a
+    // transient/schema fault into a sticky "user has no grants".
+    if (!res.ok)
+        return [];
+    const rows = (await res.json().catch(() => []));
+    const grants = Array.isArray(rows) ? rows : [];
+    grantCache.set(granteeSubject, { grants, at: Date.now() });
+    return grants;
+}
+/**
+ * Returns the subjects of everyone who currently holds an active (non-revoked)
+ * grant on the given owner+project_path. Used to re-render the "Shared
+ * Workspace" note in project instructions whenever a grant is created or
+ * revoked (BRA-388).
+ */
+export async function listActiveGranteesForProject(ownerSubject, projectPath) {
+    const cfg = config();
+    if (!cfg)
+        return [];
+    const { supabaseUrl, serviceRoleKey } = cfg;
+    const url = `${supabaseUrl}/rest/v1/project_shares` +
+        `?owner_subject=eq.${encodeURIComponent(ownerSubject)}` +
+        `&project_path=eq.${encodeURIComponent(projectPath)}&revoked_at=is.null` +
+        `&select=grantee_subject`;
+    const res = await fetch(url, { headers: headers(serviceRoleKey) });
+    if (!res.ok)
+        return [];
+    const rows = (await res.json().catch(() => []));
+    return Array.isArray(rows) ? rows.map((r) => r.grantee_subject) : [];
+}
+/**
+ * Best-effort reverse lookup of a Supabase user's email from their subject/UUID.
+ * Returns null if unavailable — callers should fall back to the raw subject.
+ */
+export async function resolveSubjectEmail(subject) {
+    const cfg = config();
+    if (!cfg)
+        return null;
+    const { supabaseUrl, serviceRoleKey } = cfg;
+    const url = `${supabaseUrl}/auth/v1/admin/users/${encodeURIComponent(subject)}`;
+    const res = await fetch(url, { headers: headers(serviceRoleKey) });
+    if (!res.ok)
+        return null;
+    const user = (await res.json().catch(() => null));
+    return user?.email ?? null;
+}
+//# sourceMappingURL=projectShares.js.map

package/dist/access/projectShares.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectShares.js","sourceRoot":"","sources":["../../src/access/projectShares.ts"],"names":[],"mappings":"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"}

package/dist/access/sharedInstructionsNote.d.ts

@@ -0,0 +1,37 @@
+/**
+ * sharedInstructionsNote.ts (BRA-388)
+ *
+ * When a project transitions from solo to shared (a `share_project` grant is
+ * created or revoked), the project's generated instructions were almost
+ * certainly written assuming a single owner-operator. This module keeps a
+ * "Shared Workspace" note in sync inside `projects/<slug>/instructions/*.md`
+ * so the instructions name the current collaborator(s), establish
+ * shared-workspace filing rules, and warn against sole-ownership assumptions
+ * written elsewhere in the document.
+ *
+ * The note is idempotent: it lives between START/END markers so re-syncing
+ * (on every grant/revoke) replaces it in place rather than duplicating it.
+ * When no active collaborators remain, the note is removed entirely.
+ */
+import type { StorageClient } from "../storage/client.js";
+/**
+ * Returns updated markdown with the Shared Workspace note applied: replaced
+ * in place if present, appended if not, or removed entirely if there are no
+ * active collaborators.
+ */
+export declare function applySharedWorkspaceSection(content: string, projectSlug: string, collaborators: string[]): string;
+export interface SyncSharedInstructionsResult {
+    collaborators: string[];
+    updated: string[];
+    skipped: string[];
+}
+/**
+ * Re-renders the Shared Workspace note in every existing
+ * `projects/<slug>/instructions/<platform>.md` file for a project, based on
+ * the project's current set of active grantees. Safe to call on both grant
+ * creation and revocation. Non-fatal by design — callers should treat
+ * failures here as best-effort and not block the underlying share/unshare
+ * operation.
+ */
+export declare function syncSharedInstructionsNote(drive: StorageClient, ownerSubject: string, projectPath: string): Promise<SyncSharedInstructionsResult>;
+//# sourceMappingURL=sharedInstructionsNote.d.ts.map

package/dist/access/sharedInstructionsNote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedInstructionsNote.d.ts","sourceRoot":"","sources":["../../src/access/sharedInstructionsNote.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA4C1D;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EAAE,GACtB,MAAM,CAOR;AAED,MAAM,WAAW,4BAA4B;IAC3C,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,aAAa,EACpB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,4BAA4B,CAAC,CA6BvC"}

package/dist/access/sharedInstructionsNote.js

@@ -0,0 +1,76 @@
+import { DriveNotFoundError } from "../drive/errors.js";
+import { listActiveGranteesForProject, resolveSubjectEmail, } from "./projectShares.js";
+const SECTION_START = "<!-- SHARED-WORKSPACE:START -->";
+const SECTION_END = "<!-- SHARED-WORKSPACE:END -->";
+const SECTION_PATTERN = new RegExp(`\\n*${SECTION_START}[\\s\\S]*?${SECTION_END}\\n*`, "g");
+const INSTRUCTION_PLATFORMS = ["claude", "gpt"];
+function projectSlugFromPath(projectPath) {
+    return projectPath.replace(/^projects\//, "");
+}
+function buildSection(projectSlug, collaborators) {
+    const collaboratorList = collaborators.length
+        ? collaborators.map((c) => `- ${c}`).join("\n")
+        : "- (no active collaborators)";
+    return [
+        SECTION_START,
+        "## Shared Workspace",
+        "",
+        `This project (\`projects/${projectSlug}/\`) is shared. Active collaborators with read/write access to everything under this folder:`,
+        "",
+        collaboratorList,
+        "",
+        `- Everything for this project must live under \`projects/${projectSlug}/\` — do not create or expect project content elsewhere in the wiki.`,
+        "- Any collaborator (or their own agent/assistant, which may be a different platform than yours) can read and edit any page under this folder. Do not assume you are the only reader or writer.",
+        "- Assumptions written elsewhere in this document that predate sharing (sole ownership, private working notes, etc.) may no longer hold — verify before relying on them.",
+        "",
+        SECTION_END,
+    ].join("\n");
+}
+function stripSection(content) {
+    return content.replace(SECTION_PATTERN, "\n");
+}
+/**
+ * Returns updated markdown with the Shared Workspace note applied: replaced
+ * in place if present, appended if not, or removed entirely if there are no
+ * active collaborators.
+ */
+export function applySharedWorkspaceSection(content, projectSlug, collaborators) {
+    const stripped = stripSection(content).replace(/\s+$/, "");
+    if (collaborators.length === 0) {
+        return `${stripped}\n`;
+    }
+    const section = buildSection(projectSlug, collaborators);
+    return `${stripped}\n\n${section}\n`;
+}
+/**
+ * Re-renders the Shared Workspace note in every existing
+ * `projects/<slug>/instructions/<platform>.md` file for a project, based on
+ * the project's current set of active grantees. Safe to call on both grant
+ * creation and revocation. Non-fatal by design — callers should treat
+ * failures here as best-effort and not block the underlying share/unshare
+ * operation.
+ */
+export async function syncSharedInstructionsNote(drive, ownerSubject, projectPath) {
+    const projectSlug = projectSlugFromPath(projectPath);
+    const granteeSubjects = await listActiveGranteesForProject(ownerSubject, projectPath);
+    const collaborators = await Promise.all(granteeSubjects.map(async (subject) => (await resolveSubjectEmail(subject)) ?? subject));
+    const updated = [];
+    const skipped = [];
+    for (const platform of INSTRUCTION_PLATFORMS) {
+        const filePath = `${projectPath}/instructions/${platform}.md`;
+        const existing = await drive.readFile(filePath).catch((err) => err instanceof DriveNotFoundError ? null : Promise.reject(err));
+        if (!existing) {
+            skipped.push(filePath);
+            continue;
+        }
+        const nextContent = applySharedWorkspaceSection(existing.content, projectSlug, collaborators);
+        if (nextContent === existing.content) {
+            skipped.push(filePath);
+            continue;
+        }
+        await drive.updateFile(existing.fileId, nextContent, existing.revision);
+        updated.push(filePath);
+    }
+    return { collaborators, updated, skipped };
+}
+//# sourceMappingURL=sharedInstructionsNote.js.map

package/dist/access/sharedInstructionsNote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedInstructionsNote.js","sourceRoot":"","sources":["../../src/access/sharedInstructionsNote.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EACL,4BAA4B,EAC5B,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,aAAa,GAAG,iCAAiC,CAAC;AACxD,MAAM,WAAW,GAAG,+BAA+B,CAAC;AACpD,MAAM,eAAe,GAAG,IAAI,MAAM,CAChC,OAAO,aAAa,aAAa,WAAW,MAAM,EAClD,GAAG,CACJ,CAAC;AAEF,MAAM,qBAAqB,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAU,CAAC;AAEzD,SAAS,mBAAmB,CAAC,WAAmB;IAC9C,OAAO,WAAW,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,YAAY,CAAC,WAAmB,EAAE,aAAuB;IAChE,MAAM,gBAAgB,GAAG,aAAa,CAAC,MAAM;QAC3C,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAC/C,CAAC,CAAC,6BAA6B,CAAC;IAClC,OAAO;QACL,aAAa;QACb,qBAAqB;QACrB,EAAE;QACF,4BAA4B,WAAW,8FAA8F;QACrI,EAAE;QACF,gBAAgB;QAChB,EAAE;QACF,4DAA4D,WAAW,sEAAsE;QAC7I,gMAAgM;QAChM,yKAAyK;QACzK,EAAE;QACF,WAAW;KACZ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,YAAY,CAAC,OAAe;IACnC,OAAO,OAAO,CAAC,OAAO,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CACzC,OAAe,EACf,WAAmB,EACnB,aAAuB;IAEvB,MAAM,QAAQ,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC3D,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,GAAG,QAAQ,IAAI,CAAC;IACzB,CAAC;IACD,MAAM,OAAO,GAAG,YAAY,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;IACzD,OAAO,GAAG,QAAQ,OAAO,OAAO,IAAI,CAAC;AACvC,CAAC;AAQD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,KAAoB,EACpB,YAAoB,EACpB,WAAmB;IAEnB,MAAM,WAAW,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAAC;IACrD,MAAM,eAAe,GAAG,MAAM,4BAA4B,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;IACtF,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,GAAG,CACrC,eAAe,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAC,IAAI,OAAO,CAAC,CACxF,CAAC;IAEF,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,QAAQ,IAAI,qBAAqB,EAAE,CAAC;QAC7C,MAAM,QAAQ,GAAG,GAAG,WAAW,iBAAiB,QAAQ,KAAK,CAAC;QAC9D,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAC5D,GAAG,YAAY,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAC/D,CAAC;QACF,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACvB,SAAS;QACX,CAAC;QACD,MAAM,WAAW,GAAG,2BAA2B,CAAC,QAAQ,CAAC,OAAO,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;QAC9F,IAAI,WAAW,KAAK,QAAQ,CAAC,OAAO,EAAE,CAAC;YACrC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACvB,SAAS;QACX,CAAC;QACD,MAAM,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACxE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACzB,CAAC;IAED,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC7C,CAAC"}

package/dist/admin/seedUsers.d.ts

@@ -0,0 +1,23 @@
+import { type StorageClient } from "../storage/client.js";
+export type SeedTier = "free_beta" | "launch_user" | "solo" | "pro" | "team";
+export interface SeedUsersInput {
+    count: number;
+    tier: SeedTier;
+    prefix: string;
+}
+export interface SeedUsersResult {
+    subjects: string[];
+}
+export interface PurgeSeedUsersResult {
+    deleted: {
+        tokens: number;
+        clients: number;
+        accessLevels: number;
+    };
+}
+export declare const SEED_DOMAIN = "brains.test";
+export declare function isSeedEnabled(): boolean;
+export declare function isGodModeSubject(subject: string): boolean;
+export declare function seedUsers(rootDrive: StorageClient, input: SeedUsersInput): Promise<SeedUsersResult>;
+export declare function purgeSeedUsers(prefix: string): Promise<PurgeSeedUsersResult>;
+//# sourceMappingURL=seedUsers.d.ts.map

package/dist/admin/seedUsers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seedUsers.d.ts","sourceRoot":"","sources":["../../src/admin/seedUsers.ts"],"names":[],"mappings":"AACA,OAAO,EAA6B,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGrF,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,aAAa,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAE7E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAWD,eAAO,MAAM,WAAW,gBAAgB,CAAC;AAEzC,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAIzD;AAgID,wBAAsB,SAAS,CAC7B,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,eAAe,CAAC,CA2C1B;AAED,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAkBlF"}