From 924093f166bd05bc7f41a9a3b682d82110fc9ff1 Mon Sep 17 00:00:00 2001 From: GeneAI Date: Sat, 23 May 2026 22:33:28 -0400 Subject: [PATCH] chore: remove redundant sidecar/.help/ corpus MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit sidecar/.help/ was an early auto-scaffold from a stale-era 'attune-author init' inside sidecar/. It was never curated and duplicates the root .help/ corpus entirely: - Its 'attune-gui' feature (attune_gui/**) is a strict subset of root's 'sidecar' feature (sidecar/**). - Its 'attune_gui-entry' feature points at the same file root's does (sidecar/attune_gui/app.py). - Its 'attune-gui.egg-info' feature is a build artifact, not source. - Its 'tests' feature is covered by root's broader sidecar/** glob. The runtime never reads sidecar/.help/ — living_docs_store.py, commands.py, and cowork_files.py all resolve .help/ via project_root, which the federated config sets to the repo root. Also drops the now-obsolete Makefile comment explaining why the sidecar corpus was deferred — it no longer exists to defer. Co-Authored-By: Claude Opus 4.7 --- Makefile | 2 - sidecar/.help/features.yaml | 23 -- sidecar/.help/templates/attune-gui/concept.md | 55 ----- .../.help/templates/attune-gui/reference.md | 220 ------------------ sidecar/.help/templates/attune-gui/task.md | 83 ------- 5 files changed, 383 deletions(-) delete mode 100644 sidecar/.help/features.yaml delete mode 100644 sidecar/.help/templates/attune-gui/concept.md delete mode 100644 sidecar/.help/templates/attune-gui/reference.md delete mode 100644 sidecar/.help/templates/attune-gui/task.md diff --git a/Makefile b/Makefile index 73921e8..296c464 100644 --- a/Makefile +++ b/Makefile @@ -36,8 +36,6 @@ clean-editor: # Regenerate living-docs templates for the root .help/ corpus. # Calls Anthropic for polish — costs $$ on stale features. -# Sidecar corpus (sidecar/.help/) is deferred and not maintained here; -# see docs/specs/living-docs-regen-automation/ for the rationale. regen-templates: uv run attune-author regenerate --help-dir .help diff --git a/sidecar/.help/features.yaml b/sidecar/.help/features.yaml deleted file mode 100644 index 11e28f5..0000000 --- a/sidecar/.help/features.yaml +++ /dev/null @@ -1,23 +0,0 @@ -version: 1 -features: - attune-gui: - description: "attune-gui \u2014 local FastAPI sidecar that drives attune-rag,\ - \ attune-author, and (later) attune-ai." - files: - - attune_gui/** - attune-gui.egg-info: - description: Attune Gui.Egg Info - files: - - attune_gui.egg-info/** - attune_gui-entry: - description: 'Entry point: attune_gui/app.py' - files: - - attune_gui/app.py - tags: - - entry-point - tests: - description: Tests - files: - - tests/** - tags: - - testing diff --git a/sidecar/.help/templates/attune-gui/concept.md b/sidecar/.help/templates/attune-gui/concept.md deleted file mode 100644 index a8d203f..0000000 --- a/sidecar/.help/templates/attune-gui/concept.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -type: concept -feature: attune-gui -depth: concept -generated_at: 2026-05-05T00:12:36.232891+00:00 -source_hash: 373196211438f141eb9a7c64116a3e8312048764f33da724833860f48eb607bc -status: generated ---- - -# Attune GUI - -A local FastAPI web server that provides a browser-based interface for attune-rag, attune-author, and attune-help. The GUI runs as a sidecar process, handling document editing, corpus management, and job execution through web endpoints. - -## Architecture - -The GUI operates as a standalone FastAPI application with these core components: - -**Command registry** — Maintains a catalog of available operations (like document generation or corpus indexing) that the web interface can trigger. Each command has a specification defining its arguments, execution function, and user-facing metadata. - -**Corpus management** — Tracks document collections stored in `~/.attune/corpora.json`. Users can register new corpora, switch between active corpora, and configure editing permissions through the web interface. - -**Editor sessions** — Manages in-memory state for each open document tab. Sessions track the original file content, current draft changes, and file system polling to detect external modifications. - -**Job execution** — Runs long-running operations (like document generation) in background threads while streaming progress updates to the browser. The job registry maintains status, output logs, and results for up to 200 recent jobs. - -## Security model - -The GUI enforces an origin guard that only accepts requests from localhost addresses (`localhost`, `127.0.0.1`, `[::1]`). This prevents remote access while allowing browser-based interaction from the local machine. - -A random token generated at startup provides additional protection against cross-site request attacks. The token must be included in requests to sensitive endpoints. - -## Document editing workflow - -When you open a document in the GUI editor: - -1. **Session creation** — An `EditorSession` loads the current file content and starts polling for external changes -2. **Draft tracking** — Your edits are stored separately from the original content, allowing you to see what changed -3. **Conflict detection** — If another process modifies the file, the session detects the change and can rebase your draft -4. **Save coordination** — The GUI can save drafts back to disk or discard changes to return to the original content - -This design prevents data loss when multiple tools (like your text editor and the GUI) work with the same files. - -## Integration points - -| Component | Purpose | Example usage | -|-----------|---------|---------------| -| **Command executors** | Run attune-rag queries, generate documents, index corpora | Background job triggered from web UI | -| **File watchers** | Detect when documents change outside the GUI | Editor session polls file timestamps | -| **Corpus registry** | Coordinate with attune-author's corpus management | Switch active corpus affects which documents appear | - -## When to use the GUI vs. command line - -Use the GUI when you need visual document editing, want to manage multiple corpora through a web interface, or prefer monitoring job progress through a browser. The command-line tools remain faster for scripting and automation workflows. - -The GUI adds overhead but provides immediate feedback and reduces the need to remember command syntax for infrequent operations. diff --git a/sidecar/.help/templates/attune-gui/reference.md b/sidecar/.help/templates/attune-gui/reference.md deleted file mode 100644 index 98d0f04..0000000 --- a/sidecar/.help/templates/attune-gui/reference.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -type: reference -feature: attune-gui -depth: reference -generated_at: 2026-05-05T00:13:12.831905+00:00 -source_hash: 373196211438f141eb9a7c64116a3e8312048764f33da724833860f48eb607bc -status: generated ---- - -# Attune GUI reference - -Build local web interfaces for attune development workflows with FastAPI-based sidecar services. - -## Classes - -### Command and job management - -| Class | Description | -|-------|-------------| -| `CommandSpec` | Dataclass defining a command that can be executed through the GUI | -| `Job` | Dataclass representing a single command execution with status tracking | -| `JobContext` | Context object passed to command executors for logging | -| `JobRegistry` | Process-wide job manager with history and cancellation support | - -#### CommandSpec fields - -| Field | Type | Default | Description | -|-------|------|---------|-------------| -| `name` | `str` | | Command identifier | -| `title` | `str` | | Human-readable display name | -| `domain` | `str` | | Logical grouping (e.g., 'editor', 'living-docs') | -| `description` | `str` | | Brief explanation of what the command does | -| `args_schema` | `dict[str, Any]` | | JSON schema for command arguments | -| `executor` | `ExecutorFn` | | Function that executes the command | -| `cancellable` | `bool` | `True` | Whether the command can be interrupted | -| `profiles` | `tuple[str, ...]` | `('developer',)` | Which UI profiles can see this command | - -#### Job fields - -| Field | Type | Default | Description | -|-------|------|---------|-------------| -| `id` | `str` | | Unique job identifier | -| `name` | `str` | | Command name that was executed | -| `args` | `dict[str, Any]` | | Arguments passed to the command | -| `status` | `JobStatus` | `'pending'` | Current execution state | -| `created_at` | `datetime` | current time | When the job was queued | -| `started_at` | `datetime | None` | `None` | When execution began | -| `finished_at` | `datetime | None` | `None` | When execution completed | -| `output_lines` | `list[str]` | `[]` | Log messages from the executor | -| `result` | `Any | None` | `None` | Return value from successful execution | -| `error` | `str | None` | `None` | Error message if execution failed | - -### Corpus and editor management - -| Class | Description | -|-------|-------------| -| `CorpusEntry` | Dataclass representing a registered document corpus | -| `Registry` | In-memory snapshot of `~/.attune/corpora.json` | -| `EditorSession` | In-process state for a single `(corpus, path)` editing tab | -| `PortfileData` | Dataclass storing sidecar process coordination data | - -#### CorpusEntry fields - -| Field | Type | Default | Description | -|-------|------|---------|-------------| -| `id` | `str` | | Unique corpus identifier | -| `name` | `str` | | Human-readable corpus name | -| `path` | `str` | | Filesystem path to the corpus root | -| `kind` | `CorpusKind` | `'source'` | Type of corpus content | -| `warn_on_edit` | `bool` | `False` | Whether to show warnings when editing | - -#### Registry fields - -| Field | Type | Default | Description | -|-------|------|---------|-------------| -| `active` | `str | None` | `None` | ID of the currently active corpus | -| `corpora` | `list[CorpusEntry]` | `[]` | All registered corpora | - -#### EditorSession fields - -| Field | Type | Default | Description | -|-------|------|---------|-------------| -| `abs_path` | `Path` | | Absolute path to the file being edited | -| `base_text` | `str` | | Content from disk when session started | -| `base_hash` | `str` | | SHA-256 prefix of base_text | -| `draft_text` | `str` | | Current editor content (auto-initialized) | -| `poll_interval` | `float` | `0.1` | How often to check for disk changes | - -#### PortfileData fields - -| Field | Type | Default | Description | -|-------|------|---------|-------------| -| `pid` | `int` | | Process ID of the running sidecar | -| `port` | `int` | | TCP port the sidecar is listening on | -| `token` | `str` | | Authentication token for API requests | - -### Living docs tracking - -| Class | Description | -|-------|-------------| -| `DocEntry` | Dataclass representing a tracked documentation file | -| `ReviewItem` | Dataclass representing an auto-applied change awaiting review | - -#### DocEntry fields - -| Field | Type | Default | Description | -|-------|------|---------|-------------| -| `id` | `str` | | Unique document identifier | -| `feature` | `str` | | Feature name the document covers | -| `depth` | `str` | | Documentation depth (concept, reference, etc.) | -| `persona` | `str` | | Target audience (end-user, developer, support) | -| `status` | `str` | | Current state (draft, approved, etc.) | -| `path` | `str | None` | | Filesystem path, if the document exists | -| `last_modified` | `str | None` | | ISO timestamp of last change | -| `reason` | `str | None` | `None` | Why the document is in its current state | - -#### ReviewItem fields - -| Field | Type | Default | Description | -|-------|------|---------|-------------| -| `id` | `str` | | Unique review item identifier | -| `doc_id` | `str` | | ID of the associated DocEntry | -| `feature` | `str` | | Feature name | -| `depth` | `str` | | Documentation depth | -| `persona` | `str` | | Target audience | -| `trigger` | `str` | | What caused the auto-update | -| `auto_applied_at` | `str` | | ISO timestamp when change was applied | -| `reviewed` | `bool` | `False` | Whether a human has reviewed this change | -| `diff_summary` | `str` | `''` | Brief description of what changed | - -## Functions - -### App lifecycle - -| Function | Parameters | Returns | Description | -|----------|------------|---------|-------------| -| `create_app` | | `FastAPI` | Build the FastAPI app with origin-guard, CORS, and all routers wired | - -### Command management - -| Function | Parameters | Returns | Description | -|----------|------------|---------|-------------| -| `get_command` | `name: str` | `CommandSpec \| None` | Return the CommandSpec for `name`, or None if it isn't registered | -| `list_commands` | `profile: str \| None = None` | `list[dict[str, Any]]` | Return registered commands as JSON-serializable dicts | - -### Corpus registry - -| Function | Parameters | Returns | Description | -|----------|------------|---------|-------------| -| `load_registry` | | `Registry` | Read the registry file. Returns an empty Registry if absent | -| `save_registry` | `reg: Registry` | `None` | Write the registry to disk. Creates `~/.attune/` if needed | -| `list_corpora` | | `list[CorpusEntry]` | Return all registered corpora | -| `get_corpus` | `corpus_id: str` | `CorpusEntry \| None` | Find a corpus by ID | -| `get_active` | | `CorpusEntry \| None` | Return the currently active corpus | -| `set_active` | `corpus_id: str` | `CorpusEntry` | Mark `corpus_id` as active | -| `register` | `name: str, path: str, *, kind: CorpusKind = 'source', warn_on_edit: bool \| None = None` | `CorpusEntry` | Register a corpus. Returns the new entry | - -#### Raises - -| Function | Exception | Message | -|----------|-----------|---------| -| `set_active` | `KeyError` | 'Unknown corpus id: {...}' | -| `register` | `ValueError` | 'Not a directory: {...}' | - -### Editor sessions - -| Function | Parameters | Returns | Description | -|----------|------------|---------|-------------| -| `EditorSession.load` | `cls, abs_path: Path, *, poll_interval: float = 0.1` | `EditorSession` | Create a session for editing the file at abs_path | -| `hash_text` | `text: str` | `str` | Return the 16-char sha256 prefix used as the session's optimistic lock token | - -### Sidecar coordination - -| Function | Parameters | Returns | Description | -|----------|------------|---------|-------------| -| `write_portfile` | `pid: int, port: int, token: str` | `None` | Write `{pid, port, token}` to the portfile (overwriting) | -| `read_portfile` | | `PortfileData \| None` | Return the parsed portfile or None if missing/corrupt | -| `delete_portfile` | | `None` | Remove the portfile if it exists. No-op when absent | -| `is_pid_alive` | `pid: int` | `bool` | Return True if a process with `pid` is currently running | -| `is_portfile_stale` | | `bool` | Return True if no fresh sidecar is reachable via the portfile | -| `portfile_context` | `pid: int, port: int, token: str` | context manager | Write the portfile on enter, remove on exit. Always cleans up | - -### Job management - -| Function | Parameters | Returns | Description | -|----------|------------|---------|-------------| -| `get_registry` | | `JobRegistry` | Return the process-global JobRegistry, creating it on first call | - -## Constants - -### Version and exports - -| Constant | Values | -|----------|--------| -| `__version__` | '0.5.0' | -| `__all__` | ['EditorSession', 'hash_text'] | - -### Documentation structure - -| Constant | Values | -|----------|--------| -| `_CORE_DEPTHS` | ('concept', 'reference', 'task') | -| `_PHASE_FILES` | ('requirements.md', 'design.md', 'tasks.md') | -| `_PHASE_NAMES` | ('requirements', 'design', 'tasks') | -| `_VALID_STATUSES` | ('draft', 'in-review', 'approved', 'complete', 'completed', 'done') | -| `_DEPTH_STEMS` | ('concept', 'task', 'reference', 'quickstart', 'how-to', 'guide') | - -### UI profiles and security - -| Constant | Values | -|----------|--------| -| `_VALID_PROFILES` | ('developer', 'author', 'support') | -| `_DEFAULT_PROFILE` | 'developer' | -| `_ALLOWED_ORIGIN_HOSTS` | ('localhost', '127.0.0.1', '[::1]') | - -### File handling - -| Constant | Values | -|----------|--------| -| `_SHOW_HIDDEN` | ('.help', '.attune') | diff --git a/sidecar/.help/templates/attune-gui/task.md b/sidecar/.help/templates/attune-gui/task.md deleted file mode 100644 index 83c848f..0000000 --- a/sidecar/.help/templates/attune-gui/task.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -type: task -feature: attune-gui -depth: task -generated_at: 2026-05-05T00:12:55.669017+00:00 -source_hash: 373196211438f141eb9a7c64116a3e8312048764f33da724833860f48eb607bc -status: generated ---- - -# Work with attune gui - -Use attune-gui when you need a local web interface to manage help documentation, run commands, and edit corpus templates. - -## Prerequisites - -- Access to the project source code -- Python development environment set up -- Familiarity with FastAPI applications - -## Configure the application - -1. **Create the FastAPI app instance.** - Call `create_app()` from `attune_gui/app.py` to build the complete application with CORS, origin guard, and all routes: - ```python - from attune_gui.app import create_app - app = create_app() - ``` - -2. **Register commands for the GUI.** - Use the command registry to make functions available through the web interface. Check existing commands with `list_commands()` or add new ones following the `CommandSpec` pattern. - -3. **Set up corpus management.** - Initialize the corpus registry by calling `load_registry()` from `attune_gui/editor_corpora.py`. This loads your existing corpus configurations or creates an empty registry. - -## Run commands through the interface - -1. **List available commands.** - Call `list_commands(profile='developer')` to see all commands registered for your profile. Each command returns as a JSON-serializable dictionary with name, title, description, and argument schema. - -2. **Execute a specific command.** - Use `get_command(name)` to retrieve a `CommandSpec` by name, then call its executor function. The command system handles job tracking and cancellation automatically. - -3. **Monitor job status.** - Access the `JobRegistry` to track running commands. Jobs store output lines, status, timestamps, and results for display in the GUI. - -## Manage document corpora - -1. **Register a new corpus.** - Call `register(name, path)` to add a corpus directory to the registry: - ```python - entry = register("my-docs", "/path/to/docs", kind="source") - ``` - -2. **Switch active corpus.** - Use `set_active(corpus_id)` to change which corpus the editor works with. This raises `KeyError` if the corpus doesn't exist. - -3. **Save registry changes.** - Call `save_registry(reg)` to persist your corpus configuration to `~/.attune/corpora.json`. - -## Edit templates with live sessions - -1. **Start an editing session.** - Create an `EditorSession` for a specific file path: - ```python - session = EditorSession.load(abs_path, poll_interval=0.1) - session.start() - ``` - -2. **Update draft content.** - Call `session.update_draft(text)` to modify the working copy without affecting the base file. - -3. **Check for external changes.** - Use `session.matches_base()` to detect if the file changed on disk. Call `session.rebase()` to incorporate external changes. - -## Verify the setup - -Run the FastAPI development server and navigate to the local URL. You should see: -- The command interface loads without errors -- Corpus registry displays your configured corpora -- Template editor opens files from the active corpus -- Jobs execute and display output in real-time - -The application serves on localhost with CORS configured for local development and includes origin validation for security.