@promptbook/cli 0.114.0-0 → 0.114.0-2

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

@@ -1,13 +1,5 @@
 import { spaceTrim } from 'spacetrim';
-import { AGENTS_FILE_PATH } from './agentsFile';
-import {
-    getDefaultCoderProjectPromptTemplateDefinitions,
-    getDefaultCoderPromptTemplateDefinitions,
-    PROMPTS_DIRECTORY_PATH,
-    PROMPTS_DONE_DIRECTORY_PATH,
-    PROMPTS_TEMPLATES_DIRECTORY_PATH,
-} from './boilerplateTemplates';
-import { formatDisplayPath } from './formatDisplayPath';
+import { string_markdown } from '../../../types/typeAliases';
 
 /**
  * Relative path to the Promptbook Coder quick-reference file initialized in project roots.
@@ -21,127 +13,12 @@ export const AGENT_CODING_FILE_PATH = 'AGENT_CODING.md';
  *
  * @private internal utility of `ptbk coder`
  */
-export function getDefaultCoderAgentCodingFileContent({
-    packageJsonScripts,
-}: {
-    readonly packageJsonScripts: Readonly<Record<string, string>>;
-}): string {
-    return spaceTrim(
-        (block) => `
-            # Promptbook Coder quick reference
+export function getDefaultCoderAgentCodingFileContent(): string_markdown {
+    return spaceTrim(`
+        # ✨ Promptbook Coder agent coding
 
-            This project is prepared for the \`ptbk coder\` workflow. Promptbook Coder does not create a new model on its own; it orchestrates coding agents such as GitHub Copilot, OpenAI Codex, Claude Code, Opencode, Cline, and Gemini CLI through prompt files in \`${formatDisplayPath(
-                PROMPTS_DIRECTORY_PATH,
-            )}/\`.
-
-            ## Workflow
-            1. Put repository-wide coding rules into \`${AGENTS_FILE_PATH}\`. The default \`npm run coder:run\` script already passes \`--context ${AGENTS_FILE_PATH}\`.
-            2. Create or customize prompt templates in \`${formatDisplayPath(
-                PROMPTS_TEMPLATES_DIRECTORY_PATH,
-            )}/\`. ${buildStarterTemplateSentence()}
-            3. Generate prompt files with \`npm run coder:generate-boilerplates\` or \`ptbk coder generate-boilerplates --template <template> --count <count>\`. To append a single ready-to-run prompt straight from a description, use \`npm run coder:add\` or \`ptbk coder add "some new feature"\`.
-            4. Replace every \`@@@\`, keep drafts as \`[-]\`, and switch prompts to \`[ ]\` when they are ready to run. Completed prompts are marked \`[x]\`.
-            5. Run \`npm run coder:run\` to execute the next ready prompt with the configured coding agent.
-            6. Use \`npm run coder:verify\` to archive finished prompts into \`${formatDisplayPath(
-                PROMPTS_DONE_DIRECTORY_PATH,
-            )}/\` and append repair follow-up prompts when more work is needed.
-            7. Use \`ptbk coder find-refactor-candidates\` when you want Promptbook to suggest refactor prompts automatically.
-
-            ## Templates
-            -   Project-owned templates created by \`ptbk coder init\`: ${formatInlineCodeList(
-                getDefaultCoderProjectPromptTemplateDefinitions().map(({ relativeFilePath }) =>
-                    formatDisplayPath(relativeFilePath),
-                ),
-            )}
-            -   Built-in \`--template\` aliases: ${formatInlineCodeList(
-                getDefaultCoderPromptTemplateDefinitions().map(({ id }) => id),
-            )}
-            -   To add a custom template, create a markdown file such as \`${formatDisplayPath(
-                PROMPTS_TEMPLATES_DIRECTORY_PATH,
-            )}/backend.md\`.
-            -   To use a project template, run \`ptbk coder generate-boilerplates --template ${formatDisplayPath(
-                PROMPTS_TEMPLATES_DIRECTORY_PATH,
-            )}/backend.md\`.
-            -   Keep shared repository rules in \`${AGENTS_FILE_PATH}\` and recurring task-family rules in template files so individual prompt files stay focused on the actual task.
-
-            ## Created npm scripts
-            | Script | Purpose |
-            | --- | --- |
-            ${block(buildPackageJsonScriptTableLines(packageJsonScripts).join('\n'))}
-
-            ## Customizing the workflow
-            -   Edit \`package.json\` if you want \`npm run coder:run\` to use another coding agent, model, thinking level, context file, or wait mode.
-            -   Use direct CLI commands when you need one-off flags such as \`--min-priority\`, \`--max-priority\`, \`--ignore-git-changes\`, \`--no-commit\`, \`--dry-run\`, \`--test\`, \`--allow-credits\`, or \`--auto-migrate\`.
-            -   Use \`ptbk coder --help\` and \`ptbk coder <command> --help\` for the full CLI reference.
-        `,
-    );
-}
-
-/**
- * Builds the sentence describing the starter templates created during initialization.
- */
-function buildStarterTemplateSentence(): string {
-    const starterTemplatePaths = getDefaultCoderProjectPromptTemplateDefinitions().map(({ relativeFilePath }) =>
-        formatDisplayPath(relativeFilePath),
-    );
-
-    if (starterTemplatePaths.length === 1) {
-        return `The starter project template created by \`ptbk coder init\` is \`${starterTemplatePaths[0]}\`.`;
-    }
-
-    return `The starter project templates created by \`ptbk coder init\` are ${formatInlineCodeList(
-        starterTemplatePaths,
-    )}.`;
-}
-
-/**
- * Builds the markdown table rows describing the initialized npm scripts.
- */
-function buildPackageJsonScriptTableLines(packageJsonScripts: Readonly<Record<string, string>>): Array<string> {
-    return Object.entries(packageJsonScripts).map(
-        ([scriptName, scriptCommand]) =>
-            `| \`npm run ${scriptName}\` | ${describeDefaultCoderPackageJsonScript(scriptName, scriptCommand)} |`,
-    );
-}
-
-/**
- * Describes one initialized npm script in human-readable terms.
- */
-function describeDefaultCoderPackageJsonScript(scriptName: string, scriptCommand: string): string {
-    if (scriptName === 'coder:generate-boilerplates') {
-        return `Runs \`${scriptCommand}\` to create new prompt files in \`${formatDisplayPath(
-            PROMPTS_DIRECTORY_PATH,
-        )}/\`.`;
-    }
-
-    if (scriptName === 'coder:add') {
-        return `Runs \`${scriptCommand}\` to add one ready-to-run prompt file to \`${formatDisplayPath(
-            PROMPTS_DIRECTORY_PATH,
-        )}/\` from a plain-language description.`;
-    }
-
-    if (scriptName === 'coder:run') {
-        return `Runs \`${scriptCommand}\` to execute the next ready prompt with shared repository context from \`${AGENTS_FILE_PATH}\`.`;
-    }
-
-    if (scriptName === 'coder:find-refactor-candidates') {
-        return `Runs \`${scriptCommand}\` to generate prompt candidates for large or crowded files.`;
-    }
-
-    if (scriptName === 'coder:verify') {
-        return `Runs \`${scriptCommand}\` to archive verified prompts into \`${formatDisplayPath(
-            PROMPTS_DONE_DIRECTORY_PATH,
-        )}/\` and append repair prompts when needed.`;
-    }
-
-    return `Runs \`${scriptCommand}\`.`;
-}
-
-/**
- * Formats one inline code list for human-readable markdown.
- */
-function formatInlineCodeList(values: ReadonlyArray<string>): string {
-    return values.map((value) => `\`${value}\``).join(', ');
+        This project is using [Promptbook Coder](https://coder.ptbk.io) or run \`ptbk coder\`!
+    `);
 }
 
 // Note: [🟡] Code for coder AGENT_CODING file boilerplate [agentCodingFile](src/cli/cli-commands/coder/agentCodingFile.ts) should never be published outside of `@promptbook/cli`

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

@@ -5,7 +5,7 @@ const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
     'coder:generate-boilerplates': 'ptbk coder generate-boilerplates --template ./prompts/templates/common.md',
     'coder:add': 'ptbk coder add --template ./prompts/templates/common.md',
     'coder:run':
-        'ptbk coder run --harness openai-codex --model gpt-5.5 --thinking-level xhigh --agent agents/developer.book --context AGENTS.md',
+        'ptbk coder run --harness openai-codex --model gpt-5.6-terra --thinking-level max --agent agents/developer.book --context AGENTS.md --test-before yes-and-fix',
     // 'coder:find-refactor-candidates': 'npx ptbk coder find-refactor-candidates',
     'coder:verify': 'ptbk coder verify',
 } as const satisfies Readonly<Record<string, string>>;

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

@@ -14,7 +14,6 @@ import { ensureCoderMarkdownFile } from './ensureCoderMarkdownFile';
 import { ensureCoderPackageJsonFile } from './ensureCoderPackageJsonFile';
 import { ensureCoderVscodeSettingsFile } from './ensureCoderVscodeSettingsFile';
 import { ensureDirectory } from './ensureDirectory';
-import { getDefaultCoderPackageJsonScripts } from './getDefaultCoderPackageJsonScripts';
 
 /**
  * Result summary returned after coder configuration initialization.
@@ -57,9 +56,7 @@ export async function initializeCoderProjectConfiguration(projectPath: string):
     const agentCodingFileStatus = await ensureCoderMarkdownFile(
         projectPath,
         AGENT_CODING_FILE_PATH,
-        getDefaultCoderAgentCodingFileContent({
-            packageJsonScripts: getDefaultCoderPackageJsonScripts(),
-        }),
+        getDefaultCoderAgentCodingFileContent(),
     );
     const { envFileStatus, initializedEnvVariableNames } = await ensureCoderEnvFile(projectPath);
     const gitignoreFileStatus = await ensureCoderGitignoreFile(projectPath);

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

@@ -0,0 +1,94 @@
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+import { spaceTrim } from 'spacetrim';
+import { NotAllowed } from '../../../errors/NotAllowed';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
+import { handleActionErrors } from '../common/handleActionErrors';
+import type { PromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
+import {
+    addPromptRunnerRuntimeOptions,
+    addPromptRunnerSelectionOptions,
+    normalizePromptRunnerSelectionCliOptions,
+    PROMPT_RUNNER_DESCRIPTION,
+} from '../common/promptRunnerCliOptions';
+
+/**
+ * Initializes `coder ping` command for Promptbook CLI utilities.
+ *
+ * The command makes one small, isolated harness/model call, prints its result
+ * and reports how long the harness/model turn took.
+ *
+ * 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 $initializeCoderPingCommand(program: Program): $side_effect {
+    const command = program.command('ping');
+    command.description(
+        spaceTrim(`
+            Test one harness and model connection with a small disposable task
+
+            ${PROMPT_RUNNER_DESCRIPTION}
+
+            Features:
+            - Runs the dummy task in a temporary directory outside the current project
+            - Prints the result returned by the selected harness and model
+            - Reports the elapsed harness/model response time in milliseconds
+            - Can be used to start consuming an applicable harness/model quota before a longer run
+        `),
+    );
+
+    addPromptRunnerSelectionOptions(command);
+    addPromptRunnerRuntimeOptions(command);
+
+    command.action(
+        handleActionErrors(async (cliOptions) => {
+            const normalizedOptions = normalizePromptRunnerSelectionCliOptions(
+                cliOptions as PromptRunnerSelectionCliOptions,
+                { isAgentRequired: true },
+            );
+
+            const agentName = normalizedOptions.agentName;
+            if (!agentName) {
+                throw new NotAllowed(
+                    spaceTrim(`
+                        A harness is required for \`ptbk coder ping\`.
+
+                        Pass one with \`--harness <harness-name>\`.
+                    `),
+                );
+            }
+
+            await $ensureHarnessInstallations([agentName]);
+
+            // Note: Import the runner-backed implementation dynamically to avoid loading heavy dependencies until needed.
+            const { runCoderPing } = await import('../../../../scripts/run-agent-chat/runCoderPing');
+            const pingResult = await runCoderPing({
+                agentName,
+                model: normalizedOptions.model,
+                thinkingLevel: normalizedOptions.thinkingLevel,
+                isUiDisabled: normalizedOptions.noUi,
+                isCreditsAllowed: normalizedOptions.allowCredits,
+            });
+
+            printCoderPingResult(pingResult);
+        }),
+    );
+}
+
+/**
+ * Prints the result and duration of one completed coder ping.
+ */
+function printCoderPingResult(pingResult: { readonly result: string; readonly elapsedTimeMs: number }): void {
+    console.info(
+        spaceTrim(`
+            Result: ${pingResult.result}
+            Time: ${pingResult.elapsedTimeMs.toFixed(0)} ms
+        `),
+    );
+}
+
+// Note: [🟡] Code for CLI command [ping](src/cli/cli-commands/coder/ping.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/run.ts

