@ikon85/agent-workflow-kit 0.23.0 → 0.25.0

package/scripts/safety-guardrails/search.py

@@ -0,0 +1,92 @@
+"""Verified search-shim breaker detection."""
+
+from __future__ import annotations
+
+import shlex
+
+OPERATORS = {"|", "||", "&&", ";", "&", "|&"}
+
+
+def _count_unescaped(value: str, character: str) -> int:
+    count = index = 0
+    while index < len(value):
+        if value[index] == "\\":
+            index += 2
+            continue
+        if value[index] == character:
+            count += 1
+        index += 1
+    return count
+
+
+def _pattern_and_flags(args: list[str]) -> tuple[str | None, set[str]]:
+    pattern = None
+    flags = set()
+    after_options = False
+    index = 0
+    while index < len(args):
+        value = args[index]
+        if value == "--":
+            after_options = True
+        elif not after_options and value in {"-e", "--regexp"}:
+            index += 1
+            if index < len(args) and pattern is None:
+                pattern = args[index]
+        elif not after_options and value.startswith("--regexp="):
+            if pattern is None:
+                pattern = value.split("=", 1)[1]
+        elif not after_options and value.startswith("-"):
+            flags.add(value)
+        elif pattern is None:
+            pattern = value
+        index += 1
+    return pattern, flags
+
+
+def _has_flag(flags: set[str], letter: str, long: str) -> bool:
+    return long in flags or any(
+        flag.startswith("-") and not flag.startswith("--") and letter in flag[1:]
+        for flag in flags
+    )
+
+
+def _breaker(pattern: str, flags: set[str]) -> str | None:
+    if _has_flag(flags, "F", "--fixed-strings"):
+        return None
+    if _count_unescaped(pattern, "(") != _count_unescaped(pattern, ")"):
+        return "unbalanced parentheses"
+    extended = _has_flag(flags, "E", "--extended-regexp") or _has_flag(
+        flags, "P", "--perl-regexp"
+    )
+    if not extended and _count_unescaped(pattern, "|"):
+        return "bare alternation without extended-regexp mode"
+    return None
+
+
+def scan(command: str, command_names: set[str]) -> tuple[str, str] | None:
+    try:
+        tokens = shlex.split(command, posix=True)
+    except ValueError:
+        return None
+    index = 0
+    while index < len(tokens):
+        token = tokens[index]
+        shim = token in command_names
+        if token == "grep" and index and tokens[index - 1] in {"command", "git"}:
+            shim = False
+        if token == "grep" and index and tokens[index - 1] == "rtk":
+            shim = True
+        if not shim:
+            index += 1
+            continue
+        end = index + 1
+        args = []
+        while end < len(tokens) and tokens[end] not in OPERATORS:
+            args.append(tokens[end])
+            end += 1
+        pattern, flags = _pattern_and_flags(args)
+        reason = _breaker(pattern, flags) if pattern is not None else None
+        if reason:
+            return reason, pattern
+        index = end
+    return None

