@loom-framework/core 0.1.0-alpha.10 → 0.1.0-alpha.100

package/builtin-skills/loom/references/dashboard.md

@@ -0,0 +1,215 @@
+# 生成 Dashboard（数据概览页面）
+
+Dashboard 在 `loom.config.ts` 的 `dashboards` 字段中定义，然后通过 CLI 生成页面。
+
+## 配置 Dashboard
+
+在 `loom.config.ts` 中添加 `dashboards` 字段：
+
+```typescript
+import { defineConfig } from '@loom-framework/core';
+
+export default defineConfig({
+  project: { name: 'my-app' },
+  data: { /* ... */ },
+  dashboards: [{
+    name: 'overview',
+    description: '数据概览',
+    models: ['items'],
+    layout: [
+      { row: [{ type: 'stat', title: '总数', model: 'items', aggregate: 'count', span: 6 }] },
+    ],
+  }],
+});
+```
+
+**设计原则：**
+- 统计卡片放第一行（一眼看到关键数字）
+- 分布图表按业务重要性排列
+- 趋势图放最后一行（需要更多空间）
+- 每行不超过 4 个元素
+- 标题用业务语言，不用字段名
+
+### 配置 Schema
+
+```typescript
+{
+  name: 'overview',           // 必填：Dashboard 标识（同模型命名规则）
+  description: '数据概览',     // 可选：侧边栏展示名
+  models: ['model_a'],        // 必填：关联的数据模型名列表
+  layout: [{                  // 必填：布局定义，数组每项代表一行
+    row: [{                   // 每行包含一组 widget
+      type: 'stat',           // 图表类型，见下方图表类型表
+      title: '总数',          // 业务语言标题
+      model: 'model_a',      // 数据模型名
+      span: 6,               // 可选：Col 宽度（1-24），省略则自动均分
+      aggregate: 'count',    // 可选：count|sum|avg|min|max|ratio（默认 count）
+      field: 'score',        // aggregate 为 sum/avg/min/max 时必填：数值字段名
+      filter: { status: 'active' },  // 可选：聚合前筛选条件
+      groupBy: 'category',   // 可选：分组字段（string/enum/date/boolean）
+      crossGroupBy: 'grade', // 可选：第二分组字段，用于二维图表
+      interval: 'month'      // 可选：date 字段分组粒度 day|week|month（默认 month）
+    }]
+  }]
+}
+```
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `aggregate` | `count\|sum\|avg\|min\|max\|ratio` | 聚合方式。`ratio` = 符合 filter 条件的记录数/总记录数，用于 gauge/liquid/stat 百分比 |
+| `field` | string | 聚合目标字段。仅 aggregate 为 sum/avg/min/max 时需要 |
+| `filter` | object | 筛选条件，键值对。如 `{isMastered: true}` 筛选已掌握的记录 |
+| `groupBy` | string | 主分组字段。string/enum 字段按值分组计数；boolean 字段自动映射为"是/否"；date 字段按 interval 分段 |
+| `crossGroupBy` | string | 第二分组维度。配合 groupBy 使用，产生交叉分组数据，用于二维图表 |
+| `interval` | `day\|week\|month` | date 字段的分组粒度，仅 groupBy 指向 date 字段时有效 |
+
+### 图表类型与配置要点
+
+#### 数值类 — 展示关键指标
+
+| type | 中文名称 | 必填字段 | 典型配置 | 生成效果 |
+|------|---------|---------|---------|---------|
+| `stat` | 统计卡片 | — | `{ aggregate: "count" }` 或 `{ aggregate: "avg", field: "score" }` 或 `{ aggregate: "ratio", filter: { passed: true } }` | Ant Design Statistic 数值卡片 |
+| `gauge` | 仪表盘 | `aggregate: "ratio"` + `filter` | `{ aggregate: "ratio", filter: { isMastered: true } }` | G2 仪表盘（百分比进度） |
+| `liquid` | 水波图 | `aggregate: "ratio"` + `filter` | `{ aggregate: "ratio", filter: { isMastered: true } }` | G2 水波图（百分比进度） |
+
+> **说明**：gauge 和 liquid 使用 `aggregate: "ratio"` + `filter` 来计算百分比（如掌握率 = 已掌握数/总数），ratio 自动算出 0-1 之间的值。
+
+#### 占比类 — 展示分布构成
+
+| type | 中文名称 | 必填字段 | 典型配置 | 生成效果 |
+|------|---------|---------|---------|---------|
+| `pie` | 饼图 | `groupBy` (enum/string) | `{ groupBy: "subject" }` | G2 饼图（分布占比） |
+| `ring` | 环形图 | `groupBy` (boolean/enum) | `{ groupBy: "difficulty" }` 或 `{ groupBy: "isMastered" }` | G2 环形图（占比对比，boolean 自动映射"是/否"） |
+| `treemap` | 矩形树图 | `groupBy` + 可选 `crossGroupBy` | `{ groupBy: "subject" }` 或 `{ groupBy: "subject", crossGroupBy: "difficulty" }` | G2 矩形树图（层级占比，有 crossGroupBy 则两层） |
+
+#### 对比类 — 跨类别比较
+
+| type | 中文名称 | 必填字段 | 典型配置 | 生成效果 |
+|------|---------|---------|---------|---------|
+| `bar` | 条形图 | `groupBy` | `{ groupBy: "errorType" }` | G2 条形图（横向分类对比） |
+| `stacked_bar` | 堆叠条形图 | `groupBy` + `crossGroupBy` | `{ groupBy: "subject", crossGroupBy: "errorType" }` | G2 堆叠条形图（组成+对比） |
+| `grouped_bar` | 分组条形图 | `groupBy` + `crossGroupBy` | `{ groupBy: "subject", crossGroupBy: "difficulty" }` | G2 分组条形图（并列对比） |
+| `radar` | 雷达图 | `groupBy` | `{ groupBy: "subject" }` | G2 雷达图（多维度闭合多边形） |
+| `funnel` | 漏斗图 | `groupBy` | `{ groupBy: "errorType" }` | G2 漏斗图（阶段转化，柱条宽度反映数值） |
+
+#### 趋势类 — 时间维度变化
+
+| type | 中文名称 | 必填字段 | 典型配置 | 生成效果 |
+|------|---------|---------|---------|---------|
+| `line` | 折线图 | `groupBy` (date 字段) + `interval` | `{ groupBy: "createdAt", interval: "month" }` | G2 折线图（时间趋势） |
+| `area` | 面积图 | `groupBy` (date 字段) + `interval` | `{ groupBy: "createdAt", interval: "month" }` | G2 面积图（累计趋势） |
+
+#### 分布类 — 交叉/密度分析
+
+| type | 中文名称 | 必填字段 | 典型配置 | 生成效果 |
+|------|---------|---------|---------|---------|
+| `scatter` | 散点图 | `groupBy` | `{ groupBy: "subject" }` | G2 散点图（相关性/分布） |
+| `heatmap` | 热力图 | `groupBy` + `crossGroupBy` | `{ groupBy: "subject", crossGroupBy: "grade" }` | G2 热力图（密度/交叉分析，颜色深浅表示数量） |
+
+## 执行 generate dashboard
+
+配置好 `dashboards` 字段后，运行命令生成页面：
+
+```bash
+loom generate dashboard <name>
+```
+
+此命令会：
+1. 从 `loom.config.ts` 的 `dashboards` 字段读取配置
+2. 验证引用的模型是否存在
+3. 生成 Dashboard TSX 页面（含 `useData` + `useChartData` + `DashboardChart`）
+4. 自动接线 App.tsx（添加 import、navItem、switch case）
+5. 检测 `@antv/g2` 是否已安装，未安装则自动安装
+
+**前置依赖：** Dashboard 使用 @antv/g2 渲染图表，需在 frontend 目录安装：
+
+```bash
+cd frontend && pnpm add @antv/g2
+```
+
+## 完整配置示例
+
+以小学生错题管理平台为例，展示所有 15 种图表的配置：
+
+```typescript
+import { defineConfig } from '@loom-framework/core';
+
+export default defineConfig({
+  project: { name: 'wrong-questions' },
+  data: { /* ... */ },
+  dashboards: [{
+    name: 'overview',
+    description: '错题数据概览',
+    models: ['wrong_questions', 'review_plans'],
+    layout: [
+      {
+        row: [
+          { type: 'stat', title: '错题总数', model: 'wrong_questions', aggregate: 'count', span: 4 },
+          { type: 'stat', title: '掌握率', model: 'wrong_questions', aggregate: 'ratio', filter: { isMastered: true }, span: 4 },
+          { type: 'gauge', title: '掌握率仪表盘', model: 'wrong_questions', aggregate: 'ratio', filter: { isMastered: true }, span: 6 },
+          { type: 'liquid', title: '掌握率水波图', model: 'wrong_questions', aggregate: 'ratio', filter: { isMastered: true }, span: 5 },
+          { type: 'stat', title: '平均复习次数', model: 'wrong_questions', aggregate: 'avg', field: 'reviewCount', span: 5 }
+        ]
+      },
+      {
+        row: [
+          { type: 'pie', title: '科目分布', model: 'wrong_questions', groupBy: 'subject', span: 8 },
+          { type: 'ring', title: '难度分布', model: 'wrong_questions', groupBy: 'difficulty', span: 8 },
+          { type: 'bar', title: '错误类型分布', model: 'wrong_questions', groupBy: 'errorType', span: 8 }
+        ]
+      },
+      {
+        row: [
+          { type: 'line', title: '错题录入趋势', model: 'wrong_questions', groupBy: 'createdAt', interval: 'month', span: 12 },
+          { type: 'area', title: '复习计划趋势', model: 'review_plans', groupBy: 'createdAt', interval: 'month', span: 12 }
+        ]
+      },
+      {
+        row: [
+          { type: 'radar', title: '各科目概览', model: 'wrong_questions', groupBy: 'subject', span: 8 },
+          { type: 'stacked_bar', title: '科目×错误类型', model: 'wrong_questions', groupBy: 'subject', crossGroupBy: 'errorType', span: 8 },
+          { type: 'grouped_bar', title: '科目×难度', model: 'wrong_questions', groupBy: 'subject', crossGroupBy: 'difficulty', span: 8 }
+        ]
+      },
+      {
+        row: [
+          { type: 'scatter', title: '科目分布散点', model: 'wrong_questions', groupBy: 'subject', span: 8 },
+          { type: 'funnel', title: '错误类型漏斗', model: 'wrong_questions', groupBy: 'errorType', span: 8 },
+          { type: 'treemap', title: '科目×难度树图', model: 'wrong_questions', groupBy: 'subject', crossGroupBy: 'difficulty', span: 8 }
+        ]
+      },
+      {
+        row: [
+          { type: 'heatmap', title: '科目×年级热力图', model: 'wrong_questions', groupBy: 'subject', crossGroupBy: 'grade', span: 24 }
+        ]
+      }
+    ]
+  }],
+});
+```
+
+## 追加自定义图表
+
+生成后的 Dashboard 页面是普通 TSX，可直接编辑追加图表：
+
+1. 使用 `useChartData` / `useCrossGroupChartData` / `useTreemapChartData` 准备数据
+2. 使用 `/antv-g2-chart` skill 生成 G2 v5 Spec 代码
+3. 添加 `<DashboardChart spec={...} />` 组件
+
+示例——追加一个科目×年级的堆叠柱状图：
+
+```tsx
+// 在已有的 Dashboard 页面中追加
+const subjectGradeData = useCrossGroupChartData(wrongQuestionsList, { groupBy: 'subject', crossGroupBy: 'grade' });
+
+<DashboardChart spec={{
+  type: 'interval',
+  data: subjectGradeData,
+  encode: { x: 'group', y: 'value', color: 'name' },
+  coordinate: { transform: [{ type: 'transpose' }] },
+  transform: [{ type: 'stackY' }],
+}} />
+```

