@loom-framework/core 0.1.0-alpha.14 → 0.1.0-alpha.141

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

@@ -0,0 +1,257 @@
+# 生成 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: { 'zh-CN': '数据概览', 'en-US': 'Overview' },
+    models: ['items'],
+    layout: [
+      { row: [{ type: 'stat', title: { 'zh-CN': '总数', 'en-US': 'Total' }, model: 'items', aggregate: 'count', span: 6 }] },
+    ],
+  }],
+});
+```
+
+**设计原则：**
+- 统计卡片放第一行（一眼看到关键数字）
+- 分布图表按业务重要性排列
+- 趋势图放最后一行（需要更多空间）
+- 每行不超过 4 个元素
+- 标题用业务语言，不用字段名
+
+### 配置 Schema
+
+```typescript
+{
+  name: 'overview',           // 必填：Dashboard 标识（同模型命名规则）
+  description: { 'zh-CN': '数据概览', 'en-US': 'Overview' },  // 可选：支持多语言
+  models: ['model_a'],        // 必填：关联的数据模型名列表
+  layout: [{                  // 必填：布局定义，数组每项代表一行
+    row: [{                   // 每行包含一组 widget
+      type: 'stat',           // 图表类型，见下方图表类型表
+      title: { 'zh-CN': '总数', 'en-US': 'Total' },  // 支持多语言
+      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 字段时有效 |
+
+### Dashboard 级别配置
+
+除了 `layout` 中的 widget 配置，Dashboard 还支持以下顶级配置：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `defaultDateField` | string | 默认日期字段名。启用后 Dashboard 顶部显示日期范围选择器，选择日期后筛选条件发送到后端（`__range` filter） |
+| `filterDimensions` | `DashboardFilterDimension[]` | 筛选维度定义。启用后 Dashboard 顶部显示对应的筛选控件，选择的值作为 filter 发送到后端 |
+
+#### DashboardFilterDimension
+
+```typescript
+{
+  field: 'subject',           // 必填：筛选字段名
+  label: { 'zh-CN': '科目' }, // 必填：显示标签，支持多语言
+  type: 'select',             // 必填：'select'（下拉选择）| 'dateRange'（日期范围）
+  options: ['语文', '数学'],   // 可选：select 类型的选项。省略则从数据中自动提取去重值
+}
+```
+
+**筛选机制：** 日期范围和 select 筛选器变更后只加载符合条件的数据，清除筛选后恢复加载全量数据。
+
+**典型配置：**
+
+```typescript
+dashboards: [{
+  name: 'overview',
+  models: ['wrong_questions'],
+  defaultDateField: 'createdAt',          // 启用日期范围筛选
+  filterDimensions: [                      // 启用下拉筛选
+    { field: 'subject', label: { 'zh-CN': '科目', 'en-US': 'Subject' }, type: 'select' },
+    { field: 'difficulty', label: { 'zh-CN': '难度', 'en-US': 'Difficulty' }, type: 'select' },
+  ],
+  layout: [/* ... */],
+}]
+```
+
+### 图表类型与配置要点
+
+#### 数值类 — 展示关键指标
+
+| 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: { 'zh-CN': '错题数据概览', 'en-US': 'Overview' },
+    models: ['wrong_questions', 'review_plans'],
+    defaultDateField: 'createdAt',
+    filterDimensions: [
+      { field: 'subject', label: { 'zh-CN': '科目', 'en-US': 'Subject' }, type: 'select' },
+      { field: 'difficulty', label: { 'zh-CN': '难度', 'en-US': 'Difficulty' }, type: 'select' },
+    ],
+    layout: [
+      {
+        row: [
+          { type: 'stat', title: { 'zh-CN': '错题总数', 'en-US': 'Total Questions' }, model: 'wrong_questions', aggregate: 'count', span: 4 },
+          { type: 'stat', title: { 'zh-CN': '掌握率', 'en-US': 'Mastery Rate' }, model: 'wrong_questions', aggregate: 'ratio', filter: { isMastered: true }, span: 4 },
+          { type: 'gauge', title: { 'zh-CN': '掌握率仪表盘', 'en-US': 'Mastery Gauge' }, model: 'wrong_questions', aggregate: 'ratio', filter: { isMastered: true }, span: 6 },
+          { type: 'liquid', title: { 'zh-CN': '掌握率水波图', 'en-US': 'Mastery Liquid' }, model: 'wrong_questions', aggregate: 'ratio', filter: { isMastered: true }, span: 5 },
+          { type: 'stat', title: { 'zh-CN': '平均复习次数', 'en-US': 'Avg Reviews' }, model: 'wrong_questions', aggregate: 'avg', field: 'reviewCount', span: 5 }
+        ]
+      },
+      {
+        row: [
+          { type: 'pie', title: { 'zh-CN': '科目分布', 'en-US': 'By Subject' }, model: 'wrong_questions', groupBy: 'subject', span: 8 },
+          { type: 'ring', title: { 'zh-CN': '难度分布', 'en-US': 'By Difficulty' }, model: 'wrong_questions', groupBy: 'difficulty', span: 8 },
+          { type: 'bar', title: { 'zh-CN': '错误类型分布', 'en-US': 'By Error Type' }, model: 'wrong_questions', groupBy: 'errorType', span: 8 }
+        ]
+      },
+      {
+        row: [
+          { type: 'line', title: { 'zh-CN': '错题录入趋势', 'en-US': 'Questions Trend' }, model: 'wrong_questions', groupBy: 'createdAt', interval: 'month', span: 12 },
+          { type: 'area', title: { 'zh-CN': '复习计划趋势', 'en-US': 'Review Plans Trend' }, model: 'review_plans', groupBy: 'createdAt', interval: 'month', span: 12 }
+        ]
+      },
+      {
+        row: [
+          { type: 'radar', title: { 'zh-CN': '各科目概览', 'en-US': 'Subject Overview' }, model: 'wrong_questions', groupBy: 'subject', span: 8 },
+          { type: 'stacked_bar', title: { 'zh-CN': '科目×错误类型', 'en-US': 'Subject × Error Type' }, model: 'wrong_questions', groupBy: 'subject', crossGroupBy: 'errorType', span: 8 },
+          { type: 'grouped_bar', title: { 'zh-CN': '科目×难度', 'en-US': 'Subject × Difficulty' }, model: 'wrong_questions', groupBy: 'subject', crossGroupBy: 'difficulty', span: 8 }
+        ]
+      },
+      {
+        row: [
+          { type: 'scatter', title: { 'zh-CN': '科目分布散点', 'en-US': 'Subject Scatter' }, model: 'wrong_questions', groupBy: 'subject', span: 8 },
+          { type: 'funnel', title: { 'zh-CN': '错误类型漏斗', 'en-US': 'Error Type Funnel' }, model: 'wrong_questions', groupBy: 'errorType', span: 8 },
+          { type: 'treemap', title: { 'zh-CN': '科目×难度树图', 'en-US': 'Subject × Difficulty Tree' }, model: 'wrong_questions', groupBy: 'subject', crossGroupBy: 'difficulty', span: 8 }
+        ]
+      },
+      {
+        row: [
+          { type: 'heatmap', title: { 'zh-CN': '科目×年级热力图', 'en-US': 'Subject × Grade Heatmap' }, 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,196 @@
+# 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: { 'zh-CN': '状态', 'en-US': 'Status' },  // optional: LocaleString, 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 (storage values)
+  enumLabels: {            // optional: display labels per locale for each enum value
+    active: { 'zh-CN': '激活', 'en-US': 'Active' },
+    inactive: { 'zh-CN': '停用', 'en-US': 'Inactive' },
+    archived: { 'zh-CN': '归档', 'en-US': 'Archived' },
+  },
+}
+```
+
+## ModelSchema
+
+```typescript
+{
+  name: 'orders',              // ^[a-zA-Z][a-zA-Z0-9_]*$, will be used as React component name
+  description: { 'zh-CN': '订单记录', 'en-US': 'Order Records' },  // optional: LocaleString, shown in page heading
+  fields: [...],
+  indexes?: [{ fields: ['userId', 'status'], unique: false }],
+  adapters?: {                  // optional: per-model adapter override
+    filesystem: { dir: 'orders', format: 'json' | 'yaml', datePattern: 'YYYY-MM' },  // datePattern: date-partitioned sub-directories using the model's first date field
+    sqlite: { table: 'orders' },
+  },
+  crud?: {                      // optional: control CRUD page features (all default to true when omitted)
+    batch: true,                // optional: enable batch selection and batch delete
+    export: true,               // optional: enable CSV export button
+    import: true,               // optional: enable CSV import button
+    deleteWithUndo: true,       // optional: delete-with-undo instead of confirm dialog; set false to use confirm dialog
+  },
+}
+```
+
+## AIButtonConfig
+
+```typescript
+aiButtons: [{
+  id: 'summarize',          // required: unique identifier
+  label: { 'zh-CN': '总结', 'en-US': 'Summarize' },  // required: LocaleString, 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 (default: true in headless mode — Claude Code runs without interactive terminal, so permissions are skipped unless explicitly set to false)
+    models: [                       // optional: available AI models
+      {
+        name: 'GLM-5.1',           // required: model name, passed to --model flag
+        authToken: 'sk-xxx',       // optional: ANTHROPIC_AUTH_TOKEN, passed via --settings
+        baseUrl: 'https://api.example.com',  // optional: ANTHROPIC_BASE_URL, passed via --settings
+        isDefault: true,           // optional: default model for new chats
+      },
+    ],
+  },
+}
+```
+
+Models can be managed via the Model Management page (System Settings → Model Management) or by editing `loom.config.ts` directly. On `loom init`, the default model is auto-detected from `~/.claude/settings.json` (ANTHROPIC_MODEL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL).
+
+## 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'
+}
+```
+
+## UIConfig
+
+```typescript
+ui: {
+  theme: {                       // optional: theme configuration
+    defaultMode: 'light',        // optional: 'light' | 'dark', default 'light'
+    token: { colorPrimary: '#1677ff' },  // optional: Ant Design token overrides
+  },
+  siderCollapsed: false,         // optional: sidebar collapsed by default on desktop
+  showHeader: true,              // optional: show header bar (breadcrumbs + theme toggle)
+  locale: 'zh-CN',              // optional: 'zh-CN' | 'en-US', default 'zh-CN'
+}
+```
+
+## RelationConfig
+
+```typescript
+relations: [{
+  name: 'question_reviews',            // required: unique relation identifier
+  label: { 'zh-CN': '复习记录', 'en-US': 'Review Records' },  // optional: LocaleString
+  from: 'wrong_questions',             // required: source model name
+  to: 'review_plans',                  // required: target model name
+  foreignKey: 'questionId',            // required: foreign key field in target model
+  type: 'hasMany',                     // required: 'hasOne' | 'hasMany' | 'manyToMany'
+  through: 'enrollments',              // optional: pivot model for manyToMany
+}]
+```
+
+Relations are displayed in the detail drawer of generated CRUD pages. `hasMany` and `manyToMany` relations show as a nested table.
+
+## DashboardConfig
+
+```typescript
+dashboards: [{
+  name: 'overview',           // ^[a-zA-Z][a-zA-Z0-9_]*$, same naming rules as model
+  description: { 'zh-CN': '数据概览', 'en-US': 'Overview' },  // optional: LocaleString, shown in sidebar
+  models: ['items'],          // required: data models included in this dashboard
+  defaultDateField: 'createdAt',  // optional: default date field for date range filtering across all widgets
+  filterDimensions: [             // optional: filter bar dimensions for interactive filtering
+    {
+      field: 'status',            // required: field name to filter on
+      label: { 'zh-CN': '状态', 'en-US': 'Status' },  // required: LocaleString
+      type: 'select',             // required: 'select' | 'dateRange'
+      options: ['active', 'inactive'],  // optional: for 'select' type, auto-derived from data if omitted
+    },
+    {
+      field: 'createdAt',
+      label: { 'zh-CN': '日期范围', 'en-US': 'Date Range' },
+      type: 'dateRange',
+    },
+  ],
+  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: { 'zh-CN': '任务总数', 'en-US': 'Total Tasks' },  // required: LocaleString, 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
+      dateField: 'createdAt', // optional: per-widget date field override (falls back to dashboard.defaultDateField)
+    }],
+  }],
+}]
+```
+
+## useSchema Runtime API
+
+Generated pages use `useSchema(model)` to fetch model schema and AI buttons at runtime. Schema is auto-resolved by current locale:
+
+```typescript
+const { schema, loading, error } = useSchema('items');
+// schema.fields — field definitions with resolved LocaleString (e.g. description is string, not LocaleString)
+// schema.fields[].enumLabels — resolved to { [enumValue]: displayLabel } for current locale
+// schema.aiButtons — AI buttons filtered by placement, label resolved to current locale
+
+// Convert schema enum to antd formats (uses resolved enumLabels):
+filterOptions(schema, 'status')  // → [{ text: '激活', value: 'active' }, ...]
+selectOptions(schema, 'status')  // → [{ label: '激活', value: 'active' }, ...]
+
+// Get display label for a single enum value:
+enumLabel(schema, 'status', 'active')  // → '激活'
+```
+
+## LocaleString
+
+All user-facing string fields support `LocaleString` format: `string | Record<string, string>`.
+
+- **Simple**: `description: '科目'` — same text for all locales
+- **Multi-locale**: `description: { 'zh-CN': '科目', 'en-US': 'Subject' }` — auto-translated on locale switch
+- **Fallback**: requested locale → `'zh-CN'` → first available value
+
+Supported fields: `project.description`, `ModelSchema.description`, `FieldDefinition.description`, `AIButtonConfig.label`, `DashboardConfig.description`, `DashboardWidget.title`, `RelationConfig.label`, `DashboardFilterDimension.label`

package/dist/adapter-base.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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>;
+    /** Default count() — delegates to read(), overridden by adapters for efficiency */
+    count(model: string, options?: Omit<import('./types.js').ReadOptions, 'limit' | 'offset' | 'sort'>): Promise<number>;
+    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;IAEzD,mFAAmF;IAC7E,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,OAAO,YAAY,EAAE,WAAW,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAMpH,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,69 @@
+/**
+ * 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);
+        }
+    }
+    /** Default count() — delegates to read(), overridden by adapters for efficiency */
+    async count(model, options) {
+        const result = await this.read(model, { filter: options?.filter, id: options?.id });
+        if (Array.isArray(result))
+            return result.length;
+        return result ? 1 : 0;
+    }
+    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"}