@rubytech/create-maxy-lite 0.1.4 → 0.1.6

package/payload/skills/url-get/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: url-get
+description: >
+  Fetch a web page faithfully and read its content as markdown. Use when the
+  owner gives a URL and wants the page read, quoted, or summarised, or when you
+  need the verbatim text of an article, doc, or listing. Trigger phrases:
+  "fetch this page", "get the content of", "read this article", "what does this
+  link say", "pull the text from", "open this URL and tell me". For
+  JavaScript-heavy pages that come back empty, fall to the browser skill.
+---
+
+# url-get
+
+Retrieve a web page exactly as the server sent it and read it as markdown. There is no model in the fetch path, so nothing is summarised or inferred on the way in. The script prints the cleaned markdown and writes the full verbatim copy to a scratch file.
+
+## When to use
+
+- The owner gives a URL and wants it read, quoted, fact-checked, or summarised.
+- You need the real text of a page rather than a recollection of it.
+- A research step (see `[[deep-research]]`) needs a source fetched.
+
+Use this for server-rendered HTML, which is most of the web. For a page that runs its content in the browser (a client-rendered app), this returns little or nothing; switch to the `[[browser]]` render script.
+
+## How to run
+
+```bash
+node ~/.maxy-lite/skills/url-get/scripts/url-get.mjs "https://example.com/article"
+```
+
+The cleaned markdown prints to stdout. The full copy is written to `$LITE_SCRATCH/url-get/<hash>.md` (default `~/.maxy-lite/scratch/url-get/`) so a long page does not have to be re-fetched.
+
+## Reading the result
+
+- **Markdown on stdout, exit 0**: the page text. Read it, then answer.
+- **Empty stdout, exit 0**: the page is HTTP 200 but has no extractable text. This is the client-rendered-shell signal. Re-fetch with the `[[browser]]` render script, which runs the page's JavaScript first.
+- **Non-zero exit**: a fetch error printed to stderr as `[url-get] error=<code>`:
+  - `fetch`: network failure or timeout.
+  - `http`: the server returned a non-2xx status.
+  - `non-html`: the URL is a PDF, image, or other non-HTML type this script does not handle.
+  - `challenge`: the response was a bot-challenge interstitial, not content. Try the `[[browser]]` render script, which presents a real browser.
+
+Surface the error to the owner plainly. Do not invent the page contents.
+
+## Boundaries
+
+- Reads one URL per call. For several pages, call it once per URL.
+- Does not run page JavaScript, submit forms, or follow in-page actions. Those are the `[[browser]]` skill.
+- Does not fetch PDFs or images. A PDF link needs a different tool.

