Cloonar/deckle
3
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions

Walking skeleton: Go binary + SolidJS shell + supervised hugo server preview #1

New issue
Closed
opened 2026-07-11 12:58:26 +02:00 by dominik.polakovics · 2 comments
dominik.polakovics commented 2026-07-11 12:58:26 +02:00
Owner
Copy link

What to build

The end-to-end spine everything else plugs into (docs/DECISIONS.md D13, D22): a single Go binary that, pointed at a Hugo site directory, serves an embedded SolidJS SPA shell and supervises a hugo server --buildDrafts subprocess, with the live preview shown in an iframe inside the shell. Include a sample Hugo site in the repo (testdata) to run against. The tool binds to localhost only.

Acceptance criteria

  • harness serve --site <dir> starts, spawns hugo server --buildDrafts bound to an internal port, and restarts it if it crashes
  • Browser at the tool's port shows the SolidJS shell (TYPO3-style layout placeholder: tree pane, form pane, preview pane) with the live site in the preview iframe
  • Editing a content file on disk by hand reflects in the preview via Hugo LiveReload without tool involvement
  • Hugo build errors from the subprocess are captured and surfaced in the shell instead of a dead iframe
  • SPA is embedded in the Go binary (go:embed); go build produces one deployable artifact
  • CI for this repo runs Go and frontend builds + tests

Blocked by

None - can start immediately

## What to build The end-to-end spine everything else plugs into (docs/DECISIONS.md D13, D22): a single Go binary that, pointed at a Hugo site directory, serves an embedded SolidJS SPA shell and supervises a `hugo server --buildDrafts` subprocess, with the live preview shown in an iframe inside the shell. Include a sample Hugo site in the repo (testdata) to run against. The tool binds to localhost only. ## Acceptance criteria - [ ] `harness serve --site <dir>` starts, spawns `hugo server --buildDrafts` bound to an internal port, and restarts it if it crashes - [ ] Browser at the tool's port shows the SolidJS shell (TYPO3-style layout placeholder: tree pane, form pane, preview pane) with the live site in the preview iframe - [ ] Editing a content file on disk by hand reflects in the preview via Hugo LiveReload without tool involvement - [ ] Hugo build errors from the subprocess are captured and surfaced in the shell instead of a dead iframe - [ ] SPA is embedded in the Go binary (go:embed); `go build` produces one deployable artifact - [ ] CI for this repo runs Go and frontend builds + tests ## Blocked by None - can start immediately
dominik.polakovics commented 2026-07-11 13:09:54 +02:00
Author
Owner
Copy link

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Build the end-to-end walking skeleton: a single Go binary that serves an embedded SolidJS shell and supervises a hugo server --buildDrafts subprocess whose output is shown live in an iframe.

Current behavior:
The repository is greenfield: it contains only README.md and docs/DECISIONS.md (the design record). There is no code, no build tooling, and no CI. Every other planned issue depends on the spine this issue creates.

Desired behavior:
harness serve --site <dir>, pointed at a Hugo site directory, starts a localhost-only web server (D19: bind to localhost, never a public interface) that serves a SolidJS SPA embedded in the binary via go:embed (D22). On startup it spawns hugo server --buildDrafts as a subprocess (never linked as a library — D13/D22) bound to an internal localhost port, and supervises it: if the subprocess crashes it is restarted. The SPA presents the TYPO3-style three-pane layout placeholder (D11): page-tree pane, form pane, and a preview pane containing an iframe of the live Hugo site. Hugo LiveReload works through the iframe, so hand-editing a content file on disk updates the preview with no tool involvement. If the Hugo subprocess fails to build (e.g. a broken template or content file), the error output is captured and surfaced in the shell UI instead of leaving a dead iframe.

The repo includes a minimal sample Hugo site under a testdata-style directory to run and test against.

