Add Bruno imports and a file-tree importer API (#706)

This commit is contained in:
Gregory Schier authored and GitHub committed 2026-09-24 14:50:44 -07:00
1 parent 46464cfacf
commit aa10c44a45
109 files changed
+4684 -879

No files matched your search

@@ -0,0 +1,40 @@
# Importers
Implement **`onImportSource(ctx, { source })`**. The source is one of two things:
- `{ type: "text", name, text }`: a single UTF-8 document, or pasted text (named `input`).
- `{ type: "directory", files }`: a directory or a ZIP archive, read as one file tree.
Return `null` or `undefined` when the source isn't your format. Only one importer's result is used per source.
```ts
import type { PluginDefinition } from "@yaakapp/api";
export const plugin: PluginDefinition = {
importer: {
name: "Example",
async onImportSource(ctx, { source }) {
if (source.type === "text") return convertDocument(source.text);
for (const entry of await source.files.readDir()) {
if (entry.name === "example.json") {
return convertDocument(await source.files.readTextFile(entry.path));
}
}
return null;
},
},
};
```
The older `onImport(ctx, { text })` hook still works but is deprecated. It only receives single text documents and is ignored when `onImportSource` is defined.
## The file tree
- `files.kind` is `"directory"` or `"zip"`; `files.name` is the selected basename.
- `readDir(path = "")` lists immediate children. `readFile(path)` returns bytes. `readTextFile(path)` decodes UTF-8 strictly.
- Paths use `/` and are relative to the root. Absolute paths, `..`, and backslashes are rejected. Symbolic links are skipped in listings and rejected on read. Nothing is extracted to disk.
- ZIPs are detected by signature, not extension. A ZIP made by compressing a folder is rooted at that folder, so plugins see the same tree as for the directory. Directory reads are not a snapshot: a symlink swapped in under a validated path can redirect a read outside the root, so treat directory imports as trusted input.
- Limits: 64 MiB per source file or download, 32 MiB per file read, 10,000 entries, 256 MiB declared ZIP expansion. Encrypted ZIPs are unsupported.
- The tree is read-only and only valid until the hook settles.
Plugins run with the normal Node.js permissions of the plugin runtime; the tree scopes convenience, not security.
+10 -1
View File
@@ -470,7 +470,16 @@ export type HttpRequestAction = { label: string, icon?: Icon, };
export type Icon = "alert_triangle" | "check" | "check_circle" | "chevron_down" | "copy" | "info" | "pin" | "search" | "trash" | "_unknown";
export type ImportRequest = { content: string, };
/**
* Transport descriptor; plugins see a scoped ImportFiles API, not this representation.
*/
export type ImportFileSource = { "type": "file", name: string, base64: string, } | { "type": "directory", path: string, };
export type ImportRequest = {
/**
* Kept for text-only importers and older runtimes.
*/
content: string, source?: ImportFileSource, };
export type ImportResources = { workspaces: Array<Workspace>, environments: Array<Environment>, folders: Array<Folder>, httpRequests: Array<HttpRequest>, grpcRequests: Array<GrpcRequest>, websocketRequests: Array<WebsocketRequest>, };
+7 -1
View File
@@ -6,4 +6,10 @@ export * from "./bindings/gen_events";
// Some extras for utility
export type { PartialImportResources } from "./plugins/ImporterPlugin";
export type {
PartialImportResources,
ImportFiles,
ImportFileEntry,
ImportSource,
ImportSourceHandler,
} from "./plugins/ImporterPlugin";
@@ -21,11 +21,45 @@ export type ImportPluginResponse =
resources: PartialImportResources;
});
/** A read-only view of a selected directory or ZIP archive. Paths are relative and use
* forward slashes. Directory path checks are best-effort under concurrent filesystem
* changes, not a security boundary. Valid only while onImportSource runs. */
export interface ImportFiles {
readonly name: string;
readonly kind: "zip" | "directory";
/** List immediate children. The root directory is "" (the default). */
readDir(path?: string): Promise<ImportFileEntry[]>;
readFile(path: string): Promise<Uint8Array>;
/** Decode UTF-8 strictly; binary or invalid UTF-8 content throws. */
readTextFile(path: string): Promise<string>;
}
export interface ImportFileEntry {
name: string;
path: string;
type: "file" | "directory";
}
/** What the user chose to import: one text document, or a directory or ZIP read as a tree. */
export type ImportSource =
| { type: "text"; name: string; text: string }
| { type: "directory"; files: ImportFiles };
type ImportTextHandler = (
ctx: Context,
args: { text: string },
) => MaybePromise<ImportPluginResponse | undefined>;
export type ImportSourceHandler = (
ctx: Context,
args: { source: ImportSource },
) => MaybePromise<ImportPluginResponse | undefined>;
export type ImporterPlugin = {
name: string;
description?: string;
onImport(
ctx: Context,
args: { text: string },
): MaybePromise<ImportPluginResponse | null | undefined>;
/** Return null when the source isn't this importer's format. Takes precedence over onImport. */
onImportSource?: ImportSourceHandler;
/** @deprecated Use onImportSource. Only receives single text documents. */
onImport?: ImportTextHandler;
};