@lostgradient/cinder 0.5.0 → 0.6.0

package/dist/cli/index.js

@@ -0,0 +1,978 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/cli/best-practices.ts
+var bestPracticeSections;
+var init_best_practices = __esm(() => {
+  bestPracticeSections = {
+    imports: {
+      topic: "imports",
+      title: "Imports",
+      guidance: [
+        "Import the base stylesheet once at the app entry before any component sidecar styles.",
+        "Prefer component subpaths such as @lostgradient/cinder/button in application code for the smallest import graph.",
+        "Use the root barrel when convenience matters more than per-file tree-shaking.",
+        "Use the kebab-case manifest id when cross-referencing components in tools or generated code."
+      ]
+    },
+    styles: {
+      topic: "styles",
+      title: "Styles",
+      guidance: [
+        "Load @lostgradient/cinder/styles first; it declares cascade layer order, tokens, foundation rules, utilities, and shared internal chrome.",
+        "Import @lostgradient/cinder/<component>/styles beside each component when using the slim, tree-shaken CSS path.",
+        "Use @lostgradient/cinder/styles/all only when shipping every component style is acceptable.",
+        "Override public --cinder-* tokens and component root classes; do not redefine private --_cinder-* variables."
+      ]
+    },
+    metadata: {
+      topic: "metadata",
+      title: "Metadata",
+      guidance: [
+        "Read @lostgradient/cinder/manifest first; it is the authoritative component index for agents.",
+        "Use schema and variables artifacts for prop contracts and CSS custom-property names.",
+        "Fetch examples only when hasExamples is true and constraints only when hasConstraints is true.",
+        "Treat constraints as the source for cross-prop rules that JSON Schema cannot express cleanly."
+      ]
+    },
+    overlap: {
+      topic: "overlap",
+      title: "Overlap Decisions",
+      guidance: [
+        "Use overlapFamilies when multiple components solve similar problems.",
+        "Prefer each candidate component useWhen and avoidWhen guidance over name similarity.",
+        "Compare related components before introducing bespoke UI for overlays, notices, selection controls, hover surfaces, or tabs.",
+        "When no Cinder component fits, compose from Cinder primitives before introducing a fully bespoke surface."
+      ]
+    }
+  };
+});
+
+// src/cli/types.ts
+var CinderKnowledgeError;
+var init_types = __esm(() => {
+  CinderKnowledgeError = class CinderKnowledgeError extends Error {
+    code;
+    suggestions;
+    constructor(code, message, suggestions = []) {
+      super(message);
+      this.name = "CinderKnowledgeError";
+      this.code = code;
+      this.suggestions = suggestions;
+    }
+  };
+});
+
+// src/cli/manifest-validation.ts
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isAvoidWhenArray(value) {
+  return Array.isArray(value) && value.every((item) => isRecord(item) && typeof item["reason"] === "string" && (item["alternative"] === undefined || typeof item["alternative"] === "string"));
+}
+function isPackageMetadata(value) {
+  return isRecord(value) && typeof value["name"] === "string" && typeof value["version"] === "string" && typeof value["framework"] === "string" && typeof value["frameworkVersionRange"] === "string" && typeof value["stylesEntry"] === "string" && typeof value["schemaDialect"] === "string";
+}
+function isCategoryMap(value) {
+  return isRecord(value) && Object.values(value).every((category) => isRecord(category) && typeof category["label"] === "string" && typeof category["description"] === "string");
+}
+function isStatusLevelMap(value) {
+  return isRecord(value) && Object.values(value).every((status) => typeof status === "string");
+}
+function isOverlapFamilyMap(value) {
+  return isRecord(value) && Object.values(value).every(isStringArray);
+}
+function isManifestComponent(value) {
+  if (!isRecord(value))
+    return false;
+  const artifacts = value["artifacts"];
+  return typeof value["id"] === "string" && typeof value["name"] === "string" && typeof value["import"] === "string" && typeof value["exportName"] === "string" && typeof value["category"] === "string" && typeof value["status"] === "string" && typeof value["purpose"] === "string" && isStringArray(value["tags"]) && isStringArray(value["useWhen"]) && isAvoidWhenArray(value["avoidWhen"]) && isStringArray(value["related"]) && typeof value["hasConstraints"] === "boolean" && typeof value["hasExamples"] === "boolean" && isRecord(artifacts) && typeof artifacts["schema"] === "string" && typeof artifacts["variables"] === "string" && (artifacts["examples"] === undefined || typeof artifacts["examples"] === "string") && (artifacts["constraints"] === undefined || typeof artifacts["constraints"] === "string");
+}
+function validateManifest(value) {
+  if (!isRecord(value)) {
+    throw new CinderKnowledgeError("INVALID_MANIFEST", "components.json must be an object.");
+  }
+  const manifestVersion = value["manifestVersion"];
+  const packageValue = value["package"];
+  const components = value["components"];
+  const categories = value["categories"];
+  const statusLevels = value["statusLevels"];
+  const overlapFamilies = value["overlapFamilies"];
+  if (manifestVersion !== 1) {
+    throw new CinderKnowledgeError("INVALID_MANIFEST", "components.json must use manifestVersion 1.");
+  }
+  if (!isPackageMetadata(packageValue) || !Array.isArray(components)) {
+    throw new CinderKnowledgeError("INVALID_MANIFEST", "components.json is missing package metadata or components.");
+  }
+  if (!isCategoryMap(categories) || !isStatusLevelMap(statusLevels) || !isOverlapFamilyMap(overlapFamilies)) {
+    throw new CinderKnowledgeError("INVALID_MANIFEST", "components.json is missing category, status, or overlap metadata.");
+  }
+  const manifestComponents = components.map((component) => {
+    if (!isManifestComponent(component)) {
+      throw new CinderKnowledgeError("INVALID_MANIFEST", "Every manifest component must include the generated component contract fields.");
+    }
+    return component;
+  });
+  return {
+    manifestVersion,
+    package: packageValue,
+    categories,
+    statusLevels,
+    overlapFamilies,
+    components: manifestComponents
+  };
+}
+var init_manifest_validation = __esm(() => {
+  init_types();
+});
+
+// src/cli/knowledge.ts
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { createRequire as createRequire2 } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+function normalize(value) {
+  return value.trim().toLowerCase();
+}
+function tokenize(value) {
+  return normalize(value).split(/[^a-z0-9]+/u).filter((token) => token.length > 0);
+}
+function unique(values) {
+  return [...new Set(values)];
+}
+function levenshtein(left, right) {
+  const rows = Array.from({ length: left.length + 1 }, (_, index) => [index]);
+  for (let column = 1;column <= right.length; column += 1)
+    rows[0][column] = column;
+  for (let row = 1;row <= left.length; row += 1) {
+    for (let column = 1;column <= right.length; column += 1) {
+      const cost = left[row - 1] === right[column - 1] ? 0 : 1;
+      rows[row][column] = Math.min(rows[row - 1][column] + 1, rows[row][column - 1] + 1, rows[row - 1][column - 1] + cost);
+    }
+  }
+  return rows[left.length][right.length];
+}
+function textIncludesToken(value, token) {
+  return normalize(value).includes(token);
+}
+function componentDirectory(component, packageRoot) {
+  const suffix = component.import.replace(/^@lostgradient\/cinder\//u, "");
+  const segments = suffix.startsWith("experimental/") ? ["src", "components", "experimental", suffix.replace(/^experimental\//u, "")] : ["src", "components", suffix];
+  return join(packageRoot, ...segments);
+}
+async function readJsonFile(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+async function loadMetadataJson(component, kind, packageRoot) {
+  const localPath = join(componentDirectory(component, packageRoot), `${component.id}.${kind}.json`);
+  if (existsSync(localPath)) {
+    return readJsonFile(localPath);
+  }
+  throw new CinderKnowledgeError("ARTIFACT_NOT_FOUND", `${component.id} does not ship a ${kind} JSON artifact.`, [component.id]);
+}
+async function loadJsonArtifact(component, kind, packageRoot) {
+  const specifier = component.artifacts[kind];
+  if (!specifier) {
+    throw new CinderKnowledgeError("ARTIFACT_NOT_FOUND", `${component.id} does not ship a ${kind} artifact.`, [component.id]);
+  }
+  const localPath = join(componentDirectory(component, packageRoot), `${component.id}.${kind}.json`);
+  if (existsSync(localPath))
+    return readJsonFile(localPath);
+  return requireFromCli(specifier);
+}
+function toSummary(component, overlapFamilies) {
+  const componentOverlapFamilies = Object.entries(overlapFamilies).filter(([, members]) => members.includes(component.id)).map(([family]) => family);
+  componentOverlapFamilies.sort();
+  return {
+    id: component.id,
+    name: component.name,
+    exportName: component.exportName,
+    import: component.import,
+    category: component.category,
+    status: component.status,
+    purpose: component.purpose,
+    tags: component.tags,
+    useWhen: component.useWhen,
+    avoidWhen: component.avoidWhen,
+    related: component.related,
+    overlapFamilies: componentOverlapFamilies,
+    hasExamples: component.hasExamples,
+    hasConstraints: component.hasConstraints
+  };
+}
+
+class CinderKnowledge {
+  manifest;
+  package;
+  packageRoot;
+  byId;
+  constructor(manifest, packageRoot = defaultPackageRoot) {
+    this.manifest = manifest;
+    this.package = {
+      name: manifest.package.name,
+      version: manifest.package.version
+    };
+    this.packageRoot = packageRoot;
+    this.byId = new Map(manifest.components.map((component) => [component.id, component]));
+  }
+  list(options = {}) {
+    this.validateFilters(options);
+    return this.manifest.components.filter((component) => this.matchesFilters(component, options)).map((component) => toSummary(component, this.manifest.overlapFamilies));
+  }
+  search(query, options = {}) {
+    const tokens = tokenize(query);
+    if (tokens.length === 0) {
+      throw new CinderKnowledgeError("BAD_QUERY", "Search query must contain at least one token.");
+    }
+    this.validateFilters(options);
+    const limit = options.limit ?? 10;
+    const results = this.manifest.components.filter((component) => this.matchesFilters(component, options)).map((component) => this.scoreComponent(component, query, tokens)).filter((result) => result.score > 0);
+    results.sort((left, right) => right.score - left.score || left.id.localeCompare(right.id));
+    return results.slice(0, limit);
+  }
+  async show(idOrName) {
+    const component = this.findComponent(idOrName);
+    const detail = {
+      component,
+      overlapFamilies: toSummary(component, this.manifest.overlapFamilies).overlapFamilies,
+      schema: await loadMetadataJson(component, "schema", this.packageRoot),
+      variables: await loadMetadataJson(component, "variables", this.packageRoot)
+    };
+    if (component.hasExamples) {
+      detail.examples = await loadJsonArtifact(component, "examples", this.packageRoot);
+    }
+    if (component.hasConstraints) {
+      detail.constraints = await loadJsonArtifact(component, "constraints", this.packageRoot);
+    }
+    return detail;
+  }
+  compare(idsOrNames) {
+    if (idsOrNames.length < 2) {
+      throw new CinderKnowledgeError("BAD_COMPARE", "Compare requires at least two component ids.", this.manifest.components.slice(0, 5).map((component) => component.id));
+    }
+    const components = idsOrNames.map((id) => toSummary(this.findComponent(id), this.manifest.overlapFamilies));
+    const componentIds = new Set(components.map((component) => component.id));
+    const sharedOverlapFamilies = {};
+    for (const [family, members] of Object.entries(this.manifest.overlapFamilies)) {
+      const selected = members.filter((member) => componentIds.has(member));
+      if (selected.length > 1)
+        sharedOverlapFamilies[family] = selected;
+    }
+    return {
+      components,
+      sharedOverlapFamilies,
+      guidance: [
+        "Start with purpose, then use useWhen and avoidWhen as the tiebreaker.",
+        "If the components share an overlap family, prefer the component whose avoidWhen entries do not describe your scenario.",
+        "When a component has constraints, read them before generating code."
+      ]
+    };
+  }
+  bestPractices(topic = "all") {
+    if (topic === "all")
+      return Object.values(bestPracticeSections);
+    const section = bestPracticeSections[topic];
+    if (!section) {
+      throw new CinderKnowledgeError("BAD_TOPIC", `Unknown best-practices topic "${topic}".`, [
+        "imports",
+        "styles",
+        "metadata",
+        "overlap",
+        "all"
+      ]);
+    }
+    return [section];
+  }
+  async artifact(idOrName, kind) {
+    const component = this.findComponent(idOrName);
+    if (kind === "schema" || kind === "variables") {
+      return loadMetadataJson(component, kind, this.packageRoot);
+    }
+    return loadJsonArtifact(component, kind, this.packageRoot);
+  }
+  componentIds() {
+    return this.manifest.components.map((component) => component.id);
+  }
+  suggestComponentIds(value, limit = 5) {
+    const normalized = normalize(value);
+    const suggestions = this.manifest.components.map((component) => ({
+      id: component.id,
+      distance: levenshtein(normalized, component.id),
+      substring: component.id.includes(normalized) || normalize(component.name).includes(normalized)
+    }));
+    suggestions.sort((left, right) => Number(right.substring) - Number(left.substring) || left.distance - right.distance || left.id.localeCompare(right.id));
+    return suggestions.slice(0, limit).map((component) => component.id);
+  }
+  findComponent(idOrName) {
+    const normalized = normalize(idOrName);
+    const exact = this.byId.get(normalized);
+    if (exact)
+      return exact;
+    const byExportName = this.manifest.components.find((component) => normalize(component.exportName) === normalized || normalize(component.name) === normalized);
+    if (byExportName)
+      return byExportName;
+    throw new CinderKnowledgeError("COMPONENT_NOT_FOUND", `Unknown Cinder component "${idOrName}".`, this.suggestComponentIds(idOrName));
+  }
+  validateFilters(options) {
+    if (options.category && !Object.hasOwn(this.manifest.categories, options.category)) {
+      const categorySuggestions = Object.keys(this.manifest.categories);
+      categorySuggestions.sort();
+      throw new CinderKnowledgeError("BAD_CATEGORY", `Unknown category "${options.category}".`, categorySuggestions);
+    }
+    if (options.status && !Object.hasOwn(this.manifest.statusLevels, options.status)) {
+      const statusSuggestions = Object.keys(this.manifest.statusLevels);
+      statusSuggestions.sort();
+      throw new CinderKnowledgeError("BAD_STATUS", `Unknown status "${options.status}".`, statusSuggestions);
+    }
+  }
+  matchesFilters(component, options) {
+    if (options.category && component.category !== options.category)
+      return false;
+    if (options.status && component.status !== options.status)
+      return false;
+    if (options.tag && !component.tags.includes(options.tag))
+      return false;
+    return true;
+  }
+  scoreComponent(component, query, tokens) {
+    const matched = [];
+    let score = 0;
+    const normalizedQuery = normalize(query);
+    if (normalizedQuery === component.id || normalizedQuery === normalize(component.exportName)) {
+      score += 1e4;
+      matched.push("exact");
+    }
+    const fields = [
+      ["id", 200, [component.id, component.name, component.exportName]],
+      ["tags", 80, component.tags],
+      ["category", 60, [component.category, component.status]],
+      ["purpose", 40, [component.purpose]],
+      ["useWhen", 30, component.useWhen],
+      [
+        "avoidWhen",
+        25,
+        component.avoidWhen.map((entry) => `${entry.reason} ${entry.alternative ?? ""}`)
+      ],
+      ["related", 20, component.related]
+    ];
+    for (const token of tokens) {
+      for (const [field, weight, values] of fields) {
+        if (values.some((value) => textIncludesToken(value, token))) {
+          score += weight;
+          matched.push(field);
+        }
+      }
+      for (const [family, members] of Object.entries(this.manifest.overlapFamilies)) {
+        if (family.includes(token) && members.includes(component.id)) {
+          score += 35;
+          matched.push(`overlap:${family}`);
+        } else if (members.some((member) => member.includes(token)) && members.includes(component.id)) {
+          score += 10;
+          matched.push(`overlap:${family}`);
+        }
+      }
+    }
+    const matchedFields = unique(matched);
+    matchedFields.sort();
+    return {
+      ...toSummary(component, this.manifest.overlapFamilies),
+      score,
+      matched: matchedFields
+    };
+  }
+}
+async function loadCinderKnowledge(packageRoot = defaultPackageRoot) {
+  const manifest = validateManifest(await readJsonFile(join(packageRoot, "components.json")));
+  return new CinderKnowledge(manifest, packageRoot);
+}
+var cliDirectory, defaultPackageRoot, requireFromCli;
+var init_knowledge = __esm(() => {
+  init_best_practices();
+  init_manifest_validation();
+  init_types();
+  cliDirectory = dirname(fileURLToPath(import.meta.url));
+  defaultPackageRoot = resolve(cliDirectory, "..", "..");
+  requireFromCli = createRequire2(import.meta.url);
+});
+
+// src/cli/mcp.ts
+var exports_mcp = {};
+__export(exports_mcp, {
+  runMcpServer: () => runMcpServer,
+  createMcpServer: () => createMcpServer
+});
+import * as z from "zod/v4";
+function textResult(text, structuredContent) {
+  return {
+    content: [{ type: "text", text }],
+    structuredContent
+  };
+}
+function jsonText(value) {
+  return JSON.stringify(value, null, 2);
+}
+function errorPayload(error) {
+  return {
+    code: error instanceof CinderKnowledgeError ? error.code : "UNEXPECTED_ERROR",
+    message: error instanceof Error ? error.message : String(error),
+    suggestions: error instanceof CinderKnowledgeError ? error.suggestions : []
+  };
+}
+function toolError(error) {
+  const payload = errorPayload(error);
+  return {
+    isError: true,
+    content: [{ type: "text", text: payload.message }],
+    structuredContent: { error: payload }
+  };
+}
+function resourceError(error, dependencies) {
+  const payload = errorPayload(error);
+  const protocolCode = error instanceof CinderKnowledgeError ? dependencies.ErrorCode.InvalidParams : dependencies.ErrorCode.InternalError;
+  throw new dependencies.McpError(protocolCode, payload.message, { error: payload });
+}
+function firstVariable(value) {
+  if (Array.isArray(value))
+    return value[0] ?? "";
+  return value ?? "";
+}
+function jsonResource(uri, value) {
+  return {
+    contents: [
+      {
+        uri,
+        mimeType: "application/json",
+        text: jsonText(value)
+      }
+    ]
+  };
+}
+async function readJsonResource(uri, read, dependencies) {
+  try {
+    return jsonResource(uri.href, await read());
+  } catch (error) {
+    resourceError(error, dependencies);
+  }
+}
+function componentResourceList(knowledge, suffix = "") {
+  return {
+    resources: knowledge.list().filter((component) => {
+      if (suffix === "/examples")
+        return component.hasExamples;
+      if (suffix === "/constraints")
+        return component.hasConstraints;
+      return true;
+    }).map((component) => ({
+      uri: `cinder://component/${component.id}${suffix}`,
+      name: `${component.id}${suffix.replace("/", "-") || "-component"}`,
+      title: `${component.name}${suffix ? ` ${suffix.slice(1)}` : ""}`,
+      description: component.purpose,
+      mimeType: "application/json"
+    }))
+  };
+}
+function searchOptionsFromArgs(args) {
+  const options = {};
+  if (args.category !== undefined)
+    options.category = args.category;
+  if (args.status !== undefined)
+    options.status = args.status;
+  if (args.tag !== undefined)
+    options.tag = args.tag;
+  if (args.limit !== undefined)
+    options.limit = args.limit;
+  return options;
+}
+function registerTools(server, knowledge) {
+  server.registerTool("search_components", {
+    title: "Search Cinder components",
+    description: "Search Cinder components by purpose, id, tag, category, guidance, or overlap family.",
+    inputSchema: z.object({
+      query: z.string().min(1),
+      category: z.string().optional(),
+      status: z.string().optional(),
+      tag: z.string().optional(),
+      limit: z.number().int().min(1).max(50).optional()
+    })
+  }, async (args) => {
+    try {
+      const data = knowledge.search(args.query, searchOptionsFromArgs(args));
+      return textResult(jsonText(data), { results: data });
+    } catch (error) {
+      return toolError(error);
+    }
+  });
+  server.registerTool("get_component", {
+    title: "Get Cinder component",
+    description: "Return manifest guidance plus schema, variables, examples, and constraints for one component.",
+    inputSchema: z.object({ id: z.string().min(1) })
+  }, async ({ id }) => {
+    try {
+      const data = await knowledge.show(id);
+      return textResult(jsonText(data), { component: data });
+    } catch (error) {
+      return toolError(error);
+    }
+  });
+  server.registerTool("compare_components", {
+    title: "Compare Cinder components",
+    description: "Compare two or more Cinder components using manifest useWhen, avoidWhen, and overlap guidance.",
+    inputSchema: z.object({ ids: z.array(z.string().min(1)).min(2).max(12) })
+  }, async ({ ids }) => {
+    try {
+      const data = knowledge.compare(ids);
+      return textResult(jsonText(data), { comparison: data });
+    } catch (error) {
+      return toolError(error);
+    }
+  });
+  server.registerTool("get_best_practices", {
+    title: "Get Cinder best practices",
+    description: "Return Cinder import, style, metadata, and overlap decision guidance.",
+    inputSchema: z.object({
+      topic: z.enum(["imports", "styles", "metadata", "overlap", "all"]).optional()
+    })
+  }, async ({ topic }) => {
+    try {
+      const selectedTopic = topic ?? "all";
+      const data = knowledge.bestPractices(selectedTopic);
+      return textResult(jsonText(data), { sections: data });
+    } catch (error) {
+      return toolError(error);
+    }
+  });
+}
+function registerResources(server, knowledge, ResourceTemplate, dependencies) {
+  server.registerResource("manifest", "cinder://manifest", {
+    title: "Cinder manifest",
+    description: "The full generated Cinder component manifest.",
+    mimeType: "application/json"
+  }, (uri) => jsonResource(uri.href, knowledge.manifest));
+  const complete = {
+    id: (value) => knowledge.componentIds().filter((id) => id.startsWith(value)).slice(0, 20)
+  };
+  server.registerResource("component", new ResourceTemplate("cinder://component/{id}", {
+    list: () => componentResourceList(knowledge),
+    complete
+  }), {
+    title: "Cinder component",
+    description: "Manifest guidance and generated artifacts for one Cinder component.",
+    mimeType: "application/json"
+  }, async (uri, variables) => readJsonResource(uri, () => knowledge.show(firstVariable(variables["id"])), dependencies));
+  for (const artifact of ["schema", "variables", "examples", "constraints"]) {
+    server.registerResource(`component-${artifact}`, new ResourceTemplate(`cinder://component/{id}/${artifact}`, {
+      list: () => componentResourceList(knowledge, `/${artifact}`),
+      complete
+    }), {
+      title: `Cinder component ${artifact}`,
+      description: `Generated ${artifact} artifact for one Cinder component.`,
+      mimeType: "application/json"
+    }, async (uri, variables) => readJsonResource(uri, () => knowledge.artifact(firstVariable(variables["id"]), artifact), dependencies));
+  }
+}
+function registerPrompts(server) {
+  server.registerPrompt("choose_cinder_component", {
+    title: "Choose a Cinder component",
+    description: "Guide an agent to choose an appropriate Cinder component before writing UI.",
+    argsSchema: {
+      goal: z.string().optional(),
+      constraints: z.string().optional()
+    }
+  }, ({ goal, constraints }) => {
+    const constraintsLine = constraints ? `Constraints: ${constraints}
+` : "";
+    return {
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Choose the best @lostgradient/cinder component for this UI task: ${goal ?? "unspecified task"}.
+` + constraintsLine + "Use search_components first, then compare_components for close alternatives, and read get_component before recommending code."
+          }
+        }
+      ]
+    };
+  });
+  server.registerPrompt("review_cinder_usage", {
+    title: "Review Cinder usage",
+    description: "Review code for Cinder import, style, metadata, and component-choice best practices.",
+    argsSchema: {
+      code: z.string(),
+      componentId: z.string().optional()
+    }
+  }, ({ code, componentId }) => {
+    const componentLine = componentId ? `Focus component: ${componentId}
+` : "";
+    return {
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Review this code for @lostgradient/cinder usage. Check component choice, imports, styles, constraints, and accessibility guidance.
+` + componentLine + `
+${code}`
+          }
+        }
+      ]
+    };
+  });
+}
+async function createMcpServer() {
+  const [{ McpServer, ResourceTemplate }, { ErrorCode, McpError }, knowledge] = await Promise.all([
+    import("@modelcontextprotocol/sdk/server/mcp.js"),
+    import("@modelcontextprotocol/sdk/types.js"),
+    loadCinderKnowledge()
+  ]);
+  const server = new McpServer({
+    name: "cinder",
+    version: knowledge.package.version
+  });
+  registerTools(server, knowledge);
+  registerResources(server, knowledge, ResourceTemplate, { ErrorCode, McpError });
+  registerPrompts(server);
+  return server;
+}
+async function runMcpServer() {
+  const [{ StdioServerTransport }, server] = await Promise.all([
+    import("@modelcontextprotocol/sdk/server/stdio.js"),
+    createMcpServer()
+  ]);
+  await server.connect(new StdioServerTransport);
+  await new Promise((resolve2) => {
+    const close = () => {
+      process.stdin.off("close", close);
+      process.stdin.off("end", close);
+      resolve2();
+    };
+    process.stdin.once("close", close);
+    process.stdin.once("end", close);
+  });
+}
+var init_mcp = __esm(() => {
+  init_knowledge();
+});
+
+// src/cli/index.ts
+init_knowledge();
+import { realpathSync } from "node:fs";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { parseArgs } from "node:util";
+
+// src/cli/output.ts
+function jsonEnvelope(packageSummary, command, data) {
+  return JSON.stringify({ package: packageSummary, command, data }, null, 2);
+}
+function jsonError(code, message, suggestions = []) {
+  return JSON.stringify({ error: { code, message, suggestions } }, null, 2);
+}
+function bulletList(items, indent = "  ") {
+  return items.map((item) => `${indent}- ${item}`);
+}
+function formatAvoidWhen(component) {
+  if (component.avoidWhen.length === 0)
+    return ["  Avoid when: none listed"];
+  return [
+    "  Avoid when:",
+    ...component.avoidWhen.map((entry) => `    - ${entry.reason}${entry.alternative ? ` Use ${entry.alternative}.` : ""}`)
+  ];
+}
+function formatImportStatement(component) {
+  return `import { ${component.exportName} } from '${component.import}';`;
+}
+function formatList(components) {
+  if (components.length === 0)
+    return "No Cinder components matched.";
+  return components.map((component) => `${component.id} (${component.category}, ${component.status})
+` + `  ${component.purpose}
+` + `  ${formatImportStatement(component)}`).join(`
+
+`);
+}
+function formatSearch(results) {
+  if (results.length === 0)
+    return "No Cinder components matched.";
+  return results.map((result) => `${result.id} (${result.category}, ${result.status}; score ${result.score})
+` + `  ${result.purpose}
+` + `  Use when: ${result.useWhen[0] ?? "No guidance listed."}
+` + `  Matched: ${result.matched.join(", ") || "n/a"}`).join(`
+
+`);
+}
+function formatDetail(detail) {
+  const { component, overlapFamilies } = detail;
+  const useWhen = component.useWhen.length > 0 ? bulletList(component.useWhen) : ["  No guidance listed."];
+  const lines = [
+    `${component.name} (${component.id})`,
+    component.purpose,
+    "",
+    `Import: ${formatImportStatement(component)}`,
+    `Category: ${component.category}`,
+    `Status: ${component.status}`,
+    `Tags: ${component.tags.join(", ") || "none"}`,
+    `Overlap families: ${overlapFamilies.join(", ") || "none"}`,
+    "",
+    "Use when:",
+    ...useWhen,
+    ...formatAvoidWhen({
+      ...component,
+      overlapFamilies
+    }),
+    "",
+    `Schema: ${component.artifacts.schema}`,
+    `Variables: ${component.artifacts.variables}`
+  ];
+  if (component.artifacts.examples)
+    lines.push(`Examples: ${component.artifacts.examples}`);
+  if (component.artifacts.constraints)
+    lines.push(`Constraints: ${component.artifacts.constraints}`);
+  return lines.join(`
+`);
+}
+function formatComparison(comparison) {
+  const lines = ["Component comparison", ""];
+  for (const component of comparison.components) {
+    lines.push(`${component.id} — ${component.purpose}`);
+    lines.push(`  Use when: ${component.useWhen[0] ?? "No guidance listed."}`);
+    const avoid = component.avoidWhen[0];
+    if (avoid)
+      lines.push(`  Avoid when: ${avoid.reason}${avoid.alternative ? ` Use ${avoid.alternative}.` : ""}`);
+    lines.push("");
+  }
+  const shared = Object.entries(comparison.sharedOverlapFamilies);
+  if (shared.length > 0) {
+    lines.push("Shared overlap families:");
+    for (const [family, members] of shared)
+      lines.push(`  - ${family}: ${members.join(", ")}`);
+    lines.push("");
+  }
+  lines.push("Guidance:");
+  lines.push(...bulletList(comparison.guidance));
+  return lines.join(`
+`).trimEnd();
+}
+function formatBestPractices(sections) {
+  return sections.map((section) => `${section.title}
+${bulletList(section.guidance).join(`
+`)}`).join(`
+
+`);
+}
+function formatHelp() {
+  return [
+    "cinder — Cinder component discovery for agents",
+    "",
+    "Usage:",
+    "  cinder list [--category <id>] [--status <level>] [--tag <tag>] [--json]",
+    "  cinder search <query> [--category <id>] [--status <level>] [--tag <tag>] [--limit <n>] [--json]",
+    "  cinder show <component-id> [--json]",
+    "  cinder compare <component-id>... [--json]",
+    "  cinder best-practices [imports|styles|metadata|overlap|all] [--json]",
+    "  cinder mcp",
+    "",
+    "Options:",
+    "  --json              Print deterministic JSON.",
+    "  --category <id>     Filter by manifest category.",
+    "  --status <level>    Filter by component status.",
+    "  --tag <tag>         Filter by tag.",
+    "  --limit <n>         Limit search results.",
+    "  -h, --help          Show help."
+  ].join(`
+`);
+}
+
+// src/cli/index.ts
+init_types();
+var bestPracticeTopics = new Set(["imports", "styles", "metadata", "overlap", "all"]);
+function isBestPracticeTopic(value) {
+  return bestPracticeTopics.has(value);
+}
+function parseLimit(value) {
+  if (value === undefined)
+    return;
+  if (!/^\d+$/.test(value)) {
+    throw new CinderKnowledgeError("BAD_LIMIT", "--limit must be a positive integer.");
+  }
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new CinderKnowledgeError("BAD_LIMIT", "--limit must be a positive integer.");
+  }
+  return parsed;
+}
+function setListOption(target, key, value) {
+  if (value !== undefined)
+    target[key] = value;
+}
+function parseCommand(argv) {
+  const parsed = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      category: { type: "string" },
+      status: { type: "string" },
+      tag: { type: "string" },
+      limit: { type: "string" },
+      json: { type: "boolean" },
+      help: { type: "boolean", short: "h" }
+    }
+  });
+  const [command = "help", ...positionals] = parsed.positionals;
+  const listOptions = {};
+  setListOption(listOptions, "category", parsed.values.category);
+  setListOption(listOptions, "status", parsed.values.status);
+  setListOption(listOptions, "tag", parsed.values.tag);
+  const searchOptions = { ...listOptions };
+  const limit = parseLimit(parsed.values.limit);
+  if (limit !== undefined)
+    searchOptions.limit = limit;
+  return {
+    command,
+    positionals,
+    json: parsed.values.json === true,
+    listOptions,
+    searchOptions,
+    help: parsed.values.help === true
+  };
+}
+async function runParsedCommand(parsed) {
+  if (parsed.help || parsed.command === "help" || parsed.command === "--help") {
+    const text = formatHelp();
+    if (parsed.json) {
+      const knowledge2 = await loadCinderKnowledge();
+      return { command: "help", data: { usage: text }, text, package: knowledge2.package };
+    }
+    return { command: "help", data: { usage: text }, text };
+  }
+  if (parsed.command === "mcp") {
+    const { runMcpServer: runMcpServer2 } = await Promise.resolve().then(() => (init_mcp(), exports_mcp));
+    await runMcpServer2();
+    return { command: "mcp", data: null, text: "" };
+  }
+  const knowledge = await loadCinderKnowledge();
+  switch (parsed.command) {
+    case "list": {
+      const data = knowledge.list(parsed.listOptions);
+      return { command: "list", data, text: formatList(data), package: knowledge.package };
+    }
+    case "search": {
+      const query = parsed.positionals.join(" ");
+      const data = knowledge.search(query, parsed.searchOptions);
+      return { command: "search", data, text: formatSearch(data), package: knowledge.package };
+    }
+    case "show": {
+      const id = parsed.positionals[0];
+      if (!id)
+        throw new CinderKnowledgeError("MISSING_COMPONENT", "show requires a component id.");
+      const data = await knowledge.show(id);
+      return { command: "show", data, text: formatDetail(data), package: knowledge.package };
+    }
+    case "compare": {
+      const data = knowledge.compare(parsed.positionals);
+      return { command: "compare", data, text: formatComparison(data), package: knowledge.package };
+    }
+    case "best-practices": {
+      const topic = parsed.positionals[0] ?? "all";
+      if (!isBestPracticeTopic(topic)) {
+        throw new CinderKnowledgeError("BAD_TOPIC", `Unknown best-practices topic "${topic}".`, [
+          "imports",
+          "styles",
+          "metadata",
+          "overlap",
+          "all"
+        ]);
+      }
+      const data = knowledge.bestPractices(topic);
+      return {
+        command: "best-practices",
+        data,
+        text: formatBestPractices(data),
+        package: knowledge.package
+      };
+    }
+    default:
+      throw new CinderKnowledgeError("UNKNOWN_COMMAND", `Unknown command "${parsed.command}".`, [
+        "list",
+        "search",
+        "show",
+        "compare",
+        "best-practices",
+        "mcp"
+      ]);
+  }
+}
+async function runCli(argv = process.argv.slice(2)) {
+  let parsed;
+  try {
+    parsed = parseCommand(argv);
+    const result = await runParsedCommand(parsed);
+    if (result.text.length > 0) {
+      let output = result.text;
+      if (parsed.json) {
+        if (!result.package) {
+          throw new CinderKnowledgeError("PACKAGE_UNAVAILABLE", "Package metadata was not available for JSON output.");
+        }
+        output = jsonEnvelope(result.package, result.command, result.data);
+      }
+      process.stdout.write(`${output}
+`);
+    }
+    return 0;
+  } catch (error) {
+    const isJson = argv.includes("--json");
+    const code = error instanceof CinderKnowledgeError ? error.code : "UNEXPECTED_ERROR";
+    const message = error instanceof Error ? error.message : String(error);
+    const suggestions = error instanceof CinderKnowledgeError ? error.suggestions : [];
+    if (isJson) {
+      process.stdout.write(`${jsonError(code, message, suggestions)}
+`);
+    } else {
+      process.stderr.write(`${message}
+`);
+      if (suggestions.length > 0)
+        process.stderr.write(`Suggestions: ${suggestions.join(", ")}
+`);
+    }
+    return 1;
+  }
+}
+function isCliEntrypoint(entrypointPath = process.argv[1], moduleUrl = import.meta.url) {
+  if (!entrypointPath)
+    return false;
+  try {
+    return realpathSync(entrypointPath) === realpathSync(fileURLToPath2(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+if (isCliEntrypoint()) {
+  const exitCode = await runCli();
+  process.exit(exitCode);
+}
+export {
+  runCli,
+  parseCommand,
+  isCliEntrypoint
+};
+
+//# debugId=AA1A712EED53408B64756E2164756E21