Skip to content

Add structkit explain command to preview structure resolution #136

@httpdss

Description

@httpdss

Summary

Add a structkit explain command that explains how a structure definition will resolve before generation.

Motivation

generate --dry-run previews file operations, but users also need a structure-focused explanation that shows nested structures, remote content, variables, hooks, and conflict behavior before writing anything.

Proposed behavior

  • Accept built-in, custom-path, and local YAML structure definitions.
  • Show files and folders that would be generated.
  • Show nested structures referenced by folders[].struct.
  • Show remote files that would be fetched.
  • Show declared variables and resolved values when --vars is provided.
  • Show pre/post hooks without executing them.
  • Support output formats such as text and JSON.

Example usage

  • structkit explain terraform/modules/generic
  • structkit explain ./my-struct.yaml --vars project_name=demo
  • structkit explain project/python --json

Acceptance criteria

  • Command is registered in the CLI.
  • Does not create files, folders, or execute hooks.
  • Includes tests for nested structures, remote file references, hooks, variables, and JSON output.
  • Documentation explains the difference between explain and generate --dry-run.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions