@codewizard-dt/bootstrap 3.0.1 → 3.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.
@@ -0,0 +1,26 @@
1
+ name: Docker Fresh-Machine Harness
2
+
3
+ on:
4
+ pull_request:
5
+ paths:
6
+ - "test/docker/fresh-machine/**"
7
+ - "lib/scripts/**"
8
+
9
+ jobs:
10
+ fresh-machine:
11
+ runs-on: ubuntu-latest
12
+ steps:
13
+ - name: Checkout repo
14
+ uses: actions/checkout@v4
15
+
16
+ - name: Build fresh-machine image
17
+ run: docker build -t bootstrap-claude-fresh-machine test/docker/fresh-machine
18
+
19
+ - name: Run setup mode
20
+ run: ./test/docker/fresh-machine/run.sh setup
21
+
22
+ - name: Run update mode
23
+ run: ./test/docker/fresh-machine/run.sh update
24
+
25
+ # TASK-071 (stale mode) and TASK-072 (idempotency check) are still `status: todo` —
26
+ # add their run.sh modes as additional steps here once those tasks land.
@@ -39,6 +39,7 @@ These are **not** referenced by `bin/cli.js` or by any other script — they're
39
39
  |--------|---------|
40
40
  | `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
41
  | `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]`. |
42
43
 
43
44
  ## `templates/`
44
45
 
@@ -245,23 +245,198 @@ _enable_obsidian_plugin() {
245
245
  ' "$vault_dir" "$id" || true
246
246
  }
247
247
 
248
+ # _graph_defaults_node <template> <graph_file> <fingerprint_file> <mode> <decisions_json>
249
+ # Shared plan/apply logic: plan lists diverged keys needing a decision (no writes); apply resolves them via <decisions_json> and writes graph.json + fingerprint sidecar (changed files only). Template keys come from the packaged template's own Object.keys(), never hardcoded.
250
+ _graph_defaults_node() {
251
+ node -e '
252
+ const fs = require("fs");
253
+ const crypto = require("crypto");
254
+
255
+ const [templatePath, graphFile, fingerprintFile, mode, decisionsRaw] = process.argv.slice(1);
256
+
257
+ const hashOf = (v) => crypto.createHash("sha256").update(JSON.stringify(v)).digest("hex");
258
+
259
+ let template;
260
+ try {
261
+ template = JSON.parse(fs.readFileSync(templatePath, "utf8"));
262
+ } catch (e) {
263
+ console.error(" WARNING: could not read/parse the packaged graph.json template — skipping graph defaults.");
264
+ process.exit(0);
265
+ }
266
+ const templateKeys = Object.keys(template);
267
+
268
+ let existing = {};
269
+ if (fs.existsSync(graphFile)) {
270
+ try {
271
+ existing = JSON.parse(fs.readFileSync(graphFile, "utf8"));
272
+ } catch (e) {
273
+ console.error(" WARNING: could not parse existing graph.json — treating it as empty.");
274
+ existing = {};
275
+ }
276
+ }
277
+
278
+ let fingerprint = {};
279
+ if (fs.existsSync(fingerprintFile)) {
280
+ try {
281
+ const raw = JSON.parse(fs.readFileSync(fingerprintFile, "utf8"));
282
+ if (raw && typeof raw === "object" && !Array.isArray(raw)) fingerprint = raw;
283
+ else throw new Error("unexpected shape");
284
+ } catch (e) {
285
+ console.error(" WARNING: could not parse .graph-defaults-fingerprint.json — treating it as empty.");
286
+ fingerprint = {};
287
+ }
288
+ }
289
+
290
+ let decisions = {};
291
+ if (decisionsRaw) {
292
+ try {
293
+ decisions = JSON.parse(decisionsRaw);
294
+ } catch (e) {
295
+ decisions = {};
296
+ }
297
+ }
298
+
299
+ const merged = Object.assign({}, existing);
300
+ const newFingerprint = {};
301
+ const pending = [];
302
+ const added = [];
303
+ const refreshed = [];
304
+ const unchanged = [];
305
+ const kept = [];
306
+
307
+ for (const key of templateKeys) {
308
+ const templateValue = template[key];
309
+ const templateHash = hashOf(templateValue);
310
+ const hasKey = Object.prototype.hasOwnProperty.call(existing, key);
311
+ const fp = fingerprint[key] && typeof fingerprint[key] === "object" ? fingerprint[key] : {};
312
+
313
+ if (!hasKey) {
314
+ // Case 1: key absent from the existing file.
315
+ merged[key] = templateValue;
316
+ newFingerprint[key] = { offeredHash: templateHash };
317
+ added.push(key);
318
+ continue;
319
+ }
320
+
321
+ const fileHash = hashOf(existing[key]);
322
+
323
+ if (fp.offeredHash && fileHash === fp.offeredHash) {
324
+ // Case 2: file still holds exactly what we last delivered.
325
+ merged[key] = templateValue;
326
+ newFingerprint[key] = { offeredHash: templateHash };
327
+ (fileHash === templateHash ? unchanged : refreshed).push(key);
328
+ continue;
329
+ }
330
+
331
+ if (!fp.offeredHash && fileHash === templateHash) {
332
+ // Case 3, unmodified branch: no sidecar yet, but the file already
333
+ // matches todays template — bootstrap the fingerprint silently.
334
+ merged[key] = templateValue;
335
+ newFingerprint[key] = { offeredHash: templateHash };
336
+ unchanged.push(key);
337
+ continue;
338
+ }
339
+
340
+ // Case 4 (including the bootstrapped-diverged branch of case 3): the
341
+ // file has diverged from what we last offered.
342
+ if (fp.declinedHash && templateHash === fp.declinedHash) {
343
+ // Already declined exactly this template value — stay sticky.
344
+ merged[key] = existing[key];
345
+ newFingerprint[key] = fp;
346
+ kept.push(key);
347
+ continue;
348
+ }
349
+
350
+ if (mode === "plan") {
351
+ pending.push(key);
352
+ continue;
353
+ }
354
+
355
+ if (Object.prototype.hasOwnProperty.call(decisions, key)) {
356
+ if (decisions[key] === true) {
357
+ merged[key] = templateValue;
358
+ newFingerprint[key] = { offeredHash: templateHash };
359
+ refreshed.push(key);
360
+ } else {
361
+ merged[key] = existing[key];
362
+ newFingerprint[key] = Object.assign({}, fp, { declinedHash: templateHash });
363
+ kept.push(key);
364
+ }
365
+ } else {
366
+ // Non-interactive, or a plan-only pass with no decision supplied:
367
+ // leave the file untouched and record nothing, so a later
368
+ // interactive run still offers this key.
369
+ merged[key] = existing[key];
370
+ if (fp.offeredHash) newFingerprint[key] = { offeredHash: fp.offeredHash };
371
+ kept.push(key);
372
+ }
373
+ }
374
+
375
+ if (mode === "plan") {
376
+ for (const key of pending) console.log(key);
377
+ process.exit(0);
378
+ }
379
+
380
+ const graphStr = JSON.stringify(merged, null, 2) + "\n";
381
+ const fingerprintStr = JSON.stringify(newFingerprint, null, 2) + "\n";
382
+ const existingGraphStr = fs.existsSync(graphFile) ? fs.readFileSync(graphFile, "utf8") : null;
383
+ const existingFingerprintStr = fs.existsSync(fingerprintFile) ? fs.readFileSync(fingerprintFile, "utf8") : null;
384
+
385
+ if (graphStr !== existingGraphStr) {
386
+ const tmp = graphFile + ".tmp-" + process.pid;
387
+ fs.writeFileSync(tmp, graphStr);
388
+ fs.renameSync(tmp, graphFile);
389
+ }
390
+ if (fingerprintStr !== existingFingerprintStr) {
391
+ const tmp = fingerprintFile + ".tmp-" + process.pid;
392
+ fs.writeFileSync(tmp, fingerprintStr);
393
+ fs.renameSync(tmp, fingerprintFile);
394
+ }
395
+
396
+ const parts = [];
397
+ if (added.length) parts.push(added.length + " added");
398
+ if (refreshed.length) parts.push(refreshed.length + " refreshed");
399
+ if (unchanged.length) parts.push(unchanged.length + " unchanged");
400
+ if (kept.length) parts.push(kept.length + " kept (your customization)");
401
+ console.log(" graph.json: " + (parts.length ? parts.join(", ") : "no changes") + ".");
402
+ ' "$1" "$2" "$3" "$4" "$5"
403
+ }
404
+
405
+ # _install_obsidian_graph_defaults <vault_dir>
406
+ # Per-key sticky refresh (TASK-067) via a fingerprint sidecar, replacing the old whole-file write-if-absent check — never silently clobbers a genuinely user-diverged key. See _graph_defaults_node for the decision table.
248
407
  _install_obsidian_graph_defaults() {
249
408
  local vault_dir="$1"
409
+ local template="$SCRIPT_DIR/templates/obsidian/graph.json"
410
+ local graph_file="$vault_dir/.obsidian/graph.json"
411
+ local fingerprint_file="$vault_dir/.obsidian/.graph-defaults-fingerprint.json"
250
412
 
251
413
  if ! mkdir -p "$vault_dir/.obsidian"; then
252
414
  echo " WARNING: failed to create $vault_dir/.obsidian — skipping graph defaults." >&2
253
415
  return
254
416
  fi
255
417
 
256
- if [ -f "$vault_dir/.obsidian/graph.json" ]; then
257
- echo " .obsidian/graph.json already present — leaving your customization in place, skipping."
258
- return 0
259
- fi
418
+ local decisions="{}"
419
+ if [ "$INTERACTIVE" = true ]; then
420
+ local pending=() key
421
+ while IFS= read -r key; do
422
+ [ -n "$key" ] && pending+=("$key")
423
+ done < <(_graph_defaults_node "$template" "$graph_file" "$fingerprint_file" plan "{}")
260
424
 
261
- if ! cp "$SCRIPT_DIR/templates/obsidian/graph.json" "$vault_dir/.obsidian/graph.json"; then
262
- echo " WARNING: failed to install graph defaults — skipping." >&2
263
- return
425
+ if [ "${#pending[@]}" -gt 0 ]; then
426
+ local parts=() answer
427
+ for key in "${pending[@]}"; do
428
+ if prompt_yn " graph.json key '$key' differs from your saved customization — update to the new default? [y/N]: "; then
429
+ answer=true
430
+ else
431
+ answer=false
432
+ fi
433
+ parts+=("\"$key\":$answer")
434
+ done
435
+ decisions="{$(IFS=,; echo "${parts[*]}")}"
436
+ fi
264
437
  fi
438
+
439
+ _graph_defaults_node "$template" "$graph_file" "$fingerprint_file" apply "$decisions"
265
440
  }
266
441
 
267
442
  # ---------------------------------------------------------------------------
@@ -140,7 +140,7 @@
140
140
  "scope": "project",
141
141
  "consumer": "installer",
142
142
  "summary": "Install default graph-view styling (.obsidian/graph.json)",
143
- "detail": "Asked by install-obsidian.sh. true installs and refreshes .obsidian/graph.json with default graph-view styling if the file is absent; false means the installer stops offering it until the key is changed or removed via /bootstrap-config. This preference is independent of obsidian.plugins — accepting or declining one has no effect on the other. The file lives inside this project's own .obsidian/ directory, which is why this key is project scope, matching obsidian.plugins's scope choice.",
143
+ "detail": "Asked by install-obsidian.sh. true installs .obsidian/graph.json and thereafter keeps it refreshed per template key (search, colorGroups, and the boilerplate display-flag keys) via a sidecar fingerprint file, .obsidian/.graph-defaults-fingerprint.json: a key untouched since the last delivery is silently refreshed to the current template value, a key the user has diverged from gets a one-time interactive prompt asking whether to update it to the new default (a decline is sticky and not re-asked until that key's template value itself changes again), and non-interactive runs never prompt and never record a decline. Force/layout keys (centerStrength, repelStrength, etc.) are never part of the template and are always left untouched regardless of this key. false means the installer stops offering the feature at all until the key is changed or removed via /bootstrap-config. This preference is independent of obsidian.plugins — accepting or declining one has no effect on the other. The file lives inside this project's own .obsidian/ directory, which is why this key is project scope, matching obsidian.plugins's scope choice.",
144
144
  "values": "true | false",
145
145
  "default": null,
146
146
  "askedBy": "install-obsidian.sh"
@@ -31,7 +31,25 @@ Before committing, run the `/lint` workflow to catch and fix any diagnostics:
31
31
  2. If any fixes were applied, they will be included in the commit automatically
32
32
  3. If any issues were skipped (unfixable), warn the user before proceeding
33
33
 
34
- ## Step 2: Assess Changes
34
+ ## Step 2: Condense Verbose Inline Comments
35
+
36
+ Scan every line this commit **adds or modifies** for comments more verbose than necessary, and rewrite them to the shortest form that keeps the essential point — ideally one line.
37
+
38
+ **Scope: diff-only, not whole-file.** Run `git diff HEAD` and look only at `+` lines. A comment already sitting untouched elsewhere in a file is out of scope — never touch a comment this commit did not add or modify.
39
+
40
+ **Never touch — leave exactly as-is:**
41
+ - **Structured documentation comments**, in any language: JSDoc/TSDoc (`/** ... */`, especially with `@param`/`@returns`/`@throws`/`@example`), Python docstrings (`"""..."""`/`'''...'''` directly under a `def`/`class`), Rust doc comments (`///`, `//!`), Go doc comments (the block directly above an exported declaration, starting with that declaration's own name), Java/C# Javadoc/XMLDoc blocks. These document an API's contract, not implementation rationale — condensing them destroys structure a doc generator or IDE tooltip depends on.
42
+ - **Repo-documented comment exceptions.** Before editing a file, check whether the target repo's own `CLAUDE.md` (nearest one up the directory tree) explicitly carves out a comment-density exception for that file or directory (e.g. this repo's own `CLAUDE.md`: `lib/hooks/*.js` carries inline rationale comments "by deliberate exception... do not strip them"). Skip any file covered by such an exception entirely.
43
+ - Comments already a single concise line.
44
+
45
+ **Condense everything else:**
46
+ - If a comment restates what the code already makes obvious (the *what*) with no *why* — delete it entirely. Matches this repo's own default: "if removing the comment wouldn't confuse a future reader, don't write it."
47
+ - If it explains a genuinely non-obvious *why* (a workaround, a hidden constraint, a subtle invariant) but spans more lines or words than necessary, rewrite it to the single shortest sentence that preserves that reason.
48
+ - Preserve the comment's position (same line for a trailing comment, same location for a block comment) and its language's comment syntax — only the wording and line count change.
49
+
50
+ Use `Edit` per file for every change — never `sed`/`awk`/shell rewrites.
51
+
52
+ ## Step 3: Assess Changes
35
53
 
