jj-stack 0.1.0__tar.gz

jj_stack-0.1.0/.github/SECURITY.md

@@ -0,0 +1,20 @@
+# Security Policy
+
+## Supported Versions
+
+This project is under active development. Security fixes are supported on `main`.
+
+## Reporting a Vulnerability
+
+Please do not report security vulnerabilities in public GitHub issues.
+
+Use GitHub's private vulnerability reporting for this repo if it is enabled. If you cannot
+use private reporting, contact the maintainers directly and include:
+
+- a description of the issue
+- steps to reproduce or a proof of concept
+- the affected version or environment details
+- any suggested mitigations or fixes you have identified
+
+We will investigate reports on a best-effort basis and coordinate on disclosure before any public
+announcement.

jj_stack-0.1.0/.github/dependabot.yml

@@ -0,0 +1,28 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+    commit-message:
+      prefix: "ci"
+
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+    versioning-strategy: "increase-if-necessary"
+    commit-message:
+      prefix: "deps"

jj_stack-0.1.0/.github/workflows/block-pr-base-merges.yml

@@ -0,0 +1,24 @@
+name: block-pr-base-merges
+
+on:
+  pull_request_target:
+    branches:
+      - "jj-stack/**"
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - edited
+      - ready_for_review
+
+jobs:
+  reject-pr-base-merge:
+    name: reject-pr-base-merge
+    runs-on: ubuntu-latest
+    permissions: {}
+    steps:
+      - name: Explain policy and fail
+        run: |
+          echo "PRs targeting jj-stack/* are based on another PR and must not be merged directly."
+          echo "Retarget this PR to main or another allowed base branch."
+          exit 1

jj_stack-0.1.0/.github/workflows/check-jj-release-updates.yml

@@ -0,0 +1,24 @@
+name: check jj release updates
+
+on:
+  schedule:
+    - cron: "23 7 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  check-jj-release-updates:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Check tested jj versions against the latest release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          REPOSITORY: ${{ github.repository }}
+        run: python tools/check_jj_release_updates.py --write-issues

jj_stack-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,95 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  complexity:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: "3.14"
+
+      - name: Install tokei
+        env:
+          # Must match TOKEI_VERSION in tools/check_complexity.py; the budgets are baselined
+          # against this exact counter. 14.0.0 publishes no prebuilt binaries, so build it.
+          TOKEI_VERSION: 14.0.0
+        run: cargo install tokei --locked --version "$TOKEI_VERSION"
+
+      - name: Install project environment
+        run: uv sync --locked
+
+      - name: Enforce complexity budgets
+        run: uv run tools/check_complexity.py
+
+  check:
+    strategy:
+      fail-fast: false
+      matrix:
+        jj-version: ["v0.44.0"]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.14"]
+    runs-on: ${{ matrix.os }}
+    env:
+      JJ_VERSION: ${{ matrix.jj-version }}
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install jj
+        shell: bash
+        run: |
+          install_dir="$(tools/install-jj-release.sh "$JJ_VERSION")"
+          if command -v cygpath >/dev/null 2>&1; then
+            install_dir="$(cygpath -w "$install_dir")"
+          fi
+          printf '%s\n' "$install_dir" >> "$GITHUB_PATH"
+
+      - name: Run local verification suite
+        shell: bash
+        run: ./check.py
+
+  submit-property-smoke:
+    runs-on: ubuntu-latest
+    env:
+      JJ_VERSION: v0.44.0
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: "3.14"
+
+      - name: Install jj
+        run: echo "$(tools/install-jj-release.sh "$JJ_VERSION")" >> "$GITHUB_PATH"
+
+      - name: Run submit property smoke scenarios
+        run: >-
+          tests/run_submit_property_scenarios.py 10 --random-seed -n auto
+          --stack-join-scenarios 5
+          --lifecycle-scenarios 10
+          --stack-move-scenarios 5
+          --retry-scenarios 5
+          --drift-scenarios 21

jj_stack-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,32 @@
+name: codeql
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  schedule:
+    - cron: "31 7 * * 1"
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: analyze
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4.37.3
+        with:
+          languages: python
+          build-mode: none
+
+      - name: Analyze
+        uses: github/codeql-action/analyze@v4.37.3

