@akanjs/devkit 3.1.0-rc.26 → 3.1.0-rc.27

package/applicationBuildRunner.test.ts

@@ -172,4 +172,40 @@ console.info(new SampleService().name);
       await rm(root, { recursive: true, force: true });
     }
   });
+
+  test("asks the bundler for a metafile with AKAN_BUILD_METAFILE=1, and not with 0, false or an empty value", async () => {
+    const { root, workspace } = await createTempApp("portal");
+    const keys = [
+      "AKAN_BUILD_METAFILE",
+      "AKAN_PUBLIC_ENV",
+      "AKAN_PUBLIC_REPO_NAME",
+      "AKAN_PUBLIC_SERVE_DOMAIN",
+    ] as const;
+    const shellEnv = Object.fromEntries(keys.map((key) => [key, process.env[key]]));
+    await Promise.all(["main.ts", "server.ts"].map((file) => writeFile(path.join(root, "apps", "portal", file), "")));
+    const app = AppExecutor.from(workspace, "portal");
+    app.prepareCommand = async () => ({ env: {} });
+    const bundle = spyOn(Bun, "build").mockImplementation(async () => {
+      throw new Error("stopped at the first bundle");
+    });
+    const asksForMetafile = async (flag: string) => {
+      process.env.AKAN_BUILD_METAFILE = flag;
+      await expect(new ApplicationBuildRunner(app, { fast: true }).build()).rejects.toThrow(
+        "stopped at the first bundle",
+      );
+      return bundle.mock.lastCall?.[0].metafile === true;
+    };
+    try {
+      const asked: { [flag: string]: boolean } = {};
+      for (const flag of ["1", "0", "false", ""]) asked[flag] = await asksForMetafile(flag);
+      expect(asked).toEqual({ "1": true, "0": false, false: false, "": false });
+    } finally {
+      bundle.mockRestore();
+      for (const key of keys) {
+        if (shellEnv[key] === undefined) delete process.env[key];
+        else process.env[key] = shellEnv[key];
+      }
+      await rm(root, { recursive: true, force: true });
+    }
+  });
 });

package/applicationBuildRunner.ts

