@eddacraft/anvil-aps 0.1.0

package/examples/refactor-error-handling.aps.md

@@ -0,0 +1,119 @@
+# Refactor: API Error Handling
+
+**Scope:** API **Owner:** @engineering-team **Priority:** high
+
+> Standardise error handling across all API endpoints with consistent response
+> format, logging, and monitoring.
+
+## Tasks
+
+### API-001: Audit current error handling patterns
+
+**Intent:** Survey all endpoints to document current error handling approaches
+and inconsistencies **Expected Outcome:** Report listing error patterns, missing
+cases, and inconsistency examples **Confidence:** low **Scopes:** API, AUTH,
+PROD, CART, PAY **Tags:** audit, research, documentation **Inputs:**
+
+- Access to all API endpoint code
+- Error logs from production (last 30 days)
+
+### API-002: Design unified error response schema
+
+**Intent:** Define standard error response format with codes, messages, and
+metadata **Expected Outcome:** Error schema documented with examples for common
+cases (validation, auth, not found, server error) **Confidence:** medium
+**Scopes:** API **Tags:** design, schema, standards **Dependencies:** API-001
+
+### API-003: Create base error classes
+
+**Intent:** Implement error class hierarchy (ApiError, ValidationError,
+AuthError, NotFoundError, etc.) **Expected Outcome:** Error classes with proper
+inheritance, serialisation, and HTTP status mapping **Confidence:** high
+**Scopes:** API **Tags:** errors, classes, core **Dependencies:** API-002
+
+### API-004: Implement global error middleware
+
+**Intent:** Create Express error middleware that catches all errors and formats
+responses **Expected Outcome:** Middleware handling all error types with
+logging, status codes, and response formatting **Confidence:** medium
+**Scopes:** API **Tags:** middleware, errors, express **Dependencies:** API-003
+**Inputs:**
+
+- Logging strategy (structured JSON logs? Log aggregation tool?)
+- Monitoring integration (Sentry, DataDog?)
+
+### API-005: Refactor authentication endpoints
+
+**Intent:** Update all AUTH endpoints to use new error classes and middleware
+**Expected Outcome:** AUTH endpoints throwing proper errors, tests updated,
+error responses verified **Confidence:** high **Scopes:** API, AUTH **Tags:**
+refactor, authentication **Dependencies:** API-003, API-004
+
+### API-006: Refactor product catalog endpoints
+
+**Intent:** Update all PROD endpoints to use new error classes and middleware
+**Expected Outcome:** PROD endpoints throwing proper errors, tests updated
+**Confidence:** high **Scopes:** API, PROD **Tags:** refactor, products
+**Dependencies:** API-003, API-004
+
+### API-007: Refactor shopping cart endpoints
+
+**Intent:** Update all CART endpoints to use new error classes and middleware
+**Expected Outcome:** CART endpoints throwing proper errors, tests updated
+**Confidence:** high **Scopes:** API, CART **Tags:** refactor, cart
+**Dependencies:** API-003, API-004
+
+### API-008: Refactor payment endpoints
+
+**Intent:** Update all PAY endpoints to use new error classes and middleware
+**Expected Outcome:** PAY endpoints throwing proper errors, Stripe error mapping
+included **Confidence:** medium **Scopes:** API, PAY **Tags:** refactor,
+payments **Dependencies:** API-003, API-004 **Inputs:**
+
+- Stripe error code mappings
+- PCI compliance considerations for error messages
+
+### API-009: Add error monitoring integration
+
+**Intent:** Integrate error tracking service (Sentry) with automatic error
+reporting **Expected Outcome:** All errors automatically sent to monitoring with
+context (user, request, stack) **Confidence:** low **Scopes:** API, INFRA
+**Tags:** monitoring, observability, sentry **Dependencies:** API-004
+**Inputs:**
+
+- Sentry account and DSN
+- PII scrubbing rules
+- Alert thresholds
+
+### API-010: Update API documentation
+
+**Intent:** Document new error response format and codes in API docs **Expected
+Outcome:** API docs with error section, examples, and troubleshooting guide
+**Confidence:** high **Scopes:** DOCS **Tags:** documentation, api
+**Dependencies:** API-002, API-005, API-006, API-007, API-008
+
+### API-011: Remove deprecated error handling code
+
+**Intent:** Clean up old error handling patterns and remove dead code **Expected
+Outcome:** Codebase with only new error handling, no legacy patterns remaining
+**Confidence:** medium **Scopes:** API, AUTH, PROD, CART, PAY **Tags:** cleanup,
+refactor, technical-debt **Dependencies:** API-005, API-006, API-007, API-008
+
+## Dependencies
+
+- Monitoring service setup (Sentry or alternative)
+- Logging infrastructure (structured logging)
+
+## Notes
+
+- Consider rate limiting errors (e.g., don't log every 401)
+- May need database migration if error codes are persisted
+- Client applications will need updates to handle new error format
+- Rollout strategy: shadow mode first (log but don't change responses)?
+- Performance impact of error middleware needs measurement
+
+## Open Questions
+
+- Should we version the error response schema?
+- How do we handle errors in background jobs vs API requests?
+- Do we need different error formats for internal vs external APIs?

package/examples/system-ecommerce/APS.md

@@ -0,0 +1,57 @@
+# E-commerce Platform MVP
+
+## Overview
+
+Build the minimum viable product for an e-commerce platform with authentication,
+product catalog, shopping cart, and payment processing.
+
+## Modules
+
+### auth
+
+- **Path:** [./modules/auth.aps.md](./modules/auth.aps.md)
+- **Scope:** AUTH
+- **Owner:** @alice
+- **Priority:** high
+- **Tags:** security, core, backend
+- **Dependencies:** (none)
+
+### products
+
+- **Path:** [./modules/products.aps.md](./modules/products.aps.md)
+- **Scope:** PROD
+- **Owner:** @bob
+- **Priority:** high
+- **Tags:** catalog, backend, api
+- **Dependencies:** auth
+
+### cart
+
+- **Path:** [./modules/cart.aps.md](./modules/cart.aps.md)
+- **Scope:** CART
+- **Owner:** @carol
+- **Priority:** medium
+- **Tags:** shopping, backend, api
+- **Dependencies:** auth, products
+
+### payments
+
+- **Path:** [./modules/payments.aps.md](./modules/payments.aps.md)
+- **Scope:** PAY
+- **Owner:** @david
+- **Priority:** high
+- **Tags:** billing, stripe, backend
+- **Dependencies:** auth, cart
+
+## Open Questions
+
+- Do we need inventory management in MVP or can we assume unlimited stock?
+- Should we support guest checkout or require authentication?
+- What payment methods beyond credit card (Stripe)?
+
+## Decisions
+
+- Using Stripe for payment processing (decided 2025-12-15)
+- PostgreSQL for primary database (decided 2025-12-10)
+- JWT for authentication tokens (decided 2025-12-10)
+- Redis for session/cart caching (decided 2025-12-12)

package/examples/system-ecommerce/modules/auth.aps.md

@@ -0,0 +1,38 @@
+# Authentication Module
+
+**Scope:** AUTH **Owner:** @alice **Priority:** high
+
+> User authentication and session management with JWT tokens.
+
+## Tasks
+
+### AUTH-001: Implement user registration
+
+**Intent:** Create registration endpoint that validates email uniqueness and
+creates user accounts **Expected Outcome:** POST /auth/register endpoint
+returning user data and JWT token **Confidence:** high **Scopes:** AUTH, DB
+**Tags:** api, security, registration
+
+### AUTH-002: Implement login endpoint
+
+**Intent:** Create login endpoint that validates credentials and issues JWT
+tokens **Expected Outcome:** POST /auth/login endpoint with rate limiting and
+secure password verification **Confidence:** high **Scopes:** AUTH, DB **Tags:**
+api, security, authentication **Dependencies:** AUTH-001
+
+### AUTH-003: Create authentication middleware
+
+**Intent:** Build middleware to protect routes and attach user context to
+requests **Expected Outcome:** Reusable middleware that validates JWT and
+returns 401 for invalid tokens **Confidence:** high **Scopes:** AUTH, API
+**Tags:** middleware, security **Dependencies:** AUTH-002
+
+## Dependencies
+
+- Database schema for users table
+- Redis for token blacklist (optional for MVP)
+
+## Notes
+
+- Password reset and email verification deferred to post-MVP
+- Consider OAuth integration later

package/examples/system-ecommerce/modules/cart.aps.md

@@ -0,0 +1,53 @@
+# Shopping Cart Module
+
+**Scope:** CART **Owner:** @carol **Priority:** medium
+
+> Session-based shopping cart with Redis caching.
+
+## Tasks
+
+### CART-001: Design cart data structure
+
+**Intent:** Define cart schema for Redis with items, quantities, and expiry
+**Expected Outcome:** Documented cart data structure with TTL strategy
+**Confidence:** high **Scopes:** CART, CACHE **Tags:** design, redis, data-model
+
+### CART-002: Implement add to cart endpoint
+
+**Intent:** Create POST /cart/items endpoint that adds products to user cart
+**Expected Outcome:** Endpoint validating product exists and updating cart in
+Redis **Confidence:** high **Scopes:** CART, API, CACHE **Tags:** api, shopping
+**Dependencies:** CART-001, PROD-001, AUTH-003
+
+### CART-003: Implement view cart endpoint
+
+**Intent:** Create GET /cart endpoint returning current cart with product
+details **Expected Outcome:** Endpoint enriching cart with product info (name,
+price, availability) **Confidence:** high **Scopes:** CART, API, CACHE **Tags:**
+api, shopping **Dependencies:** CART-001, CART-002
+
+### CART-004: Implement update cart quantity endpoint
+
+**Intent:** Create PATCH /cart/items/:productId endpoint for quantity changes
+**Expected Outcome:** Endpoint handling quantity updates and item removal (qty
+= 0) **Confidence:** high **Scopes:** CART, API, CACHE **Tags:** api, shopping
+**Dependencies:** CART-002
+
+### CART-005: Add cart total calculation
+
+**Intent:** Calculate cart subtotal, tax, and total in cart response **Expected
+Outcome:** Cart endpoint including pricing breakdown **Confidence:** medium
+**Scopes:** CART, API **Tags:** pricing, calculations **Dependencies:** CART-003
+**Inputs:**
+
+- Tax calculation rules (by region or flat rate?)
+
+## Dependencies
+
+- Product module for validation
+- Authentication module for user context
+
+## Notes
+
+- Cart persistence (save for later) deferred to phase 2
+- Guest cart migration on login deferred to phase 2

package/examples/system-ecommerce/modules/payments.aps.md

@@ -0,0 +1,68 @@
+# Payment Processing Module
+
+**Scope:** PAY **Owner:** @david **Priority:** high
+
+> Stripe integration for payment processing and order completion.
+
+## Tasks
+
+### PAY-001: Set up Stripe integration
+
+**Intent:** Configure Stripe SDK and webhook endpoints for payment events
+**Expected Outcome:** Stripe client initialised with API keys and webhook
+verification **Confidence:** high **Scopes:** PAY, API **Tags:** stripe,
+integration, setup
+
+### PAY-002: Create payment intent endpoint
+
+**Intent:** Implement POST /payments/intents endpoint that creates Stripe
+PaymentIntent **Expected Outcome:** Endpoint returning client secret for
+frontend payment confirmation **Confidence:** high **Scopes:** PAY, API, CART
+**Tags:** stripe, api, checkout **Dependencies:** PAY-001, CART-003, AUTH-003
+**Inputs:**
+
+- Cart total from cart module
+- User information for Stripe metadata
+
+### PAY-003: Implement payment confirmation webhook
+
+**Intent:** Create webhook handler for Stripe payment success events **Expected
+Outcome:** Webhook that creates orders and clears carts on successful payment
+**Confidence:** medium **Scopes:** PAY, API, DB, CART **Tags:** stripe,
+webhooks, orders **Dependencies:** PAY-001, PAY-002
+
+### PAY-004: Create order model and storage
+
+**Intent:** Define Order model with items, amounts, and payment status
+**Expected Outcome:** Order model with migrations and relations to users and
+products **Confidence:** high **Scopes:** PAY, DB **Tags:** database, models,
+orders **Dependencies:** PROD-001, AUTH-001
+
+### PAY-005: Implement order history endpoint
+
+**Intent:** Create GET /orders endpoint returning user's order history
+**Expected Outcome:** Paginated list of orders with items and status
+**Confidence:** high **Scopes:** PAY, API **Tags:** api, orders, history
+**Dependencies:** PAY-004, AUTH-003
+
+### PAY-006: Add payment failure handling
+
+**Intent:** Handle failed payments and retry logic with user notifications
+**Expected Outcome:** Webhook handlers for failed/cancelled payments preserving
+cart **Confidence:** low **Scopes:** PAY, API, CART **Tags:** stripe,
+error-handling, webhooks **Dependencies:** PAY-003 **Inputs:**
+
+- Retry strategy (how many attempts? manual only?)
+- Notification system integration
+
+## Dependencies
+
+- Authentication for user context
+- Cart module for cart totals
+- Product module for order items
+
+## Notes
+
+- Refunds and order cancellation deferred to phase 2
+- Multiple payment methods (PayPal, etc.) deferred
+- Subscription payments out of scope for MVP

package/examples/system-ecommerce/modules/products.aps.md

@@ -0,0 +1,53 @@
+# Product Catalog Module
+
+**Scope:** PROD **Owner:** @bob **Priority:** high
+
+> Product listing, search, and detail management.
+
+## Tasks
+
+### PROD-001: Create product database model
+
+**Intent:** Define Product model with name, description, price, SKU, and
+inventory fields **Expected Outcome:** Product model with migrations,
+validation, and indexes **Confidence:** high **Scopes:** PROD, DB **Tags:**
+database, models
+
+### PROD-002: Implement product listing endpoint
+
+**Intent:** Create GET /products endpoint with pagination, filtering, and
+sorting **Expected Outcome:** Endpoint returning paginated product list with
+query parameters **Confidence:** high **Scopes:** PROD, API **Tags:** api,
+catalog, search **Dependencies:** PROD-001
+
+### PROD-003: Implement product detail endpoint
+
+**Intent:** Create GET /products/:id endpoint returning full product information
+**Expected Outcome:** Endpoint with product data including inventory status
+**Confidence:** high **Scopes:** PROD, API **Tags:** api, catalog
+**Dependencies:** PROD-001
+
+### PROD-004: Add product search functionality
+
+**Intent:** Implement full-text search across product names and descriptions
+**Expected Outcome:** GET /products/search endpoint with relevance scoring
+**Confidence:** medium **Scopes:** PROD, DB, API **Tags:** search, catalog
+**Dependencies:** PROD-001, PROD-002 **Inputs:**
+
+- Search indexing strategy (PostgreSQL full-text or Elasticsearch)
+
+### PROD-005: Create admin product management endpoints
+
+**Intent:** Build CRUD endpoints for product management (admin only) **Expected
+Outcome:** Protected endpoints for creating, updating, deleting products
+**Confidence:** high **Scopes:** PROD, API, AUTH **Tags:** admin, api, crud
+**Dependencies:** PROD-001, AUTH-003
+
+## Dependencies
+
+- Authentication module for admin protection
+
+## Notes
+
+- Image upload/storage deferred to separate module
+- Categories/tags system can be added in phase 2

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@eddacraft/anvil-aps",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./parser": "./dist/parser/index.js",
+    "./loader": "./dist/loader/index.js",
+    "./filter": "./dist/filter/index.js",
+    "./validator": "./dist/validator/index.js",
+    "./state": "./dist/state/index.js",
+    "./templates": "./dist/templates/index.js",
+    "./types": "./dist/types/index.js"
+  },
+  "dependencies": {
+    "@types/mdast": "^4.0.4",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "generate-templates": "pnpm build && node scripts/generate-templates.js"
+  }
+}

