pumuki 6.3.26 → 6.3.28

package/integrations/lifecycle/doctor.ts

@@ -2,6 +2,16 @@ import { getPumukiHooksStatus } from './hookManager';
 import { LifecycleGitService, type ILifecycleGitService } from './gitService';
 import { getCurrentPumukiVersion } from './packageInfo';
 import { readLifecycleState, type LifecycleState } from './state';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { PUMUKI_MANAGED_HOOKS } from './constants';
+import { parseSkillsPolicy } from '../config/skillsPolicy';
+import { resolvePolicyForStage } from '../gate/stagePolicies';
+import { readEvidenceResult } from '../evidence/readEvidence';
+import {
+  resolveEvidenceSigningConfig,
+  verifyEvidenceIntegrity,
+} from '../evidence/integrity';
 
 export type DoctorIssueSeverity = 'warning' | 'error';
 
@@ -10,6 +20,27 @@ export type DoctorIssue = {
   message: string;
 };
 
+export type DoctorDeepCheckStatus = 'pass' | 'warn' | 'error';
+
+export type DoctorDeepCheckId =
+  | 'hooks'
+  | 'upstream'
+  | 'adapters'
+  | 'policy_drift'
+  | 'evidence_drift';
+
+export type DoctorDeepCheck = {
+  id: DoctorDeepCheckId;
+  status: DoctorDeepCheckStatus;
+  message: string;
+  details?: Record<string, string | number | boolean | null | ReadonlyArray<string>>;
+};
+
+export type LifecycleDoctorDeepReport = {
+  enabled: true;
+  checks: ReadonlyArray<DoctorDeepCheck>;
+};
+
 export type LifecycleDoctorReport = {
   repoRoot: string;
   packageVersion: string;
@@ -17,12 +48,494 @@ export type LifecycleDoctorReport = {
   trackedNodeModulesPaths: ReadonlyArray<string>;
   hookStatus: ReturnType<typeof getPumukiHooksStatus>;
   issues: ReadonlyArray<DoctorIssue>;
+  deep?: LifecycleDoctorDeepReport;
+};
+
+const DEEP_PRECOMMIT_MAX_EVIDENCE_AGE_SECONDS = 900;
+const SHA256_HEX_PATTERN = /^[A-Fa-f0-9]{64}$/;
+const ADAPTER_PATH_CANDIDATES = [
+  '.pumuki/adapter.json',
+  '.pumuki/adapters.json',
+  '.pumuki/adapter/hooks.json',
+  '.pumuki/mcp.json',
+] as const;
+
+const toDeepCheckIssueSeverity = (
+  status: DoctorDeepCheckStatus
+): DoctorIssueSeverity | null => {
+  if (status === 'error') {
+    return 'error';
+  }
+  if (status === 'warn') {
+    return 'warning';
+  }
+  return null;
+};
+
+const safeRunGit = (
+  git: ILifecycleGitService,
+  repoRoot: string,
+  args: ReadonlyArray<string>
+): string | undefined => {
+  try {
+    const output = git.runGit(args, repoRoot).trim();
+    return output.length > 0 ? output : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const toPositiveCount = (value: unknown): number => {
+  const count = typeof value === 'number' && Number.isFinite(value)
+    ? Math.trunc(value)
+    : Number.parseInt(String(value), 10);
+  if (!Number.isFinite(count) || Number.isNaN(count)) {
+    return 0;
+  }
+  return Math.max(0, count);
+};
+
+const evaluateDeepHooksCheck = (params: {
+  repoRoot: string;
+  hookStatus: ReturnType<typeof getPumukiHooksStatus>;
+}): DoctorDeepCheck => {
+  const missingManagedHooks: string[] = [];
+  const nonExecutableManagedHooks: string[] = [];
+
+  for (const hook of PUMUKI_MANAGED_HOOKS) {
+    const status = params.hookStatus[hook];
+    if (!status.exists || !status.managedBlockPresent) {
+      missingManagedHooks.push(hook);
+      continue;
+    }
+    const hookPath = join(params.repoRoot, '.git', 'hooks', hook);
+    try {
+      const mode = statSync(hookPath).mode;
+      if ((mode & 0o111) === 0) {
+        nonExecutableManagedHooks.push(hook);
+      }
+    } catch {
+      nonExecutableManagedHooks.push(hook);
+    }
+  }
+
+  if (nonExecutableManagedHooks.length > 0) {
+    return {
+      id: 'hooks',
+      status: 'error',
+      message: `Managed hooks are not executable: ${nonExecutableManagedHooks.join(', ')}.`,
+      details: {
+        non_executable_hooks: nonExecutableManagedHooks,
+      },
+    };
+  }
+
+  if (missingManagedHooks.length > 0) {
+    return {
+      id: 'hooks',
+      status: 'warn',
+      message: `Managed hook blocks are missing for: ${missingManagedHooks.join(', ')}.`,
+      details: {
+        missing_hooks: missingManagedHooks,
+      },
+    };
+  }
+
+  return {
+    id: 'hooks',
+    status: 'pass',
+    message: 'Managed hooks are present and executable.',
+  };
+};
+
+const evaluateDeepUpstreamCheck = (params: {
+  repoRoot: string;
+  git: ILifecycleGitService;
+}): DoctorDeepCheck => {
+  const branch = safeRunGit(params.git, params.repoRoot, [
+    'rev-parse',
+    '--abbrev-ref',
+    'HEAD',
+  ]);
+  if (!branch || branch === 'HEAD') {
+    return {
+      id: 'upstream',
+      status: 'warn',
+      message: 'Current branch could not be resolved for upstream diagnostics.',
+    };
+  }
+
+  const upstream = safeRunGit(params.git, params.repoRoot, [
+    'rev-parse',
+    '--abbrev-ref',
+    '--symbolic-full-name',
+    '@{u}',
+  ]);
+  if (!upstream) {
+    return {
+      id: 'upstream',
+      status: 'warn',
+      message: `No upstream configured for branch "${branch}".`,
+      details: {
+        branch,
+      },
+    };
+  }
+
+  const aheadBehindRaw = safeRunGit(params.git, params.repoRoot, [
+    'rev-list',
+    '--left-right',
+    '--count',
+    `${upstream}...HEAD`,
+  ]);
+  const [behindRaw, aheadRaw] = (aheadBehindRaw ?? '').split(/\s+/);
+  const behind = toPositiveCount(behindRaw);
+  const ahead = toPositiveCount(aheadRaw);
+
+  if (behind > 0) {
+    return {
+      id: 'upstream',
+      status: 'warn',
+      message: `Branch "${branch}" is behind "${upstream}" by ${behind} commit(s).`,
+      details: {
+        branch,
+        upstream,
+        ahead,
+        behind,
+      },
+    };
+  }
+
+  return {
+    id: 'upstream',
+    status: 'pass',
+    message: `Branch "${branch}" has upstream "${upstream}" (ahead=${ahead}, behind=${behind}).`,
+    details: {
+      branch,
+      upstream,
+      ahead,
+      behind,
+    },
+  };
+};
+
+const evaluateDeepAdaptersCheck = (repoRoot: string): DoctorDeepCheck => {
+  const discoveredPaths = ADAPTER_PATH_CANDIDATES.filter((candidate) =>
+    existsSync(resolve(repoRoot, candidate))
+  );
+  if (discoveredPaths.length === 0) {
+    return {
+      id: 'adapters',
+      status: 'warn',
+      message: 'No adapter configuration file was detected in the repository.',
+      details: {
+        candidates: ADAPTER_PATH_CANDIDATES as unknown as ReadonlyArray<string>,
+      },
+    };
+  }
+
+  const invalidJsonPaths: string[] = [];
+  const pumukiConfiguredPaths: string[] = [];
+
+  for (const relativePath of discoveredPaths) {
+    const absolutePath = resolve(repoRoot, relativePath);
+    try {
+      const parsed = JSON.parse(readFileSync(absolutePath, 'utf8')) as unknown;
+      const normalized = JSON.stringify(parsed).toLowerCase();
+      if (
+        normalized.includes('pumuki-pre-') ||
+        normalized.includes('pumuki-mcp-enterprise') ||
+        normalized.includes('pumuki-mcp-evidence')
+      ) {
+        pumukiConfiguredPaths.push(relativePath);
+      }
+    } catch {
+      invalidJsonPaths.push(relativePath);
+    }
+  }
+
+  if (invalidJsonPaths.length > 0) {
+    return {
+      id: 'adapters',
+      status: 'error',
+      message: `Adapter configuration contains invalid JSON: ${invalidJsonPaths.join(', ')}.`,
+      details: {
+        invalid_paths: invalidJsonPaths,
+      },
+    };
+  }
+
+  if (pumukiConfiguredPaths.length === 0) {
+    return {
+      id: 'adapters',
+      status: 'warn',
+      message: `Adapter files were found but no Pumuki commands were detected: ${discoveredPaths.join(', ')}.`,
+      details: {
+        discovered_paths: discoveredPaths,
+      },
+    };
+  }
+
+  return {
+    id: 'adapters',
+    status: 'pass',
+    message: `Adapter configuration detected with Pumuki bindings: ${pumukiConfiguredPaths.join(', ')}.`,
+    details: {
+      discovered_paths: discoveredPaths,
+      pumuki_paths: pumukiConfiguredPaths,
+    },
+  };
+};
+
+const evaluateDeepPolicyDriftCheck = (repoRoot: string): DoctorDeepCheck => {
+  const stages: ReadonlyArray<'PRE_COMMIT' | 'PRE_PUSH' | 'CI'> = [
+    'PRE_COMMIT',
+    'PRE_PUSH',
+    'CI',
+  ];
+  const resolvedPolicies = stages.map((stage) => ({
+    stage,
+    resolved: resolvePolicyForStage(stage, repoRoot),
+  }));
+  const invalidHashStages = resolvedPolicies
+    .filter((entry) => !SHA256_HEX_PATTERN.test(entry.resolved.trace.hash))
+    .map((entry) => entry.stage);
+  const invalidSignatureStages = resolvedPolicies
+    .filter((entry) => !SHA256_HEX_PATTERN.test(entry.resolved.trace.signature ?? ''))
+    .map((entry) => entry.stage);
+  const missingVersionStages = resolvedPolicies
+    .filter((entry) => {
+      const version = entry.resolved.trace.version;
+      return typeof version !== 'string' || version.trim().length === 0;
+    })
+    .map((entry) => entry.stage);
+
+  if (invalidHashStages.length > 0) {
+    return {
+      id: 'policy_drift',
+      status: 'error',
+      message: `Policy trace hash is invalid for stages: ${invalidHashStages.join(', ')}.`,
+      details: {
+        invalid_hash_stages: invalidHashStages,
+      },
+    };
+  }
+  if (invalidSignatureStages.length > 0) {
+    return {
+      id: 'policy_drift',
+      status: 'error',
+      message: `Policy trace signature is invalid for stages: ${invalidSignatureStages.join(', ')}.`,
+      details: {
+        invalid_signature_stages: invalidSignatureStages,
+      },
+    };
+  }
+  if (missingVersionStages.length > 0) {
+    return {
+      id: 'policy_drift',
+      status: 'error',
+      message: `Policy trace version is missing for stages: ${missingVersionStages.join(', ')}.`,
+      details: {
+        missing_version_stages: missingVersionStages,
+      },
+    };
+  }
+
+  const policyPath = resolve(repoRoot, 'skills.policy.json');
+  const policyExists = existsSync(policyPath);
+  if (!policyExists) {
+    return {
+      id: 'policy_drift',
+      status: 'pass',
+      message: 'No skills.policy.json detected; default/hard-mode policy trace is consistent.',
+    };
+  }
+
+  let parsedPolicy: unknown;
+  try {
+    parsedPolicy = JSON.parse(readFileSync(policyPath, 'utf8')) as unknown;
+  } catch {
+    return {
+      id: 'policy_drift',
+      status: 'error',
+      message: 'skills.policy.json exists but is not valid JSON.',
+      details: {
+        policy_path: policyPath,
+      },
+    };
+  }
+
+  if (!parseSkillsPolicy(parsedPolicy)) {
+    return {
+      id: 'policy_drift',
+      status: 'error',
+      message: 'skills.policy.json exists but does not match the expected schema.',
+      details: {
+        policy_path: policyPath,
+      },
+    };
+  }
+
+  const usingHardMode = resolvedPolicies.some(
+    (entry) => entry.resolved.trace.source === 'hard-mode'
+  );
+  const defaultSourceStages = resolvedPolicies
+    .filter((entry) => entry.resolved.trace.source === 'default')
+    .map((entry) => entry.stage);
+  if (!usingHardMode && defaultSourceStages.length > 0) {
+    return {
+      id: 'policy_drift',
+      status: 'warn',
+      message: `skills.policy.json is present but default policy remains active for: ${defaultSourceStages.join(', ')}.`,
+      details: {
+        default_source_stages: defaultSourceStages,
+      },
+    };
+  }
+
+  return {
+    id: 'policy_drift',
+    status: 'pass',
+    message: 'Policy trace is consistent with the active policy bundle.',
+  };
+};
+
+const toTimestampAgeSeconds = (value: string): number | null => {
+  const parsed = Date.parse(value);
+  if (!Number.isFinite(parsed)) {
+    return null;
+  }
+  const rawAge = Math.floor((Date.now() - parsed) / 1000);
+  return rawAge >= 0 ? rawAge : 0;
+};
+
+const evaluateDeepEvidenceDriftCheck = (repoRoot: string): DoctorDeepCheck => {
+  const evidenceResult = readEvidenceResult(repoRoot);
+  if (evidenceResult.kind === 'missing') {
+    return {
+      id: 'evidence_drift',
+      status: 'warn',
+      message: '.ai_evidence.json is missing; evidence drift cannot be evaluated.',
+    };
+  }
+
+  if (evidenceResult.kind === 'invalid') {
+    return {
+      id: 'evidence_drift',
+      status: 'error',
+      message: `.ai_evidence.json is invalid${evidenceResult.version ? ` (version=${evidenceResult.version})` : ''}.`,
+    };
+  }
+
+  const integrity = verifyEvidenceIntegrity(evidenceResult.evidence, {
+    signatureConfig: resolveEvidenceSigningConfig(process.env),
+    enforceSignature: false,
+  });
+  if (!integrity.ok) {
+    return {
+      id: 'evidence_drift',
+      status: 'error',
+      message: `${integrity.code ?? 'EVIDENCE_INTEGRITY_INVALID'}: ${integrity.message ?? 'Evidence integrity verification failed.'}`,
+      details: {
+        payload_hash: integrity.payloadHash,
+        chain_hash: integrity.chainHash,
+        previous_chain_hash: integrity.previousChainHash,
+        signature_present: integrity.signature.present,
+        signature_key_id: integrity.signature.keyId,
+      },
+    };
+  }
+
+  const timestamp = (evidenceResult.evidence as { timestamp?: unknown }).timestamp;
+  if (typeof timestamp !== 'string' || timestamp.trim().length === 0) {
+    return {
+      id: 'evidence_drift',
+      status: 'error',
+      message: 'Evidence payload is missing a valid timestamp.',
+    };
+  }
+
+  const ageSeconds = toTimestampAgeSeconds(timestamp);
+  if (ageSeconds === null) {
+    return {
+      id: 'evidence_drift',
+      status: 'error',
+      message: 'Evidence timestamp is not a valid ISO date.',
+    };
+  }
+
+  const aiGateStatus = (
+    evidenceResult.evidence as { ai_gate?: { status?: unknown } }
+  ).ai_gate?.status;
+
+  if (ageSeconds > DEEP_PRECOMMIT_MAX_EVIDENCE_AGE_SECONDS) {
+    return {
+      id: 'evidence_drift',
+      status: 'warn',
+      message: `Evidence is stale (${ageSeconds}s > ${DEEP_PRECOMMIT_MAX_EVIDENCE_AGE_SECONDS}s for PRE_COMMIT baseline).`,
+      details: {
+        age_seconds: ageSeconds,
+        max_age_seconds: DEEP_PRECOMMIT_MAX_EVIDENCE_AGE_SECONDS,
+      },
+    };
+  }
+
+  if (aiGateStatus === 'BLOCKED') {
+    return {
+      id: 'evidence_drift',
+      status: 'warn',
+      message: 'Evidence gate status is BLOCKED in the latest evidence snapshot.',
+      details: {
+        age_seconds: ageSeconds,
+      },
+    };
+  }
+
+  return {
+    id: 'evidence_drift',
+    status: 'pass',
+    message: `Evidence freshness is within baseline (age=${ageSeconds}s).`,
+    details: {
+      age_seconds: ageSeconds,
+      max_age_seconds: DEEP_PRECOMMIT_MAX_EVIDENCE_AGE_SECONDS,
+      integrity_chain_hash: integrity.chainHash,
+      integrity_previous_chain_hash: integrity.previousChainHash,
+      integrity_signature_present: integrity.signature.present,
+      integrity_signature_verified: integrity.signature.verified,
+    },
+  };
+};
+
+const buildDeepDoctorReport = (params: {
+  repoRoot: string;
+  git: ILifecycleGitService;
+  hookStatus: ReturnType<typeof getPumukiHooksStatus>;
+}): LifecycleDoctorDeepReport => {
+  const checks: DoctorDeepCheck[] = [
+    evaluateDeepHooksCheck({
+      repoRoot: params.repoRoot,
+      hookStatus: params.hookStatus,
+    }),
+    evaluateDeepUpstreamCheck({
+      repoRoot: params.repoRoot,
+      git: params.git,
+    }),
+    evaluateDeepAdaptersCheck(params.repoRoot),
+    evaluateDeepPolicyDriftCheck(params.repoRoot),
+    evaluateDeepEvidenceDriftCheck(params.repoRoot),
+  ];
+
+  return {
+    enabled: true,
+    checks,
+  };
 };
 
 const buildDoctorIssues = (params: {
   trackedNodeModulesPaths: ReadonlyArray<string>;
   hookStatus: ReturnType<typeof getPumukiHooksStatus>;
   lifecycleState: LifecycleState;
+  deepChecks?: ReadonlyArray<DoctorDeepCheck>;
 }): ReadonlyArray<DoctorIssue> => {
   const issues: DoctorIssue[] = [];
 
@@ -56,12 +569,24 @@ const buildDoctorIssues = (params: {
     });
   }
 
+  for (const check of params.deepChecks ?? []) {
+    const severity = toDeepCheckIssueSeverity(check.status);
+    if (!severity) {
+      continue;
+    }
+    issues.push({
+      severity,
+      message: `doctor --deep [${check.id}] ${check.message}`,
+    });
+  }
+
   return issues;
 };
 
 export const runLifecycleDoctor = (params?: {
   cwd?: string;
   git?: ILifecycleGitService;
+  deep?: boolean;
 }): LifecycleDoctorReport => {
   const git = params?.git ?? new LifecycleGitService();
   const cwd = params?.cwd ?? process.cwd();
@@ -69,11 +594,19 @@ export const runLifecycleDoctor = (params?: {
   const trackedNodeModulesPaths = git.trackedNodeModulesPaths(repoRoot);
   const hookStatus = getPumukiHooksStatus(repoRoot);
   const lifecycleState = readLifecycleState(git, repoRoot);
+  const deepReport = params?.deep
+    ? buildDeepDoctorReport({
+        repoRoot,
+        git,
+        hookStatus,
+      })
+    : undefined;
 
   const issues = buildDoctorIssues({
     trackedNodeModulesPaths,
     hookStatus,
     lifecycleState,
+    deepChecks: deepReport?.checks,
   });
 
   return {
@@ -83,6 +616,7 @@ export const runLifecycleDoctor = (params?: {
     trackedNodeModulesPaths,
     hookStatus,
     issues,
+    deep: deepReport,
   };
 };
 

package/integrations/lifecycle/hookBlock.ts

@@ -8,6 +8,7 @@ const HOOK_COMMANDS: Record<PumukiManagedHook, string> = {
   'pre-commit': 'pumuki-pre-commit',
   'pre-push': 'pumuki-pre-push',
 };
+const PUMUKI_HOOK_PACKAGE = 'pumuki@latest';
 
 const trimTrailingWhitespace = (value: string): string =>
   value.replace(/[ \t]+\n/g, '\n').trimEnd();
@@ -30,7 +31,7 @@ export const buildPumukiManagedHookBlock = (hook: PumukiManagedHook): string =>
   return [
     PUMUKI_MANAGED_BLOCK_START,
     'if command -v npx >/dev/null 2>&1; then',
-    `  npx --yes ${cli}`,
+    `  npx --yes --package ${PUMUKI_HOOK_PACKAGE} ${cli}`,
     '  status=$?',
     '  if [ "$status" -ne 0 ]; then',
     '    exit "$status"',

package/integrations/lifecycle/index.js

@@ -0,0 +1,5 @@
+'use strict';
+
+require('tsx/cjs');
+
+module.exports = require('./index.ts');