@holmes-lab/holmes-kit 0.31.0 → 0.31.2
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.
- package/CHANGELOG.md +26 -0
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/codex-legacy.d.ts +16 -0
- package/dist/holmes/cli/codex-legacy.js +129 -0
- package/dist/holmes/cli/doctor.js +32 -1
- package/dist/holmes/cli/index.js +24 -0
- package/dist/holmes/cli/upgrade.d.ts +5 -0
- package/dist/holmes/cli/upgrade.js +13 -1
- package/dist/holmes/update/refresh.d.ts +5 -0
- package/dist/holmes/update/refresh.js +23 -0
- package/dist/holmes/update/upgrade-plan.d.ts +28 -0
- package/dist/holmes/update/upgrade-plan.js +31 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
<!-- @implements A-SPEC-209 -->
|
|
8
|
+
## [0.31.2] - 2026-09-30
|
|
9
|
+
|
|
10
|
+
### Fixed
|
|
11
|
+
|
|
12
|
+
- **A project `.codex/config.toml` left by a pre-0.30 init is named and offered for removal** (A-SPEC-721, amended).
|
|
13
|
+
Holmes wires Codex in the user configuration since 0.30, but in a trusted project Codex loads that old file over it:
|
|
14
|
+
a consumer workspace kept starting the 0.29.0 server through a committed `npx @holmes-lab/holmes-kit@0.29.0` pin
|
|
15
|
+
while init and doctor wired and judged the current release. doctor now says `codex legacy wiring` (WARN) with the
|
|
16
|
+
file, its launch and the command to remove it; `init --agent codex` (or `all`) asks before deleting it (default no),
|
|
17
|
+
and a non-interactive run — `upgrade`'s re-pin included — prints the command and deletes nothing. Only a file that is
|
|
18
|
+
exactly Holmes's own wiring is recognised; a comment, another table or key, or any other launch leaves it alone.
|
|
19
|
+
- **doctor names an expired approval** (A-SPEC-178, amended). An `HOLMES_APPROVAL` in `.mcp.json`'s server env whose
|
|
20
|
+
`expires` has passed read `approval channel` PASS ("spec_approve reaches it"); it is now WARN with the expiry (never
|
|
21
|
+
the value) and the fix to remove it.
|
|
22
|
+
|
|
23
|
+
## [0.31.1] - 2026-09-29
|
|
24
|
+
|
|
25
|
+
### Fixed
|
|
26
|
+
|
|
27
|
+
- **`holmes-kit upgrade` asks the registry for the latest version** (A-SPEC-543.2, amended). It read only the update
|
|
28
|
+
cache, which SessionStart refreshes at most once a day, so right after 0.31.0 was published it answered `already up
|
|
29
|
+
to date (current 0.31.0, latest 0.30.0)` and a newer release would not have been installed for up to a day. The
|
|
30
|
+
command now queries the registry (5 s, the same public `dist-tags` the banner uses) and refreshes the cache; when the
|
|
31
|
+
registry cannot be reached it says it used the cache and how old that answer is; an installed version newer than the
|
|
32
|
+
latest is no longer called "already up to date". `--dry-run` asks and shows, and writes nothing.
|
|
33
|
+
|
|
8
34
|
## [0.31.0] - 2026-09-29
|
|
9
35
|
|
|
10
36
|
Post-0.30 hardening (H1–H12) and a new rule for Codex: whether Codex loads its own files is now
|
package/dist/.build-id
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
8bd6277b-mumvdzzj
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
export declare function legacyCodexLayer(target: string): {
|
|
2
|
+
path: string;
|
|
3
|
+
launch: string;
|
|
4
|
+
} | null;
|
|
5
|
+
/**
|
|
6
|
+
* A-SPEC-721 (amendment 2026-09-29) — after init wires Codex: ask before deleting a Holmes-only legacy project file
|
|
7
|
+
* (default no); a non-interactive run (and so `upgrade`'s re-pin) only prints the command; a dry run asks nothing.
|
|
8
|
+
*/
|
|
9
|
+
export declare function offerLegacyCodexRemoval(o: {
|
|
10
|
+
target: string;
|
|
11
|
+
interactive: boolean;
|
|
12
|
+
dryRun: boolean;
|
|
13
|
+
confirm: (question: string) => Promise<boolean>;
|
|
14
|
+
remove: (file: string) => void;
|
|
15
|
+
out: (line: string) => void;
|
|
16
|
+
}): Promise<void>;
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
14
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
15
|
+
}) : function(o, v) {
|
|
16
|
+
o["default"] = v;
|
|
17
|
+
});
|
|
18
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
19
|
+
var ownKeys = function(o) {
|
|
20
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
21
|
+
var ar = [];
|
|
22
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
23
|
+
return ar;
|
|
24
|
+
};
|
|
25
|
+
return ownKeys(o);
|
|
26
|
+
};
|
|
27
|
+
return function (mod) {
|
|
28
|
+
if (mod && mod.__esModule) return mod;
|
|
29
|
+
var result = {};
|
|
30
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
31
|
+
__setModuleDefault(result, mod);
|
|
32
|
+
return result;
|
|
33
|
+
};
|
|
34
|
+
})();
|
|
35
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.legacyCodexLayer = legacyCodexLayer;
|
|
37
|
+
exports.offerLegacyCodexRemoval = offerLegacyCodexRemoval;
|
|
38
|
+
// @implements A-SPEC-721
|
|
39
|
+
const fs = __importStar(require("node:fs"));
|
|
40
|
+
const path = __importStar(require("node:path"));
|
|
41
|
+
const smol_toml_1 = require("smol-toml");
|
|
42
|
+
/**
|
|
43
|
+
* A-SPEC-721 (amendment 2026-09-29) — the project `.codex/config.toml` a pre-0.30 init wrote. Holmes now wires Codex in
|
|
44
|
+
* the user configuration, but in a trusted project Codex loads this file OVER it: measured in a consumer workspace, a
|
|
45
|
+
* committed file pinning `npx @holmes-lab/holmes-kit@0.29.0` kept Codex on the 0.29.0 server while init and doctor
|
|
46
|
+
* wired and judged the current one. Only a file that is exactly Holmes's own legacy wiring is recognised — anything
|
|
47
|
+
* the user wrote or added is left alone.
|
|
48
|
+
*/
|
|
49
|
+
const LEGACY_MAX_BYTES = 64 * 1024;
|
|
50
|
+
const TABLE_KEYS = new Set(['command', 'args', 'env']);
|
|
51
|
+
const ENV_KEYS = new Set(['HOLMES_SPECS', 'HOLMES_MCP_AUTORELOAD']);
|
|
52
|
+
function legacyCodexLayer(target) {
|
|
53
|
+
const file = path.join(target, '.codex', 'config.toml');
|
|
54
|
+
let text;
|
|
55
|
+
try {
|
|
56
|
+
const st = fs.lstatSync(file);
|
|
57
|
+
if (!st.isFile() || st.size > LEGACY_MAX_BYTES)
|
|
58
|
+
return null; // a link or a large file is not what init wrote
|
|
59
|
+
text = fs.readFileSync(file, 'utf8');
|
|
60
|
+
}
|
|
61
|
+
catch {
|
|
62
|
+
return null;
|
|
63
|
+
}
|
|
64
|
+
if (text.split(/\r?\n/).some((l) => l.trim().startsWith('#')))
|
|
65
|
+
return null; // a comment is the user's
|
|
66
|
+
let doc;
|
|
67
|
+
try {
|
|
68
|
+
doc = (0, smol_toml_1.parse)(text);
|
|
69
|
+
}
|
|
70
|
+
catch {
|
|
71
|
+
return null;
|
|
72
|
+
}
|
|
73
|
+
const keys = Object.keys(doc);
|
|
74
|
+
if (keys.length !== 1 || keys[0] !== 'mcp_servers')
|
|
75
|
+
return null;
|
|
76
|
+
const servers = doc.mcp_servers;
|
|
77
|
+
if (servers === null || typeof servers !== 'object' || Array.isArray(servers))
|
|
78
|
+
return null;
|
|
79
|
+
if (Object.keys(servers).length !== 1 || !('holmes-kit' in servers))
|
|
80
|
+
return null;
|
|
81
|
+
const table = servers['holmes-kit'];
|
|
82
|
+
if (table === null || typeof table !== 'object' || Array.isArray(table))
|
|
83
|
+
return null;
|
|
84
|
+
if (!Object.keys(table).every((k) => TABLE_KEYS.has(k)))
|
|
85
|
+
return null;
|
|
86
|
+
const { command, args, env } = table;
|
|
87
|
+
if (typeof command !== 'string' || !Array.isArray(args) || !args.every((a) => typeof a === 'string'))
|
|
88
|
+
return null;
|
|
89
|
+
const words = args;
|
|
90
|
+
const holmesLaunch = command === 'npx'
|
|
91
|
+
? words.some((a) => a.startsWith('@holmes-lab/holmes-kit')) && words[words.length - 1] === 'holmes-mcp'
|
|
92
|
+
: command === 'node' && typeof words[0] === 'string' && /holmes-mcp\.js$/.test(words[0]);
|
|
93
|
+
if (!holmesLaunch)
|
|
94
|
+
return null;
|
|
95
|
+
if (env !== undefined) {
|
|
96
|
+
if (env === null || typeof env !== 'object' || Array.isArray(env))
|
|
97
|
+
return null;
|
|
98
|
+
if (!Object.keys(env).every((k) => ENV_KEYS.has(k)))
|
|
99
|
+
return null;
|
|
100
|
+
}
|
|
101
|
+
return { path: file, launch: [command, ...words].join(' ') };
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* A-SPEC-721 (amendment 2026-09-29) — after init wires Codex: ask before deleting a Holmes-only legacy project file
|
|
105
|
+
* (default no); a non-interactive run (and so `upgrade`'s re-pin) only prints the command; a dry run asks nothing.
|
|
106
|
+
*/
|
|
107
|
+
async function offerLegacyCodexRemoval(o) {
|
|
108
|
+
const legacy = legacyCodexLayer(o.target);
|
|
109
|
+
if (legacy === null)
|
|
110
|
+
return;
|
|
111
|
+
const rel = path.relative(o.target, legacy.path).split(path.sep).join('/');
|
|
112
|
+
const why = `${legacy.path} holds only the Holmes wiring an older init wrote (\`${legacy.launch}\`); in a trusted project Codex loads it instead of the user-level wiring.`;
|
|
113
|
+
if (o.dryRun) {
|
|
114
|
+
o.out(`${why} (dry run — nothing asked or removed)`);
|
|
115
|
+
return;
|
|
116
|
+
}
|
|
117
|
+
if (!o.interactive) {
|
|
118
|
+
o.out(`${why} Remove it: git rm ${rel} (or delete it), then commit.`);
|
|
119
|
+
return;
|
|
120
|
+
}
|
|
121
|
+
o.out(why);
|
|
122
|
+
if (await o.confirm(`Remove the stale Holmes Codex wiring in ${legacy.path}? [y/N] `)) {
|
|
123
|
+
o.remove(legacy.path);
|
|
124
|
+
o.out(`Removed ${legacy.path} — commit the deletion (git add -A ${rel} && git commit).`);
|
|
125
|
+
}
|
|
126
|
+
else {
|
|
127
|
+
o.out(`Kept ${legacy.path}. Remove it later with: git rm ${rel}`);
|
|
128
|
+
}
|
|
129
|
+
}
|
|
@@ -1202,7 +1202,28 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
|
|
|
1202
1202
|
mcpApproval = false;
|
|
1203
1203
|
} // absent or unreadable is "not guaranteed", which is the point
|
|
1204
1204
|
const procApproval = !!process.env.HOLMES_APPROVAL;
|
|
1205
|
-
|
|
1205
|
+
// @implements A-SPEC-178 (amendment 2026-09-29) — an expired approval is not a channel (it read PASS twelve days after
|
|
1206
|
+
// it expired — measured). Only the expiry is printed, never the value.
|
|
1207
|
+
const mcpApprovalExpiry = (() => {
|
|
1208
|
+
try {
|
|
1209
|
+
const raw = fs.readFileSync(path.join(target, '.mcp.json'), 'utf8');
|
|
1210
|
+
const v = JSON.parse(raw).mcpServers?.[init_1.SERVER_NAME]?.env?.HOLMES_APPROVAL;
|
|
1211
|
+
if (typeof v !== 'string')
|
|
1212
|
+
return null;
|
|
1213
|
+
const expires = JSON.parse(v).expires;
|
|
1214
|
+
if (typeof expires !== 'string')
|
|
1215
|
+
return null;
|
|
1216
|
+
const at = Date.parse(expires);
|
|
1217
|
+
return Number.isFinite(at) && at < Date.now() ? expires : null;
|
|
1218
|
+
}
|
|
1219
|
+
catch {
|
|
1220
|
+
return null;
|
|
1221
|
+
}
|
|
1222
|
+
})();
|
|
1223
|
+
if (mcpApproval && mcpApprovalExpiry !== null) {
|
|
1224
|
+
add('approval channel', 'WARN', `The approval in .mcp.json's server env expired on ${(0, codex_oracle_1.clipText)(mcpApprovalExpiry, 40)} — spec_approve will refuse it`, 'Remove HOLMES_APPROVAL from the holmes-kit env in .mcp.json; set a fresh one only when an approval is needed.');
|
|
1225
|
+
}
|
|
1226
|
+
else if (mcpApproval) {
|
|
1206
1227
|
add('approval channel', 'PASS', 'The approval variable is in .mcp.json\'s server env — spec_approve reaches it');
|
|
1207
1228
|
}
|
|
1208
1229
|
else if (!procApproval) {
|
|
@@ -1505,6 +1526,16 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
|
|
|
1505
1526
|
// judged for THIS target only when it carries Holmes's table or the target is Codex-wired;
|
|
1506
1527
|
// otherwise a Claude- or Antigravity-only workspace would inherit another tool's diagnosis.
|
|
1507
1528
|
const targetWantsCodex = codexWiredTarget(target);
|
|
1529
|
+
// @implements A-SPEC-721 (amendment 2026-09-29) — a project file that is exactly Holmes's pre-0.30 wiring replaces the
|
|
1530
|
+
// user-level wiring in a trusted project (a consumer's Codex ran 0.29.0 — measured); named with its launch.
|
|
1531
|
+
{
|
|
1532
|
+
const { legacyCodexLayer } = require('./codex-legacy');
|
|
1533
|
+
const legacy = legacyCodexLayer(target);
|
|
1534
|
+
if (legacy !== null) {
|
|
1535
|
+
const rel = path.relative(target, legacy.path).split(path.sep).join('/');
|
|
1536
|
+
add('codex legacy wiring', 'WARN', `${(0, codex_oracle_1.clipText)(legacy.path)} holds only the Holmes wiring an older init wrote (\`${(0, codex_oracle_1.clipText)(legacy.launch)}\`); in a trusted project Codex loads it instead of the user-level wiring`, `Remove it: git rm ${(0, codex_oracle_1.clipText)(rel)} (or delete it), or run holmes-kit init --agent codex and confirm the removal.`);
|
|
1537
|
+
}
|
|
1538
|
+
}
|
|
1508
1539
|
let cdxRaw;
|
|
1509
1540
|
// @implements A-SPEC-731 (round 6) — decoded strictly: Codex refuses a config that is not UTF-8.
|
|
1510
1541
|
let cdxUndecodable = null;
|
package/dist/holmes/cli/index.js
CHANGED
|
@@ -1261,6 +1261,27 @@ async function main(argv) {
|
|
|
1261
1261
|
process.stdout.write(c.after.split('\n').map((l) => ` | ${(0, doctor_1.terminalSafe)(l)}`).join('\n') + '\n');
|
|
1262
1262
|
}
|
|
1263
1263
|
}
|
|
1264
|
+
// @implements A-SPEC-721 (amendment 2026-09-29) — a Holmes-only project Codex file from a pre-0.30 init replaces the
|
|
1265
|
+
// user-level wiring in a trusted project: offered for removal after the user's yes (non-interactive: the command).
|
|
1266
|
+
if (!opts.remove && agents.includes('codex')) {
|
|
1267
|
+
const { offerLegacyCodexRemoval } = require('./codex-legacy');
|
|
1268
|
+
await offerLegacyCodexRemoval({
|
|
1269
|
+
target: opts.target, dryRun: opts.dryRun === true,
|
|
1270
|
+
interactive: process.stdin.isTTY === true && process.stdout.isTTY === true,
|
|
1271
|
+
confirm: async (q) => {
|
|
1272
|
+
const rl = require('node:readline/promises').createInterface({ input: process.stdin, output: process.stdout });
|
|
1273
|
+
try {
|
|
1274
|
+
const ans = (await rl.question(q)).trim().toLowerCase();
|
|
1275
|
+
return ans === 'y' || ans === 'yes';
|
|
1276
|
+
}
|
|
1277
|
+
finally {
|
|
1278
|
+
rl.close();
|
|
1279
|
+
}
|
|
1280
|
+
},
|
|
1281
|
+
remove: (f) => fs.rmSync(f),
|
|
1282
|
+
out: (l) => process.stdout.write(`${(0, doctor_1.terminalSafe)(l)}\n`),
|
|
1283
|
+
});
|
|
1284
|
+
}
|
|
1264
1285
|
// @implements A-SPEC-543.1 — zero-config upgrade PREPARATION: a successful real wiring records
|
|
1265
1286
|
// WHERE holmes-kit is wired, so `upgrade` later knows every workspace to re-pin. Best-effort by
|
|
1266
1287
|
// contract: a registry problem must never change init's output or exit code.
|
|
@@ -1303,7 +1324,10 @@ async function main(argv) {
|
|
|
1303
1324
|
// non-TTY passes --yes), never a silent auto-install of a gate-enforcing engine.
|
|
1304
1325
|
if (cmd === 'upgrade') {
|
|
1305
1326
|
const { runUpgrade } = require('./upgrade');
|
|
1327
|
+
const { queryRegistryLatest } = require('../update/refresh');
|
|
1306
1328
|
return await runUpgrade({
|
|
1329
|
+
// A-SPEC-543.2 (amendment 2026-09-29): the explicit command asks the registry for latest.
|
|
1330
|
+
queryLatest: () => queryRegistryLatest(),
|
|
1307
1331
|
dryRun: flags['dry-run'] === true,
|
|
1308
1332
|
yes: flags.yes === true,
|
|
1309
1333
|
stdout: (s) => process.stdout.write(s),
|
|
@@ -5,6 +5,11 @@ export interface UpgradeIO {
|
|
|
5
5
|
stdout: (s: string) => void;
|
|
6
6
|
stderr: (s: string) => void;
|
|
7
7
|
confirm: (prompt: string) => Promise<boolean>;
|
|
8
|
+
/**
|
|
9
|
+
* A-SPEC-543.2 (amendment 2026-09-29) — asks the registry for latest; the CLI passes `queryRegistryLatest`. A caller
|
|
10
|
+
* that passes nothing makes no query and the update cache decides.
|
|
11
|
+
*/
|
|
12
|
+
queryLatest?: () => Promise<string | null>;
|
|
8
13
|
}
|
|
9
14
|
/** What upgrade does with one registered workspace — decided once, shown in the plan and done in the run. */
|
|
10
15
|
interface RepinDecision {
|
|
@@ -144,6 +144,18 @@ async function runUpgrade(io) {
|
|
|
144
144
|
const current = currentVersion(root);
|
|
145
145
|
const mode = (0, session_start_1.detectInstallMode)(root);
|
|
146
146
|
const cached = (0, update_notice_1.readCache)(os.homedir(), (p) => fs.readFileSync(p, 'utf8'));
|
|
147
|
+
// A-SPEC-543.2 (amendment 2026-09-29): the registry is asked first — the cache alone kept a release unseen for up to a
|
|
148
|
+
// day ("already up to date (current 0.31.0, latest 0.30.0)", measured). A fresh answer refreshes the cache.
|
|
149
|
+
const now = Date.now();
|
|
150
|
+
const fresh = io.queryLatest ? await io.queryLatest().catch(() => null) : null;
|
|
151
|
+
if (fresh !== null && !io.dryRun) { // --dry-run asks and shows, and writes nothing
|
|
152
|
+
try {
|
|
153
|
+
fs.mkdirSync(path.join(os.homedir(), '.holmes'), { recursive: true });
|
|
154
|
+
fs.writeFileSync(path.join(os.homedir(), '.holmes', 'update-check.json'), JSON.stringify({ latest: fresh, checkedAt: now }));
|
|
155
|
+
}
|
|
156
|
+
catch { /* the cache is a convenience; the plan below uses the fresh answer either way */ }
|
|
157
|
+
}
|
|
158
|
+
const resolved = (0, upgrade_plan_1.resolveLatest)({ fresh, cached: cached ? { latest: cached.latest, checkedAt: cached.checkedAt } : null, now });
|
|
147
159
|
const registry = (() => {
|
|
148
160
|
try {
|
|
149
161
|
return (0, workspaces_1.readRegistry)(fs.readFileSync(path.join(os.homedir(), '.holmes', 'workspaces.json'), 'utf8'));
|
|
@@ -152,7 +164,7 @@ async function runUpgrade(io) {
|
|
|
152
164
|
return (0, workspaces_1.readRegistry)(null);
|
|
153
165
|
}
|
|
154
166
|
})();
|
|
155
|
-
const plan = (0, upgrade_plan_1.planUpgrade)({ current, latest:
|
|
167
|
+
const plan = (0, upgrade_plan_1.planUpgrade)({ current, latest: resolved.latest, registry, installMode: mode, latestNote: (0, upgrade_plan_1.describeLatest)(resolved) });
|
|
156
168
|
if (plan.kind === 'noop') {
|
|
157
169
|
io.stdout(`${plan.reason}\n`);
|
|
158
170
|
return 0;
|
|
@@ -21,6 +21,11 @@ export declare function parseLatest(body: string): string | null;
|
|
|
21
21
|
* caller's decision — this always attempts.
|
|
22
22
|
*/
|
|
23
23
|
export declare function refreshCache(opts: RefreshOpts): Promise<boolean>;
|
|
24
|
+
/**
|
|
25
|
+
* @implements A-SPEC-543.2 (amendment 2026-09-29) — the registry's latest, asked now: `node:https` GET of REGISTRY_URL
|
|
26
|
+
* with a 5 s timeout, `parseLatest`, null on any failure. What `holmes-kit upgrade` asks before it plans.
|
|
27
|
+
*/
|
|
28
|
+
export declare function queryRegistryLatest(timeoutMs?: number): Promise<string | null>;
|
|
24
29
|
export interface SpawnRefreshOpts {
|
|
25
30
|
home: string;
|
|
26
31
|
env: NodeJS.ProcessEnv;
|
|
@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
36
36
|
exports.REGISTRY_URL = void 0;
|
|
37
37
|
exports.parseLatest = parseLatest;
|
|
38
38
|
exports.refreshCache = refreshCache;
|
|
39
|
+
exports.queryRegistryLatest = queryRegistryLatest;
|
|
39
40
|
exports.shouldRefreshCache = shouldRefreshCache;
|
|
40
41
|
exports.maybeSpawnRefresh = maybeSpawnRefresh;
|
|
41
42
|
// @implements A-SPEC-547.1
|
|
@@ -80,6 +81,28 @@ async function refreshCache(opts) {
|
|
|
80
81
|
opts.writeFile(path.join(dir, 'update-check.json'), JSON.stringify({ latest, checkedAt: opts.now }));
|
|
81
82
|
return true;
|
|
82
83
|
}
|
|
84
|
+
/**
|
|
85
|
+
* @implements A-SPEC-543.2 (amendment 2026-09-29) — the registry's latest, asked now: `node:https` GET of REGISTRY_URL
|
|
86
|
+
* with a 5 s timeout, `parseLatest`, null on any failure. What `holmes-kit upgrade` asks before it plans.
|
|
87
|
+
*/
|
|
88
|
+
function queryRegistryLatest(timeoutMs = 5000) {
|
|
89
|
+
return new Promise((resolve) => {
|
|
90
|
+
try {
|
|
91
|
+
const https = require('node:https');
|
|
92
|
+
const req = https.get(exports.REGISTRY_URL, { headers: { accept: 'application/vnd.npm.install-v1+json' } }, (res) => {
|
|
93
|
+
let d = '';
|
|
94
|
+
res.on('data', (c) => (d += c));
|
|
95
|
+
res.on('end', () => resolve(res.statusCode === 200 ? parseLatest(d) : null));
|
|
96
|
+
res.on('error', () => resolve(null));
|
|
97
|
+
});
|
|
98
|
+
req.on('error', () => resolve(null));
|
|
99
|
+
req.setTimeout(timeoutMs, () => { req.destroy(); resolve(null); });
|
|
100
|
+
}
|
|
101
|
+
catch {
|
|
102
|
+
resolve(null);
|
|
103
|
+
}
|
|
104
|
+
});
|
|
105
|
+
}
|
|
83
106
|
/**
|
|
84
107
|
* @implements A-SPEC-547.2
|
|
85
108
|
* Pure: whether a network refresh should fire now — network allowed (not opted out / not CI) AND the
|
|
@@ -23,7 +23,35 @@ export declare function planUpgrade(a: {
|
|
|
23
23
|
latest: string | null;
|
|
24
24
|
registry: Registry;
|
|
25
25
|
installMode: InstallMode;
|
|
26
|
+
/** Where latest came from (`describeLatest`), appended to a noop reason. */
|
|
27
|
+
latestNote?: string;
|
|
26
28
|
}): UpgradePlan;
|
|
29
|
+
/** Where `upgrade` found latest: the registry just now, the update cache (with its age), or nowhere. */
|
|
30
|
+
export type ResolvedLatest = {
|
|
31
|
+
latest: string;
|
|
32
|
+
source: 'registry';
|
|
33
|
+
} | {
|
|
34
|
+
latest: string;
|
|
35
|
+
source: 'cache';
|
|
36
|
+
ageMs: number;
|
|
37
|
+
} | {
|
|
38
|
+
latest: null;
|
|
39
|
+
source: 'none';
|
|
40
|
+
};
|
|
41
|
+
/**
|
|
42
|
+
* @implements A-SPEC-543.2 (amendment 2026-09-29) — pure: a fresh registry answer wins; without one the cache answers
|
|
43
|
+
* and keeps its age; with neither latest is unknown.
|
|
44
|
+
*/
|
|
45
|
+
export declare function resolveLatest(a: {
|
|
46
|
+
fresh: string | null;
|
|
47
|
+
cached: {
|
|
48
|
+
latest: string;
|
|
49
|
+
checkedAt: number;
|
|
50
|
+
} | null;
|
|
51
|
+
now: number;
|
|
52
|
+
}): ResolvedLatest;
|
|
53
|
+
/** The words for where latest came from — the note `planUpgrade` appends. */
|
|
54
|
+
export declare function describeLatest(r: ResolvedLatest): string;
|
|
27
55
|
/** The env switch that turns SessionStart's forward self-heal re-pin OFF. */
|
|
28
56
|
export declare const NO_AUTO_REPIN_ENV = "HOLMES_NO_AUTO_REPIN";
|
|
29
57
|
/**
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.NO_AUTO_REPIN_ENV = void 0;
|
|
4
4
|
exports.planUpgrade = planUpgrade;
|
|
5
|
+
exports.resolveLatest = resolveLatest;
|
|
6
|
+
exports.describeLatest = describeLatest;
|
|
5
7
|
exports.repinDecision = repinDecision;
|
|
6
8
|
// @implements A-SPEC-543.2
|
|
7
9
|
const update_notice_1 = require("./update-notice");
|
|
@@ -13,14 +15,41 @@ const update_notice_1 = require("./update-notice");
|
|
|
13
15
|
* (install-only, first machine).
|
|
14
16
|
*/
|
|
15
17
|
function planUpgrade(a) {
|
|
18
|
+
const note = a.latestNote ? ` ${a.latestNote}` : '';
|
|
16
19
|
if (a.latest === null) {
|
|
17
20
|
return { kind: 'noop', reason: 'latest version unknown (registry unreachable and no cache) — nothing to plan' };
|
|
18
21
|
}
|
|
19
|
-
|
|
20
|
-
|
|
22
|
+
const order = (0, update_notice_1.compareSemver)(a.latest, a.current);
|
|
23
|
+
// A-SPEC-543.2 (amendment 2026-09-29): an installed version newer than latest means latest is stale — it is not
|
|
24
|
+
// "already up to date" (the report read `current 0.31.0, latest 0.30.0` from a cache that predated the release).
|
|
25
|
+
if (order < 0)
|
|
26
|
+
return { kind: 'noop', reason: `installed ${a.current} is newer than the latest ${a.latest}${note}` };
|
|
27
|
+
if (order === 0) {
|
|
28
|
+
return { kind: 'noop', reason: `already up to date (current ${a.current}, latest ${a.latest})${note}` };
|
|
21
29
|
}
|
|
22
30
|
return { kind: 'run', current: a.current, latest: a.latest, installMode: a.installMode, repins: a.registry.workspaces };
|
|
23
31
|
}
|
|
32
|
+
/**
|
|
33
|
+
* @implements A-SPEC-543.2 (amendment 2026-09-29) — pure: a fresh registry answer wins; without one the cache answers
|
|
34
|
+
* and keeps its age; with neither latest is unknown.
|
|
35
|
+
*/
|
|
36
|
+
function resolveLatest(a) {
|
|
37
|
+
if (a.fresh !== null)
|
|
38
|
+
return { latest: a.fresh, source: 'registry' };
|
|
39
|
+
if (a.cached !== null)
|
|
40
|
+
return { latest: a.cached.latest, source: 'cache', ageMs: Math.max(0, a.now - a.cached.checkedAt) };
|
|
41
|
+
return { latest: null, source: 'none' };
|
|
42
|
+
}
|
|
43
|
+
/** The words for where latest came from — the note `planUpgrade` appends. */
|
|
44
|
+
function describeLatest(r) {
|
|
45
|
+
if (r.source === 'registry')
|
|
46
|
+
return '(registry)';
|
|
47
|
+
if (r.source === 'none')
|
|
48
|
+
return '';
|
|
49
|
+
const minutes = Math.round(r.ageMs / 60_000);
|
|
50
|
+
const age = minutes < 60 ? `${minutes} min` : `${Math.round(r.ageMs / 3_600_000)} h`;
|
|
51
|
+
return `(cached check from ${age} ago — the registry could not be reached)`;
|
|
52
|
+
}
|
|
24
53
|
/** The env switch that turns SessionStart's forward self-heal re-pin OFF. */
|
|
25
54
|
exports.NO_AUTO_REPIN_ENV = 'HOLMES_NO_AUTO_REPIN';
|
|
26
55
|
/**
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"//": "@implements A-SPEC-209",
|
|
3
3
|
"name": "@holmes-lab/holmes-kit",
|
|
4
|
-
"version": "0.31.
|
|
4
|
+
"version": "0.31.2",
|
|
5
5
|
"description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
|
|
6
6
|
"main": "dist/holmes/mcp/server.js",
|
|
7
7
|
"types": "dist/holmes/mcp/server.d.ts",
|