getaura 0.0.0-stage → 0.1.0

package/templates/skills/database-migrations/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: database-migrations
+description: Use when creating or changing database tables, columns, views, functions or row level security policies in Supabase. Covers migration files, row level security, indexes and testing policies.
+---
+
+# Database migrations
+
+All database changes go through migration files in `supabase/migrations/`, committed to git. Never change the production schema by hand in the Supabase dashboard; the next deploy or a new environment won't have it.
+
+## Creating a migration
+
+1. Run `npx supabase migration new <short_name>` (for example `add_projects_table`). It creates `supabase/migrations/<timestamp>_<short_name>.sql`.
+2. Write the SQL in that file.
+3. Apply it locally with `npx supabase db reset` (rebuilds the local database from all migrations) or `npx supabase migration up`.
+4. Production gets it through `npx supabase db push` or the team's deploy pipeline. Ask the user before pushing to production.
+
+Never edit a migration that has already been applied anywhere else. Write a new migration that makes the change.
+
+## Every table gets row level security
+
+Supabase exposes tables in the `public` schema through its API. Without row level security (RLS), anyone with the public key can read and change every row.
+
+```sql
+create table public.projects (
+  id uuid primary key default gen_random_uuid(),
+  owner_id uuid not null references auth.users (id) on delete cascade,
+  name text not null,
+  created_at timestamptz not null default now()
+);
+
+alter table public.projects enable row level security;
+
+create policy "Owners can read their projects"
+  on public.projects for select to authenticated
+  using ((select auth.uid()) = owner_id);
+
+create policy "Owners can create projects"
+  on public.projects for insert to authenticated
+  with check ((select auth.uid()) = owner_id);
+
+create policy "Owners can update their projects"
+  on public.projects for update to authenticated
+  using ((select auth.uid()) = owner_id)
+  with check ((select auth.uid()) = owner_id);
+
+create policy "Owners can delete their projects"
+  on public.projects for delete to authenticated
+  using ((select auth.uid()) = owner_id);
+
+create index projects_owner_id_idx on public.projects (owner_id);
+```
+
+Rules:
+- `enable row level security` on every new table, in the same migration that creates it.
+- Write explicit policies for each operation you allow. No policy means no access, which is the safe default.
+- Wrap `auth.uid()` as `(select auth.uid())` so Postgres evaluates it once per query, not once per row.
+- Add `to authenticated` (or `to anon` when truly public) so policies don't run for roles they don't apply to.
+- Never use `using (true)` for writes. Use it for reads only when the data is meant to be public, and say so in a comment.
+- Don't base policies on `user_metadata` in the JWT; users can change it.
+
+## Indexes
+
+Add an index on every foreign key column and every column used in a policy (`owner_id`, `team_id`, `user_id`). Missing indexes make RLS slow as data grows.
+
+## Views and functions
+
+- Create views with `with (security_invoker = true)` so they respect RLS.
+- `security definer` functions bypass RLS. Avoid them unless needed; if you use one, set `set search_path = ''`, use fully qualified names, and keep it out of the exposed `public` schema when possible.
+
+## Keys
+
+The service role key (`service_role` JWT or `sb_secret_...`) bypasses RLS. Use it only in server code, never in client components or `NEXT_PUBLIC_` variables. The browser uses the publishable or anon key, and RLS protects the data.
+
+## Storage
+
+Storage buckets need policies too, on `storage.objects`. Scope them by bucket and by the owner's folder, for example `(storage.foldername(name))[1] = (select auth.uid())::text`.
+
+## Testing policies
+
+After changing policies, check them:
+- With pgTAP tests in `supabase/tests/` run by `npx supabase test db`, or
+- In the local SQL editor, impersonating a user:
+
+```sql
+begin;
+set local role authenticated;
+set local request.jwt.claims = '{"sub": "<some user uuid>"}';
+select * from public.projects; -- should only return that user's rows
+rollback;
+```
+
+Test that a user can't read or change another user's rows, and that signed-out users get nothing.

