@stonyx/orm 0.2.1-beta.2 → 0.2.1-beta.21

package/improvements.md

@@ -0,0 +1,139 @@
+# Code Improvements: @stonyx/orm
+
+> Audited: 2026-02-09 | Auto-generated by project-docs-auditor
+
+---
+
+## Summary
+
+The codebase is well-structured with clear separation of concerns and consistent patterns. The main areas for improvement are: a debug `console.log` left in production config, duplicated utility functions across multiple files, and documentation that has drifted from the actual code. The MySQL driver is well-tested and cleanly DI'd, but the JSON persistence side lacks equivalent test coverage.
+
+**Findings by priority:**
+| Priority | Count |
+|----------|-------|
+| High | 2 |
+| Medium | 6 |
+| Low | 5 |
+
+---
+
+## High Priority
+
+### [H1] Stray `console.log` in production config
+- **Category:** Debug Leak
+- **Files:** `config/environment.js`
+- **Lines:** L57
+- **Problem:** `console.log(MYSQL_HOST)` is left at the bottom of the environment config file. This will log the MySQL host (or `undefined`) on every application startup, leaking configuration details to stdout.
+- **Suggestion:** Remove the `console.log(MYSQL_HOST)` line entirely.
+- **Impact:** Eliminates unintended log noise and prevents leaking configuration values in production.
+
+### [H2] Duplicated `getRelationshipInfo()` function
+- **Category:** WET Code
+- **Files:** `src/orm-request.js` (L18-28), `src/mysql/schema-introspector.js` (L6-14), `src/meta-request.js` (L33-34)
+- **Problem:** The pattern of inspecting a function's `toString()` for `getRelationships('belongsTo',` or `getRelationships('hasMany',` is repeated in three separate files with slight variations. Each independently detects relationship type from a property.
+- **Suggestion:** Extract a shared `getRelationshipInfo(property)` function into `src/relationships.js` (which already acts as the relationship utility module) and import it from all three consumers.
+- **Impact:** Single source of truth for relationship detection. Changes to the detection pattern only need to happen in one place.
+
+---
+
+## Medium Priority
+
+### [M1] Duplicated `getOrSet` helper
+- **Category:** WET Code
+- **Files:** `src/has-many.js` (imports from `@stonyx/utils/object`), `src/belongs-to.js` (L4-7)
+- **Problem:** `belongs-to.js` defines its own local `getOrSet(map, key, defaultValue)` function identical to the one available from `@stonyx/utils/object` that `has-many.js` already imports.
+- **Suggestion:** Replace the local `getOrSet` in `belongs-to.js` with `import { getOrSet } from '@stonyx/utils/object'`.
+- **Impact:** Eliminates duplicated code and maintains consistency with `has-many.js`.
+
+### [M2] Duplicated `getCollectionKeys()` and `getDirPath()`
+- **Category:** WET Code
+- **Files:** `src/db.js` (L42-61), `src/migrate.js` (L7-26)
+- **Problem:** Both files contain identical `getCollectionKeys()` and `getDirPath()` functions. The migration module duplicated these from the DB class as standalone functions.
+- **Suggestion:** Export these methods from `src/db.js` (or extract into a shared `src/db-utils.js`) and import them in `src/migrate.js`.
+- **Impact:** Eliminates duplication and ensures migration logic always matches DB logic.
+
+### [M3] `TYPES` array missing `pendingBelongsTo`
+- **Category:** Bug Risk
+- **Files:** `src/relationships.js` (L43)
+- **Lines:** L43
+- **Problem:** `export const TYPES = ['global', 'hasMany', 'belongsTo', 'pending']` is missing `'pendingBelongsTo'`, which is a relationship type initialized in `src/main.js` (L48). The `TYPES` array is used by `store.unloadAllRecords()` (L75) for cleanup, meaning `pendingBelongsTo` entries won't be cleaned up when unloading all records for a model.
+- **Suggestion:** Add `'pendingBelongsTo'` to the `TYPES` array.
+- **Impact:** Prevents potential stale pending belongsTo references when unloading all records for a model.
+
+### [M4] `introspectModels` called repeatedly on every persist operation
+- **Category:** Performance
+- **Files:** `src/mysql/mysql-db.js` (L147, L193, L231)
+- **Problem:** `_persistCreate`, `_persistUpdate`, and `_persistDelete` all call `this.deps.introspectModels()` on every single write operation. Schema introspection iterates all models, creates instances, and inspects properties. Since model schemas don't change at runtime, this is unnecessary repeated work.
+- **Suggestion:** Cache the introspected schemas in `MysqlDB.init()` (or lazily on first access) and reuse the cached result in persist methods.
+- **Impact:** Reduces CPU overhead on every write operation, especially significant with frequent CRUD activity.
+
+### [M5] `startup()` also calls `introspectModels()` separately from `loadAllRecords()`
+- **Category:** Performance
+- **Files:** `src/mysql/mysql-db.js` (L69, L88)
+- **Problem:** `startup()` calls `introspectModels()` at L69 for drift detection, but `loadAllRecords()` (called at L62 inside the migration-apply branch) also calls `introspectModels()` at L88. When migrations are applied, `introspectModels()` runs three times: once in `loadAllRecords` (via init), once in reloaded `loadAllRecords`, and once for drift check.
+- **Suggestion:** Same as M4 — cache the result.
+- **Impact:** Reduces redundant schema introspection calls during startup.
+
+### [M6] No test coverage for JSON DB `save()` and `getRecord()` flows
+- **Category:** Test Gap
+- **Files:** `src/db.js`
+- **Problem:** The JSON file persistence layer (`DB` class) lacks unit tests for its core `save()`, `getRecord()`, `getRecordFromDirectory()`, `getRecordFromFile()`, and `validateMode()` methods. The MySQL driver has thorough unit tests via dependency injection, but the JSON DB has no equivalent.
+- **Suggestion:** Add unit tests for `src/db.js`, potentially using the same DI pattern used by `MysqlDB` to mock file operations.
+- **Impact:** Increases confidence in the JSON persistence path, which is the default storage mode.
+
+---
+
+## Low Priority
+
+### [L1] Documentation references non-existent files
+- **Category:** Stale Docs
+- **Files:** `.claude/index.md` (L38-39), `.claude/personal/outline.md` (L1107)
+- **Problem:** The `.claude/index.md` references `src/include-parser.js` and `src/include-collector.js` which don't exist — include parsing is inline in `src/orm-request.js`. The outline references `stonyx-bootstrap.cjs` which doesn't exist.
+- **Suggestion:** Remove the `include-parser.js` and `include-collector.js` references from `.claude/index.md` and the `stonyx-bootstrap.cjs` reference from the outline. Update the architecture section to point to `src/orm-request.js` for include logic.
+- **Impact:** Prevents confusion when navigating docs.
+
+### [L2] Outdated version in outline doc
+- **Category:** Stale Docs
+- **Files:** `.claude/personal/outline.md` (L1076)
+- **Problem:** Lists version as `0.1.0` but `package.json` shows `0.2.1-beta.1`.
+- **Suggestion:** Update or remove the version reference. Since `package.json` is the source of truth, the docs shouldn't duplicate it.
+- **Impact:** Minor — prevents stale version confusion.
+
+### [L3] Outline docs missing `./commands` and `./hooks` package exports
+- **Category:** Stale Docs
+- **Files:** `.claude/personal/outline.md` (L884-889)
+- **Problem:** The package.json `exports` section in the outline doc only shows `"."` and `"./db"`, but the actual `package.json` also exports `"./migrate"`, `"./commands"`, and `"./hooks"`.
+- **Suggestion:** Update the outline's package.json section to match the actual exports.
+- **Impact:** Minor — ensures docs reflect the full public API surface.
+
+### [L4] Outline references old event-based system
+- **Category:** Stale Docs
+- **Files:** `.claude/index.md` (L204)
+- **Problem:** States `@stonyx/events - Pub/sub event system (optional, not used for hooks)`. However, `@stonyx/events` is imported and `setup(eventNames)` is called in `src/main.js` (L91). The events are set up but the hooks system uses its own registry. This is confusing — events are initialized but the hooks use a separate middleware pattern.
+- **Suggestion:** Clarify that `@stonyx/events` is still initialized for event names during ORM setup, but the actual hook dispatch uses the middleware-based system in `src/hooks.js`.
+- **Impact:** Reduces confusion about the relationship between `@stonyx/events` and the hooks system.
+
+### [L5] Manual test scripts in project root
+- **Category:** Dead Code
+- **Files:** `test-hooks-with-logging.js`, `test-events-setup.js`, `test-hooks-manual.js`
+- **Problem:** Three manual test scripts remain in the project root from the hooks implementation. They were used to verify functionality when the test harness had linking issues, but are not part of the test suite and won't run via `npm test`.
+- **Suggestion:** Either move them to `test/manual/` or remove them if the hooks implementation is considered stable and the test harness issues are resolved.
+- **Impact:** Cleaner project root; reduces confusion about which test files are authoritative.
+
+---
+
+## Refactoring Roadmap
+
+**Quick wins (do first):**
+1. **H1** — Delete one line (`console.log(MYSQL_HOST)`) in config
+2. **M1** — Replace local `getOrSet` in `belongs-to.js` with import
+3. **M3** — Add `'pendingBelongsTo'` to `TYPES` array
+
+**Medium effort:**
+4. **H2** — Extract shared `getRelationshipInfo` into `relationships.js`
+5. **M2** — Extract shared `getCollectionKeys`/`getDirPath` from `db.js`
+
+**Longer term:**
+6. **M4/M5** — Cache introspected schemas in MysqlDB
+7. **M6** — Add DB unit tests
+8. **L1-L4** — Documentation cleanup pass

