@nanhara/hara 0.67.0 → 0.70.0

package/CHANGELOG.md

@@ -5,6 +5,57 @@ All notable changes to `@nanhara/hara`.
 > Versioning (pre-1.0, SemVer-style): the **minor** (middle) number bumps for a **new feature**; the
 > **patch** (last) number bumps for **optimizations/fixes of existing features**.
 
+## 0.70.0 — unreleased (B-end: devices pull their governed org-role bundle)
+
+- An enrolled device now **syncs its digital-employee roles from hara-control** — `GET {gateway}/v1/roles`
+  (Bearer device token) returns the governed bundle the control plane resolved for this device's
+  person/team, and hara materializes it into `~/.hara/org-roles/*.md`. This closes the B3 gap where the
+  server could resolve+govern roles but the CLI never consumed them (it only read local `.hara/roles/`).
+- **Precedence layer** (in `loadRoles`): `plugins < org(B-end push) < global < .claude/agents < project`
+  — the org baseline sits above third-party plugins, but a dev's own global/project roles still win, so
+  pushed roles are a managed default, not a lock. (Org policy can tighten this later.)
+- **Authoritative replace**: the org bundle owns `~/.hara/org-roles/` — each sync wipes and rewrites it,
+  so a server-side role revoke/rename actually removes the local file. A `_policy.json` sidecar carries
+  the org governance floor (model/tool/approval) for later enforcement.
+- Wired on `hara enroll` (reports the count) and best-effort in the background on startup when
+  `provider=hara-gateway` (alongside the heartbeat). Never throws / never blocks — returns 0 on any
+  failure or when not enrolled. snake_case wire fields (`allow_tools`/`deny_tools`) map to the CLI's
+  `allowTools`/`denyTools` frontmatter. New `syncOrgRoles()` in `src/org-fleet/enroll.ts` + test.
+
+## 0.69.1 — unreleased (@file expands inline, not appended at the bottom)
+
+- `@path` mentions now expand **in place** — the referenced file/dir content lands exactly where it's
+  written, so "compare `@a.ts` with `@b.ts`" reads in context instead of keeping the bare `@a.ts`
+  tokens and dumping both files in a block at the very end. A repeated mention keeps the bare `@path`
+  the second time (no double-inlining); a non-readable ref is left as typed. Labels ("Referenced file
+  `x`:") and the image/dir handling are unchanged — only the position moved.
+
+## 0.69.0 — unreleased (real local vector store via zvec)
+
+- Local semantic search now uses **zvec** (`@zvec/zvec`, an in-process native vector DB) for ANN
+  retrieval, replacing the brute-force-cosine scan as the query path. zvec was previously referenced
+  only in comments as the "scale-up path"; it's now actually wired (it ships a darwin-arm64/linux
+  prebuilt, added as an **optionalDependency**).
+- Design keeps the JSON store as the durable embedding cache + SSOT for hit text, and recomputes the
+  cosine **score from the JSON vectors** after zvec returns candidate ids — so ranking/threshold
+  semantics are byte-identical to before (no change to `hybrid.ts`), zvec just does fast candidate
+  retrieval. Build writes the zvec index alongside the JSON cache (`~/.hara/index/<name>.zvec`).
+- **Graceful fallback preserved**: if `@zvec/zvec` is absent or its native binding fails to load (a
+  platform with no prebuilt), `queryIndex` falls back to the JSON brute-force — so installs without
+  the binding keep working. Lexical remains the zero-dep floor when no embedder is configured at all.
+- New `src/search/zvec-store.ts` (lazy load · read-only open for queries · best-effort build) + test.
+
+## 0.68.0 — unreleased (run hara in Docker)
+
+- **Dockerfile** — run hara in a container against any mounted repo, no Node install needed, and as an
+  isolated/ephemeral environment (handy for CI). Multi-stage build → a slim runtime that still ships a
+  shell + `git` + `ripgrep` (the bash/search tools need them; a distroless image would break them).
+  `docker run --rm -v "$PWD:/workspace" -e HARA_API_KEY=… ghcr.io/hara-cli/hara -p "…"`.
+- **Release pipeline** now also builds + pushes a multi-arch (amd64/arm64) image to
+  `ghcr.io/hara-cli/hara` on a version tag, alongside the existing standalone binaries — so the Docker
+  and binary distributions stay in lockstep. (Single-binary distribution shipped in 0.60.0; this
+  rounds out "install hara any way you like": npm · binary · Docker.)
+
 ## 0.67.0 — unreleased (bounded parallel concurrency)
 
 - hara already runs work in parallel — fan-out **`agent`** sub-agents, concurrent read-kind tools in a turn,

