@onexeor/lumo 0.0.2 → 0.0.4

package/README.md

@@ -42,6 +42,24 @@ Under the hood the installer:
 The installer never modifies anything outside `~/.lumo`, the chosen
 client's skill directory, and the chosen client's MCP config file.
 
+## Publishing (maintainers only)
+
+The installer ships with no npm lifecycle scripts on purpose — Socket.dev
+and similar supply-chain scanners penalise packages that auto-execute
+code on install or pack, even when that code is benign. To publish a
+new version:
+
+```bash
+cd installer
+bash scripts/release.sh --dry-run   # bundles /skill into installer/skill, npm pack --dry-run
+bash scripts/release.sh             # same, but actually publishes
+```
+
+`release.sh` is the only sanctioned way to build the tarball. Running
+`npm pack` or `npm publish` directly will produce a broken tarball
+without the bundled `SKILL.md`, so `lumo init` would fail
+post-install. The script makes the bundling explicit and Socket-clean.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onexeor/lumo",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Install Lumo — mobile UI/UX design intelligence for AI coding assistants (Claude Code, Cursor, Codex, MCP clients).",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
   },
   "scripts": {
     "start": "node src/index.js",
-    "prepack": "node scripts/bundle-skill.js"
+    "bundle-skill": "node scripts/bundle-skill.js"
   },
   "keywords": [
     "mobile",
@@ -40,11 +40,6 @@
     "url": "https://github.com/OneXeor-Dev/lumo.git"
   },
   "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "commander": "^12.1.0",
-    "kleur": "^4.1.5",
-    "prompts": "^2.4.2"
+    "node": ">=18.3"
   }
 }

package/skill/SKILL.md

@@ -43,7 +43,15 @@ mobile UI concern, stay out.
 
 Lumo ships with Python tools. Each tool has a single CLI entry-point with
 deterministic output. Invoke via Bash. Tools live in `tools/lumo/<area>/cli.py`
-and are exposed as console scripts after `pip install -e tools/`.
+and are exposed as console scripts after `pip install -e tools/` or
+`pipx install lumo-mobile`.
+
+When running inside an MCP-aware client (Cursor, Continue, Aider, Goose,
+Zed, Codex, or Claude Code with MCP enabled), the same four tools are
+also exposed as MCP functions: `lumo_wcag_check`, `lumo_wcag_fix`,
+`lumo_theory_check`, `lumo_parity_diff`. Prefer the MCP function over
+spawning a Bash subprocess when available — the structured response is
+already JSON and the user does not see noisy command output.
 
 ### `lumo-wcag` — WCAG contrast validator + OKLCH auto-correct
 

package/src/commands/doctor.js

@@ -1,28 +1,27 @@
 import fs from "node:fs";
 
-import kleur from "kleur";
-
 import { CLIENTS } from "../lib/clients.js";
 import { LUMO_HOME, listInstalledBinaries, venvBinary } from "../lib/python.js";
+import { bold, cyan, dim, green, red, yellow } from "../lib/style.js";
 
 function row(ok, label, detail = "") {
-  const icon = ok ? kleur.green("✓") : kleur.red("✗");
-  const text = ok ? kleur.white(label) : kleur.yellow(label);
-  console.log(`  ${icon} ${text}${detail ? kleur.dim("  " + detail) : ""}`);
+  const icon = ok ? green("✓") : red("✗");
+  const text = ok ? label : yellow(label);
+  const trail = detail ? "  " + dim(detail) : "";
+  process.stdout.write(`  ${icon} ${text}${trail}\n`);
 }
 
 export async function doctorCommand() {
-  console.log(kleur.bold().cyan("\n• lumo doctor\n"));
+  process.stdout.write("\n" + bold(cyan("• lumo doctor")) + "\n\n");
 
-  console.log(kleur.bold("Python tools"));
-  row(fs.existsSync(LUMO_HOME), `Lumo home`, LUMO_HOME);
-  row(fs.existsSync(venvBinary("python")), `venv Python`, venvBinary("python"));
+  process.stdout.write(bold("Python tools") + "\n");
+  row(fs.existsSync(LUMO_HOME), "Lumo home", LUMO_HOME);
+  row(fs.existsSync(venvBinary("python")), "venv Python", venvBinary("python"));
   for (const bin of listInstalledBinaries()) {
     row(bin.exists, bin.name, bin.path);
   }
 
-  console.log("");
-  console.log(kleur.bold("Client integrations"));
+  process.stdout.write("\n" + bold("Client integrations") + "\n");
   for (const client of CLIENTS) {
     if (!client.skillDir) continue;
     const skillPresent = fs.existsSync(client.skillDir);
@@ -44,7 +43,5 @@ export async function doctorCommand() {
     }
   }
 
-  console.log("");
-  console.log(kleur.dim("Run `lumo init` to install or repair any missing pieces."));
-  console.log("");
+  process.stdout.write("\n" + dim("Run `lumo init` to install or repair any missing pieces.") + "\n\n");
 }

