@rubytech/create-maxy-lite 0.1.0

package/payload/validator/validate.mjs

@@ -0,0 +1,166 @@
+// The validation engine. Two passes over a vault, no LLM in the decision path:
+//   1. parse every markdown file's frontmatter and index basename -> entity type(s)
+//   2. check each file's fields and associations against the schema
+//
+// Every violation is named `<field>:<rule>` (or `type:unknown` / `type:missing`)
+// so a failure is diagnosable from the report alone.
+
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { parseFrontmatter } from './frontmatter.mjs';
+
+// A `date` is a real calendar date: `YYYY-MM-DD`, optionally with a time. js-yaml
+// coerces a bare ISO date to a Date object; a quoted date stays a string, so we
+// validate the string form by components (shape alone would pass 2026-13-40).
+function isValidDateString(value) {
+  const m = value.match(/^(\d{4})-(\d{2})-(\d{2})([T ].*)?$/);
+  if (!m) return false;
+  const y = Number(m[1]);
+  const mo = Number(m[2]);
+  const d = Number(m[3]);
+  if (mo < 1 || mo > 12 || d < 1 || d > 31) return false;
+  const dt = new Date(Date.UTC(y, mo - 1, d));
+  return dt.getUTCFullYear() === y && dt.getUTCMonth() === mo - 1 && dt.getUTCDate() === d;
+}
+
+/** List every `.md` file under a vault, as paths relative to the vault root. */
+export function collectMarkdownFiles(vaultPath) {
+  return readdirSync(vaultPath, { recursive: true })
+    .map((p) => String(p))
+    .filter((p) => p.toLowerCase().endsWith('.md'))
+    .sort();
+}
+
+/** Reduce a link value to the bare basename it points at, or null if it is not a string. */
+export function normalizeLink(value) {
+  if (typeof value !== 'string') return null;
+  let s = value.trim();
+  const wiki = s.match(/^\[\[(.+?)\]\]$/);
+  if (wiki) s = wiki[1].split('|')[0].trim(); // [[Name|alias]] -> Name (alias only meaningful in brackets)
+  s = s.replace(/\.md$/i, '');                // Name.md -> Name
+  s = s.split('/').pop();                     // folder/Name -> Name
+  return s || null;
+}
+
+function matchesScalar(type, value) {
+  switch (type) {
+    case 'text': return typeof value === 'string';
+    case 'number': return typeof value === 'number' && Number.isFinite(value);
+    case 'checkbox': return typeof value === 'boolean';
+    case 'date': return value instanceof Date || (typeof value === 'string' && isValidDateString(value));
+    default: return false;
+  }
+}
+
+/**
+ * Validate one file's parsed frontmatter against the schema.
+ *
+ * @returns {{ entity: string, errors: string[] }}
+ */
+export function validateFile(frontmatter, schema, index) {
+  const type = frontmatter.type;
+  if (type === undefined || type === null || type === '') {
+    return { entity: 'none', errors: ['type:missing'] };
+  }
+  const entity = schema.entities.get(type);
+  if (!entity) {
+    return { entity: String(type), errors: ['type:unknown'] };
+  }
+
+  const errors = [];
+
+  for (const [field, spec] of entity.fields) {
+    const raw = frontmatter[field];
+    // Present means a real value. `false` and `0` count; null, undefined, and an
+    // empty/whitespace-only string do not (a required field left blank is missing).
+    const present = Object.prototype.hasOwnProperty.call(frontmatter, field)
+      && raw !== undefined && raw !== null
+      && !(typeof raw === 'string' && raw.trim() === '');
+    if (!present) {
+      if (spec.required) errors.push(`${field}:missing`);
+      continue;
+    }
+    const value = frontmatter[field];
+    const assoc = schema.associations.get(field);
+
+    if (spec.type === 'list') {
+      if (!Array.isArray(value)) { errors.push(`${field}:type`); continue; }
+      if (assoc) checkLinks(field, value, assoc, index, errors);
+      continue;
+    }
+    if (spec.type === 'link') {
+      checkLinks(field, [value], assoc, index, errors);
+      continue;
+    }
+    if (spec.type === 'area') {
+      if (typeof value !== 'string') errors.push(`${field}:type`);
+      else if (!schema.areas.has(value)) errors.push(`${field}:area`);
+      continue;
+    }
+    if (!matchesScalar(spec.type, value)) errors.push(`${field}:type`);
+  }
+
+  return { entity: type, errors };
+}
+
+/** Resolve each link item and append dangling/target/type violations for `field`. */
+function checkLinks(field, items, assoc, index, errors) {
+  let dangling = false;
+  let wrongTarget = false;
+  let malformed = false;
+  for (const item of items) {
+    const name = normalizeLink(item);
+    if (name === null) { malformed = true; continue; }
+    const targetTypes = index.get(name);
+    if (!targetTypes) { dangling = true; continue; }
+    if (assoc && assoc.targets !== 'any') {
+      const ok = [...targetTypes].some((t) => assoc.targets.includes(t));
+      if (!ok) wrongTarget = true;
+    }
+  }
+  if (malformed) errors.push(`${field}:type`);
+  if (dangling) errors.push(`${field}:dangling`);
+  if (wrongTarget) errors.push(`${field}:target`);
+}
+
+/**
+ * Validate a whole vault.
+ *
+ * @param {string} vaultPath
+ * @param {ReturnType<import('./schema.mjs').loadSchema>} schema
+ * @returns {{ results: Array<{file:string,entity:string,ok:boolean,errors:string[]}>,
+ *            summary: {files:number,valid:number,invalid:number} }}
+ */
+export function validateVault(vaultPath, schema) {
+  const relPaths = collectMarkdownFiles(vaultPath);
+
+  // Pass 1: parse frontmatter and index basename -> set of entity types.
+  const parsed = [];
+  const index = new Map();
+  for (const rel of relPaths) {
+    const text = readFileSync(join(vaultPath, rel), 'utf8');
+    const { frontmatter } = parseFrontmatter(text);
+    parsed.push({ rel, frontmatter });
+    const type = frontmatter.type;
+    if (typeof type === 'string' && type) {
+      const key = basename(rel).replace(/\.md$/i, '');
+      if (!index.has(key)) index.set(key, new Set());
+      index.get(key).add(type);
+    }
+  }
+
+  // Pass 2: validate each file.
+  const results = [];
+  let valid = 0;
+  for (const { rel, frontmatter } of parsed) {
+    const { entity, errors } = validateFile(frontmatter, schema, index);
+    const ok = errors.length === 0;
+    if (ok) valid += 1;
+    results.push({ file: rel, entity, ok, errors });
+  }
+
+  return {
+    results,
+    summary: { files: parsed.length, valid, invalid: parsed.length - valid },
+  };
+}

