ai-guidelines 1.0.1__tar.gz

ai_guidelines-1.0.1/.github/guidelines/dependency-management.guidelines.md

@@ -0,0 +1,14 @@
+---
+name: Dependency Management Guidelines
+description: Dependency and reproducibility rules for ai-guidelines
+---
+
+# Dependency Management Guidelines
+
+Use `uv` with the repository's `uv.toml` and commit intentional `uv.lock`
+changes. Keep runtime dependencies minimal, public, and compatible with Python
+3.10+.
+
+Use `just update` for dependency upgrades. Do not rely on inherited user-level
+package indexes or hidden environment configuration. Do not add a dependency
+when a small standard-library implementation is sufficient.

ai_guidelines-1.0.1/.github/guidelines/documentation.guidelines.md

@@ -0,0 +1,13 @@
+---
+name: Documentation Guidelines
+description: Documentation maintenance rules for ai-guidelines
+---
+
+# Documentation Guidelines
+
+Update user-facing documentation when commands, options, file formats, or API
+behavior changes. Keep examples aligned with the implementation and avoid
+claiming guarantees that the code does not provide.
+
+Use clear Markdown headings and concise prose. Keep public Python docstrings
+useful and consistent with the documented contract.

ai_guidelines-1.0.1/.github/guidelines/git-commit-message.guidelines.md

