madarx 2.17.0 → 2.19.0

package/lib/cli/doctor-deep.js

@@ -0,0 +1,170 @@
+/**
+ * `madarx doctor` — deep, DB-aware checks (and `--fix` repairs).
+ *
+ * The base doctor (doctor.js) is presence/health only and NEVER opens the DB.
+ * That contract can't catch state DRIFT — e.g. the `madarx` CLI runs against
+ * ~/.madarx, a SEPARATE database from `npm run dev`, so its config table can
+ * hold a stale `auth_mode=local` while the env says supabase. Detecting that
+ * requires opening the home DB and comparing it against the resolved env.
+ *
+ * This module is imported ONLY after the caller has:
+ *   1. set MADARX_DISABLE_INPROC_DAEMON=1   (opening the DB must NOT spin up the
+ *      cron/heartbeat loops for a one-shot diagnostic), and
+ *   2. applyHomeEnv() + loadProjectEnv()    (so DATA_DIR + Supabase creds resolve
+ *      exactly as the running server would see them).
+ *
+ * Each check returns { name, ok, detail, hard, fixable, fix? }. With `apply`,
+ * fixable failures are repaired in place and the result reflects the new state.
+ * Every repair is DETERMINISTIC — no LLM in the auth-config path.
+ */
+
+import fs from 'node:fs';
+
+const VALID_MODES = new Set(['local', 'supabase']);
+
+function envMode() {
+  const raw = String(process.env.MADARX_AUTH_MODE || '').trim().toLowerCase();
+  return VALID_MODES.has(raw) ? raw : null;
+}
+
+/**
+ * Auth-mode drift — the bug this whole command exists for.
+ *
+ * env=supabase + resolvable creds, but the config table holds a non-supabase
+ * value → the stored row is stale (typically a `madarx setup` default). Runtime
+ * now honors the env in this case, but we still repair the row so the mode is
+ * unambiguous when the server is started WITHOUT the env (e.g. from the UI).
+ *
+ * The inverse — config=supabase with NO resolvable creds — is a potential
+ * lockout; we flag it but never auto-flip to local (that's a human decision via
+ * the recovery hatch / `madarx setup`).
+ */
+function checkAuthModeDrift({ getConfig, setConfig, isSupabaseConfigured, ensureRecoveryToken, getAuthMode }, { apply }) {
+  const env = envMode();
+  const stored = getConfig('auth_mode', null);
+  const creds = isSupabaseConfigured();
+
+  if (env === 'supabase' && creds && stored !== 'supabase') {
+    const base = {
+      name: 'Auth-mode drift',
+      hard: false,
+      fixable: true,
+      detail: `env=supabase + Supabase creds resolve, but config table says ${stored ? `'${stored}'` : 'unset'} → login uses the stale value when run without the env`,
+    };
+    if (!apply) return { ...base, ok: false };
+    setConfig('auth_mode', 'supabase');
+    try { ensureRecoveryToken(); } catch { /* best-effort */ }
+    return { ...base, ok: true, detail: `FIXED — config table set to supabase (was ${stored ? `'${stored}'` : 'unset'})` };
+  }
+
+  if (stored === 'supabase' && !creds) {
+    return {
+      name: 'Auth-mode drift',
+      ok: false,
+      hard: false,
+      fixable: false,
+      detail: 'config=supabase but no Supabase URL/anon key resolves (env or vault) → login will fail. Run `madarx setup` to add keys, or use the recovery hatch to drop to local.',
+    };
+  }
+
+  return { name: 'Auth-mode drift', ok: true, hard: false, fixable: false, detail: `resolved mode=${getAuthMode()}` };
+}
+
+/** The encrypted vault must open with the resolved master key. */
+function checkVault({ listSecrets }) {
+  try {
+    const n = listSecrets().length;
+    return { name: 'Secrets vault', ok: true, hard: false, fixable: false, detail: `opens (${n} secret${n === 1 ? '' : 's'})` };
+  } catch (err) {
+    return {
+      name: 'Secrets vault',
+      ok: false,
+      hard: false,
+      fixable: false,
+      detail: `cannot open — ${err.message}. Check MADARX_MASTER_KEY matches the key that encrypted ~/.madarx.`,
+    };
+  }
+}
+
+/**
+ * In supabase mode, the seeded personal-org can end up owned only by the
+ * synthetic local-user-1, leaving the real operator below owner (every
+ * owner/admin gate 403s). Idempotent; reuses the boot-migration heal.
+ */
+function checkDefaultOrgOwner(db, { healDefaultOrgOwnership, getAuthMode }, { apply }) {
+  if (getAuthMode() !== 'supabase') {
+    return { name: 'Default-org owner', ok: true, hard: false, fixable: false, detail: 'n/a (local mode)' };
+  }
+  const realOwner = db
+    .prepare("SELECT user_id FROM org_memberships WHERE org_id = 'personal-org' AND role = 'owner' AND user_id != 'local-user-1'")
+    .get();
+  if (realOwner) {
+    return { name: 'Default-org owner', ok: true, hard: false, fixable: false, detail: `owned by ${realOwner.user_id}` };
+  }
+  const realMembers = db
+    .prepare("SELECT COUNT(*) AS n FROM org_memberships WHERE org_id = 'personal-org' AND user_id != 'local-user-1'")
+    .get();
+  if (!realMembers || realMembers.n === 0) {
+    return { name: 'Default-org owner', ok: true, hard: false, fixable: false, detail: 'no real members yet (sign in to bootstrap)' };
+  }
+  const base = {
+    name: 'Default-org owner',
+    hard: false,
+    fixable: true,
+    detail: 'personal-org has real members but no real owner — operator is stuck below owner (admin gates 403)',
+  };
+  if (!apply) return { ...base, ok: false };
+  const res = healDefaultOrgOwnership(db);
+  if (res.status === 'promoted') {
+    return { ...base, ok: true, detail: `FIXED — promoted ${res.user_id} to owner (${res.basis})` };
+  }
+  return {
+    ...base,
+    ok: res.status === 'already_owned',
+    detail: res.status === 'ambiguous'
+      ? `ambiguous (${res.count} members) — set MADARX_OWNER_EMAIL and re-run`
+      : `heal result: ${res.status}`,
+  };
+}
+
+/** Supabase mode needs the recovery token so a future lockout has an escape. */
+function checkRecoveryToken({ RECOVERY_TOKEN_FILE, ensureRecoveryToken, getAuthMode }, { apply }) {
+  if (getAuthMode() !== 'supabase') {
+    return { name: 'Recovery token', ok: true, hard: false, fixable: false, detail: 'n/a (local mode)' };
+  }
+  if (fs.existsSync(RECOVERY_TOKEN_FILE)) {
+    return { name: 'Recovery token', ok: true, hard: false, fixable: false, detail: 'present' };
+  }
+  const base = { name: 'Recovery token', hard: false, fixable: true, detail: 'missing — no escape hatch if supabase locks out' };
+  if (!apply) return { ...base, ok: false };
+  const tok = ensureRecoveryToken();
+  return { ...base, ok: Boolean(tok), detail: tok ? 'FIXED — generated' : 'could not generate (see logs)' };
+}
+
+/**
+ * Run the deep, DB-aware checks. The caller MUST have set the daemon-disable env
+ * and applied the home env BEFORE this runs (see module header). Returns
+ * { checks, ok } where ok is false only on hard failures.
+ *
+ * @param {{ apply?: boolean }} [opts]
+ */
+export async function runDeepDoctor({ apply = false } = {}) {
+  // Lazy imports: these pull node:sqlite via lib/db and resolve DATA_DIR from the
+  // env the caller set up — importing them earlier would bind the wrong paths.
+  const { getDb } = await import('../db.js');
+  const { getConfig, setConfig } = await import('../config.js');
+  const { isSupabaseConfigured, getAuthMode, ensureRecoveryToken, RECOVERY_TOKEN_FILE } = await import('../auth-config.js');
+  const { listSecrets } = await import('../secrets.js');
+  const { healDefaultOrgOwnership } = await import('../../scripts/migrate-auth-v1.mjs');
+
+  const db = getDb();
+  const cfg = { getConfig, setConfig, isSupabaseConfigured, getAuthMode, ensureRecoveryToken, listSecrets, RECOVERY_TOKEN_FILE };
+
+  const checks = [
+    checkAuthModeDrift(cfg, { apply }),
+    checkVault(cfg),
+    checkDefaultOrgOwner(db, { healDefaultOrgOwnership, getAuthMode }, { apply }),
+    checkRecoveryToken(cfg, { apply }),
+  ];
+  return { checks, ok: !checks.some((c) => c.hard && !c.ok) };
+}

