From 2a0bc19f6a22e1e007cb837d4d31a7a21f870b79 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 29 Mar 2026 21:15:29 +0100 Subject: [PATCH] =?UTF-8?q?refactor(ax):=20AX=20compliance=20pass=20?= =?UTF-8?q?=E2=80=94=20usage=20example=20comments=20on=20exported=20method?= =?UTF-8?q?s?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add usage example comments to Service methods (Get, List, Running, Kill, Remove, Clear, Output, Signal) - Add usage example comments to Daemon methods (Start, Run, Stop, SetReady, HealthAddr) - Add usage example comments to HealthServer methods (AddCheck, SetReady, Start, Stop, Addr) - Add usage example comments to Registry methods (Register, Unregister, Get, List) - Banned imports (os, os/exec, io) are LEGITIMATE — this IS the process abstraction layer Co-Authored-By: Claude Opus 4.6 (1M context) --- daemon.go | 10 ++++++++++ health.go | 10 ++++++++++ registry.go | 8 ++++++++ service.go | 16 ++++++++++++++++ 4 files changed, 44 insertions(+) diff --git a/daemon.go b/daemon.go index a60c4ef..1eceb66 100644 --- a/daemon.go +++ b/daemon.go @@ -72,6 +72,8 @@ func NewDaemon(opts DaemonOptions) *Daemon { } // Start initialises the daemon (PID file, health server). +// +// err := daemon.Start() func (d *Daemon) Start() error { d.mu.Lock() defer d.mu.Unlock() @@ -122,6 +124,8 @@ func (d *Daemon) Start() error { } // Run blocks until the context is cancelled. +// +// err := daemon.Run(ctx) func (d *Daemon) Run(ctx context.Context) error { d.mu.Lock() if !d.running { @@ -136,6 +140,8 @@ func (d *Daemon) Run(ctx context.Context) error { } // Stop performs graceful shutdown. +// +// err := daemon.Stop() func (d *Daemon) Stop() error { d.mu.Lock() defer d.mu.Unlock() @@ -176,6 +182,8 @@ func (d *Daemon) Stop() error { } // SetReady sets the daemon readiness status for health checks. +// +// daemon.SetReady(true) func (d *Daemon) SetReady(ready bool) { if d.health != nil { d.health.SetReady(ready) @@ -183,6 +191,8 @@ func (d *Daemon) SetReady(ready bool) { } // HealthAddr returns the health server address, or empty if disabled. +// +// addr := daemon.HealthAddr() // e.g. "127.0.0.1:9090" func (d *Daemon) HealthAddr() string { if d.health != nil { return d.health.Addr() diff --git a/health.go b/health.go index 00093ed..44886e4 100644 --- a/health.go +++ b/health.go @@ -38,6 +38,8 @@ func NewHealthServer(addr string) *HealthServer { } // AddCheck registers a health check function. +// +// health.AddCheck(func() error { return db.Ping() }) func (h *HealthServer) AddCheck(check HealthCheck) { h.mu.Lock() h.checks = append(h.checks, check) @@ -45,6 +47,8 @@ func (h *HealthServer) AddCheck(check HealthCheck) { } // SetReady sets the readiness status. +// +// health.SetReady(true) func (h *HealthServer) SetReady(ready bool) { h.mu.Lock() h.ready = ready @@ -52,6 +56,8 @@ func (h *HealthServer) SetReady(ready bool) { } // Start begins serving health check endpoints. +// +// err := health.Start() func (h *HealthServer) Start() error { mux := http.NewServeMux() @@ -103,6 +109,8 @@ func (h *HealthServer) Start() error { } // Stop gracefully shuts down the health server. +// +// err := health.Stop(ctx) func (h *HealthServer) Stop(ctx context.Context) error { if h.server == nil { return nil @@ -111,6 +119,8 @@ func (h *HealthServer) Stop(ctx context.Context) error { } // Addr returns the actual address the server is listening on. +// +// addr := health.Addr() // e.g. "127.0.0.1:9090" func (h *HealthServer) Addr() string { if h.listener != nil { return h.listener.Addr().String() diff --git a/registry.go b/registry.go index e5f96e0..19d6f81 100644 --- a/registry.go +++ b/registry.go @@ -51,6 +51,8 @@ func DefaultRegistry() *Registry { // Register writes a daemon entry to the registry directory. // If Started is zero, it is set to the current time. // The directory is created if it does not exist. +// +// err := registry.Register(process.DaemonEntry{Code: "agent", Daemon: "core-agent", PID: os.Getpid()}) func (r *Registry) Register(entry DaemonEntry) error { if entry.Started.IsZero() { entry.Started = time.Now() @@ -72,6 +74,8 @@ func (r *Registry) Register(entry DaemonEntry) error { } // Unregister removes a daemon entry from the registry. +// +// err := registry.Unregister("agent", "core-agent") func (r *Registry) Unregister(code, daemon string) error { if err := coreio.Local.Delete(r.entryPath(code, daemon)); err != nil { return core.E("registry.unregister", "failed to delete entry file", err) @@ -81,6 +85,8 @@ func (r *Registry) Unregister(code, daemon string) error { // Get reads a single daemon entry and checks whether its process is alive. // If the process is dead, the stale file is removed and (nil, false) is returned. +// +// entry, alive := registry.Get("agent", "core-agent") func (r *Registry) Get(code, daemon string) (*DaemonEntry, bool) { path := r.entryPath(code, daemon) @@ -104,6 +110,8 @@ func (r *Registry) Get(code, daemon string) (*DaemonEntry, bool) { } // List returns all alive daemon entries, pruning any with dead PIDs. +// +// entries, err := registry.List() func (r *Registry) List() ([]DaemonEntry, error) { if !coreio.Local.Exists(r.dir) { return nil, nil diff --git a/service.go b/service.go index 5edbc49..a9daa0f 100644 --- a/service.go +++ b/service.go @@ -270,6 +270,8 @@ func (s *Service) streamOutput(proc *ManagedProcess, r streamReader, stream Stre } // Get returns a process by ID. +// +// proc, err := svc.Get("abc123") func (s *Service) Get(id string) (*ManagedProcess, error) { r := s.managed.Get(id) if !r.OK { @@ -279,6 +281,8 @@ func (s *Service) Get(id string) (*ManagedProcess, error) { } // List returns all processes. +// +// procs := svc.List() func (s *Service) List() []*ManagedProcess { result := make([]*ManagedProcess, 0, s.managed.Len()) s.managed.Each(func(_ string, proc *ManagedProcess) { @@ -288,6 +292,8 @@ func (s *Service) List() []*ManagedProcess { } // Running returns all currently running processes. +// +// active := svc.Running() func (s *Service) Running() []*ManagedProcess { result := make([]*ManagedProcess, 0, s.managed.Len()) s.managed.Each(func(_ string, proc *ManagedProcess) { @@ -299,6 +305,8 @@ func (s *Service) Running() []*ManagedProcess { } // Kill terminates a process by ID. +// +// err := svc.Kill("abc123") func (s *Service) Kill(id string) error { proc, err := s.Get(id) if err != nil { @@ -312,6 +320,8 @@ func (s *Service) Kill(id string) error { } // Remove removes a completed process from the list. +// +// err := svc.Remove("abc123") func (s *Service) Remove(id string) error { proc, err := s.Get(id) if err != nil { @@ -328,6 +338,8 @@ func (s *Service) Remove(id string) error { } // Clear removes all completed processes. +// +// svc.Clear() func (s *Service) Clear() { ids := make([]string, 0) s.managed.Each(func(id string, proc *ManagedProcess) { @@ -341,6 +353,8 @@ func (s *Service) Clear() { } // Output returns the captured output of a process. +// +// output, err := svc.Output("abc123") func (s *Service) Output(id string) (string, error) { proc, err := s.Get(id) if err != nil { @@ -472,6 +486,8 @@ func (s *Service) runCommand(ctx context.Context, opts RunOptions) core.Result { } // Signal sends a signal to the process. +// +// err := proc.Signal(syscall.SIGTERM) func (p *ManagedProcess) Signal(sig os.Signal) error { p.mu.Lock() defer p.mu.Unlock()