Metadata-Version: 2.2
Name: lam-cli
Version: 0.1.2
Summary: Secure data transformation tool supporting JQ and JavaScript (Bun)
Home-page: https://github.com/laminar-run/lam
Author: Laminar Run, Inc.
Author-email: connect@laminar.run
License: GPLv3
Project-URL: Documentation, https://docs.laminar.run
Project-URL: Source, https://github.com/laminar-run/lam
Project-URL: Issue Tracker, https://github.com/laminar-run/lam/issues
Keywords: laminar,api,integration,transformation,json,jq,javascript,bun
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: backoff>=2.2.1
Requires-Dist: certifi>=2024.12.14
Requires-Dist: charset-normalizer>=3.3.2
Requires-Dist: click>=8.1.7
Requires-Dist: idna>=3.7
Requires-Dist: logtail-python>=0.2.2
Requires-Dist: monotonic>=1.6
Requires-Dist: msgpack>=1.0.8
Requires-Dist: posthog>=3.4.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: requests>=2.32.3
Requires-Dist: six>=1.16.0
Requires-Dist: urllib3>=2.2.2
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# lam
Lam is a data transformation tool for Laminar that supports both `jq` and JavaScript transformations using Bun.

## Quickstart
Install the dependencies:
```bash
# For JQ support
brew install jq  # or sudo apt-get install jq

# For JavaScript support
curl -fsSL https://bun.sh/install | bash

make setup
```

Run the CLI tool:
```bash
make cli ARGS="run <program> <input> [--language jq|js]"
```

## Features
- JQ transformations (default)
- JavaScript transformations with Bun runtime
- Built-in utilities (lodash, date-fns)
- Resource monitoring and limits
- Detailed execution statistics
- Secure execution environment

## Examples

### JQ Transform
```bash
make cli ARGS="run examples/transform.jq data.json"
```

### JavaScript Transform
```bash
make cli ARGS="run examples/transform.js data.json --language js"
```

Example JavaScript transform:
```javascript
(input) => {
    // Lodash available as _
    return _.map(input.data, item => ({
        value: item.value * 2
    }));
}
```

## Installation

### Docker Installation
```dockerfile
# Install lam-cli
RUN pip3 install git+https://${GITHUB_USER}:${GITHUB_TOKEN}@github.com/user/project.git@{version}

# Install dependencies
RUN apt-get update && apt-get install -y jq
RUN curl -fsSL https://bun.sh/install | bash
```

### Manual Setup
Create a virtual environment and install dependencies:
```bash
python3 -m venv ./venv
source ./venv/bin/activate
pip install -r requirements.txt
```

## Usage
```bash
# Basic usage
python3 ./lam/lam.py run <program> <input>

# With JavaScript
python3 ./lam/lam.py run script.js data.json --language js

# Full options
python3 ./lam/lam.py run <program> <input> \
    --language [jq|js] \
    --workspace_id <id> \
    --flow_id <id> \
    --execution_id <id> \
    [--as-json]
```

## Resource Limits
- Maximum input size: 10MB
- Execution timeout: 5 seconds
- Memory limits enabled
- Disk space monitoring

## Security
- Sandboxed JavaScript execution
- Network access disabled
- Limited global scope
- Resource monitoring
- Secure dependency management

## Logging and Monitoring
- Execution statistics (duration, memory usage)
- Detailed error tracking
- PostHog analytics integration
- Log file generation

## Development
```bash
# Run all tests
make test

# Run specific test suite
make test-jq
make test-js
make test-js-edge-cases

# Run single test
make test-single TEST=test/js/example.js DATA=test/data/input.json
```

## Releases
Update version in `setup.py`:
```python
setup(
    name="lam-cli",
    version="0.0.<x>",
    ...
)
```

Create and push tag:
```bash
git tag v<version>-<increment>
git push origin v<version>-<increment>
```

## Dependencies
Update dependencies:
```bash
pip3 install <package>
pip3 freeze > requirements.txt
```

## Install Locally

```bash
pip3 install -e .
```

## Troubleshooting

### Package Installation Issues
If you encounter issues installing the package with pip, particularly with the certifi dependency, you may see errors like:

```bash
error: uninstall-no-record-file
× Cannot uninstall certifi None
╰─> The package's contents are unknown: no RECORD file was found for certifi.
```
This can happen when multiple Python versions are installed or when system packages have been modified. Try these steps:

First, identify which Python version you're using:

```bash
which python3
python3 --version
which pip3
```

Remove the problematic certifi installation (adjust path based on your Python version):

```bash
sudo rm -rf /usr/local/lib/python3.13/site-packages/certifi
```

Install certifi directly:

```bash
pip3 install --ignore-installed certifi --break-system-packages
```

Then try installing lam-cli again:

```bash
pip3 install . --break-system-packages
```
