@mr.dj2u/library-registry 0.2.0 → 0.3.0

package/README.md

@@ -40,3 +40,6 @@ explicitly declared in an asset's `contentTokens` metadata. V1 declares only
 
 The registry does not track installation history and does not implement
 authentication. See `THIRD_PARTY_NOTICES.md` for snapshot provenance.
+
+See `docs/database-adapter.md` for the generated app database adapter contract
+and provider variant expectations.

package/assets/mds/env/convex.env.example

@@ -0,0 +1 @@
+EXPO_PUBLIC_CONVEX_URL=

package/assets/mds/env/firebase.env.example

@@ -0,0 +1,6 @@
+EXPO_PUBLIC_FIREBASE_API_KEY=
+EXPO_PUBLIC_FIREBASE_AUTH_DOMAIN=
+EXPO_PUBLIC_FIREBASE_PROJECT_ID=
+EXPO_PUBLIC_FIREBASE_STORAGE_BUCKET=
+EXPO_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
+EXPO_PUBLIC_FIREBASE_APP_ID=

package/assets/mds/env/supabase.env.example

@@ -0,0 +1,3 @@
+EXPO_PUBLIC_SUPABASE_URL=
+EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
+EXPO_PUBLIC_SUPABASE_KEY=

package/assets/mds/project/auth-base.md

@@ -0,0 +1,17 @@
+# Auth Setup
+
+This app includes the provider-neutral MDS auth shell.
+
+## What Was Added
+
+- Sign-in, sign-up, and password reset routes under the auth route group.
+- Shared auth form UI in `src/features/auth`.
+- `AuthProvider` and `useAuth`.
+- A base in-memory adapter at `src/features/auth/auth-adapter.ts`.
+
+## Before Production
+
+- Replace the base adapter with a real auth provider.
+- Persist sessions outside process memory.
+- Guard protected app routes in the root Expo Router layout.
+- Store legal acceptance and onboarding completion in user-scoped storage when those flows matter for compliance.

package/assets/mds/project/auth-convex.md

@@ -0,0 +1,33 @@
+# Convex Auth Setup
+
+This app includes the MDS auth shell wired to Convex React Native and Convex Auth. This variant is experimental.
+
+## Environment
+
+Install the generated app dependencies, then initialize Convex:
+
+```bash
+npx convex dev
+npx @convex-dev/auth
+```
+
+Set the public Convex deployment URL for the Expo app:
+
+```bash
+EXPO_PUBLIC_CONVEX_URL=
+```
+
+## Password Provider Snippet
+
+After Convex generates its `convex/` folder and `_generated` files, configure password auth in the Convex backend:
+
+```ts
+import { convexAuth } from '@convex-dev/auth/server';
+import { Password } from '@convex-dev/auth/providers/Password';
+
+export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
+  providers: [Password],
+});
+```
+
+Convex Auth is beta. Confirm the current Convex Auth setup docs before treating this path as production infrastructure.

package/assets/mds/project/auth-firebase.md

@@ -0,0 +1,22 @@
+# Firebase Auth Setup
+
+This app includes the MDS auth shell wired to Firebase Authentication through the Firebase JS SDK.
+
+## Environment
+
+Register a web app in Firebase, enable Email/Password authentication, then set:
+
+```bash
+EXPO_PUBLIC_FIREBASE_API_KEY=
+EXPO_PUBLIC_FIREBASE_AUTH_DOMAIN=
+EXPO_PUBLIC_FIREBASE_PROJECT_ID=
+EXPO_PUBLIC_FIREBASE_STORAGE_BUCKET=
+EXPO_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
+EXPO_PUBLIC_FIREBASE_APP_ID=
+```
+
+## Notes
+
+- This variant uses the Firebase JS SDK so it works with Expo Go and universal Expo apps.
+- React Native Firebase requires native code and a development build, so it is intentionally outside this source-copy variant.
+- Legal acceptance and onboarding completion default to local app state in this branch. Add Firestore or another backend before using Firebase-authenticated legal audit trails in production.

package/assets/mds/project/auth-supabase.md

