@astryxdesign/cli 0.0.0-bootstrap.0 → 0.1.0-canary.08d4cf4

package/src/types/base.d.ts

@@ -0,0 +1,164 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Shared types for the Astryx CLI JSON API.
+ *
+ * CLIError and CLIUnsupportedError are the two error shapes.
+ * CLIAnyResponse is the union of all success response types.
+ * CLIResult<T> wraps any response with possible errors.
+ */
+
+import type {
+  ComponentListResponse,
+  ComponentBriefResponse,
+  ComponentDetailResponse,
+  ComponentDetailPropsResponse,
+  ComponentDetailSourceResponse,
+  ComponentDetailShowcaseResponse,
+} from './component';
+import type {
+  DiscoverListResponse,
+  DiscoverDetailResponse,
+  DiscoverDetailDocResponse,
+  DiscoverSearchResponse,
+} from './discover';
+import type {
+  DocsListResponse,
+  DocsDetailResponse,
+  DocsDetailSectionResponse,
+} from './docs';
+import type {
+  TemplateListResponse,
+  TemplateShowResponse,
+  TemplateSkeletonResponse,
+  TemplateCopyResponse,
+  TemplateGetResponse,
+} from './template';
+import type {
+  HookListResponse,
+  HookBriefResponse,
+  HookFullResponse,
+  HookDetailResponse,
+  HookDetailParamsResponse,
+} from './hook';
+import type {SwizzleListResponse, SwizzleCopyResponse} from './swizzle';
+import type {ThemeBuildResponse} from './theme';
+import type {UpgradeListResponse, UpgradeRunResponse} from './upgrade';
+import type {
+  GapReportCategoriesResponse,
+  GapReportFileResponse,
+} from './gap-report';
+import type {SearchResponse} from './search';
+import type {ErrorCode} from './error-codes';
+import type {ManifestResponse} from './manifest';
+import type {DoctorResponse} from './doctor';
+
+/**
+ * Structured error. Check `'error' in result` to discriminate.
+ *
+ * Branch on `code` (a stable machine-readable identifier), never on the
+ * human-readable `error` string, which changes freely.
+ */
+export interface CLIError {
+  error: string;
+  code: ErrorCode;
+  suggestions?: Array<{name: string; reason: string}>;
+}
+
+/** Returned by the fallback hook for commands without --json support. */
+export interface CLIUnsupportedError {
+  error: `JSON output is not supported for the '${string}' command`;
+  code: ErrorCode;
+}
+
+/** Wrap any response type to include possible error shapes. */
+export type CLIResult<T> = T | CLIError | CLIUnsupportedError;
+
+/** Union of all possible success response types. */
+export type CLIAnyResponse =
+  | ComponentListResponse
+  | ComponentBriefResponse
+  | ComponentDetailResponse
+  | ComponentDetailPropsResponse
+  | ComponentDetailSourceResponse
+  | ComponentDetailShowcaseResponse
+  | DiscoverListResponse
+  | DiscoverDetailResponse
+  | DiscoverDetailDocResponse
+  | DiscoverSearchResponse
+  | DocsListResponse
+  | DocsDetailResponse
+  | DocsDetailSectionResponse
+  | TemplateListResponse
+  | TemplateShowResponse
+  | TemplateSkeletonResponse
+  | TemplateCopyResponse
+  | TemplateGetResponse
+  | HookListResponse
+  | HookBriefResponse
+  | HookFullResponse
+  | HookDetailResponse
+  | HookDetailParamsResponse
+  | SwizzleListResponse
+  | SwizzleCopyResponse
+  | ThemeBuildResponse
+  | UpgradeListResponse
+  | UpgradeRunResponse
+  | GapReportCategoriesResponse
+  | GapReportFileResponse
+  | SearchResponse
+  | ManifestResponse
+  | DoctorResponse;
+
+/** Union of all type discriminator string literals. */
+export type CLIResponseType = CLIAnyResponse['type'];
+
+/**
+ * Map from type discriminator to the data shape for that response.
+ * Used by jsonOut to enforce type-safe data payloads.
+ */
+export type CLIResponseDataMap = {
+  [R in CLIAnyResponse as R['type']]: R['data'];
+};
+
+/**
+ * Output a typed JSON response envelope. The data parameter is
+ * constrained to match the declared shape for the given type discriminator.
+ */
+export function jsonOut<T extends CLIResponseType>(
+  type: T,
+  data: CLIResponseDataMap[T],
+): void;
+
+/**
+ * Output a structured JSON error and exit.
+ */
+export function jsonError(
+  message: string,
+  suggestions?: Array<{name: string; reason: string}>,
+  code?: ErrorCode,
+): never;
+
+/** Parse raw CLI output (string or object) into typed result. */
+export function parseResponse(
+  raw: unknown,
+): CLIAnyResponse | CLIError | CLIUnsupportedError;
+
+/** Type guard: returns true if result is an error. */
+export function isError(
+  result: unknown,
+): result is CLIError | CLIUnsupportedError;
+
+/** Assert a specific response type. Throws on error or type mismatch. */
+export function assertResponse<T extends CLIResponseType>(
+  raw: unknown,
+  type: T,
+): Extract<CLIAnyResponse, {type: T}>;
+
+declare global {
+  namespace NodeJS {
+    interface Process {
+      __xdsJsonHandled?: boolean;
+    }
+  }
+}

