@promptbook/components 0.114.0-5 → 0.114.0-50

package/umd/src/cli/cli-commands/coder/planning/planningGitSync.test.d.ts

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

package/umd/src/cli/cli-commands/coder/planning/planningPackagedCli.test.d.ts

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

package/umd/src/cli/cli-commands/coder/planning/planningProtocol.d.ts

@@ -0,0 +1,152 @@
+import { z as schema } from 'zod';
+/** Read-only host requests and scoped TEAM consultations; there is deliberately no shell operation. */
+declare const PLANNING_READ_SCHEMA: schema.ZodDiscriminatedUnion<[schema.ZodObject<{
+    kind: schema.ZodLiteral<"list">;
+    path: schema.ZodString;
+}, schema.core.$strict>, schema.ZodObject<{
+    kind: schema.ZodLiteral<"read">;
+    path: schema.ZodString;
+    startLine: schema.ZodNumber;
+    lineCount: schema.ZodNumber;
+}, schema.core.$strict>, schema.ZodObject<{
+    kind: schema.ZodLiteral<"search">;
+    path: schema.ZodString;
+    query: schema.ZodString;
+}, schema.core.$strict>, schema.ZodObject<{
+    kind: schema.ZodLiteral<"git">;
+    operation: schema.ZodEnum<{
+        status: "status";
+        diff: "diff";
+        log: "log";
+    }>;
+}, schema.core.$strict>, schema.ZodObject<{
+    message: schema.ZodString;
+    context: schema.ZodNonOptional<schema.ZodOptional<schema.ZodString>>;
+    kind: schema.ZodLiteral<"team">;
+    toolName: schema.ZodString;
+}, schema.core.$strict>], "kind">;
+/** Proposed changes are data, never instructions executed by a harness. */
+declare const PLANNING_PROPOSAL_SCHEMA: schema.ZodDiscriminatedUnion<[schema.ZodObject<{
+    kind: schema.ZodLiteral<"create">;
+    title: schema.ZodString;
+    body: schema.ZodString;
+    priority: schema.ZodNumber;
+    isReady: schema.ZodBoolean;
+}, schema.core.$strict>, schema.ZodObject<{
+    kind: schema.ZodLiteral<"edit">;
+    path: schema.ZodString;
+    find: schema.ZodString;
+    replace: schema.ZodString;
+    isReady: schema.ZodBoolean;
+}, schema.core.$strict>], "kind">;
+/** Strict validation prevents unsupported operations from reaching any filesystem code. */
+declare const PLANNING_REPLY_SCHEMA: schema.ZodObject<{
+    message: schema.ZodString;
+    reads: schema.ZodArray<schema.ZodDiscriminatedUnion<[schema.ZodObject<{
+        kind: schema.ZodLiteral<"list">;
+        path: schema.ZodString;
+    }, schema.core.$strict>, schema.ZodObject<{
+        kind: schema.ZodLiteral<"read">;
+        path: schema.ZodString;
+        startLine: schema.ZodNumber;
+        lineCount: schema.ZodNumber;
+    }, schema.core.$strict>, schema.ZodObject<{
+        kind: schema.ZodLiteral<"search">;
+        path: schema.ZodString;
+        query: schema.ZodString;
+    }, schema.core.$strict>, schema.ZodObject<{
+        kind: schema.ZodLiteral<"git">;
+        operation: schema.ZodEnum<{
+            status: "status";
+            diff: "diff";
+            log: "log";
+        }>;
+    }, schema.core.$strict>, schema.ZodObject<{
+        message: schema.ZodString;
+        context: schema.ZodNonOptional<schema.ZodOptional<schema.ZodString>>;
+        kind: schema.ZodLiteral<"team">;
+        toolName: schema.ZodString;
+    }, schema.core.$strict>], "kind">>;
+    proposals: schema.ZodArray<schema.ZodDiscriminatedUnion<[schema.ZodObject<{
+        kind: schema.ZodLiteral<"create">;
+        title: schema.ZodString;
+        body: schema.ZodString;
+        priority: schema.ZodNumber;
+        isReady: schema.ZodBoolean;
+    }, schema.core.$strict>, schema.ZodObject<{
+        kind: schema.ZodLiteral<"edit">;
+        path: schema.ZodString;
+        find: schema.ZodString;
+        replace: schema.ZodString;
+        isReady: schema.ZodBoolean;
+    }, schema.core.$strict>], "kind">>;
+}, schema.core.$strict>;
+/**
+ * The same response contract constrains Codex output and validates it at the host boundary.
+ * @private internal constant of `coder plan`
+ */
+export declare const PLANNING_RESPONSE_SCHEMA: schema.core.ZodStandardJSONSchemaPayload<schema.ZodObject<{
+    message: schema.ZodString;
+    reads: schema.ZodArray<schema.ZodDiscriminatedUnion<[schema.ZodObject<{
+        kind: schema.ZodLiteral<"list">;
+        path: schema.ZodString;
+    }, schema.core.$strict>, schema.ZodObject<{
+        kind: schema.ZodLiteral<"read">;
+        path: schema.ZodString;
+        startLine: schema.ZodNumber;
+        lineCount: schema.ZodNumber;
+    }, schema.core.$strict>, schema.ZodObject<{
+        kind: schema.ZodLiteral<"search">;
+        path: schema.ZodString;
+        query: schema.ZodString;
+    }, schema.core.$strict>, schema.ZodObject<{
+        kind: schema.ZodLiteral<"git">;
+        operation: schema.ZodEnum<{
+            status: "status";
+            diff: "diff";
+            log: "log";
+        }>;
+    }, schema.core.$strict>, schema.ZodObject<{
+        message: schema.ZodString;
+        context: schema.ZodNonOptional<schema.ZodOptional<schema.ZodString>>;
+        kind: schema.ZodLiteral<"team">;
+        toolName: schema.ZodString;
+    }, schema.core.$strict>], "kind">>;
+    proposals: schema.ZodArray<schema.ZodDiscriminatedUnion<[schema.ZodObject<{
+        kind: schema.ZodLiteral<"create">;
+        title: schema.ZodString;
+        body: schema.ZodString;
+        priority: schema.ZodNumber;
+        isReady: schema.ZodBoolean;
+    }, schema.core.$strict>, schema.ZodObject<{
+        kind: schema.ZodLiteral<"edit">;
+        path: schema.ZodString;
+        find: schema.ZodString;
+        replace: schema.ZodString;
+        isReady: schema.ZodBoolean;
+    }, schema.core.$strict>], "kind">>;
+}, schema.core.$strict>>;
+/** @private internal type of `coder plan` */
+export type PlanningRead = Exclude<schema.infer<typeof PLANNING_READ_SCHEMA>, {
+    kind: 'team';
+}>;
+/** @private internal type of `coder plan` */
+export type PlanningProposal = schema.infer<typeof PLANNING_PROPOSAL_SCHEMA>;
+/** @private internal type of `coder plan` */
+export type PlanningReply = schema.infer<typeof PLANNING_REPLY_SCHEMA>;
+/** @private internal type of `coder plan` */
+export type PlanningMessage = {
+    readonly role: 'user' | 'planner' | 'context';
+    readonly content: string;
+};
+/**
+ * Rejects malformed or unsupported harness output before processing reads or proposed writes.
+ * @private internal utility of `coder plan`
+ */
+export declare function parsePlanningReply(output: string): PlanningReply;
+/**
+ * Describes the host-mediated planning protocol, independent of the selected Book's instructions.
+ * @private internal constant of `coder plan`
+ */
+export declare const PLANNING_PROTOCOL: string;
+export {};

