@danieljvdm/dev-kit 0.15.0 → 0.16.0

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, [

package/src/global-cache.ts

@@ -0,0 +1,304 @@
+import {
+  Config,
+  DateTime,
+  Effect,
+  FileSystem,
+  Option,
+  Path,
+  Schema,
+  Stream,
+  type PlatformError,
+} from "effect";
+import { ChildProcess } from "effect/unstable/process";
+
+import { printStatus } from "./cli-ui.ts";
+
+export class GlobalCacheError extends Schema.TaggedError<GlobalCacheError>()("GlobalCacheError", {
+  message: Schema.String,
+}) {}
+
+/**
+ * Resolves the machine-global dev-kit cache directory. Entries stored here are
+ * keyed by immutable identifiers (resolved commit SHAs, repository URLs), so
+ * the cache is shared safely across projects and git worktrees. Populating it
+ * is not project state: locked verification and dry-run planning may write
+ * here without violating their read-only project semantics.
+ */
+export const resolveGlobalCacheDirectory = Effect.fn("resolveGlobalCacheDirectory")(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const override = yield* Config.string("DEV_KIT_CACHE_DIR").pipe(Config.withDefault(""));
+
+  if (override.length > 0) return path.resolve(override);
+  const xdgCacheHome = yield* Config.string("XDG_CACHE_HOME").pipe(Config.withDefault(""));
+
+  if (xdgCacheHome.length > 0 && path.isAbsolute(xdgCacheHome)) {
+    return path.join(xdgCacheHome, "dev-kit");
+  }
+  const home = yield* Config.string("HOME").pipe(
+    Config.orElse(() => Config.string("USERPROFILE")),
+    Config.withDefault(""),
+  );
+
+  if (home.length === 0 || !path.isAbsolute(home)) {
+    return yield* GlobalCacheError.make({
+      message: "cannot locate the dev-kit cache; set DEV_KIT_CACHE_DIR, XDG_CACHE_HOME, or HOME",
+    });
+  }
+  // The user cache convention differs per platform; an existing Library/Caches
+  // identifies macOS without reaching for Node platform APIs.
+  const macCaches = path.join(home, "Library", "Caches");
+
+  return (yield* fs.exists(macCaches))
+    ? path.join(macCaches, "dev-kit")
+    : path.join(home, ".cache", "dev-kit");
+});
+
+/**
+ * Publishes a fully staged cache entry at its immutable destination. The
+ * staged directory must live on the same filesystem so the rename is atomic;
+ * when a concurrent writer publishes the destination first, its entry wins and
+ * the staged copy is discarded.
+ */
+export const commitCacheDirectory = Effect.fn("commitCacheDirectory")(function* (
+  staged: string,
+  destination: string,
+  isPopulated: Effect.Effect<boolean, PlatformError.PlatformError>,
+) {
+  const fs = yield* FileSystem.FileSystem;
+
+  if ((yield* fs.exists(destination)) && !(yield* isPopulated)) {
+    yield* fs.remove(destination, { force: true, recursive: true });
+  }
+
+  yield* fs.rename(staged, destination).pipe(
+    Effect.catch((error) =>
+      Effect.gen(function* () {
+        if (!(yield* isPopulated)) return yield* error;
+
+        return yield* fs.remove(staged, { force: true, recursive: true });
+      }),
+    ),
+  );
+});
+
+export const CACHE_PRUNE_AGE_DAYS = 30;
+
+const DAY_MILLIS = 24 * 60 * 60 * 1000;
+const LAST_USED_STAMP = ".last-used";
+const TAG_USAGE_DIRECTORY = "dev-kit-tag-usage";
+
+const runGit = Effect.fn("runGlobalCacheGit")(function* (cwd: string, args: ReadonlyArray<string>) {
+  const child = yield* ChildProcess.make("git", args, {
+    cwd,
+    stderr: "pipe",
+    stdout: "pipe",
+  });
+  const [output, exitCode] = yield* Effect.all([
+    Stream.mkString(Stream.decodeText(child.all)),
+    child.exitCode,
+  ]);
+
+  if (exitCode !== 0) {
+    return yield* GlobalCacheError.make({
+      message: `git ${args.join(" ")} failed: ${output.trim()}`,
+    });
+  }
+
+  return output.trim();
+});
+
+const readMtimeMillis = Effect.fn("readCacheMtimeMillis")(function* (target: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const info = yield* fs.stat(target).pipe(Effect.catch(() => Effect.void));
+
+  if (info === undefined) return undefined;
+
+  return Option.match(info.mtime, {
+    onNone: () => undefined,
+    onSome: (mtime) => mtime.getTime(),
+  });
+});
+
+const listDirectory = Effect.fn("listCacheDirectory")(function* (directory: string) {
+  const fs = yield* FileSystem.FileSystem;
+
+  return (yield* fs.exists(directory)) ? yield* fs.readDirectory(directory) : [];
+});
+
+/** Best-effort recency stamp for a catalog cache entry; read by pruning. */
+export const stampCacheEntryUsage = Effect.fn("stampCacheEntryUsage")(function* (entryDir: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+
+  yield* fs.writeFileString(path.join(entryDir, LAST_USED_STAMP), "").pipe(Effect.ignore);
+});
+
+/**
+ * Best-effort recency stamp for one tag in a shared repository. Written before
+ * the tag is fetched so pruning never mistakes an in-flight fetch for an
+ * unused tag.
+ */
+export const stampTagUsage = Effect.fn("stampTagUsage")(function* (
+  repositoryDir: string,
+  tag: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const usageDir = path.join(repositoryDir, TAG_USAGE_DIRECTORY);
+
+  yield* fs
+    .makeDirectory(usageDir, { recursive: true })
+    .pipe(
+      Effect.andThen(fs.writeFileString(path.join(usageDir, encodeURIComponent(tag)), "")),
+      Effect.ignore,
+    );
+});
+
+export type GlobalCachePruneOptions = {
+  readonly all?: boolean;
+  readonly maxAgeDays?: number;
+};
+
+export type GlobalCachePruneSummary = {
+  readonly removedEntries: number;
+  readonly removedRepositories: number;
+  readonly removedTags: number;
+};
+
+/**
+ * Evicts cache content that no project on the machine has used recently.
+ * Everything here is regenerable, so eviction is always safe: a wrongly
+ * removed entry is simply fetched again on the next apply.
+ */
+export const pruneGlobalCache = Effect.fn("pruneGlobalCache")(function* (
+  options: GlobalCachePruneOptions = {},
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const cacheDir = yield* resolveGlobalCacheDirectory();
+  const catalogDir = path.join(cacheDir, "catalog");
+  const repositoriesDir = path.join(cacheDir, "effect-source");
+  let removedEntries = 0;
+  let removedRepositories = 0;
+  let removedTags = 0;
+
+  if (options.all === true) {
+    for (const id of yield* listDirectory(catalogDir)) {
+      removedEntries += (yield* listDirectory(path.join(catalogDir, id))).length;
+    }
+    removedRepositories = (yield* listDirectory(repositoriesDir)).length;
+    yield* fs.remove(catalogDir, { force: true, recursive: true });
+    yield* fs.remove(repositoriesDir, { force: true, recursive: true });
+
+    return { removedEntries, removedRepositories, removedTags } satisfies GlobalCachePruneSummary;
+  }
+  const now = DateTime.toEpochMillis(yield* DateTime.now);
+  const cutoff = now - (options.maxAgeDays ?? CACHE_PRUNE_AGE_DAYS) * DAY_MILLIS;
+
+  // Catalog entries and orphaned staging directories age out individually.
+  for (const id of yield* listDirectory(catalogDir)) {
+    const idDir = path.join(catalogDir, id);
+
+    for (const entry of yield* listDirectory(idDir)) {
+      const entryDir = path.join(idDir, entry);
+      const lastUsed =
+        (yield* readMtimeMillis(path.join(entryDir, LAST_USED_STAMP))) ??
+        (yield* readMtimeMillis(path.join(entryDir, ".ready"))) ??
+        (yield* readMtimeMillis(entryDir));
+
+      if (lastUsed !== undefined && lastUsed < cutoff) {
+        yield* fs.remove(entryDir, { force: true, recursive: true }).pipe(Effect.ignore);
+        removedEntries += 1;
+      }
+    }
+  }
+  // Shared repositories drop tags individually; a repository that no longer
+  // holds any tag is removed whole.
+  for (const name of yield* listDirectory(repositoriesDir)) {
+    const repositoryDir = path.join(repositoriesDir, name);
+
+    if (!(yield* fs.exists(path.join(repositoryDir, "HEAD")))) {
+      const mtime = yield* readMtimeMillis(repositoryDir);
+
+      if (mtime !== undefined && mtime < cutoff) {
+        yield* fs.remove(repositoryDir, { force: true, recursive: true }).pipe(Effect.ignore);
+        removedRepositories += 1;
+      }
+      continue;
+    }
+    const listed = yield* runGit(repositoryDir, ["tag", "--list"]).pipe(
+      Effect.catchTag("GlobalCacheError", () => Effect.void),
+    );
+
+    if (listed === undefined) {
+      // Unreadable repository: age it out by initialization time.
+      if (((yield* readMtimeMillis(path.join(repositoryDir, "HEAD"))) ?? 0) < cutoff) {
+        yield* fs.remove(repositoryDir, { force: true, recursive: true }).pipe(Effect.ignore);
+        removedRepositories += 1;
+      }
+      continue;
+    }
+    const tags = listed.split("\n").filter((tag) => tag.length > 0);
+    let kept = 0;
+    let deleted = 0;
+
+    for (const tag of tags) {
+      const stamp = path.join(repositoryDir, TAG_USAGE_DIRECTORY, encodeURIComponent(tag));
+
+      if (((yield* readMtimeMillis(stamp)) ?? 0) < cutoff) {
+        yield* runGit(repositoryDir, ["update-ref", "-d", `refs/tags/${tag}`]).pipe(Effect.ignore);
+        yield* fs.remove(stamp, { force: true }).pipe(Effect.ignore);
+        removedTags += 1;
+        deleted += 1;
+      } else {
+        kept += 1;
+      }
+    }
+    if (kept === 0) {
+      if (
+        deleted > 0 ||
+        ((yield* readMtimeMillis(path.join(repositoryDir, "HEAD"))) ?? 0) < cutoff
+      ) {
+        yield* fs.remove(repositoryDir, { force: true, recursive: true }).pipe(Effect.ignore);
+        removedRepositories += 1;
+      }
+    } else if (deleted > 0) {
+      yield* runGit(repositoryDir, ["gc", "--prune=now", "--quiet"]).pipe(Effect.ignore);
+    }
+  }
+
+  return { removedEntries, removedRepositories, removedTags } satisfies GlobalCachePruneSummary;
+});
+
+/**
+ * Opportunistic prune for the apply lifecycle: runs the age-based sweep at
+ * most once a day so routine applies stay fast.
+ */
+export const maybePruneGlobalCache = Effect.fn("maybePruneGlobalCache")(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const cacheDir = yield* resolveGlobalCacheDirectory();
+  const marker = path.join(cacheDir, ".last-pruned");
+  const lastPruned = yield* readMtimeMillis(marker);
+  const now = DateTime.toEpochMillis(yield* DateTime.now);
+
+  if (lastPruned !== undefined && now - lastPruned < DAY_MILLIS) return;
+  yield* fs.makeDirectory(cacheDir, { recursive: true });
+  yield* fs.writeFileString(marker, "");
+  yield* pruneGlobalCache();
+});
+
+export const runCachePrune = Effect.fn("runCachePrune")(function* (
+  options: GlobalCachePruneOptions = {},
+) {
+  const cacheDir = yield* resolveGlobalCacheDirectory();
+  const summary = yield* pruneGlobalCache(options);
+
+  yield* printStatus(
+    "success",
+    options.all === true ? "Cache cleared" : "Cache pruned",
+    `removed ${summary.removedEntries} catalog entries, ${summary.removedTags} tags, ` +
+      `${summary.removedRepositories} repositories from ${cacheDir}`,
+  );
+});

