procedure-cli 0.1.12 → 0.1.14

package/CLAUDE.md

@@ -1,138 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-See docs/PRD.md for product requirements and docs/USER-STORIES.md for user stories with acceptance criteria.
-
-## Build & Test
-
-```bash
-npm run dev                 # Run CLI directly (tsx, no build step)
-npm run typecheck           # Typecheck (fast — run first)
-npm run build               # Compile to dist/
-npx tsx src/cli.tsx         # Run entry point directly
-```
-
-## Code Style
-
-- TypeScript strict mode, ESM (`"type": "module"` in package.json)
-- JSX runtime: `react-jsx` (no `import React` needed in components, but keep it for clarity in entry points)
-- Ink components use `.tsx` extension; pure logic uses `.ts`
-- Handlebars templates use `.hbs` extension in `templates/`
-- Providers live in `src/providers/` — one file per provider, each exports a single provider instance
-- Environment variables for API keys: `ZAI_API_KEY`, `OPENAI_API_KEY` (never hardcode)
-
-## Architecture
-
-- **Entry point**: `src/cli.tsx` — parses args, calls `render(<App />)`
-- **UI layer**: `src/app.tsx` — Ink root component, wizard controller with 7-step flow
-- **Wizard steps**: `src/steps/` — one component per step, each receives `onComplete` callback
-- **UI components**: `src/components/` — banner, timeline, step-indicator, gutter-line, guttered-select
-- **Core logic**: `src/lib/` — pure functions, no UI
-  - `template.ts` — Handlebars rendering, file scaffolding
-  - `powerline.ts` — Claude Code powerline setup (from setup-powerline.sh logic)
-  - `git.ts` — git init + initial commit
-  - `fs.ts` — directory/file helpers
-  - `types.ts` — WizardAnswers interface, StepId type
-- **Templates**: `templates/` — Handlebars files (.hbs) rendered with wizard answers into target projects
-- **Config**: `config/` — defaults, stack presets, bundled powerline config
-- **AI providers**: `src/providers/` — Z.ai uses `@ai-sdk/openai-compatible` (GLM models), OpenAI uses `@ai-sdk/openai`
-- **AI SDK 6**: All AI calls go through Vercel AI SDK 6 (`ai` package). Use `generateText`, `streamText`, or `generateObject` — not raw fetch
-- **Docs**: `docs/` — PRD, User Stories (Gherkin A/C), methodology explainer (Vietnamese)
-
-## Workflow
-
-### Planning
-- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
-- If something goes sideways, STOP and re-plan — don't keep pushing
-- A good plan lets you one-shot the implementation
-
-### Verification
-- Never mark a task complete without proving it works
-- Run `npm run typecheck` then `npm run dev` to verify
-- Ask yourself: "Would a staff engineer approve this?"
-
-### Self-Improvement
-- After ANY correction from the user: update the Lessons section below
-- Write rules that prevent the same mistake from recurring
-
-### Bug Fixing
-- Given a bug report: just fix it. Don't ask for hand-holding
-- Point at logs, errors, failing tests — then resolve them
-
-### Elegance
-- For non-trivial changes: pause and ask "is there a more elegant way?"
-- If a fix feels hacky, step back and implement the clean solution
-- Skip this for simple, obvious fixes — don't over-engineer
-
-## Task Management
-
-### Solo Work
-1. Plan first (plan mode for complex tasks)
-2. Track progress with TaskCreate/TaskUpdate for multi-step work
-3. Verify before claiming done
-4. Update Lessons after corrections
-
-### Agent Teams
-1. Plan-then-team: design approach BEFORE spawning a team
-2. Each task = one clear deliverable with verification steps
-3. File ownership: each teammate owns specific files — NEVER have two edit the same file
-4. Include file paths and constraints in task descriptions — teammates don't inherit context
-5. DMs by default, broadcast only for critical blocking issues
-6. 3-5 teammates max
-
-## Code Review & Fix Logging
-
-Two tracking files live at the project root. Both are append-only logs — never delete or rewrite past entries.
-
-### CODE-REVIEW.md — review findings
-- Created/appended during code review sessions.
-- Entry ID format: `CR-YYYYMMDD-###` (zero-padded sequence per day).
-- Findings ordered by severity (`High`, `Medium`, `Low`).
-- Every finding includes `file:line` evidence, a clear recommendation, and `Status` (`New`, `Still Open`, `Fixed`, `Regressed`, `Not Reproducible`).
-
-### CODE-FIXED.md — fix results
-- Created/appended when fixing findings from CODE-REVIEW.md.
-- Entry ID format: `CF-YYYYMMDD-###`.
-- Each entry references its source review by `CR-` Entry ID — do NOT re-describe findings, only document actions taken.
-- Fixed findings include `file:line` for every change made.
-- Deferred findings include rationale and a revisit trigger.
-- Verification section must confirm `npm run typecheck` + `npm run build` status after fixes.
-
-### Procedure
-1. **Reviewing**:
-   - **First**: Read CODE-REVIEW.md → Read CODE-FIXED.md → understand current state of findings and fixes.
-   - **Then**: Read codebase → append findings to CODE-REVIEW.md with a new `CR-` entry (write to CODE-REVIEW.md only, never modify CODE-FIXED.md).
-   - **Never** fix code during a reviewing process.
-2. **Fixing**:
-   - **First**: Read CODE-REVIEW.md → Read CODE-FIXED.md → identify unfixed findings.
-   - **Then**: Fix only unfixed findings → append a new `CF-` entry to CODE-FIXED.md (write to CODE-FIXED.md only, never modify CODE-REVIEW.md).
-   - **Never** perform a code review during a fixing process.
-
-## Core Principles
-
-- **Simplicity First**: Make every change as simple as possible. Minimal code impact.
-- **No Laziness**: Find root causes. No temporary fixes. Senior developer standards.
-- **Minimal Impact**: Changes should only touch what's necessary.
-
-## Lessons
-
-- Timeline `│` lines must stay vertically aligned — never indent content in a way that breaks the straight line from dot to dot
-- Required wizard fields must validate: don't allow empty submissions for project name, description, etc.
-- Active step needs visual animation (spinner/pulse) so user knows the CLI is waiting for input
-- Errors display below the input field in a distinct color (red/yellow) — never inline with the prompt
-- Completed steps need visual acknowledgment (checkmark, color change) beyond just swapping the dot symbol
-- Always add an intro/tagline under the ASCII banner so the user knows what the tool does
-- NEVER run `npm run dev` from the procedure project directory — scaffolding writes to cwd and overwrites procedure's own files. Always test in a temp directory.
-- Select menus (not text input) for fields with known options: package manager, license, architecture pattern
-- Don't prefill fields from unrelated previous answers (e.g., project name → description)
-- Architecture notes should be auto-generated from the selected pattern — users may not know best practices
-- Generation step must show a summary and ask for confirmation before writing files
-- Use `<Text>` not `<Box>` for single-line elements — `<Box>` creates flex containers that add visual gaps
-- Step components must return `<>` fragments, NOT `<Box flexDirection="column">` — only timeline.tsx gets the outer Box
-- Completed step summaries go on a SEPARATE `│  ` line below the step name, not on the same line (prevents wrapping)
-- Custom GutteredSelect/GutteredMultiSelect for select menus — `@inkjs/ui` Select breaks the `│` gutter line
-- Tech stack multi-select should prefill from Stack & Style selections (language + framework)
-- Stack & Style = dev setup (language, framework, code style → CLAUDE.md). Tech Stack = full product stack (databases, infra → PRD/README)
-- Color theme is Catppuccin Mocha — always use hex constants from `src/theme.ts` (`C.mauve`, `C.green`, etc.), never terminal color names like `"cyan"`, `"green"`, `"red"`. This ensures consistent rendering across all terminal emulators.
-- Timeline `┌`/`└` corners wrap the entire wizard flow (top of Project Info, bottom of Setup) — not individual steps

