pikku-deps

name	pikku-deps
description	Use for the Pikku dependency security audit: the `pikku audit` CLI command, the `.pikku/audit.json` artifact, the `SecurityAuditReport` type in @pikku/core, and the console Security screen (getSecurityAudit / runSecurityAudit / updateDependency + SecurityAuditView). TRIGGER when: user asks about `pikku audit`, dependency vulnerabilities/advisories, outdated dependencies, the Security screen/page in the console, updating a vulnerable dependency, or reading/rendering audit.json. DO NOT TRIGGER when: user asks about authentication/sessions/JWT (use pikku-security), permissions (use pikku-permissions), or secrets/env vars (use pikku-config).
installGroups	["core"]

Pikku Dependency Audit

Agent Operating Procedure

1. The audit is a generated artifact, not live state. pikku audit writes the normalised report to .pikku/audit.json (config outDir), so it rides the same meta pipeline as every other codegen output — uploaded on deploy, readable by the console addon and any tooling. Read it via metaService.readFile('audit.json'), never by shelling out to the package manager from a function.
2. One source of truth for the shape: SecurityAuditReport (and SecurityAuditIssue / SecurityAuditUpdate / SecurityAuditSummary + SecuritySeverity / SecurityUpdateLevel) are exported from @pikku/core. The CLI writes it, the addon reads it, the UI renders it — never redeclare the type at a call site.
3. Validate with pikku all --tsc after changes — it type-checks and fails on type errors, like any real build gate. Separately, pikku audit never fails a build: advisories are informational, and a missing/failed audit yields an empty-but-valid report.

The pikku audit command

• pikku audit — reports security advisories only.
• pikku audit --outdated — also reports available dependency updates.
• Package-manager detection is by lockfile (walks up: bun.lock/bun.lockb, then yarn.lock). Only bun runs a real audit (bun audit --json + bun outdated, normalised into one SecurityAuditReport with per-severity / per-update-level counts). Other PMs are detected but stubbed with a note field until their shapes are normalised — issues/updates come back empty.
• bun audit exits non-zero when it finds advisories but still writes a valid report — treat any non-zero exit as data, not failure.

Console integration (@pikku/addon-console)

Three RPCs, all reading/writing the same artifact via the meta service. Shared spawn/read helpers live in lib/audit-exec.ts (readAuditReport, runPikkuAudit, spawnProcess, findBin) — reuse them, don't re-implement. Like every console RPC these require an authenticated session (the console is admin-only), so the host must have Better Auth wired — see pikku-better-auth.

• getSecurityAudit — reads .pikku/audit.json, returns the report (or null).
• runSecurityAudit — runs pikku audit --outdated server-side (regenerates the artifact) then returns the fresh report. Same shape as the Run Tests action.
• updateDependency({ package, version }) — bumps the package in package.json (preserving the ^/~ range prefix), runs bun install, re-audits, and returns the fresh report. Throws if the package is not a direct dependency. NOTE: bun install must be scoped to a standalone project — do not run it inside a yarn/bun monorepo member (it resolves the whole workspace).

Console UI (@pikku/console)

• SecurityPage — the page: Run audit button (lead) + responsive ShellHeader (structured search + selection for the Issues/Dependencies lens; never cram raw controls into the non-collapsing filters/view escape hatch). Empty state until an audit has run.
• SecurityAuditView — exported presentational component. Two lenses (Issues grouped by severity; Dependencies table). Each finding row carries its actions right-aligned in the row header (Accordion.Control sibling, so a click acts instead of toggling): "View advisory" + a per-finding remediation slot.
• renderRemediation({ pkg, version, issue }) — the extension seam. OSS default is UpdateDependencyButton (the free bump + bun install). Downstream consoles (Fabric) pass their own sandbox-verified action here — replace the action, keep the view.
• Hooks: useSecurityAudit (read), useRunSecurityAudit (run), useUpdateDependency (bump). All are useMutation/useQuery — surface mutation.error, never hand-roll loading/error state or swallow the error.

Report shape (SecurityAuditReport)

{
  tool: string                 // e.g. 'bun'
  note?: string                // set when the audit could NOT run (unsupported PM);
                               // render ONLY the note — never a reassuring "no vulnerabilities"
  summary: { critical, high, moderate, low, info: number }
  issues: SecurityAuditIssue[] // package, severity, title, advisoryId, cwe[], cvssScore?,
                               // url?, vulnerableVersions, recommendedVersion?
  updates: SecurityAuditUpdate[] // package, current, latest, level (major|minor|patch|unknown)
}

When note is present the audit did not run — show only the note (an "Audit not run" state), never the "no known vulnerabilities / up to date" copy.