@astryxdesign/cli 0.1.8-canary.08a0957 → 0.1.8-canary.0db5dfd

package/templates/blocks/components/Thumbnail/ThumbnailElevated.tsx

@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Thumbnail} from '@astryxdesign/core/Thumbnail';
+import {Stack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+// Demo imagery is inlined as same-origin data URIs so the example is
+// self-contained. Thumbnail's remove-button overlay uses useImageMode, which
+// FETCHES the image to sample pixels (APCA) for contrast — a cross-origin CDN
+// URL without CORS headers cannot be sampled, so contrast detection fails
+// silently in hosted previews.
+const NIGHT_FOREST =
+  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAMAAACdt4HsAAAAwFBMVEX18+H08uDy8d/y8N/v7t/m5NXl49Tk4tPc3NDX1cnW1cnW1cjW1MjV1MjV1MfR0cXIyLzEw7m8vLC3t68wM0QvM0MvM0IvMkIuMkEtMEErLz8iJjkhJTggJTcgJDcfJDYfIzYeIjUcITMbHzIWHiwYGzIXGjEWGjAWGTAVGS8VGC8UGC4UGC0UFy4TFy0TFywTFi0SFiwRFSsQFSkNFR4QFCoPFCkPFCgPEykOEygOEigNEicNEScMESYIDw8ECgr+gzZIAAABqElEQVR42uWQ61aCQBRGD5GylNBMKS9FZgNdNE0cyUvB+79VM8MoF9Fgplau2j/8nO8c9hqAD0ngDwjeJYH1lrfBWoCtYDboNu/Zv7qQYNap1bpCN1gxFh1dNe5WAsCScWqoWttbChAKvHZZ0W6XQoIFpW8ooFmLCG2Rl1BgaZAU5Ac8yg0RlC9nngCRQDFuhQRzinWmkCuYk3lxQoFrlskVqlcTMcEFvYIKoFbNfmEFuIypWaGGkt66tqZuEbjAHZl6SQVF1WqNvpDAHVktXTvR9JbgDZii1+tZI7cYMJXkCASvksB4L5VxHmAsibzgRRIYbjgfCgFDSeBZkh8W1HMIniSBR0mOQPCQA3RgBk4M5DhNZwdEcbKgLXy5iDiZg5gApRYbqTql2FZgMxAKeEWSNUFYx3s2SfU28HPWItrpySSwE2cEdqrYtxgmxgHGScFmHrAGk8SxczIxZnNC1McFOGshShyb4yxB9sI3CXDGnH0MLsD7F5LvvptEgH12Zg1Pn2WuHsjvrwt8308t+nwxT38sgiAE8/RTeagH+vx/F8SeF0Ja8Ak14ia/LgmpZQAAAABJRU5ErkJggg==';
+const GOLDEN_SUNSET =
+  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAMAAACdt4HsAAAAkFBMVEX/+uv/7sj6tFr3sVn1r1nzrVjxq1jvqVftp1frpVbpo1bnoVXln1XjnVThm1TfmVPdl1PblVLZk1LXkVLVj1HTjVHRi1DPiVDNh0/LhU/Jg07HgU7Ff03DfU3Be0y/eUy9d0u7dUu5c0u2cEq0bkqybEmwakmuaEisZkiqZEeoYkemYEakXkaiXEVgLjQ8HCjaJlMkAAABI0lEQVR42u3Mx3qDMBSE0Z/03nsvdhxjcnn/twsYjISR5MUkO5+V9N2ZYUPEpogtEdsidkTsitgTsS/iQMShiCMRxyJORJyKOBNxLuJCxKWIKxHXIm5E3Iq4E3Ev4kHEo4gnEc8iXkS8inhLymrJBO8J2UIiw0dc5sRDfEbVRWr1o/pbMMWox9yz6zcLIzMbBTD2VaHu7fr1gjXGA3w5baj5+H0w6x09TDpdaP7rDZhn0sd3y89Y9fcHbPnoYdroZ2w6dQNmg6OHfG4QyrsBC8gdZpVQxtqF4M1mjepFURThTLNgMYsePxaX2WqY6D8GSm2grK2slbGBciHZ9hOE2smNpTuxenhieCdeH06E7qTqvYnImWTbbUSPlKL1wHrgTwZ+AWq+3H5MpRkwAAAAAElFTkSuQmCC';
+
+export default function ThumbnailElevated() {
+  return (
+    <Stack direction="vertical" gap={3}>
+      <Text type="supporting" color="secondary">
+        Raised tiles — `elevation` lifts an image off the page at rest
+      </Text>
+      <Stack direction="horizontal" gap={3} vAlign="center">
+        <Thumbnail src={NIGHT_FOREST} alt="Forest at night" elevation="low" />
+        <Thumbnail src={GOLDEN_SUNSET} alt="Golden sunset" elevation="high" />
+      </Stack>
+    </Stack>
+  );
+}

package/{src/types → types}/api.contract.assert.ts

@@ -31,14 +31,14 @@
  */
 
 import type * as Api from './api';
-import type {component} from '../api/component.mjs';
-import type {docs} from '../api/docs.mjs';
-import type {discover} from '../api/discover.mjs';
-import type {template} from '../api/template.mjs';
+import type {component} from '../api/component/component.mjs';
+import type {docs} from '../api/docs/docs.mjs';
+import type {discover} from '../api/discover/discover.mjs';
+import type {template} from '../api/template/template.mjs';
 
 /** Resolve to `true` only when `A` and `B` are mutually assignable. */
 type Equal<A, B> =
-  (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2)
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
     ? true
     : false;
 
@@ -52,16 +52,25 @@ type Opt<T> = NonNullable<T>;
 // must describe the same set of keys/types, in both directions. ──────────────
 
 type _ComponentOptions = Expect<
-  Equal<Opt<Parameters<typeof Api.component>[1]>, Opt<Parameters<typeof component>[1]>>
+  Equal<
+    Opt<Parameters<typeof Api.component>[1]>,
+    Opt<Parameters<typeof component>[1]>
+  >
 >;
 type _DocsOptions = Expect<
   Equal<Opt<Parameters<typeof Api.docs>[2]>, Opt<Parameters<typeof docs>[2]>>
 >;
 type _DiscoverOptions = Expect<
-  Equal<Opt<Parameters<typeof Api.discover>[1]>, Opt<Parameters<typeof discover>[1]>>
+  Equal<
+    Opt<Parameters<typeof Api.discover>[1]>,
+    Opt<Parameters<typeof discover>[1]>
+  >
 >;
 type _TemplateOptions = Expect<
-  Equal<Opt<Parameters<typeof Api.template>[1]>, Opt<Parameters<typeof template>[1]>>
+  Equal<
+    Opt<Parameters<typeof Api.template>[1]>,
+    Opt<Parameters<typeof template>[1]>
+  >
 >;
 
 // ── Positional-argument parity: arity and positional types must match. ───────

package/{src/types → types}/api.d.ts

@@ -44,17 +44,24 @@ import type {
 import type {SearchResponse, SearchDomain} from './search';
 import type {ErrorCode} from './error-codes';
 import type {DoctorResponse} from './doctor';
+import type {
+  LayoutForm,
+  LayoutExpandResponse,
+  LayoutCheckResponse,
+  LayoutGrammarResponse,
+} from './layout';
+import type {ValidateIntegrationResponse} from './validate-integration';
+import type {AstryxIntegrationIssue} from './integration';
+import type {BuildHelpResponse, BuildKitResponse} from './build';
+import type {SwizzleListResponse, SwizzleCopyResponse} from './swizzle';
+import type {Suggestion} from './base';
 
 /** Structured API error with a stable machine-readable code. */
 export declare class AstryxError extends Error {
   /** Stable error code; consumers branch on this, never the message. */
   code: ErrorCode;
-  suggestions?: Array<{name: string; reason: string}>;
-  constructor(
-    message: string,
-    suggestions?: Array<{name: string; reason: string}>,
-    code?: ErrorCode,
-  );
+  suggestions?: Suggestion[];
+  constructor(message: string, suggestions?: Suggestion[], code?: ErrorCode);
 }
 
 // ── Component ────────────────────────────────────────────────────────
@@ -100,9 +107,7 @@ export interface DocsOptions {
 }
 
 type DocsResult =
-  | DocsListResponse
-  | DocsDetailResponse
-  | DocsDetailSectionResponse;
+  DocsListResponse | DocsDetailResponse | DocsDetailSectionResponse;
 
 export declare function docs(
   topic?: string,
@@ -191,6 +196,47 @@ export declare function search(
   options?: SearchOptions,
 ): Promise<SearchResponse>;
 
+// ── Build ────────────────────────────────────────────────────────────
+
+export interface BuildOptions {
+  cwd?: string;
+  type?: SearchDomain;
+  limit?: number;
+}
+
+/**
+ * Page-building assistant. No query → `build.help` (playbook signal); a query →
+ * `build.kit` (grouped composition kit of raw search entries + frame/foundation).
+ */
+export declare function build(
+  query?: string,
+  options?: BuildOptions,
+): Promise<BuildHelpResponse | BuildKitResponse>;
+
+// ── Swizzle ──────────────────────────────────────────────────────────
+
+export interface SwizzleOptions {
+  cwd?: string;
+  /** Output directory (must resolve inside cwd). Defaults to ./components/astryx. */
+  output?: string;
+  /** Scope to a specific owning package when a name is ambiguous. */
+  package?: string;
+  /** Force the list response even with a component argument. */
+  list?: boolean;
+  /** Overwrite existing files instead of erroring. */
+  overwrite?: boolean;
+}
+
+/**
+ * List swizzlable components (no name / `list`) or copy one component's source
+ * into the project (side effect) and return a `swizzle.copy` receipt. Errors
+ * throw AstryxError (ERR_UNKNOWN_COMPONENT, ERR_AMBIGUOUS_COMPONENT, …).
+ */
+export declare function swizzle(
+  component?: string,
+  options?: SwizzleOptions,
+): Promise<SwizzleListResponse | SwizzleCopyResponse>;
+
 // ── Doctor ──────────────────────────────────
 
 export interface DoctorOptions {
@@ -200,3 +246,58 @@ export interface DoctorOptions {
 export declare function doctor(
   options?: DoctorOptions,
 ): Promise<DoctorResponse>;
+
+// ── Layout ───────────────────────────────────────────────────────────
+
+export interface LayoutExpandOptions {
+  targetPath?: string;
+  form?: LayoutForm;
+  loose?: boolean;
+  name?: string;
+  cwd?: string;
+}
+
+export declare function layoutExpand(
+  expression: string,
+  options?: LayoutExpandOptions,
+): Promise<LayoutExpandResponse>;
+
+export interface LayoutCheckOptions {
+  form?: LayoutForm;
+  loose?: boolean;
+  cwd?: string;
+}
+
+export declare function layoutCheck(
+  expression: string,
+  options?: LayoutCheckOptions,
+): Promise<LayoutCheckResponse>;
+
+export interface LayoutGrammarOptions {
+  cwd?: string;
+}
+
+export declare function layoutGrammar(
+  options?: LayoutGrammarOptions,
+): Promise<LayoutGrammarResponse>;
+
+// ── Validate integration ─────────────────────────────────────────────
+
+export interface ValidateIntegrationOptions {
+  cwd?: string;
+}
+
+/**
+ * Validate the local integration (no `pkg`) or an installed one (`pkg` given).
+ * The no-manifest local case returns `{ name: null, version: null, issues: [] }`.
+ */
+export declare function validateIntegration(
+  pkg?: string,
+  options?: ValidateIntegrationOptions,
+): Promise<ValidateIntegrationResponse>;
+
+/** Count issues by severity. */
+export declare function summarizeIssues(issues: AstryxIntegrationIssue[]): {
+  errors: number;
+  warnings: number;
+};

package/{src/types → types}/base.d.ts

@@ -11,10 +11,12 @@
 import type {
   ComponentListResponse,
   ComponentBriefResponse,
+  ComponentFullResponse,
   ComponentDetailResponse,
   ComponentDetailPropsResponse,
   ComponentDetailSourceResponse,
   ComponentDetailShowcaseResponse,
+  ComponentDetailBlocksResponse,
 } from './component';
 import type {
   DiscoverListResponse,
@@ -41,14 +43,38 @@ import type {
   HookDetailParamsResponse,
 } from './hook';
 import type {SwizzleListResponse, SwizzleCopyResponse} from './swizzle';
-import type {ThemeBuildResponse} from './theme';
-import type {UpgradeListResponse, UpgradeRunResponse} from './upgrade';
+import type {
+  ThemeBuildResponse,
+  ThemeListResponse,
+  ThemeAddResponse,
+} from './theme';
+import type {
+  UpgradeListResponse,
+  UpgradeRunResponse,
+  UpgradeStatusResponse,
+} from './upgrade';
 import type {SearchResponse} from './search';
+import type {
+  LayoutExpandResponse,
+  LayoutCheckResponse,
+  LayoutGrammarResponse,
+} from './layout';
+import type {BuildHelpResponse, BuildKitResponse} from './build';
 import type {ErrorCode} from './error-codes';
 import type {ManifestResponse} from './manifest';
 import type {DoctorResponse} from './doctor';
 import type {ValidateIntegrationResponse} from './validate-integration';
 
+/**
+ * A "did you mean…" suggestion attached to an error. `reason` is optional:
+ * some call sites emit bare `{name}` (e.g. a list of candidate component names)
+ * with no per-item explanation.
+ */
+export interface Suggestion {
+  name: string;
+  reason?: string;
+}
+
 /**
  * Structured error. Check `'error' in result` to discriminate.
  *
@@ -58,7 +84,7 @@ import type {ValidateIntegrationResponse} from './validate-integration';
 export interface CLIError {
   error: string;
   code: ErrorCode;
-  suggestions?: Array<{name: string; reason: string}>;
+  suggestions?: Suggestion[];
 }
 
 /** Returned by the fallback hook for commands without --json support. */
@@ -74,10 +100,12 @@ export type CLIResult<T> = T | CLIError | CLIUnsupportedError;
 export type CLIAnyResponse =
   | ComponentListResponse
   | ComponentBriefResponse
+  | ComponentFullResponse
   | ComponentDetailResponse
   | ComponentDetailPropsResponse
   | ComponentDetailSourceResponse
   | ComponentDetailShowcaseResponse
+  | ComponentDetailBlocksResponse
   | DiscoverListResponse
   | DiscoverDetailResponse
   | DiscoverDetailDocResponse
@@ -97,9 +125,17 @@ export type CLIAnyResponse =
   | SwizzleListResponse
   | SwizzleCopyResponse
   | ThemeBuildResponse
+  | ThemeListResponse
+  | ThemeAddResponse
   | UpgradeListResponse
   | UpgradeRunResponse
+  | UpgradeStatusResponse
   | SearchResponse
+  | LayoutExpandResponse
+  | LayoutCheckResponse
+  | LayoutGrammarResponse
+  | BuildHelpResponse
+  | BuildKitResponse
   | ManifestResponse
   | DoctorResponse
   | ValidateIntegrationResponse;
@@ -129,7 +165,7 @@ export function jsonOut<T extends CLIResponseType>(
  */
 export function jsonError(
   message: string,
-  suggestions?: Array<{name: string; reason: string}>,
+  suggestions?: Suggestion[],
   code?: ErrorCode,
 ): never;
 

package/types/build.d.ts

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Build command JSON responses.
+ *
+ * `astryx build` is the "assemble a page" verb. With no query it emits the
+ * workflow playbook; with a query it delegates to the search pipeline and
+ * emits a `search` response (see search.d.ts).
+ *
+ * Invocation                    -> type discriminator
+ * ---------------------------------------------------
+ * xds --json build              -> build.help
+ * xds --json build "<idea>"     -> build.kit
+ */
+
+import type {SearchResultEntry} from './search';
+
+/** xds --json build (no query) — the "how to build a page" playbook signal. */
+export interface BuildHelpResponse {
+  type: 'build.help';
+  data: {
+    /** Always true; marks this envelope as the playbook rather than a result set. */
+    playbook: true;
+  };
+}
+
+/**
+ * xds --json build "<idea>" — the composition kit for what you're building.
+ *
+ * Entries are raw `SearchResultEntry` objects (no package-manager-prefixed
+ * command strings — the CLI adds those); `frame`/`foundation` are static
+ * component-name arrays surfaced on every kit.
+ */
+export interface BuildKitResponse {
+  type: 'build.kit';
+  data: {
+    query: string;
+    /** False when search returned nothing (renderer shows "No matches"). */
+    hasResults: boolean;
+    /** True when the top page template is a confident direct match. */
+    directMatch: boolean;
+    /** Closest page templates (≤3). */
+    pages: SearchResultEntry[];
+    /** Drop-in block patterns covering parts of the idea (≤5). */
+    blocks: SearchResultEntry[];
+    /** Idea-specific components/hooks (≤6), excluding frame/foundation. */
+    domain: SearchResultEntry[];
+    /** Always-on page-shell component names. */
+    frame: string[];
+    /** Always-on layout/typography/action component names. */
+    foundation: string[];
+  };
+}

package/types/codemod.d.ts

@@ -0,0 +1,166 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Public type surface for the file-based codemod-authoring API exported from
+ * `@astryxdesign/cli/codemod`.
+ */
+
+/** A single source file presented to a codemod's transform. */
+export interface AstryxCodemodFile {
+  /** Absolute path to the file being transformed. */
+  path: string;
+  /** The current source contents of the file. */
+  source: string;
+}
+
+/** Helpers and context passed to a codemod's transform as the second argument. */
+export interface AstryxCodemodApi {
+  /** A jscodeshift instance configured with a parser for the file. */
+  jscodeshift: unknown;
+  /** Report a statistic (no-op-friendly; provided for jscodeshift parity). */
+  stats: (...args: unknown[]) => void;
+  /** Report progress (no-op-friendly; provided for jscodeshift parity). */
+  report: (...args: unknown[]) => void;
+}
+
+/**
+ * A codemod's transform. Return the new source to rewrite the file, or
+ * `null`/`undefined` to leave the file unchanged.
+ */
+export type AstryxCodemodTransform = (
+  file: AstryxCodemodFile,
+  api: AstryxCodemodApi,
+) => string | null | undefined;
+
+/** Definition accepted by {@link createCodemod}. */
+export interface AstryxCodemodDef {
+  /** Short, human-readable title shown in upgrade output. */
+  title: string;
+  /** Optional longer description. */
+  description?: string;
+  /** When true, the codemod runs only when explicitly requested. */
+  isOptional?: boolean;
+  /** File extensions this codemod applies to (e.g. ['.tsx', '.ts']). */
+  fileExtensions?: string[];
+  /** The transform function. */
+  transform: AstryxCodemodTransform;
+}
+
+/** Result of {@link createCodemod}. */
+export interface AstryxCodemod extends AstryxCodemodDef {
+  isOptional: boolean;
+  type: 'code';
+}
+
+/** Definition accepted by {@link createConfigCodemod}. */
+export interface AstryxConfigCodemodDef {
+  /** Short, human-readable title shown in upgrade output. */
+  title: string;
+  /** Optional longer description. */
+  description?: string;
+  /** When true, the codemod runs only when explicitly requested. */
+  isOptional?: boolean;
+  /** The transform function applied to the astryx.config.* file. */
+  transform: AstryxCodemodTransform;
+}
+
+/** Result of {@link createConfigCodemod}. */
+export interface AstryxConfigCodemod extends AstryxConfigCodemodDef {
+  isOptional: boolean;
+  type: 'config';
+}
+
+/** Define a file-transforming codemod. */
+export declare function createCodemod<T extends AstryxCodemodDef>(
+  def: T,
+): AstryxCodemod;
+
+/** Define a codemod that targets the consumer's astryx.config.* file. */
+export declare function createConfigCodemod<T extends AstryxConfigCodemodDef>(
+  def: T,
+): AstryxConfigCodemod;
+
+// ---------------------------------------------------------------------------
+// Internal types (used by the CLI codemod runner infrastructure & transforms).
+// These are not part of the public authoring surface but are shared across the
+// .mjs files under src/codemods/ so JSDoc annotations stay consistent.
+// ---------------------------------------------------------------------------
+
+/**
+ * jscodeshift transform signature. jscodeshift ships no type declarations, so
+ * the AST surface (`api.jscodeshift`, paths, node attributes) is untyped by
+ * design; transforms operate on it dynamically.
+ */
+export type CodemodTransform = (
+  file: AstryxCodemodFile,
+  api: CodemodTransformApi,
+) => string | null | undefined;
+
+/**
+ * The `api` argument as seen INSIDE a transform implementation. Identical to
+ * {@link AstryxCodemodApi} except `jscodeshift` is typed as the callable
+ * factory (jscodeshift ships no types, so the AST it returns is untyped). Used
+ * by the .mjs transforms so `const j = api.jscodeshift; j(file.source)` type-checks.
+ */
+export interface CodemodTransformApi {
+  jscodeshift: JscodeshiftFactory;
+  stats: (...args: unknown[]) => void;
+  report: (...args: unknown[]) => void;
+}
+
+/**
+ * A normalized codemod entry as produced by both the core registry runner and
+ * integration discovery. See the header of `run-codemod.mjs` for the contract.
+ */
+export interface CodemodEntry {
+  /** Unique id within its package/version (e.g. the transform module name). */
+  id: string;
+  /** Whether this is a source-file codemod or a config-file codemod. */
+  type: 'code' | 'config';
+  /** The codemod itself. */
+  codemod: {
+    title: string;
+    description?: string;
+    isOptional?: boolean;
+    fileExtensions?: string[];
+    transform: CodemodTransform;
+  };
+  /** Owning package name. */
+  package: string;
+  /** Owning package version. */
+  version?: string;
+}
+
+/** The result of running a single codemod over one or more files. */
+export interface CodemodRunResult {
+  filesChanged: number;
+  writtenFiles: string[];
+  errors: Array<{file: string; codemod: string; error: string}>;
+}
+
+/** The console-like log surface used across the codemod runners. */
+export interface CliLog {
+  step: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  success: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+  message?: (...args: unknown[]) => void;
+}
+
+/**
+ * The jscodeshift factory (the module's default export / `withParser` root).
+ * Callable and carries `withParser`; both return an untyped jscodeshift API.
+ *
+ * `any` is unavoidable here: jscodeshift ships no types and its AST/builder
+ * surface is fully dynamic (`j(src)`, `j.JSXElement`, `path.node`, …). `unknown`
+ * would break the callable + index access the transforms rely on.
+ */
+export interface JscodeshiftFactory {
+  /* eslint-disable @typescript-eslint/no-explicit-any */
+  (...args: any[]): any;
+  withParser: (parser: string) => any;
+  /** AST node types and builders (j.JSXElement, j.jsxAttribute, ...) are untyped. */
+  [key: string]: any;
+  /* eslint-enable @typescript-eslint/no-explicit-any */
+}

package/{src/types → types}/component.d.ts

@@ -23,7 +23,7 @@
  * (not found)                               -> CLIError
  */
 
-import type {ComponentDoc, PropDoc} from '../../../core/src/docs-types';
+import type {ComponentDoc, PropDoc} from '../../core/src/docs-types';
 
 /** xds --json component [--list] [--category X] [--detail brief] */
 export interface ComponentListResponse {

package/{src/types → types}/discover.d.ts

@@ -13,7 +13,7 @@
  * (not found)                                    -> CLIError
  */
 
-import type {ComponentDoc} from '../../../core/src/docs-types';
+import type {ComponentDoc} from '../../core/src/docs-types';
 
 /** xds --json discover */
 export interface DiscoverListResponse {

package/{src/types → types}/docs.d.ts

@@ -11,10 +11,7 @@
  * (unknown topic/section)                   -> CLIError
  */
 
-import type {
-  ReferenceDoc,
-  ReferenceSection,
-} from '../../../core/src/docs-types';
+import type {ReferenceDoc, ReferenceSection} from '../../core/src/docs-types';
 
 /** xds --json docs */
 export interface DocsListResponse {

package/{src/types → types}/hook.d.ts

@@ -20,7 +20,7 @@
  * (not found)                               -> CLIError
  */
 
-import type {HookDoc, HookParamDoc} from '../../../core/src/docs-types';
+import type {HookDoc, HookParamDoc} from '../../core/src/docs-types';
 
 /** xds --json hook [--list] [--category X] [--detail brief] */
 export interface HookListResponse {

package/{src/types → types}/index.d.ts

@@ -10,6 +10,7 @@ export * from './swizzle';
 export * from './theme';
 export * from './upgrade';
 export * from './search';
+export * from './build';
 export * from './error-codes';
 export * from './manifest';
 export * from './doctor';

package/types/jscodeshift.d.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Ambient declaration for `jscodeshift`, which ships no type declarations.
+ * The AST surface is intentionally untyped; codemod transforms operate on it
+ * dynamically. This keeps dynamic `import('jscodeshift')` from tripping TS7016
+ * under strict checkJs.
+ */
+declare module 'jscodeshift' {
+  interface JscodeshiftFactory {
+    /* eslint-disable @typescript-eslint/no-explicit-any */
+    (...args: any[]): any;
+    withParser: (parser: string) => any;
+    [key: string]: any;
+    /* eslint-enable @typescript-eslint/no-explicit-any */
+  }
+  const jscodeshift: JscodeshiftFactory;
+  export default jscodeshift;
+}