fix(appkit): keep node: cache-path resolver out of the client-safe shared barrel

CI surfaced two failures from routing the cache-path resolvers through the
shared root barrel:

1. Docs Build (+ PR Template): the root barrel `shared/src/index.ts` is
   client-safe (docs webpack aliases shared->src and pulls it via appkit-ui),
   but cache-paths imports `node:path`, so the docs client bundle died with
   UnhandledSchemeError. Move the resolvers off the root barrel onto a
   Node-only subpath and import them there from appkit's cache/serving/
   choice-sink modules. tsdown owns shared's generated `exports` (devExports),
   so the subpath is added as a tsdown entry and keyed by its src-relative
   path: `shared/cli/commands/cache-paths`.

2. Unit Tests: the new bootstrap-vs-drift message assertions matched raw text,
   but picocolors emits ANSI codes when CI is set, splitting the strings. Strip
   ANSI (incl. the ESC byte) before matching. Also repoint the cache
   serialization test's `vi.mock` to the new subpath specifier.

Verified with the gates CI runs: `CI=true pnpm test` (3725 pass), `pnpm
docs:build` (client compiles, no node: error), typecheck, build, check, knip.

xavier loop: iteration 6 -- CI fixes (docs node: leak + ANSI-brittle tests)

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

Author: atilafassina

packages/appkit/src/plugins/ui-variants/choice-sink.ts

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { getEphemeralStateDir } from "shared";
+import { getEphemeralStateDir } from "shared/cli/commands/cache-paths";
 
 /**
  * Filename of the JSONL choices file. The agent skill discovers this file at

packages/appkit/src/type-generator/cache.ts

@@ -1,7 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { getCommittedCacheDir } from "shared";
+import { getCommittedCacheDir } from "shared/cli/commands/cache-paths";
 import { createLogger } from "../logging/logger";
 import type { MetricSchema } from "./mv-registry/types";
 

packages/appkit/src/type-generator/serving/cache.ts

@@ -1,7 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { getCommittedCacheDir } from "shared";
+import { getCommittedCacheDir } from "shared/cli/commands/cache-paths";
 import { createLogger } from "../../logging/logger";
 
 const logger = createLogger("type-generator:serving:cache");

packages/appkit/src/type-generator/tests/cache-serialization.test.ts

@@ -14,8 +14,11 @@ vi.mock("node:fs/promises", () => ({
   },
 }));
 
-// Mock getCommittedCacheDir to return a consistent test path
-vi.mock("shared", () => ({
+// Mock getCommittedCacheDir to return a consistent test path.
+// cache.ts imports it from the Node-only "shared/cli/commands/cache-paths"
+// subpath (kept out of the client-safe "shared" root barrel), so the mock must
+// target that exact specifier.
+vi.mock("shared/cli/commands/cache-paths", () => ({
   getCommittedCacheDir: () => "/test/app/.appkit",
 }));
 

packages/appkit/src/type-generator/tests/index.test.ts

@@ -11,6 +11,12 @@ import {
 } from "vitest";
 import type { DatabricksStatementExecutionResponse } from "../types";
 
+// picocolors emits ANSI color codes when CI is set; strip them (ESC + the
+// bracketed SGR sequence) so message-content assertions match regardless of
+// the color environment.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching the ESC (\x1b) byte is the point.
+const stripAnsi = (s: string): string => s.replace(/\x1b\[[0-9;]*m/g, "");
+
 const mocks = vi.hoisted(() => ({
   generateQueriesFromDescribe: vi.fn(),
   getWarehouseState: vi.fn(),
@@ -304,11 +310,12 @@ describe("generateFromEntryPoint — query failure handling", () => {
       expect(err).toBeInstanceOf(TypegenFatalError);
       // This is the critical assertion: the message must reflect the state
       // BEFORE generation, not after (when the cache file now exists).
-      expect((err as Error).message).toMatch(/No committed type cache found/i);
-      expect((err as Error).message).toMatch(/generate-types --wait/i);
-      expect((err as Error).message).toMatch(/commit \.appkit\//i);
+      const message = stripAnsi((err as Error).message);
+      expect(message).toMatch(/No committed type cache found/i);
+      expect(message).toMatch(/generate-types --wait/i);
+      expect(message).toMatch(/commit \.appkit\//i);
       // Must NOT say "missing or stale" (the drift message):
-      expect((err as Error).message).not.toMatch(/missing or stale/i);
+      expect(message).not.toMatch(/missing or stale/i);
     }
   });
 
@@ -334,13 +341,12 @@ describe("generateFromEntryPoint — query failure handling", () => {
     } catch (err) {
       expect(err).toBeInstanceOf(TypegenFatalError);
       // Cache existed at start → report drift (stale/missing key).
-      expect((err as Error).message).toMatch(/missing or stale/i);
-      expect((err as Error).message).toMatch(/Regenerate with/i);
-      expect((err as Error).message).toMatch(/generate-types --wait/i);
+      const message = stripAnsi((err as Error).message);
+      expect(message).toMatch(/missing or stale/i);
+      expect(message).toMatch(/Regenerate with/i);
+      expect(message).toMatch(/generate-types --wait/i);
       // Must NOT say "No committed type cache found" (the bootstrap message):
-      expect((err as Error).message).not.toMatch(
-        /No committed type cache found/i,
-      );
+      expect(message).not.toMatch(/No committed type cache found/i);
     }
   });
 });

packages/appkit/tsconfig.json

@@ -7,6 +7,9 @@
       "@/*": ["src/*"],
       "@tools/*": ["../../tools/*"],
       "shared": ["../../packages/shared/src"],
+      "shared/cli/commands/cache-paths": [
+        "../../packages/shared/src/cli/commands/cache-paths"
+      ],
       "@databricks/lakebase": ["../../packages/lakebase/src"]
     }
   },

packages/shared/package.json

@@ -15,6 +15,10 @@
       "development": "./src/cli/index.ts",
       "default": "./dist/cli/index.js"
     },
+    "./cli/commands/cache-paths": {
+      "development": "./src/cli/commands/cache-paths.ts",
+      "default": "./dist/cli/commands/cache-paths.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -35,6 +39,7 @@
     "exports": {
       ".": "./dist/index.js",
       "./cli": "./dist/cli/index.js",
+      "./cli/commands/cache-paths": "./dist/cli/commands/cache-paths.js",
       "./package.json": "./package.json"
     }
   },

packages/shared/src/index.ts

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

packages/shared/tsdown.config.ts

@@ -2,7 +2,15 @@ import { defineConfig } from "tsdown";
 
 export default defineConfig({
   name: "shared",
-  entry: ["src/index.ts", "src/cli/index.ts"],
+  entry: [
+    "src/index.ts",
+    "src/cli/index.ts",
+    // Node-only path resolvers, exposed as the "shared/cache-paths" subpath so
+    // appkit can import them without pulling node: builtins into the
+    // client-safe root barrel. Must be a tsdown entry or the exports plugin
+    // (exports.devExports below) drops the "./cache-paths" export on rebuild.
+    "src/cli/commands/cache-paths.ts",
+  ],
   outDir: "dist",
   minify: false,
   format: "esm",

tsconfig.json

@@ -16,6 +16,9 @@
       "@databricks/appkit": ["packages/appkit/*"],
       "@databricks/appkit-ui": ["packages/appkit-ui/*"],
       "shared": ["packages/shared/src"],
+      "shared/cli/commands/cache-paths": [
+        "packages/shared/src/cli/commands/cache-paths"
+      ],
       "@tools/*": ["tools/*"]
     }
   },