package/scripts/security/audit-gate.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'node:url';
+
+const SEVERITIES = ['info', 'low', 'moderate', 'high', 'critical'];
+
+function emptyCounts() {
+  return Object.fromEntries(SEVERITIES.map((severity) => [severity, 0]));
+}
+
+function normalizedCounts(input) {
+  const counts = emptyCounts();
+  for (const severity of SEVERITIES) {
+    const value = Number(input?.[severity] ?? 0);
+    if (!Number.isInteger(value) || value < 0) throw new Error('invalid vulnerability count');
+    counts[severity] = value;
+  }
+  return counts;
+}
+
+function parseJson(input) {
+  return JSON.parse(input);
+}
+
+function countsFromAdvisories(data) {
+  const counts = emptyCounts();
+  for (const advisories of Object.values(data)) {
+    if (!Array.isArray(advisories)) throw new Error('invalid advisory collection');
+    for (const advisory of advisories) {
+      const severity = advisory?.severity;
+      if (!SEVERITIES.includes(severity)) throw new Error('invalid advisory severity');
+      counts[severity] += 1;
+    }
+  }
+  return counts;
+}
+
+function parseAudit(manager, input) {
+  let data;
+  try {
+    data = parseJson(input);
+  } catch (error) {
+    if (manager !== 'yarn') throw error;
+    const events = input.trim().split(/\r?\n/).map(parseJson);
+    const summary = events.find((event) => event?.type === 'auditSummary');
+    if (!summary?.data?.vulnerabilities) throw error;
+    return {
+      counts: normalizedCounts(summary.data.vulnerabilities),
+      data: summary,
+    };
+  }
+  if (manager === 'npm' || manager === 'pnpm') {
+    if (data?.error && typeof data.error === 'object') {
+      return { counts: emptyCounts(), data };
+    }
+    if (!data?.metadata?.vulnerabilities) throw new Error('missing metadata.vulnerabilities');
+    return { counts: normalizedCounts(data.metadata.vulnerabilities), data };
+  }
+  if (manager === 'yarn' || manager === 'bun') {
+    if (data?.error && typeof data.error === 'object') {
+      return { counts: emptyCounts(), data };
+    }
+    return { counts: countsFromAdvisories(data), data };
+  }
+  throw new Error(`unsupported package manager: ${manager}`);
+}
+
+export function auditCommand(manager) {
+  const commands = {
+    npm: ['npm', 'audit', '--omit=dev', '--json'],
+    pnpm: ['pnpm', 'audit', '--prod', '--json'],
+    yarn: ['yarn', 'npm', 'audit', '--environment', 'production', '--recursive', '--json'],
+    bun: ['bun', 'audit', '--prod', '--json'],
+  };
+  if (!commands[manager]) throw new Error(`unsupported package manager: ${manager}`);
+  return commands[manager];
+}
+
+export function evaluateAudit({
+  manager,
+  input,
+  serviceOutage = 'warn',
+  blockingSeverities = ['high', 'critical'],
+}) {
+  let parsed;
+  try {
+    parsed = parseAudit(manager, input);
+  } catch (error) {
+    return { status: 'malformed', exitCode: 2, message: error.message };
+  }
+
+  if (parsed.data?.error && typeof parsed.data.error === 'object') {
+    return serviceOutage === 'block'
+      ? { status: 'service-outage-blocked', exitCode: 3 }
+      : { status: 'service-outage-warning', exitCode: 0 };
+  }
+
+  const isBlocking = blockingSeverities.some((severity) => parsed.counts[severity] > 0);
+  return {
+    status: isBlocking ? 'blocking-findings' : 'passed',
+    exitCode: isBlocking ? 1 : 0,
+    counts: parsed.counts,
+  };
+}
+
+async function main() {
+  const manager = process.argv[2];
+  const serviceOutageArg = process.argv.find((arg) => arg.startsWith('--service-outage='));
+  const serviceOutage = serviceOutageArg?.split('=', 2)[1] ?? 'warn';
+  let input = '';
+  for await (const chunk of process.stdin) input += chunk;
+  const verdict = evaluateAudit({ manager, input, serviceOutage });
+  const output = JSON.stringify(verdict);
+  (verdict.exitCode === 0 ? console.log : console.error)(output);
+  process.exitCode = verdict.exitCode;
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(JSON.stringify({ status: 'malformed', message: error.message }));
+    process.exitCode = 2;
+  });
+}

package/scripts/security/ensure-gitleaks.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  chmod, copyFile, mkdir, mkdtemp, readFile, rename, rm, unlink, writeFile,
+} from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+const exec = promisify(execFile);
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const DEFAULT_GITLEAKS_PROFILE = JSON.parse(
+  await readFile(join(HERE, 'gitleaks-profile.json'), 'utf8'),
+);
+
+async function defaultIsAvailable() {
+  try {
+    await exec('gitleaks', ['version']);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function defaultFetchArchive(url) {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`download returned HTTP ${response.status}`);
+  return Buffer.from(await response.arrayBuffer());
+}
+
+async function defaultInstallArchive({ bytes, destination }) {
+  const scratch = await mkdtemp(join(tmpdir(), 'awkit-gitleaks-'));
+  const archive = join(scratch, 'gitleaks.tar.gz');
+  const extracted = join(scratch, 'gitleaks');
+  const staged = `${destination}.tmp-${process.pid}`;
+  try {
+    await writeFile(archive, bytes);
+    await exec('tar', ['-xzf', archive, '-C', scratch, 'gitleaks']);
+    await mkdir(dirname(destination), { recursive: true });
+    await copyFile(extracted, staged);
+    await chmod(staged, 0o755);
+    await rename(staged, destination);
+  } finally {
+    await unlink(staged).catch(() => {});
+    await rm(scratch, { recursive: true, force: true });
+  }
+}
+
+export async function ensureGitleaks({
+  profile = DEFAULT_GITLEAKS_PROFILE,
+  platform = process.platform,
+  arch = process.arch,
+  destination = join(homedir(), '.local', 'bin', 'gitleaks'),
+  isAvailable = defaultIsAvailable,
+  fetchArchive = defaultFetchArchive,
+  installArchive = defaultInstallArchive,
+} = {}) {
+  if (await isAvailable()) return { status: 'already-available' };
+
+  const target = profile.platforms?.[`${platform}-${arch}`];
+  if (!target?.asset || !/^[a-f0-9]{64}$/i.test(target.sha256 ?? '')) {
+    return { status: 'unsupported-platform', platform, arch };
+  }
+
+  const url = `${profile.baseUrl ?? ''}/${target.asset}`;
+  let bytes;
+  try {
+    bytes = await fetchArchive(url);
+  } catch (error) {
+    return { status: 'offline', message: error.message };
+  }
+
+  const actual = createHash('sha256').update(bytes).digest('hex');
+  if (actual !== target.sha256.toLowerCase()) {
+    return { status: 'checksum-mismatch', expected: target.sha256, actual };
+  }
+
+  try {
+    await installArchive({ bytes, destination, asset: target.asset });
+  } catch (error) {
+    return { status: 'unwritable', message: error.message };
+  }
+  return { status: 'installed', destination, version: profile.version };
+}
+
+async function main() {
+  const result = await ensureGitleaks({ destination: process.argv[2] });
+  if (result.status === 'installed' || result.status === 'already-available') {
+    console.log(`Gitleaks provisioning: ${result.status}.`);
+  } else {
+    console.error(`Gitleaks provisioning skipped safely: ${result.status}.`);
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`Gitleaks provisioning failed safely: ${error.message}`);
+  });
+}

