Front Door: Hardening Walkthrough

-- Create the app_runtime role if it does not exist yet.
--
-- Deliberately breaks the rule of not editing applied migrations: without this block, a fresh database fails at the GRANTs below because nothing creates the role.
-- Safe because Drizzle never re-runs an applied migration, and on any database where the role already
-- exists this block does nothing — so no two databases can end up different. On a fresh database it creates
-- the role before the GRANTs below need it.
DO $$
BEGIN
  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'app_runtime') THEN
    CREATE ROLE app_runtime
      -- create role without login capability to avoid committing a password to source control.
      -- admin can enable login by setting a password manually before setting up connection strings in the app.
      -- ALTER ROLE app_runtime WITH LOGIN PASSWORD '<strong-password>';
      NOLOGIN
      NOSUPERUSER
      NOBYPASSRLS
      NOCREATEDB
      NOCREATEROLE
      NOREPLICATION;
  END IF;
END
$$;

ALTER ROLE app_runtime WITH LOGIN PASSWORD 'your-strong-password';

git mv packages/core/src/db/index.ts packages/core/src/db/unsafe.ts

const client = postgres(url, { prepare: false });

import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';
import { authUsers } from 'drizzle-orm/supabase';

export const profiles = pgTable('profiles', {
  id: uuid('id')
    .primaryKey()
    .references(() => authUsers.id, { onDelete: 'cascade' }),
  email: text('email').notNull(),
  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
});

pnpm --filter @sidekick/core db:generate --name=profiles_auth_users_fk

ALTER TABLE "profiles" ADD CONSTRAINT "profiles_id_users_id_fk" FOREIGN KEY ("id") REFERENCES "auth"."users"("id") ON DELETE cascade ON UPDATE no action;

pnpm --filter @sidekick/core db:generate --custom --name=profile_creation_trigger

-- Creates a public.profiles row whenever Supabase Auth creates a user.
--
-- Originally created by hand in the Supabase SQL editor; versioned here so
-- fresh databases get it. Idempotent: on databases that already have the
-- function and trigger, this replaces them with identical behavior plus the
-- search_path fix below.
--
-- SECURITY DEFINER: runs as the function owner (postgres), not as Supabase
-- Auth's role. The insert succeeds despite FORCE ROW LEVEL SECURITY on
-- profiles only because postgres has BYPASSRLS — no user context exists
-- during signup.
--
-- search_path = '': a privileged function must not resolve names through a
-- caller-controlled search path. Every object is therefore schema-qualified.
--
-- Known limit: auth.users.email is nullable but profiles.email is NOT NULL,
-- so phone or anonymous sign-ins would fail here. Email signup only for now.
CREATE OR REPLACE FUNCTION public.create_profile_for_new_user()
  RETURNS trigger
  LANGUAGE plpgsql
  SECURITY DEFINER
  SET search_path = ''
AS $$
BEGIN
  INSERT INTO public.profiles (id, email)
  VALUES (NEW.id, NEW.email)
  ON CONFLICT DO NOTHING;
  RETURN NEW;
END;
$$;

CREATE OR REPLACE TRIGGER on_auth_user_created
  AFTER INSERT ON auth.users
  FOR EACH ROW
  EXECUTE FUNCTION public.create_profile_for_new_user();

SELECT count(*) FROM public.profiles p
WHERE NOT EXISTS (SELECT 1 FROM auth.users u WHERE u.id = p.id);

pnpm --filter @sidekick/core db:migrate

pnpm --filter @sidekick/core add server-only

import 'server-only';

import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';

import * as schema from './schema';

const url = process.env.DATABASE_URL;

if (!url) {
  throw new Error('Missing DATABASE_URL environment variable');
}

// DATABASE_URL points at Supavisor in transaction mode (port 6543), which does
// not keep you on one Postgres connection between transactions, so named
// prepared statements must be off (Supabase requirement).
// Do NOT set max_pipeline: 0 — postgres.js then never reserves a connection
// for a transaction, and every transaction (including withRLS) fails with
// UNSAFE_TRANSACTION. Caught by tests/integration/rls.test.ts.
const client = postgres(url, { prepare: false });

// UNSAFE: queries on this client run without a user context. As app_runtime
// they fail closed (RLS returns zero rows), but nothing ties them to a caller.
// Only for building safe wrappers such as withRLS — ESLint enforces this, and
// the package `exports` map deliberately does not expose this file.
export const unsafeDb = drizzle(client, { schema });

import { sql } from 'drizzle-orm';

import { unsafeDb } from './unsafe';

export type RlsTx = Parameters<Parameters<typeof unsafeDb.transaction>[0]>[0];

export async function withRLS<T>(userId: string, fn: (tx: RlsTx) => Promise<T>): Promise<T> {
  return unsafeDb.transaction(async (tx) => {
    await tx.execute(sql`select set_config('app.current_user_id', ${userId}, true)`);
    return fn(tx);
  });
}

// Safe entry point: every user-data query runs inside withRLS.
export { withRLS, type RlsTx } from './rls';

// `paths` match an import's exact text; `patterns` take globs. Both match the
// text as written, not the resolved file — so `**/unsafe` (not `**/db/unsafe`)
// is needed to also catch `./unsafe` and `../unsafe` from inside db/.
const adminClientMessage =
  'The Supabase admin client bypasses RLS. If this is truly needed, add a reviewed per-file exception in eslint.config.js.';

const adminClientPathBan = {
  name: '@sidekick/core/supabase/admin',
  message: adminClientMessage,
};

const adminClientPatternBan = {
  group: ['**/supabase/admin'],
  message: adminClientMessage,
};

