@devfellowship/components 2.0.0 → 3.0.1

package/dist/cli.js

@@ -3,321 +3,10 @@
 // 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";
+import chalk 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();
@@ -326,7 +15,7 @@ function registerInit(program2) {
     const appId = opts.appId || basename(cwd);
     if (existsSync(flowsPath) && !opts.force) {
       console.error(
-        chalk4.yellow(`${flowsPath} already exists. Use --force to overwrite.`)
+        chalk.yellow(`${flowsPath} already exists. Use --force to overwrite.`)
       );
       process.exit(1);
     }
@@ -342,9 +31,9 @@ function registerInit(program2) {
       flows: []
     };
     writeFileSync(flowsPath, JSON.stringify(stub, null, 2) + "\n", "utf8");
-    console.log(chalk4.green("Created"), flowsPath);
+    console.log(chalk.green("Created"), flowsPath);
     console.log(
-      chalk4.gray(
+      chalk.gray(
         "Next steps: populate screens/flows, then run `dfl-components ux-paths validate` and `dfl-components ux-paths generate-mermaid`."
       )
     );
@@ -356,43 +45,441 @@ 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";
+import chalk2 from "chalk";
+
+// src/cli/ux-paths/lib/v1.schema.json
+var v1_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://raw.githubusercontent.com/devfellowship/dfl-ux-paths/main/schema/v1.json",
+  title: "DFL UX Paths v1",
+  description: "Versioned per-app user-flow JSON schema for migration-gap analysis and dead-code detection. Accepts schema_version 1.0.0, 1.1.0, 1.2.0 and 1.3.0 (all additive \u2014 v1.1 adds optional navigation/prereq/test_metadata fields; v1.2 adds optional source_ref (screen\u2192repo file) and screenshots[] (per platform\xD7orientation), and documents `route` as the canonical shared route nomenclature for 1:1 cross-app mapping; v1.3 adds optional source (build|spec), phases[], and phase/description on screen and flow, so the format can also describe a product that has not been built yet. Backward compatible \u2014 v1.0/v1.1/v1.2 files still validate).",
+  $comment: "schema v1.2 \u2014 additive over v1.1. New optional screen fields: source_ref { component_file, file_path_chain? } links a screen to the repo file(s) that render it (Figma-Code-Connect style); screenshots[] { platform, orientation, viewport?, url, captured_at? } captures rendered images per platform\xD7orientation for vision-first comparison. `screen.id` is the STICKY 1:1 JOIN KEY across apps \u2014 comparators pair screens by shared id. `route` is the canonical shared route nomenclature (e.g. studio/project/:id/editor) letting two apps map 1:1 by the same name even when their real URLs differ. Draft 2020-12. The file `$id` is intentionally unchanged across additive bumps so consumers pinned to the canonical URL keep working. || schema v1.3 \u2014 additive over v1.2, and the first bump aimed at files authored BEFORE the code exists. `source: \"spec\"` says so explicitly: routes are proposed nomenclature, app_version carries the zero-sha `init` emits, and the absence of source_ref/screenshots/base_url is correct rather than incomplete. `phases[]` declares the app's delivery-phase vocabulary once; `screen.phase` / `flow.phase` reference a phase id. That pair is what lets a viewer render committed scope differently from work the requirement explicitly parks (`phases[].optional: true`) instead of showing one undifferentiated blob \u2014 the distinction a client reads as 'what am I actually getting'. `screen.description` / `flow.description` carry the prose a spec needs and a generated-from-code file usually does not.",
+  type: "object",
+  required: ["schema_version", "app_id", "app_version", "screens", "flows"],
+  additionalProperties: false,
+  properties: {
+    schema_version: {
+      type: "string",
+      enum: ["1.0.0", "1.1.0", "1.2.0", "1.3.0"],
+      description: "Version of the dfl-ux-paths schema this file conforms to. v1.1.0 adds optional navigation_path, prerequisites, test_metadata, and richer flow step objects. v1.2.0 adds optional screen.source_ref (screen\u2192repo file link) and screen.screenshots[] (per platform\xD7orientation), and documents `route` as the canonical shared route nomenclature for 1:1 cross-app mapping. v1.3.0 adds optional spec-first authoring fields: top-level `source` (build|spec) and `phases[]`, plus optional `phase`/`description` on screens and flows."
+    },
+    app_id: {
+      type: "string",
+      minLength: 1,
+      description: "Stable identifier for the app (e.g. 'dfl-learn-mobile')."
+    },
+    app_version: {
+      type: "string",
+      pattern: "^\\d{4}-\\d{2}-\\d{2}-[0-9a-f]{4,40}$",
+      description: 'App build identifier in the form YYYY-MM-DD-<git-sha-short>. A file authored before any build exists uses the zero-sha form `YYYY-MM-DD-0000000` that `dfl-ux-paths init` already emits, and should also set `source: "spec"`.'
+    },
+    source: {
+      type: "string",
+      enum: ["build", "spec"],
+      description: "v1.3 \u2014 provenance of this file. 'build' (the assumed default when omitted) means it was derived from a shipped build, so `route` values are real and source_ref/screenshots are meaningful. 'spec' means it was authored from a requirement document before the code exists: routes are PROPOSED nomenclature, app_version carries a zero-sha, and the absence of source_ref/screenshots/test_metadata.base_url is expected rather than a gap. Optional, additive."
+    },
+    phases: {
+      type: "array",
+      items: { $ref: "#/$defs/phase" },
+      description: "v1.3 \u2014 the app's delivery-phase vocabulary, declared once and referenced by `screen.phase` / `flow.phase`. Phase ids are free-form on purpose (every product names its phases differently). Mark a phase `optional: true` when the requirement explicitly parks it outside committed scope. Optional, additive."
+    },
+    generated_at: {
+      type: "string",
+      format: "date-time",
+      description: "ISO-8601 timestamp when this snapshot was generated."
+    },
+    tech_stack: {
+      type: "array",
+      items: { type: "string" },
+      description: "List of tech-stack tags (e.g. 'react-native', 'expo', 'powersync')."
+    },
+    test_metadata: {
+      $ref: "#/$defs/testMetadata",
+      description: "v1.1 \u2014 app-level metadata used by e2e-user-persona / Playwright skills to bootstrap a session (auth strategy, default viewport, base URL)."
+    },
+    screens: {
+      type: "array",
+      items: { $ref: "#/$defs/screen" }
+    },
+    flows: {
+      type: "array",
+      items: { $ref: "#/$defs/flow" }
+    },
+    dead_code: {
+      type: "array",
+      items: { $ref: "#/$defs/deadCodeEntry" }
+    }
+  },
+  $defs: {
+    phase: {
+      type: "object",
+      required: ["id"],
+      additionalProperties: false,
+      description: "v1.3 \u2014 one entry in the app's delivery-phase vocabulary.",
+      properties: {
+        id: {
+          type: "string",
+          minLength: 1,
+          description: "Stable phase id referenced by `screen.phase` / `flow.phase` (e.g. 'alpha', 'beta', 'mvp', 'optional')."
+        },
+        label: {
+          type: "string",
+          description: "Human-readable phase name."
+        },
+        description: {
+          type: "string",
+          description: "What this phase covers \u2014 ideally quoting the source requirement rather than paraphrasing it."
+        },
+        optional: {
+          type: "boolean",
+          description: "True when the requirement explicitly parks this phase outside committed scope (e.g. 'eventual landing, not in MVP'). Viewers and generated Mermaid MUST render it as visually distinct from in-scope work, so a reader never mistakes parked work for a commitment."
+        }
+      }
+    },
+    screen: {
+      type: "object",
+      required: ["id", "name"],
+      additionalProperties: false,
+      properties: {
+        id: {
+          type: "string",
+          minLength: 1,
+          description: "Stable screen identifier (snake_case recommended). REQUIRED. This is the STICKY 1:1 JOIN KEY across apps: cross-app comparators (web \u2194 mobile, old build \u2194 new build) pair screens by shared `id`. Treat it as a contract \u2014 keep ids stable across versions and identical across apps you intend to map 1:1, or diffs/parity comparisons break."
+        },
+        name: {
+          type: "string",
+          minLength: 1,
+          description: "Human-readable screen name."
+        },
+        route: {
+          type: "string",
+          description: "v1.2 \u2014 canonical SHARED route nomenclature for 1:1 cross-app mapping (e.g. 'studio/project/:id/editor'). Lets two apps (web \u2194 mobile) map by the same route name even when their real URLs/deep-links differ. Also doubles as the screen's route/path/deep-link when the app uses a single URL scheme. Use ':param' for dynamic segments. Optional, additive."
+        },
+        description: {
+          type: "string",
+          description: "v1.3 \u2014 free-form prose describing this screen. For a spec-first file the description IS the requirement, so keep it faithful to the source document. Optional, additive."
+        },
+        phase: {
+          type: "string",
+          minLength: 1,
+          description: "v1.3 \u2014 id of the phase (from top-level `phases[]`) this screen belongs to. Optional, additive."
+        },
+        source_ref: {
+          $ref: "#/$defs/sourceRef",
+          description: "v1.2 \u2014 link from this screen to the repo file(s) that render it (route/page/modal component). Figma-Code-Connect style. Optional, additive \u2014 populated by the route\u2192file resolver (bin/resolve-routes.mjs) or by hand."
+        },
+        screenshots: {
+          type: "array",
+          items: { $ref: "#/$defs/screenshot" },
+          description: "v1.2 \u2014 rendered screenshots of this screen, one entry per platform\xD7orientation(\xD7viewport). URLs are committed (e.g. S3 via supabase-upload) so humans AND agents view the same image for vision-first comparison. Optional, additive."
+        },
+        components: {
+          type: "array",
+          items: { type: "string" },
+          description: "Component identifiers rendered on this screen."
+        },
+        api_calls: {
+          type: "array",
+          items: { type: "string" },
+          description: "API endpoints or RPC calls invoked from this screen."
+        },
+        actions: {
+          type: "array",
+          items: { $ref: "#/$defs/action" }
+        },
+        navigation_path: {
+          type: "array",
+          items: { $ref: "#/$defs/navigationStep" },
+          description: "v1.1 \u2014 ordered list of UI actions to navigate TO this screen from the app entrypoint. Used by e2e-user-persona to auto-generate persona scripts instead of LLM-driven discovery. When multiple navigationStep entries are present, the runner tries them in order and the first matching selector wins (useful for resilience across renames)."
+        },
+        prerequisites: {
+          $ref: "#/$defs/prerequisites",
+          description: "v1.1 \u2014 preconditions that must hold for this screen to be reachable / functional."
+        }
+      }
+    },
+    sourceRef: {
+      type: "object",
+      required: ["component_file"],
+      additionalProperties: false,
+      description: "v1.2 \u2014 points a screen at the repo file(s) that render it.",
+      properties: {
+        component_file: {
+          type: "string",
+          minLength: 1,
+          description: "Repo-relative path to the route/page/modal component that renders this screen (e.g. 'app/studio/[id]/editor.tsx' for Expo Router, 'app/studio/[id]/editor/page.tsx' for Next app-router). This is what the route\u2192file resolver emits."
+        },
+        file_path_chain: {
+          type: "array",
+          items: { type: "string" },
+          minItems: 1,
+          description: "Optional \u2014 ordered repo-relative paths from the app entry (e.g. 'App.tsx' / 'app/_layout.tsx') down to the component, giving the 'tree' from app root to this screen's renderer."
+        }
+      }
+    },
+    screenshot: {
+      type: "object",
+      required: ["platform", "orientation", "url"],
+      additionalProperties: false,
+      description: "v1.2 \u2014 one rendered screenshot of a screen, keyed by platform\xD7orientation(\xD7viewport).",
+      properties: {
+        platform: {
+          type: "string",
+          enum: ["web", "mobile"],
+          description: "Rendering platform the screenshot was captured on."
+        },
+        orientation: {
+          type: "string",
+          enum: ["portrait", "landscape"],
+          description: "Device/viewport orientation."
+        },
+        viewport: {
+          type: "string",
+          description: "Optional viewport dimensions string, e.g. '375x812' or '1440x900'."
+        },
+        url: {
+          type: "string",
+          format: "uri",
+          description: "Public URL of the committed screenshot (e.g. S3 via supabase-upload)."
+        },
+        captured_at: {
+          type: "string",
+          format: "date-time",
+          description: "Optional ISO-8601 timestamp when the screenshot was captured."
+        }
+      }
+    },
+    action: {
+      type: "object",
+      required: ["id", "label"],
+      additionalProperties: false,
+      properties: {
+        id: {
+          type: "string",
+          minLength: 1
+        },
+        label: {
+          type: "string",
+          minLength: 1
+        },
+        next_screen: {
+          type: "string",
+          description: "Screen id the user lands on after this action."
+        },
+        side_effect: {
+          type: "string",
+          description: "Free-form description of side effect (mutation, analytics, etc.)."
+        }
+      }
+    },
+    flow: {
+      type: "object",
+      required: ["name", "start", "steps"],
+      additionalProperties: false,
+      properties: {
+        name: {
+          type: "string",
+          minLength: 1
+        },
+        description: {
+          type: "string",
+          description: "v1.3 \u2014 free-form prose describing what this flow accomplishes and why it matters. Optional, additive."
+        },
+        phase: {
+          type: "string",
+          minLength: 1,
+          description: "v1.3 \u2014 id of the phase (from top-level `phases[]`) this flow belongs to. Optional, additive."
+        },
+        start: {
+          type: "string",
+          minLength: 1,
+          description: "Screen id where the flow starts."
+        },
+        steps: {
+          type: "array",
+          items: {
+            oneOf: [
+              {
+                type: "string",
+                description: "v1.0 \u2014 screen id traversed in this flow."
+              },
+              {
+                $ref: "#/$defs/flowStepObject"
+              }
+            ]
+          },
+          description: "Ordered list of flow steps. v1.0 accepts plain screen ids (strings); v1.1 additionally accepts step objects with action/selector/target_screen for executable scripts. Mixed arrays are allowed during migration."
+        },
+        actions: {
+          type: "array",
+          items: { type: "string" },
+          description: "Ordered list of action ids exercised during this flow."
+        },
+        tested_by: {
+          type: "array",
+          items: { type: "string" },
+          description: "References to tests (file paths, test names) that cover this flow."
+        }
+      }
+    },
+    flowStepObject: {
+      type: "object",
+      required: ["screen"],
+      additionalProperties: false,
+      properties: {
+        screen: {
+          type: "string",
+          minLength: 1,
+          description: "Screen id where this step is executed."
+        },
+        action: {
+          type: "string",
+          description: "Action verb (tap, type, scroll, swipe, navigate, wait, assert, etc.)."
+        },
+        selector: {
+          type: "string",
+          description: "Playwright-compatible selector (e.g. 'text=Next', 'role=button[name=Save]', 'css=[data-testid=foo]')."
+        },
+        value: {
+          type: "string",
+          description: "Optional value to type / select / assert."
+        },
+        target_screen: {
+          type: "string",
+          description: "Screen id the user lands on after this step."
+        },
+        wait_for_target: {
+          type: "string",
+          description: "Selector / condition to wait for to confirm the target screen rendered."
+        },
+        note: {
+          type: "string",
+          description: "Free-form annotation for humans / debugging."
+        }
+      }
+    },
+    navigationStep: {
+      type: "object",
+      required: ["selector", "action"],
+      additionalProperties: false,
+      properties: {
+        selector: {
+          type: "string",
+          minLength: 1,
+          description: "Playwright-compatible selector (e.g. 'text=Studio', 'role=tab[name=Studio]', 'css=[data-testid=studio-tab]')."
+        },
+        action: {
+          type: "string",
+          enum: ["tap", "click", "type", "scroll", "swipe", "navigate", "wait", "assert"],
+          description: "Interaction primitive to execute."
+        },
+        value: {
+          type: "string",
+          description: "Optional value for type/select/assert."
+        },
+        wait_for: {
+          type: "string",
+          description: "Selector / condition to wait for after performing the action to confirm success."
+        },
+        note: {
+          type: "string",
+          description: "Free-form annotation."
+        }
+      }
+    },
+    prerequisites: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        auth_required: {
+          type: "boolean",
+          description: "True if a logged-in user session is required to reach this screen."
+        },
+        auth_role: {
+          type: "string",
+          description: "Optional \u2014 specific role required (e.g. 'admin', 'instructor'). Omit for any authenticated user."
+        },
+        data_required: {
+          type: "array",
+          items: { type: "string" },
+          description: "Free-form descriptions of DB/state preconditions (e.g. 'lesson_studio.projects has >= 0 rows')."
+        },
+        preconditions_in_app: {
+          type: "array",
+          items: { type: "string" },
+          description: "Free-form descriptions of in-app preconditions (feature flag enabled, onboarding complete, etc.)."
+        },
+        feature_flags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Feature flag identifiers that must be enabled."
+        }
+      }
+    },
+    testMetadata: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        auth_strategy: {
+          type: "string",
+          description: "Brief description of how to authenticate (e.g. 'supabase-anon + CLAUDE_SMOKE creds', 'magic-link', 'oauth google')."
+        },
+        default_viewport: {
+          type: "string",
+          enum: ["mobile", "tablet", "desktop", "responsive"],
+          description: "Hint for test runners \u2014 preferred viewport for this app."
+        },
+        base_url: {
+          type: "string",
+          format: "uri",
+          description: "Production / smoke-target base URL (e.g. 'https://mobile.devfellowship.com/')."
+        },
+        test_user_secret_path: {
+          type: "string",
+          description: "Infisical path to credentials suitable for smoke tests (e.g. '/shared/CLAUDE_SMOKE_USERNAME')."
+        },
+        notes: {
+          type: "string",
+          description: "Free-form notes for test authors / persona-script generators."
+        }
+      }
+    },
+    deadCodeEntry: {
+      type: "object",
+      required: ["component", "reason"],
+      additionalProperties: false,
+      properties: {
+        component: {
+          type: "string",
+          minLength: 1
+        },
+        reason: {
+          type: "string",
+          minLength: 1
+        }
+      }
+    }
+  }
+};
 
 // 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;