package/package.json

@@ -4,13 +4,16 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-beta.2",
+  "version": "0.2.1-beta.21",
   "description": "",
   "main": "src/main.js",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
-    "./db": "./src/exports/db.js"
+    "./db": "./src/exports/db.js",
+    "./migrate": "./src/migrate.js",
+    "./commands": "./src/commands.js",
+    "./hooks": "./src/hooks.js"
   },
   "repository": {
     "type": "git",
@@ -30,17 +33,25 @@
   },
   "homepage": "https://github.com/abofs/stonyx-orm#readme",
   "dependencies": {
-    "stonyx": "^0.2.2",
-    "@stonyx/events": "^0.1.0",
-    "@stonyx/cron": "^0.2.0"
+    "stonyx": "0.2.3-beta.4",
+    "@stonyx/events": "0.1.1-beta.5",
+    "@stonyx/cron": "0.2.1-beta.8"
+  },
+  "peerDependencies": {
+    "mysql2": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "mysql2": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@stonyx/rest-server": "^0.2.0",
-    "@stonyx/utils": "^0.2.2",
+    "@stonyx/rest-server": "0.2.1-beta.11",
+    "@stonyx/utils": "0.2.3-beta.4",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0"
   },
   "scripts": {
-    "test": "qunit --require ./stonyx-bootstrap.cjs"
+    "test": "stonyx test"
   }
 }

