@nebutra/agent-runtime 0.2.1 → 2.0.0

package/src/command-suggestions.test.ts

@@ -1,251 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  classifyMatch,
-  dedupeByText,
-  type FuzzyMatchFn,
-  historyCandidates,
-  InMemorySuggestionHistoryStore,
-  rankSuggestions,
-  recordHistory,
-  type SuggestionItem,
-} from "./command-suggestions.js";
-
-const T = "tenant_a";
-
-/** Deterministic fake matcher: subsequence with fixed score, recorded indices. */
-const fakeFuzzy: FuzzyMatchFn = (text, query) => {
-  if (query === "") return null;
-  const lowerText = text.toLowerCase();
-  const lowerQuery = query.toLowerCase();
-  const indices: number[] = [];
-  let cursor = 0;
-  for (const ch of lowerQuery) {
-    const found = lowerText.indexOf(ch, cursor);
-    if (found === -1) return null;
-    indices.push(found);
-    cursor = found + 1;
-  }
-  return { score: 10, indices };
-};
-
-/** Matcher that returns a huge score, used to prove exact/prefix banding wins. */
-const hugeScoreFuzzy: FuzzyMatchFn = (text, query) => {
-  if (query === "") return null;
-  if (text.toLowerCase().includes(query.toLowerCase())) {
-    return { score: 1_000_000, indices: [0] };
-  }
-  return null;
-};
-
-const neverFuzzy: FuzzyMatchFn = () => null;
-
-function item(id: string, text: string, overrides: Partial<SuggestionItem> = {}): SuggestionItem {
-  return {
-    id,
-    text,
-    type: overrides.type ?? "completion",
-    isHistory: overrides.isHistory ?? false,
-    detail: overrides.detail,
-  };
-}
-
-describe("classifyMatch", () => {
-  it("returns exact for case-insensitive full equality with the highest band", () => {
-    const r = classifyMatch("Deploy", "deploy", fakeFuzzy);
-    expect(r.matchType).toBe("exact");
-    expect(r.score).toBeGreaterThan(0);
-    expect(r.indices).toEqual([0, 1, 2, 3, 4, 5]);
-  });
-
-  it("returns prefix when text starts with query (ci) but is not equal", () => {
-    const r = classifyMatch("deploy-prod", "deploy", fakeFuzzy);
-    expect(r.matchType).toBe("prefix");
-    expect(r.indices).toEqual([0, 1, 2, 3, 4, 5]);
-  });
-
-  it("delegates to injected fuzzy when neither exact nor prefix", () => {
-    const r = classifyMatch("git deploy", "dpl", fakeFuzzy);
-    expect(r.matchType).toBe("fuzzy");
-    expect(r.score).toBe(10);
-    expect(r.indices.length).toBe(3);
-  });
-
-  it("returns none when fuzzy returns null", () => {
-    const r = classifyMatch("git status", "zzz", neverFuzzy);
-    expect(r.matchType).toBe("none");
-    expect(r.score).toBe(0);
-    expect(r.indices).toEqual([]);
-  });
-
-  it("bands exact > prefix > fuzzy regardless of fuzzy magnitude", () => {
-    const exact = classifyMatch("deploy", "deploy", hugeScoreFuzzy);
-    const prefix = classifyMatch("deploy-prod", "deploy", hugeScoreFuzzy);
-    const fuzzy = classifyMatch("xx-deploy", "deploy", hugeScoreFuzzy);
-    expect(fuzzy.matchType).toBe("fuzzy");
-    expect(fuzzy.score).toBe(1_000_000);
-    expect(prefix.score).toBeGreaterThan(fuzzy.score);
-    expect(exact.score).toBeGreaterThan(prefix.score);
-  });
-
-  it("empty query yields none/0/[]", () => {
-    const r = classifyMatch("anything", "", fakeFuzzy);
-    expect(r.matchType).toBe("none");
-    expect(r.score).toBe(0);
-    expect(r.indices).toEqual([]);
-  });
-});
-
-describe("rankSuggestions", () => {
-  it("throws on empty tenantId (fail-closed)", () => {
-    expect(() => rankSuggestions("", "q", [], fakeFuzzy)).toThrow();
-    expect(() => rankSuggestions("   ", "q", [], fakeFuzzy)).toThrow();
-  });
-
-  it("drops 'none' matches when query is non-empty", () => {
-    const candidates = [item("1", "deploy"), item("2", "totally-unrelated")];
-    const out = rankSuggestions(T, "deploy", candidates, neverFuzzy);
-    expect(out.results.map((r) => r.item.id)).toEqual(["1"]);
-    expect(out.query).toBe("deploy");
-  });
-
-  it("keeps all candidates when query is empty", () => {
-    const candidates = [item("1", "alpha"), item("2", "beta")];
-    const out = rankSuggestions(T, "", candidates, neverFuzzy);
-    expect(out.results.length).toBe(2);
-    expect(out.results.every((r) => r.matchType === "none")).toBe(true);
-  });
-
-  it("applies history boost when scores tie", () => {
-    const candidates = [
-      item("plain", "deploy app", { isHistory: false }),
-      item("hist", "deploy app", { isHistory: true }),
-    ];
-    const out = rankSuggestions(T, "deploy", candidates, fakeFuzzy);
-    expect(out.results[0]?.item.id).toBe("hist");
-  });
-
-  it("shorter text wins when score and history tie", () => {
-    const candidates = [
-      item("long", "deployment longer", { isHistory: true }),
-      item("short", "deploy app", { isHistory: true }),
-    ];
-    const out = rankSuggestions(T, "deploy", candidates, fakeFuzzy);
-    expect(out.results[0]?.item.id).toBe("short");
-  });
-
-  it("is stable on full ties (input order preserved)", () => {
-    const candidates = [
-      item("a", "same text", { isHistory: false }),
-      item("b", "same text", { isHistory: false }),
-      item("c", "same text", { isHistory: false }),
-    ];
-    const out = rankSuggestions(T, "same text", candidates, fakeFuzzy);
-    expect(out.results.map((r) => r.item.id)).toEqual(["a", "b", "c"]);
-  });
-
-  it("caps to opts.limit and defaults to 50", () => {
-    const many = Array.from({ length: 80 }, (_, i) => item(String(i), `deploy ${i}`));
-    const capped = rankSuggestions(T, "deploy", many, fakeFuzzy, { limit: 5 });
-    expect(capped.results.length).toBe(5);
-    const def = rankSuggestions(T, "deploy", many, fakeFuzzy);
-    expect(def.results.length).toBe(50);
-  });
-
-  it("orders exact above prefix above fuzzy", () => {
-    const candidates = [
-      item("fuzzy", "xx-deploy"),
-      item("exact", "deploy"),
-      item("prefix", "deploy-prod"),
-    ];
-    const out = rankSuggestions(T, "deploy", candidates, fakeFuzzy);
-    expect(out.results.map((r) => r.item.id)).toEqual(["exact", "prefix", "fuzzy"]);
-  });
-
-  it("does not mutate the input candidates array", () => {
-    const candidates = [item("2", "beta"), item("1", "alpha")];
-    const snapshot = candidates.map((c) => ({ ...c }));
-    rankSuggestions(T, "a", candidates, fakeFuzzy);
-    expect(candidates).toEqual(snapshot);
-  });
-});
-
-describe("dedupeByText", () => {
-  it("keeps first occurrence per normalized text", () => {
-    const out = dedupeByText([
-      item("1", "Deploy"),
-      item("2", "  deploy "),
-      item("3", "DEPLOY"),
-      item("4", "other"),
-    ]);
-    expect(out.map((c) => c.id)).toEqual(["1", "4"]);
-  });
-
-  it("prefers the history item even if it comes later", () => {
-    const out = dedupeByText([
-      item("plain", "deploy", { isHistory: false }),
-      item("hist", "DEPLOY", { isHistory: true }),
-    ]);
-    expect(out.map((c) => c.id)).toEqual(["hist"]);
-  });
-
-  it("is otherwise stable", () => {
-    const out = dedupeByText([item("a", "one"), item("b", "two"), item("c", "three")]);
-    expect(out.map((c) => c.id)).toEqual(["a", "b", "c"]);
-  });
-
-  it("does not mutate input", () => {
-    const input = [item("1", "x"), item("2", "x")];
-    const snapshot = input.map((c) => ({ ...c }));
-    dedupeByText(input);
-    expect(input).toEqual(snapshot);
-  });
-});
-
-describe("InMemorySuggestionHistoryStore", () => {
-  it("records and reads back most-recent-first", () => {
-    const store = new InMemorySuggestionHistoryStore();
-    recordHistory(store, T, "first cmd");
-    recordHistory(store, T, "second cmd");
-    const out = historyCandidates(store, T);
-    expect(out.map((c) => c.text)).toEqual(["second cmd", "first cmd"]);
-    expect(out.every((c) => c.isHistory && c.type === "history")).toBe(true);
-  });
-
-  it("dedupes on re-record and moves the entry to the front", () => {
-    const store = new InMemorySuggestionHistoryStore();
-    recordHistory(store, T, "a");
-    recordHistory(store, T, "b");
-    recordHistory(store, T, "a");
-    expect(historyCandidates(store, T).map((c) => c.text)).toEqual(["a", "b"]);
-  });
-
-  it("evicts oldest beyond the ring cap", () => {
-    const store = new InMemorySuggestionHistoryStore(3);
-    recordHistory(store, T, "1");
-    recordHistory(store, T, "2");
-    recordHistory(store, T, "3");
-    recordHistory(store, T, "4");
-    expect(historyCandidates(store, T).map((c) => c.text)).toEqual(["4", "3", "2"]);
-  });
-
-  it("isolates tenants (cross-tenant reads impossible)", () => {
-    const store = new InMemorySuggestionHistoryStore();
-    recordHistory(store, "tenant_x", "x-secret");
-    recordHistory(store, "tenant_y", "y-secret");
-    expect(historyCandidates(store, "tenant_x").map((c) => c.text)).toEqual(["x-secret"]);
-    expect(historyCandidates(store, "tenant_y").map((c) => c.text)).toEqual(["y-secret"]);
-  });
-
-  it("throws on empty tenant for record and read (fail-closed)", () => {
-    const store = new InMemorySuggestionHistoryStore();
-    expect(() => recordHistory(store, "", "x")).toThrow();
-    expect(() => recordHistory(store, "  ", "x")).toThrow();
-    expect(() => historyCandidates(store, "")).toThrow();
-  });
-
-  it("ignores blank text on record", () => {
-    const store = new InMemorySuggestionHistoryStore();
-    recordHistory(store, T, "   ");
-    expect(historyCandidates(store, T)).toEqual([]);
-  });
-});

