@litfamily/litgrok 1.0.0

package/.grok/skills/lsp-setup/references/rust/README.md

@@ -0,0 +1,55 @@
+# Rust — LSP setup (Grok Build / LitGrok)
+
+- **Recommended server:** `rust-analyzer`
+- **Extensions:** `.rs`
+- **Install hint:** `rustup component add rust-analyzer`
+
+## Install
+
+- **macOS:** `rustup component add rust-analyzer` (or `brew install rust-analyzer`)
+- **Linux:** `rustup component add rust-analyzer`
+- **Windows:** `rustup component add rust-analyzer`
+
+The rustup component is the recommended path — it stays pinned to your toolchain.
+`rust-analyzer` also needs the `rust-src` component to index the standard library
+(`rustup component add rust-src`).
+
+Confirm it resolves:
+
+```bash
+command -v rust-analyzer
+```
+
+## Server settings
+
+Grok Build documents no project language-server schema, and LitGrok ships no server
+configuration: the only documented code-intelligence surface is the built-in tool
+behind `GROK_LSP_TOOLS=1` / `[features] lsp_tools`, which is off by default (see the
+`lsp` skill). Installing the server binary on PATH is the whole setup this reference
+can vouch for. Do not add a server entry to `.grok/config.toml`; that key is not a
+documented Grok Build surface.
+
+## Alternatives
+
+None — `rust-analyzer` is the official and sole Rust language server.
+
+## Troubleshooting
+- **PATH:** `rust-analyzer` must be on PATH; reopen shell after install. The rustup shim lives in `~/.cargo/bin`.
+- **Exits while loading rust-src:** if rust-analyzer crashes during stdlib indexing, reinstall the source component:
+
+  ```bash
+  rustup component remove rust-src && rustup component add rust-src
+  ```
+
+- **No proc-macro / build script support:** ensure the project builds with `cargo check`; rust-analyzer reuses the same toolchain.
+
+## Verify
+
+```bash
+command -v rust-analyzer
+```
+
+A resolving executable is the only claim this reference makes. Whether Grok Build's
+built-in code-intelligence tool picks the server up is undocumented; confirm tool
+visibility inside the session as the `lsp` skill describes, and fall back to the
+project's own checks when it is absent.

package/.grok/skills/lsp-setup/references/swift/README.md

@@ -0,0 +1,52 @@
+# Swift — LSP setup (Grok Build / LitGrok)
+
+- **Recommended server:** `sourcekit-lsp`
+- **Extensions:** `.swift .objc .objcpp`
+- **Install hint:** `Included with Xcode or the Swift toolchain`
+
+## Install
+
+`sourcekit-lsp` ships with the Swift toolchain — no separate install.
+
+- **macOS:** `xcode-select --install` (or install full Xcode). It resolves to the active toolchain selected by `xcode-select`.
+- **Linux:** Install a swift.org toolchain (`sourcekit-lsp` ships inside it); add the toolchain's `usr/bin` to PATH.
+- **Windows:** Install the swift.org Windows toolchain; `sourcekit-lsp` is bundled.
+
+Confirm it resolves:
+
+```bash
+command -v sourcekit-lsp
+```
+
+## Server settings
+
+Grok Build documents no project language-server schema, and LitGrok ships no server
+configuration: the only documented code-intelligence surface is the built-in tool
+behind `GROK_LSP_TOOLS=1` / `[features] lsp_tools`, which is off by default (see the
+`lsp` skill). Installing the server binary on PATH is the whole setup this reference
+can vouch for. Do not add a server entry to `.grok/config.toml`; that key is not a
+documented Grok Build surface.
+
+## Alternatives
+
+**No mainstream alternative.** `sourcekit-lsp` is the official Apple/swift.org
+server and the only practical choice.
+
+## Troubleshooting
+
+- **PATH:** `sourcekit-lsp` on PATH; reopen shell after install (or after `xcode-select -s`).
+- **Wrong toolchain (macOS):** point `xcode-select` at the right Xcode/toolchain; mismatches cause stale or missing results.
+- **No `Package.swift` / compile db:** add a SwiftPM manifest or generate `compile_commands.json` for accurate indexing.
+- **Objective-C (`.objc`/`.objcpp`):** needs a compilation database to resolve headers and frameworks.
+- **First build slow:** the server builds the module graph on first open; wait for it.
+
+## Verify
+
+```bash
+command -v sourcekit-lsp
+```
+
+A resolving executable is the only claim this reference makes. Whether Grok Build's
+built-in code-intelligence tool picks the server up is undocumented; confirm tool
+visibility inside the session as the `lsp` skill describes, and fall back to the
+project's own checks when it is absent.

