@crombolo/backoffice-host 0.60.0 → 0.62.0

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.
@@ -0,0 +1,128 @@
1
+ /**
2
+ * Where installed extensions live (story 326): each in a root of its own,
3
+ * `extensions/<id>/`, with its own `package.json`, `bun.lock` and
4
+ * `node_modules`, and the site's record of them in `crombolo.extensions.json`.
5
+ * Nothing of an extension is a dependency of the site, so trying one never
6
+ * changes the site's lockfile, and removing one is deleting its root. The
7
+ * root's two files and the record are committed; its `node_modules` is not.
8
+ * docs/bundles.md, "The record and the roots".
9
+ */
10
+ import { createHash } from 'node:crypto'
11
+ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
12
+ import { join } from 'node:path'
13
+
14
+ /** The folder every extension's root sits in, at the site's root. */
15
+ export const ROOTS_DIR = 'extensions'
16
+
17
+ /** The site's record of what it has installed. */
18
+ export const RECORD_FILE = 'crombolo.extensions.json'
19
+
20
+ /** One installed extension, as the record keeps it. */
21
+ export interface RecordedExtension {
22
+ /** Its npm package name. */
23
+ name: string
24
+ /** The exact version installed. */
25
+ version: string
26
+ /** The tarball's integrity, as the registry or the kept file gives it; absent for a link. */
27
+ integrity?: string
28
+ /** A hash of what it was granted, so an apply can tell a grant that no longer covers it. */
29
+ grant?: string
30
+ /** Installed from a path or a workspace on a developer's machine, outside production only. */
31
+ linked?: boolean
32
+ }
33
+
34
+ /** By extension id, sorted, as the file holds it. */
35
+ export type ExtensionRecord = Record<string, RecordedExtension>
36
+
37
+ export const rootOf = (siteDir: string, id: string): string => join(siteDir, ROOTS_DIR, id)
38
+
39
+ /** Where an extension's package sits in its root. */
40
+ export const packageInRoot = (siteDir: string, id: string, name: string): string =>
41
+ join(rootOf(siteDir, id), 'node_modules', name)
42
+
43
+ /** The site's record, or an empty one when there is none or it does not read. */
44
+ export function readRecord(siteDir: string): ExtensionRecord {
45
+ try {
46
+ const parsed = JSON.parse(readFileSync(join(siteDir, RECORD_FILE), 'utf8')) as unknown
47
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {}
48
+ const out: ExtensionRecord = {}
49
+ for (const [id, line] of Object.entries(parsed as Record<string, unknown>)) {
50
+ const entry = line as Partial<RecordedExtension> | null
51
+ if (entry && typeof entry.name === 'string' && typeof entry.version === 'string')
52
+ out[id] = {
53
+ name: entry.name,
54
+ version: entry.version,
55
+ ...(typeof entry.integrity === 'string' ? { integrity: entry.integrity } : {}),
56
+ ...(typeof entry.grant === 'string' ? { grant: entry.grant } : {}),
57
+ ...(entry.linked === true ? { linked: true } : {}),
58
+ }
59
+ }
60
+ return out
61
+ } catch {
62
+ return {}
63
+ }
64
+ }
65
+
66
+ /** Writes the record sorted by id, so a change to it is a change to one line. */
67
+ export function writeRecord(siteDir: string, record: ExtensionRecord): void {
68
+ const sorted = Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)))
69
+ writeFileSync(join(siteDir, RECORD_FILE), `${JSON.stringify(sorted, null, 2)}\n`)
70
+ }
71
+
72
+ /** Records one extension, replacing what was there for it. */
73
+ export function recordExtension(siteDir: string, id: string, line: RecordedExtension): void {
74
+ writeRecord(siteDir, { ...readRecord(siteDir), [id]: line })
75
+ }
76
+
77
+ /** Takes one extension out of the record. */
78
+ export function forgetExtension(siteDir: string, id: string): void {
79
+ const { [id]: _, ...rest } = readRecord(siteDir)
80
+ writeRecord(siteDir, rest)
81
+ }
82
+
83
+ /** A root ready for `bun add`: its folder and a `package.json` that is nobody's package. */
84
+ export function prepareRoot(siteDir: string, id: string): string {
85
+ const root = rootOf(siteDir, id)
86
+ mkdirSync(root, { recursive: true })
87
+ const manifest = join(root, 'package.json')
88
+ if (!existsSync(manifest))
89
+ writeFileSync(
90
+ manifest,
91
+ `${JSON.stringify({ name: `${id}-root`, private: true, dependencies: {} }, null, 2)}\n`,
92
+ )
93
+ return root
94
+ }
95
+
96
+ /** Why the record and the roots disagree: a root with no line, or a line with no root. Pure but for reading the folder. */
97
+ export function recordProblems(siteDir: string, record = readRecord(siteDir)): string[] {
98
+ const problems: string[] = []
99
+ const roots = existsSync(join(siteDir, ROOTS_DIR))
100
+ ? readdirSync(join(siteDir, ROOTS_DIR), { withFileTypes: true })
101
+ .filter((entry) => entry.isDirectory())
102
+ .map((entry) => entry.name)
103
+ : []
104
+ for (const id of roots)
105
+ if (!record[id])
106
+ problems.push(
107
+ `${ROOTS_DIR}/${id}/ is an extension's root that ${RECORD_FILE} does not name: install it again, or delete the folder`,
108
+ )
109
+ for (const [id, line] of Object.entries(record))
110
+ if (!existsSync(join(packageInRoot(siteDir, id, line.name), 'package.json')))
111
+ problems.push(
112
+ `${RECORD_FILE} names ${line.name}@${line.version} as "${id}", which is not installed in ${ROOTS_DIR}/${id}/: run \`bun install --frozen-lockfile\` there`,
113
+ )
114
+ return problems
115
+ }
116
+
117
+ /** A stable hash of what was granted: permissions and origins, in any order. Pure. */
118
+ export function grantHashOf(
119
+ permissions: readonly string[],
120
+ origins: readonly string[] = [],
121
+ ): string {
122
+ const text = JSON.stringify([[...permissions].sort(), [...origins].sort()])
123
+ return `sha256-${createHash('sha256').update(text).digest('hex').slice(0, 32)}`
124
+ }
125
+
126
+ /** What a dependency of the site that is an extension is told, since this release does not run it. */
127
+ export const INSTALLED_AS_DEPENDENCY =
128
+ 'it is installed as a dependency of the site, which this release no longer runs: remove it from package.json and install it again with `crombolo extension install`, so it has a root of its own'
package/src/extensions.ts CHANGED
@@ -19,6 +19,7 @@ import {
19
19
  readBundlePackage,
20
20
  } from './bundle-package.ts'