package/umd/src/cli/cli-commands/coder/planning/planningTeam.test.d.ts

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

package/umd/src/cli/cli-commands/coder/planning/preparePlanningChanges.d.ts

@@ -0,0 +1,16 @@
+import type { PlanningProposal } from './planningProtocol';
+/**
+ * A fully rendered change retained in memory until the user explicitly saves it.
+ * @private internal type of `coder plan`
+ */
+export type PlanningChange = {
+    readonly path: string;
+    readonly before: string | null;
+    readonly after: string;
+    readonly draft: string;
+};
+/**
+ * Prepares an entire proposal set without writing. Exact replacements preserve unrelated content and line endings.
+ * @private internal utility of `coder plan`
+ */
+export declare function preparePlanningChanges(projectPath: string, proposals: ReadonlyArray<PlanningProposal>, templateOption: string | undefined): Promise<PlanningChange[]>;

package/umd/src/cli/cli-commands/coder/planning/readPlanningContext.d.ts

@@ -0,0 +1,6 @@
+import type { PlanningRead } from './planningProtocol';
+/**
+ * Executes only the read operations in the planning protocol. Never evaluates a command from the model.
+ * @private internal utility of `coder plan`
+ */
+export declare function readPlanningContext(projectPath: string, request: PlanningRead): Promise<string>;

package/umd/src/cli/cli-commands/coder/planning/resolvePlanningPath.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolves a repository path without traversing symlinks, junctions, device paths, or parent escapes.
+ * Writes additionally require an ordinary, singly linked PRD Markdown file in the active prompts directory.
+ * The queue loader reads only this directory; archives, templates and reusable context remain read-only.
+ * @private internal execution boundary of `coder plan`
+ */
+export declare function resolvePlanningPath(projectPath: string, path: string, isWriting?: boolean): string;

