@openprd/cli 0.1.9 → 0.1.11

package/src/self-update.js

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { readWorkspaceRegistry } from './workspace-registry.js';
 
 export const DEFAULT_SELF_UPDATE_SOURCE = '@openprd/cli@latest';
 
@@ -20,6 +21,139 @@ export function formatCommand(command, args = []) {
   return [command, ...args].map(shellQuote).join(' ');
 }
 
+function normalizeVersionText(value) {
+  const raw = String(value ?? '').trim();
+  if (!raw) {
+    return null;
+  }
+  return raw.startsWith('v') ? raw.slice(1) : raw;
+}
+
+function parseSemverParts(value) {
+  const normalized = normalizeVersionText(value);
+  const match = normalized?.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$/u);
+  if (!match) {
+    return null;
+  }
+  return {
+    major: Number.parseInt(match[1], 10),
+    minor: Number.parseInt(match[2], 10),
+    patch: Number.parseInt(match[3], 10),
+    prerelease: match[4] ?? null,
+    build: match[5] ?? null,
+  };
+}
+
+function comparePrereleaseIdentifiers(left, right) {
+  const leftParts = String(left ?? '').split('.');
+  const rightParts = String(right ?? '').split('.');
+  const max = Math.max(leftParts.length, rightParts.length);
+  for (let index = 0; index < max; index += 1) {
+    const leftPart = leftParts[index];
+    const rightPart = rightParts[index];
+    if (leftPart === undefined) {
+      return -1;
+    }
+    if (rightPart === undefined) {
+      return 1;
+    }
+    const leftNumeric = /^\d+$/u.test(leftPart);
+    const rightNumeric = /^\d+$/u.test(rightPart);
+    if (leftNumeric && rightNumeric) {
+      const diff = Number.parseInt(leftPart, 10) - Number.parseInt(rightPart, 10);
+      if (diff !== 0) {
+        return diff > 0 ? 1 : -1;
+      }
+      continue;
+    }
+    if (leftNumeric !== rightNumeric) {
+      return leftNumeric ? -1 : 1;
+    }
+    const diff = leftPart.localeCompare(rightPart);
+    if (diff !== 0) {
+      return diff > 0 ? 1 : -1;
+    }
+  }
+  return 0;
+}
+
+export function compareVersions(left, right) {
+  const leftParts = parseSemverParts(left);
+  const rightParts = parseSemverParts(right);
+  if (!leftParts || !rightParts) {
+    return null;
+  }
+  for (const field of ['major', 'minor', 'patch']) {
+    if (leftParts[field] !== rightParts[field]) {
+      return leftParts[field] > rightParts[field] ? 1 : -1;
+    }
+  }
+  if (!leftParts.prerelease && !rightParts.prerelease) {
+    return 0;
+  }
+  if (!leftParts.prerelease) {
+    return 1;
+  }
+  if (!rightParts.prerelease) {
+    return -1;
+  }
+  return comparePrereleaseIdentifiers(leftParts.prerelease, rightParts.prerelease);
+}
+
+function packageNameFromSource(source, fallback = '@openprd/cli') {
+  const text = String(source ?? '').trim();
+  if (!text) {
+    return fallback;
+  }
+  const scopedMatch = text.match(/^(@[^/]+\/[^@]+)(?:@.+)?$/u);
+  if (scopedMatch) {
+    return scopedMatch[1];
+  }
+  const unscopedMatch = text.match(/^([^@]+)(?:@.+)?$/u);
+  return unscopedMatch?.[1] ?? fallback;
+}
+
+function parseVersionOutput(text) {
+  const raw = String(text ?? '').trim();
+  if (!raw) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === 'string') {
+      return normalizeVersionText(parsed);
+    }
+    if (Array.isArray(parsed)) {
+      const first = parsed.find((item) => typeof item === 'string' && item.trim());
+      return first ? normalizeVersionText(first) : null;
+    }
+  } catch {
+    // Fall back to plain text parsing.
+  }
+  const firstLine = raw.split(/\r?\n/u).map((line) => line.trim()).find(Boolean);
+  return firstLine ? normalizeVersionText(firstLine) : null;
+}
+
+function versionComparisonLabel(currentVersion, targetVersion) {
+  const comparison = compareVersions(currentVersion, targetVersion);
+  if (comparison === null) {
+    return 'unknown';
+  }
+  if (comparison < 0) {
+    return 'behind';
+  }
+  if (comparison > 0) {
+    return 'ahead';
+  }
+  return 'same';
+}
+
+function refreshCandidateNote(workspaceRoot) {
+  return /(^|\/)(archive|archives|归档)(\/|$)/iu.test(String(workspaceRoot ?? ''))
+    ? '归档项目，建议先确认'
+    : '可直接处理';
+}
+
 async function readPackageInfo(packageRoot = DEFAULT_PACKAGE_ROOT) {
   const packageJsonPath = path.join(packageRoot, 'package.json');
   const raw = await fs.readFile(packageJsonPath, 'utf8');
@@ -101,6 +235,109 @@ async function resolveOpenPrdExecutable(deps = {}) {
   };
 }
 
