Skip to content

Commit a116aef

Browse files
huangyiirenehuangyiirene
authored
Merge pull request #3 from objectstack-ai/copilot/set-up-copilot-instructions
2 parents f046f0c + 802d03a commit a116aef

8 files changed

Lines changed: 505 additions & 23 deletions

File tree

‎.gitignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,14 @@ Thumbs.db
1919
# Logs
2020
*.log
2121
npm-debug.log*
22+
23+
# Testing
24+
coverage/
25+
.nyc_output/
26+
27+
# Temporary files
28+
*.tmp
29+
.cache/
2230
yarn-debug.log*
2331
yarn-error.log*
2432

‎README.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,134 @@
1+
# @objectstack/spec
2+
3+
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5+
6+
> ObjectStack Protocol & Specification - The Constitution of the ObjectStack Ecosystem
7+
8+
## 📜 Overview
9+
10+
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.
11+
12+
**Guiding Principle:** *"Strict Types, No Logic"*
13+
14+
This package contains:
15+
- ✅ TypeScript Interfaces (Shared types)
16+
- ✅ Zod Schemas (Validation rules with type inference)
17+
- ✅ Constants (Convention configurations)
18+
19+
This package does NOT contain:
20+
- ❌ Database connections
21+
- ❌ UI components
22+
- ❌ Runtime business logic
23+
24+
## 🚀 Installation
25+
26+
```bash
27+
npm install @objectstack/spec
28+
```
29+
30+
## 📦 What's Inside
31+
32+
### 1. Manifest Schema (`ManifestSchema`)
33+
34+
Defines the structure of a package configuration file. All packages (apps, plugins, drivers, modules) must conform to this schema.
35+
36+
```typescript
37+
import { ManifestSchema, type ObjectStackManifest } from '@objectstack/spec';
38+
39+
// Validate a manifest
40+
const manifest: ObjectStackManifest = {
41+
id: 'com.example.myapp',
42+
version: '1.0.0',
43+
type: 'plugin',
44+
name: 'My App',
45+
permissions: ['system.user.read'],
46+
menus: [
47+
{ label: 'Dashboard', path: '/dashboard', icon: 'home' }
48+
]
49+
};
50+
51+
// Validate with Zod
52+
ManifestSchema.parse(manifest);
53+
```
54+
55+
### 2. Plugin Runtime Interface (`ObjectStackPlugin`)
56+
57+
Defines the contract that every plugin must implement to be loaded by ObjectOS.
58+
59+
```typescript
60+
import { ObjectStackPlugin, PluginContext } from '@objectstack/spec';
61+
62+
export default function createPlugin(): ObjectStackPlugin {
63+
return {
64+
async onInstall(ctx: PluginContext) {
65+
ctx.logger.info('Plugin installed');
66+
},
67+
68+
async onEnable(ctx: PluginContext) {
69+
ctx.logger.info('Plugin enabled');
70+
},
71+
72+
async onDisable(ctx: PluginContext) {
73+
ctx.logger.info('Plugin disabled');
74+
}
75+
};
76+
}
77+
```
78+
79+
### 3. Directory Conventions (`PKG_CONVENTIONS`)
80+
81+
Defines the "Law of Location" - where things must be in ObjectStack packages.
82+
83+
```typescript
84+
import { PKG_CONVENTIONS } from '@objectstack/spec';
85+
86+
console.log(PKG_CONVENTIONS.DIRS.SCHEMA); // 'src/schemas'
87+
console.log(PKG_CONVENTIONS.DIRS.TRIGGERS); // 'src/triggers'
88+
console.log(PKG_CONVENTIONS.FILES.MANIFEST); // 'objectstack.config.ts'
89+
```
90+
91+
## 📚 API Reference
92+
93+
### Schemas
94+
95+
- `ManifestSchema` - Zod schema for package manifests
96+
- `MenuItemSchema` - Zod schema for menu items
97+
- `ObjectStackManifest` - TypeScript type for manifests
98+
- `MenuItem` - TypeScript type for menu items
99+
100+
### Types
101+
102+
- `ObjectStackPlugin` - Plugin interface with lifecycle methods
103+
- `PluginContext` - Context provided to plugin methods
104+
- `PluginFactory` - Plugin factory function type
105+
- `PluginLogger` - Logger interface
106+
- `ObjectQLClient` - Database client interface
107+
- `ObjectOSKernel` - OS kernel interface
108+
109+
### Constants
110+
111+
- `PKG_CONVENTIONS` - Directory and file conventions
112+
- `PackageDirectory` - Type for package directories
113+
- `PackageFile` - Type for package files
114+
115+
## 🏗️ Development
116+
117+
```bash
118+
# Install dependencies
119+
npm install
120+
121+
# Build the project
122+
npm run build
123+
124+
# Watch mode for development
125+
npm run dev
126+
127+
# Clean build artifacts
128+
npm run clean
129+
```
130+
131+
## 📄 License
1132
# ObjectStack Specification
2133

3134
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‎

