@gxp-dev/tools 2.0.70 → 2.0.72

package/README.md

@@ -1,16 +1,16 @@
 # GxP Dev Tools
 
-A development toolkit for creating plugins for the GxP kiosk platform. Provides CLI tools, project scaffolding, an interactive TUI, and a development environment that emulates the GxP platform.
+A development toolkit for building plugins for the GxP kiosk platform. Ships a CLI, an interactive TUI, a platform emulator for local dev, a JSON-config linter, and a Model Context Protocol (MCP) server that gives AI coding assistants 29 specialized tools across API specs, config editing, documentation search, and test scaffolding.
 
 ## Installation
 
-### Global (Recommended)
+### Global (recommended)
 
 ```bash
 npm install -g @gxp-dev/tools
 ```
 
-### Project-Level
+### Project-level
 
 ```bash
 npm install --save-dev @gxp-dev/tools
@@ -19,30 +19,26 @@ npm install --save-dev @gxp-dev/tools
 ### Updating
 
 ```bash
-# Global
-npm update -g @gxp-dev/tools
-
-# Project-level
-npm update @gxp-dev/tools
+npm update -g @gxp-dev/tools        # global
+npm update @gxp-dev/tools           # project-level
 ```
 
-After updating, run `gxdev init` in existing projects to sync dependencies and config files.
+After updating, run `gxdev init` in existing projects to sync required dependencies, scripts, and config files.
 
 ## Quick Start
 
-### New Project
+### New project
 
 ```bash
 gxdev init my-plugin
 cd my-plugin
+npm install
 npm run dev-http
 ```
 
-Your plugin is running at `http://localhost:3060`. Press `Ctrl+Shift+D` to open the in-browser Dev Tools.
-
-### Existing Project
+Open `http://localhost:3060`. Press `Ctrl+Shift+D` for the in-browser Dev Tools (Store Inspector, Layout Switcher, Socket Simulator, Mock Data Editor).
 
-If you already have a Vue/Vite project:
+### Adding to an existing project
 
 ```bash
 cd my-existing-project
@@ -51,102 +47,133 @@ npm install
 npm run dev-http
 ```
 
-When run in a directory with an existing `package.json` (no name argument), `gxdev init` will:
+When run in a directory with an existing `package.json` and no name argument, `gxdev init`:
 
-- Add missing required dependencies and devDependencies
-- Update mismatched dependency versions
-- Add missing npm scripts (`dev`, `build`, `dev-http`, etc.)
-- Back up your existing `vite.config.js` to `vite.config.js.backup`
-- Copy config files (`app-manifest.json`, `.env.example`, store setup, AI agent configs)
+- Adds missing required dependencies and devDependencies (Vue, Pinia, Vite, ESLint, Prettier, Vitest, Vue Test Utils, toolkit itself).
+- Sets `"type": "module"` if the field is missing (preserves an explicit `"commonjs"`).
+- Adds missing npm scripts (`dev`, `build`, `test`, `lint`, `format`, `prepare`, socket/assets/datastore helpers).
+- Copies bundle files: `app-manifest.json`, `configuration.json`, `app-instructions.md`, `vite.extend.js`, `eslint.config.js`, `.prettierrc`, `.githooks/pre-commit`, `.env.example`, store setup, AI agent configs.
+- Creates `src/public/` for static assets (served by Vite at `/src/public/*`).
 
-It will **not** overwrite your source files (`src/`, `theme-layouts/`, etc.).
+It does **not** overwrite your source files (`src/`, `theme-layouts/`, etc.).
 
 ## CLI Commands
 
