feat: Build gonsole, the command line brick

.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        module: ["mailkit"]
+        module: ["mailkit", "gonsole"]
     defaults:
       run:
         working-directory: ${{ matrix.module }}
@@ -25,7 +25,9 @@ jobs:
       - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6.5.0
         with:
           go-version-file: ${{ matrix.module }}/go.mod
-          cache-dependency-path: ${{ matrix.module }}/go.sum
+          cache-dependency-path: |
+            ${{ matrix.module }}/go.mod
+            ${{ matrix.module }}/go.sum
       - run: go test -race -covermode=atomic -coverprofile=cover.out ./...
       - run: go vet ./...
 
@@ -59,15 +61,17 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        module: ["mailkit"]
+        module: ["mailkit", "gonsole"]
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
       - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6.5.0
         with:
           go-version-file: ${{ matrix.module }}/go.mod
-          cache-dependency-path: ${{ matrix.module }}/go.sum
+          cache-dependency-path: |
+            ${{ matrix.module }}/go.mod
+            ${{ matrix.module }}/go.sum
       - uses: golangci/golangci-lint-action@ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a # v9.3.0
         with:
           version: v2.13.2
@@ -79,7 +83,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        module: ["mailkit"]
+        module: ["mailkit", "gonsole"]
     defaults:
       run:
         working-directory: ${{ matrix.module }}
@@ -90,5 +94,7 @@ jobs:
       - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6.5.0
         with:
           go-version-file: ${{ matrix.module }}/go.mod
-          cache-dependency-path: ${{ matrix.module }}/go.sum
+          cache-dependency-path: |
+            ${{ matrix.module }}/go.mod
+            ${{ matrix.module }}/go.sum
       - run: go run golang.org/x/vuln/cmd/govulncheck@latest ./...

README.md

@@ -11,20 +11,21 @@ need and ignore the rest.
 
 ## Modules
 
+- [`gonsole`](gonsole/) runs the command line of a Go program built from
+  core commands, settings and compiled plugins.
 - [`gottext`](gottext/) reads, writes and syncs gettext catalogs for
   TypeScript applications, published to npm as `@gopherium/gottext`.
 - [`mailkit`](mailkit/) renders mail from template files and sends it
   over SMTP.
 
 ## Design
 
-One repository, one self-contained brick per directory, no shared code
-between them. A Go brick carries its own go.mod and a TypeScript brick
-its own package.json, each with its own CHANGELOG and lint
-configuration, released independently under a path-prefixed tag such
-as `mailkit/v0.1.0` or `gottext/v0.4.0`. Bricks depend on published
-versions only, never on sibling source, so what you pin is what you
-get.
+One repository, one self-contained brick per directory. A Go brick
+carries its own go.mod and a TypeScript brick its own package.json,
+each with its own CHANGELOG and lint configuration, released
+independently under a path-prefixed tag such as `mailkit/v0.1.0` or
+`gottext/v0.4.0`. Bricks share code only through those published tags,
+never through sibling source, so what you pin is what you get.
 
 ## Reporting security issues
 

gonsole/.golangci.yml

@@ -0,0 +1,49 @@
+version: "2"
+
+linters:
+  default: standard
+  enable:
+    - cyclop
+    - depguard
+    - gocognit
+    - lll
+    - misspell
+    - revive
+    - unconvert
+    - unparam
+  settings:
+    cyclop:
+      max-complexity: 10
+    gocognit:
+      min-complexity: 15
+    lll:
+      line-length: 120
+    revive:
+      rules:
+        - name: blank-imports
+          disabled: true
+        - name: exported
+    depguard:
+      rules:
+        engine-purity:
+          list-mode: strict
+          files:
+            - "**/*.go"
+          allow:
+            - $gostd
+            - github.com/gopherium/framework/gonsole
+  exclusions:
+    rules:
+      - path: _test\.go
+        linters:
+          - cyclop
+          - gocognit
+
+formatters:
+  enable:
+    - gofmt
+    - goimports
+  settings:
+    goimports:
+      local-prefixes:
+        - github.com/gopherium/framework