package/project.json

@@ -0,0 +1,37 @@
+{
+  "name": "@eddacraft/anvil-aps",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/aps/src",
+  "projectType": "library",
+  "release": {
+    "version": {
+      "manifestRootsToUpdate": ["{projectRoot}/dist"],
+      "currentVersionResolver": "git-tag",
+      "fallbackCurrentVersionResolver": "disk"
+    }
+  },
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "nx:run-script",
+      "outputs": ["{projectRoot}/dist"],
+      "options": {
+        "script": "build"
+      },
+      "dependsOn": ["^build"]
+    },
+    "nx-release-publish": {
+      "options": {
+        "packageRoot": "{projectRoot}/dist"
+      }
+    },
+    "generate-templates": {
+      "executor": "nx:run-script",
+      "outputs": ["{projectRoot}/templates"],
+      "options": {
+        "script": "generate-templates"
+      },
+      "dependsOn": ["build"]
+    }
+  }
+}

package/scripts/generate-templates.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * Generate APS planning document templates
+ *
+ * Usage: node generate-templates.js [output-dir]
+ */
+
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { generateAllTemplates } from '../dist/templates/generator.js';
+
+const OUTPUT_DIR = process.argv[2] || './templates';
+
+try {
+  // Create output directory
+  mkdirSync(OUTPUT_DIR, { recursive: true });
+
+  // Generate all templates
+  const templates = generateAllTemplates();
+
+  // Write each template to a file
+  writeFileSync(join(OUTPUT_DIR, 'index-template.md'), templates.index, 'utf8');
+  writeFileSync(join(OUTPUT_DIR, 'leaf-template.md'), templates.leaf, 'utf8');
+  writeFileSync(join(OUTPUT_DIR, 'simple-template.md'), templates.simple, 'utf8');
+
+  console.log(`✓ Generated templates in ${OUTPUT_DIR}/`);
+  console.log('  - index-template.md');
+  console.log('  - leaf-template.md');
+  console.log('  - simple-template.md');
+} catch (error) {
+  console.error('✗ Failed to generate templates:', error);
+  process.exit(1);
+}