package/umd/src/cli/cli-commands/coder/planning/runPlanningHarness.d.ts

@@ -0,0 +1,30 @@
+import type { Usage } from '../../../../execution/Usage';
+import type { NormalizedPromptRunnerSelectionCliOptions } from '../../common/promptRunnerCliOptions';
+/**
+ * Parameters for one tool-restricted inference. Repository reads and PRD writes are host operations.
+ * @private internal type of `coder plan`
+ */
+export type PlanningHarnessOptions = NormalizedPromptRunnerSelectionCliOptions & {
+    readonly workspacePath: string;
+    readonly prompt: string;
+    readonly signal: AbortSignal;
+    /** Reports available usage from this inference once, including turns whose final answer is malformed. */
+    readonly onUsage?: (usage: Usage) => void;
+};
+/**
+ * Rejects harnesses without a planning execution policy before any Git sync or process launch.
+ * @private internal utility of `coder plan`
+ */
+export declare function assertPlanningHarnessSupported(harness: string | undefined): void;
+/**
+ * Constructs a fail-closed Codex invocation. User config, rules, project config discovery, native shell,
+ * connectors, hooks and delegation cannot expand the planning tool set. Read-only sandboxing also denies patches.
+ * Older Codex versions that do not support these switches fail instead of using the implementation runner.
+ * @private internal utility of `coder plan`
+ */
+export declare function buildPlanningHarnessArguments(options: PlanningHarnessOptions): string[];
+/**
+ * Runs a bounded inference with no shell interpolation and consumes only its final JSON answer.
+ * @private internal utility of `coder plan`
+ */
+export declare function runPlanningHarness(options: PlanningHarnessOptions): Promise<string>;

package/umd/src/cli/cli-commands/coder/planning/runPlanningHarness.test.d.ts

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

package/umd/src/cli/cli-commands/coder/planning/runPlanningSession.d.ts

@@ -0,0 +1,24 @@
+import { type ResolvedCoderProjectContext } from '../../../../../scripts/run-codex-prompts/common/resolveCoderProjectContext';
+import type { NormalizedPromptRunnerSelectionCliOptions } from '../../common/promptRunnerCliOptions';
+import { runPlanningHarness } from './runPlanningHarness';
+/**
+ * Terminal interface also used by deterministic conversation fixtures.
+ * @private internal type of `coder plan`
+ */
+export type PlanningSessionIo = {
+    readonly readMessage: () => Promise<string | undefined>;
+    readonly write: (message: string) => void;
+    readonly signal: AbortSignal;
+};
+/**
+ * Runs one multi-topic planning conversation; only explicit save commands cross the PRD write boundary.
+ * @private internal utility of `coder plan`
+ */
+export declare function runPlanningSession(options: NormalizedPromptRunnerSelectionCliOptions & {
+    readonly projectPath: string;
+    readonly agent?: string;
+    readonly context?: string;
+    readonly projectContext?: ResolvedCoderProjectContext;
+    readonly template?: string;
+    readonly preexistingChangedPaths?: ReadonlySet<string>;
+}, io: PlanningSessionIo, harness?: typeof runPlanningHarness): Promise<ReadonlyMap<string, string>>;

package/umd/src/cli/cli-commands/coder/planning/runPlanningSession.test.d.ts

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

package/umd/src/cli/cli-commands/coder/planning/savePlanningChanges.d.ts

@@ -0,0 +1,7 @@
+import type { PlanningChange } from './preparePlanningChanges';
+/**
+ * Validates the entire batch before writing, stages outside the queue, then atomically replaces each file.
+ * The synchronous commit region cannot be interrupted by a SIGINT callback halfway through a save.
+ * @private internal execution boundary of `coder plan`
+ */
+export declare function savePlanningChanges(projectPath: string, workspacePath: string, changes: ReadonlyArray<PlanningChange>, isDraft: boolean): string[];

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

@@ -0,0 +1,12 @@
+/** Result of preparing project-owned checks and migrating recognized generated callers. @private internal initializer result */
+export type PreparedCoderPackageJsonScripts = {
+    readonly scripts: Readonly<Record<string, string>>;
+    readonly checkScriptSummary: string;
+    readonly migrationInstructions: ReadonlyArray<string>;
+    readonly isCheckConfigured: boolean;
+};
+/**
+ * Preserves project scripts, creates one canonical check, and migrates only exact generated caller forms.
+ * @private shared package-script preparation for Coder initialization
+ */
+export declare function prepareCoderPackageJsonScripts(existing: Readonly<Record<string, string>>, externalCallers?: Readonly<Record<string, ReadonlyArray<string>>>): PreparedCoderPackageJsonScripts;

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/printInitializationSummary.d.ts