-| Command                    | Description                                            |
-| -------------------------- | ------------------------------------------------------ |
-| `gxdev`                    | Launch interactive TUI                                 |
-| `gxdev init [name]`        | Create a new project or update an existing one         |
-| `gxdev dev`                | Start development server (HTTPS + TUI)                 |
-| `gxdev dev --no-https`     | Start with HTTP only                                   |
-| `gxdev dev --with-socket`  | Start with Socket.IO server                            |
-| `gxdev dev --chrome`       | Start and launch Chrome with extension                 |
-| `gxdev dev --firefox`      | Start and launch Firefox with extension                |
-| `gxdev build`              | Build plugin for production                            |
-| `gxdev setup-ssl`          | Generate SSL certificates for HTTPS development        |
-| `gxdev publish <file>`     | Copy runtime files to your project for customization   |
-| `gxdev datastore <action>` | Manage GxP datastore (list, add, scan-strings, config) |
-| `gxdev socket <action>`    | Simulate socket events (list, send)                    |
-| `gxdev assets <action>`    | Manage development assets (list, init, generate)       |
-| `gxdev add-dependency`     | Add API dependency via interactive wizard              |
-| `gxdev extract-config`     | Extract GxP config from source files                   |
-| `gxdev ext:chrome`         | Launch Chrome with browser extension                   |
-| `gxdev ext:firefox`        | Launch Firefox with browser extension                  |
-| `gxdev ext:build`          | Build browser extensions for distribution              |
+| Command                            | Description                                                                                                                                                                                           |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `gxdev`                            | Launch the interactive TUI                                                                                                                                                                            |
+| `gxdev init [name]`                | Create a new project or update an existing one                                                                                                                                                        |
+| `gxdev dev`                        | Start the dev server (HTTPS + Vite + Socket.IO)                                                                                                                                                       |
+| `gxdev dev --no-https`             | HTTP only                                                                                                                                                                                             |
+| `gxdev dev --no-socket`            | Skip the Socket.IO server                                                                                                                                                                             |
+| `gxdev dev --with-mock`            | Enable the local Mock API (routes under `/api/*`)                                                                                                                                                     |
+| `gxdev dev --chrome`               | Start dev + launch Chrome with the inspector extension                                                                                                                                                |
+| `gxdev dev --firefox`              | Start dev + launch Firefox with the inspector extension                                                                                                                                               |
+| `gxdev build`                      | Build the plugin for production → `dist/<name>.gxpapp`                                                                                                                                                |
+| `gxdev lint [files..]`             | Validate `configuration.json` / `app-manifest.json` against the templating schema. `--all` lints every known config file in the project. `--json` emits machine-readable results.                     |
+| `gxdev extract-config`             | Scan `src/` for GxP directives and store calls; merge findings into `app-manifest.json`                                                                                                               |
+| `gxdev add-dependency`             | Build an API dependency entry via interactive wizard                                                                                                                                                  |
+| `gxdev setup-ssl`                  | Generate local SSL certificates via mkcert                                                                                                                                                            |
+| `gxdev publish <file>`             | Copy a runtime file (`main.js`, `index.html`, `server.cjs`, `gxpPortalConfigStore.js`) into the project for customization. For Vite config changes, use `vite.extend.js` at the project root instead. |
+| `gxdev datastore <action>`         | Manage the GxP datastore (`list`, `add`, `scan-strings`, `config`)                                                                                                                                    |
+| `gxdev socket <action>`            | Simulate socket events (`list`, `send`)                                                                                                                                                               |
+| `gxdev assets <action>`            | Manage dev assets (`list`, `init`, `generate`)                                                                                                                                                        |
+| `gxdev ext:chrome` / `ext:firefox` | Launch the browser inspector extension                                                                                                                                                                |
+| `gxdev ext:build`                  | Build the browser extensions for distribution                                                                                                                                                         |
 
 ## Features
 
