kodu 2.1.0 → 2.1.2

package/skills/liteend-init/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: liteend-init
+description: Bootstrap a new backend project from LiteEnd template with Docker, Prisma, and initial setup
+---
+
+You are a senior backend engineer. Your task is to initialize a new project from the LiteEnd template in a clean,
+reproducible way.
+
+## Input
+
+- project_name: string (required)
+- use_docker: boolean (default: true)
+- install_deps: boolean (default: true)
+
+## Steps
+
+1. Validate input
+
+- Check Node.js version: `node -v` must be >= 20. Fail with a clear message if not.
+- project_name must be a valid folder name (no spaces, no special chars except `-` and `_`)
+- fail if directory already exists and is not empty
+
+2. Scaffold project
+   Run:
+   npx degit uxname/liteend {{project_name}}
+
+3. Enter directory
+   cd {{project_name}}
+
+4. Initialize git (if .git does not exist)
+   git init
+   git add .
+   git commit -m "Initial commit"
+
+5. Setup environment
+   If .env does not exist:
+   cp .env.example .env
+
+6. Install dependencies (if install_deps = true)
+   npm install
+
+7. Start infrastructure (if use_docker = true)
+   docker compose up -d db redis
+
+8. Run database migrations
+   npm run db:migrations:apply
+
+9. Seed database
+   Check if `db:seed` key exists in package.json scripts. If yes:
+   npm run db:seed
+
+10. Verify setup
+    Launch dev server in background, then check endpoints:
+    npm run start:dev &
+     - GET /health → expect 200
+     - GET /swagger → expect 200
+    Stop the dev server after verification.
+
+11. Read project AGENTS.md
+    Read the file `AGENTS.md` in the project root to understand conventions,
+    available commands, and how to work with this project further.
+
+12. Output result
+
+Return:
+
+- project path
+- next steps:
+    - edit .env (DATABASE_URL, Redis config, etc.)
+    - run `docker compose up -d` (if skipped)
+    - `npm run start:dev`
+
+## Failure handling
+
+- If Node.js < 20 → stop immediately, instruct user to upgrade
+- If docker is not running → suggest fallback to manual PostgreSQL + Redis
+- If migrations fail → show prisma error and suggest checking DATABASE_URL
+- If port is busy → suggest changing PORT in .env
+
+## Notes
+
+- Requires Node.js LTS (>=20)
+- Requires Docker for full setup
+- Uses Prisma + PostgreSQL + Redis

