@rubytech/create-maxy-lite 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @rubytech/create-maxy-lite
+
+The maxy-lite installer: one command that puts the `claude` code binary on an Android phone, controlled from the phone browser. Run it in bare Termux; it orchestrates the whole on-device stack.
+
+## Install
+
+```sh
+# In Termux (from F-Droid):
+pkg install -y nodejs
+npx @rubytech/create-maxy-lite
+```
+
+The single `npx` does everything, idempotently:
+
+1. `termux-deps` — Termux packages (`proot-distro`) for the glibc layer
+2. `proot` — verify the proot-distro framework is operational
+3. `ubuntu` — install the glibc Ubuntu rootfs under proot
+4. `node` — pinned glibc Node inside Ubuntu (the bionic Node cannot run `claude`)
+5. `toolchain` — `python3`/`make`/`g++` so `node-pty` compiles
+6. `vault-bind` — the shared-storage vault plus the proot bind so Obsidian and `claude` share one folder
+7. `npm-app` — pinned `@anthropic-ai/claude-code` and `ttyd`, the app (validator + web-chat relay), and the `maxy-lite` launcher
+
+Re-running reconciles to the same state without duplicating anything. `--dry-run` prints the plan and pinned versions without touching the device.
+
+## Why a Node-only installer works in bare Termux
+
+`claude` ships a glibc-only native binary, so the *agent* must run inside a proot-distro Ubuntu layer. But the *installer* is plain Node and runs fine on Termux's bionic Node, so there is no hosted shell script to maintain. A `curl … | bash` bootstrap exists only as a documented alternative (it just installs the Node prerequisite and calls this same package).
+
+## Layout
+
+| Path | What |
+|---|---|
+| `index.mjs` | Entry: wires the real subprocess/fs/probe primitives and runs the orchestrator. |
+| `lib/orchestrate.mjs` | The guarded, idempotent step sequence. |
+| `lib/healthcheck.mjs` | The four post-install probes (claude, webchat, validator, vault). |
+| `lib/pins.mjs`, `versions.json` | Pinned Node major, claude-code and ttyd versions. |
+| `lib/paths.mjs` | On-device paths and the `maxy-lite` launcher. |
+| `payload/` | Bundled app components (schema, validator, webchat), generated by `npm run bundle`. |
+
+The `payload/` directory is gitignored and rebuilt at publish time from the sibling `maxy-lite` component tree; edit the sources there, never the payload.
+
+## Observability
+
+Every step emits one structured line so a failed install is diagnosable from its log:
+
+```
+[lite-install] op=step name=<…> ok=<bool> ms=<…>
+[lite-install] op=versions node=<v> claude=<v> ttyd=<v>
+[lite-install] op=healthcheck claude=<bool> webchat=<bool> validator=<bool> vault=<bool>
+[lite-install] op=done ok=<bool> ranMs=<…>
+```
+
+A healthy run ends `op=done ok=true`. The first `ok=false` step is the failure point. Full operator instructions: `maxy-code/.docs/maxy-lite-install.md`.
+
+## Tests
+
+```sh
+npm test     # node --test over lib (log, pins, paths, healthcheck, orchestrate, bundle)
+```
+
+The validator probe runs the real bundled validator against an empty vault; the orchestrator tests assert the step order, the idempotency guards, and the structured-line output against a recording context.

