pumuki 6.3.7

package/integrations/git/runPlatformGateFacts.ts

@@ -0,0 +1,34 @@
+import type { Fact } from '../../core/facts/Fact';
+import type { IGitService } from './GitService';
+import { getFactsForCommitRange } from './getCommitRangeFacts';
+
+export type GateScope =
+  | {
+    kind: 'staged';
+    extensions?: string[];
+  }
+  | {
+    kind: 'range';
+    fromRef: string;
+    toRef: string;
+    extensions?: string[];
+  };
+
+const DEFAULT_EXTENSIONS = ['.swift', '.ts', '.tsx', '.js', '.jsx', '.kt', '.kts'];
+
+export const resolveFactsForGateScope = async (params: {
+  scope: GateScope;
+  git: IGitService;
+}): Promise<ReadonlyArray<Fact>> => {
+  const extensions = params.scope.extensions ?? DEFAULT_EXTENSIONS;
+  if (params.scope.kind === 'staged') {
+    return params.git.getStagedFacts(extensions);
+  }
+
+  return getFactsForCommitRange({
+    fromRef: params.scope.fromRef,
+    toRef: params.scope.toRef,
+    extensions: [...extensions],
+    git: params.git,
+  });
+};

package/integrations/git/runPlatformGateOutput.ts

@@ -0,0 +1,11 @@
+import type { Finding } from '../../core/gate/Finding';
+
+const formatFinding = (finding: Finding): string => {
+  return `${finding.ruleId}: ${finding.message}`;
+};
+
+export const printGateFindings = (findings: ReadonlyArray<Finding>): void => {
+  for (const finding of findings) {
+    console.log(formatFinding(finding));
+  }
+};

package/integrations/git/stageRunners.ts

@@ -0,0 +1,40 @@
+import { resolvePolicyForStage } from '../gate/stagePolicies';
+import { resolveCiBaseRef, resolveUpstreamRef } from './resolveGitRefs';
+import { runPlatformGate } from './runPlatformGate';
+
+export async function runPreCommitStage(): Promise<number> {
+  const resolved = resolvePolicyForStage('PRE_COMMIT');
+  return runPlatformGate({
+    policy: resolved.policy,
+    policyTrace: resolved.trace,
+    scope: {
+      kind: 'staged',
+    },
+  });
+}
+
+export async function runPrePushStage(): Promise<number> {
+  const resolved = resolvePolicyForStage('PRE_PUSH');
+  return runPlatformGate({
+    policy: resolved.policy,
+    policyTrace: resolved.trace,
+    scope: {
+      kind: 'range',
+      fromRef: resolveUpstreamRef(),
+      toRef: 'HEAD',
+    },
+  });
+}
+
+export async function runCiStage(): Promise<number> {
+  const resolved = resolvePolicyForStage('CI');
+  return runPlatformGate({
+    policy: resolved.policy,
+    policyTrace: resolved.trace,
+    scope: {
+      kind: 'range',
+      fromRef: resolveCiBaseRef(),
+      toRef: 'HEAD',
+    },
+  });
+}

package/integrations/lifecycle/artifacts.ts

@@ -0,0 +1,26 @@
+import { existsSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ILifecycleGitService } from './gitService';
+
+const PUMUKI_ARTIFACTS = ['.ai_evidence.json', '.AI_EVIDENCE.json'] as const;
+
+export const purgeUntrackedPumukiArtifacts = (params: {
+  git: ILifecycleGitService;
+  repoRoot: string;
+}): ReadonlyArray<string> => {
+  const removed: string[] = [];
+
+  for (const relativePath of PUMUKI_ARTIFACTS) {
+    const absolutePath = join(params.repoRoot, relativePath);
+    if (!existsSync(absolutePath)) {
+      continue;
+    }
+    if (params.git.isPathTracked(params.repoRoot, relativePath)) {
+      continue;
+    }
+    unlinkSync(absolutePath);
+    removed.push(relativePath);
+  }
+
+  return removed;
+};

package/integrations/lifecycle/cli.ts

