@marwes-ui/cli 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,7 +1,7 @@
 import { parseArgs } from 'util';
-import { resolve, join } from 'path';
+import { readFile, readdir, writeFile, access } from 'fs/promises';
+import { basename, resolve, join, extname } from 'path';
 import { spawn } from 'child_process';
-import { readFile, access, readdir, writeFile } from 'fs/promises';
 
 // src/index.ts
 var defaultCommandRunner = (command, options) => {
@@ -78,6 +78,62 @@ function formatShellCommand(command) {
   return [command.command, ...command.args].join(" ");
 }
 
+// src/provider-detection.ts
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function maskNonCode(source, maskStrings = true) {
+  return source.replace(
+    /<!--[\s\S]*?-->|\/\*[\s\S]*?\*\/|\/\/[^\r\n]*|"(?:\\[\s\S]|[^"\\])*"|'(?:\\[\s\S]|[^'\\])*'|`(?:\\[\s\S]|[^`\\])*`/g,
+    (match) => {
+      const isString = ['"', "'", "`"].includes(match[0] ?? "");
+      return !maskStrings && isString ? match : match.replace(/[^\r\n]/g, " ");
+    }
+  );
+}
+function runtimeBindings(source, code, packageName, exported) {
+  const names = [];
+  const namespaces = [];
+  const importSource = maskNonCode(source, false);
+  const pattern = /^import\s+([^;]*?)\s+from\s*(["'])([^"']+)\2/;
+  for (const position of code.matchAll(/\bimport\b/g)) {
+    const match = importSource.slice(position.index).match(pattern);
+    if (!match || match[3] !== packageName) continue;
+    const bindings = maskNonCode(match[1] ?? "").trim();
+    if (/^type\b/.test(bindings)) continue;
+    const namespace = bindings.match(/\*\s+as\s+([A-Za-z_$][\w$]*)/);
+    if (namespace?.[1]) namespaces.push(namespace[1]);
+    for (const binding of (bindings.match(/\{([^}]*)\}/)?.[1] ?? "").split(",")) {
+      const named = binding.trim().match(new RegExp(`^${escapeRegExp(exported)}(?:\\s+as\\s+([A-Za-z_$][\\w$]*))?$`));
+      if (named) names.push(named[1] ?? exported);
+    }
+    if (packageName === "react") {
+      const defaultBinding = bindings.match(/^([A-Za-z_$][\w$]*)\s*(?:,|$)/);
+      if (defaultBinding?.[1]) namespaces.push(defaultBinding[1]);
+    }
+  }
+  return [...names, ...namespaces.map((name) => `${name}.${exported}`)];
+}
+function hasConfiguredProvider(source, adapter) {
+  const code = maskNonCode(source);
+  const providers = runtimeBindings(source, code, `@marwes-ui/${adapter}`, "MarwesProvider");
+  const renderers = adapter === "react" ? runtimeBindings(source, code, "react", "createElement") : adapter === "vue" ? runtimeBindings(source, code, "vue", "h") : [];
+  return providers.some((provider) => {
+    const tags = [provider];
+    if (adapter === "vue" && !provider.includes(".")) {
+      tags.push(provider.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase());
+    }
+    if (tags.some((name) => new RegExp(`<\\s*${escapeRegExp(name)}(?:\\s|/?>)`).test(code))) {
+      return true;
+    }
+    return renderers.some(
+      (renderer) => new RegExp(
+        `(?:^|[^\\w$.])${escapeRegExp(renderer)}\\s*\\(\\s*${escapeRegExp(provider)}\\s*[,)]`
+      ).test(code)
+    );
+  });
+}
+
 // src/recipes.ts
 var adapters = ["react", "vue", "svelte"];
 var packageManagers = ["pnpm", "npm", "yarn", "bun"];
@@ -173,6 +229,8 @@ function supportedTemplatesLabel() {
 
 // src/doctor.ts
 var sourceExtensions = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".vue", ".svelte", ".css"]);
+var sourceDirectories = ["src", "app", "pages"];
+var knownRootFile = /^(?:main|app|layout|index|root)\.(?:ts|tsx|js|jsx|vue|svelte)$/i;
 function dependencyVersion(packageJson, packageName) {
   return packageJson.dependencies?.[packageName] ?? packageJson.devDependencies?.[packageName] ?? packageJson.peerDependencies?.[packageName] ?? packageJson.optionalDependencies?.[packageName];
 }