-- **Platform Emulator** - PortalContainer.vue mimics the GxP platform environment
-- **Interactive TUI** - Terminal UI for managing dev services, logs, and slash commands
-- **Hot Module Replacement** - Instant updates during development
-- **Socket.IO Integration** - Test real-time features with simulated events
-- **SSL Support** - HTTPS development with auto-generated certificates
-- **Browser Extensions** - Chrome/Firefox DevTools panel for inspecting plugins
-- **Dev Tools Modal** - In-browser tools for inspecting state, switching layouts, and more (Ctrl+Shift+D)
-- **AI Scaffolding** - Generate starter code with Claude, Codex, or Gemini during init
-- **Mock API** - Local mock API server with OpenAPI spec integration
-- **Asset Generation** - Create placeholder images for development
+- **Platform emulator** — `PortalContainer.vue` mimics the live GxP environment so plugins render exactly like production.
+- **Interactive TUI** — terminal UI for managing dev services, streaming logs, and firing slash commands.
+- **HMR + HTTPS** — Vite 8 dev server with mkcert-generated certs (or HTTP fallback).
+- **GxP Strings Plugin** — `gxp-string` / `gxp-src` / `gxp-settings` / `gxp-state` directives pull live values from the datastore, editable in the in-browser Dev Tools.
+- **Socket.IO integration** — real-time events with a local server; CLI `socket send` simulates events on demand.
+- **Mock API** — OpenAPI-driven local mock (auto-loads platform specs, routes under `/api/*`).
+- **Browser extensions** — Chrome/Firefox DevTools panels for inspecting Vue component trees and GxP state.
+- **Config linting** — AJV-based JSON Schema validation of `configuration.json` (form-builder definitions) and `app-manifest.json` (plugin metadata + defaults).
+- **Pre-commit hook** — `.githooks/pre-commit` runs Prettier, ESLint, and the GxP linter on staged files; configured automatically via the `prepare` npm script.
+- **Unit testing** — Vitest + `@vue/test-utils` wired out of the box; scaffolded tests via the MCP server.
+- **MCP server** — 29 tools for AI coding assistants (see below).
+- **AI scaffolding** — pre-wired configs for Claude Code, Codex, and Gemini during `init`.
+
+## MCP Server for AI assistants
+
+The toolkit ships `gxp-api-server` (bin `@gxp-dev/tools/mcp/gxp-api-server.js`), an MCP server exposing 29 tools across five families. Point your AI assistant at it to get API-aware, schema-aware, test-aware help inside plugin projects:
+
+| Family                 | Tools                                                                                                                                                                                                                                                                                               |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **API spec** (6)       | `get_openapi_spec`, `get_asyncapi_spec`, `search_api_endpoints`, `search_websocket_events`, `get_endpoint_details`, `get_api_environment`                                                                                                                                                           |
+| **Extended API** (5)   | `api_list_tags`, `api_list_operation_ids`, `api_get_operation_parameters`, `api_find_endpoints_by_schema`, `api_generate_dependency`                                                                                                                                                                |
+| **Config editor** (13) | `config_validate`, `config_list_field_types`, `config_list_card_types`, `config_get_field_schema`, `config_list_cards`, `config_list_fields`, `config_add_field`, `config_move_field`, `config_remove_field`, `config_add_card`, `config_move_card`, `config_remove_card`, `config_extract_strings` |
+| **Docs search** (3)    | `docs_list_pages`, `docs_search`, `docs_get_page` — full-text across `docs.gxp.dev` via its sitemap                                                                                                                                                                                                 |
+| **Test helpers** (2)   | `test_scaffold_component_test`, `test_api_route`                                                                                                                                                                                                                                                    |
+
+Every config mutation is linter-guarded: invalid writes are refused unless `force: true`, so AI agents can't save broken state.
 
 ## Project Structure
 
-After `gxdev init`, your project contains:
+After `gxdev init`:
 
 ```
 my-plugin/
 ├── src/
-│   ├── Plugin.vue          # Main plugin entry point
-│   ├── DemoPage.vue        # Example component
+│   ├── Plugin.vue              # App entry point
+│   ├── DemoPage.vue            # Example component
+│   ├── public/                 # Static assets (served at /src/public/*)
 │   └── stores/
-│       └── index.js        # Pinia store setup
-├── theme-layouts/          # Layout components (Public, Private, System)
-├── dev-assets/images/      # Development placeholder images
-├── socket-events/          # Socket event templates
-├── app-manifest.json       # Plugin configuration (strings, settings, assets)
-├── .env                    # Environment variables
+│       └── index.js            # Pinia store setup
+├── theme-layouts/              # System/Private/Public layouts
+├── dev-assets/images/          # Dev placeholder images
+├── socket-events/              # Socket event templates for simulation
+├── tests/                      # Vitest test files (scaffolded as you go)
+├── scripts/                    # Browser extension launch/pack scripts
+├── .githooks/pre-commit        # Prettier + ESLint + gxdev lint on staged files
+├── app-manifest.json           # Plugin metadata + default strings/settings/assets
+├── app-instructions.md         # End-user onboarding doc (shown on install)
+├── configuration.json          # Admin-panel config form definition
+├── vite.extend.js              # Optional Vite config extension (aliases, plugins)
+├── eslint.config.js            # ESLint flat config (JS + Vue)
+├── .prettierrc                 # Prettier config
 └── package.json
 ```
 
-The dev server automatically serves `index.html` and `main.js` from the toolkit runtime — no local copies needed.
+The dev server serves `index.html` and `main.js` from the toolkit runtime — no local copies needed unless you opt in with `USE_LOCAL_INDEX` / `USE_LOCAL_MAIN`.
 
 ## Environment Variables
 
