connect-flow 0.1.1__tar.gz

connect_flow-0.1.1/.claude/settings.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "graphify hook-guard search"
+          }
+        ]
+      },
+      {
+        "matcher": "Read|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "graphify hook-guard read"
+          }
+        ]
+      }
+    ]
+  }
+}

connect_flow-0.1.1/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+uv.lock
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+*.bak
+graphify-out/

connect_flow-0.1.1/.gitlab-ci.yml

@@ -0,0 +1,37 @@
+default:
+  image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+
+stages:
+  - test
+  - publish
+
+test:
+  stage: test
+  script:
+    # pygraphviz's wheel needs several system shared libs (expat, glib,
+    # ...) that bookworm-slim omits; installing the graphviz apt package
+    # pulls its whole correct dependency tree instead of chasing each
+    # missing .so one at a time.
+    - apt-get update && apt-get install -y --no-install-recommends graphviz
+    - uv sync --all-extras
+    - uv run pytest
+
+publish:
+  stage: publish
+  rules:
+    - if: $CI_COMMIT_TAG
+  # PyPI trusted publishing (no stored secret): this job requests a short-
+  # lived OIDC token scoped to `pypi`; twine >=6.0 auto-detects it via the
+  # PYPI_ID_TOKEN env var and exchanges it for a PyPI API token itself when
+  # no credentials are passed - see https://docs.pypi.org/trusted-publishers/
+  # using-a-publisher/. One-time setup: on pypi.org -> Your projects ->
+  # connect-flow -> Settings -> Publishing, add a GitLab publisher for
+  # namespace `mludvig`, project `connect-flow`, workflow filename
+  # `.gitlab-ci.yml` (a "pending" publisher can be added before the project
+  # exists on PyPI at all, for the very first release).
+  id_tokens:
+    PYPI_ID_TOKEN:
+      aud: pypi
+  script:
+    - uv build
+    - uvx twine upload dist/*

connect_flow-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,39 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-json
+      - id: check-yaml
+      - id: check-xml
+      - id: detect-aws-credentials
+        args: ["--allow-missing-credentials"]
+      - id: mixed-line-ending
+        args: ["--fix", "auto"]
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]
+        pass_filenames: true
+
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types: [python]
+        pass_filenames: true
+
+      #- id: mypy
+      #  name: mypy
+      #  entry: uv run mypy src/
+      #  language: system
+      #  types: [python]
+      #  pass_filenames: false

connect_flow-0.1.1/.pre-commit-hooks.yaml

@@ -0,0 +1,15 @@
+# Hook definitions published FOR OTHER REPOS to consume.
+#
+# The audience here is a repo that stores Amazon Connect contact flow JSON
+# and wants it kept in the neutral layout.
+#
+# Consumers should narrow `files:` to wherever their flow JSON actually
+# lives — the default below matches every .json in the repo.
+
+- id: connect-flow
+  name: connect-flow
+  description: Auto-arrange Amazon Connect contact flow JSON without changing behaviour
+  entry: connect-flow
+  language: python
+  files: \.json$
+  args: [prettify, --check]

connect_flow-0.1.1/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-09-10
+
+- `pygraphviz` is now an optional `[graphviz]` extra instead of a required
+  dependency - `lint`, `diff` and `digest` no longer need it installed.
+- Added PyPI release metadata (classifiers, license files, project URLs).
+- Added a GitLab CI pipeline that runs tests on every push and publishes to
+  PyPI via trusted publishing on tagged commits.
+
+## [0.1.0] - 2026-09-03
+
+Initial release.

connect_flow-0.1.1/CLAUDE.md

@@ -0,0 +1,127 @@
+# CLAUDE.md
+
+Guidance for working on this repository.
+
+## What this is
+
+A standalone CLI that rewrites Amazon Connect contact flow JSON block
+*positions* into a readable auto-layout, guaranteeing no behavioural change.
+See `README.md` for usage and `docs/design.md`, `docs/data-model.md`,
+`docs/safety.md` for the reasoning — read those before changing `writer.py`,
+`digest.py`, or `graph.py`, since each encodes a specific, previously
+measured or tested invariant, not an arbitrary choice.
+
+## The one rule that matters most
+
+`digest.py`'s semantic digest is the safety boundary. Any change to
+`writer.py`, `flow.py`, or `digest.py` itself must preserve: digests are
+invariant under any position/geometry change, and are sensitive to every
+other field. If you're not sure whether a change preserves this, add a test
+in `tests/test_digest.py` proving it before proceeding, not after.
+
+## Never re-serialise a flow file
+
+`writer.py` patches position literals via regex, in place, and must never
+route through `json.dumps` on a whole file. See `docs/safety.md` for why —
+in short, it destroys the property that a rewrite's diff is exactly the
+coordinates that changed.
+
+## Edge order into `dot` must never be re-sorted
+
+`layout.py` feeds `graph.edges` to `pygraphviz` in the exact order
+`graph.py` produced them (i.e., in designer port order), because
+`ordering="out"` depends on insertion order as each node's port order. This
+has regressed once already from an innocuous-looking `sorted(...)` — see the
+comment in `layout.py` and `docs/design.md`'s "Edge order and weight" section
+before touching this.
+
+## Test data must stay synthetic
+
+This repo is open source and must never contain real customer data,
+identifiers, or references to any specific deployment. Everything under
+`tests/fixtures/` is hand-authored from scratch with throwaway UUIDs — see
+`tests/fixtures/README.md`. Do not add a fixture derived from, or copy any
+fragment of, a real flow export. `tests/test_corpus.py` exists precisely so
+that real-corpus validation can happen locally (via `$CONNECT_FLOW_CORPUS`)
+without ever needing to commit that corpus.
+
+This rule isn't limited to fixtures: help text, error messages, docstrings,
+version/snapshot descriptions, and doc examples are all committed text too,
+and all of them handle real ARNs, account ids, instance ids and resource
+names at runtime. Every example anywhere in this repo uses the one
+placeholder set (`11111111-1111-…` instance, `22222222-…`/`33333333-…`
+resource, account `000000000000`) — never a value copied from a real
+console session or CLI run, even a redacted-looking one.
+
+## The CLI is six modules, not one
+
+`cli.py` is the verb dispatch and the five verb runners only. The rest of
+the CLI is layered beneath it, and imports flow one way — never back into
+`cli.py`, which is what keeps the graph acyclic. `resolve.py` and `load.py`
+are a parallel pair, not a chain — neither imports the other:
+
+```
+args.py  ->  resolve.py  ->  remote_write.py  ->  pipeline.py  ->  cli.py
+             load.py     ---------^
+```
+
+- `args.py` — parser construction and cross-flag validation.
+- `resolve.py` — strings to regions, clients, instance ids, resolved targets.
+  Never touches a flow's contents.
+- `load.py` — an already-resolved target to a loaded `Flow`, wherever it
+  lives; the only code in the CLI layer that reads one. See
+  `docs/adr/0012-load-module-split.md` for why this is split from `resolve.py`
+  rather than folded into it.
+- `remote_write.py` — confirm and upload; the only code that mutates a live
+  instance, kept isolated so it can be audited alone.
+- `pipeline.py` — the shared transform-and-emit engine behind `prettify`,
+  `copy` and `normalize`.
+
+New CLI code goes in the layer it belongs to, not in `cli.py` by default —
+see `docs/adr/0011-cli-module-split.md` for why the file was split. Exit
+codes come from `exits.py` directly in every module; `cli.py` only
+re-exports them (along with `main_connect_flow`,
+`build_connect_flow_parser` and `_classify_copy_endpoint`) so the console
+script, `__main__.py` and the tests address one unchanged name.
+
+## `boto3` stays contained to `aws.py`
+
+`src/connect_flow/aws.py` is the *only* module allowed to import
+`boto3` or `botocore`. `boto3` is a required dependency (see
+`docs/adr/0003-boto3-required-dependency.md` for why the optional `[aws]`
+extra was dropped), but the containment still matters: `aws.py`'s job is to
+be the only place that ever sees a `botocore.ClientError`, translating every
+AWS failure into `AwsError` before anything above it can observe a botocore
+type — and to keep `resolve.py`, `load.py`, `cli.py`, `targets.py`, `arn.py`
+free of credential/region resolution details that belong to boto3, not to
+this tool's own logic. `resolve.py` is where region and client resolution
+now lives, so it is the module most likely to tempt you — it calls
+`aws.get_default_region()`/`aws.client()` and must keep doing so rather
+than reaching past them. `load.py` constructs `aws.RemoteFlowClient`
+instances from a factory it's handed, for the same reason — it must keep
+going through `aws.py` rather than reaching past it. If
+you're adding remote-target code anywhere else and find yourself reaching
+for `boto3` directly, that's a sign the operation belongs in `aws.py`
+instead.
+
+## Commands
+
+```
+uv sync
+uv run pytest
+uv run connect-flow --version
+```
+
+No linter or type-checker is currently wired in; keep changes consistent
+with the existing style (dataclasses, `from __future__ import annotations`,
+docstrings that explain *why*, not what).
+
+## graphify
+
+This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
+
+Rules:
+- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
+- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
+- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).

connect_flow-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 connect-flow contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.