@fragments-sdk/cli 0.14.3 → 0.15.0

package/src/commands/__tests__/init.test.ts

@@ -0,0 +1,113 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { init } from "../init.js";
+
+describe("init", () => {
+  let tmpDir: string;
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "fragments-init-test-"));
+  });
+
+  afterAll(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("skips Fragments UI runtime injection for shadcn-style projects", async () => {
+    const projectDir = join(tmpDir, "shadcn-app");
+    await mkdir(join(projectDir, "src", "components", "ui"), { recursive: true });
+
+    await writeFile(
+      join(projectDir, "package.json"),
+      JSON.stringify(
+        {
+          name: "shadcn-app",
+          private: true,
+          devDependencies: {
+            tailwindcss: "^4.0.0",
+          },
+        },
+        null,
+        2
+      )
+    );
+    await writeFile(join(projectDir, "vite.config.ts"), "export default {};\n");
+    await writeFile(
+      join(projectDir, "src", "main.tsx"),
+      [
+        "import { StrictMode } from 'react';",
+        "import { createRoot } from 'react-dom/client';",
+        "import App from './App';",
+        "",
+        "createRoot(document.getElementById('root')!).render(",
+        "  <StrictMode><App /></StrictMode>",
+        ");",
+        "",
+      ].join("\n")
+    );
+    await writeFile(join(projectDir, "src", "App.tsx"), "export default function App() { return <div />; }\n");
+    await writeFile(
+      join(projectDir, "src", "components", "ui", "button.tsx"),
+      [
+        "export interface ButtonProps {",
+        "  variant?: 'default' | 'secondary';",
+        "}",
+        "export function Button({ variant = 'default' }: ButtonProps) {",
+        "  return <button data-variant={variant} />;",
+        "}",
+        "",
+      ].join("\n")
+    );
+
+    const result = await init({ projectRoot: projectDir });
+
+    expect(result.success).toBe(true);
+
+    const main = await readFile(join(projectDir, "src", "main.tsx"), "utf-8");
+    expect(main).not.toContain("@fragments-sdk/ui");
+    expect(main).not.toContain("ThemeProvider");
+  });
+
+  it("respects explicit metadata-only mode even without an existing UI library", async () => {
+    const projectDir = join(tmpDir, "metadata-only-app");
+    await mkdir(join(projectDir, "src"), { recursive: true });
+
+    await writeFile(
+      join(projectDir, "package.json"),
+      JSON.stringify(
+        {
+          name: "metadata-only-app",
+          private: true,
+        },
+        null,
+        2
+      )
+    );
+    await writeFile(join(projectDir, "vite.config.ts"), "export default {};\n");
+    await writeFile(
+      join(projectDir, "src", "main.tsx"),
+      [
+        "import { StrictMode } from 'react';",
+        "import { createRoot } from 'react-dom/client';",
+        "import App from './App';",
+        "",
+        "createRoot(document.getElementById('root')!).render(",
+        "  <StrictMode><App /></StrictMode>",
+        ");",
+        "",
+      ].join("\n")
+    );
+    await writeFile(join(projectDir, "src", "App.tsx"), "export default function App() { return <div />; }\n");
+
+    const result = await init({ projectRoot: projectDir, metadataOnly: true });
+
+    expect(result.success).toBe(true);
+
+    const main = await readFile(join(projectDir, "src", "main.tsx"), "utf-8");
+    expect(main).not.toContain("@fragments-sdk/ui");
+    expect(main).not.toContain("ThemeProvider");
+  });
+});

package/src/commands/__tests__/scan-generate.test.ts

