git/metabuilder
1
0
Fork 0
mirror of https://github.com/johndoe6345789/metabuilder.git synced 2026-04-24 13:54:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: package,production,dbal (20 files)

Browse Source
This commit is contained in:
Richard Ward
2025-12-30 23:47:16 +00:00
parent d9932718d9
commit f2ebee76cf
20 changed files with 123 additions and 448 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
.actrc → config/.actrc
View File

0
bun.lock → config/bun.lock
View File

0
package-lock.json → config/package-lock.json generated
View File

39
config/package.json Normal file
View File

@@ -0,0 +1,39 @@
{
"scripts": {
"generate:package": "npx ts-node scripts/generate-package.ts",
"todos:scan": "python3 docs/todo/scans/scan-project-todos.py",
"todos:preview": "python3 tools/project-management/populate-kanban.py --dry-run --limit 10",
"todos:export": "python3 tools/project-management/populate-kanban.py --output todos.json",
"todos:export-critical": "python3 tools/project-management/populate-kanban.py --output todos-critical.json --filter-priority critical",
"todos:export-filtered": "python3 tools/project-management/populate-kanban.py --output todos-filtered.json --exclude-checklist",
"todos:test": "python3 tools/project-management/test_populate_kanban.py",
"todos:create": "python3 tools/project-management/populate-kanban.py --create",
"todos:help": "python3 tools/project-management/populate-kanban.py --help",
"todos:check": "python3 tools/project-management/check-new-todos.py",
"todos:baseline": "python3 tools/project-management/check-new-todos.py --save-baseline",
"extract:preview": "cd frontends/nextjs && npm run extract:preview",
"extract:quick": "cd frontends/nextjs && npm run extract:quick",
"extract:auto": "cd frontends/nextjs && npm run extract:auto",
"extract:all": "cd frontends/nextjs && npm run extract:all",
"extract:help": "cd frontends/nextjs && npm run extract:help",
"schema:scan": "npx ts-node tools/codegen/schema-cli.ts scan",
"schema:list": "npx ts-node tools/codegen/schema-cli.ts list",
"schema:approve": "npx ts-node tools/codegen/schema-cli.ts approve",
"schema:generate": "npx ts-node tools/codegen/schema-cli.ts generate",
"schema:status": "npx ts-node tools/codegen/schema-cli.ts status",
"schema:preview": "npx ts-node tools/codegen/schema-cli.ts preview",
"db:generate": "npx prisma generate",
"db:migrate": "npx prisma migrate dev"
},
"devDependencies": {
"@prisma/client": "^7.2.0",
"prisma": "^7.2.0",
"yaml": "^2.8.2"
},
"dependencies": {
"@prisma/adapter-better-sqlite3": "^7.2.0",
"better-sqlite3": "^12.5.0",
"clsx": "^2.1.1",
"jszip": "^3.10.1"
}
}

51
dbal/production/build-config/CMakeLists.txt
View File

@@ -98,57 +98,6 @@ add_test(NAME query_test COMMAND query_test)
add_test(NAME integration_tests COMMAND integration_tests)
add_test(NAME conformance_tests COMMAND conformance_tests)
# =============================================================================
# Package Generator Tool (Lua-based)
# =============================================================================
find_package(lua QUIET)
find_package(sol2 QUIET)
if(lua_FOUND AND sol2_FOUND)
message(STATUS "Building package_generator tool with Lua support")
add_executable(package_generator
${DBAL_SRC_DIR}/tools/package_generator/main.cpp
)
target_include_directories(package_generator PRIVATE
${DBAL_SRC_DIR}/tools/package_generator
)
target_link_libraries(package_generator
lua::lua
sol2::sol2
)
if(nlohmann_json_FOUND)
target_link_libraries(package_generator nlohmann_json::nlohmann_json)
endif()
# Package generator tests
add_executable(package_generator_test
${DBAL_TEST_DIR}/tools/package_generator_test.cpp
)
target_include_directories(package_generator_test PRIVATE
${DBAL_SRC_DIR}/tools/package_generator
)
target_link_libraries(package_generator_test
lua::lua
sol2::sol2
)
if(nlohmann_json_FOUND)
target_link_libraries(package_generator_test nlohmann_json::nlohmann_json)
endif()
add_test(NAME package_generator_test COMMAND package_generator_test)
install(TARGETS package_generator DESTINATION bin)
else()
message(STATUS "Skipping package_generator (lua or sol2 not found)")
endif()
install(TARGETS dbal_daemon DESTINATION bin)
install(DIRECTORY ${DBAL_INCLUDE_DIR}/dbal DESTINATION include)

