@promptbook/cli 0.112.0-99 → 0.113.0-0

package/src/cli/cli-commands/coder/ensureCoderDeveloperAgentFile.ts

@@ -0,0 +1,79 @@
+import { copyFile, stat } from 'fs/promises';
+import { join } from 'path';
+import { spaceTrim } from 'spacetrim';
+import { NotAllowed } from '../../../errors/NotAllowed';
+import type { InitializationStatus } from './boilerplateTemplates';
+
+/**
+ * Relative directory path for agents initialized by `ptbk coder init`.
+ *
+ * @private internal utility of `coder init` command
+ */
+export const CODER_AGENTS_DIRECTORY_PATH = 'agents';
+
+/**
+ * Relative file path to the default developer agent initialized by `ptbk coder init`.
+ *
+ * @private internal utility of `coder init` command
+ */
+export const CODER_DEVELOPER_AGENT_FILE_PATH = 'agents/developer.book';
+
+/**
+ * Source file path of the bundled developer agent inside the Promptbook repository.
+ *
+ * @private internal utility of `coder init` command
+ */
+export const DEFAULT_CODER_DEVELOPER_AGENT_SOURCE_FILE_PATH = 'agents/default/developer.book';
+
+/**
+ * Ensures the default developer agent exists in the initialized project.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+export async function ensureCoderDeveloperAgentFile(projectPath: string): Promise<InitializationStatus> {
+    const absoluteFilePath = join(projectPath, CODER_DEVELOPER_AGENT_FILE_PATH);
+    if (await isExistingFile(absoluteFilePath)) {
+        return 'unchanged';
+    }
+
+    await copyFile(await resolveDefaultCoderDeveloperAgentFilePath(), absoluteFilePath);
+    return 'created';
+}
+
+/**
+ * Resolves the bundled developer agent from a source checkout or generated CLI package.
+ */
+async function resolveDefaultCoderDeveloperAgentFilePath(): Promise<string> {
+    const candidates = [
+        join(__dirname, '..', DEFAULT_CODER_DEVELOPER_AGENT_SOURCE_FILE_PATH),
+        join(__dirname, '..', '..', '..', '..', DEFAULT_CODER_DEVELOPER_AGENT_SOURCE_FILE_PATH),
+    ];
+
+    for (const candidate of candidates) {
+        if (await isExistingFile(candidate)) {
+            return candidate;
+        }
+    }
+
+    throw new NotAllowed(
+        spaceTrim(`
+            Cannot find the bundled Promptbook developer agent.
+
+            Checked:
+            ${candidates.map((candidate) => `- \`${candidate}\``).join('\n')}
+        `),
+    );
+}
+
+/**
+ * Checks whether a path exists and is a file.
+ */
+async function isExistingFile(path: string): Promise<boolean> {
+    try {
+        return (await stat(path)).isFile();
+    } catch {
+        return false;
+    }
+}
+
+// Note: [🟡] Code for coder init developer agent bootstrapping [ensureCoderDeveloperAgentFile](src/cli/cli-commands/coder/ensureCoderDeveloperAgentFile.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/coder/find-unwritten.ts

@@ -0,0 +1,58 @@
+import colors from 'colors';
+import { Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */ } from 'commander';
+import { assertsError } from '../../../errors/assertsError';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { handleActionErrors } from '../common/handleActionErrors';
+
+/**
+ * Initializes `coder find-unwritten` command for Promptbook CLI utilities
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI
+ *
+ * @private internal function of `promptbookCli`
+ */
+export function $initializeCoderFindUnwrittenCommand(program: Program): $side_effect {
+    const command = program.command('find-unwritten');
+    command.description('List all prompt sections that still need to be authored (contain @@@ placeholder)');
+    command.option('--priority <minimum-priority>', 'Filter prompts by minimum priority level', parseIntOption, 0);
+
+    command.action(
+        handleActionErrors(async (cliOptions) => {
+            const { priority = 0 } = cliOptions as {
+                readonly priority?: number;
+            };
+
+            // Note: Import the function dynamically to avoid loading heavy dependencies until needed
+            const { findUnwrittenPrompts } = await import(
+                '../../../../scripts/run-codex-prompts/main/findUnwrittenPrompts'
+            );
+
+            try {
+                await findUnwrittenPrompts({ priority });
+            } catch (error) {
+                assertsError(error);
+                console.error(colors.bgRed(`${error.name}`));
+                console.error(colors.red(error.stack || error.message));
+                return process.exit(1);
+            }
+
+            return process.exit(0);
+        }),
+    );
+}
+
+/**
+ * Parses an integer option value
+ *
+ * @private internal utility of `coder find-unwritten` command
+ */
+function parseIntOption(value: string): number {
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed)) {
+        throw new Error(`Invalid number: ${value}`);
+    }
+    return parsed;
+}
+
+// Note: [🟡] Code for CLI command [find-unwritten](src/cli/cli-commands/coder/find-unwritten.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/cli/cli-commands/coder/getDefaultCoderPackageJsonScripts.ts

@@ -4,8 +4,8 @@
 const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
     'coder:generate-boilerplates': 'ptbk coder generate-boilerplates --template ./prompts/templates/common.md',
     'coder:run':
-        'ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --no-wait',
-    'coder:find-refactor-candidates': 'ptbk coder find-refactor-candidates',
+        'ptbk coder run --harness openai-codex --model gpt-5.5 --thinking-level xhigh --agent agents/developer.book --context AGENTS.md',
+    // 'coder:find-refactor-candidates': 'ptbk coder find-refactor-candidates',
     'coder:verify': 'ptbk coder verify',
 } as const satisfies Readonly<Record<string, string>>;
 

package/src/cli/cli-commands/coder/init.ts

@@ -7,7 +7,9 @@ import { handleActionErrors } from '../common/handleActionErrors';
 import { AGENT_CODING_FILE_PATH } from './agentCodingFile';
 import { AGENTS_FILE_PATH } from './agentsFile';
 import { getDefaultCoderProjectPromptTemplateDefinitions } from './boilerplateTemplates';
+import { CODER_DEVELOPER_AGENT_FILE_PATH } from './ensureCoderDeveloperAgentFile';
 import { formatDisplayPath } from './formatDisplayPath';
+import { generatePromptBoilerplate } from './generate-boilerplates';
 import { initializeCoderProjectConfiguration } from './initializeCoderProjectConfiguration';
 import { printInitializationSummary } from './printInitializationSummary';
 
@@ -33,6 +35,7 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
             - prompts/
             - prompts/done/
             ${listDefaultCoderProjectPromptTemplateDisplayPaths()}
+            - ${CODER_DEVELOPER_AGENT_FILE_PATH}
             - ${AGENTS_FILE_PATH}
             - ${AGENT_CODING_FILE_PATH}
             - .gitignore
@@ -48,8 +51,10 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
 
     command.action(
         handleActionErrors(async () => {
-            const summary = await initializeCoderProjectConfiguration(process.cwd());
+            const projectPath = process.cwd();
+            const summary = await initializeCoderProjectConfiguration(projectPath);
             printInitializationSummary(summary);
+            await generatePromptBoilerplate({ projectPath, filesCount: 5 });
         }),
     );
 }

package/src/cli/cli-commands/coder/initializeCoderProjectConfiguration.ts

@@ -8,6 +8,10 @@ import {
     PROMPTS_TEMPLATES_DIRECTORY_PATH,
 } from './boilerplateTemplates';
 import { ensureCoderEnvFile } from './ensureCoderEnvFile';
+import {
+    CODER_AGENTS_DIRECTORY_PATH,
+    ensureCoderDeveloperAgentFile,
+} from './ensureCoderDeveloperAgentFile';
 import { ensureCoderGitignoreFile } from './ensureCoderGitignoreFile';
 import { ensureCoderMarkdownFile } from './ensureCoderMarkdownFile';
 import { ensureCoderPackageJsonFile } from './ensureCoderPackageJsonFile';
@@ -25,6 +29,8 @@ export type CoderInitializationSummary = {
     readonly promptsDoneDirectoryStatus: InitializationStatus;
     readonly promptsTemplatesDirectoryStatus: InitializationStatus;
     readonly promptTemplateFileStatuses: ReadonlyArray<EnsuredCoderPromptTemplateFile>;
+    readonly agentsDirectoryStatus: InitializationStatus;
+    readonly developerAgentFileStatus: InitializationStatus;
     readonly agentsFileStatus: InitializationStatus;
     readonly agentCodingFileStatus: InitializationStatus;
     readonly envFileStatus: InitializationStatus;
@@ -44,6 +50,8 @@ export async function initializeCoderProjectConfiguration(projectPath: string):
     const promptsDoneDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DONE_DIRECTORY_PATH);
     const promptsTemplatesDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_TEMPLATES_DIRECTORY_PATH);
     const promptTemplateFileStatuses = await ensureDefaultCoderPromptTemplateFiles(projectPath);
+    const agentsDirectoryStatus = await ensureDirectory(projectPath, CODER_AGENTS_DIRECTORY_PATH);
+    const developerAgentFileStatus = await ensureCoderDeveloperAgentFile(projectPath);
     const agentsFileStatus = await ensureCoderMarkdownFile(
         projectPath,
         AGENTS_FILE_PATH,
@@ -66,6 +74,8 @@ export async function initializeCoderProjectConfiguration(projectPath: string):
         promptsDoneDirectoryStatus,
         promptsTemplatesDirectoryStatus,
         promptTemplateFileStatuses,
+        agentsDirectoryStatus,
+        developerAgentFileStatus,
         agentsFileStatus,
         agentCodingFileStatus,
         envFileStatus,

package/src/cli/cli-commands/coder/printInitializationSummary.ts

@@ -2,6 +2,7 @@ import colors from 'colors';
 import { AGENT_CODING_FILE_PATH } from './agentCodingFile';
 import { AGENTS_FILE_PATH } from './agentsFile';
 import type { InitializationStatus } from './boilerplateTemplates';
+import { CODER_DEVELOPER_AGENT_FILE_PATH } from './ensureCoderDeveloperAgentFile';
 import { formatDisplayPath } from './formatDisplayPath';
 import type { CoderInitializationSummary } from './initializeCoderProjectConfiguration';
 
@@ -23,6 +24,8 @@ export function printInitializationSummary(summary: CoderInitializationSummary):
         );
     }
 
+    printInitializationStatusLine('agents/', summary.agentsDirectoryStatus);
+    printInitializationStatusLine(CODER_DEVELOPER_AGENT_FILE_PATH, summary.developerAgentFileStatus);
     printInitializationStatusLine(AGENTS_FILE_PATH, summary.agentsFileStatus);
     printInitializationStatusLine(AGENT_CODING_FILE_PATH, summary.agentCodingFileStatus);
     printInitializationStatusLine('.env', summary.envFileStatus);

package/src/cli/cli-commands/coder/run.ts

@@ -1,6 +1,7 @@
 import colors from 'colors';
 import { Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */ } from 'commander';
 import { spaceTrim } from 'spacetrim';
+import { NotAllowed } from '../../../errors/NotAllowed';
 import { assertsError } from '../../../errors/assertsError';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 import { handleActionErrors } from '../common/handleActionErrors';
@@ -11,6 +12,10 @@ import {
     normalizePromptRunnerCliOptions,
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
+import {
+    DEFAULT_WAIT_AFTER_ERROR_MS,
+    parseOptionalWaitDuration,
+} from './waitOptions';
 
 /**
  * Initializes `coder run` command for Promptbook CLI utilities
@@ -42,6 +47,10 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
 
     command.option('--dry-run', 'Print unwritten prompts without executing', false);
     addPromptRunnerSelectionOptions(command);
+    command.option(
+        '--agent <agent-book-path>',
+        'Path to a .book file whose compiled system message is prepended to each coding prompt',
+    );
     command.option(
         '--context <context-or-file>',
         'Append extra instructions either inline or from a file path relative to the current project',
@@ -57,7 +66,38 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
     );
     addPromptRunnerExecutionOptions(command);
     command.option('--priority <minimum-priority>', 'Filter prompts by minimum priority level', parseIntOption, 0);
-    command.option('--no-wait', 'Skip user prompts between processing');
+    command.option(
+        '--limit <run-count>',
+        'Stop after processing this many prompt runs',
+        parsePositiveIntegerOption,
+    );
+    command.option(
+        '--wait-after-prompt <duration>',
+        spaceTrim(`
+            Wait this long after each prompt has been implemented, verified and committed before starting the next prompt.
+            Accepts durations like 1h, 30m, 5s. Defaults to 0 (no wait).
+        `),
+    );
+    command.option(
+        '--wait-between-prompts <duration>',
+        spaceTrim(`
+            Pace prompts so that each next prompt starts at least this long after the previous one began.
+            If the previous prompt already took longer than this, the next prompt starts immediately.
+            Accepts durations like 1h, 30m, 5s. Defaults to 0 (no pacing).
+        `),
+    );
+    command.option(
+        '--wait-after-error <duration>',
+        spaceTrim(`
+            Wait this long before retrying a prompt after an error occurs (up to 3 retries before giving up).
+            Accepts durations like 1h, 30m, 5s. Defaults to 10m.
+        `),
+    );
+    // Note: --no-auto disables the default auto behaviour and waits for user confirmation before each prompt
+    command.option(
+        '--no-auto',
+        'Wait for user confirmation before each prompt instead of running automatically through the queue',
+    );
     command.option(
         '--auto-migrate',
         'Run testing-server database migrations automatically after each successfully processed prompt',
@@ -69,37 +109,71 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
 
     command.action(
         handleActionErrors(async (cliOptions) => {
-            const { dryRun, context, test, preserveLogs, priority, wait, autoMigrate, allowDestructiveAutoMigrate } =
-                cliOptions as {
-                    readonly dryRun: boolean;
-                    readonly context?: string;
-                    readonly test?: string | string[];
-                    readonly preserveLogs: boolean;
-                    readonly priority: number;
-                    readonly wait: boolean;
-                    readonly autoMigrate: boolean;
-                    readonly allowDestructiveAutoMigrate: boolean;
-                } & PromptRunnerCliOptions;
+            const {
+                dryRun,
+                agent,
+                context,
+                test,
+                preserveLogs,
+                priority,
+                limit,
+                waitAfterPrompt: waitAfterPromptValue,
+                waitBetweenPrompts: waitBetweenPromptsValue,
+                waitAfterError: waitAfterErrorValue,
+                auto,
+                autoMigrate,
+                allowDestructiveAutoMigrate,
+            } = cliOptions as {
+                readonly dryRun: boolean;
+                readonly agent?: string;
+                readonly context?: string;
+                readonly test?: string | string[];
+                readonly preserveLogs: boolean;
+                readonly priority: number;
+                readonly limit?: number;
+                readonly waitAfterPrompt?: string;
+                readonly waitBetweenPrompts?: string;
+                readonly waitAfterError?: string;
+                readonly auto: boolean;
+                readonly autoMigrate: boolean;
+                readonly allowDestructiveAutoMigrate: boolean;
+            } & PromptRunnerCliOptions;
 
             const testCommand = normalizeCommandOptionValue(test);
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
                 isAgentRequired: !dryRun,
             });
 
+            // [1] Parse the wait options and --no-auto:
+            //   default: run automatically through the queue (no waiting between prompts)
+            //   --no-auto: wait for user confirmation before each prompt (interactive mode)
+            //   --wait-after-prompt: pause after a successful round before starting the next prompt
+            //   --wait-between-prompts: pace from start of one prompt to start of next
+            //   --wait-after-error: wait before retrying after an error (default 10m)
+            const waitForUser = !auto;
+            const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
+            const waitBetweenPrompts = parseOptionalWaitDuration(waitBetweenPromptsValue, 0);
+            const waitAfterError = parseOptionalWaitDuration(waitAfterErrorValue, DEFAULT_WAIT_AFTER_ERROR_MS);
+
             // Convert commander options to RunOptions format
             const runOptions = {
                 dryRun,
-                waitForUser: wait,
+                waitForUser,
+                waitAfterPrompt,
+                waitBetweenPrompts,
+                waitAfterError,
                 noCommit: runnerOptions.noCommit,
                 ignoreGitChanges: runnerOptions.ignoreGitChanges,
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
+                agent,
                 context,
                 testCommand,
                 preserveLogs,
                 noUi: runnerOptions.noUi,
                 thinkingLevel: runnerOptions.thinkingLevel,
                 priority,
+                limit,
                 normalizeLineEndings: runnerOptions.normalizeLineEndings,
                 allowCredits: runnerOptions.allowCredits,
                 autoMigrate,
@@ -139,6 +213,27 @@ function parseIntOption(value: string): number {
     return parsed;
 }
 
+/**
+ * Parses a positive integer option value.
+ *
+ * @private internal utility of `coder run` command
+ */
+function parsePositiveIntegerOption(value: string): number {
+    const parsed = Number(value);
+
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid value for \`--limit\`: \`${value}\`.
+
+                Use a positive integer.
+            `),
+        );
+    }
+
+    return parsed;
+}
+
 /**
  * Joins one Commander option that may be parsed either as a single string or a variadic token array.
  *

package/src/cli/cli-commands/coder/server.ts

@@ -0,0 +1,259 @@
+import colors from 'colors';
+import { Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */ } from 'commander';
+import { Option } from 'commander';
+import { spaceTrim } from 'spacetrim';
+import { NETWORK_LIMITS } from '../../../constants';
+import { assertsError } from '../../../errors/assertsError';
+import { NotAllowed } from '../../../errors/NotAllowed';
+import type { number_port } from '../../../types/number_positive';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { handleActionErrors } from '../common/handleActionErrors';
+import type { PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
+import {
+    addPromptRunnerExecutionOptions,
+    addPromptRunnerSelectionOptions,
+    normalizePromptRunnerCliOptions,
+    PROMPT_RUNNER_DESCRIPTION,
+} from '../common/promptRunnerCliOptions';
+import { DEFAULT_WAIT_AFTER_ERROR_MS, parseOptionalWaitDuration } from './waitOptions';
+
+/**
+ * Default port used by `ptbk coder server`.
+ *
+ * @private internal constant of `ptbk coder server`
+ */
+const DEFAULT_CODER_SERVER_PORT = '4441';
+
+/**
+ * Initializes `coder server` command for Promptbook CLI utilities.
+ *
+ * Runs the same prompt processing logic as `ptbk coder run` but keeps the process alive
+ * and serves a kanban web UI on the configured port.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI
+ *
+ * @private internal function of `promptbookCli`
+ */
+export function $initializeCoderServerCommand(program: Program): $side_effect {
+    const command = program.command('server');
+    command.description(
+        spaceTrim(`
+            Start a coder server that watches for prompts and serves a kanban web UI
+
+            ${PROMPT_RUNNER_DESCRIPTION}
+
+            Features:
+            - Runs the same prompt processing as \`ptbk coder run\`
+            - Does not exit when all prompts are done; polls for new prompt files instead
+            - Serves a kanban board at http://localhost:<port> for visual progress tracking
+            - Allows editing prompt files directly from the browser (Trello-style)
+            - Play / pause button in the browser stays in sync with the CLI pause state
+            - Press "p" in the terminal to pause / resume (same as \`ptbk coder run\`)
+        `),
+    );
+
+    command.addOption(
+        new Option('--port <port>', 'Port to start the coder server on')
+            .env('PTBK_CODER_SERVER_PORT')
+            .default(DEFAULT_CODER_SERVER_PORT),
+    );
+    command.option('--dry-run', 'Print unwritten prompts without executing', false);
+    addPromptRunnerSelectionOptions(command);
+    command.option(
+        '--agent <agent-book-path>',
+        'Path to a .book file whose compiled system message is prepended to each coding prompt',
+    );
+    command.option(
+        '--context <context-or-file>',
+        'Append extra instructions either inline or from a file path relative to the current project',
+    );
+    command.option(
+        '--test <test-command...>',
+        'Run a verification command after each prompt; quote it when the command itself contains top-level flags',
+    );
+    command.option(
+        '--preserve-logs',
+        'Keep generated temp prompt/log artifacts after successful rounds for debugging and analytics',
+        false,
+    );
+    addPromptRunnerExecutionOptions(command);
+    command.option('--priority <minimum-priority>', 'Filter prompts by minimum priority level', parseIntOption, 0);
+    command.option(
+        '--wait-after-prompt <duration>',
+        spaceTrim(`
+            Wait this long after each prompt has been implemented, verified and committed before starting the next prompt.
+            Accepts durations like 1h, 30m, 5s. Defaults to 0 (no wait).
+        `),
+    );
+    command.option(
+        '--wait-between-prompts <duration>',
+        spaceTrim(`
+            Pace prompts so that each next prompt starts at least this long after the previous one began.
+            If the previous prompt already took longer than this, the next prompt starts immediately.
+            Accepts durations like 1h, 30m, 5s. Defaults to 0 (no pacing).
+        `),
+    );
+    command.option(
+        '--wait-after-error <duration>',
+        spaceTrim(`
+            Wait this long before retrying a prompt after an error occurs (up to 3 retries before giving up).
+            Accepts durations like 1h, 30m, 5s. Defaults to 10m.
+        `),
+    );
+    command.option(
+        '--no-auto',
+        'Wait for user confirmation before each prompt instead of running automatically through the queue',
+    );
+    command.option(
+        '--auto-migrate',
+        'Run testing-server database migrations automatically after each successfully processed prompt',
+    );
+    command.option(
+        '--allow-destructive-auto-migrate',
+        'Allow auto-migrate even when heuristic SQL safety check flags destructive pending migrations',
+    );
+
+    command.action(
+        handleActionErrors(async (cliOptions) => {
+            const {
+                port: rawPort,
+                dryRun,
+                agent,
+                context,
+                test,
+                preserveLogs,
+                priority,
+                waitAfterPrompt: waitAfterPromptValue,
+                waitBetweenPrompts: waitBetweenPromptsValue,
+                waitAfterError: waitAfterErrorValue,
+                auto,
+                autoMigrate,
+                allowDestructiveAutoMigrate,
+            } = cliOptions as {
+                readonly port: string;
+                readonly dryRun: boolean;
+                readonly agent?: string;
+                readonly context?: string;
+                readonly test?: string | string[];
+                readonly preserveLogs: boolean;
+                readonly priority: number;
+                readonly waitAfterPrompt?: string;
+                readonly waitBetweenPrompts?: string;
+                readonly waitAfterError?: string;
+                readonly auto: boolean;
+                readonly autoMigrate: boolean;
+                readonly allowDestructiveAutoMigrate: boolean;
+            } & PromptRunnerCliOptions;
+
+            const port = parseCoderServerPort(rawPort);
+            const testCommand = normalizeCommandOptionValue(test);
+            const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
+                isAgentRequired: !dryRun,
+            });
+
+            // [1] Parse the wait options and --no-auto (same logic as `coder run`)
+            const waitForUser = !auto;
+            const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
+            const waitBetweenPrompts = parseOptionalWaitDuration(waitBetweenPromptsValue, 0);
+            const waitAfterError = parseOptionalWaitDuration(waitAfterErrorValue, DEFAULT_WAIT_AFTER_ERROR_MS);
+
+            const runOptions = {
+                port,
+                dryRun,
+                waitForUser,
+                waitAfterPrompt,
+                waitBetweenPrompts,
+                waitAfterError,
+                noCommit: runnerOptions.noCommit,
+                ignoreGitChanges: runnerOptions.ignoreGitChanges,
+                agentName: runnerOptions.agentName,
+                model: runnerOptions.model,
+                agent,
+                context,
+                testCommand,
+                preserveLogs,
+                noUi: runnerOptions.noUi,
+                thinkingLevel: runnerOptions.thinkingLevel,
+                priority,
+                normalizeLineEndings: runnerOptions.normalizeLineEndings,
+                allowCredits: runnerOptions.allowCredits,
+                autoMigrate,
+                allowDestructiveAutoMigrate,
+                autoPush: runnerOptions.autoPush,
+                autoPull: runnerOptions.autoPull,
+            };
+
+            // Note: Import dynamically to avoid loading heavy dependencies until needed
+            const { runCodexPromptsServer } = await import(
+                '../../../../scripts/run-codex-prompts/main/runCodexPromptsServer'
+            );
+
+            try {
+                await runCodexPromptsServer(runOptions);
+            } catch (error) {
+                assertsError(error);
+                console.error(colors.bgRed(`${error.name}`));
+                console.error(colors.red(error.stack || error.message));
+                return process.exit(1);
+            }
+
+            return process.exit(0);
+        }),
+    );
+}
+
+/**
+ * Parses and validates the coder server port number.
+ *
+ * @private internal utility of `coder server` command
+ */
+function parseCoderServerPort(rawPort: string): number_port {
+    const port = Number.parseInt(rawPort, 10);
+
+    if (!Number.isInteger(port) || port <= 0 || port > NETWORK_LIMITS.MAX_PORT) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid coder server port: \`${rawPort}\`.
+
+                Use \`--port\` or \`PTBK_CODER_SERVER_PORT\` with an integer between \`1\` and \`${NETWORK_LIMITS.MAX_PORT}\`.
+            `),
+        );
+    }
+
+    return port as number_port;
+}
+
+/**
+ * Parses an integer option value.
+ *
+ * @private internal utility of `coder server` command
+ */
+function parseIntOption(value: string): number {
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed)) {
+        throw new Error(`Invalid number: ${value}`);
+    }
+    return parsed;
+}
+
+/**
+ * Joins one Commander option that may be parsed either as a single string or a variadic token array.
+ *
+ * @private internal utility of `coder server` command
+ */
+function normalizeCommandOptionValue(value: string | string[] | undefined): string | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+
+    const parts = Array.isArray(value) ? value : [value];
+    const normalizedValue = parts
+        .map((part) => part.trim())
+        .filter(Boolean)
+        .join(' ')
+        .trim();
+    return normalizedValue === '' ? undefined : normalizedValue;
+}
+
+// Note: [🟡] Code for CLI command [server](src/cli/cli-commands/coder/server.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and entity name