fticket 0.1.0__tar.gz

fticket-0.1.0/.github/workflows/gitleaks.yml

@@ -0,0 +1,15 @@
+name: gitleaks
+on:
+  push:
+  pull_request:
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Run gitleaks (full history)
+        run: |
+          curl -sSL https://github.com/gitleaks/gitleaks/releases/download/v8.24.3/gitleaks_8.24.3_linux_x64.tar.gz | tar xz gitleaks
+          ./gitleaks git . --no-banner --redact --exit-code 1

fticket-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: publish
+on:
+  release:
+    types: [published]
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uvx 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/fticket
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

fticket-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

fticket-0.1.0/LICENSE

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

fticket-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: fticket
+Version: 0.1.0
+Summary: Factory Ticket System (FTS): transactional coordination core for the AI software factory
+Project-URL: Repository, https://github.com/fmktech/fticket
+Project-URL: Issues, https://github.com/fmktech/fticket/issues
+Author-email: Foad Kesheh <foad@fmktech.com.br>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,coordination,leases,sqlite,task-queue,ticketing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# fticket — Factory Ticket System (FTS)
+
+Transactional coordination core for the AI software factory: task status, claims,
+dependencies, resource leases, and history in one SQLite file (WAL, single writer,
+one `BEGIN IMMEDIATE` transaction per operation). Task folders stay immutable-path
+artifact storage; FTS owns all control-plane state. Zero runtime dependencies.
+
+## Install
+
+```bash
+uv sync          # dev
+uv pip install . # as a library
+```
+
+## Quickstart
+
+```python
+from fticket import FTS, Mode
+
+FTS.init_db("factory.db", stages=["code", "review", "qa", "deploy"])  # create schema first
+fts = FTS("factory.db")
+
+t = fts.create_ticket(title="build parser", stage="code", folder_path="tasks/0001")
+claim = fts.claim("code", worker_id="coder-1")         # atomic, race-free
+fts.start(claim.ticket.id, "coder-1")                  # claimed -> in_progress
+fts.acquire(resource="staging", ticket_id=t.id, worker_id="coder-1", mode=Mode.EXCLUSIVE)
+fts.complete(t.id, "coder-1")                          # records reached_stage
+fts.advance(t.id, "coder-1", to_stage="review")        # done -> queued @ review
+fts.tick()                                             # expire TTLs, promote waitlists
+```
+
+## CLI
+
+`fts <cmd> --db factory.db` — read commands work on a read-only database.
+
+| | |
+|---|---|
+| `init` | create schema, seed config + stages |
+| `board` / `show <id>` / `dag` / `queues` | board grid, ticket detail + history, dependency DAG, queue depths |
+| `why <id>` / `triage` / `stats` / `doctor` | stuck-ticket root cause, dead-letter + orphans, AC16 metrics, health checks |
+| `create` / `claim` / `renew` / `start` / `complete` / `advance` | ticket lifecycle |
+| `transition` / `reject` / `dead-letter` / `revive` | generic edge, bounce, operator kill, un-kill |
+| `add-dep` / `acquire` / `release` / `register-resource` | dependencies and resource leases |
+| `tick` / `scheduler` | one sweep pass / loop until Ctrl-C |
+| `events` | poll/tail the event stream |
+| `config get\|set` | tunables (`bounce_limit`, `claim_ttl_ms`, ...) |
+| `serve` | read-only web dashboard |
+
+## Dashboard
+
+```bash
+fts serve --db factory.db --port 8377
+```
+
+Read-only, bound to `127.0.0.1` only, GET-only, no external assets.

fticket-0.1.0/README.md

@@ -0,0 +1,55 @@
+# fticket — Factory Ticket System (FTS)
+
+Transactional coordination core for the AI software factory: task status, claims,
+dependencies, resource leases, and history in one SQLite file (WAL, single writer,
+one `BEGIN IMMEDIATE` transaction per operation). Task folders stay immutable-path
+artifact storage; FTS owns all control-plane state. Zero runtime dependencies.
+
+## Install
+
+```bash
+uv sync          # dev
+uv pip install . # as a library
+```
+
+## Quickstart
+
+```python
+from fticket import FTS, Mode
+
+FTS.init_db("factory.db", stages=["code", "review", "qa", "deploy"])  # create schema first
+fts = FTS("factory.db")
+
+t = fts.create_ticket(title="build parser", stage="code", folder_path="tasks/0001")
+claim = fts.claim("code", worker_id="coder-1")         # atomic, race-free
+fts.start(claim.ticket.id, "coder-1")                  # claimed -> in_progress
+fts.acquire(resource="staging", ticket_id=t.id, worker_id="coder-1", mode=Mode.EXCLUSIVE)
+fts.complete(t.id, "coder-1")                          # records reached_stage
+fts.advance(t.id, "coder-1", to_stage="review")        # done -> queued @ review
+fts.tick()                                             # expire TTLs, promote waitlists
+```
+
+## CLI
+
+`fts <cmd> --db factory.db` — read commands work on a read-only database.
+
+| | |
+|---|---|
+| `init` | create schema, seed config + stages |
+| `board` / `show <id>` / `dag` / `queues` | board grid, ticket detail + history, dependency DAG, queue depths |
+| `why <id>` / `triage` / `stats` / `doctor` | stuck-ticket root cause, dead-letter + orphans, AC16 metrics, health checks |
+| `create` / `claim` / `renew` / `start` / `complete` / `advance` | ticket lifecycle |
+| `transition` / `reject` / `dead-letter` / `revive` | generic edge, bounce, operator kill, un-kill |
+| `add-dep` / `acquire` / `release` / `register-resource` | dependencies and resource leases |
+| `tick` / `scheduler` | one sweep pass / loop until Ctrl-C |
+| `events` | poll/tail the event stream |
+| `config get\|set` | tunables (`bounce_limit`, `claim_ttl_ms`, ...) |
+| `serve` | read-only web dashboard |
+
+## Dashboard
+
+```bash
+fts serve --db factory.db --port 8377
+```
+
+Read-only, bound to `127.0.0.1` only, GET-only, no external assets.

