@codemation/cli 0.0.1

package/src/dev/DevSourceRestartCoordinator.ts

@@ -0,0 +1,48 @@
+import type { Logger } from "@codemation/host/next/server";
+import process from "node:process";
+
+import { DevelopmentGatewayNotifier } from "./DevelopmentGatewayNotifier";
+
+export class DevSourceRestartCoordinator {
+  constructor(
+    private readonly gatewayNotifier: DevelopmentGatewayNotifier,
+    private readonly performanceDiagnosticsLogger: Logger,
+    private readonly cliLogger: Logger,
+  ) {}
+
+  async runHandshakeAfterSourceChange(gatewayBaseUrl: string, developmentServerToken: string): Promise<void> {
+    const restartStarted = performance.now();
+    try {
+      await this.gatewayNotifier.notify({
+        gatewayBaseUrl,
+        developmentServerToken,
+        payload: {
+          kind: "buildStarted",
+        },
+      });
+      await this.gatewayNotifier.notify({
+        gatewayBaseUrl,
+        developmentServerToken,
+        payload: {
+          kind: "buildCompleted",
+          buildVersion: `${Date.now()}-${process.pid}`,
+        },
+      });
+      const totalMs = performance.now() - restartStarted;
+      this.performanceDiagnosticsLogger.info(
+        `triggered source-based runtime restart timingMs={total:${totalMs.toFixed(1)}}`,
+      );
+    } catch (error) {
+      const exception = error instanceof Error ? error : new Error(String(error));
+      await this.gatewayNotifier.notify({
+        gatewayBaseUrl,
+        developmentServerToken,
+        payload: {
+          kind: "buildFailed",
+          message: exception.message,
+        },
+      });
+      this.cliLogger.error("source-based runtime restart request failed", exception);
+    }
+  }
+}

package/src/dev/DevSourceWatcher.ts

@@ -0,0 +1,102 @@
+import type { FSWatcher } from "chokidar";
+import { watch } from "chokidar";
+import path from "node:path";
+
+export class DevSourceWatcher {
+  private static readonly ignoredDirectoryNames = new Set([
+    ".codemation",
+    ".git",
+    ".next",
+    "coverage",
+    "dist",
+    "node_modules",
+  ]);
+
+  private watcher: FSWatcher | null = null;
+  private debounceTimeout: NodeJS.Timeout | null = null;
+  private readonly changedPathsBuffer = new Set<string>();
+
+  async start(
+    args: Readonly<{
+      roots: ReadonlyArray<string>;
+      onChange: (ctx: Readonly<{ changedPaths: ReadonlyArray<string> }>) => Promise<void>;
+    }>,
+  ): Promise<void> {
+    if (this.watcher) {
+      return;
+    }
+    this.watcher = watch([...args.roots], {
+      ignoreInitial: true,
+      ignored: (watchPath: string) => this.isIgnoredPath(watchPath),
+    });
+    this.watcher.on("all", (_eventName, watchPath) => {
+      if (typeof watchPath !== "string" || watchPath.length === 0) {
+        return;
+      }
+      if (!this.isRelevantPath(watchPath)) {
+        return;
+      }
+      this.changedPathsBuffer.add(path.resolve(watchPath));
+      this.scheduleDebouncedChange(args.onChange);
+    });
+  }
+
+  async stop(): Promise<void> {
+    if (this.debounceTimeout) {
+      clearTimeout(this.debounceTimeout);
+      this.debounceTimeout = null;
+    }
+    if (this.watcher) {
+      await this.watcher.close();
+      this.watcher = null;
+    }
+  }
+
+  private scheduleDebouncedChange(
+    onChange: (ctx: Readonly<{ changedPaths: ReadonlyArray<string> }>) => Promise<void>,
+  ): void {
+    if (this.debounceTimeout) {
+      clearTimeout(this.debounceTimeout);
+    }
+    this.debounceTimeout = setTimeout(() => {
+      this.debounceTimeout = null;
+      void this.flushPendingChange(onChange);
+    }, 75);
+  }
+
+  private async flushPendingChange(
+    onChange: (ctx: Readonly<{ changedPaths: ReadonlyArray<string> }>) => Promise<void>,
+  ): Promise<void> {
+    if (this.changedPathsBuffer.size === 0) {
+      return;
+    }
+    const changedPaths = [...this.changedPathsBuffer];
+    this.changedPathsBuffer.clear();
+    await onChange({ changedPaths });
+  }
+
+  private isIgnoredPath(watchPath: string): boolean {
+    const normalized = path.resolve(watchPath).replace(/\\/g, "/");
+    return normalized.split("/").some((segment: string) => DevSourceWatcher.ignoredDirectoryNames.has(segment));
+  }
+
+  private isRelevantPath(watchPath: string): boolean {
+    const fileName = path.basename(watchPath);
+    if (fileName === ".env" || fileName.startsWith(".env.")) {
+      return true;
+    }
+    const extension = path.extname(watchPath).toLowerCase();
+    return (
+      extension === ".cts" ||
+      extension === ".cjs" ||
+      extension === ".js" ||
+      extension === ".json" ||
+      extension === ".jsx" ||
+      extension === ".mts" ||
+      extension === ".mjs" ||
+      extension === ".prisma" ||
+      extension === ".ts" ||
+      extension === ".tsx"
+    );
+  }
+}

