// Skill versioning for a workspace's installed skill copy drifting behind the // version this moi installation ships. The marker in each skill's `SKILL.md` // drives both the CLI status and the frontend's automatic update check. import { join } from 'node:path' import type { WorkspaceSkillStatus, WorkspaceType } from '@/lib/types' import { findWorkspaceForPath, liftToWorkspaceRoot, listWorkspaces } from '../workspaces/registry' import { bundledSkillDirectory } from './template' import { displaySkillPath, resolveSkillLocations } from './locations' import type { SkillLocation } from './locations' // The version is stamped as a self-contained marker in SKILL.md, e.g. // ``, rather than in YAML frontmatter. SKILL.md // frontmatter is NOT reliably strict YAML — the free-text `description` routinely // contains `: ` and other tokens that make real parsers reject the block — so a // controlled, unambiguous marker we own is both simpler and more robust than // scraping the frontmatter. Returns `null` when the file or marker is missing. const VERSION_MARKER = /]*\bversion="([^"]+)"/ export async function readSkillVersion(skillMdPath: string): Promise { const file = Bun.file(skillMdPath) if (!(await file.exists())) return null const m = (await file.text()).match(VERSION_MARKER) return m ? m[1] : null } // Bun.semver (built-in: `order` + `satisfies`) isn't in this repo's bun-types // yet, so reach it through a narrow typed view rather than `any`. const semver = ( Bun as unknown as { semver: { order(a: string, b: string): -1 | 0 | 1 satisfies(v: string, range: string): boolean } } ).semver function isValidVersion(v: string): boolean { try { semver.order(v, v) return true } catch { return false } } // Compare an installed version against the bundled one with Bun's semver. // `behind` = bundled is strictly newer; `minorBehind` = that gap is at least a // minor bump (patch gaps stay silent). `~installed` spans installed's whole // major.minor, so a bundled version outside it is a minor-or-major bump. A // missing/invalid installed counts as behind (legacy or broken stamp → prompt); // a missing/invalid bundled never does (don't nag on our own broken ship). function compare( installed: string | null, bundled: string | null ): { behind: boolean; minorBehind: boolean } { if (!bundled || !isValidVersion(bundled)) return { behind: false, minorBehind: false } if (!installed || !isValidVersion(installed)) return { behind: true, minorBehind: true } const behind = semver.order(installed, bundled) < 0 return { behind, minorBehind: behind && !semver.satisfies(bundled, `~${installed}`) } } // Bundled is a MINOR-or-major release ahead — surfaced to the agent. Patch bumps // stay silent and ride along on the next minor update. export const isMinorBehind = (installed: string | null, bundled: string | null): boolean => compare(installed, bundled).minorBehind // Any difference at all, patch included — decides whether `moi skill update` // would change anything and whether the frontend should offer or run it. export const isBehind = (installed: string | null, bundled: string | null): boolean => compare(installed, bundled).behind // Report every installed copy, plus the required primary harness destination. export async function skillStatuses( workspaceRoot: string, type?: WorkspaceType ): Promise { return skillStatusesForLocations(await resolveSkillLocations(workspaceRoot, type)) } export async function skillStatusesForLocations( locations: SkillLocation[] ): Promise { return Promise.all( locations.map(async ({ name, path, brokenLink }) => ({ name, path, bundled: await readSkillVersion(join(bundledSkillDirectory(name), 'SKILL.md')), installed: brokenLink ? null : await readSkillVersion(join(path, 'SKILL.md')) })) ) } export type ResolvedWorkspace = { root: string; type?: WorkspaceType } // Resolve a path to its workspace root: the registered workspace that owns it // (carrying its backend type), else lifted out of any `.moi/`, else the path // itself. Mirrors how `moi bundle` resolves a target so `moi skill` works from // the same places. export async function resolveWorkspace(cwd: string): Promise { const ws = findWorkspaceForPath(await listWorkspaces(), cwd) if (ws) return { root: ws.path, type: ws.type } return { root: liftToWorkspaceRoot(cwd) } } export async function resolveWorkspaceRoot(cwd: string): Promise { return (await resolveWorkspace(cwd)).root } // One-line, agent-facing notice when any installed skill is a minor+ behind the // bundled version — else `null`. Other commands append it to their output so // the agent reading that output knows to run `moi skill update`. Never throws: // version checks must not break the command they ride on. export async function staleSkillNotice(cwd: string): Promise { try { const { root, type } = await resolveWorkspace(cwd) const stale = (await skillStatuses(root, type)).filter(s => isMinorBehind(s.installed, s.bundled) ) if (stale.length === 0) return null const parts = stale.map( s => `${displaySkillPath(root, s.path)} (${s.installed ?? 'none'} → ${s.bundled})` ) return `⚠ Moi skill outdated: ${parts.join(', ')} — run \`moi skill update\` to refresh.` } catch { return null } }