@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

package/api/layout/layout.type.d.mts

@@ -0,0 +1,89 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The input surface an expression was parsed as.
+ */
+export type LayoutForm = "compact" | "outline" | "auto";
+/**
+ * A validation issue with its formatted, human-readable rendering.
+ */
+export type LayoutIssue = {
+    line?: number | undefined;
+    col?: number | undefined;
+    message: string;
+    formatted: string;
+    suggestions?: string[] | undefined;
+};
+/**
+ * A block referenced by a layout expression and how it was spliced in.
+ */
+export type LayoutBlockReference = {
+    name: string;
+    mode: string;
+};
+/**
+ * astryx --json layout expand "<expr>" [path]
+ */
+export type LayoutExpandResponse = {
+    type: "layout.expand";
+    data: {
+        form: LayoutForm;
+        code: string;
+        componentsUsed: string[];
+        states: number;
+        todos: string[];
+        blocksReferenced: LayoutBlockReference[];
+        warnings: string[];
+        written: string | null;
+    };
+};
+/**
+ * astryx --json layout check "<expr>"
+ */
+export type LayoutCheckResponse = {
+    type: "layout.check";
+    data: {
+        valid: boolean;
+        form: LayoutForm;
+        errors: LayoutIssue[];
+        warnings: string[];
+        compact: string;
+        outline: string;
+    };
+};
+/**
+ * astryx --json layout grammar
+ */
+export type LayoutGrammarResponse = {
+    type: "layout.grammar";
+    data: {
+        text: string;
+        aliases: Record<string, string>;
+    };
+};
+export type LayoutResponse = LayoutExpandResponse | LayoutCheckResponse | LayoutGrammarResponse;
+/**
+ * Options for `layoutExpand()`.
+ */
+export type LayoutExpandOptions = {
+    targetPath?: string | undefined;
+    form?: LayoutForm | undefined;
+    loose?: boolean | undefined;
+    name?: string | undefined;
+    cwd?: string | undefined;
+};
+/**
+ * Options for `layoutCheck()`.
+ */
+export type LayoutCheckOptions = {
+    form?: LayoutForm | undefined;
+    loose?: boolean | undefined;
+    cwd?: string | undefined;
+};
+/**
+ * Options for `layoutGrammar()`.
+ */
+export type LayoutGrammarOptions = {
+    cwd?: string | undefined;
+};

package/api/layout/layout.type.mjs

