update: packages,lua,shared (5 files)

packages/package_validator/seed/scripts/print_help.lua

@@ -1,4 +1,5 @@
 --- Prints CLI help message
+---@return nil
 local function print_help()
   print([[
 Package Validator CLI

packages/shared/seed/scripts/permissions/check_access.lua

@@ -0,0 +1,69 @@
+-- Check if user has permission to access a package or component
+-- Single function module for access control
+
+---@class CheckAccess
+local M = {}
+
+---Check if user has required permission level for a resource
+---@param userLevel PermissionLevel Current user's permission level (0-6)
+---@param permissions PackagePermissions|ComponentPermission Permission requirements
+---@param featureFlags? table<string, boolean> Active feature flags
+---@param databaseEnabled? boolean Whether database is enabled
+---@return PermissionCheckResult Result with allowed status and reason
+function M.check_access(userLevel, permissions, featureFlags, databaseEnabled)
+  -- Default feature flags and database state
+  featureFlags = featureFlags or {}
+  databaseEnabled = databaseEnabled ~= false -- Default to true
+
+  -- Check if resource is enabled
+  if permissions.enabled == false then
+    return {
+      allowed = false,
+      reason = "Resource is currently disabled"
+    }
+  end
+
+  -- Check minimum permission level
+  local minLevel = permissions.minLevel or 0
+  if userLevel < minLevel then
+    return {
+      allowed = false,
+      reason = "Insufficient permission level",
+      requiredLevel = minLevel
+    }
+  end
+
+  -- Check database requirement
+  if permissions.databaseRequired and not databaseEnabled then
+    return {
+      allowed = false,
+      reason = "Database is required but not enabled"
+    }
+  end
+
+  if permissions.requireDatabase and not databaseEnabled then
+    return {
+      allowed = false,
+      reason = "Database is required but not enabled"
+    }
+  end
+
+  -- Check feature flags (only if specified)
+  if permissions.featureFlags then
+    for _, flag in ipairs(permissions.featureFlags) do
+      if not featureFlags[flag] then
+        return {
+          allowed = false,
+          reason = "Required feature flag '" .. flag .. "' is not enabled"
+        }
+      end
+    end
+  end
+
+  -- All checks passed
+  return {
+    allowed = true
+  }
+end
+
+return M

packages/shared/seed/scripts/permissions/enforce_level.lua

@@ -0,0 +1,25 @@
+-- Enforce minimum permission level requirement
+-- Single function module for level enforcement
+
+---@class EnforceLevel
+local M = {}
+
+---Enforce minimum permission level, throw error if not met
+---@param userLevel PermissionLevel Current user's permission level (0-6)
+---@param minLevel PermissionLevel Required minimum level
+---@param resourceName? string Name of resource for error message
+---@return boolean success Always returns true if no error thrown
+function M.enforce_level(userLevel, minLevel, resourceName)
+  if userLevel < minLevel then
+    local resource = resourceName or "this resource"
+    error(string.format(
+      "Access denied to %s: requires level %d, user has level %d",
+      resource,
+      minLevel,
+      userLevel
+    ))
+  end
+  return true
+end
+
+return M

packages/shared/seed/scripts/permissions/manage_flags.lua

@@ -0,0 +1,60 @@
+-- Feature flag management
+-- Functions for managing and checking feature flags
+
+---@class ManageFlags
+local M = {}
+
+-- Internal feature flag state
+local featureFlags = {}
+
+---Initialize feature flags
+---@param flags table<string, boolean> Initial flag states
+function M.initialize_flags(flags)
+  featureFlags = flags or {}
+end
+
+---Enable a feature flag
+---@param flagName string Name of the flag to enable
+function M.enable_flag(flagName)
+  featureFlags[flagName] = true
+end
+
+---Disable a feature flag
+---@param flagName string Name of the flag to disable
+function M.disable_flag(flagName)
+  featureFlags[flagName] = false
+end
+
+---Check if a feature flag is enabled
+---@param flagName string Name of the flag to check
+---@return boolean enabled Whether the flag is enabled
+function M.is_flag_enabled(flagName)
+  return featureFlags[flagName] == true
+end
+
+---Get all feature flags
+---@return table<string, boolean> All feature flags
+function M.get_all_flags()
+  -- Return a copy to prevent external modification
+  local copy = {}
+  for k, v in pairs(featureFlags) do
+    copy[k] = v
+  end
+  return copy
+end
+
+---Check if all required flags are enabled
+---@param requiredFlags string[] List of required flag names
+---@return boolean allEnabled Whether all flags are enabled
+---@return string[] missingFlags List of missing/disabled flags
+function M.check_required_flags(requiredFlags)
+  local missing = {}
+  for _, flag in ipairs(requiredFlags) do
+    if not M.is_flag_enabled(flag) then
+      table.insert(missing, flag)
+    end
+  end
+  return #missing == 0, missing
+end
+
+return M

packages/shared/seed/scripts/permissions/types.lua

@@ -0,0 +1,54 @@
+-- Permission system type definitions
+-- Defines the structure for package and component permissions
+
+--------------------------------------------------------------------------------
+-- Permission Level Enum
+--------------------------------------------------------------------------------
+
+---@alias PermissionLevel integer
+---| 0 # PUBLIC - No authentication required
+---| 1 # PUBLIC - No authentication required (same as 0)
+---| 2 # USER - Authenticated user
+---| 3 # MODERATOR - Moderator access
+---| 4 # ADMIN - Administrator access
+---| 5 # GOD - Super administrator
+---| 6 # SUPERGOD - System owner
+
+--------------------------------------------------------------------------------
+-- Component Permission
+--------------------------------------------------------------------------------
+
+---@class ComponentPermission
+---@field enabled boolean Component enabled/disabled
+---@field minLevel PermissionLevel Minimum permission level required
+---@field featureFlags? string[] Required feature flags (optional)
+---@field requireDatabase? boolean Whether this component requires database (optional)
+
+--------------------------------------------------------------------------------
+-- Package Permissions
+--------------------------------------------------------------------------------
+
+---@class PackagePermissions
+---@field enabled boolean Package enabled/disabled
+---@field minLevel PermissionLevel Minimum level to access package (0-6)
+---@field databaseRequired? boolean Whether package needs database connection
+---@field components? table<string, ComponentPermission> Per-component permissions
+
+--------------------------------------------------------------------------------
+-- Permission Check Result
+--------------------------------------------------------------------------------
+
+---@class PermissionCheckResult
+---@field allowed boolean Whether access is allowed
+---@field reason? string Denial reason if not allowed
+---@field requiredLevel? PermissionLevel Required level if denied
+
+--------------------------------------------------------------------------------
+-- Feature Flag State
+--------------------------------------------------------------------------------
+
+---@class FeatureFlagState
+---@field flags table<string, boolean> Active feature flags
+---@field databaseEnabled boolean Whether database is currently enabled
+
+return {}