metabuilder/docx/REFACTOR_PLAN.md

Next.js to Lua Conversion TODO

Table of Contents

• TODOs by Phase
• Audit Results
• Quick File References
• Next Steps
• Support Notes

TODOs by Phase

Phase 0 – Foundation

• Audit all frontends/nextjs/src/ entry points (pages, components, hooks, lib). Determine what goes to Lua.
• Define the Lua boundary. List metadata, static, and seed assets plus their API surface.

Phase 1 – Mapping

• Map reusable TypeScript helpers to single-function Lua targets (one file, one function) and describe their inputs/outputs for future porting.
• Categorize each file as “port to Lua”, “adapter only”, or “keep in TypeScript”.

Phase 2 – Framework Bridge

• Extend the core framework only where gaps remain (data loading, metadata resolution, routing) with tiny TypeScript adapters to Lua if needed.
• Align metadata/seed folder structure with the requirements (consider lua/ or packages/static_content) and add placeholder files.

Phase 3 – Pilot Conversion

• Pilot a TypeScript → Lua helper conversion (choose one small helper, wrap it with an adapter, and keep the rest of the build intact).
• Ensure the pilot is wired into the Next.js app without breaking the current build or tests.

Phase 4 – Stabilize

• Update documentation/tests to reflect the new Lua metadata focus and ensure existing CI steps continue to pass with the new structure.
• Iterate with feedback—confirm the team agrees on the folder layout, metadata ownership, and which TypeScript files stay as adapters.

Prep Checklist

• Confirm tooling (Lua runtime, luacheck, etc.) is installed if needed before creating helpers.
• Backup critical TypeScript files via comments or notes before starting ports.
• Share the plan with the team and gather quick approvals for folder names (lua/, packages/static_content).
• Identify one “safe” helper to convert first, ideally small and well-tested.

Audit Results

App surface

• frontends/nextjs/src/app has 40+ routes.
• Each route needs metadata.
• Key files:
  • page.tsx
  • layout.tsx
  • levels tree
  • auth/dashboards
  • providers.tsx and theme hooks
  • packages/[...path]/route.ts
• API handlers touch auth, users, packages, levels, power-transfers, GitHub actions, screenshot, and health.
• They depend on helpers under frontends/nextjs/src/lib/api, lib/packages/loader, db, and dbal.

UI components

• frontends/nextjs/src/components holds ~60 React files.
• Builders:
  • Builder
  • Level1, Level2, Level3, Level4, Level5
  • NerdModeIDE
• Editors:
  • LuaEditor
  • LuaBlocksEditor
  • CodeEditor
  • JsonEditor
  • SchemaEditors
• Management views:
  • PackageManager
  • DatabaseManager
  • ComponentCatalog
  • WorkflowEditor
• Integrations and tools:
  • GitHubActionsFetcher
  • IRCWebchat variants
  • DBALDemo
  • UnifiedLogin
• Atoms, molecules, and organisms live in nested folders. We will tag each file in Phase 1.

Hooks & libraries

• Hooks:
  • useAuth
  • useAutoRefresh
  • useKV
  • useLevelRouting
  • useDBAL
  • useFileTree
  • useCodeEditor
  • useResolvedUser
  • useGitHubFetcher
  • use-mobile
  • hooks/auth store
  • hooks/use-dbal helpers (blob storage, kv store, cached data)
• Libraries cover:
  • auth and security (lib/auth, lib/security)
  • database and DBAL helpers
  • package, seed, and metadata tooling (lib/packages, lib/seed)
  • Lua engine and functions
  • workflow and rendering helpers
  • API helpers and schema utilities
  • GitHub and general utilities (lib/utils, lib/prisma)
• Phase 1 will tag each file as “adapter” or “port”.

Supporting assets

• frontends/nextjs/src/seed-data has JSON seeds for packages and baseline data. These can move to metadata.
• Tests live in app/api/*/*.test.tsx, lib/**/*test.ts, components/get-component-icon.test.tsx, and hooks/*.test.ts. We will decide which tests follow Lua stubbed logic or stay with TypeScript.

Quick File References

• frontends/nextjs/src/app: each route, page, provider, and API handler needs metadata or a Lua adapter.
• frontends/nextjs/src/components: move builders, editors, and managers to metadata-driven definitions.
• frontends/nextjs/src/hooks: turn each hook into a Lua micro-function.
• frontends/nextjs/src/lib: catalogue auth, security, db/DBAL, packages, Lua, workflow, API, schema, GitHub, and utility modules.
• Supporting assets: seed JSONs, README docs, and tests must align with the Lua transition.

Next Steps

1. Create the companion metadata folder (e.g., lua/ or packages/static_content) with placeholder single-function files that mirror the above references.
2. Run the audit across the identified folders. Mark each file as “port to Lua”, “adapter only”, or “leave in TypeScript” before editing.

Phase Deliverables

• Phase 0: Audit spreadsheet/list with tags for each entry. Lua boundary doc with endpoints and metadata goals.
• Phase 1: Mapping sheet (spreadsheet or Markdown) documenting TypeScript helper → Lua micro-function mapping and file categorization.
• Phase 2: Adapter interface stubs plus placeholder Lua files under the new metadata folder.
• Phase 3: One working Lua helper wired through an adapter, with updated unit test coverage or manual verification notes.
• Phase 4: Documentation updates, test run results, and a summary of which files moved versus stayed.

Support Notes

• Risks: The Next.js frontend is large; do not remove TypeScript pages until their Lua replacements exist. Keep unit/e2e tests running in TypeScript during transition.

• Owner: Track who updates each phase and keep a note in this doc or comments for accountability.

• Validation tips: After a Lua helper is added, run npm run lint and npm run test:unit from frontends/nextjs/. Keep logs of failing tests if you defer them.

• Documentation: Update READMEs in components/, hooks/, and lib/ with pointers to the new Lua package once core content moves.

• Checkpoint: Before Phase 3, ensure adapter interfaces exist for data access and that seed data has been migrated to the metadata folder.

• Toolbelt

  • npm run lint (in frontends/nextjs/)
  • npm run test:unit
  • npm run test:e2e (only after Lua helpers are wired)
  • npm run build to verify core app still compiles

• Folder sketch

  • lua/metadata/ – metadata + seed descriptors per package
  • lua/functions/ – single-function files (one helper per file)
  • lua/adapters/ – TypeScript adapters that relay calls into Lua micro-functions
  • packages/static_content/ – optional storage for JSON seeds already living in the frontend

Tracking & Templates

• Audit table:
  1. File path
  2. Current role (page, API, hook, lib)
  3. Port target (Lua, adapter, stay TS)
  4. Notes/risks
  5. Owner/ETA
• Mapping sheet:
  1. Helper name
  2. Inputs/outputs
  3. Proposed Lua file path
  4. Adapter needed (yes/no)
  5. Test expectations
• Documentation reminders: keep the doc updated with any new folder names, helper descriptions, or decisions so new contributors can follow the trail.