connect-flow 0.1.1__py3-none-any.whl

connect_flow/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

connect_flow/__main__.py

@@ -0,0 +1,4 @@
+from connect_flow.cli import main_connect_flow
+
+if __name__ == "__main__":
+    raise SystemExit(main_connect_flow())

connect_flow/args.py

@@ -0,0 +1,647 @@
+"""Argument parser construction for the ``connect-flow`` console script, plus
+the two cross-flag validators that belong with it.
+
+Split out of cli.py: parser construction is ~500 lines of pure declaration
+with no behaviour, and it depends on nothing else in the CLI beyond an exit
+code. Keeping it here leaves cli.py as the verb dispatch it is named for.
+See docs/adr/0011-cli-module-split.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from connect_flow import __version__
+from connect_flow.exits import EXIT_USAGE_ERROR
+
+
+class _ArgumentParser(argparse.ArgumentParser):
+    """argparse exits with status 2 on its own usage errors; we reserve 2 for
+    safety violations and want 3 for bad usage (see module docstring)."""
+
+    def error(self, message: str) -> None:
+        self.print_usage(sys.stderr)
+        self.exit(EXIT_USAGE_ERROR, f"{self.prog}: error: {message}\n")
+
+
+def _add_common_output_arguments(
+    parser: argparse.ArgumentParser, *, suppress_defaults: bool = False
+) -> None:
+    """Flags shared by every ``connect-flow`` subcommand, and by the top-level
+    parser itself so they can also be given before the subcommand, aws-cli
+    style (``connect-flow --profile p --region r list``).
+
+    A subparser's ``parse_known_args`` is handed a *fresh* sub-namespace, not
+    the parent's - once it returns, argparse copies every attribute that
+    sub-namespace holds onto the parent namespace unconditionally, clobbering
+    whatever the top-level parsing already set. ``suppress_defaults=True``
+    (used only for the per-subcommand copies of these flags) makes an
+    unsupplied flag simply absent from that sub-namespace instead of present
+    with a default of ``None``/``False``, so the merge has nothing to
+    clobber with and a value given before the subcommand survives.
+    """
+    str_default = argparse.SUPPRESS if suppress_defaults else None
+    bool_default = argparse.SUPPRESS if suppress_defaults else False
+    parser.add_argument(
+        "--profile", metavar="NAME", default=str_default, help="AWS profile to use"
+    )
+    parser.add_argument(
+        "--region",
+        metavar="NAME",
+        default=str_default,
+        help="AWS region; inferred from a target ARN if omitted, or checked for a "
+        "conflict if a target ARN disagrees. Where a region must be known up "
+        "front (--instance addressing, list) and none is given, falls back "
+        "to your AWS profile/config default",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        default=bool_default,
+        help="machine-readable report on stdout",
+    )
+    parser.add_argument(
+        "--quiet", action="store_true", default=bool_default, help="errors only"
+    )
+
+
+def _add_instance_argument(parser: argparse.ArgumentParser) -> None:
+    """--instance: a Connect instance id or alias, auto-detected via
+    aws.is_id_like() - a name is resolved via ListInstances (exact match).
+    Added everywhere instance addressing is needed, so this is the one place
+    the flag is defined. See docs/adr/0008-unified-instance-flow-addressing.md."""
+    parser.add_argument(
+        "--instance",
+        metavar="ID-OR-ALIAS",
+        default=None,
+        help="Connect instance id, or alias resolved via ListInstances (exact match)",
+    )
+
+
+def _add_flow_arguments(
+    parser: argparse.ArgumentParser, *, flow_help: str, module_help: str
+) -> None:
+    """--flow/--flow-module: each value may be a full ARN, a bare id, a bare
+    name (resolved against --instance), or INSTANCE/NAME-OR-ID embedding its
+    own instance (id or alias, resolved independently of --instance). Added
+    everywhere this addressing is needed, so this is the one place these
+    flags are defined. See docs/adr/0008-unified-instance-flow-addressing.md."""
+    parser.add_argument(
+        "--flow",
+        metavar="[INSTANCE/]ID-OR-NAME-OR-ARN",
+        action="append",
+        default=[],
+        help=flow_help,
+    )
+    parser.add_argument(
+        "--flow-module",
+        metavar="[INSTANCE/]ID-OR-NAME-OR-ARN",
+        action="append",
+        default=[],
+        help=module_help,
+    )
+
+
+def _add_prettify_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "targets",
+        nargs="*",
+        metavar="TARGET",
+        help="local flow JSON file(s), or flow/flow-module ARN(s)",
+    )
+    _add_instance_argument(parser)
+    _add_flow_arguments(
+        parser,
+        flow_help="contact flow to target (repeatable): a bare id, a name (resolved via "
+        "ListContactFlows against --instance), a full ARN, or INSTANCE/NAME-OR-ID embedding "
+        "its own instance",
+        module_help="flow module to target (repeatable): a bare id, a name (resolved via "
+        "ListContactFlowModules against --instance), a full ARN, or INSTANCE/NAME-OR-ID "
+        "embedding its own instance",
+    )
+    parser.add_argument(
+        "--stage",
+        choices=["published", "saved"],
+        default=None,
+        help="which remote content to read/write (default: published for reads, "
+        "saved for writes)",
+    )
+    parser.add_argument(
+        "--in-place",
+        action="store_true",
+        help="write the result back to its source (an upload, for a remote target)",
+    )
+    parser.add_argument(
+        "--output",
+        "-o",
+        metavar="FILE",
+        default=None,
+        help="write the prettified flow to this exact path (single target only)",
+    )
+    parser.add_argument(
+        "--output-dir",
+        metavar="DIR",
+        default=None,
+        help="write each prettified flow to DIR/STEM.json",
+    )
+    parser.add_argument(
+        "--stdout",
+        action="store_true",
+        help="emit the rewritten JSON to stdout instead of writing anywhere (single target only)",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="never write; exit 1 if any target would change (CI / pre-commit gate)",
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true", help="never write; report what would change"
+    )
+    parser.add_argument(
+        "--diff", action="store_true", help="print a unified diff of changes"
+    )
+    parser.add_argument(
+        "--no-backup",
+        action="store_true",
+        help="skip writing a .bak file (local targets only)",
+    )
+    parser.add_argument(
+        "--render",
+        action="store_true",
+        help="also write STEM.before.png and STEM.after.png for each target "
+        "(next to a local input, or into --render-dir)",
+    )
+    parser.add_argument(
+        "--render-dir",
+        metavar="DIR",
+        default=None,
+        help="directory to write --render PNGs into (required for a remote target)",
+    )
+    _add_remote_write_arguments(parser)
+
+
+def _add_remote_write_arguments(parser: argparse.ArgumentParser) -> None:
+    """Flags that only make sense alongside a remote write (--in-place on a
+    RemoteTarget, or push). Shared between the prettify and push subparsers."""
+    parser.add_argument(
+        "--publish",
+        action="store_true",
+        help="write the live content instead of leaving it a saved draft",
+    )
+    parser.add_argument(
+        "--snapshot",
+        choices=["before", "after", "both", "none"],
+        default="before",
+        help="create an immutable version snapshot around the upload (default: before)",
+    )
+    parser.add_argument(
+        "--snapshot-description",
+        metavar="TEXT",
+        default=None,
+        help=f"description for the snapshot (default: connect-flow {__version__}: pre-format snapshot)",
+    )
+    parser.add_argument(
+        "--local-backup",
+        metavar="DIR",
+        default=None,
+        help="write the pre-change content to DIR/STEM.json before uploading - a rollback "
+        "copy that doesn't depend on Create*Version, which Connect only supports for "
+        "Campaign-type contact flows",
+    )
+    parser.add_argument(
+        "--yes",
+        action="store_true",
+        help="skip the interactive confirmation before a remote write",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="proceed despite a sha conflict or an ARCHIVED resource",
+    )
+    parser.add_argument(
+        "--no-verify",
+        action="store_true",
+        help="skip the post-upload read-back digest check",
+    )
+
+
+def _add_multi_target_arguments(parser: argparse.ArgumentParser) -> None:
+    """TARGET positionals plus the --instance/--flow/--flow-module
+    desugaring, shared by lint and digest (same shape as prettify's)."""
+    parser.add_argument(
+        "targets",
+        nargs="*",
+        metavar="TARGET",
+        help="local flow JSON file(s), or flow/flow-module ARN(s)",
+    )
+    _add_instance_argument(parser)
+    _add_flow_arguments(
+        parser,
+        flow_help="contact flow (repeatable): a bare id, a name (resolved via "
+        "ListContactFlows against --instance), a full ARN, or INSTANCE/NAME-OR-ID embedding "
+        "its own instance",
+        module_help="flow module (repeatable): a bare id, a name (resolved via "
+        "ListContactFlowModules against --instance), a full ARN, or INSTANCE/NAME-OR-ID "
+        "embedding its own instance",
+    )
+
+
+def _add_translate_common_arguments(parser: argparse.ArgumentParser) -> None:
+    """Flags shared by export/import/normalize: the environment map, the
+    discovery bootstrap, and the same destination-flag set prettify uses -
+    any of the three can also re-layout via --prettify, reusing prettify()'s
+    own engine rather than a second implementation."""
+    parser.add_argument(
+        "--map",
+        metavar="PATH",
+        action="append",
+        default=[],
+        help="environment map file (repeatable); a local path, or (export/import "
+        "only) an s3://bucket/key URI",
+    )
+    parser.add_argument(
+        "--emit-map",
+        metavar="FILE",
+        default=None,
+        help="write a map of every literal discovered in TARGET (single target "
+        "only) instead of translating it, auto-naming Lambda references from "
+        "their ARN; merges into FILE if it already exists, so a loop of "
+        "invocations against the same FILE accumulates one shared map",
+    )
+    parser.add_argument(
+        "--prettify",
+        action="store_true",
+        help="also rewrite block positions into a readable layout",
+    )
+    parser.add_argument(
+        "--in-place",
+        action="store_true",
+        help="write the result back to its source (an upload, for a remote target)",
+    )
+    parser.add_argument(
+        "--output",
+        "-o",
+        metavar="FILE",
+        default=None,
+        help="write the result to this exact path (single target only)",
+    )
+    parser.add_argument(
+        "--output-dir",
+        metavar="DIR",
+        default=None,
+        help="write each result to DIR/STEM.json",
+    )
+    parser.add_argument(
+        "--stdout",
+        action="store_true",
+        help="emit the rewritten JSON to stdout instead of writing anywhere (single target only)",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="never write; exit 1 if any target would change (CI / pre-commit gate)",
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true", help="never write; report what would change"
+    )
+    parser.add_argument(
+        "--diff", action="store_true", help="print a unified diff of changes"
+    )
+    parser.add_argument(
+        "--no-backup",
+        action="store_true",
+        help="skip writing a .bak file (local targets only)",
+    )
+
+
+def build_connect_flow_parser() -> argparse.ArgumentParser:
+    """``connect-flow``'s parser: git-style subcommands, shared output flags,
+    long-form-only (no short flags anywhere)."""
+    parser = _ArgumentParser(
+        prog="connect-flow",
+        description="Promote Amazon Connect contact flow JSON between environments and "
+        "auto-arrange its layout, without changing behaviour - for local files and live "
+        "Connect instances alike.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"connect-flow {__version__}"
+    )
+    # Also accepted before the subcommand, aws-cli style (`connect-flow --profile
+    # p --region r list`), in addition to after it. argparse only applies a
+    # default when the namespace attribute isn't already set, so whichever
+    # position actually supplies a flag wins; the two placements are never in
+    # conflict with each other.
+    _add_common_output_arguments(parser)
+    subparsers = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    prettify_parser = subparsers.add_parser(
+        "prettify",
+        help="rewrite block positions into a readable layout (the core verb)",
+    )
+    _add_common_output_arguments(prettify_parser, suppress_defaults=True)
+    _add_prettify_arguments(prettify_parser)
+
+    copy_parser = subparsers.add_parser(
+        "copy",
+        help="promote a flow from --from to --to (1:1); a live --to shows the diff "
+        "and prompts before writing",
+    )
+    _add_common_output_arguments(copy_parser, suppress_defaults=True)
+    copy_parser.add_argument(
+        "--from",
+        dest="from_",
+        metavar="SOURCE",
+        required=True,
+        help="a local flow JSON file, '-' (stdin), a full ARN, or INSTANCE/NAME-OR-ID "
+        "(see docs/adr/0009-copy-verb.md for the disambiguation rule)",
+    )
+    copy_parser.add_argument(
+        "--to",
+        metavar="DEST",
+        required=True,
+        help="a local flow JSON file, a full ARN, or INSTANCE/NAME-OR-ID; a live --to is "
+        "written as a saved draft (add --publish to go live) after showing the diff "
+        "and prompting, or not written at all with --output/--stdout",
+    )
+    copy_parser.add_argument(
+        "--kind",
+        choices=["flow", "flow-module"],
+        default="flow",
+        help="resource kind addressed by an INSTANCE/NAME --from/--to value (default: flow)",
+    )
+    copy_parser.add_argument(
+        "--from-map",
+        metavar="PATH",
+        action="append",
+        default=[],
+        help="environment map (repeatable) normalising --from's real identifiers to "
+        "placeholders; a local path or s3://bucket/key URI",
+    )
+    copy_parser.add_argument(
+        "--to-map",
+        metavar="PATH",
+        action="append",
+        default=[],
+        help="environment map (repeatable) resolving placeholders to --to's real "
+        "identifiers; a local path or s3://bucket/key URI",
+    )
+    copy_parser.add_argument(
+        "--emit-map",
+        metavar="FILE",
+        default=None,
+        help="write a map of every literal discovered in --from instead of "
+        "copying, auto-naming ContactFlow/FlowModule/Queue/Lambda references "
+        "(a live --from name lookup, disabled by --no-auto-resolve); merges "
+        "into FILE if it already exists, so a loop of invocations against the "
+        "same FILE accumulates one shared map",
+    )
+    copy_parser.add_argument(
+        "--prettify",
+        action="store_true",
+        help="also rewrite block positions into a readable layout",
+    )
+    copy_parser.add_argument(
+        "--stage",
+        choices=["published", "saved"],
+        default=None,
+        help="which remote content to read/write (default: published for reads, "
+        "saved for writes)",
+    )
+    # A live --to is written by default (after a diff and a prompt), so --apply
+    # no longer gates anything. Kept as an accepted no-op rather than removed:
+    # it shipped in the help text and in ADR 0009's examples, and an unknown
+    # flag would abort a script that has it hard-coded, which is a worse
+    # outcome than one warning line. See docs/adr/0015-copy-writes-by-default.md.
+    copy_parser.add_argument("--apply", action="store_true", help=argparse.SUPPRESS)
+    emit_group = copy_parser.add_mutually_exclusive_group()
+    emit_group.add_argument(
+        "--output",
+        metavar="FILE",
+        default=None,
+        help="resolve against a live --to and write the result to FILE instead of "
+        "uploading it",
+    )
+    emit_group.add_argument(
+        "--stdout",
+        action="store_true",
+        help="resolve against a live --to and print the result instead of uploading it",
+    )
+    copy_parser.add_argument(
+        "--no-backup",
+        action="store_true",
+        help="skip writing a .bak file (local --to only)",
+    )
+    copy_parser.add_argument(
+        "--no-auto-resolve",
+        action="store_true",
+        help="don't carry sibling flow/module/queue references across by name "
+        "between two live instances; only --from-map/--to-map entries apply "
+        "(also disables --emit-map's live name lookup) - see "
+        "docs/adr/0013-copy-name-auto-resolution.md",
+    )
+    copy_parser.add_argument(
+        "--exit-code",
+        action="store_true",
+        help="with --output/--stdout, exit 1 if the destination would change, like "
+        "diff(1); without it a successful run exits 0 - see "
+        "docs/adr/0014-copy-preview-exit-code.md",
+    )
+    _add_remote_write_arguments(copy_parser)
+
+    normalize_parser = subparsers.add_parser(
+        "normalize",
+        help="offline: local files only, no AWS - translate identifiers via --map, either direction",
+    )
+    _add_common_output_arguments(normalize_parser, suppress_defaults=True)
+    normalize_parser.add_argument(
+        "targets", nargs="+", metavar="TARGET", help="local flow JSON file(s)"
+    )
+    _add_translate_common_arguments(normalize_parser)
+    normalize_parser.add_argument(
+        "--reverse",
+        action="store_true",
+        help="resolve placeholders to real values instead of normalising real values to placeholders",
+    )
+    normalize_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="proceed despite unresolved identifiers (warn instead of erroring)",
+    )
+
+    list_parser = subparsers.add_parser(
+        "list", help="list instances, or flows / flow modules within one (read-only)"
+    )
+    _add_common_output_arguments(list_parser, suppress_defaults=True)
+    list_parser.add_argument(
+        "--instance",
+        metavar="ID-OR-ALIAS",
+        default=None,
+        help="Connect instance id, or alias resolved via ListInstances (exact match); "
+        "omit to list instances instead",
+    )
+    _add_flow_arguments(
+        list_parser,
+        flow_help="describe this contact flow instead of listing (repeatable, but only "
+        "one flow may resolve in total): a bare id, a name (resolved via ListContactFlows "
+        "against --instance), a full ARN, or INSTANCE/NAME-OR-ID embedding its own instance",
+        module_help="describe this flow module instead of listing (repeatable, but only "
+        "one flow may resolve in total): a bare id, a name (resolved via "
+        "ListContactFlowModules against --instance), a full ARN, or INSTANCE/NAME-OR-ID "
+        "embedding its own instance",
+    )
+    kind_group = list_parser.add_mutually_exclusive_group()
+    kind_group.add_argument(
+        "--flows", action="store_true", help="list contact flows (default)"
+    )
+    kind_group.add_argument(
+        "--flow-modules", action="store_true", help="list flow modules"
+    )
+    list_parser.add_argument(
+        "--state",
+        choices=["ACTIVE", "ARCHIVED"],
+        default=None,
+        help="filter by resource state",
+    )
+
+    diff_parser = subparsers.add_parser(
+        "diff", help="semantic diff between two targets (local file and/or live ARN)"
+    )
+    _add_common_output_arguments(diff_parser, suppress_defaults=True)
+    diff_parser.add_argument(
+        "target_a",
+        metavar="TARGET_A",
+        help="a local flow JSON file, a full ARN, or INSTANCE/NAME-OR-ID "
+        "(see docs/adr/0009-copy-verb.md for the disambiguation rule)",
+    )
+    diff_parser.add_argument(
+        "target_b",
+        metavar="TARGET_B",
+        nargs="?",
+        default=None,
+        help="a local flow JSON file, a full ARN, or INSTANCE/NAME-OR-ID "
+        "(omit with --both-stages)",
+    )
+    # See docs/adr/0010-diff-instance-addressing.md: reuses copy's --kind
+    # rather than diff's own --instance/--flow/--flow-module flags.
+    diff_parser.add_argument(
+        "--kind",
+        choices=["flow", "flow-module"],
+        default="flow",
+        help="resource kind addressed by an INSTANCE/NAME-OR-ID TARGET_A/TARGET_B "
+        "value (default: flow)",
+    )
+    diff_parser.add_argument(
+        "--stage",
+        choices=["published", "saved"],
+        default=None,
+        help="which remote content to read for a remote target with no explicit "
+        ":$SAVED (or :SAVED) qualifier (default: published)",
+    )
+    diff_parser.add_argument(
+        "--both-stages",
+        action="store_true",
+        help="diff TARGET_A's saved draft against its published content - TARGET_A "
+        "must be a remote ARN, and TARGET_B must be omitted",
+    )
+    diff_parser.add_argument(
+        "--functional",
+        action="store_true",
+        help="compare only what the flow does at runtime - drop ActionMetadata, its "
+        "key order, Annotations and snapToGrid, which the console rewrites on every "
+        "save and which therefore differ between two snapshots of a flow nobody "
+        "edited; combine with --normalize-opaque to compare across instances",
+    )
+    diff_parser.add_argument(
+        "--normalize-opaque",
+        action="store_true",
+        help="replace ${...} templatefile placeholders and ARN-shaped literals with "
+        "<opaque> before comparing, so a local .tftpl can compare cleanly against live "
+        "content; for a remote target, also resolves a referenced ContactFlowId/"
+        "FlowModuleId/QueueId to its Name so the same sibling resource in a different "
+        "instance doesn't show as a diff - hides genuine wrong-reference changes, so "
+        "it's off by default",
+    )
+
+    lint_parser = subparsers.add_parser(
+        "lint",
+        help="structural checks: dangling transitions, unreachable actions, empty branches",
+    )
+    _add_common_output_arguments(lint_parser, suppress_defaults=True)
+    _add_multi_target_arguments(lint_parser)
+    lint_parser.add_argument(
+        "--stage",
+        choices=["published", "saved"],
+        default=None,
+        help="which remote content to check (default: published)",
+    )
+
+    digest_parser = subparsers.add_parser(
+        "digest", help="print each target's semantic digest"
+    )
+    _add_common_output_arguments(digest_parser, suppress_defaults=True)
+    _add_multi_target_arguments(digest_parser)
+    digest_parser.add_argument(
+        "--stage",
+        choices=["published", "saved"],
+        default=None,
+        help="which remote content to digest (default: published)",
+    )
+
+    return parser
+
+
+_DESTINATION_FLAGS = ("in_place", "output", "output_dir", "stdout", "check", "dry_run")
+
+
+def _validate_destination_args(
+    args: argparse.Namespace, target_count: int, *, allow_default_stdout: bool = False
+) -> str | None:
+    """Returns an error message, or None if args are fine. Shared by every
+    subcommand that writes somewhere (prettify, export, import, normalize) -
+    they all use the same mutually-exclusive destination flag set.
+
+    ``target_count`` is the *resolved* target count (positionals plus any
+    --instance/--flow desugaring), not len(args.targets) - a TARGET can
+    be entirely absent when --instance/--flow supplies it instead, and
+    checking the raw positional list would wrongly reject that combination
+    with --stdout/--output.
+
+    ``allow_default_stdout``: for prettify/export/normalize, no destination
+    flag at all with exactly one target is treated as ``--stdout`` rather
+    than an error - their result is inspected as often as written. This also
+    implies ``--quiet``, since the point is the content itself, not a report
+    about it; an explicit ``--stdout`` is unaffected and still reports
+    normally unless ``--quiet`` is passed too. ``import`` always writes
+    something real (a local destination or ``--to`` a live ARN), so it keeps
+    requiring an explicit destination flag. See
+    docs/adr/0005-default-to-stdout.md."""
+    given = [name for name in _DESTINATION_FLAGS if getattr(args, name)]
+    if not given:
+        if allow_default_stdout and target_count == 1:
+            args.stdout = True
+            args.quiet = (
+                True  # implicit stdout: the content itself is the point, not a report
+            )
+            return None
+        return (
+            "a destination is required: one of --in-place, --output FILE, "
+            "--output-dir DIR, --stdout, --check or --dry-run"
+        )
+    if len(given) > 1:
+        readable = ", ".join(f"--{n.replace('_', '-')}" for n in given)
+        return f"{readable} are mutually exclusive - pass exactly one destination"
+    if args.stdout and target_count != 1:
+        return "--stdout requires exactly one TARGET"
+    if args.output and target_count != 1:
+        return "--output FILE requires exactly one TARGET - use --output-dir DIR for more than one"
+    return None
+
+
+def _validate_prettify_args(args: argparse.Namespace, target_count: int) -> str | None:
+    error = _validate_destination_args(args, target_count, allow_default_stdout=True)
+    if error is not None:
+        return error
+    if args.render_dir is not None and not args.render:
+        return "--render-dir requires --render"
+    return None