eblume/hephaestus
1
0
Fork 0
generated from eblume/project-template
Code Issues Pull requests Projects Releases 10 Packages Wiki Activity Actions
hephaestus/docs/reference/reference.md
Erich Blume ee865e5635
Some checks failed
Build / validate (pull_request) Failing after 4s
Details
heph.nvim: RPC client + buffer editing + wiki-links + journal (slice 11a) 
The primary surface begins (tech-spec §8): a Neovim plugin that is a thin
client of the local hephd over its unix-socket JSON-RPC.

- node.resolve {title} → Node|null (heph-core Store + dispatch): exact,
  owner-scoped, non-tombstoned alias-then-title match — the same mapping that
  materializes wiki links, so follow-link jumps to the node the stored link
  points at (never fuzzy search). Unit + rpc_socket integration tests.
- heph.nvim/: vim.uv unix-socket JSON-RPC client (blocking call via vim.wait,
  id-demuxed, partial-line buffered, luanil so JSON null → Lua nil; isolated
  Sessions for tests). Buffer-backed nodes (heph://node/<id>, acwrite;
  BufReadCmd→node.get / BufWriteCmd→node.update, whole-buffer body round-trips
  exactly through the CRDT). [[wiki-link]] follow on <CR>. Daily journal.
  :Heph command surface + completion.
- Headless e2e (§9): a self-contained busted-style runner (tests/e2e/runner.lua)
  — no external plugins, no network, deterministic CI exit codes. Specs: journal
  round-trip, follow-link (+ unresolved no-op), link-two-docs/backlink.
  `make -C heph.nvim test` builds hephd and runs it.

Docs: heph-nvim reference card, §14 tracker (11a done; 11b/11c/11d queued),
changelog fragment.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-01 20:33:29 -07:00

3.1 KiB
Raw Blame History

title modified tags
Reference 2026-04-19
reference
meta

Reference

Technical reference material for the repository tooling that ships with this project.

Project

  • tech-spec — Hephaestus technical specification (data model, RPC API, "what is next?" ranking, recurrence, testing strategy, v1 scope)
  • heph-nvim — The Neovim plugin surface: architecture, buffer-backed editing, RPC dependencies, commands, and the headless e2e harness

Template Surface Area

Path Purpose
.dagger/src/hephaestus_ci/ Dagger module that builds the Quartz docs tarball used by releases
.forgejo/workflows/build.yaml Generic CI validation workflow
.forgejo/workflows/release.yaml Manual release workflow that versions, builds docs, and publishes release assets
.forgejo/scripts/ Optional project-specific hooks consumed by the workflows
mise-tasks/ Helper tasks for docs validation, Mikado chains, PR review, and runner inspection

Forgejo Workflows

build.yaml

  • Triggers on pushes to main and pull requests targeting main
  • Runs prek run --all-files
  • Executes .forgejo/scripts/build if that hook exists and is executable
  • Otherwise exits after generic template validation

release.yaml

  • Triggered manually via workflow_dispatch
  • Accepts BUMP_PATCH, BUMP_MINOR, BUMP_MAJOR, or SPECIFIC_VERSION
  • Resolves the next version from the latest Forgejo release tag
  • Builds CHANGELOG.md with towncrier when fragment files exist
  • Builds docs-<version>.tar.gz via dagger call build-docs --src=. --version=<version>
  • Executes .forgejo/scripts/release <version> if present to stage extra files under release-assets/
  • Creates the Forgejo release and uploads the docs tarball plus any extra assets
  • Commits generated changelog updates back to main when fragments were consumed

Mise Tasks

Task Purpose
mise run ai-docs Print the key docs files AI agents are expected to read first
mise run changelog-check Validate changelog fragments are flat files under docs/changelog.d/
mise run docs-check-filenames Detect duplicate doc filenames
mise run docs-check-frontmatter Validate required frontmatter fields
mise run docs-check-index Ensure each doc is linked from its category index
mise run docs-check-links Validate wiki-links against existing doc filenames
mise run docs-mikado Inspect active Mikado chains and resume C2 work
mise run docs-preview <tarball> Extract and serve a released docs tarball locally
mise run mikado-branch-invariant-check Validate mikado/* branch commit discipline
mise run pr-comments <pr_number> List unresolved PR comments
mise run runner-logs [run_number] List Forgejo Actions runs or fetch logs for a job

Changelog Fragments

  • Store towncrier fragments under docs/changelog.d/
  • Use one flat .md file per change
  • The directory may contain only .gitkeep until the first real fragment is added

TODO After Templating

  • TODO: Set baseUrl in docs/quartz.config.ts to the hosted docs domain once published (currently localhost)