-Key variables (set in `.env`):
-
-| Variable            | Default            | Description                                                              |
-| ------------------- | ------------------ | ------------------------------------------------------------------------ |
-| `NODE_PORT`         | `3060`             | Development server port                                                  |
-| `SOCKET_IO_PORT`    | `3061`             | Socket.IO server port                                                    |
-| `COMPONENT_PATH`    | `./src/Plugin.vue` | Main component path                                                      |
-| `USE_HTTPS`         | `true`             | Enable HTTPS                                                             |
-| `CERT_PATH`         |                    | SSL certificate path                                                     |
-| `KEY_PATH`          |                    | SSL private key path                                                     |
-| `USE_LOCAL_INDEX`   |                    | Set to `true` to use a local `index.html` instead of the runtime version |
-| `USE_LOCAL_MAIN`    |                    | Set to `true` to use a local `main.js` instead of the runtime version    |
-| `SOCKET_IO_ENABLED` | `false`            | Auto-start Socket.IO                                                     |
-| `API_ENV`           | `mock`             | API environment (mock, local, development, staging, production)          |
-
-## Runtime vs Template
-
-- **Runtime files** stay in `node_modules/` and are served automatically (`index.html`, `main.js`, store, dev tools, Vite config). Override `index.html`/`main.js` with `USE_LOCAL_INDEX`/`USE_LOCAL_MAIN` env vars. Use `gxdev publish` to copy other runtime files locally for customization.
+Set in `.env` at the project root:
+
+| Variable                 | Default            | Description                                                                      |
+| ------------------------ | ------------------ | -------------------------------------------------------------------------------- |
+| `NODE_PORT`              | `3060`             | Dev server port                                                                  |
+| `SOCKET_IO_PORT`         | `3069`             | Socket.IO server port                                                            |
+| `COMPONENT_PATH`         | `./src/Plugin.vue` | Main component path                                                              |
+| `USE_HTTPS`              | `true`             | Enable HTTPS                                                                     |
+| `CERT_PATH` / `KEY_PATH` |                    | SSL cert/key paths (auto-set by `setup-ssl`)                                     |
+| `USE_LOCAL_INDEX`        |                    | `true` to serve a local `index.html` instead of the runtime version              |
+| `USE_LOCAL_MAIN`         |                    | `true` to serve a local `main.js` instead of the runtime version                 |
+| `DISABLE_SOURCE_TRACKER` |                    | `true` to skip the source-tracking Vite plugin                                   |
+| `DISABLE_INSPECTOR`      |                    | `true` to skip the component inspector plugin                                    |
+| `API_ENV`                | `mock`             | API environment (`mock`, `local`, `develop`, `testing`, `staging`, `production`) |
+| `MOCK_API_ENABLED`       | `false`            | Mount the local mock API at `/api/*`                                             |
+| `ALLOWED_HOSTS`          |                    | Comma-separated list of additional hostnames the dev server should accept        |
+
+## Runtime vs. template
+
+- **Runtime files** stay in `node_modules/@gxp-dev/tools/runtime/` and are used via imports or served by Vite at request time (`index.html`, `main.js`, store, dev tools, Vite config, inspector plugins). Override `index.html` / `main.js` with the `USE_LOCAL_*` env vars. Use `gxdev publish <file>` to copy other runtime files locally.
 - **Template files** are copied to your project during `gxdev init` and are fully yours to edit.
+- **`vite.extend.js`** at the project root is deep-merged into the runtime Vite config via `mergeConfig` — add aliases, plugins, and `define` keys without replacing the whole config.
 
 ## Documentation
 
