Merge branch 'main' of github.com:connortessaro/shopify-web-replicator

Author: connortessaro

GEMINI.md

@@ -0,0 +1,41 @@
+# GEMINI.md
+
+## Project Context
+Shopify Web Replicator is a monorepo containing a replication engine, an MCP server, a companion API, and a React frontend. It automates the replication of Shopify storefronts into a local theme workspace.
+
+## Critical Mandates
+- **Build Order:** You MUST build packages in the following order: `packages/shared` → `packages/engine` → `apps/api` | `apps/web` | `apps/mcp`.
+- **Logic Duplication:** `apps/api/src/services/` contains intentional duplicates of services in `packages/engine`. When modifying engine logic, you MUST check if the corresponding service in `apps/api` needs mirroring.
+- **Stable Artifacts:** Never change the filenames of generated artifacts defined as constants in `packages/shared/src/job.ts`.
+- **Preflight Checks:** The MCP server (`apps/mcp`) runs preflight checks on every tool call. Ensure any new dependencies or system requirements are added to `runtime-preflight.ts`.
+
+## Development Workflows
+
+### Build & Verify
+- **Full Verification:** `pnpm build && pnpm test && pnpm typecheck && pnpm theme:check`
+- **Install:** `pnpm install --frozen-lockfile --ignore-scripts`
+- **Build All:** `pnpm build`
+- **Type-check:** `pnpm typecheck`
+- **Theme Linting:** `pnpm theme:check`
+
+### Testing
+- **Run All Tests:** `pnpm test`
+- **Package Specific:** `pnpm --filter <package-name> test` (e.g., `@shopify-web-replicator/engine`)
+- **Single File:** `pnpm --filter <package-name> exec vitest run <path-to-test>`
+
+### Local Execution
+- **Dev Mode:** `pnpm dev` (starts watchers and servers in parallel)
+- **Database:** SQLite is used, located at `.data/replicator.db` by default.
+
+## Architectural Patterns
+- **Services:** All services depend on interfaces in `src/services/types.ts` to allow for easy testing with doubles.
+- **Persistence:** `SqliteJobRepository` handles job state persistence after each pipeline stage.
+- **Pipeline:** Deterministic sequence: `intake` → `analysis` → `mapping` → `theme_generation` → `store_setup` → `commerce_wiring` → `validation` → `integration_check` → `review`.
+
+## Environment Variables
+| Variable | Default | Purpose |
+|---|---|---|
+| `REPLICATOR_DB_PATH` | `.data/replicator.db` | SQLite database path |
+| `THEME_WORKSPACE_PATH` | `packages/theme-workspace` | Target Shopify theme directory |
+| `REPLICATOR_CAPTURE_ROOT` | `.data/captures` | Playwright capture storage |
+| `PORT` | `8787` | API server port |

apps/api/src/services/integration-report-generator.test.ts

@@ -154,7 +154,7 @@ describe("ShopifyIntegrationReportGenerator", () => {
       summary: "All deterministic integration checks passed for Example Storefront."
     });
     await expect(readFile(join(themeRoot, "config/generated-integration-report.json"), "utf8")).resolves.toContain(
-      "\"generated_artifacts\""
+      "\"generatedArtifacts\""
     );
   });
 

apps/api/src/services/replication-pipeline.test.ts

@@ -83,8 +83,12 @@ describe("ReplicationPipeline", () => {
 
     const repository = new SqliteJobRepository(join(dataRoot, "replicator.db"));
     const job = createReplicationJob({
+<<<<<<< HEAD
       referenceUrl: "https://example.com",
       destinationStore: "local-dev-store",
+=======
+      referenceUrl: "https://example.com/offer",
+>>>>>>> 0ff837ae2df3782ab4b72a9b6d93d92b7f7d8110
       notes: "Landing page MVP"
     });
 
@@ -246,7 +250,7 @@ describe("ReplicationPipeline", () => {
       readFile(join(themeRoot, "templates/page.generated-reference.json"), "utf8")
     ).resolves.toContain('"type": "generated-reference"');
     await expect(readFile(join(themeRoot, "config/generated-store-setup.json"), "utf8")).resolves.toContain(
-      "\"example-storefront\""
+      "\"example-heading\""
     );
     await expect(readFile(join(themeRoot, "snippets/generated-commerce-wiring.liquid"), "utf8")).resolves.toContain(
       "/checkout"
@@ -750,4 +754,84 @@ describe("ReplicationPipeline", () => {
       ])
     });
   });
