@danieljvdm/dev-kit 0.15.0 → 0.16.0

package/README.md

@@ -137,6 +137,7 @@ the root package itself.
 | `dev-kit gitignore`                        | Add `.repos/` and `.dev-kit/` to `.gitignore`.            |
 | `dev-kit effect sync`                      | Sync `.repos/effect` to the installed Effect version.     |
 | `dev-kit tsgo patch`                       | Validate and patch Effect TypeScript-Go directly.         |
+| `dev-kit cache prune`                      | Evict stale machine-global cache content (`--all` wipes). |
 | `dev-kit catalog refresh`                  | Maintainer command to approve current upstream refs.      |
 | `dev-kit catalog add <repository>`         | Inspect a repository and approve selected skills.         |
 | `dev-kit catalog remove <source-or-skill>` | Revoke an approval (`--yes` outside a terminal).          |
@@ -200,7 +201,8 @@ tool versions. A project-local process lock also prevents concurrent applies.
 
 - `dev-kit` installs guidance for operating the toolkit itself.
 - `effect` is a built-in family: the `effect-ts` bootstrap,
-  `effect-architecture-audit`, `build-effect-apis`, and `build-effect-clis`.
+  `effect-architecture-audit`, `build-effect-apis`, `effect-atom-state`, and
+  `build-effect-clis`.
 - External Git skills (`workers-best-practices`, `serve-sim`, …) are selected
   individually after scanning the project for relevant technologies. An
   approved source ID selects every skill from that source; use it only when
