From 201973d741fce03f1c3228050443801d5f94f697 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Wed, 16 Sep 2026 13:03:39 +0200 Subject: [PATCH] docs(01-01): complete hello app kernel plan - Record task commits, deviations, and verification evidence --- .../01-01-SUMMARY.md | 160 ++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 .planning/phases/01-framework-kernel-foundation/01-01-SUMMARY.md diff --git a/.planning/phases/01-framework-kernel-foundation/01-01-SUMMARY.md b/.planning/phases/01-framework-kernel-foundation/01-01-SUMMARY.md new file mode 100644 index 0000000..49e80d7 --- /dev/null +++ b/.planning/phases/01-framework-kernel-foundation/01-01-SUMMARY.md @@ -0,0 +1,160 @@ +--- +phase: 01-framework-kernel-foundation +plan: 01 +subsystem: kernel +tags: [go, cobra, koanf, plugins, cli, workspace] + +requires: [] +provides: + - Manifest-driven code generation and app build + - Required plugin interface and activation + - Shared cobra command construction + - Ordered hello plugin manifest +affects: [01-02, 01-03, 01-04] + +tech-stack: + added: + - github.com/spf13/cobra v1.10.2 + - github.com/knadh/koanf/v2 v2.3.6 + - github.com/knadh/koanf/parsers/yaml v1.1.1 + patterns: + - Compiled plugins self-register in init(); Activate orders by Requires() + - Shared bonfire.NewRoot used by tool and app + - summer.yaml ordered plugin list drives generated imports + +key-files: + created: + - party/registry.go + - backpack/app.go + - pact/capabilities.go + - compass/config.go + - bonfire/command.go + - bonfire/root.go + - internal/build/build.go + - cmd/summer/main.go + - examples/hello/summer.yaml + - examples/hello/main.go + - examples/hello/plugins.gen.go + - go.work + modified: + - go.mod + - go.sum + - .gitignore + +key-decisions: + - "Plugin lives in party with Register/Boot(*backpack.App); backpack does not import party" + - "bonfire.NewRoot takes []bonfire.Command, not a party registry" + - "HasConfig.ConfigFS() named to match Plan 02" + - "Example modules use local replace for unpublished git.golem15.com/golem15/summercms v0.0.0" + - "Pin toolchain go1.27.0 in go.work and every example go.mod" + +patterns-established: + - "Pattern: blank-import plugins.gen.go plus explicit PluginIDs slice; never use init order for lifecycle" + - "Pattern: summer build validates module paths, quotes imports, and execs go build with separate args" + +requirements-completed: [KERN-01, KERN-02, KERN-03, KERN-04, CLI-01] + +duration: 15min +completed: 2026-09-16 +--- + +# Phase 1 Plan 1: Hello App Kernel Summary + +**Compiled-plugin hello app boots via party.Activate and runs greeter:hello through a shared cobra/bonfire kernel, built by `summer build` from an ordered summer.yaml manifest** + +## Performance + +- **Duration:** 15 min +- **Started:** 2026-09-16T10:47:05Z +- **Completed:** 2026-09-16T11:02:48Z +- **Tasks:** 2 +- **Files modified:** 30 + +## Accomplishments + +- Framework kernel packages (`party`, `backpack`, `pact`, `compass`, `bonfire`) boot two compiled hello plugins with all Register calls before any Boot +- Permanent `examples/hello` app prints `app.name` from `config/app.yaml` via `greeter:hello` +- `cmd/summer build` generates stable `main.go`/`plugins.gen.go` from `summer.yaml` and produces `bin/hello` without importing example plugins + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Make the hello app boot and dispatch a plugin command** - `96a8d38` (feat) +2. **Task 2: Generate and build the hello app from its ordered manifest** - `2078f91` (feat) + +**Plan metadata:** pending (docs: complete plan) + +## Files Created/Modified + +- `party/registry.go` - Plugin interface, init registry, topo-sorted Activate +- `backpack/app.go` - App container holding compass config; no party import +- `pact/capabilities.go` - HasCommands, HasConfig; reserved KERN-03 names documented +- `compass/config.go` - Load config/
.yaml and String dot-path lookup +- `bonfire/command.go` / `bonfire/root.go` - Command values, Input/Output, shared cobra root +- `internal/build/build.go` - Manifest parse, validated codegen, `go build` via CommandContext +- `cmd/summer/main.go` - Framework tool entry using the same NewRoot +- `examples/hello/` - Workspace app, two plugin modules, summer.yaml, generated main +- `go.mod` / `go.work` - cobra, koanf, toolchain go1.27.0, four workspace modules + +## Decisions Made + +- Keep `Plugin` in `party` taking `*backpack.App` so `backpack` never imports `party` +- `bonfire.NewRoot(name, []Command, io.Writer)` is the single command kernel for tool and app +- Name `HasConfig.ConfigFS()` now so Plan 02 can load embedded plugin defaults without a rename +- Add `replace` lines in example `go.mod` files; D-04 allows go.work or local replace, and `v0.0.0` is not fetchable from the private module host +- Re-pin `toolchain go1.27.0` after `go mod tidy`, which drops a matching toolchain line + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 3 - Blocking] Local replace for unpublished framework module** +- **Found during:** Task 1 (module tidy) +- **Issue:** `go mod tidy` in example modules tried to fetch `git.golem15.com/golem15/summercms@v0.0.0` over HTTPS and failed (private host, no tag) +- **Fix:** Added `replace git.golem15.com/golem15/summercms => ` in hello/plugin go.mod files, which D-04 already allows +- **Files modified:** `examples/hello/go.mod`, `examples/hello/plugins/base/go.mod`, `examples/hello/plugins/greeter/go.mod` +- **Verification:** `go vet`/`go test` in root and hello +- **Committed in:** `96a8d38` (Task 1) + +**2. [Rule 2 - Missing Critical] Restore toolchain directive after tidy** +- **Found during:** Task 1 +- **Issue:** `go mod tidy` removed `toolchain go1.27.0` from go.mod files because the local toolchain already matched +- **Fix:** Re-added the directive to root and all example modules plus `go.work` (D-05) +- **Files modified:** `go.mod`, `examples/hello/go.mod`, plugin go.mod files, `go.work` +- **Verification:** files contain `toolchain go1.27.0` +- **Committed in:** `96a8d38` (Task 1) + +--- + +**Total deviations:** 2 auto-fixed (1 blocking, 1 missing critical) +**Impact on plan:** Required for a buildable workspace of unpublished modules and the D-05 toolchain pin. No scope creep. + +## Issues Encountered + +- Spawn HEAD was `master` on this isolated Grok clone (`.git` is a directory, not a linked worktree). Created `worktree-agent-01a0a9d2` from `552cadb` without rewriting `refs/heads/master`. Commits live on the agent branch. + +## Authentication Gates + +None. + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness + +Ready for `01-02-PLAN.md` (layered compass config, optional plugin composition, services, typed events). Hello already boots and `summer build` is the shared generate-and-compile function later plans extend. + +## Self-Check: PASSED + +- Created kernel, hello, and build files exist on disk +- Commits `96a8d38` and `2078f91` exist +- Root and hello `go vet ./...` and `go test ./...` passed +- Two `summer build` runs left `main.go`/`plugins.gen.go` hashes unchanged; `./bin/hello greeter:hello` printed `hello-app` +- `go list -deps ./cmd/summer` has no hello plugin packages +- STATE.md and ROADMAP.md were not updated in this worktree + +--- +*Phase: 01-framework-kernel-foundation* +*Completed: 2026-09-16*