arkaos 2.22.1 → 2.25.0

package/installer/migrations/v3_path_schema.js

@@ -0,0 +1,109 @@
+/**
+ * Migration: profile.json schema v2 → v3 (paths-portability, v2.23.0).
+ *
+ * Adds the structured `projectRoots: string[]` and `reposRoot: string`
+ * fields to every existing profile.json so the new path_resolver token
+ * substitution can run for the 20K-user installed base.
+ *
+ * Strategy:
+ *   1. Skip if `version === "3"` or `projectRoots` already present (idempotent).
+ *   2. Otherwise:
+ *        - Write `.bak-<unix-timestamp>` backup beside the profile.
+ *        - Parse `projectsDir` free-text to extract absolute paths.
+ *        - Default to ["~/Herd","~/Work","~/AIProjects"] if parsing returns 0.
+ *        - reposRoot = first match containing "AIProjects", else "~/AIProjects".
+ *        - Atomic write (temp file + rename) with version: "3" and migrated_at.
+ *        - Log to ~/.arkaos/logs/migrate.log.
+ *
+ * Safe for concurrent invocations: the backup filename includes the
+ * timestamp, atomic rename prevents partial writes, and the idempotent
+ * guard means a second run is a no-op.
+ *
+ * Contract documented in core/specs/SPEC-paths-portability.md (PR1 v2.23.0).
+ */
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const DEFAULT_PROJECT_ROOTS = ["~/Herd", "~/Work", "~/AIProjects"];
+const DEFAULT_REPOS_ROOT = "~/AIProjects";
+
+export function migrateProfileSchemaV3({ profilePath, logPath } = {}) {
+  const profile = profilePath || join(homedir(), ".arkaos", "profile.json");
+  const log = logPath || join(homedir(), ".arkaos", "logs", "migrate.log");
+
+  if (!existsSync(profile)) {
+    return { skipped: true, reason: "profile.json absent" };
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(profile, "utf8"));
+  } catch (err) {
+    return { skipped: true, reason: `parse error: ${err.message}` };
+  }
+
+  if (raw.version === "3" || Array.isArray(raw.projectRoots)) {
+    return { skipped: true, reason: "already migrated" };
+  }
+
+  const projectRoots = parseProjectsDirText(raw.projectsDir || "");
+  const reposRoot =
+    projectRoots.find((r) => r.includes("AIProjects")) || DEFAULT_REPOS_ROOT;
+
+  const migrated = {
+    ...raw,
+    version: "3",
+    projectRoots,
+    reposRoot,
+    migrated_at: new Date().toISOString(),
+  };
+
+  const backup = `${profile}.bak-${Math.floor(Date.now() / 1000)}`;
+  writeFileSync(backup, readFileSync(profile, "utf8"));
+
+  const tmp = `${profile}.tmp`;
+  writeFileSync(tmp, JSON.stringify(migrated, null, 2));
+  renameSync(tmp, profile);
+
+  writeLog(log, projectRoots, reposRoot);
+
+  return {
+    migrated: true,
+    projectRoots,
+    reposRoot,
+    backup,
+  };
+}
+
+export function parseProjectsDirText(text) {
+  if (!text) return [...DEFAULT_PROJECT_ROOTS];
+  const posix = /(?:\/Users|\/home)\/\S+?\/(?:Herd|Work|AIProjects|code|repos)/g;
+  const windows = /[A-Z]:\\Users\\[^\s\\]+\\(?:Herd|Work|AIProjects|code|repos)/g;
+  const found = [
+    ...(text.match(posix) || []),
+    ...(text.match(windows) || []),
+  ];
+  return found.length > 0 ? found : [...DEFAULT_PROJECT_ROOTS];
+}
+
+function writeLog(logPath, projectRoots, reposRoot) {
+  try {
+    mkdirSync(dirname(logPath), { recursive: true });
+    const line =
+      `[arka:migrated] ${new Date().toISOString()} ` +
+      `profile.json schema v2 → v3 (` +
+      `${projectRoots.length} roots, reposRoot=${reposRoot})\n`;
+    appendFileSync(logPath, line);
+  } catch {
+    // Log failure should never block migration.
+  }
+}

package/installer/package-manager.js

