Merge pull request #63 from objectstack-ai/copilot/sort-src-export-content

huangyiirene · web-flow · commit 97de0930b8da · 2026-01-22T11:31:09.000+08:00
diff --git a/examples/ai-analyst/src/ai-config.d.ts b/examples/ai-analyst/src/ai-config.d.ts
@@ -1,4 +1,4 @@
-import type { Agent, NLQModelConfig, QueryTemplate } from '@objectstack/spec';
+import type { Agent, NLQModelConfig, QueryTemplate } from '@objectstack/spec/ai';
 /**
  * AI Data Analyst Agent
  */
diff --git a/examples/ai-analyst/src/ai-config.ts b/examples/ai-analyst/src/ai-config.ts
@@ -1,4 +1,4 @@
-import type { Agent, NLQModelConfig, QueryTemplate } from '@objectstack/spec';
+import type { Agent, NLQModelConfig, QueryTemplate } from '@objectstack/spec/ai';
 
 /**
  * AI Data Analyst Agent
diff --git a/examples/ai-codegen/src/ai-config.d.ts b/examples/ai-codegen/src/ai-config.d.ts
@@ -1,4 +1,4 @@
-import type { Agent, ModelRegistry, RAGPipelineConfig } from '@objectstack/spec';
+import type { Agent, ModelRegistry, RAGPipelineConfig } from '@objectstack/spec/ai';
 /**
  * ObjectStack Code Generator Agent
  */
diff --git a/examples/ai-codegen/src/ai-config.ts b/examples/ai-codegen/src/ai-config.ts
@@ -1,4 +1,4 @@
-import type { Agent, ModelRegistry, RAGPipelineConfig } from '@objectstack/spec';
+import type { Agent, ModelRegistry, RAGPipelineConfig } from '@objectstack/spec/ai';
 
 /**
  * ObjectStack Code Generator Agent
diff --git a/examples/ai-sales/src/ai-config.d.ts b/examples/ai-sales/src/ai-config.d.ts
@@ -1,4 +1,4 @@
-import type { Agent, ModelRegistry, RAGPipelineConfig } from '@objectstack/spec';
+import type { Agent, ModelRegistry, RAGPipelineConfig } from '@objectstack/spec/ai';
 /**
  * AI Sales Assistant Agent
  */
diff --git a/examples/ai-sales/src/ai-config.ts b/examples/ai-sales/src/ai-config.ts
@@ -1,4 +1,4 @@
-import type { Agent, ModelRegistry, RAGPipelineConfig } from '@objectstack/spec';
+import type { Agent, ModelRegistry, RAGPipelineConfig } from '@objectstack/spec/ai';
 
 /**
  * AI Sales Assistant Agent
diff --git a/examples/ai-support/src/ai-config.d.ts b/examples/ai-support/src/ai-config.d.ts
@@ -1,4 +1,4 @@
-import type { Agent, ModelRegistry, RAGPipelineConfig, FieldSynonymConfig } from '@objectstack/spec';
+import type { Agent, ModelRegistry, RAGPipelineConfig, FieldSynonymConfig } from '@objectstack/spec/ai';
 /**
  * AI Support Assistant - Agent Configuration
  */
