specshield 3.2.1 → 3.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specshield",
-  "version": "3.2.1",
+  "version": "3.2.2",
   "description": "CLI for OpenAPI breaking change detection and bi-directional contract verification — with can-i-deploy gating, GitHub PR checks, and a first-run setup wizard.",
   "main": "src/cli.js",
   "bin": {

package/src/commands/bdct.js

@@ -41,7 +41,7 @@ function withProjectDefaults(opts, command) {
   try {
     applyBdctDefaults(opts, command);
   } catch (err) {
-    if (err.code === 'MISSING_REQUIRED_OPTIONS') {
+    if (err.code === 'MISSING_REQUIRED_OPTIONS' || err.code === 'UNRESOLVED_PLACEHOLDER') {
       logger.error(err.message);
       process.exit(2);
     }

package/src/commands/init.js

@@ -25,6 +25,17 @@ const DEFAULT_SERVER = 'https://specshield.io';
 
 // ─── Helpers ───────────────────────────────────────────────────────────────
 
+const PLACEHOLDER = '<replace-me>';
+
+// Skippable text fields in the interactive wizard. Empty values for these
+// become PLACEHOLDER tokens in the generated config; non-skippable fields
+// (kind, contractFormat, environment which has a default) are not in this list.
+const PLACEHOLDER_FIELDS = [
+  'providerName', 'specPath',
+  'consumerName', 'consumerProvider', 'contractPath',
+  'org',
+];
+
 function abortIfCancelled(answers, keys) {
   // `prompts` returns undefined values when the user hits Ctrl-C.
   for (const k of keys) {
@@ -35,6 +46,42 @@ function abortIfCancelled(answers, keys) {
   }
 }
 
+/**
+ * Replace empty answers with the PLACEHOLDER token so the generated config
+ * makes the gap visible (vs writing an empty string the user might miss).
+ * Only operates on the fields listed in PLACEHOLDER_FIELDS — required
+ * non-text choices like `kind` are left untouched.
+ */
+function fillPlaceholders(answers) {
+  for (const f of PLACEHOLDER_FIELDS) {
+    if (answers[f] === '' || answers[f] === null || answers[f] === undefined) continue;
+    // Keep the value the user entered.
+  }
+  for (const f of PLACEHOLDER_FIELDS) {
+    if (answers[f] === '' || answers[f] === null) answers[f] = PLACEHOLDER;
+  }
+}
+
+/**
+ * Walk a built config object and return a list of `{ path, value }` for every
+ * leaf whose value equals PLACEHOLDER. The `path` is the dotted YAML path
+ * (e.g. `bdct.org`, `bdct.provider.spec`) — same form the user sees when
+ * editing the .specshield.yml file.
+ */
+function collectPlaceholders(cfg) {
+  const out = [];
+  const walk = (obj, prefix) => {
+    if (!obj || typeof obj !== 'object') return;
+    for (const [k, v] of Object.entries(obj)) {
+      const p = prefix ? `${prefix}.${k}` : k;
+      if (v === PLACEHOLDER) out.push({ path: p, value: v });
+      else if (v && typeof v === 'object') walk(v, p);
+    }
+  };
+  walk(cfg, '');
+  return out;
+}
+
 async function validateApiKey(server, key) {
   try {
     const res = await axios.post(`${server.replace(/\/$/, '')}/auth/validate-api-key`,
@@ -156,12 +203,21 @@ async function interactiveFlow(detected, opts) {
   const wantsProvider = k.kind === 'provider' || k.kind === 'both';
   const wantsConsumer = k.kind === 'consumer' || k.kind === 'both';
 
+  // Optional-by-default prompts. Pressing Enter on any text field is OK
+  // and produces a "<replace-me>" placeholder in the generated config —
+  // surfaced at the end of the wizard and refused by any bdct command
+  // that later tries to use it. Lets a user explore the wizard without
+  // having to know their org key or provider name up front.
+  const skipHint = chalk.gray('(press Enter to skip — fill in later)');
+
   if (wantsProvider) {
     const provQs = [
-      { type: 'text', name: 'providerName', message: 'Provider name', initial: detected.serviceName },
-      { type: 'text', name: 'specPath',     message: 'Path to provider OpenAPI spec',
-        initial: detected.spec || 'api/openapi.yaml',
-        validate: (v) => v ? true : 'Required',
+      { type: 'text', name: 'providerName',
+        message: `Provider name ${skipHint}`,
+        initial: detected.serviceName },
+      { type: 'text', name: 'specPath',
+        message: `Path to provider OpenAPI spec ${skipHint}`,
+        initial: detected.spec || 'openapi.yaml',
       },
     ];
     const r = await prompts(provQs);
@@ -171,15 +227,14 @@ async function interactiveFlow(detected, opts) {
 
   if (wantsConsumer) {
     const consQs = [
-      { type: 'text', name: 'consumerName',     message: 'Consumer name',
+      { type: 'text', name: 'consumerName',
+        message: `Consumer name ${skipHint}`,
         initial: detected.serviceName },
-      { type: 'text', name: 'consumerProvider', message: 'Provider this consumer talks to',
-        validate: (v) => v ? true : 'Required',
-      },
-      { type: 'text', name: 'contractPath',     message: 'Path to consumer contract',
-        initial: 'contracts/contract.yaml',
-        validate: (v) => v ? true : 'Required',
-      },
+      { type: 'text', name: 'consumerProvider',
+        message: `Provider this consumer talks to ${skipHint}` },
+      { type: 'text', name: 'contractPath',
+        message: `Path to consumer contract ${skipHint}`,
+        initial: 'contracts/contract.yaml' },
       { type: 'select', name: 'contractFormat', message: 'Contract format',
         choices: [
           { title: 'OpenAPI', value: 'OPENAPI' },
@@ -243,8 +298,8 @@ async function interactiveFlow(detected, opts) {
       });
       abortIfCancelled(r, ['org']);
       if (r.org === '__manual__') {
-        const m = await prompts({ type: 'text', name: 'org', message: 'Org key',
-          validate: (v) => v ? true : 'Required' });
+        const m = await prompts({ type: 'text', name: 'org',
+          message: `Org key ${skipHint}` });
         abortIfCancelled(m, ['org']);
         answers.org = m.org;
       } else {
@@ -252,8 +307,8 @@ async function interactiveFlow(detected, opts) {
       }
     } else {
       const r = await prompts({
-        type: 'text', name: 'org', message: 'Org key',
-        validate: (v) => v ? true : 'Required',
+        type: 'text', name: 'org',
+        message: `Org key ${skipHint}`,
       });
       abortIfCancelled(r, ['org']);
       answers.org = r.org;
@@ -409,6 +464,11 @@ const initCommand = new Command('init')
       if (answers === null) return;     // user said "don't overwrite"
     }
 
+    // Empty answers from the interactive flow → "<replace-me>" placeholders.
+    // The end-of-wizard summary lists every placeholder by path so users
+    // don't accidentally commit them.
+    fillPlaceholders(answers);
+
     const cfg  = buildConfig(answers, detected);
     const yaml = render(cfg);
 
@@ -435,10 +495,29 @@ const initCommand = new Command('init')
         providerName:        answers.providerName,
         consumerName:        answers.consumerName,
         providerForConsumer: answers.consumerProvider,
+        org:                 answers.org,
+        specPath:            answers.specPath,
+        contractPath:        answers.contractPath,
+        environment:         answers.environment,
       }, cwd);
       ok(`Wrote ${chalk.white(path.relative(cwd, workflowPath))}`);
     }
 
+    // Placeholders summary — if the user pressed Enter on any prompt,
+    // surface what's still missing so they can fill it in before running
+    // any bdct command. Pre-flight checks in bdct.js will block commands
+    // that hit a literal "<replace-me>" value at runtime.
+    const placeholders = collectPlaceholders(cfg);
+    if (placeholders.length > 0) {
+      fmtSection('Placeholders to fill in');
+      placeholders.forEach(p =>
+        warn(`${chalk.yellow(p.path)} = ${chalk.gray('<replace-me>')}`));
+      warn(chalk.yellow(
+        `Edit ${path.relative(cwd, target) || '.specshield.yml'} ` +
+        `to replace ${placeholders.length} placeholder${placeholders.length === 1 ? '' : 's'} ` +
+        `before running bdct commands.`));
+    }
+
     fmtSection('Next steps');
     if (answers.kind !== 'skip') {
       info(`Try: ${chalk.white('specshield bdct list-providers')}`);
@@ -449,3 +528,6 @@ const initCommand = new Command('init')
   });
 
 module.exports = initCommand;
+
+// Exposed for unit tests — keep usage internal to the init module otherwise.
+module.exports.__test__ = { fillPlaceholders, collectPlaceholders, PLACEHOLDER };

package/src/core/configWriter.js

@@ -137,10 +137,32 @@ function writeProjectConfig(config, cwd = process.cwd()) {
 /**
  * Render a starter GitHub Actions workflow that uses
  * `specshield26/bdct-action@v1`. Optional output of the wizard.
+ *
+ * Every input forwarded to the action MUST be present in the rendered YAML
+ * — including org. A missing org renders `--org ""` on the CLI invocation
+ * and the action fails with a cryptic "expected value" error from commander.
+ *
+ * spec/contract paths come from detection (or the user's --spec / --contract
+ * flag). They are NOT hardcoded — a previous version assumed every project
+ * stored its spec at `api/openapi.yaml`, which broke every project that
+ * keeps the spec at the repo root.
  */
-function renderWorkflow({ kind, providerName, consumerName, providerForConsumer }) {
+function renderWorkflow({
+  kind,
+  providerName,
+  consumerName,
+  providerForConsumer,
+  org,
+  specPath,
+  contractPath,
+  environment,
+}) {
   const isProvider = kind === 'provider' || kind === 'both';
   const isConsumer = kind === 'consumer' || kind === 'both';
+  const env = environment || 'production';
+  const orgLine = org ? `          org: ${org}` : '          org: <replace-me>';
+  const spec    = specPath     || 'openapi.yaml';
+  const contract = contractPath || 'contracts/contract.yaml';
 
   const lines = [
     '# .github/workflows/specshield-bdct.yml',
@@ -163,10 +185,11 @@ function renderWorkflow({ kind, providerName, consumerName, providerForConsumer
       '      - uses: specshield26/bdct-action@v1',
       '        with:',
       '          command: publish-provider',
+      orgLine,
       `          provider: ${providerName}`,
       '          version: ${{ github.sha }}',
-      '          spec: api/openapi.yaml',
-      '          env: production',
+      `          spec: ${spec}`,
+      `          env: ${env}`,
       '          api-token: ${{ secrets.SPECSHIELD_API_KEY }}',
       '',
       '  gate:',
@@ -176,9 +199,10 @@ function renderWorkflow({ kind, providerName, consumerName, providerForConsumer
       '      - uses: specshield26/bdct-action@v1',
       '        with:',
       '          command: can-i-deploy',
+      orgLine,
       `          service: ${providerName}`,
       '          version: ${{ github.sha }}',
-      '          env: production',
+      `          env: ${env}`,
       '          api-token: ${{ secrets.SPECSHIELD_API_KEY }}',
       '',
     );
@@ -193,10 +217,11 @@ function renderWorkflow({ kind, providerName, consumerName, providerForConsumer
       '      - uses: specshield26/bdct-action@v1',
       '        with:',
       '          command: publish-consumer',
+      orgLine,
       `          consumer: ${consumerName}`,
       `          provider: ${providerForConsumer}`,
       '          version: ${{ github.sha }}',
-      '          contract: contracts/contract.yaml',
+      `          contract: ${contract}`,
       '          api-token: ${{ secrets.SPECSHIELD_API_KEY }}',
       '',
     );

package/src/core/projectConfig.js

@@ -157,6 +157,25 @@ function applyBdctDefaults(opts, command, { cwd = process.cwd() } = {}) {
     opts[f] = (f === 'spec' || f === 'contract') ? resolvePath(def) : def;
   }
 
+  // Placeholder check — `<replace-me>` is the marker `specshield init` writes
+  // for fields the user skipped during the wizard. Letting it flow through
+  // would send the literal string to the backend, producing confusing 4xx
+  // errors. Refuse with a message that points at the file and field.
+  const placeholders = FIELDS
+    .filter(f => opts[f] === '<replace-me>')
+    .map(f => '--' + f.replace(/[A-Z]/g, m => '-' + m.toLowerCase()));
+  if (placeholders.length > 0) {
+    const where = cfg._file ? cfg._file : '(no config file found)';
+    const err = new Error(
+      `The following value${placeholders.length === 1 ? ' is' : 's are'} still set to ` +
+      `the "<replace-me>" placeholder written by \`specshield init\`: ` +
+      placeholders.join(', ') + '\n' +
+      `Edit ${where} (or pass real values as CLI flags) before re-running.`);
+    err.code = 'UNRESOLVED_PLACEHOLDER';
+    err.placeholders = placeholders;
+    throw err;
+  }
+
   // Required-field check.
   const required = REQUIRED_FIELDS[command] || [];
   const missing  = required.filter(k => !opts[k]);