@litfamily/litcodex 1.0.26 → 1.0.28

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 (71) hide show
  1. package/README-Ko-KR.md +27 -26
  2. package/README.md +31 -28
  3. package/dist/cli.d.ts +3 -2
  4. package/dist/cli.js +72 -3
  5. package/dist/install/generated-skill-payload-hashes.d.ts +2 -2
  6. package/dist/install/generated-skill-payload-hashes.js +2 -2
  7. package/dist/postinstall.js +12 -1
  8. package/dist/pty-helper.d.ts +7 -0
  9. package/dist/pty-helper.js +45 -0
  10. package/dist/run.d.ts +57 -0
  11. package/dist/run.js +354 -0
  12. package/marketplace/plugins/litcodex/.codex-plugin/plugin.json +1 -1
  13. package/marketplace/plugins/litcodex/components/auto-update/package.json +1 -1
  14. package/marketplace/plugins/litcodex/components/comment-checker/package.json +1 -1
  15. package/marketplace/plugins/litcodex/components/git-bash/package.json +1 -1
  16. package/marketplace/plugins/litcodex/components/lit-loop/dist/card-status.d.ts +8 -3
  17. package/marketplace/plugins/litcodex/components/lit-loop/dist/card-status.js +11 -6
  18. package/marketplace/plugins/litcodex/components/lit-loop/dist/hook-cli.js +28 -10
  19. package/marketplace/plugins/litcodex/components/lit-loop/dist/hud-cli.d.ts +38 -0
  20. package/marketplace/plugins/litcodex/components/lit-loop/dist/hud-cli.js +155 -0
  21. package/marketplace/plugins/litcodex/components/lit-loop/dist/hud.d.ts +42 -0
  22. package/marketplace/plugins/litcodex/components/lit-loop/dist/hud.js +297 -0
  23. package/marketplace/plugins/litcodex/components/lit-loop/dist/run-filter.d.ts +23 -0
  24. package/marketplace/plugins/litcodex/components/lit-loop/dist/run-filter.js +142 -0
  25. package/marketplace/plugins/litcodex/components/lit-loop/dist/run-panel.d.ts +29 -0
  26. package/marketplace/plugins/litcodex/components/lit-loop/dist/run-panel.js +102 -0
  27. package/marketplace/plugins/litcodex/components/lit-loop/dist/screen-card.d.ts +24 -0
  28. package/marketplace/plugins/litcodex/components/lit-loop/dist/screen-card.js +104 -0
  29. package/marketplace/plugins/litcodex/components/lit-loop/dist/screen-status.d.ts +24 -0
  30. package/marketplace/plugins/litcodex/components/lit-loop/dist/screen-status.js +110 -0
  31. package/marketplace/plugins/litcodex/components/lit-loop/dist/statusline.d.ts +17 -0
  32. package/marketplace/plugins/litcodex/components/lit-loop/dist/statusline.js +113 -0
  33. package/marketplace/plugins/litcodex/components/lit-loop/dist/workflow-map.d.ts +7 -0
  34. package/marketplace/plugins/litcodex/components/lit-loop/dist/workflow-map.js +58 -10
  35. package/marketplace/plugins/litcodex/components/lit-loop/package.json +1 -1
  36. package/marketplace/plugins/litcodex/components/lsp/package.json +1 -1
  37. package/marketplace/plugins/litcodex/components/rules/bundled-rules/lit-humanizer.md +2 -0
  38. package/marketplace/plugins/litcodex/components/rules/dist/deliverable-hedge-guard.d.ts +8 -0
  39. package/marketplace/plugins/litcodex/components/rules/dist/deliverable-hedge-guard.js +381 -39
  40. package/marketplace/plugins/litcodex/components/rules/package.json +1 -1
  41. package/marketplace/plugins/litcodex/components/start-work-continuation/package.json +1 -1
  42. package/marketplace/plugins/litcodex/components/telemetry/package.json +1 -1
  43. package/marketplace/plugins/litcodex/components/wikify-knowledge/package.json +1 -1
  44. package/marketplace/plugins/litcodex/skills/lit-humanizer/SKILL.md +4 -0
  45. package/marketplace/plugins/litcodex/skills/lit-humanizer/scripts/core.mjs +5 -1
  46. package/marketplace/plugins/litcodex/skills/lit-loop/SKILL.md +2 -1
  47. package/node_modules/@litcodex/lit-loop/dist/card-status.d.ts +8 -3
  48. package/node_modules/@litcodex/lit-loop/dist/card-status.js +11 -6
  49. package/node_modules/@litcodex/lit-loop/dist/hook-cli.js +28 -10
  50. package/node_modules/@litcodex/lit-loop/dist/hud-cli.d.ts +38 -0
  51. package/node_modules/@litcodex/lit-loop/dist/hud-cli.js +155 -0
  52. package/node_modules/@litcodex/lit-loop/dist/hud.d.ts +42 -0
  53. package/node_modules/@litcodex/lit-loop/dist/hud.js +297 -0
  54. package/node_modules/@litcodex/lit-loop/dist/run-filter.d.ts +23 -0
  55. package/node_modules/@litcodex/lit-loop/dist/run-filter.js +142 -0
  56. package/node_modules/@litcodex/lit-loop/dist/run-panel.d.ts +29 -0
  57. package/node_modules/@litcodex/lit-loop/dist/run-panel.js +102 -0
  58. package/node_modules/@litcodex/lit-loop/dist/screen-card.d.ts +24 -0
  59. package/node_modules/@litcodex/lit-loop/dist/screen-card.js +104 -0
  60. package/node_modules/@litcodex/lit-loop/dist/screen-status.d.ts +24 -0
  61. package/node_modules/@litcodex/lit-loop/dist/screen-status.js +110 -0
  62. package/node_modules/@litcodex/lit-loop/dist/statusline.d.ts +17 -0
  63. package/node_modules/@litcodex/lit-loop/dist/statusline.js +113 -0
  64. package/node_modules/@litcodex/lit-loop/dist/workflow-map.d.ts +7 -0
  65. package/node_modules/@litcodex/lit-loop/dist/workflow-map.js +58 -10
  66. package/node_modules/@litcodex/lit-loop/package.json +1 -1
  67. package/node_modules/@litcodex/lit-loop/skills/lit-humanizer/SKILL.md +4 -0
  68. package/node_modules/@litcodex/lit-loop/skills/lit-humanizer/scripts/core.mjs +5 -1
  69. package/node_modules/@litcodex/lit-loop/skills/lit-loop/SKILL.md +2 -1
  70. package/package.json +5 -2
  71. package/readme-assets/badge-version.svg +1 -1
