@rubytech/create-maxy-lite 0.1.0 → 0.1.2

package/index.mjs

@@ -18,7 +18,7 @@
 
 import fs from 'node:fs'
 import path from 'node:path'
-import { spawnSync } from 'node:child_process'
+import { spawn, spawnSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 
 import { makeLog } from './lib/log.mjs'
@@ -34,15 +34,44 @@ 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 || '' })
+// stderr is kept (not just stdout) so a failed command's cause is recoverable
+// from the install log without re-running by hand.
+const decode = (r) => ({ code: r.status === null ? 1 : r.status, stdout: r.stdout || '', stderr: r.stderr || '' })
 
-/** Run a command in bare Termux. */
+/** Run a command in bare Termux (captured, for guards and quick steps). */
 const run = (cmd) => decode(spawnSync('bash', ['-lc', cmd], { encoding: 'utf8' }))
 
-/** Run a command inside the glibc Ubuntu layer. */
+/** Run a command inside the glibc Ubuntu layer (captured). */
 const runIn = (cmd) =>
   decode(spawnSync('proot-distro', ['login', PATHS.distro, '--', 'bash', '-lc', cmd], { encoding: 'utf8' }))
 
+// Streaming variants for the long, network-bound steps: tee the child's stdout
+// and stderr to the terminal as they arrive (so the operator sees apt/proot/npm
+// progress live), while capturing a bounded slice of stderr for the failure
+// message. Returns the same { code, stdout, stderr } shape, stdout left empty
+// (these commands are run for effect, never parsed).
+const STDERR_CAP = 8192
+
+function spawnStreaming(file, args) {
+  return new Promise((resolve) => {
+    const child = spawn(file, args, { stdio: ['ignore', 'pipe', 'pipe'] })
+    let stderr = ''
+    child.stdout.on('data', (d) => process.stdout.write(d))
+    child.stderr.on('data', (d) => {
+      process.stderr.write(d)
+      if (stderr.length < STDERR_CAP) stderr += d.toString()
+    })
+    child.on('error', (e) => resolve({ code: 1, stdout: '', stderr: String(e && e.message ? e.message : e) }))
+    child.on('close', (code) => resolve({ code: code === null ? 1 : code, stdout: '', stderr: stderr.slice(0, STDERR_CAP) }))
+  })
+}
+
+/** Stream a command in bare Termux. */
+const runStream = (cmd) => spawnStreaming('bash', ['-lc', cmd])
+
+/** Stream a command inside the glibc Ubuntu layer. */
+const runInStream = (cmd) => spawnStreaming('proot-distro', ['login', PATHS.distro, '--', 'bash', '-lc', cmd])
+
 // ---- 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).
@@ -53,6 +82,25 @@ const appHostPath = `${rootfs}${PATHS.appDir}` // appDir is absolute inside the
 const existsHost = (p) => fs.existsSync(p)
 const mkdirHost = (p) => fs.mkdirSync(p, { recursive: true })
 
