Skip to content

Commit b933bec

Browse files
antfuantfu
committed
docs: update AGENTS.md
1 parent 90f8675 commit b933bec

2 files changed

Lines changed: 144 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# AGENTS GUIDE
2+
3+
## Positioning
4+
5+
**`devframe`** is the framework-neutral container for one devtool integration, portable across viewers. Build a single tool (its RPC, its SPA, its diagnostics, its CLI/build/spa/embedded outputs) without caring how it'll be displayed. A devframe app runs standalone (CLI, static deploy, embedded SPA) just as well as it mounts inside a hub.
6+
7+
## Stack & Structure
8+
9+
ESM TypeScript library. Bundled with `tsdown`. Tested with `vitest`. pnpm workspaces with catalog dependencies (`pnpm-workspace.yaml`); workspace globs reserve `playground`, `docs`, `packages/*`, `examples/*` for future additions.
10+
11+
Source layout:
12+
- `src/` — library code; entry `src/index.ts`
13+
- `test/` — vitest specs; API snapshots via `tsnapi` under `test/__snapshots__/`
14+
- `dist/` — `tsdown` build output (committed to npm tarball via `files`)
15+
16+
## Development
17+
18+
```sh
19+
pnpm install # requires pnpm@10.x
20+
pnpm build # tsdown
21+
pnpm dev # tsdown --watch
22+
pnpm test # pnpm build && vitest (api snapshot guards against stale dist)
23+
pnpm typecheck # tsc --noEmit
24+
pnpm lint --fix # ESLint via @antfu/eslint-config
25+
pnpm start # tsx src/index.ts
26+
```
27+
28+
The `pnpm test` script intentionally runs `build` first so `tsnapi` snapshots compare against fresh `dist/`. `tsdown-stale-guard` enforces this in `test/api-snapshot.test.ts`.
29+
30+
## Conventions
31+
32+
- RPC functions must use `defineRpcFunction`; always namespace IDs (`my-plugin:fn-name`).
33+
- Shared state via `utils/shared-state`; keep values serializable.
34+
- Dependencies go through the pnpm catalogs in `pnpm-workspace.yaml` (`cli`, `inlined`, `testing`, `types`) — add to a catalog and reference as `catalog:<name>`, don't pin versions in `package.json`.
35+
36+
### Devframe design principles
37+
38+
These reinforce devframe's positioning as "the container for one devtool integration, portable to multiple viewers". When in doubt, err on the side of "devframe provides primitives, the hub provides UX".
39+
40+
- **Single-integration scope.** Devframe describes one tool. If a feature only makes sense when multiple tools share a UI — docking, a unified command palette, cross-tool toasts, terminal aggregation — it belongs in a hub package, not here.
41+
- **Headless by default.** No default startup banners, no opinionated logging to stdout, no default styling. Provide hooks (`onReady`, `cli.configure`, etc.); let the application print its own branding. Structured diagnostics via `logs-sdk` are fine — ad-hoc `console.log`s baked into adapters are not.
42+
- **Mount path depends on adapter context.** Given `id: 'foo'`, the default mount path is `/__foo/` for *hosted* adapters (`vite`, `embedded`) and `/` for *standalone* adapters (`cli`, `spa`, `build`). Authors override via `DevframeDefinition.basePath`. Don't hardcode mount paths in adapter code paths that may run standalone.
43+
- **SPAs own their basePath at runtime.** Build SPAs with relative asset paths (`vite.base: './'`); discover the effective base in the browser from the executing script's location / `document.baseURI`. `createBuild` / `createSpa` copy SPA output verbatim — no HTML rewriting, no build-time `--base` injection. The client (`connectDevframe`) resolves `.connection.json` relative to the runtime base automatically.
44+
- **CLI flags compose from both sides.** The `cac` instance backing `createCli` is exposed both to the `DevframeDefinition` (`cli.configure(cli)`) — for capabilities contributed by the tool itself — and to the `createCli` caller — for flags added at the final assembly stage. Parsed flag values are forwarded to `setup(ctx, { flags })`. Never hardcode domain-specific flags into `createCli`.
45+
46+
## Structured Diagnostics (Error Codes)
47+
48+
All node-side warnings and errors use structured diagnostics via [`logs-sdk`](https://github.com/vercel-labs/logs-sdk). Never use raw `console.warn`, `console.error`, or `throw new Error` with ad-hoc messages in node-side code — always define a coded diagnostic.
49+
50+
Prefix: **`DF`**. Codes are sequential 4-digit numbers (e.g. `DF0033`). Check the existing diagnostics file to find the next available number.
51+
52+
### Adding a new error
53+
54+
1. **Define the code** in the appropriate `diagnostics.ts`:
55+
<!-- eslint-skip -->
56+
```ts
57+
DF0033: {
58+
message: (p: { name: string }) => `Something went wrong with "${p.name}"`,
59+
hint: 'Optional hint for the user.',
60+
level: 'warn', // defaults to 'error' if omitted
61+
},
62+
```
63+
64+
2. **Use the logger** at the call site:
65+
```ts
66+
import { logger } from './diagnostics'
67+
68+
// For thrown errors — always prefix with `throw` for TypeScript control flow:
69+
throw logger.DF0033({ name }).throw()
70+
71+
// For logged warnings/errors (not thrown):
72+
logger.DF0033({ name }).log() // uses definition level
73+
logger.DF0033({ name }).warn() // override to warn
74+
logger.DF0033({ name }, { cause: error }).log() // attach cause
75+
```
76+
77+
3. **Create a docs page** at `docs/errors/DF0033.md` (when `docs/` lands):
78+
```md
79+
---
80+
outline: deep
81+
---
82+
# DF0033: Short Title
83+
84+
## Message
85+
> Something went wrong with "`{name}`"
86+
87+
## Cause
88+
When and why this occurs.
89+
90+
## Example
91+
Code that triggers it.
92+
93+
## Fix
94+
How to resolve it.
95+
96+
## Source
97+
- [`src/node/filename.ts`](...) — `functionName()` throws this when …
98+
```
99+
100+
The `## Source` section lists each call site that emits the code, with a one-line role per entry. Don't list the `diagnostics.ts` definition — it's implied.
101+
102+
### Scope
103+
104+
- **Node-side only.**
105+
- **Client-side excluded**: browser-only code keeps using `console.*` / `throw`.
106+
107+
## Before PRs
108+
109+
```sh
110+
pnpm lint && pnpm test && pnpm typecheck && pnpm build
111+
```
112+
113+
Follow conventional commits (`feat:`, `fix:`, etc.).
114+
115+
## Documentation style
116+
117+
These rules apply to every Markdown file under `docs/` once it exists (error reference pages are template-driven and exempt). Apply them on every doc edit, not just dedicated revision passes.
118+
119+
### 1. Positive framing
120+
121+
Describe what *is*, not what *isn't*. Replace constructions like "X is for Y, not Z" or "there is no X for Y" with the closest natural positive phrasing. Don't document features that don't exist yet — release notes are the place for "now supported" announcements; docs describe what works today.
122+
123+
- ❌ "Build mode only; dev mode is not supported yet."
124+
- ✅ "Analyses production builds in Vite 8+."
125+
126+
### 2. Use callouts sparingly
127+
128+
Callouts (`> [!NOTE]`, `> [!TIP]`, `> [!INFO]`, `::: tip`, etc.) interrupt the reading flow and should earn their visual weight. Default to prose; reach for a callout only for genuinely critical material.
129+
130+
- **`[!WARNING]` / `[!DANGER]`** — security hazards, footguns, breaking-change pitfalls, experimental-API stability warnings. Keep these.
131+
- **Bad-practice "✗" inline blocks** — fine inside code samples to contrast with a `✓` good example.
132+
- **Everything else** — fold into the surrounding prose.
133+
134+
### 3. Concise and precise
135+
136+
Trim filler intros, redundant cross-links (one link per page is enough — sidebars handle navigation), and code samples that demonstrate more than the point being made. Lead each page with one sentence that says what the reader can build with this. Strip out promises about future work, marketing language ("powerful", "seamless"), and exposition that the surrounding code already conveys.
137+
138+
### What goes where
139+
140+
- Critical security / data-loss hazard → `[!WARNING]` callout.
141+
- Experimental API / stability caveat → `[!WARNING]` callout at the top of the page.
142+
- Bad-practice contrast → inline `// ✗ Bad` / `// ✓ Good` comments inside code blocks.
143+
- Anything else worth saying → prose.

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

0 commit comments

Comments
 (0)