2.2.6

.gitea/workflows/default_nottags.yaml

@@ -0,0 +1,66 @@
+name: Default (not tags)
+
+on:
+  push:
+    tags-ignore:
+      - '**'
+
+env:
+  IMAGE: code.foss.global/host.today/ht-docker-node:npmci
+  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@/${{gitea.repository}}.git
+  NPMCI_TOKEN_NPM: ${{secrets.NPMCI_TOKEN_NPM}}
+  NPMCI_TOKEN_NPM2: ${{secrets.NPMCI_TOKEN_NPM2}}
+  NPMCI_GIT_GITHUBTOKEN: ${{secrets.NPMCI_GIT_GITHUBTOKEN}}
+  NPMCI_URL_CLOUDLY: ${{secrets.NPMCI_URL_CLOUDLY}}
+
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    container:
+      image: ${{ env.IMAGE }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install pnpm and npmci
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+
+      - name: Run npm prepare
+        run: npmci npm prepare
+
+      - name: Audit production dependencies
+        run: |
+          npmci command npm config set registry https://registry.npmjs.org
+          npmci command pnpm audit --audit-level=high --prod
+        continue-on-error: true
+
+      - name: Audit development dependencies
+        run: |
+          npmci command npm config set registry https://registry.npmjs.org
+          npmci command pnpm audit --audit-level=high --dev
+        continue-on-error: true
+
+  test:
+    if: ${{ always() }}
+    needs: security
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ env.IMAGE }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Test stable
+        run: |
+          npmci node install stable
+          npmci npm install
+          npmci npm test
+
+      - name: Test build
+        run: |
+          npmci node install stable
+          npmci npm install
+          npmci npm build

.gitea/workflows/default_tags.yaml

@@ -0,0 +1,124 @@
+name: Default (tags)
+
+on:
+  push:
+    tags:
+      - '*'
+
+env:
+  IMAGE: code.foss.global/host.today/ht-docker-node:npmci
+  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@/${{gitea.repository}}.git
+  NPMCI_TOKEN_NPM: ${{secrets.NPMCI_TOKEN_NPM}}
+  NPMCI_TOKEN_NPM2: ${{secrets.NPMCI_TOKEN_NPM2}}
+  NPMCI_GIT_GITHUBTOKEN: ${{secrets.NPMCI_GIT_GITHUBTOKEN}}
+  NPMCI_URL_CLOUDLY: ${{secrets.NPMCI_URL_CLOUDLY}}
+
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    container:
+      image: ${{ env.IMAGE }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Prepare
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+          npmci npm prepare
+
+      - name: Audit production dependencies
+        run: |
+          npmci command npm config set registry https://registry.npmjs.org
+          npmci command pnpm audit --audit-level=high --prod
+        continue-on-error: true
+
+      - name: Audit development dependencies
+        run: |
+          npmci command npm config set registry https://registry.npmjs.org
+          npmci command pnpm audit --audit-level=high --dev
+        continue-on-error: true
+
+  test:
+    if: ${{ always() }}
+    needs: security
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ env.IMAGE }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Prepare
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+          npmci npm prepare
+
+      - name: Test stable
+        run: |
+          npmci node install stable
+          npmci npm install
+          npmci npm test
+
+      - name: Test build
+        run: |
+          npmci node install stable
+          npmci npm install
+          npmci npm build
+
+  release:
+    needs: test
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ env.IMAGE }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Prepare
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+          npmci npm prepare
+
+      - name: Release
+        run: |
+          npmci node install stable
+          npmci npm publish
+
+  metadata:
+    needs: test
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ env.IMAGE }}
+    continue-on-error: true
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Prepare
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+          npmci npm prepare
+
+      - name: Code quality
+        run: |
+          npmci command npm install -g typescript
+          npmci npm install
+
+      - name: Trigger
+        run: npmci trigger
+
+      - name: Build docs and upload artifacts
+        run: |
+          npmci node install stable
+          npmci npm install
+          pnpm install -g @git.zone/tsdoc
+          npmci command tsdoc
+        continue-on-error: true

.gitlab-ci.yml

