Repository navigation
fix: make a cold start work on a machine that already runs the project - #4
Merged
Merged
Conversation
Vite's default host is `localhost`, which resolves dual-stack. When another process already held IPv4 127.0.0.1:5173, Vite still bound [::1]:5173, skipped its port-increment path, and printed http://localhost:5173/ - a URL that opened the other application with no error anywhere. Bind 127.0.0.1 explicitly so the collision is visible and Vite moves to the next free port. An explicit OIP_WEB_PORT is now strict, because Docker, CI and shared links depend on that exact port.
The gallery port was fixed at 4173 with no fallback, and server_status only inspects the current checkout's .oip/, so a second checkout on the same machine reported "stopped" and then failed to bind. The bind failed instantly but the parent still burned the full 30s timeout before printing a raw traceback with the real cause on the last line. Probe the port first: fall back to a free port when 4173 is taken and no port was requested, and fail immediately with the owning process named when one was. The gallery URL now carries the port actually bound. Startup also detects a dead child instead of waiting out the timeout. The gallery is detached on purpose, so an agent session that ends without calling `stop` used to leak it forever - this repository had a proxy plus two Vite servers alive four days later, holding 4173. Add an idle watchdog defaulting to four hours, overridable through OIP_GALLERY_IDLE_TIMEOUT. Health probes do not count as traffic, so a monitor cannot keep an abandoned gallery alive. Also drop the Git LFS wording from the missing-dependency error and tell a Skill installed outside a checkout where to get the repository.
.gitignore excludes images/ and db/prompts.db.gz but .dockerignore only excluded db/*.db, so a checkout that had run `npm run data:pull` shipped 4.3 GB to the Docker daemon on every build. The build re-fetches the archive itself, so neither path belongs in the context. Measured on a full checkout: 4,336 MB down to 1.6 MB. Also pin the tar extraction filter instead of relying on the default, which warns on Python 3.12/3.13 and changed in 3.14. tarfile.data_filter exists exactly in the versions that accept the keyword, so this stays compatible with 3.10.0.
Both READMEs quoted 15,033 prompts and 25,216 images while the released dataset has 14,693 and 24,479, and three files still told readers to obtain a Git LFS corpus that no longer exists. Nothing guarded either claim. Add scripts/verify_docs.py, which reconciles the prose counts against data/public-corpus.json, rejects stale LFS instructions, and requires every style card to expose one unique id. It needs neither the database nor the network. Give the 17 cards whose heading is their id an explicit id bullet too, so all 39 cards are read the same way, and say so in the Skill: a heading is not a reliable id when six files use a prose title instead. AGENTS.md is the condensed entry point for an agent handed only the repository URL: how to start, where the dataset comes from, why no port may be hardcoded, the Skill contract, and what to run before committing.
…pm test windows-start-smoke.yml was the only workflow, so start.sh, npm test, lint and build never ran in CI. Its paths filter also omitted skills/**, scripts/** and tests/**, which is how the stale dataset counts and LFS instructions survived review. Add a Ubuntu and macOS matrix that runs start.sh and asserts the frontend answers on the loopback address the launcher was told to use - a dev server that bound another interface would pass a plain "did it start" check while serving nobody - plus a Ubuntu job running the full suite, lint, build and Skill readiness. Broaden the Windows paths filter to match, and add verify:docs and test:gallery to npm test. Both run without the database, so they fail before the 80 MB download.
5 tasks done
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Verified the README path end to end from a fresh clone — full 4.24 GB dataset from
GitHub Releases, both Skills installed with
npx skills add -g,npm test/ lint /build / status all green. Three problems only appear once something else on the
machine holds a port, which is exactly the state a second checkout or a returning
user is in.
The printed URL could open a different application. Vite's default host
localhostresolves dual-stack, so with IPv4127.0.0.1:5173already taken itstill bound
[::1]:5173, skipped its port-increment path, and printedhttp://localhost:5173/. That URL served the unrelated app on IPv4, silently.Binding
127.0.0.1explicitly makes the collision visible.The Skill gallery could not start at all in a second checkout. Port 4173 was
fixed with no fallback,
server_statusonly inspects the current checkout's.oip/, and although the bind failed instantly the parent waited the full 30 sbefore printing a traceback whose real cause was on the last line.
url_usable: truelsofstdoutstays pure JSON; notices go tostderr.Abandoned galleries leaked forever. The process is detached on purpose, so a
session ending without
stopnever reaped it — this machine had a proxy plus twoVite servers alive four days later, and they were what held 4173. Added an idle
watchdog (four hours,
OIP_GALLERY_IDLE_TIMEOUT); health probes deliberately donot count as traffic.
Plus the drift these gaps hid: both READMEs quoted 15,033 prompts / 25,216 images
against an actual 14,693 / 24,479; three files still pointed at a Git LFS corpus
that no longer exists;
.dockerignoremissedimages/anddb/*.db.gz, shipping4.3 GB of build context; and
windows-start-smoke.ymlwas the only workflow, witha paths filter that excluded
skills/**andscripts/**— so none of this couldhave been caught.
scripts/verify_docs.pyreconciles prose counts againstdata/public-corpus.json,rejects stale LFS wording, and requires every style card to expose a unique id.
No database, no network.
are read the same way.
AGENTS.mdfor an agent handed only the repository URL.tar.extractfilter pinned (warns on 3.12/3.13, changed in 3.14), guarded soPython 3.10.0 still works.
Test Plan
npm test(docs, public-data boundary, API, gallery ports, 72-queryretrieval benchmark, frontend),
lint,build,status— green on acheckout with the full 24,479-file corpus
precision_on_returned0.9567127.0.0.1:5173, confirmed the printedURL serves this app and nothing bound
[::1]:5173gallery page and session JSON reachable on the fallback port
removed); stays alive under periodic traffic
OIP_WEB_HOST=0.0.0.0still binds*:4193and printsa network URL;
strictPortfails loudly instead of driftingverify_docs.pyfails on an injected wrong count and on a removed card id./start.shcompletes all four steps unattendeddocker build/docker runnot executed — no Docker daemon available onthis machine. The
.dockerignorefix is measured statically.