effected-packages
/effected-packages
The @effected package index — what each of the kit's 55 packages contains and when to reach for it. Use when working in a repo that uses @effected/* packages and about to add a capability the kit may already ship — parsing/editing JSONC/YAML/TOML/Markdown, offset to line/character (LSP position) conversion, semver, SPDX, glob matching, an in-memory filesystem for tests, package.json/tsconfig/lockfile/config-file handling, monorepo/workspace introspection, git introspection, runtime-version resolution, running commands, managed sections, JSONL journals, the GitHub REST/GraphQL API and Actions r
- Author
- spencerbeggs ↗
- Repository
- effected ↗
- Licence
- MIT
- Last repository change
- 13.11.2026
Assessment and security
- Files in this package
- 111
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
The @effected package index — what each of the kit's 55 packages contains and when to reach for it. Use when working in a repo that uses @effected/* packages and about to add a capability the kit may already ship — parsing/editing JSONC/YAML/TOML/Markdown, offset to line/character (LSP position) conversion, semver, SPDX, glob matching, an in-memory filesystem for tests, package.json/tsconfig/lockfile/config-file handling, monorepo/workspace introspection, git introspection, runtime-version resolution, running commands, managed sections, JSONL journals, the GitHub REST/GraphQL API and Actions r
Original author description
The @effected package index — what each of the kit's 55 packages contains and when to reach for it. Use when working in a repo that uses @effected/* packages and about to add a capability the kit may already ship — parsing/editing JSONC/YAML/TOML/Markdown, offset to line/character (LSP position) conversion, semver, SPDX, glob matching, an in-memory filesystem for tests, package.json/tsconfig/lockfile/config-file handling, monorepo/workspace introspection, git introspection, runtime-version resolution, running commands, managed sections, JSONL journals, the GitHub REST/GraphQL API and Actions r
How it works
- Index
- Search by intent
- Local-build dogfood state
- The two warnings every consumer inherits
- Cross-cutting facts
- Related skills
SKILL.md preview
---
name: effected-packages
description: The @effected package index — what each of the kit's 55 packages contains and when to reach for it. Use when working in a repo that uses @effected/* packages and about to add a capability the kit may already ship — parsing/editing JSONC/YAML/TOML/Markdown, offset to line/character (LSP position) conversion, semver, SPDX, glob matching, an in-memory filesystem for tests, package.json/tsconfig/lockfile/config-file handling, monorepo/workspace introspection, git introspection, runtime-version resolution, running commands, managed sections, JSONL journals, the GitHub REST/GraphQL API and Actions runtime, CLI output, prompts and failure reporting, cross-front-end primitives for a CLI or MCP boundary, serving or testing an MCP server over stdio, SBOM generation and signing, or publishing SchemaStore JSON Schema or schema.org JSON-LD. Also use when choosing dependencies for a new Effect v4 app or library. Rows route; per-package depth lives in references/; per-construct intent search lives in references/constructs/.
when_to_use: >-
reading image dimensions or MIME type from bytes, caching generated images such as Open Graph cards, signing or verifying a JWT or an OIDC token (JWKS) on Node or Cloudflare Workers, HMAC sign/verify, AWS SigV4 request signing, constant-time compare of secrets or MACs, webhook signature verification (Stripe, GitHub, Svix/Standard Webhooks, Sanity, Linear), the OIDC issuer contract or `IdentityToken`, verifying an OIDC ID token, verifying a GitHub Actions OIDC token, caching a GitHub App installation token across requests, detecting an agent or CI audience, terminal colour level or hyperlinks, neutralizing GitHub Actions workflow commands in log text, interactive prompts, TUI screens, wizards or pickers (Ink) in a CLI, upward path walking, XDG directories, SQLite state/caching, unsatisfied peer-dependency detection, discovering CLI tools, parsing GitHub issue references (Closes #12) out of a commit message or PR body, framing, launching, driving or boot-proving an LSP server over stdio, a crash guard for a stdio server process, parsing a shell command string an agent emitted without executing it, finding every command in a Bash tool call for a guard or hook, S3/R2 object put/get/list from a Worker or Node, a conditional first-write-wins object put, writing a markdownlint custom rule over an mdast tree, defining a markdown lint rule once for both a programmatic linter and markdownlint, when a task names an @effected package
targets:
copilot:
description: >-
The @effected package index — what each kit package contains and when to reach for it. Use when working in a
repo that uses @effected/* packages and about to add a capability the kit may already ship — parsing/editing
JSONC/YAML/TOML/Markdown, semver, SPDX, glob matching, an in-memory filesystem, package.json/tsconfig/config
files, workspace and git introspection, running commands, JSONL journals, the GitHub API and Actions runtime,
CLI output, prompts and TUIs (Ink), MCP servers, JWT/OIDC sign/verify, HMAC, AWS SigV4, webhook signature
verification (Stripe, GitHub, Svix, Sanity), parsing a shell command string without running it, S3/R2 objects,
markdownlint custom rules over kit trees, SBOM signing, or SchemaStore and schema.org publishing. Per-package
depth and construct search live in references/.
---
# The @effected package index
`@effected/*` is an Effect v4-first app kit: 55 packages (50 libraries, the
`pnpm-plugin-effected` companion, and the four packages of
the `effected` tool) designed against the
v4 line, released together, with every
`effect` dependency drawn from one pnpm catalog range held to one Effect minor (a tilde range, `lock-minor`). Before
designing lockfile/config/glob/semver/path/state/workspace/git capability by
hand, check this table — the kit probably ships it, schema-first and with a
typed error channel.
**Tier vocabulary** (what depending on a package costs you): **pure** — peers
on `effect` only, no IO; **boundary** — does IO through core service contracts
(`FileSystem`, `Path`, `HttpClient`, `ChildProcessSpawner`) required in `R`,
so you provide one platform layer at the edge; **integrated** — carries a real
backend/runtime dependency that propagates to consumers. **Companion** and **tool** packages carry no tier: a companion fronts one library, a tool package belongs to the `effected` tool (an application, not a library). Check core first
(`effect-v4-module-index`), then the kit — never re-implement either.
**Core's `effect/crypto` replaces `node:crypto`:** `createHash` goes to `Digest`, HMAC to `Mac`, signing to `Signature`, random bytes and UUIDs to `SecureRandom`; the kit's `@effected/crypto` builds on them.
## Index
Load a package's reference when you are about to import from it, design
against its services, or test code that uses it.
| Package | What it contains | Reach for it when | Tier | Reference |
| --- | --- | --- | --- | --- |
| `@effected/semver` | SemVer versions/ranges/comparators as Schema classes, range algebra, `VersionCache` service | any version parse/compare/range logic that crosses a kit API or needs range algebra, positional errors or `Result` twins; core `effect/SemVer` and `effect/SemVerRange` cover a plain compare, bump or match | pure | [semver.md](./references/semver.md) |
| `@effected/jsonc` | JSONC parse/edit/format schemas, AST, comment-preserving edits, visitor stream | reading or editing JSON-with-comments (tsconfig, VS Code-style config) | pure | [jsonc.md](./references/jsonc.md) |
| `@effected/yaml` | YAML 1.2 parse/edit/format schemas, error-tolerant AST, edits, visitor | any YAML read/write/transform | pure | [yaml.md](./references/yaml.md) |
| `@effected/toml` | TOML parse/edit/format schemas, lossless CST, date-time value classes; parses 1.1.0, emits 1.0.0 spellings | any TOML read/write/transform | pure | [toml.md](./references/toml.md) |
| `@effected/markdown` | CommonMark 0.31.2 + GFM parse/edit/format as pure schemas: 28 constructible mdast-shaped node classes with UTF-16 code-unit offsets, offset-splice edits, node-level modify, `Mdast` projection both ways, visitor (`walk`, a sync `Iterable`, and `visit`, the `Stream` over it), frontmatter codecs, section finders (`firstSection` / `sectionByHeading`, `find` and `frontmatter` return an `Option`), lint facts (`frontmatterFence` for an unclosed fence, `Frontmatter.valueStart` for diagnostics in file coordinates, `unresolvedFootnoteReferences` for undefined footnotes), and the parser-free `@effected/markdown/stringify` entry | reading, editing, querying or rewriting markdown — **and building it**: `new Table(...)` → `Markdown.stringify` — instead of `remark`/`mdast-util-*`/`gray-matter`; emitting markdown from a bundle that must not carry the parser; linting frontmatter fences or undefined footnotes | pure | [markdown.md](./references/markdown.md) |
| `@effected/markdown-lint` | a markdownlint-compatible rule shape over `@effected/markdown` trees: `LintRule.make` (markdownlint metadata plus a synchronous `check` over a `LintContext`, validated as markdownlint validates and throwing on a violation), `MarkdownLint.lint`/`lintDocument`/`lintEffect` (the pure programmatic host, total on input), `MarkdownlintAdapter.rule`/`rules` (the same rule as a markdownlint custom rule, with no markdownlint import), `LintDiagnostic` in markdownlint's `onError` fields, and `PositionMapping` (offsets to lines, columns, ranges and one-line `fixInfo`) | writing a markdownlint custom rule over an mdast tree instead of micromark tokens, or defining a markdown lint rule once so a programmatic linter and markdownlint-cli2 report the same findings on the same lines | pure | [markdown-lint.md](./references/markdown-lint.md) |
| `@effected/source` | source-text positions as plain values: `LineIndex` (built once over a text; offset to zero-based `{ line, character }` in UTF-16 code units and back, line count, line start/end/text, `spanOf`/`rangeOf`/`locationOf`; LSP's `\n`/`\r\n`/`\r` line breaks by default, `"lf"` and `"unicode"` rules on request; out-of-range input clamps, a non-integer throws `RangeError`), plus the structural `SourcePosition`, `SourceRange`, `SourceSpan` (an LSP `Range`), `SourceLocation` and `SourceDiagnostic` shapes the format packages' diagnostics and ranges already satisfy; no dependency at all, not even `effect` | converting a parser offset to an LSP or editor position (or back), counting lines, or writing one consumer over any kit format package's diagnostics — instead of hand-rolling a `lineCharacter` loop | pure | [source.md](./references/source.md) |
| `@effected/spdx` | SPDX license IDs, exceptions and license *expressions* as Schema classes, with a hardened depth-capped expression parser and vendored SPDX datasets | validating or parsing a license field / expression (`MIT OR Apache-2.0 WITH …`) | pure | [spdx.md](./references/spdx.md) |
| `@effected/glob` | full minimatch dialect as pure string→predicate schemas (`GlobPattern`, `GlobSet`), with enumerator metadata (`enumerationRoots`) for a walker; beside it `Wildcard`, `*`/`?` wildcard matching with no separator semantics and no backtracking, not a glob dialect | matching path strings against globs without touching the fs, or wildcard matching an allow-list entry like `agent:*`. Core's experimental `effect/Glob` is smaller: no extglobs or leading-`!` negation (probed, `src/+(foo\|bar).ts` matches `src/foo.ts` in the kit and not in core), and the walker takes a `GlobPattern` | pure | [glob.md](./references/glob.md) |
| `@effected/memfs` | in-memory implementation of core's `FileSystem` contract: an isolated virtual POSIX volume behind the standard `FileSystem.FileSystem` key — `MemoryFileSystem.layer` (empty volume) / `layerWith(seed)` (absolute-POSIX-path → `string` \| `Uint8Array` \| tagged `file`/`directory`/`symlink` entries, parents auto-created); unseeded reads fail typed `NotFound`, never fabricate; every memory layer also publishes `Volume` for sync write read-back (resolve it under the same provide — layers re-seed per build; `makeHandle`/`makeSync` pin one volume with a stable `layer`), `layerWith(seed, { root, caseSensitive, faults, spies, watchEvents })` injects typed per-method faults delegate-by-default, `layerWithPath` adds `Path`, and `syncFileSystem`/`promisesFileSystem` serve injected `node:fs` ports; the `node-sync` subpath is a read-only sync `FileSystem` over the real disk | any test needing a filesystem — instead of hand-stubbing `FileSystem.layerNoop` (the stub answering `""` is the documented footgun it exists to kill) | pure | [memfs.md](./references/memfs.md) |
| `@effected/npm` | resolver CONTRACTS for `catalog:`/`workspace:` specifiers (shared by pnpm and bun) + shared dependency vocabulary, **plus** `NpmRegistry` (reads over `HttpClient`, `manifest` for one version's dependency, peer and engines fields), `NpmConfig` (npmrc resolution, at the workspace root on request, array settings via `list`), `NpmReleaseAge` (npm's `min-release-age`), `PackageTarball` (extract a published tarball, or read its `CHANGELOG.md` in memory), `NpmHttpClient` from `@effected/npm/node` (the Node `HttpClient` that applies an npmrc's proxy and TLS settings) and `PackagePublish` (the npm CLI over `commands`) | typing dependency specifiers; reading a registry or a version's peers; packing/publishing | boundary | [npm.md](./references/npm.md) |
| `@effected/pnpm` | everything pnpm owns alone: `PnpmSettings` (the values `pnpm config get` reports, merged from `PNPM_CONFIG_*` variables, `pnpm-workspace.yaml` and the global `config.yaml` in pnpm's precedence, typed accessors), `ReleaseAgeGate` (`minimumReleaseAge` minutes + `minimumReleaseAgeExclude`, `combine` the one clamping authority, `filterVersions`), `PnpmMatcher` (`@pnpm/matcher` list grammar for `peerDependencyRules`), `PnpmNpmConfig` (pnpm 12's registry, proxy and TLS view as an `NpmConfig`), `PnpmWorkspaceFile` (the format-preserving `pnpm-workspace.yaml` editor), `VersioningConfig`/`Epic` (the `versioning` block), `PnpmSettingsCatalog` on the `./settings` subpath (one descriptor per pnpm 12 setting), `OverrideKey` (the `overrides`/`allowedVersions` selector grammar), `PeerDependencyRules` (the `peerDependencyRules` block), `PnpmLockDocument`/`PnpmEnvDocument` (`pnpm-lock.yaml`'s lockfile and env preamble documents as written) and `PnpmExtension`; the `catalog:`/`workspace:` contracts stay in `npm` as shared with bun | reading `minimumReleaseAge` or any pnpm setting without a subprocess; dropping too-young versions before resolving; matching a `peerDependencyRules` list; reading a `pnpm-lock.yaml` as written | boundary | [pnpm.md](./references/pnpm.md) |
| `@effected/bun` | what bun owns alone: `BunLockDocument` (`bun.lock` as bun writes it, `parse` failing `@effected/npm`'s `LockfileDocumentError`) and `BunExtension` (the lockfile header `Lockfile.extension` carries); no `bunfig.toml` settings model, no `bun.lockb` reader | reading a `bun.lock` as written; for the manager-neutral model use `@effected/lockfiles`; the `catalog:`/`workspace:` contracts bun shares with pnpm are `@effected/npm`'s | pure | [bun.md](./references/bun.md) |
| `@effected/lockfiles` | bun/npm/pnpm lockfile parsers → one `Lockfile` model of package *instances* (`instanceId`, `resolved`, `unresolvedEdges`, `peerDependencies`) + pure integrity checking + `LockfileDiff.compare` (catalog and importer changes between two lockfiles); parses pnpm `lockfileVersion` 9+ and npm `lockfileVersion` 3+ only, older formats fail typed | reading any lockfile; lockfile-vs-manifest drift checks; comparing two lockfiles to report what an install or update moved | pure | [lockfiles.md](./references/lockfiles.md) |
| `@effected/package-json` | package.json schemas, `Package` model, validation, file IO service; `repository`/`bugs`/`homepage`/`maintainers`/`keywords` now typed | reading/editing/validating package.json | boundary | [package-json.md](./references/package-json.md) |
| `@effected/tsconfig-json` | tsconfig schemas, tsc-parity `extends` resolution, nearest-config discovery | loading/resolving/discovering tsconfig files | boundary | [tsconfig-json.md](./references/tsconfig-json.md) |
| `@effected/config-file` | codec × resolver × strategy config loading, 4 codecs, encryption/migration decorators, one-shot `ConfigFile.read(path, { schema, codec })` | any app/tool config-file loading | boundary | [config-file.md](./references/config-file.md) |
| `@effected/kit` | platform-free primitives shared across a tool's front ends: `Distribution`/`DistributionField`/`CurrentDistribution`/`distributionSuffix`/`withDistribution`/`withDistributionVersion` (carrier identity, and a `--version` formatter decorator), `Remediation` (what a caller should do after a failure), `ErrorText` (any value, or a `cause` chain, as error text without throwing: `describe`, `causeMessage`, `of`), `LaunchContext.projectDir`/`resolve`/`usable` (resolving an agent-launched project directory or other location from caller-supplied `argv`/`env`/`cwd` — no `process` read inside), `Exclusive` (a one-permit lane with a required timeout for work that mutates process-global state; `Exclusive.promise` waits for an interrupted promise) and `ProcessScope` (scoped `chdir` and `env` patches, restored on scope close), and `ProcessGuard` on the import-free `./guard` subpath (crash guards on a structural host, installed before a server's graph loads, for any transport) | sharing carrier-distribution identity, a remediation shape, or launch-context resolution between a CLI and an MCP server front end, serializing handlers that change the working directory or environment, or guarding an LSP or other non-MCP server process against stray crashes — pattern: `design-patterns` | pure | [kit.md](./references/kit.md) |
| `@effected/files` | `AtomicFile.write`: replace one file through a synced temp file and a rename, following a symlink and keeping permission bits by default or replacing the link itself with `{ links: "replace" }`, with `FileSystem` and `Path` in `R` and plain `PlatformError` as the error; `AtomicDirectory.write`: replace a whole directory by staging a sibling and renaming it into place | saving a user's file where a crash must not leave it truncated, replacing a symlink atomically or refusing to write through one in an untrusted checkout, or replacing a cached directory tree | boundary | [files.md](./references/files.md) |
| `@effected/images` | image facts from bytes: `ImageFacts` (format, MIME type, width, height; sync `fromBytesResult`, Effect `fromBytes`) for PNG/JPEG/GIF/WebP/AVIF with one typed `ImageParseError`, and the `./cache` generated-image cache (`ImageCacheKey.fromParams`, `ImageCache.getOrGenerate`, `ImageBackend` directory backend or any structurally matching store) | reading image dimensions or MIME type without an image library, or skipping re-rendering of a generated image such as an Open Graph card | boundary (`./cache` needs `FileSystem`, `Path`, `Digest.Digest`) | [images.md](./references/images.md) |
| `@effected/jwt` | a thin layer over core `effect/jose`, with no `node:` import and `@effected/crypto` as its only dependency: `JwtKey` importers (PKCS#8, PKCS#1 and one-line PEM, JWK, `generate`), `Jwt.sign`/`Jwt.verify` with safer defaults (60 s tolerance, `exp` required), `Jws` for the signature layer, `JwksResolver` (OIDC discovery, cached JWKS, rate-limited refetch on a new `kid`) over a KV-backable `JwksStore` seam, one `JwtError` routed on `reason`, and `TestIssuer` under `./testing`; every asymmetric algorithm core has, never HMAC, algorithm from the key | verifying an OIDC token against a discovered issuer's JWKS, signing with a PKCS#1 GitHub App key, on Node or Cloudflare Workers — instead of `jose`/`jsonwebtoken`; with a key in hand or one fixed JWKS URL, core `effect/jose` alone suffices; for GitHub's tokens reach for `@effected/github`'s `GitHubApp` and `ActionsOidc` first | boundary (signing and verifying need core `Signature`; `JwksResolver` needs `HttpClient` and `JwksStore`) | [jwt.md](./references/jwt.md) |
| `@effected/crypto` | HMAC sign/verify (`Hmac`, SHA-256/512, bytes/hex/base64/base64url), `Hash.digest` (MD5, SHA-1, SHA-256/384/512 over multi-part messages), `ConstantTime.equal` and `secretsEqual`, and `SigV4.sign` for S3-compatible stores (R2, MinIO, Spaces), with HMACs from core `Mac.Mac` and `Hash`'s, SigV4's and `Fingerprint.of`'s digests from core `Digest.Digest` (`effect/crypto`), both in `R`, failing with core's `CryptoError`; and `HttpRedaction` (credential-free copies of core `HttpClientError`, request and response values) | HMAC-signing or verifying a MAC, hashing a multi-part message to hex or base64, comparing secrets or MACs without a timing leak, or signing an S3/R2 request on Node or Cloudflare Workers — instead of `node:crypto` or an AWS SDK; keeping an `HttpClientError` as a `cause` without its `authorization` header (`HttpRedaction.cause`) | boundary (`Hmac`, `secretsEqual` and `SigV4` need `Mac.Mac`; `Hash`, `SigV4` and `Fingerprint.of` need `Digest.Digest`) | [crypto.md](./references/crypto.md) |
| `@effected/s3` | a minimal client for one bucket of an S3-compatible store (S3, R2, MinIO, Spaces): `S3Client.layer`/`make`, conditional `put` (`ifNoneMatch`, `ifMatch`), `get` (with `range`), `head`, `delete`, one-page `list` and a `listAll` `Stream`, signed with `@effected/crypto`'s `SigV4`, with no `node:` import; a strict ListObjectsV2 reader that fails a body whose root is not `ListBucketResult` rather than reading it as empty; typed `S3NotFound`, `S3NotModified`, `S3PreconditionFailed`, `S3ConditionalConflict` (a `409` race to retry), `S3RequestFailed`, `S3MalformedResponse`, `S3TransportError`, `S3InvalidRequest` with redacted causes | putting, getting or listing raw objects in S3 or R2 from a Worker or Node, or a first-write-wins conditional put — instead of an AWS SDK or a hand-rolled client over `SigV4`; for an Action's framed blobs, `BlobStore.layerS3` in `@effected/github-actions` | boundary (`S3Client.layer` and `make` need `HttpClient`, `Digest.Digest`, `Mac.Mac`; methods then need nothing) | [s3.md](./references/s3.md) |
| `@effected/webhooks` | inbound webhook signature verification as pure `verify(request)` presets over `WebhookRequest` (header lookup, raw body, `receivedAt`, `Redacted` secret): `GitHub`, `Stripe`, `StandardWebhooks` (Svix, Clerk, Resend), `Sanity`, generic `HmacHeader` and `SharedSecret` (with `attest`/`verifyAttested`, a proof to archive in place of the secret header), plus `Webhooks.checkFreshness`; one `WebhookVerificationError` routed on `reason` | verifying a Stripe, GitHub, Svix/Standard Webhooks, Sanity or Linear delivery on a Worker or Node server; attesting an archived shared-secret delivery so a replay can be re-verified | boundary (every `verify` needs `Mac.Mac`) | [webhooks.md](./references/webhooks.md) |
| `@effected/oidc` | the `IdentityToken` OIDC issuer contract (`layerStatic`, `layerTest`), `IdTokenClaims`, `Oidc.decodeUnverified` and a discovery-backed `Oidc.verify` (required non-empty audience) over `@effected/jwt` | asking for or supplying a workload identity token, or verifying an OIDC ID token against an issuer's JWKS — `sbom`, `github` and `github-actions` all take their identity types from it | boundary (`Oidc.verify` needs `JwksResolver` and core `Signature`) | [oidc.md](./references/oidc.md) |
| `@effected/changesets` | changeset files, `.changeset/config.json` and the release plan as schemas and pure functions: `ChangesetFile.parse`, `PendingChangesets.read`, `ChangesetConfig.read`, and `ReleasePlan.read` / `assemble` (snapshot plans included), `ReleasePlan.edits` (manifest versions and ranges, consumed changesets, next `pre.json`, as data) `Changelog.entry` / `insert` over a `@changesets/types`-identical `ChangelogFunctions`, pnpm-native release planning (`ReleaseManager.detect`, `Ledger`, `VersioningCheck`, `RegistryVersions.layerFrom` for first releases; a lane prerelease publishes under `latest` unless `--tag` is passed), each held to its `@changesets/*` engine as a test oracle | reading pending changesets, computing which packages a release would bump and to what, or applying a release plan and rendering changelogs, without `@changesets/*` | boundary (`ReleasePlan.read` needs `FileSystem`, `Path`, `WorkspaceDiscovery`) | [changesets.md](./references/changesets.md) |
| `@effected/bundler` | the pipeline behind `effected package build` and `effected action build`: `Bundler.build` (JS and declaration passes, emitted manifest, API Extractor meta, `bundle.json`, SEA binary, `issues.json`), `ActionBuilder.build` (validate, bundle with rolldown, load-check, persist), the `effected.toml` config schemas, a re-export of `@effected/manifest` and the build journals | embedding or testing the build pipeline; to build a package or an action, run the commands from `@effected/plugin` instead | integrated (peers `typescript`) | [bundler.md](./references/bundler.md) |
| `@effected/manifest` | the platform-neutral `bundle.json` documentation-bundle manifest as a pure schema: `BundleManifest` (spec 1) with `RegistryRef`, `OpenGraphImage`, `OpenGraphConfig`, `SbomRef` and `ProjectIdentity`, `decodeBundleManifest`/`encodeBundleManifest` failing `BundleManifestError`, `MANIFEST_SPEC`, `BUNDLE_MANIFEST_FILENAME`, `isKnownRegistryType`, and the `ManifestSource` authoring shape | reading or writing a bundle's `bundle.json` (a docs site, a bundle reader) without installing the build toolchain | pure (peers `effect` only) | [manifest.md](./references/manifest.md) |
| `@effected/jsonl` | append-only, schema-validated JSONL journals as a definable service: an event registry + envelope contract (`at`/`event`/`scope`/`data`), a pure sync core for runtime-free readers, `Slice`-filtered `query`/`changes`/`projection`, and a watcher so cooperating writers cross-observe each other's appends | an append-only journal/event log on disk, agent-state files, or watching a JSONL file another process appends to | boundary (`./node` is Node-only) | [jsonl.md](./references/jsonl.md) |
| `@effected/walker` | upward directory traversal (`ascend`, `ascendWithin`, `ascendToMarker`, `firstMatch`, `findUpward`, `findUpwardAll`, `findRoot`, with `*Sync` twins of every IO form, and `findUpwardSyncWith`, which accepts a directory by reading and validating what it finds), `PosixPath` (sync POSIX path functions that read no working directory), downward glob expansion (`descend`, `descendEntries`, and sync `descendSync`/`descendEntriesSync` over `./node-sync` ports) matching files, directories or both, with `prune` (skips `node_modules`), `boundaries` (nested-package markers) and opt-in `followSymlinks`, plus `confineRelative` (lexical) and `confineReal` (symlink-aware) path containment, and `relativeWithin` (base-relative placement of an absolute path that may not exist yet) | find-nearest-file/marker-based root discovery, finding the nearest *valid* manifest, materializing a glob against a directory tree, refusing a path that escapes a base, with or without an Effect runtime, or POSIX path arithmetic in pure code that cannot put `Path` in `R` | boundary | [walker.md](./references/walker.md) |
| `@effected/xdg` | XDG Base Directory resolution: `Xdg` (ambient, `layerFromEnv(record)`), `AppDirs` (with `segment` for a filesystem-safe name), native dirs, config resolvers | platform-correct config/data/cache/state paths, with XDG search paths and the runtime directory that core `UserDirectories` (`effect/persistence`) does not model | boundary | [xdg.md](./references/xdg.md) |
| `@effected/git` | 76 typed members in two tiers — a read tier (show/ls-tree/ls-files/refs/upstream/log/merge-base/diffs/status/tree identity/ls-remote) and a marked mutating tier (checkout/fetch, restore trio, stash, branches, tags, remotes, worktrees, commit/push/pull, submodules, config, staging) — plus a PURE `GitConfig`/`Gitmodules` document core, a pure `GitRemote` address parser with `redact` for logging, and argv/stderr redaction on every error | reading repo state at any ref without checkout, driving git as a program, parsing/editing a git-config or `.gitmodules` file losslessly, or parsing/redacting a remote URL | boundary | [git.md](./references/git.md) |
| `@effected/runtimes` | Node/Bun/Deno version resolution from live feeds with offline snapshot | resolving runtime versions against ranges/phases | boundary | [runtimes.md](./references/runtimes.md) |
| `@effected/commands` | `Run` combinators over core `ChildProcess.Command` (collect/text/lines/json/`jsonLine`/detach, typed failure, redaction, transient retry) + `ToolDiscovery` + the `LocalExec` contract `workspaces` implements (with `LocalExec.parse` to split a launcher argv back apart) + sync primitives for code with no Effect runtime: `PrebuiltBinary` (per-platform `optionalDependencies` binaries), `RunOnce` (run work once across concurrent processes) and the `ProcessLiveness` contract; Node bindings and `ModuleResolution` on `./node-sync` | running any subprocess, framing a JSON protocol payload out of a noisy child's stdout, asking whether a CLI tool is installed and which copy to use, resolving a prebuilt platform binary, or deduplicating a prebuild across processes | boundary | [commands.md](./references/commands.md) |
| `@effected/shell` | a tolerant shell-syntax lexer and segmenter: `ShellSyntax.parse` (total, synchronous, never throws, evaluates nothing) to a `ShellScript` of segments split on `&&`, `\|\|`, `;`, `\|`, `&` and newlines, with `commands()` (`ShellCommand`: name and args, unwrapping `sudo`, `env`, `command`, `exec`, `nohup`, `time`), `substitutions()` (every `$(…)`, backtick and `<(…)` body), words with typed quoting parts and a fail-closed `literal`, assignments, redirections, heredocs and diagnostics; no dependency at all | parsing a shell command string an agent emitted without executing it, or a guard that must see every command in a Bash tool call — instead of `shell-quote` or a regex; to run a command, `@effected/commands` | pure | [shell.md](./references/shell.md) |
| `@effected/templates` | managed sections: delimited BEGIN/END blocks inside user-editable files, with reconcile/sync/check and a parameterized marker + comment style | writing generated content into a file a human also edits | boundary | [templates.md](./references/templates.md) |
| `@effected/schema-org` | schema.org vocabulary as Schema classes (`SoftwareSourceCode`, `TechArticle`, `APIReference`, `Person`, `Organization`, `CreativeWork`), a `JsonLdDocument` assembler with `@id` cross-references, a script-embeddable escaped serializer, and offline conformance validation against the vendored v30.0 vocabulary behind a separate `./validate` entrypoint | emitting schema.org JSON-LD for a page, or gating structured data in CI without calling a live validator | pure | [schema-org.md](./references/schema-org.md) |
| `@effected/schemastore` | Effect Schemas published as SchemaStore-shaped Draft-07 JSON Schema documents: `SchemaPipeline` (the generate → lint → validate → gate → write loop), `StoreDocument` assembly (owning the `#/$defs` restore), versioned/unversioned catalog modes, fileMatch hygiene lint, `DocumentLint`, the declared-family annotation gate, the `SchemaValidator` contract (engine-free; the ajv engines live in `@effected/engine/schema`), `HostedSchema` for a derived `$schema`/`$id` identity, `DocumentDiff` change classification, content-comparing `SchemaFile` IO | emitting editor-consumable JSON Schema from Effect Schemas, deriving the `$schema` URL an application writes, or publishing a catalog to SchemaStore | boundary | [references/schemastore.md](references/schemastore.md) |
| `@effected/store` | migrated SQLite `Store` + TTL `Cache` with tags/eviction/events; `Store.migrateOnce` (once-per-process migration shared by concurrent callers) and `Store.fromMigratorRecord` (effect/sql `Migrator` record → migrations) | durable local state or an on-disk cache | integrated | [store.md](./references/store.md) |
| `@effected/workspaces` | monorepo discovery (manager-neutral: a yarn repo's `package.json#workspaces` still discovers), dependency graph, PM detection (npm/pnpm/bun; yarn fails `UnsupportedPackageManagerError`), catalogs (with four `ConfigDependencyHooks` replay layers — noop / in-process / subprocess / a hermetic `layerFrom` map — every replaying one loading the pnpmfile of the DECLARED config-dependency version — live/subprocess from `.pnpm-config` or the pnpm store, `layerFrom` from its map — so `at(ref)` diffs hook-only catalogs across a config-dependency bump), change detection, snapshots, versioning/tag strategies, `PeerCheck` unsatisfied-peer detection over a parsed lockfile; implements `npm`'s resolvers and `commands`' `LocalExec`, plus `@effected/workspaces/testing` (`WorkspaceLayering`, `PackedInstall`, `SourceBoundary`) | any monorepo/workspace introspection, or asking whether a workspace's peer graph is satisfied (npm/pnpm/bun), or checking a monorepo's layering, packed install or source boundaries in its own tests | boundary | [workspaces.md](./references/workspaces.md) |
| `@effected/github` | typed GitHub REST + GraphQL over octokit's core `request` (GraphQL as `POST /graphql` with a `data` body, never `octokit.graphql`), App auth, `GitHubUserAuth` (the OAuth web flow: code exchange, refresh, grant revocation, with final and temporary failures), resources (branches/tags/commits/releases/PRs/checks), pagination, one error taxonomy — **plus the configuration-WRITE half**: `GitHubRepository` settings (`repositoryPatch` builds a cast-free partial patch, dropping `undefined` fields), `Ruleset`, repo/environment secrets and variables (it owns the sealed-box crypto), `DeploymentEnvironment`, `CodeScanning`, `Attestation` | any GitHub API call — the route literal types params AND response, no casts — **and configuring a repository**: settings, rulesets, secrets, variables, environments; signing a user in with GitHub OAuth and refreshing their tokens | integrated | [github.md](./references/github.md) |
| `@effected/github-references` | GitHub's issue-reference grammar as PURE functions — the canonical nine closing keywords plus the separate non-closing `ref`/`refs`/`references` set, and three dialects: inline-in-prose (`harvestIssueReferences`, offsets, no colon), bare-line (`parseBareLineReference`, colon optional), closing-list (`parseClosingList`/`parseReferenceList`, `,`/`and`/Oxford `, and`), plus the whole-text sweeps (`parseBareLines`, `parseClosingLists`, `parseReferenceLists`, `harvestReferenceLists`, `collectReferenceLists`) and `keywordFamily` | parsing `Closes #12` out of a commit message, PR body or changelog — instead of hand-rolling a regex, which is the documented way to report a link GitHub never made | pure | [github-references.md](./references/github-references.md) |
| `@effected/github-actions` | the Actions RUNTIME: inputs/outputs/state/env, workflow commands, logger, cache, artifacts, tool installer, OIDC, the `GitHubToken` bridge; plus the reporting/document suite (`GitHubMarkdown`, `ManagedDocument`, `CheckDocument`/`CheckState`), the sbom-seam adapters (`ActionsProvenance`, `ActionsIdentityToken`), and `ActionsRegistryCredential` (npm's workload credential minted from the runner's identity) | writing a GitHub Action — talking to the runner, not the API | integrated | [github-actions.md](./references/github-actions.md) |
| `@effected/github-commands` | the Actions workflow-command grammar as pure string functions, no `effect` import: `WorkflowCommand` (render `::name key=value::message` with the runner's escaping; re-exported by `github-actions`) and `CommandNeutralizer` (make untrusted text safe to log, against both runner parsers) | writing or neutralizing a workflow command from any package, at any tier, without the Actions runtime | pure | [github-commands.md](./references/github-commands.md) |
| `@effected/sbom` | owned CycloneDX 1.6 emitter, Sigstore signing, in-toto/SLSA provenance, NTIA minimum-elements validation | generating, signing or attesting an SBOM | integrated | [sbom.md](./references/sbom.md) |
| `@effected/app` | the application control plane: one layer wiring XDG dirs + Store + Cache + config; `AppTest.layer` from `@effected/app/testing` is the hermetic memfs-backed test plane | wiring an APPLICATION's local state in one move | integrated | [app.md](./references/app.md) |
| `@effected/env` | who runs the program and what its terminal can do, through `Config` with no `process` read: `RuntimeEnv`/`CurrentRuntimeEnv` (agent family, CI provider as an exhaustive `CiName`, CI run coordinates `ciRun`, terminal, multiplexer/pane `session`, raw `termProgram`), `TerminalEnv` (per-stream colour level with Node's `FORCE_COLOR` precedence, hyperlinks, width), `Audience` (human/agent/CI, an override variable, flag-sourced), `EnvOverride` (a mode variable accepted per audience), `ShellExports` (strict, non-interpreting read/write of `export NAME=…` shell files such as Claude Code's session-env) | deciding output for an agent vs a person vs CI, or a colour/width/hyperlink fact, from an MCP server, an engine or a test reporter — without a CLI dependency; `@effected/cli-kit` builds it through `CliEnv` | boundary | [env.md](./references/env.md) |
| `@effected/cli-kit` | the CLI **presentation boundary**: `CliRuntime.main` (platform, environment, failure reporting, logger in one order; `CliExit` for findings), `CliAudience` (`--audience`/`--agent`/`--human`/`--ci` resolved before parsing), `CliEnv`/`CliInteractive`, `CliTheme`/`Token`/`Status`/`Glyphs`, `CliMessage`, the `Doc` IR with `Render.plain`/`ansi`/`markdown`/`githubLog`, `CliFailure`, `CliLog` diagnostics, `CliFormat` (a `--format` flag with `aliases` and `custom` formats, the one print that honours it, and `printJson` alone for a CLI with its own `--json`), `Fmt` (text helpers: `suggest` for a "did you mean" list, `errorText` for any failure as text), `CliPrompt` gates, schema/config issue renderers; `./ui` (optional `ink`/`react` peers): `CliUi` screens and widgets, the `CliUi.live` view, `CliUi.liveDetached` (a live view hosted outside Effect) and `CliUi.routeStream`, `DocView`; `./testing` (`CliTest.sandbox`/`run`/`spawn`, `TestTerminal`) and `./ui/testing` (`CliUiTest`) | a command-line program on `effect/cli` — Effect's default logger prints `[00:33:56.619] INFO (#2)` at a user, `runMain` reports failures on **stdout**, and nothing in core knows whether a person, an agent or CI is reading — teaching skill: `effect-v4-cli` | boundary (`./ui` integrated on opt-in) | [cli-kit.md](./references/cli-kit.md) |
| `@effected/mcp-kit` | the MCP boundary: `McpStdio` (`layerStdio` with stderr logging, a launch that never reports on stdout, teardown mapping stdin EOF to 0), `ToolFailure` (remediation folded into the wire message), `ToolInputSchema` (every unknown key at every depth in a `Tool.dynamic` payload), `McpToolkit` (registers a toolkit strict-by-default; core names every bad key and field in one response), `ToolOutcome` (the `ok: false` envelope: an expected error returned on the success channel as `structuredContent`), `ToolReplay` (idempotent replay of a write tool's first result by key), plus `@effected/mcp-kit/node` (`StdioCapture`: keeps an in-process library's stdout off the wire) plus `@effected/mcp-kit/testing` (`McpHarness`, `McpProcess`, `McpProbe`, `McpToolAudit`, `McpTestFailure`) | an MCP server on `effect/ai` — `runMain` reports a launch failure on stdout, which is the JSON-RPC wire, and a declared failure reaches the agent as message text only — teaching skill: `effect-v4-mcp` | boundary | [mcp-kit.md](./references/mcp-kit.md) |
| `@effected/lsp` | LSP base-protocol framing as pure functions: `LspFrame` (`encode` with a byte-counted `Content-Length`; `decodeResult`/`decodeAllResult`/`decodeStream` incremental decoders), `LspFrameError`, `LspStdio` (`launch`/`teardown`/`exitCode`: the stdio `main.ts` of an Effect Language Server), `LspUri` (`toPath`/`fromPath`: `file:` URI to path and back, pure, `Option.none()` for `untitled:`), plus `@effected/lsp/testing` (`LspProbe.initialize`, `LspProcess.spawn`, `LspTestFailure`) | reading or writing LSP frames; converting a `textDocument.uri` to a path without `node:url`; launching an Effect Language Server without a failure report on stdout and with the specification's exit code; driving a server bin frame by frame or proving its stdout held only frames; the packed-install proof that it boots (`initialize` → `initialized` → `shutdown` → `exit`, exit 0) — the LSP twins of `McpStdio`, `McpProcess` and `McpProbe` | boundary | [lsp.md](./references/lsp.md) |
| `@effected/pnpm-plugin-effected` | one pnpm catalog, `effected`, pinning the Effect family and the kit (companion — config, not code) | setting up Effect and `@effected/*` version pinning in a pnpm workspace | — | [pnpm-plugin-effected.md](./references/pnpm-plugin-effected.md) |
| `@effected/plugin` | the `effected` tool's carrier: install it and both bins arrive, `effected` (the command: `effected schema build\|check\|validate`, `effected package build`, `effected action build\|init`) and `effected-mcp` (the stdio MCP server with `schema_check`, `schema_validate`, `schema_build`, `package_build`, `action_build`, `action_init`), each reporting `via @effected/plugin <version>`; exports the `schemastore.config.ts` authoring surface (`defineSchemastore`, `HostedSchema`, `SchemaTarget` and the rest) from the copy of `@effected/schemastore` built into it, the tsconfig presets `@effected/plugin/tsconfig/ecma.json`, `action.json` and `root.json`, and `PLUGIN_VERSION` | giving a repo the `effected` tool, or publishing SchemaStore documents from a consumer repository without a generator script: add it as a root devDependency with `"@effected/plugin": "catalog:effected"` — the one tool package a consumer installs; the effected agent plugin launches `effected-mcp` from it | tool (no tier) | [plugin.md](./references/plugin.md) |
| `@effected/cli` | the `effected` command over `effect/cli` and `@effected/cli-kit`: `effected schema build\|check\|validate`, `effected package build`, `effected action build\|init`, `--version`, `--help`; `makeRootCommand(deps)` builds the tree, `main` runs it, a carrier passes its `distribution` | embedding or testing the `effected` command; do not install it directly, install `@effected/plugin` — not the CLI presentation library, which is `@effected/cli-kit` | tool (no tier) | [cli.md](./references/cli.md) |
| `@effected/mcp` | the `effected-mcp` stdio server with the `identity` tool and the `schema_check`, `schema_validate`, `schema_build`, `package_build`, `action_build` and `action_init` tools, on `effect/ai` and `@effected/mcp-kit`; `main` runs it, a carrier passes its `distribution` | embedding or testing the `effected-mcp` server; do not install it directly, install `@effected/plugin` — not the MCP boundary library, which is `@effected/mcp-kit` | tool (no tier) | [mcp.md](./references/mcp.md) |
| `@effected/engine` | the `effected` tool's shared logic: `Identity.report` builds an `IdentityReport` for both front ends; `@effected/engine/schema` holds the schema run (`SchemaRun`, `SchemaValidate`, `ConfigLoader`, reports) and the ajv engines `AjvValidator` and `AjvInstanceValidator` | adding logic both the `effected` command and `effected-mcp` must share — not the cross-front-end primitives library, which is `@effected/kit` | tool (no tier) | [engine.md](./references/engine.md) |
**Every row has a `references/` file.** Each package's own `CLAUDE.md` remains the
authority when the two disagree; the reference is the routing layer over it.
For `github`, `github-actions` and `commands` specifically, depth also lives
one level up: `building-a-github-action` routes a 14-skill suite (capability
references plus `designing-an-action`'s build sequence) covering these three
packages and `npm`/`sbom` in more depth than one reference file can — start
there when you are actually building an action.
## Search by intent
The package table routes when you know *which package*; the construct index
routes when you know *what you want done* but not what it is called. One
generated file per package lives in
[references/constructs/](./references/constructs/) — every export in the kit,
with its kind, TSDoc purpose, and intent keywords ("validate NTIA compliance",
"run a workspace binary", "build a GFM table node").
Before concluding the kit lacks a capability, grep the index by intent words:
```bash
grep -ri "table" plugin/skills/effected-packages/references/constructs/
grep -ri "oidc\|identity token" plugin/skills/effected-packages/references/constructs/
```
(In a consumer repo the plugin's install path replaces `plugin/`.) Rows whose
last column names an `implements` / `implemented by` pair are the kit's
deliberate contract↔implementation splits — the capability lives in a
different package than its contract. A no-match result means "not found in
this index" — check the package's reference and source before concluding the
kit lacks the capability. That is still far stronger evidence than never
grepping at all: hand-rolling a capability without an intent grep is how every
documented miss happened.
Facts about the kit that change how you depend on it:
- **`@effected/markdown` peers on `@effected/yaml` / `@effected/toml` /
`@effected/jsonc` *optionally*** (`peerDependenciesMeta`), consumed only by the
three frontmatter codec modules. Parsing markdown pulls in none of them. Note
also that **markdown→HTML and HTML→markdown are permanently out of scope**: to
render, project via `Mdast` and hand the plain-mdast tree to a renderer.
- **`@effected/package-json` delegates license validity to `@effected/spdx`** —
do not re-validate an SPDX expression yourself downstream of it.
- **`@effected/commands` owns no subprocess vocabulary.** Commands are core
`ChildProcess.Command` values built with core's own constructors; `Run` adds
the outcome (collected output, typed failure), the policy (timeout,
redaction, transience) and the tool. It ships no spawner backend — you provide
a platform layer at the edge, as with any boundary package.
- **`@effected/github-actions` is the ONE package in the kit with a required
`@effect/platform-node` peer.** An action always compiles into Node on a
GitHub runner, so there is no second platform to abstract over. Its
`@azure/storage-blob` dependency is confined to three modules and asserted by
a reachability test — import `ActionOutputs` and you cannot link Azure.
- **`@effected/sbom`'s entrypoint re-exports `Package`, `Person` and
`Repository` from `@effected/package-json`** — a consumer constructing
`SbomMetadataSource` inputs imports them from `@effected/sbom` directly
instead of adding the `package-json` edge itself.
- **`@effected/github` re-exports exactly six names from
`@effected/github-references`** (`CLOSING_KEYWORDS`, `ClosingKeyword`,
`IssueReference`, `harvestIssueReferences`, `BareLineReference`,
`parseBareLineReference`) as a **droppable compat shim** for consumers of the
grammar's old home. New consumers import `@effected/github-references`
directly — it is pure and octokit-free. The closing-list surfaces are
deliberately NOT re-exported from `github`; widening that shim would make it
permanent by accident.
- **`@effected/github` deliberately omits `@octokit/rest` and
`@octokit/auth-app`.** The former is a second spelling of the endpoint types;
the latter makes ~492 KB of OAuth machinery reachable just to mint installation
tokens, and the user OAuth web flow is `GitHubUserAuth` over plain `fetch`. Do
not reintroduce either.
- **`@effected/memfs` has zero `@effected/*` edges — by law, not accident** —
so ANY kit package may devDepend on it for tests without creating a cycle
(`glob` included: the engine keeps its embedded mini-glob; do not
"deduplicate" it). The engine is vendored from Effect-TS/effect PRs
#6573/#6555, with a planned sunset when core ships its own in-memory
`FileSystem`.
- **`@effected/workspaces` publishability has NO ambient default.** No
composite (`Workspaces.layer`, `layerWithGit`, …) provides
`PublishabilityDetector`, and none *requires* it either — nothing inside a
composite asks a publishability question, so its `R` stays `FileSystem |
Path`. The requirement surfaces only in the `R` of an operation that does
ask (`VersioningStrategy.detect`, e.g.): a program that asks and never wires
one fails to compile there, and a program that never asks never needs a
policy. Wire one explicitly where needed — `Layer.mergeAll(Workspaces.layer(),
PublishabilityDetector.layerNpm)` for npm semantics, `layerNone`, or your own
policy. The composite used to bake npm semantics in, and because
`Layer.mergeAll` is last-wins, the natural spelling of an override
(`Layer.mergeAll(mine, Workspaces.layer())`) silently lost to it. Each
shipped policy is also reachable as a **value** (`PublishabilityDetector.npm`),
so a policy that wraps npm semantics does not have to re-enter the tag it is
replacing.
## Local-build dogfood state
**Whether a given package has published is a check, not a roster to
memorize** — `npm view @effected/<name> version` answers it directly, and a
package that has not yet published is consumed from the local checkout during
a dogfood loop instead of from the registry.
Releases are changeset-driven: CI builds the appropriate changesets and
releases the packages they name. That may be the whole kit on an Effect advance
or a single package on a patch — a package can be released on its own, and
solo patches like `workspaces@0.11.1` are ordinary. A downstream repo
mid-dogfood-loop may still consume unreleased branch work from the local
`effected` checkout via `file:` overrides. Everything published is `0.x` and
unstable.
Three standing directives for a downstream repo rebuilding against this kit:
- **The dogfood main agent runs Fable and orchestrates** — it delegates rather
than implements: reasoning-heavy work to opus, mechanical work to sonnet.
- **No branching and no changesets in downstream repos during the rebuild.**
Work lands on the working branch; release bookkeeping comes later, once the
rebuild settles.
- **Mid-loop branch work resolves from the local checkout.** While a dogfood
loop is linked, a downstream manifest points at it (a workspace link or a
`file:`/`overrides:` entry) rather than a registry range, until the next
release wave carries the work.
## The two warnings every consumer inherits
- **`@effected/config-file`'s codecs are free-standing named exports**
(`JsonCodec`, `JsoncCodec`, `YamlCodec`, `TomlCodec`) — import exactly the
one you use and never collect them into a namespace object; a namespace
object reaches every codec and silently drags every parsing engine into the
bundle. `JsonCodec` is on the root; the other three import from
`@effected/config-file/jsonc`, `/yaml` and `/toml`, and each needs its
optional engine peer (`@effected/jsonc`, `@effected/yaml`,
`@effected/toml`) installed.
- **No library or package may depend on `@effected/app`** — but the application
itself is exactly its intended consumer. It is the application control plane;
a library taking it as a dependency drags integrated tier into every consumer,
so libraries compose `xdg`/`store`/`config-file` directly.
## Cross-cutting facts
- Every package publishes a flat CODE entrypoint (`@effected/<pkg>`), and a
few add a code subpath that the main entry never re-exports:
`@effected/workspaces/node-sync` (Node bindings for the synchronous escape
hatch), `@effected/workspaces/testing` (the repo-shape checks),
`@effected/memfs/node-sync` (`NodeSyncFileSystem`, a read-only synchronous
`FileSystem` over the real disk), `@effected/commands/node-sync` and
`@effected/walker/node-sync` (Node bindings for their sync forms),
`@effected/app/testing` (`AppTest`), `@effected/markdown/stringify` (serialize
markdown with no parser in the bundle), `@effected/mcp-kit/node` (`StdioCapture`),
`@effected/cli-kit/testing` (`CliTest`, `TestTerminal`), `@effected/cli-kit/ui`
(Ink screens and the live view, behind the optional `ink`/`react` peers),
`@effected/cli-kit/ui/testing` (`CliUiTest`), `@effected/mcp-kit/testing` (`McpHarness`,
`McpProbe` and friends), `@effected/lsp/testing` (`LspProbe`, `LspProcess`), the two
import-free crash-guard entrypoints `@effected/kit/guard`
(`ProcessGuard`, any transport) and `@effected/mcp-kit/guard` (`McpGuard`, its
MCP launcher), `@effected/npm/node` (`NpmHttpClient` and
`NpmTransportError`, behind the optional `@effect/platform-node` peer),
`@effected/pnpm/settings` (`PnpmSettingsCatalog`, which the root entry
never reaches), and `@effected/schema-org/validate` (offline
conformance validation). Everywhere else, no code subpath imports (each
package also exports its own `./package.json` for tooling; that is
metadata, not API).
- One platform layer at the edge discharges all IO: `NodeFileSystem.layer` +
`NodePath.layer` for the fs-only packages (walker, xdg, config-file,
package-json, tsconfig-json, workspaces), `NodeServices.layer` when
`ChildProcessSpawner` is also needed (git, `Workspaces.layerWithGit`,
`Workspaces.layerWithConfigDependenciesSubprocess`), or
the `@effect/platform-bun` equivalents. `runtimes` needs only
`FetchHttpClient.layer`; `store`'s sqlite layers bundle their own Node
driver. Pure packages and every `layerTest`/`testLayer` need nothing.
- Parameterized layer factories (`ConfigFile.layer(...)`,
`Store.layerSqlite(...)`, `App.layer(...)`, `WorkspaceDiscovery.layer(...)`)
mint a fresh layer per call and layers memoize by reference — bind the
result to a `const` once and reuse it.
- Test machinery worth knowing: `ConfigFile.testLayer`, `Store.layerTest`,
`Cache.layerTest`, `AppTest.layer` (`@effected/app/testing`), `@effected/npm`'s `Default` noop
resolvers, and `@effected/runtimes`' `.layerOffline`. Everything else tests
against core layers (`Path.layer`; a `FileSystem` double is `@effected/memfs`,
never `FileSystem.layerNoop`) or a mocked
`ChildProcessSpawner` — no platform package needed in unit tests.
- If a package feels like it is missing a service, a construct reads awkwardly,
or you re-implement something twice, surface it to the user as an
improvement suggestion for the kit — the ecosystem is actively dogfooding.
## Related skills
`effect-v4-module-index` routes Effect core; this skill routes the kit. Check
core first — the kit deliberately requires core contracts (`FileSystem`,
`ChildProcessSpawner`) rather than re-declaring them. `effect-v4-cli` and
`effect-v4-mcp` teach the CLI and MCP boundaries in depth; `design-patterns`
teaches the carrier pattern shared between a CLI and an MCP front end that
`@effected/kit` supports. `building-a-package` teaches `effected package build`
and `effected.toml` for a library a consumer builds with the kit, and
`authoring-tsdoc` the TSDoc and API Extractor rules that build enforces.
**Construct-level coverage — does every export get named somewhere in
`skills/` — is checked, not maintained by hand here.**
`plugin/__test__/construct-index.bats` regenerates the construct index from
every package's api-extractor doc model and fails on any drift from the
committed tables under `references/constructs/`, and its strict mode requires
an intent annotation for every value-kind export. The generated tables, not
this file's prose, are the source of truth for whether a given export is
covered — a hand-maintained claim of completeness drifts the same way this
file's own stale reference-file count once did. The maintenance loop lives in
the repo's `constructs` skill.
Files in this package (111)
- SKILL.md 53 KB
- references/app.md 13 KB
- references/bun.md 2 KB
- references/bundler.md 7 KB
- references/changesets.md 14 KB
- references/cli-kit.md 30 KB
- references/cli.md 8 KB
- references/commands.md 22 KB
- references/config-file.md 16 KB
- references/crypto.md 13 KB
- references/engine.md 2 KB
- references/env.md 12 KB
- references/files.md 5 KB
- references/git.md 24 KB
- references/github-actions.md 26 KB
- references/github-commands.md 4 KB
- references/github-references.md 8 KB
- references/github.md 30 KB
- references/glob.md 13 KB
- references/images.md 6 KB
- references/jsonc.md 10 KB
- references/jsonl.md 11 KB
- references/jwt.md 8 KB
- references/kit.md 15 KB
- references/lockfiles.md 12 KB
- references/lsp.md 12 KB
- references/manifest.md 3 KB
- references/markdown-lint.md 8 KB
- references/markdown.md 12 KB
- references/mcp-kit.md 31 KB
- references/mcp.md 4 KB
- references/memfs.md 11 KB
- references/npm.md 26 KB
- references/oidc.md 5 KB
- references/package-json.md 15 KB
- references/plugin.md 6 KB
- references/pnpm-plugin-effected.md 7 KB
- references/pnpm.md 10 KB
- references/runtimes.md 5 KB
- references/s3.md 9 KB
- references/sbom.md 12 KB
- references/schema-org.md 8 KB
- references/schemastore.md 22 KB
- references/semver.md 14 KB
- references/shell.md 14 KB
- references/source.md 5 KB
- references/spdx.md 6 KB
- references/store.md 14 KB
- references/templates.md 10 KB
- references/toml.md 4 KB
- references/tsconfig-json.md 7 KB
- references/walker.md 21 KB
- references/webhooks.md 8 KB
- references/workspaces.md 48 KB
- references/xdg.md 9 KB
- references/yaml.md 8 KB
- references/constructs/app.md 2 KB
- references/constructs/bun.md 1 KB
- references/constructs/bundler.md 41 KB
- references/constructs/changesets.md 11 KB
- references/constructs/cli-kit.md 26 KB
- references/constructs/cli.md 7 KB
- references/constructs/commands.md 11 KB
- references/constructs/config-file.md 7 KB
- references/constructs/crypto.md 5 KB
- references/constructs/engine.md 18 KB
- references/constructs/env.md 4 KB
- references/constructs/files.md 1 KB
- references/constructs/git.md 10 KB
- references/constructs/github-actions.md 22 KB
- references/constructs/github-commands.md 1 KB
- references/constructs/github-references.md 3 KB
- references/constructs/github.md 26 KB
- references/constructs/glob.md 3 KB
- references/constructs/images.md 4 KB
- references/constructs/jsonc.md 8 KB
- references/constructs/jsonl.md 5 KB
- references/constructs/jwt.md 3 KB
- references/constructs/kit.md 5 KB
- references/constructs/lockfiles.md 5 KB
- references/constructs/lsp.md 4 KB
- references/constructs/manifest.md 3 KB
- references/constructs/markdown-lint.md 3 KB
- references/constructs/markdown.md 28 KB
- references/constructs/mcp-kit.md 8 KB
- references/constructs/mcp.md 1 KB
- references/constructs/memfs.md 8 KB
- references/constructs/npm.md 20 KB
- references/constructs/oidc.md 1 KB
- references/constructs/package-json.md 15 KB
- references/constructs/plugin.md 7 KB
- references/constructs/pnpm-plugin-effected.md 1 KB
- references/constructs/pnpm.md 7 KB
- references/constructs/runtimes.md 6 KB
- references/constructs/s3.md 5 KB
- references/constructs/sbom.md 6 KB
- references/constructs/schema-org.md 6 KB
- references/constructs/schemastore.md 16 KB
- references/constructs/semver.md 5 KB
- references/constructs/shell.md 6 KB
- references/constructs/source.md 2 KB
- references/constructs/spdx.md 3 KB
- references/constructs/store.md 3 KB
- references/constructs/templates.md 3 KB
- references/constructs/toml.md 10 KB
- references/constructs/tsconfig-json.md 9 KB
- references/constructs/walker.md 9 KB
- references/constructs/webhooks.md 3 KB
- references/constructs/workspaces.md 26 KB
- references/constructs/xdg.md 3 KB
- references/constructs/yaml.md 16 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · spencerbeggs/effected | 100 | MIT |
| spencerbeggs/effected | 100 | MIT |
Database snapshot: 13.11.2026 · package version 7e0ca961f1b7 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100effected-renovate
Use when the user runs /effected-renovate, or asks to move a repository onto a new @effected kit release or a new Effect version — bump the catalog plugin and the other config dependencies, regenerate the lockfile, get the build and tests green, then work through the release's… - 100testing-actions
Use when writing or reviewing tests for @effected/github-actions, @effected/github, @effected/sbom or @effected/commands — stubbing the GitHub API, writing a service's layerTest or makeTest double, testing the pre/main/post lifecycle through Action.run, or debugging why a test… - 90working-in-the-monorepo
Package map, allowed dependencies, PR order, new packages, catalog versions, boundary lint errors. Use when you add a package, edit a package.json or pnpm-workspace.yaml, or import across packages. Don't use for contracts content (use working-with-contracts) or tests (use testing-and-ci). - 100link-workspace-packages
Link workspace packages in monorepos (npm, yarn, pnpm, bun). USE WHEN: (1) you just created or generated new packages and need to wire up their dependencies, (2) user imports from a sibling package and needs to add it as a dependency, (3) you get resolution errors for workspace… - 90monorepo
MUST use for ANY query mentioning packages, monorepo, workspace, catalog, turbo, turborepo, or pnpm in a multi-package context. MUST use when sharing config (ESLint, tsconfig, prettier) across packages, fixing build order between packages, adding new packages, scoping CI… - 100npm-semver
Semver and version-field discipline for published npm packages, plus a reminder to propagate a bump into consuming repos. TRIGGER when: editing the source of a published npm package, or preparing to publish one. DO NOT TRIGGER when: the package.json has "private": true, or the…