@@ -1,12 +1,14 @@
 import { describe, it, expect, beforeAll, afterAll, vi } from "vitest";
 import { mkdtemp, writeFile, mkdir, rm, readFile as rf } from "node:fs/promises";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import {
   extractComponentJSDocFromSource,
   detectCompoundComponentsFromSource,
   calculateFieldConfidence,
   scanGenerate,
+  detectPackageManagerForProject,
+  excludeFragmentsFromTsconfig,
   parseEnrichmentResponse,
   buildEnrichmentSystemPrompt,
   buildEnrichmentUserPrompt,
@@ -268,39 +270,28 @@ export function Button({ children, variant = 'primary', disabled, onClick }: But
     // Read the generated file and check structure
     const { readFile: rf } = await import("node:fs/promises");
     const content = await rf(
-      join(tmpDir, "components", "Button", "Button.fragment.tsx"),
+      join(tmpDir, "components", "Button", "Button.contract.json"),
       "utf-8"
     );
 
-    // Check import uses @fragments-sdk/core
-    expect(content).toContain(
-      "import { defineFragment } from '@fragments-sdk/core'"
-    );
-
-    // Check confidence header
-    expect(content).toMatch(
-      /\/\/ Auto-generated by fragments init --scan \| Confidence: \d+\/100/
-    );
+    const contract = JSON.parse(content);
 
-    // Check TODO markers exist
-    expect(content).toContain("// TODO:");
-
-    // Check component name in meta
-    expect(content).toContain("name: 'Button'");
+    // Check required contract fields
+    expect(contract.$schema).toBe("https://usefragments.com/schemas/contract.v1.json");
+    expect(contract.name).toBe("Button");
 
     // Check JSDoc was picked up in description
-    expect(content).toContain("A primary button for user interactions.");
+    expect(contract.description).toContain("A primary button for user interactions.");
 
     // Check category was inferred (Button → Actions)
-    expect(content).toContain("category: 'Actions'");
+    expect(contract.category).toBe("Actions");
 
-    // Check props block has content
-    expect(content).toContain("children:");
-    expect(content).toContain("variant:");
+    // Check props have content
+    expect(contract.props).toHaveProperty("variant");
 
-    // Check _generated provenance block
-    expect(content).toContain("_generated:");
-    expect(content).toContain("source: 'ai'");
+    // Check provenance block
+    expect(contract.provenance).toBeDefined();
+    expect(contract.provenance.source).toBe("extracted");
   });
 
   it("skips existing fragments without --force", async () => {
@@ -326,17 +317,163 @@ export function Button({ children, variant = 'primary', disabled, onClick }: But
 
     const { readFile: rf } = await import("node:fs/promises");
     const content = await rf(
-      join(tmpDir, "components", "Button", "Button.fragment.tsx"),
+      join(tmpDir, "components", "Button", "Button.contract.json"),
       "utf-8"
     );
 
-    // Check contract block exists
-    expect(content).toContain("contract:");
-    expect(content).toContain("propsSummary:");
+    const contract = JSON.parse(content);
+
+    // Check propsSummary exists and has entries for local props
+    expect(contract.propsSummary).toBeDefined();
+    expect(contract.propsSummary.length).toBeGreaterThan(0);
+    expect(contract.propsSummary.some((s: string) => s.includes("variant"))).toBe(true);
+  });
+});
+
+describe("scanGenerate helpers", () => {
+  let tmpDir: string;
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "scan-gen-helpers-"));
+  });
+
+  afterAll(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("detects pnpm from an ancestor workspace root", async () => {
+    const workspaceRoot = join(tmpDir, "workspace-root");
+    const appDir = join(workspaceRoot, "apps", "demo");
+    await mkdir(appDir, { recursive: true });
+    await writeFile(join(workspaceRoot, "pnpm-workspace.yaml"), "packages:\n  - 'apps/*'\n");
+    await writeFile(join(workspaceRoot, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
+
+    const result = await detectPackageManagerForProject(appDir);
+
+    expect(result.manager).toBe("pnpm");
+    expect(result.lockfileDir).toBe(workspaceRoot);
+  });
+
+  it("adds fragment exclusions to JSONC tsconfig files with aliases", async () => {
+    const projectDir = join(tmpDir, "jsonc-app");
+    const scanDir = join(projectDir, "src", "components");
+    await mkdir(scanDir, { recursive: true });
+    await writeFile(
+      join(projectDir, "package.json"),
+      JSON.stringify({ name: "jsonc-app", private: true }, null, 2)
+    );
+    await writeFile(
+      join(projectDir, "tsconfig.app.json"),
+      `{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"]
+}
+`
+    );
+
+    await excludeFragmentsFromTsconfig(scanDir);
+
+    const updated = JSON.parse(await rf(join(projectDir, "tsconfig.app.json"), "utf-8"));
+    expect(updated.exclude).toContain("**/*.contract.json");
+  });
+
+  it("generates shadcn-style compound fragments without React imports or member syntax", async () => {
+    const projectDir = join(tmpDir, "shadcn-compound");
+    const componentDir = join(projectDir, "components");
+    const cardDir = join(componentDir, "Card");
+    await mkdir(cardDir, { recursive: true });
+
+    await writeFile(
+      join(projectDir, "package.json"),
+      JSON.stringify(
+        {
+          name: "shadcn-compound",
+          private: true,
+          devDependencies: {
+            "@fragments-sdk/core": "workspace:^",
+          },
+        },
+        null,
+        2
+      )
+    );
+    await writeFile(
+      join(projectDir, "tsconfig.app.json"),
+      JSON.stringify(
+        {
+          compilerOptions: {
+            jsx: "react-jsx",
+          },
+          include: ["components"],
+        },
+        null,
+        2
+      )
+    );
+    await writeFile(
+      join(cardDir, "Card.tsx"),
+      `export function Card(props: { children?: React.ReactNode; size?: 'default' | 'sm' }) {
+  return <div>{props.children}</div>;
+}
+
+export function CardHeader(props: { children?: React.ReactNode }) {
+  return <div>{props.children}</div>;
+}
+
+export function CardContent(props: { children?: React.ReactNode }) {
+  return <div>{props.children}</div>;
+}
+
+export function CardFooter(props: { children?: React.ReactNode }) {
+  return <div>{props.children}</div>;
+}
+
+export { Card as default };
+`
+    );
+
+    const result = await scanGenerate({
+      scanPath: componentDir,
+      force: true,
+    });
+
+    expect(result.success).toBe(true);
+
+    const content = await rf(join(cardDir, "Card.contract.json"), "utf-8");
+    const contract = JSON.parse(content);
+    // Contract.json should have the component name and props
+    expect(contract.name).toBe("Card");
+    expect(contract.$schema).toBe("https://usefragments.com/schemas/contract.v1.json");
+    expect(contract.provenance).toBeDefined();
+  });
+
+  it("falls back to inherited wrapper props for shadcn-style Label primitives", async () => {
+    const projectDir = resolve(__dirname, "../__fixtures__/shadcn-label-wrapper");
+    const scanDir = join(projectDir, "src", "components", "ui");
+
+    const result = await scanGenerate({
+      scanPath: scanDir,
+      force: true,
+      tsconfig: join(projectDir, "tsconfig.app.json"),
+    });
+
+    expect(result.success).toBe(true);
 
-    // Check propsSummary has entries for local props
-    expect(content).toContain("variant:");
-    expect(content).toContain("disabled:");
+    const fragment = await rf(join(scanDir, "label.contract.json"), "utf-8");
+    const contract = JSON.parse(fragment);
+    // Should have extracted inherited props like htmlFor and form
+    expect(contract.props).toBeDefined();
+    // Props may be in propsSummary or props object
+    const allKeys = [
+      ...Object.keys(contract.props ?? {}),
+      ...(contract.propsSummary ?? []).map((s: string) => s.split(':')[0]),
+    ];
+    expect(allKeys.some((k: string) => k.includes('htmlFor') || k.includes('form'))).toBe(true);
   });
 });
 
@@ -393,22 +530,16 @@ export function CardFooter({ children }: { children: React.ReactNode }) {
     expect(result.generated[0].name).toBe("Card");
 
     const content = await rf(
-      join(tmpDir, "components", "Card", "Card.fragment.tsx"),
+      join(tmpDir, "components", "Card", "Card.contract.json"),
       "utf-8"
     );
 
-    // Should have contract with compoundChildren
-    expect(content).toContain("contract:");
-    expect(content).toContain("compoundChildren:");
-    expect(content).toContain("Header:");
-    expect(content).toContain("Body:");
-    expect(content).toContain("Footer:");
-
-    // Should have canonicalUsage
-    expect(content).toContain("canonicalUsage:");
-    expect(content).toContain("Card.Header");
-    expect(content).toContain("Card.Body");
-    expect(content).toContain("Card.Footer");
+    const contract = JSON.parse(content);
+    // Should have AI metadata with compound composition
+    expect(contract.ai).toBeDefined();
+    expect(contract.ai.compositionPattern).toBe("compound");
+    expect(contract.ai.subComponents).toBeDefined();
+    expect(contract.ai.subComponents.length).toBeGreaterThan(0);
   });
 });
 
