create-erxes 0.1.7 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -9,7 +9,7 @@ import { mkdir, readFile, readdir, symlink, writeFile } from "node:fs/promises";
9
9
  import { homedir } from "node:os";
10
10
  import { fileURLToPath } from "node:url";
11
11
  // package.json
12
- var version = "0.1.7";
12
+ var version = "0.1.8";
13
13
  // src/existing-plugins.ts
14
14
  /** The old erxes plugins a new-core plugin can be migrated from (`backend/plugins/<name>_api`). */
15
15
  const OLD_PLUGINS = [
@@ -10,6 +10,9 @@ reference: `contacts/customers` and `products` for lists and records,
10
10
  built only from what plugins can import. When a page has to differ, say why in
11
11
  a comment.
12
12
 
13
+ Read `ui/node_modules/erxes-ui/CATALOG.md` before writing a component: it lists
14
+ what erxes-ui already has, and the screen each kind of page copies.
15
+
13
16
  ## Page
14
17
 
15
18
  - `PageContainer`, then `PageHeader`. `PageHeader.Start` holds the breadcrumb:
@@ -76,6 +79,15 @@ gives it its fields, and `api/src/modules/items/itemFilter.ts` applies them.
76
79
  (the draft). `contacts`, given an id, gives the record's customers and companies as
77
80
  query options, so other plugins' relation tabs show on it; `activity` names
78
81
  a manifest `timelines` type for core's Activity tab.
82
+ - Every record type has an Activity tab, as customers do: declare the type in
83
+ the manifest's `timelines`, set `activity`, and publish what happens to the
84
+ record (created, changed fields, moved, assigned) as events with
85
+ core's core_publish_event SQL function in the change's transaction: a `summary`, a flat
86
+ payload, `entityType` (that `timelines` type) and `entityId` (the record's
87
+ id). Core puts each on the record's Activity tab, styled by the manifest's
88
+ `activityTypes`; `activities.create` is only for entries that are not
89
+ events. Notes come from core's tab itself. The panel opens on Detail; the record's own page opens on Activity, with
90
+ Detail beside it.
79
91
  - Each slot gets `contentType` and `contentId` and reads the record itself; the
80
92
  slots share one query (`ui/src/modules/items/ItemPanel.tsx`). The Detail
81
93
  tab is `PanelSection`s of `PanelField` rows. Never an erxes-ui `Sheet`, a
@@ -17,6 +17,12 @@ Node 26 runs the TypeScript directly; imports carry `.ts` and `#/` is `src/`.
17
17
  no org filter; only an insert sets `orgId`, from `context.member`.
18
18
  - Call core (`core.forOrg(orgId)...`) outside `context.tx`; a failed core call
19
19
  must not roll back the plugin's own change.
20
+ - What happens to a record is an event: publish it with core's core_publish_event SQL function
21
+ in `context.tx`, so it commits with the change, with a `summary`,
22
+ a flat payload, `entityType` (a type in the manifest's `timelines`) and
23
+ `entityId`. It appears on the record's Activity tab, and on the customer's or
24
+ company's too when it names `subjectType` and `subjectId`. A retried event
25
+ adds nothing. `activities.create` is for entries that are not events.
20
26
  - Tests: `vite-plus/test`, run with `call(procedure, input, { context: { member } })`.
21
27
  `src/test/setup.ts` gives each file its own database, owned by a role without
22
28
  BYPASSRLS, so row-level security is real in tests.
@@ -16,7 +16,7 @@
16
16
  "image:context": "pnpm build && rm -rf .runtime && pnpm --filter @__id__/api deploy --prod .runtime"
17
17
  },
18
18
  "devDependencies": {
19
- "@erxes/lint": "0.1.2",
19
+ "@erxes/lint": "0.1.3",
20
20
  "@types/node": "^26.6.6",
21
21
  "knip": "^6.45.1",
22
22
  "react-doctor": "0.9.23",
@@ -13,6 +13,9 @@ and renders `./__id__` (the `__Pascal__` export) under `/__id__/*`.
13
13
  - Build pages from `erxes-ui` components and its root export. The host provides
14
14
  React, the router, the query client and erxes-ui, and web's stylesheet styles
15
15
  erxes-ui's components.
16
+ - Read `node_modules/erxes-ui/CATALOG.md` before writing a component, hook or
17
+ helper. It lists every erxes-ui export with what it is for, and the core screen
18
+ each kind of page copies.
16
19
  - Any Tailwind class works, on erxes-ui's tokens (`bg-muted`, `text-sm`,
17
20
  `md:grid-cols-2`). `src/styles.css` builds the plugin's own utilities, and
18
21
  `src/__Pascal__.tsx` passes them to `addPluginStyles`, which adds only the
@@ -13,7 +13,7 @@
13
13
  "@orpc/tanstack-query": "1.16.2",
14
14
  "@tabler/icons-react": "3.34.0",
15
15
  "@tanstack/react-query": "^5.107.1",
16
- "erxes-ui": "npm:@erxes/ui@4.0.0-v2.9",
16
+ "erxes-ui": "npm:@erxes/ui@4.0.0-v2.10",
17
17
  "jotai": "^3.0.2",
18
18
  "nuqs": "^2.10.3",
19
19
  "react": "19.3.1",
@@ -3,10 +3,14 @@ name: plugin-migrate
3
3
  description: Port the old erxes plugin this repo was made from onto the new core. Use when working through MIGRATION.md, porting a module, or when someone asks how far the migration is.
4
4
  ---
5
5
 
6
- The port keeps every feature the old plugin had and fixes its architecture.
7
- Port what each feature does, never its code: where the old plugin got
8
- something wrong (a missing check, a race, a workaround for the old core), the
9
- new one does it right.
6
+ We're rewriting to fix the architecture. A port that carries over the old
7
+ bugs, tech debt and workarounds wasted the rewrite. Once customer data is in,
8
+ big changes get hard, so give each table and screen its long-term shape the
9
+ first time.
10
+
11
+ Every old feature stays. Port what it does, never its code. Where the old
12
+ plugin got something wrong, such as a missing check, a race or a workaround
13
+ for the old core, the new one does it right.
10
14
 
11
15
  If scaffolding skipped installation, first run `pnpm migrate:inventory -- --from <old-checkout> --plugin <old-plugin> --ref <ref>`
12
16
  and `pnpm migrate:checklist`. These commands generate the port's working files:
@@ -20,6 +24,37 @@ migration/schema-draft.ts Draft tables to port
20
24
  `migration/core-map.ts` says what each old core call becomes. Use synthetic
21
25
  data only. The inventory reads code, never a database.
22
26
 
27
+ ## Never carry these over
28
+
29
+ | Old | New |
30
+ | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
31
+ | `subdomain` passed around, org filters written by hand | The org comes from the token, and row level security scopes every query. |
32
+ | Row mappers that reshape query results | The procedure's `.output()` picks the row's fields. A value the row lacks comes from the query. |
33
+ | String errors the UI matches on | A typed oRPC error for each failure the UI acts on. |
34
+ | `console` calls | `api/src/logger.ts`, with the facts as fields. |
35
+ | Several writes per action outside one transaction | One transaction per action. |
36
+ | Uniqueness checked in code | A unique index that includes `org_id`. |
37
+ | Status strings compared across the code | A `text({ enum })` column and one function that owns the allowed moves. |
38
+ | Branches on provider kind | One adapter interface. Shared code never names a provider. |
39
+ | Per-provider copies of core data, such as customers | Core owns customers and companies. The plugin stores their ids. |
40
+ | Secrets in plain text, such as tokens and passwords | Encrypted at rest, with the key read in `api/src/config.ts`. |
41
+
42
+ ## When core lacks something
43
+
44
+ Don't build around it. Check `migration/core-map.ts` and `@erxes/core-contract`
45
+ first. If core doesn't have it, file an issue in the plugin's repo that says
46
+ what the old plugin did and what core would need, and add a `DECISIONS.md`
47
+ row. Port the rest of the module. A workaround is never the answer, because
48
+ it needs a data migration once core ships the feature.
49
+
50
+ ## Decisions
51
+
52
+ `DECISIONS.md` gets one row per difference from the old plugin, with Old, New
53
+ and Why: a fixed bug, a changed shape, a feature left out or waiting for core.
54
+ The row goes in the module's commit.
55
+
56
+ ## Steps
57
+
23
58
  1. Read the checklist. Port the module with the fewest unticked items first;
24
59
  `Plugin-wide` goes last.
25
60
  2. Tables. Move the module's draft tables into
@@ -52,27 +87,37 @@ data only. The inventory reads code, never a database.
52
87
  drafted with their import from old core's `departments`, `branches` and the
53
88
  members' `departmentIds` and `branchIds`. The ids stay the same, so the old
54
89
  records' `departmentIds` still match.
55
- 5. Pages. One per UI route, under `ui/src/modules/<module>/`, built from
56
- `erxes-ui` the way `ui/src/modules/items/` is, laid out by the `ui-patterns` skill. The old `ui-modules` components don't exist
57
- here. Member pickers and names become erxes-ui's `SelectMember` and
58
- `MemberInline`; a picker of other records is erxes-ui's `EntityPicker` over
59
- the plugin's own query. For erxes-ui components whose props changed, see
60
- its old-to-new table, `packages/ui/MIGRATION.md` in the erxes repo (branch
61
- `postgre`).
62
- 6. Check parity in the browser, following the `verify` skill: open the old
63
- page and the new one side by side, and walk the same actions on both.
90
+ 5. Pages. One per UI route, under `ui/src/modules/<module>/`. No old screen
91
+ is copied. The old screen shows what the feature does, and the new one
92
+ follows core's screens through the `ui-patterns` skill and
93
+ `ui/node_modules/erxes-ui/CATALOG.md`. The catalog's Pages table names the
94
+ components and the screen to copy for each kind of page, and its other
95
+ sections list what erxes-ui already has. Import those, never a copy of
96
+ your own. A record with a status gets a list grouped by status,
97
+ erxes-ui's `RecordList`. Member pickers and names become erxes-ui's
98
+ `SelectMember` and `MemberInline`; a picker of other records is
99
+ erxes-ui's `EntityPicker` over the plugin's own query. For erxes-ui
100
+ components whose props changed, see its old-to-new table,
101
+ `packages/ui/MIGRATION.md` in the erxes repo (branch `postgre`). A feature
102
+ that's left out gets a `DECISIONS.md` row.
103
+ 6. Check feature parity, not layout parity, in the browser with the `verify`
104
+ skill. Every old action, field and filter must be reachable on the
105
+ new page. Run at most 2 parity runs per module. Wording, spacing, order and
106
+ colour go in the PR body as a list, never into another fix round. When the
107
+ same failure happens twice, stop and report it with the output.
64
108
  7. Tick an item once it works on the new core and its old bugs and
65
109
  workarounds are gone. When an item needs something core doesn't offer
66
- (marked **gap**, or one you find), file an issue in the plugin's repo that
67
- says what the old plugin did and what core would need, tick the item and
68
- end its line with `(filed <issue url>)`. The feature waits for core.
69
- 8. Commit the module: schema, migration, procedures, page and the ticks
70
- together.
110
+ (marked **gap**, or one you find), follow "When core lacks something",
111
+ tick the item and end its line with `(filed <issue url>)`. The feature
112
+ waits for core.
113
+ 8. Commit the module: schema, migration, procedures, pages, ticks and its
114
+ `DECISIONS.md` rows together.
71
115
  9. Copy data once all modules are in: `pnpm migrate:import` with `MONGO_URL`,
72
116
  `DATA_URL` and `ORG_ID` set. Its `Skipped` list must be empty or explained.
73
117
 
74
118
  Rerun `pnpm migrate:inventory` and `pnpm migrate:checklist` only to pick up
75
119
  new old-side code; ticks survive the rerun.
76
120
 
77
- Done when every checklist item is ticked, each gap with its issue
78
- link, and `vp run check`, `vp run test`, `pnpm check:rls` and `pnpm build` pass.
121
+ Done when every checklist item is ticked, each gap with its issue link and
122
+ decision row, and `vp run check`, `vp run test`, `pnpm check:rls` and
123
+ `pnpm build` pass.
@@ -0,0 +1,8 @@
1
+ # Decisions
2
+
3
+ Where the port differs from the old plugin: a fixed bug, a changed shape, a
4
+ feature left out or waiting for core. One row each, added in the module's
5
+ commit. The `plugin-migrate` skill says when.
6
+
7
+ | Old | New | Why |
8
+ | --- | --- | --- |
@@ -156,8 +156,8 @@ export const CORE_CALLS: Record<string, Equivalent> = {
156
156
  'country and currency: organizations.current (sdk)',
157
157
  ),
158
158
  'activityLog.createActivityLog': sdk(
159
- 'activities.create',
160
- 'scope activities:write; customer or company targets, else manifest timelines',
159
+ 'core_publish_event() in the same transaction',
160
+ 'summary, entityType (a manifest timelines type) and entityId put it on the record; subjectType and subjectId on a customer or company; activities.create only for entries that are not events',
161
161
  ),
162
162
  'notifications.send': sdk('notifications.create', 'scope notifications:write; team members only'),
163
163
  'core.sendEmail': sdk(
@@ -197,7 +197,7 @@ export const HELPERS: Record<string, Equivalent> = {
197
197
  sendAutomationTrigger: START_AUTOMATIONS,
198
198
  sendAutomationDeferredCompletion: owned(
199
199
  'the action answers at once ({ queued: true, jobId })',
200
- 'the plugin keeps the final result on its own job row, and on the timeline with activities.create',
200
+ 'the plugin keeps the final result on its own job row, and on the timeline as an event naming the record',
201
201
  ),
202
202
  };
203
203
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-erxes",
3
- "version": "0.1.7",
3
+ "version": "0.1.8",
4
4
  "private": false,
5
5
  "description": "Create an erxes plugin for the new core, or migrate an old erxes plugin onto it: pnpm create erxes",
6
6
  "license": "MIT",