We use the feature's name as a unique identifier throughout the system, and for the purposes of typings. This should be validated in the frontend.

Blocked by #7, because currently the GUI is using the old terminology.

Big Sextant fan!

It would be fantastic if we had the ability to export an image of our Sextant diagrams straight to clipboard/file so that we could do things like drop them into Github issues or share with peers (sort of like how Excalidraw's "copy as PNG to clipboard" does it).

This includes documenting the functions and methods that each plugin exposes, but also documenting in the 'advanced' section on how to create your own plugin.

Fix: make Sextant create the directory if it doesn't exist.

Similar to Playroom, we should have the ability to easily share a sextant diagram with others.

This would work by saving the entire database as a Base64 string in the URL search parameters. One could then preview the link by visiting https://demo.sextant.tools?special-link.

Edits to the database would then be done to the Base64 string, meaning users could edit documents asychronously and collaboratively.

Using plugins

You'd use plugins by adding a sextant.config.js inside the directory you target with sextant ./target-dir. The config file might look like this:

// sextant.config.js

module.exports = {
  plugins: [
    // Reference to a node_module, with config
    ['@sextant-tools/plugin-typescript', { configOption: true }],

    // Reference to a local plugin file
    './local-plugin-file.js',

    // An inline implementation of a plugin
    createPlugin(() => {}),
  ]
}

I'm also envisaging that users could add plugins and manage configuration through the Sextant GUI, giving an awesome experience for folks wanting to explore plugin possibilities.

Creating a plugin

@sextant-tools/core would export a function: createPlugin. This could be used like this:

// sextant-plugin.js
const { createPlugin } = require('@sextant-tools/core');

module.exports = createPlugin((sextantContext, pluginConfig) => {
  // do something with the data you get
})

I'm in favour of the createPlugin syntax because you get more discoverability of our API through Typescript inference on sextantContext and pluginConfig.

From here, you have access to the usual node API's, as well as any custom API's we'll give you to through sextantContext.

An awesome use for Sextant could be generating code for a Lambda endpoint. Let's imagine you have a consistent environment name of 'lambda' across multiple services (glossary here #7). This lambda can be accessed from another consistently named environment, the 'frontend'.

So each service could map to a /path (Get Users becomes /get-users) which each takes a POST, and the event as an application/json. It then must send back an event described in Sextant. This might be implemented like this:

import express from 'express';
import { buildExpressApi } from './sextant-generated-code';

const app = express();

const lambdaEndpoints = buildExpressApi({
  // req.body would be typed to the input event, and req.json would be typed to the output
  getUsers: (req, res) => {},
  someOtherService: (req, res) => {},
});

lambdaEndpoints.forEach(({ handler, path }) => {
  app.post(path, handler)
});

Looks like it is meant to run just on your machine.

This'll be useful in development, but also for CI.

Some kind of issue exists when creating new events. When running through the Success case for Get User, the USER event
type was not created. I had to delete the event node using the X button and redo it to get the Event payload to show up properly.

Suggested labels: Recipes

We have the potential to build a beautiful, beautiful GUI. Currently, we have a bit of a gnarly one that I threw together.

An ideal contribution from someone visual-minded would be to go through and redesign the GUI from the ground up, adding the polish it deserves.

The codebase is your digital garden - go for it.

When the server stops, any changes will no longer be saved to the database. This ain't good. We should make it so a snackbar appears to tell users to restart the dev server.

Currently, we use react-contenteditable for input fields on titles, events, and environment names.

This isn't a good idea, because it can occasionally emit crazy HTML syntax instead of human-readable text. We need an input component that:

1. Can stretch easily to take up space
2. Looks editable enough to want to click and edit it, but also presentational enough when it's not being edited.

We should create a docs site, and link to it from the Sextant GUI.

These can live at https://sextant.tools/docs

I'd like to see what people are thinking about this tool in regards to sharing configs and start a discussion about structure and code generation.

What are our current thoughts about sharing these things across projects and/or colocation?

Regarding this reference diagram:

Presumably that diagram has actors that are spread across projects - do we have a workflow for "sharing" sextant config among disparate projects?

Is sextant suited to be part of a mono-repo? Is it suited to be part of a monolithic project?

Could it generate code shared by all packages in a mono-repo? Should it generate a "package" for itself?

As plugins mature, maybe it could generate many types of code in different places? Perhaps akin to graphql-code-generator, you could define which files and plugins are output to which places and have it at the root of the project?

Just thinking out loud, but please reply with any thoughts. @mattpocock feel free to edit or tweak this as you see fit.

This would make it clearer that it performs an action, rather than being some sort or link or label.

When running yarn install on a fresh repo clone, the postinstall script is failing. This makes sense as packages/core is trying to use lib/index.js as main entry AND lib/index.js is only available once running yarn build.

Stack Trace

Scanning File: packages/frontend/src/components/keepDataInSync.machine.ts
Error: Cannot find module '/Users/juanditoro/open-source/sextant/node_modules/@sextant-tools/core/lib/index.js'. Please verify that the package.json has a valid "main" entry
    at tryPackage (internal/modules/cjs/loader.js:322:19)
    at Function.Module._findPath (internal/modules/cjs/loader.js:683:18)
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:953:27)
    at Function.Module._load (internal/modules/cjs/loader.js:842:27)
    at Module.require (internal/modules/cjs/loader.js:1026:19)
    at require (internal/modules/cjs/helpers.js:72:18)
    at Object.<anonymous> (/Users/juanditoro/open-source/sextant/packages/frontend/src/components/keepDataInSync-machine-ts-j5gbi67cgzc.xstate.js:5:12)
    at Module._compile (internal/modules/cjs/loader.js:1138:30)
    at Object.module_1.default._extensions..xstate.js (/Users/juanditoro/open-source/sextant/node_modules/xstate-codegen/bin/extractMachines.js:72:12)
    at Module.load (internal/modules/cjs/loader.js:986:32) {
  code: 'MODULE_NOT_FOUND',
  path: '/Users/juanditoro/open-source/sextant/node_modules/@sextant-tools/core/package.json',
  requestPath: '@sextant-tools/core'
}
Could not complete due to errors
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] codegen:machines: `xstate-codegen "./!(node_modules)/!(node_modules)/**/**.machine.ts" --once`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] codegen:machines script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/juanditoro/.npm/_logs/2020-10-31T13_50_49_214Z-debug.log
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command.