@@ -186,33 +244,51 @@ async function collectSourceFiles(directory) {
   for (const entry of entries) {
     const path = join(directory, entry.name);
     if (entry.isDirectory()) {
-      if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".git") {
+      if (["node_modules", "dist", ".git", ".next", ".svelte-kit"].includes(entry.name)) {
         continue;
       }
       files.push(...await collectSourceFiles(path));
       continue;
     }
-    const extension = entry.name.slice(entry.name.lastIndexOf("."));
-    if (sourceExtensions.has(extension)) {
+    if (sourceExtensions.has(extname(entry.name))) {
       files.push(path);
     }
   }
   return files;
 }
+async function readProjectSources(cwd) {
+  const paths = /* @__PURE__ */ new Set();
+  for (const directory of sourceDirectories) {
+    for (const file of await collectSourceFiles(join(cwd, directory))) {
+      paths.add(file);
+    }
+  }
+  const rootEntries = await readdir(cwd, { withFileTypes: true }).catch(() => []);
+  for (const entry of rootEntries) {
+    if (entry.isFile() && knownRootFile.test(entry.name)) {
+      paths.add(join(cwd, entry.name));
+    }
+  }
+  return Promise.all(
+    [...paths].map(async (path) => ({ path, source: await readFile(path, "utf8") }))
+  );
+}
 function detectInstalledAdapter(packageJson) {
   return adapters.find(
     (adapter) => dependencyVersion(packageJson, getAdapterRecipe(adapter).packageName)
   );
 }
-async function sourceContains(cwd, needle) {
-  const sourceFiles = await collectSourceFiles(join(cwd, "src"));
-  for (const file of sourceFiles) {
-    const source = await readFile(file, "utf8");
-    if (source.includes(needle)) {
-      return true;
-    }
-  }
-  return false;
+function escapeRegExp2(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function providerSetupFile(sources, adapter) {
+  return sources.find((file) => hasConfiguredProvider(file.source, adapter));
+}
+function sourceContains(sources, needle) {
+  return sources.some((file) => file.source.includes(needle));
+}
+function sourceMatches(sources, pattern) {
+  return sources.some((file) => pattern.test(file.source));
 }
 function formatItem(item) {
   const prefix = item.level === "pass" ? "[pass]" : item.level === "warn" ? "[warn]" : "[fail]";
@@ -225,7 +301,9 @@ async function runDoctor(options = {}) {
   const runner = options.runner ?? defaultCommandRunner;
   const packageJson = await readPackageJson(cwd);
   const adapter = options.adapter ?? detectInstalledAdapter(packageJson);
+  const sources = await readProjectSources(cwd);
   const items = [];
+  let commandFailureCode;
   if (!adapter) {
     items.push({
       level: "fail",
@@ -245,12 +323,16 @@ async function runDoctor(options = {}) {
         });
       }
     }
-    const hasProvider = await sourceContains(cwd, "MarwesProvider");
+    const providerFile = providerSetupFile(sources, adapter);
+    const providerMentioned = sourceContains(sources, "MarwesProvider");
     items.push(
-      hasProvider ? { level: "pass", message: "MarwesProvider is referenced in app source." } : {
-        level: "warn",
-        message: "MarwesProvider was not found in app source.",
-        fix: `Wrap the app root with MarwesProvider from ${recipe.packageName}.`
+      providerFile ? {
+        level: "pass",
+        message: `MarwesProvider is imported from ${recipe.packageName} and rendered in ${basename(providerFile.path)}.`
+      } : {
+        level: "fail",
+        message: providerMentioned ? `MarwesProvider is not both imported from ${recipe.packageName} and rendered in the same app entry file.` : "MarwesProvider was not rendered in app source.",
+        fix: `Wrap the app root with MarwesProvider from ${recipe.packageName}. Checked src/, app/, pages/, and known root entry files.`
       }
     );
   }
@@ -262,8 +344,16 @@ async function runDoctor(options = {}) {
         fix: "App projects should import from the public adapter package instead."
       });
     }
+    const escapedPackage = escapeRegExp2(internalPackage);
+    if (sourceMatches(sources, new RegExp(`(?:from\\s*|import\\s*)["']${escapedPackage}(?:["'/])`))) {
+      items.push({
+        level: "warn",
+        message: `Direct source import from ${internalPackage} found.`,
+        fix: "Import consumer APIs from the framework adapter package instead."
+      });
+    }
   }
-  if (await sourceContains(cwd, "@marwes-ui/presets/firstEdition/styles.css")) {
+  if (sourceMatches(sources, /["']@marwes-ui\/presets\/[^"']*styles\.css["']/)) {
     items.push({
       level: "warn",
       message: "Manual Marwes preset stylesheet import found.",
@@ -272,22 +362,34 @@ async function runDoctor(options = {}) {
   }
   if (options.runBuild) {
     const packageManager = options.packageManager ?? await detectPackageManager(cwd);
-    const scriptName = packageJson.scripts?.typecheck ? "typecheck" : packageJson.scripts?.build ? "build" : void 0;
-    if (!scriptName) {
-      items.push({ level: "warn", message: "No typecheck or build script found to run." });
-    } else {
+    if (!packageJson.scripts?.build) {
+      items.push({
+        level: "fail",
+        message: "No build script found to run.",
+        fix: "Add a production build script to package.json, then rerun marwes doctor --run-build."
+      });
+    }
+    const scripts = [
+      ...packageJson.scripts?.typecheck ? ["typecheck"] : [],
+      ...packageJson.scripts?.build ? ["build"] : []
+    ];
+    for (const scriptName of scripts) {
       const command = runScriptCommand(packageManager, scriptName);
       write(`Running ${formatShellCommand(command)}`);
       const exitCode2 = await runner(command, { cwd });
+      if (exitCode2 !== 0) {
+        commandFailureCode = exitCode2;
+      }
       items.push(
-        exitCode2 === 0 ? { level: "pass", message: `${scriptName} completed successfully.` } : { level: "fail", message: `${scriptName} failed.` }
+        exitCode2 === 0 ? { level: "pass", message: `${scriptName} completed successfully.` } : { level: "fail", message: `${scriptName} failed with exit code ${exitCode2}.` }
       );
+      if (exitCode2 !== 0) break;
     }
   }
   for (const item of items) {
     write(formatItem(item));
   }
-  const exitCode = items.some((item) => item.level === "fail") ? 1 : 0;
+  const exitCode = commandFailureCode ?? (items.some((item) => item.level === "fail") ? 1 : 0);
   return { ...adapter ? { adapter } : {}, items, exitCode };
 }
 function adapterFromString(value) {
@@ -344,25 +446,39 @@ async function patchReact(cwd, dryRun) {
   if (!relativeFile) {
     return {
       adapter: "react",
+      status: "manual-action-required",
       changed: false,
       dryRun,
+      searchedFiles: candidates,
       message: "No React Vite entrypoint found. Expected src/main.tsx or src/main.jsx."
     };
   }
   const file = join(cwd, relativeFile);
   const source = await readFile(file, "utf8");
-  if (source.includes("MarwesProvider")) {
+  if (hasConfiguredProvider(source, "react")) {
     return {
       adapter: "react",
+      status: "already-configured",
       changed: false,
       dryRun,
       file: relativeFile,
       message: "React entrypoint already references MarwesProvider."
     };
   }
+  if (source.includes("MarwesProvider")) {
+    return {
+      adapter: "react",
+      status: "manual-action-required",
+      changed: false,
+      dryRun,
+      file: relativeFile,
+      message: "React entrypoint references MarwesProvider but not with a verified @marwes-ui/react import and render."
+    };
+  }
   if (!source.includes("<App />")) {
     return {
       adapter: "react",
+      status: "manual-action-required",
       changed: false,
       dryRun,
       file: relativeFile,
@@ -377,6 +493,7 @@ async function patchReact(cwd, dryRun) {
   const changed = await writeIfNeeded(file, next, dryRun);
   return {
     adapter: "react",
+    status: changed ? "applied" : "already-configured",
     changed,
     dryRun,
     file: relativeFile,
@@ -406,25 +523,39 @@ async function patchVue(cwd, dryRun) {
   if (!await fileExists(file)) {
     return {
       adapter: "vue",
+      status: "manual-action-required",
       changed: false,
       dryRun,
+      searchedFiles: [relativeFile],
       message: "No Vue starter component found. Expected src/App.vue."
     };
   }
   const source = await readFile(file, "utf8");
-  if (source.includes("<MarwesProvider")) {
+  if (hasConfiguredProvider(source, "vue")) {
     return {
       adapter: "vue",
+      status: "already-configured",
       changed: false,
       dryRun,
       file: relativeFile,
       message: "Vue starter component already contains MarwesProvider."
     };
   }
+  if (source.includes("MarwesProvider")) {
+    return {
+      adapter: "vue",
+      status: "manual-action-required",
+      changed: false,
+      dryRun,
+      file: relativeFile,
+      message: "Vue starter references MarwesProvider but not with a verified @marwes-ui/vue import and render."
+    };
+  }
   const templateMatch = source.match(/<template>([\s\S]*?)<\/template>/);
   if (!templateMatch) {
     return {
       adapter: "vue",
+      status: "manual-action-required",
       changed: false,
       dryRun,
       file: relativeFile,
@@ -435,6 +566,7 @@ async function patchVue(cwd, dryRun) {
   if (!innerTemplate) {
     return {
       adapter: "vue",
+      status: "manual-action-required",
       changed: false,
       dryRun,
       file: relativeFile,
@@ -453,6 +585,7 @@ async function patchVue(cwd, dryRun) {
   const changed = await writeIfNeeded(file, next, dryRun);
   return {
     adapter: "vue",
+    status: changed ? "applied" : "already-configured",
     changed,
     dryRun,
     file: relativeFile,
@@ -485,27 +618,41 @@ async function patchSvelte(cwd, dryRun) {
   if (!await fileExists(file)) {
     return {
       adapter: "svelte",
+      status: "manual-action-required",
       changed: false,
       dryRun,
+      searchedFiles: [relativeFile],
       message: "No Svelte starter component found. Expected src/App.svelte."
     };
   }
   const source = await readFile(file, "utf8");
-  if (source.includes("<MarwesProvider")) {
+  if (hasConfiguredProvider(source, "svelte")) {
     return {
       adapter: "svelte",
+      status: "already-configured",
       changed: false,
       dryRun,
       file: relativeFile,
       message: "Svelte starter component already contains MarwesProvider."
     };
   }
+  if (source.includes("MarwesProvider")) {
+    return {
+      adapter: "svelte",
+      status: "manual-action-required",
+      changed: false,
+      dryRun,
+      file: relativeFile,
+      message: "Svelte starter references MarwesProvider but not with a verified @marwes-ui/svelte import and render."
+    };
+  }
   const scriptBlocks = blockMatches(source, "script");
   const styleBlocks = blockMatches(source, "style");
   const body = removeBlocks(source, [...scriptBlocks, ...styleBlocks]).trim();
   if (!body) {
     return {
       adapter: "svelte",
+      status: "manual-action-required",
       changed: false,
       dryRun,
       file: relativeFile,
@@ -527,6 +674,7 @@ ${styles}` : ""
 `, dryRun);
   return {
     adapter: "svelte",
+    status: changed ? "applied" : "already-configured",
     changed,
     dryRun,
     file: relativeFile,
@@ -543,23 +691,79 @@ async function patchProject(cwd, adapter, dryRun) {
   return patchSvelte(cwd, dryRun);
 }
 
-// src/init.ts
-function providerGuidance(adapter) {
-  const recipe = getAdapterRecipe(adapter);
-  return `Manual follow-up: wrap the app root with ${recipe.providerImport} from ${recipe.packageName}.`;
-}
-function shouldPrintProviderGuidance(patch) {
-  if (!patch || patch.changed) {
-    return false;
+// src/setup-guidance.ts
+function providerExample(adapter) {
+  const packageName = getAdapterRecipe(adapter).packageName;
+  const providerImport = `import { MarwesProvider, type ThemeInput } from "${packageName}"`;
+  const theme = 'const brandTheme = { color: { primary: "#2457FF" } } satisfies ThemeInput';
+  if (adapter === "react") {
+    return [
+      'import { createRoot } from "react-dom/client"',
+      providerImport,
+      'import App from "./App"',
+      "",
+      theme,
+      "",
+      'createRoot(document.getElementById("root")!).render(',
+      "  <MarwesProvider theme={brandTheme}>",
+      "    <App />",
+      "  </MarwesProvider>,",
+      ")"
+    ].join("\n");
   }
-  return !patch.message.toLowerCase().includes("already");
+  return [
+    adapter === "vue" ? '<script setup lang="ts">' : '<script lang="ts">',
+    `  ${providerImport}`,
+    `  ${theme}`,
+    "</script>",
+    "",
+    ...adapter === "vue" ? [
+      "<template>",
+      '  <MarwesProvider :theme="brandTheme">',
+      "    <main>Your app</main>",
+      "  </MarwesProvider>",
+      "</template>"
+    ] : ["<MarwesProvider theme={brandTheme}>", "  <main>Your app</main>", "</MarwesProvider>"]
+  ].join("\n");
 }
-function writeAgenticBoundaryRules(adapter, write) {
+function setupGuidance(adapter, fullExample) {
   const recipe = getAdapterRecipe(adapter);
-  write("Agentic rules:");
-  write(`- Import Marwes APIs only from ${recipe.packageName}.`);
-  write("- Do not install @marwes-ui/core or @marwes-ui/presets directly.");
-  write("- Do not add a separate Marwes stylesheet import.");
+  const ssrIntegration = { react: "next", vue: "nuxt", svelte: "sveltekit" }[adapter];
+  const hookGuidance = {
+    react: "useTheme() returns resolved concrete values: const theme = useTheme(); read theme.color.primary.base.",
+    vue: "useTheme() returns a resolved snapshot directly, not a ref: const theme = useTheme(); read theme.color.primary.base (no .value).",
+    svelte: "useTheme() returns a .theme getter: const themeState = useTheme(); read themeState.theme.color.primary.base. Keep the getter object; destructuring .theme takes a snapshot."
+  }[adapter];
+  return [
+    "Marwes setup guidance:",
+    `- Import Marwes APIs only from ${recipe.packageName}.`,
+    "- Do not install or import @marwes-ui/core or @marwes-ui/presets directly.",
+    "- Default preset CSS loads automatically from the adapter; do not add a separate Marwes stylesheet import.",
+    "- Wrap the app once with MarwesProvider; pass a small typed ThemeInput override. Unspecified values retain defaults.",
+    "- --mw-* CSS variables are scoped to the provider and its descendants, not :root. Keep app styles and runtime consumers below the provider.",
+    "- Use mwThemeVars for CSS var(...) references, not concrete JavaScript values. Call useTheme() only in a child component below MarwesProvider.",
+    `- ${hookGuidance}`,
+    ...fullExample ? [
+      `Complete ${recipe.displayName} provider example:`,
+      providerExample(adapter),
+      `Component example: import { PrimaryButton } from "${recipe.packageName}"; render <PrimaryButton>Save</PrimaryButton> below the provider. Use public components, not invented mw-* replacement classes.`,
+      `Token example: import { mwThemeVars } from "${recipe.packageName}"; use mwThemeVars.color.text and mwThemeVars.spacing.sp24 in app-owned styles below the provider.`,
+      "For SSR, follow the framework guide for matching style/script helpers and provider options before hydration; changing html classes alone is not no-flash setup."
+    ] : [],
+    `Setup guide: https://marwes.io/docs/get-started/${adapter}/`,
+    "Theming guide: https://marwes.io/docs/theming/",
+    `SSR guide: https://marwes.io/docs/integrations/${ssrIntegration}/`,
+    ...fullExample ? [
+      "AI discovery: https://marwes.io/llms.txt",
+      `AI framework guide: https://marwes.io/ai/${adapter}.md`,
+      "Public export inventory: https://marwes.io/ai/v1/public-api.json"
+    ] : []
+  ];
+}
+
+// src/init.ts
+function shouldPrintProviderGuidance(patch) {
+  return patch?.status === "manual-action-required";
 }
 async function runInit(options) {
   const cwd = options.cwd ?? process.cwd();
@@ -586,7 +790,12 @@ async function runInit(options) {
   } else {
     exitCode = await runner(command, { cwd });
     if (exitCode !== 0) {
+      write("Marwes init status: failed.");
+      write(
+        `Marwes init failed: installation command exited with code ${exitCode}. Provider patching and doctor were not run.`
+      );
       return {
+        status: "failed",
         adapter: options.adapter,
         packageManager,
         installCommand: commandLabel,
@@ -603,29 +812,47 @@ async function runInit(options) {
     patch = await patchProject(cwd, options.adapter, dryRun);
     const patchLabel = patch.file ? `${patch.file}: ${patch.message}` : patch.message;
     write(dryRun && patch.changed ? `[dry-run] ${patchLabel}` : patchLabel);
+    if (patch.searchedFiles?.length) {
+      write(`Files searched: ${patch.searchedFiles.join(", ")}`);
+    }
   }
   let doctor;
-  if (agentic) {
-    if (shouldPrintProviderGuidance(patch) || noPatch) {
-      write(providerGuidance(options.adapter));
-    }
-    writeAgenticBoundaryRules(options.adapter, write);
-    if (dryRun) {
-      write(`[dry-run] marwes doctor --adapter ${options.adapter}`);
-    } else {
-      write("Marwes doctor:");
-      doctor = await runDoctor({
-        adapter: options.adapter,
-        cwd,
-        packageManager,
-        runner,
-        write
-      });
-      exitCode = doctor.exitCode;
-    }
+  if (dryRun) {
+    write(`[dry-run] marwes doctor --adapter ${options.adapter}`);
+  } else {
+    write("Marwes doctor:");
+    doctor = await runDoctor({
+      adapter: options.adapter,
+      cwd,
+      packageManager,
+      runner,
+      write
+    });
+  }
+  const providerFailure = doctor?.items.some(
+    (item) => item.level === "fail" && item.message.startsWith("MarwesProvider")
+  ) === true;
+  const otherFailure = doctor?.items.some(
+    (item) => item.level === "fail" && !item.message.startsWith("MarwesProvider")
+  ) === true;
+  const needsManualAction = providerFailure && (shouldPrintProviderGuidance(patch) || noPatch);
+  const status = otherFailure ? "failed" : needsManualAction ? "manual-action-required" : doctor && doctor.exitCode !== 0 ? "failed" : "complete";
+  if (needsManualAction) {
+    write(
+      `Manual follow-up: wrap the app root with ${recipe.providerImport} from ${recipe.packageName}.`
+    );
+    write("Automatic patching currently supports the standard Vite app layout.");
+  }
+  if (agentic || needsManualAction || status === "complete") {
+    for (const line of setupGuidance(options.adapter, agentic || needsManualAction)) write(line);
   }
-  write("Marwes init complete.");
+  exitCode = status === "manual-action-required" ? 2 : status === "failed" ? doctor?.exitCode ?? 1 : 0;
+  write(dryRun ? `[dry-run] Planned init status: ${status}.` : `Marwes init status: ${status}.`);
+  write(
+    dryRun ? "[dry-run] Marwes init plan complete. No installation, file changes, or doctor checks performed." : status === "complete" ? "Marwes init complete." : status === "manual-action-required" ? "Marwes provider wiring requires manual action (exit code 2)." : "Marwes init failed."
+  );
   return {
+    status,
     adapter: options.adapter,
     packageManager,
     installCommand: commandLabel,
@@ -638,10 +865,35 @@ async function runInit(options) {
 }
 
 // src/create.ts
+var safeProjectPathPattern = /^[a-zA-Z0-9][a-zA-Z0-9._-]*(?:\/[a-zA-Z0-9][a-zA-Z0-9._-]*)*$/;
+function isSafeProjectPath(projectName) {
+  return safeProjectPathPattern.test(projectName);
+}
+async function stageAdapterDependency(cwd, adapter) {
+  const packageJsonPath = resolve(cwd, "package.json");
+  const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+  const packageName = getAdapterRecipe(adapter).packageName;
+  const dependencies = packageJson.dependencies ?? {};
+  if (!(packageName in dependencies) && !(packageName in (packageJson.devDependencies ?? {}))) {
+    packageJson.dependencies = { ...dependencies, [packageName]: "latest" };
+    await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}
+`);
+  }
+}
 async function runCreate(options) {
   const cwd = options.cwd ?? process.cwd();
   const write = options.write ?? ((message) => console.log(message));
   const runner = options.runner ?? defaultCommandRunner;
+  if (!isSafeProjectPath(options.projectName)) {
+    write(
+      "Invalid project name. Use a relative path made from letters, numbers, dots, dashes, underscores, and forward slashes."
+    );
+    return {
+      projectName: options.projectName,
+      template: options.template,
+      exitCode: 1
+    };
+  }
   const packageManager = options.packageManager ?? await detectPackageManager(cwd);
   const command = createViteCommand(packageManager, options.projectName, options.template);
   const adapter = adapterFromTemplate(options.template);
@@ -665,6 +917,12 @@ async function runCreate(options) {
       exitCode: createExitCode
     };
   }
+  if (options.noInstall) {
+    await stageAdapterDependency(targetCwd, adapter);
+    write(
+      `Recorded ${getAdapterRecipe(adapter).packageName} in package.json. Run ${packageManager} install before starting the app.`
+    );
+  }
   const initResult = await runInit({
     adapter,
     cwd: targetCwd,
@@ -694,10 +952,65 @@ Options:
   --pm <${supportedPackageManagersLabel()}>
   --agentic
   --dry-run
-  --no-install
+  --no-install                      Record dependencies but skip installation
   --no-patch
 `);
 }
+function wantsHelp(args) {
+  return args.includes("--help") || args.includes("-h") || args[0] === "help";
+}
+function writeInitHelp(write) {
+  write(`marwes init --adapter <${supportedAdaptersLabel()}>
+
+Install a framework adapter, wire MarwesProvider into a standard Vite app, then run doctor.
+
+Options:
+  --adapter <${supportedAdaptersLabel()}>  Required framework adapter
+  --pm <${supportedPackageManagersLabel()}>       Package manager override
+  --agentic                         Print AI-agent boundary rules
+  --dry-run                         Show changes without writing or installing
+  --no-install                      Skip dependency installation
+  --no-patch                        Skip automatic provider wiring
+  --yes                             Accept defaults
+  --help                            Show this help
+`);
+}
+function writeDoctorHelp(write) {
+  write(`marwes doctor [--adapter <${supportedAdaptersLabel()}>] [--run-build]
+
+Verify dependencies, adapter imports, provider rendering, and optional project compilation.
+
+Options:
+  --adapter <${supportedAdaptersLabel()}>  Framework adapter override
+  --pm <${supportedPackageManagersLabel()}>       Package manager override
+  --run-build                       Run optional typecheck, then the required production build
+  --help                            Show this help
+`);
+}
+function writeAiPromptHelp(write) {
+  write(`marwes ai-prompt --adapter <${supportedAdaptersLabel()}>
+
+Print a framework-specific setup prompt for an AI coding agent.
+
+Options:
+  --adapter <${supportedAdaptersLabel()}>  Required framework adapter
+  --pm <${supportedPackageManagersLabel()}>       Package manager used in the prompt
+  --help                            Show this help
+`);
+}
+function writeCreateHelp(write) {
+  write(`create-marwes <name> --template <${supportedTemplatesLabel()}>
+
+Create a new Vite app and configure its Marwes adapter.
+
+Options:
+  --template <${supportedTemplatesLabel()}>
+  --pm <${supportedPackageManagersLabel()}>
+  --dry-run
+  --no-install
+  --help
+`);
+}
 function parsePackageManager(value) {
   return typeof value === "string" && isPackageManager(value) ? value : void 0;
 }
@@ -709,6 +1022,10 @@ async function runMarwesCli(argv, options = {}) {
     return 0;
   }
   if (command === "init") {
+    if (wantsHelp(args)) {
+      writeInitHelp(write);
+      return 0;
+    }
     const parsed = parseArgs({
       args,
       options: {
@@ -747,6 +1064,10 @@ async function runMarwesCli(argv, options = {}) {
     return result.exitCode;
   }
   if (command === "doctor") {
+    if (wantsHelp(args)) {
+      writeDoctorHelp(write);
+      return 0;
+    }
     const parsed = parseArgs({
       args,
       options: {
@@ -775,6 +1096,10 @@ async function runMarwesCli(argv, options = {}) {
     return result.exitCode;
   }
   if (command === "ai-prompt") {
+    if (wantsHelp(args)) {
+      writeAiPromptHelp(write);
+      return 0;
+    }
     const parsed = parseArgs({
       args,
       options: {
@@ -800,6 +1125,10 @@ async function runMarwesCli(argv, options = {}) {
 }
 async function runCreateMarwesCli(argv, options = {}) {
   const write = options.write ?? ((message) => console.log(message));
+  if (wantsHelp(argv)) {
+    writeCreateHelp(write);
+    return 0;
+  }
   const parsed = parseArgs({
     args: argv,
     options: {