feat: implement DX Phase 2 - branded types, suggestions, error map, strict defineStack

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

Author: Copilot

packages/spec/src/index.ts

@@ -71,6 +71,8 @@ export {
   ObjectOSCapabilitiesSchema
 } from './stack.zod';
 
+export type { DefineStackOptions } from './stack.zod';
+
 export * from './stack.zod';
 
 // DX Helper Functions (re-exported for convenience)
@@ -79,5 +81,9 @@ export { defineApp } from './ui/app.zod';
 export { defineFlow } from './automation/flow.zod';
 export { defineAgent } from './ai/agent.zod';
 
+// DX Validation Utilities (re-exported for convenience)
+export { objectStackErrorMap, formatZodError, formatZodIssue, safeParsePretty } from './shared/error-map.zod';
+export { suggestFieldType, findClosestMatches, formatSuggestion } from './shared/suggestions.zod';
+
 export { type PluginContext } from './kernel/plugin.zod';
 

packages/spec/src/shared/branded-types.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect } from 'vitest';
+import {
+  ObjectNameSchema,
+  FieldNameSchema,
+  ViewNameSchema,
+  AppNameSchema,
+  FlowNameSchema,
+  RoleNameSchema,
+  type ObjectName,
+  type FieldName,
+  type ViewName,
+  type AppName,
+  type FlowName,
+  type RoleName,
+} from './branded-types.zod';
+
+describe('ObjectNameSchema', () => {
+  it('should accept valid snake_case object names', () => {
+    const validNames = ['account', 'project_task', 'crm_lead', 'user_profile'];
+    validNames.forEach((name) => {
+      expect(() => ObjectNameSchema.parse(name)).not.toThrow();
+    });
+  });
+
+  it('should reject dots (not allowed in object names)', () => {
+    expect(() => ObjectNameSchema.parse('user.created')).toThrow();
+  });
+
+  it('should reject uppercase', () => {
+    expect(() => ObjectNameSchema.parse('Account')).toThrow();
+    expect(() => ObjectNameSchema.parse('projectTask')).toThrow();
+  });
+
+  it('should reject too short names', () => {
+    expect(() => ObjectNameSchema.parse('a')).toThrow();
+  });
+
+  it('should produce branded type at runtime', () => {
+    const name: ObjectName = ObjectNameSchema.parse('my_object');
+    expect(name).toBe('my_object');
+  });
+});
+
+describe('FieldNameSchema', () => {
+  it('should accept valid snake_case field names', () => {
+    const validNames = ['first_name', 'created_at', 'total_amount', 'is_active'];
+    validNames.forEach((name) => {
+      expect(() => FieldNameSchema.parse(name)).not.toThrow();
+    });
+  });
+
+  it('should reject dots', () => {
+    expect(() => FieldNameSchema.parse('user.name')).toThrow();
+  });
+
+  it('should reject camelCase', () => {
+    expect(() => FieldNameSchema.parse('firstName')).toThrow();
+  });
+
+  it('should produce branded type at runtime', () => {
+    const name: FieldName = FieldNameSchema.parse('task_name');
+    expect(name).toBe('task_name');
+  });
+});
+
+describe('ViewNameSchema', () => {
+  it('should accept valid system identifiers', () => {
+    const validNames = ['all_tasks', 'my_open_deals', 'contact.recent'];
+    validNames.forEach((name) => {
+      expect(() => ViewNameSchema.parse(name)).not.toThrow();
+    });
+  });
+
+  it('should allow dots (namespacing)', () => {
+    const name: ViewName = ViewNameSchema.parse('contact.recent');
+    expect(name).toBe('contact.recent');
+  });
+
+  it('should reject uppercase', () => {
+    expect(() => ViewNameSchema.parse('AllTasks')).toThrow();
+  });
+});
+
+describe('AppNameSchema', () => {
+  it('should accept valid app names', () => {
+    const validNames = ['crm', 'helpdesk', 'project_management'];
+    validNames.forEach((name) => {
+      expect(() => AppNameSchema.parse(name)).not.toThrow();
+    });
+  });
+
+  it('should produce branded type at runtime', () => {
+    const name: AppName = AppNameSchema.parse('crm');
+    expect(name).toBe('crm');
+  });
+});
+
+describe('FlowNameSchema', () => {
+  it('should accept valid flow names', () => {
+    const validNames = ['approval_flow', 'onboarding_wizard', 'lead_qualification'];
+    validNames.forEach((name) => {
+      expect(() => FlowNameSchema.parse(name)).not.toThrow();
+    });
+  });
+
+  it('should produce branded type at runtime', () => {
+    const name: FlowName = FlowNameSchema.parse('approval_flow');
+    expect(name).toBe('approval_flow');
+  });
+});
+
+describe('RoleNameSchema', () => {
+  it('should accept valid role names', () => {
+    const validNames = ['admin', 'sales_manager', 'read_only'];
+    validNames.forEach((name) => {
+      expect(() => RoleNameSchema.parse(name)).not.toThrow();
+    });
+  });
+
+  it('should produce branded type at runtime', () => {
+    const name: RoleName = RoleNameSchema.parse('admin');
+    expect(name).toBe('admin');
+  });
+});
+
+describe('Branded type safety', () => {
+  it('branded types parse the same underlying strings', () => {
+    const objectName = ObjectNameSchema.parse('my_entity');
+    const fieldName = FieldNameSchema.parse('my_entity');
+    // At runtime both are 'my_entity' strings but TS types differ
+    expect(objectName).toBe('my_entity');
+    expect(fieldName).toBe('my_entity');
+  });
+});

