@juancr11/sibu 0.1.0

package/bin/features/use-skill/handler.js

@@ -0,0 +1,197 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { log } from '@clack/prompts';
+import { STATE_RELATIVE_PATH, resolveSelectableSkillById } from '../../shared/catalog.js';
+import { sha256 } from '../../shared/hash.js';
+import { getProjectContext } from '../../shared/paths.js';
+import { renderTemplateForSync } from '../../shared/templates.js';
+import { getWorkflowMutationReadiness } from '../../shared/workflow-mutation-readiness.js';
+import { getSelectedAgentsFromState, getWorkflowTargets, renderMissingWorkflowFiles, writeSibuState } from '../../shared/workflow-targets.js';
+export async function handleUseSkill(command) {
+    const { rootPath, statePath } = getProjectContext();
+    const readiness = getWorkflowMutationReadiness({ rootPath, statePath });
+    if (!readiness.ok) {
+        log.error(readiness.message);
+        log.info(readiness.hint);
+        for (const preview of readiness.actionablePreviews?.slice(0, 3) ?? []) {
+            log.info(`${preview.relativePath}: ${preview.status}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const selectionResult = getNextSkillSelection(readiness.state, command.skillName);
+    switch (selectionResult.status) {
+        case 'noop':
+            log.success(selectionResult.message);
+            log.info('No files changed.');
+            return;
+        case 'blocked':
+            log.error(selectionResult.message);
+            if (selectionResult.hint) {
+                log.info(selectionResult.hint);
+            }
+            process.exitCode = 1;
+            return;
+        case 'selected':
+            applySelectedSkill({ rootPath, statePath, state: readiness.state, selectionResult });
+            return;
+    }
+}
+export function getNextSkillSelection(state, skillName) {
+    const resolution = resolveSelectableSkillById(skillName);
+    if (!resolution.ok) {
+        return { status: 'blocked', message: resolution.message };
+    }
+    const selectedLanguageSkills = [...(state.selectedLanguageSkills ?? [])];
+    const selectedFrameworkSkills = [...(state.selectedFrameworkSkills ?? [])];
+    switch (resolution.resolved.kind) {
+        case 'language':
+            if (selectedLanguageSkills.includes(resolution.resolved.skill.id)) {
+                return { status: 'noop', message: `${resolution.resolved.skill.name} is already selected.` };
+            }
+            return {
+                status: 'selected',
+                skillName: resolution.resolved.skill.name,
+                selection: {
+                    selectedLanguageSkills: [...selectedLanguageSkills, resolution.resolved.skill.id].map(getLanguageSkillById),
+                    selectedFrameworkSkills: selectedFrameworkSkills.map(getFrameworkSkillById),
+                    selectedArchitectureSkill: getArchitectureSkillById(state.selectedArchitectureSkill),
+                },
+            };
+        case 'framework':
+            if (selectedFrameworkSkills.includes(resolution.resolved.skill.id)) {
+                return { status: 'noop', message: `${resolution.resolved.skill.name} is already selected.` };
+            }
+            return {
+                status: 'selected',
+                skillName: resolution.resolved.skill.name,
+                selection: {
+                    selectedLanguageSkills: selectedLanguageSkills.map(getLanguageSkillById),
+                    selectedFrameworkSkills: [...selectedFrameworkSkills, resolution.resolved.skill.id].map(getFrameworkSkillById),
+                    selectedArchitectureSkill: getArchitectureSkillById(state.selectedArchitectureSkill),
+                },
+            };
+        case 'architecture':
+            if (state.selectedArchitectureSkill === resolution.resolved.skill.id) {
+                return { status: 'noop', message: `${resolution.resolved.skill.name} is already selected.` };
+            }
+            if (state.selectedArchitectureSkill) {
+                return {
+                    status: 'blocked',
+                    message: `Cannot select ${resolution.resolved.skill.name} because another architecture skill is already selected.`,
+                    hint: 'Architecture skill replacement is not supported yet. Keep the existing architecture skill or stop managing it first.',
+                };
+            }
+            return {
+                status: 'selected',
+                skillName: resolution.resolved.skill.name,
+                selection: {
+                    selectedLanguageSkills: selectedLanguageSkills.map(getLanguageSkillById),
+                    selectedFrameworkSkills: selectedFrameworkSkills.map(getFrameworkSkillById),
+                    selectedArchitectureSkill: resolution.resolved.skill,
+                },
+            };
+    }
+}
+function applySelectedSkill({ rootPath, statePath, state, selectionResult, }) {
+    const plan = buildSkillApplicationPlan({ rootPath, state, selectionResult });
+    const preflightError = getSkillApplicationPreflightError({ rootPath, state, plan });
+    if (preflightError) {
+        log.error(preflightError);
+        log.info('Run `sibu sync` to review workflow state before selecting a skill.');
+        process.exitCode = 1;
+        return;
+    }
+    const agentsContents = renderTemplateForSync({
+        templateRelativePath: plan.agentsTarget.templateRelativePath,
+        currentPath: plan.agentsTarget.targetPath,
+        selectedLanguageSkills: selectionResult.selection.selectedLanguageSkills,
+        selectedFrameworkSkills: selectionResult.selection.selectedFrameworkSkills,
+        selectedArchitectureSkill: selectionResult.selection.selectedArchitectureSkill,
+    });
+    const [newSkillFile] = renderMissingWorkflowFiles({
+        missingTargets: [plan.newSkillTarget],
+        selectedLanguageSkills: selectionResult.selection.selectedLanguageSkills,
+        selectedFrameworkSkills: selectionResult.selection.selectedFrameworkSkills,
+        selectedArchitectureSkill: selectionResult.selection.selectedArchitectureSkill,
+    });
+    fs.mkdirSync(path.dirname(newSkillFile.targetPath), { recursive: true });
+    fs.writeFileSync(newSkillFile.targetPath, newSkillFile.contents, { encoding: 'utf8', flag: 'wx' });
+    log.success(`Created ${newSkillFile.label}`);
+    fs.writeFileSync(plan.agentsTarget.targetPath, agentsContents, 'utf8');
+    log.success('Updated AGENTS.md skill routing');
+    writeSibuState({
+        rootPath,
+        statePath,
+        selectedAgents: plan.selectedAgents,
+        selectedLanguageSkills: selectionResult.selection.selectedLanguageSkills,
+        selectedFrameworkSkills: selectionResult.selection.selectedFrameworkSkills,
+        selectedArchitectureSkill: selectionResult.selection.selectedArchitectureSkill,
+        targets: plan.targets,
+    });
+    log.success(`Updated ${STATE_RELATIVE_PATH}`);
+    log.success(`Added ${selectionResult.skillName}.`);
+}
+function buildSkillApplicationPlan({ rootPath, state, selectionResult, }) {
+    const selectedAgents = getSelectedAgentsFromState(state);
+    const previousTargets = getWorkflowTargets(rootPath, selectedAgents, getSelectedLanguageSkillsFromState(state), getSelectedFrameworkSkillsFromState(state), getArchitectureSkillById(state.selectedArchitectureSkill));
+    const targets = getWorkflowTargets(rootPath, selectedAgents, selectionResult.selection.selectedLanguageSkills, selectionResult.selection.selectedFrameworkSkills, selectionResult.selection.selectedArchitectureSkill);
+    const previousTargetPaths = new Set(previousTargets.map((target) => target.targetPath));
+    const newSkillTarget = targets.find((target) => !previousTargetPaths.has(target.targetPath));
+    const agentsTarget = targets.find((target) => target.label === 'AGENTS.md');
+    if (!newSkillTarget) {
+        throw new Error(`No new workflow target found for ${selectionResult.skillName}.`);
+    }
+    if (!agentsTarget) {
+        throw new Error('AGENTS.md target is missing from workflow targets.');
+    }
+    return { agentsTarget, newSkillTarget, targets, selectedAgents };
+}
+function getSkillApplicationPreflightError({ rootPath, state, plan }) {
+    if (fs.existsSync(plan.newSkillTarget.targetPath)) {
+        return `${path.relative(rootPath, plan.newSkillTarget.targetPath)} already exists but is not recorded for this selection.`;
+    }
+    const agentsRelativePath = path.relative(rootPath, plan.agentsTarget.targetPath);
+    const agentsManagedFile = state.managedFiles[agentsRelativePath];
+    if (!agentsManagedFile) {
+        return 'AGENTS.md is not recorded in `.sibu/state.json`.';
+    }
+    if (!fs.existsSync(plan.agentsTarget.targetPath)) {
+        return 'AGENTS.md is missing.';
+    }
+    const agentsCurrentHash = sha256(fs.readFileSync(plan.agentsTarget.targetPath, 'utf8'));
+    if (agentsCurrentHash !== agentsManagedFile.sha256) {
+        return 'AGENTS.md has changed since Sibu last recorded it.';
+    }
+    return undefined;
+}
+function getSelectedLanguageSkillsFromState(state) {
+    return (state.selectedLanguageSkills ?? []).map(getLanguageSkillById);
+}
+function getSelectedFrameworkSkillsFromState(state) {
+    return (state.selectedFrameworkSkills ?? []).map(getFrameworkSkillById);
+}
+function getLanguageSkillById(skillId) {
+    const resolution = resolveSelectableSkillById(skillId);
+    if (!resolution.ok || resolution.resolved.kind !== 'language') {
+        throw new Error(`Unsupported language skill in state: ${skillId}`);
+    }
+    return resolution.resolved.skill;
+}
+function getFrameworkSkillById(skillId) {
+    const resolution = resolveSelectableSkillById(skillId);
+    if (!resolution.ok || resolution.resolved.kind !== 'framework') {
+        throw new Error(`Unsupported framework skill in state: ${skillId}`);
+    }
+    return resolution.resolved.skill;
+}
+function getArchitectureSkillById(skillId) {
+    if (!skillId) {
+        return undefined;
+    }
+    const resolution = resolveSelectableSkillById(skillId);
+    if (!resolution.ok || resolution.resolved.kind !== 'architecture') {
+        throw new Error(`Unsupported architecture skill in state: ${skillId}`);
+    }
+    return resolution.resolved.skill;
+}

package/bin/shared/catalog.js

@@ -0,0 +1,199 @@
+export const SIBU_PACKAGE_NAME = '@juancr11/sibu';
+export const SIBU_VERSION = '0.1.0';
+export const STATE_RELATIVE_PATH = '.sibu/state.json';
+export const NPM_VERSION_LOOKUP_MODE_ENV = 'SIBU_NPM_LOOKUP_MODE';
+export const NPM_VERSION_OVERRIDE_ENV = 'SIBU_NPM_LATEST_VERSION';
+export const SIBU_CACHE_HOME_ENV = 'SIBU_CACHE_HOME';
+export const SUPPORTED_NPM_LOOKUP_MODES = ['live', 'offline'];
+export const MANDATORY_SKILLS = [
+    {
+        templateRelativePath: 'skills/clean-code/SKILL.md',
+        targetRelativePathsByAgent: {
+            codex: '.agents/skills/clean-code/SKILL.md',
+            gemini: '.agents/skills/clean-code/SKILL.md',
+            claude: '.agents/skills/clean-code/SKILL.md',
+            windsurf: '.agents/skills/clean-code/SKILL.md',
+        },
+    },
+    {
+        templateRelativePath: 'skills/product-vision-writer/SKILL.md',
+        targetRelativePathsByAgent: {
+            codex: '.agents/skills/product-vision-writer/SKILL.md',
+            gemini: '.agents/skills/product-vision-writer/SKILL.md',
+            claude: '.agents/skills/product-vision-writer/SKILL.md',
+            windsurf: '.agents/skills/product-vision-writer/SKILL.md',
+        },
+    },
+    {
+        templateRelativePath: 'skills/feature-brief-writer/SKILL.md',
+        targetRelativePathsByAgent: {
+            codex: '.agents/skills/feature-brief-writer/SKILL.md',
+            gemini: '.agents/skills/feature-brief-writer/SKILL.md',
+            claude: '.agents/skills/feature-brief-writer/SKILL.md',
+            windsurf: '.agents/skills/feature-brief-writer/SKILL.md',
+        },
+    },
+    {
+        templateRelativePath: 'skills/technical-design-writer/SKILL.md',
+        targetRelativePathsByAgent: {
+            codex: '.agents/skills/technical-design-writer/SKILL.md',
+            gemini: '.agents/skills/technical-design-writer/SKILL.md',
+            claude: '.agents/skills/technical-design-writer/SKILL.md',
+            windsurf: '.agents/skills/technical-design-writer/SKILL.md',
+        },
+    },
+    {
+        templateRelativePath: 'skills/scrum-master-planner/SKILL.md',
+        targetRelativePathsByAgent: {
+            codex: '.agents/skills/scrum-master-planner/SKILL.md',
+            gemini: '.agents/skills/scrum-master-planner/SKILL.md',
+            claude: '.agents/skills/scrum-master-planner/SKILL.md',
+            windsurf: '.agents/skills/scrum-master-planner/SKILL.md',
+        },
+    },
+    {
+        templateRelativePath: 'skills/ai-implementation-planner/SKILL.md',
+        targetRelativePathsByAgent: {
+            codex: '.agents/skills/ai-implementation-planner/SKILL.md',
+            gemini: '.agents/skills/ai-implementation-planner/SKILL.md',
+            claude: '.agents/skills/ai-implementation-planner/SKILL.md',
+            windsurf: '.agents/skills/ai-implementation-planner/SKILL.md',
+        },
+    },
+    {
+        templateRelativePath: 'skills/ai-implementation-plan-executor/SKILL.md',
+        targetRelativePathsByAgent: {
+            codex: '.agents/skills/ai-implementation-plan-executor/SKILL.md',
+            gemini: '.agents/skills/ai-implementation-plan-executor/SKILL.md',
+            claude: '.agents/skills/ai-implementation-plan-executor/SKILL.md',
+            windsurf: '.agents/skills/ai-implementation-plan-executor/SKILL.md',
+        },
+    },
+];
+export const SELECTABLE_LANGUAGE_SKILLS = [
+    {
+        id: 'typescript',
+        name: 'TypeScript',
+        description: 'Install practical guidance for writing and modifying .ts and .tsx files',
+        routingInstruction: 'For any task that changes `.ts` or `.tsx` files, also use `typescript`.',
+        templateRelativePath: 'skills/typescript/SKILL.md',
+        targetRelativePathsByAgent: {
+            codex: '.agents/skills/typescript/SKILL.md',
+            gemini: '.agents/skills/typescript/SKILL.md',
+            claude: '.agents/skills/typescript/SKILL.md',
+            windsurf: '.agents/skills/typescript/SKILL.md',
+        },
+    },
+    {
+        id: 'golang',
+        name: 'Go',
+        description: 'Install practical guidance for writing and modifying .go files',
+        routingInstruction: 'For any task that changes `.go` files, also use `golang`.',
+        templateRelativePath: 'skills/golang/SKILL.md',
+        targetRelativePathsByAgent: {
+            codex: '.agents/skills/golang/SKILL.md',
+            gemini: '.agents/skills/golang/SKILL.md',
+            claude: '.agents/skills/golang/SKILL.md',
+            windsurf: '.agents/skills/golang/SKILL.md',
+        },
+    },
+];
+export const SELECTABLE_FRAMEWORK_SKILLS = [
+    {
+        id: 'react',
+        name: 'React',
+        description: 'Install guidance for React components, props, state ownership, and component boundaries',
+        routingInstruction: 'For tasks that create or change React components, component responsibility, props, state ownership, or presentational vs data-owning boundaries, use `react`.',
+        templateRelativePath: 'skills/react/SKILL.md',
+        targetRelativePathsByAgent: {
+            codex: '.agents/skills/react/SKILL.md',
+            gemini: '.agents/skills/react/SKILL.md',
+            claude: '.agents/skills/react/SKILL.md',
+            windsurf: '.agents/skills/react/SKILL.md',
+        },
+    },
+    {
+        id: 'nextjs',
+        name: 'Next.js',
+        description: 'Install guidance for Next.js App Router and framework-specific files',
+        routingInstruction: 'For tasks that change Next.js App Router or framework-specific files, including `src/app/**`, pages, layouts, route handlers, loading/error/not-found files, metadata, or Server/Client Component boundaries, use `nextjs`.',
+        templateRelativePath: 'skills/nextjs/SKILL.md',
+        targetRelativePathsByAgent: {
+            codex: '.agents/skills/nextjs/SKILL.md',
+            gemini: '.agents/skills/nextjs/SKILL.md',
+            claude: '.agents/skills/nextjs/SKILL.md',
+            windsurf: '.agents/skills/nextjs/SKILL.md',
+        },
+    },
+];
+export const SELECTABLE_ARCHITECTURE_SKILLS = [
+    {
+        id: 'ddd-hexagonal',
+        name: 'DDD + Hexagonal Architecture',
+        description: 'Install back-end architecture guidance for DDD, ports/adapters, and inward dependencies',
+        routingInstruction: 'For any back-end work, use `ddd-hexagonal`. This includes new features, refactors, bug fixes, persistence, external integrations, application/service boundaries, domain modeling, and architectural tradeoffs.',
+        templateRelativePath: 'skills/architecture/ddd-hexagonal/SKILL.md',
+        targetRelativePathsByAgent: {
+            codex: '.agents/skills/ddd-hexagonal/SKILL.md',
+            gemini: '.agents/skills/ddd-hexagonal/SKILL.md',
+            claude: '.agents/skills/ddd-hexagonal/SKILL.md',
+            windsurf: '.agents/skills/ddd-hexagonal/SKILL.md',
+        },
+    },
+    {
+        id: 'command-pattern',
+        name: 'Command Pattern',
+        description: 'Install architecture guidance for structuring executable operations as commands and handlers',
+        routingInstruction: 'For work that structures actions, workflows, command handlers, operation dispatch, request processing, or executable tasks, use `command-pattern`.',
+        templateRelativePath: 'skills/architecture/command-pattern/SKILL.md',
+        targetRelativePathsByAgent: {
+            codex: '.agents/skills/command-pattern/SKILL.md',
+            gemini: '.agents/skills/command-pattern/SKILL.md',
+            claude: '.agents/skills/command-pattern/SKILL.md',
+            windsurf: '.agents/skills/command-pattern/SKILL.md',
+        },
+    },
+];
+export const SUPPORTED_AGENTS = [
+    {
+        id: 'codex',
+        name: 'Codex',
+        description: 'Create .codex/config.toml pointing Codex to AGENTS.md',
+        targetRelativePath: '.codex/config.toml',
+        templateRelativePath: '.codex/config.toml',
+    },
+    {
+        id: 'gemini',
+        name: 'Gemini',
+        description: 'Create GEMINI.md that delegates to AGENTS.md',
+        targetRelativePath: 'GEMINI.md',
+        templateRelativePath: 'GEMINI.md',
+    },
+    {
+        id: 'claude',
+        name: 'Claude',
+        description: 'Create CLAUDE.md that delegates to AGENTS.md',
+        targetRelativePath: 'CLAUDE.md',
+        templateRelativePath: 'CLAUDE.md',
+    },
+    {
+        id: 'windsurf',
+        name: 'Windsurf',
+        description: 'Use root AGENTS.md and shared .agents/skills/ discovery',
+    },
+];
+export function resolveSelectableSkillById(skillId) {
+    const languageSkill = SELECTABLE_LANGUAGE_SKILLS.find((skill) => skill.id === skillId);
+    if (languageSkill) {
+        return { ok: true, resolved: { kind: 'language', skill: languageSkill } };
+    }
+    const frameworkSkill = SELECTABLE_FRAMEWORK_SKILLS.find((skill) => skill.id === skillId);
+    if (frameworkSkill) {
+        return { ok: true, resolved: { kind: 'framework', skill: frameworkSkill } };
+    }
+    const architectureSkill = SELECTABLE_ARCHITECTURE_SKILLS.find((skill) => skill.id === skillId);
+    if (architectureSkill) {
+        return { ok: true, resolved: { kind: 'architecture', skill: architectureSkill } };
+    }
+    return { ok: false, message: `Unknown skill \`${skillId}\`. Run \`sibu skills list\` to see available skills.` };
+}

package/bin/shared/hash.js

@@ -0,0 +1,11 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+export function sha256(contents) {
+    return crypto.createHash('sha256').update(contents).digest('hex');
+}
+export function readFileHashIfPresent(filePath) {
+    if (!fs.existsSync(filePath) || !fs.lstatSync(filePath).isFile()) {
+        return undefined;
+    }
+    return sha256(fs.readFileSync(filePath, 'utf8'));
+}

package/bin/shared/npm-version.js

@@ -0,0 +1,178 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { NPM_VERSION_LOOKUP_MODE_ENV, NPM_VERSION_OVERRIDE_ENV, SIBU_PACKAGE_NAME, SIBU_VERSION, SUPPORTED_NPM_LOOKUP_MODES } from './catalog.js';
+import { getNpmVersionCachePath } from './paths.js';
+const NPM_VERSION_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+const NPM_REGISTRY_URL = 'https://registry.npmjs.org';
+export async function checkForLatestSibuVersion(options = {}) {
+    const now = options.now ?? new Date();
+    const overrideResult = readOverrideResult(now);
+    if (overrideResult) {
+        return overrideResult;
+    }
+    const cachedRecord = readCachedNpmVersionResult();
+    if (cachedRecord.ok && isFreshCacheRecord(cachedRecord.record, now)) {
+        return {
+            ...cachedRecord.record,
+            source: 'cache',
+        };
+    }
+    const liveOutcome = await fetchLatestVersionOutcome({
+        fetchImpl: options.fetchImpl ?? fetch,
+        now,
+    });
+    writeCachedNpmVersionResult(liveOutcome);
+    return liveOutcome;
+}
+async function fetchLatestVersionOutcome({ fetchImpl, now }) {
+    try {
+        const response = await fetchImpl(`${NPM_REGISTRY_URL}/${encodeURIComponent(SIBU_PACKAGE_NAME)}/latest`, {
+            headers: { accept: 'application/json' },
+        });
+        if (!response.ok) {
+            return buildUnavailableOutcome({ checkedAt: now.toISOString(), reason: 'network-error' });
+        }
+        const payload = (await response.json());
+        const latestVersion = getLatestVersionFromPayload(payload);
+        if (!latestVersion) {
+            return buildUnavailableOutcome({ checkedAt: now.toISOString(), reason: 'invalid-response' });
+        }
+        return buildVersionedOutcome({
+            checkedAt: now.toISOString(),
+            latestVersion,
+            source: 'live',
+            status: compareVersions(latestVersion, SIBU_VERSION) > 0 ? 'update-available' : 'up-to-date',
+        });
+    }
+    catch {
+        return buildUnavailableOutcome({ checkedAt: now.toISOString(), reason: 'network-error' });
+    }
+}
+function readOverrideResult(now) {
+    const overrideMode = readLookupModeOverride();
+    if (overrideMode === 'offline') {
+        return buildUnavailableOutcome({
+            checkedAt: now.toISOString(),
+            reason: 'override',
+            source: 'override',
+        });
+    }
+    const overrideVersion = process.env[NPM_VERSION_OVERRIDE_ENV]?.trim();
+    if (!overrideVersion) {
+        return undefined;
+    }
+    return buildVersionedOutcome({
+        checkedAt: now.toISOString(),
+        latestVersion: overrideVersion,
+        source: 'override',
+        status: compareVersions(overrideVersion, SIBU_VERSION) > 0 ? 'update-available' : 'up-to-date',
+    });
+}
+function readLookupModeOverride() {
+    const value = process.env[NPM_VERSION_LOOKUP_MODE_ENV]?.trim().toLowerCase();
+    if (!value) {
+        return undefined;
+    }
+    return SUPPORTED_NPM_LOOKUP_MODES.find((mode) => mode === value);
+}
+function readCachedNpmVersionResult() {
+    const cachePath = getNpmVersionCachePath();
+    if (!fs.existsSync(cachePath)) {
+        return { ok: false, reason: 'missing' };
+    }
+    try {
+        const payload = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+        if (!isNpmVersionCacheRecord(payload)) {
+            return { ok: false, reason: 'invalid' };
+        }
+        return { ok: true, record: payload };
+    }
+    catch {
+        return { ok: false, reason: 'invalid' };
+    }
+}
+function writeCachedNpmVersionResult(result) {
+    const cachePath = getNpmVersionCachePath();
+    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    fs.writeFileSync(cachePath, `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+}
+function isFreshCacheRecord(record, now) {
+    const checkedAt = Date.parse(record.checkedAt);
+    if (Number.isNaN(checkedAt)) {
+        return false;
+    }
+    return now.getTime() - checkedAt < NPM_VERSION_CACHE_TTL_MS;
+}
+function getLatestVersionFromPayload(payload) {
+    if (!payload || typeof payload !== 'object') {
+        return undefined;
+    }
+    const version = payload.version;
+    return typeof version === 'string' && version.trim() ? version.trim() : undefined;
+}
+function buildVersionedOutcome({ checkedAt, latestVersion, source, status, }) {
+    return {
+        checkedAt,
+        currentVersion: SIBU_VERSION,
+        latestVersion,
+        packageName: SIBU_PACKAGE_NAME,
+        source,
+        status,
+    };
+}
+function buildUnavailableOutcome({ checkedAt, reason, source = 'live', }) {
+    return {
+        checkedAt,
+        packageName: SIBU_PACKAGE_NAME,
+        reason,
+        source,
+        status: 'unavailable',
+    };
+}
+function compareVersions(left, right) {
+    const leftParts = splitVersion(left);
+    const rightParts = splitVersion(right);
+    const maxLength = Math.max(leftParts.core.length, rightParts.core.length);
+    for (let index = 0; index < maxLength; index += 1) {
+        const leftValue = leftParts.core[index] ?? 0;
+        const rightValue = rightParts.core[index] ?? 0;
+        if (leftValue !== rightValue) {
+            return leftValue > rightValue ? 1 : -1;
+        }
+    }
+    if (leftParts.prerelease === rightParts.prerelease) {
+        return 0;
+    }
+    if (!leftParts.prerelease) {
+        return 1;
+    }
+    if (!rightParts.prerelease) {
+        return -1;
+    }
+    return leftParts.prerelease.localeCompare(rightParts.prerelease);
+}
+function splitVersion(version) {
+    const [core, prerelease] = version.trim().split('-', 2);
+    return {
+        core: core.split('.').map((part) => Number.parseInt(part, 10) || 0),
+        prerelease,
+    };
+}
+function isNpmVersionCacheRecord(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    if (record.status === 'unavailable') {
+        return (typeof record.checkedAt === 'string' &&
+            typeof record.packageName === 'string' &&
+            typeof record.reason === 'string' &&
+            typeof record.source === 'string');
+    }
+    return ((record.status === 'up-to-date' || record.status === 'update-available') &&
+        typeof record.checkedAt === 'string' &&
+        typeof record.currentVersion === 'string' &&
+        typeof record.latestVersion === 'string' &&
+        typeof record.packageName === 'string' &&
+        typeof record.source === 'string');
+}

package/bin/shared/object.js

@@ -0,0 +1,3 @@
+export function removeUndefinedFields(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, fieldValue]) => fieldValue !== undefined));
+}

package/bin/shared/paths.js

@@ -0,0 +1,41 @@
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SIBU_CACHE_HOME_ENV, STATE_RELATIVE_PATH } from './catalog.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export function getProjectContext() {
+    const rootPath = process.cwd();
+    return {
+        rootPath,
+        statePath: path.join(rootPath, STATE_RELATIVE_PATH),
+    };
+}
+export function getTemplatesPath() {
+    return path.join(__dirname, '..', '..', 'templates');
+}
+export function resolveManagedFilePath(rootPath, file) {
+    const absolutePath = path.isAbsolute(file) ? path.resolve(file) : path.resolve(rootPath, file);
+    const relativePath = path.relative(rootPath, absolutePath);
+    if (relativePath === '' || relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+        throw new Error(`Managed file path must be inside this project: ${file}`);
+    }
+    return {
+        absolutePath,
+        relativePath: relativePath.split(path.sep).join('/'),
+    };
+}
+export function getSideTemplatePath(rootPath, relativePath, templateVersion) {
+    const safeName = relativePath.replace(/[\\/]/g, '__');
+    return path.join(rootPath, '.sibu', 'sync', `${safeName}.template-v${templateVersion}`);
+}
+export function getSibuCacheRoot() {
+    const override = process.env[SIBU_CACHE_HOME_ENV]?.trim();
+    if (override) {
+        return path.resolve(override);
+    }
+    return path.join(os.homedir(), '.sibu');
+}
+export function getNpmVersionCachePath() {
+    return path.join(getSibuCacheRoot(), 'cache', 'npm-version.json');
+}