tiny-forge/docs/WORKLOAD_REFACTOR_TODO.md

# Workload-First Refactor — Remaining Work

Handoff for resuming the refactor. The plugin architecture (Source × Trigger),
`/api/workloads` surface, `/apps` UI, env/volume/webhook/logs/chain panels,
multi-face proxy routes, blue-green image deploys, schema-driven wizard, and
test coverage on triggers / image helpers / webhook parser / store upserts are
**already landed and live**. What follows is what's still pending, in priority
order.

> ## Current focus (read this first)
>
> **Triggers as first-class reusable entities — DONE** (2026-05-16) and
> **Static source inline port — DONE** (2026-05-16). The phantom-row
> adapter (`cmd/server/static_backend.go`) is gone; the static plugin
> now operates directly on `plugin.Workload` + `containers` +
> `workload_env`, with runtime state (`last_commit_sha`, `last_sync_at`,
> `last_error`, `status`) carried in `containers.extra_json`. Provider
> downloads enforce path-traversal rejection, error strings are
> sanitized before persistence, and Docker resource names are suffixed
> with the workload ID short prefix to dodge name collisions.
>
> **Next on Priority 1** is the **hard legacy cutover** — drop
> `/api/projects`, `/api/stacks`, `/api/sites`, `/api/stages` handlers,
> drop their tables, delete `internal/stack/` + `internal/staticsite/`
> packages, delete frontend `/projects` / `/stacks` / `/sites` routes.
> The `internal/staticsite` package stays alive only for the legacy
> `/api/sites/*` HTTP routes — once those drop, it dies with them.

## Status at a glance

| Item | Priority | Status |
| ---- | -------- | ------ |
| Triggers as first-class reusable entities | 1 | **DONE** (2026-05-16) |
| Static source inline port | 1 | **DONE** (2026-05-16) |
| Hard legacy cutover | 1 | **PENDING — current focus** |
| Generalized volume scopes | 2 | DONE |
| Kind-aware editors (compose / image / static) | 2 | DONE |
| Vendor-specific webhook parsing | 2 | DONE |
| Chain-panel CSS | 3 | DONE |
| Log Rules panel on `/apps/[id]` | adjacent | DONE — uses `getEffectiveLogScanRules` + per-workload override action |
| i18n for `/apps/*` page strings | 3 | **PARTIAL** — Log Rules panel + Observability surfaces i18n'd; `apps.*` namespace still pending |
| Docs / codemap entries for `internal/workload/plugin/` | 3 | **PENDING** |
| API-handler / dispatcher / compose-source / static-backend tests | 4 | **PENDING** |

Cross-references to the adjacent Observability work (Event Triggers + Log
Scanner backend + drop-counter stats panel) live in
[docs/LOGSCAN_AND_TRIGGERS_TODO.md](LOGSCAN_AND_TRIGGERS_TODO.md).

## Priority 1 — Architecture unlock

### ~~Triggers as first-class reusable entities~~ — DONE (2026-05-16)

Trigger config used to live embedded in the workload row
(`workload.trigger_kind` + `workload.trigger_config`). One workload owned
exactly one trigger; one trigger served exactly one workload. The split
makes a Trigger its own record so one inbound webhook / registry watcher /
schedule / git-push filter fans out to many workloads.

**Schema + store** — `triggers` + `workload_trigger_bindings` tables with
`ON DELETE CASCADE`. `binding_config` JSON merges on top of `trigger.config`
(top-level merge, binding wins). Boot-time backfill lifts every existing
embedded trigger into a standalone trigger row + binding inside a
per-workload transaction so a partial failure rolls back cleanly. Trigger
names are id-suffixed unconditionally to dodge the (name, kind) collision
race. `store.ErrUnique` sentinel translates SQLite UNIQUE violations at
the store boundary; API handlers use `errors.Is` instead of substring
match. `MergeJSONConfig` always returns a freshly allocated slice (no
aliasing under fan-out).

