@promptbook/cli 0.114.0-41 → 0.114.0-47

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

@@ -1,4 +1,5 @@
 import colors from 'colors';
+import { NotAllowed } from '../../../errors/NotAllowed';
 import {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
     Option,
@@ -17,6 +18,8 @@ import {
     CODER_GIT_SYNC_DESCRIPTION,
     normalizeCoderGitSyncCliOptions,
 } from '../common/coderGitSyncCliOptions';
+import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
+import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 
 /**
@@ -74,6 +77,8 @@ export function $initializeCoderVerifyCommand(program: Program): $side_effect {
     );
     addCoderGitSyncOptions(command);
 
+    addWorkspaceRepositoryOptions(command);
+
     command.action(
         handleActionErrors(async (cliOptions) => {
             const { order, ignore } = cliOptions as {
@@ -83,11 +88,23 @@ export function $initializeCoderVerifyCommand(program: Program): $side_effect {
 
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
 
+            const workspace = await $preflightWorkspaceRepository({
+                policy: 'mutate',
+                isAskingQuestionsEnabled: cliOptions.questions,
+            });
+            if (cliOptions.questions === false) {
+                throw new NotAllowed(
+                    spaceTrim(
+                        '`ptbk coder verify` requires answers before changing PRD statuses or archiving files. Run it without `--no-questions` in an interactive terminal.',
+                    ),
+                );
+            }
+
             // Note: Import the main function dynamically to avoid loading heavy dependencies until needed
             const { verifyPrompts } = await import('../../../../scripts/verify-prompts/verify-prompts');
 
             try {
-                await verifyPrompts({ order, ignore, gitSync });
+                await verifyPrompts({ order, ignore, gitSync, workspace });
             } catch (error) {
                 console.error(colors.bgRed('Prompt verification failed:'), error);
                 return process.exit(1);

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

@@ -3,6 +3,7 @@ import type {
 } 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';
@@ -12,6 +13,7 @@ import { $initializeCoderGenerateBoilerplatesCommand } from './coder/generate-bo
 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 { $initializeCoderServerCommand } from './coder/server';
 import { $initializeCoderVerifyCommand } from './coder/verify';
@@ -22,6 +24,7 @@ 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 Planner 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
@@ -43,6 +46,7 @@ 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 Planner 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
@@ -55,9 +59,12 @@ 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);

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

@@ -7,6 +7,7 @@ import { parseAgentSource } from '../../../book-2.0/agent-source/parseAgentSourc
 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';
@@ -33,6 +34,8 @@ 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.
@@ -48,7 +51,12 @@ export class LocalAgentBookCollection {
     public readonly createdAgentBookPaths: string[] = [];
 
     /** Creates a collection rooted at the primary book's directory. */
-    public constructor(private readonly agentDirectoryPath: string, private readonly currentWorkingDirectory: string) {}
+    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> {
@@ -95,6 +103,15 @@ export class LocalAgentBookCollection {
     /** 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;
         }
@@ -137,13 +154,21 @@ export class LocalAgentBookCollection {
     }
 
     /** Loads a referenced remote book, while keeping local identifiers entirely inside the collection. */
-    public async getBook(url: string): Promise<LocalAgentBook> {
+    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);
             }
@@ -159,23 +184,36 @@ export class LocalAgentBookCollection {
         if (!/\.(book|md)$/i.test(bookUrl.pathname) && !bookUrl.pathname.endsWith('/api/book')) {
             bookUrl.pathname = bookUrl.pathname.replace(/\/$/, '') + '/api/book';
         }
-        const response = await fetch(bookUrl.href);
-        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') {
-            throw new ParseError(spaceTrim(`Agent book \`${url}\` did not return a text source.`));
+        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);
         }
-        return this.registerBook(url, source);
     }
 
     /** Adds a book under its normalized first-line name and preserves the display name for TEAM. */

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

