@astryxdesign/cli 0.1.2 → 0.1.3

package/src/types/component.d.ts

@@ -28,7 +28,18 @@ import type {ComponentDoc, PropDoc} from '../../../core/src/docs-types';
 /** xds --json component [--list] [--category X] [--detail brief] */
 export interface ComponentListResponse {
   type: 'component.list';
-  data: Record<string, string[]>;
+  data: Record<string, ComponentListEntry[]>;
+}
+
+/**
+ * A single entry in a `component.list` group. Pre-1.0 the list moved from bare
+ * strings to package-qualified objects so consumers can disambiguate ownership
+ * (core vs. an integration package).
+ */
+export interface ComponentListEntry {
+  name: string;
+  /** Owner package, e.g. '@astryxdesign/core' or '@acme/astryx-meta'. */
+  package: string;
 }
 
 /** xds --json component --list --detail compact */
@@ -52,7 +63,21 @@ export interface ComponentFullResponse {
 /** xds --json component <name> */
 export interface ComponentDetailResponse {
   type: 'component.detail';
-  data: ComponentDoc;
+  data: ComponentDoc & ComponentOwnership;
+}
+
+/**
+ * Ownership metadata attached to every `component.detail` payload. Exposes the
+ * owner package, the import specifier, and whether a swizzleable source file is
+ * available — the inputs the integration-component swizzle (a later PR) needs.
+ */
+export interface ComponentOwnership {
+  /** Owner package, e.g. '@astryxdesign/core' or an integration package name. */
+  package: string;
+  /** Import specifier for the component (e.g. '@astryxdesign/core/Button'). */
+  import: string;
+  /** Whether a component source file exists for `--source` / swizzle. */
+  sourceAvailable: boolean;
 }
 
 /** xds --json component <name> --props */

package/src/types/config.d.ts

@@ -1,99 +1,70 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** User config exported from astryx.config.mjs. */
-export interface AstryxConfig {
-  /** External package directories to scan for package.json astryx.docs metadata. */
-  packages?: string | string[];
-  /** Integration package names or manifest paths. */
-  integrations?: string | string[];
-  /** Gap report delivery override. Omit for default GitHub issue filing. */
-  gapReport?: false | {command: string};
-  /** Template hooks. */
-  template?: {
-    get?: (id: string) => string | Promise<string>;
+/**
+ * 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 interface PostCodemodCommand {
+  command: string;
+  args?: string[];
+  options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeout?: number;
   };
-  [key: string]: unknown;
-}
-
-export interface AstryxIntegrationCodemod {
-  name: string;
-  from?: string;
-  to?: string;
-  title?: string;
-  description?: string;
-  pr?: string;
-  optional?: boolean;
-  fileExtensions?: string[];
-  transform:
-    | string
-    | ((file: unknown, api: unknown) => string | undefined | null);
-}
-
-export interface AstryxPostCodemodContext {
-  packageDir: string;
-  codemodDir: string;
-  changedFiles: string[];
-  absoluteChangedFiles: string[];
-  packageChangedFiles: string[];
-  apply: boolean;
-  run: (
-    command: string,
-    args?: string[],
-    options?: {
-      cwd?: string;
-      timeoutMs?: number;
-      env?: Record<string, string>;
-    },
-  ) => Promise<void>;
 }
 
-export interface AstryxPostCodemodHook {
+/**
+ * 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;
-  run?: (context: AstryxPostCodemodContext) => void | Promise<void>;
-  command?: (context: AstryxPostCodemodContext) =>
-    | {
-        command: string;
-        args?: string[];
-        cwd?: string;
-        timeoutMs?: number;
-        env?: Record<string, string>;
-      }
+  buildCommand: (ctx: {
+    packageDir: string;
+    files: string[];
+  }) =>
+    | PostCodemodCommand
     | null
     | undefined
-    | Promise<
-        | {
-            command: string;
-            args?: string[];
-            cwd?: string;
-            timeoutMs?: number;
-            env?: Record<string, string>;
-          }
-        | null
-        | undefined
-      >;
-}
+    | Promise<PostCodemodCommand | null | undefined>;
+};
 
-/** Integration manifest exported from an astryx.integration.mjs file. */
-export interface AstryxIntegration {
-  name: string;
-  version?: string;
-  displayName?: string;
+/** 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;
-  /** Relative docs root containing *.doc.mjs files. */
-  docs?: string;
-  category?: string;
-  /** Relative block-template root. */
-  blocks?: string;
-  gapReport?: false | {command: string};
-  template?: {
-    get?: string | ((id: string) => string | Promise<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>;
+    };
   };
-  codemods?: AstryxIntegrationCodemod[];
-  postCodemod?: AstryxPostCodemodHook[];
-  [key: string]: unknown;
 }
 
 export declare function createConfig<T extends AstryxConfig>(config: T): T;
-export declare function createIntegration<T extends AstryxIntegration>(
-  integration: T,
-): T;

package/src/types/error-codes.d.ts

@@ -25,6 +25,9 @@ export type ErrorCode =
   | 'ERR_UNKNOWN_SECTION'
   | 'ERR_UNKNOWN_CATEGORY'
   | 'ERR_UNKNOWN_TEMPLATE'
+  | 'ERR_AMBIGUOUS_TEMPLATE'
+  | 'ERR_AMBIGUOUS_COMPONENT'
+  | 'ERR_UNKNOWN_THEME'
   | 'ERR_UNKNOWN_PACKAGE'
   | 'ERR_UNKNOWN_AGENT'
   | 'ERR_UNKNOWN_FEATURE'
@@ -41,13 +44,12 @@ export type ErrorCode =
   | 'ERR_WRITE_FAILED'
   | 'ERR_THEME_INVALID'
   | 'ERR_THEME_LOAD'
-  | 'ERR_TEMPLATE_CONFIG'
-  | 'ERR_TEMPLATE_GET'
   | 'ERR_VERSION_DETECT'
   | 'ERR_INVALID_VERSION'
   | 'ERR_DEP_MISSING'
   | 'ERR_GH_CLI'
-  | 'ERR_GAP_REPORT_FAILED';
+  | 'ERR_LAYOUT_PARSE'
+  | 'ERR_LAYOUT_INVALID';
 
 /** The frozen runtime map of all error codes (keys === values). */
 export declare const ERROR_CODES: Readonly<Record<ErrorCode, ErrorCode>>;

package/src/types/index.d.ts

@@ -8,7 +8,6 @@ export * from './template';
 export * from './hook';
 export * from './swizzle';
 export * from './theme';
-export * from './gap-report';
 export * from './upgrade';
 export * from './search';
 export * from './error-codes';

package/src/types/integration.d.ts

@@ -0,0 +1,29 @@
+// 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.
+ */
+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 {
+  code: string;
+  severity: 'warning' | 'error';
+  message: string;
+}
+
+export declare function createIntegration<T extends AstryxIntegration>(
+  integration: T,
+): T;

package/src/types/swizzle.d.ts

@@ -7,7 +7,6 @@
  * ------------------------------------------------------------------
  * xds --json swizzle [--list]               -> swizzle.list
  * xds --json swizzle <component>            -> swizzle.copy
- * xds --json swizzle <component> --gap "x"  -> swizzle.copy (with gapReport)
  * (not found)                               -> CLIError
  */
 
@@ -17,6 +16,14 @@ export interface SwizzleListResponse {
   data: string[];
 }
 
+/** Maintainer feedback note emitted after a successful swizzle. */
+export interface SwizzleFeedback {
+  /** Where to report the gap that led to swizzling. */
+  issuesUrl: string;
+  /** Ready-to-run `gh issue create` command, when `gh` is available. */
+  ghCommand?: string;
+}
+
 /** xds --json swizzle <component> */
 export interface SwizzleCopyResponse {
   type: 'swizzle.copy';
@@ -25,6 +32,6 @@ export interface SwizzleCopyResponse {
     outputDir: string;
     filesCopied: number;
     files: string[];
-    gapReport?: string | null;
+    feedback?: SwizzleFeedback;
   };
 }

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

@@ -0,0 +1,54 @@
+// 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.
+ */
+
+/** 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'};

package/src/types/template.d.ts

@@ -21,12 +21,21 @@ export interface TemplateListResponse {
 }
 
 export interface TemplateListEntry {
+  /** Stable template id (relative path under the templates root, minus the .doc.* suffix). */
+  id: string;
   name: string;
+  /** @deprecated Alias of `name`, retained for back-compat. */
   displayName: string;
   description: string;
+  type: 'page' | 'block';
+  /** Owning package; core (built-in) templates report '@astryxdesign/core'. */
+  package: string;
+  /** Optional grouping/category label. */
+  category?: string;
+  /** Component display names the template composes. */
+  componentsUsed?: string[];
   isReady: boolean;
   scaffold?: boolean;
-  type: 'page' | 'block';
 }
 
 /** xds --json template <name> */
@@ -62,9 +71,3 @@ export interface TemplateCopyResponse {
     filesCopied: number;
   };
 }
-
-/** xds --json template get --id <id> */
-export interface TemplateGetResponse {
-  type: 'template.get';
-  data: {id: string; source: string};
-}

package/src/types/upgrade.d.ts

@@ -7,6 +7,7 @@
  * ------------------------------------------------------------------
  * xds --json upgrade --list                 -> upgrade.list
  * xds --json upgrade [--apply]              -> upgrade.run
+ * xds --json upgrade (status short-circuit) -> upgrade.status
  * (version detection failure)               -> CLIError
  */
 
@@ -33,3 +34,31 @@ export interface UpgradeRunResponse {
     agentDocsRefreshed: boolean;
   };
 }
