@akanjs/devkit 1.0.19 → 2.1.0-rc.0

package/artifact/implicitRootLayout.ts

@@ -0,0 +1,155 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import type { App } from "../commandDecorators";
+
+export interface PageEntry {
+  key: string;
+  moduleAbsPath: string;
+  seedAbsPaths?: string[];
+}
+
+const LAYOUT_KEY_RE = /^\.\/(.+\/)?_layout\.(tsx|ts|jsx|js)$/;
+
+async function appHasStModule(appCwdPath: string): Promise<boolean> {
+  return Bun.file(path.join(appCwdPath, "lib", "st.ts")).exists();
+}
+
+const IMPLICIT_LAYOUT_DIR = path.join(".akan", "generated", "root-layouts");
+
+interface RootBoundary {
+  sourceKey: string | null;
+  sourceAbsPath: string | null;
+  segments: string[];
+}
+
+function getRootBoundarySegments(key: string): string[] | null {
+  const match = LAYOUT_KEY_RE.exec(key);
+  if (!match) return null;
+  const prefix = match[1]?.replace(/\/$/, "");
+  if (!prefix) return [];
+  return prefix.split("/").filter(Boolean);
+}
+
+function implicitRootLayoutKey(segments: string[]): string {
+  return `./${[...segments, "__root_layout"].join("/")}.tsx`;
+}
+
+function implicitRootLayoutAbsPath(appCwdPath: string, segments: string[]): string {
+  const filename = segments.length ? `${segments.join("__")}__root_layout.tsx` : "__root_layout.tsx";
+  return path.join(path.resolve(appCwdPath), IMPLICIT_LAYOUT_DIR, filename);
+}
+
+function isRootBoundarySegments(segments: string[], basePaths: Iterable<string>): boolean {
+  const firstVisibleIndex = segments.findIndex((segment) => !/^\(.+\)$/.test(segment));
+  if (firstVisibleIndex === -1) return segments.length <= 1;
+  if (segments.slice(firstVisibleIndex + 1).some((segment) => /^\(.+\)$/.test(segment))) return false;
+  const visible = segments.slice(firstVisibleIndex);
+  const allowedBasePaths = new Set([...basePaths].map((basePath) => basePath.trim()).filter(Boolean));
+  return visible.length === 1 && (firstVisibleIndex > 0 || allowedBasePaths.has(visible[0] ?? ""));
+}
+
+function findRootBoundaries(pageKeys: string[], appCwdPath: string, basePaths: Iterable<string>): RootBoundary[] {
+  const boundaries = new Map<string, RootBoundary>();
+  for (const key of pageKeys) {
+    const segments = getRootBoundarySegments(key);
+    if (!segments) continue;
+    if (!isRootBoundarySegments(segments, basePaths)) continue;
+    const id = segments.join("/");
+    boundaries.set(id, {
+      sourceKey: key,
+      sourceAbsPath: path.resolve(appCwdPath, "page", key.replace(/^\.\//, "")),
+      segments,
+    });
+  }
+  const hasExplicitRootBoundary = [...boundaries.values()].some((boundary) => boundary.segments.length === 0);
+  if (!hasExplicitRootBoundary && boundaries.size === 0) {
+    boundaries.set("", { sourceKey: null, sourceAbsPath: null, segments: [] });
+  }
+  return [...boundaries.values()].sort((a, b) => a.segments.join("/").localeCompare(b.segments.join("/")));
+}
+
+function routePrefixForSegments(segments: string[]): string | null {
+  const visible = segments.filter((segment) => !/^\(.+\)$/.test(segment));
+  return visible[0] ?? null;
+}
+
+async function assertEnvClientConvention(appCwdPath: string, appName: string) {
+  const envPath = path.join(appCwdPath, "env", "env.client.ts");
+  if (!(await Bun.file(envPath).exists())) {
+    throw new Error(
+      `[route-convention] app "${appName}" must provide env/env.client.ts exporting "env" for generated System.Provider`,
+    );
+  }
+}
+
+async function writeGeneratedRootLayoutFile(opts: {
+  appCwdPath: string;
+  appName: string;
+  boundary: RootBoundary;
+  includeStInit: boolean;
+}): Promise<string> {
+  await assertEnvClientConvention(opts.appCwdPath, opts.appName);
+  const absPath = implicitRootLayoutAbsPath(opts.appCwdPath, opts.boundary.segments);
+  await mkdir(path.dirname(absPath), { recursive: true });
+  const sourceRel = opts.boundary.sourceAbsPath
+    ? path.relative(path.dirname(absPath), opts.boundary.sourceAbsPath).split(path.sep).join("/")
+    : null;
+  const sourceSpecifier = sourceRel ? (sourceRel.startsWith(".") ? sourceRel : `./${sourceRel}`) : null;
+  const clientImport = opts.includeStInit
+    ? `import { st } from "@apps/${opts.appName}/client";\nvoid st;\n`
+    : `import "@apps/${opts.appName}/client";\n`;
+  const prefix = routePrefixForSegments(opts.boundary.segments);
+  const userImport = sourceSpecifier
+    ? `import UserLayout, * as userLayout from ${JSON.stringify(sourceSpecifier)};\n`
+    : "const UserLayout = ({ children }) => children;\nconst userLayout = {};\n";
+  const source = `import type { LayoutProps, PageProps } from "akanjs/client";\nimport { loadFonts } from "akanjs/client";\nimport { System } from "akanjs/ui";\nimport { env } from "@apps/${opts.appName}/env/env.client";\n${clientImport}${userImport}\nconst userFonts = userLayout.fonts ?? [];\nconst defaultFonts = userFonts.filter((font) => font.default);\nif (defaultFonts.length > 1) throw new Error("[route-convention] only one default font is allowed per root layout");\nconst defaultFont = defaultFonts[0];\nconst defaultFontClassName = defaultFont ? (defaultFont.className ?? \`font-\${defaultFont.name}\`) : undefined;\n\nexport async function generateHead(props: PageProps) {\n  if (userLayout.generateHead) return userLayout.generateHead(props);\n  return userLayout.head;\n}\n\nexport default function GeneratedLayout({ children, params, searchParams }: LayoutProps) {\n  return (\n    <System.Provider\n      of={GeneratedLayout as never}\n      appName=${JSON.stringify(opts.appName)}\n      ${prefix ? `prefix=${JSON.stringify(prefix)}\n      ` : ""}params={params}\n      manifest={userLayout.manifest}\n      env={env}\n      theme={userLayout.theme}\n      fonts={loadFonts(userFonts)}\n      className={defaultFontClassName}\n      gaTrackingId={userLayout.gaTrackingId}\n      layoutStyle={userLayout.layoutStyle}\n      reconnect={userLayout.reconnect ?? false}\n    >\n      <UserLayout params={params} searchParams={searchParams}>{children}</UserLayout>\n    </System.Provider>\n  );\n}\n`;
+  await Bun.write(absPath, source);
+  return absPath;
+}
+
+/**
+ * When no root `page/_layout.*` exists on disk, merge a generated implicit root layout
+ * (with generated client runtime registration and optional `void st` when `lib/st.ts` exists).
+ */
+export async function resolveSsrPageEntries(opts: {
+  appCwdPath: string;
+  appName: string;
+  pageKeys: string[];
+  basePaths?: Iterable<string>;
+}): Promise<PageEntry[]> {
+  const absPageDir = path.resolve(opts.appCwdPath, "page");
+  const hasSt = await appHasStModule(opts.appCwdPath);
+  const basePaths = opts.basePaths ?? [];
+  const rootLayoutKeys = new Set(
+    opts.pageKeys.filter((key) => {
+      const segments = getRootBoundarySegments(key);
+      return segments !== null && isRootBoundarySegments(segments, basePaths);
+    }),
+  );
+  const base = opts.pageKeys
+    .filter((key) => !rootLayoutKeys.has(key))
+    .map((key) => ({
+      key,
+      moduleAbsPath: path.resolve(absPageDir, key),
+    }));
+  const generated = await Promise.all(
+    findRootBoundaries(opts.pageKeys, opts.appCwdPath, basePaths).map(async (boundary) => ({
+      key: implicitRootLayoutKey(boundary.segments),
+      moduleAbsPath: await writeGeneratedRootLayoutFile({
+        appCwdPath: opts.appCwdPath,
+        appName: opts.appName,
+        boundary,
+        includeStInit: hasSt && boundary.segments.length === 0,
+      }),
+      seedAbsPaths: boundary.sourceAbsPath ? [boundary.sourceAbsPath] : [],
+    })),
+  );
+  const entries = [...base, ...generated];
+  entries.sort((a, b) => a.key.localeCompare(b.key));
+  return entries;
+}
+
+export async function resolveSsrPageEntriesForApp(app: App, pageKeys: string[]): Promise<PageEntry[]> {
+  const config = await app.getConfig();
+  return resolveSsrPageEntries({ appCwdPath: app.cwdPath, appName: app.name, pageKeys, basePaths: config.basePaths });
+}

package/artifact/index.ts

@@ -0,0 +1 @@
+export * from "./routeSeedIndex";

package/artifact/routeSeedIndex.test.ts

@@ -0,0 +1,98 @@
+import { computeRouteSeedIndex, serializeRouteSeedIndexForArtifact } from "./routeSeedIndex";
+
+describe("computeRouteSeedIndex", () => {
+  test("uses layouts as route client seeds and skips sibling leaf layout ownership", () => {
+    const index = computeRouteSeedIndex([
+      {
+        key: "./__root_layout.tsx",
+        moduleAbsPath: "/app/.akan/generated/root-layouts/__root_layout.tsx",
+        seedAbsPaths: ["/app/page/_layout.tsx"],
+      },
+      {
+        key: "./foo/__root_layout.tsx",
+        moduleAbsPath: "/app/.akan/generated/root-layouts/foo__root_layout.tsx",
+        seedAbsPaths: ["/app/page/foo/_layout.tsx"],
+      },
+      { key: "./foo.tsx", moduleAbsPath: "/app/page/foo.tsx" },
+      { key: "./foo/bar.tsx", moduleAbsPath: "/app/page/foo/bar.tsx" },
+    ]);
+
+    const leaf = index.entries.find((entry) => entry.routeId === "/:lang/foo");
+    expect(leaf?.seeds).toContain("/app/page/foo.tsx");
+    expect(leaf?.seeds).not.toContain("/app/page/foo/_layout.tsx");
+    expect(leaf?.seeds).toContain("/app/.akan/generated/root-layouts/__root_layout.tsx");
+    expect(leaf?.seeds).toContain("/app/page/_layout.tsx");
+
+    expect(() =>
+      computeRouteSeedIndex([
+        { key: "./foo.tsx", moduleAbsPath: "/app/page/foo.tsx" },
+        { key: "./foo/_index.tsx", moduleAbsPath: "/app/page/foo/_index.tsx" },
+      ]),
+    ).toThrow("route conflict");
+  });
+
+  test("keeps special route seeds outside implicit locale", () => {
+    const index = computeRouteSeedIndex([
+      {
+        key: "./__root_layout.tsx",
+        moduleAbsPath: "/app/.akan/generated/root-layouts/__root_layout.tsx",
+        seedAbsPaths: ["/app/page/_layout.tsx"],
+      },
+      { key: "./robots.txt.tsx", moduleAbsPath: "/app/page/robots.txt.tsx" },
+    ]);
+    const robots = index.entries.find((entry) => entry.routeId === "/robots.txt");
+    expect(robots?.seeds).not.toContain("/app/.akan/generated/root-layouts/__root_layout.tsx");
+    expect(robots?.seeds).not.toContain("/app/page/_layout.tsx");
+  });
+
+  test("serializes seed paths relative to the artifact directory", () => {
+    const artifactDir = "/repo/dist/apps/angelo/.akan/artifact";
+    const serialized = serializeRouteSeedIndexForArtifact(
+      {
+        entries: [
+          {
+            routeId: "/profile",
+            pattern: "/profile",
+            seeds: [
+              "/repo/dist/apps/angelo/.akan/generated/implicit-root-layout.tsx",
+              "/repo/apps/angelo/page/profile.tsx",
+            ],
+          },
+        ],
+        globalLayoutFiles: ["/repo/dist/apps/angelo/.akan/generated/implicit-root-layout.tsx"],
+      },
+      artifactDir,
+    );
+
+    expect(serialized.entries[0]?.seeds).toEqual([
+      "../generated/implicit-root-layout.tsx",
+      "../../../../../apps/angelo/page/profile.tsx",
+    ]);
+    expect(serialized.globalLayoutFiles).toEqual(["../generated/implicit-root-layout.tsx"]);
+    expect(JSON.stringify(serialized)).not.toContain("/repo/");
+  });
+
+  test("omits source seed metadata for production artifacts", () => {
+    const artifactDir = "/repo/dist/apps/angelo/.akan/artifact";
+    const serialized = serializeRouteSeedIndexForArtifact(
+      {
+        entries: [
+          {
+            routeId: "/:lang/profile",
+            pattern: "/:lang/profile",
+            seeds: ["/repo/apps/angelo/page/profile.tsx"],
+          },
+        ],
+        globalLayoutFiles: ["/repo/apps/angelo/.akan/generated/implicit-root-layout.tsx"],
+      },
+      artifactDir,
+      { production: true },
+    );
+
+    expect(serialized).toEqual({ entries: [{ routeId: "/:lang/profile" }] });
+    expect(JSON.stringify(serialized)).not.toContain("seeds");
+    expect(JSON.stringify(serialized)).not.toContain("pattern");
+    expect(JSON.stringify(serialized)).not.toContain("globalLayoutFiles");
+    expect(JSON.stringify(serialized)).not.toContain("/repo/");
+  });
+});

package/artifact/routeSeedIndex.ts

@@ -0,0 +1,130 @@
+import path from "node:path";
+import { assertUniqueRoutePatterns, compareRouteSpecificity, parseRouteModuleKey } from "akanjs/common";
+import type { PageEntry } from "./implicitRootLayout";
+
+/**
+ * Build-time utilities for the route seed index. `computeRouteSeedIndex`
+ * takes resolved `PageEntry` rows (`key` plus absolute module path — files
+ * under `app/` or the generated implicit root layout) and produces — for every
+ * route — the list of source files that seed the `"use client"` graph walk.
+ *
+ * The result is serialized to `route-seed-index.json` by
+ * `saveRouteSeedIndex` so the runtime server can call
+ * `loadRouteSeedIndex` to restore it without re-importing `pages.ts`
+ * (which no longer exists) or reparsing loader sources.
+ */
+
+export interface RouteSeedEntry {
+  routeId: string;
+  pattern: string;
+  seeds: string[];
+}
+
+export interface RouteSeedIndex {
+  entries: RouteSeedEntry[];
+  globalLayoutFiles: string[];
+}
+
+export type SerializedRouteSeedEntry = Pick<RouteSeedEntry, "routeId"> &
+  Partial<Pick<RouteSeedEntry, "pattern" | "seeds">>;
+
+export interface SerializedRouteSeedIndex {
+  entries: SerializedRouteSeedEntry[];
+  globalLayoutFiles?: string[];
+}
+
+/**
+ * Compute the route seed index from `PageEntry`s (disk paths or generated
+ * implicit root layout absolute paths).
+ */
+export function computeRouteSeedIndex(pageEntries: PageEntry[]): RouteSeedIndex {
+  const layoutsByPrefix = new Map<string, string[]>();
+  const pagesBySegments: Array<{
+    key: string;
+    pattern: string;
+    segments: string[];
+    files: string[];
+    includeOwnLayout: boolean;
+  }> = [];
+
+  for (const { key, moduleAbsPath, seedAbsPaths } of pageEntries) {
+    const parsed = parseRouteModuleKey(key);
+    const files = [path.resolve(moduleAbsPath), ...(seedAbsPaths ?? []).map((seed) => path.resolve(seed))];
+    if (parsed.kind === "layout") {
+      const prefix = parsed.routeSegments.join("/");
+      const prev = layoutsByPrefix.get(prefix) ?? [];
+      layoutsByPrefix.set(prefix, [...prev, ...files]);
+    } else if (parsed.kind === "page") {
+      pagesBySegments.push({
+        key,
+        pattern: parsed.pattern,
+        segments: parsed.routeSegments,
+        files,
+        includeOwnLayout: parsed.leaf === "_index",
+      });
+    }
+  }
+  assertUniqueRoutePatterns(pagesBySegments);
+
+  const rootLayouts = layoutsByPrefix.get("") ?? [];
+  const globalLayoutFiles = rootLayouts;
+
+  const seedEntries: RouteSeedEntry[] = [];
+  for (const { pattern, segments, files, includeOwnLayout } of pagesBySegments) {
+    const layouts: string[] = [];
+    const maxPrefixLength = includeOwnLayout ? segments.length : Math.max(segments.length - 1, 0);
+    for (let i = 0; i <= maxPrefixLength; i++) {
+      const prefix = segments.slice(0, i).join("/");
+      const layoutFiles = layoutsByPrefix.get(prefix);
+      if (layoutFiles) layouts.push(...layoutFiles);
+    }
+    const seeds = Array.from(new Set([...layouts, ...files]));
+    const routeId = pattern || "/";
+    seedEntries.push({ routeId, pattern: routeId, seeds });
+  }
+  // Static segments must beat `:param` ones at match time, otherwise
+  // `/persona/new` resolves to `[personaId]=new`. Sort once at build time
+  // so the runtime matcher can stay first-match-wins.
+  seedEntries.sort((a, b) => compareRouteSpecificity(a.pattern, b.pattern));
+  return { entries: seedEntries, globalLayoutFiles };
+}
+
+export const ROUTE_SEED_INDEX_JSON = "route-seed-index.json";
+
+export function serializeRouteSeedIndexForArtifact(
+  index: RouteSeedIndex,
+  artifactDir: string,
+  options: { production?: boolean } = {},
+): SerializedRouteSeedIndex {
+  const normalizedArtifactDir = path.resolve(artifactDir);
+  if (options.production) {
+    return {
+      entries: index.entries.map((entry) => ({ routeId: entry.routeId })),
+    };
+  }
+  return {
+    entries: index.entries.map((entry) => ({
+      ...entry,
+      seeds: entry.seeds.map((seed) => serializeArtifactPath(seed, normalizedArtifactDir)),
+    })),
+    globalLayoutFiles: index.globalLayoutFiles.map((file) => serializeArtifactPath(file, normalizedArtifactDir)),
+  };
+}
+
+export async function saveRouteSeedIndex(
+  artifactDir: string,
+  index: RouteSeedIndex,
+  options: { production?: boolean } = {},
+): Promise<string> {
+  const absPath = path.join(path.resolve(artifactDir), ROUTE_SEED_INDEX_JSON);
+  await Bun.write(
+    absPath,
+    `${JSON.stringify(serializeRouteSeedIndexForArtifact(index, artifactDir, options), null, 2)}\n`,
+  );
+  return absPath;
+}
+
+function serializeArtifactPath(artifactPath: string, artifactDir: string): string {
+  if (!path.isAbsolute(artifactPath)) return artifactPath;
+  return path.relative(artifactDir, artifactPath).split(path.sep).join("/");
+}

package/auth.ts

@@ -0,0 +1,41 @@
+import { mkdir } from "node:fs/promises";
+
+import {
+  type AkanGlobalConfig,
+  akanCloudHost,
+  akanCloudUrl,
+  basePath,
+  configPath,
+  defaultAkanGlobalConfig,
+  defaultHostConfig,
+  type HostConfig,
+} from "./constants";
+import { FileSys } from "./fileSys";
+
+export const getAkanGlobalConfig = async () => {
+  const exists = await FileSys.fileExists(configPath);
+  const akanConfig = exists ? await FileSys.readJson<AkanGlobalConfig>(configPath) : defaultAkanGlobalConfig;
+  return akanConfig;
+};
+export const setAkanGlobalConfig = async (akanConfig: AkanGlobalConfig) => {
+  await mkdir(basePath, { recursive: true });
+  await Bun.write(configPath, JSON.stringify(akanConfig, null, 2));
+};
+export const getHostConfig = async (host = akanCloudHost) => {
+  const akanConfig = await getAkanGlobalConfig();
+  return akanConfig.cloudHost[host] ?? defaultHostConfig;
+};
+export const setHostConfig = async (host = akanCloudHost, config: HostConfig = {}) => {
+  const akanConfig = await getAkanGlobalConfig();
+  akanConfig.cloudHost[host] = config;
+  await setAkanGlobalConfig(akanConfig);
+};
+export const getSelf = async (token: string) => {
+  try {
+    const res = await fetch(`${akanCloudUrl}/user/getSelf`, { headers: { Authorization: `Bearer ${token}` } });
+    const user = (await res.json()) as { id: string; nickname: string };
+    return user;
+  } catch (e) {
+    return null;
+  }
+};

package/builder.ts

@@ -0,0 +1,164 @@
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import type { Loader } from "bun";
+import type { Executor } from "./executors";
+import { FileSys } from "./fileSys";
+import type { PackageJson } from "./types";
+
+/** Relative paths under these directories are not used as Bun.build entrypoints (Bun does not expand `**` in entrypoint strings; we scan with {@link Bun.Glob}). */
+const SKIP_ENTRY_DIR_SET = new Set(["node_modules", "dist", "build", ".git", ".next"]);
+
+const assetExtensions = [".css", ".md", ".js", ".png", ".ico", ".svg", ".json", ".template"];
+const assetLoader = Object.fromEntries(assetExtensions.map((ext) => [ext, "file" as const])) satisfies Record<
+  string,
+  Loader
+>;
+
+type BunBuildConfig = Parameters<typeof Bun.build>[0] & { bundle?: boolean };
+type ExportValue = string | string[] | { [condition: string]: ExportValue };
+
+interface BuildOptions {
+  bundle?: boolean;
+  additionalEntryPoints?: string[];
+}
+
+interface BuilderOptions {
+  executor: Executor;
+  distExecutor: Executor;
+  pkgJson: PackageJson;
+  rootPackageJson: PackageJson;
+}
+export class Builder {
+  #executor: Executor;
+  #distExecutor: Executor;
+  #pkgJson: PackageJson;
+
+  constructor({ executor, distExecutor, pkgJson }: BuilderOptions) {
+    this.#executor = executor;
+    this.#distExecutor = distExecutor;
+    this.#pkgJson = pkgJson;
+  }
+  #globEntrypoints(cwd: string, pattern: string): string[] {
+    const glob = new Bun.Glob(pattern);
+    return Array.from(glob.scanSync({ cwd, onlyFiles: true }))
+      .filter((relativePath) => {
+        const segments = relativePath.split(path.sep);
+        return !segments.some((segment) => SKIP_ENTRY_DIR_SET.has(segment));
+      })
+      .map((rel) => path.join(cwd, rel));
+  }
+  #globFiles(cwd: string, pattern = "**/*.*"): string[] {
+    const glob = new Bun.Glob(pattern);
+    return Array.from(glob.scanSync({ cwd, onlyFiles: true })).filter((relativePath) => {
+      const segments = relativePath.split(path.sep);
+      return !segments.some((segment) => SKIP_ENTRY_DIR_SET.has(segment));
+    });
+  }
+
+  #resolveAdditionalEntrypoints(cwd: string, additionalEntryPoints: string[]): string[] {
+    const out: string[] = [];
+    for (const p of additionalEntryPoints) {
+      if (p.includes("*")) {
+        const rel = p.startsWith(`${cwd}/`) || p.startsWith(`${cwd}${path.sep}`) ? p.slice(cwd.length + 1) : p;
+        out.push(...this.#globEntrypoints(cwd, rel));
+      } else out.push(path.isAbsolute(p) ? p : path.join(cwd, p));
+    }
+    return out;
+  }
+  #getBuildOptions({ bundle = false, additionalEntryPoints = [] }: BuildOptions = {}): BunBuildConfig {
+    const cwd = this.#executor.cwdPath;
+    const entrypoints = [
+      ...(bundle ? [path.join(cwd, "index.ts")] : this.#globEntrypoints(cwd, "**/*.{ts,tsx}")),
+      ...this.#resolveAdditionalEntrypoints(cwd, additionalEntryPoints),
+    ];
+    return {
+      root: cwd,
+      entrypoints,
+      bundle,
+      packages: "external",
+      splitting: false,
+      target: this.#pkgJson.bun?.platform,
+      format: "esm",
+      outdir: this.#distExecutor.cwdPath,
+      external: ["react", "react-dom"],
+      loader: assetLoader,
+    };
+  }
+  async #copySourceFiles() {
+    const cwd = this.#executor.cwdPath;
+    for (const relativePath of this.#globFiles(cwd)) {
+      if (relativePath === "package.json") continue;
+      const sourcePath = path.join(cwd, relativePath);
+      const targetPath = path.join(this.#distExecutor.cwdPath, relativePath);
+      await mkdir(path.dirname(targetPath), { recursive: true });
+      await Bun.write(targetPath, Bun.file(sourcePath));
+    }
+  }
+  #toPublishedPath(publishedPath: string, { useSource }: { useSource: boolean }) {
+    const hasDotSlash = publishedPath.startsWith("./");
+    const withoutFormatDir = publishedPath.replace(/^(?:\.\/)?(?:esm|cjs)\//, hasDotSlash ? "./" : "");
+    if (!useSource) return withoutFormatDir;
+    if (!hasDotSlash && withoutFormatDir === publishedPath) return publishedPath;
+    const parsed = path.posix.parse(withoutFormatDir);
+    if (![".js", ".mjs", ".cjs"].includes(parsed.ext)) return withoutFormatDir;
+    const withoutExt = path.posix.join(parsed.dir, parsed.name);
+    const sourcePath = withoutExt.startsWith("./") ? withoutExt.slice(2) : withoutExt;
+    const sourceCandidates = [`${sourcePath}.ts`, `${sourcePath}.tsx`];
+    const matchedSource = sourceCandidates.find((candidate) =>
+      existsSync(path.join(this.#executor.cwdPath, candidate)),
+    );
+    if (!matchedSource) return withoutFormatDir;
+    return hasDotSlash ? `./${matchedSource}` : matchedSource;
+  }
+  #normalizeExports(
+    exportsValue: ExportValue | undefined,
+    { useSource }: { useSource: boolean },
+  ): ExportValue | undefined {
+    if (!exportsValue) return exportsValue;
+    if (typeof exportsValue === "string") return this.#toPublishedPath(exportsValue, { useSource });
+    if (Array.isArray(exportsValue))
+      return exportsValue.map((value) => this.#normalizeExports(value, { useSource }) as string);
+    if (typeof exportsValue !== "object") return exportsValue;
+
+    return Object.fromEntries(
+      Object.entries(exportsValue)
+        .filter(([condition]) => condition !== "require")
+        .map(([condition, value]) => [condition, this.#normalizeExports(value, { useSource })])
+        .filter((entry): entry is [string, ExportValue] => entry[1] !== undefined),
+    );
+  }
+  #getPackageJson({ bundle = false }: BuildOptions = {}): PackageJson {
+    const rootEntry = bundle ? "./index.js" : "./index.ts";
+    const normalizedExports = this.#normalizeExports(this.#pkgJson.exports as ExportValue | undefined, {
+      useSource: !bundle,
+    });
+    return {
+      ...this.#pkgJson,
+      type: "module",
+      main: rootEntry,
+      bin: this.#normalizeExports(this.#pkgJson.bin as ExportValue | undefined, { useSource: !bundle }),
+      exports: {
+        ...((typeof normalizedExports === "object" && !Array.isArray(normalizedExports)
+          ? normalizedExports
+          : {}) as Record<string, ExportValue>),
+        ".": {
+          import: rootEntry,
+          types: bundle ? "./index.d.ts" : "./index.ts",
+        },
+      },
+    };
+  }
+  async build(options: BuildOptions = {}) {
+    if (await FileSys.dirExists(this.#distExecutor.cwdPath))
+      await this.#distExecutor.exec(`rm -rf ${this.#distExecutor.cwdPath}`);
+
+    if (options.bundle) {
+      const buildResult = await Bun.build({ ...this.#getBuildOptions(options) });
+      if (!buildResult.success) throw new AggregateError(buildResult.logs, "Bundle failed");
+    } else await this.#copySourceFiles();
+
+    const pkgPackageJson = this.#getPackageJson(options);
+    await this.#distExecutor.setPackageJson(pkgPackageJson);
+  }
+}

package/capacitor.base.config.ts

@@ -0,0 +1,88 @@
+import os from "node:os";
+import type { CapacitorConfig } from "@capacitor/cli";
+import type { AkanMobileTargetConfig, AppScanResult } from "akanjs";
+
+const getLocalIP = () => {
+  const interfaces = os.networkInterfaces();
+  for (const interfaceName in interfaces) {
+    const iface = interfaces[interfaceName];
+    if (!iface) continue;
+    for (const alias of iface) {
+      if (alias.family === "IPv4" && !alias.internal) return alias.address;
+    }
+  }
+  return "127.0.0.1"; // fallback to localhost if no suitable IP found
+};
+
+const normalizeBasePath = (basePath: string | undefined) => basePath?.replace(/^\/+|\/+$/g, "");
+
+const routeBasePaths = (appInfo: AppScanResult) =>
+  new Set(
+    appInfo.routes
+      .map((route) => route.replace(/^\.\//, "").split("/")[0])
+      .filter((segment): segment is string => !!segment && !segment.startsWith("_") && !segment.startsWith("(")),
+  );
+
+const resolveTarget = (appInfo: AppScanResult, targetName = process.env.AKAN_MOBILE_TARGET) => {
+  const targets = appInfo.akanConfig.mobile.targets;
+  if (!targets || Object.keys(targets).length === 0) throw new Error("Akan mobile target metadata is missing.");
+  if (targetName) {
+    const target = targets[targetName];
+    if (!target) {
+      const basePath = normalizeBasePath(targetName);
+      const [template] = Object.values(targets);
+      if (basePath && template && routeBasePaths(appInfo).has(basePath))
+        return { ...template, name: basePath, basePath };
+      throw new Error(`Akan mobile target '${targetName}' was not found.`);
+    }
+    return target;
+  }
+  const entries = Object.entries(targets);
+  if (entries.length !== 1) throw new Error("AKAN_MOBILE_TARGET is required when multiple mobile targets exist.");
+  return entries[0]?.[1] as AkanMobileTargetConfig;
+};
+
+const localCsrUrl = (ip: string, target: AkanMobileTargetConfig) => {
+  const basePath = normalizeBasePath(target.basePath);
+  const port = process.env.AKAN_PUBLIC_CLIENT_PORT ?? process.env.PORT ?? "8282";
+  return `http://${ip}:${port}/${basePath ? `${basePath}` : ""}?csr=true`;
+};
+
+export const withBase = (
+  configImp: (config: CapacitorConfig, target: AkanMobileTargetConfig) => CapacitorConfig = (config) => config,
+  appData?: AppScanResult,
+  targetName?: string,
+) => {
+  const ip = getLocalIP();
+  const appInfo = appData;
+  if (!appInfo) throw new Error("withBase requires apps/<app>/akan.app.json metadata.");
+  const target = resolveTarget(appInfo, targetName);
+  const baseConfig: CapacitorConfig = {
+    ...target,
+    appId: target.appId,
+    appName: target.appName,
+    webDir: "dist",
+    server:
+      process.env.APP_OPERATION_MODE !== "release"
+        ? {
+            androidScheme: "http",
+            url: localCsrUrl(ip, target),
+            cleartext: true,
+            allowNavigation: [ip, "localhost"],
+          }
+        : {
+            allowNavigation: ["*"],
+          },
+    plugins: {
+      CapacitorCookies: { enabled: true },
+      ...target.plugins,
+    },
+    android: {
+      ...target.android,
+    },
+    ios: {
+      ...target.ios,
+    },
+  };
+  return configImp(baseConfig, target);
+};