package/lib/cli/doctor.js

@@ -60,6 +60,30 @@ function checkMasterKey(layout) {
   };
 }
 
+// Catches the "team mode set but no credentials" lockout BEFORE boot. Soft +
+// env-only (doctor never opens the DB), so it can't see vault-stored keys — the
+// message is hedged accordingly. Precedence here mirrors getSupabaseAuthConfig:
+// process.env → env file, with NEXT_PUBLIC_* aliases honored.
+function checkAuthConfig(layout) {
+  const env = readEnvFile(layout.envFile);
+  const pick = (k) => process.env[k] || env[k] || '';
+  const mode = (pick('MADARX_AUTH_MODE') || '').trim().toLowerCase();
+  if (mode !== 'supabase') {
+    return { name: 'Auth config', ok: true, hard: false, detail: mode ? `mode=${mode}` : 'mode=local (default)' };
+  }
+  const url = pick('SUPABASE_URL') || pick('NEXT_PUBLIC_SUPABASE_URL');
+  const anon = pick('SUPABASE_ANON_KEY') || pick('NEXT_PUBLIC_SUPABASE_ANON_KEY');
+  if (url && anon) {
+    return { name: 'Auth config', ok: true, hard: false, detail: 'team mode + Supabase keys present' };
+  }
+  return {
+    name: 'Auth config',
+    ok: false,
+    hard: false,
+    detail: 'team mode set but no SUPABASE_URL/ANON_KEY in env — if they are not in the vault, login will fail. Configure on the login screen or run `madarx setup`.',
+  };
+}
+
 function checkStandalone() {
   const p = path.join(PKG_ROOT, '.next', 'standalone', 'server.js');
   const ok = fs.existsSync(p);
@@ -100,6 +124,7 @@ export async function runDoctor() {
     await checkSqlite(),
     checkHomeWritable(layout),
     checkMasterKey(layout),
+    checkAuthConfig(layout),
     checkStandalone(),
     checkWhatsAppDeps(),
     await checkPort(),
@@ -107,14 +132,65 @@ export async function runDoctor() {
   return { checks, ok: !checks.some((c) => c.hard && !c.ok) };
 }
 
-export async function doctor() {
-  const { checks, ok } = await runDoctor();
-  console.log('madarx doctor\n');
+function printChecks(checks) {
   for (const c of checks) {
     const mark = c.ok ? '✓' : (c.hard ? '✗' : '!');
     console.log(`  ${mark} ${c.name.padEnd(22)} ${c.detail}`);
   }
+}
+
+/**
+ * Run the deep, DB-aware checks. These OPEN the home DB, so set up the env first:
+ * disable the in-proc daemons (a one-shot diagnostic must not start cron/heartbeat)
+ * and apply the home + project env so DATA_DIR and Supabase creds resolve exactly
+ * as the server would see them. Imported lazily AFTER that env is in place.
+ *
+ * Best-effort: a deep-check failure (e.g. unreadable DB) never breaks the base
+ * verdict — it just prints a notice.
+ */
+async function runDeep({ apply }) {
+  process.env.MADARX_DISABLE_INPROC_DAEMON = '1';
+  try {
+    const { applyHomeEnv } = await import('./home.js');
+    const { loadProjectEnv } = await import('../load-env.js');
+    applyHomeEnv();
+    loadProjectEnv();
+    const { runDeepDoctor } = await import('./doctor-deep.js');
+    return await runDeepDoctor({ apply });
+  } catch (err) {
+    console.log(`  ! deep checks skipped — ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * @param {{ flags?: Record<string, string|boolean> }} [opts] `--fix` applies
+ *   deterministic repairs to fixable drift; `--no-deep` skips the DB-aware pass.
+ */
+export async function doctor({ flags = {} } = {}) {
+  const apply = Boolean(flags.fix);
+  const deepEnabled = flags.deep !== false; // --no-deep opts out
+
+  console.log(`madarx doctor${apply ? ' --fix' : ''}\n`);
+
+  const { checks, ok } = await runDoctor();
+  printChecks(checks);
+
+  let deepOk = true;
+  if (deepEnabled) {
+    console.log('');
+    const deep = await runDeep({ apply });
+    if (deep) {
+      printChecks(deep.checks);
+      deepOk = deep.ok;
+      if (!apply && deep.checks.some((c) => c.fixable && !c.ok)) {
+        console.log('\n  Run `madarx doctor --fix` to repair the fixable (!) items above.');
+      }
+    }
+  }
+
+  const allOk = ok && deepOk;
   console.log('');
-  console.log(ok ? 'All hard checks passed.' : 'Some hard checks FAILED — fix the ✗ items above.');
-  return ok ? 0 : 1;
+  console.log(allOk ? 'All hard checks passed.' : 'Some hard checks FAILED — fix the ✗ items above.');
+  return allOk ? 0 : 1;
 }

package/lib/cloud-schema.generated.js

@@ -0,0 +1,18 @@
+/**
+ * lib/cloud-schema.generated.js — GENERATED. DO NOT EDIT BY HAND.
+ *
+ * Produced by scripts/build-cloud-schema.mjs from supabase/migrations/*.sql.
+ * Regenerate with: node scripts/build-cloud-schema.mjs  (runs on `prebuild`).
+ */
+
+/** The full idempotent SQL that stands up the Supabase shared layer. */
+export const CLOUD_SCHEMA_SQL = "-- MadarX OS — Supabase shared-layer schema (generated bundle).\n-- Generated from supabase/migrations/*.sql — DO NOT EDIT THE BUNDLE.\n-- Idempotent: safe to run repeatedly in the Supabase SQL editor.\n\n-- ════════════════════════════════════════════════════════════════════\n-- ▶ 0001_shared_layer.sql\n-- ════════════════════════════════════════════════════════════════════\n-- 0001_shared_layer.sql — MadarX OS hybrid shared layer (Supabase / cloud).\n--\n-- WHAT THIS IS\n--   The cloud coordination layer for *explicitly shared* org collaboration.\n--   Personal work stays local: local SQLite + the filesystem remain the source\n--   of truth for private artifacts and local runs. Only data that a user\n--   explicitly publishes/shares is represented here. This migration deliberately\n--   does NOT mirror the full local runtime schema (agents, runs, heartbeat,\n--   secrets, egress, etc.) — only the shared surface needed for collaboration.\n--\n-- WHAT LIVES HERE\n--   organizations         — tenant boundary (id mirrors the local org id, text)\n--   org_memberships       — who belongs to which org, and their role\n--   shared_spaces         — explicitly shared spaces/projects (metadata only)\n--   shared_artifacts      — metadata for explicitly published artifacts; payload\n--                           is optional and only present when a user opts in\n--   shared_artifact_acl   — per-principal grants on a shared artifact\n--   share_links           — cloud-coordinated external share tokens (hash only)\n--\n-- SECURITY MODEL\n--   RLS is ON for every table. Authenticated end users only ever see rows for\n--   orgs they are a member of, and only mutate per their role. The server-side\n--   service-role key (used by lib/shared-cloud.js, never shipped to the browser)\n--   bypasses RLS to perform publish/unpublish on the user's behalf after the\n--   local app has already authorized the action.\n--\n-- IDEMPOTENCY\n--   Safe to re-run. Tables use IF NOT EXISTS; policies are dropped-then-created.\n\n-- ── Extensions ────────────────────────────────────────────────────────────────\ncreate extension if not exists pgcrypto;\n\n-- ── organizations ─────────────────────────────────────────────────────────────\ncreate table if not exists public.organizations (\n  id          text primary key,\n  slug        text not null unique,\n  name        text not null,\n  plan        text not null default 'free',\n  created_at  timestamptz not null default now(),\n  updated_at  timestamptz not null default now()\n);\n\n-- ── org_memberships ───────────────────────────────────────────────────────────\ncreate table if not exists public.org_memberships (\n  id                 uuid primary key default gen_random_uuid(),\n  org_id             text not null references public.organizations(id) on delete cascade,\n  user_id            uuid not null references auth.users(id) on delete cascade,\n  role               text not null default 'member' check (role in ('owner','admin','member','viewer')),\n  invited_by_user_id uuid,\n  invited_at         timestamptz,\n  accepted_at        timestamptz,\n  created_at         timestamptz not null default now(),\n  unique (org_id, user_id)\n);\ncreate index if not exists idx_org_memberships_user on public.org_memberships(user_id);\ncreate index if not exists idx_org_memberships_org on public.org_memberships(org_id);\n\n-- ── shared_spaces ─────────────────────────────────────────────────────────────\n-- A space/project that was explicitly shared into the org. `local_space_id`\n-- points back to the source-of-truth row in the user's local SQLite.\ncreate table if not exists public.shared_spaces (\n  id             uuid primary key default gen_random_uuid(),\n  org_id         text not null references public.organizations(id) on delete cascade,\n  local_space_id text not null,\n  slug           text not null,\n  name           text not null,\n  description    text,\n  visibility     text not null default 'org' check (visibility in ('org','team','private')),\n  created_by     uuid,\n  created_at     timestamptz not null default now(),\n  updated_at     timestamptz not null default now(),\n  unique (org_id, local_space_id)\n);\ncreate index if not exists idx_shared_spaces_org on public.shared_spaces(org_id);\n\n-- ── shared_artifacts ──────────────────────────────────────────────────────────\n-- Metadata for an explicitly published artifact. `local_artifact_id` points back\n-- to the local source of truth. `content` is nullable on purpose: by default\n-- only metadata is published; the payload is uploaded only when the user opts in.\ncreate table if not exists public.shared_artifacts (\n  id                uuid primary key default gen_random_uuid(),\n  org_id            text not null references public.organizations(id) on delete cascade,\n  space_id          uuid references public.shared_spaces(id) on delete set null,\n  local_artifact_id text not null,\n  title             text not null,\n  kind              text not null default 'html',\n  scope             text not null default 'org' check (scope in ('private','team','org','link')),\n  content_hash      text,\n  byte_size         integer,\n  content           text,\n  storage_path      text,\n  published_by      uuid,\n  published_at      timestamptz not null default now(),\n  updated_at        timestamptz not null default now(),\n  unique (org_id, local_artifact_id)\n);\ncreate index if not exists idx_shared_artifacts_org on public.shared_artifacts(org_id);\ncreate index if not exists idx_shared_artifacts_space on public.shared_artifacts(space_id);\n\n-- ── shared_artifact_acl ───────────────────────────────────────────────────────\ncreate table if not exists public.shared_artifact_acl (\n  id             uuid primary key default gen_random_uuid(),\n  artifact_id    uuid not null references public.shared_artifacts(id) on delete cascade,\n  org_id         text not null references public.organizations(id) on delete cascade,\n  principal_type text not null check (principal_type in ('user','team','org')),\n  principal_id   text,\n  permission     text not null default 'read' check (permission in ('read','write','admin')),\n  created_by     uuid,\n  created_at     timestamptz not null default now(),\n  unique (artifact_id, principal_type, principal_id)\n);\ncreate index if not exists idx_shared_acl_artifact on public.shared_artifact_acl(artifact_id);\n\n-- ── share_links ───────────────────────────────────────────────────────────────\n-- Cloud-coordinated external share. Only the HMAC of the token is stored, so a\n-- DB leak cannot replay outstanding links.\ncreate table if not exists public.share_links (\n  id           uuid primary key default gen_random_uuid(),\n  artifact_id  uuid not null references public.shared_artifacts(id) on delete cascade,\n  org_id       text not null references public.organizations(id) on delete cascade,\n  token_hmac   text not null unique,\n  created_by   uuid,\n  expires_at   timestamptz,\n  max_views    integer,\n  access_count integer not null default 0,\n  revoked      boolean not null default false,\n  created_at   timestamptz not null default now()\n);\ncreate index if not exists idx_share_links_artifact on public.share_links(artifact_id);\n\n-- ── Membership helper functions (SECURITY DEFINER, search_path pinned) ─────────\ncreate or replace function public.is_org_member(p_org_id text)\nreturns boolean\nlanguage sql\nstable\nsecurity definer\nset search_path = public\nas $$\n  select exists (\n    select 1 from public.org_memberships m\n    where m.org_id = p_org_id and m.user_id = auth.uid()\n  );\n$$;\n\ncreate or replace function public.org_role(p_org_id text)\nreturns text\nlanguage sql\nstable\nsecurity definer\nset search_path = public\nas $$\n  select m.role\n  from public.org_memberships m\n  where m.org_id = p_org_id and m.user_id = auth.uid()\n  limit 1;\n$$;\n\n-- ── Enable RLS on every table ─────────────────────────────────────────────────\nalter table public.organizations      enable row level security;\nalter table public.org_memberships    enable row level security;\nalter table public.shared_spaces      enable row level security;\nalter table public.shared_artifacts   enable row level security;\nalter table public.shared_artifact_acl enable row level security;\nalter table public.share_links        enable row level security;\n\n-- ── Policies: organizations ───────────────────────────────────────────────────\ndrop policy if exists organizations_select on public.organizations;\ncreate policy organizations_select on public.organizations\n  for select to authenticated\n  using (public.is_org_member(id));\n\ndrop policy if exists organizations_update on public.organizations;\ncreate policy organizations_update on public.organizations\n  for update to authenticated\n  using (public.org_role(id) in ('owner','admin'))\n  with check (public.org_role(id) in ('owner','admin'));\n\n-- ── Policies: org_memberships ─────────────────────────────────────────────────\n-- A member can see the roster of any org they belong to.\ndrop policy if exists org_memberships_select on public.org_memberships;\ncreate policy org_memberships_select on public.org_memberships\n  for select to authenticated\n  using (public.is_org_member(org_id));\n\n-- Only owners/admins manage membership.\ndrop policy if exists org_memberships_write on public.org_memberships;\ncreate policy org_memberships_write on public.org_memberships\n  for all to authenticated\n  using (public.org_role(org_id) in ('owner','admin'))\n  with check (public.org_role(org_id) in ('owner','admin'));\n\n-- ── Policies: shared_spaces ───────────────────────────────────────────────────\ndrop policy if exists shared_spaces_select on public.shared_spaces;\ncreate policy shared_spaces_select on public.shared_spaces\n  for select to authenticated\n  using (public.is_org_member(org_id));\n\ndrop policy if exists shared_spaces_write on public.shared_spaces;\ncreate policy shared_spaces_write on public.shared_spaces\n  for all to authenticated\n  using (public.org_role(org_id) in ('owner','admin','member'))\n  with check (public.org_role(org_id) in ('owner','admin','member'));\n\n-- ── Policies: shared_artifacts ────────────────────────────────────────────────\ndrop policy if exists shared_artifacts_select on public.shared_artifacts;\ncreate policy shared_artifacts_select on public.shared_artifacts\n  for select to authenticated\n  using (public.is_org_member(org_id));\n\ndrop policy if exists shared_artifacts_write on public.shared_artifacts;\ncreate policy shared_artifacts_write on public.shared_artifacts\n  for all to authenticated\n  using (public.org_role(org_id) in ('owner','admin','member'))\n  with check (public.org_role(org_id) in ('owner','admin','member'));\n\n-- ── Policies: shared_artifact_acl ─────────────────────────────────────────────\ndrop policy if exists shared_artifact_acl_select on public.shared_artifact_acl;\ncreate policy shared_artifact_acl_select on public.shared_artifact_acl\n  for select to authenticated\n  using (public.is_org_member(org_id));\n\ndrop policy if exists shared_artifact_acl_write on public.shared_artifact_acl;\ncreate policy shared_artifact_acl_write on public.shared_artifact_acl\n  for all to authenticated\n  using (public.org_role(org_id) in ('owner','admin'))\n  with check (public.org_role(org_id) in ('owner','admin'));\n\n-- ── Policies: share_links ─────────────────────────────────────────────────────\ndrop policy if exists share_links_select on public.share_links;\ncreate policy share_links_select on public.share_links\n  for select to authenticated\n  using (public.is_org_member(org_id));\n\ndrop policy if exists share_links_write on public.share_links;\ncreate policy share_links_write on public.share_links\n  for all to authenticated\n  using (public.org_role(org_id) in ('owner','admin','member'))\n  with check (public.org_role(org_id) in ('owner','admin','member'));\n\n-- NOTE: the service-role key bypasses RLS by design. lib/shared-cloud.js uses it\n-- server-side only (never in browser/client code) to publish on a user's behalf\n-- after the local app has authorized the action.\n\n-- ════════════════════════════════════════════════════════════════════\n-- ▶ 0002_shared_brand.sql\n-- ════════════════════════════════════════════════════════════════════\n-- 0002_shared_brand.sql — Org-shared brand profile (MadarX OS shared layer).\n--\n-- WHAT THIS IS\n--   The org-wide brand identity, shared through the cloud coordination layer.\n--   A brand profile is local-first by default (it lives in each install's local\n--   SQLite `config` table). When an owner/admin explicitly *publishes* the brand,\n--   one canonical row lands here so every teammate can *adopt* it locally. This\n--   mirrors the artifact/space publish pattern in lib/shared-cloud.js: nothing\n--   leaves the machine implicitly; publish + adopt are explicit, audited actions.\n--\n-- WHAT LIVES HERE\n--   shared_brand_profiles — exactly ONE row per org (unique org_id). Holds the\n--   brand profile JSON (company name, colors, fonts, voice, presentation style,\n--   document types) and an optional inlined logo data URL. No secrets — a brand\n--   profile is pure identity, so the full payload is safe to store.\n--\n-- SECURITY MODEL\n--   RLS is ON. Any org member may READ their org's brand (so they can adopt it).\n--   Only owners/admins may WRITE it (brand identity is an admin-managed default,\n--   consistent with organizations_update). The service-role key used server-side\n--   by lib/shared-cloud.js bypasses RLS to publish on an owner's behalf after the\n--   local app has already authorized the action.\n--\n-- IDEMPOTENCY\n--   Safe to re-run. Table uses IF NOT EXISTS; policies are dropped-then-created.\n\n-- ── shared_brand_profiles ─────────────────────────────────────────────────────\ncreate table if not exists public.shared_brand_profiles (\n  id            uuid primary key default gen_random_uuid(),\n  org_id        text not null unique references public.organizations(id) on delete cascade,\n  company_name  text not null default 'Brand',\n  profile_json  jsonb not null,\n  logo_data_url text,\n  content_hash  text,\n  published_by  uuid,\n  created_at    timestamptz not null default now(),\n  updated_at    timestamptz not null default now()\n);\ncreate index if not exists idx_shared_brand_org on public.shared_brand_profiles(org_id);\n\n-- ── RLS ───────────────────────────────────────────────────────────────────────\nalter table public.shared_brand_profiles enable row level security;\n\n-- Any member may read their org's brand (needed to adopt it locally).\ndrop policy if exists shared_brand_select on public.shared_brand_profiles;\ncreate policy shared_brand_select on public.shared_brand_profiles\n  for select to authenticated\n  using (public.is_org_member(org_id));\n\n-- Only owners/admins may publish/replace the org brand.\ndrop policy if exists shared_brand_write on public.shared_brand_profiles;\ncreate policy shared_brand_write on public.shared_brand_profiles\n  for all to authenticated\n  using (public.org_role(org_id) in ('owner','admin'))\n  with check (public.org_role(org_id) in ('owner','admin'));\n\n-- NOTE: the service-role key bypasses RLS by design. lib/shared-cloud.js uses it\n-- server-side only (never in browser/client code) to publish on a user's behalf\n-- after the local app has authorized the action.\n\n-- ════════════════════════════════════════════════════════════════════\n-- ▶ 0002_shared_spaces_resources.sql\n-- ════════════════════════════════════════════════════════════════════\n-- 0002_shared_spaces_resources.sql — Shareable project folders + space resources.\n--\n-- WHAT THIS ADDS (on top of 0001_shared_layer.sql)\n--   1. shared_spaces.space_type   — distinguishes a shared *project folder*\n--      ('project') from a shared *dashboard/UI space* ('dashboard_space').\n--   2. shared_spaces.local_project_id — convenience pointer to the local\n--      projects.id when space_type = 'project' (local_space_id holds the same\n--      value; this column makes project-scoped joins explicit).\n--   3. shared_space_resources     — metadata-only index of the folders, files,\n--      and artifacts that live inside a shared project folder. NEVER stores file\n--      bodies; only name/path/kind/size/sha256/local_only + a metadata jsonb bag.\n--\n-- WHY space_type WIDENS UNIQUENESS\n--   0001 made shared_spaces unique on (org_id, local_space_id). A project id and\n--   a dashboard-space id are drawn from independent id namespaces and could\n--   collide, so the uniqueness is widened to (org_id, space_type, local_space_id).\n--\n-- SECURITY MODEL — identical to 0001\n--   RLS is ON for the new table. Authenticated end users only ever see rows for\n--   orgs they belong to (is_org_member). Writes are gated by org_role. The\n--   server-side service-role key (lib/shared-cloud.js, never shipped to the\n--   browser) bypasses RLS to publish on a user's behalf after the local app has\n--   already authorized the action.\n--\n-- IDEMPOTENCY\n--   Safe to re-run. Columns use ADD COLUMN IF NOT EXISTS; constraints are guarded\n--   with IF EXISTS / catalog checks; the table uses IF NOT EXISTS; policies are\n--   dropped-then-created.\n\n-- ── shared_spaces: new columns ────────────────────────────────────────────────\nalter table public.shared_spaces add column if not exists space_type       text not null default 'dashboard_space';\nalter table public.shared_spaces add column if not exists local_project_id  text;\n\n-- space_type domain guard.\nalter table public.shared_spaces drop constraint if exists shared_spaces_space_type_check;\nalter table public.shared_spaces\n  add constraint shared_spaces_space_type_check\n  check (space_type in ('dashboard_space','project'));\n\n-- Widen uniqueness to include space_type. 0001 created the implicit constraint\n-- named shared_spaces_org_id_local_space_id_key; drop it then add the wider one.\nalter table public.shared_spaces drop constraint if exists shared_spaces_org_id_local_space_id_key;\ndo $$\nbegin\n  if not exists (\n    select 1 from pg_constraint where conname = 'shared_spaces_org_type_local_key'\n  ) then\n    alter table public.shared_spaces\n      add constraint shared_spaces_org_type_local_key\n      unique (org_id, space_type, local_space_id);\n  end if;\nend $$;\n\ncreate index if not exists idx_shared_spaces_type on public.shared_spaces(org_id, space_type);\n\n-- ── shared_space_resources ────────────────────────────────────────────────────\n-- Metadata-only index of what lives inside a shared project folder. The body of\n-- a file is NEVER uploaded here (or anywhere by default) — only its descriptive\n-- metadata. local_only files are excluded by the server library unless a caller\n-- passes an explicit unsafe override; even then only metadata is recorded and\n-- the row is flagged local_only = true.\ncreate table if not exists public.shared_space_resources (\n  id                uuid primary key default gen_random_uuid(),\n  org_id            text not null references public.organizations(id) on delete cascade,\n  shared_space_id   uuid not null references public.shared_spaces(id) on delete cascade,\n  local_resource_id text not null,\n  resource_type     text not null check (resource_type in ('folder','file','artifact')),\n  name              text not null,\n  path              text,\n  mime_type         text,\n  kind              text,\n  size_bytes        integer,\n  sha256            text,\n  local_only        boolean not null default false,\n  metadata          jsonb,\n  updated_at        timestamptz not null default now(),\n  unique (shared_space_id, resource_type, local_resource_id)\n);\ncreate index if not exists idx_shared_space_resources_space on public.shared_space_resources(shared_space_id);\ncreate index if not exists idx_shared_space_resources_org on public.shared_space_resources(org_id);\n\n-- ── RLS ───────────────────────────────────────────────────────────────────────\nalter table public.shared_space_resources enable row level security;\n\ndrop policy if exists shared_space_resources_select on public.shared_space_resources;\ncreate policy shared_space_resources_select on public.shared_space_resources\n  for select to authenticated\n  using (public.is_org_member(org_id));\n\ndrop policy if exists shared_space_resources_write on public.shared_space_resources;\ncreate policy shared_space_resources_write on public.shared_space_resources\n  for all to authenticated\n  using (public.org_role(org_id) in ('owner','admin','member'))\n  with check (public.org_role(org_id) in ('owner','admin','member'));\n\n-- NOTE: the service-role key bypasses RLS by design. lib/shared-cloud.js uses it\n-- server-side only (never in browser/client code) to publish on a user's behalf\n-- after the local app has authorized the action.\n\n-- ════════════════════════════════════════════════════════════════════\n-- ▶ 0003_org_invites.sql\n-- ════════════════════════════════════════════════════════════════════\n-- 0003_org_invites.sql — Org invite & join (email pre-invite + shareable link).\n--\n-- WHAT THIS ADDS (on top of 0001_shared_layer.sql)\n--   public.org_invites — ONE table for BOTH invite kinds (eng-review decision 1):\n--     • email pre-invite → `email` set, `token_hash` NULL. Claimed on first login\n--       by verified-email match (claim_email_invites RPC). No placeholder users\n--       row, no pending membership — a real membership is created only on join.\n--     • shareable link   → `token_hash` set (SHA-256 of a ≥128-bit CSPRNG token;\n--       the raw token is NEVER stored), `email` NULL. Redeemed via\n--       redeem_invite_token RPC.\n--\n-- WHY RPCs INSTEAD OF LOOSENED RLS (eng-review decision 3)\n--   A not-yet-member cannot read org_invites under RLS (is_org_member is false),\n--   so redemption runs through two SECURITY DEFINER functions that derive the\n--   joining identity from auth.uid()/auth.email() and never trust client input.\n--   Members call them with their OWN JWT — the service-role key never reaches a\n--   member machine. The RPCs are appended by the Phase 2 / Phase 3 changesets.\n--\n-- HARDENING (H2–H5, non-negotiable)\n--   H2  every definer fn: SET search_path, schema-qualified, asserts auth.uid(),\n--       EXECUTE revoked from public/anon and granted to authenticated only.\n--   H3  email-claim requires auth.users.email_confirmed_at and normalized email.\n--   H4  use-count bump is a single conditional UPDATE (no check-then-write);\n--       membership insert is ON CONFLICT DO NOTHING (idempotent).\n--   H5  the granted role is bounded by the CREATOR's role — enforced DB-side by\n--       a BEFORE INSERT trigger here (not only in the API route): an owner may\n--       mint owner/admin/member/viewer; an admin may mint member/viewer only.\n--\n-- IDEMPOTENCY\n--   Safe to re-run. Table uses IF NOT EXISTS; policies/trigger/functions are\n--   dropped-then-created or use CREATE OR REPLACE.\n\n-- ── org_invites ───────────────────────────────────────────────────────────────\ncreate table if not exists public.org_invites (\n  id                 uuid primary key default gen_random_uuid(),\n  org_id             text not null references public.organizations(id) on delete cascade,\n  role               text not null default 'member' check (role in ('owner','admin','member','viewer')),\n  email              text,\n  token_hash         text unique,\n  label              text,\n  created_by_user_id uuid,\n  expires_at         timestamptz,\n  max_uses           integer,\n  used_count         integer not null default 0,\n  revoked_at         timestamptz,\n  created_at         timestamptz not null default now(),\n  -- Exactly one invite kind per row.\n  constraint org_invites_kind_chk check ((email is not null)::int + (token_hash is not null)::int = 1)\n);\ncreate index if not exists idx_org_invites_org   on public.org_invites(org_id);\ncreate index if not exists idx_org_invites_email on public.org_invites(lower(email));\ncreate index if not exists idx_org_invites_token on public.org_invites(token_hash);\n\nalter table public.org_invites enable row level security;\n\n-- SELECT: members of the org can see its invites (the roster/admin surface).\ndrop policy if exists org_invites_select on public.org_invites;\ncreate policy org_invites_select on public.org_invites\n  for select to authenticated\n  using (public.is_org_member(org_id));\n\n-- INSERT/UPDATE/DELETE: owners/admins only. The role-grant ceiling (H5) is\n-- enforced in addition by the trigger below. Note: a not-yet-member redeeming a\n-- link does NOT write here directly — the SECURITY DEFINER RPCs do (and they bump\n-- used_count under the function's privileges, not the caller's).\ndrop policy if exists org_invites_write on public.org_invites;\ncreate policy org_invites_write on public.org_invites\n  for all to authenticated\n  using (public.org_role(org_id) in ('owner','admin'))\n  with check (public.org_role(org_id) in ('owner','admin'));\n\n-- ── H5: role-grant ceiling, enforced DB-side ───────────────────────────────────\n-- The invite's granted role must be bounded by the creator's role in the org.\n-- Without this, anyone who can create an invite could mint an owner invite and\n-- self-escalate. Runs as a trigger so it binds the cloud path regardless of API.\ncreate or replace function public.org_invites_enforce_role_ceiling()\nreturns trigger\nlanguage plpgsql\nsecurity definer\nset search_path = pg_catalog, public\nas $$\ndeclare\n  v_creator_role text;\nbegin\n  -- Only the GRANTED ROLE is ceiling-bounded. used_count bumps and revoked_at\n  -- writes (which redeem_invite_token / revoke perform, sometimes as the joining\n  -- member) leave role unchanged and must pass freely — otherwise redemption,\n  -- which UPDATEs used_count under the member's own auth.uid(), would be blocked.\n  if tg_op = 'UPDATE' and new.role is not distinct from old.role then\n    return new;\n  end if;\n  -- Service-role / server path: auth.uid() is NULL. The owner app already\n  -- authorized the action at the API layer (requireRole admin) before using the\n  -- service key, which bypasses RLS by design. The ceiling exists to stop an\n  -- AUTHENTICATED admin from self-escalating via a direct PostgREST insert OR a\n  -- role-changing UPDATE (auth.uid() is set on those paths).\n  if auth.uid() is null then\n    return new;\n  end if;\n  v_creator_role := public.org_role(new.org_id);\n  if v_creator_role is null then\n    raise exception 'org_invites: creator is not a member of org %', new.org_id;\n  end if;\n  -- owner may grant any role; admin may grant member/viewer only.\n  if v_creator_role = 'owner' then\n    return new;\n  elsif v_creator_role = 'admin' and new.role in ('member','viewer') then\n    return new;\n  end if;\n  raise exception 'org_invites: role % cannot mint an invite granting %', v_creator_role, new.role;\nend;\n$$;\n\ndrop trigger if exists trg_org_invites_role_ceiling on public.org_invites;\ncreate trigger trg_org_invites_role_ceiling\n  before insert or update on public.org_invites\n  for each row execute function public.org_invites_enforce_role_ceiling();\n\nrevoke execute on function public.org_invites_enforce_role_ceiling() from public, anon;\n\n-- ── Phase 2: claim_email_invites() — email pre-invite claim (H2/H3/H4) ─────────\n-- Called by the member's session ONLY when they currently have no membership\n-- (bounded to first-login / no-org state). Derives identity from auth.uid()/\n-- auth.email(); accepts NO client input. Honors a claim only for a VERIFIED,\n-- normalized email (H3). Membership insert is idempotent (H4).\ncreate or replace function public.claim_email_invites()\nreturns table(org_id text, granted_role text)\nlanguage plpgsql\nsecurity definer\nset search_path = pg_catalog, public\nas $$\ndeclare\n  v_uid   uuid := auth.uid();\n  v_email text;\n  rec     record;\nbegin\n  if v_uid is null then\n    raise exception 'claim_email_invites: authentication required';\n  end if;\n  -- H3: verified email only, normalized (lower+trim).\n  select lower(trim(u.email)) into v_email\n    from auth.users u\n    where u.id = v_uid and u.email_confirmed_at is not null;\n  if v_email is null then\n    return;\n  end if;\n  for rec in\n    select * from public.org_invites\n      where lower(email) = v_email and revoked_at is null\n        and (expires_at is null or expires_at > now())\n  loop\n    insert into public.org_memberships (org_id, user_id, role, accepted_at)\n    values (rec.org_id, v_uid, rec.role, now())\n    on conflict (org_id, user_id) do nothing;\n    update public.org_invites\n      set used_count = used_count + 1, revoked_at = now()\n      where id = rec.id and revoked_at is null;\n    org_id := rec.org_id; granted_role := rec.role; return next;\n  end loop;\n  return;\nend;\n$$;\nrevoke execute on function public.claim_email_invites() from public, anon;\ngrant  execute on function public.claim_email_invites() to authenticated;\n\n-- ── Phase 3: redeem_invite_token() — shareable-link redemption (H2/H4, Q2) ─────\n-- Called by POST /api/orgs/join under the member's own JWT. Derives the joining\n-- identity from auth.uid(); accepts ONLY the opaque token (never org_id/role/\n-- user_id/used_count). H4: the use-count bump is a single conditional UPDATE.\n-- Q2: an existing member is a no-op that consumes no use.\ncreate or replace function public.redeem_invite_token(p_token text)\nreturns table(org_id text, granted_role text)\nlanguage plpgsql\nsecurity definer\nset search_path = pg_catalog, public\nas $$\ndeclare\n  v_uid  uuid := auth.uid();\n  v_hash text;\n  rec    public.org_invites%rowtype;\nbegin\n  if v_uid is null then\n    raise exception 'redeem_invite_token: authentication required';\n  end if;\n  if p_token is null or length(p_token) = 0 then\n    raise exception 'invalid invite token';\n  end if;\n  -- sha256() is a pg_catalog built-in (PG14+), so it resolves under the pinned\n  -- search_path WITHOUT depending on where pgcrypto's digest() was installed\n  -- (Supabase puts pgcrypto in `extensions`, not `public`). Matches the Node\n  -- hashToken(): sha256 hex of the token's UTF-8 bytes.\n  v_hash := encode(sha256(p_token::bytea), 'hex');\n\n  select * into rec from public.org_invites\n    where token_hash = v_hash and email is null;\n  if rec.id is null then\n    raise exception 'invalid invite token';\n  end if;\n\n  -- Q2: an existing member just resolves — consume no use.\n  if exists (select 1 from public.org_memberships m where m.org_id = rec.org_id and m.user_id = v_uid) then\n    org_id := rec.org_id;\n    select m.role into granted_role from public.org_memberships m\n      where m.org_id = rec.org_id and m.user_id = v_uid;\n    return next; return;\n  end if;\n\n  -- H4: atomic conditional bump (no check-then-write).\n  update public.org_invites\n    set used_count = used_count + 1\n    where id = rec.id and revoked_at is null\n      and (expires_at is null or expires_at > now())\n      and (max_uses is null or used_count < max_uses);\n  if not found then\n    raise exception 'invite is no longer valid (expired, revoked, or fully used)';\n  end if;\n\n  insert into public.org_memberships (org_id, user_id, role, accepted_at)\n  values (rec.org_id, v_uid, rec.role, now())\n  on conflict (org_id, user_id) do nothing;\n\n  org_id := rec.org_id; granted_role := rec.role; return next;\nend;\n$$;\nrevoke execute on function public.redeem_invite_token(text) from public, anon;\ngrant  execute on function public.redeem_invite_token(text) to authenticated;\n\n-- ════════════════════════════════════════════════════════════════════\n-- ▶ 0004_tighten_share_links.sql\n-- ════════════════════════════════════════════════════════════════════\n-- 0004_tighten_share_links.sql — Narrow share_links writes to owner/admin.\n--\n-- WHY (locked tension resolution)\n--   0001 allowed share_links writes by (owner, admin, member). A public share\n--   link is an external-exposure decision; a plain member should not be able to\n--   mint one. This migration TIGHTENS that one policy to (owner, admin). It is\n--   the ONLY RLS change in the invite/join feature, and it is a tightening — not\n--   the loosening the original Phase 6 draft proposed. Members still publish\n--   artifacts and spaces (those policies are unchanged); they simply cannot mint\n--   public share-links.\n--\n-- IDEMPOTENCY\n--   Safe to re-run: the policy is dropped-then-created.\n\ndrop policy if exists share_links_write on public.share_links;\ncreate policy share_links_write on public.share_links\n  for all to authenticated\n  using (public.org_role(org_id) in ('owner','admin'))\n  with check (public.org_role(org_id) in ('owner','admin'));\n\n-- ════════════════════════════════════════════════════════════════════\n-- ▶ 0005_shared_space_acl.sql\n-- ════════════════════════════════════════════════════════════════════\n-- 0003_shared_space_acl.sql — Per-principal access grants for shared spaces.\n--\n-- WHAT THIS ADDS (on top of 0001 + 0002)\n--   shared_space_acl — grants a specific principal (a user, a team, or the whole\n--   org) a permission (read | write | admin) on a shared space/project folder.\n--   This is the space-level mirror of `shared_artifact_acl` (0001). The coarse\n--   `shared_spaces.visibility` flag stays the baseline; these rows AUGMENT it:\n--     - visibility='private' + user grants  → \"only these people\"\n--     - visibility='org'                    → every member gets baseline read;\n--                                             grants only ELEVATE permission.\n--\n-- PERMISSION SEMANTICS (enforced read-time in lib/shared-cloud.js)\n--   read   browse the space's resource index + open published artifact bodies\n--   write  read + re-sync / add resources\n--   admin  write + manage this space's ACL\n--\n-- PRINCIPAL TYPES\n--   'user' and 'org' are live. 'team' is kept in the CHECK domain for forward\n--   compatibility but is NOT yet targetable (no teams table exists — Phase 4).\n--\n-- SECURITY MODEL — identical to 0001/0002\n--   RLS ON. Authenticated end users only see rows for orgs they belong to\n--   (is_org_member). Writes require org_role in ('owner','admin'). The\n--   service-role key (lib/shared-cloud.js, server-only) bypasses RLS to write a\n--   grant AFTER the local app has authorized the action.\n--\n-- IDEMPOTENCY\n--   Safe to re-run. Table uses IF NOT EXISTS; policies are dropped-then-created.\n\n-- ── shared_space_acl ────────────────────────────────────────────────────────────\ncreate table if not exists public.shared_space_acl (\n  id              uuid primary key default gen_random_uuid(),\n  shared_space_id uuid not null references public.shared_spaces(id) on delete cascade,\n  org_id          text not null references public.organizations(id) on delete cascade,\n  principal_type  text not null check (principal_type in ('user','team','org')),\n  principal_id    text not null,\n  permission      text not null default 'read' check (permission in ('read','write','admin')),\n  created_by      uuid,\n  created_at      timestamptz not null default now(),\n  updated_at      timestamptz not null default now(),\n  unique (shared_space_id, principal_type, principal_id)\n);\ncreate index if not exists idx_shared_space_acl_space on public.shared_space_acl(shared_space_id);\ncreate index if not exists idx_shared_space_acl_org on public.shared_space_acl(org_id);\n\n-- ── RLS ───────────────────────────────────────────────────────────────────────\nalter table public.shared_space_acl enable row level security;\n\ndrop policy if exists shared_space_acl_select on public.shared_space_acl;\ncreate policy shared_space_acl_select on public.shared_space_acl\n  for select to authenticated\n  using (public.is_org_member(org_id));\n\ndrop policy if exists shared_space_acl_write on public.shared_space_acl;\ncreate policy shared_space_acl_write on public.shared_space_acl\n  for all to authenticated\n  using (public.org_role(org_id) in ('owner','admin'))\n  with check (public.org_role(org_id) in ('owner','admin'));\n\n-- NOTE: the service-role key bypasses RLS by design. lib/shared-cloud.js uses it\n-- server-side only (never in browser/client code) to write a grant after the\n-- local app has authorized the action.\n\n-- Refresh the PostgREST schema cache so new tables are visible now.\nnotify pgrst, 'reload schema';\n";
+
+/** Tables the bundle creates — used to probe whether the schema is applied. */
+export const REQUIRED_TABLES = ["org_invites","org_memberships","organizations","share_links","shared_artifact_acl","shared_artifacts","shared_brand_profiles","shared_space_acl","shared_space_resources","shared_spaces"];
+
+/** Source migration filenames, in applied order. */
+export const MIGRATION_FILES = ["0001_shared_layer.sql","0002_shared_brand.sql","0002_shared_spaces_resources.sql","0003_org_invites.sql","0004_tighten_share_links.sql","0005_shared_space_acl.sql"];
+
+/** Short content hash; changes whenever the bundled SQL changes. */
+export const SCHEMA_VERSION = "065e7d20e9ca";

package/lib/cloud-schema.js

@@ -0,0 +1,144 @@
+/**
+ * lib/cloud-schema.js — Supabase shared-layer schema bootstrap (server-only).
+ *
+ * The onboarding wizard's "Build tables" step uses this to:
+ *   1. DETECT  — probe which shared-layer tables exist (service-role .select).
+ *   2. APPLY   — either guide a copy-paste into the project's SQL editor, or,
+ *                one-click, run the bundle via the Supabase Management API.
+ *   3. VERIFY  — re-probe and confirm everything is present.
+ *
+ * The SQL itself is the generated bundle (lib/cloud-schema.generated.js), which
+ * is built from supabase/migrations/*.sql so the migrations stay the single
+ * source of truth. No secret is ever returned, logged, or echoed.
+ */
+
+import { getSharedCloudAdmin, isSharedCloudReady } from './shared-cloud.js';
+import {
+  CLOUD_SCHEMA_SQL,
+  REQUIRED_TABLES,
+  SCHEMA_VERSION,
+  MIGRATION_FILES,
+} from './cloud-schema.generated.js';
+
+export { CLOUD_SCHEMA_SQL, REQUIRED_TABLES, SCHEMA_VERSION, MIGRATION_FILES };
+
+// ── URL / ref helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Accepts a full Supabase URL OR a bare project ref and returns the 20-char ref.
+ * Examples:
+ *   https://abcd1234efgh5678ijkl.supabase.co  → abcd1234efgh5678ijkl
+ *   abcd1234efgh5678ijkl                       → abcd1234efgh5678ijkl
+ * Returns null if it can't confidently extract one.
+ */
+export function projectRefFromUrl(input) {
+  if (!input || typeof input !== 'string') return null;
+  const raw = input.trim();
+  // Bare ref: 20 lowercase alphanumerics, no dots/slashes.
+  if (/^[a-z0-9]{20}$/.test(raw)) return raw;
+  try {
+    const host = new URL(raw.includes('://') ? raw : `https://${raw}`).hostname;
+    const m = host.match(/^([a-z0-9]{20})\.supabase\.(co|in|red)$/);
+    if (m) return m[1];
+    // Fallback: first label if it looks like a ref.
+    const first = host.split('.')[0];
+    if (/^[a-z0-9]{20}$/.test(first)) return first;
+  } catch {
+    /* not a URL */
+  }
+  return null;
+}
+
+/** Builds the canonical project URL from a ref. */
+export function urlFromRef(ref) {
+  return /^[a-z0-9]{20}$/.test(String(ref || '')) ? `https://${ref}.supabase.co` : null;
+}
+
+/** Deep link to the project's SQL editor (new query), from a URL or ref. */
+export function sqlEditorUrl(urlOrRef) {
+  const ref = projectRefFromUrl(urlOrRef);
+  return ref ? `https://supabase.com/dashboard/project/${ref}/sql/new` : null;
+}
+
+// ── Detection ─────────────────────────────────────────────────────────────────
+
+/**
+ * Probes the shared layer for each required table using the service-role
+ * client (RLS-bypassing, so empty/locked tables still resolve). A missing table
+ * surfaces as a PostgREST 404 → counted as missing.
+ *
+ * @param {{ agent_id?: string, project_id?: string }} [options]
+ * @returns {Promise<{ configured: boolean, ready?: boolean, present?: string[],
+ *   missing?: string[], total?: number, version?: string }>}
+ */
+export async function probeCloudSchema(options = {}) {
+  if (!isSharedCloudReady(options)) return { configured: false };
+  const admin = getSharedCloudAdmin(options);
+  const present = [];
+  const missing = [];
+  await Promise.all(
+    REQUIRED_TABLES.map(async (table) => {
+      try {
+        await admin.select(table, { limit: 1 });
+        present.push(table);
+      } catch {
+        missing.push(table);
+      }
+    })
+  );
+  present.sort();
+  missing.sort();
+  return {
+    configured: true,
+    ready: missing.length === 0,
+    present,
+    missing,
+    total: REQUIRED_TABLES.length,
+    version: SCHEMA_VERSION,
+  };
+}
+
+// ── One-click apply via the Supabase Management API ───────────────────────────
+
+const MANAGEMENT_API = 'https://api.supabase.com';
+
+/**
+ * Runs the schema bundle against a project using a Supabase Personal Access
+ * Token (account-level). This is the optional one-click path; the default
+ * onboarding path is copy-paste into the SQL editor, which needs no PAT.
+ *
+ * The PAT is used for this single request and never persisted, logged, or
+ * returned. The target host is the fixed Supabase Management API (no SSRF
+ * surface). On success the bundle's trailing `notify pgrst` refreshes the
+ * PostgREST cache so a follow-up probe sees the new tables.
+ *
+ * @param {{ ref: string, pat: string }} args
+ * @returns {Promise<{ ok: boolean, error?: string }>}
+ */
+export async function applySchemaViaManagementApi({ ref, pat } = {}) {
+  const projectRef = projectRefFromUrl(ref) || (/(^[a-z0-9]{20}$)/.test(String(ref || '')) ? ref : null);
+  if (!projectRef) return { ok: false, error: 'invalid_project_ref' };
+  if (!pat || typeof pat !== 'string' || pat.trim().length < 20) {
+    return { ok: false, error: 'invalid_access_token' };
+  }
+  let res;
+  try {
+    res = await fetch(`${MANAGEMENT_API}/v1/projects/${projectRef}/database/query`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${pat.trim()}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ query: CLOUD_SCHEMA_SQL }),
+      redirect: 'error',
+      signal: AbortSignal.timeout(30000),
+    });
+  } catch {
+    return { ok: false, error: 'unreachable' };
+  }
+  if (res.ok) return { ok: true };
+  // Map the few cases the operator can act on; never echo the upstream body.
+  if (res.status === 401 || res.status === 403) return { ok: false, error: 'unauthorized_token' };
+  if (res.status === 404) return { ok: false, error: 'project_not_found' };
+  return { ok: false, error: `apply_failed_${res.status}` };
+}

package/lib/connection-seeds.js

@@ -207,7 +207,7 @@ const CONNECTION_SEEDS = [
           type: 'password',
           placeholder: 'ghp_…',
           help_url: 'https://github.com/settings/tokens',
-          help_text: 'Use a fine-grained token. Grant only the scopes you need.',
+          help_text: 'To read repos beyond your own, the token must be granted access to them. Fine-grained PAT: under "Repository access" pick the orgs/repos (org owner may need to approve); classic PAT: enable the "repo" scope and, for SSO orgs, click "Authorize" / "Configure SSO" next to the token.',
           required: true,
         },
       ],

