@promptbook/cli 0.114.0-32 → 0.114.0-34

package/esm/scripts/run-codex-prompts/common/createFreeDiskSpaceGuard.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Measures the free disk space of a run which is already in progress and requests a pause when it became critical.
+ *
+ * @private internal utility of `ptbk coder` free disk space handling
+ */
+export type FreeDiskSpaceGuard = () => Promise<void>;
+/**
+ * Creates the guard which watches the free disk space while one `ptbk coder` run is in progress.
+ *
+ * The guard runs at every pause checkpoint of the run. When the disk became critically full it reports the
+ * warning and requests a pause, so the run stops at that checkpoint instead of failing in the middle of a
+ * coding round, and continues once the user has freed some space and pressed `P`.
+ *
+ * @private internal utility of `ptbk coder` free disk space handling
+ */
+export declare function createFreeDiskSpaceGuard(options: {
+    /**
+     * Path whose filesystem is watched, usually the project the coder runs in.
+     */
+    readonly inspectedPath: string;
+    /**
+     * Whether the run may stop and wait for somebody to free the disk space, disabled by `--no-questions`.
+     */
+    readonly isAskingQuestionsEnabled: boolean;
+}): FreeDiskSpaceGuard;

package/esm/scripts/run-codex-prompts/common/formatUnknownErrorDetails.d.ts

@@ -1,4 +1,8 @@
 /**
  * Formats one unknown error-like value into readable text for logs and feedback.
+ *
+ * An `AuthenticationError` is reported without its stack, because its message is written for the user - it
+ * says which harness has to be signed in again and how - and the frames of a failure nobody can debug would
+ * only push those instructions out of sight.
  */
 export declare function formatUnknownErrorDetails(error: unknown): string;

package/esm/scripts/run-codex-prompts/common/resolveCoderAgent.d.ts

@@ -1,20 +1,38 @@
 import type { string_book } from '../../../src/book-2.0/agent-source/string_book';
 /**
- * Agent data resolved from the optional `--agent` book file.
+ * Source and prompt-routing references resolved from an optional `--agent` book file.
  */
