@litfamily/litcodex 1.0.32 → 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
@@ -0,0 +1,174 @@
1
+ // `litcodex agent-file` routes: the project section writer, the install-time consent
2
+ // step, and the `config agentFile` switch. None of them spawns a child process.
3
+ import { statSync } from "node:fs";
4
+ import { join, resolve } from "node:path";
5
+ import { applyInstructionFile, instructionFileState } from "./apply.js";
6
+ import { ATTRIBUTION_MODES, readAttributionMode, storedAttributionMode, writeAttributionMode, } from "./attribution.js";
7
+ import { AGENT_FILE_ID, AGENT_FILE_MODES, globalBody, projectBody } from "./bodies.js";
8
+ import { readAgentFileMode, writeAgentFileMode } from "./mode.js";
9
+ /** One `AGENT_FILE:` status line for an apply result. */
10
+ export const agentFileLine = (result) => `AGENT_FILE: ${result.status} ${result.path}${result.backup ? ` (backup: ${result.backup})` : ""}`;
11
+ /** The global instruction file for one Codex home. */
12
+ export const agentFilePath = (codexHome) => join(codexHome, "AGENTS.md");
13
+ /** The question an interactive install asks before touching the global file. */
14
+ export const AGENT_FILE_QUESTION = "Add the short LitFamily block to your global AGENTS.md? Your own text stays as it is. [Y/n] ";
15
+ /** The one extra question an interactive install asks once, right after the block is accepted. */
16
+ export const ATTRIBUTION_QUESTION = "Also add one line asking the model not to add AI attribution to commits or pull requests? [y/N] ";
17
+ /** What a dry run says about the section instead of writing it. */
18
+ export const agentFileDryRunLine = (codexHome) => `Would add the LitFamily block to ${agentFilePath(codexHome)} (asks first; --yes adds it, --no-agent-file skips)`;
19
+ /**
20
+ * `litcodex agent-file project [--dir <path>]`: the project section in the repo's
21
+ * `AGENTS.md`. No backup copy here: in a repo it would sit untracked beside
22
+ * `AGENTS.md` and could be committed. A mistyped `--dir` is never created.
23
+ */
24
+ export const runAgentFileProjectCli = (rest, deps) => {
25
+ const [sub, ...args] = rest;
26
+ if (sub === "--help" || sub === "-h") {
27
+ deps.out.write("Usage: litcodex agent-file project [--dir <path>]\n");
28
+ return 0;
29
+ }
30
+ if (sub !== "project") {
31
+ deps.err.write("Usage: litcodex agent-file project [--dir <path>]\n");
32
+ return 64;
33
+ }
34
+ let dir = deps.cwd;
35
+ for (let index = 0; index < args.length; index += 1) {
36
+ if (args[index] === "--dir" && args[index + 1]) {
37
+ dir = resolve(deps.cwd, args[index + 1]);
38
+ index += 1;
39
+ continue;
40
+ }
41
+ deps.err.write(`Unknown agent-file option: ${args[index]}\n`);
42
+ return 64;
43
+ }
44
+ let isDirectory = false;
45
+ try {
46
+ isDirectory = statSync(dir).isDirectory();
47
+ }
48
+ catch {
49
+ // Missing: reported below, never created.
50
+ }
51
+ if (!isDirectory) {
52
+ deps.err.write(`agent-file: ${dir} is not an existing folder\n`);
53
+ return 64;
54
+ }
55
+ const agents = applyInstructionFile({
56
+ path: join(dir, "AGENTS.md"),
57
+ id: AGENT_FILE_ID,
58
+ version: deps.version,
59
+ body: projectBody(),
60
+ action: "install",
61
+ backup: false,
62
+ createParent: false,
63
+ });
64
+ deps.out.write(`${agentFileLine(agents)}\n`);
65
+ return agents.status.startsWith("refused") ? 1 : 0;
66
+ };
67
+ /** Writes or refreshes the global section; returns the printed `AGENT_FILE:` line. */
68
+ export const writeGlobalAgentFile = (codexHome, version, attribution = "keep") => agentFileLine(applyInstructionFile({
69
+ path: agentFilePath(codexHome),
70
+ id: AGENT_FILE_ID,
71
+ version,
72
+ body: globalBody({ attribution }),
73
+ action: "install",
74
+ }));
75
+ /** Removes the global section; returns the printed `AGENT_FILE:` line. */
76
+ export const removeGlobalAgentFile = (codexHome, version) => agentFileLine(applyInstructionFile({
77
+ path: agentFilePath(codexHome),
78
+ id: AGENT_FILE_ID,
79
+ version,
80
+ body: globalBody(),
81
+ action: "uninstall",
82
+ }));
83
+ /**
84
+ * The install-time consent step. `--yes` writes; the skip flag and the stored `off`
85
+ * mode leave the file alone; without a prompt a non-interactive install only says how
86
+ * to add the section, and never stores a mode. The caller passes `prompt` only for a
87
+ * genuinely interactive install (TTY, not `--no-tui`/`--json`, no CI).
88
+ */
89
+ export const runInstallAgentFile = async (options) => {
90
+ const say = (line) => {
91
+ if (options.json !== true)
92
+ options.stdout.write(`${line}\n`);
93
+ return line;
94
+ };
95
+ const path = agentFilePath(options.codexHome);
96
+ if (options.noAgentFile || readAgentFileMode({ env: options.env, codexHome: options.codexHome }) === "off") {
97
+ return say(`AGENT_FILE: off (${path} left as it is; turn on: litcodex config agentFile on)`);
98
+ }
99
+ const state = instructionFileState({ path, id: AGENT_FILE_ID, version: options.version });
100
+ if (state === "symlink" || state === "not-file" || state === "not-utf8") {
101
+ return say(`AGENT_FILE: ${state} ${path}; left as it is`);
102
+ }
103
+ if (options.dryRun)
104
+ return say(agentFileDryRunLine(options.codexHome));
105
+ const attribution = () => readAttributionMode({ env: options.env, codexHome: options.codexHome });
106
+ if (options.yes)
107
+ return say(writeGlobalAgentFile(options.codexHome, options.version, attribution()));
108
+ if (options.prompt === undefined) {
109
+ return say(`AGENT_FILE: skipped (add the LitFamily block to ${path}: litcodex config agentFile on)`);
110
+ }
111
+ const confirmed = await options.prompt();
112
+ if (!confirmed) {
113
+ writeAgentFileMode(options.codexHome, "off");
114
+ return say("AGENT_FILE: off (turn on later: litcodex config agentFile on)");
115
+ }
116
+ if (options.attributionPrompt !== undefined && storedAttributionMode(options.codexHome) === undefined) {
117
+ writeAttributionMode(options.codexHome, (await options.attributionPrompt()) ? "off" : "keep");
118
+ }
119
+ return say(writeGlobalAgentFile(options.codexHome, options.version, attribution()));
120
+ };
121
+ /** `litcodex config agentFile <on|off>`: the switch acts at once on the global file. */
122
+ export const runConfigAgentFileCli = (rest, deps) => {
123
+ const [mode] = rest;
124
+ if (!AGENT_FILE_MODES.includes(mode) || rest.length !== 1) {
125
+ deps.err.write(`litcodex config agentFile: unknown subcommand "${rest[0] ?? "<none>"}". Usage: litcodex config agentFile <on|off>\n`);
126
+ return 64;
127
+ }
128
+ try {
129
+ writeAgentFileMode(deps.codexHome, mode);
130
+ }
131
+ catch (error) {
132
+ deps.err.write(`litcodex config agentFile: ${error.message}\n`);
133
+ return 3;
134
+ }
135
+ const line = mode === "off"
136
+ ? removeGlobalAgentFile(deps.codexHome, deps.version)
137
+ : writeGlobalAgentFile(deps.codexHome, deps.version, readAttributionMode({ env: deps.env, codexHome: deps.codexHome }));
138
+ deps.out.write(`agentFile ${mode.padEnd(5)} (${AGENT_FILE_MODES.join(", ")})\n`);
139
+ deps.out.write(`${line}\n`);
140
+ return 0;
141
+ };
142
+ /**
143
+ * `litcodex config attribution <keep|off>`. `off` stores the choice and, when the block is already in the
144
+ * global AGENTS.md, adds the request line to it; `keep` takes the line out again. Nothing here writes
145
+ * config.toml, and the output says why the line cannot be a guarantee.
146
+ */
147
+ export const runConfigAttributionCli = (rest, deps) => {
148
+ const [mode] = rest;
149
+ if (!ATTRIBUTION_MODES.includes(mode) || rest.length !== 1) {
150
+ deps.err.write(`litcodex config attribution: unknown subcommand "${rest[0] ?? "<none>"}". Usage: litcodex config attribution <keep|off>\n`);
151
+ return 64;
152
+ }
153
+ try {
154
+ writeAttributionMode(deps.codexHome, mode);
155
+ }
156
+ catch (error) {
157
+ deps.err.write(`litcodex config attribution: ${error.message}\n`);
158
+ return 3;
159
+ }
160
+ deps.out.write(`attribution ${mode.padEnd(5)} (${ATTRIBUTION_MODES.join(", ")})\n`);
161
+ const state = instructionFileState({
162
+ path: agentFilePath(deps.codexHome),
163
+ id: AGENT_FILE_ID,
164
+ version: deps.version,
165
+ });
166
+ if (state.startsWith("present") || state.startsWith("stale")) {
167
+ deps.out.write(`${writeGlobalAgentFile(deps.codexHome, deps.version, readAttributionMode({ env: deps.env, codexHome: deps.codexHome }))}\n`);
168
+ }
169
+ else {
170
+ deps.out.write(`The global AGENTS.md has no LitFamily block (${state}), so the line is applied the next time the LitFamily block is written (litcodex config agentFile on).\n`);
171
+ }
172
+ deps.out.write("Codex adds its own Co-authored-by trailer and pull request line from an account setting in your ChatGPT settings, not from config.toml, and LitCodex never writes config.toml for this. The line in the block is a request to the model, not a guarantee.\n");
173
+ return 0;
174
+ };
@@ -0,0 +1,28 @@
1
+ /** Thrown when a marker pair cannot be located unambiguously. */
2
+ export declare class AgentBlockError extends Error {
3
+ }
4
+ /** The text handed to the block writer: marker id, recorded version, section body. */
5
+ export interface InstructionBlock {
6
+ readonly id: string;
7
+ readonly version: string;
8
+ readonly body: string;
9
+ }
10
+ /** `{state: "absent" | "present" | "malformed", version, created}` for block `id` in `text`. */
11
+ export declare const inspectInstructionBlock: (text: string, id: string) => {
12
+ state: "absent" | "present" | "malformed";
13
+ version: string | null;
14
+ created: boolean;
15
+ };
16
+ /** Adds or replaces block `id`; `created` marks a file made for the block. */
17
+ export declare const upsertInstructionBlock: (text: string, block: InstructionBlock, options?: {
18
+ created?: boolean;
19
+ }) => {
20
+ text: string;
21
+ changed: boolean;
22
+ };
23
+ /** Takes block `id` back out with the line ending after it and what was added before it. */
24
+ export declare const removeInstructionBlock: (text: string, id: string) => {
25
+ text: string;
26
+ changed: boolean;
27
+ created: boolean;
28
+ };
@@ -0,0 +1,103 @@
1
+ // The LitFamily section inside a user-owned instruction file: the lines between
2
+ // `<!-- litfamily:<id>:start v=<version> ... -->` and `<!-- litfamily:<id>:end -->`.
3
+ // Only those lines are ever rewritten; the user's own text before and after them is
4
+ // kept byte for byte. The start marker remembers what was put in front of the
5
+ // section (`pre=`, hex) and whether the file was created for it (`new=1`), so taking
6
+ // the section back out returns the exact original bytes whatever the line endings.
7
+ // A start without its end, or a doubled marker, is malformed: reported, never guessed.
8
+ /** Thrown when a marker pair cannot be located unambiguously. */
9
+ export class AgentBlockError extends Error {
10
+ }
11
+ const startHead = (id) => `<!-- litfamily:${id}:start`;
12
+ const endLine = (id) => `<!-- litfamily:${id}:end -->`;
13
+ const lineEndingOf = (text) => (text.includes("\r\n") ? "\r\n" : "\n");
14
+ const START_PATTERN = /^<!-- litfamily:[^:\s]+:start v=(\S+)((?: [a-z]+=[0-9a-f]*)*) -->/u;
15
+ const positions = (text, needle) => {
16
+ const found = [];
17
+ for (let at = text.indexOf(needle); at !== -1; at = text.indexOf(needle, at + needle.length)) {
18
+ found.push(at);
19
+ }
20
+ return found;
21
+ };
22
+ // The section span `[start, end)`, end just past the end marker, plus recorded attributes.
23
+ const locate = (text, id) => {
24
+ const starts = positions(text, startHead(id));
25
+ const ends = positions(text, endLine(id));
26
+ if (starts.length === 0 && ends.length === 0)
27
+ return null;
28
+ const firstStart = starts[0];
29
+ const firstEnd = ends[0];
30
+ if (starts.length !== 1 ||
31
+ ends.length !== 1 ||
32
+ firstStart === undefined ||
33
+ firstEnd === undefined ||
34
+ firstEnd < firstStart) {
35
+ throw new AgentBlockError(`malformed LitFamily ${id} block: expected one start and one end marker`);
36
+ }
37
+ const head = START_PATTERN.exec(text.slice(firstStart));
38
+ const version = head?.[1];
39
+ if (!head || version === undefined) {
40
+ throw new AgentBlockError(`malformed LitFamily ${id} block: unreadable start marker`);
41
+ }
42
+ const attrs = Object.fromEntries((head[2] ?? "")
43
+ .trim()
44
+ .split(" ")
45
+ .filter(Boolean)
46
+ .map((pair) => pair.split("=")));
47
+ const pre = typeof attrs["pre"] === "string" && attrs["pre"] ? Buffer.from(attrs["pre"], "hex").toString("utf8") : "";
48
+ return {
49
+ start: firstStart,
50
+ end: firstEnd + endLine(id).length,
51
+ version,
52
+ pre,
53
+ created: attrs["new"] === "1",
54
+ };
55
+ };
56
+ const render = (block, eol, meta) => [
57
+ `${startHead(block.id)} v=${block.version}${meta.pre ? ` pre=${Buffer.from(meta.pre, "utf8").toString("hex")}` : ""}${meta.created ? " new=1" : ""} -->`,
58
+ ...String(block.body)
59
+ .replace(/\r?\n$/u, "")
60
+ .split(/\r?\n/u),
61
+ endLine(block.id),
62
+ ].join(eol);
63
+ /** `{state: "absent" | "present" | "malformed", version, created}` for block `id` in `text`. */
64
+ export const inspectInstructionBlock = (text, id) => {
65
+ let span;
66
+ try {
67
+ span = locate(text, id);
68
+ }
69
+ catch {
70
+ return { state: "malformed", version: null, created: false };
71
+ }
72
+ return span
73
+ ? { state: "present", version: span.version, created: span.created }
74
+ : { state: "absent", version: null, created: false };
75
+ };
76
+ /** Adds or replaces block `id`; `created` marks a file made for the block. */
77
+ export const upsertInstructionBlock = (text, block, options = {}) => {
78
+ const eol = lineEndingOf(text);
79
+ const span = locate(text, block.id);
80
+ if (span) {
81
+ const rendered = render(block, eol, span);
82
+ const next = `${text.slice(0, span.start)}${rendered}${text.slice(span.end)}`;
83
+ return { text: next, changed: next !== text };
84
+ }
85
+ const pre = text === "" ? "" : `${text.endsWith("\n") ? "" : eol}${eol}`;
86
+ return {
87
+ text: `${text}${pre}${render(block, eol, { pre, created: options.created ?? false })}${eol}`,
88
+ changed: true,
89
+ };
90
+ };
91
+ /** Takes block `id` back out with the line ending after it and what was added before it. */
92
+ export const removeInstructionBlock = (text, id) => {
93
+ const span = locate(text, id);
94
+ if (!span)
95
+ return { text, changed: false, created: false };
96
+ let before = text.slice(0, span.start);
97
+ let after = text.slice(span.end);
98
+ const eol = after.startsWith("\r\n") ? "\r\n" : after.startsWith("\n") ? "\n" : "";
99
+ after = after.slice(eol.length);
100
+ if (span.pre && before.endsWith(span.pre))
101
+ before = before.slice(0, -span.pre.length);
102
+ return { text: `${before}${after}`, changed: true, created: span.created };
103
+ };
@@ -0,0 +1,13 @@
1
+ import { type AgentFileMode } from "./bodies.js";
2
+ /** Where the mode is stored for one Codex home. */
3
+ export declare const agentFileModePath: (codexHome: string) => string;
4
+ /** Reads the stored mode; missing, unreadable or unknown content means `on`. */
5
+ export declare const readAgentFileMode: (options: {
6
+ env: NodeJS.ProcessEnv;
7
+ codexHome: string;
8
+ }) => AgentFileMode;
9
+ /**
10
+ * Stores the mode. Throws when the stored file exists but is unreadable, so a
11
+ * broken file is never silently overwritten.
12
+ */
13
+ export declare const writeAgentFileMode: (codexHome: string, mode: AgentFileMode) => void;
@@ -0,0 +1,52 @@
1
+ // The stored on/off switch for the LitFamily section. The mode lives beside the
2
+ // other LitCodex state under the resolved Codex home, so temp-home tests and the
3
+ // real-surface probe never touch a real profile. `LITCODEX_AGENT_FILE` overrides it.
4
+ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
5
+ import { dirname, join } from "node:path";
6
+ import { AGENT_FILE_MODES } from "./bodies.js";
7
+ /** Where the mode is stored for one Codex home. */
8
+ export const agentFileModePath = (codexHome) => join(codexHome, "litcodex", "agent-file.json");
9
+ /** Reads the stored mode; missing, unreadable or unknown content means `on`. */
10
+ export const readAgentFileMode = (options) => {
11
+ const override = String(options.env["LITCODEX_AGENT_FILE"] ?? "")
12
+ .trim()
13
+ .toLowerCase();
14
+ if (AGENT_FILE_MODES.includes(override))
15
+ return override;
16
+ try {
17
+ const stored = JSON.parse(readFileSync(agentFileModePath(options.codexHome), "utf8"))["agentFile"];
18
+ return AGENT_FILE_MODES.includes(stored) ? stored : "on";
19
+ }
20
+ catch {
21
+ return "on";
22
+ }
23
+ };
24
+ /**
25
+ * Stores the mode. Throws when the stored file exists but is unreadable, so a
26
+ * broken file is never silently overwritten.
27
+ */
28
+ export const writeAgentFileMode = (codexHome, mode) => {
29
+ if (!AGENT_FILE_MODES.includes(mode)) {
30
+ throw new Error(`agentFile takes one of: ${AGENT_FILE_MODES.join(", ")}`);
31
+ }
32
+ const path = agentFileModePath(codexHome);
33
+ try {
34
+ const raw = readFileSync(path, "utf8");
35
+ const stored = JSON.parse(raw)["agentFile"];
36
+ if (!AGENT_FILE_MODES.includes(stored)) {
37
+ throw new Error(`unreadable agent-file mode in ${path}`);
38
+ }
39
+ if (stored === mode)
40
+ return;
41
+ }
42
+ catch (error) {
43
+ if (error.code === "ENOENT") {
44
+ mkdirSync(dirname(path), { recursive: true });
45
+ writeFileSync(path, `${JSON.stringify({ agentFile: mode })}\n`);
46
+ return;
47
+ }
48
+ throw error instanceof SyntaxError ? new Error(`unreadable agent-file mode in ${path}`) : error;
49
+ }
50
+ mkdirSync(dirname(path), { recursive: true });
51
+ writeFileSync(path, `${JSON.stringify({ agentFile: mode })}\n`);
52
+ };
@@ -11,6 +11,8 @@ export function renderDoctorText(report) {
11
11
  ` plugin: ${yn(report.pluginInstalled)}`,
12
12
  ` hook: ${yn(report.hooksWired)}`,
13
13
  ` managed config: ${yn(report.configManaged)}`,
14
+ ` agent file: ${report.agentFile}`,
15
+ ` attribution: ${report.attribution}`,
14
16
  ` config: ${report.effectiveConfig.state} (${report.effectiveConfig.detail})`,
15
17
  ` agent config: ${report.agentRouting.desiredConfig}`,
16
18
  ` agent TOMLs: ${report.agentRouting.installedTomls}`,
@@ -9,6 +9,11 @@ import { homedir } from "node:os";
9
9
  import { join } from "node:path";
10
10
  import { EXPLICIT_GPT56_SOL_MODEL, GPT56_MODELS } from "../config-migration/gpt56-policy.js";
11
11
  import { isNewer } from "../update-check.js";
12
+ import { instructionFileState } from "./agent-file/apply.js";
13
+ import { readAttributionMode } from "./agent-file/attribution.js";
14
+ import { AGENT_FILE_ID } from "./agent-file/bodies.js";
15
+ import { agentFilePath } from "./agent-file/cli.js";
16
+ import { readAgentFileMode } from "./agent-file/mode.js";
12
17
  import { inspectAgentRouting, routingReport } from "./agent-routing.js";
13
18
  import { detectAuthMode } from "./auth-mode.js";
14
19
  import { inspectAutoHandoff } from "./auto-handoff-doctor.js";
@@ -62,6 +67,11 @@ const POST_INSTALL_CAPABILITY = {
62
67
  };
63
68
  export function runDoctor(deps) {
64
69
  const postInstall = deps.scope === "post-install";
70
+ const agentHome = resolveCodexHome(deps.env);
71
+ const agentFile = readAgentFileMode({ env: deps.env, codexHome: agentHome }) === "off"
72
+ ? "off"
73
+ : instructionFileState({ path: agentFilePath(agentHome), id: AGENT_FILE_ID, version: PACKAGE_VERSION });
74
+ const attribution = readAttributionMode({ env: deps.env, codexHome: agentHome });
65
75
  const codexBin = findCodexBinary(deps.env, deps.fs);
66
76
  const codexBinaryFound = codexBin !== null;
67
77
  const issues = [];
@@ -84,6 +94,8 @@ export function runDoctor(deps) {
84
94
  return {
85
95
  ok: false,
86
96
  ...(postInstall ? { scope: "post-install" } : {}),
97
+ agentFile,
98
+ attribution,
87
99
  marketplaceRegistered: false,
88
100
  pluginInstalled: false,
89
101
  hooksWired: false,
@@ -141,6 +153,12 @@ export function runDoctor(deps) {
141
153
  }
142
154
  const effectiveConfig = inspectEffectiveConfig(deps.fs, join(codexHome, "config.toml"));
143
155
  const configManaged = effectiveConfig.state !== "unavailable";
156
+ if (agentFile === "malformed") {
157
+ issues.push(`LitFamily block in ${agentFilePath(codexHome)} is malformed; remove the broken markers, then run \`litcodex install --yes\`.`);
158
+ }
159
+ else if (agentFile === "symlink" || agentFile === "not-file" || agentFile === "not-utf8") {
160
+ warnings.push(`Global AGENTS.md is ${agentFile}; the LitFamily block was left as it is.`);
161
+ }
144
162
  if (effectiveConfig.state === "unavailable") {
145
163
  issues.push(`Codex config unavailable: ${effectiveConfig.detail}.`);
146
164
  }
@@ -194,6 +212,8 @@ export function runDoctor(deps) {
194
212
  return {
195
213
  ok: issues.length === 0,
196
214
  ...(postInstall ? { scope: "post-install" } : {}),
215
+ agentFile,
216
+ attribution,
197
217
  marketplaceRegistered,
198
218
  pluginInstalled,
199
219
  hooksWired,
@@ -318,12 +318,12 @@ export declare const README_STUDIO_PAYLOAD_HASHES: {
318
318
  readonly "templates/cover-source.json": "2f65ec7706431a308619f57c5741c5fa0b24bd60c0c2c649c364aafdb8170e26";
319
319
  readonly "templates/hyperframes-cover/index.html": "cd89b5c6c0fbeeb895eb38a7eb9e232d622323a48adc9773b548032acf6d6c64";
320
320
  readonly "templates/hyperframes-cover/index.motion.json": "18dab5464db575a5048e0f3a476c0eddbf284545147283ba04025a8495d16e43";
321
- readonly "templates/hyperframes-cover/package-lock.json": "0346787c50cf6599e2ded66f308ab0a935bb5c5dd21a46ed4a815b58ba17c16f";
321
+ readonly "templates/hyperframes-cover/package-lock.json": "8ee67c0541ad31030fbc7166cda3b3b06e85c40c920edc49be7b77304388b92b";
322
322
  readonly "templates/hyperframes-cover/package.json": "9ec0e871126193a545f898f0ed994412a518e2bf06170cd07b3fc9e61cae2530";
323
323
  readonly "templates/readme-cover-section.md": "324e61dd601c42af7117f0eed7ef6ca58c66444c0607919831a64685f4d49b7a";
324
324
  readonly "templates/readme-facts.json": "3155f9b36f98db20d588f68358d0152aa24ad395c1cb62c39a72d2084abb6ddd";
325
- readonly "templates/remotion-cover/package-lock.json": "70b73745a2f763bd55b080a6a20433f9eb4c79fe26bc751f55fdf3408baf124f";
326
- readonly "templates/remotion-cover/package.json": "88448fd7021c32527fb36ee4d6a709f32f1289eae126d9532fca033c4b2debeb";
325
+ readonly "templates/remotion-cover/package-lock.json": "3a75c89827e447c6f0414fd0248347e41ed5684b73fc074adae69d1e481deada";
326
+ readonly "templates/remotion-cover/package.json": "aed7abf478033247d5529c4f89d1ba5c80e364f0be6d7ea707f2c68b091cab0f";
327
327
  readonly "templates/remotion-cover/src/ReadmeCover.tsx": "bdaddbadcddd99102e2f915eb16eaa1d1def9d8aacd777772afc6d66d106443d";
328
328
  readonly "templates/remotion-cover/src/Root.tsx": "0b3e22dd556216d67bbbca4745f5b041c9fc2a986ca3ba9945bf4b916a51e004";
329
329
  readonly "templates/remotion-cover/src/index.tsx": "32185b5fe29233ed658013191cf02a1ba3181fe15dd4c43848136a344887ff0f";
@@ -1054,7 +1054,7 @@ export declare const MOTION_PAYLOAD_HASHES: {
1054
1054
  readonly "references/type-and-timing.md": "7fd70378a466fa82c50a1d58a0565ae5117f25d753314844f192190b8ace0d6a";
1055
1055
  readonly "runtime/package-lock.json": "f2fbcf6465074357c50b8337bdad50a1575c01d44b01b66ceebbf945452901ce";
1056
1056
  readonly "runtime/package.json": "a9b24cc897fbea65cb5272f42a7af9b77c9b1f19785c982391280c38f91d00b0";
1057
- readonly "runtime/requirements-audio.txt": "039658e6e9f2d83e2c2b7f2cac17c330986759f09d29809875780e14fb4342e2";
1057
+ readonly "runtime/requirements-audio.txt": "d7a14ace3cc1c356559d8c79d69221387391b0cea50c52be8cb6adfd30880589";
1058
1058
  readonly "runtime/word-timing-models.json": "ec78f5ee18a586efd02cca0749121595ebb6226e17dde969caa91340e53b7643";
1059
1059
  readonly "scripts/beat-grid.py": "fee5a17b03c6fa4302fcd47464db76aafce462c1a68a413bda3fb3a6b105051b";
1060
1060
  readonly "scripts/render.mjs": "f1dfef821d05e6cba8e150d9b5d52f35b5ccc53e3930b252dfadac1d8be3ecb6";
@@ -319,12 +319,12 @@ export const README_STUDIO_PAYLOAD_HASHES = {
319
319
  "templates/cover-source.json": "2f65ec7706431a308619f57c5741c5fa0b24bd60c0c2c649c364aafdb8170e26",
320
320
  "templates/hyperframes-cover/index.html": "cd89b5c6c0fbeeb895eb38a7eb9e232d622323a48adc9773b548032acf6d6c64",
321
321
  "templates/hyperframes-cover/index.motion.json": "18dab5464db575a5048e0f3a476c0eddbf284545147283ba04025a8495d16e43",
322
- "templates/hyperframes-cover/package-lock.json": "0346787c50cf6599e2ded66f308ab0a935bb5c5dd21a46ed4a815b58ba17c16f",
322
+ "templates/hyperframes-cover/package-lock.json": "8ee67c0541ad31030fbc7166cda3b3b06e85c40c920edc49be7b77304388b92b",
323
323
  "templates/hyperframes-cover/package.json": "9ec0e871126193a545f898f0ed994412a518e2bf06170cd07b3fc9e61cae2530",
324
324
  "templates/readme-cover-section.md": "324e61dd601c42af7117f0eed7ef6ca58c66444c0607919831a64685f4d49b7a",
325
325
  "templates/readme-facts.json": "3155f9b36f98db20d588f68358d0152aa24ad395c1cb62c39a72d2084abb6ddd",
326
- "templates/remotion-cover/package-lock.json": "70b73745a2f763bd55b080a6a20433f9eb4c79fe26bc751f55fdf3408baf124f",
327
- "templates/remotion-cover/package.json": "88448fd7021c32527fb36ee4d6a709f32f1289eae126d9532fca033c4b2debeb",
326
+ "templates/remotion-cover/package-lock.json": "3a75c89827e447c6f0414fd0248347e41ed5684b73fc074adae69d1e481deada",
327
+ "templates/remotion-cover/package.json": "aed7abf478033247d5529c4f89d1ba5c80e364f0be6d7ea707f2c68b091cab0f",
328
328
  "templates/remotion-cover/src/ReadmeCover.tsx": "bdaddbadcddd99102e2f915eb16eaa1d1def9d8aacd777772afc6d66d106443d",
329
329
  "templates/remotion-cover/src/Root.tsx": "0b3e22dd556216d67bbbca4745f5b041c9fc2a986ca3ba9945bf4b916a51e004",
330
330
  "templates/remotion-cover/src/index.tsx": "32185b5fe29233ed658013191cf02a1ba3181fe15dd4c43848136a344887ff0f",
@@ -1055,7 +1055,7 @@ export const MOTION_PAYLOAD_HASHES = {
1055
1055
  "references/type-and-timing.md": "7fd70378a466fa82c50a1d58a0565ae5117f25d753314844f192190b8ace0d6a",
1056
1056
  "runtime/package-lock.json": "f2fbcf6465074357c50b8337bdad50a1575c01d44b01b66ceebbf945452901ce",
1057
1057
  "runtime/package.json": "a9b24cc897fbea65cb5272f42a7af9b77c9b1f19785c982391280c38f91d00b0",
1058
- "runtime/requirements-audio.txt": "039658e6e9f2d83e2c2b7f2cac17c330986759f09d29809875780e14fb4342e2",
1058
+ "runtime/requirements-audio.txt": "d7a14ace3cc1c356559d8c79d69221387391b0cea50c52be8cb6adfd30880589",
1059
1059
  "runtime/word-timing-models.json": "ec78f5ee18a586efd02cca0749121595ebb6226e17dde969caa91340e53b7643",
1060
1060
  "scripts/beat-grid.py": "fee5a17b03c6fa4302fcd47464db76aafce462c1a68a413bda3fb3a6b105051b",
1061
1061
  "scripts/render.mjs": "f1dfef821d05e6cba8e150d9b5d52f35b5ccc53e3930b252dfadac1d8be3ecb6",
@@ -11,6 +11,8 @@ import { join } from "node:path";
11
11
  import readline from "node:readline/promises";
12
12
  import { migrateCodexConfig, readLitCodexOutputStyleId } from "../config-migration/index.js";
13
13
  import { humanLabel, preflightLabel, renderBanner, renderInstallFailure, renderInstallReceipt, renderPreflightIntro, renderStepIntro, renderStepResult, Spinner, shouldDecorate, } from "../ui.js";
14
+ import { clearAttributionMode } from "./agent-file/attribution.js";
15
+ import { AGENT_FILE_QUESTION, ATTRIBUTION_QUESTION, agentFileDryRunLine, removeGlobalAgentFile, runInstallAgentFile, } from "./agent-file/cli.js";
14
16
  import { codexSpawnInvocation, resolveCodexHome } from "./codex.js";
15
17
  import { doctorScopeFor, renderDoctorText, runDoctor } from "./doctor.js";
16
18
  import { exitCodeForInstallError, InstallError, toErrorJson } from "./errors.js";
@@ -246,6 +248,7 @@ export async function runInstallCli(args, io = defaultIo()) {
246
248
  if (opts.dryRun) {
247
249
  // ZERO spawns, ZERO fs writes: render and return.
248
250
  io.stdout.write(`${renderInstallPlan(plan)}\n`);
251
+ io.stdout.write(`${agentFileDryRunLine(opts.codexHome)}\n`);
249
252
  return 0;
250
253
  }
251
254
  let result;
@@ -338,6 +341,40 @@ export async function runInstallCli(args, io = defaultIo()) {
338
341
  finally {
339
342
  marketplaceSource?.cleanup();
340
343
  }
344
+ const agentPrompt = interactiveInstall(opts, io)
345
+ ? async () => {
346
+ const rl = installReadline(opts, io);
347
+ try {
348
+ return !/^\s*n/iu.test((await rl.question(AGENT_FILE_QUESTION)).trim());
349
+ }
350
+ finally {
351
+ rl.close();
352
+ }
353
+ }
354
+ : undefined;
355
+ const attributionPrompt = agentPrompt
356
+ ? async () => {
357
+ const rl = installReadline(opts, io);
358
+ try {
359
+ return /^\s*y/iu.test((await rl.question(ATTRIBUTION_QUESTION)).trim());
360
+ }
361
+ finally {
362
+ rl.close();
363
+ }
364
+ }
365
+ : undefined;
366
+ const agentFileLine = await runInstallAgentFile({
367
+ env: io.env,
368
+ stdout: io.stdout,
369
+ codexHome: opts.codexHome,
370
+ version: PACKAGE_VERSION,
371
+ yes: opts.yes,
372
+ noAgentFile: opts.noAgentFile,
373
+ dryRun: false,
374
+ json: opts.json,
375
+ ...(agentPrompt === undefined ? {} : { prompt: agentPrompt }),
376
+ ...(attributionPrompt === undefined ? {} : { attributionPrompt }),
377
+ });
341
378
  const officeRuntime = result.ok ? prepareOfficeRuntime(opts.codexHome, spawnSync, io.env) : undefined;
342
379
  if (officeRuntime)
343
380
  io.stderr.write(`[litcodex] ${officeRuntimeNotice(officeRuntime.ready, officeRuntime.detail)}\n`);
@@ -345,7 +382,7 @@ export async function runInstallCli(args, io = defaultIo()) {
345
382
  if (motionRuntime)
346
383
  io.stderr.write(`[litcodex] ${motionRuntime.receipt}\n`);
347
384
  if (opts.json) {
348
- io.stdout.write(`${JSON.stringify(result)}\n`);
385
+ io.stdout.write(`${JSON.stringify({ ...result, agentFile: agentFileLine })}\n`);
349
386
  }
350
387
  else if (decorate) {
351
388
  io.stdout.write(renderInstallReceipt(result, {
@@ -427,14 +464,19 @@ export function runUninstallCli(args, io = defaultIo()) {
427
464
  },
428
465
  },
429
466
  });
467
+ const agentRemoval = removeGlobalAgentFile(codexHome, PACKAGE_VERSION);
468
+ clearAttributionMode(codexHome);
430
469
  if (json) {
431
- io.stdout.write(`${JSON.stringify(result)}\n`);
432
- }
433
- else if (result.ok) {
434
- io.stdout.write("litcodex uninstall: complete\n");
470
+ io.stdout.write(`${JSON.stringify({ ...result, agentFile: agentRemoval })}\n`);
435
471
  }
436
472
  else {
437
- io.stderr.write("[litcodex] uninstall: codex plugin remove failed\n");
473
+ io.stdout.write(`${agentRemoval}\n`);
474
+ if (result.ok) {
475
+ io.stdout.write("litcodex uninstall: complete\n");
476
+ }
477
+ else {
478
+ io.stderr.write("[litcodex] uninstall: codex plugin remove failed\n");
479
+ }
438
480
  }
439
481
  return result.ok ? 0 : 3;
440
482
  }
@@ -6,6 +6,7 @@ import { managedMarketplaceRoot } from "./marketplace.js";
6
6
  const KNOWN_FLAGS = new Set([
7
7
  "--dry-run",
8
8
  "--no-tui",
9
+ "--no-agent-file",
9
10
  "--codex-autonomous",
10
11
  "--force",
11
12
  "--json",
@@ -44,6 +45,7 @@ export function parseInstallOptions(args, context) {
44
45
  force: args.includes("--force"),
45
46
  json: args.includes("--json"),
46
47
  yes: args.includes("--yes"),
48
+ noAgentFile: args.includes("--no-agent-file"),
47
49
  profile: lead.profile,
48
50
  leadModel: lead.id,
49
51
  effort,
@@ -6,6 +6,7 @@ export interface InstallOptions {
6
6
  readonly force: boolean;
7
7
  readonly json: boolean;
8
8
  readonly yes: boolean;
9
+ readonly noAgentFile: boolean;
9
10
  readonly profile: import("../config-migration/gpt56-policy.js").Gpt56Profile;
10
11
  /** Explicit lead model id (e.g. "gpt-5.6-sol", "gpt-5.6", "gpt-5.6-luna"). */
11
12
  readonly leadModel: string;
@@ -84,6 +85,10 @@ export interface DoctorReport {
84
85
  readonly skillCatalogComplete: boolean;
85
86
  readonly missingSkillIds: readonly string[];
86
87
  readonly missingSkillResourcePaths: readonly string[];
88
+ /** `off` when the stored switch is off, else the global AGENTS.md section state. */
89
+ readonly agentFile: string;
90
+ /** `keep` or `off`: whether the block asks the model not to add AI attribution. */
91
+ readonly attribution: string;
87
92
  readonly handoffInstalled: boolean;
88
93
  readonly scientificVisualizationInstalled: boolean;
89
94
  readonly capabilities: import("./host-capabilities.js").HostCapabilities;
@@ -39,6 +39,7 @@ export function uninstallPlanSteps(codexHome) {
39
39
  `Remove the marketplace: codex plugin marketplace remove ${LITCODEX_MARKETPLACE}, then delete ${managedMarketplaceRoot(codexHome)} only if the marketplace removal succeeds`,
40
40
  `Remove LitCodex agent roles from ${join(codexHome, "agents")} and the native default route ${join(codexHome, NATIVE_DEFAULT_AGENT_FILE)}, when they still match what LitCodex installed`,
41
41
  `Remove the managed [agents] defaults from ${join(codexHome, "config.toml")} and LitCodex-generated profile files from ${codexHome}`,
42
+ `Remove the LitFamily block from ${join(codexHome, "AGENTS.md")} (your own text stays; a file the block alone created is deleted)`,
42
43
  `If the marketplace root or config.toml is a symlink or otherwise unsafe, uninstall refuses to change anything`,
43
44
  ];
44
45
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "litcodex",
3
- "version": "1.0.32",
3
+ "version": "1.0.34",
4
4
  "author": {
5
5
  "name": "LitCodex Authors"
6
6
  },
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/auto-update",
3
- "version": "1.0.32",
3
+ "version": "1.0.34",
4
4
  "description": "LitCodex foreground update barrier for the SessionStart and management lifecycles.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/comment-checker",
3
- "version": "1.0.32",
3
+ "version": "1.0.34",
4
4
  "description": "LitCodex Comment-Checker hook: flags low-value / AI-slop comments introduced by edits.",
5
5
  "type": "module",
6
6
  "private": true,