@akanjs/cli 3.0.0-beta.19 → 3.0.0-beta.20

package/guidelines/conventions/conventions.instruction.md

@@ -216,6 +216,8 @@ Do not narrate code. Do document the thing the code cannot say. Both halves are
 ## Client / Server Boundaries (`apps/**`, `libs/**`, `pkgs/akanjs/**`)
 
 - Use `"use client";` at the top of client component files.
+- A `"use client"` file re-exports by name (`export { A, B } from "./x"`), never with `export *`: the server knows a
+  client module only by the export names it spells out, so `akan start` and `akan build` stop on a star re-export.
 - Be careful when importing client-only code from page or layout modules.
 - Keep page props serializable unless the existing route pattern clearly allows otherwise.
 - In domain UI the boundary is mechanical, not a judgment call: `Template`, `Zone`, and `Util` are always client components with `"use client"` on line 1; `Unit` and `View` are always server components and never carry the directive.
@@ -679,7 +681,9 @@ it.
   (RFC 7591; Cursor's `cursor://` redirect admitted) plus the consent page `libs/shared/page/oauth/consent` — and
   names itself as the issuer, so `/mcp` demands a bearer token, verifies its signature, and refuses one carrying no
   `aud`. A token is the app's own access JWT plus `aud`/`iss`/`client_id`, so `AccountMiddleware` and the guards
-  judge it unchanged; there is no scope. Per-app knobs live in `env.server.*` under `oauth` (`consentPath` and
+  judge it unchanged. The tokens this built-in server mints carry no scope; `auth.scopes` / `AKAN_MCP_SCOPES` are for
+  tokens an external issuer mints, and declared beside this server they refuse every one of its tokens with 403
+  `insufficient_scope`. Per-app knobs live in `env.server.*` under `oauth` (`consentPath` and
   `signinPath` with the basePath, `clients`, `dynamicRegistration`, `allowedRedirectSchemes`, `accessTokenSeconds`,
   `clientIdMetadata`, `enabled`, plus `issuer` / `resource` — set those when a tunnel or an edge makes the derived
   origin wrong, because an MCP client compares the issuer byte for byte). `/mcp` reads the `Authorization` header only — a cookie is dropped at the door — and `JWT_SECRET` (or

package/guidelines/mcpRule/mcpRule.instruction.md

@@ -189,11 +189,13 @@ export default page()
 - OAuth resource metadata is published at `/.well-known/oauth-protected-resource` (and at that path plus the mount
   path, the spelling most clients try first). `auth.authorizationServers` / `AKAN_MCP_AUTH_SERVERS`,
   `auth.scopes` / `AKAN_MCP_SCOPES`, `auth.resource` / `AKAN_MCP_RESOURCE` and `auth.verify` configure it;
-  `insufficient_scope` is enforced only once scopes are declared. Naming an issuer changes three things at once: a
-  request with no credential is answered 401 from `initialize` on (an MCP client starts its OAuth flow on nothing
-  else), a token carrying no `aud` is refused (that issuer mints for its other resources too), and the challenge
-  carries no `error` code (RFC 6750 §3.1 reserves it for a credential that was presented). A server naming no
-  issuer keeps anonymous access and accepts a first-party token, which is bound by app and environment instead.
+  `insufficient_scope` is enforced only once scopes are declared. Declare them only for tokens an external issuer
+  mints: the built-in authorization server's tokens carry no scope, so beside it every one of them would be refused
+  with 403. Naming an issuer changes three things at once: a request with no credential is answered 401 from
+  `initialize` on (an MCP client starts its OAuth flow on nothing else), a token carrying no `aud` is refused (that
+  issuer mints for its other resources too), and the challenge carries no `error` code (RFC 6750 §3.1 reserves it
+  for a credential that was presented). A server naming no issuer keeps anonymous access and accepts a first-party
+  token, which is bound by app and environment instead.
 - **The boot log names every published entry with no dictionary `.desc()`.** An agent picks a tool by its
   description, so a missing one is a broken tool. What the framework generates has no text of its own and borrows
   the model's: the generated list reads the `.of()` label, and the base CRUD tools append the model's `.desc()` to

package/incrementalBuilder.proc.js

@@ -1,22 +1,22 @@
 // @bun
+import {
+  ApplicationBuildReporter,
+  HmrWatcher,
+  WatchRootResolver
+} from "./index-khpfpcsd.js";
 import {
   CodegenLock,
   WorkspaceExecutor,
   AppExecutor
-} from "./index-crmeqnmf.js";
-import"./index-q0y2jq9j.js";
-import"./index-6wwzs1bc.js";
+} from "./index-9d9bgcx4.js";
+import"./index-5b6tavv3.js";
 import {
   GraphClientEntryDiscovery,
   RouteClientBuilder,
   AutoImportSync,
   DevChangePlanner,
   DevGeneratedIndexSync
-} from "./index-89hy31kf.js";
-import {
-  HmrWatcher,
-  WatchRootResolver
-} from "./index-hwkygn9s.js";
+} from "./index-fgq75haa.js";
 import {
   prepareDevWatchBatch
 } from "./index-a5vmm6x4.js";
@@ -30,12 +30,6 @@ import path from "path";
 import { Logger } from "akanjs/common";
 
 class BuildBatchRunner {
-  static #entryCandidates = (workspaceRoot) => [
-    path.join(workspaceRoot, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
-    path.join(workspaceRoot, "node_modules/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
-    path.join(import.meta.dir, "buildBatch.proc.js"),
-    path.join(import.meta.dir, "buildBatch.proc.ts")
-  ];
   #logger = new Logger("BuildBatchRunner");
   #entry = null;
   #workspaceRoot;
@@ -47,7 +41,12 @@ class BuildBatchRunner {
   async#resolveEntry() {
     if (this.#entry)
       return this.#entry;
-    const candidates = BuildBatchRunner.#entryCandidates(this.#workspaceRoot);
+    const candidates = [
+      path.join(this.#workspaceRoot, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      path.join(this.#workspaceRoot, "node_modules/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      path.join(import.meta.dir, "buildBatch.proc.js"),
+      path.join(import.meta.dir, "buildBatch.proc.ts")
+    ];
     for (const candidate of candidates) {
       if (!await Bun.file(candidate).exists())
         continue;
@@ -196,7 +195,7 @@ class IncrementalBuilder {
         }
       };
     } catch (err) {
-      const errMsg = err instanceof Error ? err.message : String(err);
+      const errMsg = ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot);
       this.#logger.error(`build-route failed routeId=${msg.routeId}: ${errMsg}`);
       this.#sendBuildStatus("route", { generation: msg.generation, ok: false, files: msg.seeds, message: errMsg });
       return { type: "build-route-res", id: msg.id, ok: false, error: errMsg };
@@ -336,20 +335,19 @@ class IncrementalBuilder {
     }, 150);
   }
   async installWatcher() {
-    const artifactDir = this.#artifactDir;
     const roots = await new WatchRootResolver(this.#app).resolve();
     const watcher = new HmrWatcher({
       roots,
       logger: this.#logger,
       onBatch: async (batch) => {
-        await this.#enqueueWork("hmr-batch", async () => this.#handleWatchBatch(artifactDir, batch));
+        await this.#enqueueWork("hmr-batch", async () => this.#handleWatchBatch(batch));
       }
     });
     await watcher.start();
     this.#watcher = watcher;
     this.#logger.verbose(`watching ${roots.length} roots`);
   }
-  async#handleWatchBatch(artifactDir, batch) {
+  async#handleWatchBatch(batch) {
     const rawKinds = new Set(batch.kinds);
     if (rawKinds.size === 0)
       return;
@@ -402,7 +400,7 @@ class IncrementalBuilder {
     }
     const needs = [];
     if (kinds.includes("code") && rebuildClient) {
-      if (this.#shouldRebuildCsr())
+      if (this.#csrActive)
         needs.push("csr");
       else
         this.#logger.verbose(`csr-rebundle skipped; request /__csr or ?csr=true (or set AKAN_DEV_CSR_REBUILD=1) to enable per-save CSR rebuilds`);
@@ -417,13 +415,10 @@ class IncrementalBuilder {
       this.#logger.verbose(`css-rebuild scheduled generation=${generation}`);
     }
   }
-  async#runBatch({
-    generation,
-    needs,
-    changedFiles
-  }) {
+  async#runBatch(work) {
+    const { generation, needs, changedFiles } = work;
     const started = Date.now();
-    const result = await this.#batchRunner.run(await this.#batchRequest({ generation, needs, changedFiles }), (msg) => BuilderChannel.emit(msg));
+    const result = await this.#batchRunner.run(await this.#batchRequest(work), (msg) => BuilderChannel.emit(msg));
     if (result.optimizedFonts)
       this.#optimizedFonts = result.optimizedFonts;
     if (result.cssAssets)
@@ -437,11 +432,7 @@ class IncrementalBuilder {
       this.#logger.verbose(`css-rebuild checked (${Date.now() - started}ms)`);
     return result;
   }
-  async#batchRequest({
-    generation,
-    needs,
-    changedFiles
-  }) {
+  async#batchRequest({ generation, needs, changedFiles }) {
     return {
       appName: this.#app.name,
       workspaceRoot: this.#app.workspace.workspaceRoot,
@@ -506,9 +497,6 @@ class IncrementalBuilder {
       await BuilderChannel.send({ type: "build-csr-res", id: msg.id, ok: true });
     });
   }
-  #shouldRebuildCsr() {
-    return this.#csrActive;
-  }
   static #csrArmedByEnv() {
     return process.env.AKAN_DEV_CSR_REBUILD === "1";
   }
@@ -607,23 +595,17 @@ class IncrementalBuilder {
         builder.shutdown(msg.reason);
         return;
       }
-      if (msg.type === "build-route") {
+      if (msg.type !== "build-route" && msg.type !== "build-csr")
+        return;
+      if (!builder || builder.shuttingDown) {
         const error = builder?.shuttingDown ? recyclingError : bootingError;
-        if (!builder || builder.shuttingDown) {
-          BuilderChannel.emit({ type: "build-route-res", id: msg.id, ok: false, error });
-          return;
-        }
-        builder.handleBuildRoute(msg);
+        BuilderChannel.emit({ type: `${msg.type}-res`, id: msg.id, ok: false, error });
         return;
       }
-      if (msg.type === "build-csr") {
-        const error = builder?.shuttingDown ? recyclingError : bootingError;
-        if (!builder || builder.shuttingDown) {
-          BuilderChannel.emit({ type: "build-csr-res", id: msg.id, ok: false, error });
-          return;
-        }
+      if (msg.type === "build-route")
+        builder.handleBuildRoute(msg);
+      else
         builder.handleBuildCsr(msg);
-      }
     });
     process.on("disconnect", () => {
       logger.warn("host IPC channel closed; exiting builder");
@@ -648,7 +630,7 @@ class IncrementalBuilder {
     await builder.rearmCsrFromEnv();
   }
 }
-IncrementalBuilder.main().catch((err) => {
+await IncrementalBuilder.main().catch((err) => {
   console.error(err);
   process.exit(1);
 });

package/{index-s5rhm04y.js → index-0bq14vr1.js}

@@ -1,7 +1,7 @@
 // @bun
 import {
   getDirname2
-} from "./index-6wwzs1bc.js";
+} from "./index-5b6tavv3.js";
 
 // pkgs/@akanjs/devkit/prompter.ts
 import fsPromise from "fs/promises";

package/{index-10dkrrww.js → index-13ffe9wp.js}

@@ -1,16 +1,16 @@
 // @bun
 import {
   jsonText
-} from "./index-2446k7b4.js";
+} from "./index-myhc3c1j.js";
 import {
   akanMcpInstallTargets
-} from "./index-18zybgkc.js";
+} from "./index-ygn77a5w.js";
 import {
   script
-} from "./index-qdgzsnhg.js";
+} from "./index-w2zdcw3k.js";
 import {
   ContextRunner2
-} from "./index-3jrp517k.js";
+} from "./index-nv5976x3.js";
 
 // pkgs/@akanjs/cli/context/context.script.ts
 import { Logger } from "akanjs/common";

