argsbarg 6.1.8 → 6.1.10

package/docs/distribution-homebrew.md

@@ -1,159 +1,172 @@
-# Shipping via Homebrew (tap-from-repo)
+# Homebrew Distribution & Release Guide (Tap-from-Repo)
 
-Argsbarg apps distribute the **binary and shell completions** through Homebrew, and **agent artifacts** (skills, MCP config) through `configure --sync`.
+ArgsBarg provides native, first-class support for packaging, releasing, and distributing command-line binaries and shell autocomplete configurations through Homebrew via a standard **tap-from-repo** model. This is designed to serve as a secure, standard-compliant mechanism for internal enterprise distribution.
 
-## Distribution model
+---
 
-| Layer | Mechanism |
-| --- | --- |
-| Binary + completions | Formula `install` block |
-| Skills + MCP | Formula `post_install` → `{key} configure --sync --yes` |
-| App config file | Bootstrapped as `{}` on `post_install` via `--sync` (`~/.local/lib/<key>/config.json`) |
-| App config values | User opt-in: `{key} configure` (interactive wizard when `program.appConfig` has entries) |
-| App config cleanup | Formula `uninstall` → `{key} configure --remove-all --yes` |
+## 1. Enterprise Distribution Model
 
-**Only tap-from-repo** — in-repo `Formula/` or GitHub tap. Not Homebrew core.
+ArgsBarg maps the lifecycle of your application directly to standard Homebrew hooks, separating binary installation from user-interactive environment setup.
 
-### End-user install
+| Layer | Mechanism | Role in Lifecycle |
+| --- | --- | --- |
+| **Binary & Autocompletions** | Formula `install` block | Installs compiled binary and registers native shell autocompletions. |
+| **Telemetry & Agent Synclinks** | Formula `post_install` | Automatically runs `{key} configure --sync --yes` to bootstrap configuration files and sync developer tools. |
+| **Application Configuration** | User-facing `{key} configure` | Runs an interactive TTY setup wizard (only when `program.appConfig` defines required parameters). |
+| **Clean Uninstall** | Formula `uninstall` | Automatically runs `{key} configure --remove-all --yes` to clean up local configurations and symlinks. |
 
-For **private or internal GitHub taps**, authenticate with GitHub CLI before `brew install` or `brew upgrade` (release formulae download via the GitHub API; Homebrew discovers credentials from `gh auth login`).
+*Note: This architecture explicitly separates non-interactive installation (safe for automation/CI) from interactive configuration (which requires a TTY).*
 
-```bash
-brew install gh   # skip if already installed
-gh auth login     # skip if already authenticated
-```
+---
 
-Then:
+## 2. Distribution Strategies: Public vs. Private Taps
 
-```bash
-brew tap <org>/<repo> git@github.com:<org>/<repo>.git
-brew install <tap>/{key}
-{key} configure   # when app config is required
-```
-
-Upgrade:
-
-```bash
-brew upgrade {key}
-```
+ArgsBarg supports both open-source public formulas and secure private enterprise distribution. You can configure your repository structure depending on your project type.
 
-Local dev installs (`just install-local`) use a `file://` staging URL and do not need GitHub authentication.
+### Strategy A: Public Open-Source Taps (Default)
 
-### Developer install
+For open-source projects, Homebrew requires zero authentication. Users can tap your public repository and install your application with standard commands out of the box:
 
 ```bash
-just build
-just install-local    # or `just install` (alias)
-just reinstall-local   # fast binary swap (`install -m 755` into Cellar; run install-local first)
-just uninstall        # undo formula + agent artifacts (app config removed by formula uninstall)
-```
+# Tap the public repository
+brew tap <org>/<repo>
 
-Dev and release use the **same formula file** (`Formula/{key}.rb`). `just install-local` runs:
-
-```bash
-bun scripts/dev-formula.ts install    # back up release formula, write file:// dev formula
-brew install --formula <tap>/{key}  # install from the dev formula
-bun scripts/dev-formula.ts reset      # restore release formula
+# Install the application
+brew install <tap>/{key}
 ```
 
