arkaos 2.22.1 → 2.28.0

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;
+}

package/installer/update.js

@@ -6,6 +6,7 @@ import { ensureVenv, getArkaosPython, pipInstall } from "./python-resolver.js";
 import { getRuntimeConfig } from "./detect-runtime.js";
 import { loadAdapter } from "./index.js";
 import { migrateUserData, printMigrationReport } from "./migrate-user-data.js";
+import { resolveFile } from "./path-resolver.js";
 import { IS_WINDOWS, HOOK_EXT } from "./platform.js";
 import { fileURLToPath } from "node:url";
 
@@ -277,7 +278,7 @@ export async function update() {
   const skillDest = join(skillsBase, "arka");
   mkdirSync(skillDest, { recursive: true });
   if (existsSync(skillSrc)) {
-    copyFileSync(skillSrc, join(skillDest, "SKILL.md"));
+    safeResolveMarkdown(skillSrc, join(skillDest, "SKILL.md"));
     writeFileSync(join(skillDest, ".repo-path"), ARKAOS_ROOT);
     writeFileSync(join(skillDest, "VERSION"), VERSION);
     console.log("         ✓ /arka skill updated");
@@ -309,7 +310,7 @@ export async function update() {
     if (!existsSync(md)) return false;
     const dest = join(skillsBase, arkaName);
     mkdirSync(dest, { recursive: true });
-    copyFileSync(md, join(dest, "SKILL.md"));
+    safeResolveMarkdown(md, join(dest, "SKILL.md"));
     copyResources(src, dest);
     return true;
   };
@@ -476,6 +477,20 @@ function ensureDir(dir) {
   }
 }
 
+/**
+ * Copy a markdown file, substituting ${VAR} tokens from path-resolver when
+ * a profile.json is available. Falls back to plain copy on any error so a
+ * missing profile during first install never blocks deployment of the file
+ * itself; the agent / Python runtime will resolve later when profile lands.
+ */
+function safeResolveMarkdown(src, dst) {
+  try {
+    resolveFile(src, dst);
+  } catch {
+    copyFileSync(src, dst);
+  }
+}
+
 /**
  * Copy v2 hook state files from the legacy ~/.arka-os/ directory into
  * the canonical ~/.arkaos/ runtime directory. Safe to run every update:
@@ -563,7 +578,13 @@ function updateCognitiveScheduler(installDir, arkaosRoot) {
   const promptsSrc = join(arkaosRoot, "config", "cognition", "prompts");
   if (existsSync(promptsSrc)) {
     for (const f of readdirSync(promptsSrc)) {
-      copyFileSync(join(promptsSrc, f), join(promptsDir, f));
+      const src = join(promptsSrc, f);
+      const dst = join(promptsDir, f);
+      if (f.endsWith(".md")) {
+        safeResolveMarkdown(src, dst);
+      } else {
+        copyFileSync(src, dst);
+      }
     }
     console.log("         \u2713 Cognitive prompts updated");
   }

package/knowledge/obsidian-config.json

@@ -3,7 +3,7 @@
     "description": "ARKA OS — Obsidian Vault Configuration",
     "notes": "ALL department output goes to this Obsidian vault. Conventions match existing vault format."
   },
-  "vault_path": "/Users/andreagroferreira/Documents/Personal",
+  "vault_path": "${VAULT_PATH}",
   "paths": {
     "personas": "Personas",
     "sources_videos": "Sources/Videos",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "2.22.1",
+  "version": "2.28.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "2.22.1"
+version = "2.28.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}