@jskit-ai/console-web 0.1.127 → 0.1.129

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@jskit-ai/console-web",
-  "version": "0.1.127",
+  "version": "0.1.129",
   "type": "module",
   "scripts": {
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/auth-web": "0.1.159",
-    "@jskit-ai/console-core": "0.1.122",
-    "@jskit-ai/shell-web": "0.1.163"
+    "@jskit-ai/auth-web": "0.1.161",
+    "@jskit-ai/console-core": "0.1.124",
+    "@jskit-ai/shell-web": "0.1.165"
   },
   "description": "Authenticated console surface scaffold and surface policy wiring.",
   "jskit": {
@@ -36,11 +36,7 @@
             "subpath": "./client",
             "summary": "Exports no runtime API today (reserved console surface package entrypoint)."
           }
-        ],
-        "containerTokens": {
-          "server": [],
-          "client": []
-        }
+        ]
       },
       "ui": {
         "placements": {
@@ -50,7 +46,7 @@
               "surfaces": [
                 "console"
               ],
-              "source": "templates/src/pages/console/settings.vue"
+              "source": "patterns/console-surface/example/src/pages/console/settings.vue"
             }
           ],
           "topology": {
@@ -95,7 +91,7 @@
               ],
               "order": 600,
               "when": "auth.authenticated === true && surfaceAccess.consoleowner === true && surface !== \"console\"",
-              "source": "mutations.text#console-web-profile-menu-console-placement"
+              "source": "patterns/console-surface/example/src/pages/console/index.vue"
             },
             {
               "id": "console.web.menu.settings",
@@ -106,119 +102,11 @@
               ],
               "order": 100,
               "when": "auth.authenticated === true",
-              "source": "mutations.text#console-web-console-settings-placement"
+              "source": "patterns/console-surface/example/src/pages/console/settings.vue"
             }
           ]
         }
       }
