@hanzlaa/rcode 3.5.0 → 3.6.0

package/server/lib/html/client/orchestrator.js

@@ -0,0 +1,279 @@
+/**
+ * orchestrator.js — ESM client for the orchestrator service.
+ *
+ * Pure logic: no DOM-by-id, no innerHTML. All state flows through the
+ * Preact store (activeSessions field). Components import these functions
+ * directly; no window.* globals needed after Sprint 31.4.
+ *
+ * Constants
+ *   ORCH_HTTP — base URL for orchestrator REST API
+ *   ORCH_WS   — base URL for orchestrator WebSocket
+ */
+
+import { getState, setState } from './store.js';
+import { showToast } from './components/shared.js';
+
+export const ORCH_HTTP = 'http://localhost:7718';
+export const ORCH_WS   = 'ws://localhost:7718';
+
+// ── Token helpers ─────────────────────────────────────────────────────────────
+
+/** Return the current orchestrator token from the window global. */
+export function orchToken() {
+  return (typeof window !== 'undefined' && window.__ORCH_TOKEN__) || '';
+}
+
+/**
+ * Re-fetch the live orchestrator token from the dashboard (same-origin).
+ * Self-heals a long-open tab if the embedded token drifts.
+ */
+export function refreshOrchToken() {
+  return fetch('/api/orch-token')
+    .then(r => r.json())
+    .then(d => { if (d && d.token) window.__ORCH_TOKEN__ = d.token; })
+    .catch(() => {});
+}
+
+// ── REST actions ──────────────────────────────────────────────────────────────
+
+/**
+ * POST /api/run — start a PTY session for storyId.
+ * Returns the parsed JSON response (or throws on network error).
+ */
+export function runSession(storyId, cmd) {
+  const tok = orchToken();
+  return fetch(ORCH_HTTP + '/api/run', {
+    method: 'POST',
+    headers: { 'Authorization': 'Bearer ' + tok, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ storyId, cmd }),
+  }).then(r => r.json());
+}
+
+/**
+ * POST /api/stop — stop a running session.
+ */
+export function stopSession(storyId) {
+  const tok = orchToken();
+  return fetch(ORCH_HTTP + '/api/stop', {
+    method: 'POST',
+    headers: { 'Authorization': 'Bearer ' + tok, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ storyId }),
+  }).catch(() => {});
+}
+
+/**
+ * GET /api/sessions — return the sessions array (or [] on error).
+ */
+export function fetchSessions() {
+  const tok = orchToken();
+  if (!tok) return Promise.resolve([]);
+  return fetch(ORCH_HTTP + '/api/sessions', {
+    headers: { 'Authorization': 'Bearer ' + tok },
+  })
+    .then(r => {
+      if (r.status === 401) { refreshOrchToken(); return []; }
+      return r.json().then(d => (d && d.sessions) || []);
+    })
+    .catch(() => []);
+}
+
+/**
+ * POST /api/clean-sessions — remove sessions older than N days.
+ */
+export function cleanSessions(olderThanDays = 7) {
+  const tok = orchToken();
+  return fetch(ORCH_HTTP + '/api/clean-sessions', {
+    method: 'POST',
+    headers: { 'Authorization': 'Bearer ' + tok, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ olderThanDays }),
+  })
+    .then(r => r.json())
+    .catch(() => ({ removed: 0 }));
+}
+
+// ── Session-awareness helpers ─────────────────────────────────────────────────
+// These read activeSessions from the store — components subscribe to the store
+// and re-render when the poll writes new data.
+
+/** Return the session object for storyId, or null. */
+export function activeSession(storyId) {
+  const { activeSessions } = getState();
+  return (activeSessions || []).find(s => s.storyId === storyId) || null;
+}
+
+/** True when storyId has a session with status==='running'. */
+export function isSessionRunning(storyId) {
+  const s = activeSession(storyId);
+  return !!(s && s.status === 'running');
+}
+
+/** Count running sessions touching this sprint (sprint-level + its stories). */
+export function runningInSprint(sp) {
+  let n = isSessionRunning('sprint-' + sp.id) ? 1 : 0;
+  (sp.stories || []).forEach(st => { if (st.id && isSessionRunning(st.id)) n++; });
+  return n;
+}
+
+/** Count running sessions touching this phase. */
+export function runningInPhase(p) {
+  let n = isSessionRunning('phase-' + p.id) ? 1 : 0;
+  (p.sprints || []).forEach(sp => { n += runningInSprint(sp); });
+  return n;
+}
+
+/** Total count of sessions with status==='running'. */
+export function runningTotal() {
+  const { activeSessions } = getState();
+  return (activeSessions || []).filter(s => s.status === 'running').length;
+}
+
+// ── Session poll ──────────────────────────────────────────────────────────────
+
+let _pollTimer = null;
+
+/**
+ * Start polling /api/sessions every 4 s and writing activeSessions into the
+ * store. Components react via useStore(). Safe to call multiple times — only
+ * one poll runs at a time.
+ */
+export function startSessionsPoll() {
+  if (_pollTimer) return;
+  _poll();
+  _pollTimer = setInterval(_poll, 4000);
+}
+
+/** Stop the session poll (e.g. when the dashboard is idle). */
+export function stopSessionsPoll() {
+  if (_pollTimer) { clearInterval(_pollTimer); _pollTimer = null; }
+}
+
+function _poll() {
+  fetchSessions().then(sessions => {
+    setState({ activeSessions: sessions });
+  });
+}
+
+// ── runAndOpenTerm convenience ────────────────────────────────────────────────
+
+/**
+ * Start a PTY session then open the xterm terminal panel.
+ * The terminal panel is driven by store state (terminal field).
+ *
+ * @param {string} storyId
+ * @param {string} cmd
+ * @param {string} title
+ */
+export function runAndOpenTerm(storyId, cmd, title) {
+  // Open the panel immediately (it shows "connecting" while the session starts).
+  setState({
+    terminal: {
+      open: true,
+      storyId,
+      title: title || storyId,
+      minimized: false,
+      fullscreen: false,
+    },
+  });
+
+  const tok = orchToken();
+  if (!tok) return;
+
+  runSession(storyId, cmd).catch(() => {});
+}
+
+/**
+ * Open the xterm panel for an already-running session (no POST /api/run).
+ */
+export function openTermPanel(storyId, title) {
+  setState({
+    terminal: {
+      open: true,
+      storyId,
+      title: title || storyId,
+      minimized: false,
+      fullscreen: false,
+    },
+  });
+}
+
+/**
+ * Open the orchestrator side panel for storyId.
+ * Stored in store.orchPanel so OrchPanel reacts.
+ */
+export function openOrchPanel(storyId) {
+  setState({ orchPanel: { open: true, storyId } });
+}
+
+/**
+ * runStory — Kanban "Run" action. Moves card to in_progress visually then
+ * delegates to runAndOpenTerm.
+ */
+export function runStory(storyId) {
+  if (!storyId) return;
+  runAndOpenTerm(storyId, '/rihal-dev-story ' + storyId, storyId);
+}
+
+/**
+ * stopStory — Kanban "Stop" action.
+ */
+export function stopStory(storyId) {
+  stopSession(storyId);
+}
+
+// ── Command runner ────────────────────────────────────────────────────────────
+/**
+ * Client-side allowlist — mirrors the server COMMAND_ALLOWLIST.
+ * The server always re-validates; this list drives the picker dropdown only.
+ * Update both when adding a new command.
+ */
+export const ALLOWED_COMMANDS = [
+  { cmd: '/rihal-init',          label: 'init — initialise project workspace' },
+  { cmd: '/rihal-status',        label: 'status — phase / sprint status' },
+  { cmd: '/rihal-progress',      label: 'progress — milestone progress' },
+  { cmd: '/rihal-help',          label: 'help — command reference' },
+  { cmd: '/rihal-health',        label: 'health — repo health check' },
+  { cmd: '/rihal-next',          label: 'next — suggest next action' },
+  { cmd: '/rihal-show',          label: 'show — show current plan' },
+  { cmd: '/rihal-list-plans',    label: 'list-plans — list all sprint plans' },
+  { cmd: '/rihal-sprint-status', label: 'sprint-status — sprint execution status' },
+  { cmd: '/rihal-config',        label: 'config — show rihal config' },
+  { cmd: '/rihal-diff',          label: 'diff — diff since last checkpoint' },
+  { cmd: '/rihal-stats',         label: 'stats — project statistics' },
+];
+
+/**
+ * Launch an allowlisted rihal command from the dashboard command runner.
+ * Uses a synthetic storyId derived from the command slug so it shows up as
+ * its own session in the Orchestration grid.
+ *
+ * storyId format: "cmd-rihal-init" (satisfies STORY_ID_RE /^[A-Za-z0-9._-]+$/).
+ *
+ * Surfaces errors as toast notifications:
+ *   - 403 / 503 / any server error message  → showToast('Command error: ...')
+ *   - 409 "already running"                  → no toast (expected; terminal reattaches)
+ *   - network failure                         → showToast('Could not reach orchestrator')
+ *
+ * @param {string} cmd  Must be one of ALLOWED_COMMANDS[*].cmd.
+ */
+export function runCommandFromUI(cmd) {
+  if (!cmd) return;
+  const slug    = cmd.replace(/^\//, '').replace(/\//g, '-');
+  const storyId = 'cmd-' + slug;
+  const title   = cmd + ' (command runner)';
+  // Open the terminal panel immediately so the user gets visual feedback.
+  setState({
+    terminal: { open: true, storyId, title, minimized: false, fullscreen: false },
+  });
+
+  const tok = orchToken();
+  if (!tok) { showToast('No orchestrator token — restart the dashboard'); return; }
+
+  runSession(storyId, cmd)
+    .then(data => {
+      // 409 = already running (not an error — terminal is already attached).
+      if (data && data.error && !data.error.includes('already running')) {
+        showToast('Command error: ' + data.error);
+      }
+    })
+    .catch(() => showToast('Could not reach orchestrator'));
+}

package/server/lib/html/client/preact.js

@@ -0,0 +1,34 @@
+/**
+ * Preact + htm ESM runtime — single dependency surface.
+ *
+ * All esm.sh version pins live here. Every other client module imports
+ * from this file so version bumps happen in one place.
+ *
+ * Pinned versions (current stable as of 2026-05):
+ *   preact  10.24.3
+ *   htm      3.1.1
+ */
+
+import { h, render, Fragment } from 'https://esm.sh/preact@10.24.3';
+import {
+  useState,
+  useEffect,
+  useRef,
+  useMemo,
+  useCallback,
+  useReducer,
+} from 'https://esm.sh/preact@10.24.3/hooks';
+import htmLib from 'https://esm.sh/htm@3.1.1';
+
+// htm bound to Preact's h — use as a tagged template literal: html`<div>...</div>`
+export const html = htmLib.bind(h);
+
+export { h, render, Fragment };
+export {
+  useState,
+  useEffect,
+  useRef,
+  useMemo,
+  useCallback,
+  useReducer,
+};

package/server/lib/html/client/store.js

@@ -0,0 +1,91 @@
+/**
+ * Reactive store — shared state for the Preact dashboard client.
+ *
+ * Seeds from window.__S__ (injected by client.js before app.js loads).
+ * Expose: getState(), setState(patch), subscribe(fn), useStore() hook.
+ *
+ * This is intentionally NOT a framework — no Redux, no Zustand.
+ * Just a plain mutable object, a subscriber set, and a Preact hook.
+ */
+
+import { useState, useEffect } from './preact.js';
+
+// ---- Initial state seed from server-injected data ----
+const _seed = (typeof window !== 'undefined' && window.__S__) || {};
+
+let _state = {
+  // Fields injected by client.js / window.__S__
+  phases:           _seed.phases           || [],
+  milestone:        _seed.milestone        || '',
+  currentPhase:     _seed.currentPhase     || null,
+  currentSprint:    _seed.currentSprint    || null,
+  decisions:        _seed.decisions        || [],
+  blockers:         _seed.blockers         || [],
+  council_sessions: _seed.council_sessions || [],
+  last_session:     _seed.last_session     || null,
+  chains:           _seed.chains           || [],
+  workstreams:      _seed.workstreams      || [],
+  pendingHandoff:   _seed.pendingHandoff   || null,
+  memoryBank:       _seed.memoryBank       || null,
+  // Live orchestrator sessions (populated by startSessionsPoll in orchestrator.js)
+  activeSessions:   [],
+  // File jump bridge: AgentsView sets this to a slug so FilesView opens it.
+  requestedFile:    null,
+  // xterm terminal panel state (driven by orchestrator.js / XtermPanel.js)
+  // { open, storyId, title, minimized, fullscreen }
+  terminal:         null,
+  // Orchestrator side-panel state (driven by orchestrator.js / OrchPanel.js)
+  // { open, storyId }
+  orchPanel:        null,
+};
+
+/** Registered subscriber functions. */
+const _subscribers = new Set();
+
+/** Return a shallow copy of the current state. */
+export function getState() {
+  return { ..._state };
+}
+
+/**
+ * Shallow-merge `patch` into state, then notify all subscribers.
+ * Only notifies if at least one key actually changed value.
+ */
+export function setState(patch) {
+  let changed = false;
+  for (const key of Object.keys(patch)) {
+    if (_state[key] !== patch[key]) {
+      changed = true;
+      break;
+    }
+  }
+  if (!changed) return;
+  _state = { ..._state, ...patch };
+  for (const fn of _subscribers) {
+    try { fn(_state); } catch (e) { console.error('[store] subscriber error', e); }
+  }
+}
+
+/**
+ * Subscribe to state changes. Returns an unsubscribe function.
+ * @param {function} fn — called with the new state on every setState().
+ */
+export function subscribe(fn) {
+  _subscribers.add(fn);
+  return () => _subscribers.delete(fn);
+}
+
+/**
+ * Preact hook. Subscribes the calling component to the store and
+ * returns the current state. The component re-renders on every setState().
+ */
+export function useStore() {
+  const [state, setLocalState] = useState(getState);
+  useEffect(() => {
+    // Resync on mount in case setState was called before mount.
+    setLocalState(getState());
+    const unsub = subscribe(newState => setLocalState({ ...newState }));
+    return unsub;
+  }, []);
+  return state;
+}

package/server/lib/html/client/util.js

@@ -0,0 +1,186 @@
+/**
+ * Shared pure helpers — ported from client-render.js.
+ *
+ * All functions are stateless: no module-global phase state (_phases).
+ * `allSprints` and `allTasks` take `phases` as an explicit argument.
+ *
+ * Import here; do NOT duplicate in component files.
+ */
+
+/** HTML-escape a value for safe rendering. */
+export function esc(s) {
+  return String(s || '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/** Percentage string. Returns '—' if total is 0. */
+export function pct(done, total) {
+  return total > 0 ? Math.round(done / total * 100) + '%' : '—';
+}
+
+/** Percentage as a number (0–100). Returns 0 if total is 0. */
+export function pctNum(done, total) {
+  return total > 0 ? Math.round(done / total * 100) : 0;
+}
+
+/** Slice an ISO date string to YYYY-MM-DD, or null. */
+export function dateStr(s) {
+  return s ? String(s).slice(0, 10) : null;
+}
+
+/** Human-readable date string, e.g. "May 16, 2026". */
+export function humanDate(s) {
+  if (!s) return null;
+  try {
+    const d = new Date(s);
+    return d.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' });
+  } catch {
+    return dateStr(s);
+  }
+}
+
+/**
+ * Flatten all sprints across phases.
+ * @param {Array} phases — the phases array from the store.
+ * @returns {Array} sprints with phaseId and phaseName injected.
+ */
+export function allSprints(phases) {
+  return (phases || []).flatMap(p =>
+    (p.sprints || []).map(s => Object.assign({}, s, { phaseId: p.id, phaseName: p.name }))
+  );
+}
+
+/**
+ * Flatten all tasks (stories) across phases and sprints.
+ * @param {Array} phases — the phases array from the store.
+ * @returns {Array} tasks with sprintId, phaseId, and phaseName injected.
+ */
+export function allTasks(phases) {
+  return (phases || []).flatMap(p =>
+    (p.sprints || []).flatMap(s =>
+      (s.stories || []).map(t => Object.assign({}, t, { sprintId: s.id, phaseId: p.id, phaseName: p.name }))
+    )
+  );
+}
+
+/**
+ * Return a status chip descriptor — NOT an HTML string.
+ * Components decide how to render the CSS class and label.
+ *
+ * @param {string} status
+ * @returns {{ cls: string, label: string }}
+ */
+export function chip(status) {
+  const s = String(status || '').toLowerCase();
+  const cls =
+    (s === 'complete' || s === 'completed' || s === 'done') ? 'complete' :
+    (s === 'active'   || s === 'in_progress')               ? 'active'   :
+    s === 'blocked'   ? 'blocked' :
+    s === 'planned'   ? 'planned' :
+    s === 'todo'      ? 'todo'    : 'other';
+  return { cls, label: status };
+}
+
+/**
+ * Human-readable elapsed time since an ISO timestamp.
+ * Ported from _orchElapsed() in client-main.js.
+ *
+ * @param {string|null} iso — ISO 8601 start time
+ * @returns {string}
+ */
+export function orchElapsed(iso) {
+  if (!iso) return '—';
+  let s = Math.floor((Date.now() - new Date(iso).getTime()) / 1000);
+  if (s < 0) s = 0;
+  if (s < 60) return s + 's';
+  const m = Math.floor(s / 60);
+  if (m < 60) return m + 'm ' + (s % 60) + 's';
+  return Math.floor(m / 60) + 'h ' + (m % 60) + 'm';
+}
+
+/**
+ * Return command-hint pairs [cmd, desc] for a sprint, based on its status.
+ * Ported from sprintHints() in client-render.js.
+ *
+ * @param {object} s — sprint object (id, status, stories, phaseId)
+ * @returns {Array<[string, string]>}
+ */
+export function sprintHints(s) {
+  const stories = Array.isArray(s.stories) ? s.stories : [];
+  const st = s.status || 'planned';
+  const sid = s.id || '';
+  if (st === 'completed' || st === 'complete' || st === 'done') {
+    return [
+      ['/rihal-verify-work',   'Verify UAT for Sprint ' + sid],
+      ['/rihal-audit',         'Audit completed Sprint ' + sid],
+      ['/rihal-session-report','Generate session report'],
+      ['/rihal-code-review',   'Review code from Sprint ' + sid],
+    ];
+  } else if (st === 'active' || st === 'in_progress') {
+    return [
+      ['/rihal-progress',     'Check Sprint ' + sid + ' progress'],
+      ['/rihal-sprint-status','Status report for Sprint ' + sid],
+      ['/rihal-pause-work',   'Pause and save context'],
+    ];
+  } else if (st === 'blocked') {
+    return [
+      ['/rihal-debug',         'Debug blocker in Sprint ' + sid],
+      ['/rihal-correct-course','Course-correct Sprint ' + sid],
+    ];
+  } else {
+    if (!stories.length) {
+      return [
+        ['/rihal-sprint-planning','Groom Sprint ' + sid + ' — add stories'],
+        ['/rihal-create-story',   'Create a story for Sprint ' + sid],
+        ['/rihal-discuss-phase',  'Discuss approach before planning'],
+      ];
+    }
+    return [
+      ['/rihal-execute-sprint ' + sid, 'Execute Sprint ' + sid],
+      ['/rihal-discuss-phase',  'Discuss before executing'],
+      ['/rihal-sprint-planning','Refine Sprint ' + sid + ' plan'],
+    ];
+  }
+}
+
+/**
+ * Return command-hint pairs [cmd, desc] for a phase, based on its status.
+ * Ported from phaseHints() in client-render.js.
+ *
+ * @param {object} p — phase object (id, status, sprints)
+ * @returns {Array<[string, string]>}
+ */
+export function phaseHints(p) {
+  const sps = Array.isArray(p.sprints) ? p.sprints : [];
+  const st = p.status || 'planned';
+  const pid = p.id || '';
+  if (st === 'completed' || st === 'complete' || st === 'done') {
+    return [
+      ['/rihal-validate-phase','Validate Phase ' + pid + ' deliverables'],
+      ['/rihal-audit',        'Audit Phase ' + pid + ' completion'],
+      ['/rihal-code-review',  'Review Phase ' + pid + ' code'],
+    ];
+  } else if (st === 'active' || st === 'in_progress') {
+    return [
+      ['/rihal-progress',     'Check Phase ' + pid + ' progress'],
+      ['/rihal-sprint-status','Current sprint status'],
+      ['/rihal-code-review',  'Review code in Phase ' + pid],
+    ];
+  } else {
+    if (!sps.length) {
+      return [
+        ['/rihal-plan',         'Create sprint plan for Phase ' + pid],
+        ['/rihal-discuss-phase','Discuss Phase ' + pid + ' approach'],
+        ['/rihal-research-phase','Research Phase ' + pid + ' before planning'],
+      ];
+    }
+    return [
+      ['/rihal-execute ' + pid, 'Start executing Phase ' + pid],
+      ['/rihal-sprint-planning','Plan next sprint in Phase ' + pid],
+    ];
+  }
+}

package/server/lib/html/client/views/AgentsView.js

@@ -0,0 +1,83 @@
+/**
+ * AgentsView — Preact port of the #view-agents markup from shell.js.
+ *
+ * Renders Team (real agents) and AI Agents groups from the AGENTS roster
+ * that was moved client-side into agents-data.js.
+ *
+ * Clicking an agent sets store.requestedFile = skillSlug and navigates to
+ * the Files view, replacing the legacy viewAgentSkill() setTimeout+DOM-poll
+ * hack in shell.js. FilesView watches requestedFile and pre-fills the filter.
+ */
+
+import { html, useState } from '../preact.js';
+import { setState } from '../store.js';
+import { AGENTS } from '../agents-data.js';
+
+const REAL_AGENTS = AGENTS.filter(a => a.real);
+const AI_AGENTS   = AGENTS.filter(a => !a.real);
+
+// ---- Single agent card ----
+function AgentCard({ agent }) {
+  const skillSlug = agent.name.split(' ')[0].toLowerCase();
+
+  function handleClick() {
+    // Navigate to Files view and pre-fill search with the agent's skill slug.
+    // FilesView watches requestedFile in the store and responds via useEffect.
+    setState({ requestedFile: skillSlug });
+    window.location.hash = 'files';
+  }
+
+  return html`
+    <div
+      class="agent-card"
+      onClick=${handleClick}
+      style="cursor:pointer;"
+    >
+      <div class="name">
+        ${agent.name}
+        ${agent.real ? html` <span class="real-badge">real</span>` : null}
+        ${' '}<span class="type-badge">${agent.type}</span>
+      </div>
+      <div class="arabic">${agent.arabic}</div>
+      <div class="role">${agent.role}</div>
+    </div>
+  `;
+}
+
+// ---- Agent group ----
+function AgentGroup({ label, agents, filter }) {
+  const visible = agents.filter(a => {
+    if (!filter) return true;
+    const q = filter.toLowerCase();
+    return (a.name + ' ' + a.role + ' ' + a.arabic + ' ' + a.type).toLowerCase().includes(q);
+  });
+  if (!visible.length) return null;
+  return html`
+    <div class="memory-group-header">${label} (${visible.length})</div>
+    <div class="agent-list">
+      ${visible.map(a => html`<${AgentCard} key=${a.name} agent=${a} />`)}
+    </div>
+  `;
+}
+
+// ---- Root AgentsView ----
+export function AgentsView() {
+  const [filter, setFilter] = useState('');
+
+  return html`
+    <div class="view active" id="view-agents">
+      <div class="view-title">Team</div>
+      <div class="filter-bar">
+        <input
+          class="filter-input"
+          type="text"
+          placeholder="Filter agents…"
+          value=${filter}
+          onInput=${e => setFilter(e.target.value)}
+        />
+      </div>
+      <${AgentGroup} label="Team" agents=${REAL_AGENTS} filter=${filter} />
+      <${AgentGroup} label="AI Agents" agents=${AI_AGENTS} filter=${filter} />
+    </div>
+  `;
+}