feat(legacy): add PID fallback discovery and shared file upload

Author: GhostTypes

src/api/PrinterDiscovery.test.ts

@@ -286,6 +286,40 @@ describe('PrinterDiscovery', () => {
             expect(result?.status).toBe(PrinterStatus.Error);
         });
 
+        it('should classify an unknown legacy printer by Adventurer 4 PID fallback', () => {
+            const discovery = createDiscovery();
+            const buffer = createLegacyBuffer({
+                name: 'Workshop Printer',
+                productId: 0x001e,
+            });
+
+            const result = discovery['parseLegacyProtocol'](buffer, {
+                address: '10.0.0.101',
+                port: 8899,
+                family: 'IPv4',
+                size: 140,
+            });
+
+            expect(result?.model).toBe(PrinterModel.Adventurer4);
+        });
+
+        it('should classify an unknown legacy printer by Adventurer 3 PID fallback', () => {
+            const discovery = createDiscovery();
+            const buffer = createLegacyBuffer({
+                name: 'Workshop Printer',
+                productId: 0x0008,
+            });
+
+            const result = discovery['parseLegacyProtocol'](buffer, {
+                address: '10.0.0.102',
+                port: 8899,
+                family: 'IPv4',
+                size: 140,
+            });
+
+            expect(result?.model).toBe(PrinterModel.Adventurer3);
+        });
+
         it('should throw InvalidResponseError for undersized buffer', () => {
             const discovery = createDiscovery();
             const buffer = Buffer.alloc(50); // Too small
@@ -369,6 +403,30 @@ describe('PrinterDiscovery', () => {
                 expect(discovery['detectLegacyModel']('AD3')).toBe(PrinterModel.Adventurer3);
             });
 
+            it('should use Adventurer 4 PID as a fallback when the name is unknown', () => {
+                const discovery = createDiscovery();
+                expect(discovery['detectLegacyModel']('Workshop Printer', 0x001e)).toBe(
+                    PrinterModel.Adventurer4
+                );
+            });
+
+            it('should use Adventurer 3 PID as a fallback when the name is unknown', () => {
+                const discovery = createDiscovery();
+                expect(discovery['detectLegacyModel']('Workshop Printer', 0x0008)).toBe(
+                    PrinterModel.Adventurer3
+                );
+            });
+
+            it('should prefer name matches over conflicting PID hints', () => {
+                const discovery = createDiscovery();
+                expect(discovery['detectLegacyModel']('Adventurer 3', 0x001e)).toBe(
+                    PrinterModel.Adventurer3
+                );
+                expect(discovery['detectLegacyModel']('Adventurer 4', 0x0008)).toBe(
+                    PrinterModel.Adventurer4
+                );
+            });
+
             it('should return Unknown for unrecognized models', () => {
                 const discovery = createDiscovery();
                 expect(discovery['detectLegacyModel']('Unknown Printer')).toBe(PrinterModel.Unknown);

src/api/PrinterDiscovery.ts

@@ -44,6 +44,16 @@ const MODERN_PROTOCOL_SIZE = 276;
  */
 const LEGACY_PROTOCOL_SIZE = 140;
 
+/**
+ * Known legacy product IDs observed in firmware/discovery research.
+ *
+ * These are used as hints only when the printer name does not identify the model.
+ */
+const LEGACY_PRODUCT_IDS = {
+    Adventurer3: 0x0008,
+    Adventurer4: 0x001e,
+} as const;
+
 /**
  * EventEmitter-based continuous discovery monitor.
  *
@@ -564,7 +574,7 @@ export class PrinterDiscovery {
         const status = this.mapStatusCode(statusCode);
 
         // Detect model
-        const model = this.detectLegacyModel(name);
+        const model = this.detectLegacyModel(name, productId);
 
         return {
             model,
@@ -619,13 +629,14 @@ export class PrinterDiscovery {
     /**
      * Detects printer model from legacy protocol response.
      *
-     * Uses printer name heuristics for legacy models.
+     * Uses printer name heuristics first, then known PID hints as a fallback.
      *
      * @param name Printer name from response
+     * @param productId Legacy product ID when available
      * @returns Detected printer model
      * @private
      */
-    protected detectLegacyModel(name: string): PrinterModel {
+    protected detectLegacyModel(name: string, productId?: number): PrinterModel {
         const upperName = name.toUpperCase();
 
         if (upperName.includes('ADVENTURER 4') || upperName.includes('ADVENTURER4') || upperName.includes('AD4')) {
@@ -636,6 +647,14 @@ export class PrinterDiscovery {
             return PrinterModel.Adventurer3;
         }
 
+        if (productId === LEGACY_PRODUCT_IDS.Adventurer4) {
+            return PrinterModel.Adventurer4;
+        }
+
+        if (productId === LEGACY_PRODUCT_IDS.Adventurer3) {
+            return PrinterModel.Adventurer3;
+        }
+
         return PrinterModel.Unknown;
     }
 

src/tcpapi/FlashForgeTcpClient.test.ts

@@ -1,8 +1,15 @@
 /**
  * @fileoverview Tests for FlashForgeTcpClient file list parsing logic, validating extraction
- * of filenames from M661 command responses across different printer models.
+ * of filenames from M661 command responses across different printer models and
+ * the shared legacy upload workflow used by Adventurer 3/4-style printers.
  */
+import * as fs from 'node:fs';
+import type * as net from 'node:net';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { EventEmitter } from 'node:events';
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { GCodes } from './client/GCodes';
 import { FlashForgeTcpClient } from './FlashForgeTcpClient';
 
 // Suppress logs (from API files) during tests
@@ -34,6 +41,61 @@ const parseFileListResponse = (response: string): string[] => {
   return result;
 };
 
+const createUploadTestClient = (
+  commandResponses: Record<string, string | null>
+): {
+  client: FlashForgeTcpClient;
+  writes: Array<string | Buffer>;
+} => {
+  const writes: Array<string | Buffer> = [];
+  const mockSocket = new EventEmitter() as net.Socket;
+
+  Object.assign(mockSocket, {
+    destroyed: false,
+    setTimeout: vi.fn(),
+    destroy: vi.fn(() => {
+      Object.assign(mockSocket, { destroyed: true });
+    }),
+    write: vi.fn(
+      (
+        data: string | Buffer,
+        encodingOrCallback?: BufferEncoding | ((error?: Error | null) => void),
+        callbackMaybe?: (error?: Error | null) => void
+      ) => {
+        const callback =
+          typeof encodingOrCallback === 'function' ? encodingOrCallback : callbackMaybe;
+        writes.push(Buffer.isBuffer(data) ? Buffer.from(data) : data);
+        callback?.(null);
+
+        if (!Buffer.isBuffer(data)) {
+          const response = commandResponses[data];
+          if (response !== undefined && response !== null) {
+            setTimeout(() => {
+              mockSocket.emit('data', Buffer.from(response, 'utf8'));
+            }, 0);
+          }
+        }
+
+        return true;
+      }
+    ),
+  });
+
+  // @ts-expect-error access private connect for tests
+  const originalConnect = FlashForgeTcpClient.prototype.connect;
+  // @ts-expect-error inject a mocked socket instead of opening a real TCP connection
+  FlashForgeTcpClient.prototype.connect = function mockConnect(): void {
+    this.socket = mockSocket;
+  };
+
+  const client = new FlashForgeTcpClient('localhost');
+
+  // @ts-expect-error restore private method after client creation
+  FlashForgeTcpClient.prototype.connect = originalConnect;
+
+  return { client, writes };
+};
+
 describe('FlashForgeTcpClient', () => {
   // Mock socket methods
   beforeAll(() => {
@@ -126,4 +188,71 @@ describe('FlashForgeTcpClient', () => {
       expect(result.length).toBe(15);
     });
   });
+
+  describe('uploadFile', () => {
+    it('should upload a legacy file using M28, raw binary data, and M29', async () => {
+      const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ff-api-upload-'));
+      const localFile = path.join(tempDir, 'test-upload.gcode');
+      const fileData = Buffer.from('G28\nG1 X10 Y10\nM104 S200\n', 'utf8');
+      fs.writeFileSync(localFile, fileData);
+
+      const startCommand = `${GCodes.CmdPrepFileUpload.replace('%%size%%', fileData.length.toString()).replace('%%filename%%', 'test-upload.gcode')}\n`;
+      const { client, writes } = createUploadTestClient({
+        [startCommand]: 'CMD M28 Received.\n/data/test-upload.gcode\n',
+        [`${GCodes.CmdCompleteFileUpload}\n`]: 'CMD M29 Received.\n',
+      });
+
+      try {
+        await expect(client.uploadFile(localFile)).resolves.toBe(true);
+      } finally {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+      }
+
+      const textWrites = writes.filter((entry): entry is string => typeof entry === 'string');
+      const binaryWrites = writes.filter((entry): entry is Buffer => Buffer.isBuffer(entry));
+
+      expect(textWrites).toEqual([startCommand, `${GCodes.CmdCompleteFileUpload}\n`]);
+      expect(Buffer.concat(binaryWrites)).toEqual(fileData);
+    });
+
+    it('should normalize legacy prefixes in the requested remote file name', async () => {
+      const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ff-api-upload-'));
+      const localFile = path.join(tempDir, 'local-name.gcode');
+      const fileData = Buffer.from('M105\n', 'utf8');
+      fs.writeFileSync(localFile, fileData);
+
+      const normalizedStartCommand = `${GCodes.CmdPrepFileUpload.replace('%%size%%', fileData.length.toString()).replace('%%filename%%', 'renamed.gx')}\n`;
+      const { client, writes } = createUploadTestClient({
+        [normalizedStartCommand]: 'CMD M28 Received.\n/data/renamed.gx\n',
+        [`${GCodes.CmdCompleteFileUpload}\n`]: 'CMD M29 Received.\n',
+      });
+
+      try {
+        await expect(client.uploadFile(localFile, '/data/renamed.gx')).resolves.toBe(true);
+      } finally {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+      }
+
+      expect(writes[0]).toBe(normalizedStartCommand);
+    });
+
+    it('should fail the upload when M29 reports a size mismatch', async () => {
+      const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ff-api-upload-'));
+      const localFile = path.join(tempDir, 'broken-upload.gcode');
+      const fileData = Buffer.from('G1 X5 Y5\n', 'utf8');
+      fs.writeFileSync(localFile, fileData);
+
+      const startCommand = `${GCodes.CmdPrepFileUpload.replace('%%size%%', fileData.length.toString()).replace('%%filename%%', 'broken-upload.gcode')}\n`;
+      const { client } = createUploadTestClient({
+        [startCommand]: 'CMD M28 Received.\n/data/broken-upload.gcode\n',
+        [`${GCodes.CmdCompleteFileUpload}\n`]: 'CMD M29 Received.\nFile Is Not Available\n',
+      });
+
+      try {
+        await expect(client.uploadFile(localFile)).resolves.toBe(false);
+      } finally {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+  });
 });