guardian-framework 0.1.25 → 0.1.27

package/dist/exports.js

@@ -995,7 +995,7 @@ __export(exports_package, {
   bin: () => bin,
   author: () => author
 });
-var name = "guardian-framework", version = "0.1.25", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
+var name = "guardian-framework", version = "0.1.27", description = "Token-optimized agentic framework scaffolder with pi-first architecture", type = "module", main = "dist/exports.js", exports, types = "dist/exports.d.ts", bin, files, engines, scripts, publishConfig, pi, repository, homepage = "https://github.com/arman-jalili/guardian-framework#readme", bugs, dependencies, devDependencies, keywords, author = "Arman Wolkensteiner-Jalili", license = "MIT", package_default;
 var init_package = __esm(() => {
   exports = {
     ".": {
@@ -11022,6 +11022,115 @@ Respond with ONLY valid JSON matching this exact structure. Do not include markd
   "aggregateRoots": "Which entities are aggregate roots and why"
 }`;
 }
+function buildFrontendExplorationPrompt(context) {
+  const sanitized = sanitizeBusinessContext(context);
+  return `You are a frontend architecture expert. Analyze the following web application description and extract a structured model focused on user experience, UI concepts, and design principles.
+
+Business Context:
+${sanitized}
+
+Respond with ONLY valid JSON matching this exact structure. Do not include markdown formatting, code fences, or explanatory text:
+
+{
+  "sessionId": "auto-generated-uuid",
+  "businessContext": "original description",
+  "status": "draft",
+  "actors": [
+    {
+      "name": "UserRole",
+      "description": "Who this user is",
+      "interactions": "What they do in the application"
+    }
+  ],
+  "functionalRequirements": [
+    {
+      "id": "FR-001",
+      "requirement": "The user shall be able to...",
+      "priority": "critical|high|medium|low",
+      "boundedContext": "FeatureName"
+    }
+  ],
+  "nonFunctionalRequirements": [
+    {
+      "id": "NFR-001",
+      "requirement": "The application shall...",
+      "category": "performance|accessibility|usability|security|maintainability",
+      "target": "Specific measurable target"
+    }
+  ],
+  "assumptions": [
+    {
+      "assumption": "We assume that...",
+      "impactIfWrong": "What breaks if this is false",
+      "mitigation": "How we handle it being wrong"
+    }
+  ],
+  "boundedContexts": [
+    {
+      "name": "FeatureName",
+      "description": "Brief description of this app feature/section",
+      "entities": ["UIConcept1", "UIConcept2"]
+    }
+  ],
+  "entities": [
+    {
+      "name": "UIConceptName",
+      "context": "FeatureName",
+      "type": "ui-concept | user-intent | design-token | app-shell | value-object",
+      "description": "What this UI concept represents"
+    }
+  ],
+  "userIntents": [
+    {
+      "name": "UserIntentName",
+      "context": "FeatureName",
+      "description": "What the user is trying to do",
+      "triggeredBy": "What UI action triggers this intent"
+    }
+  ],
+  "designPrinciples": [
+    {
+      "principle": "The application is...",
+      "description": "What this principle means in practice",
+      "rationale": "Why this principle exists"
+    }
+  ],
+  "navigationPhilosophy": {
+    "contextPreservation": "How the user never loses context",
+    "deepLinking": "How every page is deep-linkable",
+    "multiTab": "How multiple tabs are supported"
+  },
+  "appShell": {
+    "navigation": "Navigation structure",
+    "header": "Header content",
+    "sidebar": "Sidebar content",
+    "commandPalette": "Command palette actions",
+    "globalSearch": "Global search behavior"
+  },
+  "degradationStrategy": [
+    {
+      "feature": "FeatureName",
+      "whenUnavailable": "What happens when this feature's API is down",
+      "degradesTo": "What still works"
+    }
+  ],
+  "ubiquitousLanguage": [
+    {
+      "term": "CanonicalTerm",
+      "definition": "Clear definition",
+      "boundedContext": "FeatureName",
+      "aliases": ["AlternativeName1"],
+      "examples": "Usage example"
+    }
+  ],
+  "openQuestions": "Any open questions about the application",
+  "designSystem": {
+    "componentLibrary": "Which component library or approach (Tailwind, MUI, custom)",
+    "theming": "How theming works (dark mode, branding)",
+    "accessibility": "Accessibility requirements"
+  }
+}`;
+}
 function parseExplorationResponse(rawResponse, sessionId) {
   try {
     let cleaned = rawResponse.trim();
@@ -11103,6 +11212,14 @@ function coerceEntityType(val) {
     return "value-object";
   if (val === "aggregate-root")
     return "aggregate-root";
+  if (val === "ui-concept")
+    return "ui-concept";
+  if (val === "user-intent")
+    return "user-intent";
+  if (val === "design-token")
+    return "design-token";
+  if (val === "app-shell")
+    return "app-shell";
   return "entity";
 }
 function coerceFrPriority(val) {
@@ -11187,8 +11304,20 @@ async function exploreDomain(context, options) {
   if (!fs12.existsSync(explorationDir)) {
     fs12.mkdirSync(explorationDir, { recursive: true });
   }
+  let lang = options?.language;
+  if (!lang) {
+    try {
+      const manifestPath = path11.join(projectDir, "guardian-manifest.json");
+      if (fs12.existsSync(manifestPath)) {
+        const manifest = JSON.parse(fs12.readFileSync(manifestPath, "utf-8"));
+        if (manifest.language)
+          lang = manifest.language;
+      }
+    } catch {}
+  }
   const sanitized = sanitizeBusinessContext(context);
-  const prompt = buildExplorationPrompt(sanitized);
+  const isFrontend = lang === "nextjs" || lang === "angular";
+  const prompt = isFrontend ? buildFrontendExplorationPrompt(sanitized) : buildExplorationPrompt(sanitized);
   const promptContent = [
     "# Domain Exploration Prompt",
     "",
@@ -11341,6 +11470,18 @@ function extractTable(body, sectionName) {
 function scaffoldFromExploration(sessionId, options) {
   const projectDir = options?.projectDir ?? process.cwd();
   const dryRun = options?.dryRun ?? false;
+  let lang = options?.language;
+  if (!lang) {
+    try {
+      const manifestPath = path11.join(projectDir, "guardian-manifest.json");
+      if (fs12.existsSync(manifestPath)) {
+        const manifest = JSON.parse(fs12.readFileSync(manifestPath, "utf-8"));
+        if (manifest.language)
+          lang = manifest.language;
+      }
+    } catch {}
+  }
+  const isFrontend = lang === "nextjs" || lang === "angular";
   const sessionResult = readExplorationSession(sessionId, projectDir);
   if (!sessionResult) {
     throw new Error(`Exploration session not found: ${sessionId}`);
@@ -11462,76 +11603,239 @@ function scaffoldFromExploration(sessionId, options) {
 `;
       }
     }
-    let content = `# ${bc.name}
+    let content = "";
+    if (isFrontend) {
+      const uiConcepts = contextEntities.filter((e2) => e2.type === "ui-concept");
+      const userIntents = contextEntities.filter((e2) => e2.type === "user-intent");
+      const designTokens = contextEntities.filter((e2) => e2.type === "design-token");
+      const appShells = contextEntities.filter((e2) => e2.type === "app-shell");
+      content = `# ${bc.name}
 
 `;
-    content += `## Module Status
+      content += `## Module Status
 
 `;
-    content += `**Status:** Planned
+      content += `**Status:** Planned
 `;
-    content += `**Last reviewed:** ${timestamp}
+      content += `**Last reviewed:** ${timestamp}
 `;
-    content += `**Source session:** ${sessionId}
+      content += `**Source session:** ${sessionId}
 
 `;
-    content += `## Description
+      content += `## Description
 
 ${bc.description}
 
 `;
-    content += `## Components
+      content += `## UI Concepts
 
-${componentsSection}
 `;
-    content += `## Domain Events
+      if (uiConcepts.length === 0) {
+        content += `None defined yet.
 
 `;
-    if (contextEvents.length === 0) {
-      content += `None defined yet.
+      } else {
+        for (const uc of uiConcepts) {
+          content += `### ${uc.name}
+`;
+          content += `**Description:** ${uc.description}
 
 `;
-    } else {
-      for (const ev of contextEvents) {
-        content += `- **${ev.name}** - ${ev.description} (triggered by: ${ev.triggeredBy})
+        }
+      }
+      content += `## User Intents
+
 `;
+      if (userIntents.length === 0) {
+        content += `None defined yet.
+
+`;
+      } else {
+        for (const ui of userIntents) {
+          content += `### ${ui.name}
+`;
+          content += `**Description:** ${ui.description}
+
+`;
+        }
       }
+      if (designTokens.length > 0) {
+        content += `## Design Tokens
+
+`;
+        for (const dt of designTokens) {
+          content += `- **${dt.name}** - ${dt.description}
+`;
+        }
+        content += `
+`;
+      }
+      if (appShells.length > 0) {
+        content += `## App Shell Integration
+
+`;
+        for (const as of appShells) {
+          content += `- **${as.name}** - ${as.description}
+`;
+        }
+        content += `
+`;
+      }
+      content += `## Design Principles
+
+`;
+      content += `- The Web application is not responsible for enforcing business rules.
+`;
+      content += `- The Web application is optimistic.
+`;
+      content += `- The Web application is resilient.
+`;
+      content += `- The Web application is accessible.
+`;
+      content += `- The Web application is stateless whenever possible.
+`;
+      content += `- The Web application delegates authority to Enterprise.
+`;
+      content += `- The Web application enhances productivity rather than exposing implementation details.
+`;
       content += `
 `;
-    }
-    content += `## Ubiquitous Language
+      content += `## Navigation Philosophy
+
+`;
+      content += `- The user shall never lose context.
+`;
+      content += `- Every screen belongs to a Brain. Every Brain belongs to a Workspace.
+`;
+      content += `- Every action should expose the current path.
+`;
+      content += `- Deep linking shall exist for every page.
+`;
+      content += `- Browser navigation shall always work.
+`;
+      content += `- Multiple tabs shall be supported.
+`;
+      content += `
+`;
+      content += `## Degradation Strategy
+
+`;
+      content += `- If a feature API is unavailable, navigation still works.
+`;
+      content += `- Editing still works.
+`;
+      content += `- AI features are disabled gracefully, not causing errors.
+`;
+      content += `- The application renders a degraded UI instead of crashing.
+`;
+      content += `
+`;
+      content += `## Ubiquitous Language
 
 `;
-    if (contextTerms.length === 0) {
-      content += `None defined yet.
+      if (contextTerms.length === 0) {
+        content += `None defined yet.
+
+`;
+      } else {
+        content += `| Term | Definition | Aliases |
+`;
+        content += `|------|-----------|---------|
+`;
+        for (const t of contextTerms) {
+          content += `| ${t.term} | ${t.definition} | ${t.aliases.join(", ")} |
+`;
+        }
+        content += `
+`;
+      }
+      content += `## Dependencies
+
+`;
+      content += `${depsSection}
+`;
+      content += `## Key Files
+
+None yet
+
+`;
+      content += `## ADRs
+
+None yet
 
 `;
     } else {
-      content += `| Term | Definition | Aliases |
+      content = `# ${bc.name}
+
 `;
-      content += `|------|-----------|---------|
+      content += `## Module Status
+
+`;
+      content += `**Status:** Planned
+`;
+      content += `**Last reviewed:** ${timestamp}
 `;
-      for (const t of contextTerms) {
-        content += `| ${t.term} | ${t.definition} | ${t.aliases.join(", ")} |
+      content += `**Source session:** ${sessionId}
+
+`;
+      content += `## Description
+
+${bc.description}
+
+`;
+      content += `## Components
+
+${componentsSection}
+`;
+      content += `## Domain Events
+
+`;
+      if (contextEvents.length === 0) {
+        content += `None defined yet.
+
+`;
+      } else {
+        for (const ev of contextEvents) {
+          content += `- **${ev.name}** - ${ev.description} (triggered by: ${ev.triggeredBy})
+`;
+        }
+        content += `
 `;
       }
-      content += `
+      content += `## Ubiquitous Language
+
 `;
-    }
-    content += `## Dependencies
+      if (contextTerms.length === 0) {
+        content += `None defined yet.
+
+`;
+      } else {
+        content += `| Term | Definition | Aliases |
+`;
+        content += `|------|-----------|---------|
+`;
+        for (const t of contextTerms) {
+          content += `| ${t.term} | ${t.definition} | ${t.aliases.join(", ")} |
+`;
+        }
+        content += `
+`;
+      }
+      content += `## Dependencies
 
 ${depsSection}
 `;
-    content += `## Key Files
+      content += `## Key Files
 
 None yet
 
 `;
-    content += `## ADRs
+      content += `## ADRs
 
 None yet
 
 `;
+    }
     if (!dryRun) {
       fs12.mkdirSync(modulesDir, { recursive: true });
       const tempPath = `${filePath}.tmp`;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "guardian-framework",
-	"version": "0.1.25",
+	"version": "0.1.27",
 	"description": "Token-optimized agentic framework scaffolder with pi-first architecture",
 	"type": "module",
 	"main": "dist/exports.js",

package/templates/pi/architecture/modules/module-template.md

@@ -10,18 +10,40 @@ Generated: NEVER (this is the source)
 
 [Brief description of the module's purpose and scope within the system]
 
-## Responsibilities
+## DDD Layers
 
-- [Responsibility 1]
-- [Responsibility 2]
-- [Responsibility 3]
+This module follows Clean Architecture with 4 DDD layers:
 
-## Components
+| Layer | Purpose | Tech |
+|-------|---------|------|
+| `domain/` | Pure business logic, types, errors | Zero framework imports |
+| `application/` | State management, use cases, actions | Stores, Server Actions |
+| `infrastructure/` | External adapters, API clients, SDKs | Fetch, tRPC, GraphQL |
+| `interfaces/` | UI components, pages, layouts | React, Next.js |
 
-| Component | File Path | Purpose | Canonical Section |
-|-----------|-----------|---------|-------------------|
-| [Name] | src/[module]/domain/[file].rs | [Description] | #[section] |
-| [Name] | src/[module]/application/[file].rs | [Description] | #[section] |
+**Dependency rule:** `domain → application → infrastructure → interfaces` (inward)
+
+## Components by Layer
+
+### Domain Layer (`domain/`)
+| Component | Description | Framework? |
+|-----------|-------------|------------|
+| [Name] | [Purpose] | ❌ No |
+
+### Application Layer (`application/`)
+| Component | Description | Type |
+|-----------|-------------|------|
+| [Name] | [Purpose] | Store / Action / Query |
+
+### Infrastructure Layer (`infrastructure/`)
+| Component | Description | Connects to |
+|-----------|-------------|-------------|
+| [Name] | [Purpose] | [API / SDK] |
+
+### Interfaces Layer (`interfaces/`)
+| Component | Description | 'use client'? |
+|-----------|-------------|---------------|
+| [Name] | [Purpose] | Yes / No |
 
 ---
 
@@ -31,35 +53,40 @@ Generated: NEVER (this is the source)
 
 **Purpose:** [What this component does]
 
-**Implementation File:** `src/[module]/[layer]/[file].rs`
+**DDL Layer:** `[domain/application/infrastructure/interfaces]`
+
+**Implementation File:** `src/[module]/[layer]/[file].ts`
 
 **Canonical Reference:** `.pi/architecture/modules/[module-name].md#[component-section]`
 
+**States:**
+- **Loading:** [What the user sees during load]
+- **Empty:** [What the user sees when there's no data]
+- **Populated:** [Normal state]
+- **Error:** [What the user sees on failure]
+
 **Dependencies:**
 - [Dependency 1]
 - [Dependency 2]
 
-**Interface:**
-
-```typescript
-// Public interface
-interface [InterfaceName] {
-  [method signatures]
-}
-```
-
 ---
 
 ## Data Flow
 
 ```
-[Input Source]
+User Intent
      │
      ▼
-[Processing Component]
+Component (interfaces/) → user action
      │
      ▼
-[Output Destination]
+Store/Server Action (application/) → optimistic update
+     │
+     ▼
+API Client (infrastructure/) → fetch
+     │
+     ▼
+Response → commit or rollback → UI update
 ```
 
 **Flow Description:**
@@ -69,40 +96,57 @@ interface [InterfaceName] {
 
 ---
 
+## User Intents
+
+| Intent | Triggered By | Handled By | Domain Event (backend) |
+|--------|-------------|------------|----------------------|
+| UserClickedThread | Click on thread title | ThreadPanel | ThreadSelected |
+| UserSubmittedComment | Click Submit button | CommentInput | CommentCreated |
+
+---
+
+## Design Principles
+
+- This module is **optimistic**: UI updates before API responds
+- This module is **resilient**: failure doesn't crash other modules
+- This module is **stateless**: state lives in stores, not server
+
+---
+
+## Degradation Strategy
+
+| Feature | When Unavailable | User Sees |
+|---------|-----------------|-----------|
+| [Feature] | API is down | [Degraded state] |
+
+---
+
 ## Dependencies
 
 ### Depends On
 - **[Module Name]**: [Why/what it provides]
-- **[Module Name]**: [Why/what it provides]
 
 ### Used By
 - **[Module Name]**: [Why/what it uses]
-- **[Module Name]**: [Why/what it uses]
 
 ---
 
 ## Security Considerations
 
-| Concern | Mitigation | Validator |
-|---------|------------|-----------|
-| [Concern 1] | [Mitigation] | security-validator |
-| [Concern 2] | [Mitigation] | security-validator |
-
-**Authentication/Authorization:**
-- [Auth requirements]
-
-**Data Protection:**
-- [Encryption/sanitization requirements]
+| Concern | Mitigation |
+|---------|------------|
+| [Concern 1] | [Mitigation] |
 
 ---
 
 ## Testing Requirements
 
-| Test Type | Coverage Target | Files |
-|-----------|-----------------|-------|
-| Unit | [X]% | tests/unit/[module].test.ts |
-| Integration | [Y]% | tests/integration/[module].test.ts |
-| E2E | [Z]% | tests/e2e/[module].test.ts |
+| Layer | Test Type | Coverage Target |
+|-------|-----------|-----------------|
+| Domain | Unit | [X]% |
+| Application | Unit | [X]% |
+| Infrastructure | Integration | [X]% |
+| Interfaces | Component | [X]% |
 
 **Key Test Scenarios:**
 - [Scenario 1]
@@ -113,17 +157,17 @@ interface [InterfaceName] {
 
 ## Error Handling
 
+**Domain errors (domain/):**
 ```typescript
-// Error types defined in this module
 class [ErrorType] extends Error {
-  constructor(message: string) {
+  constructor(code: string, message: string, retriable?: boolean) {
     super(message);
     this.name = '[ErrorType]';
   }
 }
 ```
 
-**Error Recovery:**
+**Recovery:**
 - [Error 1]: [Recovery strategy]
 - [Error 2]: [Recovery strategy]
 
@@ -131,22 +175,11 @@ class [ErrorType] extends Error {
 
 ## Performance Considerations
 
-| Metric | Target | Monitoring |
-|--------|--------|------------|
-| Latency | [X]ms | [How monitored] |
-| Throughput | [Y] req/s | [How monitored] |
-
----
-
-## Change Log References
-
-| Date | Change | Section | Status |
-|------|--------|---------|--------|
-| [date] | [description] | #[section] | [synced/pending] |
-
-See full details in `.pi/architecture/CHANGELOG.md`
+| Metric | Target | Strategy |
+|--------|--------|----------|
+| [Metric] | [Target] | [Strategy] |
 
 ---
 
 *Last updated: [date]*
-*Module version: [version]*
+*Module version: [version]*