Metadata-Version: 2.4
Name: openspec-ui
Version: 0.2.1
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>=0.86.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.

## What it does

- **Dashboard** — lists changes (draft / in-progress / completed / archived) with
  task progress bars, and specs with requirement counts.
- **Kanban** — a pipeline view of changes by stage, for at-a-glance status.
- **Detail view** — renders a change's artifacts (`proposal.md`, `design.md`,
  `specs/**`, `tasks.md`) read-only as markdown (ASCII diagrams and code
  blocks stay aligned in monospace). Switch artifacts with arrow keys.
- **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 actions.

## 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
