Index of every page on this site: llms.txt
All skills
bluesky-social avatar

/lexification-server

@d9cdc54
by bluesky-socialbluesky-social/atproto9.7k stars
941
Run it yourself

Migrate a service package off the legacy server stack — `lex gen-server` codegen, a committed `src/lexicon/` tree, `server.<ns>.<method>()` route chains, `@atproto/api` inside service code — onto `@atproto/lex` and `@atproto/xrpc-server`. Use when asked to lexify, modernize, or migrate a server package; when a route file imports `Server` or `createServer` from `../lexicon/index.js`; when replacing `ids.*` constants, generated `isX()` guards, `server.xrpc.router`, or `QueryParams`/`OutputSchema` type imports; and when a package still runs `lex gen-server` in its `codegen:lex` script. For the calls a service makes *out* to other services, use lexification-client. For writing new routes on an already-migrated package, use xrpc-server.

  • 4 files
  • 25.4 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/bluesky-social/atproto/lexification-server

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈192 tokens for metadata: the name and description. ≈2.3k when used: this file. ≈4k more on demand in 3 files.

Description uses 9.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈763 characters, or 9.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Lexification: migrating a service package

Moves a package from @atproto/lex-cli's lex gen-server output to @atproto/lex schemas plus @atproto/xrpc-server routing.

Every service in this repo — packages/pds, packages/bsky, packages/ozone — is already migrated, so this skill now applies to packages outside the repo, or to a stray route chain left behind. Read the migrated services before inventing a pattern.

Which skill applies

Situation Skill
Package has src/lexicon/ (singular) and route chains this skill
Adding a route to a package already on server.add() xrpc-server
The same package's outbound AtpAgent / agent.api.… calls lexification-client

A service migration almost always needs this skill and lexification-client: one package both serves routes and calls other services. Do the server half first — it forces src/lexicons/ into existence, which the client half then imports from.

Guiding principles

  • Type-level changes over runtime changes. Working runtime logic stays; what changes is where types and constants come from. A migration diff that alters behavior is a bug in the migration.
  • Migrate one namespace of route files at a time, building in between. A route file is self-contained, so a broken one doesn't block the rest.
  • Leave test call sites on AtpAgent. Tests double as the regression check that the migration didn't change behavior — swapping the client they use destroys that signal. Tests that import types or constants from the deleted src/lexicon/ do have to move (details below).

Order of work

  1. Project config — swap codegen, deps, gitignore, delete src/lexicon/. → references/project-config.md
  2. Server bootstrap — createServer, Server type, Express mount.
  3. Route files — server.<ns>.<method>(…) → server.add(schema, …). → references/routes.md
  4. Constants and guards — ids.*, isX(), token exports, $build. → references/types-and-guards.md
  5. Outbound calls — lexification-client.
  6. Branded types at function/interface/DB boundaries. → references/types-and-guards.md

