codegate-ai 0.4.0 → 0.6.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![CI](https://github.com/jonathansantilli/codegate/actions/workflows/ci.yml/badge.svg)](https://github.com/jonathansantilli/codegate/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/jonathansantilli/codegate/actions/workflows/codeql.yml/badge.svg)](https://github.com/jonathansantilli/codegate/actions/workflows/codeql.yml)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg?url=https://deepwiki.com/jonathansantilli/codegate)](https://deepwiki.com/jonathansantilli/codegate)
 [![npm version](https://img.shields.io/npm/v/codegate-ai)](https://www.npmjs.com/package/codegate-ai)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
@@ -70,6 +71,21 @@ npm install -g codegate-ai
 codegate scan .
 ```
 
+Recommended first run:
+
+```bash
+codegate init
+```
+
+Why run `init`:
+
+- Creates `~/.codegate/config.json` so your behavior is explicit and easy to tune.
+- Makes it straightforward to set preferences like `scan_user_scope`, output format, thresholds, and tool discovery options.
+
+If you skip `init`, CodeGate still works with built-in defaults. Nothing breaks.
+
+See the [Configuration](#configuration) section for full settings and examples.
+
 ## System Capabilities
 
 1. Multi-layer analysis pipeline:
@@ -89,15 +105,17 @@ codegate scan .
 
 ## Core Commands
 
-| Command                 | Purpose                                                                |
-| ----------------------- | ---------------------------------------------------------------------- |
-| `codegate scan [dir]`   | Scan a directory for AI tool config risks. Defaults to `.`.            |
-| `codegate run <tool>`   | Scan current directory, then launch selected AI tool if policy allows. |
-| `codegate undo [dir]`   | Restore the most recent remediation backup session. Defaults to `.`.   |
-| `codegate init`         | Create `~/.codegate/config.json` with defaults.                        |
-| `codegate update-kb`    | Show knowledge-base update guidance.                                   |
-| `codegate update-rules` | Show rules update guidance.                                            |
-| `codegate --help`       | Show CLI usage.                                                        |
+| Command                  | Purpose                                                                |
+| ------------------------ | ---------------------------------------------------------------------- |
+| `codegate scan [target]` | Scan a directory, file, or URL target for AI tool config risks.        |
+| `codegate run <tool>`    | Scan current directory, then launch selected AI tool if policy allows. |
+| `codegate skills [...]`  | Wrap `npx skills` and preflight-scan `skills add` targets.             |
+| `codegate clawhub [...]` | Wrap `npx clawhub` and preflight-scan `clawhub install` targets.       |
+| `codegate undo [dir]`    | Restore the most recent remediation backup session. Defaults to `.`.   |
+| `codegate init`          | Create `~/.codegate/config.json` with defaults.                        |
+| `codegate update-kb`     | Show knowledge-base update guidance.                                   |
+| `codegate update-rules`  | Show rules update guidance.                                            |
+| `codegate --help`        | Show CLI usage.                                                        |
 
 ## `scan` Command Flags
 
@@ -167,6 +185,42 @@ codegate run codex
 codegate run cursor
 ```
 
+## Installer Wrappers (`skills` and `clawhub`)
+
+CodeGate also provides scan-first wrappers for skill installers:
+
+- `codegate skills [skillsArgs...]` wraps `npx skills`.
+- `codegate clawhub [clawhubArgs...]` wraps `npx clawhub`.
+
+Behavior:
+
+- For `skills add ...`, CodeGate resolves the requested source target, scans it, and only proceeds if policy allows.
+- For `clawhub install ...`, CodeGate stages the remote skill content via `clawhub inspect`, scans the staged content, and only proceeds if policy allows.
+- Dangerous findings block execution (fail-closed).
+- Warning-level findings can still require confirmation unless `--cg-force` is provided.
+- Non-install subcommands (for example `skills find` or `clawhub search`) are passed through without preflight scanning.
+
+Wrapper flags (consumed by CodeGate, not forwarded):
+
+- `--cg-force`
+- `--cg-deep`
+- `--cg-no-tui`
+- `--cg-include-user-scope`
+- `--cg-format <type>`
+- `--cg-config <path>`
+
+Examples:
+
+```bash
+codegate skills add https://github.com/vercel-labs/skills --skill find-skills
+codegate skills add https://github.com/owner/repo --skill security-review --cg-force
+codegate skills add https://github.com/owner/repo --skill security-review --cg-deep
+codegate clawhub install security-auditor
+codegate clawhub install security-auditor --version 1.0.0
+codegate clawhub install security-auditor --cg-deep
+codegate clawhub search security
+```
+
 ## Deep Scan (Layer 3)
 
 Deep scan is opt-in and only runs with `--deep`.

package/dist/cli.d.ts

@@ -9,6 +9,7 @@ import { type ResolvedScanTarget } from "./scan-target.js";
 import type { CodeGateReport } from "./types/report.js";
 import { type RemediationRunnerInput, type RemediationRunnerResult } from "./layer4-remediation/remediation-runner.js";
 import { type SkillsWrapperLaunchResult } from "./commands/skills-wrapper.js";
+import { type ClawhubWrapperLaunchResult } from "./commands/clawhub-wrapper.js";
 import { type DeepAgentOption, type MetaAgentCommandConsentContext, type MetaAgentCommandRunResult, type RemediationConsentContext, type ScanRunnerInput } from "./commands/scan-command.js";
 export interface RunWarningConsentContext {
     target: string;
@@ -57,10 +58,15 @@ export interface CliDeps {
     requestSkillSelection?: (options: string[]) => Promise<string | null> | string | null;
     executeDeepResource?: (resource: DeepScanResource) => Promise<ResourceFetchResult>;
     launchSkills?: (args: string[], cwd: string) => SkillsWrapperLaunchResult;
+    launchClawhub?: (args: string[], cwd: string) => ClawhubWrapperLaunchResult;
     runSkillsWrapper?: (input: {
         version: string;
         skillsArgs: string[];
     }) => Promise<void>;
+    runClawhubWrapper?: (input: {
+        version: string;
+        clawhubArgs: string[];
+    }) => Promise<void>;
     runWrapper?: (input: {
         target: string;
         cwd: string;

package/dist/cli.js

@@ -21,6 +21,7 @@ import { runRemediation as runRemediationWorkflow, } from "./layer4-remediation/
 import { undoLatestSession } from "./commands/undo.js";
 import { executeScanCommand } from "./commands/scan-command.js";
 import { executeSkillsWrapper, launchSkillsPassthrough, } from "./commands/skills-wrapper.js";
+import { executeClawhubWrapper, launchClawhubPassthrough, } from "./commands/clawhub-wrapper.js";
 import { promptDeepAgentSelection, promptDeepScanConsent, promptMetaAgentCommandConsent, promptRemediationConsent, promptSkillSelection, } from "./cli-prompts.js";
 import { resetScanState } from "./layer2-static/state/scan-state.js";
 const require = createRequire(import.meta.url);
@@ -67,6 +68,51 @@ function mapAcquisitionFailure(status, error) {
         error: error ?? "tool description acquisition failed",
     };
 }
+async function runMetaAgentCommandWithSandbox(context) {
+    const commandResult = await runSandboxCommand({
+        command: context.command.command,
+        args: context.command.args,
+        cwd: context.command.cwd,
+        timeoutMs: context.command.timeoutMs,
+    });
+    return {
+        command: context.command,
+        code: commandResult.code,
+        stdout: commandResult.stdout,
+        stderr: commandResult.stderr,
+    };
+}
+function resolveInteractiveCallback(input) {
+    if (!input.enabled) {
+        return undefined;
+    }
+    return input.provided ?? input.fallback;
+}
+function buildWrapperScanBridgeDeps(deps) {
+    const isTTY = deps.isTTY();
+    return {
+        prepareScanDiscovery: deps.prepareScanDiscovery,
+        discoverDeepResources: deps.discoverDeepResources,
+        discoverLocalTextTargets: deps.discoverLocalTextTargets,
+        requestDeepScanConsent: resolveInteractiveCallback({
+            enabled: true,
+            provided: deps.requestDeepScanConsent,
+            fallback: isTTY ? promptDeepScanConsent : undefined,
+        }),
+        requestDeepAgentSelection: resolveInteractiveCallback({
+            enabled: true,
+            provided: deps.requestDeepAgentSelection,
+            fallback: isTTY ? promptDeepAgentSelection : undefined,
+        }),
+        requestMetaAgentCommandConsent: resolveInteractiveCallback({
+            enabled: true,
+            provided: deps.requestMetaAgentCommandConsent,
+            fallback: isTTY ? promptMetaAgentCommandConsent : undefined,
+        }),
+        runMetaAgentCommand: deps.runMetaAgentCommand ?? runMetaAgentCommandWithSandbox,
+        executeDeepResource: deps.executeDeepResource,
+    };
+}
 async function promptRunWarningConsent(context) {
     const rl = createInterface({
         input: process.stdin,
@@ -157,6 +203,7 @@ const defaultCliDeps = {
         return fetchResourceMetadata(resource.request);
     },
     launchSkills: (args, cwd) => launchSkillsPassthrough(args, cwd),
+    launchClawhub: (args, cwd) => launchClawhubPassthrough(args, cwd),
 };
 function addScanCommand(program, version, deps) {
     program
@@ -245,38 +292,28 @@ function addScanCommand(program, version, deps) {
                 prepareScanDiscovery: deps.prepareScanDiscovery,
                 discoverDeepResources: deps.discoverDeepResources,
                 discoverLocalTextTargets: deps.discoverLocalTextTargets,
-                requestDeepScanConsent: promptCallbacksEnabled
-                    ? (deps.requestDeepScanConsent ??
-                        (interactivePromptsEnabled ? promptDeepScanConsent : undefined))
-                    : undefined,
-                requestDeepAgentSelection: promptCallbacksEnabled
-                    ? (deps.requestDeepAgentSelection ??
-                        (interactivePromptsEnabled ? promptDeepAgentSelection : undefined))
-                    : undefined,
-                requestMetaAgentCommandConsent: promptCallbacksEnabled
-                    ? (deps.requestMetaAgentCommandConsent ??
-                        (interactivePromptsEnabled ? promptMetaAgentCommandConsent : undefined))
-                    : undefined,
+                requestDeepScanConsent: resolveInteractiveCallback({
+                    enabled: promptCallbacksEnabled,
+                    provided: deps.requestDeepScanConsent,
+                    fallback: interactivePromptsEnabled ? promptDeepScanConsent : undefined,
+                }),
+                requestDeepAgentSelection: resolveInteractiveCallback({
+                    enabled: promptCallbacksEnabled,
+                    provided: deps.requestDeepAgentSelection,
+                    fallback: interactivePromptsEnabled ? promptDeepAgentSelection : undefined,
+                }),
+                requestMetaAgentCommandConsent: resolveInteractiveCallback({
+                    enabled: promptCallbacksEnabled,
+                    provided: deps.requestMetaAgentCommandConsent,
+                    fallback: interactivePromptsEnabled ? promptMetaAgentCommandConsent : undefined,
+                }),
                 executeDeepResource: deps.executeDeepResource,
-                runMetaAgentCommand: deps.runMetaAgentCommand ??
-                    (async (context) => {
-                        const commandResult = await runSandboxCommand({
-                            command: context.command.command,
-                            args: context.command.args,
-                            cwd: context.command.cwd,
-                            timeoutMs: context.command.timeoutMs,
-                        });
-                        return {
-                            command: context.command,
-                            code: commandResult.code,
-                            stdout: commandResult.stdout,
-                            stderr: commandResult.stderr,
-                        };
-                    }),
-                requestRemediationConsent: promptCallbacksEnabled
-                    ? (deps.requestRemediationConsent ??
-                        (interactivePromptsEnabled ? promptRemediationConsent : undefined))
-                    : undefined,
+                runMetaAgentCommand: deps.runMetaAgentCommand ?? runMetaAgentCommandWithSandbox,
+                requestRemediationConsent: resolveInteractiveCallback({
+                    enabled: promptCallbacksEnabled,
+                    provided: deps.requestRemediationConsent,
+                    fallback: interactivePromptsEnabled ? promptRemediationConsent : undefined,
+                }),
                 runRemediation: deps.runRemediation,
                 stdout: deps.stdout,
                 stderr: deps.stderr,
@@ -376,6 +413,7 @@ function addSkillsCommand(program, version, deps) {
         .addHelpText("after", renderExampleHelp([
         "codegate skills add vercel-labs/skills --skill find-skills",
         "codegate skills add https://github.com/owner/repo --skill security-review",
+        "codegate skills add owner/repo --skill demo --cg-deep",
         "codegate skills find security",
         "codegate skills add owner/repo --skill demo --cg-force",
     ]))
@@ -388,6 +426,7 @@ function addSkillsCommand(program, version, deps) {
                     pathExists: deps.pathExists,
                     resolveConfig: deps.resolveConfig,
                     runScan: deps.runScan,
+                    ...buildWrapperScanBridgeDeps(deps),
                     resolveScanTarget: deps.resolveScanTarget,
                     requestSkillSelection: deps.requestSkillSelection,
                     requestWarningProceed: deps.requestRunWarningConsent,
@@ -409,6 +448,49 @@ function addSkillsCommand(program, version, deps) {
         }
     });
 }
+function addClawhubCommand(program, version, deps) {
+    program
+        .command("clawhub [clawhubArgs...]")
+        .description("Wrap npx clawhub with CodeGate preflight scanning for installs")
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .addHelpText("after", renderExampleHelp([
+        "codegate clawhub install security-auditor",
+        "codegate clawhub install security-auditor --version 1.0.0",
+        "codegate clawhub install security-auditor --cg-deep",
+        "codegate clawhub search security",
+        "codegate clawhub install security-auditor --cg-force",
+    ]))
+        .action(async (clawhubArgs) => {
+        try {
+            const runClawhubWrapper = deps.runClawhubWrapper ??
+                ((input) => executeClawhubWrapper(input, {
+                    cwd: deps.cwd,
+                    isTTY: deps.isTTY,
+                    pathExists: deps.pathExists,
+                    resolveConfig: deps.resolveConfig,
+                    runScan: deps.runScan,
+                    ...buildWrapperScanBridgeDeps(deps),
+                    resolveScanTarget: deps.resolveScanTarget,
+                    requestWarningProceed: deps.requestRunWarningConsent,
+                    launchClawhub: deps.launchClawhub ?? ((args, cwd) => launchClawhubPassthrough(args, cwd)),
+                    stdout: deps.stdout,
+                    stderr: deps.stderr,
+                    setExitCode: deps.setExitCode,
+                    renderTui: deps.renderTui,
+                }));
+            await runClawhubWrapper({
+                version,
+                clawhubArgs: clawhubArgs ?? [],
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            deps.stderr(`ClawHub wrapper failed: ${message}`);
+            deps.setExitCode(3);
+        }
+    });
+}
 function addUndoCommand(program, deps) {
     program
         .command("undo [dir]")
@@ -513,10 +595,12 @@ export function createCli(version = packageJson.version ?? "0.0.0-dev", deps = d
         "codegate scan https://github.com/owner/repo",
         "codegate scan https://github.com/owner/repo/blob/main/skills/security-review/SKILL.md",
         "codegate skills add owner/repo --skill security-review",
+        "codegate clawhub install security-auditor",
         "codegate run claude",
     ]));
     addScanCommand(program, version, deps);
     addSkillsCommand(program, version, deps);
+    addClawhubCommand(program, version, deps);
     addRunCommand(program, version, deps);
     addUndoCommand(program, deps);
     addInitCommand(program, deps);

package/dist/commands/clawhub-wrapper.d.ts

@@ -0,0 +1,76 @@
+import { type CodeGateConfig, type OutputFormat, type ResolveConfigOptions } from "../config.js";
+import { type ResolvedScanTarget } from "../scan-target.js";
+import type { CodeGateReport } from "../types/report.js";
+import { type ScanAnalysisDeps, type ScanRunnerInput } from "./scan-command.js";
+interface SourceDetectionContext {
+    cwd: string;
+    pathExists: (path: string) => boolean;
+}
+export interface ClawhubWrapperRuntimeOptions {
+    force: boolean;
+    deep: boolean;
+    noTui: boolean;
+    includeUserScope: boolean;
+    format?: OutputFormat;
+    configPath?: string;
+}
+export interface ParsedClawhubInvocation {
+    passthroughArgs: string[];
+    wrapper: ClawhubWrapperRuntimeOptions;
+    subcommand: string | null;
+    sourceTarget: string | null;
+    requestedVersion: string | null;
+}
+export interface ClawhubWrapperLaunchResult {
+    status: number | null;
+    error?: Error;
+}
+export interface ExecuteClawhubWrapperInput {
+    version: string;
+    clawhubArgs: string[];
+}
+export interface ClawhubWarningConsentContext {
+    target: string;
+    report: CodeGateReport;
+}
+export interface ClawhubWrapperDeps {
+    cwd: () => string;
+    isTTY: () => boolean;
+    pathExists?: (path: string) => boolean;
+    resolveConfig: (options: ResolveConfigOptions) => CodeGateConfig;
+    runScan: (input: ScanRunnerInput) => Promise<CodeGateReport>;
+    prepareScanDiscovery?: ScanAnalysisDeps["prepareScanDiscovery"];
+    discoverDeepResources?: ScanAnalysisDeps["discoverDeepResources"];
+    discoverLocalTextTargets?: ScanAnalysisDeps["discoverLocalTextTargets"];
+    requestDeepScanConsent?: ScanAnalysisDeps["requestDeepScanConsent"];
+    requestDeepAgentSelection?: ScanAnalysisDeps["requestDeepAgentSelection"];
+    requestMetaAgentCommandConsent?: ScanAnalysisDeps["requestMetaAgentCommandConsent"];
+    runMetaAgentCommand?: ScanAnalysisDeps["runMetaAgentCommand"];
+    executeDeepResource?: ScanAnalysisDeps["executeDeepResource"];
+    resolveScanTarget?: (input: {
+        rawTarget: string;
+        cwd: string;
+        preferredSkill?: string;
+        interactive?: boolean;
+        requestSkillSelection?: (options: string[]) => Promise<string | null> | string | null;
+    }) => Promise<ResolvedScanTarget> | ResolvedScanTarget;
+    stageClawhubTarget?: (input: {
+        sourceTarget: string;
+        requestedVersion?: string;
+        cwd: string;
+    }) => Promise<ResolvedScanTarget> | ResolvedScanTarget;
+    requestWarningProceed?: (context: ClawhubWarningConsentContext) => Promise<boolean> | boolean;
+    launchClawhub: (args: string[], cwd: string) => ClawhubWrapperLaunchResult;
+    stdout: (message: string) => void;
+    stderr: (message: string) => void;
+    setExitCode: (code: number) => void;
+    renderTui?: (props: {
+        view: "dashboard" | "summary";
+        report: CodeGateReport;
+        notices?: string[];
+    }) => void;
+}
+export declare function parseClawhubInvocation(rawArgs: string[], context?: SourceDetectionContext): ParsedClawhubInvocation;
+export declare function launchClawhubPassthrough(args: string[], cwd: string): ClawhubWrapperLaunchResult;
+export declare function executeClawhubWrapper(input: ExecuteClawhubWrapperInput, deps: ClawhubWrapperDeps): Promise<void>;
+export {};