@zahid15/mockline 0.0.0-stage → 0.1.1

package/docs/configuration.md

@@ -0,0 +1,214 @@
+# Configuration reference
+
+Mockline reads an explicit file passed by `--config`, or discovers the first
+`mockline.yaml`, `mockline.yml`, or `mockline.json` in the current directory.
+The config is validated at startup; malformed config is an error rather than
+silently falling back to defaults. CLI options override matching values.
+
+The editor schema is [`config.schema.json`](config.schema.json). Regenerate it
+after changing `src/config/schema.ts` with `corepack pnpm schema:config`.
+
+## Top-level fields
+
+| Field              | Default          | Meaning                                                                         |
+| ------------------ | ---------------- | ------------------------------------------------------------------------------- |
+| `port`             | `4010`           | TCP port; `0` requests an ephemeral port.                                       |
+| `host`             | `127.0.0.1`      | Bind address. Non-loopback addresses expose the mock to other hosts.            |
+| `seed`             | `0` when omitted | Base for deterministic response generation.                                     |
+| `prefer`           | `example`        | `example` selects documented examples first; `generate` generates from schemas. |
+| `latency`          | `0`              | Delay in milliseconds; see [Latency and errors](#latency-and-errors).           |
+| `validate`         | `warn`           | `off`, `warn`, or `strict` request validation.                                  |
+| `enforceAuth`      | `false`          | Require declared security credentials to be present. Does not verify them.      |
+| `requestBodyLimit` | `1048576`        | Maximum request-body size in bytes.                                             |
+| `requestTimeoutMs` | `30000`          | HTTP request/header timeout in milliseconds.                                    |
+
+## Nested fields
+
+### `errors`
+
+```yaml
+errors:
+  rate: 0.05
+  statuses: [500, 503]
+  perOperationRates:
+    createPet: 0.2
+```
+
+`rate` and operation-specific rates are between 0 and 1. An operation-specific
+entry takes precedence over `rate`; `statuses` is the pool used for injected
+failures. `X-Mockline-Error: true` forces the first configured status.
+
+### `stateful`
+
+```yaml
+stateful:
+  enabled: true
+  seedItems: 3
+  idProperty: id
+```
+
+Stateful behavior is in-memory and only activates for structurally detected
+REST collections (see [Stateful mode](../README.md#stateful-mode)). Numeric IDs
+are allocated for numeric schemas; string IDs are generated from the declared
+schema. `seedItems` must be a non-negative integer.
+
+### `generation`
+
+```yaml
+generation:
+  hints: true
+  counter: false
+  maxDepth: 3
+  minArrayItems: 1
+  maxArrayItems: 3
+```
+
+- `hints` enables field-name hints, or supplies a map of property names to
+  string/number/boolean/null/primitive-array values. Hints are applied only
+  where a schema does not already constrain the generated value.
+- `counter` varies generation by per-operation request count. The default is
+  repeatable output for the same seed and operation.
+- `maxDepth` bounds recursive schemas (0–20).
+- `minArrayItems` and `maxArrayItems` bound generated array lengths. Use
+  non-negative integers; keep the minimum no greater than the maximum.
+
+### `overrides`
+
+Overrides are keyed by `operationId` or by a case-insensitive `METHOD /path`
+key. Fixed overrides can set `status`, `body`, `headers`, and `delay`:
+
+```yaml
+overrides:
+  listPets:
+    status: 200
+    body:
+      - id: 1
+        name: Fixed response
+```
+
+A `sequence` provides successive responses; it holds on the last item by
+default, or cycles with `loop: true`:
+
+```yaml
+overrides:
+  getPet:
+    loop: true
+    sequence:
+      - status: 200
+        body: { id: 1, name: First }
+      - status: 404
+        body: { title: Not Found, status: 404 }
+```
+
+Conditional `rules` are checked in order; the first matching rule wins. A
+single `when`/`response` pair is also supported. Condition locations are
+`query`, `header`, and `body`; operations are `eq` (default), `contains`, and
+`regex`:
+
+```yaml
+overrides:
+  listPets:
+    rules:
+      - when: { location: query, name: demo, op: eq, value: empty }
+        response: { status: 200, body: [] }
+      - when: { location: header, name: x-fixture, op: contains, value: pets }
+        response: { status: 200, body: [{ id: 7, name: Matched }] }
+```
+
+For a body condition, `name` may be a dotted property path such as `user.id`
+or a JSON Pointer-like path such as `/user/id`. Regex conditions use JavaScript
+regular-expression syntax; keep config patterns simple and trusted.
+
+### `proxy`
+
+```yaml
+proxy:
+  url: https://api.example.test/v1
+  all: false
+  allowPrivate: false
+  timeoutMs: 5000
+  recordFile: ./proxy-examples.json
+```
+
+With `all: false`, only unmatched requests are proxied. `all: true` forwards all
+non-inspector requests. The upstream must use HTTP(S). Private/loopback/link-
+local destinations are blocked unless `allowPrivate` is explicitly enabled.
+`timeoutMs` is a positive integer. `recordFile` stores upstream response
+examples as JSON.
+
+### `cors`
+
+```yaml
+cors:
+  enabled: true
+  origins: ['*']
+```
+
+CORS is enabled by default for local development. `origins` accepts exact
+origin strings; `*` allows any origin. Disable it with `--no-cors` or set
+`enabled: false`.
+
+### `recording`
+
+```yaml
+recording:
+  enabled: true
+  file: ./mockline-records.jsonl
+  maxRequests: 500
+  redactHeaders: [authorization, cookie, set-cookie, x-api-key, api-key]
+```
+
+Records are kept in a bounded in-memory ring. If `file` is set, each record is
+also appended as JSONL. Common credential headers are always redacted; this list
+adds more names. Header-name matching is case-insensitive. Request bodies are
+not redacted—use a private file and avoid recording sensitive payloads.
+
+### `controlHeaders`
+
+```yaml
+controlHeaders:
+  allow: true
+```
+
+When enabled, `Prefer` and `X-Mockline-*` control headers can influence example,
+status, delay, and injected-error selection. Disable them when requests come
+from clients that must not control mock behavior.
+
+### `inspector`
+
+```yaml
+inspector:
+  enabled: false
+```
+
+On a loopback bind the inspector is enabled by default unless explicitly set to
+`false`. On non-loopback binds it is disabled by default unless explicitly set
+to `true` (or `--inspector` is passed). It has no authentication; expose it only
+on a trusted interface.
+
+## Latency and errors
+
+Latency accepts a fixed number, a two-number inclusive range, or a distribution
+object:
+
+```yaml
+latency: 25
+# or: latency: [10, 80]
+# or:
+# latency:
+#   min: 10
+#   max: 80
+#   distribution: normal  # uniform (default) or normal
+# A fixed form is also available: latency: { fixed: 25 }
+```
+
+CLI `--delay` accepts a fixed number or `min-max` range and overrides config
+latency. `X-Mockline-Delay` (when control headers are allowed) has higher
+precedence than a per-override delay, which has higher precedence than global
+latency.
+
+## Example files
+
+- [`../examples/petstore/mockline.yaml`](../examples/petstore/mockline.yaml)
+- [`../examples/petstore/openapi.yaml`](../examples/petstore/openapi.yaml)
+- [`../README.md`](../README.md) for CLI, API, security, and Docker usage.

package/docs/generation.md

@@ -0,0 +1,26 @@
+# Schema generation
+
+Responses use a seed derived from the configured seed, HTTP method, matched
+path template and optional operation-local counter. generation.counter is false
+by default, so repeated requests to one operation return the same generated
+body and requests to other routes do not alter it. Date generation uses a fixed
+2020-01-01 reference time so wall-clock time does not change seeded output.
+
+Generation respects supported primitive constraints, formats, object properties,
+required fields, arrays, compositions and local schema references. writeOnly
+response properties and readOnly request properties are omitted. Property hints
+apply only when stronger constraints are absent; hints can be disabled or set
+per property in config. OpenAPI 3.0 uses the draft-07 validator with nullable
+support; OpenAPI 3.1 uses the JSON Schema 2020-12 validator.
+
+Simple regex patterns are generated directly; complex patterns use candidate
+fallbacks and warnings. Every candidate is schema-validated, including calls
+without an OpenAPI root. Up to twelve deterministic attempts are made. If no
+valid candidate can be generated, the library throws and the server returns a
+500 problem response; it does not silently return invalid generated data.
+
+Depth limits prune optional recursive fields. Schemas requiring infinite nested
+objects have no finite JSON value and fail with a bounded error. Not every valid
+JSON Schema can be synthesized: complex regexes, constrained composition
+intersections and unsupported keywords may fail generation even though the spec
+itself is valid. Examples are the practical fallback for those operations.

package/docs/release.md

@@ -0,0 +1,32 @@
+# Releasing Mockline
+
+GitHub repository: zahidhasann88/mockline. npm package: @zahid15/mockline.
+The CLI remains mockline. The npm account must own the zahid15 scope.
+
+## First npm publication
+
+Push the repository and wait for all CI jobs. npm trusted publishing is configured
+from an existing package's settings. For a new package, first publish the checked
+0.1.0 build interactively from your own npm account with npm login and npm publish
+--access public. Review npm pack --dry-run before publishing. Do not upload npm
+credentials to GitHub. This first local publication does not carry Actions OIDC
+provenance; future CI publications do.
+
+After the package exists, add a GitHub trusted publisher in its npm settings:
+owner zahidhasann88, repository mockline, workflow release.yml, environment npm.
+Allow npm publish. Create the npm GitHub environment and repository variable
+PUBLISH_TO_NPM=true. The workflow uses Node 22 and npm 11 with id-token: write.
+See https://docs.npmjs.com/trusted-publishers/ for current registry requirements.
+
+GHCR publication is separate: enable repository variable PUBLISH_DOCKER=true
+only when ready. The image is ghcr.io/zahidhasann88/mockline. GitHub release
+assets are created independently of npm/GHCR publication.
+
+## Each release
+
+Run the checks documented in CONTRIBUTING.md. Regenerate the config schema,
+review tarball contents, update package.json and CHANGELOG.md, commit and push.
+Only after main CI passes, push a matching annotated v<version> tag. Release
+checks validate the tag/version before publishing and test the tagged checkout.
+An existing npm version is skipped on retries. Manual dispatch accepts an
+existing tag; it never changes where that tag points. Never move a published tag.

package/docs/stateful.md

@@ -0,0 +1,19 @@
+# In-memory state
+
+A collection requires GET /things with an array response, POST /things, and
+GET /things/{id} whose item schema matches the array item schema and contains
+the configured ID property (id by default). Matching PUT/PATCH/DELETE item
+routes participate; other operations use normal response selection.
+
+Seeded items default to three; stateful.seedItems: 0 starts empty. POST stores
+an item and assigns an ID if needed, GET lists or retrieves, PUT replaces,
+PATCH shallow-merges, and DELETE returns 204. Declared limit/offset query
+parameters paginate lists. Missing GET/PUT/PATCH items return 404. Deleting a
+missing item still returns 204. Overrides and response-selection controls do
+not execute the state handler. reset() and POST /__mockline/reset regenerate
+seed data and reset deterministic counters; request history remains available.
+
+This is a development store, not a database: state is lost on restart, updates
+are shallow, relations and transactions are absent, and arbitrary resource
+wrappers or workflow schemas are not detected. Constrained ID namespaces may
+be exhausted; use a broad integer/string ID schema for stateful demos.

package/examples/README.md

@@ -0,0 +1,21 @@
+# Examples
+
+- `petstore/openapi.yaml` and `petstore/mockline.yaml`: CLI, config, seeded
+  stateful CRUD, and a conditional override.
+- `programmatic.ts`: typed Node.js library usage. Build Mockline first, install
+  the published package or use this repository after building, then run with a TS
+  runner such as `pnpm exec tsx examples/programmatic.ts`.
+
+From the repository root, try the CLI example with:
+
+```sh
+mockline routes examples/petstore/openapi.yaml
+mockline validate examples/petstore/openapi.yaml
+mockline serve examples/petstore/openapi.yaml --config examples/petstore/mockline.yaml --port 4010
+```
+
+The sample config binds only to `127.0.0.1`. To exercise the conditional
+`listPets` override, request `GET /v1/pets?demo=empty`.
+
+- `docker/compose.yaml`: local-only published port and a read-only spec mount.
+- `workflows/e2e.yml`: start the published CLI and wait for a healthy server.

package/examples/docker/compose.yaml

@@ -0,0 +1,7 @@
+services:
+  mockline:
+    build: ../..
+    ports: ['127.0.0.1:4010:4010']
+    volumes:
+      - ../petstore:/spec:ro
+    command: ['serve', '/spec/openapi.yaml', '--host', '0.0.0.0', '--port', '4010', '--inspector']

package/examples/petstore/mockline.yaml

@@ -0,0 +1,43 @@
+# Keep the mock on loopback for local development.
+port: 4010
+host: 127.0.0.1
+seed: 42
+prefer: example
+validate: warn
+latency: 0
+
+stateful:
+  enabled: true
+  seedItems: 3
+  idProperty: id
+
+generation:
+  hints: true
+  counter: false
+  maxDepth: 3
+  minArrayItems: 1
+  maxArrayItems: 3
+
+recording:
+  enabled: true
+  maxRequests: 500
+  redactHeaders:
+    - authorization
+    - cookie
+    - set-cookie
+    - x-api-key
+    - api-key
+    - x-auth-token
+
+# A conditional override is selected before stateful CRUD responses.
+overrides:
+  listPets:
+    rules:
+      - when:
+          location: query
+          name: demo
+          op: eq
+          value: empty
+        response:
+          status: 200
+          body: []

package/examples/petstore/openapi.yaml

@@ -0,0 +1,169 @@
+openapi: 3.0.3
+info:
+  title: Mockline Petstore Fixture
+  version: 1.0.0
+servers:
+  - url: https://api.example.test/v1
+paths:
+  /pets:
+    get:
+      operationId: listPets
+      parameters:
+        - name: limit
+          in: query
+          schema: { type: integer, minimum: 1, maximum: 100 }
+        - name: filter
+          in: query
+          style: deepObject
+          explode: true
+          schema:
+            type: object
+            properties:
+              active: { type: boolean }
+        - name: X-Trace
+          in: header
+          schema: { type: string }
+      responses:
+        '200':
+          description: A page of pets
+          content:
+            application/json:
+              examples:
+                kitten:
+                  summary: Small sample list
+                  value:
+                    - id: 17
+                      name: Miso
+                      tag: cat
+                      createdAt: '2025-01-02T03:04:05Z'
+              schema:
+                type: array
+                items: { $ref: '#/components/schemas/Pet' }
+    post:
+      operationId: createPet
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/PetInput' }
+      responses:
+        '201':
+          description: Created pet
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Pet' }
+  /pets/mine:
+    get:
+      operationId: getMyPets
+      responses:
+        '200':
+          description: Static path wins over petId
+          content:
+            application/json:
+              example: { id: 88, name: My pet, tag: dog }
+  /pets/{petId}:
+    parameters:
+      - name: petId
+        in: path
+        required: true
+        schema: { type: integer, minimum: 1 }
+    get:
+      operationId: getPet
+      responses:
+        '200':
+          description: Pet details
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Pet' }
+        '404':
+          description: Not found
+          content:
+            application/problem+json:
+              example: { title: Not Found, status: 404 }
+    put:
+      operationId: replacePet
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/PetInput' }
+      responses:
+        '200':
+          description: Replaced pet
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Pet' }
+    patch:
+      operationId: patchPet
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/PetInput' }
+      responses:
+        '200':
+          description: Updated pet
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Pet' }
+    delete:
+      operationId: deletePet
+      responses:
+        '204':
+          description: Deleted pet
+  /private:
+    get:
+      operationId: readPrivate
+      security:
+        - ApiKeyAuth: []
+      responses:
+        '200':
+          description: Protected response
+          content:
+            application/json:
+              example: { ok: true }
+  /hello:
+    get:
+      operationId: hello
+      responses:
+        '200':
+          description: Plain text greeting
+          content:
+            text/plain:
+              example: hello from mockline
+  /accept:
+    get:
+      operationId: acceptedMedia
+      responses:
+        '200':
+          description: Negotiated body
+          content:
+            application/json:
+              example: { format: json }
+            text/plain:
+              example: plain
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-API-Key
+  schemas:
+    PetInput:
+      type: object
+      required: [name]
+      properties:
+        name: { type: string, minLength: 2 }
+        tag: { type: string, enum: [cat, dog, bird] }
+        password: { type: string, writeOnly: true }
+        id: { type: integer, readOnly: true, minimum: 1 }
+    Pet:
+      allOf:
+        - $ref: '#/components/schemas/PetInput'
+        - type: object
+          required: [id, email, createdAt]
+          properties:
+            id: { type: integer, readOnly: true, minimum: 1 }
+            email: { type: string, format: email }
+            createdAt: { type: string, format: date-time }
+            password: { type: string, writeOnly: true }

package/examples/programmatic.ts

@@ -0,0 +1,23 @@
+import { createMockServer } from '@zahid15/mockline';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const exampleDirectory = resolve(fileURLToPath(new URL('.', import.meta.url)));
+const server = await createMockServer({
+  spec: resolve(exampleDirectory, 'petstore/openapi.yaml'),
+  port: 0,
+  seed: 42,
+  config: {
+    validate: 'warn',
+    stateful: { enabled: true, seedItems: 2 },
+  },
+});
+
+try {
+  console.log(`Mock API listening at ${server.url}`);
+  const response = await fetch(`${server.url}/v1/pets`);
+  console.log(await response.json());
+  console.log(`Recorded ${server.requests({ method: 'GET' }).length} GET request(s).`);
+} finally {
+  await server.close();
+}

package/examples/workflows/e2e.yml

@@ -0,0 +1,24 @@
+name: Mock API example
+on: workflow_dispatch
+permissions:
+  contents: read
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Start Mockline (after its first npm release)
+        run: |
+          npm install --global @zahid15/mockline@0.1.0
+          mockline serve examples/petstore/openapi.yaml --port 4010 --seed 42 > mockline.log 2>&1 &
+          for attempt in $(seq 1 30); do
+            if curl --fail --silent http://127.0.0.1:4010/__mockline/health; then exit 0; fi
+            sleep 1
+          done
+          cat mockline.log
+          exit 1
+      - name: Check the example route
+        run: curl --fail http://127.0.0.1:4010/v1/pets

package/package.json

@@ -1,6 +1,100 @@
 {
   "name": "@zahid15/mockline",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "A local mock API server and TypeScript library powered by OpenAPI.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@9.15.9",
+  "bin": {
+    "mockline": "dist/cli.js"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cli": {
+      "import": "./dist/cli.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CODE_OF_CONDUCT.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zahidhasann88/mockline.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zahidhasann88/mockline/issues"
+  },
+  "homepage": "https://github.com/zahidhasann88/mockline#readme",
+  "keywords": [
+    "openapi",
+    "mock-server",
+    "api",
+    "testing",
+    "typescript",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "node -e \"for (const p of ['dist', 'coverage']) require('node:fs').rmSync(p, { recursive: true, force: true })\"",
+    "lint": "eslint src tests scripts *.ts eslint.config.js",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "test": "tsup && vitest run --coverage",
+    "test:watch": "vitest",
+    "schema:config": "tsx scripts/generate-config-schema.ts",
+    "publint": "publint",
+    "attw": "attw --pack --profile esm-only",
+    "benchmark": "tsx scripts/benchmark.ts",
+    "pack:check": "tsup && node scripts/verify-pack.mjs",
+    "demo": "pnpm build && node scripts/demo.mjs"
+  },
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^12.1.0",
+    "@faker-js/faker": "^9.9.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "cac": "^6.7.14",
+    "chokidar": "^4.0.3",
+    "picocolors": "^1.1.1",
+    "yaml": "^2.7.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@eslint/js": "^9.26.0",
+    "@types/node": "^22.15.0",
+    "@vitest/coverage-v8": "^3.1.4",
+    "eslint": "^9.26.0",
+    "prettier": "^3.5.3",
+    "publint": "^0.3.12",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.31.0",
+    "vitest": "^3.1.4",
+    "zod-to-json-schema": "^3.24.5"
+  },
+  "author": "Zahid Hasan <jahidhasann67@gmail.com>"
+}