package/builtin-skills/loom/references/data-model.md

@@ -0,0 +1,116 @@
+# Data Model Reference
+
+Advanced configuration for `loom.config.ts`. Full type definitions from `packages/core/src/types.ts`.
+
+## FieldDefinition
+
+```typescript
+{
+  name: 'status',         // ^[a-zA-Z_][a-zA-Z0-9_]*$
+  type: 'string',         // 'string' | 'number' | 'boolean' | 'date' | 'string[]' | 'number[]' | 'json'
+  required: true,         // optional, default false
+  description: '...',     // optional: shown in generated forms
+  default: 'active',      // optional: auto-filled on write if not provided
+  enum: ['active', 'inactive', 'archived'],  // optional: restrict string field to allowed values
+}
+```
+
+## ModelSchema
+
+```typescript
+{
+  name: 'orders',              // ^[a-zA-Z][a-zA-Z0-9_]*$, will be used as React component name
+  description: 'Order records', // optional: shown in generated page heading
+  fields: [...],
+  indexes?: [{ fields: ['userId', 'status'], unique: false }],
+  adapters?: {                  // optional: per-model adapter override
+    filesystem: { dir: 'orders', format: 'json' | 'yaml', datePattern: 'YYYY-MM' },
+    sqlite: { table: 'orders' },
+  },
+}
+```
+
+## AIButtonConfig
+
+```typescript
+aiButtons: [{
+  id: 'summarize',          // required: unique identifier
+  label: '总结',             // required: button text
+  icon: 'FileTextOutlined', // optional: Ant Design icon component name
+  prompt: '请总结以下内容',   // required: supports {{var}} placeholders, replaced with current row field values
+  placement: 'wrong_questions',  // optional: limit to specific model pages, comma-separated; omit for all pages
+}]
+```
+
+## AIConfig
+
+```typescript
+ai: {
+  engine: 'claude-code',       // default 'claude-code'
+  claudeCode: {
+    path: '/usr/local/bin/claude',  // optional: custom claude binary path
+    pluginRoot: '.claude',          // optional: plugin root directory
+    timeout: 120000,                // optional: command timeout in ms
+    skipPermissions: false,         // optional: skip permission prompts
+  },
+}
+```
+
+## ServerConfig
+
+```typescript
+server: {
+  port: 3000,              // default 3000
+  host: '0.0.0.0',
+  cors: true,              // default true
+  staticDir: './dist/frontend',
+}
+```
+
+## DataConfig
+
+```typescript
+data: {
+  defaultAdapter: 'filesystem' | 'sqlite',
+  models: [...],
+  sqlite: { filename: 'loom.db' },  // optional, default 'loom.db'
+}
+```
+
+## DashboardConfig
+
+```typescript
+dashboards: [{
+  name: 'overview',           // ^[a-zA-Z][a-zA-Z0-9_]*$, same naming rules as model
+  description: '数据概览',     // optional: shown in sidebar navigation
+  models: ['items'],          // required: data models included in this dashboard
+  layout: [{                  // required: at least one row
+    row: [{                   // at least one widget per row
+      type: 'stat' | 'pie' | 'ring' | 'bar' | 'line' | 'area' | 'scatter' | 'radar' | 'funnel' | 'treemap' | 'gauge' | 'liquid' | 'heatmap' | 'stacked_bar' | 'grouped_bar',
+      title: '任务总数',       // required: display title
+      model: 'items',         // required: data model name
+      span: 6,                // optional: Ant Design Grid Col span (1-24), auto-equal-split if omitted
+      groupBy: 'status',      // optional: group by field for aggregation
+      crossGroupBy: 'priority', // optional: second group-by for 2D charts (heatmap, stacked_bar, grouped_bar)
+      aggregate: 'count',     // optional: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'ratio', default count
+      field: 'score',         // optional: numeric field for sum/avg/min/max
+      filter: { status: 'active' }, // optional: pre-aggregation filter
+      interval: 'month',      // optional: 'day' | 'week' | 'month' for date groupBy
+    }],
+  }],
+}]
+```
+
+## useSchema Runtime API
+
+Generated pages use `useSchema(model)` to fetch model schema and AI buttons at runtime:
+
+```typescript
+const { schema, loading, error } = useSchema('items');
+// schema.fields — field definitions with enum values
+// schema.aiButtons — AI buttons filtered by placement
+
+// Convert schema enum to antd formats:
+filterOptions(schema, 'status')  // → [{ text: 'active', value: 'active' }, ...]
+selectOptions(schema, 'status')  // → [{ label: 'active', value: 'active' }, ...]
+```

