| # 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
|
| - <command> --help
|
| id: cli
|
|
|
| - `interfaces.tui` [builtin:tui-client]
|
| purpose: User interacts with the project through a terminal user interface.
|
| examples:
|
| - run <command>
|
| - 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
|