@skillguard/cli 0.2.1 → 0.5.0

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/config.d.ts

@@ -15,5 +15,6 @@ export interface ApiKeyResolutionInput {
 export declare function getConfigPath(home?: string): string;
 export declare function readConfig(configPath?: string): Promise<SkillguardCliConfig | null>;
 export declare function writeConfig(config: SkillguardCliConfig, configPath?: string): Promise<void>;
+export declare function clearConfig(configPath?: string): Promise<boolean>;
 export declare function normalizeBaseUrl(value?: string): string;
 export declare function resolveApiKey(input: ApiKeyResolutionInput): ResolvedApiKey | null;

package/dist/lib/config.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, chmod, writeFile } from 'node:fs/promises';
+import { access, chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 export const DEFAULT_BASE_URL = 'https://skillguard.ai';
@@ -39,6 +39,25 @@ export async function writeConfig(config, configPath = getConfigPath()) {
     await writeFile(configPath, `${body}\n`, { encoding: 'utf8', mode: 0o600 });
     await chmod(configPath, 0o600);
 }
+export async function clearConfig(configPath = getConfigPath()) {
+    try {
+        await access(configPath);
+    }
+    catch (error) {
+        const typed = error;
+        if (typed?.code === 'ENOENT') {
+            return false;
+        }
+        throw new Error('Failed to clear CLI config.');
+    }
+    try {
+        await rm(configPath, { force: true });
+        return true;
+    }
+    catch {
+        throw new Error('Failed to clear CLI config.');
+    }
+}
 export function normalizeBaseUrl(value) {
     const raw = (value || DEFAULT_BASE_URL).trim();
     const withoutTrailingSlash = raw.replace(/\/+$/, '');

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;

package/dist/lib/help.js

@@ -0,0 +1,267 @@
+const COMMAND_ALIASES = {
+    man: 'help',
+};
+function normalizeTopic(topic) {
+    if (!topic) {
+        return null;
+    }
+    const normalized = topic.trim().toLowerCase();
+    const aliased = COMMAND_ALIASES[normalized] || normalized;
+    if (aliased === 'help' ||
+        aliased === 'auth' ||
+        aliased === 'init' ||
+        aliased === 'scan' ||
+        aliased === 'gate' ||
+        aliased === 'limits' ||
+        aliased === 'verify' ||
+        aliased === 'workflow') {
+        return aliased;
+    }
+    return null;
+}
+export function renderGeneralHelp(version) {
+    return `SkillGuard CLI ${version}
+
+Usage:
+  skillguard <command> [options]
+
+Core commands:
+  auth        API-key auth commands (login/status/logout)
+  init        Save API key in local CLI config
+  scan        Scan one file or recursively scan a directory
+  gate        CI gate mode (0 pass, 1 fail)
+  limits      Show anonymous/owner/agent remaining limits
+  verify      Verify signed SKILL.md via SkillGuard JWKS
+  workflow    Generate GitHub Actions workflow file
+
+Help commands:
+  help [command]
+  man [command]
+
+Quick start:
+  skillguard scan SKILL.md
+  skillguard auth status
+  skillguard gate .
+  skillguard workflow
+  skillguard workflow --auto-gh-push
+
+Global flags:
+  -h, --help     Show help
+  -v, --version  Show version
+  --workflow     Alias for "workflow"
+
+Run "skillguard help <command>" for full command details.`;
+}
+function renderHelpCommandHelp() {
+    return `NAME
+  skillguard help, skillguard man - show detailed command help
+
+SYNOPSIS
+  skillguard help [command]
+  skillguard man [command]
+
+DESCRIPTION
+  Shows command-level help in a man-page style format.
+  If no command is provided, prints general CLI help.
+
+EXAMPLES
+  skillguard help scan
+  skillguard man workflow`;
+}
+function renderInitHelp() {
+    return `NAME
+  skillguard init - save API key in local config
+
+SYNOPSIS
+  skillguard init [--api-key <key>] [--base-url <url>]
+
+DESCRIPTION
+  Writes ~/.config/skillguard/config.json with apiKey and apiUrl.
+  If --api-key is omitted, prompts interactively.
+
+OPTIONS
+  --api-key <key>     API key to persist
+  --base-url <url>    API base URL (default: https://skillguard.ai)
+
+EXIT CODES
+  0 success
+  4 usage/input/config error
+  5 external runtime error`;
+}
+function renderAuthHelp() {
+    return `NAME
+  skillguard auth - manage CLI authentication state
+
+SYNOPSIS
+  skillguard auth login [--api-key <key>] [--base-url <url>]
+  skillguard auth status [--json] [--api-key <key>] [--base-url <url>]
+  skillguard auth logout
+
+DESCRIPTION
+  login   Save API key in local config (interactive if key omitted)
+  status  Show effective auth source (flag/env/config/none)
+  logout  Remove local CLI config key
+
+NOTES
+  logout cannot unset SKILLGUARD_API_KEY environment variables from parent shell.
+
+EXIT CODES
+  0 success
+  4 usage/input/config error
+  5 external runtime error`;
+}
+function renderScanHelp() {
+    return `NAME
+  skillguard scan - scan SKILL.md content for risk
+
+SYNOPSIS
+  skillguard scan [path] [options]
+
+DESCRIPTION
+  Scans one file or recursively scans a directory for SKILL.md files.
+  If no path is provided, scans from current directory.
+  If no API key is configured, uses anonymous mode (rate-limited).
+
+OPTIONS
+  --json                       Machine-readable JSON output
+  --fail-on <safe|warning|dangerous>
+                               Explicit threshold mode (exit 0/1)
+  --timeout <ms>              Request timeout (default: 30000)
+  --base-url <url>            API base URL
+  --api-key <key>             Override API key
+  --dry-run                   Show target files, skip API call
+  --quiet                     Suppress output, keep exit code
+  --no-color                  Disable ANSI colors
+  --skip-node-modules         Skip node_modules (default: enabled)
+  --scan-all                  Disable skip filters for recursive scan
+
+EXIT CODES
+  default mode (no --fail-on): safe=0, warning=1, dangerous=2
+  threshold mode (--fail-on): 0 below threshold, 1 threshold reached
+  4 usage/input/config error
+  5 network/API/runtime failure`;
+}
+function renderGateHelp() {
+    return `NAME
+  skillguard gate - CI gate mode for deterministic pass/fail
+
+SYNOPSIS
+  skillguard gate [path] [options]
+
+DESCRIPTION
+  Wrapper around scan with explicit threshold mode enabled.
+  Default fail-on is warning.
+
+OPTIONS
+  Same as "skillguard scan".
+  --fail-on defaults to warning in gate mode.
+
+EXIT CODES
+  0 below threshold
+  1 threshold reached
+  4 usage/input/config error
+  5 network/API/runtime failure`;
+}
+function renderLimitsHelp() {
+    return `NAME
+  skillguard limits - show remaining limits/quota
+
+SYNOPSIS
+  skillguard limits [--json] [--timeout <ms>] [--base-url <url>] [--api-key <key>] [--no-color]
+
+DESCRIPTION
+  Fetches /api/v1/limits and prints current request mode:
+  anonymous, owner, or agent.
+
+OPTIONS
+  --json             JSON output
+  --timeout <ms>     Request timeout (default: 30000)
+  --base-url <url>   API base URL
+  --api-key <key>    Optional API key
+  --no-color         Disable ANSI colors
+
+EXIT CODES
+  0 success
+  4 usage/input/config error
+  5 network/API/runtime failure`;
+}
+function renderVerifyHelp() {
+    return `NAME
+  skillguard verify - verify signed SKILL.md content
+
+SYNOPSIS
+  skillguard verify <path> [--json] [--timeout <ms>] [--base-url <url>]
+
+DESCRIPTION
+  Verifies SkillGuard Ed25519 signature and content hash using JWKS.
+
+OPTIONS
+  --json             JSON output
+  --timeout <ms>     Request timeout (default: 30000)
+  --base-url <url>   API base URL
+
+EXIT CODES
+  0 signature valid
+  1 invalid/tampered/expired signature
+  4 usage/input/config error
+  5 network/API/runtime failure`;
+}
+function renderWorkflowHelp() {
+    return `NAME
+  skillguard workflow - generate GitHub Actions workflow for CI gate
+
+SYNOPSIS
+  skillguard workflow [options]
+  skillguard --workflow [options]
+
+DESCRIPTION
+  Writes .github/workflows/skillguard.yml configured to run:
+  npx @skillguard/cli gate . --fail-on warning
+
+OPTIONS
+  --path <file>              Output workflow path
+                             (default: .github/workflows/skillguard.yml)
+  --scan-path <path>         Path passed to gate command (default: .)
+  --fail-on <safe|warning|dangerous>
+                             Gate threshold (default: warning)
+  --print                    Print YAML to stdout, do not write files
+  --force                    Overwrite existing file
+  --auto-gh-push             Run git add/commit/push after writing
+
+EXIT CODES
+  0 success
+  4 usage/input/config error
+  5 runtime/git failure
+
+EXAMPLES
+  skillguard workflow
+  skillguard workflow --print
+  skillguard workflow --auto-gh-push
+  skillguard --workflow --force`;
+}
+export function renderTopicHelp(command) {
+    const topic = normalizeTopic(command);
+    if (!topic) {
+        return null;
+    }
+    switch (topic) {
+        case 'help':
+            return renderHelpCommandHelp();
+        case 'auth':
+            return renderAuthHelp();
+        case 'init':
+            return renderInitHelp();
+        case 'scan':
+            return renderScanHelp();
+        case 'gate':
+            return renderGateHelp();
+        case 'limits':
+            return renderLimitsHelp();
+        case 'verify':
+            return renderVerifyHelp();
+        case 'workflow':
+            return renderWorkflowHelp();
+        default:
+            return null;
+    }
+}

package/dist/lib/version.d.ts

@@ -0,0 +1 @@
+export declare const CLI_VERSION = "0.5.0";

package/dist/lib/version.js

@@ -0,0 +1 @@
+export const CLI_VERSION = '0.5.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillguard/cli",
-  "version": "0.2.1",
+  "version": "0.5.0",
   "description": "Security scanner for AI agent skill files",
   "type": "module",
   "bin": {