andesine 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.6.0
+
+- Validate extension manifests with the 0.6.0 rules: `settingsSections` is no longer
+  accepted, and element views accept a `description` and an `icon`, whose CSS
+  `extensions build` generates with the other manifest icons.
+- Update the `extensions init` template: block action samples without UI (“Shout”), with a
+  `Menu` (“Count words”), and with a `Dialog` (“Wrap in Note”); a “More” menu and an “About”
+  dialog in the panel sample; a description and an icon for the Note view; and a local setup
+  guide in its README. The bookmarks panel and the About settings section samples, and the
+  declared request URL, are removed.
+- Simplify the buttons of the `pages init` template: one `variant` (`primary`, `secondary`, or
+  `ghost`) replaces `variant` and `color`, and buttons default to the small size.
+
 ## 0.5.0
 
 - Accept the `extensions` role permission (manage workspace extensions) in role commands.

package/dist/cli.js

@@ -51,7 +51,7 @@ var CancelledError = class extends CLIError {
 };
 //#endregion
 //#region package.json
-var version = "0.5.0";
+var version = "0.6.0";
 //#endregion
 //#region src/config/files.ts
 /** Read declarative JSON only. Missing optional files are distinct from invalid files. */
@@ -1896,10 +1896,7 @@ const isEmptyDirectory = async (directory) => {
 const toPackageName = (directory, fallback) => {
 	return path.basename(directory).toLowerCase().replace(/[^a-z\d._~-]+/g, "-").replace(/^[._-]+|[-]+$/g, "") || fallback;
 };
-/**
-* Copies a template that the build places next to the bundled CLI (see `scripts/templates.ts`)
-* into a new or empty directory, named after the directory.
-*/
+/** Copies a bundled template (see `scripts/templates.ts`) into a new or empty directory. */
 const copyTemplate = async (template, directory, output) => {
 	const source = fileURLToPath(new URL(`./templates/${template}/`, import.meta.url));
 	const target = path.resolve(directory);
@@ -9067,7 +9064,6 @@ const publicID = (prefix, options) => {
 };
 //#endregion
 //#region ../../private/contracts/src/primitives/unique.ts
-/** Whether every value is distinct. */
 const uniqueItems = (values) => new Set(values).size === values.length;
 //#endregion
 //#region ../../private/contracts/src/webhooks/catalog-definitions.ts
@@ -9499,7 +9495,7 @@ const fieldType = z.union([
 		])).optional()
 	})
 ]);
