@promptbook/cli 0.114.0-33 → 0.114.0-35

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/harness/$applyHarnessInstallationStatus.d.ts

@@ -1,3 +1,4 @@
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
 /**
  * Reports one detected harness installation status and offers to install or update the harness.
@@ -6,4 +7,4 @@ import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
  *
  * @private internal utility of `promptbookCli`
  */
-export declare function $applyHarnessInstallationStatus(status: HarnessInstallationStatus): Promise<void>;
+export declare function $applyHarnessInstallationStatus(status: HarnessInstallationStatus, questionsOptions: NormalizedQuestionsCliOptions): Promise<void>;

package/umd/src/cli/cli-commands/common/harness/$ensureHarnessInstallations.d.ts

@@ -1,6 +1,7 @@
 import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 /**
- * Checks that every given CLI coding harness is installed globally and, when enabled, up to date.
+ * Checks that every given CLI coding harness is installed globally and, when the questions are enabled, up to date.
  * Offers to install missing harnesses and update outdated ones.
  *
  * Harness names which are `undefined`, for example when no `--harness` is selected in a dry run,
@@ -10,4 +11,4 @@ import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
  *
  * @private internal utility of `promptbookCli`
  */
-export declare function $ensureHarnessInstallations(harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>, isHarnessUpdateCheckEnabled?: boolean): Promise<void>;
+export declare function $ensureHarnessInstallations(harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>, questionsOptions: NormalizedQuestionsCliOptions): Promise<void>;

package/umd/src/cli/cli-commands/common/harness/HarnessDefinition.d.ts

@@ -19,6 +19,28 @@ export type HarnessStandaloneInstallation = {
      */
     readonly updateCommand: string;
 };
+/**
+ * Description of how the user signs in to one CLI coding harness again.
+ *
+ * Every harness refuses to work once its login is missing or its session has expired, and each of them is
+ * signed in differently - some have a dedicated login command, others sign in from their own interactive UI.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessAuthenticationMethod = {
+    /**
+     * Command which starts the sign-in flow of the harness.
+     */
+    readonly command: string;
+    /**
+     * Step which finishes the sign-in inside the started command.
+     *
+     * Harnesses which sign in from their own interactive user interface leave the user in that interface, so
+     * naming just the command would not be enough to get them signed in. Harnesses with a dedicated login
+     * command leave this undefined.
+     */
+    readonly interactiveStep?: string;
+};
 /**
  * Static description of one supported CLI coding harness.
  *
@@ -49,6 +71,10 @@ export type HarnessDefinition = {
      * Project-local files or directories which this harness can create and which should not be committed.
      */
     readonly projectGitignoreRules: ReadonlyArray<string>;
+    /**
+     * How the user signs in to this harness again after its login is missing or has expired.
+     */
+    readonly authenticationMethod: HarnessAuthenticationMethod;
     /**
      * How a standalone installation of this harness is recognized and updated.
      *

package/umd/src/cli/cli-commands/common/npm/$askForNpmPackageInstallationApproval.d.ts

@@ -1,9 +1,11 @@
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 /**
  * Asks the user in the terminal whether an npm package should be installed or updated now.
  *
  * 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 $askForNpmPackageInstallationApproval(question: string): Promise<boolean>;
+export declare function $askForNpmPackageInstallationApproval(question: string, questionsOptions: NormalizedQuestionsCliOptions): Promise<boolean>;

package/umd/src/cli/cli-commands/common/promptbook-cli/$ensurePromptbookCliInstallations.d.ts

@@ -1,3 +1,4 @@
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 /**
  * Checks local and global Promptbook CLI installations before an interactive coder run and offers to update them.
  *
@@ -11,4 +12,4 @@
  * @returns `true` when at least one installation was updated and the current coder run should stop
  * @private internal utility of `promptbookCli`
  */
-export declare function $ensurePromptbookCliInstallations(): Promise<boolean>;
+export declare function $ensurePromptbookCliInstallations(questionsOptions: NormalizedQuestionsCliOptions): Promise<boolean>;

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

@@ -0,0 +1,45 @@
+import type { Command as Program } from 'commander';
+/**
+ * Commander option bag for opting out of every interactive question.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type QuestionsCliOptions = {
+    readonly questions: boolean;
+};
+/**
+ * Normalized interactive-questions option shared by every `ptbk coder` command which can ask something.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type NormalizedQuestionsCliOptions = {
+    readonly isAskingQuestionsEnabled: boolean;
+};
+/**
+ * Description block shared by the `ptbk coder` commands which can ask interactive questions.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const QUESTIONS_DESCRIPTION: string;
+/**
+ * Registers the shared `--no-questions` option on a `ptbk coder` command which can ask interactive questions.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function addQuestionsOption(command: Program): void;
+/**
+ * Converts the Commander questions flag into the normalized interactive-questions option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function normalizeQuestionsCliOptions(cliOptions: QuestionsCliOptions): NormalizedQuestionsCliOptions;
+/**
+ * Asserts that a command which waits for a user confirmation before each prompt is allowed to ask for it.
+ *
+ * @throws {NotAllowed} when `--no-auto` is combined with `--no-questions`
+ * @private internal utility of `promptbookCli`
+ */
+export declare function assertUserConfirmationIsAllowed(options: {
+    readonly isAskingQuestionsEnabled: boolean;
+    readonly isWaitingForUser: boolean;
+}): void;

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

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

