Techcle Wiki

Requirements

6 min read

Requirements Document

Introduction

CascadeGuard CLI v2 aligns the pre-release CLI (v0.1) with the published getting-started documentation. The changes introduce a cg shorthand alias, rename the ci command group to build, add a cg init scaffolding command, unify images check to absorb check-upstream and generate into a single pass, and remove the now-redundant check-upstream-tags.yaml workflow from open-secure-images.

Glossary

  • CLI: The CascadeGuard command-line interface, invoked as cascadeguard or cg
  • State_Repository: A Git repository that declares managed images and tracks their current state via images.yaml, .cascadeguard.yaml, and generated state files
  • Seed_Repo: The cascadeguard-seed GitHub repository containing starter files for a new state repository
  • Init_Command: The cg init subcommand that scaffolds a state repository from the seed repo
  • Check_Command: The unified cg images check subcommand that discovers base images, writes state files, checks digest drift, and checks upstream tags in a single pass
  • Build_Command: The cg build command group (renamed from ci) that generates CI pipeline files
  • Images_Yaml: The images.yaml file listing all enrolled images and their configuration
  • Config_Yaml: The .cascadeguard.yaml file containing repo-level defaults
  • State_Dir: The .cascadeguard/ directory containing generated image and base-image state files
  • Digest_Drift: A condition where the live registry digest for a base image differs from the recorded digest in the state file
  • Upstream_Tags: New tags discovered on Docker Hub for enrolled images that were not previously recorded

Requirements

Requirement 1: cg Alias Entry Point

User Story: As a developer, I want to invoke CascadeGuard using the short cg command, so that I can type less when running CLI operations.

Acceptance Criteria

  1. THE CLI SHALL register both cascadeguard and cg as entry points in pyproject.toml pointing to the same app:main function
  2. WHEN a user invokes cg with any subcommand, THE CLI SHALL produce identical behaviour to invoking cascadeguard with the same subcommand
  3. WHEN the install script completes, THE CLI SHALL make both cascadeguard and cg available on the user PATH

Requirement 2: Init Command

User Story: As a developer, I want to run cg init to scaffold a new state repository from the seed repo, so that I can get started quickly without manually copying files.

Acceptance Criteria

  1. WHEN a user runs cg init, THE Init_Command SHALL clone the Seed_Repo and copy all seed files into the target directory
  2. WHEN a seed file already exists in the target directory, THE Init_Command SHALL skip that file and print a warning to stderr
  3. WHEN the target directory does not contain a .gitignore file, THE Init_Command SHALL create one containing the .cascadeguard/.cache/ entry
  4. WHEN the target directory contains a .gitignore file that lacks the .cascadeguard/.cache/ entry, THE Init_Command SHALL append that entry to the existing file
  5. WHEN the target directory contains a .gitignore file that already has the .cascadeguard/.cache/ entry, THE Init_Command SHALL leave the file unchanged
  6. WHEN all files are processed, THE Init_Command SHALL print a summary showing the count of files copied and files skipped
  7. WHEN the init operation completes without fatal errors, THE Init_Command SHALL return exit code 0
  8. IF the Seed_Repo cannot be cloned due to network failure or invalid URL, THEN THE Init_Command SHALL return exit code 1 and print a descriptive error to stderr

Requirement 3: Rename ci Command Group to build

User Story: As a developer, I want to use cg build generate instead of cg ci generate, so that the CLI matches the published documentation.

Acceptance Criteria

  1. THE CLI SHALL register a build command group with a generate subcommand
  2. WHEN a user runs cg build generate, THE Build_Command SHALL produce identical output to the current cg ci generate command
  3. WHEN a user runs cg build generate --dry-run, THE Build_Command SHALL preview generated workflow files without writing them to disk
  4. THE CLI SHALL remove the ci command group from the argument parser

Requirement 4: Unified images check Command

User Story: As a developer, I want cg images check to perform state generation, digest drift detection, and upstream tag checking in a single pass, so that I do not need to run multiple commands.

Acceptance Criteria

  1. WHEN a user runs cg images check, THE Check_Command SHALL load Images_Yaml and Config_Yaml defaults
  2. WHEN processing each enabled image, THE Check_Command SHALL parse the Dockerfile to discover base image references
  3. WHEN base images are discovered, THE Check_Command SHALL write or update state files under State_Dir/images/ and State_Dir/base-images/
  4. WHEN state files are written, THE Check_Command SHALL query the container registry for the current digest of each base image
  5. WHEN the live digest differs from the recorded digest, THE Check_Command SHALL report the base image as having Digest_Drift
  6. WHEN checking upstream tags, THE Check_Command SHALL query Docker Hub for new tags on each enrolled image
  7. WHEN Digest_Drift is detected or new Upstream_Tags are found, THE Check_Command SHALL return exit code 1
  8. WHEN no drift and no new upstream tags are found, THE Check_Command SHALL return exit code 0
  9. WHEN the --format table option is provided, THE Check_Command SHALL render results as a human-readable table
  10. WHEN the --format json option is provided, THE Check_Command SHALL render results as a JSON object
  11. WHEN the --image option is provided, THE Check_Command SHALL scope all operations to the named image only
  12. IF Images_Yaml does not exist or is not valid YAML, THEN THE Check_Command SHALL print a descriptive error and return exit code 1

Requirement 5: Remove check-upstream Subcommand

User Story: As a developer, I want the separate images check-upstream subcommand removed, so that there is a single unified check workflow and no confusion about which command to run.

Acceptance Criteria

  1. THE CLI SHALL remove the check-upstream subcommand from the images command group
  2. WHEN a user runs cg images check-upstream, THE CLI SHALL display an unrecognised-command error

Requirement 6: Remove check-upstream-tags Workflow

User Story: As a maintainer of the open-secure-images repository, I want the check-upstream-tags.yaml workflow removed, so that upstream tag checking is handled entirely by the unified images check command.

Acceptance Criteria

  1. THE Seed_Repo SHALL not include a check-upstream-tags.yaml workflow file
  2. WHEN cg init scaffolds a new repository, THE Init_Command SHALL not create a check-upstream-tags.yaml workflow file

Requirement 7: Output Formatting

User Story: As a developer, I want consistent output formatting across all commands, so that I can parse results in CI pipelines and read them in a terminal.

Acceptance Criteria

  1. WHEN the --format flag is set to table, THE Check_Command SHALL render results using a human-readable table with columns for image name, status, and details
  2. WHEN the --format flag is set to json, THE Check_Command SHALL render results as a valid JSON array where each element contains image name, status, and relevant details
  3. WHEN no --format flag is provided, THE Check_Command SHALL default to table format

Graph View