@xopcai/xopc 0.0.6 → 0.0.11

package/dist/src/infra/update-check.d.ts

@@ -0,0 +1,53 @@
+import { type UpdateChannel } from './update-channels.js';
+export type InstallKind = 'git' | 'package' | 'unknown';
+export type NpmTagResult = {
+    tag: string;
+    version: string | null;
+    error?: string;
+};
+export type UpdateCheckResult = {
+    installKind: InstallKind;
+    root: string | null;
+};
+export type UpdateAvailable = {
+    currentVersion: string;
+    latestVersion: string;
+    channel: string;
+};
+/**
+ * Fetch the version published under a specific npm dist-tag.
+ * Uses the abbreviated packument endpoint: `GET /<pkg>/<tag>`.
+ */
+export declare function fetchNpmTagVersion(params: {
+    tag: string;
+    timeoutMs?: number;
+}): Promise<NpmTagResult>;
+/**
+ * Resolve the best version for the given update channel.
+ * For beta channel: if the beta tag version is older than latest, return latest instead.
+ */
+export declare function resolveNpmChannelTag(params: {
+    channel: UpdateChannel;
+    timeoutMs?: number;
+}): Promise<{
+    tag: string;
+    version: string | null;
+}>;
+/**
+ * Compare two semver strings. Returns:
+ * -1 if a < b, 0 if equal, 1 if a > b, null if either is unparseable.
+ * Prerelease versions are considered older than the same version without prerelease.
+ */
+export declare function compareSemver(a: string | null, b: string | null): number | null;
+/**
+ * Detect whether the current process is running from a git checkout or npm-installed package.
+ * Checks for `.git` directory in the package root.
+ */
+export declare function detectInstallKind(packageRoot: string): Promise<InstallKind>;
+/**
+ * Resolve the xopc package root directory.
+ * Walks up from this file to find package.json with name @xopcai/xopc.
+ */
+export declare function resolvePackageRoot(): Promise<string | null>;
+/** Get the current running version from package.json. */
+export declare function getCurrentVersion(): string;

package/dist/src/infra/update-check.js

