@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
@@ -0,0 +1,23 @@
1
+ export interface ScreenFilter {
2
+ /** The bytes to write now, scroll regions rewritten; an unfinished tail stays held. */
3
+ push(chunk: Uint8Array): Buffer;
4
+ /** Releases the held bytes as they are, for when the caller's deadline passed. */
5
+ flush(): Buffer;
6
+ /** True while bytes are held. */
7
+ readonly holding: boolean;
8
+ /** True when the output so far ends between whole sequences, so the panel may be drawn. */
9
+ readonly atBoundary: boolean;
10
+ /** Whether the child last asked for a visible cursor (`ESC[?25h` / `ESC[?25l`). */
11
+ readonly cursorVisible: boolean;
12
+ /** True after a forced flush or a terminal reset, until `regionAsserted` is called. */
13
+ readonly regionLost: boolean;
14
+ /** The caller has set the scroll region again. */
15
+ regionAsserted(): void;
16
+ /** True while the child has saved the cursor (`ESC7`, `ESC[s`) and not restored it yet. */
17
+ readonly cursorSaved: boolean;
18
+ /** The child's row count, after a resize. */
19
+ setRows(rows: number): void;
20
+ }
21
+ /** Where the unfinished tail of `data` starts; `data.length` when everything is whole. */
22
+ export declare function unfinishedFrom(data: Buffer): number;
23
+ export declare function createScreenFilter(initialRows: number): ScreenFilter;
@@ -0,0 +1,142 @@
1
+ // src/run-filter.ts — the byte filter between Codex and the real terminal under `litcodex run`.
2
+ //
3
+ // `litcodex run` gives Codex a pseudo-terminal a few rows shorter than the real one and draws the LIT
4
+ // panel in the rows below. Two things decide whether that works. First, a scroll region Codex sets must
5
+ // end at its own last row: a reset (`ESC[r`, `ESC[;r`) or a bottom margin past that row would let Codex
6
+ // scroll the panel, so every DECSTBM is rewritten to stop there. Second, the panel can only be drawn
7
+ // between two whole sequences: a read may end inside an escape sequence (CSI, an OSC or DCS string, a
8
+ // lone ESC) or a UTF-8 character, and drawing there prints garbage such as `385;Breadfruit`. Such an
9
+ // unfinished tail is held back until the rest arrives. The caller flushes a tail that stays unfinished
10
+ // (after 50 ms; without that the screen once froze), and the filter then reports no boundary until a
11
+ // later read ends cleanly. A forced flush may also have let a scroll region through unclamped, and a full
12
+ // or soft reset (`ESC c`, `ESC[!p`) drops the region, so the filter then reports the region lost until the
13
+ // caller sets it again. While the child holds a saved cursor (`ESC7` or `ESC[s` not yet restored or reset), drawing
14
+ // the panel would overwrite that saved position, so the filter reports that too. Pure: no I/O, no timers.
15
+ const ESC = 0x1b;
16
+ const BEL = 0x07;
17
+ /** `ESC ]` OSC, `ESC P` DCS, `ESC X` SOS, `ESC ^` PM, `ESC _` APC: strings that end in BEL or `ESC \`. */
18
+ const STRING_STARTS = new Set([0x5d, 0x50, 0x58, 0x5e, 0x5f]);
19
+ const SCROLL_REGION = /\u001b\[(\d*)(?:;(\d*))?r/gu;
20
+ const CURSOR = /\u001b\[\?25([hl])/gu;
21
+ /** Cursor save (`ESC7`, `ESC[s`), restore (`ESC8`, `ESC[u`) and the resets that discard a saved cursor. */
22
+ const CURSOR_SAVE = /\u001b([78c])|\u001b\[([su]|!p)/gu;
23
+ /** True when the sequence starting at `data[at]` (an ESC) is complete within `data`. */
24
+ function escapeComplete(data, at) {
25
+ const kind = data[at + 1];
26
+ if (kind === undefined)
27
+ return false;
28
+ if (kind === 0x5b) {
29
+ for (let index = at + 2; index < data.length; index++) {
30
+ const byte = data[index];
31
+ // Parameters and intermediates continue; a final byte ends it; anything else is malformed and passes.
32
+ if (byte < 0x20 || byte > 0x3f)
33
+ return true;
34
+ }
35
+ return false;
36
+ }
37
+ if (STRING_STARTS.has(kind))
38
+ return data.indexOf(BEL, at + 2) >= 0;
39
+ if (kind >= 0x20 && kind <= 0x2f) {
40
+ for (let index = at + 2; index < data.length; index++) {
41
+ const byte = data[index];
42
+ if (byte < 0x20 || byte > 0x2f)
43
+ return true;
44
+ }
45
+ return false;
46
+ }
47
+ return true;
48
+ }
49
+ /** Where an unfinished trailing UTF-8 character starts; `data.length` when the tail is whole. */
50
+ function utf8TailStart(data) {
51
+ for (let back = 1; back <= Math.min(4, data.length); back++) {
52
+ const byte = data[data.length - back];
53
+ if ((byte & 0xc0) === 0x80)
54
+ continue;
55
+ const need = (byte & 0xe0) === 0xc0 ? 2 : (byte & 0xf0) === 0xe0 ? 3 : (byte & 0xf8) === 0xf0 ? 4 : 1;
56
+ return need > back ? data.length - back : data.length;
57
+ }
58
+ return data.length;
59
+ }
60
+ /** Where the unfinished tail of `data` starts; `data.length` when everything is whole. */
61
+ export function unfinishedFrom(data) {
62
+ let cut = data.length;
63
+ const last = data.lastIndexOf(ESC);
64
+ if (last >= 0 && !escapeComplete(data, last)) {
65
+ cut = last;
66
+ // A lone ESC may be the first half of the `ESC \` that ends an open string; hold the whole string.
67
+ const previous = last > 0 ? data.lastIndexOf(ESC, last - 1) : -1;
68
+ const kind = previous >= 0 ? data[previous + 1] : undefined;
69
+ if (kind !== undefined && STRING_STARTS.has(kind) && data.subarray(previous + 2, last).indexOf(BEL) < 0) {
70
+ cut = previous;
71
+ }
72
+ }
73
+ return Math.min(cut, utf8TailStart(data));
74
+ }
75
+ export function createScreenFilter(initialRows) {
76
+ let rows = initialRows;
77
+ let held = Buffer.alloc(0);
78
+ let boundary = true;
79
+ let cursorVisible = true;
80
+ let regionLost = false;
81
+ let cursorSaved = false;
82
+ const rewrite = (data) => {
83
+ if (data.indexOf(ESC) < 0)
84
+ return data;
85
+ const text = data.toString("latin1");
86
+ for (const match of text.matchAll(CURSOR))
87
+ cursorVisible = match[1] === "h";
88
+ for (const match of text.matchAll(CURSOR_SAVE)) {
89
+ cursorSaved = match[1] === "7" || match[2] === "s";
90
+ if (match[1] === "c" || match[2] === "!p")
91
+ regionLost = true;
92
+ }
93
+ if (!text.includes("r"))
94
+ return data;
95
+ const out = text.replace(SCROLL_REGION, (_all, top, bottom) => {
96
+ const first = top === "" ? 1 : Number(top);
97
+ const end = bottom === undefined || bottom === "" ? rows : Math.min(Number(bottom), rows);
98
+ return `\u001b[${first};${end}r`;
99
+ });
100
+ return out === text ? data : Buffer.from(out, "latin1");
101
+ };
102
+ return {
103
+ push(chunk) {
104
+ const data = held.length === 0 ? Buffer.from(chunk) : Buffer.concat([held, chunk]);
105
+ const cut = unfinishedFrom(data);
106
+ held = Buffer.from(data.subarray(cut));
107
+ if (held.length === 0)
108
+ boundary = true;
109
+ return rewrite(data.subarray(0, cut));
110
+ },
111
+ flush() {
112
+ if (held.length === 0)
113
+ return held;
114
+ const out = rewrite(held);
115
+ held = Buffer.alloc(0);
116
+ boundary = false;
117
+ regionLost = true;
118
+ return out;
119
+ },
120
+ get holding() {
121
+ return held.length > 0;
122
+ },
123
+ get atBoundary() {
124
+ return boundary && held.length === 0;
125
+ },
126
+ get cursorVisible() {
127
+ return cursorVisible;
128
+ },
129
+ get regionLost() {
130
+ return regionLost;
131
+ },
132
+ regionAsserted() {
133
+ regionLost = false;
134
+ },
135
+ get cursorSaved() {
136
+ return cursorSaved;
137
+ },
138
+ setRows(next) {
139
+ rows = next;
140
+ },
141
+ };
142
+ }
@@ -0,0 +1,29 @@
1
+ import { type CardStatus } from "./card-status.js";
2
+ import { type ChecklistRow } from "./workflow-map.js";
3
+ /** Rows the panel takes below Codex. */
4
+ export declare const PANEL_ROWS = 4;
5
+ /** The panel needs room for its own rows and a usable Codex above them. */
6
+ export declare const MIN_RUN_ROWS = 12;
7
+ export declare const MIN_RUN_COLUMNS = 40;
8
+ export interface RunPanelView {
9
+ /** The session's card, or null while no LIT turn has run in this folder since the run started. */
10
+ readonly status: CardStatus | null;
11
+ /** The open checklist row, else the next one, else the last finished one; null when there is none. */
12
+ readonly checklist: ChecklistRow | null;
13
+ }
14
+ export interface RunPanelOptions {
15
+ readonly width: number;
16
+ readonly color: boolean;
17
+ readonly now: number;
18
+ }
19
+ /** What the panel shows now for a run started in `cwd` at `since`. Never throws and never writes. */
20
+ export declare function readRunPanel(env: NodeJS.ProcessEnv, cwd: string, since: number, now: number): RunPanelView;
21
+ /** Exactly `PANEL_ROWS` rows, each at most `width` cells. Pure. */
22
+ export declare function renderRunPanel(view: RunPanelView, options: RunPanelOptions): string[];
23
+ /** The escapes that draw `rows` below a child of `childRows` rows and put the cursor back where it was. */
24
+ export declare function panelFrame(rows: readonly string[], options: {
25
+ readonly childRows: number;
26
+ readonly cursorVisible: boolean;
27
+ }): string;
28
+ /** The escapes that give the whole screen back: no scroll region, empty panel rows, cursor below the child. */
29
+ export declare function panelClear(childRows: number): string;
@@ -0,0 +1,102 @@
1
+ // src/run-panel.ts — the LIT panel `litcodex run` draws in the rows below Codex.
2
+ //
3
+ // Four rows, the same `┃` card the hooks print (screen-card.ts): the route with the turn's clock, the
4
+ // stage map, the running step, and the open checklist row. The session is the newest one whose thread
5
+ // pointer names the folder `litcodex run` started in and whose LIT activity is newer than the run, read
6
+ // the way `litcodex hud` reads it (hud.ts) with `rollout: false`, so no Codex rollout is opened. Until
7
+ // then the panel says, dimmed, that it waits for a LIT turn. Record text is stripped of control
8
+ // characters and every row is cut to the width given. The escape strings that place the panel save and
9
+ // restore the cursor around it and leave Codex's own rows alone. Nothing here writes a file.
10
+ import { realpathSync } from "node:fs";
11
+ import { clock, readCardStatus } from "./card-status.js";
12
+ import { clean, cleanStatus, fit, listSessions } from "./hud.js";
13
+ import { renderScreenCard } from "./screen-card.js";
14
+ import { readChecklist } from "./workflow-map.js";
15
+ /** Rows the panel takes below Codex. */
16
+ export const PANEL_ROWS = 4;
17
+ /** The panel needs room for its own rows and a usable Codex above them. */
18
+ export const MIN_RUN_ROWS = 12;
19
+ export const MIN_RUN_COLUMNS = 40;
20
+ const ACCENT = "\u001b[38;2;255;155;94m";
21
+ const DIM = "\u001b[2m";
22
+ const RESET = "\u001b[0m";
23
+ const MIN_WIDTH = 20;
24
+ const WAITING = { status: null, checklist: null };
25
+ function realOrSame(path) {
26
+ try {
27
+ return realpathSync(path);
28
+ }
29
+ catch {
30
+ return path;
31
+ }
32
+ }
33
+ /** What the panel shows now for a run started in `cwd` at `since`. Never throws and never writes. */
34
+ export function readRunPanel(env, cwd, since, now) {
35
+ try {
36
+ const real = realOrSame(cwd);
37
+ const session = listSessions(env).find((candidate) => (candidate.cwd === cwd || candidate.cwd === real) && candidate.activeAt >= since);
38
+ if (session === undefined)
39
+ return WAITING;
40
+ const status = readCardStatus(session.id, env, now, { rollout: false });
41
+ if (status.state === "ready")
42
+ return WAITING;
43
+ const rows = readChecklist(session.cwd, session.id);
44
+ const checklist = rows.find((row) => row.state === "current") ??
45
+ rows.find((row) => row.state === "pending") ??
46
+ rows.at(-1) ??
47
+ null;
48
+ return { status: cleanStatus(status), checklist };
49
+ }
50
+ catch {
51
+ return WAITING;
52
+ }
53
+ }
54
+ function stepText(status, now) {
55
+ if (status.step !== null)
56
+ return { text: `⠹ ${clean(status.step.tool)} · ${clock(now - status.step.startedAt)}`, live: true };
57
+ if (status.working)
58
+ return { text: "⠹ thinking", live: true };
59
+ if (status.state === "complete")
60
+ return { text: "✓ turn done", live: false };
61
+ return { text: "· waiting for your next prompt", live: false };
62
+ }
63
+ /** Exactly `PANEL_ROWS` rows, each at most `width` cells. Pure. */
64
+ export function renderRunPanel(view, options) {
65
+ const width = Math.max(MIN_WIDTH, Math.floor(options.width));
66
+ const status = view.status;
67
+ if (status === null) {
68
+ const rows = ["┃ 🔥 LIT · waiting for a LIT turn", "┃ Type `lit <task>` in Codex to start one.", "", ""];
69
+ return rows.map((row) => {
70
+ const line = fit(row, width);
71
+ return options.color && line !== "" ? `${DIM}${line}${RESET}` : line;
72
+ });
73
+ }
74
+ const started = status.turnStartedAt ?? status.ignitedAt ?? options.now;
75
+ const elapsed = clock((status.turnEndedAt ?? options.now) - started);
76
+ const hasMap = status.map !== null && status.map.cells.length > 0;
77
+ const card = renderScreenCard({
78
+ mode: status.mode ?? "lit",
79
+ note: status.state === "complete" ? `✓ ${elapsed}` : elapsed,
80
+ map: status.map,
81
+ checklist: view.checklist === null ? [] : [view.checklist],
82
+ }, { color: options.color, width }).split("\n");
83
+ const step = stepText(status, options.now);
84
+ const stepLine = fit(`┃ ${step.text}`, width);
85
+ const stepRow = options.color ? `${ACCENT}┃ ${RESET}${step.live ? "" : DIM}${stepLine.slice(2)}${RESET}` : stepLine;
86
+ return [card[0] ?? "", hasMap ? (card[1] ?? "") : "", stepRow, view.checklist === null ? "" : (card.at(-1) ?? "")];
87
+ }
88
+ /** The escapes that draw `rows` below a child of `childRows` rows and put the cursor back where it was. */
89
+ export function panelFrame(rows, options) {
90
+ let out = "\u001b7\u001b[?25l";
91
+ rows.forEach((row, index) => {
92
+ out += `\u001b[${options.childRows + 1 + index};1H\u001b[0m\u001b[2K${row}`;
93
+ });
94
+ return `${out}\u001b8${options.cursorVisible ? "\u001b[?25h" : ""}`;
95
+ }
96
+ /** The escapes that give the whole screen back: no scroll region, empty panel rows, cursor below the child. */
97
+ export function panelClear(childRows) {
98
+ let out = "\u001b[r\u001b[0m";
99
+ for (let index = 0; index < PANEL_ROWS; index++)
100
+ out += `\u001b[${childRows + 1 + index};1H\u001b[2K`;
101
+ return `${out}\u001b[${childRows + 1};1H\u001b[?25h`;
102
+ }
@@ -0,0 +1,24 @@
1
+ import { type ChecklistRow, type MapCell, type WorkflowMap } from "./workflow-map.js";
2
+ /** Codex indents hook rows by four cells; the card stays inside a common terminal width. */
3
+ export declare const DEFAULT_CARD_WIDTH = 96;
4
+ export interface ScreenCardInput {
5
+ readonly mode: string;
6
+ readonly note: string | null;
7
+ readonly map: WorkflowMap | null;
8
+ readonly checklist: readonly ChecklistRow[];
9
+ }
10
+ export interface ScreenCardOptions {
11
+ readonly color: boolean;
12
+ readonly width?: number;
13
+ }
14
+ /** One stage as the card, the `litcodex run` panel and the status line show it: the stage word always in capitals. */
15
+ export declare function stageText(item: MapCell): string;
16
+ /** The card rows joined by newlines, without the leading newline the caller adds for row one. */
17
+ export declare function renderScreenCard(input: ScreenCardInput, options: ScreenCardOptions): string;
18
+ /**
19
+ * The card for a session's saved state. With `quietWhenEmpty`, null when there is neither a map nor a
20
+ * checklist, since the route row alone would repeat the activation banner above it.
21
+ */
22
+ export declare function workflowCard(repoRoot: string, sessionId: string | null, mode: string, note: string | null, options: ScreenCardOptions & {
23
+ readonly quietWhenEmpty?: boolean;
24
+ }): string | null;
@@ -0,0 +1,104 @@
1
+ // src/screen-card.ts — the LIT card the hooks print inside the Codex screen.
2
+ //
3
+ // A few `┃` rows in a hook `systemMessage`: the route (`🔥 LIT · <mode>` and a short note), the stage map,
4
+ // then at most three checklist rows around the open task. The same rows come out as plain text (emoji and
5
+ // `┃` only) unless colour is asked for; the caller asks only when `screen-status` is on and
6
+ // NO_COLOR is unset, because only the terminal UI is known to draw the escapes. Record-derived text is
7
+ // stripped of control characters and every row is cut to the width given.
8
+ import { clean, displayWidth, fit } from "./hud.js";
9
+ import { progressBar, readChecklist, readWorkflowSignals, workflowMapCells, } from "./workflow-map.js";
10
+ const ACCENT = "\u001b[38;2;255;155;94m";
11
+ const GREEN = "\u001b[38;2;107;196;109m";
12
+ const BOLD = "\u001b[1m";
13
+ const DIM = "\u001b[2m";
14
+ const RESET = "\u001b[0m";
15
+ /** Codex indents hook rows by four cells; the card stays inside a common terminal width. */
16
+ export const DEFAULT_CARD_WIDTH = 96;
17
+ const MIN_CARD_WIDTH = 20;
18
+ const MAX_CHECKLIST = 3;
19
+ const seg = (text, style = "") => ({ text, style });
20
+ /** One stage as the card, the `litcodex run` panel and the status line show it: the stage word always in capitals. */
21
+ export function stageText(item) {
22
+ const word = item.word.toUpperCase();
23
+ const bar = item.progress === null
24
+ ? ""
25
+ : ` ${progressBar(item.progress.done, item.progress.total)} ${item.progress.done}/${item.progress.total}`;
26
+ switch (item.state) {
27
+ case "pending":
28
+ return `${item.icon} ${word}`;
29
+ case "done":
30
+ return item.label === null ? `✓ ${word}` : `✓ ${clean(item.label)}`;
31
+ case "partial":
32
+ return `${item.icon} ${word}${bar}`;
33
+ case "current":
34
+ return `${item.icon} ${clean(item.label ?? word)}${bar}`;
35
+ }
36
+ }
37
+ function cellStyle(item) {
38
+ if (item.state === "done")
39
+ return GREEN;
40
+ if (item.state === "current")
41
+ return `${BOLD}${ACCENT}`;
42
+ return DIM;
43
+ }
44
+ function mapRow(map) {
45
+ const row = [];
46
+ map.cells.forEach((item, index) => {
47
+ if (index > 0)
48
+ row.push(seg(" › ", DIM));
49
+ row.push(seg(stageText(item), cellStyle(item)));
50
+ });
51
+ return row;
52
+ }
53
+ function checklistRow(item) {
54
+ const label = clean(item.label);
55
+ if (item.state === "done")
56
+ return [seg("✓", GREEN), seg(` ${label}`, DIM)];
57
+ if (item.state === "current")
58
+ return [seg("▸", ACCENT), seg(` ${label}`)];
59
+ return [seg(`· ${label}`, DIM)];
60
+ }
61
+ /** Cut a row of styled pieces to `width` cells; the cut piece ends in `…` and nothing follows it. */
62
+ function fitRow(row, width) {
63
+ const out = [];
64
+ let used = 0;
65
+ for (const piece of row) {
66
+ const size = displayWidth(piece.text);
67
+ if (used + size <= width) {
68
+ out.push(piece);
69
+ used += size;
70
+ continue;
71
+ }
72
+ out.push({ text: fit(piece.text, width - used), style: piece.style });
73
+ break;
74
+ }
75
+ return out;
76
+ }
77
+ function paint(row, color) {
78
+ return row.map(({ text, style }) => (color && style !== "" ? `${style}${text}${RESET}` : text)).join("");
79
+ }
80
+ /** The card rows joined by newlines, without the leading newline the caller adds for row one. */
81
+ export function renderScreenCard(input, options) {
82
+ const width = Math.max(MIN_CARD_WIDTH, Math.floor(options.width ?? DEFAULT_CARD_WIDTH));
83
+ const bar = seg("┃ ", ACCENT);
84
+ const route = [seg(`🔥 LIT · ${clean(input.mode)}`, `${BOLD}${ACCENT}`)];
85
+ if (input.note !== null && clean(input.note) !== "")
86
+ route.push(seg(` ${clean(input.note)}`, DIM));
87
+ const rows = [route];
88
+ if (input.map !== null && input.map.cells.length > 0)
89
+ rows.push(mapRow(input.map));
90
+ for (const item of input.checklist.slice(0, MAX_CHECKLIST))
91
+ rows.push(checklistRow(item));
92
+ return rows.map((row) => paint([bar, ...fitRow(row, width - displayWidth(bar.text))], options.color)).join("\n");
93
+ }
94
+ /**
95
+ * The card for a session's saved state. With `quietWhenEmpty`, null when there is neither a map nor a
96
+ * checklist, since the route row alone would repeat the activation banner above it.
97
+ */
98
+ export function workflowCard(repoRoot, sessionId, mode, note, options) {
99
+ const map = workflowMapCells(mode, readWorkflowSignals(repoRoot, sessionId));
100
+ const checklist = readChecklist(repoRoot, sessionId);
101
+ if (options.quietWhenEmpty === true && map === null && checklist.length === 0)
102
+ return null;
103
+ return renderScreenCard({ mode, note, map, checklist }, options);
104
+ }
@@ -0,0 +1,24 @@
1
+ export declare const SCREEN_STATUS_ENV = "LITCODEX_SCREEN_STATUS";
2
+ export interface ScreenStatusState {
3
+ /** The hook card is coloured (NO_COLOR is applied by `screenColor`). */
4
+ readonly enabled: boolean;
5
+ readonly source: "default" | "command" | "environment";
6
+ readonly warnings: readonly string[];
7
+ }
8
+ export declare const SCREEN_STATUS_HELP_TEXT = "litcodex screen-status on|off|status\n\nColour the LIT card the hooks print inside Codex. Off by default.\nOnly the terminal `codex` draws the colour:\nthe Codex desktop app and IDE extensions show the colour codes as raw text,\nso turn it on only if you use the terminal `codex`. Without colour the card has the same rows.\nThe setting is stored in $CODEX_HOME/litcodex/screen-status.json; LITCODEX_SCREEN_STATUS=1 or 0 overrides it.\nNO_COLOR keeps the card plain.\n";
9
+ /** The stored choice and the environment override; a missing, corrupt or linked file reads as off. */
10
+ export declare function readScreenStatus(env: NodeJS.ProcessEnv): ScreenStatusState;
11
+ /** True when the hooks may colour the card: the switch is on and NO_COLOR is unset or empty. */
12
+ export declare function screenColor(env: NodeJS.ProcessEnv): boolean;
13
+ export declare function writeScreenStatus(env: NodeJS.ProcessEnv, enabled: boolean): boolean;
14
+ export interface ScreenStatusIo {
15
+ readonly env: NodeJS.ProcessEnv;
16
+ readonly stdout: {
17
+ write(text: string): unknown;
18
+ };
19
+ readonly stderr: {
20
+ write(text: string): unknown;
21
+ };
22
+ }
23
+ /** `litcodex screen-status on|off|status`; resolves an exit code and never throws. */
24
+ export declare function screenStatusCommand(args: readonly string[], io: ScreenStatusIo): number;
@@ -0,0 +1,110 @@
1
+ // src/screen-status.ts — the user-level switch for the LIT card's colour.
2
+ //
3
+ // Off by default. `litcodex screen-status on` colours the LIT card the hooks print, `off` keeps it plain and
4
+ // `status` reports the state. The choice lives in `$CODEX_HOME/litcodex/screen-status.json` (else
5
+ // `~/.codex`), written atomically and never through a symlink; `LITCODEX_SCREEN_STATUS=1|0` overrides it.
6
+ // Codex 0.162.0 and later draw ANSI colour inside hook text in the terminal UI, but the desktop app and IDE
7
+ // show the escape codes as raw text, and the hook input does not say which client is attached, hence the
8
+ // switch. NO_COLOR keeps the card plain either way; without colour the card has the same rows.
9
+ import { lstatSync } from "node:fs";
10
+ import { join } from "node:path";
11
+ import { writeSmallFile } from "./auto-handoff-settings.js";
12
+ import { codexHomeFrom, readSmallJson } from "./live-step.js";
13
+ export const SCREEN_STATUS_ENV = "LITCODEX_SCREEN_STATUS";
14
+ const SETTINGS_DIR = "litcodex";
15
+ const SETTINGS_FILE = "screen-status.json";
16
+ const MAX_SETTINGS_BYTES = 4_096;
17
+ const USAGE_EXIT_CODE = 64;
18
+ export const SCREEN_STATUS_HELP_TEXT = `litcodex screen-status on|off|status
19
+
20
+ Colour the LIT card the hooks print inside Codex. Off by default.
21
+ Only the terminal \`codex\` draws the colour:
22
+ the Codex desktop app and IDE extensions show the colour codes as raw text,
23
+ so turn it on only if you use the terminal \`codex\`. Without colour the card has the same rows.
24
+ The setting is stored in $CODEX_HOME/litcodex/screen-status.json; ${SCREEN_STATUS_ENV}=1 or 0 overrides it.
25
+ NO_COLOR keeps the card plain.
26
+ `;
27
+ function settingsPath(env) {
28
+ const home = codexHomeFrom(env);
29
+ return home === null ? null : { home, path: join(home, SETTINGS_DIR, SETTINGS_FILE) };
30
+ }
31
+ function isRecord(value) {
32
+ return typeof value === "object" && value !== null && !Array.isArray(value);
33
+ }
34
+ /** True when something sits at `path`, readable or not. */
35
+ function present(path) {
36
+ try {
37
+ return lstatSync(path, { throwIfNoEntry: false }) !== undefined;
38
+ }
39
+ catch {
40
+ return true;
41
+ }
42
+ }
43
+ /** The stored choice and the environment override; a missing, corrupt or linked file reads as off. */
44
+ export function readScreenStatus(env) {
45
+ const warnings = [];
46
+ const flag = env[SCREEN_STATUS_ENV]?.trim() ?? "";
47
+ if (flag === "1" || flag === "0")
48
+ return { enabled: flag === "1", source: "environment", warnings };
49
+ if (flag !== "")
50
+ warnings.push(`${SCREEN_STATUS_ENV} is not 1 or 0 and was ignored.`);
51
+ const settings = settingsPath(env);
52
+ if (settings === null)
53
+ return { enabled: false, source: "default", warnings };
54
+ const stored = readSmallJson(settings.path, MAX_SETTINGS_BYTES);
55
+ if (!isRecord(stored)) {
56
+ if (present(settings.path))
57
+ warnings.push(`${SETTINGS_DIR}/${SETTINGS_FILE} could not be read, so the card stays plain.`);
58
+ return { enabled: false, source: "default", warnings };
59
+ }
60
+ const enabled = stored["enabled"] === true;
61
+ return { enabled, source: enabled ? "command" : "default", warnings };
62
+ }
63
+ /** True when the hooks may colour the card: the switch is on and NO_COLOR is unset or empty. */
64
+ export function screenColor(env) {
65
+ const noColor = env["NO_COLOR"];
66
+ return readScreenStatus(env).enabled && (noColor === undefined || noColor === "");
67
+ }
68
+ export function writeScreenStatus(env, enabled) {
69
+ const settings = settingsPath(env);
70
+ if (settings === null)
71
+ return false;
72
+ return writeSmallFile(settings.path, `${JSON.stringify({ version: 1, enabled })}\n`, settings.home);
73
+ }
74
+ function describe(state, noColor) {
75
+ const origin = state.source === "environment" ? ` (set by ${SCREEN_STATUS_ENV})` : "";
76
+ const value = state.enabled ? (noColor ? "ON, but NO_COLOR keeps it plain" : "ON") : "OFF";
77
+ const lines = [`LIT card colour is ${value}${origin}.`];
78
+ for (const warning of state.warnings)
79
+ lines.push(`Warning: ${warning}`);
80
+ return `${lines.join("\n")}\n`;
81
+ }
82
+ /** `litcodex screen-status on|off|status`; resolves an exit code and never throws. */
83
+ export function screenStatusCommand(args, io) {
84
+ const [verb, ...extra] = args;
85
+ if (verb === "--help" || verb === "-h") {
86
+ io.stdout.write(SCREEN_STATUS_HELP_TEXT);
87
+ return 0;
88
+ }
89
+ if ((verb !== "on" && verb !== "off" && verb !== "status") || extra.length > 0) {
90
+ io.stderr.write("Usage: litcodex screen-status on|off|status\n");
91
+ return USAGE_EXIT_CODE;
92
+ }
93
+ if (verb === "status") {
94
+ const noColor = io.env["NO_COLOR"] !== undefined && io.env["NO_COLOR"] !== "";
95
+ io.stdout.write(describe(readScreenStatus(io.env), noColor));
96
+ return 0;
97
+ }
98
+ if (!writeScreenStatus(io.env, verb === "on")) {
99
+ io.stderr.write("litcodex screen-status: the setting could not be saved, so nothing changed.\n");
100
+ return 1;
101
+ }
102
+ const overridden = readScreenStatus(io.env).source === "environment"
103
+ ? ` ${SCREEN_STATUS_ENV} is set in the environment and takes priority over this setting.`
104
+ : "";
105
+ const note = verb === "on"
106
+ ? " The Codex desktop app and IDE show colour codes as raw text; use it with the terminal `codex`."
107
+ : "";
108
+ io.stdout.write(`LIT card colour is ${verb === "on" ? "ON" : "OFF"}.${note}${overridden}\n`);
109
+ return 0;
110
+ }
@@ -0,0 +1,17 @@
1
+ import { type CardStatus } from "./card-status.js";
2
+ export interface StatuslineIo {
3
+ readonly stdin: NodeJS.ReadableStream & {
4
+ readonly isTTY?: boolean;
5
+ };
6
+ readonly stdout: {
7
+ write(text: string): unknown;
8
+ };
9
+ readonly env: NodeJS.ProcessEnv;
10
+ readonly now?: () => number;
11
+ }
12
+ /** The one line, coloured on request and cut to `width` cells; "" when there is no LIT turn to show. */
13
+ export declare function statuslineText(status: CardStatus | null, options: {
14
+ width: number;
15
+ color: boolean;
16
+ }): string;
17
+ export declare function statuslineCommand(_args: readonly string[], io: StatuslineIo): Promise<number>;