package/src/types/component.d.ts

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Component command JSON responses.
+ *
+ * Detail-level contract for list views (brief < compact < full):
+ *   --detail brief    Names only. Smallest, most scannable. (DEFAULT for --list)
+ *   --detail compact  Names + 1-line description + import path.
+ *   --detail full     Full ComponentDoc per entry (props, theming, examples, etc.).
+ *
+ * Invocation                                 -> type discriminator
+ * ------------------------------------------------------------------
+ * xds --json component                      -> component.list
+ * xds --json component --list               -> component.list
+ * xds --json component --category Form      -> component.list (filtered)
+ * xds --json component --list --detail compact -> component.brief
+ * xds --json component --list --detail full -> component.full
+ * xds --json component Button               -> component.detail
+ * xds --json component Button --props       -> component.detail.props
+ * xds --json component Button --source      -> component.detail.source
+ * xds --json component Button --showcase    -> component.detail.showcase
+ * xds --json component Button --blocks      -> component.detail.blocks
+ * (not found)                               -> CLIError
+ */
+
+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[]>;
+}
+
+/** xds --json component --list --detail compact */
+export interface ComponentBriefResponse {
+  type: 'component.brief';
+  data: Record<string, ComponentBriefEntry[]>;
+}
+
+export interface ComponentBriefEntry {
+  name: string;
+  description: string;
+  import: string;
+}
+
+/** xds --json component --list --detail full */
+export interface ComponentFullResponse {
+  type: 'component.full';
+  data: Record<string, ComponentDoc[]>;
+}
+
+/** xds --json component <name> */
+export interface ComponentDetailResponse {
+  type: 'component.detail';
+  data: ComponentDoc;
+}
+
+/** xds --json component <name> --props */
+export interface ComponentDetailPropsResponse {
+  type: 'component.detail.props';
+  data: PropDoc[];
+}
+
+/** xds --json component <name> --source */
+export interface ComponentDetailSourceResponse {
+  type: 'component.detail.source';
+  data: {component: string; source: string};
+}
+
+/** xds --json component <name> --showcase */
+export interface ComponentDetailShowcaseResponse {
+  type: 'component.detail.showcase';
+  data: {component: string; aspectRatio: number; source: string};
+}
+
+/** xds --json component <name> --blocks */
+export interface ComponentDetailBlocksResponse {
+  type: 'component.detail.blocks';
+  data: {
+    component: string;
+    showcase: BlockEntry | null;
+    examples: BlockEntry[];
+    related: BlockEntry[];
+  };
+}
+
+export interface BlockEntry {
+  name: string;
+  displayName: string;
+  description: string;
+  isShowcase: boolean;
+  category: string;
+}

package/src/types/discover.d.ts

