mirror of
https://github.com/mountain-loop/yaak.git
synced 2026-11-22 00:11:56 +01:00
Add Bruno imports and a file-tree importer API (#706)
This commit is contained in:
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
@@ -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>, };
|
||||
|
||||
|
||||
@@ -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;
|
||||
};
|
||||
Reference in new issue
Block a user