@geminix/gxpm 0.1.0

package/core/template-engine.ts

@@ -0,0 +1,152 @@
+/**
+ * Template Engine — Variable substitution and inter-node data flow for
+ * capability prompts and skill templates.
+ *
+ * Inspired by Archon dag-executor.ts and executor-shared.ts, but stripped
+ * of provider/platform dependencies to remain a pure string-replacement
+ * utility that gxpm capabilities can call.
+ */
+
+export interface NodeOutput {
+  state: string;
+  output: string;
+  error?: string;
+}
+
+export interface SubstitutionContext {
+  workflowId?: string;
+  userMessage?: string;
+  artifactsDir?: string;
+  baseBranch?: string;
+  docsDir?: string;
+  loopUserInput?: string;
+  rejectionReason?: string;
+  loopPrevOutput?: string;
+  issueContext?: string;
+}
+
+const CONTEXT_VAR_PATTERN = /\$CONTEXT|\$EXTERNAL_CONTEXT|\$ISSUE_CONTEXT/g;
+
+/**
+ * Substitute workflow-level variables in a template.
+ *
+ * Supported variables:
+ *   $WORKFLOW_ID, $USER_MESSAGE, $ARGUMENTS, $ARTIFACTS_DIR,
+ *   $BASE_BRANCH, $DOCS_DIR, $LOOP_USER_INPUT, $REJECTION_REASON,
+ *   $LOOP_PREV_OUTPUT, $CONTEXT, $EXTERNAL_CONTEXT, $ISSUE_CONTEXT
+ *
+ * Returns the substituted prompt and a flag indicating whether a $CONTEXT
+ * variable was present (used by buildPromptWithContext to avoid duplication).
+ */
+export function substituteWorkflowVariables(
+  template: string,
+  context: SubstitutionContext = {}
+): { prompt: string; contextSubstituted: boolean } {
+  if (!context.baseBranch && template.includes("$BASE_BRANCH")) {
+    throw new Error(
+      "No base branch could be resolved. " +
+        "Set worktree.baseBranch in .gxpm/config.json or use --from flag."
+    );
+  }
+
+  const resolvedDocsDir = context.docsDir || "docs/";
+
+  let result = template
+    .replace(/\$WORKFLOW_ID/g, context.workflowId ?? "")
+    .replace(/\$USER_MESSAGE/g, context.userMessage ?? "")
+    .replace(/\$ARGUMENTS/g, context.userMessage ?? "")
+    .replace(/\$ARTIFACTS_DIR/g, context.artifactsDir ?? "")
+    .replace(/\$BASE_BRANCH/g, context.baseBranch ?? "")
+    .replace(/\$DOCS_DIR/g, resolvedDocsDir)
+    .replace(/\$LOOP_USER_INPUT/g, context.loopUserInput ?? "")
+    .replace(/\$REJECTION_REASON/g, context.rejectionReason ?? "")
+    .replace(/\$LOOP_PREV_OUTPUT/g, context.loopPrevOutput ?? "");
+
+  const hasContextVariables = CONTEXT_VAR_PATTERN.test(result);
+
+  if (!context.issueContext && hasContextVariables) {
+    // Clear context variables when no context is provided
+  }
+
+  result = result.replace(CONTEXT_VAR_PATTERN, context.issueContext ?? "");
+
+  return {
+    prompt: result,
+    contextSubstituted: hasContextVariables && !!context.issueContext,
+  };
+}
+
+/**
+ * Build a final prompt by substituting workflow variables and optionally
+ * appending issue context when it was not already substituted inline.
+ */
+export function buildPromptWithContext(
+  template: string,
+  context: SubstitutionContext = {}
+): string {
+  const { prompt, contextSubstituted } = substituteWorkflowVariables(
+    template,
+    context
+  );
+
+  if (context.issueContext && !contextSubstituted) {
+    return prompt + "\n\n---\n\n" + context.issueContext;
+  }
+
+  return prompt;
+}
+
+/**
+ * Single-quote a string for safe inline shell use.
+ */
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * Substitute $nodeId.output and $nodeId.output.field references in a prompt.
+ *
+ * Called *after* the standard substituteWorkflowVariables pass.
+ *
+ * @param prompt - The prompt template with variable placeholders
+ * @param nodeOutputs - Map of node IDs to their outputs
+ * @param escapedForBash - When true, wraps substituted values in single quotes
+ *   so they are safe to embed in bash scripts. Set true only for bash node
+ *   script substitution; AI/command prompt substitution should use false.
+ */
+export function substituteNodeOutputRefs(
+  prompt: string,
+  nodeOutputs: Map<string, NodeOutput>,
+  escapedForBash = false
+): string {
+  return prompt.replace(
+    /\$([a-zA-Z_][a-zA-Z0-9_-]*)\.output(?:\.([a-zA-Z_][a-zA-Z0-9_]*))?/g,
+    (match, nodeId: string, field: string | undefined) => {
+      const nodeOutput = nodeOutputs.get(nodeId);
+      if (!nodeOutput) {
+        return escapedForBash ? "''" : "";
+      }
+      if (!field) {
+        return escapedForBash
+          ? shellQuote(nodeOutput.output)
+          : nodeOutput.output;
+      }
+      try {
+        const parsed = JSON.parse(nodeOutput.output) as Record<
+          string,
+          unknown
+        >;
+        const value = parsed[field];
+        if (typeof value === "string") {
+          return escapedForBash ? shellQuote(value) : value;
+        }
+        if (typeof value === "number" || typeof value === "boolean") {
+          return String(value);
+        }
+        return escapedForBash ? "''" : "";
+      } catch {
+        return escapedForBash ? "''" : "";
+      }
+    }
+  );
+}

