@devfellowship/components 1.2.1 → 1.2.3

package/dist/cli.js

@@ -0,0 +1,737 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { Command } from "commander";
+
+// src/cli/commands/init.ts
+import fs from "fs-extra";
+import path from "path";
+import chalk2 from "chalk";
+import ora from "ora";
+import prompts from "prompts";
+
+// src/cli/types/config.ts
+import { z } from "zod";
+var configSchema = z.object({
+  typescript: z.boolean().default(true),
+  aliases: z.object({
+    components: z.string().default("@/components/dfl"),
+    hooks: z.string().default("@/hooks"),
+    providers: z.string().default("@/providers"),
+    pages: z.string().default("@/pages")
+  }),
+  registry: z.string().default("https://raw.githubusercontent.com/taigfs/dfl-components-cli/main/registry")
+});
+
+// src/cli/utils/logger.ts
+import chalk from "chalk";
+var logger = {
+  info: (message) => console.log(chalk.blue("info"), message),
+  success: (message) => console.log(chalk.green("\u2713"), message),
+  warn: (message) => console.log(chalk.yellow("warn"), message),
+  error: (message) => console.log(chalk.red("error"), message),
+  break: () => console.log("")
+};
+
+// src/cli/commands/init.ts
+async function init(options) {
+  const cwd = path.resolve(options.cwd);
+  logger.info("Initializing dfl-components configuration...");
+  logger.break();
+  const configPath = path.join(cwd, "dfl-components.json");
+  if (await fs.pathExists(configPath)) {
+    const { overwrite } = await prompts({
+      type: "confirm",
+      name: "overwrite",
+      message: "dfl-components.json already exists. Overwrite?",
+      initial: false
+    });
+    if (!overwrite) {
+      logger.warn("Aborted.");
+      return;
+    }
+  }
+  let config;
+  if (options.yes) {
+    config = configSchema.parse({
+      aliases: {}
+    });
+  } else {
+    const answers = await prompts([
+      {
+        type: "confirm",
+        name: "typescript",
+        message: "Would you like to use TypeScript?",
+        initial: true
+      },
+      {
+        type: "text",
+        name: "componentsPath",
+        message: "Where would you like to install components?",
+        initial: "@/components/dfl"
+      },
+      {
+        type: "text",
+        name: "hooksPath",
+        message: "Where would you like to install hooks?",
+        initial: "@/hooks"
+      },
+      {
+        type: "text",
+        name: "providersPath",
+        message: "Where would you like to install providers?",
+        initial: "@/providers"
+      },
+      {
+        type: "text",
+        name: "pagesPath",
+        message: "Where would you like to install pages?",
+        initial: "@/pages"
+      }
+    ]);
+    if (!answers.typescript) {
+      logger.warn("Aborted.");
+      return;
+    }
+    config = configSchema.parse({
+      typescript: answers.typescript,
+      aliases: {
+        components: answers.componentsPath,
+        hooks: answers.hooksPath,
+        providers: answers.providersPath,
+        pages: answers.pagesPath
+      }
+    });
+  }
+  const spinner = ora("Writing configuration...").start();
+  try {
+    await fs.writeJson(configPath, config, { spaces: 2 });
+    spinner.succeed("Configuration saved to dfl-components.json");
+    logger.break();
+    logger.success("Project initialized successfully!");
+    logger.break();
+    console.log("You can now add components:");
+    console.log(chalk2.cyan("  npx dfl-components add button"));
+    console.log(chalk2.cyan("  npx dfl-components add card input"));
+    console.log(chalk2.cyan("  npx dfl-components add auth-pages"));
+    logger.break();
+  } catch (error) {
+    spinner.fail("Failed to write configuration");
+    throw error;
+  }
+}
+
+// src/cli/commands/add.ts
+import fs2 from "fs-extra";
+import path2 from "path";
+import chalk3 from "chalk";
+import ora2 from "ora";
+import prompts2 from "prompts";
+
+// src/cli/utils/get-config.ts
+import { cosmiconfig } from "cosmiconfig";
+async function getConfig(cwd) {
+  const explorer = cosmiconfig("dfl-components", {
+    searchPlaces: ["dfl-components.json"]
+  });
+  const result = await explorer.search(cwd);
+  if (!result) {
+    return null;
+  }
+  return configSchema.parse(result.config);
+}
+
+// src/cli/utils/get-registry.ts
+import fetch2 from "node-fetch";
+async function getRegistry(registryUrl) {
+  const response = await fetch2(`${registryUrl}/registry.json`);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch registry: ${response.statusText}`);
+  }
+  return response.json();
+}
+function getComponentFolderByCategory(category) {
+  switch (category) {
+    case "Hooks":
+      return "hooks";
+    case "Providers":
+      return "providers";
+    case "Pages":
+      return "pages";
+    default:
+      return "components";
+  }
+}
+
+// src/cli/utils/resolve-alias.ts
+function resolveAlias(aliasPath) {
+  if (aliasPath.startsWith("@/")) {
+    return aliasPath.replace("@/", "src/");
+  }
+  return aliasPath;
+}
+function getTargetPath(category, aliases) {
+  switch (category) {
+    case "Hooks":
+      return resolveAlias(aliases.hooks);
+    case "Providers":
+      return resolveAlias(aliases.providers);
+    case "Pages":
+      return resolveAlias(aliases.pages);
+    default:
+      return resolveAlias(aliases.components);
+  }
+}
+
+// src/cli/commands/add.ts
+async function add(components, options) {
+  const cwd = path2.resolve(options.cwd);
+  const config = await getConfig(cwd);
+  if (!config) {
+    logger.error("No dfl-components.json found.");
+    console.log("Run", chalk3.cyan("npx dfl-components init"), "first.");
+    return;
+  }
+  const spinner = ora2("Fetching registry...").start();
+  try {
+    let resolveDeps2 = function(name) {
+      if (allComponents.has(name)) return;
+      allComponents.add(name);
+      const item = registry.items.find((i) => i.name === name);
+      if (item?.registryDependencies) {
+        for (const dep of item.registryDependencies) {
+          resolveDeps2(dep);
+        }
+      }
+    };
+    var resolveDeps = resolveDeps2;
+    const registry = await getRegistry(config.registry);
+    let toInstall;
+    if (options.all) {
+      toInstall = registry.items.map((item) => item.name);
+    } else if (components.length === 0) {
+      spinner.stop();
+      const { selected } = await prompts2({
+        type: "multiselect",
+        name: "selected",
+        message: "Which components would you like to add?",
+        choices: registry.items.map((item) => ({
+          title: `${item.title} (${item.category})`,
+          value: item.name,
+          description: item.description
+        })),
+        min: 1
+      });
+      if (!selected || selected.length === 0) {
+        logger.warn("No components selected.");
+        return;
+      }
+      toInstall = selected;
+      spinner.start("Fetching components...");
+    } else {
+      toInstall = components;
+    }
+    const validComponents = [];
+    for (const name of toInstall) {
+      const item = registry.items.find((i) => i.name === name);
+      if (!item) {
+        logger.warn(`Component "${name}" not found in registry. Skipping.`);
+      } else {
+        validComponents.push(name);
+      }
+    }
+    if (validComponents.length === 0) {
+      spinner.fail("No valid components to install.");
+      return;
+    }
+    const allComponents = /* @__PURE__ */ new Set();
+    for (const component of validComponents) {
+      resolveDeps2(component);
+    }
+    spinner.text = `Installing ${allComponents.size} component(s)...`;
+    const installed = [];
+    const errors = [];
+    for (const componentName of allComponents) {
+      const registryItem = registry.items.find((i) => i.name === componentName);
+      if (!registryItem) continue;
+      try {
+        const folder = getComponentFolderByCategory(registryItem.category);
+        const url = `${config.registry}/${folder}/${componentName}.json`;
+        const response = await fetch(url);
+        if (!response.ok) {
+          throw new Error(`Failed to fetch: ${response.statusText}`);
+        }
+        const componentData = await response.json();
+        for (const file of componentData.files) {
+          const targetDir = file.target ? path2.dirname(path2.join(cwd, "src", file.target)) : path2.join(cwd, getTargetPath(registryItem.category, config.aliases));
+          const targetPath = file.target ? path2.join(cwd, "src", file.target) : path2.join(targetDir, file.path);
+          if (await fs2.pathExists(targetPath)) {
+            if (!options.overwrite && !options.yes) {
+              spinner.stop();
+              const { overwrite } = await prompts2({
+                type: "confirm",
+                name: "overwrite",
+                message: `${path2.relative(cwd, targetPath)} already exists. Overwrite?`,
+                initial: false
+              });
+              if (!overwrite) {
+                logger.info(`Skipping ${path2.basename(targetPath)}`);
+                continue;
+              }
+              spinner.start();
+            } else if (!options.overwrite) {
+              logger.info(`Skipping ${path2.basename(targetPath)} (use --overwrite to replace)`);
+              continue;
+            }
+          }
+          await fs2.ensureDir(path2.dirname(targetPath));
+          await fs2.writeFile(targetPath, file.content);
+          installed.push(targetPath);
+        }
+      } catch (error) {
+        errors.push(`${componentName}: ${error instanceof Error ? error.message : "Unknown error"}`);
+      }
+    }
+    spinner.succeed(`Installed ${installed.length} file(s)`);
+    if (installed.length > 0) {
+      logger.break();
+      console.log(chalk3.green("Files created:"));
+      for (const file of installed) {
+        console.log(chalk3.gray("  -"), path2.relative(cwd, file));
+      }
+    }
+    if (errors.length > 0) {
+      logger.break();
+      console.log(chalk3.red("Errors:"));
+      for (const error of errors) {
+        console.log(chalk3.gray("  -"), error);
+      }
+    }
+    logger.break();
+  } catch (error) {
+    spinner.fail("Failed to add components");
+    throw error;
+  }
+}
+
+// src/cli/ux-paths/commands/init.ts
+import { mkdirSync, writeFileSync, existsSync } from "fs";
+import { resolve, basename } from "path";
+import chalk4 from "chalk";
+function registerInit(program2) {
+  program2.command("init").description("Bootstrap a .dfl-ux-paths/ directory in the current cwd.").option("--app-id <id>", "App identifier (defaults to current dir name).").option("--force", "Overwrite an existing flows.json if present.", false).action((opts) => {
+    const cwd = process.cwd();
+    const dir = resolve(cwd, ".dfl-ux-paths");
+    const flowsPath = resolve(dir, "flows.json");
+    const appId = opts.appId || basename(cwd);
+    if (existsSync(flowsPath) && !opts.force) {
+      console.error(
+        chalk4.yellow(`${flowsPath} already exists. Use --force to overwrite.`)
+      );
+      process.exit(1);
+    }
+    mkdirSync(dir, { recursive: true });
+    const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+    const stub = {
+      schema_version: "1.0.0",
+      app_id: appId,
+      app_version: `${today}-0000000`,
+      generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+      tech_stack: [],
+      screens: [],
+      flows: []
+    };
+    writeFileSync(flowsPath, JSON.stringify(stub, null, 2) + "\n", "utf8");
+    console.log(chalk4.green("Created"), flowsPath);
+    console.log(
+      chalk4.gray(
+        "Next steps: populate screens/flows, then run `dfl-components ux-paths validate` and `dfl-components ux-paths generate-mermaid`."
+      )
+    );
+  });
+}
+
+// src/cli/ux-paths/commands/validate.ts
+import { readFileSync, existsSync as existsSync2 } from "fs";
+import { resolve as resolve2 } from "path";
+import Ajv2020 from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import chalk5 from "chalk";
+
+// src/cli/ux-paths/lib/load-schema.ts
+var SCHEMA_URL = "https://raw.githubusercontent.com/devfellowship/dfl-ux-paths/main/schema/v1.json";
+var cached = null;
+async function loadSchemaV1() {
+  if (cached) return cached;
+  let res;
+  try {
+    res = await fetch(SCHEMA_URL);
+  } catch (err) {
+    throw new Error(
+      `Unable to fetch the UX Paths schema from ${SCHEMA_URL}: ${err.message}`
+    );
+  }
+  if (!res.ok) {
+    throw new Error(
+      `Unable to fetch the UX Paths schema from ${SCHEMA_URL}: HTTP ${res.status} ${res.statusText}`
+    );
+  }
+  cached = await res.json();
+  return cached;
+}
+
+// src/cli/ux-paths/commands/validate.ts
+function registerValidate(program2) {
+  program2.command("validate [path]").description("Validate a flows.json against the DFL UX Paths v1 schema.").action(async (maybePath) => {
+    const path3 = resolve2(process.cwd(), maybePath || ".dfl-ux-paths/flows.json");
+    if (!existsSync2(path3)) {
+      console.error(chalk5.red("File not found:"), path3);
+      process.exit(1);
+    }
+    let doc;
+    try {
+      doc = JSON.parse(readFileSync(path3, "utf8"));
+    } catch (err) {
+      console.error(chalk5.red("Invalid JSON:"), err.message);
+      process.exit(1);
+    }
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    addFormats(ajv);
+    let schema;
+    try {
+      schema = await loadSchemaV1();
+    } catch (err) {
+      console.error(chalk5.red("Schema error:"), err.message);
+      process.exit(1);
+    }
+    const validate = ajv.compile(schema);
+    const ok = validate(doc);
+    if (ok) {
+      console.log(chalk5.green("OK"), path3, "conforms to schema v1.");
+      process.exit(0);
+    }
+    console.error(chalk5.red("FAIL"), path3);
+    for (const err of validate.errors ?? []) {
+      console.error(
+        chalk5.yellow("  -"),
+        err.instancePath || "<root>",
+        err.message,
+        err.params ? JSON.stringify(err.params) : ""
+      );
+    }
+    process.exit(1);
+  });
+}
+
+// src/cli/ux-paths/commands/generate-mermaid.ts
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync3 } from "fs";
+import { resolve as resolve3, dirname } from "path";
+import chalk6 from "chalk";
+
+// src/cli/ux-paths/lib/json-to-mermaid.ts
+function jsonToMermaid(doc) {
+  const lines = [];
+  lines.push("graph TD");
+  lines.push(`  %% app_id: ${doc.app_id}`);
+  lines.push(`  %% app_version: ${doc.app_version}`);
+  lines.push(`  %% schema_version: ${doc.schema_version}`);
+  if (doc.test_metadata?.base_url) {
+    lines.push(`  %% base_url: ${doc.test_metadata.base_url}`);
+  }
+  for (const screen of doc.screens) {
+    const lockPrefix = screen.prerequisites?.auth_required ? "\u{1F512} " : "";
+    lines.push(
+      `  ${sanitizeId(screen.id)}["${escapeLabel(lockPrefix + screen.name)}"]`
+    );
+  }
+  for (const screen of doc.screens) {
+    if (screen.navigation_path && screen.navigation_path.length > 0) {
+      const summary = screen.navigation_path.map((s) => `${s.action} ${s.selector}`).join(" -> ");
+      lines.push(`  %% nav[${sanitizeId(screen.id)}]: ${summary}`);
+    }
+  }
+  for (const screen of doc.screens) {
+    for (const action of screen.actions ?? []) {
+      if (action.next_screen) {
+        lines.push(
+          `  ${sanitizeId(screen.id)} -->|${escapeLabel(action.label)}| ${sanitizeId(
+            action.next_screen
+          )}`
+        );
+      }
+    }
+  }
+  for (const flow of doc.flows) {
+    const flowKey = sanitizeId(`flow_${flow.name}`);
+    lines.push(`  subgraph ${flowKey}["Flow: ${escapeLabel(flow.name)}"]`);
+    const nodes = flowStepsToNodes(flow.start, flow.steps);
+    for (let i = 0; i < nodes.length - 1; i++) {
+      const from = nodes[i];
+      const to = nodes[i + 1];
+      if (to.label) {
+        lines.push(
+          `    ${sanitizeId(from.id)} -.->|${escapeLabel(to.label)}| ${sanitizeId(to.id)}`
+        );
+      } else {
+        lines.push(`    ${sanitizeId(from.id)} -.-> ${sanitizeId(to.id)}`);
+      }
+    }
+    if (nodes.length === 1) {
+      lines.push(`    ${sanitizeId(nodes[0].id)}`);
+    }
+    lines.push("  end");
+  }
+  if (doc.dead_code && doc.dead_code.length > 0) {
+    lines.push("  %% --- dead code ---");
+    for (const entry of doc.dead_code) {
+      lines.push(`  %% dead: ${entry.component} \u2014 ${entry.reason}`);
+    }
+  }
+  return lines.join("\n") + "\n";
+}
+function flowStepsToNodes(start, steps) {
+  const out = [{ id: start }];
+  for (const step of steps) {
+    if (typeof step === "string") {
+      out.push({ id: step });
+    } else {
+      const id = step.target_screen ?? step.screen;
+      const labelParts = [];
+      if (step.action) labelParts.push(step.action);
+      if (step.selector) labelParts.push(step.selector);
+      const label = labelParts.length > 0 ? labelParts.join(": ") : void 0;
+      out.push({ id, label });
+    }
+  }
+  return out;
+}
+function sanitizeId(raw) {
+  return raw.replace(/[^A-Za-z0-9_]/g, "_");
+}
+function escapeLabel(raw) {
+  return raw.replace(/"/g, '\\"');
+}
+
+// src/cli/ux-paths/commands/generate-mermaid.ts
+var HEADER = "%% AUTO-GENERATED by dfl-components ux-paths \u2014 do not edit by hand.\n";
+function registerGenerateMermaid(program2) {
+  program2.command("generate-mermaid [path]").description("Generate a Mermaid graph from a flows.json file.").option("-o, --out <file>", "Output path (defaults to <dir>/flows.mmd).").action((maybePath, opts) => {
+    const path3 = resolve3(process.cwd(), maybePath || ".dfl-ux-paths/flows.json");
+    if (!existsSync3(path3)) {
+      console.error(chalk6.red("File not found:"), path3);
+      process.exit(1);
+    }
+    const doc = JSON.parse(readFileSync2(path3, "utf8"));
+    const out = opts.out ? resolve3(process.cwd(), opts.out) : resolve3(dirname(path3), "flows.mmd");
+    const body = HEADER + jsonToMermaid(doc);
+    writeFileSync2(out, body, "utf8");
+    console.log(chalk6.green("Wrote"), out);
+  });
+}
+
+// src/cli/ux-paths/commands/diff.ts
+import { readFileSync as readFileSync3, existsSync as existsSync4 } from "fs";
+import { resolve as resolve4 } from "path";
+import chalk7 from "chalk";
+
+// src/cli/ux-paths/lib/flows-diff.ts
+function flowsDiff(a, b) {
+  const aScreenIds = new Set(a.screens.map((s) => s.id));
+  const bScreenIds = new Set(b.screens.map((s) => s.id));
+  const screensAdded = [...bScreenIds].filter((id) => !aScreenIds.has(id)).sort();
+  const screensRemoved = [...aScreenIds].filter((id) => !bScreenIds.has(id)).sort();
+  const screensCommon = [...aScreenIds].filter((id) => bScreenIds.has(id)).sort();
+  const aActionKeys = collectActionKeys(a);
+  const bActionKeys = collectActionKeys(b);
+  const actionsAdded = [...bActionKeys].filter((k) => !aActionKeys.has(k)).sort();
+  const actionsRemoved = [...aActionKeys].filter((k) => !bActionKeys.has(k)).sort();
+  const aFlowsByName = new Map(a.flows.map((f) => [f.name, f]));
+  const bFlowsByName = new Map(b.flows.map((f) => [f.name, f]));
+  const flowsAdded = [...bFlowsByName.keys()].filter((n) => !aFlowsByName.has(n)).sort();
+  const flowsRemoved = [...aFlowsByName.keys()].filter((n) => !bFlowsByName.has(n)).sort();
+  const flowsChanged = [];
+  for (const name of [...aFlowsByName.keys()].sort()) {
+    const aFlow = aFlowsByName.get(name);
+    const bFlow = bFlowsByName.get(name);
+    if (!bFlow) continue;
+    const reasons = [];
+    if (aFlow.start !== bFlow.start) {
+      reasons.push(`start: ${aFlow.start} \u2192 ${bFlow.start}`);
+    }
+    if (!stepArraysEqual(aFlow.steps, bFlow.steps)) {
+      reasons.push(`steps changed (${aFlow.steps.length} \u2192 ${bFlow.steps.length})`);
+    }
+    if (!arraysEqual(aFlow.actions ?? [], bFlow.actions ?? [])) {
+      reasons.push("actions changed");
+    }
+    if (reasons.length > 0) {
+      flowsChanged.push({ name, reason: reasons.join("; ") });
+    }
+  }
+  return {
+    screens: { added: screensAdded, removed: screensRemoved, common: screensCommon },
+    actions: { added: actionsAdded, removed: actionsRemoved },
+    flows: { added: flowsAdded, removed: flowsRemoved, changed: flowsChanged }
+  };
+}
+function collectActionKeys(doc) {
+  const out = /* @__PURE__ */ new Set();
+  for (const screen of doc.screens) {
+    for (const action of screen.actions ?? []) {
+      out.add(`${screen.id}.${action.id}`);
+    }
+  }
+  return out;
+}
+function arraysEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+function stepArraysEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (stepKey(a[i]) !== stepKey(b[i])) return false;
+  }
+  return true;
+}
+function stepKey(step) {
+  if (typeof step === "string") return step;
+  return step.target_screen ?? step.screen;
+}
+
+// src/cli/ux-paths/commands/diff.ts
+function registerDiff(program2) {
+  program2.command("diff <a> <b>").description("Diff screens/actions/flows between two flows.json files (a = baseline).").option("--json", "Emit machine-readable JSON instead of human-readable output.", false).action((aPath, bPath, opts) => {
+    const a = loadDoc(aPath);
+    const b = loadDoc(bPath);
+    const result = flowsDiff(a, b);
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(chalk7.bold(`Diff ${a.app_id}@${a.app_version} \u2192 ${b.app_id}@${b.app_version}`));
+    printSection("Screens added", result.screens.added, chalk7.green);
+    printSection("Screens removed", result.screens.removed, chalk7.red);
+    printSection("Actions added", result.actions.added, chalk7.green);
+    printSection("Actions removed", result.actions.removed, chalk7.red);
+    printSection("Flows added", result.flows.added, chalk7.green);
+    printSection("Flows removed", result.flows.removed, chalk7.red);
+    if (result.flows.changed.length > 0) {
+      console.log(chalk7.yellow("\nFlows changed:"));
+      for (const ch of result.flows.changed) {
+        console.log(`  - ${ch.name}: ${ch.reason}`);
+      }
+    }
+  });
+}
+function loadDoc(p) {
+  const path3 = resolve4(process.cwd(), p);
+  if (!existsSync4(path3)) {
+    console.error(chalk7.red("File not found:"), path3);
+    process.exit(1);
+  }
+  return JSON.parse(readFileSync3(path3, "utf8"));
+}
+function printSection(label, items, color) {
+  if (items.length === 0) return;
+  console.log(color(`
+${label} (${items.length}):`));
+  for (const item of items) {
+    console.log(`  - ${item}`);
+  }
+}
+
+// src/cli/ux-paths/commands/stamp.ts
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync5 } from "fs";
+import { resolve as resolve5 } from "path";
+import { execSync } from "child_process";
+import chalk8 from "chalk";
+
+// src/cli/ux-paths/lib/preserve-format.ts
+function replaceTopLevelStringField(raw, key, newValue) {
+  const re = new RegExp(`("${escapeRegExp(key)}"\\s*:\\s*")((?:[^"\\\\]|\\\\.)*)(")`);
+  if (!re.test(raw)) return raw;
+  return raw.replace(re, (_m, pre, _old, post) => {
+    return pre + escapeJsonStringValue(newValue) + post;
+  });
+}
+function stampPreserveFormat(raw, fields) {
+  let out = raw;
+  out = replaceTopLevelStringField(out, "app_version", fields.app_version);
+  out = replaceTopLevelStringField(out, "generated_at", fields.generated_at);
+  return out;
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function escapeJsonStringValue(s) {
+  const json = JSON.stringify(s);
+  return json.slice(1, -1);
+}
+
+// src/cli/ux-paths/commands/stamp.ts
+function registerStamp(program2) {
+  program2.command("stamp [path]").description("Refresh app_version to YYYY-MM-DD-<git-sha-short> and bump generated_at.").option(
+    "--no-preserve-format",
+    "Reformat the whole file (legacy). By default, stamp surgically updates only app_version/generated_at, preserving the existing formatting (minimal diff)."
+  ).action((maybePath, opts) => {
+    const path3 = resolve5(process.cwd(), maybePath || ".dfl-ux-paths/flows.json");
+    if (!existsSync5(path3)) {
+      console.error(chalk8.red("File not found:"), path3);
+      process.exit(1);
+    }
+    const raw = readFileSync4(path3, "utf8");
+    const doc = JSON.parse(raw);
+    const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+    let sha = "0000000";
+    try {
+      sha = execSync("git rev-parse --short=7 HEAD", { stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+      if (!sha) sha = "0000000";
+    } catch {
+    }
+    const newVersion = `${today}-${sha}`;
+    const newGeneratedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const preserve = opts.preserveFormat !== false;
+    let output;
+    if (preserve) {
+      output = stampPreserveFormat(raw, {
+        app_version: newVersion,
+        generated_at: newGeneratedAt
+      });
+    } else {
+      const updated = {
+        ...doc,
+        app_version: newVersion,
+        generated_at: newGeneratedAt
+      };
+      output = JSON.stringify(updated, null, 2) + "\n";
+    }
+    writeFileSync3(path3, output, "utf8");
+    console.log(chalk8.green("Stamped"), path3, preserve ? chalk8.gray("(minimal diff)") : "");
+    console.log(chalk8.gray(`  app_version: ${newVersion}`));
+    console.log(chalk8.gray(`  generated_at: ${newGeneratedAt}`));
+  });
+}
+
+// src/cli/ux-paths/index.ts
+function registerUxPaths(program2) {
+  const group = program2.command("ux-paths").description("Versioned, schema-validated per-app user-flow mapping (DFL UX Paths).");
+  registerInit(group);
+  registerValidate(group);
+  registerGenerateMermaid(group);
+  registerDiff(group);
+  registerStamp(group);
+}
+
+// src/cli/index.ts
+var program = new Command();
+program.name("dfl-components").description(
+  "DevFellowship components CLI \u2014 add shared components AND map app UX paths (folds the dfl-ux-paths CLI). Shipped as the `dfl-components` bin of @devfellowship/components."
+).version("1.0.0");
+program.command("init").description("Initialize your project with dfl-components configuration").option("-y, --yes", "Skip prompts and use defaults").option("-c, --cwd <path>", "Working directory", process.cwd()).action(init);
+program.command("add").description("Add a component to your project").argument("[components...]", "Components to add").option("-y, --yes", "Skip confirmation prompts").option("-o, --overwrite", "Overwrite existing files").option("-c, --cwd <path>", "Working directory", process.cwd()).option("-a, --all", "Add all available components").action(add);
+registerUxPaths(program);
+program.parse();

package/dist/index.cjs

@@ -167,7 +167,7 @@ __export(src_exports, {
   InputOTPGroup: () => InputOTPGroup,
   InputOTPSeparator: () => InputOTPSeparator,
   InputOTPSlot: () => InputOTPSlot,
-  Kbd: () => Kbd,
+  Kbd: () => Kbd2,
   Label: () => Label3,
   LoginPage: () => LoginPage,
   LoginScreen: () => LoginScreen,
@@ -492,13 +492,37 @@ var Spinner = () => /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
     ]
   }
 );
+var Kbd = ({ children }) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+  "kbd",
+  {
+    className: cn(
+      "ml-1 inline-flex items-center justify-center font-mono uppercase tracking-[0.04em]",
+      "text-[10.5px] text-[var(--s-ink-muted)]",
+      "min-w-[18px] h-[18px] px-1 rounded-[var(--p-radius-sm)]",
+      "border border-[var(--s-border-subtle)] bg-[var(--s-surface-raised)]"
+    ),
+    children
+  }
+);
 var Button = React3.forwardRef(
   ({ className, variant, size, asChild = false, loading = false, disabled, kbd, children, ...props }, ref) => {
-    const Comp = asChild ? import_react_slot.Slot : "button";
+    const classes = cn(buttonVariants({ variant, size, className }));
+    if (asChild) {
+      return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+        import_react_slot.Slot,
+        {
+          className: classes,
+          ref,
+          "data-loading": loading ? "" : void 0,
+          ...props,
+          children
+        }
+      );
+    }
     return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
-      Comp,
+      "button",
       {
-        className: cn(buttonVariants({ variant, size, className })),
+        className: classes,
         ref,
         disabled: disabled || loading,
         "data-loading": loading ? "" : void 0,
@@ -506,18 +530,7 @@ var Button = React3.forwardRef(
         children: [
           loading ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(Spinner, {}) : null,
           children,
-          kbd ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
-            "kbd",
-            {
-              className: cn(
-                "ml-1 inline-flex items-center justify-center font-mono uppercase tracking-[0.04em]",
-                "text-[10.5px] text-[var(--s-ink-muted)]",
-                "min-w-[18px] h-[18px] px-1 rounded-[var(--p-radius-sm)]",
-                "border border-[var(--s-border-subtle)] bg-[var(--s-surface-raised)]"
-              ),
-              children: kbd
-            }
-          ) : null
+          kbd ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(Kbd, { children: kbd }) : null
         ]
       }
     );
@@ -2270,8 +2283,8 @@ var kbdVariants = (0, import_class_variance_authority6.cva)(
     }
   }
 );
