patchshuttle 0.1.0a5__tar.gz → 0.1.0a6__tar.gz

{patchshuttle-0.1.0a5 → patchshuttle-0.1.0a6}/.github/workflows/ci.yml

@@ -47,14 +47,46 @@ jobs:
       - name: Check formatting
         run: python -m black --check src tests tools
       - name: Run tests with branch coverage
-        run: |
-          python -m coverage erase
-          python -m coverage run -m pytest -q
-          python -m coverage report --fail-under=100
+        run: python -m coverage run -m pytest -q
+      - name: Require full branch coverage
+        run: python -m coverage report --fail-under=100
+
+  postgres:
+    name: Django / PostgreSQL 16
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_DB: patchshuttle_test
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: disposable-ci-password
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: actions/setup-python@v7.0.0
+        with:
+          python-version: "3.12"
+      - name: Install Django adapter and PostgreSQL driver
+        run: python -m pip install -e ".[django]" "psycopg[binary]>=3.2,<4"
+      - name: Check migration lifecycle and cross-connection lock
+        env:
+          PSH_PG_DATABASE: patchshuttle_test
+          PSH_PG_USER: postgres
+          PSH_PG_PASSWORD: disposable-ci-password
+          PSH_PG_PORT: "5432"
+        run: python tools/django_postgres_smoke.py
 
   package:
     name: Build and smoke-test distributions
-    needs: test
+    needs: [test, postgres]
     runs-on: ubuntu-24.04
     timeout-minutes: 20
     steps:

{patchshuttle-0.1.0a5 → patchshuttle-0.1.0a6}/CHANGELOG.md

@@ -3,7 +3,30 @@
 All notable changes to PatchShuttle are recorded in this file. The project
 uses semantic versioning, including Python-compatible pre-release versions.
 
-## Unreleased
+## 0.1.0a6 - 2026-10-21
+
+### Added
+
+- Guarded `read_imports`, `ensure_import` and `remove_import` with alias-aware AST matching, comment preservation and binding checks.
+
+- Optional authenticated MCP history server for ChatGPT, scoped to one workspace and OAuth subject.
+- Optional Django migration command with hashed plans, database locks, pre/post checks, explicit reversals and separate recovery journals.
+- Guarded `move_range` and `move_symbol` source transfers between files,
+  including destination fingerprints, structural validation, Python constructors,
+  and shared transaction rollback.
+- Guarded `move_file` with destination absence checks, byte/mode preservation,
+  explicit deleted-file reporting, and automatic and manual rollback.
+
+- Optional AST guards for `replace_symbol`, with hashes and Python version
+  reported by `read_symbol`, replacement declaration validation and compile
+  validation. Existing text-only job serialization remains compatible.
+
+### Changed
+
+- Formatter child interpreters and Black preflight explicitly enable Python
+  UTF-8 mode, including under isolated execution.
+
+See `docs/NEXT_RELEASE.md` for implemented scope and remaining release work.
 
 ## 0.1.0a5 - 2026-08-28
 

patchshuttle-0.1.0a5/README.md → patchshuttle-0.1.0a6/PKG-INFO

@@ -1,3 +1,47 @@
+Metadata-Version: 2.4
+Name: patchshuttle
+Version: 0.1.0a6
+Summary: Local, auditable patch workflows for AI-assisted software development
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,automation,cli,development-tools,patch
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: black<27,>=24
+Requires-Dist: click<9,>=8.1
+Requires-Dist: filelock<4,>=3.30
+Requires-Dist: isort<7,>=5.13
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: ruff<1,>=0.16
+Requires-Dist: tomli<3,>=2; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: django<7,>=5.2; extra == 'dev'
+Requires-Dist: mcp<2,>=1.30; extra == 'dev'
+Requires-Dist: pyjwt[crypto]<3,>=2.10; extra == 'dev'
+Requires-Dist: pytest-cov<8,>=5; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: twine<7,>=6.1; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django<7,>=5.2; extra == 'django'
+Provides-Extra: html
+Requires-Dist: djlint<2,>=1.44; extra == 'html'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.30; extra == 'mcp'
+Requires-Dist: pyjwt[crypto]<3,>=2.10; extra == 'mcp'
+Description-Content-Type: text/markdown
+
 # PatchShuttle
 
 PatchShuttle is intended to provide local, auditable patch workflows for