package/index.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// @rubytech/create-maxy-lite — the maxy-lite installer.
+//
+// Run in bare Termux (bionic Node) via `npx @rubytech/create-maxy-lite`. It
+// orchestrates the whole on-device install: proot-distro Ubuntu -> glibc Node ->
+// claude -> the app (validator + web-chat relay) -> the shared-storage vault and
+// its proot bind-mount. Every step emits one `[lite-install]` line and the run
+// exits non-zero on any failed step or health-check probe.
+//
+// This file is only the wiring: it builds the real subprocess/fs/probe
+// primitives and hands them to orchestrate(). The sequence, guards, idempotency
+// and probe rules live in ./lib and are unit-tested there.
+//
+// Subprocesses use spawnSync with an explicit (file, args[]) — never exec() and
+// never shell:true. The command text is interpreted by an explicit `bash -lc` so
+// pipes work; every command is a pinned constant from versions.json/paths.mjs,
+// never user input, so there is no injection surface.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+import { makeLog } from './lib/log.mjs'
+import { readPins } from './lib/pins.mjs'
+import { PATHS, WEBCHAT_DIR, VALIDATOR_CLI, launcherPath, launcherScript } from './lib/paths.mjs'
+import { orchestrate, STEP_NAMES } from './lib/orchestrate.mjs'
+import { claudeOk, validatorOk, vaultOk, webchatOk, healthcheck } from './lib/healthcheck.mjs'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const PAYLOAD = path.join(HERE, 'payload')
+const PINS = readPins(path.join(HERE, 'versions.json'))
+const PREFIX = process.env.PREFIX || '/data/data/com.termux/files/usr'
+
+// ---- subprocess primitives --------------------------------------------------
+
+const decode = (r) => ({ code: r.status === null ? 1 : r.status, stdout: r.stdout || '' })
+
+/** Run a command in bare Termux. */
+const run = (cmd) => decode(spawnSync('bash', ['-lc', cmd], { encoding: 'utf8' }))
+
+/** Run a command inside the glibc Ubuntu layer. */
+const runIn = (cmd) =>
+  decode(spawnSync('proot-distro', ['login', PATHS.distro, '--', 'bash', '-lc', cmd], { encoding: 'utf8' }))
+
+// ---- filesystem primitives --------------------------------------------------
+// The Ubuntu rootfs is a normal directory under the Termux prefix, so the app
+// payload is copied into it directly from bionic Node (no proot round-trip).
+
+const rootfs = `${PREFIX}/var/lib/proot-distro/installed-rootfs/${PATHS.distro}`
+const appHostPath = `${rootfs}${PATHS.appDir}` // appDir is absolute inside the rootfs
+
+const existsHost = (p) => fs.existsSync(p)
+const mkdirHost = (p) => fs.mkdirSync(p, { recursive: true })
+
+/** Copy the bundled app payload into the Ubuntu rootfs (idempotent overwrite). */
+const layPayload = () => {
+  fs.mkdirSync(appHostPath, { recursive: true })
+  fs.cpSync(PAYLOAD, appHostPath, { recursive: true })
+}
+
+/** Install the app deps (validator's js-yaml) and the webchat deps (node-pty, ws). */
+const installDeps = () => {
+  if (runIn(`cd ${PATHS.appDir} && npm install --omit=dev`).code !== 0) throw new Error('app deps install failed')
+  if (runIn(`cd ${WEBCHAT_DIR} && npm install --omit=dev`).code !== 0) throw new Error('webchat deps install failed')
+}
+
+/** Write the `maxy-lite` launcher into the Termux bin dir. */
+const writeLauncher = () => {
+  fs.writeFileSync(launcherPath(PREFIX), launcherScript({ prefix: PREFIX }), { mode: 0o755 })
+}
+
+// ---- measured versions ------------------------------------------------------
+
+const firstMatch = (s, re, fallback) => {
+  const m = re.exec(s || '')
+  return m ? m[1] : fallback
+}
+
+const readVersions = () => ({
+  node: firstMatch(runIn('node -v').stdout, /v(\d+\.\d+\.\d+)/, PINS.nodeMajor),
+  claude: firstMatch(runIn('claude --version').stdout, /(\d+\.\d+\.\d+)/, PINS.claudeCode),
+  ttyd: firstMatch(runIn('ttyd --version').stdout, /(\d+\.\d+\.\d+)/, PINS.ttyd),
+})
+
+// ---- health-check probes (the measured post-conditions) ---------------------
+
+const runHealthcheck = () =>
+  healthcheck({
+    checkClaude: () => claudeOk(() => runIn('claude --version')),
+    // Start the relay, poll its port for up to 10s, record whether it bound, kill it.
+    checkWebchat: () =>
+      webchatOk(async () => {
+        const probe =
+          `cd ${WEBCHAT_DIR} && node server.mjs & SVPID=$!; ` +
+          `for i in $(seq 1 10); do sleep 1; ` +
+          `curl -sf -o /dev/null http://localhost:${PATHS.webchatPort} && break; done; ` +
+          `curl -sf -o /dev/null http://localhost:${PATHS.webchatPort}; RC=$?; ` +
+          `kill $SVPID 2>/dev/null; exit $RC`
+        return runIn(probe).code === 0
+      }),
+    // Validator must exit 0 on an empty vault.
+    checkValidator: () => {
+      const empty = `${PATHS.appDir}/.hc-empty-vault`
+      runIn(`mkdir -p ${empty}`)
+      return validatorOk((vault) => runIn(`node ${VALIDATOR_CLI} ${vault}`).code, empty)
+    },
+    checkVault: () => vaultOk(() => runIn(`test -d ${PATHS.vaultGuest}`).code === 0),
+  })
+
+// ---- dry run ----------------------------------------------------------------
+
+function printDryRun(log) {
+  log('plan', { steps: STEP_NAMES.join('>'), node: PINS.nodeMajor, claude: PINS.claudeCode, ttyd: PINS.ttyd })
+  log('plan', { vaultHost: PATHS.vaultHost, vaultGuest: PATHS.vaultGuest, appDir: PATHS.appDir })
+  log('plan', { launcher: launcherPath(PREFIX), webchatPort: PATHS.webchatPort })
+}
+
+// ---- entry ------------------------------------------------------------------
+
+async function main() {
+  const log = makeLog()
+  if (process.argv.includes('--dry-run')) {
+    printDryRun(log)
+    return 0
+  }
+  const ctx = {
+    run,
+    runIn,
+    existsHost,
+    mkdirHost,
+    layPayload,
+    installDeps,
+    writeLauncher,
+    readVersions,
+    runHealthcheck,
+    pins: PINS,
+    now: () => Date.now(),
+    log,
+  }
+  const result = await orchestrate(ctx)
+  return result.ok ? 0 : 1
+}
+
+main()
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    process.stderr.write(`[lite-install] op=done ok=false error=${err && err.message ? err.message : err}\n`)
+    process.exit(1)
+  })

