lud/README.md

The Luddites CLI Client To Manage Free And Paid Versions Of Packages For Publishing.

<div align="center"><p align="center">

# Lud

_by <a href="https://www.artd.eco">Art Deco&trade;</a>_ &mdash;<a href="https://www.artd.eco">Professional Software Development Company In London</a>.

[![npm version](https://badge.fury.io/js/protypes.svg)](https://www.npmjs.com/package/protypes)
<a href="https://gitlab.com/luddites/lud/-/commits/master">
  <img src="https://gitlab.com/luddites/lud/badges/master/pipeline.svg" alt="Pipeline Badge">
</a>
</p></div>

> **PLEASE REFER TO THE FULL DOCUMENTATION ON THE [LUD](https://artdeco.software/lud/) HOMEPAGE!**<br/>
> Information provided in this README has illustrative purpose only, is limited and doesn't describe API of this library in details.

`lud` is: a library to manage free and paid versions of the same package within its repo. The `package.json` source of truth for publishing is abandoned, and is only used to store dependencies' information for development purposes. In its place, the `package` folder is added in which a JS file `index.js` is kept from which metadata is exported. Different versions for publishing are stored as individual folders in the `package` folder, and `lud` generates `package.json` files to put in each of the versions (free/paid) and copies necessary files across.

The packages are published individually from within each of the folders with standard `yarn/npm publish` commands, however the future version will allow to publish packages on the [`luddites.io`](https://luddites.io) registry for paid packages.

Below is an example of the `package` folder:

```m
package
├── EULA
├── LICENSE
├── free
│   ├── CHANGELOG.md
│   ├── LICENSE
│   ├── README.md
│   ├── bin
│   │   └── lud.js
│   └── package.json
└── index.js
```

```sh
# lud is meant to be a dev dependency
yarn add -D lud
npm i --save-dev lud
```

<a name="table-of-contents"></a>

- [Example](#example)
- [CLI](#cli)
- [Copyright & License](#copyright--license)

<div align="center"><p align="center"><a href="#table-of-contents">
  <img alt="section break" src="https://luddites.gitlab.io/lud/section-breaks/0.svg">
</a></p></div>

## Example

The following is an example of `package/index.js` of the [_Erte_](https://npmjs.com/erte) package, that allows to use ANSI codes to format and colour strings for CLI output:

```js
import { dependencies } from '../package.json'

export let name = '@artdeco/erte'
export let description = 'String difference with colour and CLI ANSI formatting.'

let keywords = [
  'erte', 'art deco', 'artdeco',
  'string', 'diff', 'ansi',
  'color', 'colour',
  'difference', 'cli',
]
export let author = 'Art Deco™'
export let bugs = {
  url: 'https://github.com/art-deco/Issues',
  email: 'issues+erte@adc.sh',
}
export let homepage = 'https://www.artd.eco'

const EULA = 'package/EULA'
const LICENSE = 'package/LICENSE'

let compile = ['compile/index.js']
export const FREE = {
  description: `${description} [FREE]`,
  addFiles: ['README.md', 'CHANGELOG.md', LICENSE, ...compile],
  license: 'AGPL-3.0',
  keywords,
}
export const PUBLIC = {
  ...FREE,
  name: 'erte',
  description: `${description} [PUBLIC]`,
  copy: {
    'package/free/erte.js': 'erte.js',
  },
}
export const PAID = {
  description: `${description} [PAID]`,
  addFiles: ['README.md', 'CHANGELOG.md', EULA, ...compile],
  license: 'SEE LICENSE IN EULA',
  private: true,
  paid: true,
  keywords,
}
export const LIB = {
  dependencies,
  description: `${description} [LIB]`,
  addFiles: [EULA, ...compile, 'types', 'src'],
  module: 'src/index.js',
  externs: 'types/externs.js',
  license: 'SEE LICENSE IN EULA',
  private: true,
  paid: true,
  lib: true,
  copy: {
    'package/paid/erte.js': 'erte.js',
  },
}
```

The example includes different versions, including free (published on npm as `erte`) and its analogue but with namespace, public (published on npm as `@artdeco/erte`), as well as paid and library (w/ source code) versions published on the private registry. Since the source code is kept in a single repo, it would be a chore to switch between branches for different package versions, and maintaining different `package.json` files is too cumbersome, therefore _Lud_ solves this problem by allowing to generate and maintain multiple versions within the `package` directory.

There are additional APIs that can be used within the `index.js` file:

- `addFiles`: an array of files that need to be added to the target package, preserving their paths structure.
- `copy`: copies these files into the given location relative to the target package's folder.

Dependencies can be required from the `package.json` and exported via entry as well. However, in the example for Erte, they are only exported with the **LIB** version that is meant for development and provides the source code for the package, since all other versions compile the source code and its dependencies into a single JS file with a [compiler](https://www.compiler.page).

<div align="center"><p align="center"><a href="#table-of-contents">
  <img alt="section break" src="https://luddites.gitlab.io/lud/section-breaks/1.svg">
</a></p></div>

## CLI

The package is used from the CLI. Please refer to the [documentation](https://artdeco.software/lud/) for all available commands. Standard usage:

```console
# generate free version into package/free
lud@luddites:~$ lud -t package/free -e FREE
```

<div align="center"><p align="center"><a href="#table-of-contents">
  <img alt="section break" src="https://luddites.gitlab.io/lud/section-breaks/2.svg">
</a></p></div>



## Copyright & License

The public free version of the package is provided under the **GNU Affero General Public License v3.0** so that you can use it in AGPL-compatible projects. The full version requires purchasing of a license key and is distributed under an EULA terms. Please contact [Art Deco](https://keybase.io/artdeco) on Keybase chat to purchase the key.

<table>
  <tr>
    <th>
      <a href="https://www.artd.eco">
        <img width="100" src="https://gitlab.com/uploads/-/system/group/avatar/7454762/artdeco.png"
          alt="Art Deco">
      </a>
    </th>
    <th>© <a href="https://www.artd.eco">Art Deco™</a>   2020</th>
    <th>
      <a href="LICENSE"><img src="https://artdeco.gitlab.io/assets/licenses/agpl-3.0.svg" alt="AGPL-3.0"></a>
    </th>
  </tr>
</table>

<div align="center"><p align="center"><a href="#table-of-contents">
  <img alt="section break" src="https://luddites.gitlab.io/lud/section-breaks/-1.svg">
</a></p></div>