nusus 0.3.0 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
 # Nusus
 
-TypeScript SDK for searching and citing classical Islamic and Arabic texts through [Turath](https://app.turath.io/), a Shamela-style digital library. Use Nusus to retrieve source text, metadata, citations, locators, and direct links from Arabic heritage books for research tools and AI agents.
+TypeScript SDK **and agent CLI** for searching and citing classical Islamic and Arabic texts through [Turath](https://app.turath.io/), a Shamela-style digital library. Use Nusus to retrieve source text, metadata, citations, locators, and direct links from Arabic heritage books for research tools and AI agents. The `nusus` binary ships in the same npm package as the SDK.
 
 ```bash
 npm install nusus
@@ -48,16 +48,49 @@ All requests support `AbortSignal`; failures use the exported `NususError` codes
 
 ## Agent CLI
 
-```bash
-npx nusus "إنما الأعمال بالنيات" 3
-npx nusus --book-id 147927 "النية" 3
-npx nusus --page 147927 5
+The package installs a `nusus` binary (`scripts/search.mjs`) that wraps the SDK as explicit research tools. Prefer the CLI from agents; use the SDK from application code.
 
-# Bun
-bunx nusus "إنما الأعمال بالنيات" 3
+```bash
+npm install -g nusus   # or: npx nusus …
+nusus --help
+nusus --version
+
+# Discover (offline bundled catalog)
+nusus find-books "الأربعون النووية" --limit 5
+nusus find-books --author-id 44 --limit 10
+nusus find-authors "النووي" --limit 5
+nusus list-categories
+nusus catalog
+
+# Search / retrieve (live Turath)
+nusus search "إنما الأعمال بالنيات" --book-id 147927
+nusus retrieve "النية" --max-passages 3 --max-chars 2000
+
+# Page / metadata (live)
+nusus get-page --book-id 147927 --page-id 5
+nusus get-context --book-id 147927 --page-id 5 --pages-before 1 --pages-after 1
+nusus get-book 147927
+nusus get-author 44
 ```
 
-The CLI emits JSON Lines with passage text, source metadata, citations, and direct Turath URLs. It also supports `--madhhab hanafi|maliki|shafii|hanbali` and `--books "title one,title two"`.
+Default stdout is **JSONL** (one object per line, camelCase, every line has `type`). Use `--format text` for compact human lines. Diagnostics are JSON on **stderr** only. Unknown or command-inapplicable flags are rejected.
+
+| Record `type` | Commands |
+| --- | --- |
+| `meta` | First line of `find-books`, `find-authors`, `search`, `retrieve` |
+| `book` / `author` / `category` / `catalog` | Discovery + `get-book` / `get-author` |
+| `passage` | `search`, `retrieve`, `get-page`, `get-context` |
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | Success (including zero hits; find/search/retrieve emit a `meta` line; offline finders report `returned`, live search/retrieve report `totalMatches`) |
+| 1 | Usage / invalid argument |
+| 2 | Not found |
+| 3 | Rate limit / HTTP / invalid response / timeout (`ABORTED`) / internal |
+
+`page-id` is Turath’s internal page (`location.internalPage`), not the printed page. `search`/`retrieve` accept at most one `--book-id`, one `--author-id`, and one `--category-id` (filters may be combined). Offline `find-books` accepts repeated `--author-id`/`--category-id` and may omit the title query when those filters are set. `--timeout 0` disables the request timeout (max `600000`). There is no madhhab ranking or multi-book fanout in the CLI.
+
+Repo layout and module boundaries: [`docs/CODEBASE_MAP.md`](docs/CODEBASE_MAP.md). Agent skill copy: [`docs/turath-research-SKILL.md`](docs/turath-research-SKILL.md).
 
 ## Known limitations
 
@@ -71,9 +104,9 @@ Browser support is not claimed because the checked API responses do not advertis
 
 ```bash
 bun install
+bun run build   # CLI bin loads dist/; also auto-built by CLI tests if missing
 bun test
 bun run typecheck
-bun run build
 
 # optional live contract (also scheduled via GitHub Actions)
 bun run test:live

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { NususError } from "./errors.js";
 export type { NususErrorCode } from "./errors.js";
-export type { Author, AuthorSummary, Book, BookSummary, CatalogMetadata, Category, CategorySummary, Passage, PassageProvenance, RetrievedContext, RetrieveScope, SearchPage, SourceLocation, SourceLocator, TurathId, } from "./models.js";
+export type { Author, AuthorSummary, Book, BookSummary, BookTocEntry, CatalogMetadata, Category, CategorySummary, Passage, PassageProvenance, RetrievedContext, RetrieveScope, SearchPage, SourceLocation, SourceLocator, TurathId, } from "./models.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,YAAY,EACV,MAAM,EACN,aAAa,EACb,IAAI,EACJ,WAAW,EACX,eAAe,EACf,QAAQ,EACR,eAAe,EACf,OAAO,EACP,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,cAAc,EACd,aAAa,EACb,QAAQ,GACT,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,YAAY,EACV,MAAM,EACN,aAAa,EACb,IAAI,EACJ,WAAW,EACX,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,eAAe,EACf,OAAO,EACP,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,cAAc,EACd,aAAa,EACb,QAAQ,GACT,MAAM,aAAa,CAAC"}

package/dist/models.d.ts

@@ -16,6 +16,11 @@ export type BookSummary = {
     id: string;
     title: string;
 };
+export type BookTocEntry = {
+    title: string;
+    level?: number;
+    page?: number;
+};
 export type Author = AuthorSummary & {
     provider: "turath";
     id: string;
@@ -29,6 +34,10 @@ export type Book = BookSummary & {
     category?: CategorySummary;
     description?: string;
     hasPdf?: boolean;
+    /** Normalized TOC from Turath book indexes when present. */
+    toc?: BookTocEntry[];
+    /** Volume labels from Turath book indexes when present. */
+    volumes?: string[];
     raw?: unknown;
 };
 export type SourceLocation = {

package/dist/models.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,eAAe,GAAG;IACvC,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG,aAAa,GAAG;IACnC,QAAQ,EAAE,QAAQ,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,IAAI,GAAG,WAAW,GAAG;IAC/B,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,GAAG,CAAC,EAAE,YAAY,EAAE,CAAC;IACrB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,QAAQ,GAAG,cAAc,CAAC;IACvC,YAAY,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,YAAY,EAAE,MAAM,GAAG,YAAY,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,QAAQ,EAAE,cAAc,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,eAAe,EAAE,MAAM,CAAC;IACxB,2GAA2G;IAC3G,uBAAuB,EAAE,MAAM,CAAC;CACjC,CAAC"}

package/dist/turath/catalog.d.ts

@@ -1,5 +1,6 @@
 import type { Author, Book, CatalogMetadata, Category, TurathId } from "../models.js";
 export type FindBooksOptions = {
+    authorIds?: TurathId[];
     categoryIds?: TurathId[];
     limit?: number;
 };
@@ -7,7 +8,7 @@ export type FindAuthorsOptions = {
     limit?: number;
 };
 export declare const getCatalogMetadata: () => CatalogMetadata;
-export declare const findCatalogBooks: (query: string, options?: FindBooksOptions) => Book[];
+export declare const findCatalogBooks: (query?: string, options?: FindBooksOptions) => Book[];
 export declare const findCatalogAuthors: (query: string, options?: FindAuthorsOptions) => Author[];
 export declare const listCatalogCategories: () => Category[];
 export declare const listCatalogAuthorIds: () => string[];

package/dist/turath/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/turath/catalog.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAItF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAyCF,eAAO,MAAM,kBAAkB,QAAO,eAarC,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,EAAE,UAAS,gBAAqB,KAAG,IAAI,EA6BpF,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,EAAE,UAAS,kBAAuB,KAAG,MAAM,EAqB1F,CAAC;AAEF,eAAO,MAAM,qBAAqB,QAAO,QAAQ,EAShD,CAAC;AAEF,eAAO,MAAM,oBAAoB,QAAO,MAAM,EACU,CAAC"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/turath/catalog.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAItF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAyCF,eAAO,MAAM,kBAAkB,QAAO,eAarC,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,cAAU,EAAE,UAAS,gBAAqB,KAAG,IAAI,EAkCjF,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,EAAE,UAAS,kBAAuB,KAAG,MAAM,EAqB1F,CAAC;AAEF,eAAO,MAAM,qBAAqB,QAAO,QAAQ,EAShD,CAAC;AAEF,eAAO,MAAM,oBAAoB,QAAO,MAAM,EACU,CAAC"}

package/dist/turath/catalog.js

@@ -54,22 +54,27 @@ export const getCatalogMetadata = () => {
         unresolvedAuthorIdCount: uniqueAuthorIds.size - authorNameCount,
     };
 };
-export const findCatalogBooks = (query, options = {}) => {
+export const findCatalogBooks = (query = "", options = {}) => {
     const needle = normalize(query);
-    if (!needle)
-        throw new NususError("INVALID_ARGUMENT", "query must not be empty");
-    const limit = positiveLimit(options.limit, 20);
+    const authors = options.authorIds?.map((value) => positiveId(value, "author id"));
     const categories = options.categoryIds?.map((value) => positiveId(value, "category id"));
+    const authorSet = authors?.length ? new Set(authors) : undefined;
     const categorySet = categories?.length ? new Set(categories) : undefined;
-    const words = needle.split(/\s+/);
+    if (!needle && !authorSet && !categorySet) {
+        throw new NususError("INVALID_ARGUMENT", "query must not be empty unless authorIds or categoryIds are set");
+    }
+    const limit = positiveLimit(options.limit, 20);
+    const words = needle ? needle.split(/\s+/) : [];
     return CATALOG_BOOKS
         .flatMap(([bookId, title, authorId, categoryId]) => {
+        const authorKey = String(authorId);
+        if (authorSet && !authorSet.has(authorKey))
+            return [];
         if (categorySet && !categorySet.has(String(categoryId)))
             return [];
-        const score = scoreMatch(normalize(title), needle, words);
+        const score = needle ? scoreMatch(normalize(title), needle, words) : 0;
         if (score < 0)
             return [];
-        const authorKey = String(authorId);
         const authorName = authorNames.get(authorKey);
         return [{
                 score,

package/dist/turath/catalog.js.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/turath/catalog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/turath/catalog.ts"],"names":[],"mappings":"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"}

package/dist/turath/client.d.ts

@@ -24,7 +24,7 @@ export type RetrieveOptions = RequestOptions & {
 };
 export type TurathClientOptions = TransportOptions;
 export declare const createTurathClient: (options?: TurathClientOptions) => {
-    findBooks: (query: string, options?: import("./catalog.js").FindBooksOptions) => Book[];
+    findBooks: (query?: string, options?: import("./catalog.js").FindBooksOptions) => Book[];
     findAuthors: (query: string, options?: import("./catalog.js").FindAuthorsOptions) => import("../models.js").Author[];
     listCategories: () => import("../models.js").Category[];
     getCatalogMetadata: () => import("../models.js").CatalogMetadata;

package/dist/turath/normalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/turath/normalize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAwB1D,eAAO,MAAM,eAAe,GAAI,KAAK,OAAO,KAAG,MAa9C,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,KAAK,OAAO,KAAG,IAe5C,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,KAAK,OAAO,EAAE,QAAQ,MAAM,KAAG,OAoB5D,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,KAAK,OAAO,KAAG,OAsBjD,CAAC"}
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/turath/normalize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAgB,OAAO,EAAE,MAAM,cAAc,CAAC;AA6CxE,eAAO,MAAM,eAAe,GAAI,KAAK,OAAO,KAAG,MAa9C,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,KAAK,OAAO,KAAG,IAiB5C,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,KAAK,OAAO,EAAE,QAAQ,MAAM,KAAG,OAoB5D,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,KAAK,OAAO,KAAG,OAsBjD,CAAC"}

package/dist/turath/normalize.js

@@ -1,6 +1,31 @@
 import { NususError } from "../errors.js";
 import { decoratePassage } from "./citations.js";
 const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const extractIndexes = (raw) => {
+    const indexes = raw.indexes;
+    if (!record(indexes))
+        return {};
+    const out = {};
+    if (Array.isArray(indexes.headings)) {
+        const toc = [];
+        for (const item of indexes.headings) {
+            if (!record(item) || typeof item.title !== "string")
+                continue;
+            const entry = { title: item.title };
+            if (typeof item.level === "number")
+                entry.level = item.level;
+            if (typeof item.page === "number")
+                entry.page = item.page;
+            toc.push(entry);
+        }
+        if (toc.length)
+            out.toc = toc;
+    }
+    if (Array.isArray(indexes.volumes) && indexes.volumes.every((value) => typeof value === "string")) {
+        out.volumes = indexes.volumes;
+    }
+    return out;
+};
 const invalid = (message, cause) => {
     throw new NususError("INVALID_RESPONSE", message, { cause });
 };
@@ -39,6 +64,7 @@ export const normalizeBook = (raw) => {
         return invalid("Turath returned an invalid book");
     }
     const book = raw;
+    const indexes = extractIndexes(raw);
     return {
         provider: "turath",
         id: String(book.meta.id),
@@ -47,6 +73,7 @@ export const normalizeBook = (raw) => {
         ...(typeof book.meta.cat_id === "number" && { category: { id: String(book.meta.cat_id) } }),
         ...(typeof book.meta.info === "string" && { description: book.meta.info }),
         ...(Boolean(book.meta.pdf_links) && { hasPdf: true }),
+        ...indexes,
         raw,
     };
 };

package/dist/turath/normalize.js.map

@@ -1 +1 @@
-{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/turath/normalize.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/turath/normalize.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nusus",
-  "version": "0.3.0",
-  "description": "TypeScript SDK for searching and citing classical Islamic and Arabic texts via Turath, a Shamela-style digital library",
+  "version": "0.4.1",
+  "description": "TypeScript SDK and agent CLI for searching and citing classical Islamic and Arabic texts via Turath",
   "keywords": [
     "turath",
     "shamela",
@@ -11,7 +11,9 @@
     "hadith",
     "fiqh",
     "typescript",
-    "sdk"
+    "sdk",
+    "cli",
+    "jsonl"
   ],
   "repository": {
     "type": "git",

package/scripts/search.mjs

@@ -1,155 +1,642 @@
 #!/usr/bin/env node
-// Agent-facing Turath search CLI built on nusus.
-// Drop-in replacement for the old turath-sdk search.mjs.
-//
-// Usage:
-//   node search.mjs "<Arabic query>" [max_results]
-//   node search.mjs --madhhab hanafi|maliki|shafii|hanbali "<topic>" [max_results]
-//   node search.mjs --books "بدائع الصنائع,الهداية" "<query>" [max_results]
-//   node search.mjs --book-id 147927 "<query>" [max_results]
-//   node search.mjs --page <book_id> <page_id>          # fetch one page + context
-//
-// Output: JSON per line — book_id, title, author, volume, page_id, printed_page,
-// headings, citation, url, text (bounded), prev/next context.
+// Agent-facing Turath CLI — thin subcommand surface over the nusus SDK.
+// Default stdout: JSONL. Diagnostics: stderr JSON. No ranking heuristics.
 
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { createTurathClient } from "../dist/turath/index.js";
+import { NususError } from "../dist/errors.js";
 
-const MADHHAB_BOOKS = {
-  hanafi: ["رد المحتار ابن عابدين", "الهداية المرغيناني", "فتح القدير ابن الهمام", "بدائع الصنائع الكاساني", "المبسوط السرخسي"],
-  maliki: ["مختصر خليل", "المدونة الكبرى سحنون", "التوضيح شرح مختصر ابن الحاجب خليل", "الشرح الكبير الدردير حاشية الدسوقي", "مواهب الجليل الحطاب"],
-  shafii: ["منهاج الطالبين النووي", "تحفة المحتاج ابن حجر الهيتمي", "نهاية المحتاج الرملي", "مغني المحتاج الشربيني", "المجموع شرح المهذب النووي"],
-  hanbali: ["منتهى الإرادات ابن النجار", "الإقناع الحجاوي", "كشاف القناع البهوتي", "شرح منتهى الإرادات البهوتي", "المغني ابن قدامة"],
-};
-
-const MADHHAB_LABELS = {
-  hanafi: { name: "الحنفية", at: "عند الحنفية", fi: "في مذهب الحنفية" },
-  maliki: { name: "المالكية", at: "عند المالكية", fi: "في المذهب المالكي" },
-  shafii: { name: "الشافعية", at: "عند الشافعية", fi: "في مذهب الشافعية" },
-  hanbali: { name: "الحنابلة", at: "عند الحنابلة", fi: "في المذهب الحنبلي" },
-};
-
-// === arg parsing ===
-const args = process.argv.slice(2);
-let madhhab = null;
-let books = null;
-let bookId = null;
-let pageMode = false;
-let query = null;
-let maxResults = 5;
-
-for (let i = 0; i < args.length; i++) {
-  const a = args[i];
-  if (a === "--madhhab") {
-    madhhab = args[++i]?.toLowerCase();
-    if (!MADHHAB_BOOKS[madhhab]) fail(`Invalid madhhab. Use: ${Object.keys(MADHHAB_BOOKS).join(", ")}`);
-  } else if (a === "--books") books = args[++i]?.split(",").map((s) => s.trim()).filter(Boolean);
-  else if (a === "--book-id") bookId = args[++i];
-  else if (a === "--page") pageMode = true;
-  else if (a === "--topic") query = args[++i];
-  else if (!a.startsWith("--") && query === null && isNaN(Number(a))) query = a;
-}
-// last numeric non-flag arg = max results (or page args in --page mode)
-const numbers = args.filter((a) => !a.startsWith("--") && /^\d+$/.test(a));
-if (numbers.length && !pageMode) maxResults = parseInt(numbers[numbers.length - 1], 10);
-
-function fail(message) {
-  console.error(message);
-  process.exit(1);
-}
-
-const turath = createTurathClient({ timeout: 15_000 });
-
-const emit = (item) => console.log(JSON.stringify(item));
-
-const passageToJson = (p, extra = {}) => ({
-  book_id: Number(p.book.id),
-  title: p.book.title,
-  author: p.author?.name,
-  volume: p.location.volume,
-  page_id: p.location.internalPage,
-  printed_page: p.location.printedPage,
-  headings: p.headings.join(" > "),
-  citation: p.citation,
-  url: p.url,
-  ...extra,
+const DEFAULT_TIMEOUT = 15_000;
+const MAX_TIMEOUT = 600_000;
+const MAX_FILTER_IDS = 50;
+const VERSION = createRequire(import.meta.url)(join(dirname(fileURLToPath(import.meta.url)), "../package.json")).version;
+
+const EXIT = {
+  USAGE: 1,
+  INVALID_ARGUMENT: 1,
+  NOT_FOUND: 2,
+  RATE_LIMITED: 3,
+  HTTP_ERROR: 3,
+  INVALID_RESPONSE: 3,
+  ABORTED: 3,
+  INTERNAL_ERROR: 3,
+};
+
+// --- I/O ---
+
+process.stdout.on("error", (error) => {
+  if (error?.code === "EPIPE") process.exit(0);
+  throw error;
 });
 
-// === page mode: node search.mjs --page <book_id> <page_id> ===
-if (pageMode) {
-  const [pBook, pPage] = numbers;
-  if (!pBook || !pPage) fail("Usage: node search.mjs --page <book_id> <page_id>");
-  const page = await turath.getPage(pBook, pPage);
-  const context = await turath.getContext(page, { pagesBefore: 1, pagesAfter: 1 });
-  emit(passageToJson(page, { text: page.text, context_text: context.text }));
-  process.exit(0);
-}
-
-if (!query) fail('Usage: node search.mjs [--madhhab hanafi|maliki|shafii|hanbali] [--books "t1,t2"] [--book-id N] "<query>" [max_results]');
-
-// === build tiered queries ===
-const searchQueries = [];
-if (madhhab) {
-  const label = MADHHAB_LABELS[madhhab];
-  searchQueries.push({ q: `${query} ${label.at}`, tier: 1, source_type: `madhhab:${madhhab}` });
-  searchQueries.push({ q: `${query} ${label.fi}`, tier: 1, source_type: `madhhab:${madhhab}` });
-  searchQueries.push({ q: `${query} ${label.name}`, tier: 2, source_type: `madhhab:${madhhab}` });
-  for (const book of MADHHAB_BOOKS[madhhab]) {
-    searchQueries.push({ q: `${query} ${book}`, tier: 3, source_type: `book:${madhhab}` });
+const writeJsonl = (record) => {
+  process.stdout.write(`${JSON.stringify(record)}\n`);
+};
+
+const fail = (code, error) => {
+  const payload = {
+    ok: false,
+    error: {
+      code,
+      message: error?.message ?? String(error),
+      ...(error?.status !== undefined && { status: error.status }),
+      ...(error?.url !== undefined && { url: error.url }),
+      ...(error?.retryAfter !== undefined && { retryAfter: error.retryAfter }),
+    },
+  };
+  process.stderr.write(`${JSON.stringify(payload)}\n`);
+  process.exit(EXIT[code] ?? 3);
+};
+
+const usage = (message) => fail("USAGE", { message });
+
+// --- text format ---
+
+const preview = (text, n = 160) => {
+  const one = String(text ?? "").replace(/\s+/g, " ").trim();
+  return one.length <= n ? one : `${one.slice(0, n)}…`;
+};
+
+const writeText = (record) => {
+  switch (record.type) {
+    case "meta": {
+      const parts = [`meta\t${record.command}`];
+      if (record.query !== undefined) parts.push(`q=${record.query}`);
+      if (record.returned !== undefined) parts.push(`returned=${record.returned}`);
+      if (record.totalMatches !== undefined) parts.push(`totalMatches=${record.totalMatches}`);
+      if (record.page !== undefined) parts.push(`page=${record.page}`);
+      process.stdout.write(`${parts.join("\t")}\n`);
+      break;
+    }
+    case "book":
+      process.stdout.write(
+        `book\t${record.id}\t${record.title}` +
+          (record.author?.name ? `\t${record.author.name}` : record.author?.id ? `\tauthor=${record.author.id}` : "") +
+          (record.toc ? `\ttoc=${record.toc.length}` : "") +
+          "\n",
+      );
+      break;
+    case "author":
+      process.stdout.write(`author\t${record.id}\t${record.name}\n`);
+      break;
+    case "category":
+      process.stdout.write(`category\t${record.id}\t${record.title}\tbooks=${record.bookCount}\n`);
+      break;
+    case "catalog":
+      process.stdout.write(
+        `catalog\tbooks=${record.bookCount}\tcategories=${record.categoryCount}\tauthors=${record.authorIdCount}\n`,
+      );
+      break;
+    case "passage":
+      process.stdout.write(
+        `passage\t${record.book?.id ?? "?"}\t${record.citation ?? ""}\t${record.url ?? ""}\t${preview(record.text)}\n`,
+      );
+      break;
+    default:
+      process.stdout.write(`${record.type}\t${JSON.stringify(record)}\n`);
   }
-} else if (books) {
-  for (const title of books) {
-    const match = turath.findBooks(title, { limit: 1 })[0];
-    if (match) searchQueries.push({ q: query, tier: 3, source_type: "targeted", bookId: match.id, matched_term: title });
+};
+
+const emit = (format, record) => {
+  if (format === "text") writeText(record);
+  else writeJsonl(record);
+};
+
+// --- records ---
+
+const toPassageRecord = (passage) => {
+  const record = {
+    type: "passage",
+    book: passage.book,
+    location: passage.location,
+    text: passage.text,
+    headings: passage.headings ?? [],
+    url: passage.url,
+    citation: passage.citation,
+  };
+  if (passage.author) record.author = passage.author;
+  if (passage.category) record.category = passage.category;
+  if (passage.snippet !== undefined) record.snippet = passage.snippet;
+  if (passage.locator) record.locator = passage.locator;
+  if (passage.provenance) record.provenance = passage.provenance;
+  return record;
+};
+
+const toBookRecord = (book) => {
+  const record = {
+    type: "book",
+    id: book.id,
+    title: book.title,
+    provider: book.provider ?? "turath",
+  };
+  if (book.author) record.author = book.author;
+  if (book.category) record.category = book.category;
+  if (book.description !== undefined) record.description = book.description;
+  if (book.hasPdf !== undefined) record.hasPdf = book.hasPdf;
+  if (book.toc) record.toc = book.toc;
+  if (book.volumes) record.volumes = book.volumes;
+  return record;
+};
+
+const toAuthorRecord = (author) => {
+  const record = {
+    type: "author",
+    id: author.id,
+    name: author.name,
+    provider: author.provider ?? "turath",
+  };
+  if (author.biography !== undefined) record.biography = author.biography;
+  if (author.deathYear !== undefined) record.deathYear = author.deathYear;
+  return record;
+};
+
+const toCategoryRecord = (category) => ({
+  type: "category",
+  id: category.id,
+  title: category.title,
+  provider: category.provider ?? "turath",
+  bookCount: category.bookCount,
+});
+
+const toCatalogRecord = (meta) => ({ type: "catalog", ...meta });
+
+// --- parse helpers ---
+
+const parseIntFlag = (raw, name, { def, min, max } = {}) => {
+  if (raw === undefined) return def;
+  if (raw === true) usage(`--${name} requires a value`);
+  if (!/^\d+$/.test(String(raw))) usage(`--${name} must be an integer`);
+  const n = Number(raw);
+  if (min !== undefined && n < min) usage(`--${name} must be >= ${min}`);
+  if (max !== undefined && n > max) usage(`--${name} must be <= ${max}`);
+  return n;
+};
+
+const parsePositiveId = (raw, label) => {
+  const value = String(raw);
+  if (!/^[1-9]\d*$/.test(value)) usage(`${label} must be a positive integer`);
+  return value;
+};
+
+const requireFlag = (flags, name) => {
+  const value = flags[name];
+  if (value === undefined || value === true) usage(`--${name} is required`);
+  return value;
+};
+
+const optionalFlag = (flags, name) => {
+  const value = flags[name];
+  if (value === undefined) return undefined;
+  if (value === true) usage(`--${name} requires a value`);
+  return value;
+};
+
+const parseIdList = (values, label, { max = 1 } = {}) => {
+  const list = values ?? [];
+  if (list.length > max) {
+    usage(max === 1 ? `at most one --${label}` : `at most ${max} --${label} values`);
   }
-}
-searchQueries.push({ q: query, tier: 4, source_type: "broad" });
-
-// === execute ===
-const seen = new Set();
-const collected = [];
-for (const sq of searchQueries) {
-  if (collected.length >= maxResults * 3) break;
-  try {
-    const selectedBookId = sq.bookId ?? bookId;
-    const result = await turath.search(sq.q, selectedBookId ? { bookIds: [selectedBookId] } : {});
-    for (const hit of result.items) {
-      const key = `${hit.book.id}:${hit.location.internalPage ?? ""}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-      collected.push({ hit, tier: sq.tier, source_type: sq.source_type, matched_term: sq.matched_term ?? sq.q.replace(query, "").trim() });
+  return list.map((value) => parsePositiveId(value, label));
+};
+
+const takeQuery = (positionals, { required = true } = {}) => {
+  if (positionals.length > 1) usage("accepts a single <query> argument");
+  if (!positionals.length) {
+    if (required) usage("requires a <query>");
+    return "";
+  }
+  const query = positionals[0];
+  if (!String(query).trim()) {
+    if (required) usage("query must not be empty");
+    return "";
+  }
+  return query;
+};
+
+const takeIdArg = (positionals, label) => {
+  if (positionals.length === 0) usage(`${label} requires an id argument`);
+  if (positionals.length > 1) usage(`${label} accepts a single id argument`);
+  return parsePositiveId(positionals[0], `${label} id`);
+};
+
+const rejectExtras = (positionals, flags, multi) => {
+  if (positionals.length) usage("this command accepts no positional arguments");
+  if (Object.keys(flags).length) usage(`unknown option --${Object.keys(flags)[0]}`);
+  if (Object.keys(multi).length) usage(`unknown option --${Object.keys(multi)[0]}`);
+};
+
+const parseArgs = (argv) => {
+  const positionals = [];
+  const flags = Object.create(null);
+  const multi = Object.create(null);
+  const multiKeys = new Set(["author-id", "category-id"]);
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--") {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg === "-h" || arg === "--help") {
+      flags.help = true;
+      continue;
     }
-  } catch {
-    // skip failed tier queries; broad fallback still runs
+    if (arg === "-v" || arg === "--version") {
+      flags.version = true;
+      continue;
+    }
+    if (arg.startsWith("-") && !arg.startsWith("--")) {
+      usage(`unknown option ${arg}`);
+    }
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    const eq = arg.indexOf("=");
+    let key;
+    let value;
+    if (eq !== -1) {
+      key = arg.slice(2, eq);
+      value = arg.slice(eq + 1);
+    } else {
+      key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("-")) {
+        value = next;
+        i += 1;
+      } else {
+        value = true;
+      }
+    }
+    if (!key) usage("invalid option");
+    if (multiKeys.has(key)) {
+      if (value === true) usage(`--${key} requires a value`);
+      (multi[key] ??= []).push(value);
+      continue;
+    }
+    if (flags[key] !== undefined) usage(`duplicate flag --${key}`);
+    flags[key] = value;
   }