package/skills/litefront-init/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: litefront-init
+description: Bootstrap a new frontend project from LiteFront template with Vite, React, GraphQL, and OIDC setup
+---
+
+You are a senior frontend engineer. Your task is to initialize a new project from the LiteFront template in a
+deterministic and production-aware way.
+
+## Input
+
+- project_name: string (required)
+- install_deps: boolean (default: true)
+- setup_env: boolean (default: true)
+- run_dev: boolean (default: true)
+
+## Steps
+
+1. Validate input
+
+- Check Node.js version: `node -v` must be >= 20. Fail with a clear message if not.
+- project_name must be a valid folder name (no spaces, no special chars except `-` and `_`)
+- fail if directory exists and is not empty
+
+2. Scaffold project
+   Run:
+   npx degit uxname/litefront {{project_name}}
+
+3. Enter directory
+   cd {{project_name}}
+
+4. Initialize git (if .git does not exist)
+   git init
+   git add .
+   git commit -m "Initial commit"
+
+5. Install dependencies (if install_deps = true)
+   npm install
+   After install, commit the generated lockfile:
+   git add package-lock.json && git commit -m "Add package-lock.json"
+
+6. Setup environment (if setup_env = true)
+   If .env does not exist:
+   cp .env.example .env
+
+   Warn user — these variables are REQUIRED before the app works:
+    - VITE_GRAPHQL_API_URL (GraphQL endpoint)
+    - VITE_BASE_URL
+    - VITE_OIDC_AUTHORITY
+    - VITE_OIDC_CLIENT_ID
+
+7. Generate GraphQL types
+   Only run if VITE_GRAPHQL_API_URL is set in .env AND the endpoint is reachable.
+   Run:
+   npm run gen
+
+   If endpoint is not reachable or gen fails:
+    - warn user that types generation was skipped
+    - instruct to run `npm run gen` manually once the backend is available
+
+8. Run dev server (if run_dev = true)
+   npm run start:dev
+
+9. Verify setup (only if run_dev = true)
+    - app is accessible at http://localhost:3000 (or PORT from .env)
+    - no critical runtime errors in console
+    - GraphQL client initializes
+
+10. Read project AGENTS.md
+    Read the file `AGENTS.md` in the project root to understand conventions,
+    available commands, and how to work with this project further.
+
+11. Output result
+
+Return:
+
+- project path
+- dev URL
+- checklist:
+    - configure .env (OIDC + GraphQL) if not done yet
+    - run `npm run gen` after every schema change
+    - run `npm run check` before commits
+
+## Failure handling
+
+- If Node.js < 20 → stop immediately, instruct user to upgrade
+- If npm install fails → suggest clearing cache: `npm cache clean --force`, then retry
+- If dev server fails → check PORT conflict, suggest changing PORT in .env
+- If GraphQL types fail → backend likely not running; skip gen and continue
+- If auth fails → OIDC misconfiguration; check VITE_OIDC_* vars
+
+## Notes
+
+- Requires Node.js LTS (>=20)
+- Designed to pair with LiteEnd backend
+- Uses Vite dev server (fast HMR)
+- GraphQL types MUST be regenerated on schema change

