@litfamily/litcodex 1.0.21 → 1.0.23

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 (50) hide show
  1. package/README-Ko-KR.md +9 -9
  2. package/README.md +9 -9
  3. package/dist/install/doctor-render.js +5 -0
  4. package/dist/install/doctor.js +9 -0
  5. package/dist/install/types.d.ts +4 -0
  6. package/marketplace/plugins/litcodex/.codex-plugin/plugin.json +1 -1
  7. package/marketplace/plugins/litcodex/.mcp.json +9 -1
  8. package/marketplace/plugins/litcodex/components/auto-update/package.json +1 -1
  9. package/marketplace/plugins/litcodex/components/comment-checker/package.json +1 -1
  10. package/marketplace/plugins/litcodex/components/git-bash/package.json +1 -1
  11. package/marketplace/plugins/litcodex/components/lit-loop/dist/card-html.d.ts +1 -0
  12. package/marketplace/plugins/litcodex/components/lit-loop/dist/card-html.js +313 -0
  13. package/marketplace/plugins/litcodex/components/lit-loop/dist/card-mcp.d.ts +14 -0
  14. package/marketplace/plugins/litcodex/components/lit-loop/dist/card-mcp.js +141 -0
  15. package/marketplace/plugins/litcodex/components/lit-loop/dist/card-server.d.ts +2 -0
  16. package/marketplace/plugins/litcodex/components/lit-loop/dist/card-server.js +38 -0
  17. package/marketplace/plugins/litcodex/components/lit-loop/dist/card-status.d.ts +43 -0
  18. package/marketplace/plugins/litcodex/components/lit-loop/dist/card-status.js +363 -0
  19. package/marketplace/plugins/litcodex/components/lit-loop/dist/cli.js +5 -1
  20. package/marketplace/plugins/litcodex/components/lit-loop/dist/hook-cli.d.ts +14 -0
  21. package/marketplace/plugins/litcodex/components/lit-loop/dist/hook-cli.js +76 -2
  22. package/marketplace/plugins/litcodex/components/lit-loop/dist/live-step.d.ts +59 -0
  23. package/marketplace/plugins/litcodex/components/lit-loop/dist/live-step.js +287 -0
  24. package/marketplace/plugins/litcodex/components/lit-loop/dist/workflow-map.d.ts +30 -0
  25. package/marketplace/plugins/litcodex/components/lit-loop/dist/workflow-map.js +113 -45
  26. package/marketplace/plugins/litcodex/components/lit-loop/package.json +1 -1
  27. package/marketplace/plugins/litcodex/components/lsp/package.json +1 -1
  28. package/marketplace/plugins/litcodex/components/rules/package.json +1 -1
  29. package/marketplace/plugins/litcodex/components/start-work-continuation/package.json +1 -1
  30. package/marketplace/plugins/litcodex/components/telemetry/package.json +1 -1
  31. package/marketplace/plugins/litcodex/components/wikify-knowledge/package.json +1 -1
  32. package/marketplace/plugins/litcodex/hooks/hooks.json +20 -0
  33. package/node_modules/@litcodex/lit-loop/dist/card-html.d.ts +1 -0
  34. package/node_modules/@litcodex/lit-loop/dist/card-html.js +313 -0
  35. package/node_modules/@litcodex/lit-loop/dist/card-mcp.d.ts +14 -0
  36. package/node_modules/@litcodex/lit-loop/dist/card-mcp.js +141 -0
  37. package/node_modules/@litcodex/lit-loop/dist/card-server.d.ts +2 -0
  38. package/node_modules/@litcodex/lit-loop/dist/card-server.js +38 -0
  39. package/node_modules/@litcodex/lit-loop/dist/card-status.d.ts +43 -0
  40. package/node_modules/@litcodex/lit-loop/dist/card-status.js +363 -0
  41. package/node_modules/@litcodex/lit-loop/dist/cli.js +5 -1
  42. package/node_modules/@litcodex/lit-loop/dist/hook-cli.d.ts +14 -0
  43. package/node_modules/@litcodex/lit-loop/dist/hook-cli.js +76 -2
  44. package/node_modules/@litcodex/lit-loop/dist/live-step.d.ts +59 -0
  45. package/node_modules/@litcodex/lit-loop/dist/live-step.js +287 -0
  46. package/node_modules/@litcodex/lit-loop/dist/workflow-map.d.ts +30 -0
  47. package/node_modules/@litcodex/lit-loop/dist/workflow-map.js +113 -45
  48. package/node_modules/@litcodex/lit-loop/package.json +1 -1
  49. package/package.json +2 -2
  50. package/readme-assets/badge-version.svg +1 -1
