Copied issue from gramps-graphql/gramps-express#35

Add API docs and an intro tutorial for the CLI.

We need docs before we can officially release.

Per feedback from @ecwyne, we should be deleting the temporary directory on process exit.

gramps-cli is not working at all with node 10 because of the cpy module
sindresorhus/cpy#44

pr already created by bot here:
#49

please merge.

regards,
Mostafa

@jlengstorf commented on Tue Oct 24 2017

The CLI currently doesn't have any tests written. We'll probably need a light refactor to make it easier to test.

@ecwyne it looks like the ability to override data sources with a local version got lost in this migration. Was there a reason you pulled it out, or was it just an oversight that we can revert?

@jlengstorf Unfortunately I can't fork this repo while it's empty nor do I have write privileges so I can't push to a non-master branch either.

From what I can tell the /gateway directory didn't make it to v1.1.2 on npm

Version 10 of Node.js (code name Dubnium) has been released! 🎊

To see what happens to your code in Node.js 10, Greenkeeper has created a branch with the following changes:

• Added the new Node.js version to your .travis.yml

If you’re interested in upgrading this repo to Node.js 10, you can open a PR with these changes. Please note that this issue is just intended as a friendly reminder and the PR as a possible starting point for getting your code running on Node.js 10.

Your Greenkeeper Bot 🌴

Several things appear to be going wrong in the git bash shell on Windows. I'm unable to confirm any of these because I don't have a Windows machine, so this is just me repeating what I've been told.

del.sync hangs infinitely

Despite the fact it should be Windows-compatible, del.sync() seems to hang forever in git bash.

mkdirp doesn't work

Similarly, mkdirp seems to be failing in git bash

Relative paths are converted to absolute paths

The temporary directory path is being set to something like this:

C:\Users\dev\git\graphql-data-source-test\node_modules\@gramps\cli\dist\.tmp\C:\Users\dev\git\graphql-data-source-test

According to the dev having these issues, if del.sync is omitted, mkdirp is omitted, and a hard-coded temp dir path is used, the CLI works as intended.

@kbrandwijk, if you have a chance to take a look at this when you're free, I'd really appreciate it.

I'm unable to load data-sources using cli.

dataSources = [], ^^^^^^^^^^^^^^^^ SyntaxError: Invalid shorthand property initializer at Object.exports.runInThisContext (vm.js:76:16)

Also won't this always equal false?