36
54
  **Always run all three commands fresh.** Do not rely on session context, prior output, or anything produced earlier in the conversation — those reflect only a subset of what may have changed. The commit message must be based on the complete current working-tree state.
37
55
 
@@ -41,7 +59,7 @@ Run all three in parallel:
41
59
  - `git diff HEAD` — see exact diffs for ALL staged and unstaged changes
42
60
  - `git log --oneline -10` — see recent commit history for context
43
61
 
44
- ## Step 3: Summarize Changes and Recommend Semver Bump
62
+ ## Step 4: Summarize Changes and Recommend Semver Bump
45
63
 
46
64
  Before touching any files or committing, output a summary block like this:
47
65
 
@@ -64,9 +82,9 @@ Use these semver rules to determine the bump:
64
82
  | **minor** | New features or capabilities that are backward-compatible; new commands, skills, config options, or APIs added without breaking existing ones |
65
83
  | **major** | Breaking changes — removed or renamed commands/APIs/config keys, changed behavior that callers must update for, deleted files that others depend on |
66
84
 
67
- Print the summary. What happens next is decided by `gitCommit.versionBump` from Step 0 — see the table in Step 4. **Do not ask for confirmation here**; the only value that asks is `confirm`, and it asks in Step 4 where the manifest list is known.
85
+ Print the summary. What happens next is decided by `gitCommit.versionBump` from Step 0 — see the table in Step 5. **Do not ask for confirmation here**; the only value that asks is `confirm`, and it asks in Step 5 where the manifest list is known.
68
86
 
