feat: filesystem directory picker for path fields (0.2.1)

- GET /api/fs/browse — server-side dir listing (dirs only, hides hidden
  except .attune/.help); breadcrumb nav + parent traversal
- PathBrowser.jsx — modal with breadcrumb nav, folder list, footer
  showing current path, Cancel/Select buttons
- PathField.jsx — wraps text input with Browse… button; inline red-
  border validation for relative paths (must start with / or ~)
- FormPanel routes ui:widget=path fields to PathField
- All project_path / project_root / help_dir / template_dir args now
  carry ui:widget=path so they render as pickers
- CommandsPanel: friendly domain labels (Search & Query / Author Docs /
  Help Lookup) instead of raw domain keys
- Bump version 0.2.0 → 0.2.1

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: silversurfer562

.help/features.yaml

@@ -0,0 +1,20 @@
+version: 1
+features:
+  attune_gui-entry:
+    description: 'Entry point: sidecar/attune_gui/app.py'
+    files:
+    - sidecar/attune_gui/app.py
+    tags:
+    - entry-point
+  scripts:
+    description: Scripts
+    files:
+    - scripts/**
+  sidecar:
+    description: Sidecar
+    files:
+    - sidecar/**
+  ui:
+    description: Ui
+    files:
+    - ui/**

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "attune-gui"
-version = "0.2.0"
+version = "0.2.1"
 description = "Local Living Docs dashboard for the attune-rag / attune-help / attune-author family. FastAPI sidecar + React UI."
 readme = "README.md"
 requires-python = ">=3.10"

sidecar/attune_gui/__init__.py

@@ -2,4 +2,4 @@
 
 from __future__ import annotations
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"

sidecar/attune_gui/app.py

@@ -11,7 +11,7 @@
 from fastapi.staticfiles import StaticFiles
 
 from attune_gui import __version__
-from attune_gui.routes import help, jobs, living_docs, profile, rag, system  # noqa: F401
+from attune_gui.routes import fs, help, jobs, living_docs, profile, rag, system  # noqa: F401
 from attune_gui.security import origin_guard
 
 logger = logging.getLogger(__name__)
@@ -38,6 +38,7 @@ def create_app() -> FastAPI:
     )
 
     app.include_router(system.router)
+    app.include_router(fs.router)
     app.include_router(rag.router)
     app.include_router(jobs.router)
     app.include_router(help.router)

sidecar/attune_gui/commands.py

@@ -226,11 +226,13 @@ async def _exec_author_generate(args: dict[str, Any], ctx: JobContext) -> dict[s
                     "type": "string",
                     "title": ".help/ path",
                     "default": ".help",
+                    "ui:widget": "path",
                 },
                 "project_root": {
                     "type": "string",
                     "title": "Project root",
                     "default": ".",
+                    "ui:widget": "path",
                 },
                 "all_kinds": {
                     "type": "boolean",
@@ -334,6 +336,7 @@ async def _exec_author_init(args: dict[str, Any], ctx: JobContext) -> dict[str,
                 "title": "Project root",
                 "default": ".",
                 "description": "Root of the project to scan.",
+                "ui:widget": "path",
             },
         },
     },
@@ -379,16 +382,23 @@ async def _exec_author_status(args: dict[str, Any], ctx: JobContext) -> dict[str
     args_schema={
         "type": "object",
         "properties": {
-            "project_path": {"type": "string", "title": "Project path", "default": ""},
+            "project_path": {
+                "type": "string",
+                "title": "Project path",
+                "default": "",
+                "ui:widget": "path",
+            },
             "help_dir": {
                 "type": "string",
                 "title": ".help/ path (overrides project_path)",
                 "default": "",
+                "ui:widget": "path",
             },
             "project_root": {
                 "type": "string",
                 "title": "Project root (overrides project_path)",
                 "default": "",
+                "ui:widget": "path",
             },
         },
     },
@@ -437,16 +447,23 @@ async def _exec_author_maintain(args: dict[str, Any], ctx: JobContext) -> dict[s
     args_schema={
         "type": "object",
         "properties": {
-            "project_path": {"type": "string", "title": "Project path", "default": ""},
+            "project_path": {
+                "type": "string",
+                "title": "Project path",
+                "default": "",
+                "ui:widget": "path",
+            },
             "help_dir": {
                 "type": "string",
                 "title": ".help/ path (overrides project_path)",
                 "default": "",
+                "ui:widget": "path",
             },
             "project_root": {
                 "type": "string",
                 "title": "Project root (overrides project_path)",
                 "default": "",
+                "ui:widget": "path",
             },
             "features": {
                 "type": "string",
@@ -521,7 +538,12 @@ async def _exec_author_lookup(args: dict[str, Any], ctx: JobContext) -> dict[str
                 "default": "concept",
                 "description": "concept | task | reference",
             },
-            "help_dir": {"type": "string", "title": ".help/ path", "default": ".help"},
+            "help_dir": {
+                "type": "string",
+                "title": ".help/ path",
+                "default": ".help",
+                "ui:widget": "path",
+            },
         },
         "required": ["query"],
     },
@@ -531,8 +553,6 @@ async def _exec_author_lookup(args: dict[str, Any], ctx: JobContext) -> dict[str
 )
 
 
-
-
 # ---------------------------------------------------------------------------
 # Help: lookup
 # ---------------------------------------------------------------------------
@@ -604,6 +624,7 @@ async def _exec_help_lookup(args: dict[str, Any], ctx: JobContext) -> dict[str,
                 "title": "Template dir",
                 "default": "",
                 "description": "Path to .help/templates/ directory. Leave blank to use bundled templates.",
+                "ui:widget": "path",
             },
         },
         "required": ["topic"],
@@ -663,6 +684,7 @@ async def _exec_help_search(args: dict[str, Any], ctx: JobContext) -> dict[str,
                 "title": "Template dir",
                 "default": "",
                 "description": "Path to .help/templates/ directory. Leave blank to use bundled templates.",
+                "ui:widget": "path",
             },
         },
         "required": ["query"],
@@ -714,6 +736,7 @@ async def _exec_help_list(args: dict[str, Any], ctx: JobContext) -> dict[str, An
                 "title": "Template dir",
                 "default": "",
                 "description": "Path to .help/templates/ directory. Leave blank to use bundled templates.",
+                "ui:widget": "path",
             },
         },
     },

sidecar/attune_gui/routes/fs.py

@@ -0,0 +1,49 @@
+"""Filesystem browsing — directories only, local use."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException, Query
+
+router = APIRouter(prefix="/api/fs", tags=["fs"])
+
+_SHOW_HIDDEN = {".help", ".attune"}
+
+
+@router.get("/browse")
+async def browse(path: str = Query(default="~")) -> dict:
+    """Return directory listing for *path*.
+
+    Only directories are included. Hidden entries (names starting with ``.'')
+    are suppressed except for a small allow-list that is relevant to attune.
+    """
+    try:
+        resolved = Path(path).expanduser().resolve()
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=f"Invalid path: {exc}") from exc
+
+    if not resolved.is_dir():
+        raise HTTPException(status_code=400, detail=f"Not a directory: {resolved}")
+
+    try:
+        children = sorted(resolved.iterdir(), key=lambda p: p.name.lower())
+    except PermissionError as exc:
+        raise HTTPException(status_code=403, detail=str(exc)) from exc
+
+    entries = []
+    for child in children:
+        if not child.is_dir():
+            continue
+        name = child.name
+        if name.startswith(".") and name not in _SHOW_HIDDEN:
+            continue
+        entries.append({"name": name, "path": str(child)})
+
+    parent = str(resolved.parent) if resolved.parent != resolved else None
+
+    return {
+        "path": str(resolved),
+        "parent": parent,
+        "entries": entries,
+    }

ui/src/components/CommandsPanel.jsx

@@ -1,3 +1,9 @@
+const DOMAIN_LABELS = {
+  rag: 'Search & Query',
+  author: 'Author Docs',
+  help: 'Help Lookup',
+}
+
 export default function CommandsPanel({ commands, selected, onSelect }) {
   const byDomain = {}
   for (const c of commands) {
@@ -10,7 +16,7 @@ export default function CommandsPanel({ commands, selected, onSelect }) {
       <div className="col-body">
         {Object.entries(byDomain).map(([domain, cmds]) => (
           <div key={domain} className="cmd-domain">
-            <div className="cmd-domain-label">{domain}</div>
+            <div className="cmd-domain-label">{DOMAIN_LABELS[domain] ?? domain}</div>
             {cmds.map(c => (
               <button
                 key={c.name}

ui/src/components/FormPanel.jsx

@@ -1,5 +1,6 @@
 import { useState, useEffect } from 'react'
 import { api } from '../api'
+import PathField from './PathField'
 
 function buildDefaults(schema) {
   const props = schema?.properties || {}
@@ -100,6 +101,19 @@ export default function FormPanel({ cmd, onJobStarted, bootError }) {
         </div>
       )
     }
+    if (prop['ui:widget'] === 'path') {
+      return (
+        <PathField
+          key={key}
+          id={`f_${key}`}
+          value={val}
+          label={label}
+          isRequired={isReq}
+          description={desc}
+          onChange={v => set(key, v)}
+        />
+      )
+    }
     if (prop['ui:widget'] === 'textarea') {
       return (
         <div key={key} className="field">

ui/src/components/PathBrowser.jsx

@@ -0,0 +1,108 @@
+import { useState, useEffect, useCallback } from 'react'
+import { api } from '../api'
+
+export default function PathBrowser({ initialPath, onSelect, onClose }) {
+  const [data, setData] = useState(null)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState(null)
+
+  const load = useCallback(async (path) => {
+    setLoading(true)
+    setError(null)
+    try {
+      const result = await api(`/api/fs/browse?path=${encodeURIComponent(path)}`)
+      setData(result)
+    } catch (err) {
+      setError(err.message)
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    load(initialPath || '~')
+  }, []) // eslint-disable-line react-hooks/exhaustive-deps
+
+  const breadcrumbs = data ? buildCrumbs(data.path) : []
+
+  function handleKey(e) {
+    if (e.key === 'Escape') onClose()
+  }
+
+  return (
+    <div className="pb-backdrop" onClick={onClose} onKeyDown={handleKey}>
+      <div className="pb-modal" onClick={e => e.stopPropagation()} role="dialog" aria-modal="true">
+        <div className="pb-header">
+          <span className="pb-title">Select directory</span>
+          <button className="pb-close" onClick={onClose} aria-label="Close">✕</button>
+        </div>
+
+        <div className="pb-crumbs">
+          {breadcrumbs.map((crumb, i) => (
+            <span key={crumb.path} className="pb-crumb">
+              {i > 0 && <span className="pb-sep">/</span>}
+              <button className="pb-crumb-btn" onClick={() => load(crumb.path)}>
+                {crumb.label || '/'}
+              </button>
+            </span>
+          ))}
+        </div>
+
+        <div className="pb-list">
+          {loading && <div className="pb-status">Loading…</div>}
+          {error && <div className="pb-status pb-error">{error}</div>}
+          {!loading && !error && data && (
+            <>
+              {data.parent && (
+                <button className="pb-entry pb-up" onClick={() => load(data.parent)}>
+                  ↑ ..
+                </button>
+              )}
+              {data.entries.length === 0 && (
+                <div className="pb-status">No subdirectories</div>
+              )}
+              {data.entries.map(entry => (
+                <button
+                  key={entry.path}
+                  className="pb-entry"
+                  onClick={() => load(entry.path)}
+                >
+                  <span className="pb-icon">📁</span>
+                  <span className="pb-entry-name">{entry.name}</span>
+                </button>
+              ))}
+            </>
+          )}
+        </div>
+
+        <div className="pb-footer">
+          {data && (
+            <span className="pb-current-path">{data.path}</span>
+          )}
+          <div className="pb-actions">
+            <button className="ghost" onClick={onClose}>Cancel</button>
+            <button
+              className="primary"
+              disabled={!data}
+              onClick={() => { if (data) onSelect(data.path) }}
+            >
+              Select
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function buildCrumbs(absPath) {
+  const parts = absPath.split('/').filter(Boolean)
+  const crumbs = [{ label: '', path: '/' }]
+  for (let i = 0; i < parts.length; i++) {
+    crumbs.push({
+      label: parts[i],
+      path: '/' + parts.slice(0, i + 1).join('/'),
+    })
+  }
+  return crumbs
+}