chore: import upstream snapshot with attribution

2026-07-13 12:40:33 +08:00
commit e071084ebe
982 changed files with 160368 additions and 0 deletions
@@ -0,0 +1,701 @@
+# Micro
+
+Go Micro Command Line
+
+## Install the CLI
+
+Install `micro` via `go install`
+
+```
+go install go-micro.dev/v5/cmd/micro@v5.16.0
+```
+
+
+## Create a service
+
+Create your service (all setup is now automatic!):
+
+```
+micro new helloworld
+```
+
+Or use a template for common service patterns:
+
+```
+micro new contacts --template crud      # CRUD with Create/Read/Update/Delete/List
+micro new events --template pubsub      # Pub/sub with broker integration
+micro new gateway --template api        # API gateway with health check
+```
+
+This will:
+- Create a new service in the `helloworld` directory
+- Automatically run `go mod tidy` and `make proto` for you
+- Show the updated project tree including generated files
+- Warn you if `protoc` is not installed, with install instructions
+
+## Run the service
+
+Run your service:
+
+```
+micro run
+```
+
+This starts:
+- **API Gateway** on http://localhost:8080
+- **Web Dashboard** at http://localhost:8080
+- **Agent Playground** at http://localhost:8080/agent
+- **API Explorer** at http://localhost:8080/api
+- **MCP Tools** at http://localhost:8080/mcp/tools
+- **Hot Reload** watching for file changes
+- **Services** in dependency order
+
+Open http://localhost:8080 to see your services and call them from the browser.
+
+Call the generated service from another terminal:
+
+```
+curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call \
+  -H 'Content-Type: application/json' -d '{"name":"World"}'
+```
+
+## First agent on-ramp
+
+Once the scaffold → run → call path works, ask the installed CLI for the
+provider-free agent path. The focused no-secret docs/CLI contract is
+`make docs-wayfinding`:
+
+```
+micro agent demo
+micro agent quickcheck
+micro examples
+micro zero-to-hero
+```
+
+`micro agent quickcheck` (alias: `micro agent debug`) prints the short recovery map when scaffold → run → chat → inspect stalls. Those commands point at the smallest mock-model first-agent example, the no-secret transcript, and the 0→hero support app before you add provider-backed chat.
+
+### Output
+
+```
+  ┌─────────────────────────────────────────────────────────────┐
+  │                                                             │
+  │   Micro                                                     │
+  │                                                             │
+  │   Web:     http://localhost:8080                            │
+  │   API:     http://localhost:8080/api/{service}/{method}     │
+  │   Health:  http://localhost:8080/health                     │
+  │                                                             │
+  │   Services:                                                 │
+  │     ● helloworld                                            │
+  │                                                             │
+  │   Watching for changes...                                   │
+  │                                                             │
+  └─────────────────────────────────────────────────────────────┘
+```
+
+### Options
+
+```
+micro run                    # Gateway on :8080, hot reload enabled
+micro run --address :3000    # Gateway on custom port
+micro run --no-gateway       # Services only, no HTTP gateway
+micro run --no-watch         # Disable hot reload
+micro run --env production   # Use production environment
+micro run github.com/micro/blog  # Clone and run from GitHub
+```
+
+### Calling Services
+
+Via curl:
+```bash
+curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call -d '{"name": "World"}'
+```
+
+Or browse to http://localhost:8080 and use the web interface.
+
+List services:
+```
+micro services
+```
+
+## Configuration (micro.mu)
+
+For multi-service projects, create a `micro.mu` file to define services, dependencies, and environments:
+
+```
+service users
+    path ./users
+    port 8081
+
+service posts
+    path ./posts
+    port 8082
+    depends users
+
+service web
+    path ./web
+    port 8089
+    depends users posts
+
+env development
+    STORE_ADDRESS file://./data
+    DEBUG true
+
+env production
+    STORE_ADDRESS postgres://localhost/db
+```
+
+### Configuration Options
+
+| Property | Description |
+|----------|-------------|
+| `path` | Directory containing the service (with main.go) |
+| `port` | Port the service listens on (for health checks) |
+| `depends` | Services that must start first (space-separated) |
+
+### Environment Management
+
+Environment variables are injected based on the `--env` flag:
+
+```
+micro run                    # Uses 'development' env (default)
+micro run --env production   # Uses 'production' env
+MICRO_ENV=staging micro run  # Uses 'staging' env
+```
+
+### JSON Alternative
+
+You can also use `micro.json` if you prefer:
+
+```json
+{
+  "services": {
+    "users": { "path": "./users", "port": 8081 },
+    "posts": { "path": "./posts", "port": 8082, "depends": ["users"] }
+  },
+  "env": {
+    "development": { "STORE_ADDRESS": "file://./data" }
+  }
+}
+```
+
+### Without Configuration
+
+If no `micro.mu` or `micro.json` exists, `micro run` discovers all `main.go` files and runs them (original behavior).
+
+## Describe the service
+
+Describe the service to see available endpoints
+
+```
+micro describe helloworld
+```
+
+Output
+
+```
+{
+    "name": "helloworld",
+    "version": "latest",
+    "metadata": null,
+    "endpoints": [
+        {
+            "request": {
+                "name": "Request",
+                "type": "Request",
+                "values": [
+                    {
+                        "name": "name",
+                        "type": "string",
+                        "values": null
+                    }
+                ]
+            },
+            "response": {
+                "name": "Response",
+                "type": "Response",
+                "values": [
+                    {
+                        "name": "msg",
+                        "type": "string",
+                        "values": null
+                    }
+                ]
+            },
+            "metadata": {},
+            "name": "Helloworld.Call"
+        },
+        {
+            "request": {
+                "name": "Context",
+                "type": "Context",
+                "values": null
+            },
+            "response": {
+                "name": "Stream",
+                "type": "Stream",
+                "values": null
+            },
+            "metadata": {
+                "stream": "true"
+            },
+            "name": "Helloworld.Stream"
+        }
+    ],
+    "nodes": [
+        {
+            "metadata": {
+                "broker": "http",
+                "protocol": "mucp",
+                "registry": "mdns",
+                "server": "mucp",
+                "transport": "http"
+            },
+            "id": "helloworld-31e55be7-ac83-4810-89c8-a6192fb3ae83",
+            "address": "127.0.0.1:39963"
+        }
+    ]
+}
+```
+
+## Call the service
+
+Call via RPC endpoint
+
+```
+micro call helloworld Helloworld.Call '{"name": "Asim"}'
+```
+
+## Create a client
+
+Create a client to call the service
+
+```go
+package main
+
+import (
+        "context"
+        "fmt"
+
+        "go-micro.dev/v5"
+)
+
+type Request struct {
+        Name string
+}
+
+type Response struct {
+        Message string
+}
+
+func main() {
+        client := micro.NewService("helloworld").Client()
+
+        req := client.NewRequest("helloworld", "Helloworld.Call", &Request{Name: "John"})
+
+        var rsp Response
+
+        err := client.Call(context.TODO(), req, &rsp)
+        if err != nil {
+                fmt.Println(err)
+                return
+        }
+
+        fmt.Println(rsp.Message)
+}
+```
+
+## Building and Deployment
+
+### Build Binaries
+
+Build Go binaries for deployment:
+
+```bash
+micro build                     # Build for current OS
+micro build --os linux          # Cross-compile for Linux
+micro build --os linux --arch arm64  # For ARM64
+micro build --output ./dist     # Custom output directory
+```
+
+### Deploy to Server
+
+Deploy to any Linux server with systemd:
+
+```bash
+# First time: set up the server
+ssh user@server
+curl -fsSL https://go-micro.dev/install.sh | sh
+sudo micro init --server
+exit
+
+# Deploy from your laptop
+micro deploy user@server
+```
+
+The deploy command:
+1. Builds binaries for linux/amd64
+2. Copies via SSH to `/opt/micro/bin/`
+3. Sets up systemd services (`micro@<service>`)
+4. Restarts and verifies services are running
+
+### Named Deploy Targets
+
+Add deploy targets to `micro.mu`:
+
+```
+deploy prod
+    ssh deploy@prod.example.com
+
+deploy staging
+    ssh deploy@staging.example.com
+```
+
+Then:
+```bash
+micro deploy prod      # Deploy to production
+micro deploy staging   # Deploy to staging
+```
+
+### Managing Deployed Services
+
+```bash
+# Check status
+micro status --remote user@server
+
+# View logs
+micro logs --remote user@server
+micro logs myservice --remote user@server -f
+
+# Stop a service
+micro stop myservice --remote user@server
+```
+
+See [internal/website/docs/deployment.md](../../internal/website/docs/deployment.md) for the full deployment guide.
+
+## API Gateway
+
+Run a standalone HTTP-to-RPC gateway (no dashboard, no auth, no hot reload):
+
+```bash
+micro api                    # listen on :8080
+micro api --address :3000    # custom port
+```
+
+Routes:
+- `POST /{service}/{endpoint}` — proxies to an RPC call
+- `GET /` — lists all services and endpoints
+- `GET /{service}` — describes a service
+- `GET /health` — health check
+
+```bash
+curl -XPOST -d '{"name":"Alice"}' http://localhost:8080/greeter/Greeter.Hello
+```
+
+## Inspecting the Framework
+
+Every core interface has a matching CLI command:
+
+### Registry
+
+```bash
+micro registry list              # list all registered services (JSON)
+micro registry get <name>        # show nodes and endpoints for a service
+micro registry watch             # stream registration events
+```
+
+### Broker
+
+```bash
+micro broker publish <topic> <message>   # publish a message
+micro broker subscribe <topic>           # stream messages from a topic
+```
+
+### Store
+
+```bash
+micro store list [prefix]        # list keys (optionally by prefix)
+micro store read <key>           # read a record
+micro store write <key> <value>  # write a record
+micro store delete <key>         # delete a record
+```
+
+### Config
+
+```bash
+micro config get <key>           # read a config value (dot notation → env var)
+micro config dump                # print all configuration
+```
+
+Keys use dot notation: `database.host` reads from `DATABASE_HOST`.
+
+## AI & Agents
+
+### micro chat
+
+Interactive LLM agent that discovers services and orchestrates them through natural language:
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-... micro chat --provider anthropic
+> list all users
+> send a welcome email to Alice
+```
+
+Supports: `--provider` (anthropic, openai, gemini, atlascloud, groq, mistral, together), `--prompt` for single-shot mode, `--model` and `--base_url` for overrides.
+
+Environment variables: `MICRO_AI_PROVIDER`, `MICRO_AI_API_KEY`, or provider-specific keys like `ANTHROPIC_API_KEY`.
+
+### micro flow
+
+Event-driven LLM orchestration:
+
+```bash
+# Subscribe to events and react
+micro flow run --trigger events.user.created \
+  --prompt "New user: {{.Data}}. Send welcome email." \
+  --provider anthropic
+
+# One-shot execution
+micro flow exec --prompt "List all users" --provider anthropic
+```
+
+### micro mcp
+
+Expose services as MCP tools for AI agents:
+
+```bash
+micro mcp serve              # stdio transport (for Claude Code)
+micro mcp serve --address :3000  # HTTP/SSE transport
+micro mcp list               # list available tools
+micro mcp test <tool>        # test a tool
+```
+
+## Protobuf 
+
+Use protobuf for code generation with [protoc-gen-micro](https://github.com/micro/go-micro/tree/master/cmd/protoc-gen-micro)
+
+## Server
+
+The micro server is a production web dashboard and authenticated API gateway for interacting with services that are already running (e.g., managed by systemd via `micro deploy`). It does **not** build, run, or watch services — for local development, use `micro run` instead.
+
+Run it like so
+
+```
+micro server
+```
+
+Then browse to [localhost:8080](http://localhost:8080) and log in with the default admin account (`admin`/`micro`).
+
+### API Endpoints 
+
+The API provides a fixed HTTP entrypoint for calling services
+
+```
+curl http://localhost:8080/api/helloworld/Helloworld/Call -d '{"name": "John"}'
+```
+See /api for more details and documentation for each service
+
+### Web Dashboard 
+
+The web dashboard provides a modern, secure UI for managing and exploring your Micro services. Major features include:
+
+- **Dynamic Service & Endpoint Forms**: Browse all registered services and endpoints. For each endpoint, a dynamic form is generated for easy testing and exploration.
+- **API Documentation**: The `/api` page lists all available services and endpoints, with request/response schemas and a sidebar for quick navigation. A documentation banner explains authentication requirements.
+- **JWT Authentication**: All login and token management uses a custom JWT utility. Passwords are securely stored with bcrypt. All `/api/x` endpoints and authenticated pages require an `Authorization: Bearer <token>` header (or `micro_token` cookie as fallback).
+- **Token Management**: The `/auth/tokens` page allows you to generate, view (obfuscated), and copy JWT tokens. Tokens are stored and can be revoked. When a user is deleted, all their tokens are revoked immediately.
+- **User Management**: The `/auth/users` page allows you to create, list, and delete users. Passwords are never shown or stored in plaintext.
+- **Token Revocation**: JWT tokens are stored and checked for revocation on every request. Revoked or deleted tokens are immediately invalidated.
+- **Security**: All protected endpoints use consistent authentication logic. Unauthorized or revoked tokens receive a 401 error. All sensitive actions require authentication.
+- **Logs & Status**: View service logs and status (PID, uptime, etc) directly from the dashboard.
+
+To get started, run:
+
+```
+micro server
+```
+
+Then browse to [localhost:8080](http://localhost:8080) and log in with the default admin account (`admin`/`micro`).
+
+> **Note:** See the `/api` page for details on API authentication and how to generate tokens for use with the HTTP API
+
+## Gateway Architecture
+
+The `micro run` and `micro server` commands both use a unified gateway implementation (`cmd/micro/server/gateway.go`), providing consistent HTTP-to-RPC translation, service discovery, and web UI capabilities.
+
+### Key Differences
+
+| Feature | `micro run` | `micro server` |
+|---------|-------------|----------------|
+| **Purpose** | Development | Production |
+| **Authentication** | Enabled (default `admin`/`micro`) | Enabled (default `admin`/`micro`) |
+| **Process Management** | Yes (builds/runs services) | No (assumes services running) |
+| **Hot Reload** | Yes (watches files) | No |
+| **Scopes** | Available (`/auth/scopes`) | Available (`/auth/scopes`) |
+| **Use Case** | Local development | Deployed API gateway |
+
+### Why Unified?
+
+Previously, each command had its own gateway implementation, leading to code duplication. The unified gateway means:
+
+- New features (like MCP integration) benefit both commands
+- Consistent behavior between development and production
+- Single codebase to test and maintain
+- Same HTTP API, web UI, and service discovery logic
+
+### Gateway Features
+
+Both commands provide:
+
+- **HTTP API**: `POST /api/{service}/{endpoint}` with JSON request/response
+- **Service Discovery**: Automatic detection via registry (mdns/consul/etcd)
+- **Health Checks**: `/health`, `/health/live`, `/health/ready` endpoints
+- **Web Dashboard**: Browse services, test endpoints, view documentation
+- **Hot Service Updates**: Gateway automatically picks up new service registrations
+- **JWT Authentication**: Tokens, user management, login at `/auth/login`, `/auth/tokens`, `/auth/users`
+- **Endpoint Scopes**: Restrict which tokens can call which endpoints via `/auth/scopes`
+- **MCP Integration**: AI tools at `/mcp/tools`, agent playground at `/agent`
+
+### Authentication & Scopes
+
+Both `micro run` and `micro server` use the same `auth.Account` type from the go-micro framework. The gateway stores accounts under `auth/<id>` in the default store and uses JWT tokens with RSA256 signing.
+
+**Scope enforcement** applies to all call paths:
+
+| Path | Description |
+|------|-------------|
+| `POST /api/{service}/{endpoint}` | HTTP API calls |
+| `POST /mcp/call` | MCP tool invocations |
+| Agent playground | Tool calls made by the AI agent |
+
+Scopes are configured via the web UI at `/auth/scopes`. Each endpoint can require one or more scopes. A token must carry at least one matching scope to call a protected endpoint. The `*` scope on a token bypasses all checks. Endpoints with no scopes set are open to any authenticated token.
+
+See the [Scopes](#scopes) section below for details.
+
+### Development Mode (`micro run`)
+
+```bash
+micro run  # Auth enabled, default admin/micro
+```
+
+- Authentication enabled with default credentials (`admin`/`micro`)
+- Web UI requires login
+- Scopes available for testing access control
+- Ideal for development with realistic auth behavior
+
+### Production Mode (`micro server`)
+
+```bash
+micro server  # Auth enabled, JWT tokens required
+```
+
+- JWT authentication on all API calls
+- User/token management via web UI
+- Secure by default
+- Login required: default credentials `admin/micro`
+
+### Programmatic Gateway Usage
+
+You can also start the gateway programmatically in your own Go code:
+
+```go
+import "go-micro.dev/v5/cmd/micro/server"
+
+// Start gateway with auth (recommended)
+gw, err := server.StartGateway(server.GatewayOptions{
+    Address:     ":8080",
+    AuthEnabled: true,
+})
+
+// Start gateway without auth (testing only)
+gw, err := server.StartGateway(server.GatewayOptions{
+    Address:     ":8080",
+    AuthEnabled: false,
+})
+```
+
+See [`internal/website/docs/architecture/adr-010-unified-gateway.md`](../../internal/website/docs/architecture/adr-010-unified-gateway.md) for architecture details.
+
+### Scopes
+
+Scopes provide fine-grained access control over which tokens can call which service endpoints. They are managed through the web UI at `/auth/scopes` and enforced on every call through the gateway.
+
+#### How It Works
+
+1. **Define scopes on endpoints** — Visit `/auth/scopes` and set required scopes for each service endpoint (e.g., set `billing` on `payments.Payments.Charge`)
+2. **Create tokens with scopes** — Visit `/auth/tokens` and create tokens with matching scopes (e.g., a token with `billing` scope)
+3. **Scopes are enforced** — When a token calls an endpoint, the gateway checks that the token has at least one scope matching the endpoint's required scopes
+
+#### Scope Matching Rules
+
+- Scopes are **exact string matches** — `billing` on a token matches `billing` on an endpoint
+- A token with `*` scope bypasses all scope checks (admin wildcard)
+- Endpoints with **no scopes set** are open to any valid token
+- An endpoint can require **multiple scopes** — the token needs to match just one
+- Scope names are free-form strings — use whatever convention fits your project
+
+#### Common Patterns
+
+| Pattern | Endpoint Scopes | Token Scopes | Result |
+|---------|----------------|--------------|--------|
+| Protect a service | Set `greeter` on all greeter endpoints (use Bulk Set with `greeter.*`) | Token with `greeter` | Token can call any greeter endpoint |
+| Restrict an endpoint | Set `billing` on `payments.Payments.Charge` | Token with `billing` | Only that endpoint is restricted |
+| Role-based | Set `admin` on sensitive endpoints | Admin token with `admin`, user token with `user` | Only admin tokens can call sensitive endpoints |
+| Full access | Any | Token with `*` | Bypasses all scope checks |
+
+#### Relationship to Framework Auth
+
+The gateway's scope system uses `auth.Account` from the go-micro framework. Scopes on accounts are the same `[]string` field used by the framework's `auth.Rules` and `wrapper/auth` package. The gateway stores scope requirements in the default store under `endpoint-scopes/<service>.<endpoint>` keys and checks them on every HTTP request.
+
+For service-level (RPC) auth within the go-micro mesh, use the `wrapper/auth` package which provides `auth.Rules` with priority-based access control. See the [auth wrapper documentation](../../wrapper/auth/README.md) for details.
+
+## Self-improving loop (`micro loop`)
+
+Turn a repository into a self-improving one: GitHub Actions workflows that
+dispatch a coding agent to plan, build, and triage — gated by CI. This is the
+same loop that maintains go-micro itself, generalized so any repo (and any
+@mention-driven agent) can use it.
+
+```bash
+micro loop init      # scaffold the loop into the current repo
+micro loop verify    # check a repo is wired correctly
+```
+
+`micro loop init` writes the selected roles' workflows, their prompts, and a queue. Choose roles with `--roles` (default `planner,builder,triage`; `--roles all` for everything):
+
+| Role | Workflow | What it does |
+|------|----------|--------------|
+| Planner | `loop-planner.yml` | Keeps a ranked queue in `.github/loop/PRIORITIES.md` |
+| Builder | `loop-builder.yml` | Builds the top open item as a single-concern PR, auto-merged on green CI |
+| Triage | `loop-triage.yml` | Turns CI failures into scoped fix issues, back into the queue |
+| Coherence | `loop-coherence.yml` | Keeps README/docs/CHANGELOG aligned with the North Star *(opt-in)* |
+| Security | `loop-security.yml` | Audits for vulnerabilities and files them; never auto-merges fixes, never publishes exploit detail *(opt-in)* |
+| Release | `loop-release.yml` | Cuts the next patch tag when the branch has new commits *(opt-in)* |
+
+The workflows are the **mechanism**; each dispatch role's instruction is an editable file in `.github/loop/prompts/` — the **policy**. Edit those prompts (and `.github/loop/NORTH_STAR.md`) to steer the loop without touching the CLI. That split is what lets go-micro itself use `micro loop` while keeping its own richer prompts.
+
+Common flags:
+
+```bash
+micro loop init \
+  --roles all \
+  --agent @codex \
+  --token-secret LOOP_TOKEN \
+  --branch main \
+  --ci-workflow CI
+```
+
+- `--roles`: which roles to scaffold (`planner,builder,triage`, or `all`)
+- `--agent`: how the workflows summon the agent — any `@mention`-driven coding agent (e.g. `@codex`, `@claude`)
+- `--token-secret`: repo secret holding the driving user PAT
+- `--branch`: base branch for the loop's PRs
+- `--ci-workflow`: `name:` of the CI workflow triage watches
+- `--tag-prefix`: tag prefix the release role matches and bumps (default `v`)
+
+Two things the CLI can't do for you (and `micro loop verify` reminds you of):
+
+1. **Add the token secret.** The agent ignores `@mentions` from the
+   `github-actions` bot, so dispatch posts as a real user via a PAT stored in
+   the `--token-secret` repo secret. The workflows no-op until it's set.
+2. **Set branch protection.** Require the CI checks with **0 approving reviews**
+   so the builder's native auto-merge lands PRs the moment CI is green — that
+   green-CI gate is the loop's only safety mechanism, so keep the suite strong.