@@ -0,0 +1,155 @@
+import { PACKAGE_VERSION, init_package_version } from "../package-version.js";
+import { channelToNpmTag } from "./update-channels.js";
+import { dirname, join } from "node:path";
+import { access, readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+//#region src/infra/update-check.ts
+init_package_version();
+const REGISTRY_BASE = "https://registry.npmjs.org";
+const PACKAGE_NAME = "@xopcai/xopc";
+const REGISTRY_TIMEOUT_MS = 3500;
+/**
+* Fetch the version published under a specific npm dist-tag.
+* Uses the abbreviated packument endpoint: `GET /<pkg>/<tag>`.
+*/
+async function fetchNpmTagVersion(params) {
+	const timeoutMs = params.timeoutMs ?? REGISTRY_TIMEOUT_MS;
+	const url = `${REGISTRY_BASE}/${encodeURIComponent(PACKAGE_NAME).replace("%40", "@")}/${encodeURIComponent(params.tag)}`;
+	try {
+		const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+		if (!response.ok) return {
+			tag: params.tag,
+			version: null,
+			error: `HTTP ${response.status}`
+		};
+		const json = await response.json();
+		const version = typeof json?.version === "string" ? json.version : null;
+		return {
+			tag: params.tag,
+			version
+		};
+	} catch (err) {
+		return {
+			tag: params.tag,
+			version: null,
+			error: String(err)
+		};
+	}
+}
+/**
+* Resolve the best version for the given update channel.
+* For beta channel: if the beta tag version is older than latest, return latest instead.
+*/
+async function resolveNpmChannelTag(params) {
+	const channelTag = channelToNpmTag(params.channel);
+	const channelResult = await fetchNpmTagVersion({
+		tag: channelTag,
+		timeoutMs: params.timeoutMs
+	});
+	if (params.channel !== "beta") return {
+		tag: channelTag,
+		version: channelResult.version
+	};
+	const latestResult = await fetchNpmTagVersion({
+		tag: "latest",
+		timeoutMs: params.timeoutMs
+	});
+	if (!latestResult.version) return {
+		tag: channelTag,
+		version: channelResult.version
+	};
+	if (!channelResult.version) return {
+		tag: "latest",
+		version: latestResult.version
+	};
+	const comparison = compareSemver(channelResult.version, latestResult.version);
+	if (comparison !== null && comparison < 0) return {
+		tag: "latest",
+		version: latestResult.version
+	};
+	return {
+		tag: channelTag,
+		version: channelResult.version
+	};
+}
+/**
+* Parse a version string into comparable numeric parts.
+* Handles formats like "1.2.3", "1.2.3-beta.1".
+* Returns null for unparseable strings.
+*/
+function parseSemverParts(version) {
+	const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(version.trim());
+	if (!match) return null;
+	return {
+		major: parseInt(match[1], 10),
+		minor: parseInt(match[2], 10),
+		patch: parseInt(match[3], 10),
+		prerelease: match[4] ?? null
+	};
+}
+/**
+* Compare two semver strings. Returns:
+* -1 if a < b, 0 if equal, 1 if a > b, null if either is unparseable.
+* Prerelease versions are considered older than the same version without prerelease.
+*/
+function compareSemver(a, b) {
+	if (!a || !b) return null;
+	const parsedA = parseSemverParts(a);
+	const parsedB = parseSemverParts(b);
+	if (!parsedA || !parsedB) return null;
+	for (const field of [
+		"major",
+		"minor",
+		"patch"
+	]) if (parsedA[field] !== parsedB[field]) return parsedA[field] < parsedB[field] ? -1 : 1;
+	if (parsedA.prerelease === null && parsedB.prerelease === null) return 0;
+	if (parsedA.prerelease !== null && parsedB.prerelease === null) return -1;
+	if (parsedA.prerelease === null && parsedB.prerelease !== null) return 1;
+	if (parsedA.prerelease < parsedB.prerelease) return -1;
+	if (parsedA.prerelease > parsedB.prerelease) return 1;
+	return 0;
+}
+/**
+* Detect whether the current process is running from a git checkout or npm-installed package.
+* Checks for `.git` directory in the package root.
+*/
+async function detectInstallKind(packageRoot) {
+	try {
+		await access(join(packageRoot, ".git"));
+		return "git";
+	} catch {
+		try {
+			await access(join(packageRoot, "package.json"));
+			return "package";
+		} catch {
+			return "unknown";
+		}
+	}
+}
+/**
+* Resolve the xopc package root directory.
+* Walks up from this file to find package.json with name @xopcai/xopc.
+*/
+async function resolvePackageRoot() {
+	let current = dirname(fileURLToPath(import.meta.url));
+	for (let depth = 0; depth < 20; depth++) {
+		const pkgPath = join(current, "package.json");
+		try {
+			const raw = await readFile(pkgPath, "utf-8");
+			const parsed = JSON.parse(raw);
+			if (typeof parsed.name === "string" && parsed.name === PACKAGE_NAME) return current;
+		} catch {}
+		const parent = dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+	return null;
+}
+/** Get the current running version from package.json. */
+function getCurrentVersion() {
+	return PACKAGE_VERSION;
+}
+//#endregion
+export { compareSemver, detectInstallKind, fetchNpmTagVersion, getCurrentVersion, resolveNpmChannelTag, resolvePackageRoot };
+
+//# sourceMappingURL=update-check.js.map

package/dist/src/infra/update-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.js","names":[],"sources":["../../../src/infra/update-check.ts"],"sourcesContent":["// src/infra/update-check.ts\n\nimport { access, readFile } from 'node:fs/promises';\nimport { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\nimport { PACKAGE_VERSION } from '../package-version.js';\n\nimport { channelToNpmTag, type UpdateChannel } from './update-channels.js';\n\n// --- Types ---\n\nexport type InstallKind = 'git' | 'package' | 'unknown';\n\nexport type NpmTagResult = {\n  tag: string;\n  version: string | null;\n  error?: string;\n};\n\nexport type UpdateCheckResult = {\n  installKind: InstallKind;\n  root: string | null;\n};\n\nexport type UpdateAvailable = {\n  currentVersion: string;\n  latestVersion: string;\n  channel: string;\n};\n\n// --- npm Registry ---\n\nconst REGISTRY_BASE = 'https://registry.npmjs.org';\nconst PACKAGE_NAME = '@xopcai/xopc';\nconst REGISTRY_TIMEOUT_MS = 3500;\n\n/**\n * Fetch the version published under a specific npm dist-tag.\n * Uses the abbreviated packument endpoint: `GET /<pkg>/<tag>`.\n */\nexport async function fetchNpmTagVersion(params: {\n  tag: string;\n  timeoutMs?: number;\n}): Promise<NpmTagResult> {\n  const timeoutMs = params.timeoutMs ?? REGISTRY_TIMEOUT_MS;\n  const encodedName = encodeURIComponent(PACKAGE_NAME).replace('%40', '@');\n  const url = `${REGISTRY_BASE}/${encodedName}/${encodeURIComponent(params.tag)}`;\n  try {\n    const response = await fetch(url, {\n      signal: AbortSignal.timeout(timeoutMs),\n    });\n    if (!response.ok) {\n      return { tag: params.tag, version: null, error: `HTTP ${response.status}` };\n    }\n    const json = (await response.json()) as { version?: unknown };\n    const version = typeof json?.version === 'string' ? json.version : null;\n    return { tag: params.tag, version };\n  } catch (err) {\n    return { tag: params.tag, version: null, error: String(err) };\n  }\n}\n\n/**\n * Resolve the best version for the given update channel.\n * For beta channel: if the beta tag version is older than latest, return latest instead.\n */\nexport async function resolveNpmChannelTag(params: {\n  channel: UpdateChannel;\n  timeoutMs?: number;\n}): Promise<{ tag: string; version: string | null }> {\n  const channelTag = channelToNpmTag(params.channel);\n  const channelResult = await fetchNpmTagVersion({ tag: channelTag, timeoutMs: params.timeoutMs });\n\n  if (params.channel !== 'beta') {\n    return { tag: channelTag, version: channelResult.version };\n  }\n\n  // For beta: also check latest, return whichever is newer\n  const latestResult = await fetchNpmTagVersion({ tag: 'latest', timeoutMs: params.timeoutMs });\n  if (!latestResult.version) {\n    return { tag: channelTag, version: channelResult.version };\n  }\n  if (!channelResult.version) {\n    return { tag: 'latest', version: latestResult.version };\n  }\n  const comparison = compareSemver(channelResult.version, latestResult.version);\n  if (comparison !== null && comparison < 0) {\n    return { tag: 'latest', version: latestResult.version };\n  }\n  return { tag: channelTag, version: channelResult.version };\n}\n\n// --- Semver comparison ---\n\n/**\n * Parse a version string into comparable numeric parts.\n * Handles formats like \"1.2.3\", \"1.2.3-beta.1\".\n * Returns null for unparseable strings.\n */\nfunction parseSemverParts(\n  version: string,\n): { major: number; minor: number; patch: number; prerelease: string | null } | null {\n  const match = /^v?(\\d+)\\.(\\d+)\\.(\\d+)(?:-(.+))?$/.exec(version.trim());\n  if (!match) return null;\n  return {\n    major: parseInt(match[1], 10),\n    minor: parseInt(match[2], 10),\n    patch: parseInt(match[3], 10),\n    prerelease: match[4] ?? null,\n  };\n}\n\n/**\n * Compare two semver strings. Returns:\n * -1 if a < b, 0 if equal, 1 if a > b, null if either is unparseable.\n * Prerelease versions are considered older than the same version without prerelease.\n */\nexport function compareSemver(a: string | null, b: string | null): number | null {\n  if (!a || !b) return null;\n  const parsedA = parseSemverParts(a);\n  const parsedB = parseSemverParts(b);\n  if (!parsedA || !parsedB) return null;\n\n  for (const field of ['major', 'minor', 'patch'] as const) {\n    if (parsedA[field] !== parsedB[field]) {\n      return parsedA[field] < parsedB[field] ? -1 : 1;\n    }\n  }\n\n  // Both have same major.minor.patch — compare prerelease\n  if (parsedA.prerelease === null && parsedB.prerelease === null) return 0;\n  if (parsedA.prerelease !== null && parsedB.prerelease === null) return -1; // pre < release\n  if (parsedA.prerelease === null && parsedB.prerelease !== null) return 1;\n\n  // Both have prerelease — lexicographic fallback\n  if (parsedA.prerelease! < parsedB.prerelease!) return -1;\n  if (parsedA.prerelease! > parsedB.prerelease!) return 1;\n  return 0;\n}\n\n// --- Install kind detection ---\n\n/**\n * Detect whether the current process is running from a git checkout or npm-installed package.\n * Checks for `.git` directory in the package root.\n */\nexport async function detectInstallKind(packageRoot: string): Promise<InstallKind> {\n  try {\n    await access(join(packageRoot, '.git'));\n    return 'git';\n  } catch {\n    // No .git directory — likely installed via npm\n    try {\n      await access(join(packageRoot, 'package.json'));\n      return 'package';\n    } catch {\n      return 'unknown';\n    }\n  }\n}\n\n/**\n * Resolve the xopc package root directory.\n * Walks up from this file to find package.json with name @xopcai/xopc.\n */\nexport async function resolvePackageRoot(): Promise<string | null> {\n  let current = dirname(fileURLToPath(import.meta.url));\n  for (let depth = 0; depth < 20; depth++) {\n    const pkgPath = join(current, 'package.json');\n    try {\n      const raw = await readFile(pkgPath, 'utf-8');\n      const parsed = JSON.parse(raw) as { name?: unknown };\n      if (typeof parsed.name === 'string' && parsed.name === PACKAGE_NAME) {\n        return current;\n      }\n    } catch {\n      // continue\n    }\n    const parent = dirname(current);\n    if (parent === current) return null;\n    current = parent;\n  }\n  return null;\n}\n\n/** Get the current running version from package.json. */\nexport function getCurrentVersion(): string {\n  return PACKAGE_VERSION;\n}\n"],"mappings":"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"}

package/dist/src/infra/update-runner.d.ts

@@ -0,0 +1,18 @@
+import type { UpdateChannel } from './update-channels.js';
+export type AutoUpdateResult = {
+    ok: boolean;
+    exitCode: number | null;
+    reason?: string;
+    stdout?: string;
+    stderr?: string;
+};
+/**
+ * Spawn a child process to execute `xopc update --yes --channel <channel> --json`.
+ * Uses the current runtime (process.execPath) and entry point (process.argv[1]) to
+ * ensure the correct Node.js version and binary path are used.
+ */
+export declare function runAutoUpdateCommand(params: {
+    channel: UpdateChannel;
+    root?: string | null;
+    timeoutMs?: number;
+}): Promise<AutoUpdateResult>;

package/dist/src/infra/update-runner.js

@@ -0,0 +1,112 @@
+import { join } from "node:path";
+import { access } from "node:fs/promises";
+import { spawn } from "node:child_process";
+//#region src/infra/update-runner.ts
+const AUTO_UPDATE_TIMEOUT_MS = 2700 * 1e3;
+/**
+* Spawn a child process to execute `xopc update --yes --channel <channel> --json`.
+* Uses the current runtime (process.execPath) and entry point (process.argv[1]) to
+* ensure the correct Node.js version and binary path are used.
+*/
+async function runAutoUpdateCommand(params) {
+	const timeoutMs = params.timeoutMs ?? AUTO_UPDATE_TIMEOUT_MS;
+	const argv = await resolveUpdateCommandArgv([
+		"update",
+		"--yes",
+		"--channel",
+		params.channel,
+		"--json"
+	], params.root ?? null);
+	return new Promise((resolve) => {
+		const child = spawn(argv[0], argv.slice(1), {
+			env: {
+				...process.env,
+				XOPC_AUTO_UPDATE: "1"
+			},
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			detached: false
+		});
+		let stdout = "";
+		let stderr = "";
+		const timeoutId = setTimeout(() => {
+			child.kill("SIGTERM");
+		}, timeoutMs);
+		const finish = (result) => {
+			clearTimeout(timeoutId);
+			resolve(result);
+		};
+		child.stdout?.on("data", (chunk) => {
+			stdout += chunk.toString();
+			if (stdout.length > 64e3) stdout = stdout.slice(-32e3);
+		});
+		child.stderr?.on("data", (chunk) => {
+			stderr += chunk.toString();
+			if (stderr.length > 64e3) stderr = stderr.slice(-32e3);
+		});
+		child.on("error", (err) => {
+			finish({
+				ok: false,
+				exitCode: null,
+				reason: String(err),
+				stdout,
+				stderr
+			});
+		});
+		child.on("exit", (code, signal) => {
+			if (signal === "SIGTERM" || code === 143) {
+				finish({
+					ok: false,
+					exitCode: code,
+					reason: "timeout",
+					stdout,
+					stderr
+				});
+				return;
+			}
+			finish({
+				ok: code === 0,
+				exitCode: code,
+				reason: code === 0 ? void 0 : "non-zero-exit",
+				stdout,
+				stderr
+			});
+		});
+	});
+}
+/**
+* Resolve the argv array for spawning the update command.
+*
+* Priority:
+* 1. process.execPath + process.argv[1] (current runtime + entry point)
+* 2. process.execPath + known dist entry points in root
+* 3. Fallback to bare `xopc` (assumes global install)
+*/
+async function resolveUpdateCommandArgv(baseArgs, root) {
+	const execPath = process.execPath?.trim();
+	const argv1 = process.argv[1]?.trim();
+	if (execPath && argv1) return [
+		execPath,
+		argv1,
+		...baseArgs
+	];
+	if (execPath && root) {
+		const candidates = [join(root, "dist/src/cli/index.js"), join(root, "dist/index.js")];
+		for (const candidate of candidates) try {
+			await access(candidate);
+			return [
+				execPath,
+				candidate,
+				...baseArgs
+			];
+		} catch {}
+	}
+	return ["xopc", ...baseArgs];
+}
+//#endregion
+export { runAutoUpdateCommand };
+
+//# sourceMappingURL=update-runner.js.map

package/dist/src/infra/update-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-runner.js","names":[],"sources":["../../../src/infra/update-runner.ts"],"sourcesContent":["// src/infra/update-runner.ts\n\nimport { spawn } from 'node:child_process';\nimport { access } from 'node:fs/promises';\nimport { join } from 'node:path';\n\nimport type { UpdateChannel } from './update-channels.js';\n\nconst AUTO_UPDATE_TIMEOUT_MS = 45 * 60 * 1000; // 45 minutes\n\nexport type AutoUpdateResult = {\n  ok: boolean;\n  exitCode: number | null;\n  reason?: string;\n  stdout?: string;\n  stderr?: string;\n};\n\n/**\n * Spawn a child process to execute `xopc update --yes --channel <channel> --json`.\n * Uses the current runtime (process.execPath) and entry point (process.argv[1]) to\n * ensure the correct Node.js version and binary path are used.\n */\nexport async function runAutoUpdateCommand(params: {\n  channel: UpdateChannel;\n  root?: string | null;\n  timeoutMs?: number;\n}): Promise<AutoUpdateResult> {\n  const timeoutMs = params.timeoutMs ?? AUTO_UPDATE_TIMEOUT_MS;\n  const baseArgs = ['update', '--yes', '--channel', params.channel, '--json'];\n\n  const argv = await resolveUpdateCommandArgv(baseArgs, params.root ?? null);\n\n  return new Promise<AutoUpdateResult>((resolve) => {\n    const child = spawn(argv[0], argv.slice(1), {\n      env: {\n        ...process.env,\n        XOPC_AUTO_UPDATE: '1',\n      },\n      stdio: ['ignore', 'pipe', 'pipe'],\n      detached: false,\n    });\n\n    let stdout = '';\n    let stderr = '';\n\n    const timeoutId = setTimeout(() => {\n      child.kill('SIGTERM');\n    }, timeoutMs);\n\n    const finish = (result: AutoUpdateResult) => {\n      clearTimeout(timeoutId);\n      resolve(result);\n    };\n\n    child.stdout?.on('data', (chunk: Buffer) => {\n      stdout += chunk.toString();\n      if (stdout.length > 64_000) stdout = stdout.slice(-32_000);\n    });\n    child.stderr?.on('data', (chunk: Buffer) => {\n      stderr += chunk.toString();\n      if (stderr.length > 64_000) stderr = stderr.slice(-32_000);\n    });\n\n    child.on('error', (err) => {\n      finish({ ok: false, exitCode: null, reason: String(err), stdout, stderr });\n    });\n\n    child.on('exit', (code, signal) => {\n      if (signal === 'SIGTERM' || code === 143) {\n        finish({ ok: false, exitCode: code, reason: 'timeout', stdout, stderr });\n        return;\n      }\n      finish({\n        ok: code === 0,\n        exitCode: code,\n        reason: code === 0 ? undefined : 'non-zero-exit',\n        stdout,\n        stderr,\n      });\n    });\n  });\n}\n\n/**\n * Resolve the argv array for spawning the update command.\n *\n * Priority:\n * 1. process.execPath + process.argv[1] (current runtime + entry point)\n * 2. process.execPath + known dist entry points in root\n * 3. Fallback to bare `xopc` (assumes global install)\n */\nasync function resolveUpdateCommandArgv(\n  baseArgs: string[],\n  root: string | null,\n): Promise<string[]> {\n  const execPath = process.execPath?.trim();\n  const argv1 = process.argv[1]?.trim();\n\n  // Best case: we know both the runtime and the entry point\n  if (execPath && argv1) {\n    return [execPath, argv1, ...baseArgs];\n  }\n\n  // Try known entry points in the package root\n  if (execPath && root) {\n    const candidates = [join(root, 'dist/src/cli/index.js'), join(root, 'dist/index.js')];\n    for (const candidate of candidates) {\n      try {\n        await access(candidate);\n        return [execPath, candidate, ...baseArgs];\n      } catch {\n        // try next\n      }\n    }\n  }\n\n  // Fallback: rely on global PATH\n  return ['xopc', ...baseArgs];\n}\n"],"mappings":";;;;AAQA,MAAM,yBAAyB,OAAU;;;;;;AAezC,eAAsB,qBAAqB,QAIb;CAC5B,MAAM,YAAY,OAAO,aAAa;CAGtC,MAAM,OAAO,MAAM,yBAFF;EAAC;EAAU;EAAS;EAAa,OAAO;EAAS;EAAS,EAErB,OAAO,QAAQ,KAAK;AAE1E,QAAO,IAAI,SAA2B,YAAY;EAChD,MAAM,QAAQ,MAAM,KAAK,IAAI,KAAK,MAAM,EAAE,EAAE;GAC1C,KAAK;IACH,GAAG,QAAQ;IACX,kBAAkB;IACnB;GACD,OAAO;IAAC;IAAU;IAAQ;IAAO;GACjC,UAAU;GACX,CAAC;EAEF,IAAI,SAAS;EACb,IAAI,SAAS;EAEb,MAAM,YAAY,iBAAiB;AACjC,SAAM,KAAK,UAAU;KACpB,UAAU;EAEb,MAAM,UAAU,WAA6B;AAC3C,gBAAa,UAAU;AACvB,WAAQ,OAAO;;AAGjB,QAAM,QAAQ,GAAG,SAAS,UAAkB;AAC1C,aAAU,MAAM,UAAU;AAC1B,OAAI,OAAO,SAAS,KAAQ,UAAS,OAAO,MAAM,MAAQ;IAC1D;AACF,QAAM,QAAQ,GAAG,SAAS,UAAkB;AAC1C,aAAU,MAAM,UAAU;AAC1B,OAAI,OAAO,SAAS,KAAQ,UAAS,OAAO,MAAM,MAAQ;IAC1D;AAEF,QAAM,GAAG,UAAU,QAAQ;AACzB,UAAO;IAAE,IAAI;IAAO,UAAU;IAAM,QAAQ,OAAO,IAAI;IAAE;IAAQ;IAAQ,CAAC;IAC1E;AAEF,QAAM,GAAG,SAAS,MAAM,WAAW;AACjC,OAAI,WAAW,aAAa,SAAS,KAAK;AACxC,WAAO;KAAE,IAAI;KAAO,UAAU;KAAM,QAAQ;KAAW;KAAQ;KAAQ,CAAC;AACxE;;AAEF,UAAO;IACL,IAAI,SAAS;IACb,UAAU;IACV,QAAQ,SAAS,IAAI,KAAA,IAAY;IACjC;IACA;IACD,CAAC;IACF;GACF;;;;;;;;;;AAWJ,eAAe,yBACb,UACA,MACmB;CACnB,MAAM,WAAW,QAAQ,UAAU,MAAM;CACzC,MAAM,QAAQ,QAAQ,KAAK,IAAI,MAAM;AAGrC,KAAI,YAAY,MACd,QAAO;EAAC;EAAU;EAAO,GAAG;EAAS;AAIvC,KAAI,YAAY,MAAM;EACpB,MAAM,aAAa,CAAC,KAAK,MAAM,wBAAwB,EAAE,KAAK,MAAM,gBAAgB,CAAC;AACrF,OAAK,MAAM,aAAa,WACtB,KAAI;AACF,SAAM,OAAO,UAAU;AACvB,UAAO;IAAC;IAAU;IAAW,GAAG;IAAS;UACnC;;AAOZ,QAAO,CAAC,QAAQ,GAAG,SAAS"}

package/dist/src/infra/update-startup.d.ts

@@ -0,0 +1,20 @@
+import type { Config } from '../config/schema.js';
+import { type UpdateAvailable } from './update-check.js';
+/** Get the cached update-available state (populated after startup check). */
+export declare function getUpdateAvailable(): UpdateAvailable | null;
+/**
+ * Main startup update check. Called once when the gateway starts (or on demand).
+ */
+export declare function runGatewayUpdateCheck(params: {
+    config: Config;
+    onUpdateAvailableChange?: (update: UpdateAvailable | null) => void;
+    /** When true, bypass checkOnStart/auto-disabled early exit and throttle (for POST /api/update/check). */
+    force?: boolean;
+}): Promise<void>;
+/**
+ * Schedule periodic update checks. Returns a cleanup function to stop the timer.
+ */
+export declare function scheduleGatewayUpdateCheck(params: {
+    config: Config;
+    onUpdateAvailableChange?: (update: UpdateAvailable | null) => void;
+}): () => void;

package/dist/src/infra/update-startup.js

@@ -0,0 +1,246 @@
+import { PACKAGE_VERSION, init_package_version } from "../package-version.js";
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { resolveStateDir } from "../config/paths-state.js";
+import { init_paths } from "../config/paths.js";
+import { normalizeUpdateChannel } from "./update-channels.js";
+import { compareSemver, detectInstallKind, resolveNpmChannelTag, resolvePackageRoot } from "./update-check.js";
+import { dirname, join } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+//#region src/infra/update-startup.ts
+init_paths();
+init_package_version();
+init_logger();
+const log = createLogger("UpdateCheck");
+const UPDATE_CHECK_FILENAME = "update-check.json";
+const CHECK_INTERVAL_MS = 1440 * 60 * 1e3;
+const ONE_HOUR_MS = 3600 * 1e3;
+let updateAvailableCache = null;
+/** Get the cached update-available state (populated after startup check). */
+function getUpdateAvailable() {
+	return updateAvailableCache;
+}
+async function readState(statePath) {
+	try {
+		const raw = await readFile(statePath, "utf-8");
+		const parsed = JSON.parse(raw);
+		return parsed && typeof parsed === "object" ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+async function writeState(statePath, state) {
+	await mkdir(dirname(statePath), { recursive: true });
+	await writeFile(statePath, JSON.stringify(state, null, 2), "utf-8");
+}
+function resolveCheckIntervalMs(config) {
+	const auto = config.update?.auto;
+	if (!auto?.enabled) return CHECK_INTERVAL_MS;
+	if ((normalizeUpdateChannel(config.update?.channel) ?? "stable") === "beta") {
+		const hours = auto.betaCheckIntervalHours ?? 1;
+		return Math.max(ONE_HOUR_MS / 4, Math.floor(hours * ONE_HOUR_MS));
+	}
+	return ONE_HOUR_MS;
+}
+/**
+* Compute a deterministic delay for stable auto-update rollout,
+* based on a per-installation hash to spread updates over time.
+*/
+function resolveStableJitterMs(installId, version, tag, jitterWindowMs) {
+	if (jitterWindowMs <= 0) return 0;
+	return createHash("sha256").update(`${installId}:${version}:${tag}`).digest().readUInt32BE(0) % (Math.floor(jitterWindowMs) + 1);
+}
+/**
+* Main startup update check. Called once when the gateway starts (or on demand).
+*/
+async function runGatewayUpdateCheck(params) {
+	const { config, force } = params;
+	const autoEnabled = config.update?.auto?.enabled ?? false;
+	const shouldCheckHints = config.update?.checkOnStart !== false;
+	if (!force && !shouldCheckHints && !autoEnabled) return;
+	const statePath = join(resolveStateDir(), UPDATE_CHECK_FILENAME);
+	const state = await readState(statePath);
+	const now = Date.now();
+	const lastCheckedAt = state.lastCheckedAt ? Date.parse(state.lastCheckedAt) : null;
+	if (state.lastAvailableVersion && (shouldCheckHints || force)) {
+		const comparison = compareSemver(PACKAGE_VERSION, state.lastAvailableVersion);
+		if (comparison !== null && comparison < 0) {
+			const cached = {
+				currentVersion: PACKAGE_VERSION,
+				latestVersion: state.lastAvailableVersion,
+				channel: state.lastAvailableTag ?? "latest"
+			};
+			updateAvailableCache = cached;
+			params.onUpdateAvailableChange?.(cached);
+		}
+	}
+	const checkIntervalMs = resolveCheckIntervalMs(config);
+	const shouldBypassThrottleForVersion = state.lastCheckPackageVersion === void 0 || state.lastCheckPackageVersion !== PACKAGE_VERSION;
+	if (!force && !shouldBypassThrottleForVersion && lastCheckedAt && Number.isFinite(lastCheckedAt) && now - lastCheckedAt < checkIntervalMs) return;
+	const root = await resolvePackageRoot();
+	let installKind = "unknown";
+	if (root) {
+		installKind = await detectInstallKind(root);
+		if (installKind === "git") log.info("Update check: git checkout (hint-only; use git pull to update, no auto npm install)");
+	}
+	const channel = normalizeUpdateChannel(config.update?.channel) ?? "stable";
+	const resolved = await resolveNpmChannelTag({
+		channel,
+		timeoutMs: 2500
+	});
+	const nextState = {
+		...state,
+		lastCheckedAt: new Date(now).toISOString()
+	};
+	if (!resolved.version) {
+		nextState.lastCheckPackageVersion = PACKAGE_VERSION;
+		await writeState(statePath, nextState);
+		return;
+	}
+	const comparison = compareSemver(PACKAGE_VERSION, resolved.version);
+	if (comparison !== null && comparison < 0) {
+		const updateInfo = {
+			currentVersion: PACKAGE_VERSION,
+			latestVersion: resolved.version,
+			channel: resolved.tag
+		};
+		if (shouldCheckHints || force) {
+			updateAvailableCache = updateInfo;
+			params.onUpdateAvailableChange?.(updateInfo);
+		}
+		nextState.lastAvailableVersion = resolved.version;
+		nextState.lastAvailableTag = resolved.tag;
+		const shouldNotify = state.lastNotifiedVersion !== resolved.version || state.lastNotifiedTag !== resolved.tag;
+		if ((shouldCheckHints || force) && shouldNotify) {
+			log.info({
+				currentVersion: PACKAGE_VERSION,
+				latestVersion: resolved.version,
+				tag: resolved.tag
+			}, `Update available (${resolved.tag}): v${resolved.version} (current v${PACKAGE_VERSION}). Run: xopc update`);
+			nextState.lastNotifiedVersion = resolved.version;
+			nextState.lastNotifiedTag = resolved.tag;
+		}
+		if (autoEnabled && (channel === "stable" || channel === "beta") && installKind !== "git") await handleAutoUpdate({
+			channel,
+			version: resolved.version,
+			tag: resolved.tag,
+			state,
+			nextState,
+			now,
+			root,
+			config
+		});
+	} else {
+		delete nextState.lastAvailableVersion;
+		delete nextState.lastAvailableTag;
+		updateAvailableCache = null;
+		params.onUpdateAvailableChange?.(null);
+	}
+	nextState.lastCheckPackageVersion = PACKAGE_VERSION;
+	await writeState(statePath, nextState);
+}
+async function handleAutoUpdate(params) {
+	const { channel, version, tag, state, nextState, now, root, config } = params;
+	const auto = config.update?.auto;
+	if (!auto) return;
+	const stableDelayHours = auto.stableDelayHours ?? 6;
+	const stableJitterHours = auto.stableJitterHours ?? 12;
+	const betaCheckIntervalHours = auto.betaCheckIntervalHours ?? 1;
+	const attemptIntervalMs = channel === "beta" ? Math.max(ONE_HOUR_MS / 4, Math.floor(betaCheckIntervalHours * ONE_HOUR_MS)) : ONE_HOUR_MS;
+	const lastAttemptAt = state.autoLastAttemptAt ? Date.parse(state.autoLastAttemptAt) : null;
+	if (state.autoLastAttemptVersion === version && lastAttemptAt !== null && Number.isFinite(lastAttemptAt) && now - lastAttemptAt < attemptIntervalMs) {
+		log.info({
+			version,
+			tag
+		}, "Auto-update deferred: recent attempt exists");
+		return;
+	}
+	if (channel === "stable") {
+		if (!nextState.autoInstallId) nextState.autoInstallId = state.autoInstallId?.trim() || randomUUID();
+		if (state.autoFirstSeenVersion !== version || state.autoFirstSeenTag !== tag) {
+			nextState.autoFirstSeenVersion = version;
+			nextState.autoFirstSeenTag = tag;
+			nextState.autoFirstSeenAt = new Date(now).toISOString();
+		} else nextState.autoFirstSeenAt = state.autoFirstSeenAt;
+		const firstSeenMs = nextState.autoFirstSeenAt ? Date.parse(nextState.autoFirstSeenAt) : now;
+		const baseDelayMs = Math.max(0, stableDelayHours) * ONE_HOUR_MS;
+		const jitterWindowMs = Math.max(0, stableJitterHours) * ONE_HOUR_MS;
+		const jitterMs = resolveStableJitterMs(nextState.autoInstallId, version, tag, jitterWindowMs);
+		const applyAfterMs = firstSeenMs + baseDelayMs + jitterMs;
+		if (now < applyAfterMs) {
+			log.info({
+				version,
+				tag,
+				applyAfter: new Date(applyAfterMs).toISOString()
+			}, "Auto-update deferred: stable rollout window not yet due");
+			return;
+		}
+	}
+	nextState.autoLastAttemptVersion = version;
+	nextState.autoLastAttemptAt = new Date(now).toISOString();
+	log.info({
+		channel,
+		version,
+		tag
+	}, "Starting auto-update");
+	try {
+		const { runAutoUpdateCommand } = await import("./update-runner.js");
+		const result = await runAutoUpdateCommand({
+			channel,
+			root
+		});
+		if (result.ok) {
+			nextState.autoLastSuccessVersion = version;
+			nextState.autoLastSuccessAt = new Date(now).toISOString();
+			log.info({
+				channel,
+				version,
+				tag
+			}, "Auto-update applied successfully");
+		} else log.warn({
+			channel,
+			version,
+			tag,
+			exitCode: result.exitCode,
+			reason: result.reason
+		}, `Auto-update attempt failed: ${result.reason ?? `exit ${result.exitCode}`}`);
+	} catch (err) {
+		log.error({
+			err,
+			channel,
+			version
+		}, "Auto-update command threw");
+	}
+}
+/**
+* Schedule periodic update checks. Returns a cleanup function to stop the timer.
+*/
+function scheduleGatewayUpdateCheck(params) {
+	let stopped = false;
+	let timer = null;
+	const tick = async () => {
+		if (stopped) return;
+		try {
+			await runGatewayUpdateCheck(params);
+		} catch (err) {
+			log.warn({ err }, "Periodic update check failed");
+		}
+		if (!stopped) {
+			const intervalMs = resolveCheckIntervalMs(params.config);
+			timer = setTimeout(() => void tick(), intervalMs);
+		}
+	};
+	timer = setTimeout(() => void tick(), 5e3);
+	return () => {
+		stopped = true;
+		if (timer) {
+			clearTimeout(timer);
+			timer = null;
+		}
+	};
+}
+//#endregion
+export { getUpdateAvailable, runGatewayUpdateCheck, scheduleGatewayUpdateCheck };
+
+//# sourceMappingURL=update-startup.js.map