@@ -697,30 +828,17 @@ export function Badge({ children, variant = 'default' }: BadgeProps) {
     expect(result.generated[0].enriched).toBe(true);
 
     const content = await rf(
-      join(tmpDir, "components", "Badge", "Badge.fragment.tsx"),
+      join(tmpDir, "components", "Badge", "Badge.contract.json"),
       "utf-8"
     );
 
-    // Enriched usage fields should be present (not TODO markers)
-    expect(content).toContain("'Showing status counts'");
-    expect(content).toContain("'Labeling items'");
-    expect(content).toContain("'Long text content — use a Tag instead'");
-    expect(content).toContain("guidelines:");
-    expect(content).toContain("'Keep text short (1-3 words)'");
-
-    // Meta tags should be present
-    expect(content).toContain("tags:");
-    expect(content).toContain("'badge'");
-
-    // Contract should have enriched a11yRules and scenarioTags
-    expect(content).toContain("a11yRules:");
-    expect(content).toContain("'Use aria-label for icon-only badges'");
-    expect(content).toContain("scenarioTags:");
-    expect(content).toContain("'feedback.indicator.badge'");
-
-    // Should NOT have TODO markers for usage.when or usage.whenNot
-    expect(content).not.toContain("// TODO: Describe when to use Badge");
-    expect(content).not.toContain("// TODO: Describe when NOT to use Badge");
+    const contract = JSON.parse(content);
+    // Enriched usage fields should be present
+    expect(contract.usage.when.length).toBeGreaterThan(0);
+    expect(contract.usage.when).toContain("Showing status counts");
+    expect(contract.usage.whenNot).toContain("Long text content — use a Tag instead");
+    expect(contract.usage.guidelines).toBeDefined();
+    expect(contract.usage.guidelines).toContain("Keep text short (1-3 words)");
 
     vi.doUnmock("../../ai-client.js");
   });
