docks-kit 0.20.5 → 0.20.8

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 (72) hide show
  1. package/AGENTS.md +19 -17
  2. package/README.md +17 -6
  3. package/cli/docs/command-guards.md +269 -0
  4. package/cli/docs/install.md +23 -12
  5. package/cli/docs/models.md +3 -2
  6. package/cli/docs/modifiers.md +4 -3
  7. package/cli/docs/omp-context.md +9 -2
  8. package/cli/docs/omp-models.md +61 -31
  9. package/cli/docs/plugins.md +12 -7
  10. package/cli/docs/sync-layers.md +26 -9
  11. package/cli/docs/toolchain.md +7 -4
  12. package/cli/src/argv.ts +2 -0
  13. package/cli/src/argvSurface.ts +23 -0
  14. package/cli/src/argvValidate.ts +3 -3
  15. package/cli/src/commands/docs.ts +6 -1
  16. package/cli/src/commands/harnesses.ts +15 -4
  17. package/cli/src/commands/omp.ts +92 -41
  18. package/cli/src/commands/status.ts +15 -0
  19. package/cli/src/commands/sync.ts +6 -6
  20. package/cli/src/commands/toolchain.ts +8 -2
  21. package/cli/src/commands/update.ts +51 -10
  22. package/cli/src/engine-native/DESIGN.md +56 -35
  23. package/cli/src/engine-native/atomicWrite.ts +64 -0
  24. package/cli/src/engine-native/claudeLsp.ts +9 -2
  25. package/cli/src/engine-native/claudeOptionalPlugins.ts +19 -6
  26. package/cli/src/engine-native/claudePluginPasses.ts +77 -21
  27. package/cli/src/engine-native/claudeRemovals.ts +245 -57
  28. package/cli/src/engine-native/claudeRetired.ts +1 -1
  29. package/cli/src/engine-native/claudeSettings.ts +46 -19
  30. package/cli/src/engine-native/claudeSettingsModifiers.ts +3 -3
  31. package/cli/src/engine-native/claudeSync.ts +18 -16
  32. package/cli/src/engine-native/codexConfig.ts +72 -12
  33. package/cli/src/engine-native/codexHooks.ts +3 -3
  34. package/cli/src/engine-native/codexPaths.ts +14 -0
  35. package/cli/src/engine-native/codexPlugins.ts +48 -23
  36. package/cli/src/engine-native/codexStatus.ts +2 -1
  37. package/cli/src/engine-native/codexSync.ts +33 -7
  38. package/cli/src/engine-native/codexToml.ts +161 -35
  39. package/cli/src/engine-native/deps.ts +4 -9
  40. package/cli/src/engine-native/engineCtx.ts +42 -14
  41. package/cli/src/engine-native/exec.ts +28 -1
  42. package/cli/src/engine-native/harnesses.ts +32 -8
  43. package/cli/src/engine-native/index.ts +6 -1
  44. package/cli/src/engine-native/kitDb.ts +12 -6
  45. package/cli/src/engine-native/liveModels.ts +2 -1
  46. package/cli/src/engine-native/models.ts +6 -3
  47. package/cli/src/engine-native/modes.ts +15 -10
  48. package/cli/src/engine-native/ompFileDeploy.ts +3 -4
  49. package/cli/src/engine-native/ompMarketplace.ts +9 -7
  50. package/cli/src/engine-native/ompOverlay.ts +39 -13
  51. package/cli/src/engine-native/ompPaths.ts +20 -9
  52. package/cli/src/engine-native/ompPlugins.ts +16 -15
  53. package/cli/src/engine-native/ompSync.ts +11 -6
  54. package/cli/src/engine-native/ompYaml.ts +91 -6
  55. package/cli/src/engine-native/os/darwin.ts +2 -0
  56. package/cli/src/engine-native/os/linux.ts +1 -0
  57. package/cli/src/engine-native/os/posix.ts +17 -5
  58. package/cli/src/engine-native/os/types.ts +2 -2
  59. package/cli/src/engine-native/os/windows.ts +24 -16
  60. package/cli/src/engine-native/skillsInstall.ts +10 -5
  61. package/cli/src/engine-native/skillsLinks.ts +14 -1
  62. package/cli/src/engine-native/skillsManifest.ts +20 -0
  63. package/cli/src/engine-native/skillsPrune.ts +33 -26
  64. package/cli/src/engine-native/skillsSync.ts +6 -3
  65. package/cli/src/engine-native/syncDispatch.ts +32 -18
  66. package/cli/src/engine.ts +29 -3
  67. package/cli/src/generated/sotPayload.ts +14 -14
  68. package/cli/src/main.ts +10 -3
  69. package/cli/src/manifests.ts +29 -11
  70. package/docks-kit +6 -3
  71. package/docks-kit.ps1 +22 -11
  72. package/package.json +1 -1