package/templates/skills/docs-and-readme/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: docs-and-readme
+description: Use when a change affects how the app behaves, is set up, configured or deployed (new feature, new env var, new integration, new command), or when the work seems to contradict the product brief. Keeps README.md, docs/ and .aura/brief.md accurate.
+---
+
+# Docs and README
+
+Docs are how the user, future teammates and future coding agent sessions understand the project without reading all the code. Out-of-date docs are worse than none.
+
+## What to update
+
+| You changed… | Update |
+| --- | --- |
+| Setup steps, scripts or prerequisites | `README.md` → Getting started and Commands |
+| Added or renamed an environment variable | `.env.example` and `README.md` → Environment variables |
+| Added a service or integration (Stripe, email, AI) | `docs/index.md` → Integrations, plus a short note in `docs/` if setup is involved |
+| Data model or how parts fit together | `docs/index.md` → Architecture notes |
+| Where code lives | `docs/index.md` → Where things live |
+| Deployment or migrations process | `README.md` → Deployment |
+| User-visible behaviour | `README.md` → What it does, if the summary changed |
+
+Update docs in the same change as the code, not in a follow-up.
+
+## docs/index.md
+
+This is the first file a coding agent reads. Keep it short: links and one-line facts, not essays. When you learn something about the codebase that would have saved you time (a non-obvious convention, where a key piece of logic lives, a gotcha), add one line to it.
+
+## The product brief
+
+`.aura/brief.md` is the source of truth for what the product is, who it's for and what it does. Read it before planning a feature.
+
+If the work you're asked to do contradicts the brief (a new audience, a different pricing model, a feature the brief rules out), stop and ask the user before continuing. If they confirm, update the brief in the same change. Never update the brief silently.
+
+## Writing style
+
+- Plain language. The reader may be non-technical.
+- Short sentences, active voice, sentence case headings.
+- Exact commands in code blocks, using the project's package manager.
+- Never include real secrets, keys, passwords or personal data, even as examples. Use placeholders like `sk_test_...`.
+- Delete docs that no longer apply rather than leaving them stale.

package/templates/skills/error-handling/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: error-handling
+description: Use when building pages, forms, data fetching, route handlers or server actions, or when something can fail (network, database, payments, AI calls). Covers user-facing error, loading and empty states and safe server-side logging.
+---
+
+# Error handling
+
+Things fail: networks drop, APIs time out, users submit bad data. The app should tell the user what happened in plain words, let them recover, and keep the details in the server logs.
+
+## Every screen has four states
+
+For every page or component that loads data, handle:
+1. **Loading**: a skeleton or spinner.
+2. **Empty**: a helpful message and the next action ("No projects yet. Create your first one.").
+3. **Error**: a plain message and a way to retry.
+4. **Success**: the data.
+
+## Next.js special files
+
+Add these per route segment where it makes sense, at least at the app root:
+
+- `app/loading.tsx`: shown while the segment loads.
+- `app/error.tsx`: catches errors in the segment. Must be a client component.
+- `app/not-found.tsx`: shown when `notFound()` is called or no route matches.
+- `app/global-error.tsx`: catches errors in the root layout. Must render its own `<html>` and `<body>`.
+
+```tsx
+"use client";
+
+export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
+  return (
+    <div role="alert">
+      <h2>Something went wrong</h2>
+      <p>Please try again. If it keeps happening, contact support.</p>
+      <button onClick={() => reset()}>Try again</button>
+    </div>
+  );
+}
+```
+
+Call `notFound()` from `next/navigation` when a record doesn't exist or the user can't see it.
+
+## Never leak internals
+
+- Don't show stack traces, SQL errors, raw API error messages, file paths or IDs of other users to the user.
+- Route handlers return a generic message and the right status code: 400 invalid input, 401 not signed in, 403 not allowed, 404 not found, 429 rate limited, 500 anything else.
+- Never return `error.message` from a database or third-party call to the client.
+
+## Server actions and forms
+
+Return expected errors as values instead of throwing, so the form can show them:
+
+```ts
+"use server";
+
+export async function createProject(_prev: unknown, formData: FormData) {
+  // check the user and validate input first (see the secure-api-routes skill)
+  const { error } = await saveProject(formData);
+  if (error) {
+    console.error("createProject failed", error);
+    return { ok: false, message: "Could not save the project. Please try again." };
+  }
+  return { ok: true, message: "Project created." };
+}
+```
+
+Show `message` with `useActionState`. Show field-level validation messages next to the fields. Disable the submit button while pending.
+
+## Logging
+
+- Log unexpected errors on the server with `console.error("what failed", error)`. On Vercel they appear in the project's Logs.
+- Include context (which action, which record id), never secrets, passwords, tokens or full card or personal data.
+- If the project uses an error tracker such as Sentry, use it instead of only `console.error`.
+
+## External calls
+
+- Wrap calls to Stripe, AI APIs, email providers and other services in `try`/`catch`.
+- Set a timeout on slow calls (`AbortSignal.timeout(10_000)` with `fetch`).
+- For payments and emails, make retries safe (Stripe idempotency keys, check before sending twice).