package/.grok/skills/lsp-setup/references/terraform/README.md

@@ -0,0 +1,50 @@
+# Terraform — LSP setup (Grok Build / LitGrok)
+
+- **Recommended server:** `terraform-ls serve`
+- **Extensions:** `.tf .tfvars`
+- **Install hint:** See https://github.com/hashicorp/terraform-ls
+
+## Install
+
+- **macOS:** `brew install hashicorp/tap/terraform-ls`
+- **Linux:** download a release from https://github.com/hashicorp/terraform-ls/releases and place `terraform-ls` on PATH (or `apt`/`dnf` via the HashiCorp repo)
+- **Windows:** `choco install terraform-ls` (or download a release zip)
+
+`terraform-ls` requires the `terraform` binary itself to be installed and on PATH.
+
+Confirm both resolve:
+
+```bash
+command -v terraform-ls
+command -v terraform
+```
+
+## Server settings
+
+Grok Build documents no project language-server schema, and LitGrok ships no server
+configuration: the only documented code-intelligence surface is the built-in tool
+behind `GROK_LSP_TOOLS=1` / `[features] lsp_tools`, which is off by default (see the
+`lsp` skill). Installing the server binary on PATH is the whole setup this reference
+can vouch for. Do not add a server entry to `.grok/config.toml`; that key is not a
+documented Grok Build surface.
+
+## Alternatives
+
+- `tflint` standalone for opinionated linting (complements the LSP).
+- `terraform fmt` for formatting.
+
+## Troubleshooting
+- **PATH:** `terraform-ls` AND `terraform` both on PATH; reopen shell after install.
+- **No provider completion:** run `terraform init` so the `.terraform/` schema cache exists.
+- **`.tfvars` not analyzed:** open the containing module so the server has root context.
+
+## Verify
+
+```bash
+command -v terraform-ls
+```
+
+A resolving executable is the only claim this reference makes. Whether Grok Build's
+built-in code-intelligence tool picks the server up is undocumented; confirm tool
+visibility inside the session as the `lsp` skill describes, and fall back to the
+project's own checks when it is absent.

package/.grok/skills/lsp-setup/references/typescript/README.md