+
+/**
+ * xds --json upgrade — short-circuit status results.
+ *
+ * - `up_to_date`: `--from` is >= installed target and `--force` was not passed.
+ * - `no_codemods`: no codemods (core or integration) apply to the range.
+ * - `config_fixable`: DRY-RUN ONLY. The consumer's astryx.config currently
+ *   fails strict validation, but a pending core CONFIG codemod (in the selected
+ *   range) would repair it. The dry run previews the fix without writing and
+ *   reports the exact command to apply it; integrations are skipped for the
+ *   preview (they will be processed on the `--apply` run).
+ */
+export interface UpgradeStatusResponse {
+  type: 'upgrade.status';
+  data:
+    | {status: 'up_to_date'; from: string; to: string}
+    | {status: 'no_codemods'; from: string; to: string}
+    | {
+        status: 'config_fixable';
+        from: string;
+        to: string;
+        configError: string;
+        configCodemods: string[];
+        suggestedCommand: string;
+        message: string;
+        note: string;
+      };
+}

package/src/types/validate-integration.d.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * validate-integration command JSON responses.
+ *
+ * Invocation                              -> type discriminator
+ * ------------------------------------------------------------
+ * astryx --json validate-integration       -> integration.validate
+ * astryx --json validate-integration <pkg> -> integration.validate
+ */
+
+import type {AstryxIntegrationIssue} from './integration';
+
+/** astryx --json validate-integration [package] */
+export interface ValidateIntegrationResponse {
+  type: 'integration.validate';
+  data: {
+    /** Integration package name, or null when no manifest was located. */
+    name: string | null;
+    /** Integration package version, or null when unavailable. */
+    version: string | null;
+    issues: AstryxIntegrationIssue[];
+  };
+}