69
- ## Step 4: Bump Version in Project Files
87
+ ## Step 5: Bump Version in Project Files
70
88
 
71
89
  ### Gate: `gitCommit.versionBump`
72
90
 
@@ -77,7 +95,7 @@ Its grammar is `auto | confirm | never` — there is deliberately **no `ask` val
77
95
  | `auto` | Today's behavior. Detect every manifest and apply the bump to all of them, no confirmation. | **written** |
78
96
  | `confirm` — approved | Bump exactly as `auto` does. | **written** |
79
97
  | `confirm` — declined | Edit no manifest. | **omitted** |
80
- | `never` | Touch **no** version file at all. Skip straight to Step 5. | **omitted** |
98
+ | `never` | Touch **no** version file at all. Skip straight to Step 6. | **omitted** |
81
99
  | `unset` | Behave exactly as `auto` — that is today's behavior and an unanswered key must never change it. | **written** |
82
100
 
83
101
  `confirm` prints the suggested bump **and the full list of manifest files that would change**, then asks once with `AskUserQuestion` before editing anything. Ask **every run** and **never persist the answer** — the standing choice is "keep asking me", so recording a reply would destroy it.
@@ -97,7 +115,7 @@ Report lines, each at most once per run:
97
115
 
98
116
  Anything else stored under this key is a value from a newer bootstrap that this skill has no branch for: treat it as `unset`, and say which value you did not recognize.