const handler = exports.handler = async ({
  dataSources = [],
  mock = false,
  gateway,
  transpile
}) => {
  (0, _logger.warn)('The GrAMPS CLI is intended for local development only.');

  let dataSourcePaths = [];
  let loadedDataSources = [];
  if (dataSources.length) {

Per the discussion that started on #4, we need to finalize the actual API of this tool. We know what it should do, but need to agree on how to actually expose the commands.

I'm porting the last comment from #4 to here:

@corycook @ecwyne To try and consolidate things, let me do a recap of where we are so far:

Cory’s Proposal

API

gramps [<datasource> [<datasource> ...]] [--live | --mock] [--gateway=<gateway>]

Examples

# run the current data source with the built-in dev server
gramps

# run the current data source with the built-in dev server in live mode
gramps --live

# run the current data source + an additional data source
gramps ./ ../otherSource

# run the current source + a custom gateway
gramps --gateway ../gateway

Additional Recommendation from Cory: Don’t Transpile

I'm personally against this because it's moving us further and further from a plug-and-play solution, but I'd be down to have an opt-out flag (e.g. gramps --no-transpile). A requirement to set up additional tools (e.g. concurrently) for dev seems like more overhead than is necessary. For advanced users, I think an opt-out is fine, but for someone who's new to this I think they should be able to just run gramps dev and see some data in GraphiQL.

Eric’s Proposal

API

gramps dev [<datasource> [<datasource> ...]] [--live | --mock]
gramps serve <gateway> [--override=<datasource> [--override=<datasource> ...]] [--live | --mock]

Examples

# run the current data source with the built-in dev server
gramps dev

# run the current data source with the built-in dev server in live mode
gramps dev --live

# run the current data source + an additional data source
gramps dev . ../otherSource

# run the current source + a custom gateway
gramps serve ../gateway --override ./

Jason’s Proposal

API

gramps dev [<gateway>] [--data-source=<datasource> [--data-source=<datasource> ...]] [--live | --mock] [--gateway=<gateway>]

Examples

# run the current data source with the built-in dev server
gramps dev --data-source .

# run the current data source with the built-in dev server in live mode
gramps dev --data-source . --live

# run the current data source + an additional data source
gramps dev --data-source . --data-source ../otherSource

# run the current source + a custom gateway
gramps dev ../gateway --data-source .

The Good Stuff

I think we've all got good ideas and good rationale behind them, so I want to see if I can walk through our main points of contention

Positional vs. Explicit Args

My preference is to remain explicit. Positional arguments are confusing to me, because it's not clear if ./one ./two is an input > output arg, or a "use both of these" arg. I think it's easier to reason about code that tells you what it does with descriptive options.

Command Name

I think @ecwyne had a great idea to change the command from gramps to something more clear: gramps dev. We may want to add new commands in the future (e.g. new data source creation), plus it makes it more obvious that this is only intended for development.

Pulling It All Together

Based on the three options, I've got two suggestions:

1. An API with named args (my preference)
2. An API with positional args

Potential Named Args API

gramps dev [--data-source=<datasource> [--data-source=<datasource> ...]] [--live | --mock] [--gateway=<gateway>] [--no-transpile]

Examples

# run the built-in dev server with no data sources (for "hello world" testing)
gramps dev

# run the current data source with the built-in dev server
gramps dev --data-source .

# run the current data source with the built-in dev server in live mode
gramps dev --data-source . --live

# run the current data source + an additional data source
gramps dev --data-source . --data-source ../otherSource

# run the current source + a custom gateway
gramps dev --data-source . --gateway ../gateway

# run the current source + custom gateway in live mode with no transpilation
gramps dev --data-source . --gateway ../gateway --live --no-transpile

Potential Positional API

gramps dev [<datasource> [<datasource> ...]] [--live | --mock] [--gateway=<gateway>] [--no-transpile]

Examples

# run the built-in dev server with no data sources (for "hello world" testing)
gramps dev

# run the current data source with the built-in dev server
gramps dev .

# run the current data source with the built-in dev server in live mode
gramps dev . --live

# run the current data source + an additional data source
gramps dev . ../otherSource

# run the current source + a custom gateway
gramps dev . --gateway ../gateway

# run the current source + custom gateway in live mode with no transpilation
gramps dev . --gateway ../gateway --live --no-transpile

What does everyone think of this?

I'd like a -p or --port flag in the CLI to specify the port. I like that get-port has a preferred port option, although port 8080 is a pretty popular port so being able to change the default yarn dev port would be useful for local development and testing.

We need #9 to be completed before we can do this. During development, we need to the ability to provide a gateway start script.

This needs to:

• Start a GraphQL gateway server
• Allow overriding installed data sources with local data sources (dev only)

Once the 1.0 release is ready and the docs are written, we need to update the README with a new quickstart and docs links.

After a discussion today with @schickling, @kbrandwijk, and @nikolasburk about how GrAMPS data sources will fit with external tools (such as Graphcool and qewl), a couple things came up:

1. GrAMPS data sources should be exporting an executable schema, and not the typeDefs/resolvers/mocks as I was previously pushing for
2. GrAMPS data sources should not require the context to be attached externally (meaning there should be no intermediate step to attach a data source context to its resolvers)

(@ecwyne and @corycook, you're going to say, "I told you so.") 😄

Please get rid of reify, and set up babel, because any module importing gramps-cli is forced to add require('reify'), otherwise the code cannot be imported. See https://github.com/supergraphql/graphql-cli-gramps/blob/master/src/index.ts

Once we have a finalized API (#9), we need to refactor the CLI to start data sources using it.

Hi,

It'd be great if the cli can provide watch mode, something like:

$(yarn bin)/gramps dev --watch -d ./

Best,
Joseph

The dependency @gramps/gramps was updated from 1.4.0 to 1.5.0.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

@gramps/gramps is a direct dependency of this project, and it is very likely causing it to break. If other packages depend on yours, this update is probably also breaking those in turn.

Your Greenkeeper Bot 🌴

Let's get this thing to 1.0!

For the CLI, here's what we need to do:

• Design: Finalize the API #9
• Refactor: Start data source(s) with a local dev server (this should already work, but needs to be refactored to the formate in #9) #11
• Feature: Add support for using a custom gateway during local dev #10
• Docs: Write CLI docs #6
• Docs: Update the README #13

- [ ] Feature: Move to Typescript #8 <-- let's do this, but not block the 1.0 release for it.

@ecwyne @corycook Am I missing anything here?

A discussion with @schickling suggested the use of Typescript, since the majority of the GraphQL tooling ecosystem is written in Typescript.

I'm on board with this for the core of GrAMPS, but want to make sure that data sources don't require Typescript. (Doing so would be a huge onboarding problem within my team; it's not possible to just proclaim, "Okay, everyone needs to learn Typescript now!")

@corycook, you've got Typescript experience, right?

Use the format from https://github.com/gramps-graphql/gramps

@jlengstorf commented on Sat Dec 23 2017

@kbrandwijk commented on Sat Dec 23 2017

Should probably go here: https://github.com/gramps-graphql/gramps-cli?