akanjs 0.0.1 → 2.0.0-beta.0

package/devkit/frontendBuild/ssrBaseArtifactBuilder.ts

@@ -0,0 +1,139 @@
+import path from "node:path";
+import type { BaseBuildArtifact } from "akanjs/server";
+import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
+import { computeRouteSeedIndex, type RouteSeedIndex, saveRouteSeedIndex } from "../artifact/routeSeedIndex";
+import type { App } from "../commandDecorators";
+import { ClientEntriesBundler } from "./clientEntriesBundler";
+import { CssCompiler } from "./cssCompiler";
+import { FontOptimizer } from "./fontOptimizer";
+import { PagesBundleBuilder } from "./pagesBundleBuilder";
+import { VENDOR_SPECIFIERS, type VendorSpecifier } from "./vendorSpecifiers";
+
+export interface BuildSsrBaseArtifactResult {
+  artifact: BaseBuildArtifact;
+  seedIndex: RouteSeedIndex;
+  cssCompiler: CssCompiler;
+  optimizedFonts: Awaited<ReturnType<FontOptimizer["optimize"]>>;
+}
+
+export class SsrBaseArtifactBuilder {
+  #app: App;
+  #command: "build" | "start";
+  #artifactDir: string;
+  #absArtifactDir: string;
+  #started = Date.now();
+
+  constructor(app: App, command: "build" | "start" = "start") {
+    this.#app = app;
+    this.#command = command;
+    this.#artifactDir = `${command === "build" ? app.dist.cwdPath : app.cwdPath}/.akan/artifact`;
+    this.#absArtifactDir = path.resolve(this.#artifactDir);
+  }
+
+  async build(): Promise<BuildSsrBaseArtifactResult> {
+    const akanConfig = await this.#app.getConfig();
+    const { rscClientUrl, vendorMap } = await this.#buildRuntimeClientEntries();
+    const pageKeys = await this.#app.getPageKeys();
+    this.#app.verbose(`[base-artifact] discovered ${pageKeys.length} route files under ${this.#app.cwdPath}/page`);
+
+    const pageEntries = await resolveSsrPageEntriesForApp(this.#app, pageKeys);
+    const { cssCompiler, optimizedFonts, cssAssets } = await this.#buildStyleAssets();
+    const pagesBundle = await new PagesBundleBuilder(this.#app, this.#command, pageEntries).build();
+    this.#app.verbose(
+      `[base-artifact] pages bundle -> ${pagesBundle.bundlePath} (buildId=${pagesBundle.buildId}, splitting=${pagesBundle.splitting}, entry=${pagesBundle.entryBytes} bytes, outputs=${pagesBundle.outputCount}, chunks=${pagesBundle.chunkCount}, total=${pagesBundle.outputBytes} bytes)`,
+    );
+
+    const seedIndex = computeRouteSeedIndex(pageEntries);
+    const seedIndexPath = await saveRouteSeedIndex(this.#absArtifactDir, seedIndex, {
+      production: this.#command === "build",
+    });
+    this.#app.verbose(
+      `[base-artifact] route seed index -> ${seedIndexPath} entries=${seedIndex.entries.length} globalLayouts=${seedIndex.globalLayoutFiles.length}`,
+    );
+
+    const artifact: BaseBuildArtifact = {
+      rscClientUrl,
+      vendorMap,
+      cssAssets,
+      pagesBundlePath:
+        this.#command === "build"
+          ? path.relative(this.#absArtifactDir, pagesBundle.bundlePath)
+          : pagesBundle.bundlePath,
+      pagesBundleBuildId: pagesBundle.buildId,
+      domains: [...akanConfig.domains],
+      subRoutes: Object.fromEntries(
+        Array.from(akanConfig.subRoutes.entries()).map(([basePath, domains]) => [basePath, [...domains]]),
+      ),
+      basePaths: [...akanConfig.basePaths],
+      branches: [...akanConfig.branches],
+      i18n: akanConfig.i18n,
+      imageConfig: akanConfig.images,
+    };
+    await Bun.write(path.join(this.#absArtifactDir, "base-artifact.json"), `${JSON.stringify(artifact, null, 2)}\n`);
+    this.#app.verbose(`[base-artifact] complete in ${Date.now() - this.#started}ms`);
+
+    return { artifact, seedIndex, cssCompiler, optimizedFonts };
+  }
+
+  async #buildRuntimeClientEntries(): Promise<{ rscClientUrl: string; vendorMap: Record<VendorSpecifier, string> }> {
+    const akanServerPath = await this.#resolveAkanServerPath();
+    const rscClientEntry = `${akanServerPath}/rscClient.tsx`;
+    const vendorEntries = VENDOR_SPECIFIERS.map((specifier) => ({
+      specifier,
+      absPath: `${akanServerPath}/vendor/${specifier.replaceAll("/", "-").replaceAll(".", "-")}.ts`,
+    }));
+    const entries = [rscClientEntry, ...vendorEntries.map((v) => v.absPath)];
+    const clientBundle = await new ClientEntriesBundler({ app: this.#app, entries, command: this.#command }).bundle();
+    const rscClientUrl = clientBundle.entryUrlsByAbsPath.get(rscClientEntry) ?? "";
+    const vendorMap = Object.fromEntries(
+      vendorEntries.map(({ specifier, absPath }) => [specifier, clientBundle.entryUrlsByAbsPath.get(absPath) ?? ""]),
+    ) as Record<VendorSpecifier, string>;
+    this.#app.verbose(`[base-artifact] rscClientUrl=${rscClientUrl} vendors=${Object.keys(vendorMap).length}`);
+    return { rscClientUrl, vendorMap };
+  }
+  async #resolveAkanServerPath() {
+    const candidates = [
+      path.join(this.#app.workspace.workspaceRoot, "pkgs/akanjs/server"),
+      path.resolve(import.meta.dir, "../../server"),
+      path.resolve(import.meta.dir, "../server"),
+    ];
+    for (const candidate of candidates) {
+      if (await Bun.file(path.join(candidate, "rscClient.tsx")).exists()) return candidate;
+    }
+    return candidates[0];
+  }
+
+  async #buildStyleAssets(): Promise<{
+    cssCompiler: CssCompiler;
+    optimizedFonts: Awaited<ReturnType<FontOptimizer["optimize"]>>;
+    cssAssets: BaseBuildArtifact["cssAssets"];
+  }> {
+    const cssCompiler = new CssCompiler(this.#app);
+    const cssByBasePath = await cssCompiler.getCssByBasePath();
+    const optimizedFonts = await new FontOptimizer(this.#app, this.#command).optimize();
+    const cssAssets = Object.fromEntries(
+      await Promise.all(
+        Object.entries(cssByBasePath).flatMap(([basePath, baseCssText]) => {
+          const cssText = [baseCssText, optimizedFonts.css].filter(Boolean).join("\n");
+          if (!cssText) return [];
+          return [this.#writeCssAsset(basePath, cssText)];
+        }),
+      ),
+    );
+    if (optimizedFonts.files.length > 0)
+      this.#app.verbose(`[base-artifact] optimized ${optimizedFonts.files.length} font files`);
+    return { cssCompiler, optimizedFonts, cssAssets };
+  }
+
+  async #writeCssAsset(basePath: string, cssText: string) {
+    const cssAssetName = basePath || "root";
+    const cssHash = Bun.hash(`${basePath}\n${cssText}`).toString(36);
+    const [cssRelPath, cssUrl] = [
+      `styles/${cssAssetName}-${cssHash}.css`,
+      `/_akan/styles/${cssAssetName}-${cssHash}.css`,
+    ];
+    await Bun.write(path.join(this.#absArtifactDir, cssRelPath), cssText);
+    this.#app.verbose(`[base-artifact] wrote ${cssText.length} bytes of CSS for ${basePath} -> ${cssRelPath}`);
+    return [basePath, { cssUrl, cssRelPath }] as const;
+  }
+}

package/devkit/frontendBuild/vendorSpecifiers.ts

@@ -0,0 +1,16 @@
+export const VENDOR_SPECIFIERS = [
+  "react",
+  "react-dom",
+  "react-dom/client",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "react-refresh/runtime",
+  "scheduler",
+  "react-server-dom-webpack/client.browser",
+  "akanjs/store",
+  "akanjs/base",
+  "akanjs/common",
+  "akanjs/constant",
+] as const;
+
+export type VendorSpecifier = (typeof VENDOR_SPECIFIERS)[number];

package/devkit/frontendBuild/watchRootResolver.ts

@@ -0,0 +1,28 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { App } from "../commandDecorators";
+
+export class WatchRootResolver {
+  #app: App;
+
+  constructor(app: App) {
+    this.#app = app;
+  }
+
+  async resolve(): Promise<string[]> {
+    const tsconfig = await this.#app.getTsConfig();
+    const set = new Set<string>();
+    set.add(path.resolve(`${this.#app.cwdPath}/page`));
+    for (const targets of Object.values(tsconfig.compilerOptions.paths ?? {})) {
+      for (const target of targets) {
+        if (!target) continue;
+        if (path.isAbsolute(target)) continue;
+        
+        const cleaned = target.replace(/\/?\*+.*$/, "").replace(/\/[^/]+\.[^/]+$/, "");
+        const resolved = path.resolve(this.#app.workspace.workspaceRoot, cleaned);
+        if (fs.existsSync(resolved)) set.add(resolved);
+      }
+    }
+    return [...set];
+  }
+}

package/devkit/getCredentials.ts

@@ -0,0 +1,19 @@
+import yaml from "js-yaml";
+
+import type { AppExecutor } from "./executors";
+import { FileSys } from "./fileSys";
+
+export interface AppSecret {
+  postgres?: { account?: { user?: { username: string; password: string } } };
+}
+interface Secret {
+  [key: string]: AppSecret;
+}
+
+export const getCredentials = async (app: AppExecutor, environment: string): Promise<AppSecret> => {
+  const content = await FileSys.readText(`${app.workspace.workspaceRoot}/infra/app/values/${app.name}-secret.yaml`);
+  const secret = yaml.load(content) as Secret;
+  const appSecret = secret[environment];
+  if (!appSecret) throw new Error(`No secret found for ${app.name} in ${environment}`);
+  return appSecret;
+};

package/devkit/getDirname.ts

@@ -0,0 +1,3 @@
+import path from "node:path";
+
+export const getDirname = (url: string) => path.dirname(new URL(url).pathname);

package/devkit/getModelFileData.ts

@@ -0,0 +1,59 @@
+interface ModelFileData {
+  moduleType: "lib" | "app";
+  moduleName: string;
+  modelName: string;
+  constantFilePath: string;
+  importModelNames: string[];
+  hasImportScalar: boolean;
+  importLibNames: string[];
+  constantFileStr: string;
+  unitFilePath: string;
+  unitFileStr: string;
+  viewFilePath: string;
+  viewFileStr: string;
+}
+
+export const getModelFileData = async (modulePath: string, modelName: string): Promise<ModelFileData> => {
+  const moduleType = modulePath.startsWith("apps") ? "app" : "lib";
+  const moduleName = modulePath.split("/")[1] ?? "";
+  const constantFilePath = `${modulePath}/lib/${modelName}/${modelName}.constant.ts`;
+  const unitFilePath = `${modulePath}/lib/${modelName}/${modelName}.Unit.tsx`;
+  const viewFilePath = `${modulePath}/lib/${modelName}/${modelName}.View.tsx`;
+  const [constantFileStr, unitFileStr, viewFileStr] = await Promise.all([
+    Bun.file(constantFilePath).text(),
+    Bun.file(unitFilePath).text(),
+    Bun.file(viewFilePath).text(),
+  ]);
+
+  const constantFileLines = constantFileStr.split("\n");
+  const importLibNames = constantFileLines
+    .filter((line) => line.startsWith("import { cnst as "))
+    .map((line) => line.split("cnst as ")[1]?.split(" ")[0] ?? "");
+
+  const importLocalPaths = constantFileLines
+    .filter((line) => line.startsWith("import { ") && line.includes('from "../'))
+    .map((line) => line.split("from ")[1]?.split('"')[1] ?? "");
+
+  const importModelNames = importLocalPaths
+    .map((path) => path.split("/")[1] ?? "")
+    .filter((name) => !name.startsWith("_"));
+
+  const hasImportScalar = !!importLocalPaths
+    .map((path) => path.split("/")[1] ?? "")
+    .filter((name) => name.startsWith("_")).length;
+
+  return {
+    moduleType,
+    moduleName,
+    modelName,
+    constantFilePath,
+    unitFilePath,
+    viewFilePath,
+    importModelNames,
+    hasImportScalar,
+    importLibNames,
+    constantFileStr,
+    unitFileStr,
+    viewFileStr,
+  };
+};

package/devkit/getRelatedCnsts.ts

@@ -0,0 +1,300 @@
+import { readFileSync, realpathSync } from "node:fs";
+import ora from "ora";
+import * as ts from "typescript";
+
+const tsTranspiler = new Bun.Transpiler({ loader: "ts" });
+const tsxTranspiler = new Bun.Transpiler({ loader: "tsx" });
+
+const getTranspiler = (filePath: string) => (filePath.endsWith(".tsx") ? tsxTranspiler : tsTranspiler);
+
+const scanModuleSpecifiers = (source: string, filePath: string, includeExports: boolean) => {
+  const scannedImports = getTranspiler(filePath)
+    .scanImports(source)
+    .map((imp) => imp.path)
+    .filter(Boolean);
+
+  if (includeExports) {
+    const specifiers = new Set(scannedImports);
+    const typeOnlyModuleRegex = /\b(?:import|export)\s+type\s+[\s\S]*?\s+from\s*["']([^"']+)["']/g;
+    for (const match of source.matchAll(typeOnlyModuleRegex)) {
+      const importPath = match[1];
+      if (importPath) specifiers.add(importPath);
+    }
+    const exportFromRegex = /\bexport\s+(?:type\s+)?(?:\*|{[\s\S]*?})\s+from\s*["']([^"']+)["']/g;
+    for (const match of source.matchAll(exportFromRegex)) {
+      const importPath = match[1];
+      if (importPath) specifiers.add(importPath);
+    }
+    return specifiers;
+  }
+
+  const importSpecifiers = new Set<string>();
+  const importDeclarationRegex = /\bimport\s+(?:type\s+)?(?:["']([^"']+)["']|[\s\S]*?\s+from\s*["']([^"']+)["'])/g;
+  for (const match of source.matchAll(importDeclarationRegex)) {
+    const importPath = match[1] ?? match[2];
+    if (importPath && (scannedImports.includes(importPath) || match[0].startsWith("import type"))) {
+      importSpecifiers.add(importPath);
+    }
+  }
+
+  return importSpecifiers;
+};
+
+/**
+ * TypeScript 설정 파일을 읽고 파싱하는 함수
+ */
+export const parseTsConfig = (tsConfigPath: string = "./tsconfig.json") => {
+  const configFile = ts.readConfigFile(tsConfigPath, (path) => {
+    return ts.sys.readFile(path);
+  });
+
+  return ts.parseJsonConfigFileContent(configFile.config, ts.sys, realpathSync(tsConfigPath).replace(/[^/\\]+$/, ""));
+};
+
+/**
+ * 파일 내의 임포트를 기반으로 관련 파일을 수집하는 함수
+ */
+export const collectImportedFiles = (constantFilePath: string, parsedConfig: ts.ParsedCommandLine) => {
+  const allFilesToAnalyze = new Set<string>([constantFilePath]);
+  const analyzedFiles = new Set<string>();
+  const spinner = ora("Collecting related files...");
+  spinner.start();
+
+  function collectImported(filePath: string) {
+    if (analyzedFiles.has(filePath)) return;
+    analyzedFiles.add(filePath);
+
+    const source = readFileSync(filePath, "utf-8");
+    for (const importPath of scanModuleSpecifiers(source, filePath, false)) {
+      if (!importPath.startsWith(".")) continue;
+
+      const resolved = ts.resolveModuleName(importPath, filePath, parsedConfig.options, ts.sys).resolvedModule
+        ?.resolvedFileName;
+
+      if (resolved && !allFilesToAnalyze.has(resolved)) {
+        allFilesToAnalyze.add(resolved);
+        
+        collectImported(resolved);
+      }
+    }
+  }
+
+  collectImported(constantFilePath);
+  spinner.succeed(`Found ${allFilesToAnalyze.size} related files.`);
+
+  return {
+    allFilesToAnalyze,
+    analyzedFiles,
+  };
+};
+
+/**
+ * export 선언을 기반으로 관련 파일을 수집하는 함수
+ */
+export const collectExportedFiles = (constantFilePath: string, parsedConfig: ts.ParsedCommandLine) => {
+  const allFilesToAnalyze = new Set<string>([constantFilePath]);
+  const analyzedFiles = new Set<string>();
+  const spinner = ora("Collecting files from exports...");
+  spinner.start();
+
+  function collectExported(filePath: string) {
+    if (analyzedFiles.has(filePath)) return;
+    analyzedFiles.add(filePath);
+
+    const source = readFileSync(filePath, "utf-8");
+    for (const importPath of scanModuleSpecifiers(source, filePath, true)) {
+      if (!importPath.startsWith(".")) continue;
+
+      const resolved = ts.resolveModuleName(importPath, filePath, parsedConfig.options, ts.sys).resolvedModule
+        ?.resolvedFileName;
+
+      if (resolved && !allFilesToAnalyze.has(resolved)) {
+        allFilesToAnalyze.add(resolved);
+        
+        collectExported(resolved);
+      }
+    }
+  }
+
+  collectExported(constantFilePath);
+  spinner.succeed(`Found ${allFilesToAnalyze.size} related files from exports.`);
+
+  return {
+    allFilesToAnalyze,
+    analyzedFiles,
+  };
+};
+
+/**
+ * TypeScript 프로그램 생성 함수
+ */
+export const createTsProgram = (filePaths: Set<string>, options: ts.CompilerOptions) => {
+  const spinner = ora("Creating TypeScript program for all files...");
+  spinner.start();
+
+  const program = ts.createProgram(Array.from(filePaths), options);
+  const checker = program.getTypeChecker();
+
+  spinner.succeed("TypeScript program created.");
+
+  return {
+    program,
+    checker,
+  };
+};
+
+/**
+ * 심볼 캐싱 및 조회 함수 생성기
+ */
+export const createSymbolCache = (checker: ts.TypeChecker) => {
+  const symbolCache = new Map<string, ts.Symbol | undefined>();
+
+  return (node: ts.Node): ts.Symbol | undefined => {
+    const cacheKey = `${node.getSourceFile().fileName}:${node.pos}:${node.end}`;
+
+    if (!symbolCache.has(cacheKey)) {
+      symbolCache.set(cacheKey, checker.getSymbolAtLocation(node));
+    }
+
+    return symbolCache.get(cacheKey);
+  };
+};
+
+/**
+ * 파일 속성 분석 함수
+ */
+export const analyzeProperties = (filesToAnalyze: Set<string>, program: ts.Program, checker: ts.TypeChecker) => {
+  const propertyMap = new Map<
+    string,
+    {
+      filePath: string;
+      isLibModule: boolean;
+      isImport: boolean;
+      isScalar: boolean;
+      source: string;
+      libName?: string;
+    }
+  >();
+
+  const analyzedFiles = new Set<string>();
+  const sourceLineCache = new Map<string, string[]>();
+  const getCachedSymbol = createSymbolCache(checker);
+
+  const spinner = ora("Analyzing property relationships...");
+  spinner.start();
+
+  function analyzeFileProperties(filePath: string) {
+    if (analyzedFiles.has(filePath)) return;
+    analyzedFiles.add(filePath);
+
+    const source = program.getSourceFile(filePath);
+    if (!source) return;
+
+    if (!sourceLineCache.has(filePath)) {
+      sourceLineCache.set(filePath, source.getFullText().split("\n"));
+    }
+    const sourceLines = sourceLineCache.get(filePath);
+
+    function visit(node: ts.Node) {
+      if (!source) return;
+
+      if (ts.isPropertyAccessExpression(node)) {
+        const left = node.expression;
+        const right = node.name;
+        const { line } = ts.getLineAndCharacterOfPosition(source, node.getStart());
+
+        if (
+          ts.isIdentifier(left) &&
+          sourceLines &&
+          sourceLines.length > line &&
+          sourceLines[line] &&
+          (sourceLines[line]?.includes(`@Field.Prop(() => ${left.text}.${right.text}`) ||
+            sourceLines[line].includes(`base.Filter(${left.text}.${right.text},`))
+        ) {
+          
+          const symbol = getCachedSymbol(right);
+
+          if (symbol?.declarations && symbol.declarations.length > 0) {
+            const key = symbol.declarations[0]?.getSourceFile().fileName.split("/").pop()?.split(".")[0] ?? "";
+            const property = propertyMap.get(key);
+            const isScalar = symbol.declarations[0]?.getSourceFile().fileName.includes("_") ?? false;
+            
+            const symbolFilePath = symbol.declarations[0]
+              ?.getSourceFile()
+              .fileName.replace(`${ts.sys.getCurrentDirectory()}/`, "");
+            if (!symbolFilePath) throw new Error(`No symbol file path found for ${left.text}.${right.text}`);
+
+            if (property) {
+              propertyMap.set(`${left.text}.${right.text}`, {
+                filePath: symbolFilePath,
+                isLibModule: true,
+                isImport: false,
+                libName: left.text,
+                source: readFileSync(symbolFilePath, "utf-8"),
+                isScalar,
+              });
+            } else {
+              propertyMap.set(key, {
+                filePath: symbolFilePath,
+                isLibModule: true,
+                isImport: false,
+                libName: left.text,
+                isScalar,
+                source: readFileSync(symbolFilePath, "utf-8"),
+              });
+            }
+          }
+        }
+      } else if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+        
+        const importPath = node.moduleSpecifier.text;
+
+        if (importPath.startsWith(".")) {
+          const resolved = ts.resolveModuleName(importPath, filePath, program.getCompilerOptions(), ts.sys)
+            .resolvedModule?.resolvedFileName;
+          const moduleName = importPath.split("/").pop()?.split(".")[0] ?? "";
+          const property = propertyMap.get(moduleName);
+          const isScalar = importPath.includes("_");
+
+          if (moduleName && resolved && (!property || property.filePath !== resolved)) {
+            propertyMap.set(moduleName, {
+              filePath: resolved,
+              isLibModule: false,
+              isImport: true,
+              isScalar,
+              source: readFileSync(resolved, "utf-8"),
+            });
+          }
+        }
+      }
+
+      ts.forEachChild(node, visit);
+    }
+
+    visit(source);
+  }
+
+  for (const filePath of filesToAnalyze) {
+    analyzeFileProperties(filePath);
+  }
+
+  spinner.succeed(`Analysis complete. Found ${propertyMap.size} properties.`);
+
+  return propertyMap;
+};
+
+/**
+ * 메인 함수: 상수 파일 관련 요소 분석
+ */
+export const getRelatedCnsts = (constantFilePath: string) => {
+  
+  const parsedConfig = parseTsConfig();
+
+  const { allFilesToAnalyze } = collectImportedFiles(constantFilePath, parsedConfig);
+  
+  const { program, checker } = createTsProgram(allFilesToAnalyze, parsedConfig.options);
+
+  const propertyMap = analyzeProperties(allFilesToAnalyze, program, checker);
+
+  return Array.from(propertyMap.entries()).map(([key, value]) => ({ key, ...value }));
+};

package/devkit/guideline.ts

@@ -0,0 +1,19 @@
+export interface GuideScan {
+  type: "example" | "source" | "usage" | (string & {});
+  description: string;
+  path: string;
+  filterText?: string;
+  sample?: number;
+}
+export interface GuideUpdate {
+  filePath: string;
+  contents: string[];
+  rules: string[];
+}
+export interface GuideGenerateJson {
+  title: string;
+  description: string;
+  scans: GuideScan[];
+  update: GuideUpdate;
+  page?: string;
+}

package/devkit/incrementalBuilder/incrementalBuilder.host.ts

@@ -0,0 +1,78 @@
+import path from "node:path";
+import { Logger } from "akanjs/common";
+import type { BuilderMessage } from "akanjs/server";
+import type { App } from "../commandDecorators";
+
+const builderMsgTypeSet = new Set<BuilderMessage["type"]>([
+  "build-route-res",
+  "builder-ready",
+  "invalidate",
+  "css-updated",
+  "pages-updated",
+]);
+interface IncrementalBuilderHostOptions {
+  app: App;
+  entry: string;
+  env: Record<string, string>;
+  onMessage: (message: BuilderMessage) => void;
+}
+
+export class IncrementalBuilderHost {
+  logger = new Logger("IncrementalBuilderHost");
+  entry: string;
+  env: Record<string, string>;
+  app: App;
+  ready = false;
+  readonly #onMessage: (message: BuilderMessage) => void;
+  #proc: Bun.Subprocess<"ignore", "inherit", "inherit"> | null = null;
+  constructor({ app, entry, env, onMessage }: IncrementalBuilderHostOptions) {
+    this.app = app;
+    this.entry = entry;
+    this.env = env;
+    this.#onMessage = onMessage;
+  }
+  start({ onExit, onReady }: { onExit?: () => void; onReady?: () => void }) {
+    if (this.#proc) this.stop();
+    this.#proc = Bun.spawn(["bun", this.entry], {
+      cwd: this.app.cwdPath,
+      env: { ...this.env, AKAN_WATCH: "1" },
+      stdio: ["ignore", "inherit", "inherit"],
+      ipc: (msg: BuilderMessage) => {
+        if (!msg || typeof msg !== "object") return;
+        if (builderMsgTypeSet.has(msg.type)) this.#onMessage(msg);
+        if (msg.type === "builder-ready" && !this.ready) {
+          this.ready = true;
+          onReady?.();
+        }
+      },
+      serialization: "advanced",
+      onExit: () => {
+        onExit?.();
+      },
+    });
+    this.logger.verbose(`builder spawned pid=${this.#proc.pid} entry=${this.entry}`);
+    return this;
+  }
+  send(message: BuilderMessage) {
+    if (this.#proc) this.#proc.send(message);
+    else this.logger.warn("incrementalBuilderHost is not running");
+  }
+  stop() {
+    if (this.#proc) this.#proc.kill();
+    this.#proc = null;
+    this.ready = false;
+  }
+  static async create(app: App, env: Record<string, string>, onMessage: (message: BuilderMessage) => void) {
+    const candidates = [
+      path.join(app.workspace.workspaceRoot, "pkgs/akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts"),
+      path.join(
+        app.workspace.workspaceRoot,
+        "node_modules/akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts",
+      ),
+      path.join(import.meta.dir, "incrementalBuilder.proc.ts"),
+    ];
+    for (const c of candidates)
+      if (await Bun.file(c).exists()) return new IncrementalBuilderHost({ app, entry: c, env, onMessage });
+    throw new Error(`[cli] frontend builder entry not found; looked in: ${candidates.join(", ")}`);
+  }
+}