opsx-gherkin 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## Unreleased
+
+- Migrate the conversion CLI into a typed, tested, reproducible package.
+- Include an independent syntax compatibility skill owning the canonical profile.
+- Check normalized model preservation before emitting converted documents.
+- Preserve delta operation-group order and reject unmapped removal/rename content.

package/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+Use Node.js 22.18+ and the pnpm version declared in `package.json`.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm verify
+```
+
+The only canonical compatibility contract is
+[OPENSPEC_MDG_PROFILE.feature.md](skills/opsx-gherkin/references/OPENSPEC_MDG_PROFILE.feature.md).
+Read it before changing conversion behavior or syntax guidance. Update the
+relevant Rule/Scenario before introducing a compatibility correction; a new
+mapping needs an explicit contract change. Keep examples executable and update
+their generated counterparts when behavior changes.
+
+Parsing and rendering operate on the typed document model. Keep filesystem I/O
+and command diagnostics at the CLI boundary. Official validators remain behind
+their shared adapter and pinned during compatibility-preserving maintenance.
+
+Tests must examine actual interpreted structures and values, including expanded
+Examples. Parser acceptance and stable text alone cannot establish preservation.
+Package tests must use the installed tarball and the bundled skill resources.
+`pnpm test` rebuilds commands before process tests; `pnpm test:coverage` also
+checks coverage thresholds. `pnpm test:package` builds and verifies npm/npx in
+an isolated temporary consumer directory.
+
+Use Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, etc.). Mark public
+interface incompatibilities with `!` or a `BREAKING CHANGE:` footer. Check a
+message with `pnpm exec commitlint --edit <message-file>`.
+
+## Release setup
+
+The repository includes a manually dispatched release workflow. Before its first run:
+
+1. Configure the real Git remote and add its actual repository, homepage, and
+   issue URLs to package metadata. No destination is assumed by this repository.
+2. Confirm npm ownership/availability for `opsx-gherkin` and register the GitHub
+   workflow as a trusted publisher for that package, permitting `npm publish`.
+   Use workflow filename `release.yml` and environment name `npm` in that configuration.
+3. Configure the GitHub `npm` environment and repository permissions as desired.
+   The workflow requests an OIDC token for npm provenance and uses the repository's
+   `GITHUB_TOKEN` for release notes. No npm token is stored in the project.
+4. Establish the release history. The package retains the prototype's `1.0.0`
+   baseline; semantic-release determines the published version from tags and
+   Conventional Commits. A first release requires a release-triggering commit.
+5. Run `pnpm verify`, then dispatch the Release workflow on `main`.
+
+The release job verifies before invoking semantic-release. Versioning, changelog,
+and release-note configuration live in `release.config.mjs`. Local verification
+and package smoke checks do not upload artifacts or require publishing credentials.
+
+Trusted publisher requirements: [npm documentation](https://docs.npmjs.com/trusted-publishers/).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opsx-gherkin contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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,99 @@
+# opsx-gherkin
+
+Deterministic conversion between OpenSpec and Gherkin, with a self-contained
+skill explaining compatible syntax. Requires Node.js 22.18+.
+
+## Convert a specification
+
+```sh
+npx opsx-gherkin mdg-to-opsx input.feature.md -o spec.md
+npx opsx-gherkin opsx-to-mdg spec.md -o output.feature.md
+npx opsx-gherkin opsx-to-feature spec.md -o output.feature
+```
+
+The supported directions are Markdown with Gherkin to OpenSpec, OpenSpec to
+Markdown with Gherkin, and OpenSpec to plain Gherkin. Plain `.feature` input is
+available for direct validation only.
+
+Each converter accepts one input path, inline `--text`, or stdin. With no `-o`,
+the result goes to stdout. Existing destinations require `--force`; successful
+file writes are atomic. Invalid conversions leave the destination unchanged.
+
+```sh
+npx opsx-gherkin mdg-to-opsx < input.feature.md
+npx opsx-gherkin opsx-to-feature --text "$(cat spec.md)"
+npx opsx-gherkin opsx-to-mdg --help
+```
+
+`--name` supplies a name when OpenSpec input lacks a title or usable source-path
+context. `--project-root` supplies main-spec context for delta validation.
+`--output` is an alias for `-o`. Standalone `mdg-to-opsx`, `opsx-to-mdg`, and
+`opsx-to-feature` executables accept the same options after installation.
+
+## Compatibility
+
+Read the complete contract before authoring compatible documents:
+
+```sh
+npx opsx-gherkin profile
+```
+
+`instructions` is an alias. Both print the same
+[canonical contract](skills/opsx-gherkin/references/OPENSPEC_MDG_PROFILE.feature.md)
+owned by the bundled skill.
+
+Conversions validate both endpoints with the pinned official OpenSpec and
+Cucumber validators and compare their normalized models. They preserve the
+documented structure and values while normalizing formatting. Syntax outside
+the compatibility profile produces a diagnostic instead of an inferred mapping.
+Supported delta operations include ADDED, MODIFIED, REMOVED, and RENAMED; the
+contract defines their allowed content.
+
+Complete examples: [account access](skills/opsx-gherkin/references/examples/account.feature.md)
+and [authentication delta](skills/opsx-gherkin/references/examples/authentication-delta.feature.md).
+
+## Validate syntax directly
+
+```sh
+npx --package opsx-gherkin validate-spec --format openspec spec.md
+npx --package opsx-gherkin validate-spec --format mdg input.feature.md
+npx --package opsx-gherkin validate-spec --format feature output.feature
+```
+
+The validator emits JSON. Without `--format`, `.feature.md` selects MDG,
+`.feature` selects plain Gherkin, and other suffixes select OpenSpec. The legacy
+`--format gherkin` alias selects MDG for `.feature.md` and plain Gherkin otherwise.
+Direct OpenSpec validation checks a main specification; converters also validate
+supported deltas. Valid endpoint syntax alone does not establish convertibility.
+
+Exit codes: `0` success, `1` invalid syntax/profile/conversion, `2` usage or I/O
+failure. Conversion diagnostics go to stderr; stdout remains usable as a document.
+
+## Use the syntax skill
+
+The package contains [skills/opsx-gherkin](skills/opsx-gherkin/SKILL.md), including
+its contract and examples. To obtain it locally:
+
+```sh
+npm install --save-dev opsx-gherkin
+```
+
+Copy the **complete** `node_modules/opsx-gherkin/skills/opsx-gherkin` directory to
+the skill location supported by your agent. Keep the references beside
+`SKILL.md`. The skill explains syntax and conversion independently; installing
+the npm package does not activate it or change agent settings automatically.
+
+## Development
+
+```sh
+pnpm install --frozen-lockfile
+pnpm verify
+```
+
+Verification includes lint, types, tests and coverage, build, package checks,
+and a production installation of the actual tarball. It needs registry access
+to install dependencies and does not publish. `pnpm test:package` runs the
+package checks separately. Supported Node versions are tested in CI.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contract changes and release setup,
+[SECURITY.md](SECURITY.md) for security reporting, and [LICENSE](LICENSE) for MIT terms.

package/SECURITY.md

@@ -0,0 +1,14 @@
+# Security
+
+Keep Node.js and dependencies within their supported ranges. Before converting
+untrusted specifications, inspect the selected source and destination paths.
+The converters treat specification content as data; they do not execute steps
+or Doc Strings. Existing output files require an explicit `--force`.
+
+For a potential vulnerability, use the private reporting channel of the hosting
+repository when available. Otherwise contact its maintainer privately. Avoid
+including credentials or sensitive source documents in public reports.
+
+Include the package and Node versions, affected command, a minimal sanitized
+input, and the observed behavior. Security fixes should include a regression
+test and pass the package's full verification command.

package/dist/cli.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { c as errorMessage } from "./official-99qBUZpr.mjs";
+import { t as runConverterCli } from "./converter-CFtzcfoM.mjs";
+import { readFile } from "node:fs/promises";
+//#region src/profile-resource.ts
+const profileUrl = new URL("./skills/opsx-gherkin/references/OPENSPEC_MDG_PROFILE.feature.md", import.meta.resolve("opsx-gherkin/package.json"));
+function readProfile() {
+	return readFile(profileUrl, "utf8");
+}
+//#endregion
+//#region src/cli.ts
+const help = `Usage: opsx-gherkin <command> [options]
+
+Before generating a compatible specification:
+  npx opsx-gherkin profile
+
+Commands:
+  profile          Print the complete normative authoring and conversion contract
+  instructions     Alias for profile
+  mdg-to-opsx      Convert Markdown with Gherkin (.feature.md) to OpenSpec
+  opsx-to-mdg      Convert OpenSpec to Markdown with Gherkin (.feature.md)
+  opsx-to-feature  Convert OpenSpec to plain Gherkin (.feature)
+
+Standalone validator:
+  validate-spec [--format openspec|mdg|feature] <file>
+
+Run <command> --help for converter options.
+`;
+const [command, ...args] = process.argv.slice(2);
+if (!command || [
+	"--help",
+	"-h",
+	"help"
+].includes(command)) process.stdout.write(help);
+else if (command === "profile" || command === "instructions") try {
+	if (args.length) throw new Error(`The ${command} command accepts no arguments`);
+	process.stdout.write(await readProfile());
+} catch (error) {
+	process.stderr.write(`${errorMessage(error)}\n`);
+	process.exitCode = 2;
+}
+else if (command === "mdg-to-opsx" || command === "opsx-to-mdg" || command === "opsx-to-feature") process.exitCode = await runConverterCli(command, args);
+else {
+	process.stderr.write(`Unknown command: ${command}\n\n${help}`);
+	process.exitCode = 2;
+}
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.mjs.map

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/profile-resource.ts","../src/cli.ts"],"sourcesContent":["import { readFile } from 'node:fs/promises'\n\nexport const profileUrl = new URL(\n  './skills/opsx-gherkin/references/OPENSPEC_MDG_PROFILE.feature.md',\n  import.meta.resolve('opsx-gherkin/package.json'),\n)\n\nexport function readProfile(): Promise<string> {\n  return readFile(profileUrl, 'utf8')\n}\n","#!/usr/bin/env node\nimport { runConverterCli } from './cli/converter.js'\nimport { errorMessage } from './errors.js'\nimport { readProfile } from './profile-resource.js'\n\nconst help = `Usage: opsx-gherkin <command> [options]\n\nBefore generating a compatible specification:\n  npx opsx-gherkin profile\n\nCommands:\n  profile          Print the complete normative authoring and conversion contract\n  instructions     Alias for profile\n  mdg-to-opsx      Convert Markdown with Gherkin (.feature.md) to OpenSpec\n  opsx-to-mdg      Convert OpenSpec to Markdown with Gherkin (.feature.md)\n  opsx-to-feature  Convert OpenSpec to plain Gherkin (.feature)\n\nStandalone validator:\n  validate-spec [--format openspec|mdg|feature] <file>\n\nRun <command> --help for converter options.\n`\n\nconst [command, ...args] = process.argv.slice(2)\nif (!command || ['--help', '-h', 'help'].includes(command)) {\n  process.stdout.write(help)\n} else if (command === 'profile' || command === 'instructions') {\n  try {\n    if (args.length) throw new Error(`The ${command} command accepts no arguments`)\n    process.stdout.write(await readProfile())\n  } catch (error) {\n    process.stderr.write(`${errorMessage(error)}\\n`)\n    process.exitCode = 2\n  }\n} else if (\n  command === 'mdg-to-opsx' ||\n  command === 'opsx-to-mdg' ||\n  command === 'opsx-to-feature'\n) {\n  process.exitCode = await runConverterCli(command, args)\n} else {\n  process.stderr.write(`Unknown command: ${command}\\n\\n${help}`)\n  process.exitCode = 2\n}\n"],"mappings":";;;;;AAEA,MAAa,aAAa,IAAI,IAC5B,oEACA,YAAY,QAAQ,2BAA2B,CACjD;AAEA,SAAgB,cAA+B;CAC7C,OAAO,SAAS,YAAY,MAAM;AACpC;;;ACJA,MAAM,OAAO;;;;;;;;;;;;;;;;;AAkBb,MAAM,CAAC,SAAS,GAAG,QAAQ,QAAQ,KAAK,MAAM,CAAC;AAC/C,IAAI,CAAC,WAAW;CAAC;CAAU;CAAM;AAAM,CAAC,CAAC,SAAS,OAAO,GACvD,QAAQ,OAAO,MAAM,IAAI;KACpB,IAAI,YAAY,aAAa,YAAY,gBAC9C,IAAI;CACF,IAAI,KAAK,QAAQ,MAAM,IAAI,MAAM,OAAO,QAAQ,8BAA8B;CAC9E,QAAQ,OAAO,MAAM,MAAM,YAAY,CAAC;AAC1C,SAAS,OAAO;CACd,QAAQ,OAAO,MAAM,GAAG,aAAa,KAAK,EAAE,GAAG;CAC/C,QAAQ,WAAW;AACrB;KACK,IACL,YAAY,iBACZ,YAAY,iBACZ,YAAY,mBAEZ,QAAQ,WAAW,MAAM,gBAAgB,SAAS,IAAI;KACjD;CACL,QAAQ,OAAO,MAAM,oBAAoB,QAAQ,MAAM,MAAM;CAC7D,QAAQ,WAAW;AACrB"}