@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.
- package/README-Ko-KR.md +9 -9
- package/README.md +9 -9
- package/dist/install/doctor-render.js +5 -0
- package/dist/install/doctor.js +9 -0
- package/dist/install/types.d.ts +4 -0
- package/marketplace/plugins/litcodex/.codex-plugin/plugin.json +1 -1
- package/marketplace/plugins/litcodex/.mcp.json +9 -1
- package/marketplace/plugins/litcodex/components/auto-update/package.json +1 -1
- package/marketplace/plugins/litcodex/components/comment-checker/package.json +1 -1
- package/marketplace/plugins/litcodex/components/git-bash/package.json +1 -1
- package/marketplace/plugins/litcodex/components/lit-loop/dist/card-html.d.ts +1 -0
- package/marketplace/plugins/litcodex/components/lit-loop/dist/card-html.js +313 -0
- package/marketplace/plugins/litcodex/components/lit-loop/dist/card-mcp.d.ts +14 -0
- package/marketplace/plugins/litcodex/components/lit-loop/dist/card-mcp.js +141 -0
- package/marketplace/plugins/litcodex/components/lit-loop/dist/card-server.d.ts +2 -0
- package/marketplace/plugins/litcodex/components/lit-loop/dist/card-server.js +38 -0
- package/marketplace/plugins/litcodex/components/lit-loop/dist/card-status.d.ts +43 -0
- package/marketplace/plugins/litcodex/components/lit-loop/dist/card-status.js +363 -0
- package/marketplace/plugins/litcodex/components/lit-loop/dist/cli.js +5 -1
- package/marketplace/plugins/litcodex/components/lit-loop/dist/hook-cli.d.ts +14 -0
- package/marketplace/plugins/litcodex/components/lit-loop/dist/hook-cli.js +76 -2
- package/marketplace/plugins/litcodex/components/lit-loop/dist/live-step.d.ts +59 -0
- package/marketplace/plugins/litcodex/components/lit-loop/dist/live-step.js +287 -0
- package/marketplace/plugins/litcodex/components/lit-loop/dist/workflow-map.d.ts +30 -0
- package/marketplace/plugins/litcodex/components/lit-loop/dist/workflow-map.js +113 -45
- package/marketplace/plugins/litcodex/components/lit-loop/package.json +1 -1
- package/marketplace/plugins/litcodex/components/lsp/package.json +1 -1
- package/marketplace/plugins/litcodex/components/rules/package.json +1 -1
- package/marketplace/plugins/litcodex/components/start-work-continuation/package.json +1 -1
- package/marketplace/plugins/litcodex/components/telemetry/package.json +1 -1
- package/marketplace/plugins/litcodex/components/wikify-knowledge/package.json +1 -1
- package/marketplace/plugins/litcodex/hooks/hooks.json +20 -0
- package/node_modules/@litcodex/lit-loop/dist/card-html.d.ts +1 -0
- package/node_modules/@litcodex/lit-loop/dist/card-html.js +313 -0
- package/node_modules/@litcodex/lit-loop/dist/card-mcp.d.ts +14 -0
- package/node_modules/@litcodex/lit-loop/dist/card-mcp.js +141 -0
- package/node_modules/@litcodex/lit-loop/dist/card-server.d.ts +2 -0
- package/node_modules/@litcodex/lit-loop/dist/card-server.js +38 -0
- package/node_modules/@litcodex/lit-loop/dist/card-status.d.ts +43 -0
- package/node_modules/@litcodex/lit-loop/dist/card-status.js +363 -0
- package/node_modules/@litcodex/lit-loop/dist/cli.js +5 -1
- package/node_modules/@litcodex/lit-loop/dist/hook-cli.d.ts +14 -0
- package/node_modules/@litcodex/lit-loop/dist/hook-cli.js +76 -2
- package/node_modules/@litcodex/lit-loop/dist/live-step.d.ts +59 -0
- package/node_modules/@litcodex/lit-loop/dist/live-step.js +287 -0
- package/node_modules/@litcodex/lit-loop/dist/workflow-map.d.ts +30 -0
- package/node_modules/@litcodex/lit-loop/dist/workflow-map.js +113 -45
- package/node_modules/@litcodex/lit-loop/package.json +1 -1
- package/package.json +2 -2
- 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,
|
|
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
|
-
/**
|
|
47
|
-
|
|
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
|
-
|
|
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
|
|
286
|
-
|
|
287
|
-
|
|
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
|
-
|
|
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 ?
|
|
293
|
-
return
|
|
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
|
-
/**
|
|
296
|
-
export function
|
|
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
|
|
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(
|
|
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
|
-
|
|
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(
|
|
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(
|
|
367
|
+
cells.push(cell(stage, icon, "done", null, bar));
|
|
330
368
|
else if (work !== null)
|
|
331
|
-
cells.push(
|
|
369
|
+
cells.push(cell(stage, icon, "partial", null, bar));
|
|
332
370
|
}
|
|
333
371
|
else if (stage === "review" && work?.status === "completed") {
|
|
334
|
-
cells.push(
|
|
372
|
+
cells.push(cell(stage, icon, "done"));
|
|
335
373
|
}
|
|
336
374
|
});
|
|
337
|
-
return
|
|
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
|
-
|
|
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.
|
|
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,
|