@@ -1,141 +0,0 @@
-# gitzone ci_default
-image: registry.gitlab.com/hosttoday/ht-docker-node:npmci
-
-cache:
-  paths:
-    - .npmci_cache/
-  key: '$CI_BUILD_STAGE'
-
-stages:
-  - security
-  - test
-  - release
-  - metadata
-
-before_script:
-  - npm install -g @shipzone/npmci
-
-# ====================
-# security stage
-# ====================
-mirror:
-  stage: security
-  script:
-    - npmci git mirror
-  only:
-    - tags
-  tags:
-    - lossless
-    - docker
-    - notpriv
-
-auditProductionDependencies:
-  image: registry.gitlab.com/hosttoday/ht-docker-node:npmci
-  stage: security
-  script:
-    - npmci npm prepare
-    - npmci command npm install --production --ignore-scripts
-    - npmci command npm config set registry https://registry.npmjs.org
-    - npmci command npm audit --audit-level=high --only=prod --production
-  tags:
-    - docker
-  allow_failure: true
-
-auditDevDependencies:
-  image: registry.gitlab.com/hosttoday/ht-docker-node:npmci
-  stage: security
-  script:
-    - npmci npm prepare
-    - npmci command npm install --ignore-scripts
-    - npmci command npm config set registry https://registry.npmjs.org
-    - npmci command npm audit --audit-level=high --only=dev
-  tags:
-    - docker
-  allow_failure: true
-
-# ====================
-# test stage
-# ====================
-
-testStable:
-  stage: test
-  script:
-    - npmci npm prepare
-    - npmci node install stable
-    - npmci npm install
-    - npmci npm test
-  coverage: /\d+.?\d+?\%\s*coverage/
-  tags:
-    - docker
-
-testBuild:
-  stage: test
-  script:
-    - npmci npm prepare
-    - npmci node install stable
-    - npmci npm install
-    - npmci command npm run build
-  coverage: /\d+.?\d+?\%\s*coverage/
-  tags:
-    - docker
-
-release:
-  stage: release
-  script:
-    - npmci node install stable
-    - npmci npm publish
-  only:
-    - tags
-  tags:
-    - lossless
-    - docker
-    - notpriv
-
-# ====================
-# metadata stage
-# ====================
-codequality:
-  stage: metadata
-  allow_failure: true
-  only:
-    - tags
-  script:
-    - npmci command npm install -g tslint typescript
-    - npmci npm prepare
-    - npmci npm install
-    - npmci command "tslint -c tslint.json ./ts/**/*.ts"
-  tags:
-    - lossless
-    - docker
-    - priv
-
-trigger:
-  stage: metadata
-  script:
-    - npmci trigger
-  only:
-    - tags
-  tags:
-    - lossless
-    - docker
-    - notpriv
-
-pages:
-  stage: metadata
-  script:
-    - npmci node install lts
-    - npmci command npm install -g @gitzone/tsdoc
-    - npmci npm prepare
-    - npmci npm install
-    - npmci command tsdoc
-  tags:
-    - lossless
-    - docker
-    - notpriv
-  only:
-    - tags
-  artifacts:
-    expire_in: 1 week
-    paths:
-      - public
-  allow_failure: true

.serena/project.yml

@@ -0,0 +1,68 @@
+# language of the project (csharp, python, rust, java, typescript, go, cpp, or ruby)
+#  * For C, use cpp
+#  * For JavaScript, use typescript
+# Special requirements:
+#  * csharp: Requires the presence of a .sln file in the project folder.
+language: typescript
+
+# whether to use the project's gitignore file to ignore files
+# Added on 2025-04-07
+ignore_all_files_in_gitignore: true
+# list of additional paths to ignore
+# same syntax as gitignore, so you can use * and **
+# Was previously called `ignored_dirs`, please update your config if you are using that.
+# Added (renamed) on 2025-04-07
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+
+# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+project_name: "smarts3"

changelog.md