package/templates/skills/folder-structure/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: folder-structure
+description: Use when creating a new file or folder, deciding where code belongs, or when the user asks to tidy or reorganize the project. Describes the target layout for a Next.js App Router and Supabase project.
+---
+
+# Folder structure
+
+A predictable layout means the user and every agent session can find things without searching the whole repo.
+
+## Target layout
+
+Projects use either the root layout or the `src/` layout. Check which one exists and stay with it. In the `src/` layout, everything below except `supabase/`, `e2e/`, `docs/` and `public/` lives inside `src/`.
+
+```
+app/                  Routes only: page.tsx, layout.tsx, route.ts, loading.tsx, error.tsx
+  (marketing)/        Route groups to organize routes without changing URLs
+  api/                Route handlers
+components/
+  ui/                 Generic building blocks (button, input, dialog)
+  <feature>/          Components for one feature (billing/, projects/)
+lib/
+  supabase/           Supabase clients: client.ts (browser), server.ts (server), admin.ts (secret key, server only)
+  <feature>.ts        Business logic, data access, integrations (stripe.ts, email.ts)
+hooks/                React hooks (use-*.ts)
+types/                Shared TypeScript types
+supabase/
+  migrations/         Database migrations
+  tests/              Database policy tests
+e2e/                  Playwright end-to-end tests
+docs/                 Project docs, starting with docs/index.md
+public/               Static files served as-is
+```
+
+Unit tests sit next to the file they test (`lib/pricing.test.ts`) or in `tests/`. Follow whichever the repo already uses.
+
+## Rules for new code
+
+- `app/` holds routes. Keep page files thin: fetch data and render components. Put logic in `lib/` and UI in `components/`.
+- Code that uses secrets or the Supabase admin client lives in `lib/` and starts with `import "server-only";`.
+- Client components (`"use client"`) go in `components/`, not `lib/`.
+- One component per file. Name files in kebab-case (`project-card.tsx`) unless the repo already uses another convention.
+- Use the `@/` import alias instead of long relative paths (`../../../`).
+- If a file grows past about 300 lines, split it by responsibility.
+- Before creating a helper, search for an existing one. Don't create a second `utils` that does the same thing.
+
+## Moving existing files
+
+- Don't reorganize many files at once. Move a few related files per change, update imports, and run typecheck, lint and tests.
+- Never move files in `app/` without checking the URL won't change. Moving a page folder changes its URL.
+- Don't move or rename migrations in `supabase/migrations/`.
+- If the user asks for a big reorganization, propose a plan in small steps first.

