Implement ObjectStack protocol specification with Zod schemas and TypeScript interfaces

.gitignore

@@ -19,6 +19,14 @@ Thumbs.db
 # Logs
 *.log
 npm-debug.log*
+
+# Testing
+coverage/
+.nyc_output/
+
+# Temporary files
+*.tmp
+.cache/
 yarn-debug.log*
 yarn-error.log*
 

README.md

@@ -1,3 +1,134 @@
+# @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
 # 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.

package.json

@@ -1,34 +1,32 @@
 {
   "name": "@objectstack/spec",
   "version": "0.1.0",
-  "description": "ObjectStack Protocol & Specification - Type definitions and schemas",
+  "description": "ObjectStack Protocol & Specification - TypeScript Interfaces, JSON Schemas, and Convention Configurations",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": [
-    "dist",
-    "src"
-  ],
   "scripts": {
     "build": "tsc",
+    "dev": "tsc --watch",
     "clean": "rm -rf dist",
-    "changeset": "changeset",
-    "version": "changeset version",
-    "release": "npm run build && changeset publish"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/objectstack-ai/spec.git"
+    "prepublishOnly": "npm run clean && npm run build"
   },
   "keywords": [
     "objectstack",
+    "protocol",
     "specification",
-    "types",
-    "metamodel"
+    "schema",
+    "types"
   ],
   "author": "ObjectStack",
   "license": "MIT",
   "devDependencies": {
-    "@changesets/cli": "^2.29.8",
-    "typescript": "^5.9.3"
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0"
+  },
+  "dependencies": {
+    "zod": "^3.22.4"
+  },
+  "engines": {
+    "node": ">=18.0.0"
   }
 }

src/constants/paths.ts

@@ -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/index.ts

@@ -1,10 +1,42 @@
 /**
- * ObjectStack Specification
+ * @objectstack/spec
  * 
- * This module provides the core type definitions and interfaces for the ObjectStack ecosystem.
- * It defines the contract between backend (ObjectQL) parsers and frontend (ObjectUI) renderers.
+ * ObjectStack Protocol & Specification
  * 
- * @packageDocumentation
+ * 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 * from './types';
+// 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';