const unsafeDbPatternBan = {
  group: ['**/unsafe'],
  message:
    'The raw database client runs queries without a user context. Use withRLS from "@sidekick/core/db" instead.',
};

  {
    // Restricted imports across the whole codebase:
    // - CSS-in-JS libraries (use CSS modules)
    // - the raw database client (use withRLS) and the RLS-bypassing admin client
    // Flat config replaces, not merges, a rule's options per block — any later
    // block that sets no-restricted-imports must repeat every ban it keeps.
    files: ['**/*.ts', '**/*.tsx'],
    rules: {
      'no-restricted-imports': [
        'error',
        {
          paths: [...cssInJsBans, adminClientPathBan],
          patterns: [unsafeDbPatternBan, adminClientPatternBan],
        },
      ],
    },
  },
  {
    // The single file allowed to import the raw database client: withRLS is
    // built on it. Every other ban still applies here.
    files: ['packages/core/src/db/rls.ts'],
    rules: {
      'no-restricted-imports': [
        'error',
        {
          paths: [...cssInJsBans, adminClientPathBan],
          patterns: [adminClientPatternBan],
        },
      ],
    },
  },

printf "import '../db/unsafe';\nimport './unsafe';\nimport '../supabase/admin';\n" | pnpm exec eslint --stdin --stdin-filename packages/core/src/api/x.ts

brew install postgresql@17

-- Stand-ins for the Supabase-managed pieces our migrations depend on, so the
-- RLS proof test can run against a throwaway local Postgres. Mirrors what we
-- verified on the live project (2026-10-14): postgres is NOT a superuser but
-- has CREATEROLE and BYPASSRLS; supabase_auth_admin owns auth.users and has
-- neither. Run as the throwaway cluster's superuser, before migrations.

-- Supabase's migration role
CREATE ROLE postgres LOGIN CREATEROLE BYPASSRLS;
ALTER DATABASE postgres OWNER TO postgres;  -- lets it create objects in public

-- Supabase Auth's role and its users table (only the columns we use)
CREATE ROLE supabase_auth_admin LOGIN NOBYPASSRLS;
CREATE SCHEMA auth AUTHORIZATION supabase_auth_admin;
CREATE TABLE auth.users (id uuid PRIMARY KEY, email text);
ALTER TABLE auth.users OWNER TO supabase_auth_admin;

-- Same rights Supabase gives postgres, so migrations 0004/0005 can add the
-- foreign key and the trigger
GRANT USAGE ON SCHEMA auth TO postgres;
GRANT REFERENCES, TRIGGER ON auth.users TO postgres;

#!/usr/bin/env bash
# Runs a command against a throwaway Postgres built from our migrations:
#   tests/with-test-db.sh <command...>
# Starts a temporary cluster, applies the Supabase stand-ins and all
# migrations, enables app_runtime login, exports connection URLs, runs the
# command, then deletes the cluster — even if the command fails.
# Requires initdb, pg_ctl and psql of the PostgreSQL major version in PG_MAJOR.
set -euo pipefail

# macOS Postgres refuses to start without a locale; Linux (CI) has a usable default
if [[ "$(uname)" == "Darwin" ]]; then
  export LC_ALL="${LC_ALL:-en_US.UTF-8}"
fi

# PostgreSQL major version must match production (Supabase). Bump in one place
# here — and in .github/workflows/ci.yml — when Supabase upgrades.
PG_MAJOR=17

# Use that version's tools from the usual install locations if present
# (Homebrew on Apple Silicon or Intel, Debian/Ubuntu packages), else PATH.
for dir in "/opt/homebrew/opt/postgresql@$PG_MAJOR/bin" \
           "/usr/local/opt/postgresql@$PG_MAJOR/bin" \
           "/usr/lib/postgresql/$PG_MAJOR/bin"; do
  if [[ -x "$dir/initdb" ]]; then
    PATH="$dir:$PATH"
    break
  fi
done

found="$(initdb --version 2>/dev/null | grep -oE '[0-9]+' | head -1 || true)"
if [[ "$found" != "$PG_MAJOR" ]]; then
  echo "with-test-db.sh: PostgreSQL $PG_MAJOR tools required (found: ${found:-none})." >&2
  echo "  macOS: brew install postgresql@$PG_MAJOR" >&2
  exit 1
fi

PORT="${TEST_DB_PORT:-54329}"            # avoids a local Postgres on 5432
HERE="$(cd "$(dirname "$0")" && pwd)"
CORE="$(cd "$HERE/.." && pwd)"
DATA="$(mktemp -d)"

cleanup() {
  pg_ctl -D "$DATA" stop -m fast >/dev/null 2>&1 || true
  rm -rf "$DATA"
}
trap cleanup EXIT

url() { echo "postgresql://[email protected]:$PORT/postgres"; }

# Local-only cluster: trust auth, TCP on 127.0.0.1, no Unix socket
initdb -D "$DATA" -U admin --auth=trust >/dev/null
pg_ctl -D "$DATA" -o "-p $PORT -k '' -c listen_addresses=127.0.0.1" \
  -l "$DATA/server.log" -w start >/dev/null

psql "$(url admin)" -v ON_ERROR_STOP=1 -q -f "$HERE/supabase-stub.sql"
(cd "$CORE" && DATABASE_DIRECT_URL="$(url postgres)" drizzle-kit migrate >/dev/null)

# The out-of-band step from the app_runtime decision note
psql "$(url admin)" -v ON_ERROR_STOP=1 -q \
  -c "ALTER ROLE app_runtime WITH LOGIN PASSWORD 'test-only'"

