docs: add error-handling guide, sideEffects:false to 24 packages, create tests, update roadmap status

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

docs/ROADMAP_NEXT_PHASE.md

@@ -1,6 +1,6 @@
 # ObjectQL — Next Phase Optimization & Improvement Roadmap
 
-> Created: 2026-02-09 | Status: **Proposed**
+> Created: 2026-02-09 | Status: **In Progress — Phases 1, 3, 4 (Wave 1-2), 5A, 6 (partial), 7 (partial) Complete**
 > Current Version: **4.2.0** | @objectstack Platform: **v2.0.1**
 > Scope: Code quality, type safety, error handling, testing, performance, and DX improvements
 
@@ -135,9 +135,9 @@ type PluginErrorCode =
 ```
 
 **Success Criteria:**
-- [ ] Zero `throw new Error(` in `packages/` (excluding test files)
-- [ ] All error codes documented in `@objectql/types`
-- [ ] Existing tests still pass after migration
+- [x] Zero `throw new Error(` in `packages/` (excluding test files)
+- [x] All error codes documented in `@objectql/types`
+- [x] Existing tests still pass after migration
 
 ### 1B. Reduce `any` type usage
 

packages/tools/create/__tests__/scaffolding.test.ts

@@ -0,0 +1,80 @@
+/**
+ * @objectql/create — Scaffolding output tests
+ *
+ * Verifies that the create-objectql templates exist and produce valid projects.
+ */
+import { describe, it, expect } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const TEMPLATES_DIR = path.resolve(__dirname, '../templates');
+
+const EXPECTED_TEMPLATES = ['hello-world', 'starter', 'enterprise'];
+
+describe('@objectql/create templates', () => {
+    it('should have all expected template directories', () => {
+        for (const template of EXPECTED_TEMPLATES) {
+            const templatePath = path.join(TEMPLATES_DIR, template);
+            expect(fs.existsSync(templatePath), `Template "${template}" should exist at ${templatePath}`).toBe(true);
+        }
+    });
+
+    for (const template of EXPECTED_TEMPLATES) {
+        describe(`${template} template`, () => {
+            const templatePath = path.join(TEMPLATES_DIR, template);
+
+            it('should contain a package.json', () => {
+                const pkgPath = path.join(templatePath, 'package.json');
+                expect(fs.existsSync(pkgPath)).toBe(true);
+
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+                expect(pkg.name).toBeDefined();
+                expect(pkg.dependencies || pkg.devDependencies).toBeDefined();
+            });
+
+            it('should contain a tsconfig.json', () => {
+                const tsconfigPath = path.join(templatePath, 'tsconfig.json');
+                expect(fs.existsSync(tsconfigPath)).toBe(true);
+            });
+
+            it('should contain a src directory with entry point', () => {
+                const srcDir = path.join(templatePath, 'src');
+                expect(fs.existsSync(srcDir)).toBe(true);
+
+                // Check for at least one .ts file in src
+                const srcFiles = fs.readdirSync(srcDir, { recursive: true }) as string[];
+                const tsFiles = srcFiles.filter(f => String(f).endsWith('.ts'));
+                expect(tsFiles.length).toBeGreaterThan(0);
+            });
+
+            it('should contain objectstack.config.ts or objectql config', () => {
+                const srcDir = path.join(templatePath, 'src');
+                const rootFiles = fs.readdirSync(templatePath);
+                const srcFiles = fs.existsSync(srcDir) ? fs.readdirSync(srcDir) : [];
+                const allFiles = [...rootFiles, ...srcFiles];
+
+                const hasConfig = allFiles.some(f =>
+                    String(f).includes('objectstack.config') ||
+                    String(f).includes('objectql.config') ||
+                    String(f).includes('index.ts')
+                );
+                expect(hasConfig).toBe(true);
+            });
+
+            it('should have workspace:* dependencies for @objectql packages', () => {
+                const pkgPath = path.join(templatePath, 'package.json');
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+                const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+                const objectqlDeps = Object.entries(allDeps).filter(
+                    ([key]) => key.startsWith('@objectql/') || key.startsWith('@objectstack/')
+                );
+
+                // Templates in the monorepo should use workspace:* references
+                for (const [name, version] of objectqlDeps) {
+                    expect(version, `${name} should use workspace:* in template`).toBe('workspace:*');
+                }
+            });
+        });
+    }
+});

packages/tools/create/package.json

@@ -11,7 +11,8 @@
   ],
   "scripts": {
     "build": "tsc && node scripts/copy-templates.js",
-    "copy-templates": "node scripts/copy-templates.js"
+    "copy-templates": "node scripts/copy-templates.js",
+    "test": "vitest run"
   },
   "dependencies": {
     "chalk": "^4.1.2",
@@ -24,4 +25,4 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0"
   }
-}
+}