- sync-docker-prep.sh: add MindLyst, LysnrAI, talk2obsidian to consumer list
- docker-doctor.sh: detect Python Dockerfiles (python:3.x base) and skip
Node-specific checks (pnpm/corepack, .npmrc.docker ARGs). Python base
images are now in the approved list alongside node:22-{alpine,slim}.
Refs: docker-build-optimization-roadmap.md \xc2\xa7 D
Promotes docker-prep.sh to canonical home in common-plat with full Phase B
hardening from the docker-build-optimization-roadmap:
- B1: --dry-run mode (lists actions, no side effects)
- B2: idempotency guard (refuses to run if *.bak exists, --force to bypass)
- B5: trap-based auto-restore on error (--keep to disable)
- B6: standardized header + usage block
- B7: canonical home + sync + drift-check (mirrors npmrc.template pattern)
- B8: --strip-overrides for safety-net cleanup
- New: --check mode for CI-friendly state verification
- New: auto-discovers package.json files with @bytelyst/* deps
- New: portable sed -i (BSD on macOS, GNU on Linux)
- New: preserves .docker-deps/.gitkeep on clear (fixes earlier regression)
- New: 2 small JS helpers (_docker-prep-*.js) avoid bash 3.2 heredoc quirks
Verified on clock + peakpulse: dry-run, pack, check, idempotency guard,
restore, and post-restore git status all clean.
Copy-pasteable runbook for the case where:
- VM is already provisioned
- Gitea is already installed and running on :3300
- Repos are already cloned on the VM
- User needs to wire admin + npm-user + token + laptop end-to-end
10 numbered steps with expected outputs and troubleshooting:
1. Create Gitea admin user (idempotent skip if exists)
2. Create npm owner user (learning_ai_user)
3. Mint npm-scoped token via API
4. Write token to ~/.gitea_npm_token_home on laptop
5. Update ~/.gitea_vm_host with VM hostname
6. Pre-flight verification via doctor.sh (expects 404 on probe)
7. Publish @bytelyst/* via publish-local-packages.sh
8. End-to-end verification (re-run doctor + smoke-test pnpm install)
9. Optional: backfill historical versions
10. Persist environment in ~/.zshrc
Includes troubleshooting table, persistence map (what survives VM reboot
vs rebuild), and Azure NSG/firewall guidance.
Companion to scripts/gitea/{bootstrap-vm,doctor,token}.sh.
Static linter for Dockerfile + docker-compose + .npmrc.docker drift.
Sibling to gitea-doctor. Codifies all 15 invariants from Phase A of
the docker-build-optimization-roadmap so regressions are caught at
PR time, not at build time.
Verified against both pilots:
- learning_ai_clock: PASS (1 expected warning)
- learning_ai_peakpulse: PASS (1 expected warning, pnpm-lock per ADR-0001)
- learning_ai_notes (un-migrated control): FAIL with 6 specific findings
Refs: docker-build-optimization-roadmap.md \xc2\xa7Phase E (E1, E5)
Resolves F17 in docker-build-optimization-roadmap.
Root cause:
Gitea's app.ini ROOT_URL was http://localhost:3300/. Gitea bakes
ROOT_URL into the dist.tarball field of every published package's
metadata. Inside a Docker container, 'localhost' is the container
itself, not the host \u2014 so any 'pnpm install' that needed to fetch
a tarball would ECONNREFUSED, even though the registry metadata
itself was reachable via host.docker.internal.
Server-side fix (not in git, requires manual replication on each dev
machine; documented in roadmap \u00a73 A-pre-6):
- Edit /opt/homebrew/var/gitea/custom/conf/app.ini:
ROOT_URL = http://host.docker.internal:3300/
- brew services restart gitea
- sudo sh -c 'echo "127.0.0.1 host.docker.internal" >> /etc/hosts'
Repo-side fix (this commit):
- switch-network.sh: add host.docker.internal to NO_PROXY +
NPM_CONFIG_NOPROXY when NETWORK=corp. Required so host-side curl/
pnpm/npm bypass the corporate proxy (cso.proxy.att.com) when
resolving host.docker.internal. Without this, host installs fail
with the corp proxy's 'Unknown Host' 504 page.
Republished all 64 @bytelyst/* packages so tarball URLs reflect the
new ROOT_URL:
- .publish-manifest.json: 64 entries with new content hashes
- packages/*/package.json: 64 patch-version bumps
(auto-bumped by publish-outdated-packages.sh because previous
versions already existed in registry)
Verification:
curl http://localhost:3300/.../@bytelyst%2Ferrors | jq .dist.tarball
→ http://host.docker.internal:3300/.../errors-0.1.11.tgz (was localhost:3300)
workspace:* refs across all 64 packages: 0
Unblocks: A0-V on every pilot. Verified PASSING on learning_ai_clock:
backend cold build: 59.2 s
web cold build: 3:13 (193 s)
Both via Gitea registry, no docker-prep.sh tarballs needed.
Resolves F16 in docker-build-optimization-roadmap v5.
Root cause:
publish-outdated-packages.sh uses a pack-extract-repack pattern:
1. pnpm pack (rewrites workspace:* in tarball)
2. extract
3. npm pack (re-tar from extracted content)
4. npm publish
Step 3 is the bug. npm pack does not recognize the pnpm-specific
workspace: protocol — it treats workspace:* as a literal version
string and passes it through to the final tarball. Result: any
consumer doing 'pnpm install' inside Docker (where there is no
workspace context) fails with ERR_PNPM_WORKSPACE_PKG_NOT_FOUND.
Documented in roadmap §0 F16 + §3 Phase A-pre.
Fix (publish-outdated-packages.sh):
- Insert a workspace:* rewriter between publishConfig strip and
npm pack. Reads source package.json for each @bytelyst/* target,
resolves workspace:* / workspace:^ / workspace:~ to ^x.y.z.
- Add defense-in-depth: grep the post-rewrite package.json for any
surviving 'workspace:' literal. If found, refuse to publish.
Republished 10 affected packages with workspace:* → resolved semver:
@bytelyst/auth 0.1.5 → 0.1.6
@bytelyst/diagnostics-client 0.1.6 → 0.1.7
@bytelyst/events 0.1.5 → 0.1.6
@bytelyst/extraction 0.1.5 → 0.1.6
@bytelyst/fastify-auth 0.1.5 → 0.1.6
@bytelyst/fastify-core 0.1.5 → 0.1.6
@bytelyst/feedback-client 0.1.6 → 0.1.7
@bytelyst/field-encrypt 0.1.6 → 0.1.7
@bytelyst/react-auth 0.1.6 → 0.1.7
@bytelyst/sync 0.1.5 → 0.1.6
Verification: all 10 packages now scan with 0 workspace:* refs in
their published package.json (per registry curl scan).
Unblocks: A0-V verification on learning_ai_clock (currently blocked
at learning_ai_clock@0be887288).
Idempotent end-to-end Gitea bootstrap for Azure VM (or any Linux host
with Docker available). Replaces manual SSH-and-paste workflow.
Steps (each skippable on re-run):
1. Install Docker via official script (skip with --skip-docker)
2. Write /etc/gitea/docker-compose.yml with package registry enabled
3. Start gitea container, wait for HTTP :3300
4. Create admin user via 'gitea admin user create' (CLI inside container,
no auth bootstrap needed)
5. Create npm-user (learning_ai_user) via admin API
6. Mint npm-scoped token with write:package + read:package
Two execution modes:
- On the VM directly: scp + ssh + run
- Locally targeting remote: --ssh-host azureuser@vm
Outputs npm token to --output FILE or stdout. Prints copy-paste-ready
command for writing to ~/.gitea_npm_token_home on the workstation.
Final summary prints the doctor.sh verification command so user can
confirm registry reachability from their laptop in one step.
--dry-run shows planned actions without execution.
--force re-creates users (use after manual deletion).
Closes the 'cloud VM bootstrap' gap identified during the Gitea hardening
review — pairs with scripts/gitea/{doctor,token}.sh from commit 610a59fd.
Eliminates the three operational pain points hit in the last
owner-rename incident:
1. Owner-rename drift across 14 repos
- npmrc.template now uses ${GITEA_NPM_OWNER:-learning_ai_user}
- switch-network.sh exports GITEA_NPM_OWNER on shell start
- Future renames are a one-line env change, not 14 git commits
2. Stale shell-env tokens (file rotated, env didn't)
- scripts/gitea/token.sh: status|print|validate|rotate subcommands
- 'eval "$(bash scripts/gitea/token.sh print --export)"' refreshes
any shell without re-sourcing ~/.zshrc
- rotate uses Gitea API + macOS Keychain for admin creds
3. No pre-deploy validation
- scripts/gitea/doctor.sh: NETWORK + DNS + token consistency +
registry HTTP 200 + optional package@version probe
- Run before any deploy that needs @bytelyst/* from Gitea
1) Dual-numbering reconciliation
- ROADMAP groups Phase 1 by topic (1.1-1.8); PRH groups by execution
day (1.A-1.F). Added bidirectional mapping table to both docs so
agents can cross-reference any phase reference unambiguously.
2) Fresh-agent quick pointer at top of ROADMAP
- New section tells a new agent exactly which 4 docs to read, in
what order, and which task to pick up first (1.A from the tracker).
3) Broken sub-roadmap links neutralised
- 03_RICH_ITEMS_ROADMAP.md, 04_AGENT_API_ROADMAP.md,
05_INTAKE_ROADMAP.md were linked but did not exist. Replaced with
plain text + 'create when Phase N begins' note so the link doesn't
404. Matches the pattern already used in IMPLEMENTATION_TRACKER.
4) Runbook stubs created (Phase 1.F.11/1.F.12 placeholders)
- docs/runbooks/MEK_ROTATION.md — adapted from NoteLett bcad7d3
- docs/runbooks/SECRET_MANAGEMENT.md — secret inventory + resolution
path + compromise procedure + PII scrubbing rule
Each is a stub now; full content lands when Phase 1.F executes.
5) Stale 'today' wording removed from PRH baseline table
- Replaced 'after fix today' with 'as of 2026-05-25' so the doc
ages cleanly.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Moves 5 related docs into docs/devops/gitea-runner/ to keep this
multi-doc workstream from colliding with future roadmaps and
delegation prompts in docs/devops/.
Renames:
HOSTINGER_GITEA_RUNNER_ROADMAP.md -> ROADMAP.md
HOSTINGER_GITEA_ACT_RUNNER_SETUP.md -> ACT_RUNNER_SETUP.md
GITEA_PACKAGES_PUBLISH_WORKFLOW.md -> PUBLISH_WORKFLOW.md
HOSTINGER_GITHUB_RUNNER_SETUP.md -> _PLAN_B_GITHUB_RUNNER.md
CODEX_DELEGATION_PROMPT.md -> (same name, moved)
All internal cross-links updated via sed sweep. Verified no stale
references remain.
Adds README.md in the new folder as the index + pattern doc for
future multi-doc workstreams (one-liner handoff, file map,
architecture summary).
Updated one-liner handoff path:
Read docs/devops/gitea-runner/CODEX_DELEGATION_PROMPT.md ...
Captures the exact bootstrap prompt to paste to Codex on the
Hostinger VM, plus a one-liner that just points Codex at the prompt
file (after Codex has the repo).
Also documents how to monitor Codex's progress from Cascade side
(grep roadmap-update commits) and how to recover if it gets stuck
(the checkbox state in the roadmap IS the resume pointer).
Adds HOSTINGER_GITEA_RUNNER_ROADMAP.md — a single execution tracker
that Codex on the Hostinger VM works through phase-by-phase, ticking
checkboxes and recording commit hashes as it goes.
Structure:
- 6 phases (P0 Pre-flight → P5 First real release) + P6 review handoff
- Each task: [ ] checkbox + Commit hash field + Status note
- Detail steps live in the two companion docs (act_runner setup +
publish workflow); the roadmap is the orchestrator
- Final report section Codex fills in when P0-P5 are complete
- Human review checklist (R1-R9) for verification after handoff
- Operating notes: commit message format, when to ask, never-do list
- Change log table Codex auto-appends to
Critical invariant repeated at P3.6 and P5.4: cross-Gitea SHA1
comparison must match. If it doesn't, Codex stops — it's the
load-bearing architectural guarantee that the dual-Gitea, no-sync-
script model rests on.
Also adds roadmap-pointer banners to the two companion docs
(HOSTINGER_GITEA_ACT_RUNNER_SETUP.md, GITEA_PACKAGES_PUBLISH_WORKFLOW.md)
so anyone landing there knows the master tracker exists.
