npm package: @galacean/file-browser
Description: A file browser utility to read and list files from the assets directory
Latest version: 0.0.0-alpha.8

# Galacean File Browser

A utility library for browsing and reading files from the `assets` directory, and for generating a cross‑package source/type index from the Galacean engine submodule.

## Features

- Read files from the assets directory
- List all files in a specific directory
- Supports nested directory structures
- File content caching for better performance
- Path normalization and security checks

## Installation

```bash
npm install @galacean/file-browser
```

## Usage

### Reading Files

```typescript
import { FileReader } from '@galacean/file-browser';

const reader = FileReader.ins;

// Read single or multiple files (paths are relative to assets/)
const contents = await reader.read([
  'galacean.md',
  'docs/engine.md'
]);
console.log(contents);
```

### Listing Files

```typescript
import { FileReader } from '@galacean/file-browser';

const reader = FileReader.ins;

// List all files in a directory
const files = reader.listFiles('docs');
console.log(files);
```

### Get Full Document Path

```typescript
import { FileReader } from '@galacean/file-browser';

const reader = FileReader.ins;

// Get the full path of a document under assets/docs
const fullPath = reader.getFullDocPath('engine.md');
console.log(fullPath);
```

## Directory Structure

The library expects an `assets` directory in your project root. Typical structure:

```
assets/
├── docs/                       # Topic documents (Markdown)
│   ├── doc-directory.md        # Human‑friendly docs index
│   └── tool-index.md           # Generated tool list (from src/tools/**)
├── packages/                   # Copied src/types from submodule packages/*
├── directory/
│   └── code-directory.json     # Generated code index (see below)
│   └── tool-directory.json     # Consolidated tool schema map: { [toolId]: JSONSchema }
└── galacean.md                 # Quick prompt/overview
```

### About code-directory.json

`assets/directory/code-directory.json` is an auto‑generated index (map) with the shape:

```json
{
  "animator": [
    {
      "declare": "./packages/core/types/animation/Animator.d.ts",
      "source": "./packages/core/src/animation/Animator.ts"
    }
  ],
  "spriterenderer": [
    {
      "declare": "./packages/core/types/2d/sprite/SpriteRenderer.d.ts",
      "source": "./packages/core/src/2d/sprite/SpriteRenderer.ts"
    }
  ]
}
```

- Keys are lowercased export names.
- Values are arrays of `{ declare, source }`, each path is relative to `assets/`.

## Submodule and Sync (Pre‑requisites)

This project depends on the Galacean engine as a Git submodule and the ability to build it before generating the code index.

1) Update or initialize submodules

```bash
git submodule update --init --recursive
```

2) Install and build the engine submodule (requires pnpm)

```bash
cd external/galacean-engine
pnpm i
pnpm run b:all
cd -
```

3) Sync packages and generate code index

```bash
npm run sync:engine
```

This will:
- Clean `assets/packages/*`
- Copy `external/galacean-engine/packages/*/{src,types}` into `assets/packages/*/{src,types}`
- Generate `assets/directory/code-directory.json`

## Tools Metadata and Index

The `src/tools/**` folder contains tool definitions. Each tool exports a `meta` object (with `toolId` and `description`) and a `payloadSchema` (zod schema).

You can generate a tools index and the consolidated tool schema map:

```bash
npm run gen:tool-index
```

This generates:
- `assets/docs/tool-index.md` — a table of all tools (`toolId | description`).
- `assets/directory/tool-directory.json` — a single JSON file mapping `toolId` to its JSON Schema.

## Programmatic APIs

This package exposes a few simple helpers for working with the `assets` tree and the generated code index. The code index (`assets/directory/code-directory.json`) is read once and cached internally.

- `readDocumentFiles(paths: string[])` → Promise<string[]>
  - Reads document files under `assets/docs/`. Each input is a file name like `engine.md` and the function will prefix `./docs/` automatically.
  - Example:
    ```ts
    import { readDocumentFiles } from '@galacean/file-browser';
    const docs = await readDocumentFiles(['engine.md', 'scene.md']);
    ```

- `readDeclareFiles(names: string[])` → Promise<string[]>
  - Given export names (e.g., `Animator`), returns the corresponding declaration file contents (`*.d.ts`) via the code‑directory map.

- `readSourceFiles(names: string[])` → Promise<string[]>
  - Given export names, returns the corresponding TypeScript source file contents.

- `readToolFiles(names: string[])` → Promise<string[]>
  - Reads tool JSON Schemas from the consolidated map `assets/directory/tool-directory.json` generated by `npm run gen:tool-index`.
  - Each input is a toolId like `asset.delete` and the function returns the JSON string for that schema (empty string when missing).
  - Example:
    ```ts
    import { readToolFiles } from '@galacean/file-browser';
    const [schemaOrJson] = await readToolFiles(['asset.delete']);
    const schema = typeof schemaOrJson === 'string' ? JSON.parse(schemaOrJson) : schemaOrJson;
    ```

## License

MIT