@promptbook/utils 0.114.0-5 → 0.114.0-50

package/README.md

@@ -710,7 +710,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
@@ -720,22 +720,22 @@ In short: tools like Claude Code, Codex, or GitHub Copilot are the **engines**;
 
 #### How the workflow works
 
-1. `ptbk coder init` prepares the project for the coder workflow, seeds project-owned generic templates in `prompts/templates/`, creates a starter `AGENTS.md` context file, adds helper `npm run coder:*` scripts, ensures `.gitignore` ignores `/.promptbook`, and configures VS Code prompt screenshots in `prompts/screenshots/`.
+1. `ptbk coder init` prepares the project for the coder workflow, seeds project-owned generic templates in `prompts/templates/`, creates a starter `AGENTS.md` context file, adds helper `npm run coder:*` scripts, ensures `.gitignore` ignores `node_modules` and `/.promptbook`, creates missing `.gitattributes` for LF line endings, and configures VS Code prompt screenshots in `prompts/screenshots/`.
 2. `ptbk coder generate-boilerplates` creates prompt files in `prompts/`.
 3. You replace placeholder `@@@` sections with real coding tasks.
 4. `ptbk coder run` sends the next ready `[ ]` prompt to the selected coding agent and immediately marks it as in progress `[^]`, naming the harness, the model and the step which is running.
 5. Promptbook Coder marks the prompt as done `[x]`, records runner metadata, then stages, commits, and pushes the resulting changes.
 6. `ptbk coder verify` reviews completed prompts, archives finished files to `prompts/done/`, and appends a repair prompt when more work is needed.
 
-Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treated as not fully written, and prompts with more `!` markers have higher priority. A prompt left as `[^]` was interrupted in the middle of its implementation — the in-progress status is never reverted, so a killed or crashed coder always leaves that signal behind.
+Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treated as not fully written, and prompts with more `!` markers have higher priority. A prompt left as `[^]` was interrupted in the middle of its implementation — the in-progress status is never reverted, so a killed or crashed coder always leaves that signal behind, and `--git-changes continue` resumes exactly that prompt with its uncommitted changes still in place.
 
 #### Features
 
--   **Multi-runner execution:** `openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`
--   **Context injection:** `--agent agents/coding/developer.book --context AGENTS.md` or inline extra instructions
+-   **Multi-runner execution:** `openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`, `qwen-code`
+-   **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, optional `--ignore-git-changes`
+-   **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
 -   **Opt-in remote pushes:** commits stay local unless you explicitly pass `--auto-push`
 -   **Prompt triage:** `--priority` to process only more important tasks first
 -   **Failure logging:** failed runs write a neighboring `.error.log`
@@ -752,11 +752,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 --ignore-git-changes
+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
 
@@ -778,11 +778,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 --ignore-git-changes
+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
 
@@ -791,41 +791,60 @@ ptbk coder find-refactor-candidates --level xhigh
 ptbk coder verify
 ```
 
-`ptbk coder init` also bootstraps a starter `AGENTS.md`, adds `package.json` scripts for the four main coder commands, adds the shared `/.promptbook` temp ignore to `.gitignore`, and configures `.vscode/settings.json` so pasted images from `prompts/*.md` land in `prompts/screenshots/`.
+`ptbk coder init` also bootstraps a starter `AGENTS.md`, adds `package.json` scripts for the four main coder commands, adds `node_modules` and the shared `/.promptbook` temp ignore to `.gitignore`, and configures `.vscode/settings.json` so pasted images from `prompts/*.md` land in `prompts/screenshots/`. It creates a missing `.gitattributes` with `* text=auto eol=lf` and preserves existing attributes.
 
 #### What each command does
 
 | Command                               | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------ | ---- | ----- | ------------------------------------------------------------------------ |
-| `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 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 `node_modules` and `/.promptbook`; creates missing `.gitattributes` with `* text=auto eol=lf`; 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` and `gemini`, 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.                                                                                     |
-| `--ignore-git-changes`     | Disables the clean-working-tree guard.                                                                                                                                                 |
-| `--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/esm/index.es.js

@@ -17,7 +17,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.114.0-5';
+const PROMPTBOOK_ENGINE_VERSION = '0.114.0-50';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -5143,17 +5143,28 @@ function $getCurrentDate() {
 }
 
 /**
- * Handles debounce.
+ * Creates a debounced function that runs after calls have been quiet for the given delay.
  *
  * @public exported from `@promptbook/utils`
  */
 function debounce(fn, delay) {
     let timeout = null;
-    return (...args) => {
-        if (timeout)
-            clearTimeout(timeout);
-        timeout = setTimeout(() => fn(...args), delay);
+    const cancel = () => {
+        if (timeout === null) {
+            return;
+        }
+        clearTimeout(timeout);
+        timeout = null;
+    };
+    const debounced = (...args) => {
+        cancel();
+        timeout = setTimeout(() => {
+            timeout = null;
+            fn(...args);
+        }, delay);
     };
+    debounced.cancel = cancel;
+    return debounced;
 }
 
 /**