fix(app): clarify create settings flow

Author: rikohomeless

packages/app/src/docker-git/menu-create-shared.ts

@@ -43,6 +43,32 @@ type AdvanceCreateFlowOptions = {
   readonly quickCreate?: boolean
 }
 
+/**
+ * Direction over the finite ordered set of unresolved Create settings rows.
+ *
+ * @pure true
+ * @effect none
+ * @invariant value ∈ {"up", "down"}
+ * @precondition n/a
+ * @postcondition navigation direction is total for settings rows
+ * @complexity O(1)
+ */
+export type CreateSettingsNavigationDirection = "up" | "down"
+
+/**
+ * User-facing key guide shown only after Create leaves the repo URL step.
+ *
+ * @pure true
+ * @effect none
+ * @invariant hint contains the complete settings-mode key contract
+ * @precondition CreateFlowView.step > 0
+ * @postcondition no repo-step quick-create guidance is rendered from this value
+ * @complexity O(1)
+ */
+export const createSettingsHint = "↑ - up, ↓ - down, Enter - apply"
+
+const firstCreateSettingsStepIndex = 1
+
 const trimLeftSlash = (value: string): string => {
   let start = 0
   while (start < value.length && value[start] === "/") {
@@ -462,6 +488,65 @@ const continueCreateFlow = (
   }
 })
 
