outfitter-dev/trails

Última atividade de origem registrada: 22 de outubro de 2026 às 19:27

Catálogo do SkillsMP atualizado: 5 de novembro de 2026 às 19:57

skills coletadas: 71

Estrelas no GitHub: 6
Forks no GitHub: 1

Instalar com um assistente de IA

Copie este prompt para o assistente de IA que você usa.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/outfitter-dev/trails.

README do repositório

Arquivo de origem do README: README.md

Ler o README original

Expandir README completo

# Trails **Define once. Surface everywhere.** Trails is a contract-first TypeScript framework. Define a trail — typed input, Result output, examples, intent, and an `implementation` that establishes how it runs — and the framework renders it on CLI, MCP, HTTP, or the RPC surface hosted on WebSocket. One definition, every surface, zero drift. Trails ships CLI, MCP, and HTTP surfaces today. The RPC surface (JSON-RPC 2.0, hosted on WebSocket first) is landing through `@ontrails/rpc`. ## Get started ### With an AI agent **Claude Code** — add the marketplace, then install the plugin: ```bash claude plugin marketplace add outfitter-dev/trails claude plugin install trails@trails ``` **Codex, Cursor, and others** — install the skill in the target agent profile: ```bash npx skills outfitter-dev/trails ``` That command mutates the selected local skill install. Use a disposable or profile-specific target when testing installer behavior, and prefer the repo's [plugin release runbook](./docs/releases/plugin-release.md) for operator preflight checks. The skill gives your agent the full Trails reference: lexicon, patterns, error taxonomy, surface wiring, testing, and before/after migration examples. ### With code Normal Trails 0.2 releases use the npm `latest` tag. The pinned Bun examples below target `0.2.4`. Moving an existing app from the 1.0 beta line? The [0.x migration guide](./docs/releases/migrate-to-0x.md) includes a preview-first script for manifests, catalogs, and package overrides. The 0.x line ships on `latest`; minor releases may include documented API changes. For the standalone `trails` CLI, follow the canonical [Homebrew installation guide](./docs/getting-started.md#installation). The CLI requires Bun at runtime; use `trails --version` to check the installed release. ```bash bunx @ontrails/trails@0.2.4 create --permit '{"id":"local-dev","scopes":["project:write"]}' ``` Follow the prompts — pick a name, choose a starter, select your surfaces. The scaffolder generates a working project with trails, a topo, surface wiring, and tests. The `--permit` flag is required: `create` writes a new project, and Trails write commands always name their authority explicitly instead of assuming it. Apps generated by the published `0.2.0` CLI need an explicit Node types dependency before typechecking. Follow the [0.2.0 scaffold repair](./docs/getting-started.md#repair-apps-generated-by-020). Or install manually: ```bash bun add --exact @ontrails/core@0.2.4 @ontrails/cli@0.2.4 @ontrails/commander@0.2.4 zod bun add --exact -d @ontrails/testing@0.2.4 ``` ## Before and after ### Before: an Express handler ```typescript app.get('/api/projects/:id', async (req, res) => { try { const project = await db.projects.findById(req.params.id); if (!project) { return res.status(404).json({ error: 'Project not found' }); } res.json(project); } catch (err) { console.error('Failed to fetch project:', err); res.status(500).json({ error: 'Internal server error' }); } }); ``` ### After: a trail ```typescript const show = trail('project.show', { input: z.object({ id: z.string().describe('Project ID') }), output: projectSchema, intent: 'read', examples: [ { name: 'Found', input: { id: 'p_1' }, expected: { id: 'p_1', name: 'Acme' } }, { name: 'Missing', input: { id: 'p_0' }, error: 'NotFoundError' }, ], implementation: async (input) => { const project = await db.projects.findById(input.id); if (!project) return Result.err(new NotFoundError(`Project ${input.id} not found`)); return Result.ok(project); }, }); ``` Same behavior, now captured as a runnable trail contract. The framework derives: - **CLI**: `myapp project show --id p_1` with `--help` text, exit code 2 for not-found - **MCP**: tool `myapp_project_show` with JSON Schema input, `readOnlyHint` annotation - **Tests**: both examples run as assertions — `testAll(graph)` validates the happy path and the error path - **Governance**: warden checks for throws, surface-specific imports in trail code, missing output schemas You authored the contract and implementation. The framework did the rest. ## What compounds Each declaration you add to a trail unlocks derived behavior across every surface: | You add | You get for free | |---------|-----------------| | `input` (Zod schema) | CLI flags + `--help` text, MCP JSON Schema, input validation | | `output` (Zod schema) | Contract tests, MCP response typing, TopoGraph surface entries | | `intent: 'read'` | MCP `readOnlyHint`, CLI skips confirmation, HTTP GET | | `intent: 'destroy'` | MCP `destructiveHint`, CLI auto-adds `--dry-run`, HTTP DELETE | | `examples` | Tests (happy + error path), agent guidance, documentation | | `composes` | Composition graph, cycle detection, compose coverage in tests | | `resources: [db]` | Singleton lifecycle, test mock auto-resolution, warden governance | | `detours` | Recovery paths, detour contract validation, shadowing checks | The value isn't any single feature. It's that they multiply — each declaration makes every surface smarter without additional wiring. ## How it works ```typescript import { trail, topo, Result } from '@ontrails/core'; import { surface as cliSurface } from '@ontrails/commander'; import { surface as mcpSurface } from '@ontrails/mcp'; import { z } from 'zod'; // 1. Define trails const greet = trail('greet', { input: z.object({ name: z.string().describe('Who to greet') }), output: z.object({ message: z.string() }), intent: 'read', implementation: (input) => Result.ok({ message: `Hello, ${input.name}!` }), }); // 2. Collect into topo const graph = topo('myapp', { greet }); // 3. Open surfaces with any adapter await cliSurface(graph); // CLI // await mcpSurface(graph); // MCP — same runnable trails ``` The same topo can be opened on HTTP today with `@ontrails/hono` or Bun-native `@ontrails/http/bun`. The RPC surface, hosted on WebSocket, follows the same peer-surface model through `@ontrails/rpc`. ```bash $ myapp greet --name World { "message": "Hello, World!" } ``` ## Packages | Package | What it does | |---------|-------------| | [`@ontrails/core`](./packages/core) | Result, errors, trail/signal/entity/topo, validation, schema derivation | | [`@ontrails/cli`](./packages/cli) | CLI command model - flag derivation, output formatting | | [`@ontrails/commander`](./adapters/commander) | Commander adapter for the CLI surface | | [`@ontrails/mcp`](./packages/mcp) | MCP surface — tool generation, annotations, progress bridge | | [`@ontrails/rpc`](./packages/rpc) | JSON-RPC 2.0 surface kernel — derived method table, `trails.*` methods, serializable connection state | | [`@ontrails/http`](./packages/http) | HTTP surface model — route derivation, Web Fetch kernel, Bun-native subpath | | [`@ontrails/hono`](./adapters/hono) | Hono adapter that opens a topo on the HTTP surface using the shared kernel | | [`@ontrails/vite`](./adapters/vite) | Vite adapter for opening Trails surfaces inside Vite projects | | [`@ontrails/config`](./packages/config) | Config resolution, profiles, resource config schemas, diagnostics | | [`@ontrails/permits`](./packages/permits) | Auth layer, permit model, JWT adapter, scope enforcement | | [`@ontrails/store`](./packages/store) | Backend-agnostic store definitions, typed accessors, adapter-support helpers | | [`@ontrails/kv`](./packages/kv) | Provider-neutral key-value resources, isolated memory mocks, and binding conformance | | [`@ontrails/blob`](./packages/blob) | Provider-neutral blob resources, byte/stream bodies, and binding conformance | | [`@ontrails/queue`](./packages/queue) | Provider-neutral queue producers, recorder mocks, and binding conformance | | [`@ontrails/drizzle`](./adapters/drizzle) | Drizzle SQLite adapter, typed store bindings, read-only bindings | | [`@ontrails/cloudflare`](./adapters/cloudflare) | Portable role bindings, native resource escape hatches and Workers hosting; D1 store bindings with reviewed schema SQL | | [`@ontrails/testing`](./packages/testing) | `testAll()`, `testTrail()`, `testComposes()`, contract testing, surface harnesses | | [`@ontrails/topography`](./packages/topography) | TopoGraphs, semantic diffing, durable artifact helpers, lock manifests, topo-store persistence, Wayfind graph-read query APIs | | [`@ontrails/source`](./packages/source) | Shared source-code AST parsing, walking, locations, edits, literals, and Trails syntax helpers | | [`@ontrails/observability`](./packages/observability) | Log and trace sink contracts, sink composition, built-in sinks, trace rendering | | [`@ontrails/observability`](./packages/observability) | Log and trace sinks, `/dev` query/status and `trails.db` state, sampling helpers, `/otel` export | | [`@ontrails/logtape`](./adapters/logtape) | LogTape adapter with real library integration and category-aware record forwarding | | [`@ontrails/pino`](./adapters/pino) | Pino adapter with real library integration and flush support | | [`@ontrails/warden`](./packages/warden) | AST-based convention rules, drift detection, CI formatters | ## Documentation See **[docs/index.md](./docs/index.md)** for the full guide, organized by what you're trying to do. ## Development ```bash bun run build # Build all packages bun run test # Run all tests bun run lint # Lint with oxlint bun run typecheck # TypeScript strict mode ``` ## Status Pre-1.0 API development. The first normal release was `0.2.0`; normal releases use the npm `latest` tag. The contract layer, CLI/MCP/HTTP surfaces, `trails topo` and `trails dev` workflows, shared `trails.db`, tracing-backed developer state, schema-derived stores, and the Drizzle runtime are implemented. The RPC surface, hosted on WebSocket, is landing through `@ontrails/rpc`. See [Horizons](./docs/horizons.md) for what's next.

Carregando o README do repositório…

Skills neste repositório

Desenvolvedores de software Analistas de garantia de qualidade de software e testadores Analistas de sistemas de computador

3 categorias ocupacionais · 15% classificado

skill

ocupação

descrição

atualizado

trails

sem classificação

Build with the Trails framework — define trail contracts, open CLI/MCP surfaces, test with examples, debug errors, migrate codebases, run governance. Use when creating trails, adding surfaces, testing, debugging Trails errors, migrating to Trails, running…