⚠️ This set of documentation may not be reflective of the current beta version and some things may break. Documentation will be revamped upon release, but for now reference your IDE's intellisense and JSDoc hints.

Documentation

Client

Constructor

new Client(options)

Parameters:

options: the configuration options for the client.
- token: string: the token to use for authentication.
- replId: string: the replId to use for the client.
- [ignore]: string: a gitignore file to enfore when recursing a Repl's directory.
- [fetchGovalMetadata]: (signal, { replId, token, firewalled }) => Promise<: a low-level handler to replace crosis4furrets method of fetching Goval Metadata Tokens
- [streams]: the streams to use for the client.
  - [stdin]: fs.ReadStream: the stdin stream for the client.
  - [stdout]: fs.WriteStream: the stdout stream for the client.
  - [stderr]: fs.WriteStream: the stderr stream for the client.

Example:

import fs from 'node:fs';
import { Client } from 'crosis4furrets';

const ignorefile = await fs.readFile('local.gitignore');

const streams = {
  stdin: process.stdin,
  stdout: fs.createWriteStream('output.txt', { flags: 'a' }),
  stderr: fs.createWriteStream('error.txt', { flags: 'a' }),
};

const fetchGovalMetadata = (signal, { token, replId, firewalled }) => {
  // Mint a Goval Metadata Token and return it.
  // You likely will not need to specify this
  // function and crosis4furrets built-in
  // handler will suffice.

  // Presuming you have a Goval Metadata Token
  // stored in your Secrets.
  return JSON.parse(process.env.GOVAL_METADATA);
};

const client = new Client({
  streams,
  fetchGovalMetadata,
  ignore: ignorefile,
  token: process.env.REPLIT_TOKEN,
  replId: process.env.REPLIT_REPL_ID,
});

Methods

Connection

.connect()

Open a connection to a remote Repl instance. You must perform this before any actions are taken via the Client.

await client.connect();

If you want to connect to a repl in firewalled mode, you can pass true to the function.

await client.connect(true);

.persist()

Persist any file-changes on the remote Replit. Useful if you are interacting with a Replit with the intentional of keeping changes.

await client.persist();

const success = await client.persist();
if (success) console.log('Persisting files on the remote Repl.');

.close()

Close a connection to a remote Repl. This must be done to exit the process and perform cleanups.

client.close();

Configuration

.dotEnv()

Read a Repl's Secrets via the .env file.

const dotenv = await client.dotEnv();
console.log(dotenv);

.updateDotEnv()

Update a Repl's Secrets via an object of secrets.

const dotenv = await client.updateDotEnv({ MY_API_KEY: 'SECRET_VALUE' });
console.log(dotenv);

.dotReplit()

Read a Repl's DotReplit configuration via the .replit file.

const dotreplit = await client.dotReplit();
console.log(dotreplit);

.updateDotReplit()

Update a Repl's DotReplit configuration via an array of DotReplitOps.

const dotreplit = await client.updateDotReplit([
	{ op: 'add', path: 'run', value: 'node index.js' },
	{ op: 'add', path: 'entrypoint', value: 'index.js' },
	{ op: 'remove', path: 'interpreter' },
]);
console.log(dotreplit);

.gitignore()

Read a Repl's Gitignore configuration via the .gitignore file.

const gitignore = await client.gitignore();
console.log(gitignore);

File Operations

.read()

Read a file from a remote Repl based on path. Specify an encoding for the file or recieve a buffer of the file.

const file = await client.read('index.js');
console.log(file);

const file = await client.read('index.js', 'utf8');
console.log(file);

.readdir()