packages/spec/src/shared/branded-types.zod.ts

@@ -0,0 +1,101 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { z } from 'zod';
+import { SnakeCaseIdentifierSchema, SystemIdentifierSchema } from './identifiers.zod';
+
+/**
+ * Branded Types for ObjectStack Identifiers
+ *
+ * Branded types provide compile-time safety by preventing accidental mixing
+ * of different identifier kinds. For example, you cannot pass an ObjectName
+ * where a FieldName is expected, even though both are strings at runtime.
+ *
+ * @example
+ * ```ts
+ * import { ObjectNameSchema, FieldNameSchema } from '@objectstack/spec';
+ *
+ * const objName = ObjectNameSchema.parse('project_task');   // ObjectName
+ * const fieldName = FieldNameSchema.parse('task_name');     // FieldName
+ *
+ * // TypeScript will catch this at compile time:
+ * // const fn: FieldName = objName; // Error!
+ * ```
+ */
+
+/**
+ * ObjectName — Branded type for business object names.
+ *
+ * Must be snake_case (no dots). Used for table/collection names.
+ *
+ * @example 'project_task', 'crm_account', 'user_profile'
+ */
+export const ObjectNameSchema = SnakeCaseIdentifierSchema
+  .brand<'ObjectName'>()
+  .describe('Branded object name (snake_case, no dots)');
+
+export type ObjectName = z.infer<typeof ObjectNameSchema>;
+
+/**
+ * FieldName — Branded type for field (column) names.
+ *
+ * Must be snake_case (no dots). Used for column/property names within objects.
+ *
+ * @example 'first_name', 'created_at', 'total_amount'
+ */
+export const FieldNameSchema = SnakeCaseIdentifierSchema
+  .brand<'FieldName'>()
+  .describe('Branded field name (snake_case, no dots)');
+
+export type FieldName = z.infer<typeof FieldNameSchema>;
+
+/**
+ * ViewName — Branded type for view identifiers.
+ *
+ * Must be a valid system identifier (lowercase, may contain dots for namespacing).
+ *
+ * @example 'all_tasks', 'my_open_deals', 'contact.recent'
+ */
+export const ViewNameSchema = SystemIdentifierSchema
+  .brand<'ViewName'>()
+  .describe('Branded view name (system identifier)');
+
+export type ViewName = z.infer<typeof ViewNameSchema>;
+
+/**
+ * AppName — Branded type for application identifiers.
+ *
+ * Must be a valid system identifier.
+ *
+ * @example 'crm', 'helpdesk', 'project_management'
+ */
+export const AppNameSchema = SystemIdentifierSchema
+  .brand<'AppName'>()
+  .describe('Branded app name (system identifier)');
+
+export type AppName = z.infer<typeof AppNameSchema>;
+
+/**
+ * FlowName — Branded type for flow identifiers.
+ *
+ * Must be a valid system identifier.
+ *
+ * @example 'approval_flow', 'onboarding_wizard', 'lead_qualification'
+ */
+export const FlowNameSchema = SystemIdentifierSchema
+  .brand<'FlowName'>()
+  .describe('Branded flow name (system identifier)');
+
+export type FlowName = z.infer<typeof FlowNameSchema>;
+
+/**
+ * RoleName — Branded type for role identifiers.
+ *
+ * Must be a valid system identifier.
+ *
+ * @example 'admin', 'sales_manager', 'read_only'
+ */
+export const RoleNameSchema = SystemIdentifierSchema
+  .brand<'RoleName'>()
+  .describe('Branded role name (system identifier)');
+
+export type RoleName = z.infer<typeof RoleNameSchema>;