Add CLI usage example and project structure documentation; include configuration files for CLI development

Author: hotlong

examples/README.md

@@ -148,6 +148,28 @@ pnpm dev
 
 **Complete server implementation** showing how to build a metadata-driven backend.
 
+---
+
+### CLI Usage Example
+**Path:** [`examples/cli-usage/`](./cli-usage/)  
+**Level:** 🟢 Beginner  
+**Protocols:** System  
+
+**CLI Development Workflow** - Learn how to use `@objectstack/cli` for development and debugging.
+
+**What you'll learn:**
+- Setting up a project for CLI
+- `dev` vs `serve` commands
+- Debugging configurations for VS Code
+- Project structure best practices
+
+**Quick Start:**
+```bash
+cd examples/cli-usage
+pnpm install
+pnpm dev
+```
+
 **Features:**
 - Dynamic schema loading from plugins
 - Auto-generated REST APIs

examples/cli-usage/README.md

@@ -0,0 +1,46 @@
+# CLI Usage Example
+
+This example demonstrates how to use the `@objectstack/cli` to develop, serve, and debug an ObjectStack project.
+
+## Scripts
+
+The `package.json` includes several useful scripts:
+
+- `pnpm dev`: Starts the development server in watch mode.
+- `pnpm serve`: Starts the production server.
+- `pnpm build`: Compiles the project.
+- `pnpm doctor`: Checks for issues.
+- `pnpm debug`: Starts the server in debug mode (breaking at the first line).
+
+## Debugging in VS Code
+
+To debug this project using VS Code:
+
+1. Open the Javascript Debug Terminal.
+2. Run `pnpm dev` or `pnpm serve`.
+
+### Using Launch Configuration
+
+You can also use a launch configuration. Add this to your `.vscode/launch.json`:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug CLI Usage Example",
+      "cwd": "${workspaceFolder}/examples/cli-usage",
+      "runtimeExecutable": "pnpm",
+      "runtimeArgs": ["debug"],
+      "port": 9229
+    }
+  ]
+}
+```
+
+## Project Structure
+
+- `src/project.object.ts`: Defines a simple "Project" object.
+- `objectstack.config.ts`: Registers the object.

examples/cli-usage/objectstack.config.ts

@@ -0,0 +1,9 @@
+import { defineStack } from '@objectstack/spec';
+import { Project } from './src/project.object.js';
+
+export default defineStack({
+  objects: [
+    Project
+  ],
+  apps: []
+});

examples/cli-usage/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@examples/cli-usage",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "dev": "objectstack dev",
+    "serve": "objectstack serve",
+    "build": "objectstack compile",
+    "doctor": "objectstack doctor",
+    "debug": "node --inspect-brk node_modules/.bin/objectstack serve"
+  },
+  "dependencies": {
+    "@objectstack/cli": "workspace:*",
+    "@objectstack/spec": "workspace:*"
+  }
+}

examples/cli-usage/src/project.object.ts

@@ -0,0 +1,12 @@
+import { ObjectSchema, Field } from '@objectstack/spec/data';
+
+export const Project = ObjectSchema.create({
+  name: 'cli_project',
+  label: 'CLI Project',
+  icon: 'briefcase',
+  fields: {
+    name: Field.text({ required: true, label: 'Project Name' }),
+    status: Field.select(['Planned', 'In Progress', 'Completed'], { defaultValue: 'Planned' }),
+    description: Field.textarea()
+  }
+});

examples/cli-usage/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist"
+  },
+  "include": ["src", "objectstack.config.ts"]
+}