pumuki 6.3.110 → 6.3.111

package/CHANGELOG.md

@@ -6,12 +6,12 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-## [6.3.110] - 2026-04-23
+## [6.3.111] - 2026-04-23
 
 ### Fixed
 
-- **`status` expone `issues` canónicos cuando el runtime está bloqueado:** la salida JSON ya no obliga a combinar `governanceEffective`, `attention_codes` y `human_summary_preview` para entender un bloqueo real.
-- **Contrato alineado en `main` y `develop`:** la lista de issues consumible queda fijada en ambas líneas para los consumers que leen `status` como fuente principal de diagnóstico.
+- **Alignment commands now respect the consumer runtime declaration:** `status`, `doctor` and the lifecycle helpers prepend the matching Node runtime switch when the consumer declares `volta`, `.nvmrc`, or `package.json.engines.node` and the current shell Node does not match.
+- **Reproducible remediation stays repo-aware:** the suggested command keeps the consumer's runtime manager in the loop before the Pumuki install/alignment step, so fixes stay tied to the repo that is being audited.
 
 ## [6.3.102] - 2026-04-22
 

package/docs/operations/RELEASE_NOTES.md

@@ -6,11 +6,10 @@ This file keeps only the operational highlights and rollout notes that matter wh
 
 ## 2026-04 (CLI stability and macOS notifications)
 
-### 2026-04-23 (v6.3.110)
+### 2026-04-23 (v6.3.111)
 
-- **Salida canónica de bloqueos en `status`:** el payload añade `issues` cuando el runtime está bloqueado, evitando que el consumo automatizado tenga que recomponer el fallo a partir de varias señales.
-- **Contrato alineado entre ramas:** el mismo criterio queda disponible en `develop` y `main`, por lo que el rollout no depende de interpretar superficies distintas.
-- **Rollout recomendado:** publicar `pumuki@6.3.110`, repin inmediato en `RuralGo` y revalidar `status` / `doctor` para cerrar `PUMUKI-INC-084`.
+- **Runtime-aware remediation:** `alignmentCommand` now respects the consumer's declared Node runtime when the shell Node does not match, using `volta`, `.nvmrc`, or `package.json.engines.node` as the source of truth.
+- **Rollout recommended:** publish `pumuki@6.3.111`, repin the active consumer, and revalidate `status` / `doctor` to confirm the consumer runtime is aligned before following the remediation command.
 
 ### 2026-04-22 (v6.3.102)
 

package/docs/product/API_REFERENCE.md

@@ -174,7 +174,7 @@ Interpretation contract:
 - `consumerInstalled`: version installed in the consumer repository.
 - `lifecycleInstalled`: version recorded in managed lifecycle metadata.
 - `driftWarning`: compact human-readable explanation when those values diverge.
-- `alignmentCommand`: exact remediation command to align dependency and lifecycle state with the current runtime version.
+- `alignmentCommand`: exact remediation command to align dependency and lifecycle state with the current runtime version. When the consumer repo declares a Node runtime via `volta`, `.nvmrc`, or `package.json.engines.node`, this command prepends the matching runtime switch before the Pumuki install step.
 - `pathExecutionHazard`: boolean flag raised when the repo root contains the platform `PATH` delimiter and `npx/npm exec` can fail to resolve `pumuki`.
 - `pathExecutionWarning`: compact warning explaining why `PATH` resolution is unsafe in that repo.
 - `pathExecutionWorkaroundCommand`: safe local-node entrypoint to use when `pathExecutionHazard=true`.

package/docs/product/USAGE.md

@@ -403,7 +403,7 @@ How to read it:
 - `lifecycleInstalled`: version persisted in managed lifecycle state.
 - `source`: source chosen to compute `effective`.
 - `driftWarning`: compact explanation when those values diverge.
-- `alignmentCommand`: exact command to align consumer dependency and lifecycle state with the current runtime.
+- `alignmentCommand`: exact command to align consumer dependency and lifecycle state with the current runtime. If the consumer declares Node via `volta`, `.nvmrc`, or `package.json.engines.node`, the command prepends the matching runtime switch before the Pumuki install step.
 - `pathExecutionHazard`: tells you whether the repo root itself can break `PATH`-based execution.
 - `pathExecutionWarning`: compact explanation of that hazard.
 - `pathExecutionWorkaroundCommand`: safe local-node entrypoint to use when `PATH` execution is unsafe.

package/integrations/lifecycle/packageInfo.ts

@@ -49,15 +49,126 @@ const hasPathExecutionHazard = (repoRoot?: string): boolean =>
   repoRoot.trim().length > 0 &&
   repoRoot.includes(delimiter);
 