@@ -363,6 +365,53 @@ The scaffolded workflow performs one frozen, script-suppressed install, runs
 [Vite Task run guide](https://viteplus.dev/guide/run) when maintaining the
 templates.
 
+### Absolute (path-alias) imports
+
+Opt into enforcing path-alias imports for selected app sources. The factory
+appends an Oxlint override that errors on `../` imports inside the given
+globs, so those files import through tsconfig path aliases such as `@/*`:
+
+```ts
+export default defineConfig(
+  createRecommendedVitePlusConfig({
+    absoluteImports: {
+      files: ["apps/app/src/**/*.{ts,tsx}", "apps/mobile/src/**/*.{ts,tsx}"],
+    },
+  }),
+);
+```
+
+The lint rule only forbids relative parent imports; each covered app must map
+the alias itself. Add the `paths` entry to the app's `tsconfig.json`:
+
+```jsonc
+{
+  "compilerOptions": {
+    "paths": { "@/*": ["./src/*"] },
+  },
+}
+```
+
+Vite-built apps also resolve the alias from the same tsconfig by setting
+`resolve: { tsconfigPaths: true }` in the app's Vite config. Expo apps need no
+Metro configuration: Expo SDK 49+ resolves tsconfig `paths` by default.
+
+Standalone Oxlint projects compose the same override directly:
+
+```ts
+// oxlint.config.ts
+import {
+  createAbsoluteImportsOxlintOverride,
+  recommendedOxlintConfig,
+} from "@danieljvdm/dev-kit/oxlint";
+import { defineConfig } from "oxlint";
+
+export default defineConfig({
+  extends: [recommendedOxlintConfig],
+  overrides: [createAbsoluteImportsOxlintOverride({ files: ["src/**/*.{ts,tsx}"] })],
+});
+```
+
 ## Worktrunk project config
 
 Enable a scaffolded default [Worktrunk](https://worktrunk.dev) project config
@@ -413,9 +462,12 @@ Enable a local checkout of the exact installed Effect release in the manifest:
 ```
 
 `dev-kit apply` reads `node_modules/effect/package.json`, then shallow-clones or
-updates `.repos/effect` to the detached `effect@<version>` tag. It skips the
-checkout in CI, leaves the repository in place when the task is disabled, and
-refuses to switch a checkout with local changes or an unexpected origin.
+updates `.repos/effect` to the detached `effect@<version>` tag. Tag fetches go
+through a shared clone in the machine-global cache, so a new worktree or
+project reuses tags already cached on the machine and only contacts the
+network for a tag the cache has never seen. It skips the checkout in CI,
+leaves the repository in place when the task is disabled, and refuses to
+switch a checkout with local changes or an unexpected origin.
 
 The path, package name, and repository URL may be overridden for compatible
 Effect package layouts. Use `dev-kit effect sync --dry-run` to inspect this
@@ -587,9 +639,23 @@ names and paths, rejects symlinks and collisions, extracts descriptions, and
 updates `skill-sources.lock.json`.
 
 When a project selects one of these Git-backed skills, Dev Kit fetches the
-approved commit into the ignored `.dev-kit/cache` and installs it through the
-same ownership-safe sync path. Only a reviewed catalog refresh changes the
-approved Git content.
+approved commit into a machine-global cache and installs it through the same
+ownership-safe sync path. Cache entries are keyed by resolved commit SHA, so
+every project and git worktree on the machine shares one download; a warm
+`dev-kit plan` or `dev-kit apply` performs no network operations. The cache
+lives in `$XDG_CACHE_HOME/dev-kit` (falling back to `~/Library/Caches/dev-kit`
+on macOS and `~/.cache/dev-kit` elsewhere) and may be overridden with
+`DEV_KIT_CACHE_DIR`; it is safe to delete at any time. Populating this
+immutable commit-keyed cache is not project state, so planning and `--locked`
+verification use it too. Only a reviewed catalog refresh changes the approved
+Git content.
+
+The cache does not grow without bounds: every use refreshes a recency stamp,
+and `dev-kit apply` sweeps content unused for 30 days at most once a day.
+Shared Effect repositories drop unused tags individually and are removed whole
+once empty. Run `dev-kit cache prune` to sweep on demand (`--max-age-days` to
+tune the threshold, `--all` to clear the cache entirely); an evicted entry is
+simply fetched again the next time a project needs it.
 
 ## Oxlint and Oxfmt configurations
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danieljvdm/dev-kit",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "private": false,
   "description": "Declarative project development toolkit with portable agent skills.",
   "license": "MIT",

package/skills/build-effect-apis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: build-effect-apis
-description: Build and consume contract-first Effect HTTP APIs. Use when defining shared HttpApiEndpoint/HttpApiGroup contracts, implementing HttpApiBuilder or HttpApiServer handlers and middleware, deriving HttpApiClient or Effect Atom clients, or integrating those APIs with TanStack Start and Cloudflare Workers/effect-cf.
+description: Build contract-first Effect HTTP APIs. Use when defining shared HttpApiEndpoint/HttpApiGroup contracts, implementing HttpApiBuilder or HttpApiServer handlers and middleware, assembling server runtimes and OpenAPI docs, or serving on Cloudflare Workers/effect-cf. For consuming an API from client state, use $effect-atom-state.
 ---
 
 # Build Effect APIs
@@ -9,12 +9,11 @@ Treat the shared `HttpApi` value as the **contract spine**: schemas, server,
 OpenAPI, and clients all derive from it. Keep transport contracts isomorphic;
 keep runtime behavior in handlers, services, layers, and client state modules.
 
-Effect HTTP and reactivity APIs are version-sensitive. Read the target
-repository's manifests and lockfile, inspect its existing imports, and confirm
-exact signatures from the installed package declarations before editing. In
-current Effect v4 betas the server module is `HttpApiBuilder`; a request that
-mentions `HttpApiServer` may refer to the same server-building responsibility
-from another version.
+Effect HTTP APIs are version-sensitive. Read the target repository's manifests
+and lockfile, inspect its existing imports, and confirm exact signatures from
+the installed package declarations before editing. In current Effect v4 betas
+the server module is `HttpApiBuilder`; a request that mentions `HttpApiServer`
+may refer to the same server-building responsibility from another version.
 
 ## Build the contract spine
 
@@ -31,35 +30,21 @@ from another version.
    decoded boundary adapters into application services and assemble all
    requirements at the runtime edge. Finish when each endpoint identifier has
    exactly one handler and every declared middleware has a provided layer.
-4. Choose the consumer branch:
-   - For React server state, read
-     [effect-atom-client.md](references/effect-atom-client.md) and
-     [effect-atom-lifecycle.md](references/effect-atom-lifecycle.md), then
-     derive one `AtomHttpApi.Service`, stable query atoms or families, mutation
-     atoms, and one reactivity-key vocabulary.
-   - For non-React Effect code, use the direct `HttpApiClient` branch in
-     [effect-atom-client.md](references/effect-atom-client.md).
-
-   Finish when consumers call the shared contract rather than redefining wire
-   types or using ad hoc `fetch` for declared endpoints.
-
+4. Route consumer changes through the `$effect-atom-state` skill: deriving
+   `AtomHttpApi` or direct `HttpApiClient` clients, query and mutation atoms,
+   reactivity keys, and React integration all live there. Finish when consumers
+   call the shared contract rather than redefining wire types or using ad hoc
+   `fetch` for declared endpoints.
 5. Read [verification.md](references/verification.md). Run the repository's
    format, lint, typecheck, and test commands. Finish when changed schemas
-   round-trip, middleware failures use declared error channels, server and
-   client agree on every request shape, and changed atom lifecycles have
-   deterministic coverage.
+   round-trip, middleware failures use declared error channels, and server and
+   client agree on every request shape.
 
 ## Optional branches
 
 - Read [runtime-assembly.md](references/runtime-assembly.md) when wiring a
   conventional Node/Bun server, generated API docs, process entrypoint, or
   serverless web handler.
-- Read [effect-atom-testing.md](references/effect-atom-testing.md) when changing
-  Atom cache retention, SWR, polling, invalidation, cancellation, aggregation,
-  provider placement, SSR, or hydration behavior.
-- Read [tanstack-start.md](references/tanstack-start.md) when the client is
-  TanStack Start, SSR, hydration, `ClientOnly`, loaders, server functions, or a
-  proxied separate API.
 - Read [cloudflare-workers.md](references/cloudflare-workers.md) when the server
   runs on Cloudflare Workers or uses `effect-cf`, bindings, Durable Objects,
   Queues, WebSockets, streaming, or raw byte routes.
@@ -94,6 +79,3 @@ but the boundary and type reasoning remain the source of truth.
 - Let handlers own transport-to-application mapping and boundary invariants.
 - Let application services own orchestration, persistence, retries, and
   transactions.
-- Let client data modules own API services, query identity, cache policy,
-  invalidation keys, and mutation atoms; let UI action owners own navigation,
-  toasts, optimistic presentation, and form reset.

package/skills/build-effect-apis/references/verification.md

@@ -48,9 +48,9 @@ decoding are skipped.
   `HttpApiMiddleware.layerClient` and assert that it transforms the request.
 - Assert params, query, headers, payload, and expected errors at least once for
   every changed request shape.
-- For Atom clients, complete every applicable scenario routed through
-  `effect-atom-testing.md`; use a deterministic HTTP layer so request encoding,
-  invalidation, and lifecycle remain observable.
+- For Atom clients, complete every applicable scenario in the
+  `$effect-atom-state` skill's testing reference; use a deterministic HTTP
+  layer so request encoding, invalidation, and lifecycle remain observable.
 
 ## Completion matrix
 

package/skills/effect-atom-state/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: effect-atom-state
+description: Manage client-side state and server data in React with Effect Atom, which fills the role TanStack/React Query, SWR, Zustand, Redux, or Jotai play in other stacks — use this skill instead of reaching for those libraries or hand-rolled useEffect fetching whenever a component needs shared state, data fetching, caching, mutations, or optimistic updates. Also use when reading or dispatching atoms (useAtomValue, useAtomSet, useAtom), refactoring promise chains or useState-held server state into atom workflows, choosing reactivity keys and invalidation, deriving AtomHttpApi or HttpApiClient clients from a shared contract, deciding where the Effect→Promise boundary sits, or wiring RegistryProvider and SSR with TanStack Start.
+---
+
+# Effect Atom State
+
+Effect Atom is the client-state and server-data layer in an Effect repository:
+the role other stacks give TanStack Query, SWR, Zustand, Redux, or Jotai.
+Every need that would reach for one of those libraries — or for hand-rolled
+`useEffect` fetching — is atom work; never introduce a second state or query
+library beside it.
+
+Business logic stays in Effect for as long as possible. Components read
+`AsyncResult` values and dispatch actions; workflows, optimistic updates, and
+cache invalidation live in atoms, not in promise chains at the React boundary.
+
+Effect Atom APIs are version-sensitive. Read the target repository's manifests
+and lockfile, inspect its existing imports, and confirm exact signatures from
+the installed `effect` and `@effect/atom-react` declarations before editing.
+In current Effect v4 betas the atom modules live in
+`effect/unstable/reactivity` and the React hooks in `@effect/atom-react`.
+
+## Build the client state graph
+
+1. Inventory the existing `RegistryProvider`, runtime factories,
+   `AtomHttpApi.Service` clients, query atoms and families, mutation and
+   workflow atoms, reactivity-key constructors, state atoms, and promise-mode
+   dispatch sites. Finish when every consumer of the affected state is
+   identified.
+2. Read [effect-atom-client.md](references/effect-atom-client.md), then derive
+   one `AtomHttpApi.Service` per contract, stable query atoms or families,
+   mutation atoms, and one reactivity-key vocabulary. For non-React Effect
+   code, use the direct `HttpApiClient` branch. Finish when consumers call the
+   shared contract rather than redefining wire types or using ad hoc `fetch`
+   for declared endpoints.
+3. Read [effect-atom-workflows.md](references/effect-atom-workflows.md), then
+   express every multi-step action — mutate then invalidate, optimistic echo
+   then rollback — as an `Atom.fn` effect composing other atoms through the fn
+   context. Finish when no component or route chains `.then`/`.catch` on a
+   dispatch and no `useState` holds state a workflow atom must own.
+4. Read [effect-atom-lifecycle.md](references/effect-atom-lifecycle.md) when
+   changing registry scope, atom identity, retention, freshness, polling,
+   cancellation, or aggregate stability.
+5. Read [effect-atom-testing.md](references/effect-atom-testing.md), then give
+   changed atom behavior deterministic coverage below React first, with a
+   deterministic HTTP layer so request encoding, invalidation, and lifecycle
+   remain observable. Run the repository's format, lint, typecheck, and test
+   commands. Finish when changed queries, mutations, invalidation, and
+   workflow atoms have deterministic tests and every repository check passes.
+
+## Optional branches
+
+- Read [tanstack-start.md](references/tanstack-start.md) when the client is
+  TanStack Start, SSR, hydration, `ClientOnly`, loaders, server functions, or a
+  proxied separate API.
+- Use the `$build-effect-apis` skill when the change reaches the contract or
+  server: shared `HttpApiEndpoint`/`HttpApiGroup` definitions, handlers,
+  middleware, or runtime assembly.
+
+## Keep the Promise boundary logic-free
+
+The Effect→Promise boundary sits at the outermost edge and carries no logic.
+
+- Return a promise-mode dispatch (`useAtomSet(action, { mode: "promise" })`)
+  bare to a leaf component whose contract is promise-shaped — a pending
+  button, a composer that owns its in-flight state. A `.then` or `.catch`
+  chain in a component or route is a violation: move that logic into the
+  action's Effect.
+- Express multi-step workflows as `Atom.fn` effects composing other atoms
+  through the fn context: `get.setResult` awaits another fn atom, `get.set`
+  writes state atoms. Reads through the fn context callable are untracked, so
+  mutating a state atom from inside the effect cannot re-trigger the workflow.
+- Declare cross-query invalidation as reactivity keys on the mutation; never
+  chain a manual refresh at a call site. When several `AtomHttpApi` services
+  share one Atom runtime, one `Reactivity` instance spans them, so a mutation
+  on one client invalidates another client's query keys.
+- Keep optimistic UI state in `Atom.family` state atoms keyed by the entity,
+  not `useState`, so the workflow atom that writes it owns its lifecycle.
+- Genuine view state — controlled inputs, open/closed toggles, reconciling
+  optimistic rows against rendered props — stays in React; do not force it
+  into Effect.
+
+A repository may reinforce the boundary with a lint warning on `then` scoped
+to component and route modules, with a documented local suppression for a
+genuinely promise-shaped contract, but the boundary reasoning remains the
+source of truth.
+
+## Boundary rules
+
+- Let client data modules own API services, query identity, cache policy,
+  invalidation keys, mutation atoms, and workflow atoms.
+- Let workflow atoms own orchestration, optimistic echo, rollback, and
+  cross-query invalidation.
+- Let UI action owners own navigation, toasts, form reset, and presentation
+  derived from `AsyncResult` state.
+- Let React own view state that no atom needs to write.

package/skills/effect-atom-state/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Effect Atom State"
+  short_description: "Manage Effect Atom client state and React integration"
+  default_prompt: "Use $effect-atom-state to move this component's client state and workflows into Effect Atom."

package/skills/effect-atom-state/references/effect-atom-workflows.md

@@ -0,0 +1,180 @@
+# Effect Atom workflows
+
+Multi-step client actions are Effects composing atoms. Components dispatch
+them and render `AsyncResult` state; no orchestration crosses the React
+boundary. Confirm exact signatures against the installed
+`effect/unstable/reactivity` declarations before copying.
+
+- [Define workflow atoms with Atom.fn](#define-workflow-atoms-with-atomfn)
+- [Compose atoms through the fn context](#compose-atoms-through-the-fn-context)
+- [Overlay optimistic query values](#overlay-optimistic-query-values)
+- [Dispatch from React](#dispatch-from-react)
+- [Reinforce the boundary with a lint rule](#reinforce-the-boundary-with-a-lint-rule)
+
+## Define workflow atoms with Atom.fn
+
+`Atom.fn<Input>()(effect)` creates a writable atom: writing an input runs the
+effect, and the atom's value is the `AsyncResult` of the latest run. The
+effect receives `(input, get: Atom.FnContext)`.
+
+Bare `Atom.fn` accepts no reactivity keys. When the workflow needs Effect
+services or invalidation, create it through a runtime factory —
+`AtomHttpApi.Service` exposes its own as `Client.runtime.fn`:
+
+```ts
+import { Effect } from "effect";
+import { Atom, Reactivity } from "effect/unstable/reactivity";
+
+export const updateProject = ApiClient.runtime.fn(
+  Effect.fnUntraced(function* (input: { readonly projectId: ProjectId; readonly patch: Patch }) {
+    const client = yield* ApiClient;
+
+    return yield* Reactivity.mutation(
+      client.projects.updateProject({
+        params: { projectId: input.projectId },
+        payload: input.patch,
+      }),
+      [...projectKeys.collection, ...projectKeys.project(input.projectId)],
+    );
+  }),
+);
+```
+
+Prefer `Client.mutation(group, endpoint)` with call-site `reactivityKeys` for a
+single request; wrap the client call in `runtime.fn` with
+`Reactivity.mutation(effect, keys)` when the key set depends on the input or
+the workflow spans several requests. Either way, keys invalidate only when the
+effect succeeds.
+
+Invalidation spans clients: every `AtomHttpApi.Service` built on the same
+runtime factory shares one `Reactivity` instance, so a mutation on one client
+invalidates query keys registered by another. A service given its own
+`Atom.context()` gets a separate `Reactivity` and cannot invalidate the rest —
+share one runtime factory across API services on purpose.
+
+## Compose atoms through the fn context
+
+Inside the effect, the fn context is the composition surface:
+
+- `get.setResult(fnAtom, input)` writes another fn atom and returns an Effect
+  of its settled result — the await-another-workflow primitive;
+- `get.set(stateAtom, value)` writes a state atom;
+- `get(atom)` reads the current value **untracked** — the workflow never
+  subscribes, so mutating a state atom from inside the effect cannot
+  re-trigger it.
+
+Optimistic echo with rollback, keyed by the owning entity so the atoms
+dispose with it:
+
+```ts
+import { Effect, Exit } from "effect";
+
+interface PendingComment {
+  readonly id: string;
+  readonly body: string;
+  readonly status: "sending" | "queued";
+}
+
+export const pendingCommentsAtom = Atom.family((_projectId: ProjectId) =>
+  Atom.make<ReadonlyArray<PendingComment>>([]),
+);
+
+export const sendCommentWithEcho = Atom.family((projectId: ProjectId) =>
+  Atom.fn<{ readonly body: string }>()(
+    Effect.fnUntraced(function* (input, get) {
+      const pending = pendingCommentsAtom(projectId);
+      const id = yield* Effect.sync(() => crypto.randomUUID());
+
+      get.set(pending, [...get(pending), { id, body: input.body, status: "sending" }]);
+
+      const exit = yield* Effect.exit(get.setResult(sendComment, { projectId, body: input.body }));
+
+      get.set(
+        pending,
+        Exit.isSuccess(exit)
+          ? get(pending).map((entry) =>
+              entry.id === id ? { ...entry, status: "queued" as const } : entry,
+            )
+          : get(pending).filter((entry) => entry.id !== id),
+      );
+
+      yield* exit;
+    }),
+  ),
+);
+```
+
+The pending list lives in an `Atom.family` state atom, not component
+`useState`, so the workflow owns append, settle, and rollback while any
+component can render it. Re-raise the exit so the dispatching leaf still
+observes failure.
+
+## Overlay optimistic query values
+
+When the optimistic value is the query's own value rather than a sidecar list,
+wrap the query with `Atom.optimistic` and drive it with `Atom.optimisticFn`:
+
+```ts
+import { AsyncResult } from "effect/unstable/reactivity";
+
+export const timelineAtom = Atom.family((projectId: ProjectId) =>
+  Atom.optimistic(timelineQuery(projectId)),
+);
+
+export const sendMessage = Atom.family((projectId: ProjectId) =>
+  Atom.optimisticFn(timelineAtom(projectId), {
+    reducer: (current, message: MessageDto) =>
+      AsyncResult.map(current, (page) => ({
+        ...page,
+        messages: [...page.messages, message],
+      })),
+    fn: submitMessage(projectId),
+  }),
+);
+```
+
+The reducer computes the provisional value shown while the mutation runs; a
+successful transition refreshes the source query, and a failure rolls the
+value back to the latest source value. Consumers render `timelineAtom` and
+never see the seam.
+
+## Dispatch from React
+
+A promise-mode dispatch is handed bare to a leaf component whose contract is
+promise-shaped; presentation derives from the atom's `AsyncResult`:
+
+```tsx
+const [sendResult, send] = useAtom(sendMessage(projectId), { mode: "promise" });
+const hint = AsyncResult.isSuccess(sendResult) && !sendResult.waiting ? "sent" : undefined;
+
+return <Composer hint={hint} onSubmit={(body) => send({ body })} />;
+```
+
+The returned promise resolves with the success value and rejects with the
+squashed failure cause; use `mode: "promiseExit"` when the leaf needs the full
+`Exit`. Anything more than returning the promise — chaining a refresh, echo
+bookkeeping, sequencing a second mutation — belongs in the workflow atom.
+
+## Reinforce the boundary with a lint rule
+
+A repository can back the logic-free boundary with a lint warning on `then`
+scoped to component and route modules, mirroring the typed-codec lint pattern:
+
+```ts
+{
+  files: ["apps/web/src/components/**", "apps/web/src/routes/**"],
+  rules: {
+    "no-restricted-properties": [
+      "warn",
+      {
+        property: "then",
+        message:
+          "Compose the workflow in Effect (Atom.fn + reactivity keys) and return promise-mode dispatches bare to the leaf component.",
+      },
+    ],
+  },
+}
+```
+
+Keep any justified suppression local and documented; the boundary reasoning,
+not the lint rule, remains the source of truth.

package/src/bin/dev-kit.ts

@@ -12,6 +12,7 @@ import { printError } from "../cli-ui.ts";
 import { syncEffectSource } from "../effect-source.ts";
 import { patchEffectTsgo } from "../effect-tsgo.ts";
 import { patchProjectGitignore } from "../gitignore.ts";
+import { CACHE_PRUNE_AGE_DAYS, runCachePrune } from "../global-cache.ts";
 import {
   addSkills,
   chooseSkillsToAdd,
@@ -351,6 +352,25 @@ const catalogVerifyCommand = CliCommand.make(
     refreshSkillCatalog({ locked: true, lockfilePath: lockfile, repoDir, sourcesPath: sources }),
 ).pipe(CliCommand.withDescription("Verify the committed catalog without advancing refs."));
 
+const cachePruneCommand = CliCommand.make(
+  "prune",
+  {
+    all: Flag.boolean("all").pipe(
+      Flag.withDescription("Remove the entire cache instead of only stale content."),
+    ),
+    maxAgeDays: Flag.integer("max-age-days").pipe(
+      Flag.withDefault(CACHE_PRUNE_AGE_DAYS),
+      Flag.withDescription("Evict content unused for this many days."),
+    ),
+  },
+  ({ all, maxAgeDays }) => runCachePrune({ all, maxAgeDays }),
+).pipe(CliCommand.withDescription("Evict stale content from the machine-global source cache."));
+
+const cacheCommand = CliCommand.make("cache").pipe(
+  CliCommand.withDescription("Manage the machine-global source cache."),
+  CliCommand.withSubcommands([cachePruneCommand] as const),
+);
+
 const catalogCommand = CliCommand.make("catalog").pipe(
   CliCommand.withDescription("Maintain the approved upstream catalog."),
   CliCommand.withSubcommands([
@@ -382,6 +402,7 @@ const command = CliCommand.make("dev-kit", projectFlags, ({ manifest, projectDir
         effectCommand,
         tsgoCommand,
         catalogCommand,
+        cacheCommand,
       ],
     },
   ] as const),

package/src/catalog.ts

@@ -2,6 +2,11 @@ import { Effect, FileSystem, Path, Schema, Stream } from "effect";
 import { ChildProcess } from "effect/unstable/process";
 import { parse as parseJsonc, type ParseError } from "jsonc-parser";
 
+import {
+  commitCacheDirectory,
+  resolveGlobalCacheDirectory,
+  stampCacheEntryUsage,
+} from "./global-cache.ts";
 import {
   discoverPackageSkills,
   resolvePackageSkillSelector,
@@ -181,7 +186,13 @@ export const loadSkillCatalog = Effect.fn("loadSkillCatalog")(function* (
     });
   }
   const families: Readonly<Record<string, ReadonlyArray<string>>> = {
-    effect: ["effect-ts", "effect-architecture-audit", "build-effect-apis", "build-effect-clis"],
+    effect: [
+      "effect-ts",
+      "effect-architecture-audit",
+      "build-effect-apis",
+      "effect-atom-state",
+      "build-effect-clis",
+    ],
     ...Object.fromEntries(externalFamilies),
   };
 
@@ -261,26 +272,35 @@ const materializePackageSkill = Effect.fn("materializePackageSkill")(function* (
   return staged;
 });
 
+// Catalog checkouts are keyed by source id and resolved commit SHA, so the
+// materialized content is immutable and shared machine-wide across projects
+// and worktrees. Planning and locked verification populate the same cache:
+// writing an immutable commit-keyed cache entry is not project state.
 const materializeSource = Effect.fn("materializeCatalogSource")(function* (
-  projectDir: string,
   source: LockedSkillSource,
   selected: ReadonlyArray<string>,
-  cache: boolean,
 ) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
-  const root = cache
-    ? path.join(projectDir, ".dev-kit", "cache", "catalog", source.id, source.resolved)
-    : path.join(
-        yield* fs.makeTempDirectoryScoped({ prefix: "dev-kit-catalog-plan-" }),
-        source.id,
-        source.resolved,
-      );
-  const checkout = path.join(root, "checkout");
+  const root = path.join(
+    yield* resolveGlobalCacheDirectory(),
+    "catalog",
+    source.id,
+    source.resolved,
+  );
   const ready = path.join(root, ".ready");
 
   if (!(yield* fs.exists(ready))) {
-    yield* fs.remove(root, { force: true, recursive: true });
+    yield* fs.makeDirectory(path.dirname(root), { recursive: true });
+    const staged = path.join(
+      yield* fs.makeTempDirectoryScoped({
+        directory: path.dirname(root),
+        prefix: ".dev-kit-catalog-stage-",
+      }),
+      source.resolved,
+    );
+    const checkout = path.join(staged, "checkout");
+
     yield* fs.makeDirectory(checkout, { recursive: true });
     yield* runGit(checkout, ["init", "--quiet"]);
     yield* runGit(checkout, ["remote", "add", "origin", source.repository]);
@@ -302,7 +322,7 @@ const materializeSource = Effect.fn("materializeCatalogSource")(function* (
     }
     for (const skill of source.skills) {
       const from = path.join(checkout, source.skillsPath, skill);
-      const to = path.join(root, "skills", skill);
+      const to = path.join(staged, "skills", skill);
       const observation = yield* observePath(from);
 
       if (observation.kind !== "directory") {
@@ -320,8 +340,10 @@ const materializeSource = Effect.fn("materializeCatalogSource")(function* (
         );
       }
     }
-    yield* fs.writeFileString(ready, `${source.resolved}\n`);
+    yield* fs.writeFileString(path.join(staged, ".ready"), `${source.resolved}\n`);
+    yield* commitCacheDirectory(staged, root, fs.exists(ready));
   }
+  yield* stampCacheEntryUsage(root);
   for (const skill of selected) {
     const observation = yield* observePath(path.join(root, "skills", skill));
     const approvedDigest = source.digests?.[skill];
@@ -351,6 +373,8 @@ const materializeSource = Effect.fn("materializeCatalogSource")(function* (
   );
 });
 
+// The cache flag only affects package skills, whose staging area is project
+// state under .dev-kit; catalog sources always use the machine-global cache.
 export const resolveSkillSources = Effect.fn("resolveSkillSources")(function* (
   packageRoot: string,
   projectDir: string,
@@ -370,7 +394,7 @@ export const resolveSkillSources = Effect.fn("resolveSkillSources")(function* (
     const wanted = source.skills.filter((skill) => selected.includes(skill));
 
     if (wanted.length === 0) continue;
-    for (const [name, sourcePath] of yield* materializeSource(projectDir, source, wanted, cache)) {
+    for (const [name, sourcePath] of yield* materializeSource(source, wanted)) {
       sources.set(name, sourcePath);
     }
   }