npm package: @sakaax/loom
Description: Weave your stack. The first framework built for the agent era.
Latest version: 0.1.0

# Loom

> **Weave your stack.**  
> The first full-stack framework built for the agent era.

---

Loom is a Bun-first framework designed from scratch so that **AI agents and humans can build together without friction**.

No interactive prompts that block your agent. No cryptic errors. No implicit conventions to guess.  
MCP-native from day one.

---

## Why Loom

Every framework today was designed for humans typing code slowly. In 2026, agents write most of the code — but the tooling hasn't caught up:

- `create-next-app` crashes if the folder exists
- Interactive prompts block CLI agents
- Errors are cryptic and unstructured
- Conventions are implicit — the AI has to guess
- Integrating external services (Stripe, DB...) means 10 libs, 10 configs
- No framework has a native MCP client

**Loom fixes all of this.**

---

## Quick start

```bash
bun create @sakaax/loom my-app
cd my-app
bun install
loom dev
```

Or with an existing folder:

```bash
# Drop an init.config.ts in your folder first
loom init
```

---

## Features

### 1. Agent-proof init

Fill `init.config.ts` before running — Loom reads it and executes without asking a single question.

```typescript
// init.config.ts
export default {
  name: "my-app",
  typescript: true,
  database: "postgres",
  auth: false,
  mcp: ["stripe", "neon"],
}
```

Works in an existing folder, empty folder, or folder with files. Never crashes.

---

### 2. Declarative routing

No file-based magic. Every route is explicit — and generated automatically by the CLI.

```bash
loom add route api/products --method POST
# → creates src/routes/api/products.ts
# → registers the route in loom.routes.ts
```

```typescript
// loom.routes.ts — always readable, always accurate
export const routes = [
  { path: "/", handler: "./src/routes/home.ts" },
  { path: "/api/products", handler: "./src/routes/api/products.ts", method: "POST" },
  { path: "/api/users/:id", handler: "./src/routes/api/users/user.ts" },
]
```

The agent always knows where to add a route. No guessing.

---

### 3. Native MCP client

Loom is an MCP client. Not for Claude — **for your code**.

```typescript
// loom.config.ts
export default defineLoom({
  port: 3000,
  mcp: {
    stripe: { command: "npx", args: ["-y", "@stripe/mcp"] },
    neon:   { command: "npx", args: ["-y", "@neondatabase/mcp-server-neon"] },
  },
})
```

```typescript
// src/routes/api/plans.ts
import { mcp } from "@sakaax/loom"

export default async function handler(req: Request): Promise<Response> {
  const result = await mcp.stripe.createProduct({
    name: "Pro Plan",
    price: 2900,
  })

  return Response.json({ id: result.id })
}
```

MCPs are initialized automatically on `loom dev`. No boilerplate.

---

### 4. Structured dual-channel logs

Every request, every error, every event:

- **Terminal** — human-readable, colored, concise
- **`.loom/logs/loom.log.json`** — structured JSON with context, cause, and fix suggestion

```json
{
  "level": "error",
  "route": "/api/plans",
  "message": "MCP call failed",
  "cause": "stripe-mcp: invalid price format",
  "suggestion": "Price must be in cents (integer). Got: 29.00",
  "timestamp": "2026-03-10T14:23:00Z"
}
```

The agent reads the file, understands, fixes. Zero friction.

---

### 5. One-command deploy

```bash
loom deploy
```

Via MCP (Cloudflare Workers or Vercel). No YAML, no config.

```typescript
// loom.config.ts — add your deploy target
mcp: {
  vercel: { command: "npx", args: ["-y", "vercel-mcp"] },
}
```

---

## CLI reference

| Command | Description |
|---------|-------------|
| `loom init [name]` | Initialize a new project |
| `loom dev` | Start the development server |
| `loom add route <path> [--method]` | Create a route and register it |
| `loom build` | Build for production |
| `loom deploy` | Deploy via MCP |

---

## Project structure

```
my-app/
├── src/
│   └── routes/
│       ├── home.ts
│       └── api/
│           └── health.ts
├── loom.config.ts      ← framework config + MCP registry
├── loom.routes.ts      ← route manifest (auto-updated by CLI)
├── init.config.ts      ← init config (read once, safe to delete)
├── .env.example
└── .loom/
    └── logs/
        └── loom.log.json
```

---

## Principles

1. **Explicit > Implicit** — Zero hidden magic. Everything is declared, readable, traceable.
2. **Agent-proof** — Never a blocking interactive prompt. Always a config file.
3. **MCP-native** — The framework is an MCP client. Your routes call any MCP service directly.
4. **Logs for both** — Terminal for the human, structured JSON for the agent.
5. **Bun-first** — No Node, no webpack. Bun everywhere.

---

## Roadmap

| Phase | Content |
|-------|---------|
| **MVP** ✅ | Init + Routing + MCP Registry + Logs + Deploy |
| **v0.2** | Auth first-class + Schema-first |
| **v0.3** | Real-time sync (Convex alternative) |
| **v1.0** | Hot context (`loom explain`) + Multi-agent safe + Dev profile |

---

## Stack

- **Runtime**: Bun
- **Language**: TypeScript strict
- **Server**: Bun.serve (native)
- **MCP client**: `@modelcontextprotocol/sdk`
- **Logs**: Custom (zero deps)

---

## License

MIT