export DATABASE_URL="postgresql://app_runtime:[email protected]:$PORT/postgres"
export TEST_AUTH_DATABASE_URL="$(url supabase_auth_admin)"

"$@"

chmod +x packages/core/tests/with-test-db.sh

pnpm --filter @sidekick/core exec tests/with-test-db.sh bash -c 'psql "$DATABASE_URL" -qtAc "select current_user, (select count(*) from public.profiles)"'

pnpm --filter @sidekick/core add -D vitest

// Test-only stand-in for the `server-only` package. The real package throws
// unless it's resolved with Next.js's "react-server" condition, which a test
// runner doesn't use. vitest.config.ts points `server-only` here instead.
export {};

import { fileURLToPath } from 'node:url';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  resolve: {
    alias: {
      'server-only': fileURLToPath(new URL('./tests/stubs/server-only.ts', import.meta.url)),
    },
  },
  test: {
    include: ['src/**/*.test.ts', 'tests/**/*.test.ts'],
  },
});

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "dist"
  },
  "include": ["src", "tests", "drizzle.config.ts", "vitest.config.ts"]
}

{
  "extends": "./tsconfig.json",
  "include": ["src"],
  "exclude": ["src/**/*.test.{ts,tsx}"]
}

import { randomUUID } from 'node:crypto';
import postgres from 'postgres';
import { afterAll, beforeAll, describe, expect, it } from 'vitest';

import { withRLS } from '../../src/db';
import { profiles } from '../../src/db/schema';

// Proves row-level security on the runtime connection. Runs inside
// tests/with-test-db.sh, which builds a fresh database from our
// migrations and exports these connection URLs:
// - DATABASE_URL: app_runtime, the role the app and withRLS use
// - TEST_AUTH_DATABASE_URL: supabase_auth_admin, which creates users the way
//   Supabase Auth does

function requireEnv(name: string) {
  const value = process.env[name];
  if (!value) {
    throw new Error(`${name} is not set; run this test through tests/with-test-db.sh`);
  }

  return value;
}

const authDb = postgres(requireEnv('TEST_AUTH_DATABASE_URL'), { max: 1 });
const runtimeDb = postgres(requireEnv('DATABASE_URL'), { max: 1 });

const userA = randomUUID();
const userB = randomUUID();

beforeAll(async () => {
  await authDb`INSERT INTO auth.users
      (id, email)
   VALUES
      (${userA}, '[email protected]'),
      (${userB}, '[email protected]')
   `;
});

afterAll(async () => {
  await authDb.end();
  await runtimeDb.end();
});

describe('RLS on profiles', () => {
  it.each([
    ['userA', userA],
    ['userB', userB],
  ])('shows %s only their own profile', async (userKey, userId) => {
    const rows = await withRLS(userId, (tx) => tx.select().from(profiles));
    expect(rows).toHaveLength(1);
    expect(rows[0].id).toBe(userId);
  });

  it('returns zero rows without a user context when run as app_runtime', async () => {
    const userProfilesVisibleToUserA = await withRLS(userA, (tx) => tx.select().from(profiles));
    expect(userProfilesVisibleToUserA).toHaveLength(1);

    const rows = await runtimeDb`SELECT 1 FROM profiles`;
    expect(rows).toHaveLength(0);
  });
});

    "build": "tsc -p tsconfig.build.json",
    "test": "vitest run src --passWithNoTests",
    "test:integration": "tests/with-test-db.sh vitest run tests/integration"

    "test": "turbo test",
    "test:integration": "turbo test:integration"

    "test": {},
    "test:integration": {
      "cache": false
    }

pnpm test && pnpm test:integration && pnpm build

name: CI

on:
  push:
    branches: [main]
  pull_request:

# A newer push to the same branch cancels the older, still-running check
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

# Read-only token: CI only needs to check out code
permissions:
  contents: read

jobs:
  checks:
    # Pinned, not ubuntu-latest: -latest moves to new images silently, and the
    # preinstalled tools inside it (Node, PostgreSQL, …) change with it
    runs-on: ubuntu-24.04
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-node@v7
        with:
          node-version-file: .nvmrc

      # pnpm version and hash come from package.json "packageManager"
      - name: Enable Corepack
        run: corepack enable

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - run: pnpm prettier:check
      - run: pnpm lint
      - run: pnpm typecheck
      - run: pnpm build
      - run: pnpm test
      # Production (Supabase) runs PostgreSQL 17; the runner image ships 16.
      # Install 17's tools from the official PostgreSQL apt repository (PGDG).
      # tests/with-test-db.sh finds them in /usr/lib/postgresql/17/bin.
      - name: Install PostgreSQL 17 tools
        run: |
          sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y
          sudo apt-get install -y --no-install-recommends postgresql-17
      - run: pnpm test:integration

# Found in: Supabase Dashboard → Connect (project URL, keys, connection strings)

# Project URL. Public.
# https://<project-ref>.supabase.co
NEXT_PUBLIC_SUPABASE_URL=

# Publishable key (sb_publishable_…). Public by design; replaces the legacy
# anon key. RLS, not this key, protects user data.
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=

# Secret key (sb_secret_…). SERVER-ONLY — bypasses RLS. Replaces the legacy
# service_role key. Never commit it; never give it a NEXT_PUBLIC_ prefix.
SUPABASE_SECRET_KEY=

# Runtime connection — used by the app (packages/core/src/db/unsafe.ts).
# Role: app_runtime (non-superuser, RLS enforced). SERVER-ONLY.
# Supavisor transaction mode, port 6543: requires prepare: false.
# postgresql://app_runtime.<project-ref>:<app_runtime-password>@<region>.pooler.supabase.com:6543/postgres
DATABASE_URL=

