@lynx-js/genui 0.0.1-rc.0

package/cli/README.md

@@ -0,0 +1,88 @@
+# GenUI CLI
+
+`@lynx-js/genui-cli` is the command line entry point for GenUI workflows. It is
+structured by namespace so A2UI commands can live beside future OpenUI commands
+without adding another package or binary.
+
+## Usage
+
+```bash
+genui <namespace> <command> [options]
+```
+
+Available namespaces:
+
+- `a2ui`: generate A2UI catalog artifacts and system prompts.
+- `openui`: reserved for future OpenUI workflows.
+
+The package also exposes `genui-cli` as an alias. `a2ui-cli` remains available as
+a compatibility alias for existing A2UI-only scripts.
+
+## A2UI Commands
+
+Generate a system prompt with the built-in A2UI basic catalog:
+
+```bash
+genui a2ui generate prompt --out dist/a2ui-system-prompt.txt
+```
+
+Generate catalog artifacts for a custom catalog:
+
+```bash
+genui a2ui generate catalog \
+  --catalog-dir src/catalog \
+  --source src/functions \
+  --out-dir dist/catalog
+```
+
+Generate a system prompt for a custom catalog:
+
+```bash
+genui a2ui generate prompt \
+  --catalog-dir dist/catalog \
+  --catalog-id https://example.com/catalogs/custom/v1/catalog.json \
+  --out dist/a2ui-system-prompt.txt
+```
+
+`generate prompt` uses the built-in A2UI basic catalog by default. Pass
+`--catalog-dir` only when generating a prompt for custom generated catalog
+artifacts. When `--catalog-dir` is provided, the directory must contain files
+like `<Component>/catalog.json`.
+
+### `genui a2ui generate catalog`
+
+Delegates catalog extraction to `@lynx-js/genui/a2ui-catalog-extractor`.
+
+Useful options:
+
+- `--catalog-dir <dir>`: directory to scan for TypeScript component catalog
+  interfaces. Defaults to `src/catalog`.
+- `--source <path>`: source file or directory to scan for catalog functions.
+  Repeatable.
+- `--typedoc-json <file>`: read an existing TypeDoc JSON project.
+- `--out-dir <dir>`: output directory for generated catalog artifacts. Defaults
+  to `dist/catalog`.
+
+### `genui a2ui generate prompt`
+
+Delegates prompt construction to `@lynx-js/genui/a2ui-prompt`.
+
+Useful options:
+
+- `--catalog-dir <dir>`: generated catalog artifact directory. Omit this option
+  to use the built-in A2UI basic catalog.
+- `--catalog-id <id>`: catalog id to require in `createSurface` messages.
+  Defaults to the built-in A2UI basic catalog id.
+- `--out <file>`: write the prompt to a file instead of stdout.
+- `--appendix <text>`: append extra instructions to the generated prompt.
+
+## Compatibility
+
+Existing A2UI commands still work:
+
+```bash
+a2ui-cli generate catalog --catalog-dir src/catalog --out-dir dist/catalog
+a2ui-cli generate prompt --out dist/a2ui-system-prompt.txt
+```
+
+New scripts should prefer `genui a2ui ...`.

