@jaskrowo/xtb2sure 0.0.0-stage → 0.1.0

package/.editorconfig

@@ -0,0 +1,30 @@
+# EditorConfig helps developers define and maintain consistent coding styles between different editors and IDEs.
+# Requires EditorConfig JetBrains Plugin - http://github.com/editorconfig/editorconfig-jetbrains
+
+# Set this file as the topmost .editorconfig
+# (multiple files can be used, and are applied starting from current document location)
+root = true
+
+# Use bracketed regexp to target specific file types or file locations
+[*.{ts,js,tsx,json,yml,yaml}]
+
+# Use hard or soft tabs ["tab", "space"]
+indent_style = space
+
+# Size of a single indent [an integer, "tab"]
+indent_size = tab
+
+# Number of columns representing a tab character [an integer]
+tab_width = 4
+
+# Line breaks representation ["lf", "cr", "crlf"]
+end_of_line = lf
+
+# ["latin1", "utf-8", "utf-16be", "utf-16le"]
+charset = utf-8
+
+# Remove any whitespace characters preceding newline characters ["true", "false"]
+trim_trailing_whitespace = false
+
+# Ensure file ends with a newline when saving ["true", "false"]
+insert_final_newline = true

package/.github/actions/setup/action.yml

@@ -0,0 +1,15 @@
+name: Runtime & application setup
+description: Sets right node version, installs dependencies
+
+runs:
+    using: 'composite'
+    steps:
+        - name: Set correct node version
+          uses: actions/setup-node@v7
+          with:
+              node-version-file: package.json
+              cache: 'npm'
+              registry-url: 'https://registry.npmjs.org'
+        - name: Install dependencies
+          run: npm ci --quiet --no-audit --no-fund --ignore-scripts
+          shell: bash

package/.github/actions/validate-pr-title/action.yml

@@ -0,0 +1,18 @@
+name: Validate PR title
+description: Runs commitlint on the PR title
+
+runs:
+  using: composite
+  steps:
+    - name: Set correct node version
+      uses: actions/setup-node@v7
+      with:
+        node-version: 24.x
+    - name: Install commitlint
+      run: npm install -g @commitlint/cli @commitlint/config-conventional
+      shell: bash
+    - name: Validate PR title
+      env:
+        PR_TITLE: ${{ github.event.pull_request.title }}
+      run: echo "$PR_TITLE" | npx commitlint
+      shell: bash

package/.github/pull_request_template.md

@@ -0,0 +1,3 @@
+# Summary
+
+## Related issue(s)

package/.github/workflows/main.yml

@@ -0,0 +1,51 @@
+name: Main branch
+
+on:
+    workflow_dispatch:
+    push:
+        branches:
+            - main
+    merge_group:
+
+permissions:
+    id-token: write
+    contents: read
+
+env:
+    TZ: ${{ vars.TZ }}
+    FORCE_COLOR: 1
+
+jobs:
+    validate:
+        name: Validate
+        uses: ./.github/workflows/validate.yml
+        secrets: inherit
+
+    npm:
+        name: NPM audit
+        uses: ./.github/workflows/npm-audit.yml
+        secrets: inherit
+
+    release:
+        name: Release
+        needs: [validate]
+        runs-on: ubuntu-latest
+        concurrency: ${{ github.workflow }}-release
+        permissions:
+            contents: write
+            id-token: write
+        steps:
+        - uses: actions/checkout@v7
+          with:
+            fetch-depth: 0
+            token: ${{ secrets.RELEASE_TOKEN }}
+        - name: Select correct node version, install deps
+          uses: ./.github/actions/setup
+        - name: Configure git
+          run: |
+            git config user.name "domeq"
+            git config user.email "iskra.wojtek@gmail.com"
+        - name: Create a release
+          env:
+            GITHUB_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+          run: npm run release -- --ci

package/.github/workflows/npm-audit.yml

@@ -0,0 +1,23 @@
+name: NPM
+
+on:
+  workflow_call:
+
+env:
+  TZ: Europe/Oslo
+
+jobs:
+  audit:
+    name: Audit
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set correct node version
+        uses: actions/setup-node@v7
+        with:
+          node-version-file: package.json
+          cache: npm
+          registry-url: 'https://registry.npmjs.org'
+      - name: NPM Audit
+        run: npm audit --omit=dev --audit-level=high

package/.github/workflows/pr.yml

@@ -0,0 +1,20 @@
+name: PR
+
+on:
+    workflow_dispatch:
+    pull_request:
+
+permissions:
+    id-token: write
+    contents: read
+    pull-requests: write
+
+env:
+    TZ: ${{ vars.TZ }}
+    FORCE_COLOR: 1
+
+jobs:
+    validate:
+        name: Validate
+        uses: ./.github/workflows/validate.yml
+        secrets: inherit