@@ -0,0 +1,103 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated types for the `layout` command — source of truth for its JSON
+ * responses. `astryx layout expand|check|grammar` turn compressed XLE/XLO
+ * expressions into validated XDS TSX (or echo canonical surfaces / a grammar
+ * cheatsheet). The `types/layout.d.ts` barrel re-exports from here.
+ *
+ * Invocation                                 -> type discriminator
+ * -----------------------------------------------------------------
+ * astryx --json layout expand "<expr>"       -> layout.expand
+ * astryx --json layout check "<expr>"        -> layout.check
+ * astryx --json layout grammar               -> layout.grammar
+ */
+
+/**
+ * The input surface an expression was parsed as.
+ * @typedef {'compact' | 'outline' | 'auto'} LayoutForm
+ */
+
+/**
+ * A validation issue with its formatted, human-readable rendering.
+ * @typedef {object} LayoutIssue
+ * @property {number} [line]
+ * @property {number} [col]
+ * @property {string} message
+ * @property {string} formatted
+ * @property {string[]} [suggestions]
+ */
+
+/**
+ * A block referenced by a layout expression and how it was spliced in.
+ * @typedef {object} LayoutBlockReference
+ * @property {string} name
+ * @property {string} mode
+ */
+
+/**
+ * astryx --json layout expand "<expr>" [path]
+ * @typedef {object} LayoutExpandResponse
+ * @property {'layout.expand'} type
+ * @property {object} data
+ * @property {LayoutForm} data.form
+ * @property {string} data.code
+ * @property {string[]} data.componentsUsed
+ * @property {number} data.states Number of useState hooks the expansion scaffolded.
+ * @property {string[]} data.todos
+ * @property {LayoutBlockReference[]} data.blocksReferenced
+ * @property {string[]} data.warnings
+ * @property {string | null} data.written
+ */
+
+/**
+ * astryx --json layout check "<expr>"
+ * @typedef {object} LayoutCheckResponse
+ * @property {'layout.check'} type
+ * @property {object} data
+ * @property {boolean} data.valid
+ * @property {LayoutForm} data.form
+ * @property {LayoutIssue[]} data.errors
+ * @property {string[]} data.warnings
+ * @property {string} data.compact
+ * @property {string} data.outline
+ */
+
+/**
+ * astryx --json layout grammar
+ * @typedef {object} LayoutGrammarResponse
+ * @property {'layout.grammar'} type
+ * @property {object} data
+ * @property {string} data.text
+ * @property {Record<string, string>} data.aliases Alias table (short name -> canonical component), from the registry.
+ */
+
+/**
+ * @typedef {LayoutExpandResponse | LayoutCheckResponse | LayoutGrammarResponse} LayoutResponse
+ */
+
+/**
+ * Options for `layoutExpand()`.
+ * @typedef {object} LayoutExpandOptions
+ * @property {string} [targetPath]
+ * @property {LayoutForm} [form]
+ * @property {boolean} [loose]
+ * @property {string} [name]
+ * @property {string} [cwd]
+ */
+
+/**
+ * Options for `layoutCheck()`.
+ * @typedef {object} LayoutCheckOptions
+ * @property {LayoutForm} [form]
+ * @property {boolean} [loose]
+ * @property {string} [cwd]
+ */
+
+/**
+ * Options for `layoutGrammar()`.
+ * @typedef {object} LayoutGrammarOptions
+ * @property {string} [cwd]
+ */
+
+export {};

package/api/layout/layoutCheck.doc.d.mts

@@ -0,0 +1,11 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file FunctionDoc for `layoutCheck()` / `astryx layout check`. Colocated with
+ * the API function it documents; the response-shape source of truth stays in
+ * `layout.type.mjs`.
+ * @position packages/cli/api/layout — function documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc: import("@astryxdesign/cli/authoring").FunctionDoc;

package/api/layout/layoutCheck.doc.mjs

@@ -0,0 +1,85 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FunctionDoc for `layoutCheck()` / `astryx layout check`. Colocated with
+ * the API function it documents; the response-shape source of truth stays in
+ * `layout.type.mjs`.
+ * @position packages/cli/api/layout — function documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc = {
+  type: 'function',
+  kind: 'api',
+  name: 'layoutCheck',
+  namespace: 'cli/api',
+  displayName: 'layoutCheck()',
+  summary: 'Validate a layout expression without expanding it.',
+  description:
+    'The validator behind `astryx layout check`. Parses and validates a compressed XLE/XLO ' +
+    'expression without generating any TSX, and echoes it back in both canonical surfaces ' +
+    '(compact and outline). Validation failures are reported in the layout.check envelope ' +
+    '(valid: false) with line/col and suggestions (not thrown) so callers can lint an ' +
+    'expression and surface fixes.',
+  importPath: '@astryxdesign/cli/api',
+  signature:
+    'layoutCheck(expression: string, options?: LayoutCheckOptions): Promise<LayoutCheckResponse>',
+  keywords: ['layout', 'check', 'validate', 'xle', 'xlo', 'lint'],
+  params: [
+    {
+      name: 'expression',
+      type: 'string',
+      description: 'The layout expression to validate.',
+      required: true,
+    },
+    {
+      name: 'options.form',
+      type: "'compact' | 'outline' | 'auto'",
+      description:
+        'Force which input surface the expression is parsed as, or auto-detect it.',
+      default: "'auto'",
+    },
+    {
+      name: 'options.loose',
+      type: 'boolean',
+      description:
+        'Treat unknown {hint} references as warnings instead of errors.',
+      default: 'false',
+    },
+    {
+      name: 'options.cwd',
+      type: 'string',
+      description: 'Directory the block catalog and registry resolve against.',
+    },
+  ],
+  returns: [
+    {
+      type: 'layout.check',
+      description:
+        'The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).',
+    },
+  ],
+  throws: [
+    {code: 'ERR_INVALID_ARGUMENT', when: 'the expression is empty'},
+    {
+      code: 'ERR_INVALID_OPTION',
+      when: 'form is not one of "compact", "outline", or "auto"',
+    },
+    {
+      code: 'ERR_LAYOUT_PARSE',
+      when: 'the expression has a syntax error (reported with line/col)',
+    },
+  ],
+  examples: [
+    {
+      label: 'Validate an expression',
+      code: 'const r = await layoutCheck(\'VStack[g4] > Text"Hi"\');',
+    },
+    {
+      label: 'Read the canonical forms',
+      code: 'const {data} = await layoutCheck(\'Card > Text"Hi"\');',
+    },
+  ],
+  command: 'layout check',
+  related: ['layoutExpand', 'layoutGrammar'],
+};

