supabase-saas-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mateus Zingano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# saas-kit — the companion CLI for the SaaS boilerplate
+
+Four commands that make the boilerplate a one-liner to start, verify, grow, and
+ship — so the safe path (RLS on, env wired right, checks green) is the default.
+
+```bash
+npm install -g @mateuszingano/saas-kit   # or prefix each command with: npx @mateuszingano/saas-kit
+
+saas-kit new my-app              # scaffold (free starter)
+saas-kit doctor                  # env + Supabase + RLS
+saas-kit gen:migration add_projects   # RLS-safe migration
+saas-kit check                   # pre-deploy gate
+```
+
+## Commands
+
+### `new <name> (--repo <url> | --from <dir>)`
+Scaffolds a fresh project: clones/copies the template, strips `.git`, renames
+`package.json`, and seeds `.env` from `.env.example` — the first thing you do is
+run, not hunt for what to fill.
+
+- **(default)** — clones the free public
+  [nextjs-supabase-starter](https://github.com/mateuszingano/nextjs-supabase-starter).
+- `--repo <git-url>` — clones another repo, **public or private** (uses your git
+  credentials, so a buyer who owns the paid boilerplate scaffolds from it).
+- `--from <dir>` — copies a local template (offline).
+- or set `SAAS_KIT_TEMPLATE`.
+
+The default is the **free** starter, never a paid repo — a free CLI shouldn't
+hand out a paid boilerplate. Point `--repo` at the paid one when you own it.
+
+### `doctor [--env <path>]`
+Answers "is this wired up right?" without deploying to find out:
+- checks the env vars the app actually reads;
+- flags a service-role key exposed to the browser as an **error**, not a warning;
+- pings Supabase over REST to confirm it's reachable;
+- points you at [Airlock](../16-CI-SEGURANCA-SUPABASE/airlock) for a real RLS audit.
+
+Exits non-zero when required vars are missing — safe to drop in CI.
+
+### `gen:migration <name>`
+Creates `supabase/migrations/<timestamp>_<slug>.sql` pre-filled with the
+boilerplate's RLS-first pattern: RLS enabled, API roles granted, and all four
+verbs scoped to the user's workspaces. Shipping a table with RLS off is the #1
+Supabase footgun — this makes it the hard thing to do by accident.
+
+### `check [--skip-e2e]`
+The pre-deploy gate. Runs the quality steps the project ships — `typecheck`,
+`lint`, `test`, `e2e` — in order, stopping at the first failure, then runs an
+RLS audit via Airlock when `SUPABASE_DB_URL` is set. One command answers "is
+this safe to ship?" instead of remembering four. Non-zero on any failure.
+
+## Why it's free
+This CLI is the front door to the boilerplate. It's MIT and standalone; the paid
+products are the boilerplate it scaffolds, the Pro tier, and Airlock for
+continuous RLS monitoring. Use it on anything.
+
+## Develop
+```bash
+npm test          # 29 tests, offline
+node bin/cli.mjs --help
+```
+
+MIT © Mateus Zingano

package/bin/cli.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// saas-kit — companion CLI for the SaaS boilerplate.
+//   saas-kit new <name> (--repo <url> | --from <dir>)   scaffold a new project
+//   saas-kit doctor [--env <path>]                        check env + Supabase + RLS
+//   saas-kit gen:migration <name>                         RLS-safe migration
+//   saas-kit check [--skip-e2e]                           pre-deploy gate
+
+import { resolve, join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { parseArgs } from '../src/args.mjs';
+import { genMigration } from '../src/gen-migration.mjs';
+import { scaffold } from '../src/new.mjs';
+import { loadEnv, checkEnv } from '../src/doctor.mjs';
+import { runCheck } from '../src/check.mjs';
+
+const HELP = `saas-kit — companion CLI for the SaaS boilerplate
+
+Usage:
+  saas-kit new <name> [--repo <url> | --from <dir>]   Scaffold a new project
+  saas-kit doctor [--env <path>]                      Check env, Supabase, RLS
+  saas-kit gen:migration <name>                       Create an RLS-safe migration
+  saas-kit check [--skip-e2e]                         Run the pre-deploy gate
+  saas-kit --help                                     Show this help
+
+Template source for \`new\` (defaults to the free public starter):
+  (default)          the free nextjs-supabase-starter
+  --repo <git-url>   clone another repo (public or private — uses your git auth)
+  --from <dir>       copy a local template
+  or set SAAS_KIT_TEMPLATE
+
+Examples:
+  saas-kit new my-app                       # from the free starter
+  saas-kit new my-app --repo <paid-repo>    # from the paid boilerplate you own
+  saas-kit gen:migration add_projects
+  SUPABASE_DB_URL=postgres://... saas-kit check
+`;
+
+// Best-effort online check: can the anon key reach REST?
+async function probeSupabase(env) {
+  const url = env.NEXT_PUBLIC_SUPABASE_URL;
+  const key = env.NEXT_PUBLIC_SUPABASE_ANON_KEY;
+  if (!url || !key) return { skipped: true };
+  try {
+    const res = await fetch(`${url.replace(/\/$/, '')}/rest/v1/`, {
+      headers: { apikey: key, Authorization: `Bearer ${key}` },
+    });
+    return { reachable: res.ok || res.status === 404, status: res.status };
+  } catch (err) {
+    return { reachable: false, error: err.message };
+  }
+}
+
+async function cmdDoctor(flags) {
+  const envPath = typeof flags.env === 'string' ? flags.env : '.env';
+  const env = loadEnv(envPath, process.env);
+  const { results, ok } = checkEnv(env);
+
+  console.log(`\nsaas-kit doctor — ${existsSync(envPath) ? envPath : 'process env'}\n`);
+  for (const r of results) {
+    const mark = r.status === 'ok' ? '✔' : r.status === 'warn' ? '!' : '✖';
+    console.log(`  ${mark} ${r.key}${r.present ? '' : '  (missing)'}`);
+    if (r.status !== 'ok') console.log(`      ${r.hint}`);
+  }
+
+  const probe = await probeSupabase(env);
+  if (probe.skipped) {
+    console.log('\n  · Supabase probe skipped (fill the env first).');
+  } else if (probe.reachable) {
+    console.log(`\n  ✔ Supabase reachable (HTTP ${probe.status}).`);
+    console.log('  · For a real RLS audit, run: npx airlock-rls "$SUPABASE_DB_URL"');
+  } else {
+    console.log(`\n  ✖ Could not reach Supabase (${probe.error || 'HTTP ' + probe.status}).`);
+  }
+
+  console.log('');
+  process.exit(ok && (probe.skipped || probe.reachable) ? 0 : 1);
+}
+
+function cmdNew(positional, flags) {
+  const name = positional[0];
+  if (!name) throw new Error('usage: saas-kit new <name> (--repo <url> | --from <dir>)');
+  const dest = resolve(process.cwd(), name);
+  scaffold({ name, dest, flags, env: process.env });
+  console.log(`\n✔ Scaffolded ${name} at ${dest}`);
+  console.log('\nNext:');
+  console.log(`  cd ${name}`);
+  console.log('  npm install');
+  console.log('  # fill .env, then: supabase start && npm run dev');
+  console.log('  saas-kit doctor\n');
+}
+
+function cmdGenMigration(positional) {
+  const name = positional.join(' ').trim();
+  const path = genMigration({ name });
+  console.log(`✔ Created ${path}`);
+  console.log('  Edit the columns; keep the RLS block. Then: supabase db push');
+}
+
+function cmdCheck(flags) {
+  const pkgPath = resolve(process.cwd(), 'package.json');
+  if (!existsSync(pkgPath)) throw new Error('no package.json here — run inside a project');
+  const scripts = JSON.parse(readFileSync(pkgPath, 'utf8')).scripts || {};
+  const dbUrl = process.env.SUPABASE_DB_URL || '';
+  console.log('\nsaas-kit check — pre-deploy gate\n');
+  const { ok } = runCheck(scripts, { dbUrl, skipE2e: !!flags['skip-e2e'] });
+  console.log('');
+  process.exit(ok ? 0 : 1);
+}
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  const { flags, positional } = parseArgs(rest);
+
+  if (!command || command === '--help' || command === '-h' || flags.help) {
+    console.log(HELP);
+    return;
+  }
+
+  switch (command) {
+    case 'new':
+      return cmdNew(positional, flags);
+    case 'doctor':
+      return cmdDoctor(flags);
+    case 'gen:migration':
+    case 'migration':
+      return cmdGenMigration(positional);
+    case 'check':
+      return cmdCheck(flags);
+    default:
+      console.error(`Unknown command: ${command}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(`✖ ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "supabase-saas-kit",
+  "version": "0.1.0",
+  "description": "The companion CLI for the SaaS boilerplate: scaffold a new project, check your Supabase setup (RLS included), and generate RLS-safe migrations.",
+  "type": "module",
+  "bin": {
+    "saas-kit": "bin/cli.mjs",
+    "supabase-saas-kit": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/cli.mjs",
+    "test": "node --test",
+    "prepublishOnly": "node --test"
+  },
+  "keywords": [
+    "supabase",
+    "nextjs",
+    "saas",
+    "boilerplate",
+    "scaffold",
+    "rls",
+    "cli",
+    "migrations"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "Mateus Zingano",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mateuszingano/saas-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mateuszingano/saas-kit/issues"
+  },
+  "homepage": "https://github.com/mateuszingano/saas-kit#readme",
+  "license": "MIT"
+}

package/src/args.mjs

@@ -0,0 +1,23 @@
+// Tiny arg parser shared by the CLI and its tests. Pulls `--key value` and
+// `--flag` (boolean) out of argv, leaving positionals in order.
+
+export function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { flags, positional };
+}

package/src/check.mjs

@@ -0,0 +1,69 @@
+// check — the pre-deploy gate. Runs the quality steps the boilerplate ships
+// (typecheck, lint, test, e2e) plus a real RLS audit via Airlock, and stops at
+// the first failure. One command answers "is this safe to ship?" instead of
+// remembering four.
+
+import { execSync } from 'node:child_process';
+
+// Canonical order: cheapest/fastest signal first, so failures surface early.
+const STEP_ORDER = ['typecheck', 'lint', 'test', 'e2e'];
+
+/**
+ * Pure: given a package.json `scripts` object and options, produce the ordered
+ * list of steps to run. Only includes scripts that actually exist; appends an
+ * RLS audit when a DB url is available (skips it otherwise, and says so).
+ * Returns [{ name, cmd }].
+ */
+export function buildCheckSteps(scripts = {}, { dbUrl = '', skipE2e = false } = {}) {
+  const steps = STEP_ORDER.filter((s) => {
+    if (s === 'e2e' && skipE2e) return false;
+    return typeof scripts[s] === 'string';
+  }).map((s) => ({ name: s, cmd: `npm run ${s}` }));
+
+  if (dbUrl) {
+    steps.push({ name: 'rls-audit', cmd: `npx airlock-rls "${dbUrl}"` });
+  }
+  return steps;
+}
+
+/** Human summary of what will run and what's skipped, for the header. */
+export function planSummary(scripts = {}, opts = {}) {
+  const steps = buildCheckSteps(scripts, opts);
+  const names = steps.map((s) => s.name);
+  const missing = STEP_ORDER.filter((s) => typeof scripts[s] !== 'string');
+  const notes = [];
+  if (!opts.dbUrl) notes.push('rls-audit skipped (set SUPABASE_DB_URL to enable)');
+  if (missing.length) notes.push(`no script for: ${missing.join(', ')}`);
+  return { steps, names, notes };
+}
+
+/**
+ * Run the steps in order, stopping at the first non-zero exit.
+ * `run` is injectable for tests. Returns { ok, ran, failed }.
+ */
+export function runCheck(scripts, opts = {}, run = defaultRun) {
+  const { steps, notes } = planSummary(scripts, opts);
+  for (const note of notes) console.log(`  · ${note}`);
+  if (!steps.length) {
+    console.log('\n  ✖ nothing to run — is this a boilerplate project?');
+    return { ok: false, ran: [], failed: null };
+  }
+
+  const ran = [];
+  for (const step of steps) {
+    console.log(`\n▶ ${step.name}: ${step.cmd}`);
+    try {
+      run(step.cmd);
+      ran.push(step.name);
+    } catch {
+      console.log(`\n  ✖ ${step.name} failed — stopping.`);
+      return { ok: false, ran, failed: step.name };
+    }
+  }
+  console.log(`\n  ✔ all checks passed (${ran.join(', ')}).`);
+  return { ok: true, ran, failed: null };
+}
+
+function defaultRun(cmd) {
+  execSync(cmd, { stdio: 'inherit' });
+}

package/src/doctor.mjs

@@ -0,0 +1,82 @@
+// doctor — is this project wired up right? Checks the env vars the boilerplate
+// needs, then (best effort, online) pings Supabase and confirms the anon role
+// is NOT reading a table it shouldn't. The RLS check is what makes this more
+// than a spellchecker: it catches the exposed-table footgun before deploy.
+
+import { readFileSync, existsSync } from 'node:fs';
+
+// The vars the app actually reads (grounded in the boilerplate .env.example).
+export const ENV_SPEC = [
+  {
+    key: 'NEXT_PUBLIC_SUPABASE_URL',
+    level: 'error',
+    hint: 'Supabase project URL. Local: `supabase start` prints it. Prod: dashboard → Settings → API.',
+  },
+  {
+    key: 'NEXT_PUBLIC_SUPABASE_ANON_KEY',
+    level: 'error',
+    hint: 'Anon public key from the same place. Safe to expose to the browser.',
+  },
+  {
+    key: 'SUPABASE_SERVICE_ROLE_KEY',
+    level: 'warn',
+    hint: 'Server-only, bypasses RLS. Optional until you write privileged server code. NEVER prefix with NEXT_PUBLIC_.',
+  },
+];
+
+/** Parse a .env file into a plain object. Tolerates comments, blanks, quotes. */
+export function parseEnv(text) {
+  const out = {};
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    let val = line.slice(eq + 1).trim();
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    out[key] = val;
+  }
+  return out;
+}
+
+/** Merge process.env over a .env file at `envPath` (real env wins). */
+export function loadEnv(envPath = '.env', processEnv = {}) {
+  const fromFile = existsSync(envPath) ? parseEnv(readFileSync(envPath, 'utf8')) : {};
+  return { ...fromFile, ...processEnv };
+}
+
+/**
+ * Pure check: given an env object, return one result per spec'd var.
+ * A NEXT_PUBLIC_-prefixed service role key is flagged as an error (leak),
+ * even though it's "present" — being set the wrong way is worse than unset.
+ */
+export function checkEnv(env, spec = ENV_SPEC) {
+  const results = spec.map(({ key, level, hint }) => {
+    const value = env[key];
+    const present = typeof value === 'string' && value.length > 0;
+    return {
+      key,
+      present,
+      level,
+      hint,
+      status: present ? 'ok' : level, // 'ok' | 'error' | 'warn'
+    };
+  });
+
+  // Extra guard: the service key must never be public.
+  if (env.NEXT_PUBLIC_SUPABASE_SERVICE_ROLE_KEY) {
+    results.push({
+      key: 'NEXT_PUBLIC_SUPABASE_SERVICE_ROLE_KEY',
+      present: true,
+      level: 'error',
+      hint: 'The service role key is exposed to the browser. Remove the NEXT_PUBLIC_ prefix immediately.',
+      status: 'error',
+    });
+  }
+
+  const hasError = results.some((r) => r.status === 'error');
+  return { results, ok: !hasError };
+}

package/src/gen-migration.mjs

@@ -0,0 +1,108 @@
+// gen:migration — create a new Supabase migration that follows the boilerplate's
+// RLS-first convention. A table never ships without Row Level Security here:
+// the skeleton enables RLS, grants the API roles, and scopes all four verbs to
+// the user's workspaces. Copy-paste-shipping a table with RLS off is the #1
+// Supabase footgun; this template makes the safe path the default path.
+
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Two-digit zero-pad.
+const p2 = (n) => String(n).padStart(2, '0');
+
+/**
+ * Build the `YYYYMMDDHHmmss` timestamp Supabase orders migrations by.
+ * `date` is injectable so tests are deterministic.
+ */
+export function migrationTimestamp(date = new Date()) {
+  return (
+    date.getUTCFullYear().toString() +
+    p2(date.getUTCMonth() + 1) +
+    p2(date.getUTCDate()) +
+    p2(date.getUTCHours()) +
+    p2(date.getUTCMinutes()) +
+    p2(date.getUTCSeconds())
+  );
+}
+
+/** Turn a human name into a snake_case slug safe for a filename. */
+export function slugify(name) {
+  const slug = String(name)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+  if (!slug) throw new Error('migration name is empty after slugifying');
+  return slug;
+}
+
+/** `20260707123000_add_projects.sql` */
+export function migrationFilename(name, date = new Date()) {
+  return `${migrationTimestamp(date)}_${slugify(name)}.sql`;
+}
+
+/**
+ * The RLS-first skeleton. `table` defaults to the slug so a name like
+ * "projects" produces a ready-to-edit `public.projects` table; anything the
+ * dev must decide is a clearly-marked TODO, never a silent gap.
+ */
+export function migrationSkeleton(name) {
+  const table = slugify(name);
+  return `-- ${name}
+-- RLS-first: this table is scoped to a workspace and can't ship exposed.
+-- Adjust the columns; keep the security block. The isolation test in the
+-- boilerplate proves tenant A can't touch tenant B's rows.
+
+create table public.${table} (
+  id uuid primary key default gen_random_uuid(),
+  workspace_id uuid not null references public.workspaces (id) on delete cascade,
+  author_id uuid not null references auth.users (id) on delete cascade,
+  -- TODO: your columns here
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+create index ${table}_workspace_id_idx on public.${table} (workspace_id);
+
+alter table public.${table} enable row level security;
+
+-- Table privileges for the API roles (RLS below governs which rows).
+grant select on public.${table} to anon;
+grant select, insert, update, delete on public.${table} to authenticated;
+grant all on public.${table} to service_role;
+
+create policy "read ${table} in my workspaces"
+  on public.${table} for select
+  using (workspace_id in (select public.user_workspace_ids()));
+
+create policy "create ${table} in my workspaces"
+  on public.${table} for insert
+  with check (
+    workspace_id in (select public.user_workspace_ids())
+    and author_id = (select auth.uid())
+  );
+
+create policy "update ${table} in my workspaces"
+  on public.${table} for update
+  using (workspace_id in (select public.user_workspace_ids()))
+  with check (workspace_id in (select public.user_workspace_ids()));
+
+create policy "delete ${table} in my workspaces"
+  on public.${table} for delete
+  using (workspace_id in (select public.user_workspace_ids()));
+`;
+}
+
+/**
+ * Write the migration. Returns the absolute path written.
+ * Throws if the target file already exists (never clobber).
+ */
+export function genMigration({ name, dir = 'supabase/migrations', date = new Date() }) {
+  if (!name) throw new Error('usage: saas-kit gen:migration <name>');
+  const filename = migrationFilename(name, date);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const path = join(dir, filename);
+  if (existsSync(path)) throw new Error(`refusing to overwrite existing migration: ${path}`);
+  writeFileSync(path, migrationSkeleton(name), 'utf8');
+  return path;
+}

package/src/new.mjs

@@ -0,0 +1,135 @@
+// new — scaffold a fresh project from a template. Works three ways:
+//   (default)      clone the free public starter (DEFAULT_TEMPLATE below)
+//   --from <dir>   copy a local template (offline; used in dev/tests)
+//   --repo <url>   git clone any template (public OR private — uses the caller's
+//                  git credentials, so a buyer invited to the paid private repo
+//                  can scaffold straight from it)
+// The default is the FREE starter, never the paid boilerplate — a free CLI must
+// not hand out a paid repo. Point --repo at the paid one when you own it.
+
+// The free, public top-of-funnel starter. Cloning this is the zero-arg path.
+export const DEFAULT_TEMPLATE = 'https://github.com/mateuszingano/nextjs-supabase-starter.git';
+
+import {
+  cpSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  rmSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+// Never carry build artifacts, deps, or local secrets into a new project.
+const IGNORE = new Set([
+  'node_modules',
+  '.next',
+  '.git',
+  'coverage',
+  'test-results',
+  '.env',
+  '.env.local',
+  '.env.test',
+  'tsconfig.tsbuildinfo',
+]);
+
+/** Pure: should this top-level entry be skipped when scaffolding? */
+export function ignoreEntry(name) {
+  return IGNORE.has(name);
+}
+
+/** Set the "name" field of a package.json string to `name`, reset version. */
+export function renamePackage(pkgJson, name) {
+  const pkg = JSON.parse(pkgJson);
+  pkg.name = name;
+  pkg.version = '0.1.0';
+  return JSON.stringify(pkg, null, 2) + '\n';
+}
+
+/**
+ * Pure: decide where the template comes from, from flags + env.
+ * A value that looks like a git URL is treated as a repo, otherwise local dir.
+ * Returns { kind: 'local' | 'repo' | 'none', value }.
+ */
+export function resolveSource(flags = {}, env = {}) {
+  if (typeof flags.from === 'string') return { kind: 'local', value: flags.from };
+  if (typeof flags.repo === 'string') return { kind: 'repo', value: flags.repo };
+  const tmpl = env.SAAS_KIT_TEMPLATE;
+  if (tmpl) {
+    const looksGit = /^https?:\/\/|^git@|\.git$/.test(tmpl);
+    return { kind: looksGit ? 'repo' : 'local', value: tmpl };
+  }
+  // No explicit source → default to the free public starter.
+  return { kind: 'repo', value: DEFAULT_TEMPLATE };
+}
+
+/** Post-clone/copy cleanup: strip .git, rename package, seed .env. */
+export function finalize(dest, name) {
+  const gitDir = join(dest, '.git');
+  if (existsSync(gitDir)) rmSync(gitDir, { recursive: true, force: true });
+
+  const pkgPath = join(dest, 'package.json');
+  if (existsSync(pkgPath)) {
+    writeFileSync(pkgPath, renamePackage(readFileSync(pkgPath, 'utf8'), name), 'utf8');
+  }
+
+  const envPath = join(dest, '.env');
+  const examplePath = join(dest, '.env.example');
+  if (!existsSync(envPath) && existsSync(examplePath)) {
+    writeFileSync(envPath, readFileSync(examplePath, 'utf8'), 'utf8');
+  }
+  return dest;
+}
+
+/** Copy a local template dir into dest, honoring IGNORE. */
+export function scaffoldLocal({ name, from, dest }) {
+  if (!name) throw new Error('usage: saas-kit new <name>');
+  if (!from || !existsSync(from)) throw new Error(`template not found: ${from}`);
+  if (existsSync(dest)) throw new Error(`refusing to overwrite existing directory: ${dest}`);
+
+  cpSync(from, dest, {
+    recursive: true,
+    filter: (src) => {
+      const rel = src.slice(resolve(from).length).replace(/^[\\/]/, '');
+      const top = rel.split(/[\\/]/)[0];
+      return !(top && ignoreEntry(top));
+    },
+  });
+  return finalize(dest, name);
+}
+
+/** Shallow git clone a template repo into dest, then finalize. */
+export function scaffoldRepo({ name, repo, dest, clone = defaultClone }) {
+  if (!name) throw new Error('usage: saas-kit new <name>');
+  if (existsSync(dest)) throw new Error(`refusing to overwrite existing directory: ${dest}`);
+  clone(repo, dest);
+  return finalize(dest, name);
+}
+
+// Real clone (injectable so tests don't hit the network).
+function defaultClone(repo, dest) {
+  try {
+    execFileSync('git', ['clone', '--depth', '1', repo, dest], { stdio: 'pipe' });
+  } catch (err) {
+    const detail = err.stderr ? err.stderr.toString().trim() : err.message;
+    throw new Error(`git clone failed for ${repo}\n  ${detail}`);
+  }
+}
+
+/**
+ * Top-level scaffold: resolves the source and dispatches. `dest` is absolute.
+ * Throws a helpful error when no source is configured.
+ */
+export function scaffold({ name, dest, flags = {}, env = {}, clone }) {
+  const source = resolveSource(flags, env);
+  if (source.kind === 'none') {
+    throw new Error(
+      'no template source. Pass --repo <git-url> or --from <dir>,\n' +
+        '  or set SAAS_KIT_TEMPLATE. (A free CLI ships no default paid repo.)'
+    );
+  }
+  if (source.kind === 'local') {
+    return scaffoldLocal({ name, from: resolve(source.value), dest });
+  }
+  return scaffoldRepo({ name, repo: source.value, dest, clone });
+}