package/scripts/security/gitleaks-profile.json

@@ -0,0 +1,14 @@
+{
+  "version": "8.30.1",
+  "baseUrl": "https://github.com/gitleaks/gitleaks/releases/download/v8.30.1",
+  "platforms": {
+    "linux-x64": {
+      "asset": "gitleaks_8.30.1_linux_x64.tar.gz",
+      "sha256": "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb"
+    },
+    "linux-arm64": {
+      "asset": "gitleaks_8.30.1_linux_arm64.tar.gz",
+      "sha256": "e4a487ee7ccd7d3a7f7ec08657610aa3606637dab924210b3aee62570fb4b080"
+    }
+  }
+}

package/scripts/security/install-git-hooks.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+const exec = promisify(execFile);
+
+async function defaultRunGit(cwd, args) {
+  const result = await exec('git', args, { cwd });
+  return result.stdout.trim();
+}
+
+export async function installGitHooks({
+  cwd = process.cwd(),
+  hooksPath = '.githooks',
+  runGit = defaultRunGit,
+} = {}) {
+  try {
+    await runGit(cwd, ['rev-parse', '--is-inside-work-tree']);
+  } catch (error) {
+    if (error?.code === 128) return { status: 'not-a-repository' };
+    throw error;
+  }
+
+  let current = '';
+  try {
+    current = await runGit(cwd, ['config', '--get', 'core.hooksPath']);
+  } catch (error) {
+    if (error?.code !== 1) throw error;
+  }
+  if (current === hooksPath) return { status: 'unchanged', hooksPath };
+
+  await runGit(cwd, ['config', 'core.hooksPath', hooksPath]);
+  return { status: 'wired', hooksPath };
+}
+
+async function main() {
+  const hooksPath = process.argv[2] ?? '.githooks';
+  const result = await installGitHooks({ hooksPath });
+  if (result.status === 'not-a-repository') {
+    console.log('Git hooks not wired: current directory is not a Git work tree.');
+    return;
+  }
+  console.log(`Git hooks ${result.status}: core.hooksPath=${result.hooksPath}`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`Git hook wiring failed: ${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/scripts/workflow-advisories/capabilities.json

@@ -0,0 +1,33 @@
+{
+  "version": 1,
+  "capabilities": [
+    {
+      "profileKey": "largeRead",
+      "artifact": ".claude/hooks/recon-size-hint.py"
+    },
+    {
+      "profileKey": "baseline",
+      "artifact": ".claude/hooks/baseline-capture-hint.py"
+    },
+    {
+      "profileKey": "preRefactor",
+      "artifact": ".claude/hooks/pre-refactor-sweep.py"
+    },
+    {
+      "profileKey": "stopChecks",
+      "artifact": ".claude/hooks/typecheck-on-stop.sh"
+    },
+    {
+      "profileKey": "freshness",
+      "artifact": ".claude/hooks/convention-drift-hint.py"
+    },
+    {
+      "profileKey": "migration",
+      "artifact": ".claude/hooks/migration-snapshot-reminder.py"
+    },
+    {
+      "profileKey": "locForewarn",
+      "artifact": ".claude/hooks/loc-offender-forewarn.py"
+    }
+  ]
+}