package/payload/webchat/README.md

@@ -0,0 +1,55 @@
+# maxy-lite web chat relay
+
+A localhost relay that turns the raw `claude` TUI into a structured chat surface
+on the phone browser. It spawns `claude` in a node-pty (the message you type in
+the browser is written into the pty), and renders replies by **tailing the
+session JSONL** — not by scraping terminal bytes. Rows stream to the browser as
+user / assistant / tool bubbles over a WebSocket.
+
+This is the "structured web chat" tier above the `ttyd` raw terminal in
+[`maxy-lite-install.md`](../../../.docs/maxy-lite-install.md). It runs inside the
+proot-distro Ubuntu layer; it is localhost-only (no off-device exposure).
+
+## Run (inside proot Ubuntu)
+
+```sh
+cd ~/.maxy/packages/maxy-lite/webchat   # wherever the package landed
+npm install                             # builds node-pty (needs python3 make g++)
+LITE_AGENT_HOME=~/maxy npm start        # serves on http://localhost:7682
+```
+
+Open **http://localhost:7682** in the phone browser. Type a message; the reply
+renders as bubbles. A reload replays the current transcript.
+
+## Environment
+
+| Var | Default | Meaning |
+|---|---|---|
+| `LITE_PORT` | `7682` | HTTP + WebSocket port (localhost). |
+| `LITE_AGENT_HOME` | `process.cwd()` | claude's working dir = the markdown store root. |
+| `LITE_CLAUDE_BIN` | `claude` | The binary spawned in the pty. |
+| `LITE_STATE_DIR` | `<home>/.maxy-lite` | Where the active session id is persisted for resume. |
+
+The relay persists the session id under `LITE_STATE_DIR`; on restart it resumes
+that session (`claude --resume`) so the transcript survives a relay bounce.
+Delete `session-id` there to start a fresh conversation.
+
+## Observability
+
+Every per-turn step emits one `[lite-chat]` line to stderr, correlated by
+`turn=<n>`. Capture stderr to a file and reconstruct one turn:
+
+```sh
+LITE_AGENT_HOME=~/maxy npm start 2> relay.log
+grep '\[lite-chat\]' relay.log | grep 'turn=3'
+```
+
+A healthy turn shows the full lifeline: `inbound -> spawn (pty=true) -> jsonl
+(newBytes>0) -> render (msgs>0) -> done`. Failure signals: `spawn pty=false`,
+`jsonl newBytes=0` on a replying turn, `render msgs=0`, repeated `parse-skip`.
+
+## Boundaries
+
+The filesystem browser over the markdown store is delegated to **Obsidian** on
+the shared vault — it is not part of this relay. Multi-session UI, auth, theming,
+and off-device exposure are out of scope.