@@ -6,7 +50,7 @@ describes a small job, the user reviews and runs it locally, and PatchShuttle
 records the result for the next iteration.
 
 > [!IMPORTANT]
-> PatchShuttle is alpha software. Version `0.1.0a5` implements the complete
+> PatchShuttle is alpha software. Version `0.1.0a6` implements the complete
 > local v0.1 workflow. It executes bounded read-only
 > audits, approved patch transactions, and approved one-pass verification jobs
 > under a project lock. Patch jobs retain backups, run controlled checks, apply
@@ -63,7 +107,7 @@ After publication, install the exact alpha release from PyPI:
 ```bash
 python -m venv .venv
 python -m pip install --upgrade pip
-python -m pip install "patchshuttle==0.1.0a5"
+python -m pip install "patchshuttle==0.1.0a6"
 ```
 
 For development from a local checkout:
@@ -76,7 +120,7 @@ To enable opt-in HTML template linting in an installed release, install the
 `html` extra:
 
 ```bash
-python -m pip install "patchshuttle[html]==0.1.0a5"
+python -m pip install "patchshuttle[html]==0.1.0a6"
 ```
 
 For a local development checkout, install both development and HTML extras:
@@ -478,6 +522,13 @@ rejects missing, duplicate, syntactically invalid, or stale targets, and does
 not use fuzzy relocation or automatic line shifting. Exact desired symbol
 content is an idempotent `NO_CHANGE`.
 
+The optional `expected_ast_sha256` guard uses the structural hash from
+`read_symbol` to tolerate formatting changes. It ignores ordinary comments,
+includes docstrings and decorators, and is scoped to the reported Python minor
+version. Supply the text hash too when comments must be guarded. AST-guarded
+replacements retain the name and kind and undergo compile and resolution
+validation. See [next-release work](docs/NEXT_RELEASE.md) for current scope.
+
 For a supported plan, the implemented sequence is:
 
 1. validate the workspace lock file and acquire a non-blocking cross-platform