package/umd/src/cli/common/$deprecateCliCommand.d.ts

@@ -3,6 +3,9 @@ import type { $side_effect } from '../../utils/organization/$side_effect';
 /**
  * Marks one CLI command as deprecated while keeping it available for existing callers.
  *
+ * Deprecated commands are not advertised anymore - they are hidden from the list of commands in the help of their
+ * parent command, they warn when they are used and they explain the deprecation in their own help.
+ *
  * @private utility of CLI
  */
 export declare function $deprecateCliCommand(command: Command, deprecationMessage: string): $side_effect;

package/umd/src/cli/common/$hideCliCommandFromHelp.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from 'commander';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+/**
+ * Keeps one already registered CLI command out of the help of its parent command while the command itself stays
+ * fully usable - it can still be run, it still has its own help and it is still reachable through `ptbk help <command>`.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it changes how the CLI renders its help
+ *
+ * @private utility of CLI
+ */
+export declare function $hideCliCommandFromHelp(command: Command): $side_effect;

package/umd/src/cli/common/$hideCliCommandFromHelp.test.d.ts

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

package/umd/src/cli/common/$requireCliSubcommand.d.ts

@@ -0,0 +1,18 @@
+import type { Command } from 'commander';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+/**
+ * Makes one CLI command which only groups subcommands ask for a subcommand instead of doing anything on its own.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers an action in the CLI
+ *
+ * @private utility of CLI
+ */
+export declare function $requireCliSubcommand(command: Command): $side_effect;
+/**
+ * Asks for a subcommand of one CLI command, prints its help and exits the process.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it writes to the console and exits the process
+ *
+ * @private utility of CLI
+ */
+export declare function $reportMissingCliSubcommand(command: Command): never;

package/umd/src/cli/common/$requireCliSubcommand.test.d.ts

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

package/umd/src/llm-providers/vercel/VercelExecutionToolsOptions.d.ts

@@ -17,7 +17,10 @@ export type VercelExecutionToolsOptions = CommonToolsOptions & Pick<LlmExecution
      */
     readonly availableModels: ReadonlyArray<AvailableModel>;
     /**
-     * Additional settings for chat models when calling `vercelProvider.chat('model-name', settings)`
+     * Additional settings for chat models, for example `temperature` or `providerOptions`
+     *
+     * Note: Since Vercel AI SDK v5 these settings belong to the model call, not to
+     *       `vercelProvider.chat('model-name')` which takes just the model name
      */
-    readonly additionalChatSettings?: Partial<Parameters<VercelProvider['chat']>[1]>;
+    readonly additionalChatSettings?: Partial<Omit<Parameters<ReturnType<VercelProvider['chat']>['doGenerate']>[0], 'prompt'>>;
 };

