Why:
svc.sh grew into a three-kind service manager with database operations,
but its only documentation was a flat --help wall of text; the user asked
for a complete usage document and a better help experience.
Evidence:
- docs/svc.md: 14-section manual (prerequisites, quick start, concepts
and directory layout, per-command reference for service/global/db
commands, deploy sources, database operations handbook, configuration
layering, registry fields and event types, safety boundaries, exit
codes, troubleshooting table, recipe index) — every claim cross-checked
against the implementation from the previous two rounds.
- Help layering: no-args and -h print a one-screen overview; --help
renders the header comment reorganized into 7 labeled sections; the new
"help [topic]" command deep-dives eight topics (model, deploy,
lifecycle, db, dbops, config, examples, safety); usage errors now show
the short overview plus a pointer to --help / help / docs/svc.md.
All topics verified to render; unknown topic exits 2.
- No runtime behavior changed: end-to-end db lifecycle regression
(create → start → backup → status → stop → rm --purge) passes after the
refactor.
- Makefile help and README's documentation section point to docs/svc.md.
Impact:
Documentation-only plus display-layer changes; command semantics,
exit codes and file formats are untouched. Maintenance note: behavior
changes must now update both --help and docs/svc.md.
Refs: .task/feature-svc-docs-help.md（任务卡=PR 描述）
Why: branches merged into main had left their task cards open; backfill status and archive to prevent bookkeeping debt.
Evidence: feature-svc-db-ops.md(PR#59) — merges verified via git log --merges against origin/main.
Impact: .task/*.md moved to .task/archive/ with status backfilled; no code or submodule change.
Refs: task.sh close (card-autoclose-r1)
Why:
The service manager could create and run postgres instances but had no
way to retarget a port explicitly, back data up, clone an instance to
another port, or move a database between instances — the user asked for
exactly these operations.
Evidence:
- "set <name> [--port N] [--host H] [--apply] [--tag T...]": explicit
registration change; running postgres requires --apply (stop → rewrite
registration → start); port availability checked against both
registrations and live listeners. Verified: 8890→8895 with data intact
and DSN updated, old port freed; refusal without --apply.
- "db backup <name> [--db X] [--out F]": pg_dump -Fc into
runtime/<name>/backups/ (0600) with pg_restore --list self-check;
"db backups" lists them.
- "db restore <name> --file F [--db X] [--force]": restores into a new db
or refuses on a non-empty target unless --force (drop with FORCE +
recreate + restore), reporting table counts afterwards. Verified all
three paths.
- "db clone <src> <dst> [--port P] [--password PW] [--tag] [--online]":
default physical clone (brief source stop, cp -a of pgdata minus
postmaster files, new registration, source restarted on its own port);
--online copies via dump/restore without stopping the source (verified
source pid unchanged). Clone lands on the requested or derived port.
- "db copy <src> <dst> [--db X] [--force]": single-database logical move
between two running instances with the same non-empty-target guard.
"db ls <name>" lists databases.
- Fixed during verification: clone/copy leaked the CLI --port into the
source restart path (source briefly came up on the clone's port); the
address overrides are now cleared inside those commands.
Impact:
All operations stay inside runtime/<name>/, append to history.jsonl, and
reuse the existing safety constraints (own-process stop, port conflicts
reported not seized, secrets in 0600 files). Overwriting a non-empty
database requires an explicit --force everywhere. Makefile help line
mentions the new db subcommands.
Refs: .task/feature-svc-db-ops.md（任务卡=PR 描述）
Why: feature/svc-services-registry merged via PR #57 (merge 33fe7fb);
its card must be marked done and archived per the no-pending-cards rule.
Evidence: git log --merges origin/main shows 33fe7fb merging the branch;
card backfilled with PR link and moved to .task/archive/.
Impact: .task bookkeeping only (main checkout holds an unrelated untracked
.video_agent/ dir which is left untouched).
Refs: task.sh close
Why:
svc.sh only managed agent-system environments; databases, standalone
frontend serving, per-service tags and reusable start configs were out of
scope, and the user asked for a unified service lifecycle on this host.
Evidence:
- Service model v2: kind=agent|static|postgres registered in
runtime/<name>/svc.env (dotenv, mode 600); legacy entries without kind=
are adopted as agent.
- postgres: "db create <name> --port/--user/--password/--db/--auth-mode/
--tag" runs initdb (scram-sha-256, pwfile 0600), start/stop/restart use
pg_ctl (-m fast, never SIGKILL on postmaster) with pg_isready checks and
first-start database creation; "db dsn <name> [--reveal]" prints a
composable DSN (password masked by default). Verified end to end against
a real postgresql@18 instance: data survives restart, wrong passwords
rejected, stop/restart clean.
- static: "deploy --kind static --from dev[@sha]|local" builds frontend
dist into htdocs/ in an isolated worktree, or "--dir PATH" serves an
existing directory; verified serving HTTP 200, restart, stop, dry-run
plan, and explicit rejection of release sources.
- agent: unchanged three deploy sources plus --tag; bare start/restart now
reuses the persisted exec= from svc.env (verified: same custom port and
args across restart); old binaries lacking --dsn/--auth get those flags
auto-omitted with a warning.
- "list|status [--tag]" shows NAME/KIND/STATE/PID/ADDR/SOURCE/TAGS for all
registered services; "<name> status" gives per-kind detail; "rm <name>
[--purge]" unregisters (and optionally deletes) only runtime/<name>/.
- Fixed during verification: psql arg mangling (-c -c), tags lost because
record_state read svc.env inside its own redirect block, postgres
--version field parsing, unbound vars for unregistered names.
Impact:
Same invariants as before: writes stay under runtime/<name>/ and
runtime/.worktrees/ (only --from local also writes main-checkout build
outputs, all gitignored), stops only own pidfile+cmdline-verified
processes, port conflicts reported not seized. Prompt output moved to
stderr so stdout (tables, DSNs) stays pipeable. Makefile gains svc-list.
Refs: .task/feature-svc-services-registry.md（任务卡=PR 描述）
Why: feature/svc-deploy-source-registry merged via PR #55 (merge 8523415);
its card must be marked done and archived per the no-pending-cards rule.
Evidence: git log --merges origin/main shows 8523415 merging the branch;
card backfilled with PR link and moved to .task/archive/.
Impact: .task bookkeeping only.
Refs: task.sh close
Why:
svc.sh only knew two hardcoded environments (dev/prod) and always built
the current workspace, so there was no way to deploy a specific Dev- repo
commit or a Releases artifact, and no record of what was actually started.
Evidence:
- scripts/svc.sh commits dev|release lists deployable commits (release
entries annotated with version + devCommit; both mark HEAD and the
environments already running them).
- deploy --from local|dev@<sha>|release@<version|sha> materializes the
chosen source: dev commits build in an isolated worktree
(runtime/.worktrees/<sha>, submodule pins verified to land exactly),
release artifacts are sha256-verified against versions/<v>/manifest.json
(a forged manifest is refused); --pick offers an interactive numbered
choice and --dry-run prints the plan.
- Environment names are generalized (^[a-z][a-z0-9-]{0,15}$, derived port
8800-9099 on collision-free scan); each env is self-contained under
runtime/<env>/{bin,plugins,data} with svc.env (current state) and
history.jsonl (append-only deploy/start/stop events). status scans all
registered envs and history [env] [N] merges the event stream.
- Old artifacts that predate --dsn/--auth have those flags auto-omitted
(probed via serve usage); legacy svc.env files still render in status.
- Verified end to end in the task worktree: stub-binary lifecycle, a real
release@0.1.0 deploy (HTTP 200, source shown in status, commits marked),
failure paths (sha mismatch, immediate exit, non-TTY --pick).
Impact:
scripts/svc.sh users gain multi-version side-by-side environments and
rollback by redeploying an older source; existing dev/prod defaults and
safety constraints (own-pidfile-only stop, port-occupancy check) are
unchanged. Environments deployed by the previous script need one fresh
deploy before start/restart works again. Makefile gains svc-commits and
svc-history targets.
Refs: .task/feature-svc-deploy-source-registry.md（任务卡=PR 描述）
Why: branches merged into main had left their task cards open; backfill status and archive to prevent bookkeeping debt.
Evidence: feature-visual-refresh-r4.md(PR#53) — merges verified via git log --merges against origin/main.
Impact: .task/*.md moved to .task/archive/ with status backfilled; no code or submodule change.
Refs: task.sh close (card-autoclose-r1)
Why: R4 spans ui (token scale) and frontend (icon set + restyle); the
Dev repo advances pointers and the task record.
Evidence: make test full suite green on this head (exit 0); headless
journey on the real binary across both themes with zero console errors
and zero leftover emoji glyphs.
Impact: pure visual layer. Merge order: ui -> frontend -> this PR.
Refs: proposal 2026-09-30-ui-redesign-and-auth.md (R4)
Why: merged card needs its PR link backfilled and archived per the
no-bookkeeping-debt rule.
Evidence: Dev PR #51 merged; card records the env-file test matrix.
Impact: card archived with link; no code change.
Why: merged card needs its PR link backfilled and archived per the
no-bookkeeping-debt rule.
Evidence: Dev PR #49 merged; card records the seeding test matrix.
Impact: card archived with link; no code change.
Why: merged card needs its PR link backfilled and archived per the
no-bookkeeping-debt rule.
Evidence: Dev PR #47 merged; card records the live flag matrix.
Impact: card archived with link; no code change.
Why: merged card needs its PR link backfilled and archived per the
no-bookkeeping-debt rule.
Evidence: Dev PR #45 merged; card records the live test matrix.
Impact: card archived with link; no code change.
Why: branches merged into main had left their task cards open; backfill status and archive to prevent bookkeeping debt.
Evidence: feature-auth-admin-accounts.md(PR#43) — merges verified via git log --merges against origin/main.
Impact: .task/*.md moved to .task/archive/ with status backfilled; no code or submodule change.
Refs: task.sh close (card-autoclose-r1)
Why: R2 spans backend (migration v10, auth/session APIs, CLI user
subcommands), frontend (login page, forced change gate, admin user
management), documents (decision record).
Evidence: make test full suite green on this head (exit 0); headless
journey on the real binary with --auth on covers admin bootstrap,
first-login forced change for created and reset passwords, non-admin
menu gating, API-key login, logout.
Impact: auth-enabled deployments gain password login and admin account
management; embedded no-auth mode unchanged. Merge order: backend ->
frontend -> documents -> this PR.
Refs: proposal 2026-09-30-ui-redesign-and-auth.md (R2 admin-issued)
Why: merged combo card needs its PR link backfilled and the card
archived per the no-bookkeeping-debt rule.
Evidence: Dev PR #41 merged; card records both boot-state checks.
Impact: card archived with link; no code change.
Why: merged combo card needs its PR link backfilled and the card
archived per the no-bookkeeping-debt rule.
Evidence: Dev PR #38 merged; card carries the coverage test records.
Impact: card moved to .task/archive/ with the link filled; no code
change.
Why: branches merged into main had left their task cards open; backfill status and archive to prevent bookkeeping debt.
Evidence: feature-task-sidebar-r1.md(PR#37) — merges verified via git log --merges against origin/main.
Impact: .task/*.md moved to .task/archive/ with status backfilled; no code or submodule change.
Refs: task.sh close (card-autoclose-r1)
weichen