pumuki 6.3.7

package/integrations/lifecycle/hookManager.ts

@@ -0,0 +1,107 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PUMUKI_MANAGED_HOOKS, type PumukiManagedHook } from './constants';
+import {
+  hasPumukiManagedBlock,
+  removePumukiManagedBlock,
+  upsertPumukiManagedBlock,
+} from './hookBlock';
+
+export type HookInstallResult = {
+  changedHooks: ReadonlyArray<PumukiManagedHook>;
+};
+
+export type HookUninstallResult = {
+  changedHooks: ReadonlyArray<PumukiManagedHook>;
+};
+
+const HOOK_FILE_MODE = 0o755;
+
+const resolveHooksDirectory = (repoRoot: string): string => join(repoRoot, '.git', 'hooks');
+
+const resolveHookPath = (repoRoot: string, hook: PumukiManagedHook): string =>
+  join(resolveHooksDirectory(repoRoot), hook);
+
+const readHookFileOrEmpty = (hookPath: string): string =>
+  existsSync(hookPath) ? readFileSync(hookPath, 'utf8') : '';
+
+const writeHookFile = (hookPath: string, contents: string): void => {
+  writeFileSync(hookPath, contents, 'utf8');
+  chmodSync(hookPath, HOOK_FILE_MODE);
+};
+
+const ensureHooksDirectory = (repoRoot: string): void => {
+  mkdirSync(resolveHooksDirectory(repoRoot), { recursive: true });
+};
+
+export const installPumukiHooks = (repoRoot: string): HookInstallResult => {
+  ensureHooksDirectory(repoRoot);
+  const changedHooks: PumukiManagedHook[] = [];
+
+  for (const hook of PUMUKI_MANAGED_HOOKS) {
+    const hookPath = resolveHookPath(repoRoot, hook);
+    const current = readHookFileOrEmpty(hookPath);
+    const updated = upsertPumukiManagedBlock({
+      contents: current,
+      hook,
+    });
+    if (updated !== current) {
+      writeHookFile(hookPath, updated);
+      changedHooks.push(hook);
+    }
+  }
+
+  return { changedHooks };
+};
+
+export const uninstallPumukiHooks = (repoRoot: string): HookUninstallResult => {
+  const changedHooks: PumukiManagedHook[] = [];
+
+  for (const hook of PUMUKI_MANAGED_HOOKS) {
+    const hookPath = resolveHookPath(repoRoot, hook);
+    if (!existsSync(hookPath)) {
+      continue;
+    }
+
+    const current = readHookFileOrEmpty(hookPath);
+    const result = removePumukiManagedBlock(current);
+    if (!result.removed) {
+      continue;
+    }
+
+    if (result.updated === '') {
+      unlinkSync(hookPath);
+    } else {
+      writeHookFile(hookPath, result.updated);
+    }
+
+    changedHooks.push(hook);
+  }
+
+  return { changedHooks };
+};
+
+export const getPumukiHooksStatus = (
+  repoRoot: string
+): Record<PumukiManagedHook, { exists: boolean; managedBlockPresent: boolean }> => {
+  const status = {} as Record<PumukiManagedHook, { exists: boolean; managedBlockPresent: boolean }>;
+
+  for (const hook of PUMUKI_MANAGED_HOOKS) {
+    const hookPath = resolveHookPath(repoRoot, hook);
+    if (!existsSync(hookPath)) {
+      status[hook] = {
+        exists: false,
+        managedBlockPresent: false,
+      };
+      continue;
+    }
+
+    const contents = readHookFileOrEmpty(hookPath);
+    status[hook] = {
+      exists: true,
+      managedBlockPresent: hasPumukiManagedBlock(contents),
+    };
+  }
+
+  return status;
+};

package/integrations/lifecycle/index.ts