+// ---- shared-storage permission ----------------------------------------------
+// The vault lives on Android shared storage, whose parent (`/storage/emulated/0`)
+// is unwritable until Termux holds the shared-storage permission. `termux-setup-
+// storage` pops the Android grant dialog; the parent becomes writable once the
+// user taps Allow. Detection is the writability of that parent, not an existence
+// check — the directory can be present but inaccessible before the grant.
+
+const storageParent = path.dirname(PATHS.vaultHost)
+const storageAccessible = () => {
+  try {
+    fs.accessSync(storageParent, fs.constants.W_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+const interactive = Boolean(process.stdin.isTTY)
+const STORAGE_POLL_MS = 3000
+
 /** Copy the bundled app payload into the Ubuntu rootfs (idempotent overwrite). */
 const layPayload = () => {
   fs.mkdirSync(appHostPath, { recursive: true })
@@ -60,9 +108,13 @@ const layPayload = () => {
 }
 
 /** 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')
+// Streamed: the webchat deps build node-pty natively, which is slow and verbose;
+// a failure carries the child's stderr so the cause is in the log.
+const installDeps = async () => {
+  const app = await runInStream(`cd ${PATHS.appDir} && npm install --omit=dev`)
+  if (app.code !== 0) throw new Error(`app deps install failed: ${app.stderr.replace(/\s+/g, ' ').trim()}`)
+  const wc = await runInStream(`cd ${WEBCHAT_DIR} && npm install --omit=dev`)
+  if (wc.code !== 0) throw new Error(`webchat deps install failed: ${wc.stderr.replace(/\s+/g, ' ').trim()}`)
 }
 
 /** Write the `maxy-lite` launcher into the Termux bin dir. */
@@ -118,17 +170,49 @@ function printDryRun(log) {
 
 // ---- entry ------------------------------------------------------------------
 
+// A long step emits a liveness heartbeat at least this often, so no silent gap
+// between log lines reads as a hang.
+const HEARTBEAT_MS = 10000
+
 async function main() {
   const log = makeLog()
   if (process.argv.includes('--dry-run')) {
     printDryRun(log)
     return 0
   }
+  // Periodic liveness for a running step: emit `op=step-progress` every
+  // HEARTBEAT_MS until stopped. unref so a stray timer never holds the process open.
+  const heartbeat = (name, startMs) => {
+    const timer = setInterval(() => log('step-progress', { name, elapsedMs: Date.now() - startMs }), HEARTBEAT_MS)
+    if (timer.unref) timer.unref()
+    return () => clearInterval(timer)
+  }
+  // Drive the Android shared-storage grant: surface the dialog, then poll the vault
+  // parent's writability until the user taps Allow. No timeout — the step heartbeat
+  // keeps the wait visibly alive — so a slow grant never fails the install. Returns
+  // only once storage is writable; the caller re-runs the vault-bind mutation after.
+  const ensureStorageGrant = async () => {
+    log('storage-grant', { state: 'requesting' })
+    process.stdout.write(
+      `\n[maxy-lite] Shared storage is needed for the vault at ${PATHS.vaultHost}.\n` +
+        `[maxy-lite] An Android dialog will appear — tap "Allow", then leave this running.\n`,
+    )
+    run('termux-setup-storage')
+    while (!storageAccessible()) {
+      await new Promise((resolve) => setTimeout(resolve, STORAGE_POLL_MS))
+    }
+    log('storage-grant', { state: 'granted' })
+  }
   const ctx = {
     run,
     runIn,
+    runStream,
+    runInStream,
     existsHost,
     mkdirHost,
+    storageAccessible,
+    interactive,
+    ensureStorageGrant,
     layPayload,
     installDeps,
     writeLauncher,
@@ -137,6 +221,7 @@ async function main() {
     pins: PINS,
     now: () => Date.now(),
     log,
+    heartbeat,
   }
   const result = await orchestrate(ctx)
   return result.ok ? 0 : 1

package/lib/orchestrate.mjs

@@ -19,16 +19,44 @@ 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. */
+/** Throw unless the command result is a clean exit; the message carries the command's stderr. */
 function ensureOk(r) {
-  if (!r || r.code !== 0) throw new Error(`command failed (code ${r ? r.code : 'none'})`)
+  if (!r || r.code !== 0) {
+    const stderr = r && r.stderr ? String(r.stderr).replace(/\s+/g, ' ').trim() : ''
+    const detail = stderr ? `: ${stderr}` : ''
+    throw new Error(`command failed (code ${r ? r.code : 'none'})${detail}`)
+  }
   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}`
+/** The actionable error when the vault's shared-storage parent is not writable. */
+const STORAGE_PERMISSION_ERROR = 'storage-permission-required: run termux-setup-storage and grant access'
+
+/**
+ * Gate the vault-bind mutation on shared-storage access. The vault parent
+ * (`/storage/emulated/0`) is unwritable until Termux has been granted Android
+ * shared-storage permission, so `c.mkdirHost(vaultHost)` would otherwise fail with
+ * an opaque `Permission denied`. When access is missing we either drive the
+ * interactive grant (TTY present), which blocks until the permission lands, or
+ * fail fast with a clear, actionable message when no TTY can surface the dialog.
+ */
+async function ensureStorageAccessible(c) {
+  if (c.storageAccessible()) return
+  if (!c.interactive) throw new Error(STORAGE_PERMISSION_ERROR)
+  await c.ensureStorageGrant()
+}
+
+/**
+ * True when proot-distro can enter the distro — its own proof the rootfs is
+ * installed. A login that exits 0 means proot-distro resolved and entered the
+ * rootfs. The earlier guard reconstructed the rootfs path and `fs.existsSync`'d
+ * it, which disagreed with proot-distro on-device (present to proot-distro,
+ * absent to the path guess) and re-ran `install` into an "already exists"
+ * failure. Delegating to proot-distro's own exit code makes the guard agree
+ * with the install action by construction, so an installed distro skips.
+ */
+function distroInstalled(c) {
+  return c.runIn('true').code === 0
 }
 
 /** True when the glibc Node inside Ubuntu matches the pinned major. */
@@ -43,7 +71,8 @@ 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')),
+    // Long and network-bound (repo sync + download); stream so the operator sees apt progress.
+    run: async (c) => ensureOk(await c.runStream('pkg install -y proot-distro')),
   },
   {
     name: 'proot',
@@ -52,27 +81,28 @@ const STEPS = [
   },
   {
     name: 'ubuntu',
-    done: (c) => c.existsHost(rootfsPath()),
-    run: (c) => ensureOk(c.run(`proot-distro install ${PATHS.distro}`)),
+    done: (c) => distroInstalled(c),
+    run: async (c) => ensureOk(await c.runStream(`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'))
+    run: async (c) => {
+      // runInStream already wraps in `bash -lc`; pass the pipeline directly (no inner bash).
+      ensureOk(await c.runInStream(`curl -fsSL https://deb.nodesource.com/setup_${c.pins.nodeMajor}.x | bash -`))
+      ensureOk(await c.runInStream('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++')),
+    run: async (c) => ensureOk(await c.runInStream('apt install -y python3 make g++')),
   },
   {
     name: 'vault-bind',
     done: (c) => c.existsHost(PATHS.vaultHost),
-    run: (c) => {
+    run: async (c) => {
+      await ensureStorageAccessible(c)
       c.mkdirHost(PATHS.vaultHost)
       ensureOk(c.run(`proot-distro login ${PATHS.distro} --bind ${PATHS.vaultHost}:${PATHS.vaultGuest} -- test -d ${PATHS.vaultGuest}`))
     },
@@ -86,39 +116,53 @@ const STEPS = [
       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}`))
+    run: async (c) => {
+      ensureOk(await c.runInStream(`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(
+        await c.runInStream(
           `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()
+      await c.installDeps()
       c.writeLauncher()
     },
   },
 ]
 
-/** Run one step: guard then action, timed, one structured line. Never throws. */
-function runStep(step, ctx) {
+/**
+ * Run one step: announce, guard, then action — timed, one structured line. Never
+ * throws. Emits `op=step-start` before any work so the operator always sees what
+ * is running; a failed step's `op=step` line carries `err=<message>` (the command's
+ * stderr, via ensureOk) so the cause is diagnosable from the log alone. While the
+ * action runs, a heartbeat (injected) keeps a long step from looking hung.
+ */
+async function runStep(step, ctx) {
   const start = ctx.now()
+  ctx.log('step-start', { name: step.name })
   let ok = false
   let skipped = false
+  let errMsg = null
+  let stopHeartbeat = null
   try {
     if (step.done(ctx)) {
       skipped = true
       ok = true
     } else {
-      step.run(ctx)
+      if (ctx.heartbeat) stopHeartbeat = ctx.heartbeat(step.name, start)
+      await step.run(ctx)
       ok = true
     }
-  } catch {
-    ok = false
+  } catch (err) {
+    errMsg = err && err.message ? err.message : String(err)
+  } finally {
+    if (stopHeartbeat) stopHeartbeat()
   }
   const ms = ctx.now() - start
-  ctx.log('step', { name: step.name, ok, ms })
+  const fields = { name: step.name, ok, ms }
+  if (!ok && errMsg) fields.err = errMsg.replace(/\s+/g, ' ').trim().slice(0, 300)
+  ctx.log('step', fields)
   return { name: step.name, ok, skipped, ms }
 }
 
@@ -131,7 +175,7 @@ export async function orchestrate(ctx) {
   const t0 = ctx.now()
   const results = []
   for (const step of STEPS) {
-    const r = runStep(step, ctx)
+    const r = await runStep(step, ctx)
     results.push(r)
     if (!r.ok) {
       ctx.log('done', { ok: false, ranMs: ctx.now() - t0 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-lite",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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": {