@hackaiz/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# Hackaiz CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Paquet préparé, non publié sur npm. Node 22 ou supérieur.
+
+```sh
+export HACKAIZ_API_KEY='votre clé personnelle'
+node bin/hackaiz.mjs analyze UUID_PLATEFORME CLE_DE_DEMANDE_STABLE
+node bin/hackaiz.mjs status UUID_PLATEFORME UUID_DEMANDE
+node bin/hackaiz.mjs verify UUID_PLATEFORME UUID_DEMANDE
+node bin/hackaiz.mjs report UUID_PLATEFORME
+node bin/hackaiz.mjs findings UUID_PLATEFORME
+```
+
+La clé doit autoriser la lecture et le lancement pour la plateforme. Analyse passive seulement, propriété et consentement actuels exigés, crédits normaux. Aucun correctif publié, aucune fusion. Le client demande le traitement autonome puis consulte son état, sans appel d'exécution ni clic dans Hackaiz. Le service doit être publié et synchronisé avec Inngest pour démarrer effectivement les demandes. En cas de perte de connexion, consulter la même demande plutôt que créer une nouvelle demande. Une analyse déjà commencée n'est jamais rejouée automatiquement après interruption. Une analyse partielle ne démontre pas une couverture complète.
+
+`npm pack --dry-run` permet d'inspecter le paquet avant publication par un éditeur autorisé. Ne jamais enregistrer de clé dans le dépôt ou les journaux.
+
+`verify` lit seulement le rapport explicitement lié à la demande : analyse complète obligatoire, constats de cette analyse paginés. Il renvoie 0 sans High/Critical non résolu, 1 si de tels constats existent, 2 si incomplet/indisponible. Ce contrôle de la plateforme enregistrée n'est pas une vérification du commit de PR/déploiement ; ne pas le présenter comme telle.
+## Check before installing
+
+```sh
+hackaiz check ./my-skill            # Skill folder, MCP config, package.json, workflow or Dockerfile
+hackaiz check . --sarif > hackaiz.sarif   # CI: exit code 2 on a Danger verdict
+```
+
+### Claude Code hook (automatic check before a Skill, MCP or install command)
+
+Add to `.claude/settings.json` (with `HACKAIZ_API_KEY` set in your environment):
+
+```json
+{ "hooks": { "PreToolUse": [ { "matcher": "Write|Edit|MultiEdit|Bash", "hooks": [ { "type": "command", "command": "hackaiz hook claude" } ] } ] } }
+```
+
+Only Skill/MCP/package/workflow writes and install commands are checked, and each new check uses credits, including unchanged content. Enabling this hook opts into paid checks before these actions; it is not background monitoring. A Danger verdict blocks the action. An incomplete response, missing key, service error or exhausted credits also blocks it: no missing verdict is treated as approval. Set `HACKAIZ_HOOK_FAIL_OPEN=1` only to explicitly choose advisory mode during failures. This hook checks submitted text, not all installed package code or runtime behaviour.

package/bin/check.mjs

