Merge pull request #33 from LAA-Software-Engineering/issue/1-go-module-skeleton

leo-aa88 · web-flow · commit 7c63fc89f992 · 2026-04-11T00:27:37.000-03:00
feat: Go module skeleton, CI, and issue #1 foundations
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1,4 @@
+# LF everywhere for Go so gofmt -l matches Linux/macOS on Windows CI and locally.
+*.go text eol=lf
+go.mod text eol=lf
+go.sum text eol=lf
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,94 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - "Makefile"
+      - "**/*.md"
+  pull_request:
+    paths-ignore:
+      - "Makefile"
+      - "**/*.md"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-test:
+    name: Go ${{ matrix.go }} — ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        go: ["1.22.x"]
+        include:
+          # Extra Go patch line on Linux to catch regressions on newer toolchain.
+          - os: ubuntu-latest
+            go: "1.23.x"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go }}
+          cache: true
+
+      - name: Download modules
+        run: go mod download
+
+      - name: Verify go.sum
+        run: go mod verify
+
+      - name: Check formatting
+        shell: bash
+        run: |
+          set -euo pipefail
+          out="$(gofmt -l .)"
+          if [[ -n "$out" ]]; then
+            echo "::error::Run gofmt on:"
+            echo "$out"
+            exit 1
+          fi
+
+      - name: Go vet
+        run: go vet ./...
+
+      - name: Build agentctl
+        run: go build -v -o agentctl${{ runner.os == 'Windows' && '.exe' || '' }} ./cmd/agentctl
+
+      # Use bash on Windows: PowerShell misparses -coverprofile=coverage.out
+      # (".out" becomes a separate argument / package path).
+      - name: Unit tests
+        shell: bash
+        run: |
+          go test -v \
+            -race \
+            -count=1 \
+            -shuffle=on \
+            -timeout=10m \
+            -covermode=atomic \
+            -coverprofile=coverage.out \
+            ./...
+
+      - name: Coverage summary
+        if: runner.os == 'Linux'
+        run: go tool cover -func=coverage.out | tail -n1
+
+      - name: Upload coverage artifact
+        if: runner.os == 'Linux' && matrix.go == '1.22.x'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-linux-go122
+          path: coverage.out
+          if-no-files-found: error
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,9 @@
 # If you prefer the allow list template instead of the deny list, see community template:
 # https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
 #
+# Local build output (see Makefile)
+bin/
+
 # Binaries for programs and plugins
 *.exe
 *.exe~