+async function inspectPublishedVersion(packageInfo, options = {}, deps = {}) {
+  const runCommand = deps.runCommand ?? runProcess;
+  const packageName = packageInfo.name ?? packageNameFromSource(options.source ?? DEFAULT_SELF_UPDATE_SOURCE);
+  const command = 'npm';
+  const args = ['view', packageName, 'version', '--json'];
+  const result = await runCommand(command, args, {
+    cwd: options.cwd ?? packageInfo.packageRoot ?? process.cwd(),
+    env: options.env ?? process.env,
+  });
+  const publishedVersion = result.ok ? parseVersionOutput(result.stdout) : null;
+  const errors = [];
+  if (!result.ok) {
+    errors.push(result.stderr.trim() || `npm view failed with exit code ${result.exitCode}.`);
+  } else if (!publishedVersion) {
+    errors.push('Unable to parse the published npm version for @openprd/cli.');
+  }
+  const comparison = versionComparisonLabel(packageInfo.version, publishedVersion);
+  return {
+    ok: errors.length === 0,
+    packageName,
+    currentVersion: normalizeVersionText(packageInfo.version),
+    publishedVersion,
+    updateAvailable: comparison === 'behind',
+    comparison,
+    command: {
+      command,
+      args,
+      display: formatCommand(command, args),
+    },
+    result,
+    errors,
+  };
+}
+
+async function resolveExecutableVersion(executable, options = {}, deps = {}) {
+  const runCommand = deps.runCommand ?? runProcess;
+  const result = await runCommand(executable, ['--version'], {
+    cwd: options.cwd ?? process.cwd(),
+    env: options.env ?? process.env,
+  });
+  const version = result.ok ? parseVersionOutput(result.stdout || result.stderr) : null;
+  const errors = [];
+  if (!result.ok) {
+    errors.push(result.stderr.trim() || `Version check failed with exit code ${result.exitCode}.`);
+  } else if (!version) {
+    errors.push('Unable to parse the installed OpenPrd version after update.');
+  }
+  return {
+    ok: errors.length === 0,
+    executable,
+    version,
+    command: {
+      command: executable,
+      args: ['--version'],
+      display: formatCommand(executable, ['--version']),
+    },
+    result,
+    errors,
+  };
+}
+
+async function collectRefreshCandidates(targetVersion, options = {}, deps = {}) {
+  const normalizedTargetVersion = normalizeVersionText(targetVersion);
+  if (!normalizedTargetVersion) {
+    return {
+      ok: true,
+      targetVersion: null,
+      registryPath: null,
+      staleCount: 0,
+      total: 0,
+      projects: [],
+    };
+  }
+  const registry = await (deps.readWorkspaceRegistry ?? readWorkspaceRegistry)({
+    openprdHome: options.openprdHome,
+  });
+  const projects = registry.entries
+    .filter((entry) => {
+      if (!entry.openprdVersion) {
+        return false;
+      }
+      return compareVersions(entry.openprdVersion, normalizedTargetVersion) === -1;
+    })
+    .map((entry) => ({
+      workspaceRoot: entry.workspaceRoot,
+      workspaceName: entry.workspaceName ?? path.basename(entry.workspaceRoot),
+      currentVersion: normalizeVersionText(entry.openprdVersion),
+      targetVersion: normalizedTargetVersion,
+      suggestedAction: '刷新 OpenPrD',
+      note: refreshCandidateNote(entry.workspaceRoot),
+    }))
+    .sort((left, right) => left.workspaceRoot.localeCompare(right.workspaceRoot));
+
+  return {
+    ok: true,
+    targetVersion: normalizedTargetVersion,
+    registryPath: registry.registryPath,
+    staleCount: registry.staleEntries.length,
+    total: projects.length,
+    projects,
+  };
+}
+
 function buildSelfUpdatePlan(options = {}) {
   const source = options.source ?? DEFAULT_SELF_UPDATE_SOURCE;
   const command = options.packageManager ?? 'npm';
@@ -164,9 +401,41 @@ export function createSelfUpdateWorkspace(deps = {}) {
   const runCommand = deps.runCommand ?? runProcess;
   const packageRoot = deps.packageRoot ?? DEFAULT_PACKAGE_ROOT;
 
+  async function checkSelfUpdateWorkspace(options = {}) {
+    const packageInfo = await (deps.readPackageInfo ?? readPackageInfo)(packageRoot);
+    const versionCheck = await inspectPublishedVersion(packageInfo, options, {
+      ...deps,
+      runCommand,
+    });
+    const refreshTargetVersion = versionCheck.updateAvailable
+      ? versionCheck.publishedVersion
+      : packageInfo.version;
+    const refreshCandidates = await collectRefreshCandidates(refreshTargetVersion, options, deps);
+    return {
+      ok: versionCheck.ok,
+      action: 'self-update-check',
+      checkOnly: true,
+      source: 'npm-published-version',
+      package: packageInfo,
+      currentVersion: normalizeVersionText(packageInfo.version),
+      publishedVersion: versionCheck.publishedVersion,
+      updateAvailable: versionCheck.updateAvailable,
+      comparison: versionCheck.comparison,
+      versionCheck,
+      refreshCandidates,
+      errors: [...versionCheck.errors],
+      nextActions: versionCheck.updateAvailable
+        ? ['Run `openprd self-update` to install the published CLI version.']
+        : [],
+    };
+  }
+
   async function selfUpdateWorkspace(options = {}) {
     const packageInfo = await (deps.readPackageInfo ?? readPackageInfo)(packageRoot);
     const localCheckout = await (deps.isLocalSourceCheckout ?? isLocalSourceCheckout)(packageRoot);
+    if (options.check) {
+      return checkSelfUpdateWorkspace(options);
+    }
     const plan = buildSelfUpdatePlan(options);
     const base = {
       ok: true,
@@ -178,6 +447,15 @@ export function createSelfUpdateWorkspace(deps = {}) {
       installCommand: plan.install,
       result: null,
       resolvedExecutable: null,
+      installedVersion: null,
+      refreshCandidates: {
+        ok: true,
+        targetVersion: null,
+        registryPath: null,
+        staleCount: 0,
+        total: 0,
+        projects: [],
+      },
       errors: [],
       nextActions: [],
     };
@@ -213,19 +491,36 @@ export function createSelfUpdateWorkspace(deps = {}) {
     const resolvedExecutable = installResult.ok
       ? await resolveOpenPrdExecutable(deps)
       : null;
+    const installedVersion = installResult.ok && resolvedExecutable?.ok
+      ? await resolveExecutableVersion(resolvedExecutable.executable, options, {
+        ...deps,
+        runCommand,
+      })
+      : null;
+    const refreshCandidates = installedVersion?.ok
+      ? await collectRefreshCandidates(installedVersion.version, options, deps)
+      : base.refreshCandidates;
 
     return {
       ...base,
-      ok: installResult.ok && (resolvedExecutable?.ok ?? false),
+      ok: installResult.ok && (resolvedExecutable?.ok ?? false) && (installedVersion?.ok ?? false),
       result: installResult,
       resolvedExecutable,
+      installedVersion,
+      refreshCandidates,
       errors: [
         ...(installResult.ok ? [] : [installResult.stderr.trim() || `Self-update command failed with exit code ${installResult.exitCode}.`]),
         ...(installResult.ok && !resolvedExecutable?.ok ? [resolvedExecutable?.error ?? 'Unable to resolve updated openprd executable.'] : []),
+        ...(installedVersion?.errors ?? []),
+      ],
+      nextActions: [
+        ...(installResult.ok && !resolvedExecutable?.ok
+          ? ['Check that the global npm bin directory is on PATH, then run openprd update <project>.']
+          : []),
+        ...((refreshCandidates?.total ?? 0) > 0
+          ? ['If you want to refresh older workspaces too, review the refreshCandidates list before running fleet or per-project updates.']
+          : []),
       ],
-      nextActions: installResult.ok && !resolvedExecutable?.ok
-        ? ['Check that the global npm bin directory is on PATH, then run openprd update <project>.']
-        : [],
     };
   }
 
@@ -318,6 +613,7 @@ export function createSelfUpdateWorkspace(deps = {}) {
   }
 
   return {
+    checkSelfUpdateWorkspace,
     selfUpdateWorkspace,
     upgradeWorkspace,
   };
@@ -325,5 +621,6 @@ export function createSelfUpdateWorkspace(deps = {}) {
 
 const defaultWorkspace = createSelfUpdateWorkspace();
 
+export const checkSelfUpdateWorkspace = defaultWorkspace.checkSelfUpdateWorkspace;
 export const selfUpdateWorkspace = defaultWorkspace.selfUpdateWorkspace;
 export const upgradeWorkspace = defaultWorkspace.upgradeWorkspace;

package/src/standards.js

@@ -370,9 +370,36 @@ function validateTextSections(relativePath, text, sections, errors) {
   }
 }
 
-function sourceManualReadmeName(projectRoot, dirPath) {
-  const moduleName = path.basename(projectRoot).replace(/[^a-zA-Z0-9_-]+/g, '-');
-  const folderName = path.basename(dirPath).replace(/[^a-zA-Z0-9_-]+/g, '-');
+function normalizeModuleName(raw, fallback = 'project') {
+  const candidate = String(raw ?? '').trim().split('/').filter(Boolean).pop() ?? '';
+  const normalized = candidate.replace(/[^a-zA-Z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
+  return normalized || fallback;
+}
+
+async function resolveSourceManualModuleName(projectRoot, config = {}, fallbackModuleName = '') {
+  const configuredName = typeof config?.folderManual?.moduleName === 'string'
+    ? config.folderManual.moduleName.trim()
+    : '';
+  if (configuredName) {
+    return normalizeModuleName(configuredName, normalizeModuleName(path.basename(projectRoot)));
+  }
+
+  const packageJson = await readJson(cjoin(projectRoot, 'package.json')).catch(() => null);
+  const packageName = typeof packageJson?.name === 'string' ? packageJson.name.trim() : '';
+  if (packageName) {
+    return normalizeModuleName(packageName, normalizeModuleName(path.basename(projectRoot)));
+  }
+
+  const fallbackName = typeof fallbackModuleName === 'string' ? fallbackModuleName.trim() : '';
+  if (fallbackName) {
+    return normalizeModuleName(fallbackName, normalizeModuleName(path.basename(projectRoot)));
+  }
+
+  return normalizeModuleName(path.basename(projectRoot));
+}
+
+function sourceManualReadmeName(moduleName, dirPath) {
+  const folderName = path.basename(dirPath).replace(/[^a-zA-Z0-9_-]+/g, '-') || moduleName;
   return `${moduleName}_${folderName}_README.md`;
 }
 
@@ -602,6 +629,11 @@ async function validateSourceManuals(projectRoot, errors, checks, options = {})
   const sourceFiles = await collectSourceFiles(projectRoot, projectRoot, [], options.ignorePatterns, discovery);
   const filesMissingManualRaw = [];
   const foldersMissingManualRaw = [];
+  const moduleName = await resolveSourceManualModuleName(
+    projectRoot,
+    options.config ?? {},
+    options.folderManualModuleName,
+  );
 
   for (const filePath of sourceFiles) {
     const relativePath = path.relative(projectRoot, filePath);
@@ -613,7 +645,8 @@ async function validateSourceManuals(projectRoot, errors, checks, options = {})
 
   const sourceDirsRaw = new Set(sourceFiles.map((filePath) => path.dirname(filePath)));
   for (const dirPath of sourceDirsRaw) {
-    const expectedPath = cjoin(dirPath, sourceManualReadmeName(projectRoot, dirPath));
+    const folderLabel = dirPath === projectRoot ? moduleName : null;
+    const expectedPath = cjoin(dirPath, sourceManualReadmeName(moduleName, folderLabel ?? dirPath));
     const relativePath = path.relative(projectRoot, expectedPath);
     const text = await readText(expectedPath).catch(() => null);
     if (!text || !hasAllManualSections(text)) {
@@ -785,6 +818,9 @@ export async function checkStandardsWorkspace(projectRoot, options = {}) {
     if (config.docsRoot !== 'docs/basic') {
       errors.push(`${OPENPRD_STANDARDS_CONFIG} docsRoot must be docs/basic.`);
     }
+    if (config?.folderManual?.moduleName != null && (typeof config.folderManual.moduleName !== 'string' || !config.folderManual.moduleName.trim())) {
+      errors.push(`${OPENPRD_STANDARDS_CONFIG} folderManual.moduleName must be a non-empty string when provided.`);
+    }
     validateDevelopmentStandardsConfig(config, errors);
     validateGrowthConfig(config, errors);
     for (const externalPath of normalizeStringList(config?.externalReferences?.paths)) {
@@ -847,7 +883,12 @@ export async function checkStandardsWorkspace(projectRoot, options = {}) {
     && config?.fileManual?.enabled !== false
     && config?.folderManual?.enabled !== false;
   const manualReport = enforceSourceManuals
-    ? await validateSourceManuals(projectRoot, errors, checks, { ignorePatterns, externalReferencePaths })
+    ? await validateSourceManuals(projectRoot, errors, checks, {
+      ignorePatterns,
+      externalReferencePaths,
+      config,
+      folderManualModuleName: options.folderManualModuleName,
+    })
     : {
       ignorePatterns,
       externalReferencePaths,