@mattpocock

We should work out what best to call things in Sextant. I am keen to hear about prior art, and what feels most natural for you.

Environments

Environments are things that can fire events and receive events, like actors in an actor system.

Possible Alternatives:

Actors. Resources.

Events

Events are what link up environments to each other.

Possible alternatives

None. I like 'events'. They match up to 'event-driven-programming', XState 'events'.

Sequences

A sequence is a chain of events. A single sequence matches a single path through the system, like a success or failure case.

Possible alternatives

Test cases. Cases. Chains. Branches. Variants. Paths. Lots here.

Services

A service is a group of sequences. Together, sequences form an overview of possible paths through a system. You can see what happens when something works, and when it doesn't. This graph of possibilities is the service.

Possible alternatives

Systems. Behaviour Graphs...? Workflows. Features. Lots here too.

EDIT

The new terminology is Features, Scenarios, Actors and Events. We should migrate the database and generated types to use these new terms.

I think hasura could make a good plugin, possibly generating some queries or mutations based on events that are sent or received based on a project's graphql schema.

Thoughts:

• failure cases returning to hasura could adopt the convention of types for their error cases:

type Extension {
  code: Int!
  path: String!
}
type ErrorLocation {
  line: Int!
  column: Int!
}
type GraphQLError {
  message: String!
  locations: [ErrorLocation!]!
  extensions: [Extension!]
}

• leveraging a local schema could allow fragments to be created and validated against a schema. the type generated by the fragment could be used as a type between actors in sextant.

If anyone has thoughts about what would be cool or helpful with this, please comment. I'm going to play with this.