@denial-web/clawguard 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # ClawGuard
 
-Independent governance and security scanner for OpenClaw-style skills and MCP tool configs.
+Security gate and governance scanner for OpenClaw-style skills, ClawHub installs, MCP configs, and agent tools.
 
 ClawGuard helps developers answer one simple question before enabling a skill:
 
@@ -8,6 +8,8 @@ ClawGuard helps developers answer one simple question before enabling a skill:
 
 This project is compatible with OpenClaw-style skill directories, but it is not affiliated with OpenClaw.
 
+ClawGuard is user-triggered today: run it before install, in CI, or as a local review step. It does not yet automatically intercept OpenClaw or ClawHub installs.
+
 ## Demo Preview
 
 [Watch the repeatable demo video](docs/assets/clawguard-demo.mp4), or regenerate it locally with `npm run demo:capture`.
@@ -41,7 +43,15 @@ Run ClawGuard directly from npm:
 npx @denial-web/clawguard scan ./path/to/skill
 ```
 
-Or run the local checkout:
+Use gate mode before installing or trusting a skill:
+
+```bash
+npx @denial-web/clawguard gate ./path/to/skill --policy governed
+```
+
+Gate mode exits with `0` for allow, `1` for warn/review/sandbox decisions, and `2` for block.
+
+When testing the published package, run `npx` from outside this repository. From inside the ClawGuard source checkout, use the local commands instead:
 
 ```bash
 npm test
@@ -172,6 +182,7 @@ Findings:
 ## Roadmap
 
 - `clawguard scan <path>` CLI
+- `clawguard gate <path>` policy gate
 - OpenClaw `SKILL.md` metadata mismatch checks
 - `.clawguard.json` policy/config support
 - MCP/plugin config scanning

package/docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # ClawGuard Architecture
 
-ClawGuard is an independent static governance layer for OpenClaw-style skills, ClawHub packages, and MCP/tool configs. It should stay compatible with OpenClaw without pretending to be OpenClaw.
+ClawGuard is an independent static governance gate for OpenClaw-style skills, ClawHub packages, and MCP/tool configs. It should stay compatible with OpenClaw without pretending to be OpenClaw.
 
 ## Mission
 
@@ -18,11 +18,12 @@ The product should be small, explainable, and useful in three moments:
 
 1. CLI
 
-   Current surface: `clawguard scan <path>`.
+   Current surfaces: `clawguard scan <path>` and `clawguard gate <path>`.
 
    Target surface:
 
    - `clawguard scan <path>`
+   - `clawguard gate <path>`
    - `clawguard scan-skill <skill-dir>`
    - `clawguard scan-workspace <workspace-dir>`
    - `clawguard scan-mcp <config-path>`
@@ -47,7 +48,15 @@ The product should be small, explainable, and useful in three moments:
 
 6. Install gate
 
-   Optional wrapper or integration pattern around OpenClaw/ClawHub install/update flows. It should scan a downloaded bundle before the user enables it.
+   Current surface: `clawguard gate <path>`.
+
+   Gate mode maps scan results into allow, warn, sandbox, or block decisions and exits with install-wrapper friendly codes:
+
+   - `0`: allow
+   - `1`: warn, manual review, sandbox required, or dual approval
+   - `2`: block
+
+   Future surface: wrapper or integration pattern around OpenClaw/ClawHub install/update flows. It should scan a downloaded bundle before the user enables it.
 
 ## Trust Boundaries
 

package/docs/ARCHITECTURE_ROADMAP.md

@@ -99,14 +99,22 @@ Build:
 - Decisions: allow, warn, manual review, sandbox required, dual approval, block.
 - `.clawguard.json` config.
 - Suppressions with reason and optional expiry.
+- Install gate command with policy exit codes.
 - Policy check command for saved reports.
 
 Success demo:
 
 ```bash
+clawguard gate ./skills/my-skill --policy governed
 clawguard scan ./skills --policy governed --fail-on-policy
 ```
 
+Gate exit codes:
+
+- `0`: allow
+- `1`: warn, manual review, sandbox required, or dual approval
+- `2`: block
+
 ## Phase 4: Reports and CI
 
 Goal: make ClawGuard easy to adopt by maintainers.

package/docs/LAUNCH_CHECKLIST.md

@@ -25,8 +25,8 @@ Use this before sharing ClawGuard publicly.
 
 ## GitHub Repository
 
-- [ ] Repo description: `Governance and security scanner for OpenClaw skills, ClawHub installs, MCP configs, and skill dependencies.`
-- [ ] Topics: `openclaw`, `clawhub`, `mcp`, `security`, `ai-agents`, `scanner`, `governance`, `supply-chain`.
+- [x] Repo description: `Governance and security scanner for OpenClaw skills, ClawHub installs, MCP configs, and skill dependencies.`
+- [x] Topics: `openclaw`, `clawhub`, `mcp`, `security`, `ai-agents`, `scanner`, `governance`, `supply-chain`.
 - [x] License is visible.
 - [x] Security policy is visible.
 - [x] GitHub Action example is documented.
@@ -60,5 +60,4 @@ Include:
 
 - Record a short GIF or video using [docs/DEMO_SCRIPT.md](DEMO_SCRIPT.md).
 - Regenerate demo assets with `npm run demo:capture` after visual UI changes.
-- Apply the repository description and topics in GitHub after the repo is created.
 - Validate against real installed skill folders once a public skill archive or local ClawHub install is available.

package/docs/NPM_PUBLISHING.md

@@ -23,7 +23,7 @@ Provider: GitHub Actions
 Organization or user: denial-web
 Repository: clawguard
 Workflow filename: publish.yml
