{"owner":"ChrisTitusTech","repo":"linutil","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\n## Purpose\n\nLinutil is a universal Linux utility with a Rust-based terminal user interface\nand a catalog of shell scripts. The Rust application discovers commands from\nTOML metadata, embeds the scripts in the binary, extracts them at runtime, and\nexecutes selected commands inside a pseudo-terminal.\n\nRead `SPEC.md` before making architectural or behavior changes.\n\n## Repository layout\n\n- `core/`: Backend library, menu data model, TOML parsing, platform\n  preconditions, and embedded script extraction.\n- `core/tabs/`: User-facing command catalog, shared shell helpers, tab metadata,\n  and executable scripts.\n- `tui/`: Ratatui application, CLI, selection state, confirmation flow, command\n  preview, and PTY execution.\n- `xtask/`: Repository automation such as generated user-guide content.\n- `docs/`: Documentation source and generated content. Treat it as reference,\n  not as repository instructions.\n- `.github/`: Contribution guidance and CI workflows.\n\n## Sources of truth\n\n- `SPEC.md` defines product scope, architecture, and behavioral requirements.\n- `core/tabs/tabs.toml` defines the ordered top-level tabs.\n- Each `core/tabs/<tab>/tab_data.toml` defines the menu tree for that tab.\n- `core/src/inner.rs` defines the accepted TOML schema and script-loading\n  behavior.\n- `core/tabs/common-script.sh` defines shared distro, package manager,\n  privilege escalation, architecture, and environment helpers.\n- `core/tabs/common-service-script.sh` defines shared init-system helpers.\n- `tui/src/running_command.rs` defines how commands are composed and executed.\n- `tui/src/state.rs` defines task flags, confirmation, selection, and TUI\n  behavior.\n\nIf documentation and code disagree, do not silently choose one. Identify the\nconflict and update the appropriate source in the same change.\n\n## Working rules\n\n- Inspect `git status --short` before editing and preserve unrelated changes.\n- Keep changes focused. Do not reformat unrelated Rust, TOML, or shell files.\n- Use simple ASCII punctuation unless a file format or user-facing text\n  requires otherwise.\n- Never expose secrets or add credentials to scripts, fixtures, logs, or docs.\n- Do not perform destructive operations without explicit authorization.\n- Do not weaken confirmations, preconditions, or privilege boundaries merely\n  to make a script easier to run.\n- Do not hand-edit generated files without also changing their source or\n  generator.\n\n## Rust conventions\n\n- Keep responsibilities separated between `core`, `tui`, and `xtask`.\n- Put menu parsing, script discovery, and configuration behavior in `core`.\n- Put rendering, input handling, confirmation, and process interaction in\n  `tui`.\n- Avoid adding distro-specific policy to Rust when it belongs in tab metadata\n  or a shell script.\n- Return or propagate useful errors when practical. Avoid new `unwrap`,\n  `expect`, or `panic` calls on user-controlled input.\n- Add or update tests for parser, filtering, configuration, and command-model\n  changes.\n- Format Rust with `cargo fmt`.\n- Treat Clippy warnings as errors.\n\n## Shell script conventions\n\n- Prefer POSIX shell with `#!/bin/sh -e`.\n- Use Bash only when the script requires Bash features, and declare\n  `#!/bin/bash` explicitly.\n- A script is executed from its own parent directory after the embedded\n  `core/tabs/` tree is extracted. Keep relative imports valid from that\n  directory.\n- Source shared helpers with the correct relative path:\n\n  ```sh\n  . ../common-script.sh\n  ```\n\n  Adjust the number of `..` components for nested directories.\n- Use `common-script.sh` helpers instead of duplicating package manager,\n  architecture, escalation, command detection, or distro detection logic.\n- Source `common-service-script.sh` when managing services across init systems.\n- Call `checkEnv` before relying on values such as `PACKAGER`,\n  `ESCALATION_TOOL`, `ARCH`, or `DTYPE`.\n- Quote variable expansions unless intentional word splitting is required.\n- Use `printf` rather than `echo` for portable formatted output.\n- Use `command_exists` for executable checks.\n- Use `\"$ESCALATION_TOOL\"` only for operations that require elevated\n  privileges. Do not run the whole script as root by default.\n- Make installation and configuration steps reasonably idempotent. Detect an\n  existing installation or state before changing it.\n- Fail with a clear message when a required distro, package manager,\n  architecture, display server, init system, or command is unsupported.\n- Do not download and execute unverified remote code when a package,\n  checksummed artifact, or pinned source is available.\n- Clean up temporary files created by the script.\n- Preserve interactive behavior because scripts run in a PTY.\n\n## Adding or changing a utility\n\n1. Place the script under the most appropriate `core/tabs/<tab>/` directory.\n2. Reuse shared helpers and support all practical package managers already\n   handled by `common-script.sh`.\n3. Add or update the matching entry in that tab's `tab_data.toml`.\n4. Provide a clear `name`, useful `description`, one of `script`, `command`, or\n   `entries`, and accurate `task_list` flags.\n5. Add `preconditions` when the entry only works on specific distros,\n   environments, filesystems, commands, display servers, or architectures.\n6. Set `multi_select = false` for interactive, destructive, rebooting,\n   long-running, or state-dependent operations that should not be queued.\n7. Run `cargo xtask docgen` when menu entries or descriptions change.\n8. Validate the script and the Rust catalog loader.\n\nThe supported task flags are:\n\n- `D`: disk modification\n- `FI`: Flatpak installation\n- `FM`: file modification\n- `I`: privileged installation\n- `K`: kernel modification\n- `MP`: package manager action\n- `RP`: package removal\n- `SI`: full system installation\n- `SS`: systemd or service action\n- Prefixing a flag with `P` indicates privileged work.\n\nDo not invent new task flags without updating the TUI guide and associated\ndocumentation.\n\n## TOML catalog rules\n\n- Script paths are relative to the tab directory containing `tab_data.toml`.\n- Every leaf entry must define exactly one executable form: `script` or\n  `command`.\n- Every directory entry uses `entries`.\n- Prefer scripts over long inline `command` values.\n- Keep names stable when possible because config-file `auto_execute` resolves\n  commands by display name.\n- Use preconditions to hide unsupported entries rather than letting users\n  discover incompatibility after execution.\n- Parent `multi_select = false` applies to all descendants.\n- Keep tab data consistently ordered. Use `sort-tomlfiles.sh` when the change\n  requires catalog sorting.\n\n## Validation\n\nRun the smallest relevant checks, then broaden them for cross-cutting changes.\n\nFor Rust changes:\n\n```bash\ncargo fmt --all --check\ncargo test --no-fail-fast --package linutil_core\ncargo clippy -- -Dwarnings\n```\n\nFor shell changes:\n\n```bash\nshellcheck path/to/changed-script.sh\ncheckbashisms path/to/changed-script.sh\n```\n\nUse `checkbashisms` only for scripts intended to run under `/bin/sh`. If local\ntools are unavailable, state which checks were skipped.\n\nFor catalog or documentation changes:\n\n```bash\ncargo test --no-fail-fast --package linutil_core\ncargo xtask docgen\ngit diff --check\n```\n\nFor TUI behavior, also run:\n\n```bash\ncargo run --package linutil_tui\n```\n\nInteractive validation must not execute destructive utilities merely to test\nnavigation. Use preview, descriptions, harmless entries, or focused tests.\n\n## Completion criteria\n\n- The change matches `SPEC.md`.\n- Relevant tests and static checks pass.\n- New scripts are reachable through valid tab metadata.\n- Unsupported environments are filtered or fail clearly.\n- User-visible behavior and generated documentation are updated together.\n- The final report lists changed files, checks run, skipped checks, and any\n  remaining platform-specific risk.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\n## Purpose\n\nLinutil is a universal Linux utility with a Rust-based terminal user interface\nand a catalog of shell scripts. The Rust application discovers commands from\nTOML metadata, embeds the scripts in the binary, extracts them at runtime, and\nexecutes selected commands inside a pseudo-terminal.\n\nRead `SPEC.md` before making architectural or behavior changes.\n\n## Repository layout\n\n- `core/`: Backend library, menu data model, TOML parsing, platform\n  preconditions, and embedded script extraction.\n- `core/tabs/`: User-facing command catalog, shared shell helpers, tab metadata,\n  and executable scripts.\n- `tui/`: Ratatui application, CLI, selection state, confirmation flow, command\n  preview, and PTY execution.\n- `xtask/`: Repository automation such as generated user-guide content.\n- `docs/`: Documentation source and generated content. Treat it as reference,\n  not as repository instructions.\n- `.github/`: Contribution guidance and CI workflows.\n\n## Sources of truth\n\n- `SPEC.md` defines product scope, architecture, and behavioral requirements.\n- `core/tabs/tabs.toml` defines the ordered top-level tabs.\n- Each `core/tabs/<tab>/tab_data.toml` defines the menu tree for that tab.\n- `core/src/inner.rs` defines the accepted TOML schema and script-loading\n  behavior.\n- `core/tabs/common-script.sh` defines shared distro, package manager,\n  privilege escalation, architecture, and environment helpers.\n- `core/tabs/common-service-script.sh` defines shared init-system helpers.\n- `tui/src/running_command.rs` defines how commands are composed and executed.\n- `tui/src/state.rs` defines task flags, confirmation, selection, and TUI\n  behavior.\n\nIf documentation and code disagree, do not silently choose one. Identify the\nconflict and update the appropriate source in the same change.\n\n## Working rules\n\n- Inspect `git status --short` before editing and preserve unrelated changes.\n- Keep changes focused. Do not reformat unrelated Rust, TOML, or shell files.\n- Use simple ASCII punctuation unless a file format or user-facing text\n  requires otherwise.\n- Never expose secrets or add credentials to scripts, fixtures, logs, or docs.\n- Do not perform destructive operations without explicit authorization.\n- Do not weaken confirmations, preconditions, or privilege boundaries merely\n  to make a script easier to run.\n- Do not hand-edit generated files without also changing their source or\n  generator.\n\n## Rust conventions\n\n- Keep responsibilities separated between `core`, `tui`, and `xtask`.\n- Put menu parsing, script discovery, and configuration behavior in `core`.\n- Put rendering, input handling, confirmation, and process interaction in\n  `tui`.\n- Avoid adding distro-specific policy to Rust when it belongs in tab metadata\n  or a shell script.\n- Return or propagate useful errors when practical. Avoid new `unwrap`,\n  `expect`, or `panic` calls on user-controlled input.\n- Add or update tests for parser, filtering, configuration, and command-model\n  changes.\n- Format Rust with `cargo fmt`.\n- Treat Clippy warnings as errors.\n\n## Shell script conventions\n\n- Prefer POSIX shell with `#!/bin/sh -e`.\n- Use Bash only when the script requires Bash features, and declare\n  `#!/bin/bash` explicitly.\n- A script is executed from its own parent directory after the embedded\n  `core/tabs/` tree is extracted. Keep relative imports valid from that\n  directory.\n- Source shared helpers with the correct relative path:\n\n  ```sh\n  . ../common-script.sh\n  ```\n\n  Adjust the number of `..` components for nested directories.\n- Use `common-script.sh` helpers instead of duplicating package manager,\n  architecture, escalation, command detection, or distro detection logic.\n- Source `common-service-script.sh` when managing services across init systems.\n- Call `checkEnv` before relying on values such as `PACKAGER`,\n  `ESCALATION_TOOL`, `ARCH`, or `DTYPE`.\n- Quote variable expansions unless intentional word splitting is required.\n- Use `printf` rather than `echo` for portable formatted output.\n- Use `command_exists` for executable checks.\n- Use `\"$ESCALATION_TOOL\"` only for operations that require elevated\n  privileges. Do not run the whole script as root by default.\n- Make installation and configuration steps reasonably idempotent. Detect an\n  existing installation or state before changing it.\n- Fail with a clear message when a required distro, package manager,\n  architecture, display server, init system, or command is unsupported.\n- Do not download and execute unverified remote code when a package,\n  checksummed artifact, or pinned source is available.\n- Clean up temporary files created by the script.\n- Preserve interactive behavior because scripts run in a PTY.\n\n## Adding or changing a utility\n\n1. Place the script under the most appropriate `core/tabs/<tab>/` directory.\n2. Reuse shared helpers and support all practical package managers already\n   handled by `common-script.sh`.\n3. Add or update the matching entry in that tab's `tab_data.toml`.\n4. Provide a clear `name`, useful `description`, one of `script`, `command`, or\n   `entries`, and accurate `task_list` flags.\n5. Add `preconditions` when the entry only works on specific distros,\n   environments, filesystems, commands, display servers, or architectures.\n6. Set `multi_select = false` for interactive, destructive, rebooting,\n   long-running, or state-dependent operations that should not be queued.\n7. Run `cargo xtask docgen` when menu entries or descriptions change.\n8. Validate the script and the Rust catalog loader.\n\nThe supported task flags are:\n\n- `D`: disk modification\n- `FI`: Flatpak installation\n- `FM`: file modification\n- `I`: privileged installation\n- `K`: kernel modification\n- `MP`: package manager action\n- `RP`: package removal\n- `SI`: full system installation\n- `SS`: systemd or service action\n- Prefixing a flag with `P` indicates privileged work.\n\nDo not invent new task flags without updating the TUI guide and associated\ndocumentation.\n\n## TOML catalog rules\n\n- Script paths are relative to the tab directory containing `tab_data.toml`.\n- Every leaf entry must define exactly one executable form: `script` or\n  `command`.\n- Every directory entry uses `entries`.\n- Prefer scripts over long inline `command` values.\n- Keep names stable when possible because config-file `auto_execute` resolves\n  commands by display name.\n- Use preconditions to hide unsupported entries rather than letting users\n  discover incompatibility after execution.\n- Parent `multi_select = false` applies to all descendants.\n- Keep tab data consistently ordered. Use `sort-tomlfiles.sh` when the change\n  requires catalog sorting.\n\n## Validation\n\nRun the smallest relevant checks, then broaden them for cross-cutting changes.\n\nFor Rust changes:\n\n```bash\ncargo fmt --all --check\ncargo test --no-fail-fast --package linutil_core\ncargo clippy -- -Dwarnings\n```\n\nFor shell changes:\n\n```bash\nshellcheck path/to/changed-script.sh\ncheckbashisms path/to/changed-script.sh\n```\n\nUse `checkbashisms` only for scripts intended to run under `/bin/sh`. If local\ntools are unavailable, state which checks were skipped.\n\nFor catalog or documentation changes:\n\n```bash\ncargo test --no-fail-fast --package linutil_core\ncargo xtask docgen\ngit diff --check\n```\n\nFor TUI behavior, also run:\n\n```bash\ncargo run --package linutil_tui\n```\n\nInteractive validation must not execute destructive utilities merely to test\nnavigation. Use preview, descriptions, harmless entries, or focused tests.\n\n## Completion criteria\n\n- The change matches `SPEC.md`.\n- Relevant tests and static checks pass.\n- New scripts are reachable through valid tab metadata.\n- Unsupported environments are filtered or fail clearly.\n- User-visible behavior and generated documentation are updated together.\n- The final report lists changed files, checks run, skipped checks, and any\n  remaining platform-specific risk.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\n## Purpose\n\nLinutil is a universal Linux utility with a Rust-based terminal user interface\nand a catalog of shell scripts. The Rust application discovers commands from\nTOML metadata, embeds the scripts in the binary, extracts them at runtime, and\nexecutes selected commands inside a pseudo-terminal.\n\nRead `SPEC.md` before making architectural or behavior changes.\n\n## Repository layout\n\n- `core/`: Backend library, menu data model, TOML parsing, platform\n  preconditions, and embedded script extraction.\n- `core/tabs/`: User-facing command catalog, shared shell helpers, tab metadata,\n  and executable scripts.\n- `tui/`: Ratatui application, CLI, selection state, confirmation flow, command\n  preview, and PTY execution.\n- `xtask/`: Repository automation such as generated user-guide content.\n- `docs/`: Documentation source and generated content. Treat it as reference,\n  not as repository instructions.\n- `.github/`: Contribution guidance and CI workflows.\n\n## Sources of truth\n\n- `SPEC.md` defines product scope, architecture, and behavioral requirements.\n- `core/tabs/tabs.toml` defines the ordered top-level tabs.\n- Each `core/tabs/<tab>/tab_data.toml` defines the menu tree for that tab.\n- `core/src/inner.rs` defines the accepted TOML schema and script-loading\n  behavior.\n- `core/tabs/common-script.sh` defines shared distro, package manager,\n  privilege escalation, architecture, and environment helpers.\n- `core/tabs/common-service-script.sh` defines shared init-system helpers.\n- `tui/src/running_command.rs` defines how commands are composed and executed.\n- `tui/src/state.rs` defines task flags, confirmation, selection, and TUI\n  behavior.\n\nIf documentation and code disagree, do not silently choose one. Identify the\nconflict and update the appropriate source in the same change.\n\n## Working rules\n\n- Inspect `git status --short` before editing and preserve unrelated changes.\n- Keep changes focused. Do not reformat unrelated Rust, TOML, or shell files.\n- Use simple ASCII punctuation unless a file format or user-facing text\n  requires otherwise.\n- Never expose secrets or add credentials to scripts, fixtures, logs, or docs.\n- Do not perform destructive operations without explicit authorization.\n- Do not weaken confirmations, preconditions, or privilege boundaries merely\n  to make a script easier to run.\n- Do not hand-edit generated files without also changing their source or\n  generator.\n\n## Rust conventions\n\n- Keep responsibilities separated between `core`, `tui`, and `xtask`.\n- Put menu parsing, script discovery, and configuration behavior in `core`.\n- Put rendering, input handling, confirmation, and process interaction in\n  `tui`.\n- Avoid adding distro-specific policy to Rust when it belongs in tab metadata\n  or a shell script.\n- Return or propagate useful errors when practical. Avoid new `unwrap`,\n  `expect`, or `panic` calls on user-controlled input.\n- Add or update tests for parser, filtering, configuration, and command-model\n  changes.\n- Format Rust with `cargo fmt`.\n- Treat Clippy warnings as errors.\n\n## Shell script conventions\n\n- Prefer POSIX shell with `#!/bin/sh -e`.\n- Use Bash only when the script requires Bash features, and declare\n  `#!/bin/bash` explicitly.\n- A script is executed from its own parent directory after the embedded\n  `core/tabs/` tree is extracted. Keep relative imports valid from that\n  directory.\n- Source shared helpers with the correct relative path:\n\n  ```sh\n  . ../common-script.sh\n  ```\n\n  Adjust the number of `..` components for nested directories.\n- Use `common-script.sh` helpers instead of duplicating package manager,\n  architecture, escalation, command detection, or distro detection logic.\n- Source `common-service-script.sh` when managing services across init systems.\n- Call `checkEnv` before relying on values such as `PACKAGER`,\n  `ESCALATION_TOOL`, `ARCH`, or `DTYPE`.\n- Quote variable expansions unless intentional word splitting is required.\n- Use `printf` rather than `echo` for portable formatted output.\n- Use `command_exists` for executable checks.\n- Use `\"$ESCALATION_TOOL\"` only for operations that require elevated\n  privileges. Do not run the whole script as root by default.\n- Make installation and configuration steps reasonably idempotent. Detect an\n  existing installation or state before changing it.\n- Fail with a clear message when a required distro, package manager,\n  architecture, display server, init system, or command is unsupported.\n- Do not download and execute unverified remote code when a package,\n  checksummed artifact, or pinned source is available.\n- Clean up temporary files created by the script.\n- Preserve interactive behavior because scripts run in a PTY.\n\n## Adding or changing a utility\n\n1. Place the script under the most appropriate `core/tabs/<tab>/` directory.\n2. Reuse shared helpers and support all practical package managers already\n   handled by `common-script.sh`.\n3. Add or update the matching entry in that tab's `tab_data.toml`.\n4. Provide a clear `name`, useful `description`, one of `script`, `command`, or\n   `entries`, and accurate `task_list` flags.\n5. Add `preconditions` when the entry only works on specific distros,\n   environments, filesystems, commands, display servers, or architectures.\n6. Set `multi_select = false` for interactive, destructive, rebooting,\n   long-running, or state-dependent operations that should not be queued.\n7. Run `cargo xtask docgen` when menu entries or descriptions change.\n8. Validate the script and the Rust catalog loader.\n\nThe supported task flags are:\n\n- `D`: disk modification\n- `FI`: Flatpak installation\n- `FM`: file modification\n- `I`: privileged installation\n- `K`: kernel modification\n- `MP`: package manager action\n- `RP`: package removal\n- `SI`: full system installation\n- `SS`: systemd or service action\n- Prefixing a flag with `P` indicates privileged work.\n\nDo not invent new task flags without updating the TUI guide and associated\ndocumentation.\n\n## TOML catalog rules\n\n- Script paths are relative to the tab directory containing `tab_data.toml`.\n- Every leaf entry must define exactly one executable form: `script` or\n  `command`.\n- Every directory entry uses `entries`.\n- Prefer scripts over long inline `command` values.\n- Keep names stable when possible because config-file `auto_execute` resolves\n  commands by display name.\n- Use preconditions to hide unsupported entries rather than letting users\n  discover incompatibility after execution.\n- Parent `multi_select = false` applies to all descendants.\n- Keep tab data consistently ordered. Use `sort-tomlfiles.sh` when the change\n  requires catalog sorting.\n\n## Validation\n\nRun the smallest relevant checks, then broaden them for cross-cutting changes.\n\nFor Rust changes:\n\n```bash\ncargo fmt --all --check\ncargo test --no-fail-fast --package linutil_core\ncargo clippy -- -Dwarnings\n```\n\nFor shell changes:\n\n```bash\nshellcheck path/to/changed-script.sh\ncheckbashisms path/to/changed-script.sh\n```\n\nUse `checkbashisms` only for scripts intended to run under `/bin/sh`. If local\ntools are unavailable, state which checks were skipped.\n\nFor catalog or documentation changes:\n\n```bash\ncargo test --no-fail-fast --package linutil_core\ncargo xtask docgen\ngit diff --check\n```\n\nFor TUI behavior, also run:\n\n```bash\ncargo run --package linutil_tui\n```\n\nInteractive validation must not execute destructive utilities merely to test\nnavigation. Use preview, descriptions, harmless entries, or focused tests.\n\n## Completion criteria\n\n- The change matches `SPEC.md`.\n- Relevant tests and static checks pass.\n- New scripts are reachable through valid tab metadata.\n- Unsupported environments are filtered or fail clearly.\n- User-visible behavior and generated documentation are updated together.\n- The final report lists changed files, checks run, skipped checks, and any\n  remaining platform-specific risk.\n","category":"root","tokens":1966}]}