@@ -0,0 +1,59 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Discover command JSON responses.
+ *
+ * Invocation                                      -> type discriminator
+ * ------------------------------------------------------------------
+ * xds --json discover                            -> discover.list
+ * xds --json discover @scope/name                -> discover.detail
+ * xds --json discover @scope/name/Component      -> discover.detail.doc
+ * xds --json discover <searchterm> (1 match)     -> discover.detail.doc
+ * xds --json discover <searchterm> (N matches)   -> discover.search
+ * (not found)                                    -> CLIError
+ */
+
+import type {ComponentDoc} from '../../../core/src/docs-types';
+
+/** xds --json discover */
+export interface DiscoverListResponse {
+  type: 'discover.list';
+  data: DiscoverListEntry[];
+  /**
+   * Present when the list is empty so callers can distinguish "no packages
+   * configured" from "configured but nothing discovered".
+   */
+  meta?: {configured: boolean};
+}
+
+export interface DiscoverListEntry {
+  name: string;
+  category: string;
+  components: string[];
+  version?: string;
+  description?: string;
+  displayName?: string;
+}
+
+/** xds --json discover @scope/name */
+export interface DiscoverDetailResponse {
+  type: 'discover.detail';
+  data: DiscoverListEntry;
+}
+
+/** xds --json discover @scope/name/Component */
+export interface DiscoverDetailDocResponse {
+  type: 'discover.detail.doc';
+  data: ComponentDoc;
+}
+
+/** xds --json discover <searchterm> (multiple matches) */
+export interface DiscoverSearchResponse {
+  type: 'discover.search';
+  data: {query: string; matches: DiscoverSearchEntry[]};
+}
+
+export interface DiscoverSearchEntry {
+  package: string;
+  component: string;
+}

package/src/types/docs.d.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Docs command JSON responses.
+ *
+ * Invocation                                 -> type discriminator
+ * ------------------------------------------------------------------
+ * xds --json docs                           -> docs.list
+ * xds --json docs <topic>                   -> docs.detail
+ * xds --json docs <topic> <section>         -> docs.detail.section
+ * (unknown topic/section)                   -> CLIError
+ */
+
+import type {
+  ReferenceDoc,
+  ReferenceSection,
+} from '../../../core/src/docs-types';
+
+/** xds --json docs */
+export interface DocsListResponse {
+  type: 'docs.list';
+  data: DocsListEntry[];
+}
+
+export interface DocsListEntry {
+  topic: string;
+  description: string;
+}
+
+/** xds --json docs <topic> */
+export interface DocsDetailResponse {
+  type: 'docs.detail';
+  data: ReferenceDoc;
+}
+
+/** xds --json docs <topic> <section> */
+export interface DocsDetailSectionResponse {
+  type: 'docs.detail.section';
+  data: ReferenceSection;
+}

package/src/types/doctor.d.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Doctor command JSON responses.
+ *
+ * Invocation                  -> type discriminator
+ * --------------------------------------------------
+ * xds --json doctor           -> doctor
+ */
+
+/** Outcome of a single diagnostic check. */
+export type DoctorStatus = 'pass' | 'warn' | 'fail' | 'info';
+
+/** A single diagnostic check result. */
+export interface DoctorCheck {
+  /** Stable machine-readable id (e.g. 'node-version'). */
+  id: string;
+  /** Human-readable check name. */
+  label: string;
+  status: DoctorStatus;
+  /** One-line result summary. */
+  message: string;
+  /** Actionable remediation, present when status is not 'pass'. */
+  fix?: string;
+}
+
+/** Aggregate counts per status. */
+export interface DoctorSummary {
+  pass: number;
+  warn: number;
+  fail: number;
+  info: number;
+}
+
+/** xds --json doctor */
+export interface DoctorResponse {
+  type: 'doctor';
+  data: {
+    checks: DoctorCheck[];
+    summary: DoctorSummary;
+  };
+}

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

