@supabase/lite 0.2.0 → 0.2.1-next.2

package/UPGRADE.md

@@ -0,0 +1,221 @@
+# Upgrade to Supabase
+
+This document describes the current `lite upgrade` behavior. It is intended for both users and LLM agents working on the upgrade path.
+
+Supalite is designed as a lightweight starting point with a path to full Supabase. The upgrade command exports the local Supalite project, rehearses it against Postgres-compatible execution, and applies it to a Supabase target.
+
+## Quick Start
+
+Hosted Supabase is the default target:
+
+```bash
+lite upgrade
+lite upgrade --target hosted
+```
+
+Use `--dry-run` first to check readiness and rehearse the generated SQL without creating or changing a Supabase target:
+
+```bash
+lite upgrade --dry-run
+```
+
+Use `--force` to skip the interactive confirmation:
+
+```bash
+lite upgrade --force
+```
+
+Write generated credentials to a JSON file:
+
+```bash
+lite upgrade --force --dump-credentials ./supabase-credentials.json
+```
+
+## Targets
+
+### Hosted Supabase
+
+`--target hosted` is the default. It creates a new hosted Supabase project through the Supabase Management API, waits for it to become healthy, applies schema/auth/data, fetches API keys, and prints the new project details.
+
+Relevant options:
+
+```bash
+lite upgrade \
+  --target hosted \
+  --org-id <organization-id-or-slug> \
+  --region <region-key> \
+  --project-name <name> \
+  --supabase-token <personal-access-token>
+```
+
+If `--supabase-token` is omitted, `SUPABASE_ACCESS_TOKEN` is used. If required hosted values are omitted in an interactive shell, the CLI prompts for them.
+
+Only `--mode user` is currently supported. `--mode platform` is reserved for future work.
+
+### Local Supabase
+
+`--target local` upgrades into a local Supabase CLI workdir. By default, the workdir is the current directory, so the command initializes or updates `./supabase/config.toml` in the project being upgraded:
+
+```bash
+lite upgrade --target local --force --no-migrate-sessions
+```
+
+Use `--local-dir` to put the Supabase CLI workdir somewhere else:
+
+```bash
+lite upgrade \
+  --target local \
+  --local-dir ../my-local-supabase \
+  --force \
+  --no-migrate-sessions
+```
+
+The local target uses the Supabase CLI through `bunx supabase@2.98.1` by default. Override the executable with `LITE_SUPABASE_CLI` if needed.
+
+Local target behavior:
+
+- Starts a disposable-style local Supabase stack with deterministic generated config.
+- Removes Supalite-only database config keys such as `[db].driver` and `[db].url` before starting Supabase CLI.
+- Pins `db.major_version = 15`.
+- Enables Studio for inspecting the upgraded local project.
+- Disables services that are not needed for upgrade verification, including mailpit, realtime, storage, imgproxy, edge runtime, analytics/logflare/vector, and supavisor.
+- Parses `supabase status -o json` for API URL, DB URL, anon key, service role key, and JWT secret.
+- Applies schema/auth/data directly to the local Postgres database.
+- Leaves the local Supabase stack running after a successful CLI upgrade.
+
+Stop a local target manually with:
+
+```bash
+bunx supabase@2.98.1 stop --workdir <local-dir> --no-backup
+```
+
+To rerun a local upgrade cleanly in the same workdir, stop the stack and remove Supabase CLI runtime state before running the upgrade again:
+
+```bash
+cd <project-dir>
+bunx supabase@2.98.1 stop --workdir . --no-backup
+rm -rf supabase/.branches supabase/.temp
+lite upgrade --target local --force --no-migrate-sessions
+```
+
+If the local target uses a separate directory, clean that directory instead:
+
+```bash
+bunx supabase@2.98.1 stop --workdir <local-dir> --no-backup
+rm -rf <local-dir>/supabase/.branches <local-dir>/supabase/.temp
+lite upgrade --target local --local-dir <local-dir> --force --no-migrate-sessions
+```
+
+After a successful rerun, verify the database directly before relying on Studio:
+
+```bash
+bunx supabase@2.98.1 status --workdir <local-dir-or-project-dir> -o json
+psql '<DB URL from status>' -c '\dt public.*'
+psql '<DB URL from status>' -c 'select * from public.<table>;'
+```
+
+## What Gets Migrated
+
+The shared upgrade runner applies statements in this order:
+
+1. Project schema from local schema files.
+2. `auth.users`.
+3. `auth.identities`.
+4. Optional hosted session rows, when session migration is enabled.
+5. Optional hosted refresh token rows, when session migration is enabled.
+6. User table data, in foreign-key-safe order.
+7. Sequence resets after all migrated user data has been inserted.
+8. Hosted auth config sync, when supported by the target.
+
+User data migration emits inserts for application tables and resets serial or bigserial sequences after explicit migrated IDs. This avoids the common post-upgrade problem where the next insert collides with migrated primary keys.
+
+## Session Migration
+
+Hosted upgrades can preserve existing Supalite sessions by importing `auth.jwt_secret` as a Supabase HS256 signing key and migrating session and refresh token rows:
+
+```bash
+lite upgrade --migrate-sessions
+```
+
+If `auth.jwt_secret` is missing, hosted session migration fails and the CLI asks you to rerun with `--no-migrate-sessions`.
+
+Weak JWT secrets are blocked non-interactively unless explicitly allowed:
+
+```bash
+lite upgrade --migrate-sessions --allow-weak-jwt-secret
+```
+
+Use this only when preserving sessions is more important than rotating a weak development secret. If sessions are not migrated, existing tokens become invalid and users must sign in again.
+
+Local Supabase target does not support preserving sessions yet. Run local upgrades with:
+
+```bash
+lite upgrade --target local --no-migrate-sessions
+```
+
+## Auth Config
+
+Hosted upgrades map supported Supalite auth settings to Supabase Management API auth config and apply them after schema/auth/data migration.
+
+Local upgrades do not call Management API config endpoints. Instead, supported local Supabase CLI config values are written before the local stack starts. This currently covers settings such as API max rows, auth site URL, redirect URLs, JWT expiry, signup flags, anonymous sign-ins, minimum password length, and email confirmation behavior.
+
+## Rehearsal and Readiness
+
+Every non-dry-run upgrade performs:
+
+1. Readiness checks.
+2. An in-memory PGlite rehearsal.
+3. The real target upgrade only if rehearsal succeeds.
+
+`--dry-run` runs readiness and rehearsal only:
+
+```bash
+lite upgrade --dry-run
+```
+
+Rehearsal creates Supabase-compatible roles before applying grants, then exercises the generated schema/auth/data SQL against a Postgres-compatible engine.
+
+## Known Gaps
+
+Storage migration is not implemented. If storage is enabled, the command warns but continues with database and auth migration.
+
+Realtime config migration is not implemented. If realtime is enabled, the command warns but continues.
+
+Local target does not preserve sessions or JWT secret. Users must re-authenticate after local target migration.
+
+Local Supabase is not a valid `SupabaseManagementApi` endpoint. A local CLI stack exposes API URL, DB URL, keys, and JWT secret through `supabase status`; it does not expose hosted Management API project routes like `/v1/projects/{ref}/database/query`.
+
+Supabox is a better future target for high-fidelity hosted-flow tests, because it runs the local Supabase platform/control-plane and project lifecycle. It should augment, not replace, the faster local Supabase CLI harness.
+
+## Testing the Upgrade Path
+
+Fast focused tests:
+
+```bash
+cd app
+bun test src/cli/upgrade/*.spec.ts src/cli/commands/cloud/upgrade.cmd.spec.ts test/cli/upgrade/local-supabase-status.test.ts
+```
+
+Opt-in Docker test against local Supabase CLI:
+
+```bash
+cd app
+LITE_LOCAL_SUPABASE_TESTS=1 bun test test/cli/upgrade/local-supabase.test.ts
+```
+
+Full default verification:
+
+```bash
+cd app && bun test
+bun test --recursive
+```
+
+The intended next testing layer is a fixture-based upgrade suite:
+
+1. Copy a full Supalite fixture project to a temp directory.
+2. Run that fixture's app/e2e tests against Supalite.
+3. Run `lite upgrade --target local --local-dir <temp-target> --force --no-migrate-sessions`.
+4. Point the same app/e2e tests at the upgraded Supabase API URL and anon key.
+5. Assert the same user-visible behavior before and after upgrade.
+
+For hosted-flow fidelity, add a separate opt-in Supabox lane later. That suite should validate the default hosted code path through a local Management API/project lifecycle rather than through the single-project Supabase CLI stack.

