prizmkit 1.1.48 → 1.1.51

package/bundled/skills/prizmkit-test/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: "prizmkit-test"
+description: "Full-stack test generation and orchestration. Detects architecture, discovers/runs existing tests, analyzes coverage gaps, generates missing tests (unit/integration/E2E), outputs unified report. Use after completing development to verify quality before deploy. Trigger on: 'test', 'run tests', 'check quality', 'verify code', 'generate tests', 'test coverage', 'fill test gaps', 'quality check', '测试', '验证', '跑测试', '补测试'. (project)"
+---
+
+# PrizmKit Test
+
+A comprehensive test generation and orchestration skill. Discovers existing tests, runs them, compares coverage against spec acceptance criteria and module interfaces, generates missing tests at three levels (unit → integration → E2E), and produces a unified report.
+
+### When to Use
+- After completing one or more features/refactors/bugfixes
+- As a quality gate before deploy
+- Project has a test framework installed but zero tests written (first-time test generation)
+- User says "test", "run tests", "verify", "check quality", "补测试"
+
+### When NOT to Use
+- Project has no test framework AND no code to test
+- Trivial single-line config changes
+
+## Precondition
+
+| Required State | Check | If Missing |
+|---|---|---|
+| `.prizmkit/prizm-docs/root.prizm` exists | File exists | Run `/prizmkit-init` first |
+| Test framework installed | Dependency in package.json or equivalent | Offer to skip or let user install one manually |
+
+If `.prizmkit/prizm-docs/` exists but may be stale (no retrospective run after recent changes), warn user: "Prizm docs may be out of date. Gap analysis accuracy depends on current docs. Continue anyway?"
+
+## Context Loading
+
+Before execution, load context once:
+
+1. **Architecture context**: Read `.prizmkit/prizm-docs/root.prizm` (L0 — project overview, module index, tech stack, conventions) and relevant L1 docs for modules in scope. If scope includes specific modules, also load relevant L2 docs for INTERFACES, DATA_FLOW, TRAPS, and DECISIONS.
+2. **Project config**: Read `.prizmkit/config.json` (tech stack, AI CLI config).
+3. **Dependencies**: Read `package.json` or equivalent to detect test framework and project type.
+
+## Input
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `scope` | No | User selects interactively in Phase 1. In headless mode, defaults to full project. |
+
+## Execution
+
+### Phase 0: Architecture Detection
+
+1. From context already loaded, classify project type:
+
+| Signal | Classification |
+|--------|---------------|
+| react/vue/angular/next in deps, no backend framework | Frontend |
+| express/fastify/django/flask in deps, no frontend framework | Backend |
+| Both present | Fullstack |
+| Neither clear | Ask user (headless: mark as "unknown", skip E2E) |
+
+2. Detect test framework by scanning dependencies:
+   - Jest → `npx jest` or `npm test`
+   - Vitest → `npx vitest run`
+   - pytest → `python -m pytest`
+   - Go testing → `go test ./...`
+   - Multiple frameworks found → use the one with the most test files; list all in report
+   - Custom `npm test` script → use `npm test`
+
+3. **Interactive mode**: Show "Detected: {type}, test framework: {name}. Correct?"
+   **Headless mode**: Auto-proceed with detected values, note assumptions in report.
+
+### Phase 1: Scope Selection
+
+**Interactive mode** — present three options:
+
+1. **Full project** — all modules, all specs in `.prizmkit/specs/`
+2. **Single module** — pick from L1 doc module names (e.g., "auth", "payment")
+3. **Single feature** — pick from `.prizmkit/specs/###-*/` directories
+
+**Headless mode** — default to full project. If `artifact_dir` or `scope` was passed by the caller, use that.
+
+### Phase 2: Run Existing Tests
+
+1. Find test directories matching common patterns: `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`. If no test files exist at all, note this and skip to Phase 3 (all coverage is "missing").
+
+2. Run the detected test command in scope. Capture:
+   - Pass/fail counts and failed test details
+   - Which test files exist (for gap analysis)
+   - Raw output (saved to report directory)
+
+3. If existing tests fail: record failures but continue — this is coverage data. Do not attempt to fix pre-existing test failures (they predate this session).
+
+### Phase 3: Coverage Gap Analysis
+
+Staleness of `.prizmkit/prizm-docs/` was already checked during Context Loading (see Precondition). Gap analysis proceeds with the available data.
+
+Compare what exists against what should exist, across three levels:
+
+**Unit test gaps** — for each module in scope:
+- Read the corresponding L2 `.prizm` doc INTERFACES section to get exported functions/classes. If no L2 doc exists for a module, analyze source files directly to identify exported functions/classes.
+- Check if each has a corresponding test file (match project's test naming: `foo.test.ts`, `foo.spec.ts`, `test_foo.py`)
+- Flag uncovered interfaces
+
+**Integration test gaps** (skip if project has no API/DB layer — pure library/CLI tool):
+- Read L1 doc DEPENDENCIES section for cross-module interactions
+- Check if tests exist covering module boundaries, API endpoints, DB operations
+- Flag missing integration coverage
+
+**E2E test gaps** (skip if project has no UI):
+- Collect acceptance criteria from all spec.md files in scope
+- Check existing E2E test files against these criteria
+- Flag uncovered criteria
+
+### Phase 4: Generate Missing Tests
+
+Generate tests in priority order: unit → integration → E2E. After each batch, run immediately.
+
+When generated tests fail, distinguish two cases:
+- **Test bug** (syntax error, wrong import, wrong mock, wrong framework API usage) → fix the test and re-run
+- **Assertion failure** (test is valid but code returns unexpected result) → mark as "needs review" in report; do NOT modify production code. This is a potential bug discovered by the generated test.
+
+If a test fails repeatedly after 2 fix attempts, skip it and mark as "unresolved" in the report.
+
+**4a. Unit Tests (always applicable)**
+
+For each uncovered interface:
+- Read the source file to understand function signature and logic
+- Generate test file matching project conventions (framework, naming, directory, import style, mock/fixture patterns)
+- Common naming patterns to match:
+  - `src/foo.ts` → `src/__tests__/foo.test.ts` or `src/foo.spec.ts` or `tests/foo_test.py`
+  - Mirror the existing pattern; if no tests exist, use the framework's default convention
+- Cover: happy path, edge cases (null/undefined/empty), error conditions, boundary values
+- Do NOT test framework internals or third-party library behavior
+- Run tests immediately after generating
+
+**4b. Integration Tests**
+
+For each module with dependencies:
+- Generate tests for the module's primary interface exercising its real dependencies
+- If API endpoints exist: request/response tests (valid input, invalid input, missing params, auth)
+- If database operations exist: CRUD tests using the project's existing test database config
+- Run tests immediately after generating
+
+**4c. E2E Tests (conditional)**
+
+Preconditions (ALL must be met):
+- Playwright is available (`@playwright/test` or `playwright` in package.json dependencies, or `npx playwright --version` succeeds as fallback)
+- Playwright browsers are installed (check `npx playwright install --dry-run 2>/dev/null` exits cleanly, or `node_modules/.cache/ms-playwright/` directory exists; if missing, warn in report and skip E2E)
+- Project has a UI layer
+- Project can be started (start/dev script in package.json)
+- Acceptance criteria exist in spec.md files
+
+If ALL met:
+- **Before starting dev server**: detect whether it's already running: (1) check `package.json` scripts for port flags (`--port`, `-p`, `PORT=`), (2) fall back to framework defaults (3000 for React/Next/Express, 5173 for Vite, 8000 for Django, 5000 for Flask), (3) if still unknown, ask the user. Use the detected port in `lsof -i :<port>` to check. If running, tell user: "Dev server appears to be already running on port {N}. Use this running instance for E2E tests?" If user confirms, use existing instance. If user declines, skip E2E.
+- Start the project dev server (only if not already running). Wait for it to be ready.
+- For each uncovered acceptance criterion, generate a Playwright test script
+- Run generated E2E tests, capture screenshots of failures
+- **Only stop dev server if you started it.** Never stop a server that was already running.
+
+If NOT met:
+- Note what was skipped and why in the report
+- If only the server wasn't startable: still generate E2E script files but mark as "not run — manual execution needed"
+
+### Phase 5: Unified Report
+
+Create `.prizmkit/test/{YYYY_MM_DD_HH_MM_SS}_testresult/` directory.
+
+**test-report.md** format:
+
+```markdown
+# Test Report — {timestamp}
+
+## Summary
+- Scope: {full / module: name / feature: ###-name}
+- Architecture: {frontend / backend / fullstack}
+- Test framework: {name}
+- Mode: {interactive / headless}
+
+## Existing Tests
+- Total: {N} | Passed: {N} | Failed: {N}
+{failed test details or "All passing"}
+{or "No existing tests found — generated first batch"}
+
+## Coverage Gaps Found
+| Module | Interface | Type | Status |
+|--------|-----------|------|--------|
+| ... | ... | unit/integration/e2e | covered / generated / needs-review / unresolved / skipped |
+
+## Generated Tests
+- Unit: {N} generated, {N} needs-review, {N} unresolved
+- Integration: {N} generated, {N} needs-review, {N} unresolved
+- E2E: {N} generated, {N} skipped ({reason})
+
+## Final Status
+- All tests passing: {yes / no}
+- Needs human review: {list of tests marked needs-review}
+{remaining failures if any}
+```
+
+Also save:
+- `existing-test-output.txt` — raw output from Phase 2
+- `generated-tests/` — copies of all generated test files
+- `e2e-output/` — E2E logs and failure screenshots (if applicable)
+
+## Output
+
+- Test report: `.prizmkit/test/{timestamp}_testresult/test-report.md`
+- Generated test files written to project test directories
+- Existing test output, generated test copies, and E2E artifacts in the report directory
+
+## Recovery
+
+If the session is interrupted:
+- Check `.prizmkit/test/` for the most recent report directory — it contains what was completed before interruption
+- Re-run `/prizmkit-test` — it starts fresh, but Phase 2 will skip tests that already pass, and Phase 3 will re-evaluate gaps
+
+## Examples
+
+### Example 1: Full-Project Quality Check with Test Generation
+
+**User**: `/prizmkit-test`
+
+**Phase 0 — Architecture Detection**:
+```
+Detected: Fullstack (React + Express)
+Test framework: Vitest (7 existing test files)
+```
+
+**Phase 1 — Scope Selection** (user selects option 1):
+```
+Scope: Full project (all modules, all specs)
+```
+
+**Phase 2 — Existing Tests**: 7 test files found, 20 tests run, 18 passed, 2 pre-existing failures (recorded, not fixed).
+
+**Phase 3 — Gap Analysis** (excerpt):
+| Module | Interface | Type | Status |
+|--------|-----------|------|--------|
+| auth | login() | unit | missing |
+| auth | register() | unit | missing |
+| payment | processPayment() | unit | missing |
+| payment | api/checkout | integration | missing |
+| — | Checkout flow | e2e | missing |
+
+**Phase 4**: Generated 5 unit tests (3 passing, 2 assertion failures marked "needs-review"), 1 integration test (passing), 1 E2E test (passing).
+
+**Phase 5 — Report Summary**:
+```
+Generated: 5 unit (2 needs-review), 1 integration, 1 E2E
+Report: .prizmkit/test/2026_05_23_14_30_00_testresult/test-report.md
+Needs human review: processPayment (returns 400 for negative amounts, expected 422), refund (missing authorization header causes 500 instead of 401)
+```
+
+### Example 2: Single-Feature Targeted Test
+
+**User**: `/prizmkit-test`
+
+**Phase 0 — Architecture Detection**:
+```
+Detected: Backend (Express)
+Test framework: Vitest
+```
+
+**Phase 1 — Scope Selection** (user selects option 3, then picks "042-payment-gateway"):
+```
+Scope: Single feature — 042-payment-gateway
+Test files in scope: 2
+
+**Phase 2 — Existing Tests**: 2 test files, 8 tests, all passing.
+
+**Phase 3 — Gap Analysis** (excerpt):
+| Module | Interface | Type | Status |
+|--------|-----------|------|--------|
+| payment | processPayment() | unit | missing |
+| payment | refund() | unit | missing |
+
+**Phase 4**: Generated 2 unit tests (both passing). No integration/E2E applicable for this scope.
+
+**Phase 5 — Report Summary**:
+```
+Generated: 2 unit tests (all passing)
+Report: .prizmkit/test/2026_05_23_15_00_00_testresult/test-report.md
+All tests passing. Ready for commit.
+```
+
+**HANDOFF:** Independent skill — no handoff. User may proceed to `/prizmkit-committer` if all tests pass, or fix issues manually if tests are marked "needs-review".

package/bundled/skills/refactor-planner/SKILL.md

@@ -293,12 +293,14 @@ If issues found, discuss with user and resolve before proceeding.
 
 **Goal**: Produce `.prizmkit/plans/refactor-list.json` and validate it.
 
-1. Generate `.prizmkit/plans/refactor-list.json` at `.prizmkit/plans/`
-2. Run validation:
+**IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
+1. Write a draft JSON to `.prizmkit/plans/refactor-list.draft.json` with all collected refactor data.
+2. Call the generate script to validate and produce the final file:
    ```bash
-   python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py validate --input .prizmkit/plans/refactor-list.json
+   python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
    ```
-3. If validation fails -> fix issues and re-validate (max 3 attempts)
+   The script fills in defaults (`$schema`, `created_at`, `created_by`), validates all fields, and writes the final file only if validation passes.
+3. If validation fails -> fix the draft and retry (max 3 attempts)
 4. If validation passes -> present final summary
 
 **CHECKPOINT CP-RP-6**: `.prizmkit/plans/refactor-list.json` generated and validated.
@@ -380,9 +382,12 @@ For simple refactoring with minimal scope:
    
    **NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
 3. Draft items (title + type + scope + description + acceptance_criteria + behavior_preservation + dependencies)
-4. Run validation script immediately
+4. Write draft to `.prizmkit/plans/refactor-list.draft.json`, then call the generate script:
+   ```bash
+   python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
+   ```
 5. If valid -> summarize and recommend next step
-6. If invalid -> apply fixes, re-validate (max 2 attempts, then escalate to full workflow)
+6. If invalid -> apply fixes to the draft, re-run generate (max 2 attempts, then escalate to full workflow)
 
 ### When NOT to Use Fast Path
 - More than 2 refactor items

package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py

@@ -6,11 +6,13 @@ for the dev-pipeline system.
 Commands:
   validate    Validate an existing .prizmkit/plans/refactor-list.json
   template    Generate a blank template .prizmkit/plans/refactor-list.json
+  generate    Validate a draft JSON and generate final refactor-list.json with defaults
   summary     Print a summary table of refactors from a .prizmkit/plans/refactor-list.json
 
 Usage:
   python3 validate-and-generate-refactor.py validate --input .prizmkit/plans/refactor-list.json [--output validated.json]
   python3 validate-and-generate-refactor.py template --output .prizmkit/plans/refactor-list.json
+  python3 validate-and-generate-refactor.py generate --input draft.json --output .prizmkit/plans/refactor-list.json
   python3 validate-and-generate-refactor.py summary --input .prizmkit/plans/refactor-list.json [--format markdown|json]
 
 Python 3.6+ required. No external dependencies.
@@ -22,6 +24,7 @@ import json
 import os
 import re
 import sys
+from datetime import datetime, timezone
 
 # ---------------------------------------------------------------------------
 # Constants
@@ -687,6 +690,61 @@ def cmd_template(args):
     return 0
 
 
+def cmd_generate(args):
+    """Handle the 'generate' command.
+
+    Loads a draft JSON (produced by AI), fills in defaults, validates,
+    and writes the final refactor-list.json.
+    """
+    if not args.input:
+        _err("--input is required for the generate command")
+        return 2
+    if not args.output:
+        _err("--output is required for the generate command")
+        return 2
+
+    # Load draft (supports stdin via '-')
+    if args.input == "-":
+        try:
+            data = json.load(sys.stdin)
+        except json.JSONDecodeError as exc:
+            _err("Invalid JSON from stdin: {}".format(exc))
+            return 2
+    else:
+        data, load_err = _load_json(args.input)
+        if load_err:
+            _err(load_err)
+            return 2
+
+    # Fill in defaults
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    data.setdefault("$schema", SCHEMA_VERSION)
+    data.setdefault("created_at", now)
+    data.setdefault("created_by", "refactor-planner")
+
+    # Set default status for refactors without one
+    for refactor in data.get("refactors", []):
+        refactor.setdefault("status", "pending")
+
+    # Validate
+    result = validate_refactor_list(data)
+
+    # Output validation result
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+    if result["valid"]:
+        _write_json(args.output, data)
+        _info("Generated refactor-list written to {}".format(args.output))
+        return 0
+    else:
+        _err("Validation failed with {} error(s)".format(len(result["errors"])))
+        for e in result["errors"]:
+            _err("  " + e)
+        for w in result.get("warnings", []):
+            _warn("  " + w)
+        return 1
+
+
 def cmd_summary(args):
     """Handle the 'summary' command."""
     if not args.input:
@@ -719,6 +777,7 @@ def main():
             "  %(prog)s validate --input .prizmkit/plans/refactor-list.json\n"
             "  %(prog)s validate --input .prizmkit/plans/refactor-list.json --output validated.json\n"
             "  %(prog)s template --output .prizmkit/plans/refactor-list.json\n"
+            "  %(prog)s generate --input draft.json --output .prizmkit/plans/refactor-list.json\n"
             "  %(prog)s summary --input .prizmkit/plans/refactor-list.json\n"
             "  %(prog)s summary --input .prizmkit/plans/refactor-list.json --format json\n"
         ),
@@ -747,6 +806,18 @@ def main():
         "--output", required=True, help="Path to write template file"
     )
 
+    # -- generate --
+    p_generate = subparsers.add_parser(
+        "generate",
+        help="Validate a draft and generate final refactor-list.json with defaults",
+    )
+    p_generate.add_argument(
+        "--input", required=True, help="Path to draft JSON (or '-' for stdin)"
+    )
+    p_generate.add_argument(
+        "--output", required=True, help="Path to write final refactor-list.json"
+    )
+
     # -- summary --
     p_summary = subparsers.add_parser(
         "summary",
@@ -771,6 +842,7 @@ def main():
     dispatch = {
         "validate": cmd_validate,
         "template": cmd_template,
+        "generate": cmd_generate,
         "summary": cmd_summary,
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.1.48",
+  "version": "1.1.51",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {

package/src/scaffold.js

@@ -769,6 +769,11 @@ export async function installPlaywrightCli(projectRoot, dryRun) {
   try {
     execSync('playwright-cli install --skills', { cwd: projectRoot, stdio: 'pipe', timeout: 60000 });
     console.log(chalk.green('      ✓ playwright-cli skills installed'));
+    // playwright-cli creates an empty .playwright directory — remove it
+    const dotPlaywright = path.join(projectRoot, '.playwright');
+    if (fs.pathExistsSync(dotPlaywright)) {
+      fs.removeSync(dotPlaywright);
+    }
   } catch (e) {
     console.log(chalk.yellow(`      ⚠ Skills install skipped: ${e.message}`));
     console.log(chalk.yellow('      ⚠ Run manually: playwright-cli install --skills'));