@fro.bot/systematic 3.27.2 → 3.28.1

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 (34) hide show
  1. package/ATTRIBUTIONS.md +2 -2
  2. package/HARNESSES.md +23 -10
  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 +117 -3
  10. package/dist/lib/agent-resolver.d.ts +15 -3
  11. package/dist/lib/config-protected-fields.d.ts +1 -1
  12. package/dist/lib/config-schema.d.ts +6 -0
  13. package/dist/lib/config.d.ts +13 -0
  14. package/dist/lib/main-module.d.ts +30 -0
  15. package/dist/lib/opencode-v2-skills.d.ts +12 -2
  16. package/dist/lib/opencode-v2.d.ts +1 -0
  17. package/dist/lib/pi-delegate-session.d.ts +3 -1
  18. package/dist/lib/pi-delegate-tool.d.ts +12 -1
  19. package/dist/lib/search-cli.d.ts +52 -0
  20. package/dist/lib/search-core.d.ts +128 -0
  21. package/dist/lib/search-corpus.d.ts +105 -0
  22. package/dist/lib/search-lexical.d.ts +136 -0
  23. package/dist/lib/search-render.d.ts +69 -0
  24. package/dist/lib/search-tool.d.ts +53 -0
  25. package/dist/lib/search-user-config.d.ts +96 -0
  26. package/dist/pi.js +1169 -82
  27. package/package.json +5 -5
  28. package/skills/ce-review/SKILL.md +1 -1
  29. package/skills/ce-review/references/review-output-template.md +1 -1
  30. package/skills/ce-review/scripts/validate-review.mjs +1 -3
  31. package/skills/using-systematic/references/claude-code-profile.md +1 -0
  32. package/skills/using-systematic/references/opencode-profile.md +1 -0
  33. package/skills/using-systematic/references/opencode-v2-profile.md +1 -0
  34. package/skills/using-systematic/references/pi-profile.md +1 -0
package/dist/index.js CHANGED
@@ -2,6 +2,7 @@
2
2
  import {
3
3
  parseFrontmatter,
4
4
  string,
5
+ number,
5
6
  AgentOverlaySchema,
6
7
  CategoryOverlaySchema,
7
8
  isRecord,
@@ -16,8 +17,15 @@ import {
16
17
  findCommandsInDir,
17
18
  extractCommandFrontmatter,
18
19
  findSkillsInDir,
19
- discoverSkills
20
- } from "./index-608preny.js";
20
+ discoverSkills,
21
+ SEARCH_TOOL_NAME,
22
+ SEARCH_ARGS,
23
+ SEARCH_TOOL_DESCRIPTION,
24
+ SEARCH_ARG_DESCRIPTIONS,
25
+ SEARCH_NOTICES,
26
+ SEARCH_CONFIG_UNREADABLE_NOTE,
27
+ runSearch
28
+ } from "./index-9chxhh5j.js";
21
29
 
22
30
  // src/index.ts
23
31
  import path8 from "path";
@@ -970,6 +978,104 @@ function normalizePath(path) {
970
978
  return path.replaceAll("\\", "/").replace(/\/+$/u, "");
971
979
  }
972
980
 