@@ -0,0 +1,191 @@
+/**
+ * Cross-OS package manager abstraction for the ArkaOS installer.
+ *
+ * Centralises detection of brew (macOS), winget/choco (Windows) and
+ * apt/snap (Linux) so install/update flows can either run a non-sudo
+ * install themselves or return a copy-paste command for the user.
+ *
+ * **Never invokes sudo automatically.** When sudo is required (apt /
+ * snap on Linux, winget without elevation), `installViaPackageManager`
+ * returns `{ needsSudo: true, command }` and the caller is expected
+ * to print the command for the user to run. This keeps the installer
+ * headless-safe — it must not surprise a CI job with a password prompt.
+ *
+ * See core/specs/SPEC-installer-cross-os.md (PR2 v2.24.0).
+ */
+
+import { execSync } from "node:child_process";
+import { platform } from "node:os";
+import { IS_WINDOWS } from "./platform.js";
+
+const MAC = "darwin";
+const LINUX = "linux";
+
+/**
+ * Detect the highest-priority package manager available on this host.
+ *
+ * Priority order:
+ *   macOS:   brew
+ *   Linux:   apt > snap (apt for generic packages; snap preferred for
+ *            Obsidian because its tarball is classic-confined)
+ *   Windows: winget > choco
+ *
+ * Returns the canonical name string or null when nothing is available.
+ */
+export function detectPackageManager() {
+  const candidates = preferredCandidates();
+  for (const name of candidates) {
+    if (hasCommand(name)) return name;
+  }
+  return null;
+}
+
+/**
+ * Return every package manager available on this host, in priority order.
+ * Useful for callers that need a different manager per package (e.g.
+ * snap for Obsidian on a host that also has apt for Node).
+ */
+export function detectAllPackageManagers() {
+  return preferredCandidates().filter((name) => hasCommand(name));
+}
+
+/**
+ * Build the install command for a package on a given manager, without
+ * executing it. Useful for `formatSudoInstructions` and for dry-run paths.
+ */
+export function buildInstallCommand(manager, pkg) {
+  switch (manager) {
+    case "brew":
+      return pkg.startsWith("cask:")
+        ? `brew install --cask ${pkg.slice(5)}`
+        : `brew install ${pkg}`;
+    case "apt":
+      return `sudo apt update && sudo apt install -y ${pkg}`;
+    case "snap":
+      return pkg.endsWith(":classic")
+        ? `sudo snap install ${pkg.slice(0, -8)} --classic`
+        : `sudo snap install ${pkg}`;
+    case "winget":
+      return `winget install --id ${pkg} --silent --accept-source-agreements --accept-package-agreements`;
+    case "choco":
+      return `choco install ${pkg} -y`;
+    default:
+      return "";
+  }
+}
+
+/**
+ * Whether a manager needs sudo (or Windows elevation) for install.
+ * brew on macOS is intentionally not sudo-gated (Homebrew runs as the user).
+ */
+export function managerNeedsSudo(manager) {
+  return manager === "apt" || manager === "snap";
+}
+
+/**
+ * Attempt a non-sudo install. When the chosen manager requires sudo
+ * we never invoke it ourselves — the caller surfaces the command to
+ * the user. Returns a structured result the caller can react to.
+ */
+export function installViaPackageManager(pkg, options = {}) {
+  const manager = options.manager || detectPackageManager();
+  if (!manager) {
+    return {
+      success: false,
+      manager: null,
+      command: "",
+      needsSudo: false,
+      installed: false,
+      error: "no_package_manager",
+      fallbackUrl: options.fallbackUrl || null,
+    };
+  }
+
+  const command = buildInstallCommand(manager, pkg);
+  const needsSudo = managerNeedsSudo(manager);
+
+  if (needsSudo) {
+    return {
+      success: true,
+      manager,
+      command,
+      needsSudo: true,
+      installed: false,
+      error: null,
+    };
+  }
+
+  if (options.dryRun) {
+    return {
+      success: true,
+      manager,
+      command,
+      needsSudo: false,
+      installed: false,
+      error: null,
+    };
+  }
+
+  try {
+    execSync(command, { stdio: "inherit" });
+    return {
+      success: true,
+      manager,
+      command,
+      needsSudo: false,
+      installed: true,
+      error: null,
+    };
+  } catch (err) {
+    return {
+      success: false,
+      manager,
+      command,
+      needsSudo: false,
+      installed: false,
+      error: err?.message || "install_failed",
+    };
+  }
+}
+
+/**
+ * Format an array of sudo install commands into a copy-paste block.
+ * Used by ensureSystemTools to print a single, friendly block when
+ * several packages need privileged install on Linux.
+ */
+export function formatSudoInstructions(commands) {
+  if (!commands || commands.length === 0) return "";
+  const unique = [...new Set(commands.filter(Boolean))];
+  if (unique.length === 0) return "";
+  const lines = [
+    "",
+    "  To finish setup, please run these commands:",
+    "",
+    ...unique.map((c) => `    ${c}`),
+    "",
+    "  Then re-run: npx arkaos install",
+    "",
+  ];
+  return lines.join("\n");
+}
+
+function preferredCandidates() {
+  const os = platform();
+  if (os === MAC) return ["brew"];
+  if (os === LINUX) return ["apt", "snap"];
+  if (IS_WINDOWS) return ["winget", "choco"];
+  return [];
+}
+
+function hasCommand(name) {
+  const finder = IS_WINDOWS ? "where" : "command -v";
+  try {
+    execSync(`${finder} ${name}`, {
+      stdio: ["ignore", "ignore", "ignore"],
+      shell: !IS_WINDOWS,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/installer/path-resolver.js

@@ -0,0 +1,124 @@
+/**
+ * Path template resolver for the ArkaOS installer (Node.js side).
+ *
+ * Mirrors core/runtime/path_resolver.py just enough to substitute
+ * ${VAULT_PATH}, ${ARKA_OS_REPOS}, ${PROJECT_ROOTS}, ${GIT_HOST}, ${HOME}
+ * inside SKILL.md, cognition prompts and other markdown that the installer
+ * copies to the user's ~/.claude/skills/arka/ tree or ~/.arkaos/.
+ *
+ * Source files contain templates so the arka-os repo stays portable across
+ * the 20K user base. The installer rewrites tokens at copy-time so each
+ * user's installation has concrete paths.
+ *
+ * The Python module is the single source of truth for the substitution
+ * contract. Keep this file in sync. See core/specs/SPEC-paths-portability.md.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const TOKEN_PATTERN = /\$\{([A-Z_]+)\}/g;
+const DEFAULT_PROJECT_ROOTS = ["~/Herd", "~/Work", "~/AIProjects"];
+const DEFAULT_REPOS_ROOT = "~/AIProjects";
+const DEFAULT_GIT_HOST = "github.com";
+
+let _profileCache = null;
+
+function profilePath() {
+  return join(homedir(), ".arkaos", "profile.json");
+}
+
+export function loadProfile({ refresh = false } = {}) {
+  if (_profileCache && !refresh) return _profileCache;
+
+  const path = profilePath();
+  if (!existsSync(path)) {
+    // Installer can be invoked before profile.json exists (first install).
+    // Caller decides whether to treat that as fatal.
+    return null;
+  }
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    throw new Error(
+      `~/.arkaos/profile.json could not be parsed (${err.message}). ` +
+      `Run /arka setup to repair, or restore from a .bak file.`
+    );
+  }
+
+  const vaultPath = raw.vaultPath || raw.vault_path || "";
+  const reposRoot = raw.reposRoot || raw.repos_root || DEFAULT_REPOS_ROOT;
+  const projectRoots = Array.isArray(raw.projectRoots) && raw.projectRoots.length
+    ? raw.projectRoots
+    : deriveProjectRoots(raw.projectsDir || "");
+
+  _profileCache = {
+    version: String(raw.version || "2"),
+    vaultPath,
+    reposRoot,
+    projectRoots,
+    raw,
+  };
+  return _profileCache;
+}
+
+export function resetCache() {
+  _profileCache = null;
+}
+
+export function resolveString(template, options = {}) {
+  if (typeof template !== "string" || !template.includes("${")) return template;
+  const profile = options.profile || loadProfile();
+  return template.replace(TOKEN_PATTERN, (match, name) =>
+    resolveToken(name, match, profile)
+  );
+}
+
+export function resolveFile(srcPath, dstPath, options = {}) {
+  const content = readFileSync(srcPath, "utf8");
+  const resolved = resolveString(content, options);
+  writeFileSync(dstPath, resolved, "utf8");
+}
+
+function resolveToken(name, original, profile) {
+  if (name === "HOME") return homedir();
+  if (name === "GIT_HOST") {
+    return envOr("ARKAOS_GIT_HOST", DEFAULT_GIT_HOST);
+  }
+  if (name === "VAULT_PATH") {
+    const envValue = envOr("ARKAOS_VAULT_PATH", envOr("ARKAOS_VAULT", ""));
+    if (envValue) return envValue;
+    return profile?.vaultPath || original;
+  }
+  if (name === "ARKA_OS_REPOS") {
+    const envValue = envOr("ARKAOS_REPOS_ROOT", "");
+    if (envValue) return envValue;
+    return profile?.reposRoot || original;
+  }
+  if (name === "PROJECT_ROOTS") {
+    const envValue = envOr("ARKAOS_PROJECT_ROOTS", "");
+    if (envValue) return envValue;
+    const roots = profile?.projectRoots || DEFAULT_PROJECT_ROOTS;
+    const sep = process.platform === "win32" ? ";" : ":";
+    return roots.join(sep);
+  }
+  return original;
+}
+
+function envOr(name, fallback) {
+  const value = process.env[name];
+  return value && value.length > 0 ? value : fallback;
+}
+
+function deriveProjectRoots(projectsDirText) {
+  if (!projectsDirText) return [...DEFAULT_PROJECT_ROOTS];
+  const posix = /(?:\/Users|\/home)\/\S+?\/(?:Herd|Work|AIProjects|code|repos)/g;
+  const windows = /[A-Z]:\\Users\\[^\s\\]+\\(?:Herd|Work|AIProjects|code|repos)/g;
+  const found = [
+    ...(projectsDirText.match(posix) || []),
+    ...(projectsDirText.match(windows) || []),
+  ];
+  return found.length > 0 ? found : [...DEFAULT_PROJECT_ROOTS];
+}

package/installer/system-tools.js

@@ -0,0 +1,243 @@
+/**
+ * Cross-OS system-tool guarantor for the ArkaOS installer.
+ *
+ * Validates that the three external dependencies ArkaOS needs at runtime
+ * — Obsidian, Node.js ≥ 20, Python ≥ 3.12 — are present. Tools that can
+ * be installed without sudo (brew on macOS, winget on Windows) are
+ * installed automatically. Tools that need sudo (apt/snap on Linux) get
+ * a copy-paste command surfaced via `sudoCommands`.
+ *
+ * Idempotent: tools already at an acceptable version are no-ops.
+ *
+ * Spec: core/specs/SPEC-installer-cross-os.md (PR2 v2.24.0).
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { platform } from "node:os";
+import { IS_WINDOWS, CMD_FINDER } from "./platform.js";
+import {
+  buildInstallCommand,
+  detectAllPackageManagers,
+  detectPackageManager,
+  installViaPackageManager,
+  managerNeedsSudo,
+} from "./package-manager.js";
+
+const NODE_MIN_MAJOR = 20;
+const PYTHON_MIN = { major: 3, minor: 12 };
+
+const OBSIDIAN_PACKAGE = {
+  brew: "cask:obsidian",
+  snap: "obsidian:classic",
+  winget: "Obsidian.Obsidian",
+  choco: "obsidian",
+};
+
+const NODE_PACKAGE = {
+  brew: "node",
+  apt: "nodejs",
+  winget: "OpenJS.NodeJS",
+  choco: "nodejs",
+};
+
+const OBSIDIAN_FALLBACK_URL = "https://obsidian.md/download";
+const NODE_FALLBACK_URL = "https://nodejs.org/en/download";
+const PYTHON_FALLBACK_URL = "https://www.python.org/downloads/";
+
+/**
+ * Validate every required tool, install what can be installed without
+ * sudo, and collect copy-paste commands for the ones that can't.
+ */
+export function ensureSystemTools(options = {}) {
+  if (options.skipSystem) {
+    return {
+      skipped: true,
+      obsidian: null,
+      node: null,
+      python: null,
+      sudoCommands: [],
+    };
+  }
+
+  const obsidian = ensureTool("obsidian", checkObsidian, OBSIDIAN_PACKAGE, OBSIDIAN_FALLBACK_URL, options);
+  const node = ensureTool("node", checkNode, NODE_PACKAGE, NODE_FALLBACK_URL, options);
+  const python = checkPython();  // never auto-install Python — leave to OS
+
+  const sudoCommands = [obsidian, node]
+    .filter((t) => t?.needsSudo && t.suggestedCommand)
+    .map((t) => t.suggestedCommand);
+
+  if (python.needsAction !== "none" && python.suggestedCommand) {
+    sudoCommands.push(python.suggestedCommand);
+  }
+
+  return { skipped: false, obsidian, node, python, sudoCommands };
+}
+
+/**
+ * Cheap presence + version check for Obsidian. Looks for the binary
+ * via OS-native finder and falls back to known install paths.
+ */
+export function checkObsidian() {
+  const location = findBinary("obsidian") || findObsidianAppPath();
+  if (location) {
+    return {
+      name: "obsidian",
+      installed: true,
+      location,
+      needsAction: "none",
+    };
+  }
+  const suggested = buildSuggestedInstall(OBSIDIAN_PACKAGE, OBSIDIAN_FALLBACK_URL);
+  return {
+    name: "obsidian",
+    installed: false,
+    needsAction: "install",
+    suggestedCommand: suggested.command,
+    needsSudo: suggested.needsSudo,
+    fallbackUrl: suggested.fallbackUrl,
+  };
+}
+
+export function checkNode() {
+  const location = findBinary("node");
+  if (!location) {
+    const suggested = buildSuggestedInstall(NODE_PACKAGE, NODE_FALLBACK_URL);
+    return {
+      name: "node",
+      installed: false,
+      needsAction: "install",
+      suggestedCommand: suggested.command,
+      needsSudo: suggested.needsSudo,
+      fallbackUrl: suggested.fallbackUrl,
+    };
+  }
+  const version = readNodeVersion();
+  const major = version ? Number(version.split(".")[0]) : 0;
+  if (major >= NODE_MIN_MAJOR) {
+    return { name: "node", installed: true, location, version, needsAction: "none" };
+  }
+  const suggested = buildSuggestedInstall(NODE_PACKAGE, NODE_FALLBACK_URL);
+  return {
+    name: "node",
+    installed: true,
+    location,
+    version,
+    needsAction: "upgrade",
+    suggestedCommand: suggested.command,
+    needsSudo: suggested.needsSudo,
+    fallbackUrl: suggested.fallbackUrl,
+  };
+}
+
+export function checkPython() {
+  const candidates = IS_WINDOWS ? ["python", "py"] : ["python3", "python3.12", "python3.13"];
+  for (const cmd of candidates) {
+    const location = findBinary(cmd);
+    if (!location) continue;
+    const version = readVersion(`${cmd} --version`);
+    const ok = versionAtLeast(version, PYTHON_MIN.major, PYTHON_MIN.minor);
+    if (ok) {
+      return { name: "python", installed: true, location, version, needsAction: "none" };
+    }
+  }
+  return {
+    name: "python",
+    installed: false,
+    needsAction: "install",
+    suggestedCommand: `Install Python ${PYTHON_MIN.major}.${PYTHON_MIN.minor}+ from ${PYTHON_FALLBACK_URL}`,
+    needsSudo: false,
+    fallbackUrl: PYTHON_FALLBACK_URL,
+  };
+}
+
+function ensureTool(name, checkFn, packageMap, fallbackUrl, options) {
+  const status = checkFn();
+  if (status.needsAction === "none") return status;
+
+  const manager = detectPackageManager();
+  if (!manager || !packageMap[manager]) {
+    return { ...status, fallbackUrl };
+  }
+
+  if (managerNeedsSudo(manager)) {
+    return {
+      ...status,
+      suggestedCommand: buildInstallCommand(manager, packageMap[manager]),
+      needsSudo: true,
+    };
+  }
+
+  if (options.dryRun) return status;
+
+  const result = installViaPackageManager(packageMap[manager], {
+    manager,
+    fallbackUrl,
+  });
+  if (result.installed) {
+    return { ...checkFn(), justInstalled: true };
+  }
+  return { ...status, error: result.error };
+}
+
+function buildSuggestedInstall(packageMap, fallbackUrl) {
+  const managers = detectAllPackageManagers();
+  for (const m of managers) {
+    if (packageMap[m]) {
+      return {
+        command: buildInstallCommand(m, packageMap[m]),
+        needsSudo: managerNeedsSudo(m),
+        fallbackUrl,
+      };
+    }
+  }
+  return { command: `Download from ${fallbackUrl}`, needsSudo: false, fallbackUrl };
+}
+
+function findBinary(name) {
+  try {
+    const out = execSync(`${CMD_FINDER} ${name}`, {
+      stdio: ["ignore", "pipe", "ignore"],
+    }).toString().trim().split(/\r?\n/)[0];
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+function findObsidianAppPath() {
+  if (platform() === "darwin") {
+    const mac = "/Applications/Obsidian.app";
+    if (existsSync(mac)) return mac;
+  }
+  if (IS_WINDOWS) {
+    const localApp = process.env.LOCALAPPDATA;
+    if (localApp) {
+      const candidate = `${localApp}\\Obsidian\\Obsidian.exe`;
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+function readNodeVersion() {
+  return readVersion("node --version");
+}
+
+function readVersion(command) {
+  try {
+    const out = execSync(command, { stdio: ["ignore", "pipe", "ignore"] }).toString();
+    const match = out.match(/(\d+\.\d+(?:\.\d+)?)/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+function versionAtLeast(version, major, minor) {
+  if (!version) return false;
+  const parts = version.split(".").map((n) => Number(n) || 0);
+  if (parts[0] !== major) return parts[0] > major;
+  return parts[1] >= minor;
+}