@try-works/dsh-recursive-mode 0.2.3 → 0.2.4

package/src/client/styles.ts

@@ -532,6 +532,316 @@ const BOARD_CSS = `
   color: var(--board-muted-fg);
 }
 
+/* ===== Per-phase doc viewer (0.2.4, inside the inspector detail body) ===== */
+
+/* View phase ghost button on each present phase row. */
+.rec-phase-view {
+  flex: none;
+  padding: 3px 10px;
+  font-size: var(--board-text-xs);
+  color: var(--board-info);
+  background: transparent;
+  border: 1px solid var(--board-border);
+  border-radius: 999px;
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.rec-phase-view:hover {
+  background: var(--board-accent);
+}
+
+/* Viewer shell: fills the inspector detail body (the panel owns data-theme). */
+.rec-doc {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  gap: var(--board-space-12);
+  color: var(--board-fg);
+  font-family: var(--board-font-sans);
+  background: var(--board-bg);
+  border: 1px solid var(--board-border);
+  border-radius: var(--board-radius-xl);
+  overflow: hidden;
+}
+
+.rec-doc-header {
+  display: flex;
+  align-items: center;
+  gap: var(--board-space-12);
+  padding: var(--board-space-12) var(--board-space-16);
+  border-bottom: 1px solid var(--board-border);
+  flex: none;
+}
+
+.rec-doc-heading {
+  display: flex;
+  align-items: baseline;
+  gap: var(--board-space-12);
+  flex: 1;
+  min-width: 0;
+}
+
+.rec-doc-badge {
+  flex: none;
+  padding: 2px 10px;
+  font-size: 11px;
+  font-weight: var(--board-fw-semibold);
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+  border-radius: 999px;
+  background: var(--board-accent);
+  color: var(--board-muted-fg);
+}
+
+.rec-doc-title {
+  margin: 0;
+  font-size: var(--board-text-sm);
+  font-weight: var(--board-fw-semibold);
+  letter-spacing: var(--board-tracking-tight);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.rec-doc-run {
+  flex: none;
+  font-family: var(--board-font-mono);
+  font-size: var(--board-text-xs);
+  color: var(--board-muted-fg);
+}
+
+.rec-doc-btn {
+  flex: none;
+  padding: 5px 12px;
+  font-size: var(--board-text-xs);
+  color: var(--board-fg);
+  background: transparent;
+  border: 1px solid var(--board-border);
+  border-radius: 999px;
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.rec-doc-btn:hover {
+  background: var(--board-accent);
+}
+
+/* Search bar (/ to open). */
+.rec-doc-search {
+  display: flex;
+  align-items: center;
+  gap: var(--board-space-12);
+  padding: var(--board-space-8) var(--board-space-16);
+  border-bottom: 1px solid var(--board-border);
+  flex: none;
+}
+
+.rec-doc-search-input {
+  flex: 1 1 auto;
+  background: var(--board-muted);
+  color: var(--board-fg);
+  border: 1px solid var(--board-border);
+  border-radius: var(--board-radius-md);
+  padding: 5px 10px;
+  font-size: var(--board-text-xs);
+  font-family: inherit;
+  min-width: 0;
+}
+
+.rec-doc-search-input::placeholder {
+  color: var(--board-muted-fg);
+  opacity: 1;
+}
+
+.rec-doc-search-count {
+  font-size: var(--board-text-xs);
+  color: var(--board-muted-fg);
+  white-space: nowrap;
+}
+
+/* Body: scrollable line list. */
+.rec-doc-body {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+  padding: var(--board-space-12) var(--board-space-16) var(--board-space-16);
+}
+
+.rec-doc-line {
+  font-size: var(--board-text-sm);
+  line-height: 1.7;
+  padding: 0 6px;
+  border-left: 2px solid transparent;
+}
+
+.rec-doc-line-current {
+  background: var(--board-muted);
+  border-left-color: var(--board-info);
+}
+
+.rec-doc-blank {
+  height: 10px;
+}
+
+.rec-doc-plain {
+  white-space: pre-wrap;
+}
+
+.rec-doc-h1 {
+  font-size: 22px;
+  font-weight: 700;
+  margin: 8px 0 6px;
+  line-height: 1.3;
+}
+
+.rec-doc-h2 {
+  font-size: 18px;
+  font-weight: 600;
+  margin: 12px 0 4px;
+  line-height: 1.3;
+}
+
+.rec-doc-h3 {
+  font-size: 15px;
+  font-weight: 600;
+  margin: 10px 0 4px;
+  line-height: 1.3;
+}
+
+.rec-doc-h4 {
+  font-size: 14px;
+  font-weight: 600;
+  margin: 8px 0 4px;
+  line-height: 1.3;
+}
+
+.rec-doc-li {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  font-size: var(--board-text-sm);
+  line-height: 1.65;
+  margin: 0 0 4px;
+}
+
+.rec-doc-bullet {
+  flex: none;
+  color: var(--board-muted-fg);
+  width: 14px;
+  text-align: center;
+}
+
+.rec-doc-li-text {
+  flex: 1;
+  min-width: 0;
+}
+
+.rec-doc-pre {
+  margin: 6px 0;
+  padding: var(--board-space-12);
+  background: var(--board-muted);
+  border: 1px solid var(--board-border);
+  border-radius: var(--board-radius-md);
+  overflow-x: auto;
+}
+
+.rec-doc-code,
+.rec-doc-inline-code {
+  font-family: var(--board-font-mono);
+  font-size: 12.5px;
+  letter-spacing: var(--board-tracking-mono);
+}
+
+.rec-doc-inline-code {
+  background: var(--board-muted);
+  border: 1px solid var(--board-border);
+  border-radius: 4px;
+  padding: 0 4px;
+}
+
+.rec-doc-inline-link {
+  color: var(--board-info);
+  text-decoration: underline;
+  cursor: pointer;
+}
+
+.rec-doc-table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 6px 0;
+  font-size: var(--board-text-xs);
+}
+
+.rec-doc-table th,
+.rec-doc-table td {
+  border: 1px solid var(--board-border);
+  padding: 4px 8px;
+  text-align: left;
+}
+
+.rec-doc-table th {
+  background: var(--board-muted);
+  color: var(--board-muted-fg);
+  font-weight: var(--board-fw-semibold);
+}
+
+/* Footer: status + key hints. */
+.rec-doc-footer {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: var(--board-space-16);
+  padding: var(--board-space-8) var(--board-space-16);
+  border-top: 1px solid var(--board-border);
+  flex-wrap: wrap;
+}
+
+.rec-doc-status {
+  font-size: var(--board-text-xs);
+  color: var(--board-muted-fg);
+  min-width: 120px;
+}
+
+.rec-doc-status-error {
+  color: var(--board-error);
+}
+
+.rec-doc-status-ok {
+  color: var(--board-success);
+}
+
+.rec-doc-hints {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  flex-wrap: wrap;
+  font-size: var(--board-text-xs);
+  color: var(--board-muted-fg);
+}
+
+.rec-doc-hints kbd {
+  background: var(--board-muted);
+  border: 1px solid var(--board-border);
+  border-radius: 4px;
+  padding: 1px 6px;
+  font-family: inherit;
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--board-fg);
+  margin: 0 3px 0 8px;
+}
+
+.rec-doc-text {
+  margin: 0;
+  font-size: var(--board-text-sm);
+  color: var(--board-muted-fg);
+}
+
+.rec-doc-error {
+  color: var(--board-error);
+}
+
 /* ===== Strip (session dock) — keeps the shell --dsw-* theme ===== */
 .rec-badge {
   flex: none;

package/src/live-route.ts

@@ -17,7 +17,10 @@
  * would be both wrong and a crash).
  */
 import type { IncomingMessage, ServerResponse } from 'node:http'
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve, sep } from 'node:path'
 import type { RecursiveProjection } from './types.ts'
+import { RUN_ARTIFACT_SEQUENCE } from './status.ts'
 
 /** API prefix the board/strip fetch. */
 export const RECURSIVE_API_PREFIX = '/.recursive/api'
@@ -65,8 +68,72 @@ function queryOf(req: IncomingMessage, name: string): string {
   return new URLSearchParams(url.slice(q + 1)).get(name) ?? ''
 }
 
+/** Phase-doc basename allowlist (the run artifact sequence: single *.md, no subdirs). */
+const PHASE_DOC_FILES = new Set(RUN_ARTIFACT_SEQUENCE)
+
+/** runId/file safety: alphanumerics, dot, underscore, dash only; no '..', no separators. */
+const DOC_SAFE_RE = /^[A-Za-z0-9._-]+$/
+
+/** Invalid runId or file name (path traversal / subdir / non-phase doc) — reject. */
+function docTargetError(runId: string, file: string): string | null {
+  if (!DOC_SAFE_RE.test(runId) || runId.includes('..')) return 'invalid runId'
+  if (!DOC_SAFE_RE.test(file) || file.includes('..') || file.includes('/') || file.includes('\\')) return 'invalid file'
+  if (!file.endsWith('.md')) return 'invalid file: must be a .md phase doc'
+  if (!PHASE_DOC_FILES.has(file)) return 'invalid file: not a phase doc'
+  return null
+}
+
+/**
+ * The lazy per-phase doc route (0.2.4): GET the raw markdown of one run phase
+ * doc, read ON DEMAND from the filesystem. NOT part of the /state or /events
+ * projection payloads (they stay fold-only). Same browser-marker tripwire as
+ * state/events; the client root is re-validated by the host (never trusted:
+ * an unknown root -> 400), then the resolved doc path is containment-checked
+ * under join(root, '.recursive', 'run', runId).
+ */
+function docRoute(host: RecursiveRouteHost) {
+  return {
+    kind: 'exact' as const,
+    path: RECURSIVE_API_PREFIX + '/doc',
+    handler: async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+      if (req.method !== 'GET') { res.writeHead(405); res.end(); return }
+      if (!browserMarker(req)) { res.writeHead(403); res.end(); return }
+      const root = queryOf(req, 'root')
+      const runId = queryOf(req, 'runId')
+      const file = queryOf(req, 'file')
+      const targetError = docTargetError(runId, file)
+      if (root === '' || targetError !== null) {
+        json(res, 400, { ok: false, error: targetError ?? 'missing root' })
+        return
+      }
+      // Root validation: the client passes back what the host already resolved.
+      // Re-resolve via the host and require a canonical match — never accept an
+      // arbitrary path (registry know-it or headless cwd pass-through).
+      const resolvedRoot = await host.resolveRoot(undefined, root)
+      if (resolvedRoot === null || resolve(resolvedRoot) !== resolve(root)) {
+        json(res, 400, { ok: false, error: 'root is not a known workspace' })
+        return
+      }
+      // Containment: the doc must stay under join(root, .recursive, run, runId).
+      const runBase = resolve(root, '.recursive', 'run', runId)
+      const docPath = resolve(runBase, file)
+      if (docPath === runBase || !docPath.startsWith(runBase + sep)) {
+        json(res, 400, { ok: false, error: 'doc path escapes the run dir' })
+        return
+      }
+      if (!existsSync(docPath)) {
+        json(res, 404, { ok: false, error: 'phase doc not found' })
+        return
+      }
+      const text = readFileSync(docPath, 'utf8')
+      res.writeHead(200, { 'content-type': 'text/markdown; charset=utf-8', 'cache-control': 'no-store' })
+      res.end(text)
+    },
+  }
+}
+
 /**
- * Build the two read-only routes. Returns [state, events] in registration order.
+ * Build the read-only routes. Returns [state, events, doc] in registration order.
  * @param host - the resolved-root + fs-fold seam (the RecursiveRuntime adapter).
  */
 export function makeRecursiveRoutes(host: RecursiveRouteHost): readonly { kind: 'exact'; path: string; handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void> }[] {
@@ -109,7 +176,7 @@ export function makeRecursiveRoutes(host: RecursiveRouteHost): readonly { kind:
       await push()
     },
   }
-  return [state, events]
+  return [state, events, docRoute(host)]
 }
 
 /**