Key interfaces:

  • CLI entrypoint: harness serve --site <dir> (the binary name is harness; further subcommands like init are other issues' scope)
  • Process supervisor contract: spawn hugo server --buildDrafts on an internal port, restart on crash, capture stdout/stderr for error surfacing; assume hugo is available on PATH for this slice (version pinning + auto-download is a separate issue)
  • Frontend shell: SolidJS SPA, three-pane layout placeholder, preview iframe pointed at the supervised Hugo server (directly or via proxy — implementer's choice, as long as LiveReload works)
  • Build contract: go build from the repo root produces one deployable artifact containing the built frontend (D22); frontend tooling choice (e.g. Vite) is the implementer's

Acceptance criteria:

  • harness serve --site <dir> starts, spawns hugo server --buildDrafts bound to an internal port, and restarts it if it crashes
  • The tool's HTTP server binds to localhost only
  • Browser at the tool's port shows the SolidJS shell with tree/form/preview panes and the live site in the preview iframe
  • Editing a content file of the sample site on disk by hand reflects in the preview via Hugo LiveReload without tool involvement
  • Hugo build errors from the subprocess are captured and surfaced in the shell instead of a dead iframe
  • The SPA is embedded via go:embed; go build produces a single deployable artifact
  • A sample Hugo site lives in the repo (testdata) and is used by tests
  • CI on this repo (Forgejo Actions workflow) runs Go and frontend builds + tests

Out of scope:

  • Hugo version pinning, harness.yaml, and auto-downloading the hugo binary (issue #5) — assume hugo on PATH
  • Any real editing functionality: shortcode round-trip (#2), forms (#3), page tree data (#4) — panes are placeholders
  • Click-to-select bridge and viewport toggle in the preview (#16)
  • harness init scaffolding (#17)
  • Git operations, locks, auth/proxy identity, media handling
  • Note the CI criterion above is this repo's own CI, not the scaffolded customer-site workflow from D15/D26 (#17)
> *This was generated by AI during triage.* ## Agent Brief **Category:** enhancement **Summary:** Build the end-to-end walking skeleton: a single Go binary that serves an embedded SolidJS shell and supervises a `hugo server --buildDrafts` subprocess whose output is shown live in an iframe. **Current behavior:** The repository is greenfield: it contains only `README.md` and `docs/DECISIONS.md` (the design record). There is no code, no build tooling, and no CI. Every other planned issue depends on the spine this issue creates. **Desired behavior:** `harness serve --site <dir>`, pointed at a Hugo site directory, starts a localhost-only web server (D19: bind to localhost, never a public interface) that serves a SolidJS SPA embedded in the binary via `go:embed` (D22). On startup it spawns `hugo server --buildDrafts` as a subprocess (never linked as a library — D13/D22) bound to an internal localhost port, and supervises it: if the subprocess crashes it is restarted. The SPA presents the TYPO3-style three-pane layout placeholder (D11): page-tree pane, form pane, and a preview pane containing an iframe of the live Hugo site. Hugo LiveReload works through the iframe, so hand-editing a content file on disk updates the preview with no tool involvement. If the Hugo subprocess fails to build (e.g. a broken template or content file), the error output is captured and surfaced in the shell UI instead of leaving a dead iframe. The repo includes a minimal sample Hugo site under a testdata-style directory to run and test against. **Key interfaces:** - CLI entrypoint: `harness serve --site <dir>` (the binary name is `harness`; further subcommands like `init` are other issues' scope) - Process supervisor contract: spawn `hugo server --buildDrafts` on an internal port, restart on crash, capture stdout/stderr for error surfacing; assume `hugo` is available on `PATH` for this slice (version pinning + auto-download is a separate issue) - Frontend shell: SolidJS SPA, three-pane layout placeholder, preview iframe pointed at the supervised Hugo server (directly or via proxy — implementer's choice, as long as LiveReload works) - Build contract: `go build` from the repo root produces one deployable artifact containing the built frontend (D22); frontend tooling choice (e.g. Vite) is the implementer's **Acceptance criteria:** - [ ] `harness serve --site <dir>` starts, spawns `hugo server --buildDrafts` bound to an internal port, and restarts it if it crashes - [ ] The tool's HTTP server binds to localhost only - [ ] Browser at the tool's port shows the SolidJS shell with tree/form/preview panes and the live site in the preview iframe - [ ] Editing a content file of the sample site on disk by hand reflects in the preview via Hugo LiveReload without tool involvement - [ ] Hugo build errors from the subprocess are captured and surfaced in the shell instead of a dead iframe - [ ] The SPA is embedded via `go:embed`; `go build` produces a single deployable artifact - [ ] A sample Hugo site lives in the repo (testdata) and is used by tests - [ ] CI on this repo (Forgejo Actions workflow) runs Go and frontend builds + tests **Out of scope:** - Hugo version pinning, `harness.yaml`, and auto-downloading the hugo binary (issue #5) — assume `hugo` on PATH - Any real editing functionality: shortcode round-trip (#2), forms (#3), page tree data (#4) — panes are placeholders - Click-to-select bridge and viewport toggle in the preview (#16) - `harness init` scaffolding (#17) - Git operations, locks, auth/proxy identity, media handling - Note the CI criterion above is this repo's own CI, not the scaffolded customer-site workflow from D15/D26 (#17)
dominik.polakovics commented 2026-07-11 14:13:24 +02:00
Author
Owner
Copy link

This was generated by AI while landing a PR.

Landed via PR #18 (merged).

Verification signal: Forgejo Actions CI — ci / build-and-test, run 2, success in 2m8s (frontend build+test, go vet, go test incl. the real-hugo integration test, go build). The initial run was stuck pending because the workflow targeted a docker runner this instance doesn't offer; fixed on the PR branch (commit 1d81872, runs-on: ubuntu-latest), after which CI went green.

Review: Conventional-commit title; valid Closes #1; clean merge into main; all 8 acceptance criteria satisfied (harness serve/supervise/restart, localhost-only bind, three-pane SolidJS shell + preview iframe, LiveReload-safe polling, build errors surfaced, go:embed single artifact, testdata sample site used by tests, CI runs Go+frontend). Scope stayed within the issue — #2/#3/#4/#16/#17 left as declared placeholders.

Verdict: PASS. Merged with a merge commit.

> *This was generated by AI while landing a PR.* Landed via PR #18 (merged). **Verification signal:** Forgejo Actions CI — `ci / build-and-test`, run 2, success in 2m8s (frontend build+test, `go vet`, `go test` incl. the real-hugo integration test, `go build`). The initial run was stuck pending because the workflow targeted a `docker` runner this instance doesn't offer; fixed on the PR branch (commit 1d81872, `runs-on: ubuntu-latest`), after which CI went green. **Review:** Conventional-commit title; valid `Closes #1`; clean merge into main; all 8 acceptance criteria satisfied (harness serve/supervise/restart, localhost-only bind, three-pane SolidJS shell + preview iframe, LiveReload-safe polling, build errors surfaced, go:embed single artifact, testdata sample site used by tests, CI runs Go+frontend). Scope stayed within the issue — #2/#3/#4/#16/#17 left as declared placeholders. Verdict: PASS. Merged with a merge commit.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
afk/130
afk/129
afk/128
afk/124
afk/117
afk/116
afk/115
afk/114
afk/113
afk/112
afk/111
lab/20260718-0231
afk/95
afk/93
afk/91
afk/97
afk/90
afk/94
afk/96
afk/92
afk/89
lab/20260716-2349
afk/83
afk/72
afk/70
afk/58
afk/56
afk/54
afk/52
afk/50
afk/48
lab/20260715-1223
afk/44
afk/42
afk/40
afk/37
afk/35
afk/33
lab/20260712-0208
afk/9
afk/4
afk/14
afk/12
afk/10
afk/7
afk/6
afk/3
afk/2
afk/1
No results found.
Labels
Clear labels   
enhancement
New feature or improvement

  
needs-triage
Maintainer needs to evaluate this issue

  
ready-for-agent
Fully specified, ready for an AFK agent

  
ready-for-human
Requires human implementation

No labels
enhancement
needs-triage
ready-for-agent
ready-for-human
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Cloonar/deckle#1
No description provided.