@@ -1,5 +1,8 @@
 import colors from 'colors';
-import { Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */ } from 'commander';
+import {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+    Option,
+} from 'commander';
 import { spaceTrim } from 'spacetrim';
 import { assertsError } from '../../../errors/assertsError';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
@@ -14,6 +17,11 @@ import {
     normalizePromptRunnerCliOptions,
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
+import {
+    DEFAULT_CODER_TEST_COMMAND,
+    TEST_BEFORE_MODE_VALUES,
+    type TestBeforeMode,
+} from '../../../../scripts/run-codex-prompts/testing/TestBeforeMode';
 import { DEFAULT_WAIT_AFTER_ERROR_MS, parseOptionalWaitDuration } from './waitOptions';
 
 /**
@@ -40,6 +48,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             - Optional --no-ui keeps plain streaming console output for logging and debugging
             - Checks that the selected harness is installed globally and up to date before the first prompt
             - Supports GPG signing of commits
+            - Optional pre-coding test run that can stop or repair pre-existing failures
             - Optional post-prompt verification with test-feedback retries
             - Progress tracking and interactive P/S/X terminal controls
             - Dry-run mode to preview prompts
@@ -60,6 +69,16 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
         '--test <test-command...>',
         'Run a verification command after each prompt; quote it when the command itself contains top-level flags',
     );
+    command.addOption(
+        new Option(
+            '--test-before <mode>',
+            `Run tests before coding: ${TEST_BEFORE_MODE_VALUES.join(
+                ', ',
+            )} (defaults to no; uses npm test when --test is omitted)`,
+        )
+            .choices([...TEST_BEFORE_MODE_VALUES])
+            .default('no'),
+    );
     command.option(
         '--preserve-logs',
         'Keep generated temp prompt/log artifacts after successful rounds for debugging and analytics',
@@ -138,6 +157,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 agent,
                 context,
                 test,
+                testBefore,
                 preserveLogs,
                 isolate: isIsolated,
                 priority,
@@ -155,6 +175,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 readonly agent?: string;
                 readonly context?: string;
                 readonly test?: string | string[];
+                readonly testBefore: TestBeforeMode;
                 readonly preserveLogs: boolean;
                 readonly isolate: boolean;
                 readonly priority?: number;
@@ -169,7 +190,8 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 readonly allowDestructiveAutoMigrate: boolean;
             } & PromptRunnerCliOptions;
 
-            const testCommand = normalizeCommandOptionValue(test);
+            const configuredTestCommand = normalizeCommandOptionValue(test);
+            const testCommand = configuredTestCommand ?? (testBefore === 'no' ? undefined : DEFAULT_CODER_TEST_COMMAND);
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
                 isAgentRequired: !dryRun,
             });
@@ -201,6 +223,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 agent,
                 context,
                 testCommand,
+                testBefore,
                 preserveLogs,
                 isIsolated,
                 noUi: runnerOptions.noUi,

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

@@ -10,6 +10,7 @@ import { $initializeCoderFindRefactorCandidatesCommand } from './coder/find-refa
 import { $initializeCoderFindUnwrittenCommand } from './coder/find-unwritten';
 import { $initializeCoderGenerateBoilerplatesCommand } from './coder/generate-boilerplates';
 import { $initializeCoderInitCommand } from './coder/init';
+import { $initializeCoderPingCommand } from './coder/ping';
 import { $initializeCoderRunCommand } from './coder/run';
 import { $initializeCoderServerCommand } from './coder/server';
 import { $initializeCoderVerifyCommand } from './coder/verify';
@@ -22,6 +23,7 @@ import { $initializeCoderVerifyCommand } from './coder/verify';
  * - add: Add one ready-to-run prompt file to the queue
  * - generate-boilerplates: Generate prompt boilerplate files
  * - find-refactor-candidates: Find files that need refactoring
+ * - ping: Test one harness and model connection with a disposable task
  * - run: Run coding prompts with AI agents
  * - verify: Verify completed prompts
  * - find-fresh-emoji-tags: Find unused emoji tags
@@ -42,6 +44,7 @@ export function $initializeCoderCommand(program: Program): $side_effect {
             - generate-boilerplates: Generate prompt boilerplate files
             - find-refactor-candidates: Find files that need refactoring
             - find-unwritten: List prompt sections that still need to be authored
+            - ping: Test one harness and model connection with a disposable task
             - run: Run coding prompts with AI agents
             - server: Start a long-running coder server with a kanban web UI
             - verify: Verify completed prompts
@@ -55,6 +58,7 @@ export function $initializeCoderCommand(program: Program): $side_effect {
     $initializeCoderGenerateBoilerplatesCommand(coderCommand);
     $initializeCoderFindRefactorCandidatesCommand(coderCommand);
     $initializeCoderFindUnwrittenCommand(coderCommand);
+    $initializeCoderPingCommand(coderCommand);
     $initializeCoderRunCommand(coderCommand);
     $initializeCoderServerCommand(coderCommand);
     $initializeCoderVerifyCommand(coderCommand);