@delfos-ai/cli 1.0.3

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@delfos-ai/cli",
+  "version": "1.0.3",
+  "description": "Delfos CLI — AI Layer tools for the terminal",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": ["dist", "templates", "README.md"],
+  "bin": {
+    "delfos": "dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc --project tsconfig.build.json",
+    "test": "jest",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "test:coverage": "jest --coverage",
+    "typecheck": "tsc --noEmit --project tsconfig.build.json"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^4.2.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "chalk": "^5.6.2",
+    "chromadb": "^3.4.3",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.3",
+    "dotenv": "^17.4.2",
+    "gray-matter": "^4.0.3",
+    "inquirer": "^13.4.2",
+    "open": "^10.1.0",
+    "pino": "^10.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.0",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.2.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.3.0",
+    "ts-jest": "^29.1.4",
+    "ts-jest-mock-import-meta": "^1.3.2",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.6"
+  }
+}

package/templates/obsidian-vault/AI-Context/global-rules.md

@@ -0,0 +1,129 @@
+---
+title: Global Rules for AI Agents
+tags:
+  - ai-context
+  - rules
+created: {{date}}
+---
+
+# Global Rules for AI Agents
+
+## Repository Context
+
+This is the **Delfos AI Layers Backend** — a Node.js + Express.js + BullMQ API that serves as the centralized intelligence layer for autonomous and semi-autonomous development workflows.
+
+## Tech Stack
+
+- **Runtime**: Node.js 24+ LTS
+- **Framework**: Express.js 5.x
+- **Language**: TypeScript (strict mode, ESNext target)
+- **Job Queue**: BullMQ 5.x with Redis
+- **Validation**: Zod 3.x
+- **CMS**: Directus 11.17 (REST API)
+- **Cache**: Redis 7+
+- **Testing**: Jest + Supertest
+
+## Architecture Principles
+
+### Vertical Slice Architecture (VSA)
+
+All feature code MUST be in `features/<slice>/`. Global controllers or services are forbidden.
+
+### Feature Slice Structure
+
+```
+features/<slice>/
+  <slice>.route.ts       # Express router
+  <slice>.producer.ts    # BullMQ job enqueuer
+  <slice>.worker.ts      # Worker processor
+  <slice>.handler.ts     # Business logic
+  <slice>.schema.ts      # Zod validation schemas
+  index.ts               # Re-exports
+```
+
+### Forbidden Patterns
+
+- ❌ `src/controllers/` directory
+- ❌ `src/services/` directory
+- ❌ `console.log()` anywhere
+- ❌ `import { logger }` inside features
+- ❌ Installing AI SDKs (use native `fetch`)
+
+## Code Style
+
+| Element | Convention | Example |
+|---|---|---|
+| Files | kebab-case | `vault-scaffolder.ts` |
+| Classes/Interfaces | PascalCase | `ScaffoldResult` |
+| Functions/Variables | camelCase | `scaffoldVault` |
+| Constants | UPPER_SNAKE_CASE | `MAX_RETRIES` |
+| Feature dirs | lowercase-kebab | `memory-init/` |
+
+## TypeScript Rules
+
+- **No `any` types** - use explicit interfaces or Zod inference
+- **ESNext target** - never ES2022 or older
+- **`import type`** for type-only imports
+- **Zod-inferred types** for job payloads
+
+## Logging Rules
+
+1. **L1 — Redaction**: Never log sensitive fields (API keys, tokens, passwords)
+2. **L2 — Slice child**: Use `createSliceLogger('slice-name')` in features
+3. **L3 — Job child**: Use `createJobLogger(job, sliceLogger)` in workers
+4. **L4 — Transport**: JSON in production, pino-pretty in dev
+5. **L5 — Fatal handlers**: Register first in `main.ts`
+
+## BullMQ Rules
+
+- Use `bullConnection` for BullMQ primitives (db: 1)
+- Use `cacheConnection` for cache (db: 0)
+- `maxRetriesPerRequest: null` is mandatory for BullMQ
+- Every worker must have DLQ handler
+- QueueEvents requires `bullConnection.duplicate()`
+
+## Directus Integration
+
+- Include `Authorization: Bearer ${DIRECTUS_SERVICE_TOKEN}` on every request
+- Never prefix with `NEXT_PUBLIC_` (backend-only)
+- Filter `is_active` server-side
+
+## Security Rules
+
+- BYOK keys must be encrypted, never logged
+- Use native `fetch` for BYOK bridge (no AI SDKs)
+- Validate all inputs with Zod
+- Check for path traversal before file operations
+
+## Validation Commands
+
+Run after every implementation phase:
+```bash
+npm run build    # TypeScript compilation
+npm run lint     # ESLint
+npm test         # Jest tests
+```
+
+## Branch Rules
+
+- Working branch: `feat/<epic>-<story>`
+- Never commit or push to `main`
+
+## Commit Convention
+
+Follow Conventional Commits:
+```
+feat(backend): add migration worker
+fix(backend): resolve BullMQ timeout
+refactor(operations): extract validation
+chore(deps): update bullmq to 5.x
+```
+
+## Memory Integration Context
+
+This vault is integrated with Delfos AI Layer for memory context. AI agents can reference:
+- Technical decisions in `Decisions/`
+- Migration notes in `Migrations/`
+- Session summaries in `Sessions/`
+- Coding standards in `Patterns/coding-standards.md`
+- Architecture patterns in `Patterns/architecture-patterns.md`

