arkaos 2.22.0 → 2.25.0

package/departments/dev/skills/scaffold/SKILL.md

@@ -16,7 +16,7 @@ Create new projects from real git repositories with full automation: dependencie
 
 | Command | Git Repository | Stack |
 |---------|---------------|-------|
-| `/dev scaffold laravel <name>` | `git@andreagroferreira:andreagroferreira/laravel-starter-kit.git` | Laravel + Herd |
+| `/dev scaffold laravel <name>` | `https://${GIT_HOST}/laravel/laravel.git` (override with `ARKAOS_LARAVEL_STARTER_REPO` env) | Laravel + Herd |
 | `/dev scaffold nuxt-saas <name>` | `https://github.com/nuxt-ui-templates/dashboard.git` | Nuxt 3 Dashboard |
 | `/dev scaffold nuxt-landing <name>` | `https://github.com/nuxt-ui-templates/landing.git` | Nuxt 3 Landing |
 | `/dev scaffold nuxt-docs <name>` | `https://github.com/nuxt-ui-templates/docs.git` | Nuxt 3 Docs |
@@ -136,7 +136,7 @@ cp PROJECT.md "$ARKA_OS/projects/<name>/PROJECT.md"
 
 Create pages in the Obsidian vault:
 
-**Main page:** `Documents/Personal/Projects/<name>/Home.md`
+**Main page:** `${VAULT_PATH}/Projects/<name>/Home.md`
 ```markdown
 ---
 type: project
@@ -165,7 +165,7 @@ tags:
 - *Part of the [[Projects MOC]]*
 ```
 
