fix: rewrite README.md — stale quick example used deleted API
README showed core.New(core.Options{...}) (deleted pattern),
RegisterTask (removed), PERFORM (removed), type Task any (removed).
Quick example would not compile.
Also found 6 docs/ files with same stale patterns — tracked for
next session (getting-started, index, messaging, primitives, testing).
Co-Authored-By: Virgil <virgil@lethean.io>
This commit is contained in:
Snider
parent
cd452791e5
commit
ba77e029c8
1 changed files with 20 additions and 97 deletions
117
README.md
117
README.md
|
|
@ -1,8 +1,6 @@
|
|||
# CoreGO
|
||||
|
||||
Dependency injection, service lifecycle, command routing, and message-passing for Go.
|
||||
|
||||
Import path:
|
||||
Dependency injection, service lifecycle, permission, and message-passing for Go.
|
||||
|
||||
```go
|
||||
import "dappco.re/go/core"
|
||||
|
|
@ -14,75 +12,24 @@ CoreGO is the foundation layer for the Core ecosystem. It gives you:
|
|||
- one input shape: `Options`
|
||||
- one output shape: `Result`
|
||||
- one command tree: `Command`
|
||||
- one message bus: `ACTION`, `QUERY`, `PERFORM`
|
||||
|
||||
## Why It Exists
|
||||
|
||||
Most non-trivial Go systems end up needing the same small set of infrastructure:
|
||||
|
||||
- a place to keep runtime state and shared subsystems
|
||||
- a predictable way to start and stop managed components
|
||||
- a clean command surface for CLI-style workflows
|
||||
- decoupled communication between components without tight imports
|
||||
|
||||
CoreGO keeps those pieces small and explicit.
|
||||
- one message bus: `ACTION`, `QUERY` + named `Action` callables
|
||||
- one permission gate: `Entitled`
|
||||
- one collection primitive: `Registry[T]`
|
||||
|
||||
## Quick Example
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
|
||||
"dappco.re/go/core"
|
||||
)
|
||||
|
||||
type flushCacheTask struct {
|
||||
Name string
|
||||
}
|
||||
import "dappco.re/go/core"
|
||||
|
||||
func main() {
|
||||
c := core.New(core.Options{
|
||||
{Key: "name", Value: "agent-workbench"},
|
||||
})
|
||||
|
||||
c.Service("cache", core.Service{
|
||||
OnStart: func() core.Result {
|
||||
core.Info("cache started", "app", c.App().Name)
|
||||
return core.Result{OK: true}
|
||||
},
|
||||
OnStop: func() core.Result {
|
||||
core.Info("cache stopped", "app", c.App().Name)
|
||||
return core.Result{OK: true}
|
||||
},
|
||||
})
|
||||
|
||||
c.RegisterTask(func(_ *core.Core, task core.Task) core.Result {
|
||||
switch t := task.(type) {
|
||||
case flushCacheTask:
|
||||
return core.Result{Value: "cache flushed for " + t.Name, OK: true}
|
||||
}
|
||||
return core.Result{}
|
||||
})
|
||||
|
||||
c.Command("cache/flush", core.Command{
|
||||
Action: func(opts core.Options) core.Result {
|
||||
return c.PERFORM(flushCacheTask{
|
||||
Name: opts.String("name"),
|
||||
})
|
||||
},
|
||||
})
|
||||
|
||||
if !c.ServiceStartup(context.Background(), nil).OK {
|
||||
panic("startup failed")
|
||||
}
|
||||
|
||||
r := c.Cli().Run("cache", "flush", "--name=session-store")
|
||||
fmt.Println(r.Value)
|
||||
|
||||
_ = c.ServiceShutdown(context.Background())
|
||||
c := core.New(
|
||||
core.WithOption("name", "agent-workbench"),
|
||||
core.WithService(cache.Register),
|
||||
core.WithServiceLock(),
|
||||
)
|
||||
c.Run()
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -93,22 +40,16 @@ func main() {
|
|||
| `Core` | Central container and access point |
|
||||
| `Service` | Managed lifecycle component |
|
||||
| `Command` | Path-based executable operation |
|
||||
| `Cli` | CLI surface over the command tree |
|
||||
| `Action` | Named callable with panic recovery + entitlement |
|
||||
| `Task` | Composed sequence of Actions |
|
||||
| `Registry[T]` | Thread-safe named collection |
|
||||
| `Process` | Managed execution (Action sugar) |
|
||||
| `API` | Remote streams (protocol handlers) |
|
||||
| `Entitlement` | Permission check result |
|
||||
| `Data` | Embedded filesystem mounts |
|
||||
| `Drive` | Named transport handles |
|
||||
| `Fs` | Local filesystem operations |
|
||||
| `Fs` | Local filesystem (sandboxable) |
|
||||
| `Config` | Runtime settings and feature flags |
|
||||
| `I18n` | Locale collection and translation delegation |
|
||||
| `E`, `Wrap`, `ErrorLog`, `ErrorPanic` | Structured failures and panic recovery |
|
||||
|
||||
## AX-Friendly Model
|
||||
|
||||
CoreGO follows the same design direction as the AX spec:
|
||||
|
||||
- predictable names over compressed names
|
||||
- paths as documentation, such as `deploy/to/homelab`
|
||||
- one repeated vocabulary across the framework
|
||||
- examples that show how to call real APIs
|
||||
|
||||
## Install
|
||||
|
||||
|
|
@ -121,30 +62,12 @@ Requires Go 1.26 or later.
|
|||
## Test
|
||||
|
||||
```bash
|
||||
core go test
|
||||
```
|
||||
|
||||
Or with the standard toolchain:
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
go test ./... # 483 tests, 84.7% coverage
|
||||
```
|
||||
|
||||
## Docs
|
||||
|
||||
The full documentation set lives in `docs/`.
|
||||
|
||||
| Path | Covers |
|
||||
|------|--------|
|
||||
| `docs/getting-started.md` | First runnable CoreGO app |
|
||||
| `docs/primitives.md` | `Options`, `Result`, `Service`, `Message`, `Query`, `Task` |
|
||||
| `docs/services.md` | Service registry, runtime helpers, service locks |
|
||||
| `docs/commands.md` | Path-based commands and CLI execution |
|
||||
| `docs/messaging.md` | `ACTION`, `QUERY`, `QUERYALL`, `PERFORM`, `PerformAsync` |
|
||||
| `docs/lifecycle.md` | Startup, shutdown, context, and task draining |
|
||||
| `docs/subsystems.md` | `App`, `Data`, `Drive`, `Fs`, `I18n`, `Cli` |
|
||||
| `docs/errors.md` | Structured errors, logging helpers, panic recovery |
|
||||
| `docs/testing.md` | Test naming and framework testing patterns |
|
||||
The authoritative API contract is `docs/RFC.md` (21 sections).
|
||||
|
||||
## License
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue