spec-gen-cli 1.2.6 → 1.2.8

package/examples/cline-workflows/spec-gen-plan-refactor.md

@@ -0,0 +1,255 @@
+# spec-gen: Plan Refactor
+
+Identify the highest-priority refactoring target using static analysis, assess
+its blast radius, and produce a detailed written plan — saved to
+`.spec-gen/refactor-plan.md` — that `/spec-gen-execute-refactor` can follow
+step by step without losing context.
+
+This workflow makes **no code changes**. It only reads and writes the plan file.
+
+## Step 1: Confirm the project directory
+
+Ask the user which project to analyse, or confirm the current workspace root.
+
+<ask_followup_question>
+  <question>Which project directory should I plan the refactor for?</question>
+  <options>["Current workspace root", "Enter a different path"]</options>
+</ask_followup_question>
+
+## Step 2: Run static analysis
+
+Analyse the project. If analysis already ran recently, skip unless the user
+requests a fresh run.
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>analyze_codebase</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+## Step 3: Get the full refactoring report
+
+Retrieve the prioritised list of functions with structural issues.
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_refactor_report</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+Present the top 5 candidates in a table: function, file, issues, priority score.
+
+## Step 3b: Check for duplicate code (optional enrichment)
+
+Call `get_duplicate_report` to surface clones that overlap with the top candidates.
+If the target function (or any callee) appears in a clone group, note it in the plan:
+consolidated duplicates reduce blast radius before extracting logic.
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_duplicate_report</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+If a top candidate appears in a clone group, prepend a **Deduplication note** to the plan:
+> "⚠️ `<function>` has N near-clones. Consolidate them first to reduce the blast radius
+> of this refactor."
+
+Before asking the user to pick a target, **check test coverage for the files
+containing the top candidates**. Detect the coverage tool from the project
+(look for `package.json` scripts, `pytest.ini`, `Cargo.toml`, `go.mod`, etc.)
+and run it scoped to those files only:
+
+- Node.js → `npm test -- --coverage --collectCoverageFrom="<files>"`
+- Python  → `pytest --cov=<module> --cov-report=term-missing`
+- Rust    → `cargo tarpaulin --include-files <files>`
+- Go      → `go test -cover ./...` (filter relevant packages)
+
+For each candidate file, present a compact coverage badge:
+
+| Function | File | Priority | Coverage |
+|---|---|---|---|
+| ... | ... | ... | 72% ✅ / 35% ⚠️ / 0% 🚫 |
+
+Apply these thresholds to annotate each row:
+
+| Coverage | Badge | Meaning |
+|---|---|---|
+| ≥ 70% lines | ✅ | Safe to refactor |
+| 40–69% lines | ⚠️ | Write characterisation tests first |
+| < 40% lines | 🛑 | Strongly discouraged — recommend tests first |
+| 0% (no tests) | 🚫 | Blocked — propose a test harness before proceeding |
+
+If **all top candidates are below 40%**, tell the user:
+> "Every high-priority target has insufficient test coverage (< 40%). Refactoring
+> without tests risks introducing silent regressions. I recommend writing a
+> minimal test harness for at least one target before proceeding. Would you like
+> me to suggest test cases based on the function signatures?"
+
+Then ask the user which one to tackle first, or pick the top one by default.
+Prefer candidates with higher coverage when scores are otherwise close.
+
+## Step 4: Assess impact
+
+For the chosen function, get the full impact analysis.
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>analyze_impact</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "symbol": "$FUNCTION_NAME"}</arguments>
+</use_mcp_tool>
+
+Note:
+- Risk score (0–100) and what it means
+- Recommended strategy (extract / split / facade / delegate)
+- Upstream callers and downstream callees (keep the top 5 of each for the plan)
+
+## Step 5: Visualise the call neighbourhood
+
+Render the subgraph to map callers and callees precisely.
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_subgraph</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "functionName": "$FUNCTION_NAME", "direction": "both", "format": "mermaid"}</arguments>
+</use_mcp_tool>
+
+Show the Mermaid diagram to the user.
+
+## Step 6: Find safe entry points
+
+Identify low-risk leaf functions that can be extracted first (bottom-up).
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_low_risk_refactor_candidates</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "filePattern": "$TARGET_FILE", "limit": 5}</arguments>
+</use_mcp_tool>
+
+Cross-reference with the subgraph from Step 5: a candidate is a good first
+extraction if it already appears as a callee of the target function.
+
+## Step 6b: Find insertion points for extracted helpers
+
+Before designing the change sequence, identify where extracted functions should land.
+This avoids creating helpers in the wrong file or layer.
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>suggest_insertion_points</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "query": "extract helper from $FUNCTION_NAME", "limit": 5}</arguments>
+</use_mcp_tool>
+
+For each candidate returned, note its role (entry_point / orchestrator / hub / utility / internal)
+and the suggested strategy. Cross-reference with the subgraph from Step 5: prefer candidates
+that already call into — or are called by — the target function.
+
+## Step 7: Design the change sequence
+
+Based on the recommended strategy from Step 4, design an ordered sequence of
+atomic changes. Each change must specify:
+
+- **What**: the exact block of logic to move (line range or description)
+- **New name**: the function or method name to give it
+- **Target file**: the file where it will live after the move
+  - If the logic belongs to an existing module: name that file
+  - If no suitable module exists: propose a new file path (e.g.
+    `src/services/validation.ts`) and justify the choice
+- **Target class** (if applicable): the class or namespace to place it in
+- **Callers to update**: list every call site that will need updating
+
+For each strategy, apply these rules:
+
+- **split**: decompose the function into N sub-functions; each sub-function
+  stays in the same file unless it clearly belongs elsewhere
+- **extract**: pull out a helper; place it in the nearest cohesive module or
+  create a new file if none exists
+- **facade**: keep the original signature, delegate body to smaller functions;
+  create a private companion module if the file would exceed 300 lines
+- **delegate**: move ownership logic to callers; update each caller file listed
+  in the upstream chain
+
+Present the full change sequence to the user for review and ask for confirmation
+before writing the plan file.
+
+## Step 8: Write the plan file
+
+Create `.spec-gen/refactor-plan.md` in the project directory with the following
+structure (fill every section — leave nothing as "TBD"):
+
+```markdown
+# Refactor Plan
+
+Generated: <ISO date>
+Workflow: /spec-gen-plan-refactor → /spec-gen-execute-refactor
+
+## Target
+
+- **Function**: <name>
+- **File**: <relative path>
+- **Lines**: <start>–<end>  (read the file to confirm)
+- **Risk score**: <0–100>
+- **Strategy**: <extract | split | facade | delegate>
+- **Priority score before refactor**: <value>
+
+## Why
+
+- <issue 1 from refactor report>
+- <issue 2>
+- ...
+
+## Callers (upstream — must not break)
+
+| Caller | File |
+|---|---|
+| <name> | <path> |
+
+## Callees (downstream — candidates for extraction)
+
+| Callee | File |
+|---|---|
+| <name> | <path> |
+
+## Coverage baseline
+
+- **File**: <target file>
+- **Coverage**: <X>% lines, <Y>% branches
+- **Status**: ✅ safe / ⚠️ caution / 🛑 discouraged
+- **Test command**: <exact command to run>
+
+## Change sequence
+
+Apply in order. Do not skip ahead. Run tests after each step.
+
+### Change 1 — <short label>
+
+- **What**: extract lines <start>–<end> (logic: <one-line description>)
+- **New function name**: `<name>`
+- **Target file**: `<path>` (<new file | existing file — reason>)
+- **Target class**: `<ClassName>` or none
+- **Call sites to update**: <list each file:line>
+- **Expected diff**: +<N> lines in <new/existing file>, -<M> lines in <source file>
+
+### Change 2 — <short label>
+
+...
+
+## Acceptance criteria
+
+- Priority score drops below <target score> in `get_refactor_report`
+- Function exits the top-5 list
+- Full test suite passes (green)
+- `git diff --stat` shows only the expected files
+
+## Restore point
+
+Run before starting execute:
+```bash
+git log --oneline -1
+```
+Note the hash here: <to be filled by execute workflow>
+```
+
+Once the file is written, tell the user:
+> "Plan written to `.spec-gen/refactor-plan.md`. Review it, then run
+> `/spec-gen-execute-refactor` to apply the changes."

