ship-create 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ship-create",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Scaffold a new project the SHIP Method way — Structure, Human Flow, Instruction, Publish. No git clone, no API key, just one command.",
   "type": "module",
   "license": "MIT",

package/templates/starter-kit/.env.example

@@ -0,0 +1,32 @@
+# Pick exactly one provider. This is a setup-time choice, not runtime-switchable.
+DB_PROVIDER=supabase # supabase | neon | cloudflare-d1 | postgres
+
+# --- supabase | postgres | neon (Postgres-family — all use DATABASE_URL) ---
+# Supabase: Project Settings -> Database -> Connection string (use the "Transaction pooler" URI for serverless)
+# Neon: Project Dashboard -> Connection Details -> select "Pooled connection"
+# Plain Postgres: your host's connection string, e.g. postgres://user:pass@host:5432/dbname
+DATABASE_URL=
+
+# --- cloudflare-d1 only ---
+# D1 has no connection string at runtime — the binding comes from wrangler.toml
+# and the Cloudflare Workers runtime, not an env var. The vars below are only
+# used by `drizzle-kit` migration commands run from your local machine.
+CLOUDFLARE_ACCOUNT_ID=
+CLOUDFLARE_D1_DATABASE_ID=
+CLOUDFLARE_API_TOKEN=
+
+# IMPORTANT: DB_PROVIDER=cloudflare-d1 requires deploying this app to
+# Cloudflare Workers/Pages via @opennextjs/cloudflare. It will NOT work on
+# Vercel. See 13-TECH-STACK/DB_PROVIDER_GUIDE.md before picking this option.
+
+# --- Auth.js (required regardless of DB_PROVIDER) ---
+AUTH_SECRET=
+# Add at least one provider's keys here once chosen, e.g.:
+# AUTH_GITHUB_ID=
+# AUTH_GITHUB_SECRET=
+
+# --- Storage (optional — only needed once you wire up file uploads) ---
+STORAGE_PROVIDER=supabase # supabase | cloudflare-r2 | vercel-blob (only supabase is implemented)
+SUPABASE_URL=
+SUPABASE_SERVICE_ROLE_KEY=
+SUPABASE_STORAGE_BUCKET=uploads

package/templates/starter-kit/README.md

@@ -1,15 +1,16 @@
 # SHIP Starter Kit
 
-This is the code foundation for **The SHIP Method OS** — a Next.js 14 (App
+This is the code foundation for **The SHIP Method OS** — a Next.js 16 (App
 Router) + TypeScript + Tailwind CSS starter that gives every downstream agent
 a consistent, working UI shell to build on top of.
 
-It is currently **mock-data only**. There is no backend wired up — no
-Supabase, no auth, no payments. Every list, table, and metric you see is
-sourced from `lib/mock-data.ts`. That's intentional: the goal of this layer
-is a correct, consistent shared foundation (design tokens, primitives,
-layout) that other agents can build real features on without re-deciding
-button styles or color values per screen.
+It is currently **mock-data only**. Backend code (`lib/db/`, `lib/auth.ts`,
+`lib/storage.ts`) is included but has no live database connection configured
+by default. Every list, table, and metric you see is sourced from
+`lib/mock-data.ts`. That's intentional: the goal of this layer is a correct,
+consistent shared foundation (design tokens, primitives, layout) that other
+agents can build real features on without re-deciding button styles or color
+values per screen.
 
 ## Running it
 
@@ -51,14 +52,23 @@ shared primitives in `components/ui/` and the `cn()` helper in
 
 ## Next step: real data
 
-When it's time to move off mock data, replace the contents of
-`lib/mock-data.ts` (or the call sites that import from it) with real
-Supabase queries. Before doing that, read:
+This kit ships with a real, pluggable backend in `lib/db/`, `lib/auth.ts`,
+and `lib/storage.ts` — but it has no live database connection configured
+yet. To turn it on:
 
-- `../13-TECH-STACK/TECH_STACK.md` — the chosen stack and why.
-- `../03-INSTRUCTION/DATABASE_SPEC.md` — the database schema this app
-  should query against.
+1. Copy `.env.example` to `.env` and pick a `DB_PROVIDER`: `supabase`,
+   `neon`, `cloudflare-d1`, or `postgres`. Read
+   `../13-TECH-STACK/DB_PROVIDER_GUIDE.md` first if you're unsure which —
+   it covers free-tier limits and which providers can deploy where.
+2. Fill in that provider's connection details in `.env` (see the comments
+   in `.env.example`).
+3. Run `npx drizzle-kit generate` then apply the generated migration to
+   create the `user`/`account`/`session`/`verificationToken` tables.
+4. Add at least one Auth.js provider (OAuth or credentials) to the empty
+   `providers: []` array in `lib/auth.ts` — auth won't work until you do.
+5. Replace the contents of `lib/mock-data.ts` (or its call sites) with
+   real queries against `getDb()` from `lib/db`.
 