package/skills/project-setup-standardizer/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: project-setup-standardizer
+description: Enforces a unified, production-ready project setup (scripts, linting, testing, biome, lefthook) across any JS/TS project (backend, frontend, CLI, etc.). This skill MUST be invoked when initializing a new project.
+---
+
+**This skill is MANDATORY and must be invoked when creating a new project.**
+
+You are responsible for transforming an existing JavaScript/TypeScript project into a **production-ready, standardized
+structure**.
+
+Your goal is NOT to suggest — you MUST **apply and enforce** the conventions below.
+
+---
+
+## 1. PROJECT TYPE DETECTION
+
+Before making any changes, detect the project type using these signals:
+
+| Signal                                                           | Type     |
+|------------------------------------------------------------------|----------|
+| `dependencies` contains `react` or `vue`                         | frontend |
+| `devDependencies` contains `vite` (without react/vue)            | frontend |
+| `dependencies` contains `@nestjs/core` or `express` or `fastify` | backend  |
+| `bin` field exists in package.json                               | CLI      |
+| None of the above                                                | library  |
+
+Frontend projects get additional tools (stylelint, steiger). All other types share the base setup.
+
+---
+
+## 2. MIGRATION: REMOVE CONFLICTING TOOLS FIRST
+
+Before installing Biome, you MUST remove ESLint and Prettier if present:
+
+1. Delete config files: `.eslintrc*`, `.eslintignore`, `.prettierrc*`, `.prettierignore`
+2. Remove from `package.json` dependencies/devDependencies: `eslint`, `prettier`, and all `eslint-*` / `prettier-*`
+   packages
+3. Only after removal, proceed with Biome setup
+
+---
+
+## 3. PACKAGE.JSON SCRIPTS (MANDATORY STRUCTURE)
+
+You MUST normalize `package.json/scripts` into clearly separated sections using visual separators.
+
+Use this exact pattern:
+
+```json
+"scripts": {
+"________________ BUILD AND RUN ________________": "",
+"build": "...",
+"start:dev": "...",
+"start:prod": "...",
+"________________ FORMAT AND LINT ________________": "",
+"lint": "biome check",
+"lint:fix": "biome check --write",
+"lint:fix:unsafe": "biome check --write --unsafe",
+"ts:check": "tsc --noEmit",
+"knip": "knip --production",
+"check": "run-p ts:check lint:fix knip",
+"________________ TEST ________________": "",
+"test": "vitest run",
+"test:watch": "vitest",
+"test:cov": "vitest run --coverage",
+
+"________________ OTHER ________________": "",
+"prepare": "is-ci || lefthook install",
+"update": "npx npm-check-updates -u && rimraf node_modules package-lock.json && npm i",
+"postupdate": "npm run lint:fix && npm run check"
+}
+```
+
+If the project has distinct unit and e2e test layers, add:
+
+```json
+"test:unit": "...",
+"test:e2e": "...",
+"test:all": "run-s test:unit test:e2e"
+```
+
+Otherwise omit `test:all` — do not duplicate `test` under a different name.
+
+### Rules:
+
+- ALWAYS include `check` script → central quality gate
+- ALWAYS include `ts:check`; if no `tsconfig.json` exists, create a minimal one (see section 7)
+- ALWAYS include `knip` for unused exports/deps detection
+- ALWAYS include `lint:fix` in `check`
+- Use `run-p` (from `npm-run-all`) for parallel execution — never `npx run-p`
+- `prepare` MUST use `is-ci || lefthook install` to avoid CI failures when lefthook is not yet installed
+
+---
+
+## 4. FRONTEND-SPECIFIC REQUIREMENTS
+
+If project type is **frontend**, additionally include:
+
+```json
+"lint:fsd": "steiger ./src",
+"lint:style": "stylelint '**/*.{css,scss}'",
+"lint:style:fix": "npm run lint:style -- --fix",
+"check": "run-p lint:style ts:check lint:fix knip lint:fsd"
+```
+
+### Mandatory:
+
+- FSD validation via `steiger`
+- stylelint integration
+- include ALL checks in `check`
+
+---
+
+## 5. TESTING STANDARD (MANDATORY)
+
+Use **vitest only**.
+
+Rules:
+
+- NO jest
+- NO mixed frameworks
+- coverage MUST be supported via `test:cov`
+
+---
+
+## 6. BIOME CONFIG (MANDATORY)
+
+You MUST ensure `biome.json` exists with this content:
+
+```json
+{
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "lineEnding": "lf"
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single"
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "correctness": {
+        "noUnusedImports": "error",
+        "noUnusedVariables": "error",
+        "noUnusedFunctionParameters": "error"
+      }
+    }
+  },
+  "files": {
+    "includes": [
+      "**",
+      "!node_modules",
+      "!dist"
+    ]
+  },
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  }
+}
+```
+
+---
+
+## 7. LEFTHOOK (MANDATORY)
+
+You MUST write `lefthook.yml` with this exact content:
+
+```yaml
+pre-commit:
+  parallel: false
+  commands:
+    check:
+      run: npm run check
+
+pre-push:
+  parallel: false
+  commands:
+    test-all:
+      run: npm run test:all
+```
+
+Rules:
+
+- `check` (lint + types + knip) gates every commit
+- tests gate every push — `pre-push` does NOT re-run `check` (already gated at commit)
+- no bypassing allowed
+
+---
+
+## 8. MINIMAL TSCONFIG (if missing)
+
+If `tsconfig.json` does not exist, create it:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "src",
+    "*.ts"
+  ]
+}
+```
+
+---
+
+## 9. REQUIRED DEV DEPENDENCIES
+
+Ensure these are installed (add any that are missing):
+
+Core (all project types):
+
+- `@biomejs/biome`
+- `typescript`
+- `vitest`
+- `lefthook`
+- `is-ci`
+- `npm-run-all`
+- `knip`
+- `rimraf`
+- `npm-check-updates`
+
+Frontend only:
+
+- `stylelint`
+- `steiger`
+
+---
+
+## 10. ENFORCEMENT LOGIC
+
+You MUST follow this order:
+
+1. Detect project type (section 1)
+2. Remove conflicting tools (section 2)
+3. Rewrite `package.json` scripts (section 3, or 4 for frontend)
+4. Write/update `biome.json` (section 6)
+5. Write/update `lefthook.yml` (section 7)
+6. Create `tsconfig.json` if missing (section 8)
+7. Install missing dev dependencies (section 9)
+
+NEVER:
+
+- keep inconsistent scripts
+- mix tools (eslint + biome)
+- leave partial setup
+
+---
+
+## 11. OUTPUT FORMAT
+
+You must output:
+
+1. Updated `package.json` (only the `scripts` and `devDependencies` sections)
+2. `biome.json`
+3. `lefthook.yml`
+4. `tsconfig.json` (if created)
+5. List of removed files and packages
+
+All configs must be **complete and copy-paste ready**.
+
+---
+
+## 12. PRINCIPLE
+
+Your job is to enforce:
+
+- determinism
+- reproducibility
+- zero-config onboarding
+- strict quality gates
+
+If something is ambiguous — choose the stricter option.

package/src/core/config/config.service.ts

@@ -19,13 +19,10 @@ export class ConfigService {
     const explorer = lilconfigSync('kodu', { searchPlaces: ['kodu.json'] });
     const result = explorer.search(process.cwd());
 
-    if (!result || result.isEmpty || !result.config) {
-      this.terminate(
-        'kodu.json not found. Create it in the project root to configure kodu.',
-      );
-    }
+    const rawConfig =
+      result && !result.isEmpty && result.config ? result.config : {};
 
-    const parsed = configSchema.safeParse(result.config);
+    const parsed = configSchema.safeParse(rawConfig);
 
     if (!parsed.success) {
       console.error(pc.red('kodu.json is invalid:'));

package/tsconfig.build.json

@@ -1,4 +1,7 @@
 {
   "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false
+  },
   "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
 }

package/tsconfig.json

@@ -1,5 +1,6 @@
 {
   "compilerOptions": {
+    "target": "ES2023",
     "module": "nodenext",
     "moduleResolution": "nodenext",
     "resolvePackageJsonExports": true,
@@ -10,16 +11,18 @@
     "emitDecoratorMetadata": true,
     "experimentalDecorators": true,
     "allowSyntheticDefaultImports": true,
-    "target": "ES2023",
     "sourceMap": true,
     "outDir": "./dist",
     "baseUrl": "./",
     "incremental": true,
     "skipLibCheck": true,
+    "strict": true,
     "strictNullChecks": true,
     "forceConsistentCasingInFileNames": true,
     "noImplicitAny": false,
+    "noEmit": true,
     "strictBindCallApply": false,
     "noFallthroughCasesInSwitch": false
-  }
+  },
+  "include": ["src", "*.ts"]
 }

package/dist/scripts/generate-json-schema.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/scripts/generate-json-schema.js

@@ -1,17 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const promises_1 = require("node:fs/promises");
-const execa_1 = require("execa");
-const config_schema_1 = require("../src/core/config/config.schema");
-async function main() {
-    const schema = config_schema_1.configSchema.toJSONSchema();
-    const schemaString = JSON.stringify(schema, null, 2);
-    await (0, promises_1.writeFile)('kodu.schema.json', schemaString, 'utf8');
-    await (0, execa_1.execa)('biome', ['format', '--write', 'kodu.schema.json']);
-    console.log('✅ JSON schema generated: kodu.schema.json');
-}
-main().catch((error) => {
-    console.error(error);
-    process.exitCode = 1;
-});
-//# sourceMappingURL=generate-json-schema.js.map

package/dist/scripts/generate-json-schema.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"generate-json-schema.js","sourceRoot":"","sources":["../../scripts/generate-json-schema.ts"],"names":[],"mappings":";;AAAA,+CAA6C;AAC7C,iCAA8B;AAC9B,oEAAgE;AAEhE,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,4BAAY,CAAC,YAAY,EAAE,CAAC;IAC3C,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAErD,MAAM,IAAA,oBAAS,EAAC,kBAAkB,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;IAC1D,MAAM,IAAA,aAAK,EAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAEhE,OAAO,CAAC,GAAG,CAAC,2CAA2C,CAAC,CAAC;AAC3D,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACrB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}