pi-neutrasearch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NetroAki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# pi-neutrasearch
+
+Token-efficient native indexed filename and path search for [Pi](https://pi.dev).
+
+`pi-neutrasearch` registers one read-only `neutrasearch` tool. It queries an existing Neutrasearch compact index without walking directories, opening file contents, writing files, elevating privileges, or using the network.
+
+## Install
+
+Install Neutrasearch and build its index first, then install the Pi package:
+
+```sh
+pi install npm:pi-neutrasearch
+```
+
+Use `/neutrasearch` inside Pi to confirm executable discovery.
+
+The package resolves, in order:
+
+1. `NEUTRASEARCH_QUERY`
+2. `neutrasearch-query` on `PATH`
+3. `NEUTRASEARCH_BIN`
+4. `neutrasearch` on `PATH`
+
+Set `NEUTRASEARCH_INDEX` to override Neutrasearch's platform-default index path.
+
+## Agent tool
+
+```json
+{
+  "action": "search",
+  "query": "invoice ext:pdf",
+  "scope": "/workspace/project",
+  "limit": 20,
+  "relative_paths": true,
+  "metadata": false,
+  "max_chars": 6000
+}
+```
+
+The output is deliberately compact:
+
+```text
+scope=/workspace/project
+matched=2 returned=2 search_us=184
+records/2025/invoice-1042.pdf
+records/2024/invoice-991.pdf
+```
+
+Defaults are optimized for agent context:
+
+- 20 results
+- relative paths
+- no metadata columns
+- 6,000-character hard output budget
+- two-line numeric header
+
+Use `metadata: true` only when kind, size, or modification time is needed.
+
+## Search language
+
+- words and `"quoted phrases"`
+- `ext:rs,toml`
+- `kind:file`, `kind:dir`, or `kind:link`
+- `fs:btrfs,ext4,ntfs`
+- `size:>10M`, `size:<4K`, or `size:1M..20M`
+
+Neutrasearch searches indexed names and paths, not file contents. Locate candidates with this tool, then use targeted `read` or `grep` calls.
+
+## Scope and privacy
+
+Every search is scoped to the current Pi workspace by default. A requested scope must resolve inside that workspace.
+
+To authorize additional roots explicitly, set an OS-path-delimited list:
+
+```sh
+export NEUTRASEARCH_PI_ALLOWED_ROOTS="$HOME/Documents:$HOME/Projects"
+```
+
+The extension verifies returned paths again and drops any path outside the approved scope. It never starts the scanner or helper daemon.
+
+## Development
+
+```sh
+cd packages/pi-neutrasearch
+npm test
+pi -e .
+```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,152 @@
+import { compactSearchResult, limits, queryArguments, resolveNeutrasearch, resolveScope } from "./lib.js";
+
+const TOOL_NAME = "neutrasearch";
+
+function shortError(value, max = 1600) {
+  const text = String(value || "unknown error").replace(/\s+/g, " ").trim();
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+function result(text, details = {}) {
+  return { content: [{ type: "text", text }], details };
+}
+
+function status(binary) {
+  if (!binary) {
+    return {
+      ok: false,
+      tool: TOOL_NAME,
+      error: "Neutrasearch executable not found",
+      setup: "Install Neutrasearch, or set NEUTRASEARCH_QUERY / NEUTRASEARCH_BIN.",
+      token_defaults: { limit: limits.defaultLimit, max_chars: limits.defaultMaxChars },
+    };
+  }
+  return {
+    ok: true,
+    tool: TOOL_NAME,
+    executable: binary.command,
+    executable_kind: binary.kind,
+    index: process.env.NEUTRASEARCH_INDEX || "platform default",
+    default_scope: "current Pi workspace",
+    extra_scope_env: "NEUTRASEARCH_PI_ALLOWED_ROOTS",
+    token_defaults: {
+      limit: limits.defaultLimit,
+      max_chars: limits.defaultMaxChars,
+      relative_paths: true,
+      metadata: false,
+    },
+    safety: "read-only index query; never scans, indexes, elevates, writes, or uses the network",
+  };
+}
+
+async function search(pi, params, signal, ctx) {
+  if (!String(params.query || "").trim()) throw new Error("query is required for action=search");
+  const binary = resolveNeutrasearch();
+  if (!binary) {
+    throw new Error(
+      "Neutrasearch executable not found. Install Neutrasearch or set NEUTRASEARCH_QUERY / NEUTRASEARCH_BIN.",
+    );
+  }
+  const { scope } = resolveScope(params.scope, ctx.cwd);
+  const { args, limit } = queryArguments(params, scope);
+  const timeout = Math.max(1000, Math.min(30000, Math.trunc(Number(params.timeout_ms) || 10000)));
+  const execution = await pi.exec(binary.command, [...binary.prefix, ...args], {
+    cwd: ctx.cwd,
+    signal,
+    timeout,
+  });
+  if (execution.code !== 0) {
+    throw new Error(`Neutrasearch exited ${execution.code}: ${shortError(execution.stderr || execution.stdout)}`);
+  }
+  let payload;
+  try {
+    payload = JSON.parse(execution.stdout);
+  } catch {
+    throw new Error(`Neutrasearch returned non-JSON output: ${shortError(execution.stdout)}`);
+  }
+  const compact = compactSearchResult(payload, {
+    scope,
+    relative: params.relative_paths !== false,
+    metadata: Boolean(params.metadata),
+    maxChars: params.max_chars,
+  });
+  return result(compact.text, {
+    ...compact.details,
+    query: params.query,
+    limit,
+    executable_kind: binary.kind,
+    token_efficient: true,
+  });
+}
+
+const PARAMETERS = {
+  type: "object",
+  properties: {
+    action: {
+      enum: ["search", "status"],
+      description: "search (default) or status.",
+    },
+    query: {
+      type: "string",
+      description: "Filename/path query. Supports ext:, kind:, fs:, size:, and quoted terms.",
+    },
+    scope: {
+      type: "string",
+      description: "Existing directory inside the current workspace. Defaults to the workspace root.",
+    },
+    limit: {
+      type: "integer",
+      minimum: 1,
+      maximum: limits.maxLimit,
+      description: `Maximum matches. Default ${limits.defaultLimit}; keep small for token efficiency.`,
+    },
+    relative_paths: {
+      type: "boolean",
+      description: "Return paths relative to scope. Default true.",
+    },
+    metadata: {
+      type: "boolean",
+      description: "Include kind, size, and mtime columns. Default false.",
+    },
+    max_chars: {
+      type: "integer",
+      minimum: 500,
+      maximum: limits.maxOutputChars,
+      description: `Hard output budget. Default ${limits.defaultMaxChars}.`,
+    },
+    timeout_ms: {
+      type: "integer",
+      minimum: 1000,
+      maximum: 30000,
+      description: "Query timeout. Default 10000.",
+    },
+  },
+  additionalProperties: false,
+};
+
+export default function register(pi) {
+  pi.registerTool({
+    name: TOOL_NAME,
+    label: "Neutrasearch",
+    description:
+      "Token-efficient, read-only indexed filename/path search. Prefer this over find or broad filesystem scans when locating files. It does not search file contents; use grep only after locating candidate files.",
+    parameters: PARAMETERS,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const action = String(params?.action || "search");
+      if (action === "status") {
+        const current = status(resolveNeutrasearch());
+        return result(JSON.stringify(current), current);
+      }
+      if (action !== "search") throw new Error(`unknown action: ${action}`);
+      return search(pi, params || {}, signal, ctx);
+    },
+  });
+
+  pi.registerCommand("neutrasearch", {
+    description: "Show Neutrasearch Pi integration status",
+    handler: async (_args, ctx) => {
+      const current = status(resolveNeutrasearch());
+      ctx.ui.notify(current.ok ? `Neutrasearch ready: ${current.executable}` : current.error, current.ok ? "info" : "warning");
+    },
+  });
+}

package/lib.js

@@ -0,0 +1,181 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 200;
+const DEFAULT_MAX_CHARS = 6000;
+const MAX_OUTPUT_CHARS = 30000;
+
+function clampInteger(value, fallback, minimum, maximum) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(minimum, Math.min(maximum, Math.trunc(parsed)));
+}
+
+function executableNames(name, platform = process.platform, pathExt = process.env.PATHEXT) {
+  if (platform !== "win32" || path.extname(name)) return [name];
+  const extensions = (pathExt || ".EXE;.CMD;.BAT;.COM")
+    .split(";")
+    .filter(Boolean)
+    .map((extension) => extension.toLowerCase());
+  return [name, ...extensions.map((extension) => `${name}${extension}`)];
+}
+
+function canExecute(candidate, platform = process.platform) {
+  try {
+    fs.accessSync(candidate, platform === "win32" ? fs.constants.F_OK : fs.constants.X_OK);
+    return fs.statSync(candidate).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function findOnPath(command, env = process.env, platform = process.platform) {
+  if (path.isAbsolute(command) || command.includes("/") || command.includes("\\")) {
+    const expanded = command.startsWith("~/") ? path.join(os.homedir(), command.slice(2)) : command;
+    return canExecute(expanded, platform) ? path.resolve(expanded) : null;
+  }
+  const pathValue = env.PATH || env.Path || env.path || "";
+  for (const directory of pathValue.split(path.delimiter).filter(Boolean)) {
+    for (const name of executableNames(command, platform, env.PATHEXT)) {
+      const candidate = path.join(directory.replace(/^~(?=$|[\\/])/, os.homedir()), name);
+      if (canExecute(candidate, platform)) return candidate;
+    }
+  }
+  return null;
+}
+
+export function resolveNeutrasearch(env = process.env, platform = process.platform) {
+  const candidates = [
+    env.NEUTRASEARCH_QUERY
+      ? { command: env.NEUTRASEARCH_QUERY, prefix: [], kind: "query" }
+      : null,
+    { command: "neutrasearch-query", prefix: [], kind: "query" },
+    env.NEUTRASEARCH_BIN
+      ? { command: env.NEUTRASEARCH_BIN, prefix: ["search"], kind: "launcher" }
+      : null,
+    { command: "neutrasearch", prefix: ["search"], kind: "launcher" },
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    const resolved = findOnPath(candidate.command, env, platform);
+    if (resolved) return { ...candidate, command: resolved };
+  }
+  return null;
+}
+
+function canonicalDirectory(input) {
+  const resolved = fs.realpathSync(path.resolve(input));
+  if (!fs.statSync(resolved).isDirectory()) throw new Error(`scope is not a directory: ${input}`);
+  return resolved;
+}
+
+function comparable(value, platform = process.platform) {
+  const normalized = path.resolve(value).replace(/[\\/]+$/, "");
+  return platform === "win32" || platform === "darwin" ? normalized.toLowerCase() : normalized;
+}
+
+export function pathIsInside(candidate, root, platform = process.platform) {
+  const normalizedCandidate = comparable(candidate, platform);
+  const normalizedRoot = comparable(root, platform);
+  if (normalizedCandidate === normalizedRoot) return true;
+  return normalizedCandidate.startsWith(`${normalizedRoot}${path.sep}`);
+}
+
+export function resolveScope(requested, cwd, env = process.env, platform = process.platform) {
+  const workspace = canonicalDirectory(cwd);
+  const configured = String(env.NEUTRASEARCH_PI_ALLOWED_ROOTS || "")
+    .split(path.delimiter)
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map(canonicalDirectory);
+  const allowed = [workspace, ...configured];
+  const scope = canonicalDirectory(requested || workspace);
+  if (!allowed.some((root) => pathIsInside(scope, root, platform))) {
+    throw new Error(
+      "scope is outside this Pi workspace; add its canonical root to NEUTRASEARCH_PI_ALLOWED_ROOTS to opt in",
+    );
+  }
+  return { scope, workspace, allowed };
+}
+
+function pathForOutput(candidate, scope, relative) {
+  if (!relative) return candidate;
+  const rel = path.relative(scope, candidate);
+  return rel || ".";
+}
+
+export function compactSearchResult(payload, options) {
+  if (!payload || !Array.isArray(payload.paths)) throw new Error("Neutrasearch returned invalid JSON");
+  const scope = options.scope;
+  const relative = options.relative !== false;
+  const maxChars = clampInteger(options.maxChars, DEFAULT_MAX_CHARS, 500, MAX_OUTPUT_CHARS);
+  const recordsByPath = new Map(
+    Array.isArray(payload.records) ? payload.records.map((record) => [record.path, record]) : [],
+  );
+  const safe = [];
+  let rejected = 0;
+  for (const candidate of payload.paths) {
+    if (typeof candidate !== "string" || !path.isAbsolute(candidate) || !pathIsInside(candidate, scope)) {
+      rejected += 1;
+      continue;
+    }
+    safe.push(candidate);
+  }
+
+  const lines = [
+    `scope=${scope}`,
+    `matched=${Number(payload.matched || 0)} returned=${safe.length} search_us=${Number(payload.search_us || 0)}`,
+  ];
+  let omittedByBudget = 0;
+  for (let index = 0; index < safe.length; index += 1) {
+    const candidate = safe[index];
+    const record = recordsByPath.get(candidate);
+    const displayPath = pathForOutput(candidate, scope, relative);
+    const line = options.metadata && record
+      ? `${displayPath}\t${record.kind}\t${record.size}\t${record.mtime}`
+      : displayPath;
+    if (lines.join("\n").length + line.length + 1 > maxChars) {
+      omittedByBudget = safe.length - index;
+      break;
+    }
+    lines.push(line);
+  }
+  if (omittedByBudget || rejected) {
+    lines.push(`omitted_budget=${omittedByBudget} rejected_outside_scope=${rejected}`);
+  }
+  return {
+    text: lines.join("\n"),
+    details: {
+      scope,
+      matched: Number(payload.matched || 0),
+      returned: safe.length,
+      emitted: safe.length - omittedByBudget,
+      omitted_by_budget: omittedByBudget,
+      rejected_outside_scope: rejected,
+      search_us: Number(payload.search_us || 0),
+    },
+  };
+}
+
+export function queryArguments(params, scope, env = process.env) {
+  const limit = clampInteger(params.limit, DEFAULT_LIMIT, 1, MAX_LIMIT);
+  const args = [
+    String(params.query || ""),
+    "--scope",
+    scope,
+    "--limit",
+    String(limit),
+    params.metadata ? "--json" : "--json-paths",
+  ];
+  if (env.NEUTRASEARCH_INDEX) args.push("--index", env.NEUTRASEARCH_INDEX);
+  return { args, limit };
+}
+
+export const limits = {
+  defaultLimit: DEFAULT_LIMIT,
+  maxLimit: MAX_LIMIT,
+  defaultMaxChars: DEFAULT_MAX_CHARS,
+  maxOutputChars: MAX_OUTPUT_CHARS,
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "pi-neutrasearch",
+  "version": "0.1.0",
+  "description": "Token-efficient native indexed filename and path search for Pi agents",
+  "type": "module",
+  "license": "MIT",
+  "author": "NetroAki",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "neutrasearch",
+    "file-search",
+    "indexed-search",
+    "agent-tools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NetroAki/neutrasearch.git",
+    "directory": "packages/pi-neutrasearch"
+  },
+  "homepage": "https://github.com/NetroAki/neutrasearch#pi-package",
+  "bugs": {
+    "url": "https://github.com/NetroAki/neutrasearch/issues"
+  },
+  "files": [
+    "index.js",
+    "lib.js",
+    "README.md",
+    "LICENSE",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "npm test"
+  },
+  "pi": {
+    "extensions": [
+      "./index.js"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/skills/neutrasearch/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: use-neutrasearch
+description: Locate filenames and paths through the local Neutrasearch index instead of walking the filesystem
+---
+
+# Use Neutrasearch
+
+Use the `neutrasearch` tool before `find`, directory walking, or broad globbing when the task is to locate files or folders by name, extension, type, size, or indexed path.
+
+## Token-efficient defaults
+
+1. Start with `limit: 20`, `relative_paths: true`, and `metadata: false`.
+2. Scope defaults to the current Pi workspace. Narrow `scope` further when possible.
+3. Refine with query filters such as `ext:rs,toml`, `kind:file`, `kind:dir`, `size:>10M`, or quoted terms before increasing the limit.
+4. Request metadata only when size, kind, filesystem, or modification time is needed.
+5. Increase `max_chars` or `limit` only after a narrow query still omits needed candidates.
+
+## Boundary
+
+Neutrasearch searches indexed metadata—filenames and paths—not file contents. After locating a small candidate set, use `read` or targeted `grep` for content inspection.
+
+The tool is read-only. It must not initiate indexing, request privileges, write files, or contact the network. Outside-workspace searches require the user to pre-authorize canonical roots through `NEUTRASEARCH_PI_ALLOWED_ROOTS`.