Jan26 extended logging + AI

.github/copilot-instructions.md

@@ -0,0 +1,48 @@
+# Copilot / AI Agent Instructions — ptr-be-core
+Shared TypeScript library for backend and frontend applications of the Panther project.
+
+## Important Rule
+Read and folow all `.github/instructions/*` files for code and practises clarity.
+
+## Repository Summary
+- This repo is a shared TypeScript library used by backend and frontend apps. 
+- It builds two entrypoints: `browser` and `node` (see `src/index.browser.ts` and `src/index.node.ts`). 
+- Node entrypoint includes server-only APIs and helpers (e.g., logging, API response models, Arrows.json parsing).
+- As build system, it uses `rollup` to produce ESM bundles in `dist/`.
+- The package is published locally with `yalc` for local integration and testing.
+
+## Mandatory folders / files
+- `src/`: main source code in TypeScript.
+- `tests/`: unit tests using Vitest.
+- `src/globals/`: global types and interfaces for both frontend and backend.
+- `src/node/`: Node.js specific code
+- `src/index.browser.ts`: exports for browser runtime.
+- `src/index.node.ts`: exports for Node.js runtime.
+- `dist/`: built artifacts (do not edit directly).
+- `package.json`: project metadata, scripts, and dependencies.
+- `rollup.config.js`: build configuration for rollup.
+- `tsconfig.json`: TypeScript configuration.
+- `vitest.config.ts`: configuration for Vitest test runner.
+- `docs/`: documentation files (if any).
+- `.github/`: GitHub-specific files including workflows and instructions.
+
+# Testing and Linting
+- Using Vitest as the test framework and typescript for type safety.
+- Please folow `.github/instructions/testing.instructions.md` for testing-related guidelines.
+- This project uses ESLint major version 8 for code linting.
+- Read `eslint.config.js` for detailed linting rules and configurations.
+
+# Build and Publish goals
+- Always build two bundles: browser and node.
+- Use `rollup` for bundling.
+- Build declaration files (`.d.ts`) for type safety.
+- Publish the package locally using `yalc` for testing in other projects before actual publishing.
+- Read `.github/instructions/build.instructions.md` for detailed build and publish guidelines.
+
+# Delivered Features
+- Logging utilities for Node.js applications (`src/node/logging/logger.ts`).
+- API response models for consistent API responses (`src/node/api/models.api.ts`).
+- Functions to parse and validate Arrows.app JSON format (`src/node/api/parse.arrows.json.ts`).
+- Utility functions for parsing and validating raw input data (`src/node/api/parse.raw.input.ts`).
+- Global types and interfaces shared between frontend and backend (`src/globals/arrows/`, `src/globals/panther/`).
+- General shared coding helpers and formaters (`src/globals/coding/`)

.github/instructions/build.instructions.md

@@ -0,0 +1,15 @@
+---
+applyTo: "**/*"
+---
+
+# Build strategy for this repository
+- This repository product is NPM package (library) written in TypeScript.
+- The package targets two runtimes: browser and Node.js.
+- The build system uses `rollup` to create two separate bundles: one for browser and one for Node.js.
+- Each bundle has its own entrypoint: `src/index.browser.ts` for browser and `src/index.node.ts` for Node.js.
+- The build process also generates TypeScript declaration files (`.d.ts`) for type safety.
+- The built artifacts are placed in the `dist/` directory.
+- The package is published locally using `yalc` for testing in other projects before actual publishing to a package registry.
+- The build and publish process is automated using NPM scripts defined in `package.json`.
+- Check the `rollup.config.js` for detailed build configuration and options.
+- Check all tsconfig*.json files for TypeScript compilation settings.

.github/instructions/coding.instructions.md