-Keep the typed interfaces (`MockUser`, `MockMemberContent`, `MockMetric`)
-as the contract — swap the data source, not the shape, unless the database
-spec requires otherwise.
+Before writing your own tables, also read
+`../03-INSTRUCTION/DATABASE_SPEC.md` for the schema-design template this
+app's data model should follow.

package/templates/starter-kit/drizzle.config.ts

@@ -0,0 +1,27 @@
+import { defineConfig } from "drizzle-kit"
+
+const provider = process.env.DB_PROVIDER
+
+const config =
+  provider === "cloudflare-d1"
+    ? defineConfig({
+        dialect: "sqlite",
+        schema: "./lib/db/schema.sqlite.ts",
+        out: "./drizzle/sqlite",
+        driver: "d1-http",
+        dbCredentials: {
+          accountId: process.env.CLOUDFLARE_ACCOUNT_ID ?? "",
+          databaseId: process.env.CLOUDFLARE_D1_DATABASE_ID ?? "",
+          token: process.env.CLOUDFLARE_API_TOKEN ?? "",
+        },
+      })
+    : defineConfig({
+        dialect: "postgresql",
+        schema: "./lib/db/schema.pg.ts",
+        out: "./drizzle/postgres",
+        dbCredentials: {
+          url: process.env.DATABASE_URL ?? "",
+        },
+      })
+
+export default config

package/templates/starter-kit/lib/auth.ts

@@ -0,0 +1,30 @@
+import NextAuth from "next-auth"
+import { DrizzleAdapter } from "@auth/drizzle-adapter"
+import { getDb } from "./db"
+import * as pgSchema from "./db/schema.pg"
+import * as sqliteSchema from "./db/schema.sqlite"
+
+const provider = process.env.DB_PROVIDER
+const schema = (provider === "cloudflare-d1" ? sqliteSchema : pgSchema) as any
+
+// D1's binding only exists inside a Cloudflare request context, so the
+// adapter is built per-request via NextAuth's config-function form instead
+// of once at module scope (which is enough for every other provider).
+export const { handlers, signIn, signOut, auth } = NextAuth(async () => {
+  if (provider === "cloudflare-d1") {
+    const { getCloudflareContext } = await import("@opennextjs/cloudflare")
+    const { env } = getCloudflareContext()
+    return {
+      adapter: DrizzleAdapter(getDb((env as { DB: unknown }).DB), schema),
+      // No providers configured yet — add at least one (OAuth or
+      // credentials) before this auth setup is functional.
+      providers: [],
+      session: { strategy: "database" },
+    }
+  }
+  return {
+    adapter: DrizzleAdapter(getDb(), schema),
+    providers: [],
+    session: { strategy: "database" },
+  }
+})

package/templates/starter-kit/lib/db/index.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"
+import { getDb } from "./index"
+
+describe("getDb", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs()
+  })
+
+  it("throws when DB_PROVIDER is missing", () => {
+    vi.stubEnv("DB_PROVIDER", "")
+    expect(() => getDb()).toThrow(/DB_PROVIDER/)
+  })
+
+  it("throws when DB_PROVIDER is invalid", () => {
+    vi.stubEnv("DB_PROVIDER", "mongodb")
+    expect(() => getDb()).toThrow(/DB_PROVIDER/)
+  })
+
+  it("throws when DB_PROVIDER=postgres and DATABASE_URL is missing", () => {
+    vi.stubEnv("DB_PROVIDER", "postgres")
+    vi.stubEnv("DATABASE_URL", "")
+    expect(() => getDb()).toThrow(/DATABASE_URL/)
+  })
+
+  it("constructs a client for DB_PROVIDER=postgres given a connection string", () => {
+    vi.stubEnv("DB_PROVIDER", "postgres")
+    vi.stubEnv("DATABASE_URL", "postgres://user:pass@localhost:5432/db")
+    expect(() => getDb()).not.toThrow()
+  })
+
+  it("constructs a client for DB_PROVIDER=supabase given a connection string", () => {
+    vi.stubEnv("DB_PROVIDER", "supabase")
+    vi.stubEnv("DATABASE_URL", "postgres://user:pass@localhost:5432/db")
+    expect(() => getDb()).not.toThrow()
+  })
+
+  it("constructs a client for DB_PROVIDER=neon given a connection string", () => {
+    vi.stubEnv("DB_PROVIDER", "neon")
+    vi.stubEnv("DATABASE_URL", "postgres://user:pass@neon.example.com/db")
+    expect(() => getDb()).not.toThrow()
+  })
+
+  it("throws when DB_PROVIDER=cloudflare-d1 and no binding is passed", () => {
+    vi.stubEnv("DB_PROVIDER", "cloudflare-d1")
+    expect(() => getDb()).toThrow(/d1Binding/)
+  })
+
+  it("constructs a client for DB_PROVIDER=cloudflare-d1 given a binding", () => {
+    vi.stubEnv("DB_PROVIDER", "cloudflare-d1")
+    const fakeBinding = {} as never
+    expect(() => getDb(fakeBinding)).not.toThrow()
+  })
+})

