gitea/TODO.AI.md

# TODO.AI.md

## Lint cleanup done — UUOC fixed (start-runners)

Verified clean by `script-lint` agent after fix.

- `rootfs/usr/local/bin/start-runners`: line 24 UUOC (`echo | grep -q '://'`) replaced with
  `[[ "$SERVER_ADDRESS" != *"://"* ]]`; grep call removed entirely so the missing `--` no longer
  applies.

## Lint cleanup done — version stamp and grep -- fixed (zz-act_runner.sh)

Verified clean by `script-lint` agent after fix.

- `rootfs/usr/local/etc/docker/init.d/zz-act_runner.sh`: added `VERSION="202608031200-git"`
  matching the existing `##@Version` header; added `--` before the pattern argument on all 15 grep
  invocations in the file (not just the subset originally enumerated); quoted the bare `grep`
  pattern at the former line 544 (now `grep -v -- 'grep'`).

## Lint cleanup done — line-length violation fixed (start-runners)

- `rootfs/usr/local/bin/start-runners`: the 781-char `RUNNER_LABELS="${RUNNER_LABELS:-...}"`
  default literal was replaced with a `_default_runner_labels` array joined via `IFS=,`, only
  applied when `RUNNER_LABELS` is unset. Verified with `bash -n` and a line-length scan (no line
  exceeds 180 chars).

## App-breaking bug fixed — DEBUGGER guard pattern under set -e (functions/entrypoint.sh)

Needs syncing back to the upstream template in `casjay-dotfiles/scripts` per the Docker Template
Update Runbook in AI.md — `functions/entrypoint.sh` is normally regenerated, not hand-edited.

- 26x occurrences of `[ "$DEBUGGER" = "on" ] && echo/printf/__service_banner "..."` used as a bare
  statement: under `set -e`, this aborts the whole script silently whenever `$DEBUGGER` != "on"
  (the default). This was the root cause of the container dying immediately after printing only
  the startup banner. Fixed by appending `|| true` to all 26 occurrences.

## App-breaking bug fixed — __random_password() SIGPIPE (functions/entrypoint.sh)

Needs syncing back to the upstream template in `casjay-dotfiles/scripts` per the Docker Template
Update Runbook in AI.md — `functions/entrypoint.sh` is normally regenerated, not hand-edited.

- `__random_password()` (~line 333): `tr | head -c` pipeline died under `set -eo pipefail` on
  SIGPIPE. Fixed by wrapping in `{ ... } || true`.

## App-breaking bug fixed — __format_variables() whitespace-only input (functions/entrypoint.sh)

Needs syncing back to the upstream template per AI.md's runbook.

- `__format_variables()` (~line 187): `printf '%s\n' $input | sort -Ru | tr '\n' ' '` always
  emits at least one line even when `$input` word-splits to zero words (whitespace-only), because
  `printf` with a format containing `%s` runs once even with no args. This made `ENV_PORTS` /
  `WEB_SERVER_PORTS` resolve to a single space `" "` instead of empty when no port env vars were
  set, which made `SERVICE_PORT` in `08-gitea.sh` become `" "` — passing the `-n` test but
  rendering as an empty `--port` arg to `gitea web`, which broke gitea's CLI argument parsing
  entirely (`Command error: unknown command: /config/gitea/app.ini`). Fixed by replacing the
  `[ -z "$input" ]` check with `[[ "$input" =~ [^[:space:]] ]] || return 0`.

## App-breaking bug fixed — missing /config/env directory (bin/entrypoint.sh)

- `/config/env` directory was never explicitly created. It only came into existence as a side
  effect of `__create_env_file()` (functions/entrypoint.sh) copying
  `/usr/local/etc/docker/env/default.sample` into it — but that sample file/dir does not exist in
  this image's rootfs, so `__create_env_file()` returns early (line 960) without creating the
  directory. `05-dockerd.sh`'s `__create_service_env()` then fails writing
  `/config/env/docker.local.sh` directly (`cat <<'EOF' >"/config/env/....local.sh"`, no `tee`
  suppression) with `No such file or directory`; `zz-act_runner.sh` hits the same error writing
  `/config/env/act_runner.local.sh`. Fixed by adding
  `mkdir -p "/config/env" 2>/dev/null || true` alongside the other `/config/*` directory creation
  lines (~line 241) in `rootfs/usr/local/bin/entrypoint.sh`. Needs syncing to the upstream
  template per AI.md's runbook.

## OCI label cleanup done — forbidden labels removed from Dockerfile

- Removed `org.opencontainers.image.base.name` (belongs on the base image, not the app image) and
  `org.opencontainers.image.schema-version` (non-spec, redundant with `version`).
- Removed the duplicate `org.opencontainers.image.authors="${LICENSE}"` line and duplicate
  `org.opencontainers.image.source="https://docker.io/..."` line; the license value now correctly
  populates the (previously missing) `org.opencontainers.image.licenses` label per AI.md's OCI
  label standard (lines 58-87), and `source` keeps the single github.com URL.

## Non-issue — confirmed intentional (`.gitea/workflows/docker.yaml`)

- Uses a stale/unpinned action pattern (`@v2`-`@v4`, DockerHub-only, `catthehacker/ubuntu:act-latest`).
  AI.md PART 7 explicitly documents this as the legacy hand-crafted workflow: "Never overwrite it,
  and never use it as a template for new work — it uses tag-pinned actions and retired secret
  names. All new/updated workflows come from `gen-dockerfile actions`." No `build.yml` exists yet in
  this repo; generating one is a separate task (running `gen-dockerfile actions`), not a fix to this
  file.