# Migration connection — used only by drizzle-kit (pnpm db:generate / db:migrate).
# Role: postgres (schema owner, bypasses RLS). SERVER-ONLY; never set in Vercel.
# Supavisor session mode, port 5432 — despite the name, NOT Supabase's "Direct
# connection" (db.<project-ref>.supabase.co:5432), which is IPv6-only unless the
# IPv4 add-on is enabled. Session mode keeps one Postgres connection per client,
# so it is safe for migrations.
# postgresql://postgres.<project-ref>:<database-password>@<region>.pooler.supabase.com:5432/postgres
DATABASE_DIRECT_URL=

  "scripts": {
    "lint": "eslint .",
    "typecheck": "tsc -p tsconfig.json --noEmit"
  },

      // Element patterns are matched relative to this root. `pnpm lint` runs
      // ESLint from inside each package (cwd = packages/core, …), where the
      // default root (cwd) makes every file "unknown" and boundaries silently
      // enforces nothing — so the repo root is set explicitly.
      'boundaries/root-path': import.meta.dirname,
      // A file belongs to the first element whose pattern matches, so specific
      // patterns come before the catch-all `packages/*`.
      'boundaries/elements': [
        { type: 'app', pattern: 'apps/*' },
        { type: 'feature', pattern: 'packages/features/*' },
        { type: 'registry', pattern: 'packages/features-registry' },
        { type: 'tooling', pattern: 'packages/eslint-plugin-sidekick' },
        // core, ui, copy
        { type: 'foundation', pattern: 'packages/*' },
      ],

      // Dependency direction: apps → registry → features → foundation.
      // Everything not allowed here is disallowed. Imports within one package
      // are never checked. Foundation packages (core, ui, copy) and tooling
      // import no other workspace package; loosen deliberately with a new rule.
      'boundaries/dependencies': [
        'error',
        {
          default: 'disallow',
          rules: [
            {
              from: { type: 'app' },
              allow: { to: { type: ['feature', 'registry', 'foundation'] } },
            },
            {
              from: { type: 'registry' },
              allow: { to: { type: ['feature', 'foundation'] } },
            },
            {
              from: { type: 'feature' },
              allow: { to: { type: 'foundation' } },
            },
          ],
        },
      ],

cd packages/core && printf "import '../../copy/src/app';\n" | pnpm exec eslint --stdin --stdin-filename src/x.ts; cd ../..

import type { Rule, Scope } from 'eslint';
import type * as ESTree from 'estree';

/**
 * Requires every Next.js App Router route handler to be wrapped in withApiGuard.
 *
 * The proxy deliberately does not authenticate /api routes; withApiGuard is
 * the only place authentication, feature entitlement, API-key scopes and the
 * RLS context are applied. A handler exported any other way is publicly
 * reachable, so this rule fails closed: anything it cannot verify is reported.
 *
 * Allowed:
 *   export const GET = withApiGuard(handler, options);
 *   (withApiGuard must be an imported binding, not a local look-alike)
 *
 * Reported:
 *   export async function GET() {}           function declaration
 *   export const GET = handler;               not wrapped
 *   export let GET = withApiGuard(handler);   reassignable
 *   export { handler as GET };                cannot be verified
 *   export * from './handlers';               cannot be verified
 *
 * Non-method exports (e.g. `export const dynamic = 'force-dynamic'`) are ignored.
 * Wired up only for app/**\/route.* files via eslint.config.js.
 */
