plainx.dev 0.1.0__tar.gz

plainx_dev-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+.venv
+/.env
+*.egg-info
+*.py[co]
+__pycache__
+*.DS_Store
+
+/*.code-workspace
+
+# Test apps
+plain*/tests/.plain
+
+# Agent scratch files
+/scratch
+
+# Plain temp dirs
+.plain
+
+.vscode
+/.claude/settings.local.json
+/.benchmarks

plainx_dev-0.1.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: plainx.dev
+Version: 0.1.0
+Summary: Development tools for plainx package developers, including release automation.
+Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
+License-Expression: BSD-3-Clause
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# plainx-dev
+
+Development tools for plainx package developers.
+
+## Installation
+
+Add as a dev dependency:
+
+```bash
+uv add --dev plainx-dev
+```
+
+## Skills
+
+After installing, run `plain agent install` to copy skills to your `.claude/` directory.
+
+### /plainx-release
+
+A release workflow skill that helps you:
+
+- Analyze commits and suggest version bump type (major/minor/patch)
+- Generate release notes from actual code changes
+- Update CHANGELOG.md
+- Guide through commit, tag, and push steps
+
+Usage:
+
+```
+/plainx-release
+/plainx-release --major
+/plainx-release --minor
+/plainx-release --patch
+```

plainx_dev-0.1.0/README.md

@@ -0,0 +1,33 @@
+# plainx-dev
+
+Development tools for plainx package developers.
+
+## Installation
+
+Add as a dev dependency:
+
+```bash
+uv add --dev plainx-dev
+```
+
+## Skills
+
+After installing, run `plain agent install` to copy skills to your `.claude/` directory.
+
+### /plainx-release
+
+A release workflow skill that helps you:
+
+- Analyze commits and suggest version bump type (major/minor/patch)
+- Generate release notes from actual code changes
+- Update CHANGELOG.md
+- Guide through commit, tag, and push steps
+
+Usage:
+
+```
+/plainx-release
+/plainx-release --major
+/plainx-release --minor
+/plainx-release --patch
+```

plainx_dev-0.1.0/plainx/dev/CHANGELOG.md

@@ -0,0 +1,11 @@
+# plainx-dev changelog
+
+## [0.1.0](https://github.com/dropseed/plain/releases/plainx-dev@0.1.0) (2026-02-05)
+
+Initial release.
+
+- `/plainx-release` skill for releasing plainx packages with guided workflow
+- Version bump suggestions based on commit analysis
+- First release detection (0.0.0 convention)
+- Changelog generation from code diffs
+- GitHub Actions workflow template for PyPI trusted publishing