99
117
 
100
- For `auto`, `confirm`-approved, and `unset`, continue below. For `never` and `confirm`-declined, go to Step 5.
118
+ For `auto`, `confirm`-approved, and `unset`, continue below. For `never` and `confirm`-declined, go to Step 6.
101
119
 
102
120
  Find and update version numbers in project files.
103
121
 
@@ -118,7 +136,7 @@ Filter results:
118
136
 
119
137
  **There is no "root only" rule.** A manifest anywhere in the tree counts. Monorepo layouts with no root-level manifest are normal — update every package found.
120
138
 
121
- If **no files with a version field** are found anywhere in the repo, skip this step entirely and proceed to Step 5.
139
+ If **no files with a version field** are found anywhere in the repo, skip this step entirely and proceed to Step 6.
122
140
 
123
141
  ### Bumping rules
124
142
 
@@ -134,7 +152,7 @@ Pre-release tags (e.g. `1.0.0-beta.1`) — strip the pre-release suffix and appl
134
152
 
135
153
  Edit **every file** that contains a version using the Edit tool — do not stop at one. Then include all version-bump edits in the commit automatically (no separate commit needed).
136
154
 
137
- ## Step 5: Commit
155
+ ## Step 6: Commit
138
156
 
139
157
  ### ⛔ Never create a branch — commit on the current branch