fticket-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "fticket"
+version = "0.1.0"
+description = "Factory Ticket System (FTS): transactional coordination core for the AI software factory"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Foad Kesheh", email = "foad@fmktech.com.br" }]
+keywords = ["sqlite", "ticketing", "coordination", "agents", "task-queue", "leases"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+requires-python = ">=3.13"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/fmktech/fticket"
+Issues = "https://github.com/fmktech/fticket/issues"
+
+[project.scripts]
+fts = "fticket.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "factory-boy>=3.3",
+    "mypy>=1.14",
+    "ruff>=0.9",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fticket"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+markers = [
+    "slow: long-running concurrency/latency tests",
+]
+
+[tool.mypy]
+strict = true
+python_version = "3.13"
+files = ["src", "tests"]
+warn_unreachable = true
+
+[[tool.mypy.overrides]]
+module = "factory.*"
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "TID252"]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "parents"
+
+[tool.hatch.build.targets.sdist]
+exclude = ["prd-*.md", ".ffactory/"]

fticket-0.1.0/src/fticket/__init__.py

@@ -0,0 +1,122 @@
+"""FTS — Factory Ticket System (§10 public surface).
+
+Re-exports the facade (`FTS`), the clock protocol, every public StrEnum and value
+dataclass (`types`), and the full error hierarchy (`errors`), so callers import from the
+package root. Names are listed in `__all__` for explicit re-export under mypy --strict.
+"""
+
+from fticket.clock import Clock, SystemClock
+from fticket.core import FTS
+from fticket.errors import (
+    ClaimExpired,
+    ClaimFenced,
+    ConfigError,
+    Contended,
+    DependencyCycle,
+    DuplicateFolder,
+    FTSError,
+    FTSStageWarning,
+    IllegalTransition,
+    LeaseUpgradeUnsupported,
+    NotClaimOwner,
+    NotFound,
+    ReadOnlyError,
+    ResourceModeError,
+    ResourceNotFound,
+    ResourceOrderViolation,
+    SelfDependency,
+    TicketNotFound,
+)
+from fticket.types import (
+    AcquireResult,
+    BounceRate,
+    Claim,
+    ClaimResult,
+    CycleTimeStats,
+    Dag,
+    DagEdge,
+    DagNode,
+    Dependency,
+    DoctorCheck,
+    DoctorCheckId,
+    DoctorReport,
+    Event,
+    EventType,
+    Grant,
+    HistoryKind,
+    HistoryRow,
+    Kind,
+    LeaseView,
+    Mode,
+    ModePolicy,
+    OrphanReport,
+    ResourceBlock,
+    ResourceState,
+    StageDepth,
+    Status,
+    StuckReason,
+    Ticket,
+    TicketDetail,
+    TickReport,
+    WaitView,
+    WhyCategory,
+)
+
+__all__ = [
+    "FTS",
+    "Clock",
+    "SystemClock",
+    # enums
+    "Status",
+    "Kind",
+    "Mode",
+    "ModePolicy",
+    "Grant",
+    "HistoryKind",
+    "EventType",
+    "WhyCategory",
+    "DoctorCheckId",
+    # value dataclasses
+    "Dependency",
+    "Ticket",
+    "ClaimResult",
+    "Claim",
+    "AcquireResult",
+    "HistoryRow",
+    "Event",
+    "TickReport",
+    "StageDepth",
+    "ResourceBlock",
+    "BounceRate",
+    "CycleTimeStats",
+    "DagNode",
+    "DagEdge",
+    "Dag",
+    "LeaseView",
+    "WaitView",
+    "ResourceState",
+    "OrphanReport",
+    "TicketDetail",
+    "StuckReason",
+    "DoctorCheck",
+    "DoctorReport",
+    # errors
+    "FTSError",
+    "NotFound",
+    "TicketNotFound",
+    "ResourceNotFound",
+    "IllegalTransition",
+    "DependencyCycle",
+    "SelfDependency",
+    "NotClaimOwner",
+    "ClaimExpired",
+    "ClaimFenced",
+    "ResourceModeError",
+    "LeaseUpgradeUnsupported",
+    "ResourceOrderViolation",
+    "DuplicateFolder",
+    "Contended",
+    "ConfigError",
+    "ReadOnlyError",
+    "FTSStageWarning",
+]

fticket-0.1.0/src/fticket/__main__.py

@@ -0,0 +1,8 @@
+"""`python -m fticket` entry point -> `cli.main` (§8). [CLI wave 2]"""
+
+import sys
+
+from fticket.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())