dForge Module Tools

VS Code extension for authoring, validating, generating, and packaging dForge module files.

dForge modules are local, versionable module packages made mostly of JSON metadata and optional DSL action scripts. This extension helps module developers catch common mistakes before installing or publishing a module.

Main Features

• JSON Schema validation for dForge module files, based on dForge-core/docs/schemas.
• Cross-file validation for entity, view, menu, folder, role, action, seed data, webhook, and changelog references.
• Syntax highlighting for .dsl action scripts.
• Basic DSL diagnostics based on documented DSL sections and ActionDslCompiler behavior.
• DBML-based module generation through schema-importer.
• .dforge package creation for manual workspace installation.
• Changelog file generation in the documented module changelog format.

Supported Module Files

The extension validates these files and folders:

• manifest.json
• entities/*.json
• ui/data_views.json
• ui/menus.json
• ui/folders.json
• ui/actions.json
• ui/reports.json
• security/roles.json
• seed-data/*.json
• traits.json
• logic/webhooks.json
• logic/actions/*.dsl
• changelog/*.md

Getting Started

Install or run the dForge Module Tools extension, then open an empty folder in VS Code and run:

dForge: Initialize Module Workspace

The command creates a starter module, module-authoring instructions, a SPEC.md file for the user's idea, AI-assistant guidance files, prompt examples, scripts, and the standard dForge module folders.

The starter module contains small test files such as entities/item.json, ui/data_views.json, menus, roles, translations, and changelog content. These files are created only as a valid example and as context for the user's AI assistant. After generation, the AI assistant is expected to replace the starter files with real module files based on the user's request.

After initialization:

1. Open SPEC.md.
2. Describe the module idea, or copy a prompt from examples/TEST_PROMPT.md or examples/CUSTOM_PROMPT.md.
3. Ask the user's own VS Code AI assistant, such as Cursor, Claude Code, Copilot, or Codex, to generate/update the module files and run the generated package script.
4. Run dForge: Validate Module Workspace.
5. Fix diagnostics.
6. If the AI assistant did not create the package, run dForge: Package Module as .dforge manually.

The extension does not call an LLM directly and does not store AI provider keys. AI generation stays on the user's side.

You can also open an existing dForge module folder in VS Code. The folder should contain a manifest.json file at the module root.

Example module structure:

my-module/
  manifest.json
  entities/
    customer.json
  ui/
    data_views.json
    menus.json
    folders.json
    actions.json
  security/
    roles.json
  logic/
    actions/
      approve.dsl
  translations/
    en-US.json
  changelog/
    0.1.0.md

Validation runs automatically when JSON or DSL files are opened, saved, or edited. You can also run a full manual validation pass from the Command Palette.

Commands

Open the Command Palette with Ctrl+Shift+P and use one of these commands.

dForge: Initialize Module Workspace

Creates a local dForge module development workspace in the currently opened folder.

Generated files include:

• manifest.json
• entities/item.json
• ui/data_views.json
• ui/menus.json
• ui/folders.json
• ui/actions.json
• security/roles.json
• translations/en-US.json
• changelog/0.1.0.md
• README.md
• SPEC.md
• AGENTS.md
• CLAUDE.md
• .cursor/rules/dforge-module.mdc
• docs/MODULE_AUTHORING.md
• examples/TEST_PROMPT.md
• examples/CUSTOM_PROMPT.md
• scripts/package.ps1
• scripts/package.sh

The starter module is intentionally small and valid. It is generated as an example of the expected file layout, not as the final business module. Users can then ask their own AI assistant to replace or expand it using SPEC.md and the files under examples/. The generated prompt files also tell the AI assistant to run scripts/package.ps1 or scripts/package.sh, so the flow can end with a ready .dforge file in dist/.

dForge: Validate Module Workspace

Runs a full validation pass for every dForge module found in the current workspace.

It checks:

• manifest required fields, semver values, UUID format, entity paths, locales, README, and translations
• entity fields, links, references, indexes, constraints, formula fields, dropdown/flags options
• data view entity and column references
• menu data view and report references
• folder entity references
• role rights and references to entities, actions, and reports
• action definitions and linked .dsl files
• seed data entityCode and record field names
• webhook entity and payload field references
• changelog filenames, frontmatter, and audience sections

dForge: Generate Module from DBML

Generates a rough dForge module from a .dbml schema file.

Workflow:

1. Open a workspace that contains a .dbml file.
2. Run dForge: Generate Module from DBML.
3. Select the DBML file if there is more than one.
4. Choose an output directory.
5. Enter a display name.
6. The extension calls schema-importer and validates the generated module.

The extension looks for schema-importer in nearby workspace folders, especially:

schema-importer/dist/index.js
schema-importer/dist/cli.js

If no local importer is found, it falls back to dforge-import from PATH.

dForge: Package Module as .dforge

Creates a .dforge package from the current module folder.

Output format:

dist/<module-code>-<version>.dforge

The package is a ZIP archive with a .dforge extension. It excludes development-only folders such as .git, node_modules, and dist.

dForge: Create Changelog File

Creates a changelog markdown file under:

changelog/<version>.md

Generated format:

---
released: 2026-05-05
title: Module Name 0.1.0
---

## For users

- Describe user-visible changes here.

## For admins

- Describe schema, migration, security, or operational impact here.

The format follows the module changelog documentation in dForge-core/docs/modules/system-module-upgrades.md.

JSON Validation

The extension contributes JSON Schema validation for:

• manifest.json
• entities/*.json
• ui/data_views.json
• ui/menus.json
• ui/folders.json
• security/roles.json
• seed-data/*.json
• traits.json
• logic/webhooks.json

The bundled schemas are copied from dForge-core/docs/schemas and adjusted where markdown documentation and real modules clarify the current module format.

Cross-File Validation

JSON Schema can validate the shape of one file, but it cannot know whether a referenced entity, field, view, action, or report exists somewhere else. The extension adds extra diagnostics for those module-level relationships.

Examples of detected issues:

• manifest.json points to a missing entity file
• ui/data_views.json references an unknown entity
• a data view column does not exist on its entity
• ui/menus.json references a missing data view
• security/roles.json references an unknown entity or action
• ui/actions.json references a missing DSL script
• seed-data/*.json contains fields that do not exist on the target entity
• logic/webhooks.json includes fields that do not exist on the target entity

DSL Support

The extension registers .dsl files as dforge-dsl and provides syntax highlighting for:

• params:
• canExecute:
• onBeforeStart:
• execute:
• bracket field references like [status]
• parameter references like params[reason]
• strings, comments, functions, and operators

Current DSL diagnostics check:

• unknown or duplicated top-level DSL sections
• missing execute: section
• malformed params: declarations
• unbalanced square brackets
• params[x] used without declaration in params:
• calls to undocumented or undeclared functions
• field references that do not exist on the action entity

DSL validation is intentionally conservative. It is based on the documented DSL format and the behavior of ActionDslCompiler in dForge-core.

Async Action Pre-Checks

The extension supports the newer onBeforeStart: DSL section used by async actions.

onBeforeStart: runs synchronously before the async execute: part is queued. This is useful for fast validation and immediate UI feedback. For example, the File Library module can check whether a file type is supported, whether a required API secret exists, and whether a model setting is configured before starting a background job.

Supported built-ins include:

• exit(message?, level?)
• getFileInfo(fileField)
• getFileBase64(fileField)
• getFileUrl(fileField)
• tryParseJson(value)
• getSetting(settingCd)
• getSecret(secretCd)
• flush()

If exit() is called inside onBeforeStart:, the async execute: part is not started. Field changes made before exit() are preserved, so a module can mark a record as failed immediately instead of making the user wait for an async background failure.

Development

To run the extension locally:

1. Open this repository in VS Code.
2. Press F5.
3. A new Extension Development Host window opens.
4. In that new window, open a dForge module folder.
5. Edit module JSON or DSL files, or run commands from Ctrl+Shift+P.

Useful local check:

node --check src/extension.js

Current Scope

This extension is focused on local module development. It validates JSON files, highlights and checks DSL files, generates module skeletons from DBML, creates changelog files, and builds local .dforge packages.

Marketplace publishing is not implemented yet. The current packaging command is intended for manual installation into a workspace.