xcoder-jarvis-agent 0.0.0-stage → 1.4.0

package/dist/jarvis/util/text.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Text and filesystem primitives shared by the prompt assembler, the tools and
+ * the memory store. Kept together so the injection and redaction behaviour is
+ * auditable in exactly one file (PRM-02, PRM-06, PRM-10).
+ */
+export declare function sha256(input: string | Buffer): string;
+export declare function shortHash(input: string, len?: number): string;
+/**
+ * Normalise untrusted text before it enters a prompt (PRM-06).
+ *
+ * Strips zero-width/bidi controls, collapses CRLF to LF, and normalises to
+ * NFC. Deliberately does NOT rewrite ordinary text: the output still reads as
+ * the author wrote it, it just cannot carry invisible instructions.
+ */
+export declare function normalizeUntrusted(text: string, maxChars?: number): string;
+/**
+ * Escape a closing delimiter so untrusted text cannot break out of its block.
+ *
+ * An attacker who gets `</untrusted-skill>` into a skill pack could otherwise
+ * end the data block early and have the remainder read as instructions. We
+ * escape the angle brackets of any delimiter-shaped sequence rather than
+ * stripping it, so the text stays visible and reviewable.
+ */
+export declare function escapeDelimiter(text: string, tag: string): string;
+/** Escape every angle bracket/quoter — used for attribute values (name, sha). */
+export declare function escapeAttr(value: string): string;
+export interface Redacted {
+    text: string;
+    hits: number;
+}
+/** Redact secrets and report how many rules fired (CORE-07). */
+export declare function redact(text: string): Redacted;
+export declare function truncate(text: string, max: number): {
+    text: string;
+    truncated: boolean;
+};
+export declare function byteLength(text: string): number;
+/**
+ * Short, filesystem-safe label derived from a user-supplied scope id.
+ *
+ * `--user` is an untrusted scope label, and it becomes a filename, so it must
+ * not be able to name a directory that resolves above the memory root. All
+ * separators become '-', runs of dots collapse to a single '.', and leading
+ * dots are stripped — that removes '.' and '..' as possible results, which
+ * are the only relative names that traverse.
+ */
+export declare function sanitizeLabel(raw: string, fallback?: string): string;
+/**
+ * Resolve `candidate` inside `root`, refusing paths that escape it.
+ *
+ * Uses `realpath` on both sides so a symlink pointing outside the workspace
+ * is rejected rather than followed (AI-04 path confinement).
+ */
+export declare function resolveInsideRoot(root: string, candidate: string): Promise<{
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    reason: string;
+}>;
+export declare function ensureDir(dir: string, mode?: number): Promise<void>;
+export declare function writeFilePrivate(file: string, data: string): Promise<void>;
+/** Write via temp file + rename so a reader never sees a half-written file. */
+export declare function writeAtomic(file: string, data: string): Promise<void>;
+/** Read a file, refusing anything larger than `maxBytes` before allocating. */
+export declare function readBounded(file: string, maxBytes: number): Promise<{
+    ok: true;
+    text: string;
+    bytes: number;
+    truncated: boolean;
+} | {
+    ok: false;
+    reason: string;
+}>;

package/dist/jarvis/util/text.js

