From d2ae235628aa93ce3d99bd5efc36634ded3b4db5 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sun, 4 Oct 2026 01:20:33 +1000 Subject: [PATCH] refactor(archieplaybooks): fold archie-playbooks into archied playbooks lint|serve --- .github/workflows/deploy.yml | 6 +-- RELEASING.md | 6 +-- Taskfile.yml | 2 +- cmd/archied/main.go | 4 ++ deployments/INSTRUCTIONS.md | 15 +++---- install.sh | 6 +-- .../app/archieplaybooks/command.go | 45 +++++-------------- internal/app/archieplaybooks/lint.go | 2 +- internal/app/archieplaybooks/serve.go | 4 +- scripts/archie-update-install | 5 +-- tools/release.sh | 3 +- 11 files changed, 38 insertions(+), 60 deletions(-) rename cmd/archie-playbooks/main.go => internal/app/archieplaybooks/command.go (58%) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index b1c0264e9..65dbc3dee 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -273,7 +273,7 @@ jobs: cache-to: type=gha,mode=max,scope=archie-agent # Packages every host-run binary (archied, archie-gateway, - # archie-state-store, archie-ui, archie-messaging, archie-playbooks) as a + # archie-state-store, archie-ui, archie-messaging) as a # linux/amd64 zip for a # non-Docker install. Independent of build-and-push: it never touches the # archied/archie-agent image jobs, and a gateway-only release (no @@ -329,7 +329,7 @@ jobs: # list and the copy list below stop matching the commands in cmd/. ldflags="-X github.com/samcharles93/archie-core/internal/installtype.buildType=binary -X github.com/samcharles93/archie-core/internal/buildinfo.Version=${{ steps.version.outputs.version }} -X github.com/samcharles93/archie-core/internal/buildinfo.Runtime=${{ steps.version.outputs.version }}" mkdir -p dist - for cmd in archied archie-gateway archie-state-store archie-ui archie-messaging archie-playbooks; do + for cmd in archied archie-gateway archie-state-store archie-ui archie-messaging; do go build -ldflags "$ldflags" -o "dist/$cmd" "./cmd/$cmd" done @@ -339,7 +339,7 @@ jobs: set -e name="archie-core-archied-v${{ steps.version.outputs.version }}-linux-amd64" mkdir -p "$name" - cp dist/archied dist/archie-gateway dist/archie-state-store dist/archie-ui dist/archie-messaging dist/archie-playbooks "$name/" + cp dist/archied dist/archie-gateway dist/archie-state-store dist/archie-ui dist/archie-messaging "$name/" cp deployments/INSTRUCTIONS.md CHANGELOG.md "$name/" # README.md doesn't exist yet in this repo; include it once it does # rather than fail the release on its absence. diff --git a/RELEASING.md b/RELEASING.md index 5cd3ffa73..3c3c53cd0 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -6,8 +6,8 @@ version covering whatever changed; the components' entries are labelled sections inside it (`### archied`, `### archie-agent`), not separate numbers or separate pages. -The host bundle ships six processes — `archied`, `archie-gateway`, -`archie-state-store`, `archie-ui`, `archie-messaging`, `archie-playbooks` — and +The host bundle ships five processes (`archied`, `archie-gateway`, +`archie-state-store`, `archie-ui`, `archie-messaging`), and one version covers all of them. `archie-agent`, the per-task sandboxed runtime, ships as a container image and its changes are the `## [version]` release's `### archie-agent` section. @@ -105,7 +105,7 @@ Tagging one version produces, from a single `deploy` run: follows `:edge`. - **A GitHub Release with a distribution zip** — `dist-zip` builds every process the reference deployment runs (`archied`, `archie-gateway`, - `archie-state-store`, `archie-ui`, `archie-messaging`, `archie-playbooks`) for + `archie-state-store`, `archie-ui`, `archie-messaging`) for linux/amd64, packs them with `deployments/INSTRUCTIONS.md` and `CHANGELOG.md`, and attaches the zip to the Release. The Release body is that version's `## [version]` section of `CHANGELOG.md`. diff --git a/Taskfile.yml b/Taskfile.yml index dde4fcdde..260690361 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -99,7 +99,7 @@ tasks: lint:playbooks: desc: Validate playbook bindings cmds: - - go run ./cmd/archie-playbooks lint -dir ./playbooks + - go run ./cmd/archied playbooks lint -dir ./playbooks vuln: desc: Scan for known vulnerabilities (requires network access) diff --git a/cmd/archied/main.go b/cmd/archied/main.go index a12379d30..f6243ce03 100644 --- a/cmd/archied/main.go +++ b/cmd/archied/main.go @@ -5,6 +5,7 @@ import ( "os" "github.com/samcharles93/archie-core/internal/app/archied" + "github.com/samcharles93/archie-core/internal/app/archieplaybooks" ) func main() { @@ -15,5 +16,8 @@ func main() { if archied.IsSetupArgs(args) { os.Exit(archied.RunSetup(args[1:], os.Stdin, os.Stdout, os.Stderr)) } + if len(args) > 0 && args[0] == "playbooks" { + os.Exit(archieplaybooks.Run(args[1:], os.Stderr)) + } os.Exit(archied.Run()) } diff --git a/deployments/INSTRUCTIONS.md b/deployments/INSTRUCTIONS.md index 95f07fce0..623824d60 100644 --- a/deployments/INSTRUCTIONS.md +++ b/deployments/INSTRUCTIONS.md @@ -1,6 +1,6 @@ # Running this distribution -This archive contains six linux/amd64 binaries: +This archive contains five linux/amd64 binaries: Each service owns its data and reaches the others only through their gRPC contracts (or NATS, for task actions): @@ -13,8 +13,8 @@ contracts (or NATS, for task actions): | `archie-messaging` | the Telegram, email and webhook channel connections | Gateway; State Store for channel settings | | `archie-ui` | the dashboard and the webhook capture receiver | Gateway; State Store | -- **`archie-playbooks`** is a CLI that lints playbook binding YAML before it - reaches `archied`. +`archied playbooks lint` checks playbook binding YAML before it reaches the +daemon, and `archied playbooks serve` is its language server for editors. Without `archie-messaging` the channels are simply absent, so it needs a unit of its own (`deployments/systemd-user-service.md`). @@ -69,15 +69,15 @@ as a host binary. Pull it from GHCR: `ghcr.io/samcharles93/archie-agent`. ## Verifying an install -`archie-playbooks lint -dir ` validates playbook binding YAML +`archied playbooks lint -dir ` validates playbook binding YAML against the same schema `archied` loads at startup — run it against your playbooks directory before pointing `archied` at it. ## Version This archive's binaries are built from the `archied` release tag in its -filename; `archie-ui`, `archie-gateway`, `archie-state-store`, -`archie-messaging` and `archie-playbooks` ship at that same version rather than +filename; `archie-ui`, `archie-gateway`, `archie-state-store` and +`archie-messaging` ship at that same version rather than being independently tagged (see `RELEASING.md` in the source repository for why only `archied` and `archie-agent` are independently versioned). @@ -85,5 +85,4 @@ only `archied` and `archie-agent` are independently versioned). `archied` are services that must be running and addressable; `archie-messaging` carries the Telegram, email and webhook channels since the v1.30.0 extraction, so an install (or an upgrade across v1.30.0) needs its unit as well -- see -`deployments/systemd-user-service.md`. `archie-playbooks` is a CLI and runs on -demand. +`deployments/systemd-user-service.md`. diff --git a/install.sh b/install.sh index 673364eaf..950fdff40 100755 --- a/install.sh +++ b/install.sh @@ -193,12 +193,12 @@ echo "==> Building native archie binaries..." # webhook channels dead with no error anywhere. This list, # the zip's two lists and the two in scripts/archie-update-install must agree; # TestDistZipShipsEveryHostCommand fails when they do not. - for cmd in archied archie-gateway archie-state-store archie-ui archie-messaging archie-playbooks; do + for cmd in archied archie-gateway archie-state-store archie-ui archie-messaging; do go build -ldflags "${LDFLAGS}" -o "${ARCHIE_BIN_DIR}/${cmd}" "./cmd/${cmd}" done install -m755 "${SRC_DIR}/scripts/archie-update-install" "${ARCHIE_BIN_DIR}/archie-update-install" ) -echo " Installed archied, archie-gateway, archie-state-store, archie-ui, archie-messaging, archie-playbooks and updater to ${ARCHIE_BIN_DIR}/" +echo " Installed archied, archie-gateway, archie-state-store, archie-ui, archie-messaging and updater to ${ARCHIE_BIN_DIR}/" # 5. Interactive Configuration: Forge & LLM Provider Setup if [ ! -f "${ENV_FILE}" ]; then @@ -563,7 +563,7 @@ echo " ✓ Archie Core Installation Complete!" echo "============================================================" echo "" echo "Installation Details:" -echo " - Binaries : ${ARCHIE_BIN_DIR}/{archied,archie-state-store,archie-gateway,archie-ui,archie-messaging,archie-playbooks}" +echo " - Binaries : ${ARCHIE_BIN_DIR}/{archied,archie-state-store,archie-gateway,archie-ui,archie-messaging}" echo " - Agent image: ghcr.io/samcharles93/archie-agent:latest" echo " - Config : ${ARCHIE_CONFIG_DIR}/config.toml" echo " - Secrets : ${ENV_FILE}" diff --git a/cmd/archie-playbooks/main.go b/internal/app/archieplaybooks/command.go similarity index 58% rename from cmd/archie-playbooks/main.go rename to internal/app/archieplaybooks/command.go index 7ea813be3..5699dedda 100644 --- a/cmd/archie-playbooks/main.go +++ b/internal/app/archieplaybooks/command.go @@ -1,15 +1,4 @@ -// Command archie-playbooks is the standalone playbook tool for archie-core, -// shaped like gopls: one binary, multiple invocation modes. It validates -// playbook YAML binding files against the same schema the daemon loads at -// startup, so a pre-merge check can never disagree with runtime validation. -// -// It ships two modes: lint for CI, and serve, a language server that -// publishes the same findings as editor diagnostics. Both call the loaders -// the daemon runs. -// -// A finding about one binding key leads with the key's file:line; a file -// that does not parse is reported by path with the YAML parser's message. -package main +package archieplaybooks import ( "context" @@ -19,31 +8,19 @@ import ( "os" "os/signal" "syscall" - - "github.com/samcharles93/archie-core/internal/app/archieplaybooks" - "github.com/samcharles93/archie-core/internal/buildinfo" ) -func main() { - os.Exit(run(os.Args[1:], os.Stderr)) -} - -func run(args []string, stderr io.Writer) int { - // Subcommand table from day one (gopls shape): each mode owns its flag - // set and returns an exit code. Adding serve/lsp later is a new entry - // here, not a restructuring. +// Run runs `archied playbooks `: lint for CI, serve for editors. +// Both use the loaders the daemon runs, so a check here cannot disagree with +// what the daemon accepts at startup. +func Run(args []string, stderr io.Writer) int { commands := map[string]func([]string, io.Writer) int{ "lint": runLint, "serve": runServe, } - if len(args) > 0 && (args[0] == "-version" || args[0] == "--version") { - buildinfo.Print("archie-playbooks") - return 0 - } - if len(args) == 0 { - fmt.Fprintln(stderr, "usage: archie-playbooks [args]") + fmt.Fprintln(stderr, "usage: archied playbooks [args]") fmt.Fprintln(stderr, "commands:") for name := range commands { fmt.Fprintf(stderr, " %s\n", name) @@ -53,7 +30,7 @@ func run(args []string, stderr io.Writer) int { cmd, ok := commands[args[0]] if !ok { - fmt.Fprintf(stderr, "archie-playbooks: unknown command %q\n", args[0]) + fmt.Fprintf(stderr, "archied playbooks: unknown command %q\n", args[0]) return 2 } return cmd(args[1:], stderr) @@ -63,7 +40,7 @@ func run(args []string, stderr io.Writer) int { // directory (-eda-dir) against the loaders the daemon runs at startup. // Exit codes: 0 clean, 1 findings, 2 usage error. func runLint(args []string, stderr io.Writer) int { - flags := flag.NewFlagSet("archie-playbooks lint", flag.ContinueOnError) + flags := flag.NewFlagSet("archied playbooks lint", flag.ContinueOnError) flags.SetOutput(stderr) var dirs multiFlag flags.Var(&dirs, "dir", "routing binding directory to lint (repeatable)") @@ -79,10 +56,10 @@ func runLint(args []string, stderr io.Writer) int { code := 0 if len(dirs) > 0 { - code = max(code, archieplaybooks.Lint(dirs, stderr).ExitCode) + code = max(code, Lint(dirs, stderr).ExitCode) } if *edaDir != "" { - code = max(code, archieplaybooks.LintEDA(*edaDir, stderr).ExitCode) + code = max(code, LintEDA(*edaDir, stderr).ExitCode) } return code } @@ -96,7 +73,7 @@ func runServe(args []string, stderr io.Writer) int { } ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() - if err := archieplaybooks.Serve(ctx, stdio{}); err != nil { + if err := Serve(ctx, stdio{}); err != nil { fmt.Fprintln(stderr, "serve:", err) return 1 } diff --git a/internal/app/archieplaybooks/lint.go b/internal/app/archieplaybooks/lint.go index e29014922..048fb3a31 100644 --- a/internal/app/archieplaybooks/lint.go +++ b/internal/app/archieplaybooks/lint.go @@ -1,4 +1,4 @@ -// Package archieplaybooks implements the archie-playbooks CLI, using the +// Package archieplaybooks implements the `archied playbooks` command, using the // daemon's own playbook loaders. package archieplaybooks diff --git a/internal/app/archieplaybooks/serve.go b/internal/app/archieplaybooks/serve.go index 152ed3669..5fa44bb38 100644 --- a/internal/app/archieplaybooks/serve.go +++ b/internal/app/archieplaybooks/serve.go @@ -54,7 +54,7 @@ func (s *server) Initialize(context.Context, *protocol.InitializeParams) (*proto Save: protocol.Boolean(true), }, }, - ServerInfo: protocol.ServerInfo{Name: "archie-playbooks"}, + ServerInfo: protocol.ServerInfo{Name: "archied-playbooks"}, }, nil } @@ -101,7 +101,7 @@ func diagnose(u uri.URI) *protocol.PublishDiagnosticsParams { out.Diagnostics = append(out.Diagnostics, protocol.Diagnostic{ Range: protocol.Range{Start: protocol.Position{Line: line}, End: protocol.Position{Line: line + 1}}, Severity: protocol.DiagnosticSeverityError, - Source: protocol.NewOptional("archie-playbooks"), + Source: protocol.NewOptional("archied-playbooks"), Message: protocol.String(finding), }) } diff --git a/scripts/archie-update-install b/scripts/archie-update-install index a002b432a..be82e669c 100755 --- a/scripts/archie-update-install +++ b/scripts/archie-update-install @@ -75,8 +75,7 @@ STATE_STORE_TARGET="${ARCHIE_UPDATE_STATE_STORE_TARGET:-$(configured_state_store # The archied release is a set of processes, not one binary. Listed in start # order: the State Store owns archie.db and every other process dials it, the # Gateway serves the chat contract archied, the UI and the Messaging Service -# dial, and each comes up before its consumers. archie-playbooks is a CLI, so -# it is installed but never restarted. deployments/systemd-user-service.md is +# dial, and each comes up before its consumers. deployments/systemd-user-service.md is # the reference deployment; installing archied alone leaves the rest on the # previous release, which is why a 1.23.0 update failed its health check # (archie-core-hbqk). @@ -87,7 +86,7 @@ STATE_STORE_TARGET="${ARCHIE_UPDATE_STATE_STORE_TARGET:-$(configured_state_store # (archie-core-1c01). TestDistZipShipsEveryHostCommand fails if this # list and GATEWAY_BINARIES stop covering the commands the release zip ships. GATEWAY_SERVICES="archie-state-store archie-gateway archied archie-ui archie-messaging" -GATEWAY_BINARIES="$GATEWAY_SERVICES archie-playbooks" +GATEWAY_BINARIES="$GATEWAY_SERVICES" PREV_GW="${ARCHIE_UPDATE_DAEMON_PREVIOUS:-}" PREV_RT="${ARCHIE_UPDATE_AGENT_PREVIOUS:-}" diff --git a/tools/release.sh b/tools/release.sh index 5d980c05c..60ce81f22 100755 --- a/tools/release.sh +++ b/tools/release.sh @@ -82,14 +82,13 @@ archied_dirs() { component_dirs ./cmd/archied # Every process the host bundles ships in this release, so a change to a # package only one of them links still lands in the changelog. Without - # these, messaging-only, state-store-only and playbooks-only packages closed + # these, messaging-only and state-store-only packages closed # over no component and the release silently omitted them (the telegram fence # fix was dropped this way). The gap is pre-existing -- the old two-file # closures named only cmd/archied and cmd/archie-agent -- but it grew teeth # when the Messaging Service was severed from archied in 1.35.0. component_dirs ./cmd/archie-messaging component_dirs ./cmd/archie-state-store - component_dirs ./cmd/archie-playbooks component_dirs ./cmd/archie-ui printf '%s\n' "cmd/archied" "Dockerfile.archied" "cmd/archie-ui" "internal/app/archieui" \ "Taskfile.yml" ".github/workflows/deploy.yml" "install.sh" \