-**Architecture page:** `Documents/Personal/Projects/<name>/Architecture/decisions.md`
+**Architecture page:** `${VAULT_PATH}/Projects/<name>/Architecture/decisions.md`
 ```markdown
 ---
 type: adr-log
@@ -242,7 +242,7 @@ Both directories get their respective dependencies installed, and the full-stack
 
 ## Error Handling
 
-- If `git clone` fails: check SSH keys (`git@andreagroferreira:` for private repos)
+- If `git clone` fails: check SSH keys / repo access permissions for the configured `${GIT_HOST}`
 - If `composer install` fails: check PHP version (`php -v`, need 8.3+)
 - If `pnpm install` fails: check Node version (`node -v`, need 18+)
 - If `herd link` fails: check Herd is installed and running

package/departments/kb/skills/knowledge/SKILL.md

@@ -22,7 +22,7 @@ Dynamic knowledge acquisition and management system. Learn from YouTube videos,
 
 ## Obsidian Configuration
 
-- **Vault:** `/Users/andreagroferreira/Documents/Personal`
+- **Vault:** `${VAULT_PATH}`
 - **Config:** Read `knowledge/obsidian-config.json` for full path/convention details
 - **MCP:** Use Obsidian MCP when available, fallback to direct file Write
 - **Conventions:** YAML frontmatter, wikilinks `[[]]`, MOC references, kebab-case tags

package/departments/ops/skills/operations/SKILL.md

@@ -56,7 +56,7 @@ Every phase transition announced to the user.
 
 ## Obsidian Output
 
-Vault root: `/Users/andreagroferreira/Documents/Personal`
+Vault root: `${VAULT_PATH}`
 
 | Content | Path |
 |---------|------|

package/installer/cli.js

@@ -19,6 +19,7 @@ const { values, positionals } = parseArgs({
     runtime: { type: "string", short: "r" },
     path: { type: "string", short: "p" },
     force: { type: "boolean", short: "f" },
+    "no-system": { type: "boolean" },
   },
   allowPositionals: true,
   strict: false,
@@ -74,7 +75,7 @@ async function main() {
   switch (command) {
     case "install":
       const runtime = values.runtime || await detectRuntime();
-      await install({ runtime, path: values.path, force: values.force });
+      await install({ runtime, path: values.path, force: values.force, skipSystem: values["no-system"] });
       break;
 
     case "init": {

package/installer/doctor.js

@@ -4,6 +4,7 @@ import { homedir } from "node:os";
 import { execSync } from "node:child_process";
 import { getArkaosPython, getVenvPython, canImportCore, getRepoRoot } from "./python-resolver.js";
 import { IS_WINDOWS, HOOK_EXT, CMD_FINDER } from "./platform.js";
+import { checkNode, checkObsidian } from "./system-tools.js";
 
 const INSTALL_DIR = join(homedir(), ".arkaos");
 
@@ -124,6 +125,53 @@ const checks = [
     check: () => existsSync(join(INSTALL_DIR, "schedules.yaml")),
     fix: () => "Run: npx arkaos@latest update (deploys scheduler)",
   },
+  {
+    name: "obsidian",
+    description: "Obsidian app installed",
+    severity: "warn",
+    check: () => checkObsidian().installed,
+    fix: () => {
+      const s = checkObsidian();
+      if (s.suggestedCommand) return `Run: ${s.suggestedCommand}`;
+      return `Install Obsidian from ${s.fallbackUrl || "https://obsidian.md/download"}`;
+    },
+  },
+  {
+    name: "node",
+    description: "Node.js 20+ available",
+    severity: "warn",
+    check: () => checkNode().needsAction === "none",
+    fix: () => {
+      const s = checkNode();
+      if (s.suggestedCommand) return `Run: ${s.suggestedCommand}`;
+      return `Install Node.js 20+ from ${s.fallbackUrl || "https://nodejs.org/en/download"}`;
+    },
+  },
+  {
+    name: "claude-code-version",
+    description: "Claude Code 2.1.122+ (ToolSearch late-binding + hooks isolation)",
+    severity: "warn",
+    check: () => {
+      if (!commandExists("claude")) return true; // no claude binary = not applicable
+      try {
+        const out = execSync("claude --version 2>&1", {
+          stdio: "pipe",
+        }).toString().trim();
+        const m = out.match(/(\d+)\.(\d+)\.(\d+)/);
+        if (!m) return false;
+        const [, maj, min, patch] = m.map(Number);
+        // 2.1.122 minimum
+        if (maj > 2) return true;
+        if (maj < 2) return false;
+        if (min > 1) return true;
+        if (min < 1) return false;
+        return patch >= 122;
+      } catch {
+        return false;
+      }
+    },
+    fix: () => "Upgrade Claude Code: npm install -g @anthropic-ai/claude-code@latest",
+  },
 ];
 
 // ─── Windows-only checks ───────────────────────────────────────────────

package/installer/index.js

@@ -12,7 +12,7 @@ const __dirname = dirname(__filename);
 const ARKAOS_ROOT = resolve(__dirname, "..");
 const VERSION = JSON.parse(readFileSync(join(ARKAOS_ROOT, "package.json"), "utf-8")).version;
 
-export async function install({ runtime, path, force }) {
+export async function install({ runtime, path, force, skipSystem }) {
   const startTime = Date.now();
   const config = getRuntimeConfig(runtime);
   const isUpgrade = existsSync(join(path || join(homedir(), ".arkaos"), "install-manifest.json"));
@@ -72,6 +72,31 @@ export async function install({ runtime, path, force }) {
     ok("No v1 installation found");
   }
 
+  // ═══ Step 2.5: Ensure system tools (Obsidian, Node ≥ 20, Python ≥ 3.12) ═══
+  // Wrapped in try/catch so a regression in system-tools.js cannot break a
+  // fresh `npx arkaos install` for the ~20K user base. We degrade to a warn
+  // and proceed to venv creation rather than exiting non-zero.
+  if (!skipSystem) {
+    try {
+      const { ensureSystemTools } = await import("./system-tools.js");
+      const { formatSudoInstructions } = await import("./package-manager.js");
+      const sys = ensureSystemTools({ skipSystem: false });
+      if (sys.sudoCommands && sys.sudoCommands.length > 0) {
+        console.log(formatSudoInstructions(sys.sudoCommands));
+      }
+      for (const tool of [sys.obsidian, sys.node]) {
+        if (!tool) continue;
+        if (tool.justInstalled) ok(`${tool.name} installed`);
+        else if (tool.needsAction === "none") ok(`${tool.name} ready`);
+        else warn(`${tool.name} ${tool.needsAction} — see commands above`);
+      }
+    } catch (err) {
+      warn(`System tool check failed: ${err.message}. Continuing without it.`);
+    }
+  } else {
+    warn("System tool checks skipped (--no-system)");
+  }
+
   // ═══ Step 3: Check Python + create venv ═══
   step(3, 14, "Checking Python 3.11+ and creating virtual environment...");
   const systemPython = findSystemPython();

package/installer/migrate-user-data.js

@@ -2,6 +2,8 @@ import { existsSync, mkdirSync, readdirSync, renameSync, statSync, writeFileSync
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+import { migrateProfileSchemaV3 } from "./migrations/v3_path_schema.js";
+
 const LEGACY_SKILLS_ROOT = join(homedir(), ".claude", "skills", "arka");
 const USER_DATA_ROOT = join(homedir(), ".arkaos");
 
@@ -28,8 +30,22 @@ export function migrateUserData({ dryRun = false } = {}) {
   const skipped = [...projectsResult.skipped, ...ecosystemsResult.skipped];
   const conflicts = [...projectsResult.conflicts, ...ecosystemsResult.conflicts];
 
+  let profileSchemaResult = null;
+  if (!dryRun) {
+    try {
+      profileSchemaResult = migrateProfileSchemaV3();
+      if (profileSchemaResult?.migrated) {
+        moved.push(
+          `profile.json schema v2 → v3 (${profileSchemaResult.projectRoots.length} roots)`
+        );
+      }
+    } catch (err) {
+      conflicts.push(`profile schema v3 migration failed: ${err.message}`);
+    }
+  }
+
   const logPath = writeReport({ moved, skipped, conflicts, dryRun });
-  return { moved, skipped, conflicts, logPath };
+  return { moved, skipped, conflicts, logPath, profileSchemaResult };
 }
 
 export function printMigrationReport(result) {

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