@promptbook/cli 0.114.0-47 → 0.114.0-49

package/README.md

@@ -67,6 +67,21 @@ npm install --global @promptbook/cli
 
 CLI utilities for Promptbook that provide command-line tools for building, prettifying, and managing promptbook collections. After installation, you can use the `ptbk` command in your terminal.
 
+## Project commands
+
+`ptbk coder run --harness openai-codex` uses the invocation's current directory, its `agents/developer.book`, and
+the UTF-8 contents of its `AGENTS.md`. The explicit equivalent is
+`ptbk coder run --harness openai-codex --path . --agent ./agents/developer.book --context ./AGENTS.md`.
+`--path` selects an existing project directory; relative Book/context files resolve inside it, even in a nested
+Git project. Explicit context replaces the default; `--context ""` disables additional context. Missing implicit
+AGENTS.md warns and continues, while unreadable files or invalid explicit Book/context references fail clearly.
+
+`ptbk init` and `ptbk coder init` share initialization and preserve custom Books, context, scripts and settings.
+`coder plan` also defaults to Developer, retaining PRD-only permissions; `--agent ./agents/planner.book` selects
+Planner explicitly. `coder list` has no default Book filter. See the
+[command inventory and precedence reference](https://github.com/webgptorg/promptbook/blob/main/scripts/run-codex-prompts/README.md#shared-project-selection-and-command-inventory)
+for execution, authoring, listing, folder-runner, and legacy-command distinctions.
+
 ## 🎯 Purpose and Motivation
 
 The CLI package provides essential command-line tools for Promptbook development workflows. It enables developers to build optimized promptbook libraries, prettify promptbook files, and manage collections efficiently from the command line, making it easier to integrate Promptbook into development and deployment pipelines.
@@ -528,7 +543,7 @@ Promptbook Coder is **not another standalone coding model**. It is an orchestrat
 
 -   prompt files with explicit statuses like `[ ]`, `[^]`, `[x]`, and `[-]`
 -   automatic selection of the next runnable task, including priority support
--   optional shared repo context loaded from a file such as `AGENTS.md`
+-   shared project context loaded from `AGENTS.md` by default
 -   automatic `git add`, commit, and push after each successful prompt
 -   dedicated coding-agent Git identity and optional GPG signing
 -   verification and repair flow for work that is done, partial, or broken
@@ -550,7 +565,7 @@ Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treate
 #### Features
 
 -   **Multi-runner execution:** `openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`, `qwen-code`
--   **Context injection:** `--agent agents/coding/developer.book --context AGENTS.md` or inline extra instructions
+-   **Project defaults:** Developer, invocation cwd, and project `AGENTS.md`; `--agent`, `--path`, and `--context` independently override them
 -   **Reasoning control:** `--thinking-level low|medium|high|xhigh` for supported runners
 -   **Unattended or interactive runs:** default auto mode, or `--no-auto` to wait for user confirmation before each prompt
 -   **Git safety:** clean working tree check by default, or `--git-changes ignore` to keep the changes and `--git-changes continue` to resume an interrupted prompt
@@ -570,11 +585,11 @@ npx ts-node ./src/cli/test/ptbk.ts coder generate-boilerplates --template prompt
 
 npx ts-node ./src/cli/test/ptbk.ts coder generate-boilerplates --template prompts/templates/agents-server.md
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --auto-push
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --auto-push
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --git-changes ignore
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --git-changes ignore
 
 npx ts-node ./src/cli/test/ptbk.ts coder find-refactor-candidates
 
@@ -596,11 +611,11 @@ ptbk coder generate-boilerplates
 
 ptbk coder generate-boilerplates --template prompts/templates/common.md
 
-ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --test npm run test
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --check "npm run check"
 
-ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --auto-push
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --auto-push
 
-ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --test npm run test --git-changes ignore
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --check "npm run check" --git-changes ignore
 
 ptbk coder find-refactor-candidates
 
@@ -617,33 +632,52 @@ ptbk coder verify
 | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------ | ---- | ----- | ------------------------------------------------------------------------ |
 | `ptbk coder init`                     | Creates `prompts/`, `prompts/done/`, the project-generic template files materialized in `prompts/templates/` (currently `common.md`), and a starter `AGENTS.md`; ensures `.env` contains `CODING_AGENT_GIT_NAME`, `CODING_AGENT_GIT_EMAIL`, and `CODING_AGENT_GIT_SIGNING_KEY`; adds helper coder scripts to `package.json`; ensures `.gitignore` contains `/.promptbook`; and configures `.vscode/settings.json` to save pasted prompt images into `prompts/screenshots/`. |
 | `ptbk coder generate-boilerplates`    | Creates new prompt markdown files with fresh emoji tags so you can quickly fill in coding tasks; `--template` accepts either a built-in alias or a markdown file path relative to the project root.                                                                                                                                                                                                                                                                         |
-| `ptbk coder run`                      | Picks the next ready prompt, can run tests before coding to stop or repair pre-existing failures, appends optional context, runs it through the selected coding agent, can optionally verify each attempt with a shell test command and feed failing output back for retries, then marks success or failure, commits the result, and pushes only when `--auto-push` is enabled.                                                                                             |
+| `ptbk coder run`                      | Picks the next ready prompt, can run project checks before coding to stop or repair pre-existing failures, appends optional context, runs it through the selected coding agent, can optionally check each attempt with the project command and feed failing output back for retries, then marks success or failure, commits the result, and pushes only when `--auto-push` is enabled.                                                                                      |
 | `ptbk coder find-refactor-candidates` | Scans the repository for oversized or overpacked files and writes prompt files for likely refactors; `--level <xlow                                                                                                                                                                                                                                                                                                                                                         | low | medium | high | xhigh | extreme>` ranges from a very benevolent scan to a very aggressive sweep. |
 | `ptbk coder verify`                   | Walks through completed prompts, archives truly finished work, and adds follow-up repair prompts for unfinished results.                                                                                                                                                                                                                                                                                                                                                    |
 
 #### Most useful `ptbk coder run` flags
 
-| Flag                       | Purpose                                                                                                                                                                                |
-| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--harness <name>`         | Selects the coding harness.                                                                                                                                                            |
-| `--model <model>`          | Chooses the runner model; required for `openai-codex`, `gemini` and `qwen-code`, optional for `github-copilot`.                                                                        |
-| `--context <text-or-file>` | Appends extra instructions inline or from a file like `AGENTS.md`.                                                                                                                     |
-| `--test <command>`         | Runs a verification command after each prompt attempt and feeds failing output back for retries.                                                                                       |
-| `--test-before <mode>`     | Runs tests before coding: `no` (default), `yes-and-fail` (stop with results), or `yes-and-fix` (create one repair prompt first); defaults to `npm test` when enabled without `--test`. |
-| `--thinking-level <level>` | Sets reasoning effort for supported runners.                                                                                                                                           |
-| `--no-auto`                | Waits for user confirmation before each prompt instead of running automatically through the queue.                                                                                     |
-| `--git-changes <mode>`     | Decides what happens with a dirty working tree: `fail` (default), `ignore` to keep the changes, or `continue` to resume the single interrupted `[^]` prompt with them.                 |
-| `--priority <n>`           | Runs only prompts at or above the given priority.                                                                                                                                      |
-| `--dry-run`                | Prints which prompts are ready instead of executing them.                                                                                                                              |
-| `--allow-credits`          | Lets OpenAI Codex spend credits when required.                                                                                                                                         |
-| `--auto-push`              | Pushes each successful coding-agent commit to the configured remote.                                                                                                                   |
-| `--auto-migrate`           | Runs testing-server database migrations after each successful prompt.                                                                                                                  |
+A **check** is the project's aggregate validation: tests, linting, typechecking, builds, generated-code consistency,
+and other quality checks. `ptbk init` and `ptbk coder init` preserve an existing `scripts.check`, or compose available
+validation scripts and report their scope. Configure the failing setup placeholder if the project has none.
+
+```bash
+ptbk coder run --harness openai-codex --check "npm run check" --check-before yes-and-fix
+ptbk coder run --harness openai-codex --check "npm run lint && npm run build && npm test"
+```
+
+The default preflight mode remains `no`. Enabled preflight uses `npm run check` when no command is supplied;
+post-prompt verification remains opt-in. Initial checks and repairs use the same command and actual process result.
+Replace retired `--test` and `--test-before` with `--check` and `--check-before`. Init migrates recognized generated
+scripts while preserving custom validation. For conflicts or custom callers, it reports the exact entries/files to
+review: preserve the required validation in `check`, update references, then remove the unused legacy entry.
+Automation that invokes `npm run test-for-ptbk-coder` must switch to `npm run check`. Restart an already-running
+Coder invocation with the new flags to release its captured legacy command; initialization creates no compatibility alias.
+
+| Flag                       | Purpose                                                                                                                                                                                               |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--harness <name>`         | Selects the coding harness.                                                                                                                                                                           |
+| `--agent <book>`           | Selects the primary Book; defaults to the selected project's `agents/developer.book`.                                                                                                                 |
+| `--path <directory>`       | Selects the project; defaults to invocation cwd. Relative paths start there, not at the CLI installation or enclosing Git root.                                                                       |
+| `--model <model>`          | Chooses the runner model; required for `openai-codex`, `gemini` and `qwen-code`, optional for `github-copilot`.                                                                                       |
+| `--context <text-or-file>` | Replaces the default project `AGENTS.md` with inline instructions or a project-relative file; an empty value disables context.                                                                        |
+| `--check <command>`        | Runs a verification command after each prompt attempt and feeds failing output back for retries.                                                                                                      |
+| `--check-before <mode>`    | Runs project checks before coding: `no` (default), `yes-and-fail` (stop with results), or `yes-and-fix` (create one repair prompt first); defaults to `npm run check` when enabled without `--check`. |
+| `--thinking-level <level>` | Sets reasoning effort for supported runners.                                                                                                                                                          |
+| `--no-auto`                | Waits for user confirmation before each prompt instead of running automatically through the queue.                                                                                                    |
+| `--git-changes <mode>`     | Decides what happens with a dirty working tree: `fail` (default), `ignore` to keep the changes, or `continue` to resume the single interrupted `[^]` prompt with them.                                |
+| `--priority <n>`           | Runs only prompts at or above the given priority.                                                                                                                                                     |
+| `--dry-run`                | Prints which prompts are ready instead of executing them.                                                                                                                                             |
+| `--allow-credits`          | Lets OpenAI Codex spend credits when required.                                                                                                                                                        |
+| `--auto-push`              | Pushes each successful coding-agent commit to the configured remote.                                                                                                                                  |
+| `--auto-migrate`           | Runs testing-server database migrations after each successful prompt.                                                                                                                                 |
 
 #### Typical usage pattern
 
 1. Initialize once with `ptbk coder init`.
 2. Customize `prompts/templates/*.md` if needed, then create or write prompt files in `prompts/`.
-3. Customize the starter `AGENTS.md` with repository-specific instructions, then pass `--agent agents/coding/developer.book --context AGENTS.md`.
+3. Customize `agents/developer.book` and `AGENTS.md`; the runner selects both automatically. Use `--path` for another project or `--agent` and `--context` for explicit overrides.
 4. Run unattended batches by default, or pass `--no-auto` to confirm each prompt interactively.
 5. Finish with `ptbk coder verify` so resolved prompts are archived and broken ones get explicit repair follow-ups.
 

package/apps/agents-server/tests/e2e/mockSupabaseServer.cjs

@@ -21,6 +21,36 @@ const REST_PREFIX = '/rest/v1/';
  */
 const OBJECT_ACCEPT_HEADER = 'application/vnd.pgrst.object+json';
 
+/**
+ * Matches PostgREST LIKE patterns, including escaped literals and the `*` alias for `%`.
+ *
+ * @param {unknown} value
+ * @param {string} pattern
+ * @param {boolean} ignoreCase
+ * @returns {boolean}
+ */
+function matchesLikePattern(value, pattern, ignoreCase) {
+    if (value === null || value === undefined) {
+        return false;
+    }
+
+    let expression = '';
+    for (let index = 0; index < pattern.length; index++) {
+        const character = pattern[index];
+        if (character === '\\' && index + 1 < pattern.length) {
+            expression += pattern[++index].replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        } else if (character === '%' || character === '*') {
+            expression += '.*';
+        } else if (character === '_') {
+            expression += '.';
+        } else {
+            expression += character.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        }
+    }
+
+    return new RegExp(`^${expression}$`, ignoreCase ? 'is' : 's').test(String(value));
+}
+
 /**
  * In-memory table store used by the mocked Supabase API.
  */
@@ -92,6 +122,20 @@ function getTableRows(tableName) {
     return tables.get(tableName);
 }
 
+/**
+ * Decodes explicitly escaped filter values while preserving literal percent wildcards from URLSearchParams.
+ *
+ * @param {string} rawValue
+ * @returns {string}
+ */
+function decodeFilterValue(rawValue) {
+    try {
+        return decodeURIComponent(rawValue);
+    } catch {
+        return rawValue;
+    }
+}
+
 /**
  * Parses a PostgREST token into a primitive JavaScript value.
  *
@@ -99,7 +143,7 @@ function getTableRows(tableName) {
  * @returns {string | number | boolean | null}
  */
 function parseTokenValue(rawValue) {
-    const decoded = decodeURIComponent(rawValue);
+    const decoded = decodeFilterValue(rawValue);
 
     if (decoded === 'null') {
         return null;
@@ -236,6 +280,15 @@ function matchesRowFilters(row, searchParams) {
             continue;
         }
 
+        if (rawClause.startsWith('like.') || rawClause.startsWith('ilike.')) {
+            const ignoreCase = rawClause.startsWith('ilike.');
+            const pattern = decodeFilterValue(rawClause.slice(ignoreCase ? 'ilike.'.length : 'like.'.length));
+            if (!matchesLikePattern(row[columnName], pattern, ignoreCase)) {
+                return false;
+            }
+            continue;
+        }
+
         if (rawClause.startsWith('is.')) {
             const expectedValue = parseTokenValue(rawClause.slice('is.'.length));
             if (expectedValue === null) {
@@ -378,6 +431,26 @@ async function handleRestRequest(request, response, requestUrl) {
     if (method === 'POST') {
         const body = await parseJsonBody(request);
         const payloadRows = Array.isArray(body) ? body : body ? [body] : [];
+        if (tableName === 'User' || tableName.endsWith('_User')) {
+            // Match the database constraint so concurrent identity creation can retry the existing user.
+            // Validate the whole batch before inserting any rows, as PostgreSQL does for one statement.
+            const usernames = new Set(tableRows.map((row) => row.username));
+            for (const payloadRow of payloadRows) {
+                if (payloadRow.username === undefined || payloadRow.username === null) {
+                    continue;
+                }
+                if (usernames.has(payloadRow.username)) {
+                    sendJson(response, 409, {
+                        code: '23505',
+                        details: `Key (username)=(${payloadRow.username}) already exists.`,
+                        hint: null,
+                        message: `duplicate key value violates unique constraint "${tableName}_username_idx"`,
+                    });
+                    return;
+                }
+                usernames.add(payloadRow.username);
+            }
+        }
         const insertedRows = payloadRows.map((payloadRow) => {
             const nextRow = { ...payloadRow };
 
@@ -506,4 +579,8 @@ function main() {
     process.on('SIGTERM', shutdown);
 }
 
-main();
+module.exports = { createMockSupabaseServer };
+
+if (require.main === module) {
+    main();
+}

package/apps/agents-server/tests/e2e/support/ChatHistoryNavigationSupport.ts

@@ -46,6 +46,10 @@ type DelayNextMatchingRequestOptions = {
      * @private internal utility of ChatHistoryNavigationSupport
      */
     readonly isMatchingUrl: (url: string) => boolean;
+    /**
+     * Buffers the response before pausing, so navigation can cancel the browser request without blocking release.
+     */
+    readonly delayResponse?: boolean;
 };
 
 /**
@@ -236,6 +240,7 @@ async function delayNextMatchingRequest(
         }
 
         hasInterceptedTargetRequest = true;
+        const bufferedResponse = options.delayResponse ? await route.fetch() : undefined;
         markStarted?.();
 
         await new Promise<void>((resolve) => {
@@ -246,8 +251,12 @@ async function delayNextMatchingRequest(
         });
 
         try {
-            await route.continue();
-            await request.response().catch(() => null);
+            if (bufferedResponse) {
+                await route.fulfill({ response: bufferedResponse });
+            } else {
+                await route.continue();
+                await request.response().catch(() => null);
+            }
         } finally {
             markFinished?.();
         }
@@ -294,6 +303,7 @@ async function delayNextUserChatSnapshotRequest(page: Page, agentName: string, c
     return delayNextMatchingRequest(page, {
         method: 'GET',
         isMatchingUrl: (url) => isMatchingUserChatSnapshotRequest(url, agentName, chatId),
+        delayResponse: true,
     });
 }
 

package/apps/agents-server/tests/e2e/support/auth.ts

@@ -62,6 +62,12 @@ export async function loginAsAdmin(page: Page): Promise<void> {
     await page.getByLabel('Password').press('Enter');
     await expect(page.getByLabel('Username')).toBeHidden();
 
+    // Authentication is setup for these tests. Wait for the session and load it without racing the client refresh.
+    await expect
+        .poll(async () => (await page.context().cookies()).some((cookie) => cookie.name === 'sessionToken'))
+        .toBe(true);
+    await page.reload();
+
     const desktopAdminButton = page.getByRole('button', { name: /admin/i });
     if (await desktopAdminButton.isVisible().catch(() => false)) {
         return;