@akanjs/cli 2.3.0 → 2.3.1-rc.0

package/README.ko.md

@@ -44,8 +44,17 @@ akan create-scalar <scalar-name>
 akan build-package akanjs
 akan build-package @akanjs/cli
 akan build-package @akanjs/devkit
+akan build-package create-akan-workspace
+akan verify-akan-publish-packages
+akan smoke-registry --test=true --tag=rc
 ```
 
+Akan framework 패키지는 반드시 `dist/pkgs/*` 산출물 기준으로 publish합니다. `verify-akan-publish-packages`는
+빌드된 패키지에 `npm pack --dry-run --json`을 실행하고, `deploy-akan` 또는 local registry smoke 전에 필요한
+metadata를 검증합니다.
+저장소 릴리즈에서는 root `akan` bootstrap script가 CLI dist를 덮어쓰지 않도록
+`bun run release:build-packages && bun run release:verify-packages`를 우선 사용합니다.
+
 ## 패키지 경계
 
 - 애플리케이션과 런타임 코드는 `akanjs`를 사용합니다.

package/README.md

@@ -58,8 +58,16 @@ Package maintenance commands are also exposed through the same executable:
 akan build-package akanjs
 akan build-package @akanjs/cli
 akan build-package @akanjs/devkit
+akan build-package create-akan-workspace
+akan verify-akan-publish-packages
+akan smoke-registry --test=true --tag=rc
 ```
 
+Publish Akan framework packages from `dist/pkgs/*` only. `verify-akan-publish-packages` runs `npm pack --dry-run --json`
+against the built packages and checks metadata that must be correct before `deploy-akan` or local registry smoke.
+For repository releases, prefer `bun run release:build-packages && bun run release:verify-packages` so the CLI package
+artifact is built last and is not overwritten by the root `akan` bootstrap script.
+
 ## Package Boundary
 
 - Use `akanjs` from application and runtime code.

package/incrementalBuilder.proc.js

@@ -2487,11 +2487,21 @@ var parseEnvFile = (envPath) => {
   }
   return env;
 };
-var PAGE_ROUTE_EXPORTS = new Set(["default", "pageConfig", "head", "generateHead", "Loading"]);
+var PAGE_ROUTE_EXPORTS = new Set([
+  "default",
+  "pageConfig",
+  "head",
+  "metadata",
+  "generateHead",
+  "generateMetadata",
+  "Loading"
+]);
 var ROOT_LAYOUT_EXPORTS = new Set([
   "default",
   "head",
+  "metadata",
   "generateHead",
+  "generateMetadata",
   "fonts",
   "manifest",
   "theme",
@@ -2502,7 +2512,16 @@ var ROOT_LAYOUT_EXPORTS = new Set([
   "NotFound",
   "Error"
 ]);
-var LAYOUT_ROUTE_EXPORTS = new Set(["default", "head", "generateHead", "Loading", "NotFound", "Error"]);
+var LAYOUT_ROUTE_EXPORTS = new Set([
+  "default",
+  "head",
+  "metadata",
+  "generateHead",
+  "generateMetadata",
+  "Loading",
+  "NotFound",
+  "Error"
+]);
 function validateRouteSourceExports(source, filePath, kind, options = {}) {
   const sourceFile = ts3.createSourceFile(filePath, source, ts3.ScriptTarget.Latest, true, ts3.ScriptKind.TSX);
   const allowed = kind === "page" ? PAGE_ROUTE_EXPORTS : options.rootLayout ? ROOT_LAYOUT_EXPORTS : LAYOUT_ROUTE_EXPORTS;
@@ -2555,6 +2574,12 @@ function validateRouteSourceExports(source, filePath, kind, options = {}) {
   if (exported.has("head") && exported.has("generateHead")) {
     throw new Error(`[route-convention] head and generateHead cannot both be exported in ${filePath}`);
   }
+  if (!options.rootLayout && (exported.has("head") || exported.has("generateHead")) && (exported.has("metadata") || exported.has("generateMetadata"))) {
+    throw new Error(`[route-convention] head/generateHead and metadata/generateMetadata cannot both be exported in ${filePath}`);
+  }
+  if (exported.has("metadata") && exported.has("generateMetadata")) {
+    throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${filePath}`);
+  }
 }
 
 class Executor {
@@ -7897,6 +7922,7 @@ class PagesBundleBuilder {
       define: this.#define(),
       plugins: [
         PagesBundleBuilder.createPagesEntryPlugin(entrySource),
+        PagesBundleBuilder.createServerCssStubPlugin(),
         await createExternalizeFrameworkPlugin({ app: this.#app, extra: akanConfig2.externalLibs }),
         akanConfig2.barrelImports.length > 0 ? await createBarrelImportsPlugin(this.#app, {
           pipeAfter: (source, args) => transformUseClient(source, {
@@ -7955,6 +7981,17 @@ class PagesBundleBuilder {
       }
     };
   }
+  static createServerCssStubPlugin() {
+    return {
+      name: "akan-server-css-stub",
+      setup(build) {
+        build.onLoad({ filter: /\.css$/ }, () => ({
+          contents: "",
+          loader: "js"
+        }));
+      }
+    };
+  }
 }
 // pkgs/@akanjs/devkit/frontendBuild/precompressArtifacts.ts
 import fs5 from "fs";
@@ -8026,7 +8063,7 @@ class SsrBaseArtifactBuilder {
   }
   async build() {
     const akanConfig2 = await this.#app.getConfig();
-    const { rscClientUrl, vendorMap } = await this.#buildRuntimeClientEntries();
+    const { rscClientUrl, rscRuntimeClientManifest, rscRuntimeSsrManifest, 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);
@@ -8040,6 +8077,8 @@ class SsrBaseArtifactBuilder {
     this.#app.verbose(`[base-artifact] route seed index -> ${seedIndexPath} entries=${seedIndex.entries.length} globalLayouts=${seedIndex.globalLayoutFiles.length}`);
     const artifact = {
       rscClientUrl,
+      rscRuntimeClientManifest,
+      rscRuntimeSsrManifest,
       vendorMap,
       cssAssets,
       pagesBundlePath: this.#command === "build" ? path31.relative(this.#absArtifactDir, pagesBundle.bundlePath) : pagesBundle.bundlePath,
@@ -8059,16 +8098,42 @@ class SsrBaseArtifactBuilder {
   async#buildRuntimeClientEntries() {
     const akanServerPath = await this.#resolveAkanServerPath();
     const rscClientEntry = `${akanServerPath}/rscClient.tsx`;
+    const rscSegmentOutletEntry = `${akanServerPath}/rscSegmentOutlet.tsx`;
     const vendorEntries = VENDOR_SPECIFIERS.map((specifier) => ({
       specifier,
       absPath: `${akanServerPath}/vendor/${specifier.replaceAll("/", "-").replaceAll(".", "-")}.ts`
     }));
-    const entries = [rscClientEntry, ...vendorEntries.map((v) => v.absPath)];
+    const entries = [rscClientEntry, rscSegmentOutletEntry, ...vendorEntries.map((v) => v.absPath)];
     const clientBundle = await new ClientEntriesBundler({ app: this.#app, entries, command: this.#command }).bundle();
+    const ssrBundle = await new ClientEntriesBundler({
+      app: this.#app,
+      entries: [rscSegmentOutletEntry],
+      ...RouteClientBuilder.resolveSsrClientExternalOptions(this.#command),
+      outputSubdir: "client-ssr",
+      command: this.#command
+    }).bundle();
     const rscClientUrl = clientBundle.entryUrlsByAbsPath.get(rscClientEntry) ?? "";
+    const rscRuntimeSsrManifest = {
+      moduleLoading: null,
+      moduleMap: Object.fromEntries(Object.entries(clientBundle.manifest).map(([key, row]) => {
+        const ssrOutput = ssrBundle.entryOutputAbsByAbsPath.get(rscSegmentOutletEntry);
+        if (!ssrOutput || key !== `${clientBundle.clientReferenceIdByAbsPath.get(rscSegmentOutletEntry)}#${row.name}`) {
+          return null;
+        }
+        return [
+          row.id,
+          { [row.name]: { id: ssrOutput, chunks: [ssrOutput, ssrOutput], name: row.name, async: true } }
+        ];
+      }).filter((entry) => Boolean(entry)))
+    };
     const vendorMap = Object.fromEntries(vendorEntries.map(({ specifier, absPath }) => [specifier, clientBundle.entryUrlsByAbsPath.get(absPath) ?? ""]));
     this.#app.verbose(`[base-artifact] rscClientUrl=${rscClientUrl} vendors=${Object.keys(vendorMap).length}`);
-    return { rscClientUrl, vendorMap };
+    return {
+      rscClientUrl,
+      rscRuntimeClientManifest: clientBundle.manifest,
+      rscRuntimeSsrManifest,
+      vendorMap
+    };
   }
   async#resolveAkanServerPath() {
     const candidates = [];
@@ -10004,7 +10069,8 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`)
           return formatCommandHelp(command, targetMeta.key);
         };
         programCommand.action(async (...args) => {
-          Logger10.rawLog();
+          if (!targetMeta.targetOption.stdio)
+            Logger10.rawLog();
           const cmdArgs = args.slice(0, args.length - 2);
           const opt = args[args.length - 2];
           const commandArgs = [];
@@ -10028,7 +10094,8 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`)
           const cmd = CommandContainer.get(command);
           try {
             await targetMeta.handler.call(cmd, ...commandArgs);
-            Logger10.rawLog();
+            if (!targetMeta.targetOption.stdio)
+              Logger10.rawLog();
           } catch (e) {
             printCliError(e);
             throw e;

package/index.js

@@ -2485,11 +2485,21 @@ var parseEnvFile = (envPath) => {
   }
   return env;
 };
-var PAGE_ROUTE_EXPORTS = new Set(["default", "pageConfig", "head", "generateHead", "Loading"]);
+var PAGE_ROUTE_EXPORTS = new Set([
+  "default",
+  "pageConfig",
+  "head",
+  "metadata",
+  "generateHead",
+  "generateMetadata",
+  "Loading"
+]);
 var ROOT_LAYOUT_EXPORTS = new Set([
   "default",
   "head",
+  "metadata",
   "generateHead",
+  "generateMetadata",
   "fonts",
   "manifest",
   "theme",
@@ -2500,7 +2510,16 @@ var ROOT_LAYOUT_EXPORTS = new Set([
   "NotFound",
   "Error"
 ]);
-var LAYOUT_ROUTE_EXPORTS = new Set(["default", "head", "generateHead", "Loading", "NotFound", "Error"]);
+var LAYOUT_ROUTE_EXPORTS = new Set([
+  "default",
+  "head",
+  "metadata",
+  "generateHead",
+  "generateMetadata",
+  "Loading",
+  "NotFound",
+  "Error"
+]);
 function validateRouteSourceExports(source, filePath, kind, options = {}) {
   const sourceFile = ts3.createSourceFile(filePath, source, ts3.ScriptTarget.Latest, true, ts3.ScriptKind.TSX);
   const allowed = kind === "page" ? PAGE_ROUTE_EXPORTS : options.rootLayout ? ROOT_LAYOUT_EXPORTS : LAYOUT_ROUTE_EXPORTS;
@@ -2553,6 +2572,12 @@ function validateRouteSourceExports(source, filePath, kind, options = {}) {
   if (exported.has("head") && exported.has("generateHead")) {
     throw new Error(`[route-convention] head and generateHead cannot both be exported in ${filePath}`);
   }
+  if (!options.rootLayout && (exported.has("head") || exported.has("generateHead")) && (exported.has("metadata") || exported.has("generateMetadata"))) {
+    throw new Error(`[route-convention] head/generateHead and metadata/generateMetadata cannot both be exported in ${filePath}`);
+  }
+  if (exported.has("metadata") && exported.has("generateMetadata")) {
+    throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${filePath}`);
+  }
 }
 
 class Executor {
@@ -7895,6 +7920,7 @@ class PagesBundleBuilder {
       define: this.#define(),
       plugins: [
         PagesBundleBuilder.createPagesEntryPlugin(entrySource),
+        PagesBundleBuilder.createServerCssStubPlugin(),
         await createExternalizeFrameworkPlugin({ app: this.#app, extra: akanConfig2.externalLibs }),
         akanConfig2.barrelImports.length > 0 ? await createBarrelImportsPlugin(this.#app, {
           pipeAfter: (source, args) => transformUseClient(source, {
@@ -7953,6 +7979,17 @@ class PagesBundleBuilder {
       }
     };
   }
+  static createServerCssStubPlugin() {
+    return {
+      name: "akan-server-css-stub",
+      setup(build) {
+        build.onLoad({ filter: /\.css$/ }, () => ({
+          contents: "",
+          loader: "js"
+        }));
+      }
+    };
+  }
 }
 // pkgs/@akanjs/devkit/frontendBuild/precompressArtifacts.ts
 import fs5 from "fs";
@@ -8024,7 +8061,7 @@ class SsrBaseArtifactBuilder {
   }
   async build() {
     const akanConfig2 = await this.#app.getConfig();
-    const { rscClientUrl, vendorMap } = await this.#buildRuntimeClientEntries();
+    const { rscClientUrl, rscRuntimeClientManifest, rscRuntimeSsrManifest, 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);
@@ -8038,6 +8075,8 @@ class SsrBaseArtifactBuilder {
     this.#app.verbose(`[base-artifact] route seed index -> ${seedIndexPath} entries=${seedIndex.entries.length} globalLayouts=${seedIndex.globalLayoutFiles.length}`);
     const artifact = {
       rscClientUrl,
+      rscRuntimeClientManifest,
+      rscRuntimeSsrManifest,
       vendorMap,
       cssAssets,
       pagesBundlePath: this.#command === "build" ? path31.relative(this.#absArtifactDir, pagesBundle.bundlePath) : pagesBundle.bundlePath,
@@ -8057,16 +8096,42 @@ class SsrBaseArtifactBuilder {
   async#buildRuntimeClientEntries() {
     const akanServerPath = await this.#resolveAkanServerPath();
     const rscClientEntry = `${akanServerPath}/rscClient.tsx`;
+    const rscSegmentOutletEntry = `${akanServerPath}/rscSegmentOutlet.tsx`;
     const vendorEntries = VENDOR_SPECIFIERS.map((specifier) => ({
       specifier,
       absPath: `${akanServerPath}/vendor/${specifier.replaceAll("/", "-").replaceAll(".", "-")}.ts`
     }));
-    const entries = [rscClientEntry, ...vendorEntries.map((v) => v.absPath)];
+    const entries = [rscClientEntry, rscSegmentOutletEntry, ...vendorEntries.map((v) => v.absPath)];
     const clientBundle = await new ClientEntriesBundler({ app: this.#app, entries, command: this.#command }).bundle();
+    const ssrBundle = await new ClientEntriesBundler({
+      app: this.#app,
+      entries: [rscSegmentOutletEntry],
+      ...RouteClientBuilder.resolveSsrClientExternalOptions(this.#command),
+      outputSubdir: "client-ssr",
+      command: this.#command
+    }).bundle();
     const rscClientUrl = clientBundle.entryUrlsByAbsPath.get(rscClientEntry) ?? "";
+    const rscRuntimeSsrManifest = {
+      moduleLoading: null,
+      moduleMap: Object.fromEntries(Object.entries(clientBundle.manifest).map(([key, row]) => {
+        const ssrOutput = ssrBundle.entryOutputAbsByAbsPath.get(rscSegmentOutletEntry);
+        if (!ssrOutput || key !== `${clientBundle.clientReferenceIdByAbsPath.get(rscSegmentOutletEntry)}#${row.name}`) {
+          return null;
+        }
+        return [
+          row.id,
+          { [row.name]: { id: ssrOutput, chunks: [ssrOutput, ssrOutput], name: row.name, async: true } }
+        ];
+      }).filter((entry) => Boolean(entry)))
+    };
     const vendorMap = Object.fromEntries(vendorEntries.map(({ specifier, absPath }) => [specifier, clientBundle.entryUrlsByAbsPath.get(absPath) ?? ""]));
     this.#app.verbose(`[base-artifact] rscClientUrl=${rscClientUrl} vendors=${Object.keys(vendorMap).length}`);
-    return { rscClientUrl, vendorMap };
+    return {
+      rscClientUrl,
+      rscRuntimeClientManifest: clientBundle.manifest,
+      rscRuntimeSsrManifest,
+      vendorMap
+    };
   }
   async#resolveAkanServerPath() {
     const candidates = [];
@@ -10002,7 +10067,8 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`)
           return formatCommandHelp(command, targetMeta.key);
         };
         programCommand.action(async (...args) => {
-          Logger10.rawLog();
+          if (!targetMeta.targetOption.stdio)
+            Logger10.rawLog();
           const cmdArgs = args.slice(0, args.length - 2);
           const opt = args[args.length - 2];
           const commandArgs = [];
@@ -10026,7 +10092,8 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`)
           const cmd = CommandContainer.get(command);
           try {
             await targetMeta.handler.call(cmd, ...commandArgs);
-            Logger10.rawLog();
+            if (!targetMeta.targetOption.stdio)
+              Logger10.rawLog();
           } catch (e) {
             printCliError(e);
             throw e;
@@ -11420,6 +11487,7 @@ import { Logger as Logger14 } from "akanjs/common";
 var {$: $2 } = globalThis.Bun;
 
 class PackageRunner extends runner("package") {
+  static publishableAkanPackages = ["akanjs", "@akanjs/cli", "@akanjs/devkit", "create-akan-workspace"];
   async version(workspace, { log = true } = {}) {
     const pkgJson = process.env.USE_AKANJS_PKGS === "true" ? await FileSys.readJson(`${workspace?.workspaceRoot ?? process.cwd()}/pkgs/akanjs/package.json`) : await this.#getInstalledPackageJson();
     const version = pkgJson.name === "akanjs" ? pkgJson.version : pkgJson.dependencies?.akanjs ?? pkgJson.version;
@@ -11490,7 +11558,13 @@ class PackageRunner extends runner("package") {
     await pkg.updatePackageJsonDependencies(packageRuntimeDeps, packageRuntimeDevDeps);
     const hasBuildFile = await Bun.file(`${pkg.cwdPath}/build.ts`).exists();
     if (hasBuildFile) {
-      await pkg.workspace.spawn(process.execPath, [`${pkg.cwdPath}/build.ts`], { env: process.env, stdio: "inherit" });
+      await pkg.workspace.spawn(process.execPath, [`${pkg.cwdPath}/build.ts`], {
+        env: {
+          ...process.env,
+          ...pkg.name === "akanjs" ? { AKAN_BUILD_DECLARATION_DIAGNOSTICS: "error" } : {}
+        },
+        stdio: "inherit"
+      });
     } else {
       await $2`cp -r ${pkg.cwdPath}/. ${pkg.dist.cwdPath}`;
       await Promise.all([
@@ -11500,6 +11574,55 @@ class PackageRunner extends runner("package") {
     }
     await this.#copyPackageReadmes(pkg);
   }
+  async verifyDistPackage(pkg) {
+    const distPackageJsonPath = `${pkg.dist.cwdPath}/package.json`;
+    if (!await Bun.file(distPackageJsonPath).exists()) {
+      throw new Error(`[package] dist package not found for ${pkg.name}. Run build-package first.`);
+    }
+    const pkgJson = await FileSys.readJson(distPackageJsonPath);
+    if (pkgJson.name !== pkg.name) {
+      throw new Error(`[package] dist package name mismatch: expected ${pkg.name}, got ${pkgJson.name ?? "(missing)"}`);
+    }
+    if (!pkgJson.version)
+      throw new Error(`[package] dist package version is missing for ${pkg.name}`);
+    if (!pkgJson.publishConfig || pkgJson.publishConfig.access !== "public") {
+      throw new Error(`[package] ${pkg.name} must publish with publishConfig.access=public`);
+    }
+    if (!await Bun.file(`${pkg.dist.cwdPath}/README.md`).exists()) {
+      throw new Error(`[package] README.md is missing from dist package ${pkg.name}`);
+    }
+    if (!await Bun.file(`${pkg.dist.cwdPath}/README.ko.md`).exists()) {
+      throw new Error(`[package] README.ko.md is missing from dist package ${pkg.name}`);
+    }
+    const binEntries = typeof pkgJson.bin === "string" ? [pkgJson.bin] : Object.values(pkgJson.bin ?? {});
+    if (binEntries.some((binPath) => binPath.endsWith(".ts"))) {
+      throw new Error(`[package] ${pkg.name} dist bin entries must not point at TypeScript sources`);
+    }
+    if (pkg.name === "akanjs") {
+      const exports = pkgJson.exports;
+      const rootExport = exports?.["."];
+      if (!rootExport?.types?.startsWith("./types/")) {
+        throw new Error("[package] akanjs dist exports must point type declarations at ./types");
+      }
+    }
+    const packOutput = await pkg.workspace.spawn("npm", ["pack", "--dry-run", "--json", pkg.dist.cwdPath], {
+      cwd: pkg.workspace.workspaceRoot
+    });
+    const [packResult] = JSON.parse(packOutput);
+    return {
+      name: pkg.name,
+      version: pkgJson.version,
+      files: packResult?.files?.length ?? 0,
+      size: packResult?.size ?? 0
+    };
+  }
+  async verifyAkanPublishPackages(workspace) {
+    const results = [];
+    for (const pkgName of PackageRunner.publishableAkanPackages) {
+      results.push(await this.verifyDistPackage(PkgExecutor.from(workspace, pkgName)));
+    }
+    return results;
+  }
   async#copyPackageReadmes(pkg) {
     await Promise.all(["README.md", "README.ko.md"].map((fileName) => pkg.cp(fileName, `${pkg.dist.cwdPath}/${fileName}`)));
   }
@@ -11543,6 +11666,18 @@ class PackageScript extends script("package", [PackageRunner]) {
     if (spinner2)
       spinner2.succeed("Package built");
   }
+  async verifyDistPackage(pkg) {
+    const spinner2 = pkg.spinning("Verifying dist package...");
+    const result = await this.packageRunner.verifyDistPackage(pkg);
+    spinner2.succeed(`Package verified (${result.files} files, ${result.size} bytes packed)`);
+    return result;
+  }
+  async verifyAkanPublishPackages(workspace) {
+    const spinner2 = workspace.spinning("Verifying Akan publish packages...");
+    const results = await this.packageRunner.verifyAkanPublishPackages(workspace);
+    spinner2.succeed(`Akan publish packages verified (${results.length} packages)`);
+    return results;
+  }
   async updateWorskpaceRootPackageJson(workspace) {
     const rootPackageJson = await workspace.getPackageJson();
     await this.packageRunner.updateWorskpaceRootPackageJson(workspace, rootPackageJson);
@@ -11988,6 +12123,7 @@ class CloudScript extends script("cloud", [CloudRunner, ApplicationScript, Packa
         await this.applicationScript.test(pkg);
     for (const pkg of pkgs)
       await this.packageScript.buildPackage(pkg);
+    await this.packageScript.verifyAkanPublishPackages(workspace);
     await this.cloudRunner.deployAkan(workspace, akanPkgs, { registryUrl });
   }
   async update(workspace, tag = "latest", { registryUrl } = {}) {
@@ -12094,6 +12230,13 @@ var resourceList = [
   { uri: "akan://workspace/apps", name: "Workspace apps", mimeType: "application/json" },
   { uri: "akan://workspace/modules", name: "Workspace modules", mimeType: "application/json" }
 ];
+var cursorMcpConfigPath = ".cursor/mcp.json";
+var cursorWorkspaceFolder = "$" + "{workspaceFolder}";
+var akanCursorMcpServer = {
+  type: "stdio",
+  command: "bash",
+  args: ["-lc", `cd "${cursorWorkspaceFolder}" && akan mcp`]
+};
 
 class ContextRunner extends runner("context") {
   async getContext(workspace, {
@@ -12117,20 +12260,44 @@ class ContextRunner extends runner("context") {
   async getGuidelineResource(name) {
     return await Prompter.getInstruction(name);
   }
+  async installMcp(workspace, target, { force = false } = {}) {
+    if (target !== "cursor")
+      throw new Error(`Unknown MCP install target: ${target}. Use cursor.`);
+    const existing = await workspace.exists(cursorMcpConfigPath) ? await workspace.readJson(cursorMcpConfigPath) : {};
+    const mcpServers = existing.mcpServers ?? {};
+    const currentAkanServer = mcpServers.akan;
+    if (currentAkanServer && !force && JSON.stringify(currentAkanServer) !== JSON.stringify(akanCursorMcpServer)) {
+      throw new Error(`${cursorMcpConfigPath} already has an "akan" MCP server. Re-run with --force to overwrite it.`);
+    }
+    const nextConfig = {
+      ...existing,
+      mcpServers: {
+        ...mcpServers,
+        akan: akanCursorMcpServer
+      }
+    };
+    await workspace.writeFile(cursorMcpConfigPath, `${JSON.stringify(nextConfig, null, 2)}
+`);
+    return cursorMcpConfigPath;
+  }
   async runMcp(workspace) {
     const decoder = new TextDecoder;
     let buffer = "";
-    const respond = (id, result) => {
-      const payload = JSON.stringify({ jsonrpc: "2.0", id, result });
-      process.stdout.write(`Content-Length: ${Buffer.byteLength(payload)}\r
+    const writeMessage = (message, framing) => {
+      const payload = JSON.stringify(message);
+      if (framing === "newline")
+        process.stdout.write(`${payload}
+`);
+      else
+        process.stdout.write(`Content-Length: ${Buffer.byteLength(payload)}\r
 \r
 ${payload}`);
     };
-    const respondError = (id, code, message) => {
-      const payload = JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } });
-      process.stdout.write(`Content-Length: ${Buffer.byteLength(payload)}\r
-\r
-${payload}`);
+    const respond = (id, result, framing) => {
+      writeMessage({ jsonrpc: "2.0", id, result }, framing);
+    };
+    const respondError = (id, code, message, framing) => {
+      writeMessage({ jsonrpc: "2.0", id, error: { code, message } }, framing);
     };
     const readResource = async (uri) => {
       const context = await AkanContextAnalyzer.analyze(workspace);
@@ -12155,14 +12322,14 @@ ${payload}`);
       }
       throw new Error(`Unknown resource: ${uri}`);
     };
-    const handle = async (request) => {
+    const handle = async (request, framing) => {
       const params = request.params ?? {};
       if (request.method === "initialize") {
         respond(request.id, {
           protocolVersion: "2024-11-05",
           capabilities: { tools: {}, resources: {} },
           serverInfo: { name: "akan", version: process.env.AKAN_VERSION ?? "0.0.0" }
-        });
+        }, framing);
       } else if (request.method === "tools/list") {
         respond(request.id, {
           tools: [
@@ -12181,9 +12348,12 @@ ${payload}`);
               name: "explain_command",
               inputSchema: { type: "object", properties: { command: { type: "string" } }, required: ["command"] }
             },
-            { name: "doctor_workspace", inputSchema: { type: "object", properties: { strict: { type: "boolean" } } } }
+            {
+              name: "doctor_workspace",
+              inputSchema: { type: "object", properties: { strict: { type: "boolean" } } }
+            }
           ]
-        });
+        }, framing);
       } else if (request.method === "tools/call") {
         const name = params.name;
         const args = params.arguments ?? {};
@@ -12210,36 +12380,64 @@ ${payload}`);
         })();
         respond(request.id, {
           content: [{ type: "text", text: typeof result === "string" ? result : jsonText(result) }]
-        });
+        }, framing);
       } else if (request.method === "resources/list") {
-        respond(request.id, { resources: resourceList });
+        respond(request.id, { resources: resourceList }, framing);
       } else if (request.method === "resources/read") {
-        respond(request.id, { contents: [await readResource(params.uri)] });
+        respond(request.id, { contents: [await readResource(params.uri)] }, framing);
       } else if (!request.method.endsWith("/initialized")) {
-        respondError(request.id, -32601, `Unknown method: ${request.method}`);
+        respondError(request.id, -32601, `Unknown method: ${request.method}`, framing);
       }
     };
-    const parse = async () => {
-      while (true) {
-        const headerEnd = buffer.indexOf(`\r
+    const parseContentLengthMessage = async () => {
+      const headerEnd = buffer.indexOf(`\r
 \r
 `);
-        if (headerEnd < 0)
+      if (headerEnd < 0)
+        return false;
+      const header = buffer.slice(0, headerEnd);
+      const match = /Content-Length:\s*(\d+)/i.exec(header);
+      if (!match) {
+        buffer = buffer.slice(headerEnd + 4);
+        return true;
+      }
+      const length = Number(match[1]);
+      const bodyStart = headerEnd + 4;
+      const bodyEnd = bodyStart + length;
+      if (buffer.length < bodyEnd)
+        return false;
+      const body = buffer.slice(bodyStart, bodyEnd);
+      buffer = buffer.slice(bodyEnd);
+      await handle(JSON.parse(body), "content-length");
+      return true;
+    };
+    const parseLineMessage = async () => {
+      const lineEnd = buffer.indexOf(`
+`);
+      if (lineEnd < 0)
+        return false;
+      const line = buffer.slice(0, lineEnd).trim();
+      buffer = buffer.slice(lineEnd + 1);
+      if (!line)
+        return true;
+      await handle(JSON.parse(line), "newline");
+      return true;
+    };
+    const parse = async () => {
+      while (true) {
+        buffer = buffer.trimStart();
+        if (/^Content-Length:/i.test(buffer)) {
+          if (await parseContentLengthMessage())
+            continue;
           return;
-        const header = buffer.slice(0, headerEnd);
-        const match = /Content-Length:\s*(\d+)/i.exec(header);
-        if (!match) {
-          buffer = buffer.slice(headerEnd + 4);
-          continue;
         }
-        const length = Number(match[1]);
-        const bodyStart = headerEnd + 4;
-        const bodyEnd = bodyStart + length;
-        if (buffer.length < bodyEnd)
-          return;
-        const body = buffer.slice(bodyStart, bodyEnd);
-        buffer = buffer.slice(bodyEnd);
-        await handle(JSON.parse(body));
+        if (buffer.includes(`\r
+\r
+`) && await parseContentLengthMessage())
+          continue;
+        if (await parseLineMessage())
+          continue;
+        return;
       }
     };
     for await (const chunk of Bun.stdin.stream()) {
@@ -12267,6 +12465,13 @@ class ContextScript extends script("context", [ContextRunner]) {
   async doctor(workspace, options = {}) {
     Logger17.rawLog(await this.contextRunner.doctor(workspace, options));
   }
+  async mcpInstall(workspace, target, { force = false } = {}) {
+    if (target && target !== "cursor")
+      throw new Error(`Unknown MCP install target: ${target}. Use cursor.`);
+    const written = await this.contextRunner.installMcp(workspace, "cursor", { force });
+    Logger17.rawLog(`Akan MCP server installed for Cursor:
+- ${written}`);
+  }
   async mcp(workspace) {
     await this.contextRunner.runMcp(workspace);
   }
@@ -12288,7 +12493,10 @@ class ContextCommand extends command("context", [ContextScript], ({ public: targ
   }).option("strict", Boolean, { desc: "treat recommended conventions as errors", default: false }).with(Workspace).exec(async function(format, strict, workspace) {
     await this.contextScript.doctor(workspace, { format, strict });
   }),
-  mcp: target({ desc: "Start the read-only Akan MCP server over stdio" }).with(Workspace).exec(async function(workspace) {
+  mcpInstall: target({ desc: "Install the Akan MCP server config for Cursor" }).arg("target", String, { desc: "cursor", nullable: true }).option("force", Boolean, { desc: "overwrite an existing Akan MCP server entry", default: false }).with(Workspace).exec(async function(targetName, force, workspace) {
+    await this.contextScript.mcpInstall(workspace, targetName, { force });
+  }),
+  mcp: target({ desc: "Start the read-only Akan MCP server over stdio", stdio: true }).with(Workspace).exec(async function(workspace) {
     await this.contextScript.mcp(workspace);
   })
 })) {
@@ -12754,6 +12962,7 @@ class LocalRegistryScript extends script("localRegistry", [
         await this.applicationScript.test(pkg);
     for (const pkg of pkgs)
       await this.packageScript.buildPackage(pkg, { showSpinner: false });
+    await this.packageScript.verifyAkanPublishPackages(workspace);
   }
 }
 
@@ -13376,6 +13585,12 @@ class PackageCommand extends command("package", [PackageScript], ({ public: targ
   }),
   buildPackage: target({ desc: "Build a package for distribution" }).with(Pkg).exec(async function(pkg) {
     await this.packageScript.buildPackage(pkg);
+  }),
+  verifyDistPackage: target({ desc: "Verify a built dist package with npm pack dry-run" }).with(Pkg).exec(async function(pkg) {
+    await this.packageScript.verifyDistPackage(pkg);
+  }),
+  verifyAkanPublishPackages: target({ devOnly: true, desc: "Verify all Akan publish dist packages" }).with(Workspace).exec(async function(workspace) {
+    await this.packageScript.verifyAkanPublishPackages(workspace);
   })
 })) {
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "2.3.0",
+  "version": "2.3.1-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -35,7 +35,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.3.0",
+    "akanjs": "2.3.1-rc.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "^5.5.20",
@@ -47,7 +47,7 @@
     "js-yaml": "^4.1.1",
     "ora": "^9.4.0",
     "qrcode": "^1.5.4",
-    "react": "19.2.6",
+    "react": "19.2.7",
     "ssh2": "^1.17.0",
     "subset-font": "^2.5.0",
     "tailwind-scrollbar": "^4.0.2",