package/dist/{Connection-rAPmec1m.d.ts → Connection-CSVCuMv-.d.ts}

@@ -1,5 +1,3 @@
-import { ParseResult } from 'libpg-query';
-import { DeparserOptions } from 'pgsql-deparser';
 import { SelectQueryBuilder, InsertQueryBuilder, UpdateQueryBuilder, DeleteQueryBuilder, KyselyConfig, Kysely } from 'kysely';
 
 /**
@@ -256,128 +254,6 @@ type TranslatorConfig = {
     basePath?: string;
 };
 
-type TUnwrappedConst = string | number | boolean | null | undefined;
-
-type PolicyCommand = "SELECT" | "INSERT" | "UPDATE" | "DELETE" | "ALL";
-type PolicyRole = "anon" | "authenticated" | string;
-interface PolicyData {
-    name: string;
-    table: string;
-    schema?: string;
-    command: PolicyCommand;
-    permissive: boolean;
-    roles: PolicyRole[];
-    using?: Where;
-    withCheck?: Where;
-}
-declare class Policy {
-    readonly data: PolicyData;
-    constructor(data: PolicyData);
-    appliesTo(cmd: "SELECT" | "INSERT" | "UPDATE" | "DELETE"): boolean;
-    appliesToRole(role: string): boolean;
-    toJSON(): PolicyData;
-    static fromJSON(data: PolicyData): Policy;
-}
-
-declare class CheckConstraintError extends Error {
-    readonly table: string;
-    readonly column: string;
-    readonly constraint: string;
-    readonly value: unknown;
-    constructor(table: string, column: string, constraint: string, value: unknown);
-}
-
-type SqliteType = "INTEGER" | "REAL" | "TEXT" | "BLOB" | "ANY";
-type DefaultFn = () => unknown;
-interface ValidationResult {
-    status: "pass" | "warn" | "fail";
-    message: string | null;
-    action?: string;
-}
-interface FieldContext {
-    schema: string;
-    table: string;
-    column: string;
-    pgTypeName: string;
-    nullable: boolean;
-    defaultValue: string | null;
-    defaultFn?: DefaultFn | null;
-    isPrimaryKey: boolean;
-    isUnique: boolean;
-    isSerial: boolean;
-    isGenerated?: boolean;
-    fkRef?: {
-        refSchema?: string;
-        refTable: string;
-        refColumn: string;
-        constraintName?: string;
-    };
-    hasCheck?: boolean;
-    checkConstraintName?: string;
-    uniqueConstraintName?: string;
-}
-interface ColumnDDLOptions {
-    includeNullable?: boolean;
-}
-declare abstract class Field {
-    readonly context: FieldContext;
-    constructor(context: FieldContext);
-    abstract get sqliteType(): SqliteType;
-    get isShimBacked(): boolean;
-    checkConstraint(): string | null;
-    serialize(value: unknown): unknown;
-    deserialize(value: unknown): unknown;
-    validateStorage(_rawSqliteValue: unknown): ValidationResult;
-    protected validationFail(message: string, action?: string): ValidationResult;
-    protected validationPass(): ValidationResult;
-    protected isNullish(value: unknown): value is null | undefined;
-    toColumnDDL(options?: ColumnDDLOptions): string;
-    protected checkError(constraint: string, value: unknown): CheckConstraintError;
-    protected quoteIfNeeded(name: string): string;
-}
-
-type FunctionResolutionMode = "synthetic" | "translate" | "auto";
-
-declare class TableSchema {
-    readonly table: string;
-    readonly schema: string;
-    private fields;
-    constructor(table: string, schema?: string, fields?: Map<string, Field>);
-    get(col: string): Field | undefined;
-    has(col: string): boolean;
-    set(col: string, field: Field): void;
-    columns(): string[];
-    all(): Field[];
-    serializeRow(row: Record<string, unknown>): Record<string, unknown>;
-    deserializeRow(row: Record<string, unknown>): Record<string, unknown>;
-    applyDefaults(row: Record<string, unknown>): Record<string, unknown>;
-}
-
-type CollectedEnums = Map<string, string[]>;
-type CollectedVariable = {
-    local?: boolean;
-    value: TUnwrappedConst;
-};
-type CollectedVariables = Map<string, CollectedVariable>;
-type CollectedRlsTables = Set<string>;
-type CollectedSchema = Map<string, TableSchema>;
-type CollectedTableConstraint = {
-    schema: string;
-    table: string;
-    kind: "unique" | "check" | "foreign_key";
-    name?: string;
-    columns: string[];
-    refSchema?: string;
-    refTable?: string;
-    refColumns?: string[];
-};
-type CollectedComment = {
-    schema: string;
-    table: string;
-    column?: string;
-    text: string;
-};
-
 interface TableInfo {
     name: string;
     sql: string;
@@ -598,33 +474,6 @@ interface ConnectionMigrator {
     safeSortPlanSteps(steps: PlanStep[]): PlanStep[];
 }
 
-type SchemaHandling = "default" | "prefix";
-interface DeparseOptions extends DeparserOptions {
-    schemaHandling?: SchemaHandling;
-    forceDefaultSchema?: string | false;
-    enums?: CollectedEnums;
-    /** Current DB introspection. Required for ALTER TABLE ops that need 12-step rebuild. */
-    introspection?: IntrospectResult;
-    functionResolution?: FunctionResolutionMode;
-}
-
-declare function translatePostgresDdl(pgSql: string, options?: DeparseOptions): Promise<string>;
-declare function deparsePostgresDdl(pgSql: string, options?: DeparseOptions & {
-    strict?: boolean;
-}): Promise<{
-    ddl: string;
-    enums: CollectedEnums;
-    rls: {
-        tables: CollectedRlsTables;
-        policies: Policy[];
-    };
-    schema: CollectedSchema;
-    vars: CollectedVariables;
-    tableConstraints: CollectedTableConstraint[];
-    comments: CollectedComment[];
-    ast: ParseResult;
-}>;
-
 interface CacheSetOptions {
     ttl?: number;
 }