package/dist/adapter-base.d.ts

@@ -0,0 +1,29 @@
+/**
+ * BaseAdapter - Shared logic for DataAdapter implementations
+ *
+ * Extracts common validation, ID generation, and schema management
+ * used by both FileSystemAdapter and SQLiteAdapter.
+ */
+import type { DataAdapter, DataRecord, ModelSchema, LoomConfig } from './types.js';
+export declare abstract class BaseAdapter implements DataAdapter {
+    abstract readonly name: string;
+    protected schemas: Map<string, ModelSchema>;
+    protected config: LoomConfig;
+    constructor(config: LoomConfig);
+    abstract initialize(): Promise<void>;
+    abstract healthCheck(): Promise<boolean>;
+    abstract read(model: string, options?: import('./types.js').ReadOptions): Promise<DataRecord | DataRecord[] | null>;
+    abstract write(model: string, data: DataRecord): Promise<DataRecord>;
+    abstract update(model: string, id: string, data: DataRecord): Promise<DataRecord>;
+    abstract delete(model: string, id: string): Promise<void>;
+    getSchema(model: string): Promise<ModelSchema | undefined>;
+    listModels(): Promise<string[]>;
+    protected requireModel(model: string): void;
+    protected generateId(): string;
+    /**
+     * Validate required fields and apply defaults on a record.
+     * Returns the validated record with defaults applied.
+     */
+    protected validateAndApplyDefaults(model: string, record: DataRecord, skipIdValidation?: boolean): DataRecord;
+}
+//# sourceMappingURL=adapter-base.d.ts.map

