Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

config: give generated-brain scripts a declared, cache-safe way to parse frontmatter

Open Beginner friendly
  • Is something wrong?
#3 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
86/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
bun, typescript
Domain
documentation, tooling

Research direction

Start with the template's package.json and the brain-kit core dependency declaration at packages/core/package.json:65, then locate the template's lockfile and available-tooling guidance. Add gray-matter at ^4.0.3, document it as the supported frontmatter library, update the lockfile, and verify with bun install --linker isolated followed by the specified import one-liner in a fresh generated brain.

Written by the indexing model from the issue text.

Description

area: config blocked priority: p2 type: feat upstream: brain-kit

Context

A generated brain declares one dependency, @schlessera/brain (package.json:13-15). Scripts and skills that live in a brain — personal tooling, local skills with helper scripts, one-off maintenance scripts an agent writes — routinely need to read and write Markdown frontmatter. Today they reach for gray-matter, which only resolves by accident: it is a transitive dependency of @schlessera/brain (schlessera/brain-kit: packages/core/package.json:92, packages/common/package.json:76) that bun's default install hoists into the brain's top-level node_modules. Under an isolated linker, a future core refactor or another package manager it disappears, and agents that find no declared parser fall back to regex parsing or ask to install something.

Simply declaring gray-matter and calling it "the supported way" is not safe. brain-kit's binding record (docs/decisions/frontmatter-parsing.md:1-28, ruling 2026-09-28 on brain-kit#142) explains why: called as matter(input) with no options, gray-matter 4.0.3 keeps a process-wide cache keyed by the input string that shares one data object between byte-identical documents, caches a failed parse as a success, and never evicts. gray-matter also selects a frontmatter language from the opening fence, including executable engines. Inside brain-kit every parse therefore goes through the cache-free parseFrontmatter helper with an optional data-language guard (parseFrontmatter, packages/common/src/frontmatter-parse.ts:34-52), and a lint gate refuses direct use. That helper is reached only through @schlessera/brain-common/internal/frontmatter, an /internal entry with no compatibility promise (docs/integration-contract.md:1-18), so the template cannot tell brains to import it either. The earlier body cited packages/core/src/cli/commands/briefing.ts:3 as a gray-matter precedent; that line now imports parseFrontmatter.

Decision (maintainer, 2026-10-26): Option B. Generated-brain scripts use a supported read/write frontmatter helper from an ordinary entry of @schlessera/brain, with cache independence and data-only parsing enforced by the helper. No direct gray-matter dependency or internal import is added. The upstream API, decision record and contract work are owned by https://github.com/schlessera/brain-kit/issues/2990.

Blocked by schlessera/brain-kit#2990

Scope

  • Adopt the supported read/write API delivered by brain-kit#2990 through the existing @schlessera/brain dependency. Set the minimum supported version to the release containing that API and refresh the lockfile; do not add gray-matter or an internal dependency.
  • Add a short read/edit/write example to the template's agent guidance, using the shipped public import and documenting supported YAML data, error behavior and serialization normalization.

Out of scope

  • Making brain setup or brain doctor add the dependency to existing brains.
  • Adding other YAML libraries beyond what the ruling names.
  • The brain-kit side of any option that needs one (for example a new public export or command); that would be its own brain-kit issue, linked with upstream: brain-kit.

Acceptance criteria

  • A fresh generated brain declares @schlessera/brain at a version containing the supported API, without adding a direct parser dependency or an internal import.

  • After bun install --linker isolated in a fresh brain, the documented import resolves from the brain root.

  • Following the documented usage, two byte-identical documents parse to independent data objects (mutating one does not change the other), and a malformed document throws on every parse, not only the first.

  • Following the documented usage, a document whose fence declares a non-data language (for example ---js) is refused rather than evaluated.

  • The documented read/edit/write example preserves supported values and body through serialization and reparsing, with the upstream documented normalization.

Verification

Generate a brain from the template, run bun install --linker isolated, and from the brain root run a short bun -e script that follows the documented usage: import, parse the same bytes twice and mutate one result, parse a malformed block twice, and parse a ---js block. Before the change the import fails with a module-not-found error under the isolated linker.

Contract impact

No new template machine contract. brain-kit#2990 owns the additive supported API contract change.

2026-10-24: rethought around safe, declared frontmatter tooling. The previous scope recommended direct gray-matter use, which brain-kit's frontmatter-parsing decision rules unsafe, and cited a precedent that no longer exists; the supported consumer approach needs a maintainer ruling first (needs: decision).

2026-10-26: Option B selected; scope now targets the supported public read/write API, retaining the existing core dependency. The decision is resolved; adoption waits on brain-kit#2990. Historical undecided wording above describes the prior state.

Dominant language
TypeScript
Stars
0
Forks
0
No merged PRs in 30d

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from schlessera/brain-template

All issues in schlessera/brain-template

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.