@@ -0,0 +1,59 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Stable, machine-readable error codes carried on every CLI error envelope
+ * and every thrown AstryxError. Consumers should branch on these — never on the
+ * human-readable `error` string, which can change at any time.
+ *
+ * Append-only: a code's meaning never changes and codes are never removed.
+ * See packages/cli/README.md for the documented contract and meanings.
+ */
+export type ErrorCode =
+  | 'ERR_UNKNOWN'
+  | 'ERR_UNKNOWN_COMMAND'
+  | 'ERR_UNKNOWN_SUBCOMMAND'
+  | 'ERR_INVALID_OPTION'
+  | 'ERR_INVALID_ARGUMENT'
+  | 'ERR_MISSING_ARGUMENT'
+  | 'ERR_INVALID_LANG'
+  | 'ERR_INVALID_DETAIL'
+  | 'ERR_NODE_VERSION'
+  | 'ERR_CORE_NOT_FOUND'
+  | 'ERR_UNKNOWN_COMPONENT'
+  | 'ERR_UNKNOWN_HOOK'
+  | 'ERR_UNKNOWN_TOPIC'
+  | 'ERR_UNKNOWN_SECTION'
+  | 'ERR_UNKNOWN_CATEGORY'
+  | 'ERR_UNKNOWN_TEMPLATE'
+  | 'ERR_UNKNOWN_PACKAGE'
+  | 'ERR_UNKNOWN_AGENT'
+  | 'ERR_UNKNOWN_FEATURE'
+  | 'ERR_UNKNOWN_CODEMOD'
+  | 'ERR_CODEMOD_FAILED'
+  | 'ERR_NOT_FOUND'
+  | 'ERR_NO_DOC'
+  | 'ERR_NO_SHOWCASE'
+  | 'ERR_NO_SOURCE'
+  | 'ERR_INVALID_DOC'
+  | 'ERR_FILE_NOT_FOUND'
+  | 'ERR_FILE_EXISTS'
+  | 'ERR_PATH_TRAVERSAL'
+  | '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';
+
+/** The frozen runtime map of all error codes (keys === values). */
+export declare const ERROR_CODES: Readonly<Record<ErrorCode, ErrorCode>>;
+
+/** Type guard: is `value` a known error code? */
+export declare function isErrorCode(value: unknown): value is ErrorCode;
+
+/** All error code string values, sorted. */
+export declare function allErrorCodes(): ErrorCode[];

package/src/types/gap-report.d.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Gap-report command JSON responses.
+ *
+ * Invocation                                               -> type discriminator
+ * ------------------------------------------------------------------
+ * xds --json gap-report --list-categories                 -> gap-report.categories
+ * xds --json gap-report --component X --category Y --reason Z -> gap-report.file
+ * (invalid category)                                      -> CLIError
+ * (interactive mode)                                      -> CLIUnsupportedError (fallback)
+ */
+
+/** xds --json gap-report --list-categories */
+export interface GapReportCategoriesResponse {
+  type: 'gap-report.categories';
+  data: GapReportCategoryEntry[];
+}
+
+export interface GapReportCategoryEntry {
+  value: string;
+  label: string;
+}
+
+/** xds --json gap-report --component X --category Y --reason Z */
+export interface GapReportFileResponse {
+  type: 'gap-report.file';
+  data: {filed: boolean; url: string | null};
+}

package/src/types/hook.d.ts

@@ -0,0 +1,59 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Hook command JSON responses.
+ *
+ * Detail-level contract for list views (brief < compact < full):
+ *   --detail brief    Names only. Smallest, most scannable. (DEFAULT for --list)
+ *   --detail compact  Names + 1-line description + import path.
+ *   --detail full     Full HookDoc per entry (params, returns, usage, etc.).
+ *
+ * Invocation                                 -> type discriminator
+ * ------------------------------------------------------------------
+ * xds --json hook                           -> hook.list
+ * xds --json hook --list                    -> hook.list
+ * xds --json hook --category State          -> hook.list (filtered)
+ * xds --json hook --list --detail compact   -> hook.brief
+ * xds --json hook --list --detail full      -> hook.full
+ * xds --json hook useMediaQuery             -> hook.detail
+ * xds --json hook useMediaQuery --params    -> hook.detail.params
+ * (not found)                               -> CLIError
+ */
+
+import type {HookDoc, HookParamDoc} from '../../../core/src/docs-types';
+
+/** xds --json hook [--list] [--category X] [--detail brief] */
+export interface HookListResponse {
+  type: 'hook.list';
+  data: Record<string, string[]>;
+}
+
+/** xds --json hook --list --detail compact */
+export interface HookBriefResponse {
+  type: 'hook.brief';
+  data: Record<string, HookBriefEntry[]>;
+}
+
+export interface HookBriefEntry {
+  name: string;
+  description: string;
+  import: string;
+}
+
+/** xds --json hook --list --detail full */
+export interface HookFullResponse {
+  type: 'hook.full';
+  data: Record<string, HookDoc[]>;
+}
+
+/** xds --json hook <name> */
+export interface HookDetailResponse {
+  type: 'hook.detail';
+  data: HookDoc;
+}
+
+/** xds --json hook <name> --params */
+export interface HookDetailParamsResponse {
+  type: 'hook.detail.params';
+  data: HookParamDoc[];
+}

package/src/types/index.d.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+export * from './base';
+export * from './component';
+export * from './discover';
+export * from './docs';
+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';
+export * from './manifest';
+export * from './doctor';

