Skip to content

Commit

Permalink
Make dev docs
Browse files Browse the repository at this point in the history
  • Loading branch information
HuakunShen committed May 16, 2024
1 parent 0e6a7db commit 59eb19b
Show file tree
Hide file tree
Showing 31 changed files with 885 additions and 0 deletions.
21 changes: 21 additions & 0 deletions dev/docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# build output
dist/
# generated types
.astro/

# dependencies
node_modules/

# logs
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*


# environment variables
.env
.env.production

# macOS-specific files
.DS_Store
54 changes: 54 additions & 0 deletions dev/docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Starlight Starter Kit: Basics

[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)

```
npm create astro@latest -- --template starlight
```

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics)
[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/basics)
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwithastro%2Fstarlight%2Ftree%2Fmain%2Fexamples%2Fbasics&project-name=my-starlight-docs&repository-name=my-starlight-docs)

> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
## 🚀 Project Structure

Inside of your Astro + Starlight project, you'll see the following folders and files:

```
.
├── public/
├── src/
│ ├── assets/
│ ├── content/
│ │ ├── docs/
│ │ └── config.ts
│ └── env.d.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json
```

Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.

Images can be added to `src/assets/` and embedded in Markdown with a relative link.

Static assets, like favicons, can be placed in the `public/` directory.

## 🧞 Commands

All commands are run from the root of the project, from a terminal:

