@phren/cli 0.1.44 → 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.
Files changed (74) hide show
  1. package/dist/cli/actions.d.ts +1 -1
  2. package/dist/cli/actions.js +7 -2
  3. package/dist/cli/config-proactivity.d.ts +6 -6
  4. package/dist/cli/hooks.d.ts +1 -1
  5. package/dist/cli/hooks.js +14 -3
  6. package/dist/cli/session-stop.d.ts +1 -1
  7. package/dist/cli/session-tool-hook.d.ts +1 -1
  8. package/dist/cli-registry.js +1 -1
  9. package/dist/data/access.js +2 -1
  10. package/dist/generated/memory-ui-graph.browser.js +481 -318
  11. package/dist/governance/locks.js +6 -0
  12. package/dist/graph-core/index.d.ts +2 -0
  13. package/dist/graph-core/index.js +2 -0
  14. package/dist/graph-core/model.d.ts +84 -0
  15. package/dist/graph-core/model.js +355 -0
  16. package/dist/graph-core/types.d.ts +110 -0
  17. package/dist/graph-core/types.js +43 -0
  18. package/dist/index.js +4 -1
  19. package/dist/init/init-uninstall.d.ts +1 -0
  20. package/dist/init/init-uninstall.js +1 -1
  21. package/dist/init/setup.js +11 -4
  22. package/dist/link/context.js +2 -1
  23. package/dist/link/link.js +3 -2
  24. package/dist/link/skills.js +2 -1
  25. package/dist/memory-ui-graph.runtime.js +481 -318
  26. package/dist/phren-core.d.ts +16 -0
  27. package/dist/phren-core.js +21 -0
  28. package/dist/phren-paths.js +8 -4
  29. package/dist/profile-store.js +3 -2
  30. package/dist/project-config.js +2 -1
  31. package/dist/shared/index.js +1 -1
  32. package/dist/shared/retrieval.d.ts +28 -0
  33. package/dist/shared/retrieval.js +45 -0
  34. package/dist/shell/entry.d.ts +3 -3
  35. package/dist/shell/entry.js +19 -44
  36. package/dist/shell/graph/canvas.d.ts +64 -0
  37. package/dist/shell/graph/canvas.js +256 -0
  38. package/dist/shell/graph/controller.d.ts +164 -0
  39. package/dist/shell/graph/controller.js +645 -0
  40. package/dist/shell/graph/glyphs.d.ts +12 -0
  41. package/dist/shell/graph/glyphs.js +31 -0
  42. package/dist/shell/graph/graph-view.d.ts +12 -0
  43. package/dist/shell/graph/graph-view.js +408 -0
  44. package/dist/shell/graph/layout.d.ts +68 -0
  45. package/dist/shell/graph/layout.js +267 -0
  46. package/dist/shell/input.d.ts +3 -0
  47. package/dist/shell/input.js +24 -4
  48. package/dist/shell/intro.d.ts +37 -0
  49. package/dist/shell/intro.js +82 -0
  50. package/dist/shell/logo-fx.d.ts +35 -0
  51. package/dist/shell/logo-fx.js +128 -0
  52. package/dist/shell/render.d.ts +2 -2
  53. package/dist/shell/render.js +12 -28
  54. package/dist/shell/shell.d.ts +13 -1
  55. package/dist/shell/shell.js +45 -7
  56. package/dist/shell/startup.d.ts +37 -0
  57. package/dist/shell/startup.js +105 -0
  58. package/dist/shell/state-store.d.ts +1 -1
  59. package/dist/shell/state-store.js +1 -1
  60. package/dist/shell/types.js +1 -0
  61. package/dist/shell/view.d.ts +3 -0
  62. package/dist/shell/view.js +24 -3
  63. package/dist/store-registry.js +3 -3
  64. package/dist/test-global-setup.d.ts +1 -0
  65. package/dist/test-global-setup.js +22 -0
  66. package/dist/tool-registry.js +1 -0
  67. package/dist/ui/data.d.ts +15 -7
  68. package/dist/ui/data.js +102 -3
  69. package/dist/utils-fts.js +2 -1
  70. package/dist/utils-helpers.d.ts +1 -0
  71. package/dist/utils-helpers.js +6 -0
  72. package/dist/utils.d.ts +1 -1
  73. package/dist/utils.js +1 -1
  74. package/package.json +11 -7
@@ -190,16 +190,8 @@ export function wrapSegments(segments, cols, opts = {}) {
190
190
  return lines.slice(0, maxLines).join("\n");
191
191
  }
192
192
  // ── Phren theme ────────────────────────────────────────────────────────────