@@ -34,7 +34,7 @@ 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`
  */

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

@@ -1,6 +1,7 @@
 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,
@@ -40,6 +41,12 @@ export function createLocalAgentReferenceResolver(
 
     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()) {

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

@@ -18,8 +18,12 @@ import { LocalAgentBookCollection, type LocalAgentBook } from './LocalAgentBookC
  * @private internal type of CLI agent resolution
  */
 export type ResolvedLocalAgentSource = {
+    /** Canonical identity used to bound recursive TEAM consultations. */
+    readonly agentUrl: string;
     readonly agentSource: string_book;
     readonly agentReferenceResolver: AgentReferenceResolver;
+    /** Resolves another Book in this collection, retaining its own inheritance and reference locations. */
+    readonly resolveAgentSource: (url: string, signal?: AbortSignal) => Promise<ResolvedLocalAgentSource>;
     /** Newly created books which the coder may include in its initialization commit. */
     readonly createdAgentBookPaths: ReadonlyArray<string>;
 };
@@ -32,8 +36,14 @@ export type ResolvedLocalAgentSource = {
 export async function resolveLocalAgentSource(
     agentBookPath: string,
     currentWorkingDirectory: string,
+    options: { readonly isInitializationAllowed?: boolean; readonly signal?: AbortSignal } = {},
 ): Promise<ResolvedLocalAgentSource> {
-    const collection = new LocalAgentBookCollection(dirname(agentBookPath), currentWorkingDirectory);
+    const collection = new LocalAgentBookCollection(
+        dirname(agentBookPath),
+        currentWorkingDirectory,
+        options.isInitializationAllowed,
+        options.signal,
+    );
     await collection.initialize();
     const primaryBook = await collection.readBook(agentBookPath);
     const adamAgentUrl = collection.getAdamAgentUrl();
@@ -42,7 +52,9 @@ export async function resolveLocalAgentSource(
     async function resolveBook(
         book: LocalAgentBook,
         inheritancePath: ReadonlyArray<string> = [],
+        signal = options.signal,
     ): Promise<string_book> {
+        signal?.throwIfAborted();
         if (inheritancePath.length > DEFAULT_MAX_RECURSION) {
             throw new ParseError(
                 spaceTrim(
@@ -59,28 +71,36 @@ export async function resolveLocalAgentSource(
             currentAgentUrl: book.url,
             inheritancePath,
             agentSourceImporter: async (url, context) =>
-                resolveBook(await collection.getBook(url), context.importAgentOptions.inheritancePath),
+                resolveBook(await collection.getBook(url, signal), context.importAgentOptions.inheritancePath, signal),
         });
     }
 
-    return {
-        agentSource: await resolveBook(primaryBook),
-        agentReferenceResolver: {
-            ...createLocalAgentReferenceResolver(collection, primaryBook),
-            resolveTeammateProfile: async (url) => {
-                if (isPseudoAgentUrl(url)) {
-                    return null;
-                }
-                const book = await collection.getBook(url);
-                const parsedSource = parseAgentSource(await resolveBook(book));
-                return {
-                    agentName: book.profile.agentName,
-                    personaDescription: parsedSource.personaDescription,
-                };
+    /** Keeps the source loader and profiles scoped to this resolution, never to a global TEAM registry. */
+    async function resolveAgent(book: LocalAgentBook, signal = options.signal): Promise<ResolvedLocalAgentSource> {
+        return {
+            agentUrl: book.url,
+            agentSource: await resolveBook(book, [], signal),
+            agentReferenceResolver: {
+                ...createLocalAgentReferenceResolver(collection, book),
+                resolveTeammateProfile: async (url) => {
+                    if (isPseudoAgentUrl(url)) {
+                        return null;
+                    }
+                    const book = await collection.getBook(url, signal);
+                    const parsedSource = parseAgentSource(await resolveBook(book, [], signal));
+                    return {
+                        agentName: book.profile.agentName,
+                        personaDescription: parsedSource.personaDescription,
+                    };
+                },
             },
-        },
-        createdAgentBookPaths: collection.createdAgentBookPaths,
-    };
+            resolveAgentSource: async (url, consultationSignal) =>
+                resolveAgent(await collection.getBook(url, consultationSignal || signal), consultationSignal || signal),
+            createdAgentBookPaths: collection.createdAgentBookPaths,
+        };
+    }
+
+    return resolveAgent(primaryBook);
 }
 
 /**

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

@@ -0,0 +1,91 @@
+import { spaceTrim } from 'spacetrim';
+import type { RunOptions } from '../../../../scripts/run-codex-prompts/cli/RunOptions';
+import { isTestBeforeMode } from '../../../../scripts/run-codex-prompts/testing/TestBeforeMode';
+import { DatabaseError } from '../../../errors/DatabaseError';
+import { NotAllowed } from '../../../errors/NotAllowed';
+
+/**
+ * Validates cross-flag constraints before workspace setup or the run starts.
+ * @private shared validation for Coder execution commands
+ */
+export function validateCoderRunOptions(options: RunOptions): void {
+    if (!isTestBeforeMode(options.testBefore ?? 'no')) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid ${'`--test-before`'} mode: \`${String(options.testBefore)}\`.
+
+                Use one of: \`no\`, \`yes-and-fail\`, \`yes-and-fix\`.
+            `),
+        );
+    }
+
+    if (options.allowDestructiveAutoMigrate && !options.autoMigrate) {
+        throw new DatabaseError(
+            spaceTrim(`
+                Flag \`--allow-destructive-auto-migrate\` requires \`--auto-migrate\`.
+            `),
+        );
+    }
+
+    if (options.noCommit && !options.waitForUser && options.gitChanges !== 'ignore') {
+        throw new NotAllowed(
+            spaceTrim(`
+                Flag \`--no-commit\` requires \`--git-changes ignore\` when running in auto mode (the default; pass \`--no-auto\` for interactive confirmation).
+
+                Without commits, the next prompt round would fail the clean working tree check.
+            `),
+        );
+    }
+
+    if (options.autoPull && options.noCommit && !options.dryRun) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Flag \`--auto-pull\` requires commits, so it cannot be combined with \`--no-commit\`.
+
+                Auto-pull keeps the repository up to date between prompt rounds, which requires each successful round to end with a clean committed working tree.
+            `),
+        );
+    }
+
+    if (options.isIsolated && options.noCommit) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Flag \`--isolate\` cannot be combined with \`--no-commit\`.
+
+                An isolated task is implemented in a temporary worktree and reaches the original branch only through a merge, which requires the round to end with a commit.
+            `),
+        );
+    }
+
+    if (options.isIsolated && options.gitChanges === 'continue') {
+        throw new NotAllowed(
+            spaceTrim(`
+                Flag \`--isolate\` cannot be combined with \`--git-changes continue\`.
+
+                An isolated task is implemented in a fresh temporary worktree checked out from the last commit, so the uncommitted changes of the interrupted prompt would be left behind instead of being continued.
+            `),
+        );
+    }
+
+    if (options.gitChanges === 'continue' && options.testBefore === 'yes-and-fix') {
+        throw new NotAllowed(
+            spaceTrim(`
+                Flag \`--git-changes continue\` cannot be combined with \`--test-before yes-and-fix\`.
+
+                An interrupted prompt already has changes in progress, so there is no unmodified project state for pre-coding verification to repair.
+            `),
+        );
+    }
+
+    if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit <= 0)) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Flag \`--limit\` expects a positive integer.
+
+                Received: \`${options.limit}\`
+            `),
+        );
+    }
+}
+
+// Note: [🟡] Code for Coder run validation [validateCoderRunOptions](src/cli/cli-commands/common/validateCoderRunOptions.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/workspaceRepository.md

