@dforge-core/dforge-cli 0.1.0-rc.3 → 0.1.0-rc.5

package/README.md

@@ -17,9 +17,7 @@ macOS arm64/x64, Linux x64/arm64, Windows x64/arm64.
 ## Commands
 
 ```bash
-# Scaffold a new module interactively (asks for code/displayName/dependencies/
-# preset/initial entity). Generates manifest with a real UUID, writes the
-# minimum file set so the module installs cleanly.
+# Scaffold a new module interactively (see `Scaffolding a new module` below).
 dforge-cli init module ./my-module
 
 # Package a module directory into a .dforge archive
@@ -41,6 +39,58 @@ DFORGE_URL=https://app.example.com DFORGE_TOKEN=<jwt> \
 dforge-cli dbml-import --from-dbml ./schema.dbml
 ```
 
+## Scaffolding a new module
+
+```bash
+dforge-cli init module ./my-module
+```
+
+Walks you through an interactive setup and writes a fresh module that's
+ready to `pack` and `install`.
+
+### What it asks
+
+| Prompt | Default | Notes |
+|---|---|---|
+| Module code | (none) | `^[a-z][a-z0-9_-]*$` — becomes the DB schema name and `module_cd` |
+| Display name | titlecased `code` | shown in the UI |
+| Description | (empty) | optional |
+| Author name | `git config user.name` | optional |
+| License | `MIT` | |
+| Version | `0.1.0` | semver |
+| DB schema version | `0.0.1` | bumped when you alter physical columns |
+| Dependencies | `admin`, `metadata` | toggle which system modules you depend on |
+| Preset | Minimal | see below |
+| First entity name | (none) | `^[a-z][a-z0-9_]*$` — table/entity code |
+| First entity label | titlecased name | display label |
+| Traits | `identity + audit` | see below |
+
+`moduleId` (the immutable UUID) is auto-generated with `crypto.randomUUID()` — no prompt.
+
+### Presets
+
+- **Minimal** — manifest + one entity + minimum UI (`data_views`, `folders`, `menus`, `actions`) + one admin role. ~8 files. Installs as-is; you add fields/views/roles from there.
+- **Minimal + add more entities interactively** — same as Minimal, then loops to add additional entities (name + label + traits per entity) so you don't have to re-run.
+- **Full template** — Minimal plus `settings.json`, `translations/en-US.json`, a `seed-data/01-<entity>.json` per entity, and a `logic/actions/` stub directory. Use this when you want the typical optional files scaffolded for you to fill in (or delete).
+
+### Entity traits
+
+The "traits" choice controls which built-in columns the entity gets for free — both rendered by the platform, no need to declare in `fields`:
+
+- **identity only** — primary key only. Use for lookup tables that don't need audit columns.
+- **identity + audit** (recommended) — primary key + `created_date` + `last_updated` + `created_by` + `last_updated_by`. Standard for any business entity.
+
+You can change traits later by editing the entity JSON.
+
+### After scaffold
+
+```bash
+cd ./my-module
+dforge-cli module install --path . --code <tenant>   # full validation + install
+```
+
+The first install runs the full server-side validator (manifest, FK targets, package-filter SQL, migration safety) — fix anything it flags, then re-run.
+
 ## Auth
 
 The remote `module install --url` and `marketplace publish` flows need a JWT

package/dist/lib.d.mts

