@promptbook/cli 0.114.0-5 → 0.114.0-50

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

@@ -0,0 +1,254 @@
+import { existsSync, readFileSync } from 'fs';
+import { realpath } from 'fs/promises';
+import { join } from 'path';
+import { resolveCoderAgent } from '../../../../../scripts/run-codex-prompts/common/resolveCoderAgent';
+import {
+    resolveCoderProjectContext,
+    type ResolvedCoderProjectContext,
+} from '../../../../../scripts/run-codex-prompts/common/resolveCoderProjectContext';
+import { DEFAULT_CODER_AGENT_ROLE } from '../coderAgentRole';
+import { CoderTeamRuntime } from '../../../../../scripts/run-codex-prompts/team/CoderTeamRuntime';
+import { appendCoderTeamEvent } from '../../../../../scripts/run-codex-prompts/team/createCoderTeamPromptRunner';
+import type { Usage } from '../../../../execution/Usage';
+import { addUsage } from '../../../../execution/utils/addUsage';
+import { NotFoundError } from '../../../../errors/NotFoundError';
+import { spaceTrim } from '../../../../utils/organization/spaceTrim';
+import type { NormalizedPromptRunnerSelectionCliOptions } from '../../common/promptRunnerCliOptions';
+import { COMMON_PROMPT_TEMPLATE_FILE_PATH, resolveCoderPromptTemplate } from '../boilerplateTemplates';
+import { assertPlanningPrdCommitScope } from './assertPlanningPrdCommitScope';
+import { createPlanningWorkspace } from './createPlanningWorkspace';
+import { resolvePlanningPath } from './resolvePlanningPath';
+import { PLANNING_PROTOCOL, type PlanningMessage } from './planningProtocol';
+import { discussPlanningTurn } from './discussPlanningTurn';
+import { preparePlanningChanges, type PlanningChange } from './preparePlanningChanges';
+import { readPlanningContext } from './readPlanningContext';
+import { assertPlanningHarnessSupported, runPlanningHarness } from './runPlanningHarness';
+import { savePlanningChanges } from './savePlanningChanges';
+
+/**
+ * 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 async 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 = runPlanningHarness,
+): Promise<ReadonlyMap<string, string>> {
+    const projectPath = await realpath(options.projectPath);
+    assertPlanningHarnessSupported(options.agentName);
+    const projectContext = options.projectContext ?? (await resolveCoderProjectContext({ ...options, projectPath }));
+    const agent = await resolveCoderAgent(options.agent, projectPath, {
+        defaultRole: DEFAULT_CODER_AGENT_ROLE,
+        isInitializationAllowed: false,
+        signal: io.signal,
+    });
+    if (!existsSync(join(projectPath, 'prompts'))) {
+        throw new NotFoundError(spaceTrim('Planning requires `prompts/`. Run `ptbk coder init` first.'));
+    }
+    if (!agent) throw new NotFoundError(spaceTrim('Primary Book is missing. Run `ptbk coder init`.'));
+    resolvePlanningPath(projectPath, 'prompts');
+    const templateOption =
+        options.template ??
+        (existsSync(join(projectPath, COMMON_PROMPT_TEMPLATE_FILE_PATH))
+            ? COMMON_PROMPT_TEMPLATE_FILE_PATH
+            : undefined);
+    const template = await resolveCoderPromptTemplate({ projectPath, templateOption });
+    const workspacePath = await createPlanningWorkspace(projectPath);
+    const primaryUsage: Usage[] = [];
+    const team = new CoderTeamRuntime({
+        agent: agent.teamAgent,
+        taskId: workspacePath,
+        signal: io.signal,
+        onEvent: (event) => appendCoderTeamEvent(join(workspacePath, 'runtime.log'), event),
+        execute: async ({ scope, message, context, reportUsage }) => {
+            const consultationHistory: PlanningMessage[] = [
+                {
+                    role: 'context',
+                    content: `Selected Book (${scope.agent.name}):\n${
+                        scope.agent.systemMessage
+                    }\nAvailable TEAM tools: ${JSON.stringify(scope.agent.teammates.map(({ tool }) => tool))}`,
+                },
+                { role: 'user', content: JSON.stringify({ message, context }) },
+            ];
+            const reply = await discussPlanningTurn({
+                projectPath,
+                history: consultationHistory,
+                signal: scope.signal,
+                team: scope,
+                isAdviser: true,
+                infer: () =>
+                    harness({
+                        ...options,
+                        workspacePath,
+                        signal: scope.signal,
+                        onUsage: reportUsage,
+                        prompt: `${PLANNING_PROTOCOL}\nYou are a TEAM adviser. Return advice in message, no proposals.\nConversation (JSON data):\n${JSON.stringify(
+                            consultationHistory,
+                        )}`,
+                    }),
+            });
+            return { answer: reply.message };
+        },
+    });
+    try {
+        const history: PlanningMessage[] = [
+            {
+                role: 'context',
+                content: `Selected Book (${agent.agentName}):\n${
+                    agent.systemMessage
+                }\nAvailable TEAM tools: ${JSON.stringify(
+                    agent.teamAgent.teammates.map(({ tool }) => tool),
+                )}\n\nSelected PRD template:\n${template.content}`,
+            },
+            { role: 'context', content: await readPlanningContext(projectPath, { kind: 'list', path: '.' }) },
+        ];
+        if (projectContext.context !== undefined) {
+            history.push({ role: 'context', content: projectContext.context });
+        }
+        for (const path of ['README.md']) {
+            if (existsSync(join(projectPath, path))) {
+                history.push({
+                    role: 'context',
+                    content: `${path}:\n${await readPlanningContext(projectPath, {
+                        kind: 'read',
+                        path,
+                        startLine: 1,
+                        lineCount: 200,
+                    })}`,
+                });
+            }
+        }
+        const savedContents = new Map<string, string>();
+        let pending: PlanningChange[] = [];
+        io.write(
+            `${agent.agentName}: Discuss features and review PRD proposals. /save applies the preview; /draft saves unresolved drafts; /discard drops it; /exit ends. Ctrl+C cancels.\n`,
+        );
+        while (!io.signal.aborted) {
+            const message = (await io.readMessage())?.trim();
+            if (message === undefined || ['/exit', 'exit', 'quit'].includes(message)) break;
+            if (!message) continue;
+            if (message === '/discard') {
+                pending = [];
+                history.push({ role: 'context', content: 'The user discarded the unsaved proposals.' });
+                io.write('Discarded unsaved proposals.');
+                continue;
+            }
+            if (message === '/save' || message === '/draft') {
+                if (!pending.length) {
+                    io.write('There are no proposed changes to save.');
+                    continue;
+                }
+                if (io.signal.aborted) break;
+                try {
+                    if (options.preexistingChangedPaths) {
+                        await assertPlanningPrdCommitScope(
+                            projectPath,
+                            pending,
+                            savedContents,
+                            options.preexistingChangedPaths,
+                        );
+                    }
+                    if (io.signal.aborted) break;
+                    const paths = savePlanningChanges(projectPath, workspacePath, pending, message === '/draft');
+                    for (const path of paths)
+                        savedContents.set(path, readFileSync(resolvePlanningPath(projectPath, path), 'utf-8'));
+                    history.push({
+                        role: 'context',
+                        content: `Saved ${message === '/draft' ? 'draft' : 'reviewed'} PRDs:\n${paths.join('\n')}`,
+                    });
+                    io.write(`Saved:\n${paths.join('\n')}`);
+                    pending = [];
+                } catch (error) {
+                    io.write(`Could not save: ${(error as Error).message}`);
+                }
+                continue;
+            }
+            // Continuing the discussion invalidates any earlier preview so a later save cannot apply stale decisions.
+            pending = [];
+            history.push({ role: 'user', content: message });
+            io.write(`${agent.agentName} is reading and thinking…`);
+            const reply = await discussPlanningTurn({
+                projectPath,
+                history,
+                signal: io.signal,
+                write: io.write,
+                team: team.root,
+                infer: () =>
+                    harness({
+                        ...options,
+                        workspacePath,
+                        signal: io.signal,
+                        onUsage: (item) => {
+                            primaryUsage.push(item);
+                        },
+                        prompt: `${PLANNING_PROTOCOL}\n\nConversation (JSON data):\n${JSON.stringify(history)}`,
+                    }),
+            });
+            if (io.signal.aborted) break;
+            io.write(`${agent.agentName}: ${reply.message}`);
+            pending = await preparePlanningChanges(projectPath, reply.proposals, templateOption);
+            for (const change of pending) io.write(formatPlanningPreview(change));
+            if (pending.length)
+                io.write(
+                    'Review the changes above. /save applies this preview; /draft saves drafts; continue discussing to revise it.',
+                );
+        }
+        io.write(
+            io.signal.aborted
+                ? 'Planning cancelled. Saved PRDs remain intact.'
+                : 'Planning ended. Unsaved proposals were discarded.',
+        );
+        return savedContents;
+    } finally {
+        await team.close();
+        await appendCoderTeamEvent(join(workspacePath, 'runtime.log'), {
+            type: 'team_summary',
+            sessionId: team.sessionId,
+            taskId: workspacePath,
+            invocationId: team.root.invocationId,
+            agent: agent.agentName,
+            data: { usage: addUsage(...primaryUsage, team.usage), isAggregate: true },
+        });
+    }
+}
+
+/** Shows exact before/after content, including lifecycle lines, without requiring an external diff command. */
+function formatPlanningPreview(change: PlanningChange): string {
+    if (change.before === null)
+        return `Create ${change.path}\n${change.after
+            .split(/\r?\n/u)
+            .map((line) => `+ ${line}`)
+            .join('\n')}`;
+    const before = change.before.split(/\r?\n/u);
+    const after = change.after.split(/\r?\n/u);
+    let start = 0;
+    while (start < before.length && start < after.length && before[start] === after[start]) start++;
+    let end = 0;
+    while (
+        end < before.length - start &&
+        end < after.length - start &&
+        before[before.length - end - 1] === after[after.length - end - 1]
+    )
+        end++;
+    return `Edit ${change.path}\n@@ line ${start + 1} @@\n${[
+        ...before.slice(start, before.length - end).map((line) => `- ${line}`),
+        ...after.slice(start, after.length - end).map((line) => `+ ${line}`),
+    ].join('\n')}`;
+}

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

