feat(project): experimental project setup command (RFC / discussion)

[Xe]

What this is

An experiment in a prompt-guided, zero-config setup flow for getting a project wired to Tigris in one command. It's opened as a draft PR to foster discussion — not a finished, ship-ready feature. The goal is to get eyes on the UX and the agent-resource bits and decide what (if anything) we want to keep.

tigris project setup

Runs the whole onboarding flow end-to-end:

1. Auth — if not logged in, pops the browser via the OAuth device flow. Respects existing auth (env vars / credentials / configured).
2. Bucket — creates a randomly named color-adjective-animal bucket (via unique-names-generator), or --bucket <name>.
3. Access key — mints <bucket>-key and assigns it the Editor role scoped to that bucket.
4. .env — writes TIGRIS_STORAGE_{ACCESS_KEY_ID,SECRET_ACCESS_KEY,ENDPOINT,BUCKET} (mode 0600) for @tigrisdata/storage. Detects an existing .env early and aborts ("already set up") unless --force.
5. npm packages (best-effort, non-fatal) — runs npm install @tigrisdata/storage @tigrisdata/agent-kit in the project. --skip-install opts out.
6. Agent skills (best-effort, non-fatal) — fetches the tigrisdata/skills tarball and installs the Tigris storage skills into .agents/skills/, with relative per-skill symlinks in .claude/skills/ (won't clobber existing real dirs). --skip-agent-setup opts out.

If bucket/key creation fails partway, the bucket is rolled back so a retry isn't blocked. The npm and skills steps are best-effort: a missing npm/tar, no network, or a failed install is reported but never aborts setup.

Because installed skills don't take effect in the agent session that launched setup, the command advises starting a fresh agent session to adapt the app to Tigris. (Earlier revisions optionally installed the Claude Code plugin under CLAUDECODE; that path was dropped — installing a plugin mutates global config and can't take effect in the same session, so setup always installs skills instead.)

tigris project setup
tigris project setup --bucket my-app --access public
tigris project setup --skip-install --skip-agent-setup

Open questions for discussion

• Is bundling agent-resource install (skills) and npm install into project setup the right call, or should those be their own commands?
• Scope of skills installed (currently a Tigris-storage allowlist) and the .agents/skills + .claude/skills symlink layout.
• Default run mode is auto-run, best-effort — should it confirm first instead?
• Should the network/exec side effects (tarball fetch, npm install) be opt-in rather than opt-out?

Testing

• npm run build (tsc + tsup), npm test (727 passing / 187 skipped), npm run lint, npm run format:check — all clean.
• README regenerated from the spec via npm run updatedocs.
• Manually smoke-tested the skills tarball path end-to-end (tarball → .agents/skills + resolving .claude/skills symlinks).

Assisted-by: Claude Opus 4.8 via Claude Code

---

Note

Medium Risk
Creates real buckets and access keys in the user's org and writes secrets to disk; npm/tarball fetch and symlink writes are opt-out side effects on the local project.

Overview
Adds a new tigris project command group with project setup, a one-shot onboarding flow that provisions cloud resources, writes local config, and optionally prepares the repo for app and agent use.

tigris project setup runs auth (OAuth if needed), creates a bucket (random color-adjective-animal name or --bucket), mints an Editor-scoped access key, and writes a mode-0600 .env with TIGRIS_STORAGE_* vars. It stops early if .env already exists unless --force. Failed key/IAM steps trigger bucket rollback so retries are not blocked.

By default it also runs best-effort npm install for @tigrisdata/storage and @tigrisdata/agent-kit (--skip-install), and downloads Tigris storage skills from GitHub into .agents/skills with symlinks under .claude/skills (--skip-agent-setup). Those side effects never fail the core setup.

Docs/specs/README are updated; unique-names-generator is added for default bucket names. Vitest coverage covers setup orchestration, npm install, and skill install behavior.

^{Reviewed by Cursor Bugbot for commit 9cb70c7. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 9cb70c7. Configure here.}

[cursor]

Rollback omits created access key

Medium Severity

After a successful createAccessKey, failure paths only call rollbackBucket and never delete the new key. The leftover ${bucketName}-key can block a retry with the same --bucket name, and leaves an orphaned credential if .env write fails after the secret was only in memory.

Additional Locations (1)

• src/lib/project/setup.ts#L98-L108

 

^{Reviewed by Cursor Bugbot for commit 9cb70c7. Configure here.}