@@ -747,13 +865,14 @@ export function Badge({ children, variant = 'default' }: BadgeProps) {
     expect(result.success).toBe(true);
 
     const content = await rf(
-      join(tmpDir, "components", "Badge", "Badge.fragment.tsx"),
+      join(tmpDir, "components", "Badge", "Badge.contract.json"),
       "utf-8"
     );
 
-    // Should have TODO markers (no enrichment)
-    expect(content).toContain("// TODO: Describe when to use Badge");
-    expect(content).toContain("// TODO: Describe when NOT to use Badge");
+    const contract = JSON.parse(content);
+    // Without enrichment, usage.when/whenNot should be empty arrays
+    expect(contract.usage.when).toEqual([]);
+    expect(contract.usage.whenNot).toEqual([]);
     expect(result.generated[0].enriched).toBeFalsy();
     expect(result.enrichmentCost).toBeUndefined();
   });

package/src/commands/__tests__/verify.test.ts

@@ -0,0 +1,91 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { verify } from "../verify.js";
+
+describe("verify --ci", () => {
+  let tmpDir: string;
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "verify-ci-test-"));
+  });
+
+  afterAll(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("prefers local fragments.json and ignores installed package fragments", async () => {
+    const projectDir = join(tmpDir, "project");
+    await mkdir(projectDir, { recursive: true });
+
+    await writeFile(
+      join(projectDir, "fragments.config.ts"),
+      `export default {
+  include: ['src/**/*.fragment.tsx'],
+  exclude: [],
+  components: ['src/**/*.tsx'],
+  framework: 'react',
+  outFile: 'fragments.json',
+};
+`
+    );
+
+    await writeFile(
+      join(projectDir, "fragments.json"),
+      JSON.stringify(
+        {
+          fragments: {
+            LocalButton: {
+              meta: {
+                name: "LocalButton",
+                description: "Local button",
+                category: "Actions",
+              },
+              usage: {
+                when: ["Actions"],
+                whenNot: [],
+              },
+              props: {
+                variant: { type: "enum", required: false, values: ["primary"] },
+              },
+              variants: [{ name: "Default" }],
+              relations: [],
+              filePath: "src/components/LocalButton.fragment.tsx",
+            },
+            InstalledButton: {
+              meta: {
+                name: "InstalledButton",
+                description: "Installed button",
+                category: "Actions",
+              },
+              usage: {
+                when: ["Actions"],
+                whenNot: [],
+              },
+              props: {
+                variant: { type: "enum", required: false, values: ["primary"] },
+              },
+              variants: [{ name: "Default" }],
+              relations: [],
+              filePath: "node_modules/@fragments-sdk/ui/Button.fragment.tsx",
+            },
+          },
+        },
+        null,
+        2
+      )
+    );
+
+    const summary = await verify(undefined, {
+      ci: true,
+      config: join(projectDir, "fragments.config.ts"),
+      port: 6553,
+      minCompliance: 60,
+    });
+
+    expect(summary.totalComponents).toBe(1);
+    expect(summary.results.map((result) => result.component)).toEqual(["LocalButton"]);
+  });
+});

package/src/commands/discover.ts