package/examples/cline-workflows/spec-gen-refactor-codebase.md

@@ -0,0 +1,16 @@
+# spec-gen: Refactor Codebase (redirected)
+
+This workflow has been split into two focused workflows for better reliability
+with limited models:
+
+- **`/spec-gen-plan-refactor`** — static analysis, impact assessment, and
+  written plan saved to `.spec-gen/refactor-plan.md` (no code changes)
+- **`/spec-gen-execute-refactor`** — reads the plan and applies changes
+  incrementally, with tests after each step
+
+Tell the user:
+> "The `/spec-gen-refactor-codebase` workflow has been split. Please use:
+> 1. `/spec-gen-plan-refactor` to analyse the codebase and write a plan
+> 2. `/spec-gen-execute-refactor` to apply the plan
+>
+> This two-step approach is more reliable, especially with smaller models."

package/examples/drift-demo/openspec/config.yaml

@@ -0,0 +1,14 @@
+schema: spec-driven
+context: |
+  TaskFlow — a task management REST API built with Express.js and PostgreSQL.
+  
+  Tech stack: TypeScript, Express.js, PostgreSQL, JWT auth, bcrypt
+  Architecture: Layered (routes → services → database)
+
+spec-gen:
+  generatedAt: "2025-06-15T00:00:00.000Z"
+  domains:
+    - auth
+    - tasks
+    - projects
+    - database

