superuser.app 0.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Keith William Horwood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,296 @@
+# Superuser Package Manager
+## Extend AI agents with tools, instantly
+
+`ibot` is the official CLI for publishing [Superuser](https://instant.chat) packages.
+You can use this utility to publish new packages to the Superuser package registry,
+available at [instant.chat/packages](https://instant.chat/packages).
+
+[Superuser](https://instant.chat) enables you to rapidly build custom
+chatbots and AI agents that can be extended with custom tools. It provides four
+major features;
+
+1. Chat with and develop your agent in real time from the web
+2. Extend your agent with [hosted tool packages](https://instant.chat/packages)
+3. Write your own private tool packages for your agents
+4. Deploy your agent to third-party services like Discord and Slack
+
+## What is the Superuser Package Registry?
+
+The Superuser Package Registry is a **serverless hosting platform and registry** for
+building tools that extend AI chatbots and agents.
+
+**Superuser packages are just REST API servers.**
+Every package is an [Instant API](https://github.com/instant-dev/api) project,
+which is a simple way to export and auto-document JavaScript functions as REST endpoints
+that can be called via any HTTP client.
+
+Authentication to your published packages are handled via **API keychains** which
+are delegated via [Superuser](https://instant.chat).
+
+**NOTE:** While in beta, only Superuser agents can use your published tools.
+We'll be opening up the gateway to programmatic access in the coming months.
+
+## Superuser Package vs. MCP
+
+Reminder, **Superuser packages are just REST API servers.**
+
+MCP, or Model Context Protocol, is a standard for passing tool and prompt context
+between AI models and service providers. Superuser packages are **not**
+MCP compatible out of the box, as they are simply REST APIs. However, it is our goal to add
+MCP bindings to the [Instant API](https://github.com/instant-dev/api) framework which
+powers all Superuser packages. When formalized, this will allow you to use
+Superuser packages with any MCP-compatible client or service provider.
+Contributors welcome!
+
+## Quickstart
+
+Visit [instant.chat/signup](https://instant.chat/signup) to register.
+Creating a new bot is easy, you can then use this CLI to develop
+and publish custom packages to extend your bots.
+
+```shell
+$ npm i ibot -g
+$ mkdir new-project
+$ cd new-project
+$ ibot init  # initialize project in this directory
+$ ibot login # log in to Superuser Package Registry with your Superuser account
+$ ibot serve # run your tool package on a local server to test
+$ ibot run / # test a single endpoint (like curl)
+$ ibot up    # publish to development environment
+$ ibot up --env staging    # publish to staging environment
+$ ibot up --env production # publish to production environment
+```
+
+You can run `ibot help` at any time to see available commands.
+
+# Table of contents
+
+1. [How does Superuser work?](#how-does-instant-bot-work)
+   1. [How is hosting billed?](#how-is-hosting-billed)
+1. [Building custom packages for your bots](#building-custom-packages-for-your-bots)
+   1. [Initialize a project](#initialize-a-project)
+      1. [Defining tools aka endpoints](#defining-tools-aka-endpoints)
+      1. [Endpoint name, description, types](#endpoint-name-description-types)
+   1. [Deploy an Superuser Package](#deploy-an-instant-tool-package)
+      1. [Public packages](#public-packages)
+      1. [Private packages](#private-packages)
+1. [Additional utilities](#additional-utilities)
+   1. [Generate endpoints](#generate-endpoints)
+   1. [Generate tests](#generate-tests)
+   1. [Run tests](#run-tests)
+   1. [Environment variables](#environment-variables)
+1. [Roadmap](#roadmap)
+1. [Contact](#contact)
+
+# How does Superuser work?
+
+Superuser provides hosting for both (1) your agent and (2) your tool packages.
+Your agent is a chatbot that you can chat with directly via the Superuser web interface.
+Tool packages are REST APIs that can be used by your agent. You can publish tool packages
+for use by your agent and others or keep them private.
+
+When you ask your agent a question that requires a tool call, Superuser will
+automatically route the request to the appropriate tool from the Superuser Package Registry
+and call the tool on your behalf.
+
+## How is hosting billed?
+
+Model usage (generating responses) is a subscription-based service. However,
+for development purposes, you can use our lowest-tier model indefinitely in rate-limited mode
+on the free tier **but only while on the web interface**.
+
+Tools cost money to run, and are billed as serverless functions
+at a rate of [$0.50 of credits per 1,000 GB-s](https://instant.chat/pricing) of usage.
+Credits are prepaid, and during our beta period all users get a one-time bonus of $1.00
+in free usage credits.
+
+GB-s represents a "gigabyte-second" and is calculated by the function RAM × execution time.
+For example, a function with 512 MB (0.5 GB) of RAM running for 200ms would use:
+
+- Used GB-s = 0.5GB × 0.2s = 0.1 GB-s
+- Used credits = $0.50 / 1,000 GB-s × 0.1 GB-s = $0.00005
+
+# Building custom packages for your bots
+
+Building bots on [Superuser](https://instant.chat) is straightforward. Extending
+with custom tool packages can be done online via the web interface, or if you prefer
+working with your own editor, you can use this CLI.
+
+## Initialize a project
+
+To initialize a new Superuser package:
+
+```shell
+$ npm i ibot -g
+$ mkdir new-project
+$ cd new-project
+$ ibot init
+```
+
+You'll be walked through the process. The `ibot` CLI will automatically check for
+updates to core packages, so make sure you update when available. To play around with your
+Superuser package locally;
+
+```shell
+$ ibot serve
+```
+
+Will start an HTTP server. To execute a standalone endpoint / tool:
+
+```shell
+$ ibot run /
+```
+
+### Defining tools aka endpoints
+
+Defining custom tools is easy. You'll find the terms **tool** and
+**endpoint** used interchangeably as they all refer
+to the same thing: your bot executing custom code in the cloud.
+
+A **tool** is just an **endpoint** hosted by the Superuser Package Registry.
+
+All endpoints for Superuser packages live in the `functions/` directory.
+Each file name maps to the endpoint route e.g. `functions/hello.js`
+routes to `localhost:8000/hello`. You can export custom `GET`, `POST`, `PUT`
+and `DELETE` functions from every file. Here's an example "hello world" endpoint:
+
+```javascript
+// functions/hello.js
+
+/**
+ * A basic hello world function
+ * @param {string} name Your name
+ * @returns {string} message The return message
+ */
+export async function GET (name = 'world') {
+  return `hello ${name}`!
+};
+```
+
+You can write any code you want and install any NPM packages you'd like to
+your tool package.
+
+### Endpoint name, description, types
+
+Using the comment block above every exported method (e.g. GET) you can
+define your endpoint. Superuser packages use an open source specification called
+[Instant API](https://github.com/instant-dev/api) to export JavaScript
+functions as type safe web APIs. You can learn more about how to properly
+define and document the shape (parameters) of your API there.
+
+## Deploy an Superuser Package
+
+### Public packages
+
+**NOTE:** You **will not** be charged for other people using your public actions.
+They are billed directly from their account.
+
+By default all packages are created as public projects. Public
+projects are namespaced to your username, e.g. `@my-username/project`.
+This can be found in the `"name"` field of `superuser.json`.
+
+Note that the code for public projects will be shared publicly for anybody
+to see, and the expectation is that others can use this code in their bots
+as well.
+they will be billed from their balance.
+
+To deploy a public project to a `development` environment, you can use:
+
+```shell
+$ ibot up
+```
+
+You can also publish to `staging` and `production` using:
+
+```shell
+$ ibot up --env staging
+$ ibot up --env production
+```
+
+### Private packages
+
+**NOTE:** You **_WILL_** be charged by anybody accessing your private
+packages. However, all code and endpoints will not be publicly available;
+you must share the URL with somebody in order for them to use it.
+
+You can publish private project by prepending `private/` on the
+`"name"` field in `superuser.json`, e.g.
+
+```json
+{
+  "name": "private/@my-username/private-package"
+}
+```
+
+You then deploy as normal. These packages will be visible by you in the
+registry but nobody else.
+
+# Additional utilities
+
+There are a few additional utilities you may find useful with this package;
+
+## Generate endpoints
+
+```shell
+# generates functions/my-endpoint/example.js
+$ ibot g:endpoint my-endpoint/example
+```
+
+## Generate tests
+
+```shell
+# Generate blank tests or ones for an endpoint
+$ ibot g:test my_test # OR ...
+$ ibot g:test --endpoint my-endpoint/example
+```
+
+## Run tests
+
+You can write tests for your tools to verify they work. Simply run;
+
+```shell
+$ ibot test
+```
+
+And voila!
+
+## Environment variables
+
+You can store environment variables with your packages in;
+
+```
+.env
+.env.production
+.env.staging
+```
+
+These files **will not** be published for everybody to see, so
+you can use them to hide secrets within your code. However, be
+careful when using environment variables with public packages:
+if you ever return them in an endpoint response, or connect to
+sensitive data, there's a chance you may expose that information
+to another user of the platform.
+
+# Roadmap
+
+There's a lot to build! [Superuser](https://instant.chat) is still in early beta. Coming soon;
+
+- Deploy to Slack
+- Uploading image support
+- Knowledge bases
+- Much more!
+
+Submit requests via Discord at [discord.gg/instant](https://discord.gg/instant)!
+
+# Contact
+
+The best place for help and support is Discord at [discord.gg/instant](https://discord.gg/instant),
+but feel free to bookmark all of these links.
+
+| Destination | Link |
+| ----------- | ---- |
+| Superuser | [instant.chat](https://instant.chat) |
+| GitHub | [github.com/instantbots](https://github.com/instantbots) |
+| Discord | [discord.gg/instant](https://discord.gg/instant) |
+| X / instantbots | [x.com/instantbots](https://x.com/instantbots) |
+| X / Keith Horwood | [x.com/keithwhor](https://x.com/keithwhor) |

package/commands/domains/add.js

@@ -0,0 +1,102 @@
+const { Command } = require('cmnd');
+const io = require('io');
+const colors = require('colors/safe');
+const inquirer = require('inquirer');
+
+const constants = require('../../helpers/constants.js');
+const SettingsManager = require('../../helpers/settings_manager.js');
+
+class DomainsAddCommand extends Command {
+
+  constructor() {
+    super('domains', 'add');
+  }
+
+  help () {
+    return {
+      description: 'Add a custom domain to a package',
+      args: [],
+      flags: {},
+      vflags: {}
+    };
+  }
+
+  async run (params) {
+
+    const settings = SettingsManager.read(true);
+    const host = settings.activeProfile.host || constants.BASE_URL;
+
+    let addResult = await inquirer.prompt([
+      {
+        name: 'hostname',
+        type: 'input',
+        message: `Hostname`,
+        validate: e => {
+          if (!e.match(/^([a-z0-9\-]+.)+[a-z0-9\-]+$/gi)) {
+            return 'Must be a valid hostname'
+          } else {
+            return true;
+          }
+        }
+      },
+      {
+        name: 'name',
+        type: 'input',
+        message: `Package name`,
+        validate: v => {
+          if (
+            v.match(/@[a-z][a-z0-9\-]*[a-z0-9]\/[a-z][a-z0-9\-]*[a-z0-9]/i) &&
+            v.indexOf('--') === -1
+          ) {
+            return true;
+          } else {
+            return 'must be a valid package name in format "@org/package"';
+          }
+        }
+      },
+      {
+        name: 'environment',
+        type: 'list',
+        message: 'Environment',
+        choices: [
+          'development',
+          'staging',
+          'production'
+        ]
+      }
+    ]);
+
+    const postParams = {...addResult};
+
+    const result = await io.post(
+      `${host}/v1/custom_domains`,
+      settings.activeProfile.key,
+      null,
+      postParams
+    );
+
+    if (result.statusCode !== 200) {
+      const message = result.data?.error?.message || `Invalid statusCode: ${result.statusCode}`;
+      throw new Error(message);
+    }
+
+    const customDomain = result.data;
+    const packageName = `@${customDomain.package.organization.name}/${customDomain.package.name}`;
+    const environment = customDomain.environment;
+
+    console.log();
+    console.log(`${colors.bold.green('Success!')} Custom domain created.`);
+    console.log(`${colors.bold(`hostname`)}:     ${customDomain.hostname}`);
+    console.log(`${colors.bold(`package`)}:      ${packageName}`);
+    console.log(`${colors.bold(`environment`)}:  ${environment}`);
+    console.log(`${colors.bold(`verified at`)}:  ${customDomain.verified_at || '(unverified)'}`);
+    console.log(`${colors.bold(`created`)}:      ${customDomain.created_at}`);
+    console.log();
+
+    return void 0;
+
+  }
+
+}
+
+module.exports = DomainsAddCommand;

package/commands/domains/list.js

@@ -0,0 +1,71 @@
+const { Command } = require('cmnd');
+const io = require('io');
+const colors = require('colors/safe');
+
+const constants = require('../../helpers/constants.js');
+const SettingsManager = require('../../helpers/settings_manager.js');
+const DrawTable = require('../../helpers/draw_table.js');
+
+class DomainsListCommand extends Command {
+
+  constructor() {
+    super('domains', 'list');
+  }
+
+  help () {
+    return {
+      description: 'List all custom domains',
+      args: [],
+      flags: {},
+      vflags: {}
+    };
+  }
+
+  async run (params) {
+
+    const settings = SettingsManager.read(true);
+    const host = settings.activeProfile.host || constants.BASE_URL;
+
+    const result = await io.get(
+      `${host}/v1/custom_domains`,
+      settings.activeProfile.key,
+      null,
+      {invalidated: false},
+    );
+
+    if (result.statusCode !== 200) {
+      const message = result.data?.error?.message || `Invalid statusCode: ${result.statusCode}`;
+      throw new Error(message);
+    }
+
+    const customDomains = result.data.data;
+
+    const columns = [
+      'hostname',
+      'package',
+      'environment',
+      'verified_at'
+    ];
+
+    const rows = customDomains.map(customDomain => {
+      const packageName = `${customDomain.package.is_private ? `private/` : ``}@${customDomain.package.organization.name}/${customDomain.package.name}`;
+      const environment = customDomain.environment;
+      return {
+        hostname: customDomain.hostname,
+        package: packageName,
+        environment: environment,
+        verified_at: customDomain.verified_at
+      }
+    });
+
+    console.log();
+    DrawTable.render(columns, rows);
+    console.log();
+
+    return void 0;
+
+  }
+
+}
+
+module.exports = DomainsListCommand;

package/commands/domains/remove.js

@@ -0,0 +1,97 @@
+const { Command } = require('cmnd');
+const io = require('io');
+const colors = require('colors/safe');
+const inquirer = require('inquirer');
+
+const constants = require('../../helpers/constants.js');
+const SettingsManager = require('../../helpers/settings_manager.js');
+const DrawTable = require('../../helpers/draw_table.js');
+
+class DomainsRemoveCommand extends Command {
+
+  constructor() {
+    super('domains', 'remove');
+  }
+
+  help () {
+    return {
+      description: 'Remove domains from your packages',
+      args: [],
+      flags: {},
+      vflags: {}
+    };
+  }
+
+  async run (params) {
+
+    const settings = SettingsManager.read(true);
+    const host = settings.activeProfile.host || constants.BASE_URL;
+
+    const result = await io.get(
+      `${host}/v1/custom_domains`,
+      settings.activeProfile.key,
+      null,
+      {invalidated: false}
+    );
+
+    if (result.statusCode !== 200) {
+      const message = result.data?.error?.message || `Invalid statusCode: ${result.statusCode}`;
+      throw new Error(message);
+    }
+
+    const customDomains = result.data.data;
+
+    const columns = [
+      'hostname',
+      'package',
+      'environment',
+      'verified_at'
+    ];
+
+    const rows = customDomains.map(customDomain => {
+      const packageName = `@${customDomain.package.organization.name}/${customDomain.package.name}`;
+      const environment = customDomain.environment;
+      return {
+        hostname: customDomain.hostname,
+        package: packageName,
+        environment: environment,
+        verified_at: customDomain.verified_at
+      }
+    });
+
+    console.log();
+    const index = await DrawTable.selectIndexFromTable('Choose a domain to remove', columns, rows);
+
+    if (index === -1) {
+      console.log();
+      return;
+    }
+    
+    const removeParams = {};
+    removeParams.hostname = rows[index].hostname;
+    removeParams.name = rows[index].package;
+    removeParams.environment = rows[index].environment;
+
+    const removeResult = await io.del(
+      `${host}/v1/custom_domains`,
+      settings.activeProfile.key,
+      null,
+      removeParams
+    );
+
+    if (removeResult.statusCode !== 200) {
+      const message = removeResult.data?.error?.message || `Invalid statusCode: ${removeResult.statusCode}`;
+      throw new Error(message);
+    }
+
+    console.log();
+    console.log(`${colors.bold.green('Success!')} Domain ${colors.bold(removeParams.hostname)} removed.`);
+    console.log();
+
+    return void 0;
+
+  }
+
+}
+
+module.exports = DomainsRemoveCommand;