@promptbook/cli 0.114.0-2 → 0.114.0-21

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

@@ -3,12 +3,24 @@ import type {
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import type { CoderGitSyncCliOptions } from '../common/coderGitSyncCliOptions';
+import {
+    addCoderGitSyncOptions,
+    CODER_GIT_SYNC_DESCRIPTION,
+    normalizeCoderGitSyncCliOptions,
+} from '../common/coderGitSyncCliOptions';
 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';
@@ -59,19 +71,43 @@ 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 globally and up to date unless \`--no-harness-update\` is used:
                 ${block(listCheckedHarnessLabels())}
+
+                ${block(CODER_GIT_SYNC_DESCRIPTION)}
             `,
         ),
     );
 
+    addCoderGitSyncOptions(command);
+    addHarnessUpdateOption(command);
+
     command.action(
-        handleActionErrors(async () => {
+        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, $startCoderGitSync } = await import(
+                '../../../../scripts/run-codex-prompts/git/coderGitSync'
+            );
+
+            const commitScope = await $startCoderGitSync({ gitSync, projectPath });
+
             const summary = await initializeCoderProjectConfiguration(projectPath);
             printInitializationSummary(summary);
-            await generatePromptBoilerplate({ projectPath, filesCount: 5 });
-            await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES);
+            await generatePromptBoilerplate({ projectPath, boilerplateCount: DEFAULT_BOILERPLATE_COUNT });
+
+            await $commitCoderChanges({
+                gitSync,
+                commitScope,
+                commitMessage: 'Initialize Promptbook Coder',
+            });
+
+            await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES, isHarnessUpdateCheckEnabled);
         }),
     );
 }

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

@@ -2,10 +2,14 @@ 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 { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
+import {
+    addHarnessUpdateOption,
+    normalizeHarnessUpdateCliOptions,
+    type HarnessUpdateCliOptions,
+} from '../common/harnessUpdateCliOptions';
 import type { PromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerRuntimeOptions,
@@ -13,14 +17,12 @@ import {
     normalizePromptRunnerSelectionCliOptions,
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
+import { parseOptionalPeriodDuration } from './waitOptions';
 
 /**
- * Initializes `coder ping` command for Promptbook CLI utilities.
+ * 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.
+ * 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`
  */
@@ -28,67 +30,79 @@ 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
+            Send one tiny dummy prompt to a harness and model to measure and warm them up
 
             ${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
+            - Verifies that the selected harness, model, thinking level and authentication really work
+            - Reports the answer of the harness, the response time and the reported usage
+            - Starts the hourly/weekly quota window before you need it, so it is already refreshing when you do
+            - Optional --period keeps the quota window refreshing by pinging once per period until stopped
+            - Leaves the project exactly as it was — nothing is read, written, changed or committed
+            - Checks that the selected harness is installed globally and up to date unless --no-harness-update is used
+            - Use --no-ui to stream the raw harness output instead of only the compact result
         `),
     );
 
     addPromptRunnerSelectionOptions(command);
+    addHarnessUpdateOption(command);
     addPromptRunnerRuntimeOptions(command);
+    command.option(
+        '--period <duration>',
+        spaceTrim(`
+            Keep pinging once per period instead of pinging only once.
+            Accepts durations like 5h, 30m, 1h30m and repeats until it is stopped with CTRL+C.
+        `),
+    );
 
     command.action(
         handleActionErrors(async (cliOptions) => {
-            const normalizedOptions = normalizePromptRunnerSelectionCliOptions(
+            const { period: periodValue } = cliOptions as {
+                readonly period?: string;
+            } & PromptRunnerSelectionCliOptions;
+
+            const runnerOptions = normalizePromptRunnerSelectionCliOptions(
                 cliOptions as PromptRunnerSelectionCliOptions,
                 { isAgentRequired: true },
             );
+            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
+                cliOptions as HarnessUpdateCliOptions,
+            );
+
+            // Note: The period is validated before the harness installation check, so a mistyped duration fails fast
+            const periodMs = parseOptionalPeriodDuration('--period', periodValue);
+
+            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
 
-            const agentName = normalizedOptions.agentName;
-            if (!agentName) {
-                throw new NotAllowed(
-                    spaceTrim(`
-                        A harness is required for \`ptbk coder ping\`.
+            const pingOptions = {
+                agentName: runnerOptions.agentName,
+                model: runnerOptions.model,
+                thinkingLevel: runnerOptions.thinkingLevel,
+                allowCredits: runnerOptions.allowCredits,
+                shouldPrintLiveOutput: runnerOptions.noUi,
+            };
 
-                        Pass one with \`--harness <harness-name>\`.
-                    `),
+            // Note: Import the ping dynamically to avoid loading heavy dependencies until needed
+            if (periodMs !== undefined) {
+                const { pingCoderHarnessPeriodically } = await import(
+                    '../../../../scripts/run-codex-prompts/ping/pingCoderHarnessPeriodically'
                 );
-            }
 
-            await $ensureHarnessInstallations([agentName]);
+                // Note: This never returns - it keeps pinging until the user stops the process
+                await pingCoderHarnessPeriodically({ ...pingOptions, periodMs });
+                return;
+            }
 
-            // 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,
-            });
+            const { pingCoderHarness } = await import('../../../../scripts/run-codex-prompts/ping/pingCoderHarness');
+            const { printCoderPingResult } = await import(
+                '../../../../scripts/run-codex-prompts/ping/printCoderPingResult'
+            );
 