Steps 1–2 are a single non-splittable commit (the package won't compile in between). Steps 3–6 are incremental.

Server bootstrap

The only structural change in the whole migration. createServer and Server stop coming from generated code:

- import { createServer } from './lexicon/index.js'
+ import { createServer } from '@atproto/xrpc-server'

- let server = createServer({
+ const server = createServer([], {
    validateResponse: config.debugMode,
    payload: { /* … */ },
  })

- app.use(server.xrpc.router)
+ app.use(server.router)

The new first argument is an array of legacy LexiconDocs for routes not backed by a generated schema; schema-based setups pass []. Option names (validateResponse, payload, catchall, rateLimits, errorParser) are unchanged — see packages/pds/src/index.ts.

In route files, Server comes from the same package:

- import { Server } from '../../../../lexicon/index.js'
+ import type { Server } from '@atproto/xrpc-server'

Import mapping

Before After
../lexicon (Server, createServer) @atproto/xrpc-server
../lexicon/lexicons (ids) ../lexicons/index.js → .$type / .$lxm
../lexicon/types/… (record & def types) ../lexicons/index.js → .Main, .ViewRecord, …
../lexicon/types/… (QueryParams, OutputSchema) ../lexicons/index.js → .$Params, .$OutputBody
../lexicon/types/… (isX, validateX) ../lexicons/index.js → .$isTypeOf, .$matches, .$safeValidate
../lexicon/util ($Typed, Un$Typed) @atproto/lex-schema
@atproto/api (AtpAgent) @atproto/lex-client (Client)
@atproto/lexicon (jsonStringToLex, stringifyLex) @atproto/lex-json (lexParse, lexStringify)
@atproto/lexicon (BlobRef) @atproto/lex-data (BlobRef)
@atproto/xrpc (HeadersMap) @atproto/xrpc-server (Headers, usually aliased)
@atproto/xrpc (XRPCError, thrown by a caller) @atproto/lex-client (XrpcError)
multiformats/cid (CID) @atproto/lex-data (Cid, parseCid)

@atproto/xrpc-server keeps its own XRPCError for errors handlers throw. The casing distinguishes them: XRPCError server-side (concrete, thrown), XrpcError client-side (abstract, caught). Both can appear in one file.

@atproto/lex re-exports lex-client, lex-schema, lex-data, lex-json, and lex-cbor, but service code must not import it: it also depends on the codegen tooling of its lex bin, so packages only list it as a devDependency (see the lex-setup skill). Import from the sub-package, and depend on it.

Pitfalls

  • $type vs $lxm vs $nsid. $type is the record/object type string (app.bsky.feed.post.$type → 'app.bsky.feed.post'), used for collections and union tags. $lxm is the method id, used in auth and proxy checks. $nsid is the raw NSID, needed for defs documents that have no main. They can hold identical strings, so a wrong one type-checks and only fails at runtime.
  • $matches vs $isTypeOf. $isTypeOf only reads the $type tag; $matches validates the whole value. Substituting $isTypeOf where the data is unvalidated silently accepts malformed records. See references/types-and-guards.md.
  • encoding widening happens in either form of server.add, when the returned literal is not contextually typed: built in an intermediate variable, or returned by a handler that declares no parameters. Don't sprinkle as const everywhere — see references/routes.md.
  • Branded strings arriving from outside TypeScript's view — protobuf, Kysely rows, JSON.parse — are plain string. Cast once at the boundary (as DidString), never deep in the call graph.
  • Generated src/lexicons/ is gitignored. It won't exist until pnpm run codegen (or a build) runs. "Cannot find module '../lexicons/index.js'" means codegen hasn't run, not that the import is wrong.

Tests

Test call sites keep using AtpAgent, deliberately (see principles above). dev-env exposes both getAgent(): AtpAgent and getClient(): Client, so a new-style client is available when a test genuinely needs one.

What must move is anything a test imported from the now-deleted src/lexicon/. Two valid destinations, both already used in migrated packages:

- import { ids } from '../../src/lexicon/lexicons'
- import { isRepoRef } from '../../src/lexicon/types/com/atproto/admin/defs'
+ import { com } from '../../src/lexicons/index.js'      // generated schemas
+ import { $Typed, ComAtprotoAdminDefs, ids } from '@atproto/api'  // legacy equivalents

Prefer ../../src/lexicons/index.js for new code; @atproto/api is the lower-churn option when the surrounding test is otherwise untouched. Do not add @atproto/api back to a package's dependencies just for this — it is a devDependency in pds and only a runtime dependency in bsky because of getAgeAssuranceRegionConfig, unrelated to tests.

Before writing or restructuring tests, use the testing skill — pds and ozone are jest, bsky is vitest.

Related skills

xrpc-server documents the target route API in full and is the better reference once a package is migrated. lex-setup owns codegen wiring, lex-schema the $-accessors, and lex-data branded strings, CIDs, and blobs.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at d9cdc54. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 weeks ago
disable-model-invocation
false

README badge

README badge for bluesky-social/atproto/lexification-server