@@ -0,0 +1,17 @@
+---
+applyTo: "src/**/*.ts"
+---
+
+# General programming style guidlines for this repository
+- Code is written in TypeScript.
+- Use ES modules (`import` / `export`) for module management.
+- Prefer functional programming paradigms where possible.
+- Write small, single-responsibility functions.
+- Use explicit types for function parameters and return types.
+- Use async/await for asynchronous operations.
+- Handle errors gracefully using try/catch blocks.
+- Write JSDoc comments for all public functions and classes.
+- Prefer arrow functions for anonymous functions.
+- Use modern ECMAScript features (e.g., destructuring, spread/rest operators).
+- Keep code DRY (Don't Repeat Yourself) by reusing functions and modules.
+- Use function prefixes to group them by purpose (e.g., `parse`, `validate`, `fetch`, `calculate`).

.github/instructions/testing.instructions.md

@@ -0,0 +1,23 @@
+---
+applyTo: "src/tests/**/*.spec.ts, src/tests/**/*.test.ts"
+---
+
+# Testing Instructions for this repository
+- All tests are located in the `src/tests/` directory.
+- Use Vitest as the testing framework.
+- Write tests in TypeScript for type safety.
+- Try to avoid mocking libraries. Prefer to create own mocks or stubs as needed.
+
+## Test content folder structure
+- Test files should have a `.spec.ts` suffix.
+- Test cases, that do not require external dependencies as databases or APIs, should be placed in `src/tests/functional/`.
+- Integration tests, that require external dependencies, should be placed in `src/tests/integration/`.
+- Test-only helpers should be placed in `src/tests/tools/`.
+- Fixtures as test data or test files should be placed in `src/tests/fixtures/`.
+
+## Test file structure
+- Name each test file with the name of the module structure it is testing, followed by `.spec.ts`. Example: `parsing.dates.spec.ts`, `api.errors.spec.ts` etc.
+- Inside the test file, use single `describe` block with human-readable description.
+- Each `it` block should have human readable description and test a single behavior or scenario.
+- Use `beforeAll`, `beforeEach`, `afterAll`, and `afterEach` hooks as needed for setup and teardown.
+- In the case of async operations, use `async/await` syntax for clarity in `it` blocks.

AGENTS.md

@@ -0,0 +1,48 @@
+# Copilot / AI Agent Instructions — ptr-be-core
+Shared TypeScript library for backend and frontend applications of the Panther project.
+
+## Important Rule
+Read and folow all `.github/instructions/*` files for code and practises clarity.
+
+## Repository Summary
+- This repo is a shared TypeScript library used by backend and frontend apps. 
+- It builds two entrypoints: `browser` and `node` (see `src/index.browser.ts` and `src/index.node.ts`). 
+- Node entrypoint includes server-only APIs and helpers (e.g., logging, API response models, Arrows.json parsing).
+- As build system, it uses `rollup` to produce ESM bundles in `dist/`.
+- The package is published locally with `yalc` for local integration and testing.
+
+## Mandatory folders / files
+- `src/`: main source code in TypeScript.
+- `tests/`: unit tests using Vitest.
+- `src/globals/`: global types and interfaces for both frontend and backend.
+- `src/node/`: Node.js specific code
+- `src/index.browser.ts`: exports for browser runtime.
+- `src/index.node.ts`: exports for Node.js runtime.
+- `dist/`: built artifacts (do not edit directly).
+- `package.json`: project metadata, scripts, and dependencies.
+- `rollup.config.js`: build configuration for rollup.
+- `tsconfig.json`: TypeScript configuration.
+- `vitest.config.ts`: configuration for Vitest test runner.
+- `docs/`: documentation files (if any).
+- `.github/`: GitHub-specific files including workflows and instructions.
+
+# Testing and Linting
+- Using Vitest as the test framework and typescript for type safety.
+- Please folow `.github/instructions/testing.instructions.md` for testing-related guidelines.
+- This project uses ESLint major version 8 for code linting.
+- Read `eslint.config.js` for detailed linting rules and configurations.
+
+# Build and Publish goals
+- Always build two bundles: browser and node.
+- Use `rollup` for bundling.
+- Build declaration files (`.d.ts`) for type safety.
+- Publish the package locally using `yalc` for testing in other projects before actual publishing.
+- Read `.github/instructions/build.instructions.md` for detailed build and publish guidelines.
+
+# Delivered Features
+- Logging utilities for Node.js applications (`src/node/logging/logger.ts`).
+- API response models for consistent API responses (`src/node/api/models.api.ts`).
+- Functions to parse and validate Arrows.app JSON format (`src/node/api/parse.arrows.json.ts`).
+- Utility functions for parsing and validating raw input data (`src/node/api/parse.raw.input.ts`).
+- Global types and interfaces shared between frontend and backend (`src/globals/arrows/`, `src/globals/panther/`).
+- General shared coding helpers and formaters (`src/globals/coding/`)

eslint.config.mjs

@@ -20,6 +20,7 @@ export default defineConfig([
     ],
     rules: {
       "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unused-vars": "off",
     },
   },
 ]);