@holdpoint/cli 0.1.0-alpha.2 → 0.1.0-alpha.20

package/dist/prompt-EQ5IFADN.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+// src/lib/prompt.ts
+import readline from "readline/promises";
+import { stdin, stdout } from "process";
+async function promptYesNo(question, defaultYes = true) {
+  if (!stdout.isTTY || !stdin.isTTY) {
+    return defaultYes;
+  }
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    const suffix = defaultYes ? " [Y/n] " : " [y/N] ";
+    const answer = (await rl.question(question + suffix)).trim().toLowerCase();
+    if (answer === "") return defaultYes;
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+export {
+  promptYesNo
+};
+//# sourceMappingURL=prompt-EQ5IFADN.js.map

package/dist/prompt-EQ5IFADN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lib/prompt.ts"],"sourcesContent":["import readline from \"node:readline/promises\";\nimport { stdin, stdout } from \"node:process\";\n\n/**\n * Ask a yes/no question on the terminal and resolve to true/false.\n *\n * Defaults to true on empty input (`Y/n` style). Returns `defaultYes` and\n * skips the prompt entirely when stdout isn't a TTY (CI, piped invocation,\n * agent hook) so we never block on input nobody can provide. Callers that\n * need different non-TTY behaviour should check `stdout.isTTY` first.\n */\nexport async function promptYesNo(question: string, defaultYes = true): Promise<boolean> {\n  if (!stdout.isTTY || !stdin.isTTY) {\n    return defaultYes;\n  }\n  const rl = readline.createInterface({ input: stdin, output: stdout });\n  try {\n    const suffix = defaultYes ? \" [Y/n] \" : \" [y/N] \";\n    const answer = (await rl.question(question + suffix)).trim().toLowerCase();\n    if (answer === \"\") return defaultYes;\n    return answer === \"y\" || answer === \"yes\";\n  } finally {\n    rl.close();\n  }\n}\n"],"mappings":";;;AAAA,OAAO,cAAc;AACrB,SAAS,OAAO,cAAc;AAU9B,eAAsB,YAAY,UAAkB,aAAa,MAAwB;AACvF,MAAI,CAAC,OAAO,SAAS,CAAC,MAAM,OAAO;AACjC,WAAO;AAAA,EACT;AACA,QAAM,KAAK,SAAS,gBAAgB,EAAE,OAAO,OAAO,QAAQ,OAAO,CAAC;AACpE,MAAI;AACF,UAAM,SAAS,aAAa,YAAY;AACxC,UAAM,UAAU,MAAM,GAAG,SAAS,WAAW,MAAM,GAAG,KAAK,EAAE,YAAY;AACzE,QAAI,WAAW,GAAI,QAAO;AAC1B,WAAO,WAAW,OAAO,WAAW;AAAA,EACtC,UAAE;AACA,OAAG,MAAM;AAAA,EACX;AACF;","names":[]}

package/dist/templates/HOLDPOINT_PREREQUISITES.md

@@ -0,0 +1,10 @@
+# Holdpoint prerequisites
+
+Holdpoint installed repo-local adapters for one or more AI coding agents. Before relying on them locally, review these setup notes:
+
+- **GitHub Copilot CLI** — Holdpoint's `.github/extensions/holdpoint/extension.mjs` uses the Copilot CLI **EXTENSIONS** feature. Today that feature is gated behind experimental mode. In Copilot CLI, run `/experimental on` so **EXTENSIONS** appears in the enabled feature set before using Holdpoint locally.
+- **Cursor** — project-level hooks run in trusted workspaces. After opening the repo in Cursor, confirm the workspace is trusted and review Settings → Hooks if hooks do not fire.
+- **OpenAI Codex** — project-level hooks require trust approval. Run `codex trust` in the Codex TUI or review the hook with `/hooks`.
+- **General** — Holdpoint expects Node.js 18+ and a git repository so `holdpoint init`, `holdpoint update`, and `holdpoint check` can run normally.
+
+Docs: https://holdpoint.dev/docs

package/dist/templates/HOLDPOINT_REFERENCE.md