package/payload/skills/url-get/scripts/url-get.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// url-get — faithful HTTP page fetch into markdown. No model in the path.
+//
+// Ported from the maxy-code url-get MCP tool to a single lite CLI script.
+// One mechanism: fetch the URL, refuse non-HTML and bot-challenge pages, convert
+// the HTML to markdown verbatim, write the full copy to a scratch reference file,
+// and print the same (capped) markdown to stdout. Nothing is summarised — a
+// caller that needs a summary reads the text and summarises in its own context.
+//
+//   FETCH -> HTTP STATUS -> CONTENT-TYPE -> CHALLENGE -> HTML->MD -> WRITE REF -> PRINT
+//
+// Errors go to stderr as [url-get] error=<code> and exit non-zero. Codes:
+//   fetch     network failure / timeout
+//   http      non-2xx response
+//   non-html  content-type is not HTML or text/plain
+//   challenge response is a bot-challenge interstitial, not content
+import { createHash } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { NodeHtmlMarkdown } from "node-html-markdown";
+
+const FETCH_TIMEOUT_MS = 30_000;
+const TEXT_CAP = 100_000;
+const UA =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
+  "(KHTML, like Gecko) Chrome/124.0 Safari/537.36";
+
+// Strong, low-false-positive markers of a bot-challenge interstitial. These do
+// not occur in legitimate article bodies; a match means the response is a
+// challenge page, not the requested content.
+const CHALLENGE = [
+  "/cdn-cgi/challenge-platform/",
+  "cf-browser-verification",
+  "enable javascript and cookies to continue",
+  "checking your browser before accessing",
+  "attention required! | cloudflare",
+  "<title>just a moment",
+];
+
+const fail = (code, msg) => {
+  console.error(`[url-get] error=${code} detail=${JSON.stringify(msg)}`);
+  process.exit(1);
+};
+
+const url = process.argv[2];
+if (!url) fail("usage", "usage: url-get.mjs <url>");
+
+let res;
+try {
+  res = await fetch(url, {
+    redirect: "follow",
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    headers: { "User-Agent": UA, Accept: "text/html,application/xhtml+xml" },
+  });
+} catch (err) {
+  fail("fetch", err instanceof Error ? err.message : String(err));
+}
+
+if (!res.ok) fail("http", `HTTP ${res.status}`);
+
+const ct = (res.headers.get("content-type") ?? "").toLowerCase();
+if (ct && !ct.includes("html") && !ct.includes("text/plain")) {
+  fail("non-html", `unsupported content-type: ${ct} (url-get handles server-rendered HTML only)`);
+}
+
+const html = await res.text();
+if (CHALLENGE.some((sig) => html.slice(0, 8000).toLowerCase().includes(sig))) {
+  fail("challenge", "page returned a bot-challenge interstitial, not content");
+}
+
+const markdown = NodeHtmlMarkdown.translate(html).trim();
+
+// The full verbatim markdown is the ground truth on disk; stdout is the same
+// content capped so a large page does not flood the caller's context. An empty
+// markdown body (textLength=0) on an HTTP 200 is the JavaScript-rendered-shell
+// signal: retry with the browser render script.
+const scratch = process.env.LITE_SCRATCH || join(homedir(), ".maxy-lite", "scratch");
+const dir = join(scratch, "url-get");
+const hash = createHash("sha256").update(url).digest("hex").slice(0, 32);
+const refPath = join(dir, `${hash}.md`);
+const fetchedAt = new Date().toISOString();
+await mkdir(dir, { recursive: true });
+await writeFile(
+  refPath,
+  `<!-- url-get source=${url} fetchedAt=${fetchedAt} httpStatus=${res.status} -->\n\n${markdown}\n`,
+  "utf-8",
+);
+
+console.error(
+  `[url-get] url=${url} httpStatus=${res.status} textLength=${markdown.length} refPath=${refPath}`,
+);
+process.stdout.write(markdown.slice(0, TEXT_CAP));