Read a directory (flat) from a remote Repl and return filepaths based on entrypoint. Specify raw to get protocol File types (used for {@link Client#recursedir}) otherwise get a string array.

const paths = await client.readdir('.');
console.log(paths);

const files = await client.readdir('.', true);
console.log(files);

.recursedir()

Read a directory (recursive) from a remote Repl and return filepaths based on entrypoint. Specify withIgnore to respect .gitignore rules.

const paths = await client.recursedir('.');
console.log(paths);

const paths = await client.recursedir('.', false);
console.log(paths);

.write()

Write to a file on a remote Repl.

await client.write('foo.txt', 'bar');

const buffer = await fs.readFile('image.png');
await client.write('foo.png', buffer);

const success = await client.write('foo.txt', 'bar');
if (success) console.log('Wrote to a file in a remote Repl.');

.mkdir()

Make a directory on a remote Repl.

await client.mkdir('foo');

const success = await client.mkdir('foo');
if (success) console.log('Made a directory in a remote Repl.');

.remove()

Remove a file or directory on a remote Repl.

await client.remove('foo');

const success = await client.remove('foo');
if (success) console.log('Removed a resource from a remote Repl.');

.removeAll()

Remove all files in a remote Repl.

await client.removeAll();

const success = await client.removeAll('foo');
if (success) console.log('Emptied a remote Repl.');

.move()

Move a resources from one location to another in a remote Repl.

await client.move('foo.txt', 'foo/foo.txt');

const success = client.move('foo.txt', 'foo/foo.txt');
if (success) console.log('Moved a file in a remote Repl.');

.stat()

Get information on a file in a remote Repl.

const stat = await client.stat('foo.txt');
console.log(stat);

.snapshot()

Take a filesystem snapshot. Used to persist files in a Repl that doesn't use Client#persist() after opening a connection.

await client.snapshot();

const success = await client.snapshot();
if (success) console.log('Took a FS Snapshot in a remote Repl.');

Packager (via UPM)

.packageInstall()

Install all Packages in a remote Repl.

await client.packageInstall();

await client.packageInstall(true);

const success = await client.packageInstall();
if (success) console.log('Installed all packages in a remote Repl.');

.packageAdd()

Add a Package to a remote Repl.

await client.packageAdd(['chalk']);

await client.packageAdd(['chalk'], true);

const success = await client.packageAdd(['chalk']);
if (success) console.log('Added a package to a remote Repl.');

.packageRemove()

Remove a Package from a remote Repl.

await client.packageRemove(['chalk']);

await client.packageRemove(['chalk'], true);

const success = await client.packageRemove(['chalk']);
if (success) console.log('Removed a package from a remote Repl.');

.packageList()

List all installed Nix packages in a remote Repl.

const packages = await client.packageList();
console.log(packages);

const packages = await client.packageList(true);
console.log(packages);

.packageSearch()

Search for new Packages to add.

const packages = await client.packageSearch('react');
console.log(packages);

const packages = await client.packageSearch('react', true);
console.log(packages);

.packageInfo()

Get information on a Package.

const package = await client.packageInfo('chalk');
console.log(package);

Nix Packager

.nixPackageAdd()

Add a Nix package to a remote Repl.

await client.nixPackageAdd(['nodejs-16_x']);

await client.nixPackageAdd(['nodejs-16_x'], true);

const success = await client.nixPackageAdd(['nodejs-16_x']);
if (success) console.log('Added a package to a remote Repl.');

.nixPackageRemove()

Remove a Nix package from a remote Repl.

await client.nixPackageRemove(['nodejs-16_x']);

await client.nixPackageRemove(['nodejs-16_x'], true);

const success = await client.nixPackageRemove(['nodejs-16_x']);
if (success) console.log('Removed a package from a remote Repl.');

.nixPackageList()

List all installed Nix packages in a remote Repl.

const nixPackages = await client.nixPackageList();
console.log(nixPackages);

const nixPackages = await client.nixPackageList(true);
console.log(nixPackages);

.nixPackageSearch()

Search for new Nix packages to add.

const nixPackages = await client.nixPackageSearch('nodejs');
console.log(nixPackages);

const nixPackages = await client.nixPackageSearch('nodejs', true);
console.log(nixPackages);

.nixChannels()

Get available Nix Channels that a Repl can use.

const nixChannels = await client.nixChannels();
console.log(nixChannels);

.nixChannelLatest()

Get the latest available Nix Channel that a Repl can use.

const latestNixChannel = await client.nixChannelsLatest();
console.log(latestNixChannels);

Runner

.shellRun()

Execute the current Run command in a remote Repl and return a Promise with the contents after running the command.

const data = await client.shellRun();
console.log(data)

await client.shellRun(10000)
  .catch((error) => console.error(error));

.shellRunStream()

Execute the current Run command in a remote Repl and stream its contents to/from the specified input/output/error streams.

await client.shellRunStream();

const success = await client.shellRunStream();
console.log(success);

await client.shellRun(10000)
  .catch((error) => console.error(error));

.shellExec()

Execute a command in a remote Repl and return a Promise with the contents after running the command.

const data = await client.shellExec('ls -lha');
console.log(data)

await client.shellExec('ls -lha', 10000)
  .catch((error) => console.error(error));

.shellExecStream()

Execute a command in a remote Repl and stream its contents to/from the specified input/output/error streams.

await client.shellExecStream('ls -lha');

const success = await client.shellExecStream('ls -lha');
console.log(success);

await client.shellExecStream('ls -lha', 10000)
  .catch((error) => console.error(error));

.shellStop()

Stop a remote Repl's current Run command.

await client.shellStop();

const replShell = await client.shellStop();
replShell.log('[PROCESS]: Stopped remote Repl from running.');

Editor

.lspMessage()

Send a message to the underlying LSP server. Messages must follow the Language Server Protocol JSONRPC Specification.

const success = await client.lspMessage(
	JSON.stringify({
		jsonrpc: '2.0',
		id: 1,
		method: 'textDocument/definition',
		params: {
			textDocument: {
				uri: path.resolve(process.cwd(), 'src/index.js'),
			},
			position: {
				line: 3,
				character: 12,
			},
		},
	}),
);

if (success) console.log('Sent a LSP message to the remote Repl.');

.lspStart()

Start a language's LSP server based on keys in the .replit configuration.

await client.lspStart('javascript');

const success = await client.lspStart('javascript');
if (success)
	console.log(
		'Started the Javascript language server on the remote Repl.',
	);

Files

DOCUMENTATION.md

Latest commit

History