create-appraisejs 0.2.0-alpha.6 → 0.3.0-alpha.0

package/README.md

@@ -54,7 +54,7 @@ The generated project includes:
 - a seeded SQLite database at `prisma/dev.db`
 - the AppraiseJS dashboard and application code
 - automation sync scripts and reusable step definitions
-- package-manager-aware scripts such as `setup`, `setup:db`, `setup:full`, and `appraisejs:sync`
+- package-manager-aware scripts such as `setup`, `setup:db`, `setup:full`, `appraisejs:sync`, and `appraisejs:install-step`
 
 The generated project does not include:
 
@@ -92,9 +92,20 @@ CREATE_APPRAISE_BRANCH=main CREATE_APPRAISE_TEMPLATE_SUBPATH=templates/default n
 | `npm run install-playwright -- <browser...>` | Install selected Playwright browsers |
 | `npm run sync-all` | Run the full sync pipeline |
 | `npm run appraisejs:sync` | Alias for `sync-all` |
+| `npm run appraisejs:install-step -- --payload-file <path>` | Internal script used by the public `appraisejs add step` CLI |
 | `npm run start` | Start the local production server |
 | `npm run dev` | Start the Next.js development server |
 
+## Install Additional Template Steps
+
+After dependencies are installed in a generated project, you can pull an individual published template step into `automation/steps` with:
+
+```bash
+npx appraisejs@latest add step <group-slug>/<step-slug>
+```
+
+The CLI downloads the step fragment, merges it into the correct step group file, and then runs `sync-template-step-groups` followed by `sync-template-steps`.
+
 ## Notes
 
 - Node.js `18+` is required.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-appraisejs",
-  "version": "0.2.0-alpha.6",
+  "version": "0.3.0-alpha.0",
   "description": "Scaffold a new AppraiseJS app in your directory",
   "license": "Apache-2.0",
   "author": "Hasnat Jamil",

package/templates/default/.appraise-template-meta.json

@@ -1,5 +1,5 @@
 {
-  "preparedAt": "2026-03-25T13:42:37.013Z",
-  "inputHash": "3d8e428a4dcbb25e993b9373c10b2a974387982a734dcfc9281c24bb38f6f36d",
+  "preparedAt": "2026-04-04T14:58:45.169Z",
+  "inputHash": "9173dcae0e64b99bb955c10e9726ad493032476fe0e85ec5dde07f1c587c7cc3",
   "databasePath": "prisma/dev.db"
 }

package/templates/default/.env.example

@@ -1,2 +1,2 @@
-# Database configuration for local development
-DATABASE_URL="file:./dev.db"
+# Database configuration for local development
+DATABASE_URL="file:./dev.db"

package/templates/default/README.md