package/templates/obsidian-vault/AI-Context/tool-preferences.md

@@ -0,0 +1,128 @@
+---
+title: Tool Preferences for AI Agents
+tags:
+  - ai-context
+  - preferences
+created: {{date}}
+---
+
+# Tool Preferences for AI Agents
+
+## Claude Code (Anthropic)
+
+### When to Use
+
+- Complex refactoring tasks requiring deep code understanding
+- Architecture decisions and design discussions
+- Code reviews with detailed explanations
+
+### Preferences
+
+- Use vertical slice architecture patterns
+- Follow the coding standards in `Patterns/coding-standards.md`
+- Always use `createSliceLogger` for logging
+- Validate with Zod schemas
+- Write tests following TDD principles
+
+### Commands
+
+- `/implement` - Execute backend user stories
+- `/review` - Production readiness review
+- `/fix` - Fix validation issues
+
+## Windsurf
+
+### When to Use
+
+- Rapid prototyping and feature development
+- Interactive coding sessions
+- Real-time collaboration
+
+### Preferences
+
+- Maintain VSA structure
+- Use TypeScript strict mode
+- Follow the established patterns
+- Run validation after changes
+
+### Integration
+
+- Use the Delfos MCP server for memory context
+- Reference decisions in `Decisions/`
+- Update session notes in `Sessions/`
+
+## Cursor
+
+### When to Use
+
+- Quick code fixes and small edits
+- Navigating large codebases
+- Understanding existing code
+
+### Preferences
+
+- Don't modify architecture without approval
+- Follow existing patterns
+- Ask before making breaking changes
+
+## Common Patterns Across All Tools
+
+### File Organization
+
+- Feature code in `features/<slice>/`
+- Infrastructure in `infrastructure/`
+- Shared utilities in `shared/`
+- Configuration in `config/`
+
+### Testing
+
+- Unit tests: mock I/O, test in isolation
+- Integration tests: real Redis/Directus
+- Functional tests: Supertest against `createApp()`
+
+### Validation
+
+Always run after changes:
+```bash
+npm run typecheck
+npm test
+```
+
+### Logging
+
+Never use `console.log()`. Always use:
+```typescript
+const logger = createSliceLogger('slice-name');
+```
+
+## MCP Server Integration
+
+The Delfos MCP server provides:
+- Memory context from this vault
+- Technical decisions reference
+- Coding standards lookup
+- Architecture patterns reference
+
+Configure in your IDE's MCP settings to enable AI agents to access this knowledge base.
+
+## Tool-Specific Notes
+
+### Claude Code
+
+- Best for architecture decisions and complex refactoring
+- Strong at understanding code context
+- Good at explaining trade-offs
+
+### Windsurf
+
+- Best for rapid development
+- Good for interactive sessions
+- Strong real-time collaboration
+
+### Cursor
+
+- Best for quick fixes
+- Good at code navigation
+- Fast code understanding
+
+Choose the right tool for the task at hand, but always maintain consistency with the established patterns and standards.

package/templates/obsidian-vault/Patterns/architecture-patterns.md

