@vegamo/loom 0.1.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025 Loom Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,465 @@
+# Loom
+
+<div align="center">
+
+AI-powered JSON Schema document generator with TUI, web viewer and mock server
+
+[![Node.js](https://img.shields.io/badge/Node.js-≥18.0.0-green)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
+
+</div>
+
+## ✨ Features
+
+- **🤖 AI-Powered Schema Generation** - Interactive TUI chat interface to generate and update JSON Schema API documentation using LLMs (DeepSeek, OpenAI)
+- **🧩 Entity-Centric Modeling** - Manage reusable entity schemas in `docs/entities` and reference them in endpoint schemas via `x-entity-ref`
+- **📚 Modern Web Viewer** - React-based SPA for browsing modules, endpoints, and entities with interactive schema rendering
+- **⚡ Mock Server** - Dynamic mock API server that generates realistic test data based on JSON Schema
+- **🖥️ In-Chat Service Control** - Start/stop/restart mock server and web viewer directly inside TUI (`/mock`, `/view`)
+- **🗂️ Manifest Indexing** - Built-in manifest rebuild command for dependency/index consistency (`loom manifest rebuild`)
+- **🔧 TypeScript First** - Fully typed with modern TypeScript architecture
+
+## 📦 Installation
+
+### Prerequisites
+- Node.js ≥ 18.0.0
+- npm or yarn
+- DeepSeek API key (for chat functionality)
+
+### Global Installation
+```bash
+npm install -g loom
+# or
+yarn global add loom
+```
+
+### Local Development
+```bash
+git clone <repository-url>
+cd loom
+npm install
+npm run build:all
+```
+
+## ⚙️ Configuration
+
+### Configuration File
+Loom now uses only `loom.config.json` (no `.env` dependency).
+
+When you run `loom chat` for the first time, it will guide you to create/update this file interactively.
+
+Default chat onboarding values:
+- `provider`: `deepseek`
+- `model`: `deepseek-chat`
+- `baseURL`: `https://api.deepseek.com/v1`
+- `apiKey`: required, must be entered by user
+
+You can also create `loom.config.json` manually:
+```json
+{
+  "outDir": "docs",
+  "llm": {
+    "provider": "deepseek",
+    "model": "deepseek-chat",
+    "baseURL": "https://api.deepseek.com/v1",
+    "apiKey": "your_deepseek_api_key",
+    "temperature": 0.7,
+    "maxTokens": 2000
+  },
+  "serve": {
+    "port": 3000,
+    "host": "0.0.0.0"
+  },
+  "mock": {
+    "port": 3001,
+    "host": "0.0.0.0"
+  }
+}
+```
+
+## 🚀 Quick Start
+
+### 1. Generate API Documentation
+```bash
+# Start interactive TUI to generate JSON Schema
+loom chat
+
+# Or specify project directory
+loom chat --dir ./my-api-project
+```
+
+In `loom chat`, you can also control local services:
+- `/mock`, `/mock stop`, `/mock restart [port]`
+- `/view`, `/view stop`, `/view restart [port]`
+
+### 2. View Documentation
+```bash
+# Start web documentation viewer
+loom view
+
+# Or with custom port
+loom view --port 8080
+```
+
+### 3. Start Mock Server
+```bash
+# Start mock API server
+loom mock
+
+# Or with custom port
+loom mock --port 8081
+```
+
+### 4. Combined Service (Recommended)
+```bash
+# Start both viewer and mock server on same port
+loom serve
+
+# Access at:
+# - Web Viewer: http://localhost:3000
+# - Mock API: http://localhost:3000/mock/...
+```
+
+## 📖 Usage Guide
+
+### `loom chat`
+Interactive terminal UI for generating JSON Schema documents through AI conversation.
+
+```bash
+loom chat [options]
+
+Options:
+  -d, --dir <path>    Target project directory (default: current directory)
+  -h, --help          Display help
+```
+
+**Example Workflow:**
+1. Run `loom chat`
+2. Describe your API endpoints in natural language
+3. AI generates JSON Schema with proper structure
+4. Schema files are saved to `docs/` directory (configurable)
+
+**Built-in chat commands:**
+- `/help` — Show command help
+- `/reset` — Reset conversation history
+- `/list` — List generated schema files
+- `/mock`, `/mock stop`, `/mock restart [port]` — Manage mock server
+- `/view`, `/view stop`, `/view restart [port]` — Manage web viewer
+- `/abort` — Abort current request
+- `/exit` — Exit Loom
+
+### `loom view`
+Modern web-based documentation viewer with React SPA interface.
+
+```bash
+loom view [options]
+
+Options:
+  -p, --port <number>  Port number (default: 3000)
+  -d, --dir <path>     Target project directory (default: current directory)
+  -h, --help           Display help
+```
+
+**Features:**
+- 📁 Module browsing with endpoint counts
+- 🧩 Entity browsing from `docs/entities`
+- 🔍 Real-time search across modules and endpoints
+- 📊 Interactive JSON schema viewer with expand/collapse
+- 🔗 `x-entity-ref` auto-resolve in endpoint request/response rendering
+- 🎨 Clean, responsive UI with dark sidebar
+- 🔗 Direct links to specific endpoints
+
+### `loom mock`
+Dynamic mock API server that generates realistic data based on JSON Schema.
+
+```bash
+loom mock [options]
+
+Options:
+  -p, --port <number>  Port number (default: 3001)
+  -d, --dir <path>     Target project directory (default: current directory)
+  -h, --help           Display help
+```
+
+**Features:**
+- 🚀 Automatic route registration from JSON Schema files
+- 🎲 Smart mock data generation using mock-json-schema
+- 📡 Support for all HTTP methods (GET, POST, PUT, DELETE, PATCH)
+- 🔧 Configurable response status codes and schemas
+
+### `loom serve`
+Combined service that runs both web viewer and mock server together.
+
+```bash
+loom serve [options]
+
+Options:
+  -p, --port <number>  Port number (default: 3000)
+  -d, --dir <path>     Target project directory (default: current directory)
+  -h, --help           Display help
+```
+
+**URL Structure:**
+- `http://localhost:3000/` - Web documentation viewer
+- `http://localhost:3000/api/docs` - Documentation API
+- `http://localhost:3000/api/schemas` - Schema file API
+- `http://localhost:3000/api/entities` - Entity file API
+- `http://localhost:3000/mock/...` - Mock API endpoints
+
+### `loom manifest rebuild`
+Rebuild docs manifest index file (`.loom-manifest.json`) for dependency/index consistency.
+
+```bash
+loom manifest rebuild [options]
+
+Options:
+  -d, --dir <path>  Target project directory (default: current directory)
+  -h, --help        Display help
+```
+
+## 📝 JSON Schema Format
+
+Loom uses a custom JSON Schema format optimized for API documentation:
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Authentication API",
+  "description": "User authentication endpoints",
+  "version": "1.0.0",
+  "endpoints": [
+    {
+      "path": "/api/auth/login",
+      "method": "POST",
+      "summary": "User login",
+      "description": "Authenticate user with credentials",
+      "tags": ["auth"],
+      "request": {
+        "headers": {
+          "Content-Type": { "type": "string", "enum": ["application/json"] }
+        },
+        "body": {
+          "type": "object",
+          "properties": {
+            "username": { "type": "string" },
+            "password": { "type": "string" }
+          },
+          "required": ["username", "password"]
+        }
+      },
+      "response": {
+        "200": {
+          "type": "object",
+          "properties": {
+            "token": { "type": "string" },
+            "user": { "type": "object" }
+          }
+        },
+        "400": {
+          "type": "object",
+          "properties": {
+            "error": { "type": "string" }
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+### Schema Structure
+- **title**: API module title
+- **description**: Module description
+- **endpoints**: Array of API endpoint definitions
+- **endpoint.path**: URL path (supports path parameters)
+- **endpoint.method**: HTTP method (GET, POST, PUT, DELETE, PATCH)
+- **endpoint.request**: Optional request schema (headers, params, query, body)
+- **endpoint.response**: Response schemas keyed by status code
+
+## 🧩 Entity Schema & References
+
+Loom supports reusable entity schemas in:
+
+```text
+docs/entities/*.entity.schema.json
+```
+
+Example entity file:
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "User",
+  "description": "Reusable user entity",
+  "type": "object",
+  "properties": {
+    "id": { "type": "integer" },
+    "name": { "type": "string" },
+    "email": { "type": "string", "format": "email" }
+  },
+  "required": ["id", "name", "email"]
+}
+```
+
+In endpoint schemas, reference an entity with `x-entity-ref`:
+
+```json
+{
+  "user": {
+    "x-entity-ref": {
+      "entity": "User",
+      "pick": ["id", "name", "email"]
+    }
+  }
+}
+```
+
+Supported forms:
+- String form: `"x-entity-ref": "User"`
+- Object form: `"x-entity-ref": { "entity": "User", "pick": ["id", "name"] }`
+
+## 🏗️ Project Structure
+
+```
+loom/
+├── src/
+│   ├── agents/          # AI agent system with tool calling
+│   │   ├── core/        # Agent core logic
+│   │   └── memory/      # Conversation memory management
+│   ├── llm/             # LLM client (DeepSeek, OpenAI)
+│   │   ├── client.ts    # Streaming LLM client
+│   │   └── config.ts    # LLM configuration
+│   ├── tools/           # Tool system for agent
+│   │   ├── schema-gen.ts     # Schema generation tools
+│   │   ├── schema-validate.ts # Schema validation tools
+│   │   ├── file-ops.ts        # Schema file operations tools
+│   │   ├── entity-file-ops.ts # Entity file operations tools
+│   │   └── entity-workflow.ts # Entity impact/sync/validate tools
+│   ├── tui/             # Terminal UI (chat interface)
+│   │   ├── app.tsx      # Main TUI application
+│   │   └── components/  # React components for TUI
+│   ├── view/            # Web documentation viewer
+│   │   ├── server.ts    # Fastify web server
+│   │   ├── routes/      # API routes
+│   │   ├── frontend/    # React SPA frontend
+│   │   └── public/      # Static assets
+│   ├── mocks/           # Mock server
+│   │   ├── server.ts    # Mock server implementation
+│   │   ├── router.ts    # Dynamic route registration
+│   │   └── generator.ts # Mock data generation
+│   ├── shared/          # Shared utilities
+│   │   ├── config.ts    # Configuration loader
+│   │   ├── entity-utils.ts     # Entity read/write/reference helpers
+│   │   ├── manifest-utils.ts   # Manifest index builder
+│   │   ├── schema-entity-resolver.ts # x-entity-ref resolver for viewer APIs
+│   │   ├── types.ts     # TypeScript definitions
+│   │   └── logger.ts    # Logging utilities
+│   ├── serve.ts         # Combined viewer + mock server
+│   └── index.ts         # CLI entry point
+├── docs/                # Generated schema files
+├── scripts/             # Build scripts
+├── dist/                # Compiled output
+└── package.json
+```
+
+## 🛠️ Development
+
+### Building the Project
+```bash
+# Build TypeScript backend
+npm run build
+
+# Build React frontend
+npm run build:view
+
+# Build both (recommended)
+npm run build:all
+```
+
+### Development Mode
+```bash
+# Start TypeScript development server
+npm run dev
+
+# Watch mode for frontend development
+npm run dev:view
+```
+
+### Adding New Features
+1. **New LLM Provider**: Extend `src/llm/config.ts` and `src/llm/client.ts`
+2. **New Agent Tool**: Add under `src/tools/` and register in `src/agents/core/agent.ts`
+3. **UI Component**: Add to `src/view/frontend/components/`
+4. **API Endpoint**: Add to `src/view/routes/` or `src/mocks/router.ts`
+
+## 📦 Publishing to npm
+
+For maintainers, to publish a new version to npm registry:
+
+```bash
+# Login to npm (first time only)
+npm login
+
+# Update version if needed
+npm version patch  # or minor, major
+
+# Build and create package
+npm run build:all
+
+# Publish to npm
+npm publish
+
+# Or publish with dry-run first
+npm publish --dry-run
+```
+
+The package includes:
+- Compiled JavaScript in `dist/`
+- TypeScript definitions
+- Pre-built React frontend bundle
+- CLI executable (`loom`)
+
+Package configuration:
+- `prepack` script ensures fresh build before packaging
+- `.npmignore` excludes source files and development artifacts
+- All runtime dependencies are correctly specified
+
+## 🤝 Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. **Fork** the repository
+2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
+3. **Commit your changes**: `git commit -m 'Add amazing feature'`
+4. **Push to the branch**: `git push origin feature/amazing-feature`
+5. **Open a Pull Request**
+
+### Development Guidelines
+- Use TypeScript with strict mode
+- Follow existing code style and patterns
+- Add tests for new functionality
+- Update documentation as needed
+
+## 📄 License
+
+This project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- [DeepSeek](https://www.deepseek.com/) for AI capabilities
+- [Fastify](https://fastify.io/) for high-performance web server
+- [React](https://reactjs.org/) for UI components
+- [mock-json-schema](https://github.com/anttiviljami/mock-json-schema) for mock data generation
+- [Ink](https://github.com/vadimdemedes/ink) for terminal UI
+
+## 📞 Support
+
+- **Issues**: [GitHub Issues](https://github.com/yourusername/loom/issues)
+- **Documentation**: This README and code comments
+- **Questions**: Open an issue or discussion
+
+---
+
+<div align="center">
+Made with ❤️ by the Loom team
+</div>

package/dist/agents/core/agent.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Agent 主类
+ *
+ * 核心职责: 编排 LLM 调用与 Tool 执行的循环
+ *
+ * 流程:
+ * 1. 接收用户输入
+ * 2. 构建 messages (system prompt + memory + user message)
+ * 3. 调用 LLM (streaming)
+ * 4. 如果 LLM 返回 tool_calls → 执行工具 → 将结果拼入 messages → 回到步骤 3
+ * 5. 如果 LLM 返回纯文本 → 返回给用户
+ *
+ * 特性:
+ * - 支持 streaming (逐字输出到 TUI)
+ * - 自动降级到非 streaming (如果 streaming 不可用)
+ * - 完善的错误分类和向上传播
+ * - 通过事件系统通知上层进度
+ */
+import type { AgentConfig, AgentReply, AgentState, AgentEventCallback } from './types.js';
+export declare class Agent {
+    private llm;
+    private tools;
+    private memory;
+    private config;
+    private toolContext;
+    private state;
+    private abortController;
+    /** 事件回调 */
+    onEvent?: AgentEventCallback;
+    /** 向后兼容的状态变更回调 */
+    onStateChange?: (event: {
+        state: AgentState;
+        message?: string;
+        toolName?: string;
+    }) => void;
+    constructor(config: AgentConfig);
+    /**
+     * 处理用户输入，返回 Agent 回复
+     *
+     * 根据 config.streaming 自动选择 streaming 或非 streaming 模式
+     */
+    chat(userMessage: string): Promise<AgentReply>;
+    /**
+     * 中断当前请求
+     */
+    abort(): void;
+    /**
+     * 重置对话
+     */
+    reset(): void;
+    /**
+     * 非 streaming LLM 调用
+     */
+    private callLLM;
+    /**
+     * Streaming LLM 调用
+     *
+     * 逐字发送 content_delta 事件到 TUI，同时累积完整响应
+     */
+    private callLLMStreaming;
+    private initSystemPrompt;
+    private setState;
+    private emit;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agents/core/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/agents/core/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAkBH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAc,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAKtG,qBAAa,KAAK;IAChB,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,eAAe,CAAgC;IAEvD,WAAW;IACJ,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAEpC,kBAAkB;IACX,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,UAAU,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;gBAEvF,MAAM,EAAE,WAAW;IAmC/B;;;;OAIG;IACG,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAoJpD;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,KAAK,IAAI,IAAI;IAWb;;OAEG;YACW,OAAO;IAQrB;;;;OAIG;YACW,gBAAgB;IAsB9B,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,IAAI;CAGb"}