package/core/template-resolver.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { TemplateResolver } from "./template-resolver";
+
+describe("TemplateResolver", () => {
+  let root: string;
+  let resolver: TemplateResolver;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "gxpm-template-test-"));
+    mkdirSync(join(root, ".gxpm", "overrides"), { recursive: true });
+    mkdirSync(join(root, ".gxpm", "presets"), { recursive: true });
+    mkdirSync(join(root, ".gxpm", "extensions"), { recursive: true });
+    mkdirSync(join(root, "skills", "gxpm"), { recursive: true });
+    resolver = new TemplateResolver(root);
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("resolves core layer when nothing else exists", () => {
+    resolver.load();
+    const result = resolver.resolve("skills/gxpm/SKILL.md", "core-content");
+    expect(result).not.toBeNull();
+    expect(result!.content).toBe("core-content");
+    expect(result!.source).toBe("core");
+  });
+
+  it("override layer takes highest priority", () => {
+    const overrideFile = join(root, ".gxpm", "overrides", "skills", "gxpm", "SKILL.md");
+    mkdirSync(join(root, ".gxpm", "overrides", "skills", "gxpm"), { recursive: true });
+    writeFileSync(overrideFile, "override-content");
+    resolver.load();
+    const result = resolver.resolve("skills/gxpm/SKILL.md", "core-content");
+    expect(result).not.toBeNull();
+    expect(result!.content).toBe("override-content");
+    expect(result!.source).toBe("override");
+  });
+
+  it("extension layer is applied above core", () => {
+    const extDir = join(root, ".gxpm", "extensions", "my-ext");
+    mkdirSync(extDir, { recursive: true });
+    writeFileSync(join(extDir, "manifest.json"), JSON.stringify({ id: "my-ext", name: "My Ext", version: "1.0.0" }));
+    mkdirSync(join(extDir, "skills", "gxpm"), { recursive: true });
+    writeFileSync(join(extDir, "skills", "gxpm", "SKILL.md"), "ext-content");
+    resolver.load();
+    const result = resolver.resolve("skills/gxpm/SKILL.md", "core-content");
+    expect(result).not.toBeNull();
+    expect(result!.content).toBe("ext-content");
+    expect(result!.source).toBe("extension");
+    expect(result!.appliedExtensions).toContain("my-ext");
+  });
+
+  it("returns null when no content available", () => {
+    resolver.load();
+    const result = resolver.resolve("nonexistent/file.txt");
+    expect(result).toBeNull();
+  });
+
+  it("lists loaded extensions", () => {
+    const extDir = join(root, ".gxpm", "extensions", "ext-a");
+    mkdirSync(extDir, { recursive: true });
+    writeFileSync(join(extDir, "manifest.json"), JSON.stringify({ id: "ext-a", name: "Ext A", version: "1.0.0" }));
+    resolver.load();
+    expect(resolver.listExtensions()).toContain("ext-a");
+  });
+});

package/core/template-resolver.ts