@@ -707,4 +556,4 @@ declare abstract class Connection<Driver = unknown, DB = any, Config extends ICo
     withContext<T>(_vars: VarsContext | undefined, fn: (db: Kysely<any>) => Promise<T>, _opts?: ConnectionContextOptions): Promise<T>;
 }
 
-export { type QbDelete as $, type AnyAST as A, type BaseAST as B, Connection as C, DataLossError as D, type EmbedDef as E, type FiltersResult as F, type ForeignKeyInfo as G, type HeadersResult as H, type IntrospectResult as I, type IndexDiff as J, type IndexInfo as K, type InsertAST as L, type IntrospectOptions as M, type JoinDef as N, type JoinMap as O, type PolicyCommand as P, type Meta as Q, MigrationError as R, type OrderEntry as S, type TransactionOptions as T, type PlanResult as U, type VarsContext as V, type PlanStep as W, PlanStepType as X, type PreferToken as Y, type PrimaryKeyInfo as Z, type Qb as _, type IConnectionConfig as a, type QbInsert as a0, type QbSelect as a1, type QbUpdate as a2, type QueryAST as a3, type QueryParamsResult as a4, RelationNotFoundError as a5, type RouteResult as a6, type RpcAST as a7, type RpcResult as a8, type SchemaDiffResult as a9, type SelectEntry as aa, type SelectResult as ab, type TableDiff as ac, type TableInfo as ad, type TextSearchValue as ae, type TransformsResult as af, type TranslatorConfig as ag, type TriggerInfo as ah, type UniqueConstraintInfo as ai, type UpdateAST as aj, type UpsertAST as ak, type UpsertResult as al, type ViewInfo as am, type Where as an, type WhereValue as ao, isRef as ap, translatePostgresDdl as aq, type CacheDriver as b, type CacheSetOptions as c, deparsePostgresDdl as d, type PolicyRole as e, Policy as f, type AST as g, type ASTType as h, type AggregateFunction as i, type BodyResult as j, type CheckConstraintInfo as k, type ColumnDef as l, type ColumnDiff as m, type ColumnInfo as n, type ColumnRef as o, type CommentInfo as p, type ConnectionContextOptions as q, type ConnectionMigrator as r, type CustomTypesInfo as s, type DataLossWarning as t, type DeleteAST as u, type Dialect as v, type DiffResult as w, type EmbedTransform as x, type ExplainOptions as y, type ForeignKeyDiff as z };
+export { type QbUpdate as $, type AnyAST as A, type BaseAST as B, Connection as C, DataLossError as D, type EmbedDef as E, type FiltersResult as F, type InsertAST as G, type HeadersResult as H, type IConnectionConfig as I, type IntrospectOptions as J, type JoinDef as K, type JoinMap as L, type Meta as M, MigrationError as N, type OrderEntry as O, type PlanResult as P, type PlanStep as Q, PlanStepType as R, type PreferToken as S, type TransactionOptions as T, type PrimaryKeyInfo as U, type VarsContext as V, type Where as W, type Qb as X, type QbDelete as Y, type QbInsert as Z, type QbSelect as _, type IntrospectResult as a, type QueryAST as a0, type QueryParamsResult as a1, RelationNotFoundError as a2, type RouteResult as a3, type RpcAST as a4, type RpcResult as a5, type SchemaDiffResult as a6, type SelectEntry as a7, type SelectResult as a8, type TableDiff as a9, type TableInfo as aa, type TextSearchValue as ab, type TransformsResult as ac, type TranslatorConfig as ad, type TriggerInfo as ae, type UniqueConstraintInfo as af, type UpdateAST as ag, type UpsertAST as ah, type UpsertResult as ai, type ViewInfo as aj, type WhereValue as ak, isRef as al, type CacheDriver as b, type CacheSetOptions as c, type AST as d, type ASTType as e, type AggregateFunction as f, type BodyResult as g, type CheckConstraintInfo as h, type ColumnDef as i, type ColumnDiff as j, type ColumnInfo as k, type ColumnRef as l, type CommentInfo as m, type ConnectionContextOptions as n, type ConnectionMigrator as o, type CustomTypesInfo as p, type DataLossWarning as q, type DeleteAST as r, type Dialect as s, type DiffResult as t, type EmbedTransform as u, type ExplainOptions as v, type ForeignKeyDiff as w, type ForeignKeyInfo as x, type IndexDiff as y, type IndexInfo as z };