@codewizard-dt/bootstrap 3.2.0 → 5.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +18 -60
- package/bin/cli.js +0 -5
- package/lib/hooks/README.md +14 -5
- package/lib/hooks/lib/command-parse.js +28 -0
- package/lib/hooks/package-install-consent.js +60 -2
- package/lib/prompts/README.md +0 -1
- package/lib/scripts/README.md +20 -13
- package/lib/scripts/bootstrap-prefs.js +20 -1
- package/lib/scripts/migrate-project.sh +1 -1
- package/lib/scripts/setup-project.sh +0 -1
- package/lib/scripts/sync-wiki-scaffold.sh +3 -15
- package/lib/scripts/templates/CLAUDE-wiki.md +4 -4
- package/lib/scripts/templates/bootstrap-prefs-schema.json +10 -1
- package/lib/scripts/templates/wiki/conventions.md +1 -1
- package/lib/scripts/templates/wiki/dashboard.html +2 -2
- package/lib/scripts/templates/wiki/index.md +4 -4
- package/lib/scripts/templates/wiki/work/requirements/index.md +1 -1
- package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +2 -2
- package/lib/scripts/templates/wiki/work/roadmaps/index.md +1 -1
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +4 -4
- package/lib/scripts/templates/wiki/work/tasks/index.md +1 -1
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +6 -6
- package/lib/scripts/templates/wiki/work/uat/index.md +1 -1
- package/lib/scripts/templates/wiki/work/uat/lifecycle.md +4 -4
- package/lib/scripts/wiki-dashboard-server.js +1 -1
- package/lib/skills/README.md +3 -1
- package/lib/skills/architecture-audit/SKILL.md +207 -0
- package/lib/skills/bootstrap-config/SKILL.md +1 -1
- package/lib/skills/bug-assess/SKILL.md +137 -0
- package/lib/skills/bug-close/SKILL.md +2 -2
- package/lib/skills/bug-file/SKILL.md +9 -5
- package/lib/skills/decision-create/SKILL.md +5 -1
- package/lib/skills/power-mode/SKILL.md +10 -10
- package/lib/skills/primer/SKILL.md +1 -1
- package/lib/skills/req-compile/SKILL.md +2 -2
- package/lib/skills/req-create/SKILL.md +13 -9
- package/lib/skills/req-extract-decisions/SKILL.md +10 -10
- package/lib/skills/req-finalize/SKILL.md +3 -3
- package/lib/skills/req-retire/SKILL.md +10 -10
- package/lib/skills/req-update/SKILL.md +4 -4
- package/lib/skills/roadmap-assess/SKILL.md +58 -20
- package/lib/skills/roadmap-create/SKILL.md +22 -22
- package/lib/skills/roadmap-next/SKILL.md +10 -10
- package/lib/skills/security-audit/SKILL.md +3 -0
- package/lib/skills/tackle/SKILL.md +3 -3
- package/lib/skills/task-add/SKILL.md +22 -22
- package/lib/skills/task-audit/SKILL.md +2 -2
- package/lib/skills/task-trash/SKILL.md +4 -4
- package/lib/skills/uat-generate/SKILL.md +22 -22
- package/lib/skills/uat-skip/SKILL.md +21 -21
- package/lib/skills/uat-walk/UAT-CORE.md +6 -6
- package/lib/skills/wiki-lint/SKILL.md +1 -1
- package/package.json +2 -4
- package/.github/workflows/docker-harness.yml +0 -26
- package/.github/workflows/security.yml +0 -24
- package/.gitleaks.toml +0 -15
- package/lib/prompts/setup-deployment.md +0 -322
- package/lib/scripts/setup-deployment.sh +0 -113
- package/raw/guides/deployment-strategy.md +0 -448
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@ Bootstrap Claude Code projects with an LLM Wiki, reusable skills, enforcement ho
|
|
|
6
6
|
|
|
7
7
|
## Description
|
|
8
8
|
|
|
9
|
-
`@codewizard-dt/bootstrap` is an npm-distributed setup toolkit for Claude Code users who repeatedly configure the same agent workflow in new repositories. It installs Model Context Protocol servers, syncs a global skill library, copies hook scripts, scaffolds an LLM Wiki, assembles a project-specific MCP tools guide, and provides explicit
|
|
9
|
+
`@codewizard-dt/bootstrap` is an npm-distributed setup toolkit for Claude Code users who repeatedly configure the same agent workflow in new repositories. It installs Model Context Protocol servers, syncs a global skill library, copies hook scripts, scaffolds an LLM Wiki, assembles a project-specific MCP tools guide, and provides an explicit command for strict type-checking setup.
|
|
10
10
|
|
|
11
11
|
The project exists to move AI-agent state out of chat history and into structured, versioned markdown. Requirements, decisions, tasks, UAT specs, bug reports, roadmaps, source summaries, and operating logs all live in a predictable wiki layout, so future Claude Code sessions and subagents can resume work from file-system state instead of relying on prior conversation context.
|
|
12
12
|
|
|
@@ -26,16 +26,16 @@ At a glance, the package entry point selects a script, scripts copy or generate
|
|
|
26
26
|
|
|
27
27
|
- **Responsibility:** Routes `bootstrap <command>` and `npx @codewizard-dt/bootstrap <command>` invocations to the appropriate setup script.
|
|
28
28
|
- **Tech:** Node.js CommonJS, `child_process.execFileSync`
|
|
29
|
-
- **Inputs:** Commands such as `setup`, `update`, `install`, `
|
|
29
|
+
- **Inputs:** Commands such as `setup`, `update`, `install`, `migrate`, `typechecks`, and `dashboard`, plus optional extra arguments for migration and dashboard (port override) flows.
|
|
30
30
|
- **Outputs:** Executes the selected script with inherited stdio and propagates the script exit status.
|
|
31
31
|
- **Depends on:** Setup Scripts
|
|
32
32
|
|
|
33
33
|
#### Setup Scripts
|
|
34
34
|
|
|
35
|
-
- **Responsibility:** Coordinate project setup, updates, global installs,
|
|
35
|
+
- **Responsibility:** Coordinate project setup, updates, global installs, Serena bootstrapping, wiki migration, and strict type-checking setup.
|
|
36
36
|
- **Tech:** Bash, `rsync`, `find`, `grep`, `claude` CLI, npm-executed shell scripts
|
|
37
|
-
- **Inputs:** Target project path, interactive prompts, CLI flags such as `--dry-run`, API keys supplied by environment variables or stdin, and optional user context for
|
|
38
|
-
- **Outputs:** Global hooks and skills, MCP registrations, project-local `wiki/`, `raw/`, `wiki/guides/`, `.mcp.json`, `.serena/project.yml`, and optional
|
|
37
|
+
- **Inputs:** Target project path, interactive prompts, CLI flags such as `--dry-run`, API keys supplied by environment variables or stdin, and optional user context for typecheck setup.
|
|
38
|
+
- **Outputs:** Global hooks and skills, MCP registrations, project-local `wiki/`, `raw/`, `wiki/guides/`, `.mcp.json`, `.serena/project.yml`, and optional type-check configuration when that explicit command is run.
|
|
39
39
|
- **Depends on:** CLI Entry Point, Skills Library, Hooks Library, Wiki Scaffold Templates, Prompt Templates, Guide Stubs, Claude Code CLI, MCP servers
|
|
40
40
|
|
|
41
41
|
#### MCP Installer
|
|
@@ -80,20 +80,12 @@ At a glance, the package entry point selects a script, scripts copy or generate
|
|
|
80
80
|
|
|
81
81
|
#### Prompt Templates
|
|
82
82
|
|
|
83
|
-
- **Responsibility:** Provide Claude Code with structured instructions for
|
|
83
|
+
- **Responsibility:** Provide Claude Code with structured instructions for wiki migration, Serena configuration, and strict type-checking setup when static templates are too brittle.
|
|
84
84
|
- **Tech:** Markdown prompt files in `lib/prompts/`
|
|
85
|
-
- **Inputs:** Target project context, raw guide content, script interpolation, and optional user-provided
|
|
86
|
-
- **Outputs:** Claude-generated project configuration,
|
|
85
|
+
- **Inputs:** Target project context, raw guide content, script interpolation, and optional user-provided typecheck details.
|
|
86
|
+
- **Outputs:** Claude-generated project configuration, migrated wiki artifacts, and type-check tooling.
|
|
87
87
|
- **Depends on:** Claude Code CLI, raw guides, Setup Scripts
|
|
88
88
|
|
|
89
|
-
#### GitHub Actions Templates
|
|
90
|
-
|
|
91
|
-
- **Responsibility:** Supplies repository automation for secret scanning and a Docker/GHCR build-push template.
|
|
92
|
-
- **Tech:** GitHub Actions YAML, Gitleaks action, Docker Buildx actions
|
|
93
|
-
- **Inputs:** Pushes and pull requests to `main` for `security.yml`; manual `workflow_dispatch` for `build.yml`; root-level `Dockerfile` for container build execution.
|
|
94
|
-
- **Outputs:** Gitleaks scan results, optional GHCR container images, and a placeholder deploy job that must be customized before production use.
|
|
95
|
-
- **Depends on:** GitHub Actions, `.gitleaks.toml`, GitHub package permissions
|
|
96
|
-
|
|
97
89
|
### Component Interaction
|
|
98
90
|
|
|
99
91
|
```mermaid
|
|
@@ -113,7 +105,6 @@ flowchart LR
|
|
|
113
105
|
MCPS["install-mcps.sh"]
|
|
114
106
|
WIKI["sync-wiki-scaffold.sh"]
|
|
115
107
|
GUIDE["build-mcp-guide.sh"]
|
|
116
|
-
DEPLOY["setup-deployment.sh"]
|
|
117
108
|
SERENA["bootstrap-serena.sh"]
|
|
118
109
|
end
|
|
119
110
|
|
|
@@ -138,7 +129,6 @@ flowchart LR
|
|
|
138
129
|
DOCS["wiki/guides/mcp-tools.md"]
|
|
139
130
|
MCP_JSON["Serena (local scope)<br/>~/.claude.json project entry"]
|
|
140
131
|
SERENA_CFG[".serena/project.yml"]
|
|
141
|
-
WORKFLOWS[".github/workflows/"]
|
|
142
132
|
end
|
|
143
133
|
|
|
144
134
|
subgraph External ["External Tools"]
|
|
@@ -147,7 +137,6 @@ flowchart LR
|
|
|
147
137
|
DOCKER["Docker<br/>brave-search-mcp container<br/>http :8941"]
|
|
148
138
|
LAUNCHD["launchd<br/>playwright-mcp LaunchAgent<br/>http :8931 (macOS)"]
|
|
149
139
|
NPX["npx<br/>Playwright MCP (non-macOS stdio)"]
|
|
150
|
-
GHA["GitHub Actions"]
|
|
151
140
|
NPM["npm Registry"]
|
|
152
141
|
end
|
|
153
142
|
|
|
@@ -155,7 +144,6 @@ flowchart LR
|
|
|
155
144
|
BIN -->|execFileSync| SETUP
|
|
156
145
|
BIN -->|execFileSync| UPDATE
|
|
157
146
|
BIN -->|execFileSync| INSTALL
|
|
158
|
-
BIN -->|execFileSync| DEPLOY
|
|
159
147
|
SETUP -->|runs| MCPS
|
|
160
148
|
SETUP -->|runs| INSTALL
|
|
161
149
|
SETUP -->|runs| WIKI
|
|
@@ -176,12 +164,8 @@ flowchart LR
|
|
|
176
164
|
WIKI -->|writes| WIKI_DIR
|
|
177
165
|
GUIDE -->|assemble selected sections| STUBS
|
|
178
166
|
GUIDE -->|writes| DOCS
|
|
179
|
-
DEPLOY -->|claude -p| PROMPTS
|
|
180
|
-
DEPLOY -->|reads| RAW
|
|
181
|
-
DEPLOY -->|writes| WORKFLOWS
|
|
182
167
|
SERENA -->|claude -p| CLAUDE
|
|
183
168
|
SERENA -->|writes| SERENA_CFG
|
|
184
|
-
WORKFLOWS -->|runs| GHA
|
|
185
169
|
DEV -->|npm publish| NPM
|
|
186
170
|
```
|
|
187
171
|
|
|
@@ -247,7 +231,7 @@ sequenceDiagram
|
|
|
247
231
|
- **Project-scoped Serena:** Serena is registered against an absolute project path in `.mcp.json`, avoiding cross-project language-server bleed while keeping other MCPs available globally when appropriate.
|
|
248
232
|
- **Copy-once vs. always-refresh templates:** Project-owned files such as indexes and logs are not overwritten, while lifecycle specs, conventions, and guide content can be refreshed from the package.
|
|
249
233
|
- **Hooks enforce behavior where permissions cannot:** PreToolUse and PostToolUse hooks enforce `.env` safety, protected git operations, and Serena-first navigation even when normal allow/deny permissions are bypassed.
|
|
250
|
-
- **Claude-driven scaffolding handles project variance:**
|
|
234
|
+
- **Claude-driven scaffolding handles project variance:** Type-checking, Serena configuration, and wiki migration use prompt templates plus `claude -p` because the right output depends on the consumer project's stack.
|
|
251
235
|
|
|
252
236
|
## Technologies
|
|
253
237
|
|
|
@@ -255,7 +239,7 @@ sequenceDiagram
|
|
|
255
239
|
- Node.js CommonJS for the CLI and hook scripts
|
|
256
240
|
- Bash for installation, synchronization, migration, and setup orchestration
|
|
257
241
|
- Markdown for skills, prompts, wiki templates, raw guides, and project documentation
|
|
258
|
-
- YAML for
|
|
242
|
+
- YAML for generated Serena/project configuration
|
|
259
243
|
- JSON for `package.json`, `.mcp.json`, hook payloads, and Claude Code settings snippets
|
|
260
244
|
|
|
261
245
|
- **CLI and package distribution**
|
|
@@ -283,15 +267,9 @@ sequenceDiagram
|
|
|
283
267
|
- LLM Wiki structure with `raw/`, `wiki/knowledge/`, and `wiki/work/`
|
|
284
268
|
- Mermaid diagrams embedded in documentation
|
|
285
269
|
|
|
286
|
-
- **CI/CD and security**
|
|
287
|
-
- GitHub Actions
|
|
288
|
-
- Gitleaks and `.gitleaks.toml`
|
|
289
|
-
- Docker Buildx GitHub Actions template
|
|
290
|
-
- GitHub Container Registry template workflow
|
|
291
|
-
|
|
292
270
|
## Use Cases
|
|
293
271
|
|
|
294
|
-
- **New Claude Code project bootstrap:** Developers can run one command in a repository to install MCP tooling, global skills, global hooks, wiki scaffolding, MCP guides, and Serena configuration
|
|
272
|
+
- **New Claude Code project bootstrap:** Developers can run one command in a repository to install MCP tooling, global skills, global hooks, wiki scaffolding, MCP guides, and Serena configuration.
|
|
295
273
|
- **Global agent workflow installation:** Users can sync the latest skill and hook library into `~/.claude/` without modifying any project by running the install command.
|
|
296
274
|
- **Legacy documentation migration:** Existing `.docs/`-style projects can be migrated into the current LLM Wiki structure with branch isolation, path mapping, frontmatter synthesis, and link rewrites.
|
|
297
275
|
- **AI-native engineering operations:** Teams can manage requirements, decisions, tasks, UAT, roadmaps, bugs, evals, research, demos, and security audits as durable markdown artifacts that agents can read and update.
|
|
@@ -305,8 +283,7 @@ sequenceDiagram
|
|
|
305
283
|
- **Knowledge Management Architecture (LLM Wiki):** Modeled project memory as immutable raw sources, timeless knowledge synthesis, and lifecycle-managed work artifacts with conventions, indexes, logs, stable IDs, and typed links.
|
|
306
284
|
- **Model Context Protocol Integration:** Integrated Serena, Brave Search, Context7, and Playwright MCP servers with appropriate scope decisions, API-key handling, and generated MCP usage guidance.
|
|
307
285
|
- **Claude Code Hook Engineering (Node.js):** Built hook scripts that enforce file-safety and LSP-first navigation policies using Claude Code hook payloads, shared helper modules, and persistent navigation state.
|
|
308
|
-
- **Prompt Engineering for Developer Tooling:** Created prompt templates that let Claude Code generate context-sensitive
|
|
309
|
-
- **CI/CD Pipeline Configuration (GitHub Actions):** Provided security scanning and container build/push workflow templates using Gitleaks, Docker Buildx, GHCR, manual dispatch, and skip guards for repositories without Dockerfiles.
|
|
286
|
+
- **Prompt Engineering for Developer Tooling:** Created prompt templates that let Claude Code generate context-sensitive migration, type-checking, and Serena configuration changes in consumer projects.
|
|
310
287
|
- **Developer Experience Design:** Organized commands, skills, templates, guides, and troubleshooting paths so repeated Claude Code setup work can be performed from a small set of predictable commands.
|
|
311
288
|
- **Documentation Systems Engineering:** Generated machine-parseable project documentation, skill instructions, lifecycle specs, MCP guides, and runbooks that serve both humans and downstream AI tools.
|
|
312
289
|
|
|
@@ -314,7 +291,7 @@ sequenceDiagram
|
|
|
314
291
|
|
|
315
292
|
### Overview
|
|
316
293
|
|
|
317
|
-
This project deploys as a public npm CLI package. There is no hosted runtime, database, or production server; publishing a new npm version
|
|
294
|
+
This project deploys as a public npm CLI package. There is no hosted runtime, database, or production server, and no CI/CD automation; publishing a new npm version to the registry is the entire release process.
|
|
318
295
|
|
|
319
296
|
### Prerequisites
|
|
320
297
|
|
|
@@ -322,13 +299,12 @@ This project deploys as a public npm CLI package. There is no hosted runtime, da
|
|
|
322
299
|
- `npm` with publish access to the `@codewizard-dt` scope.
|
|
323
300
|
- An authenticated npm session via `npm login` or an npm automation token.
|
|
324
301
|
- Git access to the repository at `git@github.com:codewizard-dt/bootstrap-claude.git`.
|
|
325
|
-
- GitHub Actions enabled for repository CI checks.
|
|
326
302
|
- For local smoke tests of setup commands, install Claude Code with `npm install -g @anthropic-ai/claude-code`.
|
|
327
303
|
- For Serena setup smoke tests, install `uv` so `uvx` is available.
|
|
328
304
|
|
|
329
305
|
### Environment Variables
|
|
330
306
|
|
|
331
|
-
No environment variables are required to build or publish this package from a logged-in npm session. The setup scripts
|
|
307
|
+
No environment variables are required to build or publish this package from a logged-in npm session. The setup scripts reference the following variables and secrets:
|
|
332
308
|
|
|
333
309
|
| Variable | Required | Example | Description |
|
|
334
310
|
|---|---|---|---|
|
|
@@ -336,11 +312,6 @@ No environment variables are required to build or publish this package from a lo
|
|
|
336
312
|
| `BRAVE_MCP_PORT` | no — defaults to `8941` | `8941` | Host port for the shared Brave Search MCP Docker container (mapped to the container's fixed port `8941`); the registered endpoint is `http://127.0.0.1:<port>/mcp`. |
|
|
337
313
|
| `PLAYWRIGHT_MCP_PORT` | no — defaults to `8931` | `8931` | Port the shared Playwright MCP launchd agent listens on (macOS); the registered endpoint is `http://127.0.0.1:<port>/mcp`. |
|
|
338
314
|
| `CONTEXT7_API_KEY` | optional for Context7 MCP install | `ctx_...` | Optional secret sent as a Context7 MCP HTTP header; Context7 can be installed without it. |
|
|
339
|
-
| `GITHUB_TOKEN` | yes in GitHub Actions | `${{ secrets.GITHUB_TOKEN }}` | GitHub-provided token used by Gitleaks and GHCR login in workflows. |
|
|
340
|
-
| `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` | yes in workflows | `true` | Plain workflow config forcing JavaScript actions to run on Node 24. |
|
|
341
|
-
| `REGISTRY` | yes in `build.yml` | `ghcr.io` | Plain workflow config for the container registry in the template workflow. |
|
|
342
|
-
| `OWNER` | yes in `build.yml` | `${{ github.repository_owner }}` | Plain workflow config used to build GHCR image tags. |
|
|
343
|
-
| `IMAGE` | yes in `build.yml` | `${{ github.event.repository.name }}` | Plain workflow config used to build GHCR image tags. |
|
|
344
315
|
| `CLAUDE_MIGRATION` | optional | `1` | Plain flag recognized by some Serena enforcement hooks to bypass during migration flows. |
|
|
345
316
|
|
|
346
317
|
### Build
|
|
@@ -352,7 +323,7 @@ There is no transpilation or bundling step. The package ships source files direc
|
|
|
352
323
|
npm pack --dry-run
|
|
353
324
|
```
|
|
354
325
|
|
|
355
|
-
The publishable surface is `bin/`, `lib/`, `raw/`,
|
|
326
|
+
The publishable surface is `bin/`, `lib/`, and `raw/` (excluding `raw/research/`, `raw/companies/`, and `raw/*.pdf`, per `package.json` `files`).
|
|
356
327
|
|
|
357
328
|
### Run Locally
|
|
358
329
|
|
|
@@ -370,9 +341,6 @@ node bin/cli.js setup
|
|
|
370
341
|
# Serves on http://localhost:4317 by default; pass a port to override
|
|
371
342
|
node bin/cli.js dashboard
|
|
372
343
|
node bin/cli.js dashboard 4400
|
|
373
|
-
|
|
374
|
-
# Preview deployment-scaffold detection for the current repository
|
|
375
|
-
node lib/scripts/setup-deployment.sh --dry-run .
|
|
376
344
|
```
|
|
377
345
|
|
|
378
346
|
The setup command writes to the current project and to `~/.claude/`, so run it from a disposable test repository when validating a release candidate.
|
|
@@ -412,11 +380,7 @@ npm view @codewizard-dt/bootstrap version
|
|
|
412
380
|
npx @codewizard-dt/bootstrap@latest
|
|
413
381
|
```
|
|
414
382
|
|
|
415
|
-
CI/CD
|
|
416
|
-
|
|
417
|
-
- `.github/workflows/security.yml` runs Gitleaks on pushes and pull requests targeting `main`.
|
|
418
|
-
- `.github/workflows/build.yml` is manual-only via `workflow_dispatch`; its build job skips unless a root-level `Dockerfile` exists, and its deploy job is a placeholder.
|
|
419
|
-
- No workflow currently publishes the npm package automatically; npm release is manual.
|
|
383
|
+
This project does not offer GitHub Actions scaffolding or any other CI/CD automation as a feature — publishing to npm by hand is the only release process.
|
|
420
384
|
|
|
421
385
|
### Data & Migrations
|
|
422
386
|
|
|
@@ -435,9 +399,6 @@ npm view @codewizard-dt/bootstrap version
|
|
|
435
399
|
|
|
436
400
|
# The latest package should execute and print usage without a command
|
|
437
401
|
npx @codewizard-dt/bootstrap@latest
|
|
438
|
-
|
|
439
|
-
# Security workflow should pass in GitHub Actions
|
|
440
|
-
gh run list --workflow security.yml --limit 5
|
|
441
402
|
```
|
|
442
403
|
|
|
443
404
|
For end-to-end validation, run `npx @codewizard-dt/bootstrap@latest setup` inside a disposable repository and confirm `wiki/`, `raw/`, `wiki/guides/`, and the selected MCP configuration files are created.
|
|
@@ -462,24 +423,21 @@ For source rollback, revert the release commit and publish a new patch version r
|
|
|
462
423
|
|
|
463
424
|
### Observability
|
|
464
425
|
|
|
465
|
-
There is no runtime telemetry, metrics backend, dashboard, or alerting because the project is a CLI package. Operational signals come from
|
|
426
|
+
There is no runtime telemetry, metrics backend, dashboard, or alerting because the project is a CLI package. Operational signals come from npm package metadata, npm install/publish output, and user-reported command failures.
|
|
466
427
|
|
|
467
428
|
Useful first places to inspect:
|
|
468
429
|
|
|
469
|
-
- GitHub Actions security workflow runs in `.github/workflows/security.yml`.
|
|
470
|
-
- Manual build template runs in `.github/workflows/build.yml`.
|
|
471
430
|
- npm package metadata from `npm view @codewizard-dt/bootstrap`.
|
|
472
431
|
- Local command traces from the setup scripts' stdout/stderr.
|
|
473
432
|
|
|
474
433
|
### Troubleshooting
|
|
475
434
|
|
|
476
435
|
- **`command not found: bootstrap`:** The package binary is not on PATH; run through `npx @codewizard-dt/bootstrap <command>` or use `node bin/cli.js <command>` locally.
|
|
477
|
-
- **`claude: command not found`:** Claude Code is missing; install it with `npm install -g @anthropic-ai/claude-code` before running setup,
|
|
436
|
+
- **`claude: command not found`:** Claude Code is missing; install it with `npm install -g @anthropic-ai/claude-code` before running setup, migration, or typecheck setup.
|
|
478
437
|
- **`uv: command not found`:** Serena setup cannot launch; install uv so `uvx` is available, then rerun setup.
|
|
479
438
|
- **Brave MCP install prompts for an API key:** Set `BRAVE_API_KEY` before non-interactive installs or enter it when prompted by `install-mcps.sh`. The key is baked into the `brave-search-mcp` container at creation, so a re-run never re-prompts while the container exists; to change the key, `docker rm -f brave-search-mcp` and re-run `bootstrap update`. Brave install also requires Docker to be running — if it is not, the script skips brave-search until the next `bootstrap update`.
|
|
480
439
|
- **`brave-search endpoint not answering`:** The shared container should be serving `http://127.0.0.1:8941/mcp` (host port overridable via `BRAVE_MCP_PORT`). Check `docker logs brave-search-mcp` and confirm Docker Desktop is running; enable Docker Desktop's "Start when you sign in" so the container comes back after reboots.
|
|
481
440
|
- **`playwright endpoint not answering` (macOS):** The launchd agent `com.bootstrap-claude.playwright-mcp` should be serving `http://127.0.0.1:8931/mcp` (overridable via `PLAYWRIGHT_MCP_PORT`). Inspect it with `launchctl print gui/$(id -u)/com.bootstrap-claude.playwright-mcp` and check `~/Library/Logs/playwright-mcp.log`. Over SSH there is no GUI session for the agent to bootstrap into — log into the Mac GUI once, then re-run `bootstrap update`.
|
|
482
441
|
- **Context7 installs without authenticated access:** Set `CONTEXT7_API_KEY` if authenticated Context7 access is required; otherwise the script can register Context7 without the header.
|
|
483
442
|
- **Hooks copy but do not run:** `install-global.sh` copies scripts to `~/.claude/hooks/`, but hook registration in `~/.claude/settings.json` is a separate manual step documented in `lib/hooks/README.md`. The `permissions.deny` list is the exception: `install-global.sh` merges the canonical deny list from `lib/scripts/templates/settings-deny.json` into `~/.claude/settings.json` automatically (additive-only — your own entries are never removed or reordered). Deleting a canonical entry locally means it gets re-added on the next `install`/`setup`/`update` run; that re-convergence is the point of a canonical list.
|
|
484
|
-
- **Manual build workflow skips:** `.github/workflows/build.yml` intentionally skips the build job unless a root-level `Dockerfile` exists.
|
|
485
443
|
- **npm package points at unexpected repository metadata:** Check `package.json` `repository`, `homepage`, and `bugs` fields before publishing; they are independent of the local git remote.
|
package/bin/cli.js
CHANGED
|
@@ -10,8 +10,6 @@ const SCRIPTS = {
|
|
|
10
10
|
setup: { script: 'setup-project.sh', args: ['.'] },
|
|
11
11
|
update: { script: 'update-project.sh', args: ['.'] },
|
|
12
12
|
install: { script: 'install-global.sh', args: [] },
|
|
13
|
-
deploy: { script: 'setup-deployment.sh', args: ['.', ...extraArgs] },
|
|
14
|
-
deployment: { script: 'setup-deployment.sh', args: ['.', ...extraArgs] },
|
|
15
13
|
migrate: { script: 'migrate-project.sh', args: ['.', ...extraArgs] },
|
|
16
14
|
typechecks: { script: 'setup-strict-typechecks.sh', args: extraArgs },
|
|
17
15
|
dashboard: { script: 'wiki-dashboard-server.js', args: ['.', ...extraArgs] },
|
|
@@ -24,9 +22,6 @@ if (!command || !SCRIPTS[command]) {
|
|
|
24
22
|
console.error(' setup Set up a new project with Claude Code configurations');
|
|
25
23
|
console.error(' update Sync wiki scaffold and install skills globally');
|
|
26
24
|
console.error(' install Install skills globally into ~/.claude/skills/');
|
|
27
|
-
console.error(' deploy Scaffold CI/CD (.github/ workflows + .gitleaks.toml) into the project');
|
|
28
|
-
console.error(' Optional: pass extra context for the Claude agent as a quoted string');
|
|
29
|
-
console.error(' e.g. bootstrap deploy "backend is on port 8080, use s-2vcpu-4gb droplet"');
|
|
30
25
|
console.error(' migrate Migrate a legacy .docs/ project to the wiki structure (Claude-driven)');
|
|
31
26
|
console.error(' Pass --dry-run to preview; runs on a fresh wiki-migration branch');
|
|
32
27
|
console.error(' typechecks Run strict typecheck setup via Claude (optional: language list)');
|
package/lib/hooks/README.md
CHANGED
|
@@ -341,11 +341,20 @@ unaffected, while the same `npm install -g @playwright/mcp@latest` typed at the
|
|
|
341
341
|
prompt IS gated. Both are correct: consent was given once for the setup script as
|
|
342
342
|
a whole; an ad-hoc install carries no such consent.
|
|
343
343
|
|
|
344
|
-
**Known friction, real and expected
|
|
345
|
-
`lib/skills/frontend-taste/SKILL.md:29` instructs Claude to
|
|
346
|
-
`cd ~/code/house-style/preview && npm i && npm run dev`. That command *is*
|
|
347
|
-
hook-visible and
|
|
348
|
-
|
|
344
|
+
**Known friction, real and expected — no longer resolvable only by running the
|
|
345
|
+
command yourself.** `lib/skills/frontend-taste/SKILL.md:29` instructs Claude to
|
|
346
|
+
run `cd ~/code/house-style/preview && npm i && npm run dev`. That command *is*
|
|
347
|
+
hook-visible and gates by default, which remains the correct behaviour for a
|
|
348
|
+
project that has not opted in to anything — it is the one genuine friction
|
|
349
|
+
point this gate introduces in-repo, not a bug, and the deny message's escape
|
|
350
|
+
hatch is still to approve it by running it yourself. A project can now change
|
|
351
|
+
that default going forward: `packageInstall.consent` (TASK-075) is a
|
|
352
|
+
bootstrap-prefs key, scope `project`, read fresh on every match. `ask` hands the
|
|
353
|
+
call to Claude Code's native permission prompt instead of denying it (`node
|
|
354
|
+
~/.claude/bootstrap-prefs.js --set packageInstall.consent --value ask --project
|
|
355
|
+
.`); `true` allows the match outright (`--value true`). `false`/unset/any read
|
|
356
|
+
failure denies exactly as before — the gate still fails closed, it just now has
|
|
357
|
+
a documented, standing opt-out alongside the per-call rephrasing escape hatch.
|
|
349
358
|
|
|
350
359
|
**Not covered, deliberately:** bare `uvx <pkg>` with no `--from`; `npx`; and a
|
|
351
360
|
manager that is not the segment's first token, so `claude mcp add … -- uvx --from
|
|
@@ -63,9 +63,37 @@ function deny(reason) {
|
|
|
63
63
|
process.exit(0);
|
|
64
64
|
}
|
|
65
65
|
|
|
66
|
+
function allow(reason) {
|
|
67
|
+
console.log(JSON.stringify({
|
|
68
|
+
hookSpecificOutput: {
|
|
69
|
+
hookEventName: 'PreToolUse',
|
|
70
|
+
permissionDecision: 'allow',
|
|
71
|
+
permissionDecisionReason: String(reason),
|
|
72
|
+
},
|
|
73
|
+
}));
|
|
74
|
+
process.exit(0);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
// `defer` hands the decision back to Claude Code's own native permission
|
|
78
|
+
// handling; the contract does not document permissionDecisionReason as
|
|
79
|
+
// meaningless there, so — same as `allow`/`deny` — we keep passing it
|
|
80
|
+
// through rather than risk silently dropping useful context.
|
|
81
|
+
function defer(reason) {
|
|
82
|
+
console.log(JSON.stringify({
|
|
83
|
+
hookSpecificOutput: {
|
|
84
|
+
hookEventName: 'PreToolUse',
|
|
85
|
+
permissionDecision: 'defer',
|
|
86
|
+
permissionDecisionReason: String(reason),
|
|
87
|
+
},
|
|
88
|
+
}));
|
|
89
|
+
process.exit(0);
|
|
90
|
+
}
|
|
91
|
+
|
|
66
92
|
module.exports = {
|
|
67
93
|
readHookInput,
|
|
68
94
|
splitSegments,
|
|
69
95
|
tokenize,
|
|
70
96
|
deny,
|
|
97
|
+
allow,
|
|
98
|
+
defer,
|
|
71
99
|
};
|
|
@@ -42,7 +42,10 @@
|
|
|
42
42
|
// coverage rather than failure: a manager or invocation form absent from the
|
|
43
43
|
// tables below is allowed, which is also why the scope note above holds.
|
|
44
44
|
|
|
45
|
-
const {
|
|
45
|
+
const { execFileSync } = require('child_process');
|
|
46
|
+
const os = require('os');
|
|
47
|
+
const path = require('path');
|
|
48
|
+
const { readHookInput, splitSegments, tokenize, deny, allow, defer } = require('./lib/command-parse');
|
|
46
49
|
|
|
47
50
|
// Manager basename → install subcommand phrases (space-separated so multi-token
|
|
48
51
|
// forms like `uv pip install` are expressible). `uvx` is absent here: its
|
|
@@ -133,12 +136,51 @@ function matchedInstall(tokens) {
|
|
|
133
136
|
return null;
|
|
134
137
|
}
|
|
135
138
|
|
|
139
|
+
// The installed location of bootstrap-prefs.js — this file runs from
|
|
140
|
+
// ~/.claude/hooks/ after install, not from a checkout of this repo, so it must
|
|
141
|
+
// resolve the helper the same way every other cross-reference to it does: a
|
|
142
|
+
// fixed, project-independent home under the user's HOME, not a path relative
|
|
143
|
+
// to __dirname. os.homedir() (not process.env.HOME) is what makes this follow
|
|
144
|
+
// a redirected HOME in tests, matching bootstrap-prefs.js's own convention.
|
|
145
|
+
const PREFS_SCRIPT = path.join(os.homedir(), '.claude', 'bootstrap-prefs.js');
|
|
146
|
+
|
|
147
|
+
// A plain fs read (bootstrap-prefs.js --get) is normally sub-millisecond.
|
|
148
|
+
// 2000ms mirrors interpreter-indirection-guard.js's SIBLING_TIMEOUT_MS for the
|
|
149
|
+
// same reason: generous enough that normal load never false-triggers it, short
|
|
150
|
+
// enough that a genuine hang does not stall the user's Bash call noticeably.
|
|
151
|
+
const PREFS_TIMEOUT_MS = 2000;
|
|
152
|
+
|
|
153
|
+
// Consults the packageInstall.consent preference for `cwd`. Returns the
|
|
154
|
+
// trimmed stdout ("true" | "ask" | "false" | "unset") on a clean run, or null
|
|
155
|
+
// on ANY trouble — missing helper, corrupt JSON, non-zero exit, a thrown
|
|
156
|
+
// error, or a timeout. null is handled identically to "false"/"unset" by the
|
|
157
|
+
// caller: this function never distinguishes "no" from "couldn't ask", because
|
|
158
|
+
// only an exact "true" or "ask" may loosen the default deny.
|
|
159
|
+
function packageInstallConsent(cwd) {
|
|
160
|
+
try {
|
|
161
|
+
const stdout = execFileSync(
|
|
162
|
+
process.execPath,
|
|
163
|
+
[PREFS_SCRIPT, '--get', 'packageInstall.consent', '--project', cwd],
|
|
164
|
+
{ encoding: 'utf8', timeout: PREFS_TIMEOUT_MS }
|
|
165
|
+
);
|
|
166
|
+
return stdout.trim();
|
|
167
|
+
} catch (err) {
|
|
168
|
+
return null;
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
|
|
136
172
|
readHookInput(data => {
|
|
137
173
|
if (data.tool_name !== 'Bash') return;
|
|
138
174
|
|
|
139
175
|
const fullCmd = String(data.tool_input?.command ?? '').trim();
|
|
140
176
|
if (!fullCmd) return;
|
|
141
177
|
|
|
178
|
+
// Mirrors protected-write-guard.js:189 / claude-settings-guard.js:192: `cwd`
|
|
179
|
+
// is a top-level field on the hook payload (the session's directory), not
|
|
180
|
+
// `data.tool_input.cwd` — Bash tool calls carry no such field — and it can
|
|
181
|
+
// differ from this process's own process.cwd().
|
|
182
|
+
const cwd = typeof data.cwd === 'string' && data.cwd ? data.cwd : process.cwd();
|
|
183
|
+
|
|
142
184
|
for (const segment of splitSegments(fullCmd)) {
|
|
143
185
|
const tokens = stripInvocationPrefix(tokenize(segment));
|
|
144
186
|
if (!tokens.length) continue;
|
|
@@ -148,6 +190,20 @@ readHookInput(data => {
|
|
|
148
190
|
const install = matchedInstall(tokens);
|
|
149
191
|
if (!install) continue;
|
|
150
192
|
|
|
193
|
+
const consent = packageInstallConsent(cwd);
|
|
194
|
+
if (consent === 'true') {
|
|
195
|
+
allow(
|
|
196
|
+
`Package install allowed (\`${install}\`) — this project's stored preference is ` +
|
|
197
|
+
`\`packageInstall.consent = true\`.`
|
|
198
|
+
);
|
|
199
|
+
}
|
|
200
|
+
if (consent === 'ask') {
|
|
201
|
+
defer(
|
|
202
|
+
`Package install (\`${install}\`) needs consent — this project's stored preference is ` +
|
|
203
|
+
`\`packageInstall.consent = ask\`, deferring to Claude Code's native permission prompt.`
|
|
204
|
+
);
|
|
205
|
+
}
|
|
206
|
+
|
|
151
207
|
// The segment is echoed verbatim, not rebuilt from tokens: the entire value
|
|
152
208
|
// of this gate over a deny rule is that the user can copy the exact string
|
|
153
209
|
// back out and run it. Re-joining tokens would silently drop quoting.
|
|
@@ -156,7 +212,9 @@ readHookInput(data => {
|
|
|
156
212
|
`without an explicit human decision. To approve, run it yourself:\n\n` +
|
|
157
213
|
` ${segment}\n\n` +
|
|
158
214
|
`If the dependency is not actually needed, say so and it will be dropped rather ` +
|
|
159
|
-
`than worked around
|
|
215
|
+
`than worked around. Or stop this gate from asking for this project's future installs: ` +
|
|
216
|
+
`\`node ~/.claude/bootstrap-prefs.js --set packageInstall.consent --value ask --project .\` ` +
|
|
217
|
+
`(or \`--value true\` to skip the prompt entirely).`
|
|
160
218
|
);
|
|
161
219
|
}
|
|
162
220
|
});
|
package/lib/prompts/README.md
CHANGED
|
@@ -4,7 +4,6 @@ Markdown prompt templates for setup steps that are too context-sensitive for a s
|
|
|
4
4
|
|
|
5
5
|
| Prompt | Driven by | Purpose |
|
|
6
6
|
|--------|-----------|---------|
|
|
7
|
-
| `setup-deployment.md` | `lib/scripts/setup-deployment.sh` | Detects deployable services (Node/Python/Go/Rust) from manifest files, then creates or updates `.github/workflows/security.yml` (always overwritten — generic CodeQL + Gitleaks), `.github/workflows/build.yml` and `.gitleaks.toml` (create-once, confirm before overwrite), and `Makefile` Docker targets (merged with existing targets, never removed/reformatted). Refuses to guess service names/entrypoints it can't confidently identify — stops and asks instead. |
|
|
8
7
|
| `migrate-wiki.md` | `lib/scripts/migrate-project.sh` | Drives the semantic conversion from a legacy `.docs/`-layout project to the LLM Wiki structure, after `sync-wiki-scaffold.sh` has already created the empty scaffold. Runs headlessly with only Bash/Read/Edit/Write (explicitly told not to look for Serena MCP tools). Hard rules: `git mv` every file before editing it (preserves history), never touch `raw/` or template-owned files (`wiki/conventions.md`, `lifecycle.md`), never move a file once it lands at its new path, and never commit — leaves everything staged for the user to review. Contains the full old-path → new-path mapping table (`.docs/tasks/` → `wiki/work/tasks/TASK-NNN`, `.docs/adr/` → `wiki/work/decisions/DEC-NNNN`, etc.) and the per-family status-inference rules. |
|
|
9
8
|
| `setup-strict-typechecks.md` | `lib/scripts/setup-strict-typechecks.sh` | Scans the repo for every language with a type-checking/linting story, researches current strict-mode conventions per language (TypeScript `strict` + `typescript-eslint` strictTypeChecked, Python `mypy --strict`, Go `staticcheck`/`vet`, Rust `deny(warnings)`/Clippy, …) via Context7/Brave Search, installs the required toolchain packages, and wires the config files plus a `make typecheck` target. Accepts an optional language list from the script's CLI args to scope the run. |
|
|
10
9
|
| `setup-design-system.md` | *(none — not currently invoked by any script)* | A generic prompt for wiring an arbitrary design system into a frontend app: migrate tokens/assets into `<APP_SRC_PATH>/design-system/`, wire the CSS import into the app entry point, then convert each prototype reference component into a typed production component driven entirely by CSS custom properties. Takes `<DESIGN_SYSTEM_PATH>`, `<APP_SRC_PATH>`, `<APP_ROUTES_PATH>`, and `<SKILL_NAME>` placeholders. Kept for manual reuse (`claude < setup-design-system.md` with placeholders filled in) when onboarding a design system other than the one `lib/skills/frontend-taste` already automates (house-style, from `~/code/house-style`). |
|
package/lib/scripts/README.md
CHANGED
|
@@ -8,10 +8,9 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
|
|
|
8
8
|
|
|
9
9
|
| Script | `bootstrap` command | What it does |
|
|
10
10
|
|--------|---------------------|---------------|
|
|
11
|
-
| `setup-project.sh` | `setup` | Preflight-checks `claude` and `uv` are installed, then runs the full new-project sequence: global hooks/skills/settings install first (offline-safe, via `install-global.sh --skip-mcps` — includes the deny-list and hooks-wiring merges), then the interactive MCP install (guarded — a failure warns and continues), wiki scaffold + tiered guides sync (optional guides prompted), `.gitignore` merge, and Serena `project.yml` bootstrap.
|
|
11
|
+
| `setup-project.sh` | `setup` | Preflight-checks `claude` and `uv` are installed, then runs the full new-project sequence: global hooks/skills/settings install first (offline-safe, via `install-global.sh --skip-mcps` — includes the deny-list and hooks-wiring merges), then the interactive MCP install (guarded — a failure warns and continues), wiki scaffold + tiered guides sync (optional guides prompted), `.gitignore` merge, and Serena `project.yml` bootstrap. |
|
|
12
12
|
| `update-project.sh` | `update` | Re-runs the same shared sequence as `setup` (global hooks/skills/settings via `install-global.sh --skip-mcps`, then the guarded interactive MCP install) and re-syncs the wiki scaffold + tiered `wiki/guides/` into an existing project. Detects legacy `.docs/`-layout families (`tasks`, `uat`, `adr`, `prd`, `bugs`, `roadmaps`) and warns without touching them — migration is a separate, explicit step (`migrate`). Never touches `.github/`. |
|
|
13
13
|
| `install-global.sh` | `install` | Installs/updates hooks, skills, settings, and MCPs globally with **no project path** — the shared step both `setup` and `update` delegate to. Local/offline-safe steps run first: hooks rsync to `~/.claude/hooks/` (stderr warning if `lib/hooks` is missing), skills install (pruning stale skill folders from the wiki rename — `adr-*` → `decision-*`, `prd-*` → `req-*`), the canonical permission deny-list merge into `~/.claude/settings.json` via `merge-settings-deny.js`, then the hooks-wiring merge via `merge-settings-hooks.js` — registering the copied hook scripts in the settings `hooks` key, with a restart-your-session reminder when the wiring was created or changed. Then copies `templates/file-suggestion.sh` → `~/.claude/file-suggestion.sh` and registers it as the `fileSuggestion` `@`-autocomplete picker (`merge-settings-deny.js --set-key` mode) — printing a restart note on fresh registration, or leaving a pre-existing different `fileSuggestion` untouched. Then step 6 installs the preference helper — `bootstrap-prefs.js` → `~/.claude/bootstrap-prefs.js` and `templates/bootstrap-prefs-schema.json` → `~/.claude/templates/bootstrap-prefs-schema.json`, the layout that lets a skill read a preference with no `--schema` flag (see [Preference helper notes](#preference-helper-notes)); a missing helper or schema warns and continues. Step 7 then settles the seven `consumer: skill` preferences that have never been answered — asked once, in a batch, at global scope, gated on a tty as a whole, so a non-interactive run prints one note and writes no answers and no preferences file. MCPs install **last** (step 8) — the only network-dependent step, guarded so a failure warns instead of aborting the local installs — and `--skip-mcps` skips them when the caller already handled MCP install interactively. |
|
|
14
|
-
| `setup-deployment.sh` | `deploy` / `deployment` | Reads `raw/guides/deployment-strategy.md` as a prompt template, copies it into the target's `wiki/guides/` (deploy-only guide tier — the wiki sync never ships it), and runs `claude` to scaffold `.github/workflows/`, `Makefile` Docker targets, and `.gitleaks.toml` into the target project. Deliberately **not** called by `setup`/`update` — CI files get hand-customized per project (Dockerfile paths, runner labels, deploy steps) and must never be created or clobbered implicitly. `security.yml` is always overwritten (generic); `build.yml`/`.gitleaks.toml` are copy-once; `Makefile` targets are merged. |
|
|
15
14
|
| `migrate-project.sh` | `migrate` | Claude-driven migration of a legacy `.docs/`-layout project to the LLM Wiki structure (`wiki/knowledge/` + `wiki/work/`). Preflight requires a clean git tree; runs on a fresh `wiki-migration` branch so the whole migration is one reviewable diff. Scaffolds first via `sync-wiki-scaffold.sh --interactive`, assembles `wiki/guides/mcp-tools.md` via `build-mcp-guide.sh`, then drives the semantic conversion (frontmatter synthesis, ID renames, link rewrites, family indexes) with the prompt at `lib/prompts/migrate-wiki.md`. `git mv` before edit, so history is preserved. `--dry-run` prints the file inventory only and does not touch anything. |
|
|
16
15
|
| `setup-strict-typechecks.sh` | `typechecks` | Loads `lib/prompts/setup-strict-typechecks.md`, appends an optional language list (space- or comma-separated), and runs `claude` to detect languages, research current strict-mode conventions, install toolchains, and wire `make typecheck`. |
|
|
17
16
|
| `wiki-dashboard-server.js` | `dashboard` | Zero-dependency Node static file server (Node builtins only) that serves the live wiki dashboard client (`templates/wiki/dashboard.html`) at `/` and the project's `wiki/` tree read-only under `/wiki/*`, all with `no-store` cache headers so the polling client always sees current content. Runs in the foreground until Ctrl-C. Binds `http://localhost:4317` by default; pass a port to override (`bootstrap dashboard 4400`), and falls back to the next port (up to 10 tries) if the chosen one is in use. Unlike the other CLI scripts, this is Node, not Bash, and is long-running rather than one-shot. |
|
|
@@ -39,7 +38,6 @@ These are **not** referenced by `bin/cli.js` or by any other script — they're
|
|
|
39
38
|
|--------|---------|
|
|
40
39
|
| `setup-runner.sh` | Generalized GitHub Actions self-hosted runner installer. Run as root on a target droplet: `RUNNER_TOKEN=<token> REPO_URL=<url> bash setup-runner.sh`. Registers the runner, installs it as a service, and configures GHCR login. |
|
|
41
40
|
| `startup.sh` | One-shot droplet bootstrap: updates apt, installs zsh/curl/make, and installs Docker + the Compose plugin from Docker's official apt repo. Typically run once before `setup-runner.sh` on a fresh VM. |
|
|
42
|
-
| [`test/docker/fresh-machine/`](../../test/docker/fresh-machine/README.md) | Docker-based harness that emulates running `setup`/`update` on a completely fresh machine with no prior Claude Code infrastructure. `./run.sh [shell\|setup\|update]`. |
|
|
43
41
|
|
|
44
42
|
## `templates/`
|
|
45
43
|
|
|
@@ -345,13 +343,19 @@ after an older version touches it, and the user can see what was kept.
|
|
|
345
343
|
|
|
346
344
|
### Why every `consumer: skill` key says `install-global.sh`
|
|
347
345
|
|
|
348
|
-
|
|
349
|
-
including `gitCommit.versionBump` and `gitCommit.autoPush` — which
|
|
350
|
-
`/git-commit` until this was settled. The field records the **settling**
|
|
351
|
-
the one site that writes the answer. For
|
|
346
|
+
Seven of the eight `consumer: skill` keys name `install-global.sh` as their
|
|
347
|
+
`askedBy`, including `gitCommit.versionBump` and `gitCommit.autoPush` — which
|
|
348
|
+
named `/git-commit` until this was settled. The field records the **settling**
|
|
349
|
+
prompt: the one site that writes the answer. For those seven keys that site is
|
|
352
350
|
`install-global.sh`'s step 7 sync pass, which asks each unanswered key once, in a
|
|
353
351
|
batch, at global scope.
|
|
354
352
|
|
|
353
|
+
`packageInstall.consent` is the one exception, naming `/bootstrap-config`
|
|
354
|
+
instead. There is no scripted installer moment that could settle it the same
|
|
355
|
+
way: a brand-new project has no `.claude/bootstrap-prefs.json` yet the first
|
|
356
|
+
time someone hits the block, so the only way to answer it is manually, after
|
|
357
|
+
the fact, via `/bootstrap-config`.
|
|
358
|
+
|
|
355
359
|
`/git-commit` does still prompt — but only once the key is already settled *to a
|
|
356
360
|
value that means "keep asking"* (`confirm` for `versionBump`, `ask` for
|
|
357
361
|
`autoPush`). That is a consumer honouring a stored answer, not the question being
|
|
@@ -369,7 +373,7 @@ real `lib/scripts/` file or one real `lib/skills/<name>/SKILL.md`, so
|
|
|
369
373
|
`"install-global.sh, /git-commit"` fails the suite by construction. Where a
|
|
370
374
|
run-time prompt exists, it is documented in the key's `detail`.
|
|
371
375
|
|
|
372
|
-
### The key registry — all
|
|
376
|
+
### The key registry — all 25 entries
|
|
373
377
|
|
|
374
378
|
Every key in `templates/bootstrap-prefs-schema.json`, grouped by `consumer` —
|
|
375
379
|
`installer` first, then `skill` — which is the same grouping and the same order
|
|
@@ -408,22 +412,25 @@ Unicode-aware slug rule for `gitignore.section.*` are in
|
|
|
408
412
|
above; `gitignore.section.*`'s deliberate one-value grammar is in
|
|
409
413
|
[the section after it](#gitignoresection-has-a-one-value-grammar-on-purpose).
|
|
410
414
|
|
|
411
|
-
#### `consumer: skill` —
|
|
415
|
+
#### `consumer: skill` — 8 entries, read by slash commands at run time
|
|
412
416
|
|
|
413
417
|
| Key | Scope | Consumer | Values | Default | Asked by | What it does |
|
|
414
418
|
|-----|-------|----------|--------|---------|----------|--------------|
|
|
415
419
|
| `gitCommit.versionBump` | either | skill | `auto \| confirm \| never` | `auto` | `install-global.sh` | How `/git-commit` handles the version bump before committing |
|
|
416
420
|
| `gitCommit.autoPush` | either | skill | `true \| false \| ask` | `false` | `install-global.sh` | Whether `/git-commit` pushes after a successful commit |
|
|
417
421
|
| `gitCommit.lint` | either | skill | `true \| false` | `false` | `install-global.sh` | Whether `/git-commit` runs the /lint fix-cycle before committing |
|
|
422
|
+
| `packageInstall.consent` | project | skill | `true \| false \| ask` | `false` | `/bootstrap-config` | Whether `package-install-consent.js` allows package-manager installs for this project |
|
|
418
423
|
| `research.persistToRaw` | either | skill | `true \| false \| ask` | `true` | `install-global.sh` | Whether `/research` writes its report and sources to `raw/research/` |
|
|
419
424
|
| `research.autoIngest` | either | skill | `true \| false \| ask` | `false` | `install-global.sh` | Whether `/research` automatically wiki-ingests its saved report |
|
|
420
425
|
| `uatGenerate.promoteTests` | either | skill | `sibling \| never \| dedicated` | `dedicated` | `install-global.sh` | Where `/uat-generate` writes the unit tests it promotes out of UAT cases |
|
|
421
426
|
| `gitignore.offerSectionUpdates` | either | skill | `true \| false \| ask` | `true` | `install-global.sh` | Master gate for the `.gitignore` template section review pass |
|
|
422
427
|
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
428
|
+
Seven of these eight are the entire `scope: either` population — a key that
|
|
429
|
+
changes what a slash command does is exactly the kind of key a user may want to
|
|
430
|
+
answer once machine-wide and then override in one checkout. `packageInstall.consent`
|
|
431
|
+
is the exception: `scope: project` on purpose, because a package-install
|
|
432
|
+
trust decision is inherently per-project, not something to settle once for
|
|
433
|
+
every checkout on the machine.
|
|
427
434
|
|
|
428
435
|
**Every `installer` key has `default: null`; every `skill` key carries a real
|
|
429
436
|
default.** That asymmetry has a consequence worth stating: `prefs_get` alone
|
|
@@ -7,6 +7,11 @@
|
|
|
7
7
|
// global ~/.claude/bootstrap-prefs.json
|
|
8
8
|
// project <project>/.claude/bootstrap-prefs.json
|
|
9
9
|
//
|
|
10
|
+
// --project <dir> resolves to <dir>'s git repo root (walking up for `.git`),
|
|
11
|
+
// not <dir> itself — a caller running from a subdirectory still hits the
|
|
12
|
+
// one project-scoped file (see findProjectRoot). Non-git dirs fall back to
|
|
13
|
+
// the literal path unchanged.
|
|
14
|
+
//
|
|
10
15
|
// Four states per key: `unset` / a settled value / `false` / `ask`.
|
|
11
16
|
// ABSENCE IS `unset`. `null` is never written and "unset" is never stored as a
|
|
12
17
|
// string — deleting a key is how you re-open a question.
|
|
@@ -143,7 +148,7 @@ function parseArgs(argv) {
|
|
|
143
148
|
} else if (arg === '--global') {
|
|
144
149
|
opts.global = true;
|
|
145
150
|
} else if (arg === '--project') {
|
|
146
|
-
opts.projectDir = argv[++i];
|
|
151
|
+
opts.projectDir = findProjectRoot(argv[++i]);
|
|
147
152
|
} else if (arg === '--target') {
|
|
148
153
|
opts.target = argv[++i];
|
|
149
154
|
} else if (arg === '--schema') {
|
|
@@ -187,6 +192,20 @@ function projectFile(dir) {
|
|
|
187
192
|
return path.join(dir, '.claude', 'bootstrap-prefs.json');
|
|
188
193
|
}
|
|
189
194
|
|
|
195
|
+
// Resolves to the repo root, not the caller's cwd — a Bash command run from
|
|
196
|
+
// a subdirectory would otherwise miss the project's real prefs file. `.git`
|
|
197
|
+
// may be a file (worktrees) or a directory; falls back to the literal path
|
|
198
|
+
// (absolute) when none is found, leaving non-git test scratch dirs unaffected.
|
|
199
|
+
function findProjectRoot(dir) {
|
|
200
|
+
let current = path.resolve(dir);
|
|
201
|
+
while (true) {
|
|
202
|
+
if (fs.existsSync(path.join(current, '.git'))) return current;
|
|
203
|
+
const parent = path.dirname(current);
|
|
204
|
+
if (parent === current) return path.resolve(dir);
|
|
205
|
+
current = parent;
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
|
|
190
209
|
// ---------------------------------------------------------------- schema ----
|
|
191
210
|
|
|
192
211
|
// A missing or malformed schema is a warning, not a crash, and not a stop: the
|
|
@@ -5,7 +5,7 @@ set -euo pipefail
|
|
|
5
5
|
# structure (wiki/knowledge/ + wiki/work/). The mechanical scaffold is done by
|
|
6
6
|
# sync-wiki-scaffold.sh; the semantic conversion (frontmatter synthesis, ID
|
|
7
7
|
# renames, link rewriting, family indexes) is performed by Claude using the
|
|
8
|
-
# prompt template at lib/prompts/migrate-wiki.md
|
|
8
|
+
# prompt template at lib/prompts/migrate-wiki.md.
|
|
9
9
|
#
|
|
10
10
|
# Safety: requires a clean git tree and runs on a fresh `wiki-migration` branch
|
|
11
11
|
# so the entire migration is one reviewable diff. Files are `git mv`d before
|
|
@@ -41,7 +41,6 @@ echo " 2. Open Claude Code: claude"
|
|
|
41
41
|
echo " 3. Run /init to initialize the project"
|
|
42
42
|
echo " 4. Run /primer to set up Serena's memory structure"
|
|
43
43
|
echo " 5. Drop source documents into raw/ and run /wiki-ingest <file> to grow the wiki"
|
|
44
|
-
echo " 6. Optional: run 'npx @codewizard-dt/bootstrap deploy' when you explicitly want deployment scaffolding"
|
|
45
44
|
echo ""
|
|
46
45
|
echo "API keys (if you skipped any during setup):"
|
|
47
46
|
echo " brave-search BRAVE_API_KEY https://brave.com/search/api/"
|