diff --git a/examples/ai-support/src/ai-config.ts b/examples/ai-support/src/ai-config.ts
@@ -3,7 +3,7 @@ import type {
   ModelRegistry,
   RAGPipelineConfig,
   FieldSynonymConfig,
-} from '@objectstack/spec';
+} from '@objectstack/spec/ai';
 
 /**
  * AI Support Assistant - Agent Configuration
diff --git a/examples/crm/objectstack.config.ts b/examples/crm/objectstack.config.ts
@@ -1,4 +1,4 @@
-import { App } from '@objectstack/spec';
+import { App } from '@objectstack/spec/ui';
 import { Account } from './src/domains/crm/account.object';
 import { Contact } from './src/domains/crm/contact.object';
 import { Opportunity } from './src/domains/crm/opportunity.object';
diff --git a/examples/crm/src/domains/crm/account.object.ts b/examples/crm/src/domains/crm/account.object.ts
@@ -1,4 +1,4 @@
-import { ObjectSchema, Field } from '@objectstack/spec';
+import { ObjectSchema, Field } from '@objectstack/spec/data';
 
 export const Account = ObjectSchema.create({
   name: 'account',
diff --git a/examples/crm/src/domains/crm/case.object.ts b/examples/crm/src/domains/crm/case.object.ts
@@ -1,4 +1,4 @@
-import { ObjectSchema, Field } from '@objectstack/spec';
+import { ObjectSchema, Field } from '@objectstack/spec/data';
 
 export const Case = ObjectSchema.create({
   name: 'case',
diff --git a/examples/crm/src/domains/crm/contact.object.ts b/examples/crm/src/domains/crm/contact.object.ts
@@ -1,4 +1,4 @@
-import { ObjectSchema, Field } from '@objectstack/spec';
+import { ObjectSchema, Field } from '@objectstack/spec/data';
 
 export const Contact = ObjectSchema.create({
   name: 'contact',
diff --git a/examples/crm/src/domains/crm/lead.object.ts b/examples/crm/src/domains/crm/lead.object.ts
@@ -1,4 +1,4 @@
-import { ObjectSchema, Field } from '@objectstack/spec';
+import { ObjectSchema, Field } from '@objectstack/spec/data';
 
 export const Lead = ObjectSchema.create({
   name: 'lead',
diff --git a/examples/crm/src/domains/crm/opportunity.object.ts b/examples/crm/src/domains/crm/opportunity.object.ts
@@ -1,4 +1,4 @@
-import { ObjectSchema, Field } from '@objectstack/spec';
+import { ObjectSchema, Field } from '@objectstack/spec/data';
 
 export const Opportunity = ObjectSchema.create({
   name: 'opportunity',
diff --git a/examples/crm/src/domains/crm/task.object.ts b/examples/crm/src/domains/crm/task.object.ts
@@ -1,4 +1,4 @@
-import { ObjectSchema, Field } from '@objectstack/spec';
+import { ObjectSchema, Field } from '@objectstack/spec/data';
 
 export const Task = ObjectSchema.create({
   name: 'task',
diff --git a/examples/crm/src/server/apis.ts b/examples/crm/src/server/apis.ts
@@ -1,4 +1,4 @@
-import { ApiEndpoint } from '@objectstack/spec';
+import { ApiEndpoint } from '@objectstack/spec/system';
 
 /**
  * Custom API: Close Won Opportunities
diff --git a/examples/crm/src/ui/actions.d.ts b/examples/crm/src/ui/actions.d.ts
@@ -1,4 +1,4 @@
-import type { Action } from '@objectstack/spec';
+import type { Action } from '@objectstack/spec/ui';
 export declare const ConvertLeadAction: Action;
 export declare const CloneOpportunityAction: Action;
 export declare const MarkPrimaryContactAction: Action;
diff --git a/examples/crm/src/ui/actions.ts b/examples/crm/src/ui/actions.ts
@@ -1,4 +1,4 @@
-import type { Action } from '@objectstack/spec';
+import type { Action } from '@objectstack/spec/ui';
 
 // Convert Lead to Account, Contact, and Opportunity
 export const ConvertLeadAction: Action = {
diff --git a/examples/crm/src/ui/dashboards.d.ts b/examples/crm/src/ui/dashboards.d.ts
@@ -1,4 +1,4 @@
-import type { Dashboard } from '@objectstack/spec';
+import type { Dashboard } from '@objectstack/spec/ui';
 export declare const SalesDashboard: Dashboard;
 export declare const ServiceDashboard: Dashboard;
 export declare const ExecutiveDashboard: Dashboard;
diff --git a/examples/crm/src/ui/dashboards.ts b/examples/crm/src/ui/dashboards.ts
@@ -1,4 +1,4 @@
-import type { Dashboard } from '@objectstack/spec';
+import type { Dashboard } from '@objectstack/spec/ui';
 
 // Sales Performance Dashboard
 export const SalesDashboard: Dashboard = {
diff --git a/examples/crm/src/ui/reports.d.ts b/examples/crm/src/ui/reports.d.ts
@@ -1,4 +1,4 @@
-import type { Report } from '@objectstack/spec';
+import type { Report } from '@objectstack/spec/ui';
 export declare const OpportunitiesByStageReport: Report;
 export declare const WonOpportunitiesByOwnerReport: Report;
 export declare const AccountsByIndustryTypeReport: Report;
diff --git a/examples/crm/src/ui/reports.ts b/examples/crm/src/ui/reports.ts
@@ -1,4 +1,4 @@
-import type { Report } from '@objectstack/spec';
+import type { Report } from '@objectstack/spec/ui';
 
 // Sales Report - Opportunities by Stage
 export const OpportunitiesByStageReport: Report = {
diff --git a/examples/plugin-bi/objectstack.config.d.ts b/examples/plugin-bi/objectstack.config.d.ts
@@ -1,4 +1,4 @@
-import { ObjectStackManifest } from '@objectstack/spec';
+import { ObjectStackManifest } from '@objectstack/spec/system';
 declare const BiPlugin: ObjectStackManifest;
 export default BiPlugin;
 //# sourceMappingURL=objectstack.config.d.ts.map
diff --git a/examples/plugin-bi/objectstack.config.ts b/examples/plugin-bi/objectstack.config.ts
@@ -1,4 +1,4 @@
-import { ObjectStackManifest } from '@objectstack/spec';
+import { ObjectStackManifest } from '@objectstack/spec/system';
 
 const BiPlugin: ObjectStackManifest = {
   id: 'com.objectstack.bi',
diff --git a/examples/plugin-bi/src/index.d.ts b/examples/plugin-bi/src/index.d.ts
@@ -1,4 +1,4 @@
-import { PluginDefinition } from '@objectstack/spec';
+import { PluginDefinition } from '@objectstack/spec/system';
 export declare class BiEngine {
     constructor();
     registerDataset(path: string): void;
diff --git a/examples/plugin-bi/src/index.ts b/examples/plugin-bi/src/index.ts
@@ -1,4 +1,4 @@
-import { PluginDefinition, PluginContextData } from '@objectstack/spec';
+import { PluginDefinition, PluginContextData } from '@objectstack/spec/system';
 
 export class BiEngine {
   constructor() {
diff --git a/examples/todo/objectstack.config.ts b/examples/todo/objectstack.config.ts
@@ -1,4 +1,4 @@
-import { App } from '@objectstack/spec';
+import { App } from '@objectstack/spec/ui';
 import { TodoTask } from './src/domains/todo/task.object';
 
 export default App.create({
diff --git a/examples/todo/src/domains/todo/task.object.ts b/examples/todo/src/domains/todo/task.object.ts
@@ -1,4 +1,4 @@
-import { ObjectSchema, Field } from '@objectstack/spec';
+import { ObjectSchema, Field } from '@objectstack/spec/data';
 
 export const TodoTask = ObjectSchema.create({
   name: 'todo_task',
diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts
@@ -1,4 +1,4 @@
-import { QueryAST, FilterNode, SortNode, AggregationNode, WindowFunctionNode } from '@objectstack/spec';
+import { QueryAST, FilterNode, SortNode, AggregationNode, WindowFunctionNode } from '@objectstack/spec/data';
 
 export interface ClientConfig {
   baseUrl: string;
diff --git a/packages/driver-memory/objectstack.config.ts b/packages/driver-memory/objectstack.config.ts
@@ -1,4 +1,4 @@
-import { ObjectStackManifest } from '@objectstack/spec';
+import { ObjectStackManifest } from '@objectstack/spec/system';
 
 const MemoryDriverPlugin: ObjectStackManifest = {
   id: 'com.objectstack.driver.memory',
diff --git a/packages/driver-memory/src/memory-driver.ts b/packages/driver-memory/src/memory-driver.ts
@@ -1,9 +1,5 @@
-import { 
-  DriverInterface, 
-  DriverOptions, 
-  QueryAST,
-  QueryInput 
-} from '@objectstack/spec';
+import { QueryAST, QueryInput } from '@objectstack/spec/data';
+import { DriverInterface, DriverOptions } from '@objectstack/spec/system';
 
 /**
  * Example: In-Memory Driver
diff --git a/packages/objectql/src/index.ts b/packages/objectql/src/index.ts
@@ -1,4 +1,5 @@
-import { DriverInterface, DriverOptions, QueryAST, ObjectStackManifest } from '@objectstack/spec';
+import { QueryAST } from '@objectstack/spec/data';
+import { DriverInterface, DriverOptions, ObjectStackManifest } from '@objectstack/spec/system';
 import { SchemaRegistry } from './registry';
 
 // Export Registry for consumers
diff --git a/packages/objectql/src/registry.ts b/packages/objectql/src/registry.ts
@@ -1,4 +1,6 @@
-import { ServiceObject, App, ObjectStackManifest } from '@objectstack/spec';
+import { ServiceObject } from '@objectstack/spec/data';
+import { App } from '@objectstack/spec/ui';
+import { ObjectStackManifest } from '@objectstack/spec/system';
 
 /**
  * Global Schema Registry
diff --git a/packages/runtime/src/kernel.ts b/packages/runtime/src/kernel.ts
@@ -1,4 +1,4 @@
-import { ServiceObject } from '@objectstack/spec';
+import { ServiceObject } from '@objectstack/spec/data';
 import { SchemaRegistry, ObjectQL } from '@objectstack/objectql';
 
 /**
diff --git a/packages/spec/README.md b/packages/spec/README.md
@@ -44,12 +44,115 @@ The specification is divided into three protocols:
 
 ## 📚 Usage
 
+### Import Styles
+
+**Important:** This package does NOT export types at the root level to prevent naming conflicts. You must use one of the following import styles:
+
+#### 1. Namespace Imports from Root
+
+Import protocol namespaces from the package root:
+
+```typescript
+import { Data, UI, System, AI, API } from '@objectstack/spec';
+
+const field: Data.Field = {
+  name: 'task_name',
+  type: 'text',
+  label: 'Task Name',
+};
+
+const user: System.User = {
+  id: 'user_123',
+  email: 'user@example.com',
+  // ...
+};
+
+const agent: AI.Agent = {
+  name: 'sales_assistant',
+  // ...
+};
+```
+
+**Pros:**
+- Single import line for multiple protocols
+- Clear namespace boundaries
+- No naming conflicts
+
+#### 2. Namespace Imports via Subpath
+
+Import protocol domains individually:
+
+```typescript
+import * as Data from '@objectstack/spec/data';
+import * as UI from '@objectstack/spec/ui';
+import * as System from '@objectstack/spec/system';
+import * as AI from '@objectstack/spec/ai';
+import * as API from '@objectstack/spec/api';
+
+const field: Data.Field = {
+  name: 'task_name',
+  type: 'text',
+  label: 'Task Name',
+};
+
+const user: System.User = {
+  id: 'user_123',
+  email: 'user@example.com',
+  // ...
+};
+```
+
+**Pros:**
+- Explicit about which protocols are used
+- Better tree-shaking (only imports needed protocols)
+- Clear namespace boundaries
+
+#### 3. Direct Subpath Imports
+
+Import specific types from subpaths:
+
+```typescript
+import { Field, FieldType, ObjectSchema } from '@objectstack/spec/data';
+import { User, Session } from '@objectstack/spec/system';
+import { App, View } from '@objectstack/spec/ui';
+
+const field: Field = {
+  name: 'task_name',
+  type: 'text',
+  label: 'Task Name',
+};
+
+const user: User = {
+  id: 'user_123',
+  email: 'user@example.com',
+  // ...
+};
+```
+
+**Pros:**
+- Most concise syntax
+- Good for importing specific types
+- No namespace prefix needed
+
+**Cons:**
+- Need to know which subpath contains each type
+- Multiple import statements for different protocols
+
 ### Validation (Runtime)
 
 ```typescript
-import { ObjectSchema } from '@objectstack/spec';
+// Style 1: Namespace from root
+import { Data } from '@objectstack/spec';
+const result = Data.ObjectSchema.safeParse(userConfig);
+
+// Style 2: Namespace via subpath
+import * as Data from '@objectstack/spec/data';
+const result = Data.ObjectSchema.safeParse(userConfig);
 
+// Style 3: Direct subpath import
+import { ObjectSchema } from '@objectstack/spec/data';
 const result = ObjectSchema.safeParse(userConfig);
+
 if (!result.success) {
   console.error("Invalid Object definition", result.error);
 }
@@ -58,14 +161,33 @@ if (!result.success) {
 ### Type Definitions (Compile Time)
 
 ```typescript
-import type { Object, Field } from '@objectstack/spec';
+// Style 1: Namespace from root
+import type { Data } from '@objectstack/spec';
+const myField: Data.Field = {
+  name: "task_name",
+  type: "text",
+  label: "Task Name"
+};
 
-const myObject: Object = {
-  name: "project_task",
-  fields: { ... }
+// Style 2: Direct subpath import
+import type { Field } from '@objectstack/spec/data';
+const myField: Field = {
+  name: "task_name",
+  type: "text",
+  label: "Task Name"
 };
 ```
 
+Using namespace imports for multiple protocols:
+
+```typescript
+import type * as Data from '@objectstack/spec/data';
+import type * as System from '@objectstack/spec/system';
+
+const field: Data.Field = { /* ... */ };
+const user: System.User = { /* ... */ };
+```
+
 ### JSON Schema (Tooling)
 The package includes valid JSON Schemas in the `/json-schema` directory.
 These can be used with:
diff --git a/packages/spec/examples/README.md b/packages/spec/examples/README.md
diff --git a/packages/spec/examples/namespaced-imports.example.ts b/packages/spec/examples/namespaced-imports.example.ts
diff --git a/packages/spec/package.json b/packages/spec/package.json
diff --git a/packages/spec/scripts/build-schemas.ts b/packages/spec/scripts/build-schemas.ts
diff --git a/packages/spec/src/ai/index.ts b/packages/spec/src/ai/index.ts
diff --git a/packages/spec/src/api/index.ts b/packages/spec/src/api/index.ts
diff --git a/packages/spec/src/data/index.ts b/packages/spec/src/data/index.ts
diff --git a/packages/spec/src/index.ts b/packages/spec/src/index.ts
diff --git a/packages/spec/src/system/index.ts b/packages/spec/src/system/index.ts
diff --git a/packages/spec/src/ui/index.ts b/packages/spec/src/ui/index.ts

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import type { Agent, NLQModelConfig, QueryTemplate } from '@objectstack/spec';`
	`1`	`+import type { Agent, NLQModelConfig, QueryTemplate } from '@objectstack/spec/ai';`
`2`	`2`	`/**`
`3`	`3`	`* AI Data Analyst Agent`
`4`	`4`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import type { Agent, ModelRegistry, RAGPipelineConfig } from '@objectstack/spec';`
	`1`	`+import type { Agent, ModelRegistry, RAGPipelineConfig } from '@objectstack/spec/ai';`
`2`	`2`	`/**`
`3`	`3`	`* ObjectStack Code Generator Agent`
`4`	`4`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import { App } from '@objectstack/spec';`
	`1`	`+import { App } from '@objectstack/spec/ui';`
`2`	`2`	`import { Account } from './src/domains/crm/account.object';`
`3`	`3`	`import { Contact } from './src/domains/crm/contact.object';`
`4`	`4`	`import { Opportunity } from './src/domains/crm/opportunity.object';`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import { ObjectSchema, Field } from '@objectstack/spec';`
	`1`	`+import { ObjectSchema, Field } from '@objectstack/spec/data';`
`2`	`2`
`3`	`3`	`export const Account = ObjectSchema.create({`
`4`	`4`	`name: 'account',`