package/payload/webchat/package-lock.json

@@ -0,0 +1,56 @@
+{
+  "name": "@rubytech/maxy-lite-webchat",
+  "version": "0.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@rubytech/maxy-lite-webchat",
+      "version": "0.0.0",
+      "dependencies": {
+        "node-pty": "^1.0.0",
+        "ws": "^8.18.0"
+      },
+      "bin": {
+        "maxy-lite-webchat": "server.mjs"
+      }
+    },
+    "node_modules/node-addon-api": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz",
+      "integrity": "sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==",
+      "license": "MIT"
+    },
+    "node_modules/node-pty": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/node-pty/-/node-pty-1.1.0.tgz",
+      "integrity": "sha512-20JqtutY6JPXTUnL0ij1uad7Qe1baT46lyolh2sSENDd4sTzKZ4nmAFkeAARDKwmlLjPx6XKRlwRUxwjOy+lUg==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "dependencies": {
+        "node-addon-api": "^7.1.0"
+      }
+    },
+    "node_modules/ws": {
+      "version": "8.21.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz",
+      "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    }
+  }
+}

package/payload/webchat/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@rubytech/maxy-lite-webchat",
+  "version": "0.0.0",
+  "private": true,
+  "description": "maxy-lite structured web chat relay: drives claude via node-pty, renders the session JSONL as chat bubbles in the phone browser (on-device, localhost).",
+  "type": "module",
+  "bin": {
+    "maxy-lite-webchat": "server.mjs"
+  },
+  "scripts": {
+    "start": "node server.mjs"
+  },
+  "dependencies": {
+    "node-pty": "^1.0.0",
+    "ws": "^8.18.0"
+  }
+}

package/payload/webchat/parse-transcript.mjs