@@ -0,0 +1,147 @@
+---
+title: Architecture Patterns
+tags:
+  - patterns
+  - architecture
+created: {{date}}
+---
+
+# Architecture Patterns
+
+## Vertical Slice Architecture (VSA)
+
+### Concept
+
+Organize code by feature/business capability rather than technical layer. Each slice contains all code needed for that feature.
+
+### Benefits
+
+- High cohesion within features
+- Low coupling between features
+- Easier to delete or replace features
+- Clear ownership boundaries
+
+### Example Structure
+
+```
+src/features/memory-init/
+  vault-scaffolder.ts      # Business logic
+  memory-init.command.ts   # CLI entry point
+  __tests__/
+    vault-scaffolder.test.ts
+```
+
+## Repository Pattern
+
+### Concept
+
+Data access encapsulated in repository objects that abstract the underlying storage.
+
+### Implementation
+
+```typescript
+export const ObsidianConnectionsRepository = {
+  upsertConnection,
+  getByVaultPath,
+  updateLastSync,
+};
+```
+
+### Benefits
+
+- Single place for Directus API calls
+- Easy to mock in tests
+- Consistent error handling
+
+## Worker Pattern
+
+### Concept
+
+Long-running tasks processed asynchronously by BullMQ workers.
+
+### Standard Worker Configuration
+
+```typescript
+{
+  connection: bullConnection,
+  concurrency: 10,
+  lockDuration: 60_000,
+  stalledInterval: 30_000,
+  limiter: { max: 10, duration: 60_000, groupKey: 'byokKeyId' },
+}
+```
+
+### DLQ Handler (Mandatory)
+
+```typescript
+worker.on('failed', (job, err) => {
+  sliceLogger.error(
+    { jobId: job?.id, userId: job?.data?.userId, err },
+    '[slice-name] failed permanently — DLQ',
+  );
+});
+```
+
+## Logger Hierarchy
+
+### Pattern
+
+1. **Base logger**: Infrastructure-level (`src/infrastructure/logger/`)
+2. **Slice logger**: Feature-level (`createSliceLogger('slice-name')`)
+3. **Job logger**: Worker-level (`createJobLogger(job, sliceLogger)`)
+
+### Benefits
+
+- Automatic context propagation
+- Redaction of sensitive fields
+- Structured logging with consistent fields
+
+## Configuration Pattern
+
+### Concept
+
+Environment-based configuration validated with Zod.
+
+### Implementation
+
+```typescript
+export const MemoryConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  vault_path: z.string().min(1),
+  // ...
+});
+
+export type MemoryConfig = z.infer<typeof MemoryConfigSchema>;
+```
+
+### Benefits
+
+- Type-safe configuration
+- Runtime validation
+- Single source of truth
+
+## Dependency Injection
+
+### Concept
+
+Pass dependencies as parameters rather than importing directly.
+
+### Example
+
+```typescript
+// Good
+export async function scaffoldVault(
+  vaultPath: string,
+  templateDir: string,
+): Promise<ScaffoldResult>
+
+// Avoid
+import { TEMPLATE_DIR } from '../config';
+export async function scaffoldVault(vaultPath: string)
+```
+
+### Benefits
+
+- Easier testing (can inject mocks)
+- Clear dependencies
+- Flexible configuration

package/templates/obsidian-vault/Patterns/coding-standards.md

@@ -0,0 +1,90 @@
+---
+title: Coding Standards
+tags:
+  - patterns
+  - standards
+created: {{date}}
+---
+
+# Coding Standards
+
+## TypeScript
+
+- Use **strict mode** - no `any` types allowed
+- Use **Zod** for runtime validation with type inference
+- Use `import type` for type-only imports
+- Follow **ESNext** target (not ES2022 or older)
+
+## File Naming
+
+- **Files**: kebab-case (e.g., `vault-scaffolder.ts`)
+- **Classes/Interfaces**: PascalCase
+- **Functions/Variables**: camelCase
+- **Constants**: UPPER_SNAKE_CASE
+- **Feature directories**: lowercase-kebab (e.g., `memory-init/`)
+
+## Architecture
+
+### Vertical Slice Architecture (VSA)
+
+All feature code lives in `features/<slice>/`:
+```
+features/<slice>/
+  <slice>.route.ts       # Express router
+  <slice>.producer.ts    # BullMQ job enqueuer
+  <slice>.worker.ts      # Worker processor
+  <slice>.handler.ts     # Business logic
+  <slice>.schema.ts      # Zod validation schemas
+  index.ts               # Re-exports
+```
+
+### Forbidden Patterns
+
+- ❌ `src/controllers/` - violates VSA
+- ❌ `src/services/` - violates VSA
+- ❌ `console.log()` - always use Pino logger
+- ❌ Global services - keep in feature slices
+
+## Logging
+
+Use `createSliceLogger('slice-name')` in every feature file:
+```typescript
+import { createSliceLogger } from '../../infrastructure/logger';
+
+const logger = createSliceLogger('memory-init');
+```
+
+For workers, use `createJobLogger` as first call:
+```typescript
+const log = createJobLogger(job, sliceLogger);
+```
+
+## Error Handling
+
+- **Operational errors**: Log and handle gracefully
+- **Programmer errors**: Log fatal and exit
+- Always use structured logging with context
+
+## Testing
+
+- **Unit tests**: Mock all I/O, test in isolation
+- **Integration tests**: Use real Redis/Directus
+- **Functional tests**: Use Supertest against `createApp()`
+- Test files: `<slice>.test.ts` or in `__tests__/` folder
+
+## Security
+
+- Never log sensitive data (API keys, tokens, passwords)
+- Use environment variables for secrets
+- Validate all inputs with Zod schemas
+- Check for path traversal before file operations
+
+## Git Conventions
+
+Follow Conventional Commits:
+```
+feat(backend): add memory init command
+fix(backend): resolve vault path validation issue
+refactor(memory): extract scaffolding logic
+chore(deps): update bullmq to 5.x
+```

