Skip to content

Commit 11fa3a4

Browse files
hotlonghotlong
committed
feat(docs): Add AI Development Context sections to README files across multiple packages
1 parent c248656 commit 11fa3a4

13 files changed

Lines changed: 140 additions & 0 deletions

File tree

‎README_AI_UPDATES.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Package Documentation Updates
2+
3+
I have scanned all packages in the workspace and updated their `README.md` files with a new **"AI Development Context"** section. This section provides high-level guidance for AI agents (and human developers) on the role, usage, and architectural context of each package.
4+
5+
## Core Packages
6+
7+
| Package | Role | AI Context Added |
8+
| :--- | :--- | :--- |
9+
| `@objectstack/spec` | Protocol Definitions | Source of Truth for Zod schemas & types. No business logic. |
10+
| `@objectstack/core` | Microkernel | Bootstrap mechanism, plugin lifecycle, dependency injection. |
11+
| `@objectstack/objectql` | Data Engine | "Backend Brain" for data operations. |
12+
| `@objectstack/runtime` | Server Runtime | REST API generation & HTTP configuration. |
13+
| `@objectstack/client` | Client SDK | Browser/Node SDK for consuming APIs. |
14+
| `@objectstack/client-react` | React Bindings | Hooks for React apps (`useQuery`, etc.). |
15+
| `@objectstack/metadata` | Metadata IO | Loading/saving `.object.ts` files & caching. |
16+
| `@objectstack/cli` | Tooling | Dev server, compilation, project scaffolding. |
17+
| `@objectstack/types` | Shared Types | Common interfaces to prevent circular dependencies. |
18+
19+
## Plugin Packages
20+
21+
| Package | Role | AI Context Added |
22+
| :--- | :--- | :--- |
23+
| `@objectstack/driver-memory` | Reference Driver | In-memory storage for testing. Volatile. |
24+
| `@objectstack/plugin-hono-server` | Hono Adapter | Edge-compatible HTTP server replacement. |
25+
| `@objectstack/plugin-msw` | Test Mocking | Network interception for testing. |
26+
27+
These updates ensure that any AI analyzing this codebase will immediately understand the dependencies and responsibilities of each module.

‎packages/cli/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,14 @@ Command Line Interface for ObjectStack Protocol - Development tools for building
1111
- 🧪 **Test Runner** - Execute Quality Protocol test scenarios
1212
- ⚡ **Auto-Configuration** - Smart defaults with minimal configuration
1313

14+
## 🤖 AI Development Context
15+
16+
**Role**: Developer Tools & Terminal Interface
17+
**Usage**:
18+
- Runs the development server (`serve` command).
19+
- Compiles metadata.
20+
- Scaffolds new projects (`create`).
21+
1422
## Installation
1523

1624
### Global Installation (Recommended)

‎packages/client-react/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,13 @@
22

33
React hooks for ObjectStack Client SDK - Type-safe data fetching and mutations for React applications.
44

5+
## 🤖 AI Development Context
6+
7+
**Role**: React Bindings for Client SDK
8+
**Usage**:
9+
- Use `useQuery`, `useMutation` hooks.
10+
- Similar to TanStack Query but specialized for ObjectStack.
11+
512
## Installation
613

714
```bash

‎packages/client/README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,17 @@ The official TypeScript client for ObjectStack.
1212
- **View Storage**: Save, load, and share custom UI view configurations.
1313
- **Standardized Errors**: Machine-readable error codes with retry guidance.
1414

15+
## 🤖 AI Development Context
16+
17+
**Role**: Browser/Node Client SDK
18+
**Usage**:
19+
- Use this in Frontend Apps (React, etc.) or external Node scripts.
20+
- Interacts with `packages/runtime` over HTTP.
21+
22+
**Key namespaces**:
23+
- `client.meta`: Metadata operations.
24+
- `client.data`: Data operations.
25+
1526
## Installation
1627

1728
```bash