package/dist/adapter-base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-base.d.ts","sourceRoot":"","sources":["../src/adapter-base.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEnF,8BAAsB,WAAY,YAAW,WAAW;IACtD,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAa;IACxD,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC;gBAEjB,MAAM,EAAE,UAAU;IAO9B,QAAQ,CAAC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IACpC,QAAQ,CAAC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IACxC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,YAAY,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,GAAG,UAAU,EAAE,GAAG,IAAI,CAAC;IACnH,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IACpE,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IACjF,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnD,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAI1D,UAAU,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAMrC,SAAS,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAQ3C,SAAS,CAAC,UAAU,IAAI,MAAM;IAM9B;;;OAGG;IACH,SAAS,CAAC,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,UAAQ,GAAG,UAAU;CA2B5G"}

package/dist/adapter-base.js

@@ -0,0 +1,62 @@
+/**
+ * BaseAdapter - Shared logic for DataAdapter implementations
+ *
+ * Extracts common validation, ID generation, and schema management
+ * used by both FileSystemAdapter and SQLiteAdapter.
+ */
+export class BaseAdapter {
+    schemas = new Map();
+    config;
+    constructor(config) {
+        this.config = config;
+        for (const model of config.data.models) {
+            this.schemas.set(model.name, model);
+        }
+    }
+    async getSchema(model) {
+        return this.schemas.get(model);
+    }
+    async listModels() {
+        return Array.from(this.schemas.keys());
+    }
+    // ── Shared Helpers ──
+    requireModel(model) {
+        if (!this.schemas.has(model)) {
+            throw new Error(`Unknown model: ${model}. Available: ${Array.from(this.schemas.keys()).join(', ')}`);
+        }
+    }
+    generateId() {
+        const timestamp = Date.now().toString(36);
+        const random = Math.random().toString(36).substring(2, 10);
+        return `rec_${timestamp}_${random}`;
+    }
+    /**
+     * Validate required fields and apply defaults on a record.
+     * Returns the validated record with defaults applied.
+     */
+    validateAndApplyDefaults(model, record, skipIdValidation = false) {
+        const schema = this.schemas.get(model);
+        // Apply default values for missing fields
+        for (const field of schema.fields) {
+            if (record[field.name] === undefined && field.default !== undefined) {
+                record[field.name] = field.default;
+            }
+        }
+        // Validate required fields
+        for (const field of schema.fields) {
+            if (skipIdValidation && field.name === 'id')
+                continue;
+            if (field.required && record[field.name] === undefined) {
+                throw new Error(`Missing required field: ${field.name}`);
+            }
+        }
+        // Validate enum constraints
+        for (const field of schema.fields) {
+            if (field.enum && record[field.name] !== undefined && !field.enum.includes(record[field.name])) {
+                throw new Error(`Invalid value for field '${field.name}': ${record[field.name]}. Allowed values: ${field.enum.join(', ')}`);
+            }
+        }
+        return record;
+    }
+}
+//# sourceMappingURL=adapter-base.js.map

