safeword 0.2.4 → 0.2.5

package/learnings/ai-sdk-v5-breaking-changes.md

@@ -1,178 +0,0 @@
-# AI SDK v5 Breaking Changes
-
-**Principle:** AI SDK v5 removed `input` and `setInput` from `useChat` hook. You must manage text input state locally.
-
-## The Gotcha
-
-What breaks when upgrading from AI SDK v4 to v5:
-
-❌ **Bad (AI SDK v4 pattern):**
-
-```typescript
-import { useChat } from '@ai-sdk/react'
-
-export function Chat() {
-  const { input, setInput, messages, sendMessage } = useChat({
-    api: '/api/chat'
-  })
-
-  // input = undefined, setInput = undefined in v5!
-  return <input value={input} onChange={(e) => setInput(e.target.value)} />
-}
-```
-
-✅ **Good (AI SDK v5 pattern):**
-
-```typescript
-import { useChat } from '@ai-sdk/react'
-import { useState } from 'react'
-
-export function Chat() {
-  // Manage input state locally
-  const [input, setInput] = useState('')
-
-  const { messages, sendMessage } = useChat({
-    api: '/api/chat'
-  })
-
-  return <input value={input} onChange={(e) => setInput(e.target.value)} />
-}
-```
-
-**Why it matters:**
-
-- `!undefined` = `true` → buttons stay disabled when checking `!input`
-- `setInput(value)` throws "setInput is not a function"
-- Tests may pass (if using controlled component wrappers) while browser fails
-
-## Breaking Changes in AI SDK v5
-
-### Removed from useChat return value:
-
-- ❌ `input` (string)
-- ❌ `setInput` (function)
-- ❌ `handleSubmit` (function)
-- ❌ `handleInputChange` (function)
-
-### Still available:
-
-- ✅ `messages`
-- ✅ `setMessages`
-- ✅ `sendMessage`
-- ✅ `status`
-- ✅ `stop`
-- ✅ `reload`
-- ✅ `data` (for data stream)
-
-### New architecture:
-
-AI SDK v5 uses **transport-based design**. Input management is now the developer's responsibility.
-
-## Migration Pattern
-
-**Before (v4):**
-
-```typescript
-const { input, setInput, handleSubmit } = useChat()
-
-<form onSubmit={handleSubmit}>
-  <input value={input} onChange={handleInputChange} />
-</form>
-```
-
-**After (v5):**
-
-```typescript
-const [input, setInput] = useState('')
-const { sendMessage } = useChat()
-
-const handleSubmit = (e: FormEvent) => {
-  e.preventDefault()
-  if (input.trim()) {
-    sendMessage({ text: input })
-    setInput('')
-  }
-}
-
-<form onSubmit={handleSubmit}>
-  <input
-    value={input}
-    onChange={(e) => setInput(e.target.value)}
-  />
-</form>
-```
-
-## Testing Trap
-
-Integration tests using `useState` in a TestWrapper will pass even if production code is broken:
-
-```typescript
-// Test (passes even with broken useChat usage)
-function TestWrapper() {
-  const [input, setInput] = useState('')  // Local state works
-  return <MultimodalInput input={input} setInput={setInput} />
-}
-
-// Production (broken - input/setInput are undefined)
-function Chat() {
-  const { input, setInput } = useChat()  // undefined in v5!
-  return <MultimodalInput input={input} setInput={setInput} />
-}
-```
-
-**Solution:** Tests should verify the actual integration pattern, not just component behavior. Or add E2E tests that exercise the full Chat → useChat → MultimodalInput chain.
-
-## Symptoms
-
-If you see these symptoms, check if you're destructuring removed properties:
-
-1. **Button stays disabled when typing** - `!undefined` = `true`
-2. **Console error: "X is not a function"** - `setInput` doesn't exist
-3. **Input state is undefined** - Check console: `input: undefined`
-4. **Tests pass but browser fails** - TestWrapper uses local state, production uses broken useChat
-
-## Debug Strategy
-
-1. Add logging to see what useChat returns:
-
-```typescript
-const chatHelpers = useChat({ ... })
-console.log('useChat returned:', Object.keys(chatHelpers))
-```
-
-2. Check if input/setInput exist:
-
-```typescript
-console.log('input:', input, 'setInput:', typeof setInput);
-// v5: input: undefined setInput: undefined
-```
-
-3. Verify AI SDK version:
-
-```bash
-grep '"ai":' package.json
-# "ai": "5.0.87" = v5 (breaking changes)
-```
-
-## References
-
-- AI SDK v5 docs: https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat
-- Migration guide: https://ai-sdk.dev/docs/ai-sdk-ui/migration-guide
-- Breaking change announcement: "The useChat API has been significantly updated in AI SDK 5.0"
-
-## Real-World Example
-
-**Project:** Chat application with send button
-**Bug:** Button stayed disabled when typing
-**Root cause:** Destructuring `input` and `setInput` from useChat (both undefined in v5)
-**Fix:** Add `const [input, setInput] = useState('')` in Chat component
-**Commit:** See project history for detailed investigation
-
-## Prevention
-
-**When upgrading to AI SDK v5:**
-
-1. Search codebase for `useChat` usage: `grep -r "useChat" --include="*.tsx"`
-2. Check each usage for destructuring `input`, `setInput`, `handleSubmit`, `handleInputChange`
-3. Replace with local state management
-4. Test in actual browser (integration tests may give false confidence)

