@akanjs/devkit 3.0.0-alpha.10 → 3.0.0-alpha.101

package/frontendBuild/watchRootResolver.ts

@@ -1,7 +1,25 @@
 import fs from "node:fs";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import type { App } from "../commandDecorators";
 
+/**
+ * The directories one app's dev watcher follows, resolved from its tsconfig `paths`.
+ *
+ * Two aliases strip down to a workspace container rather than a package, and taking either verbatim puts
+ * code the app never imports under the watcher — where a save rebuilds, restarts and reloads it for
+ * nothing, and both builders rewrite the same generated barrels:
+ *
+ * - `@apps/*` becomes the `apps/` container. Apps are leaves of the workspace graph — never one another's
+ *   dependencies — so it is replaced by this app's own directory.
+ * - `@libs/*` becomes the `libs/` container. A lib is a dependency only if the app reaches it, so it is
+ *   replaced by the app's own lib dependencies, transitively. The set is resolved once, at watcher
+ *   install: a lib that becomes a dependency mid-session needs a fresh `akan start` anyway, because the
+ *   import that made it one also needs a `sync`.
+ *
+ * Failing to resolve that set keeps the container whole, because a wrong narrowing is a dev server that
+ * silently ignores edits.
+ */
 export class WatchRootResolver {
   #app: App;
 
@@ -11,6 +29,10 @@ export class WatchRootResolver {
 
   async resolve(): Promise<string[]> {
     const tsconfig = await this.#app.getTsConfig();
+    const appDir = path.resolve(this.#app.cwdPath);
+    const appsContainer = path.dirname(appDir);
+    const libsContainer = path.resolve(this.#app.workspace.workspaceRoot, "libs");
+    const libRoots = await this.#resolveLibRoots(libsContainer);
     const set = new Set<string>();
     set.add(path.resolve(`${this.#app.cwdPath}/page`));
     for (const targets of Object.values(tsconfig.compilerOptions.paths ?? {})) {
@@ -20,9 +42,52 @@ export class WatchRootResolver {
         // Strip the trailing filename and glob so we watch the package root dir.
         const cleaned = target.replace(/\/?\*+.*$/, "").replace(/\/[^/]+\.[^/]+$/, "");
         const resolved = path.resolve(this.#app.workspace.workspaceRoot, cleaned);
-        if (fs.existsSync(resolved)) set.add(resolved);
+        if (resolved === libsContainer && libRoots) {
+          for (const root of libRoots) set.add(root);
+          continue;
+        }
+        const root = resolved === appsContainer ? appDir : resolved;
+        if (fs.existsSync(root)) set.add(root);
       }
     }
     return [...set];
   }
+
+  async #resolveLibRoots(libsContainer: string): Promise<string[] | null> {
+    const libDeps = await this.#resolveLibDeps(libsContainer);
+    if (!libDeps) return null;
+    return libDeps.map((name) => path.join(libsContainer, name)).filter((dir) => fs.existsSync(dir));
+  }
+
+  async #resolveLibDeps(libsContainer: string): Promise<string[] | null> {
+    const scanInfo = this.#app.getScanInfo({ allowEmpty: true });
+    // Already transitive, and present whenever this runs in a process that scanned. The builder and the
+    // idle watcher run in processes that did not, so they take the manifests `scan` wrote instead.
+    if (scanInfo?.type === "app") return scanInfo.libDeps;
+    const direct = await WatchRootResolver.#readManifestLibDeps(path.join(this.#app.cwdPath, "akan.app.json"));
+    if (!direct) return null;
+    const closure = new Set<string>();
+    const queue = [...direct];
+    while (queue.length > 0) {
+      const name = queue.shift();
+      if (!name || closure.has(name)) continue;
+      closure.add(name);
+      const nested = await WatchRootResolver.#readManifestLibDeps(path.join(libsContainer, name, "akan.lib.json"));
+      // An unsynced lib's own dependencies are unknowable, so no root can be ruled out.
+      if (!nested) return null;
+      queue.push(...nested);
+    }
+    return [...closure];
+  }
+
+  static async #readManifestLibDeps(manifestPath: string): Promise<string[] | null> {
+    try {
+      const parsed = JSON.parse(await readFile(manifestPath, "utf8")) as { libDeps?: unknown };
+      if (!Array.isArray(parsed.libDeps)) return null;
+      return parsed.libDeps.filter((name): name is string => typeof name === "string" && name.length > 0);
+    } catch {
+      // Missing before the first sync, and unparseable while sync is mid-write.
+      return null;
+    }
+  }
 }

package/incrementalBuilder/devWatchBatch.test.ts

@@ -22,27 +22,25 @@ describe("prepareDevWatchBatch", () => {
     expect(prepared.event.devPlan?.files).toEqual(prepared.files);
   });
 
-  test.each([
-    "common",
-    "srvkit",
-    "ui",
-    "webkit",
-  ])("keeps %s facet add/delete generated index in the same generation", (facet) => {
-    const root = "/repo";
-    const changedFile = `${root}/libs/shared/${facet}/tmpExample.ts`;
-    const generatedIndex = `${root}/libs/shared/${facet}/index.ts`;
-    const prepared = prepareDevWatchBatch({
-      generation: 20,
-      batch: { files: [changedFile], kinds: new Set(["code"]) },
-      indexSync: { changedFiles: [generatedIndex], errors: [] },
-      changePlanner: new DevChangePlanner({ workspaceRoot: root }),
-    });
+  test.each(["common", "srvkit", "ui", "webkit"])(
+    "keeps %s facet add/delete generated index in the same generation",
+    (facet) => {
+      const root = "/repo";
+      const changedFile = `${root}/libs/shared/${facet}/tmpExample.ts`;
+      const generatedIndex = `${root}/libs/shared/${facet}/index.ts`;
+      const prepared = prepareDevWatchBatch({
+        generation: 20,
+        batch: { files: [changedFile], kinds: new Set(["code"]) },
+        indexSync: { changedFiles: [generatedIndex], errors: [] },
+        changePlanner: new DevChangePlanner({ workspaceRoot: root }),
+      });
 
-    expect(new Set(prepared.files)).toEqual(new Set([changedFile, generatedIndex]));
-    expect(prepared.event.devPlan?.generatedFiles).toEqual([generatedIndex]);
-    expect(prepared.event.devPlan?.roles).toContain("barrel");
-    expect(prepared.event.devPlan?.actions).toContain("sync-generated");
-  });
+      expect(new Set(prepared.files)).toEqual(new Set([changedFile, generatedIndex]));
+      expect(prepared.event.devPlan?.generatedFiles).toEqual([generatedIndex]);
+      expect(prepared.event.devPlan?.roles).toContain("barrel");
+      expect(prepared.event.devPlan?.actions).toContain("sync-generated");
+    },
+  );
 
   test("marks failed generated index sync as an error generation", () => {
     const root = "/repo";

package/incrementalBuilder/devWatchBatch.ts

@@ -1,4 +1,4 @@
-import type { BuilderEvent, ChangeBatch } from "akanjs/server";
+import type { BuilderEvent, ChangeBatch, DevChangePlan } from "akanjs/server";
 import type { DevChangePlanner, GeneratedIndexSyncResult } from "../frontendBuild";
 
 export interface PrepareDevWatchBatchOptions {
@@ -12,6 +12,8 @@ export interface PreparedDevWatchBatch {
   files: string[];
   kinds: ("code" | "css" | "config")[];
   expandedBatch: ChangeBatch;
+  /** The same plan the event carries, where `devPlan` is optional — read it here, not off the event. */
+  devPlan: DevChangePlan;
   event: Extract<BuilderEvent, { type: "invalidate" }>;
   hasSyncErrors: boolean;
 }
@@ -35,13 +37,15 @@ export const prepareDevWatchBatch = ({
   });
 
   if (indexSync.errors.length > 0 && !devPlan.actions.includes("report-error")) {
-    devPlan.actions = [...devPlan.actions, "report-error"].sort();
+    const withReport: DevChangePlan["actions"] = [...devPlan.actions, "report-error"];
+    devPlan.actions = withReport.sort();
   }
 
   return {
     files,
     kinds,
     expandedBatch,
+    devPlan,
     event: { type: "invalidate", kinds, files, generation, devPlan },
     hasSyncErrors: indexSync.errors.length > 0,
   };

package/incrementalBuilder/incrementalBuilder.host.ts

@@ -14,11 +14,25 @@ const builderMsgTypeSet = new Set<BuilderMessage["type"]>([
   "build-status",
   "builder-metrics",
 ]);
+/**
+ * Where a dev child process writes. `"pipe"` is not only about keeping a TUI's frame clean: a Bun child
+ * that inherits the controlling terminal snapshots its termios at spawn and writes that snapshot back
+ * when it exits, so a builder spawned while something holds the terminal raw turns it raw again on the
+ * first recycle. See the XXX comment on `Spinner.oraOptions`.
+ */
+export type DevStdioMode = "inherit" | "pipe";
+
 interface IncrementalBuilderHostOptions {
   app: App;
   entry: string;
   env: Record<string, string>;
+  stdio?: DevStdioMode;
   onMessage: (message: BuilderMessage) => void;
+  /**
+   * Required when `stdio` is `"pipe"`: an undrained pipe fills and blocks the builder's next write.
+   * Text arrives as decoded chunks, not lines — a consumer that needs lines splits them itself.
+   */
+  onOutput?: (kind: "stdout" | "stderr", text: string) => void;
 }
 
 /**
@@ -63,7 +77,9 @@ export class IncrementalBuilderHost {
   app: App;
   ready = false;
   readonly #onMessage: (message: BuilderMessage) => void;
-  #proc: Bun.Subprocess<"ignore", "inherit", "inherit"> | null = null;
+  readonly #stdio: DevStdioMode;
+  readonly #onOutput: ((kind: "stdout" | "stderr", text: string) => void) | null;
+  #proc: Bun.Subprocess<"ignore", "inherit" | "pipe", "inherit" | "pipe"> | null = null;
   #status: IncrementalBuilderStatus = "stopped";
   #restartAttempts = 0;
   #restartTimer: ReturnType<typeof setTimeout> | null = null;
@@ -83,11 +99,13 @@ export class IncrementalBuilderHost {
    */
   readonly #inFlight = new Map<number, "build-route" | "build-csr">();
   #startOptions: IncrementalBuilderStartOptions = {};
-  constructor({ app, entry, env, onMessage }: IncrementalBuilderHostOptions) {
+  constructor({ app, entry, env, stdio = "inherit", onMessage, onOutput }: IncrementalBuilderHostOptions) {
     this.app = app;
     this.entry = entry;
     this.env = env;
+    this.#stdio = stdio;
     this.#onMessage = onMessage;
+    this.#onOutput = onOutput ?? null;
   }
   get status() {
     return this.#status;
@@ -115,11 +133,11 @@ export class IncrementalBuilderHost {
     // the flag is what tells it to re-announce what it booted with.
     const afterRecycle = this.#spawnAfterRecycle;
     this.#spawnAfterRecycle = false;
-    let proc!: Bun.Subprocess<"ignore", "inherit", "inherit">;
+    let proc!: Bun.Subprocess<"ignore", "inherit" | "pipe", "inherit" | "pipe">;
     proc = Bun.spawn(["bun", this.entry], {
       cwd: this.app.cwdPath,
       env: { ...this.env, AKAN_WATCH: "1", ...(afterRecycle ? { AKAN_BUILDER_ANNOUNCE_BOOT: "1" } : {}) },
-      stdio: ["ignore", "inherit", "inherit"],
+      stdio: ["ignore", this.#stdio, this.#stdio],
       ipc: (msg: BuilderMessage) => {
         if (this.#proc !== proc) return;
         if (!msg || typeof msg !== "object") return;
@@ -167,8 +185,25 @@ export class IncrementalBuilderHost {
       },
     });
     this.#proc = proc;
+    // Re-attached per spawn, not once per host: a recycle or a crash-restart brings new pipes.
+    if (this.#stdio === "pipe" && this.#onOutput) {
+      void this.#drain(proc.stdout as unknown as ReadableStream<Uint8Array> | undefined, "stdout");
+      void this.#drain(proc.stderr as unknown as ReadableStream<Uint8Array> | undefined, "stderr");
+    }
     this.logger.verbose(`builder spawned pid=${proc.pid} entry=${this.entry}${isRestart ? " restart=1" : ""}`);
   }
+  async #drain(stream: ReadableStream<Uint8Array> | undefined | null, kind: "stdout" | "stderr") {
+    if (!stream) return;
+    const decoder = new TextDecoder();
+    try {
+      for await (const chunk of stream) {
+        const text = decoder.decode(chunk, { stream: true });
+        if (text) this.#onOutput?.(kind, text);
+      }
+    } catch {
+      // The stream closes when the builder exits; nothing further to surface here.
+    }
+  }
   #scheduleRestart() {
     if (this.#manualStop || this.#restartTimer) return;
     this.#status = "restarting";
@@ -200,7 +235,7 @@ export class IncrementalBuilderHost {
     // one at a time, into the dev error page a recycle is supposed to be invisible to. `ready` the
     // field is deliberately untouched: `onExit` reads it to tell a planned exit from a boot failure.
     this.#status = "recycling";
-    this.logger.info(`recycling builder pid=${proc.pid} (${reason})`);
+    this.logger.debug(`recycling builder pid=${proc.pid} (${reason})`);
     this.#recycleTimer = setTimeout(() => {
       this.#recycleTimer = null;
       if (this.#proc !== proc) return;
@@ -278,7 +313,15 @@ export class IncrementalBuilderHost {
     this.ready = false;
     this.#status = "stopped";
   }
-  static async create(app: App, env: Record<string, string>, onMessage: (message: BuilderMessage) => void) {
+  static async create(
+    app: App,
+    env: Record<string, string>,
+    onMessage: (message: BuilderMessage) => void,
+    {
+      stdio = "inherit",
+      onOutput,
+    }: { stdio?: DevStdioMode; onOutput?: (kind: "stdout" | "stderr", text: string) => void } = {},
+  ) {
     const candidates = [
       path.join(app.workspace.workspaceRoot, "pkgs/@akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts"),
       path.join(
@@ -289,7 +332,8 @@ export class IncrementalBuilderHost {
       path.join(import.meta.dir, "incrementalBuilder.proc.ts"),
     ];
     for (const c of candidates)
-      if (await Bun.file(c).exists()) return new IncrementalBuilderHost({ app, entry: c, env, onMessage });
+      if (await Bun.file(c).exists())
+        return new IncrementalBuilderHost({ app, entry: c, env, stdio, onMessage, onOutput });
     throw new Error(`[cli] frontend builder entry not found; looked in: ${candidates.join(", ")}`);
   }
 }

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 // barrel reaches `cssCompiler`/`ssrBaseArtifactBuilder`, which pull tailwindcss + @tailwindcss/node
 // (~40MB) into a process that then holds them for the whole dev session. Phase 2 moved css compilation
 // into the batch worker, so this process has no use for them — `entryModuleGraph.test.ts` keeps it that way.
+import { CodegenLock } from "@akanjs/devkit/codegenLock";
 import type { App } from "@akanjs/devkit/commandDecorators";
 import { AppExecutor, type PageRoot, WorkspaceExecutor } from "@akanjs/devkit/executors";
 import { AutoImportSync } from "@akanjs/devkit/frontendBuild/autoImportSync";
@@ -185,7 +186,12 @@ class IncrementalBuilder {
     if (this.#shuttingDown) return;
     this.#shuttingDown = true;
     const started = Date.now();
-    this.#logger.info(`shutdown requested (${reason}); draining ${this.#inFlight} work item(s)`);
+    this.#logger.debug(`shutdown requested (${reason}); draining ${this.#inFlight} work item(s)`);
+    // Stopped before the drain, or a save landing mid-drain would enqueue a batch behind the queue tail
+    // this method already awaited — and `process.exit(0)` would cut that batch off partway through
+    // writing its artifacts. The replacement rebuilds every artifact from its boot build anyway, so the
+    // batch is not lost; a half-written one would be.
+    this.#watcher?.stop();
     if (this.#cssRebuildTimer) {
       // Only reachable if a css batch landed between the idle report and this request: the fresh
       // boot build recompiles css from scratch anyway, so dropping the debounce loses nothing.
@@ -200,7 +206,7 @@ class IncrementalBuilder {
     // flushed — a `css-updated` relayed milliseconds before this line would be dropped with no error
     // anywhere, leaving the backend serving the previous bundle. See `BuilderChannel`.
     const flushed = await BuilderChannel.drain();
-    this.#logger.info(
+    this.#logger.debug(
       `drained in ${Date.now() - started}ms${flushed ? ` after flushing ${flushed} ipc write(s)` : ""}; exiting for recycle`,
     );
     process.exit(0);
@@ -294,22 +300,27 @@ class IncrementalBuilder {
     //* Insert framework imports that are used but omitted (e.g. `Int` in *.constant.ts, `fetch` in
     //* *.store.ts) before regenerating barrels. Edits land on files already in this batch, so they
     //* rebuild in this same generation; the write is idempotent so it does not re-trigger the watcher.
-    const autoImport = await this.#autoImportSync.syncForBatch(batch.files);
+    const [autoImport, indexSync] = await CodegenLock.run(
+      this.#app.workspace.workspaceRoot,
+      `hmr-batch:${this.#app.name}`,
+      async () => {
+        const auto = await this.#autoImportSync.syncForBatch(batch.files);
+        return [auto, await this.#generatedIndexSync.syncForBatch(batch.files)] as const;
+      },
+    );
     for (const error of autoImport.errors) this.#logger.error(error);
     if (autoImport.changedFiles.length > 0)
       this.#logger.verbose(`[auto-import] inserted imports into ${autoImport.changedFiles.length} file(s)`);
-    const indexSync = await this.#generatedIndexSync.syncForBatch(batch.files);
     //* Both passes above write source files, and this generation's build consumes what they wrote. Hand
     //* them to the watcher so its verification scan does not read them back as a user edit and spend a
     //* second generation rebuilding identical content.
     await this.#watcher?.absorb([...autoImport.changedFiles, ...indexSync.changedFiles]);
-    const { files, kinds, expandedBatch, event, hasSyncErrors } = prepareDevWatchBatch({
+    const { files, kinds, expandedBatch, devPlan, event, hasSyncErrors } = prepareDevWatchBatch({
       generation,
       batch,
       indexSync,
       changePlanner: this.#changePlanner,
     });
-    const devPlan = event.devPlan;
     this.#logger.verbose(
       `[hmr] batch generation=${generation} kinds=${kinds.join(",")} files=${files.length} generated=${indexSync.changedFiles.length} roles=${devPlan.roles.join(",") || "(none)"} actions=${devPlan.actions.join(",") || "(none)"}`,
     );

package/index.ts

@@ -22,19 +22,15 @@ export type * from "./applicationBuildRunner";
 export type * from "./applicationReleasePackager";
 export type * from "./applicationTestPreload";
 export type * from "./artifact";
-export type * from "./builder";
 export type * from "./capacitorApp";
 export type * from "./cloud";
 export type * from "./commandDecorators";
 export type * from "./createTunnel";
 export type * from "./dependencyScanner";
 export type * from "./executors";
-export type * from "./extractDeps";
 export type * from "./fileSys";
 export type * from "./frontendBuild";
-export type * from "./getCredentials";
 export type * from "./getDirname";
-export type * from "./getModelFileData";
 export type * from "./getRelatedCnsts";
 export type * from "./guideline";
 export type * from "./incrementalBuilder";
@@ -46,11 +42,8 @@ export type * from "./recipeScanner";
 export type * from "./scanInfo";
 export type * from "./selectModel";
 export type * from "./spinner";
-export type * from "./streamAi";
 export type * from "./transforms";
 export type * from "./typeChecker";
 export type * from "./types";
-export type * from "./ui";
 export type * from "./uploadRelease";
-export type * from "./useStdoutDimensions";
 export type * from "./workflow";

package/integration/devStabilityHarness.ts

@@ -118,20 +118,12 @@ export default config;
       ),
       this.writeFile(
         "env/env.client.ts",
-        `import { getEnv } from "akanjs/base";
-
-export const env = {
-  ...getEnv(),
-} as const;
+        `export const env = {} as const;
 `,
       ),
       this.writeFile(
         "env/env.server.ts",
-        `import { getEnv } from "akanjs/base";
-
-export const env = {
-  ...getEnv(),
-} as const;
+        `export const env = {} as const;
 `,
       ),
       this.writeFile(

package/libSource.test.ts

@@ -0,0 +1,112 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Executor, LibExecutor, WorkspaceExecutor } from "./executors";
+import { formatLibStatuses, LibSource } from "./libSource";
+
+const tempRoots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+const write = async (filePath: string, content: string) => {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, content);
+};
+
+// `LibExecutor.from` memoises by name, so each fixture needs a name no other test has used.
+const makeLib = async (libName: string) => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-libsource-"));
+  tempRoots.push(root);
+  await write(
+    path.join(root, "package.json"),
+    '{ "name": "workspace", "version": "0.0.1", "description": "workspace" }\n',
+  );
+  await write(path.join(root, ".gitignore"), "node_modules\n");
+  await write(path.join(root, `libs/${libName}/package.json`), `{ "name": "@${libName}", "version": "0.0.1" }\n`);
+  await write(path.join(root, `libs/${libName}/common/helper.ts`), "export const helper = 1;\n");
+  await write(path.join(root, `libs/${libName}/env/env.server.testing.ts`), "export const env = { key: 1 };\n");
+
+  const git = new Executor("fixture", root);
+  await git.spawn("git", ["init", "--quiet"]);
+
+  const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: `workspace-${libName}` });
+  const lib = LibExecutor.from(workspace, libName);
+  return { root, lib, source: new LibSource(lib) };
+};
+
+describe("LibSource", () => {
+  test("reports an unstamped library", async () => {
+    const { source } = await makeLib("plain-lib");
+    const status = await source.status();
+
+    expect(status.drift).toBe("unstamped");
+    expect(status.stamp).toBeNull();
+    expect(status.hash).toMatch(/^[0-9a-f]{32}$/);
+  });
+
+  test("stamps the origin into package.json and reads back clean", async () => {
+    const { lib, source } = await makeLib("stamped-lib");
+    const stamp = await source.write({ origin: "akanjs", sha: "3.0.0" });
+
+    expect(stamp.origin).toBe("akanjs");
+    expect(await source.read()).toEqual(stamp);
+    expect((await source.status()).drift).toBe("clean");
+
+    const manifest = await lib.getPackageJson();
+    expect(manifest.name).toBe("@stamped-lib");
+    expect((manifest.akan as { source: { sha: string } }).source.sha).toBe("3.0.0");
+  });
+
+  test("detects an edit to library source as drift", async () => {
+    const { root, source } = await makeLib("drift-lib");
+    await source.write({ origin: "akanjs", sha: "3.0.0" });
+    await write(path.join(root, "libs/drift-lib/common/helper.ts"), "export const helper = 2;\n");
+
+    expect((await source.status()).drift).toBe("drifted");
+  });
+
+  test("survives every other akan write to the manifest", async () => {
+    const { lib, source } = await makeLib("merge-lib");
+    const stamp = await source.write({ origin: "akanjs", sha: "3.0.0" });
+    const manifest = await lib.getPackageJson();
+    await lib.setPackageJson({ ...manifest, dependencies: { lodash: "4.0.0" } });
+
+    expect(await source.read()).toEqual(stamp);
+    expect((await source.status()).drift).toBe("drifted");
+  });
+
+  test("leaves env values out of the hash — they belong to the installing workspace", async () => {
+    const { root, source } = await makeLib("env-lib");
+    await source.write({ origin: "akanjs", sha: "3.0.0" });
+    await write(path.join(root, "libs/env-lib/env/env.server.testing.ts"), "export const env = { key: 999 };\n");
+
+    expect((await source.status()).drift).toBe("clean");
+  });
+});
+
+describe("formatLibStatuses", () => {
+  test("marks drifted libraries and counts them", () => {
+    const text = formatLibStatuses([
+      {
+        lib: "util",
+        drift: "clean",
+        hash: "a".repeat(32),
+        stamp: { origin: "akanjs", sha: "3.0.0", hash: "a".repeat(32), syncedAt: "now" },
+      },
+      {
+        lib: "shared",
+        drift: "drifted",
+        hash: "b".repeat(32),
+        stamp: { origin: "akanjs", sha: "3.0.0", hash: "a".repeat(32), syncedAt: "now" },
+      },
+      { lib: "local", drift: "unstamped", hash: "c".repeat(32), stamp: null },
+    ]);
+
+    expect(text).toContain("DRIFTED   libs/shared  akanjs@3.0.0");
+    expect(text).toContain("unstamped libs/local  no akan.source in package.json");
+    expect(text).toContain("drifted: 1 / 3");
+  });
+});

package/libSource.ts

@@ -0,0 +1,126 @@
+import type { LibExecutor } from "./executors";
+import type { PackageJson } from "./types";
+
+export interface LibSourceStamp {
+  /** Where the copy came from: a git remote URL, or `akanjs` for the published package. */
+  origin: string;
+  /** The origin's commit sha, or the package version when the origin is a registry. */
+  sha: string;
+  /** Content hash of the library as installed, so a later edit is detectable without the origin. */
+  hash: string;
+  syncedAt: string;
+}
+
+export type LibDrift = "clean" | "drifted" | "unstamped";
+
+export interface LibStatus {
+  lib: string;
+  drift: LibDrift;
+  stamp: LibSourceStamp | null;
+  hash: string;
+}
+
+/**
+ * A library's origin, recorded in its own `package.json` under an `akan.source` key.
+ *
+ * The key rides `package.json` rather than a file of its own because every akan write to a library's
+ * manifest is a spread of the existing object (`LibExecutor.syncPackageJson`), so an unknown top-level
+ * key survives — while a new root file would have to be added to `libRootAllowedFiles` before
+ * `akan sync` stopped rejecting it.
+ */
+export class LibSource {
+  static readonly manifestKey = "akan";
+  /**
+   * Left out of the hash. `env/` holds per-deployment values that belong to the workspace the library
+   * was installed into, not to the origin, so an env edit is not drift.
+   */
+  static readonly unhashedDirs = ["env"];
+
+  #lib: LibExecutor;
+  constructor(lib: LibExecutor) {
+    this.#lib = lib;
+  }
+
+  get #prefix() {
+    return `libs/${this.#lib.name}/`;
+  }
+
+  #isHashed(file: string) {
+    const relative = file.slice(this.#prefix.length);
+    return !LibSource.unhashedDirs.includes(relative.split("/")[0] ?? "");
+  }
+
+  /** `package.json` cannot hash the stamp it carries, so the key comes off before hashing. */
+  async #hashableContent(file: string) {
+    const content = await this.#lib.workspace.readFile(file);
+    if (file !== `${this.#prefix}package.json`) return content;
+    const manifest = JSON.parse(content) as PackageJson;
+    delete manifest[LibSource.manifestKey];
+    return JSON.stringify(manifest);
+  }
+
+  /**
+   * Hash over the library's own files. Untracked files count: a freshly copied library is not committed
+   * yet, and its hash has to be the same one a later `status` recomputes.
+   */
+  async computeHash() {
+    const files = (await this.#lib.workspace.listGitFiles([`libs/${this.#lib.name}`], { untracked: true })).filter(
+      (file) => this.#isHashed(file),
+    );
+    const hasher = new Bun.CryptoHasher("sha256");
+    for (const file of files) {
+      hasher.update(file);
+      hasher.update("\0");
+      hasher.update(await this.#hashableContent(file));
+      hasher.update("\0");
+    }
+    return hasher.digest("hex").slice(0, 32);
+  }
+
+  async read(): Promise<LibSourceStamp | null> {
+    const manifest = await this.#lib.getPackageJson();
+    const akan = manifest[LibSource.manifestKey] as { source?: LibSourceStamp } | undefined;
+    return akan?.source ?? null;
+  }
+
+  async write({ origin, sha }: Pick<LibSourceStamp, "origin" | "sha">) {
+    const [manifest, hash] = await Promise.all([this.#lib.getPackageJson(), this.computeHash()]);
+    const akan = (manifest[LibSource.manifestKey] ?? {}) as Record<string, unknown>;
+    const stamp: LibSourceStamp = { origin, sha, hash, syncedAt: new Date().toISOString() };
+    await this.#lib.setPackageJson({ ...manifest, [LibSource.manifestKey]: { ...akan, source: stamp } });
+    return stamp;
+  }
+
+  /**
+   * Writes the stamp only when it would change. `syncedAt` moves on every write, so an unconditional
+   * write leaves the manifest dirty and defeats an idempotent caller — the hash is computed with the
+   * stamp removed, so comparing it first is sound.
+   */
+  async syncStamp({ origin, sha }: Pick<LibSourceStamp, "origin" | "sha">) {
+    const [current, hash] = await Promise.all([this.read(), this.computeHash()]);
+    if (current?.origin === origin && current.sha === sha && current.hash === hash)
+      return { stamp: current, changed: false };
+    return { stamp: await this.write({ origin, sha }), changed: true };
+  }
+
+  async status(): Promise<LibStatus> {
+    const [stamp, hash] = await Promise.all([this.read(), this.computeHash()]);
+    const drift = !stamp ? "unstamped" : stamp.hash === hash ? "clean" : "drifted";
+    return { lib: this.#lib.name, drift, stamp, hash };
+  }
+}
+
+export function formatLibStatuses(statuses: LibStatus[]) {
+  const marks = { clean: "clean    ", drifted: "DRIFTED  ", unstamped: "unstamped" } as const;
+  const sections = [
+    "Akan Library Source Status",
+    "",
+    ...statuses.map((status) => {
+      const origin = status.stamp ? `${status.stamp.origin}@${status.stamp.sha}` : "no akan.source in package.json";
+      return `  ${marks[status.drift]} libs/${status.lib}  ${origin}`;
+    }),
+    "",
+    `drifted: ${statuses.filter((status) => status.drift === "drifted").length} / ${statuses.length}`,
+  ];
+  return sections.join("\n");
+}