3
dbal/production/build-config/conanfile.txt
View File

@@ -5,8 +5,6 @@ spdlog/1.16.0
nlohmann_json/3.11.3
drogon/1.9.7
cpr/1.14.1
lua/5.4.7
sol2/3.3.1
[generators]
CMakeDeps
@@ -14,7 +12,6 @@ CMakeToolchain
[options]
sqlite3/*:shared=False
lua/*:shared=False
[layout]
cmake_layout

226
dbal/production/docs/package_generator.md
View File

@@ -1,226 +0,0 @@
# Package Generator C++ CLI
A native C++ command-line tool for generating MetaBuilder package scaffolding using embedded Lua scripts.
## Features
- **Native Performance**: Compiled C++ binary with embedded Lua runtime
- **Sandboxed Execution**: Lua scripts run in isolated environment (no `os`, `io`, `debug`)
- **Cross-Platform**: Builds on Linux, macOS, and Windows via Conan/CMake
- **Full Validation**: Package configs validated before generation
## Building
### Prerequisites
- C++17 compiler (GCC 9+, Clang 10+, MSVC 2019+)
- CMake 3.20+
- Conan 2.x package manager
### Build Steps
```bash
cd dbal/production/build-config
# Install dependencies with Conan
conan install . --output-folder=build --build=missing
# Configure CMake
cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
# Build
cmake --build . --target package_generator
# Install (optional)
cmake --install . --prefix=/usr/local
```
### Conan Dependencies
The tool uses these Conan packages:
- `lua/5.4.7` - Lua interpreter
- `sol2/3.3.1` - C++/Lua binding library
- `nlohmann_json/3.11.3` - JSON parsing
## Usage
```bash
# Basic usage
package_generator new my_package
# With options
package_generator new my_forum \
--category social \
--min-level 2 \
--with-schema \
--entities Thread,Post,Reply
# Quick minimal package
package_generator quick my_widget --dependency
# List categories
package_generator list-categories
# Validate config file
package_generator validate config.json
# Preview without writing
package_generator new my_package --dry-run
```
## Commands
### `new <package_id>`
Create a new package with full scaffolding including:
- `seed/metadata.json` - Package configuration
- `seed/components.json` - Component definitions
- `seed/layout.json` - UI layout
- `seed/scripts/init.lua` - Initialization hooks
- `seed/scripts/tests/` - Test files
- `static_content/icon.svg` - Package icon
- `README.md` - Documentation
### `quick <package_id>`
Create a minimal package with just essential files:
- `seed/metadata.json`
- `seed/components.json`
- `seed/scripts/init.lua`
### `list-categories`
Display available package categories:
- ui, editors, tools, social, media, gaming
- admin, config, core, demo, development, managers
### `validate <file>`
Validate a JSON configuration file for package generation.
## Options
| Option | Description | Default |
|--------|-------------|---------|
| `--name <name>` | Display name | Derived from package_id |
| `--description <desc>` | Package description | Auto-generated |
| `--category <cat>` | Package category | `ui` |
| `--min-level <n>` | Minimum access level (0-6) | `2` |
| `--primary` | Package can own routes | Yes |
| `--dependency` | Package is dependency-only | No |
| `--with-schema` | Include database schema | No |
| `--entities <e1,e2>` | Entity names (comma-separated) | None |
| `--with-components` | Include component scaffolding | No |
| `--components <c1,c2>` | Component names | None |
| `--deps <d1,d2>` | Package dependencies | None |
| `--output <dir>` | Output directory | `./packages` |
| `--dry-run` | Preview without writing | No |
## Examples
### Create a Forum Package
```bash
package_generator new forum_module \
--name "Forum Module" \
--description "Discussion forum with threads and posts" \
--category social \
--min-level 1 \
--with-schema \
--entities ForumThread,ForumPost,ForumReply \
--deps ui_permissions,dashboard
```
### Create a UI Widget
```bash
package_generator new stat_widget \
--category ui \
--min-level 2 \
--dependency \
--with-components \
--components StatCard,StatChart,StatTable
```
### Create Admin Tool
```bash
package_generator new admin_reports \
--category admin \
--min-level 4 \
--with-schema \
--entities Report,ReportSchedule
```
## Architecture
```
package_generator (C++)
│
├── arg_parser.hpp # Command-line parsing
├── lua_runner.hpp # sol2-based Lua execution
├── file_writer.hpp # File system operations
└── main.cpp # CLI entry point
│
│ calls
▼
package_template (Lua)
├── init.lua # Module entry point
├── templates.lua # Template generators
├── generator.lua # Orchestration
└── cli.lua # Lua CLI (standalone use)
```
## Lua Sandbox
The Lua environment is sandboxed for security:
**Allowed:**
- `base` - Core Lua functions
- `string` - String manipulation
- `table` - Table operations
- `math` - Mathematical functions
- `utf8` - UTF-8 handling
**Blocked:**
- `os` - Operating system access
- `io` - File I/O
- `debug` - Debug facilities
- `ffi` - Foreign function interface
- `package.loadlib` - Native library loading
All file operations are performed by the C++ host, not Lua scripts.
## Integration with MetaBuilder
The generated packages are fully compatible with MetaBuilder's package system:
1. Run generator from project root
2. Files are written to `packages/<package_id>/`
3. Run `npm run packages:index` to update package registry
4. Package is available in the platform
## Troubleshooting
### "Module not found"
Ensure you're running from the MetaBuilder project root, or specify the scripts path:
```bash
export METABUILDER_SCRIPTS=/path/to/packages/codegen_studio/seed/scripts
```
### Build errors with sol2
sol2 requires C++17. Ensure your compiler supports it:
```bash
cmake .. -DCMAKE_CXX_STANDARD=17
```
### Conan package not found
Update Conan remotes:
```bash
conan remote add conancenter https://center.conan.io
conan install . --build=missing
```

141
dbal/production/tests/tools/package_generator_test.cpp
View File

@@ -1,141 +0,0 @@
/**
* Package Generator Tests
*/
#include <cassert>
#include <iostream>
#include <filesystem>
#include "lua_runner.hpp"
#include "arg_parser.hpp"
namespace fs = std::filesystem;
void test_arg_parser() {
std::cout << "Testing ArgParser...\n";
// Test basic positional args
{
const char* argv[] = {"prog", "new", "my_package"};
tools::ArgParser parser(3, const_cast<char**>(argv));
assert(parser.get_positional(0) == "new");
assert(parser.get_positional(1) == "my_package");
assert(parser.get_positional(2) == "");
}
// Test flags
{
const char* argv[] = {"prog", "new", "pkg", "--dry-run", "--primary"};
tools::ArgParser parser(5, const_cast<char**>(argv));
assert(parser.has_flag("dry-run"));
assert(parser.has_flag("primary"));
assert(!parser.has_flag("unknown"));
}
// Test options with values
{
const char* argv[] = {"prog", "new", "pkg", "--category", "tools", "--min-level", "3"};
tools::ArgParser parser(7, const_cast<char**>(argv));
assert(parser.get_option("category") == "tools");
assert(parser.get_int_option("min-level") == 3);
assert(parser.get_option("unknown", "default") == "default");
}
// Test list options
{
const char* argv[] = {"prog", "new", "pkg", "--entities", "User,Post,Comment"};
tools::ArgParser parser(5, const_cast<char**>(argv));
auto entities = parser.get_list_option("entities");
assert(entities.size() == 3);
assert(entities[0] == "User");
assert(entities[1] == "Post");
assert(entities[2] == "Comment");
}
std::cout << " ArgParser tests passed!\n";
}
void test_lua_config() {
std::cout << "Testing LuaConfig...\n";
tools::LuaConfig config;
config.set("packageId", "test_package");
config.set("minLevel", 3);
config.set("primary", true);
config.set_list("entities", {"User", "Post"});
assert(config.data["packageId"] == "test_package");
assert(config.data["minLevel"] == 3);
assert(config.data["primary"] == true);
assert(config.data["entities"].size() == 2);
std::cout << " LuaConfig tests passed!\n";
}
void test_lua_runner() {
std::cout << "Testing LuaRunner...\n";
// Find scripts path
fs::path scripts_path = fs::current_path() / "packages" / "codegen_studio" / "seed" / "scripts";
if (!fs::exists(scripts_path)) {
std::cout << " Skipping LuaRunner tests (scripts not found at " << scripts_path << ")\n";
return;
}
tools::LuaRunner lua(scripts_path);
// Test module loading
bool loaded = lua.load_module("package_template");
if (!loaded) {
std::cout << " Warning: Could not load package_template module\n";
std::cout << " Error: " << lua.last_error() << "\n";
return;
}
// Test get_categories
auto categories = lua.call<std::vector<std::string>>("package_template.get_categories");
assert(!categories.empty());
assert(std::find(categories.begin(), categories.end(), "ui") != categories.end());
// Test validate_config
tools::LuaConfig config;
config.set("packageId", "test_pkg");
config.set("category", "tools");
config.set("minLevel", 2);
config.set("primary", true);
auto validation = lua.call<tools::ValidationResult>("package_template.validate_config", config);
assert(validation.valid);
// Test invalid config
tools::LuaConfig bad_config;
bad_config.set("packageId", "Invalid-ID"); // Invalid format
bad_config.set("category", "invalid_cat");
auto bad_validation = lua.call<tools::ValidationResult>("package_template.validate_config", bad_config);
assert(!bad_validation.valid);
assert(!bad_validation.errors.empty());
std::cout << " LuaRunner tests passed!\n";
}
int main() {
std::cout << "\n=== Package Generator Tests ===\n\n";
try {
test_arg_parser();
test_lua_config();
test_lua_runner();
std::cout << "\n✅ All tests passed!\n\n";
return 0;
} catch (const std::exception& e) {
std::cerr << "\n❌ Test failed: " << e.what() << "\n\n";
return 1;
}
}

