Make dev docs

dev/docs/.gitignore

@@ -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

dev/docs/README.md

@@ -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).

dev/docs/astro.config.mjs

@@ -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" },
+        },
+      ],
+    }),
+  ],
+});

dev/docs/package.json

@@ -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"
+  }
+}

dev/docs/src/content/config.ts

@@ -0,0 +1,6 @@
+import { defineCollection } from "astro:content";
+import { docsSchema } from "@astrojs/starlight/schema";
+
+export const collections = {
+  docs: defineCollection({ schema: docsSchema() }),
+};

dev/docs/src/content/docs/design/Extensions/draft.md

@@ -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);
+});
+```

dev/docs/src/content/docs/design/Extensions/installation.md

@@ -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.

dev/docs/src/content/docs/design/Extensions/manifest.md

@@ -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"]
+  }
+}
+```