21
21
  import type { PackageManifest, PackageManifestImportmap } from './manifests.ts'
22
+ import { PLUGIN_PATH_PLACEHOLDER } from './paths.ts'
22
23
 
23
24
  /** Where an installed bundle's assets are served from. */
24
25
  export const EXTENSION_PATH = '/bundles'
@@ -97,6 +98,28 @@ function rewriteImportmap(
97
98
  return Object.keys(scopes).length > 0 ? { imports, scopes } : { imports }
98
99
  }
99
100
 
101
+ /** The back office's own element that draws every described screen (story 323). */
102
+ export const SCREEN_ELEMENT = `${PLUGIN_PATH_PLACEHOLDER}/extension-screen.js`
103
+
104
+ /**
105
+ * An entry that names a screen, as the back office loads it: the host's element,
106
+ * told which extension and screen to ask for. Any other entry is unchanged.
107
+ */
108
+ export function describedScreen(entry: unknown, bundleId: string): unknown {
109
+ if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return entry
110
+ const { screen, ...rest } = entry as Record<string, unknown>
111
+ if (typeof screen !== 'string') return entry
112
+ const meta = (rest.meta && typeof rest.meta === 'object' ? rest.meta : {}) as Record<
113
+ string,
114
+ unknown
115
+ >
116
+ return {
117
+ ...rest,
118
+ element: SCREEN_ELEMENT,
119
+ meta: { ...meta, cromboloScreen: { bundle: bundleId, screen } },
120
+ }
121
+ }
122
+
100
123
  /** A bundle's backoffice half, or undefined when it declares no extensions. */