package/README.md

@@ -31,6 +31,16 @@ curl -fsSL https://raw.githubusercontent.com/hara-cli/hara/main/install.sh | sh
 
 Tab completion (optional): `eval "$(hara completions zsh)"` in your `~/.zshrc` (or `bash`/`fish`).
 
+Or in **Docker** — run hara against any repo without installing Node, and as an isolated/ephemeral
+environment (handy for CI):
+
+```bash
+docker run --rm -v "$PWD:/workspace" -e HARA_API_KEY=sk-... ghcr.io/hara-cli/hara -p "summarize this repo"
+# interactive TUI:
+docker run --rm -it -v "$PWD:/workspace" -e HARA_API_KEY=sk-... ghcr.io/hara-cli/hara
+# or build it yourself: docker build -t hara . && docker run --rm -v "$PWD:/workspace" -e HARA_API_KEY=sk-... hara
+```
+
 Or from source:
 
 ```bash
@@ -233,7 +243,7 @@ turn, or **`/undo`** to revert the last edit. In-session **`/diff`**, **`/review
 
 ### Roadmap
 
-**Shipped:** ink TUI · plan mode · persistent memory + self-evolution · atomization planner · parallel plan atoms · **multi-role review chains** · parallel sub-agents · MCP client *and* server · **scheduled tasks (`hara cron`)** · **single-binary distribution** · `/compact` context management.
+**Shipped:** ink TUI · plan mode · persistent memory + self-evolution · atomization planner · parallel plan atoms · **multi-role review chains** · parallel sub-agents · MCP client *and* server · **scheduled tasks (`hara cron`)** · **single-binary distribution** · **Docker image** · `/compact` context management.
 **Next:** SSOT data authority · an enterprise control-plane (fleet + central token management).
 
 ## Security

package/dist/context/mentions.js

@@ -8,45 +8,49 @@ import { mediaTypeFor } from "../images.js";
 const MAX_FILE = 50_000;
 // @ at start-of-string or after whitespace; capture a path with no spaces/@ (avoids emails like a@b.com)
 const MENTION_RE = /(?:^|\s)@([^\s@]+)/g;
