ework-aio 0.1.1 → 0.1.3

package/README.md

@@ -13,18 +13,56 @@ All-in-one installer for the **ework** self-hosted AI development stack:
 ## Quick start
 
 ```bash
-# 1. Make sure prerequisites are on PATH
-bun --version          # >= 1.1.0 — https://bun.sh
-opencode --version     # >= 1.14   — https://opencode.ai
-npm --version          # ships with bun or node
-systemctl --version    # this installer requires systemd
+npm install -g ework-aio && ework-aio install
+```
+
+That's the whole install. When it finishes it prints your login URL, operator login, and token.
+
+### Prerequisites
+
+The install command checks for these and aborts with a hint if any are missing:
 
-# 2. One-shot install
+| Tool        | Min ver | Install from                         |
+| ----------- | ------- | ------------------------------------ |
+| `bun`       | 1.1.0   | https://bun.sh                       |
+| `opencode`  | 1.14    | https://opencode.ai                  |
+| `npm`       | any     | ships with bun or node               |
+| `systemctl` | any     | systemd-based Linux                  |
+| `openssl`/`curl`/`jq`/`awk` | any | your distro package manager |
+
+### One-liner alternatives
+
+```bash
+# Run without installing globally (downloads + runs once)
 npx ework-aio install
-# or: npm install -g ework-aio && ework-aio install
+
+# If npm registry is slow on your machine, route through an HTTP proxy
+HTTPS_PROXY=http://127.0.0.1:7890 npm install -g ework-aio && ework-aio install
+
+# User-level install (no sudo) — uses ~/.local as npm prefix
+npm install -g ework-aio --prefix ~/.local && ework-aio install
 ```
 
-The installer prints your login URL and token when it finishes.
+### Why two steps?
+
+`npm install -g ework-aio` **only** lays down files: the bin launcher and the bash installer. It does **not** run the installer. The second `ework-aio install` step is what actually:
+
+- writes `.env` files with random tokens,
+- creates systemd units (user-level by default, system-level if you sudo),
+- starts services,
+- bootstraps the bot user,
+- edits `~/.config/opencode/opencode.json`.
+
+Keeping these in a separate, explicitly-invoked step is intentional:
+
+- **Privilege boundary.** `sudo npm install -g` runs as root; the install step runs as *you*. Folding them together would force system-level systemd units and root-owned files in `$HOME`.
+- **No surprise side-effects.** `npm install -g foo` should lay down files and stop. Creating services, generating tokens, editing your opencode config — that's invasive and belongs in a step you opted into.
+- **npm `--ignore-scripts`.** Many users / CI disable lifecycle scripts. Auto-installing via `postinstall` would silently no-op for them.
+- **`npm uninstall` reversibility.** Files outside npm's tracking (systemd units, `.env`, DBs, bot PAT) can't be cleaned by npm. Keeping them in a separate command means `npm uninstall -g ework-aio` does what people expect (removes files) and `ework-aio uninstall` does the rest.
+
+`bin/ework-aio` with no args defaults to `install`, so `npm install -g ework-aio && ework-aio` (no `install`) also works.
+
+---
 
 ## What it does
 

package/bin/install.sh

@@ -409,7 +409,32 @@ else
 fi
 
 # ─── Register opencode-ework plugin ────────────────────────────────────────
+# Safety: every edit writes to a temp file, validates with `jq -e .`, only
+# then atomically replaces the original. A timestamped .bak is always kept.
 mkdir -p "$(dirname "$OPENCODE_CFG")"