package/examples/drift-demo/openspec/specs/architecture/spec.md

@@ -0,0 +1,30 @@
+# Architecture Specification
+
+> Generated by spec-gen v1.0.0 on 2025-06-15
+
+## Purpose
+
+Describes the overall system architecture and how components interact.
+
+## Requirements
+
+### Requirement: LayeredArchitecture
+
+The system SHALL follow a three-layer architecture:
+1. **Routes** (Express routers) handle HTTP concerns
+2. **Services** contain business logic
+3. **Database** handles persistence
+
+### Requirement: EntryPoint
+
+The system SHALL expose a single entry point (`src/index.ts`) that mounts all route
+modules and starts an Express server on PORT (default 3000).
+
+### Requirement: HealthEndpoint
+
+The system SHALL expose a public GET /health endpoint returning `{ "status": "ok" }`.
+
+## Technical Notes
+
+- **Implementation**: `src/index.ts`
+- **Dependencies**: express

package/examples/drift-demo/openspec/specs/auth/spec.md

@@ -0,0 +1,71 @@
+# Auth Specification
+
+> Generated by spec-gen v1.0.0 on 2025-06-15
+> Source files: src/auth/auth-service.ts, src/auth/auth-middleware.ts, src/auth/auth-routes.ts
+
+## Purpose
+
+Handles user authentication (login, registration, JWT management) and request-level
+authorization via middleware.
+
+## Requirements
+
+### Requirement: UserLogin
+
+The system SHALL authenticate users by email and password, returning a signed JWT on success.
+
+#### Scenario: SuccessfulLogin
+- **GIVEN** a registered user with email "alice@test.com" and a valid password
+- **WHEN** POST /api/auth/login is called with those credentials
+- **THEN** the system returns a JWT token, expiry time, and userId with status 200
+
+#### Scenario: InvalidCredentials
+- **GIVEN** an incorrect password
+- **WHEN** POST /api/auth/login is called
+- **THEN** the system returns status 401 with error "Invalid credentials"
+
+#### Scenario: MissingFields
+- **GIVEN** a request body without email or password
+- **WHEN** POST /api/auth/login is called
+- **THEN** the system returns status 400 with error "Email and password required"
+
+### Requirement: UserRegistration
+
+The system SHALL register new users with email, password, and name, hashing the password with bcrypt (cost factor 12).
+
+#### Scenario: SuccessfulRegistration
+- **GIVEN** a unique email "bob@test.com"
+- **WHEN** POST /api/auth/register is called
+- **THEN** the system creates the user and returns a JWT with status 201
+
+#### Scenario: DuplicateEmail
+- **GIVEN** an email that already exists
+- **WHEN** POST /api/auth/register is called
+- **THEN** the system returns status 409 with error "Email already registered"
+
+### Requirement: JWTTokenManagement
+
+The system SHALL sign tokens with a configurable secret (JWT_SECRET env var, defaulting to "dev-secret") and 24-hour expiry.
+
+### Requirement: RequestAuthorization
+
+The system SHALL protect routes via `requireAuth` middleware that validates Bearer tokens and injects `userId` and `userRole` into the request.
+
+#### Scenario: MissingToken
+- **GIVEN** a request without an Authorization header
+- **WHEN** the request reaches a protected route
+- **THEN** the system returns status 401 with error "Missing authorization header"
+
+#### Scenario: ExpiredToken
+- **GIVEN** a request with an expired JWT
+- **WHEN** the request reaches a protected route
+- **THEN** the system returns status 401 with error "Invalid or expired token"
+
+### Requirement: RoleBasedAccess
+
+The system SHALL support role-based access control via `requireRole` middleware that checks `userRole` against a required role.
+
+## Technical Notes
+
+- **Implementation**: `src/auth/auth-service.ts`, `src/auth/auth-middleware.ts`, `src/auth/auth-routes.ts`
+- **Dependencies**: jsonwebtoken, bcrypt

