@litfamily/litcodex 1.0.33 → 1.0.34

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 (53) hide show
  1. package/README-Ko-KR.md +9 -9
  2. package/README.md +9 -9
  3. package/dist/cli.js +63 -0
  4. package/dist/install/agent-file/apply.d.ts +35 -0
  5. package/dist/install/agent-file/apply.js +141 -0
  6. package/dist/install/agent-file/attribution.d.ts +15 -0
  7. package/dist/install/agent-file/attribution.js +54 -0
  8. package/dist/install/agent-file/bodies.d.ts +14 -0
  9. package/dist/install/agent-file/bodies.js +40 -0
  10. package/dist/install/agent-file/cli.d.ts +70 -0
  11. package/dist/install/agent-file/cli.js +174 -0
  12. package/dist/install/agent-file/managed-block.d.ts +28 -0
  13. package/dist/install/agent-file/managed-block.js +103 -0
  14. package/dist/install/agent-file/mode.d.ts +13 -0
  15. package/dist/install/agent-file/mode.js +52 -0
  16. package/dist/install/doctor-render.js +2 -0
  17. package/dist/install/doctor.js +20 -0
  18. package/dist/install/generated-skill-payload-hashes.d.ts +4 -4
  19. package/dist/install/generated-skill-payload-hashes.js +4 -4
  20. package/dist/install/index.js +48 -6
  21. package/dist/install/install-options.js +2 -0
  22. package/dist/install/types.d.ts +5 -0
  23. package/dist/install/uninstall.js +1 -0
  24. package/marketplace/plugins/litcodex/.codex-plugin/plugin.json +1 -1
  25. package/marketplace/plugins/litcodex/components/auto-update/package.json +1 -1
  26. package/marketplace/plugins/litcodex/components/comment-checker/package.json +1 -1
  27. package/marketplace/plugins/litcodex/components/git-bash/package.json +1 -1
  28. package/marketplace/plugins/litcodex/components/lit-loop/dist/herdr-agents.d.ts +18 -0
  29. package/marketplace/plugins/litcodex/components/lit-loop/dist/herdr-agents.js +63 -0
  30. package/marketplace/plugins/litcodex/components/lit-loop/dist/rewind-go.js +19 -2
  31. package/marketplace/plugins/litcodex/components/lit-loop/dist/rewind.d.ts +21 -2
  32. package/marketplace/plugins/litcodex/components/lit-loop/dist/rewind.js +169 -13
  33. package/marketplace/plugins/litcodex/components/lit-loop/package.json +1 -1
  34. package/marketplace/plugins/litcodex/components/lsp/package.json +1 -1
  35. package/marketplace/plugins/litcodex/components/rules/package.json +1 -1
  36. package/marketplace/plugins/litcodex/components/start-work-continuation/dist/lifecycle-store.js +21 -2
  37. package/marketplace/plugins/litcodex/components/start-work-continuation/package.json +1 -1
  38. package/marketplace/plugins/litcodex/components/telemetry/package.json +1 -1
  39. package/marketplace/plugins/litcodex/components/wikify-knowledge/package.json +1 -1
  40. package/marketplace/plugins/litcodex/skills/lit-adhd/SKILL.md +9 -6
  41. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/runtime/requirements-audio.txt +92 -89
  42. package/marketplace/plugins/litcodex/skills/readme-studio/templates/hyperframes-cover/package-lock.json +4 -4
  43. package/marketplace/plugins/litcodex/skills/readme-studio/templates/remotion-cover/package-lock.json +3 -3
  44. package/marketplace/plugins/litcodex/skills/readme-studio/templates/remotion-cover/package.json +3 -0
  45. package/node_modules/@litcodex/lit-loop/dist/herdr-agents.d.ts +18 -0
  46. package/node_modules/@litcodex/lit-loop/dist/herdr-agents.js +63 -0
  47. package/node_modules/@litcodex/lit-loop/dist/rewind-go.js +19 -2
  48. package/node_modules/@litcodex/lit-loop/dist/rewind.d.ts +21 -2
  49. package/node_modules/@litcodex/lit-loop/dist/rewind.js +169 -13
  50. package/node_modules/@litcodex/lit-loop/package.json +1 -1
  51. package/node_modules/@litcodex/lit-loop/skills/lit-adhd/SKILL.md +9 -6
  52. package/package.json +2 -2
  53. package/readme-assets/badge-version.svg +1 -1
package/README-Ko-KR.md CHANGED
@@ -1,12 +1,12 @@
1
- <p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.33/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.33/readme-assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 일곱 머신의 칸이 차례로 켜지고, 셋째 칸의 LitCodex 머신이 주황 바이저와 테두리를 밝힌 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
1
+ <p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.34/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.34/readme-assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 일곱 머신의 칸이 차례로 켜지고, 셋째 칸의 LitCodex 머신이 주황 바이저와 테두리를 밝힌 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
2
2
 
3
3
  <p align="center">