-    },
-    "mutations": {
-      "dependencies": {
-        "runtime": {
-          "@jskit-ai/auth-web": "0.1.159",
-          "@jskit-ai/console-core": "0.1.122",
-          "@jskit-ai/shell-web": "0.1.163"
-        },
-        "dev": {}
-      },
-      "packageJson": {
-        "scripts": {
-          "server:console": "SERVER_SURFACE=console node ./bin/server.js",
-          "dev:console": "VITE_SURFACE=console vite",
-          "build:console": "VITE_SURFACE=console vite build"
-        }
-      },
-      "procfile": {},
-      "files": [
-        {
-          "from": "templates/src/pages/console.vue",
-          "toSurface": "console",
-          "toSurfaceRoot": true,
-          "ownership": "app",
-          "reason": "Install shell-driven console wrapper page.",
-          "category": "console-web",
-          "id": "console-web-page-console-wrapper"
-        },
-        {
-          "from": "templates/src/pages/console/index.vue",
-          "toSurface": "console",
-          "toSurfacePath": "index.vue",
-          "ownership": "app",
-          "reason": "Install shell-driven console page starter.",
-          "category": "console-web",
-          "id": "console-web-page-console"
-        },
-        {
-          "from": "templates/src/pages/console/settings.vue",
-          "toSurface": "console",
-          "toSurfacePath": "settings.vue",
-          "ownership": "app",
-          "reason": "Install console settings shell route scaffold for console-web.",
-          "category": "console-web",
-          "id": "console-web-page-console-settings-shell"
-        },
-        {
-          "from": "templates/src/pages/console/settings/index.vue",
-          "toSurface": "console",
-          "toSurfacePath": "settings/index.vue",
-          "ownership": "app",
-          "reason": "Install console settings index stub scaffold for app-owned landing or redirect behavior.",
-          "category": "console-web",
-          "id": "console-web-page-console-settings"
-        }
-      ],
-      "text": [
-        {
-          "op": "append-text",
-          "file": "config/surfaceAccessPolicies.js",
-          "position": "bottom",
-          "skipIfContains": "surfaceAccessPolicies.console_owner = {",
-          "value": "\nsurfaceAccessPolicies.console_owner = {\n  requireAuth: true,\n  requireFlagsAll: [\"console_owner\"]\n};\n",
-          "reason": "Register console-owner surface access policy for the console surface.",
-          "category": "console-web",
-          "id": "console-web-surface-access-policies-console-owner"
-        },
-        {
-          "op": "append-text",
-          "file": "config/public.js",
-          "position": "bottom",
-          "skipIfContains": "config.surfaceDefinitions.console = {",
-          "value": "\nconfig.surfaceDefinitions.console = {\n  id: \"console\",\n  label: \"Console\",\n  pagesRoot: \"console\",\n  enabled: true,\n  requiresAuth: true,\n  requiresWorkspace: false,\n  accessPolicyId: \"console_owner\",\n  icon: \"mdi-console-network-outline\",\n  showInSurfaceSwitchMenu: false,\n  origin: \"\"\n};\n",
-          "reason": "Register console surface definition once console-web is installed.",
-          "category": "console-web",
-          "id": "console-web-surface-config-console"
-        },
-        {
-          "op": "append-text",
-          "file": "src/placement.js",
-          "position": "bottom",
-          "skipIfContains": "id: \"console.web.profile.menu.console\"",
-          "value": "\naddPlacement({\n  id: \"console.web.profile.menu.console\",\n  target: \"auth.profile-menu\",\n  kind: \"link\",\n  surfaces: [\"*\"],\n  order: 600,\n  props: {\n    label: \"Go to console\",\n    to: \"/console\",\n    icon: \"mdi-console-network-outline\"\n  },\n  when: ({ auth, surfaceAccess, surface }) => {\n    return auth?.authenticated === true && surfaceAccess?.consoleowner === true && surface !== \"console\";\n  }\n});\n",
-          "reason": "Append owner-only console navigation entry into the authenticated profile menu outside the console surface.",
-          "category": "console-web",
-          "id": "console-web-profile-menu-console-placement"
-        },
-        {
-          "op": "append-text",
-          "file": "src/placement.js",
-          "position": "bottom",
-          "skipIfContains": "id: \"console.web.menu.settings\"",
-          "value": "\naddPlacement({\n  id: \"console.web.menu.settings\",\n  target: \"shell.primary-nav\",\n  kind: \"link\",\n  surfaces: [\"console\"],\n  order: 100,\n  props: {\n    label: \"Settings\",\n    to: \"/console/settings\",\n    icon: \"mdi-cog-outline\"\n  },\n  when: ({ auth }) => auth?.authenticated === true\n});\n",
-          "reason": "Append console-web settings menu placement into app-owned placement registry.",
-          "category": "console-web",
-          "id": "console-web-console-settings-placement"
-        },
-        {
-          "op": "append-text",
-          "file": "src/placementTopology.js",
-          "position": "bottom",
-          "skipIfContains": "owner: \"console-settings\"",
-          "value": "\naddPlacementTopology({\n  id: \"page.section-nav\",\n  owner: \"console-settings\",\n  description: \"Navigation between console settings child pages.\",\n  surfaces: [\"console\"],\n  variants: {\n    compact: {\n      outlet: \"console-settings:primary-menu\",\n      renderers: {\n        link: \"local.main.ui.surface-aware-menu-link-item\"\n      }\n    },\n    medium: {\n      outlet: \"console-settings:primary-menu\",\n      renderers: {\n        link: \"local.main.ui.surface-aware-menu-link-item\"\n      }\n    },\n    expanded: {\n      outlet: \"console-settings:primary-menu\",\n      renderers: {\n        link: \"local.main.ui.surface-aware-menu-link-item\"\n      }\n    }\n  }\n});\n",
-          "reason": "Append console settings semantic topology into app-owned placement topology.",
-          "category": "console-web",
-          "id": "console-web-settings-placement-topology"
-        }
-      ]
     }
   }
 }

package/patterns/console-surface/PATTERN.md

@@ -0,0 +1,58 @@
+---
+id: console/console-surface
+title: Owner console surface
+summary: Add a protected administration surface, settings shell, and semantic navigation through JSKIT console and shell APIs.
+keywords: admin, console, navigation, owner, placement, settings, surface
+requires: @jskit-ai/console-core, @jskit-ai/console-web, @jskit-ai/shell-web
+---
+
+# Owner console surface
+
+## Use when
+
+Use this pattern for a separate owner-only or operator-only application surface.
+
+## Do not use when
+
+Do not create a separate console merely for one settings page or when normal
+workspace roles already express the required access boundary.
+
+## Product decisions
+
+Choose who can enter the console, its route and label, which settings sections
+it owns, and how authorized users switch to and from it.
+
+## Framework APIs
+
+Use `@jskit-ai/console-core` for console capabilities,
+`@jskit-ai/console-web` for the web provider, and JSKIT shell surface,
+placement, and topology APIs for application composition.
+
+## Invariants
+
+- Server policy enforces console access before application actions run.
+- The surface definition and route pages use the same surface id.
+- The profile switch is visible only to authorized authenticated users.
+- Settings navigation uses semantic placements and responsive topology.
+- Loading screens use skeletons and do not shift the surrounding shell.
+
+## Example files
+
+`example/` contains concrete console root, landing, and settings routes. Adapt
+them together with the surface policy and placement examples described here.
+
+## Variation points
+
+Change the surface id, access policy, settings hierarchy, routes, labels, icons,
+and switch placement to fit the product's administration model.
+
+## Verification
+
+Test forbidden and authorized entry, switching between surfaces, direct route
+loads, compact navigation, settings navigation, and production build output.
+
+## Avoid
+
+- treating a hidden navigation item as authorization
+- sharing normal-user pages merely by changing their route prefix
+- generator ownership or appended source fragments