package/{index-srmay5jw.js → index-22d57v4c.js}

@@ -1,15 +1,19 @@
 // @bun
 import {
-  FileSys
-} from "./index-q0y2jq9j.js";
+  FileSys2
+} from "./index-5b6tavv3.js";
+import {
+  ConfigLock
+} from "./index-3hx1z96c.js";
 
 // pkgs/@akanjs/devkit/cloud/globalConfig.ts
-import { chmod, mkdir } from "fs/promises";
+import { mkdir, rename, rm, writeFile } from "fs/promises";
 import dayjs from "dayjs";
 
 // pkgs/@akanjs/devkit/cloud/constants.ts
-var basePath = `${Bun.env.HOME ?? Bun.env.USERPROFILE}/.akan`;
-var configPath = `${basePath}/config.json`;
+import path from "path";
+var basePath = path.join(Bun.env.HOME ?? Bun.env.USERPROFILE ?? "", ".akan");
+var configPath = path.join(basePath, "config.json");
 var getDefaultHostConfig = (host = GlobalConfig.akanCloudHost) => ({ host });
 var defaultAkanGlobalConfig = {
   cloudHost: {},
@@ -21,8 +25,8 @@ var defaultAkanGlobalConfig = {
 class GlobalConfig {
   static akanCloudHost = process.env.USE_AKANJS_PKGS === "true" ? `http://localhost:${process.env.CLOUD_HOST_PORT ?? 8283}` : "https://cloud.akanjs.com";
   static async#getAkanGlobalConfig() {
-    const exists = await FileSys.fileExists(configPath);
-    const akanConfig = exists ? await FileSys.readJson(configPath) : {};
+    const exists = await FileSys2.fileExists(configPath);
+    const akanConfig = exists ? await FileSys2.readJson(configPath) : {};
     return {
       ...defaultAkanGlobalConfig,
       ...akanConfig,
@@ -33,50 +37,82 @@ class GlobalConfig {
   }
   static async#setAkanGlobalConfig(akanConfig) {
     await mkdir(basePath, { recursive: true, mode: 448 });
-    await Bun.write(configPath, JSON.stringify(akanConfig, null, 2));
-    await chmod(configPath, 384);
+    const temp = `${configPath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    try {
+      await writeFile(temp, JSON.stringify(akanConfig, null, 2), { mode: 384 });
+      await rename(temp, configPath);
+    } catch (error) {
+      await rm(temp, { force: true });
+      throw error;
+    }
+  }
+  static #lockPath = `${configPath}.lock`;
+  static async#update(mutate) {
+    await ConfigLock.run(GlobalConfig.#lockPath, async () => {
+      await GlobalConfig.#setAkanGlobalConfig(mutate(await GlobalConfig.#getAkanGlobalConfig()));
+    });
   }
   static async getHostConfig(host = GlobalConfig.akanCloudHost) {
     const akanConfig = await GlobalConfig.#getAkanGlobalConfig();
     return GlobalConfig.toHostConfig(akanConfig.cloudHost[host] ?? getDefaultHostConfig(host));
   }
   static async setHostConfig(config = getDefaultHostConfig()) {
-    const akanConfig = await GlobalConfig.#getAkanGlobalConfig();
-    akanConfig.cloudHost[config.host] = GlobalConfig.toHostConfigDto(config);
-    await GlobalConfig.#setAkanGlobalConfig(akanConfig);
+    await GlobalConfig.#update((akanConfig) => GlobalConfig.#withHost(akanConfig, config));
+  }
+  static #withHost(akanConfig, config) {
+    return {
+      ...akanConfig,
+      cloudHost: { ...akanConfig.cloudHost, [config.host]: GlobalConfig.toHostConfigDto(config) }
+    };
+  }
+  static async refreshHostAuth(host, refresh) {
+    try {
+      return await ConfigLock.run(GlobalConfig.#lockPath, async () => {
+        const akanConfig = await GlobalConfig.#getAkanGlobalConfig();
+        const current = GlobalConfig.toHostConfig(akanConfig.cloudHost[host] ?? getDefaultHostConfig(host));
+        const accessToken = current.auth?.accessToken;
+        const refreshToken = accessToken?.refreshToken;
+        if (!accessToken || !refreshToken || !GlobalConfig.needRefreshToken(accessToken))
+          return current;
+        const claimed = {
+          ...current,
+          auth: { ...current.auth, accessToken: { ...accessToken, refreshToken: null } }
+        };
+        await GlobalConfig.#setAkanGlobalConfig(GlobalConfig.#withHost(akanConfig, claimed));
+        const next = await refresh(refreshToken).catch(() => null);
+        if (!next?.jwt)
+          return claimed;
+        const refreshed = { ...current, auth: { ...current.auth, accessToken: next } };
+        await GlobalConfig.#setAkanGlobalConfig(GlobalConfig.#withHost(await GlobalConfig.#getAkanGlobalConfig(), refreshed));
+        return refreshed;
+      });
+    } catch {
+      return await GlobalConfig.getHostConfig(host);
+    }
   }
   static async getRemoteEnvServers() {
-    const akanConfig = await GlobalConfig.#getAkanGlobalConfig();
-    return akanConfig.remoteEnvServers;
+    return (await GlobalConfig.#getAkanGlobalConfig()).remoteEnvServers;
   }
   static async setRemoteEnvServer(name, config) {
-    const akanConfig = await GlobalConfig.#getAkanGlobalConfig();
-    await GlobalConfig.#setAkanGlobalConfig({
+    await GlobalConfig.#update((akanConfig) => ({
       ...akanConfig,
-      remoteEnvServers: {
-        ...akanConfig.remoteEnvServers,
-        [name]: config
-      }
-    });
+      remoteEnvServers: { ...akanConfig.remoteEnvServers, [name]: config }
+    }));
   }
   static async removeRemoteEnvServer(name) {
-    const akanConfig = await GlobalConfig.#getAkanGlobalConfig();
-    const { [name]: _, ...remoteEnvServers } = akanConfig.remoteEnvServers;
-    await GlobalConfig.#setAkanGlobalConfig({
-      ...akanConfig,
-      remoteEnvServers
+    await GlobalConfig.#update((akanConfig) => {
+      const { [name]: _, ...remoteEnvServers } = akanConfig.remoteEnvServers;
+      return { ...akanConfig, remoteEnvServers };
     });
   }
   static async getTestTargets() {
-    const akanConfig = await GlobalConfig.#getAkanGlobalConfig();
-    return akanConfig.testTargets;
+    return (await GlobalConfig.#getAkanGlobalConfig()).testTargets;
   }
   static async setTestTargets(testTargets) {
-    const akanConfig = await GlobalConfig.#getAkanGlobalConfig();
-    await GlobalConfig.#setAkanGlobalConfig({
+    await GlobalConfig.#update((akanConfig) => ({
       ...akanConfig,
       testTargets: { ...akanConfig.testTargets, ...testTargets }
-    });
+    }));
   }
   static needRefreshToken(accessToken) {
     return !!accessToken?.expiresAt?.isBefore(dayjs().add(1, "hour"));
@@ -125,11 +161,7 @@ class HttpClient {
   }
   async get(url, { headers, signal } = {}) {
     const response = await fetch(`${this.baseUrl}${url}`, {
-      headers: {
-        "Content-Type": "application/json",
-        ...this.headers,
-        ...headers
-      },
+      headers: { "Content-Type": "application/json", ...this.headers, ...headers },
       ...signal ? { signal } : {}
     });
     return await HttpClient.#body(response, url);
@@ -172,7 +204,12 @@ class CloudApi {
   url;
   static async fromHost(workspace, host) {
     const hostConfig = await GlobalConfig.getHostConfig(host);
-    return new CloudApi(workspace, hostConfig);
+    const accessToken = hostConfig.auth?.accessToken;
+    if (!accessToken || !GlobalConfig.needRefreshToken(accessToken))
+      return new CloudApi(workspace, hostConfig);
+    const tokenless = new CloudApi(workspace, hostConfig);
+    const refreshed = await GlobalConfig.refreshHostAuth(hostConfig.host, (refreshToken) => tokenless.refreshAuthToken(refreshToken));
+    return new CloudApi(workspace, refreshed);
   }
   constructor(workspace, hostConfig) {
     this.#workspace = workspace;
@@ -181,16 +218,18 @@ class CloudApi {
     this.url = `${this.host}/api`;
     this.#api = new HttpClient(this.url);
     if (this.#accessToken && !GlobalConfig.needRefreshToken(this.#accessToken))
-      this.#api.setHeaders({
-        Authorization: `Bearer ${this.#accessToken.jwt}`
-      });
+      this.#api.setHeaders({ Authorization: `Bearer ${this.#accessToken.jwt}` });
+  }
+  #authorize(accessTokenDto) {
+    this.#accessToken = GlobalConfig.toAccessToken(accessTokenDto);
+    this.#api.setHeaders({ Authorization: `Bearer ${this.#accessToken.jwt}` });
+    return this.#accessToken;
   }
   async uploadEnv(devProjectId, file) {
     const formData = new FormData;
     formData.append("devProjectId", devProjectId);
     formData.append("file", file);
-    const data = await this.#api.post(`/uploadEnv/${devProjectId}`, formData);
-    return data;
+    return await this.#api.post(`/uploadEnv/${devProjectId}`, formData);
   }
   async downloadEnv(devProjectId) {
     const localPath = `${this.#workspace.workspaceRoot}/local/env.tar`;
@@ -199,34 +238,13 @@ class CloudApi {
   }
   async getRemoteAuthToken(remoteId) {
     try {
-      const accessToken = await this.#api.get(`/getRemoteAuthToken/${remoteId}`);
-      this.#accessToken = GlobalConfig.toAccessToken(accessToken);
-      this.#api.setHeaders({
-        Authorization: `Bearer ${this.#accessToken.jwt}`
-      });
-      return this.#accessToken;
+      return this.#authorize(await this.#api.get(`/getRemoteAuthToken/${remoteId}`));
     } catch (_) {
       return null;
     }
   }
