@akanjs/devkit 1.0.19 → 2.1.0-rc.0

package/applicationBuildReporter.ts

@@ -0,0 +1,69 @@
+import { Logger } from "akanjs/common";
+
+export interface ApplicationBuildPhaseResult {
+  id: string;
+  label: string;
+  durationMs: number;
+  summary?: string;
+  skipped?: boolean;
+}
+
+export interface ApplicationBuildResult {
+  phases: ApplicationBuildPhaseResult[];
+  durationMs: number;
+  outputDir: string;
+  artifactDir: string;
+}
+
+export interface ApplicationBuildProgressReporter {
+  phaseStart?(phase: Pick<ApplicationBuildPhaseResult, "id" | "label">): void;
+  phaseDone?(phase: ApplicationBuildPhaseResult): void;
+  phaseFail?(phase: Pick<ApplicationBuildPhaseResult, "id" | "label">, error: unknown): void;
+}
+
+export class ApplicationBuildReporter {
+  static create(): ApplicationBuildProgressReporter {
+    return {
+      phaseDone: (phase) => Logger.rawLog(ApplicationBuildReporter.formatPhaseLine(phase)),
+    };
+  }
+
+  static printSummary(result: ApplicationBuildResult) {
+    Logger.rawLog("");
+    Logger.rawLog(`Route artifacts: ${result.artifactDir}`);
+    Logger.rawLog(`Server output: ${result.outputDir}`);
+    Logger.rawLog(`Done in ${ApplicationBuildReporter.formatDuration(result.durationMs)}`);
+  }
+
+  static formatError(error: unknown): string {
+    if (error instanceof AggregateError) {
+      const nestedMessages = error.errors
+        .map(
+          (nestedError, index) =>
+            ApplicationBuildReporter.formatError(nestedError).trim() || `Unknown error ${index + 1}`,
+        )
+        .map((message) => message.replace(/^/gm, "  "))
+        .join("\n");
+
+      return nestedMessages ? `${error.message}\n${nestedMessages}` : error.message;
+    }
+    if (error instanceof Error) {
+      const causeMessage = error.cause ? `\nCaused by: ${ApplicationBuildReporter.formatError(error.cause)}` : "";
+      return `${error.message}${causeMessage}`;
+    }
+    if (typeof error === "object" && error !== null && "message" in error) return String(error.message);
+    return String(error);
+  }
+
+  static formatDuration(ms: number): string {
+    if (ms < 1000) return `${ms}ms`;
+    if (ms < 60_000) return `${Math.round(ms / 100) / 10}s`;
+    const seconds = Math.floor(ms / 1000);
+    return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+  }
+
+  static formatPhaseLine(phase: ApplicationBuildPhaseResult): string {
+    const summary = phase.summary ? `: ${phase.summary}` : "";
+    return `✓ ${phase.label}${summary} (${ApplicationBuildReporter.formatDuration(phase.durationMs)})`;
+  }
+}

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
+  \`\`\`
+  `;
+  }
+}