package/templates/starter-kit/lib/db/index.ts

@@ -0,0 +1,64 @@
+import { drizzle as drizzlePg } from "drizzle-orm/postgres-js"
+import postgres from "postgres"
+import { drizzle as drizzleNeon } from "drizzle-orm/neon-http"
+import { neon } from "@neondatabase/serverless"
+import { drizzle as drizzleD1 } from "drizzle-orm/d1"
+import * as pgSchema from "./schema.pg"
+import * as sqliteSchema from "./schema.sqlite"
+
+export type DbProvider = "supabase" | "neon" | "cloudflare-d1" | "postgres"
+
+function getProvider(): DbProvider {
+  const provider = process.env.DB_PROVIDER
+  if (
+    provider !== "supabase" &&
+    provider !== "neon" &&
+    provider !== "cloudflare-d1" &&
+    provider !== "postgres"
+  ) {
+    throw new Error(
+      `Invalid or missing DB_PROVIDER env var: "${provider}". Must be one of: supabase, neon, cloudflare-d1, postgres. See .env.example.`
+    )
+  }
+  return provider
+}
+
+// D1's binding only exists inside a Cloudflare request context (there is no
+// connection string for it), so callers on that path must pass it in.
+export function getDb(d1Binding?: unknown) {
+  const provider = getProvider()
+
+  switch (provider) {
+    case "supabase":
+    case "postgres": {
+      const connectionString = process.env.DATABASE_URL
+      if (!connectionString) {
+        throw new Error(
+          `DATABASE_URL is required when DB_PROVIDER is "${provider}". See .env.example.`
+        )
+      }
+      const client = postgres(connectionString)
+      return drizzlePg(client, { schema: pgSchema })
+    }
+    case "neon": {
+      const connectionString = process.env.DATABASE_URL
+      if (!connectionString) {
+        throw new Error(
+          'DATABASE_URL is required when DB_PROVIDER is "neon". See .env.example.'
+        )
+      }
+      const client = neon(connectionString)
+      return drizzleNeon(client, { schema: pgSchema })
+    }
+    case "cloudflare-d1": {
+      if (!d1Binding) {
+        throw new Error(
+          'DB_PROVIDER is "cloudflare-d1" but no d1Binding was passed to getDb(). ' +
+            "D1's binding comes from the Cloudflare runtime context (e.g. getCloudflareContext().env.DB " +
+            "from @opennextjs/cloudflare) — it cannot be constructed from an env var alone."
+        )
+      }
+      return drizzleD1(d1Binding as never, { schema: sqliteSchema })
+    }
+  }
+}

package/templates/starter-kit/lib/db/schema.pg.ts

