From fe755751758276f3e58ca7a58cadfa32282e15a2 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 20 May 2026 14:05:47 +0000 Subject: [PATCH 1/2] docs: fix CLI.md, ARCHITECTURE.md, HOOKS.md, and GETTING_STARTED.md accuracy Key corrections: - CLI.md: add missing 'hook' command (disable/enable/status) renamed from 'hooks' in #334 - CLI.md: fix 'config set' keys (remove stale 'apiKey'; add 'orgID' and 'validation.sidecarImage') - CLI.md: add missing 'task config' subcommand - CLI.md: add 'init --skip-skills' and '--skip-test-suites' flags - CLI.md: remove non-existent 'sidecar setup --snapshot-name' and '--skip-snapshot' flags - CLI.md: add 'sidecar list --all' and '--json' flags - CLI.md: add 'validate --org-id', '--json', and 'config show --json' flags - CLI.md: fix 'sidecar create' docs (--org-id and --name are not required) - ARCHITECTURE.md: add hook.go entry; fix task.go note (now includes 'task config') - ARCHITECTURE.md: remove non-existent 'usererr/' package; add 'secrets/', 'session/', 'settings/' - ARCHITECTURE.md: add CHUNK_HOOKS_DISABLED and CLAUDE_WORKING_DIR to env var table - HOOKS.md: document 'chunk hook disable/enable/status' commands - GETTING_STARTED.md: add 'chunk validate --remote' to env-forwarding section - README.md: add 'chunk hook' to commands table Co-authored-by: schurchleycci --- README.md | 1 + docs/ARCHITECTURE.md | 19 ++++++++++------ docs/CLI.md | 50 ++++++++++++++++++++++++++++------------- docs/GETTING_STARTED.md | 5 ++++- docs/HOOKS.md | 14 ++++++++++++ 5 files changed, 66 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index e9a00597..f2ef1d56 100644 --- a/README.md +++ b/README.md @@ -123,6 +123,7 @@ chunk sidecar setup Detect env, install deps, snapshot chunk sidecar snapshot create|get Manage sidecar snapshots chunk init Initialize project configuration chunk validate [name] Run quality checks +chunk hook disable|enable|status Manage hook execution chunk skill install|list Manage AI agent skills chunk task config|run Configure and trigger CI tasks chunk build-prompt Generate review context from PR comments diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 3655f00e..e71fb374 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -17,11 +17,12 @@ chunk-cli/ │ ├── completion.go # completion install/uninstall/zsh │ ├── config.go # config show/set │ ├── init.go # init (project setup, settings.json generation) - │ ├── sidecar.go # sidecar list/create/exec/add-ssh-key/ssh/sync/env/build - │ ├── skills.go # skill install/list - │ ├── task.go # task run - │ ├── upgrade.go # upgrade - │ └── validate.go # validate +│ ├── hook.go # hook disable/enable/status +│ ├── sidecar.go # sidecar list/create/exec/add-ssh-key/ssh/sync/env/build/setup +│ ├── skills.go # skill install/list +│ ├── task.go # task run/config +│ ├── upgrade.go # upgrade +│ └── validate.go # validate ├── anthropic/ # Anthropic Messages API client ├── buildprompt/ # Three-step pipeline: discover → analyze → generate ├── circleci/ # CircleCI REST API client @@ -34,11 +35,13 @@ chunk-cli/ ├── sidecar/ # CircleCI sidecar operations ├── skills/ # Skill definitions (go:embed) and installation ├── task/ # Task run config and CircleCI trigger + ├── secrets/ # Secret resolution (env var value expansion) + ├── session/ # Session ID tracking for Stop hook context + ├── settings/ # .claude/settings.json build and merge ├── testing/recorder/ # HTTP recorder for tests ├── tui/ # Terminal UI components (confirm, input, select) ├── ui/ # Colors, formatting, spinner ├── upgrade/ # CLI self-upgrade - ├── usererr/ # User-facing error wrapper └── validate/ # Validation command logic ``` @@ -179,7 +182,9 @@ in `config.Resolve` and makes clients testable. | `GITHUB_API_URL` | github | GitHub API endpoint override | | `CIRCLE_TOKEN` / `CIRCLECI_TOKEN` | circleci | CircleCI authentication | | `CIRCLECI_BASE_URL` | circleci | CircleCI endpoint override | -| `CLAUDE_PROJECT_DIR` | init | IDE-provided project directory | +| `CLAUDE_PROJECT_DIR` | validate, init | IDE-provided project directory | +| `CLAUDE_WORKING_DIR` | validate | Active worktree directory (Stop hook context) | +| `CHUNK_HOOKS_DISABLED` | validate, hook | Disable pre-commit hooks when set (any non-empty value) | | `XDG_CONFIG_HOME` | config | User config directory (default: `~/.config`) | | `XDG_DATA_HOME` | sidecar | Per-project state directory (default: `~/.local/share`) | diff --git a/docs/CLI.md b/docs/CLI.md index d8f97626..5cb3003a 100644 --- a/docs/CLI.md +++ b/docs/CLI.md @@ -24,22 +24,30 @@ chunk │ ├── config │ ├── show # Display resolved configuration -│ └── set # Set a config value (keys: model, apiKey) +│ │ --json # Output as JSON +│ └── set # Set a config value +│ # User keys: model +│ # Project keys: orgID, validation.sidecarImage │ ├── init # Initialize project configuration │ --force # Overwrite existing config │ --skip-hooks # Skip hook file generation │ --skip-validate # Skip validate command detection -│ --skip-completions # Skip shell completion installation +│ --skip-completions # Skip shell completion installation +│ --skip-skills # Skip agent skill installation +│ --skip-test-suites # Skip .circleci/test-suites.yml generation (default: true) │ --project-dir # Project directory (defaults to cwd) │ ├── task -│ └── run # Trigger a task run -│ --definition # Definition name or UUID (required) -│ --prompt # Prompt text (required) -│ --branch # Branch override -│ --new-branch # Create a new branch -│ --no-pipeline-as-tool # Disable pipeline-as-tool mode +│ ├── run # Trigger a task run +│ │ --definition # Definition name or UUID (required) +│ │ --prompt # Prompt text (required) +│ │ --branch # Branch override +│ │ --new-branch # Create a new branch +│ │ --no-pipeline-as-tool # Disable pipeline-as-tool mode +│ │ --json # Output as JSON +│ └── config # Set up .chunk/run.json for this repository +│ --force # Overwrite existing configuration without confirmation │ ├── skill │ ├── install # Install all skills @@ -49,10 +57,12 @@ chunk │ [name] # Optional: run a specific named command │ --dry-run # Print commands without executing │ --list # List all configured commands +│ --json # Output as JSON (only applies with --list) │ --cmd # Run an inline command │ --save # Save --cmd to config │ --remote # Run on the active sidecar │ --sidecar-id # Remote execution in specific sidecar +│ --org-id # Organization ID (used when creating a new sidecar) │ --identity-file # SSH identity file for sidecar │ --workdir # Working directory on sidecar │ --project # Override project directory @@ -60,13 +70,17 @@ chunk │ --env-file # Env file to load (default: .env.local; pass a path to override) │ ├── sidecar -│ ├── list --org-id # List sidecars +│ ├── list # List sidecars +│ │ --org-id # Organization ID +│ │ --all # List all sidecars in the org (requires org admin) +│ │ --json # Output as JSON │ ├── create # Create a sidecar -│ │ --org-id # Organization ID (required) -│ │ --name # Sidecar name (required) +│ │ --org-id # Organization ID (interactive picker when omitted) +│ │ --name # Sidecar name (auto-generated when omitted) │ │ --image # E2B template ID or container image │ ├── use # Set the active sidecar for this project │ ├── current # Show the active sidecar +│ │ --json # Output as JSON │ ├── forget # Clear the active sidecar │ ├── exec # Execute command in sidecar │ │ --sidecar-id # Sidecar ID (defaults to active sidecar) @@ -91,15 +105,13 @@ chunk │ ├── build # Generate Dockerfile and build test image from env spec │ │ --dir # Directory to write Dockerfile.test and build from │ │ --tag # Image tag (e.g. myapp:latest) -│ ├── setup # Detect env, sync files, run install steps, snapshot +│ ├── setup # Detect env, sync files, and run install steps │ │ --dir # Directory to detect environment in (default: .) │ │ --sidecar-id # Sidecar ID (defaults to active sidecar) │ │ --org-id # Organization ID (used when creating a new sidecar) │ │ --name # Sidecar name (used when creating a new sidecar) │ │ --identity-file # SSH identity file -│ │ --snapshot-name # Snapshot name (defaults to -setup) │ │ --skip-sync # Skip syncing files to the sidecar -│ │ --skip-snapshot # Skip creating a snapshot after install │ │ --force # Re-detect environment even if cached │ │ -e / --env KEY=VALUE # Set env var in remote sidecar session (repeatable) │ │ --env-file # Env file to load (default: .env.local; pass a path to override) @@ -108,6 +120,13 @@ chunk │ │ --sidecar-id # Sidecar ID (defaults to active sidecar) │ │ --name # Snapshot name (required) │ └── get # Get a snapshot by ID +│ --json # Output as JSON +│ +├── hook # Manage chunk hook execution +│ --project # Override project directory +│ ├── disable # Disable chunk validate hooks +│ ├── enable # Re-enable chunk validate hooks +│ └── status # Show whether hooks are enabled or disabled │ ├── completion │ ├── install # Install zsh completion @@ -124,7 +143,7 @@ chunk - `build-prompt --since` defaults to 3 months before the current date. - `task run` defaults to pipeline-as-tool mode; use `--no-pipeline-as-tool` to disable. -- `config set` accepts only `model` and `apiKey` as keys. +- `config set` accepts `model` as a user config key and `orgID` / `validation.sidecarImage` as project config keys. Use `chunk auth set` to store credentials. - `chunk init` uses Claude to auto-detect the test command for the project. It generates `.claude/settings.json` with pre-commit hooks. It never touches CircleCI — tokens are prompted inline only when a command actually needs them. @@ -133,6 +152,7 @@ chunk failing with an error. - `chunk auth set github` stores a GitHub token in the config file; previously only the `GITHUB_TOKEN` environment variable was supported. +- `chunk hook disable` creates a `.chunk/hooks-disabled` sentinel file; `hook enable` removes it. Hooks are also disabled when `CHUNK_HOOKS_DISABLED` is set in the environment. ## Flag Conventions diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index 513359ba..699c2e92 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -207,17 +207,20 @@ chunk sidecar create --image myimg # name auto-generated ### Environment variables -`chunk sidecar ssh` and `chunk sidecar setup` automatically load `.env.local` from your working directory and forward its variables to the remote sidecar session. This lets you pass secrets and configuration without embedding them in your shell or committing them to the repo. +`chunk sidecar ssh`, `chunk sidecar setup`, and `chunk validate` (when running remotely) automatically load `.env.local` from your working directory and forward its variables to the remote sidecar session. This lets you pass secrets and configuration without embedding them in your shell or committing them to the repo. ```bash # .env.local is loaded automatically — no flag needed chunk sidecar ssh +chunk validate --remote # Override with a different file chunk sidecar ssh --env-file /path/to/other.env +chunk validate --remote --env-file /path/to/other.env # Add individual variables (merged on top of the file) chunk sidecar ssh --env MY_VAR=value +chunk validate --remote --env MY_VAR=value ``` Variables from `--env` flags take precedence over those in `--env-file`. `.env.local` is gitignored by convention, so it's a safe place to store project-specific secrets. diff --git a/docs/HOOKS.md b/docs/HOOKS.md index 7d4777dc..f91ba609 100644 --- a/docs/HOOKS.md +++ b/docs/HOOKS.md @@ -92,6 +92,20 @@ without prompting. | **Claude Code** (CLI / terminal) | Fully supported | Canonical provider | | **Cursor** | Supported | Reads `.claude/settings.json` directly | +## Disabling Hooks + +Temporarily disable hooks without modifying `.claude/settings.json`: + +```bash +chunk hook disable # Creates .chunk/hooks-disabled sentinel file +chunk hook enable # Removes the sentinel file +chunk hook status # Shows "enabled" or "disabled" +``` + +Hooks are also skipped when the `CHUNK_HOOKS_DISABLED` environment variable is set to any non-empty value — useful for CI environments where the hooks should not run. + +The `--project` flag overrides the project root used to locate the sentinel file. + ## Manual Validation Use `chunk validate` to run checks manually (outside of hooks): From debd0865d5751b698dd0ad326c081a26d0b0771c Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 20 May 2026 14:55:55 +0000 Subject: [PATCH 2/2] docs: address review accuracy fixes Co-authored-by: schurchleycci --- README.md | 2 +- docs/ARCHITECTURE.md | 17 ++++++++--------- docs/CLI.md | 2 +- docs/HOOKS.md | 6 +++--- 4 files changed, 13 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index f2ef1d56..0d27bffb 100644 --- a/README.md +++ b/README.md @@ -119,7 +119,7 @@ chunk auth set|status|remove Authentication chunk sidecar list|create|exec|ssh Manage cloud sidecar environments chunk sidecar sync|env|build Sync files, detect env, build images chunk sidecar use|current|forget Manage active sidecar -chunk sidecar setup Detect env, install deps, snapshot +chunk sidecar setup Detect env and install deps chunk sidecar snapshot create|get Manage sidecar snapshots chunk init Initialize project configuration chunk validate [name] Run quality checks diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index e71fb374..13dbf6d1 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -17,12 +17,12 @@ chunk-cli/ │ ├── completion.go # completion install/uninstall/zsh │ ├── config.go # config show/set │ ├── init.go # init (project setup, settings.json generation) -│ ├── hook.go # hook disable/enable/status -│ ├── sidecar.go # sidecar list/create/exec/add-ssh-key/ssh/sync/env/build/setup -│ ├── skills.go # skill install/list -│ ├── task.go # task run/config -│ ├── upgrade.go # upgrade -│ └── validate.go # validate + │ ├── hook.go # hook disable/enable/status + │ ├── sidecar.go # sidecar list/create/exec/add-ssh-key/ssh/sync/env/build/setup + │ ├── skills.go # skill install/list + │ ├── task.go # task run/config + │ ├── upgrade.go # upgrade + │ └── validate.go # validate ├── anthropic/ # Anthropic Messages API client ├── buildprompt/ # Three-step pipeline: discover → analyze → generate ├── circleci/ # CircleCI REST API client @@ -182,9 +182,8 @@ in `config.Resolve` and makes clients testable. | `GITHUB_API_URL` | github | GitHub API endpoint override | | `CIRCLE_TOKEN` / `CIRCLECI_TOKEN` | circleci | CircleCI authentication | | `CIRCLECI_BASE_URL` | circleci | CircleCI endpoint override | -| `CLAUDE_PROJECT_DIR` | validate, init | IDE-provided project directory | -| `CLAUDE_WORKING_DIR` | validate | Active worktree directory (Stop hook context) | -| `CHUNK_HOOKS_DISABLED` | validate, hook | Disable pre-commit hooks when set (any non-empty value) | +| `CLAUDE_PROJECT_DIR` | settings | IDE-provided project directory used by generated `PreToolUse` hooks | +| `CHUNK_HOOKS_DISABLED` | validate, hook | Disable Stop-hook validation when set (any non-empty value) | | `XDG_CONFIG_HOME` | config | User config directory (default: `~/.config`) | | `XDG_DATA_HOME` | sidecar | Per-project state directory (default: `~/.local/share`) | diff --git a/docs/CLI.md b/docs/CLI.md index 5cb3003a..6292c43e 100644 --- a/docs/CLI.md +++ b/docs/CLI.md @@ -152,7 +152,7 @@ chunk failing with an error. - `chunk auth set github` stores a GitHub token in the config file; previously only the `GITHUB_TOKEN` environment variable was supported. -- `chunk hook disable` creates a `.chunk/hooks-disabled` sentinel file; `hook enable` removes it. Hooks are also disabled when `CHUNK_HOOKS_DISABLED` is set in the environment. +- `chunk hook disable` creates a `.chunk/hooks-disabled` sentinel file inspected by the `chunk validate` Stop hook; `hook enable` removes it. Stop-hook validation is also disabled when `CHUNK_HOOKS_DISABLED` is set in the environment. ## Flag Conventions diff --git a/docs/HOOKS.md b/docs/HOOKS.md index f91ba609..7db54682 100644 --- a/docs/HOOKS.md +++ b/docs/HOOKS.md @@ -92,9 +92,9 @@ without prompting. | **Claude Code** (CLI / terminal) | Fully supported | Canonical provider | | **Cursor** | Supported | Reads `.claude/settings.json` directly | -## Disabling Hooks +## Disabling Stop-Hook Validation -Temporarily disable hooks without modifying `.claude/settings.json`: +Temporarily disable the `chunk validate` Stop hook without modifying `.claude/settings.json`: ```bash chunk hook disable # Creates .chunk/hooks-disabled sentinel file @@ -102,7 +102,7 @@ chunk hook enable # Removes the sentinel file chunk hook status # Shows "enabled" or "disabled" ``` -Hooks are also skipped when the `CHUNK_HOOKS_DISABLED` environment variable is set to any non-empty value — useful for CI environments where the hooks should not run. +Stop-hook validation is also skipped when the `CHUNK_HOOKS_DISABLED` environment variable is set to any non-empty value. This does not suppress `PreToolUse` commit hooks generated by `chunk init`, because those commands run directly from `.claude/settings.json`. The `--project` flag overrides the project root used to locate the sentinel file.