@opensip-cli/tool-gitleaks 0.1.15

package/dist/tool.d.ts

@@ -0,0 +1,74 @@
+/**
+ * `@opensip-cli/tool-gitleaks` Tool descriptor (ADR-0090 / ADR-0091 / ADR-0092).
+ *
+ * The FIRST External Tool Adapter: it wraps the user-installed `gitleaks` secret
+ * scanner as an ordinary opensip-cli `Tool` via {@link defineExternalToolAdapter}.
+ * The substrate owns binary resolution, the run loop (resolve → execFile → ingest
+ * → normalize → persist via the host artifact seam), secret redaction, provenance,
+ * and the auto-added `doctor`/`version` commands; this module declares only the
+ * gitleaks identity, the wrapped binary, and the `scan` command (args + JSON
+ * parser).
+ *
+ * Layer 4: imports the substrate + `@opensip-cli/core` ONLY — never the CLI,
+ * output, or any other adapter (dependency-cruiser enforced).
+ *
+ * This is an OPT-IN, installed tool (NOT in `bundled-tools.manifest.json`): the
+ * host never imports this runtime; an `opensip gitleaks` invocation forks a worker
+ * that re-discovers + imports it and runs the handler. Installed tools are
+ * deny-by-default — a run needs `OPENSIP_CLI_ALLOW_INSTALLED_TOOLS` to include the
+ * gitleaks id.
+ */
+import type { Tool, ToolIdentity } from '@opensip-cli/core';
+import type { AdapterRunContext } from '@opensip-cli/external-tool-adapter';
+/** Human/aliased identity (`opensip gitleaks` / `opensip secrets`). */
+export declare const GITLEAKS_IDENTITY: ToolIdentity;
+/** Stable UUID identity (ADR-0048); mirrors `opensipTools.stableId` in package.json. */
+export declare const GITLEAKS_STABLE_ID = "cd08f737-ce8e-4813-9259-b4ffeb954268";
+/**
+ * Normalize the `gitleaks version` stdout to a bare semver. Gitleaks prints
+ * either `8.18.4` or `v8.18.4` (and, on some builds, a multi-line banner); take
+ * the first semver-shaped token and strip a leading `v`.
+ *
+ * VERIFY-against-installed-binary: exact `gitleaks version` output format.
+ */
+export declare function parseGitleaksVersion(stdout: string): string;
+/**
+ * Build the gitleaks scan argv (no shell — args are passed to `execFile`). Scans
+ * the project working tree (`detect --no-git --source <root>`) and writes a JSON
+ * report to the host-owned artifact path the substrate composes for this run.
+ *
+ * VERIFY-against-installed-binary: `detect --no-git --source <root>` scans files
+ * on disk (incl. uncommitted) rather than git history; v8.19 renamed the verb to
+ * `gitleaks dir <root>`.
+ */
+export declare function buildScanArgs(ctx: AdapterRunContext): readonly string[];
+/**
+ * A3: build gitleaks's exclusion of opensip's own `.runtime` artifact store.
+ *
+ * gitleaks has NO CLI path-exclude, so we generate a `--config` allowlist that
+ * EXTENDS the default ruleset (secret detection still runs) and allowlists any
+ * file under `opensip-cli/.runtime`. Without this, a raw `Secret`/`Match` in a
+ * prior run's JSON report is re-detected with a new runId in its path → a net-new
+ * message-hash fingerprint every run → permanently degraded `--gate-compare`.
+ *
+ * The leading `# opensip-cli A3 exclude:` marker is load-bearing for the
+ * deterministic worker-E2E fake (it honors the SAME injected exclusion the real
+ * binary reads from the allowlist). VERIFY-against-installed-binary: gitleaks
+ * allowlist `paths` regex semantics (matched against the reported file path).
+ */
+export declare function buildGitleaksExclude(input: {
+    readonly excludePath: string;
+    readonly configPath: (name: string) => string;
+}): {
+    readonly args: readonly string[];
+    readonly configFile: {
+        path: string;
+        contents: string;
+    };
+};
+/**
+ * The gitleaks external-tool adapter `Tool`. The host loads it by name through
+ * the installed-tool worker-dispatch path (the barrel re-exports it as `tool`).
+ */
+export declare const tool: Tool;
+//# sourceMappingURL=tool.d.ts.map