-Full documentation is available at the [GxP Documentation site](https://docs.gramercytech.com/gx-devtools).
+- **Full docs**: [docs.gxp.dev](https://docs.gxp.dev)
+- **CLI reference**: `gxdev --help` or [docs.gxp.dev/gx-devtools/cli-reference](https://docs.gxp.dev/gx-devtools/cli-reference)
+- **Getting started**: [docs.gxp.dev/gx-devtools/getting-started](https://docs.gxp.dev/gx-devtools/getting-started)
+- **Platform templating system**: [docs.gxp.dev/platform/plugin-system](https://docs.gxp.dev/platform/plugin-system)
 
 ## Contributing
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, architecture details, and how to make changes to the toolkit itself.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, architecture, and how to extend the toolkit itself.
 
 ## License
 

package/bin/lib/cli.js

@@ -24,6 +24,7 @@ const {
 	extensionInstallCommand,
 	extractConfigCommand,
 	addDependencyCommand,
+	lintCommand,
 } = require("./commands")
 
 // Load global configuration
@@ -301,6 +302,23 @@ yargs
 		},
 		extractConfigCommand,
 	)
+	.command(
+		"lint [files..]",
+		"Lint GxP config JSON (configuration.json, app-manifest.json) against the templating schema",
+		{
+			all: {
+				describe: "Lint all known config files in the project root",
+				type: "boolean",
+				default: false,
+			},
+			json: {
+				describe: "Output results as JSON instead of terminal report",
+				type: "boolean",
+				default: false,
+			},
+		},
+		lintCommand,
+	)
 	.command(
 		"add-dependency",
 		"Add an API dependency to app-manifest.json via interactive wizard",

package/bin/lib/commands/index.js

@@ -20,6 +20,7 @@ const {
 } = require("./extensions")
 const { extractConfigCommand } = require("./extract-config")
 const { addDependencyCommand } = require("./add-dependency")
+const { lintCommand } = require("./lint")
 
 module.exports = {
 	initCommand,
@@ -36,4 +37,5 @@ module.exports = {
 	extensionInstallCommand,
 	extractConfigCommand,
 	addDependencyCommand,
+	lintCommand,
 }

package/bin/lib/commands/init.js

@@ -127,6 +127,22 @@ function copyBundleFiles(projectPath, paths, overwrite = false) {
 			dest: "vite.extend.js",
 			desc: "vite.extend.js (customize the Vite runtime config)",
 		},
+		{
+			src: "eslint.config.js",
+			dest: "eslint.config.js",
+			desc: "eslint.config.js (flat config for JS/Vue)",
+		},
+		{
+			src: ".prettierrc",
+			dest: ".prettierrc",
+			desc: ".prettierrc (format config)",
+		},
+		{
+			src: "githooks/pre-commit",
+			dest: ".githooks/pre-commit",
+			desc: ".githooks/pre-commit (runs prettier + eslint + gxdev lint)",
+			mode: 0o755,
+		},
 		{ src: "env.example", dest: ".env.example", desc: ".env.example" },
 		{ src: "gitignore", dest: ".gitignore", desc: ".gitignore" },
 		{
@@ -162,6 +178,13 @@ function copyBundleFiles(projectPath, paths, overwrite = false) {
 		const srcPath = path.join(paths.templateDir, file.src)
 		const destPath = path.join(projectPath, file.dest)
 		safeCopyFile(srcPath, destPath, file.desc, overwrite)
+		if (file.mode && fs.existsSync(destPath)) {
+			try {
+				fs.chmodSync(destPath, file.mode)
+			} catch (_e) {
+				// Best-effort — Windows or restrictive FS may reject chmod.
+			}
+		}
 	})
 }
 /**

package/bin/lib/commands/lint.js

@@ -0,0 +1,77 @@
+/**
+ * Lint Command
+ *
+ * Validates GxP config JSON (configuration.json, app-manifest.json) against
+ * schemas derived from the templating system docs.
+ */
+
+const path = require("path")
+const fs = require("fs")
+const { lintFiles, detectSchema } = require("../lint")
+const { formatReport } = require("../lint/formatter")
+const { findProjectRoot } = require("../utils")
+
+/**
+ * Targets for `--all` mode. Extendable as more lintable files emerge.
+ */
+const DEFAULT_TARGETS = ["configuration.json", "app-manifest.json"]
+
+function collectAllTargets(projectPath) {
+	return DEFAULT_TARGETS.map((name) => path.join(projectPath, name)).filter(
+		(p) => fs.existsSync(p),
+	)
+}
+
+async function lintCommand(argv) {
+	const projectPath = findProjectRoot()
+	const explicit = Array.isArray(argv.files) ? argv.files.filter(Boolean) : []
+
+	let files
+	let userSuppliedFiles = false
+	if (explicit.length > 0) {
+		// Resolve relative to the cwd the user ran from.
+		files = explicit.map((f) => path.resolve(process.cwd(), f))
+		userSuppliedFiles = true
+	} else {
+		// No files given: default to the well-known targets in the project root.
+		files = collectAllTargets(projectPath)
+	}
+
+	if (files.length === 0) {
+		console.log(
+			"No configuration.json or app-manifest.json found in project root.",
+		)
+		return
+	}
+
+	// Drop files we don't have a schema for, unless the user named them
+	// explicitly — in that case surface them as skipped in the report.
+	if (!userSuppliedFiles) {
+		files = files.filter((f) => detectSchema(f))
+	}
+
+	const { results, summary } = lintFiles(files)
+
+	if (argv.json) {
+		const out = {
+			summary,
+			results: results.map((r) => ({
+				file: r.file,
+				ok: r.ok,
+				skipped: r.skipped,
+				errors: r.errors,
+			})),
+		}
+		console.log(JSON.stringify(out, null, 2))
+	} else {
+		console.log(formatReport({ results, summary }, { cwd: projectPath }))
+	}
+
+	if (summary.filesWithErrors > 0) {
+		process.exit(1)
+	}
+}
+
+module.exports = {
+	lintCommand,
+}

package/bin/lib/constants.js

@@ -16,6 +16,12 @@ const REQUIRED_DEPENDENCIES = {
 
 const REQUIRED_DEV_DEPENDENCIES = {
 	"@gxp-dev/tools": "^2.0.0",
+	eslint: "^10.2.1",
+	"eslint-plugin-vue": "^10.9.0",
+	globals: "^17.5.0",
+	prettier: "^3.8.3",
+	vitest: "^4.1.5",
+	"@vue/test-utils": "^2.4.6",
 }
 
 // Default scripts for package.json
@@ -24,6 +30,12 @@ const DEFAULT_SCRIPTS = {
 	"dev-app": "gxdev dev",
 	"dev-http": "gxdev dev --no-https",
 	build: "gxdev build",
+	test: "vitest run",
+	"test:watch": "vitest",
+	lint: "gxdev lint --all",
+	"lint:js": "eslint .",
+	format: "prettier --write .",
+	prepare: "git config core.hooksPath .githooks || true",
 	"setup-ssl": "gxdev setup-ssl",
 	"socket:list": "gxdev socket list",
 	"socket:send": "gxdev socket send",

package/bin/lib/lint/formatter.js

@@ -0,0 +1,91 @@
+/**
+ * Terminal output formatter for GxP linter results.
+ *
+ * Uses raw ANSI codes (no extra dep). Auto-disables color when stdout is not
+ * a TTY or when NO_COLOR is set.
+ */
+
+const path = require("path")
+
+const USE_COLOR = process.stdout.isTTY && !process.env.NO_COLOR
+
+function wrap(code) {
+	return (str) => (USE_COLOR ? `\x1b[${code}m${str}\x1b[0m` : String(str))
+}
+
+const red = wrap("31")
+const green = wrap("32")
+const yellow = wrap("33")
+const blue = wrap("34")
+const magenta = wrap("35")
+const cyan = wrap("36")
+const gray = wrap("90")
+const bold = wrap("1")
+const dim = wrap("2")
+
+function formatResult(result, { cwd = process.cwd() } = {}) {
+	const lines = []
+	const rel = path.relative(cwd, result.file) || result.file
+
+	if (result.skipped) {
+		lines.push(gray(`  ${rel} — skipped (${result.reason || "no schema"})`))
+		return lines.join("\n")
+	}
+
+	if (result.ok) {
+		lines.push(`  ${green("✓")} ${rel}`)
+		return lines.join("\n")
+	}
+
+	lines.push(`  ${red("✗")} ${bold(rel)}`)
+	for (const err of result.errors) {
+		const loc = gray(`${result.file}:${err.line}:${err.column}`)
+		const code = dim(`[${err.code}]`)
+		lines.push(`    ${red("error")} ${code} ${err.message}`)
+		lines.push(`       ${loc}`)
+	}
+	return lines.join("\n")
+}
+
+function formatReport({ results, summary }, opts = {}) {
+	const lines = []
+	lines.push(bold(cyan("\nGxP config lint")))
+	lines.push(
+		gray(`  ${summary.totalFiles} file(s) scanned, ${summary.skipped} skipped`),
+	)
+	lines.push("")
+
+	for (const r of results) {
+		lines.push(formatResult(r, opts))
+	}
+
+	lines.push("")
+	if (summary.totalErrors === 0 && summary.filesWithErrors === 0) {
+		lines.push(green(bold("✓ No problems found.")))
+	} else {
+		lines.push(
+			red(
+				bold(
+					`✗ ${summary.totalErrors} error(s) in ${summary.filesWithErrors} file(s).`,
+				),
+			),
+		)
+	}
+	return lines.join("\n")
+}
+
+module.exports = {
+	formatResult,
+	formatReport,
+	colors: {
+		red,
+		green,
+		yellow,
+		blue,
+		magenta,
+		cyan,
+		gray,
+		bold,
+		dim,
+	},
+}