@@ -0,0 +1,60 @@
+---
+name: Git Commit Message Guideline 3.0
+description: Guidelines for writing conventional commits that communicate intent and user impact
+metadata:
+  owner: Gaetan Semet <gaetan.semet@ampere.cars>
+  guideline-id: 566d8c89-0f00-4390-a64e-caa3dc425267
+  keywords: [git, commits, conventional-commits, version-control, developer-workflow]
+---
+
+# Git Commit Message Guideline
+
+Write a user-impact-focused Conventional Commit. State what users gain or
+which limitation is resolved, not implementation details.
+
+## Rules
+
+1. Format the subject as `type(scope): description`; `scope` is optional. Use
+   only `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `ci`,
+   `chore`, `build`, or `revert`. Keep it at most 71 characters.
+2. Apply limits to the final physical Git lines, not visual wrapping. Body
+   lines must be at most 79 characters; 80 is invalid. Keep every trailer on
+   one unwrapped, unindented line. Blank lines are exempt. Unbreakable URLs,
+   hashes, and similar strings may exceed 79 characters only on their own
+   line. A workflow may be stricter, never looser or conflicting.
+3. Prefer `git commit -F <message-file>`. With `-m`, the first value is the
+   subject and each later value is a paragraph separated by a blank line; use
+   one value per paragraph, never per wrapped line.
+4. Body text must describe user benefits, required user knowledge, or the
+   resolved limitation. Do not describe refactoring, internal functions,
+   changed files, methods, tests, or the number of checks run. Rewrite any
+   diff summary so it says what users can now do or what limitation was fixed.
+5. For breaking changes, put `!` in the subject and include a
+   `BREAKING CHANGE:` section with explicit migration steps.
+6. Do not add `Signed-off-by` unless a human requests it. Do not use
+   `git commit -s` or add it implicitly. If requested, add and verify it
+   deliberately. A human may use it to indicate ownership of AI-generated
+   content.
+7. If AI generated most of the message, append this body trailer:
+   `Assisted-by: MODEL_PROVIDER:MODEL_NAME FRAMEWORK`. Use the underlying
+   model family/vendor, never the interface or IDE; use the specific model
+   version; and include the optional SDD framework only when it drove the
+   implementation. Determine provider and model from the current harness or
+   session metadata. Never copy attribution or guess. If it cannot be
+   verified, stop and obtain it.
+8. If your workflow tooling owns a set of generated metadata trailers, do not
+   hand-author them. Let the tool write them, and treat its trailer vocabulary
+   as authoritative rather than reproducing older names as aliases.
+
+Valid attribution uses forms such as `Assisted-by: Claude:Sonnet-4.6`,
+`Assisted-by: Claude:Sonnet-4.6 SpecKit`, and `Assisted-by: GPT:4o`.
+`GitHub Copilot`, `Cursor`, and `AI` are invalid attribution values, because
+they name an interface rather than a model.
+
+## Positive example
+
+```text
+fix(auth): show which credential field is invalid
+
+Users can identify the invalid field without retrying valid credentials.
+```

ai_guidelines-1.0.1/.github/guidelines/git-commit.guidelines.md

@@ -0,0 +1,13 @@
+---
+name: Git Commit Guidelines
+description: Commit message and change hygiene rules for ai-guidelines
+---
+
+# Git Commit Guidelines
+
+Use Conventional Commits with a concise, user-impact-oriented subject. Keep a
+commit focused on one coherent change and do not include generated caches,
+virtual environments, coverage output, or unrelated worktree changes.
+
+Review the final diff for secrets, private infrastructure references, and
+accidental public API changes before committing.

ai_guidelines-1.0.1/.github/guidelines/python-development.guidelines.md

@@ -0,0 +1,17 @@
+---
+name: Python Development Guidelines
+description: Python implementation and API rules for ai-guidelines
+---
+
+# Python Development Guidelines
+
+Use Python 3.10+ syntax and type every maintained function signature. Keep
+modules focused and use absolute `ai_guidelines.*` imports; relative imports are
+not permitted.
+
+Use Pydantic v2 for persisted domain models and validate external input before
+filesystem or Git side effects. Keep public exports deliberate and preserve
+sanitized errors at public boundaries.
+
+Add useful Google-style docstrings to public APIs. Include `Args`, `Returns`,
+and `Raises` sections when they clarify non-obvious behavior.

ai_guidelines-1.0.1/.github/guidelines/python-unittest.guidelines.md

@@ -0,0 +1,61 @@
+---
+name: Python Unit Test Guideline 2.0
+description: Guidelines for Python unit testing
+metadata:
+  owner: Gaetan Semet <gaetan.semet@ampere.cars>
+  keywords: [python, testing, unit-test, pytest, fixtures]
+  guideline-id: 0b2bac4f-c5f2-4c24-a3cb-aecf5df02dbf
+---
+
+# Python Unit Test Guidelines
+
+Use pytest, function-based tests, and pytest fixtures.
+
+## Rules
+
+1. Write standalone `def test_*():` functions, not test classes.
+2. For multiple inputs with the same logic, use `@Parametrization` from the
+   `pytest-parametrization` dev dependency, not `pytest.mark.parametrize`.
+3. Use pytest fixtures instead of manual setup/teardown, including
+   `tmp_path`, `monkeypatch`, `caplog`, and `mocker`.
+4. Keep test code at most 120 characters wide. Preserve indentation in inline
+   code and strings, using `textwrap.dedent()` when needed.
+5. Put `test_<modulename>.py` in the `tests/` subdirectory parallel to its
+   source module; for example, tests for `src/craftman/models.py` go in
+   `src/craftman/tests/test_models.py`.
+
+## Tools
+
+- Framework: pytest.
+- Parametrization: `pytest-parametrization`, not `pytest.mark.parametrize`.
+- Fixtures: `tmp_path`, `monkeypatch`, `mocker`, and `caplog`.
+- Set appropriate function, module, or session fixture scopes.
+
+## Validation
+
+Find the project's test gate, such as `just tests-coverage`, and run the full
+test suite with coverage reporting.
+
+## Positive example
+
+```python
+def test_file_operations(tmp_path):
+   config_file = tmp_path / "config.yml"
+   config_file.write_text("key: value")
+
+   assert config_file.exists()
+   assert "key:" in config_file.read_text()
+```
+
+Using pytest-parametrization:
+
+```python
+from parametrization import Parametrization
+
+@Parametrization.autodetect_parameters()
+@Parametrization.case(name="valid_input", input_val=1, expected=2)
+@Parametrization.case("zero_input", input_val=0, expected=1)
+@Parametrization.case("negative_input", input_val=-1, expected=0)
+def test_increment_function(input_val, expected):
+    assert increment(input_val) == expected
+```

ai_guidelines-1.0.1/.github/skills/gh-release-notes/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: gh-release-notes
+description: Generate end-user-friendly GitHub release notes from the actual diff between releases, including user impact, examples, breaking changes, and public documentation links.
+argument-hint: "from_ref=... to_ref=... repo_path=..."
+user-invocable: true
+---
+
+# Release Notes Generator
+
+Generate clean, end-user-friendly release notes from the actual Git diff between
+an exclusive starting ref and an inclusive ending ref. The output is written
+for use as a GitHub Release body and must contain release-note sections only.
+GitHub supplies the release title, so never add a version heading, title,
+preamble, file summary, commit summary, or closing explanation.
+
+## Output contract
+
+- Start with one of: `## New Features`, `## Enhancements`, `## Bug Fixes`,
+  `## Breaking Changes`, `## Examples`, `## Documentation`, or `## Maintenance`.
+- Include only changes that ordinary users of the published `ai-guidelines`
+  package can do, observe, configure, rely on, or learn differently.
+- Exclude CI, release automation, tests, Git evidence, contributor guidance,
+  agent instructions, governance, internal process, and repository housekeeping.
+- Translate implementation details into user outcomes. Never list files,
+  functions, commit hashes, authors, or internal workflow mechanics.
+- Use one concise line per bullet and omit empty sections.
+- Include `## Maintenance` only when no user-facing change qualifies. It must be
+  the only section and say that the release contains maintenance and internal
+  improvements without inventing a benefit.
+- Never combine `## Maintenance` with a user-facing section.
+- Include `## Breaking Changes` only when the diff proves a public API, format,
+  configuration, default, or supported-workflow break.
+- Add a concrete `## Examples` section for changed commands, APIs, configuration,
+  or before/after workflows when public usage evidence exists.
+- Link relevant public documentation with descriptive inline Markdown, for example
+  `See the [installation guide](https://ai-guidelines.readthedocs.io/en/stable/).`
+  Never emit a bare URL or a repository-relative documentation path.
+- Do not use code fences, a `#` title heading, or headings outside the permitted
+  seven section names.
+
+## Analysis workflow
+
+1. Read the exact `from_ref..to_ref` commit log and diff.
+2. Inspect public README, documentation, CLI help, and API references for evidence
+   of user-visible behavior and the closest trustworthy documentation links.
+3. Apply the normal-user audience test to every candidate change.
+4. Detect breaking changes from commit markers and actual public contract changes.
+5. Consolidate multiple commits that describe one final user outcome.
+6. Categorize the remaining outcomes and write concise Markdown.
+7. Review every bullet for user impact, documentation-link correctness, and the
+   output contract before writing the requested file.
+
+## Automated invocation
+
+When the generator is invoked by a CI job with an explicit output path:
+
+- Treat the requested file as mandatory and write the final Markdown directly to it.
+- Do not use the Copilot response stream as the output artifact.
+- Do not modify any other repository files.
+- The first line must be a permitted `##` heading.
+- The file must contain only release-note Markdown, without a title, preamble,
+  code fence, or explanatory text.
+
+For an empty or intentionally maintenance-only range, write exactly:
+
+```markdown
+## Maintenance
+
+This release contains maintenance and internal improvements. No user-facing behavior changed.
+```
+
+The bundled generator precomputes Git evidence, invokes this skill through the
+Copilot CLI, and validates the resulting file before the workflow creates the
+GitHub Release.

