fix(memory-ingest): switch writer to `gbrain put`, retire legacy `put_page` by AZ-1224 · Pull Request #1341 · garrytan/gstack

AZ-1224 · 2026-05-06T16:17:45Z

Summary

bin/gstack-memory-ingest.ts calls the legacy flag-based gbrain put_page --slug X --title Y --type Z --tags T form. gbrain v0.27 retired it for the positional put <slug> (content via stdin, YAML frontmatter for metadata). Against any current gbrain, every page errors [put-error] ... Unknown command: put_page and bulk ingest produces 0 successful writes.

This PR:

Rewrites gbrainPutPage to invoke gbrain put <slug>, injecting title/type/tags as YAML frontmatter when the page body does not already start with one. The transcript builder already prepends frontmatter; the writer-side injection only fires for raw artifact pages.
Bumps gbrainAvailable() to probe gbrain --help for the put subcommand. If a future gbrain renames or removes it, the script fails fast with one clean error rather than N copies of "Unknown command: ...".
Adds two regression tests in test/gstack-memory-ingest.test.ts that stand up a fake gbrain shim on PATH:
1. Writer hits gbrain put <slug> with stdin body + frontmatter and never invokes put_page.
2. Pointing the writer at a legacy-only shim surfaces a single missing-put error from the availability probe.

Scope is intentionally tight: one function rewrite, one availability probe, two tests. No refactor of the writer abstraction.

Repro (before the fix)

# With gbrain v0.27.0+ on PATH and any transcripts in ~/.claude/projects/.../*.jsonl:
bun bin/gstack-memory-ingest.ts --bulk
# Every page errors: [put-error] ... Unknown command: put_page

Verified

bun test test/gstack-memory-ingest.test.ts — 17/17 pass (15 existing + 2 new regression tests).
Real-world: 61/62 pages ingested cleanly post-patch on a v0.27.0 install. The single failure was a within-batch slug collision unrelated to the writer.

Notes

The V1.5 NOTE block at the top of the file referenced put_page in prose. Updated to describe the current gbrain put <slug> (stdin, frontmatter) shape so the doc stays accurate; the future put_file blob-routing TODO is unchanged.
Section comment // ── Writer (calls gbrain put_page) ── updated to // ── Writer (calls \gbrain put`) ──`.

Test plan

bun test test/gstack-memory-ingest.test.ts passes
Manual --bulk run on a real gbrain v0.27.0 install ingests pages successfully
Fake-shim test catches a regression to put_page (verified: rolling back the writer makes the new test fail)

^{Need help on this PR? Tag @codesmith with what you need.}

Let Codesmith autofix CI failures and bot reviews