package/dist/adapter-base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-base.js","sourceRoot":"","sources":["../src/adapter-base.ts"],"names":[],"mappings":"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"}

package/dist/adapter-factory.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Adapter Factory
+ *
+ * Creates the appropriate DataAdapter based on LoomConfig.data.defaultAdapter.
+ */
+import type { LoomConfig, DataAdapter } from './types.js';
+export declare function createAdapter(config: LoomConfig, projectRoot: string): DataAdapter;
+//# sourceMappingURL=adapter-factory.d.ts.map

package/dist/adapter-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-factory.d.ts","sourceRoot":"","sources":["../src/adapter-factory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE1D,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,WAAW,CAgBlF"}

package/dist/adapter-factory.js

@@ -0,0 +1,25 @@
+/**
+ * Adapter Factory
+ *
+ * Creates the appropriate DataAdapter based on LoomConfig.data.defaultAdapter.
+ */
+import path from 'path';
+import { FileSystemAdapter } from './adapter-filesystem.js';
+import { SQLiteAdapter } from './adapter-sqlite.js';
+export function createAdapter(config, projectRoot) {
+    const adapterType = config.data.defaultAdapter || 'filesystem';
+    switch (adapterType) {
+        case 'sqlite':
+            return new SQLiteAdapter({
+                dbPath: path.join(projectRoot, 'data', config.data.sqlite?.filename ?? 'loom.db'),
+                config,
+            });
+        case 'filesystem':
+        default:
+            return new FileSystemAdapter({
+                dataDir: path.join(projectRoot, 'data'),
+                config,
+            });
+    }
+}
+//# sourceMappingURL=adapter-factory.js.map