@@ -0,0 +1,372 @@
+# Holdpoint — Eval Checkpoints
+
+This project uses [Holdpoint](https://github.com/holdpoint-dev/holdpoint) to enforce
+eval checkpoints. Before marking any task done, all checks must pass.
+
+---
+
+## The Rule
+
+Before marking **any** task complete:
+
+1. Run `holdpoint check` — all tasks must exit 0.
+2. `holdpoint check` also prints every **prompt** check whose `when` matches the
+   files you changed. Read and act on each listed instruction before finishing.
+
+---
+
+## The Suggest Loop
+
+`checks.yaml` is not static — it grows alongside the project automatically.
+
+**`holdpoint-suggest` is a deterministic check** in `checks.yaml` that fires whenever you change a structural file (`package.json`, `pyproject.toml`, `go.mod`, `Dockerfile`, `tsconfig.json`, `vitest.config.*`, etc.). When it fires, `holdpoint suggest` runs and **exits 1 if `checks.yaml` is out of sync** — blocking task completion until you apply the proposals.
+
+When blocked by `holdpoint-suggest`, run:
+
+```
+holdpoint suggest --apply  # scan, apply proposals, regenerate engine files
+```
+
+Then commit:
+
+```
+git add checks.yaml .github/holdpoint/generated/
+git commit -m "chore: suggest holdpoint checks"
+```
+
+`holdpoint suggest --apply` is idempotent — safe to re-run at any time. It only adds checks for tools/patterns detected in the project and wraps stale checks (whose `when:` pattern no longer matches any file) with `conditionId: file_exists` so they auto-skip instead of failing.
+
+**What triggers evolution:**
+
+- New dependency in `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml`
+- New `Dockerfile`, `docker-compose.yml`, `*.tf`, `openapi.yaml`
+- New test runner config (`vitest.config.*`, `jest.config.*`, `playwright.config.*`)
+- New CI workflow in `.github/workflows/`
+- New TypeScript setup (`tsconfig.json`)
+
+**What does NOT trigger it:** `.ts` / `.py` / `.go` source files, docs, styles, tests — minor work proceeds without interruption.
+
+---
+
+## Git workflow best practices
+
+Prefer the least-disruptive git workflow that still satisfies the task:
+
+- Use a branch + PR when the user requests it, when work targets protected
+  `main`, or when remote CI/review is part of the task.
+- For small local fixes, commit directly on the current branch and do not open a
+  PR unless the user asks.
+- If already on a feature branch, keep committing there instead of creating
+  another branch.
+- After committing, decide whether to push: push when a PR, remote review, CI
+  run, or handoff needs it; otherwise leave the commit local and report the
+  branch/commit.
+
+---
+
+## checks.yaml — Full Reference
+
+`checks.yaml` at the project root is the single source of truth. Edit it to add,
+remove, or change checkpoints.
+
+After every edit, regenerate the engine files and commit everything together:
+
+```
+holdpoint update
+git add checks.yaml .github/holdpoint/generated/ .github/hooks/
+git commit -m "chore: update holdpoint checks"
+```
+
+### Top-level structure
+
+```yaml
+version: 1
+
+context:
+  guides: # project notes shown when `holdpoint check` runs
+    setup: >
+      Use pnpm, not npm. Node 20+ required.
+
+session_context_files:
+  - MASTER_PROMPT.md # injected into Copilot/Codex sessions when supported
+
+conditions: # gate checks on file/env state
+  - id: dist-built
+    operator: file_exists
+    path: dist/index.js
+
+checks: # list of all checks — each has on/when + cmd (task) or prompt
+  - ...
+```
+
+---
+
+### Deterministic check
+
+```yaml
+- id: lint # unique slug, kebab-case
+  label: "ESLint — all packages" # human-readable label shown in output
+  # on: before_done       # lifecycle hook (default; only value today)
+  # when: frontend        # file filter — omit to run on every task
+  cmd: "pnpm turbo lint" # shell command; must exit 0 to pass
+  conditionId: dist-built # optional: skip if condition is not met
+```
+
+### Prompt check
+
+```yaml
+- id: migration-review
+  label: "Review DB migration"
+  when: "^prisma/migrations/" # only fires when migration files change
+  prompt: >
+    Open the new migration file. Confirm it is backward-compatible
+    and does not drop or truncate data without a fallback.
+```
+
+---
+
+### `on` — lifecycle hooks
+
+`on` specifies _when in the agent lifecycle_ a check fires. Omit it to use the default.
+
+| Value         | Fires                              |
+| ------------- | ---------------------------------- |
+| `before_done` | Before the agent marks a task done |
+
+---
+
+### `when` — file filters
+
+`when` is an optional file filter. If omitted the check runs on every task.
+
+| Value       | Fires when changed files match                                                                     |
+| ----------- | -------------------------------------------------------------------------------------------------- |
+| _(absent)_  | Every task — no file filter applied                                                                |
+| `frontend`  | `**/*.tsx`, `**/*.jsx`, `**/*.css`, `**/*.scss`, `**/tailwind.config.*`, `apps/**`                 |
+| `backend`   | `**/api/**`, `**/server/**`, `**/routes/**`, `**/controllers/**`, `packages/*/src/**`              |
+| `socket`    | `**/socket/**`, `**/ws/**`, `**/websocket/**`                                                      |
+| `visual`    | `**/*.stories.{ts,tsx}`, `**/__screenshots__/**`, `**/*.snap`                                      |
+| `python`    | `**/*.py`, `**/*.pyi`, `**/requirements*.txt`, `**/pyproject.toml`, `**/setup.py`, `**/pytest.ini` |
+| `go`        | `**/*.go`, `**/go.mod`, `**/go.sum`                                                                |
+| `rust`      | `**/*.rs`, `**/Cargo.toml`, `**/Cargo.lock`                                                        |
+| `java`      | `**/*.java`, `**/*.kt`, `**/*.gradle`, `**/*.gradle.kts`, `**/pom.xml`                             |
+| `ruby`      | `**/*.rb`, `**/Gemfile`, `**/Gemfile.lock`, `**/Rakefile`                                          |
+| `database`  | `**/*.sql`, `**/migrations/**`, `**/db/**`, `**/database/**`, `**/prisma/**`, `**/*.prisma`        |
+| `prisma`    | `**/prisma/**`, `**/*.prisma` — focused subset of `database` for Prisma-specific checks            |
+| `testing`   | `**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`, `**/test/**`, `**/tests/**`, `**/spec/**`         |
+| `infra`     | `**/Dockerfile*`, `**/docker-compose.*`, `**/*.tf`, `**/*.tfvars`, `**/k8s/**`, `**/kubernetes/**` |
+| `ci`        | `**/.github/workflows/**`, `**/.circleci/**`, `**/Jenkinsfile`, `**/.gitlab-ci.yml`                |
+| `docs`      | `**/*.mdx`, `**/*.rst`, `**/docs/**`, `**/documentation/**`                                        |
+| `"^src/.*"` | Any JavaScript regex tested against each changed file path                                         |
+
+Regex example — fires only when files under `src/api/` change:
+
+```yaml
+when: "^src/api/" # new RegExp(when).test(filePath)
+```
+
+> **Note:** Named scopes use glob matching; plain strings are treated as JavaScript regexes.
+
+---
+
+### Conditions
+
+Conditions let you skip a check when a prerequisite is not yet met (e.g. a build
+artefact doesn't exist yet).
+
+| Operator          | What it checks                                    |
+| ----------------- | ------------------------------------------------- |
+| `file_exists`     | A file or directory exists at `path`              |
+| `file_contains`   | The file at `path` contains the substring `value` |
+| `env_var_set`     | The environment variable named `value` is set     |
+| `shell_returns_0` | The shell command in `cmd` exits with code 0      |
+
+```yaml
+conditions:
+  - id: packages-built
+    operator: file_exists
+    path: packages/yaml-core/dist/index.js
+
+checks:
+  - id: validate-templates
+    label: "Templates parse against schema"
+    conditionId: packages-built # skipped (◌) when dist is absent
+    cmd: "node dist/validate.js templates/"
+```
+
+---
+
+### Context guides
+
+`context.guides` is a freeform key → multiline-string map. Guides are printed
+at the start of `holdpoint check` output as project-level reminders to whoever
+(or whatever) is running the checks.
+
+```yaml
+context:
+  guides:
+    setup: >
+      This project requires Node 20 and pnpm 9+.
+      Run `pnpm install` from the repo root before any other command.
+    architecture: >
+      API routes live in src/api/. Models live in src/models/.
+      Client code must never import from server modules.
+```
+
+---
+
+## Adding a New Check
+
+1. Open `checks.yaml`.
+2. Add your entry under `checks:`.
+3. Run `holdpoint update`.
+4. Commit `checks.yaml` and the generated files.
+
+**Add a task check (runs a shell command automatically):**
+
+```yaml
+checks:
+  - id: vitest
+    label: "Vitest — unit tests"
+    cmd: "pnpm vitest run"
+```
+
+**Add a scoped task (fires only on matching file changes):**
+
+```yaml
+checks:
+  - id: openapi-sync
+    label: "OpenAPI types are up to date"
+    when: "^src/api/"
+    cmd: "pnpm generate:types && git diff --exit-code src/generated/"
+```
+
+**Add an agent prompt checkpoint:**
+
+```yaml
+checks:
+  - id: jsdoc
+    label: "JSDoc on changed public functions"
+    prompt: >
+      For every public function or export you modified, ensure there is an
+      accurate JSDoc comment: description, @param, and @returns.
+```
+
+**Enforce changelog and git commit on every task (recommended):**
+
+```yaml
+checks:
+  - id: changelog-update
+    label: "Add a CHANGELOG.md entry for this session"
+    prompt: >
+      Before committing, add an entry to CHANGELOG.md describing what was done.
+      Use Keep a Changelog format — add under ## [Unreleased] (create the file
+      and that section if absent). Group entries as Added, Changed, Fixed, or Removed.
+      Be concise but specific. The entry text will serve as the commit message.
+
+  - id: readme-sync
+    label: "Update README.md if user-facing changes were made"
+    prompt: >
+      If you added, changed, or removed user-facing functionality — CLI commands,
+      configuration options, public APIs, or significant new features — update
+      README.md to reflect those changes.
+
+  - id: git-workflow
+    label: "Use the right git workflow"
+    prompt: >
+      Choose the least-disruptive git workflow: use branch + PR for requested
+      feature branches or protected-main work; for small local fixes, commit on
+      the current branch without opening a PR unless asked; if already on a
+      feature branch, keep committing there instead of creating another branch.
+      Push only when a PR, remote review, CI run, or handoff needs it; otherwise
+      leave the commit local and report the branch/commit.
+
+  - id: git-commit
+    label: "Commit all changes before finishing"
+    cmd: 'git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0; [ -z "$(git status --porcelain)" ] && exit 0; git status --short; exit 1'
+```
+
+When the `git-commit` check fails (uncommitted changes remain), the agent will also see
+the `changelog-update` and `readme-sync` prompt reminders inline — ensuring it updates
+the changelog, syncs docs, _then_ commits before it can mark the task done.
+
+---
+
+## `session_context_files`
+
+`session_context_files` is an optional list of project files that Holdpoint injects
+as context at the start of every Copilot session. Use it for files the agent should
+always read before starting work.
+
+```yaml
+session_context_files:
+  - MASTER_PROMPT.md
+  - AGENT_CONTEXT.md
+```
+
+Files are resolved relative to the repo root and must stay inside it (traversal
+paths like `../../etc/passwd` are rejected). If a file doesn't exist it is silently
+skipped.
+
+---
+
+## `inject_datetime`
+
+Holdpoint can inject the current date and time into every prompt the agent receives.
+This fixes a common failure mode where models anchor their sense of "now" to their
+training cutoff and make stale assumptions (e.g. treating months-old information as
+current, or not knowing what year it is).
+
+The feature is **on by default** — no configuration needed. To opt out:
+
+```yaml
+inject_datetime: false
+```
+
+When enabled, each prompt submission includes:
+
+```
+Current date and time: 2026-05-29T14:23:45.123Z (UTC)
+Provided by Holdpoint — use this to avoid knowledge-cutoff confusion.
+```
+
+**Agent support:**
+
+| Agent   | Hook                    | Notes                                                            |
+| ------- | ----------------------- | ---------------------------------------------------------------- |
+| Claude  | `UserPromptSubmit`      | Fires on every prompt via `additionalContext`                    |
+| Cursor  | `beforeSubmitPrompt`    | Fires on every prompt via `additional_context`                   |
+| Codex   | `UserPromptSubmit`      | Fires on every prompt via `hookSpecificOutput.additionalContext` |
+| Copilot | `onUserPromptSubmitted` | Fires on every prompt via `additionalContext`                    |
+
+---
+
+## Commands
+
+| Command                       | What it does                                            |
+| ----------------------------- | ------------------------------------------------------- |
+| `holdpoint check`             | Run checks against all files changed vs HEAD            |
+| `holdpoint check --staged`    | Run checks against staged files only                    |
+| `holdpoint suggest`           | Scan project and show proposed additions to checks.yaml |
+| `holdpoint suggest --apply`   | Apply proposals and regenerate engine files             |
+| `holdpoint require-changeset` | Require `.changeset/*.md` for package changes           |
+| `holdpoint update`            | Regenerate engine files from the current `checks.yaml`  |
+| `holdpoint validate`          | Validate `checks.yaml` schema (no commands run)         |
+| `holdpoint builder`           | Open the daemon-served visual builder UI                |
+
+---
+
+## Generated files (do not edit directly)
+
+| File                                                | Agent   |
+| --------------------------------------------------- | ------- |
+| `.github/holdpoint/generated/checks.immutable.json` | all     |
+| `.github/hooks/holdpoint.json`                      | Copilot |
+| `.github/hooks/holdpoint-check.mjs`                 | Copilot |
+| `.claude/settings.json`                             | Claude  |
+| `.cursor/hooks.json`                                | Cursor  |
+| `.cursor/holdpoint-hook.mjs`                        | Cursor  |
+| `.cursorrules` (Holdpoint section)                  | Cursor  |
+
+All generated files are overwritten by `holdpoint update`. Edit `checks.yaml`,
+then run `update` — never edit the generated files directly.