@@ -0,0 +1,180 @@
+import { runLifecycleDoctor, type LifecycleDoctorReport } from './doctor';
+import { runLifecycleInstall } from './install';
+import { runLifecycleRemove } from './remove';
+import { readLifecycleStatus } from './status';
+import { runLifecycleUninstall } from './uninstall';
+import { runLifecycleUpdate } from './update';
+
+type LifecycleCommand =
+  | 'install'
+  | 'uninstall'
+  | 'remove'
+  | 'update'
+  | 'doctor'
+  | 'status';
+
+type ParsedArgs = {
+  command: LifecycleCommand;
+  purgeArtifacts: boolean;
+  updateSpec?: string;
+};
+
+const HELP_TEXT = `
+Pumuki lifecycle commands:
+  pumuki install
+  pumuki uninstall [--purge-artifacts]
+  pumuki remove
+  pumuki update [--latest|--spec=<package-spec>]
+  pumuki doctor
+  pumuki status
+`.trim();
+
+const isLifecycleCommand = (value: string): value is LifecycleCommand =>
+  value === 'install' ||
+  value === 'uninstall' ||
+  value === 'remove' ||
+  value === 'update' ||
+  value === 'doctor' ||
+  value === 'status';
+
+export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs => {
+  const commandRaw = argv[0];
+  if (!commandRaw || commandRaw === '--help' || commandRaw === '-h') {
+    throw new Error(HELP_TEXT);
+  }
+  if (!isLifecycleCommand(commandRaw)) {
+    throw new Error(`Unknown command "${commandRaw}".\n\n${HELP_TEXT}`);
+  }
+
+  let purgeArtifacts = false;
+  let updateSpec: string | undefined;
+  for (const arg of argv.slice(1)) {
+    if (arg === '--purge-artifacts') {
+      purgeArtifacts = true;
+      continue;
+    }
+    if (arg === '--latest') {
+      updateSpec = undefined;
+      continue;
+    }
+    if (arg.startsWith('--spec=')) {
+      updateSpec = arg.slice('--spec='.length).trim();
+      continue;
+    }
+
+    throw new Error(`Unsupported argument "${arg}".\n\n${HELP_TEXT}`);
+  }
+
+  return {
+    command: commandRaw,
+    purgeArtifacts,
+    updateSpec,
+  };
+};
+
+const printDoctorReport = (report: LifecycleDoctorReport): void => {
+  console.log(`[pumuki] repo: ${report.repoRoot}`);
+  console.log(`[pumuki] package version: ${report.packageVersion}`);
+  console.log(
+    `[pumuki] tracked node_modules paths: ${report.trackedNodeModulesPaths.length}`
+  );
+  console.log(
+    `[pumuki] hook pre-commit: ${report.hookStatus['pre-commit'].managedBlockPresent ? 'managed' : 'missing'}`
+  );
+  console.log(
+    `[pumuki] hook pre-push: ${report.hookStatus['pre-push'].managedBlockPresent ? 'managed' : 'missing'}`
+  );
+
+  if (report.issues.length === 0) {
+    console.log('[pumuki] doctor verdict: PASS');
+    return;
+  }
+
+  for (const issue of report.issues) {
+    console.log(`[pumuki] ${issue.severity.toUpperCase()}: ${issue.message}`);
+  }
+  const hasBlocking = report.issues.some((issue) => issue.severity === 'error');
+  console.log(`[pumuki] doctor verdict: ${hasBlocking ? 'BLOCKED' : 'WARN'}`);
+};
+
+export const runLifecycleCli = async (
+  argv: ReadonlyArray<string>
+): Promise<number> => {
+  try {
+    const parsed = parseLifecycleCliArgs(argv);
+
+    switch (parsed.command) {
+      case 'install': {
+        const result = runLifecycleInstall();
+        console.log(
+          `[pumuki] installed ${result.version} at ${result.repoRoot} (hooks changed: ${result.changedHooks.join(', ') || 'none'})`
+        );
+        return 0;
+      }
+      case 'uninstall': {
+        const result = runLifecycleUninstall({
+          purgeArtifacts: parsed.purgeArtifacts,
+        });
+        console.log(
+          `[pumuki] uninstalled from ${result.repoRoot} (hooks changed: ${result.changedHooks.join(', ') || 'none'})`
+        );
+        if (parsed.purgeArtifacts) {
+          console.log(
+            `[pumuki] removed artifacts: ${result.removedArtifacts.join(', ') || 'none'}`
+          );
+        }
+        return 0;
+      }
+      case 'remove': {
+        const result = runLifecycleRemove();
+        console.log(
+          `[pumuki] removed from ${result.repoRoot} (package removed: ${result.packageRemoved ? 'yes' : 'no'}, hooks changed: ${result.changedHooks.join(', ') || 'none'})`
+        );
+        console.log(
+          `[pumuki] removed artifacts: ${result.removedArtifacts.join(', ') || 'none'}`
+        );
+        return 0;
+      }
+      case 'update': {
+        const result = runLifecycleUpdate({
+          targetSpec: parsed.updateSpec,
+        });
+        console.log(
+          `[pumuki] updated to ${result.targetSpec} at ${result.repoRoot} (hooks changed: ${result.reinstallHooksChanged.join(', ') || 'none'})`
+        );
+        return 0;
+      }
+      case 'doctor': {
+        const report = runLifecycleDoctor();
+        printDoctorReport(report);
+        return report.issues.some((issue) => issue.severity === 'error') ? 1 : 0;
+      }
+      case 'status': {
+        const status = readLifecycleStatus();
+        console.log(`[pumuki] repo: ${status.repoRoot}`);
+        console.log(`[pumuki] package version: ${status.packageVersion}`);
+        console.log(`[pumuki] lifecycle installed: ${status.lifecycleState.installed ?? 'false'}`);
+        console.log(`[pumuki] lifecycle version: ${status.lifecycleState.version ?? 'unknown'}`);
+        console.log(
+          `[pumuki] hooks: pre-commit=${status.hookStatus['pre-commit'].managedBlockPresent ? 'managed' : 'missing'}, pre-push=${status.hookStatus['pre-push'].managedBlockPresent ? 'managed' : 'missing'}`
+        );
+        console.log(
+          `[pumuki] tracked node_modules paths: ${status.trackedNodeModulesCount}`
+        );
+        return 0;
+      }
+      default:
+        return 1;
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unexpected lifecycle CLI error.';
+    console.error(message);
+    return 1;
+  }
+};
+
+if (require.main === module) {
+  void runLifecycleCli(process.argv.slice(2)).then((code) => {
+    process.exit(code);
+  });
+}

package/integrations/lifecycle/constants.ts

@@ -0,0 +1,13 @@
+export const PUMUKI_MANAGED_BLOCK_START = '# >>> PUMUKI MANAGED START >>>';
+export const PUMUKI_MANAGED_BLOCK_END = '# <<< PUMUKI MANAGED END <<<';
+
+export const PUMUKI_CONFIG_KEYS = {
+  installed: 'pumuki.installed',
+  version: 'pumuki.version',
+  hooks: 'pumuki.hooks',
+  installedAt: 'pumuki.installed-at',
+} as const;
+
+export const PUMUKI_MANAGED_HOOKS = ['pre-commit', 'pre-push'] as const;
+
+export type PumukiManagedHook = (typeof PUMUKI_MANAGED_HOOKS)[number];

package/integrations/lifecycle/consumerPackage.ts

@@ -0,0 +1,48 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getCurrentPumukiPackageName } from './packageInfo';
+
+export type ConsumerDependencySource = 'dependencies' | 'devDependencies' | 'none';
+
+type ConsumerPackageJson = {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+};
+
+const readPackageJson = (repoRoot: string): ConsumerPackageJson => {
+  const path = join(repoRoot, 'package.json');
+  if (!existsSync(path)) {
+    return {};
+  }
+
+  const raw = readFileSync(path, 'utf8');
+  return JSON.parse(raw) as ConsumerPackageJson;
+};
+
+export const resolveCurrentPumukiDependency = (repoRoot: string): {
+  source: ConsumerDependencySource;
+  spec?: string;
+} => {
+  const pkg = readPackageJson(repoRoot);
+  const dependencyName = getCurrentPumukiPackageName();
+
+  const dependencySpec = pkg.dependencies?.[dependencyName];
+  if (typeof dependencySpec === 'string') {
+    return {
+      source: 'dependencies',
+      spec: dependencySpec,
+    };
+  }
+
+  const devDependencySpec = pkg.devDependencies?.[dependencyName];
+  if (typeof devDependencySpec === 'string') {
+    return {
+      source: 'devDependencies',
+      spec: devDependencySpec,
+    };
+  }
+
+  return {
+    source: 'none',
+  };
+};