@@ -0,0 +1,76 @@
+# Changelog
+
+## 2025-08-16 - 2.2.6 - fix(Smarts3)
+Allow overriding S3 descriptor; update dependencies, test config and documentation
+
+- ts/index.ts: getS3Descriptor now accepts an optional Partial<IS3Descriptor> to override defaults (backwards compatible)
+- package.json: updated devDependencies and runtime dependency versions (tstest, smartpath, tsclass, s3rver, etc.) and added packageManager field
+- package.json: expanded test script to run tstest with --web --verbose --logfile --timeout 60
+- test/test.ts: test instance port changed to 3333
+- readme.md: major rewrite and expansion of usage examples, API reference and guides
+- added project config files: .claude/settings.local.json and .serena/project.yml
+
+## 2024-11-06 - 2.2.5 - fix(ci)
+Corrected docker image URLs in Gitea workflows to match the correct domain format.
+
+- Updated IMAGE environment variable in .gitea/workflows/default_nottags.yaml
+- Updated IMAGE environment variable in .gitea/workflows/default_tags.yaml
+
+## 2024-11-06 - 2.2.4 - fix(core)
+Improve code style and update dependencies
+
+- Updated @push.rocks/tapbundle to version ^5.4.3 in package.json.
+- Fixed markdown formatting in readme.md.
+- Improved code consistency in ts/00_commitinfo_data.ts, ts/plugins.ts, and test/test.ts.
+
+## 2024-11-06 - 2.2.3 - fix(core)
+Fix endpoint address from 'localhost' to '127.0.0.1' for better compatibility in Smarts3.getS3Descriptor
+
+- Corrected the endpoint address in Smarts3.getS3Descriptor to ensure proper functioning across different environments.
+
+## 2024-11-06 - 2.2.2 - fix(core)
+Fixed function call for fastPut in the test suite to ensure proper file upload handling.
+
+- Updated dependencies in package.json to newer versions.
+- Corrected the function call in test suite for file upload.
+
+## 2024-10-26 - 2.2.1 - fix(core)
+Fix import and typings for improved compatibility
+
+- Corrected the type signature for `getS3Descriptor` to return `IS3Descriptor`.
+- Fixed import structure and updated dependencies for consistent namespace usage across plugins.
+
+## 2024-10-26 - 2.2.0 - feat(ci)
+Migrate CI/CD workflow from GitLab CI to Gitea CI
+
+- Added new Gitea CI workflows for both non-tag and tag-based pushes
+- Removed existing GitLab CI configuration
+
+## 2024-05-29 - 2.1.1 - Updates and minor changes
+Updates and changes based on minor configuration improvements and organizational shifts.
+
+- Updated description file.
+- Updated tsconfig settings.
+- Updated npmextra.json with new githost configuration.
+- Shifted to new organizational scheme.
+
+## 2022-07-30 - 2.1.0 - Core improvements and fixes
+Minor improvements and important core changes.
+
+- Removed tslint from the core setup.
+
+## 2022-07-30 - 2.0.2 - Bucket creation improvement
+Enhanced file structure management.
+
+- Improved bucket creation to store locally within the .nogit directory.
+
+## 2022-04-14 - 2.0.0 to 2.0.1 - Structural updates and fixes
+This release focused on core updates and structural changes.
+
+- Reformatted the project structure.
+- Core updates with minor fixes.
+
+## 2021-12-20 - 1.0.10 - ESM Transition
+Breaking changes and minor fixes, transitioning to ES Modules.
+
+- BREAKING CHANGE: Transitioned core setup to ESM.

npmextra.json

@@ -2,17 +2,38 @@
   "gitzone": {
     "projectType": "npm",
     "module": {
-      "githost": "gitlab.com",
-      "gitscope": "pushrocks",
+      "githost": "code.foss.global",
+      "gitscope": "push.rocks",
       "gitrepo": "smarts3",
-      "shortDescription": "create an s3 endpoint that maps to a local directory",
-      "npmPackagename": "@pushrocks/smarts3",
+      "description": "A Node.js TypeScript package to create a local S3 endpoint for simulating AWS S3 operations using mapped local directories for development and testing purposes.",
+      "npmPackagename": "@push.rocks/smarts3",
       "license": "MIT",
-      "projectDomain": "push.rocks"
+      "projectDomain": "push.rocks",
+      "keywords": [
+        "S3 Mock Server",
+        "Local S3",
+        "Node.js",
+        "TypeScript",
+        "Local Development",
+        "Testing",
+        "Cloud Storage",
+        "File Storage",
+        "AWS S3 Compatibility",
+        "Development Tool",
+        "S3 Endpoint",
+        "S3 Simulation",
+        "Bucket Management",
+        "File Upload",
+        "CI/CD Integration",
+        "Developer Onboarding"
+      ]
     }
   },
   "npmci": {
     "npmGlobalTools": [],
     "npmAccessLevel": "public"
+  },
+  "tsdoc": {
+    "legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH  \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n"
   }
 }

package.json