package/src/dev/DevTrackedProcessTreeKiller.ts

@@ -0,0 +1,107 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import process from "node:process";
+
+/**
+ * Stops a spawned dev child and every descendant process.
+ *
+ * On Unix, children are expected to have been created with `spawn({ detached: true })` so the root
+ * child is the process-group leader; we first send `SIGTERM` to the whole group and only escalate to
+ * `SIGKILL` when the process does not exit within the grace period.
+ * On Windows, uses `taskkill /F /T` to terminate the process tree.
+ */
+export class DevTrackedProcessTreeKiller {
+  constructor(private readonly terminationGracePeriodMs = 1500) {}
+
+  async killProcessTreeRootedAt(child: ChildProcess): Promise<void> {
+    const pid = child.pid;
+    if (pid === undefined) {
+      if (!(await this.trySigTerm(child))) {
+        this.trySigKill(child);
+        await this.waitForExit(child);
+      }
+      return;
+    }
+    if (process.platform === "win32") {
+      await this.killWindowsProcessTree(pid);
+      await this.waitForExit(child);
+    } else {
+      if (!(await this.trySigTermProcessGroup(pid, child))) {
+        this.trySigKill(child);
+        this.trySigKillProcessGroup(pid);
+        await this.waitForExit(child);
+      }
+    }
+  }
+
+  private trySigKill(child: ChildProcess): void {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+      // Process may already be gone.
+    }
+  }
+
+  private killWindowsProcessTree(pid: number): Promise<void> {
+    return new Promise((resolve) => {
+      const proc = spawn("taskkill", ["/F", "/T", "/PID", String(pid)], {
+        stdio: "ignore",
+        windowsHide: true,
+      });
+      proc.once("exit", () => {
+        resolve();
+      });
+      proc.once("error", () => {
+        resolve();
+      });
+    });
+  }
+
+  private async trySigTerm(child: ChildProcess): Promise<boolean> {
+    try {
+      child.kill("SIGTERM");
+    } catch {
+      return child.exitCode !== null || child.signalCode !== null;
+    }
+    return await this.waitForExit(child, this.terminationGracePeriodMs);
+  }
+
+  private async trySigTermProcessGroup(pid: number, child: ChildProcess): Promise<boolean> {
+    try {
+      process.kill(-pid, "SIGTERM");
+    } catch {
+      return await this.trySigTerm(child);
+    }
+    return await this.waitForExit(child, this.terminationGracePeriodMs);
+  }
+
+  private trySigKillProcessGroup(pid: number): void {
+    try {
+      process.kill(-pid, "SIGKILL");
+    } catch {
+      // Process group may already be gone.
+    }
+  }
+
+  private waitForExit(child: ChildProcess, timeoutMs?: number): Promise<boolean> {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      return Promise.resolve(true);
+    }
+    return new Promise<boolean>((resolve) => {
+      let timeout: NodeJS.Timeout | undefined;
+      const onExit = () => {
+        if (timeout) {
+          clearTimeout(timeout);
+        }
+        resolve(true);
+      };
+      child.once("exit", onExit);
+      if (timeoutMs === undefined) {
+        return;
+      }
+      timeout = setTimeout(() => {
+        child.removeListener("exit", onExit);
+        resolve(child.exitCode !== null || child.signalCode !== null);
+      }, timeoutMs);
+    });
+  }
+}

