@rubytech/create-maxy-lite 0.1.5 → 0.1.6

package/payload/skills/replicate/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: replicate
+description: >
+  Generate an image from a text prompt. Use when the owner wants a picture,
+  logo, illustration, diagram, icon, or any visual created from a description.
+  Trigger phrases: "generate an image", "make a picture of", "create a logo",
+  "draw me", "design an illustration", "I need a graphic of". Produces a real
+  image file in the vault.
+---
+
+# replicate
+
+Turn a text prompt into an image using the Replicate API. The script picks the model, calls the API, downloads the result into the vault, and prints the file path.
+
+## When to use
+
+The owner wants an image made from a description: a logo, an illustration, a concept sketch, a photoreal scene, a diagram, an icon. This produces an actual file, not a description of one.
+
+## Models
+
+Pick the model to match the job:
+
+- `nano-banana-pro` (default): photorealistic, data-driven visuals.
+- `recraft-v4`: design compositions and branded assets. The only model that can return `svg`.
+- `flux-schnell`: fast drafts and concept sketches.
+
+## How to run
+
+```bash
+node ~/.maxy-lite/skills/replicate/scripts/replicate-image.mjs \
+  --prompt="a calm mountain lake at dawn, soft light" \
+  --model=nano-banana-pro \
+  --aspect=16:9 \
+  --format=png
+```
+
+- `--prompt` (required): what to draw.
+- `--model` (optional, default `nano-banana-pro`): one of the three above.
+- `--aspect` (optional, default `1:1`): one of `1:1`, `4:3`, `3:2`, `16:9`, `21:9`, `9:16`.
+- `--format` (optional, default `png`): `png`, `jpg`, `webp`, or `svg` (svg only with `recraft-v4`).
+
+On success the file path prints to stdout and the image is saved under `$LITE_VAULT/Assets/generated/`. Show the owner the path.
+
+## Token
+
+The script reads `REPLICATE_API_TOKEN` from the environment, or falls back to `~/.replicate/api-token`. The lite runtime supplies the token from its secrets. If neither is set the script exits with `error=no-token`. Tell the owner a Replicate token is needed and stop.
+
+## Reading the result
+
+- **A file path on stdout, exit 0**: the image was generated and saved.
+- **Non-zero exit**: an error on stderr as `[replicate] error=<code>`:
+  - `no-token`: no token configured.
+  - `auth`: the token was rejected.
+  - `network`: the Replicate API was unreachable.
+  - `model`: an unknown model, a bad model option, or the generation failed.
+  - `download`: the image was generated but could not be fetched.
+  - `disk`: the image could not be written to the vault.
+
+Surface the error plainly. Never claim an image was made when the script failed.
+
+## Boundaries
+
+Generates one image per call. Does not edit existing images, run image-to-image, or upscale. Those need a different model and are not wired here.

