Fix HMR view-name resolution + split watch from artifactWatch

The blocked verify-hmr-visual smoke test (edit a view in dev mode →
expect API to return fresh value < 1s) was failing for two reasons.

1. View bundles in the compiled artifact have no top-level \`name\` —
   their identity is the target object encoded under \`list.data.object\`
   (same convention used by ObjectQL.SchemaRegistry.resolveMetadataItemName).
   MetadataPlugin._parseAndRegisterArtifact had a naive
   so MetadataService.get('view', X) always returned undefined and
   the read path fell through to the boot-only SchemaRegistry copy.

   Derive the registration key from \`list.data.object\` (or
   \`form.data.object\`) when no top-level \`name\` is present.

2. Enabling MetadataPlugin's \`watch\` to pick up dist/objectstack.json
   changes also turned on NodeMetadataManager's recursive source-file
   scan, which polling-scanned the entire project root (incl.
   node_modules) and either hung startup or hit EMFILE on macOS.

   Split into two flags:
   - \`watch\`: source-file scanner (default false; opt-in)
   - \`artifactWatch\`: cheap single-file watcher on the compiled
     artifact (auto-enabled in dev by StandaloneStack)

Also pre-emptively switch the CLI dev watcher and NodeMetadataManager
to chokidar polling — native fs.watch hits EMFILE on busy macOS hosts
where parallel node processes saturate the FD pool.

Regression test in packages/metadata/src/plugin.test.ts asserts that
a view artifact item with no top-level \`name\` lands in MetadataManager
under its target-object key.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: os-zhuang

.changeset/pr10e-hmr-view-name-resolution.md

@@ -0,0 +1,30 @@
+---
+'@objectstack/metadata': patch
+'@objectstack/runtime': patch
+---
+
+Fix dev-mode HMR data-reload for view metadata.
+
+`MetadataPlugin._parseAndRegisterArtifact` previously required a top-level
+`name` on every artifact item and silently skipped those without one.
+View bundles in the compiled artifact carry no top-level `name` (their
+identity is the target object, encoded under `list.data.object` /
+`form.data.object` — same pattern used by `ObjectQL.SchemaRegistry`'s
+`resolveMetadataItemName`). As a result, artifact-loaded views never
+reached `MetadataManager`, and HMR file pushes never affected the read
+path: API responses kept returning the boot-time `SchemaRegistry` copy.
+
+This change derives the registration key from `list.data.object` (or
+`form.data.object`) when no top-level `name` is present, mirroring the
+ObjectQL convention.
+
+Also splits the `MetadataPlugin` watch flag into two independent
+options so dev mode can enable artifact-file HMR without paying the
+cost of the source-file scanner:
+
+- `watch` — controls `NodeMetadataManager`'s recursive source scan
+  (default `false`; turning it on in artifact mode would polling-scan
+  the entire project root including `node_modules`).
+- `artifactWatch` — controls the cheap single-file polling watcher on
+  the compiled artifact (`dist/objectstack.json`). The standalone stack
+  enables this automatically when `NODE_ENV !== 'production'`.

examples/app-crm/dist/objectstack.json

@@ -14125,7 +14125,7 @@
       "listViews": {
         "case_workflow": {
           "name": "case_workflow",
-          "label": "Service Workflow",
+          "label": "Service Workflow (HMR-LIVE)",
           "type": "kanban",
           "data": {
             "provider": "object",

packages/cli/src/commands/dev.ts

@@ -237,6 +237,13 @@ export default class Dev extends Command {
         ],
         ignoreInitial: true,
         persistent: true,
+        // Use polling to avoid `fs.watch` EMFILE on macOS when other
+        // long-running node processes (VS Code, parallel dev servers)
+        // saturate the native file-descriptor pool. Polling at 750ms
+        // is fast enough for human-perceived HMR.
+        usePolling: true,
+        interval: 750,
+        binaryInterval: 1500,
       });
 
       let timer: ReturnType<typeof setTimeout> | null = null;

packages/metadata/src/node-metadata-manager.ts

@@ -59,6 +59,12 @@ export class NodeMetadataManager extends MetadataManager {
       ignored,
       persistent,
       ignoreInitial: true,
+      // Use polling to avoid `fs.watch` EMFILE on macOS / busy dev hosts.
+      // Recursive watch over a project root would otherwise wire native
+      // watches across the entire tree, easily exhausting the FD pool.
+      usePolling: true,
+      interval: 1000,
+      binaryInterval: 2000,
     });
 
     this.watcher.on('add', async (filePath) => {

packages/metadata/src/plugin.test.ts

@@ -57,3 +57,56 @@ describe('MetadataPlugin — bootstrap × watch coupling (D2)', () => {
         expect((mgr as any).watcher).toBeUndefined();
     });
 });
+
+// ─────────────────────────────────────────────────────────────────────────
+// PR-10e regression: artifact view items have no top-level `name`. Their
+// identity is the target object (encoded in `list.data.object` /
+// `form.data.object`). When `_parseAndRegisterArtifact` consumes a
+// compiled artifact it must derive the view name from the inner data
+// source — otherwise views are silently SKIPPED and reads through
+// `metadataService.get('view', <object>)` return undefined, falling
+// back to the boot-time SchemaRegistry copy and breaking HMR data
+// reload.
+// ─────────────────────────────────────────────────────────────────────────
+describe('MetadataPlugin._parseAndRegisterArtifact — view name resolution (PR-10e)', () => {
+    it('registers view items by their target object even when top-level `name` is absent', async () => {
+        const plugin = new MetadataPlugin({
+            watch: false,
+            config: { bootstrap: 'eager' },
+            projectId: 'proj_test',
+        });
+        const mgr = (plugin as any).manager as NodeMetadataManager;
+
+        const fakeCtx = {
+            logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+        } as any;
+
+        const artifact = {
+            id: 'com.example.test',
+            name: 'test',
+            version: '0.0.0',
+            type: 'app',
+            scope: 'app',
+            namespace: 'test',
+            defaultDatasource: 'memory',
+            views: [
+                {
+                    // intentionally NO top-level name — mirrors compiled artifact shape
+                    list: { name: 'all_case', label: 'All Cases', type: 'grid',
+                            data: { provider: 'object', object: 'case' }, columns: [] },
+                    listViews: {
+                        case_workflow: { name: 'case_workflow', label: 'Service Workflow', type: 'kanban',
+                                         data: { provider: 'object', object: 'case' }, columns: [] },
+                    },
+                },
+            ],
+        };
+
+        await (plugin as any)._parseAndRegisterArtifact(fakeCtx, artifact, 'test-artifact');
+
+        const registered = await mgr.get('view', 'case');
+        expect(registered).toBeDefined();
+        const label = (registered as any)?.listViews?.case_workflow?.label;
+        expect(label).toBe('Service Workflow');
+    });
+});

packages/metadata/src/plugin.ts

@@ -62,7 +62,30 @@ const ARTIFACT_FIELD_TO_TYPE: Record<string, string> = {
 
 export interface MetadataPluginOptions {
     rootDir?: string;
+    /**
+     * When `true`, NodeMetadataManager scans `rootDir` for source-file metadata
+     * (yaml/json/ts/js loaders) AND attaches a chokidar watcher to react to
+     * filesystem changes. In **artifact-mode** (this is the normal path when
+     * a `defineStack()` config is compiled into `dist/objectstack.json`) this
+     * filesystem scan is redundant and expensive — leave `watch: false`.
+     *
+     * The artifact-file HMR watcher is controlled separately by
+     * {@link artifactWatch} so that the cheap, single-file polling watcher
+     * can be enabled in dev without paying the cost of scanning the entire
+     * project root.
+     *
+     * Default: `false` (post PR-10e — was previously `true`).
+     */
     watch?: boolean;
+    /**
+     * When `true` AND `artifactSource.mode === 'local-file'`, attach a
+     * polling chokidar watcher to the artifact file so the server reloads
+     * metadata when the CLI recompiles `dist/objectstack.json` in dev mode.
+     * Independent of {@link watch} (which controls the source-file scanner).
+     *
+     * Default: `true` when `artifactSource` is set, otherwise `false`.
+     */
+    artifactWatch?: boolean;
     config?: Partial<MetadataPluginConfig>;
     /** Organization ID for metadata-scoped consumers; MetadataPlugin itself does not persist runtime metadata. */
     organizationId?: string;
@@ -297,7 +320,7 @@ export class MetadataPlugin implements Plugin {
                     }
                 });
 
-                // ── ADR-0008 PR-8: server-side artifact-file watcher ────
+                // ── ADR-0008 PR-8 / PR-10e: server-side artifact-file watcher ──
                 //
                 // When running in local-file artifact mode (e.g. `os dev`
                 // serving from `dist/objectstack.json`), watch the
@@ -306,8 +329,15 @@ export class MetadataPlugin implements Plugin {
                 // POST endpoint. The POST route stays available for
                 // external trigger sources (cloud webhook, git hook,
                 // ad-hoc curl) but is no longer the only signal.
+                //
+                // Gated on `artifactWatch` (NOT `watch` — the latter
+                // controls the source-file scanner which is redundant in
+                // artifact mode). Default: on when artifactSource is
+                // present, off otherwise.
                 const src = this.options.artifactSource;
-                if (src?.mode === 'local-file' && this.options.watch !== false && !/^https?:\/\//i.test(src.path)) {
+                const wantArtifactWatch = this.options.artifactWatch
+                    ?? (src?.mode === 'local-file');
+                if (src?.mode === 'local-file' && wantArtifactWatch && !/^https?:\/\//i.test(src.path)) {
                     try {
                         const { watch: chokidarWatch } = await import('chokidar');
                         const w = chokidarWatch(src.path, {
@@ -449,7 +479,26 @@ export class MetadataPlugin implements Plugin {
             const items = (metadata as any)[field];
             if (!Array.isArray(items) || items.length === 0) continue;
             for (const item of items) {
-                const name = (item as any)?.name;
+                // Most metadata items carry a top-level `name`. The `View`
+                // container (UI namespace) is an exception: it has no own
+                // `name` — its identity is the target object, encoded under
+                // `list.data.object` (or `form.data.object`). Mirror the
+                // resolution used by `ObjectQL.SchemaRegistry` so that
+                // artifact-loaded views land in `MetadataManager` under the
+                // SAME key reads expect (`metadataService.get('view', <object>)`).
+                // Without this, HMR pushes views into the registry only via
+                // AppPlugin's `manifest.register`, which targets the
+                // boot-only SchemaRegistry cache and is never refreshed on
+                // file edits — leaving MetadataService empty for view/* and
+                // forcing all reads to return the stale boot copy.
+                let name = (item as any)?.name;
+                if (!name) {
+                    if (metaType === 'view') {
+                        name =
+                            (item as any)?.list?.data?.object
+                            ?? (item as any)?.form?.data?.object;
+                    }
+                }
                 if (!name) continue;
                 if (manifestPackageId && (item as any)._packageId === undefined) {
                     (item as any)._packageId = manifestPackageId;

packages/metadata/vitest.config.ts

@@ -9,6 +9,7 @@ export default defineConfig({
       '@objectstack/core': path.resolve(__dirname, '../core/src/index.ts'),
       '@objectstack/driver-memory': path.resolve(__dirname, '../plugins/driver-memory/src/index.ts'),
       '@objectstack/spec/api': path.resolve(__dirname, '../spec/src/api/index.ts'),
+      '@objectstack/spec/cloud': path.resolve(__dirname, '../spec/src/cloud/index.ts'),
       '@objectstack/spec/contracts': path.resolve(__dirname, '../spec/src/contracts/index.ts'),
       '@objectstack/spec/data': path.resolve(__dirname, '../spec/src/data/index.ts'),
       '@objectstack/spec/kernel': path.resolve(__dirname, '../spec/src/kernel/index.ts'),

packages/runtime/src/standalone-stack.ts

@@ -163,14 +163,19 @@ export async function createStandaloneStack(config?: StandaloneStackConfig): Pro
     const plugins: any[] = [
         driverPlugin,
         new MetadataPlugin({
-            // Enable the artifact-file watcher in development so edits to
-            // `*.view.ts` / `*.flow.ts` etc. (which the CLI dev-mode watcher
-            // recompiles into `dist/objectstack.json`) are picked up by the
-            // running server WITHOUT requiring a manual restart or HMR POST.
-            // In production (`NODE_ENV=production`), the artifact is static
-            // and watching is unnecessary — keep the historical default-off
-            // behavior to avoid the chokidar process cost.
-            watch: process.env.NODE_ENV !== 'production',
+            // Source-file scanner OFF — declarative metadata is loaded
+            // from the compiled artifact, not from yaml/json files on
+            // disk. Scanning would also recursively watch the project
+            // root (incl. node_modules), which is expensive and prone
+            // to EMFILE.
+            watch: false,
+            // Artifact-file HMR ON in non-production so edits to
+            // `*.view.ts` / `*.flow.ts` (which the CLI dev-mode watcher
+            // recompiles into `dist/objectstack.json`) are picked up by
+            // the running server WITHOUT requiring a manual restart.
+            // Uses polling under the hood (see plugin.ts) to avoid
+            // `fs.watch` EMFILE on macOS / busy dev hosts.
+            artifactWatch: process.env.NODE_ENV !== 'production',
             projectId,
             artifactSource: { mode: 'local-file', path: artifactPath },
         }),