**Webhook fan-out** — new `POST /api/webhook/triggers/{secret}` resolves
to one Trigger and fans out to every enabled binding via a bounded worker
pool (`maxTriggerFanOutConcurrency = 4`). Per-binding errors are isolated
(one broken workload doesn't block siblings). Outcome accounting splits
deployed / skipped / no-match / errored cleanly. Legacy
`POST /api/webhook/workloads/{secret}` route dropped (clean break per the
workload-first memory; the boot backfill kept secrets resolvable at the
new path).

**API** — `/api/triggers` CRUD, `/api/triggers/{id}/webhook`,
`/api/triggers/{id}/bindings` (list + bind), `/api/bindings/{id}` for
update and delete, and `/api/workloads/{id}/triggers` (list + bind,
accepts either `trigger_id` or inline `{kind, name, config, ...}`).
Inline-create path
runs trigger insert + binding insert inside one transaction
(`CreateTriggerWithBindingTx`) so a binding failure can't leak an orphan
trigger. `validateBindingConfig` enforces 8 KiB cap and runs the trigger
plugin's `Validate()` against the merged shape on every bind/update.
List endpoints use `LEFT JOIN ... GROUP BY` (`ListTriggersWithBindingCount`,
`ListBindingsForTriggerWithNames`, `ListBindingsForWorkloadWithNames`) —
no per-row N+1.

**Plugin contract unchanged** — `Trigger.Match` still takes `(Workload,
InboundEvent)`. The fan-out path uses `plugin.WithEffectiveTrigger` to
stuff the merged config into a copied workload before the call, so the
existing `registry`, `git`, `manual` plugins work unchanged.

**Reconciler** — gate dropped from `(SourceKind != "" && TriggerKind != "")`
to `SourceKind != ""`. A workload with a Source but no triggers still
gets `Source.Reconcile` called every tick (manual-only deploys are
common during early setup).

**Frontend** — new pages under `web/src/routes/triggers/`:

- `+page.svelte` — list with kind chips, binding count, webhook status,
  empty state.
- `new/+page.svelte` — wizard with kind picker (cards), name, kind-aware
  config form (registry / git / manual + JSON fallback), webhook toggles.
- `[id]/+page.svelte` — editable per-kind form, webhook URL panel
  (origin-prefixed, copy + ConfirmDialog-gated rotate), bindings list
  with per-row enabled `<ToggleSwitch>` + ConfirmDialog-gated unbind,
  danger-zone delete.

**Workload UI** — embedded trigger fields removed.

- `apps/new/+page.svelte` — wizard now has Trigger step with NEW / PICK /
  SKIP modes; bind happens after `createPluginWorkload` succeeds.
- `apps/[id]/+page.svelte` — Bindings panel above Containers, "Add trigger"
  modal with Inline / Pick-existing tabs, **per-binding override editor**
  (inline disclosure with read-only base config, editable JSON override,
  merged preview, 8 KiB byte cap, save / reset-to-inherit). Per-row
  "OVERRIDES n FIELDS" badge surfaces deviation from the trigger.

**Shared component** — `web/src/lib/components/TriggerKindForm.svelte`
hosts the kind picker + name + per-kind config + JSON fallback + webhook
toggles. Reused on both `/triggers/new` and the workload Add-trigger modal.

**i18n** — full EN + RU coverage under `redeployTriggers.*` (standalone
pages), `apps.detail.bindings.*` (workload bindings panel including
`override.*`), `apps.new.triggers.*` (wizard mode picker), `nav.triggers`.
The existing `/event-triggers` nav label was disambiguated to "Event
Triggers" to coexist with the new `/triggers` entry.

**Compliance** — three pre-existing raw `<input type="checkbox">`
instances in `apps/new` + `apps/[id]` (render-markdown, env-encrypted)
replaced with `<ToggleSwitch>` to honor the project rule.

**Touch points (final):**

- `internal/store/triggers.go`, `workload_trigger_bindings.go`, `models.go`,
  `store.go` (schema + backfill + `translateSQLError`).
- `internal/workload/plugin/binding.go` (`MergeJSONConfig`,
  `WithEffectiveTrigger`).
- `internal/webhook/trigger_handler.go` + `handler.go` (route mount,
  legacy route removed).
- `internal/reconciler/reconciler.go` (trigger gate dropped).
- `internal/api/triggers.go` + `router.go` (REST surface).
- `web/src/routes/triggers/`, `web/src/routes/apps/{new,[id]}`,
  `web/src/lib/components/TriggerKindForm.svelte`, `web/src/lib/api.ts`,
  `web/src/lib/i18n/{en,ru}.json`, `web/src/routes/+layout.svelte`.

**Reviews shipped through go-reviewer + security-reviewer +
typescript-reviewer subagents** — 0 CRITICAL; 5 HIGH and 4 MEDIUM
findings addressed inline before merge.

### ~~Static source inline port~~ — DONE (2026-05-16)

The phantom-row adapter (`cmd/server/static_backend.go`) is deleted; the
static plugin now operates directly on `plugin.Workload`, the `containers`
table, and `workload_env`. The deploy pipeline body lives inline in
`internal/workload/plugin/source/static/{deploy,teardown,reconcile,
state,env,build,naming,static}.go`.

**State migration:** the legacy `static_sites` columns
(`last_commit_sha`, `last_sync_at`, `last_error`, `status`,
`container_id`, `proxy_route_id`) are now persisted on the container
row keyed `<workloadID>:site` — deterministic ID, single row per
workload. First-class fields (`container_id`, `proxy_route_id`,
`subdomain`, `state`, `port`, `image_ref`) move into their dedicated
columns on the `containers` table; the rest live in
`containers.extra_json` via a typed `runtimeState` struct that
preserves unknown keys on round-trip (so future writers can extend
`extra_json` without forcing this struct to grow). `workload_env`
replaces `static_site_secrets` for plugin-native workloads.

**Reused helpers:** `internal/staticsite/{provider,gitea_content,
github_provider,gitlab_provider,markdown,deno}` stay alive (and
exported) as helpers — providers are still imported via
`staticsite.NewGitProvider`. The `staticsite.Manager` itself stays
alive only to service the legacy `/api/sites/*` HTTP routes; once
those drop in the cutover the package can be deleted entirely.

**Hardening landed alongside the port** (from `go-reviewer` +
`security-reviewer` subagent passes — 1 CRITICAL, 5 HIGH, 3 MEDIUM
addressed before merge):

- **Path-traversal defense:** providers (`gitea_content.go`,
  `github_provider.go`, `gitlab_provider.go`) reject any tree entry
  whose resolved local path escapes `destDir`; the static plugin's
  `verifyDownloadInsideRoot` walks the build dir post-download as a
  second line of defense; `copyDir` uses `filepath.WalkDir` + `Lstat`
  to refuse symlinks and non-regular files.
- **Error sanitization:** a `sanitizeError` helper redacts the
  decrypted access token, collapses to one line, and clamps to 240
  bytes before any error string lands in `runtimeState.LastError`
  (persisted in `extra_json`) or fans out to the notification
  webhook.
- **Resource naming with workload-ID short suffix:** container,
  image, and storage volume names all carry `idShort(w)` so two
  workloads sharing a name can't clobber each other's resources
  (workload `name` is not UNIQUE in the schema).
- **Per-workload mutex on `saveState`:** serializes the read-modify-
  write of `containers.extra_json` so two parallel deploys for the
  same workload can't race to clobber each other's
  `container_id` / `proxy_route_id`.
- **`saveState` failure on the success path is fatal:** rolls back
  the just-created container + proxy route and writes a "failed"
  state, so we don't leak a running container with no row pointing
  at it.
- **`primaryDomain` reads `settings.Domain`** to complete a bare
  subdomain face into a full FQDN (matches legacy Manager behavior).
- **`time.Sleep` honors `ctx.Done()`** during the post-start health
  window.
- **`json.Marshal` for event metadata + `strings.HasPrefix` for
  failed-status detection** — replaces the prior fmt.Sprintf JSON
  template + brittle slice expression.

**Touch points (final):**

- `internal/workload/plugin/source/static/{static,deploy,teardown,
  reconcile,state,env,build,naming}.go` — the inline plugin.
- `internal/staticsite/{gitea_content,github_provider,
  gitlab_provider}.go` — added the path-traversal guards.
- `cmd/server/main.go` — `wireStaticBackend(...)` call removed; the
  existing blank import on `_ "internal/workload/plugin/source/
  static"` now drives `init()` registration.
- `cmd/server/static_backend.go` — deleted.

**Behavioral notes for operators:**

- Plugin-native static workloads no longer write to the `static_sites`
  table at all — anything querying that table for plugin-native
  workloads (operator dashboards, ad-hoc SQL) sees stale or absent
  values. The legacy `/api/sites/*` routes still serve original rows
  unchanged.
- Container labels `tinyforge.static-site` / `tinyforge.static-site-name`
  are no longer set on plugin-native deploys; the canonical
  `tinyforge.workload.id` / `.kind` labels (added by
  `docker.ContainerConfig`) cover ownership.
- Container, image, and volume names all gained an 8-char ID suffix
  (e.g. `dw-site-mysite-a1b2c3d4`). Existing legacy-deployed sites
  keep their old `dw-site-mysite` shape until they're redeployed
  through the plugin path.

### Hard legacy cutover

The static-source inline port (above) is now complete; the cutover is
unblocked. Proceeding with the cutover means:

- Delete `/api/projects`, `/api/stacks`, `/api/sites`, `/api/stages` handlers.
- Drop tables: `projects`, `stages`, `stacks`, `stack_revisions`,
  `stack_deploys`, `static_sites`, `static_site_secrets`, `deploys`,
  `poll_states`.
- Delete `internal/stack/`, `internal/staticsite/` packages.
- Delete frontend `/projects`, `/sites`, `/stacks` routes.
- Delete legacy `volume.ResolvePath` + `internal/api/volume_browser.go`
  callers (the only remaining users).

## Priority 2 — Behavior gaps

### ~~Generalized volume scopes~~ — DONE

Landed: `internal/volume.ResolveWorkloadPath` (workload-keyed; sits next to the
legacy `ResolvePath` so legacy code paths keep working) plus the wired-through
`computeMounts` in `internal/workload/plugin/source/image/image.go`. All
`VolumeScope` values are now honored at deploy time:

- `absolute` — host bind, validated against `settings.AllowedVolumePaths`.
- `ephemeral` — tmpfs.
- `instance` — per-tag dir under `<base>/<workload>-<idShort>/instance-<tag>/<source>`.
- `stage`, `project` — both collapse to `<base>/<workload>-<idShort>/<source>`.
- `project_named` — Docker named volume prefixed `tf-<idShort>-<name>`.
- `named` — Docker named volume by raw name.

Test coverage: `internal/volume/resolver_test.go` (table-driven, portable
Linux/Windows). The legacy `ResolvePath` stays in place for legacy deployer +
volume-browser callers and dies with the hard cutover.

### ~~Kind-aware editors on `/apps/new` and `/apps/[id]` edit~~ — DONE

All three Source plugins now have hand-rolled forms on both pages, with
an "Advanced JSON" toggle preserved as the power-user escape hatch.
Submit logic marshals form fields back into the same JSON shape the
backend already expects — no API or store changes required.

**Principle:** the plugin contract makes new Source / Trigger kinds cheap
on the backend, but the UI is not cheap by default — every kind needs a
paired hand-rolled form to be daily-driver usable. The shared JSON
editor is the fallback for power users and brand-new plugins, not the
end state. New Source / Trigger merge requests should treat "ship the
kind-aware form" as part of done, not a follow-up.

**Landed:**

- `compose`: YAML textarea + project_name input on both `/apps/new`
  and `/apps/[id]`.
- `image`: form fields for image / port / healthcheck / default_tag /
  registry_name / cpu_limit / memory_limit / max_instances on both
  pages. Registry name is a select populated from `/api/registries`
  (with text-input fallback when the list is empty). env + volumes
  stay in their detail-page panels and round-trip through the form
  via `imageFormBody` so manual edits aren't clobbered.
- `static`: provider select (gitea / github / gitlab), base URL,
  repo_owner / repo_name (both required), branch (default "main"),
  folder_path, access_token (password input, for private repos),
  mode radio (static / deno), render_markdown checkbox. The
  storage_enabled / storage_limit_mb fields aren't surfaced as
  form controls yet, but they round-trip through `staticFormBody`
  so values set via the raw JSON editor survive form edits.

**Still pending forms:** none — all three Source plugins now have
hand-rolled forms on both `/apps/new` and `/apps/[id]`.

The raw JSON editor stays available behind the "Advanced JSON" toggle
(shipped with compose) so the plugin's full sample is still reachable
for power users and for any new plugin kind without a hand-rolled form.

Effort: per-kind form roughly half a turn each; can land incrementally.
Touches `web/src/routes/apps/new/+page.svelte` and the edit block in
`web/src/routes/apps/[id]/+page.svelte`. The Svelte side keeps
serializing into the same `source_config` JSON shape the backend
already expects — no API or store change required.

### ~~Vendor-specific webhook parsing for `/api/webhook/workloads/{secret}`~~ — DONE

Landed: `internal/webhook/vendor_parsers.go` plus rewrites in
`internal/webhook/handler.go` `buildInboundEvent`. The dispatch order is now:

1. Empty body → manual event.
2. Vendor-specific parsers, short-circuit on a recognized `X-*-Event`
   header — Gitea package, GitHub `package` / `registry_package`, GitHub
   push, Gitea push, GitLab `Push Hook` / `Tag Push Hook`.
3. Generic simple-body fallback: top-level `image` or top-level `ref` —
   what the legacy CI integrations already send.

Vendor parsers can populate fields the generic parser cannot: image
digest, `GitEvent.Vendor`, registry host. When a vendor parser claims a
request (header matches) it is authoritative — a malformed Gitea
package payload surfaces as an error rather than silently falling
through to the generic parser. Test coverage:
`internal/webhook/vendor_parsers_test.go` covers each vendor branch +
the routed-via-`buildInboundEvent` integration cases.

Open follow-ups deferred to future turns:

- GitLab Container Registry events use a custom envelope outside the
  webhook event surface — handle if a user reports needing it.
- Docker Hub webhook (push event) uses `{"push_data": {"tag": ...}, "repository": {...}}` — add when there's a user request.

## Priority 3 — Polish

### ~~Chain-panel CSS~~ — DONE

Landed: rules for `.chain-row`, `.chain-card` (with hover/transform on
anchors), `.chain-self` (brand-tinted highlight), `.chain-name`,
`.chain-label` (70px fixed-width mono column), `.chain-children-list`
(flex-wrap), plus a sub-600px stack to keep the panel usable on narrow
screens. Appended at the end of the `<style>` block in
`web/src/routes/apps/[id]/+page.svelte`.

### Docs / codemap entries

Nothing under `docs/CODEMAPS/` for `internal/workload/plugin/`. Should cover:

- The Source × Trigger contract + registry pattern (`init()` + blank-import in
  `cmd/server/main.go`).
- How a new Source kind is added (write `init()` registration, blank-import,
  add to wizard via `SchemaSample`).
- The dispatcher seam: `deployer.DispatchPlugin` / `DispatchTeardown` /
  `DispatchReconcile` and how the reconciler / webhook ingress / API
  handlers all flow through it.

`README.md` should mention `/apps` as the new user surface and that
`/projects` / `/sites` / `/stacks` carry `Deprecation: true` headers.

### i18n: page-level strings — PARTIAL

Already i18n'd:

- `nav.apps`, `nav.eventTriggers`, `nav.logScanRules` — top nav labels.
- Log Rules panel on `/apps/[id]` reuses `logscan.panel.*` keys
  (shipped with the Observability work).
- All `/event-triggers/*` and `/log-scan-rules/*` page strings — keys
  live under `triggers.*` and `logscan.*` namespaces in
  `web/src/lib/i18n/{en,ru}.json`.

Still hardcoded English:

- `/apps/+page.svelte` — list page (hero, lede, stats, empty state,
  table headers, status pills).
- `/apps/new/+page.svelte` — wizard labels, form copy, kind-aware
  form rows (compose / image / static all hardcoded English today).
- `/apps/[id]/+page.svelte` — detail page sections (chain, env,
  volumes, webhook, manual deploy, danger zone) — the Log Rules
  panel embedded inside it is the only i18n'd section.

Roughly 80–100 keys across the three `/apps/*` pages once extracted.
Namespace: `apps.*` (with sub-namespaces `apps.list.*`, `apps.new.*`,
`apps.detail.*`, `apps.form.*`).

## Priority 4 — Tests we still don't have

Solid pure-function coverage landed in the prior turn. Still missing:

- **API-handler integration tests** for `/api/workloads/*` (CRUD, deploy,
  env, volumes, webhook, chain, promote-from). Pattern: in-memory store +
  fake deployer + fake docker / proxy / dns providers, exercise via
  `httptest`.
- **Deployer dispatcher**: `DispatchPlugin` / `DispatchTeardown` /
  `DispatchReconcile` with a fake Source registered.
- **Compose source**: `composeProjectName` sanitizer, `writeYAMLIfChanged`
  short-circuit. (Both pure; just need fixtures.)
- **Static source Backend adapter** in `cmd/server/static_backend.go`.

## Open architectural questions

### Stages chain vs explicit Stage entity

`parent_workload_id` is now the canonical mechanism for stage chains
(dev → staging → prod). Decision deferred: do we need a separate `Stage`
entity at all, or is the chain sufficient? Currently feels like the chain
covers the use case — `promote-from` works, the UI shows the relationship.
Probably can leave the legacy `stages` table dropped entirely once cutover
proceeds.

### `Container.extra_json` evolution

Currently only the image source uses it (per-face proxy route IDs). If
other sources gain similar needs (compose service health metadata, static
build SHAs), the schema there should stay versionless and additive — every
reader must tolerate unknown keys. Document this in the source plugin
guide alongside the codemap entry.

## File pointers for the next session

- Plugin contracts: `internal/workload/plugin/{plugin,source,trigger,types,registry}.go`
- Source implementations: `internal/workload/plugin/source/{image,compose,static}/`
- Trigger implementations: `internal/workload/plugin/trigger/{registry,git,manual}/`
- Dispatcher: `internal/deployer/dispatch.go`
- Webhook ingress (plugin path): `internal/webhook/handler.go` `handlePluginWorkloadWebhook`
- Reconciler hook: `internal/reconciler/reconciler.go` `reconcilePluginWorkloads`
- Static backend adapter (to be deleted post-port): `cmd/server/static_backend.go`
- Frontend pages: `web/src/routes/apps/+page.svelte`, `web/src/routes/apps/new/+page.svelte`, `web/src/routes/apps/[id]/+page.svelte`
- Tests: `internal/workload/plugin/trigger/*/!(_test).go`, `internal/workload/plugin/source/image/image_helpers_test.go`, `internal/webhook/inbound_event_test.go`, `internal/store/workload_env_test.go`

## Memory pointer

Memory at
`C:/Users/Alexei/.claude/projects/c--Users-Alexei-Documents-docker-watcher/memory/`
already covers the Workload-first decision and the no-migration constraint.
Refresh as the cutover lands.