Skip to content

CLI

The CLI is the contractual entry point into the DITA Package Processor. It exposes a small, explicit set of subcommands that correspond directly to pipeline stages: discovery, normalization, planning, execution, and the full run pipeline.

The CLI performs no domain logic. Its responsibilities are limited to argument validation, loading and writing artifacts, wiring the correct components together, and reporting failures clearly. It does not inspect XML, interpret plans, or mutate the filesystem implicitly.

Each command consumes exactly one expected artifact type and produces exactly one output artifact. Invalid combinations fail immediately. This makes the CLI deterministic, scriptable, and safe for automation in batch or CI environments.

The CLI is intentionally strict. It prioritizes reproducibility and auditability over convenience, and it never guesses user intent.

dita_package_processor.cli

Unified command-line interface for dita_package_processor.

This module defines the root CLI entry point, global options, and subcommand dispatch. Subcommands are registered in dedicated modules.

Global concerns handled here
  • argument normalization
  • logging configuration
  • machine-readable output flags
  • implicit pipeline execution
  • docs and shell completion helpers
Design principles
  • argparse owns parsing
  • no manual flag handling
  • subcommands contain all behavior
  • this file is routing + orchestration only

build_parser()

Build and return the root argument parser.

Returns

argparse.ArgumentParser Configured CLI parser.

main(argv=None)

CLI entry point.

Behavior
  • --help/--version handled by argparse directly
  • implicit 'run' only when no command is supplied

dita_package_processor.cli_discover

Discovery CLI subcommand.

Runs discovery-only analysis over a DITA package directory and emits:

  • A human-readable summary (default)
  • Optional JSON discovery report (via --output or --json)
  • Optional invariant validation feedback

This command:

  • Does NOT transform content
  • Does NOT mutate files
  • Does NOT infer intent

It is a strict observational interface over the discovery subsystem. All results are deterministic, auditable, and schema-aligned.

register_discover(subparsers)

Register the discover subcommand.

Parameters:

Name Type Description Default
subparsers Any

Root argparse subparser registry.

 required

run_discover(args)

Execute discovery scanning and emit outputs.

Parameters:

Name Type Description Default
args Namespace

Parsed CLI arguments.

 required

Returns:

Type Description
int

Exit code.

dita_package_processor.cli_plan

cli_plan.py

Planning CLI interface.

Thin controller only.

Flow

read → validate contract → plan → validate → write

Responsibilities
  • Read planning_input.json
  • Hydrate PlanningInput contract
  • Invoke Planner
  • Validate produced plan
  • Write plan.json
Non-Responsibilities
  • No discovery parsing
  • No normalization
  • No schema mutation
  • No inference
  • No business logic

This file is strictly a transport/controller layer.

register_plan(subparsers)

Register the plan subcommand.

Parameters

subparsers : Any argparse subparser collection.

run_plan(args)

Execute planning workflow.

Strict transport pipeline:

file → PlanningInput → planner → file
Parameters

args : argparse.Namespace Parsed CLI arguments.

Returns

int 0 success 1 planning failure 2 setup/contract failure

dita_package_processor.cli_run

Pipeline orchestration CLI command.

This module implements the run subcommand, which represents the full DITA Package Processor pipeline:

discover → plan → materialization → execute

Design rules:

  • Dry-run is the default and safest mode
  • Filesystem mutation is only allowed when --apply is provided
  • This command performs real orchestration
  • No planning, discovery, or execution logic lives here
  • The ExecutionReport is a first-class artifact

register_run(subparsers)

Register the run subcommand.

Parameters:

Name Type Description Default
subparsers _SubParsersAction

Root argparse subparser registry.

 required

run_pipeline(args)

Execute the full discovery → planning → materialization → execution pipeline.

This function is a strict orchestration boundary: - no discovery logic - no planning logic - no materialization logic - no execution logic

It validates user intent, wires the pipeline, and normalizes failures.

Parameters:

Name Type Description Default
args Namespace

Parsed CLI arguments.

 required

Returns:

Type Description
int

Process exit code.

dita_package_processor.cli_execute

Execution CLI subcommand.

Executes a validated plan and produces an ExecutionReport.

Supports: --plan PATH required --output PATH required (execution target root) --report PATH optional --json optional

Design rules

CLI is dumb glue only.

It: - loads plan - mkdirs output - calls executor - writes report

It does NOT: - use Pipeline - perform discovery - perform planning - perform materialization - invent layers - mutate implicitly

run_execute(args)

Execute a validated plan.

Responsibilities

CLI is glue only. It must:

  1. Validate inputs
  2. Load + normalize plan
  3. Create output directory
  4. Select executor
  5. Execute
  6. Emit report

It must NOT: - mutate planning logic - perform discovery - guess paths

Returns

int 0 success 1 execution failure 2 configuration / validation failure