+
+  it("still writes the integration report when validation fails (Bug 3)", async () => {
+    const dataRoot = await mkdtemp(join(tmpdir(), "shopify-web-replicator-jobs-"));
+    const themeRoot = await mkdtemp(join(tmpdir(), "shopify-web-replicator-theme-"));
+    tempDirectories.push(dataRoot, themeRoot);
+
+    const repository = new SqliteJobRepository(join(dataRoot, "replicator.db"));
+    const job = createReplicationJob({
+      referenceUrl: "https://example.com",
+      notes: "Landing page MVP"
+    });
+
+    await repository.save(job);
+
+    const pipeline = new ReplicationPipeline({
+      repository,
+      analyzer: {
+        async analyze({ referenceUrl, notes }) {
+          return {
+            sourceUrl: referenceUrl,
+            pageType: "landing_page",
+            title: "Example Storefront",
+            summary: notes
+              ? `Prepared deterministic analysis for Example Storefront. Operator notes: ${notes}`
+              : "Prepared deterministic analysis for Example Storefront.",
+            analyzedAt: "2026-03-20T12:01:00.000Z",
+            recommendedSections: ["hero", "cta"]
+          } satisfies ReferenceAnalysis;
+        }
+      },
+      mapper: {
+        async map({ analysis, referenceUrl, notes }) {
+          return {
+            sourceUrl: referenceUrl,
+            title: analysis.title,
+            summary: notes
+              ? `Mapped ${analysis.title} into the stable generated reference section. Operator notes: ${notes}`
+              : `Mapped ${analysis.title} into the stable generated reference section.`,
+            mappedAt: "2026-03-20T12:02:00.000Z",
+            templatePath: "templates/page.generated-reference.json",
+            sectionPath: "sections/generated-reference.liquid",
+            sections: [
+              {
+                id: "hero-1",
+                type: "hero",
+                heading: "Example heading",
+                body: "Example body copy",
+                ctaLabel: "Review generated output",
+                ctaHref: "/pages/generated-reference"
+              }
+            ]
+          } satisfies ThemeMapping;
+        }
+      },
+      generator: new ShopifyThemeGenerator(themeRoot),
+      storeSetupGenerator: new ShopifyStoreSetupGenerator(themeRoot),
+      commerceGenerator: new ShopifyCommerceWiringGenerator(themeRoot),
+      integrationGenerator: new ShopifyIntegrationReportGenerator(themeRoot),
+      themeValidator: {
+        async validate() {
+          return {
+            status: "failed",
+            summary: "Theme check failed: missing required liquid tag.",
+            checkedAt: "2026-03-20T12:03:00.000Z"
+          } satisfies ThemeCheckResult;
+        }
+      }
+    });
+
+    await pipeline.process(job.id);
+
+    const savedJob = await repository.getById(job.id);
+
+    expect(savedJob?.status).toBe("failed");
+    expect(savedJob?.integration).toBeDefined();
+
+    await expect(
+      readFile(join(themeRoot, "config/generated-integration-report.json"), "utf8")
+    ).resolves.toContain("\"commerce_snippet_reference\"");
+  });
 });

apps/api/src/services/theme-generator.test.ts

