@akanjs/devkit 2.1.0-rc.0 → 2.1.0-rc.2

package/README.ko.md

@@ -0,0 +1,65 @@
+# @akanjs/devkit
+
+[문서](https://akanjs.com/docs) | [npm](https://www.npmjs.com/package/@akanjs/devkit) | [런타임](https://www.npmjs.com/package/akanjs)
+
+Akan.js를 위한 development tooling primitive입니다.
+
+`@akanjs/devkit`은 Akan CLI와 프레임워크 수준 tooling에서 사용하는 build runner, workspace
+executor, config loader, dependency scanner, frontend artifact builder, command decorator, prompt,
+release helper를 담고 있습니다. 애플리케이션 런타임 코드가 아니라 tooling과 package author를 위한
+패키지입니다.
+
+## 설치
+
+대부분의 사용자는 devkit 대신 CLI를 설치하면 됩니다.
+
+```bash
+bun install -g @akanjs/cli@latest
+```
+
+Akan-aware tooling을 직접 만들 때만 `@akanjs/devkit`을 설치하세요.
+
+```bash
+bun add -d @akanjs/devkit
+```
+
+## 사용 예시
+
+```ts
+import { ApplicationBuildRunner, WorkspaceExecutor } from "@akanjs/devkit";
+
+const workspace = WorkspaceExecutor.fromRoot();
+const app = await workspace.getApp("my-app");
+const runner = new ApplicationBuildRunner(app);
+
+await runner.build();
+```
+
+## 제공하는 것
+
+- Workspace, app, library, package, module executor.
+- `akan.config.ts` 로딩과 정규화.
+- Application build, typecheck, SSR, CSR, release runner.
+- Dependency scanning과 package metadata 생성 helper.
+- Frontend build transform과 RSC/SSR artifact builder.
+- `@akanjs/cli`가 사용하는 command/script decorator.
+- AI prompt, guideline, code-generation 지원 utility.
+- Capacitor와 mobile release helper.
+
+## 패키지 경계
+
+- 런타임 코드는 `akanjs`에서 import해야 합니다. `AppConfig`, `LibConfig`, `AppInfo`, `LibInfo` 같은
+  공유 config 타입도 `akanjs`에서 가져옵니다.
+- CLI 사용자는 `@akanjs/cli`를 설치하면 됩니다. published CLI는 이 devkit을 내부에 번들링합니다.
+- Tooling author는 Akan workspace introspection이나 build API가 필요할 때 `@akanjs/devkit`을 직접
+  import할 수 있습니다.
+
+## 요구사항
+
+- [Bun](https://bun.sh) `>=1.3.13`
+- TypeScript
+- Optional peer는 Capacitor integration처럼 해당 기능을 사용할 때만 필요합니다.
+
+## 라이선스
+
+MIT

package/README.md

@@ -0,0 +1,63 @@
+# @akanjs/devkit
+
+[Docs](https://akanjs.com/docs) | [npm](https://www.npmjs.com/package/@akanjs/devkit) | [Runtime](https://www.npmjs.com/package/akanjs)
+
+Development tooling primitives for Akan.js.
+
+`@akanjs/devkit` contains the build runners, workspace executors, config loaders, dependency scanners,
+frontend artifact builders, command decorators, prompts, and release helpers used by the Akan CLI and by
+framework-level tooling. It is intended for tools and package authors, not for application runtime code.
+
+## Install
+
+Most users should install the CLI instead:
+
+```bash
+bun install -g @akanjs/cli@latest
+```
+
+Install `@akanjs/devkit` directly only when building Akan-aware tooling:
+
+```bash
+bun add -d @akanjs/devkit
+```
+
+## Usage
+
+```ts
+import { ApplicationBuildRunner, WorkspaceExecutor } from "@akanjs/devkit";
+
+const workspace = WorkspaceExecutor.fromRoot();
+const app = await workspace.getApp("my-app");
+const runner = new ApplicationBuildRunner(app);
+
+await runner.build();
+```
+
+## What It Provides
+
+- Workspace, app, library, package, and module executors.
+- `akan.config.ts` loading and normalization.
+- Application build, typecheck, SSR, CSR, and release runners.
+- Dependency scanning and package metadata generation helpers.
+- Frontend build transforms and RSC/SSR artifact builders.
+- Command/script decorators used by `@akanjs/cli`.
+- AI prompt, guideline, and code-generation support utilities.
+- Capacitor and mobile release helpers.
+
+## Package Boundary
+
+- Runtime code should import from `akanjs`, including shared config types such as `AppConfig`, `LibConfig`,
+  `AppInfo`, and `LibInfo`.
+- CLI users should install `@akanjs/cli`; the published CLI bundles this devkit internally.
+- Tooling authors can import `@akanjs/devkit` directly when they need Akan workspace introspection or build APIs.
+
+## Requirements
+
+- [Bun](https://bun.sh) `>=1.3.13`
+- TypeScript
+- Optional peers are only needed for the features that use them, such as Capacitor integration.
+
+## License
+
+MIT

package/commandDecorators/command.ts

@@ -1,3 +1,4 @@
+import path from "node:path";
 import { confirm, input, select } from "@inquirer/prompts";
 import { Logger } from "akanjs/common";
 import chalk from "chalk";
@@ -18,6 +19,32 @@ import { formatCommandHelp, formatHelp } from "./helpFormatter";
 import { type CommandCls, getTargetMetas } from "./targetMeta";
 
 const camelToKebabCase = (str: string) => str.replace(/([A-Z])/g, "-$1").toLowerCase();
+const loggedCliErrorObjects = new WeakSet<object>();
+const loggedCliErrorMessages = new Set<string>();
+
+const formatCliError = (error: unknown): string => {
+  if (error instanceof Error) return error.message || error.name;
+  if (typeof error === "string") return error.trim() || "Unknown error";
+  if (error === null || error === undefined) return "Unknown error";
+  try {
+    const json = JSON.stringify(error);
+    if (json) return json;
+  } catch {
+    return String(error);
+  }
+  return String(error) || "Unknown error";
+};
+
+const printCliError = (error: unknown) => {
+  if (typeof error === "object" && error !== null) {
+    if (loggedCliErrorObjects.has(error)) return;
+    loggedCliErrorObjects.add(error);
+  }
+  const message = formatCliError(error);
+  if (loggedCliErrorMessages.has(message)) return;
+  loggedCliErrorMessages.add(message);
+  Logger.rawLog(`\n${chalk.red(message)}`);
+};
 
 const handleOption = (programCommand: Command, argMeta: ArgMeta) => {
   const {
@@ -218,13 +245,21 @@ const getInternalArgumentValue = async (
 
 export const runCommands = async (...commands: CommandCls[]) => {
   process.on("unhandledRejection", (error) => {
+    printCliError(error);
     process.exit(1);
   });
   const __dirname = getDirname(import.meta.url);
-  const hasPackageJson = await FileSys.fileExists(`${__dirname}/../package.json`);
-  process.env.AKAN_VERSION = hasPackageJson
-    ? (await FileSys.readJson<PackageJson>(`${__dirname}/../package.json`)).version
-    : "0.0.1";
+  const packageJsonCandidates = [`${path.dirname(Bun.main)}/package.json`, `${__dirname}/../package.json`];
+  let cliPackageJson: PackageJson | null = null;
+  for (const packageJsonPath of packageJsonCandidates) {
+    if (!(await FileSys.fileExists(packageJsonPath))) continue;
+    const packageJson = await FileSys.readJson<PackageJson>(packageJsonPath);
+    if (packageJson.name === "@akanjs/cli" || packageJson.name === "@akanjs/devkit") {
+      cliPackageJson = packageJson;
+      break;
+    }
+  }
+  process.env.AKAN_VERSION = cliPackageJson?.version ?? "0.0.1";
 
   // Custom help handling
   const hasHelpFlag = process.argv.includes("--help") || process.argv.includes("-h");
@@ -331,8 +366,7 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
             await targetMeta.handler.call(cmd, ...commandArgs);
             Logger.rawLog();
           } catch (e) {
-            const errMsg = e instanceof Error ? e.message : typeof e === "string" ? e : JSON.stringify(e);
-            Logger.rawLog(`\n${chalk.red(errMsg)}`);
+            printCliError(e);
             throw e;
           }
         });

package/executors.test.ts

@@ -3,7 +3,7 @@ import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises"
 import os from "node:os";
 import path from "node:path";
 import { AkanAppConfig } from "./akanConfig";
-import { AppExecutor, Executor, PkgExecutor, WorkspaceExecutor } from "./executors";
+import { AppExecutor, CommandExecutionError, Executor, PkgExecutor, WorkspaceExecutor } from "./executors";
 import { AppInfo } from "./scanInfo";
 import type { PackageJson } from "./types";
 
@@ -48,6 +48,41 @@ afterEach(async () => {
 });
 
 describe("Executor filesystem helpers", () => {
+  test("reports command failures with command context and captured output", async () => {
+    const root = await makeTempRoot();
+    const exec = new Executor("fixture", root);
+
+    let error: unknown;
+    try {
+      await exec.spawn(process.execPath, ["--eval", "console.error('spawn failed'); process.exit(7)"]);
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(CommandExecutionError);
+    expect((error as CommandExecutionError).message).toContain(`Command failed: ${process.execPath}`);
+    expect((error as CommandExecutionError).message).toContain(`cwd: ${root}`);
+    expect((error as CommandExecutionError).message).toContain("exit code: 7");
+    expect((error as CommandExecutionError).message).toContain("spawn failed");
+  });
+
+  test("reports inherited stdio command failures with a fallback message", async () => {
+    const root = await makeTempRoot();
+    const exec = new Executor("fixture", root);
+
+    let error: unknown;
+    try {
+      await exec.spawn(process.execPath, ["--eval", "process.exit(3)"], { stdio: "inherit" });
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(CommandExecutionError);
+    expect((error as CommandExecutionError).message).toContain(`Command failed: ${process.execPath}`);
+    expect((error as CommandExecutionError).message).toContain(`cwd: ${root}`);
+    expect((error as CommandExecutionError).message).toContain("exit code: 3");
+  });
+
   test("resolves paths and reads/writes files relative to cwd", async () => {
     const root = await makeTempRoot();
     const exec = new Executor("fixture", root);

package/executors.ts

@@ -64,6 +64,58 @@ const staticTemplateFileExtensions = new Set([
   ".xml",
 ]);
 
+const formatCommandArg = (value: string) => (/^[\w@%+=:,./-]+$/.test(value) ? value : JSON.stringify(value));
+
+const formatCommandForDisplay = (command: string, args: string[] = []) =>
+  [command, ...args].map(formatCommandArg).join(" ");
+
+export interface CommandExecutionErrorOptions {
+  command: string;
+  args?: string[];
+  cwd: string;
+  code: number | null;
+  signal: string | null;
+  stdout?: string;
+  stderr?: string;
+  cause?: unknown;
+}
+
+export class CommandExecutionError extends Error {
+  command: string;
+  args: string[];
+  cwd: string;
+  code: number | null;
+  signal: string | null;
+  stdout: string;
+  stderr: string;
+
+  constructor({
+    command,
+    args = [],
+    cwd,
+    code,
+    signal,
+    stdout = "",
+    stderr = "",
+    cause,
+  }: CommandExecutionErrorOptions) {
+    const displayCommand = formatCommandForDisplay(command, args);
+    const status = signal ? `signal: ${signal}` : `exit code: ${code ?? "unknown"}`;
+    const output = (stderr || stdout).trim();
+    super([`Command failed: ${displayCommand}`, `cwd: ${cwd}`, status, output ? `\n${output}` : ""].join("\n"), {
+      cause,
+    });
+    this.name = "CommandExecutionError";
+    this.command = command;
+    this.args = args;
+    this.cwd = cwd;
+    this.code = code;
+    this.signal = signal;
+    this.stdout = stdout;
+    this.stderr = stderr;
+  }
+}
+
 export const execEmoji = {
   workspace: "🏠",
   app: "🚀",
@@ -197,22 +249,31 @@ export class Executor {
     Logger.raw(chalk.red(data.toString()));
   }
   exec(command: string, options: ExecOptions = {}) {
+    const cwd = options.cwd?.toString() ?? this.cwdPath;
     const proc = exec(command, { cwd: this.cwdPath, ...options });
+    let stdout = "";
+    let stderr = "";
     proc.stdout?.on("data", (data: Buffer) => {
+      stdout += data.toString();
       this.#stdout(data);
     });
     proc.stderr?.on("data", (data: Buffer) => {
+      stderr += data.toString();
       this.#stdout(data); // 정상로그도 stderr로 나옴
     });
     return new Promise((resolve, reject) => {
+      proc.on("error", (error) => {
+        reject(new CommandExecutionError({ command, cwd, code: null, signal: null, stdout, stderr, cause: error }));
+      });
       proc.on("exit", (code, signal) => {
-        if (!!code || signal) reject({ code, signal });
+        if (!!code || signal) reject(new CommandExecutionError({ command, cwd, code, signal, stdout, stderr }));
         else resolve({ code, signal });
       });
     });
   }
 
   spawn(command: string, args: string[] = [], options: SpawnOptions = {}): Promise<string> {
+    const cwd = options.cwd?.toString() ?? this.cwdPath;
     const proc = spawn(command, args, {
       cwd: this.cwdPath,
       // stdio: "inherit",
@@ -232,8 +293,14 @@ export class Executor {
       this.#stdout(data); // 정상로그도 stderr로 나옴
     });
     return new Promise((resolve, reject) => {
+      proc.on("error", (error) => {
+        reject(
+          new CommandExecutionError({ command, args, cwd, code: null, signal: null, stdout, stderr, cause: error }),
+        );
+      });
       proc.on("close", (code, signal) => {
-        if (code !== 0 || signal) reject(stderr || stdout);
+        if (code !== 0 || signal)
+          reject(new CommandExecutionError({ command, args, cwd, code, signal, stdout, stderr }));
         else resolve(stdout);
       });
     });
@@ -247,20 +314,40 @@ export class Executor {
     return proc;
   }
   fork(modulePath: string, args: string[] = [], options: ForkOptions = {}) {
+    const cwd = options.cwd?.toString() ?? this.cwdPath;
     const proc = fork(modulePath, args, {
       cwd: this.cwdPath,
       // stdio: ["ignore", "inherit", "inherit", "ipc"],
       ...options,
     });
+    let stdout = "";
+    let stderr = "";
     proc.stdout?.on("data", (data: Buffer) => {
+      stdout += data.toString();
       this.#stdout(data);
     });
     proc.stderr?.on("data", (data: Buffer) => {
+      stderr += data.toString();
       this.#stderr(data);
     });
     return new Promise((resolve, reject) => {
+      proc.on("error", (error) => {
+        reject(
+          new CommandExecutionError({
+            command: modulePath,
+            args,
+            cwd,
+            code: null,
+            signal: null,
+            stdout,
+            stderr,
+            cause: error,
+          }),
+        );
+      });
       proc.on("exit", (code, signal) => {
-        if (!!code || signal) reject({ code, signal });
+        if (!!code || signal)
+          reject(new CommandExecutionError({ command: modulePath, args, cwd, code, signal, stdout, stderr }));
         else resolve({ code, signal });
       });
     });

package/incrementalBuilder/incrementalBuilder.host.ts

@@ -143,6 +143,7 @@ export class IncrementalBuilderHost {
         app.workspace.workspaceRoot,
         "node_modules/@akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts",
       ),
+      path.join(import.meta.dir, "incrementalBuilder.proc.js"),
       path.join(import.meta.dir, "incrementalBuilder.proc.ts"),
     ];
     for (const c of candidates)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.1.0-rc.0",
+  "version": "2.1.0-rc.2",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -36,7 +36,7 @@
     "@langchain/deepseek": "^1.0.26",
     "@langchain/openai": "^1.4.6",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.1.0-rc.0",
+    "akanjs": "2.1.0-rc.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "fontaine": "^0.8.0",