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.
