@hevmind/ask 0.1.0

package/README.md

@@ -0,0 +1,116 @@
+# @hevmind/ask
+
+hev ask is a heading-anchored search overlay for Astro docs sites. Typing runs
+instant keyword search; pressing `Enter` runs an optional Claude search loop that
+chooses sub-queries and ranks section results.
+
+## Install
+
+```sh
+pnpm add @hevmind/ask
+```
+
+For the current GitHub-hosted monorepo package before npm publication:
+
+```sh
+pnpm add "git+ssh://git@github.com/hev/ask.git#main&path:/packages/ui"
+```
+
+## Configure
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import hevAsk from '@hevmind/ask';
+
+export default defineConfig({
+  integrations: [
+    hevAsk({
+      collections: ['docs'],
+      basePath: '/docs/',
+    }),
+  ],
+});
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `collections` | - | Content collections to index. |
+| `model` | `claude-haiku-4-5` | Runtime search-loop model. |
+| `endpoint` | `/api/ask` | Injected on-demand route. |
+| `basePath` | `/docs/` | Turns a doc slug into its page URL. |
+| `maxResults` | `6` | Max results returned. |
+| `maxIterations` | `4` | Max search-loop rounds. |
+| `chunkHeadingDepth` | `3` | Chunk at `##` through this heading depth. |
+| `candidatePerSearch` | `8` | Chunks returned by each search tool call. |
+| `perDocCap` | `2` | Max chunks per document in one prefilter call. |
+| `digestModel` | `claude-opus-4-8` | Offline digest build model. |
+| `digestPath` | `.hev-ask/digest.json` | Committed digest artifact path. |
+| `digestContentGlobs` | derived from `collections` | Build-time Markdown/MDX corpus globs. |
+
+## Add the overlay
+
+```astro
+---
+import SearchOverlay from '@hevmind/ask/components/SearchOverlay.astro';
+---
+<button data-hev-ask-open>Search <kbd>⌘K</kbd></button>
+
+<!-- once per page, e.g. at the end of your layout -->
+<SearchOverlay />
+```
+
+Open with `⌘K` / `Ctrl+K`, or `/`. Any element with `data-hev-ask-open` also
+opens it. Typing returns keyword results immediately. Press `Enter` to ask AI,
+or move the selection with arrows/hover and press `Enter` to open a keyword hit.
+
+## Ask digest
+
+```sh
+ask digest build
+ask digest verify
+```
+
+The builder writes `.hev-ask/digest.json`, which should be committed. Builds are
+hash-gated, so unchanged content does not spend another Opus call. `verify`
+builds the site and checks that every chunk anchor exists in `dist`.
+
+hev ask uses `github-slugger` to match Astro heading anchors exactly.
+
+Recommended CI gates:
+
+```sh
+pnpm test
+pnpm typecheck
+pnpm build
+pnpm digest:verify
+```
+
+## Publishing
+
+This package is intended to publish as `@hevmind/ask`. Before publishing, bump the
+version, run the verification gates, inspect `pnpm --filter @hevmind/ask pack
+--dry-run`, then publish from this package directory with:
+
+```sh
+pnpm publish --access public
+```
+
+After publish, consumers should depend on the npm semver range instead of the
+Git `path:/packages/ui` dependency.
+
+Git dependencies are acceptable for local integration while the package is not
+yet published, but they are not the long-term distribution path.
+
+## Server Requirements
+
+- Set `ANTHROPIC_API_KEY` for AI search and fresh digest generation.
+- Without a runtime key, `/api/ask` still serves keyword results.
+- The search route is rendered on demand, so the site needs a server adapter in
+  production.
+
+## Theming
+
+The overlay reads your site's CSS custom properties with dark fallbacks:
+`--paper` (background), `--ink` (text), `--muted`, `--signal` (accent), and
+`--font-mono`. Define these on `:root` to match your brand.

package/bin/ask-launcher.mjs

