@massu/core 0.4.2 → 0.6.0

package/dist/hooks/post-tool-use.js

@@ -1606,9 +1606,66 @@ function storeSecurityScore(db, sessionId, filePath, riskScore, findings) {
 }
 
 // src/hooks/post-tool-use.ts
-import { readFileSync as readFileSync5, existsSync as existsSync6 } from "fs";
+import { readFileSync as readFileSync6, existsSync as existsSync7 } from "fs";
 import { join as join2 } from "path";
+import { parse as parseYaml3 } from "yaml";
+
+// src/memory-file-ingest.ts
+import { readFileSync as readFileSync5, existsSync as existsSync6, readdirSync } from "fs";
 import { parse as parseYaml2 } from "yaml";
+function ingestMemoryFile(db, sessionId, filePath) {
+  if (!existsSync6(filePath)) return "skipped";
+  const content = readFileSync5(filePath, "utf-8");
+  const basename2 = (filePath.split("/").pop() ?? "").replace(".md", "");
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  let name = basename2;
+  let description = "";
+  let type = "discovery";
+  let confidence;
+  if (frontmatterMatch) {
+    try {
+      const fm = parseYaml2(frontmatterMatch[1]);
+      name = fm.name ?? basename2;
+      description = fm.description ?? "";
+      type = fm.type ?? "discovery";
+      confidence = fm.confidence != null ? Number(fm.confidence) : void 0;
+    } catch {
+    }
+  }
+  const obsType = mapMemoryTypeToObservationType(type);
+  const importance = confidence != null ? Math.max(1, Math.min(5, Math.round(confidence * 4 + 1))) : 4;
+  const bodyMatch = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)/);
+  const body = bodyMatch ? bodyMatch[1].trim().slice(0, 500) : "";
+  const title = `[memory-file] ${name}`;
+  const detail = description ? `${description}
+
+${body}` : body;
+  const existing = db.prepare(
+    "SELECT id FROM observations WHERE title = ? LIMIT 1"
+  ).get(title);
+  if (existing) {
+    db.prepare("UPDATE observations SET detail = ?, importance = ? WHERE id = ?").run(detail, importance, existing.id);
+    return "updated";
+  } else {
+    addObservation(db, sessionId, obsType, title, detail, { importance });
+    return "inserted";
+  }
+}
+function mapMemoryTypeToObservationType(memoryType) {
+  switch (memoryType) {
+    case "user":
+    case "feedback":
+      return "decision";
+    case "project":
+      return "feature";
+    case "reference":
+      return "discovery";
+    default:
+      return "discovery";
+  }
+}
+
+// src/hooks/post-tool-use.ts
 var seenReads = /* @__PURE__ */ new Set();
 var currentSessionId = null;
 async function main() {
@@ -1705,6 +1762,18 @@ async function main() {
         }
       } catch (_memoryErr) {
       }
