@sebgroup/green-core 2.33.0 → 2.34.0

package/README.md

@@ -125,3 +125,27 @@ Then you can just use `<Button />` like a regular React component.
 ## Documentation
 
 Check out the [Storybook (@sebgroup/core)](https://storybook.seb.io/latest/core/) for components and documentation.
+
+## Testing
+
+The test suite is split by runtime so Node tooling tests do not run in browser mode.
+
+- **Node tests** (`src/bin/**`) for developer tooling such as CLI and MCP server:
+
+  ```bash
+  nx run core:test:node
+  ```
+
+- **Browser tests** for web components and UI behavior (Chromium + WebKit):
+
+  ```bash
+  nx run core:test:browser
+  ```
+
+- **Full suite** (same split as CI/local default target):
+
+  ```bash
+  nx run core:test
+  ```
+
+Use `core:test:node` when working on CLI/MCP code for faster feedback, and `core:test:browser` when working on components, interactions, or rendering behavior.

package/bin/context-cli/framework.d.ts

@@ -0,0 +1,3 @@
+export declare const DOCS_FRAMEWORK_CANONICAL: readonly ["angular", "react", "web-component"];
+export type DocsFramework = (typeof DOCS_FRAMEWORK_CANONICAL)[number];
+export declare function normalizeDocsFramework(input: string): DocsFramework | null;

package/bin/context-cli/framework.js

@@ -0,0 +1,23 @@
+import "../../chunks/chunk.QU3DSPNU.js";
+const DOCS_FRAMEWORK_CANONICAL = [
+  "angular",
+  "react",
+  "web-component"
+];
+const DOCS_FRAMEWORK_ALIASES = {
+  angular: "angular",
+  react: "react",
+  "web-component": "web-component",
+  "web-components": "web-component",
+  webcomponent: "web-component",
+  webcomponents: "web-component",
+  web: "web-component"
+};
+function normalizeDocsFramework(input) {
+  const normalized = DOCS_FRAMEWORK_ALIASES[input.trim().toLowerCase()];
+  return normalized ?? null;
+}
+export {
+  DOCS_FRAMEWORK_CANONICAL,
+  normalizeDocsFramework
+};

package/bin/context-cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export { parseArgs } from './parse-args.js';

package/bin/context-cli/index.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+import "../../chunks/chunk.QU3DSPNU.js";
+import { McpError } from "../mcp-server/errors.js";
+import {
+  handleGetComponentDocs,
+  handleGetGuide,
+  handleGetInstructions,
+  handleListGuides,
+  handleResolveUri,
+  handleSearchComponents
+} from "../mcp-server/handlers.js";
+import { getPackageVersion } from "../mcp-server/utils.js";
+import {
+  DOCS_FRAMEWORK_CANONICAL,
+  normalizeDocsFramework
+} from "./framework.js";
+import { parseArgs } from "./parse-args.js";
+function getPrimaryTextContent(result) {
+  const textBlock = result.content.find(
+    (block) => block.type === "text"
+  );
+  if (!textBlock) {
+    throw new Error("Tool response did not include a text content block");
+  }
+  return textBlock.text;
+}
+import { parseArgs as parseArgs2 } from "./parse-args.js";
+const PROGRAM_NAME = "green-core-context";
+const HELP_TEXT = `
+Green Design System \u2014 Context CLI
+
+Provides design system documentation, component APIs, guides, and usage
+instructions directly from the command line. Outputs to stdout for easy
+piping to grep, jq, less, etc.
+
+USAGE
+  ${PROGRAM_NAME} <command> [options]
+
+COMMANDS
+  search <query>                    Search for components and icons
+  docs <component> <framework>      Get component documentation
+  get <uri>                         Fetch raw content by green:// URI
+  guides                            List available guides
+  guide <name>                      Get a specific guide's content
+  instructions                      Get base usage instructions
+
+GLOBAL OPTIONS
+  -h, --help                        Show this help message
+  -v, --version                     Show version number
+
+Run '${PROGRAM_NAME} <command> --help' for command-specific options.
+`.trim();
+const SEARCH_HELP = `
+Search for Green Design System components and icons by name, description,
+or functionality.
+
+USAGE
+  ${PROGRAM_NAME} search <query> [options]
+
+ARGUMENTS
+  query                             Search term (required)
+
+OPTIONS
+  --category <type>                 Filter by type: component, icon, all
+                                    (default: all)
+  --no-split-terms                  Don't split query on spaces/commas
+  --match-all                       Require ALL terms to match (AND logic)
+  --use-regex                       Treat query as a regular expression
+  --max-results <n>                 Maximum results to return, 1-100
+                                    (default: 20)
+  -h, --help                        Show this help message
+
+EXAMPLES
+  ${PROGRAM_NAME} search button
+  ${PROGRAM_NAME} search "dropdown menu" --match-all
+  ${PROGRAM_NAME} search "^gds-card" --use-regex
+  ${PROGRAM_NAME} search arrow --category icon
+  ${PROGRAM_NAME} search button | jq '.results[0]'
+`.trim();
+const DOCS_HELP = `
+Get complete documentation for a specific Green component, including
+framework-specific import paths, API reference, and design guidelines.
+
+USAGE
+  ${PROGRAM_NAME} docs <component> <framework> [options]
+
+ARGUMENTS
+  component                         Component name, e.g. "button" or
+                                    "gds-button" (required)
+  framework                         Target framework (required)
+                                    Allowed: ${DOCS_FRAMEWORK_CANONICAL.join(", ")}
+                                    Aliases: web, webcomponent, web-components
+
+OPTIONS
+  --no-guidelines                   Exclude UX/design guidelines
+  --no-instructions                 Exclude agent-specific instructions
+  -h, --help                        Show this help message
+
+EXAMPLES
+  ${PROGRAM_NAME} docs button angular
+  ${PROGRAM_NAME} docs gds-dropdown react
+  ${PROGRAM_NAME} docs card web
+  ${PROGRAM_NAME} docs card web-component --no-guidelines
+`.trim();
+const GET_HELP = `
+Fetch raw content for a green:// resource URI. Use 'search' to discover
+URIs, then use 'get' to retrieve the raw document content.
+
+USAGE
+  ${PROGRAM_NAME} get <uri>
+
+ARGUMENTS
+  uri                               A green:// resource URI (required)
+
+SUPPORTED URI FORMATS
+  green://components/{name}/{doc}   Component docs (api, angular, react,
+                                    guidelines, instructions)
+  green://icons/{name}/{doc}        Icon docs (api, angular, react)
+  green://guides/{name}             Setup and framework guides
+  green://concepts/{name}           Conceptual documentation
+  green://instructions              Base instructions document
+
+OPTIONS
+  -h, --help                        Show this help message
+
+EXAMPLES
+  ${PROGRAM_NAME} get green://components/button/api
+  ${PROGRAM_NAME} get green://components/dropdown/angular
+  ${PROGRAM_NAME} get green://guides/react
+  ${PROGRAM_NAME} get green://concepts/tokens
+  ${PROGRAM_NAME} get green://instructions
+`.trim();
+const GUIDES_HELP = `
+List available setup guides and conceptual documentation.
+
+USAGE
+  ${PROGRAM_NAME} guides [options]
+
+OPTIONS
+  --category <type>                 Filter by category: framework-setup,
+                                    getting-started, concepts,
+                                    troubleshooting, migration, all
+                                    (default: all)
+  --framework <name>                Filter by framework: angular, react, all
+  -h, --help                        Show this help message
+
+EXAMPLES
+  ${PROGRAM_NAME} guides
+  ${PROGRAM_NAME} guides --category concepts
+  ${PROGRAM_NAME} guides --framework angular
+`.trim();
+const GUIDE_HELP = `
+Get the full content of a specific guide.
+
+USAGE
+  ${PROGRAM_NAME} guide <name>
+
+ARGUMENTS
+  name                              Guide name, e.g. "angular", "installing",
+                                    "troubleshooting" (required).
+                                    Run '${PROGRAM_NAME} guides' to see
+                                    available guide names.
+
+OPTIONS
+  -h, --help                        Show this help message
+
+EXAMPLES
+  ${PROGRAM_NAME} guide angular
+  ${PROGRAM_NAME} guide troubleshooting | less
+`.trim();
+const INSTRUCTIONS_HELP = `
+Get the base instructions for using Green Design System. Contains critical
+rules, typography guidelines, layout system requirements, and best practices.
+
+USAGE
+  ${PROGRAM_NAME} instructions
+
+OPTIONS
+  -h, --help                        Show this help message
+`.trim();
+async function runSearch(args) {
+  if (args.flags["h"] || args.flags["help"]) {
+    process.stdout.write(SEARCH_HELP + "\n");
+    return;
+  }
+  const query = args.positional[0];
+  if (!query) {
+    process.stderr.write("Error: search requires a <query> argument.\n\n");
+    process.stderr.write(SEARCH_HELP + "\n");
+    process.exitCode = 1;
+    return;
+  }
+  const input = { query };
+  if (args.flags["category"] !== void 0) {
+    input.category = args.flags["category"];
+  }
+  if (args.flags["split-terms"] === false) {
+    input.splitTerms = false;
+  }
+  if (args.flags["match-all"]) {
+    input.matchAll = true;
+  }
+  if (args.flags["use-regex"]) {
+    input.useRegex = true;
+  }
+  if (args.flags["max-results"] !== void 0) {
+    const n = Number(args.flags["max-results"]);
+    if (Number.isNaN(n)) {
+      process.stderr.write("Error: --max-results must be a number.\n");
+      process.exitCode = 1;
+      return;
+    }
+    input.maxResults = n;
+  }
+  const result = await handleSearchComponents(input);
+  process.stdout.write(getPrimaryTextContent(result) + "\n");
+}
+async function runDocs(args) {
+  if (args.flags["h"] || args.flags["help"]) {
+    process.stdout.write(DOCS_HELP + "\n");
+    return;
+  }
+  const componentName = args.positional[0];
+  const frameworkInput = args.positional[1];
+  if (!componentName || !frameworkInput) {
+    process.stderr.write(
+      "Error: docs requires <component> and <framework> arguments.\n\n"
+    );
+    process.stderr.write(DOCS_HELP + "\n");
+    process.exitCode = 1;
+    return;
+  }
+  const framework = normalizeDocsFramework(frameworkInput);
+  if (!framework) {
+    process.stderr.write(
+      `Error: Invalid framework '${frameworkInput}'. Allowed values: ${DOCS_FRAMEWORK_CANONICAL.join(", ")}.
+`
+    );
+    process.stderr.write(
+      "Aliases accepted for web-component: web, webcomponent, web-components.\n\n"
+    );
+    process.stderr.write(DOCS_HELP + "\n");
+    process.exitCode = 1;
+    return;
+  }
+  const input = { componentName, framework };
+  if (args.flags["guidelines"] === false) {
+    input.includeGuidelines = false;
+  }
+  if (args.flags["instructions"] === false) {
+    input.includeInstructions = false;
+  }
+  const result = await handleGetComponentDocs(input);
+  process.stdout.write(getPrimaryTextContent(result) + "\n");
+}
+async function runGet(args) {
+  if (args.flags["h"] || args.flags["help"]) {
+    process.stdout.write(GET_HELP + "\n");
+    return;
+  }
+  const uri = args.positional[0];
+  if (!uri) {
+    process.stderr.write("Error: get requires a <uri> argument.\n\n");
+    process.stderr.write(GET_HELP + "\n");
+    process.exitCode = 1;
+    return;
+  }
+  const result = await handleResolveUri(uri);
+  process.stdout.write(getPrimaryTextContent(result) + "\n");
+}
+async function runGuides(args) {
+  if (args.flags["h"] || args.flags["help"]) {
+    process.stdout.write(GUIDES_HELP + "\n");
+    return;
+  }
+  const input = {};
+  if (args.flags["category"] !== void 0) {
+    input.category = args.flags["category"];
+  }
+  if (args.flags["framework"] !== void 0) {
+    input.framework = args.flags["framework"];
+  }
+  const result = await handleListGuides(input);
+  process.stdout.write(getPrimaryTextContent(result) + "\n");
+}
+async function runGuide(args) {
+  if (args.flags["h"] || args.flags["help"]) {
+    process.stdout.write(GUIDE_HELP + "\n");
+    return;
+  }
+  const name = args.positional[0];
+  if (!name) {
+    process.stderr.write("Error: guide requires a <name> argument.\n\n");
+    process.stderr.write(GUIDE_HELP + "\n");
+    process.exitCode = 1;
+    return;
+  }
+  const result = await handleGetGuide({ name });
+  process.stdout.write(getPrimaryTextContent(result) + "\n");
+}
+async function runInstructions(args) {
+  if (args.flags["h"] || args.flags["help"]) {
+    process.stdout.write(INSTRUCTIONS_HELP + "\n");
+    return;
+  }
+  const result = await handleGetInstructions();
+  const cliText = getPrimaryTextContent(result).replace(/\bMCP server\b/gi, "Context CLI").replace(/\bMCP Server\b/g, "Context CLI").replace(/\bMCP\b/g, "CLI");
+  process.stdout.write(cliText + "\n");
+}
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.flags["v"] || args.flags["version"]) {
+    const version = await getPackageVersion();
+    process.stdout.write(version + "\n");
+    return;
+  }
+  if (!args.command) {
+    process.stdout.write(HELP_TEXT + "\n");
+    return;
+  }
+  switch (args.command) {
+    case "search":
+      await runSearch(args);
+      break;
+    case "docs":
+      await runDocs(args);
+      break;
+    case "get":
+      await runGet(args);
+      break;
+    case "guides":
+      await runGuides(args);
+      break;
+    case "guide":
+      await runGuide(args);
+      break;
+    case "instructions":
+      await runInstructions(args);
+      break;
+    default:
+      process.stderr.write(`Error: Unknown command '${args.command}'.
+
+`);
+      process.stdout.write(HELP_TEXT + "\n");
+      process.exitCode = 1;
+  }
+}
+main().catch((error) => {
+  if (error instanceof McpError) {
+    process.stderr.write(`Error [${error.code}]: ${error.message}
+`);
+  } else if (error instanceof Error) {
+    process.stderr.write(`Error: ${error.message}
+`);
+  } else {
+    process.stderr.write(`Error: ${String(error)}
+`);
+  }
+  process.exitCode = 1;
+});
+export {
+  parseArgs2 as parseArgs
+};