@@ -84,6 +84,9 @@ describe("ShopifyThemeGenerator", () => {
     await expect(readFile(join(themeRoot, "templates/page.generated-reference.json"), "utf8")).resolves.toContain(
       '"type": "generated-reference"'
     );
+    await expect(readFile(join(themeRoot, "templates/page.generated-reference.json"), "utf8")).resolves.not.toContain(
+      '"mapping_summary"'
+    );
   });
 
   it("writes product-page outputs with a product form into product-specific stable files", async () => {
@@ -242,4 +245,102 @@ describe("ShopifyThemeGenerator", () => {
       '"type": "generated-reference"'
     );
   });
+
+  it("guards the product-page eyebrow with a blank check, includes a product image, and omits mapping_summary", async () => {
+    const themeRoot = await mkdtemp(join(tmpdir(), "shopify-web-replicator-theme-"));
+    tempDirectories.push(themeRoot);
+
+    const generator = new ShopifyThemeGenerator(themeRoot);
+    const analysis: ReferenceAnalysis = {
+      sourceUrl: "https://example.com/products/trail-pack",
+      referenceHost: "example.com",
+      pageType: "product_page",
+      title: "Trail Pack",
+      summary: "Product page summary.",
+      analyzedAt: "2026-03-20T12:00:00.000Z",
+      recommendedSections: ["product_detail"]
+    };
+    const mapping: ThemeMapping = {
+      sourceUrl: "https://example.com/products/trail-pack",
+      title: "Trail Pack",
+      summary: "Product mapping summary.",
+      mappedAt: "2026-03-20T12:01:00.000Z",
+      templatePath: "templates/product.generated-reference.json",
+      sectionPath: "sections/generated-product-reference.liquid",
+      sections: [
+        {
+          id: "product-hero-1",
+          type: "product_detail",
+          heading: "Trail Pack",
+          body: "Durable pack copy",
+          ctaLabel: "Add to cart",
+          ctaHref: "/cart"
+        }
+      ]
+    };
+
+    await generator.generate({ analysis, mapping });
+
+    const sectionContent = await readFile(join(themeRoot, "sections/generated-product-reference.liquid"), "utf8");
+    const templateContent = await readFile(join(themeRoot, "templates/product.generated-reference.json"), "utf8");
+
+    // Bug 4 fix: eyebrow is wrapped in a blank check
+    expect(sectionContent).toContain("{% if section.settings.eyebrow != blank %}");
+
+    // Feature 2 fix: product image is rendered
+    expect(sectionContent).toContain("product.featured_image");
+
+    // Feature 1 fix: mapping_summary is absent from section HTML and schema settings
+    expect(sectionContent).not.toContain("section.settings.mapping_summary");
+    expect(sectionContent).not.toContain('"mapping_summary"');
+
+    // Feature 1 fix: mapping_summary is absent from the template JSON
+    expect(templateContent).not.toContain('"mapping_summary"');
+  });
+
+  it("renders collection-page product cards as linked <a> elements and omits mapping_summary", async () => {
+    const themeRoot = await mkdtemp(join(tmpdir(), "shopify-web-replicator-theme-"));
+    tempDirectories.push(themeRoot);
+
+    const generator = new ShopifyThemeGenerator(themeRoot);
+    const analysis: ReferenceAnalysis = {
+      sourceUrl: "https://example.com/collections/summer-gear",
+      referenceHost: "example.com",
+      pageType: "collection_page",
+      title: "Summer Gear",
+      summary: "Collection page summary.",
+      analyzedAt: "2026-03-20T12:00:00.000Z",
+      recommendedSections: ["collection_grid"]
+    };
+    const mapping: ThemeMapping = {
+      sourceUrl: "https://example.com/collections/summer-gear",
+      title: "Summer Gear",
+      summary: "Collection mapping summary.",
+      mappedAt: "2026-03-20T12:01:00.000Z",
+      templatePath: "templates/collection.generated-reference.json",
+      sectionPath: "sections/generated-collection-reference.liquid",
+      sections: [
+        {
+          id: "collection-1",
+          type: "collection_grid",
+          heading: "Summer Gear",
+          body: "Collection copy"
+        }
+      ]
+    };
+
+    await generator.generate({ analysis, mapping });
+
+    const sectionContent = await readFile(join(themeRoot, "sections/generated-collection-reference.liquid"), "utf8");
+    const templateContent = await readFile(join(themeRoot, "templates/collection.generated-reference.json"), "utf8");
+
+    // Bug 5 fix: cards use <a href="{{ product.url }}"> instead of <article>
+    expect(sectionContent).toContain('<a class="generated-collection-reference__card" href="{{ product.url }}">');
+    expect(sectionContent).not.toContain("<article");
+
+    // Feature 1 fix: mapping_summary is absent from section HTML, schema settings, and template JSON
+    expect(sectionContent).not.toContain("section.settings.mapping_summary");
+    expect(sectionContent).not.toContain('"mapping_summary"');
+    expect(templateContent).not.toContain('"mapping_summary"');
+  });
 });

