Initial commit: launchd MVP (builder, transfer, systemd, migrate, health, tests, Makefile, README)

Author: saadhtiwana

.gitignore

@@ -0,0 +1,24 @@
+# Binaries
+bin/
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Build artifacts
+build/
+/dist/
+*.out
+*.test
+
+# Go
+vendor/
+coverage.out
+
+# IDE
+.vscode/
+.idea/
+*.iml
+.DS_Store
+Thumbs.db

Makefile

@@ -0,0 +1,20 @@
+SHELL := /bin/bash
+
+APP := launchd
+PKG := ./...
+
+.PHONY: all build test lint clean
+
+all: build
+
+build:
+	mkdir -p bin
+	go build -o bin/$(APP) ./cmd/launchd
+
+
+test:
+	go test -race -cover $(PKG)
+
+clean:
+	rm -rf bin
+	rm -f coverage.out

README.md

@@ -0,0 +1,65 @@
+# launchd
+Deterministic deploy orchestrator for single-binary Go services anchored to Linux systemd. launchd operationalizes a minimal, auditable deploy surface by composing battle-tested primitives: the resident Go toolchain for compilation, OpenSSH for transport and privileged control, systemd for service lifecycle, an optional migrator for schema evolution, and an HTTP health contract for liveness attestation. The objective function is predictability under duress, not novelty; the codebase is dependency-thin and tuned for reproducible behavior across heterogeneous fleet baselines.
+
+## Conceptual Premise
+
+The dominant substrate for “small-but-critical” services is a single daemon under systemd supervision. For these domains, heavyweight CI/CD machinery introduces variance without proportional utility. launchd prefers an austere convergence model: converge a binary onto a machine, converge a unit into systemd, converge the database state via idempotent migrations, and converge process readiness via health probes. Each convergence step is a transparent syscall to a canonical tool, yielding failure surfaces that are legible to any seasoned operator.
+
+Assumptions:
+- A Go main package constitutes the service.
+- SSH reachability with privilege elevation exists to manage units.
+- The service exposes `/health` on a chosen TCP port.
+
+## MVP Scope
+
+- CLI: `launchd deploy --host <ip> --user <ssh-user> --app ./path/to/app --port <port> [--timeout <dur>]`.
+- Pipeline: Compile ➝ Transfer ➝ systemd Provision ➝ Migrate (optional) ➝ Health Gate.
+- Properties: idempotent (safe re-entrance), deterministic (explicit tooling), strict error surfacing, and minimal environmental preconditions (Go + OpenSSH).
+
+### Stage Semantics
+- Compile: `go build -o /tmp/<app>` using the resident toolchain; no hermetic wrapper.
+- Transfer: `scp` to `/usr/local/bin/<app>` after ensuring parent directory ownership is sane.
+- systemd: materialize a unit, `daemon-reload`, `enable`, `restart`—idempotent operations.
+- Migrations: opportunistic `migrate up` if a migrator exists on the target PATH.
+- Health: poll `http://<host>:<port>/health` until success or deadline expiry.
+
+## Example Usage
+
+```bash
+launchd deploy --host 203.0.113.10 --user ubuntu --app ./examples/hello --port 8080 --timeout 60s
+```
+
+On completion, the service is registered as `<app>.service`, executes `/usr/local/bin/<app> --port=<port>`, and is enabled for boot.
+
+## Design Guarantees
+
+- Determinism: all side effects mediated by explicit tools (`go`, `scp`, `ssh`, `systemctl`).
+- Idempotence: repeated invocations converge; non-destructive `enable`, guarded migrations.
+- Failure Locality: stages short-circuit with precise logging; no ambiguous partial states.
+- Observability: microsecond timestamps and stage banners designed for operator cognition.
+- Minimality: no bespoke protocol layers; everything deferential to Unix contracts.
+
+## Future Roadmap
+
+- Artifact integrity: checksums, content-addressed remote layout, atomic swaps.
+- Principle of Least Privilege: dedicated system users, hardening of unit sandboxing.
+- Transport hardening: native SSH client (keyboard-interactive, agent-forwarding policies) while preserving zero-daemon requirements.
+- Policy engines: JSON-structured logs, exponential backoff policies, retry budgets.
+- Migration adapters: goose, golang-migrate, app-native hooks with transactional guards.
+
+## Organizational Context
+
+This codebase is authored under the goVerta collective and aspires to the production rigor expected of core-infra artifacts. The project is intentionally conservative in feature accretion, biasing toward operability, determinism, and testable failure semantics over breadth.
+
+## Contributors and Roles
+
+- Saad H. Tiwana — lead author, deployment pipeline, systemd strategy, reliability posture  
+  GitHub: https://github.com/saadhtiwana
+- Ahmad Mustafa — SSH/SCP transport hardening, testing harnesses  
+  GitHub: https://github.com/ahmadmustafa02
+- Majid Farooq Qureshi — QA and Toolsmith, Makefile/CI touchpoints, documentation QA  
+  GitHub: https://github.com/Majid-Farooq-Qureshi
+
+Saad authored the core code; Ahmad and Majid contributed engineering and QA functions across transport, tests, and docs.
+
+— saad and gang is who build this