@@ -0,0 +1,46 @@
+# Supabase Auth Setup
+
+This app includes the MDS auth shell wired to Supabase Auth.
+
+## Environment
+
+The scaffold includes `.env.example` with the required client-safe Supabase variables. Copy it to `.env.local` and fill in your values before running the app:
+
+```bash
+EXPO_PUBLIC_SUPABASE_URL=
+EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
+EXPO_PUBLIC_SUPABASE_KEY=
+```
+
+`EXPO_PUBLIC_SUPABASE_KEY` and `EXPO_PUBLIC_SUPABASE_ANON_KEY` are still accepted as fallbacks for older projects.
+
+## Database
+
+Apply `supabase/migrations/0001_mds_auth_onboarding.sql` to the Supabase project before relying on onboarding or legal acceptance persistence.
+
+Onboarding completion and legal acceptance are written through MDS adapters, not by the auth screens. When Zustand is also selected, Zustand is only a local cache and pending queue. Supabase `user_onboarding_state` and `user_legal_acceptances` remain the source of truth. Legal rows are insert-only and scoped to `auth.uid()`.
+
+Do not treat pre-auth local legal acceptance as a hosted audit record. Hosted apps should write legal acceptance after sign-in, typically through `/legal/updates`.
+
+The Expo client env values are not enough to run migrations. To apply SQL, use one of these:
+
+```bash
+# Linked Supabase project. Requires a Supabase CLI login/access token.
+npx supabase link --project-ref <project-ref>
+npx supabase migration up --linked
+```
+
+```bash
+# Direct database connection. Requires the Postgres connection string/password from Supabase.
+npx supabase migration up --db-url "<postgres-connection-string>"
+```
+
+Use separate Supabase projects for test/staging and production. Never put service-role keys, database passwords, or other Supabase secrets in Expo client code.
+
+`EXPO_PUBLIC_SUPABASE_URL` and `EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY` are client-visible configuration values, not database admin credentials. Generated apps include a populated, ignored `.env.local` for the smoke Supabase project plus a blank tracked `.env.example` template for replacing those values when you move to another backend project.
+
+## Notes
+
+- New Supabase projects usually require email confirmation before the first session appears.
+- OAuth and magic-link auth need app deep links and are left as follow-up integration work.
+- Row level security is the production boundary for client-visible Supabase tables.

package/assets/mds/src/app/(auth)/reset-password.tsx

@@ -0,0 +1,5 @@
+import { AuthScreen } from '@/features/auth/auth-screen';
+
+export default function ResetPasswordRoute() {
+  return <AuthScreen mode="reset-password" />;
+}

package/assets/mds/src/app/(auth)/sign-in.tsx

@@ -0,0 +1,5 @@
+import { AuthScreen } from '@/features/auth/auth-screen';
+
+export default function SignInRoute() {
+  return <AuthScreen mode="sign-in" />;
+}

package/assets/mds/src/app/(auth)/sign-up.tsx

@@ -0,0 +1,5 @@
+import { AuthScreen } from '@/features/auth/auth-screen';
+
+export default function SignUpRoute() {
+  return <AuthScreen mode="sign-up" />;
+}

package/assets/mds/src/app/legal/updates.tsx

@@ -0,0 +1 @@
+export { default } from '@/features/legal/legal-update-screen';

package/assets/mds/src/app/onboarding/complete.tsx

@@ -0,0 +1,2 @@
+export { default } from '@/features/onboarding/complete-screen';
+

package/assets/mds/src/app/onboarding/features.tsx

@@ -0,0 +1 @@
+export { default } from '@/features/onboarding/features-screen';

package/assets/mds/src/app/onboarding/legal.tsx

@@ -0,0 +1,2 @@
+export { default } from '@/features/onboarding/legal-review-screen';
+

package/assets/mds/src/app/onboarding.tsx

@@ -1 +1 @@
-export { default } from '@/features/onboarding/onboarding-screen';
+export { default } from '@/features/onboarding/welcome-screen';

package/assets/mds/src/app/settings.tsx

@@ -1 +1,10 @@
-export { default } from '@/features/settings/settings-screen';
+import SettingsScreen, { createPlaceholderAuthAdapter } from '@/features/settings/settings-screen';
+
+export default function SettingsRoute() {
+  return (
+    <SettingsScreen
+      auth={createPlaceholderAuthAdapter()}
+      legalUrls={{ terms: '/terms', privacy: '/privacy' }}
+    />
+  );
+}