@@ -0,0 +1,66 @@
+type Preset = "minimal" | "minimal-plus" | "full";
+type Traits = "identity" | "identity+audit";
+interface EntitySpec {
+    name: string;
+    label: string;
+    traits: Traits;
+}
+interface ScaffoldOpts {
+    path: string;
+    code: string;
+    displayName: string;
+    description: string;
+    author: string;
+    license: string;
+    version: string;
+    dbSchemaVersion: string;
+    dependencies: string[];
+    preset: Preset;
+    entities: EntitySpec[];
+}
+interface Manifest {
+    packageFormat: number;
+    moduleId: string;
+    code: string;
+    version: string;
+    dbSchemaVersion: string;
+    displayName: string;
+    description?: string;
+    author?: {
+        name: string;
+    };
+    license?: string;
+    dependencies?: Record<string, string>;
+    entities: Record<string, string>;
+    created?: string;
+    updated?: string;
+}
+interface Entity {
+    description: string;
+    dbObject: string;
+    toString: string;
+    traits: string[];
+    fields: Record<string, unknown>;
+}
+interface DataView {
+    viewType: string;
+    label: string;
+    dataSources: Array<{
+        entityCode: string;
+        columns: string[];
+    }>;
+}
+
+declare function buildManifest(opts: ScaffoldOpts, moduleId: string): Manifest;
+declare function buildEntity(entity: EntitySpec): Entity;
+declare function buildDataViews(entities: EntitySpec[]): Record<string, DataView>;
+declare function buildFolders(opts: ScaffoldOpts): Record<string, unknown>;
+declare function buildMenus(opts: ScaffoldOpts): Record<string, unknown>;
+declare function buildRoles(opts: ScaffoldOpts): Record<string, unknown>;
+declare function buildActions(): Record<string, unknown>;
+declare function buildSettings(): Record<string, unknown>;
+declare function buildTranslations(opts: ScaffoldOpts): Record<string, string>;
+declare function buildSeedData(): unknown[];
+declare function buildGitignore(): string;
+
+export { type DataView, type Entity, type EntitySpec, type Manifest, type Preset, type ScaffoldOpts, type Traits, buildActions, buildDataViews, buildEntity, buildFolders, buildGitignore, buildManifest, buildMenus, buildRoles, buildSeedData, buildSettings, buildTranslations };

package/dist/lib.d.ts

@@ -0,0 +1,66 @@
+type Preset = "minimal" | "minimal-plus" | "full";
+type Traits = "identity" | "identity+audit";
+interface EntitySpec {
+    name: string;
+    label: string;
+    traits: Traits;
+}
+interface ScaffoldOpts {
+    path: string;
+    code: string;
+    displayName: string;
+    description: string;
+    author: string;
+    license: string;
+    version: string;
+    dbSchemaVersion: string;
+    dependencies: string[];
+    preset: Preset;
+    entities: EntitySpec[];
+}
+interface Manifest {
+    packageFormat: number;
+    moduleId: string;
+    code: string;
+    version: string;
+    dbSchemaVersion: string;
+    displayName: string;
+    description?: string;
+    author?: {
+        name: string;
+    };
+    license?: string;
+    dependencies?: Record<string, string>;
+    entities: Record<string, string>;
+    created?: string;
+    updated?: string;
+}
+interface Entity {
+    description: string;
+    dbObject: string;
+    toString: string;
+    traits: string[];
+    fields: Record<string, unknown>;
+}
+interface DataView {
+    viewType: string;
+    label: string;
+    dataSources: Array<{
+        entityCode: string;
+        columns: string[];
+    }>;
+}
+
+declare function buildManifest(opts: ScaffoldOpts, moduleId: string): Manifest;
+declare function buildEntity(entity: EntitySpec): Entity;
+declare function buildDataViews(entities: EntitySpec[]): Record<string, DataView>;
+declare function buildFolders(opts: ScaffoldOpts): Record<string, unknown>;
+declare function buildMenus(opts: ScaffoldOpts): Record<string, unknown>;
+declare function buildRoles(opts: ScaffoldOpts): Record<string, unknown>;
+declare function buildActions(): Record<string, unknown>;
+declare function buildSettings(): Record<string, unknown>;
+declare function buildTranslations(opts: ScaffoldOpts): Record<string, string>;
+declare function buildSeedData(): unknown[];
+declare function buildGitignore(): string;
+
+export { type DataView, type Entity, type EntitySpec, type Manifest, type Preset, type ScaffoldOpts, type Traits, buildActions, buildDataViews, buildEntity, buildFolders, buildGitignore, buildManifest, buildMenus, buildRoles, buildSeedData, buildSettings, buildTranslations };

package/dist/lib.js