+
+json_edit() {
+  # $1 = file, $2 = jq program, $3 = expected JSON type (optional, e.g. "object").
+  # Writes to temp, validates (parses + optional type check), only then swaps.
+  # Backup at $file.bak.<epoch>.
+  local file="$1" prog="$2" expected="${3:-}" tmp
+  tmp=$(mktemp)
+  if ! jq "$prog" "$file" > "$tmp" 2>/dev/null; then
+    rm -f "$tmp"
+    die "jq edit failed on $file (program: $prog)"
+  fi
+  if ! jq -e . "$tmp" >/dev/null 2>&1; then
+    rm -f "$tmp"
+    die "jq edit produced invalid JSON on $file — aborted, original untouched"
+  fi
+  if [[ -n "$expected" ]] && ! jq -e "type == \"$expected\"" "$tmp" >/dev/null 2>&1; then
+    rm -f "$tmp"
+    die "jq edit produced wrong type on $file (expected $expected) — aborted, original untouched"
+  fi
+  cp "$file" "$file.bak.$(date +%s)"
+  mv "$tmp" "$file"
+}
+
 if [[ ! -f "$OPENCODE_CFG" ]]; then
   log "Writing $OPENCODE_CFG (registering opencode-ework plugin)"
   cat > "$OPENCODE_CFG" <<'EOF'
@@ -418,26 +443,26 @@ if [[ ! -f "$OPENCODE_CFG" ]]; then
   "plugin": ["opencode-ework@latest"]
 }
 EOF
-elif grep -qE '"opencode-ework(@latest)?"' "$OPENCODE_CFG"; then
-  if grep -q '"opencode-ework@latest"' "$OPENCODE_CFG"; then
-    ok "opencode-ework@latest already in $OPENCODE_CFG"
-  else
-    log "Upgrading opencode-ework → opencode-ework@latest in $OPENCODE_CFG"
-    cp "$OPENCODE_CFG" "$OPENCODE_CFG.bak.$(date +%s)"
-    tmp=$(mktemp)
-    jq '(.plugin // []) | map(if . == "opencode-ework" then "opencode-ework@latest" else . end)' \
-       "$OPENCODE_CFG" > "$tmp" && mv "$tmp" "$OPENCODE_CFG"
-    ok "Plugin upgraded (backup at $OPENCODE_CFG.bak.*)"
-  fi
+elif grep -q '"opencode-ework@latest"' "$OPENCODE_CFG"; then
+  ok "opencode-ework@latest already in $OPENCODE_CFG"
+elif grep -q '"opencode-ework"' "$OPENCODE_CFG"; then
+  log "Upgrading opencode-ework → opencode-ework@latest in $OPENCODE_CFG"
+  json_edit "$OPENCODE_CFG" \
+    '.plugin = ((.plugin // []) | map(if . == "opencode-ework" then "opencode-ework@latest" else . end))' \
+    object
+  ok "Plugin upgraded (backup at $OPENCODE_CFG.bak.*)"
 else
   log "Merging opencode-ework@latest into existing $OPENCODE_CFG"
-  cp "$OPENCODE_CFG" "$OPENCODE_CFG.bak.$(date +%s)"
-  tmp=$(mktemp)
-  jq 'if .plugin then .plugin += ["opencode-ework@latest"] else . + {plugin:["opencode-ework@latest"]} end' \
-     "$OPENCODE_CFG" > "$tmp" && mv "$tmp" "$OPENCODE_CFG"
+  json_edit "$OPENCODE_CFG" \
+    'if .plugin then .plugin += ["opencode-ework@latest"] else . + {plugin:["opencode-ework@latest"]} end' \
+    object
   ok "Plugin registered (backup at $OPENCODE_CFG.bak.*)"
 fi
 
+if ! jq -e 'type == "object"' "$OPENCODE_CFG" >/dev/null 2>&1; then
+  warn "$OPENCODE_CFG is not a JSON object — check $OPENCODE_CFG.bak.* for restore"
+fi
+
 # ─── Done ──────────────────────────────────────────────────────────────────
 hr
 ok "Install complete."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ework-aio",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "All-in-one installer for ework (issue tracker) + ework-daemon (AI bridge) + opencode-ework (plugin). One command: npm i -g ework-aio && ework-aio install.",
   "type": "module",
   "license": "MIT",
@@ -38,7 +38,8 @@
   },
   "scripts": {
     "start": "bun bin/ework-aio.js",
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "postinstall": "echo '\\n  ework-aio installed. Run \\033[1mework-aio install\\033[0m to set up services.\\n  Help: ework-aio --help\\n'"
   },
   "dependencies": {
     "ework-web": "^0.1.0",