jj_stack-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,149 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  JJ_VERSION: v0.44.0
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: "3.14"
+
+      - name: Verify tag matches package version
+        if: startsWith(github.ref, 'refs/tags/v')
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: test "$RELEASE_TAG" = "v$(uv version --short)"
+
+      - name: Verify tagged commit is on main
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: git merge-base --is-ancestor HEAD refs/remotes/origin/main
+
+      - name: Install jj
+        run: echo "$(tools/install-jj-release.sh "$JJ_VERSION")" >> "$GITHUB_PATH"
+
+      - name: Run local verification suite
+        run: ./check.py
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Test built distributions
+        run: python tools/check_release_artifacts.py
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 7
+
+  publish-testpypi:
+    if: github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      id-token: write
+    environment:
+      name: testpypi
+
+    steps:
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: "3.14"
+
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to TestPyPI
+        run: >
+          uv publish
+          --trusted-publishing always
+          --publish-url https://test.pypi.org/legacy/
+          --check-url https://test.pypi.org/simple/
+          dist/*
+
+  publish-pypi:
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      id-token: write
+    environment:
+      name: pypi
+
+    steps:
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: "3.14"
+
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI
+        run: >
+          uv publish
+          --trusted-publishing always
+          --check-url https://pypi.org/simple/
+          dist/*
+
+  publish-github-release:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          if ! gh release view "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            gh release create "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" --verify-tag \
+              --generate-notes --title "$RELEASE_TAG"
+          fi
+          gh release upload "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" --clobber dist/*

jj_stack-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+.coverage
+.claude/
+htmlcov/
+.pytest_cache/
+.roam/
+.ruff_cache/
+.tmp/
+.ty_cache/
+.uv-cache/
+.venv
+.venv/

jj_stack-0.1.0/AGENTS.md

@@ -0,0 +1,96 @@
+# Work in progress
+
+This project is under heavy development. Do not make any attempt to write backwards
+compatibility code, migration code, or the like.
+
+## Complexity control
+
+- A replacement is incomplete until it deletes the mechanism it supersedes in the same change.
+  Do not add a temporary parallel model with a promise to remove it in a later cleanup slice.
+- Define each jj-stack-owned durable policy fact once and store it one way. Shared observation or
+  storage code must not create a second path for deciding or changing it.
+- Batch independent read-only facts, but keep dependent mutations in order. Bind an irreversible
+  external mutation to the identity and version observed while planning when the platform
+  supports a conditional write or lease. Re-observe only when an earlier mutation invalidates a
+  precondition or when an observed trigger or platform contract requires it.
+- Apply the cumulative complexity budgets after every code slice. CI runs
+  `uv run tools/check_complexity.py`; run it locally when the pinned `tokei` is installed. A
+  budget increase is a design stop that requires explicit review, not routine maintenance of the
+  budget file.
+- If the same subsystem needs a third consecutive hardening change, stop patching it and
+  re-derive the design from the core invariants.
+
+# Workflow
+
+- This is a `jj` repo. Do not use `git` to work on the repo itself.
+- Do not use git worktree-based agent isolation in this repo. For isolated parallel work, use
+  `jj workspace` instead.
+- Run the CLI locally with `uv run jj-stack ...` instead of invoking the module or virtualenv
+  path directly.
+- Hard-wrap code and markdown files at 98 columns unless a file uses a different convention.
+
+# Commit messages
+
+- Format the first line as a concise scoped subject, usually `scope: summary`.
+- Match the repo's existing subject style: use a lowercase scope such as `status`, `docs`, or
+  `cli`, followed by a short lowercase phrase, with no trailing period.
+- Use a body for any change whose purpose is not obvious from the subject and diff.
+- Hard-wrap commit message bodies at 72 columns.
+- The body should explain the motivation for the change, the intended behavior or design outcome,
+  and any important scope or design constraints.
+- Do not use the body to narrate the code or to record routine validation such as `./check.py`.
+- Prefer explaining why the commit exists and what rule or user-visible behavior it is enforcing.
+
+# Documentation
+
+- User-facing docs live in `docs/`. See [docs/AGENTS.md](docs/AGENTS.md) for the vocabulary
+  rules and the public/internal split. Built-in `--help` text is held to the same standard as
+  the user docs: assume jj/git familiarity, avoid `jj-stack` internal design jargon.
+- The web version of the user docs normally lives in the sibling jj repository at
+  `$(jj root)/../website`. When user-facing docs change here, inspect and update the corresponding
+  web docs there too when needed. If the change here is committed, commit the corresponding
+  website update in that repository as well; preserve unrelated work in either working copy.
+- Active internal docs use ordinary technical language too. Introduce a project-specific term
+  only when it names a real type, field, or enduring rule, define it at first use, and prefer
+  describing concrete inputs and effects.
+- `design.md` and `implementation-strategy.md` describe the current product and architecture, not
+  completed slices or abandoned mechanisms. Keep implementation history in `jj` commits.
+- Default to code and tests only. Update documentation only when a change intentionally adds or
+  changes a supported product rule or user workflow, or makes a specific existing statement
+  materially inaccurate. A bug and its fix are not by themselves a documentation trigger.
+- When documentation is required, update only the affected source: `design.md` for an enduring
+  product rule, user docs or `--help` for user guidance, and `implementation-strategy.md` for an
+  architecture, tooling, or test-layer strategy change.
+
+# Behaviour changes
+
+- In user-facing output, identify revisions by `change_id` by default. If a concrete immutable
+  snapshot matters, include the `commit_id` second and label it explicitly.
+- Read [docs/internals/design.md](docs/internals/design.md) before intentionally changing product
+  semantics or adding tests for product behavior. Design prose is derived from principles, not
+  the other way around: evaluate a documented behavior on its merits before extending it, and
+  prefer deleting case-specific rules that follow from the principles over adding new ones. Never
+  add durable transaction or replay state; recovery is observational (see design.md).
+- Preserve the core invariants: the `jj` DAG determines stack topology, local cache is sparse,
+  GitHub pull requests are derived from the local `jj` stack, and ambiguous linkage fails closed.
+
+# Testing
+
+- Run `./check.py` before finishing a code change. Docs-only edits under `docs/` do not require
+  a test run.
+- Run `./check.py` for the default local Ruff, type-check, and test pass before finishing a
+  code change.
+- For focused test runs, do not use plain `uv run pytest ...`; it can miss the repo's package
+  path in this project layout. First run `uv sync --locked`, then invoke pytest through the repo
+  virtualenv, for example `.venv/bin/python -m pytest tests/unit/test_jj_client.py`.
+- Before adding, modifying, removing, or reviewing tests, fixtures, helpers, or property
+  scenarios, read and follow
+  [docs/internals/testing-philosophy.md](docs/internals/testing-philosophy.md). Add or retain
+  coverage only for a distinct worthwhile risk at the narrowest meaningful layer; search for and
+  consolidate overlapping coverage first. For property-harness changes, also follow
+  [docs/internals/property-testing.md](docs/internals/property-testing.md).
+
+# Code reviews
+
+- When reviewing changes or existing code, read and follow
+  [docs/internals/code-reviews.md](docs/internals/code-reviews.md).

jj_stack-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md