Person/codekiln/GitHub/logseq-gardener/Project/Proposal/Astra

• A fast way to write, maintain, and publish a Logseq garden

  • I would build logseq-gardener so that a person can write in Neovim, work with coding agents, and publish a garden while keeping the existing Logseq Markdown files. A shared local engine would understand the pages, blocks, and links. The command line would be its first client, followed by Neovim, graph comparison, a Markdown exporter, editing commands, and a Git merge driver.
  • The editor should show link completion immediately while a person types. An agent should find the right note without repeatedly searching the whole repository. Editing commands should preserve surrounding text. Visitors should read published pages without downloading the garden.
  • Examples use garden as a working command name. Before distributing the executable, choose one name for the repository, package, and binary and check it against installed commands and package registries. The naming question is documented in Person/codekiln/GitHub/logseq-gardener/Analysis/Fable/26/09/12/0658 ET One tool carries four names and two of them collide.

  • Writing in Neovim

    • The editor starts garden lsp over standard input and output when a person opens a garden file. The process loads previously indexed information, reads the open file, and checks for changes elsewhere in the background. The editor owns the process lifecycle.
    • Page completion recognizes full names, aliases, and pages that exist through references even though they have no content file. Following a link opens the content when available; for a fileless page, the editor offers the notes that refer to it.
    • Block-reference completion shows enough surrounding text to identify the intended block. Following a block reference opens its source location. Finding references shows where a page or block is used.
    • Completion uses the text currently in the editor, including unsaved changes. A half-written link should remain usable while typing. A separate command run in a terminal reads the saved garden.

  • Working with a coding agent

    • An agent needs the same page identities and reference information as the editor. I would expose that information through commands with readable output and a matching JSON form.
    • Proposed command examples:
      • text

        garden page exists "Logseq/Frontmatter"
        garden page resolve "Logseq/Frontmatter" --json
        garden page complete "Logseq/Front" --json
        garden page backlinks "Logseq/Frontmatter" --json
        garden block get <uuid> --json
        garden diff --base HEAD --json

    • garden page resolve returns Resolved, Ambiguous, NoMatch, or Incomplete, with the graph identity and source evidence in its JSON output. Evidence includes filenames, title properties, aliases, links and tags, and namespace ancestry. A resolved page may have no content file. Duplicate alias declarations return the competing candidates; fuzzy spelling suggestions remain suggestions.
    • garden page exists calls that resolver and prints nothing. Its proposed exit codes are 0 for resolved, 1 for no match, 2 for ambiguous, and 3 for incomplete; invocation and I/O failures use a separate documented code. Scripts must distinguish those outcomes before creating a page. garden page resolve --batch --json reads names from standard input and returns one JSON result per name. Person/codekiln/GitHub/logseq-gardener/Analysis/Fable/26/09/12/0933 ET Answer page existence with a typed result and an exit code develops this interface.
    • An explicit --graph <path> selects a garden; otherwise discovery walks up from the working directory to the nearest logseq/config.edn. The engine reads the graph configuration before deriving page names, including filename and journal-title formats. Every core lookup receives an explicit graph view.
    • Completion can return candidates while indexing continues. A command deciding whether a name already exists must finish the necessary search or report Incomplete. After the compatibility tests pass, the draft link checker can resolve names in batches and still warn when a new page name looks suspicious.

  • One engine shared by the clients

    • text

      Existing Markdown + graph configuration
                          |
                          v
                  garden-core
           read pages and block trees
           resolve names and references
           retain original text and locations
                          |
                          v
             reusable local index and cache
                          |
           +--------------+----------------+
           |              |                |
           v              v                v
      garden commands  garden lsp     garden export
      person / agent   Neovim         Markdown for a site generator

    • garden-core owns the Logseq behavior: filename and title rules, aliases, namespaces, journals, block parents, UUIDs, properties, references, and supported queries. The command line, editor integration, and publisher call those functions.
    • The installed product should be a native executable with an embedded cache stored outside the garden. Markdown and graph configuration remain the saved knowledge. Removing the cache causes rebuilding.

  • Choose the parser through compatibility tests

    • Trial Rust with lsdoc and reusable parts of tine-core on the encode garden and the public logseq/docs graph. Record the dependency revisions, licenses, mismatches, and timings before choosing the core language. Reuse would begin through a local fork, adaptation, or insourcing. Upstream collaboration can be reconsidered after sustained personal use.
    • Syntax: run lsdoc's differential harness against mldoc and classify each disagreement on constructs these gardens use. Its normalized comparison excludes source spans, so test span accuracy separately.
    • Graph behavior: use Logseq's graph-parser from release 0.10.15, matching the desktop version pinned in the dotfiles Brewfile. Build a fixture runner under nbb-logseq, recording the resolved Logseq commit and dependencies. Check that the runner loads that pinned source. Dump page names, alias relationships, tags, block parents and order, references, and explicit UUIDs for comparison with garden-core. Normalize generated internal IDs; report duplicate explicit UUIDs as conflicts.
    • Source preservation: trial Tine's tine-check and serialization tests. Require a byte-identical no-op round trip, then test property edits and block moves for unchanged surrounding bytes and valid source ranges. A round trip alone does not prove that an actual edit changes the right text. Keep unfamiliar syntax recoverable in the original source.
    • Prefer Rust when the compatibility results and repair effort support it. A graph mismatch calls for work on graph construction; a serialization mismatch calls for source preservation. Compare fixing syntax mismatches in lsdoc with using mldoc in OCaml before choosing that fallback. Both paths need the graph tests. Person/codekiln/GitHub/logseq-gardener/Analysis/Fable/26/09/12/0933 ET Use Logseq's own graph-parser as the oracle and require a byte-identical round trip identifies the test tools.
    • After removing an alias, changing naming configuration, moving a referenced block, or deleting the last reference to a fileless page, compare an incremental update with a clean rebuild. Include legacy filenames and imperfect files from Logseq's fixtures. The test report distinguishes implemented behavior, unsupported syntax, and deliberate diagnostic differences from Logseq.

  • Make speed a feature of the whole workflow

    • I would build a persistent index that short-lived commands can reuse, with a hot in-memory view for the editor. This directly serves repeated agent calls as well as interactive typing.
    • The editor starts background indexing when a person opens the first garden file, before they request completion. The current file and likely completion candidates get priority. Background jobs pause between small batches so a large parse cannot occupy all the time needed to answer a keystroke.
    • Editing a file requires parsing its changed text and checking the references affected by the change. Removing an alias, for example, can change where links in untouched journals lead. The engine should reuse those journals' parsed text while looking up the affected targets again.
    • Start with one SQLite index per checkout under $XDG_CACHE_HOME/<tool>/<hash of real graph-root path>/, using ~/.cache when XDG_CACHE_HOME is unset. Each index owns its file list and relationships. Sharing parsed text across worktrees waits for a measured startup or storage problem. This adopts Person/codekiln/GitHub/logseq-gardener/Analysis/Fable/26/09/12/0933 ET Give each checkout its own cache and share parsed text later.
    • The editor overlays open buffers and their document versions on the saved graph. A parse result for an older version is discarded. Unsaved aliases can affect completion in that editor while a separate CLI process sees the saved files. Replay open, change, complete, save, and close through LSP, including an unfinished link, Unicode before the cursor, and a delayed parse.
    • Cache entries record content hashes, naming configuration, and parser/schema versions. Metadata checks can accelerate change detection, with content verification for uncertain cases such as a same-size rewrite within a timestamp interval. Tests must cover edits whose size and modification time stay the same. Reconciliation includes untracked files and deletions; long-running clients recover missed watcher events by checking the file list again.
    • Concurrent commands publish complete index updates in database transactions. A lookup uses one coherent saved graph view and reports incomplete work or retries when source changes prevent it from establishing that view. Configuration changes invalidate the derived page names and relationships.
    • Record cold parse time and peak memory, fresh-process warm commands, a sequence of separate agent lookups, completion during parsing, save-to-backlink delay, and cache size. Use the encode garden, logseq/docs, large pages, heavily referenced pages, and larger synthetic gardens. Add the operations that felt slow in Looksyk and Tine once those operations and graphs are identified. Set latency targets from those measurements and track the slow requests as well as the typical ones.

  • Help a person understand an edit before committing it

    • garden diff --base HEAD compares the graph at HEAD with the current saved files, including eligible untracked files. garden diff --base HEAD --staged compares HEAD with the complete staged graph, including unchanged tracked files needed to resolve references. Each side uses its own graph configuration. A pre-commit hook uses the staged form so an unstaged fix cannot hide a defect in the pending commit.
    • The report shows links whose targets changed, new reference-only pages, changed block parents, broken UUID references, and pages affected through embeds. Human-readable findings carry file and line locations; JSON exposes the same evidence. For PR review, compare complete trees at explicit base and head revisions.
    • Suppose Studio declares Workshop as an alias and a journal links to Workshop. Removing the alias leaves the journal text unchanged, but its link now names a separate Workshop page. The report identifies the removed declaration, the journal's source line, and the old and new targets. 588fb79e Remove the LazyVim alias supplies a real fixture of this kind.
    • Match blocks by unique explicit UUIDs where available. Positional paths describe locations within one graph version; repeated text, moves, and conflicting IDs can make correspondence uncertain. Share the matching code with the later merge driver and retain uncertainty in the report.
    • The garden's hook can flag broken references while leaving a new reference-only page for the person to judge. Batch page resolution still serves draft link checks. A separate personal-information check still scans each commit for names and other identifying text.
    • Start Git integration with the whole-graph command in hooks and review scripts. Git's external diff driver receives file pairs; a later adapter must obtain both complete graph versions to explain links in unchanged files. A file-pair invocation alone cannot supply that context. Person/codekiln/GitHub/logseq-gardener/Analysis/Fable/26/09/12/0933 ET Call the impact command garden diff and run it where the link checker runs motivates the name and integration.

  • Publish through a Markdown exporter

    • Trial Tine's existing HTML export during the parser evaluation, scoring embed-heavy pages, block references, video macros, and publication filtering. Use that report to decide how much publishing work is already available. Person/codekiln/GitHub/logseq-gardener/Analysis/Fable/26/09/12/0933 ET Expand embeds before evaluating queries in the publisher explains why embeds deserve early attention.
    • garden export would write one CommonMark document per published page, with frontmatter, relative page links, block anchors, backlinks, and copied referenced assets. Start the site-generator trial with QuartzMD. Validate the generated HTML for stable URLs, readable per-page content, a sitemap, and search, and compare how long it takes a visitor to open one page on the new site and the current site.
    • The first export resolves page and block references, expands page and block embeds, and renders video and YouTube timestamp macros. Use Logseq/Frontmatter, whose content comes from embedded subpages, as an acceptance fixture. Emit visible placeholders for unsupported queries and macros and list their source locations in a build report. Query evaluation follows this usable export; unsupported output must be distinguishable from an evaluated query with no results.
    • Record which pages include other content. Editing an included block rebuilds the pages displaying it, including nested embeds. Changed publication settings also invalidate affected output. When query evaluation arrives, its dependencies must account for newly matching and removed results.
    • Apply publication selection to embedded text, references, backlinks, copied assets, search entries, and diagnostics in public output. Test a mixed-visibility fixture so a published page cannot expose excluded content or private target names through those features. Recursive embeds stop at a permitted link to the repeated target; detailed local diagnostics stay outside the published directory.

  • Add editing commands that preserve the files

    • Once reading and comparison are dependable, I would add page rename, block insert/update/move/delete, and property changes. Each operation produces a proposed patch and a report of affected references.
    • Each editing command uses original text and source ranges to preserve untouched bytes, including unfamiliar constructs. Moving a block keeps its explicit UUID attached. Renaming a page finds references according to the graph's naming rules.
    • The command that applies a patch checks that the source still matches the version used to prepare it. If a person or another agent has changed the file, the command reports the conflict and prepares a new preview. A stale preview should never overwrite newer work.
    • The rename command must recover from interruption when it writes several files. The operation records enough information to finish or undo its own writes, and reports partial completion if interrupted. A successful write to one file is not sufficient evidence that the whole rename succeeded.

  • Merge branches before adding shared editing sessions

    • Build a Git merge driver over garden-core's block matcher and source-preserving edits. Git supplies base, ours, and theirs for a file; the driver can combine edits to confidently matched independent blocks. Conflicting UUIDs, uncertain ID-less matches, delete-versus-edit cases, and incompatible moves or sibling order produce an explicit conflict for a person to resolve. Conflict markers may need to cover a parent or the whole file when a smaller region would conceal the structural conflict.
    • Register the file patterns through .gitattributes and install the command through Git configuration, following Git's custom merge driver interface. Validate cross-file relationships with a whole-graph check after the merge. A file-level driver cannot alone establish that a UUID moved between pages remains unique. Person/codekiln/GitHub/logseq-gardener/Analysis/Fable/26/09/12/0658 ET A Logseq-aware git merge driver before a CRDT gives the case for starting with branch-based collaboration.
    • A later shared editing session would exchange operations with explicit block identities when live editing becomes a demonstrated need. A CRDT experiment must cover text, moves, deletion, sibling order, disconnection, and outside editors. Direct file changes must be reconciled with the session's last saved version; coordination history needed by disconnected clients has a different lifetime from disposable parsing cache.

  • Delivery

    • Evaluate compatibility: run the syntax, graph, source-preservation, and performance trials; record the parser choice and adaptation work. Run the Tine export trial alongside that evaluation.
    • Use the CLI daily: ship typed page resolution, batch lookup, completion, backlinks, and UUID lookup with the per-checkout persistent index. After the fixture comparison passes, update the agent commands that draft garden pages to call the resolver.
    • Write in Neovim: add the stdio language server with buffer overlays, navigation, and protocol replay tests against the same graph fixtures.
    • Review graph changes: ship garden diff, exercise alias-removal history and partial staging, and add staged checks to the commit workflow.
    • Publish: export links, embeds, and supported macros through the shared engine and a standard site generator. Check publication filtering and measure the resulting page load before adding query evaluation.
    • Apply edits: add mutation previews, source-version checks, and recoverable multi-file operations, with tests for small diffs and interrupted writes.
    • Merge branches: use the tested matcher in a conservative Git merge driver. Explore shared editing sessions when simultaneous editing is needed.