feat(studio): add Local/Custom (this env) scope to the package selector (#1946)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

.changeset/studio-local-custom-scope.md

@@ -0,0 +1,22 @@
+---
+"@object-ui/app-shell": minor
+---
+
+feat(studio): add a "Local / Custom (this env)" scope to the package selector
+
+In a self-hosted, metadata-customizable environment (single-tenant — no org
+dimension), the package selector only listed code packages, so metadata authored
+at runtime (`package_id = null` / `sys_metadata` provenance) was filtered out of
+every code-package view and became un-navigable — opening such an item redirected
+to "new". This complements framework #2252 + objectui #1937, which stop runtime
+metadata from being stamped into a loaded code package and keep it editable.
+
+- Surface a stable, always-present "Local / Custom (this env)" entry in the
+  Studio package context-selector (`ContextSelectors`), mapped to the
+  `sys_metadata` scope the metadata list/get API already understands.
+- Accept that scope in the metadata-admin pages (`StudioHomePage`,
+  `DirectoryPage`, `ResourceListPage`) via a shared `buildPackageScopeOptions`
+  helper, so it no longer redirects, and the list shows this environment's
+  runtime-authored items (`package_id = null`).
+- On the Studio home grid, the Local scope shows every runtime-creatable type so
+  the user can start authoring locally even with zero items yet.

packages/app-shell/src/layout/ContextSelectors.tsx

@@ -27,6 +27,18 @@ import {
 import { getIcon } from '../utils/getIcon';
 import { resolveI18nLabel } from '../utils';
 
+// Local/Custom scope sentinel — kept inline (not imported from metadata-admin)
+// so this layout module never forms an import cycle with the metadata-admin
+// views. Mirrors `LOCAL_PACKAGE_ID` in views/metadata-admin/package-scope.ts.
+const LOCAL_SCOPE_ID = 'sys_metadata';
+function localScopeLabel(): string {
+  const lang =
+    (typeof document !== 'undefined' && document.documentElement?.lang) ||
+    (typeof navigator !== 'undefined' && navigator.language) ||
+    '';
+  return /^zh/i.test(lang) ? '本地 / 自定义（本环境）' : 'Local / Custom (this env)';
+}
+
 export interface ContextSelectorFilter {
   key: string;
   op?: 'eq' | 'ne' | 'in' | 'nin';
@@ -117,6 +129,15 @@ function useSelectorOptions(def: ContextSelectorDef): { options: Option[]; refet
         opts.push({ value, label: typeof labelRaw === 'string' && labelRaw ? labelRaw : value });
       }
       opts.sort((a, b) => a.label.localeCompare(b.label));
+      // The package-scope selector gets a stable "Local / Custom (this env)"
+      // entry for this environment's runtime, DB-authored metadata — it is
+      // never a real package row (`package_id = null` / `sys_metadata`
+      // provenance) yet must always be selectable so org-authored items are
+      // discoverable and editable. The metadata list/get API already treats
+      // `?package=sys_metadata` as exactly this local scope.
+      if (/package/i.test(endpoint) && !opts.some((o) => o.value === LOCAL_SCOPE_ID)) {
+        opts.push({ value: LOCAL_SCOPE_ID, label: localScopeLabel() });
+      }
       setOptions(opts);
     } catch {
       /* offline / unauthorized — render with no options */

packages/app-shell/src/views/metadata-admin/DirectoryPage.tsx

@@ -37,6 +37,7 @@ import {
   tFormat,
   detectLocale,
 } from './i18n';
+import { buildPackageScopeOptions } from './package-scope';
 
 const DOMAIN_ICONS: Record<string, React.ComponentType<{ className?: string }>> = {
   data: Database,
@@ -98,21 +99,7 @@ export function MetadataDirectoryPage() {
       try {
         const list = await client.list<any>('package');
         if (cancelled) return;
-        const SYSTEM_SCOPES = new Set(['system', 'cloud']);
-        const rows = (list ?? [])
-          .map((raw) => {
-            const item =
-              raw && typeof raw === 'object' && 'item' in raw ? raw.item : raw;
-            const m = ((item as any)?.manifest ?? item ?? {}) as Record<string, unknown>;
-            return {
-              id: m.id as string,
-              scope: m.scope as string,
-              name: (m.name as string) || (m.id as string),
-            };
-          })
-          .filter((p) => p.id && !SYSTEM_SCOPES.has(p.scope));
-        rows.sort((a, b) => a.name.localeCompare(b.name));
-        setProjectPackages(rows.map((p) => ({ id: p.id, name: p.name })));
+        setProjectPackages(buildPackageScopeOptions(list));
       } catch {
         if (!cancelled) setProjectPackages([]);
       }

packages/app-shell/src/views/metadata-admin/ResourceListPage.tsx

@@ -39,6 +39,7 @@ import {
   resolveResourceConfig,
 } from './registry';
 import { t, tFormat, translateMetadataType, detectLocale } from './i18n';
+import { buildPackageScopeOptions, LOCAL_PACKAGE_ID } from './package-scope';
 
 export interface MetadataResourceListPageProps {
   type?: string;
@@ -134,21 +135,7 @@ function DefaultMetadataList({ type, appName }: { type: string; appName?: string
       try {
         const list = await client.list<any>('package');
         if (cancelled) return;
-        const SYSTEM_SCOPES = new Set(['system', 'cloud']);
-        const rows = (list ?? [])
-          .map((raw) => {
-            const item =
-              raw && typeof raw === 'object' && 'item' in raw ? raw.item : raw;
-            const m = ((item as any)?.manifest ?? item ?? {}) as Record<string, unknown>;
-            return {
-              id: m.id as string,
-              scope: m.scope as string,
-              name: (m.name as string) || (m.id as string),
-            };
-          })
-          .filter((p) => p.id && !SYSTEM_SCOPES.has(p.scope));
-        rows.sort((a, b) => a.name.localeCompare(b.name));
-        setProjectPackages(rows.map((p) => ({ id: p.id, name: p.name })));
+        setProjectPackages(buildPackageScopeOptions(list));
       } catch {
         if (!cancelled) setProjectPackages([]);
       }
@@ -287,8 +274,11 @@ function DefaultMetadataList({ type, appName }: { type: string; appName?: string
         // 'sys_metadata' sentinel and untagged rows never match.
         if (!activePackage) return false;
         const pkg = (row.item as any)?._packageId;
-        const effectivePkg = !pkg || pkg === 'sys_metadata' ? null : pkg;
-        return effectivePkg === activePackage;
+        const isLocal = !pkg || pkg === LOCAL_PACKAGE_ID;
+        // Local/Custom scope surfaces this environment's runtime-authored items
+        // (untagged / `sys_metadata` provenance); a code package shows its own.
+        if (activePackage === LOCAL_PACKAGE_ID) return isLocal;
+        return !isLocal && pkg === activePackage;
       }),
     [items, activePackage, config],
   );

packages/app-shell/src/views/metadata-admin/StudioHomePage.tsx

@@ -59,6 +59,7 @@ import {
   tFormat,
   detectLocale,
 } from './i18n';
+import { buildPackageScopeOptions, LOCAL_PACKAGE_ID } from './package-scope';
 
 const HIDDEN_TYPES = new Set(['field', 'package']);
 
@@ -139,21 +140,7 @@ export function StudioHomePage() {
       try {
         const list = await client.list<any>('package');
         if (cancelled) return;
-        const SYSTEM_SCOPES = new Set(['system', 'cloud']);
-        const rows = (list ?? [])
-          .map((raw) => {
-            const item =
-              raw && typeof raw === 'object' && 'item' in raw ? raw.item : raw;
-            const m = ((item as any)?.manifest ?? item ?? {}) as Record<string, unknown>;
-            return {
-              id: m.id as string,
-              scope: m.scope as string,
-              name: (m.name as string) || (m.id as string),
-            };
-          })
-          .filter((p) => p.id && !SYSTEM_SCOPES.has(p.scope));
-        rows.sort((a, b) => a.name.localeCompare(b.name));
-        setProjectPackages(rows.map((p) => ({ id: p.id, name: p.name })));
+        setProjectPackages(buildPackageScopeOptions(list));
       } catch {
         if (!cancelled) setProjectPackages([]);
       }
@@ -194,6 +181,9 @@ export function StudioHomePage() {
       entries.filter((e) => {
         if (HIDDEN_TYPES.has(e.type)) return false;
         if (!activePackage) return false;
+        // Local/Custom scope: show every runtime-creatable type so the user can
+        // start authoring any kind of metadata here, even with zero items yet.
+        if (activePackage === LOCAL_PACKAGE_ID) return e.allowOrgOverride || e.allowRuntimeCreate;
         return (packagesByType[e.type] ?? []).includes(activePackage);
       }),
     [activePackage, entries, packagesByType],

packages/app-shell/src/views/metadata-admin/i18n.ts

@@ -212,6 +212,7 @@ const ENGINE_STRINGS_EN: Record<string, string> = {
   'engine.list.warnCount': '{count} warning(s):',
   'engine.list.allSources': 'All sources',
   'engine.list.allPackages': 'All packages',
+  'engine.package.local': 'Local / Custom (this env)',
   'engine.list.packageFilter': 'Package',
   'engine.list.source.artifact': 'Artifact',
   'engine.list.source.runtime': 'Runtime',
@@ -898,6 +899,7 @@ const ENGINE_STRINGS_ZH: Record<string, string> = {
   'engine.list.warnCount': '{count} 个警告：',
   'engine.list.allSources': '全部来源',
   'engine.list.allPackages': '全部软件包',
+  'engine.package.local': '本地 / 自定义（本环境）',
   'engine.list.packageFilter': '软件包',
   'engine.list.source.artifact': '代码包',
   'engine.list.source.runtime': '运行时',

packages/app-shell/src/views/metadata-admin/package-scope.ts

@@ -0,0 +1,53 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { detectLocale, t } from './i18n';
+
+/**
+ * Sentinel "package" id for this environment's runtime, DB-authored metadata —
+ * items with no code-package binding (`package_id IS NULL`). The metadata
+ * list/get API treats `?package=sys_metadata` as exactly that local scope on
+ * READ, and a WRITE under it persists `package_id = null` (matching the
+ * server's runtime-only provenance, see framework #2252).
+ *
+ * Why this exists: a self-hosted, metadata-customizable environment is
+ * single-tenant — there is no "org" dimension here; the real axis is
+ * code-package vs. runtime (DB-authored). Before this scope, the package
+ * selector only listed code packages, so metadata authored at runtime
+ * (`package_id = null`) was filtered out of every code-package view and became
+ * un-navigable (the route redirected to "new"). Surfacing the local scope as a
+ * first-class, always-present selector entry makes it discoverable and editable.
+ */
+export const LOCAL_PACKAGE_ID = 'sys_metadata';
+
+const SYSTEM_SCOPES = new Set(['system', 'cloud']);
+
+/**
+ * Build the Studio package-scope options from the raw `package` metadata list.
+ * Filters out system/cloud-scoped packages and appends a stable
+ * "Local / Custom (this environment)" scope so runtime metadata authored here
+ * is always selectable/visible — even when zero items exist yet.
+ */
+export function buildPackageScopeOptions(
+  rawList: unknown[] | null | undefined,
+): { id: string; name: string }[] {
+  const rows = (rawList ?? [])
+    .map((raw) => {
+      const item =
+        raw && typeof raw === 'object' && 'item' in raw ? (raw as { item: unknown }).item : raw;
+      const m = ((item as { manifest?: unknown } | null)?.manifest ?? item ?? {}) as Record<
+        string,
+        unknown
+      >;
+      return {
+        id: m.id as string,
+        scope: m.scope as string,
+        name: (m.name as string) || (m.id as string),
+      };
+    })
+    .filter((p) => p.id && !SYSTEM_SCOPES.has(p.scope));
+  rows.sort((a, b) => a.name.localeCompare(b.name));
+  const opts = rows.map((p) => ({ id: p.id, name: p.name }));
+  // Append (never default) so the existing first-code-package default is
+  // preserved; the user opts into the local scope explicitly.
+  return [...opts, { id: LOCAL_PACKAGE_ID, name: t('engine.package.local', detectLocale()) }];
+}