@@ -1,7 +1,8 @@
+import type { WorkspaceRepositoryContext } from '../common/workspaceRepository';
 import type { CoderInitializationSummary } from './initializeCoderProjectConfiguration';
 /**
  * Prints a readable summary of what was initialized for the user.
  *
  * @private function of `coder init` command
  */
-export declare function printInitializationSummary(summary: CoderInitializationSummary): void;
+export declare function printInitializationSummary(summary: CoderInitializationSummary, workspace?: WorkspaceRepositoryContext): void;

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

@@ -0,0 +1,13 @@
+/**
+ * Project-relative location of the offline guide, reserved from prompt discovery.
+ *
+ * @private internal constant of `coder init`
+ */
+export declare const PROMPTS_README_FILE_PATH: string;
+/**
+ * Maintained project-independent guide, bundled as text in the published CLI.
+ * Keep examples executable against the parser and command registry in the accompanying tests.
+ *
+ * @private internal template of `coder init`
+ */
+export declare const PROMPTS_README_TEMPLATE: string;

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

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

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

@@ -0,0 +1,8 @@
+import type { string_book } from '../../../book-2.0/agent-source/string_book';
+/**
+ * Reads a project-owned Book before initialization, refusing unsafe edits while preserving its original bytes.
+ * Unknown commitments remain supported, as in the normal Book parser.
+ *
+ * @private internal utility of `coder init`
+ */
+export declare function readCoderAgentBook(filePath: string): Promise<string_book>;

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

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

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/workspacePreflight.test.d.ts

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

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

@@ -6,9 +6,12 @@ import type { $side_effect } from '../../utils/organization/$side_effect';
  * The coder command provides utilities for automated coding:
  * - init: Initialize coder configuration in current project
  * - add: Add one ready-to-run prompt file to the queue
+ * - plan: Discuss features with Developer and author reviewed PRDs
  * - 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
+ * - fix: Check and repair the project, then exit without processing the queue
  * - ping: Test one harness and model with a tiny dummy prompt
  * - verify: Verify completed prompts
  * - find-fresh-emoji-tags: Find unused emoji tags

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,48 @@
+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 isInitializationAllowed;
+    private readonly signal?;
+    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, isInitializationAllowed?: boolean, signal?: AbortSignal | undefined);
+    /** 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, signal?: AbortSignal | undefined): 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/coderCheckCliOptions.d.ts

@@ -0,0 +1,21 @@
+import { Command } from 'commander';
+/**
+ * Retired aggregate option spellings and their canonical replacements, used only for migration diagnostics.
+ * @private shared CLI migration definitions for Coder execution
+ */
+export declare const LEGACY_CODER_CHECK_OPTIONS: readonly [readonly ["--test", "--check"], readonly ["--test-before", "--check-before"]];
+/**
+ * Registers the shared project check command and rejects retired aggregate-test spellings.
+ * @private shared CLI registration for Coder execution
+ */
+export declare function addCoderCheckOptions(command: Command, isCheckBeforeSupported: boolean, description?: string): void;
+/**
+ * Builds the same actionable migration diagnostic for registered and direct-script entrypoints.
+ * @private shared CLI diagnostic for Coder execution
+ */
+export declare function formatLegacyCoderCheckOptionError(legacyFlag: string, replacementFlag: string): string;
+/**
+ * Normalizes shell command tokens without parsing a quoted command again or losing spaced argument boundaries.
+ * @private shared command normalization for Coder execution
+ */
+export declare function normalizeCheckCommandOption(value: string | ReadonlyArray<string> | undefined): string | undefined;

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

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

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

@@ -21,7 +21,7 @@ export declare const CODER_GIT_SYNC_DESCRIPTION: string;
  * Registers the shared `--commit`, `--auto-push` and `--auto-pull` flags on a `ptbk coder` command.
  *
  * Note: Unlike `ptbk coder run`, which commits by default and opts out through `--no-commit`,
- *       these commands never touch git unless the flags are used explicitly.
+ *       these commands only mutate Git when the flags are used explicitly. Workspace detection always runs.
  *
  * @private internal utility of `promptbookCli`
  */

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'>;

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

@@ -0,0 +1,7 @@
+import type { ProjectInitializationStatus } from './projectInitialization';
+/**
+ * Creates one project text file with default content, preserving any existing file.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export declare function ensureProjectTextFile(projectPath: string, relativeFilePath: string, fileContent: string): Promise<ProjectInitializationStatus>;