@@ -0,0 +1,63 @@
+# TypeScript / JavaScript — LSP setup (Grok Build / LitGrok)
+
+- **Recommended server:** `typescript-language-server --stdio`
+- **Extensions:** `.ts .tsx .js .jsx .mjs .cjs .mts .cts`
+- **Install hint:** `npm install -g typescript-language-server typescript`
+
+## Install
+
+- **macOS:** `npm install -g typescript-language-server typescript`
+- **Linux:** `npm install -g typescript-language-server typescript`
+- **Windows:** `npm install -g typescript-language-server typescript` (PowerShell or cmd)
+
+`typescript-language-server` is only a thin wrapper — it needs the `typescript`
+package (`tsserver`) present too, either globally or in the project's
+`node_modules`. Always install both.
+
+Confirm it resolves:
+
+```bash
+command -v typescript-language-server
+```
+
+## Server settings
+
+Grok Build documents no project language-server schema, and LitGrok ships no server
+configuration: the only documented code-intelligence surface is the built-in tool
+behind `GROK_LSP_TOOLS=1` / `[features] lsp_tools`, which is off by default (see the
+`lsp` skill). Installing the server binary on PATH is the whole setup this reference
+can vouch for. Do not add a server entry to `.grok/config.toml`; that key is not a
+documented Grok Build surface.
+
+## Alternatives
+
+Swap the server launch for your toolchain; each row owns the extensions named in
+its description:
+
+| server launch                             | when to choose                          |
+| ----------------------------------------- | --------------------------------------- |
+| `["deno", "lsp"]`                         | Deno projects (handles `.ts/.tsx/.js`)  |
+| `["biome", "lsp-proxy", "--stdio"]`       | Biome lint/format as the LSP            |
+| `["vscode-eslint-language-server", "--stdio"]` | ESLint diagnostics                 |
+| `["oxlint", "--lsp"]`                     | fast Oxc-based linting                  |
+| `["vue-language-server", "--stdio"]`      | `.vue` single-file components           |
+| `["svelteserver", "--stdio"]`             | `.svelte` files                         |
+| `["astro-ls", "--stdio"]`                 | `.astro` files                          |
+
+`eslint` install: `npm i -g vscode-langservers-extracted`. To run Deno instead
+of the default, launch `deno lsp` in place of `typescript-language-server --stdio`.
+
+## Troubleshooting
+- **PATH:** `typescript-language-server` must be on PATH; reopen shell after `npm i -g`. Check your global bin with `npm bin -g`.
+- **Missing tsserver:** errors like "Could not find tsserver" mean the `typescript` package is absent — install it globally or in the project.
+
+## Verify
+
+```bash
+command -v typescript-language-server
+```
+
+A resolving executable is the only claim this reference makes. Whether Grok Build's
+built-in code-intelligence tool picks the server up is undocumented; confirm tool
+visibility inside the session as the `lsp` skill describes, and fall back to the
+project's own checks when it is absent.

package/.grok/skills/lsp-setup/references/yaml/README.md

@@ -0,0 +1,47 @@
+# YAML — LSP setup (Grok Build / LitGrok)
+
+- **Recommended server:** `yaml-language-server --stdio`
+- **Extensions:** `.yaml .yml`
+- **Install hint:** `npm install -g yaml-language-server`
+
+## Install
+
+- **macOS:** `npm install -g yaml-language-server`
+- **Linux:** `npm install -g yaml-language-server`
+- **Windows:** `npm install -g yaml-language-server` (PowerShell)
+
+Confirm it resolves:
+
+```bash
+command -v yaml-language-server
+```
+
+## Server settings
+
+Grok Build documents no project language-server schema, and LitGrok ships no server
+configuration: the only documented code-intelligence surface is the built-in tool
+behind `GROK_LSP_TOOLS=1` / `[features] lsp_tools`, which is off by default (see the
+`lsp` skill). Installing the server binary on PATH is the whole setup this reference
+can vouch for. Do not add a server entry to `.grok/config.toml`; that key is not a
+documented Grok Build surface.
+
+## Alternatives
+
+- `redhat.vscode-yaml` bundles the same server in editors.
+- `yamllint` standalone for style/lint-only checks.
+
+## Troubleshooting
+- **PATH:** `yaml-language-server` on PATH; reopen shell after `npm -g` install.
+- **No validation:** no schema matched — add a `$schema` modeline or a `yaml.schemas` mapping in your editor's init options.
+- **Wrong schema applied:** SchemaStore guessed by filename; pin explicitly with a modeline.
+
+## Verify
+
+```bash
+command -v yaml-language-server
+```
+
+A resolving executable is the only claim this reference makes. Whether Grok Build's
+built-in code-intelligence tool picks the server up is undocumented; confirm tool
+visibility inside the session as the `lsp` skill describes, and fall back to the
+project's own checks when it is absent.

package/.grok/skills/lsp-setup/references/zig/README.md