plainx_dev-0.1.0/plainx/dev/agents/.claude/skills/plainx-release/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: plainx-release
+description: Releases plainx packages with version suggestions, changelog generation, and git tagging. Use when releasing a package to PyPI.
+---
+
+# Release Package
+
+Release a plainx package with version bumping, changelog generation, and git tagging.
+
+## Arguments
+
+```
+/plainx-release [--major|--minor|--patch]
+```
+
+- No args: analyze commits and prompt for version type
+- `--major`: auto-select major release
+- `--minor`: auto-select minor release
+- `--patch`: auto-select patch release
+
+## Scripts
+
+| Script             | Purpose                                             |
+| ------------------ | --------------------------------------------------- |
+| `get-package-info` | Get package metadata and commits since last release |
+
+## Workflow
+
+### Phase 1: Check Preconditions
+
+1. Check git status is clean:
+
+    ```
+    git status --porcelain
+    ```
+
+    If not clean, stop and ask user to commit or stash changes.
+
+### Phase 2: Get Package Info
+
+```
+uv run ./.claude/skills/plainx-release/get-package-info
+```
+
+This outputs JSON with:
+
+- `name`: Package name from pyproject.toml
+- `current_version`: Current version
+- `changelog_path`: Path to CHANGELOG.md
+- `last_tag`: Most recent git tag for this package
+- `repo_url`: GitHub URL (extracted from pyproject.toml)
+- `commits`: List of commits since last tag (excluding tests)
+
+If no commits since last release, inform the user and stop.
+
+### Phase 2b: First Release Detection
+
+If `current_version` is `0.0.0`, this is the **first release**:
+
+1. Inform the user: "This package has never been released (version 0.0.0)."
+2. Ask what version to release:
+    - **0.1.0** - First development release (recommended for most packages)
+    - **1.0.0** - First stable release (if the package is already production-ready)
+3. Skip to Phase 4 with the chosen version (use `uv version <version>` to set it directly)
+
+### Phase 3: Collect Release Decision
+
+1. Display the commits since last release
+2. **Analyze commits and suggest release type**:
+    - **Major**: breaking changes, major API redesigns, significant removals
+    - **Minor**: new features, significant additions, new APIs
+    - **Patch**: small bugfixes, minor tweaks, documentation updates, refactors
+3. Ask user to confirm or adjust (major/minor/patch/skip)
+    - If `--major`, `--minor`, or `--patch` was passed, auto-select that type
+    - If user chooses to skip, stop
+
+### Phase 4: Set Version
+
+For first releases (from 0.0.0):
+
+```
+uv version <version>
+```
+
+Where `<version>` is the chosen version like `0.1.0` or `1.0.0`.
+
+For subsequent releases:
+
+```
+uv version --bump <type>
+```
+
+Where `<type>` is `major`, `minor`, or `patch`.
+
+### Phase 5: Generate Release Notes
+
+1. Get the new version:
+
+    ```
+    uv version --short
+    ```
+
+2. Get the file changes since the last release:
+
+    ```
+    git diff <last_tag>..HEAD -- . ":(exclude)tests"
+    ```
+
+    If no `last_tag`, use the initial commit or recent history.
+
+3. Read the existing `<changelog_path>` file.
+
+4. Prepend a new release entry to the changelog.
+
+**For first releases:**
+
+```
+## [<new_version>](<repo_url>/releases/v<new_version>) (<today's date>)
+
+Initial release.
+
+- Brief summary of what the package provides
+- Key features or capabilities
+```
+
+**For subsequent releases:**
+
+```
+## [<new_version>](<repo_url>/releases/v<new_version>) (<today's date>)
+
+### What's changed
+
+- Summarize user-facing changes based on the actual diff (not just commit messages)
+- Include commit hash links: ([abc1234](<repo_url>/commit/abc1234))
+- Skip test changes, internal refactors that don't affect public API
+
+### Upgrade instructions
+
+- Specific steps if any API changed
+- If no changes required: "- No changes required."
+```
+
+### Phase 6: Commit, Tag, and Push
+
+Guide the user through these steps explicitly:
+
+1. **Stage files**:
+
+    ```
+    git add pyproject.toml <changelog_path> uv.lock
+    ```
+
+2. **Show what will be committed**:
+
+    ```
+    git diff --cached --stat
+    ```
+
+3. **Create commit**:
+
+    ```
+    git commit -m "Release v<new_version>"
+    ```
+
+4. **Create tag**:
+
+    ```
+    git tag -a v<new_version> -m "Release v<new_version>"
+    ```
+
+5. **GitHub Workflow Setup (first release only)**:
+
+    Check if `.github/workflows/release.yml` exists. If not, ask:
+
+    > "No release workflow found. Would you like to set up GitHub Actions to publish to PyPI when you push a tag?"
+
+    If yes, copy `.claude/skills/plainx-release/release-workflow.yml` to `.github/workflows/release.yml`, then amend the commit:
+
+    ```
+    git add .github/workflows/release.yml
+    git commit --amend --no-edit
+    git tag -fa v<new_version> -m "Release v<new_version>"
+    ```
+
+    Remind the user to configure PyPI trusted publishing after pushing:
+    - Go to https://pypi.org/manage/account/publishing/
+    - Add trusted publisher: GitHub owner, repo name, workflow "release.yml" (no environment needed)
+
+6. **Push commit and tag**:
+    ```
+    git push && git push --tags
+    ```
+
+Ask user to confirm before each destructive step (commit, push).
+
+### Phase 7: GitHub Release (Optional)
+
+After pushing, wait for the GitHub workflow to publish to PyPI. Once published, ask the user if they want to create a GitHub release:
+
+```
+gh release create v<new_version> --notes "<changelog entry summary>"
+```
+
+Or to use the full changelog entry from the file, extract and pass it manually.
+
+## Release Type Guidelines
+
+Consider the current version when suggesting release types:
+
+### Pre-1.0 packages (0.x.y)
+
+Most packages stay pre-1.0 for a long time. For these packages:
+
+- **Minor (0.x.0)**: New features, breaking changes, new APIs, significant additions
+- **Patch (0.0.x)**: Bugfixes, minor tweaks, documentation, refactors
+- **Major (1.0.0)**: Only suggest if the user explicitly wants to mark the package as stable/production-ready
+
+### Post-1.0 packages (x.y.z where x >= 1)
+
+Once a package has reached 1.0, follow semver strictly:
+
+- **Major (x.0.0)**: Breaking changes, API removals, incompatible changes
+- **Minor (x.y.0)**: New features, new APIs, backwards-compatible additions
+- **Patch (x.y.z)**: Bugfixes, minor tweaks, documentation, refactors
+
+### Commit message indicators
+
+- Breaking/major indicators: "breaking", "remove", "rename API", "redesign", "incompatible"
+- Feature/minor indicators: "add", "new", "feature", "implement"
+- Fix/patch indicators: "fix", "bugfix", "typo", "docs", "refactor", "update"