package/.github/workflows/validate.yml

@@ -0,0 +1,60 @@
+name: Validate
+
+permissions:
+    id-token: write
+    contents: read
+
+on:
+    workflow_call:
+
+env:
+    TZ: ${{ vars.TZ }}
+
+jobs:
+    validate_pr_title:
+        runs-on: ubuntu-latest
+        name: Validate PR title
+        if: github.event.pull_request != null
+        timeout-minutes: 5
+        steps:
+            - uses: actions/checkout@v7
+            - name: Validate PR title
+              uses: ./.github/actions/validate-pr-title
+    linters:
+        name: Linters
+        runs-on: ubuntu-latest
+        timeout-minutes: 15
+        steps:
+            - uses: actions/checkout@v7
+            - uses: ./.github/actions/setup
+            - name: Lint
+              run: npm run lint
+    typecheck:
+        name: Typecheck
+        runs-on: ubuntu-latest
+        timeout-minutes: 15
+        steps:
+            - uses: actions/checkout@v7
+            - uses: ./.github/actions/setup
+            - name: Typecheck
+              run: npm run typecheck
+    knip:
+        name: Knip
+        runs-on: ubuntu-latest
+        timeout-minutes: 15
+        steps:
+            - uses: actions/checkout@v7
+            - uses: ./.github/actions/setup
+            - name: Knip
+              run: npm run knip
+            - name: Knip (production mode)
+              run: npm run knip -- --production
+    tests:
+        name: Tests
+        runs-on: ubuntu-latest
+        timeout-minutes: 15
+        steps:
+            - uses: actions/checkout@v7
+            - uses: ./.github/actions/setup
+            - name: Test
+              run: npm test

package/.husky/commit-msg

@@ -0,0 +1 @@
+npx --no -- commitlint --edit ${1}

package/.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

package/.release-it.cjs

@@ -0,0 +1,41 @@
+module.exports = {
+    git: {
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: release-it placeholders
+        commitMessage: "chore: release ${version} \n\n${changelog}",
+        requireBranch: "main",
+        requireCleanWorkingDir: true,
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: release-it placeholders
+        tagName: "v${version}",
+    },
+    github: {
+        release: true,
+        tokenRef: "GITHUB_TOKEN",
+    },
+    npm: {
+        publish: true,
+        skipChecks: true,
+    },
+    plugins: {
+        "@release-it/conventional-changelog": {
+            infile: "CHANGELOG.md",
+            preset: {
+                name: "conventionalcommits",
+                types: [
+                    { section: "Features", type: "feat" },
+                    { section: "Features", type: "feature" },
+                    { section: "Bug Fixes", type: "fix" },
+                    { section: "Performance Improvements", type: "perf" },
+                    { section: "Reverts", type: "revert" },
+                    { section: "Documentation", type: "docs" },
+                    { section: "Styles", type: "style" },
+                    { section: "Miscellaneous Chores", type: "chore" },
+                    { section: "Code Refactoring", type: "refactor" },
+                    { section: "Tests", type: "test" },
+                    { section: "Build System", type: "build" },
+                    { section: "Continuous Integration", type: "ci" },
+                    { section: "Configuration changes", type: "config" },
+                ],
+            },
+        },
+    },
+};

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,23 @@
+# Code of Conduct
+
+## Our Pledge
+
+We are committed to providing a friendly, safe, and welcoming environment for everyone.
+
+## Our Standards
+
+Examples of positive behavior:
+
+- Being respectful and constructive
+- Accepting and giving feedback gracefully
+- Prioritizing collaboration and empathy
+
+Examples of unacceptable behavior:
+
+- Harassment, discrimination, or abusive language
+- Personal attacks or trolling
+- Publishing private information without consent
+
+## Enforcement
+
+Project maintainers are responsible for clarifying and enforcing this code of conduct.

