@promptbook/cli 0.114.0-5 → 0.114.0-50

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

@@ -1,4 +1,6 @@
+import { spaceTrim } from 'spacetrim';
 import { parseDuration } from '../../../../scripts/run-codex-prompts/common/parseDuration';
+import { NotAllowed } from '../../../errors/NotAllowed';
 
 /**
  * Default wait duration applied before retrying a prompt round after an error (10 minutes).
@@ -21,4 +23,35 @@ export function parseOptionalWaitDuration(value: string | undefined, defaultMs:
     return parseDuration(value);
 }
 
+/**
+ * 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 function parseOptionalPeriodDuration(optionName: string, value: string | undefined): number | undefined {
+    if (typeof value !== 'string' || value === '') {
+        return undefined;
+    }
+
+    const periodMs = parseDuration(value);
+
+    if (periodMs <= 0) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid value for \`${optionName}\`: \`${value}\`.
+
+                Use a **positive** duration like \`5h\`, \`30m\` or \`1h30m\`.
+            `),
+        );
+    }
+
+    return periodMs;
+}
+
 // Note: [💞] Ignore a discrepancy between file name and entity name

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

@@ -1,17 +1,21 @@
-import colors from 'colors';
 import type {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../utils/organization/$side_effect';
+import { WORKSPACE_REPOSITORY_DESCRIPTION } from './common/workspaceRepositoryCliOptions';
+import { $requireCliSubcommand } from '../common/$requireCliSubcommand';
 import { $initializeCoderAddCommand } from './coder/add';
 import { $initializeCoderFindFreshEmojiTagCommand } from './coder/find-fresh-emoji-tags';
 import { $initializeCoderFindRefactorCandidatesCommand } from './coder/find-refactor-candidates';
 import { $initializeCoderFindUnwrittenCommand } from './coder/find-unwritten';
 import { $initializeCoderGenerateBoilerplatesCommand } from './coder/generate-boilerplates';
 import { $initializeCoderInitCommand } from './coder/init';
+import { $initializeCoderListCommand } from './coder/list';
 import { $initializeCoderPingCommand } from './coder/ping';
+import { $initializeCoderPlanCommand } from './coder/plan';
 import { $initializeCoderRunCommand } from './coder/run';
+import { $initializeCoderFixCommand } from './coder/fix';
 import { $initializeCoderServerCommand } from './coder/server';
 import { $initializeCoderVerifyCommand } from './coder/verify';
 
@@ -21,9 +25,12 @@ import { $initializeCoderVerifyCommand } from './coder/verify';
  * 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
@@ -41,10 +48,13 @@ export function $initializeCoderCommand(program: Program): $side_effect {
             Subcommands:
             - 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
             - find-unwritten: List prompt sections that still need to be authored
+            - 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 the connection, response time and quota of one harness and model
             - server: Start a long-running coder server with a kanban web UI
             - verify: Verify completed prompts
@@ -52,24 +62,25 @@ export function $initializeCoderCommand(program: Program): $side_effect {
         `),
     );
 
+    coderCommand.addHelpText('after', `\n${WORKSPACE_REPOSITORY_DESCRIPTION}\n`);
+
     // Register all subcommands
     $initializeCoderInitCommand(coderCommand);
     $initializeCoderAddCommand(coderCommand);
+    $initializeCoderPlanCommand(coderCommand);
     $initializeCoderGenerateBoilerplatesCommand(coderCommand);
     $initializeCoderFindRefactorCandidatesCommand(coderCommand);
     $initializeCoderFindUnwrittenCommand(coderCommand);
+    $initializeCoderListCommand(coderCommand);
     $initializeCoderRunCommand(coderCommand);
+    $initializeCoderFixCommand(coderCommand);
     $initializeCoderPingCommand(coderCommand);
     $initializeCoderServerCommand(coderCommand);
     $initializeCoderVerifyCommand(coderCommand);
     $initializeCoderFindFreshEmojiTagCommand(coderCommand);
 
     // If no subcommand is provided, show help
-    coderCommand.action(() => {
-        console.info(colors.yellow('Please specify a subcommand.'));
-        console.info('');
-        coderCommand.help();
-    });
+    $requireCliSubcommand(coderCommand);
 }
 
 // Note: [🟡] Code for CLI command [coder](src/cli/cli-commands/coder.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,41 @@
+import colors from 'colors';
+import { createInterface } from 'readline';
+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 async function $askForConfirmation(
+    question: string,
+    { isAskingQuestionsEnabled }: NormalizedQuestionsCliOptions,
+): Promise<boolean> {
+    if (!isAskingQuestionsEnabled) {
+        // Note: `--no-questions` forbids asking, so the optional change is declined without blocking the run.
+        return false;
+    }
+
+    if (!process.stdin.isTTY) {
+        // Note: In non-interactive environments like CI there is nobody who could confirm the change.
+        return false;
+    }
+
+    const readlineInterface = createInterface({ input: process.stdin, output: process.stdout });
+
+    try {
+        const answer = await new Promise<string>((resolve) => {
+            readlineInterface.question(colors.cyan(`${question} [y/N] `), resolve);
+        });
+
+        return ['y', 'yes'].includes(answer.trim().toLowerCase());
+    } finally {
+        readlineInterface.close();
+    }
+}
+
+// Note: [🟡] Code for CLI confirmations [$askForConfirmation](src/cli/cli-commands/common/$askForConfirmation.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,258 @@
+import { readFile, readdir, realpath } from 'fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'path';
+import { pathToFileURL } from 'url';
+import { spaceTrim } from 'spacetrim';
+import { normalizeAgentName } from '../../../book-2.0/agent-source/normalizeAgentName';
+import { parseAgentSource } from '../../../book-2.0/agent-source/parseAgentSource';
+import type { string_book } from '../../../book-2.0/agent-source/string_book';
+import type { TeammateProfile } from '../../../book-2.0/agent-source/TeammateProfileResolver';
+import { NotFoundError } from '../../../errors/NotFoundError';
+import { NotAllowed } from '../../../errors/NotAllowed';
+import { ParseError } from '../../../errors/ParseError';
+import { isValidAgentUrl } from '../../../utils/validators/url/isValidAgentUrl';
+import { ADAM_AGENT_BOOK_RELATIVE_PATH, ensureAdamAgentBook } from './ensureAdamAgentBook';
+
+/**
+ * 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;
+};
+
+/**
+ * Internal URLs allow the shared Book commitments to identify local books without an HTTP server.
+ * These identifiers are always intercepted by this collection and are never fetched.
+ */
+const LOCAL_AGENT_URL_PREFIX = 'https://local-agent.promptbook/';
+
+/**
+ * Directories which cannot contain project-owned agent definitions.
+ */
+const IGNORED_DIRECTORY_NAMES = new Set(['.git', 'node_modules']);
+/** Bound remote profile discovery even before a consultation's own timeout has started. */
+const REMOTE_BOOK_TIMEOUT_MS = 30_000;
+
+/**
+ * Reads repository books and indexes their first-line names for CLI reference resolution.
+ *
+ * @private internal utility of CLI agent resolution
+ */
+export class LocalAgentBookCollection {
+    private readonly booksByUrl = new Map<string, LocalAgentBook>();
+    private readonly booksByName = new Map<string, LocalAgentBook[]>();
+    /** Stable default ancestor selected from the initial repository scan. */
+    private adamAgentUrl: string | undefined;
+    /** Files initialized by this collection, for the coder's normal commit handling. */
+    public readonly createdAgentBookPaths: string[] = [];
+
+    /** Creates a collection rooted at the primary book's directory. */
+    public constructor(
+        private readonly agentDirectoryPath: string,
+        private readonly currentWorkingDirectory: string,
+        private readonly isInitializationAllowed = true,
+        private readonly signal?: AbortSignal,
+    ) {}
+
+    /** Discovers nested books, including the hidden `.core` directory. */
+    public async initialize(): Promise<void> {
+        await this.readDirectory(this.agentDirectoryPath);
+    }
+
+    /** Identifies the default ancestor without creating an unused book for FROM null/void. */
+    public getAdamAgentUrl(): string {
+        this.adamAgentUrl ??= this.booksByName.has(normalizeAgentName('Adam'))
+            ? this.findByName('Adam').url
+            : createLocalAgentBookUrl(join(this.agentDirectoryPath, ADAM_AGENT_BOOK_RELATIVE_PATH));
+        return this.adamAgentUrl;
+    }
+
+    /** Resolves a unique first-line name, refusing ambiguous matches. */
+    public findByName(name: string): LocalAgentBook {
+        const matches = this.booksByName.get(normalizeAgentName(name)) || [];
+        if (matches.length === 1) {
+            return matches[0]!;
+        }
+
+        if (matches.length > 1) {
+            throw new ParseError(
+                spaceTrim(
+                    (block) => `
+                Agent reference \`${name}\` is ambiguous. Use an explicit book path.
+
+                Matching books:
+                ${block(matches.map((book) => `- \`${book.filePath || book.url}\``).join('\n'))}
+            `,
+                ),
+            );
+        }
+
+        throw new NotFoundError(
+            spaceTrim(`
+            Agent \`${name}\` was not found in \`${this.agentDirectoryPath}\` or its subdirectories.
+
+            References use the agent's **first-line name**. You can also use an explicit \`.book\` path or URL.
+        `),
+        );
+    }
+
+    /** Resolves a name, a path relative to its declaring book, or a path relative to the CLI cwd. */
+    public async resolveReference(reference: string, declaringBook: LocalAgentBook): Promise<string> {
+        const isRemoteReference = Boolean(isValidAgentUrl(reference));
+        // Remote instructions cannot name host-local Books or manufacture internal collection identities.
+        if (
+            !declaringBook.filePath &&
+            (reference.startsWith(LOCAL_AGENT_URL_PREFIX) || (!isRemoteReference && !/^\.{1,2}[\\/]/.test(reference)))
+        ) {
+            throw new NotAllowed(
+                spaceTrim(`Remote Book \`${declaringBook.url}\` cannot access local reference \`${reference}\`.`),
+            );
+        }
+        if (isRemoteReference) {
+            return reference;
+        }
+
+        const isBookPath = /\.book$/i.test(reference) || isAbsolute(reference);
+        if (!isBookPath) {
+            if (normalizeAgentName(reference) === normalizeAgentName('Adam')) {
+                return this.getAdamAgentUrl();
+            }
+            return this.findByName(reference).url;
+        }
+
+        const isRelativeToBook = /^\.{1,2}[\\/]/.test(reference);
+        if (!declaringBook.filePath && isRelativeToBook) {
+            return new URL(reference.replaceAll('\\', '/'), declaringBook.url).href;
+        }
+
+        const directoryPath =
+            isRelativeToBook && declaringBook.filePath ? dirname(declaringBook.filePath) : this.currentWorkingDirectory;
+        return (await this.readBook(resolve(directoryPath, reference))).url;
+    }
+
+    /** Reads a local book once, canonicalizing symlinks so aliases cannot bypass cycle detection. */
+    public async readBook(filePath: string): Promise<LocalAgentBook> {
+        try {
+            const canonicalFilePath = await realpath(filePath);
+            const url = createLocalAgentBookUrl(canonicalFilePath);
+            const existingBook = this.booksByUrl.get(url);
+            if (existingBook) {
+                return existingBook;
+            }
+
+            return this.registerBook(url, await readFile(canonicalFilePath, 'utf-8'), canonicalFilePath);
+        } catch (error) {
+            if (['ENOENT', 'EISDIR', 'ENOTDIR'].includes((error as NodeJS.ErrnoException).code || '')) {
+                throw new NotFoundError(spaceTrim(`Agent book \`${filePath}\` was not found or is not a file.`));
+            }
+            throw error;
+        }
+    }
+
+    /** Loads a referenced remote book, while keeping local identifiers entirely inside the collection. */
+    public async getBook(url: string, signal = this.signal): Promise<LocalAgentBook> {
+        signal?.throwIfAborted();
+        const existingBook = this.booksByUrl.get(url);
+        if (existingBook) {
+            return existingBook;
+        }
+        if (url === this.getAdamAgentUrl()) {
+            const adamBookPath = join(this.agentDirectoryPath, ADAM_AGENT_BOOK_RELATIVE_PATH);
+            if (!this.isInitializationAllowed) {
+                throw new NotFoundError(
+                    spaceTrim(
+                        `Missing inherited Adam Book at \`${adamBookPath}\`. Run \`ptbk coder init\`, or prepare the custom Book's ancestor explicitly.`,
+                    ),
+                );
+            }
+            if ((await ensureAdamAgentBook(this.agentDirectoryPath)) === 'created') {
+                this.createdAgentBookPaths.push(adamBookPath);
+            }
+            const adamBook = await this.readBook(adamBookPath);
+            this.booksByUrl.set(url, adamBook);
+            return adamBook;
+        }
+        if (url.startsWith(LOCAL_AGENT_URL_PREFIX)) {
+            throw new NotFoundError(spaceTrim(`Local agent book \`${url}\` is not registered.`));
+        }
+
+        const bookUrl = new URL(url);
+        if (!/\.(book|md)$/i.test(bookUrl.pathname) && !bookUrl.pathname.endsWith('/api/book')) {
+            bookUrl.pathname = bookUrl.pathname.replace(/\/$/, '') + '/api/book';
+        }
+        const controller = new AbortController();
+        const cancel = (): void => controller.abort(signal?.reason);
+        signal?.addEventListener('abort', cancel, { once: true });
+        if (signal?.aborted) cancel();
+        const timeout = setTimeout(
+            () => controller.abort(new NotAllowed(spaceTrim(`Remote TEAM Book \`${url}\` timed out.`))),
+            REMOTE_BOOK_TIMEOUT_MS,
+        );
+        try {
+            const response = await fetch(bookUrl.href, { signal: controller.signal });
+            if (!response.ok) {
+                throw new NotFoundError(
+                    spaceTrim(`Cannot load agent book \`${url}\`: **${response.status} ${response.statusText}**.`),
+                );
+            }
+            let source: unknown;
+            if (response.headers.get('content-type')?.includes('application/json')) {
+                const payload: unknown = await response.json();
+                source = typeof payload === 'string' ? payload : (payload as { source?: unknown } | null)?.source;
+            } else {
+                source = await response.text();
+            }
+            if (typeof source !== 'string' || !source.trim() || source.includes('\0')) {
+                throw new ParseError(spaceTrim(`Agent book \`${url}\` did not return a text source.`));
+            }
+            return this.registerBook(url, source);
+        } finally {
+            clearTimeout(timeout);
+            signal?.removeEventListener('abort', cancel);
+        }
+    }
+
+    /** Adds a book under its normalized first-line name and preserves the display name for TEAM. */
+    private registerBook(url: string, source: string, filePath?: string): LocalAgentBook {
+        const agentSource = source as string_book;
+        const parsedSource = parseAgentSource(agentSource);
+        const book: LocalAgentBook = {
+            url,
+            filePath,
+            source: agentSource,
+            profile: {
+                agentName: parsedSource.meta.fullname || parsedSource.agentName,
+                personaDescription: parsedSource.personaDescription,
+            },
+        };
+        this.booksByUrl.set(url, book);
+        // Remote titles must not shadow repository-local names.
+        if (filePath) {
+            const agentName = normalizeAgentName(parsedSource.agentName);
+            this.booksByName.set(agentName, [...(this.booksByName.get(agentName) || []), book]);
+        }
+        return book;
+    }
+
+    /** Walks real directories in deterministic order without following directory symlink loops. */
+    private async readDirectory(directoryPath: string): Promise<void> {
+        const entries = await readdir(directoryPath, { withFileTypes: true });
+        for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+            const entryPath = join(directoryPath, entry.name);
+            if (entry.isDirectory() && !IGNORED_DIRECTORY_NAMES.has(entry.name)) {
+                await this.readDirectory(entryPath);
+            } else if (entry.isFile() && entry.name.toLowerCase().endsWith('.book')) {
+                await this.readBook(entryPath);
+            }
+        }
+    }
+}
+
+/** Creates an internal URL for a local path without requiring that the file already exists. */
+function createLocalAgentBookUrl(filePath: string): string {
+    return LOCAL_AGENT_URL_PREFIX + encodeURIComponent(pathToFileURL(filePath).href);
+}

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

