@promptbook/cli 0.114.0-33 → 0.114.0-34

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

@@ -0,0 +1,37 @@
+import { statfs } from 'fs/promises';
+import type { FreeDiskSpaceStatus } from './FreeDiskSpaceStatus';
+import { resolveFreeDiskSpaceLevel } from './resolveFreeDiskSpaceLevel';
+
+/**
+ * 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 async function $readFreeDiskSpaceStatus(inspectedPath: string): Promise<FreeDiskSpaceStatus | null> {
+    try {
+        const fileSystemStats = await statfs(inspectedPath);
+        const blockSizeBytes = fileSystemStats.bsize;
+        const availableBytes = fileSystemStats.bavail * blockSizeBytes;
+        const totalBytes = fileSystemStats.blocks * blockSizeBytes;
+
+        if (!Number.isFinite(availableBytes) || availableBytes < 0) {
+            return null;
+        }
+
+        return {
+            inspectedPath,
+            availableBytes,
+            totalBytes,
+            level: resolveFreeDiskSpaceLevel(availableBytes),
+        };
+    } catch {
+        // Note: A path or a platform which can not report its free disk space must not stop `ptbk coder` from running
+        return null;
+    }
+}
+
+// Note: [🟡] Code for CLI free disk space handling [$readFreeDiskSpaceStatus](src/cli/cli-commands/common/disk-space/$readFreeDiskSpaceStatus.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,39 @@
+/**
+ * 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;
+};
+
+// Note: [🟡] Code for CLI free disk space handling [FreeDiskSpaceStatus](src/cli/cli-commands/common/disk-space/FreeDiskSpaceStatus.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,26 @@
+/**
+ * Byte units used when one amount of disk space is written for a human.
+ */
+const FREE_DISK_SPACE_BYTE_UNITS = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'] as const;
+
+/**
+ * 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 function formatFreeDiskSpaceBytes(bytes: number): string {
+    if (!Number.isFinite(bytes) || bytes <= 0) {
+        return '0 B';
+    }
+
+    const unitIndex = Math.min(FREE_DISK_SPACE_BYTE_UNITS.length - 1, Math.floor(Math.log(bytes) / Math.log(1024)));
+    const value = bytes / Math.pow(1024, unitIndex);
+    // Note: One decimal place only matters for small values, `476 GB` is more readable than `476.3 GB`
+    const decimalPlaceCount = value >= 10 || unitIndex === 0 ? 0 : 1;
+    // Note: An empty decimal place only adds noise, `2 GB` is more readable than `2.0 GB`
+    const displayedValue = value.toFixed(decimalPlaceCount).replace(/\.0$/, '');
+
+    return `${displayedValue} ${FREE_DISK_SPACE_BYTE_UNITS[unitIndex]}`;
+}
+
+// Note: [🟡] Code for CLI free disk space handling [formatFreeDiskSpaceBytes](src/cli/cli-commands/common/disk-space/formatFreeDiskSpaceBytes.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,33 @@
+import { spaceTrim } from 'spacetrim';
+import type { FreeDiskSpaceStatus } from './FreeDiskSpaceStatus';
+import { formatFreeDiskSpaceBytes } from './formatFreeDiskSpaceBytes';
+import { CRITICALLY_LOW_FREE_DISK_SPACE_BYTES, LOW_FREE_DISK_SPACE_BYTES } from './freeDiskSpaceConstants';
+
+/**
+ * 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 function formatLowFreeDiskSpaceWarning(freeDiskSpaceStatus: FreeDiskSpaceStatus): string {
+    const { inspectedPath } = freeDiskSpaceStatus;
+    const availableSpace = formatFreeDiskSpaceBytes(freeDiskSpaceStatus.availableBytes);
+    const totalSpace = formatFreeDiskSpaceBytes(freeDiskSpaceStatus.totalBytes);
+    const requiredSpaceToStart = formatFreeDiskSpaceBytes(LOW_FREE_DISK_SPACE_BYTES);
+    const requiredSpaceToContinue = formatFreeDiskSpaceBytes(CRITICALLY_LOW_FREE_DISK_SPACE_BYTES);
+
+    return spaceTrim(`
+        Only **${availableSpace}** of ${totalSpace} is left on the disk which hosts \`${inspectedPath}\`.
+
+        **\`ptbk coder\` needs at least ${requiredSpaceToStart} of free disk space to start a run and at least ${requiredSpaceToContinue} to keep one running.**
+
+        Actionable hints:
+        - Free up disk space on the drive which hosts \`${inspectedPath}\`.
+        - Remove build artifacts, package caches and \`node_modules\` folders of projects you are not working on.
+        - Remove the temporary worktrees which earlier \`--isolate\` runs left behind.
+    `);
+}
+
+// Note: [🟡] Code for CLI free disk space handling [formatLowFreeDiskSpaceWarning](src/cli/cli-commands/common/disk-space/formatLowFreeDiskSpaceWarning.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,33 @@
+/**
+ * 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 const LOW_FREE_DISK_SPACE_BYTES = 2 * 1024 * 1024 * 1024;
+
+/**
+ * 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 const CRITICALLY_LOW_FREE_DISK_SPACE_BYTES = 1 * 1024 * 1024 * 1024;
+
+/**
+ * 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 const FREE_DISK_SPACE_RECHECK_INTERVAL_MS = 60 * 1000;
+
+// Note: [🟡] Code for CLI free disk space handling [freeDiskSpaceConstants](src/cli/cli-commands/common/disk-space/freeDiskSpaceConstants.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and entity name

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

@@ -0,0 +1,21 @@
+import type { FreeDiskSpaceLevel } from './FreeDiskSpaceStatus';
+import { CRITICALLY_LOW_FREE_DISK_SPACE_BYTES, LOW_FREE_DISK_SPACE_BYTES } from './freeDiskSpaceConstants';
+
+/**
+ * Classifies one measured amount of free disk space against the `ptbk coder` free disk space limits.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function resolveFreeDiskSpaceLevel(availableBytes: number): FreeDiskSpaceLevel {
+    if (availableBytes < CRITICALLY_LOW_FREE_DISK_SPACE_BYTES) {
+        return 'critical';
+    }
+
+    if (availableBytes < LOW_FREE_DISK_SPACE_BYTES) {
+        return 'low';
+    }
+
+    return 'sufficient';
+}
+
+// Note: [🟡] Code for CLI free disk space handling [resolveFreeDiskSpaceLevel](src/cli/cli-commands/common/disk-space/resolveFreeDiskSpaceLevel.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/harness/$applyHarnessInstallationStatus.ts

@@ -1,5 +1,6 @@
 import colors from 'colors';
 import { $askForNpmPackageInstallationApproval } from '../npm/$askForNpmPackageInstallationApproval';
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 import { $runHarnessInstallationCommand } from './$runHarnessInstallationCommand';
 import { buildHarnessInstallCommand } from './buildHarnessInstallCommand';
 import type { HarnessDefinition } from './HarnessDefinition';
@@ -15,7 +16,10 @@ import { resolveHarnessUpdatePlan } from './resolveHarnessUpdatePlan';
  *
  * @private internal utility of `promptbookCli`
  */
