openlore 2.0.0

package/examples/cline-workflows/openlore-write-tests.md

@@ -0,0 +1,177 @@
+# openlore: Write Tests
+
+Write real tests for a function or spec scenario — language-agnostic (TypeScript, Python, C++…).
+Reads the implementation and spec contract first, runs tests, fixes failures.
+
+**No stubs. No placeholder assertions. No `expect(true).toBe(true)`.**
+
+Steps 1–3 are read-only. No test is written before Step 4.
+
+---
+
+## Step 1: Get the project directory and target
+
+<ask_followup_question>
+  <question>What would you like to test?</question>
+  <options>[
+    "A specific function or file (I'll provide the name)",
+    "Find untested spec scenarios automatically",
+    "All untested scenarios in a domain"
+  ]</options>
+</ask_followup_question>
+
+Ask for `$PROJECT_ROOT` if not already known.
+
+**If "Find untested scenarios" or "All untested in a domain":**
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_test_coverage</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+
+Present the top 5 uncovered scenarios to the user. Ask which to implement first. Store the
+chosen scenario as `$TARGET`.
+
+**Detect the test framework** by scanning for config files:
+
+| File | Framework | Runner |
+|---|---|---|
+| `vitest.config.*` | Vitest | `npx vitest run <file>` |
+| `jest.config.*` | Jest | `npx jest <file>` |
+| `pytest.ini`, `pyproject.toml` (`[tool.pytest]`) | pytest | `pytest <file> -v` |
+| `CMakeLists.txt` with `enable_testing()` | CTest/GTest | build + `ctest` |
+| `go.mod` | Go test | `go test ./...` |
+
+Store as `$TEST_RUNNER`.
+
+---
+
+## Step 2: Orient
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>orient</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "task": "write tests for $TARGET",
+    "limit": 5
+  }</arguments>
+</use_mcp_tool>
+
+From the result, note:
+- `$TARGET_FILE` — file containing the function(s) to test
+- `$EXISTING_TEST_FILE` — nearby test file if any (`foo.test.ts`, `test_foo.py`, `foo_test.go`)
+- `$SPEC_DOMAIN` — the spec domain associated with the target
+
+---
+
+## Step 3: Read implementation + spec contract
+
+**Do not write any test before completing this step.**
+
+### 3a — Read the function body
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_function_body</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "symbol": "$TARGET_FUNCTION",
+    "filePath": "$TARGET_FILE"
+  }</arguments>
+</use_mcp_tool>
+
+Identify: inputs, return value, external dependencies to mock, invariants (guards, throws, early returns).
+
+### 3b — Find the spec contract
+
+If `openspec/specs/` exists:
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>search_specs</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "query": "$TARGET — expected behaviour",
+    "limit": 5
+  }</arguments>
+</use_mcp_tool>
+
+For each matching spec scenario, note the **GIVEN / WHEN / THEN** clauses — these become the
+test body. The scenario name becomes the test description (`it()` / `def test_` / `TEST()`).
+
+If no specs exist, infer the contract from the function signature, docstring, and call sites.
+Document the inferred contract in a comment before the first test.
+
+### 3c — Absorb local test conventions
+
+Read `$EXISTING_TEST_FILE` if it exists (or the closest test file in the project tree). Extract:
+- Mock setup pattern (`vi.mock`, `unittest.mock.patch`, `gmock`, etc.)
+- Fixture or factory helpers already defined
+- Import path style and suite structure
+
+---
+
+## Step 4: Write tests
+
+Write (or append to) `$EXISTING_TEST_FILE`. Create it next to the source file if it doesn't exist
+(`<name>.test.ts` / `test_<name>.py` / `<name>_test.go`).
+
+### Mandatory rules
+
+- **No placeholder assertions** — every assertion must test a real return value or side effect
+- **One test = one scenario** — `it()` / `def test_` description = spec scenario name or contract statement
+- **Annotation tag** — place immediately above each `describe` / class / suite block:
+  - TS/JS: `// openlore: {"domain":"$DOMAIN","requirement":"$REQ","scenario":"$SCENARIO","specFile":"openspec/specs/$DOMAIN/spec.md"}`
+  - Python: `# openlore: {"domain":"$DOMAIN","requirement":"$REQ","scenario":"$SCENARIO"}`
+  - C++/Go: `// openlore: {"domain":"$DOMAIN","requirement":"$REQ","scenario":"$SCENARIO"}`
+  - Omit if no spec scenario exists (contract inferred from implementation)
+- **Mock only system boundaries** — filesystem, network, LLM API, DB, external process. Not pure helpers
+- **One suite per function** — `describe` / class / suite named after the function
+- **At least one edge case** per function — empty input, null, max value, or error path
+
+---
+
+## Step 5: Run and fix
+
+Run:
+
+```
+$TEST_RUNNER $TEST_FILE_PATH
+```
+
+Repeat until all tests pass.
+
+| Outcome | Action |
+|---|---|
+| All green | Proceed to Step 6 |
+| Failure in new test | Fix assertion if expectation was wrong. If a real bug is revealed, report it — do not weaken the assertion |
+| Failure in pre-existing test | Fix the regression before adding more tests |
+| Compile / import error | Fix mock setup or import path before retrying |
+
+---
+
+## Step 6: Coverage report
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_test_coverage</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+
+Report:
+- Spec scenarios now covered (new)
+- Remaining uncovered scenarios in `$SPEC_DOMAIN`
+- High-value next targets (hub functions still untested)
+
+---
+
+## Absolute constraints
+
+- Never write `expect(true).toBe(true)`, `assert True`, or equivalent placeholder assertions
+- Never skip Step 3 — implementation read and spec contract are the test source of truth
+- Never mock the function under test itself
+- Never weaken an assertion to make a test pass — fix the implementation or the expectation
+- If `get_test_coverage` shows the scenario is already covered, report it and stop
+- Do not refactor the implementation as part of this workflow — open a separate task

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)
+
+openlore:
+  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 openlore 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 openlore 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 openlore 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 openlore 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 openlore 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 openlore 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 };

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