const HTTP_METHODS = new Set(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']);
const GUARD_NAME = 'withApiGuard';

function isImportedGuardCall(
  init: ESTree.Expression | null | undefined,
  scope: Scope.Scope,
): boolean {
  if (init?.type !== 'CallExpression') return false;
  if (init.callee.type !== 'Identifier' || init.callee.name !== GUARD_NAME) return false;

  let current: Scope.Scope | null = scope;
  while (current) {
    const variable = current.set.get(GUARD_NAME);
    if (variable) return variable.defs.some((def) => def.type === 'ImportBinding');
    current = current.upper;
  }
  return false;
}

export const requireApiGuard: Rule.RuleModule = {
  meta: {
    type: 'problem',
    docs: {
      description: `Require route handlers to be exported as \`export const METHOD = ${GUARD_NAME}(...)\`.`,
    },
    messages: {
      notGuarded: `Route handler {{method}} must be exported as \`export const {{method}} = ${GUARD_NAME}(handler, options)\`, with ${GUARD_NAME} imported. Unguarded API routes are publicly reachable.`,
      unverifiable:
        'Route files may only export handlers as `export const METHOD = withApiGuard(...)`. This export form cannot be verified as guarded.',
    },
    schema: [],
  },
  create(context): Rule.RuleListener {
    return {
      ExportAllDeclaration(node: ESTree.ExportAllDeclaration) {
        context.report({ node, messageId: 'unverifiable' });
      },
      ExportNamedDeclaration(node: ESTree.ExportNamedDeclaration) {
        for (const specifier of node.specifiers) {
          const exported =
            specifier.exported.type === 'Identifier'
              ? specifier.exported.name
              : String(specifier.exported.value);
          if (HTTP_METHODS.has(exported)) {
            context.report({ node: specifier, messageId: 'unverifiable' });
          }
        }

        const declaration = node.declaration;
        if (!declaration) return;

        if (declaration.type === 'FunctionDeclaration' || declaration.type === 'ClassDeclaration') {
          const method = declaration.id?.name;
          if (method && HTTP_METHODS.has(method)) {
            context.report({ node: declaration, messageId: 'notGuarded', data: { method } });
          }
          return;
        }

        if (declaration.type !== 'VariableDeclaration') return;

        const scope = context.sourceCode.getScope(node);
        for (const declarator of declaration.declarations) {
          if (declarator.id.type !== 'Identifier') continue;
          const method = declarator.id.name;
          if (!HTTP_METHODS.has(method)) continue;

          const guarded =
            declaration.kind === 'const' && isImportedGuardCall(declarator.init, scope);
          if (!guarded) {
            context.report({ node: declarator, messageId: 'notGuarded', data: { method } });
          }
        }
      },
    };
  },
};

pnpm --filter @sidekick/eslint-plugin-sidekick add -D vitest

// Composed per block: flat config replaces no-restricted-syntax per block.
const serverActionBan = {
  selector: 'ExpressionStatement[directive="use server"]',
  message:
    'Server Actions are not allowed: each one is a public POST endpoint outside withApiGuard. Go through the public API instead (see the server-actions note).',
};

const pagesRouterBan = {
  selector: 'Program',
  message:
    'The Pages Router is not used: any file under pages/api becomes an unguarded endpoint. Use an App Router route handler with withApiGuard.',
};

const pageExtensionsBan = {
  selector: 'Property[key.name="pageExtensions"], Property[key.value="pageExtensions"]',
  message:
    'pageExtensions changes which files Next.js serves as routes, so sidekick/require-api-guard would miss them. Keep the default.',
};

  {
    // Every App Router route handler must be wrapped in withApiGuard: the proxy
    // does not authenticate /api routes, so an unguarded handler is public.
    // Matches Next.js route files in every app — not utilities such as
    // utils/route.ts. Covers both app/ and src/app/ layouts.
    files: ['apps/*/src/app/**/route.{ts,tsx,js,jsx}', 'apps/*/app/**/route.{ts,tsx,js,jsx}'],
    plugins: { sidekick: sidekickPlugin },
    rules: {
      'sidekick/require-api-guard': 'error',
    },
  },
  {
    files: ['**/*.{ts,tsx,js,jsx,mjs,cjs}'],
    rules: {
      'no-restricted-syntax': ['error', serverActionBan],
    },
  },
  {
    files: ['apps/*/pages/**', 'apps/*/src/pages/**'],
    rules: {
      'no-restricted-syntax': ['error', serverActionBan, pagesRouterBan],
    },
  },
  {
    files: ['apps/*/next.config.*'],
    rules: {
      'no-restricted-syntax': ['error', serverActionBan, pageExtensionsBan],
    },
  },

// Verifies, after `next build`, that every endpoint Next.js will serve enters
// through an App Router route handler — the only files the
// sidekick/require-api-guard lint rule checks for withApiGuard.
//
// Lint rules check what we wrote; this checks what Next.js built, so it also
// catches entry points nobody anticipated. It fails the build on:
//   - any Server Action (each is a public POST endpoint outside withApiGuard)
//   - any Pages Router entry beyond Next.js's built-in error pages
//   - any App Router route with no route.* source file (e.g. a code-generated
//     metadata route such as sitemap.ts). Static files such as favicon.ico
//     are allowed: they serve a file and run no code.
import console from 'node:console';
import { existsSync, readFileSync, statSync } from 'node:fs';
import { join } from 'node:path';
import process from 'node:process';

const appDir = process.cwd();
const serverDir = join(appDir, '.next', 'server');
const sourceRoot = [join(appDir, 'src', 'app'), join(appDir, 'app')].find((dir) => existsSync(dir));

const BUILT_IN_PAGES = new Set(['/404', '/500', '/_app', '/_document', '/_error']);
const ROUTE_SOURCES = ['route.ts', 'route.tsx', 'route.js', 'route.jsx'];
const CODE_FILE = /\.(ts|tsx|js|jsx|mjs|cjs)$/;

function readManifest(name) {
  return JSON.parse(readFileSync(join(serverDir, name), 'utf8'));
}

function isStaticFile(path) {
  return existsSync(path) && statSync(path).isFile() && !CODE_FILE.test(path);
}

const problems = [];

const actions = readManifest('server-reference-manifest.json');
const actionCount = Object.keys(actions.node ?? {}).length + Object.keys(actions.edge ?? {}).length;
if (actionCount > 0) {
  problems.push(`${actionCount} Server Action(s) found. Server Actions are not allowed.`);
}

for (const route of Object.keys(readManifest('pages-manifest.json'))) {
  if (!BUILT_IN_PAGES.has(route)) {
    problems.push(`Pages Router entry "${route}". The Pages Router is not used.`);
  }
}

for (const [route, output] of Object.entries(readManifest('app-paths-manifest.json'))) {
  if (!route.endsWith('/route')) continue; // pages render HTML; not API entry points

  const segmentPath = output.replace(/^app\/?/, '').replace(/\/?route\.js$/, '');
  const source = join(sourceRoot, segmentPath);
  const hasRouteFile = ROUTE_SOURCES.some((file) => existsSync(join(source, file)));

  if (!hasRouteFile && !isStaticFile(source)) {
    problems.push(
      `"${route}" is served but has no route.* source file, so withApiGuard is not lint-checked.`,
    );
  }
}

if (problems.length > 0) {
  console.error('verify-endpoints: unguarded entry points in the build:');
  for (const problem of problems) console.error(`  - ${problem}`);
  process.exit(1);
}

console.log('verify-endpoints: every served endpoint is a lint-checked route handler.');

    "build": "dotenv -e ../../.env.local -- next build && node scripts/verify-endpoints.mjs",

// Makes docs/ — and AGENTS.md, which links into it — resolve in a fresh clone.
//
// docs/ is a symlink to ../arkive/sources/docs: Sidekick's canonical docs live
// in the public Arkive repo. On a fresh machine or in a cloud agent
// environment that sibling checkout is missing, so agents would start without
// AGENTS.md or the plans. This script clones Arkive next to this repo,
// downloading only sources/docs.
//
// Runs on `pnpm install` (root postinstall); also: `pnpm docs:setup`.
// - Does nothing when docs/ already resolves.
// - Skipped in CI and on Vercel (nothing there reads docs/), or when
//   SIDEKICK_SKIP_DOCS is set.
// - Never fails the install: problems are reported as warnings.
import { spawnSync } from 'node:child_process';
import console from 'node:console';
import { existsSync } from 'node:fs';
import { dirname, join, resolve } from 'node:path';
import process from 'node:process';
import { fileURLToPath } from 'node:url';

const ARKIVE_REPO = 'https://github.com/mehtapratik/arkive.git';
const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const arkiveDir = resolve(repoRoot, '..', 'arkive');
const vault = join(arkiveDir, 'sources', 'docs');

function done(message) {
  console.log(`setup-docs: ${message}`);
  process.exit(0);
}

function warn(message) {
  console.warn(`setup-docs: ${message}`);
  process.exit(0);
}

if (process.env.CI || process.env.VERCEL) done('skipped in CI (nothing there reads docs/).');
if (process.env.SIDEKICK_SKIP_DOCS) done('skipped (SIDEKICK_SKIP_DOCS is set).');
if (existsSync(vault)) done(`docs/ resolves to ${vault}.`);
if (existsSync(arkiveDir)) {
  warn(`${arkiveDir} exists but has no sources/docs; left untouched, so docs/ will not resolve.`);
}

console.log(`setup-docs: cloning Arkive (sources/docs only) into ${arkiveDir}`);
const git = (args) => spawnSync('git', args, { stdio: 'inherit' }).status === 0;
const cloned =
  git(['clone', '--filter=blob:none', '--sparse', ARKIVE_REPO, arkiveDir]) &&
  git(['-C', arkiveDir, 'sparse-checkout', 'set', 'sources/docs']);

if (!cloned || !existsSync(vault)) {
  warn(
    `could not fetch the docs; the install itself succeeded. Run \`pnpm docs:setup\` later, or clone ${ARKIVE_REPO} next to this repo.`,
  );
}

done('docs/ and AGENTS.md now resolve.');

    "docs:setup": "node scripts/setup-docs.mjs",
    "postinstall": "node scripts/setup-docs.mjs"

  confirmAccountPageTitle: 'Confirm your email',
  confirmEmail: (email: string) =>
    `If this email address is valid, you will receive a confirmation email at ${email}. Please check your inbox and follow the instructions to complete the sign-up process.`,
  alreadyConfirmed: `Already confirmed your email?`,

  const handleSubmit = async (values: typeof form.values) => {
    const { error, data } = await supabase.auth.signUp(values);

    if (error) {
      notifications.show({
        color: 'red',
        message: genericErrorCopy,
      });
      return;
    }
    if (!data?.session) {
      setUnverifiedEmail(values.email);
      return;
    }
    push('/dashboard');
  };

nvm install 22

nvm alias default 22

corepack enable

22

  "engines": {
    "node": "22.x"
  },

# With `engineStrict: true`, pnpm refuses to install when the running Node doesn’t
# satisfy an engines field, ours or a dependency’s.
engineStrict: true

pnpm --filter web add -D @types/node@^22

pnpm --filter @sidekick/core add -D @types/node@^22

pnpm add -D -w @eslint/js@^9

pnpm add -D -w husky lint-staged

pnpm exec husky init

pnpm exec lint-staged

  "lint-staged": {
    "*.{js,jsx,ts,tsx,json,md}": "prettier --write"
  }

# Generated by tools — never hand-formatted
apps/web/next-env.d.ts
packages/core/src/db/migrations/meta/

curl -s https://api.github.com/repos/mehtapratik/sidekick/rules/branches/main

pnpm add -D -w eslint-plugin-react-hooks @next/[email protected]

pnpm --filter web remove eslint-config-next

  {
    files: ['**/*.ts', '**/*.tsx'],
    rules: {
      '@typescript-eslint/consistent-type-imports': [
        'error',
        { prefer: 'type-imports', fixStyle: 'separate-type-imports' },
      ],
      '@typescript-eslint/no-import-type-side-effects': 'error',
    },
  },
  {
    files: ['**/*.ts', '**/*.tsx'],
    languageOptions: {
      parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname },
    },
    rules: {
      '@typescript-eslint/no-floating-promises': 'error',
      '@typescript-eslint/no-misused-promises': [
        'error',
        { checksVoidReturn: { attributes: false } },
      ],
      '@typescript-eslint/await-thenable': 'error',
      '@typescript-eslint/consistent-type-exports': 'error',
    },
  },
  {
    files: ['**/*.{ts,tsx,js,jsx,mjs,cjs}'],
    rules: {
      'eqeqeq': ['error', 'always', { null: 'ignore' }],
      'no-console': ['error', { allow: ['warn', 'error'] }],
    },
  },
  {
    files: ['**/*.{ts,tsx,js,jsx,mjs,cjs}'],
    plugins: { import: importPlugin },
    rules: {
      'import/no-duplicates': 'error',
      'import/first': 'error',
      'import/newline-after-import': 'error',
      'import/no-self-import': 'error',
      'import/no-cycle': 'error',
    },
  },
  {
    ...reactHooks.configs.flat.recommended,
    files: ['apps/web/**/*.{ts,tsx}', 'packages/ui/**/*.{ts,tsx}'],
  },
  {
    files: ['apps/web/**/*.{ts,tsx,js,jsx}'],
    plugins: { '@next/next': nextPlugin },
    settings: { next: { rootDir: 'apps/web' } },
    rules: {
      ...nextPlugin.configs.recommended.rules,
      ...nextPlugin.configs['core-web-vitals'].rules,
      // Checks links to Pages Router pages only; the Pages Router is banned.
      '@next/next/no-html-link-for-pages': 'off',
    },
  },