981
+ // src/lib/search-tool.ts
982
+ function isSearchEnabled(settings) {
983
+ return settings?.enabled !== false;
984
+ }
985
+ async function executeSearch(args, startDir, settings, unreadable) {
986
+ try {
987
+ if (startDir === undefined)
988
+ return SEARCH_NOTICES.noProject;
989
+ const record = isRecord(args) ? args : {};
990
+ const response = await runSearch({
991
+ query: record[SEARCH_ARGS.query],
992
+ kind: record[SEARCH_ARGS.kind],
993
+ limit: record[SEARCH_ARGS.limit]
994
+ }, {
995
+ startDir,
996
+ settings,
997
+ ...unreadable === true && { notes: [SEARCH_CONFIG_UNREADABLE_NOTE] }
998
+ });
999
+ return response.text;
1000
+ } catch {
1001
+ return SEARCH_NOTICES.failed;
1002
+ }
1003
+ }
1004
+ function usableDirectory(value) {
1005
+ return typeof value === "string" && value.length > 0 ? value : undefined;
1006
+ }
1007
+ function createSearchTool(options) {
1008
+ const { settings, unreadable } = options;
1009
+ return {
1010
+ description: SEARCH_TOOL_DESCRIPTION,
1011
+ args: {
1012
+ [SEARCH_ARGS.query]: string().describe(SEARCH_ARG_DESCRIPTIONS.query),
1013
+ [SEARCH_ARGS.kind]: string().optional().describe(SEARCH_ARG_DESCRIPTIONS.kind),
1014
+ [SEARCH_ARGS.limit]: number().int().optional().describe(SEARCH_ARG_DESCRIPTIONS.limit)
1015
+ },
1016
+ async execute(args, context) {
1017
+ return executeSearch(args, usableDirectory(context.directory), settings, unreadable);
1018
+ }
1019
+ };
1020
+ }
1021
+ var V2_INPUT_SCHEMA = {
1022
+ type: "object",
1023
+ properties: {
1024
+ [SEARCH_ARGS.query]: {
1025
+ type: "string",
1026
+ description: SEARCH_ARG_DESCRIPTIONS.query
1027
+ },
1028
+ [SEARCH_ARGS.kind]: {
1029
+ type: "string",
1030
+ description: SEARCH_ARG_DESCRIPTIONS.kind
1031
+ },
1032
+ [SEARCH_ARGS.limit]: {
1033
+ type: "integer",
1034
+ description: SEARCH_ARG_DESCRIPTIONS.limit
1035
+ }
1036
+ },
1037
+ required: [SEARCH_ARGS.query],
1038
+ additionalProperties: false
1039
+ };
1040
+ function createV2SearchTool(ctx, settings, unreadable) {
1041
+ return {
1042
+ name: SEARCH_TOOL_NAME,
1043
+ description: SEARCH_TOOL_DESCRIPTION,
1044
+ input: V2_INPUT_SCHEMA,
1045
+ options: { codemode: false },
1046
+ async execute(input) {
1047
+ const startDir = usableDirectory(ctx.location?.directory);
1048
+ return {
1049
+ content: await executeSearch(input, startDir, settings, unreadable),
1050
+ metadata: {}
1051
+ };
1052
+ }
1053
+ };
1054
+ }
1055
+ var installSearch = async ({
1056
+ ctx,
1057
+ snapshot,
1058
+ guard,
1059
+ report
1060
+ }) => {
1061
+ const settings = snapshot.config.search;
1062
+ const unreadable = snapshot.config.searchUnreadable;
1063
+ if (!isSearchEnabled(settings))
1064
+ return;
1065
+ const reported = new Set;
1066
+ const toolTransform = guard.sync("search tool transform", (editor) => {
1067
+ if (editor.get(SEARCH_TOOL_NAME) !== undefined) {
1068
+ if (!reported.has(SEARCH_TOOL_NAME)) {
1069
+ reported.add(SEARCH_TOOL_NAME);
1070
+ report(`tool "${SEARCH_TOOL_NAME}" is already registered by another plugin; not registering the bundled one`);
1071
+ }
1072
+ return;
1073
+ }
1074
+ editor.add(createV2SearchTool(ctx, settings, unreadable));
1075
+ });
1076
+ await guard.async("search tool registration", () => ctx.tool.transform(toolTransform))();
1077
+ };
1078
+
973
1079
  // src/lib/skill-resolver.ts
974
1080
  import fs5 from "fs";
975
1081
  import path5 from "path";
@@ -1348,7 +1454,13 @@ var createOpenCodeV1Hooks = async ({ client, directory }, { packageRoot }) => {
1348
1454
  bundledSkillsDir,
1349
1455
  disabledSkills: config.disabled_skills,
1350
1456
  outputStore: skillOutputStore
1351
- })
1457
+ }),
1458
+ ...isSearchEnabled(config.search) && {
1459
+ systematic_search: createSearchTool({
1460
+ settings: config.search,
1461
+ unreadable: config.searchUnreadable
1462
+ })
1463
+ }
1352
1464
  },