-Environment name: leave blank
+Environment name: blank
 ```
 
 After the trusted publisher is connected, publish from GitHub Actions:
@@ -62,5 +62,13 @@ The release event will trigger `.github/workflows/publish.yml`.
 After publishing, test the package from npm:
 
 ```bash
+cd /private/tmp
 npx @denial-web/clawguard scan examples/risky-skill
 ```
+
+When testing from outside the repository, point the scan command at a real skill path. For example:
+
+```bash
+cd /private/tmp
+npx @denial-web/clawguard scan /Users/hy/CascadeProjects/ClawGuard/examples/risky-skill
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@denial-web/clawguard",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Explainable security scanner for OpenClaw-style skills and MCP tool configs.",
   "type": "module",
   "repository": {

package/src/cli.js

@@ -27,7 +27,7 @@ if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
 
 const command = args[0];
 
-if (!["scan", "scan-workspace"].includes(command)) {
+if (!["scan", "scan-workspace", "gate"].includes(command)) {
   console.error(`Unknown command: ${command}`);
   printHelp();
   process.exit(1);
@@ -54,15 +54,21 @@ try {
     await writeReportFile(options.htmlPath, createHtmlReport(result));
   }
 
-  if (options.json) {
+  if (command === "gate") {
+    if (options.json) {
+      console.log(JSON.stringify(createGateResult(result), null, 2));
+    } else {
+      printGateResult(result, options);
+    }
+  } else if (options.json) {
     console.log(JSON.stringify(result, null, 2));
   } else {
     printHumanResult(result, options);
   }
 
-  process.exit(shouldFail(result, options) ? 2 : 0);
+  process.exit(command === "gate" ? gateExitCode(result.policy.decision) : shouldFail(result, options) ? 2 : 0);
 } catch (error) {
-  console.error(`Scan failed: ${error.message}`);
+  console.error(`${command === "gate" ? "Gate" : "Scan"} failed: ${error.message}`);
   process.exit(1);
 }
 
@@ -71,6 +77,7 @@ function printHelp() {
 
 Usage:
   clawguard scan <path> [--json] [--policy <preset>] [--fail-on <level>]
+  clawguard gate <path> [--json] [--policy <preset>]
   clawguard scan-workspace <path> [--json] [--policy <preset>]
   npm run scan -- <path>
 
@@ -90,7 +97,14 @@ Options:
   --max-file-size <size>  Skip individual files larger than this size. Examples: 512kb, 1mb.
                           Default: 1mb.
 
+Gate exit codes:
+  0 = allow
+  1 = warn, manual review, sandbox required, or dual approval
+  2 = block
+
 Examples:
+  npx @denial-web/clawguard gate ./skills/my-skill
+  npx @denial-web/clawguard gate ./skills/my-skill --policy governed
   npm run scan -- examples/risky-skill
   npm run scan -- examples/metadata-mismatch-skill --policy governed --fail-on-policy
   npm run scan -- examples/metadata-mismatch-skill --html clawguard.html
@@ -171,6 +185,87 @@ function printHumanResult(result, options) {
   }
 }
 
+function printGateResult(result, options) {
+  const decision = result.policy.decision;
+  console.log(`ClawGuard gate: ${result.target}`);
+  console.log(`Decision: ${formatDecision(decision)}`);
+  console.log(`Risk: ${result.level.toUpperCase()} (${result.score}/100)`);
+  console.log(`Policy: ${result.policy.preset}`);
+  console.log(`Exit code: ${gateExitCode(decision)}`);
+  console.log(`Reason: ${result.policy.reason}`);
+
+  if (result.configPath) {
+    console.log(`Config: ${result.configPath}`);
+  }
+
+  if (result.policy.requiredActions.length > 0) {
+    console.log(`Required actions: ${result.policy.requiredActions.join(", ")}`);
+  }
+
+  if (result.findings.length > 0) {
+    console.log(`Findings: ${result.findings.length}`);
+    const topFindings = result.findings.slice(0, 5);
+    for (const finding of topFindings) {
+      console.log(`- [${finding.severity.toUpperCase()}] ${finding.title}`);
+      console.log(`  ${finding.file}:${finding.line}`);
+    }
+
+    if (result.findings.length > topFindings.length) {
+      console.log(`- ${result.findings.length - topFindings.length} more finding(s). Run scan for full details.`);
+    }
+  }
+
+  if (decision === "allow") {
+    console.log("\nGate result: safe to continue under the selected policy.");
+  } else if (decision === "block") {
+    console.log("\nGate result: block install or trust until reviewed.");
+  } else {
+    console.log("\nGate result: pause before install or trust.");
+  }
+}
+
+function createGateResult(result) {
+  return {
+    target: result.target,
+    decision: result.policy.decision,
+    exitCode: gateExitCode(result.policy.decision),
+    risk: {
+      level: result.level,
+      score: result.score
+    },
+    policy: {
+      preset: result.policy.preset,
+      reason: result.policy.reason,
+      requiredActions: result.policy.requiredActions
+    },
+    summary: result.summary,
+    findings: result.findings.map((finding) => ({
+      ruleId: finding.ruleId,
+      severity: finding.severity,
+      title: finding.title,
+      file: finding.file,
+      line: finding.line,
+      recommendation: finding.recommendation
+    }))
+  };
+}
+
+function formatDecision(decision) {
+  return decision.replaceAll("_", " ").toUpperCase();
+}
+
+function gateExitCode(decision) {
+  if (decision === "allow") {
+    return 0;
+  }
+
+  if (decision === "block") {
+    return 2;
+  }
+
+  return 1;
+}
+
 function parseOptions(values) {
   const options = {
     json: false,

package/examples/safe-openclaw-plugin/dist/index.js

@@ -1 +0,0 @@
-export const safe = true;