package/integrations/lifecycle/doctor.ts

@@ -0,0 +1,90 @@
+import { getPumukiHooksStatus } from './hookManager';
+import { LifecycleGitService, type ILifecycleGitService } from './gitService';
+import { getCurrentPumukiVersion } from './packageInfo';
+import { readLifecycleState, type LifecycleState } from './state';
+
+export type DoctorIssueSeverity = 'warning' | 'error';
+
+export type DoctorIssue = {
+  severity: DoctorIssueSeverity;
+  message: string;
+};
+
+export type LifecycleDoctorReport = {
+  repoRoot: string;
+  packageVersion: string;
+  lifecycleState: LifecycleState;
+  trackedNodeModulesPaths: ReadonlyArray<string>;
+  hookStatus: ReturnType<typeof getPumukiHooksStatus>;
+  issues: ReadonlyArray<DoctorIssue>;
+};
+
+const buildDoctorIssues = (params: {
+  trackedNodeModulesPaths: ReadonlyArray<string>;
+  hookStatus: ReturnType<typeof getPumukiHooksStatus>;
+  lifecycleState: LifecycleState;
+}): ReadonlyArray<DoctorIssue> => {
+  const issues: DoctorIssue[] = [];
+
+  if (params.trackedNodeModulesPaths.length > 0) {
+    issues.push({
+      severity: 'error',
+      message:
+        'Tracked files under node_modules were detected. This baseline is unsafe for enterprise install/uninstall lifecycle.',
+    });
+  }
+
+  if (
+    params.lifecycleState.installed === 'true' &&
+    !Object.values(params.hookStatus).every((entry) => entry.managedBlockPresent)
+  ) {
+    issues.push({
+      severity: 'warning',
+      message:
+        'Lifecycle state says installed=true but one or more managed hook blocks are missing.',
+    });
+  }
+
+  if (
+    params.lifecycleState.installed !== 'true' &&
+    Object.values(params.hookStatus).some((entry) => entry.managedBlockPresent)
+  ) {
+    issues.push({
+      severity: 'warning',
+      message:
+        'Managed hook blocks exist but lifecycle state is not marked as installed.',
+    });
+  }
+
+  return issues;
+};
+
+export const runLifecycleDoctor = (params?: {
+  cwd?: string;
+  git?: ILifecycleGitService;
+}): LifecycleDoctorReport => {
+  const git = params?.git ?? new LifecycleGitService();
+  const cwd = params?.cwd ?? process.cwd();
+  const repoRoot = git.resolveRepoRoot(cwd);
+  const trackedNodeModulesPaths = git.listTrackedNodeModulesPaths(repoRoot);
+  const hookStatus = getPumukiHooksStatus(repoRoot);
+  const lifecycleState = readLifecycleState(git, repoRoot);
+
+  const issues = buildDoctorIssues({
+    trackedNodeModulesPaths,
+    hookStatus,
+    lifecycleState,
+  });
+
+  return {
+    repoRoot,
+    packageVersion: getCurrentPumukiVersion(),
+    lifecycleState,
+    trackedNodeModulesPaths,
+    hookStatus,
+    issues,
+  };
+};
+
+export const doctorHasBlockingIssues = (report: LifecycleDoctorReport): boolean =>
+  report.issues.some((issue) => issue.severity === 'error');