@@ -0,0 +1,178 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib.ts
+var lib_exports = {};
+__export(lib_exports, {
+  buildActions: () => buildActions,
+  buildDataViews: () => buildDataViews,
+  buildEntity: () => buildEntity,
+  buildFolders: () => buildFolders,
+  buildGitignore: () => buildGitignore,
+  buildManifest: () => buildManifest,
+  buildMenus: () => buildMenus,
+  buildRoles: () => buildRoles,
+  buildSeedData: () => buildSeedData,
+  buildSettings: () => buildSettings,
+  buildTranslations: () => buildTranslations
+});
+module.exports = __toCommonJS(lib_exports);
+
+// src/init/templates.ts
+function buildManifest(opts, moduleId) {
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const manifest = {
+    packageFormat: 1,
+    moduleId,
+    code: opts.code,
+    version: opts.version,
+    dbSchemaVersion: opts.dbSchemaVersion,
+    displayName: opts.displayName,
+    entities: Object.fromEntries(
+      opts.entities.map((e) => [e.name, `./entities/${e.name}.json`])
+    ),
+    created: today,
+    updated: today
+  };
+  if (opts.description) manifest.description = opts.description;
+  if (opts.author) manifest.author = { name: opts.author };
+  if (opts.license) manifest.license = opts.license;
+  if (opts.dependencies.length > 0) {
+    manifest.dependencies = Object.fromEntries(
+      opts.dependencies.map((d) => [d, ">=0.0.1"])
+    );
+  }
+  return manifest;
+}
+function buildEntity(entity) {
+  const traits = entity.traits === "identity+audit" ? ["identity", "audit"] : ["identity"];
+  return {
+    description: entity.label,
+    dbObject: entity.name,
+    toString: "{id}",
+    traits,
+    fields: {}
+  };
+}
+function buildDataViews(entities) {
+  const views = {};
+  for (const e of entities) {
+    views[e.name] = {
+      viewType: "grid",
+      label: e.label,
+      dataSources: [
+        {
+          entityCode: e.name,
+          columns: []
+        }
+      ]
+    };
+  }
+  return views;
+}
+function buildFolders(opts) {
+  return {
+    [opts.code]: {
+      label: opts.displayName,
+      description: opts.description || opts.displayName,
+      icon: "bi-folder",
+      color: "#2196F3",
+      entities: Object.fromEntries(
+        opts.entities.map((e) => [
+          e.name,
+          { viewName: e.name, quickAdd: true }
+        ])
+      )
+    }
+  };
+}
+function buildMenus(opts) {
+  return {
+    [opts.code]: {
+      label: opts.displayName,
+      icon: "bi-folder",
+      children: Object.fromEntries(
+        opts.entities.map((e) => [
+          e.name,
+          {
+            itemType: "V",
+            label: e.label,
+            dataViewCode: e.name
+          }
+        ])
+      )
+    }
+  };
+}
+function buildRoles(opts) {
+  const rights = {};
+  for (const e of opts.entities) rights[e.name] = "SIUDC";
+  return {
+    [`${opts.code}.admin`]: {
+      description: `${opts.displayName} administrators`,
+      rights
+    }
+  };
+}
+function buildActions() {
+  return {};
+}
+function buildSettings() {
+  return {};
+}
+function buildTranslations(opts) {
+  const t = {};
+  t[`module.${opts.code}.label`] = opts.displayName;
+  if (opts.description) t[`module.${opts.code}.description`] = opts.description;
+  for (const e of opts.entities) {
+    t[`entity.${e.name}.label`] = e.label;
+    t[`view.${e.name}.label`] = e.label;
+    t[`menu.${e.name}.label`] = e.label;
+  }
+  return t;
+}
+function buildSeedData() {
+  return [];
+}
+function buildGitignore() {
+  return [
+    "# Built module package archives",
+    "*.dforge",
+    "",
+    "# Editor / OS noise",
+    "node_modules/",
+    ".DS_Store",
+    "*.swp",
+    ""
+  ].join("\n");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildActions,
+  buildDataViews,
+  buildEntity,
+  buildFolders,
+  buildGitignore,
+  buildManifest,
+  buildMenus,
+  buildRoles,
+  buildSeedData,
+  buildSettings,
+  buildTranslations
+});

package/dist/lib.mjs

