@antelopejs/dms 0.12.1 → 0.13.1

package/frontend-vue/scripts/codemods/api-error-presenter.mjs

@@ -0,0 +1,196 @@
+import { readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  apiErrorSources,
+  apiErrorScripts,
+  analyzeApiErrorScript,
+} from "../check-api-error-presentation.mjs";
+
+const require = createRequire(resolve(process.cwd(), "package.json"));
+const tools = {
+  ts: require("typescript"),
+  parse: require("vue/compiler-sfc").parse,
+};
+const { ts } = tools;
+
+function translatedKey(expression) {
+  if (
+    !expression ||
+    !ts.isCallExpression(expression) ||
+    !["t", "processI18n"].includes(expression.expression.getText())
+  )
+    return null;
+  const key = expression.arguments[0];
+  return expression.arguments.length === 1 && key && ts.isStringLiteral(key)
+    ? key.text
+    : null;
+}
+
+function literalKey(payload) {
+  if (!payload || !ts.isObjectLiteralExpression(payload)) return null;
+  const allowed = new Set(["title", "description", "color", "icon"]);
+  if (
+    payload.properties.some(
+      (property) =>
+        !ts.isPropertyAssignment(property) ||
+        !allowed.has(property.name.getText()) ||
+        (["title", "description"].includes(property.name.getText())
+          ? translatedKey(property.initializer) === null
+          : !(
+              ts.isStringLiteral(property.initializer) ||
+              (property.name.getText() === "color" &&
+                /^Color\.(error|warning|info)$/.test(
+                  property.initializer.getText(),
+                ))
+            )),
+    )
+  )
+    return null;
+  const title =
+    payload.properties.find(
+      (property) => property.name.getText() === "description",
+    )?.initializer ??
+    payload.properties.find((property) => property.name.getText() === "title")
+      ?.initializer;
+  return translatedKey(title);
+}
+
+function composableScope(node) {
+  let outer = null;
+  for (let parent = node.parent; parent; parent = parent.parent) {
+    if (
+      (ts.isFunctionDeclaration(parent) ||
+        ts.isFunctionExpression(parent) ||
+        ts.isArrowFunction(parent)) &&
+      ts.isBlock(parent.body)
+    )
+      outer = parent;
+  }
+  const name = outer?.name ?? outer?.parent?.name;
+  return name && ts.isIdentifier(name) && /^use[A-Z]/.test(name.text)
+    ? outer.body
+    : null;
+}
+
+/** Rewrites supported setup/composable catches and returns unsupported cases. */
+export function migrateApiErrorSource(file, source) {
+  const edits = [];
+  const manual = [];
+  for (const script of apiErrorScripts(file, source, tools)) {
+    const calls = analyzeApiErrorScript(script.source, file, ts);
+    let capture = false;
+    for (const call of calls) {
+      const fallbackKey = literalKey(call.payload);
+      const standalone = ts.isExpressionStatement(call.node.parent);
+      const safeCatch = call.failure && /^[A-Za-z_$][\w$]*$/.test(call.failure);
+      const collision = /\b(?:presentError|useApiErrorPresenter)\b/.test(
+        script.source,
+      );
+      const hasSetup = file.endsWith(".vue")
+        ? script.isSetup
+        : composableScope(call.node);
+      if (
+        fallbackKey &&
+        standalone &&
+        safeCatch &&
+        hasSetup &&
+        call.method === "add" &&
+        !collision
+      ) {
+        edits.push({
+          start: script.offset + call.node.getStart(),
+          end: script.offset + call.node.end,
+          text: `presentError(${call.failure}, { fallbackKey: ${JSON.stringify(fallbackKey)} })`,
+        });
+        capture = true;
+      } else {
+        manual.push({
+          file,
+          line: source
+            .slice(0, script.offset + call.node.getStart())
+            .split("\n").length,
+          reason: "manual-error-presentation",
+          expression: call.node.getText(call.tree),
+        });
+      }
+    }
+    if (capture) {
+      const tree = ts.createSourceFile(
+        file,
+        script.source,
+        ts.ScriptTarget.Latest,
+        true,
+      );
+      const imports = tree.statements.filter(ts.isImportDeclaration);
+      const offset = imports.at(-1)?.end ?? 0;
+      const declaration = file.endsWith(".vue")
+        ? "\nconst { presentError } = useApiErrorPresenter();\n"
+        : `\nimport { useApiErrorPresenter } from "#dms-core/app/composables/useApiErrorPresenter";\n`;
+      if (file.endsWith(".vue"))
+        edits.push({
+          start: script.offset + offset,
+          end: script.offset + offset,
+          text: declaration,
+        });
+      else {
+        const scopes = new Set();
+        for (const call of calls) {
+          if (
+            !edits.some(
+              (edit) => edit.start === script.offset + call.node.getStart(),
+            )
+          )
+            continue;
+          const outer = composableScope(call.node);
+          if (outer) scopes.add(outer.getStart() + 1);
+        }
+        for (const start of scopes)
+          edits.push({
+            start: script.offset + start,
+            end: script.offset + start,
+            text: "\nconst { presentError } = useApiErrorPresenter();\n",
+          });
+        edits.push({
+          start: script.offset + offset,
+          end: script.offset + offset,
+          text: declaration,
+        });
+      }
+    }
+  }
+  let output = source;
+  for (const edit of edits.sort((a, b) => b.start - a.start))
+    output = output.slice(0, edit.start) + edit.text + output.slice(edit.end);
+  return { output, rewritten: output !== source, manual };
+}
+
+/** Dry-run by default; writes only source cases accepted by the bounded migration. */
+export function migrateApiErrorFile(file, write = false) {
+  const result = migrateApiErrorSource(file, readFileSync(file, "utf8"));
+  if (write && result.rewritten) writeFileSync(file, result.output);
+  return result;
+}
+
+if (
+  process.argv[1] &&
+  realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+) {
+  const roots = process.argv
+    .slice(2)
+    .filter((argument) => argument !== "--write");
+  if (!roots.length)
+    throw new Error(
+      "Pass app directories. Add --write to apply safe rewrites. Manual cases are JSONL on stdout.",
+    );
+  for (const file of roots.flatMap(apiErrorSources)) {
+    const result = migrateApiErrorFile(file, process.argv.includes("--write"));
+    for (const entry of result.manual)
+      process.stdout.write(`${JSON.stringify(entry)}\n`);
+    if (result.rewritten)
+      process.stderr.write(
+        `${process.argv.includes("--write") ? "rewrote" : "would rewrite"} ${file}\n`,
+      );
+  }
+}

package/frontend-vue/scripts/test-api-error-presentation.mjs

@@ -0,0 +1,134 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import {
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import {
+  analyzeApiErrorScript,
+  apiErrorScripts,
+} from "./check-api-error-presentation.mjs";
+import { migrateApiErrorSource } from "./codemods/api-error-presenter.mjs";
+import { parse } from "vue/compiler-sfc";
+
+const rejected = [
+  `try { await save() } catch (error) { toast.add({ title: t('save.failed'), color: 'error' }) }`,
+  `save().catch(error => { toast.update(id, { color: 'error' }) })`,
+  `save().then(done, error => { toast.add({ color: Color.error }) })`,
+  `const notices = useToast(); try {} catch (error) { notices.add({ color: 'warning' }) }`,
+  `const { add: notify } = useToast(); try {} catch (error) { notify({ color: FAILURE_COLOR }) }`,
+  `const notices = useToast(); const alias = notices; try {} catch (error) { alias.update(id, payload) }`,
+  `import { ERROR_COLOR } from './colors'; try {} catch (error) { toast.add({ color: ERROR_COLOR }) }`,
+  `const payload = { color: 'error' }; try {} catch (error) { toast.add(payload) }`,
+  `save().catch(error => { toast.add({ title: t('save.failed') }) })`,
+];
+for (const source of rejected)
+  assert.equal(
+    analyzeApiErrorScript(source, "fixture.ts", ts).length,
+    1,
+    source,
+  );
+
+const allowed = [
+  `try { await save(); toast.add({ color: 'success' }) } catch (error) { presentError(error, { fallbackKey: 'save.failed' }) }`,
+  `try { await track() } catch {} finally { loading.value = false }`,
+  `toast.add({ color: 'info', title: t('product.notice') })`,
+  `save().catch(() => { toast.add({ color: 'success' }) })`,
+];
+for (const source of allowed)
+  assert.equal(
+    analyzeApiErrorScript(source, "fixture.ts", ts).length,
+    0,
+    source,
+  );
+
+const vue = `<script setup lang="ts">
+const toast = useToast();
+async function save() {
+  try { await write() } catch (failure) { toast.add({ title: t("save.failed"), color: "error" }); }
+}
+</script><template><button @click="save">Save</button></template>`;
+const migrated = migrateApiErrorSource("fixture.vue", vue);
+assert.ok(migrated.rewritten);
+assert.deepEqual(migrated.manual, []);
+assert.ok(
+  migrated.output.includes(
+    'presentError(failure, { fallbackKey: "save.failed" })',
+  ),
+);
+assert.equal(
+  migrateApiErrorSource("fixture.vue", migrated.output).rewritten,
+  false,
+);
+for (const script of apiErrorScripts("fixture.vue", migrated.output, { parse }))
+  assert.equal(
+    analyzeApiErrorScript(script.source, "fixture.vue", ts).length,
+    0,
+  );
+
+const composable = `export function useSave() { return async () => { try { await save() } catch (error) { toast.add({ title: t('save.failed'), color: 'error' }); } } }`;
+const converted = migrateApiErrorSource("fixture.ts", composable);
+assert.ok(
+  converted.output.indexOf("const { presentError }") <
+    converted.output.indexOf("return async"),
+);
+assert.ok(converted.output.includes("import { useApiErrorPresenter }"));
+
+for (const source of [
+  `async function save() { try {} catch (error) { toast.add({ title: t('save.failed'), color: 'error' }); } }`,
+  `export function useSave() { try {} catch { toast.add({ title: t('save.failed'), color: 'error' }); } }`,
+  `export function useSave() { try {} catch (error) { toast.update(id, { title: t('save.failed'), color: 'error' }); } }`,
+  `export function useSave() { try {} catch (error) { toast.add({ title: t(dynamic), color: 'error' }); } }`,
+  `export function useSave() { try {} catch (error) { toast.add({ title: t('save.failed'), color: color() }); } }`,
+  `export function useSave() { try {} catch (error) { toast.add({ title: t('save.failed'), icon: icon(), color: 'error' }); } }`,
+  `<script>try {} catch (error) { toast.add({ title: t('save.failed'), color: 'error' }); }</script>`,
+]) {
+  const file = source.startsWith("<script") ? "manual.vue" : "manual.ts";
+  const result = migrateApiErrorSource(file, source);
+  assert.equal(result.output, source);
+  assert.deepEqual(Object.keys(result.manual[0]), [
+    "file",
+    "line",
+    "reason",
+    "expression",
+  ]);
+  assert.equal(result.manual[0].reason, "manual-error-presentation");
+}
+const linkRoot = mkdtempSync(join(tmpdir(), "dms-api-error-cli-"));
+const appRoot = mkdtempSync(
+  fileURLToPath(new URL("../.api-error-cli-", import.meta.url)),
+);
+try {
+  const scripts = join(linkRoot, "scripts");
+  symlinkSync(fileURLToPath(new URL(".", import.meta.url)), scripts, "dir");
+  writeFileSync(join(appRoot, "package.json"), "{}");
+  mkdirSync(join(appRoot, "app"));
+  writeFileSync(
+    join(appRoot, "app", "manual.ts"),
+    `export function useSave() { try {} catch (error) { toast.add({ title: t(dynamic), color: 'error' }); } }`,
+  );
+  const checker = spawnSync(
+    process.execPath,
+    [join(scripts, "check-api-error-presentation.mjs"), join(appRoot, "app")],
+    { encoding: "utf8" },
+  );
+  assert.notEqual(checker.status, 0, "checker fails through a symlinked path");
+  const codemod = spawnSync(
+    process.execPath,
+    [join(scripts, "codemods", "api-error-presenter.mjs"), join(appRoot, "app")],
+    { encoding: "utf8", cwd: appRoot },
+  );
+  assert.equal(codemod.status, 0, codemod.stderr);
+  assert.match(codemod.stdout, /"reason":"manual-error-presentation"/);
+} finally {
+  rmSync(linkRoot, { recursive: true, force: true });
+  rmSync(appRoot, { recursive: true, force: true });
+}
+console.log("PASS API error invariant and codemod fixtures");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "description": "AntelopeJS DMS. Plug in your PostgreSQL, MongoDB or RethinkDB database and your coding agent builds a back office and analytics dashboard as typed TypeScript. Real-time updates on the data the DMS manages.",
   "keywords": [
     "antelopejs",
@@ -71,11 +71,11 @@
     "2fa": "^0.1.2",
     "@antelopejs/interface-api": ">=0.0.15 <1.0.0",
     "@antelopejs/interface-api-util": ">=0.1.3 <1.0.0",
-    "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
+    "@antelopejs/interface-core": ">=0.2.6 <1.0.0",
     "@antelopejs/interface-data-api": ">=0.5.0 <1.0.0",
     "@antelopejs/interface-database": ">=0.1.11 <1.0.0",
     "@antelopejs/interface-database-decorators": ">=0.1.10 <1.0.0",
-    "@antelopejs/interface-dms": ">=0.10.1 <0.11.0",
+    "@antelopejs/interface-dms": ">=0.10.2 <0.11.0",
     "@antelopejs/interface-email": ">=0.0.6 <1.0.0",
     "@antelopejs/interface-file-storage": ">=0.1.4 <1.0.0",
     "archiver": "^7.0.1",
@@ -114,7 +114,8 @@
     "release-it-changelogen": "^0.1.0",
     "rimraf": "^6.1.3",
     "tsc-alias": "^1.9.1",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vue": "^3.5.18"
   },
   "exports": {
     ".": {
@@ -122,6 +123,8 @@
       "default": "./dist/index.js"
     },
     "./package.json": "./package.json",
+    "./checks/api-error-presentation": "./frontend-vue/scripts/check-api-error-presentation.mjs",
+    "./codemods/api-error-presenter": "./frontend-vue/scripts/codemods/api-error-presenter.mjs",
     "./interfaces/*": null
   },
   "publishConfig": {
@@ -145,6 +148,8 @@
     "build": "pnpm --filter @antelopejs/interface-dms build && rimraf dist && tsc && tsc-alias",
     "dev": "ajs project run --inspect -w -p playground",
     "frontend:dev": "pnpm --dir playground frontend:dev",
+    "frontend:build": "pnpm --dir playground frontend:build",
+    "frontend:start": "pnpm --dir playground frontend:start",
     "typecheck": "node scripts/unless-prebuilt.mjs pnpm --filter @antelopejs/interface-dms build && tsc --noEmit",
     "test": "node scripts/unless-prebuilt.mjs pnpm run build && NODE_OPTIONS=\"${NODE_OPTIONS:+$NODE_OPTIONS }--require=\\\"$PWD/scripts/backend-runtime-boundaries.cjs\\\"\" ajs module test .",
     "test:unit": "node scripts/unless-prebuilt.mjs pnpm run build && node scripts/backend-checks.cjs && DMS_TEST_DIR=dist/test/unit NODE_OPTIONS=\"${NODE_OPTIONS:+$NODE_OPTIONS }--require=\\\"$PWD/scripts/backend-runtime-boundaries.cjs\\\"\" ajs module test .",
@@ -156,6 +161,7 @@
     "knip:all": "knip",
     "docs:catalog": "node scripts/docs-catalog.mjs",
     "docs:catalog:check": "node scripts/docs-catalog.mjs --check",
+    "check:frontend-declarations": "node scripts/check-frontend-declarations.mjs",
     "docs:screenshots": "node scripts/docs-screenshots.mjs",
     "realtime:tabs-check": "node scripts/realtime-tabs-check.mjs"
   }

package/skills/dms-module/REFERENCE.md

@@ -33,6 +33,7 @@ first-party modules follow `dms-<name>` purely for discoverability.
 ```jsonc
 {
   "main": "dist/index.js", "types": "dist/index.d.ts",
+  "dmsFrontend": "dist/frontend-module.js",          // exports frontendModule(config, { dev }) (omit if no frontend)
   "antelopeJs": {
     "baseUrl": "dist",
     "implements": ["<your-interface-package>"],  // the interface THIS module provides (omit/[] if none)
@@ -80,7 +81,8 @@ AntelopeJS — see the **ajs-author-interface** and **ajs-consume-interface** sk
    `frontend-vue/` (components registered from the root `dms.frontend.ts`), `skills/<name>/SKILL.md`,
    and the manifest (`antelopeJs` block with `skills`, plus the interface package's `exports`).
 4. **Wire the basics**: `RegisterModule({ id, title, icon, … })`, one `@RegisterPage()` page,
-   the `AddFrontendModule` call. Add the `$dms_<name>.*` keys to **every** locale file under
+   `src/frontend-module.ts` (`frontendModule`, declared as `dmsFrontend`) passed to
+   `AddFrontendModule`. Add the `$dms_<name>.*` keys to **every** locale file under
    `frontend-vue/i18n/locales/`.
 5. **Load and verify**: add the module to a consumer project's `antelope.config.ts` (the
    backend's `playground` is the reference consumer) as a `package`/`git`/local-path module,

package/skills/dms-module/SKILL.md

@@ -31,7 +31,9 @@ manifest, including the `exports` entries for an interface subpath).
 when they provide none (`dms-lang`, `dms-saas`); consumed interfaces are plain `dependencies`
 (no manifest field). Typical dependencies: `@antelopejs/dms` plus
 `@antelopejs/interface-{core,api,api-util,auth,database,database-decorators}`. The frontend is
-attached at runtime by the `AddFrontendModule` call in `construct`; there is no manifest field for it.
+attached by the `AddFrontendModule` call in `construct` and declared as `"dmsFrontend": "dist/frontend-module.js"`
+in `package.json`: `ajs dms dev`, `build` and `start` read that declaration, not the backend, and leave
+out a module without it.
 
 **Ship a skill.** Add `skills/<module-name>/SKILL.md` (frontmatter `name`, a trigger-rich
 `description`, `icon`, `category`, `tags`) saying when and how to use the module, list `"skills"` in
@@ -81,7 +83,10 @@ export function destroy(): void { /* deactivate subscriptions */ }
 
 `RegisterModule` runs at import time (top level), so the module exists before its pages
 register — it returns the module's root `CategoryInfo`. `AddFrontendModule` is what surfaces the
-module's frontend; without it the module is backend-only.
+module's frontend; without it the module is backend-only. Keep its argument in a pure
+`export function frontendModule(config, { dev })` in `src/frontend-module.ts` (no runtime imports:
+`ajs dms build` loads that file on its own) and call `AddFrontendModule(frontendModule(config, …))`,
+as the official modules do; `dmsFrontend` names its compiled file.
 
 `renderer` names the framework (Vue 3), not a loader release. The `@antelopejs/dms-frontend`
 releases the frontend module runs on go in the frontend module's own `package.json`, as

package/skills/dms-project/SKILL.md

@@ -37,7 +37,8 @@ infrastructure it needs) and whose own `src/` is the `local` module. It provides
 its `package.json` has **no `antelopeJs.implements`** (that field marks a distributable module);
 deps are `@antelopejs/dms` + the interface libs, plus `@antelopejs/dms-frontend` (the
 `ajs dms` CLI) as a dependency — the template keeps it in `dependencies`; a devDependency also works
-since it is only a CLI. The frontend attaches at runtime with `AddFrontendModule`, and the DMS
+since it is only a CLI. The frontend attaches with `AddFrontendModule` and a `dmsFrontend`
+declaration in `package.json` (below), and the DMS
 **auto-registers its base dashboard layer** (shell, login, component vocabulary) — a pages-only
 project needs no `frontend-vue/` of its own.
 
@@ -133,8 +134,13 @@ export function stop(): void {}
 export function getConfig(): Config { return globalConfig; }
 ```
 
-Frontend wiring is the `AddFrontendModule` call alone — no DMS config entry. A **project** attaches the
-layer from `start()`; a **distributable module** attaches it in `construct` (see **dms-module**).
+Frontend wiring is the `AddFrontendModule` call plus `"dmsFrontend": "dist/frontend-module.js"` in
+the project's `package.json` — no DMS config entry. `ajs dms dev`, `build` and `start` read the project,
+not the backend's registrations, and leave out a frontend that is not declared:
+move the registration into a pure `export function frontendModule()` in `src/frontend-module.ts`
+(no runtime imports), call `AddFrontendModule(frontendModule())` from `start()`, and declare it. A
+**project** attaches the layer from `start()`; a **distributable module** attaches it in `construct`
+(see **dms-module**).
 Full layer authoring: `docs/02.building/08.frontend-layer.md`.
 
 ## What you register (delegates to the other skills)

package/frontend-vue/layers/dms-core/app/composables/useReadOnlyRefusal.ts

@@ -1,49 +0,0 @@
-import { isFunction, isObject } from "../utils/type-check";
-
-const READ_ONLY_STATUS = 403;
-const READ_ONLY_HEADER = "x-dms-readonly";
-const READ_ONLY_MARK = "1";
-const READ_ONLY_TOAST_ID = "dms-read-only";
-const READ_ONLY_STATE_KEY = "dms.readOnly.presentedResponses";
-
-function refusedResponse(
-  failure: Parameters<typeof isObject>[0],
-): object | undefined {
-  if (!failure || !isObject(failure)) return;
-  const response = failure.response;
-  if (!response || !isObject(response) || response.status !== READ_ONLY_STATUS)
-    return;
-  const headers = response.headers;
-  if (!headers || !isObject(headers) || !isFunction(headers.get)) return;
-  return headers.get(READ_ONLY_HEADER) === READ_ONLY_MARK
-    ? response
-    : undefined;
-}
-
-/**
- * Captures app-local refusal presentation. The returned consumer shows one
- * generic toast per marked response and returns whether it owns presentation.
- * A consumed refusal remains a failed operation; callers skip only local notices.
- */
-export function useReadOnlyRefusal() {
-  const toast = useToast();
-  const { processApiMessage } = getAppTranslation();
-  const presented = useDmsState(
-    READ_ONLY_STATE_KEY,
-    () => new WeakSet<object>(),
-  );
-
-  return (failure: Parameters<typeof refusedResponse>[0]): boolean => {
-    const response = refusedResponse(failure);
-    if (!response) return false;
-    if (presented.value.has(response)) return true;
-    presented.value.add(response);
-    toast.add({
-      id: READ_ONLY_TOAST_ID,
-      color: "warning",
-      icon: "i-ph-lock-simple",
-      title: processApiMessage("error.read_only_demo"),
-    });
-    return true;
-  };
-}