fix(project create): guide to name it instead of inventing a junk-named project

[tonychang04]

Follow-up to the no-prompt fix (#46), per design discussion: a bare insta project create in a generic dir (~/projects, /tmp, the home dir) was auto-generating a random name (swift-meadow-482) and provisioning real postgres/storage/compute under it — too much for a bare command.

Now it guides instead of inventing:

$ cd ~/projects && insta project create
name your project:  insta project create <name>
  (or just ask your coding agent — it has the insta skill and will do this for you)

• Still never prompts/hangs.
• Still uses the dir basename when it's a real project-dir name (~/my-app → my-app).
• Agents pass a name via the skill, so the guide path is only the manual bare case.
• resolveProjectName now returns string | null (null = guide); dropped the name generator.

77/77 tests green, tsc clean; verified with a built binary that a projects dir guides and does not create.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GMbAe5K1RfwaAcge5inX7P

---

Summary by cubic

insta project create now guides you to name the project when run in generic dirs (like ~/projects, /tmp, or home) instead of inventing a random name, preventing accidental provisioning under junk names.

• Bug Fixes

  • No auto-generated names in generic directories; prints a guidance message instead.
  • Still uses the dir basename when it’s a real project dir (e.g., ~/my-app → my-app).
  • Never prompts or hangs.

• Refactors

  • resolveProjectName now returns string | null; removed the random name generator.
  • Updated tests to cover the guide path and non-blocking behavior.

^{Written for commit 0b51c64. Summary will update on new commits.}

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[jwfing]

Summary

Clean, well-scoped follow-up to #46: resolveProjectName now returns string | null and the generic-dir case guides the user to name the project instead of inventing a junk name and provisioning real resources under it.

Requirements context

No matching spec/plan found — this repo has no docs/superpowers/ (nor docs/specs/ or a docs/ dir at all). Assessed against the PR description, the linked #46 intent, and the repo-local .claude/skills/developing-insta-cli conventions.

Findings

Critical

(none)

Suggestion

• Software engineering — the fixed behavior itself is not directly tested. src/commands/project.ts:52-58 The bug being fixed (#46: bare create in a generic dir provisioning real postgres/storage/compute) lives in projectCreate's early-return guide branch, but the tests only cover the pure resolveProjectName decision (returns null). Nothing asserts that projectCreate prints the guide and returns without calling the API / provisioning when resolved is null. That said, projectCreate isn't structured for DI (info and ApiClient.load are module-level, unlike the injected-runner pattern the repo skill calls out for ensure-skills.ts/setup.ts), so a regression test here is non-trivial — hence a suggestion, not a blocker. If you do add one, guarding "generic dir → no API call" would directly pin the regression.

Information

• Software engineering — good simplification. src/commands/project.ts:42-48 Dropping the generate DI param and making resolveProjectName synchronous is a net cleanup; the await at the (only) call site was removed correctly, generateProjectName/ADJ/NOUN are fully deleted, and a repo-wide grep confirms no dangling references. README already documents insta project create <name>, so no doc drift.
• Functionality — home-vs-dirname source mismatch (harmless). test/create-name.test.ts:25-27 The home-dir test reads process.env.HOME, while the implementation uses os.homedir(). These normally agree, but they're different sources; using homedir() in the test would exercise the exact code path.
• Functionality — pre-existing edge case, not introduced here. src/commands/project.ts:46 A real project directory whose basename equals the username (base === home) will guide rather than create. This behavior is unchanged from the prior implementation and out of scope for this PR — noting only for awareness.

Security

No security-relevant changes. Removed logic was Math.random-based name generation (not security-sensitive); the resolved name is sent as a JSON body field (POST /orgs/:id/projects), not interpolated into SQL/shell, and slugifyName restricts it to [a-z0-9-]. No secrets logged, no auth/authorization changes.

Performance

No performance-relevant changes. Removed two small arrays and a generator; the function is now synchronous with no I/O.

Verdict

approved (informational — a human still gives the explicit GitHub approval via the approve flow). Zero Critical findings; the one Suggestion is a nice-to-have regression test. Verified locally: vitest 77/77 pass, tsc --noEmit clean.

[jwfing]

LGTM - approved.

[jwfing]

Review — fix(project create): guide to name it instead of inventing a junk-named project

Summary: A tight, well-scoped follow-up to #46 that replaces auto-generation of a random project name in generic dirs with a non-blocking guidance message, so a bare insta project create in ~/projects//tmp/home no longer provisions real resources under a junk name.

Requirements context

No docs/superpowers/ or docs/specs/ directory exists in this repo — no matching spec/plan found, so I assessed against the PR description, the referenced design follow-up (#46), and the repo-local .claude/skills/developing-insta-cli/SKILL.md conventions. Verified locally at head 0b51c64: npm run typecheck clean and npm test → 77/77 green, matching the PR's claims.

Findings

Critical

(none)

Suggestion

• Software engineering — the core new behavior isn't directly tested (src/commands/project.ts:50-58). The tests cover resolveProjectName returning null well, but nothing asserts that projectCreate actually short-circuits — i.e. prints the guide and returns without calling ApiClient.load() / POST /orgs/:id/projects — when the name resolves to null. That "don't provision under a junk name" guarantee is the whole point of the PR, and it's currently only covered transitively via the pure function. I recognize projectCreate calls ApiClient.load() directly with no injection seam and the repo's convention is to avoid mocking globals (SKILL.md), so this is a nice-to-have rather than a blocker — but a small DI hook (or an injected client) enabling a "guide branch makes no API call" regression test would harden the intended behavior.

Information

• Project convention — CLI reference doc (SKILL.md:35-37). The skill requires command/flag changes to be mirrored in the insta skill's cli-reference.md (a superproject submodule, not present in this repo, so I couldn't verify). This is a behavior change to bare insta project create rather than a surface change, so it may not strictly apply — but if that reference documents the previous auto-generated-name behavior, it's now stale and worth updating in the same change set so skill-equipped agents don't rely on it.
• Functionality — explicit-arg-that-slugifies-to-empty (src/commands/project.ts:43,51-58). An explicit but all-symbol arg (e.g. insta project create "###") slugifies to '', which is falsy, so it now takes the guide branch instead of POSTing an empty name as the prior code would have. This is an improvement, not a regression — just noting the interaction; no action needed.
• Security / Performance: no security-relevant changes (no new user input reaching SQL/shell/HTTP unsanitized — name and cwd basename are both slugified; no secrets logged; no auth/authorization touched) and no performance-relevant changes (pure sync helper, no loops or I/O added; net −7 lines).

Also worth calling out positively: the generateProjectName generator and ADJ/NOUN tables were fully removed with no dangling references (verified repo-wide), the resolveProjectName signature change from async … Promise<string> to sync string | null has no other callers, and the test updates honestly track the new contract rather than papering over it.

Verdict

approved (informational — human approval via the approve flow). Zero Critical findings; the items above are non-blocking.

[jwfing]

LGTM - approved.