feat: implement ObjectStack spec with schemas, types, and conventions

Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>

Author: Copilot

.gitignore

@@ -0,0 +1,27 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+
+# Testing
+coverage/
+.nyc_output/
+
+# Temporary files
+*.tmp
+.cache/

README.md

@@ -1 +1,133 @@
-# spec
+# @objectstack/spec
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> ObjectStack Protocol & Specification - The Constitution of the ObjectStack Ecosystem
+
+## 📜 Overview
+
+This package defines the **core interfaces, schemas, and conventions** for the ObjectStack ecosystem. It serves as the "Constitution" - the shared language that ObjectOS, ObjectStudio, ObjectCloud, and all third-party plugins use to communicate.
+
+**Guiding Principle:** *"Strict Types, No Logic"*
+
+This package contains:
+- ✅ TypeScript Interfaces (Shared types)
+- ✅ Zod Schemas (Validation rules with type inference)
+- ✅ Constants (Convention configurations)
+
+This package does NOT contain:
+- ❌ Database connections
+- ❌ UI components
+- ❌ Runtime business logic
+
+## 🚀 Installation
+
+```bash
+npm install @objectstack/spec
+```
+
+## 📦 What's Inside
+
+### 1. Manifest Schema (`ManifestSchema`)
+
+Defines the structure of a package configuration file. All packages (apps, plugins, drivers, modules) must conform to this schema.
+
+```typescript
+import { ManifestSchema, type ObjectStackManifest } from '@objectstack/spec';
+
+// Validate a manifest
+const manifest: ObjectStackManifest = {
+  id: 'com.example.myapp',
+  version: '1.0.0',
+  type: 'plugin',
+  name: 'My App',
+  permissions: ['system.user.read'],
+  menus: [
+    { label: 'Dashboard', path: '/dashboard', icon: 'home' }
+  ]
+};
+
+// Validate with Zod
+ManifestSchema.parse(manifest);
+```
+
+### 2. Plugin Runtime Interface (`ObjectStackPlugin`)
+
+Defines the contract that every plugin must implement to be loaded by ObjectOS.
+
+```typescript
+import { ObjectStackPlugin, PluginContext } from '@objectstack/spec';
+
+export default function createPlugin(): ObjectStackPlugin {
+  return {
+    async onInstall(ctx: PluginContext) {
+      ctx.logger.info('Plugin installed');
+    },
+    
+    async onEnable(ctx: PluginContext) {
+      ctx.logger.info('Plugin enabled');
+    },
+    
+    async onDisable(ctx: PluginContext) {
+      ctx.logger.info('Plugin disabled');
+    }
+  };
+}
+```
+
+### 3. Directory Conventions (`PKG_CONVENTIONS`)
+
+Defines the "Law of Location" - where things must be in ObjectStack packages.
+
+```typescript
+import { PKG_CONVENTIONS } from '@objectstack/spec';
+
+console.log(PKG_CONVENTIONS.DIRS.SCHEMA);    // 'src/schemas'
+console.log(PKG_CONVENTIONS.DIRS.TRIGGERS);  // 'src/triggers'
+console.log(PKG_CONVENTIONS.FILES.MANIFEST); // 'objectstack.config.ts'
+```
+
+## 📚 API Reference
+
+### Schemas
+
+- `ManifestSchema` - Zod schema for package manifests
+- `MenuItemSchema` - Zod schema for menu items
+- `ObjectStackManifest` - TypeScript type for manifests
+- `MenuItem` - TypeScript type for menu items
+
+### Types
+
+- `ObjectStackPlugin` - Plugin interface with lifecycle methods
+- `PluginContext` - Context provided to plugin methods
+- `PluginFactory` - Plugin factory function type
+- `PluginLogger` - Logger interface
+- `ObjectQLClient` - Database client interface
+- `ObjectOSKernel` - OS kernel interface
+
+### Constants
+
+- `PKG_CONVENTIONS` - Directory and file conventions
+- `PackageDirectory` - Type for package directories
+- `PackageFile` - Type for package files
+
+## 🏗️ Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Watch mode for development
+npm run dev
+
+# Clean build artifacts
+npm run clean
+```
+
+## 📄 License
+
+MIT

package-lock.json

@@ -0,0 +1,32 @@
+{
+  "name": "@objectstack/spec",
+  "version": "0.1.0",
+  "description": "ObjectStack Protocol & Specification - TypeScript Interfaces, JSON Schemas, and Convention Configurations",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "objectstack",
+    "protocol",
+    "specification",
+    "schema",
+    "types"
+  ],
+  "author": "ObjectStack",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0"
+  },
+  "dependencies": {
+    "zod": "^3.22.4"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package.json

@@ -0,0 +1,79 @@
+/**
+ * Package conventions and directory structure constants.
+ * These define the "Law of Location" - where things must be in ObjectStack packages.
+ * 
+ * These paths are the source of truth used by:
+ * - ObjectOS Runtime (to locate package components)
+ * - ObjectStack CLI (to scaffold and validate packages)
+ * - ObjectStudio IDE (to provide intelligent navigation and validation)
+ */
+export const PKG_CONVENTIONS = {
+  /**
+   * Standard directories within ObjectStack packages.
+   * All packages MUST follow these conventions for the runtime to locate resources.
+   */
+  DIRS: {
+    /** 
+     * Location for schema definitions (Zod schemas, JSON schemas).
+     * Path: src/schemas
+     */
+    SCHEMA: 'src/schemas',
+    
+    /** 
+     * Location for server-side code and triggers.
+     * Path: src/server
+     */
+    SERVER: 'src/server',
+    
+    /** 
+     * Location for server-side trigger functions.
+     * Path: src/triggers
+     */
+    TRIGGERS: 'src/triggers',
+    
+    /** 
+     * Location for client-side code.
+     * Path: src/client
+     */
+    CLIENT: 'src/client',
+    
+    /** 
+     * Location for client-side page components.
+     * Path: src/client/pages
+     */
+    PAGES: 'src/client/pages',
+    
+    /** 
+     * Location for static assets (images, fonts, etc.).
+     * Path: assets
+     */
+    ASSETS: 'assets',
+  },
+  
+  /**
+   * Standard file names within ObjectStack packages.
+   */
+  FILES: {
+    /** 
+     * Package manifest configuration file.
+     * File: objectstack.config.ts
+     */
+    MANIFEST: 'objectstack.config.ts',
+    
+    /** 
+     * Main entry point for the package.
+     * File: src/index.ts
+     */
+    ENTRY: 'src/index.ts',
+  },
+} as const;
+
+/**
+ * Type helper to extract directory path values.
+ */
+export type PackageDirectory = typeof PKG_CONVENTIONS.DIRS[keyof typeof PKG_CONVENTIONS.DIRS];
+
+/**
+ * Type helper to extract file path values.
+ */
+export type PackageFile = typeof PKG_CONVENTIONS.FILES[keyof typeof PKG_CONVENTIONS.FILES];

src/constants/paths.ts

@@ -0,0 +1,42 @@
+/**
+ * @objectstack/spec
+ * 
+ * ObjectStack Protocol & Specification
+ * 
+ * This package contains the core interfaces, schemas, and conventions for the ObjectStack ecosystem.
+ * It defines the "Constitution" of the system - the shared language that ObjectOS, ObjectStudio,
+ * ObjectCloud, and all third-party plugins use to communicate.
+ * 
+ * This package contains:
+ * - TypeScript Interfaces (Shared types)
+ * - Zod Schemas (Validation rules with type inference)
+ * - Constants (Convention configurations)
+ * 
+ * Guiding Principle: "Strict Types, No Logic"
+ * This package has NO database connections, NO UI components, and NO runtime business logic.
+ */
+
+// Export schemas
+export {
+  ManifestSchema,
+  MenuItemSchema,
+  type ObjectStackManifest,
+  type MenuItem,
+} from './schemas/manifest.zod';
+
+// Export types
+export {
+  type ObjectStackPlugin,
+  type PluginContext,
+  type PluginFactory,
+  type PluginLogger,
+  type ObjectQLClient,
+  type ObjectOSKernel,
+} from './types/plugin';
+
+// Export constants
+export {
+  PKG_CONVENTIONS,
+  type PackageDirectory,
+  type PackageFile,
+} from './constants/paths';