Add graph init with --from-example and --from-contract modes

README.md

@@ -5,117 +5,52 @@
 
 ## The Graph Command Line Interface
 
-As of today, the command line interface consists of five commands:
+As of today, the command line interface supports the following commands:
 
-- `graph codegen` — Generates TypeScript code for smart contract ABIs used in subgraphs.
-- `graph build` — Compiles subgraphs to WebAssembly and deploys them to IPFS.
-- `graph deploy` — Deploys subgraphs to a [Graph Node](https://github.com/graphprotocol/graph-node).
-- `graph remove` — Removes subgraphs from a [Graph Node](https://github.com/graphprotocol/graph-node).
-- `graph auth` — Saves access token for [Graph Node](https://github.com/graphprotocol/graph-node) to the system's keychain.
+- `graph init` — Creates a new subgraph project from an example or an existing contract.
+- `graph create` — Registers a subgraph name with a Graph Node.
+- `graph remove` — Unregisters a subgraph name with a Graph Node.
+- `graph codegen` — Generates AssemblyScript types for smart contract ABIs and the subgraph schema.
+- `graph build` — Compiles a subgraph to WebAssembly.
+- `graph deploy` — Deploys a subgraph to a [Graph Node](https://github.com/graphprotocol/graph-node).
+- `graph auth` — Stores a [Graph Node](https://github.com/graphprotocol/graph-node) access token in the system's keychain.
 
 ## How It Works
 
-`graph` takes a subgraph manifest (defaults to `subgraph.yaml`) with references to:
+The Graph CLI takes a subgraph manifest (defaults to `subgraph.yaml`) with references to:
 
 - A GraphQL schema,
 - Smart contract ABIs, and
-- Mappings written in TypeScript/AssemblyScript.
+- Mappings written in AssemblyScript.
 
 It compiles the mappings to WebAssembly, builds a ready-to-use version of the subgraph saved to IPFS or a local directory for debugging, and deploys the subgraph to a [Graph Node](https://github.com/graphprotocol/graph-node).
 
-## Usage
+## Installation
 
-Subgraphs for The Graph are set up like a typical TypeScript project. We recommend installing `graph-cli` as a local dependency via `package.json` and use `npm` scripts for code generation and building.
+The Graph CLI can be installed with `npm` or `yarn`:
 
-If you are just getting started with creating a subgraph, read the [Getting Started](https://github.com/graphprotocol/graph-node/blob/master/docs/getting-started.md) document. Eventually, that guide will lead you back here.
+```sh
+# NPM
+npm install -g @graphprotocol/graph-cli
 
-For clarity, an example of the setup below can be found in the [ENS subgraph repository](https://github.com/graphprotocol/ens-subgraph).
+# Yarn
+npm add --global @graphprotocol/graph-cli
+```
 
 ### On Linux
 
 `libsecret` is used for storing access tokens, so you may need to install it before getting started. Use one of the following commands depending on your distribution:
+
 - Debian/Ubuntu: `sudo apt-get install libsecret-1-dev`
 - Red Hat: `sudo yum install libsecret-devel`
 - Arch Linux: `sudo pacman -S libsecret`
 
-### Steps
-
-1.  Create a project for the subgraph with a `package.json`.
-2.  Add a `subgraph.yaml` subgraph manifest with a GraphQL schema.
-3.  Add `@graphprotocol/graph-cli` and `@graphprotocol/graph-ts` dependencies with either NPM or Yarn.
-
-    ```bash
-    # NPM
-    npm install --save-dev
-      @graphprotocol/graph-cli \
-      @graphprotocol/graph-ts
-
-    # Yarn
-    yarn add --dev \
-      @graphprotocol/graph-cli \
-      @graphprotocol/graph-ts
-    ```
-
-4.  Add the following `tsconfig.json`:
-    ```json
-    {
-      "extends": "./node_modules/@graphprotocol/graph-ts/tsconfig.json",
-      "compilerOptions": {
-        "types": ["@graphprotocol/graph-ts"]
-      }
-    }
-    ```
-5.  Add the following to `package.json`:
-    ```json
-    {
-      "scripts": {
-        "codegen": "graph codegen --output-dir types/",
-        "build": "graph build",
-        "build-ipfs": "graph build --ipfs /ip4/127.0.0.1/tcp/5001",
-        "deploy":
-          "graph deploy --ipfs /ip4/127.0.0.1/tcp/5001 --node http://127.0.0.1:8020 --subgraph-name <SUBGRAPH_NAME>"
-      }
-    }
-    ```
-    **Note:** Replace the IP addresses and ports with any [Graph Node](https://github.com/graphprotocol/graph-node) you want to deploy the subgraph to.
-6.  Generate type definitions for contract ABIs used in the subgraph with:
-    ```bash
-    yarn codegen
-    ```
-     This creates the `types/` folder. This folder does not need to be uploaded to GitHub, and the files within it should not be edited. With these types created, you can get auto complete for the types while writing the mappings.
-
-7.  Develop your `mapping.ts` against these generated types. If you are new to this process, read the [Getting Started](https://github.com/graphprotocol/graph-node/blob/master/docs/getting-started.md#34-write-your-mappings) document for a beginner-friendly walkthrough of The Graph.
-
-8.  Deploy your subgraph to a [Graph Node](https://github.com/graphprotocol/graph-node). The following command builds and deploys the subgraph continuously as you are making changes to it:
-    ```sh
-    graph \
-       deploy \
-       --watch \
-       --verbosity debug \
-       --node http://127.0.0.1:8020/ \
-       --ipfs /ip4/127.0.0.1/tcp/5001 \
-       --subgraph-name <SUBGRAPH_NAME>
-    ```
-    **Note:** If the Graph Node you are deploying to requires authorization, make sure to authorize the node using `graph auth http://127.0.0.:8020 <ACCESS_TOKEN>` before deploying.
-
-    You can also use the deploy script added into `package.json`:
-
-    ```sh
-    yarn deploy --debug
-    ```
-
-    This will deploy the subgraph. If you want it to continuously upgrade, also pass the `--watch` flag.
-
-    `yarn deploy` will create the `dist/` folder. Within this folder are the compiled WASM files from the AssemblyScript mappings. Since this folder is generated, it does not need to be tracked in version control.
-
-
-To remove a subgraph from the [Graph Node](https://github.com/graphprotocol/graph-node), use:
-```sh
-graph \
-  remove \
-  --node http://127.0.0.1:8020/ \
-  --subgraph-name <SUBGRAPH_NAME>
-```
+## Getting Started
+
+The Graph CLI can be used with a local or self-hosted [Graph Node](https://github.com/graphprotocol/graph-node) or with the [Hosted Service](https://thegraph.com/explorer/). To help you get going, there are [quick start guides](https://thegraph.com/docs/quick-start) available for both.
+
+If you are ready to dive into the details of building a subgraph from scratch, there is a [detailed walkthrough](https://thegraph.com/docs/define-a-subgraph) for that as well, along with API documentation for the [AssemblyScript API](https://thegraph.com/docs/assemblyscript-api).
+
 ## License
 
 Copyright &copy; 2018-2019 Graph Protocol, Inc. and contributors.

package.json

@@ -16,15 +16,18 @@
     "jayson": "^2.0.6",
     "js-yaml": "^3.12.0",
     "keytar": "^4.3.0",
+    "node-fetch": "^2.3.0",
+    "pkginfo": "^0.4.1",
     "prettier": "^1.13.5",
     "request": "^2.88.0"
   },
   "bin": {
     "graph": "bin/graph"
   },
   "devDependencies": {
-    "jest": "^23.6.0",
-    "spawn-command": "^0.0.2-1"
+    "jest": "^24.3.0",
+    "spawn-command": "^0.0.2-1",
+    "strip-ansi": "^5.0.0"
   },
   "scripts": {
     "test": "jest --verbose"

src/codegen/types/conversions.js

@@ -161,22 +161,24 @@ const VALUE_TO_ASSEMBLYSCRIPT = [
 const ASSEMBLYSCRIPT_TO_VALUE = [
   // Arrays
 
+  ['Array<Address>', '[Bytes]', code => `Value.fromBytesArray(${code})`],
   ['Array<Bytes>', '[Bytes]', code => `Value.fromBytesArray(${code})`],
   ['Array<boolean>', '[Boolean]', code => `Value.fromBooleanArray(${code})`],
   ['Array<i32>', '[Int]', code => `Value.fromI32Array(${code})`],
   ['Array<BigInt>', '[BigInt]', code => `Value.fromBigIntArray(${code})`],
-  ['Array<string>', '[ID]', code => `Value.fromStringArray(${code})`],
   ['Array<string>', '[String]', code => `Value.fromStringArray(${code})`],
+  ['Array<string>', '[ID]', code => `Value.fromStringArray(${code})`],
   ['Array<string>', /\[.*\]/, code => `Value.fromStringArray(${code})`],
 
   // Scalar values
 
+  ['Address', 'Bytes', code => `Value.fromBytes(${code})`],
   ['Bytes', 'Bytes', code => `Value.fromBytes(${code})`],
   ['boolean', 'Boolean', code => `Value.fromBoolean(${code})`],
   ['i32', 'Int', code => `Value.fromI32(${code})`],
   ['BigInt', 'BigInt', code => `Value.fromBigInt(${code})`],
-  ['string', 'ID', code => `Value.fromString(${code})`],
   ['string', 'String', code => `Value.fromString(${code})`],
+  ['string', 'ID', code => `Value.fromString(${code})`],
   ['string', /.*/, code => `Value.fromString(${code})`],
 ]
 

src/codegen/types/index.js

@@ -92,6 +92,9 @@ const ethereumValueFromAsc = (code, ethereumType) =>
 const ascTypeForValue = valueType =>
   findConversionFromType('Value', 'AssemblyScript', valueType).getIn(['to', 'type'])
 
+const valueTypeForAsc = ascType =>
+  findConversionFromType('AssemblyScript', 'Value', ascType).getIn(['to', 'type'])
+
 const valueToAsc = (code, valueType) =>
   findConversionFromType('Value', 'AssemblyScript', valueType).get('convert')(code)
 
@@ -107,6 +110,7 @@ module.exports = {
 
   // Value <-> AssemblyScript
   ascTypeForValue,
+  valueTypeForAsc,
   valueToAsc,
   valueFromAsc,
 }

src/command-helpers/gluegun.js

@@ -0,0 +1,51 @@
+// Workaround for https://github.com/infinitered/gluegun/pull/464.
+//
+// There is currently no way in Gluegun to define command-line options
+// that take no arguments (like `--watch`). As a consequence, boolean
+// options like `--watch` will consume the immediately following argument,
+// leading to confusing behavior.
+//
+// E.g. `graph deploy --watch subgraph/name
+//
+// Will result in
+// ```
+// toolbox.parameters.options === { watch: 'subgraph/name' }
+// toolbox.parameters.first === undefined
+// toolbox.parameters.array === []
+// ```
+// where what we really want is
+// ```
+// toolbox.parameters.options === { watch: true }
+// toolbox.parameters.first = 'subgraph/name'
+// toolbox.parameters.array = ['subgraph/name']
+// ```
+//
+// The `fixParameters` function checks if any of the provided boolean
+// options has a string value; if so, it pushes it to the front of the
+// parameters array and returns the result of that.
+//
+const fixParameters = (parameters, booleanOptions) => {
+  let unexpectedStringOptions = Object.keys(booleanOptions)
+    .filter(key => typeof booleanOptions[key] === 'string')
+    .map(key => ({ key, value: booleanOptions[key] }))
+
+  let optionNames = unexpectedStringOptions
+    .map(({ key }) => `--` + key.replace(/([A-Z])/, '-$1').toLowerCase())
+    .join(', ')
+
+  if (unexpectedStringOptions.length > 1) {
+    throw new Error(
+      `Unexpected value provided for one or more of ${optionNames}. See --help for more information.`
+    )
+  } else if (unexpectedStringOptions.length == 1) {
+    let params = parameters.array
+    params.unshift(unexpectedStringOptions[0].value)
+    return params
+  } else {
+    return parameters.array
+  }
+}
+
+module.exports = {
+  fixParameters,
+}

src/commands/build.js

@@ -1,6 +1,7 @@
 const chalk = require('chalk')
 
 const { createCompiler } = require('../command-helpers/compiler')
+const { fixParameters } = require('../command-helpers/gluegun')
 
 const HELP = `
 ${chalk.bold('graph build')} [options] ${chalk.bold('[<subgraph-manifest>]')}
@@ -41,13 +42,27 @@ module.exports = {
     outputFormat = outputFormat || t
     watch = watch || w
 
+    let manifest
+    try {
+      ;[manifest] = fixParameters(toolbox.parameters, {
+        h,
+        help,
+        w,
+        watch,
+      })
+    } catch (e) {
+      print.error(e.message)
+      process.exitCode = 1
+      return
+    }
+
     // Fall back to default values for options / parameters
     outputFormat =
       outputFormat && ['wasm', 'wast'].indexOf(outputFormat) >= 0 ? outputFormat : 'wasm'
     outputDir = outputDir && outputDir !== '' ? outputDir : filesystem.path('build')
-    let manifest =
-      toolbox.parameters.first !== undefined && toolbox.parameters.first !== ''
-        ? toolbox.parameters.first
+    manifest =
+      manifest !== undefined && manifest !== ''
+        ? manifest
         : filesystem.resolve('subgraph.yaml')
 
     // Show help text if requested

src/commands/codegen.js

@@ -1,5 +1,7 @@
 const chalk = require('chalk')
+
 const TypeGenerator = require('../type-generator')
+const { fixParameters } = require('../command-helpers/gluegun')
 
 const HELP = `
 ${chalk.bold('graph codegen')} [options] ${chalk.bold('[<subgraph-manifest>]')}
@@ -25,14 +27,28 @@ module.exports = {
     outputDir = outputDir || o
     watch = watch || w
 
+    let manifest
+    try {
+      ;[manifest] = fixParameters(toolbox.parameters, {
+        h,
+        help,
+        w,
+        watch,
+      })
+    } catch (e) {
+      print.error(e.message)
+      process.exitCode = 1
+      return
+    }
+
     // Fall back to default values for options / parameters
     outputDir =
       outputDir !== undefined && outputDir !== ''
         ? outputDir
         : filesystem.path('generated')
-    let manifest =
-      toolbox.parameters.first !== undefined && toolbox.parameters.first !== ''
-        ? toolbox.parameters.first
+    manifest =
+      manifest !== undefined && manifest !== ''
+        ? manifest
         : filesystem.resolve('subgraph.yaml')
 
     // Show help text if requested

src/commands/deploy.js

@@ -1,11 +1,12 @@
 const chalk = require('chalk')
 
+const { identifyAccessToken } = require('../command-helpers/auth')
 const { createCompiler } = require('../command-helpers/compiler')
+const { fixParameters } = require('../command-helpers/gluegun')
 const { createJsonRpcClient } = require('../command-helpers/jsonrpc')
-const { identifyAccessToken } = require('../command-helpers/auth')
-const { validateSubgraphName } = require('../command-helpers/subgraph')
 const { validateNodeUrl } = require('../command-helpers/node')
 const { withSpinner } = require('../command-helpers/spinner')
+const { validateSubgraphName } = require('../command-helpers/subgraph')
 
 const HELP = `
 ${chalk.bold('graph deploy')} [options] ${chalk.bold('<subgraph-name>')} ${chalk.bold(
@@ -15,7 +16,7 @@ ${chalk.bold('graph deploy')} [options] ${chalk.bold('<subgraph-name>')} ${chalk
 Options:
 
       --access-token <token>    Graph access token
-  -g, --node                    Graph node to deploy the subgraph to
+  -g, --node <node>             Graph node to deploy the subgraph to
   -h, --help                    Show usage information
   -i, --ipfs <node>             Upload build results to an IPFS node
   -o, --output-dir <path>       Output directory for build results (default: build/)
@@ -50,12 +51,25 @@ module.exports = {
     outputDir = outputDir || o
     watch = watch || w
 
+    let subgraphName, manifest
+    try {
+      ;[subgraphName, manifest] = fixParameters(toolbox.parameters, {
+        h,
+        help,
+        w,
+        watch,
+      })
+    } catch (e) {
+      print.error(e.message)
+      process.exitCode = 1
+      return
+    }
+
     // Fall back to default values for options / parameters
     outputDir = outputDir && outputDir !== '' ? outputDir : filesystem.path('build')
-    let subgraphName = toolbox.parameters.first
-    let manifest =
-      toolbox.parameters.second !== undefined && toolbox.parameters.second !== ''
-        ? toolbox.parameters.second
+    manifest =
+      manifest !== undefined && manifest !== ''
+        ? manifest
         : filesystem.resolve('subgraph.yaml')
 
     // Show help text if requested