package/payload/skills/work/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: work
+description: Capture, find, and update to-dos in the vault. Use when the user asks to remember a task, add a to-do, note something they need to do, mark a task done, change a due date, assign work to someone, or asks what is on their list or what is outstanding. Owns the Task entity of the maxy-lite SCHEMA.
+---
+
+# Work
+
+A to-do is a **Task** file in `activities/`, one task per file. It is YAML frontmatter plus a markdown body for the detail (context, sub-steps, notes). The authoritative field list is [`SCHEMA.md`](../../schema/SCHEMA.md) under *Activities*, the *Task* entity.
+
+## Task (`activities/<Title>.md`)
+
+Required: `type: task` and `title`. Optional: `due` (`YYYY-MM-DD`), `priority`, `status`, `taskType`, `assignee` (a single link to a Person), `about` (a single link to anything the task concerns), `project` (a single link to a Project), `area`. Set only what you know.
+
+```yaml
+---
+type: task
+title: Call the surveyor
+due: 2026-07-01
+status: not started
+priority: high
+assignee: "[[Jane Doe]]"
+project: "[[House Move]]"
+area: home
+---
+Surveyor quoted last spring. Ask about the loft conversion before booking.
+```
+
+`status` and `priority` are free text the assistant keeps consistent (e.g. `not started` / `in progress` / `done`); `area` must be one of the controlled areas in the SCHEMA. The links resolve to files that must already exist: `assignee` to a Person in `people/`, `project` to a Project in `projects/`, `about` to any entity. Create the target file first if it is not in the vault yet.
+
+## Finding what is outstanding
+
+Grep the frontmatter rather than recalling from memory:
+
+- open tasks: `grep -rL "status: done" activities/ | xargs grep -l "type: task"`
+- tasks for one project: `grep -rl "\[\[House Move\]\]" activities/`
+- tasks assigned to someone: `grep -rl "assignee:.*Jane Doe" activities/`
+- due dates: `grep -rh "^due:" activities/`
+
+Read the matched files for the detail. To mark a task done, edit its `status` field; do not delete the file.
+
+## After every write, validate
+
+After creating or editing any task file, run the deterministic validator over the vault:
+
+```sh
+maxy-lite-validate "$HOME/maxy"
+```
+
+It exits 0 only when every file conforms. If a line names the task you just wrote with `ok=false`, the bracketed error names the violation: `title:missing` (the required title is absent), `area:area` (an area outside the controlled vocabulary), `due:type` (a malformed date), `assignee:dangling` or `project:dangling` (the linked file does not exist), `assignee:target` (the link points at a file of the wrong type). Fix the named field and re-run until that file is `ok=true`. Never leave a task you wrote in a failing state.

package/payload/webchat/inject-line.mjs

@@ -0,0 +1,11 @@
+// Turn a message into the byte sequence written into the claude pty.
+//
+// The TUI submits on a carriage return, so an embedded newline would submit
+// early and truncate the message. Collapse every newline run to a single space,
+// then append the one trailing CR that submits the whole line. Shared by the
+// browser send path and the channel `/inject` path so both are protected.
+
+/** @param {string} text @returns {string} */
+export function ptyLine(text) {
+  return text.replace(/[\r\n]+/g, ' ') + '\r'
+}

package/payload/webchat/package.json

@@ -8,7 +8,8 @@
     "maxy-lite-webchat": "server.mjs"
   },
   "scripts": {
-    "start": "node server.mjs"
+    "start": "node server.mjs",
+    "test": "node --test"
   },
   "dependencies": {
     "node-pty": "^1.0.0",

package/payload/webchat/request-handler.mjs

@@ -0,0 +1,62 @@
+// HTTP request router for the webchat relay.
+//
+// Two surfaces:
+//   - GET /, /app.js, /style.css → static files from the public dir.
+//   - POST /inject {text}         → deliver an inbound message to the agent.
+//
+// The `/inject` route is how the on-device channel servers (Telegram, WhatsApp)
+// reach the one shared agent: they POST a context-tagged line here and it is
+// written into the same pty a browser send uses. `onInject` is injected so the
+// router stays testable without a live pty.
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+const CONTENT_TYPES = { '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css' }
+const STATIC = { '/': 'index.html', '/app.js': 'app.js', '/style.css': 'style.css' }
+
+/**
+ * @param {{ publicDir: string, onInject: (text: string) => void }} deps
+ * @returns {(req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => void}
+ */
+export function makeRequestHandler({ publicDir, onInject }) {
+  return (req, res) => {
+    if (req.method === 'POST' && req.url === '/inject') {
+      let body = ''
+      req.on('data', (c) => (body += c))
+      req.on('end', () => {
+        let text
+        try {
+          text = JSON.parse(body).text
+        } catch {
+          text = undefined
+        }
+        if (typeof text !== 'string' || text === '') {
+          res.writeHead(400, { 'content-type': 'application/json' })
+          res.end('{"ok":false,"error":"text required"}')
+          return
+        }
+        onInject(text)
+        res.writeHead(200, { 'content-type': 'application/json' })
+        res.end('{"ok":true}')
+      })
+      return
+    }
+
+    const file = STATIC[req.url]
+    if (!file) {
+      res.writeHead(404)
+      res.end('not found')
+      return
+    }
+    fs.readFile(path.join(publicDir, file), (err, data) => {
+      if (err) {
+        res.writeHead(404)
+        res.end('not found')
+        return
+      }
+      res.writeHead(200, { 'content-type': CONTENT_TYPES[path.extname(file)] || 'text/plain' })
+      res.end(data)
+    })
+  }
+}

package/payload/webchat/server.mjs

@@ -22,6 +22,8 @@ import { fileURLToPath } from 'node:url'
 import pty from 'node-pty'
 import { WebSocketServer } from 'ws'
 import { parseTranscript } from './parse-transcript.mjs'
+import { ptyLine } from './inject-line.mjs'
+import { makeRequestHandler } from './request-handler.mjs'
 
 const HERE = path.dirname(fileURLToPath(import.meta.url))
 const PUBLIC_DIR = path.join(HERE, 'public')
@@ -166,28 +168,34 @@ setInterval(() => {
   }
 }, 500)
 
