pumuki 6.3.62 → 6.3.64

package/README.md

@@ -37,6 +37,8 @@ npx --yes pumuki status
 npx --yes pumuki doctor --json
 ```
 
+Desde **6.3.63**, `npm install` en la raíz de un repo **Git** dispara un `postinstall` que ejecuta `pumuki install` automáticamente (hooks `pre-commit` / `pre-push`). No configura MCP del IDE por sí solo: usa `pumuki install --with-mcp` o el adaptador. Desactivar el postinstall: `PUMUKI_SKIP_POSTINSTALL=1`. En CI suele saltarse solo (`CI=true`). En **6.3.64+**, las notificaciones del sistema en plataformas sin banner nativo se reflejan en **stderr** por defecto (`PUMUKI_DISABLE_STDERR_NOTIFICATIONS=1` para silenciarlas).
+
 Fallback (equivalent in pasos separados):
 
 ```bash

package/VERSION

@@ -1 +1 @@
-v6.3.61
+v6.3.64

package/docs/operations/RELEASE_NOTES.md

@@ -6,6 +6,16 @@ This file keeps only the operational highlights and rollout notes that matter wh
 
 ## 2026-04 (CLI stability and macOS notifications)
 
+### 2026-04-05 (v6.3.64)
+
+- **Notificaciones multiplataforma**: fuera de macOS, avisos críticos van a **stderr** por defecto (terminal visible). `PUMUKI_DISABLE_STDERR_NOTIFICATIONS=1` lo silencia para CI/scripts. En macOS, `PUMUKI_NOTIFICATION_STDERR_MIRROR=1` añade copia en terminal; si `osascript`/banner falla, stderr actúa como respaldo.
+- Rollout: repin a `pumuki@6.3.64`; validar hooks y, si usáis notificaciones, comprobar salida en entorno no-macOS.
+
+### 2026-04-05 (v6.3.63)
+
+- **Auto-wire on install**: el paquete npm ejecuta `postinstall` → `pumuki install` en el repo del consumidor (`INIT_CWD`) cuando hay `.git`. Saltar con `PUMUKI_SKIP_POSTINSTALL=1` o en CI. OpenSpec bootstrap sigue omitido en ese camino (`PUMUKI_SKIP_OPENSPEC_BOOTSTRAP` por defecto ahí). MCP en Cursor/Codex no se configura solo: usar `pumuki install --with-mcp` / adaptador cuando proceda.
+- **Best-effort**: si `doctor` bloquea, el postinstall puede cablear hooks en modo degradado para no dejar el paquete “muerto” en el hook chain.
+
 ### 2026-04-05 (v6.3.62)
 
 - Merged `refactor/cli-complexity-reduction-phase4-rebase2` into `develop` (PR #731); GitHub Actions quota may block CI—validate locally with `npm test` before consuming.

package/docs/product/USAGE.md

@@ -242,6 +242,7 @@ Stage mapping:
 If a scope is empty, the menu prints an explicit operational hint (`Scope vacío`), so `PASS` with zero findings is distinguishable from a clean repository scan.
 
 System notifications (macOS) can be enabled from advanced menu option `31` (persisted in `.pumuki/system-notifications.json`).
+On non-macOS platforms, the same payloads are written to **stderr** by default (visible in the terminal) because there is no native banner API. Set `PUMUKI_DISABLE_STDERR_NOTIFICATIONS=1` to silence that path (delivery reports `unsupported-platform` on those OSes). On macOS, set `PUMUKI_NOTIFICATION_STDERR_MIRROR=1` to duplicate the banner text to stderr in addition to the system notification.
 Blocked notifications now use a native Swift floating modal (bottom-right) by default, with AppleScript fallback.
 Override mode with `PUMUKI_MACOS_BLOCKED_DIALOG_MODE=auto|swift-floating|applescript`.
 Custom skills import is available in advanced menu option `33` (writes `/.pumuki/custom-rules.json`).

package/integrations/lifecycle/cli.ts

@@ -2143,6 +2143,11 @@ export const runLifecycleCli = async (
       }
       case 'install': {
         const result = runLifecycleInstall();
+        if (result.degradedDoctorBypass) {
+          writeInfo(
+            '[pumuki] install: hooks wired under best-effort mode (doctor reported blocking issues; fix baseline and run `pumuki doctor`).'
+          );
+        }
         writeInfo(
           `[pumuki] installed ${result.version} at ${result.repoRoot} (hooks changed: ${result.changedHooks.join(', ') || 'none'})`
         );

package/integrations/lifecycle/install.ts

@@ -18,6 +18,7 @@ export type LifecycleInstallResult = {
   version: string;
   changedHooks: ReadonlyArray<string>;
   openSpecBootstrap?: OpenSpecBootstrapResult;
+  degradedDoctorBypass?: boolean;
 };
 
 const shouldBootstrapEvidence = (repoRoot: string): boolean =>
@@ -38,19 +39,59 @@ const writeBootstrapEvidence = (repoRoot: string): void => {
   });
 };
 