| Command | Action |
| :------------------------ | :----------------------------------------------- |
| `npm install` | Installs dependencies |
| `npm run dev` | Starts local dev server at `localhost:4321` |
| `npm run build` | Build your production site to `./dist/` |
| `npm run preview` | Preview your build locally, before deploying |
| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` |
| `npm run astro -- --help` | Get help using the Astro CLI |

## 👀 Want to learn more?

Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).
39 changes: 39 additions & 0 deletions dev/docs/astro.config.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";

// https://astro.build/config
export default defineConfig({
integrations: [
starlight({
title: "Jarvis",
social: {
github: "https://github.com/withastro/starlight",
},
sidebar: [
{
label: "Guides",
items: [
// Each item here is one entry in the navigation menu.
{ label: "Example Guide", link: "/guides/example/" },
],
},
{
label: "Reference",
autogenerate: { directory: "reference" },
},
{
label: "Design",
autogenerate: { directory: "design" },
},
{
label: "Development",
autogenerate: { directory: "development" },
},
{
label: "Extensions",
autogenerate: { directory: "extensions" },
},
],
}),
],
});
19 changes: 19 additions & 0 deletions dev/docs/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
{
"name": "docs",
"type": "module",
"version": "0.0.1",
"scripts": {
"dev": "astro dev",
"start": "astro dev",
"build": "astro check && astro build",
"preview": "astro preview",
"astro": "astro"
},
"dependencies": {
"@astrojs/starlight": "^0.22.2",
"astro": "^4.3.5",
"sharp": "^0.32.5",
"@astrojs/check": "^0.6.0",
"typescript": "^5.4.5"
}
}
1 change: 1 addition & 0 deletions dev/docs/public/favicon.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added dev/docs/src/assets/houston.webp
Binary file not shown.
6 changes: 6 additions & 0 deletions dev/docs/src/content/config.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
import { defineCollection } from "astro:content";
import { docsSchema } from "@astrojs/starlight/schema";

export const collections = {
docs: defineCollection({ schema: docsSchema() }),
};
96 changes: 96 additions & 0 deletions dev/docs/src/content/docs/design/Extensions/draft.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
---
title: Draft
description: Draft
---

How to run extension JavaScript code with `bun` or `node`? Sometimes extension can be simple and don't need a UI.

For example, a extension that runs file filter to find a file and open it with a specific editor.

## Option 1: Run with `bun`

Include `bun` as a sidecar.

In a extension, let's say keyword `code` should trigger a file filter, find the file and open it with a specific editor.

### Q1: How to trigger the function associated with keyword `code`?

Jarvis runs a `bun` process, load the extension with `const lib = await import(libpath);` and call the function associated with keyword `code`. Lifecycle functions are called automatically.

### How to execute file filter from extension?

Developer can write their own file filter function to scan the file system.

What if Jarvis API provides a file filter function and some other common functions?

Then this has to be some kind of Jarvis API library extension developer can import.

To the lowest level, extension will have to communicate with Jarvis core process to get any data. How to IPC?

- Use a server to communicate with Jarvis core process and any extension can communicate with the server to get data and control the UI or the app.

Procedures

1. When extension loads, register the command keywords like `code` or any other regex
1. Map the keyword to extension so we know which extension to call when the keyword is triggered
2. When keyword triggered, run a bun process from Jarvis core process (rust), and map the pid with active extension. If anything go wrong, such as the process exceeds time limit or memory limit, kill the process.

```bash
# run this command from Jarvis core process in Rust
bun run /path/to/extension/lib/index.ts
```

API-Driven Design: write sample client code first

```ts title="extension/lib/index.js"
import { ExtensionTemplate, FileFilter, open, setListView } from "@jarvis/api";
function customFindFile(filename: string, scope: string, depth: number = 5) {
// ...
}
class OpenEditorExt extends ExtensionTemplate {
constructor() {
super();
}
async onPluginCalled(data) {
const { code, type, payload } = data;
// payload is the query. For example `code {filename query}`
const file = await FileFilter.findFile(payload, scope);
// send request to server, server will find related files, list them, when user select a file from list view, server will send the file path to the client
// Or if developer choose to use custom file filter
const paths = customFindFile(payload, scope, 5);
// send a request to server to update the list view with the paths
setListView(paths);
// client will open the file with a specific editor
open(file, "code"); // send another request to server to open the file with a specific app
}
}
const ext = OpenEditorExt();
ext.start(); //
```
## Option 2: Provide a Extension Runtime
The runtime is a bun process that import extensions code as library and run it.
In Jarvis runtime, run with bun
```ts
// connect to server, e.g. socketio or bidirectinal grpc stream
runtime.connect("http://localhost:1566");
runtime.getExtensionInfo(); // get extension info from server, such as command keywords, etc.
// it's possible to include this code in @jarvis/api and let extension run this client to connect with server
// but if there are many extensions, the client code will be duplicated in each extension (e.g. socketio client lib duplicated many times)
runtime.on("user-input", (data) => {
const userInput: string = data;
const { command, query } = userInput; // in real code, split the command and query, command is the first word (trigger word), query is the rest
const ext = runtime.findExtension(command); // find the extension that has the command
const lib = await import(ext.libpath);
lib.onPluginCalled(query);
});
```
111 changes: 111 additions & 0 deletions dev/docs/src/content/docs/design/Extensions/installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
---
title: Installation
description: Installation of Extensions
---

- [Goal](#goal)
- [Methods](#methods)
- [Extension Store](#extension-store)
- [Remote Tarball URL](#remote-tarball-url)
- [NPM](#npm)
- [Manual](#manual)
- [Development Mode (Live Reload)](#development-mode-live-reload)
- [Multi-Platform](#multi-platform)

## Goal

The goal is to make it easy to install extensions in Jarvis

- Not only easy for developers but also for regular users
- Make is easy for developers to test their extensions locally

## Methods

Multiple methods are available to install extensions in Jarvis.

### Extension Store

An extension store is provided just like Raycast's Store https://www.raycast.com/store.

Alfred has a Alfred Gallery https://alfred.app/ where users can download workflows.

uTools and Rubick have built-in store like Apple's app store. uTools displays the number of downloads, rating, package size, review and more.

The ultimate goal is to have a store like uTools.

### Remote Tarball URL

Provide a URL to the tarball `.tgz` file of the extension. It can be hosted on any server, such as asset in a GitHub release, or NPM package.

- e.g. https://registry.npmjs.org/nest-neo4j/-/nest-neo4j-0.3.1.tgz

> TODO: Add real extension example here when I get one ready
### NPM

NPM is one of the most successful package manager in the world. It is used by millions of developers to share their code.

It makes sense to use it to share Jarvis extensions.

However, I don't want to use `npm` command to install extensions, as that will requires end users to have `npm` installed on their system, or Jarvis to have a `npm` binary embedded. Moreover, this will download the development dependencies of the extension.

NPM's API `https://registry.npmjs.org/{package-name}/{version}` provides a link to the tarball `.tgz` file of the package. This is what we will use to download the extension. We can set `version` to latest to get the latest version of the package.