package/dist/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAE5E,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,EAAE,YAG/B,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,kBAAkB,yCAAyC,CAAC;AAEzE;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAK3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,iBAAiB,GAAG,SAAS,MAAM,EAAE,CAWvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CAC/C,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAahG;AAED;;;GAGG;AACH,eAAO,MAAM,IAAI,EAAE,IA2CjB,CAAC"}

package/dist/tool.js

@@ -0,0 +1,140 @@
+/**
+ * `@opensip-cli/tool-gitleaks` Tool descriptor (ADR-0090 / ADR-0091 / ADR-0092).
+ *
+ * The FIRST External Tool Adapter: it wraps the user-installed `gitleaks` secret
+ * scanner as an ordinary opensip-cli `Tool` via {@link defineExternalToolAdapter}.
+ * The substrate owns binary resolution, the run loop (resolve → execFile → ingest
+ * → normalize → persist via the host artifact seam), secret redaction, provenance,
+ * and the auto-added `doctor`/`version` commands; this module declares only the
+ * gitleaks identity, the wrapped binary, and the `scan` command (args + JSON
+ * parser).
+ *
+ * Layer 4: imports the substrate + `@opensip-cli/core` ONLY — never the CLI,
+ * output, or any other adapter (dependency-cruiser enforced).
+ *
+ * This is an OPT-IN, installed tool (NOT in `bundled-tools.manifest.json`): the
+ * host never imports this runtime; an `opensip gitleaks` invocation forks a worker
+ * that re-discovers + imports it and runs the handler. Installed tools are
+ * deny-by-default — a run needs `OPENSIP_CLI_ALLOW_INSTALLED_TOOLS` to include the
+ * gitleaks id.
+ */
+import { readPackageVersion } from '@opensip-cli/core';
+import { defineExternalToolAdapter } from '@opensip-cli/external-tool-adapter';
+import { parseGitleaksJson } from './parse-gitleaks-json.js';
+/** Human/aliased identity (`opensip gitleaks` / `opensip secrets`). */
+export const GITLEAKS_IDENTITY = {
+    name: 'gitleaks',
+    aliases: ['secrets'],
+};
+/** Stable UUID identity (ADR-0048); mirrors `opensipTools.stableId` in package.json. */
+export const GITLEAKS_STABLE_ID = 'cd08f737-ce8e-4813-9259-b4ffeb954268';
+/**
+ * Normalize the `gitleaks version` stdout to a bare semver. Gitleaks prints
+ * either `8.18.4` or `v8.18.4` (and, on some builds, a multi-line banner); take
+ * the first semver-shaped token and strip a leading `v`.
+ *
+ * VERIFY-against-installed-binary: exact `gitleaks version` output format.
+ */
+export function parseGitleaksVersion(stdout) {
+    // Fully bounded ({1,5} digit runs, {1,2} dotted segments) so the matcher is
+    // linear — major.minor[.patch], optional leading `v`.
+    const match = /v?(\d{1,5}(?:\.\d{1,5}){1,2})/.exec(stdout);
+    return match?.[1] ?? stdout.trim();
+}
+/**
+ * Build the gitleaks scan argv (no shell — args are passed to `execFile`). Scans
+ * the project working tree (`detect --no-git --source <root>`) and writes a JSON
+ * report to the host-owned artifact path the substrate composes for this run.
+ *
+ * VERIFY-against-installed-binary: `detect --no-git --source <root>` scans files
+ * on disk (incl. uncommitted) rather than git history; v8.19 renamed the verb to
+ * `gitleaks dir <root>`.
+ */
+export function buildScanArgs(ctx) {
+    return [
+        'detect',
+        '--no-git',
+        '--source',
+        ctx.projectRoot,
+        '--report-format',
+        'json',
+        '--report-path',
+        ctx.artifactPath('gitleaks.json'),
+    ];
+}
+/**
+ * A3: build gitleaks's exclusion of opensip's own `.runtime` artifact store.
+ *
+ * gitleaks has NO CLI path-exclude, so we generate a `--config` allowlist that
+ * EXTENDS the default ruleset (secret detection still runs) and allowlists any
+ * file under `opensip-cli/.runtime`. Without this, a raw `Secret`/`Match` in a
+ * prior run's JSON report is re-detected with a new runId in its path → a net-new
+ * message-hash fingerprint every run → permanently degraded `--gate-compare`.
+ *
+ * The leading `# opensip-cli A3 exclude:` marker is load-bearing for the
+ * deterministic worker-E2E fake (it honors the SAME injected exclusion the real
+ * binary reads from the allowlist). VERIFY-against-installed-binary: gitleaks
+ * allowlist `paths` regex semantics (matched against the reported file path).
+ */
+export function buildGitleaksExclude(input) {
+    const path = input.configPath('gitleaks-exclude.toml');
+    const contents = [
+        '# opensip-cli A3 exclude: opensip-cli/.runtime',
+        '[extend]',
+        'useDefault = true',
+        '',
+        '[allowlist]',
+        'description = "opensip-cli: skip the .runtime artifact store"',
+        "paths = ['''(^|/)opensip-cli/\\.runtime(/|$)''']",
+        '',
+    ].join('\n');
+    return { args: ['--config', path], configFile: { path, contents } };
+}
+/**
+ * The gitleaks external-tool adapter `Tool`. The host loads it by name through
+ * the installed-tool worker-dispatch path (the barrel re-exports it as `tool`).
+ */
+export const tool = defineExternalToolAdapter({
+    identity: GITLEAKS_IDENTITY,
+    metadata: {
+        id: GITLEAKS_STABLE_ID,
+        version: readPackageVersion(import.meta.url),
+        description: 'Secret scanning via Gitleaks',
+        adapterPackage: '@opensip-cli/tool-gitleaks',
+    },
+    binary: {
+        command: 'gitleaks',
+        versionArgs: ['version'],
+        versionParse: parseGitleaksVersion,
+        // `detect --no-git --source` is the stable filesystem-scan invocation; the
+        // renamed `gitleaks dir` verb is v8.19+. VERIFY-against-installed-binary.
+        minVersion: '8.18.0',
+        // Operator pin (config `binaries.gitleaks.path` / `OPENSIP_GITLEAKS_BIN`)
+        // beats PATH; resolution never fetches a binary.
+        resolution: ['config', 'path'],
+        installHint: 'Install gitleaks: https://github.com/gitleaks/gitleaks#installing (brew install gitleaks)',
+    },
+    // Gitleaks scans local files via execFile — no network, no credentials.
+    network: 'local-only',
+    commands: [
+        {
+            name: 'scan',
+            description: 'Scan the project working tree for committed secrets (Gitleaks)',
+            args: buildScanArgs,
+            output: { kind: 'json', path: 'gitleaks.json' },
+            // ADR-0091 Phase-0 decision 4: `0` clean, `1` findings, `>=2` fault. Gitleaks
+            // ALSO exits 1 on an internal fatal — the substrate disambiguates by artifact
+            // presence + JSON-parseability (exit 1 + valid report ⇒ findings; exit 1 +
+            // missing/garbage ⇒ fault).
+            exitCodes: { ok: [0], findings: [1], errorFrom: 2 },
+            parse: parseGitleaksJson,
+            // A3: never re-detect secrets in opensip's OWN persisted reports under
+            // `.runtime/` (see {@link buildGitleaksExclude}).
+            excludeScan: buildGitleaksExclude,
+        },
+    ],
+    // Scanner output is line-volatile → the line-shift-tolerant message hash, not
+    // the host `ruleId|file|line|col` default. Stamped worker-side in the run loop.
+    fingerprintStrategy: 'message-hash',
+});
+//# sourceMappingURL=tool.js.map