4
- <a href="#설치"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.33/readme-assets/badge-version.svg" alt="1.0.33" /></a>
5
- <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.33/readme-assets/badge-license.svg" alt="MIT license" /></a>
4
+ <a href="#설치"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.34/readme-assets/badge-version.svg" alt="1.0.34" /></a>
5
+ <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.34/readme-assets/badge-license.svg" alt="MIT license" /></a>
6
6
  </p>
7
7
 
8
8
  <p align="center">
9
- <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage-Ko-KR.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.33/readme-assets/lucide-book-open.svg" width="16" alt="" /> 문서</a> &nbsp; <a href="#설치">설치</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.33/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.33/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
9
+ <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage-Ko-KR.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.34/readme-assets/lucide-book-open.svg" width="16" alt="" /> 문서</a> &nbsp; <a href="#설치">설치</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.34/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.34/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
10
10
  </p>
11
11
 
12
12
  # LitCodex
@@ -23,12 +23,12 @@
23
23
  Node.js 22 이상과 Codex CLI가 필요합니다.
24
24
 
25
25
  ```sh
26
- npm exec --yes --package @litfamily/litcodex@1.0.33 -- litcodex install
26
+ npm exec --yes --package @litfamily/litcodex@1.0.34 -- litcodex install
27
27
  ```
28
28
 
29
29
  설치기는 어떤 모델이 이끌지, 어떤 모델이 거들지, 답변 스타일은 무엇으로 할지 묻고, 쓰려는 내용을 먼저 보여 준 뒤
30
30
  `~/.codex/config.toml`에서 자기가 관리하는 항목만 고칩니다. 계획만 먼저 보려면
31
- `npm exec --yes --package @litfamily/litcodex@1.0.33 -- litcodex --dry-run install`을 실행하고, 묻는 단계 없이
31
+ `npm exec --yes --package @litfamily/litcodex@1.0.34 -- litcodex --dry-run install`을 실행하고, 묻는 단계 없이
32
32
  설치하려면 `install` 뒤에 `--yes`를 붙이세요.
33
33
 
34
34
  ```sh
@@ -39,7 +39,7 @@ litcodex install
39
39
  전역으로 설치하면 영상 스킬이 쓸 도구를 미리 준비하느라 버전이 고정된 파일 몇 개를 내려받습니다. 무엇을 받는지와
40
40
  건너뛰는 방법은 [설치 안내](https://github.com/wjgoarxiv/litcodex/blob/main/docs/install-Ko-KR.md#전역-명령으로-쓰기)에 있습니다.
41
41
 
42
- > 전역 설치가 없다면 `npm exec --yes --package @litfamily/litcodex@1.0.33 -- litcodex <command>` 형식을 사용하세요.
42
+ > 전역 설치가 없다면 `npm exec --yes --package @litfamily/litcodex@1.0.34 -- litcodex <command>` 형식을 사용하세요.
43
43
 
44
44
  ## 첫 작업
45
45
 
@@ -91,7 +91,7 @@ lit 회원가입 폼에 입력 검증을 추가해줘
91
91
  ## 확인, 문제 해결, 제거
92
92
 
93
93
  ```sh
94
- npm exec --yes --package @litfamily/litcodex@1.0.33 -- litcodex doctor
94
+ npm exec --yes --package @litfamily/litcodex@1.0.34 -- litcodex doctor
95
95
  ```
96
96
 
97
97
  `litcodex doctor`는 등록·훅·설정·호스트 기능을, `litcodex loop doctor`는 현재 프로젝트의 루프 상태를 확인합니다.
@@ -99,7 +99,7 @@ npm exec --yes --package @litfamily/litcodex@1.0.33 -- litcodex doctor
99
99
  [문제 해결](https://github.com/wjgoarxiv/litcodex/blob/main/README-Ko-KR.md#문제-해결)에 있습니다.
100
100
 
101
101
  ```sh
102
- npm exec --yes --package @litfamily/litcodex@1.0.33 -- litcodex uninstall
102
+ npm exec --yes --package @litfamily/litcodex@1.0.34 -- litcodex uninstall
103
103
  ```
104
104
 
105
105
  플러그인과 LitCodex가 관리하는 설정을 지우고, 관련 없는 설정은 그대로 둡니다.
package/README.md CHANGED
@@ -1,12 +1,12 @@
1
- <p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.33/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.33/readme-assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: seven armored machines power on bay by bay, the LitCodex machine in the third bay wakes with a glowing orange visor and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
1
+ <p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.34/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.34/readme-assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: seven armored machines power on bay by bay, the LitCodex machine in the third bay wakes with a glowing orange visor and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
2
2
 
3
3
  <p align="center">
4
- <a href="#install"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.33/readme-assets/badge-version.svg" alt="1.0.33" /></a>
5
- <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.33/readme-assets/badge-license.svg" alt="MIT license" /></a>
4
+ <a href="#install"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.34/readme-assets/badge-version.svg" alt="1.0.34" /></a>
5
+ <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.34/readme-assets/badge-license.svg" alt="MIT license" /></a>
6
6
  </p>
7
7
 
8
8
  <p align="center">
9
- <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.33/readme-assets/lucide-book-open.svg" width="16" alt="" /> Docs</a> &nbsp; <a href="#install">Install</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.33/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.33/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
9
+ <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.34/readme-assets/lucide-book-open.svg" width="16" alt="" /> Docs</a> &nbsp; <a href="#install">Install</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.34/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.34/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
10
10
  </p>
11
11
 
12
12
  # LitCodex
@@ -24,12 +24,12 @@ today's stopped.
24
24
  You need Node.js 22 or later and Codex CLI.
25
25
 
26
26
  ```sh
