Why
Updating the dashboard checkout does not update its installed dependencies. A recent sync fast-forwarded to code importing ajv, but the existing node_modules did not contain it. The repository sync appeared successful and the dashboard then failed at startup with ERR_MODULE_NOT_FOUND.
The repository already has .agents/bin/setup, which runs npm ci, but the full-stack synchronizer needs a stable component-owned entrypoint outside the consumer-agent seam.
Requirements
- R1: Provide an executable, noninteractive, idempotent
bin/setup entrypoint suitable for invocation immediately after a trusted checkout is synchronized.
- R2: Install the exact dependency graph from
package-lock.json; do not update dependency versions or rewrite the lockfile.
- R3: Keep one implementation source:
.agents/bin/setup should delegate to bin/setup, or both should delegate to one shared helper.
- R4: Return nonzero with actionable output when dependency installation fails.
- R5: Document the contributor and
agent-stack setup contract.
Acceptance criteria
- From a clean clone without
node_modules, bin/setup installs dependencies and the repository build/type-check seam can run.
- After adding a locked dependency while retaining stale
node_modules, rerunning bin/setup makes the newly required package available.
- Repeated setup succeeds without changing tracked files.
- Tests cover entrypoint delegation and failure propagation without contacting the real package registry.
Non-goals
- Starting or restarting the dashboard.
- Changing dependency versions.
- Adding machine-specific paths, hostnames, credentials, or SSH behavior.
Validation
Use the repository commands resolved through AGENTS.md and .agents/agent-workflow.yml, including focused setup-contract tests and the normal validation gate.
Why
Updating the dashboard checkout does not update its installed dependencies. A recent sync fast-forwarded to code importing
ajv, but the existingnode_modulesdid not contain it. The repository sync appeared successful and the dashboard then failed at startup withERR_MODULE_NOT_FOUND.The repository already has
.agents/bin/setup, which runsnpm ci, but the full-stack synchronizer needs a stable component-owned entrypoint outside the consumer-agent seam.Requirements
bin/setupentrypoint suitable for invocation immediately after a trusted checkout is synchronized.package-lock.json; do not update dependency versions or rewrite the lockfile..agents/bin/setupshould delegate tobin/setup, or both should delegate to one shared helper.agent-stacksetup contract.Acceptance criteria
node_modules,bin/setupinstalls dependencies and the repository build/type-check seam can run.node_modules, rerunningbin/setupmakes the newly required package available.Non-goals
Validation
Use the repository commands resolved through
AGENTS.mdand.agents/agent-workflow.yml, including focused setup-contract tests and the normal validation gate.