@geminix/gxpm 0.1.0

package/core/preset-system/preset-resolver.ts

@@ -0,0 +1,221 @@
+// PRESET RESOLVER — Override > Preset > Core three-layer resolution.
+// Supports replace / prepend / append / wrap composition strategies.
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+export type CompositionStrategy = "replace" | "prepend" | "append" | "wrap";
+
+export interface CompositionRule {
+  /** Target file path, relative to project root (e.g. "skills/gxpm/SKILL.md"). */
+  target: string;
+  /** How to compose the source into the target. */
+  strategy: CompositionStrategy;
+  /** Source file path, relative to the preset directory. */
+  source: string;
+  /** Optional anchor marker for prepend/append/wrap positioning. */
+  anchor?: string;
+}
+
+export interface PresetManifest {
+  id: string;
+  name: string;
+  version: string;
+  description?: string;
+  /** IDs of presets this one extends (lower priority). */
+  extends?: string[];
+  /** Composition rules for this preset. */
+  rules: CompositionRule[];
+}
+
+export interface PresetRegistry {
+  /** Ordered list of active preset IDs (highest priority first). */
+  active: string[];
+}
+
+export interface ResolveResult {
+  content: string;
+  /** Which layer provided the final content. */
+  source: "override" | "preset" | "core";
+  /** Preset IDs that contributed (empty for override/core). */
+  appliedPresets: string[];
+}
+
+const PRESET_REGISTRY_FILE = ".registry";
+const MANIFEST_FILE = "manifest.json";
+
+export class PresetResolver {
+  private presets = new Map<string, PresetManifest>();
+  private registry: PresetRegistry = { active: [] };
+
+  constructor(private projectRoot: string) {}
+
+  /** Load the preset registry and all active preset manifests. */
+  load(): void {
+    this.presets.clear();
+    this.loadRegistry();
+    for (const presetId of this.registry.active) {
+      this.loadPreset(presetId);
+    }
+  }
+
+  /**
+   * Resolve the final content for a target path.
+   *
+   * Priority: Override > Preset > Core
+   *
+   * @param targetPath — file path relative to project root
+   * @param baseContent — core-layer content (e.g. template-generated output)
+   * @returns resolved content and metadata, or null if no content found
+   */
+  resolve(targetPath: string, baseContent?: string): ResolveResult | null {
+    const normalized = targetPath.replace(/^\//, "");
+
+    // 1. Override layer (highest priority)
+    const overridePath = join(this.projectRoot, ".gxpm", "overrides", normalized);
+    if (existsSync(overridePath)) {
+      return {
+        content: readFileSync(overridePath, "utf8"),
+        source: "override",
+        appliedPresets: [],
+      };
+    }
+
+    // 2. Preset layer (middle priority)
+    let content = baseContent ?? "";
+    let presetApplied = false;
+    const appliedPresets: string[] = [];
+
+    for (const presetId of this.registry.active) {
+      const preset = this.presets.get(presetId);
+      if (!preset) continue;
+
+      const rules = preset.rules.filter((r) => this.matchTarget(r.target, normalized));
+      if (rules.length === 0) continue;
+
+      for (const rule of rules) {
+        const sourcePath = join(this.presetDir, presetId, rule.source);
+        if (!existsSync(sourcePath)) continue;
+        const sourceContent = readFileSync(sourcePath, "utf8");
+        content = this.applyStrategy(content, sourceContent, rule.strategy, rule.anchor);
+        presetApplied = true;
+      }
+
+      appliedPresets.push(presetId);
+    }
+
+    if (presetApplied) {
+      return { content, source: "preset", appliedPresets };
+    }
+
+    // 3. Core layer (lowest priority)
+    if (baseContent !== undefined) {
+      return { content: baseContent, source: "core", appliedPresets: [] };
+    }
+
+    // No content available at any layer
+    return null;
+  }
+
+  /** List all loaded preset IDs. */
+  listPresets(): string[] {
+    return Array.from(this.presets.keys());
+  }
+
+  /** List active preset IDs in resolution order. */
+  listActive(): string[] {
+    return [...this.registry.active];
+  }
+
+  /** Get a loaded preset manifest by ID. */
+  getPreset(id: string): PresetManifest | undefined {
+    return this.presets.get(id);
+  }
+
+  private get presetDir(): string {
+    return join(this.projectRoot, ".gxpm", "presets");
+  }
+
+  private loadRegistry(): void {
+    const registryPath = join(this.presetDir, PRESET_REGISTRY_FILE);
+    if (!existsSync(registryPath)) {
+      this.registry = { active: [] };
+      return;
+    }
+    try {
+      const raw = readFileSync(registryPath, "utf8");
+      const doc = JSON.parse(raw) as PresetRegistry;
+      this.registry = { active: doc.active ?? [] };
+    } catch {
+      this.registry = { active: [] };
+    }
+  }
+
+  private loadPreset(id: string): void {
+    const manifestPath = join(this.presetDir, id, MANIFEST_FILE);
+    if (!existsSync(manifestPath)) {
+      return;
+    }
+    try {
+      const raw = readFileSync(manifestPath, "utf8");
+      const manifest = JSON.parse(raw) as PresetManifest;
+      this.presets.set(id, manifest);
+    } catch {
+      // Silently skip malformed presets
+    }
+  }
+
+  private matchTarget(ruleTarget: string, filePath: string): boolean {
+    // Simple glob-like matching: exact match or wildcard suffix
+    if (ruleTarget === filePath) return true;
+    if (ruleTarget.endsWith("/*")) {
+      const prefix = ruleTarget.slice(0, -1);
+      return filePath.startsWith(prefix);
+    }
+    if (ruleTarget.includes("*")) {
+      const regex = new RegExp("^" + ruleTarget.replace(/\*/g, ".*") + "$");
+      return regex.test(filePath);
+    }
+    return false;
+  }
+
+  private applyStrategy(
+    base: string,
+    source: string,
+    strategy: CompositionStrategy,
+    anchor?: string,
+  ): string {
+    switch (strategy) {
+      case "replace":
+        return source;
+      case "prepend":
+        return anchor ? this.insertBefore(base, source, anchor) : source + "\n" + base;
+      case "append":
+        return anchor ? this.insertAfter(base, source, anchor) : base + "\n" + source;
+      case "wrap": {
+        if (anchor) {
+          const parts = base.split(anchor);
+          if (parts.length >= 2) {
+            return parts[0] + source + parts.slice(1).join(anchor);
+          }
+        }
+        return source + "\n" + base + "\n" + source;
+      }
+      default:
+        return base;
+    }
+  }
+
+  private insertBefore(base: string, source: string, anchor: string): string {
+    const idx = base.indexOf(anchor);
+    if (idx === -1) return source + "\n" + base;
+    return base.slice(0, idx) + source + "\n" + base.slice(idx);
+  }
+
+  private insertAfter(base: string, source: string, anchor: string): string {
+    const idx = base.lastIndexOf(anchor);
+    if (idx === -1) return base + "\n" + source;
+    const end = idx + anchor.length;
+    return base.slice(0, end) + "\n" + source + base.slice(end);
+  }
+}

package/core/project-init-status.ts

@@ -0,0 +1,127 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export type ProjectInitializationKind = "uninitialized" | "partial" | "initialized";
+
+export interface ProjectInitializationStatus {
+  kind: ProjectInitializationKind;
+  cwd: string | null;
+  missingMarkers: string[];
+  presentMarkers: string[];
+}
+
+export const REQUIRED_GXPM_DIRS = [
+  ".gxpm/issues",
+  ".gxpm/local",
+  ".gxpm/out-of-scope",
+  ".gxpm/wiki",
+];
+
+export const REQUIRED_GXPM_FILES = [
+  ".gxpm/config.json",
+];
+
+export const REQUIRED_GXPM_GIT_HOOKS = [
+  "gxpm-pre-commit",
+  "gxpm-commit-msg",
+  "gxpm-pre-push",
+  "gxpm-post-merge",
+  "gxpm-post-checkout",
+];
+
+export function getProjectInitializationStatus(cwd: string | null | undefined): ProjectInitializationStatus {
+  if (!cwd) {
+    return {
+      kind: "uninitialized",
+      cwd: null,
+      missingMarkers: ["cwd"],
+      presentMarkers: [],
+    };
+  }
+
+  const presentMarkers: string[] = [];
+  const missingMarkers: string[] = [];
+  const gxpmRootExists = isDirectory(join(cwd, ".gxpm"));
+
+  if (!gxpmRootExists) {
+    return {
+      kind: "uninitialized",
+      cwd,
+      missingMarkers: [".gxpm", ...REQUIRED_GXPM_DIRS, ...REQUIRED_GXPM_FILES],
+      presentMarkers,
+    };
+  }
+  presentMarkers.push(".gxpm");
+
+  for (const dir of REQUIRED_GXPM_DIRS) {
+    if (isDirectory(join(cwd, dir))) {
+      presentMarkers.push(dir);
+    } else {
+      missingMarkers.push(dir);
+    }
+  }
+
+  for (const file of REQUIRED_GXPM_FILES) {
+    if (isFile(join(cwd, file))) {
+      presentMarkers.push(file);
+    } else {
+      missingMarkers.push(file);
+    }
+  }
+
+  if (hasGitMetadata(cwd)) {
+    for (const hook of REQUIRED_GXPM_GIT_HOOKS) {
+      const marker = `.githooks/${hook}`;
+      if (isFile(join(cwd, marker))) {
+        presentMarkers.push(marker);
+      } else {
+        missingMarkers.push(marker);
+      }
+    }
+  }
+
+  return {
+    kind: missingMarkers.length === 0 ? "initialized" : "partial",
+    cwd,
+    missingMarkers,
+    presentMarkers,
+  };
+}
+
+export function formatProjectInitializationContext(status: ProjectInitializationStatus): string | null {
+  if (status.kind === "initialized") return null;
+
+  const missing = status.missingMarkers.slice(0, 8).join(", ");
+  const suffix = status.missingMarkers.length > 8 ? ", ..." : "";
+  const state =
+    status.kind === "uninitialized"
+      ? "gxpm hooks are active, but this repository has not been initialized"
+      : "gxpm initialization is incomplete";
+
+  return [
+    `${state}.`,
+    `Missing: ${missing}${suffix}.`,
+    "Run `gxpm init --target <repo>` or `gxpm doctor --fix` after reviewing existing repo hooks.",
+    "Until initialization is complete, gxpm hooks will not write plan state.",
+  ].join(" ");
+}
+
+function hasGitMetadata(cwd: string): boolean {
+  return existsSync(join(cwd, ".git"));
+}
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}