101
124
  export function extensionOf(bundle: BundlePackage): InstalledExtension | undefined {
102
125
  const field = bundle.field
@@ -115,7 +138,7 @@ export function extensionOf(bundle: BundlePackage): InstalledExtension | undefin
115
138
  allowTelemetry: field.allowTelemetry ?? false,
116
139
  // Each extension names its bundle, so Settings can group a bundle's cards and link to it.
117
140
  extensions: (field.extensions ?? []).map((extension) => {
118
- const rewritten = rewriteAssets(extension, packageName)
141
+ const rewritten = rewriteAssets(describedScreen(extension, bundle.id), packageName)
119
142
  return rewritten && typeof rewritten === 'object'
120
143
  ? { ...rewritten, cromboloBundle: { name: bundle.name, packageName } }
121
144
  : rewritten
package/src/index.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  export * from './bundle-package.ts'
2
2
  export * from './bundle-permissions.ts'
3
3
  export * from './content-security.ts'
4
+ export * from './extension-roots.ts'
4
5
  export * from './extensions.ts'
5
6
  export * from './graphics.ts'
6
7
  export * from './login-assets.ts'
package/src/manifests.ts CHANGED
@@ -93,7 +93,18 @@ export function collectManifests(
93
93
  const all = [...discoverManifests(paths.vendorDir), ...frameworkManifests(paths)].filter(
94
94
  (manifest) => !omit.has(manifest.id ?? ''),
95
95
  )
96
- all.push(...extensions.map((extension) => extension.manifest))
96
+ // A described screen is drawn by the back office's own element, wherever it is mounted.
97
+ all.push(
98
+ ...extensions.map(
99
+ (extension) =>
100
+ JSON.parse(
101
+ JSON.stringify(extension.manifest).replaceAll(
102
+ `"${PLUGIN_PATH_PLACEHOLDER}/`,
103
+ `"${paths.pluginPath}/`,
104
+ ),
105
+ ) as PackageManifest,
106
+ ),
107
+ )
97
108
 
98
109
  const imports: Record<string, string> = {}
99
110
  const scopes: Record<string, Record<string, string>> = {}
package/src/registry.ts CHANGED
@@ -5,6 +5,7 @@
5
5
  */
6
6
  export * from './bundle-package.ts'
7
7
  export * from './bundle-permissions.ts'
8
+ export * from './extension-roots.ts'
8
9
  export * from './extensions.ts'
9
10
  export type * from './manifests.ts'
10
11
  export * from './paths.ts'
@@ -1,34 +0,0 @@
1
- /**
2
- * What the Extensions screens say when an extension asks to run code in the back
3
- * office (story 320): it acts as whoever is signed in, it can't be kept apart
4
- * like the rest of an extension, and it is installed only from a publisher you
5
- * trust, named here with what its signature shows. Pure, so it is tested
6
- * without a browser.
7
- */
8
-
9
- /** The permission an extension's back-office code needs. */
10
- export const BACKOFFICE_CODE = 'backoffice.code'
11
-
12
- /**
13
- * @param {{ allows: string, reason?: string | null, warning?: string }} ask the permission as the server describes it
14
- * @param {string | null | undefined} publisher who published it, when the registry says
15
- * @param {{ label: string, detail: string } | undefined} signature `signatureWords`' reading of its signature
16
- */
17
- export function backOfficeCodeWords(ask, publisher, signature) {
18
- return {
19
- label: ask.allows,
20
- reason: ask.reason ?? '',
21
- warning: ask.warning ?? '',
22
- publisher: publisher ? `Published by ${publisher}.` : "Who published this isn't known.",
23
- signature: signature ? `${signature.label}. ${signature.detail}` : '',
24
- confirm: `I trust ${publisher ?? 'its publisher'} to act as anyone signed in to this back office`,
25
- }
26
- }
27
-
28
- /** The back-office code a set of asks includes, and the rest, so it is shown first and apart. */
29
- export function splitBackOfficeCode(asks) {
30
- return {
31
- code: asks.find((ask) => ask.permission === BACKOFFICE_CODE),
32
- rest: asks.filter((ask) => ask.permission !== BACKOFFICE_CODE),
33
- }
34
- }
@@ -1,51 +0,0 @@
1
- /**
2
- * The warning an extension's back-office code is granted under (story 320), with
3
- * its own confirmation, shared by the Marketplace's install and Installed's grant.
4
- */
5
- import { css, html } from '@umbraco-cms/backoffice/external/lit'
6
-
7
- /**
8
- * @param {ReturnType<typeof import('./bundles-backoffice-code-words.js').backOfficeCodeWords>} words
9
- * @param {boolean} confirmed
10
- * @param {((confirmed: boolean) => void) | undefined} onConfirm absent once it is granted: there is nothing to confirm
11
- */
12
- export function backOfficeCodeBlock(words, confirmed, onConfirm) {
13
- return html`
14
- <div class="backoffice-code" role="alert">
15
- <p class="heading"><uui-icon name="icon-alert"></uui-icon><strong>${words.label}</strong></p>
16
- ${words.reason ? html`<p class="reason">${words.reason}</p>` : ''}
17
- <p>${words.warning}</p>
18
- <p>${words.publisher} ${words.signature}</p>
19
- ${
20
- onConfirm
21
- ? html`<uui-checkbox
22
- label=${words.confirm}
23
- .checked=${confirmed}
24
- @change=${(event) => onConfirm(event.target.checked)}></uui-checkbox>`
25
- : ''
26
- }
27
- </div>
28
- `
29
- }
30
-
31
- export const backOfficeCodeStyles = css`
32
- .backoffice-code {
33
- margin: var(--uui-size-space-3) 0;
34
- padding: var(--uui-size-space-4);
35
- border: 1px solid var(--uui-color-warning-standalone, var(--uui-color-warning));
36
- border-radius: var(--uui-border-radius);
37
- background: var(--uui-color-warning-surface, var(--uui-color-surface-alt));
38
- }
39
- .backoffice-code p {
40
- margin: 0 0 var(--uui-size-space-2);
41
- }
42
- .backoffice-code .heading {
43
- display: flex;
44
- align-items: center;
45
- gap: var(--uui-size-space-2);
46
- color: var(--uui-color-warning-standalone, var(--uui-color-warning-emphasis));
47
- }
48
- .backoffice-code .reason {
49
- color: var(--uui-color-text-alt);
50
- }
51
- `