@@ -0,0 +1,105 @@
+import {
+    closeSync,
+    existsSync,
+    fsyncSync,
+    linkSync,
+    openSync,
+    readFileSync,
+    renameSync,
+    unlinkSync,
+    writeFileSync,
+} from 'fs';
+import { join } from 'path';
+import { NotAllowed } from '../../../../errors/NotAllowed';
+import { spaceTrim } from '../../../../utils/organization/spaceTrim';
+import { assertPlanningRuntimePath } from './assertPlanningRuntimePath';
+import { resolvePlanningPath } from './resolvePlanningPath';
+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 function savePlanningChanges(
+    projectPath: string,
+    workspacePath: string,
+    changes: ReadonlyArray<PlanningChange>,
+    isDraft: boolean,
+): string[] {
+    assertPlanningRuntimePath(projectPath, workspacePath);
+    const prepared = changes.map((change, index) => {
+        const path = resolvePlanningPath(projectPath, change.path, true);
+        const current = existsSync(path) ? readFileSync(path, 'utf-8') : null;
+        if (current !== change.before) {
+            throw new NotAllowed(
+                spaceTrim(
+                    `\`${change.path}\` changed since the preview. Nothing was saved; ask Planner to read it again.`,
+                ),
+            );
+        }
+        if (isDraft && !change.draft) {
+            throw new NotAllowed(
+                spaceTrim(
+                    `\`${change.path}\` has routing metadata that cannot be converted to [-] safely. Save the reviewed ready revision or keep discussing it.`,
+                ),
+            );
+        }
+        return {
+            ...change,
+            planningPath: change.path,
+            path,
+            content: isDraft ? change.draft : change.after,
+            temporaryPath: join(workspacePath, `save-${index}.tmp`),
+        };
+    });
+    const saved: typeof prepared = [];
+    try {
+        for (const change of prepared) {
+            writeDurableFile(change.temporaryPath, change.content);
+        }
+        for (const change of prepared) {
+            resolvePlanningPath(projectPath, change.planningPath, true);
+            const current = existsSync(change.path) ? readFileSync(change.path, 'utf-8') : null;
+            if (current !== change.before) {
+                throw new NotAllowed(
+                    spaceTrim(`\`${change.planningPath}\` changed while saving. Review a fresh preview.`),
+                );
+            }
+            if (change.before === null) {
+                // Hard-link creation is exclusive: unlike rename, it cannot overwrite a concurrently created task.
+                linkSync(change.temporaryPath, change.path);
+                saved.push(change);
+                unlinkSync(change.temporaryPath);
+            } else {
+                renameSync(change.temporaryPath, change.path);
+                saved.push(change);
+            }
+        }
+    } catch (error) {
+        for (const change of saved.reverse()) {
+            if (change.before === null) unlinkSync(change.path);
+            else {
+                writeDurableFile(change.temporaryPath, change.before);
+                renameSync(change.temporaryPath, change.path);
+            }
+        }
+        throw error;
+    } finally {
+        for (const change of prepared) {
+            if (existsSync(change.temporaryPath)) unlinkSync(change.temporaryPath);
+        }
+    }
+    return changes.map((change) => change.path);
+}
+
+/** Flushes a staged PRD before publishing its directory entry. */
+function writeDurableFile(path: string, content: string): void {
+    const descriptor = openSync(path, 'wx');
+    try {
+        writeFileSync(descriptor, content, 'utf-8');
+        fsyncSync(descriptor);
+    } finally {
+        closeSync(descriptor);
+    }
+}

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

