@polymorphism-tech/morph-spec 4.7.0 → 4.7.2

package/.morph/framework/templates/examples/spec-examples.md

@@ -0,0 +1,90 @@
+# Spec Template Reference
+
+> **Layer:** 3 | **Load:** on-demand | **Keywords:** spec, specification, template
+
+**Use the stack's `.morph/framework/templates/spec.md` as the canonical template.**
+
+This file contains extended examples for each spec section.
+
+---
+
+## Example: Entity (Pseudo-code)
+
+```csharp
+class ProcessingJob {
+  Guid Id
+  string OriginalPhotoUrl     // Azure Blob URL, max 500 chars
+  string? ProcessedPhotoUrl   // Nullable, populated after processing
+  ProcessingStatus Status     // Enum: Pending, Processing, Completed, Failed
+  DateTime CreatedAt
+  ICollection<ExecutionLog> Logs  // 1:N relationship
+}
+
+enum ProcessingStatus {
+  Pending = 0, Processing = 1, Completed = 2,  // Normal flow
+  Failed = 100                                   // Error states (high values)
+}
+```
+
+## Example: Command (Pseudo-code)
+
+```csharp
+UploadPhotoCommand {
+  Input: IFormFile photo, string? email
+  Output: Guid jobId
+
+  Handler:
+    1. Validate file (size <= 10MB, type in [.jpg, .png])
+    2. Upload to Azure Blob Storage
+    3. Create ProcessingJob entity (status = Pending)
+    4. Enqueue Hangfire background job
+    5. Return jobId
+}
+```
+
+## Example: API Endpoints
+
+```csharp
+PhotoProcessingController {
+  POST /api/upload        → multipart/form-data → { jobId: Guid }
+  GET  /api/status/{id}   → jobId → { status, progress, createdAt }
+  GET  /api/download/{id} → jobId → Redirect to Blob URL or 404
+}
+```
+
+## Example: Flow
+
+```
+Upload Flow (Actor: User)
+1. User selects photo → System validates (size, type) → If invalid: show error
+2. User sees preview → clicks "Upload"
+3. System creates ProcessingJob → uploads to Blob → enqueues Hangfire job → returns jobId
+4. System navigates to /processing/{jobId} → polls every 5s
+End State: User on progress page, job processing in background
+```
+
+## Example: ADR
+
+### ADR-001: Use Hangfire for Background Jobs
+**Status:** Accepted
+**Context:** Need background processing for AI photo transformation (30-120s).
+**Decision:** Hangfire (self-hosted).
+**Alternatives:**
+1. Azure Functions — serverless, auto-scaling, but cold start + $10/mo for 50k jobs
+2. Hangfire — zero cost, simpler, but scales with app
+3. Quartz.NET — more features, but steeper learning curve
+**Trade-offs:** Simplicity vs Features (Hangfire sufficient for MVP)
+
+## Example: Cost Estimate
+
+| Resource | SKU | Monthly | Justification |
+|----------|-----|---------|---------------|
+| Blob Storage | LRS | $0.02 | Store photos, low redundancy OK |
+| Azure SQL | Basic | $4.99 | < 100k jobs/month |
+| Container App | Consumption | $0.49 | Scale to zero |
+| Hangfire | Self-hosted | $0.00 | In-process |
+| **Total** | | **~$5.50** | |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/.morph/framework/templates/feature/decisions.md