cmd/launchd/main.go

@@ -0,0 +1,95 @@
+package main
+
+import (
+    "fmt"
+    "log"
+    "os"
+    "path/filepath"
+    "time"
+
+    "github.com/goVerta/launchd/internal/config"
+    "github.com/goVerta/launchd/internal/executil"
+    "github.com/goVerta/launchd/pkg/builder"
+    "github.com/goVerta/launchd/pkg/health"
+    "github.com/goVerta/launchd/pkg/migrate"
+    "github.com/goVerta/launchd/pkg/systemd"
+    "github.com/goVerta/launchd/pkg/transfer"
+)
+
+func main() {
+    log.SetFlags(log.LstdFlags | log.Lmicroseconds)
+    // saadhtiwana: deterministic, low-variance deploy orchestration entrypoint
+
+    if len(os.Args) < 2 {
+        usage()
+        os.Exit(1)
+    }
+
+    sub := os.Args[1]
+    if sub != "deploy" {
+        usage()
+        os.Exit(1)
+    }
+
+    cfg, err := config.ParseDeployFlags(os.Args[2:], config.DeployConfig{
+        Host:    "",
+        User:    os.Getenv("USER"),
+        AppPath: "",
+        Port:    8080,
+        Timeout: 60 * time.Second,
+    })
+    if err != nil { 
+        log.Fatalf("flag parse: %v", err) 
+    }
+    if cfg.Host == "" || cfg.User == "" || cfg.AppPath == "" {
+        log.Fatalf("missing required flags: --host, --user, --app")
+    }
+
+    exec := executil.New()
+
+    appName := filepath.Base(cfg.AppPath)
+    binOut := filepath.Join(os.TempDir(), appName)
+
+    log.Printf("[1/5] compile %s", cfg.AppPath)
+    // saadhtiwana: compile using resident toolchain for portability
+    if err := builder.Build(exec, cfg.AppPath, binOut); err != nil {
+        log.Fatalf("build failed: %v", err)
+    }
+
+    remoteBin := "/usr/local/bin/" + appName
+    log.Printf("[2/5] transfer to %s@%s:%s", cfg.User, cfg.Host, remoteBin)
+    // saadhtiwana: transfer artifact via OpenSSH primitives
+    if err := transfer.SCP(exec, binOut, cfg.User, cfg.Host, remoteBin); err != nil {
+        log.Fatalf("transfer failed: %v", err)
+    }
+
+    log.Printf("[3/5] systemd service setup for %s", appName)
+    svc := systemd.ServiceSpec{
+        Name:       appName,
+        ExecStart:  remoteBin + fmt.Sprintf(" --port=%d", cfg.Port),
+        User:       "root",
+        After:      []string{"network.target"},
+        Environment: map[string]string{},
+    }
+    if err := systemd.Setup(exec, cfg.User, cfg.Host, svc); err != nil {
+        log.Fatalf("systemd setup failed: %v", err)
+    }
+
+    log.Printf("[4/5] run migrations if available")
+    // saadhtiwana: optional DB convergence; presence-guarded
+    if err := migrate.RunIfPresent(exec, cfg.User, cfg.Host); err != nil {
+        log.Fatalf("migrations failed: %v", err)
+    }
+
+    log.Printf("[5/5] health check http://%s:%d/health", cfg.Host, cfg.Port)
+    // saadhtiwana: readiness gate to bound blast radius
+    if err := health.Wait(cfg.Host, cfg.Port, cfg.Timeout); err != nil {
+        log.Fatalf("unhealthy: %v", err)
+    }
+
+    log.Printf("deploy complete")
+}
+
+func usage() {
+    fmt.Println("usage: launchd deploy --host <ip> --user <ssh-user> --app ./path/to/app --port <port>")
+}

go.mod

@@ -0,0 +1,6 @@
+module github.com/goVerta/launchd
+
+go 1.22.0
+
+require (
+)

internal/config/config.go