package/assets/mds/src/db/adapter.ts

@@ -0,0 +1,195 @@
+export type DatabaseTableRow = Record<string, unknown>;
+export type DatabaseSchema = Record<string, DatabaseTableRow>;
+export type DatabaseTableName<Schema extends DatabaseSchema> = Extract<keyof Schema, string>;
+export type DatabaseRow<
+  Schema extends DatabaseSchema,
+  Table extends DatabaseTableName<Schema>,
+> = Schema[Table];
+export type DatabaseInsert<
+  Schema extends DatabaseSchema,
+  Table extends DatabaseTableName<Schema>,
+> = Partial<DatabaseRow<Schema, Table>>;
+export type DatabaseUpdate<
+  Schema extends DatabaseSchema,
+  Table extends DatabaseTableName<Schema>,
+> = Partial<DatabaseRow<Schema, Table>>;
+
+export type DatabaseFilterOperator =
+  | 'eq'
+  | 'neq'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'in'
+  | 'like'
+  | 'ilike'
+  | 'is';
+
+export type DatabaseErrorCode =
+  | 'not_found'
+  | 'conflict'
+  | 'timeout'
+  | 'unauthorized'
+  | 'validation'
+  | 'unsupported'
+  | 'unknown';
+
+export type DatabaseMutationType = 'insert' | 'update' | 'upsert' | 'delete';
+export type DatabaseChangeType = 'insert' | 'update' | 'delete' | '*';
+
+export interface DatabaseCapabilities {
+  transactions: boolean;
+  subscriptions: boolean;
+  rls?: boolean;
+  authIntegration?: boolean;
+}
+
+export interface DatabaseAdapterMetadata {
+  name: string;
+  version: string;
+  capabilities: DatabaseCapabilities;
+}
+
+export interface DatabaseFilter<Row extends DatabaseTableRow> {
+  column: Extract<keyof Row, string>;
+  operator?: DatabaseFilterOperator;
+  value: unknown;
+}
+
+export interface DatabaseQueryInput<
+  Schema extends DatabaseSchema,
+  Table extends DatabaseTableName<Schema>,
+> {
+  table: Table;
+  select?: string | readonly Extract<keyof DatabaseRow<Schema, Table>, string>[];
+  filters?: readonly DatabaseFilter<DatabaseRow<Schema, Table>>[];
+  limit?: number;
+  orderBy?: {
+    column: Extract<keyof DatabaseRow<Schema, Table>, string>;
+    ascending?: boolean;
+  };
+  single?: boolean;
+}
+
+export interface DatabaseMutationInput<
+  Schema extends DatabaseSchema,
+  Table extends DatabaseTableName<Schema>,
+> {
+  table: Table;
+  type: DatabaseMutationType;
+  values?: DatabaseInsert<Schema, Table> | readonly DatabaseInsert<Schema, Table>[];
+  filters?: readonly DatabaseFilter<DatabaseRow<Schema, Table>>[];
+  select?: string | readonly Extract<keyof DatabaseRow<Schema, Table>, string>[];
+}
+
+export interface DatabaseMutationResult<Row extends DatabaseTableRow> {
+  rows: Row[];
+  count: number;
+}
+
+export interface DatabaseSubscribeInput<
+  Schema extends DatabaseSchema,
+  Table extends DatabaseTableName<Schema>,
+> {
+  table: Table;
+  event?: DatabaseChangeType;
+  filters?: readonly DatabaseFilter<DatabaseRow<Schema, Table>>[];
+}
+
+export interface DatabaseChangeEvent<Row extends DatabaseTableRow> {
+  type: Exclude<DatabaseChangeType, '*'>;
+  table: string;
+  row: Row | null;
+  oldRow?: Partial<Row> | null;
+}
+
+export type DatabaseUnsubscribe = () => void;
+
+export interface DatabaseAdapter<Schema extends DatabaseSchema = DatabaseSchema>
+  extends DatabaseAdapterMetadata {
+  query<Table extends DatabaseTableName<Schema>>(
+    input: DatabaseQueryInput<Schema, Table>,
+  ): Promise<DatabaseRow<Schema, Table>[]>;
+  mutate<Table extends DatabaseTableName<Schema>>(
+    input: DatabaseMutationInput<Schema, Table>,
+  ): Promise<DatabaseMutationResult<DatabaseRow<Schema, Table>>>;
+  transaction<Result>(fn: (client: DatabaseAdapter<Schema>) => Promise<Result>): Promise<Result>;
+  subscribe<Table extends DatabaseTableName<Schema>>(
+    input: DatabaseSubscribeInput<Schema, Table>,
+    onChange: (event: DatabaseChangeEvent<DatabaseRow<Schema, Table>>) => void,
+    onError?: (error: DatabaseAdapterError) => void,
+  ): DatabaseUnsubscribe;
+}
+
+export interface DatabaseAdapterErrorOptions {
+  cause?: unknown;
+  providerCode?: string;
+  retryable?: boolean;
+  table?: string;
+}
+
+export class DatabaseAdapterError extends Error {
+  readonly code: DatabaseErrorCode;
+  readonly providerCode?: string;
+  readonly retryable: boolean;
+  readonly table?: string;
+
+  constructor(code: DatabaseErrorCode, message: string, options: DatabaseAdapterErrorOptions = {}) {
+    super(message);
+    this.name = 'DatabaseAdapterError';
+    this.code = code;
+    this.providerCode = options.providerCode;
+    this.retryable = options.retryable ?? code === 'timeout';
+    this.table = options.table;
+    if (options.cause !== undefined) {
+      this.cause = options.cause;
+    }
+  }
+}
+
+export class DatabaseNotFoundError extends DatabaseAdapterError {
+  constructor(message = 'Database row was not found.', options?: DatabaseAdapterErrorOptions) {
+    super('not_found', message, options);
+    this.name = 'DatabaseNotFoundError';
+  }
+}
+
+export class DatabaseConflictError extends DatabaseAdapterError {
+  constructor(message = 'Database write conflicted with existing data.', options?: DatabaseAdapterErrorOptions) {
+    super('conflict', message, options);
+    this.name = 'DatabaseConflictError';
+  }
+}
+
+export class DatabaseTimeoutError extends DatabaseAdapterError {
+  constructor(message = 'Database operation timed out.', options?: DatabaseAdapterErrorOptions) {
+    super('timeout', message, { ...options, retryable: true });
+    this.name = 'DatabaseTimeoutError';
+  }
+}
+
+export class DatabaseUnauthorizedError extends DatabaseAdapterError {
+  constructor(message = 'Database operation is not authorized.', options?: DatabaseAdapterErrorOptions) {
+    super('unauthorized', message, options);
+    this.name = 'DatabaseUnauthorizedError';
+  }
+}
+
+export class DatabaseValidationError extends DatabaseAdapterError {
+  constructor(message = 'Database operation input is invalid.', options?: DatabaseAdapterErrorOptions) {
+    super('validation', message, options);
+    this.name = 'DatabaseValidationError';
+  }
+}
+
+export class DatabaseUnsupportedError extends DatabaseAdapterError {
+  constructor(message = 'Database operation is not supported by this adapter.', options?: DatabaseAdapterErrorOptions) {
+    super('unsupported', message, options);
+    this.name = 'DatabaseUnsupportedError';
+  }
+}
+
+export function isDatabaseAdapterError(error: unknown): error is DatabaseAdapterError {
+  return error instanceof DatabaseAdapterError;
+}