@@ -0,0 +1,187 @@
+# Architecture Decision Records - {{titleCase FEATURE_NAME}}
+
+## ADR-001: {Decision Title}
+
+**Date:** {{DATE}}
+**Status:** Proposed | Accepted | Deprecated | Superseded
+**Deciders:** MORPH Agents, Developer
+
+### Context
+
+{Describe the context and problem that led to this decision}
+
+### Decision
+
+{Describe the decision made}
+
+### Consequences
+
+**Pros:**
+- {Positive consequence 1}
+- {Positive consequence 2}
+
+**Cons:**
+- {Negative consequence 1}
+
+**Risks:**
+- {Identified risk}
+
+### Alternatives Considered
+
+#### Option A: {Name}
+- Pros: {advantages}
+- Cons: {disadvantages}
+- **Rejected because:** {reason}
+
+#### Option B: {Name}
+- Pros: {advantages}
+- Cons: {disadvantages}
+- **Rejected because:** {reason}
+
+{{#if (eq STACK "blazor-azure")}}
+### Affected Flows
+- **Main flow:** {ex: Upload -> Payment -> Generation -> Email}
+- **Alternative flow:** {ex: Upload -> Generation -> Payment -> Email}
+- **Free flow:** {ex: Upload -> Generation -> Download}
+
+### Impacted State Validations
+
+> **Reference:** `framework/standards/status-validation.md`
+
+| Service | Method | Accepted States |
+|---------|--------|-----------------|
+| {ServiceName} | {MethodName} | {ex: PendingPayment, Completed} |
+
+### UI Components with Special Behavior
+- {ex: FluentDialog requires initial Hidden="true"}
+- {ex: Modal needs @ref for programmatic control}
+{{/if}}
+
+---
+
+{{#if (eq STACK "blazor-azure")}}
+## ADR-002: Database Model
+
+**Date:** {{DATE}}
+**Status:** Accepted
+
+### Context
+
+Need to define how {Feature} data will be stored.
+
+### Decision
+
+Use Azure SQL with the following model:
+- {Entity} table with {columns}
+- JSON columns for {flexible data}
+
+### Consequences
+
+**Pros:**
+- Fits within free tier (32GB)
+- Good query performance
+
+---
+
+## ADR-003: AI Integration
+
+**Date:** {{DATE}}
+**Status:** Accepted
+
+### Context
+
+Feature requires AI capabilities for {purpose}.
+
+### Decision
+
+Use MS Agent Framework with gpt-4o-mini model.
+
+### Consequences
+
+**Pros:**
+- Cost effective (~$0.15/1M input tokens)
+- Good enough quality for this use case
+
+**Cons:**
+- Slightly less capable than gpt-4o
+{{/if}}
+
+{{#if (eq STACK "nextjs-supabase")}}
+## ADR-002: Database Access Strategy
+
+**Date:** {{DATE}}
+**Status:** Accepted
+
+### Context
+
+Need to decide how the .NET API accesses Supabase PostgreSQL.
+
+### Decision
+
+Use Dapper with Npgsql for direct SQL queries. No EF Core.
+
+### Consequences
+
+**Pros:**
+- Full control over SQL queries
+- Better performance (no ORM overhead)
+- Direct access to PostgreSQL features (jsonb, pgvector, functions)
+- RLS policies apply naturally through connection
+
+**Cons:**
+- No automatic migrations (use Supabase CLI instead)
+- Manual SQL query writing
+- No change tracking
+
+---
+
+## ADR-003: Auth Strategy
+
+**Date:** {{DATE}}
+**Status:** Accepted
+
+### Context
+
+Need authentication for both Next.js frontend and .NET API.
+
+### Decision
+
+Use Supabase Auth with @supabase/ssr on frontend. Validate JWT tokens in .NET API middleware.
+
+### Consequences
+
+**Pros:**
+- Single auth provider for both layers
+- RLS policies work automatically with auth.uid()
+- Built-in social login, magic links, email/password
+- No separate auth service to maintain
+
+**Cons:**
+- Coupled to Supabase ecosystem
+- JWT secret must be shared with .NET API
+{{/if}}
+
+---
+
+## Template for New ADRs
+
+```markdown
+## ADR-XXX: {Title}
+
+**Date:**
+**Status:** Proposed | Accepted | Deprecated | Superseded
+
+### Context
+{Why is this decision needed?}
+
+### Decision
+{What was decided?}
+
+### Consequences
+**Pros:** {list}
+**Cons:** {list}
+```
+
+---
+
+*Generated by MORPH Framework*

package/.morph/framework/templates/feature/recap.md

@@ -0,0 +1,146 @@
+# Feature Recap: {{titleCase FEATURE_NAME}}
+
+## Summary
+
+| Field | Value |
+|-------|-------|
+| **Feature ID** | {{FEATURE_NAME}} |
+| **Completed** | {{DATE}} |
+| **Total Tasks** | {X} |
+| **Time Spent** | {X}h |
+| **Agents Used** | {list} |
+{{#if STACK}}| **Stack** | {{STACK}} |{{/if}}
+
+---
+
+## Tasks Completed
+
+| ID | Title | Category | Duration |
+|----|-------|----------|----------|
+| T001 | {title} | {{#if (eq STACK "nextjs-supabase")}}Database{{else}}{category}{{/if}} | {X}min |
+| T002 | {title} | {{#if (eq STACK "nextjs-supabase")}}Backend{{else}}{category}{{/if}} | {X}min |
+| T003 | {title} | {{#if (eq STACK "nextjs-supabase")}}Frontend{{else}}{category}{{/if}} | {X}min |
+
+---
+
+{{#if (eq STACK "nextjs-supabase")}}
+## Validation Results
+
+| Validator | Status | Details |
+|-----------|--------|---------|
+| contract-compliance | Pass/Fail | {details} |
+| architecture | Pass/Fail | {details} |
+| design-system | Pass/Fail | {details} |
+| coding-standards | Pass/Fail | {details} |
+
+---
+
+{{/if}}
+## What Was Delivered
+
+### Functionality
+- {Functionality 1 delivered}
+- {Functionality 2 delivered}
+- {Functionality 3 delivered}
+
+{{#if (eq STACK "nextjs-supabase")}}
+### Database (Supabase)
+- Tables: {list}
+- RLS Policies: {count} policies
+- Migrations: {count} files
+
+### Backend API (.NET)
+- Endpoints: {count} endpoints
+- Services: {list}
+
+### Frontend (Next.js)
+- Pages: {list}
+- Components: {list}
+{{/if}}
+
+---
+
+## Files Created
+
+```
+{{#if (eq STACK "nextjs-supabase")}}
+supabase/migrations/{files}
+backend/src/{files}
+frontend/src/{files}
+{{else}}
+{list of created files}
+{{/if}}
+```
+
+## Files Modified
+
+```
+{list of modified files}
+```
+
+---
+
+## Architecture Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| {Decision 1} | {Reason} |
+| {Decision 2} | {Reason} |
+
+See full ADRs in `decisions.md`
+
+---
+
+## Test Coverage
+
+| Type | Files | Coverage |
+|------|-------|----------|
+| {{#if (eq STACK "nextjs-supabase")}}Backend Unit{{else}}Unit Tests{{/if}} | {X} | {X}% |
+| {{#if (eq STACK "nextjs-supabase")}}Frontend Component{{else}}Integration Tests{{/if}} | {X} | {X}% |
+
+---
+
+## Lessons Learned
+
+### What Went Well
+- {Positive point 1}
+- {Positive point 2}
+
+### What Could Be Improved
+- {Improvement point 1}
+- {Improvement point 2}
+
+### Recommendations for Future
+- {Recommendation 1}
+- {Recommendation 2}
+
+---
+
+## Metrics
+
+| Metric | Value |
+|--------|-------|
+| Tasks Completed | {X}/{X} |
+| Checkpoints Passed | {X} |
+{{#if (eq STACK "nextjs-supabase")}}| Validation Passes | {X}/{X} |
+{{else}}| Code Reviews | {X} |
+{{/if}}| Bugs Found | {X} |
+| Bugs Fixed | {X} |
+
+---
+
+## Related Resources
+
+- **Proposal:** `proposal.md`
+- **Spec:** `spec.md`
+{{#if (eq STACK "nextjs-supabase")}}- **Contracts (.NET):** `contracts.cs`
+- **Contracts (TS):** `contracts.ts`
+{{else}}- **Contracts:** `contracts.cs`
+{{/if}}- **Tasks:** `tasks.md`
+- **Decisions:** `decisions.md`
+{{#if (eq STACK "blazor-azure")}}- **Azure DevOps Epic:** {link}
+{{/if}}- **PR:** {link}
+
+---
+
+*Generated by MORPH Framework on {{DATE}}*

package/.morph/framework/templates/feature/tasks.md

@@ -0,0 +1,199 @@
+# Tasks - {{titleCase FEATURE_NAME}}
+
+> Implementation checklist for the feature.
+> Update status as you progress.
+
+| Task ID | Type | Title | Status |
+|---------|------|-------|--------|
+| T001 | {type} | {title} | Pending |
+| T002 | {type} | {title} | Pending |
+| T003 | {type} | {title} | In Progress |
+| T004 | {type} | {title} | Blocked |
+| T005 | {type} | {title} | Done |
+
+**Status Values:** `Pending | In Progress | Blocked | Done`
+
+---
+
+## Task Granularity
+
+### Ideal Task
+- 15-60 minutes of implementation
+- 1-5 files modified
+- Testable in isolation
+- Independent commit possible
+
+### Signs of Too Broad (Split)
+**Bad example:** "Implement feature"
+**Split into:**
+- T001: Define contracts and interfaces
+- T002: Implement data layer
+- T003: Implement business logic
+- T004: Create UI components
+- T005: Write tests
+
+### Signs of Too Granular (Merge)
+**Bad example:** "Create field A", "Create field B", "Create field C"
+**Merge into:** "Create data model with all fields"
+
+---
+
+## Gates & Reviews
+
+| Task ID | Type | Description | Status |
+|---------|------|-------------|--------|
+| T003 | Review | Review contracts and data model | Pending |
+| T006 | Review | Review implementation | Pending |
+| T009 | Approval | Approve UI before testing | Pending |
+
+---
+
+## Phase 1: Contracts & Data Model
+
+### T001: Define contracts and interfaces
+- **Type:** Contract
+- **Priority:** 1
+- **Estimate:** 30min
+- **Assigned:** {agent}
+- **Dependencies:** None
+
+**Description:**
+
+Define service interfaces and contracts.
+
+**Deliverables:**
+- [ ] Create: `{path-to-interface-file}`
+
+---
+
+### T002: Create data model
+- **Type:** {{#if (eq STACK "nextjs-supabase")}}Database{{else}}Domain{{/if}}
+- **Priority:** 1
+- **Estimate:** 45min
+- **Assigned:** {agent}
+- **Dependencies:** None
+
+**Description:**
+
+Create data model {{#if (eq STACK "nextjs-supabase")}}with migrations{{else}}with entities{{/if}}.
+
+**Deliverables:**
+- [ ] Create: `{path-to-model-file}`
+
+---
+
+## Phase 2: Implementation
+
+### T003: Implement data layer
+- **Type:** {{#if (eq STACK "nextjs-supabase")}}Repository{{else}}Infrastructure{{/if}}
+- **Priority:** 2
+- **Estimate:** 1h
+- **Assigned:** {agent}
+- **Dependencies:** T001, T002
+
+**Description:**
+
+Implement data access layer.
+
+**Deliverables:**
+- [ ] Create: `{path-to-repository-file}`
+
+---
+
+### T004: Implement business logic
+- **Type:** Service
+- **Priority:** 2
+- **Estimate:** 1h
+- **Assigned:** {agent}
+- **Dependencies:** T001, T003
+
+**Description:**
+
+Implement service layer with business logic.
+
+**Deliverables:**
+- [ ] Create: `{path-to-service-file}`
+
+---
+
+## Phase 3: UI Components
+
+### T005: Create list component
+- **Type:** UI
+- **Priority:** 2
+- **Estimate:** 45min
+- **Assigned:** {agent}
+- **Dependencies:** T004
+
+**Description:**
+
+Create component to list items.
+
+**Deliverables:**
+- [ ] Create: `{path-to-component-file}`
+
+---
+
+### T006: Create form component
+- **Type:** UI
+- **Priority:** 2
+- **Estimate:** 1h
+- **Assigned:** {agent}
+- **Dependencies:** T005
+
+**Description:**
+
+Create component for create/edit.
+
+**Deliverables:**
+- [ ] Create: `{path-to-form-file}`
+
+---
+
+## Phase 4: Testing
+
+### T007: Write unit tests
+- **Type:** Test
+- **Priority:** 2
+- **Estimate:** 1h
+- **Assigned:** {agent}
+- **Dependencies:** T004
+
+**Description:**
+
+Unit tests for service layer.
+
+**Deliverables:**
+- [ ] Create: `{path-to-test-file}`
+
+---
+
+### T008: Write integration tests
+- **Type:** Test
+- **Priority:** 3
+- **Estimate:** 1h
+- **Assigned:** {agent}
+- **Dependencies:** T007
+
+**Description:**
+
+Integration tests for {{#if (eq STACK "nextjs-supabase")}}API and database{{else}}repository and API{{/if}}.
+
+**Deliverables:**
+- [ ] Create: `{path-to-integration-test-file}`
+
+---
+
+## Summary
+
+| Phase | Tasks | Estimate |
+|-------|-------|----------|
+| Phase 1 | T001-T002 | {X}h |
+| Phase 2 | T003-T004 | {X}h |
+| Phase 3 | T005-T006 | {X}h |
+| Phase 4 | T007-T008 | {X}h |
+| **Total** | **8 tasks** | **{X}h** |
+
+---
+
+*Generated by MORPH Framework*

package/.morph/framework/templates/frontend/nextjs/Dockerfile.nextjs.hbs

@@ -0,0 +1,43 @@
+# Multi-stage Next.js production build for EasyPanel
+# Stage 1: Dependencies
+FROM node:20-alpine AS deps
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+
+COPY package.json package-lock.json* ./
+RUN npm ci --only=production && npm cache clean --force
+
+# Stage 2: Build
+FROM node:20-alpine AS builder
+WORKDIR /app
+
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# Build args for NEXT_PUBLIC_ variables (must be available at build time)
+ARG NEXT_PUBLIC_APP_URL
+ENV NEXT_PUBLIC_APP_URL=$NEXT_PUBLIC_APP_URL
+
+RUN npm run build
+
+# Stage 3: Production runner
+FROM node:20-alpine AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+
+EXPOSE 3000
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+
+CMD ["node", "server.js"]

package/.morph/framework/templates/frontend/nextjs/client-component.tsx.hbs

@@ -0,0 +1,26 @@
+// features/{{kebabCase featureName}}/components/{{kebabCase featureName}}-list.tsx
+'use client';
+
+import { use{{pascalCase featureName}}s } from '@/features/{{kebabCase featureName}}/hooks/use-{{kebabCase featureName}}s';
+import { DataTable } from '@/components/data-table';
+import type { {{pascalCase featureName}} } from '@/features/{{kebabCase featureName}}/types/{{kebabCase featureName}}.types';
+import type { ColumnDef } from '@tanstack/react-table';
+
+const columns: ColumnDef<{{pascalCase featureName}}>[] = [
+  { accessorKey: 'id', header: 'ID' },
+  { accessorKey: 'name', header: 'Name' },
+];
+
+interface {{pascalCase featureName}}ListProps {
+  initialData?: {{pascalCase featureName}}[];
+}
+
+export function {{pascalCase featureName}}List({ initialData }: {{pascalCase featureName}}ListProps) {
+  const { data = initialData ?? [], isLoading } = use{{pascalCase featureName}}s();
+
+  if (isLoading) {
+    return <div className="flex items-center justify-center h-32">Loading...</div>;
+  }
+
+  return <DataTable columns={columns} data={data} />;
+}