@@ -0,0 +1,58 @@
+import { integer, timestamp, pgTable, primaryKey, text } from "drizzle-orm/pg-core"
+import type { AdapterAccountType } from "next-auth/adapters"
+
+export const users = pgTable("user", {
+  id: text("id")
+    .primaryKey()
+    .$defaultFn(() => crypto.randomUUID()),
+  name: text("name"),
+  email: text("email").unique(),
+  emailVerified: timestamp("emailVerified", { mode: "date" }),
+  image: text("image"),
+})
+
+export const accounts = pgTable(
+  "account",
+  {
+    userId: text("userId")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    type: text("type").$type<AdapterAccountType>().notNull(),
+    provider: text("provider").notNull(),
+    providerAccountId: text("providerAccountId").notNull(),
+    refresh_token: text("refresh_token"),
+    access_token: text("access_token"),
+    expires_at: integer("expires_at"),
+    token_type: text("token_type"),
+    scope: text("scope"),
+    id_token: text("id_token"),
+    session_state: text("session_state"),
+  },
+  (account) => ({
+    compoundKey: primaryKey({
+      columns: [account.provider, account.providerAccountId],
+    }),
+  })
+)
+
+export const sessions = pgTable("session", {
+  sessionToken: text("sessionToken").primaryKey(),
+  userId: text("userId")
+    .notNull()
+    .references(() => users.id, { onDelete: "cascade" }),
+  expires: timestamp("expires", { mode: "date" }).notNull(),
+})
+
+export const verificationTokens = pgTable(
+  "verificationToken",
+  {
+    identifier: text("identifier").notNull(),
+    token: text("token").notNull(),
+    expires: timestamp("expires", { mode: "date" }).notNull(),
+  },
+  (verificationToken) => ({
+    compositePk: primaryKey({
+      columns: [verificationToken.identifier, verificationToken.token],
+    }),
+  })
+)

package/templates/starter-kit/lib/db/schema.sqlite.ts

@@ -0,0 +1,58 @@
+import { sqliteTable, text, integer, primaryKey } from "drizzle-orm/sqlite-core"
+import type { AdapterAccountType } from "next-auth/adapters"
+
+export const users = sqliteTable("user", {
+  id: text("id")
+    .primaryKey()
+    .$defaultFn(() => crypto.randomUUID()),
+  name: text("name"),
+  email: text("email").unique(),
+  emailVerified: integer("emailVerified", { mode: "timestamp_ms" }),
+  image: text("image"),
+})
+
+export const accounts = sqliteTable(
+  "account",
+  {
+    userId: text("userId")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    type: text("type").$type<AdapterAccountType>().notNull(),
+    provider: text("provider").notNull(),
+    providerAccountId: text("providerAccountId").notNull(),
+    refresh_token: text("refresh_token"),
+    access_token: text("access_token"),
+    expires_at: integer("expires_at"),
+    token_type: text("token_type"),
+    scope: text("scope"),
+    id_token: text("id_token"),
+    session_state: text("session_state"),
+  },
+  (account) => ({
+    compoundKey: primaryKey({
+      columns: [account.provider, account.providerAccountId],
+    }),
+  })
+)
+
+export const sessions = sqliteTable("session", {
+  sessionToken: text("sessionToken").primaryKey(),
+  userId: text("userId")
+    .notNull()
+    .references(() => users.id, { onDelete: "cascade" }),
+  expires: integer("expires", { mode: "timestamp_ms" }).notNull(),
+})
+
+export const verificationTokens = sqliteTable(
+  "verificationToken",
+  {
+    identifier: text("identifier").notNull(),
+    token: text("token").notNull(),
+    expires: integer("expires", { mode: "timestamp_ms" }).notNull(),
+  },
+  (verificationToken) => ({
+    compositePk: primaryKey({
+      columns: [verificationToken.identifier, verificationToken.token],
+    }),
+  })
+)

package/templates/starter-kit/lib/storage.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect, afterEach, vi } from "vitest"
+import { createStorageClient } from "./storage"
+
+describe("createStorageClient", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs()
+  })
+
+  it("throws when STORAGE_PROVIDER=supabase and SUPABASE_URL is missing", () => {
+    vi.stubEnv("STORAGE_PROVIDER", "supabase")
+    vi.stubEnv("SUPABASE_URL", "")
+    vi.stubEnv("SUPABASE_SERVICE_ROLE_KEY", "")
+    expect(() => createStorageClient()).toThrow(/SUPABASE_URL/)
+  })
+
+  it("constructs a client when STORAGE_PROVIDER=supabase with credentials set", () => {
+    vi.stubEnv("STORAGE_PROVIDER", "supabase")
+    vi.stubEnv("SUPABASE_URL", "https://example.supabase.co")
+    vi.stubEnv("SUPABASE_SERVICE_ROLE_KEY", "fake-key")
+    expect(() => createStorageClient()).not.toThrow()
+  })
+
+  it("throws a clear not-implemented error for cloudflare-r2", () => {
+    vi.stubEnv("STORAGE_PROVIDER", "cloudflare-r2")
+    expect(() => createStorageClient()).toThrow(/not implemented/)
+  })
+
+  it("throws a clear not-implemented error for vercel-blob", () => {
+    vi.stubEnv("STORAGE_PROVIDER", "vercel-blob")
+    expect(() => createStorageClient()).toThrow(/not implemented/)
+  })
+})

