stateforge-dpt 0.1.0__tar.gz

stateforge_dpt-0.1.0/.env.example

@@ -0,0 +1,10 @@
+STATEFORGE_DPT_HOST=127.0.0.1
+STATEFORGE_DPT_PORT=8463
+# Save user configuration in ~/.stateforge-dpt/.env. Paths are independent of cwd.
+# Defaults: data in ~/.stateforge-dpt; clones in ~/.stateforge-dpt/projects/.
+# STATEFORGE_DPT_DATA_DIR=~/.stateforge-dpt
+# STATEFORGE_DPT_WORKING_DIRECTORY=~/.stateforge-dpt
+# Optional override; installed releases include the built frontend.
+# STATEFORGE_DPT_FRONTEND_DIR=/absolute/path/to/frontend/dist
+# Optional override for a different GitHub App.
+STATEFORGE_DPT_GITHUB_CLIENT_ID=Iv23lidYTyPNl3LWbjTI

stateforge_dpt-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.DS_Store
+.env
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+node_modules/
+frontend/dist/
+.stateforge-dpt/
+projects/
+idea/

stateforge_dpt-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.5
+Name: stateforge-dpt
+Version: 0.1.0
+Summary: Local development progress control for StateForge repositories.
+Project-URL: Repository, https://github.com/stateforge-org/stateforge-dpt
+Project-URL: Issues, https://github.com/stateforge-org/stateforge-dpt/issues
+Keywords: development,git,github,planning,project-management
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=44.0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic>=2.10
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: uvicorn>=0.34
+Description-Content-Type: text/markdown
+
+# StateForge DPT
+
+StateForge Development Progress Tracking is a local-first control application
+for coordinating work across the StateForge repositories.
+
+DPT edits the implementation plan locally, publishes its complete portable
+manifest into an identical `STATEFORGE_DPT.md` in every managed repository, and
+derives delivery progress from issues, pull requests, reviews, checks, and merge
+evidence retrieved from GitHub.
+
+## Run DPT
+
+DPT is packaged for Linux, macOS, and Windows. Requirements are Python 3.11 or
+newer and Git 2.31 or newer on PATH. Node.js is only needed when developing or
+building a release, not when installing and running DPT.
+
+Once the first release is published to PyPI:
+
+```bash
+python -m pip install stateforge-dpt
+stateforge-dpt run
+```
+
+On macOS/Linux, use `python3` if that is your Python command. On Windows, you can
+use `py -m pip install stateforge-dpt` and `py -m stateforge_dpt run` if the
+console command is not on PATH. A virtual environment is recommended; do not use
+`sudo pip install`. Before PyPI publication, install a downloaded wheel with
+`python -m pip install /path/to/stateforge_dpt-0.1.0-py3-none-any.whl`.
+
+Run `stateforge-dpt run` from any directory, then open
+[http://127.0.0.1:8463](http://127.0.0.1:8463) in your browser. The command prints
+the browser address and workspace locations at startup. Installed release wheels
+include the frontend; no separate frontend server is needed.
+
+By default, the SQLite working copy and encrypted GitHub credentials live in
+`~/.stateforge-dpt/`. Suggested clones live under
+`~/.stateforge-dpt/projects/<PROJECT_NAME>/<REPOSITORY_NAME>`.
+
+User configuration is read from `~/.stateforge-dpt/.env`, with environment
+variables taking precedence. Editable source installations also read the
+checkout's `.env` as a lower-priority development configuration. Relative paths
+in a configuration file are resolved beside that file, never against the launch
+directory. Relative environment paths are resolved under `~/.stateforge-dpt/`.
+See [.env.example](.env.example) for overrides.
+
+Existing databases are not moved or overwritten. To open a previous workspace:
+
+```bash
+stateforge-dpt run --data-dir /absolute/path/to/previous/.stateforge-dpt
+```
+
+The `--working-directory` option changes the parent workspace for suggested
+clones without changing the data directory.
+
+## Development and packaging
+
+```bash
+python3.11 -m venv .venv
+. .venv/bin/activate
+cd frontend && npm install && npm run build && cd ..
+python -m pip install -e .
+stateforge-dpt run
+```
+
+Build the frontend before building a Python release (`python -m build`). Both
+wheels and source distributions carry that build, so installing them does not
+require Node.js. A missing frontend build produces an actionable startup error
+instead of a server that returns 404 at its home page.
+
+The package workflow builds the frontend, creates a wheel and source
+distribution, checks their metadata, and installs the same wheel on Linux,
+macOS, and Windows using Python 3.11–3.14. Each environment runs the test suite
+and starts the installed console command from an unrelated directory to check
+the frontend, JavaScript, CSS, favicon, API, and default data directory.
+
+### Publish a release
+
+Publishing is manual; ordinary pushes and pull requests never upload to PyPI.
+Create the pending `stateforge-dpt` project in PyPI's Trusted Publishing settings
+with owner `stateforge-org`, repository `stateforge-dpt`, workflow `publish.yml`,
+and environment `pypi`. Configure the equivalent publisher on TestPyPI with
+environment `testpypi`. Protect these GitHub environments with required reviewer
+approval. No permanent PyPI token needs to be stored in the repository.
+
+Then run **Publish pip package (manual)** in GitHub Actions, choosing TestPyPI
+first. The workflow rebuilds and tests the distributions on all three operating
+systems before publishing. Choose PyPI for the production release. Increment
+the version in `pyproject.toml` for subsequent releases; PyPI versions cannot be
+overwritten. See [PyPI's Trusted Publishing guide](https://docs.pypi.org/trusted-publishers/).
+
+Select **Continue with GitHub** and authorize the StateForge DPT GitHub App
+with the displayed one-time code. DPT uses GitHub Device Flow: no callback URL,
+client secret, or user-managed token is required. Access and refresh tokens are
+encrypted locally and never exposed to the browser.
+
+## Core authority model
+
+- Git-tracked `STATEFORGE_DPT.md` files are the portable project authority. An
+  embedded versioned manifest preserves every repository, milestone, planned
+  branch, dependency, ordering rule, project revision, and content fingerprint.
+- SQLite is each computer's local editable working copy and GitHub evidence
+  cache. DPT refuses to silently overwrite local edits or choose between
+  divergent Git copies.
+- Every project has an explicit plan source branch (for example,
+  `mvp/implementation`). Reconciliation fetches that branch and reads only its
+  `STATEFORGE_DPT.md` through Git; it never checks out, rebases, or modifies the
+  developer's current branch or working tree.
+- Importing any participating clone recreates the full project. Only that clone
+  is attached immediately; the remaining repositories are ready to clone or
+  attach on the new computer.
+- Publishing writes the next identical revision to every attached clone. Commit
+  and push those generated files normally, then merge them into the configured
+  plan source branch. Reconciliation on another computer automatically imports
+  a strictly newer, conflict-free revision into its local SQLite working copy.
+- Local unpublished edits and same-revision divergence are never overwritten;
+  DPT surfaces the existing source chooser so the user can resolve them.
+- GitHub is the authority for delivery progress, not project definition.
+- DPT validates GitHub evidence against the dependency graph and reports real
+  workflow violations.
+
+See [docs/architecture.md](docs/architecture.md) for the complete design.

stateforge_dpt-0.1.0/README.md

@@ -0,0 +1,121 @@
+# StateForge DPT
+
+StateForge Development Progress Tracking is a local-first control application
+for coordinating work across the StateForge repositories.
+
+DPT edits the implementation plan locally, publishes its complete portable
+manifest into an identical `STATEFORGE_DPT.md` in every managed repository, and
+derives delivery progress from issues, pull requests, reviews, checks, and merge
+evidence retrieved from GitHub.
+
+## Run DPT
+
+DPT is packaged for Linux, macOS, and Windows. Requirements are Python 3.11 or
+newer and Git 2.31 or newer on PATH. Node.js is only needed when developing or
+building a release, not when installing and running DPT.
+
+Once the first release is published to PyPI:
+
+```bash
+python -m pip install stateforge-dpt
+stateforge-dpt run
+```
+
+On macOS/Linux, use `python3` if that is your Python command. On Windows, you can
+use `py -m pip install stateforge-dpt` and `py -m stateforge_dpt run` if the
+console command is not on PATH. A virtual environment is recommended; do not use
+`sudo pip install`. Before PyPI publication, install a downloaded wheel with
+`python -m pip install /path/to/stateforge_dpt-0.1.0-py3-none-any.whl`.
+
+Run `stateforge-dpt run` from any directory, then open
+[http://127.0.0.1:8463](http://127.0.0.1:8463) in your browser. The command prints
+the browser address and workspace locations at startup. Installed release wheels
+include the frontend; no separate frontend server is needed.
+
+By default, the SQLite working copy and encrypted GitHub credentials live in
+`~/.stateforge-dpt/`. Suggested clones live under
+`~/.stateforge-dpt/projects/<PROJECT_NAME>/<REPOSITORY_NAME>`.
+
+User configuration is read from `~/.stateforge-dpt/.env`, with environment
+variables taking precedence. Editable source installations also read the
+checkout's `.env` as a lower-priority development configuration. Relative paths
+in a configuration file are resolved beside that file, never against the launch
+directory. Relative environment paths are resolved under `~/.stateforge-dpt/`.
+See [.env.example](.env.example) for overrides.
+
+Existing databases are not moved or overwritten. To open a previous workspace:
+
+```bash
+stateforge-dpt run --data-dir /absolute/path/to/previous/.stateforge-dpt
+```
+
+The `--working-directory` option changes the parent workspace for suggested
+clones without changing the data directory.
+
+## Development and packaging
+
+```bash
+python3.11 -m venv .venv
+. .venv/bin/activate
+cd frontend && npm install && npm run build && cd ..
+python -m pip install -e .
+stateforge-dpt run
+```
+
+Build the frontend before building a Python release (`python -m build`). Both
+wheels and source distributions carry that build, so installing them does not
+require Node.js. A missing frontend build produces an actionable startup error
+instead of a server that returns 404 at its home page.
+
+The package workflow builds the frontend, creates a wheel and source
+distribution, checks their metadata, and installs the same wheel on Linux,
+macOS, and Windows using Python 3.11–3.14. Each environment runs the test suite
+and starts the installed console command from an unrelated directory to check
+the frontend, JavaScript, CSS, favicon, API, and default data directory.
+
+### Publish a release
+
+Publishing is manual; ordinary pushes and pull requests never upload to PyPI.
+Create the pending `stateforge-dpt` project in PyPI's Trusted Publishing settings
+with owner `stateforge-org`, repository `stateforge-dpt`, workflow `publish.yml`,
+and environment `pypi`. Configure the equivalent publisher on TestPyPI with
+environment `testpypi`. Protect these GitHub environments with required reviewer
+approval. No permanent PyPI token needs to be stored in the repository.
+
+Then run **Publish pip package (manual)** in GitHub Actions, choosing TestPyPI
+first. The workflow rebuilds and tests the distributions on all three operating
+systems before publishing. Choose PyPI for the production release. Increment
+the version in `pyproject.toml` for subsequent releases; PyPI versions cannot be
+overwritten. See [PyPI's Trusted Publishing guide](https://docs.pypi.org/trusted-publishers/).
+
+Select **Continue with GitHub** and authorize the StateForge DPT GitHub App
+with the displayed one-time code. DPT uses GitHub Device Flow: no callback URL,
+client secret, or user-managed token is required. Access and refresh tokens are
+encrypted locally and never exposed to the browser.
+
+## Core authority model
+
+- Git-tracked `STATEFORGE_DPT.md` files are the portable project authority. An
+  embedded versioned manifest preserves every repository, milestone, planned
+  branch, dependency, ordering rule, project revision, and content fingerprint.
+- SQLite is each computer's local editable working copy and GitHub evidence
+  cache. DPT refuses to silently overwrite local edits or choose between
+  divergent Git copies.
+- Every project has an explicit plan source branch (for example,
+  `mvp/implementation`). Reconciliation fetches that branch and reads only its
+  `STATEFORGE_DPT.md` through Git; it never checks out, rebases, or modifies the
+  developer's current branch or working tree.
+- Importing any participating clone recreates the full project. Only that clone
+  is attached immediately; the remaining repositories are ready to clone or
+  attach on the new computer.
+- Publishing writes the next identical revision to every attached clone. Commit
+  and push those generated files normally, then merge them into the configured
+  plan source branch. Reconciliation on another computer automatically imports
+  a strictly newer, conflict-free revision into its local SQLite working copy.
+- Local unpublished edits and same-revision divergence are never overwritten;
+  DPT surfaces the existing source chooser so the user can resolve them.
+- GitHub is the authority for delivery progress, not project definition.
+- DPT validates GitHub evidence against the dependency graph and reports real
+  workflow violations.
+
+See [docs/architecture.md](docs/architecture.md) for the complete design.

stateforge_dpt-0.1.0/docs/architecture.md

@@ -0,0 +1,95 @@
+# Architecture
+
+## Process model
+
+StateForge DPT runs on the developer's machine. A FastAPI process owns SQLite,
+GitHub communication, Git operations, and controlled filesystem access. The
+browser interface communicates only with that local process.
+
+```text
+Browser interface
+       |
+Local FastAPI backend
+       +-- SQLite local working plan and audit cache
+       +-- GitHub App authentication and API reconciliation
+       +-- Git repository controller
+       +-- STATEFORGE_DPT.md renderer
+       |
+Managed local repository clones <----> GitHub
+```
+
+## Sources of authority
+
+The Git-tracked `STATEFORGE_DPT.md` is the portable project authority. Its
+invisible, versioned JSON manifest contains the lossless project definition:
+project identity and revision, repositories, delivery steps, required results,
+dependencies, planned branches, and stable ordering. A SHA-256 fingerprint
+detects divergent or modified manifests. The visible Markdown remains a
+human-readable plan and is generated identically in every attached repository.
+
+SQLite is the local working copy. It holds edits that have not been published,
+machine-specific clone paths, credentials, GitHub evidence, and audit activity.
+Publishing creates the next manifest revision in every attached clone; normal
+Git commits, pushes, pulls, and reviews distribute that revision exactly like
+source code.
+
+On another computer, importing `STATEFORGE_DPT.md` from any participating clone
+recreates all repositories and milestones. The source clone is attached and the
+remaining repositories are registered for cloning or attachment. When Git has a
+newer revision, DPT can import it. If local unpublished edits exist, or two Git
+copies claim the same revision with different fingerprints, DPT stops and asks
+the user to choose rather than silently overwriting a plan.
+
+Each project also records a portable plan source branch, conventionally the
+shared parent branch from which milestone branches are derived (for example,
+`mvp/implementation`). Reconciliation runs a narrow Git fetch in each attached
+clone and reads `STATEFORGE_DPT.md` directly from the fetched ref. It does not
+check out that ref, merge, rebase, or write any worktree file. Valid snapshots
+are checksummed and cached in SQLite. A strictly newer snapshot is imported only
+when the SQLite plan has no unpublished edits; otherwise it is presented as a
+conflict. This allows plan changes merged by another computer to appear locally
+while the developer remains on any feature branch.
+
+GitHub supplies observed execution evidence. Stable labels bind an issue or
+pull request to a DPT step:
+
+```text
+dpt:project:stateforge
+dpt:release:mvp
+dpt:step:P1
+```
+
+An open issue is pending work, an open pull request is under review, a merged
+pull request is completed work, and a closed unmerged pull request is cancelled.
+When no GitHub artifact exists, dependencies determine whether a step is ready
+or blocked. Reconciliation reports workflow violations, such as opening a pull
+request before its prerequisites are complete. Issues may be prepared in
+advance without changing the dependency graph.
+
+## Generated-file safety
+
+The renderer is deterministic. DPT records the last digest written to each
+clone and refuses to overwrite a changed generated file without an explicit
+force action. The embedded manifest is independently checksummed and parsed
+through a strict schema with duplicate, missing-dependency, and cycle checks.
+Files are written atomically. Absolute local paths, credentials, cached GitHub
+activity, and tokens never appear in the generated document.
+
+## GitHub authentication
+
+The browser requests a one-time GitHub device code from the local backend. The
+backend keeps the associated device credential encrypted, enforces GitHub's
+polling interval, and creates a session only after GitHub confirms the user.
+Access and refresh tokens are encrypted at rest. The browser receives only a
+random session identifier in an HTTP-only SameSite cookie. No GitHub client
+secret or callback endpoint is used.
+
+## Repository control
+
+A repository may be attached to an existing clone or cloned by DPT. Before it
+is accepted, DPT verifies that the path is a Git worktree and that its `origin`
+remote matches the selected GitHub repository. Repository mutations are
+performed without a shell and are presented to the user before commit or push.
+Remote plan reads use argument-based Git commands with prompting disabled. The
+current HEAD, index, untracked files, and worktree are invariant across the
+operation.