Ins-48 feat: improve create & link UX — auto-org, subdirectories, next steps

[tonychang04]

Summary

• Auto-select org when user has only one organization (both create and link)
• create with template prompts for directory name, creates subdirectory, downloads template
• create blank uses current directory, shows coding agent prompt suggestions
• link --template <name> downloads template into a new subdirectory (same UX as create)
• link (no template) just links in current directory, shows prompt suggestions
• Directory validation — rejects invalid names (/, ., ..), rejects existing dirs, cleans up on failure
• Next steps messages — template projects show cd + npm run dev + agent nudge; blank/raw link shows app idea prompts
• Bumps version to 0.1.44
• Adds unit tests for org selection and directory validation logic

Test plan

• insforge create --template react — prompts for dir, creates subdir, downloads, shows next steps
• insforge create (blank) — uses cwd, shows prompt suggestions
• insforge link --template nextjs — links project, prompts for dir, downloads template
• insforge link — links in cwd, shows prompt suggestions
• Single org account skips org selection in both commands
• Invalid directory names are rejected
• Existing directory name is rejected
• npm run test:unit passes (16 tests)

🤖 Generated with Claude Code

Note

Improve create and link UX with auto-org selection, subdirectory creation, and next steps

• Both create and link commands now auto-select an organization when the account has exactly one org; in JSON mode with multiple orgs, an error is thrown requiring --org-id.
• Template-based create flows now prompt for a directory name, create a subdirectory under cwd, and run subsequent steps inside it; blank projects use cwd.
• The link command gains a --template flag that downloads a starter template into a new subdirectory and installs dependencies; without the flag, it saves config in cwd and prints suggested prompts.
• After a successful template download, both commands print "next steps" guidance (e.g. cd <dir> && npm run dev).
• create cleans up the newly created directory if project linking fails, and only runs npm install / deploy prompts when a package.json is present.
• Behavioral Change: link no longer prompts interactively to choose templates, seeds .env.local, or offers a deploy prompt post-link.

^{Macroscope summarized e8d2d28.}

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Organization auto-selection when exactly one org is returned; interactive directory-name prompt added with basename extraction, sanitization, and validation; created directory is made under the original CWD and process.chdir'd into before template/setup; JSON output includes directory; non-JSON shows adjusted "Next steps" and created-directory cleanup on error.

Changes

Cohort / File(s)	Summary
Create command src/commands/create.ts	Adds interactive directory-name prompt (basename extraction, sanitize/validate), creates the directory under the original CWD and process.chdir into it before template/download/install/link/write steps; auto-selects org when API returns exactly one; JSON output includes directory; updates step numbering and non-JSON "Next steps"; wraps post-directory flow in try/catch to remove the created dir and restore CWD on error.
Create tests src/commands/create.test.ts	New Vitest tests plus helper functions mirroring directory basename extraction, sanitization, validation, and org-selection rules; covers invalid inputs, normalization behavior, and org selection across flag, none, single, and multiple-org scenarios in interactive vs JSON modes.
Package metadata package.json	Bumped package version from 0.1.43 to 0.1.44 (no other changes).

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• feat(create): enhance onboarding experience #36: Touches the same create command logic around project-name sanitization and .env.local handling.
• fix(create): prefill project name from directory #45: Related to interactive create flow and project-name prompting/defaulting behavior.
• Fix INS-20: Add CLI instrumentation for create and link counts #55: Modifies the create command (analytics/tracking added), likely overlaps with control-flow changes here.

Suggested reviewers

• jwfing
• CarmenDou
• Fermionic-Lyu

Poem

🐇📁 I nibble names and strip the fray,
I take the base and make it stay.
One org? I pick it — quick and bright,
I chdir in and set things right.
Hop on — your project springs to light.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately summarizes the main changes: auto-organization selection, subdirectory creation/management, and next-steps UX improvements are all present and prominent in the code modifications.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/create-command-ux-improvements

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/commands/create.ts (1)

172-193: ⚠️ Potential issue | 🟠 Major

Move the JSON-mode error behind the single-org fast path.

Line 177 throws before the new orgs.length === 1 branch runs, so create --json still fails for accounts that only have one organization. That makes the auto-select behavior interactive-only.