@@ -0,0 +1,304 @@
+import {
+    assertProjectCheckScriptsAreConfigured,
+    CHECK_SETUP_PLACEHOLDER_COMMAND,
+    CoderCheckSetupError,
+    isCheckSetupRequired,
+} from '../../../../scripts/run-codex-prompts/checks/projectCheck';
+import { getDefaultCoderPackageJsonScripts } from './getDefaultCoderPackageJsonScripts';
+import { projectScriptReferences } from '../../../../scripts/run-codex-prompts/checks/projectScriptReferences';
+
+/** Old initialized aggregate entries, used only at this migration boundary. */
+const LEGACY_CHECK_SCRIPT_NAMES = ['test-for-ptbk-coder', 'check-for-ptbk-coder'] as const;
+
+/** Conventional project validation scripts, ordered from lightweight checks to tests. */
+const VALIDATION_SCRIPT_GROUPS = [
+    ['lint', 'test-lint'],
+    ['typecheck', 'type-check', 'type-checking', 'check-types', 'test-types'],
+    ['build', 'test-build'],
+] as const;
+
+/** Conventional leaf test families used when the project has no usable test aggregate. */
+const TEST_SCRIPT_GROUPS = [
+    ['test-unit', 'test:unit'],
+    ['test-integration', 'test:integration'],
+    ['test-e2e', 'test:e2e'],
+] as const;
+
+/** Script names that must never be reached by a generated aggregate. */
+const NON_VALIDATION_SCRIPT_PATTERN =
+    /^(?:check$|coder:|(?:dev|start|serve|watch|deploy|publish|install|preinstall|postinstall|prepare|reset|clean)(?:$|[:-]))/iu;
+
+/** Clearly unsuitable shell bodies are excluded even under a conventional validation name. */
+const UNSUITABLE_VALIDATION_BODY_PATTERN =
+    /(?:\b(?:ptbk|promptbook)\s+coder\s+(?:run|fix)|\bcoder:(?:run|fix)\b|--watch(?:All)?(?:\b|=)|\b(?:watch|nodemon|concurrently|serve|deploy|publish|install|reset|rm|rmdir|del|remove-item)\b|--if-present|\|\||(?:^|[^&])&(?:$|[^&])|;|\bexit\s+0\b)/iu;
+
+/** Npm lifecycle hooks that run implicitly before and after a selected project script. */
+const SCRIPT_LIFECYCLE_PREFIXES = ['pre', 'post'] as const;
+
+/** 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 function prepareCoderPackageJsonScripts(
+    existing: Readonly<Record<string, string>>,
+    externalCallers: Readonly<Record<string, ReadonlyArray<string>>> = {},
+): PreparedCoderPackageJsonScripts {
+    const scripts = { ...existing };
+    const migrationInstructions: string[] = [];
+    const legacyNames = LEGACY_CHECK_SCRIPT_NAMES.filter((name) =>
+        Object.prototype.hasOwnProperty.call(existing, name),
+    );
+    let checkScriptSummary: string;
+
+    if (Object.prototype.hasOwnProperty.call(existing, 'check')) {
+        checkScriptSummary = 'Preserved project scripts.check exactly; Coder executes npm run check.';
+    } else if (legacyNames.length > 0) {
+        const sourceName = legacyNames[0]!;
+        const isRecursive =
+            scriptReaches(sourceName, 'check', existing, new Set()) ||
+            scriptReaches(sourceName, sourceName, existing, new Set()) ||
+            scriptReaches(sourceName, 'coder:run', existing, new Set()) ||
+            scriptReaches(sourceName, 'coder:fix', existing, new Set());
+        const conflictingLifecycleNames = SCRIPT_LIFECYCLE_PREFIXES.filter(
+            (prefix) =>
+                existing[`${prefix}check`] !== undefined &&
+                existing[`${prefix}${sourceName}`] !== existing[`${prefix}check`],
+        ).map((prefix) => `${prefix}check`);
+        scripts.check =
+            isRecursive || conflictingLifecycleNames.length > 0
+                ? CHECK_SETUP_PLACEHOLDER_COMMAND
+                : existing[sourceName]!;
+        if (!isRecursive && conflictingLifecycleNames.length === 0) {
+            // npm runs these hooks implicitly. Preserve their bodies as well as the main script's scope.
+            for (const prefix of SCRIPT_LIFECYCLE_PREFIXES) {
+                const legacyHook = existing[`${prefix}${sourceName}`];
+                if (legacyHook !== undefined) scripts[`${prefix}check`] = legacyHook;
+            }
+        }
+        checkScriptSummary = isRecursive
+            ? `Kept recursive scripts.${sourceName} unchanged; configure scripts.check with validation that does not call check or Coder recursively.`
+            : conflictingLifecycleNames.length > 0
+            ? `Kept scripts.${sourceName} and conflicting ${conflictingLifecycleNames.join(
+                  ', ',
+              )} hooks unchanged; configure scripts.check and its lifecycle hooks to preserve the required validation.`
+            : `Preserved scripts.${sourceName}'s validation command and npm lifecycle hooks in scripts.check: ${scripts.check}`;
+    } else {
+        const selectedScripts = selectValidationScripts(existing);
+        scripts.check =
+            selectedScripts.length > 0
+                ? selectedScripts.map((name) => (name === 'test' ? 'npm test' : `npm run ${name}`)).join(' && ')
+                : CHECK_SETUP_PLACEHOLDER_COMMAND;
+        checkScriptSummary =
+            selectedScripts.length > 0
+                ? `Generated scripts.check from the available validation scripts (${selectedScripts.join(', ')}): ${
+                      scripts.check
+                  }`
+                : 'No usable validation scripts found. scripts.check contains a failing setup placeholder; configure it before running Coder.';
+    }
+
+    for (const [name, command] of Object.entries(existing)) {
+        if (
+            ['check', ...legacyNames].some(
+                (verificationName) =>
+                    name === verificationName ||
+                    SCRIPT_LIFECYCLE_PREFIXES.some((prefix) => name === `${prefix}${verificationName}`),
+            )
+        )
+            continue;
+        const migratedCaller = migrateGeneratedCoderRunScript(command);
+        if (migratedCaller !== undefined) {
+            // A different existing check is authoritative, but changing a custom legacy caller's scope is not safe.
+            const referencedLegacyName = legacyNames.find((legacyName) => command.includes(legacyName));
+            const isConflictingCustomCheck =
+                referencedLegacyName !== undefined &&
+                !isLegacyCheckScopePreserved(referencedLegacyName, scripts) &&
+                !isUnchangedLegacyCheckDefault(referencedLegacyName, scripts);
+            if (!isConflictingCustomCheck) scripts[name] = migratedCaller;
+        }
+    }
+
+    for (const legacyName of legacyNames) {
+        const callers = Object.entries(scripts)
+            .filter(([name, command]) => name !== legacyName && command.includes(legacyName))
+            .map(([name]) => name);
+        const isPreservedScope = isLegacyCheckScopePreserved(legacyName, scripts);
+        const isObsoleteGeneratedDefault =
+            isUnchangedLegacyCheckDefault(legacyName, scripts) && !isCheckSetupRequired(scripts.check!);
+        const files = externalCallers[legacyName] ?? [];
+        if (callers.length === 0 && files.length === 0 && (isPreservedScope || isObsoleteGeneratedDefault)) {
+            delete scripts[legacyName];
+            for (const prefix of SCRIPT_LIFECYCLE_PREFIXES) delete scripts[`${prefix}${legacyName}`];
+        } else {
+            migrationInstructions.push(
+                `Kept scripts.${legacyName}${
+                    callers.length ? `; referenced by scripts.${callers.join(', scripts.')}` : ''
+                }${files.length ? `; referenced by ${files.join(', ')}` : ''}${
+                    !isPreservedScope && !isObsoleteGeneratedDefault
+                        ? '; its custom command or npm lifecycle hooks differ from scripts.check'
+                        : ''
+                }. Preserve its required validation and pre/post hooks in scripts.check, update those callers to npm run check, then remove scripts.${legacyName} and its unused lifecycle hooks.`,
+            );
+        }
+    }
+    for (const [name, command] of Object.entries(scripts)) {
+        if (
+            /\b(?:ptbk|promptbook)\s+coder\s+(?:run|server)\b|\brun-codex-prompts\b/u.test(command) &&
+            /--test(?:-before)?(?:\s|=|$)/u.test(command)
+        ) {
+            migrationInstructions.push(
+                `Update scripts.${name}: replace --test with --check and --test-before with --check-before; review its shell expression manually. Existing command was preserved: ${command}`,
+            );
+        }
+    }
+
+    let isCheckConfigured = true;
+    try {
+        assertProjectCheckScriptsAreConfigured(scripts);
+    } catch (error) {
+        if (!(error instanceof CoderCheckSetupError)) throw error;
+        isCheckConfigured = false;
+        checkScriptSummary += ` Additional setup required: ${error.message}`;
+    }
+
+    return {
+        scripts,
+        checkScriptSummary,
+        migrationInstructions,
+        isCheckConfigured,
+    };
+}
+
+/** Determines whether both the legacy command and its implicit npm validation hooks have been preserved. */
+function isLegacyCheckScopePreserved(name: string, scripts: Readonly<Record<string, string>>): boolean {
+    return (
+        scripts[name] === scripts.check &&
+        SCRIPT_LIFECYCLE_PREFIXES.every((prefix) => scripts[`${prefix}${name}`] === scripts[`${prefix}check`])
+    );
+}
+
+/** Recognizes the generated default only when no custom lifecycle hooks extend its validation scope. */
+function isUnchangedLegacyCheckDefault(name: string, scripts: Readonly<Record<string, string>>): boolean {
+    return (
+        scripts[name] === 'npm test' &&
+        SCRIPT_LIFECYCLE_PREFIXES.every((prefix) => scripts[`${prefix}${name}`] === undefined)
+    );
+}
+
+/**
+ * Recognizes unchanged generated run scripts, including the previous explicit Developer/context defaults.
+ * Unknown shell expressions and custom harness configuration are preserved for manual migration.
+ */
+function migrateGeneratedCoderRunScript(command: string): string | undefined {
+    const prefix = 'npx ptbk coder run --harness openai-codex --thinking-level max';
+    const defaultArguments = ['', ' --agent agents/developer.book --context AGENTS.md'];
+    const verificationArguments = [
+        ' --test-before yes-and-fix',
+        ...LEGACY_CHECK_SCRIPT_NAMES.map((name) => ` --test "npm run ${name}" --test-before yes-and-fix`),
+        ...LEGACY_CHECK_SCRIPT_NAMES.map((name) => ` --check "npm run ${name}" --check-before yes-and-fix`),
+    ];
+    const isGenerated = defaultArguments.some((defaults) =>
+        verificationArguments.some((verification) => command === prefix + defaults + verification),
+    );
+    return isGenerated ? getDefaultCoderPackageJsonScripts()['coder:run'] : undefined;
+}
+
+/** Selects safe conventional scripts, avoiding duplicates already reached by another selected aggregate. */
+function selectValidationScripts(scripts: Readonly<Record<string, string>>): string[] {
+    if (
+        SCRIPT_LIFECYCLE_PREFIXES.some(
+            (prefix) =>
+                scripts[`${prefix}check`] !== undefined &&
+                !isUsableValidationScript(`${prefix}check`, scripts, new Set()),
+        )
+    )
+        return [];
+    const selected: string[] = [];
+    for (const group of VALIDATION_SCRIPT_GROUPS) {
+        const name = group.find((candidate) => isUsableValidationScript(candidate, scripts, new Set()));
+        if (name !== undefined) selected.push(name);
+    }
+    if (isUsableValidationScript('test', scripts, new Set())) selected.push('test');
+    else
+        for (const group of TEST_SCRIPT_GROUPS) {
+            const name = group.find((candidate) => isUsableValidationScript(candidate, scripts, new Set()));
+            if (name !== undefined) selected.push(name);
+        }
+    return selected.filter(
+        (name) => !selected.some((other) => other !== name && scriptReaches(other, name, scripts, new Set())),
+    );
+}
+
+/** Inspects each body, referenced script, and implicit lifecycle hook before including it in an aggregate. */
+function isUsableValidationScript(
+    name: string,
+    scripts: Readonly<Record<string, string>>,
+    visited: ReadonlySet<string>,
+): boolean {
+    const command = scripts[name];
+    if (
+        !command ||
+        visited.has(name) ||
+        NON_VALIDATION_SCRIPT_PATTERN.test(name) ||
+        isCheckSetupRequired(command) ||
+        UNSUITABLE_VALIDATION_BODY_PATTERN.test(command)
+    )
+        return false;
+    if (
+        command.split('&&').every((part) => /^\s*(?:echo|printf|true|:)(?:\s|$)/iu.test(part)) ||
+        /\bprocess\.exit\(\s*0\s*\)/u.test(command)
+    )
+        return false;
+    if (
+        /\b(?:vite|next|astro|webpack-dev-server)\s+(?:dev|start|serve)\b/iu.test(command) ||
+        /(?:^|&&)\s*(?:vite|webpack-dev-server)(?:\s*$|\s+--)/iu.test(command) ||
+        (/\bvitest\b/iu.test(command) && !/\bvitest\s+run\b/iu.test(command))
+    )
+        return false;
+    const nextVisited = new Set([...visited, name]);
+    const references = projectScriptReferences(command);
+    // Ambiguous package-manager flags and cwd switches cannot be composed confidently as root validation.
+    if (
+        /\b(?:npm|pnpm|yarn)\s+(?:--|run(?:-script)?\s+--)/u.test(command) ||
+        (/\b(?:npm|pnpm|yarn)\b/u.test(command) && references.length === 0)
+    )
+        return false;
+    if (references.some((reference) => !isUsableValidationScript(reference, scripts, nextVisited))) return false;
+    return SCRIPT_LIFECYCLE_PREFIXES.every((prefix) => {
+        const lifecycleName = `${prefix}${name}`;
+        return scripts[lifecycleName] === undefined || isUsableValidationScript(lifecycleName, scripts, nextVisited);
+    });
+}
+
+/** Checks whether a selected aggregate already reaches another selected script. */
+function scriptReaches(
+    name: string,
+    target: string,
+    scripts: Readonly<Record<string, string>>,
+    visited: ReadonlySet<string>,
+): boolean {
+    if (visited.has(name)) return false;
+    const nextVisited = new Set([...visited, name]);
+    const command = scripts[name] ?? '';
+    if (
+        (target === 'coder:run' && /\b(?:ptbk|promptbook)\s+coder\s+run\b/u.test(command)) ||
+        (target === 'coder:fix' && /\b(?:ptbk|promptbook)\s+coder\s+fix\b/u.test(command))
+    )
+        return true;
+    const references = [
+        ...projectScriptReferences(command),
+        ...SCRIPT_LIFECYCLE_PREFIXES.map((prefix) => `${prefix}${name}`).filter(
+            (lifecycleName) => scripts[lifecycleName] !== undefined,
+        ),
+    ];
+    return references.some(
+        (reference) => reference === target || scriptReaches(reference, target, scripts, nextVisited),
+    );
+}

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

@@ -0,0 +1,14 @@
+import colors from 'colors';
+import { formatUnknownErrorDetails } from '../../../../scripts/run-codex-prompts/common/formatUnknownErrorDetails';
+
+/**
+ * Prints why a coder run has ended to the terminal.
+ *
+ * @private internal utility of `coder run` and `coder server` commands
+ */
+export function printCoderRunFailure(error: Error): void {
+    console.error(colors.bgRed(`${error.name}`));
+    console.error(colors.red(formatUnknownErrorDetails(error)));
+}
+
+// Note: [🟡] Code for coder failure reporting [printCoderRunFailure](src/cli/cli-commands/coder/printCoderRunFailure.ts) should never be published outside of `@promptbook/cli`