An open source design system that's fully customizable and agent ready
TypeScript
feat(core): host authoring factories in core (config + authoring subpaths) (#4058)
EJ Hammond896bdb1399fd
diff --git a/.changeset/authoring-factories-in-core.md b/.changeset/authoring-factories-in-core.mdnew file mode 100644index 0000000000..3b539af61a--- /dev/null+++ b/.changeset/authoring-factories-in-core.md@@ -0,0 +1,8 @@+---+'@astryxdesign/core': patch+'@astryxdesign/cli': patch+---++[feat] Export the authoring factories from `@astryxdesign/core`: `createConfig` at `@astryxdesign/core/config` and `createIntegration`/`createPageTemplate`/`createBlockTemplate`/`createComponentDoc`/`createFunctionDoc`/`createDoc` at `@astryxdesign/core/authoring`. Authoring a config or integration no longer requires depending on the CLI. Existing `@astryxdesign/cli/*` imports keep working via re-export.++@ejhammonddiff --git a/packages/cli/src/api/template.mjs b/packages/cli/src/api/template.mjsindex c85cc6734e..558de67caf 100644--- a/packages/cli/src/api/template.mjs+++ b/packages/cli/src/api/template.mjs@@ -8,7 +8,7 @@ import * as fs from 'node:fs';import * as path from 'node:path';import {createJiti} from 'jiti';import {loadModuleWithSchema} from '../lib/module-loader.mjs';-import {TemplateEnvelopeSchema} from '../template.mjs';+import {TemplateEnvelopeSchema} from '../schemas/template-schema.mjs';import {CLI_ROOT, discoverExternalPackages} from '../utils/paths.mjs';import {assertWithin,diff --git a/packages/cli/src/config.mjs b/packages/cli/src/config.mjsindex 4e7074d5a3..dfbe01a502 100644--- a/packages/cli/src/config.mjs+++ b/packages/cli/src/config.mjs@@ -1,18 +1,9 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * Type-preserving helper for the Astryx config file.- *- * This is an intentionally tiny runtime identity function: it returns its- * argument unchanged. Its value is the exported TypeScript surface from- * `@astryxdesign/cli/config`, so config files get editor/type feedback without- * coupling to CLI internals. Validation is NOT performed here — it happens at- * the load boundary (see `loadModuleWithSchema` + `AstryxConfigSchema`).- *- * @template {import('./types/config').AstryxConfig} T- * @param {T} config- * @returns {T}+ * Re-export of the config-authoring helper, which now lives in+ * `@astryxdesign/core/config` so an app's config file gets type feedback+ * without depending on the CLI. Kept here so existing+ * `@astryxdesign/cli/config` imports continue to work unchanged.*/-export function createConfig(config) {- return config;-}+export {createConfig} from '@astryxdesign/core/config';diff --git a/packages/cli/src/doc.mjs b/packages/cli/src/doc.mjsindex 0207917a12..134f0ed828 100644--- a/packages/cli/src/doc.mjs+++ b/packages/cli/src/doc.mjs@@ -1,271 +1,27 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * @file Public doc-authoring API.+ * @file Doc-authoring API (public `@astryxdesign/cli/doc`).*- * A doc describes a documentable unit of the design system so the CLI and docs- * surfaces can list, search, and render it. There are three kinds, each a tiny- * runtime identity helper that stamps a `type` discriminant (mirroring how- * `createPageTemplate`/`createBlockTemplate` stamp `type`):- *- * - `createComponentDoc` -> `type: 'component'` — a component (or a family).- * - `createFunctionDoc` -> `type: 'function'` — any function, including- * hooks: an "inputs + outputs" surface (`params` + `returns`).- * - `createDoc` -> `type: 'generic'` — reference/topic docs.- *- * Like `createConfig`/`createIntegration`/`createBlockTemplate`, these factories- * do NOT validate. Validation happens at the LOAD boundary, where doc discovery- * runs the loaded value through {@link ComponentDocSchema}. That schema handles- * BOTH the new stamped formats and the legacy loose `export const docs = {...}`- * shape, so existing docs keep loading unchanged (a later PR migrates them).- */--import {z} from 'zod';--/**- * A single documented prop. Mirrors `PropDoc` from- * `@astryxdesign/core/docs-types`. Only `name`, `type`, and `description` are- * required; everything else is optional. Extra fields (e.g. `slotElements`)- * pass through so the schema does not have to track every evolution of the- * rich playground/element surface.- */-const PropSchema = z- .object({- name: z.string().min(1, 'prop name is required'),- type: z.string().min(1, 'prop type is required'),- description: z.string(),- default: z.string().optional(),- required: z.boolean().optional(),- })- .passthrough();--/** A single documented function/hook parameter (mirrors `HookParamDoc`). */-const ParamSchema = z- .object({- name: z.string().min(1, 'param name is required'),- type: z.string().min(1, 'param type is required'),- description: z.string(),- default: z.string().optional(),- required: z.boolean().optional(),- })- .passthrough();--/** A single documented function/hook return field (mirrors `HookReturnDoc`). */-const ReturnSchema = z- .object({- name: z.string().min(1, 'return name is required'),- type: z.string().min(1, 'return type is required'),- description: z.string(),- })- .passthrough();--/**- * Fields shared by every doc kind. Deliberately permissive on the rich blobs- * (usage/theming/playground) — those are large and still evolving, so they are- * `z.unknown()` passthrough rather than enumerated.- *- * `group` vs `parent` are distinct concepts and intentionally separate fields:- * - `group` is a FLAT sidebar bucket label. Many docs can share a group; it- * is not an inheritance key.- * - `parent` is a DIRECTED inheritance/composition pointer — a doc naming the- * doc it belongs to (e.g. a sub-component naming its parent component). The- * legacy `subComponentOf` field is a synonym; both map to the same concept.- *- * `relatedDocs` is a single flat curated cross-reference list. It replaces the- * legacy split `relatedComponents` + `relatedHooks`; a downstream reader can- * merge the legacy pair into it.- */-const BaseDocFields = {- /** Name of the documented unit, without any prefix. Required. */- name: z.string().min(1, 'name is required'),- /** Human-readable display name for gallery/sidebar. */- displayName: z.string().optional(),- /** One-line/short description. */- description: z.string().optional(),- /** Usage documentation (description, best practices, anatomy, slotElements). */- usage: z.unknown().optional(),- /** Flat sidebar grouping label (not an inheritance key). */- group: z.string().optional(),- /** Overview-page functional category. */- category: z.string().optional(),- /** CLI fuzzy-search keywords. */- keywords: z.array(z.string()).optional(),- /** Directed inheritance/composition pointer to the doc this belongs to. */- parent: z.string().optional(),- /** Flat curated cross-reference list of related doc names. */- relatedDocs: z.array(z.string()).optional(),- /** Hide the whole doc from human-facing UI (stays importable/discoverable). */- hidden: z.boolean().optional(),- /** Exclude from the categorized overview page (kept in sidebar/CLI). */- isHiddenFromOverview: z.boolean().optional(),-};--/**- * New-format schema for a stamped component doc (`type: 'component'`). The- * top-level component keys are enumerated, but nested blobs stay loose so real- * docs are not rejected. `.passthrough()` keeps unknown top-level fields- * (translations, element descriptors, ...) flowing through.- */-export const ComponentDocKindSchema = z- .object({- ...BaseDocFields,- type: z.literal('component'),- props: z.array(PropSchema),- theming: z.unknown().optional(),- playground: z.unknown().optional(),- examples: z.array(z.unknown()).optional(),- })- .passthrough();--/**- * New-format schema for a stamped function doc (`type: 'function'`). Covers any- * function, including hooks: an inputs (`params`) + outputs (`returns`) surface.+ * The `createComponentDoc`/`createFunctionDoc`/`createDoc` authoring helpers now+ * live in `@astryxdesign/core/authoring` and are re-exported here so existing+ * `@astryxdesign/cli/doc` imports keep working. The Zod load-boundary schemas+ * live in `./schemas/doc-schema.mjs` (core-free) and are re-exported here for+ * back-compat; internal hot-path code imports them from the schema module+ * directly so it never depends on core's built `dist/`.*/-export const FunctionDocKindSchema = z- .object({- ...BaseDocFields,- type: z.literal('function'),- params: z.array(ParamSchema),- returns: z.array(ReturnSchema),- })- .passthrough();-/**- * New-format schema for a stamped generic doc (`type: 'generic'`) — reference- * and topic docs. Just the shared base plus the discriminant.- */-export const GenericDocKindSchema = z- .object({- ...BaseDocFields,- type: z.literal('generic'),- })- .passthrough();+export {+ createComponentDoc,+ createFunctionDoc,+ createDoc,+} from '@astryxdesign/core/authoring';-/**- * The stamped-doc contract: one of the three new per-kind schemas, discriminated- * by the injected `type`. Used when a loaded doc carries a `type` field.- */-export const StampedDocSchema = z.discriminatedUnion('type', [+export {ComponentDocKindSchema,FunctionDocKindSchema,GenericDocKindSchema,-]);--// ── Legacy loose format (unchanged, kept for back-compat) ─────────────-//-// The pre-factory docs are authored as a loose, untyped object with no `type`-// discriminant and validated by shape. Enumerated top-level fields observed-// across the existing loose docs:-// name, displayName, description, group, category, keywords,-// isHiddenFromOverview, hidden, hiddenComponents, usage, props, components,-// subComponentOf, playground, theming, examples, params, returns,-// relatedComponents, relatedHooks, relatedDocs, parent, importPath.--const LegacyBaseDocSchema = z.object({- name: z.string().min(1, 'name is required'),- displayName: z.string().optional(),- description: z.string().optional(),- group: z.string().optional(),- category: z.string().optional(),- keywords: z.array(z.string()).optional(),- isHiddenFromOverview: z.boolean().optional(),- hidden: z.boolean().optional(),- hiddenComponents: z.array(z.string()).optional(),- usage: z.unknown().optional(),- playground: z.unknown().optional(),- theming: z.unknown().optional(),- examples: z.array(z.unknown()).optional(),- showcase: z.unknown().optional(),- // `parent` and legacy `subComponentOf` are synonyms; both accepted here so a- // parent-based doc that omits a stamped `type` still validates.- parent: z.string().optional(),- relatedDocs: z.array(z.string()).optional(),- relatedComponents: z.array(z.string()).optional(),- relatedHooks: z.array(z.string()).optional(),-});--/** Legacy: directory exporting a single primary component (props inline). */-const LegacySingleComponentDocSchema = LegacyBaseDocSchema.extend({- props: z.array(PropSchema),-}).passthrough();--/** Legacy: directory exporting multiple components (props on each entry). */-const LegacyMultiComponentDocSchema = LegacyBaseDocSchema.extend({- components: z.array(z.unknown()),-}).passthrough();--/** Legacy: a standalone hook doc — inputs (`params`) + outputs (`returns`). */-const LegacyHookDocSchema = LegacyBaseDocSchema.extend({- params: z.array(ParamSchema),- returns: z.array(ReturnSchema),-}).passthrough();--/** Legacy: a sub-component doc parented via `subComponentOf`. */-const LegacySubComponentDocSchema = LegacyBaseDocSchema.extend({- subComponentOf: z.string().min(1, 'subComponentOf is required'),- description: z.string(),- props: z.array(PropSchema),-}).passthrough();--/**- * The permissive legacy union. `subComponentOf` is listed first so a doc that- * carries both `subComponentOf` and `props` is validated as a sub-component- * (the more specific shape); hook (`params`/`returns`) before multi/single.- */-export const LegacyDocSchema = z.union([- LegacySubComponentDocSchema,- LegacyHookDocSchema,- LegacyMultiComponentDocSchema,- LegacySingleComponentDocSchema,-]);--/**- * The LOAD-boundary contract for a doc. Handles BOTH formats:- * - NEW: a stamped doc (`type: 'component' | 'function' | 'generic'`,- * produced by the factories below) is validated against the matching- * per-kind schema in {@link StampedDocSchema}.- * - OLD: a loose, unstamped doc is validated against the permissive- * {@link LegacyDocSchema} union (the three legacy shapes + standalone hook).- *- * Discovery validates the SHAPE, not "was it made by the factory". This PR does- * NOT migrate real docs; a later PR does. Both formats normalize into the same- * internal shape consumers already expect.- */-export const ComponentDocSchema = z.union([StampedDocSchema, LegacyDocSchema]);--/**- * Author a component doc. Stamp-only: returns the def with `type: 'component'`- * injected. Validation happens at the load boundary.- *- * @template {import('./types/doc').AstryxComponentDocInput} T- * @param {T} def- * @returns {T & {type: 'component'}}- */-export function createComponentDoc(def) {- return /** @type {T & {type: 'component'}} */ ({...def, type: 'component'});-}--/**- * Author a function doc (covers any function, including hooks). Stamp-only:- * returns the def with `type: 'function'` injected. Validation happens at the- * load boundary.- *- * @template {import('./types/doc').AstryxFunctionDocInput} T- * @param {T} def- * @returns {T & {type: 'function'}}- */-export function createFunctionDoc(def) {- return /** @type {T & {type: 'function'}} */ ({...def, type: 'function'});-}--/**- * Author a generic reference/topic doc. Stamp-only: returns the def with- * `type: 'generic'` injected. Validation happens at the load boundary.- *- * @template {import('./types/doc').AstryxGenericDocInput} T- * @param {T} def- * @returns {T & {type: 'generic'}}- */-export function createDoc(def) {- return /** @type {T & {type: 'generic'}} */ ({...def, type: 'generic'});-}+ StampedDocSchema,+ LegacyDocSchema,+ ComponentDocSchema,+} from './schemas/doc-schema.mjs';diff --git a/packages/cli/src/integration.mjs b/packages/cli/src/integration.mjsindex a5761c6c99..a96ac2b009 100644--- a/packages/cli/src/integration.mjs+++ b/packages/cli/src/integration.mjs@@ -1,19 +1,8 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * Type-preserving helper for an Astryx integration manifest.- *- * This is an intentionally tiny runtime identity function: it returns its- * argument unchanged. Its value is the exported TypeScript surface from- * `@astryxdesign/cli/integration`, so manifests get editor/type feedback- * without coupling to CLI internals. Validation is NOT performed here — it- * happens at the load boundary (see `loadModuleWithSchema` +- * `AstryxIntegrationSchema`).- *- * @template {import('./types/integration').AstryxIntegration} T- * @param {T} integration- * @returns {T}+ * Re-export of the integration-authoring helper, which now lives in+ * `@astryxdesign/core/authoring`. Kept here so existing+ * `@astryxdesign/cli/integration` imports continue to work unchanged.*/-export function createIntegration(integration) {- return integration;-}+export {createIntegration} from '@astryxdesign/core/authoring';diff --git a/packages/cli/src/lib/component-loader.mjs b/packages/cli/src/lib/component-loader.mjsindex 032a1d3f23..38b42eed8b 100644--- a/packages/cli/src/lib/component-loader.mjs+++ b/packages/cli/src/lib/component-loader.mjs@@ -7,7 +7,7 @@import {pathToFileURL} from 'node:url';import {importUserModule} from './module-loader.mjs';import {formatZodError} from './config-schema.mjs';-import {ComponentDocSchema} from '../doc.mjs';+import {ComponentDocSchema} from '../schemas/doc-schema.mjs';/*** Load a component doc through the shared load/validation boundary.diff --git a/packages/cli/src/schemas/doc-schema.mjs b/packages/cli/src/schemas/doc-schema.mjsnew file mode 100644index 0000000000..09dcc6bebd--- /dev/null+++ b/packages/cli/src/schemas/doc-schema.mjs@@ -0,0 +1,226 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Doc load-boundary schemas.+ *+ * The Zod schemas doc discovery runs a loaded doc value through (see+ * `loadComponentDoc`). {@link ComponentDocSchema} accepts BOTH the new stamped+ * formats and the legacy loose `export const docs = {...}` shape, so existing+ * docs keep loading unchanged. Kept free of any `@astryxdesign/core` import so+ * the hot path that loads them (doc discovery, `astryx init`) does not require+ * core's built `dist/`. The authoring factories live in+ * `@astryxdesign/core/authoring` and are re-exported from `../doc.mjs` for the+ * public `@astryxdesign/cli/doc` surface.+ */++import {z} from 'zod';++/**+ * A single documented prop. Mirrors `PropDoc` from+ * `@astryxdesign/core/docs-types`. Only `name`, `type`, and `description` are+ * required; everything else is optional. Extra fields (e.g. `slotElements`)+ * pass through so the schema does not have to track every evolution of the+ * rich playground/element surface.+ */+const PropSchema = z+ .object({+ name: z.string().min(1, 'prop name is required'),+ type: z.string().min(1, 'prop type is required'),+ description: z.string(),+ default: z.string().optional(),+ required: z.boolean().optional(),+ })+ .passthrough();++/** A single documented function/hook parameter (mirrors `HookParamDoc`). */+const ParamSchema = z+ .object({+ name: z.string().min(1, 'param name is required'),+ type: z.string().min(1, 'param type is required'),+ description: z.string(),+ default: z.string().optional(),+ required: z.boolean().optional(),+ })+ .passthrough();++/** A single documented function/hook return field (mirrors `HookReturnDoc`). */+const ReturnSchema = z+ .object({+ name: z.string().min(1, 'return name is required'),+ type: z.string().min(1, 'return type is required'),+ description: z.string(),+ })+ .passthrough();++/**+ * Fields shared by every doc kind. Deliberately permissive on the rich blobs+ * (usage/theming/playground) — those are large and still evolving, so they are+ * `z.unknown()` passthrough rather than enumerated.+ *+ * `group` vs `parent` are distinct concepts and intentionally separate fields:+ * - `group` is a FLAT sidebar bucket label. Many docs can share a group; it+ * is not an inheritance key.+ * - `parent` is a DIRECTED inheritance/composition pointer — a doc naming the+ * doc it belongs to (e.g. a sub-component naming its parent component). The+ * legacy `subComponentOf` field is a synonym; both map to the same concept.+ *+ * `relatedDocs` is a single flat curated cross-reference list. It replaces the+ * legacy split `relatedComponents` + `relatedHooks`; a downstream reader can+ * merge the legacy pair into it.+ */+const BaseDocFields = {+ /** Name of the documented unit, without any prefix. Required. */+ name: z.string().min(1, 'name is required'),+ /** Human-readable display name for gallery/sidebar. */+ displayName: z.string().optional(),+ /** One-line/short description. */+ description: z.string().optional(),+ /** Usage documentation (description, best practices, anatomy, slotElements). */+ usage: z.unknown().optional(),+ /** Flat sidebar grouping label (not an inheritance key). */+ group: z.string().optional(),+ /** Overview-page functional category. */+ category: z.string().optional(),+ /** CLI fuzzy-search keywords. */+ keywords: z.array(z.string()).optional(),+ /** Directed inheritance/composition pointer to the doc this belongs to. */+ parent: z.string().optional(),+ /** Flat curated cross-reference list of related doc names. */+ relatedDocs: z.array(z.string()).optional(),+ /** Hide the whole doc from human-facing UI (stays importable/discoverable). */+ hidden: z.boolean().optional(),+ /** Exclude from the categorized overview page (kept in sidebar/CLI). */+ isHiddenFromOverview: z.boolean().optional(),+};++/**+ * New-format schema for a stamped component doc (`type: 'component'`). The+ * top-level component keys are enumerated, but nested blobs stay loose so real+ * docs are not rejected. `.passthrough()` keeps unknown top-level fields+ * (translations, element descriptors, ...) flowing through.+ */+export const ComponentDocKindSchema = z+ .object({+ ...BaseDocFields,+ type: z.literal('component'),+ props: z.array(PropSchema),+ theming: z.unknown().optional(),+ playground: z.unknown().optional(),+ examples: z.array(z.unknown()).optional(),+ })+ .passthrough();++/**+ * New-format schema for a stamped function doc (`type: 'function'`). Covers any+ * function, including hooks: an inputs (`params`) + outputs (`returns`) surface.+ */+export const FunctionDocKindSchema = z+ .object({+ ...BaseDocFields,+ type: z.literal('function'),+ params: z.array(ParamSchema),+ returns: z.array(ReturnSchema),+ })+ .passthrough();++/**+ * New-format schema for a stamped generic doc (`type: 'generic'`) — reference+ * and topic docs. Just the shared base plus the discriminant.+ */+export const GenericDocKindSchema = z+ .object({+ ...BaseDocFields,+ type: z.literal('generic'),+ })+ .passthrough();++/**+ * The stamped-doc contract: one of the three new per-kind schemas, discriminated+ * by the injected `type`. Used when a loaded doc carries a `type` field.+ */+export const StampedDocSchema = z.discriminatedUnion('type', [+ ComponentDocKindSchema,+ FunctionDocKindSchema,+ GenericDocKindSchema,+]);++// ── Legacy loose format (unchanged, kept for back-compat) ─────────────+//+// The pre-factory docs are authored as a loose, untyped object with no `type`+// discriminant and validated by shape. Enumerated top-level fields observed+// across the existing loose docs:+// name, displayName, description, group, category, keywords,+// isHiddenFromOverview, hidden, hiddenComponents, usage, props, components,+// subComponentOf, playground, theming, examples, params, returns,+// relatedComponents, relatedHooks, relatedDocs, parent, importPath.++const LegacyBaseDocSchema = z.object({+ name: z.string().min(1, 'name is required'),+ displayName: z.string().optional(),+ description: z.string().optional(),+ group: z.string().optional(),+ category: z.string().optional(),+ keywords: z.array(z.string()).optional(),+ isHiddenFromOverview: z.boolean().optional(),+ hidden: z.boolean().optional(),+ hiddenComponents: z.array(z.string()).optional(),+ usage: z.unknown().optional(),+ playground: z.unknown().optional(),+ theming: z.unknown().optional(),+ examples: z.array(z.unknown()).optional(),+ showcase: z.unknown().optional(),+ // `parent` and legacy `subComponentOf` are synonyms; both accepted here so a+ // parent-based doc that omits a stamped `type` still validates.+ parent: z.string().optional(),+ relatedDocs: z.array(z.string()).optional(),+ relatedComponents: z.array(z.string()).optional(),+ relatedHooks: z.array(z.string()).optional(),+});++/** Legacy: directory exporting a single primary component (props inline). */+const LegacySingleComponentDocSchema = LegacyBaseDocSchema.extend({+ props: z.array(PropSchema),+}).passthrough();++/** Legacy: directory exporting multiple components (props on each entry). */+const LegacyMultiComponentDocSchema = LegacyBaseDocSchema.extend({+ components: z.array(z.unknown()),+}).passthrough();++/** Legacy: a standalone hook doc — inputs (`params`) + outputs (`returns`). */+const LegacyHookDocSchema = LegacyBaseDocSchema.extend({+ params: z.array(ParamSchema),+ returns: z.array(ReturnSchema),+}).passthrough();++/** Legacy: a sub-component doc parented via `subComponentOf`. */+const LegacySubComponentDocSchema = LegacyBaseDocSchema.extend({+ subComponentOf: z.string().min(1, 'subComponentOf is required'),+ description: z.string(),+ props: z.array(PropSchema),+}).passthrough();++/**+ * The permissive legacy union. `subComponentOf` is listed first so a doc that+ * carries both `subComponentOf` and `props` is validated as a sub-component+ * (the more specific shape); hook (`params`/`returns`) before multi/single.+ */+export const LegacyDocSchema = z.union([+ LegacySubComponentDocSchema,+ LegacyHookDocSchema,+ LegacyMultiComponentDocSchema,+ LegacySingleComponentDocSchema,+]);++/**+ * The LOAD-boundary contract for a doc. Handles BOTH formats:+ * - NEW: a stamped doc (`type: 'component' | 'function' | 'generic'`,+ * produced by the factories) is validated against the matching per-kind+ * schema in {@link StampedDocSchema}.+ * - OLD: a loose, unstamped doc is validated against the permissive+ * {@link LegacyDocSchema} union (the three legacy shapes + standalone hook).+ *+ * Discovery validates the SHAPE, not "was it made by the factory". Both formats+ * normalize into the same internal shape consumers already expect.+ */+export const ComponentDocSchema = z.union([StampedDocSchema, LegacyDocSchema]);diff --git a/packages/cli/src/schemas/template-schema.mjs b/packages/cli/src/schemas/template-schema.mjsnew file mode 100644index 0000000000..b0910326d1--- /dev/null+++ b/packages/cli/src/schemas/template-schema.mjs@@ -0,0 +1,47 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Template load-boundary schemas.+ *+ * The Zod schemas that integration template discovery runs a module's default+ * export through (see `loadModuleWithSchema`). Kept free of any+ * `@astryxdesign/core` import so the hot path that loads them (template+ * discovery, `astryx init`) does not require core's built `dist/`. The+ * authoring factories live in `@astryxdesign/core/authoring` and are re-exported+ * from `../template.mjs` for the public `@astryxdesign/cli/template` surface.+ */++import {z} from 'zod';++const PreviewSchema = z+ .object({+ image: z.string().optional(),+ aspectRatio: z.string().optional(),+ })+ .strict();++/**+ * Shared authored-template shape. `type` is injected by the create* helpers,+ * so authors never write it. Inline source/sourceFile are intentionally NOT+ * part of v1 — a template's source is the required same-stem sibling file.+ * Exported so integration template discovery can validate the stamped result.+ */+export const BaseTemplateSchema = z+ .object({+ name: z.string().min(1, 'name is required'),+ description: z.string().min(1, 'description is required'),+ category: z.string().optional(),+ componentsUsed: z.array(z.string()).optional(),+ preview: PreviewSchema.optional(),+ })+ .strict();++/**+ * The metadata envelope integration template discovery validates: a stamped+ * template doc. This is the LOAD-boundary contract — a hand-written plain+ * object that matches this shape is accepted (discovery does not check "was it+ * made by the factory", only the shape).+ */+export const TemplateEnvelopeSchema = BaseTemplateSchema.extend({+ type: z.enum(['page', 'block']),+});diff --git a/packages/cli/src/template.mjs b/packages/cli/src/template.mjsindex f9d726369a..e8d9c40aa1 100644--- a/packages/cli/src/template.mjs+++ b/packages/cli/src/template.mjs@@ -1,73 +1,15 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * @file Static template authoring API.+ * @file Static template authoring API (public `@astryxdesign/cli/template`).*- * Helpers for authoring Astryx page/block template docs. Like- * `createConfig`/`createIntegration`, these are tiny runtime identity helpers- * whose real value is the exported TypeScript surface from- * `@astryxdesign/cli/template`. They inject the discriminant `type` so a- * discovered doc always knows whether it is a page or a block. They do NOT- * validate — validation happens at the load boundary, where integration- * template discovery runs the module's default export through- * {@link TemplateEnvelopeSchema} (see `loadModuleWithSchema`).+ * The `createPageTemplate`/`createBlockTemplate` authoring helpers now live in+ * `@astryxdesign/core/authoring` and are re-exported here so existing+ * `@astryxdesign/cli/template` imports keep working. The Zod load-boundary+ * schemas live in `./schemas/template-schema.mjs` (core-free) and are+ * re-exported here for back-compat; internal hot-path code imports them from+ * the schema module directly so it never depends on core's built `dist/`.*/-import {z} from 'zod';--const PreviewSchema = z- .object({- image: z.string().optional(),- aspectRatio: z.string().optional(),- })- .strict();--/**- * Shared authored-template shape. `type` is injected by the create* helpers,- * so authors never write it. Inline source/sourceFile are intentionally NOT- * part of v1 — a template's source is the required same-stem sibling file.- * Exported so integration template discovery can validate the stamped result.- */-export const BaseTemplateSchema = z- .object({- name: z.string().min(1, 'name is required'),- description: z.string().min(1, 'description is required'),- category: z.string().optional(),- componentsUsed: z.array(z.string()).optional(),- preview: PreviewSchema.optional(),- })- .strict();--/**- * The metadata envelope integration template discovery validates: a stamped- * template doc. This is the LOAD-boundary contract — a hand-written plain- * object that matches this shape is accepted (discovery does not check "was it- * made by the factory", only the shape).- */-export const TemplateEnvelopeSchema = BaseTemplateSchema.extend({- type: z.enum(['page', 'block']),-});--/**- * Author an Astryx page template doc. Stamp-only: returns the def with- * `type: 'page'` injected. Validation happens at the load boundary.- *- * @template {import('./types/template-api').AstryxPageTemplateInput} T- * @param {T} def- * @returns {T & {type: 'page'}}- */-export function createPageTemplate(def) {- return /** @type {T & {type: 'page'}} */ ({...def, type: 'page'});-}--/**- * Author an Astryx block template doc. Stamp-only: returns the def with- * `type: 'block'` injected. Validation happens at the load boundary.- *- * @template {import('./types/template-api').AstryxBlockTemplateInput} T- * @param {T} def- * @returns {T & {type: 'block'}}- */-export function createBlockTemplate(def) {- return /** @type {T & {type: 'block'}} */ ({...def, type: 'block'});-}+export {createPageTemplate, createBlockTemplate} from '@astryxdesign/core/authoring';+export {BaseTemplateSchema, TemplateEnvelopeSchema} from './schemas/template-schema.mjs';diff --git a/packages/cli/src/types/config.d.ts b/packages/cli/src/types/config.d.tsindex 9618248582..687a0601fc 100644--- a/packages/cli/src/types/config.d.ts+++ b/packages/cli/src/types/config.d.ts@@ -1,70 +1,15 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * A command to run as part of a post-codemod hook. Returned by a hook's- * `buildCommand` and executed via `execFile` after codemods write files.+ * The config-authoring surface moved to `@astryxdesign/core/config` so an app's+ * config file gets type feedback without depending on the CLI. Re-exported here+ * so existing `@astryxdesign/cli/config` type imports keep resolving.*/-export interface PostCodemodCommand {- command: string;- args?: string[];- options?: {- cwd?: string;- env?: NodeJS.ProcessEnv;- timeout?: number;- };-}--/**- * A post-codemod hook. `buildCommand` receives the package directory and the- * list of files changed by codemods, and returns the command to run (or a- * nullish value to skip).- */-export type PostCodemodHook = {- name?: string;- buildCommand: (ctx: {- packageDir: string;- files: string[];- }) =>- | PostCodemodCommand- | null- | undefined- | Promise<PostCodemodCommand | null | undefined>;-};--/** A component XLE layout expressions can reference by name via `{hint}`. */-export interface XleComponent {- /** Import specifier the component is imported from, e.g. '@/components/KpiCard'. */- from: string;- /** Optional human description shown in tooling. */- description?: string;- /** Import as the module's default export instead of a named export. Defaults to false. */- default?: boolean;-}--/** User config exported from astryx.config.{ts,mjs,js}. */-export interface AstryxConfig {- /** Integration package names to load. */- integrations?: string[];- /** Where to file issues/feedback for this project. */- issuesUrl?: string;- /** Lifecycle hooks. */- hooks?: {- postCodemod?: PostCodemodHook[];- };- /**- * EXPERIMENTAL — shape may change and is not part of the stable config- * contract. Provisional home for features still being proven out.- */- experimental?: {- /** Experimental XLE (layout expression) configuration. */- xle?: {- /**- * Register app-local components so XLE layout expressions can- * reference them by name via {hint}. Keyed by component name.- */- components?: Record<string, XleComponent>;- };- };-}--export declare function createConfig<T extends AstryxConfig>(config: T): T;+export type {+ PostCodemodCommand,+ PostCodemodHook,+ XleComponent,+ AstryxConfig,+} from '@astryxdesign/core/config';++export {createConfig} from '@astryxdesign/core/config';diff --git a/packages/cli/src/types/doc.d.ts b/packages/cli/src/types/doc.d.tsindex bcd3dbf949..9be9c5cf98 100644--- a/packages/cli/src/types/doc.d.ts+++ b/packages/cli/src/types/doc.d.ts@@ -1,139 +1,23 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * Authoring surface for Astryx docs, exported from `@astryxdesign/cli/doc`.- *- * A doc lives in a `{Name}.doc.{ts,mjs,js}` file. Authors default-export a- * factory result (`createComponentDoc`/`createFunctionDoc`/`createDoc`) —- * preferred — or, for the current loose docs, name-export `docs`. The doc's- * shape is validated at the load boundary against `ComponentDocSchema` (see- * `doc.mjs`), which accepts BOTH the new stamped formats and the legacy loose- * shape.- *- * The factories inject the `type` discriminant, so authors never write it. The- * inputs are kept as broad records so authoring never fails to typecheck when a- * richer core type surface is not resolvable; the precise per-field guidance- * lives on the doc types in `@astryxdesign/core/docs-types`.+ * The doc-authoring surface moved to `@astryxdesign/core/authoring`. Re-exported+ * here so existing `@astryxdesign/cli/doc` type imports keep resolving. The Zod+ * load-boundary schemas remain in the CLI (see `src/doc.mjs`).*/--/**- * Fields shared by every doc kind (component + function + generic).- *- * `group` vs `parent` are distinct:- * - `group` is a FLAT sidebar bucket label; many docs can share it and it is- * NOT an inheritance key.- * - `parent` is a DIRECTED inheritance/composition pointer — a doc naming the- * doc it belongs to (e.g. a sub-component naming its parent component). The- * legacy `subComponentOf` field is a synonym.- *- * `relatedDocs` is a single flat curated cross-reference list; it replaces the- * legacy split `relatedComponents` + `relatedHooks`.- */-export interface AstryxBaseDocInput {- /** Name of the documented unit, without any prefix, PascalCase. Required. */- name: string;- /** Human-readable display name for gallery/sidebar. */- displayName?: string;- /** Short description. */- description?: string;- /** Usage documentation (description, best practices, anatomy, slotElements). */- usage?: unknown;- /** Flat sidebar grouping label (not an inheritance key). */- group?: string;- /** Overview-page functional category. */- category?: string;- /** CLI fuzzy-search keywords. */- keywords?: string[];- /** Directed inheritance/composition pointer to the doc this belongs to. */- parent?: string;- /** Flat curated cross-reference list of related doc names. */- relatedDocs?: string[];- /** Hide the whole doc from human-facing UI (stays importable/discoverable). */- hidden?: boolean;- /** Exclude from the categorized overview page (kept in sidebar/CLI). */- isHiddenFromOverview?: boolean;- /** Any additional fields the rich doc surface carries. */- [key: string]: unknown;-}--/** A single documented prop (mirrors `PropDoc` from core docs-types). */-export interface AstryxPropInput {- name: string;- type: string;- description: string;- default?: string;- required?: boolean;- [key: string]: unknown;-}--/** A single documented param (mirrors `HookParamDoc`). */-export interface AstryxParamInput {- name: string;- type: string;- description: string;- default?: string;- required?: boolean;- [key: string]: unknown;-}--/** A single documented return field (mirrors `HookReturnDoc`). */-export interface AstryxReturnInput {- name: string;- type: string;- description: string;- [key: string]: unknown;-}--/**- * Input accepted by {@link createComponentDoc}. A component (or a family). The- * `type` discriminant is injected by the factory. `anatomy`/`slotElements` live- * inside `usage`; `importPath` is DERIVED (never authored).- */-export interface AstryxComponentDocInput extends AstryxBaseDocInput {- /** All public props for the component. */- props: AstryxPropInput[];- /** Theming/selector-surface metadata. */- theming?: unknown;- /** Interactive-preview playground configuration. */- playground?: unknown;- /** Short code examples rendered after the props table. */- examples?: unknown[];-}--/**- * Input accepted by {@link createFunctionDoc}. Covers any function, including- * hooks: an inputs (`params`) + outputs (`returns`) surface. The `type`- * discriminant is injected by the factory; `importPath` is DERIVED.- */-export interface AstryxFunctionDocInput extends AstryxBaseDocInput {- /** Function/hook parameters or options-object fields. */- params: AstryxParamInput[];- /** Return value documentation. One entry per field (or a single primitive). */- returns: AstryxReturnInput[];-}--/**- * Input accepted by {@link createDoc}. A generic reference/topic doc — just the- * shared base. The `type` discriminant is injected by the factory.- */-export type AstryxGenericDocInput = AstryxBaseDocInput;--/**- * Back-compat alias. Previously `createDoc` accepted a broad component-doc- * record; the union of the three input kinds preserves that permissiveness for- * any code referring to the old name.- */-export type AstryxComponentDoc =- AstryxComponentDocInput | AstryxFunctionDocInput | AstryxGenericDocInput;--export declare function createComponentDoc<T extends AstryxComponentDocInput>(- def: T,-): T & {type: 'component'};--export declare function createFunctionDoc<T extends AstryxFunctionDocInput>(- def: T,-): T & {type: 'function'};--export declare function createDoc<T extends AstryxGenericDocInput>(- def: T,-): T & {type: 'generic'};+export type {+ AstryxBaseDocInput,+ AstryxPropInput,+ AstryxParamInput,+ AstryxReturnInput,+ AstryxComponentDocInput,+ AstryxFunctionDocInput,+ AstryxGenericDocInput,+ AstryxComponentDoc,+} from '@astryxdesign/core/authoring';++export {+ createComponentDoc,+ createFunctionDoc,+ createDoc,+} from '@astryxdesign/core/authoring';diff --git a/packages/cli/src/types/integration.d.ts b/packages/cli/src/types/integration.d.tsindex ec1d61b60c..4545cce18d 100644--- a/packages/cli/src/types/integration.d.ts+++ b/packages/cli/src/types/integration.d.ts@@ -1,21 +1,14 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * Integration manifest exported from a conventional root manifest file- * (astryx.integration.{ts,mjs,js}) sibling to the integration package's- * package.json. Identity (name/version) comes from the package's- * package.json, not from the manifest.+ * The integration-manifest authoring surface moved to+ * `@astryxdesign/core/authoring`. `AstryxIntegration` and `createIntegration`+ * are re-exported here so existing `@astryxdesign/cli/integration` type imports+ * keep resolving. `AstryxIntegrationIssue` stays in the CLI — it is an internal+ * validation type, not part of the authoring surface.*/-export interface AstryxIntegration {- /** Relative path to the components/docs root (resolved to absolute). */- components?: string;- /** Relative path to the templates root (resolved to absolute). */- templates?: string;- /** Relative path to the codemods root (resolved to absolute). */- codemods?: string;- /** Where to file issues/feedback for this integration. */- issuesUrl?: string;-}+export type {AstryxIntegration} from '@astryxdesign/core/authoring';+export {createIntegration} from '@astryxdesign/core/authoring';/** An issue surfaced by an integration. */export interface AstryxIntegrationIssue {@@ -23,7 +16,3 @@ export interface AstryxIntegrationIssue {severity: 'warning' | 'error';message: string;}--export declare function createIntegration<T extends AstryxIntegration>(- integration: T,-): T;diff --git a/packages/cli/src/types/template-api.d.ts b/packages/cli/src/types/template-api.d.tsindex 0cb83d1a4d..85264febcf 100644--- a/packages/cli/src/types/template-api.d.ts+++ b/packages/cli/src/types/template-api.d.ts@@ -1,54 +1,18 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * Authoring surface for Astryx static templates, exported from- * `@astryxdesign/cli/template`.- *- * A template doc lives in a `<id>.doc.{ts,mjs,js}` file with a required- * same-stem sibling source file (`<id>.tsx`). The doc's `type` (page or- * block) — injected by the create* helpers — decides how the template is- * scaffolded; there is no `/pages` vs `/blocks` directory requirement.+ * The template-authoring surface moved to `@astryxdesign/core/authoring`.+ * Re-exported here so existing `@astryxdesign/cli/template` type imports keep+ * resolving.*/--/** Optional preview metadata for a template (used by docs surfaces). */-export interface AstryxTemplatePreview {- /** Path or URL to a preview image. */- image?: string;- /** CSS aspect-ratio hint for the preview, e.g. "16 / 9". */- aspectRatio?: string;-}--/** Fields common to page and block template docs (without the `type` tag). */-export interface AstryxTemplateInput {- /** Human-readable template name. Required. */- name: string;- /** One-line description of what the template provides. Required. */- description: string;- /** Optional grouping/category label. */- category?: string;- /** Component display names the template composes. */- componentsUsed?: string[];- /** Optional preview metadata. */- preview?: AstryxTemplatePreview;-}--/** Input accepted by {@link createPageTemplate} (no `type` field). */-export type AstryxPageTemplateInput = AstryxTemplateInput;-/** Input accepted by {@link createBlockTemplate} (no `type` field). */-export type AstryxBlockTemplateInput = AstryxTemplateInput;--/** A validated page template doc. */-export type AstryxPageTemplate = AstryxTemplateInput & {type: 'page'};-/** A validated block template doc. */-export type AstryxBlockTemplate = AstryxTemplateInput & {type: 'block'};--/** A validated template doc (page or block). */-export type AstryxTemplate = AstryxPageTemplate | AstryxBlockTemplate;--export declare function createPageTemplate<T extends AstryxPageTemplateInput>(- def: T,-): T & {type: 'page'};--export declare function createBlockTemplate<T extends AstryxBlockTemplateInput>(- def: T,-): T & {type: 'block'};+export type {+ AstryxTemplatePreview,+ AstryxTemplateInput,+ AstryxPageTemplateInput,+ AstryxBlockTemplateInput,+ AstryxPageTemplate,+ AstryxBlockTemplate,+ AstryxTemplate,+} from '@astryxdesign/core/authoring';++export {createPageTemplate, createBlockTemplate} from '@astryxdesign/core/authoring';diff --git a/packages/cli/tsconfig.json-api.json b/packages/cli/tsconfig.json-api.jsonindex dad96e200a..6e221c7425 100644--- a/packages/cli/tsconfig.json-api.json+++ b/packages/cli/tsconfig.json-api.json@@ -5,7 +5,8 @@"allowJs": true,"checkJs": true,"noEmit": true,- "types": ["node"]+ "types": ["node"],+ "customConditions": ["source"]},"include": ["src/types/**/*.d.ts",diff --git a/packages/core/package.json b/packages/core/package.jsonindex d39335a707..0ecd50b0a6 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -59,6 +59,16 @@"types": "./dist/naming.d.ts","default": "./dist/naming.js"},+ "./config": {+ "source": "./src/config.ts",+ "types": "./dist/config.d.ts",+ "default": "./dist/config.js"+ },+ "./authoring": {+ "source": "./src/authoring/index.ts",+ "types": "./dist/authoring/index.d.ts",+ "default": "./dist/authoring/index.js"+ },"./theme/tokens": {"source": "./src/theme/tokens.ts","types": "./dist/theme/tokens.d.ts",diff --git a/packages/core/src/authoring/doc.ts b/packages/core/src/authoring/doc.tsnew file mode 100644index 0000000000..ef217628cc--- /dev/null+++ b/packages/core/src/authoring/doc.ts@@ -0,0 +1,166 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file doc.ts+ * @input A component/function/generic doc object (without the `type` tag).+ * @output Type-preserving `createComponentDoc`/`createFunctionDoc`/`createDoc`+ * helpers plus the doc-authoring TypeScript surface.+ * @position Integration-author authoring surface. See `./index.ts` for why+ * these authoring factories live in `@astryxdesign/core`.+ *+ * A doc describes a documentable unit of the design system so the CLI and docs+ * surfaces can list, search, and render it. There are three kinds, each a tiny+ * runtime identity helper that stamps a `type` discriminant:+ *+ * - `createComponentDoc` -> `type: 'component'` — a component (or a family).+ * - `createFunctionDoc` -> `type: 'function'` — any function, including+ * hooks: an "inputs + outputs" surface (`params` + `returns`).+ * - `createDoc` -> `type: 'generic'` — reference/topic docs.+ *+ * These factories do NOT validate. Validation happens at the CLI load boundary,+ * where doc discovery runs the loaded value through a schema that accepts BOTH+ * the stamped formats and the legacy loose `export const docs = {...}` shape.+ */++/**+ * Fields shared by every doc kind (component + function + generic).+ *+ * `group` vs `parent` are distinct:+ * - `group` is a FLAT sidebar bucket label; many docs can share it and it is+ * NOT an inheritance key.+ * - `parent` is a DIRECTED inheritance/composition pointer — a doc naming the+ * doc it belongs to (e.g. a sub-component naming its parent component). The+ * legacy `subComponentOf` field is a synonym.+ *+ * `relatedDocs` is a single flat curated cross-reference list; it replaces the+ * legacy split `relatedComponents` + `relatedHooks`.+ */+export interface AstryxBaseDocInput {+ /** Name of the documented unit, without any prefix, PascalCase. Required. */+ name: string;+ /** Human-readable display name for gallery/sidebar. */+ displayName?: string;+ /** Short description. */+ description?: string;+ /** Usage documentation (description, best practices, anatomy, slotElements). */+ usage?: unknown;+ /** Flat sidebar grouping label (not an inheritance key). */+ group?: string;+ /** Overview-page functional category. */+ category?: string;+ /** CLI fuzzy-search keywords. */+ keywords?: string[];+ /** Directed inheritance/composition pointer to the doc this belongs to. */+ parent?: string;+ /** Flat curated cross-reference list of related doc names. */+ relatedDocs?: string[];+ /** Hide the whole doc from human-facing UI (stays importable/discoverable). */+ hidden?: boolean;+ /** Exclude from the categorized overview page (kept in sidebar/CLI). */+ isHiddenFromOverview?: boolean;+ /** Any additional fields the rich doc surface carries. */+ [key: string]: unknown;+}++/** A single documented prop (mirrors `PropDoc` from core docs-types). */+export interface AstryxPropInput {+ name: string;+ type: string;+ description: string;+ default?: string;+ required?: boolean;+ [key: string]: unknown;+}++/** A single documented param (mirrors `HookParamDoc`). */+export interface AstryxParamInput {+ name: string;+ type: string;+ description: string;+ default?: string;+ required?: boolean;+ [key: string]: unknown;+}++/** A single documented return field (mirrors `HookReturnDoc`). */+export interface AstryxReturnInput {+ name: string;+ type: string;+ description: string;+ [key: string]: unknown;+}++/**+ * Input accepted by {@link createComponentDoc}. A component (or a family). The+ * `type` discriminant is injected by the factory. `anatomy`/`slotElements` live+ * inside `usage`; `importPath` is DERIVED (never authored).+ */+export interface AstryxComponentDocInput extends AstryxBaseDocInput {+ /** All public props for the component. */+ props: AstryxPropInput[];+ /** Theming/selector-surface metadata. */+ theming?: unknown;+ /** Interactive-preview playground configuration. */+ playground?: unknown;+ /** Short code examples rendered after the props table. */+ examples?: unknown[];+}++/**+ * Input accepted by {@link createFunctionDoc}. Covers any function, including+ * hooks: an inputs (`params`) + outputs (`returns`) surface. The `type`+ * discriminant is injected by the factory; `importPath` is DERIVED.+ */+export interface AstryxFunctionDocInput extends AstryxBaseDocInput {+ /** Function/hook parameters or options-object fields. */+ params: AstryxParamInput[];+ /** Return value documentation. One entry per field (or a single primitive). */+ returns: AstryxReturnInput[];+}++/**+ * Input accepted by {@link createDoc}. A generic reference/topic doc — just the+ * shared base. The `type` discriminant is injected by the factory.+ */+export type AstryxGenericDocInput = AstryxBaseDocInput;++/**+ * Back-compat alias. Previously `createDoc` accepted a broad component-doc+ * record; the union of the three input kinds preserves that permissiveness for+ * any code referring to the old name.+ */+export type AstryxComponentDoc =+ | AstryxComponentDocInput+ | AstryxFunctionDocInput+ | AstryxGenericDocInput;++/**+ * Author a component doc. Stamp-only: returns the def with `type: 'component'`+ * injected. Validation happens at the CLI load boundary.+ */+export function createComponentDoc<T extends AstryxComponentDocInput>(+ def: T,+): T & {type: 'component'} {+ return {...def, type: 'component'};+}++/**+ * Author a function doc (covers any function, including hooks). Stamp-only:+ * returns the def with `type: 'function'` injected. Validation happens at the+ * CLI load boundary.+ */+export function createFunctionDoc<T extends AstryxFunctionDocInput>(+ def: T,+): T & {type: 'function'} {+ return {...def, type: 'function'};+}++/**+ * Author a generic reference/topic doc. Stamp-only: returns the def with+ * `type: 'generic'` injected. Validation happens at the CLI load boundary.+ */+export function createDoc<T extends AstryxGenericDocInput>(+ def: T,+): T & {type: 'generic'} {+ return {...def, type: 'generic'};+}diff --git a/packages/core/src/authoring/index.test.ts b/packages/core/src/authoring/index.test.tsnew file mode 100644index 0000000000..201c42f01c--- /dev/null+++ b/packages/core/src/authoring/index.test.ts@@ -0,0 +1,52 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, expect, it} from 'vitest';+import {+ createIntegration,+ createPageTemplate,+ createBlockTemplate,+ createComponentDoc,+ createFunctionDoc,+ createDoc,+} from './index';++describe('authoring factories', () => {+ it('createIntegration returns its argument unchanged', () => {+ const input = {components: './c', templates: './t'};+ expect(createIntegration(input)).toBe(input);+ });++ it('createPageTemplate / createBlockTemplate stamp the template type', () => {+ expect(createPageTemplate({name: 'P', description: 'd'}).type).toBe('page');+ expect(createBlockTemplate({name: 'B', description: 'd'}).type).toBe(+ 'block',+ );+ });++ it('createPageTemplate preserves authored fields', () => {+ const t = createPageTemplate({name: 'P', description: 'd', category: 'x'});+ expect(t).toMatchObject({+ name: 'P',+ description: 'd',+ category: 'x',+ type: 'page',+ });+ });++ it('doc factories stamp the doc kind', () => {+ expect(createComponentDoc({name: 'Button', props: []}).type).toBe(+ 'component',+ );+ expect(+ createFunctionDoc({name: 'useX', params: [], returns: []}).type,+ ).toBe('function');+ expect(createDoc({name: 'Topic'}).type).toBe('generic');+ });++ it('doc factories do not mutate the input object', () => {+ const input = {name: 'Button', props: []};+ const out = createComponentDoc(input);+ expect(out).not.toBe(input);+ expect(input).not.toHaveProperty('type');+ });+});diff --git a/packages/core/src/authoring/index.ts b/packages/core/src/authoring/index.tsnew file mode 100644index 0000000000..04941121f5--- /dev/null+++ b/packages/core/src/authoring/index.ts@@ -0,0 +1,50 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file index.ts+ * @input None (barrel).+ * @output The Astryx integration-authoring surface: the stamp-only factories an+ * integration package uses to describe what it contributes (integrations,+ * templates, docs), plus their TypeScript input/output types.+ * @position Producer-facing authoring surface, exported as+ * `@astryxdesign/core/authoring`.+ *+ * ## Why these live in core+ *+ * These factories are tiny, zero-runtime-dependency identity functions whose+ * value is their TypeScript surface. Hosting them in `@astryxdesign/core` (the+ * base of the dependency graph) means core's own docs can adopt them without a+ * core -> cli -> core cycle, and integration authors get the types without a+ * hard dependency on the CLI. The CLI re-exports every factory from its+ * existing subpaths (`@astryxdesign/cli/integration|template|doc`) for+ * back-compat; the CLI keeps the Zod validation schemas at its load boundary.+ *+ * `createConfig` is intentionally NOT here — it is a consumer surface (every app+ * with an `astryx.config`), exported separately as `@astryxdesign/core/config`.+ */++export {createIntegration} from './integration';+export type {AstryxIntegration} from './integration';++export {createPageTemplate, createBlockTemplate} from './template';+export type {+ AstryxTemplatePreview,+ AstryxTemplateInput,+ AstryxPageTemplateInput,+ AstryxBlockTemplateInput,+ AstryxPageTemplate,+ AstryxBlockTemplate,+ AstryxTemplate,+} from './template';++export {createComponentDoc, createFunctionDoc, createDoc} from './doc';+export type {+ AstryxBaseDocInput,+ AstryxPropInput,+ AstryxParamInput,+ AstryxReturnInput,+ AstryxComponentDocInput,+ AstryxFunctionDocInput,+ AstryxGenericDocInput,+ AstryxComponentDoc,+} from './doc';diff --git a/packages/core/src/authoring/integration.ts b/packages/core/src/authoring/integration.tsnew file mode 100644index 0000000000..45b9ce5acc--- /dev/null+++ b/packages/core/src/authoring/integration.ts@@ -0,0 +1,42 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file integration.ts+ * @input An integration package's manifest object.+ * @output A type-preserving `createIntegration` helper plus the+ * `AstryxIntegration` manifest surface.+ * @position Integration-author authoring surface. See `./index.ts` for why+ * these authoring factories live in `@astryxdesign/core`.+ *+ * `createIntegration` is an intentionally tiny runtime identity function: it+ * returns its argument unchanged. Validation is NOT performed here — it happens+ * at the CLI load boundary.+ */++/**+ * Integration manifest exported from a conventional root manifest file+ * (astryx.integration.{ts,mjs,js}) sibling to the integration package's+ * package.json. Identity (name/version) comes from the package's+ * package.json, not from the manifest.+ */+export interface AstryxIntegration {+ /** Relative path to the components/docs root (resolved to absolute). */+ components?: string;+ /** Relative path to the templates root (resolved to absolute). */+ templates?: string;+ /** Relative path to the codemods root (resolved to absolute). */+ codemods?: string;+ /** Where to file issues/feedback for this integration. */+ issuesUrl?: string;+}++/**+ * Type-preserving helper for an Astryx integration manifest. Returns its+ * argument unchanged; the value is the exported TypeScript surface. Validation+ * happens at the CLI load boundary.+ */+export function createIntegration<T extends AstryxIntegration>(+ integration: T,+): T {+ return integration;+}diff --git a/packages/core/src/authoring/template.ts b/packages/core/src/authoring/template.tsnew file mode 100644index 0000000000..53ec8594be--- /dev/null+++ b/packages/core/src/authoring/template.ts@@ -0,0 +1,74 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file template.ts+ * @input A page/block template doc object (without the `type` tag).+ * @output Type-preserving `createPageTemplate`/`createBlockTemplate` helpers+ * plus the authored-template TypeScript surface.+ * @position Integration-author authoring surface. See `./index.ts` for why+ * these authoring factories live in `@astryxdesign/core`.+ *+ * A template doc lives in a `<id>.doc.{ts,mjs,js}` file with a required+ * same-stem sibling source file (`<id>.tsx`). The doc's `type` (page or block)+ * — injected by the create* helpers — decides how the template is scaffolded.+ *+ * These are tiny runtime identity helpers that inject the `type` discriminant.+ * They do NOT validate — validation happens at the CLI load boundary, where+ * integration template discovery runs the module's default export through the+ * template envelope schema.+ */++/** Optional preview metadata for a template (used by docs surfaces). */+export interface AstryxTemplatePreview {+ /** Path or URL to a preview image. */+ image?: string;+ /** CSS aspect-ratio hint for the preview, e.g. "16 / 9". */+ aspectRatio?: string;+}++/** Fields common to page and block template docs (without the `type` tag). */+export interface AstryxTemplateInput {+ /** Human-readable template name. Required. */+ name: string;+ /** One-line description of what the template provides. Required. */+ description: string;+ /** Optional grouping/category label. */+ category?: string;+ /** Component display names the template composes. */+ componentsUsed?: string[];+ /** Optional preview metadata. */+ preview?: AstryxTemplatePreview;+}++/** Input accepted by {@link createPageTemplate} (no `type` field). */+export type AstryxPageTemplateInput = AstryxTemplateInput;+/** Input accepted by {@link createBlockTemplate} (no `type` field). */+export type AstryxBlockTemplateInput = AstryxTemplateInput;++/** A validated page template doc. */+export type AstryxPageTemplate = AstryxTemplateInput & {type: 'page'};+/** A validated block template doc. */+export type AstryxBlockTemplate = AstryxTemplateInput & {type: 'block'};++/** A validated template doc (page or block). */+export type AstryxTemplate = AstryxPageTemplate | AstryxBlockTemplate;++/**+ * Author an Astryx page template doc. Stamp-only: returns the def with+ * `type: 'page'` injected. Validation happens at the CLI load boundary.+ */+export function createPageTemplate<T extends AstryxPageTemplateInput>(+ def: T,+): T & {type: 'page'} {+ return {...def, type: 'page'};+}++/**+ * Author an Astryx block template doc. Stamp-only: returns the def with+ * `type: 'block'` injected. Validation happens at the CLI load boundary.+ */+export function createBlockTemplate<T extends AstryxBlockTemplateInput>(+ def: T,+): T & {type: 'block'} {+ return {...def, type: 'block'};+}diff --git a/packages/core/src/config.test.ts b/packages/core/src/config.test.tsnew file mode 100644index 0000000000..c87b3e58f4--- /dev/null+++ b/packages/core/src/config.test.ts@@ -0,0 +1,16 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, expect, it} from 'vitest';+import {createConfig} from './config';++describe('createConfig', () => {+ it('returns its argument unchanged (identity)', () => {+ const input = {integrations: ['@acme/astryx'], issuesUrl: 'https://x'};+ expect(createConfig(input)).toBe(input);+ });++ it('does not stamp a discriminant', () => {+ const cfg = createConfig({integrations: []}) as Record<string, unknown>;+ expect(cfg.type).toBeUndefined();+ });+});diff --git a/packages/core/src/config.ts b/packages/core/src/config.tsnew file mode 100644index 0000000000..6b8ccec2d1--- /dev/null+++ b/packages/core/src/config.ts@@ -0,0 +1,92 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file config.ts+ * @input An app's Astryx config object.+ * @output A type-preserving `createConfig` helper plus the `AstryxConfig`+ * surface authors write in `astryx.config.{ts,mjs,js}`.+ * @position Consumer-facing authoring surface. Lives in `@astryxdesign/core`+ * (not the CLI) so an app's config file gets editor/type feedback without+ * taking a dependency on the CLI. The CLI re-exports this from+ * `@astryxdesign/cli/config` for back-compat.+ *+ * `createConfig` is an intentionally tiny runtime identity function: it returns+ * its argument unchanged. Its value is the exported TypeScript surface.+ * Validation is NOT performed here — it happens at the CLI load boundary.+ */++/**+ * A command to run as part of a post-codemod hook. Returned by a hook's+ * `buildCommand` and executed after codemods write files.+ */+export interface PostCodemodCommand {+ command: string;+ args?: string[];+ options?: {+ cwd?: string;+ env?: NodeJS.ProcessEnv;+ timeout?: number;+ };+}++/**+ * A post-codemod hook. `buildCommand` receives the package directory and the+ * list of files changed by codemods, and returns the command to run (or a+ * nullish value to skip).+ */+export type PostCodemodHook = {+ name?: string;+ buildCommand: (ctx: {+ packageDir: string;+ files: string[];+ }) =>+ | PostCodemodCommand+ | null+ | undefined+ | Promise<PostCodemodCommand | null | undefined>;+};++/** A component XLE layout expressions can reference by name via `{hint}`. */+export interface XleComponent {+ /** Import specifier the component is imported from, e.g. '@/components/KpiCard'. */+ from: string;+ /** Optional human description shown in tooling. */+ description?: string;+ /** Import as the module's default export instead of a named export. Defaults to false. */+ default?: boolean;+}++/** User config exported from astryx.config.{ts,mjs,js}. */+export interface AstryxConfig {+ /** Integration package names to load. */+ integrations?: string[];+ /** Where to file issues/feedback for this project. */+ issuesUrl?: string;+ /** Lifecycle hooks. */+ hooks?: {+ postCodemod?: PostCodemodHook[];+ };+ /**+ * EXPERIMENTAL — shape may change and is not part of the stable config+ * contract. Provisional home for features still being proven out.+ */+ experimental?: {+ /** Experimental XLE (layout expression) configuration. */+ xle?: {+ /**+ * Register app-local components so XLE layout expressions can+ * reference them by name via {hint}. Keyed by component name.+ */+ components?: Record<string, XleComponent>;+ };+ };+}++/**+ * Type-preserving helper for the Astryx config file. Returns its argument+ * unchanged; the value is the exported TypeScript surface so config files get+ * editor/type feedback. Validation happens at the CLI load boundary.+ */+export function createConfig<T extends AstryxConfig>(config: T): T {+ return config;+}diff --git a/scripts/sync-exports.js b/scripts/sync-exports.jsindex 808ddd2aae..408d4b627e 100644--- a/scripts/sync-exports.js+++ b/scripts/sync-exports.js@@ -68,6 +68,16 @@ const STATIC_EXPORTS = {types: './dist/naming.d.ts',default: './dist/naming.js',},+ './config': {+ source: './src/config.ts',+ types: './dist/config.d.ts',+ default: './dist/config.js',+ },+ './authoring': {+ source: './src/authoring/index.ts',+ types: './dist/authoring/index.d.ts',+ default: './dist/authoring/index.js',+ },'./theme/tokens': {source: './src/theme/tokens.ts',types: './dist/theme/tokens.d.ts',