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

harness init: scaffold Hugo skeleton, harness.yaml, CI workflow, theme + element library copies #17

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

What to build

The one-command site bootstrap (docs/DECISIONS.md D15, D21, D25, D26): harness init in an empty (or fresh git) directory scaffolds a complete, immediately editable site — Hugo skeleton (hugo.toml, content/<lang>/ with a starter home page), a copy of the basic theme, a copy of the system element library (layouts/shortcodes/* + editor/elements/*), page-type sidecars, harness.yaml (site title, language list of one, Hugo version pin, defaults), a CI workflow (Forgejo and GitHub variants: checkout → pinned hugo build → commented-out deploy step with rsync/pages examples), and .gitignore entries (.harness/). Scaffolded copies are developer-owned from then on — no update mechanism by design.

Acceptance criteria

  • harness init then harness serve yields a working editable site with the basic theme and full element library, no manual steps
  • Generated CI workflow runs green on a fresh Forgejo repo (build succeeds; deploy step present but commented, with clear instructions)
  • Workflow uses the Hugo version pinned in harness.yaml
  • init refuses to overwrite existing files and reports what it would touch
  • Everything scaffolded is committed-ready: no secrets, no absolute paths, .harness/ ignored
  • Sidecar files carry the version: field for forward compatibility

Blocked by

## What to build The one-command site bootstrap (docs/DECISIONS.md D15, D21, D25, D26): `harness init` in an empty (or fresh git) directory scaffolds a complete, immediately editable site — Hugo skeleton (`hugo.toml`, `content/<lang>/` with a starter home page), a copy of the basic theme, a copy of the system element library (`layouts/shortcodes/*` + `editor/elements/*`), page-type sidecars, `harness.yaml` (site title, language list of one, Hugo version pin, defaults), a CI workflow (Forgejo and GitHub variants: checkout → pinned hugo build → commented-out deploy step with rsync/pages examples), and `.gitignore` entries (`.harness/`). Scaffolded copies are developer-owned from then on — no update mechanism by design. ## Acceptance criteria - [ ] `harness init` then `harness serve` yields a working editable site with the basic theme and full element library, no manual steps - [ ] Generated CI workflow runs green on a fresh Forgejo repo (build succeeds; deploy step present but commented, with clear instructions) - [ ] Workflow uses the Hugo version pinned in `harness.yaml` - [ ] `init` refuses to overwrite existing files and reports what it would touch - [ ] Everything scaffolded is committed-ready: no secrets, no absolute paths, `.harness/` ignored - [ ] Sidecar files carry the `version:` field for forward compatibility ## Blocked by - #15
dominik.polakovics commented 2026-07-12 02:19:08 +02:00
Author
Owner
Copy link

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Add a harness init command that bootstraps a complete, immediately editable site in one command: Hugo skeleton with a starter home page, developer-owned copies of the basic theme and the system element library, page-type sidecars, harness.yaml, Forgejo and GitHub CI workflow variants, and a .gitignore — refusing to overwrite anything that already exists.

Dependency note: this issue is hard-blocked by #15 (basic theme), which is itself blocked by #14 (system element library) — init scaffolds copies of both, so they must exist and be stable first. The scheduler handles ordering. The issue body's docs/DECISIONS.md D15, D21, D25, D26 references point at a file that is not committed — this brief is self-contained.

Current behavior:
The harness CLI has a single command, serve, which requires an already-existing Hugo site and refuses directories without a Hugo config file. The theme (#15), the element library (#14), and the editor sidecars exist only inside this repository's sample site. A user who wants a new deckle-managed site must hand-assemble the Hugo config, content tree, theme, shortcode templates, sidecars, and CI — there is no bootstrap.

Desired behavior:

One command, working site. harness init, run in an empty directory (or a fresh git repository containing nothing but VCS metadata), scaffolds everything such that harness serve immediately afterwards yields a working, fully editable site with no manual steps:

  • A minimal hugo.toml wired to the scaffolded theme.
  • content/<lang>/ with a starter home page that renders and is editable through the harness (the language code comes from the language list in harness.yaml).
  • A full copy of the basic theme from #15 under themes/.
  • A full copy of the system element library from #14: every shortcode template plus its editor/elements/*.yaml sidecar.
  • Page-type sidecars: the editor-side declarations of the page types the theme supports (analogous to element sidecars; consumed later by page management, #9).
  • harness.yaml: the harness's own config — site title, a language list with exactly one entry, a pinned Hugo version, and sensible defaults.
  • CI workflows in both Forgejo and GitHub variants, each: checkout → Hugo build using the pinned version → a deploy step that is present but commented out, with rsync and pages examples and clear instructions for enabling it.
  • .gitignore containing .harness/ (the harness's local runtime/state directory).

The command must be usable non-interactively (defaults or flags for the site title and language), so it can run in scripts and tests.

Never overwrites. If any file init would create already exists, it refuses: it modifies no existing file, reports the paths it would touch (making the conflicts obvious), and exits nonzero. Aborting without writing anything is the cleanest acceptable behavior.

Developer-owned copies. The scaffolded theme and element library are plain-file copies, owned by the site developer from the moment they are written. There is deliberately no update mechanism — no version tracking against the harness binary, no "sync from upstream", no warnings about divergence. Document this ownership in the scaffold (the theme's "fork me" guide from #15 already carries the spirit).

Forward compatibility. Every scaffolded sidecar — element sidecars and page-type sidecars — carries a version: field so future harness versions can recognize and migrate old schemas.

Committed-ready. Everything scaffolded is safe to git add as-is: no secrets, no tokens, no absolute paths, no machine-specific content anywhere in the output.

Key interfaces:

  • The CLI grows init alongside serve, sharing the existing command dispatch; conflict refusal exits nonzero, success exits zero and prints what was created.
  • The scaffold sources (theme, element library, page-type sidecars, workflow templates, starter content) must be embedded in the harness binary — deckle is a single self-contained binary, so init works offline with no repository checkout. Keep the embedded scaffold in sync with the canonical theme/library by construction (embed the same files, don't maintain a second copy by hand).
  • The harness.yaml shape (site title, single-entry language list, Hugo version pin, defaults) becomes the harness's config contract — later issues read it (the version pin is enforced/auto-downloaded in #5). Keep its Go type in a package importable without the server.
  • The generated workflows read no secrets and reference the Hugo version literally as pinned at init time; live enforcement of the pin is #5's job.

Acceptance criteria:

  • In an empty directory, harness init followed by harness serve yields a working editable site — basic theme, full element library, starter home page — with no manual steps
  • harness.yaml is scaffolded with site title, a single-language list, a pinned Hugo version, and defaults
  • Both Forgejo and GitHub workflow variants are scaffolded; each builds with the Hugo version pinned in harness.yaml and carries a commented-out deploy step with clear rsync/pages instructions
  • The generated workflow runs green on a fresh Forgejo repository (build succeeds with deploy still commented out)
  • init refuses to overwrite: with any conflicting file present it modifies nothing, reports what it would touch, and exits nonzero
  • Everything scaffolded is committed-ready — no secrets, no absolute paths — and .gitignore contains .harness/
  • Every scaffolded sidecar (element and page-type) carries a version: field
  • The scaffolded theme and element library are plain developer-owned copies; no update mechanism exists and the scaffold's docs say so
  • The scaffold flow is covered by tests (init into a temp dir, verify layout, verify conflict refusal)

Out of scope:

  • Hugo auto-download and runtime enforcement of the version pin (#5) — init only writes the pin
  • Git save / publish flows (#10) and CI status polling (#11) — the workflow files are static output here
  • Page management UI (#9) — page-type sidecars are scaffolded, their runtime use lives there
  • Multi-language sites — the language list has exactly one entry in this slice
  • Any scaffold update/upgrade/sync mechanism — excluded by design, not deferred
  • Changes to the theme (#15) or element library (#14) content beyond what embedding them requires
> *This was generated by AI during triage.* ## Agent Brief **Category:** enhancement **Summary:** Add a `harness init` command that bootstraps a complete, immediately editable site in one command: Hugo skeleton with a starter home page, developer-owned copies of the basic theme and the system element library, page-type sidecars, `harness.yaml`, Forgejo and GitHub CI workflow variants, and a `.gitignore` — refusing to overwrite anything that already exists. **Dependency note:** this issue is **hard-blocked by #15** (basic theme), which is itself blocked by #14 (system element library) — `init` scaffolds copies of both, so they must exist and be stable first. The scheduler handles ordering. The issue body's `docs/DECISIONS.md D15, D21, D25, D26` references point at a file that is not committed — this brief is self-contained. **Current behavior:** The harness CLI has a single command, `serve`, which requires an already-existing Hugo site and refuses directories without a Hugo config file. The theme (#15), the element library (#14), and the editor sidecars exist only inside this repository's sample site. A user who wants a new deckle-managed site must hand-assemble the Hugo config, content tree, theme, shortcode templates, sidecars, and CI — there is no bootstrap. **Desired behavior:** *One command, working site.* `harness init`, run in an empty directory (or a fresh git repository containing nothing but VCS metadata), scaffolds everything such that `harness serve` immediately afterwards yields a working, fully editable site with no manual steps: - A minimal `hugo.toml` wired to the scaffolded theme. - `content/<lang>/` with a starter home page that renders and is editable through the harness (the language code comes from the language list in `harness.yaml`). - A full copy of the basic theme from #15 under `themes/`. - A full copy of the system element library from #14: every shortcode template plus its `editor/elements/*.yaml` sidecar. - Page-type sidecars: the editor-side declarations of the page types the theme supports (analogous to element sidecars; consumed later by page management, #9). - `harness.yaml`: the harness's own config — site title, a language list with exactly one entry, a pinned Hugo version, and sensible defaults. - CI workflows in **both** Forgejo and GitHub variants, each: checkout → Hugo build using the pinned version → a deploy step that is present but commented out, with rsync and pages examples and clear instructions for enabling it. - `.gitignore` containing `.harness/` (the harness's local runtime/state directory). The command must be usable non-interactively (defaults or flags for the site title and language), so it can run in scripts and tests. *Never overwrites.* If any file `init` would create already exists, it refuses: it modifies no existing file, reports the paths it would touch (making the conflicts obvious), and exits nonzero. Aborting without writing anything is the cleanest acceptable behavior. *Developer-owned copies.* The scaffolded theme and element library are plain-file copies, owned by the site developer from the moment they are written. There is deliberately **no update mechanism** — no version tracking against the harness binary, no "sync from upstream", no warnings about divergence. Document this ownership in the scaffold (the theme's "fork me" guide from #15 already carries the spirit). *Forward compatibility.* Every scaffolded sidecar — element sidecars and page-type sidecars — carries a `version:` field so future harness versions can recognize and migrate old schemas. *Committed-ready.* Everything scaffolded is safe to `git add` as-is: no secrets, no tokens, no absolute paths, no machine-specific content anywhere in the output. **Key interfaces:** - The CLI grows `init` alongside `serve`, sharing the existing command dispatch; conflict refusal exits nonzero, success exits zero and prints what was created. - The scaffold sources (theme, element library, page-type sidecars, workflow templates, starter content) must be embedded in the harness binary — deckle is a single self-contained binary, so `init` works offline with no repository checkout. Keep the embedded scaffold in sync with the canonical theme/library by construction (embed the same files, don't maintain a second copy by hand). - The `harness.yaml` shape (site title, single-entry language list, Hugo version pin, defaults) becomes the harness's config contract — later issues read it (the version pin is enforced/auto-downloaded in #5). Keep its Go type in a package importable without the server. - The generated workflows read no secrets and reference the Hugo version literally as pinned at init time; live enforcement of the pin is #5's job. **Acceptance criteria:** - [ ] In an empty directory, `harness init` followed by `harness serve` yields a working editable site — basic theme, full element library, starter home page — with no manual steps - [ ] `harness.yaml` is scaffolded with site title, a single-language list, a pinned Hugo version, and defaults - [ ] Both Forgejo and GitHub workflow variants are scaffolded; each builds with the Hugo version pinned in `harness.yaml` and carries a commented-out deploy step with clear rsync/pages instructions - [ ] The generated workflow runs green on a fresh Forgejo repository (build succeeds with deploy still commented out) - [ ] `init` refuses to overwrite: with any conflicting file present it modifies nothing, reports what it would touch, and exits nonzero - [ ] Everything scaffolded is committed-ready — no secrets, no absolute paths — and `.gitignore` contains `.harness/` - [ ] Every scaffolded sidecar (element and page-type) carries a `version:` field - [ ] The scaffolded theme and element library are plain developer-owned copies; no update mechanism exists and the scaffold's docs say so - [ ] The scaffold flow is covered by tests (init into a temp dir, verify layout, verify conflict refusal) **Out of scope:** - Hugo auto-download and runtime enforcement of the version pin (#5) — `init` only writes the pin - Git save / publish flows (#10) and CI status polling (#11) — the workflow files are static output here - Page management UI (#9) — page-type sidecars are scaffolded, their runtime use lives there - Multi-language sites — the language list has exactly one entry in this slice - Any scaffold update/upgrade/sync mechanism — excluded by design, not deferred - Changes to the theme (#15) or element library (#14) content beyond what embedding them requires
dominik.polakovics commented 2026-07-13 01:07:42 +02:00
Author
Owner
Copy link

Closing as superseded: the maintainer has decided on a clean-slate reset of the project (issue #29, PR #30). The v1 implementation this issue builds on is being removed and the plan will be re-drawn from scratch; this spec is retired rather than actioned.

Closing as superseded: the maintainer has decided on a clean-slate reset of the project (issue #29, PR #30). The v1 implementation this issue builds on is being removed and the plan will be re-drawn from scratch; this spec is retired rather than actioned.
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#17
No description provided.