diff --git a/Makefile b/Makefile
@@ -0,0 +1,8 @@
+.PHONY: test build
+
+test:
+	go test ./...
+
+build:
+	mkdir -p bin
+	go build -o bin/agentctl ./cmd/agentctl
diff --git a/cmd/agentctl/main.go b/cmd/agentctl/main.go
@@ -0,0 +1,15 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/app"
+)
+
+func main() {
+	if err := app.New().Run(); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
diff --git a/go.mod b/go.mod
@@ -0,0 +1,10 @@
+module github.com/LAA-Software-Engineering/agentic-control-plane
+
+go 1.22
+
+require github.com/spf13/cobra v1.8.1
+
+require (
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/spf13/pflag v1.0.5 // indirect
+)
diff --git a/go.sum b/go.sum
@@ -0,0 +1,10 @@
+github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/spf13/cobra v1.8.1 h1:e5/vxKd/rZsfSJMUX1agtjeTDf+qv1/JdBF8gg5k9ZM=
+github.com/spf13/cobra v1.8.1/go.mod h1:wHxEcudfqmLYa8iTfL+OuZPbBZkmvliBWKIezN3kD9Y=
+github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
+github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/internal/app/app.go b/internal/app/app.go
@@ -0,0 +1,15 @@
+package app
+
+// App is the composition root for agentctl. Subsystems (stores, planner,
+// runtime) will be assembled here in later phases.
+type App struct{}
+
+// New constructs an application instance with default wiring.
+func New() *App {
+	return &App{}
+}
+
+// Run starts the CLI and blocks until the root command finishes.
+func (a *App) Run() error {
+	return runCLI()
+}
diff --git a/internal/app/wiring.go b/internal/app/wiring.go
@@ -0,0 +1,7 @@
+package app
+
+import "github.com/LAA-Software-Engineering/agentic-control-plane/internal/cli"
+
+func runCLI() error {
+	return cli.Execute()
+}
diff --git a/internal/apply/doc.go b/internal/apply/doc.go
@@ -0,0 +1,2 @@
+// Package apply applies plans to control-plane and runtime state.
+package apply
diff --git a/internal/cli/root.go b/internal/cli/root.go
@@ -0,0 +1,38 @@
+package cli
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+)
+
+// Version is set at link time; default for dev builds.
+var Version = "0.0.0-dev"
+
+// Execute runs the root command.
+func Execute() error {
+	return newRootCmd().Execute()
+}
+
+func newRootCmd() *cobra.Command {
+	root := &cobra.Command{
+		Use:   "agentctl",
+		Short: "Declarative control plane for agent systems",
+		Long:  "agentctl validates, plans, applies, and runs declarative agent systems defined as YAML.",
+		Run: func(cmd *cobra.Command, args []string) {
+			_ = cmd.Help()
+		},
+	}
+	root.AddCommand(newVersionCmd())
+	return root
+}
+
+func newVersionCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "version",
+		Short: "Print version information",
+		Run: func(cmd *cobra.Command, args []string) {
+			fmt.Println(Version)
+		},
+	}
+}
diff --git a/internal/engine/doc.go b/internal/engine/doc.go
@@ -0,0 +1,2 @@
+// Package engine orchestrates workflow execution, steps, and interpolation.
+package engine
diff --git a/internal/models/doc.go b/internal/models/doc.go
@@ -0,0 +1,2 @@
+// Package models abstracts model providers and client interfaces.
+package models
diff --git a/internal/plan/doc.go b/internal/plan/doc.go
@@ -0,0 +1,2 @@
+// Package plan computes desired vs current state diffs and risk summaries.
+package plan
diff --git a/internal/policy/doc.go b/internal/policy/doc.go
@@ -0,0 +1,2 @@
+// Package policy evaluates permissions, budgets, and approval rules.
+package policy
diff --git a/internal/project/doc.go b/internal/project/doc.go
@@ -0,0 +1,2 @@
+// Package project loads project directories, merges resources, and resolves imports.
+package project
diff --git a/internal/render/doc.go b/internal/render/doc.go
@@ -0,0 +1,2 @@
+// Package render formats output as YAML, JSON, or tables.
+package render
diff --git a/internal/runtime/doc.go b/internal/runtime/doc.go
@@ -0,0 +1,2 @@
+// Package runtime abstracts local and remote execution targets.
+package runtime
diff --git a/internal/spec/doc.go b/internal/spec/doc.go
@@ -0,0 +1,2 @@
+// Package spec parses YAML resources, types, defaults, and validation.
+package spec
diff --git a/internal/state/doc.go b/internal/state/doc.go
@@ -0,0 +1,2 @@
+// Package state stores deployment state and runtime metadata.
+package state
diff --git a/internal/tools/doc.go b/internal/tools/doc.go
@@ -0,0 +1,2 @@
+// Package tools defines tool registries and integrations (MCP, HTTP, native).
+package tools
diff --git a/internal/trace/doc.go b/internal/trace/doc.go
@@ -0,0 +1,2 @@
+// Package trace records structured execution events for logs and debugging.
+package trace
diff --git a/internal/util/doc.go b/internal/util/doc.go
@@ -0,0 +1,2 @@
+// Package util holds small shared helpers (fs, ids, errors, etc.).
+package util
diff --git a/scripts/test.sh b/scripts/test.sh
@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")/.."
+go test ./...

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+// Package apply applies plans to control-plane and runtime state.`
	`2`	`+package apply`