package/src/commands/init.js

@@ -1,14 +1,12 @@
-import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import kleur from "kleur";
-import prompts from "prompts";
-
 import { CLIENTS, getClient } from "../lib/clients.js";
 import { installLumoTools, listInstalledBinaries } from "../lib/python.js";
 import { findSkillSource, installSkill } from "../lib/skill.js";
 import { registerMcp } from "../lib/mcp.js";
+import { select } from "../lib/prompt.js";
+import { bold, cyan, dim, green, yellow } from "../lib/style.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -18,33 +16,29 @@ function devSource() {
   return path.resolve(__dirname, "..", "..", "..", "tools");
 }
 
-async function pickClient(supplied, allFlag) {
+async function pickClients(supplied, allFlag) {
   if (allFlag) return CLIENTS.filter((c) => c.id !== "generic");
   if (supplied) return [getClient(supplied)];
 
-  const { ai } = await prompts({
-    type: "select",
-    name: "ai",
+  const ai = await select({
     message: "Which AI client are you installing Lumo for?",
     choices: CLIENTS.map((c) => ({ title: c.label, value: c.id })),
     initial: 0,
   });
-  if (!ai) {
-    throw new Error("No client selected.");
-  }
+  if (!ai) throw new Error("No client selected.");
   return [getClient(ai)];
 }
 
 export async function initCommand(opts) {
-  console.log(kleur.bold().cyan("\n• Lumo installer\n"));
+  process.stdout.write("\n" + bold(cyan("• Lumo installer")) + "\n\n");
 
-  const targets = await pickClient(opts.ai, opts.all);
+  const targets = await pickClients(opts.ai, opts.all);
 
-  console.log(kleur.dim("→ installing Python tools (lumo-mobile) into ~/.lumo/venv ..."));
+  process.stdout.write(dim("→ installing Python tools (lumo-mobile) into ~/.lumo/venv ...\n"));
   try {
     if (opts.dev) {
       const dev = devSource();
-      console.log(kleur.dim(`  using --dev source ${dev}`));
+      process.stdout.write(dim(`  using --dev source ${dev}\n`));
       await installLumoTools({ source: dev });
     } else {
       await installLumoTools();
@@ -61,39 +55,37 @@ export async function initCommand(opts) {
         missing.map((b) => `${b.name} (expected at ${b.path})`).join("\n  ")
     );
   }
-  console.log(kleur.green(`✓ Python tools installed`));
-  bins.forEach((b) => console.log(kleur.dim(`  ${b.name}  ${b.path}`)));
+  process.stdout.write(green("✓ Python tools installed\n"));
+  bins.forEach((b) => process.stdout.write(dim(`  ${b.name}  ${b.path}\n`)));
 
   const skillSource = findSkillSource();
 
   for (const client of targets) {
-    console.log(kleur.bold(`\n→ ${client.label}`));
+    process.stdout.write("\n" + bold(`→ ${client.label}`) + "\n");
     if (!client.skillDir) {
-      console.log(kleur.dim("  generic mode — nothing to copy automatically."));
-      console.log(kleur.dim("  Skill bundle is at: ") + skillSource);
-      console.log(kleur.dim("  MCP server command: ") + listInstalledBinaries()[3].path);
+      process.stdout.write(dim("  generic mode — nothing to copy automatically.\n"));
+      process.stdout.write(dim("  Skill bundle is at: ") + skillSource + "\n");
+      process.stdout.write(dim("  MCP server command: ") + listInstalledBinaries()[3].path + "\n");
       continue;
     }
 
     installSkill(client.skillDir);
-    console.log(kleur.green(`  ✓ skill copied to ${client.skillDir}`));
+    process.stdout.write(green(`  ✓ skill copied to ${client.skillDir}\n`));
 
     if (opts.mcp !== false && client.mcpConfigPath && client.mcpConfigKey) {
       try {
         const { configPath, command } = registerMcp(client.mcpConfigPath, client.mcpConfigKey);
-        console.log(kleur.green(`  ✓ MCP registered in ${configPath}`));
-        console.log(kleur.dim(`    command: ${command}`));
+        process.stdout.write(green(`  ✓ MCP registered in ${configPath}\n`));
+        process.stdout.write(dim(`    command: ${command}\n`));
       } catch (err) {
-        console.log(
-          kleur.yellow(`  ! MCP registration skipped: ${err.message}`)
-        );
+        process.stdout.write(yellow(`  ! MCP registration skipped: ${err.message}\n`));
       }
     } else if (opts.mcp === false) {
-      console.log(kleur.dim("  MCP registration skipped (--no-mcp)."));
+      process.stdout.write(dim("  MCP registration skipped (--no-mcp).\n"));
     }
   }
 
-  console.log(kleur.bold().green("\n✓ Lumo installation complete.\n"));
-  console.log(kleur.dim("Next: open your AI client and ask it to use the Lumo skill."));
-  console.log(kleur.dim("Verify any time with: lumo doctor\n"));
+  process.stdout.write("\n" + bold(green("✓ Lumo installation complete.")) + "\n\n");
+  process.stdout.write(dim("Next: open your AI client and ask it to use the Lumo skill.\n"));
+  process.stdout.write(dim("Verify any time with: lumo doctor\n\n"));
 }

package/src/commands/uninstall.js

@@ -1,17 +1,14 @@
-import kleur from "kleur";
-import prompts from "prompts";
-
 import { CLIENTS, getClient } from "../lib/clients.js";
 import { unregisterMcp } from "../lib/mcp.js";
 import { removeSkill } from "../lib/skill.js";
+import { select } from "../lib/prompt.js";
+import { bold, cyan, dim, green } from "../lib/style.js";
 
-async function pickClient(supplied, allFlag) {
+async function pickClients(supplied, allFlag) {
   if (allFlag) return CLIENTS.filter((c) => c.id !== "generic");
   if (supplied) return [getClient(supplied)];
 
-  const { ai } = await prompts({
-    type: "select",
-    name: "ai",
+  const ai = await select({
     message: "Remove Lumo from which client?",
     choices: CLIENTS.filter((c) => c.skillDir).map((c) => ({ title: c.label, value: c.id })),
     initial: 0,
@@ -21,31 +18,31 @@ async function pickClient(supplied, allFlag) {
 }
 
 export async function uninstallCommand(opts) {
-  console.log(kleur.bold().cyan("\n• Lumo uninstaller\n"));
+  process.stdout.write("\n" + bold(cyan("• Lumo uninstaller")) + "\n\n");
 
-  const targets = await pickClient(opts.ai, opts.all);
+  const targets = await pickClients(opts.ai, opts.all);
 
   for (const client of targets) {
     if (!client.skillDir) continue;
-    console.log(kleur.bold(`\n→ ${client.label}`));
+    process.stdout.write("\n" + bold(`→ ${client.label}`) + "\n");
 
     const removed = removeSkill(client.skillDir);
     if (removed) {
-      console.log(kleur.green(`  ✓ skill removed from ${client.skillDir}`));
+      process.stdout.write(green(`  ✓ skill removed from ${client.skillDir}\n`));
     } else {
-      console.log(kleur.dim(`  skill not present (${client.skillDir})`));
+      process.stdout.write(dim(`  skill not present (${client.skillDir})\n`));
     }
 
     if (client.mcpConfigPath && client.mcpConfigKey) {
       const unreg = unregisterMcp(client.mcpConfigPath, client.mcpConfigKey);
       if (unreg) {
-        console.log(kleur.green(`  ✓ MCP entry removed from ${client.mcpConfigPath}`));
+        process.stdout.write(green(`  ✓ MCP entry removed from ${client.mcpConfigPath}\n`));
       } else {
-        console.log(kleur.dim(`  no MCP entry to remove`));
+        process.stdout.write(dim(`  no MCP entry to remove\n`));
       }
     }
   }
 
-  console.log(kleur.dim("\nPython tools (~/.lumo/venv) left intact."));
-  console.log(kleur.dim("Remove them manually with: rm -rf ~/.lumo\n"));
+  process.stdout.write("\n" + dim("Python tools (~/.lumo/venv) left intact.") + "\n");
+  process.stdout.write(dim("Remove them manually with: rm -rf ~/.lumo") + "\n\n");
 }

package/src/index.js

@@ -3,57 +3,128 @@
  * lumo — mobile UI/UX design intelligence installer.
  *
  * Subcommands:
- *   init [--ai <client>] [--all]   Install the Lumo skill (+ optional MCP) into an AI client.
- *   doctor                         Verify Python tools + skill installation.
- *   uninstall [--ai <client>]      Remove the Lumo skill (Python tools left intact).
+ *   init [--ai <client>] [--all] [--no-mcp] [--dev]
+ *   doctor
+ *   uninstall [--ai <client>] [--all]
  *
  * Supported AI clients in v0.1: claude, cursor, codex, generic.
  * Other clients can still consume Lumo via `npx skills add OneXeor-Dev/lumo`
  * or by pointing their MCP config at `lumo-mcp`.
+ *
+ * Argument parsing uses node:util parseArgs (Node ≥ 18.3) — zero external
+ * dependencies, so Socket.dev sees nothing to flag at the dependency tree.
  */
 
-import { Command } from "commander";
-import kleur from "kleur";
+import { parseArgs } from "node:util";
 
 import { initCommand } from "./commands/init.js";
 import { doctorCommand } from "./commands/doctor.js";
 import { uninstallCommand } from "./commands/uninstall.js";
+import { red } from "./lib/style.js";
+
+const VERSION = "0.0.4";
+
+const USAGE = `lumo — mobile UI/UX design intelligence installer (v${VERSION})
+
+Usage:
+  lumo init [options]         Install the Lumo skill into an AI coding assistant.
+  lumo doctor                 Verify Python tools, MCP server, and skill paths.
+  lumo uninstall [options]    Remove the Lumo skill from an AI client.
+  lumo --help                 Show this message.
+  lumo --version              Print the installer version.
+
+init options:
+  -a, --ai <client>           claude | cursor | codex | generic (asks if omitted)
+      --all                   Install into every supported client at once.
+      --no-mcp                Skip registering the MCP server (skill-only).
+      --dev                   Install from the current git clone (contributors).
+
+uninstall options:
+  -a, --ai <client>           Which client to remove from (asks if omitted).
+      --all                   Remove from every supported client at once.
+`;
+
+function parseFlags(argv) {
+  // node:util parseArgs cannot do subcommands natively; we extract the
+  // first positional ourselves, then run parseArgs on the rest.
+  // parseArgs also doesn't recognise '--no-flag' as the negation of
+  // 'flag', so we translate manually before passing it on.
+  const [cmd, ...rawRest] = argv;
+  let mcpExplicitlyOff = false;
+  const rest = rawRest.filter((a) => {
+    if (a === "--no-mcp") {
+      mcpExplicitlyOff = true;
+      return false;
+    }
+    return true;
+  });
+
+  const { values } = parseArgs({
+    args: rest,
+    allowPositionals: false,
+    strict: true,
+    options: {
+      ai: { type: "string", short: "a" },
+      all: { type: "boolean", default: false },
+      mcp: { type: "boolean", default: true },
+      dev: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", short: "V", default: false },
+    },
+  });
+  if (mcpExplicitlyOff) values.mcp = false;
+  return { cmd, values };
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+
+  // No subcommand → top-level help / version.
+  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (argv[0] === "--version" || argv[0] === "-V") {
+    process.stdout.write(`${VERSION}\n`);
+    return 0;
+  }
+
+  let parsed;
+  try {
+    parsed = parseFlags(argv);
+  } catch (err) {
+    process.stderr.write(red(`✗ ${err.message ?? err}\n`));
+    process.stderr.write("\nRun `lumo --help` for usage.\n");
+    return 2;
+  }
+
+  const { cmd, values } = parsed;
+
+  if (values.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  switch (cmd) {
+    case "init":
+      await initCommand(values);
+      return 0;
+    case "doctor":
+      await doctorCommand();
+      return 0;
+    case "uninstall":
+      await uninstallCommand(values);
+      return 0;
+    default:
+      process.stderr.write(red(`✗ unknown subcommand: ${cmd}\n`));
+      process.stderr.write("\nRun `lumo --help` for usage.\n");
+      return 2;
+  }
+}
 
-const program = new Command();
-
-program
-  .name("lumo")
-  .description(
-    "Mobile UI/UX design intelligence — WCAG / parity / cognitive-science checks " +
-      "for Jetpack Compose, Android XML, SwiftUI, UIKit."
-  )
-  .version("0.0.2");
-
-program
-  .command("init")
-  .description("Install the Lumo skill into an AI coding assistant.")
-  .option(
-    "-a, --ai <client>",
-    "Target client: claude | cursor | codex | generic (asks interactively if omitted)"
-  )
-  .option("--all", "Install into every supported client at once.")
-  .option("--no-mcp", "Skip registering the MCP server (skill-only install).")
-  .option("--dev", "Install from the current git clone instead of pip (for contributors).")
-  .action(initCommand);
-
-program
-  .command("doctor")
-  .description("Verify Python tools, MCP server, and skill installation paths.")
-  .action(doctorCommand);
-
-program
-  .command("uninstall")
-  .description("Remove the Lumo skill from an AI client (Python tools left intact).")
-  .option("-a, --ai <client>", "Which client to remove from (asks interactively if omitted)")
-  .option("--all", "Remove from every supported client at once.")
-  .action(uninstallCommand);
-
-program.parseAsync(process.argv).catch((err) => {
-  console.error(kleur.red(`\n✗ ${err.message ?? err}`));
-  process.exit(1);
-});
+main()
+  .then((code) => process.exit(code ?? 0))
+  .catch((err) => {
+    process.stderr.write(red(`\n✗ ${err.message ?? err}\n`));
+    process.exit(1);
+  });

package/src/lib/prompt.js

@@ -0,0 +1,79 @@
+/**
+ * Tiny terminal `select` prompt. Self-contained replacement for `prompts`.
+ *
+ * Why: Socket.dev flagged `prompts` because it depends on `sisteransi`
+ * which hasn't been updated in 5+ years (Maintenance alert). Our usage
+ * is one select-from-list prompt; rolling our own keeps the package
+ * dependency tree empty and removes the unmaintained-transitive alert.
+ *
+ * Renders a numbered list, waits for one keystroke or a typed number
+ * followed by Enter. Plays well with raw-mode TTY. Falls back to
+ * answer 0 (first option) when stdin is not a TTY (CI, piping).
+ *
+ * Returns the value of the chosen option, or undefined if the user
+ * aborted with Ctrl-C / Ctrl-D / Esc.
+ */
+
+import readline from "node:readline";
+
+import { bold, cyan, dim } from "./style.js";
+
+/**
+ * @typedef {object} Choice
+ * @property {string} title
+ * @property {any} value
+ */
+
+/**
+ * @param {object} opts
+ * @param {string} opts.message
+ * @param {Choice[]} opts.choices
+ * @param {number} [opts.initial]
+ * @returns {Promise<any | undefined>}
+ */
+export function select({ message, choices, initial = 0 }) {
+  return new Promise((resolve) => {
+    const stdout = process.stdout;
+    const stdin = process.stdin;
+
+    // Non-interactive: pick the initial choice and move on.
+    if (!stdin.isTTY) {
+      stdout.write(`${cyan("?")} ${message} ${dim(`(non-interactive, picking ${choices[initial].title})`)}\n`);
+      resolve(choices[initial].value);
+      return;
+    }
+
+    stdout.write(`${cyan("?")} ${bold(message)}\n`);
+    for (let i = 0; i < choices.length; i++) {
+      const marker = i === initial ? cyan("›") : " ";
+      stdout.write(`  ${marker} ${i + 1}. ${choices[i].title}\n`);
+    }
+    stdout.write(dim(`  (use 1-${choices.length} then Enter, or Ctrl-C to abort)\n`));
+
+    const rl = readline.createInterface({
+      input: stdin,
+      output: stdout,
+      terminal: true,
+    });
+
+    rl.question("> ", (raw) => {
+      rl.close();
+      const trimmed = raw.trim();
+      if (trimmed === "") {
+        resolve(choices[initial].value);
+        return;
+      }
+      const idx = Number.parseInt(trimmed, 10) - 1;
+      if (!Number.isInteger(idx) || idx < 0 || idx >= choices.length) {
+        resolve(undefined);
+        return;
+      }
+      resolve(choices[idx].value);
+    });
+
+    rl.on("SIGINT", () => {
+      rl.close();
+      resolve(undefined);
+    });
+  });
+}

package/src/lib/style.js

@@ -0,0 +1,28 @@
+/**
+ * Tiny ANSI styling helper. Self-contained replacement for `kleur`.
+ *
+ * Why: Socket.dev flags packages whose dependency tree contains
+ * environment-variable access (kleur reads NO_COLOR / FORCE_COLOR
+ * which is legitimate but raises a supply-chain risk signal). We use
+ * exactly four colours in the installer; rolling our own keeps
+ * `dependencies: {}` empty.
+ *
+ * Colours are emitted unconditionally. If you need NO_COLOR support
+ * later, gate the prefix strings on `process.env.NO_COLOR` here in
+ * one place.
+ */
+
+const ESC = "\x1b";
+
+function wrap(open, close) {
+  return (text) => `${ESC}[${open}m${text}${ESC}[${close}m`;
+}
+
+export const cyan = wrap(36, 39);
+export const green = wrap(32, 39);
+export const yellow = wrap(33, 39);
+export const red = wrap(31, 39);
+export const dim = wrap(2, 22);
+export const bold = wrap(1, 22);
+
+/** Compose: `bold(cyan("text"))` works because every fn is `text -> text`. */