Lines changed: 14 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,32 @@
11
{
22
"name": "@objectstack/spec",
33
"version": "0.1.0",
4-
"description": "ObjectStack Protocol & Specification - Type definitions and schemas",
4+
"description": "ObjectStack Protocol & Specification - TypeScript Interfaces, JSON Schemas, and Convention Configurations",
55
"main": "dist/index.js",
66
"types": "dist/index.d.ts",
7-
"files": [
8-
"dist",
9-
"src"
10-
],
117
"scripts": {
128
"build": "tsc",
9+
"dev": "tsc --watch",
1310
"clean": "rm -rf dist",
14-
"changeset": "changeset",
15-
"version": "changeset version",
16-
"release": "npm run build && changeset publish"
17-
},
18-
"repository": {
19-
"type": "git",
20-
"url": "https://github.com/objectstack-ai/spec.git"
11+
"prepublishOnly": "npm run clean && npm run build"
2112
},
2213
"keywords": [
2314
"objectstack",
15+
"protocol",
2416
"specification",
25-
"types",
26-
"metamodel"
17+
"schema",
18+
"types"
2719
],
2820
"author": "ObjectStack",
2921
"license": "MIT",
3022
"devDependencies": {
31-
"@changesets/cli": "^2.29.8",
32-
"typescript": "^5.9.3"
23+
"@types/node": "^20.10.0",
24+
"typescript": "^5.3.0"
25+
},
26+
"dependencies": {
27+
"zod": "^3.22.4"
28+
},
29+
"engines": {
30+
"node": ">=18.0.0"
3331
}
3432
}

‎src/constants/paths.ts‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
/**
2+
* Package conventions and directory structure constants.
3+
* These define the "Law of Location" - where things must be in ObjectStack packages.
4+
*
5+
* These paths are the source of truth used by:
6+
* - ObjectOS Runtime (to locate package components)
7+
* - ObjectStack CLI (to scaffold and validate packages)
8+
* - ObjectStudio IDE (to provide intelligent navigation and validation)
9+
*/
10+
export const PKG_CONVENTIONS = {
11+
/**
12+
* Standard directories within ObjectStack packages.
13+
* All packages MUST follow these conventions for the runtime to locate resources.
14+
*/
15+
DIRS: {
16+
/**
17+
* Location for schema definitions (Zod schemas, JSON schemas).
18+
* Path: src/schemas
19+
*/
20+
SCHEMA: 'src/schemas',
21+
22+
/**
23+
* Location for server-side code and triggers.
24+
* Path: src/server
25+
*/
26+
SERVER: 'src/server',
27+
28+
/**
29+
* Location for server-side trigger functions.
30+
* Path: src/triggers
31+
*/
32+
TRIGGERS: 'src/triggers',
33+
34+
/**
35+
* Location for client-side code.
36+
* Path: src/client
37+
*/
38+
CLIENT: 'src/client',
39+
40+
/**
41+
* Location for client-side page components.
42+
* Path: src/client/pages
43+
*/
44+
PAGES: 'src/client/pages',
45+
46+
/**
47+
* Location for static assets (images, fonts, etc.).
48+
* Path: assets
49+
*/
50+
ASSETS: 'assets',
51+
},
52+
53+
/**
54+
* Standard file names within ObjectStack packages.
55+
*/
56+
FILES: {
57+
/**
58+
* Package manifest configuration file.
59+
* File: objectstack.config.ts
60+
*/
61+
MANIFEST: 'objectstack.config.ts',
62+
63+
/**
64+
* Main entry point for the package.
65+
* File: src/index.ts
66+
*/
67+
ENTRY: 'src/index.ts',
68+
},
69+
} as const;
70+
71+
/**
72+
* Type helper to extract directory path values.
73+
*/
74+
export type PackageDirectory = typeof PKG_CONVENTIONS.DIRS[keyof typeof PKG_CONVENTIONS.DIRS];
75+
76+
/**
77+
* Type helper to extract file path values.
78+
*/
79+
export type PackageFile = typeof PKG_CONVENTIONS.FILES[keyof typeof PKG_CONVENTIONS.FILES];

‎src/index.ts‎

Lines changed: 37 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,42 @@
11
/**
2-
* ObjectStack Specification
2+
* @objectstack/spec
33
*
4-
* This module provides the core type definitions and interfaces for the ObjectStack ecosystem.
5-
* It defines the contract between backend (ObjectQL) parsers and frontend (ObjectUI) renderers.
4+
* ObjectStack Protocol & Specification
65
*
7-
* @packageDocumentation
6+
* This package contains the core interfaces, schemas, and conventions for the ObjectStack ecosystem.
7+
* It defines the "Constitution" of the system - the shared language that ObjectOS, ObjectStudio,
8+
* ObjectCloud, and all third-party plugins use to communicate.
9+
*
10+
* This package contains:
11+
* - TypeScript Interfaces (Shared types)
12+
* - Zod Schemas (Validation rules with type inference)
13+
* - Constants (Convention configurations)
14+
*
15+
* Guiding Principle: "Strict Types, No Logic"
16+
* This package has NO database connections, NO UI components, and NO runtime business logic.
817
*/
918

10-
export * from './types';
19+
// Export schemas
20+
export {
21+
ManifestSchema,
22+
MenuItemSchema,
23+
type ObjectStackManifest,
24+
type MenuItem,
25+
} from './schemas/manifest.zod';
26+
27+
// Export types
28+
export {
29+
type ObjectStackPlugin,
30+
type PluginContext,
31+
type PluginFactory,
32+
type PluginLogger,
33+
type ObjectQLClient,
34+
type ObjectOSKernel,
35+
} from './types/plugin';
36+
37+
// Export constants
38+
export {
39+
PKG_CONVENTIONS,
40+
type PackageDirectory,
41+
type PackageFile,
42+
} from './constants/paths';

0 commit comments

Comments
 (0)