@akanjs/devkit 1.0.20 → 2.1.0-rc.1

package/applicationBuildRunner.ts

@@ -0,0 +1,302 @@
+import { mkdir, rm } from "node:fs/promises";
+import path from "node:path";
+import type { BunPlugin } from "bun";
+import type {
+  ApplicationBuildPhaseResult,
+  ApplicationBuildProgressReporter,
+  ApplicationBuildResult,
+} from "./applicationBuildReporter";
+import type { App } from "./commandDecorators";
+import { AllRoutesBuilder, CsrArtifactBuilder, precompressArtifacts, SsrBaseArtifactBuilder } from "./frontendBuild";
+import { Spinner } from "./spinner";
+
+export interface TypecheckOptions {
+  clean?: boolean;
+  incremental?: boolean;
+}
+
+export type BuildPhaseId = "prepare" | "typecheck" | "backend" | "ssr" | "csr" | "compress" | "metadata";
+
+export type BuildPhaseResult = ApplicationBuildPhaseResult & { id: BuildPhaseId };
+export type BuildResult = ApplicationBuildResult;
+export type BuildProgressReporter = ApplicationBuildProgressReporter;
+export interface ApplicationBuildRunnerOptions {
+  fast?: boolean;
+  reporter?: BuildProgressReporter;
+}
+export interface BuildOptions {
+  spinner?: boolean;
+}
+export interface BuildPhaseRunOptions {
+  spinner?: boolean;
+}
+
+const BUILD_PHASE_EMOJIS: Record<BuildPhaseId, string> = {
+  prepare: "🧹",
+  typecheck: "🔎",
+  backend: "📦",
+  ssr: "🧭",
+  csr: "🎨",
+  compress: "🗜️",
+  metadata: "📝",
+};
+
+const SSR_RENDER_EXTERNALS = [
+  "react",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "react-dom",
+  "react-dom/server.browser",
+  "react-server-dom-webpack/client.node",
+  "react-server-dom-webpack/client.browser",
+] as const;
+
+const TYPECHECK_WORKER_CODE = `
+import { TypeChecker } from "@akanjs/devkit";
+
+try {
+  const configPath = process.env.AKAN_TYPECHECK_TSCONFIG;
+  if (!configPath) throw new Error("AKAN_TYPECHECK_TSCONFIG is required");
+  const result = TypeChecker.checkProject(configPath);
+  if (result.errors.length > 0) {
+    console.error(result.message);
+    process.exit(1);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+`;
+
+export class ApplicationBuildRunner {
+  #app: App;
+  #fast: boolean;
+  #reporter?: BuildProgressReporter;
+  #startedAt = Date.now();
+  #phases: BuildPhaseResult[] = [];
+
+  constructor(app: App, { fast = false, reporter }: ApplicationBuildRunnerOptions = {}) {
+    this.#app = app;
+    this.#fast = fast;
+    this.#reporter = reporter;
+  }
+
+  async build({ spinner = false }: BuildOptions = {}): Promise<BuildResult> {
+    // serial build is needed because of Bun.build is unstable for parallel build
+    const phaseOptions = { spinner };
+    await this.#runPhase("prepare", "Preparing output directory", () => this.#app.prepareCommand("build"), undefined, {
+      spinner,
+    });
+    if (!this.#fast) await this.#runPhase("typecheck", "Typechecking", () => this.typecheck(), undefined, phaseOptions);
+    await this.#runPhase(
+      "backend",
+      "Compiling backend",
+      () => this.#buildBackend(),
+      (result) => `${result.entrypoints} entrypoints, ${result.outputs} outputs`,
+      phaseOptions,
+    );
+    await this.#runPhase(
+      "ssr",
+      "Building SSR route artifacts",
+      () => this.#buildSsr(),
+      (result) =>
+        result
+          ? `${result.allRoutes.manifest.routeIds.length} routes, ${result.allRoutes.manifest.knownEntries.length} entries`
+          : "skipped",
+      phaseOptions,
+    );
+    await this.#runPhase(
+      "csr",
+      "Building CSR assets",
+      () => this.#buildCsr(),
+      (result) => result?.outputDir ?? "skipped",
+      phaseOptions,
+    );
+    await this.#runPhase(
+      "compress",
+      "Compressing static assets",
+      () => precompressArtifacts(this.#app),
+      (result) =>
+        result.files > 0
+          ? `${result.files} files, ${ApplicationBuildRunner.formatBytes(result.inputBytes)} -> ${ApplicationBuildRunner.formatBytes(result.outputBytes)}`
+          : "no files",
+      phaseOptions,
+    );
+    await this.#runPhase("metadata", "Writing production metadata", () => this.#buildAppMeta(), undefined, {
+      spinner,
+    });
+    return {
+      phases: this.#phases,
+      durationMs: Date.now() - this.#startedAt,
+      outputDir: this.#app.dist.cwdPath,
+      artifactDir: path.join(this.#app.dist.cwdPath, ".akan/artifact"),
+    };
+  }
+
+  async typecheck(options: TypecheckOptions = {}) {
+    const { clean = false, incremental = true } = options;
+    await this.#app.getPageKeys({ refresh: true });
+    const { typecheckDir, tsconfigPath } = await this.#writeTypecheckTsconfig({ incremental });
+    if (clean) await rm(path.join(typecheckDir, "tsconfig.tsbuildinfo"), { force: true });
+    await this.#checkProjectInChildProcess(tsconfigPath);
+  }
+
+  async #runPhase<T>(
+    id: BuildPhaseId,
+    label: string,
+    task: () => Promise<T>,
+    summarize?: (result: T) => string | undefined,
+    options: BuildPhaseRunOptions = {},
+  ) {
+    this.#reporter?.phaseStart?.({ id, label });
+    const phaseStartedAt = Date.now();
+    const spinner = options.spinner
+      ? new Spinner(label, { prefix: `${BUILD_PHASE_EMOJIS[id]} ${id}` }).start()
+      : undefined;
+    try {
+      const result = await task();
+      const phase = { id, label, durationMs: Date.now() - phaseStartedAt, summary: summarize?.(result) };
+      this.#phases.push(phase);
+      const summary = phase.summary ? `: ${phase.summary}` : "";
+      spinner?.succeed(`${label}${summary}`);
+      this.#reporter?.phaseDone?.(phase);
+      return result;
+    } catch (error) {
+      spinner?.fail(`${label} failed`);
+      this.#reporter?.phaseFail?.({ id, label }, error);
+      throw error;
+    }
+  }
+
+  async #buildAppMeta() {
+    const akanConfig = await this.#app.getConfig();
+    await Promise.all([
+      this.#app.dist.writeJson("package.json", akanConfig.getProductionPackageJson()),
+      this.#app.dist.writeFile(`${this.#app.dist.cwdPath}/Dockerfile`, akanConfig.docker.content),
+    ]);
+  }
+
+  async #buildBackend() {
+    const akanConfig = await this.#app.getConfig();
+    const backendExternals = [...new Set([...akanConfig.externalLibs, ...SSR_RENDER_EXTERNALS])];
+    const backendEntryPoints = [`${this.#app.cwdPath}/main.ts`, `${this.#app.cwdPath}/server.ts`];
+    for (const entrypoint of backendEntryPoints) {
+      if (!(await Bun.file(entrypoint).exists())) throw new Error(`Backend entrypoint not found: ${entrypoint}`);
+    }
+    const backendResult = await this.#buildOrThrow("backend", {
+      entrypoints: backendEntryPoints,
+      outdir: this.#app.dist.cwdPath,
+      target: "bun",
+      minify: true,
+      define: { "process.env.NODE_ENV": JSON.stringify("production") },
+      plugins: backendExternals.length > 0 ? [this.#createExternalSpecifiersPlugin(backendExternals)] : [],
+    });
+    const rscWorkerResult = await this.#buildOrThrow("rsc-worker", {
+      entrypoints: [this.#resolveRscWorkerBuildEntry()],
+      outdir: this.#app.dist.cwdPath,
+      target: "bun",
+      minify: true,
+      naming: { entry: "[name].[ext]", chunk: "chunk-[hash].[ext]" },
+      conditions: ["react-server"],
+      // `akan build` must embed production react-server-dom regardless of the shell's NODE_ENV.
+      define: { "process.env.NODE_ENV": JSON.stringify("production") },
+      plugins:
+        akanConfig.externalLibs.length > 0 ? [this.#createExternalSpecifiersPlugin(akanConfig.externalLibs)] : [],
+    });
+    return {
+      entrypoints: backendEntryPoints.length + 1,
+      outputs: backendResult.outputs.length + rscWorkerResult.outputs.length,
+    };
+  }
+
+  #resolveRscWorkerBuildEntry(): string {
+    try {
+      return Bun.resolveSync("akanjs/server/rsc-worker", import.meta.dir);
+    } catch {
+      return path.join(this.#app.workspace.workspaceRoot, "pkgs/akanjs/server/rscWorker.tsx");
+    }
+  }
+
+  async #buildCsr() {
+    return await new CsrArtifactBuilder(this.#app, "build").build();
+  }
+
+  async #buildSsr() {
+    const pageKeys = await this.#app.getPageKeys();
+    if (pageKeys.length === 0) {
+      this.#app.log(`[cli] no route files under ${this.#app.cwdPath}/page — skipping SSR build`);
+      return null;
+    }
+    const base = await new SsrBaseArtifactBuilder(this.#app, "build").build();
+    const allRoutes = await new AllRoutesBuilder(this.#app, base.artifact, "build").build();
+    return { base, allRoutes };
+  }
+
+  async #writeTypecheckTsconfig({ incremental = true }: TypecheckOptions = {}) {
+    const typecheckDir = path.join(this.#app.cwdPath, ".akan", "typecheck");
+    await mkdir(typecheckDir, { recursive: true });
+    const tsconfig = {
+      extends: "../../tsconfig.json",
+      compilerOptions: {
+        noEmit: true,
+        incremental,
+        tsBuildInfoFile: "./tsconfig.tsbuildinfo",
+      },
+      include: [
+        "../../main.ts",
+        "../../server.ts",
+        "../../client.ts",
+        "../../page/**/*.ts",
+        "../../page/**/*.tsx",
+        "../../../../pkgs/akanjs/*/types/**/*.d.ts",
+      ],
+      references: [],
+    };
+    const tsconfigPath = path.join(typecheckDir, "tsconfig.json");
+    await Bun.write(tsconfigPath, `${JSON.stringify(tsconfig, null, 2)}\n`);
+    return { typecheckDir, tsconfigPath };
+  }
+
+  async #checkProjectInChildProcess(tsconfigPath: string) {
+    const proc = Bun.spawn([process.execPath, "--eval", TYPECHECK_WORKER_CODE], {
+      cwd: this.#app.workspace.workspaceRoot,
+      env: this.#app.getCommandEnv({
+        AKAN_COMMAND_TYPE: "typecheck",
+        AKAN_TYPECHECK_TSCONFIG: tsconfigPath,
+      }),
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    if (exitCode !== 0) throw new Error((stderr || stdout).trim() || `Typecheck failed with exit code ${exitCode}`);
+  }
+
+  async #buildOrThrow(label: string, config: Bun.BuildConfig): Promise<Bun.BuildOutput> {
+    const result = await Bun.build(config);
+    if (!result.success) throw new AggregateError(result.logs, `[${label}] Bun.build failed`);
+    return result;
+  }
+
+  #createExternalSpecifiersPlugin(specifiers: readonly string[]): BunPlugin {
+    const uniqueSpecifiers = [...new Set(specifiers)];
+    const escaped = uniqueSpecifiers.map((specifier) => specifier.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    const filter = new RegExp(`^(${escaped.join("|")})(?:/.*)?$`);
+
+    return {
+      name: "akan-backend-externalize-specifiers",
+      setup(build) {
+        build.onResolve({ filter }, (args) => ({ path: args.path, external: true }));
+      },
+    };
+  }
+
+  static formatBytes(bytes: number): string {
+    if (bytes < 1024) return `${bytes}B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+  }
+}

package/applicationReleasePackager.ts

@@ -0,0 +1,206 @@
+import { cp, mkdir, rm } from "node:fs/promises";
+import type { App } from "./commandDecorators";
+import { FileSys } from "./fileSys";
+import { uploadRelease } from "./uploadRelease";
+
+export interface ReleaseSourceOptions {
+  rebuild?: boolean;
+  buildNum?: number;
+  environment?: string;
+  local?: boolean;
+}
+
+interface ApplicationReleasePackagerOptions {
+  build: () => Promise<void>;
+}
+
+export class ApplicationReleasePackager {
+  #app: App;
+  #build: () => Promise<void>;
+
+  constructor(app: App, options: ApplicationReleasePackagerOptions) {
+    this.#app = app;
+    this.#build = options.build;
+  }
+
+  async releaseSource({
+    rebuild,
+    buildNum = 0,
+    environment = "debug",
+    local = true,
+  }: ReleaseSourceOptions = {}): Promise<void> {
+    const { platformVersion } = await this.#prepareReleaseBuild({ rebuild, buildNum });
+    await this.#writeSourceArchive({ readme: this.#confidentialReadme() });
+    await uploadRelease(this.#app.name, {
+      local,
+      buildNum,
+      environment,
+      platformVersion,
+      workspaceRoot: this.#app.workspace.cwdPath,
+    });
+  }
+
+  async compressProjectFiles({ rebuild, buildNum = 0 }: ReleaseSourceOptions = {}): Promise<void> {
+    await this.#prepareReleaseBuild({ rebuild, buildNum });
+    await this.#writeSourceArchive({ readme: this.#publicReadme() });
+  }
+
+  async #prepareReleaseBuild({ rebuild, buildNum }: { rebuild?: boolean; buildNum: number }) {
+    const akanConfig = await this.#app.getConfig();
+    const platformVersion = akanConfig.mobile.version;
+    const buildRoot = `${this.#app.workspace.workspaceRoot}/releases/builds/${this.#app.name}`;
+    if (await FileSys.dirExists(buildRoot)) await rm(buildRoot, { recursive: true, force: true });
+    await mkdir(buildRoot, { recursive: true });
+    if (rebuild || !(await FileSys.dirExists(`${this.#app.dist.cwdPath}/backend`))) await this.#build();
+
+    const buildVersion = `${platformVersion}-${buildNum}`;
+    const buildPath = `${buildRoot}/${buildVersion}`;
+    await mkdir(buildPath, { recursive: true });
+    await cp(`${this.#app.dist.cwdPath}/backend`, `${buildPath}/backend`, { recursive: true });
+
+    await cp(this.#app.dist.cwdPath, buildRoot, { recursive: true });
+    await rm(`${buildRoot}/frontend/.next`, { recursive: true, force: true });
+
+    await this.#app.workspace.spawn("tar", [
+      "-zcf",
+      `${this.#app.workspace.workspaceRoot}/releases/builds/${this.#app.name}-release.tar.gz`,
+      "-C",
+      buildRoot,
+      "./",
+    ]);
+    await this.#writeCsrZipIfPresent();
+    return { platformVersion };
+  }
+
+  async #writeCsrZipIfPresent(): Promise<void> {
+    if (!(await FileSys.dirExists(`${this.#app.dist.cwdPath}/csr`))) return;
+    await cp(`${this.#app.dist.cwdPath}/csr`, "./csr", { recursive: true });
+    await this.#app.workspace.spawn("zip", [
+      "-r",
+      `${this.#app.workspace.workspaceRoot}/releases/builds/${this.#app.name}-appBuild.zip`,
+      "./csr",
+    ]);
+    await rm("./csr", { recursive: true, force: true });
+  }
+
+  async #writeSourceArchive({ readme }: { readme: string }): Promise<void> {
+    const sourceRoot = `${this.#app.workspace.workspaceRoot}/releases/sources/${this.#app.name}`;
+    await this.#resetSourceRoot(sourceRoot);
+    await cp(this.#app.dist.cwdPath, `${sourceRoot}/apps/${this.#app.name}`, { recursive: true });
+
+    const libDeps = ["social", "shared", "platform", "util"];
+    await Promise.all(
+      libDeps.map((lib) =>
+        cp(`${this.#app.workspace.cwdPath}/libs/${lib}`, `${sourceRoot}/libs/${lib}`, { recursive: true }),
+      ),
+    );
+    await Promise.all(
+      [".next", "ios", "android", "public/libs"].map(async (path) => {
+        const targetPath = `${sourceRoot}/apps/${this.#app.name}/${path}`;
+        if (await FileSys.dirExists(targetPath)) await rm(targetPath, { recursive: true, force: true });
+      }),
+    );
+
+    const syncPaths = [".husky", ".gitignore", "package.json"];
+    await Promise.all(
+      syncPaths.map((path) =>
+        cp(`${this.#app.workspace.cwdPath}/${path}`, `${sourceRoot}/${path}`, { recursive: true }),
+      ),
+    );
+    await this.#writeSourceTsconfig(sourceRoot, libDeps);
+    await Bun.write(`${sourceRoot}/README.md`, readme);
+    await this.#app.workspace.spawn("tar", [
+      "-zcf",
+      `${this.#app.workspace.cwdPath}/releases/sources/${this.#app.name}-source.tar.gz`,
+      "-C",
+      sourceRoot,
+      "./",
+    ]);
+  }
+
+  async #resetSourceRoot(sourceRoot: string): Promise<void> {
+    if (await FileSys.dirExists(sourceRoot)) {
+      const maxRetry = 3;
+      for (let i = 0; i < maxRetry; i++) {
+        try {
+          await rm(sourceRoot, { recursive: true, force: true });
+        } catch {
+          //
+        }
+      }
+    }
+    await mkdir(sourceRoot, { recursive: true });
+  }
+
+  async #writeSourceTsconfig(sourceRoot: string, libDeps: string[]): Promise<void> {
+    const tsconfig = (await this.#app.workspace.readJson("tsconfig.json")) as {
+      compilerOptions: { paths: Record<string, string[]> };
+    };
+    const pathEntries: [string, string[]][] = [[`@${this.#app.name}/*`, [`apps/${this.#app.name}/*`]]];
+    for (const lib of libDeps) {
+      pathEntries.push([`@${lib}`, [`libs/${lib}/index.ts`]], [`@${lib}/*`, [`libs/${lib}/*`]]);
+    }
+    tsconfig.compilerOptions.paths = Object.fromEntries(pathEntries) as Record<string, string[]>;
+    await Bun.write(`${sourceRoot}/tsconfig.json`, JSON.stringify(tsconfig, null, 2));
+  }
+
+  #confidentialReadme(): string {
+    return `# ${this.#app.name}
+  본 프로젝트의 소스코드 및 관련자료는 모두 비밀정보로 관리됩니다.
+
+  ## Get Started
+  Run the code below.
+  \`\`\`
+  bun install -g bun
+  bun i
+
+  cat <<EOF >> .env
+  # ENV For Server => debug | debug.local | develop | develop.local | main | main.local
+  SERVER_ENV=debug.local
+  # Run Mode For Server => federation | batch | all
+  SERVER_MODE=federation
+  # ENV For Client => debug | debug.local | develop | develop.local | main | main.local
+  AKAN_PUBLIC_CLIENT_ENV=debug.local
+  ANALYZE=false
+  EOF
+
+  akn start-backend ${this.#app.name}
+  # or akn start-frontend ${this.#app.name}, etc
+  \`\`\`
+
+  ## Build
+  Run the code below.
+  \`\`\`
+  akn build-backend ${this.#app.name}
+  # or akn build-frontend ${this.#app.name}, etc
+  \`\`\`
+  `;
+  }
+
+  #publicReadme(): string {
+    return `# ${this.#app.name}
+  ## Get Started
+  Run the code below.
+  \`\`\`
+  cat <<EOF >> .env
+  # ENV For Server => debug | debug.local | develop | develop.local | main | main.local
+  SERVER_ENV=debug.local
+  # Run Mode For Server => federation | batch | all
+  SERVER_MODE=federation
+  # ENV For Client => debug | debug.local | develop | develop.local | main | main.local
+  AKAN_PUBLIC_CLIENT_ENV=debug.local
+  ANALYZE=false
+  EOF
+
+  akan start ${this.#app.name}
+  \`\`\`
+
+  ## Build
+  Run the code below.
+  \`\`\`
+  akan build ${this.#app.name}
+  # or akn build-frontend ${this.#app.name}, etc
+  \`\`\`
+  `;
+  }
+}

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";