@astryxdesign/cli 0.2.0 → 0.3.0

package/authoring/doctypes/template/type.ts

@@ -0,0 +1,167 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Template doc types.
+ */
+
+export interface BaseTemplateDoc {
+  /** 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
+   *  display value (e.g. `"Dashboard"`). */
+  name: string;
+  /** Human-readable display name for the gallery / CLI. Matches `name`
+   *  for already-spaced template names (e.g. `"Blank Page"`); for block
+   *  templates that mirror a PascalCase component, spaces it out
+   *  (`"ChatMessageMetadata"` → `"Chat Message Metadata"`). Required so
+   *  authors stay in control of the visible label rather than relying
+   *  on a build-time regex derivation. */
+  displayName: string;
+
+  /** One-sentence description of what the template provides. */
+  description?: string;
+
+  /** Whether this template is ready for use. Templates with
+   *  isReady: false show as "(WIP)" in the gallery and CLI. */
+  isReady?: boolean;
+
+  /** Whether this template is a scaffolding tool only (e.g. blank page).
+   *  Scaffold templates are available via the CLI but hidden from
+   *  browsable template galleries like the craft browser. */
+  scaffold?: boolean;
+
+  /** Functional category for the docsite Templates overview gallery.
+   *  Templates are grouped by the part before `" - "` (e.g. `"Dashboard"`).
+   *  Independent of CLI discovery, which uses `name`/`description`. */
+  category?: TemplateCategory;
+
+  /** Boolean opt-out for templates that shouldn't appear on the Templates
+   *  overview gallery. The template stays available via the CLI and
+   *  `astryx template <name>` — it's only hidden from the browsable gallery.
+   *  Use for duplicate/experimental variants. Scaffold templates are
+   *  hidden automatically and don't need this flag. */
+  isHiddenFromOverview?: boolean;
+}
+
+export interface BlockTemplateDoc extends BaseTemplateDoc {
+  type: 'block';
+  /** The component this block is an example of.
+   *  Matches the component's doc name (e.g. 'Button', 'Dialog', 'Stack').
+   *  Used by the docsite to show relevant examples on component detail pages. */
+  exampleFor: string;
+  /** Additional component or hook doc pages whose Examples section should
+   *  include this block. Use when a component example is also the canonical
+   *  usage example for one of that component's hooks. */
+  alsoExampleFor?: string[];
+  /** Additional component or hook doc pages whose hero showcase should reuse
+   *  this block. Unlike `isShowcase`, this does not make the block the primary
+   *  showcase for `exampleFor`; it only creates explicit secondary placements. */
+  alsoShowcaseFor?: string[];
+  /** Width-to-height ratio for preview containers (e.g. 16/9, 1, 3/4). */
+  aspectRatio: number;
+  /** Scale factor for the block preview (default 1). */
+  scale?: number;
+  /** Component names this block uses, for cross-referencing.
+   *  Powers "See also" and "Used in" sections — not for primary attribution. */
+  componentsUsed?: string[];
+  /** When true this block is the canonical "hero" showcase for a component. */
+  isShowcase?: boolean;
+}
+
+export interface PageTemplateDoc extends BaseTemplateDoc {
+  type: 'page';
+}
+
+/**
+ * Functional category for a page template, used to group templates on the
+ * docsite Templates overview gallery. Independent of any sidebar/nav grouping.
+ *
+ * Values follow a `"Group - Variant"` convention (e.g. `"Dashboard - Analytics"`).
+ * The overview page derives the group heading from the text before the `" - "`.
+ * Standalone values without a hyphen (e.g. `"Settings"`) are their own group.
+ *
+ * Not every value maps to an existing template — unused values are reserved
+ * for future templates so authors get autocomplete for the full taxonomy.
+ */
+export type TemplateCategory =
+  // Dashboard
+  | 'Dashboard - Analytics'
+  | 'Dashboard - KPI Summary'
+  | 'Dashboard - Monitoring'
+  | 'Dashboard - Executive Summary'
+  | 'Dashboard - Widget Grid'
+  | 'Dashboard - Split'
+  | 'Dashboard - Tabbed'
+  | 'Dashboard - Filterable'
+  | 'Dashboard - Portfolio'
+  // Table
+  | 'Table - Basic'
+  | 'Table - Grouped'
+  | 'Table - Index/Detail'
+  | 'Table - Split Pane'
+  | 'Table - Bulk Actions'
+  | 'Table - Filtering'
+  | 'Table - Tree/Hierarchical List'
+  | 'Table - Frozen Column'
+  | 'Table - Chart'
+  | 'Table - Heatmap'
+  // Form
+  | 'Form - Basic'
+  | 'Form - Page'
+  | 'Form - Checkout'
+  | 'Form - Two-column'
+  | 'Form - Wizard'
+  | 'Form - Modal Overlay'
+  | 'Form - Side Sheet'
+  | 'Form - Inline Edits'
+  | 'Form - Settings'
+  // Settings
+  | 'Settings'
+  | 'Settings - Dialog'
+  | 'Settings - Sidebar'
+  | 'Settings - Panels'
+  | 'Settings - Form'
+  // Login
+  | 'Login - Basic'
+  | 'Login - Card'
+  | 'Login - SSO'
+  | 'Login - Split'
+  // Tools
+  | 'Tools - File Explorer'
+  | 'Tools - Page Editor'
+  | 'Tools - IDE'
+  | 'Tools - Incident Console'
+  | 'Tools - Kanban Board'
+  | 'Tools - Notebook/Report Page'
+  | 'Tools - Diff Compare Viewer'
+  | 'Tools - Search Results Page'
+  // Content
+  | 'Content - Card Grid'
+  | 'Content - Order Detail'
+  | 'Content - Product Detail'
+  | 'Content - Product List'
+  | 'Content - Documentation Catalog'
+  | 'Content - Documentation Design'
+  | 'Content - Documentation Technical'
+  | 'Content - Infinite Scroll Page'
+  | 'Content - Timeline'
+  | 'Content - Profile Page'
+  // AI Chat
+  | 'AI Chat - Conversation'
+  | 'AI Chat - Landing'
+  | 'AI Chat - Artifact Page'
+  // Gallery
+  | 'Gallery - Hero'
+  | 'Gallery - Basic'
+  | 'Gallery - Mixed'
+  | 'Gallery - Side'
+  | 'Gallery - Product'
+  // Shell
+  | 'Shell - Left Sidebar'
+  | 'Shell - Top Nav'
+  | 'Shell - Top Nav + Left Sidebar'
+  | 'Shell - Breadcrumb Driven Layout'
+  | 'Shell - Messaging'
+  | 'Shell - Blank';
+
+export type TemplateDoc = PageTemplateDoc | BlockTemplateDoc;

