clud-bug 0.6.34 → 0.7.0-rc.1

package/{lib/agents-md.js → src/cli/agents-md.ts}

@@ -31,6 +31,12 @@ const TOUCH_IF_PRESENT = [
   '.continuerules',
 ];
 
+export interface RenderBlockOptions {
+  version?: string | undefined;
+  strictMode?: boolean | undefined;
+  skillRelPath?: string | undefined;
+}
+
 // Render the clud-bug block. Bundled here rather than in a template file so
 // updates ship with the CLI itself.
 //
@@ -52,7 +58,7 @@ const TOUCH_IF_PRESENT = [
 // path `.claude/skills/...`), render the LOCAL repo path. Otherwise the
 // link is dead in the publisher repo (this used to require a manual fix
 // every v0.6.* propagation cycle on agent-skills).
-export function renderBlock({ version, strictMode, skillRelPath } = {}) {
+export function renderBlock({ version, strictMode, skillRelPath }: RenderBlockOptions = {}): string {
   const versionLine = version ? `_Installed at clud-bug v${version}._` : '';
   const strictNote = strictMode === true
     ? '**on** in this repo (workflow check fails on critical findings)'
@@ -85,7 +91,7 @@ ${END_MARKER}`;
 // in the working tree, the AGENTS.md link should point there, not at the
 // consumer-install `.claude/skills/...` path that doesn't exist in the
 // publisher repo.
-export async function detectSkillRelPath(cwd) {
+export async function detectSkillRelPath(cwd: string): Promise<string> {
   const publisherPath = 'skills/clud-bug-collaboration/SKILL.md';
   const consumerPath = '.claude/skills/clud-bug-collaboration/SKILL.md';
   if (await fileExists(join(cwd, publisherPath))) return publisherPath;
@@ -94,7 +100,7 @@ export async function detectSkillRelPath(cwd) {
 
 // Replace an existing clud-bug block in `content`, OR append if absent.
 // Idempotent: running multiple times leaves a single block.
-export function upsertBlock(content, block) {
+export function upsertBlock(content: string, block: string): string {
   const startRe = new RegExp(escapeRe(START_MARKER));
   const endRe   = new RegExp(escapeRe(END_MARKER));
   if (startRe.test(content) && endRe.test(content)) {
@@ -113,7 +119,7 @@ export function upsertBlock(content, block) {
 // Matches at start-of-line (a literal `@AGENTS.md` mentioned in prose
 // won't fire; only the import directive does). Allows trailing space
 // (some editors trim it; some don't) and optional newline terminator.
-export function hasAgentsMdImport(content) {
+export function hasAgentsMdImport(content: unknown): boolean {
   if (typeof content !== 'string') return false;
   return /^@AGENTS\.md\s*$/m.test(content);
 }
@@ -125,7 +131,7 @@ export function hasAgentsMdImport(content) {
 //
 // Returns the cleaned content. If no block exists, returns content
 // unchanged. Idempotent.
-export function removeBlock(content) {
+export function removeBlock(content: string): string {
   if (typeof content !== 'string') return content;
   // Strip the block. Match \n+ before the marker so we also eat the
   // preceding blank line — otherwise we'd leave a "stub line + blank
@@ -136,25 +142,30 @@ export function removeBlock(content) {
   return content.replace(re, '');
 }
 
-function escapeRe(s) {
+function escapeRe(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+export interface ApplyToRepoResult {
+  touched: string[];
+  created: string[];
+}
+
 // Touches all relevant agent-instruction files in `cwd`.
 // Creates AGENTS.md if it doesn't exist (it's the canonical home).
 // Updates other files only if they already exist (don't proliferate stubs;
 // logmind or the user owns those creation decisions).
 //
 // Returns { touched: string[], created: string[] } for the caller to log.
-export async function applyToRepo(cwd, blockOpts = {}) {
+export async function applyToRepo(cwd: string, blockOpts: RenderBlockOptions = {}): Promise<ApplyToRepoResult> {
   // v0.6.25 / gotcha #2: detect publisher repo + render local skill path.
   // Pre-v0.6.25 always rendered the consumer install path → broke
   // agent-skills' check-links every propagation cycle. Detection runs
   // before block render so the path is correct from the first write.
   const skillRelPath = blockOpts.skillRelPath ?? await detectSkillRelPath(cwd);
   const block = renderBlock({ ...blockOpts, skillRelPath });
-  const touched = [];
-  const created = [];
+  const touched: string[] = [];
+  const created: string[] = [];
 
   for (const path of ALWAYS_TOUCH) {
     const full = join(cwd, path);
@@ -181,8 +192,8 @@ export async function applyToRepo(cwd, blockOpts = {}) {
   // .cursor/rules/*.md — append to every file that exists.
   const cursorRulesDir = join(cwd, '.cursor', 'rules');
   if (await fileExists(cursorRulesDir)) {
-    let entries = [];
-    try { entries = await readdir(cursorRulesDir); } catch {}
+    let entries: string[] = [];
+    try { entries = await readdir(cursorRulesDir); } catch { /* dir missing or unreadable */ }
     for (const name of entries) {
       if (!name.endsWith('.md')) continue;
       const full = join(cursorRulesDir, name);
@@ -206,11 +217,11 @@ export async function applyToRepo(cwd, blockOpts = {}) {
 //
 // AGENTS.md itself is NOT routed through here — it always gets the
 // block (it's the canonical source).
-function nextContentFor(prior, block) {
+function nextContentFor(prior: string, block: string): string {
   return hasAgentsMdImport(prior) ? removeBlock(prior) : upsertBlock(prior, block);
 }
 
-function seedFile(name) {
+function seedFile(name: string): string {
   // When AGENTS.md doesn't exist (no logmind, no prior tooling), seed with a
   // minimal canonical header so the clud-bug block has context.
   if (name === 'AGENTS.md') {
@@ -225,6 +236,6 @@ Claude Code, Cline, Continue, Aider, ...) read it directly.
   return '';
 }
 
-async function fileExists(path) {
+async function fileExists(path: string): Promise<boolean> {
   try { await stat(path); return true; } catch { return false; }
 }

package/{lib/audit.js → src/cli/audit.ts}

@@ -1,37 +1,55 @@
+// CLI audit helpers — these shell out to git and walk the working tree.
+//
+// Split from lib/audit.js during the v0.7.0 TS migration. Pure helpers
+// (durationToGitSince, renderAuditHeader) live in src/core/audit.ts so the
+// App-side (clud-bug-app) can consume them without dragging child_process
+// in. computeAuditFileSet stays CLI-only — it is only meaningful when run
+// in a checked-out repo.
+
 import { spawnSync } from 'node:child_process';
+import { durationToGitSince } from '../core/audit.js';
 
-// Convert a duration like "7d", "2w", "1mo", "3mo", "1y" to a git --since arg.
-// Returns null if the input is empty/undefined; throws on malformed input.
-export function durationToGitSince(input) {
-  if (!input) return null;
-  const m = String(input).trim().match(/^(\d+)\s*(d|w|mo|m|y)$/i);
-  if (!m) {
-    throw new Error(`Unrecognized duration "${input}". Examples: 7d, 2w, 1mo, 1y.`);
-  }
-  const n = Number(m[1]);
-  const unit = m[2].toLowerCase();
-  const map = { d: 'day', w: 'week', mo: 'month', m: 'month', y: 'year' };
-  return `${n} ${map[unit]}${n === 1 ? '' : 's'} ago`;
+export interface GitLinesOptions {
+  // `cwd?: string | undefined` (vs `cwd?: string`) is required by
+  // exactOptionalPropertyTypes: true — callers freely pass an inline
+  // object that may have `cwd` typed as `string | undefined`.
+  cwd?: string | undefined;
+  allowFail?: boolean | undefined;
 }
 
 // Run a git command, return stdout lines split by \n. Throws on non-zero exit
 // unless { allowFail: true }, in which case returns [].
-export function gitLines(args, opts = {}) {
+// Note: under noUncheckedIndexedAccess: true, array element reads are typed
+// `string | undefined`. The return type stays `string[]` (we filter falsy
+// strings out), but callers indexing into the result must keep that in mind.
+export function gitLines(args: string[], opts: GitLinesOptions = {}): string[] {
   const r = spawnSync('git', args, { encoding: 'utf8', cwd: opts.cwd || process.cwd() });
   if (r.status !== 0) {
     if (opts.allowFail) return [];
-    throw new Error(`git ${args.join(' ')} failed (${r.status}): ${r.stderr.trim()}`);
+    // spawnSync with encoding:'utf8' makes stderr `string | null`; the null
+    // path only happens when the child can't be spawned at all (a different
+    // error path). When status is non-zero we have stderr.
+    const stderr = (r.stderr ?? '').toString().trim();
+    throw new Error(`git ${args.join(' ')} failed (${r.status}): ${stderr}`);
   }
-  return r.stdout.split('\n').filter(Boolean);
+  const stdout = (r.stdout ?? '').toString();
+  return stdout.split('\n').filter(Boolean);
+}
+
+export interface AuditFileSetOptions {
+  since?: string | null;
+  changedIn?: string | null;
+  scopes?: string[];
+  cwd?: string;
 }
 
 // Returns the file set the audit should consider, in repo-relative paths.
 // Filters: optional --since (git date), optional --changed-in (duration string),
 // optional --scope globs (one or more, repeatable).
-export function computeAuditFileSet({ since, changedIn, scopes = [], cwd } = {}) {
+export function computeAuditFileSet({ since, changedIn, scopes = [], cwd }: AuditFileSetOptions = {}): string[] {
   const sinceArg = since || (changedIn ? durationToGitSince(changedIn) : null);
 
-  let files;
+  let files: string[];
   if (sinceArg) {
     // Files touched in any commit within the window.
     files = [...new Set(gitLines(['log', `--since=${sinceArg}`, '--name-only', '--pretty=format:'], { cwd }))];
@@ -57,7 +75,7 @@ export function computeAuditFileSet({ since, changedIn, scopes = [], cwd } = {})
 
 // Minimal glob → RegExp. Supports **, *, ?. Anchors at both ends so that
 // 'src/**/*.ts' matches 'src/lib/foo.ts' but not 'app/src/lib/foo.ts'.
-function globToRegex(glob) {
+function globToRegex(glob: string): RegExp {
   let rx = '';
   let i = 0;
   while (i < glob.length) {
@@ -74,7 +92,7 @@ function globToRegex(glob) {
     } else if (ch === '?') {
       rx += '[^/]';
       i++;
-    } else if (/[.+^$|()\[\]{}\\]/.test(ch)) {
+    } else if (ch !== undefined && /[.+^$|()\[\]{}\\]/.test(ch)) {
       rx += '\\' + ch;
       i++;
     } else {
@@ -84,28 +102,3 @@ function globToRegex(glob) {
   }
   return new RegExp(`^${rx}$`);
 }
-
-// Render the audit report's initial markdown body. The Action's Claude run
-// will append findings under a "## Findings" section after this header.
-export function renderAuditHeader({ date, scopeLabel, files }) {
-  const head = `# 🐛 Clud Bug audit — ${date}
-
-A scheduled walk through the habitat. Scope: ${scopeLabel}.
-Files surveyed: **${files.length}**.
-
-<details>
-<summary>File manifest (${files.length})</summary>
-
-\`\`\`
-${files.join('\n')}
-\`\`\`
-
-</details>
-
----
-
-## Findings
-
-`;
-  return head;
-}

package/{lib/branch-protection.js → src/cli/branch-protection.ts}

@@ -21,35 +21,70 @@
 
 import { spawn } from 'node:child_process';
 
+export interface GhResult {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+export interface GhOptions {
+  stdin?: string | undefined;
+}
+
+// Pluggable invoker shape — the CLI uses `defaultGh`, tests pass a mock.
+export type GhInvoker = (args: string[], opts?: GhOptions) => Promise<GhResult>;
+
 // Default `gh` invoker: spawns `gh <args>` and resolves with
 // { code, stdout, stderr }. Tests pass a function with the same shape.
-function defaultGh(args, { stdin } = {}) {
-  return new Promise((resolve, reject) => {
+function defaultGh(args: string[], opts: GhOptions = {}): Promise<GhResult> {
+  const { stdin } = opts;
+  return new Promise<GhResult>((resolve, reject) => {
     const child = spawn('gh', args, { stdio: ['pipe', 'pipe', 'pipe'] });
     let stdout = '';
     let stderr = '';
-    child.stdout.on('data', (d) => { stdout += d; });
-    child.stderr.on('data', (d) => { stderr += d; });
+    // Under strict typing, spawn() can return null for stdio pipes when
+    // stdio is configured to ignore the stream. We requested 'pipe' for
+    // all three so the streams are guaranteed; the `!` non-null asserts
+    // make this explicit and keep the runtime semantics identical.
+    child.stdout!.on('data', (d: Buffer | string) => { stdout += d; });
+    child.stderr!.on('data', (d: Buffer | string) => { stderr += d; });
     child.on('error', reject);
     child.on('close', (code) => resolve({ code, stdout, stderr }));
-    if (stdin) child.stdin.end(stdin);
-    else child.stdin.end();
+    if (stdin) child.stdin!.end(stdin);
+    else child.stdin!.end();
   });
 }
 
+export interface DetectRepoOptions {
+  gh?: GhInvoker | undefined;
+}
+
+export interface DetectedRepo {
+  owner: string;
+  repo: string;
+}
+
 // Returns { owner, repo } from the local git remote. Uses
 // `gh repo view --json owner,name` so it doesn't depend on parsing URLs.
-export async function detectRepo({ gh = defaultGh } = {}) {
+export async function detectRepo({ gh = defaultGh }: DetectRepoOptions = {}): Promise<DetectedRepo> {
   const { code, stdout, stderr } = await gh(['repo', 'view', '--json', 'owner,name']);
   if (code !== 0) {
     throw new Error(`gh repo view failed (${code}): ${stderr.trim() || '(no stderr)'}`);
   }
-  const parsed = JSON.parse(stdout);
+  const parsed = JSON.parse(stdout) as { owner: { login: string }; name: string };
   return { owner: parsed.owner.login, repo: parsed.name };
 }
 
+export interface DetectDefaultBranchOptions {
+  owner: string;
+  repo: string;
+  gh?: GhInvoker | undefined;
+}
+
 // Returns the default branch name (e.g. "main", "master", "trunk").
-export async function detectDefaultBranch({ owner, repo, gh = defaultGh } = {}) {
+export async function detectDefaultBranch(
+  { owner, repo, gh = defaultGh }: DetectDefaultBranchOptions,
+): Promise<string> {
   const { code, stdout, stderr } = await gh(['api', `repos/${owner}/${repo}`, '--jq', '.default_branch']);
   if (code !== 0) {
     throw new Error(`Could not read default_branch for ${owner}/${repo}: ${stderr.trim() || stdout.trim()}`);
@@ -57,6 +92,20 @@ export async function detectDefaultBranch({ owner, repo, gh = defaultGh } = {})
   return stdout.trim();
 }
 
+export type ProtectionState =
+  | { state: 'enabled' }
+  | { state: 'disabled' }
+  | { state: 'no-protection' }
+  | { state: 'forbidden' }
+  | { state: 'unknown'; reason: string };
+
+export interface GetProtectionStateOptions {
+  owner: string;
+  repo: string;
+  branch: string;
+  gh?: GhInvoker | undefined;
+}
+
 // Inspects the current required_conversation_resolution state. Returns
 // one of:
 //   { state: 'enabled' }
@@ -68,7 +117,9 @@ export async function detectDefaultBranch({ owner, repo, gh = defaultGh } = {})
 // The reason this returns a discriminated union rather than throwing is
 // that runInit decides what to do based on the state: each value above
 // has a different user-facing message and follow-up action.
-export async function getProtectionState({ owner, repo, branch, gh = defaultGh } = {}) {
+export async function getProtectionState(
+  { owner, repo, branch, gh = defaultGh }: GetProtectionStateOptions,
+): Promise<ProtectionState> {
   const { code, stdout, stderr } = await gh([
     'api',
     `repos/${owner}/${repo}/branches/${branch}/protection`,
@@ -89,11 +140,24 @@ export async function getProtectionState({ owner, repo, branch, gh = defaultGh }
   return { state: 'unknown', reason: stderr.trim() || stdout.trim() || `gh exited ${code}` };
 }
 
+export interface EnableConversationResolutionOptions {
+  owner: string;
+  repo: string;
+  branch: string;
+  gh?: GhInvoker | undefined;
+}
+
+export type EnableResult =
+  | { ok: true }
+  | { ok: false; state: 'no-protection' | 'forbidden' | 'unknown'; reason: string };
+
 // Enables the single flag via the dedicated endpoint. Doesn't touch any
 // other protection settings. Returns { ok: true } on success or
 // { ok: false, state, reason } using the same state taxonomy as
 // getProtectionState() so callers can produce a consistent message.
-export async function enableConversationResolution({ owner, repo, branch, gh = defaultGh } = {}) {
+export async function enableConversationResolution(
+  { owner, repo, branch, gh = defaultGh }: EnableConversationResolutionOptions,
+): Promise<EnableResult> {
   const { code, stdout, stderr } = await gh([
     'api', '-X', 'POST',
     `repos/${owner}/${repo}/branches/${branch}/protection/required_conversation_resolution`,

package/{lib/edit-workflow.js → src/cli/edit-workflow.ts}

@@ -7,41 +7,62 @@ import { spawnSync } from 'node:child_process';
 // so claude-code-action's workflow-self-mod guard doesn't bundle them
 // with other reviewable work.
 
-export function getPendingWorkflowEdits(cwd = process.cwd()) {
+export interface PendingWorkflowEdits {
+  allWorkflow: boolean;
+  files: string[];
+  nonWorkflow: string[];
+}
+
+export function getPendingWorkflowEdits(cwd: string = process.cwd()): PendingWorkflowEdits {
   // --untracked-files=all so new files in new directories are reported as
   // individual paths instead of being collapsed to the parent dir (default
   // 'normal' mode would emit '.github/' for a brand-new clud-bug-review.yml).
   const r = spawnSync('git', ['status', '--porcelain', '--untracked-files=all'], { cwd, encoding: 'utf8' });
   if (r.status !== 0) {
-    throw new Error(`git status failed: ${r.stderr.trim()}`);
+    // r.stderr is `string | null` under strict; safe to coalesce to '' for the
+    // error message — null here means the child failed to spawn entirely.
+    throw new Error(`git status failed: ${(r.stderr ?? '').trim()}`);
   }
-  const lines = r.stdout.split('\n').filter(Boolean);
+  const stdout = r.stdout ?? '';
+  const lines = stdout.split('\n').filter(Boolean);
   if (lines.length === 0) return { allWorkflow: true, files: [], nonWorkflow: [] };
 
-  const files = [];
-  const nonWorkflow = [];
+  const files: string[] = [];
+  const nonWorkflow: string[] = [];
   for (const line of lines) {
     // porcelain format: XY <space> <path> ; rename: XY old -> new
-    const path = line.slice(3).split(' -> ').pop().trim();
+    // .pop() on a non-empty split always yields a string here, but
+    // noUncheckedIndexedAccess makes TS pessimistic — coalesce + trim.
+    const path = (line.slice(3).split(' -> ').pop() ?? '').trim();
     files.push(path);
     if (!isWorkflowFile(path)) nonWorkflow.push(path);
   }
   return { allWorkflow: nonWorkflow.length === 0, files, nonWorkflow };
 }
 
-export function isWorkflowFile(path) {
+export function isWorkflowFile(path: string): boolean {
   return /^\.github\/workflows\/clud-bug-.*\.ya?ml$/.test(path);
 }
 
-export function makeBranchName(date = new Date()) {
+export function makeBranchName(date: Date = new Date()): string {
   const stamp = date.toISOString().replace(/[:.]/g, '-').slice(0, 19);
   return `clud-bug/edit-workflow-${stamp}`;
 }
 
-export function git(cwd, args, opts = {}) {
+export interface GitOptions {
+  allowFail?: boolean | undefined;
+}
+
+export interface GitResult {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+}
+
+export function git(cwd: string, args: string[], opts: GitOptions = {}): GitResult {
   const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
   if (r.status !== 0 && !opts.allowFail) {
-    throw new Error(`git ${args.join(' ')} failed (${r.status}): ${r.stderr.trim()}`);
+    throw new Error(`git ${args.join(' ')} failed (${r.status}): ${(r.stderr ?? '').trim()}`);
   }
-  return { ok: r.status === 0, stdout: r.stdout.trim(), stderr: r.stderr.trim() };
+  return { ok: r.status === 0, stdout: (r.stdout ?? '').trim(), stderr: (r.stderr ?? '').trim() };
 }

package/src/cli/index.ts

@@ -0,0 +1,101 @@
+// Public API surface for `clud-bug` CLI helpers (consumed via the package's
+// `.` exports map → `dist/cli/index.js`).
+//
+// Each line re-exports one CLI module's public symbols. Modules are
+// added incrementally as the v0.7.0 TypeScript migration converts each
+// lib/* JS file.
+
+// The top-level dispatcher main() lives in main.ts; bin/clud-bug.js
+// imports it through this barrel and runs it. Keeping main() out of
+// this file avoids accidental side effects when consumers
+// `import { ... } from 'clud-bug'`.
+export { main } from './main.js';
+
+export {
+  detectRepo,
+  detectDefaultBranch,
+  getProtectionState,
+  enableConversationResolution,
+  type GhResult,
+  type GhOptions,
+  type GhInvoker,
+  type DetectRepoOptions,
+  type DetectedRepo,
+  type DetectDefaultBranchOptions,
+  type ProtectionState,
+  type GetProtectionStateOptions,
+  type EnableConversationResolutionOptions,
+  type EnableResult,
+} from './branch-protection.js';
+
+export {
+  getPendingWorkflowEdits,
+  isWorkflowFile,
+  makeBranchName,
+  git,
+  type PendingWorkflowEdits,
+  type GitOptions,
+  type GitResult,
+} from './edit-workflow.js';
+
+export {
+  renderBlock,
+  detectSkillRelPath,
+  upsertBlock,
+  hasAgentsMdImport,
+  removeBlock,
+  applyToRepo,
+  type RenderBlockOptions,
+  type ApplyToRepoResult,
+} from './agents-md.js';
+
+export {
+  computeSkillUsageDelta,
+  mergeSkillUsage,
+  assessSkillHealth,
+  formatHealthDashboard,
+  DEFAULT_GH_RUNNER,
+  fetchUsageArtifacts,
+  aggregateUsageStream,
+  type SkillDelta,
+  type SkillUsageEntry,
+  type SkillDeltaMap,
+  type SkillUsageMap,
+  type SkillHealthStatus,
+  type SkillHealthRow,
+  type GhRunResult,
+  type GhRunner,
+  type FetchUsageArtifactsOptions,
+  type UsageArtifactRecord,
+} from './skill-usage.js';
+
+export {
+  PRICING,
+  computeReviewCost,
+  costPerLOC,
+  cacheHitRate,
+  extractTokensFromLog,
+  rollup,
+  formatRollup,
+  type ModelPricing,
+  type TokenCounts,
+  type CostParts,
+  type ReviewCost,
+  type ExtractedTokens,
+  type ReviewRecord,
+  type RollupGroupStats,
+  type RollupTotal,
+  type RollupTrend,
+  type RollupOutlier,
+  type UnknownModelReview,
+  type Rollup,
+  type FormatRollupOptions,
+} from './usage.js';
+
+export {
+  runUpdate,
+  type RunUpdateOptions,
+  type UpdateChangeRecord,
+  type UpdateSkippedRecord,
+  type RunUpdateResult,
+} from './update.js';