@@ -0,0 +1,190 @@
+// xcoder:version 2 | xcoder:task task-f1b5f6 | xcoder:updated 2026-11-05T02:49:12.254Z | xcoder:subtask code-st-53c7b5
+import crypto from "node:crypto";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { redactSecrets } from "xcoder-dna";
+/**
+ * Text and filesystem primitives shared by the prompt assembler, the tools and
+ * the memory store. Kept together so the injection and redaction behaviour is
+ * auditable in exactly one file (PRM-02, PRM-06, PRM-10).
+ */
+export function sha256(input) {
+    return crypto.createHash("sha256").update(input).digest("hex");
+}
+export function shortHash(input, len = 16) {
+    return sha256(input).slice(0, len);
+}
+/** Zero-width and bidi-control characters used to hide instructions. */
+const ZERO_WIDTH = /[\u200B-\u200F\u202A-\u202E\u2060-\u2064\uFEFF]/g;
+/**
+ * Normalise untrusted text before it enters a prompt (PRM-06).
+ *
+ * Strips zero-width/bidi controls, collapses CRLF to LF, and normalises to
+ * NFC. Deliberately does NOT rewrite ordinary text: the output still reads as
+ * the author wrote it, it just cannot carry invisible instructions.
+ */
+export function normalizeUntrusted(text, maxChars = 200_000) {
+    const clipped = text.length > maxChars ? text.slice(0, maxChars) : text;
+    return clipped.replace(ZERO_WIDTH, "").replace(/\r\n?/g, "\n").normalize("NFC");
+}
+const ENTITIES = {
+    "<": "&lt;",
+    ">": "&gt;",
+    "&": "&amp;",
+    '"': "&quot;",
+    "'": "&#39;",
+};
+/**
+ * Escape a closing delimiter so untrusted text cannot break out of its block.
+ *
+ * An attacker who gets `</untrusted-skill>` into a skill pack could otherwise
+ * end the data block early and have the remainder read as instructions. We
+ * escape the angle brackets of any delimiter-shaped sequence rather than
+ * stripping it, so the text stays visible and reviewable.
+ */
+export function escapeDelimiter(text, tag) {
+    const pattern = new RegExp(`<\\s*/?\\s*${tag}\\b`, "gi");
+    return text.replace(pattern, (m) => m.replace(/[<>]/g, (c) => ENTITIES[c] ?? c));
+}
+/** Escape every angle bracket/quoter — used for attribute values (name, sha). */
+export function escapeAttr(value) {
+    return value.replace(/[<>&"']/g, (c) => ENTITIES[c] ?? c);
+}
+/** Redact secrets and report how many rules fired (CORE-07). */
+export function redact(text) {
+    try {
+        const result = redactSecrets(text);
+        const hits = (result.redactions ?? []).reduce((n, r) => n + (r.count ?? 0), 0);
+        return { text: result.text, hits };
+    }
+    catch {
+        // redactSecrets is documented never to throw; if that ever changes, the
+        // safe action for a logging path is to withhold the text entirely.
+        return { text: "[REDACTED:redaction-failed]", hits: 1 };
+    }
+}
+export function truncate(text, max) {
+    if (text.length <= max)
+        return { text, truncated: false };
+    return { text: text.slice(0, max), truncated: true };
+}
+export function byteLength(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+/**
+ * Short, filesystem-safe label derived from a user-supplied scope id.
+ *
+ * `--user` is an untrusted scope label, and it becomes a filename, so it must
+ * not be able to name a directory that resolves above the memory root. All
+ * separators become '-', runs of dots collapse to a single '.', and leading
+ * dots are stripped — that removes '.' and '..' as possible results, which
+ * are the only relative names that traverse.
+ */
+export function sanitizeLabel(raw, fallback = "unknown") {
+    const cleaned = raw
+        .normalize("NFKC")
+        .replace(/[^A-Za-z0-9._-]+/g, "-")
+        .replace(/\.{2,}/g, ".")
+        .replace(/^[.-]+|[.-]+$/g, "")
+        .slice(0, 64);
+    return cleaned.length > 0 ? cleaned : fallback;
+}
+/**
+ * Resolve `candidate` inside `root`, refusing paths that escape it.
+ *
+ * Uses `realpath` on both sides so a symlink pointing outside the workspace
+ * is rejected rather than followed (AI-04 path confinement).
+ */
+export async function resolveInsideRoot(root, candidate) {
+    let realRoot;
+    try {
+        realRoot = await fsp.realpath(root);
+    }
+    catch {
+        return { ok: false, reason: "workspace root is not readable" };
+    }
+    const target = path.resolve(realRoot, candidate);
+    let realTarget;
+    try {
+        realTarget = await fsp.realpath(target);
+    }
+    catch {
+        return { ok: false, reason: "path does not exist" };
+    }
+    const rel = path.relative(realRoot, realTarget);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        return { ok: false, reason: "path escapes the workspace" };
+    }
+    return { ok: true, path: realTarget };
+}
+export async function ensureDir(dir, mode = 0o700) {
+    await fsp.mkdir(dir, { recursive: true, mode });
+    // Windows ignores POSIX modes; best-effort is documented in the README.
+    if (process.platform !== "win32") {
+        try {
+            await fsp.chmod(dir, mode);
+        }
+        catch {
+            /* best effort */
+        }
+    }
+}
+export async function writeFilePrivate(file, data) {
+    await ensureDir(path.dirname(file));
+    await fsp.writeFile(file, data, { encoding: "utf8", mode: 0o600 });
+    if (process.platform !== "win32") {
+        try {
+            await fsp.chmod(file, 0o600);
+        }
+        catch {
+            /* best effort */
+        }
+    }
+}
+/** Write via temp file + rename so a reader never sees a half-written file. */
+export async function writeAtomic(file, data) {
+    await ensureDir(path.dirname(file));
+    const tmp = `${file}.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`;
+    await fsp.writeFile(tmp, data, { encoding: "utf8", mode: 0o600 });
+    await fsp.rename(tmp, file);
+    if (process.platform !== "win32") {
+        try {
+            await fsp.chmod(file, 0o600);
+        }
+        catch {
+            /* best effort */
+        }
+    }
+}
+/** Read a file, refusing anything larger than `maxBytes` before allocating. */
+export async function readBounded(file, maxBytes) {
+    let stat;
+    try {
+        stat = await fsp.stat(file);
+    }
+    catch {
+        return { ok: false, reason: "file does not exist" };
+    }
+    if (!stat.isFile())
+        return { ok: false, reason: "not a regular file" };
+    const limit = Math.min(stat.size, maxBytes);
+    try {
+        const handle = await fsp.open(file, "r");
+        try {
+            const buf = Buffer.alloc(limit);
+            const { bytesRead } = await handle.read(buf, 0, limit, 0);
+            return {
+                ok: true,
+                text: buf.subarray(0, bytesRead).toString("utf8"),
+                bytes: bytesRead,
+                truncated: stat.size > limit,
+            };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return { ok: false, reason: "file could not be read" };
+    }
+}

package/dist/program.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/program.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// xcoder:version 1 | xcoder:task task-f1b5f6 | xcoder:updated 2026-11-05T02:47:38.121Z | xcoder:subtask code-st-53c7b5
+import { runJarvisAgent } from "./index.js";
+/**
+ * Process boundary only (design §2.1).
+ *
+ * Everything testable lives behind `runJarvisAgent`; this file exists so the
+ * manifest's `bin.jarvis` entry has something to point at, and so the exit
+ * code the CLI contract promises is the one the process actually returns.
+ */
+const code = await runJarvisAgent(process.argv.slice(2));
+process.exit(code);

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "xcoder-jarvis-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.4.0",
+  "description": "Jarvis — a ReAct agent with scoped memory, skill-pack prompt assembly and a code-enforced tool allowlist, built on xcoder-dna.",
+  "license": "MIT",
+  "author": "Neural Node Labs",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "jarvis": "./dist/program.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "xcoder-dna": "^1.4.0",
+    "zod": "^4.4.3"
+  }
 }