agentleFS
GTStaggGTStagg/project-eyas/.claude/skills/validate-bundle/SKILL.md

validate-bundle

Skill2 starsChanged yesterdayMITView on GitHub

Use immediately after `./make-dist.sh` to verify the standalone bundle is shippable. Runs structural checks (no dev data leak, no retired falcon-extras files, native binaries absent, eyas-mcp wheels staged, BUILD-INFO matches package.json) and an optional smoke-boot. Trigger phrases: "validate the bundle", "is the zip shippable", "check make-dist output", "verify the standalone build".

  • Reads credentials
  • Deletes or force-pushes

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    All structural checks ✓. If boot enabled, /api/health returned 200 within 60s and /login + /register both rendered.

    line 53

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

validate-bundle

Catches the failure modes we've hit on real ship days. Each check below maps to a specific bug we've already paid for.

Run

bash .claude/skills/validate-bundle/run.sh

That script auto-locates the most recent project-eyas-v*.zip in the repo root, runs every check below, and exits non-zero on any failure.

To target a specific bundle:

bash .claude/skills/validate-bundle/run.sh path/to/project-eyas-vX.Y.Z.zip

Checks performed

Structural (fatal on miss)

  1. No dev data/ leak. unzip -l must NOT show project-eyas-vX/data/auth.json, data/cost-log.jsonl, data/perf-log.jsonl, or data/dev.log. Next.js NFT tracing previously copied the dev host's data/ into the standalone tree; recipients then saw the dev's password hash + cost log. make-dist.sh scrubs $STAGE/data — this check verifies the scrub.
  2. No retired falcon-extras/ files or vendor/falcon-extras-wheels/. The sidecar was removed; every Eyas tool runs in-process. Anything under those paths means a stale staging step crept back into make-dist.sh.
  3. No platform-specific native bindings. Anything matching *.node (e.g. @node-rs/argon2-linux-x64-gnu/argon2.linux-x64-gnu.node) means a native module slipped back into the bundle. We migrated off @node-rs/argon2 to crypto.scrypt to avoid this; if a .node file appears, a new dep brought a native binding back.
  4. eyas-mcp wheels staged. vendor/falcon-mcp-wheels/ must contain at least one .whl. Without wheels the recipient's offline install path falls back to PyPI, which corp-blocked networks can't reach.
  5. BUILD-INFO.txt and build-info.json present and consistent. Both must exist; build-info.json.appVersion must equal package.json.version. Catches version drift after a forgotten npm version bump.
  6. server.js at bundle root. The bundle's entrypoint. Without it, start.sh errors with the "may be corrupt" message. 7b. Gateway lock, if requested. The lock is opt-in (ANTHROPIC_GATEWAY_BASE_URL at make-dist.sh time). An unlocked default build passes. A bundle whose build-info.json claims a lock must carry forcedGatewayUrl in its compiled .next/ output, or the check fails. REQUIRE_GATEWAY_LOCK=1 makes an unlocked bundle fail too.
  7. start.sh is executable (mode bit set in zip).

Smoke-boot (skippable)

Beyond structural checks, the only definitive proof the bundle works is launching it. The skill optionally:

  1. Extracts the zip to a /tmp/<bundle-name>-validate-$$/ dir.
  2. Writes a minimal .env containing only AUTH_SESSION_SECRET=<random> (no real Falcon/Anthropic creds — the bundle now supports running with empty credentials, deferring config to /register).
  3. Starts node server.js in the background.
  4. Polls http://127.0.0.1:<port>/api/health until 200 (timeout 60s).
  5. Asserts /login and /register both render (HTTP 200, contains "CrowdStrike — For Internal Use Only" classification banner copy).
  6. Kills the process, removes the temp dir.

Pass this stage (SKIP_BOOT=0, the default) only after the structural checks all pass — there's no point booting a bundle that's missing files.

To skip boot (faster, structural-only): SKIP_BOOT=1 bash .claude/skills/validate-bundle/run.sh.

Pass criteria

All structural checks ✓. If boot enabled, /api/health returned 200 within 60s and /login + /register both rendered.

Fail handling

CheckLikely causeFix
data/ leakNFT trace re-copying the dev tree's data dirRe-check make-dist.sh has rm -rf "$STAGE/data" after the standalone copy
Retired falcon-extras files presentA sidecar staging step was restored in make-dist.shRemove it; nothing under falcon-extras/ ships
Native .node fileNew dep with a per-platform binaryReplace with a JS / WASM equivalent (cross-platform standalone is the constraint; see auth scrypt migration as precedent)
Wheels missingBuild host doesn't have python3, or PyPI was unreachable during buildRe-run on a host with PyPI access; the warning is in make-dist.sh stderr
Gateway lock not in compiled outputThe build-flags.ts bake didn't take before npm run buildRebuild with ANTHROPIC_GATEWAY_BASE_URL set and no dev server running
BUILD-INFO.txt version driftnpm version bump didn't happen, or versions.json wasn't updatedBump appropriately and rebuild
Boot fails on /api/healthBundle is structurally sound but server crashes on startupRead node server.js stderr from the temp dir; common cause is a missing optional dep

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.