@promptbook/markdown-utils 0.114.0-4 → 0.114.0-41

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

@@ -1,4 +1,22 @@
 import type { TODO_any } from '../../../utils/organization/TODO_any';
+/**
+ * Tool name of one scheduled wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export declare 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 declare 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 declare const CANCEL_TIMEOUT_TOOL_CALL_NAME = "cancel_timeout";
 /**
  * Action performed by timeout tools.
  *
@@ -140,4 +158,16 @@ export declare function buildTimeoutToolPrimarySentence(presentation: TimeoutToo
  * @private internal utility of `<Chat/>`
  */
 export declare function buildTimeoutToolScheduleSentence(presentation: TimeoutToolCallPresentation, translations?: TimeoutToolCallTranslations): string | null;
+/**
+ * Converts timeout duration into natural language sentence fragments.
+ *
+ * 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
+ */
+export declare function formatTimeoutDurationHuman(milliseconds: number): string;
 export {};

package/umd/src/cli/$initializePromptbookCliProgram.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from 'commander';
+/**
+ * Registers the CLI commands on a fresh Commander program without parsing arguments or running an action.
+ * Tests can configure output and exit handling before registration, so subcommands inherit those settings.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $initializePromptbookCliProgram(program: Command): void;

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

@@ -0,0 +1,10 @@
+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.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it may ask the user and update `.gitignore`.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare function $ensureCoderHarnessGitignoreRules(projectPath: string, harnessName: PromptRunnerHarnessName | undefined, questionsOptions: NormalizedQuestionsCliOptions): Promise<void>;

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

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

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

@@ -0,0 +1,28 @@
+/**
+ * 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 declare const GIT_CHANGES_MODE_VALUES: readonly ["fail", "ignore", "continue"];
+/**
+ * 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 declare const DEFAULT_GIT_CHANGES_MODE: GitChangesMode;
+/**
+ * Checks whether a value is a supported `--git-changes` mode.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export declare function isGitChangesMode(value: string): value is GitChangesMode;

package/umd/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/umd/src/cli/cli-commands/coder/boilerplateCount.d.ts

@@ -12,7 +12,7 @@ export type BoilerplateCount = {
      * 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 `---` and tagged with its own fresh emoji tag.
+     *       coding task separated by `---`, with all prompts in the file sharing its fresh emoji tag.
      */
     readonly promptsPerFileCount: number;
 };

package/umd/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/umd/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/umd/src/cli/cli-commands/coder/ensureCoderGitignoreFile.d.ts

