@promptbook/cli 0.113.0-4 → 0.113.0-8

package/src/book-components/Chat/Chat/useChatInputAreaDictation.ts

@@ -38,6 +38,17 @@ type DictationChunk = {
     readonly start: number;
 };
 
+/**
+ * Stable insertion range captured when the user starts dictation.
+ *
+ * @private function of `useChatInputAreaDictation`
+ */
+type DictationInsertionSelection = {
+    readonly selectionStart: number;
+    readonly selectionEnd: number;
+    readonly isReplacingSelection: boolean;
+};
+
 /**
  * Stable dictation error shape consumed by the correction panel UI.
  *
@@ -88,7 +99,7 @@ type UseChatInputAreaDictationFinalResultHandlerProps = {
     readonly applyMessageContent: (nextContent: string) => void;
     readonly dictationSettings: DictationRefinementSettings;
     readonly dictationDictionary: ReturnType<typeof useChatInputAreaDictationPersistence>['dictationDictionary'];
-    readonly replaceSelectionOnNextFinalRef: MutableRefObject<boolean>;
+    readonly dictationInsertionSelectionRef: MutableRefObject<DictationInsertionSelection | null>;
     readonly focusTextareaSelection: (selectionStart: number, selectionEnd: number) => void;
     readonly state: UseChatInputAreaDictationState;
 };
@@ -126,7 +137,7 @@ type UseChatInputAreaDictationVoiceInputControlsProps = {
     readonly resolvedSpeechRecognitionLanguage: string;
     readonly whisperMode: boolean;
     readonly pendingStopFallbackRef: MutableRefObject<ReturnType<typeof setTimeout> | null>;
-    readonly replaceSelectionOnNextFinalRef: MutableRefObject<boolean>;
+    readonly dictationInsertionSelectionRef: MutableRefObject<DictationInsertionSelection | null>;
     readonly clearPendingStopFallback: () => void;
     readonly state: Pick<
         UseChatInputAreaDictationState,
@@ -144,6 +155,7 @@ type UseChatInputAreaDictationCorrectionHandlersProps = {
     readonly dictationLastFinalChunk: string;
     readonly dictationEditableChunk: string;
     readonly dictationDictionary: ReturnType<typeof useChatInputAreaDictationPersistence>['dictationDictionary'];
+    readonly dictationInsertionSelectionRef: MutableRefObject<DictationInsertionSelection | null>;
     readonly messageContentRef: MutableRefObject<string>;
     readonly applyMessageContent: (nextContent: string) => void;
     readonly focusTextareaSelection: (selectionStart: number, selectionEnd: number) => void;
@@ -235,21 +247,96 @@ function clearPendingStopFallbackTimeout(
 }
 
 /**
- * Captures whether the next finalized chunk should replace the current selection.
+ * Captures where the next finalized chunk should be inserted.
  *
  * @private function of `useChatInputAreaDictation`
  */
