create-fedi-app 0.1.0

package/dist/templates/modules/ai-rules/rules/OVERVIEW.md

@@ -0,0 +1,56 @@
+# Project Overview
+
+## What is Fedi?
+
+Fedi is a Bitcoin/Lightning wallet and community app built on the Fedimint protocol (federated eCash). It lets communities hold Bitcoin collectively without a single custodian. Users interact with local "Federations" — groups of guardians who jointly manage funds using threshold cryptography.
+
+Fedi ships a built-in browser (WebView) that hosts Mini Apps — small web apps that get direct access to the user's Lightning wallet and Nostr identity through injected JavaScript APIs.
+
+## What is this project?
+
+**{{PROJECT_NAME}}** is a Fedi Mini App. It runs exclusively inside Fedi's WebView at a URL the user navigates to (or pins as an installed app).
+
+This project was scaffolded with [create-fedi-app](https://github.com/fedi/create-fedi-app).
+
+## Stack
+
+- **Framework:** Next.js 16 App Router (TypeScript)
+- **Styling:** Tailwind CSS v4 with custom design tokens
+- **Fonts:** Bricolage Grotesque (display), DM Sans (body), JetBrains Mono (mono)
+- **Payments:** `@create-fedi-app/webln` — wraps `window.webln`
+- **Identity:** `@create-fedi-app/nostr` — wraps `window.nostr` (NIP-07)
+- **Fedi internals:** `@create-fedi-app/fedi-types` — TypeScript types for all injected APIs
+- **Testing:** Vitest + React Testing Library + Playwright
+
+## Selected modules
+
+{{SELECTED_MODULES}}
+
+## The WebLN/Nostr injection model
+
+Fedi injects two globals into every Mini App's WebView:
+
+| Global | Purpose |
+|--------|---------|
+| `window.webln` | Lightning wallet — send/receive payments |
+| `window.nostr` | Nostr identity — public key, signing (NIP-07) |
+
+**These are never available outside Fedi.** In a regular browser, both are `undefined`. All code must check before using them. See `rules/webln.md` and `rules/nostr.md` for full references.
+
+Fedi also injects `window.fediInternal` (optional, versioned) for app-discovery features. See `rules/fedi-api.md`.
+
+## Key constraints for AI agents
+
+1. **Never install external wallet libraries** (`webln`, `alby`, `lightning-browser-extension`, etc.). Fedi provides the WebLN provider — adding a library creates conflicts.
+2. **Never install NIP-07 browser extension adapters.** `window.nostr` is already there.
+3. **Always guard injected APIs with `typeof window.X !== 'undefined'`** before calling them — SSR and non-Fedi browsers will not have them.
+4. **This is an App Router project** — components that use browser APIs or React hooks must have `'use client'` at the top.
+5. **Do not add `window.webln.enable()` calls** — the `@create-fedi-app/webln` provider handles this automatically.
+
+## Links
+
+- Fedi: https://www.fedi.xyz
+- Fedimint protocol: https://fedimint.org
+- WebLN spec: https://webln.dev
+- NIP-07 (Nostr browser extension): https://github.com/nostr-protocol/nips/blob/master/07.md
+- create-fedi-app docs: `.ai/rules/` (this directory)

package/dist/templates/modules/ai-rules/rules/architecture.md

@@ -0,0 +1,108 @@
+# Architecture Reference
+
+## File structure
+
+```
+{{PROJECT_NAME}}/
+├── app/                        # Next.js App Router
+│   ├── layout.tsx              # Root layout — fonts, providers, dev toolbar
+│   ├── page.tsx                # Home page (client component)
+│   ├── globals.css             # Design tokens + Tailwind theme
+│   └── demo/                  # Demo pages (remove or repurpose)
+│       ├── page.tsx            # Demo index
+│       ├── webln/page.tsx      # WebLN payment demo
+│       └── nostr/page.tsx      # Nostr identity demo
+├── components/
+│   ├── providers.tsx           # WebLNProvider + NostrProvider tree
+│   ├── FediDevToolbar/         # Dev-only mock controls (strips in production)
+│   ├── webln/                  # WebLN UI components
+│   └── nostr/                  # Nostr UI components
+├── hooks/
+│   └── useFediInternal.ts      # window.fediInternal hook
+├── lib/
+│   ├── fedi.ts                 # isInFedi(), getFediInternalVersion(), formatSats(), shortenNpub()
+│   └── utils.ts                # cn() — Tailwind class merging
+├── env.ts                      # Type-safe env vars via @t3-oss/env-nextjs
+├── next.config.ts
+├── tsconfig.json
+├── vitest.config.ts
+└── vitest.setup.ts
+```
+
+## App Router conventions
+
+This project uses Next.js 16 App Router. Key rules:
+
+**Server vs client components**
+
+- All components default to Server Components.
+- Add `'use client'` to any component that: uses hooks (`useState`, `useEffect`, etc.), references browser globals (`window`, `document`, `navigator`), or imports from `@create-fedi-app/webln` / `@create-fedi-app/nostr`.
+- The root layout (`app/layout.tsx`) is a Server Component — it wraps children with `<Providers>` which is a client component.
+
+**Route structure**
+
+- `app/page.tsx` — home (`/`)
+- `app/demo/page.tsx` — demo index (`/demo`)
+- `app/demo/[feature]/page.tsx` — feature demos (`/demo/webln`, `/demo/nostr`)
+- `app/api/[route]/route.ts` — API route handlers
+
+**File colocation**
+
+Components used only by a single route can live adjacent to that route. Shared components belong in `components/`.
+
+## Provider tree
+
+Defined in `components/providers.tsx`:
+
+```tsx
+<WebLNProvider>
+  <NostrProvider>
+    {children}
+  </NostrProvider>
+</WebLNProvider>
+```
+
+Both providers auto-detect `window.webln` / `window.nostr` on mount and make them available via context. The `FediDevToolbar` (dev-only) injects `MockWebLNProvider` and `MockNostrProvider` to simulate Fedi outside the app.
+
+## Module structure
+
+Additional features are added as modules. Each module contributes:
+
+- **`app/demo/[feature]/`** — demo page for the feature
+- **`components/[feature]/`** — reusable UI components
+- **`hooks/`** — business-logic hooks (e.g. `usePaymentFlow`, `useIdentityFlow`)
+- **Module-specific packages** — `@create-fedi-app/webln`, `@create-fedi-app/nostr`
+
+## Where each type of code lives
+
+| What | Where |
+|------|-------|
+| Design tokens | `app/globals.css` |
+| Env variable validation | `env.ts` |
+| Fedi utility functions | `lib/fedi.ts` |
+| Class merging helper | `lib/utils.ts` |
+| Browser API hooks | `hooks/` |
+| Feature UI | `components/[feature]/` |
+| Route pages | `app/` |
+| API handlers | `app/api/[name]/route.ts` |
+| Tests | `__tests__/` adjacent to what they test, or `*.test.ts` colocated |
+
+## Key packages
+
+| Package | Purpose |
+|---------|---------|
+| `@create-fedi-app/webln` | React context + hooks for `window.webln` |
+| `@create-fedi-app/nostr` | React context + hooks for `window.nostr` |
+| `@create-fedi-app/fedi-types` | TypeScript types for all Fedi-injected APIs |
+| `@create-fedi-app/ui` | Shared UI components (added in a later scaffold phase) |
+
+## Environment variables
+
+Validated at build time in `env.ts` using `@t3-oss/env-nextjs`. Add new variables there, not in raw `process.env` calls. Client-side variables must be prefixed `NEXT_PUBLIC_`.
+
+## Routing conventions
+
+- **App Router only** — no Pages Router files.
+- **No `index.tsx` files in `app/`** — use `page.tsx` as required by Next.js.
+- **Parallel routes** (`@slot/`) are not used in the base template — add only if needed.
+- **Loading states** use `loading.tsx` files next to `page.tsx` — not custom suspense boundaries unless needed.

package/dist/templates/modules/ai-rules/rules/design-system.md

@@ -0,0 +1,94 @@
+# Design System Reference
+
+## CSS variables (design tokens)
+
+All tokens are defined in `app/globals.css` inside a `@theme {}` block (Tailwind v4 syntax). Use these variables in inline styles and `var()` calls.
+
+### Colors
+
+```css
+--color-bg: #0A0A0A          /* page background */
+--color-surface: #141414     /* card / panel background */
+--color-surface-2: #1C1C1C   /* elevated surface (tooltips, popovers) */
+--color-border: rgba(255, 255, 255, 0.08)  /* subtle dividers */
+--color-accent: #FF6B35      /* primary action color — Fedi orange */
+--color-accent-dim: rgba(255, 107, 53, 0.15)  /* accent tint for backgrounds */
+--color-text: #F0EEE9        /* primary text */
+--color-text-muted: #8A8880  /* secondary / supporting text */
+--color-text-subtle: #4A4845 /* placeholder, disabled text */
+```
+
+### Typography
+
+```css
+--font-display: 'Bricolage Grotesque', system-ui, sans-serif  /* headings */
+--font-body: 'DM Sans', system-ui, sans-serif                 /* body text */
+--font-mono: 'JetBrains Mono', monospace                      /* code, addresses */
+```
+
+### Border radius
+
+```css
+--radius-sm: 4px    /* small chips, badges */
+--radius-md: 8px    /* buttons, inputs, cards */
+--radius-lg: 12px   /* large cards, modals */
+```
+
+## Using tokens in components
+
+### Inline styles (when Tailwind class doesn't exist)
+
+```tsx
+<div style={{ background: 'var(--color-surface)', borderRadius: 'var(--radius-md)' }}>
+```
+
+### Tailwind arbitrary values
+
+```tsx
+<div className="bg-[var(--color-surface)] rounded-[var(--radius-md)]">
+```
+
+### Tailwind theme integration
+
+The Tailwind theme maps `--color-*` tokens, so you can use shorthand:
+
+```tsx
+<div className="bg-surface text-text-muted border border-border">
+```
+
+## Components from @create-fedi-app/ui
+
+> Note: UI components are added in the next scaffold phase. Check `packages/ui/src/index.ts` for the current export list.
+
+## shadcn/ui conventions
+
+This project uses shadcn/ui naming conventions for any added components:
+
+- Components live in `components/ui/` (shadcn primitives) and `components/` (app-specific)
+- File names are kebab-case: `components/ui/button.tsx`, `components/ui/card.tsx`
+- Exports are named (not default): `export function Button(...)`
+- Compose with `cn()` from `lib/utils.ts` for conditional classes
+
+## Anti-slop rules for AI agents
+
+These rules prevent the most common AI-generated UI mistakes in this codebase. Follow them strictly.
+
+1. **Use design tokens, not hardcoded hex.** Never write `color: '#FF6B35'` — write `color: 'var(--color-accent)'`. Never write `background: '#141414'` — write `background: 'var(--color-surface)'`. The only exception is truly one-off values with no token equivalent.
+
+2. **Never invent new colors.** If a color doesn't exist as a token, use the closest existing token or ask. Do not introduce new hex values, `hsl()`, `rgb()`, or opacity tricks that approximate an existing token.
+
+3. **Respect the radius scale.** Use `--radius-sm`, `--radius-md`, or `--radius-lg`. Do not use arbitrary values like `rounded-2xl`, `rounded-full` on rectangles, or `border-radius: 16px`. Avatars and circular elements may use `rounded-full`.
+
+4. **Never add box shadows.** The design system is shadowless. Do not add `shadow-*` classes or `box-shadow` styles. Use borders with `--color-border` for separation.
+
+5. **Match the font stack.** Headings use `--font-display`. Body copy uses `--font-body` (set on `html`, inherited). Code, addresses, keys, and amounts use `--font-mono`. Do not mix them or introduce new fonts.
+
+6. **Don't add color to text for decoration.** Color communicates state: `--color-accent` means "interactive/active", `--color-text-muted` means "supporting info", `--color-text-subtle` means "disabled/placeholder". Don't use accent color on static descriptive text.
+
+7. **Minimum touch target is 44×44px.** Any interactive element (button, link, toggle) must have at least `min-h-[44px] min-w-[44px]` or equivalent padding. Never make a button that's 24×24.
+
+8. **Loading states must show something.** When `isPaying`, `isLoading`, or `isConnecting` is true, the button/area must visibly change — spinner, opacity reduction, or label change. Never leave the UI frozen without feedback.
+
+9. **Errors must surface to the user.** When `paymentError`, `signError`, or any error state is non-null, show the message. Do not silently swallow errors with empty `catch {}` blocks or conditional rendering that hides the error element.
+
+10. **No placeholder text in production UI.** Don't generate components with "Lorem ipsum", "TODO", "Sample text", or generic copy. Write real copy, or use a `{{PLACEHOLDER}}` template variable that the dev must fill in.

package/dist/templates/modules/ai-rules/rules/fedi-api.md

@@ -0,0 +1,120 @@
+# Fedi Internal API Reference
+
+`window.fediInternal` is an optional, versioned API injected by Fedi for Mini App discovery features. Unlike `window.webln` and `window.nostr`, it may not be present even inside Fedi (older app versions will not have it).
+
+## Version detection
+
+Always check both existence and version before calling methods:
+
+```ts
+import { getFediInternalVersion } from '../lib/fedi';
+
+const version = getFediInternalVersion();
+// → 0 | 1 | 2 | null
+
+if (version === 2) {
+  // v2 methods available
+} else if (version === null) {
+  // not in Fedi, or very old version
+}
+```
+
+The helper in `lib/fedi.ts`:
+
+```ts
+export function getFediInternalVersion(): 0 | 1 | 2 | null {
+  if (typeof window === 'undefined' || !window.fediInternal) return null;
+  return window.fediInternal.version as 0 | 1 | 2;
+}
+```
+
+## TypeScript types
+
+```ts
+type FediInternalV0 = { version: 0 };
+type FediInternalV1 = { version: 1 };
+type FediInternalV2 = {
+  version: 2;
+  getInstalledMiniApps(): Promise<Array<{ url: string }>>;
+  installMiniApp(miniApp: {
+    id: string;
+    title: string;
+    url: string;
+    imageUrl?: string | null;
+    description?: string;
+  }): Promise<void>;
+};
+
+type FediInternal = FediInternalV0 | FediInternalV1 | FediInternalV2;
+```
+
+## v2 API
+
+### getInstalledMiniApps()
+
+```ts
+const apps = await window.fediInternal.getInstalledMiniApps(): Promise<Array<{ url: string }>>
+```
+
+Returns the list of Mini App URLs the current user has installed in Fedi. Useful for detecting if a companion app is installed, or for showing an "install" prompt.
+
+### installMiniApp()
+
+```ts
+await window.fediInternal.installMiniApp({
+  id: string;        // unique identifier, e.g. "com.example.myapp"
+  title: string;     // display name shown in Fedi
+  url: string;       // the Mini App URL
+  imageUrl?: string; // icon URL (optional)
+  description?: string;
+}): Promise<void>
+```
+
+Triggers Fedi's native UI to add a Mini App to the user's home screen. Resolves when the user confirms (or rejects) the install prompt.
+
+## useFediInternal() hook
+
+```ts
+import { useFediInternal } from '../hooks/useFediInternal';
+
+const { isAvailable, version, getInstalledMiniApps, installMiniApp } = useFediInternal();
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `isAvailable` | `boolean` | True if `window.fediInternal` is present |
+| `version` | `0 \| 1 \| 2 \| null` | Detected version |
+| `getInstalledMiniApps` | `V2['getInstalledMiniApps'] \| null` | Null if version < 2 |
+| `installMiniApp` | `V2['installMiniApp'] \| null` | Null if version < 2 |
+
+Non-v2 methods are `null` — always check before calling:
+
+```tsx
+'use client';
+import { useFediInternal } from '../hooks/useFediInternal';
+
+export function InstallPrompt() {
+  const { installMiniApp } = useFediInternal();
+
+  if (!installMiniApp) return null;
+
+  return (
+    <button onClick={() => installMiniApp({
+      id: 'com.example.myapp',
+      title: 'My App',
+      url: 'https://myapp.example.com',
+    })}>
+      Add to Fedi
+    </button>
+  );
+}
+```
+
+## Version history
+
+| Version | Features |
+|---------|----------|
+| `null` | Not in Fedi, or Fedi version predates fediInternal |
+| `0` | Fedi version is aware of the API but exposes nothing |
+| `1` | Reserved |
+| `2` | `getInstalledMiniApps`, `installMiniApp` |

package/dist/templates/modules/ai-rules/rules/nostr.md

@@ -0,0 +1,232 @@
+# Nostr Reference (NIP-07)
+
+Nostr is a decentralized social protocol. Fedi injects `window.nostr` (a NIP-07 provider) into every Mini App's WebView, giving the app access to the user's public key and signing capability without ever exposing the private key.
+
+## How Fedi injects window.nostr
+
+Like `window.webln`, Fedi's native layer injects a NIP-07-compliant `NostrProvider` before the page loads. The private key stays inside the native app — the Mini App only ever receives signed events or the public key.
+
+Outside Fedi, `window.nostr` is `undefined`.
+
+## Detection pattern
+
+```ts
+if (typeof window.nostr !== 'undefined') {
+  const pubkey = await window.nostr.getPublicKey();
+} else {
+  // not in Fedi, or provider not available
+}
+```
+
+Prefer the `@create-fedi-app/nostr` hooks — they handle this for you.
+
+## React hooks (preferred)
+
+### useNostr()
+
+Low-level access to the provider and connection state.
+
+```ts
+import { useNostr } from '@create-fedi-app/nostr';
+
+const { provider, pubkey, npub, isLoading, error, isConnected } = useNostr();
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `provider` | `NostrProvider \| null` | Raw NIP-07 provider |
+| `pubkey` | `string \| null` | Hex-encoded 32-byte public key |
+| `npub` | `string \| null` | bech32-encoded public key (`npub1…`) |
+| `isLoading` | `boolean` | True while provider initialises |
+| `error` | `Error \| null` | Initialisation error |
+| `isConnected` | `boolean` | Shorthand for `provider !== null` |
+
+### useIdentity()
+
+Higher-level hook for the common "connect + sign" flow.
+
+```ts
+import { useIdentity } from '@create-fedi-app/nostr';
+
+const {
+  pubkey,
+  npub,
+  displayNpub,
+  getPublicKey,
+  signEvent,
+  isConnecting,
+} = useIdentity();
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `pubkey` | `string \| null` | Hex public key (null until connected) |
+| `npub` | `string \| null` | bech32 public key |
+| `displayNpub` | `string \| null` | Truncated: `npub1abc…xyz` |
+| `getPublicKey()` | `() => Promise<string \| null>` | Trigger key retrieval |
+| `signEvent(event)` | `(UnsignedNostrEvent) => Promise<NostrEvent \| null>` | Sign a Nostr event |
+| `isConnecting` | `boolean` | True during `signEvent` |
+
+## Full API (window.nostr)
+
+### getPublicKey()
+
+```ts
+const pubkey = await window.nostr.getPublicKey(): Promise<string>
+```
+
+Returns the user's hex-encoded 32-byte Schnorr public key. This is the canonical Nostr identity — a stable, unique identifier per user.
+
+**This does not request funds or sign anything.** Safe to call for login flows.
+
+### signEvent()
+
+```ts
+const signedEvent = await window.nostr.signEvent(event: UnsignedNostrEvent): Promise<NostrEvent>
+
+interface UnsignedNostrEvent {
+  pubkey: string;      // must match the user's pubkey
+  created_at: number;  // Unix timestamp
+  kind: number;        // Nostr event kind
+  tags: string[][];    // array of tag arrays
+  content: string;
+}
+
+interface NostrEvent extends UnsignedNostrEvent {
+  id: string;   // hex-encoded event hash (SHA-256 of canonical serialisation)
+  sig: string;  // hex-encoded Schnorr signature
+}
+```
+
+Common kinds: `0` = profile metadata, `1` = short text note, `4` = encrypted DM.
+
+### getRelays()
+
+```ts
+const relays = await window.nostr.getRelays(): Promise<Record<string, { read: boolean; write: boolean }>>
+```
+
+Returns the user's configured relay list. Example:
+
+```ts
+{
+  'wss://relay.damus.io': { read: true, write: true },
+  'wss://nos.lol': { read: true, write: false },
+}
+```
+
+### nip04 (encrypted DMs)
+
+```ts
+// Encrypt a message to a recipient's pubkey
+const ciphertext = await window.nostr.nip04.encrypt(recipientPubkey: string, plaintext: string): Promise<string>
+
+// Decrypt a message encrypted to your pubkey
+const plaintext = await window.nostr.nip04.decrypt(senderPubkey: string, ciphertext: string): Promise<string>
+```
+
+NIP-04 uses ECDH + AES-256-CBC. The ciphertext format is `<base64>?iv=<base64>`.
+
+## npub format and bech32 encoding
+
+The raw public key is a 32-byte value encoded as 64 hex characters. `npub` is the human-readable bech32 encoding of the same bytes:
+
+```
+hex:  79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798
+npub: npub10279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798
+```
+
+The `@create-fedi-app/nostr` package converts between formats automatically via `@scure/base`.
+
+To display a truncated npub (for avatars, etc.):
+```ts
+const displayNpub = npub.slice(0, 8) + '...' + npub.slice(-4);
+// → "npub1abc...xyz4"
+```
+
+## Nostr as login (no username/password)
+
+Because `getPublicKey()` returns a stable identifier, you can use it as a passwordless login:
+
+1. Get the pubkey — this is the user's "account"
+2. Store any per-user data keyed on `pubkey`
+3. To authenticate a server request, have the user sign a challenge event (kind: 27235, NIP-98)
+
+The user never creates an account — their Fedi identity is their account.
+
+## Common patterns
+
+### Connect on button press (lazy)
+
+```tsx
+'use client';
+import { useIdentity } from '@create-fedi-app/nostr';
+
+export function ConnectButton() {
+  const { pubkey, displayNpub, getPublicKey, isConnecting } = useIdentity();
+
+  if (pubkey) {
+    return <span className="font-mono text-sm">{displayNpub}</span>;
+  }
+
+  return (
+    <button onClick={getPublicKey} disabled={isConnecting}>
+      {isConnecting ? 'Connecting…' : 'Connect with Nostr'}
+    </button>
+  );
+}
+```
+
+### Sign a message to prove identity
+
+```ts
+const event = await signEvent({
+  kind: 1,
+  content: 'Hello from my mini app',
+  tags: [],
+  created_at: Math.floor(Date.now() / 1000),
+});
+
+// event.sig proves the user signed this content
+// event.pubkey is their identity
+// event.id is the canonical hash
+```
+
+## MockNostrProvider (tests)
+
+```ts
+import { MockNostrProvider } from '@create-fedi-app/nostr';
+```
+
+`MockNostrProvider` uses a deterministic test keypair (well-known secp256k1 generator point) and produces real Schnorr signatures via `@noble/curves`.
+
+```ts
+const mock = new MockNostrProvider();
+
+await mock.getPublicKey();
+// → '79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798'
+
+await mock.signEvent({ kind: 1, content: 'test', tags: [], created_at: 0, pubkey: '...' });
+// → fully valid NostrEvent with real id and sig
+
+await mock.getRelays();
+// → { 'wss://relay.damus.io': { read: true, write: true }, ... }
+
+await mock.nip04.encrypt('somePubkey', 'hello');
+// → base64-encoded fake ciphertext
+```
+
+**The test keypair is a well-known vector — NEVER use in production.**
+
+Use in Vitest tests by passing to the `NostrProvider` context:
+
+```tsx
+import { NostrProvider } from '@create-fedi-app/nostr';
+import { MockNostrProvider } from '@create-fedi-app/nostr';
+
+render(
+  <NostrProvider mock={new MockNostrProvider()}>
+    <YourComponent />
+  </NostrProvider>
+);
+```