@@ -1,7 +1,20 @@
+import { type PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
 import type { InitializationStatus } from './boilerplateTemplates';
 /**
- * Ensures `.gitignore` contains the standalone Promptbook temp entry.
+ * Ensures `.gitignore` contains Promptbook Coder's local artifacts and every supported harness's local artifacts.
  *
  * @private function of `initializeCoderProjectConfiguration`
  */
 export declare function ensureCoderGitignoreFile(projectPath: string): Promise<InitializationStatus>;
+/**
+ * Lists missing project-local ignore rules for the selected harnesses.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare function getMissingCoderHarnessGitignoreRules(projectPath: string, harnessNames: ReadonlyArray<PromptRunnerHarnessName>): Promise<ReadonlyArray<string>>;
+/**
+ * Adds the given Promptbook Coder rules to a project's `.gitignore` file.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare function ensureCoderGitignoreRules(projectPath: string, rules: ReadonlyArray<string>): Promise<InitializationStatus>;

package/umd/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/umd/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/umd/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/umd/src/cli/cli-commands/coder/generate-boilerplates.d.ts

@@ -10,7 +10,7 @@ import type { BoilerplateCount } from './boilerplateCount';
  */
 export declare function $initializeCoderGenerateBoilerplatesCommand(program: Program): $side_effect;
 /**
- * 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
  */

package/umd/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/umd/src/cli/cli-commands/coder/init.test.d.ts

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

package/umd/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,22 @@ 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 adamAgentFileStatus: 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/umd/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/umd/src/cli/cli-commands/coder/list.test.d.ts

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

package/umd/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/umd/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/umd/src/cli/cli-commands/coder/server.test.d.ts

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

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

@@ -1,4 +1,4 @@
-import type { Command as Program } from 'commander';
+import { Command as Program } from 'commander';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 /**
  * Initializes `coder verify` command for Promptbook CLI utilities

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

@@ -12,3 +12,15 @@ export declare const DEFAULT_WAIT_AFTER_ERROR_MS: number;
  * @private internal utility of `ptbk coder` wait handling
  */
 export declare function parseOptionalWaitDuration(value: string | undefined, defaultMs: number): number;
+/**
+ * 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 declare function parseOptionalPeriodDuration(optionName: string, value: string | undefined): number | undefined;

package/umd/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/umd/src/cli/cli-commands/common/$askForConfirmation.d.ts

@@ -0,0 +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, the terminal is not interactive
+ *          or the questions are disabled by `--no-questions`.
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $askForConfirmation(question: string, { isAskingQuestionsEnabled }: NormalizedQuestionsCliOptions): Promise<boolean>;

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

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

package/umd/src/cli/cli-commands/common/LocalAgentBookCollection.d.ts

@@ -0,0 +1,46 @@
+import type { string_book } from '../../../book-2.0/agent-source/string_book';
+import type { TeammateProfile } from '../../../book-2.0/agent-source/TeammateProfileResolver';
+/**
+ * A book's source and identity, retaining its location for nested relative references.
+ *
+ * @private internal type of CLI agent resolution
+ */
+export type LocalAgentBook = {
+    readonly url: string;
+    readonly filePath?: string;
+    readonly source: string_book;
+    readonly profile: TeammateProfile;
+};
+/**
+ * Reads repository books and indexes their first-line names for CLI reference resolution.
+ *
+ * @private internal utility of CLI agent resolution
+ */
+export declare class LocalAgentBookCollection {
+    private readonly agentDirectoryPath;
+    private readonly currentWorkingDirectory;
+    private readonly booksByUrl;
+    private readonly booksByName;
+    /** Stable default ancestor selected from the initial repository scan. */
+    private adamAgentUrl;
+    /** Files initialized by this collection, for the coder's normal commit handling. */
+    readonly createdAgentBookPaths: string[];
+    /** Creates a collection rooted at the primary book's directory. */
+    constructor(agentDirectoryPath: string, currentWorkingDirectory: string);
+    /** Discovers nested books, including the hidden `.core` directory. */
+    initialize(): Promise<void>;
+    /** Identifies the default ancestor without creating an unused book for FROM null/void. */
+    getAdamAgentUrl(): string;
+    /** Resolves a unique first-line name, refusing ambiguous matches. */
+    findByName(name: string): LocalAgentBook;
+    /** Resolves a name, a path relative to its declaring book, or a path relative to the CLI cwd. */
+    resolveReference(reference: string, declaringBook: LocalAgentBook): Promise<string>;
+    /** Reads a local book once, canonicalizing symlinks so aliases cannot bypass cycle detection. */
+    readBook(filePath: string): Promise<LocalAgentBook>;
+    /** Loads a referenced remote book, while keeping local identifiers entirely inside the collection. */
+    getBook(url: string): Promise<LocalAgentBook>;
+    /** Adds a book under its normalized first-line name and preserves the display name for TEAM. */
+    private registerBook;
+    /** Walks real directories in deterministic order without following directory symlink loops. */
+    private readDirectory;
+}

package/umd/src/cli/cli-commands/common/createLocalAgentReferenceResolver.d.ts

@@ -0,0 +1,8 @@
+import type { AgentReferenceResolver } from '../../../book-2.0/agent-source/AgentReferenceResolver';
+import type { LocalAgentBook, LocalAgentBookCollection } from './LocalAgentBookCollection';
+/**
+ * Creates a resolver scoped to the book which declares each reference.
+ *
+ * @private internal utility of CLI agent resolution
+ */
+export declare function createLocalAgentReferenceResolver(collection: LocalAgentBookCollection, declaringBook: LocalAgentBook): AgentReferenceResolver;

package/umd/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/umd/src/cli/cli-commands/common/disk-space/$assertSufficientFreeDiskSpace.test.d.ts

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

package/umd/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/umd/src/cli/cli-commands/common/disk-space/$readFreeDiskSpaceStatus.test.d.ts

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

package/umd/src/cli/cli-commands/common/disk-space/FreeDiskSpaceStatus.d.ts

@@ -0,0 +1,33 @@
+/**
+ * How much free disk space is left, measured against the `ptbk coder` free disk space limits.
+ *
+ * - `sufficient` - there is enough free disk space to start a run and to keep it running
+ * - `low` - there is not enough free disk space to start a new run
+ * - `critical` - there is not enough free disk space to keep a started run going
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type FreeDiskSpaceLevel = 'sufficient' | 'low' | 'critical';
+/**
+ * One measurement of the free disk space on the filesystem which hosts the inspected path.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type FreeDiskSpaceStatus = {
+    /**
+     * Path whose filesystem was measured.
+     */
+    readonly inspectedPath: string;
+    /**
+     * Bytes which are still available to the current user on that filesystem.
+     */
+    readonly availableBytes: number;
+    /**
+     * Total size of that filesystem in bytes.
+     */
+    readonly totalBytes: number;
+    /**
+     * Severity of the measured free disk space.
+     */
+    readonly level: FreeDiskSpaceLevel;
+};

