@esimplicitylabs/katalyst-xspec 0.6.0

package/LICENSE

@@ -0,0 +1,7 @@
+Internal Use Only License
+
+Copyright (c) Kata. All rights reserved.
+
+Permission is hereby granted to employees and contractors of Kata, and other authorized parties explicitly approved in writing by Kata, to use, copy, and modify this software solely for internal business purposes. Distribution, sublicensing, or use for any external or commercial purpose without prior written consent from Kata is prohibited.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# @esimplicitylabs/katalyst-xspec
+
+Reusable Playwright-BDD fixtures, ports, adapters, and step registrations for API, UI, and hybrid testing. Designed to be consumed as a dev dependency across repos.
+
+## Install
+
+```bash
+npm install -D @esimplicitylabs/katalyst-xspec @playwright/test playwright-bdd
+```
+
+Or scaffold a new project:
+
+```bash
+npx @esimplicitylabs/katalyst-xspec init my-tests
+```
+
+## What’s included
+
+- **Fixtures**: `createBddTest` wiring world, api/ui/auth/cleanup adapters.
+- **Ports**: `ApiPort`, `UiPort`, `AuthPort`, `CleanupPort`.
+- **Adapters**: Playwright API/UI adapters, default cleanup, example auth adapter.
+- **Step registrations**: API (auth/http/assertions), UI (basic + wizard), shared vars/cleanup, hybrid helpers.
+- **Config helpers**: tag expression helpers for project tagging.
+
+## Minimal usage
+
+1) Create fixtures (consumer repo):
+```ts
+// features/steps/fixtures.ts
+import {
+  createBddTest,
+  PlaywrightApiAdapter,
+  PlaywrightUiAdapter,
+  UniversalAuthAdapter,
+  DefaultCleanupAdapter,
+} from '@esimplicitylabs/katalyst-xspec';
+
+export const { test } = createBddTest({
+  createApi: ({ apiRequest }) => new PlaywrightApiAdapter(apiRequest),
+  createUi: ({ page }) => new PlaywrightUiAdapter(page),
+  createAuth: ({ api, ui }) => new UniversalAuthAdapter({ api, ui }),
+  createCleanup: () => new DefaultCleanupAdapter(),
+});
+```
+
+2) Register steps (thin wrappers):
+```ts
+// features/steps/steps_api/index.ts
+import { test } from '../fixtures';
+import { registerApiSteps } from '@esimplicitylabs/katalyst-xspec/steps';
+registerApiSteps(test);
+```
+
+3) Configure Playwright projects with your features/steps globs and tag expressions. Keep `@playwright/test` and `playwright-bdd` aligned with peer ranges.
+
+## Publishing (npm)
+
+Publishing is automated. The `.github/workflows/publish.yml` workflow builds the package and publishes it to the
+public npm registry, authenticating via `actions/setup-node` with `registry-url: https://registry.npmjs.org` and the
+`NODE_AUTH_TOKEN` secret. There is no `.npmrc` in this package and none is needed.
+
+To release: bump `version` in `katalyst-xspec/package.json`, land the change, and the workflow publishes it. The
+workflow skips any version already present on npm, so a change without a version bump merges green and never
+reaches the registry.
+
+## Notes
+- Peer dependencies: `@playwright/test`, `playwright-bdd`, `typescript` must be installed in the consuming repo.
+- Defaults (auth/cleanup) are examples; override via `createBddTest` options for app-specific behavior.
+- Tagging: supports `@api`, `@ui`, `@hybrid`, plus your own (`@smoke`, `@slow`, `@external`); combine with Playwright’s `maxFailures`/reporters as needed.

package/bin/katalyst-xspec.cjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+'use strict';
+
+// Single entry point: `katalyst-xspec <command> [options]`.
+const path = require('path');
+
+const COMMANDS = {
+  init: { file: 'init.cjs', summary: 'Scaffold a new katalyst-xspec test project' },
+  upgrade: { file: 'upgrade.cjs', summary: 'Upgrade katalyst-xspec, migrate scaffolding, update skills' },
+  stubs: { file: 'stubs.cjs', summary: 'Generate stubs for undefined step definitions' },
+};
+
+function usage() {
+  const width = Math.max(...Object.keys(COMMANDS).map((c) => c.length));
+  const lines = Object.entries(COMMANDS).map(([name, { summary }]) => `  ${name.padEnd(width)}  ${summary}`);
+  return `Usage: katalyst-xspec <command> [options]
+
+Commands:
+${lines.join('\n')}
+
+Run "katalyst-xspec <command> --help" for command options.
+
+New project:   npx @esimplicitylabs/katalyst-xspec init
+In a project:  npx katalyst-xspec upgrade
+`;
+}
+
+const [command, ...rest] = process.argv.slice(2);
+
+if (!command || command === '--help' || command === '-h' || command === 'help') {
+  process.stdout.write(usage());
+  process.exit(0);
+}
+
+if (command === '--version' || command === '-V') {
+  console.log(require('../package.json').version);
+  process.exit(0);
+}
+
+const entry = COMMANDS[command];
+if (!entry) {
+  console.error(`Unknown command: ${command}\n`);
+  process.stderr.write(usage());
+  process.exit(1);
+}
+
+// Subcommands parse process.argv.slice(2), so drop the command name.
+process.argv = [process.argv[0], process.argv[1], ...rest];
+require(path.join(__dirname, '..', 'cli', entry.file))
+  .main()
+  .catch((err) => {
+    console.error(`[katalyst-xspec ${command}] ERROR: ${err && err.message ? err.message : err}`);
+    process.exit(1);
+  });