@@ -0,0 +1,6 @@
+export { runLifecycleDoctor, doctorHasBlockingIssues } from './doctor';
+export { runLifecycleInstall } from './install';
+export { runLifecycleUninstall } from './uninstall';
+export { runLifecycleRemove } from './remove';
+export { runLifecycleUpdate } from './update';
+export { readLifecycleStatus } from './status';

package/integrations/lifecycle/install.ts

@@ -0,0 +1,44 @@
+import { installPumukiHooks } from './hookManager';
+import { LifecycleGitService, type ILifecycleGitService } from './gitService';
+import { doctorHasBlockingIssues, runLifecycleDoctor } from './doctor';
+import { getCurrentPumukiVersion } from './packageInfo';
+import { writeLifecycleState } from './state';
+
+export type LifecycleInstallResult = {
+  repoRoot: string;
+  version: string;
+  changedHooks: ReadonlyArray<string>;
+};
+
+export const runLifecycleInstall = (params?: {
+  cwd?: string;
+  git?: ILifecycleGitService;
+}): LifecycleInstallResult => {
+  const git = params?.git ?? new LifecycleGitService();
+  const report = runLifecycleDoctor({
+    cwd: params?.cwd,
+    git,
+  });
+
+  if (doctorHasBlockingIssues(report)) {
+    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` +
+      'Fix the baseline (for example tracked node_modules) and retry.'
+    );
+  }
+
+  const hookResult = installPumukiHooks(report.repoRoot);
+  const version = getCurrentPumukiVersion();
+  writeLifecycleState({
+    git,
+    repoRoot: report.repoRoot,
+    version,
+  });
+
+  return {
+    repoRoot: report.repoRoot,
+    version,
+    changedHooks: hookResult.changedHooks,
+  };
+};

package/integrations/lifecycle/npmService.ts

@@ -0,0 +1,21 @@
+import { spawnSync } from 'node:child_process';
+
+export interface ILifecycleNpmService {
+  runNpm(args: ReadonlyArray<string>, cwd: string): void;
+}
+
+export class LifecycleNpmService implements ILifecycleNpmService {
+  runNpm(args: ReadonlyArray<string>, cwd: string): void {
+    const result = spawnSync('npm', args, {
+      cwd,
+      stdio: 'inherit',
+      env: process.env,
+    });
+    if (result.error) {
+      throw new Error(`npm ${args.join(' ')} failed: ${result.error.message}`);
+    }
+    if (typeof result.status !== 'number' || result.status !== 0) {
+      throw new Error(`npm ${args.join(' ')} failed with exit code ${result.status ?? 'unknown'}`);
+    }
+  }
+}

package/integrations/lifecycle/packageInfo.ts

@@ -0,0 +1,5 @@
+import packageJson from '../../package.json';
+
+export const getCurrentPumukiVersion = (): string => packageJson.version;
+
+export const getCurrentPumukiPackageName = (): string => packageJson.name;

package/integrations/lifecycle/remove.ts

@@ -0,0 +1,95 @@
+import { existsSync, readdirSync, rmSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveCurrentPumukiDependency } from './consumerPackage';
+import { LifecycleGitService, type ILifecycleGitService } from './gitService';
+import { LifecycleNpmService, type ILifecycleNpmService } from './npmService';
+import { getCurrentPumukiPackageName } from './packageInfo';
+import { runLifecycleUninstall } from './uninstall';
+
+export type LifecycleRemoveResult = {
+  repoRoot: string;
+  packageRemoved: boolean;
+  changedHooks: ReadonlyArray<string>;
+  removedArtifacts: ReadonlyArray<string>;
+};
+
+const cleanupNodeModulesIfOnlyLockfile = (repoRoot: string): void => {
+  const nodeModulesPath = join(repoRoot, 'node_modules');
+  if (!existsSync(nodeModulesPath)) {
+    return;
+  }
+
+  const entries = readdirSync(nodeModulesPath, { withFileTypes: true });
+  if (entries.length === 0) {
+    rmSync(nodeModulesPath, { recursive: true, force: true });
+    return;
+  }
+
+  const allowedNames = new Set(['.package-lock.json', '.bin']);
+  const hasOnlyAllowedEntries = entries.every((entry) => allowedNames.has(entry.name));
+  if (!hasOnlyAllowedEntries) {
+    return;
+  }
+
+  const lockfileEntry = entries.find((entry) => entry.name === '.package-lock.json' && entry.isFile());
+  if (!lockfileEntry) {
+    return;
+  }
+
+  const binEntry = entries.find((entry) => entry.name === '.bin' && entry.isDirectory());
+  if (binEntry) {
+    const binPath = join(nodeModulesPath, '.bin');
+    const binEntries = readdirSync(binPath);
+    if (binEntries.length > 0) {
+      return;
+    }
+    rmSync(binPath, { recursive: true, force: true });
+  }
+
+  if (existsSync(join(nodeModulesPath, '.package-lock.json'))) {
+    unlinkSync(join(nodeModulesPath, '.package-lock.json'));
+  }
+
+  if (readdirSync(nodeModulesPath).length === 0) {
+    rmSync(nodeModulesPath, { recursive: true, force: true });
+  }
+};
+
+export const runLifecycleRemove = (params?: {
+  cwd?: string;
+  git?: ILifecycleGitService;
+  npm?: ILifecycleNpmService;
+}): LifecycleRemoveResult => {
+  const git = params?.git ?? new LifecycleGitService();
+  const npm = params?.npm ?? new LifecycleNpmService();
+  const repoRoot = git.resolveRepoRoot(params?.cwd ?? process.cwd());
+
+  const uninstallResult = runLifecycleUninstall({
+    cwd: repoRoot,
+    purgeArtifacts: true,
+    git,
+  });
+
+  const currentDependency = resolveCurrentPumukiDependency(repoRoot);
+  const packageName = getCurrentPumukiPackageName();
+
+  if (currentDependency.source === 'none') {
+    cleanupNodeModulesIfOnlyLockfile(repoRoot);
+    return {
+      repoRoot,
+      packageRemoved: false,
+      changedHooks: uninstallResult.changedHooks,
+      removedArtifacts: uninstallResult.removedArtifacts,
+    };
+  }
+
+  npm.runNpm(['uninstall', packageName], repoRoot);
+  cleanupNodeModulesIfOnlyLockfile(repoRoot);
+
+  return {
+    repoRoot,
+    packageRemoved: true,
+    changedHooks: uninstallResult.changedHooks,
+    removedArtifacts: uninstallResult.removedArtifacts,
+  };
+};

package/integrations/lifecycle/state.ts

@@ -0,0 +1,41 @@
+import { PUMUKI_CONFIG_KEYS, PUMUKI_MANAGED_HOOKS } from './constants';
+import type { ILifecycleGitService } from './gitService';
+
+export type LifecycleState = {
+  installed?: string;
+  version?: string;
+  hooks?: string;
+  installedAt?: string;
+};
+
+export const readLifecycleState = (
+  git: ILifecycleGitService,
+  repoRoot: string
+): LifecycleState => ({
+  installed: git.getLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.installed),
+  version: git.getLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.version),
+  hooks: git.getLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.hooks),
+  installedAt: git.getLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.installedAt),
+});
+
+export const writeLifecycleState = (params: {
+  git: ILifecycleGitService;
+  repoRoot: string;
+  version: string;
+}): void => {
+  const { git, repoRoot, version } = params;
+  git.setLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.installed, 'true');
+  git.setLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.version, version);
+  git.setLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.hooks, PUMUKI_MANAGED_HOOKS.join(','));
+  git.setLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.installedAt, new Date().toISOString());
+};
+
+export const clearLifecycleState = (
+  git: ILifecycleGitService,
+  repoRoot: string
+): void => {
+  git.unsetLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.installed);
+  git.unsetLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.version);
+  git.unsetLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.hooks);
+  git.unsetLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.installedAt);
+};

package/integrations/lifecycle/status.ts

@@ -0,0 +1,30 @@
+import { getPumukiHooksStatus } from './hookManager';
+import { LifecycleGitService, type ILifecycleGitService } from './gitService';
+import { getCurrentPumukiVersion } from './packageInfo';
+import { readLifecycleState, type LifecycleState } from './state';
+
+export type LifecycleStatus = {
+  repoRoot: string;
+  packageVersion: string;
+  lifecycleState: LifecycleState;
+  hookStatus: ReturnType<typeof getPumukiHooksStatus>;
+  trackedNodeModulesCount: number;
+};
+
+export const readLifecycleStatus = (params?: {
+  cwd?: string;
+  git?: ILifecycleGitService;
+}): LifecycleStatus => {
+  const git = params?.git ?? new LifecycleGitService();
+  const cwd = params?.cwd ?? process.cwd();
+  const repoRoot = git.resolveRepoRoot(cwd);
+  const trackedNodeModulesCount = git.listTrackedNodeModulesPaths(repoRoot).length;
+
+  return {
+    repoRoot,
+    packageVersion: getCurrentPumukiVersion(),
+    lifecycleState: readLifecycleState(git, repoRoot),
+    hookStatus: getPumukiHooksStatus(repoRoot),
+    trackedNodeModulesCount,
+  };
+};

package/integrations/lifecycle/uninstall.ts

@@ -0,0 +1,36 @@
+import { purgeUntrackedPumukiArtifacts } from './artifacts';
+import { LifecycleGitService, type ILifecycleGitService } from './gitService';
+import { uninstallPumukiHooks } from './hookManager';
+import { clearLifecycleState } from './state';
+
+export type LifecycleUninstallResult = {
+  repoRoot: string;
+  changedHooks: ReadonlyArray<string>;
+  removedArtifacts: ReadonlyArray<string>;
+};
+
+export const runLifecycleUninstall = (params?: {
+  cwd?: string;
+  purgeArtifacts?: boolean;
+  git?: ILifecycleGitService;
+}): LifecycleUninstallResult => {
+  const git = params?.git ?? new LifecycleGitService();
+  const cwd = params?.cwd ?? process.cwd();
+  const repoRoot = git.resolveRepoRoot(cwd);
+
+  const hookResult = uninstallPumukiHooks(repoRoot);
+  clearLifecycleState(git, repoRoot);
+
+  const removedArtifacts = params?.purgeArtifacts
+    ? purgeUntrackedPumukiArtifacts({
+      git,
+      repoRoot,
+    })
+    : [];
+
+  return {
+    repoRoot,
+    changedHooks: hookResult.changedHooks,
+    removedArtifacts,
+  };
+};

package/integrations/lifecycle/update.ts

@@ -0,0 +1,77 @@
+import { resolveCurrentPumukiDependency } from './consumerPackage';
+import { doctorHasBlockingIssues, runLifecycleDoctor } from './doctor';
+import { LifecycleGitService, type ILifecycleGitService } from './gitService';
+import { runLifecycleInstall } from './install';
+import { LifecycleNpmService, type ILifecycleNpmService } from './npmService';
+import { getCurrentPumukiPackageName } from './packageInfo';
+
+export type LifecycleUpdateResult = {
+  repoRoot: string;
+  targetSpec: string;
+  reinstallHooksChanged: ReadonlyArray<string>;
+};
+
+const resolveTargetSpec = (explicitSpec?: string): string => {
+  if (typeof explicitSpec === 'string' && explicitSpec.trim().length > 0) {
+    return explicitSpec.trim();
+  }
+  return `${getCurrentPumukiPackageName()}@latest`;
+};
+
+export const runLifecycleUpdate = (params?: {
+  cwd?: string;
+  targetSpec?: string;
+  git?: ILifecycleGitService;
+  npm?: ILifecycleNpmService;
+}): LifecycleUpdateResult => {
+  const git = params?.git ?? new LifecycleGitService();
+  const npm = params?.npm ?? new LifecycleNpmService();
+
+  const doctorReport = runLifecycleDoctor({
+    cwd: params?.cwd,
+    git,
+  });
+  if (doctorHasBlockingIssues(doctorReport)) {
+    const renderedIssues = doctorReport.issues
+      .map((issue) => `- [${issue.severity}] ${issue.message}`)
+      .join('\n');
+    throw new Error(`pumuki update blocked by repository safety checks.\n${renderedIssues}`);
+  }
+
+  const targetSpec = resolveTargetSpec(params?.targetSpec);
+  const currentDependency = resolveCurrentPumukiDependency(doctorReport.repoRoot);
+
+  const installArgs =
+    currentDependency.source === 'dependencies'
+      ? ['install', '--save-exact', targetSpec]
+      : ['install', '--save-dev', '--save-exact', targetSpec];
+  npm.runNpm(installArgs, doctorReport.repoRoot);
+
+  try {
+    const installResult = runLifecycleInstall({
+      cwd: doctorReport.repoRoot,
+      git,
+    });
+    return {
+      repoRoot: installResult.repoRoot,
+      targetSpec,
+      reinstallHooksChanged: installResult.changedHooks,
+    };
+  } catch (error) {
+    if (currentDependency.spec) {
+      const rollbackArgs =
+        currentDependency.source === 'dependencies'
+          ? ['install', '--save-exact', `${getCurrentPumukiPackageName()}@${currentDependency.spec}`]
+          : [
+            'install',
+            '--save-dev',
+            '--save-exact',
+            `${getCurrentPumukiPackageName()}@${currentDependency.spec}`,
+          ];
+      try {
+        npm.runNpm(rollbackArgs, doctorReport.repoRoot);
+      } catch {}
+    }
+    throw error;
+  }
+};

package/integrations/mcp/evidenceContextServer.cli.ts

@@ -0,0 +1,16 @@
+import { startEvidenceContextServer } from './evidenceContextServer';
+
+const parsedPort = Number.parseInt(process.env.PUMUKI_EVIDENCE_PORT ?? '', 10);
+const port = Number.isFinite(parsedPort) ? parsedPort : 7341;
+const host = process.env.PUMUKI_EVIDENCE_HOST ?? '127.0.0.1';
+const route = process.env.PUMUKI_EVIDENCE_ROUTE ?? '/ai-evidence';
+
+const started = startEvidenceContextServer({
+  host,
+  port,
+  route,
+});
+
+process.stdout.write(
+  `Evidence context server running at http://${started.host}:${started.port}${started.route}\n`
+);

package/integrations/mcp/evidenceContextServer.ts

@@ -0,0 +1,152 @@
+import { createServer } from 'node:http';
+import type { Server } from 'node:http';
+
+import {
+  readEvidence,
+  toStatusPayload,
+  toSummaryPayload,
+  toSnapshotPayload,
+  toFindingsPayload,
+  toRulesetsPayload,
+  toPlatformsPayload,
+  toLedgerPayloadWithFilters,
+  toResponsePayload,
+} from './evidencePayloads';
+
+export interface EvidenceServerOptions {
+  host?: string;
+  port?: number;
+  route?: string;
+  repoRoot?: string;
+}
+
+export interface EvidenceServerHandle {
+  server: Server;
+  host: string;
+  port: number;
+  route: string;
+}
+
+const normalizeRoute = (route: string): string => {
+  const trimmed = route.replace(/\/+$/, '');
+  return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+};
+
+export const startEvidenceContextServer = (
+  options: EvidenceServerOptions = {}
+): EvidenceServerHandle => {
+  const host = options.host ?? '127.0.0.1';
+  const port = options.port ?? 7341;
+  const route = normalizeRoute(options.route ?? '/ai-evidence');
+  const repoRoot = options.repoRoot ?? process.cwd();
+
+  const sendJson = (
+    res: import('node:http').ServerResponse,
+    status: number,
+    body: unknown
+  ): void => {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+      'Content-Type': 'application/json; charset=utf-8',
+      'Content-Length': Buffer.byteLength(payload),
+      'Cache-Control': 'no-store',
+    });
+    res.end(payload);
+  };
+
+  const server = createServer((req, res) => {
+    if (req.method !== 'GET') {
+      sendJson(res, 405, { error: 'Method not allowed' });
+      return;
+    }
+
+    const requestUrl = new URL(req.url ?? '/', `http://${host}:${port}`);
+    const pathname = requestUrl.pathname.replace(/\/+$/, '') || '/';
+
+    if (pathname === '/health') {
+      sendJson(res, 200, { status: 'ok' });
+      return;
+    }
+
+    if (pathname === '/status') {
+      sendJson(res, 200, toStatusPayload(repoRoot));
+      return;
+    }
+
+    if (pathname === `${route}/summary`) {
+      const evidence = readEvidence(repoRoot);
+      if (!evidence) {
+        sendJson(res, 404, { error: 'Evidence file not found or invalid' });
+        return;
+      }
+      sendJson(res, 200, toSummaryPayload(evidence));
+      return;
+    }
+
+    if (pathname === `${route}/snapshot`) {
+      const evidence = readEvidence(repoRoot);
+      if (!evidence) {
+        sendJson(res, 404, { error: 'Evidence file not found or invalid' });
+        return;
+      }
+      sendJson(res, 200, toSnapshotPayload(evidence));
+      return;
+    }
+
+    if (pathname === `${route}/findings`) {
+      const evidence = readEvidence(repoRoot);
+      if (!evidence) {
+        sendJson(res, 404, { error: 'Evidence file not found or invalid' });
+        return;
+      }
+      sendJson(res, 200, toFindingsPayload(evidence, requestUrl));
+      return;
+    }
+
+    if (pathname === `${route}/rulesets`) {
+      const evidence = readEvidence(repoRoot);
+      if (!evidence) {
+        sendJson(res, 404, { error: 'Evidence file not found or invalid' });
+        return;
+      }
+      sendJson(res, 200, toRulesetsPayload(evidence, requestUrl));
+      return;
+    }
+
+    if (pathname === `${route}/platforms`) {
+      const evidence = readEvidence(repoRoot);
+      if (!evidence) {
+        sendJson(res, 404, { error: 'Evidence file not found or invalid' });
+        return;
+      }
+      sendJson(res, 200, toPlatformsPayload(evidence, requestUrl));
+      return;
+    }
+
+    if (pathname === `${route}/ledger`) {
+      const evidence = readEvidence(repoRoot);
+      if (!evidence) {
+        sendJson(res, 404, { error: 'Evidence file not found or invalid' });
+        return;
+      }
+      sendJson(res, 200, toLedgerPayloadWithFilters(evidence, requestUrl));
+      return;
+    }
+
+    if (pathname === route) {
+      const evidence = readEvidence(repoRoot);
+      if (!evidence) {
+        sendJson(res, 404, { error: 'Evidence file not found or invalid' });
+        return;
+      }
+      sendJson(res, 200, toResponsePayload(evidence, requestUrl));
+      return;
+    }
+
+    sendJson(res, 404, { error: 'Not found' });
+  });
+
+  server.listen(port, host);
+
+  return { server, host, port, route };
+};

package/integrations/mcp/evidenceFacets.ts

@@ -0,0 +1,3 @@
+export * from './evidenceFacetsBase';
+export * from './evidenceFacetsSuppressed';
+export * from './evidenceFacetsSnapshot';