package/src/types/manifest.d.ts

@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Types for the CLI capability manifest emitted by `astryx manifest --json`
+ * (and embedded under `data.manifest` of the bare `xds --json` help envelope).
+ *
+ * The manifest is a self-describing view of the entire CLI surface so an agent
+ * can discover every command, argument, flag, and response type in one call —
+ * without scraping `--help`. Most of it is derived from Commander metadata; see
+ * lib/manifest.mjs.
+ */
+
+/** A single command-line flag/option. */
+export interface ManifestOption {
+  /** Raw Commander flag spec, e.g. `--detail <level>` or `-o, --out <path>`. */
+  flag: string;
+  description: string;
+  /** `boolean` for flags, `string` for value options, `enum` when choices exist. */
+  type: 'boolean' | 'string' | 'enum';
+  /** Allowed values when `type` is `enum`. */
+  choices?: string[];
+  /** Default value, if any. */
+  default?: unknown;
+  /** True for `--no-foo` style negation flags. */
+  negate?: boolean;
+}
+
+/** A positional argument. */
+export interface ManifestArgument {
+  name: string;
+  required: boolean;
+  variadic: boolean;
+  description: string;
+}
+
+/** A single command (possibly with subcommands). */
+export interface ManifestCommand {
+  /** Fully-qualified name, e.g. `theme build`. */
+  name: string;
+  description: string;
+  arguments: ManifestArgument[];
+  options: ManifestOption[];
+  /** Whether this command supports `--json` (from the JSON_SUPPORTED allowlist). */
+  json: boolean;
+  /** Command aliases, if any. */
+  aliases?: string[];
+  /** Response `type` discriminators this command can emit in `--json` mode. */
+  responseTypes?: string[];
+  /** Example invocations. */
+  examples?: string[];
+  /** Nested subcommands (e.g. `theme build` under `theme`). */
+  subcommands?: ManifestCommand[];
+}
+
+/** The full manifest payload (the `data` of the `manifest` envelope). */
+export interface CLIManifest {
+  name: 'astryx';
+  version: string;
+  apiVersion: number;
+  description: string;
+  globalOptions: ManifestOption[];
+  commands: ManifestCommand[];
+  /** Sorted list of fully-qualified command names that support `--json`. */
+  jsonSupported: string[];
+  /** Flat index of response `type` discriminators keyed by command name. */
+  responseTypes: Record<string, string[]>;
+}
+
+/** The `astryx manifest --json` envelope. */
+export interface ManifestResponse {
+  type: 'manifest';
+  data: CLIManifest;
+}

package/src/types/search.d.ts

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Search command JSON responses.
+ *
+ * `astryx search <query>` returns a single ranked, typed result set spanning all
+ * content domains — components, hooks, docs topics, and templates. Scoring is
+ * keyword + fuzzy ranking (not semantic / embeddings).
+ *
+ * Invocation                                     -> type discriminator
+ * ------------------------------------------------------------------
+ * xds --json search button                       -> search
+ * xds --json search modal --type component       -> search (filtered)
+ * xds --json search forms --limit 5              -> search (capped)
+ * xds --json search zzznomatch                   -> search (empty results, exit 0)
+ * (no query)                                     -> CLIError
+ */
+
+/** The domain a search result belongs to. */
+export type SearchDomain = 'component' | 'hook' | 'doc' | 'template';
+
+/** A single ranked search result, tagged with its domain. */
+export interface SearchResultEntry {
+  /** Which content domain this result came from. */
+  domain: SearchDomain;
+  /** Primary identifier (component/hook name, doc topic, template dir). */
+  name: string;
+  /** Relevance score (higher is better). */
+  score: number;
+  /** Human-readable reason the candidate matched (e.g. `keyword "button"`). */
+  reason: string;
+  /** One-line description, when available. */
+  description: string;
+  /** Follow-up command to act on this result (e.g. `astryx component Button`). */
+  command: string;
+  /** Import path — present for component and hook results. */
+  import?: string;
+  /** Doc title — present for doc results. */
+  title?: string;
+  /** Friendly display name — present for template results. */
+  displayName?: string;
+  /** Template kind (`page` | `block`) — present for template results. */
+  kind?: 'page' | 'block';
+}
+
+/** xds --json search <query> */
+export interface SearchResponse {
+  type: 'search';
+  data: {
+    query: string;
+    results: SearchResultEntry[];
+  };
+}