@@ -1,25 +1,24 @@
 {
-  "name": "@pushrocks/smarts3",
-  "version": "1.0.3",
+  "name": "@push.rocks/smarts3",
+  "version": "2.2.6",
   "private": false,
-  "description": "create an s3 endpoint that maps to a local directory",
+  "description": "A Node.js TypeScript package to create a local S3 endpoint for simulating AWS S3 operations using mapped local directories for development and testing purposes.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
+  "type": "module",
   "author": "Lossless GmbH",
   "license": "MIT",
   "scripts": {
-    "test": "(tstest test/ --web)",
-    "build": "(tsbuild --web)"
+    "test": "(tstest test/ --web --verbose --logfile --timeout 60)",
+    "build": "(tsbuild --web --allowimplicitany)",
+    "buildDocs": "tsdoc"
   },
   "devDependencies": {
-    "@gitzone/tsbuild": "^2.1.25",
-    "@gitzone/tsbundle": "^1.0.78",
-    "@gitzone/tstest": "^1.0.44",
-    "@pushrocks/smartbucket": "^1.0.44",
-    "@pushrocks/tapbundle": "^3.2.9",
-    "@types/node": "^17.0.0",
-    "tslint": "^6.1.3",
-    "tslint-config-prettier": "^1.15.0"
+    "@git.zone/tsbuild": "^2.2.0",
+    "@git.zone/tsbundle": "^2.1.0",
+    "@git.zone/tsrun": "^1.3.3",
+    "@git.zone/tstest": "^2.3.2",
+    "@types/node": "^22.9.0"
   },
   "browserslist": [
     "last 1 chrome versions"
@@ -37,8 +36,38 @@
     "readme.md"
   ],
   "dependencies": {
-    "@pushrocks/smartfile": "^9.0.3",
+    "@push.rocks/smartbucket": "^3.0.23",
+    "@push.rocks/smartfile": "^11.0.21",
+    "@push.rocks/smartpath": "^6.0.0",
+    "@tsclass/tsclass": "^9.2.0",
     "@types/s3rver": "^3.7.0",
     "s3rver": "^3.7.1"
-  }
+  },
+  "keywords": [
+    "S3 Mock Server",
+    "Local S3",
+    "Node.js",
+    "TypeScript",
+    "Local Development",
+    "Testing",
+    "Cloud Storage",
+    "File Storage",
+    "AWS S3 Compatibility",
+    "Development Tool",
+    "S3 Endpoint",
+    "S3 Simulation",
+    "Bucket Management",
+    "File Upload",
+    "CI/CD Integration",
+    "Developer Onboarding"
+  ],
+  "homepage": "https://code.foss.global/push.rocks/smarts3#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://code.foss.global/push.rocks/smarts3.git"
+  },
+  "bugs": {
+    "url": "https://code.foss.global/push.rocks/smarts3/issues"
+  },
+  "packageManager": "pnpm@10.14.0+sha512.ad27a79641b49c3e481a16a805baa71817a04bbe06a38d17e60e2eaee83f6a146c6a688125f5792e48dd5ba30e7da52a5cda4c3992b9ccf333f9ce223af84748"
 }

readme.hints.md

@@ -0,0 +1 @@
+ 

readme.md

@@ -1,39 +1,426 @@
-# @pushrocks/smarts3
-create an s3 endpoint that maps to a local directory
+# @push.rocks/smarts3 🚀
 
