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,206 +0,0 @@
1
- import { Command, Flag } from "effect/cli";
2
- import { Console, Effect } from "effect";
3
- import { engineCapture, type EngineCaptureError } from "../engine";
4
- import {
5
- deployedClaudeSettings,
6
- deployedCodexModel,
7
- installedPluginsState,
8
- pluginsView,
9
- skillsView,
10
- sotClaudeSettings,
11
- sotCodexModel,
12
- } from "../manifests";
13
- import { kitHome } from "../kitHome";
14
-
15
- const json = Flag.Boolean("json").pipe(
16
- Flag.withDescription("Machine-readable output"),
17
- Flag.withDefault(false),
18
- );
19
-
20
- interface Drift {
21
- readonly setting: string;
22
- readonly deployed: string;
23
- readonly sot: string;
24
- readonly drifted: boolean;
25
- }
26
-
27
- type ClaudeDeployment =
28
- | { readonly state: "absent" }
29
- | { readonly state: "valid"; readonly settings: Record<string, unknown> }
30
- | { readonly state: "malformed"; readonly diagnostic: string };
31
-
32
- const MALFORMED_PLUGINS_DIAGNOSTIC =
33
- "installed Claude plugins file must contain a JSON object with an object 'plugins' field";
34
-
35
- const captureToolchainStatus = () =>
36
- engineCapture(["toolchain", "check"]).pipe(
37
- Effect.map((table) => ({ state: "valid" as const, table })),
38
- Effect.catch((error: EngineCaptureError) =>
39
- Effect.succeed({
40
- state: "failed" as const,
41
- table: "",
42
- diagnostic: error.diagnostic,
43
- exitCode: error.code,
44
- }),
45
- ),
46
- );
47
-
48
- const readClaudeDeployment = (): ClaudeDeployment => {
49
- try {
50
- const settings: unknown = deployedClaudeSettings();
51
- if (settings === undefined) return { state: "absent" };
52
- if (settings === null || typeof settings !== "object" || Array.isArray(settings)) {
53
- return {
54
- state: "malformed",
55
- diagnostic: "deployed Claude settings must contain a JSON object",
56
- };
57
- }
58
- return { state: "valid", settings: settings as Record<string, unknown> };
59
- } catch (error) {
60
- const detail = error instanceof Error ? error.message : String(error);
61
- return {
62
- state: "malformed",
63
- diagnostic: `deployed Claude settings contain invalid JSON: ${detail}`,
64
- };
65
- }
66
- };
67
-
68
- const gatherDrift = (): {
69
- readonly drift: Array<Drift>;
70
- readonly claudeDeployment: ClaudeDeployment;
71
- } => {
72
- const sot = sotClaudeSettings();
73
- const claudeDeployment = readClaudeDeployment();
74
- const row = (setting: string, deployed: unknown, sotVal: unknown): Drift => {
75
- const d = String(deployed ?? "(unset)");
76
- const s = String(sotVal ?? "(unset)");
77
- return { setting, deployed: d, sot: s, drifted: d !== s };
78
- };
79
- const codex = row("codex.model", deployedCodexModel(), sotCodexModel());
80
- if (claudeDeployment.state !== "valid") {
81
- return {
82
- claudeDeployment,
83
- drift: [
84
- {
85
- setting: "claude.settings",
86
- deployed: `(${claudeDeployment.state})`,
87
- sot: "present",
88
- drifted: true,
89
- },
90
- codex,
91
- ],
92
- };
93
- }
94
-
95
- const dep = claudeDeployment.settings;
96
- const env =
97
- dep.env !== null && typeof dep.env === "object" && !Array.isArray(dep.env)
98
- ? (dep.env as Record<string, unknown>)
99
- : {};
100
- return {
101
- claudeDeployment,
102
- drift: [
103
- row("claude.model", dep.model, sot.model),
104
- row("claude.effortLevel", dep.effortLevel, sot.effortLevel),
105
- row(
106
- "claude.compactWindow",
107
- env.CLAUDE_CODE_AUTO_COMPACT_WINDOW,
108
- sot.env?.CLAUDE_CODE_AUTO_COMPACT_WINDOW,
109
- ),
110
- codex,
111
- ],
112
- };
113
- };
114
-
115
- export const statusCommand = Command.make("status", { json }, (config) =>
116
- Effect.gen(function* () {
117
- const { drift, claudeDeployment } = gatherDrift();
118
- const plugins = pluginsView();
119
- const pluginsState = installedPluginsState();
120
- const skills = skillsView();
121
- const toolchain = yield* captureToolchainStatus();
122
- const diagnostics = new Array<{ source: string; message: string; exitCode: number }>();
123
- if (claudeDeployment.state === "malformed") {
124
- diagnostics.push({
125
- source: "claude.settings",
126
- message: claudeDeployment.diagnostic,
127
- exitCode: 1,
128
- });
129
- }
130
- if (pluginsState === "malformed") {
131
- diagnostics.push({
132
- source: "claude.plugins",
133
- message: MALFORMED_PLUGINS_DIAGNOSTIC,
134
- exitCode: 1,
135
- });
136
- }
137
- if (toolchain.state === "failed") {
138
- diagnostics.push({
139
- source: "toolchain",
140
- message: toolchain.diagnostic ?? "toolchain capture failed",
141
- exitCode: toolchain.exitCode ?? 1,
142
- });
143
- }
144
-
145
- if (config.json) {
146
- const deployment =
147
- claudeDeployment.state === "malformed"
148
- ? { claude: { state: claudeDeployment.state, diagnostic: claudeDeployment.diagnostic } }
149
- : { claude: { state: claudeDeployment.state } };
150
- yield* Console.log(
151
- JSON.stringify(
152
- {
153
- kitHome: kitHome(),
154
- deployment,
155
- drift,
156
- plugins,
157
- skills,
158
- toolchain,
159
- diagnostics,
160
- },
161
- null,
162
- 2,
163
- ),
164
- );
165
- } else {
166
- yield* Console.log(`Kit home: ${kitHome()}\n`);
167
- yield* Console.log("Deployed vs SoT (drift is expected for deploy-time modifiers):");
168
- for (const d of drift) {
169
- const mark = d.drifted ? "≠" : "=";
170
- yield* Console.log(
171
- ` ${d.setting.padEnd(22)} deployed=${d.deployed} ${mark} SoT=${d.sot}`,
172
- );
173
- }
174
- if (claudeDeployment.state === "malformed") {
175
- yield* Console.log(` ERROR claude.settings: ${claudeDeployment.diagnostic}`);
176
- }
177
- if (pluginsState === "malformed") {
178
- yield* Console.log(` ERROR claude.plugins: ${MALFORMED_PLUGINS_DIAGNOSTIC}`);
179
- }
180
- yield* Console.log("\nToolchain:");
181
- if (toolchain.state === "failed") {
182
- yield* Console.log(` ERROR: ${toolchain.diagnostic}`);
183
- } else {
184
- yield* Console.log(toolchain.table.trimEnd());
185
- }
186
- const enabled = plugins.filter((p) => p.sot === "true").length;
187
- yield* Console.log(
188
- `\nPlugins: ${plugins.length} known (${enabled} SoT-enabled) — details: docks-kit plugins list`,
189
- );
190
- const installed = skills.filter((s) => s.installed).length;
191
- yield* Console.log(
192
- `Skills: ${skills.length} known (${installed} installed) — details: docks-kit skills list`,
193
- );
194
- }
195
-
196
- if (diagnostics.length > 0) {
197
- yield* Effect.sync(() => {
198
- process.exitCode = diagnostics[0]?.exitCode ?? 1;
199
- });
200
- }
201
- }),
202
- ).pipe(
203
- Command.withDescription(
204
- "Doctor view: deployed-vs-SoT drift, toolchain, and plugin/skill counts.",
205
- ),
206
- );
@@ -1,89 +0,0 @@
1
- import { sotClaudeSettings, topLevelTomlString, type Tool } from "./manifests";
2
- import { payloadText } from "./payload";
3
-
4
- export const CLAUDE_EFFORT_LEVELS = ["low", "medium", "high", "xhigh"] as const;
5
- export const CODEX_REASONING_EFFORTS = [
6
- "none",
7
- "minimal",
8
- "low",
9
- "medium",
10
- "high",
11
- "xhigh",
12
- "max",
13
- "ultra",
14
- ] as const;
15
- export const CLAUDE_ADVISOR_STATES = ["on", "off", "default"] as const;
16
-
17
- const VERIFIED = "2026-07-10";
18
- const ADVISOR_VERIFIED = "2026-09-22";
19
- const DEFAULT = "default";
20
-
21
- const upstreamEfforts = (tool: Tool): ReadonlyArray<string> =>
22
- tool === "claude" ? CLAUDE_EFFORT_LEVELS : CODEX_REASONING_EFFORTS;
23
-
24
- export const effortModifierValues = (tool: Tool): ReadonlyArray<string> => [
25
- ...upstreamEfforts(tool),
26
- DEFAULT,
27
- ];
28
-
29
- export const effortValueGrammar = (tool: Tool): string => effortModifierValues(tool).join("|");
30
-
31
- export const effortFlagGrammar = (tool: Tool): string =>
32
- `--${tool}-effort=<${effortValueGrammar(tool)}>`;
33
-
34
- export const advisorValueGrammar = (): string => CLAUDE_ADVISOR_STATES.join("|");
35
-
36
- export const advisorFlagGrammar = (): string => `--claude-advisor=<${advisorValueGrammar()}>`;
37
-
38
- export const isEffortModifierValue = (tool: Tool, value: string): boolean =>
39
- effortModifierValues(tool).includes(value);
40
-
41
- export function validateEffortDefault(tool: Tool, value: unknown): string {
42
- const toolName = tool === "claude" ? "Claude" : "Codex";
43
- const setting = tool === "claude" ? "effortLevel" : "model_reasoning_effort";
44
- if (typeof value !== "string" || value === "") {
45
- throw new Error(`Embedded SoT ${toolName} ${setting} is missing`);
46
- }
47
- if (!upstreamEfforts(tool).includes(value)) {
48
- throw new Error(
49
- `Embedded SoT ${toolName} ${setting} '${value}' is outside the verified catalog`,
50
- );
51
- }
52
- return value;
53
- }
54
-
55
- export function sotEffort(tool: Tool): string {
56
- const value =
57
- tool === "claude"
58
- ? sotClaudeSettings().effortLevel
59
- : topLevelTomlString(payloadText("SoT/.codex/config.toml"), "model_reasoning_effort");
60
- return validateEffortDefault(tool, value);
61
- }
62
-
63
- export function resolveEffort(tool: Tool, value: string): string {
64
- if (value === DEFAULT) return sotEffort(tool);
65
- if (!upstreamEfforts(tool).includes(value)) {
66
- throw new Error(`Invalid ${tool} effort '${value}'`);
67
- }
68
- return value;
69
- }
70
-
71
- export function effortCatalog(tool: Tool): string {
72
- const setting = tool === "claude" ? "effortLevel" : "model_reasoning_effort";
73
- const lines = [
74
- `Available ${tool} effort levels (${setting}; verified ${VERIFIED}):`,
75
- ...upstreamEfforts(tool).map((value) => ` ${value}`),
76
- ` default — SoT: ${sotEffort(tool)}`,
77
- ];
78
- if (tool === "codex") lines.push(" (support is model-dependent)");
79
- return lines.join("\n");
80
- }
81
-
82
- export function advisorCatalog(): string {
83
- return [
84
- `Available claude advisor states (advisorModel; verified ${ADVISOR_VERIFIED}):`,
85
- " on — set advisorModel: opus",
86
- " off — unset advisorModel",
87
- " default — SoT: off (unset)",
88
- ].join("\n");
89
- }
@@ -1,301 +0,0 @@
1
- /**
2
- * EngineNative LSP server probes, `sync claude` installs, and the
3
- * `toolchain upgrade` npm upgrade. The php-lsp,
4
- * typescript-lsp, and rust-analyzer-lsp plugins are no-ops without their
5
- * server binaries, so this pass installs the missing ones. Message strings
6
- * and spawned argv are part of the contract.
7
- */
8
- import {
9
- defaultProbeExecutor,
10
- npmGlobalVersions,
11
- VERSION_PROBE_LIMIT_MS,
12
- type ToolId,
13
- } from "./deps";
14
- import { realpathSync } from "node:fs";
15
- import { capture, spawnProcess } from "./exec";
16
- import type { Ctx } from "./index";
17
- import { isObject, parseJson } from "./jq";
18
- import { belowFloor, field, installedVersion, isNewer } from "./toolchain";
19
- import { payloadText } from "../payload";
20
-
21
- function lspPkg(ctx: Ctx, tool: string, pkg: string): string | undefined {
22
- const version = field(tool, "verified");
23
- if (version !== "") return `${pkg}@${version}`;
24
- ctx.services.logger.warn(
25
- `Skipping ${pkg} install: ${tool} has no verified version in SoT/toolchain.json`,
26
- );
27
- return undefined;
28
- }
29
-
30
- /**
31
- * npm treats a package's `engines` field as advisory unless the host opted
32
- * into engine-strict, so installing typescript-language-server 6 on an older
33
- * Node succeeds and then fails at every startup. Report the host Node version
34
- * when it is too old, and the empty string when the install is safe.
35
- */
36
- async function nodeBelowServerFloor(ctx: Ctx): Promise<string> {
37
- const floor = field("node", "floor");
38
- if (floor === "") return "";
39
- const installed = await installedVersion(ctx, "node");
40
- return belowFloor(installed, floor) ? installed : "";
41
- }
42
-
43
- /** npm-global channel: intelephense, typescript-language-server, typescript. */
44
- async function installNpmServers(ctx: Ctx, missing: ReadonlyArray<string>): Promise<void> {
45
- const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger;
46
- if (missing.length === 0) return;
47
- const specs = missing.join(" ");
48
- if (ctx.dryRun) {
49
- echo(`[dry-run] would install: npm install -g ${specs}`);
50
- return;
51
- }
52
-
53
- if (ctx.services.deps.probe("npm").state === "missing") {
54
- ctx.services.deps.warnMissing(
55
- "npm",
56
- ctx.services.logger,
57
- `cannot install LSP servers (${specs}); the php-lsp/typescript-lsp plugins stay no-ops`,
58
- );
59
- return;
60
- }
61
-
62
- verbose(`Installing LSP servers via npm: ${specs}...`);
63
- progress(`Installing LSP servers via npm: ${specs}...`);
64
- const installResult = await spawnProcess("npm", ["install", "-g", ...missing], {
65
- stdio: "ignore",
66
- });
67
- clearProgress();
68
- if (installResult.exitCode === 0) {
69
- change(`LSP servers installed (${specs})`);
70
- ctx.nextStepTriggers.claudeRestart = true;
71
- } else {
72
- warn(`npm install -g ${specs} failed. Try manually: npm install -g ${specs}`);
73
- }
74
- }
75
-
76
- /**
77
- * rustup channel: rust-analyzer ships no npm package, and upstream's first
78
- * recommendation is the rustup component, which tracks the toolchain the host
79
- * already trusts. The component version therefore follows that toolchain, so
80
- * the manifest row carries no verified pin - the stance bubblewrap already
81
- * takes for a distro package.
82
- */
83
- async function installRustAnalyzer(ctx: Ctx): Promise<void> {
84
- const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger;
85
- if (ctx.dryRun) {
86
- echo("[dry-run] would install: rustup component add rust-analyzer");
87
- return;
88
- }
89
- verbose("Installing rust-analyzer via rustup...");
90
- progress("Installing rust-analyzer via rustup...");
91
- const result = await spawnProcess("rustup", ["component", "add", "rust-analyzer"], {
92
- stdio: "ignore",
93
- });
94
- clearProgress();
95
- if (result.exitCode === 0) {
96
- change("LSP server installed (rust-analyzer via rustup)");
97
- ctx.nextStepTriggers.claudeRestart = true;
98
- } else {
99
- warn(
100
- "rustup component add rust-analyzer failed. Try manually: rustup component add rust-analyzer",
101
- );
102
- }
103
- }
104
-
105
- /**
106
- * rustup links a rust-analyzer proxy into ~/.cargo/bin even when the
107
- * component is not installed, and that proxy reports no version. With rustup
108
- * present, a PATH hit without a version counts as missing. A probe that does
109
- * not answer in time tells nothing about the component, and the install would
110
- * wait on the same rustup, so that hit does not count as missing.
111
- */
112
- async function rustAnalyzerMissing(ctx: Ctx, rustupPresent: boolean): Promise<boolean> {
113
- if (ctx.services.deps.probe("rust-analyzer").state === "missing") return true;
114
- if (!rustupPresent) return false;
115
- const reading = await ctx.services.deps.versionReading("rust-analyzer");
116
- if (reading.kind === "timed-out") {
117
- ctx.services.logger.warn(
118
- `rust-analyzer --version did not answer within ${VERSION_PROBE_LIMIT_MS / 1000} s; skipped the rust-analyzer install check. Run rust-analyzer --version to see what it waits for, then re-run sync.`,
119
- );
120
- return false;
121
- }
122
- return reading.value === "";
123
- }
124
-
125
- export async function syncLspServers(ctx: Ctx): Promise<void> {
126
- const { echo, verbose, warn } = ctx.services.logger;
127
- const sot = parseJson(payloadText("SoT/.claude/settings.json"));
128
- const enabled =
129
- sot !== undefined && isObject(sot) && isObject(sot["enabledPlugins"])
130
- ? sot["enabledPlugins"]
131
- : undefined;
132
- if (enabled === undefined) return;
133
- const enables = (plugin: string): boolean =>
134
- Object.prototype.hasOwnProperty.call(enabled, plugin);
135
- const hasPhp = enables("php-lsp@claude-plugins-official");
136
- const hasTs = enables("typescript-lsp@claude-plugins-official");
137
- const hasRust = enables("rust-analyzer-lsp@claude-plugins-official");
138
- if (!hasPhp && !hasTs && !hasRust) return;
139
-
140
- const phpMissing = hasPhp && ctx.services.deps.probe("intelephense").state === "missing";
141
- const tsServerMissing =
142
- hasTs && ctx.services.deps.probe("typescript-language-server").state === "missing";
143
- const tscMissing = hasTs && ctx.services.deps.probe("tsc").state === "missing";
144
- const rustupPresent = ctx.services.deps.probe("rustup").state === "present";
145
- const rustMissing = hasRust && (await rustAnalyzerMissing(ctx, rustupPresent));
146
- // A host without rustup does no Rust work, so the plugin has nothing to
147
- // serve there. Installing is impossible and warning every sync would name no
148
- // action the user wants, so that host is not counted as missing a tool.
149
- const rustInstallable = rustMissing && rustupPresent;
150
- if (rustMissing && !rustInstallable) {
151
- verbose(
152
- "Skipping rust-analyzer: rustup is not installed, so the rust-analyzer-lsp plugin stays a no-op",
153
- );
154
- }
155
-
156
- const missingToolCount =
157
- Number(phpMissing) + Number(tsServerMissing) + Number(tscMissing) + Number(rustInstallable);
158
- if (missingToolCount === 0) {
159
- if (ctx.dryRun) {
160
- echo("[dry-run] LSP server binaries present");
161
- } else {
162
- verbose("LSP server binaries present");
163
- }
164
- return;
165
- }
166
-
167
- const blockingNode = tsServerMissing ? await nodeBelowServerFloor(ctx) : "";
168
- if (blockingNode !== "") {
169
- warn(
170
- `Skipping typescript-language-server install: Node ${blockingNode} is older than the ${field("node", "floor")} that version requires. Upgrade Node, then re-run sync.`,
171
- );
172
- }
173
- const missing = [
174
- phpMissing ? lspPkg(ctx, "intelephense", "intelephense") : undefined,
175
- tsServerMissing && blockingNode === ""
176
- ? lspPkg(ctx, "typescript-language-server", "typescript-language-server")
177
- : undefined,
178
- tscMissing ? lspPkg(ctx, "tsc", "typescript") : undefined,
179
- ].filter((spec): spec is string => spec !== undefined);
180
-
181
- await installNpmServers(ctx, missing);
182
- if (rustInstallable) await installRustAnalyzer(ctx);
183
- }
184
-
185
- /** Kit-pinned npm-global LSP packages: manifest tool id and npm package name. */
186
- const NPM_SERVERS: ReadonlyArray<readonly [ToolId, string]> = [
187
- ["intelephense", "intelephense"],
188
- ["typescript-language-server", "typescript-language-server"],
189
- ["tsc", "typescript"],
190
- ];
191
-
192
- /**
193
- * `toolchain upgrade`: move each kit-pinned npm-global LSP package that npm
194
- * owns and that sits below its `verified` pin to that exact pin. A copy that
195
- * npm does not own came from another installer, so it is named and left
196
- * alone. A missing package stays missing: `sync claude` owns first installs.
197
- */
198
- export async function upgradeLspServers(ctx: Ctx): Promise<number> {
199
- const { change, clearProgress, echo, err, progress, verbose, warn } = ctx.services.logger;
200
- if (ctx.services.deps.probe("npm").state === "missing") {
201
- err("toolchain upgrade needs npm: the kit installs its LSP servers with npm install -g");
202
- return 1;
203
- }
204
- const owned = await npmGlobalVersions(defaultProbeExecutor);
205
- const prefix = await capture("npm", ["prefix", "-g"]);
206
- const windows = ctx.services.platform.name() === "windows";
207
- const comparable = (path: string): string => {
208
- const slashed = path.replaceAll("\\", "/");
209
- return windows ? slashed.toLowerCase() : slashed;
210
- };
211
- const resolved = (path: string): string => {
212
- try {
213
- return realpathSync(path);
214
- } catch {
215
- return path;
216
- }
217
- };
218
- // A PATH entry is the npm copy of `pkg` when the file it resolves to lies in
219
- // that package's own directory: <prefix>/lib/node_modules/<pkg> on POSIX,
220
- // where npm's bin entries are links into it. Any other file under the prefix
221
- // does not count, because a system Node uses /usr or /usr/local as its prefix
222
- // and distro binaries live there too. npm writes Windows shims straight into
223
- // <prefix> instead of linking, so there a shim in <prefix> itself counts.
224
- const npmRoot = prefix === "" ? "" : `${comparable(resolved(prefix))}/`;
225
- const isNpmCopy = (path: string, pkg: string): boolean => {
226
- const packageDir = `${npmRoot}${windows ? "" : "lib/"}node_modules/${comparable(pkg)}/`;
227
- if (comparable(resolved(path)).startsWith(packageDir)) return true;
228
- const entry = comparable(path);
229
- return windows && entry.slice(0, entry.lastIndexOf("/") + 1) === `${comparable(prefix)}/`;
230
- };
231
-
232
- const targets: Array<readonly [string, string]> = [];
233
- const moves: Array<string> = [];
234
- for (const [tool, pkg] of NPM_SERVERS) {
235
- const verified = field(tool, "verified");
236
- if (verified === "") continue;
237
- const installed = owned[pkg];
238
- const probe = ctx.services.deps.probe(tool);
239
- const onPath = probe.state === "present" ? (probe.path ?? "") : "";
240
- if (installed === undefined) {
241
- if (onPath !== "") {
242
- warn(
243
- `Skipping ${pkg}: ${onPath} is not an npm global package. Upgrade it with the tool that installed it.`,
244
- );
245
- } else {
246
- verbose(`${pkg} is not installed; sync claude installs it when its plugin is enabled`);
247
- }
248
- continue;
249
- }
250
- if (onPath !== "" && npmRoot !== "" && !isNpmCopy(onPath, pkg)) {
251
- warn(
252
- `${tool} on PATH is ${onPath}, not the npm global copy under ${prefix}; an upgrade changes only the npm copy`,
253
- );
254
- }
255
- if (!isNewer(verified, installed)) {
256
- verbose(`${pkg} up to date (${installed}, verified ${verified})`);
257
- continue;
258
- }
259
- if (tool === "typescript-language-server") {
260
- const blockingNode = await nodeBelowServerFloor(ctx);
261
- if (blockingNode !== "") {
262
- warn(
263
- `Skipping typescript-language-server upgrade: Node ${blockingNode} is older than the ${field("node", "floor")} that version requires. Upgrade Node first.`,
264
- );
265
- continue;
266
- }
267
- }
268
- targets.push([pkg, verified]);
269
- moves.push(`${pkg} ${installed} -> ${verified}`);
270
- }
271
-
272
- if (targets.length === 0) {
273
- echo("npm LSP servers: nothing to upgrade");
274
- return 0;
275
- }
276
- const specs = targets.map(([pkg, verified]) => `${pkg}@${verified}`);
277
- const command = `npm install -g ${specs.join(" ")}`;
278
- if (ctx.dryRun) {
279
- echo(`[dry-run] would upgrade (${moves.join(", ")}): ${command}`);
280
- return 0;
281
- }
282
- progress(`Upgrading LSP servers via npm: ${specs.join(" ")}...`);
283
- const result = await spawnProcess("npm", ["install", "-g", ...specs], { stdio: "ignore" });
284
- clearProgress();
285
- if (result.exitCode !== 0) {
286
- err(`${command} failed. Try manually: ${command}`);
287
- return 1;
288
- }
289
- // npmGlobalVersions memoizes per executor, so a fresh executor object reads
290
- // the inventory npm holds after the install.
291
- const after = await npmGlobalVersions({ ...defaultProbeExecutor });
292
- const short = targets
293
- .filter(([pkg, verified]) => after[pkg] !== verified)
294
- .map(([pkg, verified]) => `${pkg} is ${after[pkg] ?? "missing"}, expected ${verified}`);
295
- if (short.length > 0) {
296
- err(`npm install -g exited 0, but npm ls -g reports: ${short.join("; ")}`);
297
- return 1;
298
- }
299
- change(`LSP servers upgraded (${moves.join(", ")}); restart Claude Code to load them`);
300
- return 0;
301
- }