-}
-
-collected.sort((a, b) => a.tier - b.tier);
-const top = collected.slice(0, maxResults);
-
-for (const { hit, tier, source_type, matched_term } of top) {
-  let text = hit.text;
-  let prevTail = "";
-  let nextHead = "";
-  if (hit.location.internalPage !== undefined) {
-    try {
-      const page = await turath.getPage(hit.book.id, hit.location.internalPage);
-      text = page.text;
-      const pg = hit.location.internalPage;
-      if (pg > 1) {
-        try { prevTail = (await turath.getPage(hit.book.id, pg - 1)).text.slice(-300); } catch {}
+
+  return { positionals, flags, multi };
+};
+
+const takeAllowed = (flags, multi, allowed) => {
+  const allowedSet = new Set(allowed);
+  const outFlags = Object.create(null);
+  const outMulti = Object.create(null);
+  for (const [key, value] of Object.entries(flags)) {
+    if (!allowedSet.has(key)) usage(`unknown option --${key}`);
+    outFlags[key] = value;
+  }
+  for (const [key, value] of Object.entries(multi)) {
+    if (!allowedSet.has(key)) usage(`unknown option --${key}`);
+    outMulti[key] = value;
+  }
+  return { flags: outFlags, multi: outMulti };
+};
+
+const parseLiveScope = (flags, multi) => {
+  const bookId = optionalFlag(flags, "book-id");
+  const authorIds = parseIdList(multi["author-id"], "author-id", { max: 1 });
+  const categoryIds = parseIdList(multi["category-id"], "category-id", { max: 1 });
+  const scope = {};
+  if (bookId !== undefined) scope.bookIds = [parsePositiveId(bookId, "book-id")];
+  if (authorIds.length) scope.authorIds = authorIds;
+  if (categoryIds.length) scope.categoryIds = categoryIds;
+  return scope;
+};
+
+// --- command table ---
+
+const GLOBAL_FLAGS = ["format", "timeout"];
+
+const COMMANDS = {
+  "find-books": {
+    help: `nusus find-books [query] [--limit N] [--author-id <id>]... [--category-id <id>]...
+  Offline catalog book search.
+  Query optional only when --author-id and/or --category-id is set.
+  --limit          default 20, max 100
+  --author-id      repeatable offline author filter (max ${MAX_FILTER_IDS})
+  --category-id    repeatable offline category filter (max ${MAX_FILTER_IDS})`,
+    flags: [...GLOBAL_FLAGS, "limit", "author-id", "category-id"],
+    run: async ({ turath, format, positionals, flags, multi }) => {
+      const query = takeQuery(positionals, { required: false });
+      const limit = parseIntFlag(flags.limit, "limit", { def: 20, min: 1, max: 100 });
+      const authorIds = parseIdList(multi["author-id"], "author-id", { max: MAX_FILTER_IDS });
+      const categoryIds = parseIdList(multi["category-id"], "category-id", { max: MAX_FILTER_IDS });
+      if (!query.trim() && !authorIds.length && !categoryIds.length) {
+        usage("find-books requires a <query> or --author-id/--category-id");
       }
-      try { nextHead = (await turath.getPage(hit.book.id, pg + 1)).text.slice(0, 300); } catch {}
-    } catch {}
+      const books = turath.findBooks(query, {
+        limit,
+        ...(authorIds.length && { authorIds }),
+        ...(categoryIds.length && { categoryIds }),
+      });
+      emit(format, {
+        type: "meta",
+        command: "find-books",
+        query,
+        ...(authorIds.length && { authorIds }),
+        ...(categoryIds.length && { categoryIds }),
+        limit,
+        returned: books.length,
+      });
+      for (const book of books) emit(format, toBookRecord(book));
+    },
+  },
+  "find-authors": {
+    help: `nusus find-authors <query> [--limit N]
+  Offline catalog author search.
+  --limit          default 20, max 100`,
+    flags: [...GLOBAL_FLAGS, "limit"],
+    run: async ({ turath, format, positionals, flags }) => {
+      const query = takeQuery(positionals);
+      const limit = parseIntFlag(flags.limit, "limit", { def: 20, min: 1, max: 100 });
+      const authors = turath.findAuthors(query, { limit });
+      emit(format, {
+        type: "meta",
+        command: "find-authors",
+        query,
+        limit,
+        returned: authors.length,
+      });
+      for (const author of authors) emit(format, toAuthorRecord(author));
+    },
+  },
+  "list-categories": {
+    help: `nusus list-categories
+  Offline category list.`,
+    flags: [...GLOBAL_FLAGS],
+    run: async ({ turath, format, positionals, flags, multi }) => {
+      rejectExtras(positionals, flags, multi);
+      for (const category of turath.listCategories()) emit(format, toCategoryRecord(category));
+    },
+  },
+  catalog: {
+    help: `nusus catalog
+  Offline catalog metadata.`,
+    flags: [...GLOBAL_FLAGS],
+    run: async ({ turath, format, positionals, flags, multi }) => {
+      rejectExtras(positionals, flags, multi);
+      emit(format, toCatalogRecord(turath.getCatalogMetadata()));
+    },
+  },
+  search: {
+    help: `nusus search <query> [--book-id ID] [--author-id ID] [--category-id ID]
+                 [--page N] [--sort relevance|page]
+  Live Turath search (JSONL meta + passages).
+  --page           default 1
+  --sort           relevance (default) | page
+  At most one ID per filter; filters may be combined.`,
+    flags: [...GLOBAL_FLAGS, "book-id", "author-id", "category-id", "page", "sort"],
+    run: async ({ turath, format, positionals, flags, multi }) => {
+      const query = takeQuery(positionals);
+      const scope = parseLiveScope(flags, multi);
+      const page = parseIntFlag(flags.page, "page", { def: 1, min: 1 });
+      const sortRaw = optionalFlag(flags, "sort") ?? "relevance";
+      if (sortRaw !== "relevance" && sortRaw !== "page") usage("--sort must be relevance or page");
+      const result = await turath.search(query, {
+        ...scope,
+        page,
+        ...(sortRaw === "page" && { sort: "page" }),
+      });
+      emit(format, {
+        type: "meta",
+        command: "search",
+        query,
+        totalMatches: result.totalMatches,
+        page: result.page,
+        sort: sortRaw,
+        ...(scope.bookIds && { bookIds: scope.bookIds }),
+        ...(scope.authorIds && { authorIds: scope.authorIds }),
+        ...(scope.categoryIds && { categoryIds: scope.categoryIds }),
+      });
+      for (const item of result.items) emit(format, toPassageRecord(item));
+    },
+  },
+  retrieve: {
+    help: `nusus retrieve <query> [--book-id ID] [--author-id ID] [--category-id ID]
+                   [--max-passages N] [--max-chars N]
+                   [--pages-before N] [--pages-after N]
+  Live retrieve with citations/locators.
+  --max-passages   default 5, max 20
+  --max-chars      default 2000, max 20000
+  --pages-before   default 0, max 2
+  --pages-after    default 0, max 2
+  At most one ID per filter; filters may be combined.`,
+    flags: [
+      ...GLOBAL_FLAGS,
+      "book-id",
+      "author-id",
+      "category-id",
+      "max-passages",
+      "max-chars",
+      "pages-before",
+      "pages-after",
+    ],
+    run: async ({ turath, format, positionals, flags, multi }) => {
+      const query = takeQuery(positionals);
+      const scope = parseLiveScope(flags, multi);
+      const maxPassages = parseIntFlag(flags["max-passages"], "max-passages", { def: 5, min: 1, max: 20 });
+      const maxChars = parseIntFlag(flags["max-chars"], "max-chars", { def: 2000, min: 1, max: 20_000 });
+      const pagesBefore = parseIntFlag(flags["pages-before"], "pages-before", { def: 0, min: 0, max: 2 });
+      const pagesAfter = parseIntFlag(flags["pages-after"], "pages-after", { def: 0, min: 0, max: 2 });
+      const result = await turath.retrieve(query, {
+        maxPassages,
+        maxCharsPerPassage: maxChars,
+        pagesBefore,
+        pagesAfter,
+        ...(Object.keys(scope).length && { scope }),
+      });
+      emit(format, {
+        type: "meta",
+        command: "retrieve",
+        query,
+        totalMatches: result.totalMatches,
+        maxPassages,
+        maxChars,
+        pagesBefore,
+        pagesAfter,
+        ...(scope.bookIds && { bookIds: scope.bookIds }),
+        ...(scope.authorIds && { authorIds: scope.authorIds }),
+        ...(scope.categoryIds && { categoryIds: scope.categoryIds }),
+      });
+      for (const passage of result.passages) emit(format, toPassageRecord(passage));
+    },
+  },
+  "get-page": {
+    help: `nusus get-page --book-id <id> --page-id <id>
+  Fetch one internal page.
+  page-id is Turath internal page, not printed page.`,
+    flags: [...GLOBAL_FLAGS, "book-id", "page-id"],
+    run: async ({ turath, format, positionals, flags }) => {
+      if (positionals.length) usage("get-page takes --book-id and --page-id flags only");
+      const bookId = parsePositiveId(requireFlag(flags, "book-id"), "book-id");
+      const pageId = parsePositiveId(requireFlag(flags, "page-id"), "page-id");
+      const page = await turath.getPage(bookId, pageId);
+      emit(format, toPassageRecord(page));
+    },
+  },
+  "get-context": {
+    help: `nusus get-context --book-id <id> --page-id <id>
+                  [--pages-before N] [--pages-after N]
+  Fetch page plus surrounding pages.
+  --pages-before   default 1, max 3
+  --pages-after    default 1, max 3
+  page-id is Turath internal page, not printed page.`,
+    flags: [...GLOBAL_FLAGS, "book-id", "page-id", "pages-before", "pages-after"],
+    run: async ({ turath, format, positionals, flags }) => {
+      if (positionals.length) usage("get-context takes --book-id and --page-id flags only");
+      const bookId = parsePositiveId(requireFlag(flags, "book-id"), "book-id");
+      const pageId = parsePositiveId(requireFlag(flags, "page-id"), "page-id");
+      const pagesBefore = parseIntFlag(flags["pages-before"], "pages-before", { def: 1, min: 0, max: 3 });
+      const pagesAfter = parseIntFlag(flags["pages-after"], "pages-after", { def: 1, min: 0, max: 3 });
+      const center = await turath.getPage(bookId, pageId);
+      const ctx = await turath.getContext(center, { pagesBefore, pagesAfter });
+      emit(format, toPassageRecord(ctx));
+    },
+  },
+  "get-book": {
+    help: `nusus get-book <book-id>
+  Book metadata + TOC (normalized from indexes).`,
+    flags: [...GLOBAL_FLAGS],
+    run: async ({ turath, format, positionals }) => {
+      const bookId = takeIdArg(positionals, "get-book");
+      const book = await turath.getBook(bookId);
+      emit(format, toBookRecord(book));
+    },
+  },
+  "get-author": {
+    help: `nusus get-author <author-id>
+  Author metadata.`,
+    flags: [...GLOBAL_FLAGS],
+    run: async ({ turath, format, positionals }) => {
+      const authorId = takeIdArg(positionals, "get-author");
+      const author = await turath.getAuthor(authorId);
+      emit(format, toAuthorRecord(author));
+    },
+  },
+};
+
+const GLOBAL_HELP = `nusus <command> [args] [options]
+
+Commands:
+  find-books [query]       Offline catalog book search (query optional with filters)
+  find-authors <query>     Offline catalog author search
+  list-categories          Offline category list
+  catalog                  Offline catalog metadata
+  search <query>           Live Turath search (JSONL meta + passages)
+  retrieve <query>         Live retrieve with citations/locators
+  get-page                 Fetch one internal page
+  get-context              Fetch page plus surrounding pages
+  get-book <book-id>       Book metadata + TOC
+  get-author <author-id>   Author metadata
+
+Global options:
+  --format jsonl|text      Output format (default: jsonl)
+  --timeout <ms>           Request timeout (default: ${DEFAULT_TIMEOUT}, 0 = no timeout, max ${MAX_TIMEOUT})
+  -h, --help               Show help
+  -v, --version            Print package version
+
+Notes:
+  • page-id is Turath internal page (location.internalPage), not printed page.
+  • search/retrieve accept at most one --book-id, one --author-id, and one --category-id
+    (filters may be combined; multiple values of the same filter are rejected).
+  • find-books allows repeated --author-id/--category-id (offline catalog only).
+  • Errors are JSON on stderr; data only on stdout.
+  • Exit: 0 ok (incl. zero hits), 1 usage/invalid, 2 not found, 3 http/rate/abort/invalid-response/internal.
+
+nusus help | nusus --help | nusus <command> --help
+`;
+
+const printHelp = (command) => {
+  if (command && COMMANDS[command]) {
+    process.stdout.write(`${COMMANDS[command].help}\n\nGlobal: --format jsonl|text  --timeout <ms>  --version\n`);
+  } else {
+    process.stdout.write(GLOBAL_HELP);
   }
-  emit(passageToJson(hit, {
-    source_type,
-    tier,
-    matched_term,
-    snippet: hit.snippet,
-    prev_text_tail: prevTail,
-    text: text.slice(0, 1500),
-    next_text_head: nextHead,
-  }));
-}
-
-if (top.length === 0) emit({ error: "No results", query, madhhab });
+};
+
+const createClient = (timeout) => {
+  const options = { timeout };
+  // Test-only override used by CLI subprocess tests. Not a supported public config surface.
+  const baseUrl = process.env.NUSUS_TURATH_BASE_URL;
+  if (baseUrl) options.baseUrl = baseUrl;
+  return createTurathClient(options);
+};
+
+const run = async () => {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const { positionals, flags, multi } = parseArgs(argv);
+
+  if (flags.version) {
+    const extraFlags = Object.keys(flags).filter((k) => k !== "version" && k !== "help");
+    if (positionals.length || Object.keys(multi).length || extraFlags.length) {
+      usage("--version does not accept other arguments");
+    }
+    process.stdout.write(`${VERSION}\n`);
+    process.exit(0);
+  }
+
+  let command = positionals[0];
+  let rest = positionals.slice(1);
+
+  if (flags.help && !command) {
+    printHelp();
+    process.exit(0);
+  }
+  if (command === "help") {
+    printHelp(rest[0]);
+    process.exit(0);
+  }
+  if (!command || !COMMANDS[command]) {
+    if (flags.help) {
+      printHelp();
+      process.exit(0);
+    }
+    usage(command ? `unknown command: ${command}` : "missing command");
+  }
+  if (flags.help) {
+    printHelp(command);
+    process.exit(0);
+  }
+
+  const spec = COMMANDS[command];
+  const { flags: cmdFlags, multi: cmdMulti } = takeAllowed(flags, multi, spec.flags);
+
+  const formatRaw = optionalFlag(cmdFlags, "format") ?? "jsonl";
+  if (formatRaw !== "jsonl" && formatRaw !== "text") usage("--format must be jsonl or text");
+  delete cmdFlags.format;
+
+  const timeout = parseIntFlag(cmdFlags.timeout, "timeout", {
+    def: DEFAULT_TIMEOUT,
+    min: 0,
+    max: MAX_TIMEOUT,
+  });
+  delete cmdFlags.timeout;
+
+  const turath = createClient(timeout);
+
+  try {
+    await spec.run({
+      turath,
+      format: formatRaw,
+      positionals: rest,
+      flags: cmdFlags,
+      multi: cmdMulti,
+    });
+  } catch (error) {
+    if (error instanceof NususError) fail(error.code, error);
+    fail("INTERNAL_ERROR", { message: error?.message ?? String(error) });
+  }
+};
+
+await run();