-## Availabililty and Links
-* [npmjs.org (npm package)](https://www.npmjs.com/package/@pushrocks/smarts3)
-* [gitlab.com (source)](https://gitlab.com/pushrocks/smarts3)
-* [github.com (source mirror)](https://github.com/pushrocks/smarts3)
-* [docs (typedoc)](https://pushrocks.gitlab.io/smarts3/)
+**Mock S3 made simple** - A powerful Node.js TypeScript package for creating a local S3 endpoint that simulates AWS S3 operations using mapped local directories. Perfect for development and testing! 
 
-## Status for master
+## 🌟 Features
 
-Status Category | Status Badge
--- | --
-GitLab Pipelines | [![pipeline status](https://gitlab.com/pushrocks/smarts3/badges/master/pipeline.svg)](https://lossless.cloud)
-GitLab Pipline Test Coverage | [![coverage report](https://gitlab.com/pushrocks/smarts3/badges/master/coverage.svg)](https://lossless.cloud)
-npm | [![npm downloads per month](https://badgen.net/npm/dy/@pushrocks/smarts3)](https://lossless.cloud)
-Snyk | [![Known Vulnerabilities](https://badgen.net/snyk/pushrocks/smarts3)](https://lossless.cloud)
-TypeScript Support | [![TypeScript](https://badgen.net/badge/TypeScript/>=%203.x/blue?icon=typescript)](https://lossless.cloud)
-node Support | [![node](https://img.shields.io/badge/node->=%2010.x.x-blue.svg)](https://nodejs.org/dist/latest-v10.x/docs/api/)
-Code Style | [![Code Style](https://badgen.net/badge/style/prettier/purple)](https://lossless.cloud)
-PackagePhobia (total standalone install weight) | [![PackagePhobia](https://badgen.net/packagephobia/install/@pushrocks/smarts3)](https://lossless.cloud)
-PackagePhobia (package size on registry) | [![PackagePhobia](https://badgen.net/packagephobia/publish/@pushrocks/smarts3)](https://lossless.cloud)
-BundlePhobia (total size when bundled) | [![BundlePhobia](https://badgen.net/bundlephobia/minzip/@pushrocks/smarts3)](https://lossless.cloud)
-Platform support | [![Supports Windows 10](https://badgen.net/badge/supports%20Windows%2010/yes/green?icon=windows)](https://lossless.cloud) [![Supports Mac OS X](https://badgen.net/badge/supports%20Mac%20OS%20X/yes/green?icon=apple)](https://lossless.cloud)
+- 🏃 **Lightning-fast local S3 simulation** - No more waiting for cloud operations during development
+- 🔄 **Full AWS S3 API compatibility** - Drop-in replacement for S3 in your tests
+- 📂 **Local directory mapping** - Your buckets live right on your filesystem  
+- 🧪 **Perfect for testing** - Reliable, repeatable tests without cloud dependencies
+- 🎯 **TypeScript-first** - Built with TypeScript for excellent type safety and IDE support
+- 🔧 **Zero configuration** - Works out of the box with sensible defaults
+- 🧹 **Clean slate mode** - Start fresh on every test run
 
-## Usage
+## 📦 Installation
 
-Use TypeScript for best in class intellisense
+Install using your favorite package manager:
 
-## Contribution
+```bash
+# Using npm
+npm install @push.rocks/smarts3 --save-dev
 
-We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :)
+# Using pnpm (recommended)
+pnpm add @push.rocks/smarts3 -D
 
-For further information read the linked docs at the top of this readme.
+# Using yarn
+yarn add @push.rocks/smarts3 --dev
+```
 
-> MIT licensed | **©** [Lossless GmbH](https://lossless.gmbh)
-| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy)
+## 🚀 Quick Start
 
-[![repo-footer](https://lossless.gitlab.io/publicrelations/repofooter.svg)](https://maintainedby.lossless.com)
+Get up and running in seconds:
+
+```typescript
+import { Smarts3 } from '@push.rocks/smarts3';
+
+// Start your local S3 server
+const s3Server = await Smarts3.createAndStart({
+  port: 3000,
+  cleanSlate: true // Start with empty buckets
+});
+
+// Create a bucket
+const bucket = await s3Server.createBucket('my-awesome-bucket');
+
+// Get S3 connection details for use with AWS SDK or other S3 clients
+const s3Config = await s3Server.getS3Descriptor();
+
+// When you're done
+await s3Server.stop();
+```
+
+## 📖 Detailed Usage Guide
+
+### 🏗️ Setting Up Your S3 Server
+
+The `Smarts3` class provides a simple interface for managing your local S3 server:
+
+```typescript
+import { Smarts3 } from '@push.rocks/smarts3';
+
+// Configuration options
+const config = {
+  port: 3000,        // Port to run the server on (default: 3000)
+  cleanSlate: true   // Clear all data on start (default: false)
+};
+
+// Create and start in one go
+const s3Server = await Smarts3.createAndStart(config);
+
+// Or create and start separately
+const s3Server = new Smarts3(config);
+await s3Server.start();
+```
+
+### 🪣 Working with Buckets
+
+Creating and managing buckets is straightforward:
+
+```typescript
+// Create a new bucket
+const bucket = await s3Server.createBucket('my-bucket');
+
+// The bucket is now ready to use!
+console.log(`Created bucket: ${bucket.name}`);
+```
+
+### 📤 Uploading Files
+
+Use the powerful `SmartBucket` integration for file operations:
+
+```typescript
+import { SmartBucket } from '@push.rocks/smartbucket';
+
+// Get connection configuration
+const s3Config = await s3Server.getS3Descriptor();
+
+// Create a SmartBucket instance
+const smartbucket = new SmartBucket(s3Config);
+
+// Get your bucket
+const bucket = await smartbucket.getBucket('my-bucket');
+
+// Upload a file
+const baseDir = await bucket.getBaseDirectory();
+await baseDir.fastStore('path/to/file.txt', 'Hello, S3! 🎉');
+
+// Upload with more control
+await baseDir.fastPut({
+  path: 'documents/important.pdf',
+  contents: Buffer.from(yourPdfData)
+});
+```
+
+### 📥 Downloading Files
+
+Retrieve your files easily:
+
+```typescript
+// Get file contents as string
+const content = await baseDir.fastGet('path/to/file.txt');
+console.log(content); // "Hello, S3! 🎉"
+
+// Get file as Buffer
+const buffer = await baseDir.fastGetBuffer('documents/important.pdf');
+```
+
+### 📋 Listing Files
+
+Browse your bucket contents:
+
+```typescript
+// List all files in the bucket
+const files = await baseDir.listFiles();
+
+files.forEach(file => {
+  console.log(`📄 ${file.name} (${file.size} bytes)`);
+});
+
+// List files with a specific prefix
+const docs = await baseDir.listFiles('documents/');
+```
+
+### 🗑️ Deleting Files
+
+Clean up when needed:
+
+```typescript
+// Delete a single file
+await baseDir.fastDelete('old-file.txt');
+
+// Delete multiple files
+const filesToDelete = ['temp1.txt', 'temp2.txt', 'temp3.txt'];
+for (const file of filesToDelete) {
+  await baseDir.fastDelete(file);
+}
+```
+
+## 🧪 Testing Integration
+
+### Using with Jest
+
+```typescript
+import { Smarts3 } from '@push.rocks/smarts3';
+
+describe('S3 Operations', () => {
+  let s3Server: Smarts3;
+
+  beforeAll(async () => {
+    s3Server = await Smarts3.createAndStart({
+      port: 9999,
+      cleanSlate: true
+    });
+  });
+
+  afterAll(async () => {
+    await s3Server.stop();
+  });
+
+  test('should upload and retrieve a file', async () => {
+    const bucket = await s3Server.createBucket('test-bucket');
+    // Your test logic here
+  });
+});
+```
+
+### Using with Mocha
+
+```typescript
+import { Smarts3 } from '@push.rocks/smarts3';
+import { expect } from 'chai';
+
+describe('S3 Operations', () => {
+  let s3Server: Smarts3;
+
+  before(async () => {
+    s3Server = await Smarts3.createAndStart({
+      port: 9999,
+      cleanSlate: true
+    });
+  });
+
+  after(async () => {
+    await s3Server.stop();
+  });
+
+  it('should upload and retrieve a file', async () => {
+    const bucket = await s3Server.createBucket('test-bucket');
+    // Your test logic here
+  });
+});
+```
+
+## 🔌 AWS SDK Integration
+
+Use `smarts3` with the official AWS SDK:
+
+```typescript
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import { Smarts3 } from '@push.rocks/smarts3';
+
+// Start local S3
+const s3Server = await Smarts3.createAndStart({ port: 3000 });
+const config = await s3Server.getS3Descriptor();
+
+// Configure AWS SDK
+const s3Client = new S3Client({
+  endpoint: `http://${config.endpoint}:${config.port}`,
+  region: 'us-east-1',
+  credentials: {
+    accessKeyId: config.accessKey,
+    secretAccessKey: config.accessSecret
+  },
+  forcePathStyle: true
+});
+
+// Use AWS SDK as normal
+const command = new PutObjectCommand({
+  Bucket: 'my-bucket',
+  Key: 'test-file.txt',
+  Body: 'Hello from AWS SDK!'
+});
+
+await s3Client.send(command);
+```
+
+## 🎯 Real-World Examples
+
+### CI/CD Pipeline Testing
+
+```typescript
+// ci-test.ts
+import { Smarts3 } from '@push.rocks/smarts3';
+
+export async function setupTestEnvironment() {
+  // Start S3 server for CI tests
+  const s3 = await Smarts3.createAndStart({
+    port: process.env.S3_PORT || 3000,
+    cleanSlate: true
+  });
+
+  // Create test buckets
+  await s3.createBucket('uploads');
+  await s3.createBucket('processed');
+  await s3.createBucket('archive');
+
+  return s3;
+}
+```
+
+### Microservice Development
+
+```typescript
+// dev-server.ts
+import { Smarts3 } from '@push.rocks/smarts3';
+import express from 'express';
+
+async function startDevelopmentServer() {
+  // Start local S3
+  const s3 = await Smarts3.createAndStart({ port: 3000 });
+  await s3.createBucket('user-uploads');
+
+  // Start your API server
+  const app = express();
+  
+  app.post('/upload', async (req, res) => {
+    // Your upload logic using local S3
+  });
+
+  app.listen(8080, () => {
+    console.log('🚀 Dev server running with local S3!');
+  });
+}
+```
+
+### Data Migration Testing
+
+```typescript
+import { Smarts3 } from '@push.rocks/smarts3';
+
+async function testDataMigration() {
+  const s3 = await Smarts3.createAndStart({ cleanSlate: true });
+  
+  // Create source and destination buckets
+  const sourceBucket = await s3.createBucket('legacy-data');
+  const destBucket = await s3.createBucket('new-data');
+
+  // Populate source with test data
+  const config = await s3.getS3Descriptor();
+  const smartbucket = new SmartBucket(config);
+  const source = await smartbucket.getBucket('legacy-data');
+  const sourceDir = await source.getBaseDirectory();
+  
+  // Add test files
+  await sourceDir.fastStore('user-1.json', JSON.stringify({ id: 1, name: 'Alice' }));
+  await sourceDir.fastStore('user-2.json', JSON.stringify({ id: 2, name: 'Bob' }));
+
+  // Run your migration logic
+  await runMigration(config);
+
+  // Verify migration results
+  const dest = await smartbucket.getBucket('new-data');
+  const destDir = await dest.getBaseDirectory();
+  const migratedFiles = await destDir.listFiles();
+  
+  console.log(`✅ Migrated ${migratedFiles.length} files successfully!`);
+}
+```
+
+## 🛠️ Advanced Configuration
+
+### Custom S3 Descriptor Options
+
+When integrating with different S3 clients, you can customize the connection details:
+
+```typescript
+const customDescriptor = await s3Server.getS3Descriptor({
+  endpoint: 'localhost',  // Custom endpoint
+  port: 3001,            // Different port
+  useSsl: false,         // SSL configuration
+  // Add any additional options your S3 client needs
+});
+```
+
+### Environment-Based Configuration
+
+```typescript
+const config = {
+  port: parseInt(process.env.S3_PORT || '3000'),
+  cleanSlate: process.env.NODE_ENV === 'test'
+};
+
+const s3Server = await Smarts3.createAndStart(config);
+```
+
+## 🤝 Use Cases
+
+- **🧪 Unit & Integration Testing** - Test S3 operations without AWS credentials or internet
+- **🏗️ Local Development** - Develop cloud features offline with full S3 compatibility
+- **📚 Teaching & Demos** - Perfect for workshops and tutorials without AWS setup
+- **🔄 CI/CD Pipelines** - Reliable S3 operations in containerized test environments
+- **🎭 Mocking & Stubbing** - Replace real S3 calls in test suites
+- **📊 Data Migration Testing** - Safely test data migrations locally before production
+
+## 🔧 API Reference
+
+### Smarts3 Class
+
+#### Constructor Options
+
+```typescript
+interface ISmarts3ContructorOptions {
+  port?: number;        // Server port (default: 3000)
+  cleanSlate?: boolean; // Clear storage on start (default: false)
+}
+```
+
+#### Methods
+
+- `static createAndStart(options)` - Create and start server in one call
+- `start()` - Start the S3 server
+- `stop()` - Stop the S3 server
+- `createBucket(name)` - Create a new bucket
+- `getS3Descriptor(options?)` - Get S3 connection configuration
+
+## 🐛 Debugging Tips
+
+1. **Enable verbose logging** - The server logs all operations by default
+2. **Check the buckets directory** - Find your data in `.nogit/bucketsDir/`
+3. **Use the correct endpoint** - Remember to use `127.0.0.1` or `localhost`
+4. **Force path style** - Always use path-style URLs with local S3
+
+## 📈 Performance
+
+`@push.rocks/smarts3` is optimized for development and testing:
+
+- ⚡ **Instant operations** - No network latency
+- 💾 **Low memory footprint** - Efficient file system usage
+- 🔄 **Fast cleanup** - Clean slate mode for quick test resets
+- 🚀 **Parallel operations** - Handle multiple requests simultaneously
+
+## 🔗 Related Packages
+
+- [`@push.rocks/smartbucket`](https://www.npmjs.com/package/@push.rocks/smartbucket) - Powerful S3 abstraction layer
+- [`@push.rocks/smartfile`](https://www.npmjs.com/package/@push.rocks/smartfile) - Advanced file system operations
+- [`@tsclass/tsclass`](https://www.npmjs.com/package/@tsclass/tsclass) - TypeScript class helpers
+- [`s3rver`](https://www.npmjs.com/package/s3rver) - The underlying S3 server implementation
+
+## License and Legal Information
+
+This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+
+### Company Information
+
+Task Venture Capital GmbH  
+Registered at District court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

test/plugins.ts

@@ -1,5 +1,3 @@
-import * as smartbucket from '@pushrocks/smartbucket';
+import * as smartbucket from '@push.rocks/smartbucket';
 
-export {
-  smartbucket
-};
+export { smartbucket };

test/test.ts

@@ -1,35 +1,33 @@
-import { expect, tap } from '@pushrocks/tapbundle';
-import * as plugins from './plugins';
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as plugins from './plugins.js';
 
-import * as smarts3 from '../ts/index';
+import * as smarts3 from '../ts/index.js';
 
 let testSmarts3Instance: smarts3.Smarts3;
 
-tap.test('should create a smarts3 instance and run it', async toolsArg => {
-  testSmarts3Instance = new smarts3.Smarts3({
-    port: 3000,
+tap.test('should create a smarts3 instance and run it', async (toolsArg) => {
+  testSmarts3Instance = await smarts3.Smarts3.createAndStart({
+    port: 3333,
     cleanSlate: true,
   });
-  await testSmarts3Instance.start();
   console.log(`Let the instance run for 2 seconds`);
   await toolsArg.delayFor(2000);
 });
 
 tap.test('should be able to access buckets', async () => {
-  const smartbucketInstance = new plugins.smartbucket.SmartBucket({
-    endpoint: 'localhost',
-    port: 3000,
-    useSsl: false,
-    accessKey: 'S3RVER',
-    accessSecret: 'S3RVER'
-  });
+  const smartbucketInstance = new plugins.smartbucket.SmartBucket(
+    await testSmarts3Instance.getS3Descriptor(),
+  );
   const bucket = await smartbucketInstance.createBucket('testbucket');
   const baseDirectory = await bucket.getBaseDirectory();
-  await baseDirectory.fastStore('subdir/hello.txt', 'hi there!');
+  await baseDirectory.fastPut({
+    path: 'subdir/hello.txt',
+    contents: 'hi there!',
+  });
 });
 
 tap.test('should stop the instance', async () => {
   await testSmarts3Instance.stop();
-})
+});
 
 tap.start();

ts/00_commitinfo_data.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+  name: '@push.rocks/smarts3',
+  version: '2.2.6',
+  description: 'A Node.js TypeScript package to create a local S3 endpoint for simulating AWS S3 operations using mapped local directories for development and testing purposes.'
+}

ts/index.ts

@@ -1,5 +1,5 @@
-import * as plugins from './smarts3.plugins';
-import * as paths from './paths';
+import * as plugins from './plugins.js';
+import * as paths from './paths.js';
 
 export interface ISmarts3ContructorOptions {
   port?: number;
@@ -7,11 +7,23 @@ export interface ISmarts3ContructorOptions {
 }
 
 export class Smarts3 {
+  // STATIC
+  public static async createAndStart(optionsArg: ConstructorParameters<typeof Smarts3>[0]) {
+    const smartS3Instance = new Smarts3(optionsArg);
+    await smartS3Instance.start();
+    return smartS3Instance;
+  }
+
+  // INSTANCE
   public options: ISmarts3ContructorOptions;
   public s3Instance: plugins.s3rver;
 
   constructor(optionsArg: ISmarts3ContructorOptions) {
     this.options = optionsArg;
+    this.options = {
+      ...this.options,
+      ...optionsArg,
+    };
   }
 
   public async start() {
@@ -24,13 +36,34 @@ export class Smarts3 {
       port: this.options.port || 3000,
       address: '0.0.0.0',
       silent: false,
-      directory: paths.bucketsDir
-    })
+      directory: paths.bucketsDir,
+    });
     await this.s3Instance.run();
     console.log('s3 server is running');
   }
 
+  public async getS3Descriptor(
+    optionsArg?: Partial<plugins.tsclass.storage.IS3Descriptor>
+  ): Promise<plugins.tsclass.storage.IS3Descriptor> {
+    return {
+      ...{
+        accessKey: 'S3RVER',
+        accessSecret: 'S3RVER',
+        endpoint: '127.0.0.1',
+        port: this.options.port,
+        useSsl: false,
+      },
+      ...(optionsArg? optionsArg : {})
+    };
+  }
+
+  public async createBucket(bucketNameArg: string) {
+    const smartbucketInstance = new plugins.smartbucket.SmartBucket(await this.getS3Descriptor());
+    const bucket = await smartbucketInstance.createBucket(bucketNameArg);
+    return bucket;
+  }
+
   public async stop() {
     await this.s3Instance.close();
   }
-}
+}

ts/paths.ts

@@ -1,6 +1,11 @@
-import * as plugins from './smarts3.plugins';
+import * as plugins from './plugins.js';
 
-export const packageDir = plugins.path.join(__dirname, '../');
+export const packageDir = plugins.path.join(
+  plugins.smartpath.get.dirnameFromImportMetaUrl(import.meta.url),
+  '../',
+);
 export const nogitDir = plugins.path.join(packageDir, './.nogit');
 
-export const bucketsDir = plugins.path.join(nogitDir, './bucketsDir');
+export const cwd = process.cwd();
+
+export const bucketsDir = plugins.path.join(cwd, '.nogit/bucketsDir');

ts/plugins.ts

@@ -0,0 +1,21 @@
+// node native
+import * as path from 'path';
+
+export { path };
+
+// @push.rocks scope
+import * as smartbucket from '@push.rocks/smartbucket';
+import * as smartfile from '@push.rocks/smartfile';
+import * as smartpath from '@push.rocks/smartpath';
+
+export { smartbucket, smartfile, smartpath };
+
+// @tsclass scope
+import * as tsclass from '@tsclass/tsclass';
+
+export { tsclass };
+
+// thirdparty scope
+import s3rver from 's3rver';
+
+export { s3rver };

ts/smarts3.plugins.ts

@@ -1,20 +0,0 @@
-// node native
-import * as path from 'path';
-
-export {
-  path
-}
-
-// pushrocks scope
-import * as samrtfile from '@pushrocks/smartfile';
-
-export {
-  samrtfile as smartfile
-}
-
-// thirdparty scope
-import s3rver from 's3rver';
-
-export {
-  s3rver
-}

tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false,
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "verbatimModuleSyntax": true,
+    "baseUrl": ".",
+    "paths": {}
+  },
+  "exclude": [
+    "dist_*/**/*.d.ts"
+  ]
+}

tslint.json

@@ -1,17 +0,0 @@
-{
-  "extends": ["tslint:latest", "tslint-config-prettier"],
-  "rules": {
-    "semicolon": [true, "always"],
-    "no-console": false,
-    "ordered-imports": false,
-    "object-literal-sort-keys": false,
-    "member-ordering": {
-      "options":{
-        "order": [
-          "static-method"
-        ]
-      }
-    }
-  },
-  "defaultSeverity": "warning"
-}