packages/engine/src/orchestrator.ts

@@ -1,6 +1,9 @@
 import type {
   AppRuntimeConfig,
+<<<<<<< HEAD
   DestinationStoreProfile,
+=======
+>>>>>>> 0ff837ae2df3782ab4b72a9b6d93d92b7f7d8110
   ReferenceIntake,
   ReplicationJob,
   ReplicationJobSummary
@@ -24,6 +27,7 @@ import { ShopifyStoreSetupGenerator } from "./services/store-setup-generator.js"
 import { DeterministicThemeMapper } from "./services/theme-mapper.js";
 import { ShopifyThemeGenerator } from "./services/theme-generator.js";
 import { ShopifyThemeValidator } from "./services/theme-validator.js";
+<<<<<<< HEAD
 import type {
   AdminReplicationService,
   Analyzer,
@@ -40,6 +44,9 @@ import type {
   StoreSetupGenerator,
   ThemeValidator
 } from "./services/types.js";
+=======
+import type { Analyzer, CommerceGenerator, Generator, IntegrationGenerator, Mapper, StoreSetupGenerator, ThemeValidator } from "./services/types.js";
+>>>>>>> 0ff837ae2df3782ab4b72a9b6d93d92b7f7d8110
 
 export interface ReplicationHandoff {
   job: ReplicationJob;
@@ -155,6 +162,50 @@ export class ReplicationOrchestrator {
     return job;
   }
 
+  async retryJob(jobId: string): Promise<ReplicationHandoff> {
+    const job = await this.repository.getById(jobId);
+
+    if (!job) {
+      throw new Error(`Missing job ${jobId}`);
+    }
+
+    if (job.status !== "failed") {
+      throw new Error(`Job ${jobId} is not in a failed state`);
+    }
+
+    for (const stage of job.stages) {
+      if (stage.status === "failed") {
+        stage.status = "pending";
+        delete stage.errorMessage;
+        delete stage.summary;
+      }
+    }
+
+    const firstPendingStage = job.stages.find((stage) => stage.status === "pending");
+    if (firstPendingStage) {
+      firstPendingStage.status = "current";
+      job.currentStage = firstPendingStage.name;
+    }
+
+    job.status = "in_progress";
+    delete job.error;
+
+    job.artifacts = job.artifacts.map((artifact) =>
+      artifact.status === "failed" ? { ...artifact, status: "pending" } : artifact
+    );
+
+    job.updatedAt = new Date().toISOString();
+    await this.repository.save(job);
+
+    const updatedJob = await this.runJob(jobId);
+
+    return {
+      job: updatedJob,
+      runtime: this.#runtime,
+      nextActions: buildNextActions(updatedJob)
+    };
+  }
+
   async replicateStorefront(intake: ReferenceIntake): Promise<ReplicationHandoff> {
     const created = await this.createJob(intake);
     const job = await this.runJob(created.jobId);

packages/engine/src/services/integration-report-generator.ts

@@ -226,7 +226,11 @@ export class ShopifyIntegrationReportGenerator {
       `${JSON.stringify(
         {
           generatedBy: "Shopify Web Replicator",
+<<<<<<< HEAD
           checkedAt,
+=======
+          checkedAt: checkedAt,
+>>>>>>> 0ff837ae2df3782ab4b72a9b6d93d92b7f7d8110
           sourceUrl: analysis.sourceUrl,
           pageType: analysis.pageType,
           title: analysis.title,