@nanhara/hara 0.121.1 → 0.122.1

package/dist/org/projects.js

@@ -0,0 +1,347 @@
+// Global agent index — ~/.hara/projects.json registers canonical project homes. The registry is private,
+// atomically replaced, and guarded across processes because gateway/desktop/CLI may update it concurrently.
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { loadRoles, loadGlobalRoles } from "./roles.js";
+const PROJECT_NAME = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/;
+const sleepCell = new Int32Array(new SharedArrayBuffer(4));
+const LOCK_ATTEMPTS = 500;
+const LOCK_WAIT_MS = 10;
+function haraDir() {
+    const dir = join(homedir(), ".hara");
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        /* best effort on non-POSIX filesystems */
+    }
+    return dir;
+}
+const projectsFile = () => join(haraDir(), "projects.json");
+/** Handles are case-insensitive and form the left side of `project:agent`; canonical storage is lowercase. */
+export function canonicalProjectName(value) {
+    if (typeof value !== "string")
+        return null;
+    const name = value.trim().toLowerCase();
+    return PROJECT_NAME.test(name) ? name : null;
+}
+/** Existing paths resolve symlinks so one project cannot be registered twice through aliases. */
+export function canonicalProjectPath(value, requireDirectory = false) {
+    if (typeof value !== "string" || !value.trim() || !isAbsolute(value))
+        return null;
+    const absolute = resolve(value);
+    try {
+        if (requireDirectory && !statSync(absolute).isDirectory())
+            return null;
+        return realpathSync.native(absolute);
+    }
+    catch {
+        return requireDirectory ? null : absolute;
+    }
+}
+function readLock(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return Number.isInteger(parsed?.pid) && parsed.pid > 0 && typeof parsed?.token === "string" && parsed.token
+            ? { pid: parsed.pid, token: parsed.token }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error?.code === "EPERM";
+    }
+}
+function writeExclusive(path, record) {
+    let fd;
+    try {
+        fd = openSync(path, "wx", 0o600);
+        writeFileSync(fd, JSON.stringify(record), "utf8");
+        fsyncSync(fd);
+    }
+    catch (error) {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+                fd = undefined;
+            }
+            finally {
+                rmSync(path, { force: true });
+            }
+        }
+        throw error;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function withProjectsLock(fn) {
+    const file = projectsFile();
+    const lock = `${file}.lock`;
+    const reclaim = `${lock}.reclaim`;
+    let claim;
+    for (let attempt = 0; attempt < LOCK_ATTEMPTS; attempt++) {
+        if (existsSync(reclaim)) {
+            const stale = readLock(reclaim);
+            if (stale && !pidAlive(stale.pid)) {
+                const current = readLock(reclaim);
+                if (current?.pid === stale.pid && current.token === stale.token && !pidAlive(current.pid)) {
+                    rmSync(reclaim, { force: true });
+                    continue;
+                }
+            }
+            Atomics.wait(sleepCell, 0, 0, LOCK_WAIT_MS);
+            continue;
+        }
+        const candidate = { pid: process.pid, token: randomUUID() };
+        try {
+            writeExclusive(lock, candidate);
+            claim = candidate;
+            break;
+        }
+        catch (error) {
+            if (error?.code !== "EEXIST")
+                throw error;
+        }
+        const held = readLock(lock);
+        if (held && !pidAlive(held.pid)) {
+            const guard = { pid: process.pid, token: randomUUID() };
+            try {
+                writeExclusive(reclaim, guard);
+                const current = readLock(lock);
+                if (current?.pid === held.pid && current.token === held.token && !pidAlive(current.pid))
+                    rmSync(lock);
+            }
+            catch {
+                // Another writer is reclaiming, or the evidence is malformed. Never fail open.
+            }
+            finally {
+                const currentGuard = readLock(reclaim);
+                if (currentGuard?.pid === process.pid && currentGuard.token === guard.token)
+                    rmSync(reclaim, { force: true });
+            }
+        }
+        Atomics.wait(sleepCell, 0, 0, LOCK_WAIT_MS);
+    }
+    if (!claim)
+        throw new Error("projects registry is busy; retry the operation");
+    try {
+        return fn();
+    }
+    finally {
+        const current = readLock(lock);
+        if (current?.pid === process.pid && current.token === claim.token)
+            rmSync(lock, { force: true });
+    }
+}
+function parseProjects(raw, strict) {
+    const parsed = JSON.parse(raw);
+    const source = Array.isArray(parsed) ? parsed : parsed?.projects;
+    if (!Array.isArray(source))
+        throw new Error("projects registry must contain a projects array");
+    const out = [];
+    const names = new Set();
+    const paths = new Set();
+    for (const value of source) {
+        const name = canonicalProjectName(value?.name);
+        const path = canonicalProjectPath(value?.path);
+        if (!name || !path || names.has(name) || paths.has(path)) {
+            if (strict)
+                throw new Error("projects registry contains invalid or duplicate entries");
+            continue;
+        }
+        names.add(name);
+        paths.add(path);
+        out.push({ name, path });
+    }
+    return out;
+}
+function loadProjectsUnlocked(strict) {
+    const file = projectsFile();
+    if (!existsSync(file))
+        return [];
+    try {
+        return parseProjects(readFileSync(file, "utf8"), strict);
+    }
+    catch (error) {
+        if (strict)
+            throw error;
+        return [];
+    }
+}
+export function loadProjects() {
+    return loadProjectsUnlocked(false);
+}
+function atomicSave(list) {
+    const file = projectsFile();
+    const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    let fd;
+    try {
+        fd = openSync(tmp, "wx", 0o600);
+        writeFileSync(fd, JSON.stringify({ projects: list }, null, 2) + "\n", "utf8");
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+        renameSync(tmp, file);
+        try {
+            chmodSync(file, 0o600);
+        }
+        catch {
+            /* best effort on non-POSIX filesystems */
+        }
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+        rmSync(tmp, { force: true });
+    }
+}
+function normalizeProjectList(list) {
+    if (!Array.isArray(list))
+        throw new Error("projects must be an array");
+    const normalized = list.map((value) => {
+        const name = canonicalProjectName(value?.name);
+        const path = canonicalProjectPath(value?.path);
+        if (!name || !path)
+            throw new Error("project entries require a valid name and absolute path");
+        return { name, path };
+    });
+    if (new Set(normalized.map((p) => p.name)).size !== normalized.length || new Set(normalized.map((p) => p.path)).size !== normalized.length) {
+        throw new Error("project names and paths must be unique");
+    }
+    return normalized;
+}
+export function saveProjects(list) {
+    withProjectsLock(() => atomicSave(normalizeProjectList(list)));
+}
+export function addProject(nameInput, pathInput) {
+    const name = canonicalProjectName(nameInput);
+    if (!name)
+        return "invalid project name: use 1-64 lowercase letters, numbers, '.', '_' or '-'";
+    const path = canonicalProjectPath(pathInput, true);
+    if (!path)
+        return `path does not exist or is not a directory: ${pathInput}`;
+    try {
+        return withProjectsLock(() => {
+            const list = loadProjectsUnlocked(true);
+            const alias = list.find((p) => p.path === path && p.name !== name);
+            if (alias)
+                return `path is already registered as '${alias.name}': ${path}`;
+            const next = list.filter((p) => p.name !== name);
+            next.push({ name, path });
+            atomicSave(next);
+            return null;
+        });
+    }
+    catch (error) {
+        return `projects registry: ${error instanceof Error ? error.message : String(error)}`;
+    }
+}
+export function removeProject(nameInput) {
+    const name = canonicalProjectName(nameInput);
+    if (!name)
+        return false;
+    return withProjectsLock(() => {
+        const list = loadProjectsUnlocked(true);
+        const next = list.filter((p) => p.name !== name);
+        if (next.length === list.length)
+            return false;
+        atomicSave(next);
+        return true;
+    });
+}
+function sameList(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    if (a.length !== b.length)
+        return false;
+    const left = [...a].sort();
+    const right = [...b].sort();
+    return left.every((value, i) => value === right[i]);
+}
+/** Project roles with the same prompt can still intentionally override model/routing/tool policy. */
+function sameRoleDefinition(a, b) {
+    return (a.id === b.id &&
+        a.description === b.description &&
+        a.system === b.system &&
+        a.model === b.model &&
+        sameList(a.owns, b.owns) &&
+        sameList(a.rejects, b.rejects) &&
+        sameList(a.allowTools, b.allowTools) &&
+        sameList(a.denyTools, b.denyTools) &&
+        a.readOnly === b.readOnly);
+}
+/** Build the global index: inherited globals are listed once; any project override gets its qualified home. */
+export function buildAgentsIndex() {
+    const globals = loadGlobalRoles();
+    const globalById = new Map(globals.map((role) => [role.id, role]));
+    const out = globals.map((role) => ({ name: role.id, description: role.description, home: "" }));
+    for (const project of loadProjects()) {
+        let roles = [];
+        try {
+            roles = loadRoles(project.path);
+        }
+        catch {
+            continue;
+        }
+        for (const role of roles) {
+            const global = globalById.get(role.id);
+            if (global && sameRoleDefinition(global, role))
+                continue;
+            out.push({ name: role.id, description: role.description, home: project.path, project: project.name });
+        }
+    }
+    return out;
+}
+/** Resolve `global:agent`, `project:agent`, or a bare name.
+ *
+ * Bare names normally prefer the global definition, then a unique project match. Callers that already
+ * have a working directory (the chat gateway, for example) may pass it as `preferredHome`; a matching
+ * project override then wins before the global fallback. This makes `/agent reviewer` do the local thing
+ * while keeping registry-wide, context-free lookups deterministic. */
+export function resolveAgent(refInput, preferredHome) {
+    if (typeof refInput !== "string")
+        return null;
+    const ref = refInput.trim();
+    const index = buildAgentsIndex();
+    const separator = ref.indexOf(":");
+    if (separator > 0) {
+        const namespace = ref.slice(0, separator).trim().toLowerCase();
+        const name = ref.slice(separator + 1).trim();
+        if (namespace === "global") {
+            if (!name || name.includes(":"))
+                return null;
+            return index.find((entry) => !entry.project && entry.name === name) ?? null;
+        }
+        const project = canonicalProjectName(namespace);
+        if (!project || !name || name.includes(":"))
+            return null;
+        return index.find((entry) => entry.project === project && entry.name === name) ?? null;
+    }
+    const hits = index.filter((entry) => entry.name === ref);
+    if (!hits.length)
+        return null;
+    if (hits.length === 1)
+        return hits[0];
+    if (preferredHome) {
+        const preferred = canonicalProjectPath(preferredHome);
+        const local = preferred ? hits.find((entry) => !!entry.project && entry.home === preferred) : undefined;
+        if (local)
+            return local;
+    }
+    const global = hits.find((entry) => !entry.project);
+    if (global)
+        return global;
+    return { ambiguous: hits };
+}