@mytegroupinc/myte-core 0.0.55 → 0.0.57

package/lib/build-harness.js

@@ -0,0 +1,378 @@
+"use strict";
+
+// Project-generic build harness helpers. These functions deliberately work on
+// the public bootstrap snapshot only; they never mutate Myte state.
+
+function asText(value) {
+  const text = String(value ?? "").trim();
+  return text || "";
+}
+
+function asList(value) {
+  if (Array.isArray(value)) return value.filter((item) => item !== null && item !== undefined);
+  if (value === null || value === undefined || value === "") return [];
+  return [value];
+}
+
+function uniqueTexts(values) {
+  const seen = new Set();
+  const result = [];
+  for (const value of asList(values)) {
+    const text = typeof value === "object"
+      ? asText(value.name || value.label || value.title || value.id || value.value)
+      : asText(value);
+    if (!text || seen.has(text.toLowerCase())) continue;
+    seen.add(text.toLowerCase());
+    result.push(text);
+  }
+  return result;
+}
+
+function normalizeFeature(feature, index) {
+  if (!feature || typeof feature !== "object") return null;
+  const id = asText(feature.feature_id || feature.id || feature.key || `F${String(index + 1).padStart(3, "0")}`);
+  const title = asText(feature.title || feature.name || feature.label || id);
+  const dependencies = uniqueTexts(feature.dependencies || feature.depends_on || feature.dependencies_on);
+  const roles = uniqueTexts(feature.roles || feature.role || feature.stakeholders);
+  const entities = uniqueTexts(feature.entities || feature.related_entities || feature.domain_entities);
+  return {
+    feature_id: id,
+    title,
+    ...(asText(feature.description) ? { description: asText(feature.description) } : {}),
+    ...(roles.length ? { roles } : {}),
+    ...(entities.length ? { entities } : {}),
+    ...(dependencies.length ? { dependencies } : {}),
+  };
+}
+
+function normalizeEntityGraph(raw) {
+  if (!raw || typeof raw !== "object") return { entities: [], relationships: [] };
+  const entities = [];
+  const seen = new Set();
+  for (const item of asList(raw.entities || raw.nodes)) {
+    const entity = typeof item === "object"
+      ? { id: asText(item.id || item.name || item.label), label: asText(item.label || item.name || item.id) }
+      : { id: asText(item), label: asText(item) };
+    if (!entity.id || seen.has(entity.id.toLowerCase())) continue;
+    seen.add(entity.id.toLowerCase());
+    entities.push(entity);
+  }
+  const relationships = [];
+  const edgeSeen = new Set();
+  for (const edge of asList(raw.edges || raw.relationships)) {
+    if (!edge || typeof edge !== "object") continue;
+    const source = asText(edge.source || edge.from || edge.parent);
+    const target = asText(edge.target || edge.to || edge.child);
+    if (!source || !target) continue;
+    const key = `${source.toLowerCase()}|${target.toLowerCase()}`;
+    if (edgeSeen.has(key)) continue;
+    edgeSeen.add(key);
+    relationships.push({
+      source,
+      target,
+      ...(asText(edge.reason || edge.description) ? { reason: asText(edge.reason || edge.description) } : {}),
+    });
+  }
+  return { entities, relationships };
+}
+
+function inferRepositoryRole(name, index) {
+  const value = asText(name).toLowerCase();
+  if (/web|front|next|ui|client/.test(value)) return "web";
+  if (/api|back|server|fastapi|flask|django|python/.test(value)) return "api";
+  return index === 0 ? "api" : index === 1 ? "web" : "unknown";
+}
+
+function normalizeIntent(snapshot) {
+  const intent = snapshot?.intent || snapshot?.topology || {};
+  const rawFeatures = intent.features || snapshot?.features || [];
+  const features = asList(rawFeatures).map(normalizeFeature).filter(Boolean);
+  const graph = normalizeEntityGraph(intent.entity_graph || intent.entityGraph || snapshot?.entity_graph);
+  const roles = uniqueTexts(intent.roles || intent.stakeholders || features.flatMap((item) => item.roles || []));
+  const workflows = asList(intent.workflows || snapshot?.workflows)
+    .filter((item) => item && typeof item === "object")
+    .map((item, index) => ({
+      workflow_id: asText(item.workflow_id || item.id || item.key || `W${String(index + 1).padStart(3, "0")}`),
+      title: asText(item.title || item.name || item.label || `Workflow ${index + 1}`),
+      ...(asText(item.description) ? { description: asText(item.description) } : {}),
+      roles: uniqueTexts(item.roles || item.stakeholders),
+      entities: uniqueTexts(item.entities || item.related_entities),
+      features: uniqueTexts(item.features || item.feature_ids),
+    }));
+  return {
+    roles,
+    features,
+    entity_graph: graph,
+    workflows,
+    source: intent.features || intent.entity_graph || intent.workflows ? "api_intent" : "mission_snapshot_only",
+  };
+}
+
+function missionStatusCounts(missions) {
+  const counts = {};
+  for (const mission of asList(missions)) {
+    const status = asText(mission?.status || "Unknown") || "Unknown";
+    counts[status] = (counts[status] || 0) + 1;
+  }
+  return counts;
+}
+
+function missionCoverage(missions) {
+  const active = asList(missions).filter((mission) => String(mission?.is_archived || "false") !== "true");
+  const ids = new Set(active.map((mission) => asText(mission?.mission_id || mission?.id)).filter(Boolean));
+  const missingAcceptance = active.filter((mission) => !asList(mission?.acceptance_criteria || mission?.acceptanceCriteria).length)
+    .map((mission) => asText(mission?.mission_id || mission?.id)).filter(Boolean);
+  const missingTests = active.filter((mission) => !mission?.test_cases || typeof mission.test_cases !== "object")
+    .map((mission) => asText(mission?.mission_id || mission?.id)).filter(Boolean);
+  const missingDependencies = active.filter((mission) => !asList(mission?.depends_on).length)
+    .map((mission) => asText(mission?.mission_id || mission?.id)).filter(Boolean);
+  const orphaned = active.filter((mission) => !asText(mission?.story_id || mission?.epic_id || mission?.phase_id))
+    .map((mission) => asText(mission?.mission_id || mission?.id)).filter(Boolean);
+  return {
+    active_missions: active.length,
+    mission_ids: [...ids],
+    status_counts: missionStatusCounts(active),
+    missing_acceptance_criteria: missingAcceptance,
+    missing_test_cases: missingTests,
+    missing_dependency_metadata: missingDependencies,
+    orphaned_missions: orphaned,
+  };
+}
+
+function buildTopology(snapshot, local = {}) {
+  const repoNames = Array.isArray(snapshot?.repo_names) ? snapshot.repo_names.map(asText).filter(Boolean) : [];
+  const repoBindings = Array.isArray(snapshot?.repo_bindings) ? snapshot.repo_bindings : [];
+  const repositories = repoNames.map((name, index) => {
+    const binding = repoBindings.find((item) => asText(item?.client_repo_name || item?.canonical_repo_name || item?.repo_name) === name);
+    return {
+      name,
+      role: asText(binding?.role) || inferRepositoryRole(name, index),
+      ...(binding ? { binding: { role: asText(binding.role), path: asText(binding.path || binding.client_repo_name || name) } } : {}),
+    };
+  });
+  const intent = normalizeIntent(snapshot);
+  const missions = Array.isArray(snapshot?.missions) ? snapshot.missions : [];
+  const groups = new Map();
+  const activeMissions = missions.filter((mission) => String(mission?.is_archived || "false") !== "true");
+  for (const mission of activeMissions) {
+    const grouping = mission?.workflow_id
+      ? "workflow"
+      : mission?.domain
+        ? "domain"
+        : mission?.category
+          ? "category_fallback"
+          : mission?.epic_title
+            ? "epic_fallback"
+            : mission?.phase_name
+              ? "phase_fallback"
+              : "unclassified_fallback";
+    const key = asText(mission?.workflow_id || mission?.domain || mission?.category || mission?.epic_title || mission?.phase_name || "unclassified");
+    if (!groups.has(key)) groups.set(key, { missionIds: [], grouping });
+    const missionId = asText(mission?.mission_id || mission?.id);
+    if (missionId) groups.get(key).missionIds.push(missionId);
+  }
+  return {
+    schema_version: 1,
+    generated_at: new Date().toISOString(),
+    source_snapshot_hash: snapshot?.snapshot_hash || null,
+    project: snapshot?.project ? {
+      id: asText(snapshot.project.id || snapshot.project.project_id),
+      title: asText(snapshot.project.title || snapshot.project.name),
+      description: asText(snapshot.project.description),
+    } : null,
+    repositories,
+    intent,
+    mission_groups: [...groups.entries()].map(([group, details]) => ({
+      group,
+      mission_ids: details.missionIds,
+      grouping: details.grouping,
+      source: details.grouping.endsWith("_fallback") ? "fallback" : "bootstrap_metadata",
+    })),
+    mission_coverage: missionCoverage(missions),
+    local_repositories: {
+      mode: asText(local.mode) || "unknown",
+      found: Array.isArray(local.found) ? local.found : [],
+      missing: Array.isArray(local.missing) ? local.missing : [],
+    },
+  };
+}
+
+function buildBuildHarnessMarkdown(topology) {
+  const projectTitle = asText(topology?.project?.title) || "Myte project";
+  const groups = asList(topology?.mission_groups).map((item) => `- ${item.group}: ${(item.mission_ids || []).join(", ") || "none"}`).join("\n") || "- No mission groups were returned.";
+  return [
+    "# Myte Build Harness",
+    "",
+    `Generated for **${projectTitle}** by \`myte bootstrap\`.`,
+    "This is a project execution contract. It does not grant permissions or replace the API, repository, or deployment rules.",
+    "",
+    "## Global end goal",
+    "",
+    "Reach a coherent, tested, user-observable product state in which every active mission is complete and the final server bootstrap, QA/QC evidence, repository gates, and semantic review agree.",
+    "",
+    "## Harness rules",
+    "",
+    "1. Bootstrap before every execution cycle; never rely on remembered mission state.",
+    "2. Discover topology before implementation: roles, domains, workflows, entities, relationships, repositories, and mission dependencies.",
+    "3. Group work by product workflow and domain, not only by status or frontend/backend labels.",
+    "4. Map each mission to the owning frontend route/page/state/service/type/test and backend route/service/persistence/task/test surfaces.",
+    "5. Tie acceptance criteria to observable behavior, including loading, empty, error, denied, stale, and recovery states.",
+    "6. Update mission status only through the Myte API/CLI. Re-bootstrap after every status mutation.",
+    "7. Run focused tests first, then the owning repository gate before marking a group complete.",
+    "8. A passing build is insufficient: perform a semantic/UI review against the workflow and topology.",
+    "9. Record deviations when implementation changes the intended topology, ownership, workflow, or contract.",
+    "10. Finish only when the final bootstrap and local evidence agree that all active missions are complete.",
+    "",
+    "## Mission groups from bootstrap",
+    "",
+    groups,
+    "",
+    "## Required execution cycle",
+    "",
+    "1. Run `myte bootstrap --json`.",
+    "2. Read `data/build-topology.yml`, mission cards, `AgentsMyteAPI.md`, and repository `AGENTS.md` files.",
+    "3. Select one dependency-safe workflow group.",
+    "4. Inspect the complete user path and both repository ownership surfaces.",
+    "5. Add or update focused tests before implementation where acceptance behavior is missing.",
+    "6. Implement the smallest coherent change across the owning repositories.",
+    "7. Run focused tests and the repository quality gate.",
+    "8. Perform semantic/UI review and record any deviation.",
+    "9. Update the relevant mission status through `myte mission status`.",
+    "10. Run `myte bootstrap --json` again and verify the changed state.",
+    "",
+    "## Completion gate",
+    "",
+    "Run `myte build verify --json`. Completion requires zero active incomplete missions, no orphan missions, no missing acceptance criteria or test cases, no unresolved actionable suggestion threads, QA/QC evidence for applicable work, passing repository gates, and a recorded semantic review.",
+    "",
+    "## Evidence and deviations",
+    "",
+    "Keep final evidence and deviations in the Command Center. Do not put credentials, customer data, raw prompts, or secret values in the harness.",
+    "",
+  ].join("\n");
+}
+
+function normalizeMissionId(value) {
+  return asText(value).toLowerCase();
+}
+
+function qaqcMissionRecords(qaqc) {
+  if (Array.isArray(qaqc)) return qaqc;
+  if (!qaqc || typeof qaqc !== "object") return [];
+  return asList(qaqc.active_missions || qaqc.missions);
+}
+
+function qaqcMissionCoverage(topology, qaqc) {
+  const expectedMissionIds = uniqueTexts(topology?.mission_coverage?.mission_ids)
+    .map((missionId) => ({ key: normalizeMissionId(missionId), value: missionId }));
+  if (Number(topology?.mission_coverage?.active_missions || 0) > 0 && expectedMissionIds.length === 0) {
+    return {
+      expected_missions: [],
+      covered_missions: [],
+      missing_missions: [],
+      not_run_missions: [],
+      failed_missions: [],
+      pending_missions: [],
+      record_count: qaqcMissionRecords(qaqc).length,
+      topology_mission_ids_missing: true,
+      ok: false,
+    };
+  }
+  const expectedByKey = new Map(expectedMissionIds.map((item) => [item.key, item.value]));
+  const records = qaqcMissionRecords(qaqc);
+  const covered = new Set();
+  const missingRun = [];
+  const failed = [];
+  const pending = [];
+  const invalid = [];
+
+  for (const record of records) {
+    if (!record || typeof record !== "object") continue;
+    const missionId = asText(record.mission_id || record.id);
+    const key = normalizeMissionId(missionId);
+    if (!key || !expectedByKey.has(key)) continue;
+    const summary = record.qaqc || record.qa_qc_results;
+    if (!summary || typeof summary !== "object") {
+      invalid.push(missionId);
+      continue;
+    }
+    const status = asText(summary.status).toLowerCase();
+    const resultCounts = summary.result_counts && typeof summary.result_counts === "object"
+      ? summary.result_counts
+      : {};
+    const failureCount = Number(resultCounts.fail || 0);
+    const pendingCount = Number(resultCounts.pending || 0);
+    if (["not_run", "unknown", "pending", "queued", "running", ""].includes(status)) {
+      missingRun.push(missionId);
+      continue;
+    }
+    covered.add(key);
+    if (["failed", "error"].includes(status) || summary.has_error === true || failureCount > 0) {
+      failed.push(missionId);
+    }
+    if (pendingCount > 0) pending.push(missionId);
+  }
+
+  const missing = expectedMissionIds
+    .filter((item) => !covered.has(item.key))
+    .map((item) => item.value);
+  const missingCoverage = [...new Set([...missing, ...missingRun, ...invalid])];
+  return {
+    expected_missions: expectedMissionIds.map((item) => item.value),
+    covered_missions: expectedMissionIds.filter((item) => covered.has(item.key)).map((item) => item.value),
+    missing_missions: missingCoverage,
+    not_run_missions: [...new Set(missingRun)],
+    failed_missions: [...new Set(failed)],
+    pending_missions: [...new Set(pending)],
+    record_count: records.length,
+    ok: missingCoverage.length === 0 && failed.length === 0 && pending.length === 0,
+  };
+}
+
+function verifyTopology(topology, options = {}) {
+  const errors = [];
+  const warnings = [];
+  const coverage = topology?.mission_coverage || {};
+  if (!topology?.project?.id) errors.push("project id is missing");
+  if (!Array.isArray(topology?.repositories) || topology.repositories.length === 0) warnings.push("no configured repositories were returned");
+  for (const key of ["missing_acceptance_criteria", "missing_test_cases", "orphaned_missions"]) {
+    const values = Array.isArray(coverage[key]) ? coverage[key] : [];
+    if (values.length) errors.push(`${key}: ${values.join(", ")}`);
+  }
+  if (coverage.active_missions > 0 && !Object.keys(coverage.status_counts || {}).length) errors.push("mission status counts are missing");
+  if (topology?.intent?.source === "mission_snapshot_only") warnings.push("API intent topology was not returned; workflow/domain grouping is fallback-only");
+  if (topology?.intent?.source !== "mission_snapshot_only" && !(topology?.intent?.workflows || []).length) {
+    warnings.push("no explicit workflows were returned by bootstrap; validate workflow boundaries from the feature and entity graph");
+  }
+  if ((topology?.mission_groups || []).some((group) => group.source === "fallback")) {
+    warnings.push("one or more mission groups use fallback metadata; confirm the grouping matches a real product workflow");
+  }
+  if (!(options.semanticReview === true)) errors.push("semantic/UI review evidence is missing");
+  if (!(options.repositoryGates === true)) errors.push("repository gate evidence is missing");
+  if (coverage.active_missions > 0 && !(options.qaqcEvidence === true)) {
+    errors.push("QA/QC evidence is missing for active missions");
+  }
+  if (coverage.active_missions > 0 && options.qaqcEvidence === true && options.qaqcCoverage?.ok !== true) {
+    const qaqcCoverage = options.qaqcCoverage || {};
+    if (qaqcCoverage.topology_mission_ids_missing === true) {
+      errors.push("QA/QC coverage cannot be checked because mission ids are missing from the bootstrap topology");
+    }
+    if (qaqcCoverage.missing_missions?.length) {
+      errors.push(`QA/QC coverage is missing or not terminal for missions: ${qaqcCoverage.missing_missions.join(", ")}`);
+    }
+    if (qaqcCoverage.failed_missions?.length) {
+      errors.push(`QA/QC reports failures for missions: ${qaqcCoverage.failed_missions.join(", ")}`);
+    }
+    if (qaqcCoverage.pending_missions?.length) {
+      errors.push(`QA/QC has pending cases for missions: ${qaqcCoverage.pending_missions.join(", ")}`);
+    }
+  }
+  return { ok: errors.length === 0, errors, warnings };
+}
+
+module.exports = {
+  buildBuildHarnessMarkdown,
+  buildTopology,
+  qaqcMissionCoverage,
+  normalizeEntityGraph,
+  verifyTopology,
+};