+      try {
+        if (tool_name === "Edit" || tool_name === "Write") {
+          const filePath = tool_input.file_path ?? "";
+          if (filePath && filePath.includes("/memory/") && filePath.endsWith(".md")) {
+            const basename2 = filePath.split("/").pop() ?? "";
+            if (basename2 !== "MEMORY.md") {
+              ingestMemoryFile(db, session_id, filePath);
+            }
+          }
+        }
+      } catch (_memoryIngestErr) {
+      }
       try {
         if (tool_name === "Edit" || tool_name === "Write") {
           const filePath = tool_input.file_path ?? "";
@@ -1768,9 +1837,9 @@ function readConventions(cwd) {
   try {
     const projectRoot = cwd ?? process.cwd();
     const configPath = join2(projectRoot, "massu.config.yaml");
-    if (!existsSync6(configPath)) return defaults;
-    const content = readFileSync5(configPath, "utf-8");
-    const parsed = parseYaml2(content);
+    if (!existsSync7(configPath)) return defaults;
+    const content = readFileSync6(configPath, "utf-8");
+    const parsed = parseYaml3(content);
     if (!parsed || typeof parsed !== "object") return defaults;
     const conventions = parsed.conventions;
     if (!conventions || typeof conventions !== "object") return defaults;
@@ -1797,11 +1866,11 @@ function isKnowledgeSourceFile(filePath) {
 function checkMemoryFileIntegrity(filePath) {
   const issues = [];
   try {
-    if (!existsSync6(filePath)) {
+    if (!existsSync7(filePath)) {
       issues.push("MEMORY.md file does not exist after write");
       return issues;
     }
-    const content = readFileSync5(filePath, "utf-8");
+    const content = readFileSync6(filePath, "utf-8");
     const lines = content.split("\n");
     const MAX_LINES = 200;
     if (lines.length > MAX_LINES) {

package/dist/hooks/user-prompt.js

@@ -951,6 +951,22 @@ async function main() {
         }
       } catch (_knowledgeErr) {
       }
+      try {
+        const significantSignals = ["fix", "implement", "migrate", "refactor", "debug", "decision", "chose", "architecture", "redesign", "rewrite"];
+        const promptLower = prompt.toLowerCase();
+        const signalCount = significantSignals.filter((s) => promptLower.includes(s)).length;
+        if (signalCount >= 2) {
+          const memoryFileCount = db.prepare(
+            "SELECT COUNT(*) as count FROM observations WHERE session_id = ? AND title LIKE '[memory-file] %'"
+          ).get(session_id);
+          if (memoryFileCount.count === 0) {
+            process.stderr.write(
+              "\n[MEMORY REMINDER] Significant work detected but no memory files have been written.\nConsider saving learnings to memory/*.md files for future sessions.\n\n"
+            );
+          }
+        }
+      } catch (_memoryNagErr) {
+      }
     } finally {
       db.close();
     }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@massu/core",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "type": "module",
-  "description": "AI Engineering Governance MCP Server - Session memory, knowledge system, feature registry, code intelligence, rule enforcement, tiered tooling (12 free / 72 total), 43 workflow commands",
+  "description": "AI Engineering Governance MCP Server - Session memory, knowledge system, feature registry, code intelligence, rule enforcement, tiered tooling (12 free / 72 total), 55+ workflow commands, 11 agents, 20+ patterns",
   "main": "src/server.ts",
   "bin": {
     "massu": "./dist/cli.js"
@@ -32,6 +32,10 @@
     "!src/__tests__/**",
     "dist/**/*",
     "commands/**/*",
+    "agents/**/*",
+    "patterns/**/*",
+    "protocols/**/*",
+    "reference/**/*",
     "LICENSE"
   ],
   "keywords": [

package/patterns/build-patterns.md

@@ -0,0 +1,302 @@
+# Build Patterns
+
+**Purpose**: Patterns for resolving build issues in Next.js applications with Prisma, native modules, and Edge Runtime.
+
+**When to Read**: When encountering build errors, hangs, or warnings. Before adding heavy dependencies.
+
+---
+
+## Client/Server Code Separation
+
+### The Problem
+
+PrismaClient gets bundled into browser JavaScript when imported in client components, causing:
+- Build failures
+- Massive bundle sizes
+- Runtime errors
+
+### The Pattern: Domain Split Files
+
+```
+src/lib/services/
+├── contacts-types.ts     ← Types only (shared client + server)
+├── contacts-service.ts   ← Server logic (PrismaClient, DB queries)
+└── contacts-client.ts    ← Client-safe utilities (formatting, validation)
+```
+
+**Rule**: Files ending in `-service.ts` contain server code. Client components MUST NOT import them.
+
+```typescript
+// contacts-types.ts — SAFE for client import
+export interface Contact {
+  id: string;
+  name: string;
+  email: string;
+}
+
+export type ContactCreateInput = {
+  name: string;
+  email: string;
+};
+
+// contacts-service.ts — SERVER ONLY
+import { db } from '@/lib/db';
+
+export async function getContacts(): Promise<Contact[]> {
+  return db.contacts.findMany();
+}
+```
+
+### Detection
+
+```bash
+# Find client components importing server code
+grep -rn "from '@/lib/db'" src/components/ --include="*.tsx"
+# Expected: 0 matches
+
+# Find barrel exports that leak server code
+grep -rn "export \* from.*service" src/lib/
+# Check if any client component imports the barrel
+```
+
+---
+
+## Native Module Externalization
+
+### The Problem
+
+Modules like `jsdom`, `canvas`, `sharp`, and `puppeteer` contain native binaries that cannot be bundled by webpack/turbopack. They cause build hangs or failures.
+
+### The Pattern
+
+**Step 1: Add to `serverExternalPackages` in `next.config.js`:**
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  serverExternalPackages: [
+    'jsdom', 'canvas', 'sharp', 'puppeteer', 'puppeteer-core',
+    '@sparticuz/chromium', 'pdfkit', 'pdf-parse'
+  ],
+};
+```
+
+**Step 2: Add webpack externals as fallback:**
+```javascript
+webpack: (config, { isServer }) => {
+  if (isServer) {
+    config.externals = config.externals || [];
+    config.externals.push({
+      jsdom: 'commonjs jsdom',
+      canvas: 'commonjs canvas',
+      sharp: 'commonjs sharp',
+    });
+  }
+  return config;
+},
+```
+
+**Step 3: Use dynamic imports:**
+```typescript
+// WRONG - Static import causes build issues
+import { JSDOM } from 'jsdom';
+
+// CORRECT - Dynamic import
+const { JSDOM } = await import('jsdom');
+```
+
+### Known Problematic Packages
+
+| Package | Issue | Solution |
+|---------|-------|---------|
+| `jsdom` | ESM + native deps | Dynamic import + externalize |
+| `canvas` | Native binary | Externalize |
+| `sharp` | Native binary | serverExternalPackages |
+| `puppeteer` | Chromium binary | Externalize + dynamic import |
+| `cheerio` | Heavy dependency tree | Dynamic import |
+| `pdfkit` | Native deps | Externalize |
+
+---
+
+## Edge Runtime Compatibility
+
+### The Rule
+
+Files that run in Edge Runtime (middleware, edge functions) CANNOT use Node.js APIs.
+
+**Banned in Edge Runtime:**
+- `fs` / `path` / `crypto` (Node.js builtins)
+- `pino` / `winston` (logging libraries with Node.js deps)
+- `PrismaClient` (requires Node.js)
+- Any package that imports Node.js builtins
+
+### Detection
+
+```bash
+# Check middleware for Node.js imports
+grep -rn "require('fs')\|require('path')\|require('crypto')" src/middleware.ts
+# Expected: 0 matches
+
+# Check for logging library imports in edge files
+grep -rn "from 'pino'\|from 'winston'" src/middleware.ts
+# Expected: 0 matches
+```
+
+### Alternative for Edge Runtime
+
+```typescript
+// WRONG - pino in middleware
+import pino from 'pino';
+
+// CORRECT - console in middleware (Edge Runtime safe)
+console.log('[middleware]', 'Processing request');
+
+// CORRECT - Use Web Crypto API instead of Node crypto
+const hash = await crypto.subtle.digest('SHA-256', data);
+```
+
+---
+
+## Import Chain Protection
+
+### The Problem
+
+Even `import type` triggers webpack/turbopack analysis of the entire module graph. If a type-only import points to a file that imports heavy dependencies, the bundler will try to resolve them.
+
+### The Pattern
+
+```typescript
+// WRONG - Type import still triggers analysis of heavy-deps.ts
+import type { HeavyType } from '@/lib/heavy-deps';
+
+// CORRECT - Inline the type definition
+interface HeavyType {
+  id: string;
+  data: Record<string, unknown>;
+}
+```
+
+### Detection
+
+```bash
+# Find imports from known heavy modules in client code
+grep -rn "from '@/lib/db'" src/components/ --include="*.tsx"
+grep -rn "from '@/lib/services/.*-service'" src/components/ --include="*.tsx"
+# Expected: 0 matches for both
+```
+
+---
+
+## Build Warnings
+
+### Zero-Warning Builds
+
+All builds MUST produce zero warnings. Common warning sources and fixes:
+
+| Warning | Cause | Fix |
+|---------|-------|-----|
+| CSS color deprecation | Hardcoded hex/rgb values | Use CSS variables: `var(--color-name)` |
+| Unused variable | Dead code | Remove or prefix with `_` |
+| Missing key prop | Map without key | Add `key={item.id}` |
+| React hook deps | Missing useEffect dependency | Add to dependency array or wrap in useCallback |
+
+### Semantic Color Classes
+
+Use semantic CSS classes instead of hardcoded colors:
+
+```css
+/* WRONG */
+.badge { color: #22c55e; }
+
+/* CORRECT */
+.badge-primary { color: var(--color-primary); }
+.badge-success { color: var(--color-success); }
+.badge-warning { color: var(--color-warning); }
+.badge-error { color: var(--color-error); }
+```
+
+---
+
+## next-intl Setup
+
+If using next-intl for internationalization, ALL three pieces are required:
+
+1. **Plugin in `next.config.js`:**
+```javascript
+const withNextIntl = require('next-intl/plugin')();
+module.exports = withNextIntl(nextConfig);
+```
+
+2. **`src/i18n/request.ts`:**
+```typescript
+import { getRequestConfig } from 'next-intl/server';
+export default getRequestConfig(async () => ({
+  locale: 'en',
+  messages: (await import(`../../messages/en.json`)).default
+}));
+```
+
+3. **Provider in layout:**
+```typescript
+import { NextIntlClientProvider } from 'next-intl';
+<NextIntlClientProvider locale="en" messages={messages}>
+  {children}
+</NextIntlClientProvider>
+```
+
+Missing any one of these causes build failures.
+
+---
+
+## Suspense Boundaries
+
+Pages using `use(params)` or `useSearchParams()` MUST be wrapped in Suspense:
+
+```typescript
+// page.tsx
+import { Suspense } from 'react';
+
+export default function Page() {
+  return (
+    <Suspense fallback={<LoadingState />}>
+      <PageContent />
+    </Suspense>
+  );
+}
+```
+
+Without Suspense, static generation fails with cryptic errors.
+
+---
+
+## React Query v5 Callbacks
+
+```typescript
+// WRONG - onSuccess removed in React Query v5
+api.contacts.list.useQuery(undefined, {
+  onSuccess: (data) => setContacts(data),  // TypeScript error
+});
+
+// CORRECT - Destructure data directly
+const { data: contacts } = api.contacts.list.useQuery();
+```
+
+See `patterns/component-patterns.md` for the full React Query v5 pattern.
+
+---
+
+## Quick Reference
+
+| Rule | Pattern | Error if Violated |
+|------|---------|-------------------|
+| JSDOM dynamic import | `await import('jsdom')` | ESM error on Vercel |
+| Cheerio dynamic import | `await import('cheerio')` | Build hang on Vercel |
+| Import type from heavy deps | Inline types instead | Build hang (47+ min) |
+| Client/Server boundary | No `@/lib/db` in client | PrismaClient bundled |
+| next-intl setup | Plugin + request.ts + Provider | Build fails |
+| Suspense boundaries | Wrap `use(params)` pages | Static generation fails |
+| React Query v5 callbacks | Destructure data, no `onSuccess` in useQuery | TypeScript error |
+
+---
+
+**Document Status**: ACTIVE
+**Compliance**: Mandatory for all build-related work

package/patterns/component-patterns.md

@@ -0,0 +1,246 @@
+# Component Patterns
+
+**Purpose**: Standard patterns for UI components, forms, search inputs, and common interactive elements.
+
+**When to Read**: Before creating or modifying UI components.
+
+---
+
+## Toast Notifications
+
+### Standard Pattern: Sonner
+
+```typescript
+// CORRECT - Use Sonner directly
+import { toast } from 'sonner';
+
+// Success
+toast.success('Changes saved successfully');
+
+// Error
+toast.error('Failed to save changes');
+
+// With description
+toast.success('Contact created', {
+  description: 'John Doe has been added to your contacts'
+});
+
+// Promise toast (loading → success/error)
+toast.promise(mutation.mutateAsync(data), {
+  loading: 'Saving...',
+  success: 'Saved successfully',
+  error: 'Failed to save'
+});
+```
+
+### WRONG - Deprecated useToast Hook
+
+```typescript
+// WRONG - Legacy hook pattern, do NOT use
+const { toast } = useToast();
+toast({ title: 'Success', description: '...' });
+```
+
+**Why Sonner**: Single import, consistent API, auto-dismiss, better DX.
+
+---
+
+## Loading State
+
+```typescript
+import { LoadingState } from '@/components/common/LoadingState';
+
+// In page or component
+if (isLoading) {
+  return <LoadingState />;
+}
+
+// With custom message
+if (isLoading) {
+  return <LoadingState message="Loading contacts..." />;
+}
+```
+
+**Rule**: ALL loading states MUST use the `LoadingState` component. Never use raw spinners or "Loading..." text.
+
+---
+
+## Empty State
+
+```typescript
+import { EmptyState } from '@/components/common/EmptyState';
+
+// Basic
+if (data?.length === 0) {
+  return (
+    <EmptyState
+      title="No contacts found"
+      description="Add your first contact to get started"
+      action={{
+        label: "Add Contact",
+        onClick: () => setIsCreating(true)
+      }}
+    />
+  );
+}
+```
+
+**Rule**: ALL empty states MUST use the `EmptyState` component with actionable guidance.
+
+---
+
+## Form Inputs
+
+### Checkbox
+
+```typescript
+import { Checkbox } from '@/components/ui/checkbox';
+
+<div className="flex items-center space-x-2">
+  <Checkbox
+    id="agree"
+    checked={agreed}
+    onCheckedChange={setAgreed}
+  />
+  <label htmlFor="agree" className="text-sm">
+    I agree to the terms
+  </label>
+</div>
+```
+
+### Select
+
+```typescript
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+
+// CRITICAL: Never use value="" - causes React crash
+// Use __none__ for "no selection" option
+<Select value={status} onValueChange={setStatus}>
+  <SelectTrigger>
+    <SelectValue placeholder="Select status" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="__none__">All Statuses</SelectItem>
+    <SelectItem value="active">Active</SelectItem>
+    <SelectItem value="inactive">Inactive</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### DatePicker
+
+```typescript
+import { DatePicker } from '@/components/ui/date-picker';
+
+<DatePicker
+  date={selectedDate}
+  onSelect={setSelectedDate}
+  placeholder="Select date"
+/>
+```
+
+---
+
+## Search Input
+
+```typescript
+// Standard search input with consistent styling
+<Input
+  placeholder="Search..."
+  value={searchQuery}
+  onChange={(e) => setSearchQuery(e.target.value)}
+  className="page-search-input"
+/>
+```
+
+**Rule**: ALL search inputs MUST use the `page-search-input` class for consistent styling.
+
+---
+
+## Query Keys (React Query / tRPC)
+
+```typescript
+// CORRECT - Double brackets for tRPC query keys
+queryKey: [['contacts', 'list']]
+
+// WRONG - Single brackets
+queryKey: ['contacts', 'list']  // Will not match tRPC invalidation
+```
+
+**Why**: tRPC wraps query keys in an additional array. Using single brackets means `queryClient.invalidateQueries()` won't match.
+
+---
+
+## Form Validation (Zod + react-hook-form)
+
+```typescript
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+
+const schema = z.object({
+  name: z.string().min(1, 'Name is required'),
+  email: z.string().email('Invalid email'),
+  phone: z.string().optional(),
+});
+
+type FormData = z.infer<typeof schema>;
+
+const {
+  register,
+  handleSubmit,
+  formState: { errors },
+} = useForm<FormData>({
+  resolver: zodResolver(schema),
+});
+```
+
+**Rule**: ALL forms MUST use react-hook-form with Zod validation. See `patterns/form-patterns.md` for complete guide.
+
+---
+
+## ESLint Integration
+
+Custom ESLint rules enforce component patterns:
+
+| Rule | What It Catches |
+|------|----------------|
+| `no-deprecated-toast` | useToast() hook usage |
+| `no-raw-loading` | Inline loading spinners instead of LoadingState |
+| `no-empty-select-value` | `value=""` on Select.Item |
+| `no-single-bracket-querykey` | Single bracket query keys |
+
+### Detection Commands
+
+```bash
+# Check for deprecated toast usage
+grep -rn "useToast" src/ --include="*.tsx" --include="*.ts"
+# Expected: 0 matches (all should use sonner)
+
+# Check for empty select values
+grep -rn 'value=""' src/ --include="*.tsx"
+# Expected: 0 matches
+
+# Check for single bracket query keys
+grep -rn "queryKey: \['" src/ --include="*.tsx" --include="*.ts"
+# Expected: 0 matches (should be double brackets)
+```
+
+---
+
+## Related Documentation
+
+- **Form Patterns**: `patterns/form-patterns.md`
+- **UI Patterns**: `patterns/ui-patterns.md`
+- **Display Patterns**: `patterns/display-patterns.md`
+
+---
+
+**Document Status**: ACTIVE
+**Compliance**: Mandatory for all component work