@fro.bot/systematic 3.27.1 → 3.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/ATTRIBUTIONS.md +2 -2
  2. package/HARNESSES.md +24 -11
  3. package/agents/research/learnings-researcher.md +49 -9
  4. package/dist/claude-code-search.d.ts +30 -0
  5. package/dist/claude-code-validator-bin.d.ts +17 -0
  6. package/dist/cli.d.ts +18 -0
  7. package/dist/cli.js +335 -108
  8. package/dist/{index-608preny.js → index-9chxhh5j.js} +1120 -72
  9. package/dist/index.js +204 -8
  10. package/dist/lib/agent-resolver.d.ts +8 -2
  11. package/dist/lib/asset-plan.d.ts +23 -1
  12. package/dist/lib/config-protected-fields.d.ts +1 -1
  13. package/dist/lib/config-schema.d.ts +6 -0
  14. package/dist/lib/config.d.ts +13 -0
  15. package/dist/lib/main-module.d.ts +30 -0
  16. package/dist/lib/opencode-v2-commands.d.ts +4 -3
  17. package/dist/lib/opencode-v2-skills.d.ts +12 -2
  18. package/dist/lib/opencode-v2.d.ts +1 -0
  19. package/dist/lib/pi-delegate-session.d.ts +3 -1
  20. package/dist/lib/pi-delegate-tool.d.ts +12 -1
  21. package/dist/lib/search-cli.d.ts +52 -0
  22. package/dist/lib/search-core.d.ts +128 -0
  23. package/dist/lib/search-corpus.d.ts +105 -0
  24. package/dist/lib/search-lexical.d.ts +136 -0
  25. package/dist/lib/search-render.d.ts +69 -0
  26. package/dist/lib/search-tool.d.ts +53 -0
  27. package/dist/lib/search-user-config.d.ts +96 -0
  28. package/dist/pi.js +1155 -77
  29. package/package.json +3 -3
  30. package/skills/ce-review/SKILL.md +1 -1
  31. package/skills/ce-review/references/review-output-template.md +1 -1
  32. package/skills/ce-review/scripts/validate-review.mjs +1 -3
  33. package/skills/using-systematic/references/claude-code-profile.md +1 -0
  34. package/skills/using-systematic/references/opencode-profile.md +1 -0
  35. package/skills/using-systematic/references/opencode-v2-profile.md +1 -0
  36. package/skills/using-systematic/references/pi-profile.md +1 -0