@@ -1,53 +1,57 @@
-# Appraise Starter Template
-
-This is a production-first Appraise starter project. Copy this folder into a new directory to start a new project.
-
-## Prerequisites
-
-- Node.js 18+
-- npm, pnpm, yarn, or bun
-
-## Quick start
-
-```bash
-# 1. Install dependencies, create .env, and build the production app
-npm run setup
-
-# 2. Optional: install Playwright browsers when you need test execution
-npm run install-playwright -- chromium
-
-# 3. Start the local production server
-npm run start
-```
-
-## What you get
-
-- **URL**: Open [http://localhost:3000](http://localhost:3000) in your browser.
-- **Runtime**: A seeded local SQLite database at `prisma/dev.db`.
-- **Automation**: Starter automation assets under `automation/`, including features, locators, environments, and reusable steps.
-- **UI**: The full Appraise dashboard and UI, ready to run from a production build.
-
-## Scripts
-
-| Script | Description |
-| --- | --- |
-| `npm run setup` | Install deps, create `.env`, and build the cucumber runtime plus the local production app |
-| `npm run build:local` | Build the cucumber runtime and the local production app |
-| `npm run start` | Start the local production server |
-| `npm run dev` | Start the Next.js development server |
-| `npm run install-playwright -- <browser...>` | Install selected Playwright browsers |
-| `npm run setup:db` | Recreate the local SQLite database from migrations and rerun `sync-all` |
-| `npm run setup:full` | Reinstall dependencies, rebuild the DB, rerun `sync-all`, and rebuild the production app |
-| `npm run sync-all` | Sync all starter entities from the bundled automation workspace into the database |
-| `npm run appraisejs:sync` | Alias for `sync-all` |
-
-## Configuration
-
-- Copy `.env.example` to `.env` before running, or let `npm run setup` create it.
-- Default local database URL: `DATABASE_URL="file:./dev.db"`.
-- The database file is created at `prisma/dev.db`.
-
-## Notes
-
-- `npm run setup` does not install Playwright browsers automatically. Install them only when you need browser-based test execution.
-- `npm run dev` is still available for development workflows, but `npm run start` is the primary path for day-to-day local usage.
+# Appraise Starter Template
+
+This is a production-first Appraise starter project. Copy this folder into a new directory to start a new project.
+
+## Prerequisites
+
+- Node.js 18+
+- npm, pnpm, yarn, or bun
+
+## Quick start
+
+```bash
+# 1. Install dependencies, create .env, and build the production app
+npm run setup
+
+# 2. Optional: install Playwright browsers when you need test execution
+npm run install-playwright -- chromium
+
+# 3. Optional: install an extra published template step
+npx appraisejs@latest add step <group-slug>/<step-slug>
+
+# 4. Start the local production server
+npm run start
+```
+
+## What you get
+
+- **URL**: Open [http://localhost:3000](http://localhost:3000) in your browser.
+- **Runtime**: A seeded local SQLite database at `prisma/dev.db`.
+- **Automation**: Starter automation assets under `automation/`, including features, locators, environments, and reusable steps.
+- **UI**: The full Appraise dashboard and UI, ready to run from a production build.
+
+## Scripts
+
+| Script | Description |
+| --- | --- |
+| `npm run setup` | Install deps, create `.env`, and build the cucumber runtime plus the local production app |
+| `npm run build:local` | Build the cucumber runtime and the local production app |
+| `npm run start` | Start the local production server |
+| `npm run dev` | Start the Next.js development server |
+| `npm run install-playwright -- <browser...>` | Install selected Playwright browsers |
+| `npm run setup:db` | Recreate the local SQLite database from migrations and rerun `sync-all` |
+| `npm run setup:full` | Reinstall dependencies, rebuild the DB, rerun `sync-all`, and rebuild the production app |
+| `npm run sync-all` | Sync all starter entities from the bundled automation workspace into the database |
+| `npm run appraisejs:sync` | Alias for `sync-all` |
+| `npm run appraisejs:install-step -- --payload-file <path>` | Internal script used by `npx appraisejs@latest add step ...` |
+
+## Configuration
+
+- Copy `.env.example` to `.env` before running, or let `npm run setup` create it.
+- Default local database URL: `DATABASE_URL="file:./dev.db"`.
+- The database file is created at `prisma/dev.db`.
+
+## Notes
+
+- `npm run setup` does not install Playwright browsers automatically. Install them only when you need browser-based test execution.
+- `npm run dev` is still available for development workflows, but `npm run start` is the primary path for day-to-day local usage.

package/templates/default/automation/steps/actions/click.step.ts

@@ -1,59 +1,59 @@
 import { When, Then, CustomWorld, expect, SelectorName, resolveLocator, getEnvironment, generateRandomData, RandomDataType } from '../../../packages/cucumber-runtime/src/index.js'
-/**
- * @name click
- * @description Template step for handling element click
- * @type ACTION
- */
-
-// This file is generated automatically. Add template steps to this group to generate content.
-
-/**
- * @name click
- * @description Template step for clicking on an element
- * @icon MOUSE
- */
-When('the user clicks on the {string} element', async function (this: CustomWorld, elementName: SelectorName) {
-  const selector = await resolveLocator(this.page, elementName)
-  if (!selector) {
-    throw new Error(`Selector ${elementName} not found. Current url: ${this.page.url()}`)
-  }
-  try {
-    await this.page.locator(selector).click()
-  } catch (error) {
-    throw new Error(`Failed to click on the ${elementName} element: ${error}`)
-  }
-})
-
-/**
- * @name double click
- * @description Template step for double clicking on an element
- * @icon MOUSE
- */
-When('the user double clicks on the {string} element', async function (this: CustomWorld, elementName: SelectorName) {
-  const selector = await resolveLocator(this.page, elementName)
-  if (!selector) {
-    throw new Error(`Selector ${elementName} not found. Current url: ${this.page.url()}`)
-  }
-  try {
-    await this.page.locator(selector).dblclick()
-  } catch (error) {
-    throw new Error(`Failed to double click on the ${elementName} element: ${error}`)
-  }
-})
-
-/**
- * @name right click
- * @description Template step for right clicking on an element
- * @icon MOUSE
- */
-When('the user right clicks on the {string} element', async function (this: CustomWorld, elementName: SelectorName) {
-  const selector = await resolveLocator(this.page, elementName)
-  if (!selector) {
-    throw new Error(`Selector ${elementName} not found. Current url: ${this.page.url()}`)
-  }
-  try {
-    await this.page.locator(selector).click({ button: 'right' })
-  } catch (error) {
-    throw new Error(`Failed to right click on the ${elementName} element: ${error}`)
-  }
-})
+/**
+ * @name click
+ * @description Template step for handling element click
+ * @type ACTION
+ */
+
+// This file is generated automatically. Add template steps to this group to generate content.
+
+/**
+ * @name click
+ * @description Template step for clicking on an element
+ * @icon MOUSE
+ */
+When('the user clicks on the {string} element', async function (this: CustomWorld, elementName: SelectorName) {
+  const selector = await resolveLocator(this.page, elementName)
+  if (!selector) {
+    throw new Error(`Selector ${elementName} not found. Current url: ${this.page.url()}`)
+  }
+  try {
+    await this.page.locator(selector).click()
+  } catch (error) {
+    throw new Error(`Failed to click on the ${elementName} element: ${error}`)
+  }
+})
+
+/**
+ * @name double click
+ * @description Template step for double clicking on an element
+ * @icon MOUSE
+ */
+When('the user double clicks on the {string} element', async function (this: CustomWorld, elementName: SelectorName) {
+  const selector = await resolveLocator(this.page, elementName)
+  if (!selector) {
+    throw new Error(`Selector ${elementName} not found. Current url: ${this.page.url()}`)
+  }
+  try {
+    await this.page.locator(selector).dblclick()
+  } catch (error) {
+    throw new Error(`Failed to double click on the ${elementName} element: ${error}`)
+  }
+})
+
+/**
+ * @name right click
+ * @description Template step for right clicking on an element
+ * @icon MOUSE
+ */
+When('the user right clicks on the {string} element', async function (this: CustomWorld, elementName: SelectorName) {
+  const selector = await resolveLocator(this.page, elementName)
+  if (!selector) {
+    throw new Error(`Selector ${elementName} not found. Current url: ${this.page.url()}`)
+  }
+  try {
+    await this.page.locator(selector).click({ button: 'right' })
+  } catch (error) {
+    throw new Error(`Failed to right click on the ${elementName} element: ${error}`)
+  }
+})

package/templates/default/automation/steps/actions/hover.step.ts

@@ -1,28 +1,28 @@
 import { When, Then, CustomWorld, expect, SelectorName, resolveLocator, getEnvironment, generateRandomData, RandomDataType } from '../../../packages/cucumber-runtime/src/index.js'
-/**
- * @name hover
- * @description Template steps that handles hover actions
- * @type ACTION
- */
-
-// This file is generated automatically. Add template steps to this group to generate content.
-
-/**
- * @name hover
- * @description Template step for hovering over an element
- * @icon MOUSE
- */
-When(
-  'the user hovers the cursor over the {string} element',
-  async function (this: CustomWorld, elementName: SelectorName) {
-    try {
-      const selector = await resolveLocator(this.page, elementName);
-      if (!selector) {
-        throw new Error(`Selector ${elementName} not found`);
-      }
-      await this.page.locator(selector).hover();
-    } catch (error) {
-      throw new Error(`Failed to hover over the ${elementName} element: ${error}`);
-    }
-  }
-);
+/**
+ * @name hover
+ * @description Template steps that handles hover actions
+ * @type ACTION
+ */
+
+// This file is generated automatically. Add template steps to this group to generate content.
+
+/**
+ * @name hover
+ * @description Template step for hovering over an element
+ * @icon MOUSE
+ */
+When(
+  'the user hovers the cursor over the {string} element',
+  async function (this: CustomWorld, elementName: SelectorName) {
+    try {
+      const selector = await resolveLocator(this.page, elementName);
+      if (!selector) {
+        throw new Error(`Selector ${elementName} not found`);
+      }
+      await this.page.locator(selector).hover();
+    } catch (error) {
+      throw new Error(`Failed to hover over the ${elementName} element: ${error}`);
+    }
+  }
+);

package/templates/default/automation/steps/actions/navigation.step.ts

@@ -1,71 +1,71 @@
 import { When, Then, CustomWorld, expect, SelectorName, resolveLocator, getEnvironment, generateRandomData, RandomDataType } from '../../../packages/cucumber-runtime/src/index.js'
-/**
- * @name navigation
- * @description Template steps that deals with browser navigation
- * @type ACTION
- */
-
-// This file is generated automatically. Add template steps to this group to generate content.
-
-/**
- * @name navigate to url
- * @description Navigate to the specified URL
- * @icon NAVIGATION
- */
-When('the user navigates to the {string} url', async function (this: CustomWorld, url: string) {
-  try {
-    await this.page.goto(url, { waitUntil: 'domcontentloaded' })
-  } catch (error) {
-    throw new Error(`Failed to navigate to the ${url} url: ${error}`)
-  }
-})
-
-/**
- * @name navigate to environment base url
- * @description Navigate to the base url of the selected environment
- * @icon NAVIGATION
- */
-When('the user navigates to the base url of the selected environment', async function (this: CustomWorld) {
-  try {
-    const environment = process.env.ENVIRONMENT as string
-    if (!environment) {
-      throw new Error('Environment is not set')
-    }
-    const environmentConfig = getEnvironment(environment)
-    if (!environmentConfig) {
-      throw new Error(`Environment ${environment} not found`)
-    }
-    await this.page.goto(environmentConfig.baseUrl, {
-      waitUntil: 'domcontentloaded',
-    })
-  } catch (error) {
-    throw new Error(`Failed to navigate to the base url of the selected environment: ${error}`)
-  }
-})
-
-/**
- * @name reload
- * @description Template step for reloading the current page
- * @icon NAVIGATION
- */
-When('the user reloads the page', async function (this: CustomWorld) {
-  try {
-    await this.page.reload()
-    await this.page.waitForLoadState('domcontentloaded')
-  } catch (error) {
-    throw new Error(`Failed to reload the page: ${error}`)
-  }
-})
-
-/**
- * @name go back
- * @description Template step for going back to the previous page
- * @icon NAVIGATION
- */
-When('the user goes back to the previous page', async function (this: CustomWorld) {
-  try {
-    await this.page.goBack({ waitUntil: 'domcontentloaded' })
-  } catch (error) {
-    throw new Error(`Failed to go back to the previous page: ${error}`)
-  }
-})
+/**
+ * @name navigation
+ * @description Template steps that deals with browser navigation
+ * @type ACTION
+ */
+
+// This file is generated automatically. Add template steps to this group to generate content.
+
+/**
+ * @name navigate to url
+ * @description Navigate to the specified URL
+ * @icon NAVIGATION
+ */
+When('the user navigates to the {string} url', async function (this: CustomWorld, url: string) {
+  try {
+    await this.page.goto(url, { waitUntil: 'domcontentloaded' })
+  } catch (error) {
+    throw new Error(`Failed to navigate to the ${url} url: ${error}`)
+  }
+})
+
+/**
+ * @name navigate to environment base url
+ * @description Navigate to the base url of the selected environment
+ * @icon NAVIGATION
+ */
+When('the user navigates to the base url of the selected environment', async function (this: CustomWorld) {
+  try {
+    const environment = process.env.ENVIRONMENT as string
+    if (!environment) {
+      throw new Error('Environment is not set')
+    }
+    const environmentConfig = getEnvironment(environment)
+    if (!environmentConfig) {
+      throw new Error(`Environment ${environment} not found`)
+    }
+    await this.page.goto(environmentConfig.baseUrl, {
+      waitUntil: 'domcontentloaded',
+    })
+  } catch (error) {
+    throw new Error(`Failed to navigate to the base url of the selected environment: ${error}`)
+  }
+})
+
+/**
+ * @name reload
+ * @description Template step for reloading the current page
+ * @icon NAVIGATION
+ */
+When('the user reloads the page', async function (this: CustomWorld) {
+  try {
+    await this.page.reload()
+    await this.page.waitForLoadState('domcontentloaded')
+  } catch (error) {
+    throw new Error(`Failed to reload the page: ${error}`)
+  }
+})
+
+/**
+ * @name go back
+ * @description Template step for going back to the previous page
+ * @icon NAVIGATION
+ */
+When('the user goes back to the previous page', async function (this: CustomWorld) {
+  try {
+    await this.page.goBack({ waitUntil: 'domcontentloaded' })
+  } catch (error) {
+    throw new Error(`Failed to go back to the previous page: ${error}`)
+  }
+})