package/umd/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.114.0-32`).
+ * It follows semantic versioning (e.g., `0.114.0-34`).
  *
  * @generated
  */

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

@@ -1,13 +0,0 @@
-import { string_markdown } from '../../../types/typeAliases';
-/**
- * Relative path to the Promptbook Coder quick-reference file initialized in project roots.
- *
- * @private internal utility of `ptbk coder`
- */
-export declare const AGENT_CODING_FILE_PATH = "AGENT_CODING.md";
-/**
- * Returns the default coder `AGENT_CODING.md` quick-reference content.
- *
- * @private internal utility of `ptbk coder`
- */
-export declare function getDefaultCoderAgentCodingFileContent(): string_markdown;

package/esm/src/cli/cli-commands/common/harnessUpdateCliOptions.d.ts

@@ -1,29 +0,0 @@
-import type { Command as Program } from 'commander';
-/**
- * Commander option bag for opting out of automatic coding-harness update checks.
- *
- * @private internal utility of `promptbookCli`
- */
-export type HarnessUpdateCliOptions = {
-    readonly harnessUpdate: boolean;
-};
-/**
- * Normalized automatic coding-harness update-check option.
- *
- * @private internal utility of `promptbookCli`
- */
-export type NormalizedHarnessUpdateCliOptions = {
-    readonly isHarnessUpdateCheckEnabled: boolean;
-};
-/**
- * Registers the shared `--no-harness-update` option on a `ptbk coder` command that uses a coding harness.
- *
- * @private internal utility of `promptbookCli`
- */
-export declare function addHarnessUpdateOption(command: Program): void;
-/**
- * Converts the Commander harness-update flag into the normalized harness-check option.
- *
- * @private internal utility of `promptbookCli`
- */
-export declare function normalizeHarnessUpdateCliOptions(cliOptions: HarnessUpdateCliOptions): NormalizedHarnessUpdateCliOptions;

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

@@ -1,25 +0,0 @@
-import { spaceTrim } from 'spacetrim';
-import { string_markdown } from '../../../types/typeAliases';
-
-/**
- * Relative path to the Promptbook Coder quick-reference file initialized in project roots.
- *
- * @private internal utility of `ptbk coder`
- */
-export const AGENT_CODING_FILE_PATH = 'AGENT_CODING.md';
-
-/**
- * Returns the default coder `AGENT_CODING.md` quick-reference content.
- *
- * @private internal utility of `ptbk coder`
- */
-export function getDefaultCoderAgentCodingFileContent(): string_markdown {
-    return spaceTrim(`
-        # ✨ Promptbook Coder agent coding
-
-        This project is using [Promptbook Coder](https://coder.ptbk.io) or run \`ptbk coder\`!
-    `);
-}
-
-// Note: [🟡] Code for coder AGENT_CODING file boilerplate [agentCodingFile](src/cli/cli-commands/coder/agentCodingFile.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/harnessUpdateCliOptions.ts

@@ -1,46 +0,0 @@
-import type {
-    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
-} from 'commander';
-
-/**
- * Commander option bag for opting out of automatic coding-harness update checks.
- *
- * @private internal utility of `promptbookCli`
- */
-export type HarnessUpdateCliOptions = {
-    readonly harnessUpdate: boolean;
-};
-
-/**
- * Normalized automatic coding-harness update-check option.
- *
- * @private internal utility of `promptbookCli`
- */
-export type NormalizedHarnessUpdateCliOptions = {
-    readonly isHarnessUpdateCheckEnabled: boolean;
-};
-
-/**
- * Registers the shared `--no-harness-update` option on a `ptbk coder` command that uses a coding harness.
- *
- * @private internal utility of `promptbookCli`
- */
-export function addHarnessUpdateOption(command: Program): void {
-    command.option('--no-harness-update', 'Skip checking whether the installed coding harnesses are up to date');
-}
-
-/**
- * Converts the Commander harness-update flag into the normalized harness-check option.
- *
- * @private internal utility of `promptbookCli`
- */
-export function normalizeHarnessUpdateCliOptions(
-    cliOptions: HarnessUpdateCliOptions,
-): NormalizedHarnessUpdateCliOptions {
-    return {
-        isHarnessUpdateCheckEnabled: cliOptions.harnessUpdate,
-    };
-}
-
-// Note: [🟡] Code for CLI harness update options [harnessUpdateCliOptions](src/cli/cli-commands/common/harnessUpdateCliOptions.ts) should never be published outside of `@promptbook/cli`
-// Note: [💞] Ignore a discrepancy between file name and exported helper names

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

@@ -1,13 +0,0 @@
-import { string_markdown } from '../../../types/typeAliases';
-/**
- * Relative path to the Promptbook Coder quick-reference file initialized in project roots.
- *
- * @private internal utility of `ptbk coder`
- */
-export declare const AGENT_CODING_FILE_PATH = "AGENT_CODING.md";
-/**
- * Returns the default coder `AGENT_CODING.md` quick-reference content.
- *
- * @private internal utility of `ptbk coder`
- */
-export declare function getDefaultCoderAgentCodingFileContent(): string_markdown;

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

@@ -1,29 +0,0 @@
-import type { Command as Program } from 'commander';
-/**
- * Commander option bag for opting out of automatic coding-harness update checks.
- *
- * @private internal utility of `promptbookCli`
- */
-export type HarnessUpdateCliOptions = {
-    readonly harnessUpdate: boolean;
-};
-/**
- * Normalized automatic coding-harness update-check option.
- *
- * @private internal utility of `promptbookCli`
- */
-export type NormalizedHarnessUpdateCliOptions = {
-    readonly isHarnessUpdateCheckEnabled: boolean;
-};
-/**
- * Registers the shared `--no-harness-update` option on a `ptbk coder` command that uses a coding harness.
- *
- * @private internal utility of `promptbookCli`
- */
-export declare function addHarnessUpdateOption(command: Program): void;
-/**
- * Converts the Commander harness-update flag into the normalized harness-check option.
- *
- * @private internal utility of `promptbookCli`
- */
-export declare function normalizeHarnessUpdateCliOptions(cliOptions: HarnessUpdateCliOptions): NormalizedHarnessUpdateCliOptions;