package/lib/healthcheck.mjs

@@ -0,0 +1,41 @@
+// Post-install health check — the measured post-conditions, not "ran the step".
+// Each probe answers a binary question about the running system:
+//   claude    — does `claude --version` answer with a version?
+//   webchat   — does the relay port listen?
+//   validator — does the validator exit 0 on an empty vault?
+//   vault     — does the bind-mount path exist inside Ubuntu?
+// The probes take injected primitives so the decision rules are unit-testable;
+// index.mjs wires the real ones (run-in-Ubuntu, transient port probe, fs stat).
+
+const VERSION_RE = /\d+\.\d+\.\d+/
+
+/** True when `claude --version` exits 0 and prints a version. `runIn(cmd)` → {code, stdout}. */
+export function claudeOk(runVersion) {
+  const r = runVersion()
+  return r.code === 0 && VERSION_RE.test(r.stdout || '')
+}
+
+/** True when the validator exits 0 on the given (empty) vault. `runValidator(vault)` → exit code. */
+export function validatorOk(runValidator, vaultPath) {
+  return runValidator(vaultPath) === 0
+}
+
+/** True when the bind-mount path exists. `exists()` → bool. */
+export function vaultOk(exists) {
+  return exists() === true
+}
+
+/** True when the relay port responded. `getStatus()` → Promise<bool>. */
+export async function webchatOk(getStatus) {
+  return (await getStatus()) === true
+}
+
+/** Run all four probes and return `{ claude, webchat, validator, vault }`. */
+export async function healthcheck({ checkClaude, checkWebchat, checkValidator, checkVault }) {
+  return {
+    claude: checkClaude() === true,
+    webchat: (await checkWebchat()) === true,
+    validator: checkValidator() === true,
+    vault: checkVault() === true,
+  }
+}

package/lib/log.mjs

