@madebywild/wvk 0.1.1 → 0.1.2

package/README.md

@@ -2,6 +2,19 @@
 
 Wireframe kit — accessible React components, 183 icons, and design tokens that map 1:1 to the wild Wireframe Kit Figma library.
 
+## Quick start (new project)
+
+Scaffold a fresh Next.js 16 / React 19 / Tailwind v4 app that ships with `@madebywild/wvk` already wired up — `ThemeProvider`, design tokens, the package stylesheet, and a small `Header` composition:
+
+```bash
+npx @madebywild/wvk create-next-app my-wvk-app
+cd my-wvk-app
+npm install
+npm run dev
+```
+
+Then open [http://localhost:3000](http://localhost:3000). The scaffold also writes an `AGENTS.md` so your agent harness (Claude Code, Cursor, Copilot, etc.) picks up the wvk authoring rules — pass `--no-agents` to skip that, or `--force` to scaffold into a non-empty directory.
+
 ## Install
 
 ```bash

package/bin/wvk.mjs

@@ -1,19 +1,24 @@
 #!/usr/bin/env node
 import { createHash } from "node:crypto";
 import {
+  cpSync,
   existsSync,
   mkdirSync,
   readFileSync,
+  readdirSync,
+  renameSync,
   statSync,
+  unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { dirname, relative, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const PKG_NAME = "@madebywild/wvk";
 const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(SCRIPT_DIR, "..");
 const SOURCE = resolve(PKG_ROOT, "AGENTS.md");
+const TEMPLATES_ROOT = resolve(PKG_ROOT, "templates");
 const PKG_JSON = JSON.parse(
   readFileSync(resolve(PKG_ROOT, "package.json"), "utf8"),
 );
@@ -25,6 +30,9 @@ const BEGIN_RE = new RegExp(
 );
 const END_MARK = `<!-- END ${PKG_NAME} AGENTS.md -->`;
 
+// Valid npm package name per https://github.com/npm/validate-npm-package-name
+const NAME_RE = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+
 function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -33,19 +41,28 @@ function usage() {
   return `wvk — ${PKG_NAME} CLI
 
 Usage:
+  wvk create-next-app <name> [--force] [--no-agents]
   wvk copy-harness [--force] [--append] [--out <path>]
   wvk --help
   wvk --version
 
 Commands:
-  copy-harness    Copy this package's AGENTS.md into your project so your
-                  agent harness picks up the wvk authoring rules.
+  create-next-app  Scaffold a new Next.js 16 / React 19 app preconfigured with
+                   ${PKG_NAME}, Tailwind v4, ThemeProvider, and a Header. Drops
+                   the package's AGENTS.md into the new project so a consumer's
+                   agent harness picks up the wvk authoring rules.
+  copy-harness     Copy this package's AGENTS.md into your project so your
+                   agent harness picks up the wvk authoring rules.
 
 Options:
-  --out <path>    Destination path (default: ./AGENTS.md). Parent dirs are created.
-  --force         Overwrite the destination if it exists. Mutually exclusive with --append.
-  --append        Merge the rules into the destination as a delimited, idempotent block.
-                  Re-running is safe: the block is replaced in place, never duplicated.
+  --out <path>     (copy-harness) Destination path (default: ./AGENTS.md). Parent dirs are created.
+  --force          Overwrite an existing destination. For create-next-app, allow
+                   scaffolding into an existing non-empty directory.
+                   Mutually exclusive with --append on copy-harness.
+  --append         (copy-harness) Merge the rules into the destination as a
+                   delimited, idempotent block. Re-running is safe: the block is
+                   replaced in place, never duplicated.
+  --no-agents      (create-next-app) Skip writing AGENTS.md into the new project.
 `;
 }
 
@@ -55,11 +72,12 @@ function fail(msg, code = 1) {
 }
 
 function parseArgs(argv) {
-  const args = { _: [], force: false, append: false, out: null };
+  const args = { _: [], force: false, append: false, out: null, noAgents: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--force") args.force = true;
     else if (a === "--append") args.append = true;
+    else if (a === "--no-agents") args.noAgents = true;
     else if (a === "--out") {
       const v = argv[++i];
       if (!v) fail("--out requires a path");
@@ -172,6 +190,110 @@ function report(destRel, mode) {
   }
 }
 
+function isDirEmpty(dir) {
+  try {
+    return readdirSync(dir).length === 0;
+  } catch {
+    return true;
+  }
+}
+
+function createNextApp(args) {
+  if (args.append) {
+    fail("--append is not supported for create-next-app");
+  }
+  const name = args._[1];
+  if (!name) {
+    fail("create-next-app requires a project name. Example: wvk create-next-app my-app");
+  }
+  if (!NAME_RE.test(name) && name !== ".") {
+    fail(
+      `invalid project name: ${name}\n` +
+        `wvk: must be a valid npm package name (lowercase, no spaces, may start with @scope/).`,
+    );
+  }
+  const templateRoot = resolve(TEMPLATES_ROOT, "next-app");
+  if (!existsSync(templateRoot)) {
+    fail(`scaffolding template missing in package at ${templateRoot}`);
+  }
+
+  const targetDir =
+    name === "." ? process.cwd() : resolve(process.cwd(), name);
+  const targetRel = relative(process.cwd(), targetDir) || ".";
+  const projectName = name === "." ? basename(targetDir) : name;
+  if (!NAME_RE.test(projectName)) {
+    fail(
+      `derived project name "${projectName}" is not a valid npm package name. ` +
+        `Pass an explicit name: wvk create-next-app <name>`,
+    );
+  }
+
+  if (existsSync(targetDir)) {
+    if (!statSync(targetDir).isDirectory()) {
+      fail(`${targetRel} exists and is not a directory`);
+    }
+    if (!isDirEmpty(targetDir) && !args.force) {
+      fail(
+        `${targetRel} is not empty. Re-run with --force to scaffold into it anyway ` +
+          `(existing files with the same name will be overwritten).`,
+      );
+    }
+  } else {
+    mkdirSync(targetDir, { recursive: true });
+  }
+
+  // Copy every file from the template tree. cpSync with recursive copies
+  // directories without descending into anything that doesn't exist.
+  cpSync(templateRoot, targetDir, { recursive: true, force: true });
+
+  // npm strips a literal `.gitignore` from packed tarballs (it's renamed to
+  // `.npmignore`). The template ships it as `gitignore`; rename on copy. If
+  // the caller already had a `.gitignore` (only possible with --force), keep
+  // theirs and drop ours so we don't leave an orphan `gitignore` lying around.
+  const giSrc = join(targetDir, "gitignore");
+  const giDst = join(targetDir, ".gitignore");
+  if (existsSync(giSrc)) {
+    if (existsSync(giDst)) {
+      unlinkSync(giSrc);
+    } else {
+      renameSync(giSrc, giDst);
+    }
+  }
+
+  // Set the `name` field in the new app's package.json to the requested name.
+  const targetPkgPath = join(targetDir, "package.json");
+  if (existsSync(targetPkgPath)) {
+    const pkg = JSON.parse(readFileSync(targetPkgPath, "utf8"));
+    pkg.name = projectName;
+    writeFileSync(targetPkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+  }
+
+  // Drop the package's AGENTS.md into the project so the consumer's agent
+  // harness picks up the wvk authoring rules. Sourced from PKG_ROOT (same
+  // file `wvk copy-harness` writes), not from the template, so the two
+  // never drift. Opt out with --no-agents.
+  if (!args.noAgents) {
+    if (!existsSync(SOURCE)) {
+      fail(`source AGENTS.md missing in package at ${SOURCE}`);
+    }
+    const agentsBody = readFileSync(SOURCE, "utf8");
+    writeFileSync(join(targetDir, "AGENTS.md"), agentsBody);
+  }
+
+  process.stdout.write(`wvk: scaffolded ${PKG_NAME} Next.js app in ${targetRel}\n`);
+  if (!args.noAgents) {
+    process.stdout.write(
+      `wvk: wrote AGENTS.md so your agent harness picks up the wvk authoring rules\n`,
+    );
+  }
+  process.stdout.write(`wvk: next steps:\n`);
+  if (targetRel !== ".") {
+    process.stdout.write(`  cd ${targetRel}\n`);
+  }
+  process.stdout.write(`  npm install   # or pnpm install\n`);
+  process.stdout.write(`  npm run dev   # then open http://localhost:3000\n`);
+}
+
 function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.help) {
@@ -191,6 +313,10 @@ function main() {
     copyHarness(args);
     return;
   }
+  if (cmd === "create-next-app") {
+    createNextApp(args);
+    return;
+  }
   process.stderr.write(`wvk: unknown command: ${cmd}\n\n${usage()}`);
   process.exit(1);
 }

package/dist/index.cjs

@@ -7311,6 +7311,9 @@ var TextInput = React24.forwardRef(
         "data-wvk-input": "shell",
         style: { cursor: disabled ? "not-allowed" : "var(--wvk-cursor-text)" },
         className: cn(textInputShellVariants({ inputStyle, size }), className),
+        onClick: () => {
+          if (!disabled) innerRef.current?.focus();
+        },
         children: [
           leadingIcon ? /* @__PURE__ */ (0, import_jsx_runtime208.jsx)(
             "span",