@danieljvdm/dev-kit 0.14.0 → 0.16.0

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/skills/open-pull-request/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: open-pull-request
-description: Open pull requests with conventional commits, terse context-complete English descriptions, and verified proof of work. Use whenever preparing or opening a pull request, including checking commit history, drafting the title or body, and attaching screenshots or other evidence.
+description: Open pull requests with conventional commits, reviewer-complete descriptions, links to vital code, and concrete evidence. Use whenever preparing or opening a pull request, including checking commit history, explaining a bug or architectural change, drafting the title or body, and attaching screenshots or other evidence.
 ---
 
 # Open a Pull Request
@@ -22,18 +22,38 @@ task conversation.
    `build`, `ci`, or `chore`. Keep each commit to one logical concern. Rewrite
    only commits you created and know are unshared; get approval before
    rewriting user-authored or published history.
-3. Run the repository's required validation on the final branch state. Record
-   the exact commands and results, then collect the strongest available proof
-   of the changed behavior. Finish when every claim in the PR can be traced to
-   the diff, a check result, or an artifact.
+3. Run the repository's required validation on the final branch state, then
+   collect the strongest available evidence of the changed behavior. Identify
+   the few files, symbols, or modules a reviewer must understand and prepare
+   links that resolve in the rendered PR. Finish when every claim can be traced
+   to the diff, CI, or a verified artifact.
 
 ## Write for the reviewer
 
-Write terse, plain English for someone with little context. Lead with the
-observable outcome and add only the minimum reason needed to understand it.
-Prefer short bullets and concrete nouns. Expand uncommon acronyms. Describe
-behavior and impact rather than narrating files, implementation steps, or the
-task conversation.
+Write clear, compact English for someone with little context. Give the reviewer
+enough explanation to agree with both the problem and the solution; do not
+sacrifice causal or architectural context for brevity. Lead with the observable
+outcome, then explain why the change was needed and how the important pieces
+fit together. Prefer concrete nouns and expand uncommon acronyms. Describe
+behavior and impact rather than narrating the task conversation.
+
+Link the vital implementation points from the summary or architecture section.
+Use descriptive link text that names each piece by its role, such as the request
+router or cache invalidation boundary, and verify every link after opening the
+PR. Link the core pieces a reviewer should inspect, not every touched file.
+
+For every bug fix, include a **What went wrong** section in plain English. State
+the incorrect behavior, its actual root cause and causal chain, and why the
+change fixes it. Make uncertainty or incomplete coverage explicit. A result
+such as "fixed stale state" is not a diagnosis; explain how the stale state was
+created or allowed to survive.
+
+When the change alters architecture, identify the affected components and
+boundaries, what each one owns after the change, and any important change to
+control flow, data flow, public contracts, or persistence. Link to the core
+implementation of each affected piece. Use a dedicated **Architecture** section
+when this would make the change easier to review; otherwise include the context
+in the summary.
 
 Use the repository's required template when present. Otherwise use this small
 shape and omit empty sections:
@@ -42,38 +62,57 @@ shape and omit empty sections:
 ## Summary
 
 - <What changes for a user, operator, or developer>
-- <Why it matters, only when the first bullet does not make that clear>
+- <Why it matters and the shape of the solution, with links to vital code>
+
+## What went wrong
+
+<For a bug fix: explain the symptom, root cause, causal chain, and why this fix
+addresses it.>
 
-## Proof
+## Architecture
 
