@claude-code-mastery/starter-kit 1.0.0

package/.claude/skills/terminal-tui/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: tui-builder
+description: Use when building or modifying an interactive terminal UI (TUI), especially with Ink + React on Node, or when hitting terminal-resize rendering bugs — ghost/repeated content, a blank screen after resize, or a divider/layout that won't update width. Carries battle-tested resize rules Claude otherwise gets wrong. Not for plain non-interactive CLIs (flag parsing, scripts) with no full-screen rendering.
+when_to_use: |
+  - Building or modifying an interactive terminal UI (TUI), especially Ink + React on Node
+  - Adding or fixing terminal-resize handling in a TUI
+  - Debugging resize artifacts: ghosted/repeated content, blank screen after resize, stale divider/width
+  - Do NOT use for plain non-interactive CLIs (argument parsing, batch scripts) with no live rendering
+---
+
+# Building Terminal UIs (TUIs)
+
+Battle-tested rules from shipping Ink + React TUIs. The deep stack documented here is Ink/React on Node; the underlying principles — render into the alternate screen, control resize-handler ordering, treat size as state — transfer to other TUI frameworks even when the exact escape codes differ.
+
+The thing to get right, because it's gotten wrong every time, is terminal **resize**. Ink renders by diffing its previous output and repositioning the cursor, not by clearing and redrawing. On resize that model breaks three ways at once:
+
+- content Ink no longer "owns" stays visible
+- the cursor lands at an unknown position, so Ink's positioning math is off
+- a taller terminal re-reveals old lines that were previously offscreen
+
+Every resize bug below is a variation of this one root cause.
+
+## Rule 1 — Render into the alternate screen buffer
+
+**Prevents:** ghost content — old frames stacking up, the logo repeating, a scrollbar appearing on resize.
+
+**Why:** Ink writes to the normal terminal buffer, which has scrollback. Shrink the window and the terminal shows scrollback; grow it and old output is still in the buffer at the now-visible positions. Ink overwrites from the cursor but can't erase content it no longer knows about. The alternate screen has no scrollback at all, so there's nothing to bleed in from.
+
+Enter with `\x1B[?1049h` before `render()`, exit with `\x1B[?1049l`. Hide the cursor (`\x1B[?25l`) while you're in it — cleaner, and it avoids cursor flicker on re-renders.
+
+```typescript
+// Before render():
+process.stdout.write('\x1B[?1049h\x1B[?25l'); // enter alt screen, hide cursor
+const restoreTerminal = () => process.stdout.write('\x1B[?25h\x1B[?1049l');
+process.once('exit', restoreTerminal);
+```
+
+Always register the `process.once('exit', restoreTerminal)` handler so the terminal is restored even on crash. Skip it and you strand the user in alt-screen mode after the program exits.
+
+## Rule 2 — Register the clear handler in the entry point, BEFORE `render()`
+
+**Prevents:** the blank screen after resize — everything disappears except the active-tab highlight until the user presses a key.
+
+**Why:** Node fires resize listeners in registration order. If you put the clear in a `useEffect`, it registers *after* `render()` (effects run post-mount, and `render()` is where Ink registers its own handler). So on resize, Ink's handler fires first and draws the full TUI, then your clear fires second and wipes everything Ink just drew. Ink thinks the frame is already drawn, so it doesn't redraw until the next state change.
+
+Register the clear in the entry point before `render()`, so it ends up first in the queue and Ink draws onto an already-clean screen.
+
+```typescript
+// index.ts — register BEFORE render()
+const clearOnResize = () => process.stdout.write('\x1B[2J\x1B[H');
+process.stdout.on('resize', clearOnResize);
+
+// Now call render() — Ink registers its handler here, AFTER ours
+const { waitUntilExit } = render(...);
+
+// Clean up on exit
+process.stdout.off('resize', clearOnResize);
+```
+
+## Rule 3 — Track terminal width as React state
+
+**Prevents:** the stale divider — width-dependent content (dividers, layout math) keeps its old width after resize until the user presses a key.
+
+**Why:** Values computed from `process.stdout.columns` are read once at render time. After resize the columns value updates, but nothing triggers a React re-render. Make width state so the change propagates.
+
+The resize handler in the root component does exactly one thing: update state. No escape codes, no clearing in here (the clear lives in the entry point, Rule 2).
+
+```typescript
+// App.tsx
+const [termWidth, setTermWidth] = useState(process.stdout.columns ?? 80);
+
+useEffect(() => {
+  const onResize = () => setTermWidth(process.stdout.columns ?? 80);
+  process.stdout.on('resize', onResize);
+  return () => { process.stdout.off('resize', onResize); };
+}, []);
+
+// Use termWidth for anything that depends on terminal width
+const divider = '─'.repeat(termWidth);
+```
+
+This handler registers after Ink's (correct), fires third, and triggers a second render. Ink diffs and updates only the changed line.
+
+## Correct resize event order
+
+Order is the whole game. When it's right:
+
+1. `clearOnResize` (entry point, registered first) — clears the screen, cursor to (0,0).
+2. Ink's internal handler (second) — recalculates layout with new dimensions, draws the full TUI onto the clean screen.
+3. `setTermWidth` (root component, third) — the state update triggers a second render; Ink diffs and updates only the width-dependent lines.
+
+## Never
+
+- **Never use `\x1Bc` (RIS, reset to initial state).** It resets the entire terminal — colors, font, cursor settings — and behaves differently across emulators. Use `\x1B[2J\x1B[H` (clear + cursor home).
+- **Never put the clear in a `useEffect`.** Effects run after mount, after Ink registers its handlers, so your clear will always fire after Ink draws.
+- **Never write escape codes inside a component's render path** (outside effects). They fire during React's render phase and fight Ink's output buffer.
+- **Never split resize logic across multiple conflicting handlers.** The clear lives in the entry point; state updates live in the root component. One job each, or the ordering becomes fragile.
+
+## New-TUI checklist
+
+- [ ] Alternate screen buffer (`\x1B[?1049h` / `\x1B[?1049l`) entered from the entry point
+- [ ] Clear handler (`\x1B[2J\x1B[H`) registered in the entry point BEFORE `render()`
+- [ ] Terminal width tracked as state in the root component
+- [ ] Resize handler updates state only — no escape codes
+- [ ] `process.once('exit', ...)` restores the terminal on exit and on crash
+- [ ] Resize handlers cleaned up (`process.stdout.off(...)`) when the TUI exits

