akanjs 2.2.10-rc.1 → 2.2.11

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # akanjs
 
+## 2.2.11
+
+### Patch Changes
+
+- 8190632: Add Akan server console support with CLI/build integration and documentation for console-oriented workflows.
+- 4bce7f9: Add initial LLM discovery docs and stabilize Akan client/runtime behavior.
+
+  - Add `/llms.txt` documentation discovery for Akan docs.
+  - Add `wsConnect` support for automatic WebSocket connections.
+  - Delay client bootstrap module execution until the SSR fizz stream is ready.
+  - Improve route tree, HMR, fetch, store, and SSR/client runtime stability.
+
 ## 2.2.7
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.2.10-rc.1",
+  "version": "2.2.11",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanServer.ts

@@ -39,6 +39,19 @@ interface AkanAppPrepared {
   webProxyRunner: WebProxyRunner | null;
 }
 
+export interface AkanServerConsoleInfo {
+  name: string;
+  status: AkanServer["status"];
+  serverMode: AkanServer["serverMode"];
+  env: Pick<BaseEnv, "appName" | "environment" | "operationMode" | "repoName" | "serveDomain" | "databaseMode">;
+  services: string[];
+  signals: string[];
+  adaptors: string[];
+  uses: string[];
+  serviceStages: string[][];
+  adaptorStages: string[][];
+}
+
 export class AkanServer {
   status: "stopped" | "initializing" | "initialized" | "starting" | "running" | "stopping" = "stopped";
 
@@ -120,6 +133,29 @@ export class AkanServer {
     return this.#di.getAdaptor<T>(refName);
   }
 
+  inspectConsole(): AkanServerConsoleInfo {
+    this.#assertCanGet();
+    return {
+      name: this.name,
+      status: this.status,
+      serverMode: this.serverMode,
+      env: {
+        appName: this.env.appName,
+        environment: this.env.environment,
+        operationMode: this.env.operationMode,
+        repoName: this.env.repoName,
+        serveDomain: this.env.serveDomain,
+        databaseMode: this.env.databaseMode,
+      },
+      services: [...this.#di.registry.serviceCls.keys()].sort((a, b) => a.localeCompare(b)),
+      signals: [...this.#di.registry.serverSignalCls.keys()].sort((a, b) => a.localeCompare(b)),
+      adaptors: [...this.#di.registry.adaptorCls.keys()].sort((a, b) => a.localeCompare(b)),
+      uses: [...this.#di.registry.uses.keys()].sort((a, b) => a.localeCompare(b)),
+      serviceStages: this.#di.hierarchy.serviceStages.map((stage) => [...stage]),
+      adaptorStages: this.#di.hierarchy.adaptorStages.map((stage) => [...stage]),
+    };
+  }
+
   async init({ routes: initRoutes = true, web = true }: { routes?: boolean; web?: boolean } = {}) {
     if (this.status !== "stopped") throw new Error("AkanServer is not able to init. It is already running.");
     this.status = "initializing";
@@ -248,14 +284,14 @@ export class AkanServer {
   }
 
   async start({ listen, web = true }: { listen?: boolean; web?: boolean } = {}) {
-    const isScriptCommand = process.env.AKAN_COMMAND_TYPE === "script";
-    const shouldListen = (listen ?? !isScriptCommand) && this.serverMode !== "batch";
+    const isNoListenCommand = process.env.AKAN_COMMAND_TYPE === "script" || process.env.AKAN_COMMAND_TYPE === "console";
+    const shouldListen = (listen ?? !isNoListenCommand) && this.serverMode !== "batch";
     await this.init({ routes: shouldListen, web });
     if (!shouldListen) {
       const websocket = this.#di.getWebsocketAdaptor();
       if (websocket) SignalResolver.setLocalPublish((roomId, data) => this.#localPublish?.(roomId, data), websocket);
       this.status = "running";
-      if (!isScriptCommand) {
+      if (!isNoListenCommand) {
         this.#startMetricsReporting();
         this.#di.registerSchedule(this.serverMode);
         process.on("message", (message) => this.#handleIpcMessage(message as AkanIpcMessage));

package/server/console.ts

@@ -0,0 +1,189 @@
+import { createInterface } from "node:readline/promises";
+import { inspect } from "node:util";
+import type { BaseEnv } from "akanjs/base";
+import type { Adaptor, Service } from "akanjs/service";
+import type { ServerSignal } from "akanjs/signal";
+import type { AkanServer } from "./akanServer";
+
+type AsyncFunctionConstructor = new (...args: string[]) => (scope: object) => Promise<unknown>;
+
+const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor as AsyncFunctionConstructor;
+
+export interface AkanConsoleOptions {
+  prompt?: string;
+  globals?: Record<string, unknown>;
+  input?: typeof process.stdin;
+  output?: typeof process.stdout;
+}
+
+export interface AkanConsoleContext extends Record<string, unknown> {
+  server: AkanServer;
+  env: AkanServer["env"];
+  get: AkanServer["get"];
+  service: <T = Service>(refName: string) => T;
+  signal: <T = ServerSignal>(refName: string) => T;
+  adaptor: <T = Adaptor>(refName: string) => T;
+  methods: (value: unknown) => string[];
+  debug: () => ReturnType<AkanServer["inspectConsole"]>;
+}
+
+export const assertAkanConsoleAllowed = (
+  env: Pick<BaseEnv, "environment" | "operationMode"> = {
+    environment: (process.env.AKAN_PUBLIC_ENV ?? "debug") as BaseEnv["environment"],
+    operationMode: (process.env.AKAN_PUBLIC_OPERATION_MODE ?? "cloud") as BaseEnv["operationMode"],
+  },
+) => {
+  const isProductionLike =
+    env.environment === "main" ||
+    env.operationMode === "cloud" ||
+    env.operationMode === "edge" ||
+    process.env.NODE_ENV === "production";
+  if (!isProductionLike || process.env.AKAN_CONSOLE === "1") return;
+
+  throw new Error(
+    [
+      "Akan console is disabled for production-like environments.",
+      "Run with AKAN_CONSOLE=1 only for the exec command that opens the console.",
+      "Example: AKAN_CONSOLE=1 bun console.js",
+    ].join("\n"),
+  );
+};
+
+export const getAkanConsoleMethods = (value: unknown): string[] => {
+  const names = new Set<string>();
+  let proto =
+    typeof value === "function"
+      ? value.prototype
+      : value && (typeof value === "object" || typeof value === "function")
+        ? Object.getPrototypeOf(value)
+        : null;
+
+  while (proto && proto !== Object.prototype) {
+    for (const name of Object.getOwnPropertyNames(proto)) {
+      if (name === "constructor") continue;
+      const descriptor = Object.getOwnPropertyDescriptor(proto, name);
+      if (typeof descriptor?.value === "function") names.add(name);
+    }
+    proto = Object.getPrototypeOf(proto);
+  }
+
+  return [...names].sort((a, b) => a.localeCompare(b));
+};
+
+export const createAkanConsoleContext = (
+  server: AkanServer,
+  globals: Record<string, unknown> = {},
+): AkanConsoleContext => {
+  const context = {
+    server,
+    env: server.env,
+    get: server.get.bind(server) as AkanServer["get"],
+    service: server.getService.bind(server),
+    signal: server.getSignal.bind(server),
+    adaptor: server.getAdaptor.bind(server),
+    methods: getAkanConsoleMethods,
+    debug: () => server.inspectConsole(),
+    ...globals,
+  };
+  return context;
+};
+
+const createScope = (context: Record<string, unknown>) =>
+  new Proxy(context, {
+    has: () => true,
+    get(target, prop) {
+      if (prop === Symbol.unscopables) return undefined;
+      if (prop in target) return target[prop as keyof typeof target];
+      return (globalThis as Record<PropertyKey, unknown>)[prop];
+    },
+    set(target, prop, value) {
+      target[prop as keyof typeof target] = value;
+      return true;
+    },
+  });
+
+export const evaluateAkanConsoleInput = async (source: string, context: Record<string, unknown>) => {
+  const trimmed = source.trim();
+  if (!trimmed) return undefined;
+  const scope = createScope(context);
+
+  try {
+    return await new AsyncFunction("scope", `with (scope) { return await (${trimmed}); }`)(scope);
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) throw error;
+    return await new AsyncFunction("scope", `with (scope) { return await (async () => {\n${trimmed}\n})(); }`)(scope);
+  }
+};
+
+const printHelp = (output: typeof process.stdout) => {
+  output.write(
+    [
+      "Akan console commands:",
+      "  .help       Show this help",
+      "  .globals    Show available global names",
+      "  .exit       Close the console",
+      "",
+      "Examples:",
+      "  debug()",
+      '  methods(service("user"))',
+      '  await service("user").__count()',
+      '  userService = service("user")',
+      "",
+    ].join("\n"),
+  );
+};
+
+const formatValue = (value: unknown) => {
+  if (value === undefined) return "";
+  return `${inspect(value, { colors: true, depth: 5, maxArrayLength: 100 })}\n`;
+};
+
+export const startAkanConsole = async (server: AkanServer, options: AkanConsoleOptions = {}) => {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  const context = createAkanConsoleContext(server, options.globals);
+  const prompt = options.prompt ?? `akan:${server.name}> `;
+  const rl = createInterface({ input, output, terminal: true });
+
+  output.write(`Akan console started for ${server.name}. Type .help for commands.\n`);
+  rl.setPrompt(prompt);
+  rl.prompt();
+
+  rl.on("SIGINT", () => {
+    output.write("\n");
+    rl.close();
+  });
+
+  for await (const line of rl) {
+    const trimmed = line.trim();
+    try {
+      if (!trimmed) {
+        rl.prompt();
+        continue;
+      }
+      if (trimmed === ".exit" || trimmed === ".quit") {
+        rl.close();
+        break;
+      }
+      if (trimmed === ".help") {
+        printHelp(output);
+        rl.prompt();
+        continue;
+      }
+      if (trimmed === ".globals") {
+        output.write(
+          `${Object.keys(context)
+            .sort((a, b) => a.localeCompare(b))
+            .join(", ")}\n`,
+        );
+        rl.prompt();
+        continue;
+      }
+
+      output.write(formatValue(await evaluateAkanConsoleInput(line, context)));
+    } catch (error) {
+      output.write(`${error instanceof Error ? error.stack || error.message : String(error)}\n`);
+    }
+    rl.prompt();
+  }
+};

package/server/index.ts

@@ -3,6 +3,7 @@ export * from "./akanLib";
 export * from "./akanOption";
 export * from "./akanServer";
 export * from "./artifact";
+export * from "./console";
 export * from "./decorators";
 export type { ChangeBatch, ChangeKind } from "./hmr/changeBatch";
 export * from "./processMetricsCollector";

package/types/server/akanServer.d.ts

@@ -8,6 +8,18 @@ export interface AkanServerProps extends AkanLibProps {
     prefix?: string;
     websocketPrefix?: string;
 }
+export interface AkanServerConsoleInfo {
+    name: string;
+    status: AkanServer["status"];
+    serverMode: AkanServer["serverMode"];
+    env: Pick<BaseEnv, "appName" | "environment" | "operationMode" | "repoName" | "serveDomain" | "databaseMode">;
+    services: string[];
+    signals: string[];
+    adaptors: string[];
+    uses: string[];
+    serviceStages: string[][];
+    adaptorStages: string[][];
+}
 export declare class AkanServer {
     #private;
     status: "stopped" | "initializing" | "initialized" | "starting" | "running" | "stopping";
@@ -34,6 +46,7 @@ export declare class AkanServer {
     getService<T = Service>(refName: string): T;
     getSignal<T = ServerSignal>(refName: string): T;
     getAdaptor<T = Adaptor>(refName: string): T;
+    inspectConsole(): AkanServerConsoleInfo;
     init({ routes: initRoutes, web }?: {
         routes?: boolean;
         web?: boolean;

package/types/server/console.d.ts

@@ -0,0 +1,25 @@
+import type { BaseEnv } from "akanjs/base";
+import type { Adaptor, Service } from "akanjs/service";
+import type { ServerSignal } from "akanjs/signal";
+import type { AkanServer } from "./akanServer.d.ts";
+export interface AkanConsoleOptions {
+    prompt?: string;
+    globals?: Record<string, unknown>;
+    input?: typeof process.stdin;
+    output?: typeof process.stdout;
+}
+export interface AkanConsoleContext extends Record<string, unknown> {
+    server: AkanServer;
+    env: AkanServer["env"];
+    get: AkanServer["get"];
+    service: <T = Service>(refName: string) => T;
+    signal: <T = ServerSignal>(refName: string) => T;
+    adaptor: <T = Adaptor>(refName: string) => T;
+    methods: (value: unknown) => string[];
+    debug: () => ReturnType<AkanServer["inspectConsole"]>;
+}
+export declare const assertAkanConsoleAllowed: (env?: Pick<BaseEnv, "environment" | "operationMode">) => void;
+export declare const getAkanConsoleMethods: (value: unknown) => string[];
+export declare const createAkanConsoleContext: (server: AkanServer, globals?: Record<string, unknown>) => AkanConsoleContext;
+export declare const evaluateAkanConsoleInput: (source: string, context: Record<string, unknown>) => Promise<unknown>;
+export declare const startAkanConsole: (server: AkanServer, options?: AkanConsoleOptions) => Promise<void>;

package/types/server/index.d.ts

@@ -3,6 +3,7 @@ export * from "./akanLib.d.ts";
 export * from "./akanOption.d.ts";
 export * from "./akanServer.d.ts";
 export * from "./artifact.d.ts";
+export * from "./console.d.ts";
 export * from "./decorators.d.ts";
 export type { ChangeBatch, ChangeKind } from "./hmr/changeBatch.d.ts";
 export * from "./processMetricsCollector.d.ts";