@@ -3,13 +3,15 @@
3
3
  * with the runtime cutover and deploy-time modifiers is load-bearing and
4
4
  * golden-tested; message strings and JSON semantics are part of the contract.
5
5
  */
6
- import { copyFileSync, existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
6
+ import { copyFileSync, existsSync, readFileSync } from "node:fs";
7
+ import { replaceFile } from "./atomicWrite";
7
8
  import { p } from "./exec";
8
9
  import type { Ctx } from "./index";
9
10
  import { isObject, jqStringify, parseJson, type Json } from "./jq";
10
11
  import { ExitError } from "./parseArgs";
11
12
  import { mergeSettings, reconcileSettings } from "./settings";
12
13
  import { payloadDisplayPath } from "../payload";
14
+ import type { JsonObject } from "./sharedTypes";
13
15
 
14
16
  export interface PreparedClaudeSettings {
15
17
  readonly path: string;
@@ -23,6 +25,33 @@ function assertMaterializedSettings(bytes: string): void {
23
25
  throw new Error("Claude settings contain unresolved runtime sentinels");
24
26
  }
25
27
 
28
+ /**
29
+ * Read the deployed settings document. An unparsable or non-object document
30
+ * aborts the sync, because a merge would replace the user's settings.
31
+ */
32
+ function readDeployedSettings(ctx: Ctx, path: string): { text: string; doc: JsonObject } {
33
+ const text = readFileSync(path, "utf8");
34
+ const doc = parseJson(text);
35
+ if (doc === undefined || !isObject(doc)) {
36
+ const reason = doc === undefined ? "is not valid JSON" : "must contain a JSON object";
37
+ ctx.services.logger.err(
38
+ `Aborting sync: ${path} ${reason}. Fix it manually or delete it to reinstall.`,
39
+ );
40
+ throw new ExitError(1);
41
+ }
42
+ return { text, doc };
43
+ }
44
+
45
+ /**
46
+ * Check the deployed settings before any sync pipeline starts. A document
47
+ * that cannot merge stops the whole sync, so no other harness changes first.
48
+ */
49
+ export function preflightClaudeSettings(ctx: Ctx): void {
50
+ if (!ctx.syncClaude) return;
51
+ const path = p(ctx.home, ".claude", "settings.json");
52
+ if (existsSync(path)) readDeployedSettings(ctx, path);
53
+ }
54
+
26
55
  /** Build the candidate settings bytes before the readiness-gated runtime cutover mutates disk. */
27
56
  export function prepareClaudeSettings(
28
57
  ctx: Ctx,
@@ -31,37 +60,35 @@ export function prepareClaudeSettings(
31
60
  ): PreparedClaudeSettings {
32
61
  const path = p(claudeDir, "settings.json");
33
62
  if (!existsSync(path)) {
34
- const bytes = jqStringify(repo);
63
+ // Write the form the next sync produces, so a second sync finds no change.
64
+ const canonical = ctx.reconcile ? reconcileSettings(repo, {}) : mergeSettings(repo, {});
65
+ const bytes = jqStringify(canonical);
35
66
  assertMaterializedSettings(bytes);
36
67
  return { path, bytes, previousBytes: undefined, changed: true };
37
68
  }
38
69
 
39
- const previousBytes = readFileSync(path, "utf8");
40
- const user = parseJson(previousBytes);
41
- if (user === undefined || !isObject(user)) {
42
- const reason = user === undefined ? "is not valid JSON" : "must contain a JSON object";
43
- ctx.services.logger.err(
44
- `Aborting sync: ${path} ${reason}. Fix it manually or delete it to reinstall.`,
45
- );
46
- throw new ExitError(1);
47
- }
70
+ // engineSync runs this check in preflightClaudeSettings; it stays here for other callers.
71
+ const { text: previousBytes, doc: user } = readDeployedSettings(ctx, path);
48
72
  const merged = ctx.reconcile ? reconcileSettings(repo, user) : mergeSettings(repo, user);
49
73
  const bytes = jqStringify(merged);
50
74
  assertMaterializedSettings(bytes);
51
75
  return { path, bytes, previousBytes, changed: bytes !== previousBytes };
52
76
  }
53
77
 
54
- /** Commit a fully prepared document; callers must finish runtime preparation first. */
55
- export function commitClaudeSettings(ctx: Ctx, prepared: PreparedClaudeSettings): void {
78
+ /**
79
+ * Commit a fully prepared document; callers must finish runtime preparation first.
80
+ * Returns true when the commit copied the previous settings to settings.json.bak.
81
+ */
82
+ export function commitClaudeSettings(ctx: Ctx, prepared: PreparedClaudeSettings): boolean {
56
83
  const { change, verbose } = ctx.services.logger;
57
84
  if (!prepared.changed) {
58
85
  verbose("Settings already in sync");
59
- return;
86
+ return false;
60
87
  }
61
88
 
62
- if (prepared.previousBytes !== undefined) copyFileSync(prepared.path, `${prepared.path}.bak`);
63
- writeFileSync(`${prepared.path}.tmp`, prepared.bytes);
64
- renameSync(`${prepared.path}.tmp`, prepared.path);
89
+ const backedUp = prepared.previousBytes !== undefined;
90
+ if (backedUp) copyFileSync(prepared.path, `${prepared.path}.bak`);
91
+ replaceFile(prepared.path, prepared.bytes);
65
92
  ctx.nextStepTriggers.claudeRestart = true;
66
93
  if (prepared.previousBytes === undefined) {
67
94
  change("Settings installed");
@@ -72,6 +99,7 @@ export function commitClaudeSettings(ctx: Ctx, prepared: PreparedClaudeSettings)
72
99
  } else {
73
100
  change("Settings merged (backup at settings.json.bak)");
74
101
  }
102
+ return backedUp;
75
103
  }
76
104
 
77
105
  export function describeSettingsSync(ctx: Ctx, claudeDir: string): void {
@@ -114,8 +142,7 @@ function jqEditSettings(
114
142
  edit(doc);
115
143
  const out = jqStringify(doc);
116
144
  if (out === before) return false;
117
- writeFileSync(`${userSettings}.tmp`, out);
118
- renameSync(`${userSettings}.tmp`, userSettings);
145
+ replaceFile(userSettings, out);
119
146
  return true;
120
147
  }
121
148
 
@@ -1,6 +1,7 @@
1
1
  /** Atomic top-level Claude settings modifiers, including direct model mode. */
2
2
  import { p } from "./exec";
3
- import { readFileSync, renameSync, writeFileSync } from "node:fs";
3
+ import { readFileSync } from "node:fs";
4
+ import { replaceFile } from "./atomicWrite";
4
5
 
5
6
  import { resolveEffort } from "../efforts";
6
7
  import type { Ctx } from "./index";
@@ -59,8 +60,7 @@ function syncClaudeSetting(ctx: Ctx, edit: ClaudeSettingEdit): void {
59
60
  verbose(edit.unchanged);
60
61
  return;
61
62
  }
62
- writeFileSync(`${userSettings}.tmp`, out);
63
- renameSync(`${userSettings}.tmp`, userSettings);
63
+ replaceFile(userSettings, out);
64
64
  change(edit.changed);
65
65
  ctx.nextStepTriggers.claudeRestart = true;
66
66
  }
@@ -4,14 +4,8 @@
4
4
  * plugins. Message strings, guard order, JSON semantics, and spawned argv are
5
5
  * golden-tested.
6
6
  */
7
- import {
8
- appendFileSync,
9
- existsSync,
10
- mkdirSync,
11
- readFileSync,
12
- renameSync,
13
- writeFileSync,
14
- } from "node:fs";
7
+ import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
8
+ import { replaceFile } from "./atomicWrite";
15
9
  import { bunBootstrap } from "./bun";
16
10
  import { syncClaudeAdvisor, syncClaudeEffort, syncClaudeModel } from "./claudeSettingsModifiers";
17
11
  import {
@@ -74,12 +68,13 @@ export async function claudeSync(ctx: Ctx): Promise<ClaudeRuntimeState> {
74
68
 
75
69
  syncClaudeRuntime(ctx, runtime);
76
70
  syncClaudeMd(ctx, claudeDir);
71
+ let settingsBackedUp = false;
77
72
  if (ctx.dryRun) {
78
73
  describeSettingsSync(ctx, claudeDir);
79
74
  } else {
80
- commitClaudeSettings(ctx, prepared);
75
+ settingsBackedUp = commitClaudeSettings(ctx, prepared);
81
76
  }
82
- syncRemovals(ctx, claudeDir, runtime);
77
+ syncRemovals(ctx, claudeDir, runtime, settingsBackedUp);
83
78
  syncCompactWindow(ctx, claudeDir);
84
79
  syncPermissive(ctx, claudeDir);
85
80
  syncClaudeModel(ctx, ctx.claudeModel);
@@ -140,8 +135,12 @@ function syncClaudeMd(ctx: Ctx, claudeDir: string): void {
140
135
  }
141
136
 
142
137
  const source = payloadText("SoT/.claude/CLAUDE.md");
143
- if (writeTextIfChanged(p(claudeDir, "CLAUDE.md"), source)) {
144
- change("CLAUDE.md synced");
138
+ const target = p(claudeDir, "CLAUDE.md");
139
+ // A first sync can find the user's own global instructions here; keep them.
140
+ const replaced = existsSync(target) && readFileSync(target, "utf8") !== source;
141
+ if (replaced) copyFileSync(target, `${target}.bak`);
142
+ if (writeTextIfChanged(target, source)) {
143
+ change(`CLAUDE.md synced${replaced ? " (backup at CLAUDE.md.bak)" : ""}`);
145
144
  } else {
146
145
  verbose("CLAUDE.md already in sync");
147
146
  }
@@ -189,13 +188,13 @@ function syncClaudeJson(ctx: Ctx): void {
189
188
  if (out === before) {
190
189
  changed = false;
191
190
  } else {
192
- writeFileSync(`${claudeJson}.tmp`, out);
193
- renameSync(`${claudeJson}.tmp`, claudeJson);
191
+ replaceFile(claudeJson, out);
194
192
  }
195
193
  } else {
196
194
  const obj: JsonObject = {};
197
195
  applyFilter(obj);
198
- writeFileSync(claudeJson, jqStringify(obj));
196
+ // The file holds MCP server credentials, so a new file is private to the user.
197
+ replaceFile(claudeJson, jqStringify(obj), { mode: 0o600 });
199
198
  }
200
199
  if (changed) {
201
200
  change(`~/.claude.json updated (showTurnDuration${haveMcp ? ", mcpServers" : ""})`);
@@ -227,7 +226,10 @@ async function syncConnectorEnv(ctx: Ctx): Promise<void> {
227
226
  }
228
227
  }
229
228
 
230
- const target = p(ctx.home, setting.target(process.env["SHELL"]));
229
+ const target = p(
230
+ ctx.home,
231
+ setting.target(process.env["SHELL"], (f) => existsSync(p(ctx.home, f))),
232
+ );
231
233
  if (ctx.dryRun) {
232
234
  echo(`[dry-run] append '${setting.line}' to ${target}`);
233
235
  return;
@@ -4,10 +4,16 @@
4
4
  * be a behavior change. Guard order, message strings, and backup behavior
5
5
  * are golden-tested.
6
6
  */
7
- import { copyFileSync, existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
7
+ import { copyFileSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
8
8
 
9
9
  import { payloadDisplayPath } from "../payload";
10
- import { isTomlHeaderLine, mergeTableSettings, mergeTopLevelSettings } from "./codexToml";
10
+ import { replaceFile } from "./atomicWrite";
11
+ import {
12
+ isTomlHeaderLine,
13
+ mergeTableSettings,
14
+ mergeTopLevelSettings,
15
+ tomlContinuationLines,
16
+ } from "./codexToml";
11
17
  import type { Ctx } from "./index";
12
18
 
13
19
  // --------------------------------------------------------------- config ----
@@ -37,21 +43,26 @@ export function syncConfig(ctx: Ctx, sotConfigText: string, userConfig: string):
37
43
  // overwrite the recovery copy with already-merged content.
38
44
  const before = readFileSync(userConfig, "utf8");
39
45
  const staging = `${userConfig}.merge.tmp`;
40
- // Normalize once before record transforms because CR bytes change table-header identity.
41
- writeFileSync(staging, before.replace(/\r\n/g, "\n"));
46
+ // Normalize once before record transforms: a BOM hides the first key or
47
+ // header, and CR bytes change table-header identity.
48
+ writeFileSync(staging, before.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n"));
42
49
 
43
50
  scrubDeprecatedFeatures(ctx, staging);
44
51
  removeRetiredPluginTables(ctx, staging);
52
+ removeRetiredTopLevelSettings(ctx, staging);
45
53
  mergeTopLevelSettings(sotConfigText, staging);
46
54
  mergeTableSettings(sotConfigText, staging);
47
55
 
48
- if (readFileSync(staging, "utf8") === before) {
49
- rmSync(staging, { force: true });
56
+ const merged = readFileSync(staging, "utf8");
57
+ rmSync(staging, { force: true });
58
+ if (merged === before) {
50
59
  verbose("Codex config already in sync");
51
60
  } else {
52
61
  copyFileSync(userConfig, `${userConfig}.bak`);
53
- renameSync(staging, userConfig);
54
- change("Codex config merged (backup at config.toml.bak; user-only keys/tables preserved)");
62
+ replaceFile(userConfig, merged);
63
+ change(
64
+ "Codex config merged (backup at config.toml.bak; SoT tables replaced wholesale; user-only top-level keys and tables preserved)",
65
+ );
55
66
  ctx.nextStepTriggers.codexRestart = true;
56
67
  }
57
68
  }
@@ -106,8 +117,7 @@ function scrubDeprecatedFeatures(ctx: Ctx, userConfig: string): void {
106
117
  const next = scrubDeprecatedFeaturesText(content);
107
118
  if (next === content) return;
108
119
 
109
- writeFileSync(`${userConfig}.tmp`, next);
110
- renameSync(`${userConfig}.tmp`, userConfig);
120
+ replaceFile(userConfig, next);
111
121
  change("Codex: scrubbed deprecated [features].use_legacy_landlock");
112
122
  }
113
123
 
@@ -152,7 +162,57 @@ export function removeRetiredPluginTables(ctx: Ctx, userConfig: string): void {
152
162
  const present = retiredPluginTables(content);
153
163
  if (present.length === 0) return;
154
164
 
155
- writeFileSync(`${userConfig}.tmp`, removeRetiredPluginTablesText(content));
156
- renameSync(`${userConfig}.tmp`, userConfig);
165
+ replaceFile(userConfig, removeRetiredPluginTablesText(content));
157
166
  for (const id of present) change(`Codex: removed retired plugin table [plugins."${id}"]`);
158
167
  }
168
+
169
+ /**
170
+ * Top-level settings the kit retired. Each sync removes a deployed top-level
171
+ * line that holds exactly the retired kit value. A different user value stays.
172
+ */
173
+ const RETIRED_TOP_LEVEL_SETTINGS: ReadonlyArray<{
174
+ readonly setting: string;
175
+ readonly pattern: RegExp;
176
+ }> = [
177
+ // Codex 0.159.0 deprecated `personality`; "pragmatic" no longer selects a style.
178
+ {
179
+ setting: 'personality = "pragmatic"',
180
+ pattern: /^[ \t]*personality[ \t]*=[ \t]*"pragmatic"[ \t]*$/,
181
+ },
182
+ ];
183
+
184
+ /** Drop top-level lines that hold a retired kit setting; returns the text and the removed settings. */
185
+ function removeRetiredTopLevelSettingsText(content: string): {
186
+ readonly text: string;
187
+ readonly removed: ReadonlyArray<string>;
188
+ } {
189
+ const lines = content.split("\n");
190
+ const continuation = tomlContinuationLines(lines);
191
+ const removed: Array<string> = [];
192
+ const kept: Array<string> = [];
193
+ let inTable = false;
194
+ for (const [index, line] of lines.entries()) {
195
+ if (continuation[index] !== true && !inTable) {
196
+ if (isTomlHeaderLine(line)) {
197
+ inTable = true;
198
+ } else {
199
+ const retired = RETIRED_TOP_LEVEL_SETTINGS.find(({ pattern }) => pattern.test(line));
200
+ if (retired !== undefined) {
201
+ removed.push(retired.setting);
202
+ continue;
203
+ }
204
+ }
205
+ }
206
+ kept.push(line);
207
+ }
208
+ return { text: removed.length === 0 ? content : kept.join("\n"), removed };
209
+ }
210
+
211
+ function removeRetiredTopLevelSettings(ctx: Ctx, userConfig: string): void {
212
+ const { change } = ctx.services.logger;
213
+ const { text, removed } = removeRetiredTopLevelSettingsText(readFileSync(userConfig, "utf8"));
214
+ if (removed.length === 0) return;
215
+
216
+ replaceFile(userConfig, text);
217
+ for (const setting of removed) change(`Codex: removed retired top-level setting ${setting}`);
218
+ }
@@ -3,8 +3,9 @@
3
3
  * docks-kit retired before Codex could import them safely. Guard order,
4
4
  * message strings, and backup behavior are golden-tested.
5
5
  */
6
- import { copyFileSync, existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
6
+ import { copyFileSync, existsSync, readFileSync } from "node:fs";
7
7
 
8
+ import { replaceFile } from "./atomicWrite";
8
9
  import { p } from "./exec";
9
10
  import type { Ctx } from "./index";
10
11
  import { isObject, jqStringify, parseJson, type Json } from "./jq";
@@ -82,8 +83,7 @@ export function removeRetiredImportedHooks(ctx: Ctx, codexDir: string): void {
82
83
  }
83
84
 
84
85
  copyFileSync(hooksFile, `${hooksFile}.bak`);
85
- writeFileSync(`${hooksFile}.tmp`, jqStringify(result.value));
86
- renameSync(`${hooksFile}.tmp`, hooksFile);
86
+ replaceFile(hooksFile, jqStringify(result.value));
87
87
  change(
88
88
  `Codex: removed ${result.removed} retired imported docks-kit SessionStart hook(s) (backup at hooks.json.bak)`,
89
89
  );
@@ -0,0 +1,14 @@
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
+ }
@@ -3,16 +3,10 @@
3
3
  * merge, legacy marketplace removal, and enabled-plugin refresh. Message
4
4
  * strings and backup behavior are golden-tested.
5
5
  */
6
- import {
7
- copyFileSync,
8
- existsSync,
9
- mkdirSync,
10
- readFileSync,
11
- renameSync,
12
- writeFileSync,
13
- } from "node:fs";
6
+ import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
14
7
 
15
8
  import { payloadDisplayPath } from "../payload";
9
+ import { replaceFile } from "./atomicWrite";
16
10
  import { PLUGIN_TABLE_HEADER } from "./codexConfig";
17
11
  import { isTomlHeaderLine } from "./codexToml";
18
12
  import { p, processFailureSummary, spawnProcess } from "./exec";
@@ -23,12 +17,18 @@ import type { JsonObject } from "./sharedTypes";
23
17
 
24
18
  // ---------------------------------------------------------- marketplace ----
25
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
26
  export function syncMarketplace(
27
27
  ctx: Ctx,
28
28
  sotMarketplaceText: string,
29
29
  userMarketplace: string,
30
- ): void {
31
- const { change, echo, verbose } = ctx.services.logger;
30
+ ): string | undefined {
31
+ const { change, echo, verbose, warn } = ctx.services.logger;
32
32
  const sotMarketplace = payloadDisplayPath("SoT/.codex/plugins/marketplace.json");
33
33
  const repo = parseJson(sotMarketplaceText);
34
34
  if (repo === undefined) throw new Error(`invalid SoT marketplace JSON: ${sotMarketplace}`);
@@ -40,6 +40,18 @@ export function syncMarketplace(
40
40
  `invalid deployed Codex marketplace JSON: ${userMarketplace}. Fix or delete it.`,
41
41
  );
42
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
+ }
43
55
  const out = user === undefined ? undefined : jqStringify(mergeMarketplace(repo, user));
44
56
 
45
57
  if (ctx.dryRun) {
@@ -52,25 +64,26 @@ export function syncMarketplace(
52
64
  `[dry-run] merge ${sotMarketplace} -> ${userMarketplace} (backup at ${userMarketplace}.bak)`,
53
65
  );
54
66
  }
55
- return;
67
+ return undefined;
56
68
  }
57
69
 
58
70
  mkdirSync(p(ctx.agentsDir, "plugins"), { recursive: true });
59
71
  if (userText !== undefined && out !== undefined) {
60
72
  if (out === userText) {
61
73
  verbose("Codex marketplace already in sync");
62
- return;
74
+ return undefined;
63
75
  }
64
76
  copyFileSync(userMarketplace, `${userMarketplace}.bak`);
65
- writeFileSync(`${userMarketplace}.tmp`, out);
66
- renameSync(`${userMarketplace}.tmp`, userMarketplace);
77
+ replaceFile(userMarketplace, out);
67
78
  change("Codex marketplace merged (backup at marketplace.json.bak)");
68
79
  ctx.nextStepTriggers.codexRestart = true;
69
80
  } else {
70
- writeFileSync(userMarketplace, sotMarketplaceText);
81
+ // Install the merge form, so the next sync merges to the same bytes.
82
+ writeFileSync(userMarketplace, jqStringify(mergeMarketplace(repo, {})));
71
83
  change("Codex marketplace installed");
72
84
  ctx.nextStepTriggers.codexRestart = true;
73
85
  }
86
+ return undefined;
74
87
  }
75
88
 
76
89
  /**
@@ -190,11 +203,9 @@ function enabledPluginIdsFromText(configText: string): Array<string> {
190
203
  return ids;
191
204
  }
192
205
 
193
- function manualPluginRefreshCommand(sotConfigText: string): string {
194
- const first = enabledPluginIdsFromText(sotConfigText)[0];
195
- return first !== undefined
196
- ? `codex plugin add ${first}`
197
- : "codex plugin add <plugin@marketplace>";
206
+ function manualPluginRefreshHint(pluginIds: ReadonlyArray<string>): string {
207
+ const first = pluginIds[0];
208
+ return first !== undefined ? `; then run: codex plugin add ${first}` : "";
198
209
  }
199
210
 
200
211
  async function installedPluginIdsFromCli(): Promise<Set<string> | undefined> {
@@ -214,9 +225,23 @@ async function installedPluginIdsFromCli(): Promise<Set<string> | undefined> {
214
225
  return ids;
215
226
  }
216
227
 
217
- export async function syncPlugins(ctx: Ctx, sotConfigText: string): Promise<void> {
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> {
218
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
+ );
219
243
  if (ctx.dryRun) {
244
+ if (desiredPluginIds.length === 0) return;
220
245
  echo(
221
246
  ctx.skipPluginRefresh
222
247
  ? "[dry-run] add missing enabled Codex plugins from SoT; skip refresh-only plugin updates"
@@ -227,10 +252,11 @@ export async function syncPlugins(ctx: Ctx, sotConfigText: string): Promise<void
227
252
 
228
253
  if (ctx.services.deps.probe("codex").state === "missing") {
229
254
  warn(
230
- `codex CLI not in PATH - deployed config/marketplace only; install Codex with: ${standaloneInstallCommand(ctx)} | docs: https://developers.openai.com/codex/cli; then run: ${manualPluginRefreshCommand(sotConfigText)}`,
255
+ `codex CLI not in PATH - deployed config/marketplace only; install Codex with: ${standaloneInstallCommand(ctx)} | docs: https://developers.openai.com/codex/cli${manualPluginRefreshHint(desiredPluginIds)}`,
231
256
  );
232
257
  return;
233
258
  }
259
+ if (desiredPluginIds.length === 0) return;
234
260
  if (ctx.services.deps.probe("git").state === "missing") {
235
261
  ctx.services.deps.warnMissing(
236
262
  "git",
@@ -240,7 +266,6 @@ export async function syncPlugins(ctx: Ctx, sotConfigText: string): Promise<void
240
266
  return;
241
267
  }
242
268
 
243
- const desiredPluginIds = enabledPluginIdsFromText(sotConfigText);
244
269
  let pluginIds = desiredPluginIds;
245
270
  if (ctx.skipPluginRefresh) {
246
271
  progress("Checking installed Codex plugins...");
@@ -1,6 +1,7 @@
1
1
  /**
2
2
  * EngineNative Codex status reporting: summary lines and next-step hints.
3
3
  */
4
+ import { codexHome } from "./codexPaths";
4
5
  import { p } from "./exec";
5
6
  import { enabledPluginIds } from "./codexPlugins";
6
7
  import type { Ctx } from "./index";
@@ -9,7 +10,7 @@ import type { Ctx } from "./index";
9
10
 
10
11
  export function codexSummary(ctx: Ctx): void {
11
12
  const { echo } = ctx.services.logger;
12
- const codexDir = p(ctx.home, ".codex");
13
+ const codexDir = codexHome(ctx.home);
13
14
  echo(`Codex: ${codexDir}`);
14
15
  if (!ctx.dryRun) {
15
16
  const count = enabledPluginIds(p(codexDir, "config.toml")).length;
@@ -5,6 +5,7 @@
5
5
  */
6
6
  import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
7
7
 
8
+ import { resolveEffort } from "../efforts";
8
9
  import {
9
10
  payloadBytes,
10
11
  payloadDisplayPath,
@@ -14,8 +15,9 @@ import {
14
15
  } from "../payload";
15
16
  import { syncConfig } from "./codexConfig";
16
17
  import { removeRetiredImportedHooks } from "./codexHooks";
18
+ import { codexHome } from "./codexPaths";
17
19
  import { removeLegacyDocksMarketplace, syncMarketplace, syncPlugins } from "./codexPlugins";
18
- import { syncCodexEffort, syncCodexModel } from "./codexToml";
20
+ import { replaceTopLevelSetting, syncCodexEffort, syncCodexModel } from "./codexToml";
19
21
  import { p, spawnProcess } from "./exec";
20
22
  import type { Ctx } from "./index";
21
23
  import { compareCodepoints } from "./jq";
@@ -25,25 +27,49 @@ export { removeRetiredPluginTablesText } from "./codexConfig";
25
27
  export { codexNextSteps, codexSummary } from "./codexStatus";
26
28
 
27
29
  export async function codexSync(ctx: Ctx): Promise<void> {
28
- const codexDir = p(ctx.home, ".codex");
30
+ const codexDir = codexHome(ctx.home);
29
31
  const sotConfig = payloadText("SoT/.codex/config.toml");
30
32
  const userConfig = p(codexDir, "config.toml");
31
33
 
34
+ // Merge the SoT with the --codex-model / --codex-effort values already applied.
35
+ // A repeated modifier run then merges to the same bytes and keeps config.toml.bak.
36
+ let deployedSotConfig = sotConfig;
37
+ if (ctx.codexModel !== "") {
38
+ deployedSotConfig = replaceTopLevelSetting(
39
+ deployedSotConfig,
40
+ "model",
41
+ `model = "${ctx.codexModel}"`,
42
+ );
43
+ }
44
+ if (ctx.codexEffort !== "") {
45
+ deployedSotConfig = replaceTopLevelSetting(
46
+ deployedSotConfig,
47
+ "model_reasoning_effort",
48
+ `model_reasoning_effort = "${resolveEffort("codex", ctx.codexEffort)}"`,
49
+ );
50
+ }
51
+
32
52
  await ensureBubblewrap(ctx);
33
53
  if (!ctx.dryRun) mkdirSync(codexDir, { recursive: true });
34
- syncConfig(ctx, sotConfig, userConfig);
54
+ // Only a real sync compares against this text; a dry run reads nothing.
55
+ const deployedBefore = ctx.dryRun
56
+ ? undefined
57
+ : existsSync(userConfig)
58
+ ? readFileSync(userConfig, "utf8")
59
+ : "";
60
+ syncConfig(ctx, deployedSotConfig, userConfig);
35
61
  removeRetiredImportedHooks(ctx, codexDir);
36
- syncCodexModel(ctx, ctx.codexModel);
37
- syncCodexEffort(ctx, ctx.codexEffort);
62
+ syncCodexModel(ctx, ctx.codexModel, deployedBefore);
63
+ syncCodexEffort(ctx, ctx.codexEffort, deployedBefore);
38
64
  syncRules(ctx, payloadPaths("SoT/.codex/rules/"), p(codexDir, "rules"));
39
65
  syncAgentsMd(ctx, payloadText("SoT/.codex/AGENTS.md"), p(codexDir, "AGENTS.md"));
40
- syncMarketplace(
66
+ const unresolvedMarketplace = syncMarketplace(
41
67
  ctx,
42
68
  payloadText("SoT/.codex/plugins/marketplace.json"),
43
69
  p(ctx.agentsDir, "plugins", "marketplace.json"),
44
70
  );
45
71
  await removeLegacyDocksMarketplace(ctx, userConfig);
46
- await syncPlugins(ctx, sotConfig);
72
+ await syncPlugins(ctx, sotConfig, unresolvedMarketplace);
47
73
  }
48
74
 
49
75
  // ---------------------------------------------------------- bubblewrap ----