@buba_71/levit 0.4.0 → 0.8.2

package/dist/tests/services/validation_service.test.js

@@ -0,0 +1,196 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = __importDefault(require("node:test"));
+const node_assert_1 = __importDefault(require("node:assert"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const validation_service_1 = require("../../src/services/validation_service");
+(0, node_test_1.default)("ValidationService reports errors if core directories are missing", () => {
+    const tempDir = fs_extra_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "validation-service-test-"));
+    // Validate empty dir
+    const result = validation_service_1.ValidationService.validate(tempDir);
+    // Expect invalid
+    node_assert_1.default.strictEqual(result.valid, false);
+    node_assert_1.default.ok(result.metrics.errors > 0, "Should have errors");
+    // Check specific error code presence
+    const missingDirs = result.issues.filter(i => i.code === "MISSING_DIRECTORY");
+    node_assert_1.default.ok(missingDirs.length > 0, "Should report missing directories");
+    fs_extra_1.default.rmSync(tempDir, { recursive: true, force: true });
+});
+(0, node_test_1.default)("ValidationService passes for valid structure", () => {
+    const tempDir = fs_extra_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "validation-service-succ-"));
+    // Scout scaffolding: .levit/features, .levit/decisions, .levit/handoff, core files
+    const dirs = [".levit/features", ".levit/decisions", ".levit/handoff"];
+    dirs.forEach(d => fs_extra_1.default.ensureDirSync(node_path_1.default.join(tempDir, d)));
+    const files = ["SOCIAL_CONTRACT.md", ".levit/AGENT_CONTRACT.md", ".levit/AGENT_ONBOARDING.md"];
+    files.forEach(f => fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, f), "content"));
+    const result = validation_service_1.ValidationService.validate(tempDir);
+    node_assert_1.default.strictEqual(result.valid, true);
+    fs_extra_1.default.rmSync(tempDir, { recursive: true, force: true });
+});
+(0, node_test_1.default)("ValidationService detects feature with invalid frontmatter", () => {
+    const tempDir = fs_extra_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "validation-service-test-"));
+    const featuresDir = node_path_1.default.join(tempDir, ".levit", "features");
+    fs_extra_1.default.ensureDirSync(featuresDir);
+    // Create core structure
+    fs_extra_1.default.ensureDirSync(node_path_1.default.join(tempDir, ".levit/decisions"));
+    fs_extra_1.default.ensureDirSync(node_path_1.default.join(tempDir, ".levit/handoff"));
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, "SOCIAL_CONTRACT.md"), "content");
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, ".levit/AGENT_CONTRACT.md"), "content");
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, ".levit/AGENT_ONBOARDING.md"), "content");
+    // Create feature with missing required fields
+    const invalidFeature = `---
+id: 001
+status: active
+# Missing: owner, last_updated, risk_level, depends_on
+
+# INTENT: Test Feature
+`;
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(featuresDir, "001-test.md"), invalidFeature);
+    const result = validation_service_1.ValidationService.validate(tempDir);
+    node_assert_1.default.strictEqual(result.valid, false);
+    const frontmatterErrors = result.issues.filter(i => i.code === "INVALID_FRONTMATTER");
+    node_assert_1.default.ok(frontmatterErrors.length > 0, "Should report invalid frontmatter");
+    fs_extra_1.default.rmSync(tempDir, { recursive: true, force: true });
+});
+(0, node_test_1.default)("ValidationService detects feature without INTENT header", () => {
+    const tempDir = fs_extra_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "validation-service-test-"));
+    const featuresDir = node_path_1.default.join(tempDir, ".levit", "features");
+    fs_extra_1.default.ensureDirSync(featuresDir);
+    // Create core structure
+    fs_extra_1.default.ensureDirSync(node_path_1.default.join(tempDir, ".levit/decisions"));
+    fs_extra_1.default.ensureDirSync(node_path_1.default.join(tempDir, ".levit/handoff"));
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, "SOCIAL_CONTRACT.md"), "content");
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, ".levit/AGENT_CONTRACT.md"), "content");
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, ".levit/AGENT_ONBOARDING.md"), "content");
+    // Create feature without INTENT header
+    const featureWithoutIntent = `---
+id: 001
+status: active
+owner: human
+last_updated: 2026-01-01
+risk_level: low
+depends_on: []
+---
+
+# Some other header
+`;
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(featuresDir, "001-test.md"), featureWithoutIntent);
+    const result = validation_service_1.ValidationService.validate(tempDir);
+    node_assert_1.default.strictEqual(result.valid, false);
+    const structureErrors = result.issues.filter(i => i.code === "INVALID_STRUCTURE");
+    node_assert_1.default.ok(structureErrors.length > 0, "Should report missing INTENT header");
+    fs_extra_1.default.rmSync(tempDir, { recursive: true, force: true });
+});
+(0, node_test_1.default)("ValidationService detects decision with invalid frontmatter", () => {
+    const tempDir = fs_extra_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "validation-service-test-"));
+    const decisionsDir = node_path_1.default.join(tempDir, ".levit/decisions");
+    fs_extra_1.default.ensureDirSync(decisionsDir);
+    // Create core structure
+    fs_extra_1.default.ensureDirSync(node_path_1.default.join(tempDir, ".levit", "features"));
+    fs_extra_1.default.ensureDirSync(node_path_1.default.join(tempDir, ".levit", "handoff"));
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, "SOCIAL_CONTRACT.md"), "content");
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, ".levit/AGENT_CONTRACT.md"), "content");
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, ".levit/AGENT_ONBOARDING.md"), "content");
+    // Create decision with invalid YAML
+    const invalidDecision = `---
+id: ADR-001
+status: draft
+owner: human
+last_updated: 2026-01-01
+risk_level: low
+depends_on: [invalid: yaml: syntax]
+---
+
+# ADR 001: Test
+`;
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(decisionsDir, "ADR-001-test.md"), invalidDecision);
+    const result = validation_service_1.ValidationService.validate(tempDir);
+    node_assert_1.default.strictEqual(result.valid, false);
+    const frontmatterErrors = result.issues.filter(i => i.code === "INVALID_FRONTMATTER");
+    node_assert_1.default.ok(frontmatterErrors.length > 0, "Should report invalid YAML");
+    fs_extra_1.default.rmSync(tempDir, { recursive: true, force: true });
+});
+(0, node_test_1.default)("ValidationService detects handoff with missing frontmatter", () => {
+    const tempDir = fs_extra_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "validation-service-test-"));
+    const handoffDir = node_path_1.default.join(tempDir, ".levit/handoff");
+    fs_extra_1.default.ensureDirSync(handoffDir);
+    // Create core structure
+    fs_extra_1.default.ensureDirSync(node_path_1.default.join(tempDir, ".levit", "features"));
+    fs_extra_1.default.ensureDirSync(node_path_1.default.join(tempDir, ".levit", "decisions"));
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, "SOCIAL_CONTRACT.md"), "content");
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, ".levit/AGENT_CONTRACT.md"), "content");
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, ".levit/AGENT_ONBOARDING.md"), "content");
+    // Create handoff without frontmatter
+    const handoffWithoutFrontmatter = `# Agent Handoff
+No frontmatter here
+`;
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(handoffDir, "2026-01-01-test.md"), handoffWithoutFrontmatter);
+    const result = validation_service_1.ValidationService.validate(tempDir);
+    node_assert_1.default.strictEqual(result.valid, false);
+    const frontmatterErrors = result.issues.filter(i => i.code === "INVALID_FRONTMATTER");
+    node_assert_1.default.ok(frontmatterErrors.length > 0, "Should report missing frontmatter");
+    fs_extra_1.default.rmSync(tempDir, { recursive: true, force: true });
+});
+(0, node_test_1.default)("ValidationService reports warning when no features exist", () => {
+    const tempDir = fs_extra_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "validation-service-test-"));
+    const featuresDir = node_path_1.default.join(tempDir, ".levit", "features");
+    fs_extra_1.default.ensureDirSync(featuresDir);
+    // Create core structure
+    fs_extra_1.default.ensureDirSync(node_path_1.default.join(tempDir, ".levit/decisions"));
+    fs_extra_1.default.ensureDirSync(node_path_1.default.join(tempDir, ".levit/handoff"));
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, "SOCIAL_CONTRACT.md"), "content");
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, ".levit/AGENT_CONTRACT.md"), "content");
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, ".levit/AGENT_ONBOARDING.md"), "content");
+    // No features in features directory
+    const result = validation_service_1.ValidationService.validate(tempDir);
+    node_assert_1.default.strictEqual(result.valid, true, "Should be valid (only warning)");
+    node_assert_1.default.ok(result.metrics.warnings > 0, "Should have warnings");
+    const noFeaturesWarning = result.issues.find(i => i.code === "NO_FEATURES");
+    node_assert_1.default.ok(noFeaturesWarning, "Should report no features warning");
+    fs_extra_1.default.rmSync(tempDir, { recursive: true, force: true });
+});
+(0, node_test_1.default)("ValidationService counts files scanned correctly", () => {
+    const tempDir = fs_extra_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "validation-service-test-"));
+    const featuresDir = node_path_1.default.join(tempDir, ".levit", "features");
+    fs_extra_1.default.ensureDirSync(featuresDir);
+    // Create core structure
+    fs_extra_1.default.ensureDirSync(node_path_1.default.join(tempDir, ".levit/decisions"));
+    fs_extra_1.default.ensureDirSync(node_path_1.default.join(tempDir, ".levit/handoff"));
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, "SOCIAL_CONTRACT.md"), "content");
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, ".levit/AGENT_CONTRACT.md"), "content");
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, ".levit/AGENT_ONBOARDING.md"), "content");
+    // Create valid feature
+    const validFeature = `---
+id: 001
+status: active
+owner: human
+last_updated: 2026-01-01
+risk_level: low
+depends_on: []
+---
+
+# INTENT: Test Feature
+`;
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(featuresDir, "001-test.md"), validFeature);
+    // Create valid decision
+    const validDecision = `---
+id: ADR-001
+status: draft
+owner: human
+last_updated: 2026-01-01
+risk_level: low
+depends_on: []
+---
+
+# ADR 001: Test Decision
+`;
+    fs_extra_1.default.writeFileSync(node_path_1.default.join(tempDir, ".levit/decisions", "ADR-001-test.md"), validDecision);
+    const result = validation_service_1.ValidationService.validate(tempDir);
+    node_assert_1.default.strictEqual(result.metrics.filesScanned, 2, "Should scan 2 files (1 feature + 1 decision)");
+    fs_extra_1.default.rmSync(tempDir, { recursive: true, force: true });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buba_71/levit",
-  "version": "0.4.0",
+  "version": "0.8.2",
   "description": "Hybrid starter kit for Antigravity projects",
   "author": "David BUBA",
   "license": "MIT",