@@ -0,0 +1,25 @@
+package config
+
+import (
+	"flag"
+	"time"
+)
+
+type DeployConfig struct {
+	Host    string
+	User    string
+	AppPath string
+	Port    int
+	Timeout time.Duration
+}
+
+func ParseDeployFlags(args []string, defaults DeployConfig) (DeployConfig, error) {
+	fs := flag.NewFlagSet("deploy", flag.ContinueOnError)
+	host := fs.String("host", defaults.Host, "target host")
+	user := fs.String("user", defaults.User, "ssh user")
+	appPath := fs.String("app", defaults.AppPath, "path to Go app (main package directory)")
+	port := fs.Int("port", defaults.Port, "health port")
+	timeout := fs.Duration("timeout", defaults.Timeout, "health timeout")
+	if err := fs.Parse(args); err != nil { return DeployConfig{}, err }
+	return DeployConfig{Host: *host, User: *user, AppPath: *appPath, Port: *port, Timeout: *timeout}, nil
+}

internal/executil/executil.go

@@ -0,0 +1,29 @@
+package executil
+
+import (
+	"bytes"
+	"os/exec"
+)
+
+type Executor interface {
+	Run(name string, args ...string) error
+	RunOutput(name string, args ...string) (string, error)
+}
+
+type Default struct{}
+
+func New() *Default { return &Default{} }
+
+func (d *Default) Run(name string, args ...string) error {
+	cmd := exec.Command(name, args...)
+	return cmd.Run()
+}
+
+func (d *Default) RunOutput(name string, args ...string) (string, error) {
+	cmd := exec.Command(name, args...)
+	var out bytes.Buffer
+	cmd.Stdout = &out
+	cmd.Stderr = &out
+	err := cmd.Run()
+	return out.String(), err
+}

pkg/builder/builder.go

@@ -0,0 +1,22 @@
+package builder
+
+import (
+	"fmt"
+	"path/filepath"
+
+	"github.com/goVerta/launchd/internal/executil"
+)
+
+type Builder interface {
+	Build(appPath, out string) error
+}
+
+type GoBuilder struct{ Exec executil.Executor }
+
+func Build(exec executil.Executor, appPath, out string) error {
+	if exec == nil { return fmt.Errorf("nil executor") }
+	abs, err := filepath.Abs(appPath)
+	if err != nil { return err }
+	// saadhtiwana: build using system go toolchain for determinism
+	return exec.Run("go", "build", "-o", out, abs)
+}

pkg/builder/builder_test.go

@@ -0,0 +1,34 @@
+package builder
+
+import (
+	"errors"
+	"reflect"
+	"testing"
+)
+
+type fakeExec struct{ calls [][]string; err error }
+
+func (f *fakeExec) Run(name string, args ...string) error {
+	f.calls = append(f.calls, append([]string{name}, args...))
+	return f.err
+}
+func (f *fakeExec) RunOutput(name string, args ...string) (string, error) { return "", nil }
+
+func TestBuild_InvokesGoBuild(t *testing.T) {
+	ex := &fakeExec{}
+	if err := Build(ex, "./testdata/app", "/tmp/out"); err != nil {
+		t.Fatalf("unexpected: %v", err)
+	}
+	if len(ex.calls) != 1 { t.Fatalf("calls=%d", len(ex.calls)) }
+	got := ex.calls[0]
+	if got[0] != "go" || !reflect.DeepEqual(got[1:3], []string{"build", "-o"}) {
+		t.Fatalf("bad invocation: %v", got)
+	}
+}
+
+func TestBuild_ErrorSurfaced(t *testing.T) {
+	ex := &fakeExec{err: errors.New("boom")}
+	if err := Build(ex, "./app", "/tmp/out"); err == nil {
+		t.Fatalf("expected error")
+	}
+}

pkg/health/health.go

@@ -0,0 +1,26 @@
+package health
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+)
+
+func Wait(host string, port int, timeout time.Duration) error {
+	client := &http.Client{ Timeout: 5 * time.Second }
+	deadline := time.Now().Add(timeout)
+	url := fmt.Sprintf("http://%s:%d/health", host, port)
+	for {
+		if time.Now().After(deadline) { return errors.New("timeout waiting for health") }
+		resp, err := client.Get(url)
+		if err == nil {
+			b, _ := io.ReadAll(resp.Body)
+			_ = resp.Body.Close()
+			if resp.StatusCode >= 200 && resp.StatusCode < 300 { return nil }
+			_ = b
+		}
+		time.Sleep(500 * time.Millisecond)
+	}
+}