Imported from aditi-2827/ShipCheck (AGENTS.md). Install upstream with npx skills add aditi-2827/ShipCheck. Copyright stays with the author.

AGENTS.md

ShipCheck: a dark, terminal-inspired "deployment-readiness" analyzer. Frontend is a Next.js 14 App Router + React 18 + Tailwind single-page UI; there is also a real local backend (Next.js Route Handlers) for auth, feed data, scan execution, and persisted history. No external APIs/dependencies; everything (scanning, auth, storage) is implemented locally with Node built-ins.

Commands

• npm run dev — start dev server (http://localhost:3000)
• npm run lint — ESLint (next lint)
• npm run build — production build
• There is no typecheck script. Run npx tsc --noEmit to typecheck.
• No test script — so a scan's "Tests" check reports "not configured" until one is added.
• No CI workflows directory (.github/).

CLI (node bin/shipcheck.js / global shipcheck)

The CLI is the primary entry point (see bin/shipcheck.js):

• shipcheck server — the canonical way to start the server. Generates/reuses a boot token, auto-runs next build if .next/BUILD_ID is missing, spawns next start (or next dev with --dev), and prints Dashboard: http://<host>:<port>/?token=<bootToken>. If a ShipCheck server already answers on the port and accepts our token, it reuses it instead of spawning a duplicate. Options: --port N (default 3140), --host H (default 127.0.0.1), --dev.
• shipcheck init — register the current directory as a project (writes .shipcheck.json). Optionally --deploy-url URL to set the deployed application URL (enables Phase 3 post-deployment/API/perf checks).
• shipcheck scan — real scan of the current directory against the server (slow; runs build/tests).
• Commands run in the current directory; for monorepos run init/scan once per package root.
• The CLI talks to http://localhost:3140 by default; override with SHIPCHECK_SERVER_URL.
• Auth: the CLI authenticates using the boot token from SHIPCHECK_BOOT_TOKEN or ~/.shipcheckrc (sent as x-shipcheck-token), else a persisted session cookie, else SHIPCHECK_PASSWORD login.
• A server started by the CLI (or with SHIPCHECK_BOOT_TOKEN set) publishes the token to ~/.shipcheckrc via next.config.mjs, so the CLI can discover it no matter how the server was started.

Backend architecture

Route Handlers under src/app/api/, shared logic in src/lib/. All server-side, no external services:

• src/lib/types.ts — shared domain types (Issue, CategoryResult, ScanResult, FeedData, …).

• src/lib/data.ts — static feed reference (FEED_DATA: categories, stages, thresholds, categoryWeights). Single source of truth for weights (sum to 100) and the 80/60 thresholds. Bumped schemaVersion to 4 when Phase 4 rebalanced the weights.

  All 16 categories, with Phase 4 weights (score contribution when healthy):

  Category	slug	Weight	Phase
  Security	security	18	1
  Build	build	15	1
  Tests	tests	10	1
  Code Quality	code_quality	8	2
  API Check	api_check	8	3
  Deployment	deployment	6	2
  Dependencies	dependencies	6	1
  Post-Deploy	post_deployment	5	3
  Performance	performance	5	3
  Monitoring	monitoring	4	2
  Database	database	4	1
  Git	git	4	1
  CI/CD	ci_cd	3	1
  Docker	docker	2	1
  Rollback	rollback	1	1
  Environment	environment	1	1

  Weighting rationale (Phase 4): security + build stay dominant (blockers each lose all weight); tests/code-quality/API hold meaningful shares; "easy" heuristics (docker, rollback, environment, git) get the smallest shares so they can't inflate the score on their own.

  deployUrl flow: a project may carry an optional deployUrl (set via shipcheck init --deploy-url URL, stored on the Project record, or passed per-scan in the /api/scan body as deployUrl). When set, Phase 3 checks (API Check, Post-Deploy, Performance/Lighthouse) run for real. When unset, those three render as pass-status placeholders ("Set a deploy URL to enable …"). runScan(targetDir, projectId?, options?) and scanBody read options.deployUrl (preferring a per-scan body override over the stored Project value).

• src/lib/checks.ts — the real scan engine (runScan). Runs node/npm versions, git status/branch, npm audit, npm run build, npm test, docker presence, and a local regex secret scan + .env.example coverage. Persists each result via the store. The temp build/test workspace is a full-tree copy of the target (excluding node_modules, .next, .git, .data, dist, build, .env*; node_modules is reused via a Windows junction), so nested src/ layouts (e.g. app/, monorepo sub-packages) work. Scoring is per-category weighted (categoryWeights in data.ts, a warning keeps half its weight, a critical category contributes 0). Build/tests with no npm run <script> configured are warnings ("No build script configured"), not criticals. .env.example checks make no assumptions about required variable names; the secret scan walks the whole tree (never node_modules/.next/.env*).

  Phase 1 + Phase 2 checks (implemented): Git (branch, working-tree, .gitignore presence + critical entries), Database (detects Prisma/Drizzle/Knex/Supabase + raw pg/mysql/mongo drivers from config files or package.json deps; checks for a migration directory), CI/CD (detects GitHub Actions, GitLab CI, Jenkins, CircleCI, Bitbucket, Travis, Azure; validates YAML indentation + non-empty), Rollback (git version tags + optional rollback config), Security (secret scan + .env.example + console.log/debugger detection), Code Quality (runs the project's own ESLint config via the programmatic ESLint API, reports errors/warnings), Deployment (detects + validates Vercel/Netlify/Fly/Railway/Procfile/Heroku app.json configs), Monitoring (detects Sentry/LogRocket/Datadog from deps or source + React error boundaries).

  Phase 3 checks (implemented — all gated on options.deployUrl, from the Project record or scan body; render as pass-status placeholders when no deployUrl is set):

  • API Check (api_check): live HTTP probes via Node built-in http/https (probeUrl helper) against the deploy root, {root}/api/health, and {root}/api/status; flags any non-2xx/3xx and reports latency.
  • Post-Deployment (post_deployment): smoke test — one GET to the deploy root, fails if non-2xx or > 5s latency.
  • Performance (performance): bundle-size analyzes the (temp-workspace) build output's .next/static/chunks (warning if no build output); lighthouse runs a full Lighthouse performance audit (perf score + LCP) via scripts/lighthouse-run.cjs, a standalone CommonJS child process spawned through runCommand(['node', ...]). Because puppeteer/lighthouse are heavy and break Next's webpack static analysis, they are deliberately kept out of the server bundle and isolated in that child script (loaded from node_modules at runtime). Thresholds: perf ≥ 90 pass, 50–89 warning, < 50 critical.
  • deps: puppeteer (bundled Chromium) + lighthouse are dev deps. @types/eslint is a devDependency for the Code Quality ESLint integration.

• src/lib/store.ts — file-based JSON persistence under .data/ (gitignored): scan history, auth secret, sessions. Swappable for a real DB later.

• src/lib/http.ts — response envelope { ok:true, data } | { ok:false, error:{code,message,details?} } and ApiError/readJson/errorResponse helpers.

• src/lib/auth.ts — local session-cookie auth: password from SHIPCHECK_PASSWORD env, stored only as an scrypt hash (Node crypto), random session token in HttpOnly SameSite=Strict cookie.

API routes

All API routes declare export const dynamic = 'force-dynamic' to avoid prerendering.

Run requirements

• Scanning runs npm run build / npm test synchronously server-side, so /api/scan is slow (tens of seconds) and side-effecting. Timeouts exist per check.
• SHIPCHECK_PASSWORD must be set or login returns a 500 (INTERNAL). There is no default. Sessions expire after 12h.

Windows gotchas (this repo is developed on Windows)

• Command spawning: in checks.ts, commands run via exec (shell) on Windows. execFile will fail on npm/npx because they are .cmd shims not resolved through PATH. Do not switch to execFile for npm commands on Windows.
• Child-process commands are hard-coded literals (no user input), so shelling out is safe.
• Temp-workspace node_modules junction: the scan's temp build/test workspace reuses node_modules via a Windows junction. Next.js Turbopack builds can fail inside such a workspace ("Symlink ... node_modules is invalid, it points out of the filesystem root") — a pre-existing Windows limitation, not a scan-engine regression. Webpack builds (the default) generally work.

Frontend (src/app/page.tsx)

'single-page client view. The "RUN SHIPCHECK" button and the status/timeline data are still simulated client-side (useState + setTimeout, e.g. runScan around line 33) and are not yet wired to the /api/* backend. So flipping page.tsx to consume runScan results is a known unfinished integration, not a regression. Hand-written CSS in src/app/globals.css (not Tailwind utilities); semantic color tokens live in tailwind.config.ts.

Gotchas

• next.config.mjs sets optimizePackageImports: ['lucide-react'], but lucide-react is not installed. Don't import it unless you add it to package.json.
• reactStrictMode: true is on — be aware effects run twice in dev.
• Never add external scanning/auth/AI dependencies; core functionality must stay local.