package/dist/adapter-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-factory.js","sourceRoot":"","sources":["../src/adapter-factory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,MAAM,UAAU,aAAa,CAAC,MAAkB,EAAE,WAAmB;IACnE,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,cAAc,IAAI,YAAY,CAAC;IAE/D,QAAQ,WAAW,EAAE,CAAC;QACpB,KAAK,QAAQ;YACX,OAAO,IAAI,aAAa,CAAC;gBACvB,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,IAAI,SAAS,CAAC;gBACjF,MAAM;aACP,CAAC,CAAC;QACL,KAAK,YAAY,CAAC;QAClB;YACE,OAAO,IAAI,iBAAiB,CAAC;gBAC3B,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC;gBACvC,MAAM;aACP,CAAC,CAAC;IACP,CAAC;AACH,CAAC"}

package/dist/adapter-filesystem.d.ts

@@ -4,29 +4,24 @@
  * Stores data as JSON files, organized by model.
  * Default adapter for development and small deployments.
  */
-import type { DataAdapter, ModelSchema, ReadOptions, LoomConfig } from './types.js';
+import type { DataRecord, ReadOptions, LoomConfig } from './types.js';
+import { BaseAdapter } from './adapter-base.js';
 export interface FileSystemAdapterOptions {
     dataDir: string;
     config: LoomConfig;
 }