package/templates/starter-kit/lib/storage.ts

@@ -0,0 +1,62 @@
+import { createClient } from "@supabase/supabase-js"
+
+export interface StorageClient {
+  upload(
+    path: string,
+    file: Blob | Buffer,
+    contentType: string
+  ): Promise<{ path: string; publicUrl: string }>
+  getPublicUrl(path: string): string
+  remove(path: string): Promise<void>
+}
+
+class SupabaseStorageClient implements StorageClient {
+  private client: ReturnType<typeof createClient>
+  private bucket: string
+
+  constructor(supabaseUrl: string, supabaseKey: string, bucket: string) {
+    this.client = createClient(supabaseUrl, supabaseKey)
+    this.bucket = bucket
+  }
+
+  async upload(path: string, file: Blob | Buffer, contentType: string) {
+    const { data, error } = await this.client.storage
+      .from(this.bucket)
+      .upload(path, file, { contentType, upsert: true })
+    if (error) throw error
+    return { path: data.path, publicUrl: this.getPublicUrl(data.path) }
+  }
+
+  getPublicUrl(path: string): string {
+    const { data } = this.client.storage.from(this.bucket).getPublicUrl(path)
+    return data.publicUrl
+  }
+
+  async remove(path: string): Promise<void> {
+    const { error } = await this.client.storage.from(this.bucket).remove([path])
+    if (error) throw error
+  }
+}
+
+export type StorageProvider = "supabase" | "cloudflare-r2" | "vercel-blob"
+
+export function createStorageClient(): StorageClient {
+  const storageProvider = (process.env.STORAGE_PROVIDER || "supabase") as StorageProvider
+
+  if (storageProvider === "supabase") {
+    const url = process.env.SUPABASE_URL
+    const key = process.env.SUPABASE_SERVICE_ROLE_KEY
+    const bucket = process.env.SUPABASE_STORAGE_BUCKET || "uploads"
+    if (!url || !key) {
+      throw new Error(
+        "SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY are required when STORAGE_PROVIDER=supabase. See .env.example."
+      )
+    }
+    return new SupabaseStorageClient(url, key, bucket)
+  }
+
+  throw new Error(
+    `STORAGE_PROVIDER="${storageProvider}" is not implemented yet — only "supabase" is wired up. ` +
+      "See 13-TECH-STACK/DB_PROVIDER_GUIDE.md for how to add Cloudflare R2 or Vercel Blob."
+  )
+}

package/templates/starter-kit/package.json

@@ -6,18 +6,25 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "lint": "next lint"
+    "lint": "next lint",
+    "test": "vitest run"
   },
   "dependencies": {
+    "@auth/drizzle-adapter": "^1.7.4",
+    "@neondatabase/serverless": "^0.10.3",
     "@radix-ui/react-avatar": "^1.1.0",
     "@radix-ui/react-dialog": "^1.1.1",
     "@radix-ui/react-dropdown-menu": "^2.1.1",
     "@radix-ui/react-slot": "^1.1.0",
     "@radix-ui/react-tabs": "^1.1.0",
+    "@supabase/supabase-js": "^2.46.1",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.1.1",
+    "drizzle-orm": "^0.36.0",
     "lucide-react": "^0.439.0",
     "next": "^16.2.9",
+    "next-auth": "5.0.0-beta.25",
+    "postgres": "^3.4.5",
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "tailwind-merge": "^2.5.2"
@@ -27,10 +34,12 @@
     "@types/react": "^18.3.4",
     "@types/react-dom": "^18.3.0",
     "autoprefixer": "^10.4.20",
+    "drizzle-kit": "^0.28.1",
     "eslint": "^8.57.0",
     "eslint-config-next": "14.2.5",
     "postcss": "^8.4.41",
     "tailwindcss": "^3.4.10",
-    "typescript": "^5.5.4"
+    "typescript": "^5.5.4",
+    "vitest": "^2.1.5"
   }
 }

package/templates/starter-kit/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config"
+
+export default defineConfig({
+  test: {
+    environment: "node",
+  },
+})