Metadata-Version: 2.4
Name: openspec-ui
Version: 0.4.0
Summary: An unofficial, community-built interactive TUI for visualizing and managing OpenSpec changes and specs. Not affiliated with Fission-AI/OpenSpec.
Project-URL: Homepage, https://github.com/mrn-dk/openspec-ui
Project-URL: Repository, https://github.com/mrn-dk/openspec-ui
Project-URL: Issues, https://github.com/mrn-dk/openspec-ui/issues
Author: OpenSpec UI Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: dashboard,openspec,spec-driven,textual,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Terminals
Requires-Python: >=3.10
Requires-Dist: textual>=1.0.0
Description-Content-Type: text/markdown

# openspec-ui

> **Unofficial.** `openspec-ui` is a community-built tool and is **not
> affiliated with, endorsed by, or sponsored by [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec).**
> It consumes the `openspec` CLI over subprocess as a third-party client.

An interactive, keyboard-driven terminal UI for visualizing and managing your
[OpenSpec](https://github.com/Fission-AI/OpenSpec) changes and specs.

`openspec view` dumps a static dashboard and exits. `openspec-ui` is the
interactive version: browse changes and specs, glance at progress, see a kanban
pipeline of your changes, open artifacts, edit them in `$EDITOR`, and create new
changes — all from one terminal command.

## Install & run

```bash
uvx openspec-ui
```

Run it from inside any directory containing an `openspec/` root (or a
subdirectory of one). Requires the `openspec` CLI on PATH.

Requires Python 3.10+ and [Textual](https://textual.textualize.io/) 1.0 or
newer (installed automatically).

## What it does

- **Dashboard** — an aligned table of changes (stage, name, progress, tasks,
  last modified) over headline counts of specs and of changes per stage.
  Specs are listed with their requirement counts.
- **Kanban** — a pipeline view of changes by stage, each column and card
  carrying that stage's colour, for at-a-glance status.
- **Change detail** — renders a change's artifacts (`proposal.md`,
  `design.md`, `specs/**`) as scrollable markdown with a navigable table of
  contents; ASCII diagrams and code blocks stay aligned in monospace. When an
  artifact resolves to several files, each gets its own tab.
- **Tasks** — a change's `tasks.md` rendered as its checklist, one section per
  heading with a done/total count. Read-only; edits go through `$EDITOR`.
- **Spec browser** — open a spec to read its overview and requirements, each
  expandable to reveal its scenarios.
- **Filter** — press `/` to narrow the changes and specs by name.
- **Edit** — press `e` to open the current artifact in `$EDITOR`; the view
  reloads from disk when the editor exits.
- **New change** — press `n` to create a change via `openspec new change`.
- **Command palette** — `Ctrl+P` for fuzzy-searchable actions, including
  jumping straight to any change or spec by name, and switching theme.
- **Live refresh** — open views re-read from disk as things change on disk;
  press `p` to pause.

### Keys

Press `?` at any time for the bindings available on the current screen.

| Key | Does |
| --- | --- |
| `?` | Show key bindings for the current screen |
| `Ctrl+P` | Command palette (actions, jump to change/spec, theme) |
| `/` | Filter the current listing by name (`escape` clears) |
| `enter` | Open the selected change or spec |
| `k` / `d` | Kanban / dashboard |
| `n` | New change |
| `e` | Edit the current artifact in `$EDITOR` |
| `r` | Refresh now |
| `p` | Pause or resume live refresh |
| `t` | Toggle the table of contents (change detail) |
| `q` | Quit |

### Theming

`openspec-ui` ships no palette of its own — all colour comes from the active
Textual theme, so it follows your terminal. Switch themes in-session from the
command palette (`Ctrl+P` → *Theme*). Nothing is written to disk: the app
persists no state, theme included.

## Design

`openspec-ui` is a **thin client**: it owns no state. Every read comes from
`openspec ... --json` or direct file reads under `openspec/`; every write is
delegated to the `openspec` CLI or to `$EDITOR`. This keeps the view layer
replaceable (a future SvelteKit web UI could reuse the same data contract).

## Status

Alpha. Built with [Textual](https://textual.textualize.io/). Supports OpenSpec
CLI `1.7.x` (`@fission-ai/openspec`).

## Releases

Releases are **fully automated**. Maintainers never edit the version field by
hand.

1. Conventional commits land on `main` (via PRs).
2. On each push to `main`, CI runs [`commitizen`](https://commitizen-tools.github.io/commitizen/)
   (`cz bump --yes --changelog`), which determines the next semver from the
   commit log, updates `version` in `pyproject.toml`, updates `CHANGELOG.md`,
   and creates/pushes a `v<version>` tag.
3. The tag push triggers a second CI job that builds the wheel+sdist and
   publishes them to [PyPI](https://pypi.org/project/openspec-ui/) using
   **trusted publishing (OIDC)** — no stored API tokens.
4. `feat:`/`fix:`/breaking commits release; pure `chore:`/`docs:` commits do
   not (commitizen determines there is no increment).

### Trusted publisher setup (one-time, manual)

Before the publish job works, register a trusted publisher on
[pypi.org](https://pypi.org) once:

- **PyPI project:** `openspec-ui` (create it if it does not yet exist).
- **GitHub repo:** `mrn-dk/openspec-ui`.
- **Workflow filename:** `.github/workflows/release.yml`.
- **Environment name:** `pypi` (the publish job uses `environment: pypi`).

This is a web step on pypi.org that cannot be automated from within the repo.
Until it is done, the publish job will fail with an OIDC error; the build
artifacts still exist in the workflow run and can be uploaded manually.

The first release also needs a seeded `v0.1.0` tag (commitizen bumps
*relative* to an existing tag); after that, `cz bump` always has a reference.

## Contributing

This project follows the OpenSpec spec-driven workflow (`openspec/`).

Git history uses **Conventional Commits** and **conventional branch names**:

- Branches: `feat/<scope>`, `fix/<scope>`, `refactor/<scope>`, `chore/<scope>`, …
- Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, … (with a scope
  when helpful, e.g. `feat: add kanban view`).
- Never commit directly to `main`. Work on a dedicated branch and open a pull
  request with the GitHub CLI (`gh pr create`), referencing the OpenSpec change
  name in the PR description.

For changes managed through OpenSpec, see `openspec/config.yaml` for the
project context and per-operation guidance that the openspec skills follow.

## License

MIT