Suggested fix

         if (!orgId) {
           const orgs = await listOrganizations(apiUrl);
           if (orgs.length === 0) {
             throw new CLIError('No organizations found.');
           }
-          if (json) {
-            throw new CLIError('Specify --org-id in JSON mode.');
-          }
           if (orgs.length === 1) {
             orgId = orgs[0].id;
-            clack.log.info(`Using organization: ${orgs[0].name}`);
+            if (!json) clack.log.info(`Using organization: ${orgs[0].name}`);
           } else {
+            if (json) {
+              throw new CLIError('Multiple organizations found. Specify --org-id.');
+            }
             const selected = await clack.select({
               message: 'Select an organization:',
               options: orgs.map((o) => ({
                 value: o.id,
                 label: o.name,

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/commands/create.ts` around lines 172 - 193, The JSON-mode error check is
executed before the single-organization fast-path, preventing non-interactive
auto-selection; move the check that throws "Specify --org-id in JSON mode." to
after the orgs.length === 1 branch so that when orgs.length === 1 you auto-set
orgId (using the orgs[0].id and logging via clack.log.info) and only enforce the
JSON-mode error when there are multiple orgs and you would need to prompt via
clack.select (use clack.isCancel to handle cancels). Ensure you still call
listOrganizations(apiUrl) and preserve the existing throw for zero
organizations.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/commands/create.ts`:
- Around line 271-287: The current prompt validates the raw input but then
normalizes it into dirName using path.basename(...) which can collapse inputs
like './' back to '.' or an existing folder; update the flow around inputDir,
dirName and projectDir in create.ts so you validate the normalized dirName
(after path.basename and replacement) for empty/invalid values ('.', '..', ''),
and compute projectDir = path.resolve(process.cwd(), dirName) before creating;
then check if projectDir already exists (use fs.stat or fs.access) and if so
abort with an error rather than calling fs.mkdir with { recursive: true }, and
only then call fs.mkdir(projectDir) and process.chdir(projectDir). Ensure
references to inputDir, dirName, projectDir, fs.mkdir and process.chdir are
updated accordingly.

---

Outside diff comments:
In `@src/commands/create.ts`:
- Around line 172-193: The JSON-mode error check is executed before the
single-organization fast-path, preventing non-interactive auto-selection; move
the check that throws "Specify --org-id in JSON mode." to after the orgs.length
=== 1 branch so that when orgs.length === 1 you auto-set orgId (using the
orgs[0].id and logging via clack.log.info) and only enforce the JSON-mode error
when there are multiple orgs and you would need to prompt via clack.select (use
clack.isCancel to handle cancels). Ensure you still call
listOrganizations(apiUrl) and preserve the existing throw for zero
organizations.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d1f1688b-3d9d-4dfd-8164-7dd56cdd2cb0

📥 Commits

Reviewing files that changed from the base of the PR and between a6a1abd and 9f27201.

📒 Files selected for processing (1)

• src/commands/create.ts

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/commands/create.ts (1)

323-329: ⚠️ Potential issue | 🟠 Major

Track template bootstrap success separately from hasTemplate.

hasTemplate only reflects the requested template, not whether the scaffold actually landed on disk. Because downloadTemplate / downloadGitHubTemplate warn and return normally on failure, Lines 366-469 can still run npm install, offer deploy, and print npm run dev instructions for an empty project directory. Have the download helpers return a success flag and gate the later template-only steps on that.
Based on learnings, downloadTemplate and downloadGitHubTemplate catch all errors internally and never rethrow them.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/commands/create.ts` around lines 323 - 329, The current code uses
hasTemplate to decide later template-only steps but downloadTemplate and
downloadGitHubTemplate swallow errors and return normally; change both
downloadTemplate and downloadGitHubTemplate to return a boolean success flag
(true when files were actually written) and update the caller in create.ts to
await those functions into a new variable (e.g., const templateDownloaded =
await downloadGitHubTemplate(...) or await downloadTemplate(...)) and then gate
subsequent template-only work (npm install, deploy offer, printing "npm run dev"
instructions) on templateDownloaded rather than hasTemplate so you don't run
install/print instructions for an empty project; ensure the new boolean is
passed/used where projectConfig/projectName/json/apiUrl are currently used.

🧹 Nitpick comments (1)

src/commands/create.test.ts (1)

10-25: Test the real helpers instead of re-implementing them here.

These helpers duplicate the branching and normalization from src/commands/create.ts, so the suite can stay green even if the command behavior drifts. I'd extract the directory/org-selection logic into shared pure functions and import those here, or drive the actual command with mocks.

Also applies to: 81-101

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/commands/create.test.ts` around lines 10 - 25, The test currently
re-implements the helpers sanitizeDirName, validateDirInput, and
isValidNormalizedDir which duplicates logic from src/commands/create.ts;
instead, import and use the real helper functions (or refactor create.ts to
export shared pure functions for directory/org-selection) in the test so
behavior stays in sync, or invoke the actual create command flow with
appropriate mocks for filesystem/prompts to exercise the real helpers; update
the test to remove the local copies (sanitizeDirName, validateDirInput,
isValidNormalizedDir) and reference the exported functions from create.ts (or
the new shared module) when asserting behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/commands/create.ts`:
- Around line 290-297: Wrap the setup steps after fs.mkdir(projectDir) and
process.chdir(projectDir) in a try/catch and track that the directory was
created (e.g., a createdDir flag); if any error occurs before the local project
linking step completes, remove the partially created projectDir (using
fs.rm/fs.rmdir) and rethrow the error. Update the block around projectDir,
dirExists, fs.mkdir and process.chdir so cleanup runs only when the directory
was newly created and linking has not succeeded.

---

Outside diff comments:
In `@src/commands/create.ts`:
- Around line 323-329: The current code uses hasTemplate to decide later
template-only steps but downloadTemplate and downloadGitHubTemplate swallow
errors and return normally; change both downloadTemplate and
downloadGitHubTemplate to return a boolean success flag (true when files were
actually written) and update the caller in create.ts to await those functions
into a new variable (e.g., const templateDownloaded = await
downloadGitHubTemplate(...) or await downloadTemplate(...)) and then gate
subsequent template-only work (npm install, deploy offer, printing "npm run dev"
instructions) on templateDownloaded rather than hasTemplate so you don't run
install/print instructions for an empty project; ensure the new boolean is
passed/used where projectConfig/projectName/json/apiUrl are currently used.

---

Nitpick comments:
In `@src/commands/create.test.ts`:
- Around line 10-25: The test currently re-implements the helpers
sanitizeDirName, validateDirInput, and isValidNormalizedDir which duplicates
logic from src/commands/create.ts; instead, import and use the real helper
functions (or refactor create.ts to export shared pure functions for
directory/org-selection) in the test so behavior stays in sync, or invoke the
actual create command flow with appropriate mocks for filesystem/prompts to
exercise the real helpers; update the test to remove the local copies
(sanitizeDirName, validateDirInput, isValidNormalizedDir) and reference the
exported functions from create.ts (or the new shared module) when asserting
behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 8acce66e-ab46-4e89-a7a4-8dd5528f3a8d

📥 Commits

Reviewing files that changed from the base of the PR and between 9f27201 and 4a6c588.

📒 Files selected for processing (2)

• src/commands/create.test.ts
• src/commands/create.ts