@phren/cli 0.1.45 → 0.1.46

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 (38) hide show
  1. package/dist/agents/providers/herdr.d.ts +18 -0
  2. package/dist/agents/providers/herdr.js +94 -0
  3. package/dist/agents/providers/spawner.d.ts +13 -0
  4. package/dist/agents/providers/spawner.js +63 -0
  5. package/dist/agents/registry.d.ts +28 -0
  6. package/dist/agents/registry.js +82 -0
  7. package/dist/agents/types.d.ts +51 -0
  8. package/dist/agents/types.js +42 -0
  9. package/dist/cli/search.js +29 -0
  10. package/dist/cli-registry.d.ts +1 -1
  11. package/dist/cli-registry.js +1 -0
  12. package/dist/content/learning.js +24 -1
  13. package/dist/generated/memory-ui-graph.browser.js +69 -69
  14. package/dist/graph-core/model.js +99 -9
  15. package/dist/memory-ui-graph.runtime.js +69 -69
  16. package/dist/phren-art.d.ts +7 -0
  17. package/dist/phren-art.js +6 -41
  18. package/dist/shared/lookup-tail.d.ts +35 -0
  19. package/dist/shared/lookup-tail.js +100 -0
  20. package/dist/shell/graph/agents.d.ts +48 -0
  21. package/dist/shell/graph/agents.js +152 -0
  22. package/dist/shell/graph/controller.d.ts +40 -2
  23. package/dist/shell/graph/controller.js +149 -12
  24. package/dist/shell/graph/graph-view.d.ts +7 -0
  25. package/dist/shell/graph/graph-view.js +227 -50
  26. package/dist/shell/graph/layout.d.ts +21 -2
  27. package/dist/shell/graph/layout.js +79 -11
  28. package/dist/shell/graph/watch.d.ts +71 -0
  29. package/dist/shell/graph/watch.js +153 -0
  30. package/dist/shell/input.js +3 -1
  31. package/dist/shell/render.js +3 -0
  32. package/dist/shell/shell.d.ts +2 -0
  33. package/dist/shell/shell.js +9 -4
  34. package/dist/shell/startup.d.ts +3 -0
  35. package/dist/shell/startup.js +8 -0
  36. package/dist/shell/view.js +61 -73
  37. package/dist/ui/server.js +6 -56
  38. package/package.json +1 -1
@@ -11,6 +11,13 @@
11
11
  */
12
12
  export declare const PHREN_ART: string[];
13
13
  export declare const PHREN_ART_RIGHT: string[];
14
+ /**
15
+ * The mascot holds still: it sits at a fixed position beside the wordmark and
16
+ * only its eyes and the sparkle above its head change. Whole-body motion (the
17
+ * vertical bob and the sideways lean) shifted the art by a full cell, which
18
+ * reads as blocky jitter at terminal resolution, so it is gone. Every frame has
19
+ * the same line count and the same display width as `PHREN_ART`.
20
+ */
14
21
  export interface PhrenAnimator {
15
22
  getFrame(): string[];
16
23
  start(): void;
package/dist/phren-art.js CHANGED
@@ -83,36 +83,19 @@ function applySparkleToLine(line, frame, active) {
83
83
  }
84
84
  return line.replace(/(\x1b\[38;2;\d+;2\d\d;2\d\dm)[\u2580\u2584](\x1b\[0m)/g, `$1${sparkleChar}$2`);
85
85
  }
86
- function applyLean(line, offset) {
87
- if (offset === 0)
88
- return line;
89
- if (offset > 0) {
90
- return " ".repeat(offset) + line;
91
- }
92
- const trimCount = Math.min(-offset, line.match(/^( *)/)[1].length);
93
- return line.slice(trimCount);
94
- }
95
86
  export function createPhrenAnimator(options) {
96
87
  const facing = options?.facing ?? "left";
97
88
  const baseArt = facing === "right" ? PHREN_ART_RIGHT : PHREN_ART;
98
89
  const state = {
99
- bobUp: false,
100
90
  isBlinking: false,
101
91
  sparkleFrame: 0,
102
92
  sparkleActive: false,
103
- leanOffset: 0,
104
93
  };
105
94
  const timers = [];
106
95
  function scheduleTimer(fn, ms) {
107
96
  const t = setTimeout(fn, ms);
108
97
  timers.push(t);
109
98
  }
110
- function scheduleBob() {
111
- scheduleTimer(() => {
112
- state.bobUp = !state.bobUp;
113
- scheduleBob();
114
- }, 500);
115
- }
116
99
  function scheduleBlink() {
117
100
  const interval = randInt(2000, 8000);
118
101
  scheduleTimer(() => {
@@ -153,41 +136,23 @@ export function createPhrenAnimator(options) {
153
136
  sparkleStep(step + 1);
154
137
  }, 200);
155
138
  }
156
- function scheduleLean() {
157
- const interval = randInt(4000, 10000);
158
- scheduleTimer(() => {
159
- const direction = Math.random() < 0.5 ? -1 : 1;
160
- state.leanOffset = direction;
161
- const holdTime = randInt(1000, 2000);
162
- scheduleTimer(() => {
163
- state.leanOffset = 0;
164
- scheduleLean();
165
- }, holdTime);
166
- }, interval);
167
- }
168
139
  return {
169
140
  getFrame() {
170
- let lines = baseArt.map((line, i) => {
171
- let result = line;
141
+ // In-place substitutions only: the art grid is never shifted or padded,
142
+ // so the frame keeps its line count and its width.
143
+ return baseArt.map((line, i) => {
172
144
  if (state.isBlinking && i === EYE_ROW) {
173
- result = applyBlinkToLine(result);
145
+ return applyBlinkToLine(line);
174
146
  }
175
147
  if (i === SPARKLE_ROW) {
176
- result = applySparkleToLine(result, state.sparkleFrame, state.sparkleActive);
148
+ return applySparkleToLine(line, state.sparkleFrame, state.sparkleActive);
177
149
  }
178
- result = applyLean(result, state.leanOffset);
179
- return result;
150
+ return line;
180
151
  });
181
- if (state.bobUp) {
182
- lines = ["", ...lines.slice(0, -1)];
183
- }
184
- return lines;
185
152
  },
186
153
  start() {
187
- scheduleBob();
188
154
  scheduleBlink();
189
155
  scheduleSparkle();
190
- scheduleLean();
191
156
  },
192
157
  stop() {
193
158
  for (const t of timers) {
@@ -0,0 +1,35 @@
1
+ /**
2
+ * Tail the live lookup-events log.
3
+ *
4
+ * `.runtime/lookup-events.jsonl` is append-only: every memory phren lands on
5
+ * during a search, and every memory a hook injects, is written as one JSON
6
+ * line. Two hosts follow it live — the web UI's Activity stream and the
7
+ * shell's graph watch mode — so the read-only tailing logic lives here once.
8
+ *
9
+ * Reads only the bytes appended since the last poll, which is far more robust
10
+ * across platforms than fs.watch, and survives the file being rotated or
11
+ * truncated underneath it.
12
+ */
13
+ import type { LookupEvent } from "../governance/activity.js";
14
+ export interface LookupTailOptions {
15
+ /**
16
+ * Start at the current end of the file so only events appended after
17
+ * construction are delivered. Callers wanting history use
18
+ * `readRecentLookups` for the backfill. Default true.
19
+ */
20
+ fromEnd?: boolean;
21
+ }
22
+ export declare class LookupTail {
23
+ private readonly logPath;
24
+ private offset;
25
+ private carry;
26
+ constructor(logPath: string, opts?: LookupTailOptions);
27
+ /**
28
+ * Raw JSON lines appended since the last poll, each already validated as
29
+ * parseable. Never throws: a logging or read failure yields nothing rather
30
+ * than breaking the caller's render or stream.
31
+ */
32
+ pollLines(): string[];
33
+ /** Parsed events appended since the last poll. */
34
+ poll(): LookupEvent[];
35
+ }
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Tail the live lookup-events log.
3
+ *
4
+ * `.runtime/lookup-events.jsonl` is append-only: every memory phren lands on
5
+ * during a search, and every memory a hook injects, is written as one JSON
6
+ * line. Two hosts follow it live — the web UI's Activity stream and the
7
+ * shell's graph watch mode — so the read-only tailing logic lives here once.
8
+ *
9
+ * Reads only the bytes appended since the last poll, which is far more robust
10
+ * across platforms than fs.watch, and survives the file being rotated or
11
+ * truncated underneath it.
12
+ */
13
+ import * as fs from "fs";
14
+ export class LookupTail {
15
+ logPath;
16
+ offset = 0;
17
+ carry = "";
18
+ constructor(logPath, opts = {}) {
19
+ this.logPath = logPath;
20
+ if (opts.fromEnd !== false) {
21
+ try {
22
+ this.offset = fs.existsSync(logPath) ? fs.statSync(logPath).size : 0;
23
+ }
24
+ catch {
25
+ this.offset = 0;
26
+ }
27
+ }
28
+ }
29
+ /**
30
+ * Raw JSON lines appended since the last poll, each already validated as
31
+ * parseable. Never throws: a logging or read failure yields nothing rather
32
+ * than breaking the caller's render or stream.
33
+ */
34
+ pollLines() {
35
+ let size;
36
+ try {
37
+ if (!fs.existsSync(this.logPath))
38
+ return [];
39
+ size = fs.statSync(this.logPath).size;
40
+ }
41
+ catch {
42
+ return [];
43
+ }
44
+ if (size < this.offset) {
45
+ // Rotated or truncated: start over rather than read garbage.
46
+ this.offset = 0;
47
+ this.carry = "";
48
+ }
49
+ if (size <= this.offset)
50
+ return [];
51
+ let chunk = "";
52
+ try {
53
+ const fd = fs.openSync(this.logPath, "r");
54
+ try {
55
+ const buf = Buffer.alloc(size - this.offset);
56
+ fs.readSync(fd, buf, 0, buf.length, this.offset);
57
+ chunk = buf.toString("utf8");
58
+ }
59
+ finally {
60
+ fs.closeSync(fd);
61
+ }
62
+ }
63
+ catch {
64
+ return [];
65
+ }
66
+ this.offset = size;
67
+ const lines = (this.carry + chunk).split("\n");
68
+ // A trailing partial line is kept until the writer finishes it.
69
+ this.carry = lines.pop() ?? "";
70
+ const out = [];
71
+ for (const line of lines) {
72
+ const trimmed = line.trim();
73
+ if (!trimmed)
74
+ continue;
75
+ try {
76
+ JSON.parse(trimmed);
77
+ out.push(trimmed);
78
+ }
79
+ catch {
80
+ // Skip malformed lines rather than failing the whole poll.
81
+ }
82
+ }
83
+ return out;
84
+ }
85
+ /** Parsed events appended since the last poll. */
86
+ poll() {
87
+ const out = [];
88
+ for (const line of this.pollLines()) {
89
+ try {
90
+ const parsed = JSON.parse(line);
91
+ if (parsed && typeof parsed.at === "string")
92
+ out.push(parsed);
93
+ }
94
+ catch {
95
+ // Already validated in pollLines; defensive only.
96
+ }
97
+ }
98
+ return out;
99
+ }
100
+ }
@@ -0,0 +1,48 @@
1
+ /**
2
+ * Live coding agents on the knowledge graph.
3
+ *
4
+ * Watch mode shows what phren's memory is doing; this shows who is doing it.
5
+ * Agents are transient runtime state rather than memory, so they decorate the
6
+ * project nodes they are working in instead of becoming graph nodes of their
7
+ * own — the same shape `GraphWatch` uses, and it keeps `graph-core` (which is
8
+ * bundled for the browser) untouched.
9
+ */
10
+ import type { JoinedAgent } from "../../agents/types.js";
11
+ export interface GraphAgentsOptions {
12
+ pollMs?: number;
13
+ /** Injected in tests so nothing shells out and no timer runs. */
14
+ collect?: () => JoinedAgent[];
15
+ runFocus?: (argv: string[]) => boolean;
16
+ enabled?: boolean;
17
+ }
18
+ /** Run a provider-supplied focus command. Never throws. */
19
+ export declare function runFocusCommand(argv: string[]): boolean;
20
+ export declare class GraphAgents {
21
+ readonly phrenPath: string;
22
+ readonly profile: string;
23
+ agents: JoinedAgent[];
24
+ /** Index into `agents`; -1 when nothing is highlighted. */
25
+ highlighted: number;
26
+ enabled: boolean;
27
+ private timer;
28
+ private onUpdate;
29
+ private readonly pollMs;
30
+ private readonly collectFn;
31
+ private readonly runFocus;
32
+ constructor(phrenPath: string, profile: string, opts?: GraphAgentsOptions);
33
+ get running(): boolean;
34
+ private polledOnce;
35
+ start(onUpdate: () => void): void;
36
+ stop(): void;
37
+ toggle(): boolean;
38
+ /** Refresh the list. Never throws; a failing provider just yields nothing. */
39
+ poll(): JoinedAgent[];
40
+ /** Agents grouped by the project they are working in. */
41
+ byProject(): Map<string, JoinedAgent[]>;
42
+ get current(): JoinedAgent | null;
43
+ /** Move the highlight; wraps, and starts from the first agent. */
44
+ cycle(delta: number): JoinedAgent | null;
45
+ clearHighlight(): void;
46
+ /** Bring the highlighted agent to the front in whatever is hosting it. */
47
+ focusCurrent(): JoinedAgent | null;
48
+ }
@@ -0,0 +1,152 @@
1
+ /**
2
+ * Live coding agents on the knowledge graph.
3
+ *
4
+ * Watch mode shows what phren's memory is doing; this shows who is doing it.
5
+ * Agents are transient runtime state rather than memory, so they decorate the
6
+ * project nodes they are working in instead of becoming graph nodes of their
7
+ * own — the same shape `GraphWatch` uses, and it keeps `graph-core` (which is
8
+ * bundled for the browser) untouched.
9
+ */
10
+ import { execFileSync } from "child_process";
11
+ import { commandExists } from "../../hooks.js";
12
+ import { detectProject } from "../../shared/index.js";
13
+ import { debugLog } from "../../shared.js";
14
+ import { errorMessage } from "../../utils.js";
15
+ import { agentsEnabled, collectAgents, joinAgents, sortAgents } from "../../agents/registry.js";
16
+ import { createHerdrProvider } from "../../agents/providers/herdr.js";
17
+ import { createSpawnerProvider } from "../../agents/providers/spawner.js";
18
+ const DEFAULT_POLL_MS = 2000;
19
+ const FOCUS_TIMEOUT_MS = 5000;
20
+ /** Run a provider-supplied focus command. Never throws. */
21
+ export function runFocusCommand(argv) {
22
+ if (!argv.length)
23
+ return false;
24
+ const [command, ...args] = argv;
25
+ try {
26
+ execFileSync(command, args, { stdio: ["ignore", "ignore", "ignore"], timeout: FOCUS_TIMEOUT_MS });
27
+ return true;
28
+ }
29
+ catch (err) {
30
+ debugLog(`agent focus: ${errorMessage(err)}`);
31
+ return false;
32
+ }
33
+ }
34
+ export class GraphAgents {
35
+ phrenPath;
36
+ profile;
37
+ agents = [];
38
+ /** Index into `agents`; -1 when nothing is highlighted. */
39
+ highlighted = -1;
40
+ enabled;
41
+ timer = null;
42
+ onUpdate = null;
43
+ pollMs;
44
+ collectFn;
45
+ runFocus;
46
+ constructor(phrenPath, profile, opts = {}) {
47
+ this.phrenPath = phrenPath;
48
+ this.profile = profile;
49
+ this.pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
50
+ this.runFocus = opts.runFocus ?? runFocusCommand;
51
+ this.enabled = opts.enabled ?? agentsEnabled();
52
+ this.collectFn = opts.collect ?? (() => {
53
+ const providers = [createHerdrProvider(commandExists), createSpawnerProvider(phrenPath)];
54
+ return joinAgents(collectAgents(providers), (cwd) => detectProject(phrenPath, cwd, profile));
55
+ });
56
+ }
57
+ get running() {
58
+ return this.timer !== null || this.polledOnce;
59
+ }
60
+ polledOnce = false;
61
+ start(onUpdate) {
62
+ if (!this.enabled || this.timer)
63
+ return;
64
+ this.onUpdate = onUpdate;
65
+ this.poll();
66
+ this.timer = setInterval(() => {
67
+ const before = signature(this.agents);
68
+ this.poll();
69
+ if (signature(this.agents) !== before)
70
+ this.onUpdate?.();
71
+ }, this.pollMs);
72
+ this.timer.unref?.();
73
+ }
74
+ stop() {
75
+ if (this.timer) {
76
+ clearInterval(this.timer);
77
+ this.timer = null;
78
+ }
79
+ this.onUpdate = null;
80
+ this.polledOnce = false;
81
+ this.agents = [];
82
+ this.highlighted = -1;
83
+ }
84
+ toggle() {
85
+ this.enabled = !this.enabled;
86
+ if (!this.enabled) {
87
+ this.stop();
88
+ this.enabled = false;
89
+ }
90
+ return this.enabled;
91
+ }
92
+ /** Refresh the list. Never throws; a failing provider just yields nothing. */
93
+ poll() {
94
+ let next = [];
95
+ try {
96
+ next = sortAgents(this.collectFn());
97
+ }
98
+ catch (err) {
99
+ debugLog(`graph agents poll: ${errorMessage(err)}`);
100
+ next = [];
101
+ }
102
+ const previousId = this.highlighted >= 0 ? this.agents[this.highlighted]?.id : undefined;
103
+ this.agents = next;
104
+ this.polledOnce = true;
105
+ // Keep the highlight on the same agent across a refresh where possible.
106
+ this.highlighted = previousId ? next.findIndex((a) => a.id === previousId) : -1;
107
+ return next;
108
+ }
109
+ /** Agents grouped by the project they are working in. */
110
+ byProject() {
111
+ const map = new Map();
112
+ for (const agent of this.agents) {
113
+ if (!agent.project)
114
+ continue;
115
+ const list = map.get(agent.project);
116
+ if (list)
117
+ list.push(agent);
118
+ else
119
+ map.set(agent.project, [agent]);
120
+ }
121
+ return map;
122
+ }
123
+ get current() {
124
+ return this.highlighted >= 0 ? this.agents[this.highlighted] ?? null : null;
125
+ }
126
+ /** Move the highlight; wraps, and starts from the first agent. */
127
+ cycle(delta) {
128
+ if (!this.agents.length) {
129
+ this.highlighted = -1;
130
+ return null;
131
+ }
132
+ const next = this.highlighted < 0
133
+ ? (delta >= 0 ? 0 : this.agents.length - 1)
134
+ : (this.highlighted + delta + this.agents.length) % this.agents.length;
135
+ this.highlighted = next;
136
+ return this.agents[next] ?? null;
137
+ }
138
+ clearHighlight() {
139
+ this.highlighted = -1;
140
+ }
141
+ /** Bring the highlighted agent to the front in whatever is hosting it. */
142
+ focusCurrent() {
143
+ const agent = this.current;
144
+ if (!agent?.focus?.length)
145
+ return null;
146
+ return this.runFocus(agent.focus) ? agent : null;
147
+ }
148
+ }
149
+ /** Cheap change detector, so a poll that found nothing new costs no repaint. */
150
+ function signature(agents) {
151
+ return agents.map((a) => `${a.id}:${a.status}:${a.focused ? 1 : 0}:${a.project ?? ""}`).join("|");
152
+ }
@@ -10,6 +10,8 @@
10
10
  import type { GraphFilters, GraphModel, VisibleData } from "../../graph-core/model.js";
11
11
  import type { GraphPayload, NodeDetail, NodeKind, RuntimeNode } from "../../graph-core/types.js";
12
12
  import { type Point } from "./layout.js";
13
+ import { GraphWatch } from "./watch.js";
14
+ import { GraphAgents } from "./agents.js";
13
15
  /** Nodes drawn at once. Terminals have far fewer pixels than a browser tab. */
14
16
  export declare const TUI_NODE_LIMIT = 350;
15
17
  export type GraphStatus = "idle" | "loading" | "ready" | "empty" | "error";
@@ -23,8 +25,14 @@ export interface Camera {
23
25
  /** World coordinates at the centre of the viewport. */
24
26
  cx: number;
25
27
  cy: number;
26
- /** Braille dots per world unit. */
27
- scale: number;
28
+ /**
29
+ * Braille dots per world unit, per axis. A terminal canvas is much wider
30
+ * than it is tall, so fitting a roughly round graph to the shorter axis
31
+ * would waste most of the width. The two scales are allowed to diverge up
32
+ * to MAX_STRETCH, which fills the screen while keeping the shape readable.
33
+ */
34
+ scaleX: number;
35
+ scaleY: number;
28
36
  }
29
37
  export interface SearchState {
30
38
  query: string;
@@ -45,6 +53,12 @@ export interface GraphControllerOptions {
45
53
  tokenOf?: (phrenPath: string) => string;
46
54
  /** Animation frame period; the tests shrink it. */
47
55
  frameMs?: number;
56
+ /** Injected watch, so tests can feed events without a log file or timers. */
57
+ watch?: GraphWatch;
58
+ /** Injected agents poller, so tests never shell out. */
59
+ agents?: GraphAgents;
60
+ /** Start with watch mode off (`--no-live`). */
61
+ watchEnabled?: boolean;
48
62
  }
49
63
  declare const DIRECTIONS: Record<string, Point>;
50
64
  export declare class GraphController {
@@ -79,7 +93,31 @@ export declare class GraphController {
79
93
  private readonly builder;
80
94
  private readonly tokenOf;
81
95
  private readonly frameMs;
96
+ /** Live tail of what phren is landing on, in this or any other terminal. */
97
+ readonly watch: GraphWatch;
98
+ /** Coding agents running on this machine, joined onto their projects. */
99
+ readonly agents: GraphAgents;
100
+ watchEnabled: boolean;
101
+ /**
102
+ * Wall-clock ms of the last navigation keypress. While the user is driving,
103
+ * incoming events still pulse and feed but do not steal the camera.
104
+ */
105
+ private lastUserInputAt;
82
106
  constructor(phrenPath: string, profile: string, opts?: GraphControllerOptions);
107
+ /** Idempotent; called every render so the tail starts with the view. */
108
+ startWatch(): void;
109
+ stopWatch(): void;
110
+ /** Idempotent; the poller only runs while the Graph view is open. */
111
+ startAgents(): void;
112
+ toggleAgents(): boolean;
113
+ toggleWatch(): boolean;
114
+ /** True while the user is actively driving, so the camera is left alone. */
115
+ private get userDriving();
116
+ /**
117
+ * New events landed. Light every node they touch, then follow the newest
118
+ * one that is actually on screen — unless the user is mid-navigation.
119
+ */
120
+ private onWatchEvents;
83
121
  /**
84
122
  * Let the shell trigger a repaint on its own (settle animation, fly-to,
85
123
  * a build finishing). Without it the controller blocks the first render on