telo3-ai 5.0.7 → 6.2.0

package/src/validate.js

@@ -0,0 +1,220 @@
+/**
+ * Context validation: required sections, unfilled placeholders,
+ * accidental secrets (reported by line, never by value), staleness.
+ * @license MIT
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { CONTEXT_DOCS, findContextDir } from './find-context.js';
+
+/**
+ * Required section keys per document. Matched case-insensitively as
+ * substrings of markdown headings. Templates and examples must satisfy these.
+ */
+export const REQUIRED_SECTIONS = {
+  'prd.md': [
+    'project overview',
+    'problem statement',
+    'target users',
+    'goals',
+    'functional requirements',
+    'success criteria',
+  ],
+  'architecture.md': [
+    'architecture overview',
+    'technology stack',
+    'project structure',
+    'architectural decisions',
+  ],
+  'rules.md': ['core principles', 'security', 'testing', 'validation'],
+  'design.md': ['design philosophy', 'colors', 'typography', 'components', 'accessibility'],
+  'tasks.md': ['current sprint', 'backlog', 'completed recently'],
+  'memory.md': ['current state', 'recently completed work', 'important decisions', 'known issues'],
+};
+
+const STALE_DAYS = 30;
+const CODE_EXTENSIONS = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.java',
+  '.rb', '.php', '.css', '.scss', '.html', '.vue', '.svelte', '.sql', '.sh',
+]);
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', 'coverage', '.next', '.nuxt', 'out', 'vendor', '__pycache__',
+  '.agents', '.qoder', '.claude', '.cursor', '.gemini', '_backup_v5.1.0', 'telo3-main', 'releases',
+]);
+
+/** Remove fenced code blocks so their contents are not scanned as prose. */
+function stripFences(text) {
+  let fence = null;
+  return text.split('\n').map(line => {
+    const match = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+    if (fence) {
+      if (match && match[1][0] === fence.char && match[1].length >= fence.size && !match[2].trim()) fence = null;
+      return '';
+    }
+    if (match) { fence = { char: match[1][0], size: match[1].length }; return ''; }
+    return line;
+  }).join('\n');
+}
+
+function headingsOf(text) {
+  const stripped = stripFences(text);
+  const matches = stripped.matchAll(/^#{1,6}\s+(.+)$/gm);
+  return [...matches].map((m) => m[1].trim());
+}
+
+/**
+ * Count unfilled placeholders: [TODO ...], [Project Name], [UNKNOWN].
+ * Excludes code fences, inline code, checkboxes, links, images, footnotes.
+ */
+function countPlaceholders(text) {
+  const stripped = stripFences(text).replace(/`[^`\n]*`/g, '')
+    .replace(/^ {0,3}\[[^\]\n]+\]:[^\n]*$/gm, '')
+    .replace(/\[[^\]\n]+\][ \t]*\[[^\]\n]*\]/g, '')
+    .replace(/\[\^[^\]\n]+\]/g, '');
+  let count = 0;
+  for (const match of stripped.matchAll(/\[([^[\]\n]+)\](?!\()/g)) {
+    const inner = match[1];
+    if (/^\s*[xX]?\s*$/.test(inner)) continue; // checkbox
+    if (/^\^\d+$/.test(inner)) continue; // footnote
+    count++;
+  }
+  return count;
+}
+
+const SECRET_PATTERNS = [
+  { label: 'credential assignment', re: /\b(?:api[_-]?key|apikey|[a-z0-9_]*(?:secret|token|password|passwd|pwd|access[_-]?key))["']?\s*[:=]\s*(?:['"][^'"\n]{8,}['"]|(?!\[|<|\$\{|process\.env\.|os\.environ|z\.)[^\s'",;}]{8,})/i },
+  { label: 'AWS access key', re: /\bAKIA[0-9A-Z]{16}\b/ },
+  { label: 'private key', re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/ },
+  { label: 'connection string with password', re: /\b(?:postgres|postgresql|mysql|mongodb|redis|amqp):\/\/[^\s:'"]+:[^\s'"]+@/i },
+  { label: 'GitHub token', re: /\bghp_[A-Za-z0-9]{36}\b/ },
+  { label: 'API secret key', re: /\bsk-[A-Za-z0-9]{20,}\b/ },
+];
+
+/** Redact detected credential lines and complete private-key blocks before context output. */
+export function redactSecrets(text) {
+  const withoutKeys = text.replace(/-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----[\s\S]*?(?:-----END (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----|$)/g, '[REDACTED: private key]');
+  return withoutKeys.split('\n').map(line => SECRET_PATTERNS.some(({ re }) => re.test(line)) ? '[REDACTED: possible credential]' : line).join('\n');
+}
+
+/** Scan every line (including code blocks) for accidental secrets. */
+function findSecrets(text) {
+  const found = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    for (const { label, re } of SECRET_PATTERNS) {
+      if (re.test(lines[i])) {
+        found.push({ line: i + 1, pattern: label });
+        break; // one finding per line is enough
+      }
+    }
+  }
+  return found;
+}
+
+/** Newest mtime among source-code files under root (bounded walk). */
+function newestCodeMtime(root, contextDir) {
+  let newest = null;
+  let visited = 0;
+  let incomplete = false;
+  const walk = (dir, depth) => {
+    if (depth > 8 || visited > 4000) { incomplete = true; return; }
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      incomplete = true;
+      return;
+    }
+    for (const entry of entries) {
+      if (visited > 4000) { incomplete = true; return; }
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name) || full === contextDir) continue;
+        walk(full, depth + 1);
+      } else if (entry.isFile()) {
+        visited++;
+        const dot = entry.name.lastIndexOf('.');
+        if (dot === -1 || !CODE_EXTENSIONS.has(entry.name.slice(dot))) continue;
+        try {
+          const mtime = statSync(full).mtimeMs;
+          if (newest === null || mtime > newest) newest = mtime;
+        } catch { incomplete = true; }
+      }
+    }
+  };
+  walk(root, 0);
+  return { mtime: newest, incomplete };
+}
+
+export function validateContext(dir) {
+  const root = resolve(dir);
+  const contextDir = findContextDir(root);
+  if (!contextDir) {
+    return {
+      valid: false,
+      dir: null,
+      files: [],
+      errors: [{ message: 'No project context found. Run `telo3 init` to create it.' }],
+      warnings: [],
+    };
+  }
+
+  const errors = [];
+  const warnings = [];
+  const files = [];
+  const scan = newestCodeMtime(root, contextDir);
+  const codeMtime = scan.mtime;
+  if (scan.incomplete) warnings.push({ message: 'Stale scan incomplete: traversal budget or inaccessible files; freshness is not fully verified.' });
+
+  for (const file of CONTEXT_DOCS) {
+    const path = join(contextDir, file);
+    if (!existsSync(path)) {
+      files.push({
+        file, exists: false, sections: 0,
+        missingSections: [...REQUIRED_SECTIONS[file]],
+        placeholders: 0, secrets: [], stale: null,
+      });
+      errors.push({ file, message: `Missing required document: ${file}` });
+      continue;
+    }
+
+    const content = readFileSync(path, 'utf8');
+    const headings = headingsOf(content);
+    const lower = headings.map((h) => h.toLowerCase());
+    const missingSections = REQUIRED_SECTIONS[file].filter(
+      (key) => !lower.some((h) => h.includes(key)),
+    );
+    const placeholders = countPlaceholders(content);
+    const secrets = findSecrets(content);
+
+    let stale = null;
+    if (codeMtime !== null) {
+      const docMtime = statSync(path).mtimeMs;
+      const diffDays = Math.floor((codeMtime - docMtime) / 86400000);
+      if (diffDays >= STALE_DAYS) stale = diffDays;
+    }
+
+    files.push({
+      file, exists: true, sections: headings.length,
+      missingSections, placeholders, secrets, stale,
+    });
+
+    for (const section of missingSections) {
+      errors.push({ file, message: `Missing required section: "${section}"` });
+    }
+    if (placeholders > 0) {
+      warnings.push({ file, message: `${placeholders} unfilled placeholder(s) — replace with real content` });
+    }
+    for (const secret of secrets) {
+      warnings.push({
+        file,
+        message: `Possible secret (${secret.pattern}) at line ${secret.line} — remove it; configure secrets via environment variables`,
+      });
+    }
+    if (stale !== null) {
+      warnings.push({ file, message: `Stale: last update predates recent code changes by ${stale} days` });
+    }
+  }
+
+  return { valid: errors.length === 0, dir: contextDir, files, errors, warnings, scanIncomplete: scan.incomplete };
+}

package/src/version.js

@@ -0,0 +1,12 @@
+/**
+ * Single source of truth for the version: package.json.
+ * @license MIT
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const pkgPath = fileURLToPath(new URL('../package.json', import.meta.url));
+
+export function getVersion() {
+  return JSON.parse(readFileSync(pkgPath, 'utf8')).version;
+}

package/templates/architecture.md

@@ -1,418 +1,37 @@
-# Architecture Documentation
+<!-- Lean skeleton. Document what IS built (code is truth for current state).
+     Update when structure/stack/data-flow changes. Required sections are validated. -->
 
-> **Purpose:** Define HOW the system works — tech stack, structure, data flow, and technical decisions.  
-> **Last Updated:** [Date]
-
----
+# Architecture — [Project Name]
 
 ## Architecture Overview
 
-### System Summary
-[High-level description of the architecture. Is this a monolith, microservices, JAMstack, serverless, client-server, etc.?]
-
-### Architecture Diagram
-```
-[ASCII diagram or reference to visual architecture diagram]
-
-Example:
-┌─────────────┐      ┌──────────────┐      ┌──────────────┐
-│   Browser   │─────▶│   Frontend   │─────▶│   Backend    │
-│  (Client)   │◀─────│  (Next.js)   │◀─────│  (API)       │
-└─────────────┘      └──────────────┘      └──────────────┘
-                             │                       │
-                             ▼                       ▼
-                     ┌──────────────┐      ┌──────────────┐
-                     │   Vercel     │      │  PostgreSQL  │
-                     └──────────────┘      └──────────────┘
-```
-
-### Core Principles
-[What are the guiding architectural principles?]
-
-- [Principle 1: e.g., "API-first design"]
-- [Principle 2: e.g., "Stateless services"]
-
----
+[TODO: System shape in 2-3 sentences — monolith/services, main components, how they talk.]
 
 ## Technology Stack
 
-### Runtime & Language
-- **Language:** [e.g., TypeScript, Python, Go]
-- **Runtime:** [e.g., Node.js 20, Python 3.11, Go 1.21]
-- **Package Manager:** [e.g., npm, pnpm, yarn, pip, cargo]
-
-### Frontend
-- **Framework:** [e.g., React 18, Vue 3, Svelte, Solid]
-- **Meta-framework:** [e.g., Next.js 14, Nuxt 3, SvelteKit, none]
-- **Styling:** [e.g., Tailwind CSS, CSS Modules, Styled Components]
-- **UI Library:** [e.g., shadcn/ui, Radix, Headless UI, custom]
-- **State Management:** [e.g., React Context, Zustand, Redux, Pinia, none]
-- **Form Handling:** [e.g., React Hook Form, Formik, native]
-- **Routing:** [e.g., Next.js App Router, React Router, Vue Router]
-
-### Backend
-- **Framework:** [e.g., Express, Fastify, FastAPI, Django, Rails, none]
-- **API Style:** [e.g., REST, GraphQL, tRPC, gRPC]
-- **API Documentation:** [e.g., OpenAPI/Swagger, GraphQL introspection]
-
-### Database
-- **Primary Database:** [e.g., PostgreSQL 16, MySQL, MongoDB, SQLite]
-- **ORM/Query Builder:** [e.g., Prisma, Drizzle, SQLAlchemy, none]
-- **Migrations:** [e.g., Prisma Migrate, Alembic, manual SQL]
-- **Caching:** [e.g., Redis, in-memory, none]
-
-### Authentication & Authorization
-- **Authentication Provider:** [e.g., NextAuth.js, Auth0, Clerk, Supabase Auth, custom]
-- **Session Management:** [e.g., JWT, cookies, sessions]
-- **Authorization Pattern:** [e.g., RBAC, ABAC, simple ownership]
-
-### External Services
-- **Email:** [e.g., Resend, SendGrid, AWS SES, none]
-- **File Storage:** [e.g., AWS S3, Cloudflare R2, local filesystem]
-- **Payment Processing:** [e.g., Stripe, none]
-- **Analytics:** [e.g., Vercel Analytics, Plausible, none]
-- **Error Tracking:** [e.g., Sentry, none]
-- **[Other services]:** [e.g., Algolia for search, Twilio for SMS]
-
-### Deployment & Infrastructure
-- **Hosting:** [e.g., Vercel, AWS, Railway, self-hosted]
-- **Database Hosting:** [e.g., Vercel Postgres, Neon, AWS RDS, self-hosted]
-- **CI/CD:** [e.g., GitHub Actions, none]
-- **Monitoring:** [e.g., Vercel Monitoring, Datadog, none]
-
-### Development Tools
-- **TypeScript:** [Yes/No]
-- **Linting:** [e.g., ESLint, Biome, none]
-- **Formatting:** [e.g., Prettier, Biome, none]
-- **Testing:** [e.g., Vitest, Jest, Playwright, Cypress, none]
-- **Git Hooks:** [e.g., Husky, lint-staged, none]
-
----
+| Layer | Choice | Why |
+|-------|--------|-----|
+| Frontend | [TODO] | [TODO] |
+| Backend | [TODO] | [TODO] |
+| Database | [TODO] | [TODO] |
+| Hosting | [TODO] | [TODO] |
 
 ## Project Structure
 
-### Directory Organization
-
-```
-project-root/
-├── project-context/          # Project context documents (Telo3)
-├── src/                      # Source code
-│   ├── app/                  # [Framework-specific structure]
-│   ├── components/           # React/Vue/Svelte components
-│   ├── lib/                  # Shared utilities
-│   ├── styles/               # Global styles
-│   └── types/                # TypeScript type definitions
-├── public/                   # Static assets
-├── tests/                    # Test files
-├── docs/                     # Additional documentation
-├── package.json              # Dependencies
-├── tsconfig.json             # TypeScript configuration
-└── [Other config files]
-```
-
-### Key Directories
-
-| Directory | Purpose | Naming Convention |
-|-----------|---------|-------------------|
-| `/src/app` | [e.g., Next.js App Router pages] | [e.g., kebab-case] |
-| `/src/components` | [e.g., Reusable React components] | [e.g., PascalCase] |
-| `/src/lib` | [e.g., Utility functions, API clients] | [e.g., camelCase] |
-| `/src/types` | [e.g., TypeScript interfaces and types] | [e.g., PascalCase] |
-
----
-
-## Data Architecture
-
-### Data Model
-[High-level description of core entities and relationships]
-
-```
-User ──< Posts ──< Comments
- │
- └──< Profile (1:1)
-```
-
-### Key Entities
-
-#### User
-- **Purpose:** [What this entity represents]
-- **Key Fields:** id, email, passwordHash, createdAt
-- **Relationships:** hasMany Posts, hasOne Profile
-- **Access Control:** [Who can read/write]
-
-#### [Entity Name]
-- **Purpose:** 
-- **Key Fields:** 
-- **Relationships:** 
-- **Access Control:** 
-
-### Data Flow
-
-#### Read Operations
-[How does data flow from database to user?]
-
-1. Client requests data via API
-2. API handler validates request
-3. Database query executed
-4. Data transformed/serialized
-5. Response returned to client
-
-#### Write Operations
-[How does data flow from user to database?]
-
-1. Client submits data via API
-2. API handler validates input
-3. Business logic executed
-4. Database transaction committed
-5. Response returned to client
-
----
-
-## API Architecture
-
-### API Style
-[REST, GraphQL, tRPC, etc.]
-
-### Base URL
-- **Production:** `https://api.example.com`
-- **Development:** `http://localhost:3000/api`
-
-### API Structure
-
-#### REST Endpoints (if applicable)
-| Endpoint | Method | Purpose | Auth Required |
-|----------|--------|---------|---------------|
-| `/api/users` | GET | List users | Yes |
-| `/api/users/:id` | GET | Get user | Yes |
-| `/api/users` | POST | Create user | No |
-
-#### GraphQL Schema (if applicable)
-[Reference to schema file or high-level schema description]
-
-#### tRPC Routers (if applicable)
-[List of tRPC routers and their purposes]
-
-### API Conventions
-- **Authentication:** [Bearer token, cookies, etc.]
-- **Error Format:** [Standard error response structure]
-- **Pagination:** [Cursor-based, offset-based, etc.]
-- **Rate Limiting:** [Policy if implemented]
-
----
-
-## Authentication & Authorization
-
-### Authentication Flow
-
-```
-1. User submits credentials
-2. Server validates credentials
-3. Server generates session/token
-4. Client stores session/token
-5. Client includes token in subsequent requests
-```
-
-### Session Management
-- **Storage:** [Where are sessions stored?]
-- **Lifetime:** [How long are sessions valid?]
-- **Refresh:** [How are sessions refreshed?]
-
-### Authorization Strategy
-[How are permissions enforced?]
-
-- **Public routes:** [List or criteria]
-- **Authenticated routes:** [List or criteria]
-- **Role-based access:** [Roles and permissions]
-
-### Security Boundaries
-[What are the security zones in the system?]
-
-- **Public:** [What is accessible without authentication?]
-- **Authenticated:** [What requires login?]
-- **Admin:** [What requires elevated privileges?]
-
----
-
-## State Management
-
-### Client-Side State
-[How is state managed in the frontend?]
-
-- **Global State:** [Tool/pattern used]
-- **Server State:** [How is server data cached/synchronized?]
-- **Form State:** [How are forms managed?]
-- **URL State:** [Is state stored in URL params?]
-
-### Server-Side State
-[How is state managed on the backend?]
-
-- **Session State:** [Where/how stored]
-- **Application State:** [Any in-memory state?]
-- **Database State:** [How is consistency maintained?]
-
----
-
-## External Service Integration
-
-### [Service Name]
-- **Purpose:** [Why is this service used?]
-- **Integration Method:** [API, SDK, webhook, etc.]
-- **Configuration:** [Environment variables required]
-- **Data Sharing:** [What data is sent to this service?]
-- **Fallback:** [What happens if service is unavailable?]
-
----
-
-## Environment Configuration
-
-### Environment Variables
-
-| Variable | Purpose | Required | Default |
-|----------|---------|----------|---------|
-| `DATABASE_URL` | PostgreSQL connection string | Yes | - |
-| `NEXTAUTH_SECRET` | NextAuth.js session secret | Yes | - |
-| `NEXTAUTH_URL` | Application URL | Yes | - |
-| `[OTHER]` | [Description] | Yes/No | [Value] |
-
-### Configuration Files
-- `package.json` — Dependencies and scripts
-- `tsconfig.json` — TypeScript compiler configuration
-- `.env.local` — Local environment variables (not committed)
-- `.env.example` — Environment variable template
-- `[Other config files]`
-
----
-
-## Build & Deployment
-
-### Build Process
-
-```bash
-# Development
-npm run dev
-
-# Production build
-npm run build
-
-# Start production server
-npm start
 ```
-
-### Deployment Strategy
-[How is the application deployed?]
-
-- **Environments:** Development, Staging, Production
-- **Deployment Method:** [Git-based, CI/CD pipeline, manual]
-- **Rollback Strategy:** [How to revert if deployment fails]
-
-### Database Migrations
-[How are database schema changes managed?]
-
-```bash
-# Create migration
-npm run db:migrate:create
-
-# Run migrations
-npm run db:migrate
-
-# Rollback migration
-npm run db:migrate:rollback
+[TODO: folder tree, ~10 lines, real paths]
 ```
 
----
+## Data Flow
 
-## Performance Considerations
-
-### Frontend Performance
-- **Code Splitting:** [Strategy used]
-- **Image Optimization:** [How images are optimized]
-- **Lazy Loading:** [What is lazy loaded]
-- **Caching Strategy:** [Browser caching, service workers]
-
-### Backend Performance
-- **Database Indexing:** [Key indexes]
-- **Query Optimization:** [Strategies used]
-- **Caching:** [What is cached and where]
-- **Rate Limiting:** [If implemented]
-
----
-
-## Security Architecture
-
-### Security Layers
-1. **Network Security:** [HTTPS, CORS, rate limiting]
-2. **Authentication:** [How users are authenticated]
-3. **Authorization:** [How access is controlled]
-4. **Input Validation:** [Where/how validation occurs]
-5. **Output Encoding:** [How XSS is prevented]
-6. **Secrets Management:** [How secrets are stored]
-
-### Known Security Boundaries
-[What are the trust boundaries in the system?]
-
-- [Boundary 1: e.g., "Client code cannot be trusted"]
-- [Boundary 2: e.g., "API validates all inputs"]
-
----
+[TODO: How a request/event moves through the system. Note auth boundaries and data stores.]
 
 ## Architectural Decisions
 
-[Document important architectural decisions here. Include the decision, rationale, alternatives, and trade-offs.]
-
-### [Decision Date]: [Decision Title]
-**Decision:** [What was decided?]  
-**Context:** [What was the situation?]  
-**Rationale:** [Why was this decided?]  
-**Alternatives Considered:** [What else was considered?]  
-**Trade-offs:** [What are the downsides?]  
-**Status:** [Accepted / Superseded / Deprecated]
-
----
-
-## Technical Debt
-
-[Document known technical debt that should be addressed]
-
-### High Priority
-- [ ] [Debt item 1] — Impact: [Description]
-
-### Medium Priority
-- [ ] [Debt item 2] — Impact: [Description]
-
-### Low Priority
-- [ ] [Debt item 3] — Impact: [Description]
-
----
+| Decision | Choice | Rationale | Date |
+|----------|--------|-----------|------|
+| [TODO] | [TODO] | [TODO] | [TODO] |
 
 ## Known Limitations
 
-[Document known limitations of the current architecture]
-
-- **[Limitation 1]:** [Description and impact]
-- **[Limitation 2]:** [Description and impact]
-
----
-
-## Future Architectural Considerations
-
-[Things to consider for future scaling or evolution]
-
-- [Consideration 1: e.g., "May need to split into microservices at 10x scale"]
-- [Consideration 2]
-
----
-
-## References
-
-- [Link to API documentation]
-- [Link to database schema]
-- [Link to deployment documentation]
-- [Link to third-party service documentation]
-
----
-
-## Document History
-
-| Date | Author | Changes |
-|------|--------|---------|
-| [Date] | [Name] | Initial version |
+- [TODO: constraints, tech debt, scale ceilings.]