feat: harden wizard flow and env mapping (#8)

Author: onmax

README.md

@@ -173,27 +173,31 @@ export function getPrivateConfig() {
 
 [Shelve](https://shelve.cloud) is a secrets management service. This module fetches secrets from Shelve at build time and merges them into your runtime config before validation.
 
-### Zero-Config Setup
+### Configure Shelve
 
-If you have a `shelve.json` file in your project root, the integration enables automatically:
+Configure Shelve directly in your Nuxt config:
 
 ```ts
 export default defineNuxtConfig({
   safeRuntimeConfig: {
     $schema: runtimeConfigSchema,
-    shelve: true, // Auto-detects project, team, and environment
+    shelve: {
+      project: 'my-app',
+      slug: 'my-team',
+    },
   },
 })
 ```
 
 The module resolves configuration from multiple sources (highest priority first):
 
-| Config      | Sources                                                                |
-| ----------- | ---------------------------------------------------------------------- |
-| project     | `nuxt.config` → `SHELVE_PROJECT` → `shelve.json` → `package.json` name |
-| slug        | `nuxt.config` → `SHELVE_TEAM_SLUG` → `shelve.json`                     |
-| environment | `nuxt.config` → `SHELVE_ENV` → `shelve.json` → dev mode auto           |
-| token       | `SHELVE_TOKEN` → `~/.shelve` file                                      |
+| Config      | Sources                                                      |
+| ----------- | ------------------------------------------------------------ |
+| project     | `nuxt.config` → `SHELVE_PROJECT` → `package.json` name       |
+| slug        | `nuxt.config.slug/team` → `SHELVE_TEAM` → `SHELVE_TEAM_SLUG` |
+| environment | `nuxt.config` → `SHELVE_ENV` → dev mode auto                 |
+| url         | `nuxt.config` → `SHELVE_URL` → `https://app.shelve.cloud`    |
+| token       | `SHELVE_TOKEN` → `~/.shelve`                                 |
 
 ### Explicit Configuration
 
@@ -245,6 +249,14 @@ export default defineNuxtConfig({
 
 The runtime plugin runs before validation, so freshly fetched secrets are validated against your schema.
 
+### Install Wizard UX
+
+On module install, an interactive setup wizard can help bootstrap validation and Shelve config. The wizard now:
+
+- shows a preview of planned actions first (install deps, write `~/.shelve`, edit `nuxt.config`)
+- asks for a final confirmation before applying any change
+- skips automatically in CI and non-interactive terminals (non-TTY)
+
 ## Runtime Validation
 
 By default, validation only runs at build time. Enable runtime validation to catch environment variable issues when the server starts:
@@ -324,6 +336,12 @@ When validation fails, you see detailed error messages:
 
 The module stops the build process until all validation errors are resolved.
 
+## Upcoming Major Release Notes
+
+- Shelve setup no longer documents `shelve.json` auto-enablement; supported sources are `nuxt.config`, env vars, and `package.json` fallback for project name.
+- The install wizard now previews actions and requires explicit confirmation before mutating files or writing credentials.
+- Runtime and wizard key-shaping now use the same env-key mapping rules to avoid schema/runtime drift.
+
 ## Why This Module?
 
 Nuxt's built-in schema validation is designed for module authors and broader configuration. This module focuses specifically on **runtime config validation** using Standard Schema, allowing you to:

docs/3.integrations/2.shelve.md

@@ -57,6 +57,18 @@ export default defineNuxtConfig({
 
 For local development, run `shelve login` to authenticate. For CI/CD, set the `SHELVE_TOKEN` environment variable.
 
+## Setup Wizard
+
+On module install (interactive terminals only), the setup wizard can bootstrap schema + Shelve configuration.
+
+Before mutating anything, it shows the planned actions and asks for final confirmation:
+
+- install validation dependencies (if needed)
+- write `~/.shelve` token (if newly entered)
+- update `nuxt.config`
+
+In CI and non-interactive terminals, the wizard is skipped automatically.
+
 ## How It Works
 
 1. The module reads your Shelve configuration from nuxt.config
@@ -170,7 +182,17 @@ You can override any configuration using environment variables:
 | ------------------ | ------------------------------ |
 | `SHELVE_TOKEN`     | Authentication token           |
 | `SHELVE_PROJECT`   | Project name                   |
+| `SHELVE_TEAM`      | Team slug                      |
 | `SHELVE_TEAM_SLUG` | Team slug                      |
 | `SHELVE_ENV`       | Environment name               |
 | `SHELVE_URL`       | API URL (for self-hosted)      |
 
+Resolution priority (high to low):
+
+| Config        | Priority                                                           |
+| ------------- | ------------------------------------------------------------------ |
+| `project`     | `nuxt.config` → `SHELVE_PROJECT` → `package.json` name             |
+| `slug`        | `nuxt.config.slug/team` → `SHELVE_TEAM` → `SHELVE_TEAM_SLUG`       |
+| `environment` | `nuxt.config` → `SHELVE_ENV` → auto (`development`/`production`)   |
+| `url`         | `nuxt.config` → `SHELVE_URL` → `https://app.shelve.cloud`          |
+| `token`       | `SHELVE_TOKEN` → `~/.shelve`                                       |

src/module.ts

@@ -1,6 +1,7 @@
 import type { Nuxt } from '@nuxt/schema'
 import type { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec'
 import type { ErrorBehavior, ModuleOptions } from './types'
+import process from 'node:process'
 import { addImportsDir, addServerImportsDir, addTemplate, addTypeTemplate, createResolver, defineNuxtModule, useLogger } from '@nuxt/kit'
 import { toJsonSchema } from '@standard-community/standard-json'
 import defu from 'defu'
@@ -61,7 +62,7 @@ export default defineNuxtModule<ModuleOptions>({
   // onInstall requires Nuxt 4.1+ - ignored on older versions
   // @ts-expect-error onInstall is Nuxt 4.1+ feature
   async onInstall(nuxt: Nuxt) {
-    if (isCI || isTest)
+    if (isCI || isTest || !process.stdin.isTTY || !process.stdout.isTTY)
       return
     await runShelveWizard(nuxt)
   },

src/module.ts.bak

@@ -9,59 +9,63 @@ export function getPrefix(key: string): string | null {
   return parts.length > 1 ? parts[0]! : null
 }
 
-function countPrefixes(vars: EnvVar[]): Map<string, number> {
+function countPrefixes(keys: string[]): Map<string, number> {
   const counts = new Map<string, number>()
-  for (const { key } of vars) {
+  for (const key of keys) {
     const prefix = getPrefix(key)
     if (prefix)
       counts.set(prefix, (counts.get(prefix) || 0) + 1)
   }
   return counts
 }
 
-/** Transforms EnvVar[] to camelCase runtimeConfig. Groups repeated prefixes (2+ keys) and routes PUBLIC_* / NUXT_PUBLIC_* to public namespace */
-export function transformEnvVars(vars: EnvVar[]): TransformedConfig {
-  const prefixCounts = countPrefixes(vars)
-  const result: TransformedConfig = {}
+export type ConfigStructure = Record<string, true | Record<string, true>>
 
-  for (const { key, value } of vars) {
-    if (key.startsWith('PUBLIC_')) {
-      result.public ??= {}
-      assignNested(result.public as Record<string, unknown>, key.slice(7), value, prefixCounts)
-      continue
-    }
-    if (key.startsWith('NUXT_PUBLIC_')) {
-      result.public ??= {}
-      assignNested(result.public as Record<string, unknown>, key.slice(12), value, prefixCounts)
-      continue
-    }
+function resolveConfigPath(key: string, prefixCounts: Map<string, number>): string[] {
+  if (key.startsWith('PUBLIC_'))
+    return ['public', toCamelCase(key.slice(7))]
+  if (key.startsWith('NUXT_PUBLIC_'))
+    return ['public', toCamelCase(key.slice(12))]
 
-    const prefix = getPrefix(key)
-    if (prefix && (prefixCounts.get(prefix) || 0) >= 2) {
-      const groupKey = toCamelCase(prefix)
-      result[groupKey] ??= {}
-      const nestedKey = toCamelCase(key.slice(prefix.length + 1))
-        ; (result[groupKey] as Record<string, unknown>)[nestedKey] = value
-    }
-    else {
-      result[toCamelCase(key)] = value
-    }
+  const prefix = getPrefix(key)
+  if (prefix && (prefixCounts.get(prefix) || 0) >= 2) {
+    return [toCamelCase(prefix), toCamelCase(key.slice(prefix.length + 1))]
   }
+  return [toCamelCase(key)]
+}
 
-  return result
+function assignPath<TValue>(target: Record<string, TValue | Record<string, TValue>>, path: string[], value: TValue): void {
+  if (path.length === 1) {
+    target[path[0]!] = value
+    return
+  }
+
+  const [head, ...tail] = path
+  target[head!] ??= {}
+  assignPath(target[head!] as Record<string, TValue | Record<string, TValue>>, tail, value)
 }
 
-/** Applies same grouping rules to PUBLIC_* vars within the public namespace */
-function assignNested(obj: Record<string, unknown>, key: string, value: string, prefixCounts: Map<string, number>): void {
-  const prefix = getPrefix(key)
-  if (prefix && (prefixCounts.get(`PUBLIC_${prefix}`) || prefixCounts.get(`NUXT_PUBLIC_${prefix}`) || 0) >= 2) {
-    const groupKey = toCamelCase(prefix)
-    obj[groupKey] ??= {}
-    const rest = key.slice(prefix.length + 1)
-    const nestedKey = toCamelCase(rest)
-      ; (obj[groupKey] as Record<string, unknown>)[nestedKey] = value
+export function buildConfigStructureFromEnvKeys(keys: string[]): ConfigStructure {
+  const result: ConfigStructure = {}
+  const prefixCounts = countPrefixes(keys)
+
+  for (const key of keys) {
+    const path = resolveConfigPath(key, prefixCounts)
+    assignPath(result, path, true)
   }
-  else {
-    obj[toCamelCase(key)] = value
+
+  return result
+}
+
+/** Transforms EnvVar[] to camelCase runtimeConfig. Groups repeated prefixes (2+ keys) and routes PUBLIC_* / NUXT_PUBLIC_* to public namespace */
+export function transformEnvVars(vars: EnvVar[]): TransformedConfig {
+  const result: TransformedConfig = {}
+  const prefixCounts = countPrefixes(vars.map(v => v.key))
+
+  for (const { key, value } of vars) {
+    const path = resolveConfigPath(key, prefixCounts)
+    assignPath(result as Record<string, string | Record<string, string>>, path, value)
   }
+
+  return result
 }