aws-runtime-bridge 1.4.0 → 1.5.0

package/dist/services/workspace-files.test.js

@@ -1,30 +1,117 @@
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { createWriteStream, promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { promises as fs } from 'node:fs';
-import { createWorkspaceEntry, deleteWorkspaceEntry, listWorkspaceDirectory, readWorkspaceFile, renameWorkspaceEntry, writeWorkspaceFile, } from './workspace-files.js';
+import * as tar from 'tar';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { createWorkspaceEntry, deleteWorkspaceEntry, extractWorkspaceArchive, listWorkspaceDirectory, previewWorkspaceDocument, readWorkspaceFile, renameWorkspaceEntry, resolveWorkspaceDownloadTarget, streamWorkspaceDirectoryZip, uploadWorkspaceFiles, writeWorkspaceFile, } from './workspace-files.js';
+const { ZipArchive } = await import('archiver');
+function crc32(input) {
+    let crc = 0xffffffff;
+    for (const byte of input) {
+        crc ^= byte;
+        for (let bit = 0; bit < 8; bit += 1) {
+            crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+        }
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+async function writeStoredZip(filePath, entryName, content) {
+    const nameBytes = Buffer.from(entryName, 'utf-8');
+    await writeStoredZipWithNameBytes(filePath, nameBytes, content);
+}
+async function writeStoredZipWithNameBytes(filePath, nameBytes, content) {
+    const contentBytes = Buffer.from(content, 'utf-8');
+    const checksum = crc32(contentBytes);
+    const localHeader = Buffer.alloc(30);
+    localHeader.writeUInt32LE(0x04034b50, 0);
+    localHeader.writeUInt16LE(20, 4);
+    localHeader.writeUInt16LE(0, 6);
+    localHeader.writeUInt16LE(0, 8);
+    localHeader.writeUInt32LE(0, 10);
+    localHeader.writeUInt32LE(checksum, 14);
+    localHeader.writeUInt32LE(contentBytes.length, 18);
+    localHeader.writeUInt32LE(contentBytes.length, 22);
+    localHeader.writeUInt16LE(nameBytes.length, 26);
+    localHeader.writeUInt16LE(0, 28);
+    const centralHeader = Buffer.alloc(46);
+    centralHeader.writeUInt32LE(0x02014b50, 0);
+    centralHeader.writeUInt16LE(20, 4);
+    centralHeader.writeUInt16LE(20, 6);
+    centralHeader.writeUInt16LE(0, 8);
+    centralHeader.writeUInt16LE(0, 10);
+    centralHeader.writeUInt32LE(0, 12);
+    centralHeader.writeUInt32LE(checksum, 16);
+    centralHeader.writeUInt32LE(contentBytes.length, 20);
+    centralHeader.writeUInt32LE(contentBytes.length, 24);
+    centralHeader.writeUInt16LE(nameBytes.length, 28);
+    centralHeader.writeUInt16LE(0, 30);
+    centralHeader.writeUInt16LE(0, 32);
+    centralHeader.writeUInt16LE(0, 34);
+    centralHeader.writeUInt16LE(0, 36);
+    centralHeader.writeUInt32LE(0, 38);
+    centralHeader.writeUInt32LE(0, 42);
+    const centralDirectoryOffset = localHeader.length + nameBytes.length + contentBytes.length;
+    const centralDirectorySize = centralHeader.length + nameBytes.length;
+    const endRecord = Buffer.alloc(22);
+    endRecord.writeUInt32LE(0x06054b50, 0);
+    endRecord.writeUInt16LE(0, 4);
+    endRecord.writeUInt16LE(0, 6);
+    endRecord.writeUInt16LE(1, 8);
+    endRecord.writeUInt16LE(1, 10);
+    endRecord.writeUInt32LE(centralDirectorySize, 12);
+    endRecord.writeUInt32LE(centralDirectoryOffset, 16);
+    endRecord.writeUInt16LE(0, 20);
+    await fs.writeFile(filePath, Buffer.concat([
+        localHeader,
+        nameBytes,
+        contentBytes,
+        centralHeader,
+        nameBytes,
+        endRecord
+    ]));
+}
 describe('workspace file service', () => {
     const tempRoot = path.join(os.tmpdir(), `aws-workspace-files-${Date.now()}`);
     const workspacePath = path.join(tempRoot, 'workspace');
     const nestedDir = path.join(workspacePath, 'src');
     const nestedFile = path.join(nestedDir, 'index.ts');
+    let realWorkspacePath = '';
+    let realNestedFile = '';
     beforeAll(async () => {
         await fs.mkdir(nestedDir, { recursive: true });
         await fs.writeFile(nestedFile, 'console.log("hello")\n', 'utf-8');
         await fs.writeFile(path.join(workspacePath, 'README.md'), '# test\n', 'utf-8');
+        realWorkspacePath = (await fs.realpath(workspacePath)).replace(/\\/g, '/');
+        realNestedFile = (await fs.realpath(nestedFile)).replace(/\\/g, '/');
     });
     afterAll(async () => {
-        await fs.rm(tempRoot, { recursive: true, force: true });
-    });
+        await Promise.all([
+            path.join(workspacePath, 'outside-secret-link.txt'),
+            path.join(workspacePath, 'outside-link'),
+            path.join(tempRoot, 'archive-link')
+        ].map(async (linkPath) => {
+            try {
+                const stat = await fs.lstat(linkPath);
+                if (stat.isSymbolicLink()) {
+                    await fs.unlink(linkPath);
+                }
+            }
+            catch {
+                // Best-effort cleanup for platform-dependent symlink tests.
+            }
+        }));
+        await fs.rm(tempRoot, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
+    }, 30_000);
     it('lists workspace root when request path is empty', async () => {
         const result = await listWorkspaceDirectory({
             workspacePath,
             targetPath: ''
         });
-        expect(result.currentPath).toBe(workspacePath.replace(/\\/g, '/'));
-        expect(result.workspacePath).toBe(workspacePath.replace(/\\/g, '/'));
+        expect(result.currentPath).toBe(realWorkspacePath);
+        expect(result.workspacePath).toBe(realWorkspacePath);
         expect(result.items.some((item) => item.name === 'src' && item.isDirectory)).toBe(true);
         expect(result.items.some((item) => item.name === 'README.md' && !item.isDirectory)).toBe(true);
+        expect(result.items.find((item) => item.name === 'README.md')?.size).toBe(Buffer.byteLength('# test\n'));
         expect(result.items.every((item) => !item.path.includes('\\'))).toBe(true);
     });
     it('rejects reading files outside workspace', async () => {
@@ -39,8 +126,8 @@ describe('workspace file service', () => {
             filePath: nestedFile
         });
         expect(beforeRead.content).toBe('console.log("hello")\n');
-        expect(beforeRead.workspacePath).toBe(workspacePath.replace(/\\/g, '/'));
-        expect(beforeRead.filePath).toBe(nestedFile.replace(/\\/g, '/'));
+        expect(beforeRead.workspacePath).toBe(realWorkspacePath);
+        expect(beforeRead.filePath).toBe(realNestedFile);
         await writeWorkspaceFile({
             workspacePath,
             filePath: nestedFile,
@@ -79,13 +166,13 @@ describe('workspace file service', () => {
             targetPath: createdFile,
             newName: 'demo-renamed.txt'
         });
-        expect(renameFileResult.targetPath).toBe(renamedFile.replace(/\\/g, '/'));
+        expect(renameFileResult.targetPath).toBe((await fs.realpath(renamedFile)).replace(/\\/g, '/'));
         const renameDirResult = await renameWorkspaceEntry({
             workspacePath,
             targetPath: featureDir,
             newName: 'feature-renamed'
         });
-        expect(renameDirResult.targetPath).toBe(renamedDir.replace(/\\/g, '/'));
+        expect(renameDirResult.targetPath).toBe((await fs.realpath(renamedDir)).replace(/\\/g, '/'));
         const listRenamedDirectory = await listWorkspaceDirectory({
             workspacePath,
             targetPath: renamedDir
@@ -114,4 +201,293 @@ describe('workspace file service', () => {
             targetPath: workspacePath
         })).rejects.toThrow(/Workspace root cannot be modified/);
     });
+    it('uploads files to a selected workspace directory', async () => {
+        const uploadSource = path.join(tempRoot, 'upload-source.txt');
+        const uploadTargetDir = path.join(workspacePath, 'uploads');
+        await fs.mkdir(uploadTargetDir, { recursive: true });
+        await fs.writeFile(uploadSource, 'uploaded content', 'utf-8');
+        const result = await uploadWorkspaceFiles({
+            workspacePath,
+            targetPath: uploadTargetDir,
+            files: [{ originalname: '../safe-name.txt', path: uploadSource, size: 16 }]
+        });
+        const uploadedPath = path.join(uploadTargetDir, 'safe-name.txt');
+        expect(result.files[0].targetPath).toBe((await fs.realpath(uploadedPath)).replace(/\\/g, '/'));
+        await expect(fs.readFile(uploadedPath, 'utf-8')).resolves.toBe('uploaded content');
+    });
+    it('preserves safe relative paths when uploading folders', async () => {
+        const firstSource = path.join(tempRoot, 'folder-upload-first.txt');
+        const secondSource = path.join(tempRoot, 'folder-upload-second.txt');
+        const uploadTargetDir = path.join(workspacePath, 'folder-uploads');
+        await fs.mkdir(uploadTargetDir, { recursive: true });
+        await fs.writeFile(firstSource, 'first nested file', 'utf-8');
+        await fs.writeFile(secondSource, 'second nested file', 'utf-8');
+        const result = await uploadWorkspaceFiles({
+            workspacePath,
+            targetPath: uploadTargetDir,
+            files: [
+                { originalname: 'first.txt', relativePath: 'project/src/first.txt', path: firstSource, size: 17 },
+                { originalname: 'second.txt', relativePath: 'project/docs/second.txt', path: secondSource, size: 18 }
+            ]
+        });
+        const firstUploadedPath = path.join(uploadTargetDir, 'project', 'src', 'first.txt');
+        const secondUploadedPath = path.join(uploadTargetDir, 'project', 'docs', 'second.txt');
+        expect(result.files.map((file) => file.targetPath)).toEqual([
+            (await fs.realpath(firstUploadedPath)).replace(/\\/g, '/'),
+            (await fs.realpath(secondUploadedPath)).replace(/\\/g, '/')
+        ]);
+        await expect(fs.readFile(firstUploadedPath, 'utf-8')).resolves.toBe('first nested file');
+        await expect(fs.readFile(secondUploadedPath, 'utf-8')).resolves.toBe('second nested file');
+    });
+    it('rejects unsafe relative upload paths', async () => {
+        const uploadSource = path.join(tempRoot, 'unsafe-folder-upload.txt');
+        const uploadTargetDir = path.join(workspacePath, 'unsafe-folder-uploads');
+        await fs.mkdir(uploadTargetDir, { recursive: true });
+        await fs.writeFile(uploadSource, 'unsafe content', 'utf-8');
+        await expect(uploadWorkspaceFiles({
+            workspacePath,
+            targetPath: uploadTargetDir,
+            files: [{ originalname: 'safe.txt', relativePath: 'project/../escape.txt', path: uploadSource, size: 14 }]
+        })).rejects.toThrow(/entryName is invalid/);
+    });
+    it('uploads binary exe files and lists them after upload', async () => {
+        const uploadSource = path.join(tempRoot, 'demo-app-source.exe');
+        const uploadTargetDir = path.join(workspacePath, 'bin');
+        const exeBytes = Buffer.from([0x4d, 0x5a, 0x90, 0x00, 0x03, 0x00, 0xff, 0x00]);
+        await fs.mkdir(uploadTargetDir, { recursive: true });
+        await fs.writeFile(uploadSource, exeBytes);
+        const uploadResult = await uploadWorkspaceFiles({
+            workspacePath,
+            targetPath: uploadTargetDir,
+            files: [{ originalname: 'demo-app.exe', path: uploadSource, size: exeBytes.length }]
+        });
+        const uploadedPath = path.join(uploadTargetDir, 'demo-app.exe');
+        expect(uploadResult.files[0]).toMatchObject({
+            fileName: 'demo-app.exe',
+            size: exeBytes.length
+        });
+        await expect(fs.readFile(uploadedPath)).resolves.toEqual(exeBytes);
+        const listedDirectory = await listWorkspaceDirectory({
+            workspacePath,
+            targetPath: uploadTargetDir
+        });
+        expect(listedDirectory.items.some((item) => item.name === 'demo-app.exe' && !item.isDirectory)).toBe(true);
+    });
+    it('decodes latin1-mojibake UTF-8 upload file names before saving', async () => {
+        const uploadSource = path.join(tempRoot, 'springboot-source.zip');
+        const uploadTargetDir = path.join(workspacePath, 'encoded-uploads');
+        const originalName = 'springboot测试压缩包2.zip';
+        const mojibakeName = Buffer.from(originalName, 'utf8').toString('latin1');
+        await fs.mkdir(uploadTargetDir, { recursive: true });
+        await fs.writeFile(uploadSource, 'zip bytes', 'utf-8');
+        const uploadResult = await uploadWorkspaceFiles({
+            workspacePath,
+            targetPath: uploadTargetDir,
+            files: [{ originalname: mojibakeName, path: uploadSource, size: 9 }]
+        });
+        const uploadedPath = path.join(uploadTargetDir, originalName);
+        expect(uploadResult.files[0].fileName).toBe(originalName);
+        await expect(fs.readFile(uploadedPath, 'utf-8')).resolves.toBe('zip bytes');
+        const listedDirectory = await listWorkspaceDirectory({
+            workspacePath,
+            targetPath: uploadTargetDir
+        });
+        expect(listedDirectory.items.some((item) => item.name === originalName)).toBe(true);
+    });
+    it('extracts uploaded zip archives into a directory named after the archive', async () => {
+        const uploadTargetDir = path.join(workspacePath, 'zip-auto-extract');
+        const uploadSource = path.join(tempRoot, 'project-package-source.zip');
+        await fs.mkdir(uploadTargetDir, { recursive: true });
+        await new Promise((resolve, reject) => {
+            const archive = new ZipArchive();
+            const output = createWriteStream(uploadSource);
+            output.on('close', resolve);
+            archive.on('error', reject);
+            archive.pipe(output);
+            archive.append('first file', { name: 'a.txt' });
+            archive.append('second file', { name: 'nested/b.txt' });
+            archive.finalize().catch(reject);
+        });
+        const uploadResult = await uploadWorkspaceFiles({
+            workspacePath,
+            targetPath: uploadTargetDir,
+            extractArchives: true,
+            files: [{ originalname: 'project-package.zip', path: uploadSource, size: (await fs.stat(uploadSource)).size }]
+        });
+        const extractedRoot = path.join(uploadTargetDir, 'project-package');
+        expect(uploadResult.files[0].extracted?.targetPath).toBe((await fs.realpath(extractedRoot)).replace(/\\/g, '/'));
+        expect(uploadResult.files[0].extracted?.extractedEntries).toBe(2);
+        await expect(fs.readFile(path.join(extractedRoot, 'a.txt'), 'utf-8')).resolves.toBe('first file');
+        await expect(fs.readFile(path.join(extractedRoot, 'nested', 'b.txt'), 'utf-8')).resolves.toBe('second file');
+        await expect(fs.access(path.join(uploadTargetDir, 'a.txt'))).rejects.toThrow();
+    });
+    it('extracts uploaded tar archives into a directory named after the archive', async () => {
+        const uploadTargetDir = path.join(workspacePath, 'tar-auto-extract');
+        const tarSourceDir = path.join(tempRoot, 'tar-source');
+        const uploadSource = path.join(tempRoot, 'bundle-source.tar');
+        await fs.mkdir(path.join(tarSourceDir, 'nested'), { recursive: true });
+        await fs.mkdir(uploadTargetDir, { recursive: true });
+        await fs.writeFile(path.join(tarSourceDir, 'root.txt'), 'root tar file', 'utf-8');
+        await fs.writeFile(path.join(tarSourceDir, 'nested', 'child.txt'), 'child tar file', 'utf-8');
+        await tar.c({ file: uploadSource, cwd: tarSourceDir }, ['root.txt', 'nested/child.txt']);
+        const uploadResult = await uploadWorkspaceFiles({
+            workspacePath,
+            targetPath: uploadTargetDir,
+            extractArchives: true,
+            files: [{ originalname: 'bundle.tar', path: uploadSource, size: (await fs.stat(uploadSource)).size }]
+        });
+        const extractedRoot = path.join(uploadTargetDir, 'bundle');
+        expect(uploadResult.files[0].extracted?.targetPath).toBe((await fs.realpath(extractedRoot)).replace(/\\/g, '/'));
+        expect(uploadResult.files[0].extracted?.extractedEntries).toBe(2);
+        await expect(fs.readFile(path.join(extractedRoot, 'root.txt'), 'utf-8')).resolves.toBe('root tar file');
+        await expect(fs.readFile(path.join(extractedRoot, 'nested', 'child.txt'), 'utf-8')).resolves.toBe('child tar file');
+        await expect(fs.access(path.join(uploadTargetDir, 'root.txt'))).rejects.toThrow();
+    });
+    it('does not expose outside target size for file symlinks in directory listings', async () => {
+        const outsideFile = path.join(tempRoot, 'outside-secret.txt');
+        const symlinkPath = path.join(workspacePath, 'outside-secret-link.txt');
+        await fs.writeFile(outsideFile, 'outside-secret-content', 'utf-8');
+        try {
+            await fs.symlink(outsideFile, symlinkPath, 'file');
+        }
+        catch (error) {
+            const errorCode = typeof error === 'object' && error !== null ? Reflect.get(error, 'code') : undefined;
+            if (errorCode === 'EPERM' || errorCode === 'EACCES') {
+                return;
+            }
+            throw error;
+        }
+        const result = await listWorkspaceDirectory({
+            workspacePath,
+            targetPath: workspacePath
+        });
+        const symlinkItem = result.items.find((item) => item.name === 'outside-secret-link.txt');
+        expect(symlinkItem).toBeDefined();
+        expect(symlinkItem?.size).toBeUndefined();
+    });
+    it('resolves file and directory download targets safely', async () => {
+        const fileTarget = await resolveWorkspaceDownloadTarget({
+            workspacePath,
+            targetPath: nestedFile
+        });
+        expect(fileTarget.isDirectory).toBe(false);
+        expect(fileTarget.fileName).toBe('index.ts');
+        const directoryTarget = await resolveWorkspaceDownloadTarget({
+            workspacePath,
+            targetPath: nestedDir
+        });
+        expect(directoryTarget.isDirectory).toBe(true);
+        expect(directoryTarget.fileName).toBe('src.zip');
+    });
+    it('streams a workspace directory as a zip archive', async () => {
+        const zipPath = path.join(tempRoot, 'src.zip');
+        await streamWorkspaceDirectoryZip(nestedDir, createWriteStream(zipPath));
+        const stat = await fs.stat(zipPath);
+        expect(stat.size).toBeGreaterThan(0);
+    });
+    it('extracts zip archives and rejects path traversal entries', async () => {
+        const goodZip = path.join(workspacePath, 'archive.zip');
+        const badZip = path.join(workspacePath, 'bad.zip');
+        const extractDir = path.join(workspacePath, 'extracted');
+        await new Promise((resolve, reject) => {
+            const archive = new ZipArchive();
+            const output = createWriteStream(goodZip);
+            output.on('close', resolve);
+            archive.on('error', reject);
+            archive.pipe(output);
+            archive.append('zip content', { name: 'nested/file.txt' });
+            archive.finalize().catch(reject);
+        });
+        const extracted = await extractWorkspaceArchive({
+            workspacePath,
+            archivePath: goodZip,
+            outputPath: extractDir
+        });
+        expect(extracted.extractedEntries).toBe(1);
+        await expect(fs.readFile(path.join(extractDir, 'nested', 'file.txt'), 'utf-8')).resolves.toBe('zip content');
+        await writeStoredZip(badZip, '../escape.txt', 'escape');
+        await expect(extractWorkspaceArchive({
+            workspacePath,
+            archivePath: badZip,
+            outputPath: extractDir
+        })).rejects.toThrow(/Archive entry path is invalid|outside workspace/);
+    });
+    it('extracts GBK encoded zip entry names as Chinese paths', async () => {
+        const gbkZip = path.join(workspacePath, 'gbk-archive.zip');
+        const extractDir = path.join(workspacePath, 'gbk-extracted');
+        const chineseDirectoryName = 'springboot067摄影师社区2';
+        const gbkEntryNameBytes = Buffer.from([
+            115, 112, 114, 105, 110, 103, 98, 111, 111, 116, 48, 54, 55,
+            201, 227, 211, 176, 202, 166, 201, 231, 199, 248, 50,
+            47, 114, 101, 97, 100, 109, 101, 46, 116, 120, 116
+        ]);
+        await writeStoredZipWithNameBytes(gbkZip, gbkEntryNameBytes, '中文目录内容');
+        const extracted = await extractWorkspaceArchive({
+            workspacePath,
+            archivePath: gbkZip,
+            outputPath: extractDir
+        });
+        expect(extracted.extractedEntries).toBe(1);
+        await expect(fs.readFile(path.join(extractDir, chineseDirectoryName, 'readme.txt'), 'utf-8'))
+            .resolves.toBe('中文目录内容');
+    });
+    it('returns docx preview metadata without parsing document contents', async () => {
+        const docxPath = path.join(workspacePath, 'large-preview.docx');
+        const largeImageLikePayload = Buffer.alloc(21 * 1024 * 1024, 1);
+        await fs.writeFile(docxPath, largeImageLikePayload);
+        const preview = await previewWorkspaceDocument({ workspacePath, filePath: docxPath });
+        expect(preview.kind).toBe('html');
+        expect(preview.content).toBe('');
+        expect(preview.size).toBe(largeImageLikePayload.length);
+        expect(preview.mtimeMs).toBeGreaterThan(0);
+    });
+    it('returns unsupported preview metadata for legacy doc files', async () => {
+        const docPath = path.join(workspacePath, 'legacy.doc');
+        await fs.writeFile(docPath, 'legacy word bytes', 'utf-8');
+        const preview = await previewWorkspaceDocument({ workspacePath, filePath: docPath });
+        expect(preview.kind).toBe('unsupported');
+        expect(preview.message).toMatch(/暂不支持旧版 \.doc/);
+    });
+    it('rejects workspace access through symlink escapes', async () => {
+        const outsideDir = path.join(tempRoot, 'outside');
+        const symlinkPath = path.join(workspacePath, 'outside-link');
+        await fs.mkdir(outsideDir, { recursive: true });
+        await fs.writeFile(path.join(outsideDir, 'secret.txt'), 'secret', 'utf-8');
+        try {
+            await fs.symlink(outsideDir, symlinkPath, 'dir');
+        }
+        catch (error) {
+            const errorCode = typeof error === 'object' && error !== null ? Reflect.get(error, 'code') : undefined;
+            if (errorCode === 'EPERM') {
+                return;
+            }
+            throw error;
+        }
+        await expect(readWorkspaceFile({
+            workspacePath,
+            filePath: path.join(symlinkPath, 'secret.txt')
+        })).rejects.toThrow(/outside workspace/);
+    });
+    it('rejects tar archives with symbolic links', async () => {
+        const archivePath = path.join(workspacePath, 'link.tar');
+        const linkTarget = path.join(tempRoot, 'linked-target');
+        const sourceLink = path.join(tempRoot, 'archive-link');
+        await fs.mkdir(linkTarget, { recursive: true });
+        try {
+            await fs.symlink(linkTarget, sourceLink, 'dir');
+        }
+        catch (error) {
+            const errorCode = typeof error === 'object' && error !== null ? Reflect.get(error, 'code') : undefined;
+            if (errorCode === 'EPERM') {
+                return;
+            }
+            throw error;
+        }
+        await tar.c({ file: archivePath, cwd: tempRoot }, ['archive-link']);
+        await expect(extractWorkspaceArchive({
+            workspacePath,
+            archivePath,
+            outputPath: workspacePath
+        })).rejects.toThrow(/links are not supported/);
+    });
 });

package/dist/services/workspace-watch.d.ts

@@ -0,0 +1,21 @@
+interface WorkspaceFileWatchParams {
+    workspacePath: string;
+    filePath: string;
+}
+/**
+ * 开始监听工作区内单个文件，重复监听同一文件会复用已有 watcher。
+ */
+export declare function watchWorkspaceFile(params: WorkspaceFileWatchParams): Promise<{
+    ok: true;
+    workspacePath: string;
+    filePath: string;
+}>;
+/**
+ * 停止监听工作区内单个文件；未监听时保持幂等。
+ */
+export declare function unwatchWorkspaceFile(params: WorkspaceFileWatchParams): Promise<{
+    ok: true;
+}>;
+export declare function getWorkspaceWatchCountForTests(): number;
+export {};
+//# sourceMappingURL=workspace-watch.d.ts.map

package/dist/services/workspace-watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-watch.d.ts","sourceRoot":"","sources":["../../src/services/workspace-watch.ts"],"names":[],"mappings":"AAKA,UAAU,wBAAwB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAmGD;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAmBzI;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,CAAC,CAUlG;AAED,wBAAgB,8BAA8B,IAAI,MAAM,CAEvD"}

package/dist/services/workspace-watch.js

@@ -0,0 +1,123 @@
+import { watch, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { sendFileChanged } from './session-output.js';
+const watchedFiles = new Map();
+const WATCH_DEBOUNCE_MS = 300;
+function toDisplayPath(targetPath) {
+    return String(targetPath || '').replace(/\\/g, '/');
+}
+function ensureInsideWorkspace(workspaceRoot, targetPath) {
+    const resolvedTargetPath = path.resolve(targetPath);
+    const relativePath = path.relative(workspaceRoot, resolvedTargetPath);
+    if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+        throw new Error(`Target path is outside workspace: ${resolvedTargetPath}`);
+    }
+    return resolvedTargetPath;
+}
+async function resolveWatchTarget(params) {
+    const requestedWorkspaceRoot = path.resolve(String(params.workspacePath || '').trim());
+    const workspaceRoot = await fs.realpath(requestedWorkspaceRoot);
+    const requestedFilePath = path.resolve(String(params.filePath || '').trim());
+    const requestedRelativePath = path.relative(requestedWorkspaceRoot, requestedFilePath);
+    if (requestedRelativePath.startsWith('..') || path.isAbsolute(requestedRelativePath)) {
+        throw new Error(`Target path is outside workspace: ${requestedFilePath}`);
+    }
+    const filePath = ensureInsideWorkspace(workspaceRoot, path.join(workspaceRoot, requestedRelativePath));
+    const realFilePath = await fs.realpath(filePath);
+    ensureInsideWorkspace(workspaceRoot, realFilePath);
+    const stat = await fs.stat(realFilePath);
+    if (!stat.isFile()) {
+        throw new Error(`Path is not a file: ${realFilePath}`);
+    }
+    return { workspaceRoot, filePath: realFilePath };
+}
+function watchKey(workspaceRoot, filePath) {
+    return `${toDisplayPath(workspaceRoot)}::${toDisplayPath(filePath)}`;
+}
+function closeWatchRecord(key, record) {
+    if (record.timer) {
+        clearTimeout(record.timer);
+        record.timer = null;
+    }
+    record.watcher.close();
+    watchedFiles.delete(key);
+}
+async function resolveWatchKey(params) {
+    const requestedWorkspaceRoot = path.resolve(String(params.workspacePath || '').trim());
+    const workspaceRoot = await fs.realpath(requestedWorkspaceRoot);
+    const requestedFilePath = path.resolve(String(params.filePath || '').trim());
+    const requestedRelativePath = path.relative(requestedWorkspaceRoot, requestedFilePath);
+    if (requestedRelativePath.startsWith('..') || path.isAbsolute(requestedRelativePath)) {
+        throw new Error(`Target path is outside workspace: ${requestedFilePath}`);
+    }
+    const filePath = ensureInsideWorkspace(workspaceRoot, path.join(workspaceRoot, requestedRelativePath));
+    return watchKey(workspaceRoot, filePath);
+}
+async function notifyFileChanged(record, eventType) {
+    let size;
+    let mtimeMs;
+    try {
+        const stat = await fs.stat(record.filePath);
+        size = stat.size;
+        mtimeMs = stat.mtimeMs;
+    }
+    catch {
+        // Deletions or transient writes still notify the frontend so it can show a refresh error if needed.
+    }
+    await sendFileChanged({
+        workspacePath: toDisplayPath(record.workspacePath),
+        filePath: toDisplayPath(record.filePath),
+        eventType,
+        size,
+        mtimeMs,
+    });
+}
+function scheduleFileChanged(record, eventType) {
+    if (record.timer) {
+        clearTimeout(record.timer);
+    }
+    record.timer = setTimeout(() => {
+        record.timer = null;
+        notifyFileChanged(record, eventType).catch(() => undefined);
+    }, WATCH_DEBOUNCE_MS);
+}
+/**
+ * 开始监听工作区内单个文件，重复监听同一文件会复用已有 watcher。
+ */
+export async function watchWorkspaceFile(params) {
+    const { workspaceRoot, filePath } = await resolveWatchTarget(params);
+    const key = watchKey(workspaceRoot, filePath);
+    const existingRecord = watchedFiles.get(key);
+    if (existingRecord) {
+        existingRecord.refCount += 1;
+    }
+    else {
+        const record = {
+            watcher: watch(filePath, (eventType) => scheduleFileChanged(record, String(eventType || 'change'))),
+            workspacePath: workspaceRoot,
+            filePath,
+            timer: null,
+            refCount: 1,
+        };
+        record.watcher.on('error', () => closeWatchRecord(key, record));
+        watchedFiles.set(key, record);
+    }
+    return { ok: true, workspacePath: toDisplayPath(workspaceRoot), filePath: toDisplayPath(filePath) };
+}
+/**
+ * 停止监听工作区内单个文件；未监听时保持幂等。
+ */
+export async function unwatchWorkspaceFile(params) {
+    const key = await resolveWatchKey(params);
+    const record = watchedFiles.get(key);
+    if (record) {
+        record.refCount -= 1;
+        if (record.refCount <= 0) {
+            closeWatchRecord(key, record);
+        }
+    }
+    return { ok: true };
+}
+export function getWorkspaceWatchCountForTests() {
+    return watchedFiles.size;
+}

package/dist/services/workspace-watch.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=workspace-watch.test.d.ts.map

package/dist/services/workspace-watch.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-watch.test.d.ts","sourceRoot":"","sources":["../../src/services/workspace-watch.test.ts"],"names":[],"mappings":""}

package/dist/services/workspace-watch.test.js

@@ -0,0 +1,38 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { getWorkspaceWatchCountForTests, unwatchWorkspaceFile, watchWorkspaceFile, } from './workspace-watch.js';
+describe('workspace file watch service', () => {
+    let tempRoot = '';
+    let workspacePath = '';
+    let filePath = '';
+    beforeEach(async () => {
+        tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aws-workspace-watch-'));
+        workspacePath = path.join(tempRoot, 'workspace');
+        filePath = path.join(workspacePath, 'demo.docx');
+        await fs.mkdir(workspacePath, { recursive: true });
+        await fs.writeFile(filePath, 'watch me', 'utf-8');
+    });
+    afterEach(async () => {
+        await unwatchWorkspaceFile({ workspacePath, filePath }).catch(() => undefined);
+        await unwatchWorkspaceFile({ workspacePath, filePath }).catch(() => undefined);
+        await fs.rm(tempRoot, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
+    });
+    it('unwatches a deleted file by its original workspace path key', async () => {
+        await watchWorkspaceFile({ workspacePath, filePath });
+        expect(getWorkspaceWatchCountForTests()).toBe(1);
+        await fs.rm(filePath);
+        await unwatchWorkspaceFile({ workspacePath, filePath });
+        expect(getWorkspaceWatchCountForTests()).toBe(0);
+    });
+    it('keeps shared watchers until all references unwatch', async () => {
+        await watchWorkspaceFile({ workspacePath, filePath });
+        await watchWorkspaceFile({ workspacePath, filePath });
+        expect(getWorkspaceWatchCountForTests()).toBe(1);
+        await unwatchWorkspaceFile({ workspacePath, filePath });
+        expect(getWorkspaceWatchCountForTests()).toBe(1);
+        await unwatchWorkspaceFile({ workspacePath, filePath });
+        expect(getWorkspaceWatchCountForTests()).toBe(0);
+    });
+});