blacksmith-cli 0.1.4 → 0.1.6

package/dist/index.js

@@ -311,7 +311,7 @@ pages/<page>/
 \u251C\u2500\u2500 routes.tsx         # RouteObject[] using Path enum
 \u251C\u2500\u2500 index.ts           # Re-exports public API
 \u251C\u2500\u2500 components/        # Child components
-\u2514\u2500\u2500 hooks/             # Data hooks
+\u2514\u2500\u2500 hooks/             # Page-local hooks (UI logic, not API hooks)
 \`\`\`
 - See the \`page-structure\` skill for full conventions
 `;
@@ -1371,9 +1371,10 @@ var reactSkill = {
 - Display user-facing errors using the project's feedback components (Alert, Toast)
 
 ### Testing
-- Run all tests: \`cd frontend && npm test\`
-- Run a specific test: \`cd frontend && npm test -- --grep "test name"\`
-- Test files live alongside the code they test (\`component.test.tsx\`)
+- See the \`frontend-testing\` skill for full conventions on test placement, utilities, mocking, and what to test
+- **Every code change must include corresponding tests** \u2014 see the \`frontend-testing\` skill for the complete rules
+- Tests use \`.spec.tsx\` / \`.spec.ts\` and live in \`__tests__/\` folders co-located with source code
+- Always use \`renderWithProviders\` from \`@/__tests__/test-utils\` \u2014 never import \`render\` from \`@testing-library/react\` directly
 `;
   }
 };
