@loom-framework/core 0.1.0-alpha.39 → 0.1.0-alpha.40

package/templates/skill/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: Loom
+description: |
+  Use this skill when the user asks to "create a new loom project", "用loom开发一个系统",
+  "开发一个AI平台应用", "为系统添加页面", "为项目配置 AI 按钮功能", or any Loom framework task.
+  Loom is an AI-Native full-stack framework.
+version: 0.1.0
+---
+
+# Loom - AI-Native Framework Skill
+
+## Quick Start
+
+1. Confirm project scope: name, description, data models, skills
+2. Create project:
+   `npx @loom-framework/core@latest loom init <name> --description <desc> --adapter <filesystem|sqlite>`
+3. Define data models in `loom.config.ts` (see Schema below)
+4. Generate pages: `loom generate page <Name> --model <model>`
+5. Start dev: `loom dev` → http://localhost:5173 (frontend), http://localhost:3000 (backend)
+
+**Important:** Always run commands from the project directory (not the loom monorepo root).
+
+## Core CLI Commands
+
+- `loom dev` - Start dev environment (hot-reload)
+  - `--skip-generate`, `--backend-only`, `--frontend-only`
+- `loom build` - Build for production
+- `loom generate capabilities` - Generate MCP Server + CLI from config
+- `loom generate page <name> --model <model>` - Generate CRUD page (includes capabilities + wiring)
+- `loom generate skill <name>` - Generate skill scaffold
+
+## Detailed Workflows
+
+### Adding a New Data Model
+
+1. Edit `loom.config.ts` → add model definition (see Schema below; for advanced options see `references/data-model.md`)
+2. Run `loom generate page <Name> --model <model-name>`
+3. Model is immediately available via MCP Tools and `loom data` CLI
+
+### Adding a New Skill
+
+1. Create scaffold: `loom generate skill <name>`
+2. Edit `.claude/skills/<name>/SKILL.md` (see `references/skill-development.md` for format)
+3. Add reference prompts in `.claude/skills/<name>/references/`
+
+### Adding an AI Button
+
+1. Edit `loom.config.ts` → add entry to `aiButtons` array (top-level, not inside `ai`)
+2. In frontend page, use `useAIButton('<button-id>')` or `<AIActionButton buttonId="<id>" />`
+
+## loom.config.ts Schema (Core)
+
+```typescript
+import { defineConfig } from '@loom-framework/core';
+
+export default defineConfig({
+  project: {
+    name: 'my-app',           // required
+    description: '...',',     // optional
+  },
+  data: {
+    defaultAdapter: 'filesystem',  // 'filesystem' | 'sqlite'
+    models: [{
+      name: 'items',          // lowercase, hyphens/underscores allowed
+      description: '...',',   // optional: shown in generated pages
+      fields: [{
+        name: 'status',       // alphanumeric + underscore, start with letter/underscore
+        type: 'string',       // 'string' | 'number' | 'boolean' | 'date' | 'string[]' | 'number[]' | 'json'
+        required: true,       // optional, default false
+        description: '...,',  // optional: shown in forms
+        default: 'active',    // optional: auto-filled on write
+        enum: ['active', 'inactive'],  // optional: restrict values
+      }],
+    }],
+  },
+  aiButtons: [{               // optional
+    id: 'summarize',          // required: unique identifier
+    label: '总结',             // required: button text
+    prompt: '请总结以下内容',    // required (or promptTemplate)
+  }],
+});
+```
+
+For advanced config (`ai.claudeCode`, `server`, per-model `adapters`, `indexes`, `aiButtons.promptTemplate/contextVars`), see `references/data-model.md`.
+
+## Troubleshooting
+
+- **`loom` commands fail "No loom.config.ts found"**: Run commands from the project directory, not the loom monorepo root
+- **create-loom-app not on npm**: Use `npx @loom-framework/core loom init <name> --description <desc> --adapter <filesystem|sqlite>`
+
+See `references/troubleshooting.md` for more issues.

