@thinkwise/testwise 0.2.67 → 0.2.99

package/Testwise.ts

@@ -9,6 +9,41 @@ import type { Test } from './types/Test.js';
 
 export * from '@playwright/test';
 
+/**
+ * The main entry point for the Testwise library.
+ *
+ * **What to import:** Consumer projects import `test` (and optionally
+ * `bddTest`) from `@thinkwise/testwise` instead of from `@playwright/test`.
+ * This gives you a fully-extended fixture with all Testwise capabilities
+ * already wired up:
+ *
+ * ```ts
+ * import { test, expect } from '@thinkwise/testwise';
+ *
+ * test('create employee', async ({ page }) => {
+ *   await page.logIn();
+ *   const emp = await page.subject.EmployeeEditable1Main.goTo();
+ *   await emp.form.firstNameField.fill('Jane');
+ *   await emp.actionBar.save();
+ *   await expect(page.components.snackBar.message).toBeVisible();
+ * });
+ * ```
+ *
+ * **What `test` adds on top of Playwright base:**
+ *
+ * | Layer | What it adds |
+ * |---|---|
+ * | `ClickOverride` / `FillOverride` | Patches `page.click` and `page.fill` to wait for XHR idle after each action |
+ * | `Components` | `page.components` — global Thinkwise UI component instances |
+ * | `GoToDeepLink` | `page.goToDeepLink(path)` — deep-link navigation |
+ * | `LoginFeatures` | `page.logIn()` / `page.logOut()` etc. |
+ * | `UserSimulation` | `page.simulate.*` — keyboard/mouse helpers |
+ * | `WaitEventHandler` | `page.waitEvent(url)` — waits for specific response URLs |
+ * | `SubjectRegistry` | `page.subject.*` — access to all generated subject classes |
+ *
+ * Use `bddTest` instead of `test` when combining Testwise with `playwright-bdd`
+ * step definitions.
+ */
 function combineExtensions(baseTest: Test, ...extensions: { new (test: Test): { test: Test } }[]) {
   return extensions.reduce((test, Extension) => new Extension(test).test, baseTest);
 }

package/artifact-builder/ArtifactManager.ts

@@ -1,16 +1,39 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { PipelinePaths } from './helpers/PipelinePaths.js';
 
