Merge next into main: replace all files with next branch versions

Author: gavinmcfarland

.cursor/rules/test-location.mdc

@@ -0,0 +1,5 @@
+---
+description: Describes where to write test files
+globs: *.test.ts
+---
+test files are placed in the same folder of the file they test. For example [get-files.test.ts](mdc:plugma/src/tasks/common/get-files.test.ts) is beside [get-files.ts](mdc:plugma/src/tasks/common/get-files.ts)

.cursor/rules/vitest.mdc

@@ -0,0 +1,163 @@
+---
+description: Vitest usage guide
+globs: **/*.test.ts
+---
+ # Vitest Usage Guide
+
+## Basic Test Structure
+
+Tests are organized following these patterns:
+
+~~~typescript
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+describe('Component/Feature Name', () => {
+  // Setup and teardown
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('Specific Aspect', () => {
+    test('should do something specific', () => {
+      // Test implementation
+    });
+  });
+});
+~~~
+
+## Mocking Patterns
+
+### Module Mocking
+
+1. **Hoisted Mocks**: Use `vi.hoisted()` for mocks needed across multiple tests:
+~~~typescript
+const mocks = vi.hoisted(() => ({
+  registerCleanup: vi.fn(),
+  getDirName: vi.fn(),
+}));
+
+vi.mock('#utils/cleanup.js', () => ({
+  registerCleanup: mocks.registerCleanup,
+}));
+~~~
+
+2. **Partial Module Mocks**: Keep original functionality while mocking specific exports:
+~~~typescript
+vi.mock('node:fs', () => ({
+  ...vi.importActual('node:fs'),
+  readFileSync: vi.fn((path) => {
+    // Custom implementation
+  }),
+}));
+~~~
+
+3. **External Module Mocks**: Mock external dependencies:
+~~~typescript
+vi.mock('vite', () => ({
+  createServer: vi.fn(),
+}));
+~~~
+
+### Mock Implementations
+
+1. **Mock Classes**: Create mock implementations for complex objects:
+~~~typescript
+class MockWebSocketServer extends EventEmitter {
+  clients = new Set();
+  close = vi.fn().mockResolvedValue(undefined);
+  // ... other methods
+}
+~~~
+
+2. **Mock Functions**: Use `vi.fn()` with specific implementations:
+~~~typescript
+const mockFn = vi.fn()
+  .mockReturnValue(defaultValue)
+  .mockImplementation((arg) => {
+    // Custom implementation
+  });
+~~~
+
+3. **Async Mocks**: Handle promises in mocks:
+~~~typescript
+mockFunction.mockResolvedValue(value);  // for Promise.resolve
+mockFunction.mockRejectedValue(error);   // for Promise.reject
+~~~
+
+## Testing Patterns
+
+### Cleanup and Reset
+
+1. **Clear Mocks**: Reset all mocks before each test:
+~~~typescript
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+~~~
+
+2. **Mock Reset**: Reset specific mocks:
+~~~typescript
+mockFunction.mockClear();  // Clear usage data
+mockFunction.mockReset();  // Clear usage and implementation
+mockFunction.mockRestore(); // Restore original implementation
+~~~
+
+### Assertions
+
+1. **Function Calls**:
+~~~typescript
+expect(mockFn).toHaveBeenCalled();
+expect(mockFn).toHaveBeenCalledWith(expect.any(Function));
+expect(mockFn).toHaveBeenCalledTimes(1);
+~~~
+
+2. **Objects and Values**:
+~~~typescript
+expect(result).toBe(value);  // Strict equality
+expect(object).toEqual(expected);  // Deep equality
+expect(object).toMatchObject(partial);  // Partial object match
+~~~
+
+3. **Async Tests**:
+~~~typescript
+await expect(asyncFn()).rejects.toThrow('error message');
+await expect(asyncFn()).resolves.toBe(value);
+~~~
+
+### Event Testing
+
+1. **Event Emitters**:
+~~~typescript
+mockServer.emit('connection', mockClient, { url: '?source=test' });
+expect(mockClient.send).toHaveBeenCalledWith(
+  expect.stringContaining('"event":"client_list"')
+);
+~~~
+
+2. **Error Events**:
+~~~typescript
+await expect(
+  () => new Promise((_, reject) => {
+    server.on('error', reject);
+    server.emit('error', new Error('Test error'));
+  })
+).rejects.toThrow('Expected error');
+~~~
+
+## Best Practices
+
+1. **Organize Tests**: Group related tests using nested `describe` blocks
+2. **Mock Isolation**: Use `beforeEach` to reset mocks and state
+3. **Type Safety**: Maintain type safety in mocks using TypeScript interfaces
+4. **Error Cases**: Test both success and error scenarios
+5. **Clear Descriptions**: Use descriptive test names that explain the expected behavior
+6. **Avoid Test Interdependence**: Each test should be independent and not rely on other tests
+
+## Common Gotchas
+
+1. **Async Cleanup**: Always handle async cleanup in tests
+2. **Mock Scope**: Be aware of mock hoisting and scoping rules
+3. **Event Order**: Consider event timing in async tests
+4. **Type Assertions**: Use proper type assertions for mocked objects
+5. **Promise Handling**: Always await promises in async tests
+~~~

.cursorignore

@@ -0,0 +1,2 @@
+# Add directories or file patterns to ignore during indexing (e.g. foo/ or *.csv)
+archive/

.editorconfig

@@ -11,6 +11,6 @@ trim_trailing_whitespace = true
 [*.md]
 trim_trailing_whitespace = false
 
-[*.{json,md,yml}]
+[*.{json,md,yml,yaml}]
 indent_size = 4
-indent_style = space
+indent_style = space

.github/workflows/publish-create-plugma.txt

@@ -23,3 +23,12 @@ dist-ssr
 *.sln
 *.sw?
 .vercel
+
+package-lock.json
+
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*
+vite.config.ui.js.timestamp-*
+vite.config.ui.ts.timestamp-*
+vite.config.main.js.timestamp-*
+vite.config.main.ts.timestamp-*

.gitignore

@@ -0,0 +1,2 @@
+engine-strict=true
+node-linker=hoisted

.npmrc

@@ -0,0 +1 @@
+packages/create-plugma/templates/**

.prettierignore

@@ -1,6 +1,6 @@
 {
 	"useTabs": true,
-	"semi": false,
+	"semi": true,
 	"singleQuote": true,
 	"printWidth": 120,
 	"braceStyle": "collapse,preserve-inline",

.prettierrc

@@ -0,0 +1,59 @@
+# Publishing
+
+This repository uses Lerna for managing and publishing packages. Follow these steps to publish packages:
+
+## Prerequisites
+
+- Node.js >= 20.17.0
+- pnpm >= 9.10.0
+- Lerna (installed as a dev dependency)
+
+## Publishing Steps
+
+1. **Prepare for Publishing**
+
+    - Ensure all changes are committed to the repository
+    - Make sure you have the necessary permissions to publish to npm
+    - Verify you're logged in to npm (`npm whoami`)
+
+2. **Publish the Packages**
+
+    By default, Lerna will publish all packages with the `latest` tag.
+
+    ```bash
+    npx lerna publish
+    ```
+
+    **Or Publish With a Tag**
+
+    ```bash
+    npx lerna publish --dist-tag=next
+    ```
+
+3. **Version Selection**
+
+    - Lerna will prompt you to select a version bump type:
+        - `patch`: For backwards-compatible bug fixes
+        - `minor`: For new backwards-compatible functionality
+        - `major`: For breaking changes
+        - `custom`: To specify a custom version
+    - You can also use `--yes` flag to skip prompts and use the default version bump
+
+4. **Additional Options**
+
+    - To publish only changed packages: `npx lerna publish --since`
+    - To preview changes without publishing: `npx lerna publish --dry-run`
+
+## Troubleshooting
+
+- If you encounter permission issues, ensure you're logged in to npm
+- For package-specific issues, check the individual package's `package.json`
+- If publishing fails, check the npm registry status and your network connection
+
+## Notes
+
+- The repository uses pnpm as the package manager
+- All packages are managed in the `packages/` directory
+- Version numbers are managed centrally through Lerna
+- The version of the `plugma` package used in `create-plugma` is automatically managed by package scripts
+- Investigate if [Changesets](https://github.com/changesets/changesets) would suit this project better