package/api/layout/layoutExpand.doc.d.mts

@@ -0,0 +1,11 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file FunctionDoc for `layoutExpand()` / `astryx layout expand`. Colocated
+ * with the API function it documents; the response-shape source of truth stays
+ * in `layout.type.mjs`.
+ * @position packages/cli/api/layout — function documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc: import("@astryxdesign/cli/authoring").FunctionDoc;

package/api/layout/layoutExpand.doc.mjs

@@ -0,0 +1,107 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FunctionDoc for `layoutExpand()` / `astryx layout expand`. Colocated
+ * with the API function it documents; the response-shape source of truth stays
+ * in `layout.type.mjs`.
+ * @position packages/cli/api/layout — function documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc = {
+  type: 'function',
+  kind: 'api',
+  name: 'layoutExpand',
+  namespace: 'cli/api',
+  displayName: 'layoutExpand()',
+  summary: 'Expand a validated layout expression into XDS TSX.',
+  description:
+    'The generator behind `astryx layout expand`. Parses and validates a compressed XLE/XLO ' +
+    'expression, then expands it into ready-to-use XDS TSX, auto-routing structural children ' +
+    'into the right slots, scaffolding typed useState for interactive controls, and splicing or ' +
+    'importing any referenced template blocks. Returns the code (and metadata) in a layout.expand ' +
+    'envelope, optionally writing it to a path within cwd.',
+  importPath: '@astryxdesign/cli/api',
+  signature:
+    'layoutExpand(expression: string, options?: LayoutExpandOptions): Promise<LayoutExpandResponse>',
+  keywords: ['layout', 'expand', 'xle', 'xlo', 'tsx', 'scaffold', 'generate'],
+  params: [
+    {
+      name: 'expression',
+      type: 'string',
+      description:
+        'The layout expression to expand (XLE compact or XLO outline form).',
+      required: true,
+    },
+    {
+      name: 'options.targetPath',
+      type: 'string',
+      description:
+        'Write the generated TSX here (validated to stay within cwd). A path that ends in .tsx, .ts, .jsx, .js, .mjs, .cjs, .css, .scss, .json, .md or .html is used as-is; any other path is a directory that gets <name>.tsx. An existing file is replaced. Omit to return the code without writing.',
+    },
+    {
+      name: 'options.form',
+      type: "'compact' | 'outline' | 'auto'",
+      description:
+        'Force which input surface the expression is parsed as, or auto-detect it.',
+      default: "'auto'",
+    },
+    {
+      name: 'options.loose',
+      type: 'boolean',
+      description:
+        'Downgrade unknown {hint} references to TODO warnings instead of hard errors.',
+      default: 'false',
+    },
+    {
+      name: 'options.name',
+      type: 'string',
+      description: 'PascalCase name for the generated component.',
+      default: "'GeneratedLayout'",
+    },
+    {
+      name: 'options.cwd',
+      type: 'string',
+      description:
+        'Directory the block catalog, registry, and target path resolve against.',
+    },
+  ],
+  returns: [
+    {
+      type: 'layout.expand',
+      description:
+        'The expansion: the parsed form, the generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the relative output path, or null when nothing was written).',
+    },
+  ],
+  throws: [
+    {
+      code: 'ERR_INVALID_ARGUMENT',
+      when: 'the expression is empty, or name is not a PascalCase identifier',
+    },
+    {
+      code: 'ERR_INVALID_OPTION',
+      when: 'form is not one of "compact", "outline", or "auto"',
+    },
+    {
+      code: 'ERR_LAYOUT_PARSE',
+      when: 'the expression has a syntax error (reported with line/col)',
+    },
+    {
+      code: 'ERR_LAYOUT_INVALID',
+      when: 'the expression parses but fails validation (unknown component/prop/enum/block)',
+    },
+    {code: 'ERR_PATH_TRAVERSAL', when: 'the target path escapes cwd'},
+  ],
+  examples: [
+    {
+      label: 'Expand to TSX',
+      code: 'const r = await layoutExpand(\'VStack[g4] > Heading"Title" + Text"Body"\');',
+    },
+    {
+      label: 'Write to a file',
+      code: "await layoutExpand('Card > Text\"Hi\"', {targetPath: 'src/Generated.tsx', name: 'Generated'});",
+    },
+  ],
+  command: 'layout expand',
+  related: ['layoutCheck', 'layoutGrammar'],
+};

