@danieljvdm/dev-kit 0.15.0 → 0.17.0

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

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.
  *