Scaffold Bun workspace and blocking quality gates

.bun-version

@@ -0,0 +1 @@
+1.3.14

.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets).
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "restricted",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+
+      - name: Install (frozen lockfile)
+        run: bun install --frozen-lockfile
+
+      - name: Typecheck
+        run: bun run typecheck
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Build
+        run: bun run build
+
+      - name: Test (with coverage)
+        run: bun test --coverage
+
+      - name: API surface check
+        run: bun run api
+
+      # `lint:publish` ignores attw's `cjs-resolves-to-esm` rule. That is not a
+      # workaround for a fixable defect: @dexpace/core is ESM-only by design (no
+      # `require` condition in its exports map), so a CJS `require()` of it
+      # necessarily resolves to ESM and attw always flags it. Every other attw
+      # rule stays blocking. The `main`/`types` fields on the package exist so
+      # legacy `node10` resolution still finds the entry point — without them
+      # attw reports a hard resolution failure.
+      - name: Package health (publint + attw)
+        run: bun run lint:publish
+
+      - name: Dual JS/TS consumption check
+        run: bun run verify:dual-consumption
+
+      - name: SEAM-1 zero-dependency check
+        run: bun run verify:seam-1
+
+      - name: Runtime-floor consistency check
+        run: bun run verify:runtime-floor
+
+      - name: Dependency audit
+        run: bun run audit

.gitignore

@@ -112,3 +112,6 @@ dist
 # TernJS port file
 .tern-port
 /.idea/