package/dist/run.js ADDED
@@ -0,0 +1,354 @@
1
+ // `litcodex run`: Codex with a live LIT panel in the bottom rows of the same terminal.
2
+ //
3
+ // Codex runs in a pseudo-terminal (the optional `node-pty` package) four rows shorter than the real
4
+ // one, with the same folder, environment and arguments. Its output passes through the screen filter
5
+ // (lit-loop run-filter.ts), which keeps every scroll region above the panel and holds an unfinished
6
+ // escape sequence or UTF-8 character until the rest arrives, flushed after 50 ms at the latest. The
7
+ // panel (run-panel.ts) is drawn after each read that ends between whole sequences, while Codex holds no
8
+ // saved cursor, and once a second when its text changed; after a forced flush or a terminal reset the
9
+ // scroll region is set again first. Keys go to Codex unchanged. A resize waits for a boundary (or ends
10
+ // a flushed, still-open sequence with CAN), then sets the new scroll region, clears the screen, redraws
11
+ // the panel and resizes Codex.
12
+ //
13
+ // Every way out gives the terminal back: cooked mode, no scroll region, empty panel rows and the cursor
14
+ // below Codex. When Codex exits by itself the exit code is Codex's. SIGINT/SIGTERM/SIGHUP to the wrapper
15
+ // are passed to Codex, and an uncaught error stops it; its last output still reaches the terminal, and the
16
+ // wrapper waits up to 1.5 s for it to exit. Then, because Codex may not have undone its own modes, a
17
+ // defensive reset leaves the alternate screen and turns off bracketed paste, focus and mouse reporting
18
+ // and the keyboard flags before the panel is cleared. The exit code is then 128 + n, or 1 after an error.
19
+ //
20
+ // Ctrl-Z reaches Codex as a key and nothing more. Codex 0.163.0 stops its own process group on Ctrl-Z,
21
+ // but inside the pseudo-terminal that group has no job-control shell, so the stop is discarded and Codex
22
+ // keeps running (seen on macOS). Quit with Ctrl-C, or run plain `codex` for job control.
23
+ //
24
+ // When node-pty cannot load, its macOS helper is not executable and cannot be made so, stdin or stdout
25
+ // is not a terminal, the terminal is smaller than 40×12, or the pseudo-terminal does not start, one
26
+ // note goes to stderr and Codex runs as usual with this terminal. The command reads only LIT's own
27
+ // records and opens no Codex rollout; the one file it may change is the helper of the node-pty under its own
28
+ // node_modules (pty-helper.ts).
29
+ import { spawn } from "node:child_process";
30
+ import { accessSync, constants as fsConstants, statSync } from "node:fs";
31
+ import { createRequire } from "node:module";
32
+ import { constants as osConstants } from "node:os";
33
+ import { delimiter, dirname, join } from "node:path";
34
+ import { fileURLToPath } from "node:url";
35
+ import { createScreenFilter } from "@litcodex/lit-loop/dist/run-filter.js";
36
+ import { MIN_RUN_COLUMNS, MIN_RUN_ROWS, PANEL_ROWS, panelClear, panelFrame, readRunPanel, renderRunPanel, } from "@litcodex/lit-loop/dist/run-panel.js";
37
+ import { ensurePtyHelperExecutable } from "./pty-helper.js";
38
+ export const RUN_HELP_TEXT = `litcodex run [-- <codex args>...]
39
+
40
+ Start Codex with a live LIT panel in the bottom ${PANEL_ROWS} rows of this terminal. Codex runs in a
41
+ pseudo-terminal ${PANEL_ROWS} rows shorter, in this folder; the panel follows the newest LIT turn started
42
+ here: the route and its clock, the stage map, the running step and the open checklist row.
43
+ Everything after \`--\` goes to Codex unchanged, and Codex's exit code is the command's.
44
+
45
+ Without the optional node-pty package, outside a terminal, or in a terminal smaller than
46
+ ${MIN_RUN_COLUMNS}×${MIN_RUN_ROWS}, Codex runs as usual after a one-line note. The command writes no file.
47
+
48
+ Options:
49
+ --help Show this help.
50
+ `;
51
+ const HOLD_MS = 50;
52
+ const TICK_MS = 1_000;
53
+ const STOP_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
54
+ /** How long Codex gets to exit after a signal or an error before the terminal is taken back anyway. */
55
+ const GRACE_MS = 1_500;
56
+ /** Leaves the alternate screen and turns off what Codex may have turned on; used when it did not exit by itself. */
57
+ const MODE_RESET = "\u001b[?1049l\u001b[?2004l\u001b[?1004l\u001b[?1007l\u001b[?1000l\u001b[?1002l\u001b[?1003l\u001b[?1006l\u001b[<u";
58
+ /** Cancels an escape sequence the terminal has started to read. */
59
+ const CAN = "\u0018";
60
+ const DIM = "\u001b[2m";
61
+ const RESET = "\u001b[0m";
62
+ /** The `codex` executable on PATH, or null. */
63
+ export function findCodex(env) {
64
+ const names = process.platform === "win32"
65
+ ? ["codex", ...(env["PATHEXT"] ?? ".EXE;.CMD;.BAT").split(";").map((ext) => `codex${ext.toLowerCase()}`)]
66
+ : ["codex"];
67
+ for (const dir of (env["PATH"] ?? "").split(delimiter)) {
68
+ if (dir === "")
69
+ continue;
70
+ for (const name of names) {
71
+ const candidate = join(dir, name);
72
+ try {
73
+ if (!statSync(candidate).isFile())
74
+ continue;
75
+ accessSync(candidate, fsConstants.X_OK);
76
+ return candidate;
77
+ }
78
+ catch {
79
+ // Not here; try the next folder.
80
+ }
81
+ }
82
+ }
83
+ return null;
84
+ }
85
+ async function loadNodePty() {
86
+ try {
87
+ // A variable specifier keeps the optional package out of type checking and bundling.
88
+ const name = "node-pty";
89
+ const root = dirname(createRequire(import.meta.url).resolve(`${name}/package.json`));
90
+ const helper = ensurePtyHelperExecutable(root, process.platform, fileURLToPath(new URL("..", import.meta.url)));
91
+ if (helper !== null)
92
+ return `the node-pty helper ${helper} is not executable (run chmod +x on it)`;
93
+ const loaded = (await import(name));
94
+ const api = typeof loaded.spawn === "function" ? loaded : loaded.default;
95
+ return api !== undefined && typeof api.spawn === "function" ? api : null;
96
+ }
97
+ catch {
98
+ return null;
99
+ }
100
+ }
101
+ function signalCode(signal) {
102
+ const number = typeof signal === "number" ? signal : signal ? (osConstants.signals[signal] ?? 0) : 0;
103
+ return 128 + number;
104
+ }
105
+ /** Codex with this terminal's own stdio; Ctrl-C reaches Codex directly, so the wrapper only waits. */
106
+ function runPlainCodex(file, args, io) {
107
+ return new Promise((resolve) => {
108
+ const child = spawn(file, [...args], { stdio: "inherit", cwd: io.cwd, env: io.env });
109
+ const ignore = () => undefined;
110
+ const forward = (signal) => () => {
111
+ child.kill(signal);
112
+ };
113
+ const forwards = STOP_SIGNALS.map((signal) => [signal, signal === "SIGINT" ? ignore : forward(signal)]);
114
+ for (const [signal, listener] of forwards)
115
+ process.on(signal, listener);
116
+ const done = (code) => {
117
+ for (const [signal, listener] of forwards)
118
+ process.removeListener(signal, listener);
119
+ resolve(code);
120
+ };
121
+ child.once("error", (error) => {
122
+ io.stderr.write(`litcodex run: could not start codex: ${error.message}\n`);
123
+ done(127);
124
+ });
125
+ child.once("exit", (code, signal) => done(code ?? signalCode(signal)));
126
+ });
127
+ }
128
+ function note(io, text) {
129
+ const noColor = io.env["NO_COLOR"];
130
+ const dim = io.stderr.isTTY === true && (noColor === undefined || noColor === "");
131
+ io.stderr.write(dim ? `${DIM}${text}${RESET}\n` : `${text}\n`);
132
+ }
133
+ function fallbackReason(pty, io) {
134
+ if (pty === null)
135
+ return "node-pty is not installed or cannot load";
136
+ if (typeof pty === "string")
137
+ return pty;
138
+ if (io.stdin.isTTY !== true || io.stdout.isTTY !== true || typeof io.stdin.setRawMode !== "function")
139
+ return "stdin or stdout is not a terminal";
140
+ const rows = io.stdout.rows ?? 0;
141
+ const columns = io.stdout.columns ?? 0;
142
+ if (rows < MIN_RUN_ROWS || columns < MIN_RUN_COLUMNS)
143
+ return `the terminal is smaller than ${MIN_RUN_COLUMNS}×${MIN_RUN_ROWS}`;
144
+ return null;
145
+ }
146
+ export async function runCommand(args, io) {
147
+ const codex = findCodex(io.env);
148
+ if (codex === null) {
149
+ io.stderr.write("litcodex run: codex is not on PATH. Install Codex first, then run this again.\n");
150
+ return 127;
151
+ }
152
+ const runPlain = io.runPlain ?? runPlainCodex;
153
+ const pty = await (io.loadPty ?? loadNodePty)();
154
+ const reason = fallbackReason(pty, io);
155
+ if (reason !== null || pty === null || typeof pty === "string") {
156
+ note(io, `litcodex run: ${reason}, so Codex runs without the LIT panel.`);
157
+ return runPlain(codex, args, io);
158
+ }
159
+ const rows = io.stdout.rows ?? MIN_RUN_ROWS;
160
+ const columns = io.stdout.columns ?? MIN_RUN_COLUMNS;
161
+ let child;
162
+ try {
163
+ child = pty.spawn(codex, [...args], {
164
+ name: io.env["TERM"] ?? "xterm-256color",
165
+ cols: columns,
166
+ rows: rows - PANEL_ROWS,
167
+ cwd: io.cwd,
168
+ env: io.env,
169
+ encoding: null,
170
+ });
171
+ }
172
+ catch (error) {
173
+ const message = error instanceof Error ? error.message : String(error);
174
+ note(io, `litcodex run: the pseudo-terminal did not start (${message}), so Codex runs without the LIT panel.`);
175
+ return runPlain(codex, args, io);
176
+ }
177
+ return drive(child, io, { rows, columns });
178
+ }
179
+ /** Pumps bytes both ways, draws the panel and resolves the exit code once the terminal is given back. */
180
+ function drive(child, io, size) {
181
+ const now = io.now ?? Date.now;
182
+ const signals = io.signals ?? process;
183
+ const startedAt = now();
184
+ const noColor = io.env["NO_COLOR"];
185
+ const color = noColor === undefined || noColor === "";
186
+ let { rows, columns } = size;
187
+ let panelOn = true;
188
+ let childRows = rows - PANEL_ROWS;
189
+ const filter = createScreenFilter(childRows);
190
+ const write = (data) => {
191
+ try {
192
+ io.stdout.write(data);
193
+ }
194
+ catch {
195
+ // A terminal that has gone away (SIGHUP) cannot be written to; the way out continues.
196
+ }
197
+ };
198
+ const render = () => renderRunPanel(readRunPanel(io.env, io.cwd, startedAt, now()), { width: columns - 1, color, now: now() });
199
+ let lines = render();
200
+ let shown = lines.join("\n");
201
+ const draw = () => {
202
+ if (!panelOn || !filter.atBoundary || filter.cursorSaved)
203
+ return;
204
+ if (filter.regionLost) {
205
+ write(`\u001b7\u001b[1;${childRows}r\u001b8`);
206
+ filter.regionAsserted();
207
+ }
208
+ write(panelFrame(lines, { childRows, cursorVisible: filter.cursorVisible }));
209
+ shown = lines.join("\n");
210
+ };
211
+ // Make room so a cursor sitting in the bottom rows ends up above the panel, then fence Codex in.
212
+ write(`${"\n".repeat(PANEL_ROWS)}\u001b[${PANEL_ROWS}A\u001b7\u001b[1;${childRows}r\u001b8`);
213
+ io.stdin.setRawMode?.(true);
214
+ io.stdin.resume();
215
+ draw();
216
+ return new Promise((resolve) => {
217
+ let finished = false;
218
+ let clean = true;
219
+ let ending = null;
220
+ let crashMessage = null;
221
+ let hold;
222
+ let grace;
223
+ let resizePending = false;
224
+ /** Applies a held resize once nothing is held; a flushed, still-open sequence is ended with CAN first. */
225
+ const applyResize = () => {
226
+ if (!resizePending || finished || filter.holding)
227
+ return;
228
+ resizePending = false;
229
+ panelOn = rows >= MIN_RUN_ROWS && columns >= MIN_RUN_COLUMNS;
230
+ childRows = panelOn ? rows - PANEL_ROWS : rows;
231
+ filter.setRows(childRows);
232
+ write(`${filter.atBoundary ? "" : CAN}${panelOn ? `\u001b[1;${childRows}r` : "\u001b[r"}\u001b[2J`);
233
+ filter.regionAsserted();
234
+ lines = render();
235
+ if (panelOn && !filter.cursorSaved) {
236
+ write(panelFrame(lines, { childRows, cursorVisible: filter.cursorVisible }));
237
+ shown = lines.join("\n");
238
+ }
239
+ try {
240
+ child.resize(columns, childRows);
241
+ }
242
+ catch {
243
+ // The pty has just exited; its exit ends the run.
244
+ }
245
+ };
246
+ const onResize = () => {
247
+ rows = io.stdout.rows ?? rows;
248
+ columns = io.stdout.columns ?? columns;
249
+ resizePending = true;
250
+ applyResize();
251
+ };
252
+ const onInput = (...data) => {
253
+ child.write(data[0]);
254
+ };
255
+ const tick = setInterval(() => {
256
+ lines = render();
257
+ if (lines.join("\n") !== shown)
258
+ draw();
259
+ }, TICK_MS);
260
+ /** Stops Codex and waits for it, up to the grace period, before the terminal is taken back. */
261
+ const endAfterChild = (code, signal) => {
262
+ if (finished || ending !== null)
263
+ return;
264
+ ending = code;
265
+ clean = false;
266
+ try {
267
+ child.kill(signal);
268
+ }
269
+ catch {
270
+ // Already gone.
271
+ }
272
+ grace = setTimeout(() => finish(code), GRACE_MS);
273
+ };
274
+ const stops = STOP_SIGNALS.map((signal) => [signal, () => endAfterChild(signalCode(signal), signal)]);
275
+ const crash = (error) => {
276
+ crashMessage ??= error instanceof Error ? error.message : String(error);
277
+ endAfterChild(1);
278
+ };
279
+ const setRaw = (mode) => {
280
+ try {
281
+ io.stdin.setRawMode?.(mode);
282
+ }
283
+ catch {
284
+ // stdin already closed.
285
+ }
286
+ };
287
+ const restore = () => {
288
+ if (finished)
289
+ return;
290
+ finished = true;
291
+ clearInterval(tick);
292
+ clearTimeout(hold);
293
+ clearTimeout(grace);
294
+ io.stdin.removeListener("data", onInput);
295
+ io.stdout.removeListener("resize", onResize);
296
+ for (const [signal, listener] of stops)
297
+ signals.removeListener(signal, listener);
298
+ signals.removeListener("uncaughtException", crash);
299
+ signals.removeListener("exit", onProcessExit);
300
+ const rest = filter.flush();
301
+ if (rest.length > 0)
302
+ write(rest);
303
+ write(`${clean ? "" : MODE_RESET}${panelOn ? panelClear(childRows) : "\u001b[r\u001b[?25h"}`);
304
+ setRaw(false);
305
+ io.stdin.pause();
306
+ };
307
+ const onProcessExit = () => {
308
+ clean = false;
309
+ restore();
310
+ };
311
+ const finish = (code) => {
312
+ if (finished)
313
+ return;
314
+ restore();
315
+ if (crashMessage !== null)
316
+ io.stderr.write(`litcodex run: stopped: ${crashMessage}\n`);
317
+ resolve(code);
318
+ };
319
+ child.onData((chunk) => {
320
+ if (finished)
321
+ return;
322
+ const out = filter.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
323
+ if (out.length > 0)
324
+ write(out);
325
+ if (filter.holding) {
326
+ hold ??= setTimeout(() => {
327
+ hold = undefined;
328
+ const rest = filter.flush();
329
+ if (rest.length > 0)
330
+ write(rest);
331
+ applyResize();
332
+ }, HOLD_MS);
333
+ return;
334
+ }
335
+ clearTimeout(hold);
336
+ hold = undefined;
337
+ applyResize();
338
+ draw();
339
+ });
340
+ child.onExit(({ exitCode, signal }) => {
341
+ if (ending !== null)
342
+ return finish(ending);
343
+ if (signal)
344
+ clean = false;
345
+ finish(signal ? signalCode(signal) : exitCode);
346
+ });
347
+ io.stdin.on("data", onInput);
348
+ io.stdout.on("resize", onResize);
349
+ for (const [signal, listener] of stops)
350
+ signals.on(signal, listener);
351
+ signals.on("uncaughtException", crash);
352
+ signals.on("exit", onProcessExit);
353
+ });
354
+ }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "litcodex",
3
- "version": "1.0.26",
3
+ "version": "1.0.28",
4
4
  "description": "LitCodex Codex plugin: the lit-loop activation, durable loop runtime, and local review-gated knowledge.",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/auto-update",
3
- "version": "1.0.26",
3
+ "version": "1.0.28",
4
4
  "description": "LitCodex foreground update barrier for the SessionStart and management lifecycles.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/comment-checker",
3
- "version": "1.0.26",
3
+ "version": "1.0.28",
4
4
  "description": "LitCodex Comment-Checker hook: flags low-value / AI-slop comments introduced by edits.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/git-bash",
3
- "version": "1.0.26",
3
+ "version": "1.0.28",
4
4
  "description": "LitCodex Git-Bash hook: reminds Windows sessions to prefer the git_bash MCP before the built-in shell.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -34,12 +34,17 @@ export interface Usage {
34
34
  readonly fiveHour: number | null;
35
35
  readonly week: number | null;
36
36
  }