pnpm outdated -r

npm view typescript-eslint peerDependencies --json

git switch -c deps/minor-patch

pnpm up -r --latest '!eslint' '!@eslint/js' '!typescript' '!@types/node' '!eslint-plugin-boundaries'

nvm install 24 && nvm alias default 24 && corepack enable

pnpm --filter web add -D @types/node@^24

pnpm --filter @sidekick/core add -D @types/node@^24

pnpm add -D -w typescript@^6.0.3

pnpm --filter web add -D typescript@^6.0.3

pnpm --filter @sidekick/eslint-plugin-sidekick add -D typescript@^6.0.3

pnpm turbo build --force

pnpm remove -w eslint-plugin-import

pnpm add -D -w eslint@^10 @eslint/js@^10 eslint-plugin-import-x@^4 eslint-plugin-boundaries@^7

pnpm --filter web add -D eslint@^10 && pnpm --filter @sidekick/eslint-plugin-sidekick add -D eslint@^10

import { createTypeScriptImportResolver } from 'eslint-import-resolver-typescript';
import importX from 'eslint-plugin-import-x';

const tsProjects = [
  'tsconfig.base.json',
  'apps/*/tsconfig.json',
  'packages/*/tsconfig.json',
  'packages/features/*/tsconfig.json',
];

      'import/resolver': {
        typescript: {
          alwaysTryTypes: true,
          noWarnOnMultipleProjects: true,
          project: tsProjects,
        },
      },
      // import-x only parses these extensions when following imports (no-cycle,
      // no-duplicates across files); its default omits TypeScript.
      'import-x/extensions': ['.ts', '.tsx', '.cts', '.mts', '.js', '.jsx', '.cjs', '.mjs'],
      'import-x/resolver-next': [
        createTypeScriptImportResolver({
          alwaysTryTypes: true,
          noWarnOnMultipleProjects: true,
          project: tsProjects,
        }),
      ],

          policies: [
            {
              from: { element: { type: 'app' } },
              allow: { to: { element: { type: ['feature', 'registry', 'foundation'] } } },
            },
            {
              from: { element: { type: 'registry' } },
              allow: { to: { element: { type: ['feature', 'foundation'] } } },
            },
            {
              from: { element: { type: 'feature' } },
              allow: { to: { element: { type: 'foundation' } } },
            },
          ],

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "timezone": "America/New_York",
  "schedule": ["before 6am on monday"],
  "labels": ["dependencies"],
  "rangeStrategy": "bump",
  "minimumReleaseAge": "3 days",
  "internalChecksFilter": "strict",
  "platformAutomerge": true,
  "postUpdateOptions": ["pnpmDedupe"],
  "lockFileMaintenance": {
    "enabled": true,
    "automerge": true,
    "schedule": ["before 6am on monday"]
  },
  "packageRules": [
    {
      "description": "Minor and patch updates: one grouped PR, merged automatically once the CI `checks` job passes",
      "matchUpdateTypes": ["minor", "patch"],
      "groupName": "all minor and patch",
      "automerge": true
    },
    {
      "description": "Majors: one PR each, reviewed by a person, never merged automatically",
      "matchUpdateTypes": ["major"],
      "automerge": false
    },
    {
      "description": "Node is major-only on purpose (.nvmrc `24`, engines `24.x`): minor and patch versions arrive by themselves through nvm, setup-node and Vercel, and an exact version would make pnpm's engineStrict reject every other 24.x. Majors follow production (the newest Vercel offers) and are bumped deliberately (pin-versions).",
      "matchDepNames": ["node"],
      "enabled": false
    },
    {
      "description": "@types/node matches the Node runtime major in .nvmrc",
      "matchPackageNames": ["@types/node"],
      "allowedVersions": "24.x"
    },
    {
      "description": "Blocked: typescript-eslint supports TypeScript <6.1; TypeScript 7 waits for 7.1's API and typescript-eslint support",
      "matchPackageNames": ["typescript"],
      "allowedVersions": "<6.1.0"
    },
    {
      "description": "Third-party GitHub Actions are pinned to a commit SHA; first-party actions/* keep major tags (pin-versions)",
      "matchManagers": ["github-actions"],
      "matchPackageNames": ["!actions/**"],
      "pinDigests": true
    }
  ]
}

