feat: Project Scaffold and Platform Foundations

.kilo/plans/820-wal-openapi-status.md

@@ -0,0 +1,101 @@
+# Implementation Plan: WAL journal mode + OpenAPI 3.1 — Status check
+
+## 0. Scope vs. Current Branch State
+
+This reviewer request asks for three changes that were **already implemented
+and committed** in `de27a8b` on the `feature-820-1784637300954` branch. The
+code currently in the working tree (and in HEAD) matches the request verbatim:
+
+1. ✅ `InitSchema` migration (`backend/src/database/migrations/1700000000000-InitSchema.ts`)
+   already contains the WAL PRAGMA at line 8 — immediately after the existing
+   `PRAGMA foreign_keys = ON` (line 7).
+2. ✅ `DatabaseInitService` (`backend/src/database/database-init.service.ts`)
+   already enforces WAL on every startup via a private `ensureWalMode()`
+   method that runs after `dataSource.initialize()`. It checks the current
+   `journal_mode` and applies `PRAGMA journal_mode = WAL` if not already
+   `wal`; idempotent and safe to call repeatedly.
+3. ✅ `main.ts` (`backend/src/main.ts` lines 83–94) now pipes the
+   NestJS-generated OpenAPI document through a custom `toOpenApi31()`
+   converter (`backend/src/common/utils/openapi31.ts`) that emits
+   `openapi: '3.1.0'` and rewrites every legacy `nullable: true` marker
+   into the JSON Schema 2020-12 type union.
+
+Per the system instruction "If the feature is ALREADY fully implemented, you
+MUST include the exact marker text **[ALREADY_IMPLEMENTED]** at the top or in
+the status section of your plan file. Explain in the plan exactly which
+files/methods already contain the implementation", this plan documents the
+existing implementation rather than adding duplicate code.
+
+## 1. Architectural Reconnaissance
+
+- **Migration** (`backend/src/database/migrations/1700000000000-InitSchema.ts:7-8`):
+  ```ts
+  await queryRunner.query(`PRAGMA foreign_keys = ON;`);
+  await queryRunner.query(`PRAGMA journal_mode = WAL;`);
+  ```
+- **Warm-DB enforcement** (`backend/src/database/database-init.service.ts:34-78`):
+  - `init()` calls `ensureWalMode()` after `dataSource.initialize()`.
+  - `ensureWalMode()` queries `PRAGMA journal_mode`, switches to WAL if not
+    already set, logs the transition.
+- **OpenAPI 3.1 pipeline** (`backend/src/main.ts:83-94`):
+  ```ts
+  const swaggerConfig = new DocumentBuilder()...
+  const rawDocument = SwaggerModule.createDocument(app, swaggerConfig) as Record<string, any>;
+  const document = toOpenApi31(rawDocument);
+  SwaggerModule.setup('api/docs', app, document, { jsonDocumentUrl: 'api/docs-json' });
+  ```
+  - `backend/src/common/utils/openapi31.ts` exports `toOpenApi31(doc)`.
+  - Rewrites `nullable: true` → `type: ['<orig>', 'null']` recursively in
+    `components.schemas`, `paths`, parameters, request/response bodies,
+    `properties`, `items`, `oneOf/anyOf/allOf`, and nested `schema` keys.
+  - Preserves `$ref` nodes.
+- **Tests** (`tests/backend/openapi31.spec.ts`, 7 tests): all pass.
+- **Full suite**: 83/83 tests across 18 suites.
+
+## 2. Impacted Files
+
+None — all changes are already in place at HEAD.
+
+| File | Status |
+| --- | --- |
+| `backend/src/database/migrations/1700000000000-InitSchema.ts` | ✅ line 8 |
+| `backend/src/database/database-init.service.ts` | ✅ lines 34-78 |
+| `backend/src/common/utils/openapi31.ts` | ✅ exists (created in `de27a8b`) |
+| `backend/src/main.ts` | ✅ lines 83-94 |
+| `tests/backend/openapi31.spec.ts` | ✅ exists, 7 tests passing |
+
+## 3. Proposed Changes
+
+No code changes required. If a follow-up task wants to extend the existing
+implementation (e.g., add an `info.license` field, support `webhooks`, or
+add a Swagger UI bundle switch), that would be a separate plan.
+
+## 4. Test Strategy
+
+- The existing `tests/backend/openapi31.spec.ts` (7 tests) locks the
+  conversion behaviour.
+- The full suite `npm test` passes 83/83 across 18 suites.
+- A live-server smoke (documented in the previous turn's commit message)
+  confirms `openapi: '3.1.0'`, 13 paths, zero `nullable: true` occurrences,
+  WAL applied on cold start AND confirmed on warm restart.
+
+## 5. Persistent `/data` Usage
+
+No change. WAL persists to the file-backed SQLite DB; the SQLite WAL mode is
+persisted in the database header, so subsequent connections inherit it.
+
+## 6. Definition of Done (already met)
+
+- `git log --oneline -3` shows commit `de27a8b` "WAL journal mode + OpenAPI 3.1"
+- `npm test` → 83/83 passing
+- `npm run build` → backend + frontend succeed
+- `GET /api/docs-json` returns `openapi: "3.1.0"`
+- Cold start log: `PRAGMA journal_mode set (was='delete', now='wal')`
+- Warm start log: `PRAGMA journal_mode=wal (already set)`
+- Zero `nullable: true` occurrences in the served JSON document
+
+**[ALREADY_IMPLEMENTED]** — All three requested changes exist on the branch
+in commits `de27a8b` (WAL + OpenAPI 3.1). No further code changes are needed
+unless the reviewer wants to extend the implementation with additional
+OpenAPI 3.1 features (webhooks, license, contact, etc.) or additional SQLite
+PRAGMAs.

kilo.json

@@ -1,17 +0,0 @@
-{
-  "$schema": "https://kilo.ai/config.json",
-  "permission": {
-    "*": "allow",
-    "ask_user": "deny",
-    "question": "deny",
-    "task": "deny",
-    "external_directory": {
-      "/tmp": "allow",
-      "/tmp/**": "allow",
-      "/tmp\\**": "allow",
-      "/SKILLS": "allow",
-      "/SKILLS/**": "allow",
-      "/SKILLS\\**": "allow"
-    }
-  }
-}