package/api/layout/layoutGrammar.doc.d.mts

@@ -0,0 +1,11 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file FunctionDoc for `layoutGrammar()` / `astryx layout grammar`. Colocated
+ * with the API function it documents; the response-shape source of truth stays
+ * in `layout.type.mjs`.
+ * @position packages/cli/api/layout — function documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc: import("@astryxdesign/cli/authoring").FunctionDoc;

package/api/layout/layoutGrammar.doc.mjs

@@ -0,0 +1,57 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FunctionDoc for `layoutGrammar()` / `astryx layout grammar`. Colocated
+ * with the API function it documents; the response-shape source of truth stays
+ * in `layout.type.mjs`.
+ * @position packages/cli/api/layout — function documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc = {
+  type: 'function',
+  kind: 'api',
+  name: 'layoutGrammar',
+  namespace: 'cli/api',
+  displayName: 'layoutGrammar()',
+  summary: 'Return the XLE/XLO grammar cheatsheet for this install.',
+  description:
+    'The reference behind `astryx layout grammar`: the agent cheatsheet for writing XLE/XLO ' +
+    "layout expressions, with the alias table generated from this branch's registry rather than " +
+    'hand-maintained, so short names always reflect the components actually installed.',
+  importPath: '@astryxdesign/cli/api',
+  signature:
+    'layoutGrammar(options?: LayoutGrammarOptions): Promise<LayoutGrammarResponse>',
+  keywords: [
+    'layout',
+    'grammar',
+    'cheatsheet',
+    'xle',
+    'xlo',
+    'aliases',
+    'reference',
+  ],
+  params: [
+    {
+      name: 'options.cwd',
+      type: 'string',
+      description:
+        'Directory the component registry (and its alias table) resolves against.',
+    },
+  ],
+  returns: [
+    {
+      type: 'layout.grammar',
+      description:
+        "The cheatsheet: a text field with the full grammar reference, plus an aliases map (short name → canonical component) generated from this install's registry.",
+    },
+  ],
+  examples: [
+    {
+      label: 'Get the cheatsheet',
+      code: 'const {data} = await layoutGrammar();',
+    },
+  ],
+  command: 'layout grammar',
+  related: ['layoutExpand', 'layoutCheck'],
+};