@@ -0,0 +1,16 @@
+// Structured install log. Every install step emits exactly one `[lite-install]`
+// line so a failed install is diagnosable from its log without re-running blind:
+//   bootstrap 2>&1 | tee install.log; grep '\[lite-install\]' install.log
+// The first `ok=false` step is the failure point.
+
+/** Format one structured line: `[lite-install] op=<op> k=v k=v …` (field order preserved). */
+export function formatLine(op, fields = {}) {
+  const parts = [`[lite-install] op=${op}`]
+  for (const [k, v] of Object.entries(fields)) parts.push(`${k}=${v}`)
+  return parts.join(' ')
+}
+
+/** Wrap a writer (default: stderr) into `log(op, fields)` that emits one formatted line. */
+export function makeLog(write = (s) => process.stderr.write(s + '\n')) {
+  return (op, fields = {}) => write(formatLine(op, fields))
+}

package/lib/orchestrate.mjs

@@ -0,0 +1,148 @@
+// The install sequence. Run in bare Termux (bionic Node); each step provisions
+// one layer of the runtime stack and emits exactly one `[lite-install] op=step`
+// line, gated on exit code. Every step has a `done(ctx)` guard so a re-run on a
+// converged device skips the mutation and still reports ok=true (idempotent).
+//
+// Steps, in order:
+//   termux-deps — Termux packages (proot-distro) for the glibc layer
+//   proot       — verify the proot-distro framework is operational
+//   ubuntu      — install the glibc Ubuntu rootfs under proot
+//   node        — pinned glibc Node inside Ubuntu (the bionic Node can't run claude)
+//   toolchain   — python3/make/g++ so node-pty compiles
+//   vault-bind  — shared-storage vault + the proot bind so Obsidian and claude share it
+//   npm-app     — pinned claude-code + ttyd, the app payload, webchat deps, the launcher
+//
+// All external effects go through injected ctx primitives so the sequence,
+// guards and idempotency are unit-testable; index.mjs wires the real ones.
+
+import { PATHS, WEBCHAT_DIR, launcherPath } from './paths.mjs'
+
+export const STEP_NAMES = ['termux-deps', 'proot', 'ubuntu', 'node', 'toolchain', 'vault-bind', 'npm-app']
+
+/** Throw unless the command result is a clean exit. */
+function ensureOk(r) {
+  if (!r || r.code !== 0) throw new Error(`command failed (code ${r ? r.code : 'none'})`)
+  return r
+}
+
+/** The Ubuntu rootfs path under the Termux prefix. */
+function rootfsPath() {
+  const prefix = process.env.PREFIX || '/data/data/com.termux/files/usr'
+  return `${prefix}/var/lib/proot-distro/installed-rootfs/${PATHS.distro}`
+}
+
+/** True when the glibc Node inside Ubuntu matches the pinned major. */
+function nodeMajorOk(c) {
+  const r = c.runIn('node -v')
+  if (r.code !== 0) return false
+  const m = /^v(\d+)\./.exec((r.stdout || '').trim())
+  return !!m && m[1] === String(c.pins.nodeMajor)
+}
+
+const STEPS = [
+  {
+    name: 'termux-deps',
+    done: (c) => c.run('command -v proot-distro').code === 0,
+    run: (c) => ensureOk(c.run('pkg install -y proot-distro')),
+  },
+  {
+    name: 'proot',
+    done: () => false, // read-only verification gate; always runs, never mutates
+    run: (c) => ensureOk(c.run('proot-distro list')),
+  },
+  {
+    name: 'ubuntu',
+    done: (c) => c.existsHost(rootfsPath()),
+    run: (c) => ensureOk(c.run(`proot-distro install ${PATHS.distro}`)),
+  },
+  {
+    name: 'node',
+    done: (c) => nodeMajorOk(c),
+    run: (c) => {
+      // runIn already wraps in `bash -lc`; pass the pipeline directly (no inner bash).
+      ensureOk(c.runIn(`curl -fsSL https://deb.nodesource.com/setup_${c.pins.nodeMajor}.x | bash -`))
+      ensureOk(c.runIn('apt install -y nodejs'))
+    },
+  },
+  {
+    name: 'toolchain',
+    done: (c) => c.runIn('command -v g++').code === 0,
+    run: (c) => ensureOk(c.runIn('apt install -y python3 make g++')),
+  },
+  {
+    name: 'vault-bind',
+    done: (c) => c.existsHost(PATHS.vaultHost),
+    run: (c) => {
+      c.mkdirHost(PATHS.vaultHost)
+      ensureOk(c.run(`proot-distro login ${PATHS.distro} --bind ${PATHS.vaultHost}:${PATHS.vaultGuest} -- test -d ${PATHS.vaultGuest}`))
+    },
+  },
+  {
+    name: 'npm-app',
+    // Converged only when the deps are built, claude is present, AND the launcher
+    // is written — the launcher is the last mutation, so guarding on the first two
+    // alone would skip a half-finished install and report ok=true with no launcher.
+    done: (c) =>
+      c.runIn(`test -d ${WEBCHAT_DIR}/node_modules`).code === 0 &&
+      c.runIn('command -v claude').code === 0 &&
+      c.existsHost(launcherPath()),
+    run: (c) => {
+      ensureOk(c.runIn(`npm install -g @anthropic-ai/claude-code@${c.pins.claudeCode}`))
+      // Pin ttyd to the manifest version via its release binary; apt would float.
+      ensureOk(
+        c.runIn(
+          `curl -fsSL -o /usr/local/bin/ttyd https://github.com/tsl0922/ttyd/releases/download/${c.pins.ttyd}/ttyd.aarch64 && chmod +x /usr/local/bin/ttyd`,
+        ),
+      )
+      c.layPayload()
+      c.installDeps()
+      c.writeLauncher()
+    },
+  },
+]
+
+/** Run one step: guard then action, timed, one structured line. Never throws. */
+function runStep(step, ctx) {
+  const start = ctx.now()
+  let ok = false
+  let skipped = false
+  try {
+    if (step.done(ctx)) {
+      skipped = true
+      ok = true
+    } else {
+      step.run(ctx)
+      ok = true
+    }
+  } catch {
+    ok = false
+  }
+  const ms = ctx.now() - start
+  ctx.log('step', { name: step.name, ok, ms })
+  return { name: step.name, ok, skipped, ms }
+}
+
+/**
+ * Run the full install. Stops at the first failed step (logs `done ok=false`,
+ * no healthcheck). On success: emits the resolved versions, the four-probe
+ * healthcheck, and `done ok=<all probes true>`.
+ */
+export async function orchestrate(ctx) {
+  const t0 = ctx.now()
+  const results = []
+  for (const step of STEPS) {
+    const r = runStep(step, ctx)
+    results.push(r)
+    if (!r.ok) {
+      ctx.log('done', { ok: false, ranMs: ctx.now() - t0 })
+      return { ok: false, results }
+    }
+  }
+  const v = ctx.readVersions()
+  ctx.log('versions', { node: v.node, claude: v.claude, ttyd: v.ttyd })
+  const hc = await ctx.runHealthcheck()
+  ctx.log('healthcheck', hc)
+  const ok = Object.values(hc).every(Boolean)
+  ctx.log('done', { ok, ranMs: ctx.now() - t0 })
+  return { ok, results, healthcheck: hc }
+}

