@akanjs/devkit 3.0.2 → 3.1.0-rc.0

package/pipeline/index.ts

@@ -0,0 +1,4 @@
+export * from "./PipelineCompiler";
+export * from "./PipelineDefinition";
+export * from "./PipelineDryRun";
+export * from "./PipelineInputReader";

package/qualityScanner.test.ts

@@ -233,17 +233,23 @@ describe("AkanQualityScanner layout rules", () => {
     expect(warnings[0]?.fix).toContain("akan sync");
   });
 
-  test("keeps a root signal test out of the lib facet rule", async () => {
+  test("flags a test at the lib root and points it at its module folder or srvkit", async () => {
     const root = await makeWorkspace({
       "libs/demo/lib/cnst.ts": "export const cnst = 1;\n",
       "libs/demo/lib/user.signal.test.ts": "export const test = 1;\n",
+      "libs/demo/lib/user/user.signal.test.ts": "export const test = 1;\n",
       "libs/demo/lib/helper.ts": "export const helper = 1;\n",
     });
 
     const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.layout.lib-facet-file");
 
-    expect(warnings).toHaveLength(1);
-    expect(warnings[0]?.file).toBe("libs/demo/lib/helper.ts");
+    expect(warnings.map((warning) => warning.file).sort()).toEqual([
+      "libs/demo/lib/helper.ts",
+      "libs/demo/lib/user.signal.test.ts",
+    ]);
+    const rootTest = warnings.find((warning) => warning.file === "libs/demo/lib/user.signal.test.ts");
+    expect(rootTest?.message).toContain("lib/<model>/<model>.signal.test.ts");
+    expect(rootTest?.message).toContain("srvkit/");
   });
 });
 

package/qualityScanner.ts