package/assets/mds/src/db/firebase.ts

@@ -0,0 +1,77 @@
+import {
+  DatabaseAdapterError,
+  DatabaseUnsupportedError,
+  type DatabaseAdapter,
+  type DatabaseChangeEvent,
+  type DatabaseMutationInput,
+  type DatabaseMutationResult,
+  type DatabaseQueryInput,
+  type DatabaseSchema,
+  type DatabaseSubscribeInput,
+  type DatabaseTableName,
+} from './adapter';
+
+export type FirebaseDatabaseClient = unknown;
+export type FirebaseDatabaseClientFactory = () => FirebaseDatabaseClient;
+
+export interface FirebaseDatabaseAdapterOptions {
+  version?: string;
+}
+
+export function createFirebaseDatabaseAdapter<Schema extends DatabaseSchema>(
+  getClient: FirebaseDatabaseClientFactory,
+  options: FirebaseDatabaseAdapterOptions = {},
+): DatabaseAdapter<Schema> {
+  void getClient;
+
+  return {
+    name: 'firebase',
+    version: options.version ?? '0.1.0',
+    capabilities: {
+      transactions: false,
+      subscriptions: false,
+      rls: false,
+      authIntegration: false,
+    },
+
+    async query<Table extends DatabaseTableName<Schema>>(
+      input: DatabaseQueryInput<Schema, Table>,
+    ): Promise<Schema[Table][]> {
+      void input;
+      throw new DatabaseUnsupportedError(
+        'Firebase database reads are a generated skeleton. Implement Firestore collection/query mapping for this app schema before use.',
+      );
+    },
+
+    async mutate<Table extends DatabaseTableName<Schema>>(
+      input: DatabaseMutationInput<Schema, Table>,
+    ): Promise<DatabaseMutationResult<Schema[Table]>> {
+      void input;
+      throw new DatabaseUnsupportedError(
+        'Firebase database writes are a generated skeleton. Implement addDoc, setDoc, updateDoc, or deleteDoc mapping for this app schema before use.',
+      );
+    },
+
+    async transaction<Result>(fn: (client: DatabaseAdapter<Schema>) => Promise<Result>): Promise<Result> {
+      void fn;
+      throw new DatabaseUnsupportedError(
+        'Firebase transaction support is not wired in this generated skeleton. Use runTransaction after defining document paths for your schema.',
+      );
+    },
+
+    subscribe<Table extends DatabaseTableName<Schema>>(
+      input: DatabaseSubscribeInput<Schema, Table>,
+      onChange: (event: DatabaseChangeEvent<Schema[Table]>) => void,
+      onError?: (error: DatabaseAdapterError) => void,
+    ) {
+      void input;
+      void onChange;
+      const error = new DatabaseUnsupportedError(
+        'Firebase subscriptions are a generated skeleton. Wire Firestore onSnapshot once collection paths and auth rules are defined.',
+      );
+      onError?.(error);
+      return () => {};
+    },
+  };
+}
+