package/authoring/doctypes/types.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @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
+ * behind `@astryxdesign/cli/authoring`.
+ */
+
+export type * from './base/type';
+export type * from './component/type';
+export type * from './hook/type';
+export type * from './reference/type';
+export type * from './template/type';

package/authoring/index.d.ts

@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Public type surface for `@astryxdesign/cli/authoring`.
+ *
+ * Authoring is a pure data contract: the TYPES you write plain objects against,
+ * and the PARSERS the CLI runs at the load boundary (`unknown` → typed, or a
+ * readable throw). Zod is sealed inside each parser and never appears here.
+ * There are no `create*` factories — author a plain object and stamp its `type`.
+ *
+ * This file reads as a menu: the handful of things you author sit up top, the
+ * field/sub-types they compose from are grouped below the divider, and internal
+ * runner types are not exported here at all.
+ *
+ * NOTE: this barrel is a `.d.ts` on purpose. It is a pure re-export (including
+ * the parser value bindings from `./*.mjs`), and downstream package builds
+ * resolve `@astryxdesign/cli/authoring` here via the `types` condition. Their
+ * tsconfigs run with `skipLibCheck` (which skips `.d.ts`) but no `allowJs`, so a
+ * real `.ts` barrel would make tsc follow the `.mjs` re-exports and fail TS7016.
+ * The runtime entry is the sibling `index.mjs`.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════
+// AUTHOR THESE — each is the default export of one authored file.
+// ═══════════════════════════════════════════════════════════════════════
+export type {ComponentDoc} from './doctypes/types'; //   Button.doc.{ts,mjs}
+export type {HookDoc} from './doctypes/types'; //         useToast.doc.{ts,mjs}
+export type {ReferenceDoc} from './doctypes/types'; //    theming.doc.{ts,mjs}
+export type {TemplateDoc} from './doctypes/types'; //     Foo.template.{ts,mjs}
+export type {AstryxConfig} from './config/type'; //       astryx.config.{ts,mjs}
+export type {AstryxIntegration} from './integration/type'; // astryx.integration.{ts,mjs}
+export type {AstryxCodemod, AstryxConfigCodemod} from './codemod/type'; // codemods/*
+
+// ═══════════════════════════════════════════════════════════════════════
+// PARSERS — the CLI's load boundary (types come from each parser's JSDoc).
+// ═══════════════════════════════════════════════════════════════════════
+export {parseDoc} from './doctypes/parse.mjs';
+export {parseComponent} from './doctypes/component/parse.mjs';
+export {parseHook} from './doctypes/hook/parse.mjs';
+export {parseReference} from './doctypes/reference/parse.mjs';
+export {parseTemplate} from './doctypes/template/parse.mjs';
+export {parseLegacyDoc} from './doctypes/legacy.mjs';
+export {parseConfig} from './config/parse.mjs';
+export {parseIntegration} from './integration/parse.mjs';
+export {parseCodemod} from './codemod/parse.mjs';
+
+// ═══════════════════════════════════════════════════════════════════════
+// FIELD & SUB-TYPES — the building blocks of the docs above. Import these
+// only to annotate a part directly (or to read/render docs); you rarely
+// need them to author. Names carry the doc kind they belong to.
+// ═══════════════════════════════════════════════════════════════════════
+export type {
+  // component
+  SingleComponentDoc,
+  MultiComponentDoc,
+  ComponentEntry,
+  ComponentGroupDoc,
+  ComponentTranslationDoc,
+  ComponentPropDoc,
+  ComponentExampleDoc,
+  ComponentAnatomyElement,
+  ComponentBestPractice,
+  ComponentSlotElement,
+  ComponentPlaygroundConfig,
+  ComponentThemingTarget,
+  ComponentThemingVar,
+  ComponentThemingDerivedVar,
+  UsageDoc,
+  // hook
+  HookParamDoc,
+  HookReturnDoc,
+  HookTranslationDoc,
+  // reference
+  ReferenceSection,
+  ReferenceContentBlock,
+  ReferenceTokenPreviewType,
+  ReferenceTranslationDoc,
+  // template
+  TemplateCategory,
+} from './doctypes/types';
+export type {PostCodemodHook} from './config/type';
+export type {
+  AstryxCodemodDef,
+  AstryxConfigCodemodDef,
+  AstryxCodemodFile,
+  AstryxCodemodApi,
+  AstryxCodemodTransform,
+} from './codemod/type';

