@holmes-lab/holmes-kit 0.31.0 → 0.31.1

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 CHANGED
@@ -5,6 +5,17 @@ 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.1] - 2026-09-29
9
+
10
+ ### Fixed
11
+
12
+ - **`holmes-kit upgrade` asks the registry for the latest version** (A-SPEC-543.2, amended). It read only the update
13
+ cache, which SessionStart refreshes at most once a day, so right after 0.31.0 was published it answered `already up
14
+ 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
15
+ command now queries the registry (5 s, the same public `dist-tags` the banner uses) and refreshes the cache; when the
16
+ registry cannot be reached it says it used the cache and how old that answer is; an installed version newer than the
17
+ latest is no longer called "already up to date". `--dry-run` asks and shows, and writes nothing.
18
+
8
19
  ## [0.31.0] - 2026-09-29
9
20
 
10
21
  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
- 89eba670-mum0nzxm
1
+ 019ba709-mumrfxed
@@ -1303,7 +1303,10 @@ async function main(argv) {
1303
1303
  // non-TTY passes --yes), never a silent auto-install of a gate-enforcing engine.
1304
1304
  if (cmd === 'upgrade') {
1305
1305
  const { runUpgrade } = require('./upgrade');
1306
+ const { queryRegistryLatest } = require('../update/refresh');
1306
1307
  return await runUpgrade({
1308
+ // A-SPEC-543.2 (amendment 2026-09-29): the explicit command asks the registry for latest.
1309
+ queryLatest: () => queryRegistryLatest(),
1307
1310
  dryRun: flags['dry-run'] === true,
1308
1311
  yes: flags.yes === true,
1309
1312
  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: cached?.latest ?? null, registry, installMode: mode });
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
- if ((0, update_notice_1.compareSemver)(a.latest, a.current) <= 0) {
20
- return { kind: 'noop', reason: `already up to date (current ${a.current}, latest ${a.latest})` };
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.0",
4
+ "version": "0.31.1",
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",