package/integrations/lifecycle/gitService.ts

@@ -0,0 +1,63 @@
+import { execFileSync } from 'node:child_process';
+
+export interface ILifecycleGitService {
+  runGit(args: ReadonlyArray<string>, cwd: string): string;
+  resolveRepoRoot(cwd: string): string;
+  getStatusShort(cwd: string): string;
+  listTrackedNodeModulesPaths(cwd: string): ReadonlyArray<string>;
+  isPathTracked(cwd: string, path: string): boolean;
+  setLocalConfig(cwd: string, key: string, value: string): void;
+  unsetLocalConfig(cwd: string, key: string): void;
+  getLocalConfig(cwd: string, key: string): string | undefined;
+}
+
+const splitNonEmptyLines = (value: string): ReadonlyArray<string> =>
+  value
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+
+export class LifecycleGitService implements ILifecycleGitService {
+  runGit(args: ReadonlyArray<string>, cwd: string): string {
+    return execFileSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+    });
+  }
+
+  resolveRepoRoot(cwd: string): string {
+    return this.runGit(['rev-parse', '--show-toplevel'], cwd).trim();
+  }
+
+  getStatusShort(cwd: string): string {
+    return this.runGit(['status', '--short'], cwd);
+  }
+
+  listTrackedNodeModulesPaths(cwd: string): ReadonlyArray<string> {
+    const output = this.runGit(['ls-files', '--', 'node_modules', 'node_modules/**'], cwd);
+    return splitNonEmptyLines(output);
+  }
+
+  isPathTracked(cwd: string, path: string): boolean {
+    const output = this.runGit(['ls-files', '--', path], cwd);
+    return splitNonEmptyLines(output).includes(path);
+  }
+
+  setLocalConfig(cwd: string, key: string, value: string): void {
+    this.runGit(['config', '--local', key, value], cwd);
+  }
+
+  unsetLocalConfig(cwd: string, key: string): void {
+    try {
+      this.runGit(['config', '--local', '--unset', key], cwd);
+    } catch {}
+  }
+
+  getLocalConfig(cwd: string, key: string): string | undefined {
+    try {
+      return this.runGit(['config', '--local', '--get', key], cwd).trim();
+    } catch {
+      return undefined;
+    }
+  }
+}