-If `brew install` fails, run `bun scripts/dev-formula.ts reset` manually to restore the release formula.
-
-### Developer uninstall
+The generated Homebrew formula points directly to your public GitHub release asset URL, allowing anyone to install and receive automatic updates securely.
 
-| Recipe | Removes |
-| --- | --- |
-| `just uninstall` | Formula `{key}` + tap symlink + skills/MCP + app config via formula `uninstall` |
-| `just uninstall-config` | App config file only (`configure --remove-config --yes`) |
-| `just uninstall-release` | Release formula from `{tap}` (keeps tap; agent artifacts via formula `uninstall`) |
-| `just uninstall-release-tap` | Release formula + `brew untap {tap}` (agent artifacts via formula `uninstall`) |
-| `just test-release` | Install release formula and run formula test |
+### Strategy B: Private & Proprietary Corporate Taps
 
-End users: `brew uninstall <tap>/<key>`. The formula `uninstall` hook runs `configure --remove-all --yes` (skills, MCP, and app config).
+For proprietary, inner-source, or internal company tools, security is paramount. ArgsBarg provides a built-in strategy to distribute packages securely from private GitHub repositories without exposing sensitive personal tokens or raw download links in your formula code.
 
-## Formula pattern
+#### 1. End-User Authentication:
+Users authenticate locally using the standard GitHub CLI (`gh`), which Homebrew natively integrates with to retrieve download credentials:
 
-```ruby
-def install
-  bin.install "{key}"
-  generate_completions_from_executable(bin/"{key}", "completion", base_name: "{key}")
-end
+```bash
+# 1. Install and authenticate with GitHub CLI (if not already done)
+brew install gh
+gh auth login
 
-def post_install
-  system bin/"{key}", "configure", "--sync", "--yes"
-end
+# 2. Tap and install your private corporate repository
+brew tap <org>/<repo> git@github.com:<org>/<repo>.git
+brew install <tap>/{key}
 
-def uninstall
-  system bin/"{key}", "configure", "--remove-all", "--yes"
-end
+# 3. Perform interactive configuration (such as API tokens) if required
+{key} configure
 ```
 
-Release formulae generated by `scripts/formula-shared.ts` embed a `GitHubPrivateReleaseDownloadStrategy` that resolves the release asset through the GitHub API at download time and authenticates with `GitHub::API.credentials` (Homebrew discovers `gh auth login` automatically):
+#### 2. The Private Release Strategy:
+Release formulae generated by ArgsBarg's scripts utilize a custom **`GitHubPrivateReleaseDownloadStrategy`**. This strategy executes the secure asset download through standard GitHub API requests, leveraging the user's local `gh` login credentials securely under the hood:
 
 ```ruby
 url "https://github.com/<org>/<repo>/releases/download/vX.Y.Z/{key}",
     using: GitHubPrivateReleaseDownloadStrategy
 ```
 
-Local dev formulae (`just install-local`) use a plain `file://` URL and do not need the token.
+---
 