-            printCoderPingResult(pingResult);
+            printCoderPingResult(await pingCoderHarness(pingOptions));
         }),
     );
 }
 
-/**
- * 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

@@ -10,6 +10,12 @@ import { createNonNegativeIntegerOptionParser } from '../common/createNonNegativ
 import { createPositiveIntegerOptionParser } from '../common/createPositiveIntegerOptionParser';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
+import {
+    addHarnessUpdateOption,
+    normalizeHarnessUpdateCliOptions,
+    type HarnessUpdateCliOptions,
+} from '../common/harnessUpdateCliOptions';
+import { $ensurePromptbookCliInstallations } from '../common/promptbook-cli/$ensurePromptbookCliInstallations';
 import type { PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerExecutionOptions,
@@ -41,12 +47,16 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
 
             Features:
             - Automatically stages and commits changes with agent identity unless --no-commit is used
+            - Commits only the prompt file and the files the coding agent has changed, leaving unrelated changes alone
+            - Refuses to start on a dirty working tree unless --git-changes says what should happen with the changes
+            - Optional --git-changes continue resumes the single prompt an interrupted coder left in the [^] status
             - Optional post-commit git push with explicit --auto-push opt-in
             - Optional pre-prompt git pull with explicit --auto-pull opt-in
             - Optional --isolate runs every prompt in its own temporary git worktree and merges it back when verified
             - Optional --preserve-logs keeps temp prompt/log artifacts after successful rounds
             - 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
+            - Checks that the selected harness is installed globally and up to date before the first prompt unless --no-harness-update is used
+            - In interactive mode, checks local and global Promptbook CLI installations and offers to update them
             - 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
@@ -57,6 +67,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
 
     command.option('--dry-run', 'Print unwritten prompts without executing', false);
     addPromptRunnerSelectionOptions(command);
+    addHarnessUpdateOption(command);
     command.option(
         '--agent <agent-book-path>',
         'Path to a .book file whose compiled system message is prepended to each coding prompt',
@@ -195,8 +206,9 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
                 isAgentRequired: !dryRun,
             });
-
-            await $ensureHarnessInstallations([runnerOptions.agentName]);
+            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
+                cliOptions as HarnessUpdateCliOptions,
+            );
 
             // [1] Parse the wait options and --no-auto:
             //   default: run automatically through the queue (no waiting between prompts)
@@ -205,6 +217,13 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             //   --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;
+
+            if (await $ensurePromptbookCliInstallations()) {
+                return process.exit(0);
+            }
+
+            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
+
             const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
             const waitBetweenPrompts = parseOptionalWaitDuration(waitBetweenPromptsValue, 0);
             const waitAfterError = parseOptionalWaitDuration(waitAfterErrorValue, DEFAULT_WAIT_AFTER_ERROR_MS);
@@ -217,7 +236,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 waitBetweenPrompts,
                 waitAfterError,
                 noCommit: runnerOptions.noCommit,
-                ignoreGitChanges: runnerOptions.ignoreGitChanges,
+                gitChanges: runnerOptions.gitChanges,
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
                 agent,

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

@@ -12,6 +12,11 @@ import type { $side_effect } from '../../../utils/organization/$side_effect';
 import { createNonNegativeIntegerOptionParser } from '../common/createNonNegativeIntegerOptionParser';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
+import {
+    addHarnessUpdateOption,
+    normalizeHarnessUpdateCliOptions,
+    type HarnessUpdateCliOptions,
+} from '../common/harnessUpdateCliOptions';
 import type { PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerExecutionOptions,
@@ -48,7 +53,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
 
             Features:
             - Runs the same prompt processing as \`ptbk coder run\`
-            - Checks that the selected harness is installed globally and up to date on startup
+            - Checks that the selected harness is installed globally and up to date on startup unless --no-harness-update is used
             - 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)
@@ -64,6 +69,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
     );
     command.option('--dry-run', 'Print unwritten prompts without executing', false);
     addPromptRunnerSelectionOptions(command);
+    addHarnessUpdateOption(command);
     command.option(
         '--agent <agent-book-path>',
         'Path to a .book file whose compiled system message is prepended to each coding prompt',
@@ -173,8 +179,11 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
                 isAgentRequired: !dryRun,
             });
+            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
+                cliOptions as HarnessUpdateCliOptions,
+            );
 
-            await $ensureHarnessInstallations([runnerOptions.agentName]);
+            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
 
             // [1] Parse the wait options and --no-auto (same logic as `coder run`)
             const waitForUser = !auto;
@@ -190,7 +199,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 waitBetweenPrompts,
                 waitAfterError,
                 noCommit: runnerOptions.noCommit,
-                ignoreGitChanges: runnerOptions.ignoreGitChanges,
+                gitChanges: runnerOptions.gitChanges,
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
                 agent,

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

@@ -1,9 +1,22 @@
 import colors from 'colors';
-import type {
+import {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+    Option,
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
+import type { VerifyPromptsOrder } from '../../../../scripts/verify-prompts/VerifyPromptsOrder';
+import {
+    DEFAULT_VERIFY_PROMPTS_ORDER,
+    VERIFY_PROMPTS_ORDER_DESCRIPTIONS,
+    VERIFY_PROMPTS_ORDER_VALUES,
+} from '../../../../scripts/verify-prompts/VerifyPromptsOrder';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import type { CoderGitSyncCliOptions } from '../common/coderGitSyncCliOptions';
+import {
+    addCoderGitSyncOptions,
+    CODER_GIT_SYNC_DESCRIPTION,
+    normalizeCoderGitSyncCliOptions,
+} from '../common/coderGitSyncCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 
 /**
@@ -16,39 +29,65 @@ import { handleActionErrors } from '../common/handleActionErrors';
 export function $initializeCoderVerifyCommand(program: Program): $side_effect {
     const command = program.command('verify');
     command.description(
-        spaceTrim(`
-            Interactive verification helper for completed prompts
+        spaceTrim(
+            (block) => `
+                Interactive verification helper for completed prompts
 
-            Features:
-            - Displays list of prompt files with status counts
-            - Guides through verification of completed prompts marked [x]
-            - Archives verified prompt files to prompts/done/ directory
-            - Auto-appends repair prompts for incomplete work
-            - Processes files with all-done prompts first
-            - Supports ignoring matching prompt candidates for one verification run
-        `),
+                Features:
+                - Displays list of prompt files with status counts
+                - Guides through verification of completed prompts marked [x]
+                - Archives verified prompt files to prompts/done/ directory
+                - Auto-appends repair prompts for incomplete work
+                - Processes files with all-done prompts first
+                - Supports ignoring matching prompt candidates for one verification run
+                - Supports processing the prompt files from the earliest, from the latest or in random order
+
+                ${block(CODER_GIT_SYNC_DESCRIPTION)}
+
+                Note: The git synchronization is applied around each single verification, not once per run.
+            `,
+        ),
     );
 
-    command.option('--reverse', 'Process prompt files in reverse order', false);
+    command.addOption(
+        new Option(
+            '--order <order>',
+            spaceTrim(
+                (block) => `
+                    Order in which the prompt files are processed:
+                    ${block(
+                        VERIFY_PROMPTS_ORDER_VALUES.map(
+                            (order) => `- ${order}: ${VERIFY_PROMPTS_ORDER_DESCRIPTIONS[order]}`,
+                        ).join('\n'),
+                    )}
+                `,
+            ),
+        )
+            .choices([...VERIFY_PROMPTS_ORDER_VALUES])
+            .default(DEFAULT_VERIFY_PROMPTS_ORDER),
+    );
     command.option(
         '--ignore <candidate-text>',
         'Ignore prompt files whose filename or first prompt line contains the given text (repeatable)',
         collectStringOption,
         [],
     );
+    addCoderGitSyncOptions(command);
 
     command.action(
         handleActionErrors(async (cliOptions) => {
-            const { reverse, ignore } = cliOptions as {
-                readonly reverse: boolean;
+            const { order, ignore } = cliOptions as {
+                readonly order: VerifyPromptsOrder;
                 readonly ignore: ReadonlyArray<string>;
-            };
+            } & CoderGitSyncCliOptions;
+
+            const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
 
             // Note: Import the main function dynamically to avoid loading heavy dependencies until needed
             const { verifyPrompts } = await import('../../../../scripts/verify-prompts/verify-prompts');
 
             try {
-                await verifyPrompts({ reverse, ignore });
+                await verifyPrompts({ order, ignore, gitSync });
             } catch (error) {
                 console.error(colors.bgRed('Prompt verification failed:'), error);
                 return process.exit(1);

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

@@ -1,4 +1,6 @@
+import { spaceTrim } from 'spacetrim';
 import { parseDuration } from '../../../../scripts/run-codex-prompts/common/parseDuration';
+import { NotAllowed } from '../../../errors/NotAllowed';
 
 /**
  * Default wait duration applied before retrying a prompt round after an error (10 minutes).
@@ -21,4 +23,35 @@ export function parseOptionalWaitDuration(value: string | undefined, defaultMs:
     return parseDuration(value);
 }
 
+/**
+ * Parses an optional Commander period duration string and returns the resolved milliseconds.
+ *
+ * Returns `undefined` when the flag was not provided or was provided without a non-empty value,
+ * which means the command runs only once instead of repeating itself.
+ *
+ * @throws {NotAllowed} When the duration is not a positive one, because a non-positive period
+ *                      would repeat the command without ever pausing between two rounds
+ *
+ * @private internal utility of `ptbk coder` wait handling
+ */
+export function parseOptionalPeriodDuration(optionName: string, value: string | undefined): number | undefined {
+    if (typeof value !== 'string' || value === '') {
+        return undefined;
+    }
+
+    const periodMs = parseDuration(value);
+
+    if (periodMs <= 0) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid value for \`${optionName}\`: \`${value}\`.
+
+                Use a **positive** duration like \`5h\`, \`30m\` or \`1h30m\`.
+            `),
+        );
+    }
+
+    return periodMs;
+}
+
 // Note: [💞] Ignore a discrepancy between file name and entity name

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

