arkaos 4.34.0 → 4.36.0

package/installer/menubar.js

@@ -0,0 +1,262 @@
+/**
+ * ArkaOS menu bar launcher wiring (Foundation PR-5).
+ *
+ * Deploys bin/arka-menubar.py to the purge-proof ~/.arkaos/bin/ (the
+ * scheduler-daemon.py pattern — SNAPSHOT_DIRS does not ship bin/, and a
+ * launchd unit anchored at an npx cache dies on `npm cache clean`; the
+ * PR-1 QG blocker) and manages the io.wizardingcode.arkaos.menubar
+ * LaunchAgent.
+ *
+ * macOS-only by design (rumps is a macOS menu bar framework); every
+ * other platform reports { action: "unsupported" } gracefully. Default-on
+ * (operator decision, PR-5 Phase 0 — same posture as the PR-1 updater)
+ * with a persisted opt-out marker so `npx arkaos menubar disable`
+ * survives future updates. ESM, Node + Bun, no interactive prompts.
+ * Unit generation (`unitFor`) is pure so it is unit-tested without
+ * touching the OS (autoupdate.js precedent).
+ */
+
+import { execFileSync } from "node:child_process";
+import {
+  chmodSync, copyFileSync, existsSync, mkdirSync, rmSync, writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getArkaosPython } from "./python-resolver.js";
+
+export const MENUBAR_LABEL = "io.wizardingcode.arkaos.menubar";
+
+function defaultRepoRoot() {
+  return join(dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+/** XML-escape a value interpolated into plist content — `&` and `<`
+ *  are legal in macOS paths and would otherwise corrupt the plist into
+ *  an opaque `launchctl load` failure (QG M1). */
+export function xmlEscape(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+/** Pure: the opt-out marker path — written by disable(), honored by
+ *  ensureDefaultEnabled(). */
+export function optoutPath(home = homedir()) {
+  return join(home, ".arkaos", "menubar.optout");
+}
+
+/** Pure: where the menu bar script lives after deployment. */
+export function menubarScriptPath(home = homedir()) {
+  return join(home, ".arkaos", "bin", "arka-menubar.py");
+}
+
+/**
+ * Pure: the LaunchAgent plist for the menu bar app. macOS-only — throws
+ * on any other platform (callers catch and report "unsupported").
+ * KeepAlive is intentionally false: "Quit" must stick until next login;
+ * RunAtLoad brings it back at login. LimitLoadToSessionType=Aqua +
+ * ProcessType=Interactive mark it as a GUI agent (idiomatic launchd).
+ */
+export function unitFor(os, { home, pythonPath, scriptPath }) {
+  if (os !== "darwin") {
+    throw new Error(`menu bar launcher is macOS-only (got ${os})`);
+  }
+  const log = join(home, ".arkaos", "logs", "menubar.log");
+  // PATH: launchd defaults carry no node; ~/.arkaos/bin carries the arka
+  // wrappers. nvm/fnm installs still resolve through the app's own
+  // shutil.which guard, which logs instead of failing silently (QG M5).
+  const pathValue = `/opt/homebrew/bin:/usr/local/bin:${join(home, ".arkaos", "bin")}:/usr/bin:/bin:/usr/sbin:/sbin`;
+  const content = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${MENUBAR_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xmlEscape(pythonPath)}</string>
+    <string>${xmlEscape(scriptPath)}</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${xmlEscape(pathValue)}</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <false/>
+  <key>LimitLoadToSessionType</key>
+  <string>Aqua</string>
+  <key>ProcessType</key>
+  <string>Interactive</string>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(log)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(log)}</string>
+</dict>
+</plist>
+`;
+  return {
+    kind: "launchd",
+    files: [
+      {
+        path: join(home, "Library", "LaunchAgents", `${MENUBAR_LABEL}.plist`),
+        content,
+      },
+    ],
+  };
+}
+
+/**
+ * Copy bin/arka-menubar.py into ~/.arkaos/bin/ (mirrors the
+ * scheduler-daemon.py deployment). Returns true when deployed.
+ */
+export function deployMenubarScript({ repoRoot = defaultRepoRoot(), home = homedir() } = {}) {
+  const src = join(repoRoot, "bin", "arka-menubar.py");
+  if (!existsSync(src)) return false;
+  const dest = menubarScriptPath(home);
+  mkdirSync(dirname(dest), { recursive: true });
+  copyFileSync(src, dest);
+  try { chmodSync(dest, 0o755); } catch { /* NTFS/ACL no-op */ }
+  return true;
+}
+
+// Shell-free exec (QG M1): argv array via execFileSync — a home path
+// containing quotes/backticks/$() can never escape into a shell.
+function _silent(file, args) {
+  try {
+    execFileSync(file, args, { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function enable({ repoRoot = defaultRepoRoot(), home = homedir() } = {}) {
+  if (process.platform !== "darwin") {
+    return { ok: false, path: "", message: "Menu bar launcher is macOS-only." };
+  }
+  if (!deployMenubarScript({ repoRoot, home })) {
+    return { ok: false, path: "", message: "bin/arka-menubar.py not found in the package." };
+  }
+  const pythonPath = getArkaosPython() || "/usr/bin/python3";
+  const unit = unitFor(process.platform, {
+    home,
+    pythonPath,
+    scriptPath: menubarScriptPath(home),
+  });
+  mkdirSync(join(home, ".arkaos", "logs"), { recursive: true });
+  for (const f of unit.files) {
+    mkdirSync(dirname(f.path), { recursive: true });
+    writeFileSync(f.path, f.content, "utf8");
+  }
+  if (existsSync(optoutPath(home))) rmSync(optoutPath(home));
+  const mainPath = unit.files[0].path;
+  _silent("launchctl", ["unload", mainPath]);
+  if (!_silent("launchctl", ["load", "-w", mainPath])) {
+    return { ok: false, path: mainPath,
+      message: "Plist written but launchctl load failed — it will still start at next login." };
+  }
+  return { ok: true, path: mainPath,
+    message: "Menu bar launcher enabled (look for ▲ in the macOS menu bar)." };
+}
+
+export function disable({ home = homedir() } = {}) {
+  if (process.platform !== "darwin") {
+    return { ok: false, path: "", message: "Menu bar launcher is macOS-only." };
+  }
+  const plist = join(home, "Library", "LaunchAgents", `${MENUBAR_LABEL}.plist`);
+  _silent("launchctl", ["unload", plist]);
+  if (existsSync(plist)) rmSync(plist);
+  // Persisted opt-out: future `npx arkaos update` runs must not re-enable.
+  mkdirSync(join(home, ".arkaos"), { recursive: true });
+  writeFileSync(optoutPath(home), new Date().toISOString(), "utf8");
+  return { ok: true, path: plist, message: "Menu bar launcher disabled (opt-out persisted)." };
+}
+
+export function status({ home = homedir(), platform = process.platform } = {}) {
+  if (platform !== "darwin") {
+    return { installed: false, supported: false, optout: false,
+      message: "menu bar launcher is macOS-only" };
+  }
+  const plist = join(home, "Library", "LaunchAgents", `${MENUBAR_LABEL}.plist`);
+  return {
+    installed: existsSync(plist) && existsSync(menubarScriptPath(home)),
+    supported: true,
+    optout: existsSync(optoutPath(home)),
+    kind: "launchd",
+    path: plist,
+  };
+}
+
+/**
+ * Doctor probe (QG M2): file presence alone cannot detect the primary
+ * failure mode (agent files present, process dead at import). Composes
+ * status() with a live `launchctl list <label>` query (exit 0 iff the
+ * job is loaded in this session). `exec` and `platform` are injectable
+ * so every branch is testable without touching launchd.
+ */
+export function menubarHealthy({
+  home = homedir(),
+  platform = process.platform,
+  exec = (file, args) => _silent(file, args),
+} = {}) {
+  if (platform !== "darwin") return true; // not applicable
+  // platform flows down — status() reading the REAL process.platform
+  // here broke the injectable branches on the Linux CI runner (the
+  // opt-out branch returned false off-macOS).
+  const s = status({ home, platform });
+  // A persisted opt-out is a healthy, chosen state — not a warning.
+  if (s.optout) return true;
+  if (!s.installed) return false;
+  return exec("launchctl", ["list", MENUBAR_LABEL]);
+}
+
+/** Default-on wiring for install/update flows: enable unless the user
+ *  opted out or the platform is unsupported. Never throws. */
+export function ensureDefaultEnabled({ repoRoot = defaultRepoRoot(), home = homedir() } = {}) {
+  const s = status({ home });
+  if (!s.supported) return { action: "unsupported" };
+  if (s.optout) return { action: "optout" };
+  if (s.installed) {
+    // Refresh script + plist content in place (paths may change between
+    // versions). Deliberately no unload/load here: the refreshed unit
+    // only takes effect at next login — a reload storm on every update
+    // would flicker the running app (QG minor, documented honestly).
+    try {
+      deployMenubarScript({ repoRoot, home });
+      const pythonPath = getArkaosPython() || "/usr/bin/python3";
+      const unit = unitFor(process.platform, {
+        home, pythonPath, scriptPath: menubarScriptPath(home),
+      });
+      for (const f of unit.files) writeFileSync(f.path, f.content, "utf8");
+    } catch { /* refresh is best-effort */ }
+    return { action: "already-enabled" };
+  }
+  const r = enable({ repoRoot, home });
+  return { action: r.ok ? "enabled" : "partial", message: r.message };
+}
+
+export async function menubar(args = []) {
+  const action = (args[0] || "status").toLowerCase();
+  if (action === "enable") {
+    const r = enable();
+    console.log(`  ${r.ok ? "✓" : "⚠"} ${r.message}${r.path ? `\n    ${r.path}` : ""}`);
+  } else if (action === "disable") {
+    const r = disable();
+    console.log(`  ${r.ok ? "✓" : "⚠"} ${r.message}`);
+  } else if (action === "status") {
+    const s = status();
+    if (!s.supported) console.log(`  Menu bar launcher not supported here: ${s.message}`);
+    else if (s.optout) console.log(`  Menu bar: DISABLED by user opt-out\n    (re-enable: npx arkaos menubar enable)`);
+    else console.log(`  Menu bar: ${s.installed ? "ENABLED" : "disabled"} (${s.kind})\n    ${s.path}`);
+  } else {
+    console.error(`  Unknown menubar action: ${action}. Use enable | disable | status.`);
+    process.exitCode = 1;
+  }
+}

package/installer/product-stats.js

@@ -0,0 +1,93 @@
+/**
+ * Product stats — derived at runtime, never hand-typed (Foundation PR-3
+ * QG minor; docs-as-code rule: counts come from the shipped artifacts).
+ *
+ * Sources (all ship in the npm tarball — see package.json "files"):
+ *   agents       knowledge/agents-registry-v2.json  → agents[].length
+ *   departments  departments/                        → directory count
+ *   skills       knowledge/skills-manifest.json      → skills map +
+ *                structural surface (main + hubs + meta) — the full
+ *                deployable skill surface installer/skill-deploy.js ships
+ *
+ * Contract: any missing/corrupt source yields null for THAT field only.
+ * Callers must omit the corresponding output line — an invented number
+ * is worse than no number.
+ */
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+export function readProductStats(repoRoot) {
+  return {
+    agents: countAgents(repoRoot),
+    departments: countDepartments(repoRoot),
+    skills: countSkills(repoRoot),
+  };
+}
+
+/**
+ * Render the summary lines for the install report. Null fields are
+ * omitted; when the department count is unavailable the agents line
+ * degrades to the bare count instead of inventing a denominator.
+ */
+export function productStatsLines(stats) {
+  const lines = [];
+  if (stats.agents !== null) {
+    lines.push(
+      stats.departments !== null
+        ? `Agents:      ${stats.agents} across ${stats.departments} departments`
+        : `Agents:      ${stats.agents}`,
+    );
+  }
+  if (stats.skills !== null) {
+    lines.push(`Skills:      ${stats.skills} backed by enterprise frameworks`);
+  }
+  return lines;
+}
+
+function countAgents(repoRoot) {
+  try {
+    const registry = JSON.parse(
+      readFileSync(join(repoRoot, "knowledge", "agents-registry-v2.json"), "utf-8"),
+    );
+    if (Array.isArray(registry.agents)) return registry.agents.length;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function countDepartments(repoRoot) {
+  try {
+    const base = join(repoRoot, "departments");
+    if (!existsSync(base)) return null;
+    const count = readdirSync(base, { withFileTypes: true }).filter((e) =>
+      e.isDirectory(),
+    ).length;
+    return count > 0 ? count : null;
+  } catch {
+    return null;
+  }
+}
+
+function countSkills(repoRoot) {
+  try {
+    const manifest = JSON.parse(
+      readFileSync(join(repoRoot, "knowledge", "skills-manifest.json"), "utf-8"),
+    );
+    const skills = manifest.skills;
+    if (!skills || typeof skills !== "object" || Array.isArray(skills)) {
+      return null;
+    }
+    let count = Object.keys(skills).length;
+    const structural = manifest.structural;
+    if (structural && typeof structural === "object") {
+      if (structural.main) count += 1;
+      if (Array.isArray(structural.hubs)) count += structural.hubs.length;
+      if (Array.isArray(structural.meta)) count += structural.meta.length;
+    }
+    return count;
+  } catch {
+    return null;
+  }
+}

package/installer/profile.js

@@ -0,0 +1,75 @@
+/**
+ * Install profiles — pure, testable helpers (Foundation PR-3).
+ *
+ * A profile names WHAT gets provisioned on a machine:
+ *
+ *   essential  venv, hooks, skills, dashboard, MCPs
+ *   complete   essential + litellm[proxy] + ffmpeg
+ *   local-ai   complete + Ollama + local execution model
+ *
+ * In PR-3 the chosen profile is only PERSISTED (profile.json,
+ * `installProfile` key) — provisioning of the extra tiers lands in
+ * PR-4. Keeping the record builder here (instead of inline in
+ * installer/index.js) makes the persistence contract unit-testable
+ * without touching the filesystem.
+ */
+
+export const INSTALL_PROFILES = ["essential", "complete", "local-ai"];
+
+export const DEFAULT_PROFILE = "essential";
+
+/** Human-readable hint per profile — single source for both wizards. */
+export const PROFILE_HINTS = {
+  essential: "venv, hooks, skills, dashboard, MCPs",
+  complete: "essential + litellm[proxy] + ffmpeg",
+  "local-ai": "complete + Ollama + local execution model",
+};
+
+/**
+ * Normalize a user-supplied profile value (CLI flag, profile.json field).
+ * Returns the canonical profile string, or null when invalid/empty so
+ * callers can distinguish "not provided" from "provided and valid".
+ */
+export function normalizeProfileFlag(value) {
+  if (typeof value !== "string") return null;
+  const v = value.trim().toLowerCase();
+  return INSTALL_PROFILES.includes(v) ? v : null;
+}
+
+/**
+ * Whether `current` covers `required` on the linear profile ladder
+ * (essential ⊂ complete ⊂ local-ai — the same chain the manifest's
+ * extends encodes). Invalid values degrade to the default profile.
+ */
+export function profileIncludes(current, required) {
+  const c = INSTALL_PROFILES.indexOf(normalizeProfileFlag(current) || DEFAULT_PROFILE);
+  const r = INSTALL_PROFILES.indexOf(normalizeProfileFlag(required) || DEFAULT_PROFILE);
+  return c >= r;
+}
+
+/**
+ * Build the profile.json record persisted by installer/index.js.
+ *
+ * Mirrors the object previously built inline in install() step 11, plus
+ * the `installProfile` key. `created` is preserved from the previous
+ * record when present (upgrade), `updated` is always now.
+ */
+export function buildProfileRecord(userConfig = {}, previousProfile = null) {
+  const prev =
+    previousProfile && typeof previousProfile === "object" ? previousProfile : {};
+  return {
+    version: "2",
+    language: userConfig.language,
+    market: userConfig.market,
+    role: userConfig.role,
+    company: userConfig.company,
+    projectsDir: userConfig.projectsDir,
+    vaultPath: userConfig.vaultPath,
+    installProfile:
+      normalizeProfileFlag(userConfig.installProfile) ||
+      normalizeProfileFlag(prev.installProfile) ||
+      DEFAULT_PROFILE,
+    created: prev.created || new Date().toISOString(),
+    updated: new Date().toISOString(),
+  };
+}