gonsole/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to the `gonsole` module are documented in this
+file. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
+module follows [Semantic Versioning](https://semver.org/). While at
+v0.x, minor releases may contain breaking changes.
+
+Releases of this module are tagged `gonsole/vX.Y.Z`.
+
+## [Unreleased]
+
+### Added
+
+- `Program`, `Main` and `Run`, running a command line and answering exit code 0, 1 or 2.
+- `Command`, `Call` and `Step`, a command, what one run of it receives, and a named schema step.
+- `Misuse` and `ErrMisused`, marking an error the program answers with exit 2.
+- Command names alone or as `namespace:command`, a help page for each, and a listing of them all.
+- `-yes` dry runs for commands that write and `-json` for commands that answer one document.
+- `-as` with `Authorize` and `Record`, checking and recording the account that acts.
+- `Call.Flags`, the command's own flags the line set, for the audit record.
+- The base commands `help`, `list`, `version`, `check`, `serve`, `migrate` and `seed`.
+- `Program.Check`, refusing every naming offence in the program and its plugins.
+- `Renamed`, keeping an old two word spelling working with a warning.
+- `Env` with `Required`, `Duration`, `Count`, `Flag`, `Within`, `Parse` and `Timeouts`.
+- `NewServer` and `Serve`, serving HTTP until a signal ends the run.
+- `Program.Plugins`, `Call.Plugins`, `Loaded`, `Provider` and `Walk`, for compiled plugins' commands.
+- `testkit`, running programs from tests in process and as built binaries.

gonsole/actor.go

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package gonsole
+
+import (
+	"context"
+	"fmt"
+	"runtime/debug"
+)
+
+// perform authorizes the acting account of call, migrates when cmd asks, runs cmd and records the run when it applied.
+func (r *runner) perform(ctx context.Context, cmd Command, call Call) error {
+	if err := r.authorize(ctx, cmd, call); err != nil {
+		return err
+	}
+	if cmd.Migrates && call.Apply {
+		if err := r.migrate(ctx, call, call.Stderr); err != nil {
+			return err
+		}
+	}
+	if err := cmd.Run(ctx, call); err != nil {
+		return err
+	}
+	if !call.Apply {
+		r.warn("dry run, nothing changed, pass -yes to apply")
+		return nil
+	}
+	return r.record(ctx, cmd, call)
+}
+
+// authorize refuses the acting account of call when it lacks the capability cmd names.
+func (r *runner) authorize(ctx context.Context, cmd Command, call Call) error {
+	if cmd.Capability == "" {
+		return nil
+	}
+	return r.program.Authorize(ctx, call, cmd.Capability)
+}
+
+// record stores the applied run of cmd when cmd names a capability, under a context the end of the run cannot cancel.
+func (r *runner) record(ctx context.Context, cmd Command, call Call) error {
+	if cmd.Capability == "" {
+		return nil
+	}
+	return r.program.Record(context.WithoutCancel(ctx), call, cmd.Name)
+}
+
+// panicked is a panic recovered from the run of one command.
+type panicked struct {
+	command string
+	value   any
+	stack   []byte
+}
+
+// Error returns the line naming the command and the panic value.
+func (p panicked) Error() string {
+	return fmt.Sprintf("%s: panic: %v", p.command, p.value)
+}
+
+// crashes returns every panic err holds, in the order its message names them.
+func crashes(err error) []panicked {
+	switch e := err.(type) {
+	case panicked:
+		return []panicked{e}
+	case interface{ Unwrap() []error }:
+		var all []panicked
+		for _, inner := range e.Unwrap() {
+			all = append(all, crashes(inner)...)
+		}
+		return all
+	case interface{ Unwrap() error }:
+		return crashes(e.Unwrap())
+	}
+	return nil
+}
+
+// recoverRun turns a panic in the run of the command called name into the error err points at.
+func recoverRun(name string, err *error) {
+	if value := recover(); value != nil {
+		*err = panicked{command: name, value: value, stack: debug.Stack()}
+	}
+}