‎packages/core/README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,19 @@ This package defines the fundamental runtime mechanics of the ObjectStack archit
1313

1414
It is completely agnostic of "Data", "HTTP", or "Apps". It only knows `Plugin` and `Service`.
1515

16+
## 🤖 AI Development Context
17+
18+
**Role**: Microkernel / Runtime Orchestrator
19+
**Usage**:
20+
- Use `ObjectKernel` to bootstrap the application.
21+
- Implement `Plugin` interface to add functionality (not business logic directly).
22+
- Use `PluginLoader` features for dependency injection.
23+
24+
**Architectural Interaction**:
25+
- `Kernel` loads `Plugins`.
26+
- `Plugins` register `Services`.
27+
- `Services` implement logic defined in `spec`.
28+
1629
## Features
1730

1831
### Core Features

‎packages/metadata/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,13 @@ The `@objectstack/metadata` package provides a unified interface for managing me
1212
- **Caching** - ETag-based caching for performance optimization
1313
- **File Watching** - Development mode with automatic reload on file changes
1414

15+
## 🤖 AI Development Context
16+
17+
**Role**: Metadata IO & Persistence
18+
**Usage**:
19+
- Use `MetadataManager` to read/write `.object.ts`, `.view.yaml` files.
20+
- Handles format loading (TS, JSON, YAML).
21+
1522
## Installation
1623

1724
```bash

‎packages/objectql/README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,19 @@
1010
- **Plugin System**: Load objects and logic via standard Manifests.
1111
- **Middleware**: (Planned) Support for Hooks and Validators.
1212

13+
## 🤖 AI Development Context
14+
15+
**Role**: Data Engine / Query Layer
16+
**Usage**:
17+
- Use this package to execute data operations (`find`, `insert`).
18+
- Do NOT bypass this layer to access drivers directly unless building a driver.
19+
- This is the "Backend Brain" for data.
20+
21+
**Key Concepts**:
22+
- `SchemaRegistry`: Holds all object definitions.
23+
- `ObjectQL`: The main facade.
24+
- `Driver`: Interface for storage adapters.
25+
1326
## Usage
1427

1528
### 1. Standalone Usage

‎packages/plugins/driver-memory/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,14 @@
22

33
In-Memory Driver for ObjectStack. A reference implementation of the DriverInterface that stores data in memory using JavaScript arrays.
44

5+
## 🤖 AI Development Context
6+
7+
**Role**: Reference Driver Implementation
8+
**Usage**:
9+
- Use for testing or prototypes.
10+
- Stores data in JS RAM (volatile).
11+
- **Do not** use for production.
12+
513
## Plugin Capabilities
614

715
This driver implements the ObjectStack plugin capability protocol:

‎packages/plugins/plugin-hono-server/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,13 @@
22

33
HTTP Server Adapter for ObjectStack Runtime using the [Hono](https://hono.dev/) framework. This plugin provides a production-ready REST API gateway for ObjectStack applications.
44

5+
## 🤖 AI Development Context
6+
7+
**Role**: HTTP Server Adapter
8+
**Usage**:
9+
- Replaces the default server implementation with Hono.
10+
- Ideal for Edge runtimes (Cloudflare Workers, etc.).
11+
512
## Plugin Capabilities
613

714
This plugin implements the ObjectStack plugin capability protocol:

‎packages/plugins/plugin-msw/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,13 @@
22

33
MSW (Mock Service Worker) Plugin for ObjectStack Runtime. This plugin enables seamless integration with [Mock Service Worker](https://mswjs.io/) for testing and development environments.
44

5+
## 🤖 AI Development Context
6+
7+
**Role**: Test Mocking Adapter
8+
**Usage**:
9+
- Intercepts network requests in tests (Browser/Node).
10+
- Simulates a real ObjectStack backend.
11+
512
## Plugin Capabilities
613

714
This plugin implements the ObjectStack plugin capability protocol:

0 commit comments

Comments
 (0)