@lowdefy/codemods 5.6.0 → 6.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lowdefy/codemods",
-  "version": "5.6.0",
+  "version": "6.1.0",
   "description": "Codemod scripts and migration prompts for Lowdefy version upgrades",
   "license": "Apache-2.0",
   "repository": {

package/registry.json

@@ -1,5 +1,22 @@
 {
   "versions": [
+    {
+      "version": "6.0.0",
+      "from": ">=5.0.0 <6.0.0",
+      "description": "Vite + Hono server migration (plugin ESM exports, Auth.js imports, provider-neutral file blocks)",
+      "codemods": [
+        {
+          "id": "migrate-plugin-packages",
+          "description": "Convert custom plugin packages for the unbundled Node ESM server: exports subpaths must resolve to files (fixes ERR_UNSUPPORTED_DIR_IMPORT), next-auth imports move to @auth/core, next/* imports and NEXT_PUBLIC_* reads are removed.",
+          "path": "v6-0-0/01-migrate-plugin-packages.md"
+        },
+        {
+          "id": "s3-blocks-to-file-blocks",
+          "description": "Optional: rename the deprecated S3UploadButton/S3UploadPhoto/S3UploadDragger/S3Download blocks to the provider-neutral Upload/UploadPhoto/UploadDragger/Download blocks, and s3PostPolicyRequestId/s3GetPolicyRequestId to uploadPolicyRequestId/downloadPolicyRequestId (also on TiptapInput, TiptapMentionInput, and AgentChat attachments). The aliases keep working; this silences deprecation warnings.",
+          "path": "v6-0-0/02-s3-blocks-to-file-blocks.md"
+        }
+      ]
+    },
     {
       "version": "5.5.0",
       "from": ">=5.1.0 <5.5.0",

package/v6-0-0/01-migrate-plugin-packages.md

@@ -0,0 +1,173 @@
+# Migration: Plugin Packages for the Hono + Vite Server (ESM Exports, Auth.js Imports)
+
+## Context
+
+In Lowdefy v6 the server no longer runs on Next.js. The production server is a Hono app running as **plain, unbundled Node.js ESM**, and the client is bundled by Vite. This changes how plugin packages are loaded:
+
+- **Server-side plugin files** (`connections`, `agents`, `operators/server`, `auth/*`) are imported by Node.js directly from the generated `build/plugins/*.js` files. Node's ESM resolver is **stricter than a bundler**: it does not try `.js` completion and does not resolve `index.js` inside directories.
+- **Client-side plugin files** (`blocks`, `actions`, `operators/client`, `metas`, `icons`, plus any CSS the blocks import) are bundled by Vite, which resolves package `exports` the standard way.
+
+A plugin that worked in v5 can crash the v6 server at startup with:
+
+```
+Error [ERR_UNSUPPORTED_DIR_IMPORT]: Directory import '.../node_modules/<plugin>/dist/connections'
+is not supported resolving ES modules imported from .../build/plugins/connections.js
+```
+
+This happens when the plugin's `exports` map resolves a subpath to a **directory** instead of a file. A wildcard like `"./*": "./dist/*"` substitutes literally — the specifier `<plugin>/connections` maps to `dist/connections`, and if that is a directory (with the real barrel at `dist/connections.js` or `dist/connections/index.js`), Node refuses it. Bundlers silently completed this to a file, which is why v5 never surfaced the problem.
+
+Additionally, **auth plugins can no longer import from `next-auth`**. The v6 auth engine is Auth.js (`@auth/core`). The `next-auth` package is gone from the server, and although a plugin that ships its own `next-auth` dependency may still load, it should migrate to `@auth/core` imports, which are clean ESM (no `.default` CJS workaround).
+
+This migration targets **plugin package source and `package.json`** (local plugins and published plugin packages), not YAML configs.
+
+## Scope
+
+`plugins` — scan `package.json` and source files of custom plugin packages (workspace plugins, `git:`/`link:` plugins, and your published plugin packages).
+
+## What to Do
+
+### 1. Make every Lowdefy entry-point subpath in `exports` resolve to a file
+
+List the subpaths Lowdefy generates imports for, based on what the plugin provides:
+
+| Plugin provides | Imported subpath |
+| --- | --- |
+| Connections/requests | `<plugin>/connections` |
+| Blocks | `<plugin>/blocks`, `<plugin>/metas` |
+| Actions | `<plugin>/actions` |
+| Operators | `<plugin>/operators/client`, `<plugin>/operators/server` |
+| Auth providers/adapters/callbacks/events | `<plugin>/auth/providers`, `<plugin>/auth/adapters`, `<plugin>/auth/callbacks`, `<plugin>/auth/events` |
+| Agents | `<plugin>/agents` |
+| All plugins | `<plugin>/types` (and optionally `<plugin>/schemas`) |
+
+For each of these that the plugin uses, add an **explicit file entry** to `exports`. Explicit entries take precedence over wildcards, so the wildcard can stay for other paths:
+
+```json
+{
+  "exports": {
+    "./connections": "./dist/connections.js",
+    "./types": "./dist/types.js",
+    "./*": "./dist/*"
+  }
+}
+```
+
+Do **not** rely on `"./*": "./dist/*"` alone for any of the entry-point subpaths above — it maps the specifier to a directory whenever a folder with the same name exists next to the barrel file.
+
+If the barrel file does not exist (e.g. only `dist/connections/MyConnection.js` exists), create a barrel `src/connections.js` that re-exports each type and rebuild, then point the export at it.
+
+### 2. Replace `next-auth` imports in auth plugins with `@auth/core`
+
+For auth provider plugins:
+
+```javascript
+// Before (v4/v5)
+import _googleProvider from 'next-auth/providers/google';
+const GoogleProvider = _googleProvider.default; // CJS workaround
+
+// After (v6)
+import GoogleProvider from '@auth/core/providers/google';
+```
+
+All provider module ids are unchanged (`@auth/core/providers/<id>` matches the old `next-auth/providers/<id>`), and the `.default` CJS workaround is no longer needed — `@auth/core` is native ESM.
+
+For custom OAuth/OIDC provider objects, the v4 shape still works; for OpenID Connect providers prefer the v5 `type: 'oidc'` (discovery and ID token handling are built in, so `idToken: true` is redundant).
+
+For adapter plugins wrapping the MongoDB adapter:
+
+```javascript
+// Before
+import { MongoDBAdapter } from '@next-auth/mongodb-adapter';
+
+// After — same call shape
+import { MongoDBAdapter } from '@auth/mongodb-adapter';
+```
+
+Update `package.json`: remove `next` and `next-auth` from dependencies/peerDependencies; add `@auth/core` (and `@auth/mongodb-adapter` if used).
+
+Plugins that keep their own `next-auth@4` dependency for provider factories (e.g. a custom email provider wrapping `next-auth/providers/email`) continue to work — the v4 provider object shape is compatible with the Auth.js engine — but migrating removes a duplicate auth engine from the install.
+
+### 3. Remove any `next/*` imports and `NEXT_PUBLIC_*` env reads
+
+Client plugin code is bundled by Vite. `next/head`, `next/link`, `next/router`, `next/dynamic` no longer exist — blocks receive `Components.Head`, `Components.Link` and `router` through the framework adapter props as before, so most blocks need no change. `process.env.NEXT_PUBLIC_*` variables are not defined under Vite; only `process.env.NODE_ENV` is replaced.
+
+### 4. Prefer ESM dists
+
+Server-side plugin files load as Node ESM. CJS dists still load through Node's interop, but explicit file exports are required either way. If the plugin's build outputs CJS, consider adding `"type": "module"` and building ESM output — this matches all `@lowdefy/*` plugin packages.
+
+## Files to Check
+
+- `package.json` — `exports` map, `type`, dependencies (`next`, `next-auth`, `@next-auth/mongodb-adapter`)
+- `src/auth/**` — `next-auth` imports
+- `src/**` — `next/*` imports, `NEXT_PUBLIC_*` reads
+- Build output (`dist/`) — confirm the barrel files the exports point at actually exist
+
+## Examples
+
+### Before — plugin `package.json` (crashes the v6 server)
+
+```json
+{
+  "name": "@my-org/plugin-local",
+  "type": "module",
+  "exports": {
+    "./*": "./dist/*"
+  },
+  "peerDependencies": {
+    "next-auth": ">=4.24"
+  }
+}
+```
+
+### After — plugin `package.json`
+
+```json
+{
+  "name": "@my-org/plugin-local",
+  "type": "module",
+  "exports": {
+    "./connections": "./dist/connections.js",
+    "./types": "./dist/types.js",
+    "./*": "./dist/*"
+  },
+  "dependencies": {
+    "@auth/core": "0.41.3"
+  }
+}
+```
+
+## Edge Cases
+
+- **`<plugin>/schemas` and `<plugin>/metas`**: the build imports these inside `try/catch` — a missing `schemas` export degrades gracefully (no schema validation for that plugin), but a wrong one that resolves to a directory still warns. Point them at files or omit them.
+- **Deep wildcard exports** (`"./connections/*": "./dist/connections/*"`) for per-file imports can coexist with the explicit barrel entry.
+- **Published plugins**: a new version must be published; `lowdefy build` installs from the registry. For local testing, use a `link:`/`file:` plugin reference.
+
+## Verification
+
+1. Resolve every generated plugin import the way Node will. From the built server directory (`<config-directory>/.lowdefy/server`):
+
+   ```bash
+   node --input-type=module -e "
+   import fs from 'node:fs';
+   import { fileURLToPath } from 'node:url';
+   const files = ['build/plugins/connections.js','build/plugins/agents.js','build/plugins/operators/server.js','build/plugins/auth/adapters.js','build/plugins/auth/callbacks.js','build/plugins/auth/events.js','build/plugins/auth/providers.js'];
+   let bad = 0;
+   for (const f of files) {
+     if (!fs.existsSync(f)) continue;
+     for (const m of fs.readFileSync(f, 'utf8').matchAll(/from '([^']+)'/g)) {
+       try {
+         const p = fileURLToPath(import.meta.resolve(m[1], new URL('build/plugins/x.js', import.meta.url).href));
+         const stat = fs.statSync(p, { throwIfNoEntry: false });
+         if (!stat || stat.isDirectory()) { console.log('BAD:', m[1], '→', p); bad++; }
+       } catch (e) { console.log('BAD:', m[1], e.code); bad++; }
+     }
+   }
+   console.log(bad === 0 ? 'all server plugin imports resolve to files' : bad + ' failing imports');
+   "
+   ```
+
+   Note: a plain `import.meta.resolve` check is not enough — it does not touch the filesystem, so the `stat` check is what catches directory resolutions.
+
+2. `lowdefy build && lowdefy start` — the server must boot without `ERR_UNSUPPORTED_DIR_IMPORT` or `ERR_MODULE_NOT_FOUND`.
+
+3. For auth plugins: complete a sign-in flow (the providers list at `/api/auth/providers` must include the plugin's provider ids).

package/v6-0-0/02-s3-blocks-to-file-blocks.md

@@ -0,0 +1,156 @@
+# Migration: S3 Blocks → Provider-Neutral File Blocks
+
+## Context
+
+The S3-specific file blocks are deprecated in favour of provider-neutral blocks in
+`@lowdefy/blocks-files` that work with any storage connection (AWS S3 and S3-compatible
+services, Google Cloud Storage, Azure Blob Storage):
+
+- `S3UploadButton` → `Upload`
+- `S3UploadPhoto` → `UploadPhoto`
+- `S3UploadDragger` → `UploadDragger`
+- `S3Download` → `Download`
+
+The request-id properties are renamed with them:
+
+- `s3PostPolicyRequestId` → `uploadPolicyRequestId` (upload blocks, TiptapInput,
+  TiptapMentionInput, AgentChat `sender.attachments`)
+- `s3GetPolicyRequestId` → `downloadPolicyRequestId` (Download block)
+
+**This migration is optional.** The S3\* block names and legacy properties keep working as
+deprecated aliases — they log a console deprecation warning and will be removed in a future
+major. Migrating now silences the warnings and drops the misleading S3 naming.
+
+The requests behind the blocks (`AwsS3PresignedPostPolicy`, `AwsS3PresignedGetObject`) are
+NOT renamed — only the block types and their request-id properties change.
+
+## What to Do
+
+| Old                                              | New                                          |
+| ------------------------------------------------ | -------------------------------------------- |
+| `type: S3UploadButton`                           | `type: Upload`                               |
+| `type: S3UploadPhoto`                            | `type: UploadPhoto`                          |
+| `type: S3UploadDragger`                          | `type: UploadDragger`                        |
+| `type: S3Download`                               | `type: Download`                             |
+| `properties.s3PostPolicyRequestId`               | `properties.uploadPolicyRequestId`           |
+| `properties.s3GetPolicyRequestId`                | `properties.downloadPolicyRequestId`         |
+| `sender.attachments.s3PostPolicyRequestId` (AgentChat) | `sender.attachments.uploadPolicyRequestId` |
+
+Rename the block `type:` and its request-id property together in one pass — the generic
+blocks do not read the legacy property names (only the aliases map them).
+
+`TiptapInput` and `TiptapMentionInput` keep their block type; only rename their
+`s3PostPolicyRequestId` property.
+
+## Files to Check
+
+Glob: `**/*.{yaml,yml}`
+Grep: `S3UploadButton|S3UploadPhoto|S3UploadDragger|S3Download|s3PostPolicyRequestId|s3GetPolicyRequestId`
+
+## Examples
+
+### Before — upload button
+
+```yaml
+- id: file_upload
+  type: S3UploadButton
+  properties:
+    s3PostPolicyRequestId: upload_policy
+    accept: '.pdf'
+```
+
+### After
+
+```yaml
+- id: file_upload
+  type: Upload
+  properties:
+    uploadPolicyRequestId: upload_policy
+    accept: '.pdf'
+```
+
+### Before — download list
+
+```yaml
+- id: file_list
+  type: S3Download
+  properties:
+    s3GetPolicyRequestId: download_policy
+    fileList:
+      _state: uploaded.fileList
+```
+
+### After
+
+```yaml
+- id: file_list
+  type: Download
+  properties:
+    downloadPolicyRequestId: download_policy
+    fileList:
+      _state: uploaded.fileList
+```
+
+### Before — Tiptap editor image uploads
+
+```yaml
+- id: editor
+  type: TiptapInput
+  properties:
+    s3PostPolicyRequestId: image_upload_policy
+```
+
+### After
+
+```yaml
+- id: editor
+  type: TiptapInput
+  properties:
+    uploadPolicyRequestId: image_upload_policy
+```
+
+### Before — AgentChat attachments
+
+```yaml
+sender:
+  attachments:
+    enabled: true
+    s3PostPolicyRequestId: get_upload_policy
+```
+
+### After
+
+```yaml
+sender:
+  attachments:
+    enabled: true
+    uploadPolicyRequestId: get_upload_policy
+```
+
+## Edge Cases
+
+- **Custom CSS selectors:** the generic blocks emit `lf-upload`, `lf-upload-photo`, and
+  `lf-upload-dragger` element classes instead of `lf-s3-upload-button`, `lf-s3-upload-photo`,
+  and `lf-s3-upload-dragger` (the aliases keep the legacy classes; the renamed blocks do not).
+  Grep CSS/`style:` config for `lf-s3-` and update selectors — including inner classes like
+  `.lf-s3-upload-photo-icon` → `.lf-upload-photo-icon` and the CSS variable
+  `--lf-s3-dragger-height` → `--lf-dragger-height`.
+- If a request-id property value is an operator expression, rename the key and keep the value.
+- Do not rename request types (`AwsS3PresignedPostPolicy`, `AwsS3PresignedGetObject`) or
+  connection types (`AwsS3Bucket`) — they are unchanged.
+- References in markdown/help text (e.g. docs strings inside the app) can be renamed too, but
+  flag them for human review rather than assuming.
+
+## Verification
+
+No old block types or legacy property names should remain:
+
+```
+grep -rnE 'type: S3(UploadButton|UploadPhoto|UploadDragger|Download)|s3PostPolicyRequestId|s3GetPolicyRequestId' --include='*.yaml' --include='*.yml' .
+```
+
+Also confirm no stale CSS selectors:
+
+```
+grep -rn 'lf-s3-' --include='*.yaml' --include='*.yml' --include='*.css' .
+```