package/bin/context-cli/parse-args.d.ts

@@ -0,0 +1,22 @@
+/** Parsed result from the argument parser */
+export interface ParsedArgs {
+    /** The subcommand (or null for top-level flags like --help / --version) */
+    command: string | null;
+    /** Positional arguments following the subcommand */
+    positional: string[];
+    /** Named flags (e.g. --category → category) mapped to their values */
+    flags: Record<string, string | boolean>;
+}
+/**
+ * Parse process.argv into a structured object.
+ *
+ * Supports:
+ * - Positional arguments
+ * - Long flags: --flag, --flag value, --flag=value
+ * - Short flags: -h, -v
+ * - Boolean negation: --no-<flag> → flag = false
+ *
+ * @param argv - Raw argument array (typically process.argv.slice(2))
+ * @returns Parsed command, positional args, and flags
+ */
+export declare function parseArgs(argv: string[]): ParsedArgs;

package/bin/context-cli/parse-args.js

@@ -0,0 +1,46 @@
+import "../../chunks/chunk.QU3DSPNU.js";
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === "--") {
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith("--")) {
+      const eqIndex = arg.indexOf("=");
+      if (eqIndex !== -1) {
+        const key = arg.slice(2, eqIndex);
+        flags[key] = arg.slice(eqIndex + 1);
+      } else {
+        const key = arg.slice(2);
+        if (key.startsWith("no-")) {
+          flags[key.slice(3)] = false;
+        } else {
+          const next = argv[i + 1];
+          if (next !== void 0 && !next.startsWith("-")) {
+            flags[key] = next;
+            i++;
+          } else {
+            flags[key] = true;
+          }
+        }
+      }
+    } else if (arg.startsWith("-") && arg.length === 2) {
+      flags[arg.slice(1)] = true;
+    } else {
+      positional.push(arg);
+    }
+    i++;
+  }
+  return {
+    command: positional.length > 0 ? positional[0] : null,
+    positional: positional.slice(1),
+    flags
+  };
+}
+export {
+  parseArgs
+};