+const wireHooksLifecycleAndBootstrapEvidence = (params: {
+  git: ILifecycleGitService;
+  repoRoot: string;
+  version: string;
+  openSpecManagedArtifacts?: ReadonlyArray<string>;
+}): ReadonlyArray<string> => {
+  const hookResult = installPumukiHooks(params.repoRoot);
+  writeLifecycleState({
+    git: params.git,
+    repoRoot: params.repoRoot,
+    version: params.version,
+    openSpecManagedArtifacts: params.openSpecManagedArtifacts,
+  });
+  ensureRuntimeArtifactsIgnored(params.repoRoot);
+  if (shouldBootstrapEvidence(params.repoRoot)) {
+    writeBootstrapEvidence(params.repoRoot);
+  }
+  return hookResult.changedHooks;
+};
+
 export const runLifecycleInstall = (params?: {
   cwd?: string;
   git?: ILifecycleGitService;
   npm?: ILifecycleNpmService;
   bootstrapOpenSpec?: boolean;
+  bestEffortAfterDoctorBlock?: boolean;
 }): LifecycleInstallResult => {
   const git = params?.git ?? new LifecycleGitService();
+  const bestEffortAfterDoctorBlock =
+    params?.bestEffortAfterDoctorBlock ?? process.env.PUMUKI_AUTO_POSTINSTALL === '1';
   const report = runLifecycleDoctor({
     cwd: params?.cwd,
     git,
   });
 
   if (doctorHasBlockingIssues(report)) {
+    if (bestEffortAfterDoctorBlock) {
+      const version = getCurrentPumukiVersion();
+      const priorArtifacts = readOpenSpecManagedArtifacts(git, report.repoRoot);
+      const changedHooks = wireHooksLifecycleAndBootstrapEvidence({
+        git,
+        repoRoot: report.repoRoot,
+        version,
+        openSpecManagedArtifacts: priorArtifacts.length > 0 ? priorArtifacts : undefined,
+      });
+      return {
+        repoRoot: report.repoRoot,
+        version,
+        changedHooks,
+        openSpecBootstrap: undefined,
+        degradedDoctorBypass: true,
+      };
+    }
     const renderedIssues = report.issues.map((issue) => `- [${issue.severity}] ${issue.message}`).join('\n');
     throw new Error(
       `pumuki install blocked by repository safety checks.\n${renderedIssues}\n` +
@@ -68,7 +109,6 @@ export const runLifecycleInstall = (params?: {
     })
     : undefined;
 
-  const hookResult = installPumukiHooks(report.repoRoot);
   const version = getCurrentPumukiVersion();
   const mergedOpenSpecArtifacts = new Set(
     readOpenSpecManagedArtifacts(git, report.repoRoot)
@@ -76,22 +116,17 @@ export const runLifecycleInstall = (params?: {
   for (const artifact of openSpecBootstrap?.managedArtifacts ?? []) {
     mergedOpenSpecArtifacts.add(artifact);
   }
-  writeLifecycleState({
+  const changedHooks = wireHooksLifecycleAndBootstrapEvidence({
     git,
     repoRoot: report.repoRoot,
     version,
     openSpecManagedArtifacts: Array.from(mergedOpenSpecArtifacts),
   });
-  ensureRuntimeArtifactsIgnored(report.repoRoot);
-
-  if (shouldBootstrapEvidence(report.repoRoot)) {
-    writeBootstrapEvidence(report.repoRoot);
-  }
 
   return {
     repoRoot: report.repoRoot,
     version,
-    changedHooks: hookResult.changedHooks,
+    changedHooks,
     openSpecBootstrap,
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki",
-  "version": "6.3.62",
+  "version": "6.3.64",
   "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": {
@@ -18,6 +18,7 @@
     "pumuki-mcp-enterprise-stdio": "bin/pumuki-mcp-enterprise-stdio.js"
   },
   "scripts": {
+    "postinstall": "node scripts/consumer-postinstall.cjs",
     "install-hooks": "node bin/pumuki.js install",
     "check-version": "node bin/pumuki.js status",
     "pumuki:install": "node bin/pumuki.js install",
@@ -245,6 +246,7 @@
     "integrations/platform/*.ts",
     "integrations/telemetry/*.ts",
     "scripts/*.ts",
+    "scripts/consumer-postinstall.cjs",
     "scripts/adapters/*.ts",
     "scripts/adapters/*.md",
     "scripts/*.sh",

package/scripts/consumer-postinstall.cjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+'use strict';
+
+const { existsSync } = require('node:fs');
+const { join, resolve } = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const skipReason = () => {
+  if (process.env.PUMUKI_SKIP_POSTINSTALL === '1') {
+    return 'PUMUKI_SKIP_POSTINSTALL=1';
+  }
+  if (process.env.CI === 'true' || process.env.CI === '1') {
+    return 'CI';
+  }
+  if (process.env.npm_config_ignore_scripts === 'true') {
+    return 'npm ignore-scripts';
+  }
+  return '';
+};
+
+const main = () => {
+  const reason = skipReason();
+  if (reason) {
+    return 0;
+  }
+
+  const consumerRoot = process.env.INIT_CWD || process.cwd();
+  if (!existsSync(join(consumerRoot, '.git'))) {
+    return 0;
+  }
+
+  const packageRoot = resolve(__dirname, '..');
+  const pumukiCli = join(packageRoot, 'bin', 'pumuki.js');
+  if (!existsSync(pumukiCli)) {
+    return 0;
+  }
+
+  const env = {
+    ...process.env,
+    PUMUKI_AUTO_POSTINSTALL: '1',
+    PUMUKI_SKIP_OPENSPEC_BOOTSTRAP: process.env.PUMUKI_SKIP_OPENSPEC_BOOTSTRAP ?? '1',
+  };
+
+  const result = spawnSync(process.execPath, [pumukiCli, 'install'], {
+    cwd: consumerRoot,
+    env,
+    stdio: 'inherit',
+  });
+
+  const code = typeof result.status === 'number' ? result.status : 1;
+  if (code !== 0) {
+    console.error(
+      '[pumuki] postinstall: `pumuki install` exited non-zero; npm install will still succeed. Run `npx pumuki install` or `npx pumuki doctor` from the repo root.'
+    );
+  }
+  return 0;
+};
+
+process.exitCode = main();

package/scripts/framework-menu-system-notifications-dispatch.ts

@@ -8,18 +8,33 @@ import type {
 } from './framework-menu-system-notifications-types';
 import { applyDialogChoice } from './framework-menu-system-notifications-config';
 import { deliverMacOsNotification } from './framework-menu-system-notifications-macos';
+import { isTruthyEnvValue } from './framework-menu-system-notifications-env';
+import {
+  deliverStderrNotificationBanner,
+  isStderrNotificationFallbackDisabled,
+} from './framework-menu-system-notifications-stdio-fallback';
 
 export const dispatchSystemNotification = (params: {
   event: PumukiCriticalNotificationEvent;
   payload: SystemNotificationPayload;
+  platform: NodeJS.Platform;
   repoRoot?: string;
   config: SystemNotificationsConfig;
   env: NodeJS.ProcessEnv;
   nowMs: number;
   runCommand?: SystemNotificationCommandRunner;
   runCommandWithOutput?: SystemNotificationCommandRunnerWithOutput;
-}): SystemNotificationEmitResult =>
-  deliverMacOsNotification({
+}): SystemNotificationEmitResult => {
+  const stderrOff = isStderrNotificationFallbackDisabled(params.env);
+
+  if (params.platform !== 'darwin') {
+    if (stderrOff) {
+      return { delivered: false, reason: 'unsupported-platform' };
+    }
+    return deliverStderrNotificationBanner({ payload: params.payload });
+  }
+
+  const macResult = deliverMacOsNotification({
     event: params.event,
     payload: params.payload,
     repoRoot: params.repoRoot,
@@ -30,3 +45,14 @@ export const dispatchSystemNotification = (params: {
     runCommandWithOutput: params.runCommandWithOutput,
     applyDialogChoice,
   });
+
+  if (macResult.delivered && isTruthyEnvValue(params.env.PUMUKI_NOTIFICATION_STDERR_MIRROR)) {
+    deliverStderrNotificationBanner({ payload: params.payload });
+  }
+
+  if (!macResult.delivered && macResult.reason === 'command-failed' && !stderrOff) {
+    return deliverStderrNotificationBanner({ payload: params.payload });
+  }
+
+  return macResult;
+};

package/scripts/framework-menu-system-notifications-env.ts

@@ -0,0 +1,7 @@
+export const isTruthyEnvValue = (value?: string): boolean => {
+  if (!value) {
+    return false;
+  }
+  const normalized = value.trim().toLowerCase();
+  return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';
+};

package/scripts/framework-menu-system-notifications-gate.ts

@@ -3,19 +3,11 @@ import type {
   SystemNotificationEmitResult,
   SystemNotificationsConfig,
 } from './framework-menu-system-notifications-types';
-
-const isTruthyEnvValue = (value?: string): boolean => {
-  if (!value) {
-    return false;
-  }
-  const normalized = value.trim().toLowerCase();
-  return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';
-};
+import { isTruthyEnvValue } from './framework-menu-system-notifications-env';
 
 export const resolveSystemNotificationGate = (params: {
   config: SystemNotificationsConfig;
   nowMs: number;
-  platform: NodeJS.Platform;
   env?: NodeJS.ProcessEnv;
 }): SystemNotificationEmitResult | null => {
   if (isTruthyEnvValue(params.env?.PUMUKI_DISABLE_SYSTEM_NOTIFICATIONS)) {
@@ -27,8 +19,5 @@ export const resolveSystemNotificationGate = (params: {
   if (isMutedAt(params.config, params.nowMs)) {
     return { delivered: false, reason: 'muted' };
   }
-  if (params.platform !== 'darwin') {
-    return { delivered: false, reason: 'unsupported-platform' };
-  }
   return null;
 };

package/scripts/framework-menu-system-notifications-lib.ts

@@ -48,7 +48,6 @@ export const emitSystemNotification = (params: {
   const gateResult = resolveSystemNotificationGate({
     config,
     nowMs,
-    platform,
     env: params.env ?? process.env,
   });
   if (gateResult) {
@@ -62,6 +61,7 @@ export const emitSystemNotification = (params: {
   return dispatchSystemNotification({
     event: params.event,
     payload,
+    platform,
     repoRoot: params.repoRoot,
     config,
     env: params.env ?? process.env,

package/scripts/framework-menu-system-notifications-payload-types.ts

@@ -6,5 +6,5 @@ export type SystemNotificationPayload = {
 };
 
 export type SystemNotificationEmitResult =
-  | { delivered: true; reason: 'delivered' }
+  | { delivered: true; reason: 'delivered' | 'stderr-fallback' }
   | { delivered: false; reason: 'disabled' | 'muted' | 'unsupported-platform' | 'command-failed' };

package/scripts/framework-menu-system-notifications-stdio-fallback.ts

@@ -0,0 +1,23 @@
+import type {
+  SystemNotificationEmitResult,
+  SystemNotificationPayload,
+} from './framework-menu-system-notifications-types';
+import { isTruthyEnvValue } from './framework-menu-system-notifications-env';
+
+export const isStderrNotificationFallbackDisabled = (env: NodeJS.ProcessEnv): boolean =>
+  isTruthyEnvValue(env.PUMUKI_DISABLE_STDERR_NOTIFICATIONS);
+
+export const deliverStderrNotificationBanner = (params: {
+  payload: SystemNotificationPayload;
+  stderr?: NodeJS.WriteStream;
+}): SystemNotificationEmitResult => {
+  const stderr = params.stderr ?? process.stderr;
+  const lines = [
+    '[pumuki]',
+    `title: ${params.payload.title}`,
+    ...(params.payload.subtitle ? [`subtitle: ${params.payload.subtitle}`] : []),
+    `message: ${params.payload.message}`,
+  ];
+  stderr.write(`${lines.join('\n')}\n`);
+  return { delivered: true, reason: 'stderr-fallback' };
+};