From 00f366f07c71a2c7a1df4a380c3bba8c530fb71f Mon Sep 17 00:00:00 2001 From: Arthur van de Vondervoort Date: Wed, 29 Apr 2026 11:37:10 +0200 Subject: [PATCH 1/2] docs: add README.md and CONTRIBUTING.md Add project documentation following npm best practices: - README with badges, CLI reference, examples, CI/CD snippet, and API overview - CONTRIBUTING with dev setup, workflow, scripts, and PR guidelines Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 72 +++++++++++++++++++++++++++ README.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 199 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5318ff5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,72 @@ +# Contributing to @alcops/core + +Thanks for your interest in contributing! This document explains how to get started. + +## Getting Started + +1. Fork the repository and clone your fork: + + ```bash + git clone https://github.com//npm-package.git + cd npm-package + ``` + +2. Install dependencies: + + ```bash + npm install + ``` + +3. Verify everything works: + + ```bash + npm test + ``` + +## Development Workflow + +1. Create a branch from `main`: + + ```bash + git checkout -b feature/my-change + ``` + +2. Make your changes and ensure the checks pass: + + ```bash + npm run lint # ESLint + npm test # Vitest + npm run build # TypeScript compilation + npm run bundle # esbuild production bundle + ``` + +3. Commit your changes with a clear message. + +4. Push and open a pull request against `main`. + +## Available Scripts + +| Script | Purpose | +|--------|---------| +| `npm run lint` | Run ESLint on `src/` | +| `npm test` | Run tests with Vitest | +| `npm run test:watch` | Run tests in watch mode | +| `npm run build` | Compile TypeScript | +| `npm run bundle` | Build production bundle with esbuild | + +## Code Style + +- TypeScript in strict mode +- ESLint rules are enforced via `npm run lint` +- CI runs lint, tests, build, and bundle on every pull request + +## Pull Request Guidelines + +- Open an issue first for large or breaking changes so we can discuss the approach. +- Keep PRs focused on a single change. +- Add tests for new functionality. +- CI must pass before a PR can be merged. + +## Releases + +Releases are automated. When changes are merged to `main`, the maintainers trigger a release workflow that versions the package with [GitVersion](https://gitversion.net/), publishes to npm, and creates a GitHub Release. diff --git a/README.md b/README.md new file mode 100644 index 0000000..b87cc28 --- /dev/null +++ b/README.md @@ -0,0 +1,127 @@ +# @alcops/core + +[![CI](https://github.com/ALCops/npm-package/actions/workflows/ci.yml/badge.svg)](https://github.com/ALCops/npm-package/actions/workflows/ci.yml) +[![npm](https://img.shields.io/npm/v/@alcops/core)](https://www.npmjs.com/package/@alcops/core) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) + +Detect the Target Framework Moniker (TFM) used by Business Central, so you can build AL extensions with the correct analyzer version. Designed for CI/CD pipelines. + +## Features + +- Detect the TFM from four different sources: + - **BC artifact URL** (e.g. a sandbox or OnPrem artifact) + - **VS Marketplace** (the AL Language extension) + - **NuGet DevTools** (Microsoft's AL development tools package) + - **Local compiler path** (a directory containing the AL compiler DLLs) +- JSON output on stdout, logs on stderr (pipe-friendly) +- Zero configuration required +- Usable as a CLI or as a Node.js library + +## Installation + +```bash +# Install globally +npm install -g @alcops/core + +# Or run directly with npx +npx @alcops/core detect-tfm marketplace +``` + +## Requirements + +- Node.js >= 20 + +## CLI Usage + +``` +alcops [args] + +Commands: + detect-tfm bc-artifact Detect TFM from a BC artifact URL + detect-tfm marketplace [channel] Detect TFM from VS Marketplace (default: current) + detect-tfm nuget-devtools [version] Detect TFM from NuGet DevTools (default: latest) + detect-tfm compiler-path Detect TFM from a local compiler directory + +Options: + --help Show this help message +``` + +### Examples + +Detect from the VS Marketplace (most common): + +```bash +alcops detect-tfm marketplace +``` + +Detect from a specific NuGet DevTools version: + +```bash +alcops detect-tfm nuget-devtools 26.0.12345 +``` + +Detect from a BC artifact URL: + +```bash +alcops detect-tfm bc-artifact "https://bcartifacts.azureedge.net/sandbox/26.0.12345.0/us" +``` + +Detect from a local compiler directory: + +```bash +alcops detect-tfm compiler-path ./path/to/compiler +``` + +### Output + +All commands write JSON to stdout: + +```json +{ + "tfm": "net8.0", + "source": "marketplace", + "details": "AL Language extension v14.0.12345" +} +``` + +Logs go to stderr, so you can safely pipe the result: + +```bash +TFM=$(alcops detect-tfm marketplace | jq -r '.tfm') +echo "Building with TFM: $TFM" +``` + +### CI/CD Example (GitHub Actions) + +```yaml +- name: Detect TFM + id: tfm + run: | + result=$(npx @alcops/core detect-tfm marketplace) + echo "tfm=$(echo "$result" | jq -r '.tfm')" >> "$GITHUB_OUTPUT" + +- name: Use TFM + run: echo "Target framework is ${{ steps.tfm.outputs.tfm }}" +``` + +## Programmatic API + +The package exports all detection functions for use as a library: + +```typescript +import { detectFromMarketplace, createConsoleLogger } from '@alcops/core'; + +const logger = createConsoleLogger(); +const result = await detectFromMarketplace('current', logger); +console.log(result.tfm); // e.g. "net8.0" +``` + +See the [exported API surface](./src/index.ts) for the full list of available functions and types. + +## Contributing + +See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and contribution guidelines. + +## License + +[MIT](./LICENSE) From 6307fd7146c3055f75f68a0c90d0ed8693a6fb3c Mon Sep 17 00:00:00 2001 From: Arthur van de Vondervoort Date: Wed, 29 Apr 2026 11:40:36 +0200 Subject: [PATCH 2/2] docs: broaden README description to cover detect and download Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b87cc28..40d4e49 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![npm](https://img.shields.io/npm/v/@alcops/core)](https://www.npmjs.com/package/@alcops/core) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) -Detect the Target Framework Moniker (TFM) used by Business Central, so you can build AL extensions with the correct analyzer version. Designed for CI/CD pipelines. +Automatically detect the Target Framework Moniker (TFM) for Business Central and download the matching code analyzer files. Build AL extensions with the right analyzers, without manual version juggling. Designed for CI/CD pipelines. ## Features