feat: add fullsend admin CLI with install/uninstall/analyze

[ralphbean]

Summary

Implements the fullsend admin CLI to deliver the installation and bootstrap workflow described in #124. An org administrator runs a single command to onboard their organization: the CLI creates a .fullsend config repo with safe defaults, sets up CI workflows and CODEOWNERS, stores agent app credentials as secrets, and opens enrollment PRs on enabled repos — nothing changes in any repo until those PRs are reviewed and merged.

Two architectural choices shape the implementation:

1. Forge abstraction via interfaces — All git forge operations go through a forge.Client interface, making it straightforward to add GitLab and Forgejo support alongside the current GitHub implementation.

2. Layered install/uninstall/analyze model — Installation is decomposed into ordered layers (config-repo → workflows → secrets → enrollment), each implementing Install, Uninstall, and Analyze methods. This enables the analyze subcommand to report exactly what's installed, what's missing, and what install would do.

CLI Structure

fullsend admin install <org>    # Set up fullsend for an org
fullsend admin uninstall <org>  # Tear down fullsend from an org
fullsend admin analyze <org>    # Assess installation status

Demo

demo-reduced.mp4

Architecture

Forge Abstraction (internal/forge/)

• forge.Client interface with 17 methods covering repos, files, branches, PRs, secrets, workflows, and app installations
• forge.FakeClient — thread-safe test double with error injection and call recording
• forge/github.LiveClient — GitHub REST API implementation with NaCl secret encryption

Layer Model (internal/layers/)

• Layer interface: Name(), Install(), Uninstall(), Analyze()
• Stack processes layers in order (install) or reverse order (uninstall)
• ConfigRepoLayer — creates/manages the .fullsend config repository
• WorkflowsLayer — manages CI workflow files and CODEOWNERS
• SecretsLayer — stores agent app credentials as repo secrets/variables
• EnrollmentLayer — creates enrollment PRs for enabled repos

Other Packages

• internal/config/ — OrgConfig types, YAML marshal/unmarshal, validation
• internal/appsetup/ — GitHub App manifest flow for per-role agent apps
• internal/ui/ — Styled terminal output via lipgloss
• internal/cli/ — Cobra CLI with admin subcommand group

Test Coverage

All packages have unit tests:

• forge — 100% coverage (fake client with race detector)
• config — 94.3% coverage
• layers — 91.0% coverage (all 5 layer implementations tested)
• forge/github — 80.5% coverage (httptest-based API tests)
• appsetup — 41.5% (manifest flow partially tested due to browser interaction)
• ui — 100% coverage

Verification

• go test ./... -count=1 -cover -race — all pass
• go vet ./... — clean
• go build -o bin/fullsend ./cmd/fullsend/ — builds successfully

[ralphbean]

Somehow, I totally forgot about the vertex api credentials. We're going to need those.

At this point, if you're all okay with the outline of this, I'd prefer to get it merged and follow up with that detail in a patch PR on top.

[waynesun09]

Demo / code mismatch, credential scoping, and architectural concerns

1. Demo video shows v6 branch behavior, not the merged code

The demo video demonstrates workflow_dispatch + FULLSEND_DISPATCH_TOKEN (PAT) from the unmerged agent-admin-cli-clean-room-v6 branch. The merged code uses workflow_call:

	Merged code (main)	Demo video (v6)
Dispatch mechanism	workflow_call (reusable workflow)	workflow_dispatch (via gh workflow run)
Shim references	secrets.FULLSEND_FULLSEND_APP_PRIVATE_KEY	secrets.FULLSEND_DISPATCH_TOKEN
Agent runs in	Caller's context (target repo)	.fullsend repo
Shim trigger protection	pull_request	pull_request_target (fork-safe)
Secret type	App PEM passed cross-repo	Fine-grained PAT (Actions:write on .fullsend only)

The demo action run at ralphflux/test-repo/actions/runs/23916426574 shows the v6 shim dispatching to .fullsend, with the real agent workload at ralphflux/.fullsend/actions/runs/23916429888. This two-hop flow doesn't exist in the merged code.

2. Merged code: PEM stored in .fullsend repo secrets is inaccessible from target repo workflows

The merged SecretsLayer stores App PEMs as repo-level secrets on .fullsend:

// internal/layers/secrets.go
s.client.CreateRepoSecret(ctx, s.org, ".fullsend", sName, agent.PEM)

But with workflow_call, the agent workload runs in the caller's context (the target repo). The shim in acme/integration-service references:

secrets:
  APP_PRIVATE_KEY: ${{ secrets.FULLSEND_FULLSEND_APP_PRIVATE_KEY }}

This expression resolves in acme/integration-service's secret scope — it cannot see .fullsend's repo secrets. The secret will be empty at runtime.

Fix: Use CreateOrgSecret with visibility: "selected" scoped to enrolled repo IDs. The GitHub REST API supports this via PUT /orgs/{org}/actions/secrets/{name} with selected_repository_ids. The v6 branch already added CreateOrgSecret / SetOrgSecretRepos to the forge interface — those methods would apply here, just storing the PEM instead of the dispatch token.

3. v6 architecture: centralizing agent workload in .fullsend creates observability friction

The v6 workflow_dispatch model runs all agent execution in .fullsend. While this solves credential isolation (PEMs stay as .fullsend repo secrets):

• Observability friction — target repo maintainers must navigate to .fullsend's Actions tab to see agent execution details. The GitHub Actions UI has no filter for workflow_dispatch input values, so runs from all enrolled repos are interleaved. This is mitigable with run-name: "[${{ inputs.source_repo }}] ${{ inputs.event_type }}" to make source repos visible in the list, but maintainers still need .fullsend repo access and awareness to find their runs.
• No target-repo runner access — the agent runs on .fullsend's runners, not the target repo's self-hosted runners or environment. Running the target repo's test suite requires cloning from .fullsend's runner context, losing any repo-specific runner configuration.

4. v6 dispatch token (PAT) has lifecycle concerns

The v6 branch requires an org admin to manually create a fine-grained PAT (promptDispatchToken opens a browser for token creation):

• Tied to a human account — if that person leaves the org or their account is disabled, the dispatch token dies and all enrolled repos stop dispatching.
• Manual rotation — fine-grained PATs expire (max 1 year). No automated rotation path.
• Scope creep risk — the CLI pre-fills actions=write scoped to .fullsend, but nothing prevents the admin from creating a PAT with broader permissions.
• Audit trail — PAT usage shows up as the human user's actions in audit logs, making agent-triggered dispatches indistinguishable from human actions.

Alternative worth considering: use the GitHub App installation token (already available from the per-role Apps) to trigger the dispatch, eliminating the need for a stored PAT entirely.