@@ -0,0 +1,49 @@
+# Zig — LSP setup (Grok Build / LitGrok)
+
+- **Recommended server:** `zls`
+- **Extensions:** `.zig .zon`
+- **Install hint:** `https://github.com/zigtools/zls`
+
+## Install
+
+ZLS (the Zig Language Server) must be built against the **same Zig version** you use.
+See `https://github.com/zigtools/zls`.
+
+- **macOS:** `brew install zls`
+- **Linux:** download a prebuilt release matching your Zig version, or `zig build -Doptimize=ReleaseSafe` from the zls source
+- **Windows:** download the matching release from the zls GitHub releases, or build from source
+
+Confirm it resolves:
+
+```bash
+command -v zls
+```
+
+## Server settings
+
+Grok Build documents no project language-server schema, and LitGrok ships no server
+configuration: the only documented code-intelligence surface is the built-in tool
+behind `GROK_LSP_TOOLS=1` / `[features] lsp_tools`, which is off by default (see the
+`lsp` skill). Installing the server binary on PATH is the whole setup this reference
+can vouch for. Do not add a server entry to `.grok/config.toml`; that key is not a
+documented Grok Build surface.
+
+## Alternatives
+
+None.
+
+## Troubleshooting
+- **VERSION MATCH (critical):** zls version MUST match your zig version — build/install zls against the exact same Zig. A mismatch causes crashes, parse errors, or silent failures. After upgrading Zig, upgrade/rebuild zls too.
+- **PATH:** `zls` must be on PATH; reopen the shell after install.
+- **zig not found:** zls invokes `zig` for builds — make sure `zig` itself is also on PATH.
+
+## Verify
+
+```bash
+command -v zls
+```
+
+A resolving executable is the only claim this reference makes. Whether Grok Build's
+built-in code-intelligence tool picks the server up is undocumented; confirm tool
+visibility inside the session as the `lsp` skill describes, and fall back to the
+project's own checks when it is absent.