-/** Flat JSON Schema (draft 2020-12) subset that the host validates without running extension code. */
+/** Flat JSON Schema 2020-12 subset; the host validates it without running extension code. */
 const extensionConfigurationType = z.strictObject({
 	$schema: z.literal(JSON_SCHEMA_DIALECT).optional(),
 	type: z.literal("object"),
@@ -9800,27 +9796,22 @@ const contentNodeType = z.lazy(() => {
 const extensionContributionLimits = {
 	elementViews: 50,
 	blockActions: 20,
-	panelsPerSide: 2,
-	settingsSections: 5
+	panelsPerSide: 2
 };
 /** Stable across versions; settings and managed records are keyed by it. */
 const extensionStableIDType = z.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,63}$/, "Use a letter, then letters, digits, - or _");
 const extensionEntryType = z.string().regex(/^[A-Za-z_$][A-Za-z0-9_$]{0,63}$/, "Use the name of an exported view").describe("The export of the frontend bundle that renders this contribution");
-/**
-* An icon class of the UnoCSS icons preset, e.g. `i-lucide:rocket`, or `i-acme:logo?bg` for a
-* colored icon. Sets come from the extension build (default, installed, or custom); the build
-* checks that each icon exists.
-*/
+/** UnoCSS icon class, e.g. `i-lucide:rocket` (`?bg` for colored); the build checks it exists. */
 const extensionIconType = z.string().max(120).regex(/^i-[a-z\d]+(?:-[a-z\d]+)*:[a-z\d]+(?:-[a-z\d]+)*(?:\?(?:bg|mask))?$/, "Use an icon class, e.g. i-lucide:rocket");
 const labelType = z.string().min(1).max(60);
 const elementNameType = z.string().max(100).regex(ELEMENT_TAG_NAME, "Use an element name, e.g. Accordion");
-/**
-* A root element view. `descendants` render elements of those names inside the root's content
-* (nearest root first), before their own root registrations.
-*/
+/** `descendants` override their elements' own root views inside this root (nearest root first). */
 const extensionElementViewType = z.strictObject({
 	id: extensionStableIDType,
 	name: labelType,
+	/** Shown in the editor's slash menu and the extension's settings. */
+	description: z.string().min(1).max(200).optional(),
+	icon: extensionIconType.optional(),
 	element: elementNameType,
 	entry: extensionEntryType,
 	descendants: z.array(z.strictObject({
@@ -9854,11 +9845,6 @@ const extensionPanelType = z.discriminatedUnion("side", [z.strictObject({
 	]),
 	entry: extensionEntryType
 })]);
-const extensionSettingsSectionType = z.strictObject({
-	id: extensionStableIDType,
-	heading: labelType,
-	entry: extensionEntryType
-});
 const extensionContributionsType = {
 	elementViews: z.array(extensionElementViewType).max(extensionContributionLimits.elementViews).refine((views) => uniqueItems(views.map(({ element }) => element.toLowerCase())), "Use one view per element").default([]),
 	blockActions: z.array(extensionBlockActionType).max(extensionContributionLimits.blockActions).default([]),
@@ -9866,8 +9852,7 @@ const extensionContributionsType = {
 		return ["left", "right"].every((side) => {
 			return panels.filter((panel) => panel.side === side).length <= extensionContributionLimits.panelsPerSide;
 		});
-	}, `Use at most ${extensionContributionLimits.panelsPerSide} panels per side`).default([]),
-	settingsSections: z.array(extensionSettingsSectionType).max(extensionContributionLimits.settingsSections).default([])
+	}, `Use at most ${extensionContributionLimits.panelsPerSide} panels per side`).default([])
 };
 //#endregion
 //#region ../../private/contracts/src/api/schemas/webhooks.ts
@@ -10074,8 +10059,7 @@ const createManifestType = (protocols) => {
 		const contributionIDs = [
 			...manifest.elementViews,
 			...manifest.blockActions,
-			...manifest.panels,
-			...manifest.settingsSections
+			...manifest.panels
 		].map(({ id }) => id);
 		const isGranted = (required) => {
 			return manifest.permissions.some((permission) => hasPermission(permission, required));
@@ -10216,8 +10200,7 @@ const getEntries = (manifest) => {
 	const entries = [
 		...manifest.elementViews.flatMap((view) => [view.entry, ...view.descendants.map(({ entry }) => entry)]),
 		...manifest.blockActions.map(({ entry }) => entry),
-		...manifest.panels.map(({ entry }) => entry),
-		...manifest.settingsSections.map(({ entry }) => entry)
+		...manifest.panels.map(({ entry }) => entry)
 	];
 	return [...new Set(entries)];
 };
@@ -10325,10 +10308,7 @@ const importConfig = async (root) => {
 	});
 	return import(`${pathToFileURL(file).href}?t=${Date.now()}`);
 };
-/**
-* Loads and validates the manifest and build options of the extension in `root`. In
-* development, the manifest's backend uses the development keys and URL, and may use local HTTP.
-*/
+/** Loads and validates the project; in development, the backend uses dev keys and may use HTTP. */
 const loadExtensionProject = async (root, development) => {
 	if (!await exists(path.join(root, CONFIG_FILE))) throw new CLIError(`No ${CONFIG_FILE} in ${root}.`, exitCodes.usage);
 	const config = await importConfig(root);
@@ -10382,10 +10362,7 @@ const getViewScopePrelude = (name) => {
 const fail = (message) => {
 	throw new ExtensionStyleError(message);
 };
-/**
-* Removes comments outside strings. Escapes and strings are read like the browser reads them,
-* and a raw newline in a string fails, so the validated text cannot differ from what applies.
-*/
+/** Strips comments, parsing like the browser so the validated text matches what applies. */
 const stripComments = (css) => {
 	let result = "";
 	let quote = "";
@@ -10450,10 +10427,11 @@ const splitSelectors = (prelude) => {
 	selectors.push(prelude.slice(start).trim());
 	return selectors;
 };
-/** Every selector starts with `prefix` and a descendant combinator, never the prefix alone. */
+/** Each selector descends from `prefix` (no bare prefix); sibling combinators escape the scope. */
 const isScopedSelectorList = (selectors, prefix) => {
 	return splitSelectors(selectors).every((selector) => {
-		return selector.startsWith(`${prefix} `) && selector.trim().length > prefix.length;
+		const rest = selector.slice(prefix.length).trim();
+		return selector.startsWith(`${prefix} `) && rest.length > 0 && !/^[~+]/.test(rest);
 	});
 };
 /** Values load nothing (only inline SVG icon URLs) and contain no escapes or nested blocks. */
@@ -10489,10 +10467,8 @@ const validateBlock = (css, start, end, prefix, scopePrelude) => {
 	}
 };
 /**
-* View CSS is one `@scope (<view>) to (<content slot>)` rule, so it never reaches host-owned
-* content in slots; icon CSS rules start with the icon scope. Inside, only style rules
-* (optionally in `@media`/`@supports`) without escapes in values or URL-bearing values other
-* than inline SVG icons. The host also checks the browser-parsed rules before applying them.
+* View CSS is one `@scope (<view>) to (<content slot>)` rule; icon CSS starts with the icon scope.
+* Inside, only style rules (or `@media`/`@supports`) with safe values; the host re-checks them.
 */
 const validateExtensionCSS = (css, name, kind = "view") => {
 	if (css.length > 262144) fail("Extension CSS is too large");
@@ -10567,10 +10543,8 @@ const createExtensionGenerator = (icons) => {
 	});
 };
 /**
-* Generates the CSS of the extension views at build time: utility and icon classes found in the
-* code, in one `@scope` rule from the views down to their content slots, without preflights
-* (the host has them). Throws if the result is invalid, for example when an arbitrary value
-* loads a URL.
+* Generates view CSS in one `@scope` rule from the views down to their content slots, without
+* preflights (the host has them). Throws if invalid, e.g. when an arbitrary value loads a URL.
 */
 const generateExtensionCSS = async (options) => {
 	const { css: rules } = await (await createExtensionGenerator(options.icons)).generate(options.code, {
@@ -10620,7 +10594,8 @@ const getManifestIcons = (manifest) => {
 	const icons = [
 		manifest.icon,
 		...manifest.panels.map(({ icon }) => icon),
-		...manifest.blockActions.map(({ icon }) => icon)
+		...manifest.blockActions.map(({ icon }) => icon),
+		...manifest.elementViews.map(({ icon }) => icon)
 	];
 	return [...new Set(icons.filter((icon) => icon !== void 0))];
 };
@@ -10726,10 +10701,7 @@ const describeFailure = (status, body) => {
 	if (status === 404 && (body === null || message === "Not Found")) return "The instance has no development endpoints. Set PUBLIC_EXTENSIONS_ENABLED=true and EXTENSIONS_DEVELOPMENT_ENABLED=true on the local backend.";
 	return typeof message === "string" ? message : `The request failed (HTTP ${status}).`;
 };
-/**
-* A client for the development operations of a local instance. They are not in the public API,
-* so the SDK has no methods for them; they need the signed-in member of a CLI profile.
-*/
+/** Client for the local instance's development endpoints, which are outside the public API. */
 const createDevelopmentClient = (context) => {
 	const { baseURL, workspaceID } = context.config;
 	if (!isLocalInstance(baseURL)) throw new CLIError(`${baseURL} is not a local instance. Extension development needs a local stack (localhost, *.localhost, *.local, or *.test); use --base-url.`, exitCodes.usage);
@@ -10897,10 +10869,7 @@ const generateExtensionKey = async (root, options = {}) => {
 		ignored: await isIgnored$1(root, file)
 	};
 };
-/**
-* Checks that a private key matches a current key of the manifest and, with a registry URL, of
-* the registry entry, which Andesine instances trust.
-*/
+/** Checks that a private key matches a current manifest key and, optionally, a registry key. */
 const checkExtensionKey = async (root, options = {}) => {
 	const source = options.key ? await readFile(path.resolve(options.key), "utf8") : process.env[KEY_ENVIRONMENT_VARIABLE];
 	if (!source) throw new CLIError(`Set ${KEY_ENVIRONMENT_VARIABLE} or use --key <file>.`, exitCodes.usage);
@@ -10942,10 +10911,7 @@ const revokeExtensionKey = async (root, kid) => {
 //#region src/extensions/dev/environment.ts
 const KEY_ID = "development";
 const INSTANCES_VARIABLE = "ANDESINE_INSTANCES";
-/**
-* The project's development key pair, created once. The local instance gets only the public
-* key; the private key stays in the work directory and the backend's environment file.
-*/
+/** The project's development key pair, created once; the instance gets only the public key. */
 const getDevelopmentKey = async (root) => {
 	const directory = path.join(root, WORK_DIRECTORY, "keys");
 	const file = path.join(directory, `${KEY_ID}.json`);
@@ -10982,10 +10948,7 @@ const setVariable = (source, name, value) => {
 	if (pattern.test(source)) return source.replace(pattern, () => line);
 	return `${source}${source && !source.endsWith("\n") ? "\n" : ""}${line}\n`;
 };
-/**
-* Points the local backend at the development key and trusts the local instance, in its
-* environment file (created from `.env.example` when missing). Other variables stay.
-*/
+/** Sets the development key and trusted instance in the backend's environment file. */
 const writeDevelopmentEnvironment = async (root, file, key, baseURL) => {
 	const target = path.resolve(root, file);
 	const example = path.join(root, ".env.example");
@@ -11046,9 +11009,12 @@ const STOP_TIMEOUT = 1e4;
 const disabledHints = {
 	approval_required: "approve its new permissions or URLs in Settings → Extensions",
 	configuration_required: "fill in its required configuration in Settings → Extensions",
-	manual: "enable it in Settings → Extensions"
+	manual: "enable it in Settings → Extensions",
+	revoked: "its build is missing on the instance; save a file to upload it again"
+};
+const getErrorMessage = (error) => {
+	return error instanceof Error ? error.message : String(error);
 };
-const getErrorMessage = (error) => error instanceof Error ? error.message : String(error);
 /** Builds the project with the development key and uploads it, which installs or reloads it. */
 const uploadBuild = async (root, context, client, development) => {
 	const project = await loadExtensionProject(root, development);
@@ -11073,10 +11039,7 @@ const uploadBuild = async (root, context, client, development) => {
 	else await context.output.warning(`${name}@${version} is disabled: ${disabledHints[result.disabledReason ?? "manual"]}.`);
 	return result;
 };
-/**
-* Runs an extension on the local instance for the signed-in member: uploads each build, reloads
-* it on file changes, and stops it on exit, keeping its configuration and storage.
-*/
+/** Runs the extension on the local instance, reloading it on changes and stopping it on exit. */
 const runDevelopment = async (context, options) => {
 	const { output, signal } = context;
 	const root = path.resolve(options.root);
@@ -11218,7 +11181,9 @@ const readPublishedRegistry = async (directory) => {
 //#endregion
 //#region src/extensions/registry/check.ts
 const hash = (content) => createHash("sha256").update(content).digest("hex");
-const describeKey = (key) => JSON.stringify(key, Object.keys(key).sort());
+const describeKey = (key) => {
+	return JSON.stringify(key, Object.keys(key).sort());
+};
 const withoutKeys = (manifest) => {
 	return JSON.stringify({
 		...manifest,
@@ -11274,10 +11239,7 @@ const checkRevocations = (revocations, published, available) => {
 	}
 	return errors;
 };
-/**
-* Checks the registry repository against the published site with the same rules that Andesine
-* instances apply on ingestion, and builds each project (its dependencies must be installed).
-*/
+/** Builds each project and checks it against the published site, as instances do on ingestion. */
 const checkRegistry = async (repository, publishedDirectory, output) => {
 	const projects = await readRegistryProjects(repository);
 	const published = await readPublishedRegistry(publishedDirectory);
@@ -11351,10 +11313,7 @@ const writeVersion = async (published, siteURL, version, sourceCommit) => {
 	await writeFile(path.join(directory, VERSION_FILE), `${JSON.stringify(versionManifest, null, 2)}\n`);
 	return versionManifest;
 };
-/**
-* Checks the registry, writes the files of new versions, then the index, which instances read;
-* the index comes last, so it never names files that are not published yet.
-*/
+/** Writes new versions, then the index, so the index never names unpublished files. */
 const buildRegistry = async (options, output) => {
 	const siteURL = getSiteURL(options.siteURL);
 	const check = await checkRegistry(options.repository, options.published, output);
@@ -11423,6 +11382,7 @@ const initExtension = async (directory, options, output) => {
 };
 //#endregion
 //#region src/extensions/register.ts
+const ROOT_DESCRIPTION = "Extension directory (default: current directory)";
 const formatVersions = (manifests) => {
 	return manifests.map(({ name, version }) => `${name}@${version}`).join(", ");
 };
@@ -11431,7 +11391,6 @@ const reportRegistryErrors = async (output, errors) => {
 	for (const error of errors) await output.error(error);
 	throw new CLIError(`The registry has ${errors.length} problem(s).`);
 };
-const ROOT_DESCRIPTION = "Extension directory (default: current directory)";
 const registerExtensions = (program, signal) => {
 	const getOutput = (command) => {
 		return createOutput(command.optsWithGlobals().interactive, signal);