Skip to content

Polish the CLI and README from two QA rounds - #2

Merged
amagdy46 merged 8 commits into
mainfrom
polish-cli
Oct 22, 2026
Merged

amagdy46 merged 8 commits into
mainfrom
polish-cli

Conversation

@amagdy46

Copy link
Copy Markdown
Owner

Two rounds of hands-on QA of create and add (real terminal sessions, CI/pipe mode, every flag), plus README research across similar CLIs.

CLI

  • Fails fast without a terminal and names the flag to pass, instead of hanging.
  • Ctrl-C exits 130 and prints the commands that finish setup. clack's spinner called process.exit(0) on Ctrl-C, so steps now use a small spinner that leaves SIGINT alone.
  • Checks for pnpm (and warns about Node, skips missing git) before writing anything.
  • The name prompt re-asks when the directory isn't empty; . scaffolds in place.
  • Next steps for the stack (docker, pnpm db:migrate, Alchemy).
  • Errors say why (auth needs a database), suggest fixes for typos, and say which ids to add together.
  • add: a +/~ change summary, warnings for removed files, replaced scripts and a dirty tree, the new env vars, install only when dependencies changed.
  • New efforge list; --json errors as JSON; help examples; EPIPE handled.
  • Fix: add infra/alchemy after earlier adds no longer reports a false edit to wrangler.jsonc (regression test).

Docs

  • Shorter README built around a VHS recording (tape committed in .github/assets/demo.tape); limits moved to docs/limits.md; docs/cli.md covers CI use, exit codes and list.
  • The generated README explains database setup.

Also includes the two unreleased lint commits already on local main.

Verified: pnpm check, 227 unit tests, real generated projects pass pnpm check after create and after add.

Adopt rat-stack's lint fence ideas: a local oxlint plugin rejects manual
Effect runners in test files, and no-restricted-imports keeps the
cloudflare:workers env import in server/cloudflare.ts. The generated
AGENTS.md gains a Tests section and a lifecycle rule; decision 0003
records what was adopted and deferred.
Take two rules from Ultracite's oxlint preset after measuring it on a
generated stack. Fix what they found in the templates: FormEvent becomes
SubmitEvent, and async React handlers are wrapped as () => void fn().
From a hands-on QA pass of create and add:

- Prompts without a terminal (CI, pipes, npm eating flags) fail with the
  exact flag to pass instead of hanging.
- Ctrl-C exits 130; stopping during setup says what is left to run.
- pnpm is checked before any prompt; a failed install lists the steps that
  remain. Unsupported Node versions get a warning; missing git skips git.
- The name prompt rejects an occupied directory and asks again. A directory
  holding only .git counts as empty, and `.` scaffolds in place.
- Incompatible flags say why (auth needs a database, ...); unknown values
  say unknown. --json reports errors as JSON. Duplicate extras are dropped.
- The install shows its latest output line and every step its duration;
  in CI or a pipe, steps print one line each without spinner frames.
- create ends with next steps for the stack (docker, db:migrate, Alchemy).
- add gets the same chrome: a change summary (+ new, ~ edited), warnings for
  removed files, replaced scripts and a dirty tree, the new env vars, and
  ids that are case-insensitive with a did-you-mean.
- add explains which ids to add together (database + ORM + auth).
- New `efforge list` shows every add-on and marks what a project has.
- Help shows examples.
- README: the bare install command first, a VHS recording of create and
  add (tape committed next to the GIF), the differentiators as four
  bullets, the stack table, an "Add more later" section for add/list.
  Limits moved to docs/limits.md.
- docs/cli.md: `.`, CI and scripting (no-TTY behaviour, exit codes, JSON
  errors), `efforge list`, and the new `add` output.
- The generated README explains the database setup before `pnpm dev`.
- add skips `pnpm install` when no dependencies changed; Alchemy next
  steps leave out D1 migrations, which still need wrangler.jsonc.
- Ctrl-C during a step now exits 130 with recovery steps. clack's spinner
  put stdin in raw mode and called process.exit(0) on Ctrl-C, skipping
  cleanup; steps use a small spinner of our own that leaves SIGINT alone.
- The stop message says whether files were written and what remains.
- add infra/alchemy compares wrangler.jsonc as data and comments, so edits
  by earlier adds no longer read as user edits (regression test added).
- add prints docker/db:migrate when it adds a database, wraps env var
  descriptions instead of cutting them, lists replaced scripts one per
  line, checks for pnpm before writing, and reports unknown ids as
  UnknownAddon with prefix-first suggestions. Hints no longer suggest two
  ORMs or blame orm/none.
- create: dry runs warn about a non-empty target and print `.` for in-place
  runs; reasons replace the redundant Options list; npm-reserved names are
  refused.
- list: full descriptions when piped, errors on a missing --cwd.
- EPIPE on stdout/stderr exits quietly.
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-22T11:19:35.057520Z f9f4edf PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

release.yml runs on v* tags: checks the tag against package.json, runs
the unit checks, publishes with npm trusted publishing (OIDC, provenance,
no token) and creates the GitHub release from the CHANGELOG section.
CONTRIBUTING documents the release steps.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f9f4edf373

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/commands/add.ts Outdated
Comment on lines +707 to +709
const io = input.json
? { ...live, step: <A, E, R>(_: string, eff: Effect.Effect<A, E, R>) => eff }
: live

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Silence tasks as well in JSON mode

When add --json installs a dependency-changing add-on, this override silences only step; the later io.task("Installing dependencies…") still uses the live implementation and writes progress to stdout before the JSON result. That makes successful output from cases such as adding auth or AI invalid JSON for callers to parse, so JSON mode needs to replace task with a silent passthrough too.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in fd29a1c. In this version --json actually returned before the install, so add --json skipped pnpm install and the route tree altogether. JSON mode now silences both step and task, runs them, then prints the JSON. Test added: add --json still installs, and stdout stays one JSON document.

--json returned before the install step, so it never ran pnpm install
or regenerated the route tree. It now runs both with step and task
silenced, then prints the result as the only output. Found in review.
@amagdy46
amagdy46 merged commit 68f7332 into main Oct 22, 2026
19 checks passed
@amagdy46
amagdy46 deleted the polish-cli branch October 22, 2026 11:25
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