package/bin/mcp-server/errors.d.ts

@@ -1,6 +1,7 @@
 /**
  * Error handling for the Green Design System MCP Server
  */
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 /**
  * Error codes for MCP operations
  */
@@ -75,13 +76,7 @@ export declare class RegexError extends McpError {
  * @param error - The error to convert
  * @returns Formatted error response
  */
-export declare function formatErrorResponse(error: unknown): {
-    content: Array<{
-        type: string;
-        text: string;
-    }>;
-    isError: boolean;
-};
+export declare function formatErrorResponse(error: unknown): CallToolResult;
 /**
  * Log error with structured information
  * @param error - The error to log

package/bin/mcp-server/handlers.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Tool handler implementations for the Green Design System.
+ *
+ * This module contains the core business logic for each tool operation:
+ * searching components, fetching documentation, listing guides, and
+ * retrieving instructions. These handlers are shared between the MCP
+ * server (tools.ts) and the context CLI (context-cli/index.ts).
+ *
+ * Each handler:
+ * 1. Validates its input via the validation module
+ * 2. Loads pre-generated MCP data from disk
+ * 3. Applies business logic (search, filtering, assembly)
+ * 4. Returns a uniform `{ content: [{ type: 'text', text: string }] }` response
+ *
+ * @module handlers
+ */
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Standard response shape returned by all handlers.
+ * Mirrors the MCP content response format so both the MCP server
+ * and the CLI can consume results uniformly.
+ */
+export type HandlerResponse = CallToolResult;
+/**
+ * Handle search_components — search for components and icons by name,
+ * description, or functionality.
+ *
+ * @param input - Raw input object (validated internally)
+ * @returns Search results as JSON text
+ * @throws {ValidationError} If input fails validation
+ */
+export declare function handleSearchComponents(input: unknown): Promise<HandlerResponse>;
+/**
+ * Handle get_component_docs — retrieve full documentation for a specific
+ * component, including framework-specific imports, API reference, design
+ * guidelines, and agent usage instructions.
+ *
+ * @param input - Raw input object (validated internally)
+ * @returns Assembled markdown documentation
+ * @throws {ValidationError} If input fails validation
+ * @throws {NotFoundError} If the component cannot be found
+ */
+export declare function handleGetComponentDocs(input: unknown): Promise<HandlerResponse>;
+/**
+ * Handle list_guides — list available setup guides and conceptual
+ * documentation, optionally filtered by category and framework.
+ *
+ * @param input - Raw input object (validated internally)
+ * @returns JSON list of guides with metadata and resource URIs
+ * @throws {ValidationError} If input fails validation
+ * @throws {NotFoundError} If the global index cannot be loaded
+ */
+export declare function handleListGuides(input: unknown): Promise<HandlerResponse>;
+/**
+ * Handle get_guide — retrieve the full content of a specific guide.
+ *
+ * @param input - Raw input object (validated internally)
+ * @returns Guide content as markdown
+ * @throws {ValidationError} If input fails validation
+ * @throws {NotFoundError} If the guide cannot be found
+ */
+export declare function handleGetGuide(input: unknown): Promise<HandlerResponse>;
+/**
+ * Handle get_instructions — retrieve the base instructions document
+ * containing critical rules, typography guidelines, layout system
+ * requirements, and general best practices.
+ *
+ * @returns Instructions content as markdown
+ * @throws {NotFoundError} If instructions are not available
+ */
+export declare function handleGetInstructions(): Promise<HandlerResponse>;
+/**
+ * Handle URI resolution — read the raw content of a green:// resource URI.
+ *
+ * Supports all URI types:
+ * - green://components/{name}/{docType}  (e.g. green://components/button/api)
+ * - green://icons/{name}/{docType}       (e.g. green://icons/arrow/api)
+ * - green://guides/{name}                (e.g. green://guides/angular)
+ * - green://concepts/{name}              (e.g. green://concepts/tokens)
+ * - green://instructions                 (the root instructions document)
+ *
+ * @param uri - A green:// resource URI string
+ * @returns Raw markdown content of the resource
+ * @throws {NotFoundError} If the URI is invalid or the resource doesn't exist
+ */
+export declare function handleResolveUri(uri: string): Promise<HandlerResponse>;