@nocobase/cli 2.2.0-beta.1 → 2.2.0-beta.10

package/dist/lib/self-manager.js

@@ -7,14 +7,12 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 import fs from 'node:fs';
-import fsp from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { resolveCliHomeDir } from './cli-home.js';
 import { commandOutput, run } from './run-npm.js';
 const DEFAULT_PACKAGE_NAME = '@nocobase/cli';
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-const INSTALL_METHOD_CACHE_FILE = 'self-install-methods.json';
 function normalizePath(value) {
     return path.resolve(value);
 }
@@ -97,6 +95,9 @@ function detectChannel(currentVersion) {
     if (/-beta(?:[.-]|$)/i.test(currentVersion)) {
         return 'beta';
     }
+    if (/-test(?:[.-]|$)/i.test(currentVersion)) {
+        return 'test';
+    }
     return 'latest';
 }
 function readCurrentVersion(packageRoot) {
@@ -105,56 +106,216 @@ function readCurrentVersion(packageRoot) {
     const pkg = JSON.parse(content);
     return String(pkg.version ?? '').trim();
 }
-function detectInstallMethod(packageRoot, globalPrefix) {
+function detectInstallMethod(packageRoot, options = {}) {
     if (fs.existsSync(path.join(packageRoot, 'src'))
         && fs.existsSync(path.join(packageRoot, 'tsconfig.json'))) {
         return 'source';
     }
-    if (globalPrefix && isSubPath(globalPrefix, packageRoot)) {
+    if (options.globalPrefix && isSubPath(options.globalPrefix, packageRoot)) {
         return 'npm-global';
     }
+    if (options.yarnGlobalDir && isSubPath(options.yarnGlobalDir, packageRoot)) {
+        return 'yarn-global';
+    }
+    if (isPnpmGlobalInstallPath({
+        packageName: options.packageName ?? DEFAULT_PACKAGE_NAME,
+        packageRoot,
+        pnpmGlobalBin: options.pnpmGlobalBin,
+        pnpmGlobalRoot: options.pnpmGlobalRoot,
+    })) {
+        return 'pnpm-global';
+    }
+    // Best-effort fallback for environments where pnpm probes are unavailable.
+    if (isPnpmGlobalPath(packageRoot)) {
+        return 'pnpm-global';
+    }
     if (packageRoot.includes(`${path.sep}node_modules${path.sep}`)) {
         return 'package-local';
     }
     return 'unknown';
 }
-function getInstallMethodCacheFile() {
-    return path.join(resolveCliHomeDir('global'), INSTALL_METHOD_CACHE_FILE);
+function isPnpmGlobalPath(packageRoot) {
+    const normalized = normalizePath(packageRoot);
+    const segments = normalized.split(path.sep).filter(Boolean);
+    const globalIndex = segments.findIndex((segment, index) => segment === 'global' && segments[index - 1] === 'pnpm');
+    if (globalIndex === -1) {
+        return false;
+    }
+    return segments.slice(globalIndex + 2).includes('node_modules');
 }
-function getInstallMethodCacheKey(packageRoot) {
-    return normalizePath(path.join(packageRoot, 'bin', 'run.js'));
+function normalizePnpmGlobalNodeModulesRoot(pnpmGlobalRoot) {
+    const normalizedGlobalRoot = normalizePath(pnpmGlobalRoot);
+    return path.basename(normalizedGlobalRoot) === 'node_modules'
+        ? normalizedGlobalRoot
+        : path.join(normalizedGlobalRoot, 'node_modules');
 }
-async function readInstallMethodCache() {
+function readSiblingPnpmGlobalNodeModulesRoots(pnpmGlobalRoot) {
+    const globalNodeModulesDir = normalizePnpmGlobalNodeModulesRoot(pnpmGlobalRoot);
+    const globalProjectDir = path.dirname(globalNodeModulesDir);
+    let entries;
     try {
-        const raw = await fsp.readFile(getInstallMethodCacheFile(), 'utf8');
-        return JSON.parse(raw);
+        entries = fs.readdirSync(globalProjectDir);
     }
     catch {
-        return {};
+        return [];
     }
+    return entries
+        .filter((entry) => {
+        if (entry === path.basename(globalNodeModulesDir)) {
+            return false;
+        }
+        try {
+            return fs.statSync(path.join(globalProjectDir, entry)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    })
+        .map((entry) => path.join(globalProjectDir, entry, 'node_modules'));
 }
-async function writeInstallMethodCache(state) {
-    const filePath = getInstallMethodCacheFile();
-    await fsp.mkdir(path.dirname(filePath), { recursive: true });
-    await fsp.writeFile(filePath, JSON.stringify(state, null, 2));
+function readPnpmGlobalNodeModulesRoots(pnpmGlobalRoot) {
+    return [normalizePnpmGlobalNodeModulesRoot(pnpmGlobalRoot), ...readSiblingPnpmGlobalNodeModulesRoots(pnpmGlobalRoot)];
 }
-async function readCachedInstallMethod(packageRoot) {
-    const state = await readInstallMethodCache();
-    return state.entries?.[getInstallMethodCacheKey(packageRoot)];
+function packageNameToPath(packageName) {
+    return packageName.split('/').filter(Boolean);
 }
-async function writeCachedInstallMethod(packageRoot, entry) {
-    const state = await readInstallMethodCache();
-    const entries = {
-        ...(state.entries ?? {}),
-        [getInstallMethodCacheKey(packageRoot)]: entry,
-    };
-    await writeInstallMethodCache({ entries });
+function isSameRealPath(left, right) {
+    try {
+        return normalizePath(fs.realpathSync(left)) === normalizePath(fs.realpathSync(right));
+    }
+    catch {
+        return false;
+    }
+}
+function isPnpmGlobalRootPath(pnpmGlobalRoot, packageRoot) {
+    if (isSubPath(pnpmGlobalRoot, packageRoot)) {
+        return true;
+    }
+    const globalNodeModulesDir = normalizePnpmGlobalNodeModulesRoot(pnpmGlobalRoot);
+    const globalProjectDir = path.dirname(globalNodeModulesDir);
+    if (!isSubPath(globalProjectDir, packageRoot)) {
+        return false;
+    }
+    const segments = normalizePath(packageRoot).split(path.sep).filter(Boolean);
+    const pnpmStoreIndex = segments.indexOf('.pnpm');
+    if (pnpmStoreIndex === -1) {
+        return false;
+    }
+    return segments.slice(pnpmStoreIndex + 1).includes('node_modules');
+}
+function isPnpmGlobalPackagePath(pnpmGlobalRoot, packageRoot, packageName) {
+    return readPnpmGlobalNodeModulesRoots(pnpmGlobalRoot).some((pnpmGlobalNodeModulesRoot) => isSameRealPath(path.join(pnpmGlobalNodeModulesRoot, ...packageNameToPath(packageName)), packageRoot));
+}
+function isPnpmGlobalBinProjectPath(pnpmGlobalBin, packageRoot, packageName) {
+    const pnpmHome = path.dirname(normalizePath(pnpmGlobalBin));
+    const globalDir = path.join(pnpmHome, 'global');
+    if (isSubPath(globalDir, packageRoot)) {
+        return true;
+    }
+    let entries;
+    try {
+        entries = fs.readdirSync(globalDir);
+    }
+    catch {
+        return false;
+    }
+    return entries.some((entry) => {
+        const pnpmGlobalRoot = path.join(globalDir, entry);
+        return (isPnpmGlobalRootPath(pnpmGlobalRoot, packageRoot)
+            || isPnpmGlobalPackagePath(pnpmGlobalRoot, packageRoot, packageName));
+    });
+}
+function isPnpmGlobalInstallPath(options) {
+    if (options.pnpmGlobalRoot) {
+        const matchedRoot = isPnpmGlobalRootPath(options.pnpmGlobalRoot, options.packageRoot)
+            || isPnpmGlobalPackagePath(options.pnpmGlobalRoot, options.packageRoot, options.packageName);
+        if (matchedRoot) {
+            return true;
+        }
+    }
+    if (options.pnpmGlobalBin) {
+        return isPnpmGlobalBinProjectPath(options.pnpmGlobalBin, options.packageRoot, options.packageName);
+    }
+    return false;
+}
+function readCurrentBinPath(currentBinPath) {
+    const candidate = String(currentBinPath ?? process.argv[1] ?? '').trim();
+    if (!candidate) {
+        return undefined;
+    }
+    return normalizePath(candidate);
+}
+function cleanCommandPath(value) {
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
+function resolvePackageManagerProbeCwd() {
+    const candidates = [os.homedir(), os.tmpdir(), path.parse(process.cwd()).root];
+    for (const candidate of candidates) {
+        if (!candidate) {
+            continue;
+        }
+        try {
+            if (fs.statSync(candidate).isDirectory()) {
+                return candidate;
+            }
+        }
+        catch {
+            // Ignore invalid probe cwd candidates and continue to the next one.
+        }
+    }
+    return undefined;
 }
 async function readGlobalPrefix(commandOutputFn) {
     try {
-        return (await commandOutputFn('npm', ['prefix', '-g'], {
+        return cleanCommandPath(await commandOutputFn('npm', ['prefix', '-g'], {
+            cwd: resolvePackageManagerProbeCwd(),
             errorName: 'npm prefix',
-        })).trim();
+        }));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readPnpmGlobalBin(commandOutputFn) {
+    try {
+        return cleanCommandPath(await commandOutputFn('pnpm', ['bin', '-g'], {
+            cwd: resolvePackageManagerProbeCwd(),
+            errorName: 'pnpm bin',
+        }));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readPnpmGlobalRoot(commandOutputFn) {
+    try {
+        return cleanCommandPath(await commandOutputFn('pnpm', ['root', '-g'], {
+            cwd: resolvePackageManagerProbeCwd(),
+            errorName: 'pnpm root',
+        }));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readYarnGlobalDir(commandOutputFn) {
+    try {
+        return cleanCommandPath(await commandOutputFn('yarn', ['global', 'dir'], {
+            cwd: resolvePackageManagerProbeCwd(),
+            errorName: 'yarn global dir',
+        }));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readYarnGlobalBin(commandOutputFn) {
+    try {
+        return cleanCommandPath(await commandOutputFn('yarn', ['global', 'bin'], {
+            cwd: resolvePackageManagerProbeCwd(),
+            errorName: 'yarn global bin',
+        }));
     }
     catch {
         return undefined;
@@ -171,21 +332,21 @@ function getUnsupportedSelfUpdateReason(installMethod) {
     if (installMethod === 'source') {
         return [
             'This CLI is running from source in a repository checkout.',
-            'Automatic self-update is only supported for standard global npm installs.',
+            'Automatic self-update is only supported for standard global npm, pnpm, or yarn installs.',
             'Upgrade this checkout through your repo workflow instead.',
         ].join(' ');
     }
     if (installMethod === 'package-local') {
         return [
             'This CLI is installed from a local project dependency tree.',
-            'Automatic self-update is only supported for standard global npm installs.',
+            'Automatic self-update is only supported for standard global npm, pnpm, or yarn installs.',
             'Upgrade the parent project dependency that provides this CLI instead.',
         ].join(' ');
     }
     if (installMethod === 'unknown') {
         return [
-            'This CLI install could not be recognized as a standard global npm install.',
-            'Automatic self-update is only supported for standard global npm installs.',
+            'This CLI install could not be recognized as a standard global npm, pnpm, or yarn install.',
+            'Automatic self-update is only supported for standard global npm, pnpm, or yarn installs.',
         ].join(' ');
     }
     return undefined;
@@ -214,22 +375,45 @@ export function getSelfUpdatePackageSpec(status) {
 }
 export async function inspectSelfInstall(options = {}) {
     const packageRoot = options.packageRoot ? normalizePath(options.packageRoot) : PACKAGE_ROOT;
+    const packageName = options.packageName ?? DEFAULT_PACKAGE_NAME;
     const commandOutputFn = options.commandOutputFn ?? commandOutput;
-    const cachedInstallMethod = await readCachedInstallMethod(packageRoot);
-    const globalPrefix = cachedInstallMethod?.globalPrefix ?? await readGlobalPrefix(commandOutputFn);
-    const installMethod = cachedInstallMethod?.installMethod ?? detectInstallMethod(packageRoot, globalPrefix);
-    if (!cachedInstallMethod) {
-        await writeCachedInstallMethod(packageRoot, {
-            installMethod,
-            globalPrefix,
-        });
-    }
+    const currentBinPath = readCurrentBinPath(options.currentBinPath);
+    const globalPrefix = await readGlobalPrefix(commandOutputFn);
+    const pnpmGlobalBin = await readPnpmGlobalBin(commandOutputFn);
+    const pnpmGlobalRoot = await readPnpmGlobalRoot(commandOutputFn);
+    const yarnGlobalDir = await readYarnGlobalDir(commandOutputFn);
+    const yarnGlobalBin = await readYarnGlobalBin(commandOutputFn);
+    const installMethod = detectInstallMethodFromSignals({
+        packageRoot,
+        currentBinPath,
+        globalPrefix,
+        packageName,
+        pnpmGlobalBin,
+        pnpmGlobalRoot,
+        yarnGlobalBin,
+        yarnGlobalDir,
+    });
     return {
         packageRoot,
         installMethod,
         globalPrefix,
     };
 }
+function detectInstallMethodFromSignals(options) {
+    if (options.currentBinPath && options.yarnGlobalBin && isSubPath(options.yarnGlobalBin, options.currentBinPath)) {
+        return 'yarn-global';
+    }
+    if (options.currentBinPath && options.pnpmGlobalBin && isSubPath(options.pnpmGlobalBin, options.currentBinPath)) {
+        return 'pnpm-global';
+    }
+    return detectInstallMethod(options.packageRoot, {
+        globalPrefix: options.globalPrefix,
+        packageName: options.packageName,
+        pnpmGlobalBin: options.pnpmGlobalBin,
+        pnpmGlobalRoot: options.pnpmGlobalRoot,
+        yarnGlobalDir: options.yarnGlobalDir,
+    });
+}
 export async function inspectSelfStatus(options = {}) {
     const packageRoot = options.packageRoot ? normalizePath(options.packageRoot) : PACKAGE_ROOT;
     const packageName = options.packageName ?? DEFAULT_PACKAGE_NAME;
@@ -237,6 +421,8 @@ export async function inspectSelfStatus(options = {}) {
     const channel = options.channel && options.channel !== 'auto' ? options.channel : detectChannel(currentVersion);
     const commandOutputFn = options.commandOutputFn ?? commandOutput;
     const { installMethod, globalPrefix } = await inspectSelfInstall({
+        currentBinPath: options.currentBinPath,
+        packageName,
         packageRoot,
         commandOutputFn,
     });
@@ -258,7 +444,7 @@ export async function inspectSelfStatus(options = {}) {
         latestVersion,
         updateAvailable,
         installMethod,
-        updatable: installMethod === 'npm-global',
+        updatable: installMethod === 'npm-global' || installMethod === 'pnpm-global' || installMethod === 'yarn-global',
         updateBlockedReason: getUnsupportedSelfUpdateReason(installMethod),
         globalPrefix,
         registryError,
@@ -267,9 +453,30 @@ export async function inspectSelfStatus(options = {}) {
 export function formatUnsupportedSelfUpdateMessage(status) {
     return status.updateBlockedReason
         ?? [
-            'Automatic self-update is only supported for standard global npm installs.',
+            'Automatic self-update is only supported for standard global npm, pnpm, or yarn installs.',
         ].join('\n');
 }
+function resolveSelfUpdateInstallCommand(installMethod, packageSpec) {
+    if (installMethod === 'pnpm-global') {
+        return {
+            command: 'pnpm',
+            args: ['add', '-g', packageSpec],
+            errorName: 'pnpm add',
+        };
+    }
+    if (installMethod === 'yarn-global') {
+        return {
+            command: 'yarn',
+            args: ['global', 'add', packageSpec],
+            errorName: 'yarn global add',
+        };
+    }
+    return {
+        command: 'npm',
+        args: ['install', '-g', packageSpec],
+        errorName: 'npm install',
+    };
+}
 export async function updateSelf(options = {}) {
     const status = await inspectSelfStatus(options);
     if (!status.updatable) {
@@ -288,9 +495,10 @@ export async function updateSelf(options = {}) {
         };
     }
     const packageSpec = getSelfUpdatePackageSpec(status);
-    await (options.runFn ?? run)('npm', ['install', '-g', packageSpec], {
+    const installCommand = resolveSelfUpdateInstallCommand(status.installMethod, packageSpec);
+    await (options.runFn ?? run)(installCommand.command, installCommand.args, {
         stdio: options.verbose ? 'inherit' : 'ignore',
-        errorName: 'npm install',
+        errorName: installCommand.errorName,
     });
     return {
         action: 'updated',

package/dist/lib/skills-manager.js

@@ -21,8 +21,8 @@ const NOCOBASE_SKILLS_NAME_PREFIX = 'nocobase-';
 // resolves and boots the package, even when the local skills installation is healthy.
 const SKILLS_LIST_TIMEOUT_MS = 15000;
 const SKILLS_NPM_VIEW_TIMEOUT_MS = 3000;
-const SKILLS_PACK_TIMEOUT_MS = 30000;
-const SKILLS_ADD_TIMEOUT_MS = 20000;
+const SKILLS_PACK_TIMEOUT_MS = 120000;
+const SKILLS_ADD_TIMEOUT_MS = 120000;
 const NPM_REGISTRY_UNAVAILABLE_PATTERNS = [
     'enotfound',
     'eai_again',
@@ -154,10 +154,13 @@ export async function listGlobalSkills(options = {}) {
 export async function listProjectSkills(options = {}) {
     return await listGlobalSkills(options);
 }
-function pickInstalledNocoBaseSkillNames(installedSkills, state) {
+function pickInstalledNocoBaseSkillNames(installedSkills, state, sourceSkillNames = []) {
     const installedNames = new Set(installedSkills.map((skill) => String(skill.name ?? '').trim()).filter(Boolean));
-    if (state?.skillNames?.length) {
-        return state.skillNames.filter((name) => installedNames.has(name)).sort();
+    const managedNames = new Set([...sourceSkillNames, ...(state?.skillNames ?? [])]);
+    if (managedNames.size > 0) {
+        return Array.from(managedNames)
+            .filter((name) => installedNames.has(name))
+            .sort();
     }
     return Array.from(installedNames)
         .filter((name) => name.startsWith(NOCOBASE_SKILLS_NAME_PREFIX))
@@ -194,6 +197,31 @@ async function readCachedSkillsVersion(cacheRoot) {
         return undefined;
     }
 }
+async function readCachedPackageSkillNames(globalRoot) {
+    const skillsDir = path.join(getCachedSkillsPackageDir(getSkillsCacheRoot(globalRoot)), 'skills');
+    try {
+        const entries = await fsp.readdir(skillsDir, { withFileTypes: true });
+        const skillNames = await Promise.all(entries
+            .filter((entry) => entry.isDirectory())
+            .map(async (entry) => {
+            const skillName = entry.name.trim();
+            if (!skillName) {
+                return undefined;
+            }
+            try {
+                await fsp.access(path.join(skillsDir, skillName, 'SKILL.md'));
+                return skillName;
+            }
+            catch {
+                return undefined;
+            }
+        }));
+        return skillNames.filter((name) => Boolean(name)).sort();
+    }
+    catch {
+        return [];
+    }
+}
 async function resolvePackedSkillsTarball(packRoot) {
     const entries = await fsp.readdir(packRoot, { withFileTypes: true });
     const tarballs = entries
@@ -251,6 +279,7 @@ async function prepareLocalSkillsPackage(globalRoot, options = {}, targetVersion
     const cachedVersion = await readCachedSkillsVersion(cacheRoot);
     await fsp.mkdir(cacheRoot, { recursive: true });
     if (targetVersion && cachedVersion && compareVersions(cachedVersion, targetVersion) === 0) {
+        options.onProgress?.(`Using cached ${NOCOBASE_SKILLS_PACKAGE_NAME}@${targetVersion}...`);
         return {
             packageDir,
             cleanup: async () => undefined,
@@ -259,12 +288,14 @@ async function prepareLocalSkillsPackage(globalRoot, options = {}, targetVersion
     await fsp.rm(packRoot, { recursive: true, force: true });
     await fsp.mkdir(packRoot, { recursive: true });
     try {
-        await (options.runFn ?? run)('npm', ['pack', '--silent', packageSpec], {
+        options.onProgress?.(`Downloading ${packageSpec}...`);
+        await (options.runFn ?? run)('npm', ['pack', ...(options.verbose ? [] : ['--silent']), packageSpec], {
             cwd: packRoot,
             stdio: options.verbose ? 'inherit' : 'ignore',
             errorName: 'npm pack',
             timeoutMs: SKILLS_PACK_TIMEOUT_MS,
         });
+        options.onProgress?.(`Extracting ${NOCOBASE_SKILLS_PACKAGE_NAME}...`);
         const tarballPath = await resolvePackedSkillsTarball(packRoot);
         await extractPackedSkillsTarball(tarballPath, cacheRoot, targetVersion);
     }
@@ -279,14 +310,16 @@ async function prepareLocalSkillsPackage(globalRoot, options = {}, targetVersion
 export async function inspectSkillsStatus(options = {}) {
     const globalRoot = resolveSkillsRoot(options);
     const stateFile = getManagedSkillsStateFile(globalRoot);
-    const [installedSkills, managedState] = await Promise.all([
+    const [installedSkills, managedState, cachedSkillNames] = await Promise.all([
         listGlobalSkills({
             globalRoot,
             commandOutputFn: options.commandOutputFn,
         }),
         readManagedSkillsState(globalRoot),
+        readCachedPackageSkillNames(globalRoot),
     ]);
-    const installedSkillNames = pickInstalledNocoBaseSkillNames(installedSkills, managedState);
+    const installedSkillNames = pickInstalledNocoBaseSkillNames(installedSkills, managedState, cachedSkillNames);
+    const packageSkillNames = cachedSkillNames;
     const managedByNb = managedState?.packageName === NOCOBASE_SKILLS_PACKAGE_NAME;
     let latestVersion;
     let registryError;
@@ -312,6 +345,7 @@ export async function inspectSkillsStatus(options = {}) {
         managedByNb,
         sourcePackage: managedState?.sourcePackage ?? NOCOBASE_SKILLS_SOURCE,
         npmPackageName: managedState?.packageName ?? NOCOBASE_SKILLS_PACKAGE_NAME,
+        packageSkillNames,
         installedSkillNames,
         latestVersion,
         installedVersion,
@@ -321,13 +355,18 @@ export async function inspectSkillsStatus(options = {}) {
         registryError,
     };
 }
-async function persistManagedSkillsState(globalRoot, options = {}) {
-    const installedSkills = await listGlobalSkills({
-        globalRoot,
-        commandOutputFn: options.commandOutputFn,
-    });
-    const managedState = await readManagedSkillsState(globalRoot);
-    const installedSkillNames = pickInstalledNocoBaseSkillNames(installedSkills, managedState);
+async function persistManagedSkillsState(globalRoot, options = {}, installedVersion) {
+    const [installedSkills, managedState, cachedSkillNames] = await Promise.all([
+        listGlobalSkills({
+            globalRoot,
+            commandOutputFn: options.commandOutputFn,
+        }),
+        readManagedSkillsState(globalRoot),
+        readCachedPackageSkillNames(globalRoot),
+    ]);
+    const installedSkillNames = pickInstalledNocoBaseSkillNames(installedSkills, managedState, cachedSkillNames);
+    const packageSkillNames = cachedSkillNames.length ? cachedSkillNames : installedSkillNames;
+    const cachedVersion = await readCachedSkillsVersion(getSkillsCacheRoot(globalRoot));
     const published = await readPublishedSkillsVersion({
         globalRoot,
         commandOutputFn: options.commandOutputFn,
@@ -338,8 +377,8 @@ async function persistManagedSkillsState(globalRoot, options = {}) {
         sourcePackage: NOCOBASE_SKILLS_SOURCE,
         installedAt: managedState?.installedAt ?? now,
         updatedAt: now,
-        installedVersion: published.version,
-        skillNames: installedSkillNames,
+        installedVersion: installedVersion ?? cachedVersion ?? published.version,
+        skillNames: packageSkillNames,
     });
     return await inspectSkillsStatus({
         globalRoot,
@@ -349,7 +388,8 @@ async function persistManagedSkillsState(globalRoot, options = {}) {
 async function reinstallManagedSkills(globalRoot, options = {}, targetVersion) {
     const prepared = await prepareLocalSkillsPackage(globalRoot, options, targetVersion);
     try {
-        await (options.runFn ?? run)('npx', ['-y', 'skills', 'add', prepared.packageDir, '-g', '-y'], {
+        options.onProgress?.('Installing NocoBase AI coding skills globally...');
+        await (options.runFn ?? run)('npx', ['-y', 'skills', 'add', prepared.packageDir, '-g', '-y', '--skill', '*'], {
             cwd: globalRoot,
             stdio: options.verbose ? 'inherit' : 'ignore',
             errorName: 'skills add',
@@ -360,31 +400,66 @@ async function reinstallManagedSkills(globalRoot, options = {}, targetVersion) {
         await prepared.cleanup();
     }
 }
+function pickObsoleteManagedSkillNames(installedSkillNames, packageSkillNames) {
+    if (!packageSkillNames.length) {
+        return [];
+    }
+    const packageSkillNameSet = new Set(packageSkillNames);
+    return installedSkillNames.filter((skillName) => !packageSkillNameSet.has(skillName)).sort();
+}
+async function removeObsoleteManagedSkills(globalRoot, installedSkillNames, options = {}) {
+    const packageSkillNames = await readCachedPackageSkillNames(globalRoot);
+    const obsoleteSkillNames = pickObsoleteManagedSkillNames(installedSkillNames, packageSkillNames);
+    for (const skillName of obsoleteSkillNames) {
+        options.onProgress?.(`Removing obsolete skill ${skillName}...`);
+        await (options.runFn ?? run)('npx', ['-y', 'skills', 'remove', skillName, '-g', '-y'], {
+            cwd: globalRoot,
+            stdio: options.verbose ? 'inherit' : 'ignore',
+            errorName: 'skills remove',
+        });
+    }
+}
 export async function installNocoBaseSkills(options = {}) {
     const globalRoot = resolveSkillsRoot(options);
+    options.onProgress?.('Checking installed NocoBase AI coding skills...');
     const status = await inspectSkillsStatus({
         globalRoot,
         commandOutputFn: options.commandOutputFn,
     });
-    if (status.installed) {
+    const cachedSkillNames = await readCachedPackageSkillNames(globalRoot);
+    const missingCachedSkillNames = cachedSkillNames.filter((name) => !status.installedSkillNames.includes(name));
+    const obsoleteSkillNames = pickObsoleteManagedSkillNames(status.installedSkillNames, cachedSkillNames);
+    const targetVersion = String(options.targetVersion ?? '').trim() || undefined;
+    const targetVersionMatches = !targetVersion || status.installedVersion === targetVersion;
+    if (status.installed && targetVersionMatches && missingCachedSkillNames.length === 0 && obsoleteSkillNames.length === 0) {
         return {
             action: 'noop',
             status,
         };
     }
     await ensureSkillsWorkspaceRoot(globalRoot);
-    await reinstallManagedSkills(globalRoot, options, status.latestVersion);
+    if (!status.installed || !targetVersionMatches || missingCachedSkillNames.length > 0) {
+        const installVersion = targetVersion ?? status.latestVersion;
+        await reinstallManagedSkills(globalRoot, options, installVersion);
+    }
+    await removeObsoleteManagedSkills(globalRoot, status.installedSkillNames, options);
+    options.onProgress?.('Verifying installed NocoBase AI coding skills...');
     return {
         action: 'installed',
-        status: await persistManagedSkillsState(globalRoot, options),
+        status: await persistManagedSkillsState(globalRoot, options, targetVersion),
     };
 }
 export async function updateNocoBaseSkills(options = {}) {
     const globalRoot = resolveSkillsRoot(options);
+    options.onProgress?.('Checking installed NocoBase AI coding skills...');
     const status = await inspectSkillsStatus({
         globalRoot,
         commandOutputFn: options.commandOutputFn,
     });
+    const cachedSkillNames = await readCachedPackageSkillNames(globalRoot);
+    const missingCachedSkillNames = cachedSkillNames.filter((name) => !status.installedSkillNames.includes(name));
+    const obsoleteSkillNames = pickObsoleteManagedSkillNames(status.installedSkillNames, cachedSkillNames);
+    const targetVersion = String(options.targetVersion ?? '').trim() || undefined;
     if (!status.installed) {
         return {
             action: 'noop',
@@ -393,8 +468,11 @@ export async function updateNocoBaseSkills(options = {}) {
         };
     }
     if (status.managedByNb &&
+        !targetVersion &&
         status.latestVersion &&
         status.installedVersion &&
+        missingCachedSkillNames.length === 0 &&
+        obsoleteSkillNames.length === 0 &&
         compareVersions(status.latestVersion, status.installedVersion) <= 0) {
         return {
             action: 'noop',
@@ -402,10 +480,25 @@ export async function updateNocoBaseSkills(options = {}) {
             status,
         };
     }
-    await reinstallManagedSkills(globalRoot, options, status.latestVersion);
+    if (targetVersion &&
+        status.installedVersion === targetVersion &&
+        missingCachedSkillNames.length === 0 &&
+        obsoleteSkillNames.length === 0) {
+        return {
+            action: 'noop',
+            reason: 'up-to-date',
+            status,
+        };
+    }
+    if (!targetVersion || status.installedVersion !== targetVersion || missingCachedSkillNames.length > 0) {
+        const installVersion = targetVersion ?? status.latestVersion;
+        await reinstallManagedSkills(globalRoot, options, installVersion);
+    }
+    await removeObsoleteManagedSkills(globalRoot, status.installedSkillNames, options);
+    options.onProgress?.('Verifying installed NocoBase AI coding skills...');
     return {
         action: 'updated',
-        status: await persistManagedSkillsState(globalRoot, options),
+        status: await persistManagedSkillsState(globalRoot, options, targetVersion),
     };
 }
 export async function removeNocoBaseSkills(options = {}) {