…_page` gbrain v0.27 retired the flag-based `put_page --slug X --title Y` form for the positional `put <slug>` (content via stdin, YAML frontmatter for metadata). Against any current gbrain, the writer returned `[put-error] Unknown command: put_page` for every page; bulk ingest produced 0 successful writes. Switch `gbrainPutPage` to `gbrain put <slug>`, injecting `title`/`type`/`tags` as YAML frontmatter when the page body does not already start with one (the transcript builder already prepends frontmatter on its own; artifact pages get the writer-side injection). Also bump `gbrainAvailable()` to probe `gbrain --help` for the `put` subcommand. If a future gbrain renames or removes it, every page now fails fast with one clean error instead of N copies of "Unknown command". Regression coverage: two new tests in `test/gstack-memory-ingest.test.ts` stand up a fake `gbrain` shim on PATH. The first asserts the writer hits `put <slug>` with stdin body + frontmatter and never invokes `put_page`; the second points the writer at a legacy-only shim and asserts the availability probe surfaces a single missing-subcommand error. Tested on gbrain v0.27.0 (61/62 pages ingested cleanly post-patch; the one failure was a within-batch slug collision unrelated to the writer). Reproduced by: bun ~/.claude/skills/gstack/bin/gstack-memory-ingest.ts --bulk # before: every page errors `[put-error] ... Unknown command: put_page` # after: pages land via `gbrain put <slug>`

@smithjoshua

…n-valid source ids (#1344) * fix: use correct `gbrain put <slug>` CLI verb in memory ingest `put_page` is the MCP tool name, not a CLI subcommand. The actual gbrain verb is `put <slug>` with content via stdin and tags in YAML frontmatter. Every transcript / memory ingest fails today on clean installs. Switch to the right verb and inject title/type/tags into the frontmatter that buildTranscriptPage / buildArtifactPage already produce. Bundled in the same function: - timeout: 30s → 60s. Auto-link reconciliation hits 30s once the brain has a few hundred pages. - maxBuffer: 1MB → 16MB. Without it Node truncates gbrain's stderr and callers see only `Command failed:` with no detail. - Surface stderr/stdout in the returned error instead of the bare exception. Verified: bun test test/gstack-memory-ingest.test.ts -> 15/15 pass. bun test on the three test files touching this path -> 362/362. * fix(sync-gbrain): generate gbrain-valid source ids for repos with dots or long names `deriveCodeSourceId` previously concatenated the canonicalized remote with only `/` and whitespace stripped, leaving dots from hostnames (`github.com`) and no length cap. gbrain rejects any source id containing characters outside [a-z0-9-] or longer than 32 chars, so `github.com/<org>/<repo>` produced `gstack-code-github.com-<org>-<repo>` (40 chars, plus dots) and registration failed: code source registration failed: Invalid source id "gstack-code-github.com-radubach-platform". Must be 1-32 lowercase alnum chars with optional interior hyphens. Fix: - Drop the host segment (`github.com` is the same for nearly every user and just consumes the 32-char budget). Use only the last two path segments (org-repo). - Sanitize any remaining non-alnum to hyphens, then collapse and trim. - For genuinely long org/repo names that still exceed the budget, keep the tail (most distinctive end of the slug) and append a 6-char sha1 hash for collision resistance. Adds a regression test that spawns the CLI in temp git repos with controlled remotes (dot in hostname, SCP-style, multi-dot host, long names forcing hash-truncation) and asserts every derived id is ≤32 chars and matches the gbrain validator regex. * fix(memory-ingest): hybrid frontmatter writer + tightened gbrain availability probe PR #1328 (merged in the prior commit) correctly injects title/type/tags into the YAML frontmatter that buildTranscriptPage already prepends. But buildArtifactPage emits raw markdown without frontmatter, so design-docs, learnings, and builder-profile-entries were landing in gbrain with empty title/type/tags. Add the no-frontmatter wrap branch so artifact pages get the same metadata the inject branch provides for transcripts. Also bring in gbrainAvailable()'s --help probe (originally proposed in PR #1341 by Alex Medina), with the regex tightened from /(^|\s)put(\s|$)/m to /^\s+put\s/m. Anchoring on the indented subcommand format gbrain's help actually uses keeps the probe from matching "put" appearing as prose in help text, while still failing fast with one clean error if a future gbrain renames or removes the put subcommand. Updates the V1.5 NOTE doc block at the top of the file to describe the current put-via-stdin shape rather than the legacy put_page flag form. Co-Authored-By: Alex Medina <oficina@puntoverdemc.com> * test+fix(memory-ingest): strengthen regression tests, fix inject for malformed-close frontmatter Imports the shim-based regression tests from PR #1341 (Alex Medina) and strengthens them to assert title, type, and tags actually arrive in put stdin — not just `agent: claude-code`. Asserting the metadata fields matches the regression class that's caused this fix wave: writers can "succeed" while metadata is silently lost. The original PR #1341 tests would have passed even with title/type/tags missing. Strengthening the test surfaced a deeper issue. buildTranscriptPage joins frontmatter array elements with "\n" and does not append a trailing newline, so the close fence is "\n---<content>" directly, not "\n---\n". PR #1328's inject branch searched for "\n---\n" and never matched — which means even with PR #1328 alone, transcript pages were landing in gbrain with no title/type/tags. Two-line fix: search for "\n---" only, since the inject lands before the close fence regardless of what follows it. Also imports PR #1341's V1.5 NOTE doc-block update and the section comment refresh so the prose stays accurate against the new writer shape. Co-Authored-By: Alex Medina <oficina@puntoverdemc.com> * fix+test(gbrain-sync): handle empty-slug edge in constrainSourceId, add no-origin and basename-empty regression tests PR #1330 (merged in the prior commit) addressed the dot-in-host and length-overflow cases for source-id derivation, but constrainSourceId silently returned "${prefix}-" when the input sanitized to an empty slug — invalid per gbrain's `^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$` validator on the trailing hyphen. Adds an explicit empty-slug branch that falls back to a sha1-prefixed id ("gstack-code-<6hex>") so the output stays gbrain-valid for every input shape. Two new regression tests cover the corners PR #1330's coverage left exposed: - no-origin fallback: a cwd repo with no `origin` remote configured must still derive a valid id from the basename. - basename-sanitizes-to-empty: a repo whose path basename is all non-alnum (e.g. "___") must produce the hash-only fallback, not an invalid trailing-hyphen id. Both run the CLI inside temp git repos for genuine end-to-end coverage (matches the pattern PR #1330 established for its own four remote-shape cases). Co-Authored-By: Richard Dubach <radubach@gmail.com> * chore: bump VERSION to 1.26.5.0 + CHANGELOG entry for fix wave PATCH bump. Three bug fixes (memory-ingest put_page CLI verb mismatch, hybrid frontmatter writer for transcripts AND artifacts, gbrain-valid source-id derivation for github-hosted repos), no new user capability. CHANGELOG release-summary leads with what users can now do (clean- install transcripts populate the brain, github-hosted repos register code sources) and tabulates before/after numbers from real gbrain v0.25.1 smoke output. Itemized changes credit @smithjoshua, @AZ-1224, and @radubach for the originating PRs plus the additional hybrid branch + strengthened tests added on top per Codex plan-review. * docs(todos): file P2 (gbrain install-pin staleness) + P3 (source-id host-collision) follow-ups Two follow-ups surfaced during the v1.26.5.0 fix-wave plan review. P2 — Issue #1305 part 2: bin/gstack-gbrain-install pins gbrain to v0.18.2 (commit 08b3698) but doesn't move when gstack ships features that depend on newer gbrain ops or schema. Fresh /setup-gbrain on v1.26.x lands users on schema 24 with v1.26 features expecting 32+. Captured for a future fix-wave. P3 — Codex P1.3 from the v1.26.5.0 plan review: deriveCodeSourceId drops the host segment to fit gbrain's 32-char source-id budget, which means github.com/acme/foo and gitlab.com/acme/foo collapse to the same source id. Real but rare; PR #1330 author explicitly considered this and chose budget over cross-host uniqueness. Captured as a long-tail concern. --------- Co-authored-by: Joshua Smith <joshualowellsmith@gmail.com> Co-authored-by: Richard Dubach <radubach@gmail.com> Co-authored-by: Alex Medina <oficina@puntoverdemc.com>

garrytan · 2026-05-09T07:36:08Z

Closing as superseded — the gbrain put writer rewrite shipped in v1.26.5.0 (#1344). Thanks for the contribution!

@smithjoshua

…n-valid source ids (garrytan#1344) * fix: use correct `gbrain put <slug>` CLI verb in memory ingest `put_page` is the MCP tool name, not a CLI subcommand. The actual gbrain verb is `put <slug>` with content via stdin and tags in YAML frontmatter. Every transcript / memory ingest fails today on clean installs. Switch to the right verb and inject title/type/tags into the frontmatter that buildTranscriptPage / buildArtifactPage already produce. Bundled in the same function: - timeout: 30s → 60s. Auto-link reconciliation hits 30s once the brain has a few hundred pages. - maxBuffer: 1MB → 16MB. Without it Node truncates gbrain's stderr and callers see only `Command failed:` with no detail. - Surface stderr/stdout in the returned error instead of the bare exception. Verified: bun test test/gstack-memory-ingest.test.ts -> 15/15 pass. bun test on the three test files touching this path -> 362/362. * fix(sync-gbrain): generate gbrain-valid source ids for repos with dots or long names `deriveCodeSourceId` previously concatenated the canonicalized remote with only `/` and whitespace stripped, leaving dots from hostnames (`github.com`) and no length cap. gbrain rejects any source id containing characters outside [a-z0-9-] or longer than 32 chars, so `github.com/<org>/<repo>` produced `gstack-code-github.com-<org>-<repo>` (40 chars, plus dots) and registration failed: code source registration failed: Invalid source id "gstack-code-github.com-radubach-platform". Must be 1-32 lowercase alnum chars with optional interior hyphens. Fix: - Drop the host segment (`github.com` is the same for nearly every user and just consumes the 32-char budget). Use only the last two path segments (org-repo). - Sanitize any remaining non-alnum to hyphens, then collapse and trim. - For genuinely long org/repo names that still exceed the budget, keep the tail (most distinctive end of the slug) and append a 6-char sha1 hash for collision resistance. Adds a regression test that spawns the CLI in temp git repos with controlled remotes (dot in hostname, SCP-style, multi-dot host, long names forcing hash-truncation) and asserts every derived id is ≤32 chars and matches the gbrain validator regex. * fix(memory-ingest): hybrid frontmatter writer + tightened gbrain availability probe PR garrytan#1328 (merged in the prior commit) correctly injects title/type/tags into the YAML frontmatter that buildTranscriptPage already prepends. But buildArtifactPage emits raw markdown without frontmatter, so design-docs, learnings, and builder-profile-entries were landing in gbrain with empty title/type/tags. Add the no-frontmatter wrap branch so artifact pages get the same metadata the inject branch provides for transcripts. Also bring in gbrainAvailable()'s --help probe (originally proposed in PR garrytan#1341 by Alex Medina), with the regex tightened from /(^|\s)put(\s|$)/m to /^\s+put\s/m. Anchoring on the indented subcommand format gbrain's help actually uses keeps the probe from matching "put" appearing as prose in help text, while still failing fast with one clean error if a future gbrain renames or removes the put subcommand. Updates the V1.5 NOTE doc block at the top of the file to describe the current put-via-stdin shape rather than the legacy put_page flag form. Co-Authored-By: Alex Medina <oficina@puntoverdemc.com> * test+fix(memory-ingest): strengthen regression tests, fix inject for malformed-close frontmatter Imports the shim-based regression tests from PR garrytan#1341 (Alex Medina) and strengthens them to assert title, type, and tags actually arrive in put stdin — not just `agent: claude-code`. Asserting the metadata fields matches the regression class that's caused this fix wave: writers can "succeed" while metadata is silently lost. The original PR garrytan#1341 tests would have passed even with title/type/tags missing. Strengthening the test surfaced a deeper issue. buildTranscriptPage joins frontmatter array elements with "\n" and does not append a trailing newline, so the close fence is "\n---<content>" directly, not "\n---\n". PR garrytan#1328's inject branch searched for "\n---\n" and never matched — which means even with PR garrytan#1328 alone, transcript pages were landing in gbrain with no title/type/tags. Two-line fix: search for "\n---" only, since the inject lands before the close fence regardless of what follows it. Also imports PR garrytan#1341's V1.5 NOTE doc-block update and the section comment refresh so the prose stays accurate against the new writer shape. Co-Authored-By: Alex Medina <oficina@puntoverdemc.com> * fix+test(gbrain-sync): handle empty-slug edge in constrainSourceId, add no-origin and basename-empty regression tests PR garrytan#1330 (merged in the prior commit) addressed the dot-in-host and length-overflow cases for source-id derivation, but constrainSourceId silently returned "${prefix}-" when the input sanitized to an empty slug — invalid per gbrain's `^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$` validator on the trailing hyphen. Adds an explicit empty-slug branch that falls back to a sha1-prefixed id ("gstack-code-<6hex>") so the output stays gbrain-valid for every input shape. Two new regression tests cover the corners PR garrytan#1330's coverage left exposed: - no-origin fallback: a cwd repo with no `origin` remote configured must still derive a valid id from the basename. - basename-sanitizes-to-empty: a repo whose path basename is all non-alnum (e.g. "___") must produce the hash-only fallback, not an invalid trailing-hyphen id. Both run the CLI inside temp git repos for genuine end-to-end coverage (matches the pattern PR garrytan#1330 established for its own four remote-shape cases). Co-Authored-By: Richard Dubach <radubach@gmail.com> * chore: bump VERSION to 1.26.5.0 + CHANGELOG entry for fix wave PATCH bump. Three bug fixes (memory-ingest put_page CLI verb mismatch, hybrid frontmatter writer for transcripts AND artifacts, gbrain-valid source-id derivation for github-hosted repos), no new user capability. CHANGELOG release-summary leads with what users can now do (clean- install transcripts populate the brain, github-hosted repos register code sources) and tabulates before/after numbers from real gbrain v0.25.1 smoke output. Itemized changes credit @smithjoshua, @AZ-1224, and @radubach for the originating PRs plus the additional hybrid branch + strengthened tests added on top per Codex plan-review. * docs(todos): file P2 (gbrain install-pin staleness) + P3 (source-id host-collision) follow-ups Two follow-ups surfaced during the v1.26.5.0 fix-wave plan review. P2 — Issue garrytan#1305 part 2: bin/gstack-gbrain-install pins gbrain to v0.18.2 (commit 08b3698) but doesn't move when gstack ships features that depend on newer gbrain ops or schema. Fresh /setup-gbrain on v1.26.x lands users on schema 24 with v1.26 features expecting 32+. Captured for a future fix-wave. P3 — Codex P1.3 from the v1.26.5.0 plan review: deriveCodeSourceId drops the host segment to fit gbrain's 32-char source-id budget, which means github.com/acme/foo and gitlab.com/acme/foo collapse to the same source id. Real but rare; PR garrytan#1330 author explicitly considered this and chose budget over cross-host uniqueness. Captured as a long-tail concern. --------- Co-authored-by: Joshua Smith <joshualowellsmith@gmail.com> Co-authored-by: Richard Dubach <radubach@gmail.com> Co-authored-by: Alex Medina <oficina@puntoverdemc.com>

garrytan mentioned this pull request May 6, 2026

v1.26.5.0 fix wave: gbrain ingest writer (hybrid frontmatter) + gbrain-valid source ids #1344

Merged

9 tasks

garrytan closed this May 9, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(memory-ingest): switch writer to `gbrain put`, retire legacy `put_page`#1341

fix(memory-ingest): switch writer to `gbrain put`, retire legacy `put_page`#1341
AZ-1224 wants to merge 1 commit intogarrytan:mainfrom
AZ-1224:fix-gbrain-put-page

AZ-1224 commented May 6, 2026 •

edited by blacksmith-sh Bot

Loading

Uh oh!

garrytan commented May 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

AZ-1224 commented May 6, 2026 • edited by blacksmith-sh Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Repro (before the fix)

Verified

Notes

Test plan

Uh oh!

garrytan commented May 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

AZ-1224 commented May 6, 2026 •

edited by blacksmith-sh Bot

Loading