package/src/command-suggestions.ts

@@ -1,338 +0,0 @@
-/**
- * command-suggestions — pure, deterministic ranked input-suggestion model.
- *
- * A dependency-free re-expression of the ranked command/input suggestion
- * engine found in modern terminals and command palettes. The fuzzy matcher
- * itself lives elsewhere; this module never imports it — callers wire a real
- * matcher through the injected {@link FuzzyMatchFn} port (tests pass a
- * deterministic fake).
- *
- * Invariants:
- *   - Pure functions: no I/O, no shared state, no input mutation, no console.
- *   - Match banding is contractual: exact > prefix > fuzzy, regardless of the
- *     fuzzy matcher's score magnitude.
- *   - Tenancy is structural and fails closed: every history operation requires
- *     a non-empty tenantId (Zod-validated) and is keyed per tenant, so
- *     cross-tenant reads are impossible by construction.
- */
-
-import { z } from "zod";
-
-// ---------------------------------------------------------------------------
-// Types (faithful, neutral)
-// ---------------------------------------------------------------------------
-
-export type SuggestionType = "history" | "workflow" | "completion" | "ai";
-
-export type MatchType = "exact" | "prefix" | "fuzzy" | "none";
-
-export interface SuggestionItem {
-  readonly id: string;
-  readonly text: string;
-  readonly type: SuggestionType;
-  readonly isHistory: boolean;
-  readonly detail?: string | undefined;
-}
-
-export interface RankedSuggestion {
-  readonly item: SuggestionItem;
-  readonly score: number;
-  readonly matchType: MatchType;
-  readonly matchIndices: number[];
-}
-
-export interface SuggestionResults {
-  readonly query: string;
-  readonly results: RankedSuggestion[];
-}
-
-export interface RankOptions {
-  readonly limit?: number | undefined;
-}
-
-/**
- * Injected fuzzy-match port. The real matcher is wired by the caller; this
- * module declares only the shape it consumes. A `null` return means "no match".
- */
-export type FuzzyMatchFn = (
-  text: string,
-  query: string,
-) => { score: number; indices: number[] } | null;
-
-export interface MatchClassification {
-  readonly matchType: MatchType;
-  readonly score: number;
-  readonly indices: number[];
-}
-
-// ---------------------------------------------------------------------------
-// Score bands — exact > prefix > fuzzy, independent of fuzzy magnitude
-// ---------------------------------------------------------------------------
-
-/**
- * Fuzzy scores share the lowest band. Prefix and exact are pinned ABOVE any
- * representable fuzzy score so banding is a total order regardless of what the
- * injected matcher returns.
- */
-const FUZZY_CEILING = Number.MAX_SAFE_INTEGER / 4;
-const PREFIX_SCORE = FUZZY_CEILING * 2;
-const EXACT_SCORE = FUZZY_CEILING * 3;
-
-const DEFAULT_LIMIT = 50;
-const DEFAULT_HISTORY_CAP = 500;
-
-// ---------------------------------------------------------------------------
-// Boundary validation (fail-closed tenancy)
-// ---------------------------------------------------------------------------
-
-const TenantSchema = z
-  .string()
-  .refine((v) => v.trim() !== "", "tenantId is required (fail-closed)");
-
-function assertTenant(tenantId: unknown): string {
-  const parsed = TenantSchema.safeParse(tenantId);
-  if (!parsed.success) {
-    throw new Error("tenantId is required (fail-closed)");
-  }
-  return parsed.data;
-}
-
-// ---------------------------------------------------------------------------
-// classifyMatch
-// ---------------------------------------------------------------------------
-
-function fullSpan(length: number): number[] {
-  return Array.from({ length }, (_, i) => i);
-}
-
-/**
- * Classify how `query` matches `text`. Exact (case-insensitive full equality)
- * outranks prefix (case-insensitive starts-with) outranks the injected fuzzy
- * matcher. An empty query is inert: `none`, score 0, no indices.
- */
-export function classifyMatch(
-  text: string,
-  query: string,
-  fuzzy: FuzzyMatchFn,
-): MatchClassification {
-  if (query === "") {
-    return { matchType: "none", score: 0, indices: [] };
-  }
-
-  const lowerText = text.toLowerCase();
-  const lowerQuery = query.toLowerCase();
-
-  if (lowerText === lowerQuery) {
-    return {
-      matchType: "exact",
-      score: EXACT_SCORE,
-      indices: fullSpan(text.length),
-    };
-  }
-
-  if (lowerText.startsWith(lowerQuery)) {
-    return {
-      matchType: "prefix",
-      score: PREFIX_SCORE,
-      indices: fullSpan(query.length),
-    };
-  }
-
-  const fuzzyResult = fuzzy(text, query);
-  if (fuzzyResult === null) {
-    return { matchType: "none", score: 0, indices: [] };
-  }
-
-  return {
-    matchType: "fuzzy",
-    // Clamp into the fuzzy band so an overzealous matcher can never reach the
-    // prefix/exact bands.
-    score: Math.min(fuzzyResult.score, FUZZY_CEILING),
-    indices: [...fuzzyResult.indices],
-  };
-}
-
-// ---------------------------------------------------------------------------
-// rankSuggestions
-// ---------------------------------------------------------------------------
-
-interface ScoredEntry {
-  readonly ranked: RankedSuggestion;
-  readonly order: number;
-}
-
-/**
- * Compare two scored entries. Returns negative when `a` should rank first.
- * Order: score desc → history-first on tie → shorter text → stable input order.
- */
-function compareEntries(a: ScoredEntry, b: ScoredEntry): number {
-  if (a.ranked.score !== b.ranked.score) {
-    return b.ranked.score - a.ranked.score;
-  }
-  const aHist = a.ranked.item.isHistory ? 1 : 0;
-  const bHist = b.ranked.item.isHistory ? 1 : 0;
-  if (aHist !== bHist) {
-    return bHist - aHist;
-  }
-  const aLen = a.ranked.item.text.length;
-  const bLen = b.ranked.item.text.length;
-  if (aLen !== bLen) {
-    return aLen - bLen;
-  }
-  return a.order - b.order;
-}
-
-/**
- * Rank `candidates` against `query` for one tenant. Fails closed on an empty
- * tenant. With a non-empty query, `none` matches are dropped; with an empty
- * query every candidate is kept (inert match) and ordered purely by the
- * tie-breakers. Never mutates `candidates`.
- */
-export function rankSuggestions(
-  tenantId: string,
-  query: string,
-  candidates: readonly SuggestionItem[],
-  fuzzy: FuzzyMatchFn,
-  opts?: RankOptions,
-): SuggestionResults {
-  assertTenant(tenantId);
-
-  const limit = opts?.limit !== undefined && opts.limit >= 0 ? opts.limit : DEFAULT_LIMIT;
-  const keepNone = query === "";
-
-  const scored: ScoredEntry[] = [];
-  candidates.forEach((item, order) => {
-    const c = classifyMatch(item.text, query, fuzzy);
-    if (c.matchType === "none" && !keepNone) {
-      return;
-    }
-    scored.push({
-      ranked: {
-        item,
-        score: c.score,
-        matchType: c.matchType,
-        matchIndices: [...c.indices],
-      },
-      order,
-    });
-  });
-
-  const sorted = [...scored].sort(compareEntries);
-  const results = sorted.slice(0, limit).map((e) => e.ranked);
-
-  return { query, results };
-}
-
-// ---------------------------------------------------------------------------
-// dedupeByText
-// ---------------------------------------------------------------------------
-
-function normalizeText(text: string): string {
-  return text.trim().toLowerCase();
-}
-
-/**
- * Keep one item per normalized (trimmed, case-insensitive) text. First
- * occurrence wins, EXCEPT a history item supersedes an earlier non-history
- * item that shares the same normalized text. Stable otherwise. Pure.
- */
-export function dedupeByText(candidates: readonly SuggestionItem[]): SuggestionItem[] {
-  const order: string[] = [];
-  const chosen = new Map<string, SuggestionItem>();
-
-  for (const item of candidates) {
-    const key = normalizeText(item.text);
-    const existing = chosen.get(key);
-    if (existing === undefined) {
-      chosen.set(key, item);
-      order.push(key);
-      continue;
-    }
-    if (!existing.isHistory && item.isHistory) {
-      // History wins even when it appears later; keep the original slot.
-      chosen.set(key, item);
-    }
-  }
-
-  return order.map((key) => {
-    const value = chosen.get(key);
-    if (value === undefined) {
-      throw new Error("dedupeByText: invariant violated (missing key)");
-    }
-    return value;
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Tenant-scoped history store
-// ---------------------------------------------------------------------------
-
-/**
- * Tenant-scoped append-with-dedupe history seam. Implementations MUST key by
- * tenant so cross-tenant reads are impossible, MUST keep entries
- * most-recent-first, and MUST bound storage to a ring cap.
- */
-export interface SuggestionHistoryStore {
-  /** Append `text` for `tenantId`, deduped, most-recent-first, ring-bounded. */
-  append(tenantId: string, text: string): void;
-  /** Most-recent-first texts for `tenantId`. */
-  list(tenantId: string): string[];
-}
-
-/**
- * In-memory reference implementation mirroring this package's other stores.
- * Tenancy is structural: `tenantId` is part of the key AND validated on every
- * read/write, so a tenant can never observe another tenant's history.
- */
-export class InMemorySuggestionHistoryStore implements SuggestionHistoryStore {
-  readonly #cap: number;
-  readonly #byTenant = new Map<string, string[]>();
-
-  constructor(cap: number = DEFAULT_HISTORY_CAP) {
-    this.#cap = cap > 0 ? cap : DEFAULT_HISTORY_CAP;
-  }
-
-  append(tenantId: string, text: string): void {
-    const tenant = assertTenant(tenantId);
-    const trimmed = text.trim();
-    if (trimmed === "") {
-      return;
-    }
-    const prior = this.#byTenant.get(tenant) ?? [];
-    const deduped = prior.filter((t) => t !== trimmed);
-    const next = [trimmed, ...deduped].slice(0, this.#cap);
-    this.#byTenant.set(tenant, next);
-  }
-
-  list(tenantId: string): string[] {
-    const tenant = assertTenant(tenantId);
-    return [...(this.#byTenant.get(tenant) ?? [])];
-  }
-}
-
-/**
- * Record `text` into the tenant's suggestion history. Fails closed on an empty
- * tenant; blank text is ignored.
- */
-export function recordHistory(store: SuggestionHistoryStore, tenantId: string, text: string): void {
-  assertTenant(tenantId);
-  store.append(tenantId, text);
-}
-
-/**
- * Read the tenant's history as ranked-ready {@link SuggestionItem}s
- * (most-recent-first, flagged `isHistory`). Fails closed on an empty tenant.
- */
-export function historyCandidates(
-  store: SuggestionHistoryStore,
-  tenantId: string,
-): SuggestionItem[] {
-  assertTenant(tenantId);
-  return store.list(tenantId).map((text, index) => ({
-    id: `history:${index}:${text}`,
-    text,
-    type: "history" as const,
-    isHistory: true,
-    detail: undefined,
-  }));
-}