test: add vitest unit tests across packages

Cover shared zod schemas, extract traversal/refs/downloads, and tts filename/error handling. Document the test setup in the README and docs.

packages/extract/src/objects.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import type { TTSMod, TTSObject } from '@tts/shared';
+import { filterObjects, findObject, flattenObjects } from './objects.js';
+
+function card(guid: string, name = 'Card'): TTSObject {
+  return { Name: name, GUID: guid, Description: '' };
+}
+
+function bag(guid: string, contained: TTSObject[]): TTSObject {
+  return { Name: 'Bag', GUID: guid, Description: '', ContainedObjects: contained };
+}
+
+const mod: TTSMod = {
+  GameMode: 'Tabletop',
+  Date: '2024-01-01',
+  ObjectStates: [
+    card('a', 'Deck'),
+    bag('b', [card('c', 'Card'), card('d', 'Token')]),
+    card('e', 'Deck'),
+  ],
+};
+
+describe('flattenObjects', () => {
+  it('returns every object including those inside bags', () => {
+    const guids = flattenObjects(mod).map((o) => o.GUID);
+    expect(guids).toEqual(['a', 'c', 'd', 'e']);
+  });
+
+  it('sets Parent links before returning', () => {
+    const [a, c] = flattenObjects(mod);
+    expect(a!.Parent).toBeUndefined();
+    expect(c!.Parent!.GUID).toBe('b');
+  });
+});
+
+describe('filterObjects', () => {
+  it('filters by predicate', () => {
+    const decks = filterObjects(mod, (o) => o.Name === 'Deck');
+    expect(decks.map((o) => o.GUID)).toEqual(['a', 'e']);
+  });
+});
+
+describe('findObject', () => {
+  it('finds an object by GUID', () => {
+    expect(findObject(mod, 'd')?.Name).toBe('Token');
+  });
+
+  it('returns undefined for a missing GUID', () => {
+    expect(findObject(mod, 'zzz')).toBeUndefined();
+  });
+});