fix: address all 5 bugs plus design/feature improvements across engine and shared packages

Co-authored-by: connortessaro <116526628+connortessaro@users.noreply.github.com>
Agent-Logs-Url: https://github.com/connortessaro/shopify-web-replicator/sessions/c23ba258-cfae-4305-bc3f-445838cf5c17

Author: Copilot

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

@@ -153,7 +153,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

@@ -556,4 +556,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,13 +1,8 @@
 import type {
   AppRuntimeConfig,
-  PageType,
-  ReferenceAnalysis,
   ReferenceIntake,
   ReplicationJob,
-  ReplicationJobSummary,
-  StoreSetupPlan,
-  ThemeCheckResult,
-  ThemeMapping
+  ReplicationJobSummary
 } from "@shopify-web-replicator/shared";
 import { createReplicationJob } from "@shopify-web-replicator/shared";
 
@@ -22,64 +17,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";
-
-type Analyzer = {
-  analyze(input: { referenceUrl: string; pageType?: PageType; notes?: string }): Promise<ReferenceAnalysis>;
-};
-
-type Mapper = {
-  map(input: { analysis: ReferenceAnalysis; referenceUrl: string; notes?: string }): Promise<ThemeMapping>;
-};
-
-type Generator = {
-  generate(input: {
-    analysis: ReferenceAnalysis;
-    mapping: ThemeMapping;
-  }): Promise<{
-    artifacts: ReplicationJob["artifacts"];
-    generation: NonNullable<ReplicationJob["generation"]>;
-  }>;
-};
-
-type StoreSetupGenerator = {
-  generate(input: {
-    analysis: ReferenceAnalysis;
-    mapping: ThemeMapping;
-  }): Promise<{
-    artifact: ReplicationJob["artifacts"][number];
-    storeSetup: StoreSetupPlan;
-  }>;
-};
-
-type CommerceGenerator = {
-  generate(input: {
-    analysis: ReferenceAnalysis;
-    mapping: ThemeMapping;
-    storeSetup: StoreSetupPlan;
-  }): Promise<{
-    artifact: ReplicationJob["artifacts"][number];
-    commerce: NonNullable<ReplicationJob["commerce"]>;
-  }>;
-};
-
-type IntegrationGenerator = {
-  generate(input: {
-    analysis: ReferenceAnalysis;
-    mapping: ThemeMapping;
-    generation: NonNullable<ReplicationJob["generation"]>;
-    storeSetup: StoreSetupPlan;
-    commerce: NonNullable<ReplicationJob["commerce"]>;
-    artifacts: ReplicationJob["artifacts"];
-    validation: ThemeCheckResult;
-  }): Promise<{
-    artifact: ReplicationJob["artifacts"][number];
-    integration: NonNullable<ReplicationJob["integration"]>;
-  }>;
-};
-
-type ThemeValidator = {
-  validate(): Promise<ThemeCheckResult>;
-};
+import type { Analyzer, CommerceGenerator, Generator, IntegrationGenerator, Mapper, StoreSetupGenerator, ThemeValidator } from "./services/types.js";
 
 export interface ReplicationHandoff {
   job: ReplicationJob;
@@ -169,6 +107,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

@@ -225,25 +225,25 @@ export class ShopifyIntegrationReportGenerator {
       outputPath,
       `${JSON.stringify(
         {
-          generated_by: "Shopify Web Replicator",
-          checked_at: checkedAt,
-          source_url: analysis.sourceUrl,
-          page_type: analysis.pageType,
+          generatedBy: "Shopify Web Replicator",
+          checkedAt: checkedAt,
+          sourceUrl: analysis.sourceUrl,
+          pageType: analysis.pageType,
           title: analysis.title,
           summary: integration.summary,
-          mapping_summary: mapping.summary,
-          section_path: generation.sectionPath,
-          template_path: generation.templatePath,
-          store_setup_config_path: storeSetup.configPath,
-          commerce_snippet_path: commerce.snippetPath,
-          generated_artifacts: artifacts.map((artifact) => ({
+          mappingSummary: mapping.summary,
+          sectionPath: generation.sectionPath,
+          templatePath: generation.templatePath,
+          storeSetupConfigPath: storeSetup.configPath,
+          commerceSnippetPath: commerce.snippetPath,
+          generatedArtifacts: artifacts.map((artifact) => ({
             kind: artifact.kind,
             path: artifact.path,
             status: artifact.status,
             description: artifact.description,
-            last_written_at: artifact.lastWrittenAt
+            lastWrittenAt: artifact.lastWrittenAt
           })),
-          commerce_entrypoints: commerce.entrypoints,
+          commerceEntrypoints: commerce.entrypoints,
           validation,
           checks
         },