create-sdd-project 0.16.8 → 0.16.9

package/lib/doctor.js

@@ -73,6 +73,9 @@ function runDoctor(cwd) {
   // 12. Gemini Settings Format
   results.push(checkGeminiSettings(cwd, aiTools));
 
+  // 13. Gemini TOML Commands Format
+  results.push(checkGeminiCommands(cwd, aiTools));
+
   return results;
 }
 
@@ -613,6 +616,330 @@ function checkGeminiSettings(cwd, aiTools) {
   };
 }
 
+/**
+ * Validate a .gemini/commands/*.toml file using a strict subset of TOML
+ * grammar sufficient for our narrow use case.
+ *
+ * Scope: the templates we ship only use two top-level keys (`description`,
+ * `prompt`) with string values — standard quoted (`"..."`), single-quoted
+ * literal (`'...'`), or triple-quoted multiline (`"""..."""` / `'''...'''`).
+ * This validator enforces that subset strictly:
+ *
+ * - Each non-blank, non-comment line must be either a top-level assignment
+ *   `key = <string-literal>` or the start of a multiline string
+ * - Top-level keys must match `[A-Za-z][A-Za-z0-9_-]*` (bare keys only —
+ *   quoted keys like `"prompt" = "x"` are flagged as invalid; our templates
+ *   never use them)
+ * - Duplicate top-level keys are rejected (TOML spec forbids them)
+ * - Strings must be properly closed on the same line (except triple-quoted,
+ *   which can span lines)
+ * - Trailing content after a closed string is rejected (only a `#` comment
+ *   is allowed after the value)
+ * - Values that are not string literals (numbers, booleans, arrays, etc.)
+ *   are flagged as non-string
+ * - Assignments inside `[table]` or `[[array-table]]` sections are not
+ *   considered top-level and the scan stops there (our templates don't use
+ *   tables)
+ *
+ * This validator is intentionally stricter than full TOML and looser in a
+ * few edge cases (e.g., escape sequences inside basic strings are accepted
+ * as `\\.`). The goal is to catch files that Gemini CLI's FileCommandLoader
+ * would silently skip — not to be a general-purpose TOML parser. If our
+ * templates ever need richer TOML features, upgrade to `@iarna/toml` as
+ * a runtime dependency at that point.
+ *
+ * Returns:
+ *   { ok: true, keys: { prompt?: 'string' | 'non-string', description?: 'string' | 'non-string' } }
+ *   { ok: false, error: '<message>', line: N }
+ */
+function validateTomlCommandFile(content) {
+  const keysSeen = {};
+  const lines = content.split(/\r?\n|\r/);
+  let i = 0;
+
+  while (i < lines.length) {
+    const raw = lines[i];
+    const trimmed = raw.trim();
+
+    // Blank line or full-line comment
+    if (trimmed === '' || trimmed.startsWith('#')) {
+      i++;
+      continue;
+    }
+
+    // Table / array-table — end of top-level scope, stop scanning
+    if (/^\[\[?/.test(trimmed)) {
+      break;
+    }
+
+    // Top-level assignment: bare key = value
+    const keyMatch = trimmed.match(/^([A-Za-z][A-Za-z0-9_-]*)\s*=\s*(.*)$/);
+    if (!keyMatch) {
+      return {
+        ok: false,
+        error: `line ${i + 1}: not a valid top-level assignment: ${trimmed.slice(0, 60)}`,
+      };
+    }
+
+    const key = keyMatch[1];
+    const value = keyMatch[2];
+
+    if (keysSeen[key] !== undefined) {
+      return { ok: false, error: `line ${i + 1}: duplicate top-level key '${key}'` };
+    }
+
+    // Multi-line basic string: """..."""
+    if (value.startsWith('"""')) {
+      const after = value.slice(3);
+      const closeIdx = after.indexOf('"""');
+      if (closeIdx !== -1) {
+        // Closed on same line — check no trailing content except optional comment
+        const trailing = after.slice(closeIdx + 3).trim();
+        if (trailing !== '' && !trailing.startsWith('#')) {
+          return {
+            ok: false,
+            error: `line ${i + 1}: trailing content after """ close: ${trailing.slice(0, 40)}`,
+          };
+        }
+        keysSeen[key] = 'string';
+        i++;
+        continue;
+      }
+      // Scan forward for closing """
+      let j = i + 1;
+      let closed = false;
+      while (j < lines.length) {
+        const idx2 = lines[j].indexOf('"""');
+        if (idx2 !== -1) {
+          const trailing2 = lines[j].slice(idx2 + 3).trim();
+          if (trailing2 !== '' && !trailing2.startsWith('#')) {
+            return {
+              ok: false,
+              error: `line ${j + 1}: trailing content after """ close: ${trailing2.slice(0, 40)}`,
+            };
+          }
+          closed = true;
+          i = j + 1;
+          break;
+        }
+        j++;
+      }
+      if (!closed) {
+        return {
+          ok: false,
+          error: `line ${i + 1}: unterminated triple-quoted basic string (""" never closed)`,
+        };
+      }
+      keysSeen[key] = 'string';
+      continue;
+    }
+
+    // Multi-line literal string: '''...'''
+    if (value.startsWith("'''")) {
+      const after = value.slice(3);
+      const closeIdx = after.indexOf("'''");
+      if (closeIdx !== -1) {
+        const trailing = after.slice(closeIdx + 3).trim();
+        if (trailing !== '' && !trailing.startsWith('#')) {
+          return {
+            ok: false,
+            error: `line ${i + 1}: trailing content after ''' close: ${trailing.slice(0, 40)}`,
+          };
+        }
+        keysSeen[key] = 'string';
+        i++;
+        continue;
+      }
+      let j = i + 1;
+      let closed = false;
+      while (j < lines.length) {
+        const idx2 = lines[j].indexOf("'''");
+        if (idx2 !== -1) {
+          const trailing2 = lines[j].slice(idx2 + 3).trim();
+          if (trailing2 !== '' && !trailing2.startsWith('#')) {
+            return {
+              ok: false,
+              error: `line ${j + 1}: trailing content after ''' close: ${trailing2.slice(0, 40)}`,
+            };
+          }
+          closed = true;
+          i = j + 1;
+          break;
+        }
+        j++;
+      }
+      if (!closed) {
+        return {
+          ok: false,
+          error: `line ${i + 1}: unterminated triple-quoted literal string (''' never closed)`,
+        };
+      }
+      keysSeen[key] = 'string';
+      continue;
+    }
+
+    // Basic string: "..." with standard escapes; must close on same line
+    // and allow only a trailing comment after the closing quote.
+    if (value.startsWith('"')) {
+      const basicMatch = value.match(/^"((?:[^"\\]|\\.)*)"(?:\s*(?:#.*)?)?$/);
+      if (!basicMatch) {
+        return {
+          ok: false,
+          error: `line ${i + 1}: invalid basic string value (unterminated or trailing content): ${value.slice(0, 60)}`,
+        };
+      }
+      keysSeen[key] = 'string';
+      i++;
+      continue;
+    }
+
+    // Literal string: '...' with no escapes; must close on same line
+    if (value.startsWith("'")) {
+      const litMatch = value.match(/^'([^']*)'(?:\s*(?:#.*)?)?$/);
+      if (!litMatch) {
+        return {
+          ok: false,
+          error: `line ${i + 1}: invalid literal string value (unterminated or trailing content): ${value.slice(0, 60)}`,
+        };
+      }
+      keysSeen[key] = 'string';
+      i++;
+      continue;
+    }
+
+    // Any other value is not a string literal (int, bool, array, table, etc.)
+    keysSeen[key] = 'non-string';
+    i++;
+  }
+
+  return { ok: true, keys: keysSeen };
+}
+
+function checkGeminiCommands(cwd, aiTools) {
+  if (aiTools === 'claude') {
+    return {
+      status: PASS,
+      message: 'Gemini commands: N/A (Claude only)',
+      details: [],
+    };
+  }
+
+  const commandsDir = path.join(cwd, '.gemini', 'commands');
+  if (!fs.existsSync(commandsDir)) {
+    return {
+      status: WARN,
+      message: 'Gemini commands: .gemini/commands/ missing',
+      details: ['Run: npx create-sdd-project --upgrade to recreate template commands'],
+    };
+  }
+
+  // readdirSync with withFileTypes so we can filter symlinks before reading.
+  // Symlinks in .gemini/commands/ would make doctor read arbitrary files on
+  // the user's machine — low severity in a local CLI, but worth guarding.
+  const entries = fs
+    .readdirSync(commandsDir, { withFileTypes: true })
+    .filter((e) => e.name.endsWith('.toml'))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  if (entries.length === 0) {
+    return {
+      status: WARN,
+      message: 'Gemini commands: no .toml files in .gemini/commands/',
+      details: ['Gemini CLI slash commands require .toml files. Run: npx create-sdd-project --upgrade'],
+    };
+  }
+
+  const issues = [];
+  let validCount = 0;
+
+  for (const entry of entries) {
+    const file = entry.name;
+    const filePath = path.join(commandsDir, file);
+
+    // Reject symlinks (Dirent can lie about isFile() when followed; use lstat).
+    let lst;
+    try {
+      lst = fs.lstatSync(filePath);
+    } catch (e) {
+      issues.push(`${file}: cannot lstat (${e.code || e.message})`);
+      continue;
+    }
+    if (lst.isSymbolicLink()) {
+      issues.push(`${file}: is a symlink — refusing to follow (security). Delete and run --upgrade to restore template`);
+      continue;
+    }
+    if (!lst.isFile()) {
+      issues.push(`${file}: not a regular file`);
+      continue;
+    }
+
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf8');
+    } catch (e) {
+      issues.push(`${file}: cannot read (${e.code || e.message})`);
+      continue;
+    }
+
+    if (content.trim() === '') {
+      issues.push(`${file}: empty file (Gemini CLI will skip this command silently)`);
+      continue;
+    }
+
+    // Validate using the strict grammar subset for our templates.
+    // Gemini CLI's FileCommandLoader schema is:
+    //   z.object({ prompt: z.string(), description: z.string().optional() })
+    const result = validateTomlCommandFile(content);
+
+    if (!result.ok) {
+      issues.push(`${file}: ${result.error}`);
+      continue;
+    }
+
+    const promptKind = result.keys.prompt;
+    const descriptionKind = result.keys.description;
+
+    if (promptKind === undefined) {
+      issues.push(
+        `${file}: missing required field 'prompt' (Gemini CLI will silently skip this command)`
+      );
+      continue;
+    }
+    if (promptKind !== 'string') {
+      issues.push(
+        `${file}: 'prompt' field must be a string (Gemini CLI requires z.string())`
+      );
+      continue;
+    }
+    if (descriptionKind !== undefined && descriptionKind !== 'string') {
+      issues.push(
+        `${file}: 'description' field is present but is not a string`
+      );
+      continue;
+    }
+
+    validCount++;
+  }
+
+  if (issues.length > 0) {
+    return {
+      status: FAIL,
+      message: `Gemini commands: ${issues.length} invalid TOML file${issues.length > 1 ? 's' : ''}`,
+      details: [
+        ...issues,
+        'Gemini CLI silently skips invalid TOML commands — they will not appear as slash commands in the UI.',
+        'Run: npx create-sdd-project --upgrade to restore template commands.',
+      ],
+    };
+  }
+
+  return {
+    status: PASS,
+    message: `Gemini commands: ${validCount}/${entries.length} valid`,
+    details: [],
+  };
+}
+
 module.exports = {
   runDoctor,
   printResults,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-sdd-project",
-  "version": "0.16.8",
+  "version": "0.16.9",
   "description": "Create a new SDD DevFlow project with AI-assisted development workflow",
   "bin": {
     "create-sdd-project": "bin/cli.js"