@promptbook/cli 0.114.0-3 → 0.114.0-30

package/src/book-components/Chat/utils/timeoutToolCallPresentation.ts

@@ -2,12 +2,37 @@ import type { TODO_any } from '../../../utils/organization/TODO_any';
 import { formatToolCallDateTime } from './formatToolCallDateTime';
 import { formatToolCallTranslationTemplate } from './formatToolCallTranslationTemplate';
 
+/**
+ * Tool name of one scheduled wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export const SET_TIMEOUT_TOOL_CALL_NAME = 'set_timeout';
+
+/**
+ * Tool name of one re-planned wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export const UPDATE_TIMEOUT_TOOL_CALL_NAME = 'update_timeout';
+
+/**
+ * Tool name of one cancelled wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export const CANCEL_TIMEOUT_TOOL_CALL_NAME = 'cancel_timeout';
+
 /**
  * Tool names handled by timeout-specific chat presentation.
  *
  * @private internal timeout-chat constant
  */
-const TIMEOUT_TOOL_NAMES = ['set_timeout', 'cancel_timeout'] as const;
+const TIMEOUT_TOOL_NAMES = [
+    SET_TIMEOUT_TOOL_CALL_NAME,
+    UPDATE_TIMEOUT_TOOL_CALL_NAME,
+    CANCEL_TIMEOUT_TOOL_CALL_NAME,
+] as const;
 
 /**
  * Milliseconds in one second.
@@ -412,9 +437,15 @@ function formatTimeoutDurationCompact(milliseconds: number): string {
 /**
  * Converts timeout duration into natural language sentence fragments.
  *
- * @private internal timeout-chat helper
+ * Shared by every timeout surface: the chat chips, the goal-chat planned messages of the Agents
+ * Server, and the planned-message prompt section of the agent-folder runner.
+ *
+ * @param milliseconds - Duration or repeat interval in milliseconds.
+ * @returns Label such as `5 minutes` or `1 hour 30 minutes`.
+ *
+ * @private internal utility of `<Chat/>` and the Agents Server planned messages
  */
