wize-dev-kit 0.1.3 → 0.1.5

package/src/web-overlay/stack-catalog.md

@@ -0,0 +1,208 @@
+---
+catalog: web-stack
+owner: wize-agent-architect   # Tony (with Fury on strategy)
+applies_when: web-overlay active
+status: ready
+---
+
+# Web Stack Catalog — Tony's Reference
+
+Tony reads this during the architecture interview. The catalog is opinionated but lists trade-offs honestly; the final pick depends on the PRD audience, Fury's NFR budget, and team comfort.
+
+## 1. Decision dimensions
+
+Pick by **dimension order**, not "which framework I like":
+
+1. **Audience reach** — public marketing + SEO, or authenticated app?
+2. **Latency budget** — sub-1s LCP on 3G, or richer-but-slower OK?
+3. **Team familiarity** — favor the boring choice the team has shipped before.
+4. **Backend coupling** — separate API, fullstack monolith, or BaaS?
+5. **Deploy target** — edge platform, container, or self-managed?
+
+## 2. Front-end frameworks
+
+### Next.js (React)
+
+| | |
+|---|---|
+| **Pick when** | SEO-critical pages + product app in one codebase. Strong ecosystem. |
+| **Strengths** | App Router (RSC), edge runtime, ISR, large hiring pool. |
+| **Costs** | RSC mental model still maturing; vendor lock-in toward Vercel optional but present. |
+| **Bundle baseline** | React runtime ~45 KB gz + framework code. |
+| **Best for** | Public products needing SEO + auth product behind same domain. |
+
+### Nuxt 3 (Vue)
+
+| | |
+|---|---|
+| **Pick when** | Vue-shop wanting Next-tier DX. |
+| **Strengths** | Composition API ergonomics, auto-imports, modules ecosystem. |
+| **Costs** | Smaller third-party SDK coverage than React. |
+| **Bundle baseline** | Vue runtime ~30 KB gz. |
+| **Best for** | Marketing + dashboard hybrid where Vue is the team's stack. |
+
+### SvelteKit
+
+| | |
+|---|---|
+| **Pick when** | Smallest runtime + fastest TTI. |
+| **Strengths** | Compile-to-no-runtime, intuitive reactivity, edge-first. |
+| **Costs** | Smaller hiring pool, fewer enterprise integrations. |
+| **Bundle baseline** | ~0 KB framework runtime; only your code. |
+| **Best for** | Latency-sensitive products, content-heavy + interactive. |
+
+### Astro
+
+| | |
+|---|---|
+| **Pick when** | Content-first (docs, marketing, blog) with islands of interactivity. |
+| **Strengths** | Zero-JS by default; mix frameworks per island. |
+| **Costs** | Not a SPA; not the right tool for heavy state apps. |
+| **Bundle baseline** | ~0 KB unless you opt into an island. |
+| **Best for** | Marketing sites, docs portals, mostly-static products. |
+
+### Remix
+
+| | |
+|---|---|
+| **Pick when** | Forms + nested routes + progressive enhancement matter. |
+| **Strengths** | Web fundamentals first; great for "works without JS" requirements. |
+| **Costs** | Smaller community than Next; some patterns ported back to Next. |
+| **Bundle baseline** | React runtime + Remix glue. |
+| **Best for** | Form-heavy apps (admin, e-commerce flows). |
+
+### SPAs without SSR (CRA-style, Vite + React/Vue/Svelte)
+
+| | |
+|---|---|
+| **Pick when** | Authenticated app behind login; SEO not required. |
+| **Strengths** | Simplest mental model; fast iteration. |
+| **Costs** | Slow LCP for first-time visitors; no SEO. |
+| **Best for** | Internal tools, dashboards, B2B authenticated apps. |
+
+### Laravel + Vue (Inertia)
+
+| | |
+|---|---|
+| **Pick when** | PHP back-end exists + team is PHP-fluent. |
+| **Strengths** | Server-rendered routing + SPA UX; great DX in monolith mode. |
+| **Costs** | PHP hosting realities; smaller real-time ecosystem. |
+| **Best for** | Brownfield Laravel apps modernizing the front-end. |
+
+## 3. Back-end / data layer
+
+### Supabase
+
+| | |
+|---|---|
+| **Pick when** | Need Postgres + auth + storage + realtime with low setup. |
+| **Strengths** | Full Postgres power, RLS, edge functions, GoTrue auth. |
+| **Costs** | Lock-in to Supabase service surface (mitigated by being Postgres underneath). |
+
+### PlanetScale / Neon (managed Postgres)
+
+| | |
+|---|---|
+| **Pick when** | Need managed serverless Postgres without the rest of Supabase. |
+| **Strengths** | Branching DBs, generous free tiers, edge-friendly. |
+| **Costs** | You ship your own auth, storage, realtime. |
+
+### Drizzle ORM
+
+| | |
+|---|---|
+| **Pick when** | TypeScript-first ORM, edge-runtime compatibility matters. |
+| **Strengths** | Tiny runtime, SQL-y; great for serverless. |
+| **Costs** | Smaller ecosystem than Prisma. |
+
+### Prisma
+
+| | |
+|---|---|
+| **Pick when** | Larger team; tooling and migrations are paramount. |
+| **Strengths** | Excellent migrations, generated client, mature ecosystem. |
+| **Costs** | Heavier runtime; edge story improved but not as native as Drizzle. |
+
+### tRPC
+
+| | |
+|---|---|
+| **Pick when** | Single TS monorepo, server + client share types. |
+| **Strengths** | Type-safe end-to-end; minimal overhead. |
+| **Costs** | Not language-agnostic; OpenAPI shim needed for external consumers. |
+
+### GraphQL (Apollo / urql / Relay)
+
+| | |
+|---|---|
+| **Pick when** | Many client consumers, federated data sources. |
+| **Strengths** | Per-client shape, schema-first design. |
+| **Costs** | Server complexity; caching nuance; not always worth it for one client. |
+
+## 4. Authentication
+
+| Choice | Pick when |
+|---|---|
+| Supabase Auth (GoTrue) | Using Supabase already. |
+| Clerk / Auth0 | Need polished UI + SSO out of the box; team avoids auth complexity. |
+| WorkOS | Enterprise SSO + SCIM from day one. |
+| Lucia | Self-hosted, TS, full control, smaller team. |
+| Roll-your-own | Almost never. |
+
+## 5. Hosting / deploy
+
+| Choice | Pick when |
+|---|---|
+| **Vercel** | Next.js / Nuxt / SvelteKit, edge functions, generous DX. |
+| **Cloudflare Pages + Workers** | Latency, global edge, low cost. |
+| **Fly.io** | Need a real container with TCP, sticky regions. |
+| **Coolify** (self-hosted PaaS) | Want Vercel-ish DX on own infra. |
+| **Render / Railway** | Container apps + databases under one billing. |
+| **Self-hosted Docker** | Heavy compliance constraints. |
+
+## 6. Styling
+
+| Choice | Pick when |
+|---|---|
+| **Tailwind CSS** | Token-first design system, utility-class team comfort. |
+| **CSS Modules** | Component-scoped, no runtime, easy SSR. |
+| **Vanilla Extract** | Type-safe styling at build time. |
+| **shadcn-ui / Radix Primitives** | Need accessible primitives without ceding design. |
+| **Linaria / Compiled** | CSS-in-JS without runtime cost. |
+
+Mantis owns tokens (`.wize/solutioning/design-system/tokens.json`); Tony picks the system that maps those tokens cleanly.
+
+## 7. State management
+
+| Choice | Pick when |
+|---|---|
+| **React Server Components / Suspense** | Most data is server-derived. |
+| **TanStack Query** | Heavy client-side data + caching. |
+| **Zustand** | Small global state; no boilerplate. |
+| **Jotai** | Atoms feel right for the domain. |
+| **Pinia** (Vue) | Default Vue store. |
+| **Redux Toolkit** | Time-travel, complex async pipelines, large team. |
+
+## 8. Forms
+
+| Choice | Pick when |
+|---|---|
+| **React Hook Form + Zod** | Type-safe schemas, low re-render count. |
+| **Conform** | Server-progressive enhancement (Remix). |
+| **TanStack Form** | TanStack ecosystem, schema-agnostic. |
+
+## 9. Anti-patterns Tony flags fast
+
+- Mixing **SSR + heavy client state** without a clear seam.
+- Loading `lodash` for one function.
+- Using **Redux for an app with 3 stores** of 5 keys each.
+- Picking a tech because it's on a HackerNews front page.
+- Defaulting to GraphQL for a one-client app.
+
+## 10. Recording the choice
+
+Tony writes the chosen stack into:
+
+- `.wize/planning/tech-vision.md` (Fury): family + non-negotiables.
+- `.wize/solutioning/architecture.md` (Tony): concrete picks + reasons.
+- `.wize/solutioning/adrs/ADR-001-stack.md`: the trade-off log for future readers.

