flowfield-core 0.1.0__tar.gz

flowfield_core-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,42 @@
+name: Bug report
+description: Report a problem with Flowfield.
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Search existing issues first. Remove secrets and private project content from anything you share.
+        For a security vulnerability, use [private reporting](https://github.com/flowfield-sh/flowfield-core/security/advisories/new).
+  - type: input
+    id: version
+    attributes:
+      label: Flowfield version
+      description: Run `flowfield --version`.
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: Operating system, Python version, and installation method (uv, pip, or source).
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: Give the smallest example that reproduces the problem.
+    validations:
+      required: true
+  - type: textarea
+    id: behavior
+    attributes:
+      label: Expected and actual behavior
+      description: What did you expect, and what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Logs or screenshots
+      description: Optional supporting evidence, with secrets and private content removed.

flowfield_core-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Getting Started
+    url: https://github.com/flowfield-sh/flowfield-core/blob/main/docs/getting-started.mdx
+    about: Install Flowfield, connect your coding agent, and review a task.
+  - name: Report a security vulnerability
+    url: https://github.com/flowfield-sh/flowfield-core/security/advisories/new
+    about: Send a private report to the maintainers.

flowfield_core-0.1.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,26 @@
+name: Feature request
+description: Describe an outcome Flowfield could help you achieve.
+labels: [enhancement]
+body:
+  - type: markdown
+    attributes:
+      value: Search existing issues first. Keep examples free of secrets and private project content.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What are you trying to do, and what gets in the way?
+    validations:
+      required: true
+  - type: textarea
+    id: outcome
+    attributes:
+      label: Desired outcome
+      description: What would a useful result look like?
+    validations:
+      required: true
+  - type: textarea
+    id: ideas
+    attributes:
+      label: Ideas or alternatives
+      description: Optional approaches or workarounds you have considered.

flowfield_core-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,116 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: tests-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  FLOWFIELD_UPDATE_CHECKS: '0'
+  UV_NO_SYNC: '1'
+
+jobs:
+  backend:
+    name: Python 3.12 / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, macos-15]
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: '0.9.26'
+          python-version: '3.12'
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run --no-sync pytest
+
+  quality:
+    name: Quality, docs and installed packages
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: '0.9.26'
+          python-version: '3.12'
+          enable-cache: true
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: '24'
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+        with:
+          version: '11.19.0'
+      - run: make setup
+      - name: Python quality and API contract
+        run: |
+          uv run --no-sync ruff format --check .
+          uv run --no-sync ruff check .
+          uv run --no-sync mypy
+          uv run --no-sync python scripts/generate-api-types.py --check
+      - run: pnpm --dir web check
+      - run: make docs
+      - run: make build check-dist
+      - run: uv publish --dry-run --trusted-publishing never dist/*.whl dist/*.tar.gz
+
+  browser:
+    name: Chromium journeys
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: '0.9.26'
+          python-version: '3.12'
+          enable-cache: true
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: '24'
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+        with:
+          version: '11.19.0'
+      - run: uv sync --locked
+      - run: pnpm --dir web install --frozen-lockfile
+      - run: pnpm --dir web exec playwright install --with-deps chromium
+      - run: make smoke
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        if: failure()
+        with:
+          name: browser-failures
+          path: web/test-results/
+          retention-days: 7
+
+  checked:
+    name: All checks passed
+    if: always()
+    needs: [backend, quality, browser]
+    runs-on: ubuntu-24.04
+    timeout-minutes: 2
+    steps:
+      - name: Require every check
+        env:
+          BACKEND: ${{ needs.backend.result }}
+          QUALITY: ${{ needs.quality.result }}
+          BROWSER: ${{ needs.browser.result }}
+        run: test "$BACKEND" = success && test "$QUALITY" = success && test "$BROWSER" = success

flowfield_core-0.1.0/.github/workflows/workflow.yml

@@ -0,0 +1,145 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+  # Manual runs on main rehearse the exact release artifacts without publishing.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  FLOWFIELD_UPDATE_CHECKS: '0'
+  UV_NO_SYNC: '1'
+
+jobs:
+  checks:
+    uses: ./.github/workflows/tests.yml
+
+  build:
+    needs: checks
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    outputs:
+      version: ${{ steps.identity.outputs.version }}
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: '0.9.26'
+          python-version: '3.12'
+      - run: uv sync --locked
+      - name: Verify release identity and reviewed notes
+        id: identity
+        run: uv run --no-sync python scripts/release.py --check-ci
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: '24'
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+        with:
+          version: '11.19.0'
+      - run: pnpm --dir web install --frozen-lockfile
+      - run: make build
+      - run: uv publish --dry-run --trusted-publishing never dist/*.whl dist/*.tar.gz
+      - name: Record distribution checksums
+        working-directory: dist
+        run: shasum -a 256 ./*.whl ./*.tar.gz > ../SHA256SUMS
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: release-assets
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+            release-notes.md
+            SHA256SUMS
+            scripts/check_dist.py
+            scripts/check-install.py
+          if-no-files-found: error
+          retention-days: 30
+
+  installed:
+    name: Release installs / ${{ matrix.os }}
+    needs: build
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, macos-15]
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: release-assets
+      - name: Verify original artifact bytes
+        working-directory: dist
+        run: shasum -a 256 -c ../SHA256SUMS
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: '0.9.26'
+          python-version: '3.12'
+      - name: Exercise pip wheel/source and uv tool installations without a checkout
+        env:
+          RELEASE_VERSION: ${{ needs.build.outputs.version }}
+        run: uv run --no-project --python 3.12 python scripts/check_dist.py --version "$RELEASE_VERSION"
+
+  pypi:
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    needs: [build, installed]
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/flowfield-core/
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: release-assets
+      - name: Verify original artifact bytes
+        working-directory: dist
+        run: shasum -a 256 -c ../SHA256SUMS
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: '0.9.26'
+      - name: Publish verified distributions; identical files may be retried
+        run: >-
+          uv publish --trusted-publishing always
+          --publish-url https://upload.pypi.org/legacy/
+          --check-url https://pypi.org/simple dist/*.whl dist/*.tar.gz
+
+  github:
+    needs: pypi
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: release-assets
+      - name: Verify original artifact bytes
+        working-directory: dist
+        run: shasum -a 256 -c ../SHA256SUMS
+      - name: Publish GitHub Release after PyPI succeeds
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          if ! gh release view "$RELEASE_TAG" >/dev/null 2>&1; then
+            gh release create "$RELEASE_TAG" --verify-tag --draft \
+              --title "Flowfield $RELEASE_TAG" --notes-file release-notes.md
+          fi
+          gh release upload "$RELEASE_TAG" dist/*.whl dist/*.tar.gz SHA256SUMS --clobber
+          gh release edit "$RELEASE_TAG" --draft=false --notes-file release-notes.md
+          printf 'Published flowfield-core and GitHub release %s\n' "$RELEASE_TAG" >> "$GITHUB_STEP_SUMMARY"

flowfield_core-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+node_modules/
+src/flowfield/_web/
+web/test-results/
+web/playwright-report/
+.DS_Store
+.env
+.env.*
+!.env.example
+.work/
+.idea/
+site/
+docs/.mintlify/
+release-notes.md
+SHA256SUMS

flowfield_core-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+Reviewed release notes describe changes by user impact. See CONTRIBUTING.md for versioning
+and release preparation. A version heading becomes a release when its package is published.
+
+## 0.1.0
+
+Initial Flowfield release: a shared task feed and workspace for agent software development.
+
+- Adopt existing repositories and keep task intent, activity, questions, answers and results
+  together in a durable conversation. Group tasks into milestones and track dependencies.
+- Use the board and Needs you to prioritize work, answer questions and review results.
+- Run independent tasks in isolated Git checkouts with configurable worker capacity and
+  a paused-by-default queue. Codex is the first supported worker harness.
+- Inspect and try an exact result, then explicitly approve delivery into the project checkout.
+  Changed code or destination requires fresh approval; checkout blockers retain approval.
+- Connect coordinators through MCP and installed project guidance. The CLI and web app use
+  the same local service and persisted workspace.
+- Preserve work through tested schema upgrades with verified database snapshots and guarded
+  offline recovery. Existing supported Flowfield schemas 29 and 30 upgrade to schema 31.
+- Share persistent notifications and dismissals across browsers and restarts. Check for
+  compatible PyPI releases on web startup, hourly or manually, with release links and
+  uv/pip upgrade instructions.
+
+Install with `uv tool install --python 3.12 flowfield-core`, or pip in a dedicated Python
+environment. The package bundles its browser UI and agent guidance. macOS and Linux with
+Python 3.12 are the release test targets; managed work requires an installed, signed-in
+Codex CLI. Additional harnesses are planned.
+
+**Upgrade:** stop Flowfield before changing versions and restart afterward. Supported database
+migrations run automatically after a verified snapshot; the queue starts paused. Read the installation and storage docs
+before upgrading and retain a full workspace backup for artifacts and disaster recovery.

flowfield_core-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,162 @@
+# Issues and development
+
+Bug reports, feedback and feature requests are welcome in [GitHub Issues](https://github.com/flowfield-sh/flowfield-core/issues).
+We are not accepting external pull requests at this time.
+
+For a bug, include the Flowfield version, operating system, steps to reproduce, expected
+behavior and actual behavior. Remove secrets and private project content from logs or screenshots.
+Report potential vulnerabilities using [private security reporting](SECURITY.md).
+
+## Follow development
+
+Maintainers track public work with the **progress** label: one issue per user-facing outcome,
+with a short scope and completion criteria. Status is **Planned**, **In progress**,
+**Implemented**, or **Released**. Implemented means the code is on main; Released names
+the published version and links its release notes.
+
+Updates describe meaningful progress or a blocker and link relevant code. Progress issues
+stay open until released, or close with an explanation if the work is cancelled. Bug reports
+and feature requests can link the relevant progress issue.
+
+A progress issue uses this shape:
+
+```md
+## Outcome
+What this lets people do.
+
+## Done when
+- Observable completion criteria.
+
+## Status
+In progress
+
+## Implementation
+Links to code when implemented.
+
+## Release
+Version and release link when published.
+```
+
+## Develop locally
+
+Python 3.12+, uv, Node 24+ and pnpm 11.19.0 are required.
+
+```sh
+make setup
+make check
+pnpm --dir web exec playwright install chromium
+make smoke
+make build
+```
+
+`make check` runs Python formatting, lint, types and deterministic tests, generated API
+type validation, frontend checks/build, and Mintlify validation/link checks. `make smoke`
+runs Chromium against the built application. `make build` produces a wheel and source
+archive with the compiled UI. Both install without Node, pnpm or a checkout at runtime.
+Use `scripts/check-install.py` from a clean installed environment to exercise the package.
+`make check-dist` installs both distributions through pip and the wheel through isolated
+`uv tool install`, then exercises each installed application outside the checkout.
+
+For frontend development, run `uv run flowfield serve` and `pnpm --dir web dev` in separate
+terminals. API wire types are generated with `make api-types`. Application operations live
+under `src/flowfield/`; harness-specific behavior belongs in `src/flowfield/adapters/`.
+
+Ordinary checks use isolated disposable state and never launch live model calls.
+
+## Database changes
+
+Schema 29 is the immutable initialization baseline, captured in
+`tests/fixtures/schema_29.sql`. Append each schema change to the ordered registry in
+`src/flowfield/migrations.py`; do not edit previous migrations or the baseline SQL.
+Migration callbacks change only the database using `execute`/`executemany`. The storage
+owner controls the transaction, version, migration history and pre-upgrade snapshot;
+callbacks must not commit, use `executescript`, or mutate project files or artifacts.
+
+Test fresh initialization and upgrading populated fixtures, including failure rollback,
+interruption, restart and preserved application bindings. Keep application writes inside
+`Workspace.connection()` so recovery can detect newer work. Automatic snapshots cover
+the database; full workspace backups remain separate.
+
+## Documentation
+
+Mintlify content and configuration live in `docs/`. Its CLI is pinned and locked locally:
+
+```sh
+make docs
+make docs-serve
+```
+
+`make docs` validates the build and internal links. `make docs-serve` starts a local
+preview. Hosted deployment uses the `docs/` subdirectory and its `docs.json` configuration.
+Keep user documentation concise and accurate for the behavior being released.
+Mintlify builds `docs/` from the `docs` branch. Advance that branch to the reviewed release
+commit after publication, using a normal fast-forward push, then verify the hosted pages.
+Feature development continues on main.
+
+## Versioning and releases
+
+The first release is **0.1.0**. `pyproject.toml` owns the version; uv keeps its entry in
+`uv.lock` aligned. Tags use `vX.Y.Z`. During 0.x, patches contain compatible fixes;
+minor releases contain new capabilities or breaking changes, with explicit upgrade notes.
+From 1.0 onward, Semantic Versioning applies: major for breaking changes, minor for
+compatible features, patch for compatible fixes. Compatibility covers documented CLI/MCP
+interfaces, integration guidance and persisted workspace state. Schema changes still need
+tested migrations and recovery; a version bump does not permit discarding user state.
+
+Every push to main runs the `Tests` workflow: Python 3.12 tests on Linux/macOS, Python and
+frontend quality checks, generated API validation, Mintlify validation, Chromium journeys
+and clean installed-package checks. Live model calls are separate from CI.
+
+### Prepare and rehearse
+
+Review all commits and the aggregate diff since the last published release, then write a
+nonempty `## X.Y.Z` section in `CHANGELOG.md`, newest first. Include features, fixes and
+upgrade requirements by user impact. Preserve previous entries and verify each claim against
+implementation, documentation and checks. Commit reviewed notes before releasing.
+
+```sh
+make setup
+pnpm --dir web exec playwright install chromium
+make release-check
+uv run --no-sync python scripts/release.py 0.1.0 --dry-run
+```
+
+`release-check` runs local checks, browser journeys, clean builds, pip wheel/source and uv tool
+installation checks, and distribution metadata validation. Build clears the generated `dist/`
+directory. The preview checks branch, clean state, remotes, version, notes and unused tags,
+and prints outgoing commits; it does not run checks or change files/refs.
+
+The `Release` workflow in `.github/workflows/workflow.yml` also supports a manual run on
+main. It runs CI, builds distributions once, and verifies those same artifacts on Linux/macOS.
+Manual runs stop after verification. Artifacts and checksums remain available for 30 days.
+
+### Publish
+
+Configure the PyPI Trusted Publisher for owner `flowfield-sh`, repository `flowfield-core`,
+workflow `workflow.yml` and environment `pypi`. The matching GitHub environment permits only
+tags matching `v*`. Publishing uses short-lived GitHub identity tokens.
+
+After reviewing the preparation and explicitly authorizing publication, run from clean main:
+
+```sh
+uv run --no-sync python scripts/release.py 0.1.0
+```
+
+The command holds a repository release lock, checks identity/notes, bumps only the version
+files when needed, runs verification, and commits those version files. It rechecks the
+remote and atomically pushes main and the annotated tag, then watches the release run.
+CI requires the tag to match package/lock metadata and identify a commit on main. Only
+the tag-triggered publishing job uses the `pypi` environment and OIDC permission. It publishes
+verified original artifacts, then publishes the GitHub Release with reviewed notes and checksums.
+Check actual PyPI installation, update discovery and GitHub assets after publication.
+
+### Recover
+
+Failures preserve local state and completed steps. Never move a published tag or rebuild an
+uploaded version. Before tagging, correct and review retained changes, then retry. Exit 75
+means another local release owns the lock. If push fails, inspect local and remote refs before
+retrying the same atomic push. If CI fails, inspect the existing run; source corrections need
+a new commit/version/tag. For partial upload or GitHub failure, rerun only failed jobs to reuse
+the original artifacts. Do not rerun the build after uploading. uv skips already uploaded
+identical files; GitHub completes the existing draft/assets. Expired artifacts require recovering
+and verifying the exact originals. A bad published release needs a new version.