package/cli/bin/cli.js

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import * as fs from 'node:fs';
+import { createRequire } from 'node:module';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const usage = `Usage: genui <namespace> <command> [options]
+
+Namespaces:
+  a2ui    Generate A2UI catalog artifacts and system prompts.
+  openui  Reserved for future OpenUI workflows.
+
+Examples:
+  genui a2ui generate catalog --catalog-dir src/catalog --out-dir dist/catalog
+  genui a2ui generate prompt --out dist/a2ui-system-prompt.txt
+`;
+
+const a2uiUsage = `Usage: genui a2ui generate <target> [options]
+
+Targets:
+  catalog  Generate A2UI component and function catalog files.
+  prompt   Generate an A2UI system prompt from catalog files.
+`;
+
+const openuiUsage = `Usage: genui openui <command> [options]
+
+OpenUI CLI commands are reserved for future GenUI workflows.
+`;
+
+function createGenerateCatalogUsage(programName) {
+  return `Usage: ${programName} generate catalog [options]
+
+Options:
+  --catalog-dir <dir>  Directory to scan for TypeScript catalog interfaces.
+  --source <path>      Source file or directory to scan. Repeatable.
+  --typedoc-json <file>
+                       Read an existing TypeDoc JSON project instead of
+                       running TypeDoc conversion.
+  --out-dir <dir>      Output directory for component catalog.json files.
+  --version            Print the package version.
+  --help               Print this help message.
+
+Defaults:
+  --catalog-dir src/catalog
+  --out-dir dist/catalog
+`;
+}
+
+function createGeneratePromptUsage(programName) {
+  return `Usage: ${programName} generate prompt [options]
+
+Options:
+  --catalog-dir <dir>  Directory containing generated catalog files. When
+                       omitted, use the built-in A2UI basic catalog.
+  --catalog-id <id>    Catalog id to require in createSurface messages.
+  --out <file>         Write the prompt to a file instead of stdout.
+  --appendix <text>    Append extra instructions to the generated prompt.
+  --version            Print the package version.
+  --help               Print this help message.
+
+Defaults:
+  --catalog-id built-in A2UI basic catalog id
+`;
+}
+
+if (isMain(import.meta.url)) {
+  try {
+    process.exitCode = await runCli(process.argv.slice(2), process.cwd(), {
+      binName: path.basename(process.argv[1] ?? 'genui'),
+    });
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}
+
+export async function runCli(args, cwd = process.cwd(), cliOptions = {}) {
+  const binName = cliOptions.binName ?? 'genui';
+  if (binName === 'a2ui-cli') {
+    return await runA2UICli(args, cwd, { programName: 'a2ui-cli' });
+  }
+
+  const command = args[0];
+  if (command === undefined || command === '--help' || command === '-h') {
+    console.info(usage);
+    return 0;
+  }
+  if (command === '--version' || command === '-v') {
+    printPackageVersion();
+    return 0;
+  }
+
+  if (command === 'a2ui') {
+    return await runA2UICli(args.slice(1), cwd, { programName: 'genui a2ui' });
+  }
+  if (command === 'openui') {
+    return runOpenUICli(args.slice(1));
+  }
+
+  throw new Error(`Unknown namespace: ${command}`);
+}
+
+async function runA2UICli(args, cwd, options) {
+  const programName = options.programName;
+  const command = args[0];
+  if (command === undefined || command === '--help' || command === '-h') {
+    console.info(programName === 'a2ui-cli' ? legacyA2UIUsage : a2uiUsage);
+    return 0;
+  }
+  if (command === '--version' || command === '-v') {
+    printPackageVersion();
+    return 0;
+  }
+  if (command !== 'generate') {
+    throw new Error(`Unknown A2UI command: ${command}`);
+  }
+  const target = args[1];
+  const targetArgs = args.slice(2);
+  if (target === undefined || target === '--help' || target === '-h') {
+    console.info(programName === 'a2ui-cli' ? legacyA2UIUsage : a2uiUsage);
+    return 0;
+  }
+  if (target === '--version' || target === '-v') {
+    printPackageVersion();
+    return 0;
+  }
+  if (target === 'catalog') {
+    if (targetArgs.includes('--help') || targetArgs.includes('-h')) {
+      console.info(createGenerateCatalogUsage(programName));
+      return 0;
+    }
+    const { runCli: runCatalogExtractorCli } = await import(
+      '../../a2ui-catalog-extractor/dist/cli.js'
+    );
+    return await runCatalogExtractorCli(targetArgs, cwd);
+  }
+  if (target === 'prompt') {
+    return runGeneratePromptCli(targetArgs, cwd, { programName });
+  }
+  throw new Error(`Unknown generate target: ${target}`);
+}
+
+const legacyA2UIUsage = a2uiUsage.replaceAll('genui a2ui', 'a2ui-cli');
+
+function runOpenUICli(args) {
+  const command = args[0];
+  if (command === undefined || command === '--help' || command === '-h') {
+    console.info(openuiUsage);
+    return 0;
+  }
+  if (command === '--version' || command === '-v') {
+    printPackageVersion();
+    return 0;
+  }
+  throw new Error(
+    `Unknown OpenUI command: ${command}. OpenUI CLI commands are not available yet.`,
+  );
+}
+
+async function runGeneratePromptCli(args, cwd, cliOptions) {
+  const programName = cliOptions.programName;
+  const options = parseGeneratePromptArgs(args);
+  if (options.help) {
+    console.info(createGeneratePromptUsage(programName));
+    return 0;
+  }
+  if (options.version) {
+    printPackageVersion();
+    return 0;
+  }
+
+  const {
+    BASIC_CATALOG,
+    BASIC_CATALOG_ID,
+    buildA2UISystemPrompt,
+    readA2UICatalogFromDirectory,
+  } = await import('../../a2ui-prompt/dist/index.js');
+  const catalog = options.catalogDir
+    ? readA2UICatalogFromDirectory({
+      catalogDir: options.catalogDir,
+      catalogId: options.catalogId ?? BASIC_CATALOG_ID,
+      cwd,
+    })
+    : (options.catalogId
+      ? { ...BASIC_CATALOG, id: options.catalogId }
+      : undefined);
+  if (options.catalogDir && catalog && isEmptyCatalog(catalog)) {
+    throw new Error(
+      `[${programName}] No components or functions found in generated catalog directory: ${options.catalogDir}`,
+    );
+  }
+  const systemPrompt = buildA2UISystemPrompt({
+    ...(catalog ? { catalog } : {}),
+    ...(options.appendix ? { appendix: options.appendix } : {}),
+  });
+
+  if (options.out) {
+    const outPath = path.resolve(cwd, options.out);
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, systemPrompt);
+    console.info(`Generated A2UI system prompt at ${options.out}.`);
+  } else {
+    process.stdout.write(systemPrompt);
+  }
+
+  return 0;
+}
+
+function parseGeneratePromptArgs(args) {
+  const options = {
+    help: false,
+    version: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    switch (arg) {
+      case '--catalog-dir':
+        options.catalogDir = readValue(args, ++index, arg);
+        break;
+      case '--catalog-id':
+        options.catalogId = readValue(args, ++index, arg);
+        break;
+      case '--out':
+        options.out = readValue(args, ++index, arg);
+        break;
+      case '--appendix':
+        options.appendix = readValue(args, ++index, arg);
+        break;
+      case '--help':
+      case '-h':
+        options.help = true;
+        break;
+      case '--version':
+      case '-v':
+        options.version = true;
+        break;
+      default:
+        throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function isEmptyCatalog(catalog) {
+  return (!Array.isArray(catalog.components) || catalog.components.length === 0)
+    && (!Array.isArray(catalog.functions) || catalog.functions.length === 0);
+}
+
+function readValue(args, index, option) {
+  const value = args[index];
+  if (!value || value.startsWith('-')) {
+    throw new Error(`Missing value for ${option}.`);
+  }
+  return value;
+}
+
+function printPackageVersion() {
+  const require = createRequire(import.meta.url);
+  const packageJson = require('../package.json');
+  console.info(packageJson.version);
+}
+
+function isMain(moduleUrl) {
+  return process.argv[1] !== undefined
+    && moduleUrl === pathToFileURL(process.argv[1]).href;
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { A2UI, NodeRenderer, useAction, useChecks, useDataBinding, useResolvedProps, } from '@lynx-js/genui/a2ui/react';
+export type { A2UIProps, ActionProps, CheckLike, } from '@lynx-js/genui/a2ui/react';
+export { createFallbackMessagesFromPlainText, createMessageStore, createResource, createTextCardMessages, executeFunctionCall, FunctionRegistry, functionRegistry, isDataBinding, isFunctionCall, MessageProcessor, normalizePayloadToMessages, prepareMessagesForProcessing, resolveDynamicValue, resolveFunctionArguments, SignalStore, } from '@lynx-js/genui/a2ui/store';
+export type { A2UIClientEventMessage, A2UIEvent, ComponentInstance, FunctionCallContext, FunctionEntry, FunctionImpl, GenericComponentProps, MessageStore, MessageStoreOptions, RawResource, ResolveFunctionOptions, Resource, ResourceInfo, ResourceStatus, ServerToClientMessage, Surface, SurfaceId, UserActionPayload, } from '@lynx-js/genui/a2ui/store';
+export { basicFunctions, registerBasicFunctions, } from '@lynx-js/genui/a2ui/functions';
+export * from '@lynx-js/genui/openui';
+export { A2UI_PROTOCOL_VERSION, A2UI_SYSTEM_PROMPT, BASIC_CATALOG, BASIC_CATALOG_EXAMPLES, BASIC_CATALOG_ID, buildA2UISystemPrompt, createA2UICatalogFromManifests, readA2UICatalogFromDirectory, renderCatalogReference, } from '@lynx-js/genui/a2ui-prompt';
+export type { A2UICatalog as A2UIPromptCatalog, A2UIComponentProp, A2UIComponentSpec, A2UIExample, A2UIFunctionSpec, BuildSystemPromptOptions, JsonSchema as A2UIPromptJsonSchema, ReadA2UICatalogDirectoryOptions, } from '@lynx-js/genui/a2ui-prompt';
+export { createA2UICatalog, extractCatalogComponents, extractCatalogComponentsFromTypeDocJson, extractCatalogComponentsFromTypeDocProject, extractCatalogFunctions, extractCatalogFunctionsFromTypeDocJson, extractCatalogFunctionsFromTypeDocProject, findCatalogSourceFiles, writeCatalogArtifacts, writeCatalogComponents, writeCatalogFunctionDefinitions, writeCatalogFunctions, writeComponentCatalogs, } from '@lynx-js/genui/a2ui-catalog-extractor';
+export type { A2UICatalog as ExtractedA2UICatalog, CatalogArtifacts, CatalogComponent as ExtractedCatalogComponent, CatalogFunction, ExtractCatalogFromTypeDocOptions, ExtractCatalogOptions, FunctionDefinition, JsonSchema as ExtractedJsonSchema, TypeDocComment, TypeDocCommentDisplayPart, TypeDocCommentTag, TypeDocProject, TypeDocReflection, TypeDocSignature, TypeDocSource, TypeDocType, WriteComponentCatalogOptions, } from '@lynx-js/genui/a2ui-catalog-extractor';

package/dist/index.js

@@ -0,0 +1,10 @@
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+export { A2UI, NodeRenderer, useAction, useChecks, useDataBinding, useResolvedProps, } from '@lynx-js/genui/a2ui/react';
+export { createFallbackMessagesFromPlainText, createMessageStore, createResource, createTextCardMessages, executeFunctionCall, FunctionRegistry, functionRegistry, isDataBinding, isFunctionCall, MessageProcessor, normalizePayloadToMessages, prepareMessagesForProcessing, resolveDynamicValue, resolveFunctionArguments, SignalStore, } from '@lynx-js/genui/a2ui/store';
+export { basicFunctions, registerBasicFunctions, } from '@lynx-js/genui/a2ui/functions';
+export * from '@lynx-js/genui/openui';
+export { A2UI_PROTOCOL_VERSION, A2UI_SYSTEM_PROMPT, BASIC_CATALOG, BASIC_CATALOG_EXAMPLES, BASIC_CATALOG_ID, buildA2UISystemPrompt, createA2UICatalogFromManifests, readA2UICatalogFromDirectory, renderCatalogReference, } from '@lynx-js/genui/a2ui-prompt';
+export { createA2UICatalog, extractCatalogComponents, extractCatalogComponentsFromTypeDocJson, extractCatalogComponentsFromTypeDocProject, extractCatalogFunctions, extractCatalogFunctionsFromTypeDocJson, extractCatalogFunctionsFromTypeDocProject, findCatalogSourceFiles, writeCatalogArtifacts, writeCatalogComponents, writeCatalogFunctionDefinitions, writeCatalogFunctions, writeComponentCatalogs, } from '@lynx-js/genui/a2ui-catalog-extractor';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,yEAAyE;AACzE,0DAA0D;AAE1D,OAAO,EACL,IAAI,EACJ,YAAY,EACZ,SAAS,EACT,SAAS,EACT,cAAc,EACd,gBAAgB,GACjB,MAAM,2BAA2B,CAAC;AAMnC,OAAO,EACL,mCAAmC,EACnC,kBAAkB,EAClB,cAAc,EACd,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,0BAA0B,EAC1B,4BAA4B,EAC5B,mBAAmB,EACnB,wBAAwB,EACxB,WAAW,GACZ,MAAM,2BAA2B,CAAC;AAqBnC,OAAO,EACL,cAAc,EACd,sBAAsB,GACvB,MAAM,+BAA+B,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,sBAAsB,EACtB,gBAAgB,EAChB,qBAAqB,EACrB,8BAA8B,EAC9B,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,4BAA4B,CAAC;AAWpC,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,uCAAuC,EACvC,0CAA0C,EAC1C,uBAAuB,EACvB,sCAAsC,EACtC,yCAAyC,EACzC,sBAAsB,EACtB,qBAAqB,EACrB,sBAAsB,EACtB,+BAA+B,EAC/B,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,uCAAuC,CAAC"}