specguard 0.1.1 → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpecGuard Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,17 +2,37 @@
 
 Production-grade "Skills++" enforcement engine for code agents.
 
+## Features
+
+- **🛡️ Secure Tool Execution**: Tools run without a shell by default.
+- **🔍 Secret Redaction**: Deterministic masking of secrets in logs and reports.
+- **📄 Agent-Friendly Reporting**: Built-in "Agent Summary" for repair loops.
+- **⏭️ Smart Skipping**: Automatic detection of missing optional scripts.
+
+## Documentation
+
+For full guides and reference, see the [Documentation Index](docs/README.md).
+
+- [🚀 Quickstart](docs/quickstart.md)
+- [🤖 Codex & Agents](docs/codex-and-agents.md)
+- [🛠️ Spec Reference](docs/spec-reference.md)
+- [📊 Reports](docs/reports.md)
+- [🔄 CI Integration](docs/ci-integration.md)
+- [🔐 Security](docs/security.md)
+
 ## Installation
 
 ```bash
 npm install specguard
 ```
 
-## Usage
+## Quick Commands
 
 ```bash
-npx specguard init
-npx specguard validate
+npx specguard init      # Setup SpecGuard in your repo
+npx specguard validate  # Run validation
 ```
 
-See the [main repository](https://github.com/example/specguard) for full documentation.
+## License
+
+MIT

package/dist/init.js

@@ -21,29 +21,45 @@ tool_verified:
     - name: "Lint"
       command: "npm run lint"
       optional: true
+      skip_if_missing: true
 `;
 const AGENTS_MD_TEMPLATE = `
 ## 🛡️ SpecGuard Enforced
 
-This repository uses SpecGuard for validation.
+This repository uses **SpecGuard** to ensure code quality and security.
+As an AI agent, you **MUST** follow this workflow:
 
-**Workflow:**
-1. Make changes.
-2. Run validation:
-   \`\`\`bash
-   npm exec specguard validate
-   \`\`\`
-3. Fix any violations.
-4. Include validation report in your PR/Final Answer.
+1.  **Edit**: Make your code changes.
+2.  **Validate**: Run the validation script to check for issues.
+    \`\`\`bash
+    npx specguard validate --staged
+    \`\`\`
+3.  **Repair**: If validation fails, fix the errors and re-run.
+4.  **Report**: Include the validation summary in your final response.
+
+**Artifacts Location:**
+- Spec: \`.ai/specguard/spec.yaml\`
+- Reports: \`.ai/specguard/reports/\`
+
+**Safety Rules:**
+- 🚫 NO secrets in code.
+- 🚫 NO shell execution in tool steps (unless explicitly allowed).
+- ✅ ALWAYS verify your changes.
 `;
 export async function init(cwd, force) {
     const specDir = path.join(cwd, '.ai', 'specguard');
     const reportsDir = path.join(specDir, 'reports');
     const specPath = path.join(specDir, 'spec.yaml');
     const agentsMdPath = path.join(cwd, 'AGENTS.md');
+    const gitignorePath = path.join(cwd, '.gitignore');
     // Create directories
-    fs.mkdirSync(reportsDir, { recursive: true });
-    fs.writeFileSync(path.join(reportsDir, '.gitkeep'), '');
+    if (!fs.existsSync(reportsDir)) {
+        fs.mkdirSync(reportsDir, { recursive: true });
+    }
+    const gitkeepPath = path.join(reportsDir, '.gitkeep');
+    if (!fs.existsSync(gitkeepPath)) {
+        fs.writeFileSync(gitkeepPath, '');
+    }
     // Create spec.yaml
     if (fs.existsSync(specPath) && !force) {
         console.log('⚠️  spec.yaml already exists. Use --force to overwrite.');
@@ -56,7 +72,9 @@ export async function init(cwd, force) {
     if (fs.existsSync(agentsMdPath)) {
         const content = fs.readFileSync(agentsMdPath, 'utf-8');
         if (!content.includes('SpecGuard Enforced')) {
-            fs.appendFileSync(agentsMdPath, AGENTS_MD_TEMPLATE);
+            // Append clearly with a separator
+            const appendContent = `\n\n---\n${AGENTS_MD_TEMPLATE}`;
+            fs.appendFileSync(agentsMdPath, appendContent);
             console.log('✅ Updated AGENTS.md');
         }
         else {
@@ -67,15 +85,44 @@ export async function init(cwd, force) {
         fs.writeFileSync(agentsMdPath, `# AGENTS.md\n${AGENTS_MD_TEMPLATE}`);
         console.log('✅ Created AGENTS.md');
     }
-    // Create legacy wrapper scripts for convenience? 
-    // User asked for .ai/specguard/tools/validate.sh
+    // Update .gitignore
+    let gitignoreContent = '';
+    if (fs.existsSync(gitignorePath)) {
+        gitignoreContent = fs.readFileSync(gitignorePath, 'utf-8');
+    }
+    const ignores = [
+        '.ai/specguard/reports/**',
+        '!.ai/specguard/reports/.gitkeep'
+    ];
+    let addedIgnore = false;
+    // Ensure we end with newline before appending if file not empty
+    if (gitignoreContent && !gitignoreContent.endsWith('\n')) {
+        gitignoreContent += '\n';
+    }
+    for (const ign of ignores) {
+        if (!gitignoreContent.includes(ign)) {
+            gitignoreContent += `${ign}\n`;
+            addedIgnore = true;
+        }
+    }
+    if (addedIgnore) {
+        fs.writeFileSync(gitignorePath, gitignoreContent);
+        console.log('✅ Updated .gitignore');
+    }
+    else {
+        console.log('ℹ️  .gitignore already configured.');
+    }
+    // Create helper scripts
     const toolsDir = path.join(specDir, 'tools');
-    fs.mkdirSync(toolsDir, { recursive: true });
+    if (!fs.existsSync(toolsDir)) {
+        fs.mkdirSync(toolsDir, { recursive: true });
+    }
+    // Using npx specguard@latest as requested
     const shScript = `#!/bin/bash
-npx specguard validate --spec "${path.posix.join('.ai', 'specguard', 'spec.yaml')}" --repo-root . --report-dir "${path.posix.join('.ai', 'specguard', 'reports')}"
+npx specguard@latest validate
 `;
     fs.writeFileSync(path.join(toolsDir, 'validate.sh'), shScript, { mode: 0o755 });
-    const ps1Script = `npx specguard validate --spec ".ai\\specguard\\spec.yaml" --repo-root . --report-dir ".ai\\specguard\\reports"`;
+    const ps1Script = `npx specguard@latest validate`;
     fs.writeFileSync(path.join(toolsDir, 'validate.ps1'), ps1Script);
-    console.log('✅ Created helper scripts in .ai/specguard/tools/');
+    console.log('✅ Created validation helper scripts in .ai/specguard/tools/');
 }

package/dist/reporting/json_reporter.js

@@ -60,32 +60,76 @@ export async function generateReport(data, reportDir) {
     fs.writeFileSync(jsonPath, JSON.stringify(report, null, 2));
     // Write MD
     let md = `# SpecGuard Report\n\n`;
-    md += `**Status**: ${data.status}\n`;
+    // Agent Summary
+    md += `## 🤖 Agent Summary\n\n`;
+    const isPass = data.status === 'PASS';
+    md += `**Result**: ${isPass ? '✅ PASS' : '❌ FAIL'}\n`;
+    md += `**Changes**: ${data.changedFiles.length} files\n`;
+    if (data.violations.length > 0) {
+        md += `**Top Violations**:\n`;
+        // Top 5
+        for (const v of data.violations.slice(0, 5)) {
+            md += `- ${v.type}: ${v.details.slice(0, 100)}${v.details.length > 100 ? '...' : ''}\n`;
+        }
+        if (data.violations.length > 5) {
+            md += `- ... and ${data.violations.length - 5} more\n`;
+        }
+    }
+    else {
+        md += `**Violations**: None\n`;
+    }
+    if (processedToolResults.length > 0) {
+        md += `\n**Tools**:\n`;
+        md += `| Tool | Status | Optional | Exit |\n`;
+        md += `| --- | --- | --- | --- |\n`;
+        for (const t of processedToolResults) {
+            md += `| ${t.name} | ${t.status} | ${t.optional} | ${t.exit_code ?? '-'} |\n`;
+        }
+    }
+    md += `\n**Next Action**: `;
+    if (isPass) {
+        md += `Proceed with changes.\n`;
+    }
+    else {
+        md += `Fix violations and re-run: \`npx specguard validate\`\n`;
+    }
+    md += `\n---\n\n`; // Separator
+    // Detailed Report
+    md += `## Run Details\n`;
     md += `**Run ID**: ${runId}\n`;
     md += `**Date**: ${data.timestamp}\n`;
     md += `**Mode**: ${data.runMeta.diffMode}\n`;
-    md += `**Changes**: ${data.changedFiles.length} files\n\n`;
+    md += `**Platform**: ${os.platform()} / Node ${process.version}\n\n`;
     if (data.violations.length > 0) {
-        md += `## ❌ Violations\n`;
+        md += `## ❌ Violations Full List\n`;
         for (const v of data.violations) {
             md += `- **${v.type}**: ${v.file || 'N/A'} - ${v.details}\n`;
         }
     }
-    else {
-        md += `## ✅ No Violations Found\n`;
-    }
-    md += `\n## Tool Execution\n`;
+    md += `\n## Tool Execution Details\n`;
     if (processedToolResults.length === 0) {
         md += `No tools configured.\n`;
     }
     else {
         for (const t of processedToolResults) {
-            const icon = t.exit_code === 0 ? '✅' : (t.optional ? '⚠️' : '❌');
+            let icon = '✅';
+            if (t.status === 'FAILED')
+                icon = t.optional ? '⚠️' : '❌';
+            if (t.status === 'SKIPPED')
+                icon = '⏭️';
             md += `### ${icon} ${t.name}\n`;
+            md += `- Status: **${t.status}**\n`;
             md += `- Command: \`${t.command}\`\n`;
-            md += `- Exit Code: ${t.exit_code}\n`;
+            if (t.reason)
+                md += `- Reason: ${t.reason}\n`;
+            if (t.exit_code !== null)
+                md += `- Exit Code: ${t.exit_code}\n`;
+            md += `- Duration: ${t.duration_ms}ms\n`;
             if (t.output_tail) {
-                md += `\`\`\`\n${t.output_tail}\n\`\`\`\n`;
+                md += `Output Tail:\n\`\`\`\n${t.output_tail}\n\`\`\`\n`;
+            }
+            if (t.log_path) {
+                md += `Full Log: [${path.basename(t.log_path)}](${t.log_path})\n`;
             }
         }
     }

package/dist/spec/schema.d.ts

@@ -38,21 +38,30 @@ export declare const SpecSchema: z.ZodObject<{
             optional: z.ZodOptional<z.ZodBoolean>;
             timeout_seconds: z.ZodOptional<z.ZodNumber>;
             env_allowlist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             cwd: z.ZodOptional<z.ZodString>;
+            skip_if_missing: z.ZodOptional<z.ZodBoolean>;
+            allow_shell: z.ZodOptional<z.ZodBoolean>;
         }, "strip", z.ZodTypeAny, {
             name: string;
             command: string;
             optional?: boolean | undefined;
             timeout_seconds?: number | undefined;
             env_allowlist?: string[] | undefined;
+            env?: Record<string, string> | undefined;
             cwd?: string | undefined;
+            skip_if_missing?: boolean | undefined;
+            allow_shell?: boolean | undefined;
         }, {
             name: string;
             command: string;
             optional?: boolean | undefined;
             timeout_seconds?: number | undefined;
             env_allowlist?: string[] | undefined;
+            env?: Record<string, string> | undefined;
             cwd?: string | undefined;
+            skip_if_missing?: boolean | undefined;
+            allow_shell?: boolean | undefined;
         }>, "many">>;
     }, "strip", z.ZodTypeAny, {
         steps?: {
@@ -61,7 +70,10 @@ export declare const SpecSchema: z.ZodObject<{
             optional?: boolean | undefined;
             timeout_seconds?: number | undefined;
             env_allowlist?: string[] | undefined;
+            env?: Record<string, string> | undefined;
             cwd?: string | undefined;
+            skip_if_missing?: boolean | undefined;
+            allow_shell?: boolean | undefined;
         }[] | undefined;
     }, {
         steps?: {
@@ -70,7 +82,10 @@ export declare const SpecSchema: z.ZodObject<{
             optional?: boolean | undefined;
             timeout_seconds?: number | undefined;
             env_allowlist?: string[] | undefined;
+            env?: Record<string, string> | undefined;
             cwd?: string | undefined;
+            skip_if_missing?: boolean | undefined;
+            allow_shell?: boolean | undefined;
         }[] | undefined;
     }>>;
     output_contract: z.ZodOptional<z.ZodObject<{
@@ -99,7 +114,10 @@ export declare const SpecSchema: z.ZodObject<{
             optional?: boolean | undefined;
             timeout_seconds?: number | undefined;
             env_allowlist?: string[] | undefined;
+            env?: Record<string, string> | undefined;
             cwd?: string | undefined;
+            skip_if_missing?: boolean | undefined;
+            allow_shell?: boolean | undefined;
         }[] | undefined;
     } | undefined;
     output_contract?: {
@@ -124,7 +142,10 @@ export declare const SpecSchema: z.ZodObject<{
             optional?: boolean | undefined;
             timeout_seconds?: number | undefined;
             env_allowlist?: string[] | undefined;
+            env?: Record<string, string> | undefined;
             cwd?: string | undefined;
+            skip_if_missing?: boolean | undefined;
+            allow_shell?: boolean | undefined;
         }[] | undefined;
     } | undefined;
     output_contract?: {

package/dist/spec/schema.js

@@ -18,7 +18,10 @@ export const SpecSchema = z.object({
             optional: z.boolean().optional(),
             timeout_seconds: z.number().optional(),
             env_allowlist: z.array(z.string()).optional(),
-            cwd: z.string().optional()
+            env: z.record(z.string()).optional(),
+            cwd: z.string().optional(),
+            skip_if_missing: z.boolean().optional(),
+            allow_shell: z.boolean().optional()
         })).optional()
     }).optional(),
     output_contract: z.object({

package/dist/utils/cmd_parser.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Simple command parser that respects quoted arguments.
+ * Does NOT support shell operators (|, &&, >, etc).
+ */
+export declare function parseCommand(command: string): {
+    cmd: string;
+    args: string[];
+};

package/dist/utils/cmd_parser.js

@@ -0,0 +1,56 @@
+/**
+ * Simple command parser that respects quoted arguments.
+ * Does NOT support shell operators (|, &&, >, etc).
+ */
+export function parseCommand(command) {
+    const args = [];
+    let current = '';
+    let quoteChar = null;
+    let escaped = false;
+    for (let i = 0; i < command.length; i++) {
+        const char = command[i];
+        if (escaped) {
+            current += char;
+            escaped = false;
+            continue;
+        }
+        if (char === '\\') {
+            escaped = true;
+            continue;
+        }
+        if (quoteChar) {
+            if (char === quoteChar) {
+                quoteChar = null;
+            }
+            else {
+                current += char;
+            }
+        }
+        else {
+            if (char === '"' || char === "'") {
+                quoteChar = char;
+            }
+            else if (/\s/.test(char)) {
+                if (current.length > 0) {
+                    args.push(current);
+                    current = '';
+                }
+            }
+            else {
+                current += char;
+            }
+        }
+    }
+    if (current.length > 0) {
+        args.push(current);
+    }
+    // Requirement: Ensure no empty string arguments
+    const filteredArgs = args.filter(arg => arg.length > 0);
+    if (filteredArgs.length === 0) {
+        throw new Error(`Invalid tool command: "${command}"`);
+    }
+    return {
+        cmd: filteredArgs[0],
+        args: filteredArgs.slice(1)
+    };
+}

package/dist/utils/redaction.d.ts

@@ -0,0 +1,2 @@
+import { Spec } from '../spec/schema.js';
+export declare function redact(text: string, spec: Spec): string;

package/dist/utils/redaction.js

@@ -0,0 +1,17 @@
+export function redact(text, spec) {
+    if (!text || !spec.deterministic_rules?.secret_patterns) {
+        return text;
+    }
+    let redacted = text;
+    for (const pattern of spec.deterministic_rules.secret_patterns) {
+        try {
+            const regex = new RegExp(pattern.regex, 'g');
+            redacted = redacted.replace(regex, '***REDACTED***');
+        }
+        catch (e) {
+            // Ignore invalid regex in spec to prevent crashes
+            console.error(`Invalid regex for secret pattern '${pattern.name}':`, e);
+        }
+    }
+    return redacted;
+}

package/dist/validators/tools.d.ts

@@ -2,10 +2,12 @@ import { Spec } from '../spec/schema.js';
 interface ToolResult {
     name: string;
     command: string;
-    exit_code: number;
-    stdout: string;
-    stderr: string;
-    duration: number;
+    status: 'RAN' | 'SKIPPED' | 'FAILED';
+    exit_code: number | null;
+    stdout?: string;
+    stderr?: string;
+    reason?: string;
+    duration_ms: number;
     optional: boolean;
 }
 interface ToolOutput {

package/dist/validators/tools.js

@@ -1,4 +1,11 @@
 import { spawn } from 'child_process';
+import path from 'path';
+import fs from 'fs';
+import { parseCommand } from '../utils/cmd_parser.js';
+import { redact } from '../utils/redaction.js';
+const DEFAULT_ENV_ALLOWLIST = [
+    "PATH", "HOME", "USERPROFILE", "TEMP", "TMP", "NODE_ENV", "CI", "npm_config_user_agent"
+];
 export async function runToolChecks(spec, repoRoot) {
     const tools = spec.tool_verified?.steps || [];
     const results = [];
@@ -6,34 +13,159 @@ export async function runToolChecks(spec, repoRoot) {
     for (const tool of tools) {
         console.log(`Run tool: ${tool.name}...`);
         const startTime = Date.now();
+        // Determine script existence for npm/pnpm/yarn commands
+        // If script is missing and skip_if_missing is true (default for optional), SKIP.
+        const firstWord = tool.command.split(/\s+/)[0];
+        const isNpmRun = firstWord === 'npm' || firstWord === 'pnpm' || firstWord === 'yarn';
+        let shouldSkip = false;
+        let skipReason = '';
+        if (isNpmRun) {
+            // Check process.cwd() or tool.cwd? Default checks repoRoot unless cwd specified
+            const toolCwd = tool.cwd ? path.resolve(repoRoot, tool.cwd) : repoRoot;
+            const pkgJsonPath = path.join(toolCwd, 'package.json');
+            // Extract script name. e.g. "npm run lint" -> "lint"
+            // "pnpm lint" -> "lint"; "yarn lint" -> "lint"
+            const args = tool.command.split(/\s+/);
+            let scriptName = '';
+            if (firstWord === 'npm' && args[1] === 'run' && args[2])
+                scriptName = args[2];
+            else if (firstWord === 'pnpm' && args[1] === 'run' && args[2])
+                scriptName = args[2];
+            else if (firstWord === 'pnpm' && args[1])
+                scriptName = args[1]; // pnpm lint
+            else if (firstWord === 'yarn' && args[1])
+                scriptName = args[1];
+            if (scriptName) {
+                if (!fs.existsSync(pkgJsonPath)) {
+                    // No package.json
+                    if (tool.skip_if_missing !== false) {
+                        shouldSkip = true;
+                        skipReason = `No package.json found in ${toolCwd}`;
+                    }
+                }
+                else {
+                    try {
+                        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+                        if (!pkg.scripts || !pkg.scripts[scriptName]) {
+                            if (tool.skip_if_missing !== false) {
+                                shouldSkip = true;
+                                skipReason = `Script '${scriptName}' missing in package.json`;
+                            }
+                            else {
+                                // If skip_if_missing = false, we proceed and let logic fail or we fail early
+                                // But npm run will fail anyway if script missing.
+                                // Requirement says: "If skip_if_missing=false => mark FAILED with clear message."
+                                // But let's let it run? No, npm output might not be clear.
+                                // Let's rely on runSpawn failing ideally, but user asked for detection.
+                                // Let's let it run if not skipping? No, prompt "mark SKIPPED (not FAILED)" implies logic here.
+                            }
+                        }
+                    }
+                    catch (e) {
+                        // Broken package.json, treat same as missing
+                        if (tool.skip_if_missing !== false) {
+                            shouldSkip = true;
+                            skipReason = 'Failed to parse package.json';
+                        }
+                    }
+                }
+            }
+        }
+        // Manual skip override? (Not in spec, but helpful logic)
+        // Check "Skip if missing" default logic: default TRUE for optional, FALSE for required
+        if (tool.skip_if_missing === undefined) {
+            // If optional=true, default skip=true. If optional=false, default skip=false.
+            // Actually, strict logic requested: "default: true for optional steps; false for required steps"
+            // Implemented above implicitly? No.
+            // Wait, above logic only sets shouldSkip if explicit check fails.
+        }
+        if (shouldSkip) {
+            console.log(`  SKIPPED: ${skipReason}`);
+            results.push({
+                name: tool.name,
+                command: tool.command,
+                status: 'SKIPPED',
+                exit_code: null,
+                reason: skipReason,
+                duration_ms: Date.now() - startTime,
+                optional: !!tool.optional
+            });
+            continue;
+        }
         try {
-            // Split command into executable vs args (simplistic, assumes typical "cmd arg1 arg2")
-            // For more complex shell-like parsing without shell=true, we'd need a parser.
-            // But user requirements said "cmd: pnpm lint" etc.
-            // We will splitting by space for now or if we want shell safety we should use execFile/spawn without shell.
-            // However, "pnpm lint" requires finding pnpm in path. spawn(cmd, args) works.
-            const parts = tool.command.split(' ');
-            const cmd = parts[0];
-            const args = parts.slice(1);
-            const res = await runSpawn(cmd, args, repoRoot, tool.timeout_seconds);
-            const duration = (Date.now() - startTime) / 1000;
+            const cwd = tool.cwd ? path.resolve(repoRoot, tool.cwd) : repoRoot;
+            // Env construction
+            const env = {};
+            // Allowlist
+            const allowList = tool.env_allowlist || DEFAULT_ENV_ALLOWLIST;
+            for (const key of allowList) {
+                if (process.env[key] !== undefined) {
+                    env[key] = process.env[key];
+                }
+            }
+            // Overrides
+            if (tool.env) {
+                Object.assign(env, tool.env);
+            }
+            // Command Parsing
+            let cmdStr = tool.command;
+            let finalCmd;
+            let finalArgs;
+            let shell = false;
+            if (tool.allow_shell) {
+                shell = true;
+                finalCmd = cmdStr;
+                finalArgs = []; // Spawn with shell enabled takes command string as first arg usually, or requires shell syntax
+                // spawn(command, args, { shell: true }) -> command is string.
+                // But wait, spawn behavior with shell: true:
+                // If args provided, they are passed to shell.
+                // Usually we just pass the whole command string if shell=true.
+            }
+            else {
+                const parsed = parseCommand(cmdStr);
+                finalCmd = parsed.cmd;
+                finalArgs = parsed.args;
+                // Compatibility hack for Windows npm/pnpm without shell
+                if (process.platform === 'win32') {
+                    if (['npm', 'pnpm', 'yarn'].includes(finalCmd)) {
+                        finalCmd = `${finalCmd}.cmd`;
+                    }
+                }
+            }
+            // B) Tool runner safety
+            // 4) Assertions and filtering
+            if (!finalCmd) {
+                throw new Error('Command cannot be empty');
+            }
+            if (!Array.isArray(finalArgs)) {
+                throw new Error('Arguments must be an array');
+            }
+            finalArgs = finalArgs.filter(Boolean);
+            const res = await runSpawn(finalCmd, finalArgs, cwd, env, tool.timeout_seconds, shell);
+            const duration = Date.now() - startTime;
+            // Redact output
+            const stdout = redact(res.stdout, spec);
+            const stderr = redact(res.stderr, spec);
+            const status = res.code === 0 ? 'RAN' : 'FAILED';
             const toolRes = {
                 name: tool.name,
                 command: tool.command,
+                status,
                 exit_code: res.code,
-                stdout: res.stdout,
-                stderr: res.stderr,
-                duration,
-                optional: !!tool.optional
+                stdout,
+                stderr,
+                duration_ms: duration,
+                optional: !!tool.optional,
+                reason: res.reason
             };
             results.push(toolRes);
-            if (res.code !== 0) {
-                console.log(`  FAILED (Optional: ${tool.optional})`);
+            if (status === 'FAILED') {
+                console.log(`  FAILED (Optional: ${tool.optional}) - Code: ${res.code}`);
                 if (!tool.optional) {
                     violations.push({
                         type: 'tool_failure',
                         file: 'N/A',
-                        details: `Tool '${tool.name}' failed with exit code ${res.code}`
+                        details: `Tool '${tool.name}' failed with exit code ${res.code}. Reason: ${res.reason || 'Process exited with error'}`
                     });
                 }
             }
@@ -48,32 +180,44 @@ export async function runToolChecks(spec, repoRoot) {
                 file: 'N/A',
                 details: `Failed to execute tool '${tool.name}': ${e.message}`
             });
+            results.push({
+                name: tool.name,
+                command: tool.command,
+                status: 'FAILED',
+                exit_code: 1, // Synthetic
+                reason: e.message,
+                duration_ms: Date.now() - startTime,
+                optional: !!tool.optional
+            });
         }
     }
     return { results, violations };
 }
-function runSpawn(cmd, args, cwd, timeoutSec) {
+function runSpawn(cmd, args, cwd, env, timeoutSec, shell = false) {
     return new Promise((resolve, reject) => {
+        // If shell=true, 'cmd' is the full command string, args should be empty or handled carefully.
+        // Node spawn with shell: true treats 'cmd' as command line.
         const cp = spawn(cmd, args, {
             cwd,
-            shell: true, // Re-enabling shell=true for "pnpm", "npm" etc to work easily on Windows without searching .cmd. 
-            // The requirement says "Do NOT use shell execution by default... Use spawn/execFile with argv parsing."
-            // But "pnpm lint" is a shell command often. 
-            // If I want strict "no shell", I must append .cmd on Windows.
-            // Let's try to be compliant: shell: false.
-            // I will need to handle .cmd extension on Windows.
-            env: process.env, // TODO: Implement allowlist
-            timeout: timeoutSec ? timeoutSec * 1000 : undefined
+            shell,
+            env,
+            timeout: timeoutSec ? (timeoutSec * 1000) : 300000 // Default 300s
         });
         let stdout = '';
         let stderr = '';
         cp.stdout.on('data', (d) => stdout += d.toString());
         cp.stderr.on('data', (d) => stderr += d.toString());
         cp.on('error', (err) => {
-            reject(err);
+            // reject(err); // Don't reject, just return error code so we can log it
+            resolve({ code: 127, stdout, stderr, reason: `Spawn error: ${err.message}` });
         });
-        cp.on('close', (code) => {
-            resolve({ code: code ?? -1, stdout, stderr });
+        cp.on('close', (code, signal) => {
+            if (signal) {
+                resolve({ code: 128 + 15, stdout, stderr, reason: `Killed by signal ${signal} (Timeout?)` });
+            }
+            else {
+                resolve({ code: code ?? -1, stdout, stderr });
+            }
         });
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "specguard",
-    "version": "0.1.1",
+    "version": "0.1.3",
     "description": "Production-grade SpecGuard validator",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -34,4 +34,4 @@
         "@types/node": "^20.11.0",
         "vitest": "^4.0.18"
     }
-}
+}