@@ -0,0 +1,110 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+
+export async function runAsk(args, options = {}) {
+  const target = resolveAskTarget();
+  if (!target) {
+    const platform = `${process.platform}/${process.arch}`;
+    console.error(
+      `[hev-ask] No ask binary is available for ${platform}. ` +
+        'Install a package with @hevmind/ask optional binaries, set HEV_ASK_BINARY, or run from a source checkout with Go installed.',
+    );
+    return 1;
+  }
+
+  return run(target.command, [...target.args, ...args], {
+    cwd: target.cwd,
+    env: options.env ?? process.env,
+  });
+}
+
+function resolveAskTarget() {
+  const explicit = process.env.HEV_ASK_BINARY;
+  if (explicit) return { command: explicit, args: [] };
+
+  const packaged = resolvePackagedBinary();
+  if (packaged) return { command: packaged, args: [] };
+
+  const sourceRoot = findSourceRoot();
+  if (sourceRoot) return { command: 'go', args: ['run', path.join(sourceRoot, 'cmd', 'ask')], cwd: process.cwd() };
+
+  return null;
+}
+
+function resolvePackagedBinary() {
+  const packageName = platformPackageName();
+  if (!packageName) return null;
+  try {
+    const packageJson = require.resolve(`${packageName}/package.json`);
+    const candidate = path.join(path.dirname(packageJson), 'bin', executableName());
+    return existsSync(candidate) ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+
+function platformPackageName() {
+  const platform = process.platform;
+  const arch = process.arch;
+  if (platform === 'darwin' && arch === 'arm64') return '@hevmind/ask-darwin-arm64';
+  if (platform === 'darwin' && arch === 'x64') return '@hevmind/ask-darwin-x64';
+  if (platform === 'linux' && arch === 'arm64') return '@hevmind/ask-linux-arm64';
+  if (platform === 'linux' && arch === 'x64') return '@hevmind/ask-linux-x64';
+  if (platform === 'win32' && arch === 'x64') return '@hevmind/ask-win32-x64';
+  return null;
+}
+
+function executableName() {
+  return process.platform === 'win32' ? 'ask.exe' : 'ask';
+}
+
+function findSourceRoot() {
+  let current = path.dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 8; i += 1) {
+    const goMod = path.join(current, 'go.mod');
+    const main = path.join(current, 'cmd', 'ask', 'main.go');
+    if (existsSync(goMod) && existsSync(main) && isHevAskModule(goMod)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+
+function isHevAskModule(goMod) {
+  try {
+    return readFileSync(goMod, 'utf8').includes('module github.com/hev/ask');
+  } catch {
+    return false;
+  }
+}
+
+function run(command, args, options) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: 'inherit',
+      windowsHide: true,
+    });
+
+    child.on('error', (err) => {
+      console.error(`[hev-ask] Could not start ${command}: ${err.message}`);
+      resolve(1);
+    });
+
+    child.on('exit', (code, signal) => {
+      if (signal) {
+        process.kill(process.pid, signal);
+        resolve(1);
+        return;
+      }
+      resolve(code ?? 1);
+    });
+  });
+}

package/bin/ask.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runAsk } from './ask-launcher.mjs';
+
+process.exitCode = await runAsk(process.argv.slice(2));

package/openapi.yaml

