fix(app): resolve remaining coderabbit findings

Author: skulidropek

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

@@ -259,12 +259,15 @@ export const completeCreateDisplaySettingsFlow = (
 
 const resolveNextCreateFlowStep = (
   currentStep: CreateStep,
-  currentStepIndex: number,
-  nextSteps: ReadonlyArray<CreateStep>
+  currentStepIndex: number
 ): number =>
   currentStep === "repoUrl"
     ? firstCreateSettingsStepIndex
-    : clampCreateSettingsStep(currentStepIndex + 1, nextSteps.length - 1)
+    : currentStepIndex + 1
+
+const shouldCompleteCreateFlow = (
+  nextSteps: ReadonlyArray<CreateStep>
+): boolean => nextSteps.length <= firstCreateSettingsStepIndex
 
 /**
  * Advances create mode by applying the active prompt buffer.
@@ -278,10 +281,10 @@ const resolveNextCreateFlowStep = (
 // QUOTE(ТЗ): "after applying a non-repoUrl step it advances to currentStepIndex + 1"
 // REF: issue-339
 // SOURCE: n/a
-// FORMAT THEOREM: step != repoUrl -> nextStep = clamp(stepIndex + 1)
+// FORMAT THEOREM: remaining = empty -> Complete, otherwise Continue(next valid setting)
 // PURITY: CORE
 // EFFECT: n/a
-// INVARIANT: next step is always within the current settings range when continuing
+// INVARIANT: completion requires no unsatisfied settings after repoUrl
 // COMPLEXITY: O(k + s) where s = number of remaining create steps
 export const advanceCreateFlow = (
   contextOrCwd: string | CreateFlowContext,
@@ -303,10 +306,13 @@ export const advanceCreateFlow = (
       }
 
       const nextSteps = resolveCreateFlowSteps(nextValues)
-      const nextStep = resolveNextCreateFlowStep(step, view.step, nextSteps)
-      return nextSteps.length > firstCreateSettingsStepIndex && nextStep < nextSteps.length
-        ? continueCreateFlow(nextStep, nextValues)
-        : completeCreateFlow(context, nextValues)
+      const nextStep = resolveNextCreateFlowStep(step, view.step)
+      if (shouldCompleteCreateFlow(nextSteps)) {
+        return completeCreateFlow(context, nextValues)
+      }
+      return nextStep < nextSteps.length
+        ? continueCreateFlow(clampCreateSettingsStep(nextStep, nextSteps.length - 1), nextValues)
+        : continueCreateFlow(nextSteps.length - 1, nextValues)
     }
   )
 }

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

@@ -68,28 +68,27 @@ const consumeCreateTokenChar = (state: CreateTokenizeState, char: string): Creat
 
 const consumeCreateTokenInput = (
   input: string,
-  index: number,
   state: CreateTokenizeState
 ): CreateTokenizeState => {
-  if (index >= input.length) {
-    return state
-  }
-
-  const codePoint = input.codePointAt(index)
-  if (codePoint === undefined) {
-    return state
+  let index = 0
+  let next = state
+  while (index < input.length) {
+    const codePoint = input.codePointAt(index)
+    if (codePoint === undefined) {
+      return next
+    }
+    const char = String.fromCodePoint(codePoint)
+    next = consumeCreateTokenChar(next, char)
+    index += char.length
   }
-
-  const char = String.fromCodePoint(codePoint)
-  return consumeCreateTokenInput(input, index + char.length, consumeCreateTokenChar(state, char))
+  return next
 }
 
 const tokenizeCreateCommandLine = (
   input: string
 ): Either.Either<ReadonlyArray<string>, ParseError> => {
   const state = consumeCreateTokenInput(
     input.trim(),
-    0,
     { current: "", escaping: false, quote: null, tokens: [] }
   )
 

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

@@ -50,9 +50,15 @@ export const firstCreateSettingsStepIndex = 1
 /**
  * Narrows a create-flow view to interactive create mode.
  *
+ * @param view - Create-flow view to refine.
+ * @returns True when `view` is a create-mode view.
  * @pure true
- * @invariant true iff mode = create
+ * @effect n/a
+ * @invariant result <=> view.mode = "create"
+ * @precondition `view` is a non-null CreateFlowView value.
+ * @postcondition True narrows `view` to CreateModeFlowView; false leaves it as the remaining union member.
  * @complexity O(1)
+ * @throws Never
  */
 // CHANGE: expose a pure predicate for create-mode flow views
 // WHY: callers need type-safe mode refinement before create-only transitions
@@ -69,9 +75,15 @@ export const isCreateModeFlowView = (view: CreateFlowView): view is CreateModeFl
 /**
  * Narrows a create-flow view to browser display-settings mode.
  *
+ * @param view - Create-flow view to refine.
+ * @returns True when `view` is a display-mode view.
  * @pure true
- * @invariant true iff mode = display
+ * @effect n/a
+ * @invariant result <=> view.mode = "display"
+ * @precondition `view` is a non-null CreateFlowView value.
+ * @postcondition True narrows `view` to DisplayModeFlowView; false leaves it as the remaining union member.
  * @complexity O(1)
+ * @throws Never
  */
 // CHANGE: expose a pure predicate for display-mode flow views
 // WHY: callers need type-safe mode refinement before display-only transitions
@@ -88,9 +100,15 @@ export const isDisplayModeFlowView = (view: CreateFlowView): view is DisplayMode
 /**
  * Detects the repo-url prompt in create mode.
  *
+ * @param view - Create-flow view to inspect.
+ * @returns True when `view` is create mode at step zero.
  * @pure true
- * @invariant true implies create mode and step = 0
+ * @effect n/a
+ * @invariant result <=> view.mode = "create" and view.step = 0
+ * @precondition `view` is a non-null CreateFlowView value.
+ * @postcondition True implies callers may treat the active row as the repo-url prompt.
  * @complexity O(1)
+ * @throws Never
  */
 // CHANGE: expose the repo-step predicate for shared create-flow input handling
 // WHY: navigation and input logic treat repo URL entry differently from settings rows

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

@@ -12,9 +12,16 @@ import { resolveCreateDisplaySteps, resolveCreateFlowSteps } from "./menu-create
 /**
  * Clamps a create settings index into the editable settings range.
  *
+ * @param step - Candidate step index.
+ * @param lastStep - Inclusive upper bound of the current settings range.
+ * @returns `step` bounded to `[firstCreateSettingsStepIndex, lastStep]`.
  * @pure true
+ * @effect n/a
  * @invariant result is between first settings step and lastStep when range is valid
+ * @precondition `lastStep >= firstCreateSettingsStepIndex` for a non-empty settings range.
+ * @postcondition result >= firstCreateSettingsStepIndex and result <= lastStep when the precondition holds.
  * @complexity O(1)
+ * @throws Never
  */
 // CHANGE: centralize create settings index clamping
 // WHY: advancement and navigation must share the same range invariant
@@ -31,6 +38,31 @@ export const clampCreateSettingsStep = (
   lastStep: number
 ): number => Math.min(Math.max(step, firstCreateSettingsStepIndex), lastStep)
 
+/**
+ * Computes a wrapped adjacent settings index.
+ *
+ * @param step - Current valid settings step index.
+ * @param lastStep - Inclusive upper bound for settings.
+ * @param direction - Vertical navigation direction.
+ * @returns The previous or next settings index with wraparound.
+ * @pure true
+ * @effect n/a
+ * @invariant result is inside `[firstCreateSettingsStepIndex, lastStep]`.
+ * @precondition `step` is inside `[firstCreateSettingsStepIndex, lastStep]`.
+ * @postcondition `up` decrements or wraps to `lastStep`; `down` increments or wraps to first settings step.
+ * @complexity O(1)
+ * @throws Never
+ */
+// CHANGE: isolate wrapped create-settings index arithmetic
+// WHY: both create and display modes share the same vertical navigation law
+// QUOTE(ТЗ): "Add concise but compliant TSDoc + functional comments"
+// REF: issue-339
+// SOURCE: n/a
+// FORMAT THEOREM: forall s in [first,last], d: next(s,d) in [first,last]
+// PURITY: CORE
+// EFFECT: n/a
+// INVARIANT: navigation never returns the repo URL step
+// COMPLEXITY: O(1)
 const nextCreateSettingsStep = (
   step: number,
   lastStep: number,
@@ -42,6 +74,31 @@ const nextCreateSettingsStep = (
     Match.exhaustive
   )
 
+/**
+ * Moves any settings-capable create-flow view within a bounded range.
+ *
+ * @param view - Create or display view to move.
+ * @param lastStep - Inclusive upper bound for the active settings list.
+ * @param direction - Vertical navigation direction.
+ * @returns A moved view, the original view if unchanged, or null when no settings range is active.
+ * @pure true
+ * @effect n/a
+ * @invariant Returned views preserve mode and committed values.
+ * @precondition `view` is non-null and `lastStep` belongs to the step list used by the caller.
+ * @postcondition Non-null moved views have empty `buffer` and null `inputError`.
+ * @complexity O(1)
+ * @throws Never
+ */
+// CHANGE: share immutable settings movement across create and display modes
+// WHY: the two views differ only in the step list that defines `lastStep`
+// QUOTE(ТЗ): "Add concise but compliant TSDoc + functional comments"
+// REF: issue-339
+// SOURCE: n/a
+// FORMAT THEOREM: valid(v,last) -> move(v).values = v.values
+// PURITY: CORE
+// EFFECT: n/a
+// INVARIANT: repo URL or empty settings ranges return null
+// COMPLEXITY: O(1)
 const moveCreateSettingsWithin = <
   A extends CreateModeFlowView | DisplayModeFlowView
 >(
@@ -65,13 +122,59 @@ const moveCreateSettingsWithin = <
     }
 }
 
+/**
+ * Resolves a horizontal boolean choice to the create-flow buffer token.
+ *
+ * @param direction - Horizontal choice direction.
+ * @returns `"n"` for left and `"y"` for right.
+ * @pure true
+ * @effect n/a
+ * @invariant result is always a valid yes/no buffer token.
+ * @precondition `direction` is a valid CreateSettingsChoiceDirection.
+ * @postcondition Left maps to false-preview token; right maps to true-preview token.
+ * @complexity O(1)
+ * @throws Never
+ */
+// CHANGE: encode boolean left/right choices as create input buffer values
+// WHY: preview buffers reuse the same parser path as typed settings input
+// QUOTE(ТЗ): "Add concise but compliant TSDoc + functional comments"
+// REF: issue-339
+// SOURCE: n/a
+// FORMAT THEOREM: direction in {left,right} -> token in {n,y}
+// PURITY: CORE
+// EFFECT: n/a
+// INVARIANT: output token set is finite and parser-compatible
+// COMPLEXITY: O(1)
 const booleanChoiceBuffer = (direction: CreateSettingsChoiceDirection): string =>
   Match.value(direction).pipe(
     Match.when("left", () => "n"),
     Match.when("right", () => "y"),
     Match.exhaustive
   )
 
+/**
+ * Resolves a horizontal GPU choice to the create-flow buffer token.
+ *
+ * @param direction - Horizontal choice direction.
+ * @returns `"none"` for left and `"all"` for right.
+ * @pure true
+ * @effect n/a
+ * @invariant result is always a valid GPU buffer token.
+ * @precondition `direction` is a valid CreateSettingsChoiceDirection.
+ * @postcondition Left maps to `none`; right maps to `all`.
+ * @complexity O(1)
+ * @throws Never
+ */
+// CHANGE: encode GPU left/right choices as create input buffer values
+// WHY: display controls should use the same parser-compatible token space as manual input
+// QUOTE(ТЗ): "Add concise but compliant TSDoc + functional comments"
+// REF: issue-339
+// SOURCE: n/a
+// FORMAT THEOREM: direction in {left,right} -> token in {none,all}
+// PURITY: CORE
+// EFFECT: n/a
+// INVARIANT: output token set is finite and parser-compatible
+// COMPLEXITY: O(1)
 const gpuChoiceBuffer = (direction: CreateSettingsChoiceDirection): string =>
   Match.value(direction).pipe(
     Match.when("left", () => "none"),
@@ -82,9 +185,16 @@ const gpuChoiceBuffer = (direction: CreateSettingsChoiceDirection): string =>
 /**
  * Resolves horizontal browser setting controls into preview buffer tokens.
  *
+ * @param view - Browser display-settings view that provides the active row.
+ * @param direction - Horizontal choice direction.
+ * @returns A parser-compatible buffer token for discrete rows, otherwise null.
  * @pure true
+ * @effect n/a
  * @invariant free-text rows return null
+ * @precondition `view.step` may be inside or outside the display step range.
+ * @postcondition Returned non-null tokens do not mutate `view.values`.
  * @complexity O(1)
+ * @throws Never
  */
 // CHANGE: map display-mode left/right choices to create setting buffer values
 // WHY: browser controls should preview discrete settings without committing values
@@ -122,9 +232,16 @@ export const resolveCreateSettingsChoiceBuffer = (
 /**
  * Moves the create-mode settings selection with wraparound.
  *
+ * @param view - Create-mode view to move.
+ * @param direction - Vertical navigation direction.
+ * @returns Moved create-mode view or null when the repo URL step is active.
  * @pure true
+ * @effect n/a
  * @invariant returned view has an empty buffer
+ * @precondition `view` is a non-null CreateModeFlowView.
+ * @postcondition Non-null result preserves mode and values while clearing transient input state.
  * @complexity O(s) where s = number of remaining create steps
+ * @throws Never
  */
 // CHANGE: expose pure create-mode settings navigation
 // WHY: arrow-key handling must not mutate the current view
@@ -145,9 +262,16 @@ export const moveCreateSettingsStep = (
 /**
  * Moves the browser display-settings selection with wraparound.
  *
+ * @param view - Display-mode view to move.
+ * @param direction - Vertical navigation direction.
+ * @returns Moved display-mode view or null when no settings range is active.
  * @pure true
+ * @effect n/a
  * @invariant returned view has an empty buffer
+ * @precondition `view` is a non-null DisplayModeFlowView.
+ * @postcondition Non-null result preserves mode and values while clearing transient input state.
  * @complexity O(s) where s = number of display steps
+ * @throws Never
  */
 // CHANGE: expose pure display-mode settings navigation
 // WHY: browser settings keep all rows navigable regardless of committed values