@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,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".
@@ -5,8 +5,9 @@
5
5
  // and its plan checkboxes, lit-loop goals, the lit-plan activation record and the litresearch
6
6
  // journal. A stage with no saved signal is left out rather than guessed. Every read fails open.
7
7
  import { createHash } from "node:crypto";
8
- import { lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
9
- import { basename, isAbsolute, join } from "node:path";
8
+ import { lstatSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
9
+ import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
10
+ import { plainDirs, plainDirsOrMissing, writeFileAtomic } from "./live-step.js";
10
11
  import { LIT_LOOP_DIR, LIT_LOOP_GOALS, normalizeSessionId } from "./state-paths.js";
11
12
  const STAGES = [
12
13
  ["interview", "🧭", "INTERVIEW"],
@@ -43,20 +44,34 @@ const NO_STOP_CONTEXT = { stopHookActive: false, transcriptPath: null };
43
44
  function isRecord(value) {
44
45
  return typeof value === "object" && value !== null && !Array.isArray(value);
45
46
  }
46
- /** Parse a small regular file (never a symlink); null on any failure. */
47
- function readJson(path) {
47
+ /**
48
+ * True when `path` sits inside `repoRoot` with no symlinked folder between them, so a state read never
49
+ * leaves the workspace through a linked `.litcodex/plans` or similar.
50
+ */
51
+ function ownedPath(repoRoot, path) {
52
+ const rel = relative(repoRoot, dirname(path));
53
+ if (rel === "")
54
+ return true;
55
+ if (rel.startsWith("..") || isAbsolute(rel))
56
+ return false;
57
+ return plainDirs(repoRoot, rel.split(sep).join("/"));
58
+ }
59
+ /** Parse a small regular file (never a symlink, never behind a symlinked folder); null on any failure. */
60
+ function readJson(repoRoot, path) {
61
+ const text = readText(repoRoot, path);
62
+ if (text === null)
63
+ return null;
48
64
  try {
49
- const stat = lstatSync(path);
50
- if (!stat.isFile() || stat.size > MAX_STATE_BYTES)
51
- return null;
52
- return JSON.parse(readFileSync(path, "utf8"));
65
+ return JSON.parse(text);
53
66
  }
54
67
  catch {
55
68
  return null;
56
69
  }
57
70
  }
58
- function readText(path) {
71
+ function readText(repoRoot, path) {
59
72
  try {
73
+ if (!ownedPath(repoRoot, path))
74
+ return null;
60
75
  const stat = lstatSync(path);
61
76
  if (!stat.isFile() || stat.size > MAX_STATE_BYTES)
62
77
  return null;
@@ -158,7 +173,7 @@ export function safeTitle(label) {
158
173
  return cut < 0 ? title : `${title} …`;
159
174
  }
160
175
  function readWork(repoRoot, sessionId) {
161
- const state = readJson(join(repoRoot, ".litcodex/start-work/state.json"));
176
+ const state = readJson(repoRoot, join(repoRoot, ".litcodex/start-work/state.json"));
162
177
  if (!isRecord(state) || !isRecord(state["works"]))
163
178
  return null;
164
179
  const works = Object.values(state["works"]).filter(isRecord);
@@ -180,7 +195,7 @@ function readWork(repoRoot, sessionId) {
180
195
  const file = basename(work["active_plan"]);
181
196
  if (!file.endsWith(".md"))
182
197
  return null;
183
- const text = readText(join(repoRoot, ".litcodex/plans", file));
198
+ const text = readText(repoRoot, join(repoRoot, ".litcodex/plans", file));
184
199
  if (text === null)
185
200
  return null;
186
201
  const rows = countPlanRows(text);
@@ -188,8 +203,8 @@ function readWork(repoRoot, sessionId) {
188
203
  return null;
189
204
  return { ...rows, status: work["status"] };
190
205
  }
191
- function goalProgress(path) {
192
- const plan = readJson(path);
206
+ function goalProgress(repoRoot, path) {
207
+ const plan = readJson(repoRoot, path);
193
208
  if (!isRecord(plan) || !Array.isArray(plan["goals"]))
194
209
  return null;
195
210
  const goals = plan["goals"].filter(isRecord);
@@ -204,17 +219,17 @@ function goalProgress(path) {
204
219
  }
205
220
  function readGoals(repoRoot, sessionId) {
206
221
  if (sessionId !== null) {
207
- const scoped = goalProgress(join(repoRoot, LIT_LOOP_DIR, sessionId, LIT_LOOP_GOALS));
222
+ const scoped = goalProgress(repoRoot, join(repoRoot, LIT_LOOP_DIR, sessionId, LIT_LOOP_GOALS));
208
223
  if (scoped !== null)
209
224
  return scoped;
210
225
  }
211
- const shared = goalProgress(join(repoRoot, LIT_LOOP_DIR, LIT_LOOP_GOALS));
226
+ const shared = goalProgress(repoRoot, join(repoRoot, LIT_LOOP_DIR, LIT_LOOP_GOALS));
212
227
  return shared !== null && shared.done < shared.total ? shared : null;
213
228
  }
214
229
  function readPlanRecord(repoRoot, sessionId) {
215
230
  if (sessionId === null)
216
231
  return null;
217
- const record = readJson(join(repoRoot, ".litcodex/lit-plan", `${sessionId}.json`));
232
+ const record = readJson(repoRoot, join(repoRoot, ".litcodex/lit-plan", `${sessionId}.json`));
218
233
  if (!isRecord(record) || typeof record["satisfied"] !== "boolean")
219
234
  return null;
220
235
  return record["satisfied"] ? "published" : "drafting";
@@ -222,6 +237,8 @@ function readPlanRecord(repoRoot, sessionId) {
222
237
  /** The newest research journal by its last write, with the names of the files in it. */
223
238
  function newestJournal(repoRoot) {
224
239
  const root = join(repoRoot, RESEARCH_DIR);
240
+ if (!plainDirs(repoRoot, RESEARCH_DIR))
241
+ return null;
225
242
  try {
226
243
  let newest = null;
227
244
  for (const name of readdirSync(root)) {
@@ -281,60 +298,105 @@ function stageFromState(signals) {
281
298
  return { index: 2, active: false };
282
299
  return null;
283
300
  }
301
+ function cell(key, icon, state, label = null, progress = null, word = key) {
302
+ return { key, icon, word, state, label, progress };
303
+ }
284
304
  /** The research family: decompose › waves (the first, then expansion) › verify › synthesis. */
285
- function researchMap(research) {
286
- if (research === null || (research.wave === null && !research.verifying))
287
- return "🔎 DECOMPOSE › 🌊 · › 🔬 · › 🏁 ·";
305
+ function researchCells(research) {
306
+ const pending = (key, icon) => cell(key, icon, "pending");
307
+ if (research === null || (research.wave === null && !research.verifying)) {
308
+ return [
309
+ cell("decompose", "🔎", "current", "DECOMPOSE"),
310
+ pending("wave", "🌊"),
311
+ pending("verify", "🔬"),
312
+ pending("synthesis", "🏁"),
313
+ ];
314
+ }
288
315
  const { wave } = research;
289
316
  if (!research.verifying) {
290
- return `🔎 ✓ › 🌊 WAVE ${wave}${wave !== null && wave > 1 ? " EXPAND" : ""} › 🔬 · › 🏁 ·`;
317
+ const label = `WAVE ${wave}${wave !== null && wave > 1 ? " EXPAND" : ""}`;
318
+ return [
319
+ cell("decompose", "🔎", "done"),
320
+ cell("wave", "🌊", "current", label),
321
+ pending("verify", "🔬"),
322
+ pending("synthesis", "🏁"),
323
+ ];
291
324
  }
292
- const waves = wave === null ? "" : ` › 🌊 ✓ ${wave} wave${wave === 1 ? "" : "s"}`;
293
- return `🔎 ✓${waves} › 🔬 VERIFY › 🏁 ·`;
325
+ const waves = wave === null ? [] : [cell("wave", "🌊", "done", `${wave} wave${wave === 1 ? "" : "s"}`)];
326
+ return [
327
+ cell("decompose", "🔎", "done"),
328
+ ...waves,
329
+ cell("verify", "🔬", "current", "VERIFY"),
330
+ pending("synthesis", "🏁"),
331
+ ];
294
332
  }
295
- /** One map line, or null when there is nothing true to draw. Plain text: emoji and block cells only. */
296
- export function renderWorkflowMap(mode, signals) {
333
+ /** The map as stages, or null when there is nothing true to draw. */
334
+ export function workflowMapCells(mode, signals) {
297
335
  const fromMode = mode === null ? undefined : MODE_STAGE[mode];
336
+ const { work } = signals;
337
+ const progress = work ?? signals.goals;
338
+ const next = progress === null || progress.next === null ? null : safeTitle(progress.next);
298
339
  if (fromMode === "research")
299
- return researchMap(signals.research);
340
+ return { family: "research", cells: researchCells(signals.research), next: null };
300
341
  const position = fromMode === undefined
301
342
  ? stageFromState(signals)
302
343
  : { index: STAGES.findIndex(([stage]) => stage === fromMode), active: true };
303
344
  if (position === null)
304
345
  return null;
305
- const { work } = signals;
306
- const progress = work ?? signals.goals;
307
346
  const planKnown = work !== null || signals.plan === "published";
308
347
  const workFinished = work !== null && (work.status === "completed" || work.done === work.total);
309
348
  const cells = [];
310
349
  STAGES.forEach(([stage, icon, label], index) => {
311
350
  if (index > position.index || (index === position.index && !position.active)) {
312
- cells.push(`${icon} ·`);
351
+ cells.push(cell(stage, icon, "pending"));
313
352
  return;
314
353
  }
315
354
  if (index === position.index) {
316
355
  const name = stage === "work" && work?.status === "paused" ? "PAUSED" : label;
317
- const bar = stage === "work" && progress !== null
318
- ? ` ${progressBar(progress.done, progress.total)} ${progress.done}/${progress.total}`
319
- : "";
320
- cells.push(`${icon} ${name}${bar}`);
356
+ const bar = stage === "work" && progress !== null ? { done: progress.done, total: progress.total } : null;
357
+ cells.push(cell(stage, icon, "current", name, bar));
321
358
  return;
322
359
  }
323
360
  if (stage === "interview" || stage === "plan") {
324
361
  if (planKnown)
325
- cells.push(`${icon} ✓`);
362
+ cells.push(cell(stage, icon, "done"));
326
363
  }
327
364
  else if (stage === "work") {
365
+ const bar = work === null ? null : { done: work.done, total: work.total };
328
366
  if (workFinished)
329
- cells.push(`${icon} ✓`);
367
+ cells.push(cell(stage, icon, "done", null, bar));
330
368
  else if (work !== null)
331
- cells.push(`${icon} ${progressBar(work.done, work.total)} ${work.done}/${work.total}`);
369
+ cells.push(cell(stage, icon, "partial", null, bar));
332
370
  }
333
371
  else if (stage === "review" && work?.status === "completed") {
334
- cells.push(`${icon} ✓`);
372
+ cells.push(cell(stage, icon, "done"));
335
373
  }
336
374
  });
337
- return cells.join(" › ");
375
+ return { family: "main", cells, next };
376
+ }
377
+ function cellText(item) {
378
+ const bar = item.progress === null
379
+ ? ""
380
+ : `${progressBar(item.progress.done, item.progress.total)} ${item.progress.done}/${item.progress.total}`;
381
+ switch (item.state) {
382
+ case "pending":
383
+ return `${item.icon} ·`;
384
+ case "done":
385
+ return item.label === null ? `${item.icon} ✓` : `${item.icon} ✓ ${item.label}`;
386
+ case "partial":
387
+ return `${item.icon} ${bar}`;
388
+ case "current":
389
+ return `${item.icon} ${item.label ?? item.word.toUpperCase()}${bar === "" ? "" : ` ${bar}`}`;
390
+ }
391
+ }
392
+ /** One map line, or null when there is nothing true to draw. Plain text: emoji and block cells only. */
393
+ export function renderWorkflowMap(mode, signals) {
394
+ const map = workflowMapCells(mode, signals);
395
+ return map === null ? null : workflowMapText(map);
396
+ }
397
+ /** The text line for a map already built. */
398
+ export function workflowMapText(map) {
399
+ return map.cells.map(cellText).join(" › ");
338
400
  }
339
401
  export function workflowMapLine(repoRoot, sessionId, mode) {
340
402
  return renderWorkflowMap(mode, readWorkflowSignals(repoRoot, sessionId));
@@ -360,17 +422,17 @@ export function recordWorkflowTurn(repoRoot, sessionId, turnId, mode, now = Date
360
422
  goalsDone: signals.goals?.done ?? null,
361
423
  };
362
424
  try {
425
+ if (!plainDirsOrMissing(repoRoot, TURN_DIR))
426
+ return;
363
427
  mkdirSync(join(repoRoot, TURN_DIR), { recursive: true });
364
- const tmp = `${path}.${process.pid}.tmp`;
365
- writeFileSync(tmp, `${JSON.stringify(record)}\n`);
366
- renameSync(tmp, path);
428
+ writeFileAtomic(path, `${JSON.stringify(record)}\n`);
367
429
  }
368
430
  catch {
369
431
  // Without the record the Stop hook simply stays quiet for this turn.
370
432
  }
371
433
  }
372
- function readTurn(path) {
373
- const record = readJson(path);
434
+ function readTurn(repoRoot, path) {
435
+ const record = readJson(repoRoot, path);
374
436
  if (!isRecord(record) ||
375
437
  record["version"] !== 1 ||
376
438
  typeof record["turnId"] !== "string" ||
@@ -387,6 +449,12 @@ function readTurn(path) {
387
449
  goalsDone: count(record["goalsDone"]),
388
450
  };
389
451
  }
452
+ /** The LIT activation this session last recorded: its skill and when it started; null when none. */
453
+ export function workflowTurn(repoRoot, sessionId) {
454
+ const path = turnPath(repoRoot, sessionId);
455
+ const turn = path === null ? null : readTurn(repoRoot, path);
456
+ return turn === null ? null : { mode: turn.mode, startedAt: turn.startedAt };
457
+ }
390
458
  /** Highest wave number in the newest research journal written since `since`, or null. */
391
459
  function researchWave(repoRoot, since) {
392
460
  const journal = newestJournal(repoRoot);
@@ -429,7 +497,7 @@ function transcriptClear(path) {
429
497
  function continuingWork(repoRoot, sessionId, turnId, stop) {
430
498
  if (stop.stopHookActive || !transcriptClear(stop.transcriptPath))
431
499
  return null;
432
- const state = readJson(join(repoRoot, ".litcodex/start-work/state.json"));
500
+ const state = readJson(repoRoot, join(repoRoot, ".litcodex/start-work/state.json"));
433
501
  if (!isRecord(state) || !isRecord(state["works"]) || typeof state["active_work_id"] !== "string")
434
502
  return null;
435
503
  const owner = `codex:${sessionId}`;
@@ -446,7 +514,7 @@ function continuingWork(repoRoot, sessionId, turnId, stop) {
446
514
  if (!isRecord(work["authority"]) || typeof plan !== "string" || !/^\.litcodex\/plans\/[^/\\]+\.md$/u.test(plan)) {
447
515
  return null;
448
516
  }
449
- const text = readText(join(repoRoot, plan));
517
+ const text = readText(repoRoot, join(repoRoot, plan));
450
518
  if (text === null)
451
519
  return null;
452
520
  const rows = planRows(text);
@@ -473,7 +541,7 @@ export function workflowStopLine(repoRoot, sessionId, turnId, stop = NO_STOP_CON
473
541
  const path = turnPath(repoRoot, sessionId);
474
542
  if (path === null)
475
543
  return null;
476
- const turn = readTurn(path);
544
+ const turn = readTurn(repoRoot, path);
477
545
  if (turn === null || turn.turnId !== turnId)
478
546
  return null;
479
547
  const continuing = continuingWork(repoRoot, sessionId, turnId, stop);
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/lit-loop",
3
- "version": "1.0.21",
3
+ "version": "1.0.23",
4
4
  "description": "LitCodex Lit-Loop runtime: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/lsp",
3
- "version": "1.0.21",
3
+ "version": "1.0.23",
4
4
  "description": "LitCodex LSP hook (inert placeholder): post-edit diagnostics + cache reset, no-op until an LSP daemon is provided.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/rules",
3
- "version": "1.0.21",
3
+ "version": "1.0.23",
4
4
  "description": "LitCodex rules: injects project rule files (AGENTS.md etc.) into model context through lifecycle hooks.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/start-work-continuation",
3
- "version": "1.0.21",
3
+ "version": "1.0.23",
4
4
  "description": "LitCodex Start-Work continuation hook: resumes in-flight start-work state on root Stop.",
5
5
  "type": "module",
6
6
  "private": true,