+
+# api-extractor scratch output (the committed report lives in packages/*/etc/)
+packages/*/temp/

bunfig.toml

@@ -0,0 +1,4 @@
+[test]
+coverage = true
+coverageThreshold = 0.8
+coverageSkipTestFiles = true

eslint.config.js

@@ -0,0 +1,65 @@
+import {createRequire} from 'node:module';
+import tseslint from 'typescript-eslint';
+import gts from 'gts';
+import globals from 'globals';
+import eslintComments from '@eslint-community/eslint-plugin-eslint-comments';
+
+// gts enables `prettier/prettier` with no inline options — its actual style
+// lives in `gts/.prettierrc.json`, which Prettier resolves by walking up from
+// each linted file. This repo deliberately has no root Prettier config (the one
+// `eslint.config.js` is the only overlay), so that lookup never finds gts's
+// file and Prettier silently falls back to its own defaults — double quotes,
+// bracket spacing, the lot. Reading gts's own file is what `gts init`'s
+// generated `.prettierrc.js` does; sourcing it here keeps the single-overlay
+// rule without pinning a copy that drifts on the next gts release.
+const require = createRequire(import.meta.url);
+const gtsPrettierOptions = require('gts/.prettierrc.json');
+
+export default tseslint.config(
+  {ignores: ['**/dist/**', '**/build/**']},
+  ...gts,
+  {
+    rules: {'prettier/prettier': ['error', gtsPrettierOptions]},
+  },
+  {
+    // The root config and the `.mjs` verification scripts belong to no
+    // TypeScript project; they get the gts/format baseline only, never the
+    // type-aware tiers below. gts scopes its own Node globals to a fixed list
+    // of filenames that does not include `scripts/*.mjs`, so declare them here
+    // or `console`/`URL` trip `no-undef`.
+    files: ['eslint.config.js', 'scripts/*.mjs'],
+    languageOptions: {sourceType: 'module', globals: globals.node},
+  },
+  {
+    files: ['**/*.ts', '**/*.tsx'],
+    extends: [
+      ...tseslint.configs.strictTypeChecked,
+      ...tseslint.configs.stylisticTypeChecked,
+    ],
+    plugins: {'@eslint-community/eslint-comments': eslintComments},
+    languageOptions: {
+      parserOptions: {
+        project: null,
+        projectService: true,
+      },
+    },
+    rules: {
+      'max-lines-per-function': [
+        'error',
+        {max: 70, skipComments: true, skipBlankLines: false},
+      ],
+      'max-depth': ['error', 3],
+      'max-params': ['error', 3],
+      // Explicit API surface — the design doc's gate table (Components §3) names both of these.
+      // `allowExpressions: true` exempts inline callback arrows (test callbacks, `.map(e => ...)`)
+      // so the rule only bites named/exported functions and methods, which is where the surface lives.
+      '@typescript-eslint/explicit-function-return-type': [
+        'error',
+        {allowExpressions: true},
+      ],
+      '@typescript-eslint/explicit-module-boundary-types': 'error',
+      // Every `eslint-disable` must carry a `-- reason` (NFR-7's documented-exception clause).
+      '@eslint-community/eslint-comments/require-description': 'error',
+    },
+  },
+);

package.json

@@ -0,0 +1,36 @@
+{
+  "name": "nodejs-sdk",
+  "private": true,
+  "type": "module",
+  "workspaces": [
+    "packages/*"
+  ],
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18",
+    "@changesets/cli": "^2",
+    "@dexpace/core": "workspace:*",
+    "@eslint-community/eslint-plugin-eslint-comments": "^4",
+    "@microsoft/api-extractor": "^7",
+    "@types/bun": "latest",
+    "eslint": "^9",
+    "fast-check": "^3",
+    "globals": "^17.8.0",
+    "gts": "^7",
+    "publint": "^0.3",
+    "typescript": "^5.8",
+    "typescript-eslint": "^8"
+  },
+  "scripts": {
+    "lint": "gts lint .",
+    "fix": "gts fix .",
+    "typecheck": "tsc -p packages/core/tsconfig.json --noEmit",
+    "build": "tsc -p packages/core/tsconfig.build.json",
+    "test": "bun test",
+    "api": "cd packages/core && bun run api:ci",
+    "lint:publish": "publint packages/core && attw --pack packages/core --ignore-rules cjs-resolves-to-esm",
+    "audit": "bun audit --audit-level=high --prod",
+    "verify:dual-consumption": "node scripts/verify-dual-consumption.mjs",
+    "verify:seam-1": "node scripts/verify-seam-1.mjs",
+    "verify:runtime-floor": "node scripts/verify-runtime-floor.mjs"
+  }
+}

packages/core/api-extractor.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
+  "apiReport": {
+    "enabled": true,
+    "reportFolder": "<projectFolder>/etc/"
+  },
+  "docModel": {
+    "enabled": false
+  },
+  "dtsRollup": {
+    "enabled": false
+  }
+}

packages/core/etc/core.api.md

@@ -0,0 +1,12 @@
+## API Report File for "@dexpace/core"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+// @public (undocumented)
+export function ping(): 'pong';
+
+// (No @packageDocumentation comment for this package)
+
+```

packages/core/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@dexpace/core",
+  "version": "0.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=18.17"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {},
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "api:local": "api-extractor run --local",
+    "api:ci": "api-extractor run",
+    "prepublishOnly": "bun run build && bun run api:ci && publint . && attw --pack . --ignore-rules cjs-resolves-to-esm"
+  }
+}

packages/core/src/index.test.ts

@@ -0,0 +1,6 @@
+import {expect, test} from 'bun:test';
+import {ping} from './index.js';
+
+test('ping returns pong', () => {
+  expect(ping()).toBe('pong');
+});

packages/core/src/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @public
+ */
+export function ping(): 'pong' {
+  return 'pong';
+}

packages/core/tsconfig.build.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "exclude": [
+    "src/**/*.test.ts"
+  ]
+}

packages/core/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}

scripts/verify-dual-consumption.mjs

@@ -0,0 +1,8 @@
+// scripts/verify-dual-consumption.mjs
+import assert from 'node:assert/strict';
+import {ping} from '@dexpace/core';
+
+assert.equal(ping(), 'pong');
+console.log(
+  'dual-consumption check passed: plain Node import resolved and executed @dexpace/core',
+);