@@ -0,0 +1,151 @@
+/**
+ * `fragments discover` — list and filter components from fragments.json.
+ *
+ * Loads the compiled output and provides listing, search, category
+ * filtering, and status filtering. Outputs a formatted table, compact
+ * names list, or JSON depending on flags.
+ *
+ * This is the LIST mode only — semantic/useCase search requires the
+ * Orama sidecar available via the MCP server.
+ */
+
+import pc from 'picocolors';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type { CompiledFragmentsFile } from '../core/index.js';
+import { BRAND } from '../core/index.js';
+import { loadConfig } from '../core/node.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface DiscoverCommandOptions {
+  config?: string;
+  search?: string;
+  category?: string;
+  status?: string;
+  compact?: boolean;
+  json?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Command implementation
+// ---------------------------------------------------------------------------
+
+export async function discover(options: DiscoverCommandOptions): Promise<void> {
+  const { config, configDir } = await loadConfig(options.config);
+  const outputPath = resolve(configDir, config.outFile ?? BRAND.outFile);
+
+  let data: CompiledFragmentsFile;
+  try {
+    const content = await readFile(outputPath, 'utf-8');
+    data = JSON.parse(content) as CompiledFragmentsFile;
+  } catch {
+    console.error(
+      pc.red(`Error: Could not load ${BRAND.outFile}. Run \`${BRAND.cliCommand} build\` first.`),
+    );
+    process.exit(1);
+  }
+
+  let fragments = Object.values(data.fragments);
+
+  // --- Search filter (name, description, tags) ---
+  if (options.search) {
+    const term = options.search.toLowerCase();
+    fragments = fragments.filter(
+      (f) =>
+        f.meta.name.toLowerCase().includes(term) ||
+        f.meta.description?.toLowerCase().includes(term) ||
+        f.meta.tags?.some((t) => t.toLowerCase().includes(term)),
+    );
+  }
+
+  // --- Category filter ---
+  if (options.category) {
+    const cat = options.category.trim().toLowerCase();
+    fragments = fragments.filter(
+      (f) => f.meta.category?.toLowerCase() === cat,
+    );
+  }
+
+  // --- Status filter ---
+  if (options.status) {
+    const status = options.status.trim().toLowerCase();
+    fragments = fragments.filter((f) => (f.meta.status ?? 'stable') === status);
+  }
+
+  // Sort alphabetically
+  fragments.sort((a, b) => a.meta.name.localeCompare(b.meta.name));
+
+  const categories = [...new Set(fragments.map((f) => f.meta.category).filter(Boolean))].sort();
+
+  // --- JSON output ---
+  if (options.json) {
+    const output = {
+      total: fragments.length,
+      fragments: fragments.map((f) => ({
+        name: f.meta.name,
+        category: f.meta.category,
+        status: f.meta.status ?? 'stable',
+        description: f.meta.description,
+        tags: f.meta.tags,
+        variantCount: f.variants.length,
+        propCount: Object.keys(f.props ?? {}).length,
+      })),
+      categories,
+    };
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
+  // --- Compact output (names only) ---
+  if (options.compact) {
+    for (const f of fragments) {
+      console.log(f.meta.name);
+    }
+    return;
+  }
+
+  // --- Table output ---
+  if (fragments.length === 0) {
+    console.log(pc.yellow('\nNo components found matching the given filters.\n'));
+    return;
+  }
+
+  console.log(pc.bold(`\n${BRAND.name} Components (${fragments.length})\n`));
+
+  console.log(
+    pc.dim(
+      `  ${'Name'.padEnd(28)} ${'Category'.padEnd(16)} ${'Status'.padEnd(14)} ${'Variants'.padEnd(10)} ${'Props'}`,
+    ),
+  );
+  console.log(pc.dim(`  ${'─'.repeat(80)}`));
+
+  for (const f of fragments) {
+    const name = f.meta.name.length > 26 ? f.meta.name.slice(0, 23) + '...' : f.meta.name;
+    const category = (f.meta.category ?? '').padEnd(16);
+    const status = f.meta.status ?? 'stable';
+    const statusColored =
+      status === 'stable' ? pc.green(status.padEnd(14)) :
+      status === 'deprecated' ? pc.red(status.padEnd(14)) :
+      status === 'beta' ? pc.yellow(status.padEnd(14)) :
+      pc.cyan(status.padEnd(14));
+    const variantCount = String(f.variants.length).padEnd(10);
+    const propCount = String(Object.keys(f.props ?? {}).length);
+
+    console.log(
+      `  ${pc.cyan(name.padEnd(28))} ${pc.dim(category)} ${statusColored} ${variantCount} ${propCount}`,
+    );
+  }
+
+  // Summary
+  console.log(pc.dim(`\n  ${'─'.repeat(80)}`));
+  console.log(
+    pc.dim(`  ${fragments.length} component(s) across ${categories.length} categories`),
+  );
+  if (categories.length > 0) {
+    console.log(pc.dim(`  Categories: ${categories.join(', ')}`));
+  }
+  console.log();
+}