package/tools/installer/setup-helpers.js

@@ -0,0 +1,105 @@
+// Setup helpers used by `wize-dev-kit install`:
+//   - generateUserToml({ name, role }) → .wize/config/user.toml template
+//   - applyGitignore(projectRoot) → idempotent gitignore block injection
+//
+// Both are pure functions where possible; only applyGitignore writes to disk.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const GITIGNORE_BEGIN = '# >>> wize-dev-kit (managed) >>>';
+const GITIGNORE_END = '# <<< wize-dev-kit (managed) <<<';
+
+const GITIGNORE_BODY = [
+  '# Personal / per-developer (do NOT commit)',
+  '.wize/config/user.toml',
+  '.wize/scratch/',
+  '.wize/.local/',
+  '.wize/implementation/quick-dev-log.md',
+  '',
+  '# Generated IDE adapter outputs (regenerate with `npx wize-dev-kit install`)',
+  '.claude/skills/wize-*',
+  '.agent/skills/wize-*',
+  '.agents/skills/wize-*',
+  '.kimi/skills/wize-*',
+  '.cursor/rules/wize-*.mdc',
+  '.windsurf/rules/wize-*.md',
+  '.continue/prompts/wize-*.prompt',
+  '.opencode/agents/wize-*.md',
+  '.opencode/commands/wize-*.md',
+  '.wize/agents/wize-*.md'
+].join('\n');
+
+function buildGitignoreBlock() {
+  return [
+    GITIGNORE_BEGIN,
+    '# Managed by `npx wize-dev-kit install`. Re-running install will update',
+    '# the lines between the markers below; lines outside are untouched.',
+    '',
+    GITIGNORE_BODY,
+    GITIGNORE_END
+  ].join('\n');
+}
+
+// Idempotent: if the block exists, replace it; otherwise append.
+// Returns { changed: boolean, mode: 'created'|'replaced'|'appended'|'unchanged' }.
+function applyGitignore(projectRoot, { dryRun = false } = {}) {
+  const file = path.join(projectRoot, '.gitignore');
+  const block = buildGitignoreBlock();
+  let current = '';
+  let exists = fs.existsSync(file);
+  if (exists) current = fs.readFileSync(file, 'utf-8');
+
+  const startIdx = current.indexOf(GITIGNORE_BEGIN);
+  const endIdx = current.indexOf(GITIGNORE_END);
+  let next;
+  let mode;
+
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const before = current.slice(0, startIdx).replace(/\n+$/, '');
+    const after = current.slice(endIdx + GITIGNORE_END.length).replace(/^\n+/, '');
+    next = [before, block, after].filter(Boolean).join('\n\n');
+    if (!next.endsWith('\n')) next += '\n';
+    mode = current.includes(block) ? 'unchanged' : 'replaced';
+  } else if (exists) {
+    next = current.replace(/\n+$/, '') + '\n\n' + block + '\n';
+    mode = 'appended';
+  } else {
+    next = block + '\n';
+    mode = 'created';
+  }
+
+  const changed = next !== current;
+  if (changed && !dryRun) fs.writeFileSync(file, next, 'utf-8');
+  return { changed, mode };
+}
+
+function generateUserToml({ name = '', role = '' } = {}) {
+  const escapedName = String(name).replace(/"/g, '\\"');
+  const roleLine = role
+    ? `role = "${String(role).replace(/"/g, '\\"')}"`
+    : `# role = "developer"          # optional — "developer", "PM", "designer", etc.`;
+  return `# Wize Development Kit — user-level customizations.
+# This file is per-developer; the kit places it in .gitignore so each member
+# of the team gets their own copy. Do NOT commit.
+
+[user]
+name = "${escapedName}"
+${roleLine}
+
+[preferences]
+# Override project-level language if you prefer another locally:
+# communication   = "pt-BR"
+# document_output = "en"
+`;
+}
+
+module.exports = {
+  GITIGNORE_BEGIN,
+  GITIGNORE_END,
+  buildGitignoreBlock,
+  applyGitignore,
+  generateUserToml
+};

package/tools/installer/wize-cli.js

@@ -10,9 +10,11 @@
 'use strict';
 
 const fs = require('node:fs');
+const os = require('node:os');
 const path = require('node:path');
 const readline = require('node:readline');
 const prompts = require('prompts');
+const { applyGitignore, generateUserToml } = require('./setup-helpers.js');
 
 const INTERACTIVE = process.stdout.isTTY && process.stdin.isTTY;
 
@@ -228,7 +230,7 @@ function projectToml({ profiles, targets, communication_language, document_outpu
   const profileLine = profiles.map(p => `"${p.code}"`).join(', ');
   const targetLine = targets.map(t => `"${t.code}"`).join(', ');
   return `# Wize Development Kit — project config
-# Generated at install. Edit user-level customizations in user.toml.
+# Generated at install. Commit this file. Personal preferences live in user.toml.
 
 [project]
 name = "${project_name}"
@@ -239,7 +241,7 @@ profiles = [${profileLine}]
 ide_targets = [${targetLine}]
 
 [language]
-# Language used when agents talk to you in the IDE chat.
+# Language used when agents talk to the team in chat.
 communication = "${communication_language}"
 # Language used when agents write artifacts to disk
 # (brief.md, prd.md, architecture.md, gate.md, etc.).
@@ -271,12 +273,6 @@ gate    = { granularity = "per-story" }
 `;
 }
 
-function userToml() {
-  return `# Wize Development Kit — user-level customizations
-# This file is preserved on update; project.toml may be rewritten.
-`;
-}
-
 function renderAdapters({ kitRoot, projectRoot, targets, profiles }) {
   const results = [];
   const profileCodes = profiles.map(p => p.code);
@@ -336,18 +332,39 @@ async function cmdInstall(args) {
     communication_language
   );
 
+  // Personal touch — the user_name lands in .wize/config/user.toml (per-developer).
+  const defaultName = (os.userInfo().username || '').trim();
+  const user_name = (await prompt(
+    `How should the agents call you? [${defaultName || 'leave blank'}]: `
+  )).trim() || defaultName;
+
+  // Gitignore — opt-in, idempotent.
+  const wantsGitignore = await confirm(
+    'Add the suggested entries to .gitignore (user.toml + scratch + generated adapter outputs)?',
+    true
+  );
+
   console.log('\nCreating .wize/ skeleton...');
   for (const dir of WIZE_DIRS) mkdirp(path.join(cwd, dir));
 
   writeIfMissing(path.join(cwd, '.wize/config/project.toml'), projectToml({
     profiles, targets, communication_language, document_output_language, project_name
   }));
-  writeIfMissing(path.join(cwd, '.wize/config/user.toml'), userToml());
+  writeIfMissing(path.join(cwd, '.wize/config/user.toml'), generateUserToml({ name: user_name }));
   writeIfMissing(path.join(cwd, '.wize/config/tea.toml'), teaToml());
 
   console.log('✓ .wize/ created');
   console.log(`✓ profiles: ${profiles.map(p => p.code).join(', ')}`);
   console.log(`✓ ide targets: ${targets.map(t => t.code).join(', ')}`);
+  if (user_name) console.log(`✓ user.toml: agents will call you "${user_name}"`);
+
+  if (wantsGitignore) {
+    const r = applyGitignore(cwd);
+    if (r.changed) console.log(`✓ .gitignore ${r.mode} with the wize-dev-kit block`);
+    else           console.log(`= .gitignore already up to date`);
+  } else {
+    console.log('= .gitignore untouched (you opted out of suggested entries)');
+  }
 
   console.log('\nGenerating IDE adapters...');
   const renderResults = renderAdapters({