package/integrations/lifecycle/hookBlock.ts

@@ -0,0 +1,93 @@
+import {
+  PUMUKI_MANAGED_BLOCK_END,
+  PUMUKI_MANAGED_BLOCK_START,
+  type PumukiManagedHook,
+} from './constants';
+
+const HOOK_COMMANDS: Record<PumukiManagedHook, string> = {
+  'pre-commit': 'pumuki-pre-commit',
+  'pre-push': 'pumuki-pre-push',
+};
+
+const trimTrailingWhitespace = (value: string): string =>
+  value.replace(/[ \t]+\n/g, '\n').trimEnd();
+
+export const hasPumukiManagedBlock = (contents: string): boolean =>
+  contents.includes(PUMUKI_MANAGED_BLOCK_START) &&
+  contents.includes(PUMUKI_MANAGED_BLOCK_END);
+
+const managedBlockPattern = new RegExp(
+  `${PUMUKI_MANAGED_BLOCK_START}[\\s\\S]*?${PUMUKI_MANAGED_BLOCK_END}\\n?`,
+  'g'
+);
+
+export const buildPumukiManagedHookBlock = (hook: PumukiManagedHook): string => {
+  const cli = HOOK_COMMANDS[hook];
+
+  return [
+    PUMUKI_MANAGED_BLOCK_START,
+    'if command -v npx >/dev/null 2>&1; then',
+    `  npx --yes ${cli}`,
+    '  status=$?',
+    '  if [ "$status" -ne 0 ]; then',
+    '    exit "$status"',
+    '  fi',
+    'else',
+    '  echo "[pumuki] npx was not found in PATH." >&2',
+    '  exit 1',
+    'fi',
+    PUMUKI_MANAGED_BLOCK_END,
+  ].join('\n');
+};
+
+const ensureExecutableHeader = (contents: string): string => {
+  const normalized = contents.trim();
+  if (normalized.length === 0) {
+    return '#!/usr/bin/env sh';
+  }
+  return contents;
+};
+
+export const upsertPumukiManagedBlock = (params: {
+  contents: string;
+  hook: PumukiManagedHook;
+}): string => {
+  const block = buildPumukiManagedHookBlock(params.hook);
+  const baseline = ensureExecutableHeader(params.contents);
+
+  if (hasPumukiManagedBlock(baseline)) {
+    const replaced = baseline.replace(managedBlockPattern, `${block}\n`);
+    return `${trimTrailingWhitespace(replaced)}\n`;
+  }
+
+  const withSeparator =
+    trimTrailingWhitespace(baseline).length > 0
+      ? `${trimTrailingWhitespace(baseline)}\n\n${block}`
+      : block;
+  return `${withSeparator}\n`;
+};
+
+export const removePumukiManagedBlock = (contents: string): {
+  updated: string;
+  removed: boolean;
+} => {
+  if (!hasPumukiManagedBlock(contents)) {
+    return {
+      updated: contents,
+      removed: false,
+    };
+  }
+
+  const stripped = trimTrailingWhitespace(contents.replace(managedBlockPattern, '\n\n'));
+  if (stripped === '' || stripped === '#!/usr/bin/env sh') {
+    return {
+      updated: '',
+      removed: true,
+    };
+  }
+
+  return {
+    updated: `${stripped}\n`,
+    removed: true,
+  };
+};