@fro.bot/systematic 3.27.2 → 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.
- package/ATTRIBUTIONS.md +2 -2
- package/HARNESSES.md +22 -9
- package/agents/research/learnings-researcher.md +49 -9
- package/dist/claude-code-search.d.ts +30 -0
- package/dist/claude-code-validator-bin.d.ts +17 -0
- package/dist/cli.d.ts +18 -0
- package/dist/cli.js +335 -108
- package/dist/{index-608preny.js → index-9chxhh5j.js} +1120 -72
- package/dist/index.js +117 -3
- package/dist/lib/agent-resolver.d.ts +8 -2
- package/dist/lib/config-protected-fields.d.ts +1 -1
- package/dist/lib/config-schema.d.ts +6 -0
- package/dist/lib/config.d.ts +13 -0
- package/dist/lib/main-module.d.ts +30 -0
- package/dist/lib/opencode-v2-skills.d.ts +12 -2
- package/dist/lib/opencode-v2.d.ts +1 -0
- package/dist/lib/pi-delegate-session.d.ts +3 -1
- package/dist/lib/pi-delegate-tool.d.ts +12 -1
- package/dist/lib/search-cli.d.ts +52 -0
- package/dist/lib/search-core.d.ts +128 -0
- package/dist/lib/search-corpus.d.ts +105 -0
- package/dist/lib/search-lexical.d.ts +136 -0
- package/dist/lib/search-render.d.ts +69 -0
- package/dist/lib/search-tool.d.ts +53 -0
- package/dist/lib/search-user-config.d.ts +96 -0
- package/dist/pi.js +1155 -77
- package/package.json +3 -3
- package/skills/ce-review/SKILL.md +1 -1
- package/skills/ce-review/references/review-output-template.md +1 -1
- package/skills/ce-review/scripts/validate-review.mjs +1 -3
- package/skills/using-systematic/references/claude-code-profile.md +1 -0
- package/skills/using-systematic/references/opencode-profile.md +1 -0
- package/skills/using-systematic/references/opencode-v2-profile.md +1 -0
- 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
|
-
|
|
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
|
];
|
|
@@ -25,8 +25,14 @@ export declare function resolveAgent(catalog: AgentCatalogEntry[], name: string)
|
|
|
25
25
|
* tool's description/parameter hint text. Stable ordering (catalog is pre-sorted).
|
|
26
26
|
*/
|
|
27
27
|
export declare function renderAgentCatalogCompact(catalog: AgentCatalogEntry[]): string;
|
|
28
|
-
/**
|
|
29
|
-
|
|
28
|
+
/**
|
|
29
|
+
* The default delegate allowlist: Pi's built-in read-only tool names plus
|
|
30
|
+
* `systematic_search`, the one read-only parent tool a delegate may call.
|
|
31
|
+
* `systematic_search` is not a Pi built-in. It is active in a delegate only
|
|
32
|
+
* when `src/pi.ts` also passes its definition as a custom tool, and a name
|
|
33
|
+
* with no definition is inert.
|
|
34
|
+
*/
|
|
35
|
+
export declare const DEFAULT_READONLY_TOOLS: readonly ['read', 'grep', 'find', 'ls', "systematic_search"];
|
|
30
36
|
export interface ResolvedToolAllowlist {
|
|
31
37
|
tools: string[];
|
|
32
38
|
}
|
|
@@ -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
|
}>>>;
|
package/dist/lib/config.d.ts
CHANGED
|
@@ -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
|
|
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:
|
|
47
|
+
input: V2ToolInputSchema;
|
|
38
48
|
options: {
|
|
39
49
|
codemode: false;
|
|
40
50
|
};
|
|
@@ -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@
|
|
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` (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;
|