package/umd/src/cli/cli-commands/common/disk-space/formatFreeDiskSpaceBytes.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Writes one byte count as a compact human-readable amount of disk space, for example `812 MB` or `1.5 GB`.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function formatFreeDiskSpaceBytes(bytes: number): string;

package/umd/src/cli/cli-commands/common/disk-space/formatFreeDiskSpaceBytes.test.d.ts

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

package/umd/src/cli/cli-commands/common/disk-space/formatLowFreeDiskSpaceWarning.d.ts

@@ -0,0 +1,10 @@
+import type { FreeDiskSpaceStatus } from './FreeDiskSpaceStatus';
+/**
+ * Writes the shared warning which explains one low free disk space measurement and how to get out of it.
+ *
+ * The very same wording is used by the check which refuses to start a run and by the check which pauses
+ * a run that ran out of disk space while it was working.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function formatLowFreeDiskSpaceWarning(freeDiskSpaceStatus: FreeDiskSpaceStatus): string;

package/umd/src/cli/cli-commands/common/disk-space/freeDiskSpaceConstants.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Free disk space below which `ptbk coder` refuses to start a new run.
+ *
+ * A coding round writes prompt and log artifacts, lets the harness rewrite the project, may install npm packages,
+ * may create a git worktree for `--isolate` and usually runs a build, so a run started with less than this
+ * would very likely die somewhere in the middle with a filesystem error.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const LOW_FREE_DISK_SPACE_BYTES: number;
+/**
+ * Free disk space below which a started `ptbk coder` run stops at its next checkpoint and waits until space is freed.
+ *
+ * This limit is lower than `LOW_FREE_DISK_SPACE_BYTES`, because interrupting a run which is already in progress
+ * is more expensive than not starting one at all.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const CRITICALLY_LOW_FREE_DISK_SPACE_BYTES: number;
+/**
+ * How long one free disk space measurement is reused before the filesystem is measured again during a run.
+ *
+ * Pause checkpoints are passed very often - for example on every tick of a timed wait - so without this
+ * interval the filesystem would be measured many times per second.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const FREE_DISK_SPACE_RECHECK_INTERVAL_MS: number;

package/umd/src/cli/cli-commands/common/disk-space/resolveFreeDiskSpaceLevel.d.ts

@@ -0,0 +1,7 @@
+import type { FreeDiskSpaceLevel } from './FreeDiskSpaceStatus';
+/**
+ * Classifies one measured amount of free disk space against the `ptbk coder` free disk space limits.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function resolveFreeDiskSpaceLevel(availableBytes: number): FreeDiskSpaceLevel;

package/umd/src/cli/cli-commands/common/disk-space/resolveFreeDiskSpaceLevel.test.d.ts

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

package/umd/src/cli/cli-commands/common/ensureAdamAgentBook.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Adam's location relative to a directory of local agents.
+ *
+ * @private internal constant of CLI agent initialization
+ */
+export declare const ADAM_AGENT_BOOK_RELATIVE_PATH = ".core/adam.book";
+/**
+ * Creates the same Adam book used by the Agent Server without overwriting a project-owned book.
+ *
+ * @private internal utility of CLI agent initialization
+ */
+export declare function ensureAdamAgentBook(agentDirectoryPath: string): Promise<'created' | 'unchanged'>;