package/lib/paths.mjs

@@ -0,0 +1,50 @@
+// On-device paths and the launcher.
+//
+// Two distinct surfaces, deliberately separated:
+//   - The VAULT (markdown the agent reads/writes) lives on Android shared
+//     storage so Obsidian — an Android app — can open it as a vault. It is
+//     bind-mounted into the Ubuntu rootfs so `claude` (in proot) sees the same
+//     folder. Obsidian and claude share one tree.
+//   - The APP code (validator, webchat, its node_modules with native node-pty)
+//     lives INSIDE the Ubuntu rootfs. Android shared storage is commonly mounted
+//     noexec / no-symlink, which breaks a native node_modules; the rootfs is a
+//     normal ext4-backed tree, so the app and its build live there.
+
+export const PATHS = {
+  distro: 'ubuntu',
+  vaultHost: '/storage/emulated/0/maxy', // Android shared storage (Obsidian opens this)
+  vaultGuest: '/root/maxy', // bind target inside Ubuntu (claude's working dir)
+  appDir: '/root/.maxy-lite/app', // app code + node_modules, in the rootfs
+  webchatPort: 7682,
+}
+
+export const WEBCHAT_DIR = `${PATHS.appDir}/webchat`
+export const VALIDATOR_CLI = `${PATHS.appDir}/validator/cli.mjs`
+
+/** Absolute path of the `maxy-lite` launcher in the Termux bin dir. */
+export function launcherPath(prefix = process.env.PREFIX || '/data/data/com.termux/files/usr') {
+  return `${prefix}/bin/maxy-lite`
+}
+
+/**
+ * The `maxy-lite` launcher script (written into the Termux bin dir). Run from the
+ * Termux shell, it enters Ubuntu with the vault bind-mount and starts the webchat
+ * relay on localhost. Documented Termux:Boot opt-in re-runs this on boot.
+ */
+export function launcherScript({
+  prefix = process.env.PREFIX || '/data/data/com.termux/files/usr',
+  vaultHost = PATHS.vaultHost,
+  vaultGuest = PATHS.vaultGuest,
+  webchatDir = WEBCHAT_DIR,
+  port = PATHS.webchatPort,
+  distro = PATHS.distro,
+} = {}) {
+  return `#!${prefix}/bin/bash
+# maxy-lite launcher — starts the on-device web chat relay.
+# Enters the glibc Ubuntu layer with the shared-storage vault bound in, then runs
+# the relay on http://localhost:${port}. Open that URL in the phone browser.
+set -e
+exec proot-distro login ${distro} --bind ${vaultHost}:${vaultGuest} -- \\
+  bash -lc 'cd ${webchatDir} && LITE_AGENT_HOME=${vaultGuest} LITE_PORT=${port} exec node server.mjs'
+`
+}