package/test/packageMetadata.test.js

@@ -1,177 +1,32 @@
 import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import test from "node:test";
-import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import packageJson from "../package.json" with { type: "json" };
 
-const packageMetadata = packageJson.jskit;
-
-const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
-const PACKAGE_DIR = path.resolve(TEST_DIRECTORY, "..");
-
-function findFileMutation(id) {
-  const files = packageMetadata?.mutations?.files;
-  return Array.isArray(files)
-    ? files.find((entry) => String(entry?.id || "").trim() === id) || null
-    : null;
-}
-
-function findTextMutation(id) {
-  const text = packageMetadata?.mutations?.text;
-  return Array.isArray(text)
-    ? text.find((entry) => String(entry?.id || "").trim() === id) || null
-    : null;
-}
-
-function readOutlets(target = "") {
-  const outlets = packageMetadata?.metadata?.ui?.placements?.outlets;
-  const normalizedTarget = String(target || "").trim();
-  return Array.isArray(outlets)
-    ? outlets.filter((entry) => String(entry?.target || "").trim() === normalizedTarget)
-    : [];
-}
-
-function findTopology(id, owner = "") {
-  const placements = packageMetadata?.metadata?.ui?.placements?.topology?.placements;
-  const normalizedId = String(id || "").trim();
-  const normalizedOwner = String(owner || "").trim();
-  return Array.isArray(placements)
-    ? placements.find((entry) => {
-        const entryId = String(entry?.id || "").trim();
-        const entryOwner = String(entry?.owner || "").trim();
-        return entryId === normalizedId && entryOwner === normalizedOwner;
-      }) || null
-    : null;
-}
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
-function findContribution(id) {
-  const contributions = packageMetadata?.metadata?.ui?.placements?.contributions;
-  return Array.isArray(contributions)
-    ? contributions.find((entry) => String(entry?.id || "").trim() === id) || null
-    : null;
-}
+test("console-web publishes a pattern-owned console surface without source mutations", async () => {
+  const pattern = await readFile(path.join(packageRoot, "patterns/console-surface/PATTERN.md"), "utf8");
+  const page = await readFile(path.join(packageRoot, "patterns/console-surface/example/src/pages/console.vue"), "utf8");
+  const settings = await readFile(
+    path.join(packageRoot, "patterns/console-surface/example/src/pages/console/settings.vue"),
+    "utf8"
+  );
 
-test("console-web installs console surface scripts and files", () => {
-  assert.deepEqual(packageMetadata?.mutations?.packageJson?.scripts, {
-    "server:console": "SERVER_SURFACE=console node ./bin/server.js",
-    "dev:console": "VITE_SURFACE=console vite",
-    "build:console": "VITE_SURFACE=console vite build"
-  });
-  assert.deepEqual(findFileMutation("console-web-page-console-wrapper"), {
-    from: "templates/src/pages/console.vue",
-    toSurface: "console",
-    toSurfaceRoot: true,
-    ownership: "app",
-    reason: "Install shell-driven console wrapper page.",
-    category: "console-web",
-    id: "console-web-page-console-wrapper"
-  });
-  assert.deepEqual(findFileMutation("console-web-page-console"), {
-    from: "templates/src/pages/console/index.vue",
-    toSurface: "console",
-    toSurfacePath: "index.vue",
-    ownership: "app",
-    reason: "Install shell-driven console page starter.",
-    category: "console-web",
-    id: "console-web-page-console"
-  });
-  assert.deepEqual(findFileMutation("console-web-page-console-settings-shell"), {
-    from: "templates/src/pages/console/settings.vue",
-    toSurface: "console",
-    toSurfacePath: "settings.vue",
-    ownership: "app",
-    reason: "Install console settings shell route scaffold for console-web.",
-    category: "console-web",
-    id: "console-web-page-console-settings-shell"
-  });
-  assert.deepEqual(findFileMutation("console-web-page-console-settings"), {
-    from: "templates/src/pages/console/settings/index.vue",
-    toSurface: "console",
-    toSurfacePath: "settings/index.vue",
-    ownership: "app",
-    reason: "Install console settings index stub scaffold for app-owned landing or redirect behavior.",
-    category: "console-web",
-    id: "console-web-page-console-settings"
-  });
+  assert.equal(packageJson.jskit.mutations, undefined);
+  assert.match(pattern, /semantic navigation/u);
+  assert.match(pattern, /Loading screens use skeletons/u);
+  assert.match(page, /ShellLayout/u);
+  assert.match(settings, /console-settings:primary-menu/u);
 });
 
-test("console-web wires console surface policy into app config", () => {
-  assert.equal(
-    findTextMutation("console-web-surface-access-policies-console-owner")?.file,
-    "config/surfaceAccessPolicies.js"
-  );
-  assert.equal(findTextMutation("console-web-surface-config-console")?.file, "config/public.js");
-  assert.match(findTextMutation("console-web-surface-config-console")?.value || "", /accessPolicyId: "console_owner"/);
-  assert.match(findTextMutation("console-web-surface-config-console")?.value || "", /icon: "mdi-console-network-outline"/);
-  assert.match(findTextMutation("console-web-surface-config-console")?.value || "", /showInSurfaceSwitchMenu: false/);
-  assert.equal(findTextMutation("console-web-profile-menu-console-placement")?.file, "src/placement.js");
-  assert.match(findTextMutation("console-web-profile-menu-console-placement")?.value || "", /label: "Go to console"/);
-  assert.match(
-    findTextMutation("console-web-profile-menu-console-placement")?.value || "",
-    /surfaceAccess\?\.consoleowner === true && surface !== "console"/
-  );
-  assert.equal(findTextMutation("console-web-console-settings-placement")?.file, "src/placement.js");
-  assert.equal(findTextMutation("console-web-settings-placement-topology")?.file, "src/placementTopology.js");
-  assert.deepEqual(readOutlets("console-settings:primary-menu"), [
-    {
-      target: "console-settings:primary-menu",
-      surfaces: ["console"],
-      source: "templates/src/pages/console/settings.vue"
-    }
-  ]);
-  assert.deepEqual(findTopology("page.section-nav", "console-settings"), {
-    id: "page.section-nav",
-    owner: "console-settings",
-    description: "Navigation between console settings child pages.",
-    surfaces: ["console"],
-    variants: {
-      compact: {
-        outlet: "console-settings:primary-menu",
-        renderers: {
-          link: "local.main.ui.surface-aware-menu-link-item"
-        }
-      },
-      medium: {
-        outlet: "console-settings:primary-menu",
-        renderers: {
-          link: "local.main.ui.surface-aware-menu-link-item"
-        }
-      },
-      expanded: {
-        outlet: "console-settings:primary-menu",
-        renderers: {
-          link: "local.main.ui.surface-aware-menu-link-item"
-        }
-      }
-    }
-  });
-  assert.deepEqual(findContribution("console.web.menu.settings"), {
-    id: "console.web.menu.settings",
-    target: "shell.primary-nav",
-    kind: "link",
+test("console-web metadata describes its semantic settings outlet", () => {
+  const outlets = packageJson.jskit.metadata.ui.placements.outlets;
+  assert.deepEqual(outlets, [{
+    target: "console-settings:primary-menu",
     surfaces: ["console"],
-    order: 100,
-    when: "auth.authenticated === true",
-    source: "mutations.text#console-web-console-settings-placement"
-  });
-});
-
-test("console-web console templates stay shell-driven", async () => {
-  const wrapperSource = await readFile(path.join(PACKAGE_DIR, "templates", "src", "pages", "console.vue"), "utf8");
-  const indexSource = await readFile(path.join(PACKAGE_DIR, "templates", "src", "pages", "console", "index.vue"), "utf8");
-  const settingsSource = await readFile(path.join(PACKAGE_DIR, "templates", "src", "pages", "console", "settings.vue"), "utf8");
-  const settingsIndexSource = await readFile(path.join(PACKAGE_DIR, "templates", "src", "pages", "console", "settings", "index.vue"), "utf8");
-
-  assert.match(wrapperSource, /ShellLayout/);
-  assert.match(wrapperSource, /"surface": "console"/);
-  assert.match(indexSource, /Operations Console/);
-  assert.match(indexSource, /console-home-screen__panel/);
-  assert.doesNotMatch(indexSource, /<v-card\b|v-card-title|v-card-subtitle/);
-  assert.match(settingsSource, /target="console-settings:primary-menu"/);
-  assert.doesNotMatch(settingsSource, /default-link-component-token/);
-  assert.doesNotMatch(settingsSource, /<v-card\b/);
-  assert.match(settingsSource, /<RouterView \/>/);
-  assert.match(settingsIndexSource, /No console settings yet/);
-  assert.doesNotMatch(settingsIndexSource, /your_child_segment|To redirect this settings shell/);
+    source: "patterns/console-surface/example/src/pages/console/settings.vue"
+  }]);
 });