-export declare class FileSystemAdapter implements DataAdapter {
+export declare class FileSystemAdapter extends BaseAdapter {
     readonly name = "filesystem";
     private dataDir;
-    private config;
-    private schemas;
     constructor(options: FileSystemAdapterOptions);
     initialize(): Promise<void>;
     healthCheck(): Promise<boolean>;
-    read(model: string, options?: ReadOptions): Promise<unknown>;
-    write(model: string, data: Record<string, unknown>): Promise<unknown>;
-    update(model: string, id: string, data: Record<string, unknown>): Promise<unknown>;
+    read(model: string, options?: ReadOptions): Promise<DataRecord | DataRecord[] | null>;
+    write(model: string, data: DataRecord): Promise<DataRecord>;
+    update(model: string, id: string, data: DataRecord): Promise<DataRecord>;
     delete(model: string, id: string): Promise<void>;
-    getSchema(model: string): Promise<ModelSchema | undefined>;
-    listModels(): Promise<string[]>;
-    private requireModel;
     private getModelDir;
     private getRecordPath;
     private matchesFilter;
-    private generateId;
 }
 //# sourceMappingURL=adapter-filesystem.d.ts.map

package/dist/adapter-filesystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter-filesystem.d.ts","sourceRoot":"","sources":["../src/adapter-filesystem.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEpF,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,qBAAa,iBAAkB,YAAW,WAAW;IACnD,QAAQ,CAAC,IAAI,gBAAgB;IAC7B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,OAAO,CAAuC;gBAE1C,OAAO,EAAE,wBAAwB;IAUvC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAS/B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAmC5D,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAwBrE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAmBlF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWhD,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAI1D,UAAU,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAMrC,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,UAAU;CAMnB"}
+{"version":3,"file":"adapter-filesystem.d.ts","sourceRoot":"","sources":["../src/adapter-filesystem.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,qBAAa,iBAAkB,SAAQ,WAAW;IAChD,QAAQ,CAAC,IAAI,gBAAgB;IAC7B,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,EAAE,wBAAwB;IAKvC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAS/B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,GAAG,UAAU,EAAE,GAAG,IAAI,CAAC;IA6DrF,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAc3D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAmBxE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAatD,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,aAAa;CAoBtB"}

package/dist/adapter-filesystem.js

@@ -6,18 +6,13 @@
  */
 import { promises as fs } from 'fs';
 import path from 'path';
-export class FileSystemAdapter {
+import { BaseAdapter } from './adapter-base.js';
+export class FileSystemAdapter extends BaseAdapter {
     name = 'filesystem';
     dataDir;
-    config;
-    schemas = new Map();
     constructor(options) {
+        super(options.config);
         this.dataDir = options.dataDir;
-        this.config = options.config;
-        // Index model schemas
-        for (const model of options.config.data.models) {
-            this.schemas.set(model.name, model);
-        }
     }
     async initialize() {
         await fs.mkdir(this.dataDir, { recursive: true });
@@ -57,28 +52,49 @@ export class FileSystemAdapter {
             if (!file.endsWith('.json'))
                 continue;
             const content = await fs.readFile(path.join(modelDir, file), 'utf-8');
-            const record = JSON.parse(content);
-            // Apply filter if provided
-            if (options?.filter && !this.matchesFilter(record, options.filter)) {
-                continue;
+            const parsed = JSON.parse(content);
+            // Handle both single records and arrays (e.g. init.json seed data)
+            const items = Array.isArray(parsed) ? parsed : [parsed];
+            for (const record of items) {
+                // Apply filter if provided
+                if (options?.filter && !this.matchesFilter(record, options.filter)) {
+                    continue;
+                }
+                records.push(record);
             }
-            records.push(record);
         }
-        return records;
+        // Apply sort if provided
+        if (options?.sort) {
+            const { field, order } = options.sort;
+            records.sort((a, b) => {
+                const va = a[field];
+                const vb = b[field];
+                if (va == null && vb == null)
+                    return 0;
+                if (va == null)
+                    return 1;
+                if (vb == null)
+                    return -1;
+                let cmp;
+                if (typeof va === 'number' && typeof vb === 'number') {
+                    cmp = va - vb;
+                }
+                else {
+                    cmp = String(va).localeCompare(String(vb));
+                }
+                return order === 'desc' ? -cmp : cmp;
+            });
+        }
+        // Apply offset and limit
+        const start = options?.offset || 0;
+        const end = options?.limit ? start + options.limit : undefined;
+        return records.slice(start, end);
     }
     async write(model, data) {
         this.requireModel(model);
-        const schema = this.schemas.get(model);
         const id = data.id || this.generateId();
-        // Build the full record first (with auto-generated id)
         const record = { id, ...data };
-        // Validate required fields (check against the full record, not the raw input,
-        // so auto-generated fields like id are not falsely flagged as missing)
-        for (const field of schema.fields) {
-            if (field.required && record[field.name] === undefined) {
-                throw new Error(`Missing required field: ${field.name}`);
-            }
-        }
+        this.validateAndApplyDefaults(model, record);
         const filePath = this.getRecordPath(model, id);
         await fs.mkdir(path.dirname(filePath), { recursive: true });
         await fs.writeFile(filePath, JSON.stringify(record, null, 2), 'utf-8');
@@ -109,18 +125,7 @@ export class FileSystemAdapter {
             throw new Error(`Record not found: ${model}/${id}`);
         }
     }
-    async getSchema(model) {
-        return this.schemas.get(model);
-    }
-    async listModels() {
-        return Array.from(this.schemas.keys());
-    }
     // ── Private Helpers ──
-    requireModel(model) {
-        if (!this.schemas.has(model)) {
-            throw new Error(`Unknown model: ${model}. Available: ${Array.from(this.schemas.keys()).join(', ')}`);
-        }
-    }
     getModelDir(model) {
         const schema = this.schemas.get(model);
         const adapterConfig = schema.adapters?.filesystem;
@@ -131,13 +136,23 @@ export class FileSystemAdapter {
         return path.join(this.getModelDir(model), `${id}.json`);
     }
     matchesFilter(record, filter) {
-        return Object.entries(filter).every(([key, value]) => record[key] === value);
-    }
-    generateId() {
-        // Simple ID generation without dynamic import
-        const timestamp = Date.now().toString(36);
-        const random = Math.random().toString(36).substring(2, 10);
-        return `rec_${timestamp}_${random}`;
+        return Object.entries(filter).every(([key, value]) => {
+            const recordVal = record[key];
+            // Range filter: { __range: [start, end] }
+            if (value && typeof value === 'object' && !Array.isArray(value) && '__range' in value) {
+                const range = value.__range;
+                if (!range?.[0] || !range?.[1])
+                    return true;
+                if (recordVal == null)
+                    return false;
+                return recordVal >= range[0] && recordVal <= range[1];
+            }
+            // Array filter: match any value in the array
+            if (Array.isArray(value)) {
+                return value.includes(recordVal);
+            }
+            return recordVal === value;
+        });
     }
 }
 //# sourceMappingURL=adapter-filesystem.js.map