@nanhara/hara 0.121.1 → 0.122.1

package/dist/agent/structured.js

@@ -0,0 +1,231 @@
+/**
+ * Supported validation keywords are deliberately small and explicit:
+ * - `type`: object, array, string, number, integer, boolean, null (or a union array)
+ * - `required`, `properties`, and boolean `additionalProperties` for objects
+ * - one schema in `items` for arrays (tuple schemas are not supported)
+ * - `enum` containing JSON primitive values
+ * - annotation-only `title` and `description`
+ *
+ * Every other JSON-Schema keyword is rejected. In particular, combinators and references such as
+ * `$ref`, `allOf`, `anyOf`, `oneOf`, and `not` must never be silently accepted: doing so would make
+ * the CLI promise a constraint that this dependency-free validator did not enforce.
+ */
+const SUPPORTED_SCHEMA_KEYWORDS = new Set([
+    "type",
+    "required",
+    "properties",
+    "additionalProperties",
+    "items",
+    "enum",
+    "title",
+    "description",
+]);
+const SUPPORTED_SCHEMA_TYPES = new Set(["object", "array", "string", "number", "integer", "boolean", "null"]);
+function isSchemaObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function own(schema, key) {
+    return Object.hasOwn(schema, key) ? schema[key] : undefined;
+}
+function schemaTypes(schema) {
+    const type = own(schema, "type");
+    return type === undefined ? [] : Array.isArray(type) ? type : [type];
+}
+function describeSchemaValue(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function validateSchemaDefinition(schema, path = "$schema") {
+    if (!isSchemaObject(schema))
+        return `${path}: schema must be a plain JSON object`;
+    for (const keyword of Object.keys(schema)) {
+        if (!SUPPORTED_SCHEMA_KEYWORDS.has(keyword))
+            return `${path}.${keyword}: unsupported JSON-Schema keyword`;
+    }
+    const type = own(schema, "type");
+    if (type !== undefined) {
+        const types = Array.isArray(type) ? type : [type];
+        if (types.length === 0)
+            return `${path}.type: type array must not be empty`;
+        const seen = new Set();
+        for (const candidate of types) {
+            if (typeof candidate !== "string" || !SUPPORTED_SCHEMA_TYPES.has(candidate)) {
+                return `${path}.type: unsupported JSON-Schema type ${describeSchemaValue(candidate)}`;
+            }
+            if (seen.has(candidate))
+                return `${path}.type: duplicate type ${describeSchemaValue(candidate)}`;
+            seen.add(candidate);
+        }
+    }
+    for (const annotation of ["title", "description"]) {
+        const value = own(schema, annotation);
+        if (value !== undefined && typeof value !== "string")
+            return `${path}.${annotation}: expected string`;
+    }
+    const enumValues = own(schema, "enum");
+    if (enumValues !== undefined) {
+        if (!Array.isArray(enumValues) || enumValues.length === 0)
+            return `${path}.enum: expected a non-empty array`;
+        for (const value of enumValues) {
+            if (value !== null && !["string", "number", "boolean"].includes(typeof value)) {
+                return `${path}.enum: only JSON primitive values are supported`;
+            }
+            if (typeof value === "number" && !Number.isFinite(value))
+                return `${path}.enum: numbers must be finite`;
+        }
+    }
+    const required = own(schema, "required");
+    if (required !== undefined) {
+        if (!Array.isArray(required) || required.some((key) => typeof key !== "string")) {
+            return `${path}.required: expected an array of property names`;
+        }
+        if (new Set(required).size !== required.length)
+            return `${path}.required: property names must be unique`;
+    }
+    const properties = own(schema, "properties");
+    if (properties !== undefined) {
+        if (!isSchemaObject(properties))
+            return `${path}.properties: expected an object of property schemas`;
+        for (const [key, child] of Object.entries(properties)) {
+            const error = validateSchemaDefinition(child, `${path}.properties.${key}`);
+            if (error)
+                return error;
+        }
+    }
+    const additionalProperties = own(schema, "additionalProperties");
+    if (additionalProperties !== undefined && typeof additionalProperties !== "boolean") {
+        return `${path}.additionalProperties: only boolean values are supported`;
+    }
+    const items = own(schema, "items");
+    if (items !== undefined) {
+        const error = validateSchemaDefinition(items, `${path}.items`);
+        if (error)
+            return error;
+    }
+    const types = schemaTypes(schema);
+    const hasObjectKeyword = required !== undefined || properties !== undefined || additionalProperties !== undefined;
+    if (hasObjectKeyword && !types.includes("object")) {
+        return `${path}: object keywords require type "object"`;
+    }
+    if (items !== undefined && !types.includes("array"))
+        return `${path}: items requires type "array"`;
+    return null;
+}
+function actualType(value) {
+    return Array.isArray(value) ? "array" : value === null ? "null" : typeof value;
+}
+function matchesType(value, type) {
+    const actual = actualType(value);
+    if (type === "integer")
+        return actual === "number" && Number.isFinite(value) && Number.isInteger(value);
+    if (type === "number")
+        return actual === "number" && Number.isFinite(value);
+    return type === actual;
+}
+function validateValue(value, schema, path) {
+    const types = schemaTypes(schema);
+    if (types.length && !types.some((type) => matchesType(value, type))) {
+        return `${path}: expected ${types.join("|")}, got ${actualType(value)}`;
+    }
+    const enumValues = own(schema, "enum");
+    if (enumValues && !enumValues.some((candidate) => candidate === value)) {
+        return `${path}: value not in enum ${JSON.stringify(enumValues)}`;
+    }
+    if (typeof value === "object" && value !== null && !Array.isArray(value) && types.includes("object")) {
+        const object = value;
+        const required = own(schema, "required");
+        for (const key of required ?? []) {
+            if (!Object.hasOwn(object, key))
+                return `${path}.${key}: required property missing`;
+        }
+        const properties = own(schema, "properties");
+        for (const [key, child] of Object.entries(properties ?? {})) {
+            if (Object.hasOwn(object, key)) {
+                const error = validateValue(object[key], child, `${path}.${key}`);
+                if (error)
+                    return error;
+            }
+        }
+        if (own(schema, "additionalProperties") === false) {
+            for (const key of Object.keys(object)) {
+                if (!properties || !Object.hasOwn(properties, key))
+                    return `${path}.${key}: unexpected property`;
+            }
+        }
+    }
+    if (Array.isArray(value) && types.includes("array")) {
+        const items = own(schema, "items");
+        if (items) {
+            for (let index = 0; index < value.length; index++) {
+                const error = validateValue(value[index], items, `${path}[${index}]`);
+                if (error)
+                    return error;
+            }
+        }
+    }
+    return null;
+}
+/** Validate `value` against the supported JSON-Schema subset. Returns null when valid, otherwise a path-rich
+ * error. Invalid or unsupported schemas are errors too; they are never treated as permissive schemas. */
+export function validateAgainstSchema(value, schema, path = "$") {
+    const schemaError = validateSchemaDefinition(schema);
+    if (schemaError)
+        return `invalid schema — ${schemaError}`;
+    return validateValue(value, schema, path);
+}
+/** Parse a `--schema` CLI value: inline JSON, or (by the caller) file contents. Returns the schema object or
+ *  an error string. Top level must be an object schema — tool arguments are always a JSON object. */
+export function parseSchemaArg(raw) {
+    let schema;
+    try {
+        schema = JSON.parse(raw);
+    }
+    catch (e) {
+        return { error: `--schema is not valid JSON: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    if (!isSchemaObject(schema))
+        return { error: "--schema must be a JSON object (a JSON-Schema)" };
+    let normalized = schema;
+    if (!Object.hasOwn(normalized, "type"))
+        normalized = { ...normalized, type: "object" };
+    if (own(normalized, "type") !== "object") {
+        return { error: "--schema top level must have type:'object' (tool args are an object)" };
+    }
+    if (!Object.hasOwn(normalized, "properties"))
+        normalized = { ...normalized, properties: {} };
+    const schemaError = validateSchemaDefinition(normalized);
+    if (schemaError)
+        return { error: `--schema is unsupported or invalid: ${schemaError}` };
+    return normalized;
+}
+/** The instruction appended to the prompt so the model knows the contract. */
+export const STRUCTURED_INSTRUCTION = "\n\nWhen you have the final answer, you MUST call the `structured_output` tool exactly once with the result " +
+    "matching its schema. Do not print the result as text — the tool call IS the answer.";
+/** The retry nudge when a turn ends without the tool having been called. */
+export const STRUCTURED_NUDGE = "You finished without calling `structured_output`. Call it NOW with your final result matching the schema — the tool call is the only accepted answer.";
+/** Build the run-scoped structured_output tool. `sink` receives the validated payload (last call wins). */
+export function structuredOutputTool(schema, sink) {
+    const schemaError = validateSchemaDefinition(schema);
+    if (schemaError)
+        throw new Error(`Invalid structured-output schema: ${schemaError}`);
+    return {
+        name: "structured_output",
+        description: "Record the final structured result of this task. Call exactly once, when done, with the complete answer.",
+        input_schema: schema,
+        kind: "read", // never prompts; the payload is data, not an action
+        async run(input) {
+            const err = validateAgainstSchema(input, schema);
+            if (err)
+                return `schema validation failed — ${err}. Fix the payload and call structured_output again.`;
+            sink(input);
+            return "structured result recorded.";
+        },
+    };
+}

package/dist/agent/touched.js

@@ -2,17 +2,35 @@
 // The loop records every file the MAIN conversation reads/edits; when the history is compacted to a
 // summary, the top-N most-recent files get their CURRENT on-disk content re-attached — so the model
 // doesn't lose the very files it was working on and re-read them all next turn.
-const touched = new Map(); // absolute path → last-touch timestamp
-export function recordTouch(path) {
+import { isSensitiveFilePath } from "../security/sensitive-files.js";
+const DEFAULT_SCOPE = "default";
+const touchedByScope = new Map(); // scope → absolute path → last-touch timestamp
+function scopedTouched(scope) {
+    const key = scope?.trim() || DEFAULT_SCOPE;
+    const touched = touchedByScope.get(key) ?? new Map();
+    touchedByScope.set(key, touched);
+    return touched;
+}
+export function recordTouch(path, scope) {
+    if (isSensitiveFilePath(path))
+        return;
+    const touched = scopedTouched(scope);
+    touched.delete(path);
     touched.set(path, Date.now());
+    if (touched.size > 200)
+        touched.delete(touched.keys().next().value);
 }
 /** Most-recently-touched first. */
-export function recentTouched(n = 5) {
-    return [...touched.entries()]
+export function recentTouched(n = 5, scope) {
+    return [...scopedTouched(scope).entries()]
+        .filter(([path]) => !isSensitiveFilePath(path))
         .sort((a, b) => b[1] - a[1])
         .slice(0, n)
         .map(([p]) => p);
 }
-export function clearTouched() {
-    touched.clear();
+export function clearTouched(scope) {
+    if (scope)
+        touchedByScope.delete(scope.trim() || DEFAULT_SCOPE);
+    else
+        touchedByScope.clear();
 }

package/dist/checkpoints.js

@@ -5,22 +5,39 @@
 // snapshot-then-checkout: SAFE — it reverts changed/deleted files to the checkpoint and never deletes files
 // created since (so a stray restore can't nuke new work; it's also itself undoable via the auto-snapshot).
 import { execFileSync } from "node:child_process";
-import { mkdirSync, writeFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { chmodSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { findProjectRoot } from "./context/agents-md.js";
+import { toolSubprocessEnv } from "./security/subprocess-env.js";
+import { sensitiveFileReason } from "./security/sensitive-files.js";
+import { redactSensitiveText } from "./security/secrets.js";
 // Heavy/derived dirs the shadow repo must never snapshot (in addition to the project's own .gitignore).
-const EXCLUDES = ["node_modules/", ".git/", "dist/", "build/", "out/", ".next/", "target/", ".venv/", "venv/", "__pycache__/", ".hara/", ".cache/", ".turbo/", "coverage/", "*.log", ".DS_Store"];
+const PRIVATE_DATA_EXCLUDES = ["credentials", "credential", "secrets", "secret", "service-account", "service_account"]
+    .flatMap((stem) => ["json", "yaml", "yml", "toml", "ini", "cfg", "conf"].map((ext) => `**/${stem}.${ext}`));
+const EXCLUDES = [
+    "node_modules/", ".git/", "dist/", "build/", "out/", ".next/", "target/", ".venv/", "venv/",
+    "__pycache__/", ".hara/", ".cache/", ".turbo/", "coverage/", "*.log", ".DS_Store",
+    "**/.env", "**/.env.*", "!**/.env.example", "!**/.env.*.example", "!**/.env.sample", "!**/.env.*.sample",
+    "!**/.env.template", "!**/.env.*.template", "!**/.env.dist", "!**/.env.*.dist", "!**/.env.defaults", "!**/.env.*.defaults",
+    "**/.envrc", "**/.direnv/", "**/.netrc", "**/.npmrc", "**/.pypirc", "**/.git-credentials",
+    "**/credentials", "**/credential", "**/secrets", "**/secret", "**/service-account", "**/service_account",
+    ...PRIVATE_DATA_EXCLUDES,
+    "**/application_default_credentials.json", "**/.aws/credentials", "**/.docker/config.json", "**/.kube/config",
+    "**/id_rsa", "**/id_ed25519", "**/id_ecdsa", "**/*.pem", "**/*.key", "**/*.p12", "**/*.pfx", "**/*.keystore",
+];
+const CHECKPOINT_FORMAT = "protected-files-v2";
 function shadowGitDir(root) {
     return join(homedir(), ".hara", "checkpoints", createHash("sha256").update(root).digest("hex").slice(0, 16), "git");
 }
-function git(root, gitDir, args) {
+function git(root, gitDir, args, input) {
     return execFileSync("git", args, {
         cwd: root,
-        env: { ...process.env, GIT_DIR: gitDir, GIT_WORK_TREE: root, GIT_AUTHOR_NAME: "hara", GIT_AUTHOR_EMAIL: "hara@local", GIT_COMMITTER_NAME: "hara", GIT_COMMITTER_EMAIL: "hara@local" },
+        env: toolSubprocessEnv(process.env, { GIT_DIR: gitDir, GIT_WORK_TREE: root, GIT_AUTHOR_NAME: "hara", GIT_AUTHOR_EMAIL: "hara@local", GIT_COMMITTER_NAME: "hara", GIT_COMMITTER_EMAIL: "hara@local" }),
         encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"],
+        stdio: [input === undefined ? "ignore" : "pipe", "pipe", "ignore"],
+        ...(input === undefined ? {} : { input }),
         maxBuffer: 64 * 1024 * 1024,
         // Bound it: the per-turn shadow `git add -A` over a large tree (or a hung git) must never freeze a
         // turn. On timeout execFileSync throws → checkpoint()/ensureRepo() catch it → the snapshot is just
@@ -30,18 +47,61 @@ function git(root, gitDir, args) {
 }
 function ensureRepo(root, gitDir) {
     try {
+        const stateDir = dirname(gitDir);
+        const checkpointRoot = dirname(stateDir);
+        const marker = join(stateDir, "format");
+        mkdirSync(checkpointRoot, { recursive: true, mode: 0o700 });
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        try {
+            chmodSync(checkpointRoot, 0o700);
+            chmodSync(stateDir, 0o700);
+        }
+        catch { /* best effort */ }
+        // Older shadow repositories may contain secret blobs even after the path leaves the index. Checkpoints
+        // are a derived undo cache, so rotate the repository instead of pretending git-rm purged its history.
+        let format = "";
+        try {
+            format = readFileSync(marker, "utf8").trim();
+        }
+        catch { /* first protected open */ }
+        if (existsSync(gitDir) && format !== CHECKPOINT_FORMAT)
+            rmSync(gitDir, { recursive: true, force: true });
         if (!existsSync(join(gitDir, "HEAD"))) {
-            mkdirSync(gitDir, { recursive: true });
+            mkdirSync(gitDir, { recursive: true, mode: 0o700 });
             git(root, gitDir, ["init", "-q"]);
             mkdirSync(join(gitDir, "info"), { recursive: true });
-            writeFileSync(join(gitDir, "info", "exclude"), EXCLUDES.join("\n") + "\n");
         }
+        try {
+            chmodSync(gitDir, 0o700);
+        }
+        catch { /* best effort */ }
+        writeFileSync(marker, CHECKPOINT_FORMAT + "\n", { mode: 0o600 });
+        try {
+            chmodSync(marker, 0o600);
+        }
+        catch { /* best effort on non-POSIX filesystems */ }
+        mkdirSync(join(gitDir, "info"), { recursive: true });
+        const excludeFile = join(gitDir, "info", "exclude");
+        writeFileSync(excludeFile, EXCLUDES.join("\n") + "\n", { mode: 0o600 });
+        try {
+            chmodSync(excludeFile, 0o600);
+        }
+        catch { /* best effort on non-POSIX filesystems */ }
         return true;
     }
     catch {
         return false;
     }
 }
+function dropSensitiveIndexEntries(root, gitDir) {
+    const indexed = git(root, gitDir, ["ls-files", "-z"]).split("\0").filter(Boolean);
+    const protectedPaths = indexed.filter((path) => sensitiveFileReason(join(root, path)) !== null);
+    if (protectedPaths.length) {
+        // stdin pathspecs avoid ARG_MAX and preserve arbitrary filenames (including whitespace/newlines).
+        git(root, gitDir, ["update-index", "--force-remove", "-z", "--stdin"], protectedPaths.join("\0") + "\0");
+    }
+    return protectedPaths.length;
+}
 /** Snapshot the current working tree into the shadow repo. Returns the short sha, or null on failure. */
 export function checkpoint(cwd, label) {
     const root = findProjectRoot(cwd);
@@ -49,8 +109,22 @@ export function checkpoint(cwd, label) {
     if (!ensureRepo(root, gitDir))
         return null;
     try {
+        // If a path became protected after this format was introduced, merely unstaging it would leave its
+        // historical blobs reachable. Rotate the derived repository before taking another snapshot.
+        if (dropSensitiveIndexEntries(root, gitDir) > 0) {
+            rmSync(gitDir, { recursive: true, force: true });
+            if (!ensureRepo(root, gitDir))
+                return null;
+        }
         git(root, gitDir, ["add", "-A"]);
-        git(root, gitDir, ["commit", "-q", "--allow-empty", "--no-gpg-sign", "-m", (label || "checkpoint").slice(0, 120)]);
+        // Defense against a future exclude-list regression. Once git-add saw a protected path its blob may exist
+        // even if we unstage it, so fail closed and purge the derived repository instead of retaining that object.
+        if (dropSensitiveIndexEntries(root, gitDir) > 0) {
+            rmSync(gitDir, { recursive: true, force: true });
+            return null;
+        }
+        const safeLabel = redactSensitiveText(label || "checkpoint").text.slice(0, 120);
+        git(root, gitDir, ["commit", "-q", "--allow-empty", "--no-gpg-sign", "-m", safeLabel]);
         return git(root, gitDir, ["rev-parse", "--short", "HEAD"]).trim();
     }
     catch {
@@ -59,11 +133,12 @@ export function checkpoint(cwd, label) {
 }
 /** Recent checkpoints, newest first. */
 export function listCheckpoints(cwd, n = 15) {
-    const gitDir = shadowGitDir(findProjectRoot(cwd));
-    if (!existsSync(join(gitDir, "HEAD")))
+    const root = findProjectRoot(cwd);
+    const gitDir = shadowGitDir(root);
+    if (!ensureRepo(root, gitDir) || !existsSync(join(gitDir, "HEAD")))
         return [];
     try {
-        const out = git(findProjectRoot(cwd), gitDir, ["log", `-n${n}`, "--format=%h\x1f%ct\x1f%s"]).trim();
+        const out = git(root, gitDir, ["log", `-n${n}`, "--format=%h\x1f%ct\x1f%s"]).trim();
         if (!out)
             return [];
         return out.split("\n").map((l) => {
@@ -79,15 +154,26 @@ export function listCheckpoints(cwd, n = 15) {
  *  undoable). Files created AFTER the checkpoint are left in place — nothing is deleted. Returns the count of
  *  files restored, or null on failure. */
 export function restoreCheckpoint(cwd, ref) {
+    if (!/^[0-9a-f]{4,64}$/i.test(ref))
+        return null; // checkpoint refs are hashes; reject option/ref injection
     const root = findProjectRoot(cwd);
     const gitDir = shadowGitDir(root);
-    if (!existsSync(join(gitDir, "HEAD")))
+    if (!ensureRepo(root, gitDir) || !existsSync(join(gitDir, "HEAD")))
         return null;
     try {
-        checkpoint(cwd, `before restore to ${ref}`); // make the restore itself undoable
-        const changed = git(root, gitDir, ["diff", "--name-only", ref, "--"]).trim(); // files differing now vs ref
-        git(root, gitDir, ["checkout", ref, "--", "."]);
-        return changed ? changed.split("\n").length : 0;
+        // Restoring without a durable pre-restore snapshot can destroy the user's newest work. Checkpointing is
+        // best-effort during ordinary turns, but it is a hard prerequisite for this destructive operation.
+        if (!checkpoint(cwd, `before restore to ${ref}`))
+            return null;
+        const changed = new Set(git(root, gitDir, ["diff", "--name-only", "-z", ref, "--"]).split("\0").filter(Boolean));
+        // A pre-restore snapshot tracks files created after `ref`; `git checkout ref -- new-file` would make
+        // the whole checkout fail. Restore only paths that actually existed at the requested checkpoint.
+        const atRef = git(root, gitDir, ["ls-tree", "-r", "-z", "--name-only", ref]).split("\0").filter(Boolean);
+        const safe = atRef.filter((path) => changed.has(path) && sensitiveFileReason(join(root, path)) === null);
+        if (safe.length) {
+            git(root, gitDir, ["checkout", ref, "--pathspec-from-file=-", "--pathspec-file-nul"], safe.join("\0") + "\0");
+        }
+        return safe.length;
     }
     catch {
         return null;

package/dist/cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Keep the runtime gate dependency-free and ahead of the main CLI import. Older Node releases must see an
+// actionable upgrade message even if a future dependency starts using syntax or APIs they cannot load.
+import { unsupportedNodeMessage } from "./runtime.js";
+const runtimeError = unsupportedNodeMessage();
+if (runtimeError) {
+    process.stderr.write(`${runtimeError}\n`);
+    process.exitCode = 1;
+}
+else {
+    void import("./index.js").catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`hara: failed to start: ${message}\n`);
+        process.exitCode = 1;
+    });
+}