37
- /** The workspace a thread runs in: the hook pointer, else the rollout header; null when unknown. */
38
- export declare function resolveThreadCwd(threadId: string | null, env: NodeJS.ProcessEnv): string | null;
37
+ /** The workspace a thread runs in: the hook pointer, else (when `rollout` allows) the rollout header; null when unknown. */
38
+ export declare function resolveThreadCwd(threadId: string | null, env: NodeJS.ProcessEnv, rollout?: boolean): string | null;
39
39
  /** Context and quota use from the newest token count in a rollout tail; null when there is none. */
40
40
  export declare function usageFromRollout(text: string): Usage | null;
41
41
  /** A tool name as the card shows it: an MCP tool reads `server · tool` rather than its joined id. */
42
42
  export declare function toolDisplayName(tool: string): string;
43
- export declare function readCardStatus(threadId: string | null, env: NodeJS.ProcessEnv, now?: number): CardStatus;
43
+ /** The card for one thread. `rollout: false` keeps every Codex rollout file unread; the usage row then stays empty. */
44
+ export declare function readCardStatus(threadId: string | null, env: NodeJS.ProcessEnv, now?: number, options?: {
45
+ readonly rollout?: boolean;
46
+ }): CardStatus;
47
+ /** Minutes and seconds, `m:ss`. */
48
+ export declare function clock(ms: number): string;
44
49
  /** The card as plain text, for hosts that cannot draw it (the terminal `codex`). */