-function captureSelectionReplacementIntent(
+function captureDictationInsertionSelection(
     textareaRef: MutableRefObject<HTMLTextAreaElement | null>,
-    replaceSelectionOnNextFinalRef: MutableRefObject<boolean>,
+    dictationInsertionSelectionRef: MutableRefObject<DictationInsertionSelection | null>,
 ): void {
     const textarea = textareaRef.current;
     if (!textarea) {
         return;
     }
 
-    const { selectionStart, selectionEnd } = resolveTextareaSelection(textarea, 0);
-    replaceSelectionOnNextFinalRef.current = selectionStart !== selectionEnd;
+    const { selectionStart, selectionEnd } = resolveTextareaSelection(textarea, textarea.value.length);
+    dictationInsertionSelectionRef.current = {
+        selectionStart,
+        selectionEnd,
+        isReplacingSelection: selectionStart !== selectionEnd,
+    };
+}
+
+/**
+ * Resolves the insertion range for one finalized dictation chunk.
+ *
+ * @private function of `useChatInputAreaDictation`
+ */
+function resolveDictationInsertionSelection(
+    textareaElement: HTMLTextAreaElement,
+    messageContentLength: number,
+    dictationInsertionSelection: DictationInsertionSelection | null,
+): DictationInsertionSelection {
+    if (dictationInsertionSelection) {
+        return dictationInsertionSelection;
+    }
+
+    const { selectionStart, selectionEnd } = resolveTextareaSelection(textareaElement, messageContentLength);
+
+    return {
+        selectionStart,
+        selectionEnd,
+        isReplacingSelection: selectionStart !== selectionEnd,
+    };
+}
+
+/**
+ * Removes one tracked dictated chunk from the current composer value.
+ *
+ * @private function of `useChatInputAreaDictation`
+ */
+function removeTrackedDictationChunk(currentValue: string, chunk: DictationChunk): string {
+    const trackedText = currentValue.slice(chunk.start, chunk.start + chunk.finalText.length);
+
+    if (trackedText === chunk.finalText) {
+        return `${currentValue.slice(0, chunk.start)}${currentValue.slice(chunk.start + chunk.finalText.length)}`;
+    }
+
+    return replaceLastOccurrence(currentValue, chunk.finalText, '');
+}
+
+/**
+ * Replaces one tracked dictated chunk inside the current composer value.
+ *
+ * @private function of `useChatInputAreaDictation`
+ */
+function replaceTrackedDictationChunk(currentValue: string, chunk: DictationChunk, correctedChunk: string): string {
+    const trackedText = currentValue.slice(chunk.start, chunk.start + chunk.finalText.length);
+
+    if (trackedText === chunk.finalText) {
+        return `${currentValue.slice(0, chunk.start)}${correctedChunk}${currentValue.slice(
+            chunk.start + chunk.finalText.length,
+        )}`;
+    }
+
+    return replaceLastOccurrence(currentValue, chunk.finalText, correctedChunk);
+}
+
+/**
+ * Stores the next append position after a programmatic dictation edit.
+ *
+ * @private function of `useChatInputAreaDictation`
+ */
+function updateDictationInsertionCaret(
+    dictationInsertionSelectionRef: MutableRefObject<DictationInsertionSelection | null>,
+    caret: number,
+): void {
+    dictationInsertionSelectionRef.current = {
+        selectionStart: caret,
+        selectionEnd: caret,
+        isReplacingSelection: false,
+    };
 }
 
 /**
@@ -376,7 +463,7 @@ function useChatInputAreaDictationFinalResultHandler({
     applyMessageContent,
     dictationSettings,
     dictationDictionary,
-    replaceSelectionOnNextFinalRef,
+    dictationInsertionSelectionRef,
     focusTextareaSelection,
     state,
 }: UseChatInputAreaDictationFinalResultHandlerProps) {
@@ -403,16 +490,20 @@ function useChatInputAreaDictationFinalResultHandler({
                 return;
             }
 
-            const { selectionStart, selectionEnd } = resolveTextareaSelection(textarea, previousMessageContent.length);
+            const { selectionStart, selectionEnd, isReplacingSelection } = resolveDictationInsertionSelection(
+                textarea,
+                previousMessageContent.length,
+                dictationInsertionSelectionRef.current,
+            );
             const insertion = insertDictationChunk({
                 currentValue: previousMessageContent,
                 dictatedText: refinedText,
                 selectionStart,
                 selectionEnd,
-                shouldReplaceSelection: replaceSelectionOnNextFinalRef.current,
+                isReplacingSelection,
             });
 
-            replaceSelectionOnNextFinalRef.current = false;
+            updateDictationInsertionCaret(dictationInsertionSelectionRef, insertion.caret);
             setDictationInterimText('');
             setDictationError(null);
             setDictationUiState('listening');
@@ -433,10 +524,10 @@ function useChatInputAreaDictationFinalResultHandler({
         [
             applyMessageContent,
             dictationDictionary,
+            dictationInsertionSelectionRef,
             dictationSettings,
             focusTextareaSelection,
             messageContentRef,
-            replaceSelectionOnNextFinalRef,
             setDictationChunks,
             setDictationEditableChunk,
             setDictationError,
@@ -491,7 +582,9 @@ function useChatInputAreaDictationSpeechRecognitionEventHandler({
                     return;
                 case 'STOP':
                     clearPendingStopFallback();
-                    setDictationUiState((currentState) => (currentState === 'disabled' ? currentState : 'idle'));
+                    setDictationUiState((currentState) =>
+                        currentState === 'disabled' || currentState === 'error' ? currentState : 'idle',
+                    );
                     setDictationInterimText('');
                     return;
             }
@@ -549,7 +642,7 @@ function useChatInputAreaDictationVoiceInputControls({
     resolvedSpeechRecognitionLanguage,
     whisperMode,
     pendingStopFallbackRef,
-    replaceSelectionOnNextFinalRef,
+    dictationInsertionSelectionRef,
     clearPendingStopFallback,
     state,
 }: UseChatInputAreaDictationVoiceInputControlsProps) {
@@ -560,7 +653,7 @@ function useChatInputAreaDictationVoiceInputControls({
             return;
         }
 
-        captureSelectionReplacementIntent(textareaRef, replaceSelectionOnNextFinalRef);
+        captureDictationInsertionSelection(textareaRef, dictationInsertionSelectionRef);
         setDictationError(null);
         setDictationInterimText('');
         setDictationUiState('listening');
@@ -570,7 +663,7 @@ function useChatInputAreaDictationVoiceInputControls({
             whisperMode,
         });
     }, [
-        replaceSelectionOnNextFinalRef,
+        dictationInsertionSelectionRef,
         resolvedSpeechRecognitionLanguage,
         setDictationError,
         setDictationInterimText,
@@ -635,6 +728,7 @@ function useChatInputAreaDictationCorrectionHandlers({
     dictationLastFinalChunk,
     dictationEditableChunk,
     dictationDictionary,
+    dictationInsertionSelectionRef,
     messageContentRef,
     applyMessageContent,
     focusTextareaSelection,
@@ -651,17 +745,23 @@ function useChatInputAreaDictationCorrectionHandlers({
             return;
         }
 
+        const nextMessageContent = removeTrackedDictationChunk(messageContentRef.current, lastChunk);
+        const nextCaret = Math.min(lastChunk.start, nextMessageContent.length);
+
         setDictationChunks(previousChunks);
-        applyMessageContent(lastChunk.beforeValue);
+        applyMessageContent(nextMessageContent);
 
         const previousFinalChunk = previousChunks[previousChunks.length - 1]?.finalText || '';
         setDictationLastFinalChunk(previousFinalChunk);
         setDictationEditableChunk(previousFinalChunk);
-        focusTextareaSelection(lastChunk.start, lastChunk.start);
+        updateDictationInsertionCaret(dictationInsertionSelectionRef, nextCaret);
+        focusTextareaSelection(nextCaret, nextCaret);
     }, [
         applyMessageContent,
+        dictationInsertionSelectionRef,
         dictationChunks,
         focusTextareaSelection,
+        messageContentRef,
         setDictationChunks,
         setDictationEditableChunk,
         setDictationLastFinalChunk,
@@ -673,21 +773,27 @@ function useChatInputAreaDictationCorrectionHandlers({
             return;
         }
 
-        const nextMessageContent = replaceLastOccurrence(
-            messageContentRef.current,
-            dictationLastFinalChunk,
-            correctedChunk,
-        );
+        const lastChunk = dictationChunks[dictationChunks.length - 1];
+        const nextMessageContent = lastChunk
+            ? replaceTrackedDictationChunk(messageContentRef.current, lastChunk, correctedChunk)
+            : replaceLastOccurrence(messageContentRef.current, dictationLastFinalChunk, correctedChunk);
+        const correctionStart = lastChunk?.start ?? nextMessageContent.length;
+        const correctionCaret = Math.min(correctionStart + correctedChunk.length, nextMessageContent.length);
 
         applyMessageContent(nextMessageContent);
         setDictationLastFinalChunk(correctedChunk);
         setDictationChunks((previousChunks) => replaceLastDictationChunk(previousChunks, correctedChunk));
         setDictationDictionary(learnDictationDictionary(dictationLastFinalChunk, correctedChunk, dictationDictionary));
+        updateDictationInsertionCaret(dictationInsertionSelectionRef, correctionCaret);
+        focusTextareaSelection(correctionCaret, correctionCaret);
     }, [
         applyMessageContent,
         dictationDictionary,
         dictationEditableChunk,
+        dictationChunks,
+        dictationInsertionSelectionRef,
         dictationLastFinalChunk,
+        focusTextareaSelection,
         messageContentRef,
         setDictationChunks,
         setDictationDictionary,
@@ -713,7 +819,7 @@ export function useChatInputAreaDictation({
     applyMessageContent,
 }: UseChatInputAreaDictationProps) {
     const pendingStopFallbackRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-    const replaceSelectionOnNextFinalRef = useRef(false);
+    const dictationInsertionSelectionRef = useRef<DictationInsertionSelection | null>(null);
     const [dictationUiState, setDictationUiState] = useState<DictationUiState>('idle');
     const [dictationInterimText, setDictationInterimText] = useState('');
     const [dictationError, setDictationError] = useState<DictationError | null>(null);
@@ -753,7 +859,7 @@ export function useChatInputAreaDictation({
         applyMessageContent,
         dictationSettings,
         dictationDictionary,
-        replaceSelectionOnNextFinalRef,
+        dictationInsertionSelectionRef,
         focusTextareaSelection,
         state: dictationState,
     });
@@ -775,7 +881,7 @@ export function useChatInputAreaDictation({
         resolvedSpeechRecognitionLanguage,
         whisperMode: dictationSettings.whisperMode,
         pendingStopFallbackRef,
-        replaceSelectionOnNextFinalRef,
+        dictationInsertionSelectionRef,
         clearPendingStopFallback,
         state: {
             dictationUiState,
@@ -789,6 +895,7 @@ export function useChatInputAreaDictation({
         dictationLastFinalChunk,
         dictationEditableChunk,
         dictationDictionary,
+        dictationInsertionSelectionRef,
         messageContentRef,
         applyMessageContent,
         focusTextareaSelection,

package/src/cli/cli-commands/agents-server/buildAgentsServer.ts

@@ -739,7 +739,9 @@ function isNextBuildTerminationRetryable(exitStatus: NextBuildExitStatus): boole
  * Creates one visible retry message for a killed Next.js build attempt.
  */
 function createNextBuildRetryMessage(exitStatus: NextBuildExitStatus, nextAttempt: number): string {
-    return `\nAgents Server Next build was terminated by ${describeNextBuildExitStatus(exitStatus)}. Retrying attempt ${nextAttempt}/${AGENTS_SERVER_BUILD_MAX_ATTEMPTS}.\n`;
+    return `\nAgents Server Next build was terminated by ${describeNextBuildExitStatus(
+        exitStatus,
+    )}. Retrying attempt ${nextAttempt}/${AGENTS_SERVER_BUILD_MAX_ATTEMPTS}.\n`;
 }
 
 /**

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

@@ -120,26 +120,26 @@ const DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS = [
         id: 'common',
         relativeFilePath: join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'common.md'),
         slugPrefix: null,
-        content: buildCoderPromptTemplateContent([
-            '-   @@@',
-            "-   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)',
-        ]),
+        content: spaceTrim(`
+            -   @@@
+            -   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)
+        `),
         isDefaultProjectTemplate: true,
     },
     {
         id: 'agents-server',
         relativeFilePath: join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'agents-server.md'),
         slugPrefix: 'agents-server',
-        content: buildCoderPromptTemplateContent([
-            '-   @@@',
-            "-   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)',
-        ]),
+        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>;
@@ -288,13 +288,6 @@ function getDefaultCoderPromptTemplateDefinitionOrUndefined(
     return DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS.find((definition) => definition.id === template);
 }
 
-/**
- * Builds stable markdown content for one coder prompt template without indentation drift.
- */
-function buildCoderPromptTemplateContent(lines: ReadonlyArray<string>): string {
-    return lines.join('\n');
-}
-
 /**
  * Creates a fully resolved template payload from one built-in definition.
  */

package/src/cli/cli-commands/coder/find-refactor-candidates.ts

@@ -12,6 +12,7 @@ import {
 } from '../../../../scripts/find-refactor-candidates/RefactorCandidateLevel';
 import { assertsError } from '../../../errors/assertsError';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { createPositiveIntegerOptionParser } from '../common/createPositiveIntegerOptionParser';
 import { handleActionErrors } from '../common/handleActionErrors';
 
 /**
@@ -44,11 +45,17 @@ export function $initializeCoderFindRefactorCandidatesCommand(program: Program):
             .choices([...REFACTOR_CANDIDATE_LEVEL_VALUES])
             .default(DEFAULT_REFACTOR_CANDIDATE_LEVEL),
     );
+    command.option(
+        '--limit <candidate-count>',
+        'Create at most this many refactor prompts, keeping the most important candidates',
+        createPositiveIntegerOptionParser('--limit'),
+    );
 
     command.action(
         handleActionErrors(async (cliOptions) => {
-            const { level = DEFAULT_REFACTOR_CANDIDATE_LEVEL } = cliOptions as {
+            const { level = DEFAULT_REFACTOR_CANDIDATE_LEVEL, limit } = cliOptions as {
                 readonly level?: RefactorCandidateLevel;
+                readonly limit?: number;
             };
 
             // Note: Import the function dynamically to avoid loading heavy dependencies until needed
@@ -57,7 +64,7 @@ export function $initializeCoderFindRefactorCandidatesCommand(program: Program):
             );
 
             try {
-                await findRefactorCandidates({ level });
+                await findRefactorCandidates({ level, limit });
             } catch (error) {
                 assertsError(error);
                 console.error(colors.bgRed(`${error.name}`));

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

@@ -8,10 +8,7 @@ import {
     PROMPTS_TEMPLATES_DIRECTORY_PATH,
 } from './boilerplateTemplates';
 import { ensureCoderEnvFile } from './ensureCoderEnvFile';
-import {
-    CODER_AGENTS_DIRECTORY_PATH,
-    ensureCoderDeveloperAgentFile,
-} from './ensureCoderDeveloperAgentFile';
+import { CODER_AGENTS_DIRECTORY_PATH, ensureCoderDeveloperAgentFile } from './ensureCoderDeveloperAgentFile';
 import { ensureCoderGitignoreFile } from './ensureCoderGitignoreFile';
 import { ensureCoderMarkdownFile } from './ensureCoderMarkdownFile';
 import { ensureCoderPackageJsonFile } from './ensureCoderPackageJsonFile';

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

@@ -1,9 +1,9 @@
 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 { createPositiveIntegerOptionParser } from '../common/createPositiveIntegerOptionParser';
 import { handleActionErrors } from '../common/handleActionErrors';
 import type { PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
 import {
@@ -12,10 +12,7 @@ import {
     normalizePromptRunnerCliOptions,
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
-import {
-    DEFAULT_WAIT_AFTER_ERROR_MS,
-    parseOptionalWaitDuration,
-} from './waitOptions';
+import { DEFAULT_WAIT_AFTER_ERROR_MS, parseOptionalWaitDuration } from './waitOptions';
 
 /**
  * Initializes `coder run` command for Promptbook CLI utilities
@@ -69,7 +66,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
     command.option(
         '--limit <run-count>',
         'Stop after processing this many prompt runs',
-        parsePositiveIntegerOption,
+        createPositiveIntegerOptionParser('--limit'),
     );
     command.option(
         '--wait-after-prompt <duration>',
@@ -213,27 +210,6 @@ 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/common/createPositiveIntegerOptionParser.ts

@@ -0,0 +1,31 @@
+import { spaceTrim } from 'spacetrim';
+import { NotAllowed } from '../../../errors/NotAllowed';
+
+/**
+ * Creates a Commander argument parser that accepts only positive integers.
+ *
+ * The returned parser is meant to be passed as the coercion callback of `command.option(...)`.
+ * It throws a branded `NotAllowed` error with a clear message referencing the given option name
+ * when the provided value is not a positive integer.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function createPositiveIntegerOptionParser(optionName: string): (value: string) => number {
+    return (value: string): number => {
+        const parsedValue = Number(value);
+
+        if (!Number.isInteger(parsedValue) || parsedValue <= 0) {
+            throw new NotAllowed(
+                spaceTrim(`
+                    Invalid value for \`${optionName}\`: \`${value}\`.
+
+                    Use a positive integer.
+                `),
+            );
+        }
+
+        return parsedValue;
+    };
+}
+
+// Note: [🟡] Code for CLI option parser [createPositiveIntegerOptionParser](src/cli/cli-commands/common/createPositiveIntegerOptionParser.ts) should never be published outside of `@promptbook/cli`

package/src/commitments/TEAM/TEAM.ts

@@ -113,10 +113,10 @@ const teamToolTitles: Record<string_javascript_name, string> = {};
  *
  * @private
  */
-const TEAM_SYSTEM_MESSAGE_GUIDANCE_LINES = [
-    '-   If a teammate is relevant to the request, consult that teammate using the matching tool.',
-    '-   Do not ask the user for information that a listed teammate can provide directly.',
-] as const;
+const TEAM_SYSTEM_MESSAGE_GUIDANCE = spaceTrim(`
+    -   If a teammate is relevant to the request, consult that teammate using the matching tool.
+    -   Do not ask the user for information that a listed teammate can provide directly.
+`);
 /**
  * Constant for remote agents by Url.
  */
@@ -352,7 +352,7 @@ function buildTeamSystemMessageBody(teamEntries: ReadonlyArray<TeamToolEntry>):
 
     return spaceTrim(
         (block) => `
-            ${block(TEAM_SYSTEM_MESSAGE_GUIDANCE_LINES.join('\n'))}
+            ${block(TEAM_SYSTEM_MESSAGE_GUIDANCE)}
 
             ${block(teammateSections.join('\n\n'))}
         `,