@akanjs/devkit 2.3.11-rc.6 → 2.3.11-rc.8

package/akanConfig/akanConfig.ts

@@ -171,9 +171,7 @@ export class AkanAppConfig implements AppConfigResult {
       targets: rawTargets,
       indexPath: _indexPath,
       ...rawMobile
-    } = (mobile ?? {}) as DeepPartial<AkanMobileConfig> & {
-      indexPath?: unknown;
-    };
+    } = (mobile ?? {}) as DeepPartial<AkanMobileConfig> & { indexPath?: unknown };
     const appName = rawMobile.appName ?? this.app.name;
     const appId = rawMobile.appId ?? `com.${this.app.name}.app`;
     const version = rawMobile.version ?? "0.0.1";

package/akanContext.ts

@@ -119,6 +119,10 @@ export type JsonRpcRequest = {
 export type McpFraming = "content-length" | "newline";
 export type AkanMcpMode = "readonly" | "plan" | "apply";
 
+// Coding-agent tools that can host the Akan MCP server. Cursor and Claude Code both read a JSON
+// `mcpServers` map; Codex reads a TOML `[mcp_servers.<name>]` table.
+export type AkanMcpInstallTarget = "cursor" | "claude" | "codex";
+
 export type CursorMcpConfig = {
   mcpServers?: Record<string, unknown>;
 };
@@ -133,17 +137,79 @@ export const resourceList = [
 ];
 
 export const cursorMcpConfigPath = ".cursor/mcp.json";
+// Claude Code reads project-scoped MCP servers from `.mcp.json` at the workspace root.
+export const claudeMcpConfigPath = ".mcp.json";
+// Codex reads project-scoped config (trusted projects) from `.codex/config.toml`.
+export const codexMcpConfigPath = ".codex/config.toml";
+
+export const akanMcpInstallTargets: AkanMcpInstallTarget[] = ["cursor", "claude", "codex"];
+
+export const akanMcpInstallConfigPaths: Record<AkanMcpInstallTarget, string> = {
+  cursor: cursorMcpConfigPath,
+  claude: claudeMcpConfigPath,
+  codex: codexMcpConfigPath,
+};
 
+// `akan mcp` resolves the workspace from process.cwd(), so every launcher must run it from the
+// workspace root. Cursor expands its own ${workspaceFolder} variable. Claude Code does not guarantee
+// the server's cwd but sets CLAUDE_PROJECT_DIR in its environment, so we cd into that at runtime.
+// Codex inherits its own launch cwd (it also discovers .codex/config.toml from cwd), so it runs the
+// command directly and must be started from the workspace root.
 const cursorWorkspaceFolder = "$" + "{workspaceFolder}";
+const claudeProjectDir = "$CLAUDE_PROJECT_DIR";
+
+const akanMcpCommand = (mode: AkanMcpMode, { cd }: { cd?: string } = {}) =>
+  cd ? `cd "${cd}" && akan mcp --mode ${mode}` : `akan mcp --mode ${mode}`;
 
 export const createAkanCursorMcpServer = (mode: AkanMcpMode = "readonly") => ({
   type: "stdio",
   command: "bash",
-  args: ["-lc", `cd "${cursorWorkspaceFolder}" && akan mcp --mode ${mode}`],
+  args: ["-lc", akanMcpCommand(mode, { cd: cursorWorkspaceFolder })],
+});
+
+export const createAkanClaudeMcpServer = (mode: AkanMcpMode = "readonly") => ({
+  type: "stdio",
+  command: "bash",
+  args: ["-lc", akanMcpCommand(mode, { cd: claudeProjectDir })],
 });
 
+// JSON-config targets (Cursor, Claude Code) share the same `mcpServers` entry shape.
+export const createAkanMcpServer = (target: "cursor" | "claude", mode: AkanMcpMode = "readonly") =>
+  target === "cursor" ? createAkanCursorMcpServer(mode) : createAkanClaudeMcpServer(mode);
+
 export const akanCursorMcpServer = createAkanCursorMcpServer();
 
+// Codex config is TOML and we have no TOML serializer, so we build the `[mcp_servers.akan]` table as text.
+export const codexMcpServerTableHeader = "[mcp_servers.akan]";
+export const createAkanCodexMcpServerBlock = (mode: AkanMcpMode = "readonly") =>
+  `${codexMcpServerTableHeader}\ncommand = "bash"\nargs = ["-lc", "${akanMcpCommand(mode)}"]\n`;
+
+// A TOML table runs from its header until the next top-level `[header]` or EOF. We upsert only the
+// akan table and preserve everything else in the file, mirroring the JSON merge behavior.
+const codexAkanTablePattern = /^\[mcp_servers\.akan\][^\n]*\n(?:(?!\[)[^\n]*(?:\n|$))*/m;
+
+export const upsertCodexMcpServerBlock = (
+  existing: string,
+  block: string,
+  { force = false }: { force?: boolean } = {},
+) => {
+  const nextBlock = block.endsWith("\n") ? block : `${block}\n`;
+  const match = existing.match(codexAkanTablePattern);
+  if (!match) {
+    if (!existing.trim()) return nextBlock;
+    return `${existing.replace(/\s*$/, "")}\n\n${nextBlock}`;
+  }
+  if (match[0].trim() === nextBlock.trim()) return existing;
+  if (!force)
+    throw new Error(`${codexMcpConfigPath} already has an "akan" MCP server. Re-run with --force to overwrite it.`);
+  const start = match.index ?? 0;
+  const before = existing.slice(0, start);
+  const after = existing.slice(start + match[0].length);
+  // The matched table absorbed its trailing blank line, so re-insert one before any following table.
+  const separator = after && !after.startsWith("\n") ? "\n" : "";
+  return `${before}${nextBlock}${separator}${after}`;
+};
+
 export const renderDoctorText = (result: AkanDoctorResult) => {
   const lines = [`Akan doctor status: ${result.status}`];
   if (result.diagnostics.length === 0) {
@@ -189,7 +255,6 @@ const generatedFiles = [
   "*/lib/cnst.ts",
   "*/lib/db.ts",
   "*/lib/dict.ts",
-  "*/lib/option.ts",
   "*/lib/sig.ts",
   "*/lib/srv.ts",
   "*/lib/st.ts",

package/capacitorApp.ts

@@ -26,6 +26,7 @@ interface RunIosConfig extends RunConfig {
 interface PrepareConfig extends RunConfig {}
 
 type MobileCommandEnv = Record<string, string | undefined>;
+type IosApnsEnvironment = "development" | "production";
 
 export type IosRunTargetKind = "device" | "simulator";
 export interface IosRunTarget {
@@ -130,6 +131,9 @@ const asString = (value: unknown) => (typeof value === "string" ? value : undefi
 
 const firstString = (...values: unknown[]) => values.find((value): value is string => typeof value === "string");
 
+const resolveIosApnsEnvironment = ({ operation }: Pick<RunConfig, "operation" | "env">): IosApnsEnvironment =>
+  operation === "release" ? "production" : "development";
+
 const scoreIosDeviceTarget = (target: IosRunTarget) => {
   const state = target.state?.toLowerCase() ?? "";
   return (state.includes("available") ? 4 : 0) + (state.includes("wired") ? 2 : 0) + (state.includes("paired") ? 1 : 0);
@@ -486,6 +490,10 @@ export function materializeCapacitorConfig(
   const experimentalConfig = isRecord(experimental) ? experimental : undefined;
   const pluginsConfig = isRecord(plugins) ? plugins : {};
   const keyboardPluginConfig = isRecord(pluginsConfig.Keyboard) ? pluginsConfig.Keyboard : {};
+  const pushNotificationsPluginConfig = isRecord(pluginsConfig.PushNotifications)
+    ? pluginsConfig.PushNotifications
+    : {};
+  const usesPushNotifications = target.permissions?.includes("push") ?? false;
   const config: CapacitorConfig = {
     ...capacitorConfig,
     appId,
@@ -494,6 +502,14 @@ export function materializeCapacitorConfig(
     plugins: {
       CapacitorCookies: { enabled: true },
       ...pluginsConfig,
+      ...(usesPushNotifications || isRecord(pluginsConfig.PushNotifications)
+        ? {
+            PushNotifications: {
+              ...(usesPushNotifications ? { presentationOptions: ["badge", "sound", "alert"] } : {}),
+              ...pushNotificationsPluginConfig,
+            },
+          }
+        : {}),
       Keyboard: {
         resize: "none",
         ...keyboardPluginConfig,
@@ -587,7 +603,7 @@ export class CapacitorApp {
     await this.#prepareTargetAssets();
     await this.#prepareExternalFiles("ios");
     await this.#applyIosMetadata();
-    await this.#applyPermissions();
+    await this.#applyPermissions({ operation, env });
     await this.#applyDeepLinks("ios", { operation, env });
     await this.project.commit();
     await this.#generateAssets({ operation, env });
@@ -749,7 +765,7 @@ export class CapacitorApp {
     await this.#prepareTargetAssets();
     await this.#prepareExternalFiles("android");
     await this.#applyAndroidMetadata();
-    await this.#applyPermissions();
+    await this.#applyPermissions({ operation, env });
     await this.#applyDeepLinks("android", { operation, env });
     await this.project.commit();
     await this.#generateAssets({ operation, env });
@@ -975,12 +991,12 @@ export class CapacitorApp {
     await this.project.android.setVersionCode(this.target.buildNum);
     await this.project.android.setAppName(this.target.appName);
   }
-  async #applyPermissions() {
+  async #applyPermissions({ operation, env }: Pick<RunConfig, "operation" | "env">) {
     for (const permission of this.target.permissions ?? []) {
       if (permission === "camera") await this.addCamera();
       else if (permission === "contacts") await this.addContact();
       else if (permission === "location") await this.addLocation();
-      else if (permission === "push") await this.addPush();
+      else if (permission === "push") await this.addPush({ operation, env });
     }
   }
   async #applyDeepLinks(platform: "ios" | "android", { operation, env }: Pick<RunConfig, "operation" | "env">) {
@@ -996,7 +1012,7 @@ export class CapacitorApp {
         });
         await this.#setUrlSchemesInIos(schemes);
       }
-      if (domains.length > 0) await this.#setAssociatedDomainsInIos(domains);
+      if (domains.length > 0) await this.#setAssociatedDomainsInIos(domains, { operation, env });
       return;
     }
     if (platform === "android") {
@@ -1103,12 +1119,58 @@ export class CapacitorApp {
     this.#setPermissionsInAndroid(["ACCESS_COARSE_LOCATION", "ACCESS_FINE_LOCATION"]);
     this.#setFeaturesInAndroid(["android.hardware.location.gps"]);
   }
-  async addPush() {
+  async addPush({ operation, env }: Pick<RunConfig, "operation" | "env">) {
     await this.#setPermissionInIos({
       userNotificationsUsageDescription: "$(PRODUCT_NAME) uses notifications to keep you updated.",
     });
+    await Promise.all([
+      this.project.ios.updateInfoPlist(this.iosTargetName, "Debug", { UIBackgroundModes: ["remote-notification"] }),
+      this.project.ios.updateInfoPlist(this.iosTargetName, "Release", { UIBackgroundModes: ["remote-notification"] }),
+      this.#writeEntitlementsInIos(this.target.deepLinks?.domains ?? [], { operation, env }),
+      this.#ensurePushAppDelegateInIos(),
+    ]);
     this.#setPermissionsInAndroid(["POST_NOTIFICATIONS"]);
   }
+  async #ensurePushAppDelegateInIos() {
+    const appDelegatePath = path.join(this.app.cwdPath, this.iosProjectPath, "App/AppDelegate.swift");
+    if (!(await Bun.file(appDelegatePath).exists())) return;
+
+    const editor = await FileEditor.create(appDelegatePath);
+    let content = editor.getContent();
+
+    if (!content.includes("import FirebaseCore")) {
+      content = content.replace("import Capacitor", "import Capacitor\nimport FirebaseCore");
+    }
+    if (!content.includes("import FirebaseMessaging")) {
+      content = content.replace("import FirebaseCore", "import FirebaseCore\nimport FirebaseMessaging");
+    }
+    if (!content.includes("FirebaseApp.configure()")) {
+      content = content.replace(/\n(\s*)return true/, "\n$1FirebaseApp.configure()\n\n$1return true");
+    }
+    if (!content.includes("didRegisterForRemoteNotificationsWithDeviceToken")) {
+      const delegateMethods = `
+    func application(_ application: UIApplication,
+                     didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
+        Messaging.messaging().apnsToken = deviceToken
+        NotificationCenter.default.post(
+            name: .capacitorDidRegisterForRemoteNotifications,
+            object: deviceToken
+        )
+    }
+
+    func application(_ application: UIApplication,
+                     didFailToRegisterForRemoteNotificationsWithError error: Error) {
+        NotificationCenter.default.post(
+            name: .capacitorDidFailToRegisterForRemoteNotifications,
+            object: error
+        )
+    }
+`;
+      content = content.replace("\n    func applicationWillResignActive", `${delegateMethods}\n    func applicationWillResignActive`);
+    }
+
+    if (content !== editor.getContent()) await editor.setContent(content).save();
+  }
   async #setPermissionInIos(permissions: { [key: string]: string }) {
     const updateNs = Object.fromEntries(
       Object.entries(permissions).map(([key, value]) => [`NS${capitalize(key)}`, value]),
@@ -1128,24 +1190,37 @@ export class CapacitorApp {
       this.project.ios.updateInfoPlist(this.iosTargetName, "Release", { CFBundleURLTypes: urlTypes }),
     ]);
   }
-  async #setAssociatedDomainsInIos(domains: string[]) {
+  async #setAssociatedDomainsInIos(domains: string[], { operation, env }: Pick<RunConfig, "operation" | "env">) {
+    await this.#writeEntitlementsInIos(domains, { operation, env });
+  }
+  async #writeEntitlementsInIos(domains: string[], runConfig: Pick<RunConfig, "operation" | "env">) {
     const entitlementsRelPath = "App/App.entitlements";
     const entitlementsPath = path.join(this.app.cwdPath, this.iosProjectPath, entitlementsRelPath);
     const values = domains.map((domain) => `applinks:${domain}`);
+    const usesPush = this.target.permissions?.includes("push") ?? false;
+    const apsEnvironment = resolveIosApnsEnvironment(runConfig);
     const body = [
       '<?xml version="1.0" encoding="UTF-8"?>',
       '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
       '<plist version="1.0">',
       "<dict>",
-      "  <key>com.apple.developer.associated-domains</key>",
-      "  <array>",
-      ...values.map((value) => `    <string>${value}</string>`),
-      "  </array>",
+      ...(usesPush ? ["  <key>aps-environment</key>", `  <string>${apsEnvironment}</string>`] : []),
+      ...(values.length > 0
+        ? [
+            "  <key>com.apple.developer.associated-domains</key>",
+            "  <array>",
+            ...values.map((value) => `    <string>${value}</string>`),
+            "  </array>",
+          ]
+        : []),
       "</dict>",
       "</plist>",
       "",
     ].join("\n");
-    await writeFile(entitlementsPath, body);
+    const currentBody = (await Bun.file(entitlementsPath).exists())
+      ? await Bun.file(entitlementsPath).text()
+      : undefined;
+    if (currentBody !== body) await writeFile(entitlementsPath, body);
     await this.#setCodeSignEntitlementsInIos(entitlementsRelPath);
   }
   async #setCodeSignEntitlementsInIos(entitlementsRelPath: string) {
@@ -1236,7 +1311,7 @@ export class CapacitorApp {
     for (const permission of permissions) {
       if (this.#hasPermissionInAndroid(permission)) {
         this.app.logger.info(`${permission} already exists in android`);
-        return this;
+        continue;
       }
       this.app.logger.info(`Adding ${permission} to android`);
       this.project.android
@@ -1253,6 +1328,6 @@ export class CapacitorApp {
     return Array.from(usesPermission).map((permission) => permission.getAttribute("android:name"));
   }
   #hasPermissionInAndroid(permission: string) {
-    return this.#getPermissionsInAndroid().includes(permission);
+    return this.#getPermissionsInAndroid().includes(`android.permission.${permission}`);
   }
 }

package/executors.ts

@@ -10,6 +10,7 @@ import {
 import { readFileSync } from "node:fs";
 import { copyFile, mkdir, readdir as readDirEntries, stat } from "node:fs/promises";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 import {
   capitalize,
   isRouteSourceFile,
@@ -23,6 +24,11 @@ import chalk from "chalk";
 import ts from "typescript";
 import { AkanAppConfig, AkanLibConfig, decreaseBuildNum, increaseBuildNum } from "./akanConfig";
 import { FileSys } from "./fileSys";
+import {
+  createFirebaseMessagingServiceWorker,
+  type FirebaseClientEnvConfig,
+  normalizeFirebaseClientConfig,
+} from "./firebaseMessagingSw";
 import { getDirname } from "./getDirname";
 import { Linter } from "./linter";
 import { AppInfo, LibInfo, PkgInfo, WorkspaceInfo } from "./scanInfo";
@@ -1392,6 +1398,12 @@ export class AppExecutor extends SysExecutor {
       ...routeEnv,
       ...(devPort ? { PORT: devPort, AKAN_PUBLIC_CLIENT_PORT: devPort, AKAN_PUBLIC_SERVER_PORT: devPort } : {}),
     });
+    // `start` spawns subprocesses that carry `env`, but `build` runs its phases in this same process and
+    // reads `process.env` directly. Publish the resolved env here so SSR/CSR bundling (fed by getPublicEnv,
+    // which filters to AKAN_PUBLIC_*) sees AKAN_PUBLIC_APP_NAME — otherwise SSR throws
+    // "environment variable AKAN_PUBLIC_APP_NAME is required". Only AKAN_PUBLIC_* is baked into bundles, so
+    // this does not leak non-public env.
+    if (type === "build") Object.assign(process.env, env);
     return { env };
   }
   #publicEnv: Record<string, string> | null = null;
@@ -1497,8 +1509,28 @@ export class AppExecutor extends SysExecutor {
       writeLib: write,
     })) as AppInfo;
     if (write) await this.syncAssets(scanInfo.getScanResult().libDeps);
+    if (write) await this.#syncFirebaseMessagingSw();
     return scanInfo;
   }
+  //* firebase config 가 있으면 public/firebase-messaging-sw.js 를 1회 생성한다(있으면 스킵).
+  //* 서버 동적 라우트를 대체하는 정적 파일. env.client 파생이라 gitignore 되고 env 별로 재생성된다.
+  async #syncFirebaseMessagingSw() {
+    const swRelPath = "public/firebase-messaging-sw.js";
+    if (await FileSys.fileExists(this.getPath(swRelPath))) return;
+    const envClientPath = path.join(this.cwdPath, "env", "env.client.ts");
+    if (!(await FileSys.fileExists(envClientPath))) return;
+    let firebaseConfig: FirebaseClientEnvConfig | null = null;
+    try {
+      const envUrl = pathToFileURL(envClientPath);
+      envUrl.searchParams.set("t", String(Date.now()));
+      const envModule = (await import(envUrl.href)) as { env?: { firebase?: unknown } };
+      firebaseConfig = normalizeFirebaseClientConfig(envModule.env?.firebase);
+    } catch {
+      return;
+    }
+    if (!firebaseConfig) return;
+    await this.writeFile(swRelPath, createFirebaseMessagingServiceWorker(firebaseConfig), { overwrite: false });
+  }
   async increaseBuildNum() {
     await increaseBuildNum(this);
   }

package/firebaseMessagingSw.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createFirebaseMessagingServiceWorker,
+  normalizeFirebaseClientConfig,
+} from "./firebaseMessagingSw";
+
+describe("normalizeFirebaseClientConfig", () => {
+  test("whitelists client fields and drops secrets / vapidKey", () => {
+    const normalized = normalizeFirebaseClientConfig({
+      apiKey: "public-api-key",
+      authDomain: "example.firebaseapp.com",
+      projectId: "public-project",
+      storageBucket: "public-project.appspot.com",
+      messagingSenderId: "1234567890",
+      appId: "public-app-id",
+      vapidKey: "public-vapid-key",
+      private_key: "SERVER_PRIVATE_KEY_MUST_NOT_LEAK",
+    });
+    expect(normalized).toEqual({
+      apiKey: "public-api-key",
+      authDomain: "example.firebaseapp.com",
+      projectId: "public-project",
+      storageBucket: "public-project.appspot.com",
+      messagingSenderId: "1234567890",
+      appId: "public-app-id",
+    });
+    expect(normalized).not.toHaveProperty("vapidKey");
+    expect(normalized).not.toHaveProperty("private_key");
+  });
+
+  test("returns null when required fields are missing or input is not an object", () => {
+    expect(normalizeFirebaseClientConfig(undefined)).toBe(null);
+    expect(normalizeFirebaseClientConfig(null)).toBe(null);
+    expect(normalizeFirebaseClientConfig("nope")).toBe(null);
+    expect(normalizeFirebaseClientConfig({ apiKey: "only-key" })).toBe(null);
+  });
+});
+
+describe("createFirebaseMessagingServiceWorker", () => {
+  test("inlines client config and imports firebase compat SDK, without leaking secrets", () => {
+    const config = normalizeFirebaseClientConfig({
+      apiKey: "public-api-key",
+      projectId: "public-project",
+      messagingSenderId: "1234567890",
+      appId: "public-app-id",
+      private_key: "SERVER_PRIVATE_KEY_MUST_NOT_LEAK",
+    });
+    const body = createFirebaseMessagingServiceWorker(config);
+    expect(body).toContain("public-api-key");
+    expect(body).toContain("public-project");
+    expect(body).toContain("firebase-messaging-compat.js");
+    expect(body).toContain("onBackgroundMessage");
+    expect(body).toContain("notificationclick");
+    expect(body).not.toContain("SERVER_PRIVATE_KEY_MUST_NOT_LEAK");
+    expect(body).not.toContain("private_key");
+  });
+
+  test("produces a no-op worker (config null) that still registers notificationclick", () => {
+    const body = createFirebaseMessagingServiceWorker(null);
+    // config is null → the importScripts/onBackgroundMessage block is gated by `if (firebaseConfig)` at runtime,
+    // but notificationclick is always registered.
+    expect(body).toContain("const firebaseConfig = null");
+    expect(body).toContain("notificationclick");
+    expect(body).toContain("if (firebaseConfig)");
+  });
+});

package/firebaseMessagingSw.ts

@@ -0,0 +1,74 @@
+ const FIREBASE_WEB_SDK_VERSION = "12.13.0";
+
+export interface FirebaseClientEnvConfig {
+  apiKey: string;
+  authDomain?: string;
+  projectId: string;
+  storageBucket?: string;
+  messagingSenderId: string;
+  appId: string;
+  vapidKey?: string;
+}
+
+//* env.client 의 firebase 설정을 검증하고, 서비스워커에 필요한 필드만 화이트리스트한다.
+//* vapidKey/서버 시크릿 등 나머지 필드는 의도적으로 제외한다(SW 본문에 유출 방지).
+export function normalizeFirebaseClientConfig(config: unknown): FirebaseClientEnvConfig | null {
+  if (!config || typeof config !== "object") return null;
+  const value = config as Partial<Record<keyof FirebaseClientEnvConfig, unknown>>;
+  if (
+    typeof value.apiKey !== "string" ||
+    typeof value.projectId !== "string" ||
+    typeof value.messagingSenderId !== "string" ||
+    typeof value.appId !== "string"
+  ) {
+    return null;
+  }
+  return {
+    apiKey: value.apiKey,
+    ...(typeof value.authDomain === "string" ? { authDomain: value.authDomain } : {}),
+    projectId: value.projectId,
+    ...(typeof value.storageBucket === "string" ? { storageBucket: value.storageBucket } : {}),
+    messagingSenderId: value.messagingSenderId,
+    appId: value.appId,
+  };
+}
+
+//* firebase-messaging-sw.js 생성 코드
+export function createFirebaseMessagingServiceWorker(config: FirebaseClientEnvConfig | null): string {
+  const configJson = JSON.stringify(config);
+  return `/* Generated by Akan.js. Do not edit. */
+const firebaseConfig = ${configJson};
+
+if (firebaseConfig) {
+  importScripts("https://www.gstatic.com/firebasejs/${FIREBASE_WEB_SDK_VERSION}/firebase-app-compat.js");
+  importScripts("https://www.gstatic.com/firebasejs/${FIREBASE_WEB_SDK_VERSION}/firebase-messaging-compat.js");
+
+  firebase.initializeApp(firebaseConfig);
+  const messaging = firebase.messaging();
+
+  const notificationUrl = (payload) =>
+    payload?.data?.url || payload?.fcmOptions?.link || payload?.notification?.click_action;
+
+  messaging.onBackgroundMessage((payload) => {
+    const title = payload?.notification?.title || "";
+    const options = {
+      body: payload?.notification?.body,
+      icon: payload?.notification?.icon,
+      image: payload?.notification?.image,
+      data: {
+        url: notificationUrl(payload),
+        FCM_MSG: payload,
+      },
+    };
+    self.registration.showNotification(title, options);
+  });
+}
+
+self.addEventListener("notificationclick", (event) => {
+  const url = event.notification?.data?.url || event.notification?.data?.FCM_MSG?.data?.url;
+  event.notification?.close();
+  if (!url) return;
+  event.waitUntil(clients.openWindow(url));
+});
+`;
+}

package/index.ts

@@ -18,6 +18,7 @@ export * from "./dependencyScanner";
 export * from "./executors";
 export * from "./extractDeps";
 export * from "./fileSys";
+export * from "./firebaseMessagingSw";
 export * from "./frontendBuild";
 export * from "./getCredentials";
 export * from "./getDirname";

package/lint/no-redeclare-predefined-endpoint.grit

@@ -2,8 +2,10 @@ engine biome(1.0)
 language js(typescript, jsx)
 
 // Every model already gets auto-generated CRUD endpoints in its slice fetch
-// contract (see pkgs/akanjs/fetch/fetchType/sliceFetch.type.ts):
-//   <refName>, light<Model>, create<Model>, update<Model>, remove<Model>.
+// contract (see pkgs/akanjs/fetch/fetchType/sliceFetch.type.ts and
+// pkgs/akanjs/fetch/client/fetchClient.ts):
+//   <refName>, light<Model>, create<Model>, update<Model>, remove<Model>,
+//   view<Model>, edit<Model>, merge<Model>.
 // Re-declaring one of them inside the `endpoint(...)` block of a
 // `<model>.signal.ts` file shadows the framework contract and can pass
 // sync/typecheck/build while failing at runtime, so flag it here.
@@ -15,12 +17,12 @@ language js(typescript, jsx)
   $filename <: r".*/([a-z][a-zA-Z0-9]*)\.signal\.ts"($model),
   or {
     $key <: $model,
-    $key <: r"(?:light|create|update|remove)([A-Z][a-zA-Z0-9]*)"($keyCap) where {
+    $key <: r"(?:light|create|update|remove|view|edit|merge)([A-Z][a-zA-Z0-9]*)"($keyCap) where {
       $keyCap <: $Cap
     }
   },
   register_diagnostic(
     span = $key,
-    message = "This endpoint name collides with an auto-generated CRUD endpoint (<model>, light/create/update/remove<Model>). Rename it or move the logic into the service; do not re-declare predefined endpoints."
+    message = "This endpoint name collides with an auto-generated CRUD endpoint (<model>, light/create/update/remove/view/edit/merge<Model>). Rename it or move the logic into the service; do not re-declare predefined endpoints."
   )
 }

package/lint/no-throw-raw-error.grit

@@ -0,0 +1,40 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Domain code in apps/ and libs/ must not throw a raw `Error`. Throw the typed
+// `Err` instead, which is generated per app/lib by `makeTrans`
+// (pkgs/akanjs/dictionary/trans.ts) and imported via `import { Err } from "../dict"`
+// (or the app/lib client entrypoint). `Err` carries a translatable error key,
+// a status code, and structured payload, so raw `Error` throws lose i18n and
+// HTTP-status handling.
+//
+// The `$msg` metavariable in the argument position leniently matches any arity,
+// so `throw new Error()`, `throw new Error("x")`, and
+// `throw new Error("x", { cause })` are all caught, as is the `new`-less
+// `throw Error(...)` call form. Only real throw statements match — a
+// `new Error(...)` inside a string literal or one that is not thrown is ignored.
+//
+// No autofix: `Err`'s first argument must be a typed dictionary error key
+// (e.g. throw new Err('model.errorKey')), so a mechanical rewrite of an
+// arbitrary message string would not typecheck. Each site must be migrated to a
+// real error key by hand.
+//
+// NOTE: the diagnostic messages below use single quotes in the example on
+// purpose. Escaped double quotes (\") inside a GritQL string trigger a
+// double-unescape bug in Biome 2.4.4 that corrupts the rendered message.
+or {
+  `throw new Error($msg)` as $throw where {
+    register_diagnostic(
+      span = $throw,
+      message = "Do not throw a raw `Error`. Throw the typed `Err` instead (import { Err } from the app/lib dict), e.g. throw new Err('model.errorKey').",
+      severity = "error"
+    )
+  },
+  `throw Error($msg)` as $throw where {
+    register_diagnostic(
+      span = $throw,
+      message = "Do not throw a raw `Error`. Throw the typed `Err` instead (import { Err } from the app/lib dict), e.g. throw new Err('model.errorKey').",
+      severity = "error"
+    )
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.3.11-rc.6",
+  "version": "2.3.11-rc.8",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -32,7 +32,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.3.11-rc.6",
+    "akanjs": "2.3.11-rc.8",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/scanInfo.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { rm } from "node:fs/promises";
 import type {
   AppConfigResult,
   AppScanResult,
@@ -54,6 +55,7 @@ const appRootAllowedFiles = new Set([
   "tsconfig.json",
   "tsconfig.tsbuildinfo",
 ]);
+const generatedRootCapacitorConfigFiles = ["capacitor.config.js", "capacitor.config.json"] as const;
 const appRootAllowedDirs = new Set([
   ".akan",
   "android",
@@ -100,12 +102,17 @@ const isAllowedLibRootFile = (filename: string) =>
   libRootAllowedFiles.has(filename) || rootSignalTestFilePattern.test(filename);
 const getScanPath = (exec: AppExecutor | LibExecutor, relativePath: string) =>
   path.posix.join(`${exec.type}s`, exec.name, relativePath.split(path.sep).join("/"));
+async function clearGeneratedRootCapacitorConfigs(exec: AppExecutor | LibExecutor) {
+  if (exec.type !== "app") return;
+  await Promise.all(generatedRootCapacitorConfigFiles.map((filename) => rm(exec.getPath(filename), { force: true })));
+}
 const getModuleNameFromPath = (kind: ModuleKind, modulePath: string) => {
   const dirname = path.basename(modulePath);
   return kind === "service" ? dirname.replace(/^_+/, "") : dirname;
 };
 
 async function assertScanConvention(exec: AppExecutor | LibExecutor, libRoot: { files: string[]; dirs: string[] }) {
+  await clearGeneratedRootCapacitorConfigs(exec);
   const violations: string[] = [];
   const addViolation = (relativePath: string, reason: string) => {
     violations.push(`${getScanPath(exec, relativePath)}: ${reason}`);

package/workflow/artifacts.ts

@@ -196,7 +196,6 @@ export const generatedFilePathsForTarget = (targetRoot: string, reason = "Genera
   [
     { path: `${targetRoot}/lib/cnst.ts`, action: "sync", reason },
     { path: `${targetRoot}/lib/dict.ts`, action: "sync", reason },
-    { path: `${targetRoot}/lib/option.ts`, action: "sync", reason },
     { path: `${targetRoot}/lib/index.ts`, action: "sync", reason },
   ] satisfies PrimitiveGeneratedFile[];