package/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing
+
+Thanks for your interest in contributing to `xtb2sure`.
+
+## Setup
+
+1. Install Node.js 22+.
+2. Install dependencies:
+
+```bash
+npm install
+```
+
+## Validate changes
+
+Run the test suite before opening a pull request:
+
+```bash
+npm test
+```
+
+## Guidelines
+
+- Keep behavior deterministic and fixture-driven.
+- Add tests for every functional change.
+- Prefer small, focused pull requests.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xtb2sure contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# xtb2sure
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Convert XTB `.xlsx` exports into Sure-compatible CSV files.
+
+## What it does
+
+- Reads the `Cash Operations` sheet from an XTB export workbook.
+- Produces two CSV files:
+  - transactions CSV (`date,amount,name,account,notes`)
+  - investments CSV (`date,ticker,currency,qty,price,account,name`)
+
+## Requirements
+
+- Node.js 24
+
+## Install
+
+```bash
+npm install
+```
+
+## Usage
+
+```bash
+node --experimental-transform-types ./src/cli.ts convert <input.xlsx> --currency <CODE> --account "<ACCOUNT_NAME>"
+```
+
+Options:
+
+- `--out-dir <dir>`
+- `--transactions-out <file>`
+- `--investments-out <file>`
+- `--strict`
+- `--dry-run`
+- `--report <file>`
+
+Examples:
+
+```bash
+node --experimental-transform-types ./src/cli.ts convert sample_data/IKE/input.xlsx --currency USD --account "XTB IKE"
+```
+
+```bash
+node --experimental-transform-types ./src/cli.ts convert sample_data/PLN/input.xlsx --currency PLN --account "XTB PLN" --out-dir ./out
+
+Or via npm script:
+
+```bash
+npm run convert -- sample_data/PLN/input.xlsx --currency PLN --account "XTB PLN"
+```
+```
+
+## Exit codes
+
+- `0` success
+- `1` conversion or validation failure
+- `2` usage or config error
+
+## Development
+
+Run tests (Node.js test runner):
+
+```bash
+npm test
+```

package/SECURITY.md

@@ -0,0 +1,11 @@
+# Security Policy
+
+If you discover a security issue, please report it privately to the maintainers.
+
+Please include:
+
+- A clear description of the issue
+- Steps to reproduce
+- Potential impact
+
+Do not open public issues for security vulnerabilities.

package/biome.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "https://biomejs.dev/schemas/2.2.6/schema.json",
+    "vcs": {
+        "enabled": true,
+        "clientKind": "git",
+        "useIgnoreFile": true
+    },
+    "formatter": {
+        "enabled": true,
+        "indentStyle": "space",
+        "indentWidth": 4,
+        "lineWidth": 120
+    },
+    "linter": {
+        "enabled": true,
+        "rules": {
+            "recommended": true
+        }
+    }
+}

package/commitlint.config.cjs

@@ -0,0 +1,12 @@
+module.exports = {
+    extends: ["@commitlint/config-conventional"],
+    rules: {
+        "body-max-line-length": [2, "always", Infinity],
+        "footer-max-line-length": [2, "always", Infinity],
+        "type-enum": [
+            2,
+            "always",
+            ["build", "chore", "ci", "config", "docs", "feat", "fix", "perf", "refactor", "revert", "style", "test"],
+        ],
+    },
+};

package/config/default.mjs

@@ -0,0 +1,11 @@
+const NAME = process.env.DD_SERVICE || "xtb2sure";
+const ENVIRONMENT = process.env.NODE_ENV || "development";
+const VERSION = process.env.npm_package_version || "dev";
+
+export default {
+    application: {
+        env: ENVIRONMENT,
+        name: NAME,
+        version: VERSION,
+    },
+};

package/docs/PRD.md