@@ -0,0 +1,59 @@
+// `hackaiz check <path> [--sarif]`: static check of a Skill / MCP / package / workflow before installing.
+// Exit 2 on a Danger verdict so CI can block. Secret, binary and generated files are never sent.
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative, basename } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const SKIP_DIR = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.venv', 'venv', '__pycache__']);
+const SECRET = /(^|\/)(\.env(\..*)?|.*\.(pem|key|p12|pfx|keystore|jks)|id_rsa|id_ed25519|\.npmrc|\.netrc)$/i;
+const BINARY = /\.(png|jpe?g|gif|webp|ico|pdf|zip|gz|tgz|exe|dll|so|dylib|wasm|woff2?|ttf|mp[34]|lockb|bin)$/i;
+
+export async function collectComponent(root, { maxFiles = 400, maxFileBytes = 400 * 1024 } = {}) {
+  const files = []; const skipped = [];
+  const s = await stat(root);
+  const walk = async (dir) => {
+    for (const e of await readdir(dir, { withFileTypes: true })) {
+      if (files.length >= maxFiles) return;
+      const full = join(dir, e.name);
+      if (e.isDirectory()) { if (!SKIP_DIR.has(e.name)) await walk(full); continue; }
+      const rel = relative(root, full).replace(/\\/g, '/');
+      const size = (await stat(full)).size;
+      if (SECRET.test(rel) || BINARY.test(rel) || size > maxFileBytes) { skipped.push(rel); continue; }
+      const content = await readFile(full, 'utf8');
+      if (content.includes('\u0000')) { skipped.push(rel); continue; }
+      files.push({ path: rel, content });
+    }
+  };
+  if (s.isDirectory()) await walk(root);
+  else if (!SECRET.test(root)) files.push({ path: basename(root), content: await readFile(root, 'utf8') });
+  return { files, skipped };
+}
+
+export function toSarif(result) {
+  const level = (s) => (s === 'Critical' || s === 'High' ? 'error' : s === 'Medium' ? 'warning' : 'note');
+  return {
+    version: '2.1.0', $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    runs: [{
+      tool: { driver: { name: 'Hackaiz Import Gate', informationUri: 'https://hackaiz.com/check', rules: [...new Map((result.findings ?? []).map((f) => [f.rule, { id: f.rule, shortDescription: { text: f.title }, help: { text: f.action }, properties: { cwe: f.cwe, owasp: f.owasp } }])).values()] } },
+      results: (result.findings ?? []).map((f) => ({ ruleId: f.rule, level: level(f.severity), message: { text: `${f.title}: ${f.impact}` }, locations: [{ physicalLocation: { artifactLocation: { uri: f.file }, region: { startLine: f.line } } }] })),
+    }],
+  };
+}
+
+export async function checkCommand(target, flags, { env, fetcher, output }) {
+  if (!target) throw Error('Usage: hackaiz check <path> [--sarif] [--lang fr]');
+  const origin = new URL(env.HACKAIZ_URL ?? 'https://hackaiz.com');
+  if (origin.protocol !== 'https:' || origin.pathname !== '/' || origin.username) throw Error('HACKAIZ_URL must be an HTTPS origin');
+  if (!/^hkz_[A-Za-z0-9_-]{40,}$/.test(env.HACKAIZ_API_KEY ?? '')) throw Error('HACKAIZ_API_KEY is required');
+  const { files } = await collectComponent(target);
+  if (!files.length) throw Error('Nothing to check (secret, binary and large files are never sent)');
+  const lang = flags.includes('--lang') && flags[flags.indexOf('--lang') + 1] === 'fr' ? 'fr' : 'en';
+  const response = await fetcher(`${origin.origin}/api/public/v1/component-checks`, {
+    method: 'POST', redirect: 'error', headers: { authorization: `Bearer ${env.HACKAIZ_API_KEY}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ request_id: randomUUID(), channel: env.GITHUB_ACTIONS === 'true' ? 'ci' : 'cli', name: basename(target).slice(0, 120) || 'component', language: lang, files }),
+  });
+  const data = await response.json();
+  if (!response.ok) throw Error(`Hackaiz ${response.status}: ${data.error ?? 'request_failed'}`);
+  output(JSON.stringify(flags.includes('--sarif') ? toSarif(data) : data, null, 2));
+  return data.verdict === 'danger' ? 2 : 0;
+}

package/bin/gate.mjs

@@ -0,0 +1,6 @@
+/** A gate refers to one saved-platform run, never to an inferred PR commit. */
+export function savedRunGate(analysis, findings) {
+  if (analysis?.status !== 'success') return { verdict: 'inconclusive', reason: 'analysis_not_complete', exitCode: 2 };
+  const dangerous = findings.filter(f => ['critical', 'high'].includes(String(f.severity).toLowerCase()) && f.status !== 'resolved');
+  return dangerous.length ? { verdict: 'fail', unresolvedHighOrCritical: dangerous.length, exitCode: 1 } : { verdict: 'pass', unresolvedHighOrCritical: 0, exitCode: 0 };
+}

package/bin/hackaiz.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { randomUUID } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+import { savedRunGate } from './gate.mjs';
+
+export async function run(args, { env = process.env, fetcher = fetch, output = console.log, stdin, errorOut, wait = (ms) => new Promise(resolve => setTimeout(resolve, ms)) } = {}) {
+  const [command, projectId, value] = args;
+  if (command === 'help' || !command) {
+    output('hackaiz analyze <project-id> [request-key]\nhackaiz status <project-id> <run-id>\nhackaiz verify <project-id> <run-id>\nhackaiz report <project-id>\nhackaiz findings <project-id>\nhackaiz check <path> [--sarif] [--lang fr]  (Skill/MCP/package/workflow before installing; exit 2 on Danger)\nhackaiz hook claude  (Claude Code PreToolUse hook: blocks Danger Skills/MCP/installs)\nHACKAIZ_API_KEY: personal key. HACKAIZ_URL: optional HTTPS origin.');
+    return 0;
+  }
+  if (command === 'hook') {
+    const { hookCommand } = await import('./hook.mjs');
+    const chunks = []; for await (const c of (stdin ?? process.stdin)) chunks.push(c);
+    return hookCommand({ env, fetcher, stdin: Buffer.concat(chunks.map((c) => Buffer.from(c))).toString('utf8'), errorOut: errorOut ?? console.error });
+  }
+  if (command === 'check') {
+    const { checkCommand } = await import('./check.mjs');
+    return checkCommand(projectId, args.slice(2), { env, fetcher, output });
+  }
+  if (!['analyze', 'status', 'verify', 'report', 'findings'].includes(command)) throw Error('Unsupported command');
+  if (!/^[0-9a-f-]{36}$/i.test(projectId ?? '')) throw Error('A platform UUID is required');
+  const origin = new URL(env.HACKAIZ_URL ?? 'https://hackaiz.com');
+  if (origin.protocol !== 'https:' || origin.username || origin.password || origin.pathname !== '/' || origin.search || origin.hash) throw Error('HACKAIZ_URL must be an HTTPS origin');
+  if (!/^hkz_[A-Za-z0-9_-]{40,}$/.test(env.HACKAIZ_API_KEY ?? '')) throw Error('HACKAIZ_API_KEY is required');
+  const base = `${origin.origin}/api/public/v1/projects/${projectId}`;
+  const call = async (path, body) => {
+    const response = await fetcher(`${base}/${path}`, { method: body ? 'POST' : 'GET', headers: { authorization: `Bearer ${env.HACKAIZ_API_KEY}`, 'content-type': 'application/json' }, ...(body ? { body: JSON.stringify(body) } : {}), redirect: 'error' });
+    const data = await response.json();
+    if (!response.ok) throw Error(`Hackaiz ${response.status}: ${data.error ?? 'request_failed'}${data.purchaseUrl ? ` — ${data.purchaseUrl}` : ''}`);
+    return data;
+  };
+  if (command === 'analyze') {
+    const requestKey = value ?? randomUUID();
+    const accepted = await call('analysis-requests', { request_key: requestKey, channel: env.GITHUB_ACTIONS === 'true' ? 'ci' : 'cli' });
+    if (!/^[0-9a-f-]{36}$/i.test(accepted.requestId ?? '')) throw Error('Invalid analysis response');
+    output(JSON.stringify({ requestId: accepted.requestId, requestKey, status: accepted.status }));
+    if (accepted.delivery === 'configuration_required') throw Error('Autonomous processing is not configured; keep this request ID');
+    // GET-only polling. Closing the client does not cancel autonomous work.
+    // A lost response never creates another run or invokes execution again.
+    for (let attempt = 0; attempt < 360; attempt++) {
+      const result = await call(`analysis-runs/${accepted.requestId}`);
+      const status = result.request?.status;
+      if (['success', 'partial', 'failed', 'cancelled'].includes(status)) {
+        output(JSON.stringify(result));
+        return ['success', 'partial'].includes(status) ? 0 : 2;
+      }
+      await wait(5000);
+    }
+    output(JSON.stringify({ requestId: accepted.requestId, status: 'still_pending', note: 'Use status with the same request ID; do not create a replacement.' }));
+    return 2;
+  }
+  if (command === 'status') {
+    if (!/^[0-9a-f-]{36}$/i.test(value ?? '')) throw Error('A run UUID is required');
+    output(JSON.stringify(await call(`analysis-runs/${value}`))); return 0;
+  }
+  if (command === 'verify') {
+    if (!/^[0-9a-f-]{36}$/i.test(value ?? '')) throw Error('A run UUID is required');
+    const status = await call(`analysis-runs/${value}`);
+    const scan = status.analysis;
+    if (!scan || !/^[0-9a-f-]{36}$/i.test(scan.id ?? '') || status.request?.scan_id !== scan.id || scan.status !== 'success') {
+      output(JSON.stringify({ verdict: 'inconclusive', reason: 'analysis_not_complete_or_unlinked', runId: value }));
+      return 2;
+    }
+    const findings = []; const seen = new Set(); let offset = 0; let total;
+    for (;;) {
+      const result = await call(`findings?scanId=${scan.id}&status=open&limit=100&offset=${offset}`);
+      const invalid = !Array.isArray(result.data) || !Number.isSafeInteger(result.total) || result.total < 0 || result.total > 100000 || (total !== undefined && result.total !== total)
+        || result.data.length > 100 || offset + result.data.length > result.total || (!result.data.length && offset < result.total)
+        || result.data.some(f => !f || f.scan_id !== scan.id || typeof f.id !== 'string' || !f.id || seen.has(f.id) || !['critical', 'high', 'medium', 'low', 'info'].includes(String(f.severity).toLowerCase()) || f.status !== 'open');
+      if (invalid || (Array.isArray(result.data) && new Set(result.data.map(f => f.id)).size !== result.data.length)) {
+        output(JSON.stringify({ verdict: 'inconclusive', reason: 'invalid_findings_pagination', runId: value, scanId: scan.id }));
+        return 2;
+      }
+      total = result.total;
+      result.data.forEach(f => seen.add(f.id));
+      findings.push(...result.data); offset += result.data.length;
+      if (offset === total) break;
+    }
+    const verdict = savedRunGate(scan, findings);
+    output(JSON.stringify({ ...verdict, runId: value, scanId: scan.id, scope: 'saved_platform_not_pr_commit' }));
+    return verdict.exitCode;
+  }
+  let offset = 0;
+  do {
+    const result = await call(`${command === 'report' ? 'scans' : 'findings'}?limit=100&offset=${offset}`);
+    output(JSON.stringify(result));
+    offset += result.data?.length ?? 0;
+    if (!result.data?.length || offset >= result.total) break;
+  } while (true);
+  return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  run(process.argv.slice(2)).then((code) => { process.exitCode = code; }).catch((error) => { console.error(error.message); process.exitCode = 1; });
+}

package/bin/hook.mjs

@@ -0,0 +1,47 @@
+// Claude Code PreToolUse hook: `hackaiz hook claude`. Reads the hook JSON on stdin.
+// Only Skill/MCP/package/workflow writes and install commands are checked (each check uses credits).
+// Exit 2 blocks Danger, incomplete or unavailable checks. HACKAIZ_HOOK_FAIL_OPEN=1 explicitly opts into advisory mode.
+import { randomUUID } from 'node:crypto';
+const COMPONENT = /(^|\/)(SKILL\.md|mcp\.json|\.mcp\.json|claude_desktop_config\.json|package\.json|requirements\.txt|Dockerfile)$|\.github\/workflows\/[^/]+\.ya?ml$/i;
+const INSTALL = /\b(claude\s+mcp\s+add|npx\s+-y|npm\s+(i|install|add)\b|pnpm\s+add|yarn\s+add|bun\s+add|pip3?\s+install|uvx|pipx\s+install)\b|\b(curl|wget)\b[^|]*\|\s*(ba|z)?sh\b/i;
+
+export function hookTarget(event) {
+  const tool = event?.tool_name; const input = event?.tool_input ?? {};
+  if (['Write', 'Edit', 'MultiEdit'].includes(tool) && typeof input.file_path === 'string' && COMPONENT.test(input.file_path.replace(/\\/g, '/'))) {
+    const content = tool === 'Write' ? input.content : tool === 'Edit' ? input.new_string : (input.edits ?? []).map((e) => e.new_string).join('\n');
+    if (typeof content === 'string' && content) return { name: input.file_path.split(/[\\/]/).slice(-2).join('/'), files: [{ path: input.file_path.split(/[\\/]/).pop(), content }] };
+  }
+  if (tool === 'Bash' && typeof input.command === 'string' && INSTALL.test(input.command)) return { name: 'install-command', files: [{ path: 'install.sh', content: input.command }] };
+  return null;
+}
+
+export async function hookCommand({ env, fetcher, stdin, errorOut }) {
+  const fr = env.HACKAIZ_LANG === 'fr';
+  const unavailable = (detail = '') => {
+    errorOut(fr ? `Vérification Hackaiz indisponible${detail} ; action non vérifiée.` : `Hackaiz check unavailable${detail}; action not checked.`);
+    return env.HACKAIZ_HOOK_FAIL_OPEN === '1' ? 0 : 2;
+  };
+  let event; try { event = JSON.parse(stdin); } catch { return unavailable(); }
+  const target = hookTarget(event);
+  if (!target) return 0;
+  if (!/^hkz_[A-Za-z0-9_-]{40,}$/.test(env.HACKAIZ_API_KEY ?? '')) return unavailable();
+  try {
+    const origin = new URL(env.HACKAIZ_URL ?? 'https://hackaiz.com');
+    if (origin.protocol !== 'https:' || origin.username || origin.password || origin.pathname !== '/' || origin.search || origin.hash) return unavailable();
+    // Opting into this hook authorizes paid checks, not automatic installation on a missing verdict.
+    const r = await fetcher(`${origin.origin}/api/public/v1/component-checks`, {
+      method: 'POST', redirect: 'error', headers: { authorization: `Bearer ${env.HACKAIZ_API_KEY}`, 'content-type': 'application/json' },
+      signal: AbortSignal.timeout(30_000),
+      body: JSON.stringify({ request_id: randomUUID(), channel: 'hook', name: target.name.slice(0, 120), language: env.HACKAIZ_LANG === 'fr' ? 'fr' : 'en', files: target.files }),
+    });
+    const data = await r.json();
+    if (!r.ok) return unavailable(` (${r.status})`);
+    if (data.verdict === 'danger') {
+      errorOut(`${fr ? 'Hackaiz bloque cette action' : 'Hackaiz blocked this'}: ${data.headline}. ${data.summary} ${(data.findings ?? []).slice(0, 3).map((f) => `[${f.rule}] ${f.title} (${f.file}:${f.line})`).join(' ')}`);
+      return 2;
+    }
+    if (data.complete !== true || !['safe', 'attention'].includes(data.verdict)) return unavailable();
+    if (data.verdict === 'attention') errorOut(`${data.headline}. ${data.summary}`);
+    return 0;
+  } catch { return unavailable(); }
+}

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@hackaiz/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Authenticated Hackaiz passive analysis client",
+  "type": "module",
+  "bin": { "hackaiz": "bin/hackaiz.mjs" },
+  "files": ["bin", "README.md"],
+  "engines": { "node": ">=22" },
+  "scripts": { "test": "node --test test/*.check.mjs" }
 }