package/templates/skill/references/README.md

@@ -0,0 +1,67 @@
+# Loom - AI-Native Full-Stack Framework
+
+编织 AI 能力为应用织物
+
+## 核心理念
+
+- **Prompt as Code**: 业务逻辑写在 Skill 的 Markdown 中，而非后端代码
+- **Schema-driven**: 一个模型定义 → MCP Tool + CLI 命令 + REST API（自动同步）
+- **Zero Backend Logic**: 后端是透明代理，所有智能在 Skill 中
+
+## 三种交互类型
+
+| 类型 | 说明 | 实现方式 |
+|------|------|---------|
+| AI Chat | 自然语言对话 | HTTP SSE 流式，Claude Code 引擎 |
+| AI Buttons | 一键 AI 动作 | 预定义 Prompt，`aiButtons` 配置 |
+| CRUD | 结构化数据管理 | REST API，Schema 驱动自动生成 |
+
+## 项目结构
+
+```
+my-loom-app/
+├── loom.config.ts       # 唯一配置源（模型、AI 按钮、服务器配置）
+├── frontend/            # React + TypeScript + Vite
+│   └── src/pages/       # 业务页面（CRUD 等）
+├── backend/src/         # Fastify + AI 通信（LoomServer）
+├── .claude/skills/      # Skills（Prompt as Code）
+├── cli/src/commands/    # CLI 业务命令扩展
+├── data/                # 数据存储（DataAdapter 管理）
+└── .loom/               # 自动生成（gitignore）
+    ├── mcp-server/      # MCP Server（自动生成）
+    └── mcp.json         # MCP 配置
+```
+
+## CLI 命令速查
+
+### 开发
+
+| 命令 | 说明 |
+|------|------|
+| `loom dev` | 启动开发环境（前端 + 后端，热更新） |
+| `loom build` | 生产构建 |
+
+### 生成
+
+| 命令 | 说明 |
+|------|------|
+| `loom generate page <Name> --model <model>` | 生成 CRUD 页面 |
+| `loom generate skill <name>` | 生成 Skill 脚手架 |
+| `loom generate capabilities` | 重新生成 MCP Server + CLI |
+
+### 数据
+
+| 命令 | 说明 |
+|------|------|
+| `loom data read <model>` | 读取记录 |
+| `loom data write <model> --data '<json>'` | 写入记录 |
+| `loom data schema [model]` | 查看模型定义 |
+
+### 其他
+
+| 命令 | 说明 |
+|------|------|
+| `loom skill list` | 列出所有 Skill |
+| `loom skill validate [name]` | 校验 Skill 结构 |
+| `loom observe logs` | 查看 AI 交互日志 |
+| `loom observe metrics` | 查看聚合指标 |

package/templates/skill/references/data-model.md