-export type ResolvedCoderAgent = {
+export type ResolvedCoderAgentBook = {
     /**
      * Raw source of the agent `.book` file.
      */
     readonly agentSource: string_book;
+    /**
+     * Equivalent references by which a prompt may target this agent.
+     *
+     * Includes the configured path, relative path, filename, filename without `.book`, and the
+     * normalized Book title from its first line.
+     */
+    readonly agentReferences: ReadonlyArray<string>;
+};
+/**
+ * Agent data resolved from the optional `--agent` book file.
+ */
+export type ResolvedCoderAgent = ResolvedCoderAgentBook & {
     /**
      * Compiled system message injected into each coding prompt.
      */
     readonly systemMessage: string;
 };
+/**
+ * Reads an optional agent `.book` file and prepares the references that route prompts to it.
+ *
+ * Returns `undefined` when no agent path is provided.
+ */
+export declare function resolveCoderAgentBook(agentBookReference: string | undefined, currentWorkingDirectory: string): Promise<ResolvedCoderAgentBook | undefined>;
 /**
  * Reads an optional agent `.book` file and compiles its system message for injection into coder prompts.
  *
  * Returns `undefined` when no agent path is provided.
  */
-export declare function resolveCoderAgent(agentPath: string | undefined, currentWorkingDirectory: string): Promise<ResolvedCoderAgent | undefined>;
+export declare function resolveCoderAgent(agentBookReference: string | undefined, currentWorkingDirectory: string): Promise<ResolvedCoderAgent | undefined>;

package/esm/scripts/run-codex-prompts/main/listCoderPrompts.d.ts

@@ -0,0 +1,20 @@
+import { type PriorityFilterInput } from '../prompts/priorityFilter';
+import type { PromptRunnerIdentity } from '../prompts/isPromptCompatibleWithRunner';
+/**
+ * Options which select the ready prompts listed by `ptbk coder list`.
+ *
+ * @public exported from `@promptbook/cli`
+ */
+export type ListCoderPromptsOptions = PriorityFilterInput & {
+    /**
+     * Optional harness, model and Book-agent selection used to omit prompts routed to other runners.
+     */
+    readonly promptRunnerIdentity?: PromptRunnerIdentity;
+};
+/**
+ * Lists ready, fully authored coding prompts in descending priority groups without starting a coding harness.
+ *
+ * @returns The number of prompts printed.
+ * @public exported from `@promptbook/cli`
+ */
+export declare function listCoderPrompts(options?: ListCoderPromptsOptions): Promise<number>;

package/esm/scripts/run-codex-prompts/prompts/buildPromptRunTraceContent.d.ts

@@ -0,0 +1,77 @@
+import moment from 'moment';
+import { type CodexLoginMethod } from '../../../src/book-3.0/codexLoginMethod';
+import type { ThinkingLevel } from '../../../src/cli/cli-commands/coder/ThinkingLevel';
+import type { CoderRunStep } from '../common/CoderRunStep';
+import type { PromptFile } from './types/PromptFile';
+import type { PromptSection } from './types/PromptSection';
+/**
+ * How one prompt round the trace describes has ended.
+ *
+ * A successful round reports the steps it is made of, a failed round reports the error which ended it.
+ */
+export type PromptRunTraceOutcome = {
+    readonly kind: 'succeeded';
+    /**
+     * Ordered steps of the round, each with its own price and duration.
+     */
+    readonly steps: ReadonlyArray<CoderRunStep>;
+    /**
+     * Authentication method the harness reported, when it could be determined.
+     */
+    readonly loginMethod?: CodexLoginMethod;
+} | {
+    readonly kind: 'failed';
+    /**
+     * Error which ended the round after its last retry.
+     */
+    readonly error: unknown;
+};
+/**
+ * Everything one run trace says about the prompt round it describes.
+ */
+export type BuildPromptRunTraceContentOptions = {
+    readonly file: PromptFile;
+    readonly section: PromptSection;
+    /**
+     * Harness which ran the prompt.
+     */
+    readonly runnerName?: string;
+    /**
+     * Model the harness ran the prompt with.
+     */
+    readonly modelName?: string;
+    /**
+     * Reasoning effort the harness ran the prompt with.
+     */
+    readonly thinkingLevel?: ThinkingLevel;
+    /**
+     * Verification command the round ran after each coding attempt, when one is configured.
+     */
+    readonly testCommand?: string;
+    /**
+     * How many coding attempts the round has taken.
+     */
+    readonly attemptCount: number;
+    /**
+     * Moment the round started at.
+     */
+    readonly startedDate: moment.Moment;
+    /**
+     * Moment the round was recorded as finished or failed at.
+     */
+    readonly finishedDate: moment.Moment;
+    readonly outcome: PromptRunTraceOutcome;
+    /**
+     * Raw runtime log of the round, holding the generated shell scripts and everything the harness and the
+     * verification command have written. Empty when the round produced no readable runtime log.
+     */
+    readonly runtimeLog: string;
+};
+/**
+ * Renders the markdown run trace of one finished or failed prompt round.
+ *
+ * The trace pairs the metadata of the round - which harness, model and thinking level ran it, how long each of
+ * its steps took and what it cost - with the untouched runtime log, so a finished round can still be analyzed
+ * after its temporary artifacts are cleaned up.
+ */
+export declare function buildPromptRunTraceContent(options: BuildPromptRunTraceContentOptions): string;

package/esm/scripts/run-codex-prompts/prompts/buildPromptRunTracePath.d.ts

@@ -0,0 +1,10 @@
+import type { PromptFile } from './types/PromptFile';
+import type { PromptSection } from './types/PromptSection';
+/**
+ * Builds the path of the run trace which belongs to one prompt section.
+ *
+ * The trace is stored in the `traces` directory of the very same prompts directory the prompt itself lives in,
+ * and it carries the name of its prompt file. A prompt file holding more than one section appends the section
+ * suffix, exactly like the temporary scripts and the isolation worktrees of the same section do.
+ */
+export declare function buildPromptRunTracePath(file: PromptFile, section: PromptSection): string;

package/esm/scripts/run-codex-prompts/prompts/isPromptCompatibleWithRunner.d.ts

@@ -1,7 +1,7 @@
 import type { PromptFile } from './types/PromptFile';
 import type { PromptSection } from './types/PromptSection';
 /**
- * Names of the harness and model currently selected for a coder run.
+ * Names of the harness, model and Book agent currently selected for a coder run.
  */
 export type PromptRunnerIdentity = {
     /**
@@ -12,16 +12,21 @@ export type PromptRunnerIdentity = {
      * Effective model identifier, for example `gpt-5.5`.
      */
     readonly modelName?: string;
+    /**
+     * Equivalent agent path and name references, including the Book title from its first line.
+     */
+    readonly agentReferences?: ReadonlyArray<string>;
 };
 /**
- * Checks whether a prompt is unrestricted or matches the selected harness/model.
+ * Checks whether a prompt is unrestricted or matches the selected harness, model or Book agent.
  *
- * A prompt status line can contain one or more backtick-delimited model or harness
- * names. Matching is intentionally based on normalized substrings so a token such as
- * `gpt` selects any `gpt-*` model and `opus` selects a `claude-opus-*` model.
+ * A prompt status line can contain one or more backtick-delimited model, harness or agent
+ * references. Matching is intentionally based on normalized substrings so a token such as
+ * `gpt` selects any `gpt-*` model, `developer` selects an agent Book named `developer.book`,
+ * and `opus` selects a `claude-opus-*` model.
  */
 export declare function isPromptCompatibleWithRunner(file: PromptFile, section: PromptSection, promptRunnerIdentity?: PromptRunnerIdentity): boolean;
 /**
- * Extracts model and harness tokens from a prompt status line.
+ * Extracts model, harness and Book-agent tokens from a prompt status line.
  */
 export declare function extractPromptRunnerTokens(statusLine: string): string[];

package/esm/scripts/run-codex-prompts/prompts/loadPromptFiles.d.ts

@@ -1,5 +1,5 @@
 import type { PromptFile } from './types/PromptFile';
 /**
- * Loads and parses prompt files from the prompts directory.
+ * Loads and parses prompt files from the prompts directory, excluding files marked for `ptbk coder` to ignore.
  */
 export declare function loadPromptFiles(promptsDir: string): Promise<PromptFile[]>;

package/esm/scripts/run-codex-prompts/prompts/writePromptRunTrace.d.ts

@@ -0,0 +1,19 @@
+import { type BuildPromptRunTraceContentOptions } from './buildPromptRunTraceContent';
+/**
+ * Everything needed to persist the run trace of one prompt round.
+ *
+ * The runtime log is not passed as text but as the path of the live log the round has been writing into, because
+ * the trace is the only place where that log survives - it is deleted as soon as the round is over.
+ */
+export type WritePromptRunTraceOptions = Omit<BuildPromptRunTraceContentOptions, 'runtimeLog'> & {
+    /**
+     * Path of the temporary live runtime log of the round, when the round has one.
+     */
+    readonly logPath?: string;
+};
+/**
+ * Writes the run trace of one prompt round into the `traces` directory of the prompts directory.
+ *
+ * Returns the path of the written trace so callers can include it in a commit.
+ */
+export declare function writePromptRunTrace(options: WritePromptRunTraceOptions): Promise<string>;

package/esm/scripts/run-codex-prompts/runners/common/buildHarnessAuthenticationError.d.ts

@@ -0,0 +1,20 @@
+import type { PromptRunnerHarnessName } from '../../../../src/cli/cli-commands/common/promptRunnerCliOptions';
+import { AuthenticationError } from '../../../../src/errors/AuthenticationError';
+/**
+ * Options for building the error reported when a harness is not logged in.
+ */
+type BuildHarnessAuthenticationErrorOptions = {
+    /**
+     * Harness which refused to work.
+     */
+    readonly harnessName: PromptRunnerHarnessName;
+    /**
+     * Short reason the harness itself reported, as extracted from its output.
+     */
+    readonly reason: string;
+};
+/**
+ * Builds the branded error which tells the user that the selected harness has to be signed in again.
+ */
+export declare function buildHarnessAuthenticationError(options: BuildHarnessAuthenticationErrorOptions): AuthenticationError;
+export {};

package/esm/scripts/run-codex-prompts/runners/common/createAuthenticationAwarePromptRunner.d.ts

@@ -0,0 +1,11 @@
+import type { PromptRunnerHarnessName } from '../../../../src/cli/cli-commands/common/promptRunnerCliOptions';
+import type { PromptRunner } from '../types/PromptRunner';
+/**
+ * Wraps one prompt runner so a failure caused by a missing or expired harness login is reported as a branded
+ * `AuthenticationError` which tells the user how to sign in again.
+ *
+ * Each harness reports its own failures differently, but all of them report them by failing `runPrompt` with
+ * the raw CLI output as the message. Translating the failure here therefore keeps exactly one place which has
+ * to recognize an unauthenticated harness, for every harness and for every command which runs prompts.
+ */
+export declare function createAuthenticationAwarePromptRunner(runner: PromptRunner, harnessName: PromptRunnerHarnessName): PromptRunner;

package/esm/scripts/run-codex-prompts/runners/common/extractHarnessAuthenticationFailureReason.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Reads the reason why a harness refused to work because it is not logged in, from its raw CLI output.
+ *
+ * Messages the harness reports in machine-readable output are preferred over its raw output lines, so the
+ * reason is the sentence the harness wrote for a human and not the JSON event which transported it.
+ *
+ * @returns One short single-line reason, or `undefined` when the failure was not caused by authentication.
+ */
+export declare function extractHarnessAuthenticationFailureReason(harnessOutput: string): string | undefined;

package/esm/scripts/run-codex-prompts/ui/buildCoderRunUiFrame.d.ts

@@ -11,6 +11,9 @@ export type { CoderRunPauseState };
  * Snapshot consumed by the pure coder-run frame builder.
  */
 export type BuildCoderRunUiFrameOptions = {
+    /**
+     * Number of physical columns currently available in the terminal.
+     */
     readonly terminalWidth: number;
     readonly animationFrame: number;
     readonly animationTimeMs: number;

package/esm/src/book-2.0/book-language-documentation/getSafeCodeBlock.d.ts

@@ -5,6 +5,6 @@
  * @param language - Optional info-string language label.
  * @returns Fenced code block.
  *
- * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ * @private internal utility of `createStandaloneBookLanguageMarkdown` and of the `ptbk coder` run traces
  */
 export declare function getSafeCodeBlock(content: string, language?: string): string;

package/esm/src/book-components/Chat/MockedChat/MockedChat.test.d.ts

@@ -0,0 +1,2 @@
+/** @jest-environment jsdom */
+export {};

package/esm/src/cli/cli-commands/coder/$ensureCoderHarnessGitignoreRules.d.ts

@@ -1,4 +1,5 @@
 import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
+import type { NormalizedQuestionsCliOptions } from '../common/questionsCliOptions';
 /**
  * Offers to add missing project-local ignore rules for the selected coding harness.
  *
@@ -6,4 +7,4 @@ import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
  *
  * @private internal utility of `ptbk coder`
  */
-export declare function $ensureCoderHarnessGitignoreRules(projectPath: string, harnessName: PromptRunnerHarnessName | undefined): Promise<void>;
+export declare function $ensureCoderHarnessGitignoreRules(projectPath: string, harnessName: PromptRunnerHarnessName | undefined, questionsOptions: NormalizedQuestionsCliOptions): Promise<void>;

package/esm/src/cli/cli-commands/coder/agentCliOptions.d.ts

@@ -0,0 +1,21 @@
+import type { Command as Program } from 'commander';
+/**
+ * Commander option bag for an optional Book agent used by coder commands.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export type CoderAgentCliOptions = {
+    readonly agent?: string;
+};
+/**
+ * Description shared by coder commands which accept an agent Book.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare const CODER_AGENT_OPTION_DESCRIPTION = "Path to a .book file used to personalize coding prompts and select agent-specific tasks";
+/**
+ * Registers the shared `--agent` option for coder commands.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare function addCoderAgentOption(command: Program): void;

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

@@ -16,6 +16,12 @@ export declare const PROMPTS_DONE_DIRECTORY_PATH: string;
  * @private internal utility of `ptbk coder`
  */
 export declare const PROMPTS_TEMPLATES_DIRECTORY_PATH: string;
+/**
+ * Relative path to the project-agnostic `common` boilerplate template referenced by the default coder scripts.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare const COMMON_PROMPT_TEMPLATE_FILE_PATH: string;
 /**
  * Initialization statuses used when creating or updating coder configuration artifacts.
  *
@@ -55,25 +61,6 @@ export type CoderPromptTemplateDefinition = {
      */
     readonly isDefaultProjectTemplate: boolean;
 };
-/**
- * Result of ensuring one default coder template file exists inside a project.
- *
- * @private internal utility of `ptbk coder`
- */
-export type EnsuredCoderPromptTemplateFile = {
-    /**
-     * Stable built-in identifier of the template.
-     */
-    readonly id: BuiltInCoderPromptTemplate;
-    /**
-     * Project-relative path of the materialized template file.
-     */
-    readonly relativeFilePath: string;
-    /**
-     * Status describing whether the file had to be created.
-     */
-    readonly status: InitializationStatus;
-};
 /**
  * Fully resolved boilerplate template used by `coder generate-boilerplates`.
  *
@@ -116,11 +103,11 @@ export declare function getDefaultCoderProjectPromptTemplateDefinitions(): Reado
  */
 export declare function getDefaultCoderPromptTemplateDefinition(template: BuiltInCoderPromptTemplate): CoderPromptTemplateDefinition;
 /**
- * Ensures the default project-owned coder template files exist without overwriting user customizations.
+ * Ensures one project-owned coder template file exists without overwriting user customizations.
  *
  * @private internal utility of `ptbk coder`
  */
-export declare function ensureDefaultCoderPromptTemplateFiles(projectPath: string): Promise<ReadonlyArray<EnsuredCoderPromptTemplateFile>>;
+export declare function ensureDefaultCoderPromptTemplateFile(projectPath: string, definition: CoderPromptTemplateDefinition): Promise<InitializationStatus>;
 /**
  * Resolves the template requested by `coder generate-boilerplates`.
  *

package/esm/src/cli/cli-commands/coder/coderReferencedArtifacts.d.ts

@@ -0,0 +1,33 @@
+import type { InitializationStatus } from './boilerplateTemplates';
+/**
+ * Status of one artifact referenced by the default coder scripts.
+ *
+ * `not-referenced` means that no newly added script points at the artifact, so `ptbk coder init` left it alone.
+ *
+ * @private internal utility of `coder init` command
+ */
+export type CoderReferencedArtifactStatus = InitializationStatus | 'not-referenced';
+/**
+ * Result of ensuring one artifact referenced by the default coder scripts.
+ *
+ * @private internal utility of `coder init` command
+ */
+export type EnsuredCoderReferencedArtifact = {
+    /**
+     * Project-relative path of the referenced artifact.
+     */
+    readonly relativeFilePath: string;
+    /**
+     * Status describing whether the artifact had to be created.
+     */
+    readonly status: CoderReferencedArtifactStatus;
+};
+/**
+ * Creates only those referenced artifacts which the freshly added coder scripts point at.
+ *
+ * An artifact of a script which the project already defines is intentionally **not** created - the project-owned
+ * script is kept as is, so it does not reference the default artifact in the first place.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+export declare function ensureCoderReferencedArtifacts(projectPath: string, referencedArtifactPaths: ReadonlySet<string>): Promise<ReadonlyArray<EnsuredCoderReferencedArtifact>>;

package/esm/src/cli/cli-commands/coder/ensureCoderPackageJsonFile.d.ts

@@ -1,7 +1,9 @@
-import type { InitializationStatus } from './boilerplateTemplates';
+import type { MergedStringRecordJsonFile } from './mergeStringRecordJsonFile';
 /**
  * Ensures `package.json` contains the standalone Promptbook coder helper scripts.
  *
+ * Scripts which the project already defines are kept as they are, only missing ones are added.
+ *
  * @private function of `initializeCoderProjectConfiguration`
  */
-export declare function ensureCoderPackageJsonFile(projectPath: string): Promise<InitializationStatus>;
+export declare function ensureCoderPackageJsonFile(projectPath: string): Promise<MergedStringRecordJsonFile>;

package/esm/src/cli/cli-commands/coder/ensureCoderVscodeSettingsFile.d.ts

@@ -2,6 +2,8 @@ import type { InitializationStatus } from './boilerplateTemplates';
 /**
  * Ensures VS Code routes pasted prompt images into `prompts/screenshots`.
  *
+ * Settings which the project already defines are kept as they are, only missing ones are added.
+ *
  * @private function of `initializeCoderProjectConfiguration`
  */
 export declare function ensureCoderVscodeSettingsFile(projectPath: string): Promise<InitializationStatus>;

package/esm/src/cli/cli-commands/coder/ensureDirectory.d.ts

@@ -5,3 +5,9 @@ import type { InitializationStatus } from './boilerplateTemplates';
  * @private function of `initializeCoderProjectConfiguration`
  */
 export declare function ensureDirectory(projectPath: string, relativeDirectoryPath: string): Promise<InitializationStatus>;
+/**
+ * Checks whether a project-relative directory is missing or contains no entries.
+ *
+ * @private internal utility of `coder init` command
+ */
+export declare function isDirectoryEmpty(projectPath: string, relativeDirectoryPath: string): Promise<boolean>;

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

@@ -4,3 +4,9 @@
  * @private internal utility of `coder init` command
  */
 export declare function getDefaultCoderPackageJsonScripts(): Readonly<Record<string, string>>;
+/**
+ * Collects the project-relative artifact paths referenced by the given default coder scripts.
+ *
+ * @private internal utility of `coder init` command
+ */
+export declare function resolveCoderPackageJsonScriptReferencedArtifactPaths(scriptNames: ReadonlyArray<string>): ReadonlySet<string>;

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

@@ -1,4 +1,5 @@
-import type { EnsuredCoderPromptTemplateFile, InitializationStatus } from './boilerplateTemplates';
+import type { InitializationStatus } from './boilerplateTemplates';
+import type { EnsuredCoderReferencedArtifact } from './coderReferencedArtifacts';
 /**
  * Result summary returned after coder configuration initialization.
  *
@@ -8,20 +9,21 @@ export type CoderInitializationSummary = {
     readonly promptsDirectoryStatus: InitializationStatus;
     readonly promptsDoneDirectoryStatus: InitializationStatus;
     readonly promptsTemplatesDirectoryStatus: InitializationStatus;
-    readonly promptTemplateFileStatuses: ReadonlyArray<EnsuredCoderPromptTemplateFile>;
     readonly agentsDirectoryStatus: InitializationStatus;
-    readonly developerAgentFileStatus: InitializationStatus;
-    readonly agentsFileStatus: InitializationStatus;
-    readonly agentCodingFileStatus: InitializationStatus;
     readonly envFileStatus: InitializationStatus;
     readonly gitignoreFileStatus: InitializationStatus;
     readonly packageJsonFileStatus: InitializationStatus;
     readonly vscodeSettingsFileStatus: InitializationStatus;
+    readonly addedPackageJsonScriptNames: ReadonlyArray<string>;
+    readonly referencedArtifactStatuses: ReadonlyArray<EnsuredCoderReferencedArtifact>;
     readonly initializedEnvVariableNames: ReadonlyArray<string>;
 };
 /**
  * Creates or updates all coder configuration artifacts required in the current project.
  *
+ * Nothing the project already owns is ever overwritten - existing scripts, settings and files are kept as they are,
+ * and the artifacts they would reference are created only together with the scripts which actually reference them.
+ *
  * @private internal utility of `coder init` command
  */
 export declare function initializeCoderProjectConfiguration(projectPath: string): Promise<CoderInitializationSummary>;

package/esm/src/cli/cli-commands/coder/list.d.ts

@@ -0,0 +1,10 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `coder list` command for Promptbook CLI utilities.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeCoderListCommand(program: Program): $side_effect;

package/esm/src/cli/cli-commands/coder/mergeStringRecordJsonFile.d.ts

@@ -9,10 +9,28 @@ type MergeStringRecordJsonFileOptions = {
     readonly nextEntries: Readonly<Record<string, string>>;
     readonly ensureParentDirectoryPath?: string;
 };
+/**
+ * Result of one additive string-record merge into a JSON file.
+ *
+ * @private internal utility of `coder init` command
+ */
+export type MergedStringRecordJsonFile = {
+    /**
+     * Status describing whether the JSON file had to be created or updated.
+     */
+    readonly status: InitializationStatus;
+    /**
+     * Keys which were missing in the JSON file and therefore added by the merge.
+     */
+    readonly addedEntryKeys: ReadonlyArray<string>;
+};
 /**
  * Ensures one JSON object field contains the provided string-record entries.
  *
+ * Entries which the project already defines are **never** overridden - only missing keys are added,
+ * so hand-tuned scripts and settings survive every repeated `ptbk coder init`.
+ *
  * @private function of `initializeCoderProjectConfiguration`
  */
-export declare function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldPath, nextEntries, ensureParentDirectoryPath, }: MergeStringRecordJsonFileOptions): Promise<InitializationStatus>;
+export declare function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldPath, nextEntries, ensureParentDirectoryPath, }: MergeStringRecordJsonFileOptions): Promise<MergedStringRecordJsonFile>;
 export {};

