@grifhinz/logics-manager 2.1.2 → 2.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/AlexAgo83/logics-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/AlexAgo83/logics-manager/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/AlexAgo83/logics-manager)](LICENSE)
-![Version](https://img.shields.io/badge/version-v2.1.2-4C8BF5)
+![Version](https://img.shields.io/badge/version-v2.3.0-4C8BF5)
 ![VS Code](https://img.shields.io/badge/VS%20Code-1.86.0-007ACC?logo=visualstudiocode&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.3.3-3178C6?logo=typescript&logoColor=white)
 ![Vitest](https://img.shields.io/badge/Vitest-2.1.8-6E9F18?logo=vitest&logoColor=white)
@@ -95,18 +95,102 @@ The CLI is the stable contract for Logics. It supports:
 - closing tasks, backlog items, and requests with consistency checks;
 - linting and auditing workflow traceability;
 - exporting indexes, context packs, and graph data;
+- serving a read-only local browser viewer for the Logics corpus;
 - serving the bounded MCP tool surface.
 
 Useful commands:
 
 ```bash
 logics-manager flow list
-logics-manager flow promote request-to-backlog logics/request/req_001_example.md
-logics-manager flow promote backlog-to-task logics/backlog/item_001_example.md
-logics-manager flow finish task logics/tasks/task_001_example.md
+logics-manager flow promote request-to-backlog req_001_example
+logics-manager flow promote backlog-to-task item_001_example
+logics-manager flow finish task task_001_example
 logics-manager sync context-pack req_001_example --format json
+logics-manager view --open
+logics-manager view --focus req_001_example --read --open
 ```
 
+### Local Browser Viewer
+
+Use the CLI viewer when you want to inspect the Logics corpus outside VS Code:
+
+```bash
+logics-manager view --open
+```
+
+The viewer starts a localhost-only, read-only browser UI on `127.0.0.1:8765` by default. It shows the same workflow board/list experience as the extension, with search, filters, document previews, corpus insights, lint/audit health, Mermaid rendering, auto-refresh, and an edit shortcut that opens the selected Markdown file in the system editor.
+
+Useful options:
+
+```bash
+logics-manager view --port 0 --open
+logics-manager view --host 127.0.0.1 --port 9876
+logics-manager view --focus req_001_example --open
+logics-manager view --focus logics/tasks/task_001_example.md --read --open
+logics-manager view --no-open
+```
+
+Use `--port 0` when the default port is already taken. The viewer is intentionally read-only; use the canonical CLI commands such as `flow promote`, `flow finish`, `lint`, and `audit` for workflow mutations.
+
+Focused viewer links can point directly at a corpus item:
+
+```text
+http://127.0.0.1:8765/?focus=logics/request/req_001_example.md
+http://127.0.0.1:8765/?focus=logics/request/req_001_example.md&read=1
+```
+
+If the viewer server is not already running, start it with the equivalent fallback command:
+
+```bash
+logics-manager view --focus logics/request/req_001_example.md --open
+logics-manager view --focus req_001_example --read --open
+```
+
+This is the recommended assistant handoff pattern: provide the local viewer link for an already-running viewer and the CLI fallback command for a stopped server. Focus targets accept workflow refs such as `req_001_example`, `item_001_example`, or `task_001_example`, plus repo-relative Logics Markdown paths. Traversal and non-Logics paths are rejected.
+
+### CLI Contracts
+
+Workflow target arguments accept these forms:
+
+- a workflow ref, such as `req_001_example`, `item_001_example`, or `task_001_example`;
+- a repo-relative Markdown path under the matching Logics directory, such as `logics/request/req_001_example.md`;
+- an absolute path only when it resolves inside the current repository.
+
+Mutation commands reject `..` traversal and files outside the repository before writing. Output paths passed with `--out` must also be repo-relative and remain inside the repository after resolution. Configured log/cache paths in `logics.yaml` may be repo-relative or absolute, but absolute paths must still resolve inside the current repository.
+
+When a command supports `--format json`, stdout is a machine-readable JSON payload. Human-oriented status, diagnostics, and progress text should not be mixed into stdout for JSON mode. This makes JSON-mode commands safe to pipe into tools such as `jq` or consume from scripts.
+
+`--json` is a shorthand for `--format json` on commands that support JSON output.
+
+JSON-capable operator commands:
+
+| Command | Purpose | JSON output |
+| --- | --- | --- |
+| `logics-manager status` | Summarize open workflow docs and next actions. | `--format json` or `--json` |
+| `logics-manager health` | Show workflow health counts and issue signals. | `--format json` or `--json` |
+| `logics-manager followups` | List follow-up areas with request creation commands. | `--format json` or `--json` |
+| `logics-manager product-consistency` | Check product brief lineage links. | `--format json` or `--json` |
+| `logics-manager search <query>` | Search workflow docs directly. | `--format json` or `--json` |
+| `logics-manager index` | Regenerate `logics/INDEX.md`. | `--format json` or `--json` |
+| `logics-manager lint` | Validate doc shape and changed-doc hygiene. | `--format json` or `--json` |
+| `logics-manager audit` | Validate workflow traceability and governance. | `--format json` or `--json` |
+| `logics-manager sync ...` | Read, list, search, repair, and export workflow state. | `--format json` or `--json` on supported subcommands |
+| `logics-manager assist ...` | Build review, validation, context, and runtime summaries. | `--format json` or `--json` on supported subcommands |
+| `logics-manager flow ...` | Create, promote, split, close, finish, and list docs. | `--format json` or `--json` on supported subcommands |
+
+Operator triage flow:
+
+```bash
+logics-manager status --json
+logics-manager health --json
+logics-manager product-consistency --json
+logics-manager followups --source-kind product --json
+```
+
+Use `status` first when you need the next work signal. Use `health` for corpus-level anomalies. Use `product-consistency --strict` in release checks when active product briefs must have valid lineage. Use `followups` for open actionable follow-up areas; add `--include-closed` only when auditing historical docs.
+
+Multi-file workflow mutations such as `flow promote`, `flow split`, and `flow finish` validate their direct inputs before writing. New workflow docs are created with exclusive filesystem writes, so an ID collision fails instead of overwriting an existing file; rerun the command to allocate a fresh ID after reviewing `git status`/`git diff`. They still operate on Markdown files in the working tree rather than through a database or transaction service; if the filesystem fails mid-write, recover with git status/diff and rerun after cleanup.
+
 To update the installed CLI later:
 
 ```bash
@@ -304,6 +388,7 @@ Windows notes:
 - Create a fixture request with `logics-manager flow new request --title "Smoke test"` and confirm the compact synthetic request shape is generated.
 - Create a backlog item and a task from the UI and confirm markdown is generated.
 - Open `Read` on a Mermaid-bearing doc and confirm the graph is rendered.
+- Run `logics-manager view --port 0 --open`, confirm the browser viewer loads repository docs, then stop it with `Ctrl+C`.
 - Promote request -> backlog and confirm links are updated.
 - Confirm request/backlog/task generation fails fast if a Mermaid signature or traceability block is stale instead of waiting for audit to find it later.
 - Promote backlog -> task and confirm task document is generated.
@@ -348,6 +433,22 @@ npm run dev
 
 `npm run dev` requires the `code` CLI on PATH, so the F5 path above remains the safest cross-platform dev entrypoint.
 
+### Browser UI Debugging
+
+Use the real local viewer for repository data:
+
+```bash
+logics-manager view --open
+```
+
+Use the mock webview harness only when developing the shared browser/webview UI without VS Code:
+
+```bash
+npm run debug:webview
+```
+
+The harness runs at `http://localhost:4173/` and supports mock scenarios such as `/?scenario=empty` and `/?scenario=error`. It does not execute real VS Code commands or workflow writes.
+
 ## Deploy / Release (VSIX)
 
 1. Bump the version in `package.json`, `pyproject.toml`, and root `VERSION` when preparing a release manually.
@@ -403,6 +504,7 @@ If the current plugin version is already published, `logics-manager assist next-
 - Logics docs lint: `npm run lint:logics`
 - Logics workflow audit + docs lint: `npm run audit:logics`
 - Strict Logics governance audit: `npm run audit:logics:strict`
+- Local browser viewer smoke: `logics-manager view --port 0 --open`
 - Fast extension-focused local check: `npm run ci:fast`
 - Full CI-equivalent local check: `npm run ci:check`
 - Security audit policy gate: `npm run audit:ci`

package/VERSION

@@ -1 +1 @@
-2.1.2
+2.3.0

package/clients/README.md

@@ -0,0 +1,9 @@
+# Logics Clients
+
+This directory separates user-facing clients from the shared Logics runtime.
+
+- `vscode/` contains the VS Code extension host implementation.
+- `shared-web/` contains browser/webview assets that can be reused by the VS Code extension and the future local viewer.
+- `viewer/` is reserved for the CLI-launched local browser viewer.
+
+The Python CLI/runtime remains in `logics_manager/`.