Merge branch 'main' into copilot/set-up-copilot-instructions

Author: hotlong

.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
+  "changelog": ["@changesets/cli/changelog", { "repo": "objectstack-ai/spec" }],
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build

.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Create Release Pull Request or Publish to npm
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          publish: npm run release
+          version: npm run version
+          commit: 'chore: version packages'
+          title: 'chore: version packages'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -3,12 +3,14 @@ node_modules/
 
 # Build output
 dist/
+*.tsbuildinfo
 
 # IDE
 .vscode/
 .idea/
 *.swp
 *.swo
+*~
 
 # OS
 .DS_Store
@@ -25,3 +27,12 @@ coverage/
 # Temporary files
 *.tmp
 .cache/
+yarn-debug.log*
+yarn-error.log*
+
+# Testing
+coverage/
+
+# Temporary files
+tmp/
+temp/

README.md

@@ -129,5 +129,157 @@ npm run clean
 ```
 
 ## 📄 License
+# ObjectStack Specification
+
+The ObjectStack Protocol & Specification repository defines the core type definitions and interfaces for the ObjectStack ecosystem. This repository serves as the "Constitution" of the system, providing the contract between backend (ObjectQL) parsers and frontend (ObjectUI) renderers.
+
+## Purpose
+
+This repository contains:
+- **TypeScript Interfaces**: Shared types for the entire ObjectStack ecosystem
+- **No Logic**: Only type definitions, no runtime code or business logic
+- **Universal Compatibility**: Works in Node.js, Browser, and Electron environments
+
+## Metamodel Interfaces
+
+The metamodel defines the structure for describing data models in ObjectStack:
+
+### Core Interfaces
+
+#### `FieldType`
+Defines the available field data types:
+- Text types: `text`, `textarea`, `email`, `url`
+- Numeric types: `number`, `currency`, `percentage`
+- Date/Time types: `date`, `datetime`
+- Relation types: `lookup`
+- Selection types: `select`, `multiselect`
+- Special types: `boolean`, `json`, `file`, `image`
+
+#### `ObjectField`
+Represents a field definition within an entity:
+```typescript
+interface ObjectField {
+  name: string;           // Field identifier
+  label: string;          // Display label
+  type: FieldType;        // Data type
+  required?: boolean;     // Validation
+  unique?: boolean;       // Constraint
+  lookupEntity?: string;  // For lookup fields
+  // ... and more options
+}
+```
+
+#### `ObjectEntity`
+Represents a complete entity (data model) definition:
+```typescript
+interface ObjectEntity {
+  name: string;           // Entity identifier
+  label: string;          // Singular display label
+  pluralLabel: string;    // Plural display label
+  fields: ObjectField[];  // Field definitions
+  primaryKey?: string;    // Primary key field
+  displayField?: string;  // Display field for lookups
+  // ... and more options
+}
+```
+
+#### `ObjectView`
+Represents a view configuration for presenting entity data:
+```typescript
+interface ObjectView {
+  name: string;           // View identifier
+  label: string;          // Display label
+  entityName: string;     // Target entity
+  type: ViewType;         // Presentation type (list, form, detail, etc.)
+  fields?: string[];      // Fields to display
+  columns?: ViewColumn[]; // Column configuration
+  filters?: ViewFilter[]; // Default filters
+  sort?: ViewSort[];      // Default sort order
+  // ... and more options
+}
+```
+
+## Usage
+
+### Installation
+
+```bash
+npm install @objectstack/spec
+```
+
+### Importing Types
+
+```typescript
+// Import all metamodel types
+import { ObjectEntity, ObjectField, ObjectView, FieldType } from '@objectstack/spec';
+
+// Or import specific types
+import type { ObjectEntity } from '@objectstack/spec';
+```
+
+### Example: Defining an Entity
+
+```typescript
+import { ObjectEntity, ObjectField } from '@objectstack/spec';
+
+const userEntity: ObjectEntity = {
+  name: 'User',
+  label: 'User',
+  pluralLabel: 'Users',
+  description: 'System user account',
+  fields: [
+    {
+      name: 'id',
+      label: 'ID',
+      type: 'text',
+      required: true,
+      readonly: true
+    },
+    {
+      name: 'email',
+      label: 'Email',
+      type: 'email',
+      required: true,
+      unique: true
+    },
+    {
+      name: 'name',
+      label: 'Full Name',
+      type: 'text',
+      required: true
+    },
+    {
+      name: 'role',
+      label: 'Role',
+      type: 'select',
+      required: true,
+      options: [
+        { value: 'admin', label: 'Administrator' },
+        { value: 'user', label: 'User' }
+      ]
+    }
+  ],
+  primaryKey: 'id',
+  displayField: 'name'
+};
+```
+
+## Building
+
+```bash
+npm install
+npm run build
+```
+
+This will compile TypeScript files to JavaScript and generate type declarations in the `dist/` directory.
+
+## Philosophy
+
+Following the ObjectStack Protocol:
+- **Strict Types, No Logic**: This repository contains only type definitions
+- **Documentation as Code**: Every interface property has TSDoc comments for IntelliSense
+- **Universal Compatibility**: Pure TypeScript with no platform-specific dependencies
+
+## License
 
 MIT