-/** Append the contents of any @mentioned files to the input as fenced blocks. */
+/** Expand `@path` references **in place** — the file/dir content lands where it's referenced, not
+ *  dumped at the bottom (so "compare @a.ts with @b.ts" reads in context). A repeated mention keeps
+ *  the bare `@path` the second time (no double-inlining), and a non-readable ref is left untouched. */
 export function expandMentions(input, cwd) {
     const seen = new Set();
-    const blocks = [];
-    let m;
     MENTION_RE.lastIndex = 0;
-    while ((m = MENTION_RE.exec(input)) !== null) {
-        const ref = m[1];
+    return input.replace(MENTION_RE, (whole, ref) => {
+        const prefix = whole.slice(0, whole.length - ref.length - 1); // BOL "" or the captured leading whitespace
         if (seen.has(ref))
-            continue;
+            return whole; // already inlined above → leave this occurrence as the bare @ref
+        const block = expandRef(ref, cwd);
+        if (block === null)
+            return whole; // not a readable file/dir → leave the token as typed
         seen.add(ref);
-        const abs = isAbsolute(ref) ? ref : resolve(cwd, ref);
-        try {
-            if (existsSync(abs)) {
-                const st = statSync(abs);
-                if (st.isFile()) {
-                    if (mediaTypeFor(abs)) {
-                        // don't inline binary image bytes as text — paste it with Ctrl+V (or drag the file in) to attach visually
-                        blocks.push(`Referenced \`${ref}\` is an image — paste it with Ctrl+V to attach it visually.`);
-                    }
-                    else {
-                        let txt = readFileSync(abs, "utf8");
-                        if (txt.length > MAX_FILE)
-                            txt = txt.slice(0, MAX_FILE) + "\n…[truncated]";
-                        blocks.push(`Referenced file \`${ref}\`:\n\`\`\`\n${txt}\n\`\`\``);
-                    }
-                }
-                else if (st.isDirectory()) {
-                    // `@dir` loads a listing of the directory's files (the agent can then read specific ones)
-                    const files = walkFiles(abs, 300);
-                    blocks.push(`Referenced directory \`${ref}\` (${files.length} files):\n\`\`\`\n${files.join("\n") || "(empty)"}\n\`\`\``);
-                }
-            }
+        return `${prefix}${block}`;
+    });
+}
+/** Render one mention as an inline block, or null if it isn't a readable file/dir. */
+function expandRef(ref, cwd) {
+    const abs = isAbsolute(ref) ? ref : resolve(cwd, ref);
+    try {
+        if (!existsSync(abs))
+            return null;
+        const st = statSync(abs);
+        if (st.isFile()) {
+            // don't inline binary image bytes as text — paste with Ctrl+V (or drag the file in) to attach visually
+            if (mediaTypeFor(abs))
+                return `Referenced \`${ref}\` is an image — paste it with Ctrl+V to attach it visually.`;
+            let txt = readFileSync(abs, "utf8");
+            if (txt.length > MAX_FILE)
+                txt = txt.slice(0, MAX_FILE) + "\n…[truncated]";
+            return `\nReferenced file \`${ref}\`:\n\`\`\`\n${txt}\n\`\`\`\n`;
         }
-        catch {
-            /* ignore unreadable mention */
+        if (st.isDirectory()) {
+            // `@dir` loads a listing of the directory's files (the agent can then read specific ones)
+            const files = walkFiles(abs, 300);
+            return `\nReferenced directory \`${ref}\` (${files.length} files):\n\`\`\`\n${files.join("\n") || "(empty)"}\n\`\`\`\n`;
         }
     }
-    return blocks.length ? `${input}\n\n${blocks.join("\n\n")}` : input;
+    catch {
+        /* ignore unreadable mention */
+    }
+    return null;
 }
 // Short-lived per-cwd cache so Tab completion stays snappy without re-scanning every press.
 const cache = new Map();

package/dist/index.js

@@ -19,7 +19,7 @@ import { notifyDone } from "./notify.js";
 import { startMcpServer, mcpServeToolNames } from "./mcp/server.js";
 import { completionScript } from "./completions.js";
 import { renderSessionMarkdown } from "./export.js";
-import { loadEnrollment, clearEnrollment, enrollDevice, heartbeat, gatewayBaseURL } from "./org-fleet/enroll.js";
+import { loadEnrollment, clearEnrollment, enrollDevice, heartbeat, gatewayBaseURL, syncOrgRoles } from "./org-fleet/enroll.js";
 import { mapLimit, maxParallel } from "./concurrency.js";
 import { parseVerdict, captureChanges, reviewPrompt, fixPrompt, REVIEWER_SYSTEM, isTreeClean, stripCommitFence } from "./org/review-chain.js";
 import { parseSchedule, describeSchedule, nextRun } from "./cron/schedule.js";
@@ -763,6 +763,9 @@ program
         if (e.model)
             writeConfigValue("model", e.model);
         out(c.green(`✓ enrolled with ${e.gatewayUrl}`) + c.dim(` · device ${e.deviceId || "?"} · model ${e.model || "(gateway default)"}\n`) + c.dim("hara routes through the gateway now — the real provider key stays server-side.\n"));
+        const nRoles = await syncOrgRoles(); // pull this device's governed digital-employee bundle (B3)
+        if (nRoles > 0)
+            out(c.dim(`  ↳ synced ${nRoles} org role${nRoles === 1 ? "" : "s"} → ~/.hara/org-roles/\n`));
     }
     catch (err) {
         out(c.red(`Enroll failed: ${err instanceof Error ? err.message : String(err)}\n`));
@@ -1237,8 +1240,10 @@ program.action(async (opts) => {
         process.exit(1);
     }
     let provider = provider0;
-    if (cfg.provider === "hara-gateway")
+    if (cfg.provider === "hara-gateway") {
         void heartbeat(); // fleet visibility — fire-and-forget, never blocks startup
+        void syncOrgRoles(); // refresh governed org-role bundle (B3) in the background; best-effort, never blocks
+    }
     const cwd = cfg.cwd;
     let approval = opts.yes ? "full-auto" : (opts.approval || cfg.approval);
     let currentTurn = null; // set during a running turn so Esc can abort it

package/dist/org/roles.js

@@ -12,6 +12,12 @@ export function rolesDir(cwd) {
 export function globalRolesDir() {
     return join(homedir(), ".hara", "roles");
 }
+/** Org-pushed roles (B-end): the digital-employee bundle synced from hara-control's `/v1/roles` into
+ *  `~/.hara/org-roles/*.md` (see org-fleet/enroll.ts syncOrgRoles). A managed baseline — above
+ *  third-party plugins, but a dev's own global/project roles still win. */
+export function orgRolesDir() {
+    return join(homedir(), ".hara", "org-roles");
+}
 /** Claude-Code subagents (`.claude/agents/*.md`) — consumed for ecosystem interop (project scope). */
 export function claudeAgentsDir(cwd) {
     return join(findProjectRoot(cwd), ".claude", "agents");
@@ -62,8 +68,8 @@ export function subagentToolFilter(role, isReadonly) {
 }
 export function loadRoles(cwd) {
     const byId = new Map();
-    // lowest→highest precedence: plugins < global < .claude/agents < .hara/roles (project wins, same as memory/config)
-    for (const dir of [...pluginRoleDirs(), globalRolesDir(), claudeAgentsDir(cwd), rolesDir(cwd)]) {
+    // lowest→highest precedence: plugins < org(B-end push) < global < .claude/agents < .hara/roles (project wins)
+    for (const dir of [...pluginRoleDirs(), orgRolesDir(), globalRolesDir(), claudeAgentsDir(cwd), rolesDir(cwd)]) {
         if (!existsSync(dir))
             continue;
         for (const f of readdirSync(dir)) {

package/dist/org-fleet/enroll.js

@@ -7,10 +7,12 @@
 // Protocol (what `hara-control` implements on the other end):
 //   POST {gateway}/v1/enroll      {code, device:{name,os,hara_version}} -> {device_token, device_id, model, base_url?}
 //   POST {gateway}/v1/heartbeat   Bearer <device_token> {device_id, name, os, hara_version} -> 200/204
+//   GET  {gateway}/v1/roles       Bearer <device_token> -> {version, org_policy, roles:[…]}  (B3 digital-employee push-down)
 //   POST {gateway}/v1/chat/completions  (OpenAI-compatible; the normal agent traffic, Bearer <device_token>)
 import { homedir, hostname, platform } from "node:os";
 import { join } from "node:path";
 import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync, rmSync } from "node:fs";
+import { orgRolesDir } from "../org/roles.js";
 const orgPath = () => join(homedir(), ".hara", "org.json");
 const deviceInfo = () => ({ name: hostname(), os: platform(), hara_version: process.env.HARA_BUILD_VERSION ?? "dev" });
 /** The effective OpenAI-compatible base URL for an enrollment (explicit, else <gatewayUrl>/v1). */
@@ -92,3 +94,50 @@ export async function heartbeat(signal) {
         return false;
     }
 }
+/** Render one bundle role into the markdown frontmatter the CLI role loader expects
+ *  (src/org/roles.ts parseFrontmatter): name/description/owns/rejects/model/allowTools/denyTools, body=system. */
+function renderRoleMd(r) {
+    const fm = ["---", `name: ${r.name}`];
+    if (r.description)
+        fm.push(`description: ${r.description}`);
+    if (r.owns?.length)
+        fm.push(`owns: [${r.owns.join(", ")}]`);
+    if (r.rejects?.length)
+        fm.push(`rejects: [${r.rejects.join(", ")}]`);
+    if (r.model)
+        fm.push(`model: ${r.model}`);
+    if (r.allow_tools?.length)
+        fm.push(`allowTools: [${r.allow_tools.join(", ")}]`); // snake_case wire → camelCase fm
+    if (r.deny_tools?.length)
+        fm.push(`denyTools: [${r.deny_tools.join(", ")}]`);
+    fm.push("---", "", (r.system || "").trim(), "");
+    return fm.join("\n");
+}
+/** Pull this device's governed role bundle from the control plane and materialize it into
+ *  `~/.hara/org-roles/*.md` — a managed precedence layer below the dev's own global/project roles
+ *  (see src/org/roles.ts loadRoles). The org bundle is AUTHORITATIVE: the dir is wiped and rewritten on
+ *  every sync, so a server-side revoke/rename actually removes the local role. Best-effort: never throws;
+ *  returns the count of roles written (0 on any failure / not enrolled / empty bundle). */
+export async function syncOrgRoles(signal) {
+    const e = loadEnrollment();
+    if (!e)
+        return 0;
+    try {
+        const res = await fetch(`${e.gatewayUrl}/v1/roles`, { signal, headers: { authorization: `Bearer ${e.deviceToken}` } });
+        if (!res.ok)
+            return 0;
+        const bundle = (await res.json());
+        const roles = Array.isArray(bundle.roles) ? bundle.roles.filter((r) => r && r.name && r.system) : [];
+        const dir = orgRolesDir();
+        rmSync(dir, { recursive: true, force: true }); // authoritative replace
+        mkdirSync(dir, { recursive: true });
+        for (const r of roles)
+            writeFileSync(join(dir, `${r.name}.md`), renderRoleMd(r), "utf8");
+        // org policy sidecar (model/tool/approval floors the CLI enforces; skipped by the .md-only role loader)
+        writeFileSync(join(dir, "_policy.json"), JSON.stringify({ version: bundle.version ?? 0, org_policy: bundle.org_policy ?? {} }, null, 2) + "\n", "utf8");
+        return roles.length;
+    }
+    catch {
+        return 0;
+    }
+}

package/dist/search/semindex.js

@@ -7,6 +7,7 @@ import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { findProjectRoot } from "../context/agents-md.js";
 import { listProjectFiles, walkFiles, isProbablyBinary, fileSize } from "../fs-walk.js";
+import { zvecBuild, zvecQueryIds } from "./zvec-store.js";
 // Same code/text extensions codebase_search ranks lexically — keep the two walks in sync.
 const CODE_RE = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cc|cpp|hpp|cs|swift|scala|sh|bash|sql|md|mdx|json|ya?ml|toml|html|css|scss|less|vue|svelte|astro|tf|proto|graphql|gql|gradle|txt)$/i;
 /** Index location — repo index lives in the project (gitignore it); the rest are global. Derived/rebuildable. */
@@ -116,6 +117,8 @@ export async function buildIndex(name, chunks, embed, cwd, model = "embed") {
     if (!existsSync(join(dir, ".gitignore")))
         writeFileSync(join(dir, ".gitignore"), "*\n", "utf8");
     writeFileSync(p, JSON.stringify({ model, items }), "utf8");
+    // Build a zvec ANN index alongside the JSON cache (best-effort; queryIndex prefers it for retrieval).
+    await zvecBuild(name, items.map((it) => ({ id: it.id, vec: it.vec })), cwd);
     return { total: items.length, embedded: toEmbed.length, reused };
 }
 export function indexExists(name, cwd) {
@@ -192,6 +195,21 @@ export async function queryIndex(name, query, embed, cwd, k = 6) {
     const [qv] = await embed([query]);
     if (!qv)
         return [];
+    // Prefer the zvec ANN index for candidate retrieval; re-rank candidates by EXACT cosine from the JSON
+    // store (identical score semantics to the brute-force path). Fall back to full brute-force if zvec is
+    // unavailable / has no index / errors.
+    const ids = await zvecQueryIds(name, qv, cwd, k);
+    if (ids?.length) {
+        const byId = new Map(idx.items.map((it) => [it.id, it]));
+        const hits = ids
+            .map((id) => byId.get(id))
+            .filter((it) => Boolean(it))
+            .map((it) => ({ file: it.file, source: it.source, text: it.text, score: cosine(qv, it.vec) }))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, k);
+        if (hits.length)
+            return hits;
+    }
     return idx.items
         .map((it) => ({ file: it.file, source: it.source, text: it.text, score: cosine(qv, it.vec) }))
         .sort((a, b) => b.score - a.score)

package/dist/search/zvec-store.js

@@ -0,0 +1,77 @@
+// zvec-backed ANN index for local semantic search. zvec (@zvec/zvec) is an OPTIONAL native dependency:
+// if it's absent or fails to load (no prebuilt for the platform), every function here returns
+// null/false and the caller falls back to the JSON brute-force store in semindex.ts — so installs
+// without the native binding keep working (lexical/JSON floor preserved).
+//
+// Design: zvec stores only vector→id (a pure ANN index). The JSON store stays the durable embedding
+// cache + SSOT for hit text/score. So zvec is used for fast candidate retrieval, but the SCORE is
+// recomputed from the JSON vectors (in semindex.queryIndex) — identical score semantics, zero risk
+// to hybrid.ts's thresholds.
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { rmSync, existsSync } from "node:fs";
+import { findProjectRoot } from "../context/agents-md.js";
+/* eslint-disable @typescript-eslint/no-explicit-any */
+let cached = null;
+let attempted = false;
+async function zvec() {
+    if (attempted)
+        return cached;
+    attempted = true;
+    try {
+        cached = await import("@zvec/zvec");
+    }
+    catch {
+        cached = null; // optional dep / no native prebuilt → callers fall back to brute-force
+    }
+    return cached;
+}
+export async function zvecAvailable() {
+    return (await zvec()) !== null;
+}
+function zvecDir(name, cwd) {
+    if (name === "repo")
+        return join(findProjectRoot(cwd), ".hara", "index", "repo.zvec");
+    return join(homedir(), ".hara", "index", `${name}.zvec`);
+}
+const VEC = "v";
+/** (Re)build a fresh zvec collection from already-embedded items. Best-effort — false on any failure. */
+export async function zvecBuild(name, items, cwd) {
+    const z = await zvec();
+    if (!z || items.length === 0)
+        return false;
+    try {
+        const dim = items[0].vec.length;
+        const path = zvecDir(name, cwd);
+        rmSync(path, { recursive: true, force: true }); // rebuild from the JSON cache (vectors already computed)
+        const schema = new z.ZVecCollectionSchema({
+            name,
+            vectors: [{ name: VEC, dataType: z.ZVecDataType.VECTOR_FP32, dimension: dim, indexParams: { indexType: z.ZVecIndexType.FLAT, metricType: z.ZVecMetricType.COSINE } }],
+        });
+        const col = z.ZVecCreateAndOpen(path, schema);
+        col.insertSync(items.map((it) => ({ id: it.id, vectors: { [VEC]: it.vec } })));
+        col.closeSync?.(); // closeSync flushes + releases the LOCK so a later (read-only) open succeeds
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** ANN candidate ids (best first) from the zvec index. null if unavailable/error → caller brute-forces. */
+export async function zvecQueryIds(name, qv, cwd, k) {
+    const z = await zvec();
+    if (!z)
+        return null;
+    if (!existsSync(zvecDir(name, cwd)))
+        return null;
+    try {
+        const col = z.ZVecOpen(zvecDir(name, cwd), { readOnly: true }); // read-only → no write-lock contention
+        // over-fetch, then semindex re-ranks the candidates by exact cosine from the JSON store
+        const docs = await col.query({ fieldName: VEC, vector: qv, topk: Math.max(k * 4, 24) });
+        col.closeSync?.();
+        return docs.map((d) => d.id);
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.67.0",
+  "version": "0.70.0",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "dist/index.js"
@@ -63,5 +63,8 @@
     "ink-testing-library": "^4.0.0",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3"
+  },
+  "optionalDependencies": {
+    "@zvec/zvec": "^0.5.0"
   }
 }