@@ -0,0 +1,156 @@
+/**
+ * Template Resolver — 4-layer priority stack.
+ *
+ * Priority: Override > Preset > Extension > Core
+ *
+ * Built on top of PresetResolver (which already handles Override > Preset > Core).
+ * This module adds the Extension layer and provides a unified resolve() API.
+ */
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { PresetResolver, type ResolveResult as PresetResolveResult } from "./preset-system/preset-resolver";
+
+export type ResolutionLayer = "override" | "preset" | "extension" | "core";
+
+export interface TemplateResolveResult {
+  content: string;
+  /** Which layer provided the final content. */
+  source: ResolutionLayer;
+  /** Preset IDs that contributed (empty for override/extension/core). */
+  appliedPresets: string[];
+  /** Extension IDs that contributed (empty for override/preset/core). */
+  appliedExtensions: string[];
+}
+
+export interface ExtensionManifest {
+  id: string;
+  name: string;
+  version: string;
+  description?: string;
+}
+
+const EXTENSION_MANIFEST_FILE = "manifest.json";
+
+export class TemplateResolver {
+  private presetResolver: PresetResolver;
+  private extensions = new Map<string, ExtensionManifest>();
+  private extensionDir: string;
+
+  constructor(private projectRoot: string) {
+    this.presetResolver = new PresetResolver(projectRoot);
+    this.extensionDir = join(projectRoot, ".gxpm", "extensions");
+  }
+
+  /** Load presets and extensions. */
+  load(): void {
+    this.presetResolver.load();
+    this.loadExtensions();
+  }
+
+  /**
+   * Resolve template content for a target path.
+   *
+   * Priority stack:
+   * 1. Override (`.gxpm/overrides/`) — highest
+   * 2. Preset (`.gxpm/presets/<id>/`)
+   * 3. Extension (`.gxpm/extensions/<id>/`)
+   * 4. Core (`skills/`, `templates/`) — lowest
+   */
+  resolve(targetPath: string, baseContent?: string): TemplateResolveResult | null {
+    const normalized = targetPath.replace(/^\//, "");
+
+    // 1. Override layer
+    const overridePath = join(this.projectRoot, ".gxpm", "overrides", normalized);
+    if (existsSync(overridePath)) {
+      return {
+        content: readFileSync(overridePath, "utf8"),
+        source: "override",
+        appliedPresets: [],
+        appliedExtensions: [],
+      };
+    }
+
+    // 2. Preset layer (reuse PresetResolver for Override > Preset > Core logic,
+    //    but we only want Preset + Core here; we handle Override above and
+    //    Extension below manually.)
+    const presetResult = this.presetResolver.resolve(normalized, baseContent);
+
+    // 3. Extension layer — applied AFTER preset but BEFORE core.
+    //    If preset already resolved, extension can further compose on top.
+    let content = presetResult?.content ?? baseContent ?? "";
+    let source: ResolutionLayer = presetResult?.source ?? "core";
+    const appliedExtensions: string[] = [];
+
+    for (const [extId, manifest] of this.extensions) {
+      const extFilePath = join(this.extensionDir, extId, normalized);
+      if (!existsSync(extFilePath)) continue;
+      const extContent = readFileSync(extFilePath, "utf8");
+      // Extension defaults to "replace" behavior for MVP.
+      // Future: support composition strategies via manifest.
+      content = extContent;
+      source = "extension";
+      appliedExtensions.push(manifest.id);
+    }
+
+    if (appliedExtensions.length > 0) {
+      return {
+        content,
+        source,
+        appliedPresets: presetResult?.appliedPresets ?? [],
+        appliedExtensions,
+      };
+    }
+
+    // If no extension applied, return whatever preset/core gave us.
+    if (presetResult) {
+      return {
+        content: presetResult.content,
+        source: presetResult.source as ResolutionLayer,
+        appliedPresets: presetResult.appliedPresets,
+        appliedExtensions: [],
+      };
+    }
+
+    // 4. Core layer — if baseContent was provided but no higher layer matched
+    if (baseContent !== undefined) {
+      return {
+        content: baseContent,
+        source: "core",
+        appliedPresets: [],
+        appliedExtensions: [],
+      };
+    }
+
+    return null;
+  }
+
+  /** List loaded extension IDs. */
+  listExtensions(): string[] {
+    return Array.from(this.extensions.keys());
+  }
+
+  /** Get a loaded extension manifest by ID. */
+  getExtension(id: string): ExtensionManifest | undefined {
+    return this.extensions.get(id);
+  }
+
+  private loadExtensions(): void {
+    this.extensions.clear();
+    if (!existsSync(this.extensionDir)) return;
+
+    const entries = readdirSync(this.extensionDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const manifestPath = join(this.extensionDir, entry.name, EXTENSION_MANIFEST_FILE);
+      if (!existsSync(manifestPath)) continue;
+      try {
+        const raw = readFileSync(manifestPath, "utf8");
+        const manifest = JSON.parse(raw) as ExtensionManifest;
+        this.extensions.set(manifest.id, manifest);
+      } catch {
+        // Silently skip malformed extensions
+      }
+    }
+  }
+}

package/core/triage.ts

@@ -0,0 +1,26 @@
+import { writeArtifact } from "./artifacts";
+
+interface TriageInput {
+  root?: string;
+  issueId: string;
+}
+
+export function initializeTriage(input: TriageInput) {
+  return writeArtifact({
+    root: input.root,
+    issueId: input.issueId,
+    type: "acceptance-contract",
+    payload: {
+      criteria: [],
+      notes: "Fill criteria during triage before planning work.",
+      status: "draft",
+      capabilities: {
+        new: [],
+        modified: [],
+        removed: [],
+      },
+      affectedCapabilities: [],
+      breaking: false,
+    },
+  });
+}

package/core/verify.ts

@@ -0,0 +1,15 @@
+import { createPhaseArtifactInitializer } from "./phase-artifact";
+
+export const initializeVerifyFindings = createPhaseArtifactInitializer({
+  artifactType: "verify-findings",
+  label: "Verify findings",
+  payload: {
+    acceptanceContractArtifact: "acceptance-contract",
+    findings: [],
+    prCheckArtifact: "pr-check",
+    risks: [],
+    status: "draft",
+    summary: "",
+  },
+  requiredPhase: "pr-check",
+});