package/CODE-FIXED.md

@@ -1,197 +0,0 @@
-# Code Fix Log
-
-## Writing Standard
-- Each entry documents fixes applied for a specific `CODE-REVIEW.md` entry.
-- Reference the source review by its Entry ID (e.g., `CR-20260221-001`). Do NOT re-describe findings — only document actions taken.
-- For finding details, the reader should consult the referenced `CODE-REVIEW.md` entry.
-- Each finding is referenced as `Finding #N (Severity)` matching the review's numbering.
-- Fixed findings must include `file:line` for every change made.
-- Deferred findings must include rationale and a revisit trigger.
-- Verification section must confirm `npm run typecheck` + `npm run build` status after fixes.
-- Language: English only. Tone: Technical, concise, action-focused.
-
-### Entry ID Convention
-- Required field for every entry: `Entry ID`.
-- Format: `CF-YYYYMMDD-###`
-- Example: `CF-20260222-001`
-- `###` is a zero-padded sequence number for that day.
-
----
-
-## Entry 2026-02-22
-
-### Entry ID
-- `CF-20260222-001`
-
-### Source Review
-- `CR-20260221-001` (CODE-REVIEW.md entry 2026-02-21)
-
-### Fixes Applied
-
-1. Finding #1 (High) — **Fixed**
-- `src/lib/powerline.ts:33` — Changed `--config=~/.claude/powerline-config.json` to `--config=.claude/powerline-config.json` so the status-line command reads from the project-local path where the config is actually written.
-
-2. Finding #2 (Medium) — **Fixed**
-- `src/lib/git.ts:3-11` — Added `hasGitIdentity()` helper that pre-checks `git config user.name` and `git config user.email`.
-- `src/lib/git.ts:13-28` — Refactored `initGit()` to return `{ committed: boolean; reason?: string }`. Skips `git commit` when identity is missing and returns a descriptive reason string.
-
-3. Finding #3 (Medium) — **Fixed**
-- `src/lib/powerline.ts:21-29` — Wrapped `JSON.parse(raw)` in try/catch; malformed `.claude/settings.json` now falls back to empty object instead of throwing.
-
-4. Finding #4 (Medium) — **Fixed**
-- `src/lib/template.ts:38-44` — Added `checkConflicts(targetDir)` function that returns list of existing output files that would be overwritten.
-- `src/steps/generation.tsx:5,61,102-113` — Imported `checkConflicts`, added yellow warning in summary phase listing files that will be overwritten before user confirms.
-
-5. Finding #5 (Low) — **Fixed**
-- `src/lib/types.ts:64` — Added `generationSkipped: boolean` field to `WizardAnswers`.
-- `src/app.tsx:49` — Added `generationSkipped: false` to `EMPTY_ANSWERS`.
-- `src/app.tsx:83` — Updated `getSummary` case 5 to return `"skipped"` when `generationSkipped` is true.
-- `src/steps/generation.tsx:9` — Changed `onComplete` prop type to `(partial: Partial<WizardAnswers>) => void`.
-- `src/steps/generation.tsx:35` — On successful generation, calls `onComplete({ generationSkipped: false })`.
-- `src/steps/generation.tsx:48` — On cancel, calls `onComplete({ generationSkipped: true })`.
-- `src/app.tsx:179` — Changed `onComplete={() => handleStepComplete({})}` to `onComplete={handleStepComplete}`.
-
-6. Finding #6 (Low) — **Fixed**
-- `templates/docs/USER-STORIES.md.hbs:1-32` — Added Handlebars `{{#if userStories.length}}` conditional with fallback starter template content when `userStories` is empty. Fallback includes example user story in Gherkin format with clear TODO instructions.
-
-### Deferred
-None — all 6 findings fixed.
-
-### Verification Notes
-- `npm run typecheck`: pass (0 errors)
-- All fixes verified through code inspection.
-
-### Residual Risks / Testing Gaps
-- No automated tests for `checkConflicts()` behavior.
-- No automated tests for `initGit()` across machines with missing git identity.
-- No automated tests for malformed `.claude/settings.json` handling.
-- No automated tests asserting generation summary truthfulness when user cancels.
-- No runtime test for Handlebars `{{#if userStories.length}}` fallback rendering.
-
----
-
-## Entry 2026-02-22
-
-### Entry ID
-- `CF-20260222-002`
-
-### Source Review
-- `CR-20260221-002` (CODE-REVIEW.md entry 2026-02-21)
-
-### Fixes Applied
-
-1. Finding #7 (Medium) — **Fixed**
-- `src/lib/git.ts:13-20` — Added `hasStagedFiles()` helper that runs `git status --porcelain`; returns `false` when index is empty.
-- `src/lib/git.ts:30-33` — Added early return `{ committed: false, reason: 'Nothing to commit — directory is empty.' }` before identity check, preventing hard crash on empty-directory init.
-
-2. Finding #8 (Low) — **Fixed**
-- `src/app.tsx:133-141` — Wrapped completion message in `answers.generationSkipped` conditional. Skip path shows neutral `"Generation was skipped — no files were written."` Scaffold path retains original project name + doc check message.
-
-3. Finding #6 re-raised (Low, Still Open in CR-20260221-002) — **Already Fixed**
-- Covered by `CF-20260222-001` Finding #6: `templates/docs/USER-STORIES.md.hbs` Handlebars fallback added in previous fix cycle. No further action required.
-
-### Deferred
-None.
-
-### Verification Notes
-- `npm run typecheck`: pass (0 errors)
-- `npm run build`: pass
-
----
-
-## Entry 2026-02-22
-
-### Entry ID
-- `CF-20260222-003`
-
-### Source Review
-- `CR-20260221-004` (CODE-REVIEW.md entry 2026-02-21)
-
-### Fixes Applied
-
-1. Finding #9 (Low, Still Open) — **Fixed**
-- `src/steps/powerline.tsx:22` — Added `gitCommitted?: boolean` to `SetupResult` interface.
-- `src/steps/powerline.tsx:41-44` — `runSetup()` now stores `gitResult.committed` in `setupResult.gitCommitted`.
-- `src/steps/powerline.tsx:125-133` — "Git repository initialized." only renders when `setupResult.gitCommitted` is true. When commit failed, only the yellow warning with reason is shown (no mixed success/failure messaging).
-
-### Deferred
-None.
-
-### Verification Notes
-- `npm run typecheck`: pass
-- `npm run build`: pass
-
----
-
-## Entry 2026-02-22
-
-### Entry ID
-- `CF-20260222-004`
-
-### Source Review
-- `CR-20260222-002` (CODE-REVIEW.md entry 2026-02-22)
-
-### Fixes Applied
-
-1. Finding #10 (Low) — **Fixed**
-- `src/lib/types.ts:68` — Added `setupGit: boolean` to `WizardAnswers` so setup choice can be persisted.
-- `src/app.tsx:51` — Added `setupGit: false` to `EMPTY_ANSWERS`.
-- `src/app.tsx:89` — Updated setup summary to render `Git init: yes/no` based on `answers.setupGit` instead of always implying git initialization.
-- `src/steps/powerline.tsx:48` — Updated `onComplete` payload to include `setupGit: git`, preserving the user’s git setup decision for final summaries.
-
-### Deferred
-None.
-
-### Verification Notes
-- `npm run typecheck`: pass
-- `npm run build`: pass
-
----
-## Entry 2026-02-22
-
-### Entry ID
-- `CF-20260222-005`
-
-### Source Review
-- `CR-20260222-003` (CODE-REVIEW.md entry 2026-02-22)
-
-### Fixes Applied
-
-1. Finding #11 (Low) — **Fixed**
-- `src/steps/build-test.tsx:68` — Replaced `dimColor` with `color={C.overlay1}` to comply with the Catppuccin theme rule and keep all color rendering sourced from `src/theme.ts` constants.
-
-### Deferred
-None.
-
-### Verification Notes
-- `npm run typecheck`: pass
-- `npm run build`: pass
-- `rg "dimColor|color=\"(cyan|green|red|yellow|blue|magenta|white|black)\"" -n src`: no matches
-
----
-## Entry 2026-02-22
-
-### Entry ID
-- `CF-20260222-006`
-
-### Source Review
-- `CR-20260222-004` (CODE-REVIEW.md entry 2026-02-22)
-
-### Fixes Applied
-
-1. Finding #12 (Medium) — **Fixed**
-- `src/cli.tsx:11` — Replaced hard-stop behavior with warning-only messaging when directory is non-empty.
-- `src/cli.tsx:13` — Added explicit note that existing files may be overwritten during Step 6, preserving the intended Generation conflict-confirmation flow.
-- `src/cli.tsx:16` — Removed process exit path so wizard continues and existing overwrite warnings in Generation remain reachable.
-
-2. Finding #13 (Low) — **Fixed**
-- `src/cli.tsx:16` — Updated setup hint to include both valid invocations: `npx procedure-cli` and `npx @b3awesome/procedure`, avoiding single-command drift.
-
-### Deferred
-None.
-
-### Verification Notes
-- `npm run typecheck`: pass
-- `npm run build`: pass
-
----