package/esm/src/cli/cli-commands/coder/printCoderRunFailure.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Prints why a coder run has ended to the terminal.
+ *
+ * @private internal utility of `coder run` and `coder server` commands
+ */
+export declare function printCoderRunFailure(error: Error): void;

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

@@ -8,6 +8,7 @@ import type { $side_effect } from '../../utils/organization/$side_effect';
  * - 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
+ * - list: List ready prompts in priority order without running them
  * - run: Run coding prompts with AI agents
  * - ping: Test one harness and model with a tiny dummy prompt
  * - verify: Verify completed prompts

package/esm/src/cli/cli-commands/common/$askForConfirmation.d.ts

@@ -1,9 +1,11 @@
+import type { NormalizedQuestionsCliOptions } from './questionsCliOptions';
 /**
  * Asks the user in the terminal to confirm one optional change.
  *
  * Note: `$` is used to indicate that this function is not a pure function - it reads the answer from stdin.
  *
- * @returns `true` when the user confirms, `false` when the user declines or the terminal is not interactive.
+ * @returns `true` when the user confirms, `false` when the user declines, the terminal is not interactive
+ *          or the questions are disabled by `--no-questions`.
  * @private internal utility of `promptbookCli`
  */
-export declare function $askForConfirmation(question: string): Promise<boolean>;
+export declare function $askForConfirmation(question: string, { isAskingQuestionsEnabled }: NormalizedQuestionsCliOptions): Promise<boolean>;