140
158
 
@@ -144,7 +162,7 @@ Edit **every file** that contains a version using the Edit tool — do not stop
144
162
  - **ALWAYS use the `git-commit` bash alias.** Never use `git add` or `git commit` directly.
145
163
  - Always commit ALL files unless they are in `.gitignore`
146
164
  - Consider an appropriate commit message, let's call it `$message`
147
- - Prefix the subject with the bump type in brackets — `[patch]`, `[minor]`, or `[major]` — **only if Step 4 actually bumped a version**. If it did not (`never`, `confirm`-declined, or no manifest in the repo), the subject starts with the description and carries no bracket prefix
165
+ - Prefix the subject with the bump type in brackets — `[patch]`, `[minor]`, or `[major]` — **only if Step 5 actually bumped a version**. If it did not (`never`, `confirm`-declined, or no manifest in the repo), the subject starts with the description and carries no bracket prefix
148
166
  - Run: `git-commit "$message"`
149
167
 
150
168
  ### ⛔ No agent attribution — the user is the sole author
@@ -166,7 +184,7 @@ git-commit "[patch] Single-line subject describing the change"
166
184
  git-commit "Single-line subject describing the change"
167
185
  ```
168
186
 
169
- That's it. One pair of double quotes. One line. One argument. The only difference between the two forms is whether Step 4 bumped a version.
187
+ That's it. One pair of double quotes. One line. One argument. The only difference between the two forms is whether Step 5 bumped a version.
170
188
 
171
189
  **❌ Forbidden — every one of these patterns triggers an approval prompt:**
172
190
 
@@ -225,13 +243,13 @@ If the change feels too complex to summarize in one line, **make the subject mor
225
243
  - ✅ `Allow standard tools for markdown editing; ban bash exploration commands` (no bump this run — the subject still carries its weight)
226
244
  - ❌ `Update commands` (too vague — and vague is vague with or without a prefix)
227
245
  - ❌ `[patch] Fix bug` (too vague)
228
- - ❌ `[patch] Fix the login redirect` **when Step 4 bumped nothing** (the prefix is false)
246
+ - ❌ `[patch] Fix the login redirect` **when Step 5 bumped nothing** (the prefix is false)
229
247
 
230
248
  Detailed reasoning, before/after examples, and rationale belong in **PR descriptions**, not in commit message bodies. The commit subject is the index entry; the PR is the encyclopedia.
231
249
 
232
- ## Step 6: Push (gated on `gitCommit.autoPush`)
250
+ ## Step 7: Push (gated on `gitCommit.autoPush`)
233
251
 
234
- Runs only after the commit in Step 5 succeeded. A failed commit means there is nothing to push.
252
+ Runs only after the commit in Step 6 succeeded. A failed commit means there is nothing to push.
235
253
 
236
254
  | Value | What to do |
237
255
  |-------|------------|
@@ -242,14 +260,14 @@ Runs only after the commit in Step 5 succeeded. A failed commit means there is n
242
260
 
243
261
  ### ⛔ The push is the plainest possible push
244
262
 
245
- - **The Step 5 branch rule is unchanged and still absolute.** Never run `git branch`, `git checkout -b`, or `git switch -c`. Pushing an existing branch is all this step ever does.
263
+ - **The Step 6 branch rule is unchanged and still absolute.** Never run `git branch`, `git checkout -b`, or `git switch -c`. Pushing an existing branch is all this step ever does.
246
264
  - Never pass `--force`, `--force-with-lease`, `--set-upstream`/`-u`, `--all`, or `--tags`, and never name a different remote or refspec. Plain `git push`.
247
265
  - If the push fails for any reason — no upstream configured, no remote, rejected non-fast-forward, no credentials — **stop and report it**. The commit already succeeded and is safe; do not retry with extra flags, do not set an upstream, and do not attempt to reconcile with a pull or rebase.
248
266
 
249
- ## Step 7: Final report
267
+ ## Step 8: Final report
250
268
 
251
269
  One short report at the end. Include, in this order:
252
270
 
253
271
  1. The commit subject that was written.
254
- 2. Any of the once-only preference notes from Steps 4 and 6 that apply. Each appears **at most once per run**, here — not inline, and not repeated per file.
272
+ 2. Any of the once-only preference notes from Steps 5 and 7 that apply. Each appears **at most once per run**, here — not inline, and not repeated per file.
255
273
  3. The push outcome (pushed / not pushed and why / push failed and how).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@codewizard-dt/bootstrap",
3
- "version": "3.0.1",
3
+ "version": "3.1.0",
4
4
  "description": "Bootstrap Claude Code projects with an LLM Wiki, reusable skills, hooks, and MCP setup",
5
5
  "homepage": "https://github.com/codewizard-dt/bootstrap-wiki#readme",
6
6
  "bugs": {