@skillguard/cli 0.1.1 → 0.4.0

package/dist/commands/scan.js

@@ -1,19 +1,34 @@
 import { readFile, readdir, realpath } from 'node:fs/promises';
 import { basename, resolve, sep } from 'node:path';
-import { normalizeFindings, scanContent, toScanScore } from '../lib/api.js';
+import { normalizeFindings, scanContent, scanContentAnonymous, toScanScore } from '../lib/api.js';
 import { normalizeBaseUrl, readConfig, resolveApiKey } from '../lib/config.js';
 import { renderSingleScan, renderSummary, shouldUseColor, summarizeScores } from '../lib/format.js';
+import { CLI_VERSION } from '../lib/version.js';
 const FAIL_LEVELS = {
     safe: 0,
     warning: 1,
     dangerous: 2,
 };
+const WORST_EXIT_CODES = {
+    safe: 0,
+    warning: 1,
+    dangerous: 2,
+};
 function shouldFail(score, failOn) {
     if (failOn === 'safe') {
         return score !== 'safe';
     }
     return FAIL_LEVELS[score] >= FAIL_LEVELS[failOn];
 }
+function resolveWorstScore(results) {
+    if (results.some((result) => result.score === 'dangerous')) {
+        return 'dangerous';
+    }
+    if (results.some((result) => result.score === 'warning')) {
+        return 'warning';
+    }
+    return 'safe';
+}
 function isForbiddenFilePath(filePath) {
     const name = basename(filePath).toLowerCase();
     return (name === '.env' ||
@@ -28,7 +43,16 @@ function isWithinRoot(rootPath, candidatePath) {
     }
     return candidatePath.startsWith(`${rootPath}${sep}`);
 }
-async function findSkillFiles(rootPath) {
+function shouldSkipDirectory(entryName, options) {
+    if (options.scanAll) {
+        return false;
+    }
+    if (options.skipNodeModules && entryName.toLowerCase() === 'node_modules') {
+        return true;
+    }
+    return false;
+}
+async function findSkillFiles(rootPath, options) {
     const rootRealPath = await realpath(rootPath);
     const queue = [rootPath];
     const found = new Set();
@@ -44,6 +68,9 @@ async function findSkillFiles(rootPath) {
                 continue;
             }
             if (entry.isDirectory()) {
+                if (shouldSkipDirectory(entry.name, options)) {
+                    continue;
+                }
                 const resolvedDir = await realpath(fullPath);
                 if (!isWithinRoot(rootRealPath, resolvedDir)) {
                     continue;
@@ -70,14 +97,14 @@ async function findSkillFiles(rootPath) {
     }
     return Array.from(found).sort();
 }
-async function resolveTargets(inputPath) {
+async function resolveTargets(inputPath, traversalOptions) {
     const path = resolve(inputPath);
     const stat = await import('node:fs/promises').then((mod) => mod.lstat(path));
     if (stat.isSymbolicLink()) {
         throw new Error('Symlink paths are not supported.');
     }
     if (stat.isDirectory()) {
-        const files = await findSkillFiles(path);
+        const files = await findSkillFiles(path, traversalOptions);
         if (files.length === 0) {
             throw new Error('No SKILL.md files found in directory.');
         }
@@ -92,21 +119,25 @@ async function resolveTargets(inputPath) {
     return [path];
 }
 export async function runScan(inputPath, options) {
+    const scanRoot = inputPath ? resolve(inputPath) : process.cwd();
     let baseUrl;
     try {
         baseUrl = normalizeBaseUrl(options.baseUrl);
     }
     catch (error) {
         console.error(error.message);
-        return 2;
+        return 4;
     }
     let targets;
     try {
-        targets = await resolveTargets(inputPath);
+        targets = await resolveTargets(scanRoot, {
+            scanAll: options.scanAll,
+            skipNodeModules: options.skipNodeModules,
+        });
     }
     catch (error) {
         console.error(error.message);
-        return 2;
+        return 4;
     }
     if (options.dryRun) {
         if (!options.quiet) {
@@ -126,7 +157,7 @@ export async function runScan(inputPath, options) {
         }
         catch (error) {
             console.error(error.message);
-            return 2;
+            return 4;
         }
     }
     const resolvedApiKey = resolveApiKey({
@@ -134,26 +165,36 @@ export async function runScan(inputPath, options) {
         env: process.env,
         config,
     });
-    if (!resolvedApiKey) {
+    const useAnonymous = !resolvedApiKey;
+    if (!useAnonymous && !resolvedApiKey) {
         console.error("No API key found. Run 'skillguard init' or set SKILLGUARD_API_KEY.");
-        return 2;
+        return 4;
     }
     const color = shouldUseColor(options.noColor);
     const results = [];
+    if (useAnonymous && !options.quiet && !options.json) {
+        console.log('Scanning anonymously (limited). Add API key for higher limits.');
+    }
     for (const filePath of targets) {
         const content = await readFile(filePath, 'utf8');
         let apiResponse;
         try {
-            apiResponse = await scanContent({
-                baseUrl,
-                apiKey: resolvedApiKey.apiKey,
-                content,
-                timeoutMs: options.timeoutMs,
-            });
+            apiResponse = useAnonymous
+                ? await scanContentAnonymous({
+                    baseUrl,
+                    content,
+                    timeoutMs: options.timeoutMs,
+                })
+                : await scanContent({
+                    baseUrl,
+                    apiKey: resolvedApiKey.apiKey,
+                    content,
+                    timeoutMs: options.timeoutMs,
+                });
         }
         catch (error) {
             console.error(error.message);
-            return 3;
+            return 5;
         }
         const findings = normalizeFindings(apiResponse.findings);
         const score = toScanScore(apiResponse.score || apiResponse.overallRisk);
@@ -167,14 +208,23 @@ export async function runScan(inputPath, options) {
             signatureStatus,
         });
     }
-    const failedFiles = results.filter((result) => shouldFail(result.score, options.failOn)).map((result) => result.file);
+    const failOn = options.failOn || 'warning';
+    const mode = options.failOnExplicit ? 'threshold' : 'worst';
+    const worstScore = resolveWorstScore(results);
+    const failedFiles = results.filter((result) => shouldFail(result.score, failOn)).map((result) => result.file);
+    const exitCode = mode === 'threshold'
+        ? (failedFiles.length > 0 ? 1 : 0)
+        : WORST_EXIT_CODES[worstScore];
     if (!options.quiet) {
         if (options.json) {
             const summary = summarizeScores(results);
             console.log(JSON.stringify({
-                cli_version: '0.1.0',
+                cli_version: CLI_VERSION,
                 scanned_at: new Date().toISOString(),
-                fail_on: options.failOn,
+                mode,
+                worst_score: worstScore,
+                exit_code: exitCode,
+                fail_on: mode === 'threshold' ? failOn : undefined,
                 summary,
                 failed_files: failedFiles,
                 results,
@@ -185,9 +235,9 @@ export async function runScan(inputPath, options) {
                 console.log(renderSingleScan(result, color));
             }
             const summary = summarizeScores(results);
-            const rootLabel = targets.length === 1 ? targets[0] : resolve(inputPath);
+            const rootLabel = targets.length === 1 ? targets[0] : scanRoot;
             console.log(renderSummary(summary, rootLabel, color, failedFiles));
         }
     }
-    return failedFiles.length > 0 ? 1 : 0;
+    return exitCode;
 }

package/dist/commands/verify.js

@@ -29,7 +29,7 @@ export async function runVerify(inputPath, options) {
     }
     catch (error) {
         console.error(error.message);
-        return 2;
+        return 4;
     }
     let rawContent;
     try {
@@ -37,7 +37,7 @@ export async function runVerify(inputPath, options) {
     }
     catch {
         console.error('Could not read file.');
-        return 2;
+        return 4;
     }
     const parsedSkill = parseSkillContent(rawContent);
     if (!parsedSkill.security || typeof parsedSkill.security.signature !== 'string') {
@@ -59,7 +59,7 @@ export async function runVerify(inputPath, options) {
     }
     catch (error) {
         console.error(error.message);
-        return 3;
+        return 5;
     }
     const verification = verifySignature({ parsedSkill, jwks });
     const valid = verification.signatureValid && verification.hashMatches && !verification.expired;

package/dist/commands/workflow.d.ts

@@ -0,0 +1,21 @@
+import type { ScanScore } from '../lib/api.js';
+export interface WorkflowOptions {
+    outputPath?: string;
+    scanPath: string;
+    failOn: ScanScore;
+    print: boolean;
+    force: boolean;
+    autoGhPush: boolean;
+    commitMessage?: string;
+}
+interface GitCommandResult {
+    stdout: string;
+    stderr: string;
+    status: number;
+}
+type GitRunner = (args: string[]) => GitCommandResult;
+export declare function runWorkflow(options: WorkflowOptions, runtime?: {
+    cwd?: string;
+    gitRunner?: GitRunner;
+}): Promise<number>;
+export {};

package/dist/commands/workflow.js

@@ -0,0 +1,143 @@
+import { mkdir, access, writeFile } from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+const DEFAULT_WORKFLOW_PATH = '.github/workflows/skillguard.yml';
+const DEFAULT_COMMIT_MESSAGE = 'chore(ci): add skillguard workflow';
+function buildWorkflowYaml(input) {
+    const scanPath = input.scanPath.trim() || '.';
+    return [
+        'name: SkillGuard Gate',
+        'on:',
+        '  pull_request:',
+        '    paths:',
+        "      - '**/SKILL.md'",
+        "      - '**/skill.md'",
+        '  push:',
+        '    paths:',
+        "      - '**/SKILL.md'",
+        "      - '**/skill.md'",
+        '',
+        'jobs:',
+        '  scan:',
+        '    runs-on: ubuntu-latest',
+        '    steps:',
+        '      - uses: actions/checkout@v4',
+        '      - uses: actions/setup-node@v4',
+        '        with:',
+        "          node-version: '20'",
+        '      - name: SkillGuard scan',
+        `        run: npx @skillguard/cli gate ${scanPath} --fail-on ${input.failOn}`,
+    ].join('\n');
+}
+function isCommandSafePath(value) {
+    return /^[./a-zA-Z0-9_-]+$/.test(value);
+}
+async function fileExists(path) {
+    try {
+        await access(path, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function createDefaultGitRunner(cwd) {
+    return (args) => {
+        const result = spawnSync('git', args, {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (result.error) {
+            throw new Error('Git command failed.');
+        }
+        return {
+            stdout: typeof result.stdout === 'string' ? result.stdout : '',
+            stderr: typeof result.stderr === 'string' ? result.stderr : '',
+            status: typeof result.status === 'number' ? result.status : 1,
+        };
+    };
+}
+function ensureGitSuccess(result, fallbackMessage) {
+    if (result.status === 0) {
+        return;
+    }
+    const stderr = result.stderr.trim();
+    if (stderr) {
+        throw new Error(stderr);
+    }
+    throw new Error(fallbackMessage);
+}
+function resolveWorkflowPath(cwd, outputPath) {
+    return resolve(cwd, outputPath || DEFAULT_WORKFLOW_PATH);
+}
+function commitAndPushWorkflow(input) {
+    const git = input.gitRunner || createDefaultGitRunner(input.cwd);
+    const repoRootResult = git(['rev-parse', '--show-toplevel']);
+    ensureGitSuccess(repoRootResult, 'Not a git repository.');
+    const repoRoot = repoRootResult.stdout.trim();
+    const relativePath = relative(repoRoot, input.workflowPath);
+    if (!relativePath || relativePath.startsWith('..')) {
+        throw new Error('Workflow path must be inside the current git repository.');
+    }
+    ensureGitSuccess(git(['add', '--', relativePath]), 'Could not stage workflow file.');
+    const stagedResult = git(['diff', '--cached', '--name-only', '--', relativePath]);
+    ensureGitSuccess(stagedResult, 'Could not inspect staged changes.');
+    if (!stagedResult.stdout.trim()) {
+        return false;
+    }
+    ensureGitSuccess(git(['commit', '-m', input.commitMessage, '--', relativePath]), 'Could not create commit.');
+    ensureGitSuccess(git(['push']), 'Could not push commit.');
+    return true;
+}
+export async function runWorkflow(options, runtime) {
+    const cwd = runtime?.cwd || process.cwd();
+    const scanPath = (options.scanPath || '.').trim() || '.';
+    if (!isCommandSafePath(scanPath)) {
+        console.error('Invalid --scan-path value. Use simple relative paths only.');
+        return 4;
+    }
+    if (options.print && options.autoGhPush) {
+        console.error('Cannot use --auto-gh-push with --print.');
+        return 4;
+    }
+    const yaml = buildWorkflowYaml({
+        scanPath,
+        failOn: options.failOn,
+    });
+    if (options.print) {
+        console.log(yaml);
+        return 0;
+    }
+    const workflowPath = resolveWorkflowPath(cwd, options.outputPath);
+    const exists = await fileExists(workflowPath);
+    if (exists && !options.force) {
+        console.error(`Workflow file already exists: ${workflowPath}. Use --force to overwrite.`);
+        return 4;
+    }
+    await mkdir(dirname(workflowPath), { recursive: true });
+    await writeFile(workflowPath, `${yaml}\n`, 'utf8');
+    console.log(`Workflow written to ${workflowPath}`);
+    if (!options.autoGhPush) {
+        return 0;
+    }
+    try {
+        const pushed = commitAndPushWorkflow({
+            cwd,
+            workflowPath,
+            commitMessage: (options.commitMessage || DEFAULT_COMMIT_MESSAGE).trim() || DEFAULT_COMMIT_MESSAGE,
+            gitRunner: runtime?.gitRunner,
+        });
+        if (!pushed) {
+            console.log('Workflow already up to date. No commit created.');
+            return 0;
+        }
+    }
+    catch (error) {
+        console.error(`Auto push failed: ${error.message}`);
+        return 5;
+    }
+    console.log('Workflow committed and pushed.');
+    return 0;
+}

package/dist/lib/api.d.ts

@@ -14,6 +14,34 @@ export interface ScanApiResponse {
     signedSkillContent?: string;
     [key: string]: unknown;
 }
+export interface LimitsApiResponse {
+    mode?: 'anonymous' | 'owner' | 'agent';
+    tokenBalance?: number;
+    ownerTrial?: {
+        scansLimit?: number;
+        scansUsed?: number;
+        remainingScans?: number;
+        expiresAt?: string | null;
+        active?: boolean;
+    };
+    apiKeyQuota?: {
+        keyType?: 'standard' | 'trial';
+        maxScans?: number | null;
+        scansUsed?: number;
+        remainingScans?: number | null;
+        expiresAt?: string | null;
+        unlimited?: boolean;
+        active?: boolean;
+    };
+    anonymousQuota?: {
+        windowMs?: number;
+        maxScans?: number;
+        scansUsed?: number;
+        remainingScans?: number;
+        resetAt?: string;
+    };
+    [key: string]: unknown;
+}
 export interface SanitizedApiError {
     message: string;
     exitCode: 2 | 3;
@@ -26,6 +54,18 @@ export declare function scanContent(input: {
     timeoutMs: number;
     fetchImpl?: typeof fetch;
 }): Promise<ScanApiResponse>;
+export declare function scanContentAnonymous(input: {
+    baseUrl: string;
+    content: string;
+    timeoutMs: number;
+    fetchImpl?: typeof fetch;
+}): Promise<ScanApiResponse>;
+export declare function fetchLimits(input: {
+    baseUrl: string;
+    timeoutMs: number;
+    apiKey?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<LimitsApiResponse>;
 export declare function fetchJwks(input: {
     baseUrl: string;
     timeoutMs: number;

package/dist/lib/api.js

@@ -58,6 +58,47 @@ function mapStatusMessage(status) {
     }
     return 'SkillGuard API request failed.';
 }
+function mapLimitsStatusMessage(status) {
+    if (status === 401) {
+        return "Invalid API key. Run 'skillguard init' or set SKILLGUARD_API_KEY.";
+    }
+    if (status === 403) {
+        return 'Access denied for this API key.';
+    }
+    if (status === 429) {
+        return 'Rate limit exceeded. Wait and retry.';
+    }
+    if (status >= 500) {
+        return 'SkillGuard API error. Try again later.';
+    }
+    return 'SkillGuard limits request failed.';
+}
+function detectCiSource(env = process.env) {
+    if (env.GITHUB_ACTIONS === 'true')
+        return 'github-actions';
+    if (env.GITLAB_CI === 'true')
+        return 'gitlab';
+    if (env.BUILDKITE === 'true')
+        return 'buildkite';
+    if (env.CIRCLECI === 'true')
+        return 'circleci';
+    if (env.JENKINS_URL)
+        return 'jenkins';
+    if (env.TF_BUILD === 'True' || env.AZURE_HTTP_USER_AGENT)
+        return 'azure-pipelines';
+    return null;
+}
+function buildCliHeaders(extra = {}) {
+    const headers = {
+        'X-SkillGuard-Source': 'cli',
+        ...extra,
+    };
+    const ciSource = detectCiSource();
+    if (ciSource) {
+        headers['X-SkillGuard-CI'] = ciSource;
+    }
+    return headers;
+}
 export async function scanContent(input) {
     const fetchFn = input.fetchImpl || fetch;
     const endpoint = `${input.baseUrl}/api/v1/scan`;
@@ -66,6 +107,7 @@ export async function scanContent(input) {
         const response = await fetchWithRetry(fetchFn, endpoint, {
             method: 'POST',
             headers: {
+                ...buildCliHeaders(),
                 'X-API-Key': input.apiKey,
                 'Content-Type': 'application/json',
             },
@@ -101,6 +143,91 @@ export async function scanContent(input) {
         timeout.cancel();
     }
 }
+export async function scanContentAnonymous(input) {
+    const fetchFn = input.fetchImpl || fetch;
+    const endpoint = `${input.baseUrl}/api/v1/scan/anonymous`;
+    const timeout = withTimeout(input.timeoutMs);
+    try {
+        const response = await fetchWithRetry(fetchFn, endpoint, {
+            method: 'POST',
+            headers: {
+                ...buildCliHeaders(),
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ content: input.content }),
+            signal: timeout.signal,
+        }, 1);
+        if (!response.ok) {
+            throw new Error(mapStatusMessage(response.status));
+        }
+        const parsed = await parseJsonSafe(response);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('Unexpected API response.');
+        }
+        return parsed;
+    }
+    catch (error) {
+        const typed = error;
+        if (typed.name === 'AbortError') {
+            throw new Error('Cannot reach skillguard.ai. Check your connection.');
+        }
+        if (typed.message === 'Unexpected API response.') {
+            throw typed;
+        }
+        if (typed.message.includes('Rate limit exceeded.') ||
+            typed.message.includes('SkillGuard API error.') ||
+            typed.message.includes('SkillGuard API request failed.')) {
+            throw typed;
+        }
+        throw new Error('Cannot reach skillguard.ai. Check your connection.');
+    }
+    finally {
+        timeout.cancel();
+    }
+}
+export async function fetchLimits(input) {
+    const fetchFn = input.fetchImpl || fetch;
+    const endpoint = `${input.baseUrl}/api/v1/limits`;
+    const timeout = withTimeout(input.timeoutMs);
+    try {
+        const response = await fetchWithRetry(fetchFn, endpoint, {
+            method: 'GET',
+            headers: {
+                ...buildCliHeaders(),
+                ...(input.apiKey ? { 'X-API-Key': input.apiKey } : {}),
+            },
+            signal: timeout.signal,
+        }, 1);
+        if (!response.ok) {
+            throw new Error(mapLimitsStatusMessage(response.status));
+        }
+        const parsed = await parseJsonSafe(response);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('Unexpected API response.');
+        }
+        return parsed;
+    }
+    catch (error) {
+        const typed = error;
+        if (typed.name === 'AbortError') {
+            throw new Error('Cannot reach skillguard.ai. Check your connection.');
+        }
+        if (typed.message === 'Unexpected API response.') {
+            throw typed;
+        }
+        if (typed.message.includes('Invalid API key.') ||
+            typed.message.includes('Access denied') ||
+            typed.message.includes('Rate limit exceeded.') ||
+            typed.message.includes('SkillGuard API error.') ||
+            typed.message.includes('SkillGuard limits request failed.')) {
+            throw typed;
+        }
+        throw new Error('Cannot reach skillguard.ai. Check your connection.');
+    }
+    finally {
+        timeout.cancel();
+    }
+}
 export async function fetchJwks(input) {
     const fetchFn = input.fetchImpl || fetch;
     const endpoint = `${input.baseUrl}/.well-known/skillguard-jwks.json`;

package/dist/lib/format.js

@@ -113,6 +113,8 @@ export function renderSummary(summary, rootPath, color, failedFiles) {
         `  ${formatCell(maybeColor(color, GREEN, 'safe:'), 11)}${String(summary.safe)}`,
         `  ${formatCell(maybeColor(color, YELLOW, 'warning:'), 11)}${String(summary.warning)}`,
         `  ${formatCell(maybeColor(color, RED, 'dangerous:'), 11)}${String(summary.dangerous)}`,
+        '',
+        `Worst score: ${summary.dangerous > 0 ? 'dangerous' : summary.warning > 0 ? 'warning' : 'safe'}`,
     ];
     if (failedFiles.length > 0) {
         lines.push('');

package/dist/lib/help.d.ts

@@ -0,0 +1,2 @@
+export declare function renderGeneralHelp(version: string): string;
+export declare function renderTopicHelp(command: string | undefined): string | null;