-Completions require users to configure their shell per [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
+## 3. Standardized Formula Pattern
 
-**Why the wizard is separate from `post_install`:** prompting for secrets requires a TTY. `post_install` only bootstraps an empty `config.json` and refreshes skills/MCP. Apps with `appConfig` print a one-line configure hint in formula `caveats` for the interactive wizard.
+ArgsBarg standardizes your Homebrew formulas. A typical generated formula (`Formula/{key}.rb`) is incredibly clean:
 
-**MCP hosts:** when `mcpServer.enabled` is true, add a caveats line that chat apps (Cursor, Claude Desktop, etc.) must be **restarted** after `brew install` / `brew upgrade` — `post_install` updates MCP config on disk, but hosts typically load it only at startup.
+```ruby
+class Myapp < Formula
+  desc "My application description"
+  homepage "https://github.com/org/myapp"
+  url "https://github.com/org/myapp/releases/download/v1.0.0/myapp.zip"
+  sha256 "a1b2c3d4e5f6g7h8..."
+  version "1.0.0"
+
+  def install
+    bin.install "myapp"
+    # Auto-generates shell completions for bash, zsh, and fish directly from the executable
+    generate_completions_from_executable(bin/"myapp", "completion", base_name: "myapp")
+  end
+
+  def post_install
+    # Non-interactive bootstrap of config files and developer links
+    system bin/"myapp", "configure", "--sync", "--yes"
+  end
+
+  def uninstall
+    # Graceful clean up of local files on uninstall
+    system bin/"myapp", "configure", "--remove-all", "--yes"
+  end
+  
+  def caveats
+    <<~EOS
+      Interactive configuration is required. Please run:
+        myapp configure
+    EOS
+  end
+end
+```
 
-## Bootstrap CLI (`argsbarg create`)
+---
 
-Copy the shipped `examples/full-example` template into a new directory with identity substitutions, then run install, schemagen, tests, and git init (when appropriate):
+## 4. Developer Iteration Workflow
 
-```bash
-bunx argsbarg create my-cli \
-  --key my-cli --class-name MyCli --tap org/my-cli \
-  --homepage https://github.com/org/my-cli --release-repo org/my-cli \
-  --yes
-```
+ArgsBarg provides an optimized workflow for developers to build, package, and test their Homebrew installer locally before pushing releases.
 
-On a TTY, omit flags to use the interactive wizard. Verify an existing tree:
+### Local Staging Commands:
 
 ```bash
-bunx argsbarg create --check .
+# 1. Build the local release binary
+just build
+
+# 2. Stage and install the formula locally (bypasses GitHub, uses file://)
+just install-local
+
+# 3. Swap updated binaries quickly during tight edit cycles
+just reinstall-local
+
+# 4. Uninstall the binary and gracefully clean up all configurations
+just uninstall
 ```
 
-Template source: [`examples/full-example/`](../examples/full-example/) in the argsbarg package (also under `node_modules/argsbarg/examples/full-example` after `bun add argsbarg`).
+### Under the Hood:
 
-**Git bootstrap skip rules:** post-create skips `git init` when the target already has a `.git` directory, or when the target sits inside an existing git work tree (e.g. a monorepo subfolder). Standalone new directories get an `Initial commit`.
+To ensure you test the exact formula that will be shipped to production, `just install-local` runs:
 
-## Release workflow
+1.  `bun scripts/dev-formula.ts install` — Safely backs up your production formula and writes a temporary local dev formula using a `file://` URL pointing to your build directory.
+2.  `brew install --formula <tap>/{key}` — Installs the package locally using Homebrew.
+3.  `bun scripts/dev-formula.ts reset` — Automatically restores your production formula on disk.
 
-1. `just build` → `dist/{key}`
-2. `scripts/release.ts` → zips `dist/{key}` to `dist/{key}.zip`, writes `Formula/{key}.rb` (GitHub zip URL + archive sha256), commits, tags, uploads `dist/{key}.zip` to GitHub Releases
-3. Users `brew upgrade {key}` from the tap
+---
 
-Requires the `zip` CLI on the release machine. `just install-local` still stages the bare binary via `file://` (no zip).
+## 5. Automated Release Pipeline
 
-### Stale release cleanup
+ArgsBarg automates the release cycle. A production-ready release is performed using a single command:
 
 ```bash
-just release --purge              # delete all GitHub releases except the newest (confirm on TTY)
-just release --purge --yes        # skip confirmation
-just release --purge --dry-run    # list tags that would be deleted
-just release patch --purge        # release, then purge older releases
+# Performs build, zips binary, updates Formula with new SHA-256, tags git, pushes, and uploads release asset
+just release patch   # or minor | major
 ```
 
-`--purge` removes GitHub Release records and attached assets only — git tags remain on the remote. Old formula pins that reference deleted release URLs will fail until users upgrade.
+### Release Pipeline Steps:
 
-## Removed (breaking)
+1.  **Build**: Compiles the binary to `dist/{key}`.
+2.  **Archive**: Packages the binary into a compressed `dist/{key}.zip`.
+3.  **Integrity Check**: Calculates the cryptographically secure SHA-256 hash of the zip file.
+4.  **Formula Sync**: Updates the version number and `sha256` parameter in `Formula/{key}.rb`.
+5.  **Tag & Push**: Commits changes, tags the repository with the new version, pushes to GitHub, and publishes the compiled zip to GitHub Releases.
 
-- Self-install to `~/.local/bin`
-- Top-level `install` and `uninstall` commands (use `configure`)
-- `install --update` / `updateGetLatest`
-- Homebrew completion installer via CLI (Homebrew owns completions)
-- Bare-argv install bootstrap
-- Auto configure wizard after sync
-- Separate `{key}-local` formula and `{key}/dev` tap
+### Older Release Retention & Cleanup:
+
+To keep your storage footprint clean, the pipeline supports purging stale historical release assets while preserving the git tags:
+
+```bash
+just release --purge              # Interactive tag purge of older release records
+just release --purge --yes        # Silent automated purge (useful in CI/CD)
+just release --purge --dry-run    # Preview list of tag deletions
+```
 
-## Config path
+---
 
-Default: `~/.local/lib/<sanitized-key>/config.json`
+## 6. Directory Defaults
 
-Export helpers: `resolveAppConfigPath`, `displayAppConfigPath` from `argsbarg`.
+Applications packaged via ArgsBarg adhere to standard system directories:
+*   **Resolved Configuration Path**: `~/.local/lib/<sanitized-key>/config.json`
+*   **Auto-Exports**: Developers can import `resolveAppConfigPath` or `displayAppConfigPath` directly from `argsbarg` to display helpful directories in help screens.

package/docs/http-server.md

@@ -49,7 +49,9 @@ Set `httpServer` on the **program root only**. Validation rejects `httpServer` o
 
 `httpServer` and `mcpServer` are independent — enable either or both.
 
-Program-level `program.log` controls ECS JSON vs human text on stderr (and optional file tee). See [docs/decisions.md](decisions.md).
+## Logging
+
+Server logs (access lines, errors, startup) go to **stderr** as JSON by default. See **[logging.md](logging.md)** for `program.log`, **`enrich`**, **`serialize`**, trace headers, and examples.
 
 ## REST routes
 

package/docs/logging.md

@@ -0,0 +1,149 @@
+# Server logging
+
+When you run `myapp http` or `myapp mcp`, Argsbarg writes **server logs to stderr** — not to stdout (handlers and CLI output stay on stdout).
+
+By default each log line is **one JSON object** (NDJSON), shaped for the [ECS Logging](https://github.com/elastic/ecs-logging) convention. That plays nicely with Datadog, Elasticsearch, GCP Logging, and similar collectors.
+
+For local development, switch to plain text with `--log-format text` or `program.log.format: "text"`.
+
+## What gets logged
+
+| Event | When | `event.action` |
+| --- | --- | --- |
+| Server start | HTTP/MCP process listens | `http.server.start` / `server.start` |
+| Access | After each HTTP request or MCP JSON-RPC message | `http.access` / `mcp.access` |
+| Invoke error | After `formatError` → `onError`, before the client sees the error | `invoke.error` |
+
+Toggle access or error lines with `program.log.access` and `program.log.errors` (both default to `true`).
+
+## Example line (default JSON)
+
+After `GET /workspaces` returns 200 in 45ms:
+
+```json
+{
+  "@timestamp": "2026-07-27T14:00:00.000Z",
+  "log.level": "info",
+  "message": "GET /workspaces",
+  "ecs.version": "8.11.0",
+  "service.name": "myapp",
+  "service.version": "1.0.0",
+  "event.action": "http.access",
+  "http.request.method": "GET",
+  "url.path": "/workspaces",
+  "http.response.status_code": 200,
+  "event.duration": 45000000,
+  "labels": { "request_id": "…" }
+}
+```
+
+`event.duration` is in **nanoseconds** (ECS convention). Durations in hook callbacks (`durationMs`) stay in milliseconds.
+
+When the client sends a W3C **`traceparent`** header, lines also include `trace.id` and `span.id`, and the response echoes an updated `traceparent`.
+
+## `program.log` options
+
+Set on the **program root** (same level as `httpServer` / `mcpServer`):
+
+```typescript
+const program = {
+  key: "myapp",
+  version: "1.0.0",
+  description: "…",
+  log: {
+    format: "json",   // "text" for human-readable stderr
+    file: "server.log", // optional tee; relative paths → app config dir
+    access: true,     // HTTP/MCP access lines
+    errors: true,     // invoke error lines
+  },
+  // …
+} satisfies CliProgram;
+```
+
+| Field | Default | Purpose |
+| --- | --- | --- |
+| `format` | `"json"` | `"json"` = ECS Logging NDJSON; `"text"` = `INFO [http.access]: GET /path` |
+| `file` | — | Append the same lines to this path |
+| `access` | `true` | Emit one line per HTTP request / MCP message |
+| `errors` | `true` | Emit when a user command fails on HTTP/MCP |
+| `enrich` | — | Add custom fields to each JSON line (see below) |
+| `serialize` | — | Replace the built-in formatter entirely (see below) |
+
+CLI overrides on `myapp http` and `myapp mcp serve`: `--log-format`, `--log-file`, `--no-access-log` (HTTP only), `--dev` (print full stacks to stderr on errors).
+
+## `program.log.enrich` — add fields
+
+Use **`enrich`** when you want **extra JSON fields** on top of the default ECS line — for example a team label, deployment cell, or a shape your log pipeline expects.
+
+`enrich` is **additive only**. It cannot change `@timestamp`, `log.level`, `message`, `ecs.version`, `service.name`, `service.version`, or any field Argsbarg already set on that line.
+
+```typescript
+import type { LogEnrichContext } from "argsbarg";
+
+const program = {
+  // …
+  log: {
+    format: "json",
+    enrich: (ctx: LogEnrichContext) => {
+      // Always available:
+      // ctx.level, ctx.message, ctx.action, ctx.service.name, ctx.service.version
+      // ctx.requestId, ctx.traceId, ctx.spanId (when present)
+      // ctx.labels, ctx.error (on error lines)
+
+      // On access logs (http.access / mcp.access):
+      // ctx.http.method, ctx.http.path, ctx.http.status, ctx.http.durationMs, ctx.http.clientIp
+
+      return {
+        deployment: "prod",
+      };
+    },
+  },
+} satisfies CliProgram;
+```
+
+Return a flat object of field names → values. Argsbarg merges each key onto the log line unless that key is already set. To add team metadata inside ECS `labels`, put it in `event.labels` via hooks rather than fighting merge order — or use `serialize` for full control.
+
+## `program.log.serialize` — own the whole line
+
+Use **`serialize`** when the default ECS line is not what you need — for example a legacy JSON schema used only in your organization.
+
+When `serialize` is set, Argsbarg **does not** run the ECS formatter. Your function receives the same `LogEnrichContext` as `enrich` and must return the **full line text without a trailing newline** (Argsbarg adds `\n`).
+
+```typescript
+import type { LogEnrichContext } from "argsbarg";
+
+const program = {
+  // …
+  log: {
+    format: "json",
+    serialize: (ctx: LogEnrichContext) =>
+      JSON.stringify({
+        message: ctx.message,
+        level: ctx.level.toUpperCase(),
+        contextMap: {
+          ...(ctx.traceId ? { trace_id: ctx.traceId } : {}),
+          ...(ctx.spanId ? { span_id: ctx.spanId } : {}),
+        },
+      }),
+  },
+} satisfies CliProgram;
+```
+
+Do **not** set both `enrich` and `serialize` expecting both to apply — `serialize` wins and `enrich` is ignored.
+
+Prefer **`enrich`** when you only need a few extra fields. Reserve **`serialize`** for fully custom output.
+
+## Trace correlation (HTTP)
+
+If an upstream service (gateway, sidecar, mesh) sends a standard **`traceparent`** header:
+
+1. Argsbarg parses it and logs `trace.id` / `span.id`.
+2. The HTTP response includes an updated `traceparent` for this hop.
+
+No configuration required. If the header is missing, Argsbarg does not invent a trace id.
+
+## Related
+
+- [http-server.md](http-server.md) — HTTP server setup and endpoints
+- [mcp.md](mcp.md) — MCP server (same `program.log` applies)
+- [decisions.md](decisions.md#structured-logging-ecs-logging) — why ECS Logging and hooks instead of a bundled observability SDK

package/examples/full-example/docs/cli-schema.json

@@ -161,7 +161,7 @@
             },
             {
               "name": "log-format",
-              "description": "Log format: json (ECS) or text.",
+              "description": "Log format: json (ECS Logging) or text.",
               "kind": "enum",
               "choices": [
                 "json",
@@ -215,7 +215,7 @@
             },
             {
               "name": "log-format",
-              "description": "Log format: json (ECS) or text.",
+              "description": "Log format: json (ECS Logging) or text.",
               "kind": "enum",
               "choices": [
                 "json",
@@ -394,7 +394,7 @@
             },
             {
               "name": "log-format",
-              "description": "Log format: json (ECS) or text.",
+              "description": "Log format: json (ECS Logging) or text.",
               "kind": "enum",
               "choices": [
                 "json",
@@ -448,7 +448,7 @@
             },
             {
               "name": "log-format",
-              "description": "Log format: json (ECS) or text.",
+              "description": "Log format: json (ECS Logging) or text.",
               "kind": "enum",
               "choices": [
                 "json",
@@ -649,7 +649,7 @@
             },
             {
               "name": "log-format",
-              "description": "Log format: json (ECS) or text.",
+              "description": "Log format: json (ECS Logging) or text.",
               "kind": "enum",
               "choices": [
                 "json",
@@ -703,7 +703,7 @@
             },
             {
               "name": "log-format",
-              "description": "Log format: json (ECS) or text.",
+              "description": "Log format: json (ECS Logging) or text.",
               "kind": "enum",
               "choices": [
                 "json",
@@ -886,7 +886,7 @@
                 },
                 {
                   "name": "log-format",
-                  "description": "Log format: json (ECS) or text.",
+                  "description": "Log format: json (ECS Logging) or text.",
                   "kind": "enum",
                   "choices": [
                     "json",
@@ -940,7 +940,7 @@
                 },
                 {
                   "name": "log-format",
-                  "description": "Log format: json (ECS) or text.",
+                  "description": "Log format: json (ECS Logging) or text.",
                   "kind": "enum",
                   "choices": [
                     "json",
@@ -1119,7 +1119,7 @@
                 },
                 {
                   "name": "log-format",
-                  "description": "Log format: json (ECS) or text.",
+                  "description": "Log format: json (ECS Logging) or text.",
                   "kind": "enum",
                   "choices": [
                     "json",
@@ -1173,7 +1173,7 @@
                 },
                 {
                   "name": "log-format",
-                  "description": "Log format: json (ECS) or text.",
+                  "description": "Log format: json (ECS Logging) or text.",
                   "kind": "enum",
                   "choices": [
                     "json",
@@ -1356,7 +1356,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -1410,7 +1410,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -1589,7 +1589,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -1643,7 +1643,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -1822,7 +1822,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -1876,7 +1876,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -2055,7 +2055,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -2109,7 +2109,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",