@astryxdesign/cli 0.6.4 → 0.6.5-canary.00f1ed9

package/foundation/discovery/docs-section-key.mjs

@@ -95,7 +95,7 @@ function legacyTitleMatchIndex(sections, query) {
 
 /**
  * A name as a docs-tree route segment: lowercase words joined by hyphens, so
- * `integrationPackCheck` and `integration pack` both read naturally.
+ * `integrationPackCheck` and `integration verify` both read naturally.
  * @param {string} name
  * @returns {string}
  */

package/foundation/discovery/template-adapter.d.mts

@@ -49,6 +49,19 @@ export function effectiveTemplateDiscovery(templates: DiscoveredTemplate[]): Dis
  * @returns {string} Source with demo asset references replaced.
  */
 export function stripTemplateAssetRefs(source: string): string;
+/**
+ * {@link stripTemplateAssetRefs}, plus how many references it replaced: one per
+ * replaced reference, however many fixture paths its URL carries (a reference
+ * is replaced whole, query included), and none for a prose mention or a
+ * third-party URL left as written. That count is what a receipt discloses.
+ *
+ * @param {string} source - Template source code.
+ * @returns {{source: string, demoMediaReplaced: number}}
+ */
+export function replaceDemoMedia(source: string): {
+    source: string;
+    demoMediaReplaced: number;
+};
 /**
  * List the core page-template directory names (sorted). The `template --list`
  * view discovers far more; this is the minimal core-page set `init` scaffolds
@@ -173,6 +186,7 @@ export type DiscoveredTemplate = {
     name: string;
     displayName?: string | undefined;
     description: string;
+    keywords?: string[] | undefined;
     category?: string | undefined;
     isReady?: boolean | undefined;
     scaffold?: boolean | undefined;

package/foundation/discovery/template-adapter.fixture-refs.test.mjs

@@ -5,7 +5,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import jscodeshift from 'jscodeshift';
-import {stripTemplateAssetRefs} from './template-adapter.mjs';
+import {replaceDemoMedia, stripTemplateAssetRefs} from './template-adapter.mjs';
 
 const PLACEHOLDER = stripTemplateAssetRefs("'/template-assets/x.png'").slice(
   1,
@@ -212,6 +212,42 @@ describe('stripTemplateAssetRefs fixture references', () => {
   });
 });
 
+describe('replaceDemoMedia', () => {
+  it('counts a reference once, however many fixture paths its URL carries', () => {
+    const source =
+      "const hero = '/template-assets/a.png?f=/template-assets/b.png';";
+    expect(replaceDemoMedia(source)).toEqual({
+      source: stripTemplateAssetRefs(source),
+      demoMediaReplaced: 1,
+    });
+  });
+
+  it('counts a poster and a video as two references', () => {
+    const source =
+      '<video poster="/template-assets/poster.jpg" src="/template-assets/clip.mp4" />';
+    const result = replaceDemoMedia(source);
+    expect(result).toEqual({
+      source: stripTemplateAssetRefs(source),
+      demoMediaReplaced: 2,
+    });
+    expect(result.source).not.toContain('/template-assets/');
+  });
+
+  it.each([
+    [
+      'a prose mention',
+      '<p>Demo media lives under /template-assets/ in the docsite.</p>',
+    ],
+    [
+      'a third-party URL',
+      "const u = 'https://example.com/template-assets/a.png';",
+    ],
+    ['source with no fixture', 'const x = 1;'],
+  ])('counts nothing for %s it leaves as written', (_label, source) => {
+    expect(replaceDemoMedia(source)).toEqual({source, demoMediaReplaced: 0});
+  });
+});
+
 describe('shipped templates', () => {
   it('copy with every fixture replaced and still parse', () => {
     const root = path.resolve(

package/foundation/discovery/template-adapter.mjs

@@ -102,6 +102,7 @@ export function effectiveTemplateDiscovery(templates) {
  * @property {string} name
  * @property {string} [displayName]
  * @property {string} description
+ * @property {string[]} [keywords]
  * @property {string} [category]
  * @property {boolean} [isReady]
  * @property {boolean} [scaffold]
@@ -320,9 +321,23 @@ function toPosixPath(p) {
  * @returns {string} Source with demo asset references replaced.
  */
 export function stripTemplateAssetRefs(source) {
+  return replaceDemoMedia(source).source;
+}
+
+/**
+ * {@link stripTemplateAssetRefs}, plus how many references it replaced: one per
+ * replaced reference, however many fixture paths its URL carries (a reference
+ * is replaced whole, query included), and none for a prose mention or a
+ * third-party URL left as written. That count is what a receipt discloses.
+ *
+ * @param {string} source - Template source code.
+ * @returns {{source: string, demoMediaReplaced: number}}
+ */
+export function replaceDemoMedia(source) {
   const needle = `/${FIXTURE_SEGMENT}`;
   let output = '';
   let copied = 0;
+  let demoMediaReplaced = 0;
   /** @type {Array<[number, number]> | undefined} */
   let comments;
   let at = source.indexOf(needle);
@@ -343,10 +358,11 @@ export function stripTemplateAssetRefs(source) {
     if (edit) {
       output += source.slice(copied, start) + edit.text;
       copied = edit.end;
+      demoMediaReplaced += 1;
     }
     at = source.indexOf(needle, end);
   }
-  return output + source.slice(copied);
+  return {source: output + source.slice(copied), demoMediaReplaced};
 }
 
 /** @param {string | undefined} char */
@@ -633,6 +649,7 @@ async function discoverPages() {
       name: doc?.name || dir.name,
       description: doc?.description || '',
       category: doc?.category || '',
+      keywords: doc?.keywords ?? [],
       isReady: doc?.isReady ?? true,
       scaffold: doc?.scaffold ?? false,
       filePath: path.join(dirPath, 'page.tsx'),
@@ -661,6 +678,7 @@ async function discoverBlocks() {
       dirName: basename,
       name: doc?.name || basename,
       description: doc?.description || '',
+      keywords: doc?.keywords ?? [],
       isReady: doc?.isReady ?? true,
       aspectRatio: doc?.aspectRatio ?? 1,
       componentsUsed: doc?.componentsUsed ?? [],
@@ -702,6 +720,7 @@ async function discoverExternalBlocks(cwd = process.cwd()) {
         dirName: basename,
         name: doc?.name || basename,
         description: doc?.description || '',
+        keywords: doc?.keywords ?? [],
         isReady: doc?.isReady ?? true,
         aspectRatio: doc?.aspectRatio ?? 1,
         componentsUsed: doc?.componentsUsed ?? [],
@@ -1269,6 +1288,7 @@ export async function discoverIntegrationTemplatesForOne(integration) {
       name: doc?.name || id,
       displayName: doc?.displayName,
       description: doc?.description || '',
+      keywords: doc?.keywords ?? [],
       category: doc?.category || '',
       isReady: doc?.isReady ?? true,
       scaffold: doc?.scaffold ?? false,

package/foundation/doc-compiler/doc-loads.test.mjs

@@ -53,21 +53,21 @@ const RUNNERS = {
     sites: ['import(node:child_process)', 'worker_threads.Worker'],
   },
   'api/integration/pack-check.mjs': {
-    runs: '`npm pack`, `tar`, and a Node script that resolves the packed specifiers, to check a package as published',
-    sites: ['child_process.spawnSync ×3'],
+    runs: '`npm pack`, `tar`, and a Node script that resolves the packed specifiers, to check a package as published, and the package\'s doc modules, to see which need a newer CLI',
+    sites: ['child_process.spawnSync ×3', 'loadTopicModule'],
   },
   'api/swizzle/_github.mjs': {
     runs: '`gh auth status`, to check the GitHub CLI is signed in',
     sites: ['child_process.execFileSync'],
   },
   'api/theme/build/build.mjs': {
-    runs: 'theme source modules, through jiti; eval for legacy theme object literals',
+    runs: "theme source modules, through jiti; eval for legacy theme object literals; the project's installed Core",
     sites: [
       '.evalModule() ×2',
       '.import()',
       'createJiti ×4',
       'eval ×2',
-      'import(<computed>)',
+      'import(<computed>) ×3',
     ],
   },
   'api/theme/build/core-interception.mjs': {
@@ -188,6 +188,7 @@ const RUNNERS = {
       'import ../../../api/integration/integrationPackCheck.doc.mjs',
       'import ./integration-add.doc.mjs',
       'import ./integration-pack.doc.mjs',
+      'import ./integration-verify.doc.mjs',
       'import ./integration.doc.mjs',
     ],
   },

package/foundation/doc-compiler/inputs.test.mjs

@@ -90,7 +90,6 @@ describe('collectDocInputs over what this repo ships', () => {
     ).toEqual([
       'Chat',
       'ChatComposerTokenElement',
-      'Code',
       'ContextMenuItem',
       'Heading',
       'Indicator',

package/foundation/doc-compiler/tree.d.mts

@@ -240,6 +240,10 @@ export type TreeNode = {
     name: string;
     title: string;
     summary: string;
+    /**
+     * an authored namespace's search keywords
+     */
+    keywords?: string[] | undefined;
     /**
      * the parent's route; null at the top
      */

package/foundation/doc-compiler/tree.mjs

@@ -58,7 +58,7 @@ export const KIND_GROUPS = Object.freeze({
   schema: {
     segment: 'schemas',
     title: 'Schemas',
-    summary: 'Every shape the CLI reads or returns, field by field.',
+    summary: 'Data shapes, field by field.',
   },
   enum: {
     segment: 'enums',
@@ -140,6 +140,7 @@ export const UNORGANIZED = 'unorganized';
  * @property {string} name
  * @property {string} title
  * @property {string} summary
+ * @property {string[]} [keywords] an authored namespace's search keywords
  * @property {string | null} parent the parent's route; null at the top
  * @property {string | null} slot the parent slot this node sits in
  * @property {number | null} order
@@ -420,10 +421,14 @@ export function buildDocsTree({namespaces, docs, topics = []}) {
         name: input.doc.name,
         title: input.doc.title,
         summary: input.doc.summary,
+        ...(Array.isArray(input.doc.keywords)
+          ? {keywords: input.doc.keywords}
+          : {}),
         parent: parentRoute,
         slot: home?.slot ?? null,
         order: home?.order ?? null,
         generated: false,
+        ref: {selfDoc: input.doc},
         slots: Object.entries(input.doc.slots).map(([name, slot]) => ({
           name,
           title: slot.title,

package/foundation/doc-compiler/tree.test.mjs

@@ -13,6 +13,8 @@
  */
 
 import {describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import {
   buildDocsTree,
   KIND_GROUPS,
@@ -494,12 +496,38 @@ describe("the CLI's own docs tree", () => {
       const tree = await loadDocsTree({fresh: true});
       expect(tree.diagnostics).toEqual([]);
       expect(tree.roots().map(node => node.route)).toEqual(['cli']);
+      // Every slot child is a node one level below the namespace that places
+      // it, and every node but the root is placed. Read from the tree, so a
+      // restructure of the guides does not need this test edited.
+      const nodes = [...tree.nodes.values()];
+      const placed = new Set();
+      const misplaced = [];
+      for (const node of nodes) {
+        for (const slot of node.slots ?? []) {
+          for (const child of slot.children) {
+            placed.add(child);
+            const rest = child.slice(node.route.length + 1);
+            if (
+              tree.get(child) == null ||
+              !child.startsWith(`${node.route}/`) ||
+              rest.includes('/')
+            ) {
+              misplaced.push(`${node.route} › ${slot.name} › ${child}`);
+            }
+          }
+        }
+      }
+      expect(misplaced).toEqual([]);
       expect(
-        tree.get('cli')?.slots.map(slot => [slot.name, slot.children]),
-      ).toEqual([
-        ['guides', ['cli/integrations', 'cli/writing-docs']],
-        ['reference', ['cli/commands', 'cli/api']],
-      ]);
+        nodes
+          .map(node => node.route)
+          .filter(route => route !== 'cli' && !placed.has(route)),
+      ).toEqual([]);
+      // The reference groups the CLI generates from its own typed docs.
+      expect(
+        tree.get('cli')?.slots.find(slot => slot.name === 'reference')
+          ?.children,
+      ).toEqual(['cli/commands', 'cli/api']);
       expect(tree.get('cli/api')?.slots[0].children).toEqual([
         'cli/api/functions',
         'cli/api/schemas',
@@ -560,15 +588,38 @@ describe("the CLI's own docs tree", () => {
     async () => {
       const inputs = await loadTreeInputs({selfDocs: false});
       expect(inputs.diagnostics).toEqual([]);
-      expect(inputs.namespaces.map(n => n.doc.name).sort()).toEqual([
-        'api',
-        'cli',
-        'commands',
-      ]);
-      expect(inputs.docs.map(d => [d.name, d.placement?.parent])).toEqual([
-        ['integrations', 'namespace:cli'],
-        ['writing-docs', 'namespace:cli'],
-      ]);
+      // Every doc file in the tree directory is read, as a namespace or a
+      // guide, and named after its file.
+      const records = [
+        ...inputs.namespaces.map(n => ({name: n.doc.name, source: n.source})),
+        ...inputs.docs.map(d => ({name: d.name, source: d.source})),
+      ];
+      const files = fs
+        .readdirSync(new URL('../../assets/docs/tree/', import.meta.url))
+        .filter(file => file.endsWith('.doc.mjs'))
+        .sort();
+      expect(
+        records.map(record => path.basename(String(record.source))).sort(),
+      ).toEqual(files);
+      expect(
+        records.filter(
+          record =>
+            path.basename(String(record.source)) !== `${record.name}.doc.mjs`,
+        ),
+      ).toEqual([]);
+      expect(new Set(inputs.docs.map(d => d.kind))).toEqual(
+        new Set(['generic']),
+      );
+      // Every guide's parent is a namespace from the same directory.
+      const namespaces = new Set(
+        inputs.namespaces.map(n => `namespace:${n.doc.name}`),
+      );
+      expect(
+        inputs.docs
+          .filter(d => d.placement?.parent != null)
+          .filter(d => !namespaces.has(d.placement.parent))
+          .map(d => d.name),
+      ).toEqual([]);
     },
     SLOW,
   );

package/foundation/integrations/cli-requirement.d.mts

@@ -9,37 +9,101 @@
  * @returns {string | null}
  */
 export function lowestAdmitted(range: unknown): string | null;
+/**
+ * Why a package that uses a feature an older CLI cannot read would lose it,
+ * or null when its declared CLI range admits only CLIs that read it.
+ * @param {any} pkg package.json
+ * @param {string} feature what the package does, e.g. "ships a namespace doc"
+ * @param {string} loss what an older CLI does with it
+ * @param {string} floor the first stable CLI release that reads it
+ * @returns {string | null}
+ */
+export function cliRangeProblem(pkg: any, feature: string, loss: string, floor: string): string | null;
 /**
  * Why a package that ships a namespace doc or a placed guide would lose its
  * docs on an older CLI, or null when its declared CLI range admits only CLIs
  * that read the docs tree. Published 0.6.3 hides every topic of a package
  * with a namespace doc; builds of main before the docs tree also do so for a
- * placed guide.
+ * placed guide. Published 0.6.4 reads both.
  * @param {any} pkg package.json
  * @returns {string | null}
  */
 export function docsTreeCliProblem(pkg: any): string | null;
 /**
- * Why a package with a template that sets `replaces` would lose its templates
- * and doc topics on an older CLI (spec:AST-035), or null when its declared CLI
+ * Why a package with a template that sets `replaces` would lose templates and
+ * doc topics on an older CLI (spec:AST-035), or null when its declared CLI
  * range admits only CLIs that read the field.
  * @param {any} pkg package.json
  * @returns {string | null}
  */
 export function replacesCliProblem(pkg: any): string | null;
 /**
- * The package.json with a CLI peer that reads namespace docs: optional, unless
- * the package already says otherwise.
+ * Why a package with a doc section that sets `id` would lose its doc topics on
+ * an older CLI, or null when its declared CLI range admits only CLIs that read
+ * the field. Published 0.6.3 rejects a section `id` and hides every doc topic
+ * the package ships; published 0.6.4 reads it.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function sectionIdsCliProblem(pkg: any): string | null;
+/**
+ * Why a package that ships a theme would lose its themes and doc topics on an
+ * older CLI, or null when its declared CLI range admits only CLIs that read
+ * typed theme descriptors. Published 0.6.3 rejects a themes root with no
+ * `manifest.json` catalog, which `integration add theme` no longer writes;
+ * published 0.6.4 reads the descriptors.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function themesCliProblem(pkg: any): string | null;
+/**
+ * Why a package with a template that sets `keywords` would lose that template
+ * and its doc topics on an older CLI, or null when its declared CLI range
+ * admits only CLIs that read the field. Published 0.6.3 rejects the field,
+ * drops that template, and hides the package's doc topics.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function keywordsCliProblem(pkg: any): string | null;
+/**
+ * The package.json with a CLI peer of `>=floor`: optional, unless the package
+ * already says otherwise. Call it only when the package's range admits a CLI
+ * before `floor`, so a stricter range is never lowered.
+ * @param {any} pkg package.json
+ * @param {string} floor the first stable CLI release the package needs
+ * @returns {any}
+ */
+export function withCliPeer(pkg: any, floor: string): any;
+/**
+ * The package.json with a CLI peer that reads namespace docs.
  * @param {any} pkg package.json
  * @returns {any}
  */
 export function withDocsTreeCli(pkg: any): any;
 export const CLI_PACKAGE: "@astryxdesign/cli";
 /**
- * The first CLI release that reads an integration's docs tree (namespace docs
- * and placed guides) and its templates' `replaces`. A release before it can
- * hide every doc topic a package with a namespace doc or a placed guide
- * ships, with no warning, and it rejects `replaces` and withholds the
- * package's templates and doc topics.
+ * The first stable CLI release that reads an integration's docs tree:
+ * namespace docs and placed guides. Published 0.6.3 rejects a namespace doc
+ * and hides every doc topic the package ships, with no warning; published
+ * 0.6.4 lists the namespace and reads its guides.
+ */
+export const NAMESPACE_DOCS_CLI: "0.6.4";
+/**
+ * The first CLI release that reads a template's `replaces` and `keywords`. A
+ * release before it rejects either field, drops that template, and hides the
+ * package's doc topics.
+ */
+export const REPLACES_CLI: "0.7.0";
+/**
+ * The first stable CLI release that reads typed theme descriptors, the theme
+ * folder `integration add theme` writes. Published 0.6.3 rejects a themes root
+ * with no `manifest.json` catalog and withholds the package's themes and doc
+ * topics; published 0.6.4 lists the themes.
+ */
+export const THEMES_CLI: "0.6.4";
+/**
+ * The first stable CLI release that reads a doc section's `id`. Published
+ * 0.6.3 rejects the field and hides every doc topic the package ships;
+ * published 0.6.4 reads the section by its id.
  */
-export const DOCS_TREE_CLI: "0.7.0";
+export const SECTION_IDS_CLI: "0.6.4";