@@ -0,0 +1,141 @@
+// src/init/templates.ts
+function buildManifest(opts, moduleId) {
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const manifest = {
+    packageFormat: 1,
+    moduleId,
+    code: opts.code,
+    version: opts.version,
+    dbSchemaVersion: opts.dbSchemaVersion,
+    displayName: opts.displayName,
+    entities: Object.fromEntries(
+      opts.entities.map((e) => [e.name, `./entities/${e.name}.json`])
+    ),
+    created: today,
+    updated: today
+  };
+  if (opts.description) manifest.description = opts.description;
+  if (opts.author) manifest.author = { name: opts.author };
+  if (opts.license) manifest.license = opts.license;
+  if (opts.dependencies.length > 0) {
+    manifest.dependencies = Object.fromEntries(
+      opts.dependencies.map((d) => [d, ">=0.0.1"])
+    );
+  }
+  return manifest;
+}
+function buildEntity(entity) {
+  const traits = entity.traits === "identity+audit" ? ["identity", "audit"] : ["identity"];
+  return {
+    description: entity.label,
+    dbObject: entity.name,
+    toString: "{id}",
+    traits,
+    fields: {}
+  };
+}
+function buildDataViews(entities) {
+  const views = {};
+  for (const e of entities) {
+    views[e.name] = {
+      viewType: "grid",
+      label: e.label,
+      dataSources: [
+        {
+          entityCode: e.name,
+          columns: []
+        }
+      ]
+    };
+  }
+  return views;
+}
+function buildFolders(opts) {
+  return {
+    [opts.code]: {
+      label: opts.displayName,
+      description: opts.description || opts.displayName,
+      icon: "bi-folder",
+      color: "#2196F3",
+      entities: Object.fromEntries(
+        opts.entities.map((e) => [
+          e.name,
+          { viewName: e.name, quickAdd: true }
+        ])
+      )
+    }
+  };
+}
+function buildMenus(opts) {
+  return {
+    [opts.code]: {
+      label: opts.displayName,
+      icon: "bi-folder",
+      children: Object.fromEntries(
+        opts.entities.map((e) => [
+          e.name,
+          {
+            itemType: "V",
+            label: e.label,
+            dataViewCode: e.name
+          }
+        ])
+      )
+    }
+  };
+}
+function buildRoles(opts) {
+  const rights = {};
+  for (const e of opts.entities) rights[e.name] = "SIUDC";
+  return {
+    [`${opts.code}.admin`]: {
+      description: `${opts.displayName} administrators`,
+      rights
+    }
+  };
+}
+function buildActions() {
+  return {};
+}
+function buildSettings() {
+  return {};
+}
+function buildTranslations(opts) {
+  const t = {};
+  t[`module.${opts.code}.label`] = opts.displayName;
+  if (opts.description) t[`module.${opts.code}.description`] = opts.description;
+  for (const e of opts.entities) {
+    t[`entity.${e.name}.label`] = e.label;
+    t[`view.${e.name}.label`] = e.label;
+    t[`menu.${e.name}.label`] = e.label;
+  }
+  return t;
+}
+function buildSeedData() {
+  return [];
+}
+function buildGitignore() {
+  return [
+    "# Built module package archives",
+    "*.dforge",
+    "",
+    "# Editor / OS noise",
+    "node_modules/",
+    ".DS_Store",
+    "*.swp",
+    ""
+  ].join("\n");
+}
+export {
+  buildActions,
+  buildDataViews,
+  buildEntity,
+  buildFolders,
+  buildGitignore,
+  buildManifest,
+  buildMenus,
+  buildRoles,
+  buildSeedData,
+  buildSettings,
+  buildTranslations
+};

package/package.json

@@ -1,12 +1,12 @@
 {
 	"name": "@dforge-core/dforge-cli",
-	"version": "0.1.0-rc.3",
-	"description": "dForge CLI \u2014 validate, pack, publish, and install dForge modules. Distributes a single-file native binary per platform via optionalDependencies (esbuild-style).",
+	"version": "0.1.0-rc.5",
+	"description": "dForge CLI - validate, pack, publish, and install dForge modules. Distributes a single-file native binary per platform via optionalDependencies (esbuild-style).",
 	"license": "MIT",
 	"homepage": "https://github.com/iash44/dForge-core",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/dforge-core/dforge-cli.git"
+		"url": "git+https://github.com/dforge-core/dforge-cli.git"
 	},
 	"bin": {
 		"dforge-cli": "dist/cli.js"
@@ -16,6 +16,14 @@
 		"README.md"
 	],
 	"main": "dist/cli.js",
+	"exports": {
+		".": "./dist/cli.js",
+		"./templates": {
+			"types": "./dist/lib.d.ts",
+			"import": "./dist/lib.mjs",
+			"require": "./dist/lib.js"
+		}
+	},
 	"engines": {
 		"node": ">=18"
 	},