@codewizard-dt/bootstrap 2.18.0 → 2.20.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/lib/scripts/README.md +36 -17
- package/lib/scripts/bootstrap-prefs.js +18 -0
- package/lib/scripts/install-global.sh +59 -5
- package/lib/scripts/install-obsidian.sh +294 -0
- package/lib/scripts/lib.sh +6 -0
- package/lib/scripts/templates/bootstrap-prefs-schema.json +33 -6
- package/lib/skills/bootstrap-config/SKILL.md +3 -3
- package/lib/skills/git-commit/SKILL.md +41 -11
- package/lib/skills/research/SKILL.md +24 -3
- package/lib/skills/task-add/SKILL.md +4 -0
- package/lib/skills/task-audit/SKILL.md +2 -0
- package/lib/skills/uat-generate/SKILL.md +26 -13
- package/package.json +1 -1
- package/raw/guides/dataview-queries.md +66 -0
package/lib/scripts/README.md
CHANGED
|
@@ -28,7 +28,7 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
|
|
|
28
28
|
| `merge-gitignore.sh` | `setup-project.sh`, `update-project.sh` | Fully interactive `.gitignore` merge — **nothing is ever added without asking**. The packaged template's titled sections are offered one by one (`Add/update .gitignore section '<title>' (N new line(s))? [y/N]`); sections with nothing new are skipped silently. Non-interactive runs (or no tty) change nothing at all. Never touches existing project content. Also offers (git repos only) to keep `.serena/`/`raw/`/`wiki/` out of git via **`.git/info/exclude`** — never `.gitignore`, which would blind Serena on the wiki (see `wiki/knowledge/concepts/git-ignore-tool-visibility.md`); per-machine and idempotent. `info/exclude` *is* honored by ripgrep-class walkers and the `@` file picker, so the excluded paths are written under a `# bootstrap wiki & agent state (machine-local)` sentinel that the `fileSuggestion` picker installed by `install-global.sh` reads back to restore `@`-autocomplete. |
|
|
29
29
|
| `merge-settings-deny.js` | `install-global.sh` | Zero-dependency Node script that merges the canonical permission deny list (`templates/settings-deny.json` — `Bash(...)` command patterns plus `Edit(...)`/`Read(...)` file-tool patterns) into `~/.claude/settings.json` `permissions.deny`. Entries are opaque strings, so any rule form the permission system accepts merges unchanged. Additive union only: missing entries are appended, user entries are never removed or reordered, all other settings keys pass through untouched. Atomic write, preserves existing indentation, and always exits 0 (warns + skips on unparseable or unexpected file shapes so an install never aborts over a settings merge). `--target`/`--source` flags exist as test seams. A second mode, `--set-key <name> --set-value <json>`, merges a single top-level settings key instead of the deny list (used to register `fileSuggestion`): absent → set; already deep-equal → no-op; present but different → one-line warning and skip, never a clobber. Supplying `--set-key` skips the deny merge entirely; a malformed `--set-value` exits 1, since that is a call-site bug rather than a user's file. |
|
|
30
30
|
| `merge-settings-hooks.js` | `install-global.sh` | Zero-dependency Node sibling of `merge-settings-deny.js` (deliberately not a new mode of it — different, block-and-entry-aware semantics) that merges the canonical hook wiring (`templates/settings-hooks.json`) into the `hooks` key of `~/.claude/settings.json` with a "template owns its blocks" model: repo-owned entries (a `command` under `~/.claude/hooks/` whose basename appears in the template) are created or updated in place; matcher drift on a pure-owned block is adopted (a matcher rename ships without duplicating the block); user/foreign blocks and entries are never modified, reordered, or removed; a repo hook found relocated into a mixed block is warned about but not duplicated; no empty placeholder blocks are ever written. Always exits 0 (warns + skips on unparseable or unexpected file shapes so an install never aborts over a settings merge). `--target`/`--source` flags exist as test seams. |
|
|
31
|
-
| `bootstrap-prefs.js` | `install-global.sh`, `install-mcps.sh`, `sync-wiki-scaffold.sh`, `merge-gitignore.sh`, `update-project.sh` (all through the `prefs_*` / `prompt_*_sticky` wrappers in `lib.sh`), and the `/bootstrap-config` skill | Zero-dependency Node reader/writer for the preference store — the one binary every consumer goes through, so no prompt site keeps its own copy of a key's value list. Five operations: `--get` (a resolving read; always exits 0, so no call site needs `\|\| true`), `--set`, `--unset`, `--list`, and `--section-key <title>` (turns a `.gitignore` banner title into its `gitignore.section.<slug>` key, so the slug rule has exactly one implementation and is Unicode-aware). `--set`/`--unset` require **exactly one** layer selector (`--global` / `--project <dir>` / `--target <path>`) and will not guess — a misdirected write is unrecoverable in a way a misdirected read is not; `--get` resolves across layers by default for the mirror-image reason. Values are validated against the schema's `values` grammar (an illegal value exits 1 — a caller bug must never land in the file and read back as `unset`); writes are atomic and reuse the file's existing indentation; and every successful `--set`/`--unset` regenerates the `bootstrap-prefs.README.md` companion beside the values file. See [Preference helper notes](#preference-helper-notes). |
|
|
31
|
+
| `bootstrap-prefs.js` | `install-global.sh`, `install-mcps.sh`, `sync-wiki-scaffold.sh`, `merge-gitignore.sh`, `update-project.sh` (all through the `prefs_*` / `prompt_*_sticky` wrappers in `lib.sh`), and the `/bootstrap-config` skill | Zero-dependency Node reader/writer for the preference store — the one binary every consumer goes through, so no prompt site keeps its own copy of a key's value list. Five operations: `--get` (a resolving read; always exits 0, so no call site needs `\|\| true`), `--set`, `--unset`, `--list`, and `--section-key <title>` (turns a `.gitignore` banner title into its `gitignore.section.<slug>` key, so the slug rule has exactly one implementation and is Unicode-aware). `--set`/`--unset` require **exactly one** layer selector (`--global` / `--project <dir>` / `--target <path>`) and will not guess — a misdirected write is unrecoverable in a way a misdirected read is not; `--get` resolves across layers by default for the mirror-image reason. Values are validated against the schema's `values` grammar (an illegal value exits 1 — a caller bug must never land in the file and read back as `unset`), and `--set` also refuses to write into a layer the key's `scope` forbids (`--target` stays exempt); writes are atomic and reuse the file's existing indentation; and every successful `--set`/`--unset` regenerates the `bootstrap-prefs.README.md` companion beside the values file. See [Preference helper notes](#preference-helper-notes). |
|
|
32
32
|
|
|
33
33
|
## Standalone infra scripts (not wired to the CLI)
|
|
34
34
|
|
|
@@ -178,6 +178,16 @@ three is the whole point of the subsystem.
|
|
|
178
178
|
**`confirm`**, inside its own `auto | confirm | never` grammar. It has
|
|
179
179
|
deliberately no separate `ask` value, and offering one is a hard failure —
|
|
180
180
|
`--set gitCommit.versionBump --value ask` exits 1.
|
|
181
|
+
- **The commit-subject prefix follows the bump**, for that same key. `/git-commit`
|
|
182
|
+
writes `[patch]`/`[minor]`/`[major]` **if and only if** it actually bumped a
|
|
183
|
+
version: written under `auto` and an approved `confirm`, omitted under `never`
|
|
184
|
+
and a declined `confirm`. An earlier contract wrote it unconditionally so that
|
|
185
|
+
release tooling "kept working"; that was backwards. The prefix is a claim about
|
|
186
|
+
what the commit did and tooling acts on it, so a `[minor]` on a commit that
|
|
187
|
+
bumped nothing publishes a release with no version change behind it. Pinned by
|
|
188
|
+
`test/bootstrap-prefs.test.js`, across the skill, the schema `detail`, and the
|
|
189
|
+
installer prompt — a user who picks `never` from the prompt's own description
|
|
190
|
+
and then finds a prefix on their commit was mis-sold.
|
|
181
191
|
|
|
182
192
|
### The installed layout is what makes skill keys readable
|
|
183
193
|
|
|
@@ -234,16 +244,22 @@ records only whether to install the server. Treat this as a rule when adding a
|
|
|
234
244
|
key: if the answer to a question is a credential, the question does not belong in
|
|
235
245
|
this store.
|
|
236
246
|
|
|
237
|
-
###
|
|
238
|
-
|
|
239
|
-
`--set` validates the *value* against the schema's `values` string,
|
|
240
|
-
|
|
241
|
-
key
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
`scope
|
|
247
|
+
### `--set` enforces a key's grammar AND its scope
|
|
248
|
+
|
|
249
|
+
`--set` validates the *value* against the schema's `values` string, and also
|
|
250
|
+
checks that the chosen layer is one the key's `scope` permits — writing a
|
|
251
|
+
`global`-scope key into a project values file (or vice versa) exits `1` with
|
|
252
|
+
nothing written, naming the actual scope and the layer that would be
|
|
253
|
+
consulted instead. `--target <path>` remains the deliberate, exempt escape
|
|
254
|
+
hatch: it always bypasses the scope check, since it is an explicit
|
|
255
|
+
single-file operation rather than a resolved layer. Fixed as
|
|
256
|
+
[`BUG-0009`](../../wiki/work/bugs/archive/BUG-0009-set-writes-scope-inert-key-silently.md)
|
|
257
|
+
(previously: the write silently succeeded and printed an affirmative line
|
|
258
|
+
while landing in a layer `resolve()` never walks). A scope-inert key can
|
|
259
|
+
still exist — via `--target`, a hand edit, or a values file written by a
|
|
260
|
+
newer bootstrap — and the generated companion's `## Unrecognized keys`
|
|
261
|
+
section still explains it the same way: `scope is ... — this layer never
|
|
262
|
+
consults it, so it has no effect here`.
|
|
247
263
|
|
|
248
264
|
## Preference-schema notes
|
|
249
265
|
|
|
@@ -251,7 +267,7 @@ The shape contract for `templates/bootstrap-prefs-schema.json`. JSON cannot carr
|
|
|
251
267
|
comments, so the file itself must stay bare — no `$comment` header, no explanatory
|
|
252
268
|
keys — and everything a reader or a new consumer needs to know about its shape
|
|
253
269
|
lives here instead. What each individual key *does* is a separate question, and
|
|
254
|
-
it is answered by [The key registry — all
|
|
270
|
+
it is answered by [The key registry — all 21 entries](#the-key-registry--all-21-entries)
|
|
255
271
|
at the end of this section.
|
|
256
272
|
|
|
257
273
|
### Flat key → entry, and eight fields
|
|
@@ -351,7 +367,7 @@ real `lib/scripts/` file or one real `lib/skills/<name>/SKILL.md`, so
|
|
|
351
367
|
`"install-global.sh, /git-commit"` fails the suite by construction. Where a
|
|
352
368
|
run-time prompt exists, it is documented in the key's `detail`.
|
|
353
369
|
|
|
354
|
-
### The key registry — all
|
|
370
|
+
### The key registry — all 22 entries
|
|
355
371
|
|
|
356
372
|
Every key in `templates/bootstrap-prefs-schema.json`, grouped by `consumer` —
|
|
357
373
|
`installer` first, then `skill` — which is the same grouping and the same order
|
|
@@ -360,7 +376,7 @@ schema's `default` field; `unset` in that column means `default: null`, i.e. the
|
|
|
360
376
|
key resolves to `unset` until it is answered. This table is transcribed from the
|
|
361
377
|
JSON; if the two ever disagree, the JSON is right and this table is a bug.
|
|
362
378
|
|
|
363
|
-
#### `consumer: installer` —
|
|
379
|
+
#### `consumer: installer` — 16 entries, read by the setup/update scripts
|
|
364
380
|
|
|
365
381
|
| Key | Scope | Consumer | Values | Default | Asked by | What it does |
|
|
366
382
|
|-----|-------|----------|--------|---------|----------|--------------|
|
|
@@ -377,6 +393,8 @@ JSON; if the two ever disagree, the JSON is right and this table is a bug.
|
|
|
377
393
|
| `mcp.context7` | global | installer | `true \| false` | `unset` | `install-mcps.sh` | Install the Context7 MCP for library documentation lookups |
|
|
378
394
|
| `mcp.context7Scope` | global | installer | `user \| project` | `unset` | `lib.sh` | Registration scope for the Context7 MCP |
|
|
379
395
|
| `mcp.playwright` | global | installer | `true \| false` | `unset` | `install-mcps.sh` | Install the Playwright MCP for browser automation and UI testing |
|
|
396
|
+
| `obsidian.installApp` | global | installer | `true \| false` | `unset` | `install-obsidian.sh` | Install the Obsidian desktop app via the native package manager |
|
|
397
|
+
| `obsidian.plugins` | project | installer | `true \| false` | `unset` | `install-obsidian.sh` | Install the bundled Obsidian plugin set (Dataview, Graph Link Types, Breadcrumbs) |
|
|
380
398
|
| `skills.pruneOrphans` | global | installer | `true \| false` | `unset` | `install-global.sh` | Delete stale skill folders in `~/.claude/skills/` left by the wiki rename |
|
|
381
399
|
|
|
382
400
|
The two **(pattern)** rows carry `"dynamic": true` and are key *families*, not
|
|
@@ -387,17 +405,18 @@ Unicode-aware slug rule for `gitignore.section.*` are in
|
|
|
387
405
|
above; `gitignore.section.*`'s deliberate one-value grammar is in
|
|
388
406
|
[the section after it](#gitignoresection-has-a-one-value-grammar-on-purpose).
|
|
389
407
|
|
|
390
|
-
#### `consumer: skill` —
|
|
408
|
+
#### `consumer: skill` — 6 entries, read by slash commands at run time
|
|
391
409
|
|
|
392
410
|
| Key | Scope | Consumer | Values | Default | Asked by | What it does |
|
|
393
411
|
|-----|-------|----------|--------|---------|----------|--------------|
|
|
394
412
|
| `gitCommit.versionBump` | either | skill | `auto \| confirm \| never` | `auto` | `install-global.sh` | How `/git-commit` handles the version bump before committing |
|
|
395
413
|
| `gitCommit.autoPush` | either | skill | `true \| false \| ask` | `false` | `install-global.sh` | Whether `/git-commit` pushes after a successful commit |
|
|
396
414
|
| `research.persistToRaw` | either | skill | `true \| false \| ask` | `true` | `install-global.sh` | Whether `/research` writes its report and sources to `raw/research/` |
|
|
397
|
-
| `
|
|
415
|
+
| `research.autoIngest` | either | skill | `true \| false \| ask` | `false` | `install-global.sh` | Whether `/research` automatically wiki-ingests its saved report |
|
|
416
|
+
| `uatGenerate.promoteTests` | either | skill | `sibling \| never \| dedicated` | `dedicated` | `install-global.sh` | Where `/uat-generate` writes the unit tests it promotes out of UAT cases |
|
|
398
417
|
| `gitignore.offerSectionUpdates` | either | skill | `true \| false \| ask` | `true` | `install-global.sh` | Master gate for the `.gitignore` template section review pass |
|
|
399
418
|
|
|
400
|
-
These
|
|
419
|
+
These six are the entire `scope: either` population and the entire
|
|
401
420
|
`consumer: skill` population — the two sets coincide, because a key that changes
|
|
402
421
|
what a slash command does is exactly the kind of key a user may want to answer
|
|
403
422
|
once machine-wide and then override in one checkout.
|
|
@@ -693,6 +693,24 @@ if (opts.op === 'set') {
|
|
|
693
693
|
);
|
|
694
694
|
process.exit(1);
|
|
695
695
|
}
|
|
696
|
+
|
|
697
|
+
// BUG-0009: --set validated the value grammar but never the key's scope,
|
|
698
|
+
// so a global-scope key could be written into a project file (or vice
|
|
699
|
+
// versa) — the write succeeded, printed an affirmative line, and landed
|
|
700
|
+
// in a layer resolve() never walks for that scope, so it silently did
|
|
701
|
+
// nothing. --target is exempt (scopePermitsLayer returns true for it
|
|
702
|
+
// unconditionally); --unset is deliberately left permissive elsewhere,
|
|
703
|
+
// since unsetting an inert key is harmless and is the documented
|
|
704
|
+
// workaround for a key already stuck in the wrong layer.
|
|
705
|
+
if (!scopePermitsLayer(entry, targetLayer)) {
|
|
706
|
+
const correctLayer =
|
|
707
|
+
entry.scope === 'global' ? '--global' : entry.scope === 'project' ? '--project <dir>' : '--global or --project <dir>';
|
|
708
|
+
console.error(
|
|
709
|
+
`Error: "${opts.key}" is scope: ${entry.scope} — the ${targetLayer} layer never reads it, so this write ` +
|
|
710
|
+
`would be inert. Use ${correctLayer} instead, or --target <path> to force a specific file.`
|
|
711
|
+
);
|
|
712
|
+
process.exit(1);
|
|
713
|
+
}
|
|
696
714
|
}
|
|
697
715
|
|
|
698
716
|
// 'true'/'false' become JSON booleans; everything else is a JSON string.
|
|
@@ -197,7 +197,7 @@ settle_skill_pref() {
|
|
|
197
197
|
case "$answer" in
|
|
198
198
|
yes) prefs_set "$key" --global true ; echo " $key = true" ;;
|
|
199
199
|
no) prefs_set "$key" --global false ; echo " $key = false" ;;
|
|
200
|
-
ask) prefs_set "$key" --global ask ; echo " $key = ask (
|
|
200
|
+
ask) prefs_set "$key" --global ask ; echo " $key = ask (the skill will prompt you each time it runs; that per-run answer is never stored)" ;;
|
|
201
201
|
*) echo " $key left unanswered — today's behavior is unchanged, and you will be asked again next sync." ;;
|
|
202
202
|
esac
|
|
203
203
|
PREFS_ASKED=$(( PREFS_ASKED + 1 ))
|
|
@@ -214,7 +214,7 @@ else
|
|
|
214
214
|
echo ""
|
|
215
215
|
echo " Should /git-commit bump the version in package.json (and every other manifest) before committing?"
|
|
216
216
|
echo " Say 'never' for apps and private repos; 'auto' for published packages. The [patch]/[minor]/[major]"
|
|
217
|
-
echo " subject prefix
|
|
217
|
+
echo " subject prefix follows the bump — written when one happens, omitted when it doesn't."
|
|
218
218
|
VERSION_BUMP_ANSWER="$(prompt_letter_choice skip " [a]uto / [c]onfirm each time / [n]ever / [s]kip for now: " auto confirm never skip)"
|
|
219
219
|
case "$VERSION_BUMP_ANSWER" in
|
|
220
220
|
auto|confirm|never)
|
|
@@ -232,8 +232,51 @@ else
|
|
|
232
232
|
"Should /git-commit push the current branch after committing? (Default no — this turns a local action into a published one. It never creates a branch either way.)"
|
|
233
233
|
settle_skill_pref research.persistToRaw \
|
|
234
234
|
"Should /research save its report and sources to raw/research/ by default? (Findings always appear in the reply; this governs the file write only, and you can still decline any single report.)"
|
|
235
|
-
settle_skill_pref
|
|
236
|
-
"Should /
|
|
235
|
+
settle_skill_pref research.autoIngest \
|
|
236
|
+
"Should /research automatically fold a saved report into wiki/ (/wiki-ingest) instead of just suggesting the command? (Only runs when a report was actually saved.)"
|
|
237
|
+
# uatGenerate.promoteTests is the second key that cannot go through
|
|
238
|
+
# settle_skill_pref: its grammar is sibling|never|dedicated (plus the
|
|
239
|
+
# parameterized dedicated:<path>), not true|false|ask.
|
|
240
|
+
#
|
|
241
|
+
# THE OPTION NAMED HERE IS `beside`, THE VALUE STORED IS `sibling`.
|
|
242
|
+
# prompt_letter_choice matches on FIRST LETTER and takes the first listed name
|
|
243
|
+
# that matches, so offering `sibling` alongside `skip` would silently make one
|
|
244
|
+
# of the two unreachable — whichever came second could never be typed. `beside`
|
|
245
|
+
# collides with nothing and reads better in the prompt; the case below maps it
|
|
246
|
+
# back to the schema's value.
|
|
247
|
+
if ! prefs_stored_global uatGenerate.promoteTests; then
|
|
248
|
+
echo ""
|
|
249
|
+
echo " Where should /uat-generate write the unit tests it promotes out of UAT cases?"
|
|
250
|
+
echo " A dedicated folder keeps the suite in one place; beside puts src/parse.ts's test at"
|
|
251
|
+
echo " src/parse.test.ts. A project's existing layout always wins over this answer."
|
|
252
|
+
TEST_LOCATION_ANSWER="$(prompt_letter_choice skip \
|
|
253
|
+
" [d]edicated folder / [b]eside each file / [n]ever write tests / [s]kip for now: " \
|
|
254
|
+
dedicated beside never skip)"
|
|
255
|
+
case "$TEST_LOCATION_ANSWER" in
|
|
256
|
+
dedicated)
|
|
257
|
+
# No follow-up asking WHICH folder. `values` is a closed enumeration of
|
|
258
|
+
# literal tokens, and that closedness is what guarantees no preference key
|
|
259
|
+
# can hold an arbitrary string (see the schema's own no-secrets rule) — a
|
|
260
|
+
# stored path would be exactly that. The skill resolves the directory from
|
|
261
|
+
# the repo instead: an existing test directory, else the language default.
|
|
262
|
+
prefs_set uatGenerate.promoteTests --global dedicated
|
|
263
|
+
echo " uatGenerate.promoteTests = dedicated"
|
|
264
|
+
;;
|
|
265
|
+
beside)
|
|
266
|
+
prefs_set uatGenerate.promoteTests --global sibling
|
|
267
|
+
echo " uatGenerate.promoteTests = sibling"
|
|
268
|
+
;;
|
|
269
|
+
never)
|
|
270
|
+
prefs_set uatGenerate.promoteTests --global never
|
|
271
|
+
echo " uatGenerate.promoteTests = never"
|
|
272
|
+
;;
|
|
273
|
+
*)
|
|
274
|
+
echo " uatGenerate.promoteTests left unanswered — today's behavior (a dedicated test folder) is unchanged, and you will be asked again next sync."
|
|
275
|
+
;;
|
|
276
|
+
esac
|
|
277
|
+
PREFS_ASKED=$(( PREFS_ASKED + 1 ))
|
|
278
|
+
fi
|
|
279
|
+
|
|
237
280
|
settle_skill_pref gitignore.offerSectionUpdates \
|
|
238
281
|
"Should setup/update offer .gitignore template section updates? (No stops the opening question entirely. The .git/info/exclude block is separate and is unaffected.)"
|
|
239
282
|
|
|
@@ -261,4 +304,15 @@ if [ "$SKIP_MCPS" = false ]; then
|
|
|
261
304
|
echo ""
|
|
262
305
|
fi
|
|
263
306
|
|
|
264
|
-
|
|
307
|
+
# "preferences" stays unconditional regardless of SKIP_MCPS: step 6 always
|
|
308
|
+
# installs the helper on every pass, whether or not anything was actually
|
|
309
|
+
# asked (a non-tty run still installs it, it just settles no answers) — see
|
|
310
|
+
# BUG-0010. "MCPs" is the one token gated on what actually ran, since step 8
|
|
311
|
+
# is skipped entirely under --skip-mcps and claiming it otherwise overstates
|
|
312
|
+
# the summary's own job (evidence of what ran) on the most common invocation
|
|
313
|
+
# path — both setup-project.sh and update-project.sh call this with --skip-mcps.
|
|
314
|
+
if [ "$SKIP_MCPS" = false ]; then
|
|
315
|
+
echo "Global setup complete (hooks + skills + deny list + hooks wiring + file suggestion + preferences + MCPs)."
|
|
316
|
+
else
|
|
317
|
+
echo "Global setup complete (hooks + skills + deny list + hooks wiring + file suggestion + preferences)."
|
|
318
|
+
fi
|
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
set -euo pipefail
|
|
3
|
+
|
|
4
|
+
# install-obsidian.sh [--interactive] [--project-dir <dir>]
|
|
5
|
+
|
|
6
|
+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
7
|
+
. "$SCRIPT_DIR/lib.sh"
|
|
8
|
+
|
|
9
|
+
INTERACTIVE=false
|
|
10
|
+
PROJECT_DIR=""
|
|
11
|
+
|
|
12
|
+
while [[ $# -gt 0 ]]; do
|
|
13
|
+
case "$1" in
|
|
14
|
+
--interactive) INTERACTIVE=true; shift ;;
|
|
15
|
+
--project-dir) PROJECT_DIR="$2"; shift 2 ;;
|
|
16
|
+
*) shift ;;
|
|
17
|
+
esac
|
|
18
|
+
done
|
|
19
|
+
|
|
20
|
+
# Plugin repo slugs, pinned as named constants (never fetched or derived at
|
|
21
|
+
# runtime) so every releases/latest lookup below is driven by one audited
|
|
22
|
+
# value per plugin.
|
|
23
|
+
PLUGIN_DATAVIEW="blacksmithgu/obsidian-dataview"
|
|
24
|
+
PLUGIN_GRAPH_LINK_TYPES="natefrisch01/Graph-Link-Types"
|
|
25
|
+
# NOTE: prior research flagged an in-progress maintainer transition for
|
|
26
|
+
# Breadcrumbs — verify SkepticMystic/breadcrumbs is still the maintained fork
|
|
27
|
+
# at install time (vs. a community fork) before relying on this constant.
|
|
28
|
+
PLUGIN_BREADCRUMBS="SkepticMystic/breadcrumbs"
|
|
29
|
+
|
|
30
|
+
_install_obsidian_app() {
|
|
31
|
+
local os
|
|
32
|
+
os="$(uname -s)"
|
|
33
|
+
|
|
34
|
+
case "$os" in
|
|
35
|
+
Darwin)
|
|
36
|
+
if [ -d /Applications/Obsidian.app ]; then
|
|
37
|
+
echo " Obsidian.app already installed — skipping."
|
|
38
|
+
return 0
|
|
39
|
+
fi
|
|
40
|
+
brew install --cask obsidian \
|
|
41
|
+
|| echo " WARNING: 'brew install --cask obsidian' failed — install Obsidian manually from https://obsidian.md/download"
|
|
42
|
+
;;
|
|
43
|
+
Linux)
|
|
44
|
+
if flatpak list 2>/dev/null | grep -q md.obsidian.Obsidian; then
|
|
45
|
+
echo " Obsidian (flatpak) already installed — skipping."
|
|
46
|
+
return 0
|
|
47
|
+
fi
|
|
48
|
+
if ! command -v flatpak >/dev/null 2>&1; then
|
|
49
|
+
echo " WARNING: flatpak not found — install Obsidian manually from https://obsidian.md/download"
|
|
50
|
+
return 0
|
|
51
|
+
fi
|
|
52
|
+
flatpak install -y flathub md.obsidian.Obsidian \
|
|
53
|
+
|| echo " WARNING: 'flatpak install -y flathub md.obsidian.Obsidian' failed — install Obsidian manually from https://obsidian.md/download"
|
|
54
|
+
;;
|
|
55
|
+
*)
|
|
56
|
+
echo " Obsidian: no automated installer for '$os' — install manually from https://obsidian.md/download"
|
|
57
|
+
;;
|
|
58
|
+
esac
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
# _gh_release_asset_url <release_json_file> <asset_name>
|
|
62
|
+
# Prints the browser_download_url of a named asset from a GitHub
|
|
63
|
+
# releases/latest JSON payload already saved to disk; prints nothing if the
|
|
64
|
+
# asset is absent OR the file isn't parseable JSON in the expected shape —
|
|
65
|
+
# callers treat "empty" as the single signal to warn and skip, so a bare
|
|
66
|
+
# `node -e` failure can never trip `set -e` here. Mirrors the
|
|
67
|
+
# JSON.parse + readFileSync + try/catch style used by install-mcps.sh's
|
|
68
|
+
# _disable_project_playwright_locally.
|
|
69
|
+
_gh_release_asset_url() {
|
|
70
|
+
node -e '
|
|
71
|
+
const fs = require("fs");
|
|
72
|
+
try {
|
|
73
|
+
const data = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
|
|
74
|
+
const asset = (data.assets || []).find((a) => a.name === process.argv[2]);
|
|
75
|
+
if (asset && asset.browser_download_url) console.log(asset.browser_download_url);
|
|
76
|
+
} catch (e) {
|
|
77
|
+
// Malformed JSON or unexpected shape — print nothing; the caller warns
|
|
78
|
+
// on the resulting empty string rather than on a node exit code.
|
|
79
|
+
}
|
|
80
|
+
' "$1" "$2"
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
# _install_obsidian_plugin <vault_dir> <owner_repo>
|
|
84
|
+
# Installs one community plugin from its GitHub releases/latest into
|
|
85
|
+
# <vault_dir>/.obsidian/plugins/<id>/, where <id> comes from the release's
|
|
86
|
+
# manifest.json — the authoritative plugin directory name, NOT the GitHub
|
|
87
|
+
# repo name. manifest.json is downloaded and parsed FIRST, before anything
|
|
88
|
+
# else. Every risky step (curl, JSON parsing, mkdir) warns to stderr and
|
|
89
|
+
# returns rather than aborting the script, so one bad/renamed plugin repo
|
|
90
|
+
# never blocks the other two or the rest of the install.
|
|
91
|
+
#
|
|
92
|
+
# Prints the resolved plugin id to stdout as its ONLY stdout output — bash
|
|
93
|
+
# functions can't return strings, so the caller captures it via:
|
|
94
|
+
# plugin_id="$(_install_obsidian_plugin "$vault_dir" "$owner_repo")"
|
|
95
|
+
# All diagnostics go to stderr (`>&2`) specifically so they never end up
|
|
96
|
+
# inside that captured value.
|
|
97
|
+
_install_obsidian_plugin() {
|
|
98
|
+
local vault_dir="$1" owner_repo="$2"
|
|
99
|
+
local release_tmp manifest_tmp manifest_url main_js_url styles_css_url
|
|
100
|
+
local plugin_id plugin_dir
|
|
101
|
+
|
|
102
|
+
release_tmp="$(mktemp)"
|
|
103
|
+
if ! curl -fsSL "https://api.github.com/repos/${owner_repo}/releases/latest" -o "$release_tmp"; then
|
|
104
|
+
echo " WARNING: ${owner_repo}: failed to fetch latest release — skipping plugin." >&2
|
|
105
|
+
rm -f "$release_tmp"
|
|
106
|
+
return
|
|
107
|
+
fi
|
|
108
|
+
if [ ! -s "$release_tmp" ]; then
|
|
109
|
+
echo " WARNING: ${owner_repo}: empty release response — skipping plugin." >&2
|
|
110
|
+
rm -f "$release_tmp"
|
|
111
|
+
return
|
|
112
|
+
fi
|
|
113
|
+
|
|
114
|
+
manifest_url="$(_gh_release_asset_url "$release_tmp" manifest.json)"
|
|
115
|
+
if [ -z "$manifest_url" ]; then
|
|
116
|
+
echo " WARNING: ${owner_repo}: latest release has no manifest.json asset (or the release JSON was malformed) — skipping plugin." >&2
|
|
117
|
+
rm -f "$release_tmp"
|
|
118
|
+
return
|
|
119
|
+
fi
|
|
120
|
+
|
|
121
|
+
manifest_tmp="$(mktemp)"
|
|
122
|
+
if ! curl -fsSL "$manifest_url" -o "$manifest_tmp"; then
|
|
123
|
+
echo " WARNING: ${owner_repo}: failed to download manifest.json — skipping plugin." >&2
|
|
124
|
+
rm -f "$release_tmp" "$manifest_tmp"
|
|
125
|
+
return
|
|
126
|
+
fi
|
|
127
|
+
|
|
128
|
+
plugin_id="$(node -e '
|
|
129
|
+
const fs = require("fs");
|
|
130
|
+
try {
|
|
131
|
+
const data = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
|
|
132
|
+
if (data && typeof data.id === "string" && data.id) console.log(data.id);
|
|
133
|
+
} catch (e) {
|
|
134
|
+
// Malformed manifest.json — print nothing; caller warns on the empty
|
|
135
|
+
// result below.
|
|
136
|
+
}
|
|
137
|
+
' "$manifest_tmp")"
|
|
138
|
+
if [ -z "$plugin_id" ]; then
|
|
139
|
+
echo " WARNING: ${owner_repo}: manifest.json is missing/malformed its 'id' field — skipping plugin." >&2
|
|
140
|
+
rm -f "$release_tmp" "$manifest_tmp"
|
|
141
|
+
return
|
|
142
|
+
fi
|
|
143
|
+
|
|
144
|
+
plugin_dir="$vault_dir/.obsidian/plugins/$plugin_id"
|
|
145
|
+
if ! mkdir -p "$plugin_dir"; then
|
|
146
|
+
echo " WARNING: ${owner_repo}: failed to create $plugin_dir — skipping plugin." >&2
|
|
147
|
+
rm -f "$release_tmp" "$manifest_tmp"
|
|
148
|
+
return
|
|
149
|
+
fi
|
|
150
|
+
|
|
151
|
+
# Obsidian requires manifest.json inside the plugin's own directory to
|
|
152
|
+
# recognize and load it — copy the file we already fetched (and already
|
|
153
|
+
# parsed plugin_id from) rather than re-downloading it. See BUG-0011: an
|
|
154
|
+
# earlier version parsed plugin_id from manifest_tmp and then discarded it
|
|
155
|
+
# without ever writing it into plugin_dir, so every plugin ended up enabled
|
|
156
|
+
# in community-plugins.json but missing the manifest Obsidian needs to load it.
|
|
157
|
+
if ! cp "$manifest_tmp" "$plugin_dir/manifest.json"; then
|
|
158
|
+
echo " WARNING: ${owner_repo}: failed to write manifest.json into $plugin_dir — skipping plugin." >&2
|
|
159
|
+
rm -f "$release_tmp" "$manifest_tmp"
|
|
160
|
+
return
|
|
161
|
+
fi
|
|
162
|
+
|
|
163
|
+
main_js_url="$(_gh_release_asset_url "$release_tmp" main.js)"
|
|
164
|
+
if [ -z "$main_js_url" ]; then
|
|
165
|
+
echo " WARNING: ${owner_repo}: latest release has no main.js asset — skipping plugin." >&2
|
|
166
|
+
rm -f "$release_tmp" "$manifest_tmp"
|
|
167
|
+
return
|
|
168
|
+
fi
|
|
169
|
+
if ! curl -fsSL "$main_js_url" -o "$plugin_dir/main.js"; then
|
|
170
|
+
echo " WARNING: ${owner_repo}: failed to download main.js — skipping plugin." >&2
|
|
171
|
+
rm -f "$release_tmp" "$manifest_tmp"
|
|
172
|
+
return
|
|
173
|
+
fi
|
|
174
|
+
|
|
175
|
+
# styles.css is optional — silently skip when the release doesn't ship one.
|
|
176
|
+
styles_css_url="$(_gh_release_asset_url "$release_tmp" styles.css)"
|
|
177
|
+
if [ -n "$styles_css_url" ]; then
|
|
178
|
+
curl -fsSL "$styles_css_url" -o "$plugin_dir/styles.css" \
|
|
179
|
+
|| echo " WARNING: ${owner_repo}: failed to download styles.css — continuing without it." >&2
|
|
180
|
+
fi
|
|
181
|
+
|
|
182
|
+
rm -f "$release_tmp" "$manifest_tmp"
|
|
183
|
+
echo "$plugin_id"
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
# _enable_obsidian_plugin <vault_dir> <id>
|
|
187
|
+
# Idempotently adds <id> to <vault_dir>/.obsidian/community-plugins.json —
|
|
188
|
+
# creates the file as ["<id>"] if absent (mkdir -p'ing .obsidian first), else
|
|
189
|
+
# appends <id> only if not already present. Mirrors install-mcps.sh's
|
|
190
|
+
# _disable_project_playwright_locally: warns and skips (never crashes or
|
|
191
|
+
# overwrites) on unparseable JSON or an unexpected (non-array) shape, and
|
|
192
|
+
# never aborts the calling script on any failure.
|
|
193
|
+
_enable_obsidian_plugin() {
|
|
194
|
+
local vault_dir="$1" id="$2"
|
|
195
|
+
node -e '
|
|
196
|
+
const fs = require("fs"), path = require("path");
|
|
197
|
+
const vaultDir = process.argv[1], id = process.argv[2];
|
|
198
|
+
const dir = path.join(vaultDir, ".obsidian");
|
|
199
|
+
const file = path.join(dir, "community-plugins.json");
|
|
200
|
+
let list;
|
|
201
|
+
if (fs.existsSync(file)) {
|
|
202
|
+
let raw;
|
|
203
|
+
try {
|
|
204
|
+
raw = JSON.parse(fs.readFileSync(file, "utf8"));
|
|
205
|
+
} catch (e) {
|
|
206
|
+
console.error(" WARNING: could not parse " + file + " — skipping enable for " + id + ".");
|
|
207
|
+
process.exit(0);
|
|
208
|
+
}
|
|
209
|
+
if (!Array.isArray(raw)) {
|
|
210
|
+
console.error(" WARNING: " + file + " is not a JSON array — skipping enable for " + id + ".");
|
|
211
|
+
process.exit(0);
|
|
212
|
+
}
|
|
213
|
+
list = raw;
|
|
214
|
+
} else {
|
|
215
|
+
list = [];
|
|
216
|
+
}
|
|
217
|
+
if (list.includes(id)) {
|
|
218
|
+
console.log(" " + id + ": already enabled in " + file + ".");
|
|
219
|
+
process.exit(0);
|
|
220
|
+
}
|
|
221
|
+
list.push(id);
|
|
222
|
+
fs.mkdirSync(dir, { recursive: true });
|
|
223
|
+
const tmp = file + ".tmp-" + process.pid;
|
|
224
|
+
fs.writeFileSync(tmp, JSON.stringify(list, null, 2) + "\n");
|
|
225
|
+
fs.renameSync(tmp, file);
|
|
226
|
+
console.log(" " + id + ": enabled in " + file + ".");
|
|
227
|
+
' "$vault_dir" "$id" || true
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
# ---------------------------------------------------------------------------
|
|
231
|
+
# App install gate
|
|
232
|
+
#
|
|
233
|
+
# Interactive: prompt_yn_sticky handles the ask-once/remember dance itself.
|
|
234
|
+
# Non-interactive: mirror register_optional_mcp's non-interactive branch
|
|
235
|
+
# (install-mcps.sh) exactly — read the stored preference directly via
|
|
236
|
+
# prefs_get, never through a prompt helper (prompt_yn_sticky auto-answers
|
|
237
|
+
# "no" with no tty, which is the wrong default here), and only an explicit
|
|
238
|
+
# stored `false` diverts. `true`, `ask`, and `unset` all proceed with the
|
|
239
|
+
# install, same as register_optional_mcp.
|
|
240
|
+
# ---------------------------------------------------------------------------
|
|
241
|
+
if [ "$INTERACTIVE" = true ]; then
|
|
242
|
+
if prompt_yn_sticky obsidian.installApp --global "Install the Obsidian app (recommended local viewer for wiki/ — https://obsidian.md)? [Y/n]: "; then
|
|
243
|
+
_install_obsidian_app || echo " WARNING: Obsidian app install failed — continuing."
|
|
244
|
+
else
|
|
245
|
+
echo " Skipping Obsidian app install."
|
|
246
|
+
fi
|
|
247
|
+
else
|
|
248
|
+
if [ "$(prefs_get obsidian.installApp --global)" = "false" ]; then
|
|
249
|
+
echo " obsidian.installApp: skipped (remembered decline — change with /bootstrap-config)"
|
|
250
|
+
else
|
|
251
|
+
_install_obsidian_app || echo " WARNING: Obsidian app install failed — continuing."
|
|
252
|
+
fi
|
|
253
|
+
fi
|
|
254
|
+
|
|
255
|
+
# ---------------------------------------------------------------------------
|
|
256
|
+
# Plugin install gate
|
|
257
|
+
#
|
|
258
|
+
# obsidian.plugins is a project-scoped key — the vault root is $PROJECT_DIR,
|
|
259
|
+
# so its prompt_yn_sticky/prefs_get selector is "$PROJECT_DIR" itself (never
|
|
260
|
+
# --global), per the selector-consistency rule documented on prompt_yn_sticky
|
|
261
|
+
# in lib.sh. No $PROJECT_DIR means no vault to install into, so skip outright
|
|
262
|
+
# rather than guessing a location.
|
|
263
|
+
# ---------------------------------------------------------------------------
|
|
264
|
+
if [ -z "$PROJECT_DIR" ]; then
|
|
265
|
+
echo " WARNING: no --project-dir given — skipping Obsidian plugin install."
|
|
266
|
+
else
|
|
267
|
+
install_plugins=false
|
|
268
|
+
if [ "$INTERACTIVE" = true ]; then
|
|
269
|
+
if prompt_yn_sticky obsidian.plugins "$PROJECT_DIR" "Install recommended Obsidian plugins (Dataview, Graph Link Types, Breadcrumbs) into this project's vault config? [Y/n]: "; then
|
|
270
|
+
install_plugins=true
|
|
271
|
+
fi
|
|
272
|
+
else
|
|
273
|
+
# Same non-interactive mirroring as the app-install gate above, applied
|
|
274
|
+
# to the project-scoped key: only a stored `false` skips.
|
|
275
|
+
if [ "$(prefs_get obsidian.plugins "$PROJECT_DIR")" = "false" ]; then
|
|
276
|
+
echo " obsidian.plugins: skipped (remembered decline — change with /bootstrap-config)"
|
|
277
|
+
else
|
|
278
|
+
install_plugins=true
|
|
279
|
+
fi
|
|
280
|
+
fi
|
|
281
|
+
|
|
282
|
+
if [ "$install_plugins" = true ]; then
|
|
283
|
+
for plugin_repo in "$PLUGIN_DATAVIEW" "$PLUGIN_GRAPH_LINK_TYPES" "$PLUGIN_BREADCRUMBS"; do
|
|
284
|
+
plugin_id="$(_install_obsidian_plugin "$PROJECT_DIR" "$plugin_repo")" || plugin_id=""
|
|
285
|
+
if [ -n "$plugin_id" ]; then
|
|
286
|
+
_enable_obsidian_plugin "$PROJECT_DIR" "$plugin_id" || true
|
|
287
|
+
fi
|
|
288
|
+
# Empty $plugin_id means _install_obsidian_plugin already warned
|
|
289
|
+
# internally — just move on to the next plugin.
|
|
290
|
+
done
|
|
291
|
+
else
|
|
292
|
+
echo " Skipping Obsidian plugin install."
|
|
293
|
+
fi
|
|
294
|
+
fi
|
package/lib/scripts/lib.sh
CHANGED
|
@@ -167,6 +167,12 @@ run_project_sync() {
|
|
|
167
167
|
"$script_dir/merge-gitignore.sh" --interactive "$project_dir"
|
|
168
168
|
echo ""
|
|
169
169
|
|
|
170
|
+
echo "Checking Obsidian setup..."
|
|
171
|
+
if ! "$script_dir/install-obsidian.sh" --interactive --project-dir "$project_dir"; then
|
|
172
|
+
echo "Warning: Obsidian install failed — continuing; re-run update to retry." >&2
|
|
173
|
+
fi
|
|
174
|
+
echo ""
|
|
175
|
+
|
|
170
176
|
echo "Building MCP tools guide..."
|
|
171
177
|
installed_mcps="$(detect_installed_mcps "$project_dir")"
|
|
172
178
|
# Unquoted on purpose: word-split the space-separated names into arguments.
|
|
@@ -104,7 +104,7 @@
|
|
|
104
104
|
"scope": "global",
|
|
105
105
|
"consumer": "installer",
|
|
106
106
|
"summary": "Registration scope for the Context7 MCP",
|
|
107
|
-
"detail": "Asked by prompt_scope in lib.sh:
|
|
107
|
+
"detail": "Asked by prompt_scope in lib.sh:393 ('Scope for context7 — [u]ser (default) or [p]roject?'). prompt_scope emits exactly two answers, 'user' and 'project' — it has no local-scope branch, and any reply that does not begin with p or P falls through to user. 'user' registers Context7 once for every project on this machine; 'project' writes the registration into the current project's shareable .mcp.json.",
|
|
108
108
|
"values": "user | project",
|
|
109
109
|
"default": null,
|
|
110
110
|
"askedBy": "lib.sh"
|
|
@@ -118,6 +118,24 @@
|
|
|
118
118
|
"default": null,
|
|
119
119
|
"askedBy": "install-mcps.sh"
|
|
120
120
|
},
|
|
121
|
+
"obsidian.installApp": {
|
|
122
|
+
"scope": "global",
|
|
123
|
+
"consumer": "installer",
|
|
124
|
+
"summary": "Install the Obsidian desktop app via the native package manager",
|
|
125
|
+
"detail": "Asked by install-obsidian.sh when the Obsidian desktop app is not yet installed on this machine. true installs it via the native package manager — brew on macOS, flatpak on Linux — and, per the standard sticky-prompt semantics, keeps offering it again on every subsequent run until it is actually present. false means the installer stops offering it: the prompt is never shown again on this machine until the key is changed or removed via /bootstrap-config. The app itself is machine-wide, not tied to any one project, which is why this key is global scope, matching mcp.playwright's scope choice.",
|
|
126
|
+
"values": "true | false",
|
|
127
|
+
"default": null,
|
|
128
|
+
"askedBy": "install-obsidian.sh"
|
|
129
|
+
},
|
|
130
|
+
"obsidian.plugins": {
|
|
131
|
+
"scope": "project",
|
|
132
|
+
"consumer": "installer",
|
|
133
|
+
"summary": "Install the bundled Obsidian plugin set (Dataview, Graph Link Types, Breadcrumbs)",
|
|
134
|
+
"detail": "Asked by install-obsidian.sh. This is a single bundled prompt covering all three recommended community plugins together — Dataview, Graph Link Types, and Breadcrumbs — rather than one key per plugin, because Dataview is a hard prerequisite for the other two: both Graph Link Types and Breadcrumbs read fields that Dataview indexes, so installing them separately would let a user accept Graph Link Types or Breadcrumbs without Dataview and end up with plugins that silently don't work. true installs and refreshes all three plugin folders into .obsidian/plugins/ and enables them in .obsidian/community-plugins.json on every run. false means the installer stops offering the bundle again until the key is changed or removed via /bootstrap-config. Plugin files live inside this project's own .obsidian/ directory, which is why this key is project scope, matching guides.*'s scope choice.",
|
|
135
|
+
"values": "true | false",
|
|
136
|
+
"default": null,
|
|
137
|
+
"askedBy": "install-obsidian.sh"
|
|
138
|
+
},
|
|
121
139
|
"skills.pruneOrphans": {
|
|
122
140
|
"scope": "global",
|
|
123
141
|
"consumer": "installer",
|
|
@@ -131,7 +149,7 @@
|
|
|
131
149
|
"scope": "either",
|
|
132
150
|
"consumer": "skill",
|
|
133
151
|
"summary": "How /git-commit handles the version bump before committing",
|
|
134
|
-
"detail": "'auto' is today's behavior: the skill picks a bump level and applies it to every version manifest it finds, without confirmation. 'confirm' prints the suggested bump and asks before editing any manifest — 'confirm' IS this key's ask state, so there is deliberately no separate 'ask' value in the grammar. 'never' touches no version file at all
|
|
152
|
+
"detail": "'auto' is today's behavior: the skill picks a bump level and applies it to every version manifest it finds, without confirmation. 'confirm' prints the suggested bump and asks before editing any manifest — 'confirm' IS this key's ask state, so there is deliberately no separate 'ask' value in the grammar. 'never' touches no version file at all. The [patch]/[minor]/[major] commit-subject prefix is written IF AND ONLY IF a version was actually bumped: written under 'auto' and under an approved 'confirm', omitted entirely under 'never' and under a declined 'confirm'. That coupling is the point — release tooling reads the prefix as a claim about what the commit did, so a prefix on a commit that bumped nothing is a false statement the tooling would act on, not a harmless label. This is a choice among three behaviors, not an add/skip gate, so the declines-only rule does not apply — the answer is recorded in all three directions.",
|
|
135
153
|
"values": "auto | confirm | never",
|
|
136
154
|
"default": "auto",
|
|
137
155
|
"askedBy": "install-global.sh"
|
|
@@ -154,13 +172,22 @@
|
|
|
154
172
|
"default": true,
|
|
155
173
|
"askedBy": "install-global.sh"
|
|
156
174
|
},
|
|
157
|
-
"
|
|
175
|
+
"research.autoIngest": {
|
|
158
176
|
"scope": "either",
|
|
159
177
|
"consumer": "skill",
|
|
160
|
-
"summary": "Whether /
|
|
161
|
-
"detail": "
|
|
178
|
+
"summary": "Whether /research automatically wiki-ingests its saved report",
|
|
179
|
+
"detail": "Governs what happens right after Phase 5 writes raw/research/<slug>/index.md — it never runs when that write was suppressed (research.persistToRaw=false, a per-run --no-save, or a declined ask), because there is then no raw/ file to ingest. true immediately follows the full lib/skills/wiki-ingest/SKILL.md procedure against the file just written, non-interactively — Step 2's user checkpoint is skipped because the report was just delivered in this same reply, and the skill proceeds straight through the summary page, entity/concept pages, and the index + log entries. false leaves the wiki untouched and keeps suggesting the manual '/wiki-ingest raw/research/<slug>/index.md' command, which is today's behaviour. 'ask' prompts before ingesting this one report and never writes the answer back to the store — a different mechanism from the per-run override on research.persistToRaw, serving the same 'not this one' need at the ingest step instead of the save step.",
|
|
162
180
|
"values": "true | false | ask",
|
|
163
|
-
"default":
|
|
181
|
+
"default": false,
|
|
182
|
+
"askedBy": "install-global.sh"
|
|
183
|
+
},
|
|
184
|
+
"uatGenerate.promoteTests": {
|
|
185
|
+
"scope": "either",
|
|
186
|
+
"consumer": "skill",
|
|
187
|
+
"summary": "Where /uat-generate writes the unit tests it promotes out of UAT cases",
|
|
188
|
+
"detail": "The question is WHERE promoted tests land, not whether they exist. 'dedicated' is today's behavior: they go in the project's dedicated test directory, resolved by looking at the repo first (an existing test directory) and falling back to the language default — test/ for JS/TS, tests/ for Python, spec/ where that is the local idiom. The directory is detected rather than stored, because this grammar is a closed enumeration of literal tokens and a stored path would be free text. 'sibling' puts each test beside the file under test using the language's own convention (src/parse.ts -> src/parse.test.ts). 'never' writes nothing: the skill still runs its promotability analysis and records the verdict on each UAT case, it just creates no file. An existing test file that already covers the unit is extended in place under every value, and a project's visible layout wins over a stored answer that contradicts it — so this key is a default for new work, not an override of the repo. It affects what lands on disk, not how the UAT itself is judged. Legacy true/false/ask values from the key's earlier grammar are mapped by the skill: true -> dedicated, false -> never, ask -> ask once per run.",
|
|
189
|
+
"values": "sibling | never | dedicated",
|
|
190
|
+
"default": "dedicated",
|
|
164
191
|
"askedBy": "install-global.sh"
|
|
165
192
|
},
|
|
166
193
|
"gitignore.offerSectionUpdates": {
|
|
@@ -22,7 +22,7 @@ Bootstrap remembers your answers to installer and skill prompts in two flat JSON
|
|
|
22
22
|
`argument-hint: [view | edit | reset] [--global | --project]`
|
|
23
23
|
|
|
24
24
|
- A mode word (`view` / `edit` / `reset`) preselects the mode and skips the Step C question. Steps A and B still run, and the Step B2 summary is still printed first — a mode word skips a question, never the state read.
|
|
25
|
-
- `--global` / `--project` preselects the layer for reads and pins the write layer
|
|
25
|
+
- `--global` / `--project` preselects the layer for reads and pins the write layer. A pinned layer that the chosen key's `scope` forbids is refused by the helper itself (BUG-0009), not silently redirected — Step E offers only permitted layers so the refusal is rarely hit in practice.
|
|
26
26
|
- No arguments = the full interactive flow.
|
|
27
27
|
|
|
28
28
|
---
|
|
@@ -106,7 +106,7 @@ Skip this question entirely when a mode word was supplied as an argument — but
|
|
|
106
106
|
5. When the chosen key has `consumer: skill`, print this heavier banner:
|
|
107
107
|
> This is a **skill preference**. Changing it changes what a slash command actually does the next time it runs — not merely whether the installer asks you a question.
|
|
108
108
|
|
|
109
|
-
Name the affected command from the entry's `askedBy` / `summary` — e.g. `gitCommit.versionBump` changes what `/git-commit` does on every commit. The `consumer: skill` population is `gitCommit.versionBump`, `gitCommit.autoPush`, `research.persistToRaw`, `uatGenerate.promoteTests`, and `gitignore.offerSectionUpdates`. Every other key is `consumer: installer` and gets the lighter framing: it only affects whether a setup/update script prompts you.
|
|
109
|
+
Name the affected command from the entry's `askedBy` / `summary` — e.g. `gitCommit.versionBump` changes what `/git-commit` does on every commit. The `consumer: skill` population is `gitCommit.versionBump`, `gitCommit.autoPush`, `research.persistToRaw`, `research.autoIngest`, `uatGenerate.promoteTests`, and `gitignore.offerSectionUpdates`. Every other key is `consumer: installer` and gets the lighter framing: it only affects whether a setup/update script prompts you.
|
|
110
110
|
|
|
111
111
|
## Step E — Choose the value and the layer (edit mode)
|
|
112
112
|
|
|
@@ -118,7 +118,7 @@ Skip this question entirely when a mode word was supplied as an argument — but
|
|
|
118
118
|
- `scope: global` → the global layer only.
|
|
119
119
|
- `scope: either` → ask which, explaining that **project wins over global, per key**.
|
|
120
120
|
|
|
121
|
-
Never offer a layer the key's `scope` makes inert. The helper's `--set`
|
|
121
|
+
Never offer a layer the key's `scope` makes inert. The helper's `--set` itself now refuses a write into a layer the key's `scope` forbids (exit 1, nothing written — BUG-0009) — attempting to write a `global`-scope key into a project file is rejected rather than silently accepted and later filed under "Unrecognized keys" with a never-consulted reason. This step exists so the user is never offered a choice that would hit that refusal, not because the helper depends on it.
|
|
122
122
|
3. If `scope` requires the project layer but no project directory was resolved in Step A, abort that edit with an explanation. Do not fall back to the global layer.
|
|
123
123
|
4. Confirm with one final `AskUserQuestion` (`Yes, apply` / `No, cancel`) showing the exact command about to run:
|
|
124
124
|
```
|
|
@@ -72,12 +72,28 @@ Print the summary. What happens next is decided by `gitCommit.versionBump` from
|
|
|
72
72
|
|
|
73
73
|
Its grammar is `auto | confirm | never` — there is deliberately **no `ask` value**, because `confirm` *is* this key's ask state. Do not look for one.
|
|
74
74
|
|
|
75
|
-
| Value |
|
|
76
|
-
|
|
77
|
-
| `auto` | Today's behavior. Detect every manifest and apply the bump to all of them, no confirmation. |
|
|
78
|
-
| `confirm`
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
75
|
+
| Value | Manifests | Subject prefix |
|
|
76
|
+
|-------|-----------|----------------|
|
|
77
|
+
| `auto` | Today's behavior. Detect every manifest and apply the bump to all of them, no confirmation. | **written** |
|
|
78
|
+
| `confirm` — approved | Bump exactly as `auto` does. | **written** |
|
|
79
|
+
| `confirm` — declined | Edit no manifest. | **omitted** |
|
|
80
|
+
| `never` | Touch **no** version file at all. Skip straight to Step 5. | **omitted** |
|
|
81
|
+
| `unset` | Behave exactly as `auto` — that is today's behavior and an unanswered key must never change it. | **written** |
|
|
82
|
+
|
|
83
|
+
`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.
|
|
84
|
+
|
|
85
|
+
### ⛔ The prefix and the bump travel together
|
|
86
|
+
|
|
87
|
+
**Write `[patch]`/`[minor]`/`[major]` if and only if a version was actually bumped in this run.** The prefix is a claim about what the commit did, and release tooling reads it as one. A `[minor]` prefix on a commit that bumped nothing is not a harmless label — it is a false statement that tooling will act on, tagging or publishing a release that has no version change behind it. An unprefixed subject is merely uninformative; a lying prefix is actively wrong, and it is worse the more automation is downstream.
|
|
88
|
+
|
|
89
|
+
So when no bump happens, commit a **bare subject with no bracket prefix at all**. Do not substitute `[none]`, `[skip]`, `[no-bump]`, or any other placeholder — an unrecognized token is its own kind of noise, and tooling that pattern-matches the three real values will ignore a bare subject correctly.
|
|
90
|
+
|
|
91
|
+
The one case where nothing was bumped for a reason unrelated to this preference — a repo with **no manifest at all** (Detection below finds nothing) — follows the same rule: nothing was bumped, so no prefix.
|
|
92
|
+
|
|
93
|
+
Report lines, each at most once per run:
|
|
94
|
+
- `never` → `Version files untouched and no subject prefix written (gitCommit.versionBump=never). Change with /bootstrap-config.`
|
|
95
|
+
- `confirm`-declined → `Bump declined — no manifest edited and no subject prefix written.`
|
|
96
|
+
- `unset` → `gitCommit.versionBump is unanswered — /git-commit bumps every manifest by default. Set it with: node ~/.claude/bootstrap-prefs.js --set gitCommit.versionBump --value auto --global` (or `confirm` / `never`).
|
|
81
97
|
|
|
82
98
|
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.
|
|
83
99
|
|
|
@@ -128,7 +144,7 @@ Edit **every file** that contains a version using the Edit tool — do not stop
|
|
|
128
144
|
- **ALWAYS use the `git-commit` bash alias.** Never use `git add` or `git commit` directly.
|
|
129
145
|
- Always commit ALL files unless they are in `.gitignore`
|
|
130
146
|
- Consider an appropriate commit message, let's call it `$message`
|
|
131
|
-
- Prefix the subject with the bump type in brackets
|
|
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
|
|
132
148
|
- Run: `git-commit "$message"`
|
|
133
149
|
|
|
134
150
|
### ⛔ No agent attribution — the user is the sole author
|
|
@@ -143,13 +159,14 @@ The commit must be attributed to the user's git identity **only**. Never add the
|
|
|
143
159
|
|
|
144
160
|
The commit message MUST be a **single-line, single-quoted-argument string**. Subject only, no body. This is a hard rule because anything else triggers a Bash approval prompt and slows you down.
|
|
145
161
|
|
|
146
|
-
**Required form
|
|
162
|
+
**Required form** — bumped, and not bumped:
|
|
147
163
|
|
|
148
164
|
```bash
|
|
149
165
|
git-commit "[patch] Single-line subject describing the change"
|
|
166
|
+
git-commit "Single-line subject describing the change"
|
|
150
167
|
```
|
|
151
168
|
|
|
152
|
-
That's it. One pair of double quotes. One line. One argument.
|
|
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.
|
|
153
170
|
|
|
154
171
|
**❌ Forbidden — every one of these patterns triggers an approval prompt:**
|
|
155
172
|
|
|
@@ -178,9 +195,13 @@ git-commit "subject" "-m" "body"
|
|
|
178
195
|
|
|
179
196
|
# WRONG — piping or chaining
|
|
180
197
|
echo "subject" | git-commit -F -
|
|
198
|
+
|
|
199
|
+
# WRONG — a placeholder standing in for a bump that did not happen
|
|
200
|
+
git-commit "[none] Fix the login redirect"
|
|
201
|
+
git-commit "[no-bump] Fix the login redirect"
|
|
181
202
|
```
|
|
182
203
|
|
|
183
|
-
**✅ Correct —
|
|
204
|
+
**✅ Correct — a version was bumped:**
|
|
184
205
|
|
|
185
206
|
```bash
|
|
186
207
|
git-commit "[patch] Fix UAT verdict logic for edge-case test skips"
|
|
@@ -188,14 +209,23 @@ git-commit "[minor] Add /task-audit skill with dependency graph and wave output"
|
|
|
188
209
|
git-commit "[major] Rename all skills to noun-first convention, drop legacy verb-first aliases"
|
|
189
210
|
```
|
|
190
211
|
|
|
212
|
+
**✅ Correct — no version was bumped** (`never`, `confirm`-declined, or no manifest in the repo):
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
git-commit "Fix UAT verdict logic for edge-case test skips"
|
|
216
|
+
git-commit "Add /task-audit skill with dependency graph and wave output"
|
|
217
|
+
```
|
|
218
|
+
|
|
191
219
|
### Writing a good single-line subject
|
|
192
220
|
|
|
193
221
|
If the change feels too complex to summarize in one line, **make the subject more descriptive** — do not reach for a multi-line body. Aim for ~70–100 characters but go longer if it adds real information. Lead with the *what* and the *why* on the same line, separated by a colon when helpful:
|
|
194
222
|
|
|
195
223
|
- ✅ `[minor] Require research for every test type in /uat-generate with checkpoint gate`
|
|
196
224
|
- ✅ `[patch] Allow standard tools for markdown editing; ban bash exploration commands`
|
|
197
|
-
-
|
|
225
|
+
- ✅ `Allow standard tools for markdown editing; ban bash exploration commands` (no bump this run — the subject still carries its weight)
|
|
226
|
+
- ❌ `Update commands` (too vague — and vague is vague with or without a prefix)
|
|
198
227
|
- ❌ `[patch] Fix bug` (too vague)
|
|
228
|
+
- ❌ `[patch] Fix the login redirect` **when Step 4 bumped nothing** (the prefix is false)
|
|
199
229
|
|
|
200
230
|
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.
|
|
201
231
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: research
|
|
3
|
-
description: Deep research on a topic using codebase analysis, library docs, and web search — by default also writes the report plus its primary sources to raw/research/<slug>/ (preference-gated by research.persistToRaw; findings are always delivered in the reply)
|
|
3
|
+
description: Deep research on a topic using codebase analysis, library docs, and web search — by default also writes the report plus its primary sources to raw/research/<slug>/ (preference-gated by research.persistToRaw; findings are always delivered in the reply), and can auto-fold a saved report into wiki/ (preference-gated by research.autoIngest)
|
|
4
4
|
category: researching
|
|
5
5
|
model: claude-sonnet-5
|
|
6
6
|
effort: high
|
|
@@ -242,18 +242,38 @@ Rules for this phase:
|
|
|
242
242
|
|
|
243
243
|
---
|
|
244
244
|
|
|
245
|
+
## Phase 5b: Auto-Ingest Gate (only when Phase 5 actually wrote files)
|
|
246
|
+
|
|
247
|
+
This gate governs whether the report just written under `raw/research/<slug>/` is immediately folded into `wiki/`, instead of leaving `/wiki-ingest raw/research/<slug>/index.md` as a manual follow-up. **Skip this phase entirely when Phase 5 wrote nothing** — a suppressed save (stored `false`, a per-run `--no-save`/`--no-persist`, or a declined `ask`) leaves no `raw/` file to ingest.
|
|
248
|
+
|
|
249
|
+
Read the preference once, after Phase 5 completes:
|
|
250
|
+
|
|
251
|
+
```bash
|
|
252
|
+
node ~/.claude/bootstrap-prefs.js --get research.autoIngest --project . 2>/dev/null || echo unset
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
| Value | Behaviour |
|
|
256
|
+
|-------|-----------|
|
|
257
|
+
| `true` | Immediately follow the full procedure in `lib/skills/wiki-ingest/SKILL.md` against the file just written (`raw/research/<slug>/index.md`), non-interactively — skip Step 2's user-checkpoint pause (the report was just delivered in this same reply, so there is nothing new to confirm before proceeding) and go straight through writing/updating the summary page, entity/concept pages, and the `wiki/index.md` + `wiki/log.md` entries. |
|
|
258
|
+
| `false` | Do nothing further. Keep suggesting `/wiki-ingest raw/research/<slug>/index.md` as a manual next step, per Phase 6. |
|
|
259
|
+
| `ask` | Before ingesting, ask the user (AskUserQuestion) whether to fold this report into the wiki now. Honour the answer for **this run only** — never write it back to the store. |
|
|
260
|
+
| `unset` | Do nothing further (today's behaviour — the schema default is `false`), and add one line: "research.autoIngest is unanswered — /research does not auto-ingest by default. Set it with: node ~/.claude/bootstrap-prefs.js --set research.autoIngest --value <true\|false\|ask> --global" |
|
|
261
|
+
|
|
262
|
+
---
|
|
263
|
+
|
|
245
264
|
## Phase 6: Confirm & Suggest Next Steps
|
|
246
265
|
|
|
247
266
|
**If the files were written**, tell the user:
|
|
248
267
|
- The paths written (`raw/research/<slug>/index.md` and `raw/research/<slug>/sources.md`)
|
|
249
268
|
- A 2–4 bullet summary of the recommendation
|
|
250
|
-
-
|
|
269
|
+
- **If Phase 5b ingested the report**: say so, and name the wiki pages it created or updated — do not also suggest `/wiki-ingest`, it already ran.
|
|
270
|
+
- **Otherwise**: that the report is now a `raw/` ground-truth source: **"Run `/wiki-ingest raw/research/<slug>/index.md` to synthesize this research into the knowledge base."**
|
|
251
271
|
- Any follow-on `/task-add` or `/decision-create` suggested by the findings
|
|
252
272
|
|
|
253
273
|
**If nothing was persisted** (stored `false`, a per-run `--no-save`/`--no-persist` override, or a declined `ask`), tell the user:
|
|
254
274
|
- That no files were written, and which of the three reasons applies
|
|
255
275
|
- The same 2–4 bullet summary of the recommendation
|
|
256
|
-
- Skip the `/wiki-ingest` suggestion entirely — there is no `raw/` file to ingest
|
|
276
|
+
- Skip the `/wiki-ingest` suggestion entirely — there is no `raw/` file to ingest, and Phase 5b never ran either
|
|
257
277
|
- Any follow-on `/task-add` or `/decision-create` suggested by the findings
|
|
258
278
|
|
|
259
279
|
---
|
|
@@ -279,3 +299,4 @@ Rules for this phase:
|
|
|
279
299
|
7) **Never overwrite `raw/` files**: if a target already exists, write `<name>-2.md` / `-3.md` instead, carrying only non-redundant new/changed data with a cross-reference to the prior file
|
|
280
300
|
8) **No fabricated sources**: every row in `sources.md` is a source you actually consulted; mark unsupported claims as inferences rather than inventing citations
|
|
281
301
|
9) **`raw/research/` is the only `raw/` path this skill may write to** — never modify or delete anything elsewhere under `raw/`
|
|
302
|
+
10) **Only run Phase 5b when Phase 5 actually wrote files** — the `research.autoIngest` gate is meaningless (and must not run) against a suppressed save; when it does run with `true`, it hands off to `lib/skills/wiki-ingest/SKILL.md`'s own rules (atomic pages, contradiction callouts, index + log updates), which apply exactly as they do for a manually invoked `/wiki-ingest`
|
|
@@ -119,6 +119,8 @@ Populate `depends_on`, `blocks`, and `parallel_safe_with` from Step 5 as lists o
|
|
|
119
119
|
# TASK-NNN — Task Title
|
|
120
120
|
|
|
121
121
|
implements::[[DEC-NNNN#DM]] ← only when a decision reference was provided
|
|
122
|
+
depends_on::[[TASK-NNN]] ← one line per dependency from Step 5; omit entirely if none
|
|
123
|
+
blocks::[[TASK-NNN]] ← one line per blocked task from Step 5; omit entirely if none
|
|
122
124
|
|
|
123
125
|
## Objective
|
|
124
126
|
|
|
@@ -146,6 +148,8 @@ Agent type annotations: valid types are `general-purpose`, `Explore`, `Plan`.
|
|
|
146
148
|
|
|
147
149
|
**Decision link** (only when Step 2 found an accepted decision reference): Insert `implements::[[DEC-NNNN#DM]]` as a typed link on the line immediately after the H1, before `## Objective`.
|
|
148
150
|
|
|
151
|
+
**Dependency links** (from the Step 5 data, no re-derivation needed): insert one `depends_on::[[TASK-NNN]]` line per dependency and one `blocks::[[TASK-NNN]]` line per blocked task, in the same position — immediately after `implements::` when it's present, or immediately after the H1 when it isn't. *Aside: these typed-link lines are additive to the existing `> **Depends on**:`/`> **Blocks**:` blockquote format, not a replacement, and creating them here does not backfill any pre-existing task file.*
|
|
152
|
+
|
|
149
153
|
### Step 9: Update the family index
|
|
150
154
|
|
|
151
155
|
Append to `wiki/work/tasks/index.md`:
|
|
@@ -84,6 +84,8 @@ In the same file read, locate the dependency blockquote appearing **immediately
|
|
|
84
84
|
- Links follow the pattern `[NNN-slug](NNN-slug.md)` — extract the NNN-slug identifier from each link.
|
|
85
85
|
- A task with no dependency block at all is treated as having `Depends on: none`, `Blocks: none`, `Parallel-safe with: none`.
|
|
86
86
|
|
|
87
|
+
Going forward, task files should also carry one `depends_on::[[TASK-NNN]]` line per dependency and one `blocks::[[TASK-NNN]]` line per blocked task, directly below the blockquote — these are additive typed links for Obsidian/Breadcrumbs graph visualization. `/task-audit`'s own parser continues to read only the blockquote above, unchanged.
|
|
88
|
+
|
|
87
89
|
### 2f. Build the Node Record
|
|
88
90
|
|
|
89
91
|
For each task (skipping any moved to completed in 2d), produce a record:
|
|
@@ -89,7 +89,7 @@ Do not proceed to Step 3 until you can answer yes to all:
|
|
|
89
89
|
|
|
90
90
|
##### Preference gate
|
|
91
91
|
|
|
92
|
-
This gate governs **only
|
|
92
|
+
This gate governs **only where unit test files are written** (and whether they are written at all). It never affects the UAT file itself or how UAT verdicts are judged.
|
|
93
93
|
|
|
94
94
|
Read the preference **once per invocation** (not per case), before Step 2.5 does any other work:
|
|
95
95
|
|
|
@@ -97,12 +97,25 @@ Read the preference **once per invocation** (not per case), before Step 2.5 does
|
|
|
97
97
|
node ~/.claude/bootstrap-prefs.js --get uatGenerate.promoteTests --project . 2>/dev/null || echo unset
|
|
98
98
|
```
|
|
99
99
|
|
|
100
|
+
The key answers **where** promoted tests go, not whether they exist. Its grammar is the closed enumeration `sibling | never | dedicated`.
|
|
101
|
+
|
|
100
102
|
| Value | Behaviour |
|
|
101
103
|
|-------|-----------|
|
|
102
|
-
| `
|
|
103
|
-
| `
|
|
104
|
-
| `
|
|
105
|
-
| `unset` |
|
|
104
|
+
| `dedicated` | Write promoted tests into the project's dedicated test directory, **resolved from the repo** — an existing test directory if there is one, else the language default (`test/` for JS/TS, `tests/` for Python, `spec/` where that is the local idiom). The directory is detected, never stored: `values` is a closed list of literal tokens, and a stored path would be free text. |
|
|
105
|
+
| `sibling` | Write each test **beside the file under test**, using the language's own convention — `src/parse.ts` → `src/parse.test.ts`, `src/parse.js` → `src/parse.test.js`, `parse.py` → `test_parse.py`, `parse.go` → `parse_test.go`. Never invent a suffix the language's runner does not already discover. |
|
|
106
|
+
| `never` | Create or update **nothing** under any test path. Still run the promotability *analysis* and still record it per case, as `- **Repeatable Unit Test**: Skipped by preference (uatGenerate.promoteTests=never)`. Say once in the completion report (Step 7): "No test files were written (uatGenerate.promoteTests=never). Change with /bootstrap-config." |
|
|
107
|
+
| `unset` | Behave as `dedicated` — today's behaviour. Note once: "uatGenerate.promoteTests is unanswered — /uat-generate writes promoted tests to a dedicated folder by default. Set it with: node ~/.claude/bootstrap-prefs.js --set uatGenerate.promoteTests --value <sibling\|never\|dedicated> --global" |
|
|
108
|
+
| `true` / `false` / `ask` | **Legacy values** from the key's earlier true/false grammar. Map them and carry on — do not error: `true` → `dedicated`, `false` → `never`, `ask` → ask the user once per invocation (AskUserQuestion) which of the three locations to use, honouring the answer for this run only and never writing it back. Mention once that the stored value is from an older grammar and `/bootstrap-config` can update it. |
|
|
109
|
+
|
|
110
|
+
### The project's layout outranks the stored answer
|
|
111
|
+
|
|
112
|
+
**A stored location is a default for new work, not an instruction to fight the repo.** Before writing anything, look at where tests already live:
|
|
113
|
+
|
|
114
|
+
- An existing test file that already covers the unit under test is **extended in place** under every value except `never`. That is neither "dedicated" nor "sibling" — it is the local pattern, and it always wins.
|
|
115
|
+
- If the project visibly uses one layout and the stored preference says the other (preference says `sibling`, the repo has a populated `test/` with no siblings anywhere), **follow the repo** and say so once in Step 7: "Followed the project's existing `test/` layout over uatGenerate.promoteTests=sibling. Set it per-project with /bootstrap-config." Scattering siblings through a repo that centralises its suite makes the suite worse, and this key is `scope: either` precisely so a project can hold its own answer.
|
|
116
|
+
- Only when the project has no discernible convention does the stored value decide on its own.
|
|
117
|
+
|
|
118
|
+
`never` is the one value the repo cannot overrule — "write no test files" is a directive, not a layout hint.
|
|
106
119
|
|
|
107
120
|
For every planned UAT case, decide whether any part of it can be captured as a repeatable unit test with low setup cost.
|
|
108
121
|
|
|
@@ -117,13 +130,13 @@ A UAT case is **not** unit-test promotable when it primarily verifies:
|
|
|
117
130
|
- Real HTTP service wiring, authentication middleware, deployment behavior, shell environment setup, database migrations, or file permissions.
|
|
118
131
|
- Third-party service behavior or integration between multiple independently deployed systems.
|
|
119
132
|
|
|
120
|
-
Before writing the UAT file, inspect the existing test layout and runner:
|
|
121
|
-
- Find nearby test files for the changed code.
|
|
133
|
+
Before writing the UAT file, inspect the existing test layout and runner — this is also what resolves the location gate above:
|
|
134
|
+
- Find nearby test files for the changed code, and note **where** the project keeps them (a dedicated directory, siblings, or both).
|
|
122
135
|
- Identify the test framework, naming convention, fixtures, mocks, and command used by the repo.
|
|
123
|
-
- Prefer adding focused assertions to an existing nearby test file when that is the local pattern
|
|
124
|
-
- Otherwise create the smallest conventional new test file
|
|
136
|
+
- Prefer adding focused assertions to an existing nearby test file when that is the local pattern — this wins over the stored preference in every case except `never`.
|
|
137
|
+
- Otherwise create the smallest conventional new test file **at the location the gate resolved to**, following the repo's visible layout when it contradicts the stored value.
|
|
125
138
|
|
|
126
|
-
If a case is promotable **and the
|
|
139
|
+
If a case is promotable **and the gate resolved to a location** (anything but `never`), you **must** create or update the unit test file at that location. Do not merely list it as a recommendation. If you cannot create it because the test framework is absent or the harness would require new infrastructure, record that as a gap with the concrete blocker. When the gate resolved to `never`, do the analysis and record `Skipped by preference` — write no test file anywhere.
|
|
127
140
|
|
|
128
141
|
### Step 3: Generate UAT test cases
|
|
129
142
|
|
|
@@ -210,7 +223,7 @@ implements::[[TASK-NNN]]
|
|
|
210
223
|
- Add `- **Repeatable Unit Test**: Created: \`path/to/test-file\`` when you created or updated a unit test for the behavior.
|
|
211
224
|
- Add `- **Repeatable Unit Test**: Not applicable: <short reason>` when the case cannot reasonably become a unit test.
|
|
212
225
|
- Add `- **Repeatable Unit Test**: Blocked: <short reason>` only when it was promotable in principle but the repo lacks the needed test harness or fixtures.
|
|
213
|
-
- Add `- **Repeatable Unit Test**: Skipped by preference (uatGenerate.promoteTests=
|
|
226
|
+
- Add `- **Repeatable Unit Test**: Skipped by preference (uatGenerate.promoteTests=never)` when the Step 2.5 preference gate suppressed promotion for this run. Record the promotability analysis as usual; only the file write is skipped.
|
|
214
227
|
|
|
215
228
|
**Unit test command** (required whenever, and only when, the line above says `Created:`):
|
|
216
229
|
- Add `- **Unit Test Command**: \`<cmd>\`` on the next line, holding the **file-scoped** command that runs exactly that test file — e.g. `node --test test/foo.test.js`, `npx vitest run test/foo.test.ts`, `pytest tests/test_foo.py`, `go test ./pkg/foo/`.
|
|
@@ -228,7 +241,7 @@ Auth-Role: user
|
|
|
228
241
|
|
|
229
242
|
### Step 4: Write repeatable unit tests, the UAT file, and cross-reference
|
|
230
243
|
|
|
231
|
-
1. **If the Step 2.5
|
|
244
|
+
1. **If the Step 2.5 gate resolved to a location**, create or update the actual unit test file for each promotable case from Step 2.5 **at that location**, before writing the UAT file. If it resolved to `never`, skip this step entirely — write no test file anywhere — and record each promotable case as `Skipped by preference` instead.
|
|
232
245
|
- Use existing test framework conventions and nearby examples.
|
|
233
246
|
- Keep the test focused on the behavior from the UAT case.
|
|
234
247
|
- Do not add broad snapshots or duplicate end-to-end checks as unit tests.
|
|
@@ -236,7 +249,7 @@ Auth-Role: user
|
|
|
236
249
|
- If editing code test files, use Serena editing tools.
|
|
237
250
|
- If creating new config/markdown/test files where Serena is unavailable, use the appropriate project-approved edit/write tool; never shell redirection.
|
|
238
251
|
|
|
239
|
-
2. Include the created test path in the corresponding UAT case's `Repeatable Unit Test` metadata, plus the verified file-scoped `Unit Test Command` — or `Skipped by preference (uatGenerate.promoteTests=
|
|
252
|
+
2. Include the created test path in the corresponding UAT case's `Repeatable Unit Test` metadata, plus the verified file-scoped `Unit Test Command` — or `Skipped by preference (uatGenerate.promoteTests=never)` when the gate suppressed promotion.
|
|
240
253
|
|
|
241
254
|
3. Write `wiki/work/uat/UAT-NNN-slug.md` using the `Write` tool.
|
|
242
255
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@codewizard-dt/bootstrap",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.20.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": {
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# Dataview Queries for the Wiki
|
|
2
|
+
|
|
3
|
+
> An optional, local-only guide for readers who open this wiki in Obsidian and want live, exploratory views over `wiki/` — on top of, not instead of, the hand/LLM-maintained index files.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. What this is (and isn't)
|
|
8
|
+
|
|
9
|
+
[Dataview](https://github.com/blacksmithgu/obsidian-dataview) is a community plugin for Obsidian that lets you write query blocks — `TABLE`, `LIST`, `TASK`, `CALENDAR` — over your vault's markdown files and their frontmatter, and see live, auto-updating results rendered inline in any note.
|
|
10
|
+
|
|
11
|
+
It is **optional**. Nothing in this wiki's schema, tooling, or `/wiki-*` commands depends on Dataview being installed. It is a personal, local convenience for readers who happen to use Obsidian as their markdown viewer — not a wiki dependency, not something CI checks, and not something every contributor needs.
|
|
12
|
+
|
|
13
|
+
**Install it** one of two ways:
|
|
14
|
+
|
|
15
|
+
- Once [`TASK-053`](../../wiki/work/tasks/) lands, run `lib/scripts/install-obsidian.sh` to set up Obsidian with the recommended plugin set (including Dataview) in one step.
|
|
16
|
+
- Or install it manually: open Obsidian → Settings → Community plugins → Browse → search "Dataview" → Install → Enable.
|
|
17
|
+
|
|
18
|
+
Once enabled, paste any of the query blocks below into a scratch note inside your vault (they do not need to live in a committed file) and Dataview will render a live table or list beneath the block, kept in sync as the underlying `wiki/` files change.
|
|
19
|
+
|
|
20
|
+
**Important caveat, repeated at every example below:** these queries are illustrative, exploratory views for your own personal use in Obsidian. They are **not** a replacement for this repo's committed `index.md` files. Per [`wiki/conventions.md`](../../wiki/conventions.md)'s Maps-of-Content convention, those indexes stay flat, hand/LLM-maintained bullet lists — the canonical, git-versioned source of truth that every contributor can read without Obsidian or any plugin installed. Dataview queries are a local lens on top of that canonical data, not a substitute for it.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## 2. Example queries
|
|
25
|
+
|
|
26
|
+
### 2.1 Tasks by status
|
|
27
|
+
|
|
28
|
+
A live table of every task file under `wiki/work/tasks/`, grouped by its `status` frontmatter field — useful for eyeballing what's `todo`, `in-progress`, or `done` without opening `wiki/work/tasks/index.md`.
|
|
29
|
+
|
|
30
|
+
```dataview
|
|
31
|
+
TABLE status
|
|
32
|
+
FROM "wiki/work/tasks"
|
|
33
|
+
SORT status
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
*Illustrative only — this is a personal, exploratory view. The committed source of truth for active tasks remains [`wiki/work/tasks/index.md`](../../wiki/work/tasks/index.md), maintained by hand/LLM per the wiki's Maps-of-Content convention.*
|
|
37
|
+
|
|
38
|
+
### 2.2 Pages with a `contradicts::` link
|
|
39
|
+
|
|
40
|
+
A quick scan for any page that has flagged a contradiction with another page — a useful companion to `/wiki-lint`, which formally audits for these. This matches on the literal `contradicts::` typed-link text appearing anywhere in a page's body (see [`wiki/conventions.md`](../../wiki/conventions.md) for the typed-link convention, `rel::[[target]]`).
|
|
41
|
+
|
|
42
|
+
```dataview
|
|
43
|
+
LIST
|
|
44
|
+
FROM "wiki"
|
|
45
|
+
WHERE contains(file.text, "contradicts::")
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
*Illustrative only — a simple text-containment scan, not a substitute for `/wiki-lint`'s structured contradiction audit or the `> **Contradiction:**` callouts it produces. Treat this as a "where should I look" pointer, not a verdict.*
|
|
49
|
+
|
|
50
|
+
### 2.3 Tools by tag
|
|
51
|
+
|
|
52
|
+
A table of every tool entity page under `wiki/knowledge/entities/tools/`, alongside its `tags` frontmatter field, sorted by filename — handy for spotting which tools share a tag (e.g. "search", "mcp", "deferred") at a glance.
|
|
53
|
+
|
|
54
|
+
```dataview
|
|
55
|
+
TABLE tags
|
|
56
|
+
FROM "wiki/knowledge/entities/tools"
|
|
57
|
+
SORT file.name
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
*Illustrative only — a personal cross-cut by tag. The canonical listing of tool entities is whatever links into them from [`wiki/index.md`](../../wiki/index.md) and the concept/source pages that reference them; this query does not replace that link network.*
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## 3. Why these stay out of the committed wiki
|
|
65
|
+
|
|
66
|
+
Dataview query blocks only render inside Obsidian with the plugin enabled — a plain markdown viewer, GitHub's file preview, or a teammate without the plugin would see the raw ` ```dataview ` fence and nothing else. Committing them into `index.md` files would silently break the wiki for every non-Obsidian reader. Keep queries like these in your own local scratch notes, and let the committed `index.md` files do the job of being readable by everyone, everywhere, with no plugin required.
|