Added a permissionsTable script for yaml descriptors (#138)

* Added a permissionsTable script for yaml descriptors

* Update descriptor/package.json

Co-Authored-By: Brett Sun <[email protected]>

* Renamed examples folder

descriptor/README.md

@@ -0,0 +1,22 @@
+## Aragon organization descriptor utils
+
+### Installation
+
+Check out this repository then:
+
+```
+cd descriptor
+npm i
+```
+
+### Usage
+
+All scripts are run via npm script commands.
+
+#### permissionsTable script
+
+Generates a markdown table from a descriptor yaml file.
+
+```
+npm run permissionsTable ./descriptors/company.yaml
+```

descriptor/examples/company.yaml

@@ -0,0 +1,84 @@
+---
+id: company
+tokens:
+- ref: share
+  symbol: Share
+  name: Share Token
+  decimals: 18
+apps:
+- ref: shareholder-voting
+  type: voting
+  token: share
+  support: 50
+  acceptance: 5
+  duration: 604800
+- ref: share-tm
+  type: token-manager
+  token: share
+- type: finance
+  default: true
+  vault: agent
+  period: 2592000
+- ref: agent
+  type: agent
+  default: true
+actions:
+- ref: mint-shares
+  name: MintTokens
+  params:
+  - token: share
+    amounts: "$SHARE_AMOUNTS"
+    to: "$SHARE_KEYS"
+permissions:
+- app: kernel
+  role: APP_MANAGER_ROLE
+  grantee: share-voting
+  manager: share-voting
+- app: acl
+  role: CREATE_PERMISSIONS_ROLE
+  grantee: share-voting
+  manager: share-voting
+- app: share-voting
+  role: CREATE_VOTES_ROLE
+  grantee: share-tm
+  manager: share-voting
+- app: share-voting
+  role: MODIFY_QUORUM_ROLE
+  grantee: share-voting
+  manager: share-voting
+- app: share-voting
+  role: MODIFY_SUPPORT_ROLE
+  grantee: share-voting
+  manager: share-voting
+- app: agent
+  role: EXECUTE_ROLE
+  grantee: share-voting
+  manager: share-voting
+- app: agent
+  role: RUN_SCRIPT_ROLE
+  grantee: share-voting
+  manager: share-voting
+- app: agent
+  role: TRANSFER_ROLE
+  grantee: finance
+  manager: share-voting
+- app: finance
+  role: CREATE_PAYMENTS_ROLE
+  grantee: share-voting
+  manager: share-voting
+- app: finance
+  role: EXECUTE_PAYMENTS_ROLE
+  grantee: share-voting
+  manager: share-voting
+- app: finance
+  role: MANAGE_PAYMENTS_ROLE
+  grantee: share-voting
+  manager: share-voting
+- app: share-tm
+  role: BURN_ROLE
+  grantee: share-voting
+  manager: share-voting
+- app: share-tm
+  role: MINT_ROLE
+  grantee: share-voting
+  manager: share-voting

descriptor/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@aragon/template-descriptor",
+  "version": "0.0.1",
+  "description": "Processes yaml files that describe Aragon organization templates",
+  "author": "Aragon Association <[email protected]>",
+  "license": "GPL-3.0-or-later",
+  "scripts": {
+    "test": "mocha",
+    "permissionsTable": "node ./src/scripts/permissionsTable.js"
+  },
+  "dependencies": {
+    "js-yaml": "^3.13.1"
+  },
+  "devDependencies": {
+    "mocha": "^6.2.0"
+  }
+}

descriptor/src/scripts/permissionsTable.js

@@ -0,0 +1,18 @@
+const readYaml = require('../utils/readYaml')
+
+const args = process.argv.slice(2)
+const descriptorFilePath = args[0]
+
+const yaml = readYaml(descriptorFilePath)
+
+let str = 'App | Permission | Grantee | Manager\n'
+str += '--- | --- | --- | ---\n'
+yaml.permissions.forEach((permission) => {
+  const app = permission.app || '?'
+  const role = permission.role || '?'
+  const grantee = permission.grantee || '?'
+  const manager = permission.manager || '?'
+  str += `${app}|${role}|${grantee}|${manager}\n`
+})
+
+console.log(str)

descriptor/src/utils/readYaml.js

@@ -0,0 +1,9 @@
+const yaml = require('js-yaml')
+const fs = require('fs')
+
+const readYaml = (filePath) => {
+  const file = fs.readFileSync(filePath, 'utf8')
+  return yaml.safeLoad(file)
+}
+
+module.exports = readYaml

descriptor/test/permissionsTable.test.js

@@ -0,0 +1,44 @@
+const assert = require('assert')
+const cli = require('./utils/cli.js')
+
+describe('permissionsTable script', () => {
+
+  it('generates expected output', async () => {
+    const result = await cli(
+      'permissionsTable.js',
+      './examples/company.yaml',
+    )
+    assert.equal(result.code, 0)
+    assert.equal(result.stdout.includes('App | Permission | Grantee | Manager'), true)
+    assert.equal(result.stdout.includes('--- | --- | --- | ---'), true)
+    assert.equal(result.stdout.includes('kernel|APP_MANAGER_ROLE|share-voting|share-voting'), true)
+    assert.equal(result.stdout.includes('acl|CREATE_PERMISSIONS_ROLE|share-voting|share-voting'), true)
+    assert.equal(result.stdout.includes('share-voting|CREATE_VOTES_ROLE|share-tm|share-voting'), true)
+    assert.equal(result.stdout.includes('share-voting|MODIFY_QUORUM_ROLE|share-voting|share-voting'), true)
+    assert.equal(result.stdout.includes('share-voting|MODIFY_SUPPORT_ROLE|share-voting|share-voting'), true)
+    assert.equal(result.stdout.includes('agent|EXECUTE_ROLE|share-voting|share-voting'), true)
+    assert.equal(result.stdout.includes('agent|RUN_SCRIPT_ROLE|share-voting|share-voting'), true)
+    assert.equal(result.stdout.includes('agent|TRANSFER_ROLE|finance|share-voting'), true)
+    assert.equal(result.stdout.includes('finance|CREATE_PAYMENTS_ROLE|share-voting|share-voting'), true)
+    assert.equal(result.stdout.includes('finance|EXECUTE_PAYMENTS_ROLE|share-voting|share-voting'), true)
+    assert.equal(result.stdout.includes('finance|MANAGE_PAYMENTS_ROLE|share-voting|share-voting'), true)
+    assert.equal(result.stdout.includes('share-tm|BURN_ROLE|share-voting|share-voting'), true)
+    assert.equal(result.stdout.includes('share-tm|MINT_ROLE|share-voting|share-voting'), true)
+  })
+
+  it('throws if given no path', async () => {
+    const result = await cli(
+      'permissionsTable.js',
+      '',
+    )
+    assert.equal(result.code, 1)
+  })
+
+  it('throws if given an invalid path', async () => {
+    const result = await cli(
+      'permissionsTable.js',
+      '../non-existing.yaml',
+    )
+    assert.equal(result.code, 1)
+  })
+})

descriptor/test/utils/cli.js

@@ -0,0 +1,21 @@
+const path = require('path')
+const exec = require('child_process').exec
+
+module.exports = function cli(script, ...args) {
+  const cwd = '.'
+  return new Promise(resolve => {
+    exec(
+      `node ./src/scripts/${script} ${args.join(' ')}`,
+      { cwd },
+      (error, stdout, stderr) => {
+        const err = error || stderr
+        resolve({
+          code: err ? 1 : 0,
+          error: err,
+          stdout,
+          stderr
+        })
+      }
+    )
+  })
+}