package/lib/certification-manifest.js

@@ -11,6 +11,8 @@ const ARTIFACT_KINDS = new Set([
   "notification",
   "object",
   "query_job",
+  "feedback_ticket",
+  "ticket_batch",
 ]);
 const SENSITIVE_KEY = /(api[_-]?key|authorization|bearer|password|secret|token|credential)/i;
 

package/lib/package-update-check.js

@@ -0,0 +1,228 @@
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const DEFAULT_PACKAGE_NAME = "myte";
+const DEFAULT_PACKAGE_LATEST_URL = "https://registry.npmjs.org/myte/latest";
+const DEFAULT_TIMEOUT_MS = 1500;
+const DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_UNAVAILABLE_CACHE_TTL_MS = 15 * 60 * 1000;
+
+function parseSemverish(version) {
+  const main = String(version || "")
+    .trim()
+    .replace(/^v/i, "")
+    .split(/[+-]/)[0];
+  const match = main.match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  if (!match) return null;
+  return [match[1], match[2] || "0", match[3] || "0"].map((part) => Number(part));
+}
+
+function compareSemverish(left, right) {
+  const leftParts = parseSemverish(left);
+  const rightParts = parseSemverish(right);
+  if (!leftParts || !rightParts) return String(left || "").localeCompare(String(right || ""));
+  for (let index = 0; index < 3; index += 1) {
+    if (leftParts[index] > rightParts[index]) return 1;
+    if (leftParts[index] < rightParts[index]) return -1;
+  }
+  return 0;
+}
+
+function isVersionNewer(latest, installed) {
+  return compareSemverish(latest, installed) > 0;
+}
+
+function defaultCacheDirectory(env = process.env) {
+  if (env.MYTE_PACKAGE_UPDATE_CACHE_DIR) return String(env.MYTE_PACKAGE_UPDATE_CACHE_DIR);
+  if (process.platform === "win32" && env.LOCALAPPDATA) {
+    return path.join(env.LOCALAPPDATA, "Myte", "cache");
+  }
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Caches", "Myte");
+  }
+  return path.join(env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"), "myte");
+}
+
+function cacheFilePath({ packageName = DEFAULT_PACKAGE_NAME, cacheDir } = {}) {
+  const safeName = String(packageName || DEFAULT_PACKAGE_NAME).replace(/[^a-z0-9._-]/gi, "_");
+  return path.join(cacheDir || defaultCacheDirectory(), `package-update-${safeName}.json`);
+}
+
+function readCache(filePath) {
+  try {
+    const value = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    return value && typeof value === "object" ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(filePath, value) {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.${process.pid}.tmp`;
+    fs.writeFileSync(tempPath, `${JSON.stringify(value)}\n`, "utf8");
+    fs.renameSync(tempPath, filePath);
+  } catch {
+    // The update notice is advisory; cache failures must never affect a CLI command.
+  }
+}
+
+function isFresh(record, now, ttlMs) {
+  const checkedAt = Number(record?.checked_at || 0);
+  const age = now - checkedAt;
+  return checkedAt > 0 && age >= 0 && age < ttlMs;
+}
+
+function packageStatusBase({
+  packageName = DEFAULT_PACKAGE_NAME,
+  installedVersion = null,
+  latestUrl = DEFAULT_PACKAGE_LATEST_URL,
+  updateCommand = `npm install -g ${packageName}@latest`,
+} = {}) {
+  return {
+    name: packageName,
+    installed_version: installedVersion,
+    latest_version: null,
+    update_available: null,
+    check_status: "not-checked",
+    latest_url: latestUrl,
+    update_command: updateCommand,
+  };
+}
+
+async function defaultFetchJson(url, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const controller = typeof AbortController !== "undefined" ? new AbortController() : undefined;
+  const timeoutId = controller && timeoutMs > 0
+    ? setTimeout(() => controller.abort(), timeoutMs)
+    : undefined;
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      headers: { Accept: "application/json" },
+      signal: controller?.signal,
+    });
+    const text = await response.text();
+    let body = null;
+    try {
+      body = text.trim() ? JSON.parse(text) : null;
+    } catch {
+      body = null;
+    }
+    return { ok: Boolean(response.ok), status: response.status, body };
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
+  }
+}
+
+function statusFromCache(base, record, { unavailable = false } = {}) {
+  return {
+    ...base,
+    latest_version: record.latest_version || null,
+    update_available: typeof record.update_available === "boolean" ? record.update_available : null,
+    check_status: unavailable ? "cached-unavailable" : "cached",
+    checked_at: record.checked_at || null,
+  };
+}
+
+async function checkPackageUpdate({
+  packageName = DEFAULT_PACKAGE_NAME,
+  installedVersion,
+  latestUrl = DEFAULT_PACKAGE_LATEST_URL,
+  updateCommand = `npm install -g ${packageName}@latest`,
+  enabled = true,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  cacheTtlMs = DEFAULT_CACHE_TTL_MS,
+  unavailableCacheTtlMs = DEFAULT_UNAVAILABLE_CACHE_TTL_MS,
+  cacheDir,
+  fetchJson = defaultFetchJson,
+  now = () => Date.now(),
+} = {}) {
+  const base = packageStatusBase({ packageName, installedVersion, latestUrl, updateCommand });
+  if (!enabled) return { ...base, check_status: "skipped" };
+
+  const currentTime = Number(now()) || Date.now();
+  const filePath = cacheDir === false ? null : cacheFilePath({ packageName, cacheDir });
+  const cached = filePath ? readCache(filePath) : null;
+  if (cached && cached.latest_url === latestUrl && cached.installed_version === installedVersion) {
+    if (cached.check_status === "ok" && isFresh(cached, currentTime, cacheTtlMs)) {
+      return statusFromCache(base, cached);
+    }
+    if (cached.check_status === "unavailable" && isFresh(cached, currentTime, unavailableCacheTtlMs)) {
+      return statusFromCache(base, cached, { unavailable: true });
+    }
+  }
+
+  try {
+    const response = await fetchJson(latestUrl, { timeoutMs });
+    if (!response?.ok) {
+      const unavailable = {
+        latest_url: latestUrl,
+        installed_version: installedVersion,
+        latest_version: null,
+        update_available: null,
+        check_status: "unavailable",
+        checked_at: currentTime,
+      };
+      if (filePath) writeCache(filePath, unavailable);
+      return { ...base, ...unavailable, registry_status: response?.status || null };
+    }
+
+    const latestVersion = String(response?.body?.version || "").trim();
+    if (!latestVersion || !parseSemverish(latestVersion)) {
+      return { ...base, check_status: "invalid-response", checked_at: currentTime };
+    }
+
+    const result = {
+      ...base,
+      latest_version: latestVersion,
+      update_available: isVersionNewer(latestVersion, installedVersion),
+      check_status: "ok",
+      checked_at: currentTime,
+    };
+    if (filePath) {
+      writeCache(filePath, {
+        latest_url: latestUrl,
+        installed_version: installedVersion,
+        latest_version: result.latest_version,
+        update_available: result.update_available,
+        check_status: result.check_status,
+        checked_at: result.checked_at,
+      });
+    }
+    return result;
+  } catch (error) {
+    const unavailable = {
+      latest_url: latestUrl,
+      installed_version: installedVersion,
+      latest_version: null,
+      update_available: null,
+      check_status: "unavailable",
+      checked_at: currentTime,
+    };
+    if (filePath) writeCache(filePath, unavailable);
+    return {
+      ...base,
+      ...unavailable,
+      error: error?.message || String(error),
+    };
+  }
+}
+
+function packageUpdateNotice(status) {
+  if (!status || status.update_available !== true) return "";
+  return `myte package update available: ${status.latest_version} (installed ${status.installed_version}). Run ${status.update_command}`;
+}
+
+module.exports = {
+  checkPackageUpdate,
+  compareSemverish,
+  defaultCacheDirectory,
+  isVersionNewer,
+  packageStatusBase,
+  packageUpdateNotice,
+  parseSemverish,
+};