@@ -0,0 +1,46 @@
+<!-- cspell:ignore pathspecs noninteractive -->
+
+# Workspace Git prerequisite
+
+Every registered Coder workspace action uses `$preflightWorkspaceRepository` before project writes,
+Git synchronization, harness setup, execution, or server startup. Command argument validation runs first;
+help, version and usage errors do not run preflight. The same helper is available for the subsequent
+workspace `ptbk server` entrypoint and its `ptbk coder server` alias.
+
+| Registered action | Policy | Reason |
+| --- | --- | --- |
+| `ptbk init`, `coder init`, `coder initialize` | Initialization | Explicit authorization to create missing Git metadata, then reuse the existing additive initializer. |
+| `coder add` | Potentially mutating | Authors a prompt in the project queue. |
+| `coder plan` | Potentially mutating | Creates a planning workspace, runs a harness and saves reviewed PRDs. |
+| `coder generate-boilerplates` | Potentially mutating | Generates starter prompt files and scan caches. |
+| `coder find-refactor-candidates` | Potentially mutating | Scans source and generates refactor prompts. |
+| `coder run` | Potentially mutating | Runs tests and a harness, updates task state and may synchronize Git. |
+| `coder ping` | Potentially mutating | May install a harness, augment ignore rules, and create temporary harness artifacts. |
+| `coder server` | Potentially mutating | Starts the server and runner; browser edits also mutate PRDs. |
+| `coder verify` | Potentially mutating | Updates statuses, writes repair prompts and archives completed files. There is no separate archive action. |
+| `coder list` | Read-only | Lists ready prompts and optional runner filters. |
+| `coder find-unwritten` | Read-only | Inspects authoring placeholders. |
+| `coder find-fresh-emoji-tags` | Read-only | Scans existing tags without writing its optional cache. |
+| `coder run --dry-run`, `coder server --dry-run` | Read-only preview | Prints authoring work without installation, writes or server startup. |
+
+Discovery resolves the project directory once and uses Git to find the enclosing working tree, including
+linked worktrees and submodules. The project directory stays separate from the repository root: Books,
+prompts and initialization artifacts stay in the requested project; Git snapshots and pathspecs use the
+repository root. Isolated execution maps that project location into its temporary working tree and copies the
+project environment there. Unborn branches are valid. Discovery never requires a remote or a Git identity.
+
+Only genuinely missing repositories may be initialized. Missing Git, bare repositories, broken metadata,
+permission errors and ownership failures stop with diagnostics; no global `safe.directory` changes are made.
+Damaged inner metadata is rejected even when Git skips it and discovers a valid parent repository.
+Read-only operations warn for absent repositories. Other actions ask once in a terminal and continue after
+successful initialization. Declining or cancelling stops before normal effects. `--no-questions` and
+noninteractive input fail immediately and suggest `ptbk init`, `ptbk coder init`, or `git init`.
+
+Explicit initialization needs no Git confirmation, even with `--no-questions`. Existing Git metadata is reused
+without staging, committing or changing configuration. Optional `--auto-pull` runs after Git validation;
+`--commit` uses the existing scoped change snapshot, including before the first commit. Unrelated staged,
+unstaged and untracked files stay outside initialization commits. Remote synchronization still needs the
+user's configured remote and identity. Partial initialization failures report completed setup steps.
+
+Tests use temporary repositories and mocked prompts or harnesses. The packed CLI fixture exercises the
+top-level initializer and no-repository recovery outside this monorepo without network access.