@@ -1418,12 +1419,12 @@ const { data, errorMessage } = useApiQuery({
 import { postsRetrieveOptions } from '@/api/generated/@tanstack/react-query.gen'
 
 const { data: post, isLoading, errorMessage } = useApiQuery({
-  ...postsRetrieveOptions({ path: { id: Number(id) } }),
+  ...postsRetrieveOptions({ path: { id: id! } }),
 })
 
 // Conditional query (skip until id is available)
 const { data } = useApiQuery({
-  ...postsRetrieveOptions({ path: { id: Number(id) } }),
+  ...postsRetrieveOptions({ path: { id: id! } }),
   enabled: !!id,
 })
 \`\`\`
@@ -1478,7 +1479,7 @@ const deletePost = useApiMutation({
 })
 
 const handleDelete = async () => {
-  await deletePost.mutateAsync({ path: { id: Number(id) } })
+  await deletePost.mutateAsync({ path: { id: id! } })
   navigate('/posts')
 }
 \`\`\`
@@ -1573,7 +1574,7 @@ export function useCreatePost() {
   })
 }
 
-export function useUpdatePost(id: number) {
+export function useUpdatePost(id: string) {
   return useApiMutation({
     ...postsUpdateMutation(),
     invalidateKeys: [
@@ -1624,7 +1625,7 @@ pages/<page>/
 \u251C\u2500\u2500 routes.tsx         # Exports RouteObject[] for this page
 \u251C\u2500\u2500 index.ts           # Re-exports public members (routes)
 \u251C\u2500\u2500 components/        # Components private to this page (optional)
-\u2514\u2500\u2500 hooks/             # Hooks private to this page (optional)
+\u2514\u2500\u2500 hooks/             # Page-local hooks (UI logic, not API hooks)
 \`\`\`
 
 **\`routes.tsx\`** \u2014 defines the route config using the \`Path\` enum:
@@ -1678,8 +1679,7 @@ export const postsRoutes: RouteObject[] = [
 **\`index.ts\`** \u2014 exports routes first:
 \`\`\`ts
 export { postsRoutes } from './routes'
-export { usePosts } from './hooks/use-posts'
-export { useCreatePost, useUpdatePost, useDeletePost } from './hooks/use-post-mutations'
+export { usePosts, useCreatePost, useUpdatePost, useDeletePost } from '@/api/hooks/posts'
 \`\`\`
 
 ### Route Paths (\`src/router/paths.ts\`)
@@ -3152,7 +3152,7 @@ function useOrdersPage() {
     orders: data?.results ?? [],
     pagination: { ...pagination, total: data?.count ?? 0 },
     search,
-    deleteOrder: (id: number) => deleteOrder.mutate({ path: { id } }),
+    deleteOrder: (id: string) => deleteOrder.mutate({ path: { id } }),
   }
 }
 \`\`\`
@@ -3428,6 +3428,244 @@ class OrderService:
   }
 };
 
+// src/skills/frontend-testing.ts
+var frontendTestingSkill = {
+  id: "frontend-testing",
+  name: "Frontend Testing Conventions",
+  description: "Test infrastructure, file placement, test utilities, and rules for when and how to write frontend tests.",
+  render(_ctx) {
+    return `## Frontend Testing Conventions
+
+### Stack
+- **Vitest** \u2014 test runner (configured in \`vite.config.ts\`)
+- **jsdom** \u2014 browser environment
+- **React Testing Library** \u2014 component rendering and queries
+- **\`@testing-library/user-event\`** \u2014 user interaction simulation
+- **\`@testing-library/jest-dom\`** \u2014 DOM assertion matchers (e.g. \`toBeInTheDocument\`)
+
+### Running Tests
+- Run all tests: \`cd frontend && npm test\`
+- Watch mode: \`cd frontend && npm run test:watch\`
+- Run a specific file: \`cd frontend && npx vitest run src/pages/home/__tests__/home.spec.tsx\`
+- Coverage: \`cd frontend && npm run test:coverage\`
+
+### File Placement \u2014 Tests Live Next to the Code
+
+> **RULE: Every test file goes in a \`__tests__/\` folder co-located with the code it tests. Never put tests in a top-level \`tests/\` directory.**
+
+\`\`\`
+pages/customers/
+\u251C\u2500\u2500 customers-page.tsx
+\u251C\u2500\u2500 customer-detail-page.tsx
+\u251C\u2500\u2500 __tests__/                        # Page integration tests
+\u2502   \u251C\u2500\u2500 customers-page.spec.tsx
+\u2502   \u2514\u2500\u2500 customer-detail-page.spec.tsx
+\u251C\u2500\u2500 components/
+\u2502   \u251C\u2500\u2500 customer-card.tsx
+\u2502   \u251C\u2500\u2500 customer-list.tsx
+\u2502   \u251C\u2500\u2500 customer-form.tsx
+\u2502   \u2514\u2500\u2500 __tests__/                    # Component unit tests
+\u2502       \u251C\u2500\u2500 customer-card.spec.tsx
+\u2502       \u251C\u2500\u2500 customer-list.spec.tsx
+\u2502       \u2514\u2500\u2500 customer-form.spec.tsx
+\u2514\u2500\u2500 hooks/
+    \u251C\u2500\u2500 use-customers-page.ts
+    \u2514\u2500\u2500 __tests__/                    # Hook tests
+        \u2514\u2500\u2500 use-customers-page.spec.ts
+\`\`\`
+
+The same pattern applies to \`features/\`, \`shared/\`, and \`router/\`:
+\`\`\`
+features/auth/
+\u251C\u2500\u2500 pages/
+\u2502   \u251C\u2500\u2500 login-page.tsx
+\u2502   \u2514\u2500\u2500 __tests__/
+\u2502       \u2514\u2500\u2500 login-page.spec.tsx
+\u251C\u2500\u2500 hooks/
+\u2502   \u2514\u2500\u2500 __tests__/
+shared/
+\u251C\u2500\u2500 components/
+\u2502   \u2514\u2500\u2500 __tests__/
+\u251C\u2500\u2500 hooks/
+\u2502   \u2514\u2500\u2500 __tests__/
+router/
+\u251C\u2500\u2500 __tests__/
+\u2502   \u251C\u2500\u2500 paths.spec.ts
+\u2502   \u2514\u2500\u2500 auth-guard.spec.tsx
+\`\`\`
+
+### Test File Naming
+- Use \`.spec.tsx\` for component/page tests (JSX)
+- Use \`.spec.ts\` for pure logic tests (hooks, utilities, no JSX)
+- Name matches the source file: \`customer-card.tsx\` \u2192 \`customer-card.spec.tsx\`
+
+### Always Use \`renderWithProviders\`
+
+> **RULE: Never import \`render\` from \`@testing-library/react\` directly. Always use \`renderWithProviders\` from \`@/__tests__/test-utils\`.**
+
+\`renderWithProviders\` wraps components with all app providers (ThemeProvider, QueryClientProvider, MemoryRouter) so tests match the real app environment.
+
+\`\`\`tsx
+import { screen } from '@/__tests__/test-utils'
+import { renderWithProviders } from '@/__tests__/test-utils'
+import { MyComponent } from '../my-component'
+
+describe('MyComponent', () => {
+  it('renders correctly', () => {
+    renderWithProviders(<MyComponent />)
+    expect(screen.getByText('Hello')).toBeInTheDocument()
+  })
+})
+\`\`\`
+
+**Options:**
+\`\`\`tsx
+renderWithProviders(<MyComponent />, {
+  routerEntries: ['/customers/1'],  // Set initial route
+  queryClient: customQueryClient,   // Custom query client
+})
+\`\`\`
+
+**User interactions:**
+\`\`\`tsx
+const { user } = renderWithProviders(<MyComponent />)
+await user.click(screen.getByRole('button', { name: 'Submit' }))
+await user.type(screen.getByLabelText('Email'), 'test@example.com')
+\`\`\`
+
+### When to Write Tests
+
+> **RULE: Every code change that touches pages, components, hooks, or utilities must include corresponding test updates.**
+
+| What changed | Test required |
+|---|---|
+| New page | Add \`__tests__/<page>.spec.tsx\` with integration test |
+| New component | Add \`__tests__/<component>.spec.tsx\` |
+| New hook (with logic) | Add \`__tests__/<hook>.spec.ts\` |
+| New utility function | Add \`__tests__/<util>.spec.ts\` |
+| Modified page/component | Update existing test or add new test cases |
+| Bug fix | Add regression test that would have caught the bug |
+| Deleted page/component | Delete corresponding test file |
+
+### What to Test
+
+**Page integration tests** \u2014 test the page as a whole:
+- Renders correct heading/title
+- Loading state shows skeleton or spinner
+- Error state shows error message
+- Data renders correctly (mock the API hooks)
+- User interactions (navigation, form submission, delete confirmation)
+
+**Component unit tests** \u2014 test the component in isolation:
+- Renders with required props
+- Handles optional props correctly (present vs absent)
+- Displays correct content based on props
+- User interactions trigger correct callbacks
+- Conditional rendering (empty state, loading state)
+
+**Hook tests** \u2014 test custom hooks with logic:
+- Returns correct initial state
+- Transforms data correctly
+- Side effects fire as expected
+
+**Utility/pure function tests** \u2014 test input/output:
+- Happy path
+- Edge cases (empty input, null, special characters)
+- Error cases
+
+### Mocking Patterns
+
+**Mock hooks (for page tests):**
+\`\`\`tsx
+vi.mock('@/api/hooks/customers')
+vi.mock('@/features/auth/hooks/use-auth')
+
+import { useCustomers } from '@/api/hooks/customers'
+
+beforeEach(() => {
+  vi.mocked(useCustomers).mockReturnValue({
+    data: { customers: mockCustomers, total: 2 },
+    isLoading: false,
+    errorMessage: null,
+  } as any)
+})
+\`\`\`
+
+**Mock external UI libraries (for auth page tests):**
+\`\`\`tsx
+vi.mock('@blacksmith-ui/auth', () => ({
+  LoginForm: ({ onSubmit, error, loading }: any) => (
+    <form onSubmit={(e: any) => { e.preventDefault(); onSubmit({ email: 'test@test.com', password: 'pass' }) }}>
+      {error && <div data-testid="error">{error.message}</div>}
+      <button type="submit">Sign In</button>
+    </form>
+  ),
+}))
+\`\`\`
+
+**Mock react-router-dom hooks (for detail pages):**
+\`\`\`tsx
+const mockNavigate = vi.fn()
+vi.mock('react-router-dom', async () => {
+  const actual = await vi.importActual('react-router-dom')
+  return { ...actual, useParams: () => ({ id: '1' }), useNavigate: () => mockNavigate }
+})
+\`\`\`
+
+### Test Structure
+\`\`\`tsx
+import { screen, waitFor } from '@/__tests__/test-utils'
+import { renderWithProviders } from '@/__tests__/test-utils'
+
+// Mocks at the top, before imports of modules that use them
+vi.mock('@/api/hooks/customers')
+
+import { useCustomers } from '@/api/hooks/customers'
+import CustomersPage from '../customers-page'
+
+const mockCustomers = [
+  { id: '1', title: 'Acme Corp', created_at: '2024-01-15T10:00:00Z' },
+]
+
+describe('CustomersPage', () => {
+  beforeEach(() => {
+    vi.mocked(useCustomers).mockReturnValue({ ... } as any)
+  })
+
+  it('renders page heading', () => {
+    renderWithProviders(<CustomersPage />)
+    expect(screen.getByText('Customers')).toBeInTheDocument()
+  })
+
+  it('shows error message when API fails', () => {
+    vi.mocked(useCustomers).mockReturnValue({
+      data: undefined,
+      isLoading: false,
+      errorMessage: 'Failed to load',
+    } as any)
+
+    renderWithProviders(<CustomersPage />)
+    expect(screen.getByText('Failed to load')).toBeInTheDocument()
+  })
+})
+\`\`\`
+
+### Key Rules
+
+1. **Tests live next to code** \u2014 \`__tests__/\` folder alongside the source, not in a separate top-level directory
+2. **Always use \`renderWithProviders\`** \u2014 never import render from \`@testing-library/react\` directly
+3. **Every page gets an integration test** \u2014 at minimum: renders heading, handles loading, handles errors
+4. **Every component gets a unit test** \u2014 at minimum: renders with required props, handles optional props
+5. **Mock at the hook level** \u2014 mock \`useCustomers\`, not \`fetch\`. Mock \`useAuth\`, not the auth adapter
+6. **Test behavior, not implementation** \u2014 query by role, text, or label, not by class names or internal state
+7. **No test-only IDs unless necessary** \u2014 prefer \`getByRole\`, \`getByText\`, \`getByLabelText\` over \`getByTestId\`
+8. **Keep tests focused** \u2014 each \`it()\` tests one behavior. Don't assert 10 things in one test
+9. **Clean up mocks** \u2014 use \`beforeEach\` to reset mock return values so tests don't leak state
+10. **Update tests when code changes** \u2014 if you modify a component, update its tests. If you delete a component, delete its tests
+`;
+  }
+};
+
 // src/skills/clean-code.ts
 var cleanCodeSkill = {
   id: "clean-code",
@@ -3564,14 +3802,16 @@ var aiGuidelinesSkill = {
 
 ### Checklist Before Finishing a Task
 1. Backend tests pass: \`cd backend && ./venv/bin/python manage.py test\`
-2. Frontend builds: \`cd frontend && npm run build\`
-3. API types are in sync: \`blacksmith sync\`
-4. No lint errors in modified files
-5. All UI uses \`@blacksmith-ui/react\` components \u2014 no raw \`<div>\` for layout, no raw \`<h1>\`-\`<h6>\` for text
-6. Pages are modular \u2014 page file is a thin orchestrator, sections are in \`components/\`, logic in \`hooks/\`
-7. Logic is in hooks \u2014 no \`useApiQuery\`, \`useApiMutation\`, \`useEffect\`, or multi-\`useState\` in component bodies
-8. No hardcoded route paths \u2014 all paths use the \`Path\` enum from \`@/router/paths\`
-9. New routes have a corresponding \`Path\` enum entry
+2. Frontend tests pass: \`cd frontend && npm test\`
+3. Frontend builds: \`cd frontend && npm run build\`
+4. API types are in sync: \`blacksmith sync\`
+5. No lint errors in modified files
+6. All UI uses \`@blacksmith-ui/react\` components \u2014 no raw \`<div>\` for layout, no raw \`<h1>\`-\`<h6>\` for text
+7. Pages are modular \u2014 page file is a thin orchestrator, sections are in \`components/\`, logic in \`hooks/\`
+8. Logic is in hooks \u2014 no \`useApiQuery\`, \`useApiMutation\`, \`useEffect\`, or multi-\`useState\` in component bodies
+9. No hardcoded route paths \u2014 all paths use the \`Path\` enum from \`@/router/paths\`
+10. New routes have a corresponding \`Path\` enum entry
+11. **Tests are co-located** \u2014 every new or modified page, component, or hook has a corresponding \`.spec.tsx\` / \`.spec.ts\` in a \`__tests__/\` folder next to the source file (see the \`frontend-testing\` skill)
 `;
   }
 };
@@ -3598,6 +3838,7 @@ async function setupAiDev({ projectDir, projectName, includeBlacksmithUiSkill })
       skills.push(uiDesignSkill);
     }
     skills.push(blacksmithCliSkill);