@@ -0,0 +1,128 @@
1
+ /**
2
+ * The one host-neutral composition behind durable-output search.
3
+ *
4
+ * `runSearch` validates the request, resolves the project root, loads the
5
+ * corpus, runs the lexical lane, resolves the solution lifecycle, and renders. Every adapter (OpenCode
6
+ * v1 and v2, Pi, the CLI and the standalone search bin) calls it and does only host
7
+ * I/O: the start directory, the settings, and mapping the response to its
8
+ * host's return shape. Adapters never format text themselves.
9
+ *
10
+ * This module also owns the `SearchSettings` type, the tool name and argument
11
+ * constants, and the lifecycle constants and resolver. The resolver follows
12
+ * the learnings-researcher's rules: at most 5 hops, a visited set, and a form
13
+ * rule for the successor path. A superseded doc whose successor cannot be
14
+ * resolved is returned at its own rank with `Caution: successor unresolved`.
15
+ * Nothing is dropped.
16
+ */
17
+ import { type CorpusDocument, type CorpusLoad, type DocumentKind } from './search-corpus.js';
18
+ import { type Bm25fParams } from './search-lexical.js';
19
+ import { type SearchHitStatus, type SearchResult, SUPERSEDES_LABEL } from './search-render.js';
20
+ export type { SearchHit, SearchResult } from './search-render.js';
21
+ export { SUPERSEDES_LABEL };
22
+ /** Tool name shared by every host surface. */
23
+ export declare const SEARCH_TOOL_NAME = "systematic_search";
24
+ /** Tool argument names shared by every host surface. */
25
+ export declare const SEARCH_ARGS: {
26
+ readonly query: 'query';
27
+ readonly kind: 'kind';
28
+ readonly limit: 'limit';
29
+ };
30
+ export declare const DEFAULT_LIMIT = 8;
31
+ export declare const MIN_LIMIT = 1;
32
+ export declare const MAX_LIMIT = 20;
33
+ export declare const MAX_QUERY_CHARS = 2000;
34
+ /**
35
+ * The tool text every host surface shows the model. `limit` is a plain integer
36
+ * in every host schema, so its range is stated here and nowhere else: the core
37
+ * owns the out-of-range error and a host never pre-empts it.
38
+ */
39
+ export declare const SEARCH_TOOL_DESCRIPTION = "Search this project's durable outputs (the docs/solutions learnings) by symptom, error text, module or topic. Returns ranked hits with path, title, snippet, tags and status. A superseded learning is replaced by its successor, and a stale one carries a caution. Read a hit's path for the full text. Use it before debugging a failure or planning work a past learning may already cover.";
40
+ export declare const SEARCH_ARG_DESCRIPTIONS: {
41
+ readonly query: "What to look for: a symptom, error message, module or topic, in plain words. At most 2000 characters.";
42
+ readonly kind: 'Optional. The kind of durable output to search. Only "solution" (docs/solutions/) exists today, and it is the default.';
43
+ readonly limit: "Optional. How many hits to return, an integer from 1 to 20. Defaults to 8.";
44
+ };
45
+ /** One-line texts an adapter returns when it cannot reach the core. They carry no detail from the failure. */
46
+ export declare const SEARCH_NOTICES: {
47
+ readonly failed: 'Error: search failed.';
48
+ readonly noProject: 'No project directory is available for this session, so there is nothing to search.';
49
+ };
50
+ /** The note an adapter passes in `SearchOptions.notes` when a settings source could not be read. */
51
+ export declare const SEARCH_CONFIG_UNREADABLE_NOTE = "config unreadable";
52
+ /** Most `superseded_by` links followed from one candidate. */
53
+ export declare const MAX_SUCCESSOR_HOPS = 5;
54
+ /** A successor path must start with this and name a loaded file. */
55
+ export declare const SUCCESSOR_PATH_PREFIX: string;
56
+ export declare const CAUTION_LABEL = "Caution:";
57
+ export declare const SUCCESSOR_UNRESOLVED_TEXT = "successor unresolved";
58
+ export declare const STALE_CAUTION_TEXT = "marked stale";
59
+ /** Fixed validation errors. They never echo the rejected value. */
60
+ export declare const SEARCH_ERRORS: {
61
+ readonly queryEmpty: 'Error: query must be a non-empty string.';
62
+ readonly queryTooLong: "Error: query must be at most 2000 characters.";
63
+ readonly kindUnknown: `Error: kind must be one of: ${string}.`;
64
+ readonly limitInvalid: "Error: limit must be an integer from 1 to 20.";
65
+ };
66
+ /** User-level search settings. The zod schema's output type must stay assignable to this. */
67
+ export interface SearchSettings {
68
+ readonly enabled?: boolean | undefined;
69
+ }
70
+ export interface SearchRequest {
71
+ /** Raw host values: the core validates them. */
72
+ readonly query: unknown;
73
+ readonly kind?: unknown;
74
+ readonly limit?: unknown;
75
+ }
76
+ export interface SearchOptions {
77
+ /** The directory the root walk-up starts from. */
78
+ readonly startDir: string;
79
+ readonly settings?: SearchSettings | undefined;
80
+ /** Notes an adapter wants shown ahead of the core's own, such as `SEARCH_CONFIG_UNREADABLE_NOTE`. */
81
+ readonly notes?: readonly string[] | undefined;
82
+ /** Override the BM25F table. The recall tuning uses this; hosts do not. */
83
+ readonly lexicalParams?: Bm25fParams | undefined;
84
+ /** Replace the disk loader. Tests use this to control load order. */
85
+ readonly corpusLoader?: ((root: string, kind: DocumentKind) => CorpusLoad) | undefined;
86
+ }
87
+ export type SearchResponse = {
88
+ readonly ok: true;
89
+ readonly text: string;
90
+ readonly result: SearchResult;
91
+ } | {
92
+ readonly ok: false;
93
+ readonly text: string;
94
+ };
95
+ /** Whether a `superseded_by` value has the shape of a repo-root solution path. */
96
+ export declare function isSuccessorPathForm(value: string): boolean;
97
+ /**
98
+ * Follow a superseded document's `superseded_by` chain. Returns the first
99
+ * document that is not superseded, or `undefined` when the chain is
100
+ * unresolvable: a link that is not a string, fails the form rule, names a file
101
+ * outside the loaded corpus, revisits a document, or is still superseded after
102
+ * `MAX_SUCCESSOR_HOPS` links.
103
+ */
104
+ export declare function resolveSuccessor(candidate: CorpusDocument, byPath: ReadonlyMap<string, CorpusDocument>): CorpusDocument | undefined;
105
+ export interface ResolvedEntry {
106
+ /** The document to show: the candidate, or the successor standing in for it. */
107
+ readonly document: CorpusDocument;
108
+ /** Root-relative paths this entry replaces, in code-unit order. */
109
+ readonly supersedes: readonly string[];
110
+ /** True for a superseded document returned because its successor is unresolved. */
111
+ readonly unresolved: boolean;
112
+ }
113
+ /**
114
+ * Resolve the lifecycle of a ranked list, best first. A superseded candidate
115
+ * is replaced by its successor; a successor takes the best rank among itself
116
+ * and the documents it replaces; duplicates merge. An unresolvable superseded
117
+ * candidate stays at its own rank. `documents` is the whole loaded corpus,
118
+ * because a successor does not have to be a match.
119
+ */
120
+ export declare function resolveLifecycle(ranked: readonly CorpusDocument[], documents: readonly CorpusDocument[]): ResolvedEntry[];
121
+ export declare function entryStatus(entry: ResolvedEntry): SearchHitStatus;
122
+ /** The `Supersedes:` and `Caution:` lines for one entry, in print order. */
123
+ export declare function lifecycleLines(entry: ResolvedEntry): string[];
124
+ /**
125
+ * Validate, search, resolve the lifecycle and render. Never throws on bad
126
+ * input: a bad request comes back as `{ ok: false }` with a fixed error text.
127
+ */
128
+ export declare function runSearch(request: SearchRequest, options: SearchOptions): Promise<SearchResponse>;
@@ -0,0 +1,105 @@
1
+ /**
2
+ * Corpus loader for durable-output search: project root, `kind` table, safe
3
+ * walk of `docs/solutions/` and a narrowing wrapper around `parseFrontmatter`.
4
+ *
5
+ * Reads from disk on every call and keeps no memo, because `ce:compound`
6
+ * searches right after it writes. Never throws: every filesystem failure
7
+ * becomes a bounded, sanitised warning. Holds no lifecycle logic. Documents
8
+ * carry the narrowed `status`, `superseded_by` and `stale_reason` that the
9
+ * search core's resolver reads.
10
+ */
11
+ /** Largest single file loaded, in bytes. */
12
+ export declare const MAX_FILE_BYTES: number;
13
+ /** Most files considered per load. */
14
+ export declare const MAX_FILES = 2000;
15
+ /** Deepest directory level walked; files directly in the kind directory are depth 0. */
16
+ export declare const MAX_DEPTH = 6;
17
+ /** Total bytes of text loaded per call. */
18
+ export declare const MAX_TOTAL_BYTES: number;
19
+ /**
20
+ * One entry per document kind. Release 1 indexes `docs/solutions/` only; a new
21
+ * kind (plans, brainstorms) is a new entry here plus its frontmatter fit.
22
+ */
23
+ export declare const KIND_TABLE: {
24
+ readonly solution: {
25
+ readonly dir: 'docs/solutions';
26
+ readonly excludedFiles: readonly ["readme.md", "critical-patterns.md"];
27
+ readonly excludedDirs: readonly ["_archived"];
28
+ readonly lifecycle: true;
29
+ };
30
+ };
31
+ export type DocumentKind = keyof typeof KIND_TABLE;
32
+ export declare function isDocumentKind(value: unknown): value is DocumentKind;
33
+ /**
34
+ * The `superseded_by` frontmatter value, kept apart from its meaning so the
35
+ * resolver sees every malformed shape: `none` (key absent or null), `value`
36
+ * (a string, possibly empty) or `invalid` (a list, mapping, number or any
37
+ * other non-string).
38
+ */
39
+ export type SupersededByField = {
40
+ readonly state: 'none';
41
+ } | {
42
+ readonly state: 'value';
43
+ readonly value: string;
44
+ } | {
45
+ readonly state: 'invalid';
46
+ };
47
+ export interface CorpusDocument {
48
+ /** Root-relative path with `/` separators. */
49
+ readonly path: string;
50
+ readonly kind: DocumentKind;
51
+ /** The `title` field, else the file name without `.md`. */
52
+ readonly title: string;
53
+ readonly tags: readonly string[];
54
+ readonly module: string | undefined;
55
+ readonly component: string | undefined;
56
+ readonly problemType: string | undefined;
57
+ readonly symptoms: readonly string[];
58
+ readonly appliesWhen: readonly string[];
59
+ /** Raw `status` string; `undefined` when absent or not a string. */
60
+ readonly status: string | undefined;
61
+ readonly supersededBy: SupersededByField;
62
+ readonly staleReason: string | undefined;
63
+ /** Text after the frontmatter block, or the whole file when there is none. */
64
+ readonly body: string;
65
+ }
66
+ export interface CorpusLoad {
67
+ /** `none` when the kind directory does not exist (or lies outside the root). */
68
+ readonly state: 'none' | 'loaded';
69
+ readonly documents: readonly CorpusDocument[];
70
+ /** Bounded, sanitised, in deterministic order. */
71
+ readonly warnings: readonly string[];
72
+ }
73
+ /**
74
+ * The project root: the nearest ancestor of `startDir` holding `.git` (a
75
+ * directory, or a file for a worktree), resolved with `realpath`; otherwise
76
+ * `startDir` itself, also resolved.
77
+ *
78
+ * This is a copy of the private `findGitWorktreeRoot` in
79
+ * `discovered-skills.ts`, and the two differ on purpose: search falls back to
80
+ * the start directory, while discovery returns null. Do not unify them.
81
+ * Importing `discovered-skills.ts` here would also pull its dependencies into
82
+ * the standalone search bin. This is the second use; extract at the third.
83
+ */
84
+ export declare function resolveSearchRoot(startDir: string): string;
85
+ export type ParsedDocument = {
86
+ readonly ok: true;
87
+ readonly document: CorpusDocument;
88
+ } | {
89
+ readonly ok: false;
90
+ readonly reason: string;
91
+ };
92
+ /**
93
+ * Parse one file. Wraps `parseFrontmatter` (which stays unedited): strips a
94
+ * leading BOM, supplies the newline its regex needs when the closing `---` is
95
+ * the last line, and reads only known fields, narrowing each. No frontmatter
96
+ * means a body-only document with no warning. Invalid YAML, or a frontmatter
97
+ * block that is not a mapping, is not indexable.
98
+ */
99
+ export declare function parseCorpusDocument(kind: DocumentKind, relativePath: string, content: string): ParsedDocument;
100
+ /**
101
+ * Load every indexable document of one kind under `root`, sorted by
102
+ * root-relative path in code-unit order. `root` should come from
103
+ * `resolveSearchRoot`.
104
+ */
105
+ export declare function loadCorpus(root: string, kind?: DocumentKind): CorpusLoad;
@@ -0,0 +1,136 @@
1
+ /**
2
+ * Lexical lane for durable-output search: tokenizer, natural log and BM25F.
3
+ *
4
+ * Pure and dependency-free: no I/O, no environment reads, no imports. Scores
5
+ * must be bit-identical on Bun and Node, because the lexical lane is the part
6
+ * of search that every surface shares. ECMAScript leaves `Math.log`
7
+ * implementation-approximated and the two runtimes disagree on it, so this
8
+ * module computes its own `ln` from + - * / only. By convention it also
9
+ * avoids `Math.pow`, `**`, `exp`, `Intl`, `localeCompare`, `toLocale*`,
10
+ * `Bun.` and `bun:`. Tests enforce the outcome (bit patterns under Node),
11
+ * not the convention.
12
+ */
13
+ /** Indexed fields in the fixed order used for summation. */
14
+ export declare const LEXICAL_FIELDS: readonly ['title', 'tags', 'module', 'symptoms', 'applies_when', 'component', 'problem_type', 'body'];
15
+ export type LexicalField = (typeof LEXICAL_FIELDS)[number];
16
+ export interface Bm25fFieldParams {
17
+ /** Field weight `w_f`. */
18
+ readonly weight: number;
19
+ /** Length-normalisation strength `b_f`; 0 turns normalisation off. */
20
+ readonly b: number;
21
+ }
22
+ export interface Bm25fParams {
23
+ readonly k1: number;
24
+ readonly fields: Readonly<Record<LexicalField, Bm25fFieldParams>>;
25
+ }
26
+ /**
27
+ * The one table the recall tuning edits. Metadata fields do not
28
+ * length-normalise; the body does. Frozen at Checkpoint A: the 27-cell retune
29
+ * grid in `tests/unit/search-recall.test.ts` scored 11 of 12 on the tune
30
+ * split for every cell with body b of 0.75 or 0.9 and 10 of 12 for b of 0.5,
31
+ * so the tie went to the starting values from the plan's Key Technical
32
+ * Decisions, unchanged.
33
+ */
34
+ export declare const BM25F_PARAMS: {
35
+ readonly k1: 1.2;
36
+ readonly fields: {
37
+ readonly title: {
38
+ readonly weight: 3;
39
+ readonly b: 0;
40
+ };
41
+ readonly tags: {
42
+ readonly weight: 2.5;
43
+ readonly b: 0;
44
+ };
45
+ readonly module: {
46
+ readonly weight: 2;
47
+ readonly b: 0;
48
+ };
49
+ readonly symptoms: {
50
+ readonly weight: 3;
51
+ readonly b: 0;
52
+ };
53
+ readonly applies_when: {
54
+ readonly weight: 2;
55
+ readonly b: 0;
56
+ };
57
+ readonly component: {
58
+ readonly weight: 1.5;
59
+ readonly b: 0;
60
+ };
61
+ readonly problem_type: {
62
+ readonly weight: 1.5;
63
+ readonly b: 0;
64
+ };
65
+ readonly body: {
66
+ readonly weight: 1;
67
+ readonly b: 0.75;
68
+ };
69
+ };
70
+ };
71
+ /** Unique query terms kept after truncation. */
72
+ export declare const MAX_QUERY_TERMS = 64;
73
+ /**
74
+ * Splits text into index terms. Lowercases, then emits ASCII `[a-z0-9]` runs.
75
+ * A run joined by `_` or `-` also emits its whole joined identifier first, so
76
+ * `foo_bar` yields `foo_bar`, `foo`, `bar`. Every other character splits, a
77
+ * non-ASCII letter included (`naïve` yields `na`, `ve`, a documented limit).
78
+ * No stemming, no stopwords, no camelCase split. Duplicates are kept so the
79
+ * caller can count term frequency.
80
+ */
81
+ export declare function tokenize(text: string): string[];
82
+ /**
83
+ * Unique query terms in first-seen order, truncated to `max`, then sorted by
84
+ * code unit so summation order is fixed. `truncated` tells the caller to add
85
+ * a note.
86
+ */
87
+ export declare function uniqueQueryTerms(query: string, max?: number): {
88
+ readonly terms: string[];
89
+ readonly truncated: boolean;
90
+ };
91
+ /**
92
+ * Natural logarithm using only + - * /. Scales the argument by exact powers
93
+ * of two into [sqrt(1/2), sqrt(2)), then sums the atanh series
94
+ * `ln m = 2 * atanh((m - 1) / (m + 1))` with a fixed number of terms and adds
95
+ * `k * ln 2`. Relative error is near 1e-16 across the range search uses.
96
+ * Returns -Infinity for 0, and NaN for a negative or NaN argument.
97
+ */
98
+ export declare function ln(x: number): number;
99
+ export interface LexicalDocument {
100
+ /** Root-relative path. Equal scores order by the code units of this. */
101
+ readonly id: string;
102
+ readonly fields: Readonly<Partial<Record<LexicalField, string>>>;
103
+ }
104
+ interface FieldStats {
105
+ readonly tf: Map<string, number>;
106
+ readonly length: number;
107
+ }
108
+ interface IndexedDocument {
109
+ readonly id: string;
110
+ /** Aligned with `LEXICAL_FIELDS`. */
111
+ readonly fields: readonly FieldStats[];
112
+ }
113
+ export interface LexicalIndex {
114
+ readonly params: Bm25fParams;
115
+ readonly docs: readonly IndexedDocument[];
116
+ /** Documents in which a term appears in any field. */
117
+ readonly documentFrequency: ReadonlyMap<string, number>;
118
+ /** Mean field length, aligned with `LEXICAL_FIELDS`. */
119
+ readonly averageLength: readonly number[];
120
+ }
121
+ export interface LexicalHit {
122
+ readonly id: string;
123
+ readonly score: number;
124
+ }
125
+ /** Builds the index over documents with named fields. Pure. */
126
+ export declare function buildLexicalIndex(documents: readonly LexicalDocument[], params?: Bm25fParams): LexicalIndex;
127
+ /**
128
+ * BM25F. For each term, a length-normalised weighted term frequency is summed
129
+ * over fields and saturated with `k1`, then scaled by
130
+ * `ln(1 + (N - df + 0.5) / (df + 0.5))`. Terms are deduplicated and sorted by
131
+ * code unit here, and fields are summed in `LEXICAL_FIELDS` order, so the
132
+ * score does not depend on the order the caller supplied terms in. Returns
133
+ * documents with a positive score, best first, ties by code-unit path.
134
+ */
135
+ export declare function searchLexical(index: LexicalIndex, terms: readonly string[]): LexicalHit[];
136
+ export {};
@@ -0,0 +1,69 @@
1
+ /**
2
+ * Renderer for durable-output search results.
3
+ *
4
+ * Turns the core's structured result into the one text every surface returns.
5
+ * Owns sanitising, field caps, the snippet window, the warning cap and the
6
+ * 16 KB cut with Systematic's own marker. Imports only types from the corpus
7
+ * module, so render tests never load filesystem code.
8
+ *
9
+ * Everything echoed passes `sanitizeInline` first, because titles, tags, file
10
+ * names and bodies are untrusted text that ends up in an agent's context and
11
+ * a human's terminal.
12
+ */
13
+ import type { CorpusDocument } from './search-corpus.js';
14
+ /** Hard cap on rendered output, in UTF-8 bytes. */
15
+ export declare const MAX_OUTPUT_BYTES: number;
16
+ /** Appended on its own line when output is cut. */
17
+ export declare const TRUNCATION_MARKER = "[Systematic: search output truncated at 16 KB]";
18
+ export declare const MAX_TITLE_CHARS = 160;
19
+ export declare const MAX_TAGS = 8;
20
+ export declare const MAX_SNIPPET_CHARS = 240;
21
+ export declare const MAX_WARNINGS = 5;
22
+ /** The lifecycle line that lists the docs a successor replaces. */
23
+ export declare const SUPERSEDES_LABEL = "Supersedes:";
24
+ export type SearchHitStatus = 'active' | 'stale' | 'superseded';
25
+ export interface SearchHit {
26
+ /** 1-based position in the final list. */
27
+ readonly rank: number;
28
+ readonly document: CorpusDocument;
29
+ readonly status: SearchHitStatus;
30
+ /** Fully formed `Supersedes:` and `Caution:` lines, in print order. */
31
+ readonly lifecycle: readonly string[];
32
+ }
33
+ export interface SearchResult {
34
+ /** The query as the caller sent it; sanitised and capped when echoed. */
35
+ readonly query: string;
36
+ /** Unique, sorted query terms, used to pick snippet windows. */
37
+ readonly queryTerms: readonly string[];
38
+ /** `none`: no docs/solutions/. `empty`: the directory holds no indexable doc. */
39
+ readonly corpus: {
40
+ readonly state: 'none' | 'empty' | 'docs';
41
+ readonly docCount: number;
42
+ };
43
+ readonly hits: readonly SearchHit[];
44
+ readonly notes: readonly string[];
45
+ readonly warnings: readonly string[];
46
+ }
47
+ /**
48
+ * One line of safe text: terminal escape sequences removed, line breaks and
49
+ * tabs turned into a space, every other control character and invisible
50
+ * formatting character dropped, whitespace collapsed, then capped at `max`
51
+ * characters with an ellipsis.
52
+ */
53
+ export declare function sanitizeInline(text: string, max?: number): string;
54
+ /**
55
+ * Cut `text` so the result, marker included, is at most `maxBytes` of UTF-8.
56
+ * The cut lands on a character boundary, and on a line boundary when the kept
57
+ * text has one. The marker goes on its own line. Text that already fits is
58
+ * returned unchanged.
59
+ */
60
+ export declare function truncateUtf8(text: string, maxBytes: number, marker: string): string;
61
+ /**
62
+ * A one-line snippet of at most 240 characters. Picks the window of the body
63
+ * holding the most distinct query terms (earliest on a tie) and centres on it.
64
+ * With no match in the body it falls back to the symptoms, then the title.
65
+ * Only called for the hits being returned.
66
+ */
67
+ export declare function extractSnippet(document: Pick<CorpusDocument, 'body' | 'symptoms' | 'title'>, queryTerms: readonly string[]): string;
68
+ /** Render a structured result as text, never more than `MAX_OUTPUT_BYTES`. */
69
+ export declare function renderSearchResult(result: SearchResult): string;
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Host adapters for the `systematic_search` tool: OpenCode v1 (zod), OpenCode
3
+ * v2 (JSON Schema through the tool transform) and Pi (typebox). Each does host
4
+ * I/O only: pick the start directory, hand over the settings, and map any
5
+ * failure to one fixed line. Validation, ranking, the lifecycle and every byte
6
+ * of the rendered text belong to `runSearch` in `search-core.ts`.
7
+ *
8
+ * No adapter asks for a permission: the tool reads only the project's own
9
+ * `docs/solutions/`, under a realpath containment check in the corpus loader.
10
+ * Every host schema declares `limit` as a plain integer and states the range
11
+ * in the description, so the core's fixed error is what an out-of-range value
12
+ * gets wherever the host passes it through.
13
+ */
14
+ import type { ToolDefinition as PiToolDefinition } from '@earendil-works/pi-coding-agent';
15
+ import type { ToolDefinition } from '@opencode-ai/plugin';
16
+ import type { Type as TypeBuilder } from 'typebox';
17
+ import type { V2Installer } from './opencode-v2.js';
18
+ import { type SearchSettings } from './search-core.js';
19
+ /** Whether the config leaves the tool on. Only an explicit `enabled: false` removes it. */
20
+ export declare function isSearchEnabled(settings: SearchSettings | undefined): boolean;
21
+ export interface SearchToolV1Options {
22
+ readonly settings: SearchSettings | undefined;
23
+ /** `config.searchUnreadable`: adds the `config unreadable` note to every result. */
24
+ readonly unreadable?: boolean | undefined;
25
+ }
26
+ export declare function createSearchTool(options: SearchToolV1Options): ToolDefinition;
27
+ /**
28
+ * Registers `systematic_search` through the v2 tool transform. A name another
29
+ * plugin already holds is left alone and reported once. Nothing registers when
30
+ * `search.enabled` is false.
31
+ */
32
+ export declare const installSearch: V2Installer;
33
+ export interface SearchToolPiOptions {
34
+ readonly settings: SearchSettings | undefined;
35
+ /** `config.searchUnreadable`: adds the `config unreadable` note to every result. */
36
+ readonly unreadable?: boolean | undefined;
37
+ /**
38
+ * typebox's `Type` builder, supplied by the Pi entry. This module is also
39
+ * imported by the OpenCode entries, and typebox is an optional peer that only
40
+ * Pi installs, so it must not be a runtime import here: the OpenCode bundle
41
+ * would carry a copy of it.
42
+ */
43
+ readonly Type: typeof TypeBuilder;
44
+ }
45
+ /**
46
+ * The Pi definition. `src/pi.ts` registers it for the parent session and hands
47
+ * the same object to delegates as a custom tool, so both run one execute path.
48
+ * The start directory is the per-call `ctx.cwd`, which in a delegate is the
49
+ * delegate session's own cwd. The return type is the SDK's default, unnarrowed
50
+ * definition: a narrowed one is not assignable to `customTools` (its renderers
51
+ * take typed arguments), and `executeSearch` validates the raw arguments itself.
52
+ */
53
+ export declare function createPiSearchTool(options: SearchToolPiOptions): PiToolDefinition;
@@ -0,0 +1,96 @@
1
+ /**
2
+ * The `search` config field: its zod schema piece, the pure merge rule, the
3
+ * user-level file selection, and a reader that never touches project config.
4
+ *
5
+ * Import rule: this module may import only zod, jsonc-parser, node builtins
6
+ * and TYPES from `search-core.ts`. It must never import `config.ts` or
7
+ * `config-schema.ts`. The `systematic-search` bin bundles it, and
8
+ * pulling in `config.ts` would drag the whole config loader (and its jsonc
9
+ * build) into that bundle. `trustProtected` is applied only in
10
+ * `config-schema.ts`, which imports the schema piece from here.
11
+ *
12
+ * Why it exists as one place: the plugin loader (`config.ts`) and the bin both
13
+ * need "validate the `search` block, then merge user and custom". The block is
14
+ * validated on its own, so a bad `search` block drops with one warning and
15
+ * leaves the rest of the file loading. Search still runs, and its results
16
+ * carry a `config unreadable` note (the `unreadable` state). Search must never be the reason the plugin fails to load.
17
+ */
18
+ import { z } from 'zod';
19
+ import type { SearchSettings } from './search-core.js';
20
+ /**
21
+ * The `search` block. No zod defaults anywhere: an absent `search` stays
22
+ * absent, and the core applies its own defaults at use time.
23
+ */
24
+ export declare const SearchSettingsSchema: z.ZodObject<{
25
+ enabled: z.ZodOptional<z.ZodBoolean>;
26
+ }, z.core.$strict>;
27
+ /** What a successful parse of the `search` block yields. Assignable to the core's `SearchSettings`. */
28
+ export type SearchSchemaOutput = z.output<typeof SearchSettingsSchema>;
29
+ export type SearchBlockValidation = {
30
+ readonly ok: true;
31
+ readonly settings: SearchSchemaOutput;
32
+ } | {
33
+ readonly ok: false;
34
+ readonly fields: readonly string[];
35
+ };
36
+ /**
37
+ * Validate a raw `search` value on its own. A failure lists the offending
38
+ * field paths (`search.enabled`) and never a value: a path from
39
+ * a strict object names the parent for an unknown key, so a user-authored key
40
+ * name is not echoed either.
41
+ */
42
+ export declare function validateSearchBlock(value: unknown): SearchBlockValidation;
43
+ /** The one warning for a `search` block that failed its schema. It names fields and no value. */
44
+ export declare function formatSearchBlockWarning(sourcePath: string, fields: readonly string[]): string;
45
+ /**
46
+ * One source's `search` block after schema validation. `settings` is the
47
+ * schema-parsed block, absent when the source has none. `unreadable` is true
48
+ * when the block failed its schema or the file could not be parsed.
49
+ */
50
+ export interface SearchSettingsSource {
51
+ readonly settings?: SearchSchemaOutput | undefined;
52
+ readonly unreadable: boolean;
53
+ }
54
+ export interface MergedSearchSettings {
55
+ readonly settings: SearchSettings | undefined;
56
+ readonly unreadable: boolean;
57
+ }
58
+ /**
59
+ * The one merge rule, used by both `config.ts` and the reader. Sources arrive
60
+ * in priority order, user then custom. `enabled` takes the last source that
61
+ * defines it. `unreadable` is set when any source was.
62
+ */
63
+ export declare function mergeSearchSettings(sources: readonly SearchSettingsSource[]): MergedSearchSettings;
64
+ /**
65
+ * Pick a config file in `dir`: `<basename>.jsonc` when it exists, else the
66
+ * `.json` path (returned even when absent, so callers that stat it still work).
67
+ */
68
+ export declare function selectConfigFile(dir: string, basename: string): string;
69
+ export interface UserLevelConfigDirOptions {
70
+ readonly homeDir?: string;
71
+ readonly userConfigDir?: string;
72
+ /** `null` or a blank string means no custom directory. Leave the key out to read `OPENCODE_CONFIG_DIR`. */
73
+ readonly customConfigDir?: string | null;
74
+ }
75
+ export interface UserLevelConfigDirs {
76
+ readonly homeDir: string;
77
+ readonly userConfigDir: string;
78
+ readonly customConfigDir: string | undefined;
79
+ }
80
+ /**
81
+ * The user-level config directories: `<home>/.config/opencode`, and the
82
+ * `OPENCODE_CONFIG_DIR` directory when it is set. The variable is trimmed and
83
+ * a blank value counts as unset. `config.ts` and the reader both call this.
84
+ */
85
+ export declare function resolveUserLevelConfigDirs(options?: UserLevelConfigDirOptions): UserLevelConfigDirs;
86
+ export interface UserLevelSearchLoad {
87
+ readonly settings: SearchSettings | undefined;
88
+ readonly warnings: readonly string[];
89
+ readonly unreadable: boolean;
90
+ }
91
+ /**
92
+ * Read the `search` block from the two user-level files, user then custom, and
93
+ * merge them. It never reads project config and never throws: an unparseable
94
+ * file or an invalid block gives one warning and `unreadable: true`.
95
+ */
96
+ export declare function loadUserLevelSearchSettings(options?: UserLevelConfigDirOptions): UserLevelSearchLoad;