-  async#ensureAccessTokenLive({
-    allowUnauthorized = false
-  } = {}) {
-    if (!this.#accessToken)
-      throw new Error("No access token");
-    const needRefresh = GlobalConfig.needRefreshToken(this.#accessToken);
-    if (!needRefresh)
-      return this.#accessToken;
-    const refreshToken = this.#accessToken?.refreshToken;
-    if (!refreshToken)
-      throw new Error("No refresh token");
-    return await this.refreshAuthToken(refreshToken);
-  }
   async refreshAuthToken(refreshToken) {
-    const response = await this.#api.post(`/refreshAuthToken`, { refreshToken });
-    this.#accessToken = GlobalConfig.toAccessToken(response);
-    this.#api.setHeaders({ Authorization: `Bearer ${this.#accessToken.jwt}` });
-    return this.#accessToken;
+    return this.#authorize(await this.#api.post(`/refreshAuthToken`, { refreshToken }, { signal: AbortSignal.timeout(20000) }));
   }
   async requestTunnel(input) {
     return await this.#api.post(`/tunnel/requestTunnel`, input);
@@ -239,8 +257,7 @@ class CloudApi {
   }
   async getRemoteSelf() {
     try {
-      const data = await this.#api.get(`/getRemoteSelf`);
-      return data;
+      return await this.#api.get(`/getRemoteSelf`);
     } catch {
       return null;
     }

package/{index-53176s7j.js → index-31yr441d.js}

@@ -5,33 +5,26 @@ import {
   writeGeneratedSyncState,
   createRepairReport,
   renderRepairReport
-} from "./index-2446k7b4.js";
+} from "./index-myhc3c1j.js";
 import {
   AkanContextAnalyzer
-} from "./index-18zybgkc.js";
+} from "./index-ygn77a5w.js";
 import {
   runner
-} from "./index-qdgzsnhg.js";
+} from "./index-w2zdcw3k.js";
 
 // pkgs/@akanjs/cli/repair/repair.runner.ts
-var commandForShell = (command) => command.startsWith("akan ") ? `bun run ${command}` : command;
+var spawnShell = async (workspace, command) => await workspace.spawn("bash", ["-lc", command.startsWith("akan ") ? `bun run ${command}` : command], {
+  cwd: workspace.workspaceRoot
+});
 var defaultExecutor = (workspace) => async (command) => {
+  const base = { command: command.command, reason: command.reason };
   try {
-    const stdout = await workspace.spawn("bash", ["-lc", commandForShell(command.command)], {
-      cwd: workspace.workspaceRoot
-    });
-    return {
-      command: command.command,
-      reason: command.reason,
-      status: "passed",
-      exitCode: 0,
-      stdout
-    };
+    return { ...base, status: "passed", exitCode: 0, stdout: await spawnShell(workspace, command.command) };
   } catch (error) {
     const commandError = error;
     return {
-      command: command.command,
-      reason: command.reason,
+      ...base,
       status: "failed",
       exitCode: commandError.code ?? 1,
       stdout: commandError.stdout,
@@ -158,4 +151,4 @@ class RepairRunner extends runner("repair") {
   }
 }
 
-export { RepairRunner };
+export { spawnShell, RepairRunner };

package/index-3hx1z96c.js

@@ -0,0 +1,87 @@
+// @bun
+// pkgs/@akanjs/devkit/cloud/configLock.ts
+import { mkdir, open, readFile, rm, stat } from "fs/promises";
+import path from "path";
+
+class ConfigLock {
+  static waitTimeoutMs = 30000;
+  static #unknownHolderStaleMs = 1e4;
+  static #pollMs = 50;
+  static async run(lockPath, fn) {
+    await mkdir(path.dirname(lockPath), { recursive: true, mode: 448 });
+    const deadline = Date.now() + ConfigLock.waitTimeoutMs;
+    while (!await ConfigLock.#take(lockPath)) {
+      if (Date.now() >= deadline) {
+        const holder = (await ConfigLock.#holder(lockPath))?.pid ?? "unknown";
+        throw new Error(`${lockPath} is held by process ${holder}; if no akan command is running, delete it and retry.`);
+      }
+      await ConfigLock.#reclaimIfAbandoned(lockPath);
+      await Bun.sleep(ConfigLock.#pollMs);
+    }
+    try {
+      return await fn();
+    } finally {
+      await rm(lockPath, { force: true });
+    }
+  }
+  static async#take(lockPath) {
+    const handle = await open(lockPath, "wx", 384).catch((error) => {
+      if (error.code === "EEXIST")
+        return null;
+      throw error;
+    });
+    if (!handle)
+      return false;
+    try {
+      await handle.writeFile(JSON.stringify({ pid: process.pid, at: Date.now() }));
+    } finally {
+      await handle.close();
+    }
+    return true;
+  }
+  static async#reclaimIfAbandoned(lockPath) {
+    if (!await ConfigLock.#abandoned(lockPath))
+      return;
+    const guard = `${lockPath}.reclaim`;
+    if (!await ConfigLock.#take(guard)) {
+      if (await ConfigLock.#abandoned(guard))
+        await rm(guard, { force: true });
+      return;
+    }
+    try {
+      if (await ConfigLock.#abandoned(lockPath))
+        await rm(lockPath, { force: true });
+    } finally {
+      await rm(guard, { force: true });
+    }
+  }
+  static async#abandoned(lockPath) {
+    const info = await stat(lockPath).catch(() => null);
+    if (!info)
+      return false;
+    const holder = await ConfigLock.#holder(lockPath);
+    if (!holder)
+      return Date.now() - info.mtimeMs > ConfigLock.#unknownHolderStaleMs;
+    return !ConfigLock.#isAlive(holder.pid);
+  }
+  static async#holder(lockPath) {
+    try {
+      const parsed = JSON.parse(await readFile(lockPath, "utf8"));
+      return typeof parsed.pid === "number" && typeof parsed.at === "number" ? { pid: parsed.pid, at: parsed.at } : null;
+    } catch {
+      return null;
+    }
+  }
+  static #isAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+      return false;
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (error) {
+      return error.code === "EPERM";
+    }
+  }
+}
+
+export { ConfigLock };