@nmzpy/pi-ember-stack 0.1.6 → 0.2.2

package/plugins/pi-ember-fff/query.ts

@@ -0,0 +1,247 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ---------------------------------------------------------------------------
+// External allowlist — auto-detected pi-coding-agent package directory
+// ---------------------------------------------------------------------------
+
+/** The default alias for the pi-coding-agent package. */
+export const PI_CODING_AGENT_ALIAS = "pi-coding-agent";
+
+export type ExternalAllowlistEntry = {
+  /** User-facing alias, e.g. "pi-coding-agent" (no leading ./). */
+  alias: string;
+  /** Auto-detected absolute directory. */
+  dir: string;
+};
+
+export type ExternalAllowlist = {
+  entries: readonly ExternalAllowlistEntry[];
+  /** Resolve a user-facing path constraint to an allowlisted dir, or undefined. */
+  resolve(pathConstraint: string): ExternalAllowlistEntry | undefined;
+  /** True if an absolute path is inside an allowlisted dir. */
+  covers(absolutePath: string): boolean;
+};
+
+export type ExternalTarget = {
+  entry: ExternalAllowlistEntry;
+  /** Path relative to entry.dir, forward-slashed, no leading ./, or "" for the whole dir. */
+  relativePath: string;
+};
+
+/**
+ * Auto-detect the installed @earendil-works/pi-coding-agent package root.
+ * Returns undefined if detection fails (package not installed or
+ * import.meta.resolve unavailable).
+ */
+function detect_pi_package_dir(): string | undefined {
+  try {
+    const resolved = import.meta.resolve("@earendil-works/pi-coding-agent");
+    const entryPath = fileURLToPath(resolved); // .../dist/index.js
+    return path.dirname(path.dirname(entryPath)); // package root (parent of dist/)
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Build the external allowlist by auto-detecting the installed
+ * @earendil-works/pi-coding-agent package directory. Returns an empty
+ * allowlist if detection fails (fail-safe: no external access).
+ */
+export function buildExternalAllowlist(): ExternalAllowlist {
+  const dir = detect_pi_package_dir();
+  const entries: ExternalAllowlistEntry[] = [];
+  if (dir) {
+    entries.push({ alias: PI_CODING_AGENT_ALIAS, dir });
+  }
+  return {
+    entries,
+    resolve(pathConstraint: string): ExternalAllowlistEntry | undefined {
+      let trimmed = pathConstraint.trim();
+      if (!trimmed) return undefined;
+      if (trimmed.startsWith("./")) trimmed = trimmed.slice(2);
+      for (const entry of entries) {
+        if (trimmed === entry.alias) return entry;
+        if (
+          trimmed.startsWith(entry.alias + "/") ||
+          trimmed.startsWith(entry.alias + path.sep)
+        ) {
+          return entry;
+        }
+      }
+      return undefined;
+    },
+    covers(absolutePath: string): boolean {
+      for (const entry of entries) {
+        const rel = path.relative(entry.dir, absolutePath);
+        if (rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel))) {
+          return true;
+        }
+      }
+      return false;
+    },
+  };
+}
+
+/**
+ * If `pathConstraint` targets an allowlisted external directory, return
+ * the resolved entry and the sub-path relative to that dir. Otherwise
+ * undefined. This lets the tool layer route to a secondary FileFinder
+ * before normalization.
+ */
+export function resolveExternalTarget(
+  pathConstraint: string | undefined,
+  allowlist: ExternalAllowlist,
+): ExternalTarget | undefined {
+  if (!pathConstraint) return undefined;
+  let trimmed = pathConstraint.trim();
+  if (!trimmed) return undefined;
+
+  // Absolute path — check if it's under an allowlisted dir.
+  if (path.isAbsolute(trimmed)) {
+    if (!allowlist.covers(trimmed)) return undefined;
+    for (const entry of allowlist.entries) {
+      const rel = path.relative(entry.dir, trimmed).replaceAll(path.sep, "/");
+      if (rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel))) {
+        return { entry, relativePath: rel };
+      }
+    }
+    return undefined;
+  }
+
+  // Strip leading ./
+  if (trimmed.startsWith("./")) trimmed = trimmed.slice(2);
+
+  // Alias-prefixed relative path
+  for (const entry of allowlist.entries) {
+    if (trimmed === entry.alias) {
+      return { entry, relativePath: "" };
+    }
+    // Check alias/ or alias\ as a prefix (cross-platform)
+    const aliasPrefixFwd = entry.alias + "/";
+    const aliasPrefixSep = entry.alias + path.sep;
+    if (trimmed.startsWith(aliasPrefixFwd) || trimmed.startsWith(aliasPrefixSep)) {
+      // Normalize to forward slashes for FFF
+      const remainder = trimmed.startsWith(aliasPrefixFwd)
+        ? trimmed.slice(aliasPrefixFwd.length)
+        : trimmed.slice(aliasPrefixSep.length).replaceAll(path.sep, "/");
+      return { entry, relativePath: remainder };
+    }
+  }
+
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Path constraint normalization
+// ---------------------------------------------------------------------------
+
+export function normalizePathConstraint(
+  pathConstraint: string,
+  cwd = process.cwd(),
+  allowlist?: ExternalAllowlist,
+): string | null {
+  let trimmed = pathConstraint.trim();
+  if (!trimmed) return trimmed;
+
+  if (path.isAbsolute(trimmed)) {
+    // Allowlisted external absolute path — do not throw.
+    if (allowlist?.covers(trimmed)) {
+      const target = resolveExternalTarget(trimmed, allowlist);
+      if (target) {
+        // Return the relative path within the allowlisted dir.
+        // If bare dir, return null (whole dir). Otherwise return the
+        // relative subpath forward-slashed.
+        if (!target.relativePath) return null;
+        trimmed = target.relativePath;
+        // Jump to the post-absolute-path normalization logic below.
+      }
+    } else {
+      const relative = path.relative(cwd, trimmed).replaceAll(path.sep, "/");
+      if (relative === "") return null;
+      if (relative.startsWith("../") || relative === ".." || path.isAbsolute(relative)) {
+        throw new Error(
+          `Path constraint must be relative to the workspace: ${pathConstraint}`,
+        );
+      }
+      trimmed = relative;
+    }
+  } else if (allowlist) {
+    // Check for alias-prefixed relative path (e.g. ./pi-coding-agent/docs).
+    const target = resolveExternalTarget(trimmed, allowlist);
+    if (target) {
+      if (!target.relativePath) return null;
+      trimmed = target.relativePath;
+    }
+  }
+
+  if (trimmed === "." || trimmed === "./") return null;
+  // Strip a leading `./` so `./**/*.rs` and `**/*.rs` behave identically.
+  if (trimmed.startsWith("./")) trimmed = trimmed.slice(2);
+
+  // FFF's glob matcher can treat a hidden directory root glob such as
+  // `.agents/**` as empty, while the tool contract says this means "inside
+  // this directory". Collapse simple trailing recursive directory globs to the
+  // directory-prefix constraint understood by the parser. Keep real file globs
+  // such as `src/**/*.ts` unchanged.
+  const recursiveDir = trimmed.match(/^(.*)\/\*\*(?:\/\*)?$/);
+  if (recursiveDir) {
+    const dir = recursiveDir[1];
+    if (dir && !/[*?[{]/.test(dir)) return `${dir}/`;
+  }
+
+  // Already signals path-constraint syntax to the parser.
+  if (trimmed.startsWith("/") || trimmed.endsWith("/")) return trimmed;
+  // Globs (`*.ts`, `src/**/*.cc`, `{src,lib}`) are handled by the parser.
+  if (/[*?[{]/.test(trimmed)) return trimmed;
+  // Filename with extension (`main.rs`, `config.json`) → FilePath constraint.
+  const lastSegment = trimmed.split("/").pop() ?? "";
+  if (/\.[a-zA-Z][a-zA-Z0-9]{0,9}$/.test(lastSegment)) return trimmed;
+  // Bare directory prefix → append `/` so the parser sees a PathSegment.
+  return `${trimmed}/`;
+}
+
+// Exclusions are emitted as `!<constraint>` tokens, which the Rust parser
+// understands (crates/fff-query-parser/src/parser.rs). We normalize each one
+// the same way as the include path so bare dirs become PathSegment excludes.
+// Tolerate callers passing already-negated forms like `!src/` by stripping
+// the leading `!` before normalizing so we never double-negate (`!!src/`).
+export function normalizeExcludes(
+  exclude: string | string[] | undefined,
+  cwd = process.cwd(),
+  allowlist?: ExternalAllowlist,
+): string[] {
+  if (!exclude) return [];
+  const list = Array.isArray(exclude) ? exclude : [exclude];
+  const out: string[] = [];
+  for (const raw of list) {
+    const parts = raw
+      .split(/[,\s]+/)
+      .map((s) => s.trim())
+      .filter(Boolean);
+    for (const p of parts) {
+      const stripped = p.startsWith("!") ? p.slice(1) : p;
+      const normalized = normalizePathConstraint(stripped, cwd, allowlist);
+      if (normalized) out.push(`!${normalized}`);
+    }
+  }
+  return out;
+}
+
+export function buildQuery(
+  path: string | undefined,
+  pattern: string,
+  exclude?: string | string[],
+  cwd = process.cwd(),
+  allowlist?: ExternalAllowlist,
+): string {
+  const parts: string[] = [];
+  if (path) {
+    const pathConstraint = normalizePathConstraint(path, cwd, allowlist);
+    if (pathConstraint) parts.push(pathConstraint);
+  }
+  parts.push(...normalizeExcludes(exclude, cwd, allowlist));
+  parts.push(pattern);
+  return parts.join(" ");
+}

package/plugins/pi-ember-fff/test/query.test.ts

@@ -0,0 +1,222 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import {
+	normalizePathConstraint,
+	normalizeExcludes,
+	buildQuery,
+	buildExternalAllowlist,
+	resolveExternalTarget,
+	PI_CODING_AGENT_ALIAS,
+} from "../query.ts";
+
+describe("normalizePathConstraint", () => {
+	test("empty string returns empty", () => {
+		expect(normalizePathConstraint("")).toBe("");
+	});
+
+	test("dot returns null", () => {
+		expect(normalizePathConstraint(".")).toBeNull();
+		expect(normalizePathConstraint("./")).toBeNull();
+	});
+
+	test("bare directory gets trailing slash", () => {
+		expect(normalizePathConstraint("src")).toBe("src/");
+	});
+
+	test("glob is preserved", () => {
+		expect(normalizePathConstraint("*.ts")).toBe("*.ts");
+		expect(normalizePathConstraint("src/**/*.cc")).toBe("src/**/*.cc");
+	});
+
+	test("filename with extension is preserved", () => {
+		expect(normalizePathConstraint("main.rs")).toBe("main.rs");
+	});
+
+	test("recursive dir glob collapses to prefix", () => {
+		expect(normalizePathConstraint("src/**")).toBe("src/");
+		expect(normalizePathConstraint("src/**/*")).toBe("src/");
+	});
+
+	test("leading ./ is stripped", () => {
+		expect(normalizePathConstraint("./src")).toBe("src/");
+	});
+});
+
+describe("normalizeExcludes", () => {
+	test("undefined returns empty array", () => {
+		expect(normalizeExcludes(undefined)).toEqual([]);
+	});
+
+	test("comma-separated string is split", () => {
+		expect(normalizeExcludes("test/, *.min.js")).toEqual(["!test/", "!*.min.js"]);
+	});
+
+	test("leading ! is tolerated", () => {
+		expect(normalizeExcludes("!src/")).toEqual(["!src/"]);
+	});
+
+	test("array input works", () => {
+		expect(normalizeExcludes(["test/", "vendor/"])).toEqual(["!test/", "!vendor/"]);
+	});
+});
+
+describe("buildQuery", () => {
+	test("assembles path + excludes + pattern", () => {
+		const q = buildQuery("src/", "MyClass", "test/");
+		expect(q).toContain("src/");
+		expect(q).toContain("!test/");
+		expect(q).toContain("MyClass");
+	});
+
+	test("no path or excludes yields just pattern", () => {
+		expect(buildQuery(undefined, "foo")).toBe("foo");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// ExternalAllowlist — auto-detection and resolveExternalTarget
+// ---------------------------------------------------------------------------
+
+describe("ExternalAllowlist", () => {
+	const allowlist = buildExternalAllowlist();
+	const has_entries = allowlist.entries.length > 0;
+	const cwd = process.cwd();
+
+	test("buildExternalAllowlist auto-detects the package dir", () => {
+		expect(allowlist.entries.length).toBeGreaterThanOrEqual(1);
+		expect(allowlist.entries[0].alias).toBe(PI_CODING_AGENT_ALIAS);
+		expect(path.isAbsolute(allowlist.entries[0].dir)).toBe(true);
+	});
+
+	test("resolveExternalTarget with ./pi-coding-agent alias → bare dir", () => {
+		if (!has_entries) return;
+		const target = resolveExternalTarget("./pi-coding-agent", allowlist);
+		expect(target).toBeDefined();
+		expect(target!.entry.alias).toBe(PI_CODING_AGENT_ALIAS);
+		expect(target!.relativePath).toBe("");
+	});
+
+	test("resolveExternalTarget with pi-coding-agent alias (no ./) → bare dir", () => {
+		if (!has_entries) return;
+		const target = resolveExternalTarget("pi-coding-agent", allowlist);
+		expect(target).toBeDefined();
+		expect(target!.entry.alias).toBe(PI_CODING_AGENT_ALIAS);
+		expect(target!.relativePath).toBe("");
+	});
+
+	test("resolveExternalTarget with ./pi-coding-agent/docs → subpath", () => {
+		if (!has_entries) return;
+		const target = resolveExternalTarget("./pi-coding-agent/docs", allowlist);
+		expect(target).toBeDefined();
+		expect(target!.entry.alias).toBe(PI_CODING_AGENT_ALIAS);
+		expect(target!.relativePath).toBe("docs");
+	});
+
+	test("resolveExternalTarget with ./pi-coding-agent/docs/extensions.md → deep subpath", () => {
+		if (!has_entries) return;
+		const target = resolveExternalTarget(
+			"./pi-coding-agent/docs/extensions.md",
+			allowlist,
+		);
+		expect(target).toBeDefined();
+		expect(target!.entry.alias).toBe(PI_CODING_AGENT_ALIAS);
+		expect(target!.relativePath).toBe("docs/extensions.md");
+	});
+
+	test("resolveExternalTarget with absolute path under allowlisted dir", () => {
+		if (!has_entries) return;
+		const abs = path.join(allowlist.entries[0].dir, "docs", "extensions.md");
+		const target = resolveExternalTarget(abs, allowlist);
+		expect(target).toBeDefined();
+		expect(target!.entry.alias).toBe(PI_CODING_AGENT_ALIAS);
+		expect(target!.relativePath).toBe("docs/extensions.md");
+	});
+
+	test("resolveExternalTarget returns undefined for workspace-relative src/", () => {
+		expect(resolveExternalTarget("src/", allowlist)).toBeUndefined();
+	});
+
+	test("resolveExternalTarget returns undefined for ./src", () => {
+		expect(resolveExternalTarget("./src", allowlist)).toBeUndefined();
+	});
+
+	test("resolveExternalTarget returns undefined for undefined input", () => {
+		expect(resolveExternalTarget(undefined, allowlist)).toBeUndefined();
+	});
+
+	test("resolveExternalTarget returns undefined for empty string", () => {
+		expect(resolveExternalTarget("", allowlist)).toBeUndefined();
+	});
+
+	test("resolveExternalTarget returns undefined for alias-prefix mismatch (pi-coding-agent-foo)", () => {
+		expect(resolveExternalTarget("pi-coding-agent-foo", allowlist)).toBeUndefined();
+	});
+});
+
+// ---------------------------------------------------------------------------
+// normalizePathConstraint with allowlist
+// ---------------------------------------------------------------------------
+
+describe("normalizePathConstraint with allowlist", () => {
+	const allowlist = buildExternalAllowlist();
+	const has_entries = allowlist.entries.length > 0;
+	const cwd = process.cwd();
+
+	test("allowlisted ./pi-coding-agent → null (bare dir)", () => {
+		if (!has_entries) return;
+		expect(normalizePathConstraint("./pi-coding-agent", cwd, allowlist)).toBeNull();
+	});
+
+	test("allowlisted ./pi-coding-agent/docs → docs/ (trailing slash)", () => {
+		if (!has_entries) return;
+		expect(normalizePathConstraint("./pi-coding-agent/docs", cwd, allowlist)).toBe("docs/");
+	});
+
+	test("allowlisted ./pi-coding-agent/docs/extensions.md → preserved filename", () => {
+		if (!has_entries) return;
+		expect(
+			normalizePathConstraint("./pi-coding-agent/docs/extensions.md", cwd, allowlist),
+		).toBe("docs/extensions.md");
+	});
+
+	test("allowlisted absolute path under package dir → relative with trailing slash", () => {
+		if (!has_entries) return;
+		const abs = path.join(allowlist.entries[0].dir, "docs");
+		expect(normalizePathConstraint(abs, cwd, allowlist)).toBe("docs/");
+	});
+
+	test("non-allowlisted absolute path /etc/passwd → throws", () => {
+		expect(() => normalizePathConstraint("/etc/passwd", cwd, allowlist)).toThrow(
+			"Path constraint must be relative to the workspace: /etc/passwd",
+		);
+	});
+
+	test("workspace-relative src → src/ (unchanged with allowlist)", () => {
+		expect(normalizePathConstraint("src", cwd, allowlist)).toBe("src/");
+	});
+
+	test("workspace-relative glob *.ts → *.ts (unchanged with allowlist)", () => {
+		expect(normalizePathConstraint("*.ts", cwd, allowlist)).toBe("*.ts");
+	});
+
+	test("workspace-relative dot → null (unchanged with allowlist)", () => {
+		expect(normalizePathConstraint(".", cwd, allowlist)).toBeNull();
+	});
+});
+
+// ---------------------------------------------------------------------------
+// buildQuery with external target
+// ---------------------------------------------------------------------------
+
+describe("buildQuery with external target", () => {
+	const allowlist = buildExternalAllowlist();
+	const has_entries = allowlist.entries.length > 0;
+	const cwd = process.cwd();
+
+	test("buildQuery with ./pi-coding-agent/docs includes docs/ and pattern", () => {
+		if (!has_entries) return;
+		const q = buildQuery("./pi-coding-agent/docs", "renderCall", undefined, cwd, allowlist);
+		expect(q).toContain("docs/");
+		expect(q).toContain("renderCall");
+	});
+});