package/learnings/e2e-test-zombie-processes.md

@@ -1,231 +0,0 @@
-# E2E Test Zombie Processes
-
-**Principle:** E2E tests that spawn dev servers can create zombie processes if run in parallel. Always enforce sequential execution and provide clear cleanup instructions.
-
-## The Gotcha
-
-When E2E test frameworks (Playwright, Cypress) start dev servers via `webServer` config, running multiple test commands in parallel creates competing server instances that fight for the same port. This leads to:
-
-- Port conflicts (EADDRINUSE)
-- Orphaned processes that never terminate
-- Tests hanging indefinitely during retry phase
-- Accumulating zombie processes across multiple test runs
-
-❌ **Bad:** Running multiple test commands simultaneously
-
-```bash
-# Terminal 1
-pnpm test &
-
-# Terminal 2 (before Terminal 1 completes)
-pnpm test &
-
-# Result: 2 webServers competing for port 3000
-# Both hang, neither completes, processes accumulate
-```
-
-✅ **Good:** Enforce sequential execution
-
-```bash
-# Terminal 1
-pnpm test
-
-# Wait for completion...
-
-# Terminal 2 (only after Terminal 1 finishes)
-pnpm test
-```
-
-**Why it matters:**
-
-- Users don't realize background processes are still running
-- Each retry attempt doubles the problem (retry #1 spawns another webServer)
-- Can accumulate 8+ zombie processes across a debugging session
-- Port conflicts make ALL subsequent tests fail
-
-## Prevention
-
-### 1. Document Sequential Execution Requirement
-
-In your testing docs (e.g., `tests/SAFEWORD.md`), add prominent warning:
-
-```markdown
-### Zombie processes / Port already in use
-
-**NEVER run multiple `pnpm test` commands simultaneously**
-
-- Only run ONE test command at a time
-- Wait for previous test run to complete before starting another
-
-Why: Each test run spawns its own webServer. Multiple parallel runs
-fight for same port, creating zombie processes.
-```
-
-### 2. Configure playwright.config.ts for Safety
-
-```typescript
-export default defineConfig({
-  // In CI: workers=1 (sequential)
-  // Locally: workers=undefined (allows parallelism within single run)
-  workers: process.env.CI ? 1 : undefined,
-
-  webServer: {
-    command: 'npm run dev',
-    url: 'http://localhost:3000',
-    timeout: 120000,
-    reuseExistingServer: !process.env.CI, // Reuse locally, fresh in CI
-    stdout: 'pipe', // Capture output for debugging hangs
-    stderr: 'pipe', // Capture errors
-  },
-});
-```
-
-**Key settings:**
-
-- `reuseExistingServer: !process.env.CI` - Reuse server locally (faster), fresh in CI (reliable)
-- `stdout: 'pipe'` / `stderr: 'pipe'` - Capture output to debug when webServer hangs
-- `workers: 1` in CI - Forces sequential execution where parallelism is most dangerous
-
-### 3. Provide Clear Cleanup Instructions
-
-```bash
-# Kill all processes on test ports
-lsof -ti:3000 | xargs kill -9 2>/dev/null
-lsof -ti:3001 | xargs kill -9 2>/dev/null
-
-# Or kill by process name pattern
-pkill -9 -f "playwright.*test-name"
-pkill -9 -f "next dev"
-
-# Wait before starting tests again
-sleep 5
-```
-
-## Debugging Zombie Processes
-
-### Symptoms
-
-- Error: `Port 3000 is in use`
-- Error: `Timed out waiting 120000ms from config.webServer`
-- Tests hang during retry phase
-- `ps aux | grep test` shows multiple test processes
-
-### Root Cause Investigation
-
-```bash
-# Check for background test processes
-ps aux | grep -E "(playwright|next dev|pnpm test)"
-
-# Check what's using the port
-lsof -i:3000
-
-# Check for orphaned Node processes
-pgrep -fl node
-```
-
-### Fix
-
-1. **Kill all test-related processes**
-
-   ```bash
-   pkill -9 -f "pnpm test"
-   pkill -9 -f "next dev"
-   pkill -9 -f "playwright"
-   ```
-
-2. **Verify ports are clear**
-
-   ```bash
-   lsof -i:3000  # Should return nothing
-   ```
-
-3. **Wait before restarting**
-
-   ```bash
-   sleep 5  # Give processes time to fully terminate
-   ```
-
-4. **Review process management**
-   - Check if any terminals have background jobs (`jobs` command)
-   - Check if any tests are running in other terminal windows
-   - Restart terminal session if processes won't die
-
-## Testing Trap
-
-**Tests pass locally but fail in CI:**
-
-- **Cause:** Local machine has `reuseExistingServer: true`, so dev server stays running across test runs
-- **In CI:** Fresh server every time, exposes timing/startup issues
-- **Fix:** Occasionally test locally with `reuseExistingServer: false` to catch CI-only failures
-
-**Tests hang during retry phase:**
-
-- **Cause:** Retry spawns another webServer while first is still running
-- **Amplification:** Each retry doubles the zombie processes (1 → 2 → 4 → 8)
-- **Fix:**
-  - Reduce retries: `retries: process.env.CI ? 2 : 1`
-  - Fix flaky tests so retries aren't needed
-  - Add debugging output to understand why tests are failing
-
-## Examples
-
-### ✅ Good: Sequential Execution in Documentation
-
-````markdown
-## Running Tests
-
-```bash
-# Run all tests (ONE command at a time)
-pnpm test
-
-# Run specific test file
-pnpm test -- path/to/file.test.ts
-
-# IMPORTANT: Wait for test run to complete before starting another
-```
-````
-
-````
-
-### ✅ Good: Clear Warning in CI/CD Setup
-
-```yaml
-# .github/workflows/test.yml
-- name: Run E2E tests
-  run: pnpm test
-  # NOTE: Do not run multiple test commands in parallel
-  # Each spawns a webServer competing for ports
-````
-
-### ❌ Bad: No Warning About Parallel Execution
-
-````markdown
-## Running Tests
-
-```bash
-pnpm test  # Run all tests
-```
-````
-
-```
-
-**Problem:** Developers don't know that running `pnpm test` in multiple terminals simultaneously will cause zombie processes.
-
-## Key Principles
-
-1. **Educate developers** - Most don't realize background processes are still running
-2. **Enforce sequential execution** - Document it prominently in testing guides
-3. **Add debugging visibility** - Use `stdout: 'pipe'` to capture webServer output
-4. **Provide cleanup scripts** - Make it easy to kill zombie processes when they happen
-5. **Test locally like CI** - Occasionally disable `reuseExistingServer` to catch CI-only issues
-
-## Related Patterns
-
-- **Test retry amplification** - Each retry doubles zombie processes
-- **Port conflict cascades** - One zombie process blocks all future test runs
-- **Silent background jobs** - Users don't notice processes still running after terminal close
-
-## Reference
-
-Discovered during demo mode E2E testing implementation (2025-11-01). See project-specific learning for demo mode testing patterns.
-```

package/learnings/milkdown-crepe-editor-property.md

@@ -1,96 +0,0 @@
-# Milkdown Crepe .editor Property is Official Public API
-
-**Principle:** `crepe.editor` is the **official way** to access the underlying Milkdown Editor and register custom plugins - it's not a hack.
-
-## The Gotcha
-
-When extending Crepe with custom ProseMirror plugins, you might think accessing `.editor` is bypassing the public API:
-
-❌ **Assumption:** "We're accessing an internal property"
-✅ **Reality:** `.editor` is explicitly declared in TypeScript definitions as a public getter
-
-**Why it matters:** This is a **correct, supported pattern** for extending Crepe. No need to replace Crepe with core Milkdown just to avoid this "hack."
-
-## Evidence
-
-From `@milkdown/crepe` TypeScript definitions (`node_modules/@milkdown/crepe/lib/types/core/builder.d.ts:18`):
-
-```typescript
-export declare class CrepeBuilder {
-  #private;
-  constructor({ root, defaultValue }?: CrepeBuilderConfig);
-  addFeature: { /* ... */ };
-  create: () => Promise<Editor>;
-  destroy: () => Promise<Editor>;
-  get editor(): Editor; // ← PUBLIC API GETTER
-  get readonly(): boolean;
-  setReadonly: (value: boolean) => this;
-  getMarkdown: () => string;
-  on: (fn: (api: ListenerManager) => void) => this;
-}
-
-export declare class Crepe extends CrepeBuilder {
-  // Inherits all properties from CrepeBuilder, including .editor getter
-}
-```
-
-## Correct Usage Pattern
-
-```typescript
-import { Crepe } from '@milkdown/crepe';
-import { trackChangesPlugin } from './plugins/trackChangesPlugin';
-
-const crepe = new Crepe({ root, defaultValue: '', features: {} });
-
-// ✅ CORRECT - Official public API
-crepe.editor.use(trackChangesPlugin);
-
-return crepe.editor;
-```
-
-## When to Use This Pattern
-
-Use `crepe.editor.use()` when you need to:
-
-- Register custom ProseMirror plugins that Crepe doesn't provide
-- Access the underlying Milkdown Editor instance for direct API calls
-- Configure plugins that aren't available through Crepe's feature system
-
-## Alternative (Not Recommended)
-
-You could replace Crepe with core Milkdown:
-
-```typescript
-// ❌ NOT RECOMMENDED - Loses Crepe's pre-built features
-import { Editor } from '@milkdown/core';
-
-return Editor.make().use(commonmark).use(listener).use(history).use(trackChangesPlugin);
-```
-
-**Why not recommended:**
-
-- Lose Crepe's toolbar, slash commands, block editing UI
-- 2-3 weeks to rebuild features
-- More code to maintain
-- Violates "avoid bloat" principle
-- Zero user value
-
-## Research Sources
-
-- **GitHub Discussion:** [How to add extra plugins to the crepe editor? #1432](https://github.com/orgs/Milkdown/discussions/1432)
-  - Maintainer confirmed: "Register the plugin as usual" after fixing rollup bug in v7.5.2
-- **Web Search:** Multiple examples show `crepe.editor.use()` pattern in production code
-- **TypeScript Definitions:** Explicit public getter declaration
-
-## Conclusion
-
-When you see `crepe.editor.use(plugin)` in code reviews, **don't flag it as a hack**. It's the correct, documented way to extend Crepe with custom functionality.
-
-**Decision:** Keep the current implementation. No refactoring needed.
-
----
-
-**Related Files:**
-
-- `src/components/Editor.tsx` - Uses this pattern to register trackChangesPlugin
-- `planning/design/track-changes-refactoring-plan.md` - Initially flagged as hack, now corrected

package/learnings/prosemirror-fragment-traversal.md

@@ -1,119 +0,0 @@
-# ProseMirror Fragment Traversal
-
-**Principle:** `Fragment.forEach()` only iterates direct children, not descendants. Use recursive traversal to process nested text nodes.
-
-## The Gotcha
-
-When applying marks to typed text in ProseMirror, `Fragment.forEach()` doesn't reach text nodes nested inside block nodes (paragraphs, headings, etc.).
-
-❌ **Bad:** Iterating fragments without recursion
-
-```typescript
-// This ONLY sees paragraph nodes, not text inside them
-const markedNodes: Node[] = [];
-fragment.forEach((node: Node) => {
-  if (node.isText) {
-    markedNodes.push(node.mark([...node.marks, insertionMark]));
-  }
-  // Paragraph node with text children → mark NOT applied
-});
-```
-
-✅ **Good:** Recursive traversal
-
-```typescript
-function markFragmentRecursive(fragment: Fragment, mark: Mark): Fragment {
-  const markedNodes: Node[] = [];
-
-  fragment.forEach((node: Node) => {
-    if (node.isText) {
-      // Text node - add mark
-      markedNodes.push(node.mark([...node.marks, mark]));
-    } else if (node.content.size > 0) {
-      // Block node with children - recursively mark children
-      const markedContent = markFragmentRecursive(node.content, mark);
-      markedNodes.push(node.copy(markedContent));
-    } else {
-      // Leaf node without content - keep as-is
-      markedNodes.push(node);
-    }
-  });
-
-  return Fragment.from(markedNodes);
-}
-```
-
-**Why it matters:** User types "hello" → ProseMirror wraps it in paragraph → `Fragment → Paragraph → Text("hello")`. Without recursion, `forEach()` only sees the paragraph node, and marks are applied to the wrong level.
-
-## Document Structure
-
-ProseMirror documents are tree structures:
-
-```
-Fragment (from ReplaceStep.slice.content)
-├─ Paragraph node
-│  └─ Text("hello")  ← forEach() DOESN'T reach this
-└─ Heading node
-   └─ Text("world")  ← forEach() DOESN'T reach this
-```
-
-## Testing Trap
-
-Tests might pass if you manually create flat fragments in test fixtures:
-
-```typescript
-// ✅ Test passes (flat structure)
-const testFragment = Fragment.from(schema.text('hello'));
-// Fragment → Text("hello")  ← forEach() DOES reach this
-
-// ❌ Real app breaks (nested structure)
-// User types "hello" → editor wraps in paragraph
-// Fragment → Paragraph → Text("hello")  ← forEach() DOESN'T reach this
-```
-
-**Solution:** Test with realistic document structures (paragraphs, headings) that match actual user input, not artificially flat fragments.
-
-## When to Use Recursive Traversal
-
-Use recursive traversal when:
-
-- Processing text content across entire document (search, replace, mark application)
-- Transforming node structure at any depth (format conversion, sanitization)
-- Analyzing document content (word count, spell check)
-
-Use simple `forEach()` when:
-
-- Only processing top-level nodes (block-level operations)
-- Explicitly working with known flat structures
-
-## Reference Pattern
-
-```typescript
-// Recursive helper for deep traversal
-function processFragmentRecursive(fragment: Fragment, operation: (node: Node) => Node): Fragment {
-  const processedNodes: Node[] = [];
-
-  fragment.forEach((node: Node) => {
-    if (node.isText) {
-      processedNodes.push(operation(node));
-    } else if (node.content.size > 0) {
-      const processedContent = processFragmentRecursive(node.content, operation);
-      processedNodes.push(node.copy(processedContent));
-    } else {
-      processedNodes.push(node);
-    }
-  });
-
-  return Fragment.from(processedNodes);
-}
-```
-
-## Additional Resources
-
-- [ProseMirror Node docs](https://prosemirror.net/docs/ref/#model.Node) - `node.copy()` for immutable updates
-- [Fragment API](https://prosemirror.net/docs/ref/#model.Fragment) - `forEach()` behavior
-- Track Changes implementation example: `packages/web/src/plugins/trackChangesPlugin.ts:17-45`
-
-## Summary
-
-**Fragment.forEach() is shallow.** Always use recursive traversal when processing text content, as ProseMirror wraps text in block nodes (paragraphs, headings). Test with realistic nested structures, not flat fragments.

package/packages/cli/AGENTS.md

@@ -1 +0,0 @@
-**⚠️ ALWAYS READ FIRST: @./.safeword/SAFEWORD.md**