package/core/qa.ts

@@ -0,0 +1,15 @@
+import { createPhaseArtifactInitializer } from "./phase-artifact";
+
+export const initializeQaFindings = createPhaseArtifactInitializer({
+  artifactType: "qa-findings",
+  label: "QA findings",
+  payload: {
+    browserEvidence: [],
+    findings: [],
+    risks: [],
+    status: "draft",
+    summary: "",
+    verifyFindingsArtifact: "verify-findings",
+  },
+  requiredPhase: "verify",
+});

package/core/resilience.ts

@@ -0,0 +1,165 @@
+// ─── Error Classification ────────────────────────────────────────────────────
+
+export type ErrorType = "FATAL" | "TRANSIENT" | "UNKNOWN";
+
+/** Fatal error patterns — authentication/authorization/quota issues that won't resolve with retry */
+export const FATAL_PATTERNS = [
+  "unauthorized",
+  "forbidden",
+  "invalid token",
+  "authentication failed",
+  "permission denied",
+  "401",
+  "403",
+  "credit balance",
+  "auth error",
+  "insufficient credit",
+  "quota exceeded",
+] as const;
+
+/** Transient error patterns — temporary issues that may resolve with retry */
+export const TRANSIENT_PATTERNS = [
+  "timeout",
+  "econnrefused",
+  "econnreset",
+  "etimedout",
+  "rate limit",
+  "too many requests",
+  "429",
+  "503",
+  "502",
+  "network error",
+  "socket hang up",
+  "exited with code",
+  "temporarily unavailable",
+  "connection reset",
+] as const;
+
+/**
+ * Check if error message matches any pattern in the list.
+ */
+export function matchesPattern(message: string, patterns: readonly string[]): boolean {
+  return patterns.some((pattern) => message.includes(pattern));
+}
+
+/**
+ * Classify an error to determine if it's transient (can retry) or fatal (should fail).
+ * FATAL patterns take priority over TRANSIENT patterns to prevent an error message
+ * containing both from being retried.
+ */
+export function classifyError(error: Error): ErrorType {
+  const message = error.message.toLowerCase();
+
+  if (matchesPattern(message, FATAL_PATTERNS)) {
+    return "FATAL";
+  }
+  if (matchesPattern(message, TRANSIENT_PATTERNS)) {
+    return "TRANSIENT";
+  }
+  return "UNKNOWN";
+}
+
+// ─── Safe Send Message ───────────────────────────────────────────────────────
+
+export interface SafeSendMessageOptions {
+  /** Threshold for consecutive UNKNOWN errors before throwing. Default: 3 */
+  unknownThreshold?: number;
+  /** Mutable counter shared across calls to track consecutive UNKNOWN errors. */
+  unknownCounter?: { count: number };
+}
+
+export interface SafeSendMessageResult<T> {
+  ok: boolean;
+  value?: T;
+  error?: Error;
+  errorType?: ErrorType;
+  unknownCount?: number;
+}
+
+/**
+ * Execute a function with error classification and differentiated handling:
+ * - TRANSIENT errors: swallow and return { ok: false }
+ * - FATAL errors: re-throw immediately
+ * - UNKNOWN errors: track consecutive occurrences; throw only when threshold is exceeded
+ */
+export async function safeSendMessage<T>(
+  fn: () => T | Promise<T>,
+  options: SafeSendMessageOptions = {},
+): Promise<SafeSendMessageResult<T>> {
+  const threshold = options.unknownThreshold ?? 3;
+  const counter = options.unknownCounter ?? { count: 0 };
+
+  try {
+    const value = await Promise.resolve(fn());
+    counter.count = 0;
+    return { ok: true, value, unknownCount: counter.count };
+  } catch (rawError) {
+    const error = rawError instanceof Error ? rawError : new Error(String(rawError));
+    const errorType = classifyError(error);
+
+    if (errorType === "FATAL") {
+      throw error;
+    }
+
+    if (errorType === "TRANSIENT") {
+      return { ok: false, error, errorType, unknownCount: counter.count };
+    }
+
+    // UNKNOWN
+    counter.count += 1;
+    if (counter.count >= threshold) {
+      throw error;
+    }
+    return { ok: false, error, errorType, unknownCount: counter.count };
+  }
+}
+
+// ─── Retry Wrapper ───────────────────────────────────────────────────────────
+
+export interface RetryOptions {
+  /** Maximum number of retry attempts for TRANSIENT errors. Default: 2 */
+  maxRetries?: number;
+  /** Base delay in milliseconds for exponential backoff. Default: 1000 */
+  baseDelayMs?: number;
+  /** Optional callback invoked before each retry. */
+  onRetry?: (attempt: number, error: Error, delayMs: number) => void;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Execute a function with automatic retry for TRANSIENT errors only.
+ * FATAL and UNKNOWN errors fail immediately.
+ * Backoff delays: baseDelayMs * attempt (linear by default; caller can customize via onRetry).
+ */
+export async function withRetry<T>(fn: () => T | Promise<T>, options: RetryOptions = {}): Promise<T> {
+  const maxRetries = options.maxRetries ?? 2;
+  const baseDelayMs = options.baseDelayMs ?? 1000;
+
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await Promise.resolve(fn());
+    } catch (rawError) {
+      const error = rawError instanceof Error ? rawError : new Error(String(rawError));
+      lastError = error;
+      const errorType = classifyError(error);
+
+      if (errorType === "FATAL" || errorType === "UNKNOWN") {
+        throw error;
+      }
+
+      // TRANSIENT — retry if attempts remain
+      if (attempt < maxRetries) {
+        const delayMs = baseDelayMs * (attempt + 1);
+        options.onRetry?.(attempt + 1, error, delayMs);
+        await sleep(delayMs);
+      }
+    }
+  }
+
+  throw lastError ?? new Error("Retry exhausted");
+}