@@ -840,7 +891,7 @@ python -m coverage report --fail-under=100
 python -m build
 python -m twine check dist/*
 python tools/release_checks.py dist
-python tools/wheel_smoke.py dist/patchshuttle-0.1.0a5-py3-none-any.whl --version 0.1.0a5
+python tools/wheel_smoke.py dist/patchshuttle-0.1.0a6-py3-none-any.whl --version 0.1.0a6
 ```
 
 The `0.1.0a2`, `0.1.0a3`, and `0.1.0a4` alpha releases each passed the
@@ -971,3 +1022,61 @@ model, or project.
 ## License
 
 PatchShuttle is licensed under the MIT License.
+
+
+## Guarded source transfers
+
+- `move_range`: `path`, `start_line`, `end_line`, source `expected_content`
+  and/or `expected_sha256`, `destination`, `destination_line` and
+  `expected_destination_sha256`.
+- `move_symbol`: `path`, `symbol`, `expected_ast_sha256`, `destination`,
+  `expected_destination_sha256` and optional `destination_class`.
+
+Destination hashes cover simulated raw bytes; source range hashes cover
+canonical LF/UTF-8 text. Destinations must exist or be created earlier in the
+same job. Range insertion is before the 1-based destination line; EOF+1 appends.
+Symbol insertion appends at module scope or to the named class. Both files are
+validated and participate in the same backup/check/rollback transaction.
+
+Same-file transfers, case-only path differences, duplicate destination names,
+closure extraction, class-bound super/private-name moves and multiline-string
+reindentation are rejected. Imports and callers are not automatically rewritten;
+include explicit edits and focused project checks. These actions move source
+content and leave the source file present. Whole-file moves are separate work.
+
+
+## Whole-file transfers
+
+`move_file` moves an existing supported text file to an absent destination.
+Supply `path`, `destination`, and `expected_sha256` of the original raw bytes.
+The transaction preserves original bytes and permissions, creates missing
+parent directories, and reports the source in `deleted_files`. Formatters and
+checks target the surviving destination. Add explicit import and caller edits
+when moving Python modules; imports are not automatically rewritten.
+
+The source and destination must not have been touched earlier in the job.
+Subsequent edits to the destination are supported. Case-only moves, chains,
+swaps, binary files and reuse of the vacated path are currently rejected.
+A failed check restores the source and removes the destination. Manual rollback
+also verifies the applied state and refuses to overwrite a recreated source.
+
+
+## Optional integrations
+
+- `patchshuttle[mcp]`: authenticated, read-only history retrieval for ChatGPT. See [setup and deployment limits](docs/CHATGPT_INTEGRATION.md).
+- `patchshuttle[django]`: reviewed migration plans, explicit execution/reversal, and a separate recovery journal. See [Django workflow](docs/DJANGO_MIGRATIONS.md).
+
+
+## Structural editing and optional adapters in 0.1.0a6
+
+Use `read_symbol` AST hashes for guarded class/method replacements; use
+`read_imports`, `ensure_import`, and `remove_import` for structural imports.
+`move_file`, `move_range`, and `move_symbol` support explicit refactoring plans
+with shared checks and rollback. Imports and callers are not inferred.
+See [scope and examples](docs/NEXT_RELEASE.md).
+
+Optional [ChatGPT history retrieval](docs/CHATGPT_INTEGRATION.md) uses an
+owner-configured authenticated MCP server (`patchshuttle[mcp]`).
+Optional [Django migrations](docs/DJANGO_MIGRATIONS.md) provide reviewed plans,
+locks and recovery journals (`patchshuttle[django]`). A live ChatGPT deployment
+requires the owner's HTTPS endpoint and OAuth configuration.

patchshuttle-0.1.0a5/PKG-INFO → patchshuttle-0.1.0a6/README.md

@@ -1,40 +1,3 @@
-Metadata-Version: 2.4
-Name: patchshuttle
-Version: 0.1.0a5
-Summary: Local, auditable patch workflows for AI-assisted software development
-License-Expression: MIT
-License-File: LICENSE
-Keywords: ai,automation,cli,development-tools,patch
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Requires-Dist: black<27,>=24
-Requires-Dist: click<9,>=8.1
-Requires-Dist: filelock<4,>=3.30
-Requires-Dist: isort<7,>=5.13
-Requires-Dist: pydantic<3,>=2.6
-Requires-Dist: pyyaml<7,>=6
-Requires-Dist: ruff<1,>=0.16
-Requires-Dist: tomli<3,>=2; python_version < '3.11'
-Provides-Extra: dev
-Requires-Dist: build<2,>=1.2; extra == 'dev'
-Requires-Dist: django<7,>=5.2; extra == 'dev'
-Requires-Dist: pytest-cov<8,>=5; extra == 'dev'
-Requires-Dist: pytest<10,>=8; extra == 'dev'
-Requires-Dist: twine<7,>=6.1; extra == 'dev'
-Provides-Extra: html
-Requires-Dist: djlint<2,>=1.44; extra == 'html'
-Description-Content-Type: text/markdown
-
 # PatchShuttle
 
 PatchShuttle is intended to provide local, auditable patch workflows for
@@ -43,7 +6,7 @@ describes a small job, the user reviews and runs it locally, and PatchShuttle
 records the result for the next iteration.
 
 > [!IMPORTANT]
-> PatchShuttle is alpha software. Version `0.1.0a5` implements the complete
+> PatchShuttle is alpha software. Version `0.1.0a6` implements the complete
 > local v0.1 workflow. It executes bounded read-only
 > audits, approved patch transactions, and approved one-pass verification jobs
 > under a project lock. Patch jobs retain backups, run controlled checks, apply
@@ -100,7 +63,7 @@ After publication, install the exact alpha release from PyPI:
 ```bash
 python -m venv .venv
 python -m pip install --upgrade pip
-python -m pip install "patchshuttle==0.1.0a5"
+python -m pip install "patchshuttle==0.1.0a6"
 ```
 
 For development from a local checkout:
@@ -113,7 +76,7 @@ To enable opt-in HTML template linting in an installed release, install the
 `html` extra:
 
 ```bash
-python -m pip install "patchshuttle[html]==0.1.0a5"
+python -m pip install "patchshuttle[html]==0.1.0a6"
 ```
 
 For a local development checkout, install both development and HTML extras:
@@ -515,6 +478,13 @@ rejects missing, duplicate, syntactically invalid, or stale targets, and does
 not use fuzzy relocation or automatic line shifting. Exact desired symbol
 content is an idempotent `NO_CHANGE`.
 
+The optional `expected_ast_sha256` guard uses the structural hash from
+`read_symbol` to tolerate formatting changes. It ignores ordinary comments,
+includes docstrings and decorators, and is scoped to the reported Python minor
+version. Supply the text hash too when comments must be guarded. AST-guarded
+replacements retain the name and kind and undergo compile and resolution
+validation. See [next-release work](docs/NEXT_RELEASE.md) for current scope.
+
 For a supported plan, the implemented sequence is:
 
 1. validate the workspace lock file and acquire a non-blocking cross-platform
@@ -877,7 +847,7 @@ python -m coverage report --fail-under=100
 python -m build
 python -m twine check dist/*
 python tools/release_checks.py dist
-python tools/wheel_smoke.py dist/patchshuttle-0.1.0a5-py3-none-any.whl --version 0.1.0a5
+python tools/wheel_smoke.py dist/patchshuttle-0.1.0a6-py3-none-any.whl --version 0.1.0a6
 ```
 
 The `0.1.0a2`, `0.1.0a3`, and `0.1.0a4` alpha releases each passed the
@@ -1008,3 +978,61 @@ model, or project.
 ## License
 
 PatchShuttle is licensed under the MIT License.
+
+
+## Guarded source transfers
+
+- `move_range`: `path`, `start_line`, `end_line`, source `expected_content`
+  and/or `expected_sha256`, `destination`, `destination_line` and
+  `expected_destination_sha256`.
+- `move_symbol`: `path`, `symbol`, `expected_ast_sha256`, `destination`,
+  `expected_destination_sha256` and optional `destination_class`.
+
+Destination hashes cover simulated raw bytes; source range hashes cover
+canonical LF/UTF-8 text. Destinations must exist or be created earlier in the
+same job. Range insertion is before the 1-based destination line; EOF+1 appends.
+Symbol insertion appends at module scope or to the named class. Both files are
+validated and participate in the same backup/check/rollback transaction.
+
+Same-file transfers, case-only path differences, duplicate destination names,
+closure extraction, class-bound super/private-name moves and multiline-string
+reindentation are rejected. Imports and callers are not automatically rewritten;
+include explicit edits and focused project checks. These actions move source
+content and leave the source file present. Whole-file moves are separate work.
+
+
+## Whole-file transfers
+
+`move_file` moves an existing supported text file to an absent destination.
+Supply `path`, `destination`, and `expected_sha256` of the original raw bytes.
+The transaction preserves original bytes and permissions, creates missing
+parent directories, and reports the source in `deleted_files`. Formatters and
+checks target the surviving destination. Add explicit import and caller edits
+when moving Python modules; imports are not automatically rewritten.
+
+The source and destination must not have been touched earlier in the job.
+Subsequent edits to the destination are supported. Case-only moves, chains,
+swaps, binary files and reuse of the vacated path are currently rejected.
+A failed check restores the source and removes the destination. Manual rollback
+also verifies the applied state and refuses to overwrite a recreated source.
+
+
+## Optional integrations
+
+- `patchshuttle[mcp]`: authenticated, read-only history retrieval for ChatGPT. See [setup and deployment limits](docs/CHATGPT_INTEGRATION.md).
+- `patchshuttle[django]`: reviewed migration plans, explicit execution/reversal, and a separate recovery journal. See [Django workflow](docs/DJANGO_MIGRATIONS.md).
+
+
+## Structural editing and optional adapters in 0.1.0a6
+
+Use `read_symbol` AST hashes for guarded class/method replacements; use
+`read_imports`, `ensure_import`, and `remove_import` for structural imports.
+`move_file`, `move_range`, and `move_symbol` support explicit refactoring plans
+with shared checks and rollback. Imports and callers are not inferred.
+See [scope and examples](docs/NEXT_RELEASE.md).
+
+Optional [ChatGPT history retrieval](docs/CHATGPT_INTEGRATION.md) uses an
+owner-configured authenticated MCP server (`patchshuttle[mcp]`).
+Optional [Django migrations](docs/DJANGO_MIGRATIONS.md) provide reviewed plans,
+locks and recovery journals (`patchshuttle[django]`). A live ChatGPT deployment
+requires the owner's HTTPS endpoint and OAuth configuration.

{patchshuttle-0.1.0a5 → patchshuttle-0.1.0a6}/SPEC_V0_1.md

@@ -863,7 +863,9 @@ Fields:
 
 - `path`: required existing Python text file;
 - `symbol`: required dotted class, function, method, or nested-symbol name;
-- `expected_sha256`: required canonical hash returned by `read_symbol`;
+- `expected_sha256`: optional canonical text hash returned by `read_symbol`;
+- `expected_ast_sha256`: optional structural hash returned by `read_symbol`;
+- at least one hash is required; when both are supplied both must match;
 - `new_content`: required complete replacement source.
 
 Planning parses the current sequential simulated file without importing it,
@@ -874,6 +876,15 @@ desired symbol content returns `NO_CHANGE`. Execution publishes the planner's
 final file bytes through the normal guarded transaction, backup, check,
 workspace-comparison, and rollback lifecycle.
 
+With `expected_ast_sha256`, whitespace and ordinary comment differences do not
+invalidate the guard. Hashes include AST fields but exclude source positions,
+and are scoped to the `ast_python` major/minor version reported by the audit.
+Docstrings, decorators and annotations remain part of the AST. The replacement
+must be one declaration of the same name and kind, the final module must compile
+without execution, and the qualified target must still resolve uniquely.
+Use the text guard as well when comment changes must invalidate the job.
+Old text-guarded jobs retain their normalized serialization and registry hash.
+
 ### 13.5 `insert_before`
 
 Fields:
@@ -2085,3 +2096,76 @@ unless this specification is explicitly revised:
 - logs are plain UTF-8 text with timestamped names and an AI handoff block;
 - implementation begins with tests for the contract before completing the
   execution engine.
+
+
+## Guarded source transfers
+
+- `move_range`: `path`, `start_line`, `end_line`, source `expected_content`
+  and/or `expected_sha256`, `destination`, `destination_line` and
+  `expected_destination_sha256`.
+- `move_symbol`: `path`, `symbol`, `expected_ast_sha256`, `destination`,
+  `expected_destination_sha256` and optional `destination_class`.
+
+Destination hashes cover simulated raw bytes; source range hashes cover
+canonical LF/UTF-8 text. Destinations must exist or be created earlier in the
+same job. Range insertion is before the 1-based destination line; EOF+1 appends.
+Symbol insertion appends at module scope or to the named class. Both files are
+validated and participate in the same backup/check/rollback transaction.
+
+Same-file transfers, case-only path differences, duplicate destination names,
+closure extraction, class-bound super/private-name moves and multiline-string
+reindentation are rejected. Imports and callers are not automatically rewritten;
+include explicit edits and focused project checks. These actions move source
+content and leave the source file present. Whole-file moves are separate work.
+
+
+## Whole-file transfers
+
+`move_file` moves an existing supported text file to an absent destination.
+Supply `path`, `destination`, and `expected_sha256` of the original raw bytes.
+The transaction preserves original bytes and permissions, creates missing
+parent directories, and reports the source in `deleted_files`. Formatters and
+checks target the surviving destination. Add explicit import and caller edits
+when moving Python modules; imports are not automatically rewritten.
+
+The source and destination must not have been touched earlier in the job.
+Subsequent edits to the destination are supported. Case-only moves, chains,
+swaps, binary files and reuse of the vacated path are currently rejected.
+A failed check restores the source and removes the destination. Manual rollback
+also verifies the applied state and refuses to overwrite a recreated source.
+
+
+## Structural import edits
+
+`read_imports` accepts `path` and optional `max_bytes`. It reports top-level
+imports, `imports_ast_sha256`, and `ast_python`. The hash ignores formatting
+and comments, includes alias names and order, and is Python-minor-specific.
+Nested/conditional imports are not selected. Use the same interpreter for
+inspection and planning.
+
+`ensure_import` and `remove_import` require `path`, `statement` and
+`expected_imports_ast_sha256`. The statement must be exactly one Python
+`import` or `from ... import ...` with one alias, optionally renamed. Relative
+imports are supported. Star requests and ambiguous duplicate matches fail.
+The guard is always checked, including for already-present/absent imports.
+
+```yaml
+- ensure_import:
+    path: services/offers.py
+    statement: from .pricing import calculate_price
+    expected_imports_ast_sha256: "<64 hex digits from read_imports>"
+```
+
+An existing alias in a multi-alias import satisfies `ensure_import` without
+rewriting that line. Removal from a multi-alias import requires a separately
+reviewed rewrite. Removal retains comments, including comments inside a
+parenthesized import. Shared semicolon lines are rejected when editing them.
+Insertion preserves headers, the module docstring and future-import ordering.
+Existing bindings are checked conservatively across scopes; a conflicting
+local name may therefore require a separately reviewed edit too. The resulting
+module is compiled without importing or executing it.
+
+Unrelated source remains intact before the normal scoped formatter phase.
+Neither action rewrites callers, proves runtime compatibility, nor infers
+imports when moving files or symbols. A sequence of import edits needs the
+hash of each simulated intermediate import set, or separate audited jobs.

patchshuttle-0.1.0a6/docs/CHATGPT_INTEGRATION.md

@@ -0,0 +1,54 @@
+# Read PatchShuttle results from ChatGPT
+
+The optional MCP server exposes `history_list`, `history_latest` and
+`history_show` for one explicitly selected workspace. It does not expose job
+execution, database execution, raw log downloads or arbitrary filesystem reads.
+Returned project text is untrusted data, not instructions.
+
+Install `patchshuttle[mcp]`. Create an owner-controlled JSON configuration
+outside job content, replacing every example value:
+
+```json
+{
+  "issuer": "https://identity.example/",
+  "jwks_url": "https://identity.example/.well-known/jwks.json",
+  "resource_url": "https://history.example/mcp",
+  "subject": "your-exact-OAuth-subject",
+  "port": 8765
+}
+```
+
+Start with `patchshuttle-mcp --workspace /absolute/project --config /absolute/mcp.json`.
+The process binds only `127.0.0.1`. Put it behind your HTTPS reverse proxy and
+forward `/mcp` and `/.well-known/oauth-protected-resource/mcp` to port 8765.
+Keep Authorization and Host headers intact. Do not expose an unauthenticated
+alternate listener. The resource URL must end in the exact `/mcp` path.
+
+Use an established OAuth authorization server with discovery, authorization-code
+and PKCE support, and ChatGPT-compatible client registration (CIMD or DCR, or
+configured static client credentials). Configure audience to the exact resource
+URL and issue the `patchshuttle:history:read` scope to the configured subject.
+The resource server accepts RS256/ES256 JWT access tokens only and validates
+signature, expiry, issuer, audience, scope and the exact subject. It is not an
+OAuth authorization server; opaque tokens/introspection are not implemented.
+No access tokens or signing secrets belong in patch jobs or this configuration.
+
+In ChatGPT's custom MCP connection settings, supply the HTTPS MCP URL and
+configure OAuth. Install/select the resulting plugin and ask for the latest
+PatchShuttle result. Availability and the actual linking flow depend on the
+account/workspace. A live connection to the user's deployment is not established
+by installing this Python package.
+
+Local validation covers signed tokens, rejected claims/signatures, protected
+resource discovery, HTTP authorization and history reads. It does not constitute
+an end-to-end ChatGPT/OAuth-provider deployment test. The existing history
+redaction remains best effort; authenticated access can reveal project details.
+
+Official setup and authorization references:
+
+- https://developers.openai.com/api/docs/guides/custom-mcp-server
+- https://developers.openai.com/plugins/build/auth
+- https://developers.openai.com/api/docs/guides/secure-mcp-tunnels
+
+A Secure MCP Tunnel is another documented transport option, but this package's
+initial configuration and local tests target an HTTPS reverse-proxy deployment.

patchshuttle-0.1.0a6/docs/DJANGO_MIGRATIONS.md

@@ -0,0 +1,83 @@
+# Controlled Django migrations
+
+Install `patchshuttle[django]` in the project's interpreter and add
+`"patchshuttle.django_app"` to the owner's `INSTALLED_APPS`. The adapter has no
+models and adds no migration of its own. Initialize a PatchShuttle workspace
+and run the management command from the Django project as usual.
+
+Preview an exact target (prefix matching is deliberately unsupported):
+
+```bash
+python manage.py patchshuttle_migrate orders 0007_add_status --workspace . --database default
+```
+
+The JSON plan contains ordered operations, direction, atomicity, declared
+reversibility, migration-file checksums, current applied migrations and a database
+fingerprint. Credentials come from Django settings and are not written into the
+plan. Planning loads trusted Django project/migration code and reads database
+state; the adapter does not apply schema operations during preview. Application
+startup hooks remain project code and may have their own effects.
+
+Review the plan and prepare a tested database backup/recovery procedure. Apply
+using the exact returned SHA-256 and a non-secret reference to that procedure:
+
+```bash
+python manage.py patchshuttle_migrate orders 0007_add_status --workspace . --database default --apply --expected-plan <sha256> --recovery-reference <backup-or-recovery-record>
+```
+
+The reference records the owner's recovery preparation; PatchShuttle does not
+create or verify the backup. A workspace lock and database lock are held while
+rechecking the plan, running Django checks, applying migrations and verifying
+both the exact applied set and unchanged migration sources. System checks run
+before and after migration. Add domain-specific checks to Django's check
+framework; model checks alone do not validate business data.
+
+PostgreSQL uses a session-level advisory lock shared by cooperating adapter
+processes in that database. Persistent SQLite uses a companion file lock.
+Ordinary `manage.py migrate`, other applications and manual SQL do not observe
+these locks. Use one canonical workspace/journal for each database's migration
+operations. PostgreSQL connection poolers must preserve the same server session
+for the operation; transaction-pooling mode is not supported.
+
+Initial limits: PostgreSQL and persistent SQLite, autocommit connections,
+transactional DDL and atomic migrations. In-memory/URI SQLite, other backends,
+non-atomic migrations, unresolved graph conflicts and squashed replacements
+are rejected. Migration checksums cover migration source files, not imported
+helper implementations or arbitrary application dependencies. Keep the deployed
+code immutable during planning/execution.
+
+## Failure and recovery
+
+Records are separate from filesystem patch backups, under
+`patches/state/django-migrations`. An exclusive, flushed `*.start.json` precedes
+migration execution; a separate `*.result.json` records success or failure.
+An unfinished start record or `FAILED_REVIEW_REQUIRED` blocks another execution.
+The adapter does not automatically retry an interrupted operation or reverse
+already applied migrations. A multi-migration plan can partially succeed before
+failure even if each individual migration is atomic. Python migration code may
+also have external effects that database transactions cannot undo.
+
+After independently inspecting/recovering the database, generate a fresh plan
+and explicitly record owner reconciliation:
+
+```bash
+python manage.py patchshuttle_migrate orders 0007_add_status --workspace . --database default --reconcile <attempt-id> --expected-plan <fresh-sha256> --recovery-reference <verified-recovery-record>
+```
+
+This appends an acknowledgement. It does not repair, replay or prove the
+correctness of database contents. Corrupt journals must be investigated;
+do not delete them just to bypass an unresolved attempt.
+
+## Explicit database reversal
+
+Choose the earlier target (or `zero`) and preview with `--reverse`. Apply that
+reviewed reverse plan with the same `--reverse`, hash and recovery reference.
+An irreversible operation is rejected. Django's reversible flag does not imply
+that data lost by forward operations can be restored. Reversal can remove data
+and requires separate review and backup planning.
+
+Filesystem `rollback` never reverses the database. The MCP history adapter
+currently retrieves filesystem-job history; this separate migration journal
+is not yet exposed through MCP.
+
+Django's migration behavior: https://docs.djangoproject.com/en/6.0/topics/migrations/