-export async function $applyHarnessInstallationStatus(status: HarnessInstallationStatus): Promise<void> {
+export async function $applyHarnessInstallationStatus(
+    status: HarnessInstallationStatus,
+    questionsOptions: NormalizedQuestionsCliOptions,
+): Promise<void> {
     const { definition, installationState, installedVersion } = status;
 
     if (installationState === 'up-to-date') {
@@ -42,21 +46,25 @@ export async function $applyHarnessInstallationStatus(status: HarnessInstallatio
     console.warn(colors.yellow(formatHarnessInstallationWarning(status)));
 
     if (installationState === 'not-installed') {
-        await $applyMissingHarnessInstallation(definition);
+        await $applyMissingHarnessInstallation(definition, questionsOptions);
         return;
     }
 
-    await $applyOutdatedHarnessInstallation(status);
+    await $applyOutdatedHarnessInstallation(status, questionsOptions);
 }
 
 /**
  * Offers to install a missing harness globally through npm.
  */
-async function $applyMissingHarnessInstallation(definition: HarnessDefinition): Promise<void> {
+async function $applyMissingHarnessInstallation(
+    definition: HarnessDefinition,
+    questionsOptions: NormalizedQuestionsCliOptions,
+): Promise<void> {
     const installCommand = buildHarnessInstallCommand(definition);
 
     const isInstallationApproved = await $askForNpmPackageInstallationApproval(
         `Install ${definition.label} globally now?`,
+        questionsOptions,
     );
 
     if (!isInstallationApproved) {
@@ -75,7 +83,10 @@ async function $applyMissingHarnessInstallation(definition: HarnessDefinition):
 /**
  * Offers to update an outdated harness exactly where it is installed.
  */
-async function $applyOutdatedHarnessInstallation(status: HarnessInstallationStatus): Promise<void> {
+async function $applyOutdatedHarnessInstallation(
+    status: HarnessInstallationStatus,
+    questionsOptions: NormalizedQuestionsCliOptions,
+): Promise<void> {
     const { definition, latestVersion, installationOrigin } = status;
     const updatePlan = resolveHarnessUpdatePlan(definition, installationOrigin.installationMethod);
 
@@ -86,6 +97,7 @@ async function $applyOutdatedHarnessInstallation(status: HarnessInstallationStat
 
     const isUpdateApproved = await $askForNpmPackageInstallationApproval(
         `Update ${definition.label} to ${latestVersion} with \`${updatePlan.command}\` now?`,
+        questionsOptions,
     );
 
     if (!isUpdateApproved) {

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

@@ -1,11 +1,12 @@
 import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 import { $applyHarnessInstallationStatus } from './$applyHarnessInstallationStatus';
 import { $checkHarnessInstallation } from './$checkHarnessInstallation';
 import type { HarnessDefinition } from './HarnessDefinition';
 import { getHarnessDefinition } from './HarnessDefinition';
 
 /**
- * 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,
@@ -17,7 +18,7 @@ import { getHarnessDefinition } from './HarnessDefinition';
  */
 export async function $ensureHarnessInstallations(
     harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>,
-    isHarnessUpdateCheckEnabled = true,
+    questionsOptions: NormalizedQuestionsCliOptions,
 ): Promise<void> {
     const definitions = resolveCheckedHarnessDefinitions(harnessNames);
 
@@ -25,13 +26,17 @@ export async function $ensureHarnessInstallations(
         return;
     }
 
+    // Note: An outdated harness can be updated only after the user confirms it, so `--no-questions`
+    //       skips the slower npm registry lookup entirely and only reports what is installed.
+    const isHarnessUpdateCheckEnabled = questionsOptions.isAskingQuestionsEnabled;
+
     // Note: Detection of all harnesses runs in parallel, the questions have to be asked one by one
     const statuses = await Promise.all(
         definitions.map((definition) => $checkHarnessInstallation(definition, isHarnessUpdateCheckEnabled)),
     );
 
     for (const status of statuses) {
-        await $applyHarnessInstallationStatus(status);
+        await $applyHarnessInstallationStatus(status, questionsOptions);
     }
 }
 

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

@@ -24,6 +24,30 @@ 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.
  *
@@ -60,6 +84,11 @@ export type HarnessDefinition = {
      */
     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.
      *
@@ -80,6 +109,7 @@ export const HARNESS_DEFINITIONS: Readonly<Record<PromptRunnerHarnessName, Harne
         commandName: 'codex',
         npmPackageName: '@openai/codex',
         projectGitignoreRules: ['.codex'],
+        authenticationMethod: { command: 'codex login' },
         // Note: The official standalone installer keeps its package in `~/.codex` and links it onto the `PATH`
         standaloneInstallation: {
             directoryNames: ['.codex'],
@@ -92,6 +122,7 @@ export const HARNESS_DEFINITIONS: Readonly<Record<PromptRunnerHarnessName, Harne
         commandName: 'copilot',
         npmPackageName: '@github/copilot',
         projectGitignoreRules: ['.github/copilot/settings.local.json'],
+        authenticationMethod: { command: 'copilot', interactiveStep: 'running the `/login` command inside it' },
         // Note: The GitHub Copilot CLI downloads its native binary in a postinstall script
         npmInstallEnvironment: { npm_config_ignore_scripts: 'false' },
     },
@@ -101,6 +132,7 @@ export const HARNESS_DEFINITIONS: Readonly<Record<PromptRunnerHarnessName, Harne
         commandName: 'cline',
         npmPackageName: 'cline',
         projectGitignoreRules: ['.cline'],
+        authenticationMethod: { command: 'cline', interactiveStep: 'signing in to the provider inside it' },
     },
     'claude-code': {
         harnessName: 'claude-code',
@@ -108,6 +140,7 @@ export const HARNESS_DEFINITIONS: Readonly<Record<PromptRunnerHarnessName, Harne
         commandName: 'claude',
         npmPackageName: '@anthropic-ai/claude-code',
         projectGitignoreRules: ['.claude'],
+        authenticationMethod: { command: 'claude', interactiveStep: 'running the `/login` command inside it' },
     },
     opencode: {
         harnessName: 'opencode',
@@ -115,6 +148,7 @@ export const HARNESS_DEFINITIONS: Readonly<Record<PromptRunnerHarnessName, Harne
         commandName: 'opencode',
         npmPackageName: 'opencode-ai',
         projectGitignoreRules: ['.opencode'],
+        authenticationMethod: { command: 'opencode auth login' },
     },
     gemini: {
         harnessName: 'gemini',
@@ -122,6 +156,7 @@ export const HARNESS_DEFINITIONS: Readonly<Record<PromptRunnerHarnessName, Harne
         commandName: 'gemini',
         npmPackageName: '@google/gemini-cli',
         projectGitignoreRules: ['.gemini'],
+        authenticationMethod: { command: 'gemini', interactiveStep: 'running the `/auth` command inside it' },
     },
     'qwen-code': {
         harnessName: 'qwen-code',
@@ -129,6 +164,7 @@ export const HARNESS_DEFINITIONS: Readonly<Record<PromptRunnerHarnessName, Harne
         commandName: 'qwen',
         npmPackageName: '@qwen-code/qwen-code',
         projectGitignoreRules: ['.qwen'],
+        authenticationMethod: { command: 'qwen', interactiveStep: 'running the `/auth` command inside it' },
     },
 };
 

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

@@ -1,15 +1,20 @@
 import { $askForConfirmation } from '../$askForConfirmation';
+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 async function $askForNpmPackageInstallationApproval(question: string): Promise<boolean> {
-    return $askForConfirmation(question);
+export async function $askForNpmPackageInstallationApproval(
+    question: string,
+    questionsOptions: NormalizedQuestionsCliOptions,
+): Promise<boolean> {
+    return $askForConfirmation(question, questionsOptions);
 }
 
 // Note: [🟡] Code for CLI npm package installation approval [$askForNpmPackageInstallationApproval](src/cli/cli-commands/common/npm/$askForNpmPackageInstallationApproval.ts) should never be published outside of `@promptbook/cli`

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

@@ -1,6 +1,7 @@
 import colors from 'colors';
 import { spaceTrim } from 'spacetrim';
 import { $askForNpmPackageInstallationApproval } from '../npm/$askForNpmPackageInstallationApproval';
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 import { $checkPromptbookCliInstallations } from './$checkPromptbookCliInstallations';
 import { $updatePromptbookCliInstallation } from './$updatePromptbookCliInstallation';
 import { buildPromptbookCliInstallCommand } from './buildPromptbookCliInstallCommand';
@@ -20,7 +21,14 @@ import { formatPromptbookCliInstallationWarning } from './formatPromptbookCliIns
  * @returns `true` when at least one installation was updated and the current coder run should stop
  * @private internal utility of `promptbookCli`
  */
-export async function $ensurePromptbookCliInstallations(): Promise<boolean> {
+export async function $ensurePromptbookCliInstallations(
+    questionsOptions: NormalizedQuestionsCliOptions,
+): Promise<boolean> {
+    if (!questionsOptions.isAskingQuestionsEnabled) {
+        // Note: `--no-questions` forbids asking for the approval, so the registry checks would be useless
+        return false;
+    }
+
     if (!process.stdin.isTTY) {
         // Note: Non-interactive runs cannot approve an update and should not wait for registry checks
         return false;
@@ -36,7 +44,10 @@ export async function $ensurePromptbookCliInstallations(): Promise<boolean> {
 
     console.warn(colors.yellow(formatPromptbookCliInstallationWarning(outdatedStatuses)));
 
-    const isUpdateApproved = await $askForNpmPackageInstallationApproval('Update Promptbook CLI now?');
+    const isUpdateApproved = await $askForNpmPackageInstallationApproval(
+        'Update Promptbook CLI now?',
+        questionsOptions,
+    );
 
     if (!isUpdateApproved) {
         reportManualPromptbookCliUpdateCommands(outdatedStatuses);

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

@@ -0,0 +1,89 @@
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+import { spaceTrim } from 'spacetrim';
+import { NotAllowed } from '../../../errors/NotAllowed';
+
+/**
+ * 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 const QUESTIONS_DESCRIPTION = spaceTrim(`
+    Interactive questions:
+    - Steps which need an answer to continue are asked in the terminal
+    - --no-questions never asks: an optional step is skipped with a note how to do it manually, a required one fails right away
+`);
+
+/**
+ * Registers the shared `--no-questions` option on a `ptbk coder` command which can ask interactive questions.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function addQuestionsOption(command: Program): void {
+    command.option(
+        '--no-questions',
+        'Never ask an interactive question and skip every optional step which needs an answer to continue',
+    );
+}
+
+/**
+ * Converts the Commander questions flag into the normalized interactive-questions option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function normalizeQuestionsCliOptions(cliOptions: QuestionsCliOptions): NormalizedQuestionsCliOptions {
+    return {
+        isAskingQuestionsEnabled: cliOptions.questions,
+    };
+}
+
+/**
+ * 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 function assertUserConfirmationIsAllowed(options: {
+    readonly isAskingQuestionsEnabled: boolean;
+    readonly isWaitingForUser: boolean;
+}): void {
+    const { isAskingQuestionsEnabled, isWaitingForUser } = options;
+
+    if (!isWaitingForUser || isAskingQuestionsEnabled) {
+        return;
+    }
+
+    throw new NotAllowed(
+        spaceTrim(`
+            Flag \`--no-auto\` can not be used together with \`--no-questions\`.
+
+            **There is nobody who could confirm each prompt when no question may be asked.**
+
+            Actionable hints:
+            - Keep \`--no-auto\` for a supervised run, for example \`ptbk coder run --harness claude-code --no-auto\`.
+            - Keep \`--no-questions\` for an unattended run, for example \`ptbk coder run --harness claude-code --no-questions\`.
+        `),
+    );
+}
+
+// Note: [🟡] Code for CLI interactive questions options [questionsCliOptions](src/cli/cli-commands/common/questionsCliOptions.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/run.ts

@@ -13,7 +13,9 @@ import type { RunCommandCliOptions } from './run/runCommandAction';
  * @private internal function of `promptbookCli`
  */
 export function $initializeRunCommand(program: Program): $side_effect {
-    const runCommand = program.command('run', { isDefault: true });
+    // Note: `run` is deprecated, so it is intentionally NOT the default command of `ptbk`
+    //       and it must be asked for explicitly
+    const runCommand = program.command('run');
 
     configureRunCommand(runCommand);
     runCommand.action(

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

@@ -2,10 +2,14 @@ import colors from 'colors';
 import { Command } from 'commander';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../utils/organization/$side_effect';
+import { $hideCliCommandFromHelp } from './$hideCliCommandFromHelp';
 
 /**
  * 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 function $deprecateCliCommand(command: Command, deprecationMessage: string): $side_effect {
@@ -21,6 +25,7 @@ export function $deprecateCliCommand(command: Command, deprecationMessage: strin
     command.hook('preAction', () => {
         console.warn(colors.yellow(createDeprecatedCliCommandWarning(command, deprecationMessage)));
     });
+    $hideCliCommandFromHelp(command);
 }
 
 /**

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

@@ -0,0 +1,27 @@
+import type { Command } from 'commander';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+
+/**
+ * Shape of the Commander internals which decide whether one command is listed among the subcommands in the help
+ *
+ * Note: Commander accepts hiding only while the command is being registered - `program.command(name, { hidden: true })`
+ *       or `program.addCommand(command, { hidden: true })` - and exposes no setter for an already registered command,
+ *       so the very same flag which both of them set is written here directly.
+ *
+ * @private internal type of `$hideCliCommandFromHelp`
+ */
+type CommandWithHiddenFlag = {
+    _hidden: boolean;
+};
+
+/**
+ * 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 function $hideCliCommandFromHelp(command: Command): $side_effect {
+    (command as unknown as CommandWithHiddenFlag)._hidden = true;
+}

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

@@ -0,0 +1,35 @@
+import colors from 'colors';
+import type { Command } from 'commander';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+
+/**
+ * Message printed when one CLI command which only groups subcommands is run without picking any of them.
+ *
+ * @private internal constant of `$requireCliSubcommand`
+ */
+const MISSING_CLI_SUBCOMMAND_MESSAGE = 'Please specify a subcommand.';
+
+/**
+ * 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 function $requireCliSubcommand(command: Command): $side_effect {
+    command.action(() => $reportMissingCliSubcommand(command));
+}
+
+/**
+ * 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 function $reportMissingCliSubcommand(command: Command): never {
+    console.info(colors.yellow(MISSING_CLI_SUBCOMMAND_MESSAGE));
+    console.info('');
+
+    return command.help();
+}