@@ -0,0 +1,128 @@
+// Pure JSONL-line -> render-message classifier for the maxy-lite web chat relay.
+// The session JSONL (~/.claude/projects/.../<id>.jsonl) is the canonical claude
+// transcript; this module turns its rows into the three structured message kinds
+// the lite UI renders: user (typed), assistant (prose), tool (a call or a result).
+//
+// A stripped sibling of the maxy-code /chat parser (platform/ui/app/lib/
+// whatsapp-reader/parse-transcript.ts). The Pi-only apparatus that file carries
+// — channel <channel> wrappers, queue-operation enqueue/twin dedup, composed
+// admin frames, upload notes, api-error banners — is OUT of scope for maxy-lite:
+// the relay drives one local interactive session, so only the plain row shapes
+// remain. No fs, no transport — unit-testable in isolation.
+
+/**
+ * @typedef {{kind:'user', text:string, ts:string|null}} UserMessage
+ * @typedef {{kind:'assistant', text:string, ts:string|null}} AssistantMessage
+ * @typedef {{kind:'tool', phase:'call', name:string, input:unknown, ts:string|null}} ToolCallMessage
+ * @typedef {{kind:'tool', phase:'result', text:string, isError:boolean, ts:string|null}} ToolResultMessage
+ * @typedef {UserMessage|AssistantMessage|ToolCallMessage|ToolResultMessage} Message
+ */
+
+// CLI-synthesised user rows (slash commands, /clear, /resume) wrap their payload
+// in these openers — never a real operator message, so they are dropped.
+const CLI_MARKER_PREFIXES = ['<local-command-', '<command-name>', '<command-message>']
+
+function tsOf(row) {
+  return typeof row.timestamp === 'string' ? row.timestamp : null
+}
+
+function asString(content) {
+  return typeof content === 'string' ? content : null
+}
+
+// Recover a tool_result's text whether `content` is a plain string or the
+// array-of-blocks shape claude also emits.
+function toolResultText(content) {
+  if (typeof content === 'string') return content
+  if (Array.isArray(content)) {
+    return content
+      .map((c) => (c && typeof c === 'object' && typeof c.text === 'string' ? c.text : ''))
+      .join('')
+  }
+  return ''
+}
+
+/** Classify one assistant turn's content blocks into render messages. */
+function assistantMessages(content, ts) {
+  if (!Array.isArray(content)) return []
+  const out = []
+  for (const block of content) {
+    if (!block || typeof block !== 'object') continue
+    if (block.type === 'text' && typeof block.text === 'string') {
+      out.push({ kind: 'assistant', text: block.text, ts })
+    } else if (block.type === 'tool_use' && typeof block.name === 'string') {
+      out.push({ kind: 'tool', phase: 'call', name: block.name, input: block.input ?? null, ts })
+    }
+  }
+  return out
+}
+
+/** Classify a user turn whose content array carries tool_result blocks. */
+function toolResultMessages(content, ts) {
+  if (!Array.isArray(content)) return []
+  const out = []
+  for (const block of content) {
+    if (!block || typeof block !== 'object' || block.type !== 'tool_result') continue
+    out.push({
+      kind: 'tool',
+      phase: 'result',
+      text: toolResultText(block.content),
+      isError: block.is_error === true,
+      ts,
+    })
+  }
+  return out
+}
+
+/**
+ * Parse a list of JSONL lines into an ordered render-message list.
+ *
+ * @param {string[]} lines
+ * @param {{onSkip?: (lineIndex:number, reason:string) => void}} [opts]
+ *   `onSkip` fires once per line that could not be parsed as a JSON object
+ *   (the relay maps it to `op=parse-skip`). A blank line and a recognised but
+ *   non-renderable row (e.g. `type:"system"`) are skipped silently — they are
+ *   not parse failures. A malformed line never throws.
+ * @returns {Message[]}
+ */
+export function parseTranscript(lines, opts = {}) {
+  const onSkip = typeof opts.onSkip === 'function' ? opts.onSkip : null
+  const out = []
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (!line || line.trim() === '') continue
+    let row
+    try {
+      const parsed = JSON.parse(line)
+      if (!parsed || typeof parsed !== 'object') {
+        if (onSkip) onSkip(i, 'not-object')
+        continue
+      }
+      row = parsed
+    } catch {
+      if (onSkip) onSkip(i, 'json-parse')
+      continue
+    }
+
+    const ts = tsOf(row)
+    const msg = row.message
+
+    if (row.type === 'assistant') {
+      out.push(...assistantMessages(msg?.content, ts))
+      continue
+    }
+
+    if (row.type !== 'user' || !msg) continue // system/summary/other: nothing renderable
+
+    if (Array.isArray(msg.content)) {
+      out.push(...toolResultMessages(msg.content, ts))
+      continue
+    }
+
+    const text = asString(msg.content)
+    if (text === null) continue
+    if (CLI_MARKER_PREFIXES.some((p) => text.startsWith(p))) continue
+    out.push({ kind: 'user', text, ts })
+  }
+  return out
+}

package/payload/webchat/public/app.js

