pubanon 0.1.0__tar.gz

pubanon-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+dist/
+.eggs/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage*
+.pytest_cache/
+.cache/
+
+# Type checker / linter caches
+.pyright/
+.mypy_cache/
+.ruff_cache/
+pyrightconfig.json
+
+# Editors
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

pubanon-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the pubanon authors
+
+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.

pubanon-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: pubanon
+Version: 0.1.0
+Summary: Publish selected files to GitHub under a separate identity
+Project-URL: Documentation, https://github.com/dactylo/pubanon/tree/main/docs
+Project-URL: Homepage, https://github.com/dactylo/pubanon
+Project-URL: Issues, https://github.com/dactylo/pubanon/issues
+Project-URL: Repository, https://github.com/dactylo/pubanon
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anonymization,git,privacy,publishing,security
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: ruamel-yaml>=0.19.1
+Description-Content-Type: text/markdown
+
+# pubanon
+
+Pubanon publishes selected files from a private Git repository to GitHub under a separate name and
+email. Each release creates one publication commit without copying your private commit history.
+Choose the files, review the prepared release, and confirm publication.
+
+Pubanon checks the selected content for configured sensitive terms. It does not rewrite secrets out
+of files. You control what you publish; the
+[content matching limits](docs/guide.md#how-a-release-works) explain what the checks can detect.
+
+## Installation
+
+You need Python 3.13 or newer, Git 2.41.0 or newer, and the GitHub CLI (`gh`). Pubanon targets
+Linux, macOS, and native Windows. See [platform requirements](docs/platforms.md) for details.
+
+From a checkout of this repository, install the command with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv tool install .
+```
+
+After updating the checkout, update the installed command:
+
+```sh
+uv tool install --reinstall .
+```
+
+uv is needed for these installation commands. If you use make, `make install` and `make reinstall`
+run the same commands.
+
+## Your first release
+
+### Choose your publication identity
+
+```sh
+pubanon setup
+```
+
+Setup asks for the name and email to use in published Git history and the terms you want to keep
+private. It verifies your GitHub CLI account and shows your answers before saving. Choose the name
+and email you want readers to see: existing publication commits keep that identity. Use
+`pubanon setup --edit` to change saved answers or `pubanon doctor` to check readiness.
+
+### Select your project and files
+
+Enter a private source repository with no Git remote:
+
+```sh
+cd /path/to/private-project
+pubanon init
+```
+
+Follow the prompts to choose files, a GitHub destination, and repository settings. Choose `private`
+visibility for this walkthrough so you can check the result on GitHub before making it public.
+Review your choices and save. Pubanon stores its configuration outside the source repository.
+
+### Prepare and review
+
+Commit the changes you want to publish in your source repository, then run:
+
+```sh
+pubanon repo create
+pubanon prepare
+pubanon inspect
+```
+
+`prepare` saves the selected committed files as a local *snapshot*. Uncommitted changes are left
+out. If the selected `pyproject.toml` declares a package version, Pubanon uses it for the release
+tag; otherwise the snapshot is untagged. See [version tags](docs/guide.md#version-tags) to choose
+an explicit version.
+
+`inspect` shows the release details and a directory of read-only files to review. Builds or tests
+that write files need a separate writable copy. Changes in either copy do not alter the snapshot.
+To correct it, edit and commit in the source, then run `pubanon discard` and `pubanon prepare`
+again.
+
+### Publish and make it public
+
+When you are satisfied, run:
+
+```sh
+pubanon publish
+pubanon repo reveal
+```
+
+`publish` asks for confirmation before sending the saved snapshot to your private destination.
+`repo reveal` checks the published history, settings, and any configured CI requirements before
+asking to make the repository public. It also provides links to Actions logs and artifacts for you
+to review; Pubanon does not scan their contents.
+
+For the next release, commit your changes and repeat `prepare`, `inspect`, and `publish`. For a
+versioned Python package, update and commit its version first. The
+[publication guide](docs/guide.md#quick-path) also explains the `release VERSION` shortcut.
+
+Still correcting the initial release privately? Commit your fixes, then use
+`pubanon prepare --replace all`, `pubanon inspect`, and `pubanon publish` to replace the entire
+published history while keeping the same version. To correct only the latest publication and keep
+earlier history, use `pubanon prepare --replace`. See
+[correcting published history](docs/guide.md#correcting-published-history) for the available
+scopes.
+
+After replacements, `pubanon clean` previews and removes superseded local snapshots with one
+confirmation. It keeps current published snapshots and prepared work. See
+[cleanup](docs/operations.md#cleanup) for other cleanup tasks.
+
+## Where to go next
+
+| If you want to...                                               | Read                                                                          |
+| --------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| Publish another release or choose a workflow                    | [Publication guide](docs/guide.md)                                            |
+| Change the selected files, CI checks, or other project settings | [Project configuration](docs/guide.md#edit-an-existing-project)               |
+| Run CI privately before publishing                              | [Private staging](docs/guide.md#private-first-ci)                             |
+| Inspect an earlier release or recover its private source        | [Published history](docs/operations.md#published-history-and-source-recovery) |
+| Correct a published release                                     | [History replacement](docs/guide.md#correcting-published-history)             |
+| Recover from an interruption, clean up, or make backups         | [Operations guide](docs/operations.md)                                        |
+| Check platform requirements                                     | [Platforms](docs/platforms.md)                                                |
+| See changes by version                                          | [Changelog](CHANGELOG.md)                                                     |
+
+Use `pubanon status` to see local state or `pubanon status --remote` to compare it with GitHub. If
+a push outcome is unknown, follow the reported recovery command: `pubanon publish --resolve`.
+
+## Development
+
+Provide the tools in `[dependency-groups].dev` through your environment or package manager, then
+run:
+
+```sh
+make check
+```
+
+`make format` applies the repository formatters. Tests run offline with temporary Git repositories
+and a fake GitHub CLI.

pubanon-0.1.0/README.md

@@ -0,0 +1,132 @@
+# pubanon
+
+Pubanon publishes selected files from a private Git repository to GitHub under a separate name and
+email. Each release creates one publication commit without copying your private commit history.
+Choose the files, review the prepared release, and confirm publication.
+
+Pubanon checks the selected content for configured sensitive terms. It does not rewrite secrets out
+of files. You control what you publish; the
+[content matching limits](docs/guide.md#how-a-release-works) explain what the checks can detect.
+
+## Installation
+
+You need Python 3.13 or newer, Git 2.41.0 or newer, and the GitHub CLI (`gh`). Pubanon targets
+Linux, macOS, and native Windows. See [platform requirements](docs/platforms.md) for details.
+
+From a checkout of this repository, install the command with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv tool install .
+```
+
+After updating the checkout, update the installed command:
+
+```sh
+uv tool install --reinstall .
+```
+
+uv is needed for these installation commands. If you use make, `make install` and `make reinstall`
+run the same commands.
+
+## Your first release
+
+### Choose your publication identity
+
+```sh
+pubanon setup
+```
+
+Setup asks for the name and email to use in published Git history and the terms you want to keep
+private. It verifies your GitHub CLI account and shows your answers before saving. Choose the name
+and email you want readers to see: existing publication commits keep that identity. Use
+`pubanon setup --edit` to change saved answers or `pubanon doctor` to check readiness.
+
+### Select your project and files
+
+Enter a private source repository with no Git remote:
+
+```sh
+cd /path/to/private-project
+pubanon init
+```
+
+Follow the prompts to choose files, a GitHub destination, and repository settings. Choose `private`
+visibility for this walkthrough so you can check the result on GitHub before making it public.
+Review your choices and save. Pubanon stores its configuration outside the source repository.
+
+### Prepare and review
+
+Commit the changes you want to publish in your source repository, then run:
+
+```sh
+pubanon repo create
+pubanon prepare
+pubanon inspect
+```
+
+`prepare` saves the selected committed files as a local *snapshot*. Uncommitted changes are left
+out. If the selected `pyproject.toml` declares a package version, Pubanon uses it for the release
+tag; otherwise the snapshot is untagged. See [version tags](docs/guide.md#version-tags) to choose
+an explicit version.
+
+`inspect` shows the release details and a directory of read-only files to review. Builds or tests
+that write files need a separate writable copy. Changes in either copy do not alter the snapshot.
+To correct it, edit and commit in the source, then run `pubanon discard` and `pubanon prepare`
+again.
+
+### Publish and make it public
+
+When you are satisfied, run:
+
+```sh
+pubanon publish
+pubanon repo reveal
+```
+
+`publish` asks for confirmation before sending the saved snapshot to your private destination.
+`repo reveal` checks the published history, settings, and any configured CI requirements before
+asking to make the repository public. It also provides links to Actions logs and artifacts for you
+to review; Pubanon does not scan their contents.
+
+For the next release, commit your changes and repeat `prepare`, `inspect`, and `publish`. For a
+versioned Python package, update and commit its version first. The
+[publication guide](docs/guide.md#quick-path) also explains the `release VERSION` shortcut.
+
+Still correcting the initial release privately? Commit your fixes, then use
+`pubanon prepare --replace all`, `pubanon inspect`, and `pubanon publish` to replace the entire
+published history while keeping the same version. To correct only the latest publication and keep
+earlier history, use `pubanon prepare --replace`. See
+[correcting published history](docs/guide.md#correcting-published-history) for the available
+scopes.
+
+After replacements, `pubanon clean` previews and removes superseded local snapshots with one
+confirmation. It keeps current published snapshots and prepared work. See
+[cleanup](docs/operations.md#cleanup) for other cleanup tasks.
+
+## Where to go next
+
+| If you want to...                                               | Read                                                                          |
+| --------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| Publish another release or choose a workflow                    | [Publication guide](docs/guide.md)                                            |
+| Change the selected files, CI checks, or other project settings | [Project configuration](docs/guide.md#edit-an-existing-project)               |
+| Run CI privately before publishing                              | [Private staging](docs/guide.md#private-first-ci)                             |
+| Inspect an earlier release or recover its private source        | [Published history](docs/operations.md#published-history-and-source-recovery) |
+| Correct a published release                                     | [History replacement](docs/guide.md#correcting-published-history)             |
+| Recover from an interruption, clean up, or make backups         | [Operations guide](docs/operations.md)                                        |
+| Check platform requirements                                     | [Platforms](docs/platforms.md)                                                |
+| See changes by version                                          | [Changelog](CHANGELOG.md)                                                     |
+
+Use `pubanon status` to see local state or `pubanon status --remote` to compare it with GitHub. If
+a push outcome is unknown, follow the reported recovery command: `pubanon publish --resolve`.
+
+## Development
+
+Provide the tools in `[dependency-groups].dev` through your environment or package manager, then
+run:
+
+```sh
+make check
+```
+
+`make format` applies the repository formatters. Tests run offline with temporary Git repositories
+and a fake GitHub CLI.

pubanon-0.1.0/pyproject.toml

@@ -0,0 +1,127 @@
+# ==========================================================
+# Build System
+# ==========================================================
+[build-system]
+build-backend = "hatchling.build"
+requires = [ "hatchling>=1.27" ]
+
+# ==========================================================
+# Project Metadata
+# ==========================================================
+[project]
+name = "pubanon"
+version = "0.1.0"
+description = "Publish selected files to GitHub under a separate identity"
+readme = "README.md"
+keywords = [ "anonymization", "git", "privacy", "publishing", "security" ]
+license = "MIT"
+license-files = [ "LICENSE" ]
+requires-python = ">=3.13"
+classifiers = [
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Typing :: Typed",
+]
+dependencies = [ "ruamel-yaml>=0.19.1" ]
+urls.Documentation = "https://github.com/dactylo/pubanon/tree/main/docs"
+urls.Homepage = "https://github.com/dactylo/pubanon"
+urls.Issues = "https://github.com/dactylo/pubanon/issues"
+urls.Repository = "https://github.com/dactylo/pubanon"
+scripts.pubanon = "pubanon._cli:main"
+
+[dependency-groups]
+dev = [
+  "mdformat",
+  "mdformat-config",
+  "mdformat-frontmatter",
+  "mdformat-gfm",
+  "mdformat-pyproject",
+  "mdformat-ruff",
+  "mdformat-shfmt",
+  "pyproject-fmt",
+  "pyright",
+  "pytest",
+  "ruff",
+]
+
+[tool.hatch]
+build.targets.wheel.packages = [ "src/pubanon" ]
+build.targets.sdist.include = [ "/src" ]
+
+# ==========================================================
+# Ruff Configuration
+# ==========================================================
+[tool.ruff]
+target-version = "py313"
+line-length = 99
+format.quote-style = "single"
+format.exclude = [ "*.md" ]
+lint.select = [ "ALL" ]
+lint.ignore = [
+  "COM812", # Conflicts with the Ruff formatter
+  "CPY001", # Copyright notices are not required
+  "D203",   # Conflicts with the Google docstring convention
+  "D213",   # Conflicts with the Google docstring convention
+  "EM101",  # Exception must not use string literal
+  "EM102",  # Exception must not use f-string literal
+  "FBT001", # Boolean positional arg in function definition
+  "FBT002", # Boolean default value in function definition
+  "ISC001", # Implicit string concatenation
+  "Q000",   # Conflicts with the Ruff formatter
+  "Q001",   # Conflicts with the Ruff formatter
+  "Q002",   # Conflicts with the Ruff formatter
+  "Q003",   # Conflicts with the Ruff formatter
+  "T201",   # print() found
+  "TRY003", # Avoid specifying long messages outside exception class
+]
+lint.per-file-ignores."src/pubanon/_cli/_arguments.py" = [ "SLF001" ]
+lint.per-file-ignores."src/pubanon/_cli/_workflow.py" = [ "SLF001" ]
+lint.per-file-ignores."src/pubanon/_config.py" = [ "SLF001" ]
+lint.per-file-ignores."src/pubanon/_remote/_publish.py" = [ "SLF001" ]
+lint.per-file-ignores."src/pubanon/_remote/_stage.py" = [ "SLF001" ]
+lint.per-file-ignores."src/pubanon/_snapshots/_candidate.py" = [ "SLF001" ]
+lint.per-file-ignores."src/pubanon/_snapshots/_records.py" = [ "SLF001" ]
+lint.per-file-ignores."tests/**/*.py" = [
+  "D",       # No docstrings required in tests
+  "PLC2701", # Tests intentionally import private implementation symbols
+  "PLR2004", # Allow magic values in tests
+  "S101",    # Allow asserts in tests
+  "S603",    # Allow subprocess calls in tests
+  "S607",    # Allow partial executable paths in tests
+  "SLF001",  # Tests intentionally inspect and patch private state
+]
+lint.pydocstyle.convention = "google"
+
+[tool.pyproject-fmt]
+max_supported_python = "3.15"
+
+# ==========================================================
+# Pyright Configuration
+# ==========================================================
+[tool.pyright]
+pythonVersion = "3.13"  # Keep in sync with tool.ruff.target-version
+typeCheckingMode = "strict"
+extraPaths = [ ".", "src" ]
+executionEnvironments = [
+  { root = "tests", reportPrivateUsage = "none" },
+  { root = "." },
+]
+
+# ==========================================================
+# Pytest Configuration
+# ==========================================================
+[tool.pytest]
+ini_options.testpaths = [ "tests" ]
+ini_options.pythonpath = [ "src" ]
+ini_options.addopts = [ "-q", "--strict-markers", "--tb=short" ]
+ini_options.markers = [ "slow: marks tests as slow (deselect with '-m \"not slow\"')" ]
+ini_options.faulthandler_timeout = 300
+
+# ==========================================================
+# Mdformat Configuration (Requires mdformat-pyproject)
+# ==========================================================
+[tool.mdformat]
+wrap = 99  # Keep in sync with tool.ruff.line-length
+number = true

pubanon-0.1.0/src/pubanon/__init__.py

@@ -0,0 +1,7 @@
+"""Publish private repositories under a separate publication identity.
+
+Use the `pubanon` command or `python -m pubanon`. The package root exports no
+public Python API.
+"""
+
+__all__: list[str] = []

pubanon-0.1.0/src/pubanon/__main__.py

@@ -0,0 +1,5 @@
+"""Run the pubanon command-line interface with `python -m pubanon`."""
+
+from pubanon._cli import main
+
+raise SystemExit(main())

pubanon-0.1.0/src/pubanon/_cli/__init__.py

@@ -0,0 +1,167 @@
+"""Provide the Pubanon command-line entry point."""
+
+from __future__ import annotations
+
+import os
+import sys
+from contextlib import ExitStack
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pubanon import (
+    _config,
+    _run,
+)
+from pubanon._cli import (
+    _arguments,
+    _init,
+    _inspect,
+    _prepare,
+    _setup,
+    _status,
+    _workflow,
+)
+from pubanon._cli import _history as cli_history
+from pubanon._cli import _remote as cli_remote
+from pubanon._errors import OperationCancelled, PubanonError
+from pubanon._terminal import (
+    color_context,
+    diagnostic,
+    guidance,
+    guidance_context,
+    output_encoding_context,
+)
+
+if TYPE_CHECKING:
+    import argparse
+    from collections.abc import Callable, Iterable, Sequence
+
+
+def _dispatch(args: argparse.Namespace) -> None:
+    """Dispatch one parsed command."""
+
+    def _dispatch_doctor(_args: argparse.Namespace) -> None:
+        _setup.doctor()
+
+    def _dispatch_setup(args: argparse.Namespace) -> None:
+        if args.edit:
+            _setup.setup(edit=True)
+        else:
+            _setup.setup()
+
+    handlers: dict[str, Callable[[argparse.Namespace], None]] = {
+        'clean': cli_history.command_clean,
+        'delete': cli_history.command_delete,
+        'discard': cli_history.command_discard,
+        'doctor': _dispatch_doctor,
+        'list': cli_history.command_list,
+        'init': _init.command_init,
+        'inspect': _inspect.command_inspect,
+        'prepare': _prepare.command_prepare,
+        'publish': cli_remote.command_publish,
+        'release': _workflow.command_release,
+        'run': _workflow.command_run,
+        'setup': _dispatch_setup,
+        'show': cli_history.command_show,
+        'status': _status.command_status,
+    }
+    if args.command == 'repo':
+        handler = {
+            'create': cli_remote.repo_create,
+            'reveal': cli_remote.repo_reveal,
+            'verify': cli_remote.verify_repo,
+        }.get(args.repo_command)
+    elif args.command == 'stage':
+        handler = {
+            'clean': cli_remote.stage_clean,
+            'push': cli_remote.stage_push,
+            'status': cli_remote.stage_status,
+        }.get(args.stage_command)
+    elif args.command == 'watch':
+        handler = {'ci': cli_remote.watch_ci, 'package': cli_remote.watch_package}.get(
+            args.watch_command
+        )
+    else:
+        handler = handlers.get(args.command)
+    if handler is None:
+        raise PubanonError('unsupported command')
+    if args.command != 'setup':
+        _run.check_floors()
+    handler(args)
+
+
+def _implicit_guidance_project(args: argparse.Namespace) -> str | None:
+    """Omit redundant project advice when registry lookup is available."""
+    if args.command in {'setup', 'doctor'}:
+        return None
+    try:
+        paths = _config.derive_paths(os.environ)
+        if not paths.registry.exists():
+            return None
+        return _config.registry_lookup(paths, Path.cwd())
+    except PubanonError:
+        # Advice must not add a registry dependency to explicit project selection.
+        return None
+
+
+def _report_error(error: PubanonError) -> None:
+    """Report a refusal with its diagnostic values."""
+    print(diagnostic(error, stream=sys.stderr), file=sys.stderr)
+
+
+def _main(argv: Sequence[str] | None = None) -> int:
+    """Parse and dispatch one command, translating failures to process exit statuses."""
+    with ExitStack() as contexts:
+        try:
+            parser = _arguments.build_parser()
+            arguments = list(sys.argv[1:] if argv is None else argv)
+            contexts.enter_context(color_context(parser.selected_color_mode(arguments)))
+            args = parser.parse_args(arguments)
+            _arguments.validate_options(parser, args)
+            try:
+                selected = getattr(args, 'project', None)
+                implicit = _implicit_guidance_project(args)
+                with guidance_context(
+                    project=selected,
+                    implicit_project=implicit if selected in {None, implicit} else None,
+                ):
+                    try:
+                        _dispatch(args)
+                    except PubanonError as error:
+                        if error.recovery is not None:
+                            error.recovery = guidance(error.recovery)
+                        raise
+            except OperationCancelled:
+                raise
+            except PubanonError as error:
+                _report_error(error)
+                return 1
+        except SystemExit as exc:
+            return exc.code if isinstance(exc.code, int) else 2
+        except OperationCancelled as error:
+            print(diagnostic(error, stream=sys.stderr), file=sys.stderr)
+            return 130
+        except KeyboardInterrupt:
+            error = OperationCancelled('operation cancelled')
+            print(diagnostic(error, stream=sys.stderr), file=sys.stderr)
+            return 130
+        except PubanonError as error:
+            print(diagnostic(error, stream=sys.stderr), file=sys.stderr)
+            return 1
+    return 0
+
+
+def main(argv: Iterable[str] | None = None) -> int:
+    """Run one command with consistent color policy, including help and errors.
+
+    Args:
+        argv: Arguments excluding the executable, or None for process
+            arguments.
+
+    Returns:
+        Zero for success, one for refusal, two for usage errors, or 130 for
+        interruption.
+    """
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    with output_encoding_context():
+        return _main(arguments)