+/**
+ * Manages backup and restore of the `test-artifacts/` directory to protect
+ * against failed or partial pipeline runs.
+ *
+ * **What it does:**
+ * - Before the pipeline writes any new files it calls `performBackup()` to
+ *   copy the existing `test-artifacts/` folder into a sibling
+ *   `@thinkwise/backups/test-artifacts/` package that survives `node_modules`
+ *   reinstalls.
+ * - If the pipeline fails, the caller invokes `restoreBackup()` to reinstate
+ *   the last known-good artifacts so the consumer project's tests remain
+ *   runnable while the issue is investigated.
+ *
+ * **When it is called:** Automatically by `sync.js` at the start and on
+ * failure of every `testwise sync` run. You do not need to call it manually.
+ */
 export class ArtifactManager {
   private _backupPath: string;
   private _artifactPath: string;
 
-  constructor() {
+  constructor(paths?: PipelinePaths) {
+    const p = paths ?? new PipelinePaths();
+    this._artifactPath = p.testArtifacts;
+
+    // The backup is stored in the sibling @thinkwise/backups package so it
+    // survives reinstalls of this package. Three levels up from
+    // dist/artifact-builder/ lands at node_modules/@thinkwise/ (the org scope
+    // folder), and from there we descend into the backups package.
     const _filename = fileURLToPath(import.meta.url);
     const _dirname = path.dirname(_filename);
     this._backupPath = path.resolve(_dirname, '..', '..', '..', 'backups', 'test-artifacts');
-    this._artifactPath = path.resolve(_dirname, '..', '..', 'test-artifacts');
   }
 
   performBackup() {

package/artifact-builder/ComponentClassModelBuilder.ts

@@ -0,0 +1,148 @@
+import { KnownElementTypes } from '../enums/ElementTypes.js';
+import type { IComponentSchemaMeta } from '../interfaces/IComponentSchemaMeta.js';
+import type { SubjectComponents } from '../types/Components.js';
+import type { NamingHandler } from './helpers/NamingHandler.js';
+import type { SelectorBuilder } from './SelectorBuilder.js';
+import type {
+  ComponentAssignmentModel,
+  ComponentClassModel,
+  ComponentGetterModel,
+  ComponentPropertyModel
+} from './TsFileModel.js';
+
+/**
+ * **Pipeline sub-step** — Builds a pure in-memory model (`ComponentClassModel`)
+ * for the typed component class appended to a generated screen interface file
+ * (e.g. `EmployeeForm`, `EmployeeGrid`). Contains no file I/O — fully unit-testable.
+ */
+export class ComponentClassModelBuilder {
+  private readonly _namingHandler: NamingHandler;
+  private readonly _selectorBuilder: SelectorBuilder;
+
+  constructor(namingHandler: NamingHandler, selectorBuilder: SelectorBuilder) {
+    this._namingHandler = namingHandler;
+    this._selectorBuilder = selectorBuilder;
+  }
+
+  public build(
+    interfaceName: string,
+    componentType: SubjectComponents,
+    propertyLines: string[],
+    meta: IComponentSchemaMeta
+  ): ComponentClassModel {
+    if (componentType === 'Grid') {
+      return {
+        interfaceName,
+        componentType,
+        properties: [],
+        assignments: [],
+        getters: this.buildGetters(propertyLines, meta)
+      };
+    }
+
+    return {
+      interfaceName,
+      componentType,
+      properties: this.buildProperties(propertyLines, meta),
+      assignments: this.buildAssignments(propertyLines, meta),
+      getters: []
+    };
+  }
+
+  public buildGetters(propertyLines: string[], meta: IComponentSchemaMeta): ComponentGetterModel[] {
+    return propertyLines.map((line) => {
+      const property = line.replace('readonly', '').split(':')[0].trim();
+      const colId =
+        meta.properties[this._namingHandler.toSnakeCase(property)]?.colId ??
+        this.getColIdFromPropertyName(property, 'Grid');
+      const columnId = this._selectorBuilder.getElementId(colId, 'Grid');
+
+      return {
+        name: property,
+        returnType: 'IGridColumnControl',
+        bodyLine: `return createGridColumnControl(this._context, '${columnId}');`
+      };
+    });
+  }
+
+  public buildProperties(propertyLines: string[], meta: IComponentSchemaMeta): ComponentPropertyModel[] {
+    return propertyLines.map((line) => {
+      const property = line.replace(/^\s+/, '').split(':')[0].replace(/\?$/, '').trim();
+      return { name: property, type: this.resolvePropertyType(property, meta) };
+    });
+  }
+
+  public buildAssignments(propertyLines: string[], meta: IComponentSchemaMeta): ComponentAssignmentModel[] {
+    return propertyLines.map((line) => {
+      const property = line.split(':')[0].replace(/\?$/, '').trim();
+      const snakeKey = this._namingHandler.toSnakeCase(property);
+      const propMeta = meta.properties[snakeKey];
+      const colId = propMeta?.colId ?? this.getColIdFromPropertyName(property, meta.componentType);
+      const elementType = propMeta?.elementType ?? this.getElementTypeFromPropertyName(property);
+
+      if (meta.componentType === 'Form') {
+        const elementId = this._selectorBuilder.getElementId(colId, 'Form');
+
+        switch (elementType) {
+          case KnownElementTypes.Lookup:
+            return { property, value: `createLookupDropdown(this._context, '${elementId}')` };
+          case KnownElementTypes.DatePicker:
+            return { property, value: `createDateControl(this._context, '${elementId}')` };
+          case KnownElementTypes.ComboBox:
+            return { property, value: `createFormComboBox(this._context, '${elementId}')` };
+          case KnownElementTypes.Field:
+            return { property, value: `createInputFieldControl(this._context, '${elementId}')` };
+        }
+      }
+
+      const pageLocatorString = this._selectorBuilder.getLocatorString(colId, elementType ?? '', meta.componentType);
+      return { property, value: pageLocatorString };
+    });
+  }
+
+  private resolvePropertyType(property: string, meta: IComponentSchemaMeta): string {
+    if (meta.componentType === 'Form') {
+      const elementType =
+        meta.properties[this._namingHandler.toSnakeCase(property)]?.elementType ??
+        this.getElementTypeFromPropertyName(property);
+
+      switch (elementType) {
+        case KnownElementTypes.Lookup:
+          return 'ILookupDropdown';
+        case KnownElementTypes.ComboBox:
+          return 'IFormComboBox';
+        case KnownElementTypes.Field:
+          return 'IInputFieldControl';
+        case KnownElementTypes.DatePicker:
+          return 'IDateControl';
+      }
+    }
+
+    return 'Locator';
+  }
+
+  private getElementTypeFromPropertyName(property: string): string | undefined {
+    if (property.endsWith('Lookup')) return KnownElementTypes.Lookup;
+    if (property.endsWith('DatePicker')) return KnownElementTypes.DatePicker;
+    if (property.endsWith('ComboBox')) return KnownElementTypes.ComboBox;
+    if (property.endsWith('Field')) return KnownElementTypes.Field;
+    return undefined;
+  }
+
+  private getColIdFromPropertyName(property: string, componentType: SubjectComponents): string {
+    const snakeName = this._namingHandler.toSnakeCase(property);
+
+    if (componentType === 'Grid') {
+      return snakeName.replace(/_column$/, '');
+    }
+
+    const formSuffixes = ['_lookup', '_date_picker', '_combo_box', '_dropdown', '_field', '_checkbox', '_textarea'];
+    for (const suffix of formSuffixes) {
+      if (snakeName.endsWith(suffix)) {
+        return snakeName.slice(0, -suffix.length);
+      }
+    }
+
+    return snakeName;
+  }
+}

package/artifact-builder/InterfaceGenerator.ts

@@ -1,29 +1,40 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import * as prettier from 'prettier';
 import { FetchingJSONSchemaStore, InputData, JSONSchemaInput, quicktype } from 'quicktype-core';
-import { PathResolver } from '../helpers/PathResolver.js';
-import { DataRetriever, NamingHandler } from '../index.js';
+import { DataRetriever, NamingHandler, PipelinePaths } from './helpers/index.js';
+
+/**
+ * **Pipeline Step 4** — Runs quicktype to convert the JSON Schema files
+ * produced by `SchemaGenerator` into TypeScript interface files.
+ *
+ * **What it does:** For each schema in `dist/test-artifacts/schemas/`, it
+ * invokes the `quicktype-core` library to generate a `.ts` file containing
+ * a TypeScript interface that matches the JSON shape. The result lands in
+ * `test-artifacts/screens/` and is then refined by `ScreenInterfaceRefiner`.
+ *
+ * **When it runs:** Step 4 of `testwise sync`, after `SchemaGenerator`.
+ */
 
 export class InterfaceGenerator {
   private readonly _namingHandler: NamingHandler;
-  private _filename: string;
-  private _dirname: string;
-  private _screensToBuild: string[];
+  private readonly _screensToBuild: string[];
+  private readonly _paths: PipelinePaths;
 
-  constructor() {
+  constructor(paths?: PipelinePaths) {
+    this._paths = paths ?? new PipelinePaths();
     this._namingHandler = new NamingHandler();
-    this._filename = fileURLToPath(import.meta.url);
-    this._dirname = path.dirname(this._filename);
-    this._screensToBuild = new DataRetriever().getScreensToBuild();
+    this._screensToBuild = new DataRetriever(this._paths).getScreensToBuild();
   }
 
   public async generateScreenInterfacesFromSchemas() {
-    const screenOutputDirectory = path.resolve(this._dirname, '..', '..', 'test-artifacts/screens/');
+    const screenOutputDirectory = this._paths.screens;
     this.verifyOutputDirectory(screenOutputDirectory);
 
-    const schemasDirectory = this.getScreenSchemaFilesPath();
+    const schemasDirectory = this._paths.screenSchemas;
+    if (!fs.existsSync(schemasDirectory)) {
+      throw new Error(`Screen schemas directory not found at: ${schemasDirectory}`);
+    }
 
     await this.generateInterfacesFromSchemaFiles(schemasDirectory, SchemaType.Screen, screenOutputDirectory);
 
@@ -31,10 +42,14 @@ export class InterfaceGenerator {
   }
 
   public async generateSubjectInterfacesFromSchemas() {
-    const schemasDirectory = path.resolve(this._dirname, '../test-artifacts/schemas');
-    const subjectOutputDirectory = path.resolve(this._dirname, '..', '..', 'test-artifacts/subjects');
+    const schemasDirectory = this._paths.schemas;
+    const subjectOutputDirectory = this._paths.subjects;
+
+    if (!fs.existsSync(schemasDirectory)) {
+      // No schemas generated yet – nothing to do.
+      return;
+    }
 
-    this.verifyGeneratedSubjectSchemasDirectory(schemasDirectory);
     this.verifyOutputDirectory(subjectOutputDirectory);
 
     await this.generateInterfacesFromSchemaFiles(schemasDirectory, SchemaType.Subject, subjectOutputDirectory);
@@ -42,12 +57,6 @@ export class InterfaceGenerator {
     console.info('All subject schemas processed.');
   }
 
-  private verifyGeneratedSubjectSchemasDirectory(directory: string) {
-    if (!fs.existsSync(directory)) {
-      return;
-    }
-  }
-
   private verifyOutputDirectory(directory: string) {
     if (!fs.existsSync(directory)) {
       fs.mkdirSync(directory, { recursive: true });
@@ -55,7 +64,7 @@ export class InterfaceGenerator {
   }
 
   private getGeneratedSubjectSchemas(schemasDirectory: string): string[] {
-    return fs.readdirSync(schemasDirectory).filter((f) => f.endsWith('.json'));
+    return fs.readdirSync(schemasDirectory).filter((f) => f.endsWith('.json') && !f.endsWith('.meta.json'));
   }
 
   private verifySubjectComponentsDirectory(directory: string, subject: string) {
@@ -154,17 +163,6 @@ export class InterfaceGenerator {
 
     await Promise.all(tasks);
   }
-
-  public getScreenSchemaFilesPath(): string {
-    const directory = new PathResolver().getConsumerRootDirectory();
-
-    const screenSchemasPath = path.join(directory, 'seed-data/screen-schemas/');
-    if (!fs.existsSync(screenSchemasPath)) {
-      throw new Error(`Screen schemas directory not found at: ${screenSchemasPath}`);
-    }
-
-    return screenSchemasPath;
-  }
 }
 
 enum SchemaType {

package/artifact-builder/ModelDataBuilder.ts

@@ -1,21 +1,24 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-/** biome-ignore-all lint/style/noNonNullAssertion: Because I can */
 /** biome-ignore-all lint/suspicious/noExplicitAny: Because I can */
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import type { IProperty } from '../interfaces/IProperty.js';
+import type { ISeedSubjectDraft } from '../interfaces/ISeedSubjectDraft.js';
 import { indiciumApi } from '../services/IndiciumApi.service.js';
 import { DataRetriever } from './helpers/DataRetriever.js';
 
-// ToDo: move this to a types folder
-type Subjects = {
+interface IPropertyWithSubjectIdentifiers extends IProperty {
   subject: string;
   variant: string;
-  screentype_context: string;
-  screentype_id: 'main' | 'detail' | 'zoom' | 'popup';
-  properties?: IProperty[];
-};
+}
 
+/**
+ * **Pipeline Step 1** — Fetches the raw Thinkwise application model from the
+ * Indicium API and writes it into `seed-data/`.
+ * Calls the API to list all subjects + properties, writes `subjects.json`,
+ * and downloads each subject's screen schema JSON into `seed-data/screen-schemas/`.
+ * Run via `testwise sync` — requires valid credentials in `Testwise.json`.
+ */
 export async function buildSubjects() {
   if (!(await indiciumApi.canConnectToProject())) {
     console.log('Cannot connect to Indicium API. Aborting subject build.');
@@ -24,7 +27,7 @@ export async function buildSubjects() {
 
   const rawTables: any[] = await indiciumApi.getAllTables();
 
-  const subjects: Subjects[] = rawTables
+  const subjects: ISeedSubjectDraft[] = rawTables
     .flatMap((tab: any) => {
       const base = {
         subject: tab.tab_id,
@@ -77,18 +80,19 @@ export async function buildSubjects() {
   console.log(`Seed data written to ${seedDataPath}`);
 }
 
-async function setLookupDropdowns(subjects: Subjects[]): Promise<Subjects[]> {
+async function setLookupDropdowns(subjects: ISeedSubjectDraft[]): Promise<ISeedSubjectDraft[]> {
   const lookupMappings: any[] = await indiciumApi.getLookups();
 
   for (const mapping of lookupMappings) {
-    const targetSubject = subjects.find(
+    const matchingSubjects = subjects.filter(
       (subj) => subj.subject === mapping.tab_id && subj.variant === mapping.tab_variant_id
     );
 
-    const targetProperty = targetSubject?.properties?.find((prop) => prop.col === mapping.col_id);
-
-    if (targetProperty) {
-      targetProperty.control_type = 'LOOKUP_DROPDOWN';
+    for (const subject of matchingSubjects) {
+      const targetProperty = subject.properties?.find((prop) => prop.col === mapping.col_id);
+      if (targetProperty) {
+        targetProperty.control_type = 'LOOKUP_DROPDOWN';
+      }
     }
   }
 
@@ -157,9 +161,3 @@ export async function buildScreens() {
   }
   console.log('Screen schemas generated successfully.');
 }
-
-// ToDo: move this to a interfaces folder
-interface IPropertyWithSubjectIdentifiers extends IProperty {
-  subject: string;
-  variant: string;
-}

package/artifact-builder/ModelDataRefiner.ts

@@ -1,10 +1,30 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { DataRetriever } from '../index.js';
 import type { IRegisteredSubjects } from '../interfaces/IRegisteredSubjects.js';
-
+import { DataRetriever } from './helpers/DataRetriever.js';
+import type { PipelinePaths } from './helpers/PipelinePaths.js';
+
+/**
+ * **Pipeline Step 2** — Filters the full subject seed-data down to only the
+ * subjects that the consumer project has registered.
+ *
+ * **What it does:**
+ * - Reads `registeredSubjects.json` from the consumer project root (the
+ *   curated list the developer maintains via `testwise register`).
+ * - Intersects it with `seed-data/subjects.json` to produce two smaller files:
+ *   - `seed-data/subjectsToBuild.json` — subjects whose classes need generating.
+ *   - `seed-data/screensToBuild.json` — screen schema files to run through quicktype.
+ * - If no subjects are registered, it clears both files so later steps produce
+ *   no output instead of failing.
+ *
+ * **When it runs:** Step 2 of `testwise sync`, immediately after `ModelDataBuilder`.
+ */
 export class ModelDataRefiner {
-  private _dataRetriever = new DataRetriever();
+  private readonly _dataRetriever: DataRetriever;
+
+  constructor(paths?: PipelinePaths) {
+    this._dataRetriever = new DataRetriever(paths);
+  }
 
   public run() {
     const seedDataDir = this._dataRetriever.getSeedDataDirectory();

package/artifact-builder/SchemaGenerator.ts

@@ -1,30 +1,45 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { DataRetriever } from '../index.js';
 import type { ISubject } from '../interfaces/ISubject.js';
 import type { SubjectComponents } from '../types/Components.js';
+import { DataRetriever } from './helpers/DataRetriever.js';
 import { NamingHandler } from './helpers/NamingHandler.js';
-
-const currentFilename = fileURLToPath(import.meta.url);
-const currentDirname = dirname(currentFilename);
-
+import { PipelinePaths } from './helpers/PipelinePaths.js';
+
+/**
+ * **Pipeline Step 3** — Converts raw Thinkwise screen-schema JSON files into
+ * structured JSON Schema files that `quicktype` can consume.
+ *
+ * **What it does:**
+ * - Reads the screen-schema files listed in `seed-data/screensToBuild.json`.
+ * - For each subject, generates a JSON Schema describing the shape of the
+ *   screen's fields and component structure.
+ * - Writes one `.json` schema and one `.meta.json` sidecar file per screen
+ *   into `dist/test-artifacts/schemas/`. The `.meta.json` records which
+ *   component type (Form or Grid) owns each property, which
+ *   `SubjectComponentGenerator` reads back in step 6.
+ *
+ * **When it runs:** Step 3 of `testwise sync`, after `ModelDataRefiner`.
+ */
 export class SchemaGenerator {
-  private _namingHandler: NamingHandler;
-  private _dataRetriever: DataRetriever;
-
-  constructor() {
+  private readonly _namingHandler: NamingHandler;
+  private readonly _dataRetriever: DataRetriever;
+  private readonly _schemasDir: string;
+  private readonly _screensDir: string;
+
+  constructor(paths?: PipelinePaths) {
+    /* v8 ignore next -- default only used at runtime, not in unit tests */
+    const p = paths ?? new PipelinePaths();
     this._namingHandler = new NamingHandler();
-    this._dataRetriever = new DataRetriever();
+    this._dataRetriever = new DataRetriever(p);
+    this._schemasDir = p.schemas;
+    this._screensDir = p.screens;
   }
 
   public generateSchema() {
-    const schemasDir = path.resolve(currentDirname, '../dist/test-artifacts/schemas');
-
-    if (!fs.existsSync(schemasDir)) {
-      fs.mkdirSync(schemasDir, { recursive: true });
+    if (!fs.existsSync(this._schemasDir)) {
+      fs.mkdirSync(this._schemasDir, { recursive: true });
     }
 
     const subjects = this._dataRetriever.getSubjectsToBuild();
@@ -34,11 +49,6 @@ export class SchemaGenerator {
     }
   }
 
-  public iSubjectToJson(value: ISubject): string {
-    return JSON.stringify(value);
-  }
-
-  // Changes start here
   private createSubjectSchema(subject: ISubject): void {
     const screen = { content: this.getScreenContent(subject.screentype_id) };
     const componentsToProcess = this.getComponentsToProcess(screen);
@@ -76,21 +86,13 @@ export class SchemaGenerator {
 
   private getScreenContent(screenTypeId: string): string {
     const screenFileName = this._namingHandler.toPascalCase(screenTypeId);
-    const _filename = fileURLToPath(import.meta.url);
-    const _dirname = path.dirname(_filename);
-    const screenLocation = path.resolve(_dirname, '..', '..', 'test-artifacts/screens/');
-
-    return fs.readFileSync(path.join(screenLocation, `I${screenFileName}.ts`), 'utf-8');
+    return fs.readFileSync(path.join(this._screensDir, `I${screenFileName}.ts`), 'utf-8');
   }
 
   private createComponentSchema(subject: ISubject, componentType: SubjectComponents): void {
     const interfaceName = `${subject.subject}_${componentType.toLowerCase()}`;
-    const schemasDir = path.join(currentDirname, '..', '..', 'dist/test-artifacts/schemas');
-    const fileName = `${this._namingHandler.toPascalCase(interfaceName)}.json`;
-
-    if (fs.existsSync(path.join(schemasDir, fileName))) {
-      return;
-    }
+    const fileName = `${this._namingHandler.toSubjectPascalCase(interfaceName)}.json`;
+    const schemaFilePath = path.join(this._schemasDir, fileName);
 
     // biome-ignore lint/suspicious/noExplicitAny: reason 42
     const componentSchema: any = {
@@ -111,6 +113,9 @@ export class SchemaGenerator {
       }
     };
 
+    // Maps original schema field name → { colId, elementType }
+    const propertyMeta: Record<string, { colId: string; elementType: string }> = {};
+
     subject.properties.forEach((property) => {
       const componentTypeSuffix = this._namingHandler.getElementSuffixFromControlTypeAndComponentType(
         property.control_type,
@@ -120,12 +125,17 @@ export class SchemaGenerator {
 
       componentSchema.properties[fieldName] = { $ref: '#/definitions/Locator' };
       componentSchema.required.push(fieldName);
+      propertyMeta[fieldName] = { colId: property.col, elementType: componentTypeSuffix };
     });
 
-    if (!fs.existsSync(schemasDir)) {
-      fs.mkdirSync(schemasDir, { recursive: true });
+    /* v8 ignore next 3 — generateSchema() always creates this dir first */
+    if (!fs.existsSync(this._schemasDir)) {
+      fs.mkdirSync(this._schemasDir, { recursive: true });
     }
 
-    fs.writeFileSync(path.join(schemasDir, fileName), JSON.stringify(componentSchema, null, 2));
+    const schemaMeta = { componentType, properties: propertyMeta };
+    const metaFileName = fileName.replace('.json', '.meta.json');
+    fs.writeFileSync(schemaFilePath, JSON.stringify(componentSchema, null, 2));
+    fs.writeFileSync(path.join(this._schemasDir, metaFileName), JSON.stringify(schemaMeta, null, 2));
   }
 }

package/artifact-builder/ScreenInterfaceRefiner.ts

@@ -1,15 +1,31 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { disabledScreenComponents, type ScreenComponents, screenComponents } from '../types/Components.js';
-
+import { PipelinePaths } from './helpers/PipelinePaths.js';
+
+/**
+ * **Pipeline Step 5** — Post-processes the raw TypeScript interface files
+ * emitted by `InterfaceGenerator` (quicktype) to make them usable as
+ * Testwise screen contracts.
+ *
+ * **What it does:**
+ * - Removes the `Locator` base interface that quicktype adds (not needed here).
+ * - Strips placeholder interfaces for component types that Testwise does not
+ *   yet support (see `disabledScreenComponents`).
+ * - Merges multiple `Tab` component interfaces into one to avoid duplicates.
+ * - Adds the generated screen interface as an export to `screens/index.ts`.
+ *
+ * **When it runs:** Step 5 of `testwise sync`, immediately after
+ * `InterfaceGenerator` has written the raw quicktype output.
+ */
 export class ScreenInterfaceRefiner {
   private readonly _screensDirectory: string;
+  private readonly _screensIndexPath: string;
 
-  constructor() {
-    const _filename = fileURLToPath(import.meta.url);
-    const _dirname = path.dirname(_filename);
-    this._screensDirectory = path.resolve(_dirname, '../../test-artifacts/screens');
+  constructor(paths?: PipelinePaths) {
+    const p = paths ?? new PipelinePaths();
+    this._screensDirectory = p.screens;
+    this._screensIndexPath = p.screensIndex;
   }
 
   public refine() {
@@ -43,8 +59,7 @@ export class ScreenInterfaceRefiner {
   }
 
   private indexScreenInterface(screenFile: string) {
-    const indexPath = path.resolve(this._screensDirectory, 'index.ts');
-    let indexContent = fs.readFileSync(indexPath, 'utf-8');
+    let indexContent = fs.existsSync(this._screensIndexPath) ? fs.readFileSync(this._screensIndexPath, 'utf-8') : '';
 
     const fileJS = screenFile.replace('.ts', '.js');
     const exportLine = `export * from './${fileJS}';\n`;
@@ -56,7 +71,7 @@ export class ScreenInterfaceRefiner {
       }
       lines.splice(insertPos, 0, exportLine.trim());
       indexContent = lines.join('\n');
-      fs.writeFileSync(indexPath, indexContent, 'utf-8');
+      fs.writeFileSync(this._screensIndexPath, indexContent, 'utf-8');
     }
   }
 
@@ -149,6 +164,6 @@ export class ScreenInterfaceRefiner {
   }
 
   private getAllScreenInterfaceFiles(): string[] {
-    return fs.readdirSync(this._screensDirectory).filter((f) => f.endsWith('.ts'));
+    return fs.readdirSync(this._screensDirectory).filter((f) => f.endsWith('.ts') && f !== 'index.ts');
   }
 }