npx --yes --package renovate -- renovate-config-validator renovate.json

pnpm prettier:check && pnpm lint && pnpm typecheck && pnpm build && pnpm test && pnpm test:integration

-- The Data API's roles, with the default privileges Supabase gives them on every
-- table, sequence and function postgres creates in public (checked on the live
-- project 2026-10-23). postgres is a member of both there too.
CREATE ROLE anon NOLOGIN NOBYPASSRLS;
CREATE ROLE authenticated NOLOGIN NOBYPASSRLS;
GRANT anon, authenticated TO postgres;
ALTER DEFAULT PRIVILEGES FOR ROLE postgres IN SCHEMA public
  GRANT ALL ON TABLES TO anon, authenticated;
ALTER DEFAULT PRIVILEGES FOR ROLE postgres IN SCHEMA public
  GRANT ALL ON SEQUENCES TO anon, authenticated;
ALTER DEFAULT PRIVILEGES FOR ROLE postgres IN SCHEMA public
  GRANT ALL ON FUNCTIONS TO anon, authenticated;

# postgres: the privileged migration/seed role, the only one that writes entitlements
export TEST_ADMIN_DATABASE_URL="$(url postgres)"

import postgres from 'postgres';
import { afterAll, describe, expect, it } from 'vitest';

// Proves that Supabase's Data API roles hold no privileges on our tables, now or for
// tables created later. Runs inside tests/with-test-db.sh, whose Supabase stand-ins give
// anon and authenticated the same default privileges as the live project.
// - TEST_ADMIN_DATABASE_URL: postgres, the role that runs migrations and creates tables