@@ -387,9 +387,11 @@ void run().catch((error) => {
 
   //? Opt-in and outside `dist/`: a metafile is the size of the module graph, and `dist/` is what the image copies.
   async #buildOrThrow(label: string, config: Bun.BuildConfig): Promise<Bun.BuildOutput> {
-    const metafileDir = process.env.AKAN_BUILD_METAFILE
-      ? path.join(this.#app.workspace.workspaceRoot, "local", "build-meta", path.basename(this.#app.cwdPath))
-      : null;
+    const flag = process.env.AKAN_BUILD_METAFILE;
+    const metafileDir =
+      flag && flag !== "0" && flag !== "false"
+        ? path.join(this.#app.workspace.workspaceRoot, "local", "build-meta", path.basename(this.#app.cwdPath))
+        : null;
     const result = await Bun.build(metafileDir ? { ...config, metafile: true } : config);
     if (!result.success) throw new AggregateError(result.logs, `[${label}] Bun.build failed`);
     if (metafileDir && result.metafile) {

package/biome.base.json

@@ -196,6 +196,7 @@
     },
     {
       "includes": ["{apps,libs}/**/*.tsx", "!**/*.test.tsx", "!**/*.spec.tsx"],
+      "linter": { "rules": { "correctness": { "useHookAtTopLevel": "error" } } },
       "plugins": [
         "./node_modules/@akanjs/devkit/lint/no-unpublished-form-setter.grit",
         "./node_modules/@akanjs/devkit/lint/no-conditional-st-hook.grit"

package/biomeBase.test.ts

@@ -0,0 +1,78 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { spawn } from "node:child_process";
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { biomeBaseConfig } from "./biomeBase";
+import { Linter, parseBiomeReport } from "./linter";
+
+const devkitDir = import.meta.dir;
+const biomeBin = path.resolve(devkitDir, "../../../node_modules/.bin", Linter.biomeBinName);
+
+const hookProbe = `export const Early = ({ id }: { id?: string }) => {
+  if (!id) return null;
+  const [count] = useState(0);
+  return <p>{count}</p>;
+};
+export const Branch = ({ open }: { open: boolean }) => {
+  if (open) useEffect(() => {}, []);
+  return null;
+};
+`;
+
+const tempDirs: string[] = [];
+
+afterAll(async () => {
+  await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+const runBiome = (args: string[], cwd: string) =>
+  new Promise<string>((resolve, reject) => {
+    const proc = spawn(biomeBin, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (chunk: Buffer) => (stdout += chunk.toString()));
+    proc.stderr.on("data", (chunk: Buffer) => (stderr += chunk.toString()));
+    proc.on("error", reject);
+    proc.on("close", () => resolve(stdout || stderr));
+  });
+
+const lintWorkspace = async (files: string[]) => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "biome-base-"));
+  tempDirs.push(dir);
+  //? The base config names its plugins as `./node_modules/@akanjs/devkit/…`, resolved from the extending config's
+  //? folder. A junction needs no privilege on Windows, and the type is ignored elsewhere.
+  await mkdir(path.join(dir, "node_modules", "@akanjs"), { recursive: true });
+  await symlink(devkitDir, path.join(dir, "node_modules", "@akanjs", "devkit"), "junction");
+  await writeFile(path.join(dir, "biome.json"), JSON.stringify({ extends: [biomeBaseConfig] }));
+  for (const file of files) {
+    await mkdir(path.dirname(path.join(dir, file)), { recursive: true });
+    await writeFile(path.join(dir, file), hookProbe);
+  }
+  const output = await runBiome(["lint", "--reporter=json", "--max-diagnostics=none", ...files], dir);
+  return parseBiomeReport(output).diagnostics ?? [];
+};
+
+describe("biome.base.json", () => {
+  test("reports a conditional React hook in app and lib components, not in their tests or in packages", async () => {
+    const diagnostics = await lintWorkspace([
+      "apps/demo/ui/Probe.tsx",
+      "libs/demo/ui/Probe.tsx",
+      "apps/demo/ui/Probe.test.tsx",
+      "pkgs/demo/Probe.tsx",
+    ]);
+    const hookReports = diagnostics
+      .filter((diagnostic) => diagnostic.category === "lint/correctness/useHookAtTopLevel")
+      .map(
+        (diagnostic) =>
+          `${diagnostic.location?.path?.replaceAll("\\", "/")}:${diagnostic.location?.start?.line} ${diagnostic.severity}`,
+      )
+      .sort();
+    expect(hookReports).toEqual([
+      "apps/demo/ui/Probe.tsx:3 error",
+      "apps/demo/ui/Probe.tsx:7 error",
+      "libs/demo/ui/Probe.tsx:3 error",
+      "libs/demo/ui/Probe.tsx:7 error",
+    ]);
+  });
+});

package/codeAgent/skills/akan-store/SKILL.md

@@ -19,7 +19,8 @@ For a model `comment` (`<Slice>` is a signal slice suffix, e.g. `InPublic`):
   `add<Field>OnComment(value)` / `sub<Field>OnComment(idx)` for arrays, `upload<Field>OnComment(fileList)`
   for file fields, `checkCommentSubmitable()`, `submitComment()`, `createCommentInForm()`,
   `updateCommentInForm()`
-- single: `viewComment(model)`, `mergeComment(model, data)`, `setComment(...models)`, `resetComment()`
+- single: `viewComment(model)`, `mergeComment(model, data)`, `setComment(...models)`, `resetComment()`,
+  `invalidateComment()` (marks every slice stale after a custom mutation, so the next mount refetches)
 - per slice: `initComment<Slice>(...args)`, `refreshComment<Slice>()`, `selectComment<Slice>(model)`,
   `setPageOfComment<Slice>(page)`, `loadMoreOfComment<Slice>()`, `setLimitOfComment<Slice>(limit)`,
   `setQueryArgsOfComment<Slice>(...)`, `setSortOfComment<Slice>(sort)`

package/codeAgent/tools/WebToolPack.ts

@@ -1,3 +1,4 @@
+import { lookup } from "node:dns/promises";
 import { isIP } from "node:net";
 import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
 import { type CodeAgentProfile, codeAgentClip } from "akanjs/common";
@@ -8,6 +9,7 @@ export interface WebToolPackOptions {
   profile: CodeAgentProfile;
   /** Serves search after any key-named provider, and reads public pages to Markdown ahead of a direct fetch. */
   deepseek?: DeepSeekWeb | undefined;
+  lookup?: ((host: string) => Promise<string[]>) | undefined;
 }
 
 interface SearchProvider {
@@ -163,7 +165,7 @@ export class WebToolPack {
 
   async #read(url: string, signal?: AbortSignal): Promise<WebPage> {
     const deepseek = this.#options.deepseek;
-    if (deepseek && !WebToolPack.#isLocal(new URL(url).hostname)) {
+    if (deepseek && !(await this.#isLocal(new URL(url).hostname))) {
       try {
         const page = await deepseek.fetch(url, signal);
         return { status: 200, ok: true, title: page.title, text: page.content };
@@ -196,23 +198,46 @@ export class WebToolPack {
   }
 
   // DeepSeek's servers cannot reach these, and an intranet name has no business leaving the machine.
-  static #isLocal(hostname: string) {
-    const host = hostname.replace(/^\[|\]$/g, "").toLowerCase();
-    const family = isIP(host);
-    if (family === 6) return host === "::1" || /^(f[cd]|fe[89ab])/.test(host);
-    if (family === 4) {
-      const [a = 0, b = 0] = host.split(".").map(Number);
-      return (
-        a === 0 ||
-        a === 10 ||
-        a === 127 ||
-        (a === 100 && b >= 64 && b <= 127) ||
-        (a === 169 && b === 254) ||
-        (a === 172 && b >= 16 && b <= 31) ||
-        (a === 192 && b === 168)
-      );
+  async #isLocal(hostname: string) {
+    const host = hostname.replace(/^\[|\]$|\.$/g, "").toLowerCase();
+    if (isIP(host)) return WebToolPack.#isLocalAddress(host);
+    if (!host.includes(".") || /\.(localhost|local|internal|lan|home\.arpa)$/.test(host)) return true;
+    try {
+      const addresses = await (this.#options.lookup ?? WebToolPack.#lookup)(host);
+      return !addresses.length || addresses.some((address) => WebToolPack.#isLocalAddress(address));
+    } catch {
+      // Fails closed: an intranet name this machine cannot resolve right now is still an intranet name.
+      return true;
     }
-    return !host.includes(".") || /\.(localhost|local|internal|lan|home\.arpa)$/.test(host);
+  }
+
+  static async #lookup(host: string) {
+    return (await lookup(host, { all: true })).map((entry) => entry.address);
+  }
+
+  static #isLocalAddress(literal: string) {
+    const address = WebToolPack.#unmapped(literal);
+    if (isIP(address) === 6) return address === "::" || address === "::1" || /^(f[cd]|fe[89ab])/.test(address);
+    const [a = 0, b = 0] = address.split(".").map(Number);
+    return (
+      a === 0 ||
+      a === 10 ||
+      a === 127 ||
+      (a === 100 && b >= 64 && b <= 127) ||
+      (a === 169 && b === 254) ||
+      (a === 172 && b >= 16 && b <= 31) ||
+      (a === 192 && b === 168)
+    );
+  }
+
+  // The URL parser writes `[::ffff:127.0.0.1]` as `::ffff:7f00:1`; a resolver hands a mapped address back dotted.
+  static #unmapped(address: string) {
+    const mapped = /^::ffff:(?:(\d+\.\d+\.\d+\.\d+)|([0-9a-f]{1,4}):([0-9a-f]{1,4}))$/i.exec(address);
+    if (!mapped) return address;
+    if (mapped[1]) return mapped[1];
+    const high = Number.parseInt(mapped[2] ?? "0", 16);
+    const low = Number.parseInt(mapped[3] ?? "0", 16);
+    return [high >> 8, high & 255, low >> 8, low & 255].join(".");
   }
 
   static #refuseHost(url: string, allowHosts: string[] | undefined) {

package/codeAgent/tools/akanCodePlugins.test.ts

@@ -709,9 +709,9 @@ describe("WebToolPack", () => {
     }) as typeof fetch);
     try {
       const deepseek = new DeepSeekWeb("sk-test", `http://127.0.0.1:${deepseekServer.port}/v1/tools`);
-      const fetchTool = toolsOf(new WebToolPack({ profile: codeAgentPresets.local(root), deepseek }).extension()).get(
-        "web_fetch",
-      );
+      const lookup = async () => ["93.184.215.14"];
+      const pack = new WebToolPack({ profile: codeAgentPresets.local(root), deepseek, lookup });
+      const fetchTool = toolsOf(pack.extension()).get("web_fetch");
       const read = async (url: string) => (await fetchTool?.("1", { url } as never))?.content[0]?.text ?? "";
 
       expect(await read("https://docs.example.com/install")).toBe(
@@ -728,6 +728,74 @@ describe("WebToolPack", () => {
     }
   });
 
+  test("reads an intranet name, a mapped or unspecified loopback, and a name that does not resolve directly", async () => {
+    const asked: string[] = [];
+    const deepseekServer = Bun.serve({
+      port: 0,
+      fetch: async (request) => {
+        asked.push(((await request.json()) as { url: string }).url);
+        return Response.json({ title: "Public", content: "read by DeepSeek" });
+      },
+    });
+    const realFetch = globalThis.fetch;
+    const direct = spyOn(globalThis, "fetch").mockImplementation((async (
+      input: RequestInfo | URL,
+      init?: RequestInit,
+    ) => {
+      const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+      if (new URL(url).port === String(deepseekServer.port)) return await realFetch(input, init);
+      return new Response("<p>read directly</p>");
+    }) as typeof fetch);
+    const addresses: { [host: string]: string[] } = {
+      "jira.corp.example.com": ["10.0.0.7"],
+      "wiki.example.com": ["93.184.215.14", "fd12::1"],
+      "hosts.example.com": ["::ffff:192.168.0.2"],
+      "docs.example.com": ["93.184.215.14", "2606:2800:21f:cb07:6820:80da:af6b:8b2c"],
+    };
+    const looked: string[] = [];
+    const lookup = async (host: string) => {
+      looked.push(host);
+      const found = addresses[host];
+      if (!found) throw new Error(`getaddrinfo ENOTFOUND ${host}`);
+      return found;
+    };
+    try {
+      const deepseek = new DeepSeekWeb("sk-test", `http://127.0.0.1:${deepseekServer.port}/v1/tools`);
+      const pack = new WebToolPack({ profile: codeAgentPresets.local(root), deepseek, lookup });
+      const fetchTool = toolsOf(pack.extension()).get("web_fetch");
+      const read = async (url: string) => (await fetchTool?.("1", { url } as never))?.content[0]?.text ?? "";
+
+      for (const url of [
+        "http://jira.corp.example.com/browse/SEC-1",
+        "http://wiki.example.com/",
+        "http://hosts.example.com/",
+        "http://foo.test/",
+        "http://[::ffff:127.0.0.1]:8282/x",
+        "http://[::ffff:10.0.0.5]/wiki",
+        "http://[::]:8282/",
+        "http://0.0.0.0:8282/",
+        "http://localhost.:8282/",
+        "http://app.local./",
+      ])
+        expect(await read(url)).toContain("read directly");
+      expect(asked).toEqual([]);
+
+      expect(await read("https://docs.example.com/install")).toContain("read by DeepSeek");
+      expect(await read("http://[2606:4700:4700::1111]/")).toContain("read by DeepSeek");
+      expect(asked).toEqual(["https://docs.example.com/install", "http://[2606:4700:4700::1111]/"]);
+      expect(looked).toEqual([
+        "jira.corp.example.com",
+        "wiki.example.com",
+        "hosts.example.com",
+        "foo.test",
+        "docs.example.com",
+      ]);
+    } finally {
+      direct.mockRestore();
+      deepseekServer.stop(true);
+    }
+  });
+
   test("searches through DeepSeek when no key-named provider is set, and a key-named one wins", async () => {
     const had = { brave: process.env.BRAVE_API_KEY, tavily: process.env.TAVILY_API_KEY };
     const counts: number[] = [];

package/commandDecorators/command.ts

@@ -384,6 +384,8 @@ export const runCommands = async (...commands: CommandCls[]) => {
 Akan CLI version is mismatch with installed package. ${process.env.AKAN_VERSION} (global) vs ${installedAkanPackageJson.version} (akanjs)
 It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
       ),
+      undefined,
+      "error",
     );
   }
 

package/commandDecorators/commandDecorators.test.ts

@@ -659,3 +659,42 @@ describe("a repeatable option", () => {
     expect(await collect()).toEqual([]);
   }, 30_000);
 });
+
+describe("a workspace whose akanjs is not the CLI's version", () => {
+  const track = tempRoots();
+
+  test("hears so on stderr, leaving stdout to what the command prints", async () => {
+    const { root } = track(await makeCliTempWorkspace());
+    await writeText(path.join(root, "package.json"), '{ "name": "repo", "version": "1.0.0" }\n');
+    await writeText(path.join(root, "tsconfig.json"), "{}\n");
+    await writeText(
+      path.join(root, "node_modules", "akanjs", "package.json"),
+      '{ "name": "akanjs", "version": "0.0.1-older" }\n',
+    );
+    const entry = path.join(root, "cli.ts");
+    await writeText(
+      entry,
+      [
+        `import { command, runCommands, runner, script } from ${JSON.stringify(path.join(import.meta.dir, "index.ts"))};`,
+        'class PlanRunner extends runner("plan") {}',
+        'class PlanScript extends script("plan", [PlanRunner]) {}',
+        'class PlanCommand extends command("plan", [PlanScript], ({ public: target }) => ({',
+        '  plan: target({ desc: "plans", stdio: true }).exec(async function () {',
+        "    process.stdout.write(JSON.stringify({ phases: 1 }));",
+        "  }),",
+        "})) {}",
+        "await runCommands(PlanCommand);",
+        "",
+      ].join("\n"),
+    );
+    const proc = Bun.spawn(["bun", entry, "plan"], { cwd: root, stdout: "pipe", stderr: "pipe" });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    expect(code).toBe(0);
+    expect(stdout).toBe('{"phases":1}');
+    expect(stderr).toContain("0.0.1-older (akanjs)");
+  }, 30_000);
+});

package/executors.test.ts

@@ -429,6 +429,35 @@ describe("Workspace and app executor environment contracts", () => {
     });
   });
 
+  test("reads an explicit env file as Bun's own loader does, leaving inline comments out of the values", async () => {
+    const root = await makeTempRoot();
+    await writeFile(
+      path.join(root, ".env"),
+      [
+        "# the workspace env",
+        "AKAN_PUBLIC_SERVE_DOMAIN=example.com # prod domain",
+        'AKAN_PUBLIC_REPO_NAME="file repo" # note',
+        "AKAN_PUBLIC_ENV=develop#no space needed",
+        "export AKAN_WORKSPACE_ID='ws # kept' # dropped",
+        'AKAN_PUBLIC_APP_NAME="say \\"hi\\"\\nagain" # c',
+        'AKAN_WORKSPACE_ROOT="/unterminated # c',
+        "PORT_OFFSET=7",
+        "",
+      ].join("\r\n"),
+    );
+
+    expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env"))).toEqual({
+      appName: 'say \\"hi\\"\nagain',
+      workspaceRoot: '"/unterminated',
+      repoName: "file repo",
+      serveDomain: "example.com",
+      env: "develop",
+      portOffset: 7,
+      workspaceId: "ws # kept",
+      defaulted: [],
+    });
+  });
+
   test("builds app command environment and prepareCommand artifacts", async () => {
     const root = await makeTempRoot();
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";

package/executors.ts

@@ -140,6 +140,14 @@ export const execEmoji = {
   default: "✈️",
 };
 
+//? As Bun's own .env loader reads it (1.4.4), which fills process.env too: `#` ends an unquoted value even mid-word.
+const parseEnvValue = (value: string) => {
+  const [, quote, inner] = value.match(/^(["'`])((?:\\.|(?!\1)[^\\])*)\1/) ?? [];
+  if (!quote) return value.replace(/#.*/, "").trim();
+  if (quote !== '"') return inner;
+  return inner.replace(/\\(.)/g, (pair, char: string) => (char === "n" ? "\n" : char === "r" ? "\r" : pair));
+};
+
 const parseEnvFile = (envPath: string): Record<string, string> => {
   const env: Record<string, string> = {};
   const content = (() => {
@@ -156,11 +164,7 @@ const parseEnvFile = (envPath: string): Record<string, string> => {
     const separatorIndex = normalized.indexOf("=");
     if (separatorIndex <= 0) continue;
     const key = normalized.slice(0, separatorIndex).trim();
-    let value = normalized.slice(separatorIndex + 1).trim();
-    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-      value = value.slice(1, -1);
-    }
-    env[key] = value;
+    env[key] = parseEnvValue(normalized.slice(separatorIndex + 1).trim());
   }
   return env;
 };

package/lint/__fixtures__/no-conditional-st-hook/bad.tsx

@@ -17,8 +17,29 @@ export const A = () => {
   const [l] = open ? st.useState("l", String).desc("d").init("") : []; // @flag
   if (open) st.expose("m", String).desc("d").value("x"); // @flag
   const save = st.tool("z").desc("d").exec(async () => { st.use.n(); }); // @flag
+  const { title = st.use.title() } = props; // @flag
+  let cached = initial; cached ||= st.use.s(); // @flag
+  cached ??= st.use.t(); // @flag
+  cached &&= st.use.u(); // @flag
+  for (let i = 0; i < st.use.count(); i++) run(i); // @flag
+  const formatted = props.format?.(st.use.v()); // @flag
+  const chained = props.api?.format(st.use.w()); // @flag
+  const computed = open ? st["use"].x() : null; // @flag
+  const computedKey = open ? st.use["y"]() : null; // @flag
+  const computedSlice = open ? st.slice["inOrg"].use.z() : null; // @flag
+  useEffect(() => { void (async () => { await load(); st.use.aa(); })(); }, []); // @flag
   return <div onClick={() => st.use.o()} />; // @flag
 };
 export const B = () => <Load.Units renderList={(list) => <X a={st.use.p()} />} />; // @flag
 export const C = () => <Load.Stream of={q}>{(v) => <X a={st.sel((s) => s.q)} />}</Load.Stream>; // @flag
 export const useD = () => useMemo(() => st.use.r(), []); // @flag
+export const E = ({ name = st.use.defaultName() }) => <p>{name}</p>; // @flag
+export function F({ name = st.sel((s) => s.name) }) { return <p>{name}</p>; } // @flag
+export const G = () => {
+  const renderRow = (item) => <X a={st.use.bb()} />; // @flag
+  return <Load.Units renderItem={renderRow} />;
+};
+export const H = () => {
+  function row(item) { return <X a={st.ref((s) => s.cc)} />; } // @flag
+  return <ul>{items.map(row)}</ul>;
+};

package/lint/__fixtures__/no-conditional-st-hook/good.tsx

@@ -20,3 +20,14 @@ export const C = forwardRef((props, ref) => { const b = st.sel((s) => s.b); retu
 export const useTools = () => { const tool = (name) => st.tool(name).desc("d").exec(() => run()); tool("a"); }; // @ok
 export const D = () => <Load.Units renderItem={(item) => <Row key={item.id} id={item.id} />} />; // @ok
 export const E = () => { const busy = open && other.use.x(); return busy; }; // @ok
+export const F = () => { const Submit = useMemo(() => () => { const v = st.use.x(); return v; }, []); return <Submit />; }; // @ok
+export const G = () => { const Submit = useMemo(() => (open ? () => null : () => { const save = st.tool("s").desc("d").exec(run); return <Button onClick={save} />; }), [open]); return <Submit />; }; // @ok
+export const H = () => { for (let i = st.use.start(); i < 3; i++) run(i); return null; }; // @ok
+export const I = isNative ? () => { const a = st.use.a(); return a; } : () => null; // @ok
+export const J = () => { const a = (() => st.use.x())(); return a; }; // @ok
+export const K = () => { const Row = () => { const a = st.use.a(); return a; }; return <List row={Row} />; }; // @ok
+const renderPage = () => { const a = st.use.a(); return a; }; // @ok
+export const L = page().render(renderPage); // @ok
+export const M = () => { const v = st.use.x(); props.onPick?.(v); return v; }; // @ok
+export const N = () => { const a = st["use"].a(); const b = st.use["b"](); return a ?? b; }; // @ok
+export const O = () => { let v = cached; v = st.use.a(); return v; }; // @ok

package/lint/no-conditional-st-hook.grit

@@ -1,16 +1,20 @@
 engine biome(1.0)
 language js(typescript, jsx)
 
-// `st.use.<key>()`, `st.sel()`, `st.ref()` and the builders' last step (`st.tool(…)….exec()` / `.card()`,
-// `st.useState(…)….init()`, `st.expose(…)….value()`) are React hooks that Biome's `useHookAtTopLevel` cannot see:
-// it recognises a hook by a `use` prefix on the called name. A hook a render skips shifts every later hook by one
-// slot, and production React does not check the order — a later `useRef` then receives a frozen store value and
-// the screen dies far from the cause ("Cannot add property current, object is not extensible").
+// `st.use.<key>()`, `st.slice.<name>.use.<key>()`, `st.sel()`, `st.ref()` and the builders' last step
+// (`st.tool(…)….exec()` / `.card()`, `st.useState(…)….init()`, `st.expose(…)….value()`) are React hooks that Biome's
+// `useHookAtTopLevel` cannot see: it recognises a hook by a `use` prefix on the called name. A hook a render skips
+// shifts every later hook by one slot, and production React does not check the order — a later `useRef` then
+// receives a frozen store value and the screen dies far from the cause ("Cannot add property current, object is not
+// extensible").
 //
-// Reported: the right operand of `||` / `&&` / `??`, a ternary branch, an `if` / `else` body, a `switch` case, a
-// loop, a `catch` block, and a callback handed to a call or a JSX prop inside a component (`.map`, `useEffect`,
-// an event handler, a render prop — `Load.Units` calls `renderList` only while the list is non-empty). A test
-// position is not reported: `if (st.use.x())` always runs.
+// Reported: the right operand of `||` / `&&` / `??` and of `||=` / `&&=` / `??=`, a ternary branch, an `if` / `else`
+// body, a `switch` case, a loop (a `for` initializer runs once and is not one), a `catch` block, a default value,
+// the arguments of an optional call, and a callback handed to a call or a JSX prop inside a component, inline or by
+// a camelCase name (`.map`, `useEffect`, an event handler, a render prop — `Load.Units` calls `renderList` only while
+// the list is non-empty). A test position is not reported: `if (st.use.x())` always runs. Each position counts up to
+// the nearest function only, so a component defined in `useMemo` or picked by a module-level ternary is its own
+// render; a PascalCase name is a component, which React renders rather than calls.
 //
 // Not reported: a hook after an early `return` (GritQL sees no statement order), a local helper the component
 // calls (`const tool = (name) => st.tool(name)…exec(…)` runs a fixed number of times when called at top level),
@@ -25,7 +29,15 @@ pattern st_hook_call() {
     `$chain.exec($args)` where { $chain <: r"st\s*\.\s*tool\s*\([\s\S]*" },
     `$chain.card($args)` where { $chain <: r"st\s*\.\s*tool\s*\([\s\S]*" },
     `$chain.init($args)` where { $chain <: r"st\s*\.\s*useState\s*\([\s\S]*" },
-    `$chain.value($args)` where { $chain <: r"st\s*\.\s*expose\s*\([\s\S]*" }
+    `$chain.value($args)` where { $chain <: r"st\s*\.\s*expose\s*\([\s\S]*" },
+    // Computed access (`st["use"].x()`, `st.use[key]()`) at any step, which would take a snippet per combination.
+    JsCallExpression(callee = $callee) where {
+      $callee <: or {
+        r"st\s*(?:\.\s*use|\[\s*[\x27\x22`]use[\x27\x22`]\s*\])\s*(?:\.\s*[\w$]+|\[[^\]]*\])",
+        r"st\s*(?:\.\s*slice|\[\s*[\x27\x22`]slice[\x27\x22`]\s*\])\s*(?:\.\s*[\w$]+|\[[^\]]*\])\s*(?:\.\s*use|\[\s*[\x27\x22`]use[\x27\x22`]\s*\])\s*(?:\.\s*[\w$]+|\[[^\]]*\])",
+        r"st\s*\[\s*[\x27\x22`](?:sel|ref)[\x27\x22`]\s*\]"
+      }
+    }
   }
 }
 
@@ -34,36 +46,95 @@ pattern function_like() {
     JsArrowFunctionExpression(),
     JsFunctionExpression(),
     JsFunctionDeclaration(),
+    JsFunctionExportDefaultDeclaration(),
     JsMethodObjectMember(),
-    JsMethodClassMember()
+    JsGetterObjectMember(),
+    JsSetterObjectMember(),
+    JsMethodClassMember(),
+    JsGetterClassMember(),
+    JsSetterClassMember(),
+    JsConstructorClassMember()
+  }
+}
+
+// An IIFE runs where it stands, so the position around it still decides whether its hooks run.
+pattern function_boundary() {
+  function_like() as $boundary where {
+    not $boundary <: within JsCallExpression(callee = $iifeCallee) where {
+      $iifeCallee <: or { $boundary, JsParenthesizedExpression(expression = $boundary) }
+    }
+  }
+}
+
+pattern callback_slot() {
+  or { JsCallArguments(), JsxExpressionAttributeValue(), JsxExpressionChild() }
+}
+
+pattern passed_by_name($name) {
+  or {
+    JsCallArguments(args = [..., $arg where { $arg <: $name }, ...]),
+    JsxExpressionAttributeValue(expression = $arg) where { $arg <: $name },
+    JsxExpressionChild(expression = $arg) where { $arg <: $name }
   }
 }
 
 JsCallExpression() as $call where {
   $call <: st_hook_call(),
   or {
-    $call <: within JsLogicalExpression(right = $right) where { $right <: contains $call },
+    $call <: within JsLogicalExpression(right = $right) where { $right <: contains $call } until function_boundary(),
+    // The operator token is not a field GritQL can read; `[^=]*` makes the first `=` in the text the operator's.
+    $call <: within JsAssignmentExpression(right = $right) as $assignment where {
+      $assignment <: r"[^=]*(?:\|\||&&|\?\?)=[\s\S]*",
+      $right <: contains $call
+    } until function_boundary(),
     $call <: within JsConditionalExpression(consequent = $then, alternate = $else) where {
       or { $then <: contains $call, $else <: contains $call }
-    },
+    } until function_boundary(),
     $call <: within JsIfStatement(consequent = $then, else_clause = $else) where {
       or { $then <: contains $call, $else <: contains $call }
-    },
-    $call <: within JsForOfStatement(body = $body) where { $body <: contains $call },
-    $call <: within JsForInStatement(body = $body) where { $body <: contains $call },
+    } until function_boundary(),
+    $call <: within JsForStatement(initializer = $init) where { not $init <: contains $call } until function_boundary(),
+    $call <: within JsForOfStatement(body = $body) where { $body <: contains $call } until function_boundary(),
+    $call <: within JsForInStatement(body = $body) where { $body <: contains $call } until function_boundary(),
     $call <: within or {
       JsCaseClause(),
       JsDefaultClause(),
-      JsForStatement(),
       JsWhileStatement(),
       JsDoWhileStatement(),
       JsCatchClause()
-    },
-    // The callback must be handed over inside another function: a component passed to `memo()` / `forwardRef()`
-    // at module level is not one.
-    $call <: within function_like() as $inner where {
-      $inner <: within or { JsCallArguments(), JsxExpressionAttributeValue(), JsxExpressionChild() } as $slot where {
-        $slot <: within function_like()
+    } until function_boundary(),
+    $call <: within or {
+      JsFormalParameter(initializer = $default),
+      JsObjectBindingPatternShorthandProperty(init = $default),
+      JsObjectBindingPatternProperty(init = $default),
+      JsArrayBindingPatternElement(init = $default),
+      JsObjectAssignmentPatternShorthandProperty(init = $default),
+      JsObjectAssignmentPatternProperty(init = $default),
+      JsArrayAssignmentPatternElement(init = $default)
+    } where { $default <: contains $call } until function_boundary(),
+    // A `?.` ahead of the callee's first `(` or `[` sits on its own chain, so a nullish link skips the arguments.
+    $call <: within JsCallExpression(callee = $callee, arguments = $arguments) as $outerCall where {
+      $arguments <: contains $call,
+      or { $outerCall <: `$optionalCallee?.($optionalArgs)`, $callee <: r"[^\[\(]*\?\.[\s\S]*" }
+    } until function_boundary(),
+    and {
+      $call <: within function_boundary() as $nearest until function_boundary(),
+      or {
+        // The callback must be handed over inside another function: a component passed to `memo()` /
+        // `forwardRef()` at module level is not one.
+        $nearest <: within callback_slot() as $slot where { $slot <: within function_boundary() } until function_boundary(),
+        and {
+          or {
+            $nearest <: JsFunctionDeclaration(id = $name),
+            $nearest <: within JsVariableDeclarator(id = $name, initializer = JsInitializerClause(expression = $value)) where {
+              $value <: $nearest
+            } until function_boundary()
+          },
+          $name <: r"[a-z_$][\w$]*",
+          $nearest <: within or { JsFunctionBody(), JsModule() } as $scope where {
+            $scope <: contains passed_by_name($name) as $handover where { $handover <: within function_boundary() }
+          } until or { JsFunctionBody(), JsModule() }
+        }
       }
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.0-rc.26",
+  "version": "3.1.0-rc.27",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -48,7 +48,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.1.0-rc.26",
+    "akanjs": "3.1.0-rc.27",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/subspace.test.ts

@@ -245,7 +245,7 @@ describe("Subspace push", () => {
     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 () => {
+  test("keeps the subspace's own root config and a Jenkinsfile an earlier push left there, never the workspace's", 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");
@@ -261,7 +261,8 @@ describe("Subspace push", () => {
     expect(await FileSys.readText(path.join(subspaceRoot, "akan.config.ts"))).toContain(
       "export default { pipeline: {} };",
     );
-    expect(await FileSys.fileExists(path.join(subspaceRoot, "Jenkinsfile"))).toBe(false);
+    expect(await FileSys.fileExists(path.join(subspaceRoot, "Jenkinsfile"))).toBe(true);
+    expect(await FileSys.readText(path.join(subspaceRoot, "Jenkinsfile"))).toContain("pipeline { agent none }");
   });
 
   test("refuses a lock that resolves from a registry only this machine reaches, before it clones", async () => {

package/subspaceClone.ts

@@ -47,10 +47,6 @@ export class SubspaceClone {
     this.#clone = new Executor(`subspace-${declaration.name}`, this.#clonePath);
   }
 
-  async #cloneGit(args: string[]) {
-    return await this.#workspace.spawn("git", ["-C", this.#clonePath, ...args]);
-  }
-
   async #ensure(branch: string) {
     if (!(await FileSys.dirExists(path.join(this.#clonePath, ".git")))) {
       await rm(this.#clonePath, { recursive: true, force: true });
@@ -160,15 +156,13 @@ export class SubspaceClone {
     await rm(path.join(this.#clonePath, SubspaceClone.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.
+  //* Held even when an earlier push left it, the workspace's Jenkinsfile among them: it is the subspace's only copy.
   async #holdRootEntries() {
     const holdRoot = path.join(this.#clonePath, SubspaceClone.holdDir, "root");
     const held: string[] = [];
     for (const entry of SubspaceClone.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);
@@ -185,11 +179,6 @@ export class SubspaceClone {
     }
   }
 
-  async #isPushedCopy(entry: string) {
-    const subject = await this.#cloneGit(["log", "-1", "--format=%s", "--", entry]).catch(() => "");
-    return subject.trim().startsWith(SubspaceClone.syncSubjectPrefix);
-  }
-
   static async #copyMissing(from: string, to: string) {
     await mkdir(to, { recursive: true });
     for (const entry of await readdir(from, { withFileTypes: true })) {