Implement ObjectStack protocol specification with Zod schemas and TypeScript interfaces

[Copilot]

Establishes the foundational type system and conventions for the ObjectStack ecosystem. This defines the "Constitution" - shared interfaces, validation schemas, and directory conventions used by ObjectOS, ObjectStudio, ObjectCloud, and third-party plugins.

Core Components

• Manifest Schema (src/schemas/manifest.zod.ts)

  • Zod-first schema with type inference for package configuration
  • Defines package metadata (id, type, version), permissions, menu structure, entity patterns, and extension points
  • Validates app/plugin/driver/module packages

• Plugin Runtime Interface (src/types/plugin.ts)

  • Lifecycle contract: onInstall, onEnable, onDisable
  • PluginContext provides ql (ObjectQLClient), os (ObjectOSKernel), and logger
  • Defines ObjectQL query/mutation interface and kernel event bus

• Directory Conventions (src/constants/paths.ts)

  • Hardcoded paths: src/schemas, src/triggers, src/client/pages, assets
  • Standard files: objectstack.config.ts, src/index.ts
  • Type-safe path constants for runtime and tooling

Usage

import { ManifestSchema, ObjectStackPlugin, PKG_CONVENTIONS } from '@objectstack/spec';

// Validate package manifest
const manifest = ManifestSchema.parse({
  id: 'com.example.crm',
  version: '1.0.0',
  type: 'plugin',
  permissions: ['system.user.read']
});

// Implement plugin
export default function(): ObjectStackPlugin {
  return {
    async onInstall(ctx) { /* setup */ },
    async onEnable(ctx) { /* start */ },
    async onDisable(ctx) { /* cleanup */ }
  };
}

All types include comprehensive TSDoc for IntelliSense. No runtime dependencies except Zod. Universal compatibility (Node.js/Browser/Electron).

Original prompt

---

This section details on the original issue you should resolve

<issue_title>✨ Set up Copilot instructions</issue_title>
<issue_description>📜 ObjectStack Protocol & Specification Context
Role: You are the Chief Architect and Standards Committee for the ObjectStack Ecosystem.
Mission: Define the "Constitution" of the system. You create the interfaces, schemas, and conventions that ensure ObjectOS, ObjectStudio, ObjectCloud, and all third-party Plugins speak the exact same language.
Guiding Principle: "Strict Types, No Logic."
This repository contains NO database connections, NO UI components, and NO runtime business logic. It contains only:

• TypeScript Interfaces (Shared types).
• JSON Schemas / Zod Schemas (Validation rules).
• Constants (Convention configurations).

1. The "Manifest" Standard (Core Responsibility)
   You define what a "Package" looks like in ObjectStack.

• Schema Location: src/schemas/manifest.zod.ts (Export to JSON Schema).
• Key Definition: The ObjectStackManifest interface.
  • id: Unique identifier (e.g., com.example.crm).
  • type: app | plugin | driver | module.
  • permissions: Array of permission strings requested (e.g., ["system.user.read"]).
  • menus: Navigation structure injection.
  • entities: Glob patterns for ObjectQL files (e.g., ["./src/schema/*.gql"]).
  • extensions: Extension points (e.g., contributions to the UI).

2. Directory Conventions (Law of Location)
   You define "Where things must be". Hardcode these paths so CLI and Runtime match perfectly.

• File: src/constants/paths.ts
• Rules:
  • Schemas MUST be in src/schemas.
  • Server triggers MUST be in src/triggers.
  • Client pages MUST be in src/client/pages.
  • Assets MUST be in assets.

3. Runtime Interfaces (The Contract)
   You define the interface that every plugin must implement to be loaded by ObjectOS.

• File: src/types/plugin.ts
• Interface: ObjectStackPlugin
  • onInstall(ctx: PluginContext): Promise
  • onEnable(ctx: PluginContext): Promise
  • onDisable(ctx: PluginContext): Promise
• Context: PluginContext
  • Must expose ql (ObjectQLClient), os (ObjectOSKernel), logger.

4. Coding Rules for AI
   A. Zod First Strategy
   When defining schemas (like the Manifest), ALWAYS use Zod first.

• Why: Zod allows us to infer the TypeScript type (z.infer) AND generate the JSON Schema for the VS Code extension/CLI validator from a single source of truth.
  B. Universal Compatibility
• The code generated here must run in Node.js (CLI/OS), Browser (Studio/UI), and Electron.
• Do not import Node.js specific modules (like fs or path) unless strictly isolated in a standard utility helper. Ideally, keep it pure JS/TS.
  C. Documentation is Code
  Since this is the protocol, every interface property must have TSDoc comments (/** ... */). These comments will power the IntelliSense for third-party developers.

5. Mock Examples (Reference)
   Example: Defining the Manifest Schema (Zod)
   import { z } from 'zod';

export const ManifestSchema = z.object({
id: z.string().describe("Unique package identifier (reverse domain style)"),
version: z.string().regex(/^\d+.\d+.\d+$/),
type: z.enum(['app', 'plugin', 'driver']),
menus: z.array(z.object({
label: z.string(),
path: z.string(),
icon: z.string().optional()
})).optional()
});

export type ObjectStackManifest = z.infer;

Example: Defining Directory Constants
export const PKG_CONVENTIONS = {
// The Source of Truth for where the Engine looks for files
DIRS: {
SCHEMA: 'src/schemas',
SERVER: 'src/server',
CLIENT: 'src/client'
},
FILES: {
MANIFEST: 'objectstack.config.ts',
ENTRY: 'src/index.ts'
}
} as const;</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes ✨ Set up Copilot instructions #2

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.