27
- npm exec --yes --package @litfamily/litcodex@1.0.33 -- litcodex install
27
+ npm exec --yes --package @litfamily/litcodex@1.0.34 -- litcodex install
28
28
  ```
29
29
 
30
30
  The installer asks which model leads, which model helps and which output style you like, shows what it is
31
31
  about to write, and changes only the keys it manages in `~/.codex/config.toml`. To see the plan first, run
32
- `npm exec --yes --package @litfamily/litcodex@1.0.33 -- litcodex --dry-run install`. To skip the
32
+ `npm exec --yes --package @litfamily/litcodex@1.0.34 -- litcodex --dry-run install`. To skip the
33
33
  questions, add `--yes` after `install`.
34
34
 
35
35
  ```sh
@@ -41,7 +41,7 @@ A global install also gets the video skill's tools ready with a few pinned downl
41
41
  [install guide](https://github.com/wjgoarxiv/litcodex/blob/main/docs/install.md#a-global-command) lists them
42
42
  and shows how to skip them.
43
43
 
44
- > Without a global install, use `npm exec --yes --package @litfamily/litcodex@1.0.33 -- litcodex <command>`.
44
+ > Without a global install, use `npm exec --yes --package @litfamily/litcodex@1.0.34 -- litcodex <command>`.
45
45
 
46
46
  ## First task
47
47
 
@@ -97,7 +97,7 @@ rather have neither, set `LITCODEX_NO_UPDATE_CHECK=1`. A doctor run that failed,
97
97
  ## Check, fix, remove
98
98
 
99
99
  ```sh
100
- npm exec --yes --package @litfamily/litcodex@1.0.33 -- litcodex doctor
100
+ npm exec --yes --package @litfamily/litcodex@1.0.34 -- litcodex doctor
101
101
  ```
102
102
 
103
103
  `litcodex doctor` checks registration, hooks, config and host capabilities; `litcodex loop doctor` checks
@@ -105,7 +105,7 @@ the current project's loop state. If `lit` does nothing, run doctor and check th
105
105
  in Codex. More fixes are under [troubleshooting](https://github.com/wjgoarxiv/litcodex#troubleshooting).
106
106
 
107
107
  ```sh
108
- npm exec --yes --package @litfamily/litcodex@1.0.33 -- litcodex uninstall
108
+ npm exec --yes --package @litfamily/litcodex@1.0.34 -- litcodex uninstall
109
109
  ```
110
110
 
111
111
  This removes the plugin and the config LitCodex manages, and leaves your other settings alone.
package/dist/cli.js CHANGED
@@ -6,6 +6,7 @@ import { runForegroundAutoUpdate } from "./auto-update.js";
6
6
  import { readEffortChoice, readLeadModelChoice, readModelChoice, readSubagentEffortChoice, readSubagentModelChoice, } from "./cli-model-route.js";
7
7
  import { acceptedModelIds, FALLBACK_CATALOG } from "./config-migration/catalog.js";
8
8
  import { runConfigMigrateCli } from "./config-migration/cli.js";
9
+ import { runAgentFileProjectCli, runConfigAgentFileCli, runConfigAttributionCli } from "./install/agent-file/cli.js";
9
10
  import { resolveCodexHome } from "./install/codex.js";
10
11
  import { renderDryRunPlan, runDoctorCli, runInstallCli, runUninstallCli } from "./install/index.js";
11
12
  import { managedMarketplaceRoot } from "./install/marketplace.js";
@@ -34,6 +35,7 @@ function renderInstallDryRun(rest) {
34
35
  force: rest.includes("--force"),
35
36
  json: rest.includes("--json"),
36
37
  yes: rest.includes("--yes"),
38
+ noAgentFile: rest.includes("--no-agent-file"),
37
39
  profile: readModelChoice(rest),
38
40
  leadModel: readLeadModelChoice(rest),
39
41
  effort: readEffortChoice(rest),
@@ -55,6 +57,16 @@ const ROUTES = {
55
57
  install: (rest, dryRun) => (dryRun ? ok(renderInstallDryRun(rest)) : ok("litcodex install\n")),
56
58
  doctor: () => ok("litcodex doctor\n"),
57
59
  uninstall: () => ok("litcodex uninstall\n"),
60
+ "agent-file": (rest) => {
61
+ if (rest[0] === "--help" || rest[0] === "-h" || rest[0] === "project") {
62
+ return ok("litcodex agent-file project [--dir <path>]\n");
63
+ }
64
+ return {
65
+ stdout: "",
66
+ stderr: "Usage: litcodex agent-file project [--dir <path>]\n",
67
+ exitCode: 64,
68
+ };
69
+ },
58
70
  "office-runtime": (rest) => rest[0] === "install" || rest[0] === "status"
59
71
  ? ok(`litcodex office-runtime ${rest[0]}\n`)
60
72
  : { stdout: "", stderr: "Usage: litcodex office-runtime install|status\n", exitCode: 64 },
@@ -85,6 +97,12 @@ function configRouteHandler(rest) {
85
97
  if (rest[0] === "migrate") {
86
98
  return ok("");
87
99
  }
100
+ if (rest[0] === "agentFile" && rest.length === 2 && (rest[1] === "on" || rest[1] === "off")) {
101
+ return ok("");
102
+ }
103
+ if (rest[0] === "attribution" && rest.length === 2 && (rest[1] === "keep" || rest[1] === "off")) {
104
+ return ok("");
105
+ }
88
106
  const sub = rest[0] ?? "<none>";
89
107
  return {
90
108
  stdout: "",
@@ -106,6 +124,9 @@ function renderHelp() {
106
124
  " Typographic-motion engine adapted from mexicat/pdoom-video (MIT, Giacomo Magnanini), commit `ca251e3`.",
107
125
  " litcodex uninstall Remove LitCodex from Codex",
108
126
  " litcodex config migrate Migrate Codex config for LitCodex",
127
+ " litcodex config agentFile on|off Add or remove the LitFamily block in the global AGENTS.md",
128
+ " litcodex config attribution keep|off Ask the model not to add AI attribution to commits and PRs (a request, not a guarantee)",
129
+ " litcodex agent-file project [--dir <path>] Add the LitFamily block to a repo AGENTS.md",
109
130
  " litcodex loop <sub> Run a Lit-Loop subcommand",
110
131
  " litcodex hud [--session <id>] [--once] Watch the LIT card live from a second terminal window",
111
132
  " litcodex screen-status on|off|status Colour the LIT card; terminal `codex` only (off by default)",
@@ -122,6 +143,7 @@ function renderHelp() {
122
143
  ` --subagent-model <${modelIds}> Select the helper route (default: ${FALLBACK_CATALOG.roles["default"]?.model ?? FALLBACK_CATALOG.current.model})`,
123
144
  " --subagent-effort <low|medium|high|xhigh|max|ultra> Select helper effort (catalog validated)",
124
145
  " --yes Keep defaults; never prompt",
146
+ " --no-agent-file Skip the global AGENTS.md block for this run",
125
147
  " --reconfigure Explicitly apply the choice to the root model/effort",
126
148
  " --no-auto-update Skip the foreground update barrier for this command",
127
149
  "",
@@ -230,6 +252,47 @@ export async function runCli(rawArgv) {
230
252
  writeCliBanner(passthrough);
231
253
  return runConfigMigrateCli(passthrough);
232
254
  }
255
+ if (head === "config" && rest[1] === "agentFile") {
256
+ if (dryRun) {
257
+ return writeDryRun(`litcodex config agentFile ${rest[2] ?? ""}`.trimEnd(), [
258
+ `${rest[2] === "off" ? "Remove" : "Write"} the LitFamily block in the global AGENTS.md (dry run: writes no file)`,
259
+ ]);
260
+ }
261
+ return runConfigAgentFileCli(rest.slice(2), {
262
+ env: process.env,
263
+ out: process.stdout,
264
+ err: process.stderr,
265
+ codexHome: resolveCodexHome(process.env),
266
+ version: manifest.version,
267
+ });
268
+ }
269
+ if (head === "config" && rest[1] === "attribution") {
270
+ if (dryRun) {
271
+ return writeDryRun(`litcodex config attribution ${rest[2] ?? ""}`.trimEnd(), [
272
+ `${rest[2] === "off" ? "Add" : "Remove"} the attribution request line in the LitFamily block of the global AGENTS.md (dry run: writes no file)`,
273
+ ]);
274
+ }
275
+ return runConfigAttributionCli(rest.slice(2), {
276
+ env: process.env,
277
+ out: process.stdout,
278
+ err: process.stderr,
279
+ codexHome: resolveCodexHome(process.env),
280
+ version: manifest.version,
281
+ });
282
+ }
283
+ if (head === "agent-file") {
284
+ if (dryRun) {
285
+ return writeDryRun("litcodex agent-file project", [
286
+ "Write the LitFamily project block into <dir>/AGENTS.md (no backup; a mistyped --dir is never created)",
287
+ ]);
288
+ }
289
+ return runAgentFileProjectCli(rest.slice(1), {
290
+ cwd: process.cwd(),
291
+ out: process.stdout,
292
+ err: process.stderr,
293
+ version: manifest.version,
294
+ });
295
+ }
233
296
  if (head === "install") {
234
297
  // Preserve position-independent --dry-run: pass the args after `install`, re-injecting
235
298
  // --dry-run (which `rest` already stripped) so the flag survives regardless of position.
@@ -0,0 +1,35 @@
1
+ /** What `applyInstructionFile` can report about one install/uninstall attempt. */
2
+ export type InstructionFileStatus = "created" | "updated" | "unchanged" | "removed" | "absent" | "dry-run" | "refused-symlink" | "refused-not-file" | "refused-not-utf8" | "refused-malformed" | "refused-io";
3
+ /** Outcome of one install/uninstall attempt against `path`. */
4
+ export interface InstructionFileResult {
5
+ readonly status: InstructionFileStatus;
6
+ readonly path: string;
7
+ readonly backup?: string;
8
+ readonly preview?: string;
9
+ readonly error?: string;
10
+ }
11
+ /**
12
+ * Installs or removes the section in `path`. `backup: false` skips the first-insert
13
+ * copy (a repo's `AGENTS.md`, where a copy would sit beside tracked files);
14
+ * `createParent: false` never makes the folder.
15
+ */
16
+ export declare const applyInstructionFile: (options: {
17
+ path: string;
18
+ id: string;
19
+ version: string;
20
+ body: string;
21
+ action: "install" | "uninstall";
22
+ dryRun?: boolean;
23
+ now?: Date;
24
+ backup?: boolean;
25
+ createParent?: boolean;
26
+ }) => InstructionFileResult;
27
+ /**
28
+ * `present v=<x>` (current), `stale v=<x>` (an older install's section), `absent`,
29
+ * `malformed`, or `symlink` / `not-file` / `not-utf8` for a file LitCodex will not write.
30
+ */
31
+ export declare const instructionFileState: (options: {
32
+ path: string;
33
+ id: string;
34
+ version: string;
35
+ }) => string;
@@ -0,0 +1,141 @@
1
+ // The LitFamily section on disk: the global `$CODEX_HOME/AGENTS.md` Codex reads on
2
+ // every session start. Writes go through a staging file and rename, keep the file's
3
+ // mode, and refuse a symlinked, non-regular or non-UTF-8 file rather than rewriting it.
4
+ // A filesystem failure comes back as `refused-io` instead of throwing. The user's
5
+ // original file is copied once, the first time a section goes in.
6
+ import { randomUUID } from "node:crypto";
7
+ import { chmodSync, copyFileSync, lstatSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
8
+ import { dirname } from "node:path";
9
+ import { AgentBlockError, inspectInstructionBlock, removeInstructionBlock, upsertInstructionBlock, } from "./managed-block.js";
10
+ // "missing", "file", "symlink" or "other", without following a link.
11
+ const entryKind = (path) => {
12
+ try {
13
+ const stats = lstatSync(path);
14
+ return stats.isSymbolicLink() ? "symlink" : stats.isFile() ? "file" : "other";
15
+ }
16
+ catch (error) {
17
+ if (error.code === "ENOENT")
18
+ return "missing";
19
+ throw error;
20
+ }
21
+ };
22
+ // The file's text, or null when it is not UTF-8: a UTF-16 file from Notepad or a
23
+ // Latin-1 file would be corrupted if rewritten outside the markers.
24
+ const readUtf8 = (path) => {
25
+ const bytes = readFileSync(path);
26
+ if (bytes.includes(0) || (bytes[0] === 0xff && bytes[1] === 0xfe) || (bytes[0] === 0xfe && bytes[1] === 0xff)) {
27
+ return null;
28
+ }
29
+ try {
30
+ return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
31
+ }
32
+ catch {
33
+ return null;
34
+ }
35
+ };
36
+ // A unique staging name, so a leftover from a crashed run never blocks the next one.
37
+ const writeAtomic = (path, text, createParent) => {
38
+ if (createParent)
39
+ mkdirSync(dirname(path), { recursive: true });
40
+ const staging = `${path}.litfamily-${randomUUID()}.tmp`;
41
+ let mode = null;
42
+ try {
43
+ mode = statSync(path).mode & 0o7777;
44
+ }
45
+ catch {
46
+ // A new file takes the default mode.
47
+ }
48
+ try {
49
+ writeFileSync(staging, text, { flag: "wx" });
50
+ if (mode !== null)
51
+ chmodSync(staging, mode);
52
+ renameSync(staging, path);
53
+ }
54
+ finally {
55
+ try {
56
+ unlinkSync(staging);
57
+ }
58
+ catch {
59
+ // Renamed into place, or never written.
60
+ }
61
+ }
62
+ };
63
+ /**
64
+ * Installs or removes the section in `path`. `backup: false` skips the first-insert
65
+ * copy (a repo's `AGENTS.md`, where a copy would sit beside tracked files);
66
+ * `createParent: false` never makes the folder.
67
+ */
68
+ export const applyInstructionFile = (options) => {
69
+ const { path, id, version, body, action } = options;
70
+ const dryRun = options.dryRun ?? false;
71
+ const now = options.now ?? new Date();
72
+ const backup = options.backup ?? true;
73
+ const createParent = options.createParent ?? true;
74
+ try {
75
+ const kind = entryKind(path);
76
+ if (kind === "symlink")
77
+ return { status: "refused-symlink", path };
78
+ if (kind === "other")
79
+ return { status: "refused-not-file", path };
80
+ const text = kind === "file" ? readUtf8(path) : "";
81
+ if (text === null)
82
+ return { status: "refused-not-utf8", path };
83
+ let next;
84
+ try {
85
+ next =
86
+ action === "uninstall"
87
+ ? removeInstructionBlock(text, id)
88
+ : {
89
+ ...upsertInstructionBlock(text, { id, version, body }, { created: kind === "missing" }),
90
+ created: kind === "missing",
91
+ };
92
+ }
93
+ catch (error) {
94
+ if (error instanceof AgentBlockError)
95
+ return { status: "refused-malformed", path };
96
+ throw error;
97
+ }
98
+ if (!next.changed)
99
+ return { status: action === "uninstall" ? "absent" : "unchanged", path };
100
+ if (dryRun)
101
+ return { status: "dry-run", path, preview: next.text };
102
+ if (action === "uninstall") {
103
+ if (next.text === "" && next.created)
104
+ unlinkSync(path);
105
+ else
106
+ writeAtomic(path, next.text, false);
107
+ return { status: "removed", path };
108
+ }
109
+ let copy;
110
+ if (backup && kind === "file" && inspectInstructionBlock(text, id).state === "absent") {
111
+ copy = `${path}.litfamily-backup-${now.toISOString().replace(/[:.]/gu, "-")}`;
112
+ copyFileSync(path, copy);
113
+ }
114
+ writeAtomic(path, next.text, createParent);
115
+ return { status: kind === "file" ? "updated" : "created", path, ...(copy ? { backup: copy } : {}) };
116
+ }
117
+ catch (error) {
118
+ return { status: "refused-io", path, error: error?.code ?? String(error) };
119
+ }
120
+ };
121
+ /**
122
+ * `present v=<x>` (current), `stale v=<x>` (an older install's section), `absent`,
123
+ * `malformed`, or `symlink` / `not-file` / `not-utf8` for a file LitCodex will not write.
124
+ */
125
+ export const instructionFileState = (options) => {
126
+ const { path, id, version } = options;
127
+ const kind = entryKind(path);
128
+ if (kind === "missing")
129
+ return "absent";
130
+ if (kind === "symlink")
131
+ return "symlink";
132
+ if (kind === "other")
133
+ return "not-file";
134
+ const text = readUtf8(path);
135
+ if (text === null)
136
+ return "not-utf8";
137
+ const found = inspectInstructionBlock(text, id);
138
+ if (found.state !== "present")
139
+ return found.state;
140
+ return `${found.version === version ? "present" : "stale"} v=${found.version}`;
141
+ };
@@ -0,0 +1,15 @@
1
+ export declare const ATTRIBUTION_MODES: readonly ["keep", "off"];
2
+ export type AttributionMode = (typeof ATTRIBUTION_MODES)[number];
3
+ export declare const ATTRIBUTION_LINE: "- Do not add `Co-Authored-By` lines or other AI attribution to commits or pull requests.";
4
+ /** Where the choice is stored for one Codex home. */
5
+ export declare const attributionPath: (codexHome: string) => string;
6
+ /** The stored choice, or undefined when the user never made one (or the file is unreadable). */
7
+ export declare const storedAttributionMode: (codexHome: string) => AttributionMode | undefined;
8
+ export declare const readAttributionMode: (options: {
9
+ env: NodeJS.ProcessEnv;
10
+ codexHome: string;
11
+ }) => AttributionMode;
12
+ /** Stores the choice. Throws when the file exists but is unreadable, so a broken file is never overwritten. */
13
+ export declare const writeAttributionMode: (codexHome: string, mode: AttributionMode) => void;
14
+ /** Uninstall: forget the choice, so a later install starts from `keep` again. */
15
+ export declare const clearAttributionMode: (codexHome: string) => void;
@@ -0,0 +1,54 @@
1
+ // The attribution switch for the LitFamily block. `keep` (the default) changes nothing; `off` adds one
2
+ // line asking the model not to add AI attribution to commits or pull requests. It never touches
3
+ // config.toml: Codex decides its own co-author trailer from an account setting, so the line is a
4
+ // request, not a guarantee. The choice is stored beside the other LitCodex state under the Codex home;
5
+ // `LITCODEX_ATTRIBUTION` overrides it.
6
+ import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
7
+ import { dirname, join } from "node:path";
8
+ export const ATTRIBUTION_MODES = Object.freeze(["keep", "off"]);
9
+ export const ATTRIBUTION_LINE = "- Do not add `Co-Authored-By` lines or other AI attribution to commits or pull requests.";
10
+ const isMode = (value) => ATTRIBUTION_MODES.includes(value);
11
+ /** Where the choice is stored for one Codex home. */
12
+ export const attributionPath = (codexHome) => join(codexHome, "litcodex", "attribution.json");
13
+ /** The stored choice, or undefined when the user never made one (or the file is unreadable). */
14
+ export const storedAttributionMode = (codexHome) => {
15
+ try {
16
+ const stored = JSON.parse(readFileSync(attributionPath(codexHome), "utf8"))["attribution"];
17
+ return isMode(stored) ? stored : undefined;
18
+ }
19
+ catch {
20
+ return undefined;
21
+ }
22
+ };
23
+ export const readAttributionMode = (options) => {
24
+ const override = String(options.env["LITCODEX_ATTRIBUTION"] ?? "")
25
+ .trim()
26
+ .toLowerCase();
27
+ if (isMode(override))
28
+ return override;
29
+ return storedAttributionMode(options.codexHome) ?? "keep";
30
+ };
31
+ /** Stores the choice. Throws when the file exists but is unreadable, so a broken file is never overwritten. */
32
+ export const writeAttributionMode = (codexHome, mode) => {
33
+ if (!isMode(mode))
34
+ throw new Error(`attribution takes one of: ${ATTRIBUTION_MODES.join(", ")}`);
35
+ const path = attributionPath(codexHome);
36
+ try {
37
+ const stored = JSON.parse(readFileSync(path, "utf8"))["attribution"];
38
+ if (!isMode(stored))
39
+ throw new Error(`unreadable attribution state in ${path}`);
40
+ if (stored === mode)
41
+ return;
42
+ }
43
+ catch (error) {
44
+ if (error.code !== "ENOENT") {
45
+ throw error instanceof SyntaxError ? new Error(`unreadable attribution state in ${path}`) : error;
46
+ }
47
+ }
48
+ mkdirSync(dirname(path), { recursive: true });
49
+ writeFileSync(path, `${JSON.stringify({ attribution: mode })}\n`);
50
+ };
51
+ /** Uninstall: forget the choice, so a later install starts from `keep` again. */
52
+ export const clearAttributionMode = (codexHome) => {
53
+ rmSync(attributionPath(codexHome), { force: true });
54
+ };
@@ -0,0 +1,14 @@
1
+ import { type AttributionMode } from "./attribution.js";
2
+ /** Marker id for the LitCodex section. */
3
+ export declare const AGENT_FILE_ID: "litcodex";
4
+ /** Install modes for the section. */
5
+ export declare const AGENT_FILE_MODES: readonly ["on", "off"];
6
+ export type AgentFileMode = (typeof AGENT_FILE_MODES)[number];
7
+ /** The global section stays small enough to be read on every turn of every session. */
8
+ export declare const AGENT_FILE_MAX_BYTES: 1200;
9
+ /** The section for the global `$CODEX_HOME/AGENTS.md`. */
10
+ export declare const globalBody: (options?: {
11
+ attribution?: AttributionMode;
12
+ }) => string;
13
+ /** The section for a repo's `AGENTS.md`, written by `litcodex agent-file project`. */
14
+ export declare const projectBody: () => string;
@@ -0,0 +1,40 @@
1
+ // Shipped LitFamily section texts for the Codex global file and for project repos.
2
+ // The global text is read on every session start, so it stays short and points at the
3
+ // project's own docs for everything else. Both name only LitCodex and its host.
4
+ import { ATTRIBUTION_LINE } from "./attribution.js";
5
+ /** Marker id for the LitCodex section. */
6
+ export const AGENT_FILE_ID = "litcodex";
7
+ /** Install modes for the section. */
8
+ export const AGENT_FILE_MODES = Object.freeze(["on", "off"]);
9
+ /** The global section stays small enough to be read on every turn of every session. */
10
+ export const AGENT_FILE_MAX_BYTES = 1200;
11
+ /** The section for the global `$CODEX_HOME/AGENTS.md`. */
12
+ export const globalBody = (options = {}) => [
13
+ "## LitFamily · LitCodex",
14
+ "",
15
+ "LitCodex brings the lit workflows to Codex CLI (lit-loop, start-work, lit-plan, review-work, lit-adhd,",
16
+ "litresearch). Codex reads this file at the start of every session, so this block only sets the ground rules.",
17
+ "",
18
+ "- `lit` at the start of a prompt is LitCodex's activation word, not the Lit web library.",
19
+ "- Plans live in `plans/`, the session handoff in `HANDOFF.md`, run state in `.litcodex/`. Read them",
20
+ " before resuming work in a repo.",
21
+ "- Never push, publish, tag or bump a version without the user's explicit yes for that action.",
22
+ "- Call work done only after its tests pass and the changed surface was checked for real.",
23
+ "- In a new repo, `lit-init` writes a short project `AGENTS.md` with these conventions.",
24
+ ...(options.attribution === "off" ? [ATTRIBUTION_LINE] : []),
25
+ "- Turn this block off with `litcodex config agentFile off`.",
26
+ "",
27
+ ].join("\n");
28
+ /** The section for a repo's `AGENTS.md`, written by `litcodex agent-file project`. */
29
+ export const projectBody = () => [
30
+ "## LitFamily · project conventions",
31
+ "",
32
+ "This repo is worked with LitCodex's lit workflows (lit-loop, start-work, lit-plan, review-work).",
33
+ "",
34
+ "- Plans live in `plans/`, the session handoff in `HANDOFF.md`, run state in `.litcodex/` (keep it out",
35
+ " of commits). Read the handoff and the active plan before resuming.",
36
+ "- Never push, publish, tag or bump a version without the user's explicit yes for that action.",
37
+ "- Pair every behaviour change with a test that failed first, and check the changed surface for real",
38
+ " before calling it done.",
39
+ "",
40
+ ].join("\n");
@@ -0,0 +1,70 @@
1
+ import { type AttributionMode } from "./attribution.js";
2
+ /** One `AGENT_FILE:` status line for an apply result. */
3
+ export declare const agentFileLine: (result: {
4
+ status: string;
5
+ path: string;
6
+ backup?: string;
7
+ }) => string;
8
+ /** The global instruction file for one Codex home. */
9
+ export declare const agentFilePath: (codexHome: string) => string;
10
+ /** The question an interactive install asks before touching the global file. */
11
+ export declare const AGENT_FILE_QUESTION = "Add the short LitFamily block to your global AGENTS.md? Your own text stays as it is. [Y/n] ";
12
+ /** The one extra question an interactive install asks once, right after the block is accepted. */
13
+ export declare const ATTRIBUTION_QUESTION = "Also add one line asking the model not to add AI attribution to commits or pull requests? [y/N] ";
14
+ /** What a dry run says about the section instead of writing it. */
15
+ export declare const agentFileDryRunLine: (codexHome: string) => string;
16
+ /**
17
+ * `litcodex agent-file project [--dir <path>]`: the project section in the repo's
18
+ * `AGENTS.md`. No backup copy here: in a repo it would sit untracked beside
19
+ * `AGENTS.md` and could be committed. A mistyped `--dir` is never created.
20
+ */
21
+ export declare const runAgentFileProjectCli: (rest: readonly string[], deps: {
22
+ cwd: string;
23
+ out: NodeJS.WritableStream;
24
+ err: NodeJS.WritableStream;
25
+ version: string;
26
+ }) => number;
27
+ /** Writes or refreshes the global section; returns the printed `AGENT_FILE:` line. */
28
+ export declare const writeGlobalAgentFile: (codexHome: string, version: string, attribution?: AttributionMode) => string;
29
+ /** Removes the global section; returns the printed `AGENT_FILE:` line. */
30
+ export declare const removeGlobalAgentFile: (codexHome: string, version: string) => string;
31
+ /**
32
+ * The install-time consent step. `--yes` writes; the skip flag and the stored `off`
33
+ * mode leave the file alone; without a prompt a non-interactive install only says how
34
+ * to add the section, and never stores a mode. The caller passes `prompt` only for a
35
+ * genuinely interactive install (TTY, not `--no-tui`/`--json`, no CI).
36
+ */
37
+ export declare const runInstallAgentFile: (options: {
38
+ env: NodeJS.ProcessEnv;
39
+ stdout: NodeJS.WritableStream;
40
+ codexHome: string;
41
+ version: string;
42
+ yes: boolean;
43
+ noAgentFile: boolean;
44
+ dryRun: boolean;
45
+ /** Machine-readable install: return the line for the JSON report, write nothing to stdout. */
46
+ json?: boolean;
47
+ prompt?: () => Promise<boolean>;
48
+ /** Asked once, only after the block is accepted and no attribution choice is stored yet. */
49
+ attributionPrompt?: () => Promise<boolean>;
50
+ }) => Promise<string>;
51
+ /** `litcodex config agentFile <on|off>`: the switch acts at once on the global file. */
52
+ export declare const runConfigAgentFileCli: (rest: readonly string[], deps: {
53
+ env: NodeJS.ProcessEnv;
54
+ out: NodeJS.WritableStream;
55
+ err: NodeJS.WritableStream;
56
+ codexHome: string;
57
+ version: string;
58
+ }) => number;
59
+ /**
60
+ * `litcodex config attribution <keep|off>`. `off` stores the choice and, when the block is already in the
61
+ * global AGENTS.md, adds the request line to it; `keep` takes the line out again. Nothing here writes
62
+ * config.toml, and the output says why the line cannot be a guarantee.
63
+ */
64
+ export declare const runConfigAttributionCli: (rest: readonly string[], deps: {
65
+ env: NodeJS.ProcessEnv;
66
+ out: NodeJS.WritableStream;
67
+ err: NodeJS.WritableStream;
68
+ codexHome: string;
69
+ version: string;
70
+ }) => number;