@@ -0,0 +1,87 @@
+# Data Model Reference
+
+Advanced configuration for `loom.config.ts` data models. Load this when defining complex models.
+
+## Full Field Options
+
+```typescript
+{
+  name: 'status',         // must match ^[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 to allowed values
+}
+```
+
+## Model-Level Options
+
+```typescript
+{
+  name: 'orders',
+  description: 'Order records',  // shown in generated page heading
+  fields: [...],
+  indexes: [                     // optional: database indexes
+    { fields: ['userId', 'status'], unique: false },
+  ],
+  adapters: {                    // optional: per-model adapter override
+    filesystem: { dir: 'orders', format: 'json' | 'yaml', datePattern: 'yyyy-MM-dd' },
+    sqlite: { table: 'orders' },
+  },
+},
+```
+
+## AI Configuration
+
+```typescript
+ai: {
+  engine: 'claude-code',           // default 'claude-code'
+  claudeCode: {
+    path: '/usr/local/bin/claude', // custom claude binary path
+    pluginRoot: '.claude',         // plugin root directory
+    timeout: 120000,               // command timeout in ms
+    skipPermissions: false,        // skip permission prompts
+    defaultModel: 'claude-sonnet-4-6',
+  },
+},
+```
+
+## Server Configuration
+
+```typescript
+server: {
+  port: 3000,              // default 3000
+  host: '0.0.0.0',
+  cors: true,              // default true
+  staticDir: './dist/frontend',
+},
+```
+
+## SQLite Configuration
+
+```typescript
+data: {
+  defaultAdapter: 'sqlite',
+  sqlite: { filename: 'data.db' },  // default 'loom.db'
+}
+```
+
+## AI Buttons (Full Options)
+
+```typescript
+aiButtons: [{
+  id: 'summarize',               // required: unique identifier
+  label: '总结',                  // required: button text
+  icon: 'FileTextOutlined',      // optional: Ant Design icon name
+  prompt: '请总结以下内容',         // required (or promptTemplate)
+  promptTemplate: 'Summarize {{content}}',  // alternative to prompt, with {{vars}}
+  contextVars: ['content'],      // optional: variable names for promptTemplate
+  placement: 'page-header',      // optional: UI placement hint
+}],
+```
+
+## Data Access in Skills
+
+- **Prefer MCP Tools** for data CRUD: `read_<model>`, `write_<model>`, `update_<model>`, `delete_<model>`
+- Use `loom data read/write <model>` CLI only for debugging

package/templates/skill/references/skill-development.md

@@ -0,0 +1,46 @@
+# Skill Development Reference
+
+Guide for creating and managing Loom Skills. Load this when adding or editing `.claude/skills/`.
+
+## Skill Structure
+
+```
+.claude/skills/<skill-name>/
+├── SKILL.md          # Required: trigger conditions + workflow
+└── references/       # Optional: detailed rules and reference docs
+    └── *.md
+```
+
+## SKILL.md Format
+
+```markdown
+---
+name: <skill-name>
+description: |
+  This skill should be used when the user asks to "<trigger phrases>".
+  Include both English and Chinese trigger phrases.
+version: 1.0.0
+---
+
+# <Skill Name>
+
+<Description of what this skill does>
+
+## Workflow
+
+1. <Step 1>
+2. <Step 2>
+
+## Rules
+
+- <Rule 1>
+- <Rule 2>
+```
+
+## Best Practices
+
+- Keep SKILL.md focused on one capability domain
+- Use `references/` for detailed rules that would clutter the main SKILL.md
+- Specify which MCP Tools (`read_<model>`, `write_<model>`) the skill should use
+- Skills define behavior through prompts, not code generation
+- Run `loom skill validate [name]` to check SKILL.md structure

package/templates/skill/references/troubleshooting.md

@@ -0,0 +1,35 @@
+# Troubleshooting Guide
+
+Common issues when creating and running Loom projects.
+
+## `loom generate` Fails: Cannot find module '@loom-framework/core'
+
+Dependencies not installed. Run `npm install` from the project directory.
+
+## `loom dev` Port Already in Use (EADDRINUSE)
+
+Previous process still running. Kill it: `lsof -ti:3000 | xargs kill -9`
+
+## Commands Fail: "No loom.config.ts found"
+
+Running from the wrong directory. `cd` into the project directory before running `loom` commands.
+
+## Model Name Validation Error
+
+Model names must match `^[a-z][a-z0-9_-]*$` (lowercase, hyphens/underscores allowed).
+Field names must match `^[a-zA-Z_][a-zA-Z0-9_]*$`.
+
+## `loom build` Backend TSC Fails: Cannot use JSX
+
+Root `tsconfig.json` includes `frontend/` with `.tsx` files.
+Add `"frontend"` to `exclude` in root `tsconfig.json`:
+```json
+{ "exclude": ["node_modules", "dist", "frontend"] }
+```
+Frontend has its own `frontend/tsconfig.json` with `jsx: "react-jsx"`.
+
+## Debug Tips
+
+- `loom data schema <model>` — inspect model fields
+- `loom observe logs` — view AI interaction logs
+- `loom skill validate` — check skill structure