package/templates/skills/pre-launch-checklist/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: pre-launch-checklist
+description: Use when the user is about to launch, go live, accept real payments, invite real users or share the app publicly. Walks through security, data, configuration and ownership checks before launch.
+---
+
+# Pre-launch checklist
+
+Work through this list with the user. Run what you can yourself, and ask the user to confirm the dashboard items. Report the result as a short list: done, needs action, not applicable.
+
+## 1. Aura scan
+
+- Run `aura scan --json`. Resolve every critical and high finding before launch (`aura next --json` shows how).
+- Explain any medium findings the user decides to leave, so it's a conscious choice.
+
+## 2. Tests and build
+
+- The test suite, lint, typecheck and production build all pass locally and in CI.
+- The core flows (sign up, sign in, the main action, payment) have tests or have been checked by hand on a preview deployment.
+
+## 3. Data security
+
+- Row level security is enabled on every table in the `public` schema, with explicit policies. In Supabase: Database → Tables shows an "RLS disabled" warning on any table without it. Supabase's Security Advisor (Advisors → Security Advisor) lists issues too.
+- Every route handler and server action checks the user (see the secure-api-routes skill).
+- Storage buckets have policies, and only intentionally public buckets are public.
+
+## 4. Secrets and environment
+
+- No secrets in the repo (the Aura scan checks this). Any secret that was ever committed has been rotated.
+- Every variable in `.env.example` is set in Vercel for Production: Project → Settings → Environment Variables.
+- Production uses live keys where needed (Stripe `sk_live_` and a live webhook endpoint pointing at the production domain), and nothing secret is in a `NEXT_PUBLIC_` variable.
+
+## 5. Auth and email settings
+
+- Supabase: Authentication → URL Configuration has the production Site URL and redirect URLs.
+- Supabase's built-in email sender has low limits and is meant for testing. Set up custom SMTP (Authentication → Emails → SMTP Settings) with a provider such as Resend before real users sign up.
+
+## 6. User experience
+
+- Every page has loading, empty and error states, and there is a custom 404 page (see the error-handling skill).
+- No stack traces or raw error messages are shown to users.
+
+## 7. Legal pages
+
+Check that a privacy policy and terms of service page exist and are linked in the footer. If the app uses non-essential cookies or serves the EU or UK, check for a cookie notice. Flag what's missing; don't write legal text or give legal advice. Suggest the user gets proper legal input.
+
+## 8. Backups
+
+- Supabase daily backups are included on paid plans (Database → Backups). Free projects have no downloadable backups and pause after a week of inactivity. If the app holds real user data, recommend a paid plan, and point-in-time recovery for important data.
+- Confirm the user knows how to restore.
+
+## 9. Ownership
+
+- Run `aura inventory` with the user so every service, domain and account has a recorded owner.
+- Accounts (GitHub, Vercel, Supabase, Stripe, domain registrar) should be owned by a company account or organization with two-factor authentication, not one person's personal login. `aura guide transfer-ownership` explains how.
+- Run `aura guide github-security` if branch protection and secret scanning aren't on yet.
+
+## 10. After launch
+
+- Watch Vercel logs and error tracking for the first days.
+- Run `aura scan` after each significant change.

package/templates/skills/secrets-and-env/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: secrets-and-env
+description: Use when adding an API key, password, token or any configuration value, adding a new integration, or when a secret may have been exposed. Covers environment variables, NEXT_PUBLIC_ rules, .env.example and what to do after a leak.
+---
+
+# Secrets and environment variables
+
+## Never hardcode secrets
+
+API keys, passwords, tokens, webhook secrets and connection strings never go in source code, tests, docs, comments or commit messages. Read them from `process.env`:
+
+```ts
+const apiKey = process.env.OPENAI_API_KEY;
+if (!apiKey) throw new Error("OPENAI_API_KEY is not set");
+```
+
+Read secrets only in server code (route handlers, server actions, server components, `lib/` server modules). Add `import "server-only";` at the top of modules that read secrets so they can never be bundled into the browser.
+
+## NEXT_PUBLIC_ variables
+
+Next.js copies every variable that starts with `NEXT_PUBLIC_` into the JavaScript sent to browsers. Anyone can read them.
+
+- Only values that are safe to publish go in `NEXT_PUBLIC_`: the Supabase URL, the Supabase publishable or anon key, the Stripe publishable key (`pk_...`), analytics IDs.
+- Never put a secret in a `NEXT_PUBLIC_` variable: no `sk_`, `sb_secret_`, `service_role`, `whsec_`, AI provider keys or database URLs.
+- Never rename a secret to add `NEXT_PUBLIC_` to make an error go away. Move the code that needs it to the server instead.
+
+## When you add a variable
+
+1. Use it through `process.env.NAME` in server code.
+2. Add it to `.env.example` with a comment and no value:
+   ```bash
+   # Resend API key for transactional email. Server only. https://resend.com/api-keys
+   RESEND_API_KEY=
+   ```
+3. Tell the user to add the real value to their local `.env.local`.
+4. Tell the user to add it in Vercel: Project → Settings → Environment Variables, for Production and Preview (mark secrets as Sensitive), then redeploy. `vercel env pull .env.local` copies them back to local.
+5. If CI needs it, add it as a GitHub Actions secret.
+
+## Files
+
+- `.env.local` holds real values and is never committed. Check `.gitignore` covers `.env*` and allows `.env.example` (`!.env.example`).
+- `.env.example` is committed and lists every variable the app needs, with no real values.
+
+## If a secret leaks
+
+A secret has leaked if it was committed to git (even if later deleted), pasted in a chat, issue or log, or sent to the browser.
+
+1. Tell the user immediately and plainly which secret and where. Never print the value.
+2. Run `aura guide rotate-<service>-key` (for example `rotate-stripe-key`, `rotate-supabase-key`; `rotate-generic-key` for others) and walk the user through it. Rotating means creating a new key and deleting the old one in the service's dashboard. Only the user can do this.
+3. Remove the secret from the code and read it from `process.env` instead.
+4. Once rotated, the old key is useless, so rewriting git history is optional. Don't rewrite history or force-push without the user's agreement.
+5. Run `aura scan` to confirm.

