# Seed Blueprint Source: seed/seed.yml Genomes: cli-interface [builtin], cli-nodejs [builtin], tui-client [builtin], cli-tui [builtin] ## Project Summary - `metadata` [seed/seed.yml] name: cat-tui summary: A full-screen TUI that displays an ASCII cat. description: Defines generic TUI application guardrails for full-screen rendering, screens, keyboard navigation, focus, resize handling, and terminal restoration. ## Global Policies - `security.no-secret-output` [builtin:cli-nodejs] description: Must not print environment variables, tokens, or credentials unless explicitly required by the Seed. ## Interfaces - `interfaces.cli` [builtin:cli-nodejs] purpose: User invokes the project from a terminal as a Node.js CLI. examples: - node ./src/cli.js --help - --help id: cli - `interfaces.tui` [builtin:tui-client] purpose: User interacts with the project through a terminal user interface. examples: - run - navigate with keyboard controls id: tui ## Functional Behavior - `behavior.terminal-ui` [builtin:tui-client] description: The client presents an interactive terminal user interface. - `behavior.keyboard-navigation` [builtin:tui-client] description: The TUI supports keyboard-driven navigation and actions. - `behavior.tui-rendering` [builtin:cli-tui] full-screen-redraw: The interface renders and updates a coherent terminal viewport in place rather than emitting an ever-growing stream of output. stable-frame: Each completed render reflects one coherent application state without stale regions, interleaved output, or visibly partial frames. resize-redraw: Terminal resize events recompute layout and repaint the current screen without corrupting content or losing the active context. bounded-layout: Content is clipped, wrapped, scrolled, or otherwise adapted to the available viewport instead of drawing outside terminal bounds. id: tui-rendering - `behavior.tui-rendering.full-screen-redraw` [builtin:cli-tui] description: The interface renders and updates a coherent terminal viewport in place rather than emitting an ever-growing stream of output. - `behavior.tui-rendering.stable-frame` [builtin:cli-tui] description: Each completed render reflects one coherent application state without stale regions, interleaved output, or visibly partial frames. - `behavior.tui-rendering.resize-redraw` [builtin:cli-tui] description: Terminal resize events recompute layout and repaint the current screen without corrupting content or losing the active context. - `behavior.tui-rendering.bounded-layout` [builtin:cli-tui] description: Content is clipped, wrapped, scrolled, or otherwise adapted to the available viewport instead of drawing outside terminal bounds. - `behavior.tui-screens` [builtin:cli-tui] explicit-screens: Distinct application contexts are modeled as identifiable screens, views, dialogs, or overlays with clear entry and exit behavior. current-context: The interface makes the current screen, active region, and available primary actions understandable to the user. transient-layers: Dialogs, menus, help, and error overlays preserve the underlying screen and return predictably when dismissed. id: tui-screens - `behavior.tui-screens.explicit-screens` [builtin:cli-tui] description: Distinct application contexts are modeled as identifiable screens, views, dialogs, or overlays with clear entry and exit behavior. - `behavior.tui-screens.current-context` [builtin:cli-tui] description: The interface makes the current screen, active region, and available primary actions understandable to the user. - `behavior.tui-screens.transient-layers` [builtin:cli-tui] description: Dialogs, menus, help, and error overlays preserve the underlying screen and return predictably when dismissed. - `behavior.tui-navigation` [builtin:cli-tui] keyboard-complete: Every primary workflow is operable from the keyboard. visible-focus: The currently focused interactive element or region is always visibly distinguishable. predictable-back: Back, cancel, and escape actions dismiss the nearest transient context or return to the previous screen without trapping focus. stable-controls: Navigation and action keys remain consistent across screens unless a screen clearly communicates a contextual override. discoverable-controls: The current screen exposes or provides access to help for its important navigation and action keys. id: tui-navigation - `behavior.tui-navigation.keyboard-complete` [builtin:cli-tui] description: Every primary workflow is operable from the keyboard. - `behavior.tui-navigation.visible-focus` [builtin:cli-tui] description: The currently focused interactive element or region is always visibly distinguishable. - `behavior.tui-navigation.predictable-back` [builtin:cli-tui] description: Back, cancel, and escape actions dismiss the nearest transient context or return to the previous screen without trapping focus. - `behavior.tui-navigation.stable-controls` [builtin:cli-tui] description: Navigation and action keys remain consistent across screens unless a screen clearly communicates a contextual override. - `behavior.tui-navigation.discoverable-controls` [builtin:cli-tui] description: The current screen exposes or provides access to help for its important navigation and action keys. - `behavior.tui-lifecycle` [builtin:cli-tui] managed-terminal-mode: Interactive terminal modes and full-screen presentation are entered only for the lifetime of the TUI session. restore-terminal: Normal exit, user cancellation, handled errors, and signals restore terminal modes, cursor visibility, and screen state before returning control to the shell. id: tui-lifecycle - `behavior.tui-lifecycle.managed-terminal-mode` [builtin:cli-tui] description: Interactive terminal modes and full-screen presentation are entered only for the lifetime of the TUI session. - `behavior.tui-lifecycle.restore-terminal` [builtin:cli-tui] description: Normal exit, user cancellation, handled errors, and signals restore terminal modes, cursor visibility, and screen state before returning control to the shell. - `behavior.cat-screen` [seed/seed.yml] description: Enter a full-screen terminal view, render one centered ASCII cat, and keep it visible until the user quits. - `behavior.quit` [seed/seed.yml] description: Pressing `q` or `Escape` exits and restores the terminal. ## Error Semantics - `errors.non-interactive-terminal` [builtin:cli-tui] code: tui.non-interactive-terminal when: The full-screen interface is started without a usable interactive terminal. remediation: Fail visibly with a concise diagnostic or use an explicitly documented non-interactive interface; never emit broken control sequences. id: non-interactive-terminal - `errors.terminal-capability-failure` [builtin:cli-tui] code: tui.terminal-capability-failure when: Required terminal capabilities cannot be initialized or maintained. remediation: Restore any changed terminal state and fail visibly with a concise diagnostic. id: terminal-capability-failure - `errors.unsupported-terminal` [seed/seed.yml] description: If a full-screen TUI cannot be opened, print a clear error and exit nonzero without corrupting the terminal. ## Security - `security.no-secret-output` [builtin:cli-nodejs] description: Must not print environment variables, tokens, or credentials unless explicitly required by the Seed. ## Environment - `environment.node-runtime` [builtin:cli-nodejs] description: Must run on Node.js 20 or newer. - `environment.npm-install` [builtin:cli-nodejs] description: Dependencies are installed with npm from package.json and package-lock.json when present. - `environment.linux` [builtin:cli-nodejs] description: Must run on Linux shells. - `environment.terminal` [builtin:tui-client] description: The client runs in a terminal environment with documented terminal capability assumptions. ## Observability - `observability.stderr-errors` [builtin:cli-interface] description: User-facing errors must be written to stderr. - `observability.exit-codes` [builtin:cli-interface] description: Exit code 0 means success; nonzero means validation, input, or execution failure. ## Compatibility - `compatibility.terminal-cleanup` [builtin:cli-tui] description: Returning to the shell must not leave raw input mode, hidden cursor state, corrupted terminal attributes, or TUI rendering artifacts. ## Constraints - `constraints.nodejs-cli-runtime` [builtin:cli-nodejs] description: The implementation is a Node.js command line application. - `constraints.terminal-user-interface` [builtin:tui-client] description: The target project exposes a terminal user interface client. - `constraints.full-screen-terminal-application` [builtin:cli-tui] description: The target interface behaves as an interactive terminal application comparable to nano, Vim, or htop, not as a line-oriented script that repeatedly prints replacement output. - `constraints.no-framework-requirement` [builtin:cli-tui] description: This genome imposes behavior and interaction contracts only; it does not require a TUI framework, rendering library, or architecture. ## Implementation Freedom - `freedom.nodejs-cli-structure` [builtin:cli-nodejs] description: Implementation may choose any maintainable internal Node.js module structure. - `freedom.tui-framework` [builtin:cli-tui] description: The implementation may choose any framework, terminal library, rendering strategy, state model, and screen architecture that satisfies the observable TUI contract. ## Verification Plan - `verifications.tui-application-lifecycle` [builtin:cli-tui] title: Full-screen TUI lifecycle is safe description: Verify the interface redraws in place and restores the terminal after normal exit and an interrupted or failed session. method: Exercise the TUI in a pseudo-terminal, navigate between screens, resize it, exit normally, interrupt a second run, and inspect terminal state. evidence_required: - Pseudo-terminal command or harness used. - Screen navigation and resize observations. - Terminal state observations after normal and interrupted exit. id: tui-application-lifecycle - `verifications.tui-keyboard-navigation` [builtin:cli-tui] title: Keyboard navigation is complete and visible description: Verify primary screens and actions are reachable with visible focus, discoverable controls, and predictable back or cancel behavior. method: Exercise every primary workflow using only documented keyboard controls. evidence_required: - Screens and primary workflows exercised. - Navigation and action keys used. - Focus, help, back, and cancel behavior observed. id: tui-keyboard-navigation