package/templates/obsidian-vault/Projects/example-project/Decisions/example-decision.md

@@ -0,0 +1,51 @@
+---
+title: Example Technical Decision
+tags:
+  - decision
+  - architecture
+created: {{date}}
+---
+
+# Technical Decision: Use BullMQ for Job Queueing
+
+## Context
+
+The application requires a reliable job queue for processing long-running tasks such as workspace migrations and AI layer generation. We evaluated several options including RabbitMQ, Kafka, and BullMQ.
+
+## Decision
+
+We selected **BullMQ** for the following reasons:
+
+1. **Redis-backed**: Leverages our existing Redis infrastructure
+2. **TypeScript-first**: Excellent TypeScript support with typed job payloads
+3. **Flows support**: Built-in flow producer for complex job dependencies
+4. **Monitoring**: Bull Board provides a built-in dashboard for monitoring
+5. **Performance**: Efficient job processing with configurable concurrency
+
+## Trade-offs
+
+**Pros:**
+- Simple to set up with existing Redis instance
+- Good TypeScript integration
+- Active community and maintenance
+
+**Cons:**
+- Requires Redis persistence configuration for durability
+- Less mature than RabbitMQ for very high throughput scenarios
+
+## Implementation Details
+
+- Queue configuration in `src/infrastructure/bullmq/`
+- Worker options: `concurrency: 10`, `lockDuration: 60_000`
+- Retry policy: 5 attempts with exponential backoff
+- DLQ handler on every worker for failed jobs
+
+## Alternatives Considered
+
+- **RabbitMQ**: More mature but adds infrastructure complexity
+- **Kafka**: Overkill for our use case, higher operational overhead
+- **PostgreSQL-based queues**: Limited performance compared to Redis
+
+## Status
+
+**Implemented** - {{date}}

package/templates/obsidian-vault/Projects/example-project/Migrations/example-migration.md

@@ -0,0 +1,85 @@
+---
+title: Example Migration Note
+tags:
+  - migration
+  - upgrade
+created: {{date}}
+---
+
+# Migration: Upgrade to BullMQ 5.x
+
+## Overview
+
+Upgrading the job queue system from BullMQ 4.x to 5.x to leverage new features and performance improvements.
+
+## Version
+
+- **From**: BullMQ 4.12.0
+- **To**: BullMQ 5.1.0
+
+## Breaking Changes
+
+1. **Connection options**: `maxRetriesPerRequest: null` is now mandatory for BullMQ connections
+2. **QueueEvents**: Requires dedicated connection via `bullConnection.duplicate()`
+3. **Flow API**: Minor changes to flow producer configuration
+
+## Migration Steps
+
+### 1. Update Dependencies
+
+```bash
+npm install bullmq@5.1.0
+npm install @bull-board/express@5.0.0
+```
+
+### 2. Update Redis Configuration
+
+Updated `src/infrastructure/redis/index.ts`:
+```typescript
+export const bullConnection = new Redis({
+  host: env.REDIS_HOST,
+  port: env.REDIS_PORT,
+  password: env.REDIS_PASSWORD,
+  db: 1,
+  maxRetriesPerRequest: null,  // Required for BullMQ 5.x
+  enableReadyCheck: false,
+});
+```
+
+### 3. Update QueueEvents
+
+Updated queue events to use duplicate connection:
+```typescript
+const queueEvents = new QueueEvents('queue-name', {
+  connection: bullConnection.duplicate(),
+});
+```
+
+### 4. Update Worker Configuration
+
+No changes required for worker options, but verified:
+```typescript
+{
+  connection: bullConnection,
+  concurrency: 10,
+  lockDuration: 60_000,
+  stalledInterval: 30_000,
+}
+```
+
+## Testing
+
+- Ran existing test suite: all tests passing
+- Manual verification of job processing: working correctly
+- Bull Board dashboard: accessible and showing jobs
+
+## Rollback Plan
+
+If issues arise, rollback steps:
+1. Revert package.json to BullMQ 4.12.0
+2. Remove `maxRetriesPerRequest: null` from Redis config
+3. Use original QueueEvents configuration
+
+## Status
+
+**Completed** - {{date}}