package/src/dev/DevelopmentGatewayNotifier.ts

@@ -0,0 +1,35 @@
+import { ApiPaths } from "@codemation/host";
+import type { Logger } from "@codemation/host/next/server";
+
+export class DevelopmentGatewayNotifier {
+  constructor(private readonly cliLogger: Logger) {}
+
+  async notify(
+    args: Readonly<{
+      gatewayBaseUrl: string;
+      developmentServerToken: string;
+      payload: Readonly<{
+        kind: "buildStarted" | "buildCompleted" | "buildFailed";
+        buildVersion?: string;
+        message?: string;
+      }>;
+    }>,
+  ): Promise<void> {
+    const targetUrl = `${args.gatewayBaseUrl.replace(/\/$/, "")}${ApiPaths.devGatewayNotify()}`;
+    try {
+      const response = await fetch(targetUrl, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-codemation-dev-token": args.developmentServerToken,
+        },
+        body: JSON.stringify(args.payload),
+      });
+      if (!response.ok) {
+        this.cliLogger.warn(`failed to notify dev gateway status=${response.status}`);
+      }
+    } catch (error) {
+      this.cliLogger.warn(`failed to notify dev gateway: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}

package/src/dev/Factory.ts

@@ -0,0 +1,7 @@
+import { DevLock } from "./DevLock";
+
+export class DevLockFactory {
+  create(): DevLock {
+    return new DevLock();
+  }
+}

package/src/dev/LoopbackPortAllocator.ts

@@ -0,0 +1,20 @@
+import { createServer } from "node:net";
+
+export class LoopbackPortAllocator {
+  async allocate(): Promise<number> {
+    return await new Promise<number>((resolve, reject) => {
+      const server = createServer();
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", () => {
+        const address = server.address();
+        server.close(() => {
+          if (address && typeof address === "object") {
+            resolve(address.port);
+            return;
+          }
+          reject(new Error("Failed to resolve a free TCP port."));
+        });
+      });
+    });
+  }
+}

package/src/dev/Runner.ts

@@ -0,0 +1,7 @@
+import { DevSourceWatcher } from "./DevSourceWatcher";
+
+export class DevSourceWatcherFactory {
+  create(): DevSourceWatcher {
+    return new DevSourceWatcher();
+  }
+}

package/src/dev/RuntimeToolEntrypointResolver.ts

@@ -0,0 +1,47 @@
+import { access } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import process from "node:process";
+
+export type ResolvedRuntimeToolEntrypoint = Readonly<{
+  args: ReadonlyArray<string>;
+  command: string;
+  env: Readonly<Record<string, string>>;
+}>;
+
+export class RuntimeToolEntrypointResolver {
+  private readonly require = createRequire(import.meta.url);
+
+  async resolve(
+    args: Readonly<{
+      packageName: string;
+      repoRoot: string;
+      sourceEntrypoint: string;
+    }>,
+  ): Promise<ResolvedRuntimeToolEntrypoint> {
+    const sourceEntrypointPath = path.resolve(args.repoRoot, args.sourceEntrypoint);
+    if (await this.exists(sourceEntrypointPath)) {
+      return {
+        command: process.execPath,
+        args: ["--import", "tsx", sourceEntrypointPath],
+        env: {
+          TSX_TSCONFIG_PATH: path.resolve(args.repoRoot, "tsconfig.codemation-tsx.json"),
+        },
+      };
+    }
+    return {
+      command: process.execPath,
+      args: [this.require.resolve(args.packageName)],
+      env: {},
+    };
+  }
+
+  private async exists(filePath: string): Promise<boolean> {
+    try {
+      await access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/dev/WatchRootsResolver.ts

@@ -0,0 +1,26 @@
+import path from "node:path";
+
+export class WatchRootsResolver {
+  resolve(
+    args: Readonly<{
+      consumerRoot: string;
+      devMode: "consumer" | "framework";
+      repoRoot: string;
+    }>,
+  ): ReadonlyArray<string> {
+    if (args.devMode === "consumer") {
+      return [args.consumerRoot];
+    }
+    return [
+      args.consumerRoot,
+      path.resolve(args.repoRoot, "packages", "core"),
+      path.resolve(args.repoRoot, "packages", "core-nodes"),
+      path.resolve(args.repoRoot, "packages", "core-nodes-gmail"),
+      path.resolve(args.repoRoot, "packages", "eventbus-redis"),
+      path.resolve(args.repoRoot, "packages", "host"),
+      path.resolve(args.repoRoot, "packages", "node-example"),
+      path.resolve(args.repoRoot, "packages", "queue-bullmq"),
+      path.resolve(args.repoRoot, "packages", "runtime-dev"),
+    ];
+  }
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { CodemationCliApplicationSession } from "./bootstrap/CodemationCliApplicationSession";
+export { CliBin } from "./CliBin";
+export { CliProgramFactory } from "./CliProgramFactory";
+export { CliPathResolver, type CliPaths } from "./path/CliPathResolver";
+export { CliProgram } from "./Program";
+export { ConsumerBuildOptionsParser } from "./build/ConsumerBuildOptionsParser";
+export { ConsumerOutputBuilder } from "./consumer/ConsumerOutputBuilder";
+export type { ConsumerOutputBuildSnapshot } from "./consumer/ConsumerOutputBuilder";
+export type { ConsumerBuildOptions, EcmaScriptBuildTarget } from "./consumer/consumerBuildOptions.types";
+export type { CodemationDiscoveredPluginPackage, CodemationResolvedPluginPackage } from "@codemation/host/server";
+export { CodemationPluginDiscovery } from "@codemation/host/server";
+export type { LocalUserCreateOptions } from "./user/LocalUserCreator";

package/src/path/CliPathResolver.ts

@@ -0,0 +1,41 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+
+export type CliPaths = Readonly<{
+  consumerRoot: string;
+  repoRoot: string;
+}>;
+
+export class CliPathResolver {
+  async resolve(consumerStartPath: string): Promise<CliPaths> {
+    const consumerRoot = path.resolve(consumerStartPath);
+    const repoRoot = await this.detectWorkspaceRoot(consumerRoot);
+    return {
+      consumerRoot,
+      repoRoot: repoRoot ?? consumerRoot,
+    };
+  }
+
+  private async detectWorkspaceRoot(startDirectory: string): Promise<string | null> {
+    let currentDirectory = path.resolve(startDirectory);
+    while (true) {
+      if (await this.exists(path.resolve(currentDirectory, "pnpm-workspace.yaml"))) {
+        return currentDirectory;
+      }
+      const parentDirectory = path.dirname(currentDirectory);
+      if (parentDirectory === currentDirectory) {
+        return null;
+      }
+      currentDirectory = parentDirectory;
+    }
+  }
+
+  private async exists(filePath: string): Promise<boolean> {
+    try {
+      await access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/runtime/ListenPortResolver.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared HTTP listen port parsing for CLI commands (dev server, serve web, etc.).
+ */
+export class ListenPortResolver {
+  resolvePrimaryApplicationPort(rawPort: string | undefined): number {
+    const parsedPort = Number(rawPort);
+    if (Number.isInteger(parsedPort) && parsedPort > 0) {
+      return parsedPort;
+    }
+    return 3000;
+  }
+
+  parsePositiveInteger(raw: string | undefined): number | null {
+    const parsed = Number(raw);
+    if (Number.isInteger(parsed) && parsed > 0) {
+      return parsed;
+    }
+    return null;
+  }
+
+  resolveWebsocketPortRelativeToHttp(
+    args: Readonly<{
+      nextPort: number;
+      publicWebsocketPort: string | undefined;
+      websocketPort: string | undefined;
+    }>,
+  ): number {
+    const explicit =
+      this.parsePositiveInteger(args.publicWebsocketPort) ?? this.parsePositiveInteger(args.websocketPort);
+    if (explicit !== null) {
+      return explicit;
+    }
+    return args.nextPort + 1;
+  }
+}

package/src/runtime/SourceMapNodeOptions.ts

@@ -0,0 +1,12 @@
+export class SourceMapNodeOptions {
+  appendToNodeOptions(existingNodeOptions: string | undefined): string {
+    const sourceMapOption = "--enable-source-maps";
+    if (!existingNodeOptions || existingNodeOptions.trim().length === 0) {
+      return sourceMapOption;
+    }
+    if (existingNodeOptions.includes(sourceMapOption)) {
+      return existingNodeOptions;
+    }
+    return `${existingNodeOptions} ${sourceMapOption}`.trim();
+  }
+}

package/src/runtime/TypeScriptRuntimeConfigurator.ts

@@ -0,0 +1,8 @@
+import path from "node:path";
+import process from "node:process";
+
+export class TypeScriptRuntimeConfigurator {
+  configure(repoRoot: string): void {
+    process.env.CODEMATION_TSCONFIG_PATH = path.resolve(repoRoot, "tsconfig.base.json");
+  }
+}

package/src/user/CliDatabaseUrlDescriptor.ts

@@ -0,0 +1,33 @@
+import type { ResolvedDatabasePersistence } from "@codemation/host/persistence";
+
+/**
+ * Formats a database URL for CLI messages without exposing credentials (no user/password).
+ */
+export class CliDatabaseUrlDescriptor {
+  describePersistence(persistence: ResolvedDatabasePersistence): string {
+    if (persistence.kind === "none") {
+      return "none";
+    }
+    if (persistence.kind === "postgresql") {
+      return this.describeForDisplay(persistence.databaseUrl);
+    }
+    return `PGlite (${persistence.dataDir})`;
+  }
+
+  describeForDisplay(databaseUrl: string | undefined): string {
+    if (!databaseUrl || databaseUrl.trim().length === 0) {
+      return "unknown database target";
+    }
+    try {
+      const u = new URL(databaseUrl);
+      const pathPart = u.pathname.replace(/^\//, "").split(/[?#]/)[0] ?? "";
+      const databaseName = pathPart.length > 0 ? pathPart : "(default)";
+      const defaultPort = u.protocol === "postgresql:" || u.protocol === "postgres:" ? "5432" : "";
+      const port = u.port || defaultPort;
+      const hostPort = port ? `${u.hostname}:${port}` : u.hostname;
+      return `database "${databaseName}" on ${hostPort}`;
+    } catch {
+      return "configured database (URL not shown)";
+    }
+  }
+}

package/src/user/LocalUserCreator.ts

@@ -0,0 +1,29 @@
+import { UpsertLocalBootstrapUserCommand } from "@codemation/host";
+import { logLevelPolicyFactory, ServerLoggerFactory } from "@codemation/host/next/server";
+
+import type { UserAdminCliBootstrap, UserAdminCliOptions } from "./UserAdminCliBootstrap";
+
+export type LocalUserCreateOptions = Readonly<
+  UserAdminCliOptions & {
+    email: string;
+    password: string;
+  }
+>;
+
+export class LocalUserCreator {
+  private readonly log = new ServerLoggerFactory(logLevelPolicyFactory).create("codemation-cli.user");
+
+  constructor(private readonly userAdminBootstrap: UserAdminCliBootstrap) {}
+
+  async run(options: LocalUserCreateOptions): Promise<void> {
+    const email = options.email;
+    const password = options.password;
+    await this.userAdminBootstrap.withSession(
+      { consumerRoot: options.consumerRoot, configPath: options.configPath },
+      async (session) => {
+        const result = await session.getCommandBus().execute(new UpsertLocalBootstrapUserCommand(email, password));
+        this.log.info(result.outcome === "created" ? `Created local user: ${email}` : `Updated local user: ${email}`);
+      },
+    );
+  }
+}

package/src/user/UserAdminCliBootstrap.ts

@@ -0,0 +1,67 @@
+import { CodemationBootstrapRequest } from "@codemation/host";
+import { DatabasePersistenceResolver } from "@codemation/host/persistence";
+import { CodemationConsumerConfigLoader } from "@codemation/host/server";
+
+import { CodemationCliApplicationSession } from "../bootstrap/CodemationCliApplicationSession";
+import type { ConsumerCliTsconfigPreparation } from "../consumer/ConsumerCliTsconfigPreparation";
+import { CliPathResolver } from "../path/CliPathResolver";
+import type { UserAdminConsumerDotenvLoader } from "./UserAdminConsumerDotenvLoader";
+
+export type UserAdminCliOptions = Readonly<{
+  consumerRoot?: string;
+  configPath?: string;
+}>;
+
+/**
+ * Shared env/config/session wiring for `codemation user *` commands (local auth + database).
+ */
+export class UserAdminCliBootstrap {
+  constructor(
+    private readonly configLoader: CodemationConsumerConfigLoader,
+    private readonly pathResolver: CliPathResolver,
+    private readonly consumerDotenvLoader: UserAdminConsumerDotenvLoader,
+    private readonly tsconfigPreparation: ConsumerCliTsconfigPreparation,
+    private readonly databasePersistenceResolver: DatabasePersistenceResolver,
+  ) {}
+
+  async withSession<T>(
+    options: UserAdminCliOptions,
+    fn: (session: CodemationCliApplicationSession) => Promise<T>,
+  ): Promise<T> {
+    const consumerRoot = options.consumerRoot ?? process.cwd();
+    this.consumerDotenvLoader.load(consumerRoot);
+    this.tsconfigPreparation.applyWorkspaceTsconfigForTsxIfPresent(consumerRoot);
+    const resolution = await this.configLoader.load({
+      consumerRoot,
+      configPathOverride: options.configPath,
+    });
+    if (resolution.config.auth?.kind !== "local") {
+      throw new Error('Codemation user commands require CodemationConfig.auth.kind to be "local".');
+    }
+    const persistence = this.databasePersistenceResolver.resolve({
+      runtimeConfig: resolution.config.runtime ?? {},
+      env: process.env,
+      consumerRoot,
+    });
+    if (persistence.kind === "none") {
+      throw new Error(
+        "Database persistence is not configured. Set CodemationConfig.runtime.database (postgresql URL or PGlite).",
+      );
+    }
+    const paths = await this.pathResolver.resolve(consumerRoot);
+    const session = await CodemationCliApplicationSession.open({
+      resolution,
+      bootstrap: new CodemationBootstrapRequest({
+        repoRoot: paths.repoRoot,
+        consumerRoot,
+        env: process.env,
+        workflowSources: resolution.workflowSources,
+      }),
+    });
+    try {
+      return await fn(session);
+    } finally {
+      await session.close();
+    }
+  }
+}

package/src/user/UserAdminCliOptionsParser.ts

@@ -0,0 +1,24 @@
+import path from "node:path";
+import process from "node:process";
+
+import type { UserAdminCliOptions } from "./UserAdminCliBootstrap";
+
+/**
+ * Normalizes Commander flags (`--consumer-root`, `--config`) into {@link UserAdminCliOptions}
+ * for {@link UserAdminCliBootstrap.withSession}.
+ */
+export type UserAdminCliCommandOptionsRaw = Readonly<{
+  consumerRoot?: string;
+  config?: string;
+}>;
+
+export class UserAdminCliOptionsParser {
+  parse(opts: UserAdminCliCommandOptionsRaw): UserAdminCliOptions {
+    const consumerRoot =
+      opts.consumerRoot !== undefined && opts.consumerRoot.trim().length > 0
+        ? path.resolve(process.cwd(), opts.consumerRoot.trim())
+        : undefined;
+    const configPath = opts.config !== undefined && opts.config.trim().length > 0 ? opts.config.trim() : undefined;
+    return { consumerRoot, configPath };
+  }
+}