From f2ebee76cf5a68d780a3b5ca65536781bbff6458 Mon Sep 17 00:00:00 2001 From: Richard Ward Date: Tue, 30 Dec 2025 23:47:16 +0000 Subject: [PATCH] docs: package,production,dbal (20 files) --- .actrc => config/.actrc | 0 bun.lock => config/bun.lock | 0 package-lock.json => config/package-lock.json | 0 config/package.json | 39 +++ dbal/production/build-config/CMakeLists.txt | 51 ---- dbal/production/build-config/conanfile.txt | 3 - dbal/production/docs/package_generator.md | 226 ------------------ .../tests/tools/package_generator_test.cpp | 141 ----------- .../DEPENDENCY_CLEANUP.md | 0 .../EXECUTION_TRACKER.md | 0 .../FAKEMUI_STRATEGY.md | 0 .../IMPLEMENTATION_BREAKDOWN.md | 0 .../MASTER_MIGRATION_PLAN.md | 0 .../MIGRATION_PHASES.md | 0 .../MUI_ELIMINATION_PLAN.md | 0 .../PRISMA_PACKAGE_INTEGRATION.md | 0 .../UI_TO_LUA_MIGRATION.md | 0 frontends/cli/README.md | 90 ++++++- nul | 0 stub-patterns.json | 21 -- 20 files changed, 123 insertions(+), 448 deletions(-) rename .actrc => config/.actrc (100%) rename bun.lock => config/bun.lock (100%) rename package-lock.json => config/package-lock.json (100%) create mode 100644 config/package.json delete mode 100644 dbal/production/docs/package_generator.md delete mode 100644 dbal/production/tests/tools/package_generator_test.cpp rename DEPENDENCY_CLEANUP.md => docs/DEPENDENCY_CLEANUP.md (100%) rename EXECUTION_TRACKER.md => docs/EXECUTION_TRACKER.md (100%) rename FAKEMUI_STRATEGY.md => docs/FAKEMUI_STRATEGY.md (100%) rename IMPLEMENTATION_BREAKDOWN.md => docs/IMPLEMENTATION_BREAKDOWN.md (100%) rename MASTER_MIGRATION_PLAN.md => docs/MASTER_MIGRATION_PLAN.md (100%) rename MIGRATION_PHASES.md => docs/MIGRATION_PHASES.md (100%) rename MUI_ELIMINATION_PLAN.md => docs/MUI_ELIMINATION_PLAN.md (100%) rename PRISMA_PACKAGE_INTEGRATION.md => docs/PRISMA_PACKAGE_INTEGRATION.md (100%) rename UI_TO_LUA_MIGRATION.md => docs/UI_TO_LUA_MIGRATION.md (100%) delete mode 100644 nul delete mode 100644 stub-patterns.json diff --git a/.actrc b/config/.actrc similarity index 100% rename from .actrc rename to config/.actrc diff --git a/bun.lock b/config/bun.lock similarity index 100% rename from bun.lock rename to config/bun.lock diff --git a/package-lock.json b/config/package-lock.json similarity index 100% rename from package-lock.json rename to config/package-lock.json diff --git a/config/package.json b/config/package.json new file mode 100644 index 000000000..0aa674693 --- /dev/null +++ b/config/package.json @@ -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" + } +} diff --git a/dbal/production/build-config/CMakeLists.txt b/dbal/production/build-config/CMakeLists.txt index 3f7ea970b..4359b7ad4 100644 --- a/dbal/production/build-config/CMakeLists.txt +++ b/dbal/production/build-config/CMakeLists.txt @@ -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) diff --git a/dbal/production/build-config/conanfile.txt b/dbal/production/build-config/conanfile.txt index 22d09607f..870e9d6c5 100644 --- a/dbal/production/build-config/conanfile.txt +++ b/dbal/production/build-config/conanfile.txt @@ -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 diff --git a/dbal/production/docs/package_generator.md b/dbal/production/docs/package_generator.md deleted file mode 100644 index 5a4fd7a5b..000000000 --- a/dbal/production/docs/package_generator.md +++ /dev/null @@ -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 ` - -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 ` - -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 ` - -Validate a JSON configuration file for package generation. - -## Options - -| Option | Description | Default | -|--------|-------------|---------| -| `--name ` | Display name | Derived from package_id | -| `--description ` | Package description | Auto-generated | -| `--category ` | Package category | `ui` | -| `--min-level ` | 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 ` | Entity names (comma-separated) | None | -| `--with-components` | Include component scaffolding | No | -| `--components ` | Component names | None | -| `--deps ` | Package dependencies | None | -| `--output ` | 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//` -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 -``` diff --git a/dbal/production/tests/tools/package_generator_test.cpp b/dbal/production/tests/tools/package_generator_test.cpp deleted file mode 100644 index b6b80c1cf..000000000 --- a/dbal/production/tests/tools/package_generator_test.cpp +++ /dev/null @@ -1,141 +0,0 @@ -/** - * Package Generator Tests - */ - -#include -#include -#include - -#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(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(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(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(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>("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("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("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; - } -} diff --git a/DEPENDENCY_CLEANUP.md b/docs/DEPENDENCY_CLEANUP.md similarity index 100% rename from DEPENDENCY_CLEANUP.md rename to docs/DEPENDENCY_CLEANUP.md diff --git a/EXECUTION_TRACKER.md b/docs/EXECUTION_TRACKER.md similarity index 100% rename from EXECUTION_TRACKER.md rename to docs/EXECUTION_TRACKER.md diff --git a/FAKEMUI_STRATEGY.md b/docs/FAKEMUI_STRATEGY.md similarity index 100% rename from FAKEMUI_STRATEGY.md rename to docs/FAKEMUI_STRATEGY.md diff --git a/IMPLEMENTATION_BREAKDOWN.md b/docs/IMPLEMENTATION_BREAKDOWN.md similarity index 100% rename from IMPLEMENTATION_BREAKDOWN.md rename to docs/IMPLEMENTATION_BREAKDOWN.md diff --git a/MASTER_MIGRATION_PLAN.md b/docs/MASTER_MIGRATION_PLAN.md similarity index 100% rename from MASTER_MIGRATION_PLAN.md rename to docs/MASTER_MIGRATION_PLAN.md diff --git a/MIGRATION_PHASES.md b/docs/MIGRATION_PHASES.md similarity index 100% rename from MIGRATION_PHASES.md rename to docs/MIGRATION_PHASES.md diff --git a/MUI_ELIMINATION_PLAN.md b/docs/MUI_ELIMINATION_PLAN.md similarity index 100% rename from MUI_ELIMINATION_PLAN.md rename to docs/MUI_ELIMINATION_PLAN.md diff --git a/PRISMA_PACKAGE_INTEGRATION.md b/docs/PRISMA_PACKAGE_INTEGRATION.md similarity index 100% rename from PRISMA_PACKAGE_INTEGRATION.md rename to docs/PRISMA_PACKAGE_INTEGRATION.md diff --git a/UI_TO_LUA_MIGRATION.md b/docs/UI_TO_LUA_MIGRATION.md similarity index 100% rename from UI_TO_LUA_MIGRATION.md rename to docs/UI_TO_LUA_MIGRATION.md diff --git a/frontends/cli/README.md b/frontends/cli/README.md index f8cfbfe0c..419ed07f0 100644 --- a/frontends/cli/README.md +++ b/frontends/cli/README.md @@ -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 # Authenticate +metabuilder-cli user list # List users +metabuilder-cli user get # Get user by ID +metabuilder-cli tenant list # List tenants +metabuilder-cli tenant get # Get tenant by ID +metabuilder-cli dbal # DBAL operations +``` + +### Package Commands + +```bash +metabuilder-cli package list # List packages with scripts +metabuilder-cli package run