@@ -0,0 +1,106 @@
+// maxy-lite web chat — minimal client. Opens a WebSocket to the relay, renders
+// snapshot + appended messages as bubbles, and sends the composer text. A reload
+// replays the transcript from the snapshot the server sends on connect.
+
+const messagesEl = document.getElementById('messages')
+const statusEl = document.getElementById('status')
+const form = document.getElementById('composer')
+const input = document.getElementById('input')
+const toolIconTpl = document.getElementById('tpl-tool-icon')
+
+function atBottom() {
+  return messagesEl.scrollHeight - messagesEl.scrollTop - messagesEl.clientHeight < 80
+}
+
+function scrollDown() {
+  messagesEl.scrollTop = messagesEl.scrollHeight
+}
+
+function renderMessage(m) {
+  const el = document.createElement('div')
+  if (m.kind === 'user') {
+    el.className = 'msg user'
+    el.textContent = m.text
+  } else if (m.kind === 'assistant') {
+    el.className = 'msg assistant'
+    el.textContent = m.text
+  } else if (m.kind === 'tool') {
+    el.className = 'msg tool' + (m.isError ? ' error' : '')
+    const head = document.createElement('div')
+    head.className = 'tool-head'
+    head.appendChild(toolIconTpl.content.cloneNode(true))
+    const label = document.createElement('span')
+    label.textContent = m.phase === 'call' ? m.name : m.isError ? 'tool error' : 'tool result'
+    head.appendChild(label)
+    const body = document.createElement('pre')
+    body.className = 'tool-body'
+    body.textContent =
+      m.phase === 'call'
+        ? typeof m.input === 'string'
+          ? m.input
+          : JSON.stringify(m.input ?? null, null, 2)
+        : m.text
+    el.appendChild(head)
+    el.appendChild(body)
+  } else {
+    return
+  }
+  messagesEl.appendChild(el)
+}
+
+function renderAll(list, replace) {
+  if (replace) messagesEl.replaceChildren()
+  const stick = atBottom()
+  for (const m of list) renderMessage(m)
+  if (replace || stick) scrollDown()
+}
+
+let ws
+
+function connect() {
+  ws = new WebSocket(`ws://${location.host}/ws`)
+  ws.onopen = () => {
+    statusEl.textContent = 'connected'
+    statusEl.className = 'on'
+  }
+  ws.onclose = () => {
+    statusEl.textContent = 'reconnecting'
+    statusEl.className = 'off'
+    setTimeout(connect, 1000)
+  }
+  ws.onmessage = (ev) => {
+    let msg
+    try {
+      msg = JSON.parse(ev.data)
+    } catch {
+      return
+    }
+    if (msg.type === 'snapshot') renderAll(msg.messages || [], true)
+    else if (msg.type === 'append') renderAll(msg.messages || [], false)
+  }
+}
+
+connect()
+
+function autosize() {
+  input.style.height = 'auto'
+  input.style.height = Math.min(input.scrollHeight, 140) + 'px'
+}
+input.addEventListener('input', autosize)
+
+form.addEventListener('submit', (e) => {
+  e.preventDefault()
+  const text = input.value.trim()
+  if (!text || !ws || ws.readyState !== 1) return
+  ws.send(JSON.stringify({ type: 'send', text }))
+  input.value = ''
+  autosize()
+  input.focus()
+})
+
+input.addEventListener('keydown', (e) => {
+  if (e.key === 'Enter' && !e.shiftKey) {
+    e.preventDefault()
+    form.requestSubmit()
+  }
+})

package/payload/webchat/public/index.html

@@ -0,0 +1,32 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <title>maxy-lite</title>
+    <link rel="stylesheet" href="/style.css" />
+  </head>
+  <body>
+    <header id="bar">
+      <span id="title">maxy-lite</span>
+      <span id="status" class="off">connecting</span>
+    </header>
+    <main id="messages" aria-live="polite"></main>
+    <form id="composer">
+      <textarea id="input" rows="1" placeholder="Message" autocomplete="off"></textarea>
+      <button id="send" type="submit" aria-label="Send">
+        <svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor"
+          stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M22 2 11 13" /><path d="M22 2 15 22 11 13 2 9 22 2Z" />
+        </svg>
+      </button>
+    </form>
+    <template id="tpl-tool-icon">
+      <svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor"
+        stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M14.7 6.3a4 4 0 0 0-5.4 5.4L3 18v3h3l6.3-6.3a4 4 0 0 0 5.4-5.4l-2.6 2.6-2-2 2.6-2.6Z" />
+      </svg>
+    </template>
+    <script src="/app.js"></script>
+  </body>
+</html>