package/project-structure.md

@@ -0,0 +1,343 @@
+# Project Documentation: @stonyx/orm
+
+> Last audited: 2026-02-09 | Auto-generated by project-docs-auditor
+
+---
+
+## Table of Contents
+1. [Overview](#overview)
+2. [Tech Stack](#tech-stack)
+3. [Architecture](#architecture)
+4. [Directory Map](#directory-map)
+5. [Key Files Reference](#key-files-reference)
+6. [Data Flow](#data-flow)
+7. [API / Routes](#api--routes)
+8. [Database & Models](#database--models)
+9. [Authentication & Authorization](#authentication--authorization)
+10. [Configuration & Environment](#configuration--environment)
+11. [Development Guide](#development-guide)
+12. [Testing](#testing)
+13. [Deployment & CI/CD](#deployment--cicd)
+14. [Conventions & Standards](#conventions--standards)
+15. [Known Issues & Technical Debt](#known-issues--technical-debt)
+
+---
+
+## Overview
+
+A lightweight ORM for the Stonyx framework that provides structured data modeling with type-safe attributes, bidirectional relationships, serializers for third-party data normalization, and automatic REST API generation. Supports both JSON file-based persistence and MySQL as storage backends.
+
+## Tech Stack
+
+| Category | Technology | Version | Notes |
+|----------|-----------|---------|-------|
+| Language | JavaScript (ES Modules) | Node 24.13.0 | `"type": "module"` in package.json |
+| Framework | Stonyx | file ref | Core framework (peer dependency) |
+| Database (JSON) | Built-in `DB` class | N/A | File-based JSON persistence |
+| Database (SQL) | MySQL via mysql2 | ^3.0.0 | Optional peer dependency |
+| Test Framework | QUnit | ^2.24.1 | Via `stonyx test` runner |
+| Test Mocking | Sinon | ^21.0.0 | Stubs and spies |
+| Package Manager | pnpm | N/A | Local `file:` references for sibling packages |
+
+## Architecture
+
+The ORM follows a **singleton + registry** pattern. A single `Orm` instance manages models, serializers, and transforms. Records are stored in an in-memory `Store` (nested Maps) and optionally persisted to JSON files or MySQL.
+
+```
+                         ┌──────────────┐
+                         │   Orm (main) │  Singleton, initializes everything
+                         └──────┬───────┘
+              ┌────────────┬────┴────┬────────────┐
+              v            v         v            v
+         ┌────────┐  ┌─────────┐ ┌────┐   ┌──────────────┐
+         │ Models │  │Serializers│ │ DB │   │ REST Server  │
+         └───┬────┘  └────┬─────┘ └──┬─┘   │  Integration │
+             │             │          │      └──────┬───────┘
+             v             v          v             v
+         ┌────────┐  ┌──────────┐ ┌─────┐   ┌───────────┐
+         │ Record │──│ Store    │ │JSON │   │OrmRequest  │
+         │(instance)│ │(Map<Map>)│ │/MySQL│  │(CRUD+Hooks)│
+         └────────┘  └──────────┘ └─────┘   └───────────┘
+```
+
+**Key Design Patterns:**
+- **Singleton**: Orm, Store, DB, MysqlDB classes
+- **Proxy**: `attr()` wraps `ModelProperty` in a Proxy for type-safe get/set
+- **Registry**: Relationships tracked in nested Maps (`hasMany`, `belongsTo`, `global`, `pending`, `pendingBelongsTo`)
+- **Factory**: `createRecord()` instantiates records with serialization
+- **Middleware**: Hook system with sequential before/after execution and halting capability
+- **Convention over Configuration**: Auto-discovery of models, serializers, transforms, and access classes by filesystem directory
+
+## Directory Map
+
+```
+stonyx-orm/
+├── src/
+│   ├── index.js                     # Public exports barrel
+│   ├── main.js                      # Orm singleton class
+│   ├── model.js                     # Base Model class
+│   ├── record.js                    # Record instances (data + relationships)
+│   ├── serializer.js                # Base Serializer + computed properties
+│   ├── store.js                     # In-memory store (Map<model, Map<id, Record>>)
+│   ├── db.js                        # JSON file persistence layer
+│   ├── attr.js                      # Attribute helper (Proxy-based)
+│   ├── model-property.js            # Transform handler for attributes
+│   ├── transforms.js                # Built-in transforms (boolean, number, string, etc.)
+│   ├── has-many.js                  # One-to-many relationship handler
+│   ├── belongs-to.js                # Many-to-one relationship handler
+│   ├── relationships.js             # Relationship registry + helpers
+│   ├── manage-record.js             # createRecord / updateRecord
+│   ├── hooks.js                     # Middleware hook registry (before/after)
+│   ├── orm-request.js               # REST CRUD handler with hooks + includes
+│   ├── meta-request.js              # Dev-only meta endpoint
+│   ├── setup-rest-server.js         # REST route registration
+│   ├── migrate.js                   # JSON DB mode migration (file <-> directory)
+│   ├── commands.js                  # CLI commands (db:migrate-*, etc.)
+│   ├── utils.js                     # Pluralize wrapper for dasherized names
+│   ├── exports/
+│   │   └── db.js                    # Convenience re-export of DB instance
+│   └── mysql/
+│       ├── mysql-db.js              # MySQL driver class (CRUD persistence)
+│       ├── connection.js            # mysql2 connection pool management
+│       ├── query-builder.js         # SQL query builders (INSERT/UPDATE/DELETE/SELECT)
+│       ├── schema-introspector.js   # Introspects models into MySQL schemas
+│       ├── migration-generator.js   # Generates .sql migration files from schema diffs
+│       ├── migration-runner.js      # Applies/rollbacks migrations with transactions
+│       └── type-map.js              # ORM attr types -> MySQL column types
+├── config/
+│   └── environment.js               # Default ORM configuration
+├── test/
+│   ├── config/
+│   │   └── environment.js           # Test-specific config overrides
+│   ├── integration/
+│   │   ├── orm-test.js              # Full pipeline integration tests
+│   │   └── db-directory-test.js     # Directory-mode DB tests
+│   ├── unit/
+│   │   ├── commands-test.js         # CLI command structure tests
+│   │   ├── create-record-test.js    # Record creation tests
+│   │   ├── relationships-test.js    # Relationship wiring tests
+│   │   ├── environment-test.js      # Environment config tests
+│   │   ├── orm-lifecycle-test.js    # Startup/shutdown lifecycle tests
+│   │   ├── mysql/
+│   │   │   └── mysql-db-startup-test.js  # MySQL startup behavior tests
+│   │   ├── transforms/             # Per-transform unit tests
+│   │   └── utils/
+│   │       └── get-computed-properties-test.js
+│   └── sample/                      # Test fixtures
+│       ├── models/                  # Example model definitions
+│       ├── serializers/             # Example serializers
+│       ├── transforms/              # Custom transform functions
+│       ├── access/                  # Access control classes
+│       ├── db-schema.js             # Test DB schema
+│       ├── constants.js             # Test constants
+│       └── payload.js               # Sample raw + expected data
+├── .claude/                         # Claude AI assistant context docs
+├── .github/workflows/
+│   ├── ci.yml                       # PR CI pipeline
+│   └── publish.yml                  # NPM publish workflow
+├── package.json
+├── .nvmrc                           # Node v24.13.0
+├── .npmignore
+├── .gitignore
+└── LICENSE.md                       # Apache 2.0
+```
+
+## Key Files Reference
+
+| File / Path | Purpose | Category |
+|-------------|---------|----------|
+| `src/main.js` | Orm singleton: initialization, model/serializer/transform loading, DB + REST setup | Core |
+| `src/index.js` | Public API barrel export (Model, Serializer, attr, hooks, etc.) | Core |
+| `src/store.js` | In-memory record storage with relationship-aware unload/cascade | Core |
+| `src/record.js` | Record instances: serialize, format, toJSON (JSON:API), unload | Core |
+| `src/serializer.js` | Base serializer: path mapping, property setup, computed properties | Serialization |
+| `src/manage-record.js` | `createRecord` / `updateRecord` with pending relationship fulfillment | CRUD |
+| `src/orm-request.js` | REST request handler: CRUD routes, hooks wrapper, includes, filters, fields | REST API |
+| `src/hooks.js` | Middleware hook registry: before/after hooks with halting | Middleware |
+| `src/db.js` | JSON file persistence: read, save, directory mode, auto-save via cron | Persistence |
+| `src/mysql/mysql-db.js` | MySQL driver: load records on init, persist CRUD, migration prompts | Persistence |
+| `src/mysql/schema-introspector.js` | Model introspection to MySQL schema + DDL generation | MySQL |
+| `src/mysql/migration-generator.js` | Schema diff and `.sql` migration file generation | MySQL |
+| `src/commands.js` | CLI commands for DB migrations (file/directory mode + MySQL) | CLI |
+| `config/environment.js` | Default configuration with env var overrides | Config |
+
+## Data Flow
+
+**Typical REST request lifecycle:**
+
+1. **Request arrives** at auto-generated route (e.g., `POST /animals`) via `@stonyx/rest-server`
+2. **Access control** (`OrmRequest.auth`) calls the access class's `access()` method -- returns permissions, filter function, or denial
+3. **Before hooks** run sequentially -- can halt the operation by returning a value (status code or response object)
+4. **Handler executes** the CRUD operation (reads from / writes to the in-memory `Store`)
+5. **MySQL persistence** (if configured) -- `MysqlDB.persist()` writes to MySQL after in-memory mutation
+6. **After hooks** run sequentially with enriched context (record, response, oldState)
+7. **Auto-save** (if `autosave: 'onUpdate'`) writes the entire store to the JSON file
+8. **Response** returned as JSON:API format with optional `included` sideloaded relationships
+
+**Record creation flow:**
+
+1. `createRecord(modelName, rawData, options)` called
+2. Auto-increment ID assigned if missing (or pending MySQL ID in MySQL mode)
+3. Model + Serializer instantiated, Record wrapper created
+4. `record.serialize()` maps raw data through serializer paths, applies transforms, wires relationships
+5. Record stored in `Store` by ID
+6. Global, pending hasMany, and pending belongsTo relationships fulfilled
+
+## API / Routes
+
+Auto-generated REST endpoints for each model with an access class:
+
+| Method | Route Pattern | Operation | Notes |
+|--------|--------------|-----------|-------|
+| GET | `/:models` | List collection | Supports `?filter[path]=value`, `?fields[model]=attr1,attr2`, `?include=rel1,rel2.nested` |
+| GET | `/:models/:id` | Get single record | Same query params as list; returns 404 if not found |
+| POST | `/:models` | Create record | Body: `{ data: { type, id?, attributes } }`; 400 if no type; 409 if duplicate ID |
+| PATCH | `/:models/:id` | Update record | Body: `{ data: { attributes } }`; updates only provided fields |
+| DELETE | `/:models/:id` | Delete record | Removes from store; no response body |
+| GET | `/:models/:id/:relationship` | Related resource | Returns full related records (array for hasMany, single for belongsTo) |
+| GET | `/:models/:id/relationships/:relationship` | Relationship linkage | Returns JSON:API linkage objects with `links.self` and `links.related` |
+
+**Include parameter** supports comma-separated relationships and dot-notation nesting: `?include=owner.pets,traits`
+
+**Fields parameter** supports sparse fieldsets: `?fields[animals]=age,size`
+
+**Filter parameter** supports dot-path filtering: `?filter[owner]=angela`
+
+## Database & Models
+
+### Model Definition
+
+Models extend `Model` and define attributes with `attr(type)` and relationships with `hasMany(model)` / `belongsTo(model)`. Getters become computed properties.
+
+### In-Memory Store
+
+`Store.data` is a `Map<modelName, Map<recordId, Record>>`. O(1) lookup by model + ID.
+
+### JSON File Persistence
+
+Two modes configured via `db.mode`:
+- **`'file'`** (default): Single `db.json` file
+- **`'directory'`**: Per-collection files in a directory (e.g., `db/animals.json`)
+
+Auto-save modes: `'true'` (cron interval), `'false'` (disabled), `'onUpdate'` (after each write operation)
+
+### MySQL Persistence
+
+Enabled when `MYSQL_HOST` env var is set. Uses mysql2 connection pool. On init, loads all records from MySQL into the in-memory store. CRUD operations persist to MySQL after in-memory mutation. Supports:
+- Schema introspection from model definitions
+- Migration generation via schema diffs (`.snapshot.json`)
+- Migration apply/rollback with transactions
+- Schema drift detection on startup
+- Auto-increment ID re-keying after INSERT
+
+### Relationship System
+
+| Type | Handler | Storage | Resolution |
+|------|---------|---------|------------|
+| `hasMany` | `src/has-many.js` | Array of Records | Inline objects, ID references, or pending queue |
+| `belongsTo` | `src/belongs-to.js` | Single Record or null | Inline object, ID reference, or pending queue |
+
+Relationships are bidirectional: creating a `belongsTo` automatically populates the inverse `hasMany`, and vice versa. Pending relationships resolve when the target record is created later.
+
+## Authentication & Authorization
+
+Access control is defined via access classes in the configured `paths.access` directory:
+
+```javascript
+export default class GlobalAccess {
+  models = ['owner', 'animal']; // or '*' for all
+  access(request) {
+    // Return false → 403 Forbidden
+    // Return ['read', 'create', 'update', 'delete'] → allowed methods
+    // Return (record) => boolean → filter function for collections
+  }
+}
+```
+
+Method mapping: `GET → 'read'`, `POST → 'create'`, `DELETE → 'delete'`, `PATCH → 'update'`
+
+## Configuration & Environment
+
+Located in `config/environment.js`. All values overridable via environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DB_AUTO_SAVE` | `'false'` | Auto-save mode: `'true'`, `'false'`, or `'onUpdate'` |
+| `DB_FILE` | `'db.json'` | JSON file path |
+| `DB_MODE` | `'file'` | `'file'` or `'directory'` |
+| `DB_DIRECTORY` | `'db'` | Directory name for collection files |
+| `DB_SAVE_INTERVAL` | `3600` | Auto-save interval in seconds |
+| `DB_SCHEMA_PATH` | `'./config/db-schema.js'` | Path to DB schema |
+| `ORM_MODEL_PATH` | `'./models'` | Models directory |
+| `ORM_SERIALIZER_PATH` | `'./serializers'` | Serializers directory |
+| `ORM_TRANSFORM_PATH` | `'./transforms'` | Transforms directory |
+| `ORM_ACCESS_PATH` | `'./access'` | Access classes directory |
+| `ORM_USE_REST_SERVER` | `'true'` | Enable auto REST route generation |
+| `ORM_REST_ROUTE` | `'/'` | Base route for REST endpoints |
+| `MYSQL_HOST` | undefined | Enables MySQL mode when set |
+| `MYSQL_PORT` | `3306` | MySQL port |
+| `MYSQL_USER` | `'root'` | MySQL user |
+| `MYSQL_PASSWORD` | `''` | MySQL password |
+| `MYSQL_DATABASE` | `'stonyx'` | MySQL database name |
+| `MYSQL_CONNECTION_LIMIT` | `10` | Connection pool size |
+| `MYSQL_MIGRATIONS_DIR` | `'migrations'` | Migration files directory |
+
+## Development Guide
+
+| Task | Command |
+|------|---------|
+| Install deps | `pnpm install` |
+| Run tests | `stonyx test` (or `npm test`) |
+| Node version | v24.13.0 (see `.nvmrc`) |
+| Generate MySQL migration | `stonyx db:generate-migration <description>` |
+| Apply MySQL migrations | `stonyx db:migrate` |
+| Rollback MySQL migration | `stonyx db:migrate:rollback` |
+| Migration status | `stonyx db:migrate:status` |
+| Migrate DB file→directory | `stonyx db:migrate-to-directory` |
+| Migrate DB directory→file | `stonyx db:migrate-to-file` |
+
+**Local development** uses `file:../package-name` references in `package.json` for sibling Stonyx packages.
+
+## Testing
+
+| Aspect | Detail |
+|--------|--------|
+| Framework | QUnit via `stonyx test` |
+| Mocking | Sinon |
+| Unit tests | `test/unit/` — transforms, commands, relationships, environment, lifecycle, MySQL startup |
+| Integration tests | `test/integration/` — full ORM pipeline, directory-mode DB |
+| Test fixtures | `test/sample/` — models, serializers, transforms, access, payload, constants |
+| Test config | `test/config/environment.js` |
+
+## Deployment & CI/CD
+
+| Pipeline | Trigger | Workflow |
+|----------|---------|----------|
+| CI | Pull requests to `dev` or `main` | Shared via `abofs/stonyx-workflows/.github/workflows/ci.yml@main` |
+| Publish | Push to `main`, manual dispatch | Shared via `abofs/stonyx-workflows/.github/workflows/npm-publish.yml@main` |
+
+Published to npm as `@stonyx/orm` with public access and provenance.
+
+## Conventions & Standards
+
+- **Files**: kebab-case (e.g., `phone-number.js`)
+- **Models**: PascalCase + `Model` suffix (e.g., `PhoneNumberModel`)
+- **Serializers**: PascalCase + `Serializer` suffix (e.g., `AnimalSerializer`)
+- **Transforms**: Original filename as key (e.g., `animal.js` → `'animal'` transform)
+- **Model names in code**: kebab-case (e.g., `'phone-number'`)
+- **REST routes**: Pluralized, dasherized (e.g., `/phone-numbers`)
+- **Relationship URLs**: Dasherized (e.g., `phoneNumbers` → `/phone-numbers`)
+- **ES Modules**: All files use `import`/`export`
+- **License headers**: Apache 2.0 in core source files
+- **Git workflow**: Feature branches → `dev` → `main`
+
+## Known Issues & Technical Debt
+
+See [improvements.md](improvements.md) for detailed findings. Key items:
+
+- `config/environment.js` contains a stray `console.log(MYSQL_HOST)` statement
+- `getOrSet` utility is duplicated across `has-many.js` and `belongs-to.js`
+- `getRelationshipInfo()` is duplicated across `orm-request.js`, `schema-introspector.js`, and `meta-request.js`
+- `getCollectionKeys()` and `getDirPath()` are duplicated between `db.js` and `migrate.js`
+- Package exports in `package.json` are missing `./commands` and `./hooks` entries (present in code but not in the outline docs)
+- The outline doc (`/.claude/personal/outline.md`) references files that don't exist (`src/include-parser.js`, `src/include-collector.js`, `stonyx-bootstrap.cjs`) and lists version as `0.1.0` (actual: `0.2.1-beta.1`)