package/examples/drift-demo/openspec/specs/database/spec.md

@@ -0,0 +1,33 @@
+# Database Specification
+
+> Generated by spec-gen v1.0.0 on 2025-06-15
+> Source files: src/database/connection.ts
+
+## Purpose
+
+Manages PostgreSQL connection pooling and provides a health check endpoint.
+
+## Requirements
+
+### Requirement: ConnectionPooling
+
+The system SHALL maintain a PostgreSQL connection pool with max 20 connections and 30-second idle timeout.
+
+### Requirement: HealthCheck
+
+The system SHALL expose a health check function that verifies database connectivity by executing `SELECT 1`.
+
+#### Scenario: HealthyDatabase
+- **GIVEN** a running PostgreSQL instance
+- **WHEN** healthCheck is called
+- **THEN** the function returns true
+
+#### Scenario: UnhealthyDatabase
+- **GIVEN** a down PostgreSQL instance
+- **WHEN** healthCheck is called
+- **THEN** the function returns false
+
+## Technical Notes
+
+- **Implementation**: `src/database/connection.ts`
+- **Dependencies**: pg (node-postgres)

package/examples/drift-demo/openspec/specs/overview/spec.md

@@ -0,0 +1,20 @@
+# System Overview
+
+> Generated by spec-gen v1.0.0 on 2025-06-15
+
+## Purpose
+
+TaskFlow is a task management REST API that enables teams to organize work into
+projects and tasks with role-based access control and real-time status tracking.
+
+## Domains
+
+- **auth**: Authentication (login, registration, JWT tokens) and authorization (role-based middleware)
+- **tasks**: Task CRUD operations, status transitions, filtering, and assignment
+- **projects**: Project management, membership, and archival
+- **database**: PostgreSQL connection pooling and health checks
+
+## API Surface
+
+All endpoints live under `/api/` and require Bearer token authentication except
+`/api/auth/login`, `/api/auth/register`, and `/health`.

package/examples/drift-demo/openspec/specs/projects/spec.md

@@ -0,0 +1,55 @@
+# Projects Specification
+
+> Generated by spec-gen v1.0.0 on 2025-06-15
+> Source files: src/projects/project-model.ts, src/projects/project-service.ts
+
+## Purpose
+
+Manages projects that group tasks together, including membership and archival.
+
+## Entities
+
+### Project
+
+| Property | Type | Description |
+|----------|------|-------------|
+| id | string | Unique project identifier (format: proj_{timestamp}) |
+| name | string | Project name (required, trimmed) |
+| description | string | Description (defaults to "") |
+| ownerId | string | User who created the project |
+| members | string[] | User IDs with access (owner is auto-added) |
+| isArchived | boolean | Whether the project is archived |
+
+## Requirements
+
+### Requirement: ProjectCreation
+
+The system SHALL create projects with a required name, auto-adding the creator as owner and first member.
+
+#### Scenario: ValidCreation
+- **GIVEN** a valid project name
+- **WHEN** createProject is called
+- **THEN** the system creates the project with the creator as owner and member
+
+### Requirement: ProjectMembership
+
+The system SHALL allow adding members to a project, preventing duplicate membership.
+
+#### Scenario: DuplicateMember
+- **GIVEN** a user who is already a member
+- **WHEN** addMember is called
+- **THEN** the system throws "User is already a member"
+
+### Requirement: ProjectArchival
+
+The system SHALL allow only the project owner to archive a project.
+
+#### Scenario: NonOwnerArchival
+- **GIVEN** a user who is not the project owner
+- **WHEN** archiveProject is called
+- **THEN** the system throws "Only the owner can archive a project"
+
+## Technical Notes
+
+- **Implementation**: `src/projects/project-model.ts`, `src/projects/project-service.ts`
+- **Dependencies**: auth domain

package/examples/drift-demo/openspec/specs/tasks/spec.md