function requireEnv(name: string) {
  const value = process.env[name];
  if (!value) {
    throw new Error(`${name} is not set; run this test through tests/with-test-db.sh`);
  }

  return value;
}

const adminDb = postgres(requireEnv('TEST_ADMIN_DATABASE_URL'), { max: 1 });

const DATA_API_ROLES = ['anon', 'authenticated'];
const TABLE_PRIVILEGES = 'SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER';

// Every role/table pair in public where the role holds at least one table privilege
async function grantsInPublic() {
  return adminDb`
    SELECT r.role, c.relname AS table
    FROM pg_class c
    JOIN pg_namespace n ON n.oid = c.relnamespace
    CROSS JOIN unnest(${DATA_API_ROLES}::text[]) AS r(role)
    WHERE n.nspname = 'public'
      AND c.relkind = 'r'
      AND has_table_privilege(r.role, c.oid, ${TABLE_PRIVILEGES})
  `;
}

afterAll(async () => {
  await adminDb.end();
});

describe('Data API roles', () => {
  it('hold no privileges on existing tables', async () => {
    expect(await grantsInPublic()).toEqual([]);
  });

  it('cannot execute any function in public', async () => {
    const executable = await adminDb`
      SELECT r.role, p.proname AS function
      FROM pg_proc p
      JOIN pg_namespace n ON n.oid = p.pronamespace
      CROSS JOIN unnest(${DATA_API_ROLES}::text[]) AS r(role)
      WHERE n.nspname = 'public' AND has_function_privilege(r.role, p.oid, 'EXECUTE')
    `;
    expect(executable).toEqual([]);
  });

  it('get no privileges on a table postgres creates later', async () => {
    await adminDb`CREATE TABLE public.default_privileges_probe (id int)`;
    try {
      const rows = await adminDb`
        SELECT has_table_privilege(r.role, 'public.default_privileges_probe', ${TABLE_PRIVILEGES}) AS granted
        FROM unnest(${DATA_API_ROLES}::text[]) AS r(role)
      `;
      expect(rows.map(({ granted }) => granted)).toEqual([false, false]);
    } finally {
      await adminDb`DROP TABLE public.default_privileges_probe`;
    }
  });
});

import 'server-only';

import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';

import * as schema from './schema';

function createUnsafeDb() {
  const url = process.env.DATABASE_URL;

  if (!url) {
    throw new Error('Missing DATABASE_URL environment variable');
  }

  // DATABASE_URL points at Supavisor in transaction mode (port 6543), which does
  // not keep you on one Postgres connection between transactions, so named
  // prepared statements must be off (Supabase requirement).
  // Do NOT set max_pipeline: 0 — postgres.js then never reserves a connection
  // for a transaction, and every transaction (including withRLS) fails with
  // UNSAFE_TRANSACTION. Caught by tests/integration/rls.test.ts.
  const client = postgres(url, { prepare: false });

  return drizzle(client, { schema });
}

type UnsafeDb = ReturnType<typeof createUnsafeDb>;

// Created on first use, not when the module loads: `next build` imports every
// route module to read its config, and the build has no DATABASE_URL.
let unsafeDb: UnsafeDb | undefined;

// UNSAFE: queries on this client run without a user context. As app_runtime
// they fail closed (RLS returns zero rows), but nothing ties them to a caller.
// Only for building safe wrappers such as withRLS — ESLint enforces this, and
// the package `exports` map deliberately does not expose this file.
export function getUnsafeDb(): UnsafeDb {
  unsafeDb ??= createUnsafeDb();

  return unsafeDb;
}

import { sql } from 'drizzle-orm';

import { getUnsafeDb } from './unsafe';

export type RlsTx = Parameters<Parameters<ReturnType<typeof getUnsafeDb>['transaction']>[0]>[0];

export type RlsTxHandler<T> = (tx: RlsTx) => Promise<T>;

export async function withRLS<T>(userId: string, fn: RlsTxHandler<T>): Promise<T> {
  return getUnsafeDb().transaction(async (tx) => {
    await tx.execute(sql`select set_config('app.current_user_id', ${userId}, true)`);
    return fn(tx);
  });
}

        // Privileged scripts (dev seeds, provisioning, break-glass); nothing imports them
        { type: 'ops', pattern: 'packages/ops' },

            {
              from: { element: { type: 'ops' } },
              allow: { to: { element: { type: ['foundation', 'registry'] } } },
            },

# Privileged connection — used only by drizzle-kit (pnpm db:generate / db:migrate)
# and the ops scripts (packages/ops, pnpm ops:…).