-- `<validation command>` — passed
-- <Screenshot, sample output, or other verified artifact>
+- <When applicable: explain the changed components, ownership, and flow, with
+  links to their core implementations.>
+
+## Evidence
+
+- <Screenshot, before/after output, request/response, trace, or other verified
+  artifact>
 ```
 
-Keep the summary to one to three bullets. Make the title specific enough to
+Keep the body proportional to the change: a small change may need two useful
+bullets, while a subtle bug or architectural change may need several paragraphs.
+Omit conditional sections that do not apply. Make the title specific enough to
 stand alone in release notes and conventional enough to become the squash
 commit without editing.
 
-## Show proof of work
+## Show useful evidence
 
-Proof is something the reviewer can inspect, not an assertion that the change
-works.
+Evidence is something the reviewer can inspect, not an assertion that the
+change works.
 
 - For a runnable UI or visual feature, capture and attach a screenshot or short
   recording of the actual final state. Use a representative viewport, add a
   short caption, and check the artifact for secrets or personal data.
 - For CLI, API, or automation behavior, include concise terminal output, a
   request/response example, generated artifact, or execution log when it proves
-  more than the validation command alone.
+  the behavior more clearly than the CI result alone.
 - For a bug fix or behavior change, prefer before/after evidence when it is
   practical and materially clarifies the result.
-- For internal-only changes, exact passing validation commands may be the most
-  useful proof.
+- For internal-only changes, include focused regression output, a trace, a
+  generated artifact, or another result that demonstrates the changed behavior
+  when available.
+
+Routine validation commands that CI always runs, such as `vp check` or standard
+format, lint, typecheck, and test commands, add no useful context to the PR body.
+Let CI report them. Mention a command or CI result only when it is unusual,
+cannot run in CI, or its output itself helps the reviewer understand the change.
 
 Include only evidence that was actually produced and verified. When expected
 visual proof cannot be produced, state the concrete reason briefly instead of
-silently substituting a claim. Preserve terse descriptions by choosing the
-smallest set of evidence that proves the outcome.
+silently substituting a claim. Choose the smallest set of evidence that makes
+the changed behavior easy to inspect. Omit the section when no evidence adds
+information beyond routine CI.
 
 ## Open and verify
 

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);
     }
   }

package/src/effect-source.ts

@@ -2,6 +2,11 @@ import { Config, Effect, FileSystem, Path, Schema, Stream } from "effect";
 import { ChildProcess } from "effect/unstable/process";
 
 import { printStatus, withSpinner } from "./cli-ui.ts";
+import {
+  commitCacheDirectory,
+  resolveGlobalCacheDirectory,
+  stampTagUsage,
+} from "./global-cache.ts";
 import { observeSymbolicLink } from "./node-symbolic-link.ts";
 import { acquireProjectProcessLock } from "./project-process-lock.ts";
 import { isTypeScriptPackageName } from "./typescript-package-name.ts";
@@ -272,12 +277,73 @@ export const planEffectSource = Effect.fn("planEffectSource")(function* (
   } satisfies EffectSourcePlan;
 });
 
+// The shared bare repository accumulates shallow tag fetches machine-wide, so
+// a project checkout only contacts the network when its tag has never been
+// cached on this machine. Entries are keyed by repository URL.
+const ensureSharedRepository = Effect.fn("ensureSharedEffectRepository")(function* (
+  repository: string,
+  tag: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const repositoryDir = path.join(
+    yield* resolveGlobalCacheDirectory(),
+    "effect-source",
+    encodeURIComponent(repository),
+  );
+  const populated = fs.exists(path.join(repositoryDir, "HEAD"));
+
+  if (!(yield* populated)) {
+    yield* fs.makeDirectory(path.dirname(repositoryDir), { recursive: true });
+    const staged = path.join(
+      yield* fs.makeTempDirectoryScoped({
+        directory: path.dirname(repositoryDir),
+        prefix: ".dev-kit-effect-source-stage-",
+      }),
+      "repository",
+    );
+
+    yield* runGit(path.dirname(staged), ["init", "--quiet", "--bare", staged]);
+    yield* commitCacheDirectory(staged, repositoryDir, populated);
+  }
+  yield* stampTagUsage(repositoryDir, tag);
+  const cached = yield* runGit(repositoryDir, [
+    "rev-parse",
+    "-q",
+    "--verify",
+    `refs/tags/${tag}^{commit}`,
+  ]).pipe(Effect.catchTag("EffectSourceCommandError", () => Effect.void));
+
+  if (cached === undefined) {
+    yield* runGit(repositoryDir, [
+      "fetch",
+      "--depth",
+      "1",
+      "--force",
+      "--quiet",
+      repository,
+      `refs/tags/${tag}:refs/tags/${tag}`,
+    ]).pipe(
+      // A concurrent apply may have fetched the tag first; keep its result.
+      Effect.catchTag("EffectSourceCommandError", (error) =>
+        runGit(repositoryDir, ["rev-parse", "-q", "--verify", `refs/tags/${tag}^{commit}`]).pipe(
+          Effect.mapError(() => error),
+          Effect.asVoid,
+        ),
+      ),
+    );
+  }
+
+  return repositoryDir;
+});
+
 export const applyEffectSourcePlan = Effect.fn("applyEffectSourcePlan")(function* (
   plan: EffectSourcePlan,
 ) {
   if (plan.action !== "sync") return;
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
+  const repositoryDir = yield* ensureSharedRepository(plan.repository, plan.tag);
 
   if (!(yield* fs.exists(plan.checkoutDir))) {
     const parent = path.dirname(plan.checkoutDir);
@@ -291,15 +357,15 @@ export const applyEffectSourcePlan = Effect.fn("applyEffectSourcePlan")(function
 
     yield* runGit(plan.projectDir, [
       "clone",
-      "--depth",
-      "1",
+      "--quiet",
       "--branch",
       plan.tag,
       "--single-branch",
       "--",
-      plan.repository,
+      repositoryDir,
       staged,
     ]);
+    yield* runGit(staged, ["remote", "set-url", "origin", plan.repository]);
     if (yield* fs.exists(plan.checkoutDir)) {
       return yield* EffectSourceCheckoutError.make({
         message: `Effect source destination appeared while cloning: ${plan.checkoutDir}`,
@@ -316,7 +382,7 @@ export const applyEffectSourcePlan = Effect.fn("applyEffectSourcePlan")(function
     "1",
     "--force",
     "--quiet",
-    "origin",
+    repositoryDir,
     `refs/tags/${plan.tag}:refs/tags/${plan.tag}`,
   ]);
   const target = yield* runGit(plan.checkoutDir, [