+    skills.push(frontendTestingSkill);
     skills.push(programmingParadigmsSkill);
     skills.push(cleanCodeSkill);
     skills.push(aiGuidelinesSkill);
@@ -4157,6 +4398,20 @@ async function makeResource(name) {
   } catch {
     syncSpinner.warn('Could not sync OpenAPI. Run "blacksmith sync" manually.');
   }
+  const apiHooksDir = path7.join(frontendDir, "src", "api", "hooks", names.kebabs);
+  const apiHooksSpinner = spinner(`Creating API hooks: api/hooks/${names.kebabs}/`);
+  try {
+    renderDirectory(
+      path7.join(templatesDir, "resource", "api-hooks"),
+      apiHooksDir,
+      context
+    );
+    apiHooksSpinner.succeed(`Created frontend/src/api/hooks/${names.kebabs}/`);
+  } catch (error) {
+    apiHooksSpinner.fail("Failed to create API hooks");
+    log.error(error.message);
+    process.exit(1);
+  }
   const frontendSpinner = spinner(`Creating frontend page: pages/${names.kebabs}/`);
   try {
     renderDirectory(
@@ -4286,6 +4541,7 @@ var allSkills = [
   blacksmithUiAuthSkill,
   blacksmithHooksSkill,
   blacksmithCliSkill,
+  frontendTestingSkill,
   cleanCodeSkill,
   aiGuidelinesSkill
 ];