@dforge-core/dforge-mcp 0.2.18 → 0.2.22

package/CHANGELOG.md

@@ -4,6 +4,78 @@ All notable changes to `@dforge-core/dforge-mcp`. This project uses semver-ish
 `0.1.0-rc.N` pre-release tags; the published version is set at publish time via
 the release workflow, so committed `package.json` versions are placeholders.
 
+## 0.2.19
+
+A module could declare a dependency but not ship the contract the platform
+requires for it, and nothing here said the contract existed. The manifest
+reference's own minimal example carried a dependency on `admin` that made every
+module copying it unpackable.
+
+### Fixed — `dforge_dependency_add` writes the contract, not just the manifest
+
+Every entry in a manifest's `dependencies` needs a matching `deps/<module>.json`
+contract declaring what the module consumes from that dependency; without it the
+package fails `dforge_module_validate`, `dforge_module_pack` and install alike.
+The tool wrote only the manifest half, so the one tool meant to author this exact
+manifest key left the module in a state it could not be packed from
+(dForge-core#1090).
+
+It now writes both files, with the version mirrored verbatim — the validator
+compares the two ranges and a drift is a hard error.
+
+`entities` is now **required**, and that is the point rather than a side effect: a
+contract must name at least one consumed entity, and a dependency you cannot name
+one for is a dependency you should not declare. Two new optional inputs carry the
+detail the contract records — `use` for provenance tokens (`ref:invoice.customer`,
+`extends:parties.party`, `role:fin_admin`) and `pks` to override a provider primary
+key that is not `<entity>_id`. Both are guessed when omitted and the result says so.
+
+Declaring a system module (`admin`, `metadata`, `workspace`) now warns: they are
+provisioned into every tenant before any other module installs, so depending on one
+buys nothing on its own — the only meaningful use is gating a minimum platform
+version for a feature, and that still needs a contract naming the entity the feature
+introduced. The tool also refuses to overwrite an existing contract file.
+
+### Fixed — the manifest reference told authors to always depend on `admin`
+
+`dforge://reference/manifest` carried **"Always depend on `admin`"** in bold, and
+put `"admin": ">=0.0.1"` in its minimal example and its bridge-module example. That
+advice predates dependency contracts and now produces a module that cannot be
+packed. All three are corrected, and the reference gains a **Dependency contracts**
+section: the file shape, the version-match rule, storage classes (`int8` for a
+`cuid` primary key), which columns must never be declared, and the provenance kinds.
+
+### Added — `dforge://schema/deps`
+
+`deps.schema.json` shipped in the package but was never registered as a resource, so
+an author who found the file name still had no way to read its shape. It is now
+served like every other schema.
+
+### Added — scheduled jobs resolve folder-scoped settings
+
+`dforge://reference/jobs` and `.../settings` document the folder a cron fire runs in.
+A scheduled action has no user, so nothing supplies a folder the way a request does;
+the scheduler binds `scheduled_job.folder_id` when an admin has set one, and the
+owning module's root folder otherwise. That is what makes `getSetting()` and
+`nextNumber()` resolve inside a job. There is no `folder` key in the manifest — the
+binding is operator state, and an upgrade never overwrites it.
+
+### Changed — scaffolded entities ship a `name` column
+
+`@dforge-core/dforge-cli` 0.2.17 gives the `identity` trait a visible `name`
+column (`varchar`, `VEM`) and points the entity's `toString` at `{name}`. An
+entity with only a PK and audit stamps had nothing renderable: its grid view
+failed the data-view column check and `toString` had nothing to interpolate.
+That is the upstream fix `withIdentityToString`'s `{id}` repair was standing in
+for, so the repair no longer fires on freshly scaffolded modules.
+
+### Added — `dforge_module_create` writes `.zed/tasks.json`
+
+Zed has no extension command API, so the pack / install / auth dev loop ships as
+project-local tasks. Read off the CLI templates module by feature detection rather
+than imported: the helper landed after `@dforge-core/dforge-cli` 0.2.16, and
+scaffolding must not break for anyone still on an older CLI.
+
 ## 0.2.18
 
 Every counter a module updates — an on-hand quantity, a running balance, a used

package/dist/server.js

@@ -3226,8 +3226,8 @@ var require_utils = __commonJS({
       }
       return ind;
     }
-    function removeDotSegments(path17) {
-      let input = path17;
+    function removeDotSegments(path18) {
+      let input = path18;
       const output = [];
       let nextSlash = -1;
       let len = 0;
@@ -3479,8 +3479,8 @@ var require_schemes = __commonJS({
         wsComponent.secure = void 0;
       }
       if (wsComponent.resourceName) {
-        const [path17, query] = wsComponent.resourceName.split("?");
-        wsComponent.path = path17 && path17 !== "/" ? path17 : void 0;
+        const [path18, query] = wsComponent.resourceName.split("?");
+        wsComponent.path = path18 && path18 !== "/" ? path18 : void 0;
         wsComponent.query = query;
         wsComponent.resourceName = void 0;
       }
@@ -6899,12 +6899,12 @@ var require_dist = __commonJS({
         throw new Error(`Unknown format "${name}"`);
       return f;
     };
-    function addFormats(ajv, list, fs14, exportName) {
+    function addFormats(ajv, list, fs15, exportName) {
       var _a3;
       var _b;
       (_a3 = (_b = ajv.opts.code).formats) !== null && _a3 !== void 0 ? _a3 : _b.formats = (0, codegen_1._)`require("ajv-formats/dist/formats").${exportName}`;
       for (const f of list)
-        ajv.addFormat(f, fs14[f]);
+        ajv.addFormat(f, fs15[f]);
     }
     module2.exports = exports2 = formatsPlugin;
     Object.defineProperty(exports2, "__esModule", { value: true });
@@ -7271,8 +7271,8 @@ function getErrorMap() {
 
 // node_modules/.pnpm/zod@4.4.3/node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path: path17, errorMaps, issueData } = params;
-  const fullPath = [...path17, ...issueData.path || []];
+  const { data, path: path18, errorMaps, issueData } = params;
+  const fullPath = [...path18, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -7387,11 +7387,11 @@ var errorUtil;
 
 // node_modules/.pnpm/zod@4.4.3/node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path17, key) {
+  constructor(parent, value, path18, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path17;
+    this._path = path18;
     this._key = key;
   }
   get path() {
@@ -11311,10 +11311,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema2) {
   return mergeDefs(schema2._zod.def);
 }
-function getElementAtPath(obj, path17) {
-  if (!path17)
+function getElementAtPath(obj, path18) {
+  if (!path18)
     return obj;
-  return path17.reduce((acc, key) => acc?.[key], obj);
+  return path18.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -11723,11 +11723,11 @@ function explicitlyAborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path17, issues) {
+function prefixIssues(path18, issues) {
   return issues.map((iss) => {
     var _a3;
     (_a3 = iss).path ?? (_a3.path = []);
-    iss.path.unshift(path17);
+    iss.path.unshift(path18);
     return iss;
   });
 }
@@ -11874,16 +11874,16 @@ function flattenError(error51, mapper = (issue2) => issue2.message) {
 }
 function formatError(error51, mapper = (issue2) => issue2.message) {
   const fieldErrors = { _errors: [] };
-  const processError = (error52, path17 = []) => {
+  const processError = (error52, path18 = []) => {
     for (const issue2 of error52.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path17, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path18, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path17, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path18, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path17, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path18, ...issue2.path]);
       } else {
-        const fullpath = [...path17, ...issue2.path];
+        const fullpath = [...path18, ...issue2.path];
         if (fullpath.length === 0) {
           fieldErrors._errors.push(mapper(issue2));
         } else {
@@ -11910,17 +11910,17 @@ function formatError(error51, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error51, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error52, path17 = []) => {
+  const processError = (error52, path18 = []) => {
     var _a3, _b;
     for (const issue2 of error52.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path17, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path18, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path17, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path18, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path17, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path18, ...issue2.path]);
       } else {
-        const fullpath = [...path17, ...issue2.path];
+        const fullpath = [...path18, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -11952,8 +11952,8 @@ function treeifyError(error51, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path17 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path17) {
+  const path18 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path18) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -23065,11 +23065,11 @@ function normalizeObjectSchema(schema2) {
   }
   return void 0;
 }
-function getDotPath(path17) {
-  if (path17.length === 0) {
+function getDotPath(path18) {
+  if (path18.length === 0) {
     return "object root";
   }
-  return path17.reduce((acc, seg, index) => {
+  return path18.reduce((acc, seg, index) => {
     if (index === 0) {
       return String(seg);
     }
@@ -25094,13 +25094,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path17 = ref.slice(1).split("/").filter(Boolean);
-  if (path17.length === 0) {
+  const path18 = ref.slice(1).split("/").filter(Boolean);
+  if (path18.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path17[0] === defsKey) {
-    const key = path17[1];
+  if (path18[0] === defsKey) {
+    const key = path18[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -31002,7 +31002,7 @@ var import_node_crypto = require("crypto");
 var fs2 = __toESM(require("fs"));
 var path2 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.16/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
+// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.17/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
 function buildManifest(opts, moduleId) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const manifest = {
@@ -31023,19 +31023,36 @@ function buildManifest(opts, moduleId) {
   if (opts.license) manifest.license = opts.license;
   if (opts.dependencies.length > 0) {
     manifest.dependencies = Object.fromEntries(
-      opts.dependencies.map((d) => [d, ">=0.0.1"])
+      opts.dependencies.map(
+        (d) => typeof d === "string" ? [d, DEPENDENCY_RANGE] : [d.module, { version: DEPENDENCY_RANGE, entities: d.entities }]
+      )
     );
   }
   return manifest;
 }
+var DEPENDENCY_RANGE = ">=0.0.1";
+var NAME_FIELD = "name";
 function buildEntity(entity) {
   const traits2 = entity.traits === "identity+audit" ? ["identity", "audit"] : ["identity"];
   const built = {
     description: entity.label,
     dbObject: entity.name,
-    toString: "{id}",
+    // The traits only add a PK and audit stamps, so an entity with no fields
+    // of its own has nothing renderable: its grid view fails the data-view
+    // column check and `toString` has nothing to interpolate. Scaffold one
+    // visible name column so the module validates and the grid shows a row.
+    toString: `{${NAME_FIELD}}`,
     traits: traits2,
-    fields: {}
+    fields: {
+      [NAME_FIELD]: {
+        dbDatatype: "varchar",
+        fieldTypeCd: "text",
+        flags: "VEM",
+        maxLen: 200,
+        orderNum: 10,
+        description: "Name"
+      }
+    }
   };
   if (entity.constraints?.length) {
     built.constraints = Object.fromEntries(
@@ -31120,7 +31137,8 @@ function buildTranslations(opts) {
   for (const e of opts.entities) {
     const fields = {
       // identity trait → primary key column
-      [`${e.name}_id`]: { label: `${e.label} ID` }
+      [`${e.name}_id`]: { label: `${e.label} ID` },
+      [NAME_FIELD]: { label: "Name" }
     };
     if (e.traits === "identity+audit") {
       fields.created_date = { label: "Created Date" };
@@ -31161,8 +31179,9 @@ function buildTranslations(opts) {
     }
   };
 }
-function buildSeedData() {
-  return [];
+function buildSeedData(entity) {
+  const entityCode = typeof entity === "string" ? entity : entity?.name ?? "";
+  return { entityCode, records: [] };
 }
 function buildGitignore() {
   return [
@@ -31184,30 +31203,80 @@ var SCHEMA_BINDINGS = [
   { fileMatch: ["ui/folders.json"], schema: "folders" },
   { fileMatch: ["ui/menus.json"], schema: "menus" },
   { fileMatch: ["ui/reports.json"], schema: "reports" },
+  { fileMatch: ["ui/print_templates.json"], schema: "print-templates" },
   { fileMatch: ["security/roles.json"], schema: "roles" },
   { fileMatch: ["logic/jobs.json"], schema: "jobs" },
+  { fileMatch: ["logic/triggers.json"], schema: "triggers" },
+  { fileMatch: ["logic/webhooks.json"], schema: "webhooks" },
+  { fileMatch: ["deps/*.json"], schema: "deps" },
   { fileMatch: ["seed-data/*.json"], schema: "seed-data" },
   { fileMatch: ["settings.json"], schema: "settings" }
 ];
+function schemaEntries() {
+  return SCHEMA_BINDINGS.map((b) => ({
+    fileMatch: b.fileMatch,
+    url: `${SCHEMA_BASE}/${b.schema}.schema.json`
+  }));
+}
 function buildVscodeSettings() {
-  return {
-    "json.schemas": SCHEMA_BINDINGS.map((b) => ({
-      fileMatch: b.fileMatch,
-      url: `${SCHEMA_BASE}/${b.schema}.schema.json`
-    }))
-  };
+  return { "json.schemas": schemaEntries() };
 }
 function buildZedSettings() {
   return {
-    languages: {
-      JSON: {
-        "json.schemas": SCHEMA_BINDINGS.map((b) => ({
-          fileMatch: b.fileMatch,
-          url: `${SCHEMA_BASE}/${b.schema}.schema.json`
-        }))
+    lsp: {
+      "json-language-server": {
+        settings: { json: { schemas: schemaEntries() } }
       }
-    }
-  };
+    },
+    context_servers: {
+      dforge: {
+        source: "custom",
+        command: "npx",
+        args: ["-y", "@dforge-core/dforge-mcp@latest"],
+        env: {}
+      }
+    }
+  };
+}
+function buildZedTasks() {
+  const CLI = "npx";
+  const CLI_ARGS = ["-y", "@dforge-core/dforge-cli@latest"];
+  const DEFAULT_TENANT = "http://localhost:5179";
+  const task = (label, args) => ({
+    label: `dForge: ${label}`,
+    command: CLI,
+    args: [...CLI_ARGS, ...args],
+    cwd: "$ZED_WORKTREE_ROOT",
+    env: { DFORGE_URL: DEFAULT_TENANT },
+    use_new_terminal: false,
+    allow_concurrent_runs: false,
+    reveal: "always"
+  });
+  return [
+    task("Pack module", ["module", "pack", "$ZED_WORKTREE_ROOT"]),
+    // --force matches the extension's dev-loop default: without it the CLI
+    // skips the reinstall when the version hasn't changed and your edits
+    // silently never reach the tenant.
+    task("Install module to tenant", [
+      "module",
+      "install",
+      "--path",
+      "$ZED_WORKTREE_ROOT",
+      "--url",
+      "$DFORGE_URL",
+      "--force"
+    ]),
+    task("Sign in to tenant", [
+      "auth",
+      "login",
+      "--url",
+      "$DFORGE_URL",
+      "--login-url",
+      "$DFORGE_URL"
+    ]),
+    task("Show signed-in user", ["auth", "whoami", "--url", "$DFORGE_URL"]),
+    task("List installed modules", ["module", "list", "--url", "$DFORGE_URL"])
+  ];
 }
 
 // src/tools/_helpers.ts
@@ -31759,6 +31828,8 @@ function createModuleFiles(args) {
   writeText(".gitignore", buildGitignore());
   write(".vscode/settings.json", buildVscodeSettings());
   write(".zed/settings.json", buildZedSettings());
+  const buildZedTasks2 = buildZedTasks;
+  if (buildZedTasks2) write(".zed/tasks.json", buildZedTasks2());
   if (opts.preset === "full") {
     write("settings.json", buildSettings());
     write("translations/en-US.json", buildTranslations(opts));
@@ -35182,6 +35253,8 @@ ${warnings.map((w) => `  \u2022 ${w}`).join("\n")}` : void 0
 }
 
 // src/tools/adds.ts
+var fs10 = __toESM(require("fs"));
+var path13 = __toESM(require("path"));
 var reportAddSchema = {
   moduleDir: external_exports.string(),
   code: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Report code (keys ui/reports.json)."),
@@ -35326,16 +35399,23 @@ function folderAdd(args) {
     }
   );
 }
+var SYSTEM_MODULES = /* @__PURE__ */ new Set(["admin", "metadata", "workspace"]);
 var dependencyAddSchema = {
   moduleDir: external_exports.string(),
   moduleCode: external_exports.string().regex(/^[a-z][a-z0-9_-]*$/).describe("Module to depend on."),
   version: external_exports.string().default(">=0.1.0").describe("Semver range."),
-  entities: external_exports.array(external_exports.string()).optional().describe(
-    "If only specific entities from the dependency are used, list them \u2014 produces the object-style dep `{ version, entities }` for partial coupling. Omit to depend on the whole module."
+  entities: external_exports.array(external_exports.string()).min(1).describe(
+    "The provider entities this module consumes, e.g. ['party']. Required: every dependency needs a deps/<module>.json contract naming at least one entity, and a dependency you cannot name a consumed entity for should not be declared at all. Also narrows the manifest dep to the object form `{ version, entities }`."
+  ),
+  use: external_exports.array(external_exports.string()).optional().describe(
+    "Provenance tokens recorded against each declared entity: '<kind>:<symbol>' where kind is ref|extends|formula|action|view|report|print|role, e.g. 'ref:invoice.customer'. 'extends' must be fully qualified ('extends:parties.party'). Defaults to a placeholder you must refine."
+  ),
+  pks: external_exports.record(external_exports.string(), external_exports.string()).optional().describe(
+    `Override the provider PK column per entity, e.g. { "party": "party_uid" }. Defaults to '<entity>_id', which is what the 'identity' trait produces.`
   )
 };
 function dependencyAdd(args) {
-  const { manifest } = loadManifest(args.moduleDir);
+  const { manifest, paths } = loadManifest(args.moduleDir);
   if (manifest.code === args.moduleCode) {
     throw new Error("A module can't depend on itself.");
   }
@@ -35345,14 +35425,57 @@ function dependencyAdd(args) {
       `Dependency on '${args.moduleCode}' already exists. Edit manifest.json directly to change the version.`
     );
   }
-  const value = args.entities && args.entities.length > 0 ? { version: args.version, entities: args.entities } : args.version;
+  const contractPath = path13.join(paths.root, "deps", `${args.moduleCode}.json`);
+  if (fs10.existsSync(contractPath)) {
+    throw new Error(
+      `deps/${args.moduleCode}.json already exists but '${args.moduleCode}' is not a manifest dependency. Add the manifest entry by hand or delete the stale contract \u2014 this tool will not overwrite it.`
+    );
+  }
   const newManifest = withTodayStamp({
     ...manifest,
-    dependencies: { ...deps, [args.moduleCode]: value }
+    dependencies: {
+      ...deps,
+      [args.moduleCode]: { version: args.version, entities: args.entities }
+    }
   });
+  const placeholderUse = !args.use || args.use.length === 0;
+  const use = placeholderUse ? [`ref:${manifest.code}`] : args.use;
+  const contract = {
+    module: args.moduleCode,
+    version: args.version,
+    entities: Object.fromEntries(
+      args.entities.map((e) => [
+        e,
+        { pk: args.pks?.[e] ?? `${e}_id`, use: [...use] }
+      ])
+    )
+  };
+  const warnings = [];
+  if (placeholderUse) {
+    warnings.push(
+      `deps/${args.moduleCode}.json was written with a placeholder provenance token 'ref:${manifest.code}'. Replace it with the real usage (e.g. 'ref:<my_entity>.<my_column>', 'extends:${args.moduleCode}.<entity>', 'role:<role_cd>') \u2014 it is the record of WHY the dependency exists.`
+    );
+  }
+  if (!args.pks) {
+    warnings.push(
+      `PKs were guessed as '<entity>_id'. Check them against ${args.moduleCode}'s entity files \u2014 a wrong pk fails the install-time satisfaction check.`
+    );
+  }
+  if (SYSTEM_MODULES.has(args.moduleCode)) {
+    warnings.push(
+      `'${args.moduleCode}' is a system module \u2014 always provisioned, so this dependency is only meaningful as a minimum-platform-version gate. If you are not gating a platform feature, drop it.`
+    );
+  }
+  warnings.push(
+    `Declare the columns you actually read, write or join on under each entity's 'columns' \u2014 see dforge://schema/deps.`
+  );
   return makeResult(
-    `Added dependency on '${args.moduleCode}' (${args.version})${args.entities ? ` for entities [${args.entities.join(", ")}]` : ""}.`,
-    { "manifest.json": jsonText(newManifest) }
+    `Added dependency on '${args.moduleCode}' (${args.version}) for entities [${args.entities.join(", ")}], with the required deps/${args.moduleCode}.json contract.`,
+    {
+      "manifest.json": jsonText(newManifest),
+      [`deps/${args.moduleCode}.json`]: jsonText(contract)
+    },
+    warnings.join("\n")
   );
 }
 
@@ -35396,8 +35519,8 @@ function roleRightSet(args) {
 }
 
 // src/tools/module-inspect.ts
-var fs10 = __toESM(require("fs"));
-var path13 = __toESM(require("path"));
+var fs11 = __toESM(require("fs"));
+var path14 = __toESM(require("path"));
 var moduleInspectSchema = {
   moduleDir: external_exports.string()
 };
@@ -35405,7 +35528,7 @@ function moduleInspect(args) {
   const { paths, manifest } = loadManifest(args.moduleDir);
   const entities = manifest.entities ?? {};
   const entitySummaries = Object.entries(entities).map(([name, relPath]) => {
-    const abs = path13.join(paths.root, relPath.replace(/^\.\//, ""));
+    const abs = path14.join(paths.root, relPath.replace(/^\.\//, ""));
     const e = readJsonOrDefault(abs, {});
     const fields = e.fields ?? {};
     return {
@@ -35489,8 +35612,8 @@ function moduleInspect(args) {
     readJsonOrDefault(paths.printTemplates, {})
   );
   const domains = Object.keys(readJsonOrDefault(paths.domains, {}));
-  const seedFiles = fs10.existsSync(paths.seedDataDir) ? fs10.readdirSync(paths.seedDataDir).filter((f) => f.endsWith(".json")).sort() : [];
-  const translations = fs10.existsSync(paths.translationsDir) ? fs10.readdirSync(paths.translationsDir).filter((f) => f.endsWith(".json")).sort() : [];
+  const seedFiles = fs11.existsSync(paths.seedDataDir) ? fs11.readdirSync(paths.seedDataDir).filter((f) => f.endsWith(".json")).sort() : [];
+  const translations = fs11.existsSync(paths.translationsDir) ? fs11.readdirSync(paths.translationsDir).filter((f) => f.endsWith(".json")).sort() : [];
   const summary = {
     module: {
       code: manifest.code,
@@ -35534,8 +35657,8 @@ function computeDepth(folder, current = 1) {
 }
 
 // src/tools/module-validate.ts
-var fs11 = __toESM(require("fs"));
-var path14 = __toESM(require("path"));
+var fs12 = __toESM(require("fs"));
+var path15 = __toESM(require("path"));
 var moduleValidateSchema = {
   moduleDir: external_exports.string().describe("Path to the module root. Run this after authoring and before dforge_module_pack.")
 };
@@ -35555,12 +35678,12 @@ function hasVisibleScalarColumn(fields) {
   return false;
 }
 function resolveTranslationFile(translationsDir, locale) {
-  const exact = path14.join(translationsDir, `${locale}.json`);
-  if (fs11.existsSync(exact)) return exact;
-  if (!fs11.existsSync(translationsDir)) return void 0;
+  const exact = path15.join(translationsDir, `${locale}.json`);
+  if (fs12.existsSync(exact)) return exact;
+  if (!fs12.existsSync(translationsDir)) return void 0;
   const want = `${locale}.json`.toLowerCase();
-  for (const f of fs11.readdirSync(translationsDir)) {
-    if (f.toLowerCase() === want) return path14.join(translationsDir, f);
+  for (const f of fs12.readdirSync(translationsDir)) {
+    if (f.toLowerCase() === want) return path15.join(translationsDir, f);
   }
   return void 0;
 }
@@ -35588,14 +35711,14 @@ function moduleValidate(args) {
   const fieldDefsOf = {};
   for (const [name, relPath] of Object.entries(entityMap)) {
     if (name.includes(".")) continue;
-    const abs = path14.join(paths.root, relPath.replace(/^\.\//, ""));
-    if (!fs11.existsSync(abs)) {
+    const abs = path15.join(paths.root, relPath.replace(/^\.\//, ""));
+    if (!fs12.existsSync(abs)) {
       err(`manifest.entities.${name}`, `points to '${relPath}' which does not exist on disk`);
       continue;
     }
     let e;
     try {
-      e = JSON.parse(fs11.readFileSync(abs, "utf8"));
+      e = JSON.parse(fs12.readFileSync(abs, "utf8"));
     } catch (ex) {
       err(`entities/${name}.json`, `invalid JSON: ${ex.message}`);
       continue;
@@ -35831,7 +35954,7 @@ function moduleValidate(args) {
         const abs = resolveTranslationFile(paths.translationsDir, locale);
         if (abs) {
           try {
-            tx = JSON.parse(fs11.readFileSync(abs, "utf8"));
+            tx = JSON.parse(fs12.readFileSync(abs, "utf8"));
           } catch {
             tx = null;
           }
@@ -35947,7 +36070,7 @@ function moduleValidate(args) {
         where,
         `script '${script}' must be a BARE filename \u2014 no path, no '.dsl' extension (e.g. "script": "${script.replace(/\.dsl$/, "").split(/[\\/]/).pop()}").`
       );
-    } else if (!fs11.existsSync(path14.join(paths.logicDir, "actions", `${script}.dsl`))) {
+    } else if (!fs12.existsSync(path15.join(paths.logicDir, "actions", `${script}.dsl`))) {
       err(where, `script '${script}' has no file at logic/actions/${script}.dsl.`);
     }
     const ent = act.entityCode ?? act.entity;
@@ -35987,11 +36110,11 @@ function moduleValidate(args) {
     if (act && act in actions) {
       const script = actions[act]?.script;
       if (typeof script === "string") {
-        const dslPath = path14.join(paths.logicDir, "actions", `${script}.dsl`);
-        if (fs11.existsSync(dslPath)) {
+        const dslPath = path15.join(paths.logicDir, "actions", `${script}.dsl`);
+        if (fs12.existsSync(dslPath)) {
           let body = "";
           try {
-            body = fs11.readFileSync(dslPath, "utf8");
+            body = fs12.readFileSync(dslPath, "utf8");
           } catch {
           }
           for (const issue2 of checkDsl(body, { viaJob: true })) {
@@ -36015,11 +36138,11 @@ function moduleValidate(args) {
   for (const [acode, a] of Object.entries(actions)) {
     const script = a?.script;
     if (typeof script !== "string" || !script) continue;
-    const dslPath = path14.join(paths.logicDir, "actions", `${script}.dsl`);
-    if (!fs11.existsSync(dslPath)) continue;
+    const dslPath = path15.join(paths.logicDir, "actions", `${script}.dsl`);
+    if (!fs12.existsSync(dslPath)) continue;
     let body;
     try {
-      body = fs11.readFileSync(dslPath, "utf8");
+      body = fs12.readFileSync(dslPath, "utf8");
     } catch {
       continue;
     }
@@ -36177,7 +36300,7 @@ function moduleValidate(args) {
     }
   }
   const roleCodes = Object.keys(roles);
-  const localeFiles = fs11.existsSync(paths.translationsDir) ? fs11.readdirSync(paths.translationsDir).filter((f) => f.toLowerCase().endsWith(".json")).sort() : [];
+  const localeFiles = fs12.existsSync(paths.translationsDir) ? fs12.readdirSync(paths.translationsDir).filter((f) => f.toLowerCase().endsWith(".json")).sort() : [];
   for (const raw of supportedLocales) {
     const locale = raw.trim();
     if (!locale) continue;
@@ -36197,7 +36320,7 @@ function moduleValidate(args) {
   for (const file2 of localeFiles) {
     let tx;
     try {
-      tx = JSON.parse(fs11.readFileSync(path14.join(paths.translationsDir, file2), "utf8"));
+      tx = JSON.parse(fs12.readFileSync(path15.join(paths.translationsDir, file2), "utf8"));
     } catch (ex) {
       err(`translations/${file2}`, `invalid JSON: ${ex.message}`);
       continue;
@@ -36382,18 +36505,18 @@ function webhookAdd(args) {
 }
 
 // src/tools/apply.ts
-var fs12 = __toESM(require("fs"));
-var path15 = __toESM(require("path"));
+var fs13 = __toESM(require("fs"));
+var path16 = __toESM(require("path"));
 var applyInput = {
   apply: external_exports.boolean().default(false).describe(
     "When true, WRITE the resulting files to disk (and remove any `deletes`) instead of returning their contents for the client to write. The response then lists the paths touched. Use it for routine patches the user isn't reviewing line-by-line; leave it false when you want to preview a diff first."
   )
 };
-var isReportPayload = (relPath) => path15.basename(relPath).startsWith("_");
+var isReportPayload = (relPath) => path16.basename(relPath).startsWith("_");
 function resolveInside(root, relPath) {
-  const abs = path15.resolve(root, relPath);
-  const rel2 = path15.relative(root, abs);
-  if (rel2.startsWith("..") || path15.isAbsolute(rel2)) {
+  const abs = path16.resolve(root, relPath);
+  const rel2 = path16.relative(root, abs);
+  if (rel2.startsWith("..") || path16.isAbsolute(rel2)) {
     throw new Error(
       `Refusing to write '${relPath}' \u2014 it resolves outside the module directory (${abs}).`
     );
@@ -36401,7 +36524,7 @@ function resolveInside(root, relPath) {
   return abs;
 }
 function applyToDisk(moduleDir, result) {
-  const root = path15.resolve(moduleDir);
+  const root = path16.resolve(moduleDir);
   const written = [];
   const skipped = [];
   for (const [relPath, contents] of Object.entries(result.files ?? {})) {
@@ -36410,8 +36533,8 @@ function applyToDisk(moduleDir, result) {
       continue;
     }
     const abs = resolveInside(root, relPath);
-    fs12.mkdirSync(path15.dirname(abs), { recursive: true });
-    fs12.writeFileSync(abs, contents, "utf8");
+    fs13.mkdirSync(path16.dirname(abs), { recursive: true });
+    fs13.writeFileSync(abs, contents, "utf8");
     written.push(relPath);
   }
   const deleted = [];
@@ -36419,7 +36542,7 @@ function applyToDisk(moduleDir, result) {
     const abs = resolveInside(root, relPath);
     let stat;
     try {
-      stat = fs12.lstatSync(abs);
+      stat = fs13.lstatSync(abs);
     } catch {
       continue;
     }
@@ -36428,7 +36551,7 @@ function applyToDisk(moduleDir, result) {
         `Refusing to delete '${relPath}': it is a directory, and \`deletes\` is a file-only contract (it exists to remove a renamed entity's old JSON or an orphaned seed file). Remove the directory by hand if that is really what you want.`
       );
     }
-    fs12.rmSync(abs, { force: true });
+    fs13.rmSync(abs, { force: true });
     deleted.push(relPath);
   }
   const out = {
@@ -36443,10 +36566,10 @@ function applyToDisk(moduleDir, result) {
 }
 
 // src/resources/index.ts
-var fs13 = __toESM(require("fs"));
-var path16 = __toESM(require("path"));
-var RESOURCES_DIR = path16.resolve(__dirname, "..", "resources");
-var SKILL_DIR = path16.resolve(__dirname, "..", "skills", "dforge-mcp-author");
+var fs14 = __toESM(require("fs"));
+var path17 = __toESM(require("path"));
+var RESOURCES_DIR = path17.resolve(__dirname, "..", "resources");
+var SKILL_DIR = path17.resolve(__dirname, "..", "skills", "dforge-mcp-author");
 function schema(name, label, description) {
   return {
     uri: `dforge://schema/${name}`,
@@ -36498,6 +36621,11 @@ var resources = [
     "Module manifest JSON schema",
     "JSON Schema for manifest.json. Consult before emitting manifest content \u2014 covers required fields, semver patterns, and the entities map."
   ),
+  schema(
+    "deps",
+    "Dependency contract JSON schema",
+    "JSON Schema for deps/<module_code>.json \u2014 the import list of what this module consumes from one dependency. Every manifest 'dependencies' entry needs one or the package will not validate, pack or install."
+  ),
   schema(
     "entity",
     "Entity JSON schema",
@@ -36639,20 +36767,20 @@ var resources = [
   columnSecurityExample("README.md", "Why entity views exist, what each of the two views demonstrates, and the five ways a view fails the install.")
 ];
 function readVendored(rel2) {
-  const p = path16.join(RESOURCES_DIR, rel2);
-  if (!fs13.existsSync(p)) {
+  const p = path17.join(RESOURCES_DIR, rel2);
+  if (!fs14.existsSync(p)) {
     return `// Resource missing at build time: ${rel2}
 // Run scripts/vendor-resources.sh in dforge-mcp to refresh from dForge-core.`;
   }
-  return fs13.readFileSync(p, "utf8");
+  return fs14.readFileSync(p, "utf8");
 }
 function readSkill(rel2) {
-  const p = path16.join(SKILL_DIR, rel2);
-  if (!fs13.existsSync(p)) {
+  const p = path17.join(SKILL_DIR, rel2);
+  if (!fs14.existsSync(p)) {
     return `// Skill resource missing: ${rel2}
 // Expected under skills/dforge-mcp-author/ \u2014 check the package 'files' list.`;
   }
-  return fs13.readFileSync(p, "utf8");
+  return fs14.readFileSync(p, "utf8");
 }
 
 // src/server.ts
@@ -37020,7 +37148,7 @@ server.registerTool(
   "dforge_dependency_add",
   {
     title: "Add a module dependency",
-    description: "Add a dependency on another dForge module to manifest.json. Use the entities list form when only specific entities are imported (smaller coupling).",
+    description: "Add a dependency on another dForge module. Writes BOTH halves the platform requires: the manifest.json entry and the deps/<module>.json contract declaring what this module consumes \u2014 a manifest dependency without a contract fails validate, pack and install. Name the consumed entities in `entities`; do not declare a dependency you cannot name one for, and do not depend on the system modules (admin, metadata, workspace) except to gate a minimum platform version.",
     inputSchema: { ...dependencyAddSchema, ...applyInput }
   },
   envelope(dependencyAdd)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.2.18",
+	"version": "0.2.22",
 	"description": "MCP server for dForge module authoring. Exposes 34 scaffold/patch/validate/pack/install tools and schema resources so AI agents (Claude Code, Cursor, Zed) can create and ship dForge modules.",
 	"license": "MIT",
 	"homepage": "https://github.com/iash44/dForge-core",
@@ -35,7 +35,7 @@
 		"install-skills": "node scripts/install-skills.mjs"
 	},
 	"dependencies": {
-		"@dforge-core/dforge-cli": "^0.2.16",
+		"@dforge-core/dforge-cli": "^0.2.17",
 		"@dforge-core/metadata": "^0.0.22",
 		"@modelcontextprotocol/sdk": "^1.30.0",
 		"zod": "^4.4.3"

package/skills/dforge-mcp-author/references/jobs.md

@@ -35,7 +35,7 @@ Lives in: `logic/jobs.json` at the module root. Schema: [`docs/schemas/jobs.sche
 | `concurrency`    | No       | `1`          | Max parallel runs `[1, 5]`. `1` = single-instance.                                                                                   |
 | `idempotencyKey` | No       |              | Template like `"{job_cd}:{run.month}"`. Successful run with same key blocks re-dispatch.                                             |
 | `timeZone`       | No       | tenant tz    | IANA name. Falls back to `auth.tenant.time_zone`.                                                                                    |
-| `params`         | No       | `{}`         | Static parameters passed to the action as `__params`. For runtime values, use folder-scoped module settings.                         |
+| `params`         | No       | `{}`         | Static parameters passed to the action as `__params`. Manifest-fixed — an admin cannot change them. For tenant-configurable values use module settings, resolved from the job's folder (below).       |
 | `enabled`        | No       | `true`       | `false` fully disables — no scheduler, no manual trigger.                                                                            |
 | `paused`         | No       | `false`      | Soft pause. Scheduler skips, but "Run now" still works.                                                                              |
 | `description`    | No       |              | Human-readable description.                                                                                                          |
@@ -58,10 +58,21 @@ minute  hour  day-of-month  month  day-of-week
 Scheduled actions run with **no record bound**. Specifically:
 
 - `user_id = 0` (system user sentinel)
-- No `folder_id` — query / insert against the tenant DB directly
+- A folder, but no record — see **Folder context** below
 - `notify()` writes to inbox only (no live SSE in Phase 1)
 - `sendEmail()` raw mode only in Phase 1
 
+### Folder context
+
+A cron fire has no user, so nothing supplies a folder the way a request does. The scheduler binds one anyway, because `getSetting()` and `nextNumber()` resolve by walking a folder chain:
+
+1. `scheduled_job.folder_id`, if an admin bound one (Admin → Scheduled Jobs → **Change folder**)
+2. Otherwise the owning module's **root folder** — where the module's own settings page writes
+
+So a setting an admin sets on the module's settings page reaches that module's jobs with no configuration. There is **no `folder` key in the manifest**: the binding is operator state, and module upgrades never overwrite it.
+
+Inheritance stops at a folder whose `inherit_security` is false, exactly as it does for a user request.
+
 **Record context is forbidden.** The install pipeline rejects any action whose compiled DSL references `[field]` or `for x in records { … }` — those compile to `__r.` / `__records.` which would `ReferenceError` at fire time. Refactor to operate via `select()` / `insert()` / `update()`:
 
 ```

package/skills/dforge-mcp-author/references/manifest.md

@@ -18,9 +18,7 @@ Every dForge module has a `manifest.json` at its root. This file declares the mo
     "category": "other",
     "tags": ["tag1", "tag2"],
     "icon": "bi-box",
-    "dependencies": {
-        "admin": ">=0.0.1"
-    },
+    "dependencies": {},
     "created": "2026-04-08",
     "updated": "2026-04-08",
     "entities": {
@@ -50,7 +48,7 @@ Every dForge module has a `manifest.json` at its root. This file declares the mo
 | `category` | string | Marketplace category slug (e.g. `"sales"`, `"hr"`, `"other"`) |
 | `tags` | string[] | Search tags |
 | `icon` | string | Bootstrap icon name (e.g. `"bi-briefcase"`) or similar |
-| `dependencies` | object | Map of `module_code → semver range` |
+| `dependencies` | object | Map of `module_code → semver range`. Each entry also requires a `deps/<module_code>.json` contract — see [Dependencies](#dependencies). |
 | `created`, `updated` | ISO date | Timestamps |
 
 ## Content declarations
@@ -107,23 +105,50 @@ Dependencies are a map of module codes to semver ranges. The installer checks th
 
 ```json
 "dependencies": {
-    "admin": ">=0.0.1",
     "fin": ">=0.1.0 <0.2.0"
 }
 ```
 
-**Always depend on `admin`** unless you have a very unusual module — admin provides the user/role system every other module needs.
+**Declare a dependency only on a module you actually consume something from** — an entity you reference with a link column, extend, grant rights on, or read in a view, report, formula or action. Every entry you write here obliges you to write a matching `deps/<module>.json` contract (below), so a speculative dependency is not free.
+
+**Do not depend on `admin`.** It — like `metadata` and `workspace` — is a system module, provisioned into every tenant before any other module installs. Depending on it buys nothing. The one legitimate reason to name a system module is to require a **minimum platform version** for a feature you use, e.g. `"metadata": ">=1.5.0"` for record-report attachments; that still needs a contract naming the entity the feature introduced.
 
 **For bridge modules** (`crm-fin`, `wms-fin`, etc.), depend on both sides:
 
 ```json
 "dependencies": {
-    "admin": ">=0.0.1",
     "crm": ">=0.1.0",
     "fin": ">=0.1.0"
 }
 ```
 
+### Dependency contracts (`deps/<module>.json`)
+
+Every entry in `dependencies` needs a contract file at `deps/<module_code>.json` declaring what this module consumes from that dependency. `dforge_module_validate`, `dforge_module_pack` and the installer all fail without it. `dforge_dependency_add` writes both files for you.
+
+```json
+{
+    "module": "fin",
+    "version": ">=0.1.0 <0.2.0",
+    "entities": {
+        "invoice": {
+            "pk": "invoice_id",
+            "use": ["ref:my_entity.invoice"],
+            "columns": {
+                "invoice_no": { "type": "varchar", "use": ["formula:my_entity.invoice_label"] }
+            }
+        }
+    }
+}
+```
+
+- `version` must be the same range as the manifest's dependency entry.
+- `entities` needs at least one entry; each needs a `pk` and a non-empty `use`.
+- `columns` is optional — omit it when you touch no specific column of that entity. Declare only real storage columns you read, write or join on, at their **storage class** (`int8`, `varchar`, `numeric`, `bool`, `date`, `timestamptz`, …; a `cuid` PK is `int8`). Never declare a virtual column (`R`/`S`/`F`) or a column your own extension adds.
+- `use` tokens are `<kind>:<symbol>` where kind is `ref`, `extends`, `formula`, `action`, `view`, `report`, `print` or `role`. `extends` must be fully qualified: `extends:parties.party`.
+
+Full schema: `dforge://schema/deps`.
+
 ## Extension entities
 
 Modules can extend entities owned by other modules. Declare these in `entities` with dotted keys:
@@ -142,7 +167,7 @@ The extension file has `"extends": "fin.invoice"` inside. See MODULE_CONVENTIONS
 - **Do not** add a `translations` key (e.g. `"translations": { "en-US": "..." }`). There is **no** such manifest field — translation files are auto-discovered at `./translations/{locale}.json`, and non-English locales are declared in `supportedLocales` (English is never listed). The manifest schema is `additionalProperties: false`, so a stray `translations` key fails install.
 - **Do not** put entity definitions inline. Always reference external files.
 - **Do not** list sample or test files — only content that ships with the module.
-- **Do not** include `system: true` unless this is a dForge platform module (`admin`, `metadata`). Regular modules omit it (defaults to `false`).
+- **Do not** include `system: true` unless this is a dForge platform module (`admin`, `metadata`, `workspace`). Regular modules omit it (defaults to `false`).
 - **Do not** hardcode absolute paths. Everything is relative to the manifest.
 
 ## Versioning notes

package/skills/dforge-mcp-author/references/settings.md

@@ -70,13 +70,17 @@ From number sequence patterns:
 
 Settings resolve at runtime through the folder hierarchy:
 
-1. The folder the user is currently in → its override (if any)
+1. The context's folder → its override (if any)
 2. Parent folder → override (if any)
 3. ... up the tree ...
 4. Module default (from `settings.json`)
 
 This means different folders can have different VAT rates, different prefixes, different currencies — without any code changes.
 
+The walk stops at a folder whose `inherit_security` is false; that folder's own override still applies, but it does not inherit from its parent.
+
+**Which folder is "the context's folder"** depends on what is reading. A user request uses the folder the user navigated to; an action uses the folder of the record or the queue entry; a **scheduled job** uses `scheduled_job.folder_id`, defaulting to its module's root folder. A job is the one context with no user, which is why it carries an explicit binding — without one it would see only the module default, and module defaults are not writable through the API (`settings.set` requires a folder).
+
 ## Field types supported in settings
 
 Any field type that makes sense for a single scalar value: