flavien-ia/hypervibe-harness/track-resource

Track resource - Internal helper

You record a cloud resource in the project's resource manifest: .hypervibe/resources.json, at the project root, versioned with the code. You work silently - no user-facing message for a successful recording.

Why this matters

Backups and deletion used to rediscover resources by matching their names against the project name. That inference fails silently both ways: a bucket named differently from the project is missed (a backup ships without a single file), and a similarly-named resource of another project can be swept in. At the moment a resource is created, its identity is known with certainty - the manifest keeps that certainty. A resource that is not recorded is invisible to /save-project and /delete-project until their name-guessing fallback happens to find it.

The command

node "${CLAUDE_SKILL_DIR}/../../scripts/manifest/manifest.mjs" add \
  --project-dir "<project-root>" \
  --kind <kind> --name "<name>" \
  [--id "<stable-id>"] [--field k=v ...] \
  --added-by <calling-skill> [--shared] [--note "<short human note>"]

• `--project-dir` can be any folder inside the project: the tool anchors the manifest at the repository root on its own (nearest .git upward), and readers walk up the same way. One manifest per repository: a monorepo with several apps has a single manifest at its root, listing every app's resources (two Vercel projects deployed from one repo are two vercel-project entries in the same file); in an umbrella folder holding several repositories, each sub-repository has its own, and the umbrella never has one.
• Idempotent: re-running updates the entry in place (action: "unchanged" or "updated"). Call it unconditionally after the resource exists - including when the resource already existed and the skill merely connected it to the project.
• `--id` whenever a stable id exists (Vercel projectId, Neon project id, Stripe webhook id...). Ids survive renames; names do not.
• `--shared` for mutualized infrastructure (e.g. the hypervibe-jobs worker, used by every project on the machine). A shared resource is listed so backups know it exists, and deletion knows to NEVER remove it. Never on the project's own registrations on that worker: a cron-job calls this project's route and a db-backup is this project's database's (shared only if the database itself is declared shared). Marked shared, they would outlive the project; manifest.mjs add refuses it.
• The script prints one JSON line. ok: false means the write was refused - read reason and fix the call; do not silence it.

Kinds and their fields

Hard rules

1. Identifiers only, never secrets. No tokens, keys, passwords, connection strings. The script refuses field names and values that look like credentials - if it refuses, the fix is to drop that field, never to rename it around the guard.
2. `.hypervibe/` is committed. Never add it to .gitignore; the manifest documents the project's infrastructure for humans too. (Secrets never being in it is what makes this safe.)
3. Record after the resource exists, not before: a failed provisioning must not leave a phantom entry. If a skill deletes or replaces a resource (e.g. add-storage switching buckets), also run remove for the old one:

node "${CLAUDE_SKILL_DIR}/../../scripts/manifest/manifest.mjs" remove \
  --project-dir "<project-root>" --kind r2-bucket --name "<old-bucket>" --jurisdiction eu

1. The manifest is declarative, not authoritative. Consumers (/save-project, /delete-project) still scan the real accounts and surface differences; recording here does not replace their checks, it feeds them.