package/templates/skills/secure-api-routes/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: secure-api-routes
+description: Use when creating or changing a route handler (app/**/route.ts), a server action ("use server"), proxy.ts or middleware.ts, or a webhook endpoint. Covers authentication, permissions, input validation, webhook signatures and rate limiting.
+---
+
+# Secure API routes
+
+Every route handler and server action is a public URL that anyone on the internet can call directly, with any input. Assume they will.
+
+## Checklist for every route handler and server action
+
+1. **Who is calling?** Check the user on the server, inside the handler or action.
+2. **Are they allowed?** Check they own or have access to the specific record.
+3. **Is the input valid?** Validate with zod before using it.
+4. **What do you return?** Only the fields the caller needs. Generic error messages.
+
+## Authentication with Supabase
+
+Use the server client from `lib/supabase/server` and check the user with `getUser()` (or `getClaims()`, which verifies the token's signature). Never use `getSession()` for auth decisions on the server: it reads the cookie without verifying it.
+
+```ts
+import { z } from "zod";
+import { createClient } from "@/lib/supabase/server";
+
+const Body = z.object({ name: z.string().min(1).max(100) });
+
+export async function POST(request: Request) {
+  const supabase = await createClient();
+  const { data: { user } } = await supabase.auth.getUser();
+  if (!user) return Response.json({ error: "Not signed in" }, { status: 401 });
+
+  const parsed = Body.safeParse(await request.json().catch(() => null));
+  if (!parsed.success) return Response.json({ error: "Invalid input" }, { status: 400 });
+
+  const { data, error } = await supabase
+    .from("projects")
+    .insert({ name: parsed.data.name, owner_id: user.id })
+    .select("id, name")
+    .single();
+  if (error) {
+    console.error("Create project failed", error);
+    return Response.json({ error: "Could not create project" }, { status: 500 });
+  }
+  return Response.json(data, { status: 201 });
+}
+```
+
+Server actions follow the same pattern: get the user first, validate the arguments, then act.
+
+## Authorization by ownership
+
+- Never trust an `id` or `userId` sent by the client to decide who someone is. Use `user.id` from the server.
+- When reading or changing a record, filter by owner (`.eq("owner_id", user.id)`) and rely on row level security as a second layer. If no row matches, return 404.
+- Admin-only actions check a role stored on the server (a table or `app_metadata`), never a value from the request. Never use `user_metadata` for roles: users can edit it.
+- Use the service role or secret key only in server code, only when RLS can't express the rule, and do the permission check yourself first.
+
+## proxy.ts and middleware.ts
+
+Next.js 16 renamed `middleware.ts` to `proxy.ts`. Use it to refresh the Supabase session and redirect signed-out users, but don't rely on it as the only check. Always check auth again in the route handler, server action or data access function.
+
+## Webhooks
+
+Verify the signature before doing anything. For Stripe, read the raw body:
+
+```ts
+const body = await request.text();
+const signature = request.headers.get("stripe-signature");
+if (!signature) return new Response("Missing signature", { status: 400 });
+let event;
+try {
+  event = stripe.webhooks.constructEvent(body, signature, process.env.STRIPE_WEBHOOK_SECRET!);
+} catch {
+  return new Response("Invalid signature", { status: 400 });
+}
+```
+
+Handle each event idempotently (store `event.id` and skip duplicates); providers retry.
+
+## Rate limiting
+
+Rate-limit routes that send email or SMS, check passwords or codes, call paid AI APIs, or create accounts. Use a Vercel Firewall rate limit rule or a library such as `@upstash/ratelimit`. Key the limit on user id when signed in, IP otherwise.
+
+## Intentionally public routes
+
+Some routes are meant to be public (health checks, public pages' data, webhooks that verify a signature). Mark them on the line above the handler so Aura knows it's deliberate:
+
+```ts
+// aura-ignore: public — health check used by uptime monitoring, returns no data
+export async function GET() { ... }
+```
+
+Only add this when the route is truly public and returns nothing private. If unsure, ask the user.

package/templates/skills/writing-tests/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: writing-tests
+description: Use when adding or changing a feature, fixing a bug, or before saying a task is done. Covers writing Vitest unit tests, testing Next.js route handlers and server actions, and when to use Playwright.
+---
+
+# Writing tests
+
+Every new feature and every bug fix gets a test. Tests are how the user knows their app still works after the next change.
+
+## Rules
+
+- Add tests in the same change as the feature, not later.
+- For a bug fix, first write a test that fails because of the bug, then fix it.
+- Run the full test suite before saying you're done. If tests fail, fix them. Never delete or skip a failing test to make the suite pass unless the user agrees.
+- Test behaviour (inputs and outputs), not implementation details.
+- No real network calls, real payments or production databases in unit tests. Mock them.
+
+## Where tests go
+
+Follow the existing pattern in the repo. If there is none, put the test next to the file it tests: `lib/pricing.ts` → `lib/pricing.test.ts`. End-to-end tests go in `e2e/`.
+
+## Unit tests with Vitest
+
+```ts
+import { describe, expect, it } from "vitest";
+import { calculateTotal } from "@/lib/pricing";
+
+describe("calculateTotal", () => {
+  it("applies the discount", () => {
+    expect(calculateTotal(1000, { percentOff: 10 })).toBe(900);
+  });
+
+  it("never goes below zero", () => {
+    expect(calculateTotal(500, { amountOff: 800 })).toBe(0);
+  });
+});
+```
+
+Cover the normal case, edge cases (empty, zero, very large) and the failure case.
+
+Files that import `server-only` throw in tests. Add `vi.mock("server-only", () => ({}));` at the top of the test file.
+
+## Route handlers
+
+Import the handler and call it with a real `Request`:
+
+```ts
+import { POST } from "@/app/api/projects/route";
+
+it("rejects requests without a signed-in user", async () => {
+  const res = await POST(new Request("http://localhost/api/projects", {
+    method: "POST",
+    body: JSON.stringify({ name: "Test" }),
+  }));
+  expect(res.status).toBe(401);
+});
+```
+
+Mock the Supabase client module (`vi.mock("@/lib/supabase/server", ...)`) to control who is signed in. Always test the unauthenticated case, the wrong-user case and invalid input.
+
+## Server actions
+
+Keep the logic in a plain function in `lib/` and have the action call it. Test the plain function directly. Test the action itself for auth and validation the same way as a route handler.
+
+## Components
+
+Vitest can test client components with React Testing Library. Add `// @vitest-environment jsdom` at the top of the file (needs `jsdom`, `@testing-library/react` and `@vitejs/plugin-react` installed). Async server components can't be unit tested; cover them with an end-to-end test.
+
+## End-to-end with Playwright
+
+Use Playwright for the few flows that must never break: sign up, sign in, the core action, checkout. Keep them few and stable. Put them in `e2e/` so Vitest doesn't pick them up.
+
+## Before you finish
+
+1. Run the test script (see the commands in the project rules file).
+2. Run lint and typecheck.
+3. Tell the user which tests you added and that they pass.