package/payload/skills/replicate/scripts/replicate-image.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// replicate-image — image generation via the Replicate HTTP API. Zero deps.
+//
+// Ported from the maxy-code replicate MCP tool to a single lite CLI script.
+// Uses native fetch against the Replicate predictions API (no replicate SDK, no
+// nanoid). Same three-model registry and aspect-ratio table. The generated image
+// is downloaded into the vault assets directory and its path printed to stdout.
+//
+// Token resolution (parity with maxy-code): REPLICATE_API_TOKEN env first, then
+// ~/.replicate/api-token. Errors go to stderr as [replicate] error=<code> and
+// exit non-zero. Codes: usage, no-token, model, auth, network, download, disk.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+
+const MODELS = {
+  "nano-banana-pro": { owner: "google", name: "nano-banana-pro" },
+  "recraft-v4": { owner: "recraft-ai", name: "recraft-v4", svg: "recraft-v4-svg" },
+  "flux-schnell": { owner: "black-forest-labs", name: "flux-schnell" },
+};
+
+const ASPECT = {
+  "1:1": { width: 1024, height: 1024 },
+  "4:3": { width: 1024, height: 768 },
+  "3:2": { width: 1024, height: 683 },
+  "16:9": { width: 1024, height: 576 },
+  "21:9": { width: 1344, height: 576 },
+  "9:16": { width: 576, height: 1024 },
+};
+
+const fail = (code, msg) => {
+  console.error(`[replicate] error=${code} detail=${JSON.stringify(msg)}`);
+  process.exit(1);
+};
+
+const args = Object.fromEntries(
+  process.argv.slice(2).map((a) => {
+    const m = a.match(/^--([^=]+)=(.*)$/);
+    return m ? [m[1], m[2]] : [a, true];
+  }),
+);
+const prompt = args.prompt;
+const model = args.model || "nano-banana-pro";
+const aspectRatio = args.aspect || "1:1";
+const outputFormat = args.format || "png";
+if (!prompt || prompt === true) {
+  fail("usage", "usage: replicate-image.mjs --prompt=<text> [--model=] [--aspect=] [--format=]");
+}
+
+const token =
+  process.env.REPLICATE_API_TOKEN ||
+  (existsSync(join(homedir(), ".replicate", "api-token"))
+    ? readFileSync(join(homedir(), ".replicate", "api-token"), "utf-8").trim()
+    : "");
+if (!token) fail("no-token", "no Replicate token (set REPLICATE_API_TOKEN or ~/.replicate/api-token)");
+
+const entry = MODELS[model];
+if (!entry) fail("model", `unknown model: ${model} (use nano-banana-pro, recraft-v4, or flux-schnell)`);
+if (outputFormat === "svg" && model !== "recraft-v4") fail("model", "svg output is only available with recraft-v4");
+const name = outputFormat === "svg" && entry.svg ? entry.svg : entry.name;
+
+const dims = ASPECT[aspectRatio] ?? ASPECT["1:1"];
+const input =
+  model === "flux-schnell"
+    ? { prompt, aspect_ratio: aspectRatio, ...(outputFormat !== "svg" ? { output_format: outputFormat } : {}) }
+    : { prompt, width: dims.width, height: dims.height, ...(outputFormat !== "svg" ? { output_format: outputFormat } : {}) };
+
+// Create a prediction against the model. Prefer:wait blocks until the prediction
+// is terminal where the model supports it; otherwise we poll the get URL.
+const headers = { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Prefer: "wait" };
+let pred;
+try {
+  const r = await fetch(`https://api.replicate.com/v1/models/${entry.owner}/${name}/predictions`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ input }),
+  });
+  if (r.status === 401 || r.status === 403) fail("auth", "Replicate token rejected (invalid or revoked)");
+  if (!r.ok) fail("model", `Replicate API HTTP ${r.status}: ${(await r.text()).slice(0, 200)}`);
+  pred = await r.json();
+} catch (err) {
+  fail("network", err instanceof Error ? err.message : String(err));
+}
+
+while (pred.status && pred.status !== "succeeded" && pred.status !== "failed" && pred.status !== "canceled") {
+  if (!pred.urls?.get) fail("model", "prediction is not terminal but carries no poll URL");
+  await new Promise((r) => setTimeout(r, 1500));
+  try {
+    const r = await fetch(pred.urls.get, { headers: { Authorization: `Bearer ${token}` } });
+    pred = await r.json();
+  } catch (err) {
+    fail("network", err instanceof Error ? err.message : String(err));
+  }
+}
+if (pred.status !== "succeeded") {
+  fail("model", `generation ${pred.status}: ${JSON.stringify(pred.error ?? "").slice(0, 200)}`);
+}
+
+// Replicate output is a URL string or an array of URL strings, depending on model.
+const out = pred.output;
+const imageUrl = Array.isArray(out)
+  ? out.find((u) => typeof u === "string" && u.startsWith("http"))
+  : typeof out === "string" && out.startsWith("http")
+    ? out
+    : null;
+if (!imageUrl) fail("model", "generation returned unexpected output format");
+
+let buf;
+try {
+  const r = await fetch(imageUrl);
+  if (!r.ok) throw new Error(`HTTP ${r.status}`);
+  buf = Buffer.from(await r.arrayBuffer());
+} catch (err) {
+  fail("download", err instanceof Error ? err.message : String(err));
+}
+
+const ext = outputFormat === "svg" ? "svg" : outputFormat;
+const date = new Date().toISOString().slice(0, 10);
+const vault = process.env.LITE_VAULT || join(homedir(), ".maxy-lite", "vault");
+const genDir = resolve(vault, "Assets", "generated");
+const file = resolve(genDir, `${date}-${randomUUID().slice(0, 6)}.${ext}`);
+try {
+  mkdirSync(genDir, { recursive: true });
+  writeFileSync(file, buf);
+} catch (err) {
+  fail("disk", err instanceof Error ? err.message : String(err));
+}
+
+console.error(`[replicate] complete model=${model} format=${outputFormat} aspect=${aspectRatio} file=${file}`);
+process.stdout.write(file + "\n");

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/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)
   })
 })