0
DEPENDENCY_CLEANUP.md → docs/DEPENDENCY_CLEANUP.md
View File

0
EXECUTION_TRACKER.md → docs/EXECUTION_TRACKER.md
View File

0
FAKEMUI_STRATEGY.md → docs/FAKEMUI_STRATEGY.md
View File

0
IMPLEMENTATION_BREAKDOWN.md → docs/IMPLEMENTATION_BREAKDOWN.md
View File

0
MASTER_MIGRATION_PLAN.md → docs/MASTER_MIGRATION_PLAN.md
View File

0
MIGRATION_PHASES.md → docs/MIGRATION_PHASES.md
View File

0
MUI_ELIMINATION_PLAN.md → docs/MUI_ELIMINATION_PLAN.md
View File

0
PRISMA_PACKAGE_INTEGRATION.md → docs/PRISMA_PACKAGE_INTEGRATION.md
View File

0
UI_TO_LUA_MIGRATION.md → docs/UI_TO_LUA_MIGRATION.md
View File

90
frontends/cli/README.md
View File

@@ -1,6 +1,6 @@
# MetaBuilder CLI
This simple CLI targets MetaBuilder services via HTTP and uses Conan + Ninja for dependency management and builds.
This CLI targets MetaBuilder services via HTTP and includes a Lua runtime for executing package scripts. Uses Conan + CMake for dependency management and builds.
## Requirements
@@ -18,19 +18,97 @@ cmake -S . -B build -G Ninja
cmake --build build
```
Conan will provision [`cpr`](https://github.com/libcpr/cpr) for HTTP requests and generate `conan_toolchain.cmake` inside `build/`.
Conan provisions these dependencies:
- [`cpr`](https://github.com/libcpr/cpr) - HTTP requests
- [`lua`](https://www.lua.org/) - Lua 5.4 interpreter
- [`sol2`](https://github.com/ThePhD/sol2) - C++/Lua binding
- [`nlohmann_json`](https://github.com/nlohmann/json) - JSON handling
## Running
The executable looks for `METABUILDER_BASE_URL` (default `http://localhost:3000`):
```bash
METABUILDER_BASE_URL=http://localhost:3000 ./build/bin/metabuilder-cli auth session
METABUILDER_BASE_URL=http://localhost:3000 ./build/bin/metabuilder-cli user list
# API commands
./build/bin/metabuilder-cli auth session
./build/bin/metabuilder-cli user list
# Package commands (run from project root)
./build/bin/metabuilder-cli package list
./build/bin/metabuilder-cli package generate my_forum --category social --with-schema --entities Thread,Post
./build/bin/metabuilder-cli package run codegen_studio package_template get_categories
```
Available commands are listed when running without arguments or with an unrecognized command.
## Commands
### API Commands
```bash
metabuilder-cli auth session # Show current session
metabuilder-cli auth login <email> <password> # Authenticate
metabuilder-cli user list # List users
metabuilder-cli user get <userId> # Get user by ID
metabuilder-cli tenant list # List tenants
metabuilder-cli tenant get <tenantId> # Get tenant by ID
metabuilder-cli dbal <subcommand> # DBAL operations
```
### Package Commands
```bash
metabuilder-cli package list # List packages with scripts
metabuilder-cli package run <pkg> <script> # Run a Lua script from a package
metabuilder-cli package generate <id> [opts] # Generate a new package
```
#### Generate Options
| Option | Description | Default |
|--------|-------------|---------|
| `--name <name>` | Display name | Derived from package_id |
| `--description <desc>` | Package description | Auto-generated |
| `--category <cat>` | Package category | `ui` |
| `--min-level <n>` | Minimum access level 0-6 | `2` |
| `--primary` | Package can own routes | Yes |
| `--dependency` | Package is dependency-only | No |
| `--with-schema` | Include database schema | No |
| `--entities <e1,e2>` | Entity names (comma-separated) | None |
| `--with-components` | Include component scaffolding | No |
| `--components <c1,c2>` | Component names | None |
| `--deps <d1,d2>` | Package dependencies | None |
| `--output <dir>` | Output directory | `./packages` |
| `--dry-run` | Preview without writing | No |
#### Examples
```bash
# Generate a forum package with schema
metabuilder-cli package generate my_forum \
--category social \
--with-schema \
--entities ForumThread,ForumPost,ForumReply
# Generate a UI widget as dependency
metabuilder-cli package generate stat_widget \
--category ui \
--dependency \
--with-components \
--components StatCard,StatChart
# Preview without creating files
metabuilder-cli package generate test_pkg --dry-run
```
## Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `METABUILDER_BASE_URL` | API base URL | `http://localhost:3000` |
| `METABUILDER_PACKAGES` | Packages directory | `./packages` |
## Continuous Integration
Changes under `frontends/cli/` now trigger `.github/workflows/ci/cli.yml`, which runs Conan, configures/ninja-build the project, and validates that `metabuilder-cli --help` exits cleanly.
Changes under `frontends/cli/` trigger `.github/workflows/ci/cli.yml`, which:
1. Runs Conan to install dependencies
2. Configures and builds with CMake/Ninja
3. Validates that `metabuilder-cli --help` exits cleanly

0
nul
View File

21
stub-patterns.json
View File

@@ -1,21 +0,0 @@
{
"totalStubsFound": 0,
"bySeverity": {
"high": 0,
"medium": 0,
"low": 0
},
"byType": {
"not-implemented": 0,
"todo-comment": 0,
"console-log-only": 0,
"placeholder-return": 0,
"mock-data": 0,
"placeholder-render": 0,
"stub-component": 0,
"empty-body": 0
},
"criticalIssues": [],
"details": [],
"timestamp": "2025-12-26T00:12:56.808Z"
}