+const clampCreateSettingsStep = (
+  step: number,
+  lastStep: number
+): number => Math.min(Math.max(step, firstCreateSettingsStepIndex), lastStep)
+
+const nextCreateSettingsStep = (
+  step: number,
+  lastStep: number,
+  direction: CreateSettingsNavigationDirection
+): number =>
+  Match.value(direction).pipe(
+    Match.when("up", () => step === firstCreateSettingsStepIndex ? lastStep : step - 1),
+    Match.when("down", () => step === lastStep ? firstCreateSettingsStepIndex : step + 1),
+    Match.exhaustive
+  )
+
+/**
+ * Moves the selected Create settings row without applying the current buffer.
+ *
+ * @pure true
+ * @effect none
+ * @invariant view.step = 0 -> result = null
+ * @invariant result != null -> 1 <= result.step < |resolveCreateFlowSteps(result.values)|
+ * @invariant result != null && result.step != view.step -> result.buffer = ""
+ * @precondition view is a CreateFlowView snapshot
+ * @postcondition result values are identical to the input values
+ * @complexity O(n) where n is the number of unresolved Create steps
+ */
+export const moveCreateSettingsStep = (
+  view: CreateFlowView,
+  direction: CreateSettingsNavigationDirection
+): CreateFlowView | null => {
+  const steps = resolveCreateFlowSteps(view.values)
+  const lastStep = steps.length - 1
+  if (view.step < firstCreateSettingsStepIndex || lastStep < firstCreateSettingsStepIndex) {
+    return null
+  }
+
+  const currentStep = clampCreateSettingsStep(view.step, lastStep)
+  const step = nextCreateSettingsStep(currentStep, lastStep, direction)
+  if (step === view.step) {
+    return view
+  }
+  return {
+    ...view,
+    step,
+    buffer: ""
+  }
+}
+
+const resolveNextCreateFlowStep = (
+  currentStep: CreateStep,
+  currentStepIndex: number,
+  nextSteps: ReadonlyArray<CreateStep>
+): number =>
+  currentStep === "repoUrl"
+    ? firstCreateSettingsStepIndex
+    : clampCreateSettingsStep(currentStepIndex, nextSteps.length - 1)
+
 export const advanceCreateFlow = (
   contextOrCwd: string | CreateFlowContext,
   view: CreateFlowView,
@@ -499,8 +584,8 @@ export const advanceCreateFlow = (
   }
 
   const nextSteps = resolveCreateFlowSteps(nextValues)
-  const nextStep = step === "repoUrl" ? 1 : view.step
-  if (nextStep < nextSteps.length) {
+  const nextStep = resolveNextCreateFlowStep(step, view.step, nextSteps)
+  if (nextSteps.length > firstCreateSettingsStepIndex && nextStep < nextSteps.length) {
     return continueCreateFlow(nextStep, nextValues)
   }
 

packages/app/src/docker-git/menu-create.ts

@@ -11,6 +11,7 @@ import {
   advanceCreateFlow,
   createInitialFlowView,
   handleAdvanceCreateFlowResult,
+  moveCreateSettingsStep,
   resolveCreateInputs
 } from "./menu-create-shared.js"
 import { resetToMenu } from "./menu-shared.js"
@@ -178,6 +179,8 @@ export const handleCreateInput = (
   input: string,
   key: {
     readonly escape?: boolean
+    readonly upArrow?: boolean
+    readonly downArrow?: boolean
     readonly return?: boolean
     readonly shift?: boolean
     readonly backspace?: boolean
@@ -190,6 +193,14 @@ export const handleCreateInput = (
     resetToMenu(context)
     return
   }
+  if (key.upArrow || key.downArrow) {
+    const nextView = moveCreateSettingsStep(view, key.upArrow ? "up" : "down")
+    if (nextView !== null) {
+      context.setView({ _tag: "Create", ...nextView })
+      context.setMessage(null)
+    }
+    return
+  }
   if (key.return) {
     handleCreateReturn({ ...context, view }, key.shift === true)
     return

packages/app/src/docker-git/menu-render.ts

@@ -1,7 +1,7 @@
 import React from "react"
 
 import { Box, Text } from "../ui/primitives.js"
-import { renderCreateStepLabel } from "./menu-create-shared.js"
+import { createSettingsHint, renderCreateStepLabel } from "./menu-create-shared.js"
 import { renderLayout } from "./menu-render-layout.js"
 import {
   buildSelectLabels,
@@ -120,9 +120,7 @@ export const renderMenu = (input: MenuRenderInput): React.ReactElement => {
 export const renderCreate = (input: CreateRenderInput): React.ReactElement => {
   const { buffer, defaults, label, message, stepIndex, steps } = input
   const el = React.createElement
-  const hint = stepIndex === 0
-    ? "Enter = next, Shift+Enter = quick create, Esc = cancel."
-    : "Enter = next, Esc = cancel."
+  const hint = stepIndex > 0 ? createSettingsHint : null
   const stepViews = steps.map((step, index) =>
     el(
       Text,
@@ -132,16 +130,18 @@ export const renderCreate = (input: CreateRenderInput): React.ReactElement => {
   )
   return renderLayout(
     "docker-git / Create",
-    [
+    compactElements([
       el(Box, { flexDirection: "column", marginTop: 1 }, ...stepViews),
       el(
         Box,
         { marginTop: 1 },
         el(Text, null, `${label}: `),
         el(Text, { fg: "green" }, buffer)
       ),
-      el(Box, { marginTop: 1 }, el(Text, { fg: "gray" }, hint))
-    ],
+      hint === null
+        ? null
+        : el(Box, { marginTop: 1 }, el(Text, { fg: "gray" }, hint))
+    ]),
     message
   )
 }

packages/app/src/web/actions-projects.ts

@@ -448,7 +448,7 @@ export const runProjectMenuAction = (
   context: BrowserActionContext
 ) => {
   if (currentMenu === "Create") {
-    context.setMessage("Create mode is active. Paste URL or URL + flags, Enter = next, Shift+Enter = quick create.")
+    context.setMessage("Create mode is active. Paste URL or URL + flags, then choose Quick Create or Settings.")
     return
   }
   if (currentMenu === "Select") {

packages/app/src/web/app-ready-create.ts

@@ -6,7 +6,8 @@ import {
   advanceCreateFlow,
   type CreateFlowView,
   createInitialFlowView,
-  handleAdvanceCreateFlowResult
+  handleAdvanceCreateFlowResult,
+  moveCreateSettingsStep
 } from "../docker-git/menu-create-shared.js"
 import { submitCreateInputs } from "./actions-projects.js"
 import { requireGithubAuthConfigured } from "./actions-shared.js"
@@ -109,6 +110,16 @@ export const handleCreateKey = (
     cancelCreate(context, setCreateView)
     return true
   }
+  if (event.key === "ArrowUp" || event.key === "ArrowDown") {
+    const nextView = moveCreateSettingsStep(createView, event.key === "ArrowUp" ? "up" : "down")
+    if (nextView === null) {
+      return false
+    }
+    event.preventDefault()
+    setCreateView(nextView)
+    context.setMessage(null)
+    return true
+  }
   if (event.key === "Enter") {
     event.preventDefault()
     submitCreateView({

packages/app/src/web/app-ready-url.ts

@@ -88,8 +88,7 @@ const activeTerminalReadyPath = (session: ActiveTerminalSession | null): string
   return projectSshRoutePath(session.browserProjectKey, session.session.id)
 }
 
-const selectReadyPath = (token: string | null): string =>
-  token === null ? "/menu/select" : `/select/${encodePathTail(token)}`
+const selectReadyPath = (token: string | null): string => token === null ? "/menu/select" : projectSshRoutePath(token)
 
 const menuActionReadyPath = (
   activeScreen: BrowserScreen,

packages/app/src/web/panel-create-select.tsx

@@ -3,6 +3,7 @@ import type { JSX } from "react"
 import {
   type CreateFlowContext,
   type CreateFlowView,
+  createSettingsHint,
   renderCreateStepLabel,
   resolveCreateFlowSteps,
   resolveCreateInputs
@@ -26,11 +27,6 @@ const createPrompt = (
   }
 }
 
-const createHint = (isRepoStep: boolean): string =>
-  isRepoStep
-    ? "Enter = next, Shift+Enter = quick create, Esc = cancel."
-    : "Enter = next, Esc = cancel."
-
 const CreatePromptInput = (
   {
     createView,
@@ -111,11 +107,17 @@ export const CreatePanel = (
         ? (
           <Box gap={1} marginTop={1}>
             <Button
-              label="Quick create"
+              label="Quick Create"
               onPress={() => {
                 onSubmit(true)
               }}
             />
+            <Button
+              label="Settings"
+              onPress={() => {
+                onSubmit(false)
+              }}
+            />
           </Box>
         )
         : null}
@@ -161,8 +163,8 @@ const CreateHintBlock = (
   <HelpLines
     lines={[
       ...(isRepoStep ? ["Repo URL or URL + CLI flags."] : []),
-      createHint(isRepoStep),
-      ...(compact ? ["↑/↓ = menu, ←/→ = project"] : []),
+      ...(isRepoStep ? [] : [createSettingsHint]),
+      ...(compact && isRepoStep ? ["↑/↓ = menu, ←/→ = project"] : []),
       `Current cwd: ${controllerCwd}`
     ]}
   />

packages/app/tests/docker-git/app-ready-create.test.ts

@@ -11,7 +11,7 @@ import {
 import type { CreateInputs } from "../../src/docker-git/menu-types.js"
 import type { submitCreateInputs } from "../../src/web/actions-projects.js"
 import type { GithubAuthStatus } from "../../src/web/api.js"
-import { submitCreateView } from "../../src/web/app-ready-create.js"
+import { handleCreateKey, submitCreateView } from "../../src/web/app-ready-create.js"
 import { makeBrowserActionContext } from "./browser-action-context-fixture.js"
 
 const submitCreateInputsMock = vi.hoisted(() => vi.fn<typeof submitCreateInputs>())
@@ -117,6 +117,55 @@ const expectCreateViewReset = (setCreateViewSpy: ReturnType<typeof submitCreateB
 const expectedOutDirForRepoUrl = (repoUrl: string): string =>
   `/home/dev/.docker-git/${deriveRepoPathParts(resolveRepoInput(repoUrl).repoUrl).pathParts.join("/")}`
 
+const createKeyEvent = (
+  key: string,
+  shiftKey = false
+): Parameters<typeof handleCreateKey>[0] => {
+  const event = {
+    key,
+    shiftKey,
+    preventDefault: vi.fn()
+  }
+  return event
+}
+
+const createSettingsFlowView = (): CreateFlowView => ({
+  step: 1,
+  buffer: "30%",
+  values: {
+    outDir: "/home/dev/.docker-git/org/repo",
+    repoRef: "feature-x",
+    repoUrl: "https://github.com/org/repo/tree/feature-x"
+  }
+})
+
+const expectCreateArrowHandling = (
+  key: "ArrowDown" | "ArrowUp",
+  expectedStep: (view: CreateFlowView) => number
+) => {
+  const { context } = makeBrowserActionContext({ githubStatus: validGithubStatus })
+  const { setCreateView, spy: setCreateViewSpy } = createSetCreateViewSpy()
+  const event = createKeyEvent(key)
+  const createView = createSettingsFlowView()
+
+  const handled = handleCreateKey(event, {
+    context,
+    controllerCwd: "/workspace",
+    createView,
+    projectsRoot: "/home/dev/.docker-git",
+    setCreateView
+  })
+
+  expect(handled).toBe(true)
+  expect(event.preventDefault).toHaveBeenCalledTimes(1)
+  expect(requireCreateViewValue(setCreateViewSpy.mock.calls[0]?.[0])).toEqual({
+    ...createView,
+    step: expectedStep(createView),
+    buffer: ""
+  })
+  expect(context.setMessage).toHaveBeenCalledWith(null)
+}
+
 describe("app-ready-create", () => {
   beforeEach(() => {
     submitCreateInputsMock.mockReset()
@@ -147,6 +196,50 @@ describe("app-ready-create", () => {
     expect(context.setMessage).toHaveBeenCalledWith(null)
   })
 
+  it("enters the settings wizard when explicitly requested from the repo URL step", () => {
+    const { setCreateViewSpy } = submitCreateBuffer(
+      "https://github.com/org/repo/tree/feature-x",
+      { quickCreate: false }
+    )
+
+    expect(submitCreateInputsMock).not.toHaveBeenCalled()
+    expect(requireCreateViewValue(setCreateViewSpy.mock.calls[0]?.[0])).toMatchObject({
+      step: 1,
+      values: {
+        outDir: "/home/dev/.docker-git/org/repo",
+        repoRef: "feature-x",
+        repoUrl: "https://github.com/org/repo/tree/feature-x"
+      }
+    })
+  })
+
+  it("moves between settings with arrows and clears the uncommitted buffer", () => {
+    expectCreateArrowHandling("ArrowDown", (view) => view.step + 1)
+  })
+
+  it("wraps settings selection upward with ArrowUp and clears the uncommitted buffer", () => {
+    expectCreateArrowHandling("ArrowUp", (view) => resolveCreateFlowSteps(view.values).length - 1)
+  })
+
+  it("ignores settings arrows before the Settings flow starts", () => {
+    const { context } = makeBrowserActionContext({ githubStatus: validGithubStatus })
+    const { setCreateView, spy: setCreateViewSpy } = createSetCreateViewSpy()
+    const event = createKeyEvent("ArrowDown")
+
+    const handled = handleCreateKey(event, {
+      context,
+      controllerCwd: "/workspace",
+      createView: createInitialFlowView("https://github.com/org/repo"),
+      projectsRoot: "/home/dev/.docker-git",
+      setCreateView
+    })
+
+    expect(handled).toBe(false)
+    expect(event.preventDefault).not.toHaveBeenCalled()
+    expect(setCreateViewSpy).not.toHaveBeenCalled()
+    expect(context.setMessage).not.toHaveBeenCalled()
+  })
+
   it("shows a parse error instead of submitting on invalid inline flags", () => {
     const { context, setCreateViewSpy } = submitCreateBuffer("https://github.com/org/repo --bogus")