@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
@@ -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,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litfamily/litcodex",
3
- "version": "1.0.21",
3
+ "version": "1.0.23",
4
4
  "description": "Codex CLI plugin that turns a request into a goal with checks, keeps the evidence in your project and hands unfinished work to the next session.",
5
5
  "keywords": [
6
6
  "codex",
@@ -52,7 +52,7 @@
52
52
  "readme-assets"
53
53
  ],
54
54
  "dependencies": {
55
- "@litcodex/lit-loop": "1.0.21"
55
+ "@litcodex/lit-loop": "1.0.23"
56
56
  },
57
57
  "bundledDependencies": [
58
58
  "@litcodex/lit-loop"
@@ -1 +1 @@
1
- <svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.21"><title>release: 1.0.21</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.21</text></g></svg>
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.23"><title>release: 1.0.23</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.23</text></g></svg>