create-ailk 0.9.0 → 0.11.0

package/templates/.claude/skills/add-auth/SKILL.md

@@ -1,261 +0,0 @@
----
-name: add-auth
-description: Activate auth providers (magic-link via Resend, Google OAuth, GitHub OAuth) on an AILK consumer site. Use when the user says "wire up auth", "add login", "set up sign-in", "I need users to log in", or asks how to enable any of magic-link / Google / GitHub auth on their AILK site. The skill writes env vars for whichever subset of providers the consumer activates and prints (plus saves) an OAuth-app-setup runbook. It does NOT modify `auth.config.ts` and does NOT emit any pages.
----
-
-# add-auth
-
-Activate one or more auth providers on an AILK site by writing the env
-vars NextAuth reads to detect them, plus a `RUNBOOK.md` that documents
-the OAuth-app-creation steps for the consumer's records.
-
-## When to use
-
-The user has a working AILK site (post-`pnpm create ailk`) and wants
-to gate routes behind sign-in, send magic-link emails, or accept
-Google / GitHub OAuth. Phrases that should trigger this skill:
-
-- "wire up auth" / "add login" / "set up sign-in"
-- "I want users to log in"
-- "enable Google sign-in" / "enable GitHub login"
-- "set up magic-link auth"
-- "add OAuth"
-
-Skip this skill when:
-
-- The user wants a `/login` or `/account` _page_ — those are pages, not
-  auth wiring. Use `add-page` for that.
-- The user is asking about a third-party provider that isn't in the
-  AILK locked set (Apple, Microsoft, Twitter, etc.). The locked set is
-  magic-link + Google + GitHub at v1; broader provider support is a
-  future PR. Acknowledge the request and stop.
-- The user is in production and needs production callback URLs. v1
-  ships dev-mode callbacks (`http://localhost:3000`) only —
-  production callback setup is deferred to `setup-deploy`
-  or a future deploy skill. Note this and stop.
-
-## What this skill does (and does not do)
-
-**Does:**
-
-- Reads `.env.local` to see which providers are already activated.
-- Asks the consumer which of the three locked providers
-  (magic-link, Google, GitHub) they want to activate _this session_.
-- For each picked provider, walks the consumer through
-  OAuth-app-creation (Google / GitHub) or Resend-key setup
-  (magic-link), then writes the resulting secrets to `.env.local`.
-- Auto-detects whether `@working-theory/database` is installed with User /
-  Session models (Prisma adapter mode) or not (JWT-only mode), and
-  states which mode the site is in.
-- Writes (or merges) a `RUNBOOK.md` in the consumer's repo root
-  with the same setup instructions the consumer just followed, so
-  they can refer back later or hand to a collaborator.
-
-**Does not:**
-
-- Modify `auth.config.ts`. The locked-set providers are env-var-driven
-  — present env vars activate the matching provider in
-  `auth.config.ts`'s `buildProviders()`. No code changes are needed.
-- Create any new files under `app/`, `pages/`, or `content/`. The
-  emit is limited to `.env.local` writes and a `RUNBOOK.md` write.
-- Set up production callback URLs. Dev-mode (`http://localhost:3000`)
-  only at v1.
-- Add, remove, or modify any provider entry in `auth.config.ts`
-  outside of magic-link / Google / GitHub. Consumer-added providers
-  (e.g., Apple) are preserved as-is and never touched by this skill.
-- Accept production OAuth credentials. If the consumer pastes a
-  production-looking secret, that's acceptable, but the runbook still
-  documents only the dev callback URL.
-
-## The mechanic
-
-### Step 1 — Show the menu
-
-Greet the consumer and present the three locked providers, marking
-which are already activated (env vars present in `.env.local`):
-
-```
-Which auth providers do you want to activate?
-
-  [ ] magic-link  (passwordless email login via Resend)
-  [ ] Google OAuth
-  [ ] GitHub OAuth
-
-You can pick any subset, including "none of the above" (in which case
-this skill exits without writing anything). You can also re-run this
-skill later to activate more providers — already-activated providers
-will be skipped automatically.
-```
-
-If `.env.local` already has any of these activated, mark them:
-
-```
-  [x] magic-link  (already activated — AUTH_EMAIL_SERVER + AUTH_EMAIL_FROM are set)
-  [ ] Google OAuth
-  [ ] GitHub OAuth
-```
-
-Wait for the consumer to pick a subset. Then, for each picked
-provider, run the matching sub-flow.
-
-### Step 2 — Run per-provider sub-flows
-
-#### magic-link sub-flow
-
-1. Tell the consumer: _"Magic-link uses Resend as the email provider
-   at AILK v1. Other email providers ship as additive future PRs.
-   You'll need a Resend API key (free tier is fine for development).
-   Get one at <https://resend.com/api-keys>."_
-2. Wait for the consumer to paste the API key.
-3. Ask for the `AUTH_EMAIL_FROM` address. This must be a verified
-   sender on the consumer's Resend account. For development it's
-   common to use `onboarding@resend.dev` (Resend's shared dev
-   sender). Mention that.
-4. Construct `AUTH_EMAIL_SERVER` as
-   `smtp://resend:<API_KEY>@smtp.resend.com:465`.
-5. Write to `.env.local`:
-   ```
-   AUTH_EMAIL_SERVER=smtp://resend:re_...@smtp.resend.com:465
-   AUTH_EMAIL_FROM=onboarding@resend.dev
-   ```
-
-#### Google OAuth sub-flow
-
-1. Tell the consumer the steps in chat AND queue the same content for
-   the runbook (see Step 3). Steps:
-   - Go to <https://console.cloud.google.com/apis/credentials>.
-   - Click **Create Credentials → OAuth client ID**. If prompted,
-     configure the OAuth consent screen first (**External** → fill
-     name, support email, developer contact email; scopes are
-     auto-populated by NextAuth).
-   - Application type: **Web application**.
-   - Name: anything (e.g., "AILK dev").
-   - **Authorized redirect URIs** — add exactly:
-     `http://localhost:3000/api/auth/callback/google`
-   - Click **Create**. Copy the **Client ID** and **Client secret**
-     from the dialog.
-2. Wait for the consumer to paste both values.
-3. Write to `.env.local`:
-   ```
-   GOOGLE_CLIENT_ID=...
-   GOOGLE_CLIENT_SECRET=...
-   ```
-
-#### GitHub OAuth sub-flow
-
-1. Tell the consumer the steps in chat AND queue the same content for
-   the runbook. Steps:
-   - Go to <https://github.com/settings/developers>.
-   - Click **New OAuth App**.
-   - Application name: anything (e.g., "AILK dev").
-   - Homepage URL: `http://localhost:3000`
-   - **Authorization callback URL** — add exactly:
-     `http://localhost:3000/api/auth/callback/github`
-   - Click **Register application**. Generate a new client secret.
-     Copy the **Client ID** and **Client secret**.
-2. Wait for the consumer to paste both values.
-3. Write to `.env.local`:
-   ```
-   GITHUB_CLIENT_ID=...
-   GITHUB_CLIENT_SECRET=...
-   ```
-
-### Step 3 — Write the RUNBOOK
-
-After all picked providers are activated, write
-`RUNBOOK.md` (or merge into existing) at the consumer's repo root.
-The runbook captures the OAuth-app-creation steps and Resend setup
-the consumer just walked through, so they can hand it to a teammate
-or refer back later.
-
-Use `references/oauth-app-setup.md` as the template. Replace
-`<provider>` headings as appropriate, and only include sections for
-providers actually activated this session. If `RUNBOOK.md` already
-exists with sections for already-activated providers, do not
-duplicate — add only the new sections beneath any existing content.
-
-### Step 4 — Detect the database adapter mode
-
-Before printing the closing summary, check the consumer's setup:
-
-- If `package.json` lists `@working-theory/database` as a dependency AND
-  `database/prisma/schema.prisma` defines `User` and `Session` models
-  → **Prisma adapter mode**. Sessions persist across server restarts.
-- Otherwise → **JWT-only mode**. Sessions are cookies, no database.
-
-State the mode in the closing summary so the consumer is never
-surprised:
-
-> "Your site is running in **Prisma adapter mode** — sessions persist
-> in the `User` and `Session` tables. Run `pnpm db:push` after this
-> skill if you haven't applied the migration yet."
-
-or
-
-> "Your site is running in **JWT-only mode** — sessions are
-> cookie-only and don't require a database. To switch to persistent
-> sessions, install `@working-theory/database` and add the `User` / `Session`
-> models from `database/prisma/schema.prisma`."
-
-### Step 5 — Closing summary
-
-Print:
-
-- Which providers are now active (subset picked this session +
-  already-activated providers).
-- The database adapter mode (Prisma or JWT).
-- A reminder to set `AILK_AUTH_REQUIRED=1` in `.env.local` if they
-  want protected routes (default is auth-disabled / public).
-- A pointer to `RUNBOOK.md` for future reference.
-- A pointer to `setup-deploy` for production callback URL
-  setup when the consumer is ready to deploy.
-
-## Re-invocation
-
-The skill is idempotent. On a second run, the menu in Step 1 marks
-already-activated providers with `[x]` (read from `.env.local`), and
-the per-provider sub-flows skip those and only run for the new ones.
-The closing summary lists everything, not just what changed this
-session.
-
-If the consumer wants to _change_ a previously-activated provider's
-secrets (e.g., rotated their Google Client Secret), they should pick
-that provider in the menu and the sub-flow will overwrite the
-existing values in `.env.local`. Confirm before overwriting.
-
-## Customization preservation
-
-If `auth.config.ts` has been modified by the consumer to add a
-third-party provider (e.g., Apple), this skill leaves that file
-completely untouched. The skill never reads, edits, or even opens
-`auth.config.ts`. Activation of the AILK locked set happens entirely
-through env vars — `getActiveProviderIds()` in
-`apps/web/lib/auth-env.ts` is what reads them at startup.
-
-## What "activation" means under the hood
-
-- **Provider list is computed at startup from env-var presence** in
-  `apps/web/auth.config.ts` → `buildProviders()`.
-- A provider is included only when every required env var is set:
-  - `email` (magic-link): `AUTH_EMAIL_SERVER` + `AUTH_EMAIL_FROM`
-  - `google`: `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET`
-  - `github`: `GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET`
-- A site with zero auth env vars boots cleanly with no active
-  providers (`apps/web/lib/auth-env.ts` returns an empty array).
-
-This means the skill's job is purely env-var wiring + documentation.
-
-## References
-
-- `references/oauth-app-setup.md` — RUNBOOK template the skill instantiates per session.
-- `references/env-vars.md` — env-var contract (which vars activate which provider).
-
-## Coordination
-
-- **`add-page`** — `/login` or `/account` pages. This skill
-  emits no pages.
-- **`setup-deploy`** — production callback URL setup. v1
-  is dev-only.
-- **`@working-theory/database`** — Prisma adapter detection. Install
-  `@working-theory/database` separately to upgrade from JWT-only to persistent
-  sessions.

