@celilo/cli 0.3.16 → 0.3.18

package/src/services/module-validator/git-hygiene.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, test } from 'bun:test';
+import { execSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkGitHygiene, checkModuleStale } from './git-hygiene';
+
+interface TempRepo {
+  dir: string;
+  cleanup: () => void;
+  exec: (cmd: string) => string;
+}
+
+/**
+ * Spin up a fresh git repo in a temp dir. Returns helpers for committing
+ * files and a cleanup function. Tests use this to construct exact git
+ * histories without polluting the surrounding working tree.
+ */
+function makeTempRepo(): TempRepo {
+  const dir = mkdtempSync(join(tmpdir(), 'celilo-git-hygiene-'));
+  const exec = (cmd: string): string =>
+    execSync(cmd, { cwd: dir, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+  exec('git init -q');
+  exec('git config user.email "test@example.com"');
+  exec('git config user.name "Test"');
+  exec('git config commit.gpgsign false');
+  return {
+    dir,
+    exec,
+    cleanup: () => rmSync(dir, { recursive: true, force: true }),
+  };
+}
+
+describe('checkModuleStale', () => {
+  test('null when manifest.yml is the most recently committed file', () => {
+    const repo = makeTempRepo();
+    try {
+      writeFileSync(join(repo.dir, 'install.sh'), '#!/bin/sh\n');
+      repo.exec('git add install.sh && git commit -q -m "initial src"');
+      writeFileSync(join(repo.dir, 'manifest.yml'), 'id: x\nversion: 1.0.0\n');
+      repo.exec('git add manifest.yml && git commit -q -m "manifest"');
+
+      expect(checkModuleStale(repo.dir)).toBeNull();
+    } finally {
+      repo.cleanup();
+    }
+  });
+
+  test('returns issue when src has commits past last manifest commit', () => {
+    const repo = makeTempRepo();
+    try {
+      writeFileSync(join(repo.dir, 'manifest.yml'), 'id: x\nversion: 1.0.0\n');
+      repo.exec('git add manifest.yml && git commit -q -m "manifest"');
+      writeFileSync(join(repo.dir, 'install.sh'), '#!/bin/sh\necho hi\n');
+      repo.exec('git add install.sh && git commit -q -m "src change"');
+
+      const issue = checkModuleStale(repo.dir);
+      expect(issue).not.toBeNull();
+      expect(issue?.lastSrcCommit).toMatch(/^[0-9a-f]{40}$/);
+      expect(issue?.lastManifestCommit).toMatch(/^[0-9a-f]{40}$/);
+      expect(issue?.lastSrcCommit).not.toBe(issue?.lastManifestCommit);
+    } finally {
+      repo.cleanup();
+    }
+  });
+
+  test('null when same commit touched both src and manifest', () => {
+    const repo = makeTempRepo();
+    try {
+      writeFileSync(join(repo.dir, 'manifest.yml'), 'id: x\nversion: 1.0.0\n');
+      writeFileSync(join(repo.dir, 'install.sh'), '#!/bin/sh\n');
+      repo.exec('git add . && git commit -q -m "both"');
+
+      expect(checkModuleStale(repo.dir)).toBeNull();
+    } finally {
+      repo.cleanup();
+    }
+  });
+
+  test('null when not in a git repo', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'celilo-git-hygiene-bare-'));
+    try {
+      writeFileSync(join(dir, 'manifest.yml'), 'id: x\n');
+      expect(checkModuleStale(dir)).toBeNull();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('checkGitHygiene', () => {
+  test('all ok on a fresh, clean repo with manifest as latest commit', () => {
+    const repo = makeTempRepo();
+    try {
+      writeFileSync(join(repo.dir, 'install.sh'), '#!/bin/sh\n');
+      repo.exec('git add . && git commit -q -m "src"');
+      writeFileSync(join(repo.dir, 'manifest.yml'), 'id: x\nversion: 1.0.0\n');
+      repo.exec('git add . && git commit -q -m "manifest"');
+
+      const checks = checkGitHygiene(repo.dir);
+      expect(checks.every((c) => c.status === 'ok')).toBe(true);
+    } finally {
+      repo.cleanup();
+    }
+  });
+
+  test('fail on stale-version drift, with the same actionable message publish uses', () => {
+    const repo = makeTempRepo();
+    try {
+      writeFileSync(join(repo.dir, 'manifest.yml'), 'id: x\nversion: 1.0.0\n');
+      repo.exec('git add . && git commit -q -m "manifest"');
+      writeFileSync(join(repo.dir, 'install.sh'), '#!/bin/sh\n');
+      repo.exec('git add . && git commit -q -m "src after manifest"');
+
+      const checks = checkGitHygiene(repo.dir);
+      const stale = checks.find((c) => c.name === 'stale-version drift');
+      expect(stale?.status).toBe('fail');
+      expect(stale?.message).toContain('manifest.yml');
+      expect(stale?.message).toContain('+N');
+    } finally {
+      repo.cleanup();
+    }
+  });
+
+  test('warn on dirty working tree', () => {
+    const repo = makeTempRepo();
+    try {
+      writeFileSync(join(repo.dir, 'manifest.yml'), 'id: x\nversion: 1.0.0\n');
+      repo.exec('git add . && git commit -q -m "manifest"');
+      // Edit something without committing — dirty tree.
+      writeFileSync(join(repo.dir, 'manifest.yml'), 'id: x\nversion: 1.0.1\n');
+
+      const checks = checkGitHygiene(repo.dir);
+      const tree = checks.find((c) => c.name === 'working tree');
+      expect(tree?.status).toBe('warn');
+      expect(tree?.message).toContain('uncommitted');
+    } finally {
+      repo.cleanup();
+    }
+  });
+});

package/src/services/module-validator/git-hygiene.ts

@@ -0,0 +1,144 @@
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { collectGitInfo, makeRealGitRunner } from '../../module/packaging/release-metadata';
+import type { Check } from './types';
+
+export interface StalenessIssue {
+  moduleDir: string;
+  lastSrcCommit: string;
+  lastManifestCommit: string;
+}
+
+/**
+ * SHA of the last commit touching the given pathspecs, or null on any
+ * git failure (not a repo, never committed, etc.). Callers treat null
+ * as "can't determine — skip the check."
+ *
+ * Runs git from `cwd` so module-check works regardless of the operator's
+ * shell CWD (e.g. `celilo module check ~/hobby/lunacycle` invoked from
+ * anywhere should still talk to lunacycle's git history).
+ */
+function lastCommitTouching(cwd: string, pathspec: string[]): string | null {
+  const r = spawnSync('git', ['log', '-1', '--format=%H', '--', ...pathspec], {
+    cwd,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    encoding: 'utf-8',
+  });
+  if (r.status !== 0) return null;
+  const sha = r.stdout.trim();
+  return sha || null;
+}
+
+function isAncestor(cwd: string, maybeAncestor: string, descendant: string): boolean {
+  const r = spawnSync('git', ['merge-base', '--is-ancestor', maybeAncestor, descendant], {
+    cwd,
+    stdio: 'ignore',
+  });
+  return r.status === 0;
+}
+
+/**
+ * Detect "I edited module src but forgot to bump (or touch) manifest.yml."
+ *
+ * Returns null when the manifest is the most recently-touched file in the
+ * dir (or when neither side has any commit history — e.g. brand-new module
+ * not yet committed). Returns a StalenessIssue when src has commits AFTER
+ * the last manifest.yml change — the operator must bump the manifest
+ * (semver change → reset +N to 1) or just touch it (release-only change →
+ * auto-bump +N), then re-publish.
+ *
+ * Used by both `module publish` (where it refuses the publish) and
+ * `module check` (where it surfaces as a fail before the operator goes
+ * through publish at all).
+ */
+export function checkModuleStale(moduleDir: string): StalenessIssue | null {
+  const manifestPath = join(moduleDir, 'manifest.yml');
+  const lastManifest = lastCommitTouching(moduleDir, [manifestPath]);
+  // Excluding manifest.yml from the "src" pathspec is the whole point — we
+  // want to know if anything ELSE in the dir moved past it. node_modules
+  // and common build outputs are gitignored already, but be explicit
+  // defensively.
+  const lastSrc = lastCommitTouching(moduleDir, [
+    moduleDir,
+    `:(exclude)${manifestPath}`,
+    `:(exclude)${moduleDir}/node_modules`,
+    `:(exclude)${moduleDir}/dist`,
+  ]);
+  if (!lastManifest || !lastSrc) return null;
+  if (lastSrc === lastManifest) return null;
+  if (!isAncestor(moduleDir, lastManifest, lastSrc)) return null;
+
+  return { moduleDir, lastSrcCommit: lastSrc, lastManifestCommit: lastManifest };
+}
+
+/**
+ * Publish-readiness checks against the module's git state:
+ *
+ * - Stale-version drift: src commits past the last manifest.yml commit.
+ *   Surfaced as fail. Same shape `module publish` enforces.
+ * - Working tree dirty: uncommitted changes in the module dir. Surfaced
+ *   as warn — `--allow-dirty` overrides at publish time but it's still
+ *   the kind of thing an operator usually wants to know.
+ *
+ * Both quietly degrade to ok when the module isn't in a git repo at all
+ * (brand-new uncommitted module, third-party module shipped as a
+ * directory tarball, etc.) — git operations return null/empty and we
+ * skip the check.
+ */
+export function checkGitHygiene(modulePath: string): Check[] {
+  const checks: Check[] = [];
+
+  const stale = checkModuleStale(modulePath);
+  if (stale) {
+    checks.push({
+      category: 'git_hygiene',
+      name: 'stale-version drift',
+      status: 'fail',
+      message: [
+        'src commits past last manifest.yml change',
+        `  src commit:        ${stale.lastSrcCommit.slice(0, 12)}`,
+        `  manifest.yml commit: ${stale.lastManifestCommit.slice(0, 12)}`,
+        '  Bump manifest.yml#version (semver change), or touch it',
+        '  (release-only — auto-revision picks the next +N), then commit.',
+      ].join('\n'),
+    });
+  } else {
+    checks.push({
+      category: 'git_hygiene',
+      name: 'stale-version drift',
+      status: 'ok',
+      message: 'manifest.yml is current with respect to module src',
+    });
+  }
+
+  try {
+    const gitInfo = collectGitInfo(modulePath, makeRealGitRunner());
+    if (gitInfo.dirty) {
+      checks.push({
+        category: 'git_hygiene',
+        name: 'working tree',
+        status: 'warn',
+        message:
+          'working tree has uncommitted changes; publish refuses unless --allow-dirty is passed',
+      });
+    } else {
+      checks.push({
+        category: 'git_hygiene',
+        name: 'working tree',
+        status: 'ok',
+        message: 'working tree clean',
+      });
+    }
+  } catch {
+    // Not in a git repo, or git unavailable. Stale-check above already
+    // returned ok in that case; we mirror it here for consistency.
+    checks.push({
+      category: 'git_hygiene',
+      name: 'working tree',
+      status: 'ok',
+      message: 'not a git repo — skipping working-tree check',
+    });
+  }
+
+  return checks;
+}

package/src/services/module-validator/index.test.ts

@@ -0,0 +1,67 @@
+/**
+ * Integration test for runChecks — wires every checker together against
+ * a real in-tree module (caddy). The in-tree modules are guaranteed
+ * healthy by virtue of CI running their build/import flow on every PR;
+ * a regression in runChecks would surface as fail/warn here.
+ *
+ * The npm fetch is stubbed to keep the test offline.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { resolve } from 'node:path';
+import { runChecks } from '.';
+
+const REPO_ROOT = resolve(__dirname, '../../../../..');
+const CADDY_MODULE_PATH = resolve(REPO_ROOT, 'modules/caddy');
+
+describe('runChecks (orchestrator)', () => {
+  test('healthy in-tree module produces all-ok report', async () => {
+    const checks = await runChecks(CADDY_MODULE_PATH, {
+      noBuild: true,
+      fetchNpmMetadata: async () => null,
+    });
+
+    // git_hygiene is environment-dependent — the in-tree caddy module's
+    // git state varies during dev. Stale-version drift, dirty-tree, etc.
+    // are real publish gates but not what this test is asserting (which
+    // is "the orchestrator wires every checker up cleanly").
+    const fails = checks.filter((c) => c.status === 'fail' && c.category !== 'git_hygiene');
+    expect(fails).toEqual([]);
+
+    // Must include checks from every category we expect to fire.
+    const categories = new Set(checks.map((c) => c.category));
+    expect(categories.has('manifest_schema')).toBe(true);
+    expect(categories.has('contract_version')).toBe(true);
+    expect(categories.has('capability')).toBe(true);
+    expect(categories.has('workspace_dep')).toBe(true);
+    expect(categories.has('git_hygiene')).toBe(true);
+    expect(categories.has('typescript_build')).toBe(true);
+  });
+
+  test('returns checks in stable category order', async () => {
+    const checks = await runChecks(CADDY_MODULE_PATH, {
+      noBuild: true,
+      fetchNpmMetadata: async () => null,
+    });
+
+    const seenCategories: string[] = [];
+    for (const c of checks) {
+      if (seenCategories[seenCategories.length - 1] !== c.category) {
+        seenCategories.push(c.category);
+      }
+    }
+
+    expect(seenCategories[0]).toBe('manifest_schema');
+    expect(seenCategories[seenCategories.length - 1]).toBe('typescript_build');
+  });
+
+  test('nonexistent path produces a failed manifest_schema check', async () => {
+    const checks = await runChecks('/tmp/celilo-runChecks-doesnotexist', {
+      noBuild: true,
+      fetchNpmMetadata: async () => null,
+    });
+
+    const schemaCheck = checks.find((c) => c.category === 'manifest_schema');
+    expect(schemaCheck?.status).toBe('fail');
+  });
+});

package/src/services/module-validator/index.ts

@@ -0,0 +1,74 @@
+import { parse as parseYaml } from 'yaml';
+import { type ManifestForCapabilityCheck, checkCapabilityVersions } from './capability-versions';
+import { checkContractVersion } from './contract-version';
+import { checkGitHygiene } from './git-hygiene';
+import { checkManifestSchema, readManifestYaml } from './manifest-schema';
+import type { Check, RunChecksOptions } from './types';
+import { checkTypeScriptBuild } from './typescript-build';
+import { checkWorkspaceDeps, defaultFetchNpmMetadata } from './workspace-deps';
+
+export type { Check, CheckCategory, CheckStatus, NpmMetadata, RunChecksOptions } from './types';
+export {
+  checkCapabilityVersions,
+  validateCapabilityVersions,
+  type ManifestForCapabilityCheck,
+} from './capability-versions';
+export { checkContractVersion } from './contract-version';
+export { checkGitHygiene, checkModuleStale, type StalenessIssue } from './git-hygiene';
+export { checkManifestSchema } from './manifest-schema';
+export { checkTypeScriptBuild } from './typescript-build';
+export { checkWorkspaceDeps, defaultFetchNpmMetadata } from './workspace-deps';
+
+interface RawManifest extends ManifestForCapabilityCheck {
+  celilo_contract?: string;
+}
+
+/**
+ * Runs every checker against the module at `modulePath` and returns the
+ * combined `Check[]` in a stable, human-friendly order:
+ *
+ *   1. manifest_schema   — bedrock; if this fails, downstream checks
+ *      may not even have a parseable manifest
+ *   2. contract_version  — top-of-file claim; semantically the framing
+ *      for everything else
+ *   3. capability        — manifest's claimed capability versions
+ *   4. workspace_dep     — npm-fed; the only network-dependent check
+ *   5. git_hygiene       — publish-readiness gates (stale-version drift,
+ *                          dirty-tree); same shape `module publish`
+ *                          enforces, surfaced here so a clean check
+ *                          really does mean a clean publish
+ *   6. typescript_build  — slowest, most likely to spew errors
+ *
+ * Each checker returns its own Check[]; the orchestrator does no
+ * filtering or reshaping. CLI presentation is layered on top.
+ */
+export async function runChecks(
+  modulePath: string,
+  options: RunChecksOptions = {},
+): Promise<Check[]> {
+  const fetcher = options.fetchNpmMetadata ?? defaultFetchNpmMetadata;
+  const checks: Check[] = [];
+
+  const schemaCheck = await checkManifestSchema(modulePath);
+  checks.push(schemaCheck);
+
+  let manifest: RawManifest | null = null;
+  try {
+    const yaml = await readManifestYaml(modulePath);
+    manifest = parseYaml(yaml) as RawManifest;
+  } catch {
+    // Couldn't even read the YAML — manifest_schema check above already
+    // reports the failure. Skip the rest of the manifest-derived checks.
+  }
+
+  if (manifest) {
+    checks.push(checkContractVersion(manifest));
+    checks.push(...checkCapabilityVersions(manifest));
+  }
+
+  checks.push(...(await checkWorkspaceDeps(modulePath, fetcher)));
+  checks.push(...checkGitHygiene(modulePath));
+  checks.push(await checkTypeScriptBuild(modulePath, { noBuild: options.noBuild }));
+
+  return checks;
+}

package/src/services/module-validator/manifest-schema.ts

@@ -0,0 +1,42 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readModuleManifest } from '../../module/import';
+import type { Check } from './types';
+
+/**
+ * Runs the same manifest pipeline `module import` runs (zod schema +
+ * zone + derive + hook + cross-cap + capability-name + variable-source
+ * checks). Reports a single Check: ok if everything passes, fail with
+ * the first error message otherwise.
+ *
+ * One row instead of N because a broken manifest cascades — fix the
+ * first thing and the next run will surface the next thing. Surfacing
+ * every individual sub-validator would just spam the report.
+ */
+export async function checkManifestSchema(modulePath: string): Promise<Check> {
+  const result = await readModuleManifest(modulePath);
+  if (result.success) {
+    return {
+      category: 'manifest_schema',
+      name: 'manifest.yml',
+      status: 'ok',
+      message: 'manifest passes all schema validations',
+    };
+  }
+  return {
+    category: 'manifest_schema',
+    name: 'manifest.yml',
+    status: 'fail',
+    message: result.error,
+  };
+}
+
+/**
+ * Reads `manifest.yml` from the given module path as raw YAML. Used by
+ * checkers that want the manifest's claimed values without paying the
+ * full validation cost (e.g. capability-version drift, where a malformed
+ * manifest is already failed by checkManifestSchema).
+ */
+export async function readManifestYaml(modulePath: string): Promise<string> {
+  return readFile(join(modulePath, 'manifest.yml'), 'utf-8');
+}

package/src/services/module-validator/types.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared types for `celilo module check` and the validators it composes.
+ *
+ * A `Check` is a single named verdict — one row in the report. The same
+ * checks are produced regardless of output format (text or JSON); the
+ * format layer is pure presentation.
+ */
+
+export type CheckStatus = 'ok' | 'warn' | 'fail';
+
+export type CheckCategory =
+  | 'capability'
+  | 'workspace_dep'
+  | 'manifest_schema'
+  | 'contract_version'
+  | 'typescript_build'
+  | 'git_hygiene';
+
+export interface Check {
+  category: CheckCategory;
+  name: string;
+  status: CheckStatus;
+  message: string;
+  /** What the module currently says (manifest claim, package.json range, etc.). */
+  currentValue?: string;
+  /** What we suggest changing it to. Empty when the fix isn't a single value. */
+  suggestedValue?: string;
+  /** Convention-generated link to a per-package migration page. */
+  migrationUrl?: string;
+}
+
+export interface RunChecksOptions {
+  /** Skip the TypeScript build check unconditionally. */
+  noBuild?: boolean;
+  /** Injectable npm metadata fetcher; defaults to real registry.npmjs.org. */
+  fetchNpmMetadata?: (packageName: string) => Promise<NpmMetadata | null>;
+}
+
+export interface NpmMetadata {
+  name: string;
+  /** "latest" tag — the version a fresh `npm install` would pick up. */
+  latestVersion: string;
+}

package/src/services/module-validator/typescript-build.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkTypeScriptBuild } from './typescript-build';
+
+describe('checkTypeScriptBuild', () => {
+  test('skips with ok when noBuild is set', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'celilo-tsc-'));
+    try {
+      const r = await checkTypeScriptBuild(dir, { noBuild: true });
+      expect(r.status).toBe('ok');
+      expect(r.message).toContain('skipped');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('skips with ok when there is no TypeScript surface', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'celilo-tsc-'));
+    try {
+      // Just YAML and shell — nothing to typecheck.
+      writeFileSync(join(dir, 'manifest.yml'), 'id: x\nversion: 1.0.0');
+      writeFileSync(join(dir, 'install.sh'), '#!/usr/bin/env bash\n');
+      const r = await checkTypeScriptBuild(dir);
+      expect(r.status).toBe('ok');
+      expect(r.message).toContain('no TypeScript surface');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('warns when .ts files exist but no tsconfig', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'celilo-tsc-'));
+    try {
+      mkdirSync(join(dir, 'scripts'));
+      writeFileSync(join(dir, 'scripts', 'install.ts'), 'export const x = 1;\n');
+      const r = await checkTypeScriptBuild(dir);
+      expect(r.status).toBe('warn');
+      expect(r.message).toContain('tsconfig.json');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('fail with helpful message when tsconfig present but no node_modules', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'celilo-tsc-'));
+    try {
+      writeFileSync(join(dir, 'tsconfig.json'), '{}');
+      const r = await checkTypeScriptBuild(dir);
+      expect(r.status).toBe('fail');
+      expect(r.message).toContain('node_modules');
+      expect(r.message).toContain('bun install');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/services/module-validator/typescript-build.ts

@@ -0,0 +1,115 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { Check } from './types';
+
+/**
+ * Returns true if the module has at least one TypeScript file under
+ * `scripts/` (recursively). Used to decide whether `typescript-build`
+ * has anything to check at all.
+ */
+async function hasTypeScriptSources(modulePath: string): Promise<boolean> {
+  const scriptsDir = join(modulePath, 'scripts');
+  if (!existsSync(scriptsDir)) return false;
+  const stack: string[] = [scriptsDir];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    if (!dir) continue;
+    try {
+      const entries = await readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          stack.push(join(dir, entry.name));
+        } else if (entry.name.endsWith('.ts')) {
+          return true;
+        }
+      }
+    } catch {
+      // unreadable directory — ignore and continue
+    }
+  }
+  return false;
+}
+
+/**
+ * Runs `bunx tsc --noEmit` from the module directory.
+ *
+ * - Modules with no `tsconfig.json` AND no `.ts` files in `scripts/`
+ *   are silently skipped (returns ok). Pure YAML+shell modules don't
+ *   need a TS check.
+ * - Modules with `.ts` sources but no tsconfig get a warn telling them
+ *   to add one.
+ * - Otherwise we spawn tsc and report ok / fail with the captured
+ *   stderr+stdout truncated to a reasonable size.
+ *
+ * The whole check is skipped when `noBuild` is true; callers use that
+ * for fast iteration.
+ */
+export async function checkTypeScriptBuild(
+  modulePath: string,
+  options: { noBuild?: boolean } = {},
+): Promise<Check> {
+  if (options.noBuild) {
+    return {
+      category: 'typescript_build',
+      name: 'tsc --noEmit',
+      status: 'ok',
+      message: 'skipped (--no-build)',
+    };
+  }
+
+  const hasTsConfig = existsSync(join(modulePath, 'tsconfig.json'));
+  const hasTsFiles = await hasTypeScriptSources(modulePath);
+
+  if (!hasTsConfig && !hasTsFiles) {
+    return {
+      category: 'typescript_build',
+      name: 'tsc --noEmit',
+      status: 'ok',
+      message: 'no TypeScript surface to check',
+    };
+  }
+
+  if (!hasTsConfig) {
+    return {
+      category: 'typescript_build',
+      name: 'tsc --noEmit',
+      status: 'warn',
+      message:
+        'module has .ts files but no tsconfig.json; add one so we can typecheck against current @celilo types',
+    };
+  }
+
+  if (!existsSync(join(modulePath, 'node_modules'))) {
+    return {
+      category: 'typescript_build',
+      name: 'tsc --noEmit',
+      status: 'fail',
+      message: 'no node_modules — run `bun install` in the module directory first',
+    };
+  }
+
+  const r = spawnSync('bunx', ['tsc', '--noEmit'], {
+    cwd: modulePath,
+    encoding: 'utf-8',
+  });
+
+  if (r.status === 0) {
+    return {
+      category: 'typescript_build',
+      name: 'tsc --noEmit',
+      status: 'ok',
+      message: 'TypeScript build clean',
+    };
+  }
+
+  const output = `${r.stdout ?? ''}${r.stderr ?? ''}`.trim();
+  const truncated = output.length > 800 ? `${output.slice(0, 800)}\n…(truncated)` : output;
+  return {
+    category: 'typescript_build',
+    name: 'tsc --noEmit',
+    status: 'fail',
+    message: truncated || 'tsc exited non-zero with no output',
+  };
+}