@fragments-sdk/cli 0.15.10 → 0.16.0

package/src/commands/context-cloud.ts

@@ -0,0 +1,355 @@
+import { confirm } from '@inquirer/prompts';
+import {
+  access,
+  mkdir,
+  readFile,
+  writeFile,
+} from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import pc from 'picocolors';
+import { strFromU8, unzipSync } from 'fflate';
+import {
+  bundleManifestSchema,
+  bundleTargetSchema,
+  type BundleManifest,
+  type BundleTarget,
+} from '@fragments-sdk/core';
+
+const DEFAULT_CLOUD_URL =
+  process.env.FRAGMENTS_CLOUD_URL ?? 'https://app.usefragments.com';
+const MANAGED_START = '<!-- BEGIN FRAGMENTS DESIGN SYSTEM -->';
+const MANAGED_END = '<!-- END FRAGMENTS DESIGN SYSTEM -->';
+
+const ROOT_FILE_TARGETS: Partial<
+  Record<BundleTarget, { helperPath: string; rootPath: string }>
+> = {
+  agents: {
+    helperPath: '.fragments/instructions/agents.md',
+    rootPath: 'AGENTS.md',
+  },
+  claude: {
+    helperPath: '.fragments/instructions/claude-code.md',
+    rootPath: 'CLAUDE.md',
+  },
+  copilot: {
+    helperPath: '.fragments/instructions/copilot.md',
+    rootPath: '.github/copilot-instructions.md',
+  },
+};
+
+export interface ContextCloudInstallOptions {
+  apiKey?: string;
+  targets?: string;
+  cwd?: string;
+  dryRun?: boolean;
+  yes?: boolean;
+  rootFiles?: 'prompt' | 'never' | 'patch';
+  gitignoreFragments?: boolean;
+}
+
+export interface ContextCloudStatusOptions {
+  apiKey?: string;
+  cwd?: string;
+}
+
+function parseManifestOrThrow(
+  payload: string,
+  sourceLabel: 'local' | 'remote' | 'downloaded',
+) {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(payload);
+  } catch {
+    throw new Error(`Invalid ${sourceLabel} Fragments manifest JSON.`);
+  }
+
+  const result = bundleManifestSchema.safeParse(parsed);
+  if (result.success) {
+    return result.data;
+  }
+
+  const schemaVersion =
+    parsed &&
+    typeof parsed === 'object' &&
+    'schemaVersion' in parsed &&
+    typeof (parsed as { schemaVersion?: unknown }).schemaVersion === 'number'
+      ? (parsed as { schemaVersion: number }).schemaVersion
+      : null;
+
+  if (schemaVersion !== null) {
+    throw new Error(
+      `Unsupported Fragments bundle schemaVersion ${schemaVersion}. Upgrade your CLI.`,
+    );
+  }
+
+  throw new Error(`Invalid ${sourceLabel} Fragments manifest.`);
+}
+
+function resolveApiKey(explicit?: string) {
+  const apiKey = explicit ?? process.env.FRAGMENTS_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      'Missing Fragments Cloud API key. Set FRAGMENTS_API_KEY or pass --api-key.',
+    );
+  }
+  return apiKey;
+}
+
+function resolveTargets(csv?: string) {
+  if (!csv) return null;
+  const targets = csv
+    .split(',')
+    .map((value) => value.trim())
+    .filter(Boolean);
+  for (const target of targets) {
+    bundleTargetSchema.parse(target);
+  }
+  return Array.from(new Set(targets)) as BundleTarget[];
+}
+
+function managedBlock(content: string) {
+  return `${MANAGED_START}\n${content.trim()}\n${MANAGED_END}\n`;
+}
+
+function upsertManagedBlock(existing: string, content: string) {
+  const block = managedBlock(content);
+  if (existing.includes(MANAGED_START) && existing.includes(MANAGED_END)) {
+    return existing.replace(
+      new RegExp(
+        `${MANAGED_START}[\\s\\S]*?${MANAGED_END}\\n?`,
+        'm',
+      ),
+      block,
+    );
+  }
+  return existing.trim()
+    ? `${existing.trimEnd()}\n\n${block}`
+    : block;
+}
+
+async function fileExists(path: string) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function writeManagedFile(path: string, content: string, dryRun?: boolean) {
+  if (dryRun) return;
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, content, 'utf-8');
+}
+
+async function fetchBundle(args: {
+  apiKey: string;
+  targets: BundleTarget[] | null;
+}) {
+  const url = new URL('/api/bundle', DEFAULT_CLOUD_URL);
+  if (args.targets?.length) {
+    url.searchParams.set('targets', args.targets.join(','));
+  }
+
+  const response = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${args.apiKey}`,
+    },
+  });
+  if (!response.ok) {
+    const payload = (await response.json().catch(() => null)) as
+      | { message?: string; error?: string }
+      | null;
+    throw new Error(payload?.message ?? payload?.error ?? 'Bundle download failed.');
+  }
+
+  try {
+    const archive = unzipSync(new Uint8Array(await response.arrayBuffer()));
+    return Object.fromEntries(
+      Object.entries(archive).map(([path, bytes]) => [path, strFromU8(bytes)]),
+    ) as Record<string, string>;
+  } catch {
+    throw new Error('Bundle download was corrupted, try again.');
+  }
+}
+
+async function fetchRemoteManifest(apiKey: string) {
+  const url = new URL('/api/bundle-artifact', DEFAULT_CLOUD_URL);
+  url.searchParams.set('artifact', 'manifest');
+  const response = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+    },
+  });
+  if (!response.ok) {
+    const payload = (await response.json().catch(() => null)) as
+      | { message?: string; error?: string }
+      | null;
+    throw new Error(payload?.message ?? payload?.error ?? 'Unable to fetch remote manifest.');
+  }
+  const payload = (await response.json()) as { content: string };
+  return parseManifestOrThrow(payload.content, 'remote');
+}
+
+function resolveRootFileMode(options: ContextCloudInstallOptions) {
+  if (options.rootFiles) {
+    return options.rootFiles;
+  }
+  if (options.yes || !process.stdout.isTTY) {
+    return 'never' as const;
+  }
+  return 'prompt' as const;
+}
+
+async function maybePatchRootFile(args: {
+  projectRoot: string;
+  target: keyof typeof ROOT_FILE_TARGETS;
+  files: Record<string, string>;
+  mode: 'prompt' | 'never' | 'patch';
+  dryRun?: boolean;
+}) {
+  const config = ROOT_FILE_TARGETS[args.target];
+  if (!config) return;
+
+  const snippet = args.files[config.helperPath];
+  if (!snippet) return;
+
+  const rootPath = resolve(args.projectRoot, config.rootPath);
+  const exists = await fileExists(rootPath);
+  if (args.mode === 'never') {
+    console.log(
+      pc.dim(
+        `  • Next step: paste ${config.helperPath} into ${config.rootPath} if you want repo-level instructions.`,
+      ),
+    );
+    return;
+  }
+
+  if (args.mode === 'prompt' && exists) {
+    const approved = await confirm({
+      message: `Update ${config.rootPath} with a Fragments-managed block?`,
+      default: true,
+    });
+    if (!approved) {
+      return;
+    }
+  }
+
+  if (args.mode === 'prompt' && !exists) {
+    console.log(
+      pc.dim(
+        `  • ${config.rootPath} does not exist. Keeping snippet-only output in ${config.helperPath}.`,
+      ),
+    );
+    return;
+  }
+
+  const nextContent = exists
+    ? upsertManagedBlock(await readFile(rootPath, 'utf-8'), snippet)
+    : managedBlock(snippet);
+  await writeManagedFile(rootPath, nextContent, args.dryRun);
+  console.log(pc.green(`  • Updated ${config.rootPath}`));
+}
+
+async function maybeUpdateGitignore(projectRoot: string, dryRun?: boolean) {
+  const gitignorePath = resolve(projectRoot, '.gitignore');
+  const existing = (await fileExists(gitignorePath))
+    ? await readFile(gitignorePath, 'utf-8')
+    : '';
+  if (existing.includes('.fragments/')) {
+    return;
+  }
+  const next = existing.trimEnd()
+    ? `${existing.trimEnd()}\n.fragments/\n`
+    : '.fragments/\n';
+  await writeManagedFile(gitignorePath, next, dryRun);
+}
+
+export async function contextInstallCloud(
+  options: ContextCloudInstallOptions,
+) {
+  const projectRoot = resolve(process.cwd(), options.cwd ?? '.');
+  const apiKey = resolveApiKey(options.apiKey);
+  const targets = resolveTargets(options.targets);
+  const files = await fetchBundle({ apiKey, targets });
+  const manifest = parseManifestOrThrow(
+    files['.fragments/manifest.json'] ?? '{}',
+    'downloaded',
+  );
+  const mode = resolveRootFileMode(options);
+
+  console.log(
+    pc.cyan(
+      `Installing Fragments bundle (${manifest.totalComponents} components, revision ${manifest.catalogRevision})`,
+    ),
+  );
+
+  for (const [relativePath, content] of Object.entries(files).sort(([a], [b]) =>
+    a.localeCompare(b),
+  )) {
+    const absolutePath = resolve(projectRoot, relativePath);
+    if (!options.dryRun) {
+      await mkdir(dirname(absolutePath), { recursive: true });
+      await writeFile(absolutePath, content, 'utf-8');
+    }
+    console.log(pc.green(`  • Wrote ${relativePath}`));
+  }
+
+  if (options.gitignoreFragments) {
+    await maybeUpdateGitignore(projectRoot, options.dryRun);
+    console.log(
+      pc.yellow(
+        '  • Added .fragments/ to .gitignore. This disables committed offline context by default.',
+      ),
+    );
+  }
+
+  for (const target of ['agents', 'claude', 'copilot'] as const) {
+    await maybePatchRootFile({
+      projectRoot,
+      target,
+      files,
+      mode,
+      dryRun: options.dryRun,
+    });
+  }
+
+  console.log(
+    pc.dim(
+      `Status: ${options.dryRun ? 'dry run only — no files written' : 'bundle installed successfully'}`,
+    ),
+  );
+}
+
+export async function contextStatusCloud(
+  options: ContextCloudStatusOptions,
+) {
+  const projectRoot = resolve(process.cwd(), options.cwd ?? '.');
+  const manifestPath = resolve(projectRoot, '.fragments/manifest.json');
+  if (!(await fileExists(manifestPath))) {
+    console.log(pc.yellow('Status: missing'));
+    console.log(pc.dim('No local .fragments/manifest.json was found.'));
+    return;
+  }
+
+  const parsedLocalManifest = parseManifestOrThrow(
+    await readFile(manifestPath, 'utf-8'),
+    'local',
+  );
+  const remoteManifest = await fetchRemoteManifest(resolveApiKey(options.apiKey));
+
+  const status =
+    parsedLocalManifest.catalogRevision === remoteManifest.catalogRevision
+      ? 'up-to-date'
+      : 'outdated';
+
+  console.log(pc.cyan(`Status: ${status}`));
+  console.log(
+    pc.dim(`  Local revision:  ${parsedLocalManifest.catalogRevision}`),
+  );
+  console.log(pc.dim(`  Remote revision: ${remoteManifest.catalogRevision}`));
+  console.log(
+    pc.dim(`  Local updated:   ${parsedLocalManifest.catalogUpdatedAt}`),
+  );
+  console.log(pc.dim(`  Remote updated:  ${remoteManifest.catalogUpdatedAt}`));
+}

package/src/commands/govern-scan-report.ts

@@ -0,0 +1,170 @@
+import { resolve, dirname, relative } from 'node:path';
+import type {
+  GovernanceVerdict,
+  Severity,
+  ComponentHealthSummary,
+  Violation,
+} from '@fragments-sdk/govern';
+import type { ComponentUsage } from '../service/enhance/types.js';
+
+export interface FlatUsageEntry {
+  component: string;
+  file: string;
+  occurrences: number;
+}
+
+export interface ComplianceSummary {
+  complianceRate: number;
+  passingUsages: number;
+  totalUsages: number;
+  contractedCount: number;
+  detectedCount: number;
+}
+
+export interface GovernScanReport {
+  verdict: GovernanceVerdict;
+  componentUsage: FlatUsageEntry[];
+  complianceSummary?: ComplianceSummary;
+}
+
+const SEVERITY_RANK: Record<Severity, number> = {
+  critical: 4,
+  serious: 3,
+  moderate: 2,
+  minor: 1,
+};
+
+function mergeSeverity(a: Severity, b: Severity): Severity {
+  return SEVERITY_RANK[a] >= SEVERITY_RANK[b] ? a : b;
+}
+
+export function aggregateVerdicts(
+  verdicts: GovernanceVerdict[],
+  computeScore: (violations: Violation[]) => number,
+  runner: string = 'cli',
+): GovernanceVerdict {
+  if (verdicts.length === 0) {
+    return {
+      passed: true,
+      score: 100,
+      results: [],
+      metadata: {
+        runner,
+        duration: 0,
+        nodeCount: 0,
+        componentTypes: [],
+      },
+    };
+  }
+
+  const byValidator = new Map<string, GovernanceVerdict['results'][number]>();
+  let duration = 0;
+  let nodeCount = 0;
+  const componentTypes = new Set<string>();
+
+  for (const verdict of verdicts) {
+    duration += verdict.metadata.duration;
+    nodeCount += verdict.metadata.nodeCount;
+    for (const type of verdict.metadata.componentTypes) {
+      componentTypes.add(type);
+    }
+
+    for (const result of verdict.results) {
+      const existing = byValidator.get(result.validator);
+      if (!existing) {
+        byValidator.set(result.validator, {
+          validator: result.validator,
+          severity: result.severity,
+          passed: result.passed,
+          violations: [...result.violations],
+          suggestions: result.suggestions ? [...result.suggestions] : undefined,
+        });
+        continue;
+      }
+
+      existing.passed = existing.passed && result.passed;
+      existing.severity = mergeSeverity(existing.severity, result.severity);
+      existing.violations.push(...result.violations);
+
+      if (result.suggestions?.length) {
+        const merged = existing.suggestions ?? [];
+        merged.push(...result.suggestions);
+        existing.suggestions = merged;
+      }
+    }
+  }
+
+  const results = [...byValidator.values()].sort((a, b) =>
+    a.validator.localeCompare(b.validator),
+  );
+  const allViolations = results.flatMap((result) => result.violations);
+
+  return {
+    passed: verdicts.every((verdict) => verdict.passed),
+    score: computeScore(allViolations),
+    results,
+    metadata: {
+      runner,
+      duration,
+      nodeCount,
+      componentTypes: [...componentTypes].sort(),
+    },
+  };
+}
+
+export function flattenComponentUsage(
+  usages: ComponentUsage[],
+  rootDir: string,
+): FlatUsageEntry[] {
+  const counts = new Map<string, number>();
+
+  for (const usage of usages) {
+    const relPath = relative(rootDir, usage.filePath);
+    const key = `${relPath}\u0000${usage.componentName}`;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+
+  return [...counts.entries()]
+    .map(([key, occurrences]) => {
+      const separatorIndex = key.indexOf('\u0000');
+      const file = key.slice(0, separatorIndex);
+      const component = key.slice(separatorIndex + 1);
+      return { component, file, occurrences };
+    })
+    .sort((a, b) =>
+      a.file === b.file
+        ? a.component.localeCompare(b.component)
+        : a.file.localeCompare(b.file),
+    );
+}
+
+export function buildComplianceSummary(
+  health: ComponentHealthSummary,
+): ComplianceSummary {
+  const usageTotals = Object.values(health.components).reduce(
+    (acc, component) => {
+      acc.passingUsages += component.passed;
+      acc.totalUsages += component.total;
+      return acc;
+    },
+    { passingUsages: 0, totalUsages: 0 },
+  );
+
+  return {
+    complianceRate: health.overallCompliance,
+    passingUsages: usageTotals.passingUsages,
+    totalUsages: usageTotals.totalUsages,
+    contractedCount: health.contractedComponents,
+    detectedCount: health.totalComponents,
+  };
+}
+
+export async function writeGovernScanReport(
+  path: string,
+  report: GovernScanReport,
+): Promise<void> {
+  const { mkdir, writeFile } = await import('node:fs/promises');
+  const absPath = resolve(path);
+  await mkdir(dirname(absPath), { recursive: true });
+  await writeFile(absPath, JSON.stringify(report, null, 2), 'utf-8');
+}