package/authoring/index.mjs

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `@astryxdesign/cli/authoring` — one home for Astryx authoring.
+ *
+ * Authoring is a pure data contract: TYPES authors write plain objects against,
+ * and PARSERS the CLI calls to turn `unknown` into the typed shape (or throw a
+ * readable error) at the load boundary. Zod is an implementation detail sealed
+ * inside each parser — it is never exported here and never appears in a public
+ * type. There are no `create*` factories: author a plain object and stamp its
+ * `type` directly.
+ *
+ * Types (config, integration, codemod, and the doc vocabulary —
+ * component/hook/reference/template) are re-exported via `./index.ts`.
+ */
+
+export {parseConfig} from './config/parse.mjs';
+export {parseIntegration} from './integration/parse.mjs';
+export {parseCodemod} from './codemod/parse.mjs';
+export {parseDoc} from './doctypes/parse.mjs';
+export {parseComponent} from './doctypes/component/parse.mjs';
+export {parseHook} from './doctypes/hook/parse.mjs';
+export {parseReference} from './doctypes/reference/parse.mjs';
+export {parseTemplate} from './doctypes/template/parse.mjs';
+export {parseLegacyDoc} from './doctypes/legacy.mjs';

package/authoring/integration/parse.d.mts

@@ -0,0 +1,4 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import type {AstryxIntegration} from './type';
+export function parseIntegration(input: unknown, label?: string): AstryxIntegration;

package/authoring/integration/parse.mjs

