learn-rat-stack

Files (1)

• SKILL.md

SKILL.md (first lines)

# Learn the stack

Start with `inspectFile`, a [capability](/systems/capabilities): one named action with a contract and a server-side handler. The [contract](/systems/capabilities) defines its name, input, output, failure, and metadata. The handler implements the action.

A service is a named interface for one job. A machine defines states and the events that permit movement between them. A [projection](/lore/one-capability-every-surface) builds a callable interface from capabilities.

Follow these parts, then try the hosted content tools.

Read [Effect basics](/lore/effect-basics) before this trace if the computation model is new. For implementation tasks, use [services](/lore/services-capture-dependencies), [Layer composition](/lore/layers-make-dependencies-explicit), and [testing](/lore/tests-that-earn-their-place).

## The pieces

- Effect describes work with typed failures and required dependencies.
- Schema defines accepted values and their runtime checks.
- A Layer builds services and supplies their construction dependencies.
- XState owns finite lifecycles. The Effect bridge runs their declared actors.
- TypeScript 7 and Effect diagnostics check types and Effect usage.
- Oxlint, Oxfmt, Vitest, and lefthook enforce [the fence](/lore/the-fence): checks and hooks that reject prohibited code and shortcuts.
- pnpm and Turborepo connect packages and cache checks.
- Alchemy declares the cloud. Follow [learn Alchemy](/skills/learn-alchemy) for the deployment graph.

## One action, five interfaces

```text
                     ┌─ CLI
                     ├─ HTTP
One Capability ──────┼─ MCP
                     ├─ code mode
                     └─ RPC
```

A [projection](/lore/one-capability-every-surface) exposes the same action through another interface. RPC serves browser clients. [Code mode](/lore/one-program-can-replace-several-tool-calls) lets agents compose calls in one program.

All five interfaces use one handler.

## Trace one action

The CLI uses `inspectFile`. The hosted site uses a separate content registry.

### 1. Define the contract

The [contract](/systems/capabilities) names the action and its input, output, and failure schemas.

```ts repo=rat-stack path=packages/core/src/contracts.ts at=b4d6b8f499e57bc76914ad70df3a0c99751ae28c lines=255-263 {255,258-263}

```

`FileStatsError` belongs to the interface. The annotations mark a repeatable, read-only action.

### 2. Bind one handler

`implement` binds the contract to `runInspectMachine`. The registry includes the resulting [capability](/systems/capabilities).

```ts repo=rat-stack path=packages/core/src/inspect-file.ts at=b4d6b8f499e57bc76914ad70df3a0c99751ae28c lines=10-22 {10-12,14-15}

```

The handler starts a machine to read the file.

### 3. Put file work in a service

`FileInspector.make` captures the file system. Its `inspect` method reads bytes and maps file errors to `FileStatsError`.

```ts repo=rat-stack path=packages/core/src/file-inspector.ts at=b4d6b8f499e57bc76914ad70df3a0c99751ae28c lines=14-29 {15,20-24,28}

```

The service exposes its [Layer](/lore/layer-constructor-pattern) beside the implementation. This follows [hexagonal architecture](/lore/hexagonal-architecture): composition supplies the file-system dependency.

```ts repo=rat-stack path=packages/core/src/file-inspector.ts at=b4d6b8f499e57bc76914ad70df3a0c99751ae28c lines=31-35 {34}

```

Callers ask the service to inspect a path. Composition chooses the file-system implementation.

### 4. Give the lifecycle named states

A declared `createEffectLogic` actor calls `FileInspector`.

```ts repo=rat-stack path=packages/core/src/inspect-machine.ts at=b4d6b8f499e57bc76914ad70df3a0c99751ae28c lines=26-30 {26,28}

```

The machine starts in `reading`. It finishes in `inspected` or `unreadable`.

```ts repo=rat-stack path=packages/core/src/inspect-machine.ts at=b4d6b8f499e57bc76914ad70df3a0c99751ae28c lines=40-64 {40,43,51,57,59,62}

```

### 5. Project the registered actions

The command-line interface (CLI) projects capability lists for each server interface. HTTP uses stateless learning capabilities. MCP and code mode use their local learning counterparts. All three include `inspectFile`.

```ts repo=rat-stack path=apps/cli/src/surfaces.ts at=b4d6b8f499e57bc76914ad70df3a0c99751ae28c lines=25-33,40-51 {25-28,30-33,40,42,44,48}

```

The RPC [projection](/lore/one-capability-every-surface) derives contracts from its supplied capabilities.

```ts repo=rat-stack path=packages/capability/src/to-rpc.ts at=b4d6b8f499e57bc76914ad70df3a0c99751ae28c lines=24-27 {24,27}

```

A projection takes a registry and reuses its domain handlers.

### 6. Connect the CLI

`toCommand` derives each command. `inspectFile` also gets the `stats` alias.

```ts repo=rat-stack path=apps/cli/src/command.ts at=b4d6b8f499e57bc76914ad70df3a0c99751ae28c lines=22-35 {25-28}

```

The entry point supplies the service [Layer](/lore/layer-constructor-pattern) and Node services. It denies [approval](/systems/capabilities) by default.

```ts repo=rat-stack path=apps/cli/src/cli.ts at=b4d6b8f499e57bc76914ad70df3a0c99751ae28c lines=22-32 {24,30}

```

From joelhooks/potion-calendar, MIT.

More from joelhooks/potion-calendar