+  return v1_schema_default;
 }
 
 // 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);
+    const path = resolve2(process.cwd(), maybePath || ".dfl-ux-paths/flows.json");
+    if (!existsSync2(path)) {
+      console.error(chalk2.red("File not found:"), path);
       process.exit(1);
     }
     let doc;
     try {
-      doc = JSON.parse(readFileSync(path3, "utf8"));
+      doc = JSON.parse(readFileSync(path, "utf8"));
     } catch (err) {
-      console.error(chalk5.red("Invalid JSON:"), err.message);
+      console.error(chalk2.red("Invalid JSON:"), err.message);
       process.exit(1);
     }
     const ajv = new Ajv2020({ allErrors: true, strict: false });
@@ -401,19 +488,19 @@ function registerValidate(program2) {
     try {
       schema = await loadSchemaV1();
     } catch (err) {
-      console.error(chalk5.red("Schema error:"), err.message);
+      console.error(chalk2.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.");
+      console.log(chalk2.green("OK"), path, "conforms to schema v1.");
       process.exit(0);
     }
-    console.error(chalk5.red("FAIL"), path3);
+    console.error(chalk2.red("FAIL"), path);
     for (const err of validate.errors ?? []) {
       console.error(
-        chalk5.yellow("  -"),
+        chalk2.yellow("  -"),
         err.instancePath || "<root>",
         err.message,
         err.params ? JSON.stringify(err.params) : ""
@@ -426,7 +513,7 @@ function registerValidate(program2) {
 // 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";
+import chalk3 from "chalk";
 
 // src/cli/ux-paths/lib/json-to-mermaid.ts
 function jsonToMermaid(doc) {
@@ -516,23 +603,23 @@ function escapeLabel(raw) {
 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);
+    const path = resolve3(process.cwd(), maybePath || ".dfl-ux-paths/flows.json");
+    if (!existsSync3(path)) {
+      console.error(chalk3.red("File not found:"), path);
       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 doc = JSON.parse(readFileSync2(path, "utf8"));
+    const out = opts.out ? resolve3(process.cwd(), opts.out) : resolve3(dirname(path), "flows.mmd");
     const body = HEADER + jsonToMermaid(doc);
     writeFileSync2(out, body, "utf8");
-    console.log(chalk6.green("Wrote"), out);
+    console.log(chalk3.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";
+import chalk4 from "chalk";
 
 // src/cli/ux-paths/lib/flows-diff.ts
 function flowsDiff(a, b) {
@@ -612,15 +699,15 @@ function registerDiff(program2) {
       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);
+    console.log(chalk4.bold(`Diff ${a.app_id}@${a.app_version} \u2192 ${b.app_id}@${b.app_version}`));
+    printSection("Screens added", result.screens.added, chalk4.green);
+    printSection("Screens removed", result.screens.removed, chalk4.red);
+    printSection("Actions added", result.actions.added, chalk4.green);
+    printSection("Actions removed", result.actions.removed, chalk4.red);
+    printSection("Flows added", result.flows.added, chalk4.green);
+    printSection("Flows removed", result.flows.removed, chalk4.red);
     if (result.flows.changed.length > 0) {
-      console.log(chalk7.yellow("\nFlows changed:"));
+      console.log(chalk4.yellow("\nFlows changed:"));
       for (const ch of result.flows.changed) {
         console.log(`  - ${ch.name}: ${ch.reason}`);
       }
@@ -628,12 +715,12 @@ function registerDiff(program2) {
   });
 }
 function loadDoc(p) {
-  const path3 = resolve4(process.cwd(), p);
-  if (!existsSync4(path3)) {
-    console.error(chalk7.red("File not found:"), path3);
+  const path = resolve4(process.cwd(), p);
+  if (!existsSync4(path)) {
+    console.error(chalk4.red("File not found:"), path);
     process.exit(1);
   }
-  return JSON.parse(readFileSync3(path3, "utf8"));
+  return JSON.parse(readFileSync3(path, "utf8"));
 }
 function printSection(label, items, color) {
   if (items.length === 0) return;
@@ -648,7 +735,7 @@ ${label} (${items.length}):`));
 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";
+import chalk5 from "chalk";
 
 // src/cli/ux-paths/lib/preserve-format.ts
 function replaceTopLevelStringField(raw, key, newValue) {
@@ -678,12 +765,12 @@ function registerStamp(program2) {
     "--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);
+    const path = resolve5(process.cwd(), maybePath || ".dfl-ux-paths/flows.json");
+    if (!existsSync5(path)) {
+      console.error(chalk5.red("File not found:"), path);
       process.exit(1);
     }
-    const raw = readFileSync4(path3, "utf8");
+    const raw = readFileSync4(path, "utf8");
     const doc = JSON.parse(raw);
     const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
     let sha = "0000000";
@@ -709,10 +796,10 @@ function registerStamp(program2) {
       };
       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}`));
+    writeFileSync3(path, output, "utf8");
+    console.log(chalk5.green("Stamped"), path, preserve ? chalk5.gray("(minimal diff)") : "");
+    console.log(chalk5.gray(`  app_version: ${newVersion}`));
+    console.log(chalk5.gray(`  generated_at: ${newGeneratedAt}`));
   });
 }
 
@@ -729,7 +816,7 @@ function registerUxPaths(program2) {
 // src/cli/check-style-imports/index.ts
 import { resolve as resolve6 } from "path";
 import { existsSync as existsSync6 } from "fs";
-import chalk9 from "chalk";
+import chalk6 from "chalk";
 
 // src/cli/check-style-imports/detect.ts
 import { readdirSync, readFileSync as readFileSync5 } from "fs";
@@ -821,7 +908,7 @@ function registerCheckStyleImports(program2) {
   ).option("--json", "Emit the raw detection result as JSON instead of a human report.").action((maybeDir, opts) => {
     const root = resolve6(process.cwd(), maybeDir || ".");
     if (!existsSync6(root)) {
-      console.error(chalk9.red("Directory not found:"), root);
+      console.error(chalk6.red("Directory not found:"), root);
       process.exit(2);
     }
     const result = detectInDir(root);
@@ -832,33 +919,33 @@ function registerCheckStyleImports(program2) {
     if (!result.conflict) {
       if (result.hits.length === 0) {
         console.log(
-          chalk9.green("OK"),
+          chalk6.green("OK"),
           "no @devfellowship/components/{styles,shadcn} imports found."
         );
       } else {
         const which = result.styles.length > 0 ? "styles" : "shadcn";
         console.log(
-          chalk9.green("OK"),
+          chalk6.green("OK"),
           `app imports only @devfellowship/components/${which} (${result.hits.length} reference${result.hits.length === 1 ? "" : "s"}).`
         );
       }
       process.exit(0);
     }
     console.error(
-      chalk9.red("CONFLICT"),
+      chalk6.red("CONFLICT"),
       "this app imports BOTH @devfellowship/components/styles AND /shadcn."
     );
     console.error(
-      chalk9.yellow(
+      chalk6.yellow(
         "\nThese exports define the SAME CSS vars (--background, --primary, \u2026) in INCOMPATIBLE formats:\n  - /styles  ships them as HEX        (#0A0908)\n  - /shadcn  ships them as HSL CHANNELS (30 11% 4%)\nImporting both clobbers --background \u2014 e.g. hsl(#0A0908) is invalid CSS \u2192 the\ndeclaration drops \u2192 surfaces render TRANSPARENT (the transparent-dialog bug).\n"
       )
     );
-    console.error(chalk9.bold("  /styles imports:"));
+    console.error(chalk6.bold("  /styles imports:"));
     for (const h of result.styles) console.error(`    ${h.file}:${h.line}  ${h.text}`);
-    console.error(chalk9.bold("  /shadcn imports:"));
+    console.error(chalk6.bold("  /shadcn imports:"));
     for (const h of result.shadcn) console.error(`    ${h.file}:${h.line}  ${h.text}`);
     console.error(
-      chalk9.cyan(
+      chalk6.cyan(
         `
 FIX: keep exactly ONE. A DS-native (hex) app imports /styles only; a
 shadcn-slate (HSL-channel) app imports /shadcn only. NEVER both.
@@ -872,10 +959,8 @@ See: ${DOC_URL}`
 // 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);
+  'DevFellowship components CLI \u2014 map app UX paths (folds the dfl-ux-paths CLI). Shipped as the `dfl-components` bin of @devfellowship/components. The component set is consumed as a library import (`import { Button } from "@devfellowship/components"`), not scaffolded.'
+).version("3.0.0");
 registerUxPaths(program);
 registerCheckStyleImports(program);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devfellowship/components",
-  "version": "2.0.0",
+  "version": "3.0.1",
   "description": "DFL Design System — UI components, hooks, utils and providers",
   "type": "module",
   "sideEffects": [
@@ -43,6 +43,7 @@
   ],
   "scripts": {
     "build": "tsup && tsup --config tsup.cli.config.ts",
+    "release": "npm run build && changeset publish",
     "build:lib": "tsup",
     "build:cli": "tsup --config tsup.cli.config.ts",
     "build:watch": "tsup --watch",
@@ -68,6 +69,8 @@
     }
   },
   "devDependencies": {
+    "@changesets/changelog-github": "^0.7.0",
+    "@changesets/cli": "^2.31.0",
     "@storybook/addon-a11y": "^9.1.20",
     "@storybook/addon-themes": "^9.1.20",
     "@storybook/react": "^9.1.20",
@@ -76,9 +79,7 @@
     "@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",
@@ -128,16 +129,11 @@
     "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",