@@ -0,0 +1,44 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Integration-manifest parser — the load-boundary validator for
+ * `astryx.integration.*`. Zod is sealed here; consumers call `parseIntegration`
+ * or import the {@link AstryxIntegration} type.
+ */
+
+import {z} from 'zod';
+import {formatZodError} from '../_shared/errors.mjs';
+
+/** @typedef {import('./type').AstryxIntegration} AstryxIntegration */
+
+const integrationSchema = z
+  .object({
+    components: z.string().optional(),
+    templates: z.string().optional(),
+    codemods: z.string().optional(),
+    issuesUrl: z.string().url().optional(),
+  })
+  .strict();
+
+/**
+ * Compile-time drift-lock: sealed schema must infer exactly {@link AstryxIntegration}.
+ *
+ * @typedef {import('../_shared/contract').Expect<
+ *   import('../_shared/contract').Equal<z.infer<typeof integrationSchema>, AstryxIntegration>
+ * >} _IntegrationDriftLock
+ */
+
+/**
+ * Validate an unknown value as an Astryx integration manifest, or throw.
+ *
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {AstryxIntegration}
+ */
+export function parseIntegration(input, label = 'astryx.integration') {
+  const result = integrationSchema.safeParse(input);
+  if (!result.success) {
+    throw new Error(formatZodError(label, result.error));
+  }
+  return result.data;
+}

package/authoring/integration/parse.test.mjs

@@ -0,0 +1,41 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated tests for `parseIntegration` — the load-boundary validator for
+ * `astryx.integration.*`. Zod is sealed inside the parser; these exercise the
+ * public contract (validated value out / readable error thrown) with the same
+ * accept/reject set the old `AstryxIntegrationSchema` had.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {parseIntegration} from './parse.mjs';
+
+/** Run parseIntegration and return the thrown message (asserting it throws). */
+function reason(value, label = 'integration') {
+  try {
+    parseIntegration(value, label);
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+  throw new Error('expected parseIntegration to throw');
+}
+
+describe('parseIntegration (load boundary)', () => {
+  it('accepts an empty manifest and a valid one', () => {
+    expect(parseIntegration({})).toEqual({});
+    expect(parseIntegration({components: './src'})).toEqual({
+      components: './src',
+    });
+    expect(() =>
+      parseIntegration({components: './c', issuesUrl: 'https://example.com/i'}),
+    ).not.toThrow();
+  });
+
+  it('rejects unknown keys (strict)', () => {
+    expect(reason({name: '@acme/widgets'})).toContain('Unrecognized key');
+  });
+
+  it('rejects a non-URL issuesUrl', () => {
+    expect(reason({issuesUrl: 'nope'})).toContain('issuesUrl');
+  });
+});

package/authoring/integration/type.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Public type surface for an Astryx integration manifest
+ * (`astryx.integration.{ts,mjs,js}`, sibling to the integration package's
+ * package.json). Identity (name/version) comes from package.json, not the
+ * manifest. Authors write a plain object against {@link AstryxIntegration};
+ * the CLI validates it via `parseIntegration` at the load boundary.
+ */
+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;
+}

package/clients/cli/__tests__/cliManifest.test.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import fs from 'fs';
+import path from 'path';
+import {describe, it, expect} from 'vitest';
+
+describe('@astryxdesign/cli Theme Manifest & Template Validation', () => {
+  const manifestPath = path.resolve(
+    'packages/cli/assets/templates/themes/manifest.json',
+  );
+
+  it('validates theme manifest existence and structure', () => {
+    expect(fs.existsSync(manifestPath)).toBe(true);
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+
+    expect(manifest.version).toBe(1);
+    expect(Array.isArray(manifest.themes)).toBe(true);
+    expect(manifest.themes.length).toBeGreaterThan(0);
+  });
+
+  it('verifies all referenced theme files exist', () => {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    const themesDir = path.dirname(manifestPath);
+
+    for (const theme of manifest.themes) {
+      expect(theme.slug).toBeDefined();
+      expect(theme.displayName).toBeDefined();
+      expect(theme.entry).toBeDefined();
+
+      const entryPath = path.join(themesDir, theme.slug, theme.entry);
+      expect(fs.existsSync(entryPath)).toBe(true);
+
+      for (const file of theme.files) {
+        const filePath = path.join(themesDir, theme.slug, file);
+        expect(fs.existsSync(filePath)).toBe(true);
+      }
+    }
+  });
+});

