3.2.6

.serena/.gitignore

@@ -0,0 +1 @@
+/cache

.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: "smarthash"

changelog.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 2025-09-12 - 3.2.6 - fix(ci)
+Add .claude local settings to permit web fetch to www.npmjs.com
+
+- Added .claude/settings.local.json granting WebFetch permission for www.npmjs.com
+- Configuration-only change; no runtime or library code modified
+
+## 2025-09-12 - 3.2.5 - fix(ts_web)
+Ensure sha256FromBuffer uses correct ArrayBuffer slice for Uint8Array inputs and add local project config files
+
+- Fix sha256FromBuffer in ts_web: explicitly slice Uint8Array.buffer using byteOffset/byteLength before calling crypto.subtle.digest to ensure the correct ArrayBuffer segment is hashed in browser environments.
+- Add .claude/settings.local.json to allow WebFetch to www.npmjs.com for local tooling.
+- Add .serena/.gitignore and .serena/project.yml to include project-specific configuration and ignored cache path.
+- Add missing newline at end of ts_web/index.ts
+
+## 2025-09-12 - 3.2.4 - fix(deps)
+Bump devDependencies, update smartjson and add workspace/CI settings
+
+- Bump @git.zone/tsbuild from ^2.1.70 to ^2.6.8
+- Bump @git.zone/tstest from ^2.3.2 to ^2.3.8
+- Bump @push.rocks/smartjson from ^5.0.10 to ^5.2.0
+- Add pnpm-workspace.yaml with onlyBuiltDependencies: esbuild, mongodb-memory-server, puppeteer
+- Add .claude/settings.local.json to allow WebFetch access to www.npmjs.com
+
+## 2025-08-03 - 3.2.3 - fix(dependencies/config)
+Update dependency versions and add local settings for web fetch configuration
+
+- Bump @git.zone/tstest from ^1.0.81 to ^2.3.2
+- Bump @push.rocks/smartenv from ^5.0.5 to ^5.0.13
+- Add .claude/settings.local.json to allow WebFetch permissions for www.npmjs.com
+
+## 2025-08-03 - 3.2.1 - docs(readme)
+Enhance readme with comprehensive documentation and modern formatting
+
+- Updated readme.md with enhanced formatting, emojis, and badges
+- Added comprehensive API reference with clear examples for all functions
+- Included environment compatibility table showing Node.js vs Browser support
+- Added advanced usage examples including error handling and import strategies
+- Improved documentation structure with better visual organization
+- Fixed typo in sha265FromObject examples to sha256FromObject
+
 ## 2025-06-19 - 3.2.0 - feat(package)
 Update package.json to use exports field for dual entry points
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smarthash",
-  "version": "3.2.0",
+  "version": "3.2.6",
   "private": false,
   "description": "Cross-environment hash functions (SHA256 and MD5) for Node.js and browsers, with support for strings, streams, and files.",
   "exports": {
@@ -32,14 +32,14 @@
   "author": "Lossless GmbH",
   "license": "MIT",
   "devDependencies": {
-    "@git.zone/tsbuild": "^2.1.70",
+    "@git.zone/tsbuild": "^2.6.8",
     "@git.zone/tsrun": "^1.2.46",
-    "@git.zone/tstest": "^1.0.81",
+    "@git.zone/tstest": "^2.3.8",
     "@types/node": "^20.6.3"
   },
   "dependencies": {
-    "@push.rocks/smartenv": "^5.0.5",
+    "@push.rocks/smartenv": "^5.0.13",
-    "@push.rocks/smartjson": "^5.0.10",
+    "@push.rocks/smartjson": "^5.2.0",
     "@push.rocks/smartpromise": "^4.0.3",
     "@types/through2": "^2.0.39",
     "through2": "^4.0.2"

pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+onlyBuiltDependencies:
+  - esbuild
+  - mongodb-memory-server
+  - puppeteer

readme.md

@@ -1,119 +1,161 @@
-# @push.rocks/smarthash
+# 🔐 @push.rocks/smarthash
-simplified access to node hash functions
 
-## Install
+> **Cross-environment hashing made simple** 🚀  
-To install `@push.rocks/smarthash`, use the following command with npm:
+> SHA256 and MD5 hash functions that work seamlessly in both Node.js and browsers, with zero configuration.
+
+[![npm version](https://img.shields.io/npm/v/@push.rocks/smarthash.svg)](https://www.npmjs.com/package/@push.rocks/smarthash)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![Cross Platform](https://img.shields.io/badge/Platform-Node.js%20%7C%20Browser-brightgreen.svg)](#)
+
+## ✨ Why SmartHash?
+
+- 🌐 **Universal**: Works in Node.js AND browsers without polyfills
+- ⚡ **Smart Fallbacks**: Automatically handles Web Crypto API limitations (like non-HTTPS environments)
+- 🔧 **TypeScript First**: Full type safety and IntelliSense support
+- 📦 **Dual Entry Points**: Optimized builds for both environments
+- 🎯 **Simple API**: Consistent interface across all platforms
+
+## 🚀 Quick Start
 
 ```bash
-npm install @push.rocks/smarthash --save
+pnpm install @push.rocks/smarthash
 ```
 
-This will add `@push.rocks/smarthash` to your project's dependencies.
+## 📖 API Reference
 
-## Usage
+### 🔤 String Hashing
-The `@push.rocks/smarthash` library provides a simplified interface to Node.js hash functions, including utilities for hashing strings, files, and streams with popular algorithms like SHA-256 and MD5. Below are detailed examples to demonstrate the capabilities and usage of this library using ESM syntax and TypeScript.
 
-### Hashing Strings
-#### SHA-256
 ```typescript
 import { sha256FromString, sha256FromStringSync } from '@push.rocks/smarthash';
 
-// Asynchronously hash a string
+// Async (works everywhere)
-const asyncHash = async () => {
+const hash = await sha256FromString('Hello, world!');
-  const hash = await sha256FromString('Hello, world!');
+console.log(hash); // 📄 64-character hex string
-  console.log(hash); // Output the hashed string
-};
-asyncHash();
 
-// Synchronously hash a string
+// Sync (Node.js only)
-const syncHash = sha256FromStringSync('Hello, world!');
+const hashSync = sha256FromStringSync('Hello, world!');
-console.log(syncHash); // Output the hashed string
+console.log(hashSync); // ⚡ Instant result
 ```
 
-#### MD5
+### 🗂️ File & Stream Hashing (Node.js Only)
+
+```typescript
+import { sha256FromFile, sha256FromStream } from '@push.rocks/smarthash';
+import fs from 'fs';
+
+// Hash files directly
+const fileHash = await sha256FromFile('./myfile.txt');
+console.log(fileHash); // 📁 File's SHA256 hash
+
+// Hash streams (perfect for large files)
+const stream = fs.createReadStream('./largefile.zip');
+const streamHash = await sha256FromStream(stream);
+console.log(streamHash); // 🌊 Stream's SHA256 hash
+```
+
+### 🧱 Buffer Hashing
+
+```typescript
+import { sha256FromBuffer } from '@push.rocks/smarthash';
+
+// Works with both Buffer (Node.js) and Uint8Array (Browser)
+const encoder = new TextEncoder();
+const buffer = encoder.encode('Hello, world!');
+const bufferHash = await sha256FromBuffer(buffer);
+console.log(bufferHash); // 🔢 Buffer's SHA256 hash
+```
+
+### 🎯 Object Hashing
+
+```typescript
+import { sha256FromObject } from '@push.rocks/smarthash';
+
+// Consistent hashing for JavaScript objects
+const myObject = { 
+  userId: 12345, 
+  role: 'admin',
+  timestamp: Date.now()
+};
+
+const objectHash = await sha256FromObject(myObject);
+console.log(objectHash); // 🎯 Deterministic object hash
+```
+
+> **🔥 Pro Tip**: Object property order doesn't matter! `{a: 1, b: 2}` and `{b: 2, a: 1}` produce the same hash.
+
+### 🛡️ MD5 Hashing (Node.js Only)
+
 ```typescript
 import { md5FromString } from '@push.rocks/smarthash';
 
-// Asynchronously hash a string with MD5
+// Legacy MD5 support (use SHA256 for new projects!)
-const md5Hash = async () => {
+const md5Hash = await md5FromString('Hello, world!');
-  const hash = await md5FromString('Hello, world!');
+console.log(md5Hash); // 🔐 32-character MD5 hash
-  console.log(hash); // Output the MD5 hash
-};
-md5Hash();
 ```
 
-### Hashing Files
+## 🌍 Environment Compatibility
-To hash a file, you can use the `sha256FromFile` function. It reads the file specified by the path and calculates the SHA-256 hash.
-```typescript
-import { sha256FromFile } from '@push.rocks/smarthash';
 
-// Asynchronously hash a file
+| Function | Node.js | Browser | Notes |
-const hashFile = async () => {
+|----------|---------|---------|-------|
-  const fileHash = await sha256FromFile('./path/to/your/file.txt');
+| `sha256FromString` | ✅ | ✅ | Universal support |
-  console.log(fileHash); // Output the file's hash
+| `sha256FromStringSync` | ✅ | ❌ | Sync not possible in browsers |
-};
+| `sha256FromBuffer` | ✅ | ✅ | Handles Buffer/Uint8Array |
-hashFile();
+| `sha256FromFile` | ✅ | ❌ | File system access required |
-```
+| `sha256FromStream` | ✅ | ❌ | Node.js streams only |
+| `sha256FromObject` | ✅ | ✅ | Uses JSON serialization |
+| `md5FromString` | ✅ | ❌ | Not supported by Web Crypto API |
 
-### Hashing Streams
+## 🔧 Advanced Usage
-`@push.rocks/smarthash` also allows for hashing of streams, which is particularly useful for large files or data streams.
-```typescript
-import { sha256FromStream } from '@push.rocks/smarthash';
-import fs from 'fs';
 
-// Create a read stream from a file
+### Error Handling
-const readStream = fs.createReadStream('./path/to/your/largeFile.txt');
 
-// Asynchronously hash the stream
-const hashStream = async () => {
-  const streamHash = await sha256FromStream(readStream);
-  console.log(streamHash); // Output the hash of the stream's content
-};
-hashStream();
-```
-
-### Advanced Usage
-#### Hashing Objects
-For hashing JavaScript objects, you can serialize them and hash the resulting string. This is useful for creating hashes from complex data structures.
-```typescript
-import { sha265FromObject } from '@push.rocks/smarthash';
-
-// Hash a JavaScript object
-const hashObject = async () => {
-  const object = { hello: 'world', number: 42 };
-  const objectHash = await sha265FromObject(object);
-  console.log(objectHash); // Output the hash of the object
-};
-hashObject();
-```
-
-#### Error Handling
-All asynchronous functions return promises, so you can use `.catch()` for error handling or try-catch blocks within async functions.
 ```typescript
 import { sha256FromString } from '@push.rocks/smarthash';
 
-// Using .catch() for promises
+try {
-sha256FromString('test')
+  const hash = await sha256FromString('sensitive data');
-  .then(hash => console.log(hash))
+  console.log(`✅ Hash computed: ${hash}`);
-  .catch(error => console.error(error));
+} catch (error) {
-
+  console.error('❌ Hashing failed:', error);
-// Using try-catch with async functions
+}
-const getHash = async () => {
-  try {
-    const hash = await sha256FromString('test');
-    console.log(hash);
-  } catch (error) {
-    console.error(error);
-  }
-};
-getHash();
 ```
 
-### Best Practices
+### Browser-Specific Features
-- Utilize asynchronous functions for hashing large files or streams to avoid blocking the main thread.
-- For hashing sensitive information, ensure to follow security best practices, including using up-to-date algorithms and managing secrets properly.
 
-By leveraging `@push.rocks/smarthash`, developers can easily integrate hashing functionalities into their Node.js applications, benefiting from its simplified API and TypeScript support for better development experience.
+In browsers, SmartHash automatically:
+- 🔒 Uses Web Crypto API when available (HTTPS contexts)
+- 🔄 Falls back to pure JavaScript implementation in non-HTTPS environments
+- ⚠️ Warns when trying to use Node.js-only functions
+
+### Import Strategies
+
+```typescript
+// Main entry point (Node.js optimized)
+import { sha256FromString } from '@push.rocks/smarthash';
+
+// Browser-specific entry point (smaller bundle)
+import { sha256FromString } from '@push.rocks/smarthash/web';
+```
+
+## 🛠️ Development
+
+```bash
+# Run tests (both Node.js and browser)
+pnpm test
+
+# Build the project
+pnpm build
+
+# Generate documentation
+pnpm buildDocs
+```
+
+## 🔐 Security Notes
+
+- ✅ **SHA256**: Cryptographically secure, recommended for all use cases
+- ⚠️ **MD5**: Legacy support only, not recommended for security-critical applications
+- 🌍 **Cross-Environment**: Produces identical hashes across Node.js and browsers
+- 🔒 **Web Crypto**: Uses native browser APIs when available for maximum performance
 
 ## License and Legal Information
 
@@ -132,4 +174,4 @@ 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.
+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.

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smarthash',
-  version: '3.2.0',
+  version: '3.2.6',
   description: 'Cross-environment hash functions (SHA256 and MD5) for Node.js and browsers, with support for strings, streams, and files.'
 }

ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smarthash',
-  version: '3.2.0',
+  version: '3.2.6',
   description: 'Cross-environment hash functions (SHA256 and MD5) for Node.js and browsers, with support for strings, streams, and files.'
 }

ts_web/index.ts

@@ -60,7 +60,19 @@ export const sha256FromStringSync = (stringArg: string): string => {
  */
 export const sha256FromBuffer = async (bufferArg: ArrayBuffer | Uint8Array): Promise<string> => {
   if (isCryptoSubtleAvailable()) {
-    const hash = await crypto.subtle.digest("SHA-256", bufferArg);
+    // Ensure we pass an ArrayBuffer to satisfy BufferSource typing
+    let inputBuffer: ArrayBuffer;
+    if (bufferArg instanceof Uint8Array) {
+      const view = bufferArg;
+      inputBuffer = view.buffer.slice(
+        view.byteOffset,
+        view.byteOffset + view.byteLength
+      ) as ArrayBuffer;
+    } else {
+      inputBuffer = bufferArg;
+    }
+
+    const hash = await crypto.subtle.digest("SHA-256", inputBuffer);
     const result = hex(hash);
     return result;
   } else {
@@ -101,4 +113,4 @@ export const sha256FromFile = async (filePath: string): Promise<string> => {
  */
 export const md5FromString = async (stringToHash: string): Promise<string> => {
   throw new Error('md5FromString is not supported in browser environment. Web Crypto API does not support MD5.');
-};
+};