Add missing scripts referenced in the guide (#11)#17
Conversation
The guide referenced scripts under scripts/ (vault-graph tools, ralph.sh, fan-out.sh) but only included their source inline in the Markdown. Extract the fully-inline scripts into runnable files, add a scripts/README.md index, and link the committed files from the relevant parts. Scripts whose source lives outside this repo (memory-bridge, lightrag-watcher, qwen_embed_server) are documented in scripts/README.md rather than fabricated.
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| if (!claim && !body) { | ||
| console.log('Usage: node auto-capture.mjs --claim "insight" --body "details..."'); | ||
| process.exit(1); | ||
| } | ||
| const filename = toClaimName(claim); |
There was a problem hiding this comment.
🔴 toClaimName generates hidden .md file when claim is empty
When --body is provided without --claim, the guard at auto-capture.mjs:85 (!claim && !body) passes because body is truthy while claim is ''. Then toClaimName('') at line 89 runs all its replacements on an empty string, which all produce '', and appends .md — creating a Unix hidden file named .md in the inbox. This file won't appear in normal ls listings, won't be found by subsequent process-inbox.mjs (which filters .endsWith('.md') but .md starts with a dot), and silently loses the user's capture.
| if (!claim && !body) { | |
| console.log('Usage: node auto-capture.mjs --claim "insight" --body "details..."'); | |
| process.exit(1); | |
| } | |
| const filename = toClaimName(claim); | |
| if (!claim && !body) { | |
| console.log('Usage: node auto-capture.mjs --claim "insight" --body "details..."'); | |
| process.exit(1); | |
| } | |
| if (!claim) claim = body.split('\n')[0] || 'untitled-capture'; | |
| const filename = toClaimName(claim); |
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
Confirmed real bug. Note this is pre-existing — the script was copied verbatim out of Part 9's code block, so the same defect lives in the guide prose too. Since this PR is purely "commit the inline scripts as files," I left the logic untouched to keep the file and the Part 9 block identical. Happy to fix it in a follow-up (or here) — but the fix should land in both scripts/vault-graph/auto-capture.mjs and the Part 9 code block so they don't drift. The suggested if (!claim) claim = body.split('\n')[0] || 'untitled-capture'; guard is the right shape. Deferring to the maintainer on whether to bundle that into this PR.
| const insertPoint = content.indexOf('\n', idx) + 1; | ||
| content = content.substring(0, insertPoint) | ||
| + `\n- [ ] New capture linked: [[${linkName}]]\n` | ||
| + content.substring(insertPoint); |
There was a problem hiding this comment.
🔴 updateMOCs corrupts MOC file when ## Agent Notes has no trailing newline
If the ## Agent Notes heading is the last line of a MOC file (no trailing newline), content.indexOf('\n', idx) at auto-capture.mjs:65 returns -1. Adding 1 gives insertPoint = 0, so content.substring(0, 0) is the empty string. The result is the new link line prepended to the beginning of the file, with the entire original content appended after it — corrupting the MOC structure.
| const insertPoint = content.indexOf('\n', idx) + 1; | |
| content = content.substring(0, insertPoint) | |
| + `\n- [ ] New capture linked: [[${linkName}]]\n` | |
| + content.substring(insertPoint); | |
| const nlIdx = content.indexOf('\n', idx); | |
| const insertPoint = nlIdx !== -1 ? nlIdx + 1 : content.length; | |
| content = content.substring(0, insertPoint) | |
| + `\n- [ ] New capture linked: [[${linkName}]]\n` | |
| + content.substring(insertPoint); |
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
Same situation as the other finding — real bug, but pre-existing and copied verbatim from Part 9, so I kept the file identical to the guide block in this "extract scripts to files" PR. The suggested guard (const nlIdx = content.indexOf('\n', idx); const insertPoint = nlIdx !== -1 ? nlIdx + 1 : content.length;) is correct. If you want it fixed, I'll patch both auto-capture.mjs and the Part 9 code block together so they stay in sync.
2 participants
Summary
Closes #11. The guide repeatedly references scripts under
scripts/(the Part 9 vault-graph tools, the Part 30 Ralph loop, the Part 15 worktree spawner) and even tells readers to "save the scripts from this repo" / "seescripts/vault-graph/for the complete tools" — but thescripts/directory didn't exist; the source only lived inline in the Markdown. This extracts the fully-inline scripts into runnable files, adds ascripts/README.mdindex, and links the committed files from the relevant parts.Added (extracted verbatim from the part code blocks):
scripts/vault-graph/{graph-indexer,graph-search,auto-capture,process-inbox,update-mocs}.mjs(Part 9)scripts/ralph.sh(Part 30)scripts/fan-out.sh(Part 15)scripts/README.md— index + usage, plus a "referenced elsewhere" table for the scripts whose source is intentionally not in this repo.All five
.mjstools were run end-to-end againstexamples/vault/(index → search → update-mocs → auto-capture → process-inbox) and the.shwrappers passbash -n.Type of change
Review checklist
markdownlint-cli2andlychee --offlinelocally (CI will also run these)Notes / flagged items
scripts/memory-bridge/{memory-query,preflight-context}.js(Part 13) — Part 13's install step doesgit clone https://github.com/OnlyTerp/memory-bridge.git, but that repo currently 404s. I left the prose alone and instead documented the script's status inscripts/README.md. You may want to either publishOnlyTerp/memory-bridgeor fix that install instruction.lightrag-watcher.py(Part 21) andscripts/qwen_embed_server_v3.py(Part 10) — only config snippets / "lives in your local install" are in the guide, so these are documented as external inscripts/README.mdrather than reproduced.auto-capture.mjs(vault filer) and the Part 11hooks/auto-capture/handler.ts(transcript extractor) are different things;scripts/README.mdcalls this out to avoid confusion.scripts/(markdownlint/lychee only touch**/*.md), so the new code won't affect the existing checks.Link to Devin session: https://app.devin.ai/sessions/21e86e63e6ed4a7cb88868ac2243d9ef
Requested by: @OnlyTerp