@cruxy/cli 0.1.1 → 0.3.0

package/dist/tools/load-skill.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import type { Tool } from "./types.js";
+declare const parameters: z.ZodObject<{
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+}, {
+    name: string;
+}>;
+/**
+ * Load a skill's full instructions on demand — the expensive half of
+ * progressive disclosure. Returns the markdown body plus the absolute asset root
+ * and the relative paths of any `scripts/` and `reference/` files, so the agent
+ * can read or run them through the existing read_file / run_command tools.
+ *
+ * Read-only — no approval. Loading a skill never executes anything: scripts are
+ * surfaced as paths only and run, if at all, through run_command (which applies
+ * the normal approval gate).
+ */
+export declare const loadSkillTool: Tool<typeof parameters>;
+export {};

package/dist/tools/load-skill.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { getSkillService } from "../skills/index.js";
+const parameters = z.object({
+    name: z
+        .string()
+        .min(1)
+        .describe("The exact name of the skill to load (from list_skills)."),
+});
+/**
+ * Load a skill's full instructions on demand — the expensive half of
+ * progressive disclosure. Returns the markdown body plus the absolute asset root
+ * and the relative paths of any `scripts/` and `reference/` files, so the agent
+ * can read or run them through the existing read_file / run_command tools.
+ *
+ * Read-only — no approval. Loading a skill never executes anything: scripts are
+ * surfaced as paths only and run, if at all, through run_command (which applies
+ * the normal approval gate).
+ */
+export const loadSkillTool = {
+    name: "load_skill",
+    description: "Load the full instructions for a skill by name (discover names with list_skills). Returns the skill's markdown body plus the paths of any bundled scripts/reference files. Read-only and requires no approval — it never runs anything; use run_command to execute a script the skill describes.",
+    parameters,
+    async execute(input, ctx) {
+        try {
+            const skill = await getSkillService(ctx.cwd, ctx.logger).load(input.name);
+            return { ok: true, output: formatSkill(skill) };
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
+    },
+};
+/** Render a loaded skill: instructions, then an asset reference footer. */
+function formatSkill(skill) {
+    const parts = [
+        `# Skill: ${skill.name} (${skill.source})`,
+        "",
+        skill.body.trim(),
+    ];
+    const footer = [`Asset root: ${skill.assetRoot}`];
+    if (skill.scripts.length > 0) {
+        footer.push(`Scripts (run via run_command — not auto-executed): ${skill.scripts.join(", ")}`);
+    }
+    if (skill.references.length > 0) {
+        footer.push(`References (read via read_file): ${skill.references.join(", ")}`);
+    }
+    parts.push("", "---", footer.join("\n"));
+    return parts.join("\n");
+}

package/dist/tools/registry.js

@@ -3,6 +3,9 @@ import { listFilesTool } from "./list-files.js";
 import { gitStatusTool } from "./git-status.js";
 import { readFileTool, writeFileTool, editFileTool, applyPatchTool, globTool, grepFilesTool, } from "./file/index.js";
 import { runCommandTool } from "./shell/index.js";
+import { searchCodebaseTool } from "./search-codebase.js";
+import { listSkillsTool } from "./list-skills.js";
+import { loadSkillTool } from "./load-skill.js";
 /**
  * In-memory catalogue of the tools available to the agent. Names are unique;
  * `toToolSpecs()` projects the catalogue into the `@cruxy/sdk` wire format.
@@ -59,5 +62,8 @@ export function buildDefaultRegistry() {
     registry.register(grepFilesTool);
     registry.register(gitStatusTool);
     registry.register(runCommandTool);
+    registry.register(searchCodebaseTool);
+    registry.register(listSkillsTool);
+    registry.register(loadSkillTool);
     return registry;
 }

package/dist/tools/search-codebase.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import type { Tool } from "./types.js";
+declare const parameters: z.ZodObject<{
+    query: z.ZodString;
+    k: z.ZodOptional<z.ZodNumber>;
+    pathGlob: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    k?: number | undefined;
+    pathGlob?: string | undefined;
+}, {
+    query: string;
+    k?: number | undefined;
+    pathGlob?: string | undefined;
+}>;
+/**
+ * Semantic search over the project's local code index (C.17). Read-only — no
+ * approval — like read_file and grep_files. The index is built/refreshed lazily
+ * on first use; results are ranked by cosine similarity and token-budgeted.
+ *
+ * Complements `grep_files`: prefer this for conceptual "where / how does X work"
+ * questions, and grep for exact strings or symbols.
+ */
+export declare const searchCodebaseTool: Tool<typeof parameters>;
+export {};

package/dist/tools/search-codebase.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { getIndexService } from "../indexing/index.js";
+/** Hard cap on `k`, mirroring the retriever. */
+const MAX_K = 50;
+const parameters = z.object({
+    query: z
+        .string()
+        .min(1)
+        .describe("A natural-language description of the code you're looking for (e.g. 'where are tool results fed back to the model', 'JWT verification'). Concepts work better than exact tokens."),
+    k: z
+        .number()
+        .int()
+        .positive()
+        .max(MAX_K)
+        .optional()
+        .describe("Number of results to return (default 8)."),
+    pathGlob: z
+        .string()
+        .optional()
+        .describe("Optional glob to restrict results by path, e.g. 'src/**/*.ts' or 'packages/cli/**'."),
+});
+/**
+ * Semantic search over the project's local code index (C.17). Read-only — no
+ * approval — like read_file and grep_files. The index is built/refreshed lazily
+ * on first use; results are ranked by cosine similarity and token-budgeted.
+ *
+ * Complements `grep_files`: prefer this for conceptual "where / how does X work"
+ * questions, and grep for exact strings or symbols.
+ */
+export const searchCodebaseTool = {
+    name: "search_codebase",
+    description: "Semantically search the project's code index for the snippets most relevant to a natural-language query. Returns ranked matches as 'path:startLine-endLine (score)' with a code snippet. Read-only, no approval. Prefer this for conceptual 'where is / how does X work' questions; use grep_files for exact strings or symbol names.",
+    parameters,
+    async execute(input, ctx) {
+        if (!ctx.config.index.enabled) {
+            return {
+                ok: false,
+                error: "codebase indexing is disabled (set index.enabled = true to use search_codebase)",
+            };
+        }
+        try {
+            const service = await getIndexService(ctx.cwd, ctx.config, ctx.logger);
+            const hits = await service.search({
+                query: input.query,
+                k: input.k,
+                pathGlob: input.pathGlob,
+            });
+            if (hits.length === 0) {
+                return { ok: true, output: "(no matches in the codebase index)" };
+            }
+            return { ok: true, output: formatHits(hits) };
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
+    },
+};
+/** Render hits as a compact, model-readable block. */
+function formatHits(hits) {
+    return hits
+        .map((hit) => {
+        const header = `${hit.path}:${hit.startLine}-${hit.endLine}  (score ${hit.score.toFixed(3)})`;
+        const body = hit.snippet
+            .split("\n")
+            .map((line) => `    ${line}`)
+            .join("\n");
+        return `${header}\n${body}`;
+    })
+        .join("\n\n");
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {
     "cruxy": "./dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "engines": {
     "node": ">=20"
@@ -28,7 +29,9 @@
     "directory": "packages/cli"
   },
   "dependencies": {
+    "better-sqlite3": "^12.11.1",
     "commander": "^12.1.0",
+    "fastembed": "^2.1.0",
     "picocolors": "^1.1.1",
     "tinyglobby": "^0.2.10",
     "zod": "^3.23.8",
@@ -36,6 +39,7 @@
     "@cruxy/sdk": "0.1.0"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.10.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",

package/skills/git-commit/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: git-commit
+description: Write a conventional commit message that passes this repo's commitlint. Use when committing, writing a commit message, or opening a PR in cruxy.
+---
+
+# Writing commit messages for cruxy
+
+This repo enforces [Conventional Commits](https://www.conventionalcommits.org)
+via commitlint (a husky `commit-msg` hook) plus changesets. Follow this to get a
+message that passes on the first try.
+
+## Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+- **type** — one of `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `perf`,
+  `build`, `ci`, `style`, `revert`.
+- **scope** _(optional, but if present must be in the allow-list)_ —
+  `cli`, `sdk`, `ui`, `api`, `auth`, `billing`, `web`, `dashboard`, `docs`,
+  `ide`, `infra`, `pricing`, `repo`, `ci`. The canonical list lives in
+  `commitlint.config.cjs` (`scope-enum`).
+- **subject** — imperative mood, no trailing period.
+
+## The rule people trip on
+
+**The subject must NOT start with a capital letter.** commitlint's
+`subject-case` rejects sentence-case / start-case / pascal-case / upper-case, so
+a subject beginning with an uppercase letter fails the hook (and CI). A tag like
+`C.18` cannot be the first token.
+
+- ✅ `feat(cli): codebase indexing + search_codebase (C.18)`
+- ❌ `feat(cli): C.18 codebase indexing` — capital `C` ⇒ sentence-case ⇒ rejected.
+
+Put any phase/issue tag in a parenthetical at the end, or lowercase the lead.
+
+## Body and footer
+
+- Wrap the body at ~72 columns; explain _what_ and _why_, not _how_.
+- A breaking change uses `!` after the type/scope (`feat(cli)!: …`) and/or a
+  `BREAKING CHANGE:` footer.
+- Co-author trailers go in the footer, e.g.
+  `Co-Authored-By: Name <email>`.
+
+## Don't forget the changeset
+
+User-facing changes need a changeset: run `pnpm changeset` (or add a file under
+`.changeset/`) describing the change and the semver bump for the affected
+package (e.g. `@cruxy/cli` minor).
+
+## Quick check
+
+If a commit is rejected with `subject must not be sentence-case … [subject-case]`,
+lowercase the first word of the subject (or move the capitalized tag into a
+trailing parenthetical) and recommit.

package/skills/using-skills/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: using-skills
+description: How cruxy skills work and how to author a SKILL.md. Use when the user asks about skills or wants to create or edit one.
+---
+
+# Skills in cruxy
+
+A **skill** is a directory containing a `SKILL.md` — YAML frontmatter plus a
+markdown instructions body — that packages reusable, task-specific know-how for
+the agent. Discover skills with the `list_skills` tool and pull a skill's full
+instructions with `load_skill` when a task matches its description.
+
+## Progressive disclosure
+
+Only each skill's `name` and `description` are visible by default (a cheap
+catalog). The full body is loaded **on demand** via `load_skill`, so a large
+library of skills costs almost nothing until one is actually used. Write the
+`description` so the agent can tell, from one line, _when_ to reach for the
+skill.
+
+## Authoring a SKILL.md
+
+Create `skills/<name>/SKILL.md`:
+
+```
+---
+name: <name>
+description: <one line — what it does and when to use it>
+---
+
+# instructions
+…the body the agent reads after load_skill…
+```
+
+Rules (all enforced, fail-loud):
+
+- `name` is kebab-case (`^[a-z0-9][a-z0-9-]*$`) and **must equal the directory
+  name**.
+- `description` is required and non-empty.
+- Frontmatter is strict: unknown keys, missing fields, or malformed YAML are
+  reported in `cruxy skills --status` and the skill is excluded from the
+  catalog.
+
+## Sources and precedence
+
+Skills are discovered from three layers; on a name collision the higher layer
+wins:
+
+1. **project** — `<cwd>/.cruxy/skills/`
+2. **user** — `~/.cruxy/skills/`
+3. **builtin** — shipped with the CLI
+
+Run `cruxy skills` to see the resolved catalog, or `cruxy skills --status` to see
+the source directories and any validation errors.
+
+## Bundled assets
+
+A skill may include `scripts/` and `reference/` subdirectories. `load_skill`
+returns their paths, but **nothing is auto-executed** — the agent runs a script
+through `run_command` (which goes through the normal approval gate) and reads a
+reference through `read_file`. Skills are data, not a privileged execution path,
+and may only reference files inside their own directory.