docks-kit 0.22.25 → 0.23.0

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 (77) hide show
  1. package/AGENTS.md +35 -81
  2. package/README.md +31 -58
  3. package/cli/docs/command-guards.md +231 -197
  4. package/cli/docs/flags.md +25 -55
  5. package/cli/docs/install.md +2 -3
  6. package/cli/docs/omp-context.md +5 -5
  7. package/cli/docs/omp-models.md +249 -48
  8. package/cli/docs/overview.md +4 -12
  9. package/cli/docs/platforms.md +2 -2
  10. package/cli/docs/sync-layers.md +10 -57
  11. package/cli/docs/toolchain.md +9 -78
  12. package/cli/src/argv.ts +0 -8
  13. package/cli/src/argvValidate.ts +2 -46
  14. package/cli/src/commands/docs.ts +2 -14
  15. package/cli/src/commands/harnesses.ts +6 -9
  16. package/cli/src/commands/sync.ts +5 -99
  17. package/cli/src/commands/toolchain.ts +4 -12
  18. package/cli/src/engine-native/DESIGN.md +67 -88
  19. package/cli/src/engine-native/deps.ts +6 -86
  20. package/cli/src/engine-native/engineCtx.ts +7 -76
  21. package/cli/src/engine-native/exec.ts +1 -18
  22. package/cli/src/engine-native/harnesses.ts +6 -6
  23. package/cli/src/engine-native/index.ts +4 -6
  24. package/cli/src/engine-native/jq.ts +4 -37
  25. package/cli/src/engine-native/modes.ts +3 -132
  26. package/cli/src/engine-native/ompRemovals.ts +14 -0
  27. package/cli/src/engine-native/os/darwin.ts +0 -4
  28. package/cli/src/engine-native/os/index.ts +1 -2
  29. package/cli/src/engine-native/os/linux.ts +0 -3
  30. package/cli/src/engine-native/os/posix.ts +2 -46
  31. package/cli/src/engine-native/os/types.ts +1 -32
  32. package/cli/src/engine-native/os/windows.ts +0 -49
  33. package/cli/src/engine-native/parseArgs.ts +11 -124
  34. package/cli/src/engine-native/parseHelp.ts +5 -40
  35. package/cli/src/engine-native/scratch.ts +1 -1
  36. package/cli/src/engine-native/services.ts +1 -2
  37. package/cli/src/engine-native/sharedTypes.d.ts +0 -40
  38. package/cli/src/engine-native/skillsSync.ts +1 -1
  39. package/cli/src/engine-native/syncConcurrency.ts +3 -15
  40. package/cli/src/engine-native/syncDispatch.ts +10 -57
  41. package/cli/src/engine-native/toolchain.ts +5 -40
  42. package/cli/src/engine.ts +0 -75
  43. package/cli/src/generated/sotPayload.ts +14 -41
  44. package/cli/src/main.ts +7 -19
  45. package/cli/src/manifests.ts +1 -93
  46. package/cli/src/payload.ts +2 -8
  47. package/cli/tsconfig.json +1 -3
  48. package/package.json +3 -5
  49. package/cli/docs/models.md +0 -58
  50. package/cli/docs/modifiers.md +0 -52
  51. package/cli/docs/plugins.md +0 -70
  52. package/cli/src/commands/model.ts +0 -68
  53. package/cli/src/commands/models.ts +0 -75
  54. package/cli/src/commands/plugins.ts +0 -35
  55. package/cli/src/commands/status.ts +0 -206
  56. package/cli/src/efforts.ts +0 -89
  57. package/cli/src/engine-native/claudeLsp.ts +0 -301
  58. package/cli/src/engine-native/claudeOptionalPlugins.ts +0 -126
  59. package/cli/src/engine-native/claudePluginPasses.ts +0 -426
  60. package/cli/src/engine-native/claudeRemovals.ts +0 -383
  61. package/cli/src/engine-native/claudeRetired.ts +0 -165
  62. package/cli/src/engine-native/claudeRuntime.ts +0 -157
  63. package/cli/src/engine-native/claudeSettings.ts +0 -201
  64. package/cli/src/engine-native/claudeSettingsModifiers.ts +0 -115
  65. package/cli/src/engine-native/claudeSync.ts +0 -312
  66. package/cli/src/engine-native/codexConfig.ts +0 -214
  67. package/cli/src/engine-native/codexHooks.ts +0 -91
  68. package/cli/src/engine-native/codexPaths.ts +0 -14
  69. package/cli/src/engine-native/codexPlugins.ts +0 -315
  70. package/cli/src/engine-native/codexStatus.ts +0 -25
  71. package/cli/src/engine-native/codexSync.ts +0 -314
  72. package/cli/src/engine-native/codexToml.ts +0 -303
  73. package/cli/src/engine-native/liveModels.ts +0 -264
  74. package/cli/src/engine-native/models.ts +0 -101
  75. package/cli/src/engine-native/parseModifiers.ts +0 -225
  76. package/cli/src/engine-native/settings.ts +0 -42
  77. package/cli/src/engine-native/tomlLines.ts +0 -92