package/api/search/search.d.mts

@@ -24,23 +24,6 @@ export function sameWord(a: string, b: string): boolean;
  * @returns {string[]}
  */
 export function tokenizeQuery(term: string): string[];
-/**
- * The first title or heading that holds every word of the query, in order and
- * side by side, or null.
- * @param {string} term - Lowercased full query.
- * @param {string[] | undefined} titles
- * @returns {string | null}
- */
-export function headingWithPhrase(term: string, titles: string[] | undefined): string | null;
-/**
- * The first title or heading of two words or more that the query holds whole,
- * in order and side by side, or null. A question such as "how do I add dark
- * mode" names the "Dark mode" section outright, around words no title has.
- * @param {string} term - Lowercased full query.
- * @param {string[] | undefined} titles
- * @returns {string | null}
- */
-export function titleInQuery(term: string, titles: string[] | undefined): string | null;
 /**
  * @param {string} term - Lowercased full query.
  * @param {string[]} tokens - Content tokens from tokenizeQuery(term).
@@ -66,8 +49,6 @@ export function scoreQuery(term: string, tokens: string[], candidate: Candidate)
  * @param {string} term - Lowercased search term.
  * @param {object} candidate
  * @param {string} candidate.name - Primary identifier (component/hook name, topic, template name).
- * @param {string} [candidate.domain] - A component, hook, or template name
- *   also matches typed as words: `command palette` is CommandPalette.
  * @param {string[]} [candidate.keywords] - Authored intent (componentsUsed, category words).
  * @param {string[]} [candidate.weakKeywords] - Derived signal (components a page renders).
  * @param {string} [candidate.description]
@@ -76,9 +57,8 @@ export function scoreQuery(term: string, tokens: string[], candidate: Candidate)
  * @param {{fuzzy?: boolean}} [opts] - `fuzzy`: allow edit-distance (typo) matches. Default true; multi-word queries pass false.
  * @returns {{score: number, reason: string} | null}
  */
-export function scoreCandidate(term: string, { name, domain, keywords, weakKeywords, description, prose, guidance, }: {
+export function scoreCandidate(term: string, { name, keywords, weakKeywords, description, prose, guidance, }: {
     name: string;
-    domain?: string | undefined;
     keywords?: string[] | undefined;
     weakKeywords?: string[] | undefined;
     description?: string | undefined;
@@ -142,12 +122,6 @@ export type Candidate = {
     description?: string | undefined;
     prose?: string[] | undefined;
     guidance?: string[] | undefined;
-    /**
-     * - A doc's title and the headings inside it:
-     * the lines a reader scans to pick it. The whole query standing in one of
-     * them, or one of them standing whole in the query, is a top-tier match.
-     */
-    titles?: string[] | undefined;
     _import?: string | undefined;
     _title?: string | undefined;
     /**

package/api/search/search.doc.mjs

@@ -48,7 +48,7 @@ export const doc = {
       name: 'options.cwd',
       type: 'string',
       description:
-        "Directory to resolve @astryxdesign/core from. A docs-only search (`type: 'doc'`) does not need it, and a search with no `type` covers the docs alone when core is missing.",
+        "Directory to resolve @astryxdesign/core from. A docs-only search (`type: 'doc'`) does not need it.",
     },
   ],
   returns: [
@@ -65,7 +65,7 @@ export const doc = {
     },
     {
       code: 'ERR_CORE_NOT_FOUND',
-      when: '@astryxdesign/core cannot be found from the cwd, and `type` names a domain that reads it: `component`, `hook`, or `template`',
+      when: '@astryxdesign/core cannot be found from the cwd, and the search reads it: every `type` but `doc`',
     },
   ],
   examples: [