@@ -0,0 +1,45 @@
+import bcrypt from 'bcrypt';
+import jwt from 'jsonwebtoken';
+
+const JWT_SECRET = process.env.JWT_SECRET || 'dev-secret';
+
+export interface AuthResult {
+  token: string;
+  expiresIn: number;
+  userId: string;
+}
+
+export class AuthService {
+  async login(email: string, password: string): Promise<AuthResult> {
+    const user = await this.findUserByEmail(email);
+    if (!user) throw new Error('User not found');
+
+    const valid = await bcrypt.compare(password, user.passwordHash);
+    if (!valid) throw new Error('Invalid credentials');
+
+    const token = jwt.sign({ userId: user.id, role: user.role }, JWT_SECRET, { expiresIn: '24h' });
+    return { token, expiresIn: 86400, userId: user.id };
+  }
+
+  async register(email: string, password: string, name: string): Promise<AuthResult> {
+    const existing = await this.findUserByEmail(email);
+    if (existing) throw new Error('Email already registered');
+
+    const passwordHash = await bcrypt.hash(password, 12);
+    const user = await this.createUser({ email, passwordHash, name, role: 'user' });
+
+    const token = jwt.sign({ userId: user.id, role: user.role }, JWT_SECRET, { expiresIn: '24h' });
+    return { token, expiresIn: 86400, userId: user.id };
+  }
+
+  verifyToken(token: string): { userId: string; role: string } | null {
+    try {
+      return jwt.verify(token, JWT_SECRET) as { userId: string; role: string };
+    } catch {
+      return null;
+    }
+  }
+
+  private async findUserByEmail(email: string) { return null as any; }
+  private async createUser(data: any) { return { id: 'new-id', ...data }; }
+}

package/examples/drift-demo/src/database/connection.ts

@@ -0,0 +1,27 @@
+import { Pool } from 'pg';
+
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL || 'postgresql://localhost:5432/taskflow',
+  max: 20,
+  idleTimeoutMillis: 30000,
+});
+
+export async function query(sql: string, params?: any[]) {
+  const client = await pool.connect();
+  try {
+    return await client.query(sql, params);
+  } finally {
+    client.release();
+  }
+}
+
+export async function healthCheck(): Promise<boolean> {
+  try {
+    await query('SELECT 1');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export { pool };

package/examples/drift-demo/src/index.ts

@@ -0,0 +1,16 @@
+import express from 'express';
+import { authRouter } from './auth/auth-routes.js';
+import { taskRouter } from './tasks/task-routes.js';
+
+const app = express();
+app.use(express.json());
+
+app.use('/api/auth', authRouter);
+app.use('/api/tasks', taskRouter);
+
+app.get('/health', (_, res) => res.json({ status: 'ok' }));
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => console.log(`TaskFlow API listening on port ${PORT}`));
+
+export { app };

package/examples/drift-demo/src/projects/project-model.ts

@@ -0,0 +1,15 @@
+export interface Project {
+  id: string;
+  name: string;
+  description: string;
+  ownerId: string;
+  members: string[];
+  createdAt: Date;
+  updatedAt: Date;
+  isArchived: boolean;
+}
+
+export interface CreateProjectInput {
+  name: string;
+  description?: string;
+}