-var Kbd = React18.forwardRef(({ className, size, ...props }, ref) => /* @__PURE__ */ (0, import_jsx_runtime26.jsx)("kbd", { ref, className: cn(kbdVariants({ size }), className), ...props }));
-Kbd.displayName = "Kbd";
+var Kbd2 = React18.forwardRef(({ className, size, ...props }, ref) => /* @__PURE__ */ (0, import_jsx_runtime26.jsx)("kbd", { ref, className: cn(kbdVariants({ size }), className), ...props }));
+Kbd2.displayName = "Kbd";
 
 // src/components/menubar.tsx
 var MenubarPrimitive = __toESM(require("@radix-ui/react-menubar"), 1);

package/dist/index.js

@@ -166,13 +166,37 @@ var Spinner = () => /* @__PURE__ */ jsxs2(
     ]
   }
 );
+var Kbd = ({ children }) => /* @__PURE__ */ jsx3(
+  "kbd",
+  {
+    className: cn(
+      "ml-1 inline-flex items-center justify-center font-mono uppercase tracking-[0.04em]",
+      "text-[10.5px] text-[var(--s-ink-muted)]",
+      "min-w-[18px] h-[18px] px-1 rounded-[var(--p-radius-sm)]",
+      "border border-[var(--s-border-subtle)] bg-[var(--s-surface-raised)]"
+    ),
+    children
+  }
+);
 var Button = React3.forwardRef(
   ({ className, variant, size, asChild = false, loading = false, disabled, kbd, children, ...props }, ref) => {
-    const Comp = asChild ? Slot : "button";
+    const classes = cn(buttonVariants({ variant, size, className }));
+    if (asChild) {
+      return /* @__PURE__ */ jsx3(
+        Slot,
+        {
+          className: classes,
+          ref,
+          "data-loading": loading ? "" : void 0,
+          ...props,
+          children
+        }
+      );
+    }
     return /* @__PURE__ */ jsxs2(
-      Comp,
+      "button",
       {
-        className: cn(buttonVariants({ variant, size, className })),
+        className: classes,
         ref,
         disabled: disabled || loading,
         "data-loading": loading ? "" : void 0,
@@ -180,18 +204,7 @@ var Button = React3.forwardRef(
         children: [
           loading ? /* @__PURE__ */ jsx3(Spinner, {}) : null,
           children,
-          kbd ? /* @__PURE__ */ jsx3(
-            "kbd",
-            {
-              className: cn(
-                "ml-1 inline-flex items-center justify-center font-mono uppercase tracking-[0.04em]",
-                "text-[10.5px] text-[var(--s-ink-muted)]",
-                "min-w-[18px] h-[18px] px-1 rounded-[var(--p-radius-sm)]",
-                "border border-[var(--s-border-subtle)] bg-[var(--s-surface-raised)]"
-              ),
-              children: kbd
-            }
-          ) : null
+          kbd ? /* @__PURE__ */ jsx3(Kbd, { children: kbd }) : null
         ]
       }
     );
@@ -1944,8 +1957,8 @@ var kbdVariants = cva6(
     }
   }
 );
-var Kbd = React18.forwardRef(({ className, size, ...props }, ref) => /* @__PURE__ */ jsx26("kbd", { ref, className: cn(kbdVariants({ size }), className), ...props }));
-Kbd.displayName = "Kbd";
+var Kbd2 = React18.forwardRef(({ className, size, ...props }, ref) => /* @__PURE__ */ jsx26("kbd", { ref, className: cn(kbdVariants({ size }), className), ...props }));
+Kbd2.displayName = "Kbd";
 
 // src/components/menubar.tsx
 import * as MenubarPrimitive from "@radix-ui/react-menubar";
@@ -5242,7 +5255,7 @@ export {
   InputOTPGroup,
   InputOTPSeparator,
   InputOTPSlot,
-  Kbd,
+  Kbd2 as Kbd,
   Label3 as Label,
   LoginPage,
   LoginScreen,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devfellowship/components",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "DFL Design System — UI components, hooks, utils and providers",
   "type": "module",
   "sideEffects": [
@@ -35,11 +35,16 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "dfl-components": "./dist/cli.js"
+  },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && tsup --config tsup.cli.config.ts",
+    "build:lib": "tsup",
+    "build:cli": "tsup --config tsup.cli.config.ts",
     "build:watch": "tsup --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
@@ -72,6 +77,9 @@
     "@tailwindcss/vite": "^4.2.2",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^20.0.0",
+    "@types/prompts": "^2.4.9",
     "@types/react": "^18.3.28",
     "@types/react-dom": "^18.3.7",
     "@vitejs/plugin-react": "^4.7.0",
@@ -114,20 +122,30 @@
     "@radix-ui/react-toggle-group": "^1.1.11",
     "@radix-ui/react-tooltip": "^1.1.4",
     "@testing-library/dom": "^10.4.1",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "chalk": "^5.3.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
+    "commander": "^12.0.0",
+    "cosmiconfig": "^9.0.0",
     "date-fns": "^3.6.0",
     "embla-carousel-react": "^8.6.0",
+    "fs-extra": "^11.2.0",
     "input-otp": "^1.4.2",
     "lucide-react": "^0.462.0",
     "next-themes": "^0.4.6",
+    "node-fetch": "^3.3.2",
+    "ora": "^8.0.1",
+    "prompts": "^2.4.2",
     "react-day-picker": "^8.10.1",
     "react-hook-form": "^7.72.1",
     "react-resizable-panels": "^2.1.9",
     "recharts": "^2.15.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^2.5.2",
-    "vaul": "^1.1.2"
+    "vaul": "^1.1.2",
+    "zod": "^3.23.8"
   }
 }