@@ -19,14 +19,19 @@
   "main": "dist/src/init.js",
   "scripts": {
     "build": "tsc && chmod +x dist/bin/cli.js",
+    "prepublishOnly": "npm run build",
     "start": "node dist/bin/cli.js",
     "test": "npm run build && node --test dist/tests"
   },
   "dependencies": {
-    "fs-extra": "^11.2.0"
+    "fs-extra": "^11.2.0",
+    "js-yaml": "^4.1.1",
+    "chalk": "^4.1.2",
+    "cli-table3": "^0.6.5"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.11.0",
     "typescript": "^5.3.0"
   }

package/templates/default/.github/workflows/README.md

@@ -0,0 +1,56 @@
+# GitHub Actions Workflows
+
+This directory contains CI/CD workflows for levit-kit projects.
+
+## Available Workflows
+
+### `levit-validate.yml`
+
+Validates the levit-kit project structure on every push and pull request.
+
+**What it does**:
+- Runs `levit validate` to check project structure
+- Fails the build if validation errors are found
+- Uploads validation results as artifacts
+- Displays results in GitHub Actions summary
+
+**When it runs**:
+- On pushes to `main`, `master`, or `develop` branches
+- On pull requests targeting these branches
+
+**How to use**:
+1. This workflow is automatically included in levit-kit projects
+2. No configuration needed - it works out of the box
+3. Customize the `on:` section if you use different branch names
+
+**Customization**:
+Edit `.github/workflows/levit-validate.yml` to:
+- Change branch names
+- Add additional validation steps
+- Integrate with other workflows
+- Add notifications
+
+## Adding Custom Workflows
+
+You can add additional workflows for:
+- Feature status checks
+- Decision record validation
+- Handoff completeness checks
+- Custom evals
+
+Example structure:
+```yaml
+name: Custom Validation
+on: [push, pull_request]
+jobs:
+  custom-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: your-custom-script.sh
+```
+
+---
+
+*For more information, see the [levit-kit documentation](https://github.com/buba71/levit-kit).*
+

package/templates/default/.github/workflows/levit-validate.yml

@@ -0,0 +1,93 @@
+name: Validate Levit Project
+
+on:
+  push:
+    branches: [ main, master, develop ]
+  pull_request:
+    branches: [ main, master, develop ]
+
+jobs:
+  validate:
+    name: Validate levit-kit Structure
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      
+      - name: Validate levit-kit structure
+        id: validate
+        run: |
+          npx @buba_71/levit validate --json > validation.json 2>&1 || VALIDATION_EXIT=$?
+          if [ -n "$VALIDATION_EXIT" ]; then
+            echo "validation_failed=true" >> $GITHUB_OUTPUT
+          else
+            echo "validation_failed=false" >> $GITHUB_OUTPUT
+          fi
+      
+      - name: Display validation results
+        if: always()
+        run: |
+          if [ -f validation.json ]; then
+            echo "## Validation Results" >> $GITHUB_STEP_SUMMARY
+            echo '```json' >> $GITHUB_STEP_SUMMARY
+            cat validation.json >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+            
+            # Check for errors in JSON output
+            ERRORS=$(node -e "
+              try {
+                const fs = require('fs');
+                const content = fs.readFileSync('validation.json', 'utf8');
+                const lines = content.split('\\n').filter(l => l.trim());
+                let errorCount = 0;
+                for (const line of lines) {
+                  try {
+                    const obj = JSON.parse(line);
+                    // Check for ERROR level or validation failure messages
+                    if (obj.level === 'ERROR' || 
+                        (obj.message && (
+                          obj.message.toLowerCase().includes('error') ||
+                          obj.message.toLowerCase().includes('validation failed') ||
+                          obj.message.toLowerCase().includes('failed')
+                        ))) {
+                      errorCount++;
+                    }
+                  } catch (e) {
+                    // Non-JSON lines might be error messages
+                    if (line.toLowerCase().includes('error') || line.toLowerCase().includes('failed')) {
+                      errorCount++;
+                    }
+                  }
+                }
+                console.log(errorCount);
+              } catch (e) {
+                console.log('0');
+              }
+            " || echo "0")
+            
+            if [ "$ERRORS" -gt 0 ] || [ "${{ steps.validate.outputs.validation_failed }}" == "true" ]; then
+              echo "❌ Validation failed"
+              exit 1
+            else
+              echo "✅ Validation passed"
+            fi
+          else
+            echo "⚠️ No validation output found"
+            exit 1
+          fi
+      
+      - name: Upload validation results
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: validation-results
+          path: validation.json
+          if-no-files-found: ignore
+

package/templates/default/.gitlab-ci.yml

@@ -0,0 +1,73 @@
+# GitLab CI configuration for levit-kit validation
+# Add this to your existing .gitlab-ci.yml or use it as a separate file
+
+stages:
+  - validate
+
+levit-validate:
+  stage: validate
+  image: node:20
+  before_script:
+    - npm install -g @buba_71/levit
+  script:
+    - |
+      echo "🔍 Validating levit-kit project structure..."
+      levit validate --json > validation.json 2>&1 || VALIDATION_EXIT=$?
+      
+      if [ -f validation.json ]; then
+        echo "Validation results:"
+        cat validation.json
+        
+        # Count errors in JSON output
+        ERRORS=$(node -e "
+          try {
+            const fs = require('fs');
+            const content = fs.readFileSync('validation.json', 'utf8');
+            const lines = content.split('\\n').filter(l => l.trim());
+            let errorCount = 0;
+            for (const line of lines) {
+              try {
+                const obj = JSON.parse(line);
+                // Check for ERROR level or validation failure messages
+                if (obj.level === 'ERROR' || 
+                    (obj.message && (
+                      obj.message.toLowerCase().includes('error') ||
+                      obj.message.toLowerCase().includes('validation failed') ||
+                      obj.message.toLowerCase().includes('failed')
+                    ))) {
+                  errorCount++;
+                }
+              } catch (e) {
+                // Non-JSON lines might be error messages
+                if (line.toLowerCase().includes('error') || line.toLowerCase().includes('failed')) {
+                  errorCount++;
+                }
+              }
+            }
+            console.log(errorCount);
+          } catch (e) {
+            console.log('0');
+          }
+        " || echo "0")
+        
+        if [ "$ERRORS" -gt 0 ] || [ -n "$VALIDATION_EXIT" ]; then
+          echo "❌ Validation failed with errors"
+          exit 1
+        else
+          echo "✅ Validation passed"
+        fi
+      else
+        echo "⚠️ No validation output found"
+        exit 1
+      fi
+  artifacts:
+    when: always
+    paths:
+      - validation.json
+    expire_in: 1 week
+  only:
+    - merge_requests
+    - main
+    - master
+    - develop
+

package/templates/default/.levit/AGENT_CONTRACT.md

@@ -0,0 +1,34 @@
+# AGENT_CONTRACT.md
+
+> [!IMPORTANT]
+> This document defines the social and technical contract between the **Human Operator** and any **AI Agent** working on this project.
+
+## 1. Social Contract & Philosophy
+Our collaboration is based on the [SOCIAL_CONTRACT.md](file:///path/to/SOCIAL_CONTRACT.md) guidelines:
+- **Human in the Loop**: AI proposes, Human disposes.
+- **Cognitive Scaffolding**: Documentation is not a chore; it is the project's memory.
+
+## 2. Agent Mandates (MUST)
+- **Traceability**: Every code change MUST be mapped to an intention in `features/`.
+- **Decision Records**: Significant technical choices MUST be documented in `.levit/decisions/`.
+- **Handoffs**: Leave a clear handoff in `.levit/handoff/` when ending a session.
+- **Linter First**: Run `levit validate` before declaring a task finished.
+
+## 3. Agent Prohibitions (NEVER)
+- **No Shadow Changes**: Never modify code without updating the corresponding `INTENT` or `ADR` if the change is structural.
+- **No Deletion without Approval**: Never delete core infrastructure or large blocks of code without explicit confirmation.
+- **No Hallucinated Tech**: If an API or library is unclear, ask for clarification.
+
+## 4. Interaction Protocol
+1. **Read**: Check `AGENT_ONBOARDING.md` and the latest `HANDOFF`.
+2. **Plan**: Propose changes and get approval.
+3. **Execute**: Implement with tests.
+4. **Validate**: Run `levit validate`.
+5. **Handoff**: Document what was done.
+
+## 5. Machine-First Metadata
+Agents should prioritize reading and maintaining the YAML frontmatter in all documentation files.
+
+---
+*Status: ACTIVE | Schema: 1.1 | Last Updated: 2025-12-31*
+

package/templates/default/.levit/AGENT_ONBOARDING.md

@@ -11,14 +11,15 @@ This project is a hybrid workspace where humans define intentions and AI ensures
 ## 2. Navigation & Context
 To understand this project quickly, explore in this order:
 1.  `SOCIAL_CONTRACT.md`: Your ethical and operational boundaries.
-2.  `features/README.md`: The roadmap and logic of what we are building.
-3.  `agents/AGENTS.md`: Specific definitions of other roles if they exist.
-4.  `.levit/workflows/`: Step-by-step guides for common tasks.
+2.  `.levit/features/`: The roadmap and logic of what we are building.
+3.  `.levit/decisions/`: History of technical choices (ADRs).
+4.  `.levit/handoff/`: Specific context for your current mission.
+5.  `.levit/workflows/`: Step-by-step guides for common tasks.
 
 ## 3. Rules of Engagement
 - **Transparency**: If you are unsure about a decision, ask the human. Do not "hallucinate" architectural choices.
 - **Atomicity**: Keep your edits small and focused.
-- **Traceability**: Every major change should be linked to a feature defined in `features/`.
+- **Traceability**: Every major change should be linked to a feature defined in `.levit/features/`.
 - **Tests First**: Before submitting a complex change, check if tests exist in `tests/` and run them.
 
 ## 4. How to use Workflows

package/templates/default/{features → .levit/features}/INTENT.md

@@ -1,3 +1,12 @@
+---
+id: FEATURE-ID
+status: active
+owner: human
+last_updated: 2025-01-12
+risk_level: medium
+depends_on: []
+---
+
 # INTENT: [Feature Name]
 
 > Copy this file to create a new feature specification.

package/templates/default/{features → .levit/features}/README.md

@@ -3,8 +3,8 @@
 This directory contains the roadmap and the active specifications of the project.
 
 ## How to add a feature
-1. Copy [INTENT.md](./INTENT.md) to a new file (e.g., `001-my-feature.md`).
-2. Fill the "Human Intent" sections.
+1. Run `levit feature new` from the project root.
+2. Fill the "Human Intent" sections in the generated file.
 3. Let the Agent implement the technical details.
 
 ---