package/assets/mds/src/db/index.firebase.ts

@@ -0,0 +1,19 @@
+import { getFirebaseDb } from '../services/firebase';
+import { createFirebaseDatabaseAdapter } from './firebase';
+
+import type { DatabaseAdapter } from './adapter';
+import type { AppDatabase } from '../types/database';
+
+let adapter: DatabaseAdapter<AppDatabase> | null = null;
+
+export function getAdapter(type: 'firebase' = 'firebase'): DatabaseAdapter<AppDatabase> {
+  if (type !== 'firebase') {
+    throw new Error(`Unsupported database adapter: ${type}`);
+  }
+
+  adapter ??= createFirebaseDatabaseAdapter<AppDatabase>(() => getFirebaseDb());
+  return adapter;
+}
+
+export const database = getAdapter;
+

package/assets/mds/src/db/index.supabase.ts

@@ -0,0 +1,22 @@
+import { getSupabaseClient } from '../services/supabase';
+import { createSupabaseDatabaseAdapter } from './supabase';
+
+import type { DatabaseAdapter } from './adapter';
+import type { AppDatabase } from '../types/database';
+import type { SupabaseDatabaseClientFactory } from './supabase';
+
+let adapter: DatabaseAdapter<AppDatabase> | null = null;
+
+export function getAdapter(type: 'supabase' = 'supabase'): DatabaseAdapter<AppDatabase> {
+  if (type !== 'supabase') {
+    throw new Error(`Unsupported database adapter: ${type}`);
+  }
+
+  adapter ??= createSupabaseDatabaseAdapter<AppDatabase>(
+    () => getSupabaseClient() as unknown as ReturnType<SupabaseDatabaseClientFactory>,
+  );
+  return adapter;
+}
+
+export const database = getAdapter;
+