@vegamo/loom
Advanced tools
AI-powered JSON Schema document generator with TUI, web viewer and mock server
docs/entities and reference them in endpoint schemas via x-entity-ref/mock, /view)loom manifest rebuild)npm install -g loom
# or
yarn global add loom
git clone <repository-url>
cd loom
npm install
npm run build:all
Loom uses a global config file (no .env dependency).
Default global config path:
~/.loom/config.json%APPDATA%/loom/config.jsonOptional override:
LOOM_CONFIG=/custom/path/config.jsonWhen you run loom chat for the first time, it will guide you to create/update this global file interactively.
Default chat onboarding values:
provider: deepseekmodel: deepseek-chatbaseURL: https://api.deepseek.com/v1apiKey: required, must be entered by userYou can also create the global config manually:
{
"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"
}
}
docs/ remains in each project directory (--dir) and is not moved to global storage.
# 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]# Start web documentation viewer
loom view
# Or with custom port
loom view --port 8080
# Start mock API server
loom mock
# Or with custom port
loom mock --port 8081
# Start both viewer and mock server on same port
loom serve
# Access at:
# - Web Viewer: http://localhost:3000
# - Mock API: http://localhost:3000/mock/...
# Manually trigger upgrade
loom upgrade
Loom also checks npm for updates when you run commands.
If a newer version is found, you can confirm and let Loom auto-upgrade.
loom chatInteractive terminal UI for generating JSON Schema documents through AI conversation.
loom chat [options]
Options:
-d, --dir <path> Target project directory (default: current directory)
-h, --help Display help
Example Workflow:
loom chatdocs/ directory (configurable)Built-in chat commands:
Enter to send, Shift+Enter or Alt+Enter for newline/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 Loomloom viewModern web-based documentation viewer with React SPA interface.
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:
docs/entitiesx-entity-ref auto-resolve in endpoint request/response renderingloom mockDynamic mock API server that generates realistic data based on JSON Schema.
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:
loom serveCombined service that runs both web viewer and mock server together.
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 viewerhttp://localhost:3000/api/docs - Documentation APIhttp://localhost:3000/api/schemas - Schema file APIhttp://localhost:3000/api/entities - Entity file APIhttp://localhost:3000/mock/... - Mock API endpointsloom manifest rebuildRebuild docs manifest index file (.loom-manifest.json) for dependency/index consistency.
loom manifest rebuild [options]
Options:
-d, --dir <path> Target project directory (default: current directory)
-h, --help Display help
loom upgradeUpgrade loom to the latest npm version.
loom upgrade
Loom uses a custom JSON Schema format optimized for API documentation:
{
"$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" }
}
}
}
}
]
}
Loom supports reusable entity schemas in:
docs/entities/*.entity.schema.json
Example entity file:
{
"$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:
{
"user": {
"x-entity-ref": {
"entity": "User",
"pick": ["id", "name", "email"]
}
}
}
Supported forms:
"x-entity-ref": "User""x-entity-ref": { "entity": "User", "pick": ["id", "name"] }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
# Build TypeScript backend
npm run build
# Build React frontend
npm run build:view
# Build both (recommended)
npm run build:all
# Start TypeScript development server
npm run dev
# Watch mode for frontend development
npm run dev:view
src/llm/config.ts and src/llm/client.tssrc/tools/ and register in src/agents/core/agent.tssrc/view/frontend/components/src/view/routes/ or src/mocks/router.tsFor maintainers, to publish a new version to npm registry:
# 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:
dist/loom)Package configuration:
prepack script ensures fresh build before packaging.npmignore excludes source files and development artifacts<name>.mock.json storage for hand-written mock responses (one active override per endpoint)/mock/<path> return real HTTP 400)request schema (path params, query, headers, body all filled with samples)@cname, @integer(1,100), 'list|1-5': [...] etc.) — templates are stored as-is and expanded on each requestsetNotFoundHandler error when starting the Web Viewer (loom view) or combined server (loom serve)@stoplight/json-schema-viewer dependency (incompatible with React 19)Contributions are welcome! Please follow these steps:
git checkout -b feature/amazing-featuregit commit -m 'Add amazing feature'git push origin feature/amazing-featureThis project is licensed under the ISC License - see the LICENSE file for details.
FAQs
AI-powered JSON Schema document generator with TUI, web viewer and mock server
We found that @vegamo/loom demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
/Application Security
A practical guide to securing GitHub Actions against supply chain attacks, covering malicious pull requests, credential theft, dependency risks, and release pipelines.
Security News
Composer 2.11 adds dependency cooldowns, joining package managers that delay new releases to reduce supply chain risks while allowing urgent security updates.
Threat Research
/Security News
Cursor removed a malicious Claude Code 2.1.313 extension from its marketplace. Socket examines registry records and the initial claims about its distribution.