package/lib/db.js

@@ -182,6 +182,10 @@ export function getDb() {
     // project (manual or by a mines agent) are pinned to this space so they
     // surface as windows on the dashboard board.
     'ALTER TABLE mines_projects ADD COLUMN default_space_id TEXT',
+    // Chat live-turn continuity: resume an in-flight main-agent turn after the
+    // user navigates away and returns. active_turn_started_at gates a TTL.
+    'ALTER TABLE chat_sessions ADD COLUMN active_turn_id TEXT',
+    'ALTER TABLE chat_sessions ADD COLUMN active_turn_started_at TEXT',
   ]) {
     try { db.exec(sql); } catch (err) {
       if (!/duplicate column name/i.test(String(err?.message || err))) throw err;

package/lib/delegation-contracts.js

@@ -72,6 +72,7 @@ export const LIVE_EVENT_TYPES = [
   'agent.run.status',
   'agent.run.event',
   'agent.run.log',
+  'chat_turn',
 ];
 
 const LEGAL_TASK_TRANSITIONS = {

package/lib/engine-verbosity.js

@@ -0,0 +1,42 @@
+// Shared streaming-verbosity + extended-thinking config for sub-agent engines.
+//
+// One knob controls how much of an engine's work madarX surfaces live in the
+// chat. It applies engine-agnostically: the Claude Code CLI, the Anthropic
+// Messages API, and (best-effort) Ollama all read the same setting.
+//
+//   MADARX_CC_STREAM_VERBOSITY = 'quiet' | 'thinking' | 'full'   (default 'thinking')
+//     quiet    — legacy behavior: only complete assistant text + tool start/stop.
+//     thinking — stream token-by-token text, the model's reasoning, and rich
+//                tool detail (full input + output preview + duration).
+//     full     — everything in `thinking`, plus raw engine envelopes routed to
+//                the client's "engine log" disclosure for deep debugging.
+//
+// The name keeps the `CC_` prefix for backwards compatibility with the first
+// Claude-Code-only iteration; it now governs every engine.
+
+const VALID = new Set(['quiet', 'thinking', 'full']);
+
+export function getStreamVerbosity() {
+  const v = String(process.env.MADARX_CC_STREAM_VERBOSITY || 'thinking').trim().toLowerCase();
+  return VALID.has(v) ? v : 'thinking';
+}
+
+export function verbosityStreamsThinking(v = getStreamVerbosity()) {
+  return v === 'thinking' || v === 'full';
+}
+
+export function verbosityIsFull(v = getStreamVerbosity()) {
+  return v === 'full';
+}
+
+// Extended-thinking budget in tokens for engines where we control the request
+// (Anthropic Messages API directly; the spawned Claude Code CLI via the
+// MAX_THINKING_TOKENS env var, best-effort). 0 disables thinking. Anthropic
+// requires a floor of 1024 when enabled — callers clamp up to that. Default
+// 4000; override with MADARX_THINKING_BUDGET_TOKENS.
+export function thinkingBudgetTokens(v = getStreamVerbosity()) {
+  if (!verbosityStreamsThinking(v)) return 0;
+  const raw = Number(process.env.MADARX_THINKING_BUDGET_TOKENS);
+  if (Number.isFinite(raw) && raw >= 0) return Math.floor(raw);
+  return 4000;
+}

package/lib/env-file.js

@@ -20,6 +20,9 @@ export const ENV_DEFINITIONS = [
   // secrets vault, not here.
   { name: 'MADARX_WEB_PROVIDER', label: 'Web Provider Override', group: 'Web', description: 'Force a specific search provider: firecrawl, searxng, brave, or fetch.' },
 
+  // --- Browser tool config ---
+  { name: 'MADARX_BROWSER_HEADED', label: 'Visible Browser (headed)', group: 'Browser', description: 'Set to 1 to open a VISIBLE browser window you can watch the agent drive (click/type). Prefers your installed Chrome, falls back to bundled Chromium. Leave blank or 0 for headless. Applies on the next browser launch.' },
+
   // --- File tool config ---
   { name: 'MADARX_ALLOWED_ROOTS', label: 'Allowed File Roots', group: 'Local Tools', description: 'Colon-separated absolute paths the file adapter may read/write.' },
   { name: 'MADARX_FILE_READ_MAX_BYTES', label: 'Max File Read Bytes', group: 'Local Tools', description: 'Maximum bytes returned by a single file_read call (default: 1MB).' },