@@ -0,0 +1,141 @@
+# xtb2sure PRD
+
+## Goal
+
+Build an open-source TypeScript CLI that converts XTB `.xlsx` exports into two Sure-compatible CSV files:
+
+1. transactions CSV (for Sure Transactions import)
+2. investments CSV (for Sure Trades import)
+
+Target runtime is current Node LTS, executed directly via Node strip-types.
+
+## Confirmed Decisions
+
+- Input format: `.xlsx`
+- Source data: only `Cash Operations` sheet
+- Output: two CSVs per input file
+- Date output format: `YYYY-MM-DD`
+- Currency: required CLI parameter
+- Account: account-level label provided by CLI (e.g. `XTB PLN`, `XTB IKE`)
+- Include tax rows (`Free funds interest tax`, `Withholding tax`)
+- Ignore summary `Total` row
+- Trade ticker uses XTB input as-is (e.g. `EIMI.UK`, `IUSQ.DE`)
+
+## Input Schema (XTB Cash Operations)
+
+Relevant columns:
+- `Type`
+- `Instrument`
+- `Ticker`
+- `Time`
+- `Amount`
+- `ID`
+- `Comment`
+- `Product`
+- `Position ID`
+
+## Output A: Transactions CSV
+
+Header:
+- `date,amount,name,account,notes`
+
+Includes operation types:
+- `Deposit`
+- `IKE deposit`
+- `IKZE deposit`
+- `Free funds interest`
+- `Free funds interest tax`
+- `Withholding tax`
+
+Mapping:
+- `date` from `Time` (Excel serial UTC) -> `YYYY-MM-DD`
+- `amount` from `Amount` (signed as-is)
+- `name` from `Type` (or normalized label if fixture requires)
+- `account` from CLI account label
+- `notes` as traceable text including `XTB <ID>` and source comment
+
+## Output B: Investments CSV
+
+Header:
+- `date,ticker,currency,qty,price,account,name`
+
+Includes operation types:
+- `Stock purchase`
+- `Stock sell`
+
+Mapping:
+- `date` from `Time` -> `YYYY-MM-DD`
+- `ticker` from XTB `Ticker` as-is (e.g. `IPOL.UK`, `SXRV.DE`)
+- `currency` from CLI currency argument
+- `qty` parsed from `Comment` (sell rows negative where reflected in fixture)
+- `price` parsed from `Comment` (`@ <price>`)
+- `account` from CLI account label
+- `name` fixture-compatible human-readable label including `XTB <ID>`
+
+## CLI (v1)
+
+Command:
+- `xtb2sure convert <input.xlsx> --currency <CODE> --account "<ACCOUNT_NAME>"`
+
+Options:
+- `--out-dir <dir>`
+- `--transactions-out <file>`
+- `--investments-out <file>`
+- `--strict`
+- `--dry-run`
+- `--report <file>`
+
+Exit codes:
+- `0` success
+- `1` conversion/validation failure
+- `2` usage/config error
+
+## TDD Plan
+
+### Unit tests
+- Excel serial date conversion
+- operation classification (transaction/investment/ignored)
+- qty/price parser from comment text
+- per-row mapping by type
+
+### Integration tests (fixture exact)
+- `sample_data/IKE/input.xlsx` -> exact match:
+  - `sample_data/IKE/output_transactions.csv`
+  - `sample_data/IKE/output_investments.csv`
+- `sample_data/PLN/input.xlsx` -> exact match:
+  - `sample_data/PLN/output_transactions.csv`
+  - `sample_data/PLN/output_investments.csv`
+- investments schema regression checks:
+  - `ticker` equals source `Cash Operations.Ticker` value for the matching XTB operation ID
+
+### CLI tests
+- required args validation (`--currency`, `--account`)
+- output file generation
+- `--dry-run` behavior
+- strict-mode failure behavior
+- summary counters and exit codes
+
+## Open Source Baseline
+
+Include in repo from the beginning:
+- `README.md`
+- `LICENSE` (permissive and inclusive; MIT recommended unless you choose otherwise)
+- `CONTRIBUTING.md`
+- `CODE_OF_CONDUCT.md`
+- optional but recommended: `SECURITY.md`, CI workflow, issue templates
+
+## Non-goals (v1)
+
+- `Closed Positions` / `Open Positions` parsing
+- Sure API upload automation
+- FX conversion logic
+- Data enrichment beyond deterministic mapping
+
+## Fixture Status
+
+Current fixtures are aligned and usable for TDD:
+- `sample_data/IKE`
+- `sample_data/PLN`
+
+Investments outputs now use:
+- ticker from input as-is

package/knip.config.js

@@ -0,0 +1,5 @@
+const config = {
+    project: ["src/**!", "test/**!"],
+};
+
+export default config;

package/package.json

@@ -1,6 +1,55 @@
 {
-  "name": "@jaskrowo/xtb2sure",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@jaskrowo/xtb2sure",
+    "version": "0.1.0",
+    "description": "Convert XTB .xlsx exports into Sure-compatible CSV files",
+    "main": "src/index.ts",
+    "engines": {
+        "node": "24"
+    },
+    "type": "module",
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
+    "bin": {
+        "xtb2sure": "./src/cli.ts"
+    },
+    "scripts": {
+        "dev": "node --experimental-transform-types --watch src/index.ts",
+        "convert": "node --experimental-transform-types ./src/cli.ts convert",
+        "format": "biome format --write .",
+        "knip": "knip",
+        "lint-fix": "biome check --write .",
+        "lint": "biome check .",
+        "prepare": "husky",
+        "release": "release-it",
+        "start": "node --experimental-transform-types src/index.ts",
+        "test": "node --experimental-transform-types --test",
+        "typecheck": "tsc --noEmit"
+    },
+    "lint-staged": {
+        "*": [
+            "biome check --write --no-errors-on-unmatched"
+        ]
+    },
+    "imports": {
+        "#*": "./src/*"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "2.5.15",
+        "@commitlint/cli": "21.2.3",
+        "@commitlint/config-conventional": "21.2.3",
+        "@release-it/conventional-changelog": "12.0.2",
+        "@types/node": "24.19.1",
+        "husky": "9.1.7",
+        "knip": "6.41.0",
+        "lint-staged": "17.6.0",
+        "release-it": "21.1.1",
+        "typescript": "5.9.3"
+    },
+    "dependencies": {
+        "commander": "15.0.0",
+        "csv-stringify": "6.9.0",
+        "xlsx": "0.18.5"
+    }
+}