@@ -0,0 +1,363 @@
+openapi: 3.1.0
+info:
+  title: hev ask API
+  version: 3.0.0
+  summary: Search, answer, and digest read API exposed by the @hevmind/ask Astro integration.
+  description: |
+    `@hevmind/ask` mounts these routes on a consuming Astro site (default base `/api/ask`,
+    configurable via the integration's `endpoint` option). Two paths existed in v2:
+    keyword + agentic **search** (`POST /api/ask`) and **suggestions** (`GET /api/ask`).
+    v3 adds keyless **read** routes over the committed ask digest
+    (`/api/ask/glossary`, `/api/ask/sections`, `/api/ask/overview`) so a coding agent —
+    via the `ask` CLI, the MCP server, or a generated client — can query the docs
+    directly.
+
+    Degradation: with no `ANTHROPIC_API_KEY` configured on the server, `POST /api/ask`
+    falls back to keyword mode (HTTP 200 with a `warning`). The read routes never call a
+    model and never require a key.
+  license:
+    name: MIT
+servers:
+  - url: https://askhev.com
+    description: The hev ask docs site (dogfoods @hevmind/ask).
+  - url: "{origin}"
+    description: Any site running the integration.
+    variables:
+      origin:
+        default: http://localhost:4321
+tags:
+  - name: search
+    description: Keyword and agentic search/answer.
+  - name: digest
+    description: Keyless reads over the committed ask digest.
+
+paths:
+  /api/ask:
+    get:
+      tags: [search]
+      operationId: getSuggestions
+      summary: Suggested questions and active model
+      description: |
+        Returns the model-authored example questions baked into the committed graph,
+        shown by the overlay on open. Keyless — no model call.
+      responses:
+        "200":
+          description: Suggestions and the configured answer model.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SuggestionsResponse"
+    post:
+      tags: [search]
+      operationId: ask
+      summary: Search (keyword JSON) or answer (agentic SSE)
+      description: |
+        With `mode: "keyword"` (or when no API key is configured) returns ranked keyword
+        results as JSON. With `mode: "agentic"` and a configured key, returns a
+        Server-Sent Events stream of the grounded answer.
+
+        The SSE stream emits these named events, each with a JSON `data` payload:
+          - `sources` — `{ sources: Source[], model, mode: "agentic" }`
+          - `search`  — `{ query }` (a sub-query the loop issued)
+          - `token`   — `{ text }` (a chunk of the streamed answer)
+          - `done`    — `{}`
+          - `error`   — `{ error }` (failures after the stream has started)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AskRequest"
+      responses:
+        "200":
+          description: |
+            Keyword results (JSON) or the agentic answer stream (SSE), depending on `mode`
+            and server key configuration.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/KeywordResponse"
+            text/event-stream:
+              schema:
+                type: string
+                description: SSE stream; see operation description for event types.
+        "400":
+          description: Invalid JSON body.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "500":
+          description: Index build failure (e.g. misconfigured collections).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
+  /api/ask/glossary:
+    get:
+      tags: [digest]
+      operationId: listGlossary
+      summary: List glossary terms
+      description: All glossary entries from the committed graph. Keyless.
+      responses:
+        "200":
+          description: The glossary.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [terms]
+                properties:
+                  terms:
+                    type: array
+                    items: { $ref: "#/components/schemas/GlossaryEntry" }
+
+  /api/ask/glossary/{term}:
+    get:
+      tags: [digest]
+      operationId: getGlossaryTerm
+      summary: Get one glossary entry
+      description: Matches case-insensitively on the term or any of its aliases.
+      parameters:
+        - $ref: "#/components/parameters/Term"
+      responses:
+        "200":
+          description: The matched glossary entry.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/GlossaryEntry" }
+        "404":
+          description: No term or alias matched.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Error" }
+
+  /api/ask/sections:
+    get:
+      tags: [digest]
+      operationId: listSections
+      summary: List section nodes
+      description: |
+        A lightweight listing of every section node in the graph. Use `section get` /
+        `GET /api/ask/sections/{id}` for the full node with facts and sources.
+      parameters:
+        - name: group
+          in: query
+          required: false
+          schema: { type: string }
+          description: Filter to sections in this group (e.g. `API`).
+      responses:
+        "200":
+          description: Section summaries.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [sections]
+                properties:
+                  sections:
+                    type: array
+                    items: { $ref: "#/components/schemas/SectionSummary" }
+
+  /api/ask/sections/{id}:
+    get:
+      tags: [digest]
+      operationId: getSection
+      summary: Get one section node
+      description: The full distilled node — summary, verbatim facts, sources, deep link.
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: string }
+          description: The section id, e.g. `concepts#the-agentic-loop`.
+      responses:
+        "200":
+          description: The section node.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/DigestNode" }
+        "404":
+          description: No node with that id.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Error" }
+
+  /api/ask/overview:
+    get:
+      tags: [digest]
+      operationId: getOverview
+      summary: Grouped map + orientation
+      description: |
+        The deterministic grouped table of contents (`overview`) and the model-authored
+        prose orientation (`context`). The cheapest way for an agent to get its bearings.
+      responses:
+        "200":
+          description: Overview and context.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [overview, context]
+                properties:
+                  overview: { type: string }
+                  context: { type: string }
+
+components:
+  parameters:
+    Term:
+      name: term
+      in: path
+      required: true
+      schema: { type: string }
+      description: A glossary term or alias (case-insensitive).
+
+  schemas:
+    AskRequest:
+      type: object
+      required: [query]
+      properties:
+        query:
+          type: string
+          description: The user's search text.
+        mode:
+          type: string
+          enum: [keyword, agentic]
+          default: keyword
+          description: |
+            `keyword` returns JSON results. `agentic` streams a grounded answer over SSE
+            (falls back to keyword JSON with a `warning` if the server has no API key).
+
+    KeywordResponse:
+      type: object
+      required: [results, query, model, mode]
+      properties:
+        results:
+          type: array
+          items: { $ref: "#/components/schemas/KeywordResult" }
+        query: { type: string }
+        model: { type: string }
+        mode:
+          type: string
+          enum: [keyword]
+        warning:
+          type: string
+          description: Present when agentic mode was requested but is unavailable.
+
+    KeywordResult:
+      type: object
+      required: [title, url, snippet]
+      properties:
+        title: { type: string }
+        heading: { type: string }
+        url:
+          type: string
+          description: Deep link, e.g. `/docs/concepts#the-agentic-loop`.
+        group: { type: string }
+        snippet: { type: string }
+
+    SuggestionsResponse:
+      type: object
+      required: [suggestions, model]
+      properties:
+        suggestions:
+          type: array
+          items: { type: string }
+        model: { type: string }
+
+    Source:
+      type: object
+      description: A source cited by the agentic answer.
+      required: [url]
+      properties:
+        title: { type: string }
+        heading: { type: string }
+        group: { type: string }
+        url: { type: string }
+        terms:
+          type: array
+          items: { type: string }
+
+    GlossaryEntry:
+      type: object
+      required: [term, aliases, definition]
+      properties:
+        term: { type: string }
+        aliases:
+          type: array
+          items: { type: string }
+        definition: { type: string }
+
+    SectionSummary:
+      type: object
+      required: [id, title, url]
+      properties:
+        id:
+          type: string
+          description: Section id (`slug#anchor`, or `slug` for a page-level section).
+        title: { type: string }
+        heading:
+          type: [string, "null"]
+        group:
+          type: [string, "null"]
+        url: { type: string }
+
+    Fact:
+      type: object
+      description: A byte-verbatim literal lifted from the source section.
+      required: [kind, literal, chunkId]
+      properties:
+        kind:
+          type: string
+          enum: [flag, code, value, default, key]
+        literal:
+          type: string
+          description: Exact source text — never paraphrased.
+        chunkId: { type: string }
+
+    SourceRef:
+      type: object
+      required: [chunkId, url]
+      properties:
+        chunkId: { type: string }
+        url: { type: string }
+        anchor:
+          type: [string, "null"]
+          description: github-slugger anchor, or null for a page-level section.
+
+    DigestNode:
+      type: object
+      required: [id, kind, title, url, summary, facts, sources, mode, terms]
+      properties:
+        id: { type: string }
+        kind:
+          type: string
+          enum: [section]
+        title: { type: string }
+        heading:
+          type: [string, "null"]
+        group:
+          type: [string, "null"]
+        url: { type: string }
+        summary:
+          type: string
+          description: Model-distilled prose. Exact strings live in `facts`.
+        facts:
+          type: array
+          items: { $ref: "#/components/schemas/Fact" }
+        sources:
+          type: array
+          items: { $ref: "#/components/schemas/SourceRef" }
+        mode:
+          type: string
+          enum: [agent-primary, source-primary]
+        terms:
+          type: array
+          items: { type: string }
+
+    Error:
+      type: object
+      required: [error]
+      properties:
+        error: { type: string }

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@hevmind/ask",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "hev ask: a heading-anchored, agentic search overlay for Astro docs sites.",
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "withastro",
+    "search",
+    "agentic",
+    "command-palette",
+    "cmdk",
+    "claude",
+    "anthropic",
+    "ai"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/hev/ask#readme",
+  "sideEffects": false,
+  "files": [
+    "bin",
+    "openapi.yaml",
+    "src",
+    "skills"
+  ],
+  "bin": {
+    "ask": "./bin/ask.mjs"
+  },
+  "optionalDependencies": {
+    "@hevmind/ask-darwin-arm64": "0.1.0",
+    "@hevmind/ask-linux-arm64": "0.1.0",
+    "@hevmind/ask-darwin-x64": "0.1.0",
+    "@hevmind/ask-linux-x64": "0.1.0",
+    "@hevmind/ask-win32-x64": "0.1.0"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./endpoint": "./src/endpoint.ts",
+    "./components/SearchOverlay.astro": "./src/components/SearchOverlay.astro",
+    "./openapi.yaml": "./openapi.yaml",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "github-slugger": "^2.0.0"
+  },
+  "peerDependencies": {
+    "astro": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "astro": "^5.0.0",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "digest:build": "node bin/ask.mjs digest build",
+    "digest:verify": "node bin/ask.mjs digest verify",
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  }
+}