193
- // Neural gradient palette: purple → blue → cyan (256-color ANSI)
194
- const PHREN_GRADIENT = [
195
- "\x1b[38;5;93m", // vivid purple
196
- "\x1b[38;5;99m", // purple-blue
197
- "\x1b[38;5;105m", // blue-purple
198
- "\x1b[38;5;111m", // sky blue
199
- "\x1b[38;5;75m", // dodger blue
200
- "\x1b[38;5;81m", // cyan-blue
201
- "\x1b[38;5;87m", // bright cyan
202
- ];
193
+ // The wordmark and its gradient live with the splash text effects.
194
+ import { PHREN_GRADIENT, PHREN_LOGO } from "./logo-fx.js";
203
195
  // Apply gradient coloring across non-whitespace characters
204
196
  export function gradient(text, colors = PHREN_GRADIENT) {
205
197
  const plain = stripAnsi(text);
@@ -221,15 +213,6 @@ export function gradient(text, colors = PHREN_GRADIENT) {
221
213
  }
222
214
  return result + RESET;
223
215
  }
224
- // Block-letter logo for startup animation
225
- const PHREN_LOGO = [
226
- "██████╗ ██╗ ██╗██████╗ ███████╗███╗ ██╗",
227
- "██╔══██╗██║ ██║██╔══██╗██╔════╝████╗ ██║",
228
- "██████╔╝███████║██████╔╝█████╗ ██╔██╗ ██║",
229
- "██╔═══╝ ██╔══██║██╔══██╗██╔══╝ ██║╚██╗██║",
230
- "██║ ██║ ██║██║ ██║███████╗██║ ╚████║",
231
- "╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═══╝",
232
- ];
233
216
  import { PHREN_ART as PHREN_STARTUP_ART } from "../phren-art.js";
234
217
  // ── Line-based viewport: edge-triggered scroll (stable, no jumpiness) ─────────
