Skip to content

0.6.2: export the key before the first pxt command, and fix the scaffolded cd - #3

Merged
pierrebrunelle merged 1 commit into
mainfrom
fix-scaffold-first-run
Sep 5, 2026
Merged

pierrebrunelle merged 1 commit into
mainfrom
fix-scaffold-first-run

Conversation

@pierrebrunelle

Copy link
Copy Markdown
Member

Checked this repo after merging pixeltable-skill#13 and pixeltable-starter-kit#8, since this tool fetches the starter kit's refs/heads/main live and unpinned — every change there ships to uvx pixeltable-new users immediately.

The scaffolding mechanism is unaffected by those merges: same 7 files extracted, project name substituted, floor now correctly pixeltable[serve]>=0.7.5. Verified by scaffolding from the real tarball, both patterns.

But the next steps this tool prints carried the same first-run break that PR #8 just fixed in the starter kit.

The break

cd myapp
uv sync
pxt schema update app.py agent      <- daemon starts here, without the key
pxt service update app.py agent     <- service inherits a keyless environment

pxt schema update starts the Pixeltable daemon, which imports app.py in-process (utils/app_module.py:62-88). pxt service update then spawns the service with subprocess.Popen and no env= (serving/service_manager.py:279-281), so it inherits the daemon's environment as of daemon start. The Anthropic client is built lazily in that service process from os.environ. A key exported afterwards never reaches /ask.

Re-running pxt service update does not fix it: the project fingerprint hashes files and the lockfile, never the environment, so the plan is already in agreement and nothing respawns. Recovery is pxt daemon restart, pxt service stop agent, pxt service update.

Anyone following the printed steps literally hit this. The export now leads the chat-agent steps, and --json gained a note field with the reason and the recovery — the JSON path is what agents consume, so the explanation has to be machine-readable too. video-search is unchanged: CLIP runs locally and needs no key.

The scaffolded cd

The bundled README said cd chat-agent — a directory a scaffolded project does not have. A user running uvx pixeltable-new myapp got myapp/README.md telling them to enter a directory that isn't there.

The kit's README is correct in its own context (someone inside the monorepo), so the fix belongs here rather than there — next to the pyproject.toml name substitution this tool already does. It now rewrites to the project name, or drops the line entirely when scaffolding into the current directory.

Also dropped the pxt service run reference from the README, matching the skill and starter kit: pxt service update is the serving command.

Verified

ruff check, ruff format --check, 34 tests (was 26). The 8 new tests cover the ordering invariant (export index < first pxt index, rather than a brittle exact-list match), that video-search stays keyless, that the note reaches both output paths, and both cd rewrite cases.

One existing test asserted NEXT_STEPS["chat-agent"] as an exact list and correctly failed on this change; updated rather than weakened.

Beyond the unit suite, scaffolded from the real starter-kit main and confirmed the output:

next_steps:
    cd realapp
    export ANTHROPIC_API_KEY=sk-...
    uv sync
    pxt schema update app.py agent
    pxt service update app.py agent

with README.md line 11 reading cd realapp and pyproject.toml carrying name = "realapp" and pixeltable[serve]>=0.7.5.

Worth knowing

The test suite cannot catch a starter-kit restructure. tests/conftest.py monkeypatches fetch_tarball with a synthetic in-memory tarball, which is right for unit tests — but it means the only thing this tool actually depends on at runtime, an unpinned refs/heads/main, is never exercised in CI. A restructure of the kit would break uvx pixeltable-new for everyone with a green build here. A scheduled or dispatch-only job that scaffolds from the real tarball and asserts the expected files would close that; I have not added one, since it is a scope call rather than part of this fix.

🤖 Generated with Claude Code

…olded cd

The next steps this tool prints reproduced the first-run break just fixed
in the starter kit. They were:

    cd myapp
    uv sync
    pxt schema update app.py agent      <- daemon starts here, no key
    pxt service update app.py agent     <- service inherits a keyless env

`pxt schema update` starts the daemon, which imports app.py in-process.
`pxt service update` then spawns the service with subprocess.Popen and no
env= of its own, so it inherits the daemon's environment as of daemon
start. The Anthropic client is built lazily in that service process from
os.environ, so a key exported afterwards never reaches /ask. Re-running
`service update` does not help either: the project fingerprint covers
files and the lockfile, never the environment, so the plan is in
agreement and nothing respawns.

Anyone following these steps literally hit that. The export now leads the
chat-agent steps, and `--json` carries a `note` with the reason and the
recovery. video-search is unchanged -- CLIP runs locally and needs no key.

Separately: the scaffolded README said `cd chat-agent`, a directory a
scaffolded project does not have. The kit's README is correct for someone
inside the monorepo, so the rewrite belongs here, next to the pyproject
name substitution that already exists. It now points at the project, or
drops the line when scaffolding into the current directory.

Verified end to end against the real starter-kit main, not just the
synthetic test tarball.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@pierrebrunelle
pierrebrunelle merged commit 696ac2d into main Sep 5, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant