@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
@@ -0,0 +1,256 @@
1
+ /**
2
+ * A braille dot canvas with a text overlay, rendered to ANSI lines.
3
+ *
4
+ * Each terminal cell is a 2×4 grid of braille dots (U+2800–U+28FF), which
5
+ * gives the graph 8× the resolution of plain block characters and — because
6
+ * a cell is roughly twice as tall as it is wide — dots that are close to
7
+ * square, so no aspect correction is needed. Edges and node blobs are drawn
8
+ * in dot space; glyphs, labels and the legend are written into a cell-level
9
+ * overlay that takes precedence when rendering.
10
+ *
11
+ * Every rendered line is exactly `cols` cells wide and built only from
12
+ * width-1 characters, so the shell's `truncateLine`/`displayWidth` pipeline
13
+ * measures it correctly.
14
+ */
15
+ import { displayWidth } from "../render.js";
16
+ const RESET = "\x1b[0m";
17
+ // Braille bit for dot (x, y) inside a cell — x ∈ {0,1}, y ∈ {0..3}.
18
+ const DOT_BITS = [
19
+ [0x01, 0x08],
20
+ [0x02, 0x10],
21
+ [0x04, 0x20],
22
+ [0x40, 0x80],
23
+ ];
24
+ let colorModeOverride = null;
25
+ /** Tests pin the mode; real terminals are sniffed from COLORTERM/TERM. */
26
+ export function setColorMode(mode) {
27
+ colorModeOverride = mode;
28
+ }
29
+ export function colorMode() {
30
+ if (colorModeOverride)
31
+ return colorModeOverride;
32
+ const colorterm = (process.env.COLORTERM || "").toLowerCase();
33
+ if (colorterm === "truecolor" || colorterm === "24bit")
34
+ return "truecolor";
35
+ const term = (process.env.TERM || "").toLowerCase();
36
+ if (term.includes("direct") || term.includes("truecolor"))
37
+ return "truecolor";
38
+ return "256";
39
+ }
40
+ export function hexToRgb(hex) {
41
+ const clean = hex.replace("#", "");
42
+ const full = clean.length === 3 ? clean.split("").map((c) => c + c).join("") : clean.padEnd(6, "0");
43
+ const value = Number.parseInt(full.slice(0, 6), 16);
44
+ if (!Number.isFinite(value))
45
+ return [127, 127, 127];
46
+ return [(value >> 16) & 255, (value >> 8) & 255, value & 255];
47
+ }
48
+ export function rgbToHex(r, g, b) {
49
+ const clampByte = (v) => Math.max(0, Math.min(255, Math.round(v)));
50
+ return `#${[clampByte(r), clampByte(g), clampByte(b)].map((v) => v.toString(16).padStart(2, "0")).join("")}`;
51
+ }
52
+ /** Linear blend from `from` toward `to` by `t` in [0, 1]. */
53
+ export function blendHex(from, to, t) {
54
+ const a = hexToRgb(from);
55
+ const b = hexToRgb(to);
56
+ const k = Math.max(0, Math.min(1, t));
57
+ return rgbToHex(a[0] + (b[0] - a[0]) * k, a[1] + (b[1] - a[1]) * k, a[2] + (b[2] - a[2]) * k);
58
+ }
59
+ /** Nearest xterm-256 index: 6×6×6 colour cube, or the grey ramp for greys. */
60
+ export function hexToAnsi256(hex) {
61
+ const [r, g, b] = hexToRgb(hex);
62
+ if (Math.abs(r - g) < 10 && Math.abs(g - b) < 10) {
63
+ if (r < 8)
64
+ return 16;
65
+ if (r > 248)
66
+ return 231;
67
+ return 232 + Math.round(((r - 8) / 247) * 23);
68
+ }
69
+ const level = (v) => Math.round((v / 255) * 5);
70
+ return 16 + 36 * level(r) + 6 * level(g) + level(b);
71
+ }
72
+ const sgrCache = new Map();
73
+ /** Foreground SGR for a hex colour in the active colour mode. */
74
+ export function hexToSgr(hex) {
75
+ const key = `${colorMode()}:${hex}`;
76
+ const cached = sgrCache.get(key);
77
+ if (cached)
78
+ return cached;
79
+ const [r, g, b] = hexToRgb(hex);
80
+ const sgr = colorMode() === "truecolor" ? `\x1b[38;2;${r};${g};${b}m` : `\x1b[38;5;${hexToAnsi256(hex)}m`;
81
+ sgrCache.set(key, sgr);
82
+ return sgr;
83
+ }
84
+ export class BrailleCanvas {
85
+ cols;
86
+ rows;
87
+ masks;
88
+ zs;
89
+ colors;
90
+ overlay;
91
+ constructor(cols, rows) {
92
+ this.cols = cols;
93
+ this.rows = rows;
94
+ const cells = Math.max(0, cols * rows);
95
+ this.masks = new Uint8Array(cells);
96
+ this.zs = new Int16Array(cells).fill(-32768);
97
+ this.colors = new Array(cells);
98
+ this.overlay = new Array(cells);
99
+ }
100
+ get dotWidth() { return this.cols * 2; }
101
+ get dotHeight() { return this.rows * 4; }
102
+ cell(col, row) {
103
+ return row * this.cols + col;
104
+ }
105
+ setDot(x, y, color, z = 0) {
106
+ const dx = Math.round(x);
107
+ const dy = Math.round(y);
108
+ if (dx < 0 || dy < 0 || dx >= this.dotWidth || dy >= this.dotHeight)
109
+ return;
110
+ const col = dx >> 1;
111
+ const row = dy >> 2;
112
+ const idx = this.cell(col, row);
113
+ this.masks[idx] |= DOT_BITS[dy & 3][dx & 1];
114
+ if (z >= this.zs[idx]) {
115
+ this.zs[idx] = z;
116
+ this.colors[idx] = color;
117
+ }
118
+ }
119
+ /** Bresenham in dot space. */
120
+ line(x0, y0, x1, y1, color, opts = {}) {
121
+ let ax = Math.round(x0);
122
+ let ay = Math.round(y0);
123
+ const bx = Math.round(x1);
124
+ const by = Math.round(y1);
125
+ const ddx = Math.abs(bx - ax);
126
+ const ddy = -Math.abs(by - ay);
127
+ const sx = ax < bx ? 1 : -1;
128
+ const sy = ay < by ? 1 : -1;
129
+ let err = ddx + ddy;
130
+ let n = 0;
131
+ for (;;) {
132
+ if (!opts.dotted || n % 2 === 0)
133
+ this.setDot(ax, ay, color, opts.z ?? 0);
134
+ if (ax === bx && ay === by)
135
+ break;
136
+ const e2 = 2 * err;
137
+ if (e2 >= ddy) {
138
+ err += ddy;
139
+ ax += sx;
140
+ }
141
+ if (e2 <= ddx) {
142
+ err += ddx;
143
+ ay += sy;
144
+ }
145
+ n++;
146
+ if (n > 100000)
147
+ break;
148
+ }
149
+ }
150
+ /** Filled disc in dot space; radius 0 lights a single dot. */
151
+ disc(cx, cy, radius, color, z = 1) {
152
+ const r = Math.max(0, radius);
153
+ const r2 = r * r + 0.25;
154
+ for (let y = Math.floor(cy - r); y <= Math.ceil(cy + r); y++) {
155
+ for (let x = Math.floor(cx - r); x <= Math.ceil(cx + r); x++) {
156
+ const ddx = x - cx;
157
+ const ddy = y - cy;
158
+ if (ddx * ddx + ddy * ddy <= r2)
159
+ this.setDot(x, y, color, z);
160
+ }
161
+ }
162
+ }
163
+ /**
164
+ * True when the cells [col, col+width) on `row` hold no overlay text —
165
+ * and, with `avoidDots`, no braille dots either, so a label does not
166
+ * paint over somebody else's node or edge.
167
+ */
168
+ isFree(col, row, width, avoidDots = false) {
169
+ if (row < 0 || row >= this.rows || col < 0 || col + width > this.cols)
170
+ return false;
171
+ for (let c = col; c < col + width; c++) {
172
+ const idx = this.cell(c, row);
173
+ if (this.overlay[idx])
174
+ return false;
175
+ if (avoidDots && this.masks[idx])
176
+ return false;
177
+ }
178
+ return true;
179
+ }
180
+ /**
181
+ * Write styled text into the overlay. Characters wider than one cell are
182
+ * replaced with `·` so the row stays exactly `cols` wide. Returns the number
183
+ * of cells written (0 when the text starts off-canvas).
184
+ */
185
+ putText(col, row, text, sgr = "") {
186
+ if (row < 0 || row >= this.rows)
187
+ return 0;
188
+ let c = col;
189
+ let written = 0;
190
+ for (const raw of text) {
191
+ if (c >= this.cols)
192
+ break;
193
+ if (c >= 0) {
194
+ const width = displayWidth(raw);
195
+ const ch = width === 1 ? raw : width === 0 ? "" : "·";
196
+ if (ch) {
197
+ this.overlay[this.cell(c, row)] = { ch, sgr };
198
+ written++;
199
+ }
200
+ else {
201
+ continue;
202
+ }
203
+ }
204
+ c++;
205
+ }
206
+ return written;
207
+ }
208
+ /** Every cell in a rectangle is overlaid with a space, hiding dots underneath (pane backdrop). */
209
+ clearRect(col, row, width, height) {
210
+ for (let r = row; r < row + height; r++) {
211
+ for (let c = col; c < col + width; c++) {
212
+ if (r < 0 || r >= this.rows || c < 0 || c >= this.cols)
213
+ continue;
214
+ this.overlay[this.cell(c, r)] = { ch: " ", sgr: "" };
215
+ }
216
+ }
217
+ }
218
+ render() {
219
+ const lines = [];
220
+ for (let row = 0; row < this.rows; row++) {
221
+ let out = "";
222
+ let current = "";
223
+ let dirty = false;
224
+ for (let col = 0; col < this.cols; col++) {
225
+ const idx = this.cell(col, row);
226
+ const over = this.overlay[idx];
227
+ let ch;
228
+ let sgr;
229
+ if (over) {
230
+ ch = over.ch;
231
+ sgr = over.sgr;
232
+ }
233
+ else if (this.masks[idx]) {
234
+ ch = String.fromCharCode(0x2800 + this.masks[idx]);
235
+ sgr = hexToSgr(this.colors[idx] ?? "#7f8db3");
236
+ }
237
+ else {
238
+ ch = " ";
239
+ sgr = "";
240
+ }
241
+ if (sgr !== current) {
242
+ if (current || dirty)
243
+ out += RESET;
244
+ out += sgr;
245
+ current = sgr;
246
+ dirty = true;
247
+ }
248
+ out += ch;
249
+ }
250
+ if (current || dirty)
251
+ out += RESET;
252
+ lines.push(out);
253
+ }
254
+ return lines;
255
+ }
256
+ }
@@ -0,0 +1,164 @@
1
+ /**
2
+ * State + interaction for the terminal graph view.
3
+ *
4
+ * The controller is the terminal-side analogue of the browser's
5
+ * `browser/graph/state.ts` + `interactions.ts`: it owns the payload built by
6
+ * `buildGraph`, the normalized model from `graph-core`, the force layout, a 2D
7
+ * camera, selection/search/focus, and the key map. Rendering lives in
8
+ * `graph-view.ts`; this module never writes to the terminal.
9
+ */
10
+ import type { GraphFilters, GraphModel, VisibleData } from "../../graph-core/model.js";
11
+ import type { GraphPayload, NodeDetail, NodeKind, RuntimeNode } from "../../graph-core/types.js";
12
+ import { type Point } from "./layout.js";
13
+ /** Nodes drawn at once. Terminals have far fewer pixels than a browser tab. */
14
+ export declare const TUI_NODE_LIMIT = 350;
15
+ export type GraphStatus = "idle" | "loading" | "ready" | "empty" | "error";
16
+ export interface FilterPreset {
17
+ name: string;
18
+ types: Partial<Record<NodeKind, boolean>>;
19
+ health: string;
20
+ }
21
+ export declare const FILTER_PRESETS: FilterPreset[];
22
+ export interface Camera {
23
+ /** World coordinates at the centre of the viewport. */
24
+ cx: number;
25
+ cy: number;
26
+ /** Braille dots per world unit. */
27
+ scale: number;
28
+ }
29
+ export interface SearchState {
30
+ query: string;
31
+ matchIds: Set<string>;
32
+ results: RuntimeNode[];
33
+ /** Cursor into results; -1 when nothing is active. */
34
+ index: number;
35
+ }
36
+ /** What the controller needs from the shell when a key lands. */
37
+ export interface GraphKeyHost {
38
+ setMessage(msg: string): void;
39
+ startInput(ctx: string, initial: string): void;
40
+ }
41
+ /** Injected so tests can feed a fixture instead of scanning a store. */
42
+ export type GraphBuilder = (phrenPath: string, profile: string) => Promise<GraphPayload>;
43
+ export interface GraphControllerOptions {
44
+ builder?: GraphBuilder;
45
+ tokenOf?: (phrenPath: string) => string;
46
+ /** Animation frame period; the tests shrink it. */
47
+ frameMs?: number;
48
+ }
49
+ declare const DIRECTIONS: Record<string, Point>;
50
+ export declare class GraphController {
51
+ readonly phrenPath: string;
52
+ readonly profile: string;
53
+ status: GraphStatus;
54
+ errorText: string;
55
+ /** A rebuild is running while the previous picture stays on screen. */
56
+ get refreshing(): boolean;
57
+ payload: GraphPayload | null;
58
+ model: GraphModel;
59
+ filters: GraphFilters;
60
+ visible: VisibleData;
61
+ /** Project nodes in display order for `[`/`]`. */
62
+ projects: RuntimeNode[];
63
+ presetIndex: number;
64
+ selectedId: string | null;
65
+ search: SearchState;
66
+ camera: Camera;
67
+ private sim;
68
+ private lastPositions;
69
+ private viewport;
70
+ private dataToken;
71
+ private building;
72
+ private repaintHook;
73
+ private timer;
74
+ private cameraTarget;
75
+ /** Re-frame once the intro settle finishes so the whole map is in view. */
76
+ private fitOnSettle;
77
+ /** Set by pan/zoom; until then a resize re-fits the whole map. */
78
+ private userMoved;
79
+ private readonly builder;
80
+ private readonly tokenOf;
81
+ private readonly frameMs;
82
+ constructor(phrenPath: string, profile: string, opts?: GraphControllerOptions);
83
+ /**
84
+ * Let the shell trigger a repaint on its own (settle animation, fly-to,
85
+ * a build finishing). Without it the controller blocks the first render on
86
+ * the build and snaps every camera move.
87
+ */
88
+ setRepaintHook(hook: (() => void) | null): void;
89
+ get positions(): Map<string, Point>;
90
+ private lastToken;
91
+ private lastTokenAt;
92
+ /** The store token, re-read at most every 2s: animation repaints must not stat the whole store. */
93
+ private currentToken;
94
+ /**
95
+ * Make sure a payload matching the store is loaded, or on its way. Blocks
96
+ * only on the very first build when there is no repaint hook to come back
97
+ * through; otherwise the old picture stays up with a refreshing badge.
98
+ */
99
+ ensureData(): Promise<void>;
100
+ private build;
101
+ /** Load a payload directly (tests, or a host that already has one). */
102
+ adopt(payload: GraphPayload): void;
103
+ get preset(): FilterPreset;
104
+ get focusedProject(): string | null;
105
+ private applyFilters;
106
+ private rebuildLayout;
107
+ /**
108
+ * The view reports its canvas size (in dots) before projecting. The first
109
+ * fit happens before any frame is drawn, so a size change re-fits unless
110
+ * the user has taken the camera over.
111
+ */
112
+ setViewport(width: number, height: number): void;
113
+ get viewportSize(): {
114
+ width: number;
115
+ height: number;
116
+ };
117
+ /** World → dot coordinates for the current camera. */
118
+ project(p: Point): Point;
119
+ fitAll(): void;
120
+ zoom(factor: number): void;
121
+ pan(direction: keyof typeof DIRECTIONS): void;
122
+ /** Centre the camera on a node, eased when animation is available. */
123
+ flyTo(nodeId: string): void;
124
+ /** Fly only when the node sits outside the middle band of the viewport. */
125
+ private keepInView;
126
+ relayout(): void;
127
+ private startAnimation;
128
+ stopAnimation(): void;
129
+ get animating(): boolean;
130
+ private animationFrame;
131
+ /** Called by the shell when the view changes away or the shell closes. */
132
+ dispose(): void;
133
+ detail(nodeId: string): NodeDetail | null;
134
+ /** Visible neighbours of a node, best first — what the pane numbers 1-9. */
135
+ neighborsOf(nodeId: string): RuntimeNode[];
136
+ select(nodeId: string | null, opts?: {
137
+ fly?: boolean;
138
+ }): void;
139
+ private nearestToCenter;
140
+ /**
141
+ * Arrow-key traversal: prefer a connected neighbour in that direction; if
142
+ * there is none, take the nearest visible node in that half-plane so the
143
+ * walk never dead-ends on a leaf.
144
+ */
145
+ walk(direction: keyof typeof DIRECTIONS): RuntimeNode | null;
146
+ private refreshSearch;
147
+ /** Set the query, light up matches, and fly to the best one. */
148
+ applySearch(query: string): RuntimeNode | null;
149
+ clearSearch(): void;
150
+ stepSearch(delta: number): RuntimeNode | null;
151
+ cyclePreset(delta?: number): FilterPreset;
152
+ /** Focus one project (name) or all (null). */
153
+ focusProject(name: string | null): void;
154
+ cycleProject(delta: number): string | null;
155
+ jumpToNeighbor(n: number): RuntimeNode | null;
156
+ /**
157
+ * Returns true when the key was consumed, undefined to let the shell's
158
+ * generic handler have it (q, :, ?, view shortcuts, final Esc).
159
+ */
160
+ handleKey(rawKey: string, host: GraphKeyHost): true | undefined;
161
+ /** One-line description for the message bar. */
162
+ describe(node: RuntimeNode): string;
163
+ }
164
+ export {};