Monorepo for @alexgorbatchev/dotfiles. Go implementation (pkg/, cmd/dotfiles/) with Preact dashboard client (packages/dashboard/).
- Prepare a fresh clone or worktree:
just setup(Bun dependencies, Go modules, embedded assets viajust prepare, fixturestate generate) - Default action (run tests without compile):
just - Run CLI:
just run(e.g.just run --help,just run --config /path/to/dotfiles.config.ts generate) - Run CLI against fixture project:
just test-project(runsstate generateby default, orjust test-project state diff, etc.) - Install deps:
bun install --frozen-lockfile - Format & autofix:
just fix(orbun fix) - Lint:
just lint(orbun lint) - Typecheck:
just typecheck(orbun typecheck) - Check skill documentation links, anchors and page reachability:
just docs-links(runsscripts/check-docs-links.ts) - Go unit tests:
just test-unit(orgo test ./pkg/... ./cmd/... ./scripts/...) - Go E2E tests:
just test-e2e(orgo test -p 1 ./tests/e2e/...) - TypeScript tests:
just test-ts(orbun test) - Full release build, end to end:
just test-build(runsTestRunBuildbehind thebuildtesttag) - All tests:
just test(Go unit, Go E2E and TypeScript) - Full check:
just check(orbun check) - Build / compile binaries:
just compile(orbun compile) - CLI against fixture project:
go run ./cmd/dotfiles --config test-project/dotfiles.config.ts state generate - Dashboard server against fixture:
just dashboard(orgo run ./cmd/dotfiles --config test-project/dotfiles.config.ts dashboard) - Deploy local dev build into dotfiles directory:
just dev-bootstrap(orjust dev-bootstrap /path/to/target)
- CLI entrypoint:
cmd/dotfiles/->cmd/dotfiles/AGENTS.md - Dashboard workspace:
packages/dashboard/->packages/dashboard/AGENTS.md - Go arch package:
pkg/arch/->pkg/arch/AGENTS.md - Go archive package:
pkg/archive/->pkg/archive/AGENTS.md - Go backup package:
pkg/backup/->pkg/backup/AGENTS.md - Go block package:
pkg/block/->pkg/block/AGENTS.md - Go cliout package:
pkg/cliout/->pkg/cliout/AGENTS.md - Go config package:
pkg/config/->pkg/config/AGENTS.md - Go dashboard package:
pkg/dashboard/->pkg/dashboard/AGENTS.md - Go db package:
pkg/db/->pkg/db/AGENTS.md - Go downloader package:
pkg/downloader/->pkg/downloader/AGENTS.md - Go drift package:
pkg/drift/->pkg/drift/AGENTS.md - Go embedded package:
pkg/embedded/->pkg/embedded/AGENTS.md - Go exec package:
pkg/exec/->pkg/exec/AGENTS.md - Go features package:
pkg/features/->pkg/features/AGENTS.md - Go filesystem package:
pkg/fs/->pkg/fs/AGENTS.md - Go github package:
pkg/github/->pkg/github/AGENTS.md - Go harness package:
pkg/harness/->pkg/harness/AGENTS.md - Go installer package:
pkg/installer/->pkg/installer/AGENTS.md - Go lifecycle package:
pkg/lifecycle/->pkg/lifecycle/AGENTS.md - Go logger package:
pkg/logger/->pkg/logger/AGENTS.md - Go orchestrator package:
pkg/orchestrator/->pkg/orchestrator/AGENTS.md - Go proxy package:
pkg/proxy/->pkg/proxy/AGENTS.md - Go registry package:
pkg/registry/->pkg/registry/AGENTS.md - Go scaffold package:
pkg/scaffold/->pkg/scaffold/AGENTS.md - Go shell package:
pkg/shell/->pkg/shell/AGENTS.md - Go shellinit package:
pkg/shellinit/->pkg/shellinit/AGENTS.md - Go shim package:
pkg/shim/->pkg/shim/AGENTS.md - Go symlink package:
pkg/symlink/->pkg/symlink/AGENTS.md - Go toolbatch package:
pkg/toolbatch/->pkg/toolbatch/AGENTS.md - Go typecheck package:
pkg/typecheck/->pkg/typecheck/AGENTS.md - Go unwrap package:
pkg/unwrap/->pkg/unwrap/AGENTS.md - Go updater package:
pkg/updater/->pkg/updater/AGENTS.md - Go usagelog package:
pkg/usagelog/->pkg/usagelog/AGENTS.md - Go utils package:
pkg/utils/->pkg/utils/AGENTS.md - Go venv package:
pkg/venv/->pkg/venv/AGENTS.md - Go version package:
pkg/version/->pkg/version/AGENTS.md - Go VM package:
pkg/vm/->pkg/vm/AGENTS.md - Go E2E test suite:
tests/e2e/ - Verification fixture:
test-project/ - Isolated installer test workspace:
test-install/->test-install/AGENTS.md - Repository automation & scripts:
scripts/->scripts/AGENTS.md - Build & packaging orchestration:
scripts/build/->scripts/build/AGENTS.md - Dev bootstrap script:
scripts/dev-bootstrap/->scripts/dev-bootstrap/AGENTS.md - Documentation link verification:
scripts/docs-links/->scripts/docs-links/AGENTS.md - Hosted bootstrap installer:
scripts/managed-installer/->scripts/managed-installer/AGENTS.md - Go-to-TypeScript type generator:
scripts/typegen/->scripts/typegen/AGENTS.md
- Dashboard client rebuild required: The Go binary embeds compiled dashboard assets from
pkg/dashboard/dist/. Any changes underpackages/dashboard/src/client/require runningbun compileto re-bundle client assets into Go source before launching the dashboard server. - A fresh clone or worktree needs
just setupbefore anything builds:pkg/embeddedandpkg/dashboardembeddist/directories thatjust preparegenerates (it needsbun installfirst), so until then every Go build, vet and test that reaches them fails withpattern all:dist: no matching files found.test-project/tsconfig.jsonmaps@alexgorbatchev/dotfilestotest-project/.generated/node_modules/, which only exists after the fixture'sstate generate; without itjust typecheckreports dozens of TS2307/TS7006 errors that have nothing to do with the working tree.just setupruns all of these in order. - Starter tool configurations are never auto-created: Loading a configuration does not write
.tool.tsfiles.dotfiles tool scaffoldanddotfiles tool addare the commands that provision them into the tool configs directory. Neither overwrites an existing file unless--forceis passed, andscripts/managed-installer/install.shcallsdotfiles tool scaffoldwithout--force. --platform/--archmust reach the loader:.platform()blocks in tool files are evaluated while the configuration is being loaded, so the flags are passed throughvm.WithTarget. Platform and architecture matching itself lives in Go (vm.Target.matchesTarget,config.MatchesPlatform), and a misspelledPlatform/Architecturemember is rejected at load time rather than silently widening or disabling a block. The project-levelplatformlist indotfiles.config.ts(config.ApplyPlatformOverrides) is matched against the same target, invm.decodeProjectConfig, before placeholders are resolved.- Skill docs have one physical source:
pkg/embedded/skill/is the source of truth, embedded directly in the binary. Keep.agents/skills/dotfilesas a relative symlink to../../pkg/embedded/skill. Edits through either path modify the same files.scripts/build/main.gocopies the canonical directory into.dist/skill/without deleting or rewriting the source, andpackages/docspublishes it through the agent symlink. - One bundled dotfiles skill: Keep tool-creation instructions in
pkg/embedded/skill/SKILL.mdwith the existing references.dotfiles skillprints that entrypoint;dotfiles skill copy <path>exports onlydotfiles/. Keep command contracts and skill documentation synchronized in the same change. Do not create additional bundled skills, a skill-listing command, or global/AI-registry copies of this project's skill. - Skill snippets are type-checked:
pkg/embedded/skill_snippets_test.gocompiles every```typescript/```tsfence in the skill against the embedded declarations. A fragment must say how it is completed:```typescript builder(chain on aninstall()builder),```typescript shell(chain on a shell configurator),```typescript body(statements inside adefineToolcallback),```typescript config(members of thedefineConfigobject), or```typescript no-typecheckfor an example whose point is the error it contains. An unknown tag fails the test; a fragment left untagged fails to compile. - Declarations follow the runtime, not the docs:
pkg/vm/dsl-types.tsdeclares only memberspkg/vm/loader-api.tsprovides and parameterspkg/installer/*.goreads. When a doc and Go disagree, fix the doc or Go, never the declaration alone;tests/type-tests(tsd, run byjust typecheck) pins every member. - The full release build is not part of
just test-unitorjust check:TestRunBuildrewrites generated sources,.distand.tmp. Every package that loads a TypeScript configuration records the repository root as a test input, and Go hashes each entry's modification time, so a build insidego teststopspkg/installer,pkg/scaffold,pkg/vmandcmd/dotfilesfrom ever reusing a cached result. The test lives behind thebuildtestbuild tag and runs fromjust test-build, which CI runs as a step after the checks. - Tests get an isolated
MemFS:fs.NewMemFS()never consults the real filesystem, so a test cannot come to depend on what happens to be installed on the machine running it.fs.NewMemFSWithHostFallback()letsExists,Stat,LstatandReadlink(never content reads) answer from the host. Dry runs usefs.NewDryRunFS()to read existing files into a private overlay; writes, appends, renames and removals affect only that overlay. - Test artifact ownership: Run suites through
just test-unit,just test-e2e, orjust test-ts; their private runner owns scratch and joins child processes before cleanup, including failure and cancellation. Go scratch stays outside the checkout; Bun scratch stays under.tmp/. Docs build tests copy inputs into that owned scratch and share installed dependencies only, preserving existing site output and caches. - Docs validation is read-only:
just typecheckchecks a copied docs workspace throughpackages/docs/typecheck.ts, including content sync and Astro type generation. Reusepackages/docs/workspace.tsfor copied inputs and dependency links; never run validation sync against the developer's site output. - Stale generated output: Do not manually edit
.generated/output directories in fixtures or builds. If generated output gets stale, delete the matching.generated/directory and rerun the CLI. - Release version match: Tagged release
vX.Y.Zmust strictly matchversioninpackage.json. GitHub releases must be created/updated viagh releasewith release notes derived from actual git history. - Verify release binaries: Every release must be verified to ensure CI has completed and actually produced and uploaded all platform binary assets and checksums to the GitHub release.
- Commands that process multiple tools must report each tool's failure and continue processing the remaining tools. A per-tool failure must never abort the batch; return a nonzero exit status after processing when any tool failed.
- Before implementing a feature in any language, inspect existing dependencies and maintained third-party libraries. Prefer a suitable library, or native/standard-library functionality when it meets the requirements. Write custom functionality only when suitable existing solutions cannot meet them.
- Implement Go code in
pkg/organized by responsibility (domain-oriented, e.g.pkg/config/,pkg/installer/,pkg/logger/). - Accept interfaces, return concrete structs in Go functions. Wrap errors with context using
%w(fmt.Errorf("action: %w", err)). - Write platform-independent tests: never branch on
runtime.GOOSto select a different expected value. Assert on identity and intent (that a specific tool config is present) rather than on aggregate counts that platform-specific behavior can change, and inject the target OS as a parameter (asscaffold.Options.TargetOSdoes) when the subject genuinely is platform-specific behavior. - Copy
defineConfigpatterns fromtest-project/dotfiles.config.ts. - Copy
.tool.tspatterns fromtest-project/tools/github-release--bat.tool.ts. - Keep root
README.mdbrief; point detailed documentation to the website or skills. - Document every public API in exactly one canonical page under
.agents/skills/dotfiles/references/. Every other page that mentions it links to that page instead of restating parameters, tables, or option lists; a second copy of an API's surface is a defect, not redundancy.
- Test-only exception to the project-local
.tmppolicy: Go tests may use the OS temporary directory throught.TempDir()andos.MkdirTemp("", ...)for isolated sandboxes and shared test binaries. Keep these artifacts outside the module so randomized names and directory metadata do not invalidate Go's test cache. Use automatic test cleanup or aTestMainin an_test.gofile; remove only artifacts owned by that test process. Do not overrideTMPDIRorGOTMPDIRto point inside the repository for these tests. Temporary agent scripts and manual verification artifacts still belong in the project's.tmp. - Always: prefer non-API transports (such as direct download URLs via
pkg/downloader) when fetching GitHub data to avoid API rate limits, and use the GitHub API (orghCLI fallback) only when there is an actual need for API metadata or endpoints (e.g. release discovery, asset lists, or repository contents lookup). - Always: automatically record all new instructions in the most appropriate
AGENTS.mdfile immediately upon receipt (check with user if existing instructions conflict). - Always: keep the dotfiles skill frontmatter's
author: alexgorbatchevandmetadatablock withcreated_on,last_modified(YYYY-MM-DD HH:MM), andstatus: current. Preservecreated_onand updatelast_modifiedwhen revising the skill. - Always: maintain a minimum of 90% statement/line coverage across all packages.
- Always: run
bun checkbefore declaring work complete. - Always: verify that every release actually produces and uploads all compiled release binary assets via
gh release view vX.Y.Z --json assets. - Ask first: public API or CLI behavior changes, dependency additions or removals,
.github/workflows/*changes, release or publish logic updates, package version bumps. - Always: typecheck with
tscfromtypescript7. TypeScript 7 is released, so the native compiler ships astscin thetypescriptpackage; the@typescript/native-previewpackage and itstsgobinary were the pre-release form and are gone. - Never: hand-edit
.dist/ortest-project/.generated/; bypass Go abstractions with rawnode:fsorfetch; commit compiled Go binaries.
- Dashboard guidelines:
packages/dashboard/AGENTS.md - Go E2E test harness:
tests/e2e/harness.go - Skill definitions:
.agents/skills/dotfiles/ - Release scripts:
scripts/release.ts,.github/workflows/ci.yml,.github/workflows/publish.yml