package/.grok/skills/lsp-setup/scripts/detect-lsp.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+import {
+  assertProjectDirectory,
+  cliExitCode,
+  collectExtensions,
+  coverageForExtensions,
+  hostStatusMessage,
+  inspectProject,
+  isDirectInvocation,
+  parseOptions,
+} from './lsp-server-table.mjs';
+
+function main() {
+  try {
+    const options = parseOptions(process.argv.slice(2), { maxFiles: true, positional: 1 });
+    const project = assertProjectDirectory(options.positionals[0]);
+    const extensions = collectExtensions(project, options.maxFiles);
+    const host = inspectProject(project, options);
+    const report = {
+      root: project,
+      extensions,
+      host,
+      coverage: coverageForExtensions(extensions, host),
+    };
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(report)}\n`);
+    } else {
+      process.stdout.write(`PASS root=${project} extensions=${extensions.length} status=${host.status}\n`);
+      process.stdout.write(`${hostStatusMessage(host)}\n`);
+      for (const entry of report.coverage) process.stdout.write(`${entry.extension}: ${entry.status}\n`);
+    }
+    process.exitCode = 0;
+  } catch (error) {
+    process.stderr.write(`${error?.code ?? 'GROK_DETECT_FAILED'}: ${error?.message ?? String(error)}\n`);
+    process.exitCode = cliExitCode(error);
+  }
+}
+
+if (isDirectInvocation(import.meta.url)) main();

package/.grok/skills/lsp-setup/scripts/lsp-server-table.mjs

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { lstatSync, readdirSync, realpathSync } from 'node:fs';
+import { extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_TIMEOUT_MS = 5_000;
+const MAX_TIMEOUT_MS = 120_000;
+const DEFAULT_MAX_FILES = 50_000;
+const MAX_FILES = 100_000;
+const MAX_OUTPUT_BYTES = 1_024 * 1_024;
+const MAX_INSPECTION_ENTRIES = 64;
+const MAX_INSPECTION_KEYS = 64;
+const SKIPPED_DIRECTORIES = new Set([
+  '.git',
+  '.grok',
+  '.hg',
+  '.svn',
+  'build',
+  'coverage',
+  'dist',
+  'node_modules',
+  'vendor',
+]);
+
+export class LspSetupError extends Error {
+  constructor(code, detail = '') {
+    super(detail ? `${code}: ${detail}` : code);
+    this.name = 'LspSetupError';
+    this.code = code;
+  }
+}
+
+function fail(code, detail = '') {
+  throw new LspSetupError(code, detail);
+}
+
+function safeString(value, maximum) {
+  return typeof value === 'string' && value.length <= maximum && !value.includes('\0') ? value : undefined;
+}
+
+function numericOption(value, fallback, maximum, label) {
+  if (value === undefined) return fallback;
+  if (typeof value !== 'string' || !/^[1-9]\d*$/.test(value)) {
+    fail('CLI_ARGUMENT_INVALID', `${label} must be a positive integer`);
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed > maximum) {
+    fail('CLI_ARGUMENT_INVALID', `${label} exceeds its bound`);
+  }
+  return parsed;
+}
+
+export function parseOptions(argv, { positional = 0, maxFiles = false } = {}) {
+  const options = { json: false, project: undefined, grokBin: undefined, timeout: DEFAULT_TIMEOUT_MS };
+  const positionals = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === '--json') {
+      options.json = true;
+      continue;
+    }
+    if (argument === '--project' || argument.startsWith('--project=')) {
+      const value = argument === '--project' ? argv[++index] : argument.slice('--project='.length);
+      if (!safeString(value, 4_096) || value.startsWith('-')) fail('CLI_ARGUMENT_INVALID', '--project requires a path');
+      options.project = value;
+      continue;
+    }
+    if (argument === '--grok-bin' || argument.startsWith('--grok-bin=')) {
+      const value = argument === '--grok-bin' ? argv[++index] : argument.slice('--grok-bin='.length);
+      if (!safeString(value, 4_096) || value.startsWith('-')) fail('CLI_ARGUMENT_INVALID', '--grok-bin requires a path');
+      options.grokBin = value;
+      continue;
+    }
+    if (argument === '--timeout' || argument.startsWith('--timeout=')) {
+      const value = argument === '--timeout' ? argv[++index] : argument.slice('--timeout='.length);
+      options.timeout = numericOption(value, DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS, '--timeout');
+      continue;
+    }
+    if (maxFiles && (argument === '--max-files' || argument.startsWith('--max-files='))) {
+      const value = argument === '--max-files' ? argv[++index] : argument.slice('--max-files='.length);
+      options.maxFiles = numericOption(value, DEFAULT_MAX_FILES, MAX_FILES, '--max-files');
+      continue;
+    }
+    if (argument.startsWith('-')) fail('CLI_ARGUMENT_INVALID', `unknown argument ${argument}`);
+    positionals.push(argument);
+  }
+  if (positionals.length !== positional) {
+    fail('CLI_ARGUMENT_INVALID', `expected ${positional} positional path${positional === 1 ? '' : 's'}`);
+  }
+  return { ...options, positionals };
+}
+
+export function assertProjectDirectory(input = process.cwd()) {
+  const candidate = resolve(input);
+  let status;
+  try {
+    status = lstatSync(candidate);
+  } catch (error) {
+    fail('GROK_PROJECT_INVALID', `${candidate} (${error?.code ?? 'unreadable'})`);
+  }
+  if (!status.isDirectory() || status.isSymbolicLink()) fail('GROK_PROJECT_INVALID', candidate);
+  try {
+    return realpathSync(candidate);
+  } catch (error) {
+    fail('GROK_PROJECT_INVALID', `${candidate} (${error?.code ?? 'unreadable'})`);
+  }
+}
+
+export function assertRegularFile(input) {
+  const candidate = resolve(input);
+  let status;
+  try {
+    status = lstatSync(candidate);
+  } catch (error) {
+    fail('GROK_FILE_INVALID', `${candidate} (${error?.code ?? 'unreadable'})`);
+  }
+  if (!status.isFile() || status.isSymbolicLink()) fail('GROK_FILE_INVALID', candidate);
+  try {
+    return realpathSync(candidate);
+  } catch (error) {
+    fail('GROK_FILE_INVALID', `${candidate} (${error?.code ?? 'unreadable'})`);
+  }
+}
+
+function childEntries(directory) {
+  try {
+    return readdirSync(directory, { withFileTypes: true })
+      .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+  } catch (error) {
+    fail('GROK_PROJECT_SCAN_FAILED', `${directory} (${error?.code ?? 'unreadable'})`);
+  }
+}
+
+export function collectExtensions(project, maxFiles = DEFAULT_MAX_FILES) {
+  const counts = new Map();
+  let fileCount = 0;
+  function visit(directory) {
+    for (const entry of childEntries(directory)) {
+      if (entry.isSymbolicLink()) continue;
+      const child = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIPPED_DIRECTORIES.has(entry.name)) visit(child);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      fileCount += 1;
+      if (fileCount > maxFiles) fail('GROK_PROJECT_TOO_LARGE', `more than ${maxFiles} files`);
+      const extension = extname(entry.name).toLowerCase();
+      if (extension) counts.set(extension, (counts.get(extension) ?? 0) + 1);
+    }
+  }
+  visit(project);
+  return [...counts.entries()]
+    .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+    .map(([extension, files]) => ({ extension, files }));
+}
+
+function boundedOutput(value) {
+  return typeof value === 'string' && Buffer.byteLength(value, 'utf8') <= MAX_OUTPUT_BYTES ? value : undefined;
+}
+
+function inspectBinary(options, env) {
+  return options.grokBin ?? env.GROK_BIN ?? env.LITGROK_GROK_BIN ?? 'grok';
+}
+
+function runGrokInspect(project, options = {}) {
+  const env = options.env ?? process.env;
+  const result = spawnSync(inspectBinary(options, env), ['inspect', '--json'], {
+    cwd: project,
+    encoding: 'utf8',
+    env,
+    maxBuffer: MAX_OUTPUT_BYTES,
+    timeout: options.timeout ?? DEFAULT_TIMEOUT_MS,
+    windowsHide: true,
+  });
+  const stdout = boundedOutput(result.stdout);
+  const stderr = boundedOutput(result.stderr);
+  if (result.error || result.status !== 0 || stdout === undefined) {
+    return {
+      ok: false,
+      status: result.status,
+      signal: result.signal,
+      errorCode: result.error?.code ?? (stdout === undefined ? 'OUTPUT_TOO_LARGE' : 'EXIT_NONZERO'),
+      timedOut: result.error?.code === 'ETIMEDOUT',
+      stdoutBytes: typeof result.stdout === 'string' ? Buffer.byteLength(result.stdout, 'utf8') : 0,
+      stderrBytes: typeof result.stderr === 'string' ? Buffer.byteLength(result.stderr, 'utf8') : 0,
+    };
+  }
+  return {
+    ok: true,
+    stdout,
+    stderr,
+    status: result.status,
+    signal: result.signal,
+  };
+}
+
+function parseInspection(result) {
+  if (!result.ok) {
+    const detail = result.timedOut
+      ? 'inspect timed out'
+      : `${result.errorCode ?? 'failed'} status=${result.status ?? 'null'} signal=${result.signal ?? 'none'}`;
+    fail('GROK_INSPECT_FAILED', detail);
+  }
+  let value;
+  try {
+    value = JSON.parse(result.stdout);
+  } catch {
+    fail('GROK_INSPECT_FAILED', 'inspect returned invalid JSON');
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    fail('GROK_INSPECT_FAILED', 'inspect returned a non-object');
+  }
+  return value;
+}
+
+export function summarizeInspection(value) {
+  const hasInventory = Array.isArray(value.lspServers);
+  const status = hasInventory
+    ? (value.lspServers.length === 0 ? 'unconfigured' : 'opaque')
+    : 'not-exposed';
+  const summary = {
+    status,
+    lspServerCount: hasInventory ? value.lspServers.length : null,
+    entries: hasInventory
+      ? value.lspServers.slice(0, MAX_INSPECTION_ENTRIES).map((entry, index) => ({
+        index,
+        keys: entry && typeof entry === 'object' && !Array.isArray(entry)
+          ? Object.keys(entry).sort().slice(0, MAX_INSPECTION_KEYS)
+          : [],
+      }))
+      : [],
+  };
+  if (typeof value.grokVersion === 'string' && value.grokVersion.length <= 128) summary.grokVersion = value.grokVersion;
+  if (typeof value.projectRoot === 'string' && value.projectRoot.length <= 4_096) summary.projectRoot = value.projectRoot;
+  if (value.projectRoot === null) summary.projectRoot = null;
+  if (typeof value.projectTrusted === 'boolean') summary.projectTrusted = value.projectTrusted;
+  return summary;
+}
+
+export function inspectProject(project, options = {}) {
+  const result = runGrokInspect(project, options);
+  return summarizeInspection(parseInspection(result));
+}
+
+export function hostStatusMessage(summary) {
+  if (summary.status === 'unconfigured') {
+    return 'Grok Build reported no language-server entries; no direct diagnostics transport is exposed; use compiler, linter, or tests.';
+  }
+  if (summary.status === 'opaque') {
+    return 'Grok Build reported opaque host language-server entries, but no documented diagnostic transport is exposed.';
+  }
+  if (summary.status === 'not-exposed') {
+    return 'Grok Build does not expose a language-server inventory; use compiler, linter, or tests.';
+  }
+  return 'Grok Build language-server inspection failed; no diagnostics were attempted.';
+}
+
+export function coverageForExtensions(extensions, summary) {
+  return extensions.map(({ extension, files }) => ({
+    extension,
+    files,
+    status: summary.status,
+    message: hostStatusMessage(summary),
+  }));
+}
+
+export function ensureFileInProject(file, project) {
+  const suffix = relative(project, file);
+  const parentPrefix = `..${sep}`;
+  if (!suffix || isAbsolute(suffix) || suffix === '..' || suffix.startsWith(parentPrefix)) {
+    fail('GROK_FILE_OUTSIDE_PROJECT', `${file} is not below ${project}`);
+  }
+  return file;
+}
+
+export function cliExitCode(error, fallback = 1) {
+  if (error?.code === 'CLI_ARGUMENT_INVALID' || error?.code === 'GROK_PROJECT_INVALID'
+    || error?.code === 'GROK_FILE_INVALID' || error?.code === 'GROK_FILE_OUTSIDE_PROJECT') return 2;
+  return fallback;
+}
+
+export function isDirectInvocation(moduleUrl = import.meta.url) {
+  if (!process.argv[1]) return false;
+  try {
+    return fileURLToPath(moduleUrl) === realpathSync(resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+function main() {
+  try {
+    const options = parseOptions(process.argv.slice(2));
+    const project = assertProjectDirectory(options.project ?? process.cwd());
+    const summary = inspectProject(project, options);
+    const report = { ...summary, message: hostStatusMessage(summary) };
+    if (options.json) process.stdout.write(`${JSON.stringify(report)}\n`);
+    else process.stdout.write(`PASS status=${summary.status} lspServers=${summary.lspServerCount ?? 'not-exposed'}\n${report.message}\n`);
+    process.exitCode = 0;
+  } catch (error) {
+    process.stderr.write(`${error?.code ?? 'GROK_INSPECT_FAILED'}: ${error?.message ?? String(error)}\n`);
+    process.exitCode = cliExitCode(error);
+  }
+}
+
+if (isDirectInvocation()) main();