worktree-tilt-schema

model	haiku
name	worktree-tilt-schema
description	Temporarily modifies a Tiltfile in a git worktree so the NestJS app can boot and regenerate schema.gql, then reverts the Tiltfile. Use when the user says to regenerate schema.gql, when schema.gql is stale after @Field decorator changes, when CI's schemaDiff smoke test fails, or when tilt up in a worktree fails with 'local_resource named X already exists'.

Worktree Tilt Schema Regeneration

Temporarily modify a Tiltfile in a git worktree so the NestJS service can boot locally and regenerate schema.gql, then revert the Tiltfile.

Problem

Git worktrees live under .claude/worktrees/ (or similar), so the Tiltfile's relative ../ upstream includes resolve to the wrong directory. Upstream Tiltfiles also form circular chains that re-include the current repo's Tiltfile, causing local_resource named "X" already exists errors.

When to use

• You changed @Field decorators (e.g. adding { nullable: true }) and need to regenerate schema.gql.
• CI's smoke test (test/smoke/schemaDiff.spec.ts) fails because schema.gql is stale.
• You are in a git worktree and tilt up fails with resource-already-exists errors.

Hard rules

• NEVER edit schema.gql by hand. It must be regenerated by booting the NestJS app.
• NEVER commit the Tiltfile changes. Revert them in Step 7 before finishing.
• If any command below fails in a way not covered by an "If" branch, stop immediately and report the exact command and its full error output to the user. Do not improvise a workaround.

Workflow

Step 1: Confirm you are in a worktree

Run both commands:

pwd
git worktree list

Expected output: git worktree list prints one line per checkout. The FIRST line is the main repo. Compare the pwd output to the list:

• If pwd matches a line AFTER the first line, you are in a worktree. Continue to Step 2.
• If pwd matches the FIRST line, you are in the main repo, not a worktree. Stop and tell the user: "You are in the main repo, not a worktree. This skill is only for worktrees; in the main repo, run tilt up normally."
• If git worktree list fails (not a git repo), stop and report the error.

Step 2: Comment out the upstream includes in the Tiltfile

1. Read the file Tiltfile in the current directory. If it does not exist, stop and report: "No Tiltfile found in this directory."
2. Find every line that contains mryum_v1.include_upstream(. Prepend # to each of those lines.
3. Add this comment line directly above the first commented-out include: # TEMPORARY: upstream includes disabled for worktree schema generation
4. Do NOT modify any include('./tiltfile.d/...') lines. Those define the actual service resources (manage-api, manage-worker, etc.) and must stay active.

Before:

mryum_v1.include_upstream("../menu-api/Tiltfile")
mryum_v1.include_upstream("../mr-yum/dev-env/Tiltfile")
include('./tiltfile.d/manage-api.star')
include('./tiltfile.d/manage-worker.star')

After:

# TEMPORARY: upstream includes disabled for worktree schema generation
# mryum_v1.include_upstream("../menu-api/Tiltfile")
# mryum_v1.include_upstream("../mr-yum/dev-env/Tiltfile")
include('./tiltfile.d/manage-api.star')
include('./tiltfile.d/manage-worker.star')

5. Verify with:

grep -n 'include_upstream' Tiltfile

Every line of output must begin with a # after the line-number prefix. If ANY matching line is not commented out, go back to substep 2 and comment it. Do not continue until all matches are commented.

Step 3: Confirm infrastructure services are running

The manage-api service depends on external services (CockroachDB, Redis, Redpanda, etc.) that are normally started by the upstream includes you just disabled. They must already be running from the main repo's Tilt session or from docker-compose.

Tell the user exactly: "Make sure your infrastructure services (DB, Redis, Redpanda) are already running from the main repo or docker-compose before running tilt up here."

Wait for the user to confirm before continuing.

Step 4: Boot the service

Tell the user to run, in the worktree directory:

tilt up

• If it fails with a port conflict (an existing Tilt session is using the default port), tell the user to instead run:

tilt up --port 10351

• If it fails with local_resource named "X" already exists, go back to Step 2 substep 5: at least one include_upstream line is still active.

Wait for the manage-api service to become ready. Check http://127.0.0.1:5010 (or the port configured for the service). The NestJS app regenerates schema.gql on startup via the @nestjs/graphql autoSchemaFile option.

Step 5: Verify schema.gql was regenerated

git diff -- schema.gql

• If the diff shows the expected changes (e.g. Boolean! becoming Boolean for newly nullable fields, or String! becoming [String!]! for array fields): continue to Step 6.
• If the diff is EMPTY: do NOT commit anything. Go to Troubleshooting ("schema.gql not changing"), then report findings to the user.
• If the diff shows unrelated or unexpected changes: stop, show the diff to the user, and ask how to proceed.

Step 6: Commit schema.gql only

Stage and commit ONLY schema.gql. Do not stage the Tiltfile.

git add schema.gql
git commit -m "chore: regenerate schema.gql for nullable field changes"

If the field change was not about nullability, replace the text after chore: regenerate schema.gql with a short description of the actual change.

Step 7: Revert the Tiltfile

git checkout -- Tiltfile

Verify the revert:

git status --short Tiltfile

Expected output: nothing (empty). If Tiltfile still appears as modified, stop and report the git status output to the user.

Step 8: Stop the worktree Tilt session

Tell the user to press Ctrl+C in the Tilt terminal, or to run in the worktree directory:

tilt down

Then report to the user: schema.gql was regenerated and committed, the Tiltfile was reverted, and the worktree Tilt session is stopped.

Troubleshooting

local_resource named "X" already exists

The upstream includes are circling back into the current repo. Run grep -n 'include_upstream' Tiltfile and confirm EVERY matching line is commented out (Step 2 substep 5).

Service fails to connect to DB/Redis/Redpanda

The infrastructure services are not running. Ask the user to start them from the main repo's Tilt session or docker-compose (Step 3), then retry tilt up.

schema.gql not changing

The NestJS app may not have booted successfully. Check the Tilt UI or logs for startup errors and report them to the user. The schema is only written when the app boots, because @nestjs/graphql autoSchemaFile generates it on startup.