feat(shared): add committed/ephemeral typegen cache path resolvers

Introduce getCommittedCacheDir() -> <cwd>/.appkit and
getEphemeralStateDir() -> <cwd>/node_modules/.databricks/appkit as the
single source of truth for typegen cache/state locations, co-located with
spawn-lock.ts and re-exported from the shared root barrel. Rewire
getSpawnLockPath to compose from getEphemeralStateDir (behavior-preserving,
same resolved path). Foundation for relocating the typegen cache out of
node_modules so it survives pnpm install on warehouse-less CI/CD.

xavier loop: iteration 1 -- Phase 1 (resolvers)

Co-authored-by: Isaac
Signed-off-by: Atila Fassina <atila@fassina.eu>

Author: atilafassina

packages/shared/src/cli/commands/cache-paths.test.ts

@@ -0,0 +1,28 @@
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, test } from "vitest";
+import { getCommittedCacheDir, getEphemeralStateDir } from "./cache-paths";
+
+describe("cache-paths", () => {
+  test("getCommittedCacheDir returns the .appkit directory under root", () => {
+    const root = path.join(os.tmpdir(), "some-project");
+    expect(getCommittedCacheDir(root)).toBe(path.join(root, ".appkit"));
+  });
+
+  test("getCommittedCacheDir defaults to process.cwd() when no argument is given", () => {
+    expect(getCommittedCacheDir()).toBe(path.join(process.cwd(), ".appkit"));
+  });
+
+  test("getEphemeralStateDir returns node_modules/.databricks/appkit under root", () => {
+    const root = path.join(os.tmpdir(), "some-project");
+    expect(getEphemeralStateDir(root)).toBe(
+      path.join(root, "node_modules", ".databricks", "appkit"),
+    );
+  });
+
+  test("getEphemeralStateDir defaults to process.cwd() when no argument is given", () => {
+    expect(getEphemeralStateDir()).toBe(
+      path.join(process.cwd(), "node_modules", ".databricks", "appkit"),
+    );
+  });
+});

packages/shared/src/cli/commands/cache-paths.ts

@@ -0,0 +1,25 @@
+import path from "node:path";
+
+/**
+ * Home for typegen COMMITTED caches (build inputs that must survive `pnpm
+ * install` and travel with the app in git). Per-app, anchored at the app root.
+ * The two caches (query/metric + serving) live here as `.appkit/*.json`.
+ *
+ * @param rootDir - project root. Defaults to the current working directory.
+ * @returns absolute path to the committed cache directory.
+ */
+export function getCommittedCacheDir(rootDir: string = process.cwd()): string {
+  return path.join(rootDir, ".appkit");
+}
+
+/**
+ * Home for typegen EPHEMERAL coordination state (worker spawn lock, ui-variant
+ * choices). Stays under `node_modules/` — gitignored, cleared on clean install.
+ * Never committed.
+ *
+ * @param rootDir - project root. Defaults to the current working directory.
+ * @returns absolute path to the ephemeral state directory.
+ */
+export function getEphemeralStateDir(rootDir: string = process.cwd()): string {
+  return path.join(rootDir, "node_modules", ".databricks", "appkit");
+}

packages/shared/src/cli/commands/spawn-lock.ts

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { getEphemeralStateDir } from "./cache-paths.js";
 
 /**
  * How long a spawn lock is considered fresh. A held lock newer than this means a
@@ -28,10 +29,7 @@ export const SPAWN_LOCK_STALE_MS = 6 * 60 * 1000;
  */
 export function getSpawnLockPath(rootDir: string): string {
   return path.join(
-    rootDir,
-    "node_modules",
-    ".databricks",
-    "appkit",
+    getEphemeralStateDir(rootDir),
     ".appkit-typegen-worker.lock",
   );
 }

packages/shared/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./agent";
 export * from "./cache";
+export * from "./cli/commands/cache-paths";
 export * from "./execute";
 export * from "./genie";
 export * from "./plugin";