Skip to content

armgit / dify

Public Imported from GitHub
0

Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.

feat(cli): send a folder as one part per file (#44356)

Xiyuan Chen9253852eed12
diff --git a/cli/src/call/execute.ts b/cli/src/call/execute.ts
index 3e03d98e2d3..8ba2d93b0ce 100644
--- a/cli/src/call/execute.ts
+++ b/cli/src/call/execute.ts
@@ -2,7 +2,7 @@ import type { CallFlags } from '@/call/flags'
import type { CommandContext } from '@/plugins/base'
import type { CatalogOp } from '@/plugins/catalog'
import { readFile } from 'node:fs/promises'
-import { readLocalFile } from '@/call/files'
+import { LOCAL_FILES } from '@/call/files'
import { unsupportedFlags } from '@/call/flags'
import { applyPins, loadInput, resolveFileRefs } from '@/call/input'
import { rendererFor } from '@/call/render/index'
@@ -75,7 +75,7 @@ export async function executeCall(req: CallRequest, ctx: CommandContext): Promis
const res = await (
await ctx.get(http)
).request(async (cat) => ({
- ...(await buildRequest(cat.opOrThrow(req.id), body, { readFile: readLocalFile })),
+ ...(await buildRequest(cat.opOrThrow(req.id), body, LOCAL_FILES)),
signal,
}))
diff --git a/cli/src/call/files.test.ts b/cli/src/call/files.test.ts
new file mode 100644
index 00000000000..bf0160334e3
--- /dev/null
+++ b/cli/src/call/files.test.ts
@@ -0,0 +1,107 @@
+import { chmod, mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'
+import { platform, tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, expect, it } from 'vite-plus/test'
+import { folderLister, isLocalFolder, listLocalFolder } from './files'
+
+const LOCKED = 'locked'
+const MIB = 1024 * 1024
+
+let root: string
+
+beforeEach(async () => {
+ root = await mkdtemp(join(tmpdir(), 'difyctl-files-'))
+})
+
+afterEach(async () => {
+ await chmod(join(root, LOCKED), 0o700).catch(() => undefined)
+ await rm(root, { recursive: true, force: true })
+})
+
+it('lists files recursively, sorted, with / keys', async () => {
+ await writeFile(join(root, 'b.txt'), 'b')
+ await mkdir(join(root, 'a'))
+ await writeFile(join(root, 'a', 'x.md'), 'x')
+ await writeFile(join(root, 'a', '.env'), 'e')
+ expect(await listLocalFolder(root)).toEqual(['a/.env', 'a/x.md', 'b.txt'])
+})
+
+it('skips OS junk', async () => {
+ for (const name of ['.DS_Store', 'Thumbs.db', 'desktop.ini', 'keep.txt']) {
+ await writeFile(join(root, name), '')
+ }
+ await mkdir(join(root, '__MACOSX', 'a'), { recursive: true })
+ await writeFile(join(root, '__MACOSX', 'a', '._x'), '')
+ expect(await listLocalFolder(root)).toEqual(['keep.txt'])
+})
+
+it('keeps a regular file that shares a junk folder name', async () => {
+ await writeFile(join(root, '__MACOSX'), 'm')
+ expect(await listLocalFolder(root)).toEqual(['__MACOSX'])
+})
+
+it('returns [] when only junk is left', async () => {
+ await writeFile(join(root, '.DS_Store'), '')
+ expect(await listLocalFolder(root)).toEqual([])
+})
+
+it('tells a folder from a file and a missing path', async () => {
+ const file = join(root, 'f.txt')
+ await writeFile(file, 'f')
+ expect(await isLocalFolder(root)).toBe(true)
+ expect(await isLocalFolder(file)).toBe(false)
+ expect(await isLocalFolder(join(root, 'missing'))).toBe(false)
+})
+
+it('allows a folder at the file limit and refuses one over it', async () => {
+ const listTwo = folderLister({ files: 2, mebibytes: 1 })
+ await writeFile(join(root, 'a.txt'), 'a')
+ await writeFile(join(root, '.DS_Store'), '')
+ await writeFile(join(root, 'b.txt'), 'b')
+ expect(await listTwo(root)).toEqual(['a.txt', 'b.txt'])
+ await writeFile(join(root, 'c.txt'), 'c')
+ await expect(listTwo(root)).rejects.toMatchObject({
+ code: 'input_invalid',
+ message: `folder "${root}" has more than 2 files`,
+ })
+})
+
+it('refuses a folder over the size limit', async () => {
+ const listOneMib = folderLister({ files: 10, mebibytes: 1 })
+ await writeFile(join(root, 'a.bin'), new Uint8Array(MIB))
+ expect(await listOneMib(root)).toEqual(['a.bin'])
+ await writeFile(join(root, 'b.bin'), 'b')
+ await expect(listOneMib(root)).rejects.toMatchObject({
+ code: 'input_invalid',
+ message: `folder "${root}" is larger than 1 MiB`,
+ })
+})
+
+it.skipIf(platform() === 'win32')('rejects a symlink', async () => {
+ await symlink('..', join(root, 'loop'))
+ await expect(listLocalFolder(root)).rejects.toMatchObject({
+ code: 'input_invalid',
+ message: expect.stringContaining('loop'),
+ })
+})
+
+it.skipIf(platform() === 'win32')('names a nested symlink by its full path', async () => {
+ await mkdir(join(root, 'sub'))
+ await symlink('..', join(root, 'sub', 'loop'))
+ await expect(listLocalFolder(`${root}/`)).rejects.toMatchObject({
+ code: 'input_invalid',
+ message: expect.stringContaining(`"${join(root, 'sub', 'loop')}" is a symlink`),
+ })
+})
+
+it.skipIf(platform() === 'win32' || process.getuid?.() === 0)(
+ 'names the unreadable subfolder',
+ async () => {
+ await mkdir(join(root, LOCKED))
+ await chmod(join(root, LOCKED), 0o000)
+ await expect(listLocalFolder(root)).rejects.toMatchObject({
+ code: 'input_invalid',
+ message: `cannot read folder "${join(root, LOCKED)}"`,
+ })
+ },
+)
diff --git a/cli/src/call/files.ts b/cli/src/call/files.ts
index cbd1354c2a0..3721d8b651d 100644
--- a/cli/src/call/files.ts
+++ b/cli/src/call/files.ts
@@ -1,8 +1,77 @@
-import type { FileReader } from './request'
-import { readFile } from 'node:fs/promises'
-import { basename } from 'node:path'
+import type { FileDeps, FileReader, FolderCheck, FolderLister } from './request'
+import { readFile, stat } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import { inputInvalid } from '@/call/errors'
+import { BaseError } from '@/errors/base'
+import { ENTRY_KIND, KEY_SEPARATOR, walkTree } from '@/sys/tree'
+
+const JUNK_FILES: ReadonlySet<string> = new Set(['.DS_Store', 'Thumbs.db', 'desktop.ini'])
+const JUNK_DIRS: ReadonlySet<string> = new Set(['__MACOSX'])
+const BYTES_PER_MIB = 1024 * 1024
+
+export type FolderLimits = {
+ readonly files: number
+ readonly mebibytes: number
+}
+
+// Same as the server's App package defaults (AGENT_PACKAGE_MAX_ENTRIES,
+// AGENT_PACKAGE_MAX_BYTES): anything larger would be rejected after upload.
+export const FOLDER_LIMITS: FolderLimits = { files: 5000, mebibytes: 512 }
export const readLocalFile: FileReader = async (path) => ({
bytes: await readFile(path),
name: basename(path),
})
+
+export const isLocalFolder: FolderCheck = async (path) =>
+ (await stat(path).catch(() => undefined))?.isDirectory() === true
+
+function isJunk(path: string): boolean {
+ const segments = path.split(KEY_SEPARATOR)
+ const name = segments.pop()
+ return (
+ (name !== undefined && JUNK_FILES.has(name)) ||
+ segments.some((segment) => JUNK_DIRS.has(segment))
+ )
+}
+
+function failedPath(cause: unknown): string | undefined {
+ const path = (cause as NodeJS.ErrnoException | undefined)?.path
+ return typeof path === 'string' ? path : undefined
+}
+
+export function folderLister(limits: FolderLimits): FolderLister {
+ const maxBytes = limits.mebibytes * BYTES_PER_MIB
+ return async (path) => {
+ const files: string[] = []
+ let bytes = 0
+ try {
+ for await (const entry of walkTree(path)) {
+ if (entry.kind === ENTRY_KIND.Symlink) {
+ throw inputInvalid(
+ `"${join(path, entry.path)}" is a symlink; folders sent as input cannot contain symlinks`,
+ )
+ }
+ if (entry.kind !== ENTRY_KIND.File || isJunk(entry.path)) continue
+ files.push(entry.path)
+ if (files.length > limits.files)
+ throw inputInvalid(`folder "${path}" has more than ${limits.files} files`)
+ bytes += (await stat(join(path, entry.path))).size
+ if (bytes > maxBytes)
+ throw inputInvalid(`folder "${path}" is larger than ${limits.mebibytes} MiB`)
+ }
+ } catch (cause) {
+ if (cause instanceof BaseError) throw cause
+ throw inputInvalid(`cannot read folder "${failedPath(cause) ?? path}"`, cause)
+ }
+ return files.sort()
+ }
+}
+
+export const listLocalFolder: FolderLister = folderLister(FOLDER_LIMITS)
+
+export const LOCAL_FILES: FileDeps = {
+ readFile: readLocalFile,
+ isFolder: isLocalFolder,
+ listFolder: listLocalFolder,
+}
diff --git a/cli/src/call/request.test.ts b/cli/src/call/request.test.ts
index bb16f11c4ce..4566e39338f 100644
--- a/cli/src/call/request.test.ts
+++ b/cli/src/call/request.test.ts
@@ -1,7 +1,11 @@
+import type { FileDeps } from './request'
import type { CatalogOp } from '@/plugins/catalog'
import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { basename, join } from 'node:path'
import { expect, it } from 'vite-plus/test'
+import { LOCAL_FILES } from '@/call/files'
import { parseCatalog } from '@/plugins/catalog'
import { buildRequest } from './request'
@@ -10,9 +14,20 @@ const run = doc.ops['run.console_app.workflow']!
const list = doc.ops['get.console_app']!
const readFile = async (p: string) => ({
bytes: new TextEncoder().encode(`bytes-of-${p}`),
- name: p.split('/').pop() ?? p,
+ name: basename(p),
})
-const deps = { readFile }
+const FOLDERS: Readonly<Record<string, readonly string[]>> = {
+ './pkg': ['a.yaml', 's/SKILL.md'],
+ './junk': [],
+ './brackets': ['x[1].txt'],
+}
+const isFolder = async (p: string) => p in FOLDERS
+const listFolder = async (p: string) => {
+ const keys = FOLDERS[p]
+ if (keys === undefined) throw new Error(`not a folder: ${p}`)
+ return keys
+}
+const deps: FileDeps = { readFile, isFolder, listFolder }
it('splits path, query and body', async () => {
const req = await buildRequest(list, { workspace_id: 'ws 1', page: 2 }, deps)
@@ -61,3 +76,103 @@ it('refuses unknown bind values and non-path file values before sending', async
buildRequest(run, { app_id: 'a', inputs: {}, files: { doc: 42 } }, deps),
).rejects.toMatchObject({ code: 'input_invalid' })
})
+
+it('expands a folder into one part per file', async () => {
+ const req = await buildRequest(run, { app_id: 'a', inputs: {}, attachments: './pkg' }, deps)
+ const form = req.form!
+ expect([...form.keys()]).toEqual(['inputs', 'attachments[a.yaml]', 'attachments[s/SKILL.md]'])
+ expect((form.get('attachments[a.yaml]') as File).name).toBe('a.yaml')
+ expect((form.get('attachments[s/SKILL.md]') as File).name).toBe('SKILL.md')
+})
+
+it('refuses a folder inside a list or a map', async () => {
+ await expect(
+ buildRequest(run, { app_id: 'a', inputs: {}, files: { doc: './pkg' } }, deps),
+ ).rejects.toMatchObject({
+ code: 'input_invalid',
+ message: '"./pkg" is a folder; a folder can only be the whole value of files',
+ })
+ await expect(
+ buildRequest(run, { app_id: 'a', inputs: {}, attachments: ['./pkg'] }, deps),
+ ).rejects.toMatchObject({
+ code: 'input_invalid',
+ message: expect.stringContaining('is a folder'),
+ })
+ await expect(
+ buildRequest(run, { app_id: 'a', inputs: {}, attachments: ['./junk'] }, deps),
+ ).rejects.toMatchObject({ message: expect.stringContaining('is a folder') })
+})
+
+it('refuses an empty folder', async () => {
+ await expect(
+ buildRequest(run, { app_id: 'a', inputs: {}, attachments: './junk' }, deps),
+ ).rejects.toMatchObject({
+ code: 'input_invalid',
+ message: expect.stringContaining('folder "./junk" has no files'),
+ })
+})
+
+it('refuses a bracket in a folder path', async () => {
+ await expect(
+ buildRequest(run, { app_id: 'a', inputs: {}, attachments: './brackets' }, deps),
+ ).rejects.toMatchObject({
+ code: 'input_invalid',
+ message: expect.stringContaining('x[1].txt'),
+ })
+})
+
+it('keeps the missing-path error when the path is not a folder', async () => {
+ const failing = async () => {
+ throw new Error('ENOENT')
+ }
+ await expect(
+ buildRequest(
+ run,
+ { app_id: 'a', inputs: {}, attachments: './nope' },
+ { ...deps, readFile: failing },
+ ),
+ ).rejects.toMatchObject({
+ code: 'input_invalid',
+ message: 'cannot read file "./nope"',
+ })
+})
+
+it('lists a folder only when it is the whole value', async () => {
+ const checked: string[] = []
+ const listed: string[] = []
+ const counting: FileDeps = {
+ readFile,
+ isFolder: async (p) => {
+ checked.push(p)
+ return isFolder(p)
+ },
+ listFolder: async (p) => {
+ listed.push(p)
+ return listFolder(p)
+ },
+ }
+ await buildRequest(run, { app_id: 'a', inputs: {}, attachments: './att.txt' }, counting)
+ await expect(
+ buildRequest(run, { app_id: 'a', inputs: {}, attachments: ['./pkg'] }, counting),
+ ).rejects.toMatchObject({ message: expect.stringContaining('is a folder') })
+ expect(checked).toEqual(['./att.txt', './pkg'])
+ expect(listed).toEqual([])
+})
+
+it('sends a real folder through the local file deps', async () => {
+ const root = await mkdtemp(join(tmpdir(), 'difyctl-request-'))
+ try {
+ await writeFile(join(root, 'a.yaml'), 'app: 1')
+ await mkdir(join(root, 's'))
+ await writeFile(join(root, 's', 'SKILL.md'), '# skill')
+ const req = await buildRequest(run, { app_id: 'a', inputs: {}, attachments: root }, LOCAL_FILES)
+ const form = req.form!
+ expect([...form.keys()]).toEqual(['inputs', 'attachments[a.yaml]', 'attachments[s/SKILL.md]'])
+ const yaml = form.get('attachments[a.yaml]') as File
+ const skill = form.get('attachments[s/SKILL.md]') as File
+ expect([yaml.name, skill.name]).toEqual(['a.yaml', 'SKILL.md'])
+ expect([await yaml.text(), await skill.text()]).toEqual(['app: 1', '# skill'])
+ } finally {
+ await rm(root, { recursive: true, force: true })
+ }
+})
diff --git a/cli/src/call/request.ts b/cli/src/call/request.ts
index 7650395a1b7..74f40de597a 100644
--- a/cli/src/call/request.ts
+++ b/cli/src/call/request.ts
@@ -1,15 +1,27 @@
import type { CatalogOp } from '@/plugins/catalog'
import type { HttpRequest } from '@/plugins/http'
import type { Bind } from '@/protocol/bind'
+import { join } from 'node:path'
import { inputInvalid } from '@/call/errors'
import { BIND, isBind } from '@/protocol/bind'
import { isRecord } from '@/util/is-record'
export type FileReader = (
path: string,
-) => Promise<{ readonly bytes: Uint8Array; readonly name: string }>
+) => Promise<{ readonly bytes: Uint8Array<ArrayBuffer>; readonly name: string }>
+
+export type FolderCheck = (path: string) => Promise<boolean>
+
+export type FolderLister = (path: string) => Promise<readonly string[]>
+
+export type FileDeps = {
+ readonly readFile: FileReader
+ readonly isFolder: FolderCheck
+ readonly listFolder: FolderLister
+}
const LIST_SUFFIX = '[]'
+const RESERVED_KEY_CHARS = /[[\]]/
const HttpMethod = { Get: 'GET', Delete: 'DELETE' } as const
const BODYLESS_METHODS: ReadonlySet<string> = new Set(Object.values(HttpMethod))
@@ -88,66 +100,102 @@ function partName(field: string, key: string | undefined, many: boolean): string
return many ? `${base}${LIST_SUFFIX}` : base
}
-async function readAsFile(path: string, readFile: FileReader): Promise<File> {
- let resolved: { bytes: Uint8Array; name: string }
+async function readAsFile(path: string, { readFile }: FileDeps): Promise<File> {
+ let resolved: Awaited<ReturnType<FileReader>>
try {
resolved = await readFile(path)
} catch (cause) {
throw inputInvalid(`cannot read file "${path}"`, cause)
}
- return new File([Uint8Array.from(resolved.bytes)], resolved.name)
+ return new File([resolved.bytes], resolved.name)
}
function assertPathString(value: unknown, field: string): asserts value is string {
if (typeof value !== 'string')
throw inputInvalid(
- `file field "${field}" must be a path string, an array of paths, or an object mapping names to paths`,
+ `file field "${field}" must be a path string, a folder, an array of paths, or an object mapping names to paths`,
)
}
-async function appendFileParts(
- form: FormData,
- name: string,
- value: unknown,
- field: string,
- readFile: FileReader,
-): Promise<void> {
- if (Array.isArray(value)) {
- for (const item of value) {
- assertPathString(item, field)
- form.append(name, await readAsFile(item, readFile))
- }
- return
+async function assertNotFolder(path: string, field: string, deps: FileDeps): Promise<void> {
+ if (await deps.isFolder(path))
+ throw inputInvalid(`"${path}" is a folder; a folder can only be the whole value of ${field}`)
+}
+
+type FieldTarget = {
+ readonly form: FormData
+ // Top-level input key bound to `file`.
+ readonly field: string
+ readonly deps: FileDeps
+}
+
+type FolderParts = FieldTarget & {
+ readonly folder: string
+ // File paths relative to `folder`, as returned by `listFolder`.
+ readonly keys: readonly string[]
+}
+
+type FileParts = FieldTarget & {
+ // Multipart part name, e.g. `field`, `field[]`, `field[key]`, `field[key][]`.
+ readonly name: string
+ // A path string or an array of path strings; validated per item.
+ readonly value: unknown
+ // Input location for error messages, e.g. `field` or `field.key`.
+ readonly label: string
+}
+
+async function appendFolderParts({ form, field, deps, folder, keys }: FolderParts): Promise<void> {
+ if (keys.length === 0) throw inputInvalid(`folder "${folder}" has no files`)
+ const reserved = keys.find((key) => RESERVED_KEY_CHARS.test(key))
+ if (reserved !== undefined)
+ throw inputInvalid(
+ `"${reserved}" in folder "${folder}" contains "[" or "]", which a part name cannot carry`,
+ )
+ for (const key of keys)
+ form.append(partName(field, key, false), await readAsFile(join(folder, key), deps))
+}
+
+async function appendFileParts({
+ form,
+ field,
+ deps,
+ name,
+ value,
+ label,
+}: FileParts): Promise<void> {
+ const items = Array.isArray(value) ? value : [value]
+ for (const item of items) {
+ assertPathString(item, label)
+ await assertNotFolder(item, field, deps)
+ form.append(name, await readAsFile(item, deps))
}
- assertPathString(value, field)
- form.append(name, await readAsFile(value, readFile))
}
-async function appendFileField(
- form: FormData,
- field: string,
- value: unknown,
- readFile: FileReader,
-): Promise<void> {
+async function appendFileField(target: FieldTarget, value: unknown): Promise<void> {
+ const { form, field, deps } = target
if (value === null || value === undefined) return
+ if (typeof value === 'string') {
+ if (await deps.isFolder(value))
+ return appendFolderParts({ ...target, folder: value, keys: await deps.listFolder(value) })
+ form.append(partName(field, undefined, false), await readAsFile(value, deps))
+ return
+ }
if (isRecord(value)) {
for (const [key, item] of Object.entries(value))
- await appendFileParts(
- form,
- partName(field, key, Array.isArray(item)),
- item,
- `${field}.${key}`,
- readFile,
- )
+ await appendFileParts({
+ ...target,
+ name: partName(field, key, Array.isArray(item)),
+ value: item,
+ label: `${field}.${key}`,
+ })
return
}
- await appendFileParts(
- form,
- partName(field, undefined, Array.isArray(value)),
+ await appendFileParts({
+ ...target,
+ name: partName(field, undefined, Array.isArray(value)),
value,
- field,
- readFile,
- )
+ label: field,
+ })
}
function hasFileValue(values: Map<string, unknown>): boolean {
@@ -157,7 +205,7 @@ function hasFileValue(values: Map<string, unknown>): boolean {
export async function buildRequest(
op: CatalogOp,
input: Record<string, unknown>,
- deps: { readonly readFile: FileReader },
+ deps: FileDeps,
): Promise<HttpRequest> {
const buckets = classify(op, input)
const path = substitutePath(op.path, buckets[Placement.Path])
@@ -176,7 +224,7 @@ export async function buildRequest(
form.append(key, JSON.stringify(value))
}
for (const [field, value] of buckets[Placement.File])
- await appendFileField(form, field, value, deps.readFile)
+ await appendFileField({ form, field, deps }, value)
return { method: op.method, path, query, form }
}
diff --git a/cli/src/commands/use/workspace/index.ts b/cli/src/commands/use/workspace/index.ts
index 62f19f7ad61..f2b96e2d224 100644
--- a/cli/src/commands/use/workspace/index.ts
+++ b/cli/src/commands/use/workspace/index.ts
@@ -1,7 +1,7 @@
import type { CommandContext } from '@/plugins/base'
import { z } from 'zod'
import { assertNotEnvLogin } from '@/auth/logout'
-import { readLocalFile } from '@/call/files'
+import { LOCAL_FILES } from '@/call/files'
import { parseJsonBody } from '@/call/json-body'
import { buildRequest } from '@/call/request'
import { BaseError } from '@/errors/base'
@@ -42,7 +42,7 @@ export default class WorkspaceUse extends Command<typeof INPUT> {
buildRequest(
cat.opOrThrow(WORKSPACE_DESCRIBE_OP),
{ workspace_id: input.workspace_id },
- { readFile: readLocalFile },
+ LOCAL_FILES,
),
)
const workspace = WORKSPACE.safeParse(await parseJsonBody(res))
diff --git a/cli/src/skills/source.ts b/cli/src/skills/source.ts
index 63ff4cf65a3..861dc981d7f 100644
--- a/cli/src/skills/source.ts
+++ b/cli/src/skills/source.ts
@@ -1,11 +1,12 @@
import type { EmbeddedFile } from '@/sys'
-import { readdir, readFile, stat } from 'node:fs/promises'
-import { join, relative, sep } from 'node:path'
+import { readFile, stat } from 'node:fs/promises'
+import { join } from 'node:path'
import { fileURLToPath } from 'node:url'
import { z } from 'zod'
import { BaseError } from '@/errors/base'
import { ErrorCode } from '@/errors/codes'
import { embeddedFiles, isCompiledBinary } from '@/sys'
+import { ENTRY_KIND, walkTree } from '@/sys/tree'
export const SKILL_NAME = 'difyctl'
export const SKILL_FILE = 'SKILL.md'
@@ -57,9 +58,8 @@ export async function openDir(root: string): Promise<SkillSource> {
})
}
const paths: string[] = []
- for (const entry of await readdir(root, { recursive: true, withFileTypes: true })) {
- if (entry.isFile())
- paths.push(relative(root, join(entry.parentPath, entry.name)).split(sep).join('/'))
+ for await (const entry of walkTree(root)) {
+ if (entry.kind === ENTRY_KIND.File) paths.push(entry.path)
}
return { paths, read: (path) => readLocal(join(root, path)) }
}
diff --git a/cli/src/sys/tree.test.ts b/cli/src/sys/tree.test.ts
new file mode 100644
index 00000000000..6c3ceeb0ad7
--- /dev/null
+++ b/cli/src/sys/tree.test.ts
@@ -0,0 +1,74 @@
+import type { TreeEntry } from './tree'
+import { chmod, mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'
+import { platform, tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, expect, it } from 'vite-plus/test'
+import { ENTRY_KIND, walkTree } from './tree'
+
+const LOCKED = 'locked'
+
+let root: string
+
+async function walkAll(dir: string): Promise<TreeEntry[]> {
+ const entries: TreeEntry[] = []
+ for await (const entry of walkTree(dir)) entries.push(entry)
+ return entries
+}
+
+beforeEach(async () => {
+ root = await mkdtemp(join(tmpdir(), 'difyctl-tree-'))
+ await writeFile(join(root, 'a.txt'), 'a')
+ await mkdir(join(root, 'sub'))
+ await writeFile(join(root, 'sub', 'b.txt'), 'b')
+ await mkdir(join(root, 'empty'))
+})
+
+afterEach(async () => {
+ await chmod(join(root, LOCKED), 0o700).catch(() => undefined)
+ await rm(root, { recursive: true, force: true })
+})
+
+it('walkTree lists nested entries with / paths and their kinds', async () => {
+ const entries = (await walkAll(root)).sort((a, b) => a.path.localeCompare(b.path))
+ expect(entries).toEqual([
+ { path: 'a.txt', kind: ENTRY_KIND.File },
+ { path: 'empty', kind: ENTRY_KIND.Directory },
+ { path: 'sub', kind: ENTRY_KIND.Directory },
+ { path: 'sub/b.txt', kind: ENTRY_KIND.File },
+ ])
+})
+
+it.skipIf(platform() === 'win32')('walkTree lists a symlink as its own kind', async () => {
+ await symlink('a.txt', join(root, 'link'))
+ expect(await walkAll(root)).toContainEqual({ path: 'link', kind: ENTRY_KIND.Symlink })
+})
+
+it.skipIf(platform() === 'win32')('walkTree does not descend into a symlinked folder', async () => {
+ await symlink('sub', join(root, 'sublink'))
+ const entries = await walkAll(root)
+ expect(entries).toContainEqual({ path: 'sublink', kind: ENTRY_KIND.Symlink })
+ expect(entries.map((entry) => entry.path)).not.toContain('sublink/b.txt')
+})
+
+it.skipIf(platform() === 'win32')(
+ 'walkTree reports a nested symlink by its nested path',
+ async () => {
+ await symlink('..', join(root, 'sub', 'loop'))
+ expect(await walkAll(root)).toContainEqual({ path: 'sub/loop', kind: ENTRY_KIND.Symlink })
+ },
+)
+
+it.skipIf(platform() === 'win32' || process.getuid?.() === 0)(
+ 'walkTree reads no further once the caller stops',
+ async () => {
+ await mkdir(join(root, LOCKED))
+ await chmod(join(root, LOCKED), 0o000)
+ await expect(walkAll(root)).rejects.toThrow()
+ const seen: TreeEntry[] = []
+ for await (const entry of walkTree(root)) {
+ seen.push(entry)
+ break
+ }
+ expect(seen).toHaveLength(1)
+ },
+)
diff --git a/cli/src/sys/tree.ts b/cli/src/sys/tree.ts
new file mode 100644
index 00000000000..2f04e1555b4
--- /dev/null
+++ b/cli/src/sys/tree.ts
@@ -0,0 +1,42 @@
+import type { Dirent } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export const ENTRY_KIND = {
+ File: 'file',
+ Directory: 'directory',
+ Symlink: 'symlink',
+ Other: 'other',
+} as const
+
+export type EntryKind = (typeof ENTRY_KIND)[keyof typeof ENTRY_KIND]
+
+export type TreeEntry = {
+ readonly path: string
+ readonly kind: EntryKind
+}
+
+export const KEY_SEPARATOR = '/'
+
+function kindOf(entry: Dirent): EntryKind {
+ if (entry.isSymbolicLink()) return ENTRY_KIND.Symlink
+ if (entry.isFile()) return ENTRY_KIND.File
+ if (entry.isDirectory()) return ENTRY_KIND.Directory
+ return ENTRY_KIND.Other
+}
+
+// No `recursive` readdir: Bun follows symlinked directories there, so a link
+// loop hangs or fails with ELOOP. Walking by hand never descends into a link.
+async function* walkInto(dir: string, prefix: string): AsyncGenerator<TreeEntry> {
+ for (const entry of await readdir(dir, { withFileTypes: true })) {
+ const path = prefix === '' ? entry.name : `${prefix}${KEY_SEPARATOR}${entry.name}`
+ const kind = kindOf(entry)
+ yield { path, kind }
+ if (kind === ENTRY_KIND.Directory) yield* walkInto(join(dir, entry.name), path)
+ }
+}
+
+/** Yields one directory at a time, so a caller that stops early stops the walk. */
+export function walkTree(root: string): AsyncIterable<TreeEntry> {
+ return walkInto(root, '')
+}