-// ---- transport: HTTP static + WebSocket -------------------------------------
+// ---- deliver a message to the agent -----------------------------------------
+
+// Start a turn and write the message into the pty. The single source of truth
+// for both the browser send path and the channel `/inject` path, so a channel
+// inbound is delivered byte-for-byte the same way a browser message is. An
+// embedded newline is collapsed by ptyLine so the TUI is not submitted early.
+function submitToAgent(text) {
+  turn += 1
+  turnActive = true
+  turnSawGrowth = false
+  turnStart = Date.now()
+  lastActivity = Date.now()
+  log('inbound', { turn, chars: text.length })
+  child.write(ptyLine(text))
+  log('spawn', { turn, pty: true, pid: child.pid })
+}
 
-const CONTENT_TYPES = { '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css' }
-const STATIC = { '/': 'index.html', '/app.js': 'app.js', '/style.css': 'style.css' }
+// ---- transport: HTTP static + /inject + WebSocket ---------------------------
 
-const server = http.createServer((req, res) => {
-  const file = STATIC[req.url]
-  if (!file) {
-    res.writeHead(404)
-    res.end('not found')
-    return
-  }
-  fs.readFile(path.join(PUBLIC_DIR, file), (err, data) => {
-    if (err) {
-      res.writeHead(404)
-      res.end('not found')
-      return
-    }
-    res.writeHead(200, { 'content-type': CONTENT_TYPES[path.extname(file)] || 'text/plain' })
-    res.end(data)
-  })
-})
+const server = http.createServer(
+  makeRequestHandler({
+    publicDir: PUBLIC_DIR,
+    onInject: (text) => {
+      log('inject', { chars: text.length })
+      submitToAgent(text)
+    },
+  }),
+)
 
 const wss = new WebSocketServer({ server, path: '/ws' })
 
@@ -209,18 +217,10 @@ wss.on('connection', (ws) => {
       return
     }
     if (m.type !== 'send' || typeof m.text !== 'string' || m.text === '') return
-    turn += 1
-    turnActive = true
-    turnSawGrowth = false
-    turnStart = Date.now()
-    lastActivity = Date.now()
-    log('inbound', { turn, chars: m.text.length })
     // Deliver to claude by writing into the pty, then submit with a carriage
-    // return. This is the TUI typing model — the same input path ttyd uses. An
-    // embedded newline would submit the TUI early and truncate the message, so
-    // collapse any newline to a space: v0 chat is single-line per send.
-    child.write(m.text.replace(/[\r\n]+/g, ' ') + '\r')
-    log('spawn', { turn, pty: true, pid: child.pid })
+    // return. This is the TUI typing model — the same input path ttyd uses, and
+    // the same path the channel `/inject` route uses via submitToAgent.
+    submitToAgent(m.text)
   })
 })