ai_guidelines-1.0.1/.github/skills/gh-release-notes/scripts/generate_release_notes.py

@@ -0,0 +1,373 @@
+#!/usr/bin/env python3
+"""Generate and validate release notes through the GitHub Copilot CLI."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+SKILL_NAME = "gh-release-notes"
+DEFAULT_OUTPUT = Path("release-notes.md")
+MAX_GIT_CONTEXT_LENGTH = 60_000
+TOKEN_ENV_VARS = ("COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN")
+PERMITTED_HEADINGS = frozenset(
+    {
+        "## New Features",
+        "## Enhancements",
+        "## Bug Fixes",
+        "## Breaking Changes",
+        "## Examples",
+        "## Documentation",
+        "## Maintenance",
+    }
+)
+TRACE_MARKERS = (
+    "<function_call",
+    "<thinking>",
+    "<system_notification>",
+    "assistant.reasoning",
+    "function_calls",
+    "to=bash.exec",
+    "to=functions.exec",
+)
+MAINTENANCE_NOTES = (
+    "## Maintenance\n\n"
+    "This release contains maintenance and internal improvements. "
+    "No user-facing behavior changed.\n"
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line argument parser."""
+    parser = argparse.ArgumentParser(
+        description="Generate or validate release notes for the gh-release-notes skill."
+    )
+    parser.add_argument(
+        "--from-ref",
+        help="Starting Git ref. It is excluded: the range is from_ref..to_ref.",
+    )
+    parser.add_argument(
+        "--to-ref",
+        help="Ending Git ref. It is included: the range is from_ref..to_ref.",
+    )
+    parser.add_argument(
+        "--repo",
+        type=Path,
+        default=Path.cwd(),
+        help="Repository to inspect (default: current directory).",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=DEFAULT_OUTPUT,
+        help="Release-note output path (default: release-notes.md).",
+    )
+    parser.add_argument(
+        "--maintenance-only",
+        action="store_true",
+        help="Write deterministic maintenance notes without invoking Copilot.",
+    )
+    parser.add_argument(
+        "--model",
+        default=None,
+        help="Copilot CLI model identifier; defaults to COPILOT_MODEL or the CLI default.",
+    )
+    parser.add_argument(
+        "--validate",
+        type=Path,
+        metavar="FILE",
+        help="Verify that an existing release-note file follows the output contract.",
+    )
+    return parser
+
+
+def build_git_context(repo: Path, from_ref: str, to_ref: str) -> str:
+    """Collect generic Git evidence for Copilot environments without Git access."""
+    log = git_output(
+        repo, "commit log", "log", "--format=%h %s", "--no-merges", f"{from_ref}..{to_ref}"
+    )
+    diff_stat = git_output(
+        repo, "diff summary", "diff", "--stat", "--no-ext-diff", f"{from_ref}..{to_ref}"
+    )
+    diff = git_output(repo, "diff", "diff", "--no-ext-diff", "--unified=3", f"{from_ref}..{to_ref}")
+    context = (
+        f"Precomputed Git evidence for {from_ref}..{to_ref}:\n\n"
+        f"Commit log:\n{log or '(no commits)'}\n\n"
+        f"Diff summary:\n{diff_stat or '(empty)'}\n\n"
+        f"Diff:\n{diff or '(empty)'}"
+    )
+    if len(context) <= MAX_GIT_CONTEXT_LENGTH:
+        return context
+
+    truncated = context[:MAX_GIT_CONTEXT_LENGTH]
+    return (
+        f"{truncated}\n\n[Git evidence truncated at {MAX_GIT_CONTEXT_LENGTH} characters; "
+        "use the included summary and inspect the checked-out files when needed.]"
+    )
+
+
+def build_prompt(
+    from_ref: str,
+    to_ref: str,
+    repo: Path,
+    output: Path,
+    git_context: str | None = None,
+) -> str:
+    """Build the small orchestration prompt; the skill owns release-note policy."""
+    try:
+        output_reference = output.relative_to(repo).as_posix()
+    except ValueError:
+        output_reference = str(output)
+
+    prompt = (
+        f"Use the /{SKILL_NAME} skill. Generate release notes for the exact Git range "
+        f"{from_ref}..{to_ref} in {repo}. The skill is authoritative for analysis, "
+        f"classification, wording, documentation, and Markdown format. Write the final "
+        f"release-note Markdown directly to the shared repository file "
+        f"{output_reference} using the file-writing tools. Its resolved path is {output}. "
+        "The release workflow reads this exact file as its notes input; the Copilot "
+        "response stream is discarded. Do not put release notes or a summary in your "
+        "response, and do not modify any other files. Before writing, enforce the "
+        "skill's final output contract: render every documentation URL as concise inline "
+        "Markdown, never as a bare URL; exclude all internal CI, release automation, "
+        "governance, contributor, agent, generator, Git-evidence, and maintainer content; "
+        "and omit Maintenance whenever any user-facing section remains."
+    )
+    if git_context:
+        prompt += (
+            " Treat the following locally collected Git evidence as authoritative input; "
+            "the starting ref is excluded and the ending ref is included.\n\n"
+            f"<git-evidence>\n{git_context}\n</git-evidence>"
+        )
+    return prompt
+
+
+def build_copilot_command(prompt: str, model: str | None) -> list[str]:
+    """Build the non-interactive Copilot CLI command."""
+    command = [
+        "gh",
+        "copilot",
+        "--",
+        "--prompt",
+        prompt,
+        "--silent",
+        "--no-ask-user",
+        "--no-auto-update",
+        "--no-color",
+        "--output-format",
+        "text",
+        "--disable-builtin-mcps",
+        "--allow-all-tools",
+        "--available-tools=read,create,edit,bash",
+        "--allow-url=https://github.com",
+        "--allow-url=https://ai-guidelines.readthedocs.io",
+    ]
+    if model:
+        command.extend(["--model", model])
+    return command
+
+
+def resolve_path(path: Path, repo: Path) -> Path:
+    """Resolve a path relative to the repository when it is not absolute."""
+    return path if path.is_absolute() else repo / path
+
+
+def run_git(repo: Path, *arguments: str) -> subprocess.CompletedProcess[str]:
+    """Run a Git command in the target repository."""
+    return subprocess.run(
+        ["git", *arguments],
+        cwd=repo,
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+
+
+def git_output(repo: Path, description: str, *arguments: str) -> str:
+    """Run Git and return its output, raising one consistent error on failure."""
+    result = run_git(repo, *arguments)
+    if result.returncode != 0:
+        detail = result.stderr.strip() or "unknown Git error"
+        raise ValueError(f"Unable to collect the release {description}: {detail}")
+    return result.stdout.strip()
+
+
+def validate_range(repo: Path, from_ref: str, to_ref: str) -> None:
+    """Verify that the requested refs exist and form an ancestor range."""
+    if from_ref == to_ref:
+        raise ValueError("--from-ref and --to-ref must be different refs.")
+
+    for ref in (from_ref, to_ref):
+        result = run_git(repo, "rev-parse", "--verify", f"{ref}^{{commit}}")
+        if result.returncode != 0:
+            detail = result.stderr.strip() or "unknown Git error"
+            raise ValueError(f"Git ref {ref!r} is not available: {detail}")
+
+    result = run_git(repo, "merge-base", "--is-ancestor", from_ref, to_ref)
+    if result.returncode != 0:
+        raise ValueError(f"Git ref {from_ref!r} is not an ancestor of {to_ref!r}.")
+
+
+def range_has_commits(repo: Path, from_ref: str, to_ref: str) -> bool:
+    """Return whether the requested Git range contains at least one commit."""
+    count = git_output(repo, "commit count", "rev-list", "--count", f"{from_ref}..{to_ref}")
+    return count != "0"
+
+
+def write_maintenance_notes(output: Path) -> None:
+    """Write the deterministic notes required for a maintenance-only release."""
+    output.write_text(MAINTENANCE_NOTES, encoding="utf-8")
+
+
+def run_skill_check(repo: Path) -> None:
+    """Ensure the release-note skill is installed in the Copilot CLI."""
+    result = subprocess.run(
+        ["gh", "copilot", "--", "skill", "list"],
+        cwd=repo,
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    output = f"{result.stdout}\n{result.stderr}"
+    if result.returncode != 0:
+        raise RuntimeError(f"Unable to list Copilot skills:\n{output.strip()}")
+    if SKILL_NAME not in output:
+        raise RuntimeError(f"Copilot skill {SKILL_NAME!r} is not installed.")
+
+
+def require_copilot_token() -> None:
+    """Fail early when no supported GitHub token environment variable exists."""
+    if not any(os.environ.get(name) for name in TOKEN_ENV_VARS):
+        names = ", ".join(TOKEN_ENV_VARS[:-1]) + f", or {TOKEN_ENV_VARS[-1]}"
+        raise RuntimeError(f"Set one of {names} before running Copilot CLI.")
+
+
+def run_copilot(repo: Path, prompt: str, model: str | None) -> None:
+    """Run Copilot CLI and leave the generated Markdown in the shared output file."""
+    result = subprocess.run(
+        build_copilot_command(prompt, model),
+        cwd=repo,
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        output = f"{result.stdout}\n{result.stderr}".strip()
+        raise RuntimeError(f"Copilot CLI failed with exit code {result.returncode}:\n{output}")
+
+
+def validate_output(output: Path) -> None:
+    """Verify that generated release notes follow the output contract."""
+    try:
+        content = output.read_text(encoding="utf-8")
+    except OSError as error:
+        raise RuntimeError(f"Unable to read release-note output {output}: {error}") from error
+    if not content.strip():
+        raise RuntimeError(f"Copilot created an empty release-note file: {output}")
+
+    lines = content.splitlines()
+    first_line = lines[0] if lines else ""
+    if first_line not in PERMITTED_HEADINGS:
+        raise RuntimeError(
+            f"Release-note output must start with one of the permitted section headings: {output}"
+        )
+
+    lowered = content.lower()
+    leaked_markers = [marker for marker in TRACE_MARKERS if marker.lower() in lowered]
+    if leaked_markers:
+        markers = ", ".join(leaked_markers)
+        raise RuntimeError(
+            f"Release-note output contains Copilot trace markers ({markers}): {output}"
+        )
+    if "```" in content:
+        raise RuntimeError(f"Release-note output must not contain a code fence: {output}")
+    if any(line.startswith("# ") for line in lines):
+        raise RuntimeError(f"Release-note output must not contain a title heading: {output}")
+    headings = [line for line in lines if line.startswith("## ")]
+    invalid_headings = [heading for heading in headings if heading not in PERMITTED_HEADINGS]
+    if invalid_headings:
+        raise RuntimeError(
+            f"Release-note output contains an invalid section heading "
+            f"{invalid_headings[0]!r}: {output}"
+        )
+    print("Release-note output file verified.")
+
+
+def generate_release_notes(
+    repo: Path,
+    from_ref: str,
+    to_ref: str,
+    output: Path,
+    model: str | None,
+    maintenance_only: bool = False,
+) -> None:
+    """Generate release notes, then validate the resulting Markdown file."""
+    repo = repo.resolve()
+    output = resolve_path(output, repo).resolve()
+    validate_range(repo, from_ref, to_ref)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text("", encoding="utf-8")
+
+    print(f"Generating release notes from {from_ref} (exclusive) to {to_ref} (inclusive).")
+    print(f"Copilot model: {model or 'CLI default'}")
+    if maintenance_only or not range_has_commits(repo, from_ref, to_ref):
+        write_maintenance_notes(output)
+        validate_output(output)
+        print(f"Release notes written to {output}")
+        return
+
+    require_copilot_token()
+    run_skill_check(repo)
+    git_context = build_git_context(repo, from_ref, to_ref)
+    run_copilot(
+        repo,
+        build_prompt(from_ref, to_ref, repo, output, git_context),
+        model,
+    )
+
+    validate_output(output)
+    print(f"Release notes written to {output}")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Parse arguments, generate notes, and return an exit code."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.validate is not None:
+        if (args.from_ref is None) != (args.to_ref is None):
+            parser.error("--validate requires both --from-ref and --to-ref for range validation")
+        try:
+            repo = args.repo.resolve()
+            if args.from_ref is not None and args.to_ref is not None:
+                validate_range(repo, args.from_ref, args.to_ref)
+            validate_output(resolve_path(args.validate, repo))
+        except (OSError, RuntimeError, ValueError) as error:
+            print(f"error: {error}", file=sys.stderr)
+            return 1
+        return 0
+
+    if args.from_ref is None or args.to_ref is None:
+        parser.error("--from-ref and --to-ref are required unless --validate is used")
+
+    try:
+        generate_release_notes(
+            repo=args.repo,
+            from_ref=args.from_ref,
+            to_ref=args.to_ref,
+            output=args.output,
+            model=args.model or os.environ.get("COPILOT_MODEL"),
+            maintenance_only=args.maintenance_only,
+        )
+    except (OSError, RuntimeError, ValueError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())