235
218
  export function lineViewport(allLines, cursorFirstLine, cursorLastLine, height, prevStart) {
@@ -356,8 +339,8 @@ const LOGO_WIDTH = Math.max(...PHREN_LOGO.map(displayWidth));
356
339
  * The wordmark line, split onto two rows when the terminal is too narrow to
357
340
  * carry the tagline alongside the version badge.
358
341
  */
359
- function startupInfoLines(version, available) {
360
- const tagline = style.dim("local memory for working agents");
342
+ function startupInfoLines(version, available, taglineText = "local memory for working agents") {
343
+ const tagline = style.dim(taglineText);
361
344
  const head = `${gradient("◆")} ${style.bold("phren")} ${badge(`v${version}`, style.boldBlue)}`;
362
345
  const single = `${head} ${tagline}`;
363
346
  return displayWidth(single) <= available ? [single] : [head, tagline];
@@ -374,17 +357,18 @@ function startupInfoLines(version, available) {
374
357
  * scrolls every later cursor-home repaint lands on shifted rows, stacking the
375
358
  * frames on top of each other.
376
359
  */
377
- export function composeStartupFrame(artLines, version, hint) {
360
+ export function composeStartupFrame(artLines, version, hint, logo, tagline) {
378
361
  const cols = renderWidth();
379
362
  const rows = process.stdout.rows || 24;
380
- const logoLines = PHREN_LOGO.map(line => gradient(line));
363
+ // A text-effect frame of the wordmark may be supplied; otherwise the plain gradient.
364
+ const logoLines = logo ?? PHREN_LOGO.map(line => gradient(line));
381
365
  const hintLines = hint ? ["", ` ${hint}`] : [];
382
366
  // One blank line above, one below, plus the hint block.
383
367
  const budget = rows - 2 - hintLines.length;
384
- const stackedInfo = startupInfoLines(version, cols - 2).map(line => ` ${line}`);
368
+ const stackedInfo = startupInfoLines(version, cols - 2, tagline).map(line => ` ${line}`);
385
369
  const sideBySide = () => {
386
370
  // Logo is 6 lines; the leading blanks centre it against the character.
387
- const rightSide = ["", "", ...logoLines, "", ...startupInfoLines(version, cols - ART_WIDTH - ART_GAP)];
371
+ const rightSide = ["", "", ...logoLines, "", ...startupInfoLines(version, cols - ART_WIDTH - ART_GAP, tagline)];
388
372
  const lines = [];
389
373
  for (let i = 0; i < Math.max(artLines.length, rightSide.length); i++) {
390
374
  // padToWidth measures display cells; String.padEnd counts the art's ANSI
@@ -419,15 +403,15 @@ export function fitFrame(lines) {
419
403
  .map(line => truncateLine(line, cols) + "\x1b[K")
420
404
  .join("\n");
421
405
  }
422
- export function shellStartupFrames(version) {
406
+ export function shellStartupFrames(version, tagline) {
423
407
  const cols = process.stdout.columns || 80;
424
408
  if (cols >= 44) {
425
- return [fitFrame(composeStartupFrame(PHREN_STARTUP_ART, version))];
409
+ return [fitFrame(composeStartupFrame(PHREN_STARTUP_ART, version, undefined, undefined, tagline))];
426
410
  }
427
411
  // Narrow terminal: progressive text reveal with gradient
428
412
  const stages = ["p", "phr", "phren"];
429
413
  const spinners = ["◜", "◠", "◝"];
430
- const infoLines = startupInfoLines(version, renderWidth() - 2).map(line => ` ${line}`);
414
+ const infoLines = startupInfoLines(version, renderWidth() - 2, tagline).map(line => ` ${line}`);
431
415
  return stages.map((stage, i) => fitFrame([
432
416
  "",
433
417
  ` ${gradient(stage)} ${style.dim(spinners[i])}`,
@@ -1,5 +1,7 @@
1
1
  import { type ShellView, type ShellDeps, type DoctorResultLike } from "./types.js";
2
2
  export type { ShellView, ShellDeps } from "./types.js";
3
+ import type { ShellStartup } from "./startup.js";
4
+ import { GraphController } from "./graph/controller.js";
3
5
  export declare class PhrenShell {
4
6
  readonly phrenPath: string;
5
7
  readonly profile: string;
@@ -22,12 +24,21 @@ export declare class PhrenShell {
22
24
  private viewScrollMap;
23
25
  private healthLineCount;
24
26
  private _subsectionsCache;
27
+ private _graph?;
28
+ private repaintHandler;
25
29
  get mode(): "navigate" | "input";
26
30
  get inputBuffer(): string;
27
31
  get filter(): string | undefined;
28
- constructor(phrenPath: string, profile: string, deps?: ShellDeps);
32
+ constructor(phrenPath: string, profile: string, deps?: ShellDeps, startup?: ShellStartup);
29
33
  close(): void;
30
34
  setMessage(msg: string): void;
35
+ /**
36
+ * Let the host (entry.ts) hand over a way to repaint on the shell's own
37
+ * initiative — the graph view uses it to animate its layout settling and
38
+ * to show a build that finished while nothing was typed.
39
+ */
40
+ setRepaintHandler(handler: (() => void) | null): void;
41
+ graph(): GraphController;
31
42
  confirmThen(label: string, action: () => void): void;
32
43
  setView(view: ShellView): void;
33
44
  setFilter(value: string): void;
@@ -59,3 +70,4 @@ export declare class PhrenShell {
59
70
  completeInput(line: string): string[];
60
71
  }
61
72
  export { startShell } from "./entry.js";
73
+ export type { ShellStartup } from "./startup.js";
@@ -9,6 +9,7 @@ import { runDoctor } from "../link/link.js";
9
9
  import { renderShell, } from "./view.js";
10
10
  import { executePalette, completeInput as completeInputFn, getListItems, handleNavigateKey, applyViewShortcut, } from "./input.js";
11
11
  import { errorMessage } from "../utils.js";
12
+ import { GraphController } from "./graph/controller.js";
12
13
  /** Remove the final character, keeping surrogate pairs and combining marks intact. */
13
14
  function dropLastCharacter(s) {
14
15
  if (!s)
@@ -39,6 +40,8 @@ export class PhrenShell {
39
40
  viewScrollMap = {};
40
41
  healthLineCount = 0;
41
42
  _subsectionsCache = null;
43
+ _graph;
44
+ repaintHandler = null;
42
45
  get mode() { return this.navMode; }
43
46
  get inputBuffer() { return this.inputBuf; }
44
47
  get filter() { return this.state.filter; }
@@ -47,23 +50,47 @@ export class PhrenShell {
47
50
  runRelink: defaultRunRelink,
48
51
  runHooks: defaultRunHooks,
49
52
  runUpdate: defaultRunUpdate,
50
- }) {
53
+ }, startup = {}) {
51
54
  this.phrenPath = phrenPath;
52
55
  this.profile = profile;
53
56
  this.deps = deps;
54
57
  this.state = loadShellState(phrenPath);
55
- this.state.view = "Projects";
56
- this.message = this.state.project
57
- ? ` Dashboard ready — active context ${style.boldCyan(this.state.project)}`
58
- : ` Dashboard ready — choose a project with ${style.boldCyan("↵")} or stay global`;
58
+ // A deep link (`phren shell --view tasks --here`) wins over the view the
59
+ // last session happened to leave behind; without one we always land home.
60
+ if (startup.project)
61
+ this.state.project = startup.project;
62
+ this.state.view = startup.view ?? "Projects";
63
+ this.message = startup.notice
64
+ ? ` ${style.yellow("⚠")} ${startup.notice}`
65
+ : this.state.project
66
+ ? ` Dashboard ready — active context ${style.boldCyan(this.state.project)}`
67
+ : ` Dashboard ready — choose a project with ${style.boldCyan("↵")} or stay global`;
59
68
  }
60
- close() { saveShellState(this.phrenPath, this.state); }
69
+ close() { this._graph?.dispose(); saveShellState(this.phrenPath, this.state); }
61
70
  setMessage(msg) { this.message = msg; }
71
+ /**
72
+ * Let the host (entry.ts) hand over a way to repaint on the shell's own
73
+ * initiative — the graph view uses it to animate its layout settling and
74
+ * to show a build that finished while nothing was typed.
75
+ */
76
+ setRepaintHandler(handler) {
77
+ this.repaintHandler = handler;
78
+ this._graph?.setRepaintHook(handler);
79
+ }
80
+ graph() {
81
+ if (!this._graph) {
82
+ this._graph = new GraphController(this.phrenPath, this.profile);
83
+ this._graph.setRepaintHook(this.repaintHandler);
84
+ }
85
+ return this._graph;
86
+ }
62
87
  confirmThen(label, action) {
63
88
  this.pendingConfirm = { label, action };
64
89
  this.setMessage(`${label} ${style.boldCyan("y")} ${style.dim("confirm")} ${style.boldCyan("n")} ${style.dim("cancel")}`);
65
90
  }
66
91
  setView(view) {
92
+ if (this.state.view === "Graph" && view !== "Graph")
93
+ this._graph?.stopAnimation();
67
94
  this.state.view = view;
68
95
  this.viewScrollMap[view] = 0;
69
96
  saveShellState(this.phrenPath, this.state);
@@ -126,7 +153,7 @@ export class PhrenShell {
126
153
  this.navMode = "navigate";
127
154
  this.inputBuf = "";
128
155
  this.inputCtx = "";
129
- if (!buf.trim() && ctx !== "command") {
156
+ if (!buf.trim() && ctx !== "command" && ctx !== "graph-search") {
130
157
  this.setMessage(" Nothing entered.");
131
158
  return;
132
159
  }
@@ -134,6 +161,15 @@ export class PhrenShell {
134
161
  case "filter":
135
162
  this.setFilter(buf);
136
163
  break;
164
+ case "graph-search": {
165
+ const graph = this.graph();
166
+ const best = graph.applySearch(buf);
167
+ if (best)
168
+ this.setMessage(` ${style.yellow(`1/${graph.search.results.length}`)} ${graph.describe(best).trimStart()}`);
169
+ else
170
+ this.setMessage(buf.trim() ? ` ${style.dim("no matches for")} ${style.yellow(buf.trim())}` : ` ${style.dim("search cleared")}`);
171
+ break;
172
+ }
137
173
  case "command":
138
174
  await this.runPalette(buf.startsWith(":") ? buf.slice(1) : buf);
139
175
  break;
@@ -236,6 +272,7 @@ export class PhrenShell {
236
272
  phrenPath: this.phrenPath, profile: this.profile, state: this.state,
237
273
  currentCursor: () => this.currentCursor(), currentScroll: () => this.currentScroll(),
238
274
  setScroll: (n) => this.setScroll(n),
275
+ graph: () => this.graph(),
239
276
  };
240
277
  return renderShell(ctx, this.navMode, this.inputCtx, this.inputBuf, this.showHelp, this.message, () => this.doctorSnapshot(), this._subsectionsCache, (n) => { this.healthLineCount = n; }, (c) => { this._subsectionsCache = c; });
241
278
  }
@@ -261,6 +298,7 @@ export class PhrenShell {
261
298
  moveCursor: (delta) => this.moveCursor(delta),
262
299
  getListItems: () => this.getListItems(),
263
300
  startInput: (ctx, initial) => this.startInput(ctx, initial),
301
+ graph: () => this.graph(),
264
302
  };
265
303
  }
266
304
  // ── Palette (delegates to shell-input.ts) ──────────────────────────────
@@ -0,0 +1,37 @@
1
+ /**
2
+ * Deep links into the shell: `phren shell --view tasks --here` opens straight
3
+ * on a project's task list instead of the Projects home screen.
4
+ *
5
+ * This exists so an outside launcher — the Herdr plugin, a tmux binding, an
6
+ * editor task — can put the user where they meant to be in one keypress.
7
+ */
8
+ import type { ShellView } from "./types.js";
9
+ export interface ShellStartup {
10
+ view?: ShellView;
11
+ project?: string;
12
+ /** Shown on the shell's message line — fullscreen mode eats anything printed before launch. */
13
+ notice?: string;
14
+ }
15
+ export interface ShellStartupArgs {
16
+ view?: string;
17
+ project?: string;
18
+ here?: boolean;
19
+ unknown?: string;
20
+ }
21
+ export declare function normalizeShellView(raw: string | undefined): ShellView | undefined;
22
+ export declare const SHELL_VIEW_ALIASES: string[];
23
+ /** Parse `--view`/`--project`/`--here`, in both `--flag value` and `--flag=value` form. */
24
+ export declare function parseShellArgs(args: string[]): ShellStartupArgs;
25
+ /**
26
+ * Turn parsed flags into the state the shell should open in. An unresolvable
27
+ * view or project is dropped rather than fatal — a deep link that misses should
28
+ * still land you in the shell, on the home screen, with everything else intact.
29
+ */
30
+ export declare function resolveShellStartup(parsed: ShellStartupArgs, opts: {
31
+ phrenPath: string;
32
+ profile?: string;
33
+ cwd?: string;
34
+ }): {
35
+ startup: ShellStartup;
36
+ warnings: string[];
37
+ };
@@ -0,0 +1,105 @@
1
+ /**
2
+ * Deep links into the shell: `phren shell --view tasks --here` opens straight
3
+ * on a project's task list instead of the Projects home screen.
4
+ *
5
+ * This exists so an outside launcher — the Herdr plugin, a tmux binding, an
6
+ * editor task — can put the user where they meant to be in one keypress.
7
+ */
8
+ import { detectProject } from "../shared/index.js";
9
+ /** Spelling of a view a person would actually type, mapped to the canonical name. */
10
+ const VIEW_ALIASES = {
11
+ projects: "Projects",
12
+ project: "Projects",
13
+ tasks: "Tasks",
14
+ task: "Tasks",
15
+ todo: "Tasks",
16
+ todos: "Tasks",
17
+ findings: "Findings",
18
+ finding: "Findings",
19
+ memory: "Findings",
20
+ review: "Review Queue",
21
+ "review queue": "Review Queue",
22
+ "review-queue": "Review Queue",
23
+ queue: "Review Queue",
24
+ skills: "Skills",
25
+ skill: "Skills",
26
+ hooks: "Hooks",
27
+ hook: "Hooks",
28
+ health: "Health",
29
+ doctor: "Health",
30
+ graph: "Graph",
31
+ map: "Graph",
32
+ network: "Graph",
33
+ machines: "Machines/Profiles",
34
+ profiles: "Machines/Profiles",
35
+ "machines/profiles": "Machines/Profiles",
36
+ };
37
+ export function normalizeShellView(raw) {
38
+ if (!raw)
39
+ return undefined;
40
+ return VIEW_ALIASES[raw.trim().toLowerCase()];
41
+ }
42
+ export const SHELL_VIEW_ALIASES = Object.keys(VIEW_ALIASES);
43
+ /** Views that render nothing useful until a project is in context. */
44
+ const PROJECT_SCOPED_VIEWS = new Set(["Tasks", "Findings", "Review Queue", "Skills"]);
45
+ /** Parse `--view`/`--project`/`--here`, in both `--flag value` and `--flag=value` form. */
46
+ export function parseShellArgs(args) {
47
+ const parsed = {};
48
+ for (let i = 0; i < args.length; i++) {
49
+ const arg = args[i];
50
+ const eq = arg.indexOf("=");
51
+ const flag = eq === -1 ? arg : arg.slice(0, eq);
52
+ const inline = eq === -1 ? undefined : arg.slice(eq + 1);
53
+ // `--view tasks` consumes the next argv entry; `--view=tasks` does not.
54
+ const take = () => (inline !== undefined ? inline : args[++i]);
55
+ switch (flag) {
56
+ case "--view":
57
+ parsed.view = take();
58
+ break;
59
+ case "--project":
60
+ parsed.project = take();
61
+ break;
62
+ case "--here":
63
+ parsed.here = true;
64
+ break;
65
+ default:
66
+ if (flag.startsWith("-") && parsed.unknown === undefined)
67
+ parsed.unknown = flag;
68
+ }
69
+ }
70
+ return parsed;
71
+ }
72
+ /**
73
+ * Turn parsed flags into the state the shell should open in. An unresolvable
74
+ * view or project is dropped rather than fatal — a deep link that misses should
75
+ * still land you in the shell, on the home screen, with everything else intact.
76
+ */
77
+ export function resolveShellStartup(parsed, opts) {
78
+ const warnings = [];
79
+ const startup = {};
80
+ if (parsed.unknown)
81
+ warnings.push(`Unknown flag ${parsed.unknown} — ignored.`);
82
+ if (parsed.view) {
83
+ const view = normalizeShellView(parsed.view);
84
+ if (view)
85
+ startup.view = view;
86
+ else
87
+ warnings.push(`Unknown view "${parsed.view}" — opening on Projects.`);
88
+ }
89
+ if (parsed.project) {
90
+ startup.project = parsed.project;
91
+ }
92
+ else if (parsed.here) {
93
+ const detected = detectProject(opts.phrenPath, opts.cwd ?? process.cwd(), opts.profile);
94
+ if (detected)
95
+ startup.project = detected;
96
+ else
97
+ warnings.push("No phren project for this directory — opening without a project.");
98
+ }
99
+ // These views render an empty "no project selected" screen without a project,
100
+ // which is a worse landing spot than the project list the user came from.
101
+ if (!startup.project && startup.view && PROJECT_SCOPED_VIEWS.has(startup.view)) {
102
+ startup.view = undefined;
103
+ }
104
+ return { startup, warnings };
105
+ }
@@ -1,7 +1,7 @@
1
1
  import { type PhrenResult } from "../shared.js";
2
2
  export interface ShellState {
3
3
  version: number;
4
- view: "Projects" | "Tasks" | "Findings" | "Review Queue" | "Skills" | "Hooks" | "Machines/Profiles" | "Health";
4
+ view: "Projects" | "Tasks" | "Findings" | "Review Queue" | "Skills" | "Hooks" | "Machines/Profiles" | "Health" | "Graph";
5
5
  project?: string;
6
6
  filter?: string;
7
7
  page?: number;
@@ -5,7 +5,7 @@ import { withSafeLock } from "../shared/data-utils.js";
5
5
  import { errorMessage } from "../utils.js";
6
6
  import { logger } from "../logger.js";
7
7
  const SHELL_STATE_VERSION = 3;
8
- const VALID_VIEWS = new Set(["Projects", "Tasks", "Findings", "Review Queue", "Skills", "Hooks", "Machines/Profiles", "Health"]);
8
+ const VALID_VIEWS = new Set(["Projects", "Tasks", "Findings", "Review Queue", "Skills", "Hooks", "Machines/Profiles", "Health", "Graph"]);
9
9
  export function loadShellState(phrenPath) {
10
10
  const file = shellStateFile(phrenPath);
11
11
  const fallback = {
@@ -9,5 +9,6 @@ export const TAB_ICONS = {
9
9
  Skills: "◆",
10
10
  Hooks: "⚡",
11
11
  Health: "♡",
12
+ Graph: "❖",
12
13
  };
13
14
  export const MAX_UNDO_STACK = 10;
@@ -4,6 +4,7 @@
4
4
  */
5
5
  import { ShellState } from "../data/access.js";
6
6
  import { type DoctorResultLike } from "./types.js";
7
+ import type { GraphController } from "./graph/controller.js";
7
8
  /** Shared rendering state passed from the orchestrator */
8
9
  export interface ViewContext {
9
10
  phrenPath: string;
@@ -12,6 +13,8 @@ export interface ViewContext {
12
13
  currentCursor: () => number;
13
14
  currentScroll: () => number;
14
15
  setScroll: (n: number) => void;
16
+ /** The knowledge-graph view's controller (created on first use). Absent in hosts that only render menus. */
17
+ graph?: () => GraphController;
15
18
  }
16
19
  export interface SubsectionsCache {
17
20
  project: string;
@@ -16,6 +16,7 @@ import { isProjectHookEnabled, readProjectConfig } from "../project-config.js";
16
16
  import { getScopedSkills } from "../skill/registry.js";
17
17
  import { errorMessage } from "../utils.js";
18
18
  import { logger } from "../logger.js";
19
+ import { renderGraphView } from "./graph/graph-view.js";
19
20
  /** Resolve which store (primary or team) contains a project */
20
21
  function resolveProjectStorePath(phrenPath, project) {
21
22
  if (fs.existsSync(path.join(phrenPath, project)))
@@ -36,6 +37,10 @@ function renderTabBar(state) {
36
37
  const label = `${TAB_ICONS.Health} Health`;
37
38
  return ` ${style.boldMagenta(label)}\n${separator(cols)}`;
38
39
  }
40
+ if (state.view === "Graph") {
41
+ const label = `${TAB_ICONS.Graph} Graph`;
42
+ return ` ${style.boldMagenta(label)}\n${separator(cols)}`;
43
+ }
39
44
  if (state.view === "Projects") {
40
45
  const label = `${TAB_ICONS.Projects} Projects`;
41
46
  const tabLine = ` ${style.boldMagenta(label)} `;
@@ -73,6 +78,7 @@ function renderBottomBar(state, navMode, inputCtx, inputBuf) {
73
78
  add: "add task",
74
79
  "learn-add": "add finding",
75
80
  "skill-add": "new skill name",
81
+ "graph-search": "search graph",
76
82
  };
77
83
  const label = labels[inputCtx] || inputCtx;
78
84
  return `${sep}\n ${style.boldCyan(label + " ›")} ${inputBuf}${style.cyan("█")}`;
@@ -85,15 +91,20 @@ function renderBottomBar(state, navMode, inputCtx, inputBuf) {
85
91
  Skills: [`${k("a")} ${d("add")}`, `${k("t")} ${d("toggle")}`, `${k("d")} ${d("remove")}`],
86
92
  Hooks: [`${k("a")} ${d("enable")}`, `${k("d")} ${d("disable")}`],
87
93
  Health: [`${k("↑↓")} ${d("scroll")}`, `${k("esc")} ${d("back")}`],
94
+ Graph: [`${k("↑↓←→")} ${d("walk")}`, `${k("↵")} ${d("select")}`, `${k("f")} ${d("filter")}`, `${k("[ ]")} ${d("project")}`, `${k("esc")} ${d("back")}`],
88
95
  };
89
96
  const extra = viewHints[state.view] ?? [];
90
- const isSubView = state.view !== "Projects" && state.view !== "Health";
97
+ const isSubView = state.view !== "Projects" && state.view !== "Health" && state.view !== "Graph";
91
98
  const nav = isSubView
92
99
  ? [`${k("←→")} ${d("tabs")}`, `${k("↑↓")} ${d("move")}`, `${k("esc")} ${d("back")}`]
93
- : state.view === "Health"
100
+ : state.view === "Health" || state.view === "Graph"
94
101
  ? []
95
102
  : [`${k("↑↓")} ${d("move")}`];
96
- const tail = [`${k("h")} ${d("health")}`, `${k("/")} ${d("filter")}`, `${k(":")} ${d("cmd")}`, `${k("?")} ${d("help")}`, `${k("q")} ${d("quit")}`];
103
+ const tail = [
104
+ state.view === "Graph" ? `${k("h")} ${d("health")}` : `${k("g")} ${d("graph")}`,
105
+ `${k("/")} ${d(state.view === "Graph" ? "search" : "filter")}`,
106
+ `${k(":")} ${d("cmd")}`, `${k("?")} ${d("help")}`, `${k("q")} ${d("quit")}`,
107
+ ];
97
108
  const hints = [...nav, ...extra, ...tail];
98
109
  return `${sep}\n${wrapSegments(hints, cols, {
99
110
  indent: " ",
@@ -709,6 +720,16 @@ export async function renderShell(ctx, navMode, inputCtx, inputBuf, showHelp, me
709
720
  setHealthLineCount(result.lineCount);
710
721
  break;
711
722
  }
723
+ case "Graph": {
724
+ if (!ctx.graph) {
725
+ contentLines = [" The graph view needs the interactive shell — run `phren shell`."];
726
+ break;
727
+ }
728
+ const controller = ctx.graph();
729
+ await controller.ensureData();
730
+ contentLines = renderGraphView(controller, renderWidth(), height);
731
+ break;
732
+ }
712
733
  default:
713
734
  contentLines = [" Unknown view."];
714
735
  }
@@ -4,7 +4,7 @@ import * as path from "path";
4
4
  import * as yaml from "js-yaml";
5
5
  import { expandHomePath, atomicWriteText } from "./phren-paths.js";
6
6
  import { withFileLock } from "./governance/locks.js";
7
- import { isRecord, PhrenError } from "./phren-core.js";
7
+ import { isRecord, loadYamlDocument, PhrenError } from "./phren-core.js";
8
8
  import { getProjectDirs } from "./shared.js";
9
9
  // ── Constants ────────────────────────────────────────────────────────────────
10
10
  export const STORES_FILENAME = "stores.yaml";
@@ -39,7 +39,7 @@ export function readStoreRegistryDetailed(phrenPath) {
39
39
  }
40
40
  let parsed;
41
41
  try {
42
- parsed = yaml.load(raw, { schema: yaml.CORE_SCHEMA });
42
+ parsed = loadYamlDocument(raw, (text) => yaml.load(text, { schema: yaml.CORE_SCHEMA }));
43
43
  }
44
44
  catch (err) {
45
45
  return { registry: null, problems: [`${STORES_FILENAME} is not valid YAML: ${String(err)}`], lossy: true };
@@ -183,7 +183,7 @@ export function readTeamBootstrap(storePath) {
183
183
  return null;
184
184
  try {
185
185
  const raw = fs.readFileSync(filePath, "utf8");
186
- const parsed = yaml.load(raw, { schema: yaml.CORE_SCHEMA });
186
+ const parsed = loadYamlDocument(raw, (text) => yaml.load(text, { schema: yaml.CORE_SCHEMA }));
187
187
  if (!isRecord(parsed) || typeof parsed.name !== "string")
188
188
  return null;
189
189
  return {
@@ -11,4 +11,5 @@
11
11
  * - Watch mode re-runs where pretest does not re-fire
12
12
  * - CI environments that skip npm lifecycle scripts
13
13
  */
14
+ export declare function teardown(): Promise<void>;
14
15
  export declare function setup(): Promise<void>;
@@ -13,13 +13,35 @@
13
13
  */
14
14
  import { execFileSync } from "child_process";
15
15
  import * as fs from "fs";
16
+ import * as os from "os";
16
17
  import * as path from "path";
17
18
  import { fileURLToPath } from "url";
18
19
  const __filename = fileURLToPath(import.meta.url);
19
20
  const __dirname = path.dirname(__filename);
20
21
  const REPO_ROOT = path.resolve(__dirname, "../../..");
21
22
  const CLI_PATH = path.join(REPO_ROOT, "packages", "cli", "dist", "index.js");
23
+ let sandboxHome = null;
24
+ /**
25
+ * Point HOME (and USERPROFILE) at a throwaway directory for the whole run.
26
+ *
27
+ * `pool: "forks"` workers inherit this process's env, and on Linux/macOS
28
+ * `os.homedir()` reads $HOME too, so this covers every route the CLI uses to
29
+ * find the user's home. Without it, isolation depends on each test
30
+ * remembering to override HOME — and the ones that forgot (e.g. the web-ui
31
+ * readiness test) re-pointed the developer's real ~/.claude/CLAUDE.md and
32
+ * ~/.claude/skills/phren-* at temp dirs that were deleted seconds later.
33
+ */
34
+ function sandboxHomeDir() {
35
+ sandboxHome = fs.mkdtempSync(path.join(os.tmpdir(), "phren-test-home-"));
36
+ process.env.HOME = sandboxHome;
37
+ process.env.USERPROFILE = sandboxHome;
38
+ }
39
+ export async function teardown() {
40
+ if (sandboxHome)
41
+ fs.rmSync(sandboxHome, { recursive: true, force: true });
42
+ }
22
43
  export async function setup() {
44
+ sandboxHomeDir();
23
45
  if (fs.existsSync(CLI_PATH)) {
24
46
  // Dist already present — skip build. This is the common path when
25
47
  // `npm test` is used (pretest already built it) or during watch mode
@@ -5,6 +5,7 @@ const CATEGORY_BY_MODULE = {
5
5
  "search": "Search and browse",
6
6
  "tasks": "Task management",
7
7
  "finding": "Finding capture",
8
+ "notes": "Notes",
8
9
  "memory": "Memory quality",
9
10
  "data": "Data management",
10
11
  "graph": "Fragments and graph",
package/dist/ui/data.d.ts CHANGED
@@ -1,13 +1,13 @@
1
1
  import type { SqlJsDatabase } from "../shared/index.js";
2
2
  import { type LookupEvent } from "../governance/activity.js";
3
- interface EntryScore {
3
+ export interface EntryScore {
4
4
  impressions: number;
5
5
  helpful: number;
6
6
  repromptPenalty: number;
7
7
  regressionPenalty: number;
8
8
  lastUsedAt: string;
9
9
  }
10
- interface GraphNode {
10
+ export interface GraphNode {
11
11
  id: string;
12
12
  label: string;
13
13
  fullLabel: string;
@@ -30,18 +30,26 @@ interface GraphNode {
30
30
  findingCount?: number;
31
31
  taskCount?: number;
32
32
  }
33
- interface GraphDocRef {
33
+ export interface GraphDocRef {
34
34
  doc: string;
35
35
  project: string;
36
36
  scoreKey?: string;
37
37
  }
38
- interface GraphTopicMeta {
38
+ export interface GraphTopicMeta {
39
39
  slug: string;
40
40
  label: string;
41
41
  }
42
- interface GraphLink {
42
+ export interface GraphLink {
43
43
  source: string;
44
44
  target: string;
45
+ /** Absent for the default project→leaf spoke; set for the opt-in enrichment edges. */
46
+ kind?: "fragment" | "supersedes" | "contradicts";
47
+ }
48
+ export interface BuildGraphOptions {
49
+ /** Fragment↔fragment edges for fragments co-mentioned in the same documents. */
50
+ includeFragmentEdges?: boolean;
51
+ /** Finding→finding edges from `supersedes` / `contradicts` lifecycle annotations. */
52
+ includeLifecycleEdges?: boolean;
45
53
  }
46
54
  interface ProjectInfo {
47
55
  name: string;
@@ -92,7 +100,7 @@ export declare function collectSkillsForUI(phrenPath: string, profile?: string):
92
100
  export declare function getHooksData(phrenPath: string, profile?: string): {
93
101
  globalEnabled: boolean;
94
102
  tools: {
95
- tool: "claude" | "copilot" | "cursor" | "codex";
103
+ tool: "claude" | "codex" | "copilot" | "cursor";
96
104
  enabled: boolean;
97
105
  configPath: string;
98
106
  exists: boolean;
@@ -108,7 +116,7 @@ export declare function getHooksData(phrenPath: string, profile?: string): {
108
116
  }>;
109
117
  }[];
110
118
  };
111
- export declare function buildGraph(phrenPath: string, profile?: string, focusProject?: string, existingDb?: SqlJsDatabase | null): Promise<{
119
+ export declare function buildGraph(phrenPath: string, profile?: string, focusProject?: string, existingDb?: SqlJsDatabase | null, opts?: BuildGraphOptions): Promise<{
112
120
  nodes: GraphNode[];
113
121
  links: GraphLink[];
114
122
  total: number;