package/templates/.claude/skills/add-auth/references/env-vars.md

@@ -1,98 +0,0 @@
-# Auth Env-Var Contract
-
-Source of truth for which env vars activate which auth provider on
-an AILK consumer site. Read by the `add-auth` skill before
-asking the consumer to paste secrets.
-
-The activation logic lives in `apps/web/lib/auth-env.ts` →
-`getActiveProviderIds()`. A provider is active **only when every
-required var is set to a non-empty value**. Partial wiring (e.g.,
-`GOOGLE_CLIENT_ID` set but `GOOGLE_CLIENT_SECRET` missing) is treated
-as inactive — `apps/web/auth.ts` never constructs that provider.
-
-The site's auth library is **Better Auth** (`apps/web/auth.ts`,
-`betterAuth({ secret, baseURL, socialProviders, … })`).
-
-## Provider activation table
-
-| Provider ID | Required env vars                            | Source                       |
-| ----------- | -------------------------------------------- | ---------------------------- |
-| `email`     | `AUTH_EMAIL_SERVER` + `AUTH_EMAIL_FROM`      | Email sign-in (Resend)¹      |
-| `google`    | `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET`  | Google OAuth                 |
-| `github`    | `GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET`  | GitHub OAuth                 |
-
-¹ Better Auth core ships no magic-link provider, so `email` is an
-env-presence signal: it switches on the password method
-(`emailAndPassword`) in `apps/web/auth.ts`, not a wired magic link.
-
-## Auxiliary auth env vars
-
-| Var                    | Default | Effect                                                                                |
-| ---------------------- | ------- | ------------------------------------------------------------------------------------- |
-| `AILK_AUTH_REQUIRED`   | unset   | Read by `isAuthRequired()` in `apps/web/lib/auth-env.ts` (`"1"` or `"true"`). Default is auth-disabled / public, so a fresh scaffold boots without requiring any auth wiring. |
-| `BETTER_AUTH_URL`      | unset   | The site's public origin (e.g. `https://your-domain.com`). Better Auth builds OAuth callback URLs on it and it is the one trusted origin; unset, Better Auth derives both from each request. Set it in production. Local dev can leave it unset. |
-| `BETTER_AUTH_SECRET`   | unset   | Signs session cookies and email-verification tokens. **Required in production** — `apps/web/auth.ts` throws when it is unset there, rather than fall back to the development secret published in the source. Generate with `openssl rand -base64 32`. Optional for `next dev`. |
-
-The skill writes none of these auxiliary vars on its own. It mentions
-them in the closing summary so the consumer is aware:
-
-- `AILK_AUTH_REQUIRED` is the consumer's call (skill always defaults
-  to leaving it unset).
-- `BETTER_AUTH_URL` and `BETTER_AUTH_SECRET` are deferred to
-  production-time setup (`setup-deploy`), and a production deploy
-  fails without `BETTER_AUTH_SECRET`.
-
-## Env-var formats — what valid values look like
-
-### `AUTH_EMAIL_SERVER` (email sign-in via Resend)
-
-```
-smtp://resend:<RESEND_API_KEY>@smtp.resend.com:465
-```
-
-The Resend API key starts with `re_`. The literal username is the
-string `resend` (Resend's SMTP convention). Port 465 is implicit-TLS
-SMTP.
-
-### `AUTH_EMAIL_FROM` (email sign-in via Resend)
-
-A verified sender address on the consumer's Resend account. For
-development, `onboarding@resend.dev` works without verification.
-
-### `GOOGLE_CLIENT_ID` / `GITHUB_CLIENT_ID`
-
-Public identifiers issued by Google / GitHub. Typically:
-
-- Google: ends in `.apps.googleusercontent.com`
-- GitHub: 20-character hex string
-
-Either can be safely committed to a public template; production
-secrets stay in `.env.local`.
-
-### `GOOGLE_CLIENT_SECRET` / `GITHUB_CLIENT_SECRET`
-
-Sensitive values. Treat as passwords. Never commit. The skill writes
-these only to `.env.local` (which is in the consumer scaffold's
-`.gitignore` by default).
-
-## Detection of "already activated"
-
-The skill's Step 1 menu marks providers as `[x]` when both required
-vars are set in `.env.local`. The detection is presence-only — the
-skill does not validate that the values actually work (no Google
-API ping, no GitHub API ping, no test SMTP connection). A consumer
-who pasted typos will get a runtime auth error from Better Auth on
-their first sign-in attempt; the fix is to re-run the skill and
-overwrite.
-
-## Where these vars are read
-
-- `apps/web/lib/auth-env.ts` — `getActiveProviderIds()` and
-  `isAuthRequired()`.
-- `apps/web/auth.ts` — `buildSocialProviders()` consumes the
-  active-provider list and builds Better Auth's `socialProviders`
-  from the matching env vars; `resolveSecret()` reads
-  `BETTER_AUTH_SECRET`, and `baseURL` is `BETTER_AUTH_URL`.
-
-The skill never modifies any of those files. All activation is
-env-var-driven.

package/templates/.claude/skills/add-auth/references/oauth-app-setup.md

@@ -1,172 +0,0 @@
-# OAuth + Magic-Link Setup — RUNBOOK Template
-
-The `add-auth` skill writes (or merges into) `RUNBOOK.md` at the
-consumer's repo root using the per-provider sections below. Only the
-sections for providers actually activated this session are emitted.
-
-The skill **substitutes nothing** in these blocks at runtime — they're
-copy-paste ready as-is. The only per-session variation is which
-sections appear in the final runbook.
-
----
-
-## Provider section: magic-link (Resend)
-
-```markdown
-## Auth — magic-link (Resend)
-
-Magic-link sign-in uses Resend as the email provider. Activation is
-keyed off two env vars in `.env.local`:
-
-- `AUTH_EMAIL_SERVER` — `smtp://resend:<API_KEY>@smtp.resend.com:465`
-- `AUTH_EMAIL_FROM` — verified sender address on your Resend account
-
-### One-time setup
-
-1. Sign up at <https://resend.com> (free tier is fine for development).
-2. Create an API key: <https://resend.com/api-keys>. Save it
-   somewhere safe — you'll only see it once.
-3. Use a verified sender. For development, `onboarding@resend.dev` is
-   Resend's shared dev sender and works without verification. For
-   production, verify your own sending domain in the Resend dashboard.
-
-### `.env.local` entries
-
-\`\`\`
-AUTH_EMAIL_SERVER=smtp://resend:re_yourapikeyhere@smtp.resend.com:465
-AUTH_EMAIL_FROM=onboarding@resend.dev
-\`\`\`
-
-### Rotating the API key
-
-If you rotate the Resend API key, update `AUTH_EMAIL_SERVER` in
-`.env.local` and restart the dev server.
-```
-
----
-
-## Provider section: Google OAuth
-
-```markdown
-## Auth — Google OAuth
-
-Google sign-in is activated when both env vars are present in
-`.env.local`:
-
-- `GOOGLE_CLIENT_ID`
-- `GOOGLE_CLIENT_SECRET`
-
-### One-time setup
-
-1. Open <https://console.cloud.google.com/apis/credentials>.
-2. If you haven't yet, configure the OAuth consent screen:
-   - User type: **External** (unless you're inside a Workspace org).
-   - Fill in app name, support email, and developer contact email.
-   - Scopes are requested by Better Auth at runtime — leave the
-     consent screen scope list empty.
-3. Click **Create Credentials → OAuth client ID**.
-4. Application type: **Web application**.
-5. Name: anything (e.g., "AILK dev").
-6. **Authorized redirect URIs** — add exactly:
-   `http://localhost:3000/api/auth/callback/google`
-7. Click **Create**. Copy the Client ID and Client secret from the
-   dialog (you can return to copy them later via the Credentials page).
-
-### `.env.local` entries
-
-\`\`\`
-GOOGLE_CLIENT_ID=...
-GOOGLE_CLIENT_SECRET=...
-\`\`\`
-
-### Production callback URL
-
-The `localhost` callback above is dev-only. For production, you'll
-need to add a second redirect URI to the same OAuth client (or
-create a separate prod client) of the form
-`https://<your-prod-domain>/api/auth/callback/google`. The
-`setup-deploy` skill or your future deploy skill will help you
-wire this when you're ready to ship.
-
-### Rotating the client secret
-
-In the Google Console, find the OAuth client, generate a new secret,
-update `GOOGLE_CLIENT_SECRET` in `.env.local`, and restart the dev
-server. The Client ID stays the same.
-```
-
----
-
-## Provider section: GitHub OAuth
-
-```markdown
-## Auth — GitHub OAuth
-
-GitHub sign-in is activated when both env vars are present in
-`.env.local`:
-
-- `GITHUB_CLIENT_ID`
-- `GITHUB_CLIENT_SECRET`
-
-### One-time setup
-
-1. Open <https://github.com/settings/developers>.
-2. Click **New OAuth App**.
-3. Application name: anything (e.g., "AILK dev").
-4. Homepage URL: `http://localhost:3000`
-5. **Authorization callback URL** — add exactly:
-   `http://localhost:3000/api/auth/callback/github`
-6. Click **Register application**.
-7. On the resulting app page, click **Generate a new client secret**
-   and copy it immediately (GitHub shows it once).
-8. Copy the Client ID from the same page.
-
-### `.env.local` entries
-
-\`\`\`
-GITHUB_CLIENT_ID=...
-GITHUB_CLIENT_SECRET=...
-\`\`\`
-
-### Production callback URL
-
-The `localhost` callback above is dev-only. For production, either
-register a separate OAuth App with a `https://<your-prod-domain>/...`
-callback, or update this app's callback (GitHub allows multiple).
-The `setup-deploy` skill or your future deploy skill will help
-you wire this when you're ready to ship.
-
-### Rotating the client secret
-
-Generate a new client secret on the app's GitHub page, update
-`GITHUB_CLIENT_SECRET` in `.env.local`, and restart the dev server.
-The Client ID stays the same.
-```
-
----
-
-## Closing section (always emitted at the end of the runbook)
-
-```markdown
-## Activation summary
-
-| Provider    | Env vars                                          | Active |
-| ----------- | ------------------------------------------------- | ------ |
-| magic-link  | `AUTH_EMAIL_SERVER` + `AUTH_EMAIL_FROM`           | <fill> |
-| Google      | `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET`       | <fill> |
-| GitHub      | `GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET`       | <fill> |
-
-A provider is **active** when both required env vars are set in
-`.env.local`. The provider list is computed at server startup from env
-vars only (`getActiveProviderIds()` in `apps/web/lib/auth-env.ts`) — there
-are no `apps/web/auth.ts` edits to make.
-
-To require sign-in for protected routes, set in `.env.local`:
-
-\`\`\`
-AILK_AUTH_REQUIRED=1
-\`\`\`
-
-Default (unset or `0`) is auth-disabled / public — useful while
-building.
-```