@phren/cli 0.1.42 → 0.1.45
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/dist/capabilities/cli.js +1 -1
- package/dist/capabilities/mcp.js +1 -1
- package/dist/capabilities/vscode.js +3 -3
- package/dist/capabilities/web-ui.js +29 -29
- package/dist/cli/actions.d.ts +1 -1
- package/dist/cli/actions.js +7 -2
- package/dist/cli/config-proactivity.d.ts +6 -6
- package/dist/cli/hooks-output.js +15 -6
- package/dist/cli/hooks.d.ts +1 -1
- package/dist/cli/hooks.js +16 -5
- package/dist/cli/session-stop.d.ts +1 -1
- package/dist/cli/session-tool-hook.d.ts +1 -1
- package/dist/cli-registry.js +1 -1
- package/dist/data/access.js +2 -1
- package/dist/generated/memory-ui-graph.browser.js +481 -318
- package/dist/governance/locks.js +6 -0
- package/dist/governance/scores.d.ts +9 -1
- package/dist/governance/scores.js +12 -1
- package/dist/graph-core/index.d.ts +2 -0
- package/dist/graph-core/index.js +2 -0
- package/dist/graph-core/model.d.ts +84 -0
- package/dist/graph-core/model.js +355 -0
- package/dist/graph-core/types.d.ts +110 -0
- package/dist/graph-core/types.js +43 -0
- package/dist/index.js +4 -1
- package/dist/init/init-uninstall.d.ts +1 -0
- package/dist/init/init-uninstall.js +13 -3
- package/dist/init/setup.js +11 -4
- package/dist/link/context.js +2 -1
- package/dist/link/link.js +3 -2
- package/dist/link/skills.js +2 -1
- package/dist/memory-ui-graph.runtime.js +481 -318
- package/dist/phren-core.d.ts +16 -0
- package/dist/phren-core.js +21 -0
- package/dist/phren-paths.js +8 -4
- package/dist/profile-store.d.ts +2 -0
- package/dist/profile-store.js +16 -19
- package/dist/project-config.js +2 -1
- package/dist/shared/fragment-graph.js +7 -2
- package/dist/shared/index.js +1 -1
- package/dist/shared/retrieval.d.ts +38 -0
- package/dist/shared/retrieval.js +62 -4
- package/dist/shell/entry.d.ts +10 -2
- package/dist/shell/entry.js +128 -97
- package/dist/shell/graph/canvas.d.ts +64 -0
- package/dist/shell/graph/canvas.js +256 -0
- package/dist/shell/graph/controller.d.ts +164 -0
- package/dist/shell/graph/controller.js +645 -0
- package/dist/shell/graph/glyphs.d.ts +12 -0
- package/dist/shell/graph/glyphs.js +31 -0
- package/dist/shell/graph/graph-view.d.ts +12 -0
- package/dist/shell/graph/graph-view.js +408 -0
- package/dist/shell/graph/layout.d.ts +68 -0
- package/dist/shell/graph/layout.js +267 -0
- package/dist/shell/input.d.ts +4 -1
- package/dist/shell/input.js +28 -5
- package/dist/shell/intro.d.ts +37 -0
- package/dist/shell/intro.js +82 -0
- package/dist/shell/keys.d.ts +36 -0
- package/dist/shell/keys.js +107 -0
- package/dist/shell/logo-fx.d.ts +35 -0
- package/dist/shell/logo-fx.js +128 -0
- package/dist/shell/render.d.ts +34 -1
- package/dist/shell/render.js +220 -66
- package/dist/shell/shell.d.ts +13 -1
- package/dist/shell/shell.js +61 -10
- package/dist/shell/startup.d.ts +37 -0
- package/dist/shell/startup.js +105 -0
- package/dist/shell/state-store.d.ts +1 -1
- package/dist/shell/state-store.js +1 -1
- package/dist/shell/types.js +1 -0
- package/dist/shell/view.d.ts +3 -0
- package/dist/shell/view.js +26 -4
- package/dist/store-registry.d.ts +13 -0
- package/dist/store-registry.js +109 -37
- package/dist/test-global-setup.d.ts +1 -0
- package/dist/test-global-setup.js +22 -0
- package/dist/tool-registry.js +1 -0
- package/dist/tools/memory.js +12 -5
- package/dist/tools/ops.js +1 -1
- package/dist/ui/data.d.ts +15 -7
- package/dist/ui/data.js +102 -3
- package/dist/utils-fts.js +2 -1
- package/dist/utils-helpers.d.ts +1 -0
- package/dist/utils-helpers.js +6 -0
- package/dist/utils.d.ts +1 -1
- package/dist/utils.js +1 -1
- package/package.json +38 -7
- package/starter/global/skills/phren-consolidate/SKILL.md +152 -0
- package/starter/global/skills/phren-discover/SKILL.md +175 -0
- package/starter/global/skills/phren-init/SKILL.md +216 -0
- package/starter/global/skills/phren-profiles/SKILL.md +121 -0
- package/starter/global/skills/phren-sync/SKILL.md +261 -0
- package/dist/init-uninstall.d.ts +0 -3
- package/dist/init-uninstall.js +0 -514
- package/dist/init-walkthrough.d.ts +0 -55
- package/dist/init-walkthrough.js +0 -524
package/dist/phren-core.d.ts
CHANGED
|
@@ -48,6 +48,22 @@ export declare function phrenErr<T>(error: string, code?: PhrenErrorCode): Phren
|
|
|
48
48
|
export declare function forwardErr<T>(result: PhrenResult<unknown>): PhrenResult<T>;
|
|
49
49
|
export declare function parsePhrenErrorCode(msg: string): PhrenErrorCode | undefined;
|
|
50
50
|
export declare function isRecord(value: unknown): value is Record<string, unknown>;
|
|
51
|
+
/**
|
|
52
|
+
* `yaml.load` with js-yaml 4's empty-document behaviour.
|
|
53
|
+
*
|
|
54
|
+
* js-yaml 5 throws YAMLException("expected a document, but the input is empty")
|
|
55
|
+
* for input that is blank, whitespace, or comments only — where 4 returned
|
|
56
|
+
* `undefined`. phren's config files legitimately look like that: a freshly
|
|
57
|
+
* scaffolded `machines.yaml` is a single header comment, and an untouched
|
|
58
|
+
* profile can be empty. Every caller already handles `undefined`, but a throw
|
|
59
|
+
* is read as a parse failure, which would report those files as malformed —
|
|
60
|
+
* and `stores.yaml` refuses to write back over a file it could not parse, so
|
|
61
|
+
* an empty registry would have become unrepairable by the CLI.
|
|
62
|
+
*
|
|
63
|
+
* Only genuinely empty documents are absorbed. `---`, `null` and real syntax
|
|
64
|
+
* errors reach js-yaml exactly as before.
|
|
65
|
+
*/
|
|
66
|
+
export declare function loadYamlDocument<T = unknown>(source: string, load: (source: string) => unknown): T | undefined;
|
|
51
67
|
/** Shallow-merge data onto defaults so missing keys get filled in. */
|
|
52
68
|
export declare function withDefaults<T extends object>(data: Partial<T>, defaults: T): T;
|
|
53
69
|
/**
|
package/dist/phren-core.js
CHANGED
|
@@ -70,6 +70,27 @@ export function parsePhrenErrorCode(msg) {
|
|
|
70
70
|
export function isRecord(value) {
|
|
71
71
|
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
72
72
|
}
|
|
73
|
+
/**
|
|
74
|
+
* `yaml.load` with js-yaml 4's empty-document behaviour.
|
|
75
|
+
*
|
|
76
|
+
* js-yaml 5 throws YAMLException("expected a document, but the input is empty")
|
|
77
|
+
* for input that is blank, whitespace, or comments only — where 4 returned
|
|
78
|
+
* `undefined`. phren's config files legitimately look like that: a freshly
|
|
79
|
+
* scaffolded `machines.yaml` is a single header comment, and an untouched
|
|
80
|
+
* profile can be empty. Every caller already handles `undefined`, but a throw
|
|
81
|
+
* is read as a parse failure, which would report those files as malformed —
|
|
82
|
+
* and `stores.yaml` refuses to write back over a file it could not parse, so
|
|
83
|
+
* an empty registry would have become unrepairable by the CLI.
|
|
84
|
+
*
|
|
85
|
+
* Only genuinely empty documents are absorbed. `---`, `null` and real syntax
|
|
86
|
+
* errors reach js-yaml exactly as before.
|
|
87
|
+
*/
|
|
88
|
+
export function loadYamlDocument(source, load) {
|
|
89
|
+
// Strip blank and comment-only lines; anything left is a document to parse.
|
|
90
|
+
if (!source.replace(/^\s*(#.*)?$/gm, "").trim())
|
|
91
|
+
return undefined;
|
|
92
|
+
return load(source);
|
|
93
|
+
}
|
|
73
94
|
/** Shallow-merge data onto defaults so missing keys get filled in. */
|
|
74
95
|
export function withDefaults(data, defaults) {
|
|
75
96
|
const merged = { ...defaults };
|
package/dist/phren-paths.js
CHANGED
|
@@ -4,7 +4,7 @@ import * as path from "path";
|
|
|
4
4
|
import * as crypto from "crypto";
|
|
5
5
|
import * as yaml from "js-yaml";
|
|
6
6
|
import { bootstrapPhrenDotEnv } from "./phren-dotenv.js";
|
|
7
|
-
import { PhrenError, isRecord, RESERVED_PROJECT_DIR_NAMES } from "./phren-core.js";
|
|
7
|
+
import { PhrenError, isRecord, loadYamlDocument, RESERVED_PROJECT_DIR_NAMES } from "./phren-core.js";
|
|
8
8
|
import { errorMessage, isValidProjectName, safeProjectPath } from "./utils.js";
|
|
9
9
|
import { FINDINGS_FILENAME } from "./data/access.js";
|
|
10
10
|
bootstrapPhrenDotEnv();
|
|
@@ -128,7 +128,7 @@ export function readRootManifest(phrenPath) {
|
|
|
128
128
|
if (!fs.existsSync(manifestFile))
|
|
129
129
|
return null;
|
|
130
130
|
try {
|
|
131
|
-
const parsed =
|
|
131
|
+
const parsed = loadYamlDocument(fs.readFileSync(manifestFile, "utf8"), (text) => yaml.load(text, { schema: yaml.CORE_SCHEMA }));
|
|
132
132
|
return normalizeManifest(parsed);
|
|
133
133
|
}
|
|
134
134
|
catch (err) {
|
|
@@ -176,7 +176,11 @@ export function findNearestPhrenPath(startDir = process.cwd()) {
|
|
|
176
176
|
let current = path.resolve(startDir);
|
|
177
177
|
while (true) {
|
|
178
178
|
const localCandidate = path.join(current, ".phren");
|
|
179
|
-
|
|
179
|
+
// Only a manifest counts on the cwd walk. Loose install markers are
|
|
180
|
+
// enough for the user's own ~/.phren or an explicit PHREN_PATH, but a
|
|
181
|
+
// cloned repo could ship `.phren/global/` and become the store — with
|
|
182
|
+
// its `.env` loaded — just by being cd'd into.
|
|
183
|
+
if (hasRootManifest(localCandidate))
|
|
180
184
|
return localCandidate;
|
|
181
185
|
const parent = path.dirname(current);
|
|
182
186
|
if (parent === current)
|
|
@@ -578,7 +582,7 @@ export function getProjectDirs(phrenPath, profile) {
|
|
|
578
582
|
return [];
|
|
579
583
|
}
|
|
580
584
|
try {
|
|
581
|
-
const data =
|
|
585
|
+
const data = loadYamlDocument(fs.readFileSync(profilePath, "utf-8"), (text) => yaml.load(text, { schema: yaml.CORE_SCHEMA }));
|
|
582
586
|
const projects = isRecord(data) ? data.projects : undefined;
|
|
583
587
|
if (!Array.isArray(projects)) {
|
|
584
588
|
errorLog("getProjectDirs", `${PhrenError.MALFORMED_YAML}: Profile YAML missing valid "projects" array: ${profilePath}`);
|
package/dist/profile-store.d.ts
CHANGED
|
@@ -23,6 +23,8 @@ export interface ProjectCard {
|
|
|
23
23
|
name: string;
|
|
24
24
|
summary: string;
|
|
25
25
|
docs: string[];
|
|
26
|
+
/** Name of the non-primary store this project lives in, if any. */
|
|
27
|
+
store?: string;
|
|
26
28
|
}
|
|
27
29
|
export declare function resolveActiveProfile(phrenPath: string, requestedProfile?: string): PhrenResult<string | undefined>;
|
|
28
30
|
export declare function getDefaultMachineAlias(): string;
|
package/dist/profile-store.js
CHANGED
|
@@ -2,6 +2,7 @@ import * as fs from "fs";
|
|
|
2
2
|
import * as path from "path";
|
|
3
3
|
import * as crypto from "crypto";
|
|
4
4
|
import * as yaml from "js-yaml";
|
|
5
|
+
import { loadYamlDocument } from "./phren-core.js";
|
|
5
6
|
import { phrenErr, PhrenError, phrenOk, forwardErr, getProjectDirs, readRootManifest, } from "./shared.js";
|
|
6
7
|
import { defaultMachineName, getMachineName } from "./machine-identity.js";
|
|
7
8
|
import { errorMessage, isValidProjectName } from "./utils.js";
|
|
@@ -54,7 +55,7 @@ export function listMachines(phrenPath) {
|
|
|
54
55
|
return phrenErr(`machines.yaml not found. Run 'phren init' to set up your phren.`, PhrenError.FILE_NOT_FOUND);
|
|
55
56
|
try {
|
|
56
57
|
const raw = fs.readFileSync(machinesPath, "utf8");
|
|
57
|
-
const parsed = yaml.load(
|
|
58
|
+
const parsed = loadYamlDocument(raw, (text) => yaml.load(text, { schema: yaml.CORE_SCHEMA }));
|
|
58
59
|
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
|
|
59
60
|
return phrenErr(`machines.yaml is empty or not valid YAML. Check the file format or run 'phren doctor --fix'.`, PhrenError.MALFORMED_YAML);
|
|
60
61
|
const cleaned = {};
|
|
@@ -214,7 +215,7 @@ export function listProfiles(phrenPath) {
|
|
|
214
215
|
const full = path.join(profilesDir, file);
|
|
215
216
|
try {
|
|
216
217
|
const raw = fs.readFileSync(full, "utf8");
|
|
217
|
-
const parsed = yaml.load(
|
|
218
|
+
const parsed = loadYamlDocument(raw, (text) => yaml.load(text, { schema: yaml.CORE_SCHEMA }));
|
|
218
219
|
const data = parsed && typeof parsed === "object" && !Array.isArray(parsed)
|
|
219
220
|
? parsed
|
|
220
221
|
: null;
|
|
@@ -306,22 +307,14 @@ function buildProjectCard(dir) {
|
|
|
306
307
|
return { name, summary, docs };
|
|
307
308
|
}
|
|
308
309
|
export function listProjectCards(phrenPath, profile) {
|
|
309
|
-
const dirs = getProjectDirs(phrenPath, profile)
|
|
310
|
+
const dirs = getProjectDirs(phrenPath, profile);
|
|
310
311
|
const cards = dirs.map(buildProjectCard);
|
|
311
312
|
const seen = new Set(dirs.map((d) => path.basename(d)));
|
|
312
|
-
//
|
|
313
|
+
// Team stores carry their own subscription list (StoreEntry.projects, applied
|
|
314
|
+
// by getStoreProjectDirs). The profile's project list scopes the *primary*
|
|
315
|
+
// store, so filtering team projects through it hid every one of them — a
|
|
316
|
+
// profile never names projects that live in someone else's store.
|
|
313
317
|
try {
|
|
314
|
-
// Resolve the profile's project allow-list (if any)
|
|
315
|
-
let profileProjectNames;
|
|
316
|
-
if (profile) {
|
|
317
|
-
const profiles = listProfiles(phrenPath);
|
|
318
|
-
if (profiles.ok) {
|
|
319
|
-
const active = profiles.data.find((p) => p.name === profile);
|
|
320
|
-
if (active && active.projects.length > 0) {
|
|
321
|
-
profileProjectNames = new Set(active.projects);
|
|
322
|
-
}
|
|
323
|
-
}
|
|
324
|
-
}
|
|
325
318
|
for (const store of getNonPrimaryStores(phrenPath)) {
|
|
326
319
|
if (!fs.existsSync(store.path))
|
|
327
320
|
continue;
|
|
@@ -329,19 +322,23 @@ export function listProjectCards(phrenPath, profile) {
|
|
|
329
322
|
const name = path.basename(dir);
|
|
330
323
|
if (seen.has(name) || name === "global")
|
|
331
324
|
continue;
|
|
332
|
-
if (profileProjectNames && !profileProjectNames.has(name))
|
|
333
|
-
continue;
|
|
334
325
|
seen.add(name);
|
|
335
|
-
cards.push(buildProjectCard(dir));
|
|
326
|
+
cards.push({ ...buildProjectCard(dir), store: store.name });
|
|
336
327
|
}
|
|
337
328
|
}
|
|
338
329
|
}
|
|
339
330
|
catch {
|
|
340
331
|
// store-registry not available or error loading, continue with primary only
|
|
341
332
|
}
|
|
342
|
-
|
|
333
|
+
cards.sort((a, b) => a.name.localeCompare(b.name));
|
|
334
|
+
// Prepend global as a pinned entry so it's always accessible from the shell.
|
|
335
|
+
// getProjectDirs already returns it whenever the profile names it, so drop
|
|
336
|
+
// that copy rather than listing global twice.
|
|
343
337
|
const globalDir = path.join(phrenPath, "global");
|
|
344
338
|
if (fs.existsSync(globalDir)) {
|
|
339
|
+
const listed = cards.findIndex((card) => card.name === "global");
|
|
340
|
+
if (listed >= 0)
|
|
341
|
+
cards.splice(listed, 1);
|
|
345
342
|
cards.unshift(buildProjectCard(globalDir));
|
|
346
343
|
}
|
|
347
344
|
return cards;
|
package/dist/project-config.js
CHANGED
|
@@ -2,6 +2,7 @@ import * as crypto from "crypto";
|
|
|
2
2
|
import * as fs from "fs";
|
|
3
3
|
import * as path from "path";
|
|
4
4
|
import * as yaml from "js-yaml";
|
|
5
|
+
import { loadYamlDocument } from "./phren-core.js";
|
|
5
6
|
import { readInstallPreferences } from "./init/preferences.js";
|
|
6
7
|
import { debugLog } from "./shared.js";
|
|
7
8
|
import { errorMessage } from "./utils.js";
|
|
@@ -63,7 +64,7 @@ export function readProjectConfig(phrenPath, project) {
|
|
|
63
64
|
return cached.config;
|
|
64
65
|
}
|
|
65
66
|
try {
|
|
66
|
-
const parsed =
|
|
67
|
+
const parsed = loadYamlDocument(fs.readFileSync(configPath, "utf8"), (text) => yaml.load(text, { schema: yaml.CORE_SCHEMA }));
|
|
67
68
|
const config = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
|
|
68
69
|
_projectConfigCache.set(configPath, { mtimeMs, config });
|
|
69
70
|
return config;
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { decodeStringRow } from "./index.js";
|
|
2
2
|
import * as fs from "fs";
|
|
3
|
+
import * as path from "path";
|
|
3
4
|
import { runtimeFile } from "../shared.js";
|
|
4
5
|
import { logger } from "../logger.js";
|
|
5
6
|
import { UNIVERSAL_TECH_TERMS_RE } from "../phren-core.js";
|
|
@@ -181,8 +182,12 @@ function readUserDefinedFragmentsFromDisk(claudeMdPath) {
|
|
|
181
182
|
export function beginUserFragmentBuildCache(phrenPath, projects) {
|
|
182
183
|
_activeBuildCacheKeyPrefix = `${phrenPath}/`;
|
|
183
184
|
for (const project of projects) {
|
|
185
|
+
// The cache key stays a slash-joined string — it is only ever compared
|
|
186
|
+
// against other keys built the same way. The file path is a real path, so
|
|
187
|
+
// it goes through path.join: concatenating with "/" reads fine on Windows
|
|
188
|
+
// but produces a mixed-separator string that no other code path matches.
|
|
184
189
|
const cacheKey = `${phrenPath}/${project}`;
|
|
185
|
-
const claudeMdPath =
|
|
190
|
+
const claudeMdPath = path.join(phrenPath, project, "CLAUDE.md");
|
|
186
191
|
try {
|
|
187
192
|
const loaded = readUserDefinedFragmentsFromDisk(claudeMdPath);
|
|
188
193
|
if (!loaded) {
|
|
@@ -209,7 +214,7 @@ export function endUserFragmentBuildCache(phrenPath) {
|
|
|
209
214
|
_activeBuildCacheKeyPrefix = null;
|
|
210
215
|
}
|
|
211
216
|
function parseUserDefinedFragments(phrenPath, project) {
|
|
212
|
-
const claudeMdPath =
|
|
217
|
+
const claudeMdPath = path.join(phrenPath, project, "CLAUDE.md");
|
|
213
218
|
const cacheKey = `${phrenPath}/${project}`;
|
|
214
219
|
try {
|
|
215
220
|
// Active build path: no sync I/O in per-file extraction.
|
package/dist/shared/index.js
CHANGED
|
@@ -671,7 +671,7 @@ function endTopicBuildCache() {
|
|
|
671
671
|
function readProjectTopicsForBuild(phrenPath, project) {
|
|
672
672
|
if (!_buildTopicCacheActive)
|
|
673
673
|
return readProjectTopics(phrenPath, project);
|
|
674
|
-
const key = `${phrenPath}
|
|
674
|
+
const key = `${phrenPath}\u0000${project}`;
|
|
675
675
|
const hit = _buildTopicCache.get(key);
|
|
676
676
|
if (hit)
|
|
677
677
|
return hit;
|
|
@@ -2,6 +2,23 @@ import { type RetentionPolicy } from "./governance.js";
|
|
|
2
2
|
import { type DocRow, type SqlJsDatabase } from "./index.js";
|
|
3
3
|
import type { GitContext } from "../cli/hooks-session.js";
|
|
4
4
|
export type { GitContext } from "../cli/hooks-session.js";
|
|
5
|
+
/**
|
|
6
|
+
* Per-snippet overhead charged against the token budget: the header line
|
|
7
|
+
* (`[<source key>] (<type>) fb:<score key>`) plus its blank separator.
|
|
8
|
+
*
|
|
9
|
+
* Selection and rendering MUST charge the same amount. When they drifted
|
|
10
|
+
* apart, `selectSnippets` admitted a snippet on one estimate and
|
|
11
|
+
* `buildHookOutput` re-checked it against a larger one, silently dropping a
|
|
12
|
+
* middle snippet that legitimately fit.
|
|
13
|
+
*/
|
|
14
|
+
export declare const SNIPPET_OVERHEAD_TOKENS = 24;
|
|
15
|
+
/** Query-relevance floor (see applyRelevanceFloor). A doc with no structural
|
|
16
|
+
* signal must clear this query-overlap score to be worth injecting; on the
|
|
17
|
+
* overlapScore scale (matched / max(2, min(tokens, 10))) ~0.12 means "shares at
|
|
18
|
+
* least one query token" — enough to drop priors-only noise without hurting
|
|
19
|
+
* recall. Cross-project docs face a higher bar. Tunable via
|
|
20
|
+
* PHREN_MIN_QUERY_RELEVANCE (0 disables the floor). */
|
|
21
|
+
declare const DEFAULT_MIN_QUERY_RELEVANCE = 0.12;
|
|
5
22
|
export declare function detectTaskIntent(prompt: string): "debug" | "review" | "build" | "docs" | "skill" | "general";
|
|
6
23
|
export declare function fileRelevanceBoost(filePath: string, changedFiles: Set<string>): number;
|
|
7
24
|
export declare function branchMatchBoost(content: string, branch: string | undefined): number;
|
|
@@ -98,6 +115,27 @@ export interface SelectedSnippet {
|
|
|
98
115
|
/** Mark snippet lines with stale citations (cited file missing or line content changed).
|
|
99
116
|
* @internal Exported for tests. */
|
|
100
117
|
export declare function markStaleCitations(snippet: string): string;
|
|
118
|
+
export { DEFAULT_MIN_QUERY_RELEVANCE };
|
|
119
|
+
/**
|
|
120
|
+
* Relevance floor: drop ranked docs that aren't actually relevant to *this*
|
|
121
|
+
* prompt, so the hook injects signal or nothing — never noise to fill a quota.
|
|
122
|
+
*
|
|
123
|
+
* `rankResults` intentionally scores on priors too (intent, recency, project,
|
|
124
|
+
* feedback history), so a doc can rank well with zero query overlap. That's the
|
|
125
|
+
* right call for *ordering*, but the wrong thing to *inject*. This stage keeps a
|
|
126
|
+
* doc only when it has a real connection to the prompt:
|
|
127
|
+
* - a structural signal: it's a changed file, or matches the branch name, or
|
|
128
|
+
* - it's a canonical doc for the project you're actually in, or
|
|
129
|
+
* - its text clears a query-overlap floor (higher for cross-project docs).
|
|
130
|
+
*
|
|
131
|
+
* When there's no usable query signal (no tokens) it is a no-op. Setting the
|
|
132
|
+
* floor to 0 (env PHREN_MIN_QUERY_RELEVANCE=0) disables it and restores the
|
|
133
|
+
* previous always-fill behavior.
|
|
134
|
+
*/
|
|
135
|
+
export declare function applyRelevanceFloor(rows: DocRow[], keywords: string, gitCtx: {
|
|
136
|
+
branch?: string;
|
|
137
|
+
changedFiles?: Set<string>;
|
|
138
|
+
} | null, detectedProject: string | null, floor?: number): DocRow[];
|
|
101
139
|
export declare function selectSnippets(rows: DocRow[], keywords: string, tokenBudget: number, lineBudget: number, charBudget: number): {
|
|
102
140
|
selected: SelectedSnippet[];
|
|
103
141
|
usedTokens: number;
|
package/dist/shared/retrieval.js
CHANGED
|
@@ -27,8 +27,26 @@ const WEAK_CROSS_PROJECT_OVERLAP_MAX = 0.18;
|
|
|
27
27
|
const WEAK_CROSS_PROJECT_OVERLAP_PENALTY = 0.75;
|
|
28
28
|
const LOW_FOCUS_SNIPPET_SCORE = 0.3;
|
|
29
29
|
const VERY_LOW_FOCUS_SNIPPET_SCORE = 0.14;
|
|
30
|
+
/**
|
|
31
|
+
* Per-snippet overhead charged against the token budget: the header line
|
|
32
|
+
* (`[<source key>] (<type>) fb:<score key>`) plus its blank separator.
|
|
33
|
+
*
|
|
34
|
+
* Selection and rendering MUST charge the same amount. When they drifted
|
|
35
|
+
* apart, `selectSnippets` admitted a snippet on one estimate and
|
|
36
|
+
* `buildHookOutput` re-checked it against a larger one, silently dropping a
|
|
37
|
+
* middle snippet that legitimately fit.
|
|
38
|
+
*/
|
|
39
|
+
export const SNIPPET_OVERHEAD_TOKENS = 24;
|
|
30
40
|
const LOW_FOCUS_SNIPPET_LINE_CAP = 3;
|
|
31
41
|
const LOW_FOCUS_SNIPPET_CHAR_FRACTION = 0.55;
|
|
42
|
+
/** Query-relevance floor (see applyRelevanceFloor). A doc with no structural
|
|
43
|
+
* signal must clear this query-overlap score to be worth injecting; on the
|
|
44
|
+
* overlapScore scale (matched / max(2, min(tokens, 10))) ~0.12 means "shares at
|
|
45
|
+
* least one query token" — enough to drop priors-only noise without hurting
|
|
46
|
+
* recall. Cross-project docs face a higher bar. Tunable via
|
|
47
|
+
* PHREN_MIN_QUERY_RELEVANCE (0 disables the floor). */
|
|
48
|
+
const DEFAULT_MIN_QUERY_RELEVANCE = 0.12;
|
|
49
|
+
const CROSS_PROJECT_MIN_QUERY_RELEVANCE = 0.25;
|
|
32
50
|
const TASK_RESCUE_MIN_OVERLAP = 0.3;
|
|
33
51
|
const TASK_RESCUE_OVERLAP_MARGIN = 0.12;
|
|
34
52
|
const TASK_RESCUE_SCORE_MARGIN = 0.6;
|
|
@@ -555,7 +573,10 @@ export async function searchFederatedStores(localPhrenPath, options) {
|
|
|
555
573
|
return allRows;
|
|
556
574
|
}
|
|
557
575
|
// ── Trust filter ─────────────────────────────────────────────────────────────
|
|
558
|
-
|
|
576
|
+
// "knowledge" was a doc type until the 0.0.x renames; classifyFile can no
|
|
577
|
+
// longer produce it, so listing it here was dead weight that made the set
|
|
578
|
+
// read as broader than it is.
|
|
579
|
+
const TRUST_FILTERED_TYPES = new Set(["findings", "reference"]);
|
|
559
580
|
/**
|
|
560
581
|
* Doc types that must never be pushed into an agent's prompt automatically.
|
|
561
582
|
*
|
|
@@ -841,6 +862,43 @@ export function markStaleCitations(snippet) {
|
|
|
841
862
|
}
|
|
842
863
|
return result.join("\n");
|
|
843
864
|
}
|
|
865
|
+
export { DEFAULT_MIN_QUERY_RELEVANCE };
|
|
866
|
+
/**
|
|
867
|
+
* Relevance floor: drop ranked docs that aren't actually relevant to *this*
|
|
868
|
+
* prompt, so the hook injects signal or nothing — never noise to fill a quota.
|
|
869
|
+
*
|
|
870
|
+
* `rankResults` intentionally scores on priors too (intent, recency, project,
|
|
871
|
+
* feedback history), so a doc can rank well with zero query overlap. That's the
|
|
872
|
+
* right call for *ordering*, but the wrong thing to *inject*. This stage keeps a
|
|
873
|
+
* doc only when it has a real connection to the prompt:
|
|
874
|
+
* - a structural signal: it's a changed file, or matches the branch name, or
|
|
875
|
+
* - it's a canonical doc for the project you're actually in, or
|
|
876
|
+
* - its text clears a query-overlap floor (higher for cross-project docs).
|
|
877
|
+
*
|
|
878
|
+
* When there's no usable query signal (no tokens) it is a no-op. Setting the
|
|
879
|
+
* floor to 0 (env PHREN_MIN_QUERY_RELEVANCE=0) disables it and restores the
|
|
880
|
+
* previous always-fill behavior.
|
|
881
|
+
*/
|
|
882
|
+
export function applyRelevanceFloor(rows, keywords, gitCtx, detectedProject, floor = DEFAULT_MIN_QUERY_RELEVANCE) {
|
|
883
|
+
if (!(floor > 0))
|
|
884
|
+
return rows;
|
|
885
|
+
const queryTokens = tokenizeForOverlap(keywords);
|
|
886
|
+
if (!queryTokens.length)
|
|
887
|
+
return rows; // no query signal to judge against
|
|
888
|
+
const changedFiles = gitCtx?.changedFiles ?? new Set();
|
|
889
|
+
const branch = gitCtx?.branch;
|
|
890
|
+
const crossFloor = Math.max(floor, CROSS_PROJECT_MIN_QUERY_RELEVANCE);
|
|
891
|
+
return rows.filter((doc) => {
|
|
892
|
+
if (fileRelevanceBoost(doc.path, changedFiles) > 0)
|
|
893
|
+
return true;
|
|
894
|
+
if (branchMatchBoost(doc.content, branch) > 0)
|
|
895
|
+
return true;
|
|
896
|
+
if (detectedProject && doc.project === detectedProject && doc.type === "canonical")
|
|
897
|
+
return true;
|
|
898
|
+
const isCrossProject = Boolean(detectedProject) && doc.project !== detectedProject;
|
|
899
|
+
return docOverlapScore(queryTokens, doc) >= (isCrossProject ? crossFloor : floor);
|
|
900
|
+
});
|
|
901
|
+
}
|
|
844
902
|
export function selectSnippets(rows, keywords, tokenBudget, lineBudget, charBudget) {
|
|
845
903
|
const selected = [];
|
|
846
904
|
let usedTokens = 36;
|
|
@@ -883,7 +941,7 @@ export function selectSnippets(rows, keywords, tokenBudget, lineBudget, charBudg
|
|
|
883
941
|
? overlapScore(queryTokens, `${doc.filename}\n${snippet}`)
|
|
884
942
|
: focusScore;
|
|
885
943
|
}
|
|
886
|
-
let est = approximateTokens(snippet) +
|
|
944
|
+
let est = approximateTokens(snippet) + SNIPPET_OVERHEAD_TOKENS;
|
|
887
945
|
if (selected.length > 0 && focusScore < VERY_LOW_FOCUS_SNIPPET_SCORE && usedTokens + est > Math.floor(tokenBudget * 0.8)) {
|
|
888
946
|
continue;
|
|
889
947
|
}
|
|
@@ -891,7 +949,7 @@ export function selectSnippets(rows, keywords, tokenBudget, lineBudget, charBudg
|
|
|
891
949
|
break;
|
|
892
950
|
if (selected.length === 0 && usedTokens + est > tokenBudget) {
|
|
893
951
|
snippet = compactSnippet(snippet, 3, Math.floor(charBudget * 0.55));
|
|
894
|
-
est = approximateTokens(snippet) +
|
|
952
|
+
est = approximateTokens(snippet) + SNIPPET_OVERHEAD_TOKENS;
|
|
895
953
|
}
|
|
896
954
|
const key = entryScoreKey(doc.project, doc.filename, doc.content);
|
|
897
955
|
selected.push({ doc, snippet, key });
|
|
@@ -903,7 +961,7 @@ export function selectSnippets(rows, keywords, tokenBudget, lineBudget, charBudg
|
|
|
903
961
|
// rounding / compaction producing more tokens than estimated during selection)
|
|
904
962
|
while (selected.length > 1 && usedTokens > tokenBudget) {
|
|
905
963
|
const removed = selected.pop();
|
|
906
|
-
usedTokens -= approximateTokens(removed.snippet) +
|
|
964
|
+
usedTokens -= approximateTokens(removed.snippet) + SNIPPET_OVERHEAD_TOKENS;
|
|
907
965
|
}
|
|
908
966
|
return { selected, usedTokens };
|
|
909
967
|
}
|
package/dist/shell/entry.d.ts
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
* Shell entry point: wires PhrenShell to stdin/stdout.
|
|
3
3
|
* Extracted from shell.ts to keep the orchestrator under 300 lines.
|
|
4
4
|
*/
|
|
5
|
+
import type { ShellStartup } from "./startup.js";
|
|
5
6
|
interface LiveStateHost {
|
|
6
7
|
invalidateSubsectionsCache(): void;
|
|
7
8
|
setMessage(message: string): void;
|
|
@@ -13,6 +14,14 @@ interface StartupIntroPlan {
|
|
|
13
14
|
dwellMs: number;
|
|
14
15
|
markSeen: boolean;
|
|
15
16
|
}
|
|
17
|
+
/**
|
|
18
|
+
* The intro used to attach its own stdin listener while the shell's key handler
|
|
19
|
+
* was already live, so the keypress that dismissed the splash was *also* fed to
|
|
20
|
+
* the shell (pressing "q" at the splash quit phren outright) and the intro's
|
|
21
|
+
* animation frames raced the first dashboard repaint. Key delivery is now owned
|
|
22
|
+
* by startShell, which hands the intro a one-shot waiter that consumes the key.
|
|
23
|
+
*/
|
|
24
|
+
export type { KeypressWaiter } from "./intro.js";
|
|
16
25
|
export declare function resolveStartupIntroPlan(phrenPath: string, version?: string): StartupIntroPlan;
|
|
17
26
|
export declare function startLiveStatePoller({ phrenPath, shell, repaint, isExiting, intervalMs, computeToken, }: {
|
|
18
27
|
phrenPath: string;
|
|
@@ -22,5 +31,4 @@ export declare function startLiveStatePoller({ phrenPath, shell, repaint, isExit
|
|
|
22
31
|
intervalMs?: number;
|
|
23
32
|
computeToken?: (phrenPath: string) => string;
|
|
24
33
|
}): () => void;
|
|
25
|
-
export declare function startShell(phrenPath: string, profile: string): Promise<void>;
|
|
26
|
-
export {};
|
|
34
|
+
export declare function startShell(phrenPath: string, profile: string, startup?: ShellStartup): Promise<void>;
|