Revue

Revue is a standalone Markdown review/editor for Git worktrees. It exposes one or more documentation workspaces in a browser while keeping Git lifecycle operations outside the application.

Revue may read and edit files inside configured worktrees and persist review intentions/captures in its own state root. It does not commit, push, create branches, manage Git credentials, or execute review intentions automatically.

The project is licensed under GPL-3.0-or-later. Extraction provenance from Asami is recorded in PROVENANCE.md.

Runtime model

A permanent Revue service can mount several workspaces under /w/<key>/. / shows the workspace selector and /healthz reports the configured workspace keys. Each workspace keeps its own project configuration and operational state.

For local compatibility, a single worktree may still be served directly.

Project configuration

A workspace may contain .revue.yaml:

schema_version: 1
title: Asami documentation
markdown:
  include: ["*.md", "**/*.md"]
  exclude: ["archive/**"]
assets:
  root: docs/assets
navigation:
  pinned_groups: [docs, docs/releases]
  versioned_group_pattern: '^docs/releases-(?P<version>[0-9]+\.[0-9]+\.[0-9]+)$'
  group_containers: [docs/archive]
  readme_first_groups: [docs/releases]
  versioned_file_patterns:
    docs/releases: '^release-(?P<major>[0-9]+)\.(?P<minor>[0-9]+)\.(?P<patch>x|[0-9]+)\.md$'
  current_pointer: docs/current
  open_on_home: [docs]

All paths are relative to the workspace and are validated to stay inside it. navigation.group_containers nests matching navigation groups under one native collapsible container; containers are closed by default and open automatically when the active document is inside them. .revue.yaml is canonical; .revue.yml remains accepted for compatibility, but both files at once are rejected as ambiguous. Without project configuration, Revue uses the workspace directory name as title, discovers Markdown recursively, and stores page captures below assets/.

See revue.example.yaml for a complete example.

Service configuration

The long-running service uses a separate YAML file:

schema_version: 1
workspaces:
  asami:
    path: /workspaces/asami-docs
  charfish:
    path: /workspaces/charfish-docs

See service.example.yml.

Operational state is independent from reviewed worktrees. In service mode, pass a state root such as /state; Revue creates one private subdirectory per workspace. Single-workspace mode defaults to the historical local .review/ directory when no --state-root is supplied.

Safety properties

Revue keeps the protections inherited from the original implementation:

• Markdown discovery is Git-aware and ignores paths excluded by Git;
• file writes use SHA-256 optimistic locking;
• review-state and asset paths reject traversal and unsafe symlink crossings;
• uploads are size- and type-limited;
• state files and server secrets are written with private permissions;
• CSRF protection remains enabled in normal runtime;
• the generic core contains no Asami runtime import or fixed Asami path/version rule.

The nominal production transport is plain HTTP on loopback/container networking. TLS and client authentication belong to the reverse proxy. Revue does not generate a self-signed certificate and does not implement an internal Basic Auth layer.

Development

Requirements:

• Python 3.13 with venv;
• Node.js 22 and npm for the browser editor bundle;
• Git.

Bootstrap the local environment and build browser assets:

./bootstrap.sh

Run the tests:

.venv/bin/python -m unittest -v tests.test_revue

Single-workspace development server:

.venv/bin/python serve.py --project-root /path/to/worktree --state-root /tmp/revue-state

Multi-workspace service:

.venv/bin/python serve.py --config /path/to/service.yml --state-root /path/to/state

The default bind is 127.0.0.1:8765. --bind and --port may override it. Single-workspace direct HTTP uses a non-Secure session cookie so CSRF-protected writes work on loopback; service mode keeps Secure cookies because its nominal client path is HTTPS through the reverse proxy.

Container

The image builds the locked frontend bundle in a Node stage and installs the pinned Python runtime dependencies in the final image. The default command expects:

• service config: /config/revue.yml (read-only);
• worktrees: paths declared by that config, normally bind-mounted read/write;
• persistent state: /state (read/write by container uid 10001).

The image listens on 0.0.0.0:8765 inside the container. /healthz verifies Git discovery plus read/write access to every configured workspace and its state root; the container healthcheck uses that endpoint. Production should publish the service only on host loopback and place an HTTPS reverse proxy with mandatory client authentication in front of it.

Release workflow

Revue uses main plus short-lived feature/fix branches. There is no develop, release branch, or RC phase. Releases use CalVer tags vYY.N (v26.1, v26.2, then v27.1, and so on). A tag is created only after operator qualification of the exact commit/tree intended for production.