So user can enter the follwing info to Jarvis to let Jarvis download and install automatically

- `npm` url of the package
- e.g. without version (default to use latest) https://www.npmjs.com/package/nest-neo4j
- e.g. with version https://www.npmjs.com/package/nest-neo4j/v/0.3.1
- NPM API URL
- e.g. https://registry.npmjs.org/nest-neo4j/latest
- e.g. https://registry.npmjs.org/nest-neo4j/0.3.1
- `npm` package name and version (version will default to `latest` if not provided)

> TODO: Use a real extension example here rather than `nest-neo4j`
### Manual

The simplest way to install an extension is to download the extension and place it in the `extensions` directory of Jarvis.

Jarvis provides tool to validate the extension and will load it automatically.

This could be used for local development. Developers can package their extension and load it to Jarvis by providing a path to project or place in the `extensions` directory. (When placed in `extensions` directory, Jarvis will display it as a production extension and not list it under development extensions)

#### Development Mode (Live Reload)

In `package.json`, provide the `jarvis.development.ui` field with the URL of the development server (e.g. `http://localhost:3000`). Load the project as a development extension, Jarvis will load the extension UI from the URL.

## Multi-Platform

Jarvis allows extensions to include binaries to enable higher performance or native features.

However, to support multiple platforms and CPU architectures, the extension must provide binaries for each platform, which could result in a large package size.

To solve this, Jarvis extension store will provide a way to publish platform-specific packages. Jarvis will download the package based on the platform it is running on.

For example, the request could have this format

```json
{
"name": "demo",
"version": "1.0.0",
"description": "Demo Extension",
"author": "Jarvis",
"dist": {
"linux": {
"x86_64": "https://jarvis.com/demo-linux-x86_64.tgz",
"arm64": "https://jarvis.com/demo-linux-arm64.tgz"
},
"darwin": {
"x86_64": "https://jarvis.com/demo-darwin-x86_64.tgz",
"arm64": "https://jarvis.com/demo-darwin-arm64.tgz"
},
"win32": {
"x86_64": "https://jarvis.com/demo-win32-x86_64.tgz",
"arm64": "https://jarvis.com/demo-win32-arm64.tgz"
}
}
}
```

If `dist` is a single URL, Jarvis assumes there is no platform-specific code in the extension.
38 changes: 38 additions & 0 deletions dev/docs/src/content/docs/design/Extensions/manifest.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
title: Sample Manifest (`package.json`)
description: A guide in my new Starlight docs site.
---

## Sample Manifest (`package.json`)

```json
{
"name": "some-extensions",
"version": "1.0.0",
"description": "An extension for Jarvis",
"jarvis": {
"identifier": "video-processing.huakun.tech",
"ui": "dist",
"platforms": ["linux", "darwin", "win32"]
}
}
```

## Development Mode

To develop an extension with live reload, Jarvis can load your extension pages with an url.

For example, set `ui` to `http://localhost:3000` in `package.json`.

```json
{
"name": "some-extensions",
"version": "1.0.0",
"description": "An extension for Jarvis",
"jarvis": {
"identifier": "video-processing.huakun.tech",
"ui": "http://localhost:3000",
"platforms": ["linux", "darwin", "win32"]
}
}
```
Loading

0 comments on commit 59eb19b

Please sign in to comment.