package/clients/cli/bin/astryx.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+// ---------------------------------------------------------------------------
+// Node.js version preflight gate.
+//
+// The CLI and its dependencies use `styleText` from `node:util`, added in Node
+// 22.13.0. On older runtimes the lazy-loaded subcommands die with a cryptic
+// ESM error ("...does not provide an export named 'styleText'"). To give users
+// a clear message instead, we check the running version FIRST, using only
+// built-ins, and exit early before importing anything that touches styleText.
+//
+// `node-version.mjs` is intentionally dependency-free so it loads on the
+// unsupported runtimes this guard protects against.
+//
+// Sibling package modules (e.g. `cli/`, `lib/`) are resolved by this bin's REAL
+// path. When the CLI is installed as a package, `npx astryx` runs this file
+// through the `node_modules/.bin/astryx` symlink, and some Node versions resolve
+// relative specifiers from the symlink's directory rather than the real package
+// — breaking bare `../…` imports with a cryptic ERR_MODULE_NOT_FOUND.
+// realpath-ing `import.meta.url` makes these imports resolve correctly however
+// the bin is invoked (symlink, copy, or Windows shim). Uses only built-ins, so
+// the version gate below still runs first.
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import {realpathSync} from 'node:fs';
+import {dirname, join} from 'node:path';
+
+const binDir = dirname(realpathSync(fileURLToPath(import.meta.url)));
+/** @param {string} rel */
+const importSrc = rel =>
+  import(pathToFileURL(join(binDir, '..', rel)).href);
+
+const {isNodeVersionSupported, unsupportedNodeMessage} =
+  await importSrc('../../foundation/env/node-version.mjs');
+
+if (!isNodeVersionSupported(process.versions.node)) {
+  const msg = unsupportedNodeMessage(process.versions.node);
+  // Honor the --json contract even at this pre-import gate. We can't import
+  // json.mjs here (it transitively loads styleText, the very thing this gate
+  // protects against), so emit a minimal hand-rolled envelope. The shape and
+  // the stable `code` (ERR_NODE_VERSION) match error-codes.mjs.
+  if (process.argv.slice(2).includes('--json')) {
+    console.log(
+      JSON.stringify(
+        {apiVersion: 1, error: msg, code: 'ERR_NODE_VERSION'},
+        null,
+        2,
+      ),
+    );
+  } else {
+    console.error(msg);
+  }
+  process.exit(1);
+}
+
+// Imports that transitively load `styleText` must happen AFTER the gate above,
+// so they are dynamically imported here rather than at the top of the module.
+const {program} = await importSrc('index.mjs');
+const {isJsonMode, toErrorEnvelope} = await importSrc('../../foundation/response/json.mjs');
+const {handleCommanderError} = await importSrc('lib/json-shim.mjs');
+
+/**
+ * Top-level error boundary (contract guarantee #4): an uncaught throw must
+ * never reach a --json consumer as a raw stack trace. If we're in JSON mode,
+ * convert it to the contract's error envelope on stdout and exit 1; otherwise
+ * preserve the normal human-facing behavior.
+ *
+ * We detect JSON mode two ways: the global flag (set once root options are
+ * parsed) and a raw argv check, since a throw can occur during parsing/command
+ * load — before the preAction hook engages the flag.
+ */
+function inJsonMode() {
+  return isJsonMode() || process.argv.slice(2).includes('--json');
+}
+
+/** @param {unknown} err */
+function handleFatal(err) {
+  // CommanderError (parse errors, --help, unknown command) routes
+  // through the JSON shim so that a --json consumer always gets a
+  // valid envelope and the right exit code. handleCommanderError
+  // calls process.exit when it owns the error.
+  if (handleCommanderError(err)) return;
+
+  if (inJsonMode()) {
+    // Only emit if a command didn't already produce an envelope.
+    if (!process.__xdsJsonHandled) {
+      process.__xdsJsonHandled = true;
+      console.log(JSON.stringify(toErrorEnvelope(err), null, 2));
+    }
+    process.exit(1);
+  }
+  // Human mode: preserve Commander/Node default-ish behavior.
+  console.error(err instanceof Error ? err.stack || err.message : String(err));
+  process.exit(1);
+}
+
+process.on('unhandledRejection', handleFatal);
+process.on('uncaughtException', handleFatal);
+
+try {
+  await program.parseAsync(process.argv);
+} catch (err) {
+  handleFatal(err);
+}