@@ -1,214 +0,0 @@
1
- /**
2
- * EngineNative Codex config merge and validation. Line-based TOML passes
3
- * intentionally avoid a TOML library because reformatting user configs would
4
- * be a behavior change. Guard order, message strings, and backup behavior
5
- * are golden-tested.
6
- */
7
- import { copyFileSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
8
-
9
- import { payloadDisplayPath } from "../payload";
10
- import { replaceFile } from "./atomicWrite";
11
- import { mergeTableSettings, mergeTopLevelSettings } from "./codexToml";
12
- import type { Ctx } from "./index";
13
- import { isTomlHeaderLine, tomlContinuationLines } from "./tomlLines";
14
-
15
- // --------------------------------------------------------------- config ----
16
-
17
- export function syncConfig(ctx: Ctx, sotConfigText: string, userConfig: string): void {
18
- const { change, echo, verbose } = ctx.services.logger;
19
- const sotConfig = payloadDisplayPath("SoT/.codex/config.toml");
20
-
21
- if (ctx.dryRun) {
22
- if (existsSync(userConfig)) {
23
- echo(`[dry-run] merge ${sotConfig} -> ${userConfig}`);
24
- } else {
25
- echo(`[dry-run] install ${sotConfig} -> ${userConfig}`);
26
- }
27
- return;
28
- }
29
-
30
- if (!existsSync(userConfig)) {
31
- writeFileSync(userConfig, sotConfigText);
32
- change("Codex config installed");
33
- ctx.nextStepTriggers.codexRestart = true;
34
- return;
35
- }
36
-
37
- // Merge into a staging copy so `.bak` is written only when the config
38
- // actually changes — an unconditional early backup lets a later no-op run
39
- // overwrite the recovery copy with already-merged content.
40
- const before = readFileSync(userConfig, "utf8");
41
- const staging = `${userConfig}.merge.tmp`;
42
- // Normalize once before record transforms: a BOM hides the first key or
43
- // header, and CR bytes change table-header identity.
44
- writeFileSync(staging, before.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n"));
45
-
46
- scrubDeprecatedFeatures(ctx, staging);
47
- removeRetiredPluginTables(ctx, staging);
48
- removeRetiredTopLevelSettings(ctx, staging);
49
- mergeTopLevelSettings(sotConfigText, staging);
50
- mergeTableSettings(sotConfigText, staging);
51
-
52
- const merged = readFileSync(staging, "utf8");
53
- rmSync(staging, { force: true });
54
- if (merged === before) {
55
- verbose("Codex config already in sync");
56
- } else {
57
- copyFileSync(userConfig, `${userConfig}.bak`);
58
- replaceFile(userConfig, merged);
59
- change(
60
- "Codex config merged (backup at config.toml.bak; SoT tables replaced wholesale; user-only top-level keys and tables preserved)",
61
- );
62
- ctx.nextStepTriggers.codexRestart = true;
63
- }
64
- }
65
-
66
- /** codex::scrub_deprecated_features — the [features].use_legacy_landlock awk pass. */
67
- function scrubDeprecatedFeaturesText(content: string): string {
68
- const lines = content.split("\n");
69
- if (lines[lines.length - 1] === "") lines.pop();
70
- let out = "";
71
- let inFeatures = false;
72
- let header = "";
73
- let body = "";
74
- let keep = false;
75
- let changed = false;
76
- for (const line of lines) {
77
- if (inFeatures) {
78
- if (isTomlHeaderLine(line)) {
79
- inFeatures = false;
80
- if (keep) out += `${header}\n${body}`;
81
- else changed = true;
82
- out += `${line}\n`;
83
- continue;
84
- }
85
- if (/^[ \t]*use_legacy_landlock[ \t]*=/.test(line)) {
86
- changed = true;
87
- continue;
88
- }
89
- body += `${line}\n`;
90
- if (/[^ \t\f\v\r]/.test(line)) keep = true;
91
- continue;
92
- }
93
- if (/^[ \t]*\[features\][ \t]*$/.test(line)) {
94
- inFeatures = true;
95
- header = line;
96
- body = "";
97
- keep = false;
98
- continue;
99
- }
100
- out += `${line}\n`;
101
- }
102
- if (inFeatures) {
103
- if (keep) out += `${header}\n${body}`;
104
- else changed = true;
105
- }
106
- return changed ? out : content;
107
- }
108
-
109
- function scrubDeprecatedFeatures(ctx: Ctx, userConfig: string): void {
110
- const { change } = ctx.services.logger;
111
- if (!existsSync(userConfig)) return;
112
- const content = readFileSync(userConfig, "utf8");
113
- const next = scrubDeprecatedFeaturesText(content);
114
- if (next === content) return;
115
-
116
- replaceFile(userConfig, next);
117
- change("Codex: scrubbed deprecated [features].use_legacy_landlock");
118
- }
119
-
120
- export const PLUGIN_TABLE_HEADER = /^[ \t]*\[plugins\."([^"]+)"\][ \t]*$/;
121
- /** Plugin ids the kit retired; their deployed tables are stripped on every sync. */
122
- const RETIRED_PLUGIN_IDS: Readonly<Record<string, true>> = {
123
- "effect-kit@docks": true,
124
- "session-relay@docks": true,
125
- };
126
-
127
- /** codex::remove_retired_plugin_tables — drop [plugins."<id>"] blocks for retired ids. */
128
- export function removeRetiredPluginTablesText(content: string): string {
129
- const lines = content.split("\n");
130
- if (lines[lines.length - 1] === "") lines.pop();
131
- let out = "";
132
- let skipping = false;
133
- for (const line of lines) {
134
- const header = PLUGIN_TABLE_HEADER.exec(line);
135
- if (header !== null) {
136
- skipping = RETIRED_PLUGIN_IDS[header[1]!] === true;
137
- if (skipping) continue;
138
- } else if (skipping) {
139
- if (!isTomlHeaderLine(line)) continue;
140
- skipping = false;
141
- }
142
- out += `${line}\n`;
143
- }
144
- return out;
145
- }
146
-
147
- function retiredPluginTables(content: string): Array<string> {
148
- return content
149
- .split("\n")
150
- .map((line) => PLUGIN_TABLE_HEADER.exec(line)?.[1])
151
- .filter((id): id is string => id !== undefined && RETIRED_PLUGIN_IDS[id] === true);
152
- }
153
-
154
- export function removeRetiredPluginTables(ctx: Ctx, userConfig: string): void {
155
- const { change } = ctx.services.logger;
156
- if (!existsSync(userConfig)) return;
157
- const content = readFileSync(userConfig, "utf8");
158
- const present = retiredPluginTables(content);
159
- if (present.length === 0) return;
160
-
161
- replaceFile(userConfig, removeRetiredPluginTablesText(content));
162
- for (const id of present) change(`Codex: removed retired plugin table [plugins."${id}"]`);
163
- }
164
-
165
- /**
166
- * Top-level settings the kit retired. Each sync removes a deployed top-level
167
- * line that holds exactly the retired kit value. A different user value stays.
168
- */
169
- const RETIRED_TOP_LEVEL_SETTINGS: ReadonlyArray<{
170
- readonly setting: string;
171
- readonly pattern: RegExp;
172
- }> = [
173
- // Codex 0.159.0 deprecated `personality`; "pragmatic" no longer selects a style.
174
- {
175
- setting: 'personality = "pragmatic"',
176
- pattern: /^[ \t]*personality[ \t]*=[ \t]*"pragmatic"[ \t]*$/,
177
- },
178
- ];
179
-
180
- /** Drop top-level lines that hold a retired kit setting; returns the text and the removed settings. */
181
- function removeRetiredTopLevelSettingsText(content: string): {
182
- readonly text: string;
183
- readonly removed: ReadonlyArray<string>;
184
- } {
185
- const lines = content.split("\n");
186
- const continuation = tomlContinuationLines(lines);
187
- const removed: Array<string> = [];
188
- const kept: Array<string> = [];
189
- let inTable = false;
190
- for (const [index, line] of lines.entries()) {
191
- if (continuation[index] !== true && !inTable) {
192
- if (isTomlHeaderLine(line)) {
193
- inTable = true;
194
- } else {
195
- const retired = RETIRED_TOP_LEVEL_SETTINGS.find(({ pattern }) => pattern.test(line));
196
- if (retired !== undefined) {
197
- removed.push(retired.setting);
198
- continue;
199
- }
200
- }
201
- }
202
- kept.push(line);
203
- }
204
- return { text: removed.length === 0 ? content : kept.join("\n"), removed };
205
- }
206
-
207
- function removeRetiredTopLevelSettings(ctx: Ctx, userConfig: string): void {
208
- const { change } = ctx.services.logger;
209
- const { text, removed } = removeRetiredTopLevelSettingsText(readFileSync(userConfig, "utf8"));
210
- if (removed.length === 0) return;
211
-
212
- replaceFile(userConfig, text);
213
- for (const setting of removed) change(`Codex: removed retired top-level setting ${setting}`);
214
- }
@@ -1,91 +0,0 @@
1
- /**
2
- * EngineNative Codex retired-hook pruning. Removes only the Claude hooks
3
- * docks-kit retired before Codex could import them safely. Guard order,
4
- * message strings, and backup behavior are golden-tested.
5
- */
6
- import { copyFileSync, existsSync, readFileSync } from "node:fs";
7
-
8
- import { replaceFile } from "./atomicWrite";
9
- import { p } from "./exec";
10
- import type { Ctx } from "./index";
11
- import { isObject, jqStringify, parseJson, type Json } from "./jq";
12
-
13
- const RETIRED_CONTEXT_HOOK = `echo "[CONTEXT] Current date: $(date '+%A, %Y-%m-%d %H:%M:%S %Z')"`;
14
- const RETIRED_SKILLS_HOOK = `SKILL_COUNT=$(find .claude/skills -name 'SKILL.md' -mindepth 2 -maxdepth 2 2>/dev/null | wc -l); [ "$SKILL_COUNT" -gt 0 ] && echo "[SKILLS] $SKILL_COUNT project skills available in .claude/skills/. Claude Code loads them on demand via Skill tool. After code changes affecting documented patterns, update the relevant skill and its metadata.updated field." || true`;
15
- const RETIRED_CONFIG_HOOKS = new Set([
16
- `echo "[CONFIG] Context: $([ \\"\${CLAUDE_CODE_DISABLE_1M_CONTEXT:-0}\\" = \\"1\\" ] && echo '200K' || echo '1M') | Compact-window: \${CLAUDE_CODE_AUTO_COMPACT_WINDOW:-full} | Effort: \${CLAUDE_CODE_EFFORT_LEVEL:-high} | Thinking: adaptive | Subagent: \${CLAUDE_CODE_SUBAGENT_MODEL:-default}"`,
17
- `echo "[CONFIG] Context: $([ \\"\${CLAUDE_CODE_DISABLE_1M_CONTEXT:-0}\\" = \\"1\\" ] && echo '200K' || echo '1M') | Compact-window: \${CLAUDE_CODE_AUTO_COMPACT_WINDOW:-full} | Effort: \${CLAUDE_CODE_EFFORT_LEVEL:-high} | Thinking: adaptive | Model: \${ANTHROPIC_DEFAULT_OPUS_MODEL:-default} | Subagent: \${CLAUDE_CODE_SUBAGENT_MODEL:-default}"`,
18
- `echo "[CONFIG] Context: $([ \\"\${CLAUDE_CODE_DISABLE_1M_CONTEXT:-0}\\" = \\"1\\" ] && echo '200K' || echo '1M') | Compact-window: \${CLAUDE_CODE_AUTO_COMPACT_WINDOW:-full} | Effort: \${CLAUDE_CODE_EFFORT_LEVEL:-$(jq -r .effortLevel $HOME/.claude/settings.json 2>/dev/null || echo default)} | Thinking: adaptive | Subagent: \${CLAUDE_CODE_SUBAGENT_MODEL:-default}"`,
19
- ]);
20
-
21
- function isRetiredImportedSessionStartHook(handler: Json, codexDir: string): boolean {
22
- if (!isObject(handler) || handler["type"] !== "command" || typeof handler["command"] !== "string")
23
- return false;
24
- const command = handler["command"];
25
- const connectorScript = p(codexDir, "hooks", "disable-claudeai-connectors.sh");
26
- const retiredConnectorHook = `[ -x '${connectorScript}' ] && '${connectorScript}' || true`;
27
- return (
28
- command === RETIRED_CONTEXT_HOOK ||
29
- command === RETIRED_SKILLS_HOOK ||
30
- RETIRED_CONFIG_HOOKS.has(command) ||
31
- command === retiredConnectorHook
32
- );
33
- }
34
-
35
- function withoutRetiredImportedHooks(
36
- doc: { [key: string]: Json },
37
- codexDir: string,
38
- ): { readonly value: Json; readonly removed: number } {
39
- const hooks = doc["hooks"];
40
- if (!isObject(hooks) || !Array.isArray(hooks["SessionStart"])) return { value: doc, removed: 0 };
41
-
42
- let removed = 0;
43
- const groups: Array<Json> = [];
44
- for (const group of hooks["SessionStart"]) {
45
- if (!isObject(group) || !Array.isArray(group["hooks"])) {
46
- groups.push(group);
47
- continue;
48
- }
49
- const kept = group["hooks"].filter((handler) => {
50
- if (!isRetiredImportedSessionStartHook(handler, codexDir)) return true;
51
- removed++;
52
- return false;
53
- });
54
- if (kept.length > 0) groups.push({ ...group, hooks: kept });
55
- }
56
- if (removed === 0) return { value: doc, removed: 0 };
57
-
58
- const nextHooks = { ...hooks };
59
- if (groups.length > 0) nextHooks["SessionStart"] = groups;
60
- else delete nextHooks["SessionStart"];
61
- return { value: { ...doc, hooks: nextHooks }, removed };
62
- }
63
-
64
- /** Remove only Claude hooks that docks-kit retired before Codex could import them safely. */
65
- export function removeRetiredImportedHooks(ctx: Ctx, codexDir: string): void {
66
- const { change, echo, warn } = ctx.services.logger;
67
- const hooksFile = p(codexDir, "hooks.json");
68
- if (!existsSync(hooksFile)) return;
69
- const before = readFileSync(hooksFile, "utf8");
70
- const doc = parseJson(before);
71
- if (doc === undefined || !isObject(doc)) {
72
- warn(`Codex hooks file is not a valid JSON object; retired hook cleanup skipped: ${hooksFile}`);
73
- return;
74
- }
75
- const result = withoutRetiredImportedHooks(doc, codexDir);
76
- if (result.removed === 0) return;
77
-
78
- if (ctx.dryRun) {
79
- echo(
80
- `[dry-run] remove ${result.removed} retired imported docks-kit SessionStart hook(s) from ${hooksFile}`,
81
- );
82
- return;
83
- }
84
-
85
- copyFileSync(hooksFile, `${hooksFile}.bak`);
86
- replaceFile(hooksFile, jqStringify(result.value));
87
- change(
88
- `Codex: removed ${result.removed} retired imported docks-kit SessionStart hook(s) (backup at hooks.json.bak)`,
89
- );
90
- ctx.nextStepTriggers.codexRestart = true;
91
- }
@@ -1,14 +0,0 @@
1
- /**
2
- * Codex home resolution. Codex reads CODEX_HOME when it is set and not empty,
3
- * and otherwise uses ~/.codex, so every kit read or write of Codex state uses
4
- * the same rule.
5
- */
6
- import { isAbsolute, resolve } from "node:path";
7
-
8
- import { p } from "./exec";
9
-
10
- export function codexHome(home: string, env: NodeJS.ProcessEnv = process.env): string {
11
- const override = env["CODEX_HOME"];
12
- if (override === undefined || override === "") return p(home, ".codex");
13
- return isAbsolute(override) ? override : resolve(override);
14
- }
@@ -1,315 +0,0 @@
1
- /**
2
- * EngineNative Codex marketplace and plugin passes: personal marketplace
3
- * merge, legacy marketplace removal, and enabled-plugin refresh. Message
4
- * strings and backup behavior are golden-tested.
5
- */
6
- import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
7
-
8
- import { payloadDisplayPath } from "../payload";
9
- import { replaceFile } from "./atomicWrite";
10
- import { PLUGIN_TABLE_HEADER } from "./codexConfig";
11
- import { p, processFailureSummary, spawnProcess } from "./exec";
12
- import { recordFailure } from "./failures";
13
- import type { Ctx } from "./index";
14
- import { compareCodepoints, isObject, jqStringify, parseJson, type Json } from "./jq";
15
- import type { JsonObject } from "./sharedTypes";
16
- import { isTomlHeaderLine } from "./tomlLines";
17
-
18
- // ---------------------------------------------------------- marketplace ----
19
-
20
- /**
21
- * Merge the SoT marketplace into the deployed personal marketplace. Codex
22
- * resolves a plugin id `<plugin>@<marketplace>` through the file's top-level
23
- * `name`. When the deployed file has a different name, the file stays as it is
24
- * and the SoT marketplace name comes back, because kit plugin ids cannot resolve.
25
- */
26
- export function syncMarketplace(
27
- ctx: Ctx,
28
- sotMarketplaceText: string,
29
- userMarketplace: string,
30
- ): string | undefined {
31
- const { change, echo, verbose, warn } = ctx.services.logger;
32
- const sotMarketplace = payloadDisplayPath("SoT/.codex/plugins/marketplace.json");
33
- const repo = parseJson(sotMarketplaceText);
34
- if (repo === undefined) throw new Error(`invalid SoT marketplace JSON: ${sotMarketplace}`);
35
-
36
- const userText = existsSync(userMarketplace) ? readFileSync(userMarketplace, "utf8") : undefined;
37
- const user = userText === undefined ? undefined : parseJson(userText);
38
- if (userText !== undefined && user === undefined) {
39
- throw new Error(
40
- `invalid deployed Codex marketplace JSON: ${userMarketplace}. Fix or delete it.`,
41
- );
42
- }
43
-
44
- const sotName = isObject(repo) && typeof repo["name"] === "string" ? repo["name"] : undefined;
45
- const userName =
46
- user !== undefined && isObject(user) && typeof user["name"] === "string"
47
- ? user["name"]
48
- : undefined;
49
- if (sotName !== undefined && userName !== undefined && userName !== sotName) {
50
- warn(
51
- `Codex personal marketplace ${userMarketplace} is named "${userName}", but kit plugins need "${sotName}". Rename it to "${sotName}" and update your [plugins."<plugin>@${userName}"] tables, or move your plugins to a different marketplace. Then run sync again.`,
52
- );
53
- return sotName;
54
- }
55
- const out = user === undefined ? undefined : jqStringify(mergeMarketplace(repo, user));
56
-
57
- if (ctx.dryRun) {
58
- if (userText === undefined) {
59
- echo(`[dry-run] cp ${sotMarketplace} -> ${userMarketplace}`);
60
- } else if (out === userText) {
61
- verbose("Codex marketplace already in sync");
62
- } else {
63
- echo(
64
- `[dry-run] merge ${sotMarketplace} -> ${userMarketplace} (backup at ${userMarketplace}.bak)`,
65
- );
66
- }
67
- return undefined;
68
- }
69
-
70
- mkdirSync(p(ctx.agentsDir, "plugins"), { recursive: true });
71
- if (userText !== undefined && out !== undefined) {
72
- if (out === userText) {
73
- verbose("Codex marketplace already in sync");
74
- return undefined;
75
- }
76
- copyFileSync(userMarketplace, `${userMarketplace}.bak`);
77
- replaceFile(userMarketplace, out);
78
- change("Codex marketplace merged (backup at marketplace.json.bak)");
79
- ctx.nextStepTriggers.codexRestart = true;
80
- } else {
81
- // Install the merge form, so the next sync merges to the same bytes.
82
- writeFileSync(userMarketplace, jqStringify(mergeMarketplace(repo, {})));
83
- change("Codex marketplace installed");
84
- ctx.nextStepTriggers.codexRestart = true;
85
- }
86
- return undefined;
87
- }
88
-
89
- /**
90
- * The jq -s marketplace merge: `$user *` a {name, interface} coalesce, then
91
- * plugins = user+repo | reverse | unique_by(.name) | reverse — SoT (repo)
92
- * wins per plugin name; distinct names end up descending by name, exactly
93
- * like jq's unique_by (ascending) followed by reverse.
94
- */
95
- function mergeMarketplace(repo: Json, user: Json): Json {
96
- const u = isObject(user) ? user : {};
97
- const r = isObject(repo) ? repo : {};
98
- const coalesce = (a: Json | undefined, b: Json | undefined): Json =>
99
- a !== undefined && a !== null && a !== false ? a : (b ?? null);
100
- const merged: JsonObject = {
101
- ...u,
102
- name: coalesce(u["name"], r["name"]),
103
- interface: coalesce(u["interface"], r["interface"]),
104
- };
105
- const plugins = [
106
- ...(Array.isArray(u["plugins"]) ? u["plugins"] : []),
107
- ...(Array.isArray(r["plugins"]) ? r["plugins"] : []),
108
- ];
109
- const firstByName = new Map<string, Json>();
110
- for (const entry of [...plugins].reverse()) {
111
- const name = isObject(entry) && typeof entry["name"] === "string" ? entry["name"] : "";
112
- if (!firstByName.has(name)) firstByName.set(name, entry);
113
- }
114
- merged["plugins"] = [...firstByName.keys()]
115
- .sort(compareCodepoints)
116
- .map((n) => firstByName.get(n)!)
117
- .reverse();
118
- return merged;
119
- }
120
-
121
- // -------------------------------------------------------------- plugins ----
122
-
123
- /** codex::_marketplace_source — first `source =` inside [marketplaces.<name>]. */
124
- export function marketplaceSource(marketplace: string, configFile: string): string {
125
- if (!existsSync(configFile)) return "";
126
- let inMarketplace = false;
127
- for (const line of readFileSync(configFile, "utf8").split("\n")) {
128
- if (line.trim() === `[marketplaces.${marketplace}]`) {
129
- inMarketplace = true;
130
- continue;
131
- }
132
- if (isTomlHeaderLine(line)) inMarketplace = false;
133
- if (inMarketplace && /^[ \t]*source[ \t]*=/.test(line)) {
134
- return line
135
- .replace(/^[^=]+=[ \t]*/, "")
136
- .replace(/[ \t]*#.*/, "")
137
- .replace(/^(["'])(.*)\1$/, "$2");
138
- }
139
- }
140
- return "";
141
- }
142
-
143
- export async function removeLegacyDocksMarketplace(ctx: Ctx, userConfig: string): Promise<void> {
144
- const { change, echo } = ctx.services.logger;
145
- if (ctx.dryRun) {
146
- echo(
147
- "[dry-run] remove legacy configured Codex Docks marketplace when personal marketplace is deployed",
148
- );
149
- return;
150
- }
151
-
152
- if (ctx.services.deps.probe("codex").state === "missing") return;
153
-
154
- const source = marketplaceSource("docks", userConfig);
155
- if (source !== "https://github.com/DocksDocks/docks.git" && source !== "DocksDocks/docks") return;
156
- const res = await spawnProcess("codex", ["plugin", "marketplace", "remove", "docks"], {
157
- stdio: "ignore",
158
- });
159
- if (res.error === undefined && res.exitCode === 0) {
160
- change("Removed legacy configured Codex Docks marketplace; using personal marketplace file");
161
- ctx.nextStepTriggers.codexRestart = true;
162
- } else {
163
- recordFailure(ctx, "Failed to remove legacy configured Codex Docks marketplace");
164
- }
165
- }
166
-
167
- /** codex::_standalone_install_command — per-OS official standalone installer. */
168
- const standaloneInstallCommand = (ctx: Ctx): string =>
169
- ctx.services.deps.spec("codex").installHint();
170
-
171
- /** codex::_enabled_plugin_ids — [plugins."<id>"] tables with enabled = true. */
172
- export function enabledPluginIds(configFile: string): Array<string> {
173
- if (!existsSync(configFile)) return [];
174
- return enabledPluginIdsFromText(readFileSync(configFile, "utf8"));
175
- }
176
-
177
- function enabledPluginIdsFromText(configText: string): Array<string> {
178
- const ids: Array<string> = [];
179
- let plugin = "";
180
- let enabled = false;
181
- const flush = (): void => {
182
- if (plugin !== "" && enabled) ids.push(plugin);
183
- };
184
- for (const line of configText.split("\n")) {
185
- const m = PLUGIN_TABLE_HEADER.exec(line);
186
- if (m !== null) {
187
- flush();
188
- plugin = m[1]!;
189
- enabled = false;
190
- continue;
191
- }
192
- if (isTomlHeaderLine(line)) {
193
- flush();
194
- plugin = "";
195
- enabled = false;
196
- continue;
197
- }
198
- if (plugin !== "" && /^[ \t]*enabled[ \t]*=[ \t]*true([ \t]*(#.*)?)?$/.test(line)) {
199
- enabled = true;
200
- }
201
- }
202
- flush();
203
- return ids;
204
- }
205
-
206
- function manualPluginRefreshHint(pluginIds: ReadonlyArray<string>): string {
207
- const first = pluginIds[0];
208
- return first !== undefined ? `; then run: codex plugin add ${first}` : "";
209
- }
210
-
211
- async function installedPluginIdsFromCli(): Promise<Set<string> | undefined> {
212
- const result = await spawnProcess("codex", ["plugin", "list", "--json"], {
213
- stdio: ["ignore", "pipe", "ignore"],
214
- });
215
- if (result.error !== undefined || result.exitCode !== 0) return undefined;
216
- const value = parseJson(result.stdout);
217
- if (value === undefined || !isObject(value) || !Array.isArray(value["installed"]))
218
- return undefined;
219
- const ids = new Set<string>();
220
- for (const row of value["installed"]) {
221
- if (!isObject(row) || row["installed"] !== true || typeof row["pluginId"] !== "string")
222
- continue;
223
- ids.add(row["pluginId"]);
224
- }
225
- return ids;
226
- }
227
-
228
- /**
229
- * Add the SoT-enabled plugins through the Codex CLI. `unresolvedMarketplace`
230
- * names a marketplace that syncMarketplace could not deploy; ids from it are
231
- * skipped, because `codex plugin add` cannot resolve them.
232
- */
233
- export async function syncPlugins(
234
- ctx: Ctx,
235
- sotConfigText: string,
236
- unresolvedMarketplace?: string,
237
- ): Promise<void> {
238
- const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger;
239
- const desiredPluginIds = enabledPluginIdsFromText(sotConfigText).filter(
240
- (pluginId) =>
241
- unresolvedMarketplace === undefined || !pluginId.endsWith(`@${unresolvedMarketplace}`),
242
- );
243
- if (ctx.dryRun) {
244
- if (desiredPluginIds.length === 0) return;
245
- echo(
246
- ctx.skipPluginRefresh
247
- ? "[dry-run] add missing enabled Codex plugins from SoT; skip refresh-only plugin updates"
248
- : "[dry-run] add enabled Codex plugins from SoT",
249
- );
250
- return;
251
- }
252
-
253
- if (ctx.services.deps.probe("codex").state === "missing") {
254
- warn(
255
- `codex CLI not in PATH - deployed config/marketplace only; install Codex with: ${standaloneInstallCommand(ctx)} | docs: https://developers.openai.com/codex/cli${manualPluginRefreshHint(desiredPluginIds)}`,
256
- );
257
- return;
258
- }
259
- if (desiredPluginIds.length === 0) return;
260
- if (ctx.services.deps.probe("git").state === "missing") {
261
- ctx.services.deps.warnMissing(
262
- "git",
263
- ctx.services.logger,
264
- "plugin marketplaces are git repos — Codex plugin refresh skipped; re-run sync after installing",
265
- );
266
- return;
267
- }
268
-
269
- let pluginIds = desiredPluginIds;
270
- if (ctx.skipPluginRefresh) {
271
- progress("Checking installed Codex plugins...");
272
- const installedPluginIds = await installedPluginIdsFromCli();
273
- clearProgress();
274
- if (installedPluginIds === undefined) {
275
- warn("Codex plugin inventory unavailable — falling back to the full refresh path");
276
- } else {
277
- pluginIds = desiredPluginIds.filter((pluginId) => !installedPluginIds.has(pluginId));
278
- }
279
- }
280
-
281
- let refreshed = 0;
282
- let failed = 0;
283
- for (const pluginId of pluginIds) {
284
- progress(`Updating Codex plugin ${pluginId}...`);
285
- const res = await spawnProcess("codex", ["plugin", "add", pluginId], {
286
- stdio: ["ignore", "pipe", "pipe"],
287
- });
288
- clearProgress();
289
- const addOut = `${res.stdout}${res.stderr}`;
290
- if (res.error === undefined && res.exitCode === 0) {
291
- refreshed++;
292
- } else if (addOut.includes("could not find a Codex CLI binary")) {
293
- recordFailure(
294
- ctx,
295
- `Codex plugin refresh hit a stale launcher/wrapper on PATH - install current standalone Codex with: ${standaloneInstallCommand(ctx)}`,
296
- );
297
- failed++;
298
- } else {
299
- recordFailure(
300
- ctx,
301
- `Codex plugin refresh failed for ${pluginId}: ${processFailureSummary(res)}; run manually: codex plugin add ${pluginId}`,
302
- );
303
- failed++;
304
- }
305
- }
306
-
307
- if (refreshed > 0) {
308
- change(`Codex plugins synced (plugins: ~${refreshed})`);
309
- ctx.nextStepTriggers.codexRestart = true;
310
- }
311
- if (ctx.skipPluginRefresh && pluginIds.length === 0)
312
- verbose("Codex plugins already installed; refresh-only updates skipped");
313
- if (failed > 0)
314
- warn(`${failed} Codex plugin operation(s) failed — re-run sync or install manually`);
315
- }
@@ -1,25 +0,0 @@
1
- /**
2
- * EngineNative Codex status reporting: summary lines and next-step hints.
3
- */
4
- import { codexHome } from "./codexPaths";
5
- import { p } from "./exec";
6
- import { enabledPluginIds } from "./codexPlugins";
7
- import type { Ctx } from "./index";
8
-
9
- // -------------------------------------------------------------- summary ----
10
-
11
- export function codexSummary(ctx: Ctx): void {
12
- const { echo } = ctx.services.logger;
13
- const codexDir = codexHome(ctx.home);
14
- echo(`Codex: ${codexDir}`);
15
- if (!ctx.dryRun) {
16
- const count = enabledPluginIds(p(codexDir, "config.toml")).length;
17
- echo(`Codex plugins: ${count} enabled in config.toml`);
18
- }
19
- }
20
-
21
- export function codexNextSteps(ctx: Ctx): Array<string> {
22
- return ctx.verbose || ctx.nextStepTriggers.codexRestart
23
- ? ["Restart Codex to load any refreshed plugins, skills, or tools."]
24
- : [];
25
- }