--- name: effected-packages 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 `; 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 blob transport (plain `HttpClient`, no Azure SDK) is confined to three modules and asserted by a reachability test — import `ActionOutputs` and you cannot link it. - **`@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/ 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/`), 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.