+type ConsumerNodeRuntimeSpec = {
+  version: string;
+  source: 'volta' | '.nvmrc' | 'package.engines';
+  commandPrefix: 'volta' | 'nvm';
+};
+
+const normalizeNodeVersionToken = (value: string): string =>
+  value.trim().replace(/^node@/i, '').replace(/^v/i, '');
+
+const extractNodeVersionToken = (value: string): string | null => {
+  const normalized = normalizeNodeVersionToken(value);
+  const exactVersion = normalized.match(/\d+\.\d+\.\d+/)?.[0];
+  if (exactVersion) {
+    return exactVersion;
+  }
+  const majorOnly = normalized.match(/^\d+$/)?.[0];
+  return majorOnly ?? null;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const readNestedString = (
+  source: Record<string, unknown>,
+  path: ReadonlyArray<string>
+): string | undefined => {
+  let cursor: unknown = source;
+  for (const segment of path) {
+    if (!isRecord(cursor)) {
+      return undefined;
+    }
+    cursor = cursor[segment];
+  }
+  return typeof cursor === 'string' && cursor.trim().length > 0 ? cursor.trim() : undefined;
+};
+
+const readConsumerNodeRuntimeSpec = (repoRoot?: string): ConsumerNodeRuntimeSpec | null => {
+  if (typeof repoRoot !== 'string' || repoRoot.trim().length === 0) {
+    return null;
+  }
+
+  const packageJsonPath = join(repoRoot, 'package.json');
+  if (existsSync(packageJsonPath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as unknown;
+      if (isRecord(parsed)) {
+        const voltaNode = readNestedString(parsed, ['volta', 'node']);
+        const voltaVersion = voltaNode ? extractNodeVersionToken(voltaNode) : null;
+        if (voltaVersion) {
+          return {
+            version: voltaVersion,
+            source: 'volta',
+            commandPrefix: 'volta',
+          };
+        }
+
+        const enginesNode = readNestedString(parsed, ['engines', 'node']);
+        const enginesVersion = enginesNode ? extractNodeVersionToken(enginesNode) : null;
+        if (enginesVersion) {
+          return {
+            version: enginesVersion,
+            source: 'package.engines',
+            commandPrefix: 'nvm',
+          };
+        }
+      }
+    } catch {
+      return null;
+    }
+  }
+
+  const nvmrcPath = join(repoRoot, '.nvmrc');
+  if (existsSync(nvmrcPath)) {
+    try {
+      const nvmrcVersion = extractNodeVersionToken(readFileSync(nvmrcPath, 'utf8'));
+      if (nvmrcVersion) {
+        return {
+          version: nvmrcVersion,
+          source: '.nvmrc',
+          commandPrefix: 'nvm',
+        };
+      }
+    } catch {
+      return null;
+    }
+  }
+
+  return null;
+};
+
+const buildConsumerNodeAlignmentCommand = (repoRoot?: string): string | null => {
+  const runtimeSpec = readConsumerNodeRuntimeSpec(repoRoot);
+  if (!runtimeSpec) {
+    return null;
+  }
+
+  const currentNodeVersion = normalizeNodeVersionToken(process.version);
+  if (currentNodeVersion === runtimeSpec.version) {
+    return null;
+  }
+
+  if (runtimeSpec.commandPrefix === 'volta') {
+    return `volta install node@${runtimeSpec.version} && volta pin node@${runtimeSpec.version}`;
+  }
+
+  return `nvm install ${runtimeSpec.version} && nvm use ${runtimeSpec.version}`;
+};
+
 export const buildLifecycleAlignmentCommand = (
   runtimeVersion: string,
   repoRoot?: string
 ): string => {
+  const consumerNodeAlignmentCommand = buildConsumerNodeAlignmentCommand(repoRoot);
   const installStep = `npm install --save-exact pumuki@${runtimeVersion}`;
   const runStep = hasPathExecutionHazard(repoRoot)
     ? `${buildLocalPumukiCommand()} install`
     : `npx --yes --package pumuki@${runtimeVersion} pumuki install`;
-  return `${installStep} && ${runStep}`;
+  return [consumerNodeAlignmentCommand, installStep, runStep]
+    .filter((value): value is string => typeof value === 'string' && value.length > 0)
+    .join(' && ');
 };
 
 export const resolvePumukiVersionMetadata = (params?: { repoRoot?: string }): PumukiVersionMetadata => {
@@ -114,11 +225,17 @@ export const buildLifecycleVersionReport = (params?: {
   const driftFromConsumerInstalled =
     metadata.consumerInstalledVersion !== null &&
     metadata.consumerInstalledVersion !== metadata.runtimeVersion;
+  const consumerNodeSpec = readConsumerNodeRuntimeSpec(params?.repoRoot);
+  const consumerNodeVersion = consumerNodeSpec?.version ?? null;
+  const currentNodeVersion = normalizeNodeVersionToken(process.version);
+  const driftFromConsumerNode =
+    consumerNodeVersion !== null && currentNodeVersion !== consumerNodeVersion;
   const driftFromLifecycleInstalled =
     lifecycleInstalled !== null && metadata.resolvedVersion !== lifecycleInstalled;
   const driftTargets = [
     driftFromRuntime ? `runtime=${metadata.runtimeVersion}` : null,
     driftFromConsumerInstalled ? `consumer=${metadata.consumerInstalledVersion}` : null,
+    driftFromConsumerNode ? `node=${consumerNodeVersion}` : null,
     driftFromLifecycleInstalled ? `lifecycle=${lifecycleInstalled}` : null,
   ].filter((value): value is string => value !== null);
   const pathExecutionHazard = hasPathExecutionHazard(params?.repoRoot);

package/integrations/lifecycle/watch.ts

@@ -736,7 +736,7 @@ export const runLifecycleWatch = async (
           driftFromRuntime,
           driftWarning,
           alignmentCommand: driftFromRuntime
-            ? buildLifecycleAlignmentCommand(versionMetadata.runtimeVersion)
+            ? buildLifecycleAlignmentCommand(versionMetadata.runtimeVersion, repoRoot)
             : null,
         },
         stage,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki",
-  "version": "6.3.110",
+  "version": "6.3.111",
   "description": "Enterprise-grade AST Intelligence System with multi-platform support (iOS, Android, Backend, Frontend) and Feature-First + DDD + Clean Architecture enforcement. Includes dynamic violations API for intelligent querying.",
   "main": "index.js",
   "bin": {