Skip to main content

Repo Doctor

@maphew/repo-doctorv2026.10.29.1· MIT· 23d agoBEHAVIORS
01README

Repository hygiene checks for swamp repos — hardcoded absolute home paths in model/workflow sources (test fixtures and the Linuxbrew prefix exempted), pulled extensions whose source files are missing, generated .swamp artifacts not covered by .gitignore, and workflow wiring drift: scripts missing an exec bit/shebang, declared schedules with no live registration, and dead step dependencies that skip silently or dereference the outputs of a failed step. Writes a combined markdown report plus per-check structured resources.

02Release Notes

checkWorkflowWiring now also lints dead step dependencies: a dependsOn whose condition a skipped dependency cannot satisfy (silent skip, green run), and a condition that runs the dependent after a failed dependency whose steps..outputs it dereferences. Schedule detection probes the unauthenticated /health when /api/v1/health is auth-gated (an oauth serve answered 401, so the declared-vs-live diff had silently degraded to the YAML view). The hardcoded-path check skips _test.ts fixtures and exempts /home/linuxbrew via the new excludeSourceSuffixes/allowedHomeRoots globals, removing 21 false errors on a clean checkout. 15 new unit tests.

03Behaviors1
@maphew/repo-doctorv2026.10.23.1src/repo_doctor.ts

Global Arguments

ArgumentTypeDescription
projectDir?stringSwamp repo root to audit. Defaults to the current directory so the model stays portable across machines.
sourceDirs?arrayRepo-relative directories scanned for hardcoded absolute paths
excludeSourceSuffixes?arrayPath suffixes skipped by the hardcoded-home-path check; test fixtures embed synthetic absolute paths on purpose
allowedHomeRoots?arrayHome roots that are standard tool locations rather than a person (the Linuxbrew prefix); matches under them are not reported
includeWorkflows?booleanAlso scan workflows/ for hardcoded absolute paths
scaffoldingDirs?arrayRepo-relative directories holding generated agent scaffolding to typecheck
denoBin?stringdeno executable used for scaffolding typechecks; falls back to DENO_BIN and ~/.swamp/deno/deno
workflowDirs?arrayRepo-relative directories scanned for workflow YAML
swampBin?stringswamp executable used to read live workflow registrations; falls back to SWAMP_BIN
serveUrl?stringswamp serve base URL probed for live schedules at /api/v1/health, then the unauthenticated /health; unreachable is not an error
fn scan()
Run every repo doctor check and write a combined report
fn findPaths()
Find hardcoded absolute home paths in model and workflow sources
fn checkExtensions()
Check pulled extensions for missing source files
fn checkGitignore()
Check that generated .swamp artifacts are gitignored
fn checkScaffolding()
Typecheck generated agent scaffolding (.kilo/plugins, .opencode/plugins, .pi/extensions)
fn checkWorkflowWiring()
Check workflow-invoked scripts for exec bit/shebang and diff declared schedules against live registrations

Resources

scan(7d)— Combined repo health report from every doctor check
paths(7d)— Hardcoded absolute-path findings
extensions(7d)— Pulled extension source integrity
gitignore(7d)— .gitignore coverage of generated .swamp artifacts
scaffolding(7d)— Typecheck findings for generated agent scaffolding, separate from project-owned code
workflowWiring(7d)— Workflow script exec/shebang checks and declared-vs-live schedule diff

Files

report(text/markdown)— Markdown repo doctor report
04Previous Versions9
2026.10.23.1MIT

Add workflow-wiring pre-flight checks: inspect referenced scripts for exec bits/shebangs, compare declared workflow schedules with live registration, and report drift in the combined report.

Modified 1 behaviors. updated labels

2026.10.21.2MIT

Document checkScaffolding in the README. No behavior change from 2026.10.21.1.

2026.10.21.1MIT

Add checkScaffolding: typecheck the generated agent scaffolding (.kilo/plugins, .opencode/plugins, .pi/extensions) with deno check and report findings separately from project-owned code. Adds scaffoldingDirs and denoBin global args (both defaulted) and a scaffolding resource. Ported from myswamp 697f65e.

Modified 1 behaviors

2026.10.15.2MIT(was AGPL-3.0-only)

Relicense from AGPL-3.0-only to MIT.

2026.10.15.1AGPL-3.0-only(was none)

Declare license: AGPL-3.0-only in the manifest; no model, workflow, or schema changes.

2026.10.14.2
2026.10.14.1

updated labels

2026.09.29.2
2026.09.28.1
05Stats
A
93 / 100
Downloads
57
Archive size
43.9 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented0/1missing
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
06Platforms
07Labels