Skip to content

feat(read): add notes read for convention-aware body reading - #144

Merged
junior-ricon merged 3 commits into
KnickKnackLabs:mainfrom
olavostauros:feat/126-convention-aware-read
Aug 7, 2026
Merged

feat(read): add notes read for convention-aware body reading#144
junior-ricon merged 3 commits into
KnickKnackLabs:mainfrom
olavostauros:feat/126-convention-aware-read

Conversation

@olavostauros

Copy link
Copy Markdown
Collaborator

Summary

Closes #126

Adds notes read <file> — the convention-aware read command that returns the visible Markdown body without YAML frontmatter by default. This builds on the parser foundation from PR #127 (notes parse) and establishes the CLI interface the issue proposed.

Changes

  • .mise/tasks/read — New uv-based Python mise task (same pattern as .mise/tasks/parse):

    • Returns visible body by default (frontmatter stripped)
    • --json flag outputs structured components (frontmatter, body, diagnostics)
    • --with-frontmatter flag includes YAML frontmatter in plain text output
    • Leverages existing note_components parser library
    • Error handling for missing notes and non-UTF-8 files
  • test/read.bats — 10 tests covering:

    • Plain notes → body returned without frontmatter
    • Frontmatter notes → frontmatter stripped by default
    • --with-frontmatter → frontmatter included
    • --json → structured output with correct components
    • --json for plain notes (no frontmatter present)
    • Malformed frontmatter → treated as visible body
    • Missing notes → error message
    • Slug resolution → notes read slug resolves from notes dir
    • Absolute path resolution → notes read /path/to/file.md
    • --json diagnostics field present
  • README.md — Updated quick start, daily workflow, what notes manages, and gotchas sections with notes read documentation

Test plan

  • All 10 new tests pass locally
  • Pre-existing parse.bats failures are environment-specific (mise/rudi install issue, not caused by this PR)
  • notes read uses the same path resolution and parser as notes parse

olavostauros and others added 3 commits June 18, 2026 10:51
- Add .mise/tasks/read — a uv-based Python mise task that returns visible
  body (stripping frontmatter by default)
- Support --json flag for structured component output (frontmatter/body/
  diagnostics)
- Support --with-frontmatter flag to include YAML frontmatter in plain text
- Leverages existing note_components parser from PR KnickKnackLabs#127
- Follows same uv/usage pattern as .mise/tasks/parse
- Add test/read.bats with 10 tests covering plain notes, frontmatter notes,
  JSON output, malformed frontmatter, missing notes, slug/path resolution
- Update README with documentation and usage examples

Closes KnickKnackLabs#126
@junior-ricon
junior-ricon merged commit cbf5213 into KnickKnackLabs:main Aug 7, 2026
2 checks passed
@junior-ricon

Copy link
Copy Markdown
Contributor

Thanks for proposing a convention-aware read surface. The body-only default and clear missing-note error make this a useful command.

The repair carries two lessons forward. First, new commands should reuse shared selector and parsing boundaries rather than copy them; read, parse, and show now share path-selection behavior, while exact source preservation avoids reconstructing YAML. Second, task tests should run through the public notes/Mise path instead of a hardcoded CI-only runtime path, so local and hosted tests prove the same command users invoke.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Proposal: convention-aware notes read/query API

2 participants