package/.claude/skills/test-writer/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: test-writer
+description: Write tests that catch bugs, with explicit assertions, realistic data, and proper structure. Use when asked to write, add, improve, or expand tests, or to raise coverage. Writes test files and runs them to confirm they assert real behavior.
+when_to_use: |
+  - User asks to write tests, add coverage, or improve existing tests
+  - New code needs a test, or a bug needs a regression test
+  - User says "write tests", "add a test", "cover this"
+allowed-tools: "Read, Write, Grep, Glob, Bash"
+---
+
+# Test Writer
+
+You write tests that catch bugs, not tests that pass. A test that can't fail isn't a test.
+
+## Principles
+
+1. Every test has explicit assertions. "Page loads" is not a test.
+2. Test behavior, not implementation details.
+3. Cover the happy path, the error cases, and the edge cases.
+4. Use realistic test data, never `test` / `asdf`.
+5. Tests are independent. No shared mutable state between them.
+
+## Structure
+
+```typescript
+describe('[Feature]', () => {
+  describe('[Scenario]', () => {
+    it('should [expected behavior] when [condition]', async () => {
+      // Arrange — set up test data
+      // Act — perform the action
+      // Assert — verify SPECIFIC outcomes
+    });
+  });
+});
+```
+
+## Assertions
+
+```typescript
+// GOOD — explicit, specific
+expect(result.status).toBe(200);
+expect(result.body.user.email).toBe('ada@example.com');
+await expect(page.locator('h1')).toContainText('Welcome');
+
+// BAD — passes even when broken
+expect(result).toBeTruthy();   // too vague
+await page.goto('/dashboard'); // no assertion at all
+```
+
+## Data-layer tests (this codebase)
+
+The data layer has rules that test data must respect, or the test passes while masking the exact bug that bites in production.
+
+- **Seed real `ObjectId` values, not string ids.** The single most common production bug here is a string-vs-`ObjectId` `_id` mismatch that silently returns nothing. A test seeded with string ids passes and hides it. Use actual `ObjectId` types in fixtures.
+- **Exercise the StrictDB adapter, not a hand-rolled driver mock.** Tests go through the same `adapters/` boundary the handlers use. Mock at the network or data boundary, not by reimplementing the driver.
+- **Test the round trip.** Where data is serialized (JSON in, JSON out), assert that types survive it, since that round trip is where `_id` mismatches and code-66 upsert errors appear.
+
+## Unit tests (Vitest)
+
+Each test verifies:
+
+1. Return value matches expected.
+2. Side effects occurred, or provably didn't.
+3. Error cases throw the proper error.
+4. Edge cases: null, empty, max values, and for ids, wrong-type ids.
+
+## E2E tests (Playwright)
+
+Each test verifies:
+
+1. Correct URL after navigation.
+2. Key elements are present.
+3. Correct data is displayed.
+4. Error states show the proper message.
+
+## Before finishing
+
+Run the tests. A new test should fail against code that doesn't satisfy it and pass once it does. If a test passes the moment you write it without the behavior existing, it isn't asserting anything, fix the assertion.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheDecipherist
+
+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.