stitch-lineage 0.3.0__tar.gz

stitch_lineage-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Format
+        run: ruff format --check .
+      - name: Architecture seams
+        run: lint-imports
+      - name: Tests
+        run: pytest -q

stitch_lineage-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,86 @@
+name: Publish to PyPI
+
+# Publishes via PyPI Trusted Publishing (OIDC) — no API token is stored anywhere.
+#
+# The publisher registered on pypi.org pins these exact names; changing any of them breaks
+# the trust relationship and the upload is rejected:
+#   project: stitch-lineage, owner: sverrbear, repo: stitch-lineage,
+#   workflow: publish.yml, environment: pypi
+#
+# Releasing = push a v* tag. `git tag v0.3.0 && git push origin v0.3.0` runs this; creating a
+# GitHub release from a new tag pushes the tag too, so that path still works. Tagging is the
+# whole trigger, so the tag must already match the version in pyproject.toml — the first job
+# refuses to build otherwise, before anything can reach PyPI.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Verify the tag matches the pyproject version
+        run: |
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "${GITHUB_REF_NAME}" != "v${version}" ]; then
+            echo "::error::tag '${GITHUB_REF_NAME}' does not match pyproject version 'v${version}'"
+            exit 1
+          fi
+
+      - run: python -m pip install build twine
+      - run: python -m build
+
+      # The worst failure mode this package has is publishing a `stitch serve` with no UI:
+      # the frontend dist/ is gitignored and only reaches the wheel because hatchling is told
+      # to treat it as an artifact, so a packaging change can drop it silently and nothing
+      # else would notice until a user installed it. Fail the release instead.
+      - name: Verify the built frontend is inside the wheel
+        run: |
+          wheel=$(ls dist/*.whl)
+          echo "checking $wheel"
+          if ! unzip -l "$wheel" | grep -q 'stitch_lineage/app/frontend/dist/index.html'; then
+            echo "::error::$wheel has no stitch_lineage/app/frontend/dist/index.html -- 'stitch serve' would ship with no UI. Rebuild the frontend (npm run build) and commit dist/ before tagging."
+            unzip -l "$wheel"
+            exit 1
+          fi
+          # index.html alone is a shell: without the hashed bundles the app loads to a blank page
+          assets=$(unzip -l "$wheel" | grep -c 'stitch_lineage/app/frontend/dist/assets/' || true)
+          if [ "$assets" -lt 2 ]; then
+            echo "::error::$wheel carries index.html but only $assets file(s) under dist/assets/ -- the app would not load."
+            exit 1
+          fi
+          echo "frontend files in the wheel:"
+          unzip -l "$wheel" | grep 'stitch_lineage/app/frontend/dist/'
+
+      - name: Check the package metadata renders on PyPI
+        run: twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/stitch-lineage
+    permissions:
+      id-token: write # the OIDC token the trusted publisher exchanges; no password anywhere
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

stitch_lineage-0.3.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+/dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# stitch runtime
+.stitch/cache/
+
+# Node (app/frontend)
+node_modules/
+
+# Env & editor
+.env
+.DS_Store
+.idea/
+.vscode/

stitch_lineage-0.3.0/CLAUDE.md

@@ -0,0 +1,32 @@
+# CLAUDE.md
+
+stitch: dbt ↔ Metabase column lineage + interactive ERD. Local-first; the dbt repo is the database. `SPEC.md` is the design truth (v0.5) — **Claude owns SPEC.md as Sverrir's master agent** and updates it via docs PRs whenever decisions diverge from it.
+
+## Session bootstrap (after a context clear)
+
+1. Read this file and `SPEC.md`, then `gh issue list` + `gh pr list` for live state.
+2. Re-arm a ~20-minute session cron that fires the reconciliation checklist below at the main session. (The delivery-manager subagent is retired — do not respawn it.)
+3. Coding work continues issue-by-issue with Opus worktree agents (below). The main session orchestrates and handles git only — it does not hand-write code (saves Fable quota).
+
+## The workflow
+
+- **GitHub issues are the unit of work.** User feedback → issue (concise, factual, labeled bug/enhancement + phase-N/backlog). Issues are also derived from SPEC.md gaps.
+- **Reconciliation passes** run in the main session on a ~20-min cron, with plain `gh` commands: detect merged/closed PRs, close + re-label issues (merges to non-default branches don't fire "Fixes #N" — close manually), verify issue↔PR links, re-sync open PR branches staled by a merge, check agent liveness by worktree diff evidence (dead agents are resumed by SendMessage to their name — never cloned into a shared worktree), surface material updates only.
+- **Coding agents are Opus**, one per issue (or one per coherent group), each in its own git worktree: `git -C <repo> worktree add ~/Desktop/stitch-worktrees/<name> -b <branch> origin/main`, own `.venv` (`pip install -e ".[dev]"`), frontend work also `npm install` in `stitch_lineage/app/frontend`.
+- **One individually mergeable PR per issue**, body starts `Fixes #N`. **Never stack PRs** — every PR branches from origin/main with base `main` and stands alone. Lanes touching the committed frontend `dist/` still work one issue at a time (one dist rebuild per PR); dist conflicts between open PRs are expected and resolved by the post-merge re-sync (merge origin/main, rebuild `dist/`, push). Conventional commits ending `Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>`.
+- **Nobody merges except Sverrir.** Ever. Agents push + open PRs and stop.
+- **Branch protection on main**: 1 review + green `test` check + **strict up-to-date-with-main** — every merge stales the remaining PRs. Re-sync survivors after each merge, or consolidate several green PRs into one release PR (precedent: #42) when the user wants one click.
+
+## Quality gates (every PR)
+
+- `pytest -q` full suite, `ruff check .`, `ruff format --check .`, `lint-imports` (architecture seams — SPEC §4) all green in the worktree.
+- Frontend: `npm run typecheck`, `npm test`, `npm run build`, rebuilt `dist/` committed (git-install distribution — the wheel/repo must carry the built app).
+- UI changes: **visual verification against the real graph** (`~/Desktop/data/.stitch/graph.json`, read-only) with before/after screenshots in the PR body.
+- Public repo: **never commit real Smitten data** (card titles, column names) — synthetic shape-only fixtures; screenshots in PR bodies are fine.
+- Real-world resolution claims get measured numbers in the PR body (e.g. cards resolved before/after against the cached payload).
+
+## Using stitch on the Smitten data repo (`~/Desktop/data`)
+
+- Config: `stitch.yml` at that repo's root (Metabase "Analytics" ↔ `DEV_DBT`, `table_prefix: ${USER_PREFIX}_`, `auto_docs: true`, `serve.erd_default_scope`). Env: `METABASE_API_KEY` in `.env`.
+- `stitch build` runs `dbt docs generate` (dev target → **one MFA push to Sverrir's phone — warn him first**); `stitch build --no-docs` reuses artifacts with no MFA. `.stitch/` is fully local, never committed.
+- `stitch serve` → http://127.0.0.1:8787.

stitch_lineage-0.3.0/LICENSE

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