@@ -10,6 +10,7 @@ import { fileWarning, formatSsrBalance, type SsrBalanceEntry, SsrScanner } from
 import {
   facetIndexShadowOf,
   isAllowedLibFacetRootFile,
+  libFacetRootHintOf,
   rootAllowedDirs,
   rootAllowedFiles,
   rootEntryHintOf,
@@ -145,7 +146,7 @@ const RULE_FIXES: Record<string, string> = {
   "akan.layout.lib-root-folder":
     "Move the folder's contents into a conventional lib folder (common, env, lib, page, private, public, srvkit, ui, or webkit) and delete it.",
   "akan.layout.lib-facet-file":
-    "Move the file into a domain module folder under lib/; keep the lib facet root limited to generated support facets.",
+    "Move the file into a domain module folder under lib/ (a test beside the file it covers, or into srvkit/ when it drives several modules); keep the lib facet root limited to generated support facets.",
   "akan.layout.facet-index-shadow":
     "Delete the hand-written index file and run akan sync; move a namespace it builds into <facet>/<Folder>/index.tsx.",
   "akan.layout.module-ui-file":
@@ -460,7 +461,9 @@ export class AkanQualityScanner {
           "akan.layout.lib-facet-file",
           "layout",
           sourceFile.file,
-          `Unexpected lib facet root file "${libFacetFile}". Keep direct lib/ root files limited to generated support facets.`,
+          `Unexpected lib facet root file "${libFacetFile}". ${
+            libFacetRootHintOf(libFacetFile) ?? "Keep direct lib/ root files limited to generated support facets."
+          }`,
         ),
       );
 

package/scanInfo.ts

@@ -14,6 +14,9 @@ import {
   barrelFacetDirs,
   facetIndexShadowOf,
   isAllowedLibFacetRootFile,
+  libFacetRootHintOf,
+  moduleTestHint,
+  moduleTestTargetOf,
   rootAllowedDirs,
   rootAllowedFiles,
   rootEntryHintOf,
@@ -93,7 +96,7 @@ async function assertScanConvention(exec: AppExecutor | LibExecutor, libRoot: {
 
   for (const filename of libRoot.files)
     if (!isAllowedLibFacetRootFile(filename))
-      addViolation(path.join("lib", filename), "unsupported lib facet root file");
+      addViolation(path.join("lib", filename), libFacetRootHintOf(filename) ?? "unsupported lib facet root file");
   for (const dirname of libRoot.dirs)
     if (dirname.startsWith("__") && !internalLibDirs.has(dirname))
       addViolation(path.join("lib", dirname), "unsupported internal lib folder");
@@ -133,12 +136,14 @@ async function validateModuleFiles(
 
   for (const filename of files) {
     const scanPath = getScanPath(exec, path.join(modulePath, filename));
-    if (filename === "index.ts" || filename === "index.tsx" || /\.(test|spec)\.(ts|tsx)$/.test(filename)) continue;
+    if (filename === "index.ts" || filename === "index.tsx") continue;
     if (filename === `${moduleName}.abstract.md`) continue;
-    const uiMatch = filename.match(/^([A-Z][A-Za-z0-9]+)\.([A-Z][A-Za-z0-9]*)\.tsx$/);
-    const match = uiMatch ?? filename.match(/^([a-z][a-zA-Z0-9]*)\.([a-z][a-z0-9]*)\.ts$/);
+    const testTarget = moduleTestTargetOf(filename);
+    const sourceName = testTarget ?? filename;
+    const uiMatch = sourceName.match(/^([A-Z][A-Za-z0-9]+)\.([A-Z][A-Za-z0-9]*)\.tsx$/);
+    const match = uiMatch ?? sourceName.match(/^([a-z][a-zA-Z0-9]*)\.([a-z][a-z0-9]*)\.ts$/);
     if (!match) {
-      violations.push(`${scanPath}: unsupported module file`);
+      violations.push(`${scanPath}: ${testTarget ? moduleTestHint : "unsupported module file"}`);
       continue;
     }
     const [, fileModuleName, fileType] = match;
@@ -146,7 +151,9 @@ async function validateModuleFiles(
     if (fileModuleName !== expectedName)
       violations.push(`${scanPath}: module name mismatch: expected '${expectedName}', got '${fileModuleName}'`);
     if (!(uiMatch ? moduleUiFileTypes : moduleNonUiFileTypes)[kind].has(fileType))
-      violations.push(`${scanPath}: unsupported ${kind}${uiMatch ? " UI" : ""} file`);
+      violations.push(
+        `${scanPath}: ${testTarget ? moduleTestHint : `unsupported ${kind}${uiMatch ? " UI" : ""} file`}`,
+      );
   }
 }
 

package/subspace.test.ts

@@ -3,7 +3,13 @@ import { mkdir, readdir, rm } from "node:fs/promises";
 import path from "node:path";
 import { Executor, WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
-import { formatSubspaceDiff, formatSubspacePushResults, formatSubspaceStatuses, Subspace } from "./subspace";
+import {
+  formatSubspaceDiff,
+  formatSubspacePlan,
+  formatSubspacePushResults,
+  formatSubspaceStatuses,
+  Subspace,
+} from "./subspace";
 import { SubspaceConfig } from "./subspaceConfig";
 import { isolateEnv, tempDirs, writeText as write } from "./testHelpers";
 
@@ -88,9 +94,10 @@ const makeMirror = async (servedApp: string, privateApp: string, libName: string
   );
   await write(path.join(wsRoot, "benchmarks/bench.ts"), "export {};\n");
   await write(
-    path.join(wsRoot, "akan.subspace.ts"),
-    `export default { pushableBranches: ["develop"], exclude: ["benchmarks"], subspaces: [{ name: "acme", repo: ${JSON.stringify(bareRoot)}, apps: ["${servedApp}"] }] };\n`,
+    path.join(wsRoot, "akan.config.ts"),
+    `export default { subspace: { pushableBranches: ["develop"], exclude: ["benchmarks"], subspaces: [{ name: "acme", repo: ${JSON.stringify(bareRoot)}, apps: ["${servedApp}"] }] } };\n`,
   );
+  await write(path.join(wsRoot, "Jenkinsfile"), "pipeline { agent any }\n");
 
   await makeSys(wsRoot, "apps", servedApp, {
     "lib/task/task.constant.ts": [
@@ -152,7 +159,8 @@ describe("Subspace push", () => {
     expect(await FileSys.fileExists(path.join(subspaceRoot, "libs/kit/common/helper.ts"))).toBe(true);
     expect(await FileSys.dirExists(path.join(subspaceRoot, "apps/private"))).toBe(false);
     expect(entries).not.toContain("benchmarks");
-    expect(entries).not.toContain("akan.subspace.ts");
+    expect(entries).not.toContain("akan.config.ts");
+    expect(entries).not.toContain("Jenkinsfile");
     expect(await FileSys.fileExists(path.join(subspaceRoot, "apps/served/lib/cnst.ts"))).toBe(false);
     expect(await FileSys.fileExists(path.join(subspaceRoot, "apps/served/env/env.server.local.ts"))).toBe(false);
     expect(await FileSys.fileExists(path.join(subspaceRoot, "apps/served/env/env.server.ts"))).toBe(true);
@@ -216,6 +224,63 @@ describe("Subspace push", () => {
     expect((await subspace.push("develop", { verify: false })).outcome).toBe("skipped");
   });
 
+  test("skips a push after an unrelated workspace commit, and re-stamps a library only when its content moves", async () => {
+    const { wsRoot, workRoot, bareRoot, subspace } = await makeMirror("calm-served", "calm-private", "calm-kit");
+    expect((await subspace.push("develop", { verify: false })).outcome).toBe("pushed");
+    const stampOf = async (root: string) =>
+      (
+        (await FileSys.readJson(path.join(root, "libs/calm-kit/package.json"))) as {
+          akan: { source: { sha: string; hash: string } };
+        }
+      ).akan.source;
+    const first = await stampOf(await cloneSubspace(workRoot, bareRoot, "calm-first"));
+
+    await write(path.join(wsRoot, "apps/calm-private/lib/task/task.constant.ts"), "export const task = 2;\n");
+    await git(wsRoot, ["add", "-A"]);
+    await git(wsRoot, ["commit", "--quiet", "-m", "outside the slice"]);
+    expect((await subspace.push("develop", { verify: false })).outcome).toBe("skipped");
+
+    await write(path.join(wsRoot, "libs/calm-kit/common/helper.ts"), "export const helper = 2;\n");
+    await git(wsRoot, ["add", "-A"]);
+    await git(wsRoot, ["commit", "--quiet", "-m", "inside the slice"]);
+    expect((await subspace.push("develop", { verify: false })).outcome).toBe("pushed");
+    const second = await stampOf(await cloneSubspace(workRoot, bareRoot, "calm-second"));
+    expect(second.hash).not.toBe(first.hash);
+    expect(second.sha).not.toBe(first.sha);
+  });
+
+  test("keeps the subspace's own root config and drops a Jenkinsfile an earlier push left there", async () => {
+    const { workRoot, bareRoot, subspace } = await makeMirror("own-served", "own-private", "own-kit");
+    const customer = await cloneSubspace(workRoot, bareRoot, "own-customer");
+    await write(path.join(customer, "akan.config.ts"), "export default { pipeline: {} };\n");
+    await git(customer, ["add", "-A"]);
+    await git(customer, ["commit", "--quiet", "-m", "our own global stages"]);
+    await write(path.join(customer, "Jenkinsfile"), "pipeline { agent none }\n");
+    await git(customer, ["add", "-A"]);
+    await git(customer, ["commit", "--quiet", "-m", `${Subspace.syncSubjectPrefix}workspace@0000000`]);
+    await git(customer, ["push", "--quiet", "origin", "develop"]);
+
+    expect((await subspace.push("develop", { verify: false })).outcome).toBe("pushed");
+    const subspaceRoot = await cloneSubspace(workRoot, bareRoot, "own-check");
+    expect(await FileSys.readText(path.join(subspaceRoot, "akan.config.ts"))).toContain(
+      "export default { pipeline: {} };",
+    );
+    expect(await FileSys.fileExists(path.join(subspaceRoot, "Jenkinsfile"))).toBe(false);
+  });
+
+  test("refuses a lock that resolves from a registry only this machine reaches", async () => {
+    const { wsRoot, subspace } = await makeMirror("lock-served", "lock-private", "lock-kit");
+    await write(
+      path.join(wsRoot, "bun.lock"),
+      '{ "packages": { "lodash": ["lodash@4.0.0", "http://127.0.0.1:4873/lodash/-/lodash-4.0.0.tgz"] } }\n',
+    );
+    await git(wsRoot, ["add", "-f", "bun.lock"]);
+    await git(wsRoot, ["commit", "--quiet", "-m", "a verdaccio lock"]);
+    const result = (await subspace.push("develop", { verify: false })) as { outcome: string; reason?: string };
+    expect(result.outcome).toBe("refused");
+    expect(result.reason).toContain("http://127.0.0.1:4873");
+  });
+
   test("refuses a branch the subspace does not have, and one the config does not allow", async () => {
     const { subspace } = await makeMirror("refuse-served", "refuse-private", "refuse-kit");
     const missing = await subspace.push("release", { verify: false }).catch((error: Error) => error);
@@ -445,3 +510,42 @@ describe("SubspaceConfig", () => {
     expect(() => config.assertPushable("develop")).not.toThrow();
   });
 });
+
+describe("Subspace.plan", () => {
+  test("reports the slice a push ships without adding a remote or a clone", async () => {
+    const { wsRoot, subspace, clonePath } = await makeMirror("served", "private", "kit");
+    const plan = await subspace.plan("develop");
+    expect(plan).toMatchObject({
+      name: "acme",
+      branch: "develop",
+      branchRefusal: null,
+      apps: ["served"],
+      libs: [{ name: "kit", apps: ["served"] }],
+      excludedRootEntries: ["benchmarks"],
+      subspaceOwnedRootEntries: ["akan.config.ts", "Jenkinsfile"],
+      prunedDependencies: ["another-app-dep"],
+      lockProblem: null,
+    });
+    expect(plan.rootEntries).toEqual(expect.arrayContaining([".gitignore", "AGENTS.md", "biome.json", "package.json"]));
+    expect(plan.rootEntries).not.toContain("benchmarks");
+    expect(plan.rootEntries).not.toContain("Jenkinsfile");
+    expect(plan.files).toBeGreaterThan(0);
+    expect((await git(wsRoot, ["remote"])).trim()).toBe("");
+    expect(await FileSys.dirExists(clonePath)).toBe(false);
+    expect(formatSubspacePlan(plan)).toContain("Nothing here would make a push refuse.");
+  });
+
+  test("names what a push would refuse: a branch it may not push and a loopback-registry lock", async () => {
+    const { wsRoot, subspace } = await makeMirror("served", "private", "kit");
+    await write(
+      path.join(wsRoot, "bun.lock"),
+      '{ "packages": { "x": ["x@1.0.0", "http://127.0.0.1:4873/x/-/x-1.0.0.tgz"] } }\n',
+    );
+    await git(wsRoot, ["add", "-f", "bun.lock"]);
+    await git(wsRoot, ["commit", "--quiet", "-m", "lock"]);
+    const plan = await subspace.plan("main");
+    expect(plan.branchRefusal).toContain('Branch "main" is not pushable');
+    expect(plan.lockProblem).toContain("http://127.0.0.1:4873");
+    expect(formatSubspacePlan(plan)).toContain("A push would be refused:");
+  });
+});

package/subspace.ts

@@ -55,6 +55,28 @@ export interface SubspacePushResult {
   prunedDependencies?: string[];
 }
 
+export interface SubspacePlan {
+  name: string;
+  repo: string;
+  branch: string;
+  /** Why a push from this branch would be refused, or null when it may push. */
+  branchRefusal: string | null;
+  apps: string[];
+  /** Each library the slice carries, with the apps whose closure pulls it in. */
+  libs: { name: string; apps: string[] }[];
+  /** Tracked files under the slice's apps/ and libs/ directories. */
+  files: number;
+  /** Workspace-root entries a push copies into the subspace. */
+  rootEntries: string[];
+  excludedRootEntries: string[];
+  /** Workspace-root entries never pushed: the subspace keeps its own copy, if it has one. */
+  subspaceOwnedRootEntries: string[];
+  prunedDependencies: string[];
+  /** Why the workspace's bun.lock would make a push refuse, or null. */
+  lockProblem: string | null;
+  warnings: string[];
+}
+
 export interface SubspaceEnvUploadResult {
   name: string;
   /** The cloud workspace whose env archive was replaced: the subspace's own, never this workspace's. */
@@ -79,14 +101,19 @@ export interface SubspacePullResult {
 // pull diffs against the last push received, so it is exactly the customer's own work.
 export class Subspace {
   static readonly anchorFile = "akan.subspace.json";
-  /** Never reaches a subspace: it names every other customer's repo. */
-  static readonly workspaceOnlyEntries = ["akan.subspace.ts"];
+  /**
+   * The workspace's own never reach a subspace — its root config names every other customer's repo, its Jenkinsfile
+   * deploys the workspace — and a subspace's own survive every push.
+   */
+  static readonly subspaceOwnedRootEntries = ["akan.config.ts", "Jenkinsfile"];
+  static readonly syncSubjectPrefix = "chore(subspace): sync from ";
   /** Workspace members, which are replaced wholesale rather than overlaid. */
   static readonly memberDirs = ["apps", "libs"];
   /** Subspace-owned in both directions: env values belong to the repo that deploys, not to the workspace. */
   static readonly subspaceOwnedDirs = ["env"];
   static readonly secretsMarkers = ["# akan:secrets (managed by akan.config.ts — do not edit)", "# akan:secrets:end"];
   static readonly holdDir = ".akan-subspace-hold";
+  static readonly #loopbackRegistry = /https?:\/\/(?:127\.0\.0\.1|localhost|0\.0\.0\.0|\[::1\])(?::\d+)?/;
 
   #workspace: WorkspaceExecutor;
   #config: SubspaceConfig;
@@ -118,6 +145,10 @@ export class Subspace {
     return await this.#workspace.spawn("git", args);
   }
 
+  async #cloneGit(args: string[]) {
+    return await this.#workspace.spawn("git", ["-C", this.#clonePath, ...args]);
+  }
+
   async branch() {
     return (await this.#git(["rev-parse", "--abbrev-ref", "HEAD"])).trim();
   }
@@ -167,6 +198,52 @@ export class Subspace {
     return { plans, libs, paths };
   }
 
+  /** What a push from `branch` would ship, worked out from this checkout alone: no fetch, no remote, no clone. */
+  async plan(branch: string): Promise<SubspacePlan> {
+    const { plans, libs } = await this.slice();
+    const rootFiles = plans[0]?.rootFiles ?? [];
+    const present = new Set(rootFiles.map((file) => file.split("/")[0] ?? file));
+    const owned = Subspace.subspaceOwnedRootEntries;
+    const excluded = this.#config.exclude.filter((entry) => !owned.includes(entry));
+    const excludedTops = new Set(excluded.map((entry) => entry.replace(/\/+$/, "")));
+    const libFiles = new Map(plans.flatMap((plan) => Object.entries(plan.libFiles)));
+    const { pruned, warnings } = await SlicePlanner.pruneDependencies(
+      this.#workspace,
+      await this.#workspace.getPackageJson(),
+      plans.flatMap((plan) => plan.requiredDependencies),
+    );
+    let branchRefusal: string | null = null;
+    try {
+      this.#config.assertPushable(branch);
+    } catch (error) {
+      branchRefusal = error instanceof Error ? error.message : String(error);
+    }
+    return {
+      name: this.name,
+      repo: this.#declaration.repo,
+      branch,
+      branchRefusal,
+      apps: [...this.#declaration.apps],
+      libs: libs.map((lib) => ({
+        name: lib,
+        apps: plans.filter((plan) => plan.libs.includes(lib)).map((plan) => plan.app),
+      })),
+      files:
+        plans.reduce((sum, plan) => sum + plan.appFiles.length, 0) +
+        [...libFiles.values()].reduce((sum, files) => sum + files.length, 0),
+      rootEntries: [...present]
+        .filter((entry) => !excludedTops.has(entry) && !owned.includes(entry))
+        .sort((a, b) => a.localeCompare(b)),
+      excludedRootEntries: excluded,
+      subspaceOwnedRootEntries: owned.filter((entry) => present.has(entry)),
+      prunedDependencies: pruned,
+      lockProblem: rootFiles.includes("bun.lock")
+        ? await this.#loopbackRegistryLock(this.#workspace.workspaceRoot)
+        : null,
+      warnings: [...new Set([...plans.flatMap((plan) => plan.warnings), ...warnings])],
+    };
+  }
+
   #isSubspaceOwned(file: string) {
     const segments = file.split("/");
     if (!Subspace.memberDirs.includes(segments[0] ?? "")) return false;
@@ -258,6 +335,36 @@ export class Subspace {
     await rm(path.join(this.#clonePath, Subspace.holdDir), { recursive: true, force: true });
   }
 
+  //* A root entry last written by a sync commit is a copy an earlier push left there, the parent's Jenkinsfile among them:
+  //* it goes. Any other is the subspace's own and is held through the extraction.
+  async #holdRootEntries() {
+    const holdRoot = path.join(this.#clonePath, Subspace.holdDir, "root");
+    const held: string[] = [];
+    for (const entry of Subspace.subspaceOwnedRootEntries) {
+      const from = path.join(this.#clonePath, entry);
+      if (!(await FileSys.entryExists(from))) continue;
+      if (await this.#isPushedCopy(entry)) continue;
+      await mkdir(holdRoot, { recursive: true });
+      await rename(from, path.join(holdRoot, entry));
+      held.push(entry);
+    }
+    return held;
+  }
+
+  async #restoreRootEntries(held: string[]) {
+    const holdRoot = path.join(this.#clonePath, Subspace.holdDir, "root");
+    for (const entry of Subspace.subspaceOwnedRootEntries) {
+      const target = path.join(this.#clonePath, entry);
+      await rm(target, { recursive: true, force: true });
+      if (held.includes(entry)) await rename(path.join(holdRoot, entry), target);
+    }
+  }
+
+  async #isPushedCopy(entry: string) {
+    const subject = await this.#cloneGit(["log", "-1", "--format=%s", "--", entry]).catch(() => "");
+    return subject.trim().startsWith(Subspace.syncSubjectPrefix);
+  }
+
   static async #copyMissing(from: string, to: string) {
     await mkdir(to, { recursive: true });
     for (const entry of await readdir(from, { withFileTypes: true })) {
@@ -337,16 +444,19 @@ export class Subspace {
   async #applySlice(clone: Executor, branch: string) {
     const { libs, paths, plans } = await this.slice();
     const held = await this.#holdSubspaceOwned();
+    const heldRootEntries = await this.#holdRootEntries();
     for (const member of Subspace.memberDirs)
       await rm(path.join(this.#clonePath, member), { recursive: true, force: true });
 
     //* Overlaid, never reconciled: a subspace owns its deployment, so a root entry the workspace lacks is left alone.
     await this.#extract(["."], ["apps/*", "libs/*", "pkgs/*"]);
     await this.#extract(paths);
+    await this.#restoreRootEntries(heldRootEntries);
     await this.#restoreSubspaceOwned(held);
 
-    for (const entry of [...Subspace.workspaceOnlyEntries, ...this.#config.exclude])
-      await rm(path.join(this.#clonePath, entry), { recursive: true, force: true });
+    for (const entry of this.#config.exclude)
+      if (!Subspace.subspaceOwnedRootEntries.includes(entry))
+        await rm(path.join(this.#clonePath, entry), { recursive: true, force: true });
 
     await this.#rewriteGitignore();
     const pruned = await this.#rewriteManifest(plans);
@@ -404,11 +514,12 @@ export class Subspace {
     const [hash, previous] = await Promise.all([this.#hashLib(clone, lib), this.#committedStamp(clone, lib)]);
     const manifest = (await FileSys.readJson(manifestPath)) as Record<string, unknown>;
     const akan = (manifest[LibSource.manifestKey] ?? {}) as Record<string, unknown>;
-    //* The extraction overwrote the manifest, so the previous stamp comes from the clone's HEAD; reusing its
-    //* `syncedAt` when nothing moved keeps the file byte-identical, or no push would ever be skipped.
-    const unchanged = previous?.origin === origin && previous.sha === sha && previous.hash === hash;
-    const syncedAt = unchanged ? previous.syncedAt : new Date().toISOString();
-    manifest[LibSource.manifestKey] = { ...akan, source: { origin, sha, hash, syncedAt } };
+    //* The extraction overwrote the manifest, so the previous stamp comes from the clone's HEAD. It is kept whole while
+    //* the library's content is unchanged — matching the workspace sha too would rewrite every manifest, and push,
+    //* after any unrelated workspace commit.
+    const unchanged = previous?.origin === origin && previous.hash === hash;
+    const source = unchanged ? previous : { origin, sha, hash, syncedAt: new Date().toISOString() };
+    manifest[LibSource.manifestKey] = { ...akan, source };
     await FileSys.writeJson(manifestPath, manifest);
   }
 
@@ -472,6 +583,16 @@ export class Subspace {
     return { files, patch: await this.#git(["diff", from, "HEAD", "--", ...files]) };
   }
 
+  // A lock written against a local registry (verdaccio) resolves on this machine alone: every install of it fails.
+  async #loopbackRegistryLock(root = this.#clonePath) {
+    const lockPath = path.join(root, "bun.lock");
+    if (!(await FileSys.fileExists(lockPath))) return null;
+    const registry = (await FileSys.readText(lockPath)).match(Subspace.#loopbackRegistry)?.[0];
+    return registry
+      ? `bun.lock resolves packages from ${registry}, a registry only this machine reaches; reinstall from a public registry and commit that lock first`
+      : null;
+  }
+
   // Refuses rather than throws, so one failing subspace does not abort the rest; the env is explicit so the child
   // sees the clone's values, not the workspace's.
   async #verify(clone: Executor) {
@@ -510,9 +631,11 @@ export class Subspace {
       const failure = await this.#verify(clone);
       if (failure) return { name: this.name, outcome: "refused", reason: failure, changedFiles };
     }
+    const lockProblem = await this.#loopbackRegistryLock();
+    if (lockProblem) return { name: this.name, outcome: "refused", reason: lockProblem, changedFiles };
     await this.#writeAnchorFile(branch);
     await clone.spawn("git", ["add", "-A"]);
-    const message = `chore(subspace): sync from ${this.#workspace.repoName}@${await this.headSha()}`;
+    const message = `${Subspace.syncSubjectPrefix}${this.#workspace.repoName}@${await this.headSha()}`;
     await clone.spawn("git", ["commit", "--quiet", "-m", message]);
     //* Never force: a diverged subspace holds customer commits, and `pull` is how those come back.
     await clone.spawn("git", ["push", "--quiet", "origin", branch]);
@@ -694,3 +817,32 @@ export function formatSubspaceDiff(result: SubspaceDiffResult) {
   ];
   return sections.join("\n");
 }
+
+export function formatSubspacePlan(plan: SubspacePlan) {
+  const list = (entries: string[]) => (entries.length ? entries.join(", ") : "(none)");
+  const blockers = [plan.branchRefusal, plan.lockProblem].filter((reason): reason is string => !!reason);
+  const sections = [
+    `Akan Subspace Plan — ${plan.name} (${plan.branch})`,
+    `repo: ${plan.repo}`,
+    "what `akan subspace push` would ship, worked out from this checkout alone",
+    "",
+    `apps: ${list(plan.apps)}`,
+    `libs: ${plan.libs.length ? "" : "(none)"}`.trimEnd(),
+    ...plan.libs.map((lib) => `  - ${lib.name} (from ${lib.apps.join(", ")})`),
+    `files under apps/ and libs/: ${plan.files}`,
+    "",
+    `root entries pushed: ${list(plan.rootEntries)}`,
+    `root entries excluded: ${list(plan.excludedRootEntries)}`,
+    `root entries the subspace keeps its own: ${list(plan.subspaceOwnedRootEntries)}`,
+    "",
+    `Root dependencies left out of package.json (${plan.prunedDependencies.length}):`,
+    ...(plan.prunedDependencies.length ? plan.prunedDependencies.map((dep) => `  - ${dep}`) : ["  (none)"]),
+    "",
+    blockers.length ? "A push would be refused:" : "Nothing here would make a push refuse.",
+    ...blockers.map((reason) => `  - ${reason}`),
+    ...(plan.warnings.length
+      ? ["", `Warnings (${plan.warnings.length}):`, ...plan.warnings.map((w) => `  - ${w}`)]
+      : []),
+  ];
+  return sections.join("\n");
+}

package/subspaceConfig.ts

@@ -1,20 +1,17 @@
-import path from "node:path";
 import type { SubspaceConfigInput, SubspaceDeclaration } from "akanjs";
 import type { WorkspaceExecutor } from "./executors";
-import { FileSys } from "./fileSys";
 
 export type { SubspaceConfigInput, SubspaceDeclaration };
 
 // No branch field: the workspace's current branch is used, so every subspace on it holds the same akanjs and libs.
 export class SubspaceConfig {
-  static readonly fileName = "akan.subspace.ts";
+  /** Where the declaration lives, as error messages name it. */
+  static readonly source = "subspace in the workspace root akan.config.ts";
   static readonly defaultPushableBranches = ["main", "develop", "debug"];
 
   static async from(workspace: WorkspaceExecutor): Promise<SubspaceConfig | null> {
-    const configPath = path.join(workspace.workspaceRoot, SubspaceConfig.fileName);
-    if (!(await FileSys.fileExists(configPath))) return null;
-    const input = await import(configPath).then((mod: { default: SubspaceConfigInput }) => mod.default);
-    return new SubspaceConfig(input);
+    const { subspace } = await workspace.getConfig();
+    return subspace ? new SubspaceConfig(subspace) : null;
   }
 
   readonly pushableBranches: string[];
@@ -34,18 +31,18 @@ export class SubspaceConfig {
     const idOwners = new Map<string, string>();
     for (const subspace of this.subspaces) {
       if (!subspace.name || !subspace.repo)
-        throw new Error(`${SubspaceConfig.fileName}: every subspace needs a name and a repo`);
+        throw new Error(`${SubspaceConfig.source}: every subspace needs a name and a repo`);
       if (seenNames.has(subspace.name))
-        throw new Error(`${SubspaceConfig.fileName}: duplicate subspace "${subspace.name}"`);
+        throw new Error(`${SubspaceConfig.source}: duplicate subspace "${subspace.name}"`);
       seenNames.add(subspace.name);
       if (!subspace.apps?.length)
-        throw new Error(`${SubspaceConfig.fileName}: subspace "${subspace.name}" declares no apps`);
+        throw new Error(`${SubspaceConfig.source}: subspace "${subspace.name}" declares no apps`);
       for (const app of subspace.apps) {
         const owner = appOwners.get(app);
         //* One app never goes to two subspaces: per-subspace domains and ids are not expressible. Share a lib instead.
         if (owner)
           throw new Error(
-            `${SubspaceConfig.fileName}: app "${app}" is claimed by both "${owner}" and "${subspace.name}"`,
+            `${SubspaceConfig.source}: app "${app}" is claimed by both "${owner}" and "${subspace.name}"`,
           );
         appOwners.set(app, subspace.name);
       }
@@ -54,7 +51,7 @@ export class SubspaceConfig {
       //* An env upload replaces the cloud workspace's archive whole, so two subspaces would overwrite each other.
       if (idOwner)
         throw new Error(
-          `${SubspaceConfig.fileName}: subspaces "${idOwner}" and "${subspace.name}" declare the same workspaceId`,
+          `${SubspaceConfig.source}: subspaces "${idOwner}" and "${subspace.name}" declare the same workspaceId`,
         );
       idOwners.set(subspace.workspaceId, subspace.name);
     }
@@ -64,7 +61,7 @@ export class SubspaceConfig {
     if (!names.length) return this.subspaces;
     return names.map((name) => {
       const subspace = this.subspaces.find((candidate) => candidate.name === name);
-      if (!subspace) throw new Error(`${SubspaceConfig.fileName}: unknown subspace "${name}"`);
+      if (!subspace) throw new Error(`${SubspaceConfig.source}: unknown subspace "${name}"`);
       return subspace;
     });
   }
@@ -72,7 +69,7 @@ export class SubspaceConfig {
   assertPushable(branch: string) {
     if (this.pushableBranches.includes(branch)) return;
     throw new Error(
-      `Branch "${branch}" is not pushable. ${SubspaceConfig.fileName} allows: ${this.pushableBranches.join(", ")}`,
+      `Branch "${branch}" is not pushable. ${SubspaceConfig.source} allows: ${this.pushableBranches.join(", ")}`,
     );
   }
 }

package/testHelpers.ts

@@ -61,6 +61,10 @@ export const createFakeExecutor = <Extra extends object = object>(
       recorder.record(`${name}.scanSync`, ...args);
       return { name };
     },
+    //? `PkgExecutor.from(fake, name)` reads `.workspace`; without one it falls back to `fromRoot()`, which forks git.
+    get workspace(): unknown {
+      return this;
+    },
     ...extra,
   }) as Extra & {
     name: string;

package/transforms/externalizeFrameworkPlugin.ts

@@ -17,13 +17,7 @@ const DEFAULT_INCLUDE = ["akanjs/", "@apps/", "@libs/"];
 // Runtime hosts and singleton framework packages stay external; ordinary npm dependencies are bundled.
 const DEFAULT_EXCLUDE_EXACT = new Set<string>(["akanjs/webkit", "@akanjs/cli", "@akanjs/devkit"]);
 const DEFAULT_EXCLUDE_PREFIX = ["@akanjs/cli/", "@akanjs/devkit/"];
-const OPTIONAL_BACKEND_EXTERNAL_EXACT = new Set<string>([
-  "@libsql/client",
-  "bullmq",
-  "ioredis",
-  "postgres",
-  "protobufjs",
-]);
+const OPTIONAL_BACKEND_EXTERNAL_EXACT = new Set<string>(["bullmq", "ioredis", "postgres", "protobufjs"]);
 const RUNTIME_EXTERNAL_EXACT = new Set<string>([
   "react",
   "react-dom",