@larose-ui/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 laRose contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/cli.js

@@ -0,0 +1,1180 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { writeFileSync } from "fs";
+import { resolve } from "path";
+
+// src/doctor.ts
+import { readdir as readdir2, readFile as readFile2, stat, writeFile } from "fs/promises";
+import { join as join2, relative } from "path";
+
+// ../contracts/dist/index.js
+function validateContract(ui, api) {
+  const mismatches = [];
+  const apiFields = new Map(api.fields.map((f) => [f.name, f]));
+  const uiFields = new Map(ui.fields.map((f) => [f.name, f]));
+  for (const uiField of ui.fields) {
+    const apiField = apiFields.get(uiField.name);
+    if (!apiField) {
+      mismatches.push({
+        field: uiField.name,
+        issue: "missing_in_api",
+        message: `UI expects "${uiField.name}" but API schema does not include it`,
+        severity: uiField.required ? "error" : "warning"
+      });
+      continue;
+    }
+    if (uiField.type && apiField.type && uiField.type !== apiField.type) {
+      mismatches.push({
+        field: uiField.name,
+        issue: "type_mismatch",
+        message: `Type mismatch for "${uiField.name}": UI=${uiField.type}, API=${apiField.type}`,
+        severity: "error"
+      });
+    }
+    if (uiField.required && !apiField.required) {
+      mismatches.push({
+        field: uiField.name,
+        issue: "required_mismatch",
+        message: `"${uiField.name}" is required in UI but optional in API`,
+        severity: "warning"
+      });
+    }
+  }
+  for (const apiField of api.fields) {
+    if (!uiFields.has(apiField.name) && apiField.required) {
+      mismatches.push({
+        field: apiField.name,
+        issue: "missing_in_ui",
+        message: `API requires "${apiField.name}" but UI schema does not include it`,
+        severity: "error"
+      });
+    }
+  }
+  return {
+    valid: mismatches.filter((m) => m.severity === "error").length === 0,
+    mismatches
+  };
+}
+
+// ../accessibility/dist/index.js
+var RULES = [
+  {
+    id: "dialog-label",
+    pattern: /role=["']dialog["']/,
+    missing: /aria-labelledby|aria-label/,
+    message: "Dialog/Modal may be missing accessible label",
+    fix: "Add title prop or aria-labelledby",
+    severity: "error"
+  },
+  {
+    id: "empty-button",
+    pattern: /<button[^>]*>\s*<\/button>/,
+    missing: /aria-label/,
+    message: "Empty button without aria-label",
+    fix: "Add aria-label or visible text",
+    severity: "warning"
+  },
+  {
+    id: "img-alt",
+    pattern: /<img(?![^>]*\balt=)/,
+    message: "Image missing alt attribute",
+    fix: 'Add alt="" for decorative or descriptive alt text',
+    severity: "error"
+  },
+  {
+    id: "input-label",
+    pattern: /<input[^>]*\bid=["']([^"']+)["']/,
+    requiresLabelFor: true,
+    message: "Input with id may be missing associated label",
+    fix: 'Use <label htmlFor="..."> or aria-label',
+    severity: "warning"
+  }
+];
+function scanComponentSource(source, filePath) {
+  const violations = [];
+  const lines = source.split("\n");
+  for (const rule of RULES) {
+    if (rule.id === "input-label") {
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const idMatch = line.match(/<input[^>]*\bid=["']([^"']+)["']/);
+        if (!idMatch) continue;
+        const id = idMatch[1];
+        const hasLabel = source.includes(`htmlFor="${id}"`) || source.includes(`htmlFor='${id}'`) || line.includes("aria-label");
+        if (!hasLabel) {
+          violations.push({
+            severity: rule.severity,
+            rule: rule.id,
+            message: rule.message,
+            file: filePath,
+            line: i + 1,
+            fix: rule.fix
+          });
+        }
+      }
+      continue;
+    }
+    if (!rule.pattern.test(source)) continue;
+    if ("missing" in rule && rule.missing && rule.missing.test(source)) continue;
+    violations.push({
+      severity: rule.severity,
+      rule: rule.id,
+      message: rule.message,
+      file: filePath,
+      fix: rule.fix
+    });
+  }
+  return {
+    passed: violations.filter((v) => v.severity === "error").length === 0,
+    violations
+  };
+}
+var RECOMMENDED_CSP = [
+  "default-src 'self'",
+  "script-src 'self'",
+  "style-src 'self' 'unsafe-inline'",
+  "img-src 'self' data: https:"
+].join("; ");
+
+// ../migration/dist/index.js
+var TOKEN_RENAMES = {
+  "--ui-color-primary": "--lr-color-primary",
+  "--ui-color-secondary": "--lr-color-secondary",
+  "--ui-color-success": "--lr-color-success",
+  "--ui-color-warning": "--lr-color-warning",
+  "--ui-color-error": "--lr-color-error",
+  "--ui-color-background": "--lr-color-background",
+  "--ui-color-surface": "--lr-color-surface",
+  "--ui-color-border": "--lr-color-border",
+  "--ui-color-text": "--lr-color-text"
+};
+function renameTokens(source) {
+  let content = source;
+  const transforms = [];
+  for (const [from, to] of Object.entries(TOKEN_RENAMES)) {
+    if (content.includes(from)) {
+      content = content.replaceAll(from, to);
+      transforms.push(`token:${from}\u2192${to}`);
+    }
+  }
+  return { content, changed: content !== source, transforms };
+}
+function fixLaRoseProviderImport(source) {
+  const importRegex = /import\s+\{([^}]+)\}\s+from\s+['"]@larose-ui\/react['"]\s*;?/g;
+  let content = source;
+  let changed = false;
+  const transforms = [];
+  content = content.replace(importRegex, (full, specifiers) => {
+    if (!specifiers.includes("LaRoseProvider")) return full;
+    const parts = specifiers.split(",").map((s) => s.trim()).filter(Boolean);
+    const reactParts = parts.filter((p) => p !== "LaRoseProvider");
+    changed = true;
+    transforms.push("import:LaRoseProvider\u2192@larose-ui/runtime");
+    const runtimeImport = "import { LaRoseProvider } from '@larose-ui/runtime';";
+    if (reactParts.length === 0) {
+      return runtimeImport;
+    }
+    return `${runtimeImport}
+import { ${reactParts.join(", ")} } from '@larose-ui/react';`;
+  });
+  return { content, changed, transforms };
+}
+function fixToastImport(source) {
+  const regex = /import\s+\{([^}]*\buseToast\b[^}]*)\}\s+from\s+['"]@larose-ui\/runtime['"]\s*;?/g;
+  let content = source;
+  let changed = false;
+  const transforms = [];
+  content = content.replace(regex, (_full, specifiers) => {
+    changed = true;
+    transforms.push("import:useToast\u2192@larose-ui/runtime/toast");
+    const parts = specifiers.split(",").map((s) => s.trim()).filter(Boolean);
+    const toastParts = parts.filter((p) => p !== "useToast");
+    const toastImport = "import { useToast } from '@larose-ui/runtime/toast';";
+    if (toastParts.length === 0) return toastImport;
+    return `${toastImport}
+import { ${toastParts.join(", ")} } from '@larose-ui/runtime';`;
+  });
+  return { content, changed, transforms };
+}
+function applyCodemods(source) {
+  const steps = [renameTokens, fixLaRoseProviderImport, fixToastImport];
+  let content = source;
+  const allTransforms = [];
+  let changed = false;
+  for (const step of steps) {
+    const result = step(content);
+    content = result.content;
+    if (result.changed) {
+      changed = true;
+      allTransforms.push(...result.transforms);
+    }
+  }
+  return { content, changed, transforms: allTransforms };
+}
+function applyCodemodsToFiles(files) {
+  return files.map((file) => {
+    const result = applyCodemods(file.content);
+    return {
+      path: file.path,
+      changed: result.changed,
+      transforms: result.transforms,
+      content: result.content
+    };
+  });
+}
+function formatCodemodReport(results) {
+  const changed = results.filter((r) => r.changed);
+  if (changed.length === 0) {
+    return "No files required codemod transforms.";
+  }
+  const lines = [`Applied codemods to ${changed.length} file(s):`, ""];
+  for (const file of changed) {
+    lines.push(`${file.path}`);
+    for (const t of file.transforms) {
+      lines.push(`  - ${t}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function slug(name) {
+  return name.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+function generateForm(name, options = {}) {
+  const id = options.resource ?? slug(name);
+  return `import { Form } from '@larose-ui/forms';
+import { LaRoseProvider } from '@larose-ui/runtime';
+import { Can } from '@larose-ui/permissions';
+
+const ${name}Schema = {
+  id: '${id}',
+  title: '${name}',
+  fields: [
+    { name: 'name', type: 'text' as const, label: 'Name', required: true },
+  ],
+};
+
+export function ${name}Form() {
+  return (
+    <LaRoseProvider permissions={['${id}.write']}>
+      <Can permission="${id}.write">
+        <Form schema={${name}Schema} submitLabel="Save" />
+      </Can>
+    </LaRoseProvider>
+  );
+}
+`;
+}
+function generatePage(name, options = {}) {
+  const resource = options.resource ?? slug(name);
+  const permission = options.permissionPrefix ?? resource;
+  return `import { LaRoseProvider } from '@larose-ui/runtime';
+import { DataView } from '@larose-ui/data';
+import { useJourneyPage } from '@larose-ui/observability';
+
+export function ${name}Page() {
+  useJourneyPage('${resource}');
+
+  return (
+    <LaRoseProvider permissions={['${permission}.read']} tenant={{ id: 'acme', name: 'ACME' }}>
+      <DataView url="/api/${resource}" permission="${permission}.read">
+        {(data) => <pre>{JSON.stringify(data, null, 2)}</pre>}
+      </DataView>
+    </LaRoseProvider>
+  );
+}
+`;
+}
+function generateFeature(name, options = {}) {
+  const resource = options.resource ?? slug(name);
+  const permission = options.permissionPrefix ?? resource;
+  const pascal = name.replace(/(^\w|-\w)/g, (m) => m.replace("-", "").toUpperCase());
+  return `import { LaRoseProvider } from '@larose-ui/runtime';
+import { DataView } from '@larose-ui/data';
+import { SmartTable } from '@larose-ui/ai';
+import { DevToolsProvider } from '@larose-ui/devtools';
+import { useJourneyPage } from '@larose-ui/observability';
+import { Can } from '@larose-ui/permissions';
+import { Card } from '@larose-ui/react';
+
+interface ${pascal}Row {
+  id: string;
+  name: string;
+}
+
+export function ${name}Feature() {
+  useJourneyPage('${resource}');
+
+  return (
+    <LaRoseProvider
+      permissions={['${permission}.read']}
+      tenant={{ id: 'acme', name: 'ACME' }}
+      session="authenticated"
+    >
+      <DevToolsProvider>
+        <Card title="${name}" padding="md">
+          <Can permission="${permission}.read">
+            <DataView<${pascal}Row[]> url="/api/${resource}" permission="${permission}.read">
+              {(rows) => (
+                <SmartTable
+                  readPermission="${permission}.read"
+                  data={rows}
+                  keyExtractor={(row) => row.id}
+                  columns={[
+                    { key: 'id', header: 'ID', priority: 'low' },
+                    { key: 'name', header: 'Name', priority: 'high' },
+                  ]}
+                />
+              )}
+            </DataView>
+          </Can>
+        </Card>
+      </DevToolsProvider>
+    </LaRoseProvider>
+  );
+}
+`;
+}
+function runGenerator(kind, name, options) {
+  switch (kind) {
+    case "form":
+      return generateForm(name, options);
+    case "page":
+      return generatePage(name, options);
+    case "feature":
+      return generateFeature(name, options);
+  }
+}
+function analyzeRelease(manifests) {
+  const packages = manifests.map((manifest) => {
+    const issues = [];
+    const isPrivate = manifest.private === true;
+    if (!manifest.version) issues.push("missing version");
+    if (!isPrivate && !manifest.license) issues.push("missing license");
+    if (!isPrivate && !manifest.publishConfig?.access) {
+      issues.push("missing publishConfig.access");
+    }
+    return {
+      name: manifest.name,
+      version: manifest.version ?? "0.0.0",
+      directory: manifest.directory,
+      private: isPrivate,
+      publishReady: issues.length === 0,
+      issues
+    };
+  });
+  const publishable = packages.filter((pkg) => !pkg.private);
+  const versions = publishable.map((pkg) => pkg.version);
+  const versionCounts = /* @__PURE__ */ new Map();
+  for (const version of versions) {
+    versionCounts.set(version, (versionCounts.get(version) ?? 0) + 1);
+  }
+  let canonicalVersion = null;
+  let maxCount = 0;
+  for (const [version, count] of versionCounts) {
+    if (count > maxCount) {
+      maxCount = count;
+      canonicalVersion = version;
+    }
+  }
+  const drift = canonicalVersion === null ? [] : publishable.filter((pkg) => pkg.version !== canonicalVersion).map((pkg) => ({
+    name: pkg.name,
+    version: pkg.version,
+    expected: canonicalVersion
+  }));
+  const recommendations = [];
+  if (drift.length > 0) {
+    recommendations.push(
+      `Align ${drift.length} package version(s) to ${canonicalVersion} before release`
+    );
+  }
+  if (publishable.some((pkg) => !pkg.publishReady)) {
+    recommendations.push("Fix publish metadata on packages flagged not publish-ready");
+  }
+  if (publishable.length > 0 && drift.length === 0) {
+    recommendations.push("Versions aligned \u2014 run pnpm verify:publish and pnpm build");
+  }
+  return {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    packageCount: packages.length,
+    publishableCount: publishable.length,
+    aligned: drift.length === 0,
+    canonicalVersion,
+    packages,
+    drift,
+    recommendations
+  };
+}
+function formatReleaseReport(report) {
+  const lines = [
+    "laRose Release Intelligence",
+    "",
+    `Packages: ${report.packageCount} (${report.publishableCount} publishable)`,
+    `Canonical version: ${report.canonicalVersion ?? "n/a"}`,
+    `Aligned: ${report.aligned ? "yes" : "no"}`,
+    ""
+  ];
+  if (report.drift.length > 0) {
+    lines.push("Version drift:");
+    for (const entry of report.drift) {
+      lines.push(`  ${entry.name}: ${entry.version} (expected ${entry.expected})`);
+    }
+    lines.push("");
+  }
+  const blocked = report.packages.filter((pkg) => !pkg.private && !pkg.publishReady);
+  if (blocked.length > 0) {
+    lines.push("Publish blockers:");
+    for (const pkg of blocked) {
+      lines.push(`  ${pkg.name}: ${pkg.issues.join(", ")}`);
+    }
+    lines.push("");
+  }
+  if (report.recommendations.length > 0) {
+    lines.push("Recommendations:");
+    for (const tip of report.recommendations) {
+      lines.push(`  - ${tip}`);
+    }
+    lines.push("");
+  }
+  lines.push(report.aligned && blocked.length === 0 ? "Result: READY" : "Result: REVIEW");
+  return lines.join("\n");
+}
+function formatReleaseJson(report) {
+  return JSON.stringify(report, null, 2);
+}
+var DEPRECATIONS = [
+  {
+    id: "role-check",
+    pattern: /user\.role\s*===\s*['"]admin['"]/g,
+    message: "Inline role checks are deprecated",
+    replacement: 'Use <Can permission="..."> from @larose-ui/permissions',
+    removedIn: "1.0.0"
+  },
+  {
+    id: "old-token",
+    pattern: /--ui-color-primary/g,
+    message: "Old token prefix --ui-color-* is deprecated",
+    replacement: "Use --lr-color-* tokens from @larose-ui/tokens",
+    removedIn: "1.0.0"
+  },
+  {
+    id: "react-provider",
+    pattern: /from\s+['"]@larose-ui\/react['"].*LaRoseProvider/g,
+    message: "Import LaRoseProvider from @larose-ui/runtime instead",
+    replacement: "import { LaRoseProvider } from '@larose-ui/runtime'",
+    removedIn: "0.2.0"
+  },
+  {
+    id: "runtime-toast",
+    pattern: /import\s+\{([^}]*\buseToast\b[^}]*)\}\s+from\s+['"]@larose-ui\/runtime['"]/g,
+    message: "Import useToast from @larose-ui/runtime/toast",
+    replacement: "import { useToast } from '@larose-ui/runtime/toast'",
+    removedIn: "0.2.0"
+  }
+];
+function scanSource(source, filePath) {
+  const matches = [];
+  const lines = source.split("\n");
+  for (const dep of DEPRECATIONS) {
+    dep.pattern.lastIndex = 0;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const lineMatches = line.matchAll(dep.pattern);
+      for (const m of lineMatches) {
+        matches.push({
+          id: dep.id,
+          file: filePath,
+          line: i + 1,
+          column: (m.index ?? 0) + 1,
+          message: dep.message,
+          replacement: dep.replacement
+        });
+      }
+    }
+  }
+  return matches;
+}
+function generateMigrationReport(files, targetVersion = "1.0.0") {
+  const deprecatedUsages = files.flatMap((f) => scanSource(f.content, f.path));
+  return {
+    targetVersion,
+    deprecatedUsages,
+    breakingChanges: deprecatedUsages.filter(
+      (d) => DEPRECATIONS.find((x) => x.id === d.id)?.removedIn === targetVersion
+    ).length,
+    summary: `${deprecatedUsages.length} deprecated usages found`
+  };
+}
+function formatMigrationReport(report) {
+  const lines = [
+    `laRose Migration Report (target: v${report.targetVersion})`,
+    "",
+    report.summary,
+    `Breaking changes: ${report.breakingChanges}`,
+    ""
+  ];
+  if (report.deprecatedUsages.length === 0) {
+    lines.push("No deprecated patterns detected.");
+  } else {
+    for (const u of report.deprecatedUsages) {
+      lines.push(`${u.file}:${u.line}:${u.column} [${u.id}]`);
+      lines.push(`  ${u.message}`);
+      lines.push(`  Fix: ${u.replacement}`);
+      lines.push("");
+    }
+    lines.push(`Run: larose migrate --to ${report.targetVersion}`);
+  }
+  return lines.join("\n");
+}
+
+// src/quality/browserMatrix.ts
+var DEFAULT_BROWSER_MATRIX = {
+  version: 1,
+  browsers: [
+    { name: "chrome", minVersion: 120, engine: "Blink" },
+    { name: "firefox", minVersion: 121, engine: "Gecko" },
+    { name: "safari", minVersion: 17, engine: "WebKit" },
+    { name: "edge", minVersion: 120, engine: "Blink" }
+  ],
+  engines: {
+    node: ">=20"
+  }
+};
+function validateBrowserMatrix(matrix, nodeEngine) {
+  const issues = [];
+  if (matrix.browsers.length === 0) {
+    issues.push("Browser matrix must define at least one browser target");
+  }
+  for (const browser of matrix.browsers) {
+    if (!browser.name.trim()) issues.push("Browser target missing name");
+    if (browser.minVersion <= 0) {
+      issues.push(`Browser ${browser.name} has invalid minVersion`);
+    }
+  }
+  if (nodeEngine && matrix.engines.node) {
+    const expected = normalizeEngine(matrix.engines.node);
+    const actual = normalizeEngine(nodeEngine);
+    if (expected && actual && expected !== actual) {
+      issues.push(
+        `Node engine mismatch: package.json specifies "${nodeEngine}", matrix requires "${matrix.engines.node}"`
+      );
+    }
+  }
+  return {
+    passed: issues.length === 0,
+    matrix,
+    nodeEngine,
+    issues
+  };
+}
+function normalizeEngine(value) {
+  return value.replace(/\s+/g, "");
+}
+
+// src/quality/qualityScores.ts
+var ERROR_PENALTY = 15;
+var WARNING_PENALTY = 5;
+function computeQualityScores(diagnostics, options = {}) {
+  const treatWarningsAsErrors = options.ci === true;
+  const componentMap = /* @__PURE__ */ new Map();
+  const packageMap = /* @__PURE__ */ new Map();
+  for (const diagnostic of diagnostics) {
+    const isError = diagnostic.severity === "error" || treatWarningsAsErrors && diagnostic.severity === "warning";
+    if (diagnostic.category === "bundle") {
+      const pkgMatch = diagnostic.message.match(/^(@larose-ui\/[^\s]+)/);
+      const pkg = pkgMatch?.[1] ?? "unknown";
+      const entry2 = packageMap.get(pkg) ?? {
+        package: pkg,
+        score: 100,
+        issues: 0
+      };
+      entry2.issues += 1;
+      entry2.score -= isError ? ERROR_PENALTY : WARNING_PENALTY;
+      const sizeMatch = diagnostic.message.match(/bundle\s+([\d.]+)KB/);
+      if (sizeMatch?.[1]) entry2.bundleKb = Number(sizeMatch[1]);
+      packageMap.set(pkg, entry2);
+      continue;
+    }
+    const componentId = diagnostic.file ?? "unknown";
+    const entry = componentMap.get(componentId) ?? {
+      id: componentId,
+      score: 100,
+      errors: 0,
+      warnings: 0,
+      categories: []
+    };
+    if (diagnostic.severity === "error") entry.errors += 1;
+    if (diagnostic.severity === "warning") entry.warnings += 1;
+    entry.score -= isError ? ERROR_PENALTY : WARNING_PENALTY;
+    if (!entry.categories.includes(diagnostic.category)) {
+      entry.categories.push(diagnostic.category);
+    }
+    componentMap.set(componentId, entry);
+  }
+  const components = [...componentMap.values()].map((entry) => ({ ...entry, score: clampScore(entry.score) })).sort((a, b) => a.score - b.score);
+  const packages = [...packageMap.values()].map((entry) => ({ ...entry, score: clampScore(entry.score) })).sort((a, b) => a.score - b.score);
+  const overall = clampScore(
+    average([
+      ...components.map((entry) => entry.score),
+      ...packages.map((entry) => entry.score)
+    ]) ?? 100
+  );
+  return { overall, components, packages };
+}
+function average(values) {
+  if (values.length === 0) return void 0;
+  return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+function clampScore(score) {
+  return Math.max(0, Math.min(100, Math.round(score)));
+}
+function qualityPassed(diagnostics, options = {}) {
+  const treatWarningsAsErrors = options.ci === true;
+  const hasBlockingDiagnostics = diagnostics.some(
+    (diagnostic) => treatWarningsAsErrors ? diagnostic.severity === "error" || diagnostic.severity === "warning" : diagnostic.severity === "error"
+  );
+  if (hasBlockingDiagnostics) return false;
+  if (options.browserMatrix && !options.browserMatrix.passed) return false;
+  if (options.visualRegression && !options.visualRegression.passed) return false;
+  return true;
+}
+
+// src/quality/visualManifest.ts
+import { readdir, readFile } from "fs/promises";
+import { join } from "path";
+var META_TITLE_PATTERN = /const\s+meta[\s\S]*?title:\s*['"]([^'"]+)['"]/;
+async function scanStoryManifest(storiesDir) {
+  const entries = await readdir(storiesDir, { withFileTypes: true });
+  const stories = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".stories.tsx")) continue;
+    const file = entry.name;
+    const source = await readFile(join(storiesDir, file), "utf-8");
+    stories.push({
+      file,
+      title: extractStoryTitle(source, file)
+    });
+  }
+  return stories.sort((a, b) => a.file.localeCompare(b.file));
+}
+function extractStoryTitle(source, file) {
+  const metaMatch = source.match(META_TITLE_PATTERN);
+  if (metaMatch?.[1]) return metaMatch[1];
+  const metaIndex = source.indexOf("const meta");
+  if (metaIndex >= 0) {
+    const slice = source.slice(metaIndex, metaIndex + 600);
+    const titleMatch = slice.match(/title:\s*['"]([^'"]+)['"]/);
+    if (titleMatch?.[1]) return titleMatch[1];
+  }
+  const head = source.split("\n").slice(0, 25).join("\n");
+  const headMatch = head.match(/title:\s*['"]([^'"]+)['"]/);
+  return headMatch?.[1] ?? file.replace(".stories.tsx", "");
+}
+function compareVisualBaseline(current, baseline) {
+  const baselineByFile = new Map(baseline.stories.map((story) => [story.file, story]));
+  const currentByFile = new Map(current.map((story) => [story.file, story]));
+  const missing = baseline.stories.filter((story) => !currentByFile.has(story.file));
+  const added = current.filter((story) => !baselineByFile.has(story.file));
+  const changed = [];
+  for (const story of current) {
+    const base = baselineByFile.get(story.file);
+    if (base && base.title !== story.title) {
+      changed.push({
+        file: story.file,
+        baselineTitle: base.title,
+        currentTitle: story.title
+      });
+    }
+  }
+  return {
+    passed: missing.length === 0 && changed.length === 0,
+    current,
+    missing,
+    added,
+    changed
+  };
+}
+function formatVisualRegressionReport(result) {
+  const lines = ["Visual regression manifest", ""];
+  if (result.passed && result.added.length === 0) {
+    lines.push(`All ${result.current.length} baseline stories present.`);
+    return lines.join("\n");
+  }
+  if (result.missing.length > 0) {
+    lines.push("Missing stories (removed or renamed):");
+    for (const story of result.missing) {
+      lines.push(`  - ${story.file} (${story.title})`);
+    }
+    lines.push("");
+  }
+  if (result.changed.length > 0) {
+    lines.push("Changed story titles:");
+    for (const change of result.changed) {
+      lines.push(
+        `  - ${change.file}: "${change.baselineTitle}" \u2192 "${change.currentTitle}"`
+      );
+    }
+    lines.push("");
+  }
+  if (result.added.length > 0) {
+    lines.push("New stories (update quality/visual-baseline.json):");
+    for (const story of result.added) {
+      lines.push(`  + ${story.file} (${story.title})`);
+    }
+    lines.push("");
+  }
+  lines.push(result.passed ? "Result: PASS" : "Result: FAIL");
+  return lines.join("\n");
+}
+
+// src/doctor.ts
+var BUNDLE_BUDGETS_KB = {
+  "@larose-ui/core": 10,
+  "@larose-ui/tokens": 5,
+  "@larose-ui/network": 6,
+  "@larose-ui/offline": 5,
+  "@larose-ui/permissions": 8,
+  "@larose-ui/data": 15,
+  "@larose-ui/forms": 10,
+  "@larose-ui/react": 70,
+  "@larose-ui/runtime": 36,
+  "@larose-ui/observability": 26,
+  "@larose-ui/contracts": 5,
+  "@larose-ui/migration": 14,
+  "@larose-ui/testing": 10,
+  "@larose-ui/cli": 50,
+  "@larose-ui/devtools": 22,
+  "@larose-ui/enterprise": 25,
+  "@larose-ui/ai": 20,
+  "@larose-ui/accessibility": 5,
+  "@larose-ui/themes": 5
+};
+async function walkDir(dir, ext) {
+  const entries = await readdir2(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const full = join2(dir, entry.name);
+    if (entry.name === "node_modules" || entry.name === "dist" && dir.includes("node_modules")) continue;
+    if (entry.isDirectory()) {
+      files.push(...await walkDir(full, ext));
+    } else if (ext.some((e) => entry.name.endsWith(e))) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+var BUNDLE_ENTRY = {
+  "@larose-ui/cli": "dist/cli.js"
+};
+async function checkBundleBudgets(packagesDir) {
+  const diagnostics = [];
+  const packages = await readdir2(packagesDir, { withFileTypes: true });
+  for (const pkg of packages) {
+    if (!pkg.isDirectory()) continue;
+    const pkgName = `@larose-ui/${pkg.name}`;
+    const budget = BUNDLE_BUDGETS_KB[pkgName];
+    if (!budget) continue;
+    const distFile = join2(packagesDir, pkg.name, BUNDLE_ENTRY[pkgName] ?? "dist/index.js");
+    try {
+      const info = await stat(distFile);
+      const sizeKb = info.size / 1024;
+      if (sizeKb > budget) {
+        diagnostics.push({
+          severity: "error",
+          category: "bundle",
+          message: `${pkgName} bundle ${sizeKb.toFixed(1)}KB exceeds budget ${budget}KB`,
+          fix: "Reduce bundle size or update budget in doctor.ts",
+          file: distFile
+        });
+      } else if (sizeKb > budget * 0.9) {
+        diagnostics.push({
+          severity: "info",
+          category: "bundle",
+          message: `${pkgName} bundle ${sizeKb.toFixed(1)}KB approaching budget ${budget}KB`,
+          file: distFile
+        });
+      }
+    } catch {
+      diagnostics.push({
+        severity: "error",
+        category: "build",
+        message: `${pkgName} missing ${BUNDLE_ENTRY[pkgName] ?? "dist/index.js"} \u2014 run pnpm build`,
+        fix: "pnpm build"
+      });
+    }
+  }
+  return diagnostics;
+}
+async function checkDeprecations(rootDir2) {
+  const diagnostics = [];
+  const srcFiles = await walkDir(join2(rootDir2, "packages"), [".ts", ".tsx"]);
+  const appFiles = await walkDir(join2(rootDir2, "apps"), [".ts", ".tsx"]);
+  const allFiles = [...srcFiles, ...appFiles];
+  for (const file of allFiles) {
+    if (file.includes(".test.") || file.includes("node_modules")) continue;
+    if (file.includes("packages/migration/")) continue;
+    const content = await readFile2(file, "utf-8");
+    const matches = scanSource(content, relative(rootDir2, file));
+    for (const m of matches) {
+      diagnostics.push({
+        severity: "warning",
+        category: "deprecation",
+        message: m.message,
+        fix: m.replacement,
+        file: m.file
+      });
+    }
+  }
+  return diagnostics;
+}
+async function checkAccessibility(rootDir2) {
+  const diagnostics = [];
+  const reactFiles = await walkDir(join2(rootDir2, "packages/react/src"), [".tsx"]);
+  for (const file of reactFiles) {
+    if (file.includes(".test.")) continue;
+    const content = await readFile2(file, "utf-8");
+    const rel = relative(rootDir2, file);
+    const result = scanComponentSource(content, rel);
+    for (const v of result.violations) {
+      diagnostics.push({
+        severity: v.severity,
+        category: "accessibility",
+        message: v.message,
+        fix: v.fix,
+        file: v.file
+      });
+    }
+  }
+  return diagnostics;
+}
+async function checkContracts(rootDir2) {
+  const diagnostics = [];
+  const contractsDir = join2(rootDir2, "contracts");
+  try {
+    const files = await readdir2(contractsDir);
+    for (const file of files) {
+      if (!file.endsWith(".json")) continue;
+      const raw = await readFile2(join2(contractsDir, file), "utf-8");
+      const data = JSON.parse(raw);
+      if (data.ui && data.api) {
+        const result = validateContract(data.ui, data.api);
+        if (!result.valid) {
+          for (const m of result.mismatches.filter((x) => x.severity === "error")) {
+            diagnostics.push({
+              severity: "error",
+              category: "contract",
+              message: m.message,
+              file: join2("contracts", file)
+            });
+          }
+        }
+      }
+    }
+  } catch {
+  }
+  return diagnostics;
+}
+async function checkBrowserMatrix(rootDir2) {
+  const diagnostics = [];
+  let matrix = DEFAULT_BROWSER_MATRIX;
+  let nodeEngine;
+  try {
+    const raw = await readFile2(join2(rootDir2, "quality/browser-matrix.json"), "utf-8");
+    matrix = JSON.parse(raw);
+  } catch {
+  }
+  try {
+    const pkgRaw = await readFile2(join2(rootDir2, "package.json"), "utf-8");
+    const pkg = JSON.parse(pkgRaw);
+    nodeEngine = pkg.engines?.node;
+  } catch {
+  }
+  const check = validateBrowserMatrix(matrix, nodeEngine);
+  for (const issue of check.issues) {
+    diagnostics.push({
+      severity: "error",
+      category: "browser",
+      message: issue,
+      fix: "Align package.json engines with quality/browser-matrix.json"
+    });
+  }
+  return { diagnostics, check };
+}
+async function checkVisualRegression(rootDir2) {
+  const diagnostics = [];
+  const storiesDir = join2(rootDir2, "apps/playground/stories");
+  const current = await scanStoryManifest(storiesDir);
+  let baseline = { version: 1, stories: [] };
+  try {
+    const raw = await readFile2(join2(rootDir2, "quality/visual-baseline.json"), "utf-8");
+    baseline = JSON.parse(raw);
+  } catch {
+    diagnostics.push({
+      severity: "error",
+      category: "visual",
+      message: "Missing quality/visual-baseline.json",
+      fix: "Add visual baseline manifest for Storybook stories",
+      file: "quality/visual-baseline.json"
+    });
+    return {
+      diagnostics,
+      result: {
+        passed: false,
+        current,
+        missing: baseline.stories,
+        added: current,
+        changed: []
+      }
+    };
+  }
+  const result = compareVisualBaseline(current, baseline);
+  for (const story of result.missing) {
+    diagnostics.push({
+      severity: "error",
+      category: "visual",
+      message: `Story removed from baseline: ${story.file} (${story.title})`,
+      fix: "Restore story or update quality/visual-baseline.json intentionally",
+      file: join2("apps/playground/stories", story.file)
+    });
+  }
+  for (const change of result.changed) {
+    diagnostics.push({
+      severity: "warning",
+      category: "visual",
+      message: `Story title changed: ${change.file} "${change.baselineTitle}" \u2192 "${change.currentTitle}"`,
+      fix: "Update quality/visual-baseline.json if rename is intentional",
+      file: join2("apps/playground/stories", change.file)
+    });
+  }
+  for (const story of result.added) {
+    diagnostics.push({
+      severity: "warning",
+      category: "visual",
+      message: `New story not in baseline: ${story.file} (${story.title})`,
+      fix: "Add entry to quality/visual-baseline.json",
+      file: join2("apps/playground/stories", story.file)
+    });
+  }
+  return { diagnostics, result };
+}
+async function runVisualRegressionCheck(rootDir2) {
+  const { result } = await checkVisualRegression(rootDir2);
+  return result;
+}
+async function runDoctor(rootDir2, options = {}) {
+  const packagesDir = join2(rootDir2, "packages");
+  const diagnostics = [
+    ...await checkBundleBudgets(packagesDir),
+    ...await checkDeprecations(rootDir2),
+    ...await checkAccessibility(rootDir2),
+    ...await checkContracts(rootDir2)
+  ];
+  let browserMatrix;
+  if (!options.skipBrowser) {
+    const browser = await checkBrowserMatrix(rootDir2);
+    diagnostics.push(...browser.diagnostics);
+    browserMatrix = browser.check;
+  }
+  let visualRegression;
+  if (!options.skipVisual) {
+    const visual = await checkVisualRegression(rootDir2);
+    diagnostics.push(...visual.diagnostics);
+    visualRegression = visual.result;
+  }
+  const quality = computeQualityScores(diagnostics, { ci: options.ci });
+  const passed = qualityPassed(diagnostics, {
+    ci: options.ci,
+    browserMatrix,
+    visualRegression
+  });
+  return { passed, diagnostics, quality, browserMatrix, visualRegression };
+}
+function formatDoctorReport(result, options = {}) {
+  const lines = ["laRose Doctor", ""];
+  lines.push(`Quality score: ${result.quality.overall}/100`);
+  if (options.ci) lines.push("Mode: CI (warnings fail)");
+  lines.push("");
+  if (result.diagnostics.length === 0) {
+    lines.push("All checks passed.");
+    lines.push("");
+    lines.push("Result: PASS");
+    return lines.join("\n");
+  }
+  for (const d of result.diagnostics) {
+    if (d.severity === "info") continue;
+    lines.push(`[${d.severity.toUpperCase()}] ${d.category}: ${d.message}`);
+    if (d.file) lines.push(`  File: ${d.file}`);
+    if (d.fix) lines.push(`  Fix: ${d.fix}`);
+    lines.push("");
+  }
+  if (result.quality.components.length > 0) {
+    lines.push("Lowest component scores:");
+    for (const component of result.quality.components.slice(0, 5)) {
+      lines.push(
+        `  ${component.id}: ${component.score}/100 (${component.errors}e/${component.warnings}w)`
+      );
+    }
+    lines.push("");
+  }
+  lines.push(result.passed ? "Result: PASS" : "Result: FAIL");
+  return lines.join("\n");
+}
+function formatDoctorJson(result, options = {}) {
+  return JSON.stringify(
+    {
+      passed: result.passed,
+      ci: options.ci === true,
+      qualityScore: result.quality.overall,
+      quality: result.quality,
+      browserMatrix: result.browserMatrix,
+      visualRegression: result.visualRegression ? {
+        passed: result.visualRegression.passed,
+        storyCount: result.visualRegression.current.length,
+        missing: result.visualRegression.missing,
+        added: result.visualRegression.added,
+        changed: result.visualRegression.changed
+      } : void 0,
+      diagnostics: result.diagnostics
+    },
+    null,
+    2
+  );
+}
+async function runMigrate(rootDir2, targetVersion, options = {}) {
+  const files = [];
+  const allFiles = [
+    ...await walkDir(join2(rootDir2, "packages"), [".ts", ".tsx"]),
+    ...await walkDir(join2(rootDir2, "apps"), [".ts", ".tsx"])
+  ];
+  for (const file of allFiles) {
+    if (file.includes(".test.") || file.includes("packages/migration/")) continue;
+    files.push({
+      path: relative(rootDir2, file),
+      content: await readFile2(file, "utf-8")
+    });
+  }
+  const report = generateMigrationReport(files, targetVersion);
+  const lines = [formatMigrationReport(report)];
+  if (options.apply) {
+    const results = applyCodemodsToFiles(files);
+    for (const result of results) {
+      if (result.changed) {
+        await writeFile(join2(rootDir2, result.path), result.content, "utf-8");
+      }
+    }
+    lines.push("", formatCodemodReport(results));
+  } else if (report.deprecatedUsages.length > 0) {
+    lines.push("", `Run: larose migrate --to ${targetVersion} --apply`);
+  }
+  return lines.join("\n");
+}
+function runGenerate(type, name) {
+  return runGenerator(type, name);
+}
+async function runRelease(rootDir2, json = false) {
+  const packagesDir = join2(rootDir2, "packages");
+  const entries = await readdir2(packagesDir, { withFileTypes: true });
+  const manifests = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    try {
+      const raw = await readFile2(join2(packagesDir, entry.name, "package.json"), "utf-8");
+      const pkg = JSON.parse(raw);
+      manifests.push({
+        name: pkg.name,
+        version: pkg.version,
+        private: pkg.private,
+        license: pkg.license,
+        publishConfig: pkg.publishConfig,
+        directory: `packages/${entry.name}`
+      });
+    } catch {
+    }
+  }
+  const report = analyzeRelease(manifests);
+  const blocked = report.packages.filter((pkg) => !pkg.private && !pkg.publishReady);
+  const ready = report.aligned && blocked.length === 0;
+  const output = json ? formatReleaseJson(report) : formatReleaseReport(report);
+  return { output, ready };
+}
+
+// src/cli.ts
+var args = process.argv.slice(2);
+var command = args[0] ?? "help";
+var rootDir = resolve(process.cwd());
+function hasFlag(flag) {
+  return args.includes(flag);
+}
+async function main() {
+  switch (command) {
+    case "doctor": {
+      const options = {
+        ci: hasFlag("--ci"),
+        skipVisual: hasFlag("--skip-visual"),
+        skipBrowser: hasFlag("--skip-browser")
+      };
+      const result = await runDoctor(rootDir, options);
+      if (hasFlag("--json")) {
+        console.log(formatDoctorJson(result, options));
+      } else {
+        console.log(formatDoctorReport(result, options));
+      }
+      process.exit(result.passed ? 0 : 1);
+      break;
+    }
+    case "visual-regression": {
+      const result = await runVisualRegressionCheck(rootDir);
+      console.log(formatVisualRegressionReport(result));
+      process.exit(result.passed ? 0 : 1);
+      break;
+    }
+    case "migrate": {
+      const toIndex = args.indexOf("--to");
+      const version = toIndex >= 0 ? args[toIndex + 1] ?? "1.0.0" : "1.0.0";
+      const apply = args.includes("--apply");
+      console.log(await runMigrate(rootDir, version, { apply }));
+      break;
+    }
+    case "generate": {
+      const type = args[1] ?? "form";
+      const name = args[2] ?? "Example";
+      const output = args[3];
+      const code = runGenerate(type, name);
+      if (output) {
+        writeFileSync(output, code);
+        console.log(`Generated ${output}`);
+      } else {
+        console.log(code);
+      }
+      break;
+    }
+    case "release": {
+      const { output, ready } = await runRelease(rootDir, hasFlag("--json"));
+      console.log(output);
+      process.exit(ready ? 0 : 1);
+      break;
+    }
+    default:
+      console.log(`laRose CLI
+
+Usage:
+  larose doctor              Run quality checks
+  larose doctor --ci         CI mode (warnings fail)
+  larose doctor --json       JSON report for CI pipelines
+  larose doctor --ci --json  Combined CI + JSON output
+  larose visual-regression   Validate Storybook story manifest
+  larose migrate --to 1.0.0       Migration report (dry run)
+  larose migrate --to 1.0.0 --apply  Apply safe codemods
+  larose generate form Name     Generate form scaffold
+  larose generate page Name     Generate page scaffold
+  larose generate feature Name  Generate full feature scaffold
+  larose release                Monorepo release readiness report
+  larose release --json         JSON release report
+`);
+  }
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@larose-ui/cli",
+  "version": "0.1.0",
+  "description": "CLI for laRose UI platform — doctor, migrate, generate",
+  "type": "module",
+  "bin": {
+    "larose": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@larose-ui/accessibility": "0.1.0",
+    "@larose-ui/contracts": "0.1.0",
+    "@larose-ui/migration": "0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/larose-ui/larose.git",
+    "directory": "packages/cli"
+  },
+  "keywords": [
+    "larose",
+    "react",
+    "ui-platform",
+    "design-system",
+    "saas"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup src/cli.ts --format esm --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}