package/dist/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,142 @@
+{
+  "name": "@opensip-cli/tool-gitleaks",
+  "version": "0.1.15",
+  "license": "Apache-2.0",
+  "description": "External Tool Adapter for Gitleaks — wraps the gitleaks secret scanner as an opensip-cli tool (opensip gitleaks / opensip secrets)",
+  "keywords": [
+    "opensip-cli",
+    "static-analysis",
+    "code-quality",
+    "security",
+    "gitleaks",
+    "secrets",
+    "scanner"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/opensip-ai/opensip-cli.git",
+    "directory": "packages/tool-gitleaks"
+  },
+  "homepage": "https://github.com/opensip-ai/opensip-cli",
+  "bugs": {
+    "url": "https://github.com/opensip-ai/opensip-cli/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "opensipTools": {
+    "kind": "tool",
+    "id": "gitleaks",
+    "identity": {
+      "name": "gitleaks",
+      "aliases": [
+        "secrets"
+      ]
+    },
+    "stableId": "cd08f737-ce8e-4813-9259-b4ffeb954268",
+    "apiVersion": 1,
+    "requires": [
+      {
+        "resource": "subprocess",
+        "reason": "Executes the user-installed gitleaks binary via execFile (no shell)"
+      },
+      {
+        "resource": "filesystem",
+        "reason": "Reads the project working tree and writes the raw scan artifact under .runtime/artifacts"
+      }
+    ],
+    "commands": [
+      {
+        "name": "gitleaks",
+        "description": "Scan the project working tree for committed secrets (Gitleaks)",
+        "aliases": [
+          "secrets"
+        ],
+        "commonFlags": [
+          "json",
+          "cwd",
+          "quiet",
+          "verbose",
+          "debug",
+          "reportTo",
+          "apiKey",
+          "open"
+        ],
+        "options": [
+          {
+            "flag": "--gate-save",
+            "description": "Architecture-gate: save current findings as baseline in the project SQLite store (mutually exclusive with --gate-compare)",
+            "default": false
+          },
+          {
+            "flag": "--gate-compare",
+            "description": "Architecture-gate: compare current findings against the saved baseline; exit 1 on regression",
+            "default": false
+          }
+        ],
+        "scope": "project",
+        "output": "raw-stream",
+        "rawStreamReason": "runtime-render-dispatch"
+      },
+      {
+        "name": "doctor",
+        "description": "Check that the gitleaks binary is installed and ready",
+        "parent": "gitleaks",
+        "commonFlags": [
+          "json",
+          "cwd"
+        ],
+        "scope": "none",
+        "output": "raw-stream",
+        "rawStreamReason": "diagnostic-gate"
+      },
+      {
+        "name": "version",
+        "description": "Print the resolved gitleaks binary version",
+        "parent": "gitleaks",
+        "commonFlags": [
+          "json",
+          "cwd"
+        ],
+        "scope": "none",
+        "output": "raw-stream",
+        "rawStreamReason": "diagnostic-gate"
+      }
+    ],
+    "config": {
+      "namespace": "gitleaks",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "binaries": {
+            "type": "object"
+          }
+        }
+      }
+    }
+  },
+  "dependencies": {
+    "typescript": "~6.0.3",
+    "@opensip-cli/contracts": "0.1.15",
+    "@opensip-cli/external-tool-adapter": "0.1.15",
+    "@opensip-cli/core": "0.1.15"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.2",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}