plainx_dev-0.1.0/plainx/dev/agents/.claude/skills/plainx-release/get-package-info

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""
+Get package metadata and commits since last release.
+
+Outputs JSON with package info for the current directory's pyproject.toml.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib
+
+
+def run(cmd: list[str], cwd: Path | None = None) -> str:
+    """Run a command and return stdout."""
+    result = subprocess.run(cmd, capture_output=True, text=True, cwd=cwd)
+    return result.stdout.strip()
+
+
+def get_package_name(pyproject: dict) -> str:
+    """Get the package name from pyproject.toml."""
+    return pyproject.get("project", {}).get("name", "")
+
+
+def get_current_version() -> str:
+    """Get the current version using uv."""
+    return run(["uv", "version", "--short"])
+
+
+def get_repo_url(pyproject: dict) -> str | None:
+    """Extract GitHub repo URL from pyproject.toml."""
+    project = pyproject.get("project", {})
+
+    # Check project.urls
+    urls = project.get("urls", {})
+    for key in ["Repository", "repository", "Source", "source", "GitHub", "github"]:
+        if key in urls:
+            url = urls[key]
+            # Normalize to https://github.com/owner/repo format
+            if "github.com" in url:
+                return url.rstrip("/").rstrip(".git")
+
+    # Check project.homepage
+    homepage = project.get("homepage", "")
+    if "github.com" in homepage:
+        return homepage.rstrip("/").rstrip(".git")
+
+    return None
+
+
+def get_changelog_path() -> str:
+    """Find the CHANGELOG.md file."""
+    root = Path.cwd()
+
+    # Common locations
+    candidates = [
+        root / "CHANGELOG.md",
+        root / "changelog.md",
+    ]
+
+    # Check for package-specific changelog (src layout or namespace package)
+    for pyproject_path in [root / "pyproject.toml"]:
+        if pyproject_path.exists():
+            with open(pyproject_path, "rb") as f:
+                pyproject = tomllib.load(f)
+            name = get_package_name(pyproject)
+            if name:
+                # Handle namespace packages like plainx.sentry -> plainx/sentry
+                parts = name.replace(".", "/").replace("-", "/")
+                candidates.extend([
+                    root / parts / "CHANGELOG.md",
+                    root / "src" / parts / "CHANGELOG.md",
+                ])
+
+    for path in candidates:
+        if path.exists():
+            return str(path.relative_to(root))
+
+    # Default to root CHANGELOG.md even if it doesn't exist yet
+    return "CHANGELOG.md"
+
+
+def get_last_tag(name: str) -> str | None:
+    """Get the most recent release tag for this package."""
+    # Try v-prefixed tags first (most common for single-package repos)
+    output = run(["git", "tag", "-l", "v*", "--sort=-v:refname"])
+    tags = [t for t in output.split("\n") if t]
+    if tags:
+        return tags[0]
+
+    # Fall back to name@version format (monorepo style)
+    output = run(["git", "tag", "-l", f"{name}@*", "--sort=-v:refname"])
+    tags = [t for t in output.split("\n") if t]
+    if tags:
+        return tags[0]
+
+    return None
+
+
+def get_commits_since(since_ref: str | None) -> list[dict]:
+    """Get commits since a given ref, excluding tests."""
+    if since_ref:
+        cmd = [
+            "git", "log", "--format=%H|%s",
+            f"{since_ref}..HEAD",
+            "--", ".",
+            ":(exclude)tests",
+            ":(exclude)**/tests",
+        ]
+    else:
+        # No previous tag, get recent commits
+        cmd = [
+            "git", "log", "--format=%H|%s",
+            "-n", "50",
+            "--", ".",
+            ":(exclude)tests",
+            ":(exclude)**/tests",
+        ]
+
+    output = run(cmd)
+
+    commits = []
+    for line in output.split("\n"):
+        if "|" in line:
+            hash_, subject = line.split("|", 1)
+            commits.append({
+                "hash": hash_[:12],
+                "subject": subject
+            })
+
+    return commits
+
+
+def main():
+    root = Path.cwd()
+    pyproject_path = root / "pyproject.toml"
+
+    if not pyproject_path.exists():
+        print(json.dumps({"error": "No pyproject.toml found in current directory"}))
+        sys.exit(1)
+
+    with open(pyproject_path, "rb") as f:
+        pyproject = tomllib.load(f)
+
+    name = get_package_name(pyproject)
+    if not name:
+        print(json.dumps({"error": "No project.name found in pyproject.toml"}))
+        sys.exit(1)
+
+    current_version = get_current_version()
+    changelog_path = get_changelog_path()
+    last_tag = get_last_tag(name)
+    repo_url = get_repo_url(pyproject)
+    commits = get_commits_since(last_tag)
+
+    result = {
+        "name": name,
+        "current_version": current_version,
+        "changelog_path": changelog_path,
+        "last_tag": last_tag,
+        "repo_url": repo_url,
+        "commits": commits,
+    }
+
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

plainx_dev-0.1.0/plainx/dev/agents/.claude/skills/plainx-release/release-workflow.yml

@@ -0,0 +1,32 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv python install
+
+      # https://docs.pypi.org/trusted-publishers/using-a-publisher/
+      - name: Mint API token
+        id: mint-token
+        run: |
+          resp=$(curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
+            "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=pypi")
+          oidc_token=$(jq -r '.value' <<< "${resp}")
+          resp=$(curl -X POST https://pypi.org/_/oidc/mint-token -d "{\"token\": \"${oidc_token}\"}")
+          api_token=$(jq -r '.token' <<< "${resp}")
+          echo "::add-mask::${api_token}"
+          echo "api-token=${api_token}" >> "${GITHUB_OUTPUT}"
+
+      - run: uv build && uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ steps.mint-token.outputs.api-token }}

plainx_dev-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "plainx.dev"
+version = "0.1.0"
+description = "Development tools for plainx package developers, including release automation."
+authors = [{name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev"}]
+license = "BSD-3-Clause"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = []
+
+[tool.hatch.build.targets.wheel]
+packages = ["plainx"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"