1353
1465
  "tool.execute.after": async (input, output) => {
1354
1466
  try {
@@ -1856,12 +1968,14 @@ var installAgents = async ({ ctx, snapshot, guard }) => {
1856
1968
  var DEFAULT_INSTALLERS = {
1857
1969
  agents: installAgents,
1858
1970
  skills: installSkills,
1971
+ search: installSearch,
1859
1972
  commands: installCommands,
1860
1973
  bootstrap: installBootstrap
1861
1974
  };
1862
1975
  var INSTALLER_ORDER = [
1863
1976
  "agents",
1864
1977
  "skills",
1978
+ "search",
1865
1979
  "commands",
1866
1980
  "bootstrap"
1867
1981
  ];
@@ -18,15 +18,27 @@ export interface AgentCatalogEntry {
18
18
  }
19
19
  /** Fails closed if the same persona name appears under more than one category. */
20
20
  export declare function buildAgentCatalog(agentsDir: string): AgentCatalogEntry[];
21
- /** Resolves a persona by exact flat name from the catalog. */
21
+ /**
22
+ * Resolves a persona by exact flat name from the catalog. Failing that, accepts
23
+ * the canonical qualified form `systematic:<category>:<name>` that bundled skills
24
+ * dispatch with, translated here at the host boundary: the stripped name must
25
+ * match an entry whose `category` equals the qualified category. No other
26
+ * aliases or case folding.
27
+ */
22
28
  export declare function resolveAgent(catalog: AgentCatalogEntry[], name: string): AgentCatalogEntry | undefined;
23
29
  /**
24
30
  * Deterministic, bounded description of available personas for the delegation
25
31
  * tool's description/parameter hint text. Stable ordering (catalog is pre-sorted).
26
32
  */
27
33
  export declare function renderAgentCatalogCompact(catalog: AgentCatalogEntry[]): string;
28
- /** Pi built-in read-only tool names used as the default allowlist. */
29
- export declare const DEFAULT_READONLY_TOOLS: readonly ['read', 'grep', 'find', 'ls'];
34
+ /**
35
+ * The default delegate allowlist: Pi's built-in read-only tool names plus
36
+ * `systematic_search`, the one read-only parent tool a delegate may call.
37
+ * `systematic_search` is not a Pi built-in. It is active in a delegate only
38
+ * when `src/pi.ts` also passes its definition as a custom tool, and a name
39
+ * with no definition is inert.
40
+ */
41
+ export declare const DEFAULT_READONLY_TOOLS: readonly ['read', 'grep', 'find', 'ls', "systematic_search"];
30
42
  export interface ResolvedToolAllowlist {
31
43
  tools: string[];
32
44
  }
@@ -18,5 +18,5 @@
18
18
  * reason it exists as a separate file rather than living directly in
19
19
  * `config.ts`.
20
20
  */
21
- export declare const CONFIG_PROTECTED_FIELD_PATHS: readonly ['profiles', 'allow_project_profiles', 'agents.*.model', 'agents.*.permission', 'agents.*.skills', 'agents.*.variant', 'agents.*.opencode', 'agents.*.pi', 'categories.*.model', 'categories.*.permission', 'categories.*.skills', 'categories.*.variant', 'categories.*.opencode', 'categories.*.pi'];
21
+ export declare const CONFIG_PROTECTED_FIELD_PATHS: readonly ['profiles', 'allow_project_profiles', 'search', 'agents.*.model', 'agents.*.permission', 'agents.*.skills', 'agents.*.variant', 'agents.*.opencode', 'agents.*.pi', 'categories.*.model', 'categories.*.permission', 'categories.*.skills', 'categories.*.variant', 'categories.*.opencode', 'categories.*.pi'];
22
22
  export type ConfigProtectedFieldPath = (typeof CONFIG_PROTECTED_FIELD_PATHS)[number];
@@ -385,6 +385,9 @@ export declare function createSystematicConfigSchema(opts: SystematicConfigSchem
385
385
  }, z.core.$strict>>>;
386
386
  profile: z.ZodOptional<z.ZodNullable<z.ZodString>>;
387
387
  allow_project_profiles: z.ZodDefault<z.ZodBoolean>;
388
+ search: z.ZodOptional<z.ZodObject<{
389
+ enabled: z.ZodOptional<z.ZodBoolean>;
390
+ }, z.core.$strict>>;
388
391
  disabled_skills: z.ZodDefault<z.ZodArray<z.ZodEnum<{
389
392
  [x: string]: string;
390
393
  }>>>;
@@ -580,6 +583,9 @@ export declare const SystematicConfigSchema: z.ZodObject<{
580
583
  }, z.core.$strict>>>;
581
584
  profile: z.ZodOptional<z.ZodNullable<z.ZodString>>;
582
585
  allow_project_profiles: z.ZodDefault<z.ZodBoolean>;
586
+ search: z.ZodOptional<z.ZodObject<{
587
+ enabled: z.ZodOptional<z.ZodBoolean>;
588
+ }, z.core.$strict>>;
583
589
  disabled_skills: z.ZodDefault<z.ZodArray<z.ZodEnum<{
584
590
  [x: string]: string;
585
591
  }>>>;
@@ -1,5 +1,6 @@
1
1
  import { CONFIG_PROTECTED_FIELD_PATHS, type ConfigProtectedFieldPath } from './config-protected-fields.js';
2
2
  import { type RoutingTarget } from './routing-resolver.js';
3
+ import type { SearchSettings } from './search-core.js';
3
4
  export interface BootstrapConfig {
4
5
  enabled: boolean;
5
6
  file?: string;
@@ -172,6 +173,18 @@ export interface SystematicConfig {
172
173
  pi_subagents?: PiSubagentsOverlayMap;
173
174
  skills_as_commands: boolean;
174
175
  allow_project_profiles: boolean;
176
+ /**
177
+ * Merged `search` settings from user and custom config only. Absent when
178
+ * neither defines one: there is no default, and the core applies its own at
179
+ * use time.
180
+ */
181
+ search?: SearchSettings;
182
+ /**
183
+ * Set (to `true`) when a user or custom `search` block, or its file, could
184
+ * not be read. That block is ignored and search results carry a
185
+ * `config unreadable` note. Absent otherwise.
186
+ */
187
+ searchUnreadable?: boolean;
175
188
  }
176
189
  export declare const DEFAULT_CONFIG: SystematicConfig;
177
190
  /**
@@ -0,0 +1,30 @@
1
+ /**
2
+ * The direct-execution guard shared by `src/cli.ts`, `src/claude-code-validator-bin.ts`
3
+ * and the `systematic-search` bin.
4
+ *
5
+ * It replaces `import.meta.main`, which Node only gained in 24.2. A module that
6
+ * runs under Node 20 or 22 would see `undefined` and never self-execute. The
7
+ * guard compares the realpath of `argv[1]` with the realpath of the module, so
8
+ * it holds when the file is reached through a symlink (the npm `.bin` link, a
9
+ * macOS `/var` to `/private/var` temp path) or a relative path.
10
+ *
11
+ * Fail-closed: when either side is missing or cannot be resolved the answer is
12
+ * `false`, so importing the module for tests or tooling runs nothing.
13
+ *
14
+ * The caller passes its own `import.meta.url`. This module cannot read it: in a
15
+ * bundle with code splitting this file may live in a shared chunk, and its URL
16
+ * would then name the chunk and never the entry.
17
+ *
18
+ * `src/ce-review-validator.ts` keeps its own copy on purpose. It feeds a
19
+ * committed bundle, and keeping it self-contained keeps that bundle's digest
20
+ * independent of this file.
21
+ */
22
+ /**
23
+ * Whether the module at `moduleUrl` is the process entry point.
24
+ *
25
+ * @param moduleUrl The caller's `import.meta.url`.
26
+ * @param argv The process argument vector. Defaults to `process.argv`; the
27
+ * entry script is `argv[1]`. A vector with no `argv[1]` (a REPL, `node -e`)
28
+ * is never a main module.
29
+ */
30
+ export declare function isMainModule(moduleUrl: string, argv?: readonly string[]): boolean;
@@ -1,5 +1,5 @@
1
1
  import type { V2Installer } from './opencode-v2.js';
2
- import { type SkillOutputStore, type SkillToolDescriptor } from './skill-tool.js';
2
+ import { type SkillOutputStore } from './skill-tool.js';
3
3
  /**
4
4
  * Skills on OpenCode v2: the enabled bundled skills are registered with the
5
5
  * host so its native `skill` tool and `<available_skills>` list see them, and
@@ -31,10 +31,20 @@ export interface V2ToolContext {
31
31
  id: string;
32
32
  progress(update: Record<string, unknown>): Promise<void>;
33
33
  }
34
+ /** The JSON Schema shape of a tool's input: an object of described properties. */
35
+ export type V2ToolInputSchema = {
36
+ type: 'object';
37
+ properties: Record<string, {
38
+ type: string;
39
+ description: string;
40
+ }>;
41
+ required: readonly string[];
42
+ additionalProperties: false;
43
+ };
34
44
  export interface V2ToolDefinition {
35
45
  name: string;
36
46
  description: string;
37
- input: SkillToolDescriptor['input'];
47
+ input: V2ToolInputSchema;
38
48
  options: {
39
49
  codemode: false;
40
50
  };
@@ -32,6 +32,7 @@ export type V2Installer = (input: V2InstallInput) => Promise<void> | void;
32
32
  export interface V2Installers {
33
33
  agents: V2Installer;
34
34
  skills: V2Installer;
35
+ search: V2Installer;
35
36
  commands: V2Installer;
36
37
  bootstrap: V2Installer;
37
38
  }
@@ -1,5 +1,5 @@
1
1
  /** Real Pi session-construction for `systematic_delegate`. `noExtensions: true` is the structural depth-1 boundary preventing the child from re-registering `systematic_delegate` or any project/user extension. */
2
- import type { CreateAgentSessionOptions, CreateAgentSessionResult, ResourceLoader } from '@earendil-works/pi-coding-agent';
2
+ import type { CreateAgentSessionOptions, CreateAgentSessionResult, ResourceLoader, ToolDefinition } from '@earendil-works/pi-coding-agent';
3
3
  import { DefaultResourceLoader, SessionManager } from '@earendil-works/pi-coding-agent';
4
4
  /** `DefaultResourceLoaderOptions` is not exported by the package, so it's derived from the constructor's parameter type. */
5
5
  type DefaultResourceLoaderOptions = ConstructorParameters<typeof DefaultResourceLoader>[0];
@@ -25,6 +25,8 @@ export declare function buildDelegateAgentSessionOptions(options: {
25
25
  /** Omitted (not `undefined`-valued) when unset, so the child inherits Pi's default thinking level instead of an explicit `undefined` overriding it. */
26
26
  thinkingLevel?: CreateAgentSessionOptions['thinkingLevel'];
27
27
  allowedToolNames: string[];
28
+ /** Definitions the child may call. A definition is active only when its name is also in `allowedToolNames`. */
29
+ customTools: ToolDefinition[];
28
30
  resourceLoader: ResourceLoader;
29
31
  sessionManager: ReturnType<typeof SessionManager.inMemory>;
30
32
  }): CreateAgentSessionOptions;
@@ -13,7 +13,7 @@ export type DelegateParentModel = NonNullable<ExtensionContext['model']>;
13
13
  /**
14
14
  * Derived from the pinned Pi SDK's own `CreateAgentSessionOptions` type
15
15
  * (`'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'` as of
16
- * @earendil-works/pi-coding-agent@0.83.0) rather than hand-declared, so a
16
+ * @earendil-works/pi-coding-agent@1.4.0) rather than hand-declared, so a
17
17
  * future SDK bump that changes the union surfaces as a type error here
18
18
  * instead of silently drifting. Value-for-value identical to Systematic's
19
19
  * own `piSubagentsThinkingSchema` enum in config-schema.ts today — see
@@ -42,10 +42,21 @@ export type CreateDelegateSession = (options: {
42
42
  cwd: string;
43
43
  systemPromptOverride: string;
44
44
  allowedToolNames: string[];
45
+ /**
46
+ * Parent-supplied tool definitions the child may call. A definition is active
47
+ * only when its name is also in `allowedToolNames`. Omitted means none.
48
+ */
49
+ customTools?: ToolDefinition[];
45
50
  }) => Promise<DelegateSessionLike>;
46
51
  export interface PiDelegateToolDeps {
47
52
  catalog: AgentCatalogEntry[];
48
53
  createDelegateSession: CreateDelegateSession;
54
+ /**
55
+ * Tool definitions delegates may call, in addition to Pi's built-ins. Today
56
+ * `src/pi.ts` supplies the one shared `systematic_search` definition, or
57
+ * nothing when search is disabled. Nothing else from the parent passes.
58
+ */
59
+ customTools?: ToolDefinition[];
49
60
  /**
50
61
  * Merged agent/category routing overlays from `loadConfigWithSources`'s
51
62
  * `overlays` field. Omit for a config-neutral tool — routing then always
@@ -0,0 +1,52 @@
1
+ /**
2
+ * The command-line adapter for durable-output search, shared by
3
+ * `systematic search` (`src/cli.ts`) and the `systematic-search` plugin
4
+ * bin. Like the tool adapters it does host I/O only: parse flags, pick the
5
+ * start directory, hand the settings to `runSearch`, and map the response to
6
+ * an exit code. Every byte of a search result is the core's text.
7
+ *
8
+ * It never loads config itself. The caller injects a settings loader, so
9
+ * `cli.ts` can use the full loader (project config included, with its strip
10
+ * warnings) and the bin can use the user-level reader alone.
11
+ *
12
+ * Exit codes: 0 for results, no hits and disabled; 1 for an unexpected
13
+ * failure; 2 for usage errors. There is no `--json`.
14
+ *
15
+ * Import rule: this module is bundled into the `systematic-search` bin, so it
16
+ * may import only `search-core.ts` and node builtins.
17
+ */
18
+ import { type SearchSettings } from './search-core.js';
19
+ /**
20
+ * The usage text for one surface. `commandName` is what that surface's users
21
+ * type (`systematic search` or `systematic-search`), so the text never tells a
22
+ * bin user to run a command they may not have.
23
+ */
24
+ export declare function searchCliUsage(commandName: string): string;
25
+ /** What `search.enabled: false` prints. The researcher falls back to grep on it. */
26
+ export declare const SEARCH_CLI_DISABLED_NOTICE = "Search is disabled (search.enabled is false in your Systematic config), so there is nothing to search.";
27
+ /** What a settings loader returns. The bin's user-level reader returns the same shape. */
28
+ export interface SearchCliSettingsLoad {
29
+ readonly settings?: SearchSettings | undefined;
30
+ /** Printed to stderr, one per line, before the search runs. */
31
+ readonly warnings: readonly string[];
32
+ /** A source could not be read: its settings were ignored and results carry a `config unreadable` note. */
33
+ readonly unreadable: boolean;
34
+ }
35
+ /** Receives the absolute start directory. A loader that does not need it ignores it. */
36
+ export type SearchCliSettingsLoader = (startDir: string) => SearchCliSettingsLoad;
37
+ export interface SearchCliOptions {
38
+ /** The arguments after the `search` command: query words and flags. */
39
+ readonly argv: readonly string[];
40
+ readonly cwd?: string;
41
+ /** The command the usage text names: `systematic search` or `systematic-search`. */
42
+ readonly usageName: string;
43
+ readonly loadSettings: SearchCliSettingsLoader;
44
+ readonly outputSink?: (message: string) => void;
45
+ readonly errorSink?: (message: string) => void;
46
+ }
47
+ /**
48
+ * Run `systematic search`. Flag parse errors are decided first, before any
49
+ * settings are loaded; a request the core rejects (an empty query, a bad
50
+ * `--limit`) is decided after, so a disabled search says so first. Returns the process exit code and never throws.
51
+ */
52
+ export declare function runSearchCli(options: SearchCliOptions): Promise<number>;
@@ -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`: strips a leading BOM, supplies the
94
+ * newline its regex needs when the closing `---` is the last line, and reads
95
+ * only known fields, narrowing each. No frontmatter means a body-only document
96
+ * with no warning. Invalid YAML, or a frontmatter block that is not a mapping,
97
+ * 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;