@@ -0,0 +1,108 @@
+import { Command, Option } from 'commander';
+import { spaceTrim } from 'spacetrim';
+import { CHECK_BEFORE_MODE_VALUES } from '../../../../scripts/run-codex-prompts/checks/CheckBeforeMode';
+import { quoteBashArgument } from '../../../../scripts/run-codex-prompts/common/runGoScript/quoteBashArgument';
+import { NotAllowed } from '../../../errors/NotAllowed';
+
+/** Standalone shell composition tokens remain operators when a command is supplied as several arguments. */
+const SHELL_COMPOSITION_TOKENS = new Set([
+    '&&',
+    '||',
+    '|',
+    '|&',
+    '&',
+    ';',
+    '(',
+    ')',
+    '>',
+    '>>',
+    '<',
+    '2>',
+    '2>>',
+    '2>&1',
+]);
+
+/**
+ * Retired aggregate option spellings and their canonical replacements, used only for migration diagnostics.
+ * @private shared CLI migration definitions for Coder execution
+ */
+export const LEGACY_CODER_CHECK_OPTIONS = [
+    ['--test', '--check'],
+    ['--test-before', '--check-before'],
+] as const;
+
+/**
+ * Registers the shared project check command and rejects retired aggregate-test spellings.
+ * @private shared CLI registration for Coder execution
+ */
+export function addCoderCheckOptions(
+    command: Command,
+    isCheckBeforeSupported: boolean,
+    description = 'Run project checks after each prompt; commit eligible check changes separately unless --no-commit; quote commands containing flags or shell composition',
+): void {
+    command.option('--check <check-command...>', description);
+    if (isCheckBeforeSupported) {
+        command.addOption(
+            new Option(
+                '--check-before <mode>',
+                `Check before coding: ${CHECK_BEFORE_MODE_VALUES.join(
+                    ', ',
+                )} (defaults to no; uses npm run check when --check is omitted; both enabled modes commit eligible check changes separately unless --no-commit)`,
+            )
+                .choices([...CHECK_BEFORE_MODE_VALUES])
+                .default('no'),
+        );
+    }
+
+    // These diagnostic-only options never forward a value or start execution.
+    for (const [legacyFlag, replacementFlag] of LEGACY_CODER_CHECK_OPTIONS) {
+        command.addOption(new Option(`${legacyFlag} [value...]`).hideHelp());
+        command.on(`option:${legacyFlag.slice(2)}`, () => {
+            command.error(formatLegacyCoderCheckOptionError(legacyFlag, replacementFlag));
+        });
+    }
+}
+
+/**
+ * Builds the same actionable migration diagnostic for registered and direct-script entrypoints.
+ * @private shared CLI diagnostic for Coder execution
+ */
+export function formatLegacyCoderCheckOptionError(legacyFlag: string, replacementFlag: string): string {
+    return `Aggregate verification option \`${legacyFlag}\` was renamed to \`${replacementFlag}\`. Update your command and package.json scripts.`;
+}
+
+/**
+ * Normalizes shell command tokens without parsing a quoted command again or losing spaced argument boundaries.
+ * @private shared command normalization for Coder execution
+ */
+export function normalizeCheckCommandOption(value: string | ReadonlyArray<string> | undefined): string | undefined {
+    if (value === undefined) return undefined;
+    const parts = typeof value === 'string' ? [value] : value;
+    const firstPart = parts[0]?.trim() ?? '';
+    for (const [legacyFlag, replacementFlag] of LEGACY_CODER_CHECK_OPTIONS) {
+        if (firstPart === legacyFlag || firstPart.startsWith(`${legacyFlag}=`)) {
+            throw new NotAllowed(formatLegacyCoderCheckOptionError(legacyFlag, replacementFlag));
+        }
+    }
+    const command =
+        parts.length === 1
+            ? parts[0]!.trim()
+            : parts
+                  .map((part) =>
+                      !SHELL_COMPOSITION_TOKENS.has(part) && (!part || /[\s'"\\$`;&|<>()*?]/u.test(part))
+                          ? quoteBashArgument(part)
+                          : part,
+                  )
+                  .join(' ')
+                  .trim();
+    if (!command || !firstPart || firstPart.startsWith('-')) {
+        throw new NotAllowed(
+            spaceTrim(`
+            Option \`--check\` requires a non-empty shell command, for example \`--check "npm run check"\`.
+        `),
+        );
+    }
+    return command;
+}
+
+// Note: [💞] Ignore a discrepancy between file name and exported helper names

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

@@ -26,7 +26,7 @@ export type CoderGitSyncCliOptions = {
 export const CODER_GIT_SYNC_DESCRIPTION = spaceTrim(`
     Git synchronization:
     - --auto-pull pulls the latest changes before this command changes anything
-    - --commit commits the changes made by this command
+    - --commit commits only the files this command has changed, unrelated changes stay in the working tree
     - --auto-push pushes the created commit to the remote repository
 `);
 
@@ -34,12 +34,16 @@ export const CODER_GIT_SYNC_DESCRIPTION = spaceTrim(`
  * 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`
  */
 export function addCoderGitSyncOptions(command: Program): void {
-    command.option('--commit', 'Commit the changes made by this command with the coding-agent git identity', false);
+    command.option(
+        '--commit',
+        'Commit the files changed by this command with the coding-agent git identity, leaving unrelated changes uncommitted',
+        false,
+    );
     command.option('--auto-push', 'Automatically git push the created commit, requires --commit', false);
     command.option(
         '--auto-pull',

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

@@ -0,0 +1,69 @@
+import { spaceTrim } from 'spacetrim';
+import type { AgentReferenceResolver } from '../../../book-2.0/agent-source/AgentReferenceResolver';
+import { extractAgentReferenceTokens } from '../../../book-2.0/agent-source/extractAgentReferenceTokens';
+import { parseTeamCommitmentContent } from '../../../book-2.0/agent-source/parseTeamCommitment';
+import {
+    createPseudoAgentUrl,
+    isPseudoAgentAllowedInCommitment,
+    resolvePseudoAgentKindFromReference,
+    VOID_PSEUDO_AGENT_REFERENCE,
+} from '../../../book-2.0/agent-source/pseudoAgentReferences';
+import type { BookCommitment } from '../../../commitments/_base/BookCommitment';
+import { ParseError } from '../../../errors/ParseError';
+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 function createLocalAgentReferenceResolver(
+    collection: LocalAgentBookCollection,
+    declaringBook: LocalAgentBook,
+): AgentReferenceResolver {
+    /** Resolves pseudo-agents using the same aliases and restrictions as the Agent Server. */
+    async function resolveReference(commitmentType: BookCommitment, reference: string): Promise<string> {
+        const pseudoAgentKind = resolvePseudoAgentKindFromReference(reference);
+        if (!pseudoAgentKind) {
+            return collection.resolveReference(reference, declaringBook);
+        }
+        if (!isPseudoAgentAllowedInCommitment(pseudoAgentKind, commitmentType)) {
+            throw new ParseError(spaceTrim(`Pseudo-agent \`${reference}\` cannot be used in \`${commitmentType}\`.`));
+        }
+        if (pseudoAgentKind === 'VOID' && commitmentType === 'FROM') {
+            return VOID_PSEUDO_AGENT_REFERENCE;
+        }
+        if (pseudoAgentKind === 'VOID' && (commitmentType === 'IMPORT' || commitmentType === 'IMPORTS')) {
+            return '';
+        }
+        return createPseudoAgentUrl(pseudoAgentKind);
+    }
+
+    return {
+        resolveCommitmentContent: async (commitmentType, content) => {
+            // Bare TEAM URLs bypass compact token replacement, but must obey the same remote/local boundary.
+            if (commitmentType === 'TEAM') {
+                for (const teammate of parseTeamCommitmentContent(content)) {
+                    await collection.resolveReference(teammate.url, declaringBook);
+                }
+            }
+            const tokens = extractAgentReferenceTokens(content);
+            if (tokens.length === 0) {
+                if (commitmentType !== 'TEAM' && content.trim()) {
+                    return resolveReference(commitmentType, content.trim());
+                }
+                return content;
+            }
+
+            const parts: string[] = [];
+            let previousEnd = 0;
+            for (const token of tokens) {
+                parts.push(content.slice(previousEnd, token.index));
+                parts.push(await resolveReference(commitmentType, token.reference));
+                previousEnd = token.index + token.length;
+            }
+            parts.push(content.slice(previousEnd));
+            return parts.join('');
+        },
+    };
+}

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

@@ -0,0 +1,35 @@
+import { spaceTrim } from 'spacetrim';
+import { LimitReachedError } from '../../../../errors/LimitReachedError';
+import { $readFreeDiskSpaceStatus } from './$readFreeDiskSpaceStatus';
+import { formatLowFreeDiskSpaceWarning } from './formatLowFreeDiskSpaceWarning';
+
+/**
+ * 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 async function $assertSufficientFreeDiskSpace(inspectedPath: string): Promise<void> {
+    const freeDiskSpaceStatus = await $readFreeDiskSpaceStatus(inspectedPath);
+
+    if (freeDiskSpaceStatus === null || freeDiskSpaceStatus.level === 'sufficient') {
+        return;
+    }
+
+    throw new LimitReachedError(
+        spaceTrim(
+            (block) => `
+                There is not enough free disk space to run \`ptbk coder\`.
+
+                ${block(formatLowFreeDiskSpaceWarning(freeDiskSpaceStatus))}
+            `,
+        ),
+    );
+}
+
+// Note: [🟡] Code for CLI free disk space handling [$assertSufficientFreeDiskSpace](src/cli/cli-commands/common/disk-space/$assertSufficientFreeDiskSpace.ts) should never be published outside of `@promptbook/cli`