getaura 0.1.10 → 0.3.0

package/templates/pr/add-error-pages.md

@@ -0,0 +1,23 @@
+## What this does
+
+Adds the pages Next.js shows when something goes wrong, so visitors get a friendly message instead of a blank or broken screen:
+
+{{details}}
+
+They use plain words, a "Try again" button where it helps, and never show technical details such as error messages or stack traces. Existing files are left untouched.
+
+## Why it matters
+
+Things break sometimes: a database is slow, a service is down, a link is old. A clear message and a way back keep visitors' trust instead of making the app look broken.
+
+Pages that wait for data also need a loading state, so visitors can see the app is working. Those need design choices, so they aren't in this pull request: run `aura fix add-loading-states` to have your coding agent add them.
+
+## What to check before merging
+
+- [ ] Open the preview deployment and visit an address that doesn't exist, such as `/this-page-does-not-exist`. You see the "Page not found" page with a link home.
+- [ ] The wording and look fit your app. Edit the new files in this pull request if not.
+- [ ] If your app supports several languages, move the new text into your translation files.
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/pr/protect-agent-secrets.md

@@ -0,0 +1,18 @@
+## What this does
+
+Adds rules to your coding agent's settings so it can't open your `.env` files, where your keys and passwords live. It only adds rules: nothing you already set is removed or changed.
+
+{{details}}
+
+## Why it matters
+
+Coding agents read files to do their work. A key your agent reads can end up in a chat log, a pull request or a commit, and then it has to be replaced everywhere it's used.
+
+## What to check before merging
+
+- [ ] Your agent never needs to read your real `.env` files. It can still read and update `.env.example`.
+- [ ] Read anything under "For you to decide" and change it yourself if you didn't mean to allow it.
+
+---
+
+Opened by [Aura](https://github.com/JohnFazio1/aura) · {{aura_version}}

package/templates/rules/agent-rules.md

@@ -26,8 +26,13 @@ These apply to every change.
 6. **Small, focused changes**: one concern per change. Don't refactor unrelated code or move many files at once.
 7. **Docs**: update README.md and `docs/index.md` when behaviour, setup or env vars change.
 8. **Errors**: handle failures with plain user-facing messages; never show stack traces or raw errors to users.
-9. **Check your work**: run `aura scan` before finishing a big change and fix anything new it reports. Never disable or work around an Aura check without the user's agreement.
+9. **Check your work**: run `aura check` before finishing a big change and fix anything new it reports. Never disable or work around an Aura check without the user's agreement.
 10. **Plain language**: the user may be non-technical. Explain what you did and why in plain words, and say clearly when they need to do something themselves (dashboards, keys, payments).
+11. **GitHub Actions**: pin third-party actions to a full commit SHA (keep the tag as a comment), give every workflow a `permissions:` block (start from `contents: read`), and pass issue or pull request text to scripts through `env:`, never straight into `run:`.
+12. **Naming**: name new files to match the style already used in their folder (for example PascalCase for components), and name React components in PascalCase.
+13. **Colours from the theme**: use the theme's colour tokens (Tailwind classes like `bg-primary`, or `var(--token)`) instead of typing colour values into components. Add a new token when none matches, with a dark-mode value if the app has dark mode.
+14. **Logging**: never log secrets, tokens, request bodies or whole user objects, and don't leave `console.log` in code that runs in the browser.
+15. **Accessibility**: every image has alt text (empty for decorative ones), every form field has a label, and anything clickable is a button or link.
 
 ## Working efficiently
 

package/templates/skills/aura/SKILL.md

@@ -9,6 +9,8 @@ Aura is a CLI that scores this repo on security, agent setup, foundations and st
 
 Run `aura <command>`. If `aura` is not on the PATH, run `npx getaura <command>` instead.
 
+If a command ends with "Aura X is available", run `aura update --yes` before continuing, then tell the user Aura was updated. Aura needs the user's pilot key. If a command says so, run `aura login` and ask the user to open the link it prints and paste their key there. Never ask for the key in chat.
+
 ## When to use it
 
 - "Check my Aura score", "how healthy is my code", "is this safe to launch"
@@ -21,22 +23,29 @@ Always use the non-interactive flags below so nothing waits for input.
 
 | Goal | Command |
 | --- | --- |
-| Score and findings | `aura scan --json` (add `--fast` for a quick check without type checking, linting and dead-code analysis) |
+| Score and findings | `aura check --json` (add `--fast` for a quick check without type checking, linting and dead-code analysis) |
 | Recommended next steps | `aura next --json` |
 | Apply a template change as a PR | `aura apply <action> --yes` |
 | Let Aura's agent fix something | `aura fix <finding id or action> --yes` |
 | Get a task file for you to complete | `aura fix <finding id or action> --agent` |
+| Continue a large change the user approved | add `--approved` to the same `aura fix` or `aura apply` command |
 | Step-by-step guide for the user | `aura guide <topic>` (list topics with `aura guide --list`) |
 | Services, env vars and owners | `aura inventory --json` |
+| What kind of project Aura thinks each folder is | `aura config kind` |
+| Correct it, after the user confirms | `aura config kind <kind> [folder]` (kinds: web-app, website, api, mobile-app, desktop-app, extension, cli, library; `auto` undoes it) |
 | Score trend | `aura history` |
+| Update Aura to the newest version | `aura update --yes` |
 
 ## Reading the JSON
 
-`aura scan --json` returns:
-- `score` (0–100) and `cappedBy` when a critical finding capped the score.
+`aura check --json` returns:
+- `score` (0–100) and `cappedBy` when a critical finding capped the score. The score comes from Aura's server: `score` is `null` when it couldn't be reached, and `scoreProblem` says why. Tell the user and never guess a score; the findings are still there. `scoreSource` is `cache` when Aura reused its last score for the same code.
 - `categories[]`: `category`, `score`.
 - `checks[]`: `checkId`, `title`, `status`, `summary` and `findings[]`.
 - Each finding: `id`, `severity` (critical, high, medium, low, info), `title`, `detail`, `why`, optional `explanation`, `locations[]` (`file`, `line`) and optional `actionId`.
+- In a monorepo, findings from one project start with its folder (`apps/web: …`) and have `meta.project`.
+- `profile.projects[]`: what Aura scored each project as: `path`, `kind`, `traits`, `tools` and `confidence` (`low` means a best guess; check it with the user).
+- `setup[]`: per project, the jobs it needs done (`capability`) with `status` (`in-place` with the `tool`, or `missing`), `need` (`essential`, `recommended`) and `why`. Advice only, not scored: mention essential gaps, and offer to help pick a tool, but never install a paid service without the user's say-so.
 
 `aura next --json` returns steps in priority order. Each step has `actionId`, `title`, `delivery` (`pr`, `agent-fix`, `guide`, `checklist`), `why`, `impact` (estimated points gained), `effort` and the exact `command` to run.
 
@@ -56,21 +65,22 @@ Always use the non-interactive flags below so nothing waits for input.
    - `agent-fix`: run `aura fix <id> --agent`, then complete the task file yourself (see below), or run `aura fix <id> --yes` if the user prefers Aura's agent.
    - `guide`: run `aura guide <topic>` and walk the user through it. These steps happen in vendor dashboards, so the user does them.
    - `checklist`: run `aura inventory --json`, show the user which services and accounts Aura found, and ask them to run `aura inventory` in their own terminal to record who owns each account.
-3. After any change, run `aura scan --json` again and tell the user the new score.
+3. Large changes (renames and restructures across many files) need the user's approval first. If `aura fix` or `aura apply` stops with exit code 3 and says the change is large, show the user the breakdown it printed (also in `.aura/plans/<id>.md`) in plain words: what will change, why, what won't change, the risk and the chunks. Ask whether to go ahead. Only after they clearly say yes, run the same command again with `--approved`; `--yes` doesn't count as their approval. Each run does one chunk in one pull request. Tell the user how many chunks are left and run it again with `--approved` for the next one when they want to continue.
+4. After any change, run `aura check --json` again and tell the user the new score.
 
 ## Task files
 
-When `.aura/tasks/<id>.md` exists, it is your brief. Follow it exactly:
+When `.aura/tasks/<id>.md` exists, it is your brief. Follow it exactly. If it starts with a breakdown of a large change, show the user that breakdown and get their yes before changing anything, and do only the chunk it names:
 
 1. Create a branch: `git checkout -b aura/<id>`.
 2. Make the change the task describes. Keep it small and focused on that task.
 3. Run the tests, lint and typecheck. Fix anything you broke.
 4. Commit, push and open a PR with `gh pr create`. Write the PR body in plain language: what changed, why it matters, and what the user should check before merging.
-5. Run `aura scan --json` to confirm the finding is gone.
+5. Run `aura check --json` to confirm the finding is gone.
 
 ## Rules
 
-- Never disable, weaken or game a check to raise the score. This includes adding `aura-ignore` comments, editing `.aura/config.json` ignores or deleting tests, unless the user explicitly agrees after you explain the trade-off.
-- Never commit `.aura/report.md`, `.aura/scan.json`, `.aura/history.json` or `.aura/tasks/`. They stay local because they can describe security weaknesses.
+- Never disable, weaken or game a check to raise the score. This includes adding `aura-ignore` comments, editing `.aura/config.json` ignores, changing the kind of project or deleting tests, unless the user explicitly agrees after you explain the trade-off. Change the kind only when the user says Aura got it wrong, never to make a check stop applying.
+- Never commit `.aura/report.md`, `.aura/scan.json`, `.aura/history.json`, `.aura/tasks/` or `.aura/plans/`. They stay local because they can describe security weaknesses.
 - If a finding is a leaked secret, tell the user straight away and run `aura guide rotate-<service>-key`. Removing the secret from the code is not enough; it must be rotated.
 - If you think a finding is wrong, say so and explain why. Don't silently skip it.

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

@@ -70,6 +70,8 @@ Show `message` with `useActionState`. Show field-level validation messages next
 
 - 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.
+- Log ids and messages, not whole objects: `user.id`, not `user`; never request headers, `req.body` or `await request.json()`.
+- Don't leave `console.log` in client components or other browser code: anyone can open the browser console and read it. Keep `console.error` for real errors.
 - If the project uses an error tracker such as Sentry, use it instead of only `console.error`.
 
 ## External calls

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

@@ -38,7 +38,8 @@ Unit tests sit next to the file they test (`lib/pricing.test.ts`) or in `tests/`
 - `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.
+- One component per file. Name new files in the style the other files in their folder already use (for example `ProjectCard.tsx` next to other PascalCase components). Only in a new folder with nothing to match, use kebab-case (`project-card.tsx`).
+- Name React components in PascalCase (`ProjectCard`, never `projectCard`) and hooks `useSomething`. React treats a lowercase tag like `<projectCard />` as plain HTML.
 - 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.

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

@@ -9,7 +9,7 @@ Work through this list with the user. Run what you can yourself, and ask the use
 
 ## 1. Aura scan
 
-- Run `aura scan --json`. Resolve every critical and high finding before launch (`aura next --json` shows how).
+- Run `aura check --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
@@ -57,4 +57,4 @@ Check that a privacy policy and terms of service page exist and are linked in th
 ## 10. After launch
 
 - Watch Vercel logs and error tracking for the first days.
-- Run `aura scan` after each significant change.
+- Run `aura check` after each significant change.

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

@@ -49,4 +49,4 @@ A secret has leaked if it was committed to git (even if later deleted), pasted i
 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.
+5. Run `aura check` to confirm.

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

@@ -74,11 +74,15 @@ try {
 }
 ```
 
+Other providers work the same way: use their official helper (`verifyWebhook` from `@clerk/nextjs/webhooks`, the `svix` `Webhook` class for Resend, `@octokit/webhooks` for GitHub), or an HMAC of the raw body compared with `crypto.timingSafeEqual`. Reading the signature header without checking it protects nothing, and parsing the body with `request.json()` first breaks the check.
+
 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.
+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. For sign-in, code and password-reset routes, key it on the IP plus the email or username being tried, so nobody can guess one account's password from many tries. Sign-in through Supabase Auth, Clerk or Auth0 is already limited by the provider.
+
+AI routes also need a sign-in check and an output limit on every model call (`max_tokens` for OpenAI and Anthropic, `maxOutputTokens` for the AI SDK), and AI keys never go in `NEXT_PUBLIC_` variables or `'use client'` files.
 
 ## Intentionally public routes