package/esm/src/cli/cli-commands/common/$askForConfirmation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/cli/cli-commands/common/disk-space/$assertSufficientFreeDiskSpace.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Refuses to start one `ptbk coder` command when the disk which hosts the project is nearly full.
+ *
+ * A run which starts without enough free disk space fails somewhere in the middle, after the coding agent has
+ * already rewritten a part of the project, so it is stopped before it writes anything at all.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads the state of the filesystem
+ *
+ * @throws {LimitReachedError} when there is not enough free disk space left to start
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $assertSufficientFreeDiskSpace(inspectedPath: string): Promise<void>;

package/esm/src/cli/cli-commands/common/disk-space/$assertSufficientFreeDiskSpace.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/cli/cli-commands/common/disk-space/$readFreeDiskSpaceStatus.d.ts

@@ -0,0 +1,11 @@
+import type { FreeDiskSpaceStatus } from './FreeDiskSpaceStatus';
+/**
+ * Measures the free disk space on the filesystem which hosts the given path.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads the state of the filesystem
+ *
+ * @returns the measurement, or `null` when the filesystem can not be measured, for example on a platform which
+ *          does not report filesystem statistics - a run is never stopped by a measurement which could not be taken
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $readFreeDiskSpaceStatus(inspectedPath: string): Promise<FreeDiskSpaceStatus | null>;

package/esm/src/cli/cli-commands/common/disk-space/$readFreeDiskSpaceStatus.test.d.ts

@@ -0,0 +1 @@
+export {};