@@ -0,0 +1,59 @@
1
+ export interface LiveStep {
2
+ readonly tool: string | null;
3
+ readonly toolUseId: string | null;
4
+ readonly startedAt: number | null;
5
+ readonly endedAt: number | null;
6
+ readonly turnStartedAt: number | null;
7
+ readonly turnEndedAt: number | null;
8
+ /** The tool that finished last in this turn; most steps end between two card polls. */
9
+ readonly lastTool: string | null;
10
+ }
11
+ export interface ThreadPointer {
12
+ readonly cwd: string;
13
+ readonly updatedAt: number;
14
+ readonly cardOfferedAt: number | null;
15
+ }
16
+ export interface ToolRef {
17
+ readonly tool: string;
18
+ readonly toolUseId: string | null;
19
+ }
20
+ /**
21
+ * Open a regular file for reading, or return null. The type is checked before the open, so a symlink,
22
+ * a named pipe or a device is never opened (opening a pipe would wait for a writer and freeze a hook);
23
+ * the open itself refuses a symlink swapped in since, and callers check the type again with `fstat`.
24
+ */
25
+ export declare function openRegularFile(path: string): number | null;
26
+ /** Parse a small regular file opened without following a symlink; null on any failure. */
27
+ export declare function readSmallJson(path: string, maxBytes?: number): unknown;
28
+ /** True when every folder of `rel` under `base` is missing or a real directory (no symlink on the way). */
29
+ export declare function plainDirsOrMissing(base: string, rel: string): boolean;
30
+ /**
31
+ * Write `text` to `path` through a new temp file beside it and a rename. The temp name is random and
32
+ * opened exclusively, so a file or symlink planted at a guessable name is never written through.
33
+ */
34
+ export declare function writeFileAtomic(path: string, text: string): void;
35
+ export declare function liveStepPath(repoRoot: string, sessionId: string): string | null;
36
+ /** True when every folder of `rel` under `base` is a real directory (no symlink on the way). */
37
+ export declare function plainDirs(base: string, rel: string): boolean;
38
+ export declare function readLiveStep(repoRoot: string, sessionId: string): LiveStep | null;
39
+ /**
40
+ * Open a turn: a LIT prompt arrived, so the model is working until Stop says otherwise. A tool that is
41
+ * still running (a message typed while it runs) keeps its step.
42
+ */
43
+ export declare function recordTurnStart(repoRoot: string, sessionId: string, now?: number): void;
44
+ export declare function recordLiveStepStart(repoRoot: string, sessionId: string, ref: ToolRef, now?: number): void;
45
+ /** Clear the step when this call is the one shown; a newer parallel call keeps its record. */
46
+ export declare function recordLiveStepEnd(repoRoot: string, sessionId: string, ref: ToolRef, now?: number): void;
47
+ /**
48
+ * End whatever step this session still shows, since no tool runs once Stop fires, and close the turn
49
+ * unless a Stop guard is sending the model back to work (`closeTurn` false).
50
+ */
51
+ export declare function endLiveStep(repoRoot: string, sessionId: string, now?: number, closeTurn?: boolean): void;
52
+ /** `$CODEX_HOME`, else `$HOME/.codex`, read from the given environment only; null when neither is set. */
53
+ export declare function codexHomeFrom(env: NodeJS.ProcessEnv): string | null;
54
+ export declare function threadPointerPath(env: NodeJS.ProcessEnv, threadId: string): string | null;
55
+ export declare function readThreadPointer(env: NodeJS.ProcessEnv, threadId: string): ThreadPointer | null;
56
+ /** Point the thread at `cwd`; skips the write when the pointer already says so. */
57
+ export declare function writeThreadPointer(env: NodeJS.ProcessEnv, threadId: string, cwd: string, now?: number, options?: {
58
+ readonly cardOffered?: boolean;
59
+ }): void;
@@ -0,0 +1,287 @@
1
+ // src/live-step.ts — the live step and the per-thread pointer the LIT card reads.
2
+ //
3
+ // Two small owned records. The live step lives in the workspace (`.litcodex/live-step/<session>.json`)
4
+ // and names the tool that is running now; the catch-all PreToolUse hook writes it and PostToolUse
5
+ // clears it. It also says whether the turn is still open: a LIT prompt opens it and Stop closes it, so
6
+ // the card can tell a model that is thinking between tools from one that has answered and waits. The pointer lives in the Codex home the hook sees (`litcodex/lit-loop/threads/<session>.json`)
7
+ // and maps a session id, which the desktop app also sends as its thread id, to the hook's `cwd`, because
8
+ // the card server is started in the plugin folder and learns nothing else about the thread. Every write
9
+ // is atomic, skips symlinked folders and never throws; every read is size-capped and refuses symlinks.
10
+ import { randomBytes } from "node:crypto";
11
+ import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readSync, renameSync, rmSync, writeFileSync, } from "node:fs";
12
+ import { basename, isAbsolute, join } from "node:path";
13
+ import { normalizeSessionId } from "./state-paths.js";
14
+ const LIVE_STEP_DIR = ".litcodex/live-step";
15
+ const POINTER_DIR = "litcodex/lit-loop/threads";
16
+ const MAX_RECORD_BYTES = 4_096;
17
+ const MAX_TOOL_LABEL = 64;
18
+ function isRecord(value) {
19
+ return typeof value === "object" && value !== null && !Array.isArray(value);
20
+ }
21
+ const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
22
+ const NON_BLOCK = constants.O_NONBLOCK ?? 0;
23
+ /**
24
+ * Open a regular file for reading, or return null. The type is checked before the open, so a symlink,
25
+ * a named pipe or a device is never opened (opening a pipe would wait for a writer and freeze a hook);
26
+ * the open itself refuses a symlink swapped in since, and callers check the type again with `fstat`.
27
+ */
28
+ export function openRegularFile(path) {
29
+ try {
30
+ const stat = lstatSync(path, { throwIfNoEntry: false });
31
+ if (stat === undefined || !stat.isFile())
32
+ return null;
33
+ return openSync(path, constants.O_RDONLY | NO_FOLLOW | NON_BLOCK);
34
+ }
35
+ catch {
36
+ return null;
37
+ }
38
+ }
39
+ /** Parse a small regular file opened without following a symlink; null on any failure. */
40
+ export function readSmallJson(path, maxBytes = MAX_RECORD_BYTES) {
41
+ let fd = null;
42
+ try {
43
+ fd = openRegularFile(path);
44
+ if (fd === null)
45
+ return null;
46
+ const stat = fstatSync(fd);
47
+ if (!stat.isFile() || stat.size > maxBytes)
48
+ return null;
49
+ const buffer = Buffer.alloc(stat.size);
50
+ const read = readSync(fd, buffer, 0, stat.size, 0);
51
+ return JSON.parse(buffer.subarray(0, read).toString("utf8"));
52
+ }
53
+ catch {
54
+ return null;
55
+ }
56
+ finally {
57
+ if (fd !== null)
58
+ closeSync(fd);
59
+ }
60
+ }
61
+ /** True when `path` is missing or a real directory; a symlink or a file in its place is refused. */
62
+ function plainDirOrMissing(path) {
63
+ try {
64
+ return lstatSync(path).isDirectory();
65
+ }
66
+ catch (error) {
67
+ return error.code === "ENOENT";
68
+ }
69
+ }
70
+ /** True when every folder of `rel` under `base` is missing or a real directory (no symlink on the way). */
71
+ export function plainDirsOrMissing(base, rel) {
72
+ let dir = base;
73
+ for (const part of rel.split("/")) {
74
+ dir = join(dir, part);
75
+ if (!plainDirOrMissing(dir))
76
+ return false;
77
+ }
78
+ return true;
79
+ }
80
+ /** Write `value` as JSON through a temp file and a rename, inside `dir` under `base`. Never throws. */
81
+ function writeRecord(base, rel, name, value) {
82
+ try {
83
+ if (!plainDirsOrMissing(base, rel))
84
+ return;
85
+ const dir = join(base, rel);
86
+ mkdirSync(dir, { recursive: true });
87
+ writeFileAtomic(join(dir, name), `${JSON.stringify(value)}\n`);
88
+ }
89
+ catch {
90
+ // The card shows the last good record; a hook never fails because of it.
91
+ }
92
+ }
93
+ /**
94
+ * Write `text` to `path` through a new temp file beside it and a rename. The temp name is random and
95
+ * opened exclusively, so a file or symlink planted at a guessable name is never written through.
96
+ */
97
+ export function writeFileAtomic(path, text) {
98
+ const tmp = `${path}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
99
+ try {
100
+ writeFileSync(tmp, text, { flag: "wx" });
101
+ renameSync(tmp, path);
102
+ }
103
+ catch (error) {
104
+ if (error.code !== "EEXIST")
105
+ rmSync(tmp, { force: true });
106
+ throw error;
107
+ }
108
+ }
109
+ /** A printable tool label of at most 64 characters. */
110
+ function toolLabel(tool) {
111
+ const clean = tool.replace(/[\u0000-\u001f\u007f-\u009f]/gu, "").trim();
112
+ return clean.length > MAX_TOOL_LABEL ? `${clean.slice(0, MAX_TOOL_LABEL - 1)}…` : clean;
113
+ }
114
+ export function liveStepPath(repoRoot, sessionId) {
115
+ const id = normalizeSessionId(sessionId);
116
+ if (id === null || typeof repoRoot !== "string" || !isAbsolute(repoRoot))
117
+ return null;
118
+ return join(repoRoot, LIVE_STEP_DIR, `${id}.json`);
119
+ }
120
+ /** True when every folder of `rel` under `base` is a real directory (no symlink on the way). */
121
+ export function plainDirs(base, rel) {
122
+ let dir = base;
123
+ for (const part of rel.split("/")) {
124
+ dir = join(dir, part);
125
+ try {
126
+ if (!lstatSync(dir).isDirectory())
127
+ return false;
128
+ }
129
+ catch {
130
+ return false;
131
+ }
132
+ }
133
+ return true;
134
+ }
135
+ export function readLiveStep(repoRoot, sessionId) {
136
+ const path = liveStepPath(repoRoot, sessionId);
137
+ if (path === null || !plainDirs(repoRoot, LIVE_STEP_DIR))
138
+ return null;
139
+ const record = readSmallJson(path);
140
+ if (!isRecord(record) || record["version"] !== 1)
141
+ return null;
142
+ const text = (value) => (typeof value === "string" && value !== "" ? value : null);
143
+ const time = (value) => (typeof value === "number" && Number.isFinite(value) ? value : null);
144
+ return {
145
+ tool: text(record["tool"]),
146
+ toolUseId: text(record["toolUseId"]),
147
+ startedAt: time(record["startedAt"]),
148
+ endedAt: time(record["endedAt"]),
149
+ turnStartedAt: time(record["turnStartedAt"]),
150
+ turnEndedAt: time(record["turnEndedAt"]),
151
+ lastTool: text(record["lastTool"]),
152
+ };
153
+ }
154
+ function writeLiveStep(repoRoot, path, step) {
155
+ writeRecord(repoRoot, LIVE_STEP_DIR, basename(path), { version: 1, ...step });
156
+ }
157
+ /** A tool step older than this never ended cleanly, so it no longer counts as running. */
158
+ const STALE_STEP_MS = 30 * 60 * 1000;
159
+ /**
160
+ * Open a turn: a LIT prompt arrived, so the model is working until Stop says otherwise. A tool that is
161
+ * still running (a message typed while it runs) keeps its step.
162
+ */
163
+ export function recordTurnStart(repoRoot, sessionId, now = Date.now()) {
164
+ const path = liveStepPath(repoRoot, sessionId);
165
+ if (path === null)
166
+ return;
167
+ const current = readLiveStep(repoRoot, sessionId);
168
+ const running = current !== null && current.tool !== null && current.startedAt !== null && now - current.startedAt < STALE_STEP_MS
169
+ ? current
170
+ : null;
171
+ writeLiveStep(repoRoot, path, {
172
+ tool: running?.tool ?? null,
173
+ toolUseId: running?.toolUseId ?? null,
174
+ startedAt: running?.startedAt ?? null,
175
+ endedAt: null,
176
+ turnStartedAt: now,
177
+ turnEndedAt: null,
178
+ lastTool: null,
179
+ });
180
+ }
181
+ export function recordLiveStepStart(repoRoot, sessionId, ref, now = Date.now()) {
182
+ const path = liveStepPath(repoRoot, sessionId);
183
+ const tool = toolLabel(ref.tool);
184
+ if (path === null || tool === "")
185
+ return;
186
+ const current = readLiveStep(repoRoot, sessionId);
187
+ writeLiveStep(repoRoot, path, {
188
+ tool,
189
+ toolUseId: ref.toolUseId,
190
+ startedAt: now,
191
+ endedAt: null,
192
+ turnStartedAt: current?.turnStartedAt ?? null,
193
+ turnEndedAt: null,
194
+ lastTool: current?.lastTool ?? null,
195
+ });
196
+ }
197
+ /** Clear the step when this call is the one shown; a newer parallel call keeps its record. */
198
+ export function recordLiveStepEnd(repoRoot, sessionId, ref, now = Date.now()) {
199
+ const path = liveStepPath(repoRoot, sessionId);
200
+ if (path === null)
201
+ return;
202
+ const current = readLiveStep(repoRoot, sessionId);
203
+ if (current === null)
204
+ return;
205
+ if (current.tool !== null) {
206
+ const same = current.toolUseId !== null && ref.toolUseId !== null
207
+ ? current.toolUseId === ref.toolUseId
208
+ : current.tool === toolLabel(ref.tool);
209
+ if (!same)
210
+ return;
211
+ }
212
+ writeLiveStep(repoRoot, path, {
213
+ tool: null,
214
+ toolUseId: null,
215
+ startedAt: null,
216
+ endedAt: now,
217
+ turnStartedAt: current.turnStartedAt,
218
+ turnEndedAt: current.turnEndedAt,
219
+ lastTool: toolLabel(ref.tool) || current.lastTool,
220
+ });
221
+ }
222
+ /**
223
+ * End whatever step this session still shows, since no tool runs once Stop fires, and close the turn
224
+ * unless a Stop guard is sending the model back to work (`closeTurn` false).
225
+ */
226
+ export function endLiveStep(repoRoot, sessionId, now = Date.now(), closeTurn = true) {
227
+ const path = liveStepPath(repoRoot, sessionId);
228
+ const current = path === null ? null : readLiveStep(repoRoot, sessionId);
229
+ if (path === null || current === null)
230
+ return;
231
+ if (current.tool === null && (!closeTurn || current.turnEndedAt !== null))
232
+ return;
233
+ writeLiveStep(repoRoot, path, {
234
+ tool: null,
235
+ toolUseId: null,
236
+ startedAt: null,
237
+ endedAt: current.tool === null ? current.endedAt : now,
238
+ turnStartedAt: current.turnStartedAt,
239
+ turnEndedAt: closeTurn ? now : current.turnEndedAt,
240
+ lastTool: current.tool ?? current.lastTool,
241
+ });
242
+ }
243
+ /** `$CODEX_HOME`, else `$HOME/.codex`, read from the given environment only; null when neither is set. */
244
+ export function codexHomeFrom(env) {
245
+ const fromEnv = env["CODEX_HOME"]?.trim() ?? "";
246
+ if (fromEnv !== "" && isAbsolute(fromEnv))
247
+ return fromEnv;
248
+ const home = env["HOME"]?.trim() ?? "";
249
+ return home !== "" && isAbsolute(home) ? join(home, ".codex") : null;
250
+ }
251
+ export function threadPointerPath(env, threadId) {
252
+ const id = normalizeSessionId(threadId);
253
+ const home = codexHomeFrom(env);
254
+ if (id === null || home === null)
255
+ return null;
256
+ return join(home, POINTER_DIR, `${id}.json`);
257
+ }
258
+ export function readThreadPointer(env, threadId) {
259
+ const path = threadPointerPath(env, threadId);
260
+ const home = codexHomeFrom(env);
261
+ if (path === null || home === null || !plainDirs(home, POINTER_DIR))
262
+ return null;
263
+ const record = readSmallJson(path);
264
+ if (!isRecord(record) || record["version"] !== 1)
265
+ return null;
266
+ const { cwd, updatedAt, cardOfferedAt } = record;
267
+ if (typeof cwd !== "string" || !isAbsolute(cwd) || typeof updatedAt !== "number")
268
+ return null;
269
+ return { cwd, updatedAt, cardOfferedAt: typeof cardOfferedAt === "number" ? cardOfferedAt : null };
270
+ }
271
+ /** Point the thread at `cwd`; skips the write when the pointer already says so. */
272
+ export function writeThreadPointer(env, threadId, cwd, now = Date.now(), options = {}) {
273
+ const path = threadPointerPath(env, threadId);
274
+ const home = codexHomeFrom(env);
275
+ if (path === null || home === null || typeof cwd !== "string" || !isAbsolute(cwd))
276
+ return;
277
+ const current = readThreadPointer(env, threadId);
278
+ const cardOfferedAt = options.cardOffered === true ? now : (current?.cardOfferedAt ?? null);
279
+ if (current !== null && current.cwd === cwd && current.cardOfferedAt === cardOfferedAt)
280
+ return;
281
+ writeRecord(home, POINTER_DIR, basename(path), {
282
+ version: 1,
283
+ cwd,
284
+ updatedAt: now,
285
+ cardOfferedAt,
286
+ });
287
+ }
@@ -35,11 +35,41 @@ export declare function progressBar(done: number, total: number): string;
35
35
  */
36
36
  export declare function safeTitle(label: string): string | null;
37
37
  export declare function readWorkflowSignals(repoRoot: string, sessionId: string | null, now?: number): WorkflowSignals;
38
+ /** One stage of the map, as the text line and the LIT card both draw it. */
39
+ export interface MapCell {
40
+ readonly key: string;
41
+ readonly icon: string;
42
+ /** Lowercase stage word for the card. */
43
+ readonly word: string;
44
+ /** `done` ✓, `current` (named in capitals), `partial` (an earlier stage with an open bar) or `pending` ·. */
45
+ readonly state: "done" | "current" | "partial" | "pending";
46
+ /** What the current stage says in capitals; for a done research wave stage, how many waves ran. */
47
+ readonly label: string | null;
48
+ readonly progress: {
49
+ readonly done: number;
50
+ readonly total: number;
51
+ } | null;
52
+ }
53
+ export interface WorkflowMap {
54
+ readonly family: "main" | "research";
55
+ readonly cells: readonly MapCell[];
56
+ /** The next open task or goal title, cut the way the Stop line cuts it. */
57
+ readonly next: string | null;
58
+ }
59
+ /** The map as stages, or null when there is nothing true to draw. */
60
+ export declare function workflowMapCells(mode: string | null, signals: WorkflowSignals): WorkflowMap | null;
38
61
  /** One map line, or null when there is nothing true to draw. Plain text: emoji and block cells only. */
39
62
  export declare function renderWorkflowMap(mode: string | null, signals: WorkflowSignals): string | null;
63
+ /** The text line for a map already built. */
64
+ export declare function workflowMapText(map: WorkflowMap): string;
40
65
  export declare function workflowMapLine(repoRoot: string, sessionId: string | null, mode: string | null): string | null;
41
66
  /** Remember that this turn is a LIT activation and where its progress started. Never throws. */
42
67
  export declare function recordWorkflowTurn(repoRoot: string, sessionId: string, turnId: string, mode: string, now?: number): void;
68
+ /** The LIT activation this session last recorded: its skill and when it started; null when none. */
69
+ export declare function workflowTurn(repoRoot: string, sessionId: string): {
70
+ mode: string;
71
+ startedAt: number;
72
+ } | null;
43
73
  /**
44
74
  * The Stop line for a LIT turn, or null when this turn was not a LIT activation. At a start-work
45
75
  * checkpoint the continuation hook keeps the turn going, so the line says so instead of "turn done".