-function formatTimeoutDurationHuman(milliseconds: number): string {
+export function formatTimeoutDurationHuman(milliseconds: number): string {
     const normalizedMilliseconds = Math.max(0, Math.floor(milliseconds));
     const totalSeconds = Math.max(1, Math.floor(normalizedMilliseconds / SECOND_IN_MILLISECONDS));
 

package/src/cli/cli-commands/agents-server/startAgentsServer/createLocalAgentRunOptions.ts

@@ -17,7 +17,7 @@ export function createLocalAgentRunOptions(
         noUi: options.noUi,
         thinkingLevel: options.thinkingLevel,
         noCommit: true,
-        ignoreGitChanges: true,
+        gitChanges: 'ignore',
         normalizeLineEndings: false,
         allowCredits: options.allowCredits,
         autoPush: false,

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

@@ -0,0 +1,35 @@
+/**
+ * Supported values of the `--git-changes` option, which decides what happens with a dirty working tree.
+ *
+ * - `fail` — refuse to start while the working tree has uncommitted changes
+ * - `ignore` — start anyway and leave the uncommitted changes where they are
+ * - `continue` — resume the single prompt which was left in the middle of its implementation
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export const GIT_CHANGES_MODE_VALUES = ['fail', 'ignore', 'continue'] as const;
+
+/**
+ * Behavior requested for a working tree which has uncommitted changes.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export type GitChangesMode = (typeof GIT_CHANGES_MODE_VALUES)[number];
+
+/**
+ * Mode applied when `--git-changes` is not used at all.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export const DEFAULT_GIT_CHANGES_MODE: GitChangesMode = 'fail';
+
+/**
+ * Checks whether a value is a supported `--git-changes` mode.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export function isGitChangesMode(value: string): value is GitChangesMode {
+    return GIT_CHANGES_MODE_VALUES.includes(value as GitChangesMode);
+}
+
+// Note: [🟡] Code for CLI command [run](src/cli/cli-commands/coder/run.ts) should never be published outside of `@promptbook/cli`

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

@@ -102,11 +102,11 @@ export function $initializeCoderAddCommand(program: Program): $side_effect {
             const description = await resolveCoderPromptDescription(descriptionArgument);
 
             // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
-            const { $commitCoderChanges, $pullCoderChanges } = await import(
+            const { $commitCoderChanges, $startCoderGitSync } = await import(
                 '../../../../scripts/run-codex-prompts/git/coderGitSync'
             );
 
-            await $pullCoderChanges({ gitSync, projectPath });
+            const commitScope = await $startCoderGitSync({ gitSync, projectPath });
 
             const { /* filePath,*/ emojiTag } = await addCoderPrompt({
                 projectPath,
@@ -117,7 +117,7 @@ export function $initializeCoderAddCommand(program: Program): $side_effect {
 
             await $commitCoderChanges({
                 gitSync,
-                projectPath,
+                commitScope,
                 commitMessage: `${emojiTag} Add prompt`,
             });
         }),

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

@@ -0,0 +1,139 @@
+import { spaceTrim } from 'spacetrim';
+import { NotAllowed } from '../../../errors/NotAllowed';
+
+/**
+ * Separator between the number of generated files and the number of prompts in each of them,
+ * for example `10*7`.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+const BOILERPLATE_COUNT_SEPARATOR = '*';
+
+/**
+ * Pattern of the `--count` option value, either `N` or `N*M`.
+ */
+const BOILERPLATE_COUNT_PATTERN = /^(?<filesCount>\d+)(?:\s*\*\s*(?<promptsPerFileCount>\d+))?$/u;
+
+/**
+ * How many prompt boilerplate files are generated and how many prompts each of them contains.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export type BoilerplateCount = {
+    /**
+     * Number of generated prompt boilerplate files.
+     */
+    readonly filesCount: number;
+
+    /**
+     * Number of prompts written into each generated file.
+     *
+     * Note: More than one prompt per file is an advanced option - each prompt is one separate
+     *       coding task separated by `---`, with all prompts in the file sharing its fresh emoji tag.
+     */
+    readonly promptsPerFileCount: number;
+};
+
+/**
+ * Number of prompt boilerplate files and prompts per file used when `--count` is not provided.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export const DEFAULT_BOILERPLATE_COUNT: BoilerplateCount = {
+    filesCount: 5,
+    promptsPerFileCount: 1,
+};
+
+/**
+ * Formats one boilerplate count back into the `N*M` notation of the `--count` option.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export function formatBoilerplateCount({ filesCount, promptsPerFileCount }: BoilerplateCount): string {
+    return `${filesCount}${BOILERPLATE_COUNT_SEPARATOR}${promptsPerFileCount}`;
+}
+
+/**
+ * Default value of the `--count` option rendered in the `N*M` notation, for example `5*1`.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export const DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE = formatBoilerplateCount(DEFAULT_BOILERPLATE_COUNT);
+
+/**
+ * Description of the `--count` option shared by all commands which generate prompt boilerplates.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export const BOILERPLATE_COUNT_OPTION_DESCRIPTION = spaceTrim(`
+    Number of generated prompt boilerplate files, optionally with the number of prompts in each of them.
+
+    Use \`N\` (or \`N*1\`) for N files with one prompt each,
+    or the advanced \`N*M\` notation for N files with M prompts each, for example \`10*7\`.
+`);
+
+/**
+ * Parses the `--count` option value into the number of files and the number of prompts in each of them.
+ *
+ * Both notations are supported:
+ * - `N` and `N*1` => N files with one prompt each
+ * - `N*M` => N files with M prompts each
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export function parseBoilerplateCount(countOption: string): BoilerplateCount {
+    const normalizedCountOption = countOption.trim();
+    const match = BOILERPLATE_COUNT_PATTERN.exec(normalizedCountOption);
+
+    if (match === null) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid value for \`--count\`: \`${countOption}\`.
+
+                Use either \`N\` for N files with one prompt each,
+                or the advanced \`N*M\` notation for N files with M prompts each:
+
+                - \`--count 5\`
+                - \`--count 5*1\`
+                - \`--count 10*7\`
+            `),
+        );
+    }
+
+    const filesCount = Number(match.groups?.filesCount);
+    const promptsPerFileCount =
+        match.groups?.promptsPerFileCount === undefined
+            ? DEFAULT_BOILERPLATE_COUNT.promptsPerFileCount
+            : Number(match.groups.promptsPerFileCount);
+
+    assertsPositiveBoilerplateCountPart(filesCount, countOption, 'number of generated files');
+    assertsPositiveBoilerplateCountPart(promptsPerFileCount, countOption, 'number of prompts in each file');
+
+    return { filesCount, promptsPerFileCount };
+}
+
+/**
+ * Asserts that one part of the `--count` option value is a positive integer.
+ *
+ * @private internal utility of `parseBoilerplateCount`
+ */
+function assertsPositiveBoilerplateCountPart(
+    countPart: number,
+    countOption: string,
+    countPartDescription: string,
+): void {
+    if (Number.isInteger(countPart) && countPart > 0) {
+        return;
+    }
+
+    throw new NotAllowed(
+        spaceTrim(`
+            Invalid value for \`--count\`: \`${countOption}\`.
+
+            The ${countPartDescription} must be **a positive integer**, for example \`--count 10*7\`.
+        `),
+    );
+}
+
+// Note: [🟡] Code for coder boilerplate count [boilerplateCount](src/cli/cli-commands/coder/boilerplateCount.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and exported helper names

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

@@ -124,24 +124,12 @@ const DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS = [
             -   @@@
             -   Keep in mind the DRY _(don't repeat yourself)_ principle.
             -   Do a proper analysis of the current functionality before you start implementing.
-            -   Add the changes into the [changelog](changelog/_current-preversion.md)
+            -   Add the changes into the [changelog](CHANGELOG.md)
+            -   Update the [README](README.md) if needed.
+            -   Update the [AGENTS.md](AGENTS.md) for the next job to be done if it makes sense.
         `),
         isDefaultProjectTemplate: true,
     },
-    {
-        id: 'agents-server',
-        relativeFilePath: join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'agents-server.md'),
-        slugPrefix: 'agents-server',
-        content: spaceTrim(`
-            -   @@@
-            -   Keep in mind the DRY _(don't repeat yourself)_ principle.
-            -   Do a proper analysis of the current functionality before you start implementing.
-            -   You are working with the [Agents Server](apps/agents-server)
-            -   If you need to do the database migration, do it
-            -   Add the changes into the [changelog](changelog/_current-preversion.md)
-        `),
-        isDefaultProjectTemplate: false,
-    },
 ] as const satisfies ReadonlyArray<CoderPromptTemplateDefinition>;
 
 /**

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

@@ -13,6 +13,13 @@ import {
     normalizeCoderGitSyncCliOptions,
 } from '../common/coderGitSyncCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
+import type { BoilerplateCount } from './boilerplateCount';
+import {
+    BOILERPLATE_COUNT_OPTION_DESCRIPTION,
+    DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE,
+    formatBoilerplateCount,
+    parseBoilerplateCount,
+} from './boilerplateCount';
 import {
     buildCoderPromptSection,
     getDefaultCoderPromptTemplateDefinitions,
@@ -32,14 +39,14 @@ export function $initializeCoderGenerateBoilerplatesCommand(program: Program): $
     command.description(
         spaceTrim(
             (block) => `
-                Generate prompt boilerplate files with unique emoji tags
+                Generate prompt boilerplate files with one unique emoji tag per file
 
                 ${block(CODER_GIT_SYNC_DESCRIPTION)}
             `,
         ),
     );
 
-    command.option('--count <count>', `Number of prompt boilerplate files to generate`, '5');
+    command.option('--count <count>', BOILERPLATE_COUNT_OPTION_DESCRIPTION, DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE);
     command.option(
         '--template <template>',
         spaceTrim(`
@@ -59,27 +66,27 @@ export function $initializeCoderGenerateBoilerplatesCommand(program: Program): $
                 readonly template?: string;
             } & CoderGitSyncCliOptions;
 
-            const filesCount = parseFilesCount(countOption);
+            const boilerplateCount = parseBoilerplateCount(countOption);
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
             const projectPath = process.cwd();
 
             // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
-            const { $commitCoderChanges, $pullCoderChanges } = await import(
+            const { $commitCoderChanges, $startCoderGitSync } = await import(
                 '../../../../scripts/run-codex-prompts/git/coderGitSync'
             );
 
-            await $pullCoderChanges({ gitSync, projectPath });
+            const commitScope = await $startCoderGitSync({ gitSync, projectPath });
 
             await generatePromptBoilerplate({
                 projectPath,
-                filesCount,
+                boilerplateCount,
                 templateOption,
             });
 
             await $commitCoderChanges({
                 gitSync,
-                projectPath,
-                commitMessage: `Prompts ${filesCount}x`,
+                commitScope,
+                commitMessage: `Prompts ${formatBoilerplateCount(boilerplateCount)}`,
             });
 
             return process.exit(0);
@@ -88,19 +95,21 @@ export function $initializeCoderGenerateBoilerplatesCommand(program: Program): $
 }
 
 /**
- * Generates boilerplate prompt files with unique emoji tags.
+ * Generates boilerplate prompt files with one unique emoji tag per file.
  *
  * @private internal function of `generatePromptBoilerplate` command
  */
 export async function generatePromptBoilerplate({
     projectPath,
-    filesCount,
+    boilerplateCount,
     templateOption,
 }: {
     readonly projectPath: string;
-    readonly filesCount: number;
+    readonly boilerplateCount: BoilerplateCount;
     readonly templateOption?: string;
 }): Promise<void> {
+    const { filesCount, promptsPerFileCount } = boilerplateCount;
+
     // Note: Import these dynamically to avoid circular dependencies and keep CLI fast
     const { buildPromptFilename, getPromptNumbering } = await import(
         '../../../../scripts/utils/prompts/getPromptNumbering'
@@ -125,7 +134,9 @@ export async function generatePromptBoilerplate({
         colors.blue(`Highest existing number for ${promptNumbering.datePrefix} found: ${highestNumberFormatted}`),
     );
 
+    const promptsCount = filesCount * promptsPerFileCount;
     const { availableCount, selectedEmojis } = await getFreshPromptEmojiTags({
+        // Note: Each generated file reserves one fresh emoji tag shared by all of its prompt sections
         count: filesCount,
         rootDir: projectPath,
     });
@@ -143,7 +154,7 @@ export async function generatePromptBoilerplate({
     for (let i = 0; i < filesCount; i++) {
         const number = promptNumbering.startNumber + i * promptNumbering.step;
         const title = titles[i % titles.length]!;
-        const emoji = selectedEmojis[i]!;
+        const emojiTag = formatPromptEmojiTag(selectedEmojis[i]!);
         const filename = buildPromptFilename(
             promptNumbering.datePrefix,
             number,
@@ -151,39 +162,19 @@ export async function generatePromptBoilerplate({
         );
         const filepath = join(PROMPTS_DIRECTORY_PATH, filename);
         const absoluteFilepath = join(projectPath, filepath);
-        const emojiTag = formatPromptEmojiTag(emoji);
-        const one = buildCoderPromptSection({
-            statusLine: '[-]',
+        const content = buildBoilerplatePromptFileContent({
             emojiTag,
+            promptsPerFileCount,
             title,
             body: promptTemplate.content,
         });
-        const content = spaceTrim(
-            (block) => `
-
-                ${block(one)}
-
-                ---
-
-                ${block(one)}
-
-                ---
-
-                ${block(one)}
-
-                ---
-
-                ${block(one)}
-
-            `,
-        );
 
         filesToCreate.push({
             filepath,
             absoluteFilepath,
             filename,
             content,
-            emoji,
+            emojiTag,
             number,
         });
     }
@@ -193,26 +184,43 @@ export async function generatePromptBoilerplate({
 
     for (const file of filesToCreate) {
         writeFileSync(file.absoluteFilepath, file.content, 'utf-8');
-        console.info(colors.green(`✓ Created: ${file.filename} with ${formatPromptEmojiTag(file.emoji!)}`));
+        console.info(colors.green(`✓ Created: ${file.filename} with ${file.emojiTag}`));
     }
 
-    console.info(colors.bgGreen(` Successfully created ${filesToCreate.length} prompt boilerplate files! `));
+    console.info(
+        colors.bgGreen(
+            ` Successfully created ${promptsCount} prompts in ${filesToCreate.length} prompt boilerplate files! `,
+        ),
+    );
 }
 
 /**
- * Parses and validates the count of boilerplate files to create.
+ * Builds the markdown content of one generated prompt file with one prompt section per prompt.
+ *
+ * Multiple prompts in one file share the file emoji tag and are separated by the `---` separator,
+ * exactly like the prompt runner expects them.
  *
  * @private internal utility of `generatePromptBoilerplate` command
  */
-function parseFilesCount(countOption: string): number {
-    const filesCount = Number(countOption);
-
-    if (!Number.isFinite(filesCount) || filesCount <= 0) {
-        console.info(colors.yellow(`Invalid --count '${countOption}'. Falling back to default 5.`));
-        return 5;
-    }
-
-    return Math.floor(filesCount);
+function buildBoilerplatePromptFileContent({
+    emojiTag,
+    promptsPerFileCount,
+    title,
+    body,
+}: {
+    readonly emojiTag: string;
+    readonly promptsPerFileCount: number;
+    readonly title: string;
+    readonly body: string;
+}): string {
+    return Array.from({ length: promptsPerFileCount }, () =>
+        buildCoderPromptSection({
+            statusLine: '[-]',
+            emojiTag,
+            title,
+            body,
+        }),
+    ).join('\n\n---\n\n');
 }
 
 /**

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

@@ -1,13 +1,16 @@
+import { DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE } from './boilerplateCount';
+
 /**
  * Default npm scripts initialized by `ptbk coder init`.
  */
 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',
+    // Note: Using NPX because `ptbk` can be installed globally or locally, and NPX will resolve it correctly in either case.
+    'coder:generate-boilerplates': `npx ptbk coder generate-boilerplates --count ${DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE} --template ./prompts/templates/common.md`,
+    'coder:add': 'npx ptbk coder add --template ./prompts/templates/common.md',
     'coder:run':
-        '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',
+        'npx 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',
+    'coder:verify': 'npx ptbk coder verify',
 } as const satisfies Readonly<Record<string, string>>;
 
 /**

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

@@ -12,9 +12,15 @@ import {
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import { getHarnessDefinition } from '../common/harness/HarnessDefinition';
+import {
+    addHarnessUpdateOption,
+    normalizeHarnessUpdateCliOptions,
+    type HarnessUpdateCliOptions,
+} from '../common/harnessUpdateCliOptions';
 import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
 import { AGENT_CODING_FILE_PATH } from './agentCodingFile';
 import { AGENTS_FILE_PATH } from './agentsFile';
+import { DEFAULT_BOILERPLATE_COUNT } from './boilerplateCount';
 import { getDefaultCoderProjectPromptTemplateDefinitions } from './boilerplateTemplates';
 import { CODER_DEVELOPER_AGENT_FILE_PATH } from './ensureCoderDeveloperAgentFile';
 import { formatDisplayPath } from './formatDisplayPath';
@@ -65,7 +71,7 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
                 - CODING_AGENT_GIT_EMAIL
                 - CODING_AGENT_GIT_SIGNING_KEY
 
-                Checks that the coding harnesses are installed globally and up to date:
+                Checks that the coding harnesses are installed and up to date unless \`--no-harness-update\` is used:
                 ${block(listCheckedHarnessLabels())}
 
                 ${block(CODER_GIT_SYNC_DESCRIPTION)}
@@ -74,30 +80,34 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
     );
 
     addCoderGitSyncOptions(command);
+    addHarnessUpdateOption(command);
 
     command.action(
         handleActionErrors(async (cliOptions) => {
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
+            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
+                cliOptions as HarnessUpdateCliOptions,
+            );
             const projectPath = process.cwd();
 
             // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
-            const { $commitCoderChanges, $pullCoderChanges } = await import(
+            const { $commitCoderChanges, $startCoderGitSync } = await import(
                 '../../../../scripts/run-codex-prompts/git/coderGitSync'
             );
 
-            await $pullCoderChanges({ gitSync, projectPath });
+            const commitScope = await $startCoderGitSync({ gitSync, projectPath });
 
             const summary = await initializeCoderProjectConfiguration(projectPath);
             printInitializationSummary(summary);
-            await generatePromptBoilerplate({ projectPath, filesCount: 5 });
+            await generatePromptBoilerplate({ projectPath, boilerplateCount: DEFAULT_BOILERPLATE_COUNT });
 
             await $commitCoderChanges({
                 gitSync,
-                projectPath,
+                commitScope,
                 commitMessage: 'Initialize Promptbook Coder',
             });
 
-            await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES);
+            await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES, isHarnessUpdateCheckEnabled);
         }),
     );
 }