refactor(commands): proxy 3 help.* commands to attune-author (D3) (#26)

Phase D3 of the architecture-realignment spec, gui side. The
three ``help.*`` executor bodies (lookup, search, list) moved to
attune-author 0.9.1; this change drops the in-line CommandSpecs +
``_help_engine`` factory and replaces them with three
``_proxy_command(...)`` registrations.

None of the three needs workspace pre-resolution or post-dispatch
invalidation, so plain ``_proxy_command`` is sufficient — no
``_author_proxy``-style specialization required.

Diff stat: +107 / -275. Bumps gui to 0.6.2; pins
attune-author[ai] to >=0.9.1,<0.10.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: silversurfer562

CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes to `attune-gui` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.6.2] — 2026-05-08
+
+### Changed
+
+- **All three `help.*` commands now dispatch through `attune_author.orchestration`.** Phase D3 of the architecture-realignment spec: `lookup`, `search`, `list`. The executor bodies live in attune-author 0.9.1; the gui keeps thin proxy `CommandSpec`s registered via `_proxy_command(...)`. None of the three need workspace pre-resolution or post-dispatch invalidation, so plain `_proxy_command` is sufficient.
+- `commands.py` shrank by ~200 more lines (three executors + `_help_engine` factory + three in-line specs replaced by three proxy registrations + a one-line import).
+- `_help_engine` factory removed from `attune_gui.commands` — no production callers after this PR. A lazy-import variant lives in attune-author at `attune_author.orchestration.commands.help._help_engine`.
+
+### Tests
+
+- `TestHelpEngineFactory` and `TestHelpExecutors` removed; coverage now lives in `attune-author/tests/test_orchestration_commands_help.py`.
+- New `TestHelpProxies` class: registration check, metadata mirroring, dispatch through `run_command` for all three commands.
+
+### Dependencies
+
+- Bumped `attune-author[ai]` constraint from `>=0.9.0,<0.10` to `>=0.9.1,<0.10`.
+
 ## [0.6.1] — 2026-05-08
 
 ### Changed

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "attune-gui"
-version = "0.6.1"
+version = "0.6.2"
 description = "Local dashboard for attune-rag / attune-help / attune-author. Server-rendered Jinja2 UI — ships clean via PyPI with no npm step."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -30,7 +30,7 @@ dependencies = [
     "pydantic>=2.0,<3.0",
     "structlog>=24.0,<26.0",
     "attune-rag>=0.1.12,<0.2",
-    "attune-author[ai]>=0.9.0,<0.10",
+    "attune-author[ai]>=0.9.1,<0.10",
     "attune-help>=0.10.0,<1.0",
     "jinja2>=3.1,<4.0",
     "python-frontmatter>=1.1,<2.0",

sidecar/attune_gui/commands.py

@@ -484,205 +484,17 @@ async def _exec_author_generate(args: dict[str, Any], ctx: JobContext) -> dict[s
 
 
 # ---------------------------------------------------------------------------
-# Help: lookup
+# help.* commands now live in attune_author.orchestration.commands.help
+# (Phase D3 of the architecture-realignment spec). None of the three
+# need workspace pre-resolution or post-dispatch invalidation, so plain
+# _proxy_command is sufficient.
 # ---------------------------------------------------------------------------
 
+import attune_author.orchestration.commands.help  # noqa: F401, E402
 
-def _help_engine(template_dir: str | None, job_id: str):
-    from pathlib import Path as _Path  # noqa: PLC0415
-
-    from attune_help import HelpEngine  # noqa: PLC0415
-
-    return HelpEngine(
-        template_dir=_Path(template_dir).resolve() if template_dir else None,
-        renderer="plain",
-        user_id=job_id,
-    )
-
-
-async def _exec_help_lookup(args: dict[str, Any], ctx: JobContext) -> dict[str, Any]:
-    topic = args["topic"]
-    depth = args.get("depth", "concept")
-    template_dir = args.get("template_dir") or None
-
-    depth_steps = {"concept": 1, "task": 2, "reference": 3}
-    steps = depth_steps.get(depth, 1)
-
-    engine = _help_engine(template_dir, ctx.job_id)
-    ctx.log(f"Looking up {topic!r} at depth={depth} ({steps} step(s))…")
-
-    content = None
-    for _ in range(steps):
-        content = await asyncio.to_thread(engine.lookup, topic, suggest_on_miss=True)
-
-    if content is None:
-        raise ValueError(f"No help found for topic {topic!r}.")
-
-    topics = await asyncio.to_thread(engine.list_topics)
-    ctx.log(f"Retrieved from {engine.generated_dir}")
-    return {
-        "topic": topic,
-        "depth": depth,
-        "content": content,
-        "template_dir": str(engine.generated_dir),
-        "total_topics": len(topics),
-    }
-
-
-COMMANDS["help.lookup"] = CommandSpec(
-    name="help.lookup",
-    title="Help lookup",
-    domain="help",
-    description="Look up a help topic with progressive depth (concept → task → reference).",
-    args_schema={
-        "type": "object",
-        "properties": {
-            "topic": {
-                "type": "string",
-                "title": "Topic",
-                "minLength": 1,
-                "description": "Topic slug or feature name to look up.",
-            },
-            "depth": {
-                "type": "string",
-                "title": "Depth",
-                "default": "concept",
-                "description": "concept | task | reference",
-            },
-            "template_dir": {
-                "type": "string",
-                "title": "Template dir",
-                "default": "",
-                "description": (
-                    "Path to .help/templates/ directory. " "Leave blank to use bundled templates."
-                ),
-                "ui:widget": "path",
-            },
-        },
-        "required": ["topic"],
-    },
-    executor=_exec_help_lookup,
-    cancellable=False,
-    profiles=("developer", "author"),
-)
-
-
-# ---------------------------------------------------------------------------
-# Help: search
-# ---------------------------------------------------------------------------
-
-
-async def _exec_help_search(args: dict[str, Any], ctx: JobContext) -> dict[str, Any]:
-    query = args["query"]
-    limit = int(args.get("limit", 10))
-    template_dir = args.get("template_dir") or None
-
-    engine = _help_engine(template_dir, "search")
-    ctx.log(f"Searching {query!r} (limit={limit})…")
-
-    results = await asyncio.to_thread(engine.search, query, limit=limit)
-    ctx.log(f"Found {len(results)} result(s)")
-    return {
-        "query": query,
-        "results": results,
-        "count": len(results),
-        "template_dir": str(engine.generated_dir),
-    }
-
-
-COMMANDS["help.search"] = CommandSpec(
-    name="help.search",
-    title="Help search",
-    domain="help",
-    description="Fuzzy-search help topics by keyword across the template library.",
-    args_schema={
-        "type": "object",
-        "properties": {
-            "query": {
-                "type": "string",
-                "title": "Query",
-                "minLength": 1,
-                "description": "Keyword or phrase to search for.",
-            },
-            "limit": {
-                "type": "integer",
-                "title": "Limit",
-                "default": 10,
-                "minimum": 1,
-                "maximum": 50,
-            },
-            "template_dir": {
-                "type": "string",
-                "title": "Template dir",
-                "default": "",
-                "description": (
-                    "Path to .help/templates/ directory. " "Leave blank to use bundled templates."
-                ),
-                "ui:widget": "path",
-            },
-        },
-        "required": ["query"],
-    },
-    executor=_exec_help_search,
-    cancellable=False,
-    profiles=("developer", "author"),
-)
-
-
-# ---------------------------------------------------------------------------
-# Help: list
-# ---------------------------------------------------------------------------
-
-
-async def _exec_help_list(args: dict[str, Any], ctx: JobContext) -> dict[str, Any]:
-    type_filter = args.get("type_filter") or None
-    template_dir = args.get("template_dir") or None
-
-    engine = _help_engine(template_dir, "list")
-    ctx.log(f"Listing topics{f' (type={type_filter})' if type_filter else ''}…")
-
-    topics = await asyncio.to_thread(engine.list_topics, type_filter=type_filter)
-    ctx.log(f"{len(topics)} topic(s) found in {engine.generated_dir}")
-    return {
-        "topics": topics,
-        "count": len(topics),
-        "type_filter": type_filter,
-        "template_dir": str(engine.generated_dir),
-    }
-
-
-COMMANDS["help.list"] = CommandSpec(
-    name="help.list",
-    title="List topics",
-    domain="help",
-    description=(
-        "List all available help topics, "
-        "optionally filtered by type (concepts, tasks, references)."
-    ),
-    args_schema={
-        "type": "object",
-        "properties": {
-            "type_filter": {
-                "type": "string",
-                "title": "Type filter",
-                "default": "",
-                "description": "concepts | tasks | references | (blank for all)",
-            },
-            "template_dir": {
-                "type": "string",
-                "title": "Template dir",
-                "default": "",
-                "description": (
-                    "Path to .help/templates/ directory. " "Leave blank to use bundled templates."
-                ),
-                "ui:widget": "path",
-            },
-        },
-    },
-    executor=_exec_help_list,
-    cancellable=False,
-    profiles=("developer", "author"),
-)
+COMMANDS["help.lookup"] = _proxy_command("help.lookup")
+COMMANDS["help.search"] = _proxy_command("help.search")
+COMMANDS["help.list"] = _proxy_command("help.list")
 
 
 COMMANDS["author.regen"] = _author_proxy(