@@ -0,0 +1,78 @@
+# Tasks Specification
+
+> Generated by spec-gen v1.0.0 on 2025-06-15
+> Source files: src/tasks/task-model.ts, src/tasks/task-service.ts, src/tasks/task-routes.ts
+
+## Purpose
+
+Manages the full lifecycle of tasks: creation, retrieval, updates (including status
+transitions), deletion, and filtered listing within projects.
+
+## Entities
+
+### Task
+
+| Property | Type | Description |
+|----------|------|-------------|
+| id | string | Unique task identifier (format: task_{timestamp}) |
+| title | string | Task title (required, trimmed) |
+| description | string | Detailed description (defaults to "") |
+| status | TaskStatus | One of: todo, in_progress, done, cancelled |
+| priority | TaskPriority | One of: low, medium, high, urgent |
+| assigneeId | string \| null | User ID of assignee |
+| projectId | string | Parent project ID (required) |
+| createdBy | string | User ID of creator |
+| dueDate | Date \| null | Optional due date |
+| tags | string[] | User-defined tags |
+
+## Requirements
+
+### Requirement: TaskCreation
+
+The system SHALL create tasks with a required title and projectId, defaulting status to "todo" and priority to "medium".
+
+#### Scenario: ValidCreation
+- **GIVEN** a valid title and projectId
+- **WHEN** POST /api/tasks is called
+- **THEN** the system creates the task with default status "todo" and returns it with status 201
+
+#### Scenario: MissingTitle
+- **GIVEN** a request body without a title
+- **WHEN** POST /api/tasks is called
+- **THEN** the system returns status 400 with error "Task title is required"
+
+### Requirement: TaskStatusTransitions
+
+The system SHALL enforce valid status transitions:
+- todo → in_progress, cancelled
+- in_progress → done, todo, cancelled
+- done → todo
+- cancelled → todo
+
+#### Scenario: ValidTransition
+- **GIVEN** a task with status "todo"
+- **WHEN** the status is updated to "in_progress"
+- **THEN** the transition succeeds
+
+#### Scenario: InvalidTransition
+- **GIVEN** a task with status "todo"
+- **WHEN** the status is updated to "done"
+- **THEN** the system throws "Cannot transition from todo to done"
+
+### Requirement: TaskCRUD
+
+The system SHALL support Get, Update (PATCH), Delete, and List operations for tasks. All task routes require authentication.
+
+#### Scenario: TaskNotFound
+- **GIVEN** a non-existent task ID
+- **WHEN** GET /api/tasks/:id is called
+- **THEN** the system returns status 404
+
+### Requirement: TaskFiltering
+
+The system SHALL support filtering tasks by projectId (required), status, and assigneeId via query parameters.
+
+## Technical Notes
+
+- **Implementation**: `src/tasks/task-model.ts`, `src/tasks/task-service.ts`, `src/tasks/task-routes.ts`
+- **Dependencies**: auth domain (requireAuth middleware)

package/examples/drift-demo/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "taskflow-api",
+  "version": "2.1.0",
+  "description": "Task management REST API — brownfield Express.js app",
+  "main": "src/index.ts",
+  "scripts": {
+    "dev": "ts-node src/index.ts",
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "jsonwebtoken": "^9.0.0",
+    "bcrypt": "^5.1.0",
+    "pg": "^8.11.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  }
+}

package/examples/drift-demo/src/auth/auth-middleware.ts

@@ -0,0 +1,30 @@
+import type { Request, Response, NextFunction } from 'express';
+import { AuthService } from './auth-service.js';
+
+const authService = new AuthService();
+
+export function requireAuth(req: Request, res: Response, next: NextFunction) {
+  const header = req.headers.authorization;
+  if (!header?.startsWith('Bearer ')) {
+    return res.status(401).json({ error: 'Missing authorization header' });
+  }
+
+  const token = header.slice(7);
+  const payload = authService.verifyToken(token);
+  if (!payload) {
+    return res.status(401).json({ error: 'Invalid or expired token' });
+  }
+
+  (req as any).userId = payload.userId;
+  (req as any).userRole = payload.role;
+  next();
+}
+
+export function requireRole(role: string) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    if ((req as any).userRole !== role) {
+      return res.status(403).json({ error: 'Insufficient permissions' });
+    }
+    next();
+  };
+}

package/examples/drift-demo/src/auth/auth-routes.ts

@@ -0,0 +1,29 @@
+import { Router } from 'express';
+import { AuthService } from './auth-service.js';
+
+const router = Router();
+const authService = new AuthService();
+
+router.post('/login', async (req, res) => {
+  try {
+    const { email, password } = req.body;
+    if (!email || !password) return res.status(400).json({ error: 'Email and password required' });
+    const result = await authService.login(email, password);
+    res.json(result);
+  } catch (err: any) {
+    res.status(401).json({ error: err.message });
+  }
+});
+
+router.post('/register', async (req, res) => {
+  try {
+    const { email, password, name } = req.body;
+    if (!email || !password || !name) return res.status(400).json({ error: 'All fields required' });
+    const result = await authService.register(email, password, name);
+    res.status(201).json(result);
+  } catch (err: any) {
+    res.status(409).json({ error: err.message });
+  }
+});
+
+export { router as authRouter };