@orderful/droid 0.48.0 → 0.51.0

package/src/tools/codex/skills/codex/scripts/normalize-frontmatter.ts

@@ -0,0 +1,402 @@
+#!/usr/bin/env bun
+/**
+ * codex normalize-frontmatter
+ *
+ * Normalizes YAML frontmatter format in codex markdown files to prevent
+ * unnecessary diffs from yaml.safe_dump() in the codex repo's fix-frontmatter
+ * workflow.
+ *
+ * Usage:
+ *   droid config --get tools.codex | droid exec codex normalize-frontmatter --config -
+ *
+ * Options:
+ *   --config <json>   Config with codex_repo path (required)
+ *   --all             Process all .md files, not just uncommitted ones
+ *
+ * What it normalizes:
+ *   - Flatten multiline scalars (>, |, >-, |-) into single-line quoted strings
+ *   - Quote string values containing special characters (em dashes, colons, accents, @, arrows)
+ *   - Consistent list indentation (- item, not   - item under a key)
+ *   - Unquote dates that are YYYY-MM-DD
+ *
+ * What it does NOT do:
+ *   - Add missing required fields
+ *   - Validate field values or enums
+ *   - Reorder fields
+ *
+ * Output (JSON):
+ *   { "success": true, "files_normalized": ["path/to/file.md"], "issues": [] }
+ */
+
+import { execSync } from 'child_process';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+
+interface Config {
+  codex_repo: string;
+}
+
+interface Result {
+  success: boolean;
+  files_normalized: string[];
+  issues: string[];
+  error?: string;
+}
+
+function parseArgs(args: string[]): { config: Config | null; all: boolean } {
+  let config: Config | null = null;
+  let all = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--config' && args[i + 1]) {
+      const configArg = args[++i];
+      if (configArg === '-') {
+        const stdin = readFileSync(0, 'utf-8').trim();
+        config = JSON.parse(stdin) as Config;
+      } else {
+        config = JSON.parse(configArg) as Config;
+      }
+    } else if (arg === '--all') {
+      all = true;
+    }
+  }
+
+  return { config, all };
+}
+
+function expandPath(p: string): string {
+  if (p.startsWith('~/')) {
+    return p.replace('~', process.env.HOME || '');
+  }
+  return p;
+}
+
+/**
+ * Characters that require quoting in YAML values.
+ * Matches: em dash, en dash, accented chars, @, arrows, leading/trailing spaces,
+ * colons followed by space, # preceded by space.
+ */
+const NEEDS_QUOTING = /[\u2013\u2014\u2018\u2019\u201c\u201d\u00e0-\u00ff\u0100-\u017f@\u2190-\u21ff\u2260]|:\s|^\s|\s$|\s#|^[{[]|[{}[\]],?$/;
+
+/** Date pattern: YYYY-MM-DD */
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * Extract frontmatter block from markdown content.
+ * Returns the frontmatter lines (without delimiters) and the rest of the content.
+ */
+export function extractFrontmatter(content: string): {
+  frontmatter: string[] | null;
+  body: string;
+} {
+  const lines = content.split('\n');
+
+  if (lines[0] !== '---') {
+    return { frontmatter: null, body: content };
+  }
+
+  let endIndex = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === '---') {
+      endIndex = i;
+      break;
+    }
+  }
+
+  if (endIndex === -1) {
+    return { frontmatter: null, body: content };
+  }
+
+  return {
+    frontmatter: lines.slice(1, endIndex),
+    // Preserve everything after closing --- including the newline separator
+    body: '\n' + lines.slice(endIndex + 1).join('\n'),
+  };
+}
+
+/**
+ * Check if a string value needs quoting for YAML safety.
+ */
+export function needsQuoting(value: string): boolean {
+  if (value === '' || value === 'true' || value === 'false' || value === 'null') return false;
+  if (DATE_PATTERN.test(value)) return false;
+  if (NEEDS_QUOTING.test(value)) return true;
+  // Values starting with special YAML chars
+  if (/^[*&!%>|'"]/.test(value)) return true;
+  // Values that look like numbers but shouldn't be
+  if (/^0\d/.test(value) && !/^0x/i.test(value)) return true;
+  return false;
+}
+
+/**
+ * Quote a YAML string value using double quotes, escaping internal quotes.
+ */
+export function quoteValue(value: string): string {
+  // Already properly quoted
+  if ((value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))) {
+    return value;
+  }
+  const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  return `"${escaped}"`;
+}
+
+/**
+ * Unquote a date value if it's YYYY-MM-DD wrapped in quotes.
+ */
+export function unquoteDate(value: string): string {
+  const inner = value.replace(/^["'](.*)["']$/, '$1');
+  if (DATE_PATTERN.test(inner)) {
+    return inner;
+  }
+  return value;
+}
+
+/**
+ * Normalize frontmatter lines using a line-by-line state machine.
+ * No YAML library used — that's the whole point.
+ */
+export function normalizeFrontmatter(lines: string[]): string[] {
+  const result: string[] = [];
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    // Blank line — preserve
+    if (line.trim() === '') {
+      result.push(line);
+      i++;
+      continue;
+    }
+
+    // Comment line — preserve
+    if (line.trimStart().startsWith('#')) {
+      result.push(line);
+      i++;
+      continue;
+    }
+
+    // Key-value line: detect "key: value" or "key:" (for multiline/list)
+    const kvMatch = line.match(/^(\s*)([\w][\w.-]*)\s*:\s*(.*)$/);
+    if (!kvMatch) {
+      // List item at root or continuation — normalize indentation
+      const listMatch = line.match(/^(\s*)- (.*)$/);
+      if (listMatch) {
+        result.push(`${listMatch[1]}- ${normalizeScalarValue(listMatch[2])}`);
+      } else {
+        result.push(line);
+      }
+      i++;
+      continue;
+    }
+
+    const [, indent, key, rawValue] = kvMatch;
+
+    // Case 1: Multiline scalar indicator (>, |, >-, |-)
+    if (/^[>|][-+]?\s*$/.test(rawValue)) {
+      // Collect continuation lines
+      const continuationLines: string[] = [];
+      const baseIndentLen = indent.length + 2; // standard YAML continuation indent
+      i++;
+
+      while (i < lines.length) {
+        const nextLine = lines[i];
+        // Empty line within multiline block
+        if (nextLine.trim() === '') {
+          continuationLines.push('');
+          i++;
+          continue;
+        }
+        // Check if indented beyond the key (continuation)
+        const nextIndent = nextLine.match(/^(\s*)/)?.[1].length ?? 0;
+        if (nextIndent >= baseIndentLen) {
+          continuationLines.push(nextLine.trim());
+          i++;
+        } else {
+          break;
+        }
+      }
+
+      // Flatten into single-line value
+      const folded = rawValue.startsWith('|')
+        ? continuationLines.join(' ') // literal: join with space for single-line
+        : continuationLines.filter(l => l !== '').join(' ');
+
+      const trimmed = folded.trim();
+      if (needsQuoting(trimmed)) {
+        result.push(`${indent}${key}: ${quoteValue(trimmed)}`);
+      } else {
+        result.push(`${indent}${key}: ${trimmed}`);
+      }
+      continue;
+    }
+
+    // Case 2: Key with no value — next lines are a list or nested map
+    if (rawValue === '') {
+      result.push(`${indent}${key}:`);
+      i++;
+      continue;
+    }
+
+    // Case 3: Regular key: value
+    let value = rawValue.trim();
+
+    // Unquote dates
+    value = unquoteDate(value);
+
+    // Quote values that need it (but aren't already quoted)
+    if (needsQuoting(value) && !((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
+      value = quoteValue(value);
+    }
+
+    result.push(`${indent}${key}: ${value}`);
+    i++;
+  }
+
+  return result;
+}
+
+/**
+ * Normalize a scalar value that appears in a list item or elsewhere.
+ */
+function normalizeScalarValue(value: string): string {
+  let v = unquoteDate(value.trim());
+  if (needsQuoting(v) && !((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))) {
+    v = quoteValue(v);
+  }
+  return v;
+}
+
+/**
+ * Normalize the frontmatter in a markdown file.
+ * Returns the normalized content, or null if no changes needed.
+ */
+export function normalizeFile(content: string): string | null {
+  const { frontmatter, body } = extractFrontmatter(content);
+
+  if (!frontmatter) {
+    return null; // No frontmatter to normalize
+  }
+
+  const normalized = normalizeFrontmatter(frontmatter);
+
+  // Check if anything changed
+  const originalBlock = frontmatter.join('\n');
+  const normalizedBlock = normalized.join('\n');
+
+  if (originalBlock === normalizedBlock) {
+    return null; // No changes needed
+  }
+
+  return `---\n${normalizedBlock}\n---${body}`;
+}
+
+/**
+ * Get list of markdown files with uncommitted changes.
+ */
+function getChangedFiles(cwd: string): string[] {
+  try {
+    // Both staged and unstaged changes, plus untracked files
+    const output = execSync(
+      'git diff --name-only HEAD 2>/dev/null; git diff --name-only --cached 2>/dev/null; git ls-files --others --exclude-standard 2>/dev/null',
+      { cwd, encoding: 'utf-8' }
+    );
+
+    const files = output
+      .split('\n')
+      .map(f => f.trim())
+      .filter(f => f.endsWith('.md'))
+      .filter(f => f !== '')
+      // Deduplicate
+      .filter((f, i, arr) => arr.indexOf(f) === i);
+
+    return files;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Get all markdown files in the repo.
+ */
+function getAllMarkdownFiles(cwd: string): string[] {
+  try {
+    const output = execSync(
+      'git ls-files "*.md" 2>/dev/null',
+      { cwd, encoding: 'utf-8' }
+    );
+    return output.split('\n').map(f => f.trim()).filter(f => f !== '');
+  } catch {
+    return [];
+  }
+}
+
+// Main — only run when executed directly (not imported by tests)
+export function main(): void {
+  const args = process.argv.slice(2);
+  const { config, all } = parseArgs(args);
+
+  if (!config) {
+    console.log(JSON.stringify({
+      success: false,
+      files_normalized: [],
+      issues: [],
+      error: 'Missing --config. Usage: droid config --get tools.codex | droid exec codex normalize-frontmatter --config -',
+    }));
+    process.exit(1);
+  }
+
+  if (!config.codex_repo) {
+    console.log(JSON.stringify({
+      success: false,
+      files_normalized: [],
+      issues: [],
+      error: 'Missing codex_repo in config',
+    }));
+    process.exit(1);
+  }
+
+  const cwd = expandPath(config.codex_repo);
+
+  if (!existsSync(cwd)) {
+    console.log(JSON.stringify({
+      success: false,
+      files_normalized: [],
+      issues: [],
+      error: `Codex repo not found at ${cwd}`,
+    }));
+    process.exit(1);
+  }
+
+  const files = all ? getAllMarkdownFiles(cwd) : getChangedFiles(cwd);
+  const result: Result = {
+    success: true,
+    files_normalized: [],
+    issues: [],
+  };
+
+  for (const file of files) {
+    const fullPath = `${cwd}/${file}`;
+    try {
+      if (!existsSync(fullPath)) continue;
+
+      const content = readFileSync(fullPath, 'utf-8');
+      const normalized = normalizeFile(content);
+
+      if (normalized !== null) {
+        writeFileSync(fullPath, normalized, 'utf-8');
+        result.files_normalized.push(file);
+      }
+    } catch (err: unknown) {
+      const error = err as { message?: string };
+      result.issues.push(`${file}: ${error.message || 'Unknown error'}`);
+    }
+  }
+
+  console.log(JSON.stringify(result, null, 2));
+}
+
+if (import.meta.main) {
+  main();
+}

package/src/tools/comments/TOOL.yaml

@@ -2,6 +2,8 @@ name: comments
 description: "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration."
 version: 0.3.7
 status: beta
+audience:
+  - all
 
 includes:
   skills:

package/src/tools/droid/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "droid",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Core droid meta-skill for update awareness, tool discovery, and usage help. Checks for updates, helps users find tools, and answers 'how do I...' questions about droid workflows.",
   "author": {
     "name": "Orderful",

package/src/tools/droid/TOOL.yaml

@@ -1,7 +1,9 @@
 name: droid
 description: "Core droid meta-skill for update awareness, tool discovery, and usage help. Checks for updates, helps users find tools, and answers 'how do I...' questions about droid workflows."
-version: 0.7.1
+version: 0.7.2
 status: beta
+audience:
+  - engineering
 
 # System tool - always stays current regardless of auto-update settings
 system: true

package/src/tools/droid/skills/droid/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: droid
-description: "Core droid meta-skill for updates, tool discovery, usage help, and skill overrides. Use when checking for droid updates, discovering available tools, answering 'how do I...' questions about droid workflows, or customizing skill behaviour. User prompts like 'any droid updates?', 'what tools do I have?', 'what tools do you have?', 'remind me what tools you have', 'hey droid what can you do', 'how do I add context?', 'remind me how to use codex', 'what's the best way to start a session?', 'customize brain search', 'create an override for brain'."
+description: "Core droid meta-skill for updates, tool discovery, usage help, skill overrides, and skill review. Use when checking for droid updates, discovering available tools, answering 'how do I...' questions about droid workflows, customizing skill behaviour, or reviewing a contributed skill. User prompts like 'any droid updates?', 'what tools do I have?', 'what tools do you have?', 'remind me what tools you have', 'hey droid what can you do', 'how do I add context?', 'remind me how to use codex', 'what's the best way to start a session?', 'customize brain search', 'create an override for brain', 'review this skill', 'droid review ./my-skill'."
 alwaysApply: true
-allowed-tools: [Bash, Read, Write]
+allowed-tools: [Bash, Read, Write, Glob, Grep]
 ---
 
 # Droid
@@ -69,6 +69,7 @@ cat ~/.droid/config.yaml
 | Review code | `/code-review` |
 | Capture a decision | `/codex decision {summary}` |
 | Update project context | `/project update` |
+| Create a new droid tool | `/droid new {name}` or `/droid new {name} --from {path}` |
 
 ## Response Guidelines
 
@@ -89,6 +90,51 @@ When answering "how do I..." questions:
 2. `/codex search {topic}` - Find relevant org knowledge (if needed)
 3. Then start working with full context
 
+## New Tool
+
+Create a new droid tool, optionally starting from an existing skill/agent file. The droid skill for contributing to droid.
+
+**When:** User says `/droid new {tool-name}` or `/droid new {tool-name} --from {path}`
+
+**Usage:**
+```
+/droid new {tool-name}                            # scaffold from scratch
+/droid new {tool-name} --from path/to/file        # import with explicit path
+/droid new {tool-name} path/to/file               # same — path detected as import source
+```
+
+Accepts `.skill`, `.zip`, `.md` files, or directories. Users can also just drop a file into the chat after running `/droid new {tool-name}` and it will be picked up as the import source.
+
+**Flow:**
+
+1. **Import** (if `--from` provided) — Determine input type:
+   - `.skill` or `.zip` → extract to temp directory, locate SKILL.md or agent .md inside
+   - Directory → use directly
+   - Single `.md` file → determine if it's a skill (has frontmatter with `name`/`description`) or an agent
+   - No `--from` → scaffold blank SKILL.md from template
+2. **Transform** — Massage imported content to droid standards:
+   - Multiline YAML descriptions (`>`, `>-`, `|`) → rewrite as single-line quoted string
+   - Missing `allowed-tools` → analyse content for tool usage, add appropriate list
+   - Description missing "Use when" / "User prompts like" pattern → rewrite to match
+   - `name` not kebab-case → fix it
+   - Add missing frontmatter fields (`globs: []`, `alwaysApply: false`)
+3. **Security scan** — Flag issues. High-severity (prompt injection patterns, encoded content) blocks. Medium-severity (Bash without justification, external URLs) requires acknowledgement.
+4. **Collect metadata** — Always ask for `audience`. Confirm tool name and description.
+5. **Scaffold tool** — Create the full tool structure in `src/tools/{tool-name}/`:
+   - `TOOL.yaml` with name, description, version `0.1.0`, status `beta`, audience
+   - `skills/{skill-name}/SKILL.md` (+ `references/` if present)
+   - `agents/{agent-name}.md` if importing an agent
+   - Add changeset: `.changeset/{tool-name}-initial.md`
+6. **Open PR** — Create branch `contrib/{tool-name}`, commit, push, open PR.
+
+Present a summary with droid eyes `[● ●]` showing what was imported/transformed and what needs input. See `references/new-tool-workflow.md` for detailed validation rules, security patterns, and PR template.
+
+**Key rules:**
+- Fix what can be fixed automatically (formatting, frontmatter, descriptions)
+- Only block on things that need human judgement (security, audience)
+- New tools start at version `0.1.0` with status `beta`
+- Always create a changeset with package name `"@orderful/droid"`
+
 ## Skill Overrides
 
 Users can customize skill behaviour by creating override files in `~/.droid/skill_overrides/`.