package/lib/pins.mjs

@@ -0,0 +1,22 @@
+// Version pins — one source of truth (versions.json). The installer pins Node,
+// claude-code and ttyd so a fresh device gets reproducible versions, never a
+// floating `latest`. Read once at startup; `op=versions` reports what landed.
+
+import fs from 'node:fs'
+
+const REQUIRED = ['nodeMajor', 'claudeCode', 'ttyd']
+
+/** Read and validate the pinned versions. Throws on a missing, empty or floating pin. */
+export function readPins(manifestPath) {
+  const raw = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+  for (const key of REQUIRED) {
+    const v = raw[key]
+    if (v === undefined || v === null || String(v).trim() === '') {
+      throw new Error(`pins: ${key} is required in ${manifestPath}`)
+    }
+    if (String(v).trim().toLowerCase() === 'latest') {
+      throw new Error(`pins: ${key} must be a fixed version, not "latest"`)
+    }
+  }
+  return { nodeMajor: String(raw.nodeMajor), claudeCode: String(raw.claudeCode), ttyd: String(raw.ttyd) }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@rubytech/create-maxy-lite",
+  "version": "0.1.0",
+  "description": "Install maxy-lite on an Android phone: orchestrates proot-distro Ubuntu, glibc Node, claude, the web-chat relay, the vault and its bind-mount — run via npx in bare Termux.",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "create-maxy-lite": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "lib",
+    "versions.json",
+    "payload",
+    "README.md"
+  ],
+  "scripts": {
+    "bundle": "node scripts/bundle.mjs",
+    "test": "node --test 'test/*.test.mjs'",
+    "prepublishOnly": "node scripts/bundle.mjs"
+  },
+  "keywords": [
+    "maxy-lite",
+    "android",
+    "termux",
+    "claude",
+    "on-device"
+  ],
+  "author": "Rubytech LLC",
+  "license": "UNLICENSED"
+}

package/payload/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "maxy-lite-app",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  }
+}