* test(install): reproduce loss of pulled tracked records Exercise the two-machine push and pull sequence and reconciliation states so missing tracked clones cannot silently erase shared install intent. * fix(reconcile): preserve tracked records missing local clones Pull transfers tracked repository metadata but not ignored clones. Keep the missing records during global reconciliation so another install and push cannot erase shared intent or accepted audit findings on every machine. * test(reconcile): isolate tracked record fixtures Use the shared sandbox fixture for both reconciliation tests so their home and configuration paths remain isolated from the invoking environment. * fix(reconcile): retain all sourced tracked declarations Legacy tracked members and unfollowed source links can hide declarations from the local walk. Preserve sourced tracked records regardless of their path so unrelated installs cannot erase them or their audit acceptances. Document restoring a missing checkout before uninstalling it and cover migration, link collisions, aliases, and explicit removal. * test(reconcile): drop fixtures existing tests already pin The tracked-record unit test also seeded a missing plain record and a live plain record. TestReconcileGlobalSkills_PrunesStaleEntries already pins both outcomes: a sourced plain record whose folder is gone is pruned, and one on disk survives. The tracked record with no source still catches a fix that keeps everything or skips the prune. The two-machine test passed HOME and SKILLSHARE_CONFIG to RunCLIEnv, which already sets both from the sandbox for each child process. Separate homes, XDG paths, client overrides and git config remain. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(reconcile): retain tracked entry for unavailable link Expect sourced tracked declarations to survive reconciliation with either source-link policy, so the test matches the cross-machine retention contract. * fix(config): prune legacy tracked members Retain only sourced tracked repository declarations during reconciliation. Migrated member records are not restorable as repositories and retaining them would leave permanent misleading install requests and audit acceptances. * fix(reconcile): preserve tracked intent across followed links A source link can exist before a tracked repository declaration is pulled. Preserve that declaration when the linked folder is not a checkout so later reconciliation does not discard its record and audit acceptances. * test(reconcile): cover grouped followed declarations A followed group can contain the path of a pulled legacy repository declaration, which must retain its tracked intent while its key migrates. * fix(test): scope collision fixture runner correctly Keep the isolated CLI runner in the collision subtest that uses it so the integration test package can compile. * docs(manifest): clarify tracked checkout recovery A retained declaration cannot restore a checkout while another folder or source link occupies its destination, and restoration requires a reachable source. State those prerequisites in each manifest translation. * fix(config): prune members under recorded repositories A migrated underscore-named member can otherwise survive a missing checkout as a repository declaration. Check recorded ancestor paths while preserving ambiguous grouped declarations and unrelated aliases. * docs(manifest): restore fresh-clone project guidance Explain that project declarations without local install records remain available so teammates can install them after cloning. * refactor(reconcile): drop the tracked-intent walker policy Restore baseline normalization for present paths while retaining absent repository declarations through the shared metadata predicate. Isolate the reconcile fixtures without building a CLI and share native-client overrides without changing the original two-machine record and audit regression. Validation: gofmt, git diff --check and context-router check only. Runtime, builds and tests were not executed under the source-only gate. * fix: forget linked checkout records and declarations without checkouts Extend the metadata and uninstall owners to remove a declaration without reading or moving its occupant, contacting its source, or changing trash and gitignore. A failed metadata save makes every metadata-only result fail. Clean up global unlink records in CLI and API, preserve existing-path name precedence, report record-only results truthfully, and list declarations in the dashboard API with noCheckout. Keep project removal behavior unchanged. Remove the obsolete grouped-link walker-policy assertion while preserving grouped absent declarations and the original record/audit A/B regression. Validation: source-only five-pass review, gofmt, git diff --check and the context-router check. No runtime, builds, tests or frontend tooling ran. Stop at commit 15 for the mandatory Luna checkpoint before UI and docs work. * fix(server): reload metadata before removing declarations Preserve CLI records and audit acceptances written while the dashboard is open. Resolve new declarations from disk and refuse stale-cache saves after a reload failure, retaining unlink success when its link already moved. * feat(dashboard): remove a tracked repository record without a checkout Show declaration-only rows without checkout actions or status promises. Reuse Uninstall with record-specific confirmation and feedback, keep real-checkout force handling, and refresh the missing-entry list after repository removal or unlink. * docs: explain kept declarations and how to remove them Document direct global declaration removal and optional restore in English and all four translations, including occupied paths and normalization after reconcile. Keep built-in guidance accurate and use the existing API removal result for dashboard success feedback after concurrent CLI changes. * fix(dashboard): confirm restored checkouts after forceable refusals A tracked declaration can be restored through the CLI while its dashboard row still says there is no checkout. Treat a forceable uninstall refusal as evidence of the current checkout and promote the existing confirmation to its dirty or unreadable-status warning before allowing explicit force. Author stale-row regressions for both forceable codes before the source repair, and retain nonforceable failure and actual-result success feedback. Validation: five serial source review passes, git diff --check, and the context-router check. Tests, builds, runtime and frontend tooling were not run under the source-only gate. * test(server): persist overview declarations before routed request The overview fixture added declarations only to the in-memory skills store, which the real request's config reload replaced with on-disk metadata. The hosted unit, offline, and Nix jobs consequently returned no tracked rows. Save the complete fixture through MetadataStore before serving the request and fail setup on a save error. Keep the middleware, assertions, and production behavior unchanged. * fix(server): prefer exact declarations before checkout shorthand Removing a missing _team declaration from the dashboard could resolve the different org/_team checkout by basename and trash it instead. Reload metadata before declaration lookup, give exact declarations priority, and preserve checkout resolution before non-exact declaration fallback. Add routed absent/occupied regressions and checkout precedence guards, and persist existing checkout fixtures so the metadata reload keeps their state. Validation: gofmt, git diff --check, and context-router check passed. Tests were authored but not run under the source-only fleet restriction. * fix: preserve removal intent and report partial failures Bind dashboard record-only removal to its canonical declaration and refuse restored checkouts before checkout resolution or force. Refresh the row and require another confirmation before moving a restored checkout to trash. Keep unresolved uninstall inputs and their reasons in JSON failed results, including all-invalid requests, partial successes and dry runs. Report unlink metadata cleanup failures as partial results, refresh completed unlinks and show localized warnings. Keep CLI and dashboard guidance aligned. Regression tests were authored before source changes and remain unrun under the source-only task restriction. Static formatting, diff and router checks passed; no build, product runtime, frontend tooling or test suite was run. * fix(unlink): log partial metadata cleanup failures Write the unlink result after global metadata cleanup so load and save failures retain their diagnostic and report partial success. Preserve the successful link removal, warning, target and exit policy, and the existing link, project unlink and native removal failure behavior. Add the corrupt-metadata regression before the fix; leave it unrun under the source-only authorization. Formatting, diff and context-router checks pass; runtime verification remains with the coordinator. * fix(unlink): forget records below the removed link name Reconcile can normalize a followed link's record to untracked, and linked collections can retain nested repository declarations. Clean the removed namespace through the existing metadata path owner in both unlink callers, including audit acceptances, while keeping declaration uninstall strict. Author CLI and route regressions before the source fix for normalized and nested records, sibling preservation, and subsequent bare install. Tests remain unrun under the source-only task restriction; static checks only. * fix(uninstall): refuse a restored checkout at execution A declaration selected while absent can become a checkout before removal runs. Recheck the resolved source-relative name in the shared metadata-only execution owner and refuse before touching metadata, regardless of force. Reuse the existing dashboard conflict response and refresh/reselection flow for this refusal, preserving the earlier record-only intent guard. CLI results already carry shared execution failures through text and JSON. Author restoration, force, absent/occupied control and client boundary regressions before production edits. Correct the unlink fixture name and response-key assertion found in serial static review. All tests remain unrun under the source-only restriction; formatting/diff/router checks pass. * refactor(server): consolidate repository uninstall result handling Resolve a declaration or checkout to one item and canonical name before using the existing uninstall, conflict, log and success response tail. Keep metadata-only removal unforced, preserve its error and cache recovery behavior, and report movedToTrash from the selected item. Preserve exact declaration precedence, record-only checkout refusals, ordinary checkout errors and project behavior without changing tests. Five serial source review passes, gofmt, diff checks and the context-router check completed. Tests and builds remain unrun under the source-only brief. * fix(unlink): preserve independent records and trash undo metadata Limit unlink's legacy group matching to members so a retained declaration such as team/_repo survives unlinking _team. Share snapshot and removal matching while keeping generic uninstall's legacy contract unchanged. Save the exact removed records, audit acceptances and target overrides through uninstall's existing trash sidecar owner before pruning metadata. Keep metadata on sidecar failure and preserve completed-unlink warnings, fresh reloads, cache refresh and project-mode behavior. Author owner, CLI and API regressions for namespace collisions, undo, partial failures and project/empty controls. Source-only verification: gofmt, diff check and context-router check passed; runtime tests, builds, frontend checks and final make check remain unrun for root-owned gates. * fix(install): preserve independent tracked declarations Limit declaration-only cleanup to the precise namespace and legacy members already used by unlink. Keep independently installed prefixed repositories, their audit acceptances, and overrides when forgetting a missing checkout. * fix(cli): explain missing tracked repository recovery by mode Offer global record removal when restoring an unreachable source is unwanted. Keep project recovery scoped to install -p, share the hint with doctor, and align update documentation in every existing locale. * refactor(uninstall): share declaration and unlink operations Keep declaration resolution and unlink metadata ordering in shared owners so CLI and API preserve the same scope and recovery behavior. Consolidate domain regressions while retaining caller translation coverage. Distinguish record-only removals in API and CLI operation logs and CLI JSON, including mixed batches and dry runs. Document outcome fields, warning semantics, and current API error codes across existing locales. --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Willie <egg358358@gmail.com>
12 KiB
CLI Development
Use when adding or changing Go CLI commands, flags, handlers, interactive TUIs, domain packages, or any mutating behavior.
Before Starting
- Search for the closest existing command pattern instead of guessing APIs from memory or documentation.
- List affected command, domain, test, schema, documentation, and Web API files.
- Define acceptance criteria before changing public behavior. Ask only when ambiguity would materially change scope or interfaces.
- Use TDD: create a reproducible failing test, then write the smallest implementation that passes it.
Command Layering
cmd/skillshare/<command>.go should contain only flag parsing, validation, and mode dispatch. When a handler approaches roughly 300 lines or mixes concerns, split it using existing suffixes:
| Suffix | Responsibility |
|---|---|
_handlers.go |
Core orchestration |
_project.go |
Project-mode behavior |
_render.go / _format.go |
Output rendering and formatting |
_prompt.go / _prompt_tui.go |
Decisions and prompts |
_tui.go |
Full-screen Bubble Tea UI |
_batch.go |
Batch orchestration |
_resolve.go |
Target/resource resolution |
_context.go |
Mode-specific context |
Put testable core logic in internal/<domain>/. Do not let the CLI, Web API, and UI implement separate versions of the same business logic.
Global and Project Mode
Most commands route through parseModeArgs() for global (-g) or project (-p) mode. Pass the command's value-taking option names and aliases as additional arguments (for example, parseModeArgs(args, "--name")) so their values cannot become mode flags. Do not include optional-value flags that reject a following flag, such as search --hub. The parser preserves -- and everything after it for the command parser. Before changing behavior, verify:
- whether the modes use different configuration, registry, source, or target paths;
- whether project mode needs a separate handler;
- whether their flag sets are actually the same;
- whether tests cover mode precedence, working directory, and missing configuration.
Output and Interaction
- Ask inline questions with
internal/ui/prompt.go(Select,MultiSelect,Confirm,Input, built onhuhwith theme colors); keep full-screen Bubble Tea components for browsing lists. Do not add another prompt framework. - Full-screen TUIs share the frame in
cmd/skillshare/tui_frame.go: a title line (skillshare <cmd> · scope · counts, tabs on the right), the list and its details side by side without divider lines, and one key line with the position on the right. Show only the common keys there and the rest under?; ask confirmations and take filter input on the key line, not on a separate screen.escclears the filter, then goes back, then quits. Action keys are lowercase with one meaning per letter:dremove,uupdate,ssync,eedit settings,nnew,iimport,ccollect,rrestore,tenable/disable,mmanual only,osort,!audit. Uppercase is only for whole-set actions such asDempty trash, always with a confirmation. Screenshot every changed TUI withscripts/screenshots/record-tui.sh. - A question asked without a terminal takes its default. Print each decision with the flag that changes it instead of failing or silently doing less.
- Confirm a single action (remove, delete, apply anyway) with
ui.ConfirmAction: esc answers no, and a decline printsui.Cancelled("removed"). Without a terminalui.Confirmreads one line from stdin (y/yes,n/no, anything else is the default), soecho y | skillshare …keeps working. - Print results with
internal/ui/rows.go:ui.Row(mark, label, value, ui.RowWidth(labels...))per item (✓/!/✗, orui.MarkNonefor plain information),ui.Sectionfor a bold block name,ui.Donefor the closing line with its duration,ui.Notefor dim detail andui.Nextfor up to three follow-up commands. Leave zero counts out. Integration tests match a row withAssertRowContains(t, label, value). - Preserve dispatch order: structured JSON → TUI when interactive and allowed → empty state → plain text.
- Structured-output stdout must remain machine-readable; progress, spinners, and diagnostics must not contaminate JSON.
- When adding or changing a flag, inspect
--help, completions, website command documentation, and tests. - Completions are five hand-written scripts (
cmd/skillshare/completion_{bash,zsh,fish,powershell,nushell}.go) that do not read the CLI's dispatch, so they drift silently. Any new or renamed command, subcommand, or flag must be added to all five in the same change; the literal-content check intests/integration/completion_test.goshould name it. Installed completions are a copy, so users only see changes after rerunningskillshare completion <shell> --install. - Noninteractive automation should use explicit flags. Never treat
--forceas a universal prompt bypass.
Mutating Behavior
Operations that change configuration, sources, targets, or managed files must:
- follow existing dry-run, backup, rollback, and conflict-handling patterns;
- write an oplog entry to
operations.logwith the operation, status, duration, and necessary arguments; - send security scan events to the audit log rather than the regular operation log;
- preserve path validation, scope checks, and ownership checks;
- use domain uninstall/remove flows for managed state rather than replacing them with filesystem deletion. Skills, tracked repos and agents go through
internal/uninstall(Preflight,Run,Agents): it owns the move-out check, the dirty check for tracked repos, the move to trash,.gitignorecleanup and the metadata prune (MetadataStore.RemoveByNames), keeping a copy of the pruned metadata beside the trash entry. Restore goes throughuninstall.Restore/RestoreAgent, which put that copy back, and permanent deletion throughtrash.Delete; never calltrash.Restoreoros.RemoveAllon a trash entry directly. The CLI and the dashboard handlers useuninstall.ResolveNamefor exact declaration → disk → declaration shorthand selection, then report its per-item results; - write the skills source through
internal/sourcefs, which refuses paths with a link component unless the operation's*sourcewalk.Followpolicy (built byconfig.SkillsWalkwhenfollow_source_linksis on) resolves a first-level link; such paths are rebased onto the link target with the same escape checks. The ratchet ininternal/sourcefs/ratchet_test.gofails on any new rawoswrite call until it gets a truthful reason intestdata/raw_writes.tsv; - create first-level source links through
internal/sourcelink(Createprechecks withsourcewalk.Follow.Allow;Discardrolls back a link whose follow-up step failed). Unlink goes throughinternal/uninstall.Unlink: it moves only the link to trash viasourcelink.Remove, then in global mode reloads metadata, saves its undo copy beside the trash entry before pruning, and reloads the cache after cleanup failure. Project unlink leaves metadata alone. Callers report completed removal with a partial warning if metadata cleanup fails.uninstall <link>is refused when the linked folder itself is a skill; - read the skills source through
internal/sourcewalkand pass the samesourcewalk.Optionsthe operation's discovery used, so CLI, dashboard, and reconcile agree on which first-level links are followed. The ratchet ininternal/sourcewalk/guard_test.gofails on any new raw walk until it is listed inallowlist.json; - run git through
internal/gitenv(Command,CommandContext,Environ), which dropsGIT_DIRand the other repository variables a git hook exports, so skillshare started from a hook never works on the hook's repository (#852).TestNoRawGitCommandsininternal/gitenvfails on any newexec.Command("git", ...)outsideinternal/gitenv,internal/hooks(its own sanitized environment) andinternal/testutil.
Tests
Integration tests use internal/testutil.NewSandbox(t) and RunCLI or RunCLIInDir:
func TestFeature_BasicCase(t *testing.T) {
sb := testutil.NewSandbox(t)
defer sb.Cleanup()
sb.CreateSkill("test-skill", map[string]string{
"SKILL.md": "---\nname: test-skill\n---\n# Content",
})
result := sb.RunCLI("command", "args...")
result.AssertSuccess(t)
result.AssertOutputContains(t, "expected output")
}
For a bug fix, prove that the test fails before the fix. Add an E2E runbook in ai_docs/tests/<slug>_runbook.md for new commands, install/uninstall/sync flows, security behavior, multi-step workflows, or OS/network/permission cases that integration tests cannot cover.
All command execution and isolation rules live in testing. Never run the CLI or tests on the host.
The Nix flake also runs the unit tests, inside the Nix sandbox, which has /bin/sh but no /bin/bash or /usr/bin/env. A change to go.sum also needs a new vendorHash; see release.
Web API
When a dashboard endpoint is needed:
- Use existing
writeJSONandwriteErrorhelpers ininternal/server/handler_<name>.go. Decode request bodies withdecodeJSONordecodeJSONWith(internal/server/json_body.go), which cap the body size and return 413 when it is too large; do not calljson.NewDecoder(r.Body)directly. - Register the method and route in
internal/server/server.go. - Handle scope explicitly through
s.IsProjectMode()or the existing guards. - Add handler tests and verify UI client types and query invalidation.
- Share an
internal/package when the CLI and API expose the same operation; do not shell out between them.
Sync is the main example: the CLI and the server both run per-target sync through internal/sync (SyncSkillTarget, RunAgentSync, RunExtraTargets). Both follow CLI semantics: every target runs, and a failed target is reported as a partial failure instead of stopping the loop. Change sync behavior in these runners, not in a command or handler loop.
Updating one tracked repo is another: both call update.TrackedRepo (internal/update), which checks for uncommitted changes, pulls into an isolated candidate (install.StageGitUpdate), audits it, publishes its exact approved commit, and refreshes metadata. Rejection never resets or changes the active checkout. It, install --track --update, and the in-place pull of a git-installed skill (install.handleUpdate) hold install.LockCheckout, so concurrent skillshare processes take turns on one checkout. A forced git-installed skill update fetches and then resets to upstream, so its local edits are gone once the fetch succeeds, even if the audit then rolls back. install --track --update shares this candidate mechanism. Candidates preserve sparse-checkout selection and audit metadata; unresolved or escaping symlinks fail closed. install.GitCheckoutRecovery shares partial-checkout cleanup between ordinary pulls and candidate publication, preserving pre-existing dirty paths. Candidate diffs are captured before publication so CLI confirmation does not depend on unpublished objects being available in the active checkout. The gate is fail-closed: a scan that cannot run is never overridden by force. Findings an earlier override accepted are always honored, and an override records the ones it lets through. Callers only choose inputs (Confirm) and word the result; change the sequence in the operation, not in a command or handler.
Completion Criteria
- The failing test now passes, along with proportionate neighboring tests.
- Handler split, dual-mode behavior, structured output, oplog, Web API, and all five shell completions were reviewed.
- Public behavior changes were synchronized after loading
documentation. - Commands were verified inside the devcontainer using
testingguidance.