45
50
  export declare function cardStatusText(status: CardStatus): string;
@@ -119,8 +119,8 @@ function findRollout(home, id) {
119
119
  }
120
120
  return null;
121
121
  }
122
- /** The workspace a thread runs in: the hook pointer, else the rollout header; null when unknown. */
123
- export function resolveThreadCwd(threadId, env) {
122
+ /** The workspace a thread runs in: the hook pointer, else (when `rollout` allows) the rollout header; null when unknown. */
123
+ export function resolveThreadCwd(threadId, env, rollout = true) {
124
124
  const id = normalizeSessionId(threadId);
125
125
  // A thread id that needed cleaning is not one Codex issued; it gets no workspace.
126
126
  if (id === null || id !== threadId)
@@ -128,6 +128,8 @@ export function resolveThreadCwd(threadId, env) {
128
128
  const pointer = readThreadPointer(env, id);
129
129
  if (pointer !== null)
130
130
  return pointer.cwd;
131
+ if (!rollout)
132
+ return null;
131
133
  const home = codexHomeFrom(env);
132
134
  return home === null ? null : (findRollout(home, id)?.cwd ?? null);
133
135
  }
@@ -295,8 +297,10 @@ function turnWorking(live, lastStepAt, now) {
295
297
  }
296
298
  return lastStepAt !== null && now - lastStepAt < RECENT_STEP_MS;
297
299
  }
298
- export function readCardStatus(threadId, env, now = Date.now()) {
299
- const cwd = resolveThreadCwd(threadId, env);
300
+ /** The card for one thread. `rollout: false` keeps every Codex rollout file unread; the usage row then stays empty. */
301
+ export function readCardStatus(threadId, env, now = Date.now(), options = {}) {
302
+ const rollout = options.rollout !== false;
303
+ const cwd = resolveThreadCwd(threadId, env, rollout);
300
304
  const thread = cwd === null ? null : threadId;
301
305
  if (cwd === null || thread === null)
302
306
  return ready(null, null, null, now);
@@ -340,14 +344,15 @@ export function readCardStatus(threadId, env, now = Date.now()) {
340
344
  turnStartedAt: live?.turnStartedAt ?? null,
341
345
  turnEndedAt: turnOver ? live.turnEndedAt : null,
342
346
  working: step !== null || turnWorking(live, lastStepAt, now),
343
- usage: readUsage(thread, env),
347
+ usage: rollout ? readUsage(thread, env) : null,
344
348
  branch: readBranch(cwd),
345
349
  workspace,
346
350
  cardOpenedAt,
347
351
  now,
348
352
  };
349
353
  }
350
- function clock(ms) {
354
+ /** Minutes and seconds, `m:ss`. */
355
+ export function clock(ms) {
351
356
  const seconds = Math.max(0, Math.floor(ms / 1000));
352
357
  return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
353
358
  }
@@ -13,7 +13,9 @@ import { applyAutoHandoffRoute, clearManagedCompactionWhenOff, parseAutoHandoffR
13
13
  import { applyPreToolUseCreateGoalGuard, isLitUserPromptSubmitInput, runUserPromptSubmitHook } from "./codex-hook.js";
14
14
  import { endLiveStep, recordLiveStepEnd, recordLiveStepStart, recordTurnStart, writeThreadPointer, } from "./live-step.js";
15
15
  import { evaluatePlanPersistence, formatStopBlockOutput, recordLitPlanActivation } from "./plan-persistence.js";
16
- import { recordWorkflowTurn, workflowMapLine, workflowStopLine, workflowTurn } from "./workflow-map.js";
16
+ import { workflowCard } from "./screen-card.js";
17
+ import { screenColor } from "./screen-status.js";
18
+ import { recordWorkflowTurn, workflowStopLine, workflowTurn } from "./workflow-map.js";
17
19
  /** Hard cap on stdin to bound memory / ReDoS exposure inside the 5 s Codex hook budget. 8 MB. */
18
20
  export const MAX_STDIN_BYTES = 8_000_000;
19
21
  const INVALID_JSON_MESSAGE = "lit hook: stdin was not valid JSON";
@@ -111,8 +113,9 @@ export async function runUserPromptSubmitHookCli(stdin, stdout, stderr, repoRoot
111
113
  if (scope !== null)
112
114
  recordLitPlanActivation(scope.cwd, scope.sessionId);
113
115
  }
116
+ const env = auto.env ?? process.env;
114
117
  const own = decision.kind === "inject"
115
- ? withCardOffer(withWorkflowMap(decision.stdout, parsed, decision.mode), pointer, auto)
118
+ ? withCardOffer(withWorkflowMap(decision.stdout, parsed, decision.mode, env), pointer, auto)
116
119
  : "";
117
120
  const output = withAutoHandoffReload(own, parsed, repoRoot, auto);
118
121
  if (output !== "")
@@ -172,10 +175,11 @@ function withReloadContext(stdout, reload) {
172
175
  }
173
176
  }
174
177
  /**
175
- * Add the workflow map under the activation banner and remember the turn for the Stop line. Only an
176
- * event that names its own absolute `cwd` is mapped, so the map always describes the session's repo.
178
+ * Add the LIT card (map and checklist) under the activation banner and remember the turn for the Stop
179
+ * card. Only an event that names its own absolute `cwd` is mapped, so the card always describes the
180
+ * session's repo.
177
181
  */
178
- function withWorkflowMap(stdout, parsed, mode) {
182
+ function withWorkflowMap(stdout, parsed, mode, env) {
179
183
  if (!isRecord(parsed) || typeof parsed["cwd"] !== "string" || !isAbsolute(parsed["cwd"]))
180
184
  return stdout;
181
185
  const cwd = parsed["cwd"];
@@ -184,13 +188,16 @@ function withWorkflowMap(stdout, parsed, mode) {
184
188
  if (sessionId !== null && typeof parsed["turn_id"] === "string") {
185
189
  recordWorkflowTurn(cwd, sessionId, parsed["turn_id"], mode);
186
190
  }
187
- const map = workflowMapLine(cwd, sessionId, mode);
188
- if (map === null)
191
+ const card = workflowCard(cwd, sessionId, mode, "turn started", {
192
+ color: screenColor(env),
193
+ quietWhenEmpty: true,
194
+ });
195
+ if (card === null)
189
196
  return stdout;
190
197
  const output = JSON.parse(stdout);
191
198
  if (!isRecord(output) || typeof output["systemMessage"] !== "string")
192
199
  return stdout;
193
- output["systemMessage"] = `${output["systemMessage"]}\n${map}`;
200
+ output["systemMessage"] = `${output["systemMessage"]}\n${card}`;
194
201
  return `${JSON.stringify(output)}\n`;
195
202
  }
196
203
  catch {
@@ -237,6 +244,10 @@ function withContextAfterBanner(stdout, text) {
237
244
  function isRecord(value) {
238
245
  return typeof value === "object" && value !== null && !Array.isArray(value);
239
246
  }
247
+ /** A subagent's hooks carry the root session id, so its Stop must not end the parent's turn card. */
248
+ function isSubagent(parsed) {
249
+ return isRecord(parsed) && typeof parsed["agent_id"] === "string" && parsed["agent_id"] !== "";
250
+ }
240
251
  /** Absolute `cwd` from a hook event, else the fallback root. */
241
252
  function hookCwd(parsed, repoRoot) {
242
253
  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
@@ -299,15 +310,22 @@ export async function runStopPlanPersistenceHookCli(stdin, stdout, stderr, repoR
299
310
  stdout.write(formatStopBlockOutput(handoff.reason));
300
311
  return 0;
301
312
  }
313
+ // A subagent's Stop carries the parent's session id; the parent's turn is still running.
314
+ if (isSubagent(parsed))
315
+ return 0;
302
316
  endLiveStep(scope.cwd, scope.sessionId, auto.now);
317
+ const env = auto.env ?? process.env;
303
318
  const line = typeof record["turn_id"] === "string"
304
319
  ? workflowStopLine(scope.cwd, scope.sessionId, record["turn_id"], {
305
320
  stopHookActive: record["stop_hook_active"] === true,
306
321
  transcriptPath: typeof record["transcript_path"] === "string" ? record["transcript_path"] : null,
307
322
  })
308
323
  : null;
309
- if (line !== null)
310
- stdout.write(`${JSON.stringify({ systemMessage: line })}\n`);
324
+ const turn = line === null ? null : workflowTurn(scope.cwd, scope.sessionId);
325
+ const card = turn === null ? null : workflowCard(scope.cwd, scope.sessionId, turn.mode, line, { color: screenColor(env) });
326
+ // Codex puts a hook label before the first row, so the card starts on the next one.
327
+ if (card !== null)
328
+ stdout.write(`${JSON.stringify({ systemMessage: `\n${card}` })}\n`);
311
329
  }
312
330
  return 0;
313
331
  }
@@ -0,0 +1,38 @@
1
+ export declare const HUD_HELP_TEXT = "litcodex hud [--session <id>] [--once]\n\nWatch the LIT card of your newest Codex session from a second terminal window or tab.\nIt reads only LIT's own records, never writes a file and never touches Codex. Ctrl-C quits.\n\nOptions:\n --session <id> Follow this session (an exact id or a unique prefix) instead of the newest.\n --once Print one plain frame and exit.\n --help Show this help.\n";
2
+ export interface HudOutput {
3
+ write(text: string): unknown;
4
+ readonly isTTY?: boolean;
5
+ readonly columns?: number | undefined;
6
+ on?(event: "error", listener: (error: unknown) => void): unknown;
7
+ }
8
+ export interface HudLoopOptions {
9
+ readonly env: NodeJS.ProcessEnv;
10
+ readonly wanted: string | null;
11
+ readonly out: HudOutput;
12
+ readonly color: boolean;
13
+ readonly now: () => number;
14
+ }
15
+ /**
16
+ * A frame writer: each `tick` reads and renders once, and writes only when the frame text changed or the
17
+ * terminal was resized. On a terminal the frame stays one column short of the edge, where a full line
18
+ * followed by erase-to-end would lose its last glyph or wrap.
19
+ */
20
+ export declare function createHudLoop(options: HudLoopOptions): {
21
+ tick(): boolean;
22
+ };
23
+ /** The process events the command listens to; a test passes its own emitter. */
24
+ interface HudSignals {
25
+ on(event: string, listener: (...args: unknown[]) => void): unknown;
26
+ off(event: string, listener: (...args: unknown[]) => void): unknown;
27
+ }
28
+ export interface HudIo {
29
+ readonly stdout: HudOutput;
30
+ readonly stderr: {
31
+ write(text: string): unknown;
32
+ };
33
+ readonly env: NodeJS.ProcessEnv;
34
+ readonly signals?: HudSignals;
35
+ readonly now?: () => number;
36
+ }
37
+ export declare function hudCommand(args: readonly string[], io: HudIo): Promise<number>;
38
+ export {};