package/src/oxlint.js

@@ -8,6 +8,29 @@ import { devKitToolIgnorePatterns } from "./tool-ignore-patterns.js";
 
 export { devKitToolIgnorePatterns } from "./tool-ignore-patterns.js";
 
+export const createAbsoluteImportsOxlintOverride = (options) => {
+  if (options.files.length === 0) {
+    throw new Error("absolute imports enforcement requires at least one file glob");
+  }
+  const files = [...new Set(options.files)];
+
+  if (files.length !== options.files.length) {
+    throw new Error("absolute imports file globs must be unique");
+  }
+  for (const glob of files) {
+    if (glob.trim().length === 0) {
+      throw new Error("absolute imports file globs must not be blank");
+    }
+  }
+
+  return {
+    files,
+    rules: {
+      "import/no-relative-parent-imports": "error",
+    },
+  };
+};
+
 export const recommendedOxlintConfig = {
   ignorePatterns: [...devKitToolIgnorePatterns],
   options: {

package/src/oxlint.ts

@@ -1,9 +1,45 @@
-import type { OxlintConfig } from "oxlint";
+import type { OxlintConfig, OxlintOverride } from "oxlint";
 
 import { devKitToolIgnorePatterns } from "./tool-ignore-patterns.ts";
 
 export { devKitToolIgnorePatterns } from "./tool-ignore-patterns.ts";
 
+export type AbsoluteImportsOptions = {
+  /** Globs that must use path-alias imports, e.g. `"apps/app/src/**"`. */
+  readonly files: ReadonlyArray<string>;
+};
+
+/**
+ * Build an Oxlint override that forbids `../` imports inside the given globs,
+ * so those files import through tsconfig path aliases such as `@/*`. Append it
+ * to a standalone Oxlint config's `overrides`, or opt in through
+ * `createRecommendedVitePlusConfig({ absoluteImports })`.
+ */
+export const createAbsoluteImportsOxlintOverride = (
+  options: AbsoluteImportsOptions,
+): OxlintOverride => {
+  if (options.files.length === 0) {
+    throw new Error("absolute imports enforcement requires at least one file glob");
+  }
+  const files = [...new Set(options.files)];
+
+  if (files.length !== options.files.length) {
+    throw new Error("absolute imports file globs must be unique");
+  }
+  for (const glob of files) {
+    if (glob.trim().length === 0) {
+      throw new Error("absolute imports file globs must not be blank");
+    }
+  }
+
+  return {
+    files,
+    rules: {
+      "import/no-relative-parent-imports": "error",
+    },
+  };
+};
+
 /**
  * High-signal Oxlint defaults for TypeScript projects.
  *

package/src/project-package.ts

@@ -1,4 +1,4 @@
-import { Effect, FileSystem, Path, Schema } from "effect";
+import { Effect, FileSystem, Option, Path, Schema } from "effect";
 
 export class ProjectPackageError extends Schema.TaggedError<ProjectPackageError>()(
   "ProjectPackageError",
@@ -91,23 +91,87 @@ export const detectPackageManager = Effect.fn("detectPackageManager")(function*
   return detected.length === 1 ? detected[0] : undefined;
 });
 
-export const readDirectDependencyNames = Effect.fn("readDirectDependencyNames")(function* (
-  projectDir: string,
+const readOptionalProjectPackage = Effect.fn("readOptionalProjectPackage")(function* (
+  packageDir: string,
 ) {
-  const manifest = yield* readProjectPackage(projectDir).pipe(
+  return yield* readProjectPackage(packageDir).pipe(
     Effect.catchTag("ProjectPackageError", (error) =>
       error.message.startsWith("package.json not found:") ? Effect.void : Effect.fail(error),
     ),
   );
+});
+
+const manifestDependencyNames = (
+  manifest: (typeof ProjectPackageSchema)["Type"] | undefined | void,
+): ReadonlyArray<string> =>
+  manifest === undefined
+    ? []
+    : [
+        ...Object.keys(manifest.dependencies ?? {}),
+        ...Object.keys(manifest.devDependencies ?? {}),
+        ...Object.keys(manifest.optionalDependencies ?? {}),
+        ...Object.keys(manifest.peerDependencies ?? {}),
+      ];
+
+export const readDirectDependencyNames = Effect.fn("readDirectDependencyNames")(function* (
+  projectDir: string,
+) {
+  const manifest = yield* readOptionalProjectPackage(projectDir);
+
+  return [...new Set(manifestDependencyNames(manifest))].sort();
+});
+
+const WorkspacePatternsSchema = Schema.Union([
+  Schema.Array(Schema.String),
+  Schema.Struct({ packages: Schema.Array(Schema.String) }),
+]);
+// `workspaces` is declared `Schema.Unknown` in the project manifest schema, so
+// this is a genuinely untyped boundary.
+const decodeWorkspacePatterns = Schema.decodeUnknownOption(WorkspacePatternsSchema);
+
+const workspacePatterns = (workspaces: unknown): ReadonlyArray<string> => {
+  const decoded = decodeWorkspacePatterns(workspaces);
 
-  if (manifest === undefined) return [];
+  if (Option.isNone(decoded)) return [];
+
+  return "packages" in decoded.value ? decoded.value.packages : decoded.value;
+};
+
+/**
+ * Direct dependency names of the project package plus every workspace member
+ * package. Only literal workspace paths and single trailing-star globs
+ * (`apps/*`) are expanded; other patterns are skipped.
+ */
+export const readWorkspaceDependencyNames = Effect.fn("readWorkspaceDependencyNames")(function* (
+  projectDir: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const manifest = yield* readOptionalProjectPackage(projectDir);
+  const names = new Set(manifestDependencyNames(manifest));
+
+  for (const pattern of workspacePatterns(manifest?.workspaces)) {
+    if (pattern.startsWith("!")) continue;
+    const star = pattern.indexOf("*");
+    let memberDirs: ReadonlyArray<string> = [];
+
+    if (star === -1) {
+      memberDirs = [pattern];
+    } else if (pattern.endsWith("/*") && star === pattern.length - 1) {
+      const parent = path.join(projectDir, pattern.slice(0, -2));
+
+      if (yield* fs.exists(parent)) {
+        memberDirs = (yield* fs.readDirectory(parent)).map((name) =>
+          path.join(pattern.slice(0, -2), name),
+        );
+      }
+    }
+    for (const memberDir of memberDirs) {
+      const member = yield* readOptionalProjectPackage(path.join(projectDir, memberDir));
+
+      for (const name of manifestDependencyNames(member)) names.add(name);
+    }
+  }
 
-  return [
-    ...new Set([
-      ...Object.keys(manifest.dependencies ?? {}),
-      ...Object.keys(manifest.devDependencies ?? {}),
-      ...Object.keys(manifest.optionalDependencies ?? {}),
-      ...Object.keys(manifest.peerDependencies ?? {}),
-    ]),
-  ].sort();
+  return [...names].sort();
 });

package/src/sync.ts

@@ -15,6 +15,7 @@ import {
   planEffectTsgoPatch,
   type EffectTsgoPatchPlan,
 } from "./effect-tsgo.ts";
+import { maybePruneGlobalCache } from "./global-cache.ts";
 import { DevKitManifestSchema, normalizeManifest } from "./manifest.ts";
 import { observeSymbolicLink } from "./node-symbolic-link.ts";
 import { resolvePackageSkillSelector } from "./package-skill-source.ts";
@@ -29,6 +30,7 @@ import {
   detectPackageManager,
   PACKAGE_MANAGER_COMMANDS,
   readDirectDependencyNames,
+  readWorkspaceDependencyNames,
   readProjectPackage,
   type PackageManagerName,
 } from "./project-package.ts";
@@ -266,7 +268,13 @@ const encodePlanSnapshotJson = Schema.encodeSync(Schema.fromJsonString(Schema.Un
 const encodeAppliedStatePrettyJson = Schema.encodeSync(fromJsonString(AppliedStateSchema, 2));
 
 const SKILL_FAMILIES: SkillCatalog = {
-  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",
+  ],
 };
 
 export const DEFAULT_MANIFEST = "dev-kit.jsonc";
@@ -805,7 +813,7 @@ const renderAgentInstructions = Effect.fn("renderAgentInstructions")(function* (
           );
   const directDependencyNames = yield* readDirectDependencyNames(projectDir);
   const usesVitePlus = directDependencyNames.includes("vite-plus");
-  const effectInstructions =
+  const effectGuideInstructions =
     directDependencyNames.includes("effect") &&
     (yield* observePath(path.join(projectDir, "node_modules", "effect", "AGENTS.md"))).kind ===
       "file"
@@ -821,6 +829,20 @@ guide doesn't cover, search through the source code in \`node_modules/effect/src
 
 `
       : "";
+  const atomBoundaryInstructions = (yield* readWorkspaceDependencyNames(projectDir)).includes(
+    "@effect/atom-react",
+  )
+    ? `# Effect Atom client boundary
+
+This repository consumes APIs through Effect Atom clients (\`@effect/atom-react\`).
+Keep business logic in Effect: compose multi-step client workflows as atoms,
+declare cross-query invalidation as reactivity keys on mutations, and keep
+promise-mode dispatches at the React boundary logic-free — no \`.then\` chains
+in components or routes.
+
+`
+    : "";
+  const effectInstructions = `${effectGuideInstructions}${atomBoundaryInstructions}`;
   const projectPackage = yield* readProjectPackage(projectDir).pipe(
     Effect.catchTag("ProjectPackageError", (error) =>
       error.message.startsWith("package.json not found:") ? Effect.void : Effect.fail(error),
@@ -1877,6 +1899,18 @@ export const runProjectSkillPlan = Effect.fn("runProjectSkillPlan")(function* (
       yield* applyPlannedSkillChanges(replanned);
     }),
   );
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+
+  // Catalog checkouts moved to the machine-global cache; drop the regenerable
+  // project-local copies left behind by earlier dev-kit versions.
+  yield* fs
+    .remove(path.join(plan.projectDir, ".dev-kit", "cache", "catalog"), {
+      force: true,
+      recursive: true,
+    })
+    .pipe(Effect.ignore);
+  yield* maybePruneGlobalCache().pipe(Effect.ignore);
   yield* printStatus(
     "success",
     changes === 0 && !replanned.metadataChanged ? "Dev kit up to date" : "Dev kit ready",