@@ -23,8 +23,8 @@ 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
+ * - ping: Test one harness and model with a tiny dummy prompt
  * - verify: Verify completed prompts
  * - find-fresh-emoji-tags: Find unused emoji tags
  *
@@ -44,8 +44,8 @@ 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
+            - ping: Test the connection, response time and quota of one harness and model
             - server: Start a long-running coder server with a kanban web UI
             - verify: Verify completed prompts
             - find-fresh-emoji-tags: Find unused emoji tags
@@ -58,8 +58,8 @@ export function $initializeCoderCommand(program: Program): $side_effect {
     $initializeCoderGenerateBoilerplatesCommand(coderCommand);
     $initializeCoderFindRefactorCandidatesCommand(coderCommand);
     $initializeCoderFindUnwrittenCommand(coderCommand);
-    $initializeCoderPingCommand(coderCommand);
     $initializeCoderRunCommand(coderCommand);
+    $initializeCoderPingCommand(coderCommand);
     $initializeCoderServerCommand(coderCommand);
     $initializeCoderVerifyCommand(coderCommand);
     $initializeCoderFindFreshEmojiTagCommand(coderCommand);

package/src/cli/cli-commands/common/coderGitSyncCliOptions.ts

@@ -0,0 +1,82 @@
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+import { spaceTrim } from 'spacetrim';
+import type { CoderGitSyncOptions } from '../../../../scripts/run-codex-prompts/git/coderGitSync';
+import { NotAllowed } from '../../../errors/NotAllowed';
+
+export type { CoderGitSyncOptions };
+
+/**
+ * Commander option bag for the shared `ptbk coder` git synchronization flags.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type CoderGitSyncCliOptions = {
+    readonly commit: boolean;
+    readonly autoPush: boolean;
+    readonly autoPull: boolean;
+};
+
+/**
+ * Description block shared by the `ptbk coder` commands which can synchronize their changes with git.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export const CODER_GIT_SYNC_DESCRIPTION = spaceTrim(`
+    Git synchronization:
+    - --auto-pull pulls the latest changes before this command changes anything
+    - --commit commits only the files this command has changed, unrelated changes stay in the working tree
+    - --auto-push pushes the created commit to the remote repository
+`);
+
+/**
+ * Registers the shared `--commit`, `--auto-push` and `--auto-pull` flags on a `ptbk coder` command.
+ *
+ * Note: Unlike `ptbk coder run`, which commits by default and opts out through `--no-commit`,
+ *       these commands never touch git unless the flags are used explicitly.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function addCoderGitSyncOptions(command: Program): void {
+    command.option(
+        '--commit',
+        'Commit the files changed by this command with the coding-agent git identity, leaving unrelated changes uncommitted',
+        false,
+    );
+    command.option('--auto-push', 'Automatically git push the created commit, requires --commit', false);
+    command.option(
+        '--auto-pull',
+        'Automatically git pull the latest changes before this command changes anything',
+        false,
+    );
+}
+
+/**
+ * Converts the Commander git synchronization flags into normalized git synchronization options.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function normalizeCoderGitSyncCliOptions(cliOptions: CoderGitSyncCliOptions): CoderGitSyncOptions {
+    if (cliOptions.autoPush && !cliOptions.commit) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Flag \`--auto-push\` can be used only together with \`--commit\`.
+
+                **There is nothing to push when the changes are not committed.**
+
+                Actionable hint:
+                - Add \`--commit\`, for example \`ptbk coder init --commit --auto-push\`.
+            `),
+        );
+    }
+
+    return {
+        isCommitEnabled: cliOptions.commit,
+        isAutoPushEnabled: cliOptions.autoPush,
+        isAutoPullEnabled: cliOptions.autoPull,
+    };
+}
+
+// Note: [🟡] Code for CLI git synchronization options [coderGitSyncCliOptions](src/cli/cli-commands/common/coderGitSyncCliOptions.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/common/harness/$applyHarnessInstallationStatus.ts

@@ -1,5 +1,5 @@
 import colors from 'colors';
-import { $askForHarnessInstallationApproval } from './$askForHarnessInstallationApproval';
+import { $askForNpmPackageInstallationApproval } from '../npm/$askForNpmPackageInstallationApproval';
 import { $installHarness } from './$installHarness';
 import { buildHarnessInstallCommand } from './buildHarnessInstallCommand';
 import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
@@ -20,6 +20,13 @@ export async function $applyHarnessInstallationStatus(status: HarnessInstallatio
         return;
     }
 
+    if (installationState === 'installed') {
+        console.info(
+            colors.gray(`✔ ${definition.label} ${installedVersion} is installed. Skipped checking for updates.`),
+        );
+        return;
+    }
+
     if (installationState === 'unknown') {
         console.info(
             colors.gray(
@@ -31,7 +38,7 @@ export async function $applyHarnessInstallationStatus(status: HarnessInstallatio
 
     console.warn(colors.yellow(formatHarnessInstallationWarning(status)));
 
-    const isInstallationApproved = await $askForHarnessInstallationApproval(
+    const isInstallationApproved = await $askForNpmPackageInstallationApproval(
         installationState === 'not-installed'
             ? `Install ${definition.label} globally now?`
             : `Update ${definition.label} to ${latestVersion} now?`,