@astryxdesign/cli 0.1.6-canary.2e2e960 → 0.1.6-canary.372d81b

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.6-canary.2e2e960",
+  "version": "0.1.6-canary.372d81b",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -47,10 +47,6 @@
       "types": "./src/types/integration.d.ts",
       "import": "./src/integration.mjs"
     },
-    "./doc": {
-      "types": "./src/types/doc.d.ts",
-      "import": "./src/doc.mjs"
-    },
     "./template": {
       "types": "./src/types/template-api.d.ts",
       "import": "./src/template.mjs"
@@ -79,10 +75,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.1.6-canary.2e2e960",
-    "@astryxdesign/core": "0.1.6-canary.2e2e960",
-    "@astryxdesign/lab": "0.1.6-canary.2e2e960",
-    "@astryxdesign/theme-neutral": "0.1.6-canary.2e2e960",
+    "@astryxdesign/charts": "0.1.6-canary.372d81b",
+    "@astryxdesign/core": "0.1.6-canary.372d81b",
+    "@astryxdesign/lab": "0.1.6-canary.372d81b",
+    "@astryxdesign/theme-neutral": "0.1.6-canary.372d81b",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -100,10 +96,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.1.6-canary.2e2e960",
-    "@astryxdesign/core": "0.1.6-canary.2e2e960",
-    "@astryxdesign/lab": "0.1.6-canary.2e2e960",
-    "@astryxdesign/theme-neutral": "0.1.6-canary.2e2e960",
+    "@astryxdesign/charts": "0.1.6-canary.372d81b",
+    "@astryxdesign/core": "0.1.6-canary.372d81b",
+    "@astryxdesign/lab": "0.1.6-canary.372d81b",
+    "@astryxdesign/theme-neutral": "0.1.6-canary.372d81b",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {

package/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 '../schemas/template-schema.mjs';
+import {TemplateEnvelopeSchema} from '../template.mjs';
 import {CLI_ROOT, discoverExternalPackages} from '../utils/paths.mjs';
 import {
   assertWithin,

package/src/api/validate-integration.mjs

@@ -67,6 +67,11 @@ function error(code, message) {
   return {code, severity: 'error', message};
 }
 
+/** @param {string} code @param {string} message @returns {Issue} */
+function warning(code, message) {
+  return {code, severity: 'warning', message};
+}
+
 /**
  * Verify each declared contribution root exists on disk. A declared-but-missing
  * root is a `missing_root` error.
@@ -360,3 +365,6 @@ export function summarizeIssues(issues) {
   }
   return {errors, warnings};
 }
+
+// Re-export issue constructors for callers/tests that want them.
+export {error as integrationError, warning as integrationWarning};

package/src/config.mjs

@@ -1,9 +1,18 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * 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.
+ * 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}
  */
-export {createConfig} from '@astryxdesign/core/config';
+export function createConfig(config) {
+  return config;
+}

package/src/integration.mjs

@@ -1,8 +1,19 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * 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.
+ * 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}
  */
-export {createIntegration} from '@astryxdesign/core/authoring';
+export function createIntegration(integration) {
+  return integration;
+}

package/src/lib/component-discovery.mjs

@@ -273,24 +273,14 @@ export function findComponentReadme(coreDir, name) {
  * For "Button" finds src/Button/XDSButton.tsx
  * For "Layout" finds src/Layout/XDSLayout/XDSLayout.tsx
  * For "Card" finds src/Layout/Container/XDSCard.tsx (deep search fallback)
- *
- * Hooks and other functions are authored as `.ts` (e.g. `useMediaQuery.ts`,
- * `useResizable.ts`), so `.ts` candidates are searched alongside `.tsx`. Without
- * this, deriving the import path for a `.ts`-authored function falls back to the
- * bare `@astryxdesign/core` root instead of its tree-shakeable subpath.
  */
 export function findComponentSource(coreDir, name) {
   const srcDir = path.join(coreDir, 'src');
-  // Try the prefixed forms (`XDSButton.tsx`) first since that is the current
-  // on-disk convention, then the bare forms (`Button.tsx`) that the Astryx-prefix
-  // migration (P4) renames to. `.tsx` before `.ts` within each so a component's
-  // `.tsx` wins over a same-named `.ts` helper; `.ts` covers hooks/functions.
-  const candidateFiles = [
-    `XDS${name}.tsx`,
-    `${name}.tsx`,
-    `XDS${name}.ts`,
-    `${name}.ts`,
-  ];
+  // Try the prefixed form (`XDSButton.tsx`) first since that is the current
+  // on-disk convention, then the bare form (`Button.tsx`) that the Astryx-prefix
+  // migration (P4) renames to. Listing the prefixed name first keeps behavior
+  // identical until files are actually renamed.
+  const candidateFiles = [`XDS${name}.tsx`, `${name}.tsx`];
 
   function searchDir(dirPath) {
     if (!fs.existsSync(dirPath)) return null;

package/src/lib/component-loader.mjs

@@ -5,59 +5,6 @@
  */
 
 import {pathToFileURL} from 'node:url';
-import {importUserModule} from './module-loader.mjs';
-import {formatZodError} from './config-schema.mjs';
-import {ComponentDocSchema} from '../schemas/doc-schema.mjs';
-
-/**
- * Load a component doc through the shared load/validation boundary.
- *
- * This is the typed counterpart to {@link loadDocs}: it loads `.doc.ts` via
- * jiti (and `.doc.mjs`/`.doc.js` via native import) and validates against
- * {@link ComponentDocSchema}. That schema accepts BOTH formats, so this loader
- * reads whichever the file uses:
- *   - NEW: the factory default export
- *     (`export default createComponentDoc({...})` / `createFunctionDoc` /
- *     `createDoc`) — the same single-export convention
- *     {@link loadModuleWithSchema} uses for config/integration/template. These
- *     carry a stamped `type` and validate against the matching per-kind schema.
- *   - OLD: the legacy loose `export const docs = {...}` (no `type`), validated
- *     against the permissive legacy union.
- * The default export wins when both are present. Throws a readable
- * `formatZodError`-style message on failure. Translations (`docsZh`/
- * `docsDense`) are merged exactly as {@link loadDocs} does so callers see
- * identical output.
- *
- * @param {string} docPath absolute path to a `.doc.{ts,mjs,js}` file
- * @param {{zh?: boolean, dense?: boolean, lang?: string}} [opts]
- * @returns {Promise<object>} the validated (and optionally translated) doc
- */
-export async function loadComponentDoc(
-  docPath,
-  {zh = false, dense = false, lang} = {},
-) {
-  const mod = await importUserModule(docPath);
-  const authored = mod?.default ?? mod?.docs;
-
-  const result = ComponentDocSchema.safeParse(authored);
-  if (!result.success) {
-    throw new Error(formatZodError(docPath, result.error));
-  }
-  const docs = authored;
-
-  const locale = lang || (dense ? 'dense' : zh ? 'zh' : null);
-  if (!locale) return docs;
-
-  const translationKey =
-    locale === 'zh' ? 'docsZh' : locale === 'dense' ? 'docsDense' : null;
-  if (!translationKey || !mod[translationKey]) return docs;
-
-  const translation = mod[translationKey];
-  if (translation.props || translation.components?.some(c => c.props)) {
-    return translation;
-  }
-  return mergeTranslation(docs, translation);
-}
 
 export function mergeTranslation(docs, translation) {
   if (!translation) return docs;

package/src/lib/config-schema.mjs

@@ -73,3 +73,33 @@ export function formatZodError(label, error) {
     .join('; ');
   return `${label} is invalid: ${issues}`;
 }
+
+/**
+ * @param {unknown} config
+ * @returns {import('../types/config').AstryxConfig}
+ */
+export function validateConfig(config) {
+  const result = AstryxConfigSchema.safeParse(config);
+  if (!result.success) {
+    throw new Error(
+      formatZodError('astryx.config default export', result.error),
+    );
+  }
+  return result.data;
+}
+
+/**
+ * @param {unknown} integration
+ * @param {string} [label]
+ * @returns {import('../types/integration').AstryxIntegration}
+ */
+export function validateIntegration(
+  integration,
+  label = 'integration manifest',
+) {
+  const result = AstryxIntegrationSchema.safeParse(integration);
+  if (!result.success) {
+    throw new Error(formatZodError(label, result.error));
+  }
+  return result.data;
+}

package/src/lib/xle/registry.mjs

@@ -230,3 +230,8 @@ export async function buildRegistry({cwd = process.cwd()} = {}) {
   };
   return cachedRegistry;
 }
+
+/** Test seam — drop the module-level cache. */
+export function resetRegistryCache() {
+  cachedRegistry = null;
+}

package/src/template.mjs

@@ -1,15 +1,73 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Static template authoring API (public `@astryxdesign/cli/template`).
+ * @file Static template authoring API.
  *
- * 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/`.
+ * 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`).
  */
 
-export {createPageTemplate, createBlockTemplate} from '@astryxdesign/core/authoring';
-export {BaseTemplateSchema, TemplateEnvelopeSchema} from './schemas/template-schema.mjs';
+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'});
+}

package/src/types/config.d.ts

@@ -1,15 +1,70 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * 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.
+ * 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.
  */
-export type {
-  PostCodemodCommand,
-  PostCodemodHook,
-  XleComponent,
-  AstryxConfig,
-} from '@astryxdesign/core/config';
-
-export {createConfig} from '@astryxdesign/core/config';
+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;

package/src/types/integration.d.ts

@@ -1,14 +1,21 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * 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.
+ * 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 type {AstryxIntegration} from '@astryxdesign/core/authoring';
-export {createIntegration} from '@astryxdesign/core/authoring';
+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;
+}
 
 /** An issue surfaced by an integration. */
 export interface AstryxIntegrationIssue {
@@ -16,3 +23,7 @@ export interface AstryxIntegrationIssue {
   severity: 'warning' | 'error';
   message: string;
 }
+
+export declare function createIntegration<T extends AstryxIntegration>(
+  integration: T,
+): T;

package/src/types/template-api.d.ts

@@ -1,18 +1,54 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * The template-authoring surface moved to `@astryxdesign/core/authoring`.
- * Re-exported here so existing `@astryxdesign/cli/template` type imports keep
- * resolving.
+ * 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.
  */
-export type {
-  AstryxTemplatePreview,
-  AstryxTemplateInput,
-  AstryxPageTemplateInput,
-  AstryxBlockTemplateInput,
-  AstryxPageTemplate,
-  AstryxBlockTemplate,
-  AstryxTemplate,
-} from '@astryxdesign/core/authoring';
-
-export {createPageTemplate, createBlockTemplate} from '@astryxdesign/core/authoring';
+
+/** 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'};