@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/authoring/doctypes/template/parse.d.mts

@@ -11,4 +11,97 @@
  * @returns {TemplateDoc}
  */
 export function parseTemplate(input: unknown, label?: string): TemplateDoc;
-export type TemplateDoc = import("../types").TemplateDoc;
+export type TemplateDoc = import("../types.js").TemplateDoc;
+export type PageTemplateDoc = import("./type.js").PageTemplateDoc;
+export type BlockTemplateDoc = import("./type.js").BlockTemplateDoc;
+/**
+ * Templates as they load. Integration templates already published omit
+ * `displayName` and `aspectRatio` and group themselves under their own
+ * `category`, so the loader accepts those (template discovery falls back to an
+ * aspect ratio of 1). The published types keep asking authors for all three.
+ */
+export type LoadedPageTemplateDoc = Omit<PageTemplateDoc, "displayName" | "category"> & {
+    displayName?: string;
+    category?: string;
+};
+/**
+ * Templates as they load. Integration templates already published omit
+ * `displayName` and `aspectRatio` and group themselves under their own
+ * `category`, so the loader accepts those (template discovery falls back to an
+ * aspect ratio of 1). The published types keep asking authors for all three.
+ */
+export type LoadedBlockTemplateDoc = Omit<BlockTemplateDoc, "displayName" | "aspectRatio" | "category"> & {
+    displayName?: string;
+    aspectRatio?: number;
+    category?: string;
+};
+export type _PageTemplateDocDriftLock = import("../../_shared/contract.js").Expect<import("../../_shared/contract.js").MutuallyAssignable<import("../../_shared/contract.js").NamedFields<z.infer<typeof pageTemplateSchema>>, import("../../_shared/contract.js").NamedFields<LoadedPageTemplateDoc>>>;
+export type _BlockTemplateDocDriftLock = import("../../_shared/contract.js").Expect<import("../../_shared/contract.js").MutuallyAssignable<import("../../_shared/contract.js").NamedFields<z.infer<typeof blockTemplateSchema>>, import("../../_shared/contract.js").NamedFields<LoadedBlockTemplateDoc>>>;
+import { z } from 'zod';
+declare const pageTemplateSchema: z.ZodObject<{
+    type: z.ZodLiteral<"page">;
+    name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    componentsUsed: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    preview: z.ZodOptional<z.ZodObject<{
+        image: z.ZodOptional<z.ZodString>;
+        aspectRatio: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    isReady: z.ZodOptional<z.ZodBoolean>;
+    scaffold: z.ZodOptional<z.ZodBoolean>;
+    isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
+    registry: z.ZodOptional<z.ZodObject<{
+        slug: z.ZodOptional<z.ZodString>;
+        aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    replaces: z.ZodOptional<z.ZodString>;
+    placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
+}, z.core.$strict>;
+declare const blockTemplateSchema: z.ZodObject<{
+    type: z.ZodLiteral<"block">;
+    exampleFor: z.ZodOptional<z.ZodString>;
+    alsoExampleFor: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    alsoShowcaseFor: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    aspectRatio: z.ZodOptional<z.ZodNumber>;
+    scale: z.ZodOptional<z.ZodNumber>;
+    isShowcase: z.ZodOptional<z.ZodBoolean>;
+    name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    componentsUsed: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    preview: z.ZodOptional<z.ZodObject<{
+        image: z.ZodOptional<z.ZodString>;
+        aspectRatio: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    isReady: z.ZodOptional<z.ZodBoolean>;
+    scaffold: z.ZodOptional<z.ZodBoolean>;
+    isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
+    registry: z.ZodOptional<z.ZodObject<{
+        slug: z.ZodOptional<z.ZodString>;
+        aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    replaces: z.ZodOptional<z.ZodString>;
+    placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
+}, z.core.$strict>;
+export {};

package/authoring/doctypes/template/parse.mjs

@@ -9,9 +9,12 @@
  */
 
 import {z} from 'zod';
+import {AuthoredDocGraphFields} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').TemplateDoc} TemplateDoc */
+/** @typedef {import('../types.js').TemplateDoc} TemplateDoc */
+/** @typedef {import('./type.js').PageTemplateDoc} PageTemplateDoc */
+/** @typedef {import('./type.js').BlockTemplateDoc} BlockTemplateDoc */
 
 const previewSchema = z
   .object({
@@ -37,9 +40,10 @@ const registryIdentitySchema = z
   .strict();
 
 const baseTemplateFields = {
+  ...AuthoredDocGraphFields,
   name: z.string().min(1, 'name is required'),
   displayName: z.string().min(1).optional(),
-  description: z.string().min(1, 'description is required'),
+  description: z.string().min(1, 'description is required').optional(),
   category: z.string().optional(),
   componentsUsed: z.array(z.string()).optional(),
   preview: previewSchema.optional(),
@@ -47,6 +51,10 @@ const baseTemplateFields = {
   scaffold: z.boolean().optional(),
   isHiddenFromOverview: z.boolean().optional(),
   registry: registryIdentitySchema.optional(),
+  replaces: z
+    .string()
+    .min(1, 'replaces must name a Core template id')
+    .optional(),
 };
 
 const pageTemplateSchema = z
@@ -65,6 +73,36 @@ const blockTemplateSchema = z
   })
   .strict();
 
+/**
+ * Templates as they load. Integration templates already published omit
+ * `displayName` and `aspectRatio` and group themselves under their own
+ * `category`, so the loader accepts those (template discovery falls back to an
+ * aspect ratio of 1). The published types keep asking authors for all three.
+ *
+ * @typedef {Omit<PageTemplateDoc, 'displayName' | 'category'>
+ *   & {displayName?: string, category?: string}} LoadedPageTemplateDoc
+ * @typedef {Omit<BlockTemplateDoc, 'displayName' | 'aspectRatio' | 'category'>
+ *   & {displayName?: string, aspectRatio?: number, category?: string}} LoadedBlockTemplateDoc
+ */
+
+/**
+ * @typedef {import('../../_shared/contract.js').Expect<
+ *   import('../../_shared/contract.js').MutuallyAssignable<
+ *     import('../../_shared/contract.js').NamedFields<z.infer<typeof pageTemplateSchema>>,
+ *     import('../../_shared/contract.js').NamedFields<LoadedPageTemplateDoc>
+ *   >
+ * >} _PageTemplateDocDriftLock
+ */
+
+/**
+ * @typedef {import('../../_shared/contract.js').Expect<
+ *   import('../../_shared/contract.js').MutuallyAssignable<
+ *     import('../../_shared/contract.js').NamedFields<z.infer<typeof blockTemplateSchema>>,
+ *     import('../../_shared/contract.js').NamedFields<LoadedBlockTemplateDoc>
+ *   >
+ * >} _BlockTemplateDocDriftLock
+ */
+
 const templateEnvelopeSchema = z
   .discriminatedUnion('type', [pageTemplateSchema, blockTemplateSchema])
   .superRefine((template, context) => {

package/authoring/doctypes/template/parse.test.mjs

@@ -22,6 +22,24 @@ function reason(value, label = 'template') {
 }
 
 describe('parseTemplate (load boundary)', () => {
+  it('accepts replaces on page and block templates', () => {
+    for (const type of ['page', 'block']) {
+      const parsed = parseTemplate({
+        type,
+        name: 'Acme shell',
+        description: 'Replaces a Core template.',
+        replaces: 'shell-side-nav',
+      });
+      expect(parsed.replaces).toBe('shell-side-nav');
+    }
+  });
+
+  it('rejects an empty replaces', () => {
+    expect(reason({type: 'page', name: 'Acme shell', replaces: ''})).toMatch(
+      /replaces must name a Core template id/,
+    );
+  });
+
   it('accepts a stamped page template', () => {
     const parsed = parseTemplate({
       type: 'page',
@@ -112,8 +130,14 @@ describe('parseTemplate (load boundary)', () => {
     expect(reason({type: 'page', description: 'x'})).toContain('name');
   });
 
-  it('rejects a missing description', () => {
-    expect(reason({type: 'page', name: 'x'})).toContain('description');
+  it('accepts an omitted description and rejects an empty one when present', () => {
+    expect(parseTemplate({type: 'page', name: 'x'})).toEqual({
+      type: 'page',
+      name: 'x',
+    });
+    expect(reason({type: 'page', name: 'x', description: ''})).toContain(
+      'description',
+    );
   });
 
   it('rejects an empty-string name', () => {

package/authoring/doctypes/template/template.doc.mjs

@@ -18,7 +18,7 @@ export const doc = {
     "(type: 'page') for full page templates and BlockTemplateDoc (type: 'block') for " +
     'editable compositions. A block can stand alone or use `exampleFor` to attach ' +
     'to one component; `isShowcase` requires that component ownership.',
-  appliesTo: '<Name>.template.mjs',
+  appliesTo: '<Name>.doc.mjs',
   fields: [
     {
       name: 'type',
@@ -52,6 +52,12 @@ export const doc = {
       type: 'string',
       description: 'One-sentence description of what the template provides.',
     },
+    {
+      name: 'replaces',
+      type: 'string',
+      description:
+        "Integration templates only: the exact id of the Core template this one replaces for unqualified lookup. Find it with `astryx --json template --list --package @astryxdesign/core`; the Core original stays selectable with `--package @astryxdesign/core`. A page replaces only a Core page and a block only a Core block. Needs @astryxdesign/cli 0.7.0 or later: earlier CLIs reject the field and withhold the package's templates and doc topics.",
+    },
     {
       name: 'isReady',
       type: 'boolean',
@@ -123,7 +129,7 @@ export const doc = {
     {
       label: 'Page template',
       code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
-export const doc = {
+export default {
   type: 'page',
   name: 'Dashboard',
   displayName: 'Dashboard',
@@ -135,7 +141,7 @@ export const doc = {
     {
       label: 'Block template (component example)',
       code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
-export const doc = {
+export default {
   type: 'block',
   name: 'ButtonGroupExample',
   displayName: 'Button Group Example',
@@ -148,6 +154,10 @@ export const doc = {
     },
   ],
   notes: [
+    {
+      type: 'prose',
+      text: 'When it loads, a template may leave out `displayName` and `aspectRatio` and use its own `category`, as integration templates already published do; a block with no `aspectRatio` previews at 1. Write to the type anyway; it is the contract.',
+    },
     {
       type: 'prose',
       text: "TemplateDoc is a discriminated union keyed by `type`. Set `type: 'page'` for a full page template. Set `type: 'block'` for an editable composition; add `exampleFor` only when one component owns the example.",

package/authoring/doctypes/template/type.ts

@@ -4,9 +4,12 @@
  * @file Template doc types.
  */
 
-import type {RegistryDocIdentity} from '../base/type';
+import type {
+  AuthoredDocGraphFields,
+  RegistryDocIdentity,
+} from '../base/type.js';
 
-export interface BaseTemplateDoc {
+export interface BaseTemplateDoc extends AuthoredDocGraphFields {
   /** Identifier name for the template. For block templates this matches
    *  the React component import name (e.g. `"ChatMessageMetadata"`); for
    *  page templates it's a human-readable label that doubles as the
@@ -25,6 +28,14 @@ export interface BaseTemplateDoc {
 
   /** Optional stable slug override and prior aliases for registry output. */
   registry?: RegistryDocIdentity;
+
+  /** Integration templates only: the exact id of the Core template this one
+   *  replaces for unqualified lookup (find it with
+   *  `astryx --json template --list --package @astryxdesign/core`). The Core
+   *  original stays selectable with `--package @astryxdesign/core`. Needs
+   *  `@astryxdesign/cli` 0.7.0 or later: earlier CLIs reject the field and
+   *  withhold the package's templates and doc topics. */
+  replaces?: string;
   /** Whether this template is ready for use. Templates with
    *  isReady: false show as "(WIP)" in the gallery and CLI. */
   isReady?: boolean;

package/authoring/doctypes/theme/parse.d.mts

@@ -0,0 +1,35 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Compile-time drift lock: the sealed schema must infer exactly ThemeDoc.
+ *
+ * @typedef {import('../../_shared/contract.js').Expect<
+ *   import('../../_shared/contract.js').Equal<
+ *     z.infer<typeof themeDocSchema>,
+ *     ThemeDoc
+ *   >
+ * >} _ThemeDocDriftLock
+ */
+/**
+ * Validate an unknown value as a theme descriptor, or throw.
+ *
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {ThemeDoc}
+ */
+export function parseTheme(input: unknown, label?: string): ThemeDoc;
+/**
+ * Compile-time drift lock: the sealed schema must infer exactly ThemeDoc.
+ */
+export type _ThemeDocDriftLock = import("../../_shared/contract.js").Expect<import("../../_shared/contract.js").Equal<z.infer<typeof themeDocSchema>, ThemeDoc>>;
+export type ThemeDoc = import("./type.js").ThemeDoc;
+import { z } from 'zod';
+declare const themeDocSchema: z.ZodObject<{
+    type: z.ZodLiteral<"theme">;
+    name: z.ZodString;
+    displayName: z.ZodString;
+    description: z.ZodString;
+    maintained: z.ZodBoolean;
+}, z.core.$strict>;
+export {};

package/authoring/doctypes/theme/parse.mjs

@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Theme doc parser (stamped `type: 'theme'`). Zod is sealed here;
+ * theme discovery calls `parseTheme` at the descriptor load boundary.
+ *
+ * @input an unknown loaded or statically extracted theme descriptor
+ * @output a validated ThemeDoc or a readable schema error
+ * @position packages/cli/authoring/doctypes/theme — descriptor load boundary
+ */
+
+import {z} from 'zod';
+import {formatZodError} from '../../_shared/errors.mjs';
+
+/** @typedef {import('./type.js').ThemeDoc} ThemeDoc */
+
+/** @param {string} field */
+const nonBlank = field =>
+  z.string().refine(value => value.trim() !== '', {
+    message: `${field} must not be blank`,
+    abort: true,
+  });
+
+const themeDocSchema = z
+  .object({
+    type: z.literal('theme'),
+    name: nonBlank('name').regex(
+      /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u,
+      'name must be lowercase kebab-case starting with a letter',
+    ),
+    displayName: nonBlank('displayName'),
+    // Blank is allowed, as the released catalog allowed it.
+    description: z.string(),
+    maintained: z.boolean(),
+  })
+  .strict();
+
+/** Zod skips `__proto__` when it looks for unknown keys. */
+const PROTO_KEY_ISSUE = {
+  code: /** @type {const} */ ('unrecognized_keys'),
+  keys: ['__proto__'],
+  path: [],
+  message: 'Unrecognized key: "__proto__"',
+};
+
+/**
+ * Compile-time drift lock: the sealed schema must infer exactly ThemeDoc.
+ *
+ * @typedef {import('../../_shared/contract.js').Expect<
+ *   import('../../_shared/contract.js').Equal<
+ *     z.infer<typeof themeDocSchema>,
+ *     ThemeDoc
+ *   >
+ * >} _ThemeDocDriftLock
+ */
+
+/**
+ * Validate an unknown value as a theme descriptor, or throw.
+ *
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {ThemeDoc}
+ */
+export function parseTheme(input, label = 'theme') {
+  const result = themeDocSchema.safeParse(input);
+  const protoKey =
+    input !== null &&
+    typeof input === 'object' &&
+    Object.hasOwn(input, '__proto__');
+  if (result.success && !protoKey) return result.data;
+  const issues = [
+    ...(result.error?.issues ?? []),
+    ...(protoKey ? [PROTO_KEY_ISSUE] : []),
+  ];
+  throw new Error(formatZodError(label, new z.ZodError(issues)));
+}

package/authoring/doctypes/theme/theme.doc.d.mts

@@ -0,0 +1,9 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file SchemaDoc for the ThemeDoc authoring type.
+ * @position packages/cli/authoring/doctypes/theme — doc-type documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;

package/authoring/doctypes/theme/theme.doc.mjs

@@ -0,0 +1,79 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SchemaDoc for the ThemeDoc authoring type.
+ * @position packages/cli/authoring/doctypes/theme — doc-type documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc = {
+  type: 'schema',
+  name: 'theme-doc',
+  displayName: 'ThemeDoc',
+  namespace: 'authoring',
+  description:
+    'The strongly typed descriptor for one integration or CLI-bundled source theme.',
+  appliesTo: '<theme-source-stem>.doc.mjs',
+  fields: [
+    {
+      name: 'type',
+      type: "'theme'",
+      description: 'Doc-kind discriminant.',
+      required: true,
+    },
+    {
+      name: 'name',
+      type: 'string',
+      description:
+        'Lower-kebab CLI theme identity. Must match the descriptor parent directory.',
+      required: true,
+      example: "'ocean'",
+    },
+    {
+      name: 'displayName',
+      type: 'string',
+      description: 'Human-readable name shown by theme listings.',
+      required: true,
+      example: "'Ocean'",
+    },
+    {
+      name: 'description',
+      type: 'string',
+      description: 'One-line summary shown by theme listings.',
+      required: true,
+    },
+    {
+      name: 'maintained',
+      type: 'boolean',
+      description: 'Whether the owning package actively maintains this theme.',
+      required: true,
+    },
+  ],
+  examples: [
+    {
+      label: 'A theme descriptor beside oceanTheme.ts',
+      code: `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {
+  type: 'theme',
+  name: 'ocean',
+  displayName: 'Ocean',
+  description: 'Cool blue surfaces with crisp contrast.',
+  maintained: true,
+};`,
+    },
+  ],
+  notes: [
+    {
+      type: 'prose',
+      text: 'ThemeDoc is static metadata. Default-export one object with literal string and boolean fields; discovery validates it without executing the descriptor or theme source.',
+    },
+    {
+      type: 'prose',
+      text: 'The descriptor and source share one stem. For oceanTheme.doc.mjs, discovery requires exactly one oceanTheme source module and a named oceanTheme runtime export.',
+    },
+    {
+      type: 'prose',
+      text: 'The parent theme directory, including this descriptor, is the complete copy and pack boundary. Nested source, palettes, assets, and receipts need no second file list.',
+    },
+  ],
+};

package/authoring/doctypes/theme/type.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Theme contribution descriptor type.
+ *
+ * A theme descriptor is a strongly typed `.doc.mjs` beside its same-stem theme
+ * source. The shared stem identifies the source entry and required named runtime
+ * export. The lower-kebab parent directory and `name` identify the CLI theme.
+ *
+ * @input metadata authored beside one source theme
+ * @output the public ThemeDoc contract
+ * @position packages/cli/authoring/doctypes/theme — theme descriptor vocabulary
+ */
+
+/**
+ * The descriptor for one source theme contributed by an integration or bundled
+ * with the CLI.
+ *
+ * @example
+ * ```
+ * /** @type {import('@astryxdesign/cli/authoring').ThemeDoc} *\/
+ * export default {
+ *   type: 'theme',
+ *   name: 'ocean',
+ *   displayName: 'Ocean',
+ *   description: 'Cool blue surfaces with crisp contrast.',
+ *   maintained: true,
+ * };
+ * ```
+ */
+export interface ThemeDoc {
+  /** Doc-kind discriminant. */
+  type: 'theme';
+  /** Stable CLI identity. Must be lower-kebab and match the parent directory. */
+  name: string;
+  /** Human-readable name shown by theme listings. */
+  displayName: string;
+  /** One-line summary shown by theme listings. */
+  description: string;
+  /** Whether the owning package actively maintains this theme. */
+  maintained: boolean;
+}

package/authoring/doctypes/types.ts

@@ -3,16 +3,18 @@
 /**
  * @file Doc-type vocabulary barrel. Each kind's types live in one `type.ts`
  * under its folder (`base/` shared leaves, then `component/`, `hook/`,
- * `reference/`, `template/`); this re-exports them as the full doc vocabulary
+ * `reference/`, `template/`, `theme/`); this re-exports them as the full doc vocabulary
  * behind `@astryxdesign/cli/authoring`.
  */
 
-export type * from './base/type';
-export type * from './component/type';
-export type * from './hook/type';
-export type * from './function/type';
-export type * from './reference/type';
-export type * from './template/type';
-export type * from './schema/type';
-export type * from './command/type';
-export type * from './enum/type';
+export type * from './base/type.js';
+export type * from './component/type.js';
+export type * from './hook/type.js';
+export type * from './function/type.js';
+export type * from './reference/type.js';
+export type * from './namespace/type.js';
+export type * from './template/type.js';
+export type * from './schema/type.js';
+export type * from './command/type.js';
+export type * from './enum/type.js';
+export type * from './theme/type.js';

package/authoring/gap-report/gap-report.doc.d.mts

@@ -0,0 +1,12 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file SchemaDoc for GapReportHandler, the handler `astryx gap-report` calls.
+ * @input The GapReportHandler type beside it (`type.ts`), which `parse.mjs`
+ *   validates.
+ * @output The `gap-report-handler` section of `astryx docs authoring`.
+ * @position packages/cli/authoring/gap-report — schema documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;