@dotcomjack/grux 1.2.1

package/README.md

@@ -0,0 +1,79 @@
+# grux
+
+The one command front door to [Grux OS](https://gruxai.com).
+
+```sh
+npx grux
+```
+
+That finds Grux.app on your Mac, puts `grux` on your PATH, and hands you to the
+real command line. After the first run you can drop the `npx` and just type
+`grux`.
+
+## What this package is, and is not
+
+It is a **launcher**, about 200 lines, with **no dependencies**.
+
+Every actual command is the Swift binary that ships inside `Grux.app`, so there
+is one implementation of the grammar and no chance of two front doors drifting
+apart. This package never reimplements a command, never caches an answer, and
+never talks to the network.
+
+It does not download or install Grux. The command line lives inside the app
+bundle rather than beside it, so there is no separate artifact to fetch. If the
+app is not on your Mac, the launcher says so, prints the download link, and
+changes nothing.
+
+## Usage
+
+```sh
+npx grux                 # link, then run setup (or status when not a terminal)
+npx grux status          # anything else is passed straight through
+npx grux status --json   # including flags, verbatim
+npx grux --link-only     # just put grux on the PATH, run nothing
+```
+
+`--link-only` is the single flag this launcher consumes, and only as the first
+argument. Everything else reaches the Swift CLI untouched.
+
+## Exit codes
+
+The same four the Swift CLI uses, forwarded rather than reinvented.
+
+| Code | Meaning |
+|---|---|
+| 0 | Done. |
+| 1 | Failed. |
+| 2 | Waiting on you, on this Mac. Nothing any flag can do. |
+| 3 | Run `grux doctor`. |
+
+`npx grux` on a Mac with no Grux.app exits **2**, because installing it is
+something only you can do.
+
+## Where the link goes
+
+The first directory that is both writable by you and already on your `PATH`,
+preferring `~/.local/bin`, then `/opt/homebrew/bin`, then `/usr/local/bin`.
+
+It never uses `sudo`. An installer that asks for your password to place a
+symlink has taught you that Grux asks for passwords, and that habit costs more
+than the convenience is worth.
+
+If a file named `grux` is already there and it is not one of ours, the launcher
+refuses and tells you. It will not remove somebody else's program.
+
+## Environment
+
+| Variable | Effect |
+|---|---|
+| `GRUX_APP` | Use this bundle and no other. A miss is a miss, with no fallback. |
+| `NO_COLOR` | Honoured on presence, so `NO_COLOR=0` still means no colour. |
+
+## Requirements
+
+macOS 14 or later, and [Grux.app](https://github.com/dotcomjack/grux/releases/latest).
+Node 18 or later, which `npx` already implies.
+
+## License
+
+MIT.

package/bin/grux.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+//
+// The front door. `npx grux`.
+//
+// This package is a LAUNCHER, not a second command line. It owns exactly three
+// jobs: find Grux.app, put `grux` on your PATH, and get out of the way. Every
+// actual command is the Swift binary inside the app bundle, so there is one
+// implementation of the grammar and no chance of the two drifting.
+//
+// The one shim flag is `--link-only`, and it is only recognised as the first
+// argument. Everything else is passed through untouched, which is why
+// `npx grux status --json` behaves exactly like `grux status --json`.
+
+import { spawnSync } from 'node:child_process'
+import { locate, appVersion, RELEASES } from '../lib/locate.js'
+import { link, pathLineFor } from '../lib/link.js'
+import { out, err, fill, rail, row, accent, dim } from '../lib/ui.js'
+
+const DONE = 0
+const FAILED = 1
+const WAITING = 2
+
+function bail(code, lines) {
+  for (const l of lines) err(l)
+  process.exit(code)
+}
+
+function notMac() {
+  err(rail('LOOK'))
+  err(row('needed', 'Grux runs on macOS', 'Grux is a native Mac app and its command line talks to that app over a local socket, so there is nothing here for this platform to run.'))
+  err('')
+  err(fill(`This machine reports ${process.platform}.`, 2))
+  err('')
+  process.exit(FAILED)
+}
+
+function notInstalled() {
+  out(rail('LOOK'))
+  out(row('needed', 'Grux.app is not on this Mac', 'The command line ships inside the app bundle. It is not a separate download, so there is nothing this launcher can usefully install on its own.'))
+  out('')
+  out(fill('Download it, drag it to Applications, then run this again:', 2))
+  out('')
+  out('    ' + accent(RELEASES))
+  out('')
+  out(dim(fill('Nothing was changed on this Mac.', 2)))
+  out('')
+  process.exit(WAITING)
+}
+
+function main() {
+  if (process.platform !== 'darwin') notMac()
+
+  const argv = process.argv.slice(2)
+  const linkOnly = argv[0] === '--link-only'
+  const passthrough = linkOnly ? argv.slice(1) : argv
+
+  const found = locate()
+  if (!found) notInstalled()
+
+  // Linking is best effort and never fatal. A reader who cannot write to any
+  // PATH directory can still run every command through `npx grux`, so a
+  // failure here costs convenience and nothing else. Reporting it as a hard
+  // error would be the launcher lying about how much it matters.
+  let linked = null
+  let linkError = null
+  try {
+    linked = link(found.bin)
+  } catch (e) {
+    linkError = e
+  }
+
+  const quiet = passthrough.length > 0 && !linkOnly
+
+  if (!quiet) report(found, linked, linkError)
+
+  if (linkOnly) process.exit(linked ? DONE : FAILED)
+
+  // A terminal that cannot answer a question cannot be walked through setup,
+  // so the non interactive path lands on `status`, which states where you are
+  // and names the command that moves you. Same grammar, no hang.
+  const isTTY = process.stdin.isTTY === true && process.stdout.isTTY === true
+  const args = passthrough.length > 0
+    ? passthrough
+    : (isTTY ? ['setup'] : ['status', '--no-input'])
+
+  const r = spawnSync(found.bin, args, { stdio: 'inherit' })
+  if (r.error) {
+    bail(FAILED, ['', fill(`Could not run ${found.bin}: ${r.error.message}`, 2), ''])
+  }
+  process.exit(r.status === null ? FAILED : r.status)
+}
+
+function report(found, linked, linkError) {
+  out(rail('LOOK'))
+  const v = appVersion(found.app)
+  out(row('ready', `Grux.app${v ? '   ' + v : ''}`, found.app))
+
+  if (linked && linked.status === 'already') {
+    out(row('ready', 'grux is already on your PATH', linked.path))
+  } else if (linked) {
+    out(row('ready', linked.status === 'replaced' ? 'grux relinked' : 'grux is now on your PATH', linked.path))
+  } else {
+    out(row('optional', 'grux is not on your PATH', `Could not write a link: ${linkError && linkError.message}. Every command still works through "npx grux".`))
+  }
+
+  if (linked && linked.needsPathLine) {
+    out('')
+    out(fill(`${linked.dir} is not on your PATH. Add this to your shell profile to use "grux" directly:`, 2))
+    out('')
+    out('    ' + accent(pathLineFor(linked.dir)))
+  }
+  out('')
+}
+
+main()

package/lib/link.js

@@ -0,0 +1,108 @@
+import { existsSync, lstatSync, mkdirSync, readlinkSync, symlinkSync, unlinkSync, accessSync, constants } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, delimiter } from 'node:path'
+
+/**
+ * Directories we are willing to put the symlink in, best first.
+ *
+ * All three are conventional and none of them needs sudo when they are already
+ * yours. We never write to a directory owned by root: an installer that asks
+ * for a password to drop a symlink has taught the person that Grux asks for
+ * passwords, and that is a habit worth more than the convenience.
+ */
+export function targets() {
+  return [
+    join(homedir(), '.local', 'bin'),
+    '/opt/homebrew/bin',
+    '/usr/local/bin',
+  ]
+}
+
+const pathDirs = () => (process.env.PATH || '').split(delimiter).filter(Boolean)
+
+export const onPath = (dir) => pathDirs().includes(dir)
+
+function writable(dir) {
+  try {
+    accessSync(dir, constants.W_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Choose where the link goes.
+ *
+ * Preference order is deliberate: a directory that is BOTH already on PATH and
+ * writable wins, because linking there is complete on its own and needs no
+ * follow up from the reader. Only when nothing qualifies do we fall back to
+ * creating ~/.local/bin, which then owes the reader a PATH line.
+ */
+export function chooseTarget() {
+  const t = targets()
+  for (const dir of t) if (existsSync(dir) && writable(dir) && onPath(dir)) return { dir, needsPathLine: false }
+  for (const dir of t) if (existsSync(dir) && writable(dir)) return { dir, needsPathLine: true }
+  return { dir: t[0], needsPathLine: !onPath(t[0]), mustCreate: true }
+}
+
+/**
+ * @returns {{status: 'linked'|'already'|'replaced', path: string, needsPathLine: boolean, dir: string}}
+ * @throws {Error} when the directory cannot be created or the link cannot be written.
+ */
+export function link(binPath) {
+  const { dir, needsPathLine, mustCreate } = chooseTarget()
+  if (mustCreate || !existsSync(dir)) mkdirSync(dir, { recursive: true })
+
+  const dest = join(dir, 'grux')
+  let status = 'linked'
+
+  if (existsSync(dest) || isBrokenLink(dest)) {
+    // An existing `grux` that already points where we want is a no-op, and
+    // saying "linked" about it would be a small lie in the one place a reader
+    // is deciding whether anything happened.
+    if (isSymlinkTo(dest, binPath)) return { status: 'already', path: dest, needsPathLine, dir }
+
+    // Anything else at that name is replaced ONLY when it is a symlink we
+    // recognise as ours. A real file called `grux` belongs to somebody else
+    // and removing it is not ours to do.
+    if (!isOurSymlink(dest)) {
+      const e = new Error(`${dest} already exists and is not a Grux symlink`)
+      e.code = 'EOCCUPIED'
+      throw e
+    }
+    unlinkSync(dest)
+    status = 'replaced'
+  }
+
+  symlinkSync(binPath, dest)
+  return { status, path: dest, needsPathLine, dir }
+}
+
+function isBrokenLink(p) {
+  try {
+    return lstatSync(p).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+function isSymlinkTo(p, target) {
+  try {
+    return lstatSync(p).isSymbolicLink() && readlinkSync(p) === target
+  } catch {
+    return false
+  }
+}
+
+/** Ours means: a symlink pointing into a Grux.app bundle. */
+function isOurSymlink(p) {
+  try {
+    if (!lstatSync(p).isSymbolicLink()) return false
+    return readlinkSync(p).includes('Grux.app/Contents/MacOS/')
+  } catch {
+    return false
+  }
+}
+
+export const pathLineFor = (dir) => `export PATH="${dir}:$PATH"`

package/lib/locate.js

@@ -0,0 +1,86 @@
+import { existsSync, realpathSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+export const BUNDLE_ID = 'com.gruxai.grux'
+export const RELEASES = 'https://github.com/dotcomjack/grux/releases/latest'
+
+// The binary lives inside the app bundle. It is not a separate download and
+// there is deliberately no second copy of it anywhere, because two copies of a
+// client that speaks a versioned socket protocol is how you get a mismatch
+// that reports itself as a connection failure.
+const REL_BIN = 'Contents/MacOS/grux-cli'
+
+/**
+ * Every place a Grux.app can honestly be, cheapest lookup first.
+ * Spotlight is last because it is the only one that can be slow, and it is the
+ * only one that can find an app the person put somewhere unusual.
+ */
+export function candidates() {
+  // GRUX_APP is both a test seam and the honest answer for somebody who keeps
+  // their applications somewhere we do not guess. It is checked first and it
+  // is checked the same way as any other candidate: a bundle that does not
+  // carry the binary is still not a find, even when it was named explicitly.
+  const override = process.env.GRUX_APP
+  if (override) return [override]
+  return [
+    '/Applications/Grux.app',
+    join(homedir(), 'Applications', 'Grux.app'),
+  ]
+}
+
+// When the caller names an app explicitly, a miss is a miss. Falling back to
+// Spotlight there would quietly run a DIFFERENT build than the one asked for,
+// which is the single worst outcome for a launcher whose whole job is to be
+// unambiguous about which binary it started.
+export const overridden = () => Boolean(process.env.GRUX_APP)
+
+function viaSpotlight() {
+  try {
+    const stdout = execFileSync(
+      'mdfind',
+      [`kMDItemCFBundleIdentifier == '${BUNDLE_ID}'`],
+      { encoding: 'utf8', timeout: 4000, stdio: ['ignore', 'pipe', 'ignore'] },
+    )
+    return stdout.split('\n').map((s) => s.trim()).filter(Boolean)
+  } catch {
+    // Spotlight being off, indexing, or absent is not an error. It is one
+    // lookup of several and the caller has other ways to answer.
+    return []
+  }
+}
+
+/**
+ * @returns {{app: string, bin: string} | null} The first bundle that actually
+ * carries an executable CLI, or null. A bundle without the binary is NOT a
+ * find: it is a partial or an old build, and reporting it as located is how a
+ * caller ends up exec'ing a path that is not there.
+ */
+export function locate() {
+  const search = overridden() ? candidates() : [...candidates(), ...viaSpotlight()]
+  for (const app of search) {
+    const bin = join(app, REL_BIN)
+    if (existsSync(bin)) {
+      try {
+        return { app: realpathSync(app), bin: realpathSync(bin) }
+      } catch {
+        return { app, bin }
+      }
+    }
+  }
+  return null
+}
+
+/** The app's marketing version, or null when it cannot be read. */
+export function appVersion(app) {
+  try {
+    return execFileSync(
+      '/usr/libexec/PlistBuddy',
+      ['-c', 'Print :CFBundleShortVersionString', join(app, 'Contents/Info.plist')],
+      { encoding: 'utf8', timeout: 4000, stdio: ['ignore', 'pipe', 'ignore'] },
+    ).trim() || null
+  } catch {
+    return null
+  }
+}

package/lib/ui.js

@@ -0,0 +1,87 @@
+// Presentation only. No policy decisions live here.
+//
+// The rules this file exists to keep, all of them borrowed from the Swift CLI
+// so the two front doors cannot drift apart:
+//
+//   Colour is never the only carrier. Every state has a glyph and a word
+//   first, and the colour is decoration on top of something already legible.
+//   That is what makes NO_COLOR and a pipe safe rather than lossy.
+//
+//   NO_COLOR is honoured on PRESENCE, not on value. `NO_COLOR=0` still means
+//   no colour, because that is what the standard says and a reader who set it
+//   to zero was not asking for colour back.
+
+const ESC = '['
+
+const isTTY = process.stdout.isTTY === true
+
+// Presence, not truthiness. See above.
+const noColor = Object.prototype.hasOwnProperty.call(process.env, 'NO_COLOR')
+
+export const colorEnabled = isTTY && !noColor && process.env.TERM !== 'dumb'
+
+const wrap = (code) => (s) => (colorEnabled ? `${ESC}${code}m${s}${ESC}0m` : s)
+
+// One accent, and it means exactly one thing: "this is the thing to read".
+export const accent = wrap('38;5;179')
+export const dim = wrap('2')
+export const bold = wrap('1')
+
+// The glyph vocabulary is shared with the Swift CLI. Same word, same meaning,
+// in the app, in the CLI and here.
+export const GLYPH = {
+  ready: '+',
+  needed: '!',
+  waiting: '~',
+  optional: '-',
+}
+
+// A terminal narrower than 60 columns is a terminal we still owe a readable
+// answer to, so 60 is the floor rather than the assumption.
+export function width() {
+  const c = process.stdout.columns
+  if (!c || !Number.isFinite(c)) return 76
+  return Math.max(60, Math.min(c, 88))
+}
+
+/**
+ * Wrap `text` to the usable width, hanging continuation lines under the first
+ * character of the text rather than under the marker that introduced it. A
+ * wrapped bullet that lines up with the dash reads as a new item, which is a
+ * bug that has been shipped on this project before.
+ */
+export function fill(text, indent = 2, hanging = indent) {
+  const room = width() - indent
+  const words = String(text).split(/\s+/).filter(Boolean)
+  const lines = []
+  let line = ''
+  for (const w of words) {
+    if (line === '') line = w
+    else if (line.length + 1 + w.length <= room) line += ' ' + w
+    else { lines.push(line); line = w }
+  }
+  if (line !== '') lines.push(line)
+  return lines
+    .map((l, i) => ' '.repeat(i === 0 ? indent : hanging) + l)
+    .join('\n')
+}
+
+export const out = (s = '') => process.stdout.write(s + '\n')
+export const err = (s = '') => process.stderr.write(s + '\n')
+
+/** The six beat rail, with the current beat bracketed. Mirrors the Swift CLI. */
+const BEATS = ['LOOK', 'CHOOSE', 'COST', 'GRANT', 'HAND OFF', 'PROVE']
+export function rail(current) {
+  const cells = BEATS.map((b) => (b === current ? `[${b}]` : ` ${b} `))
+  const painted = colorEnabled
+    ? cells.map((c, i) => (BEATS[i] === current ? accent(c) : dim(c)))
+    : cells
+  return '\n  ' + painted.join(' ') + '\n'
+}
+
+/** A row whose glyph describes the SUBJECT of the row, not how it got here. */
+export function row(state, label, detail) {
+  const g = Object.prototype.hasOwnProperty.call(GLYPH, state) ? GLYPH[state] : ' '
+  const head = `  ${g} ${label}`
+  return detail ? `${head}\n${fill(detail, 6)}` : head
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@dotcomjack/grux",
+  "version": "1.2.1",
+  "description": "The one command front door to Grux OS. Finds the app, puts grux on your PATH, and hands you to the real command line.",
+  "bin": {
+    "grux": "bin/grux.js"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin"
+  ],
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "grux",
+    "macos",
+    "cli",
+    "agent",
+    "local-first"
+  ],
+  "homepage": "https://gruxai.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dotcomjack/grux.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dotcomjack/grux/issues"
+  },
+  "license": "MIT",
+  "author": "DotcomJack",
+  "publishConfig": {
+    "access": "public"
+  }
+}