@khorsheed/dsh-library 0.0.0-stage → 0.1.0

package/lib/types/tools/project.js

@@ -0,0 +1,67 @@
+/**
+ * The `library_project` tool (moved verbatim from tool-definition.ts; the shared
+ * helpers and schemas are in `tools/kit.ts`).
+ *
+ * @module @khorsheed/dsh-library/tools/project
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { jsonOutput, pickString, unwrap } from "./kit.js";
+/** Build the `library_project` tool over the shared kit. */
+export function libraryProjectTool(kit) {
+    const { service, autoBind } = kit;
+    return defineTool({
+        name: 'library_project',
+        description: 'Create a learning project (one goal), or edit one (projectId + what changes; goal "" clears). template: subject | language (marks are words) | custom. Next: shelve its textbooks (library_textbook).',
+        parameters: {
+            projectId: { type: 'string', description: 'Edit this project; omit to create (ids are minted).' },
+            name: { type: 'string' },
+            template: { type: 'string', enum: ['subject', 'language', 'custom'] },
+            goal: { type: 'string', description: 'One line.' },
+        },
+        output: jsonOutput(),
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            // The edit target's id: projectId now, `id` from a model that memorized
+            // the old name (read off the typed surface). An id that resolves to
+            // nothing plus a name is a CREATE the model dressed up with a slug —
+            // create and say so, never fail it.
+            const legacyId = args.id;
+            const editId = pickString(args.projectId, legacyId);
+            if (editId !== undefined) {
+                const patch = {};
+                if (typeof args.name === 'string')
+                    patch.name = args.name;
+                if (typeof args.template === 'string')
+                    patch.template = args.template;
+                if (typeof args.goal === 'string')
+                    patch.goal = args.goal;
+                if (Object.keys(patch).length === 0)
+                    throw new Error('editing a project takes projectId plus the fields to change (name? / goal? / template?) — omit projectId to CREATE one (name + template)');
+                const edited = await service.updateProject({ id: editId, patch: patch });
+                if (edited.ok) {
+                    await autoBind(exec, { projectId: edited.project.id });
+                    return edited;
+                }
+                if (typeof args.name !== 'string' || args.name.trim() === '')
+                    throw new Error(edited.message);
+                const created = unwrap(await service.createProject({
+                    name: args.name,
+                    ...(typeof args.template === 'string' ? { template: args.template } : {}),
+                    ...(typeof args.goal === 'string' ? { goal: args.goal } : {}),
+                }));
+                await autoBind(exec, { projectId: created.project.id });
+                return { ...created, note: `no project ${JSON.stringify(editId)} existed — created a new one instead (ids are minted (p_…), never chosen by the caller; omit projectId to create)` };
+            }
+            if (typeof args.name !== 'string' || args.name.trim() === '') {
+                throw new Error('creating a project takes name (+ template: "language" | "subject" | "custom", goal?) — e.g. { name: "数学", template: "subject" }');
+            }
+            const created = unwrap(await service.createProject({
+                name: args.name,
+                ...(typeof args.template === 'string' ? { template: args.template } : {}),
+                ...(typeof args.goal === 'string' ? { goal: args.goal } : {}),
+            }));
+            await autoBind(exec, { projectId: created.project.id });
+            return created;
+        },
+    });
+}

package/lib/types/tools/quiz.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The `library_quiz` tool (moved verbatim from tool-definition.ts; the shared
+ * helpers and schemas are in `tools/kit.ts`).
+ *
+ * @module @khorsheed/dsh-library/tools/quiz
+ */
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+import { type ToolKit } from './kit.ts';
+/** Build the `library_quiz` tool over the shared kit. */
+export declare function libraryQuizTool(kit: ToolKit): ToolDefinition;
+//# sourceMappingURL=quiz.d.ts.map

package/lib/types/tools/quiz.js

@@ -0,0 +1,74 @@
+/**
+ * The `library_quiz` tool (moved verbatim from tool-definition.ts; the shared
+ * helpers and schemas are in `tools/kit.ts`).
+ *
+ * @module @khorsheed/dsh-library/tools/quiz
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { normalizeQuizOptions } from "../store.js";
+import { arrival, jsonOutput, normalizeQuestionAxes, payloadList, pickString, QUESTIONS_SCHEMA, unwrap, } from "./kit.js";
+/** Build the `library_quiz` tool over the shared kit. */
+export function libraryQuizTool(kit) {
+    const { service, bindingOf, projectOf, autoBind, scopeParams } = kit;
+    return defineTool({
+        name: 'library_quiz',
+        description: 'Store a quiz, then reply with one line — the learner answers in the sidebar. node = the station it tests (omit: a whole-textbook quiz; resource null: a free quiz). '
+            + 'focus is the learner\'s choice: mine = only their cards; book = the chapter only; mixed = their cards, then the chapter. '
+            + 'Every question names its point; quiz weak and untested points first, then practicing ones. '
+            + 'Solve each question again before storing; fix any disagreement. choice: answer = the right option verbatim. fill: a short value (1/2), several blanks comma-separated, alternatives " / ". free: say what a good answer covers. '
+            + 'Math only in $…$. The prompt carries no kind label or chapter reference. A material textbook needs quote (the page text). Replace voided (「这题有问题」) questions on the same points.',
+        parameters: {
+            ...scopeParams,
+            resource: { type: 'json', description: 'The textbook (defaults to the binding\'s); null = a free quiz.' },
+            node: { type: 'string', description: 'The quiz-gated station it gates.' },
+            focus: { type: 'string', enum: ['mine', 'book', 'mixed'] },
+            questions: {
+                ...QUESTIONS_SCHEMA,
+                required: true,
+                description: 'The questions.',
+            },
+        },
+        output: jsonOutput(),
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            const questions = payloadList(args.questions);
+            if (questions === undefined) {
+                throw new Error(`library_quiz takes questions: [{ point, kind: "choice"|"fill"|"free", prompt, options?, answer, explanation?, quote? }] (+ node?, focus?) — ${arrival('questions', args.questions)}`);
+            }
+            const node = typeof args.node === 'string' && args.node !== '' ? args.node : undefined;
+            // An explicit null is a free quiz on no textbook; absent falls back to the binding's.
+            const argsAny = args;
+            const resourceId = args.resource === null || argsAny.book === null ? undefined : pickString(args.resource, argsAny.book) ?? bindingOf(exec)?.resourceId;
+            // Options may arrive as { label } objects or a letter-keyed map —
+            // the stored form is plain strings (the same tolerance reads them
+            // back); the two axes default (topic + knowledge) and take the flat
+            // cardIds / quote / url / pageId shorthands.
+            const cleaned = questions.map((raw, index) => {
+                // The schema no longer rejects a question missing its id / kind / prompt /
+                // answer (that refusal named no question); blanks reach the service's
+                // per-question check, which names each one.
+                const text = (value) => typeof value === 'string' ? value : typeof value === 'number' ? String(value) : '';
+                // ids are numbered when the coach leaves them out (q1, q2…).
+                let next = { ...raw, id: text(raw.id) === '' ? `q${index + 1}` : text(raw.id), kind: text(raw.kind), prompt: text(raw.prompt), answer: text(raw.answer) };
+                if (next.options !== undefined) {
+                    const options = normalizeQuizOptions(next.options);
+                    if (options !== undefined)
+                        next = { ...next, options };
+                }
+                return normalizeQuestionAxes(next);
+            });
+            const projectId = projectOf(args.project, exec, resourceId);
+            const written = unwrap(await service.putQuiz({
+                projectId,
+                quiz: {
+                    ...(args.focus === 'mine' || args.focus === 'book' || args.focus === 'mixed' ? { focus: args.focus } : {}),
+                    scope: { ...(resourceId === undefined ? {} : { resourceId }), ...(node === undefined ? {} : { nodeId: node }) },
+                    questions: cleaned,
+                    ...(Array.isArray(argsAny.addPoints) ? { addPoints: argsAny.addPoints } : {}),
+                },
+            }));
+            await autoBind(exec, { projectId, ...(resourceId === undefined ? {} : { resourceId }) });
+            return written;
+        },
+    });
+}

package/lib/types/tools/read.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The `library_read` tool (moved verbatim from tool-definition.ts; the shared
+ * helpers and schemas are in `tools/kit.ts`).
+ *
+ * @module @khorsheed/dsh-library/tools/read
+ */
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+import { type ToolKit } from './kit.ts';
+/** Build the `library_read` tool over the shared kit. */
+export declare function libraryReadTool(kit: ToolKit): ToolDefinition;
+//# sourceMappingURL=read.d.ts.map

package/lib/types/tools/read.js

@@ -0,0 +1,127 @@
+/**
+ * The `library_read` tool (moved verbatim from tool-definition.ts; the shared
+ * helpers and schemas are in `tools/kit.ts`).
+ *
+ * @module @khorsheed/dsh-library/tools/read
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { jsonOutput, pickString, READ_WHATS, unwrap, } from "./kit.js";
+/**
+ * A path as the coach needs it: each station's id, title, state, rows and
+ * points, and whether its 讲义 exist — never the 讲义 text itself (a read of
+ * an 11-station path once returned 7,300 characters).
+ */
+function compactRoadmap(read) {
+    const stations = (roadmap) => roadmap.nodes.map(node => ({
+        id: node.id,
+        title: node.title,
+        state: node.state,
+        ...(node.gate === 'quiz' ? {} : { gate: node.gate }),
+        rows: node.covers.flatMap(cover => cover.locator === undefined ? [] : [cover.locator]).join(',') || undefined,
+        points: (node.points ?? []).map(point => `${point.id}: ${point.title}`),
+        ...(node.goals.length === 0 ? {} : { goals: node.goals }),
+        ...(node.acceptance === undefined || node.acceptance.length === 0 ? {} : { acceptance: node.acceptance }),
+        ...(node.notes === undefined ? {} : { notes: `${node.notes.text.length} chars, revision ${node.notes.revisions}` }),
+        ...(node.quizStats === undefined ? {} : { best: node.quizStats.bestRatio }),
+    }));
+    return {
+        ...(read.roadmap === undefined ? { adopted: null } : { adopted: { stations: stations(read.roadmap) } }),
+        ...(read.draft === undefined ? {} : { draft: { stations: stations(read.draft), note: read.draft.note } }),
+    };
+}
+/** Build the `library_read` tool over the shared kit. */
+export function libraryReadTool(kit) {
+    const { service, bindingOf, projectOf, resourceOf } = kit;
+    return defineTool({
+        name: 'library_read',
+        description: 'Read the library: projects (all, with this session\'s binding) | resources (one project\'s textbooks in study order) | toc (a textbook\'s contents rows) | roadmap (a textbook\'s path and pending draft) | pages (photographed pages) | cards (the learner\'s cards, weakest first) | quiz (one quiz, or the list). project and resource default to the binding.',
+        parameters: {
+            what: { type: 'string', description: 'One of the reads above.' },
+            project: { type: 'string' },
+            resource: { type: 'string' },
+            node: { type: 'string', description: 'A station (pages / cards).' },
+            quiz: { type: 'string', description: 'A quiz id.' },
+            query: { type: 'string', description: 'cards: search term, gloss, sentences.' },
+            due: { type: 'boolean', description: 'cards: only those due for review.' },
+        },
+        output: jsonOutput(),
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const argsAny = args;
+            // A read that forgot what: the arguments it did pass say which one it meant.
+            const what = typeof args.what === 'string' && args.what !== '' ? args.what
+                : args.quiz !== undefined ? 'quiz' : args.resource !== undefined || args.node !== undefined ? 'roadmap' : 'projects';
+            switch (what) {
+                case 'projects': {
+                    const listed = await service.listProjects();
+                    return { ...listed, binding: bindingOf(exec) ?? null };
+                }
+                case 'resources':
+                case 'books': { // the v4 spelling
+                    const detail = unwrap(await service.getProject({ id: projectOf(args.project, exec) }));
+                    return { project: detail.project, resources: detail.resources };
+                }
+                case 'toc': {
+                    const resource = resourceOf(args, exec);
+                    return unwrap(await service.getResource({ projectId: projectOf(args.project, exec, resource), resourceId: resource })).resource;
+                }
+                case 'roadmap': {
+                    const resource = resourceOf(args, exec);
+                    return compactRoadmap(await service.getRoadmap({ projectId: projectOf(args.project, exec, resource), resourceId: resource }));
+                }
+                case 'pages': {
+                    const resource = resourceOf(args, exec);
+                    return (await service.listPages({
+                        projectId: projectOf(args.project, exec, resource),
+                        resourceId: resource,
+                        ...(args.node === undefined ? {} : { nodeId: args.node }),
+                    }));
+                }
+                case 'cards': {
+                    const resource = pickString(args.resource, args.book);
+                    const result = await service.listCards({
+                        projectId: projectOf(args.project, exec, resource),
+                        ...(resource === undefined ? {} : { resourceId: resource }),
+                        ...(args.node === undefined ? {} : { nodeId: args.node }),
+                        ...(args.query === undefined ? {} : { query: args.query }),
+                        ...(argsAny.kind === 'word' || argsAny.kind === 'concept' ? { kind: argsAny.kind } : {}),
+                        ...(['photo', 'chat', 'quiz', 'manual'].includes(String(argsAny.source ?? '')) ? { source: argsAny.source } : {}),
+                        ...(typeof argsAny.weakMin === 'number' ? { weakMin: argsAny.weakMin } : {}),
+                        ...(args.due === true ? { due: true } : {}),
+                        limit: typeof argsAny.limit === 'number' ? argsAny.limit : 30,
+                    });
+                    // The model needs the card, not its whole ledger: sources compress to counts.
+                    return {
+                        total: result.total,
+                        cards: result.cards.map(card => ({
+                            id: card.id,
+                            kind: card.kind,
+                            term: card.term,
+                            ...(card.aliases.length === 0 ? {} : { aliases: card.aliases }),
+                            gloss: card.gloss,
+                            ...(card.userGloss === undefined ? {} : { userGloss: card.userGloss }),
+                            ...(card.resourceId === undefined ? {} : { resource: card.resourceId }),
+                            contexts: card.contexts.slice(0, 2).map(context => context.sentence),
+                            weakness: card.weakness,
+                            box: card.mastery.box,
+                            dueAt: card.mastery.dueAt,
+                            sources: card.sources.map(source => source.note === undefined ? source.type : `${source.type}: ${source.note}`).slice(-4),
+                        })),
+                    };
+                }
+                case 'quiz': {
+                    const resource = pickString(args.resource, args.book) ?? bindingOf(exec)?.resourceId;
+                    const project = projectOf(args.project, exec, resource);
+                    if (args.quiz === undefined || args.quiz.trim() === '') {
+                        return (await service.listAssessments({ projectId: project, type: 'quiz', ...(resource === undefined ? {} : { resourceId: resource }) }));
+                    }
+                    return unwrap(await service.getAssessment({ projectId: project, assessmentId: args.quiz.trim() })).assessment;
+                }
+                case 'stats':
+                    return (await service.stats());
+                default:
+                    throw new Error(`what is one of ${READ_WHATS.join(' | ')} — got ${JSON.stringify(args.what)}`);
+            }
+        },
+    });
+}

package/lib/types/tools/resource.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The `library_textbook` tool (moved verbatim from tool-definition.ts; the shared
+ * helpers and schemas are in `tools/kit.ts`).
+ *
+ * @module @khorsheed/dsh-library/tools/resource
+ */
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+import { type ToolKit } from './kit.ts';
+/** Build the `library_textbook` tool over the shared kit (the file keeps its v5 name). */
+export declare function libraryResourceTool(kit: ToolKit): ToolDefinition;
+//# sourceMappingURL=resource.d.ts.map

package/lib/types/tools/resource.js

@@ -0,0 +1,147 @@
+/**
+ * The `library_textbook` tool (moved verbatim from tool-definition.ts; the shared
+ * helpers and schemas are in `tools/kit.ts`).
+ *
+ * @module @khorsheed/dsh-library/tools/resource
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { isThickResource, LIBRARY_RESOURCE_KINDS } from "../types.js";
+import { arrival, jsonOutput, payload, payloadList, pickString, splitTocText, unwrap, } from "./kit.js";
+/** Build the `library_textbook` tool over the shared kit (the file keeps its v5 name). */
+export function libraryResourceTool(kit) {
+    const { service, projectOf, autoBind, scopeParams } = kit;
+    return defineTool({
+        name: 'library_textbook',
+        description: 'Shelve, correct, reorder or remove a textbook (anything with a contents) — in study order. origin: learner (their own) | picked (a book or course you chose; its path takes only the chapters the goal needs) | authored (you write it: one chapter per lesson, your 讲义 are its text). '
+            + 'A real book: verify the edition and contents online and cite the page (tocSource { by: "web", url }); never ask for an upload. A correction (resourceId) sends only what changes. A web page a station cites is no textbook — the path names its url.',
+        parameters: {
+            ...scopeParams,
+            op: { type: 'string', required: true, description: 'add | update | move | remove.' },
+            resourceId: { type: 'string', description: 'The textbook to update / move / remove.' },
+            title: { type: 'string', description: 'The exact edition\'s title.' },
+            origin: { type: 'string', enum: ['learner', 'picked', 'authored'] },
+            toc: { type: 'json', description: 'The contents: one chapter per line in one string, or ["…", "…"].' },
+            tocSource: { type: 'json', description: '{ by: "web" | "model" | "photo", url? } — web needs the url.' },
+            seq: { type: 'integer', description: 'Its place in the study order, from 1.' },
+            bookKind: { type: 'string', enum: ['knowledge', 'material'], description: 'material only when the exact text is what is tested (exam papers, literature).' },
+            edition: { type: 'string' },
+            author: { type: 'string' },
+            url: { type: 'string', description: 'A digital textbook\'s home page.' },
+            note: { type: 'string', description: 'One line on why it is here.' },
+        },
+        output: jsonOutput(),
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            // The v4 spellings ride along off the untyped surface (bookId → resourceId).
+            const argsAny = args;
+            const namedId = pickString(args.resourceId, argsAny.bookId);
+            // add / update are the advertised spellings; create (either one) still parses.
+            const op = args.op === 'add' || args.op === 'update' ? 'create' : args.op;
+            if (op === 'remove') {
+                if (namedId === undefined)
+                    throw new Error('library_textbook · op=remove takes the resourceId field — library_read · resources lists the ids');
+                return unwrap(await service.removeResource({ projectId: projectOf(args.project, exec, namedId), resourceId: namedId }));
+            }
+            if (op === 'move') {
+                if (namedId === undefined || typeof args.seq !== 'number')
+                    throw new Error('library_textbook · op=move takes resourceId and seq (the textbook\'s new place, from 1)');
+                const moved = unwrap(await service.moveResource({ projectId: projectOf(args.project, exec, namedId), resourceId: namedId, seq: args.seq }));
+                return { order: moved.resources.filter(resource => resource.seq !== undefined).map(resource => `${resource.seq}. ${resource.id} 《${resource.title}》`) };
+            }
+            if (op !== 'create') {
+                throw new Error(`library_textbook needs op: add | update | move | remove — got ${JSON.stringify(args.op)}`);
+            }
+            // origin is the v6 field; the older addedBy still parses (coach → picked).
+            const originArg = argsAny.origin ?? (argsAny.addedBy === 'learner' ? 'learner' : argsAny.addedBy === 'coach' ? 'picked' : undefined);
+            const origin = originArg === 'learner' || originArg === 'picked' || originArg === 'authored' ? { origin: originArg } : {};
+            const projectId = projectOf(args.project, exec, namedId);
+            // Cloning from another project is no longer advertised but still parses.
+            const from = payload(argsAny.from);
+            if (from !== undefined) {
+                const fromProject = pickString(from.project, from.projectId);
+                const fromResource = pickString(from.resource, from.resourceId, from.book, from.bookId);
+                if (fromProject === undefined || fromResource === undefined)
+                    throw new Error('from is { project, resource } — the OTHER project\'s id and the entry\'s id there');
+                const cloned = unwrap(await service.putResource({
+                    projectId,
+                    title: '',
+                    kind: 'article',
+                    ...(namedId === undefined ? {} : { resourceId: namedId }),
+                    from: { projectId: fromProject, resourceId: fromResource },
+                }));
+                await autoBind(exec, { projectId, resourceId: cloned.resource.id });
+                return cloned;
+            }
+            // A whole contents may arrive as one newline-joined string — the
+            // biggest single payload, and the one models mangle most as JSON.
+            const tocList = payloadList(args.toc);
+            const sentRows = typeof args.toc === 'string' && tocList === undefined
+                ? splitTocText(args.toc)
+                : (tocList ?? []);
+            // Correcting a shelved textbook (its note, kind, edition…) sends only
+            // what changes: the title and the contents come from the shelf.
+            const shelved = namedId !== undefined && sentRows.length === 0 && pickString(args.url) === undefined
+                ? await service.getResource({ projectId, resourceId: namedId })
+                : undefined;
+            const kept = shelved?.ok === true && isThickResource(shelved.resource) ? shelved.resource : undefined;
+            const tocRows = sentRows.length > 0 ? sentRows : (kept?.toc ?? []).map(entry => ({ ...entry }));
+            if (kept !== undefined) {
+                if (typeof args.title !== 'string' || args.title.trim() === '')
+                    argsAny.title = kept.title;
+                if (argsAny.kind === undefined)
+                    argsAny.kind = kept.kind;
+            }
+            // A thin link is the hidden v5 case: only an explicit link kind (article, video…) takes that branch.
+            const linkKind = typeof argsAny.kind === 'string' && argsAny.kind !== 'book' && argsAny.kind !== 'course' && LIBRARY_RESOURCE_KINDS.includes(argsAny.kind);
+            const thick = tocRows.length > 0 || !linkKind;
+            if (thick) {
+                if (typeof args.title !== 'string' || args.title.trim() === '' || tocRows.length === 0) {
+                    throw new Error(`a textbook takes: title, toc (one chapter per line), tocSource { by, url? }, origin (+ seq?, bookKind?, edition?, author?; resourceId to update one) — ${arrival('toc', args.toc)}`);
+                }
+                const toc = tocRows.map(row => typeof row === 'string' ? { title: row } : row);
+                const written = unwrap(await service.putResource({
+                    projectId,
+                    ...(namedId === undefined ? {} : { resourceId: namedId }),
+                    title: args.title,
+                    kind: argsAny.kind === 'course' ? 'course' : 'book',
+                    ...(typeof args.url === 'string' ? { url: args.url } : {}),
+                    ...(typeof args.note === 'string' ? { note: args.note } : {}),
+                    ...origin,
+                    ...(typeof args.seq === 'number' ? { seq: args.seq } : {}),
+                    toc,
+                    tocSource: (payload(args.tocSource) ?? kept?.tocSource ?? { by: 'model' }),
+                    ...(args.bookKind === 'knowledge' || args.bookKind === 'material' ? { bookKind: args.bookKind } : {}),
+                    ...(typeof argsAny.short === 'string' ? { short: argsAny.short } : {}),
+                    ...(typeof args.author === 'string' ? { author: args.author } : {}),
+                    ...(typeof args.edition === 'string' ? { edition: args.edition } : {}),
+                    ...(typeof argsAny.isbn === 'string' ? { isbn: argsAny.isbn } : {}),
+                    ...(Array.isArray(payloadList(argsAny.extras)) ? { extras: payloadList(argsAny.extras) } : {}),
+                }));
+                await autoBind(exec, { projectId, resourceId: written.resource.id });
+                // A real book with a handful of rows was almost always joined wrong — say so before a path is drafted against it.
+                const rows = written.resource.toc?.length ?? 0;
+                return {
+                    ...written,
+                    contentsRows: rows,
+                    ...(rows < 3 ? { warning: `the contents has only ${rows} row(s) — one row per chapter is expected (station chapters count these rows). If the chapters got joined, resend toc with one chapter per line and resourceId ${written.resource.id}` } : {}),
+                };
+            }
+            const title = pickString(args.title);
+            const url = pickString(args.url);
+            if (title === undefined || url === undefined) {
+                throw new Error(`a link takes: title, url, kind ("article"|"video"|"repo"|"tool"|"hardware"), note? — got title ${title === undefined ? '✗ MISSING' : '✓'} · url ${url === undefined ? '✗ MISSING' : '✓'} (a textbook takes kind "book" | "course" + toc)`);
+            }
+            const added = unwrap(await service.putResource({
+                projectId,
+                ...(namedId === undefined ? {} : { resourceId: namedId }),
+                title,
+                kind: linkKind ? argsAny.kind : 'article',
+                url,
+                ...(typeof args.note === 'string' ? { note: args.note } : {}),
+                ...origin,
+            }));
+            await autoBind(exec, { projectId });
+            return added;
+        },
+    });
+}

package/lib/types/tools/roadmap.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The `library_roadmap` tool (moved verbatim from tool-definition.ts; the shared
+ * helpers and schemas are in `tools/kit.ts`).
+ *
+ * @module @khorsheed/dsh-library/tools/roadmap
+ */
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+import { type ToolKit } from './kit.ts';
+/** Build the `library_roadmap` tool over the shared kit. */
+export declare function libraryRoadmapTool(kit: ToolKit): ToolDefinition;
+//# sourceMappingURL=roadmap.d.ts.map

package/lib/types/tools/roadmap.js

@@ -0,0 +1,102 @@
+/**
+ * The `library_roadmap` tool (moved verbatim from tool-definition.ts; the shared
+ * helpers and schemas are in `tools/kit.ts`).
+ *
+ * @module @khorsheed/dsh-library/tools/roadmap
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { formatLocator } from "../types.js";
+import { arrival, chaptersLocator, jsonOutput, normalizeCoverArg, NODES_SCHEMA, payload, payloadList, pickString, unwrap, } from "./kit.js";
+/** Build the `library_roadmap` tool over the shared kit. */
+export function libraryRoadmapTool(kit) {
+    const { service, projectOf, autoBind, textbookList } = kit;
+    return defineTool({
+        name: 'library_roadmap',
+        description: 'Draft one textbook\'s path (replaces its previous draft); the learner adopts it in the sidebar. '
+            + 'One station = one lesson: 3–5 knowledge points, simple → hard. A real book\'s long chapter splits into several stations; a textbook you authored teaches one chapter per station.',
+        parameters: {
+            resource: { type: 'string', required: true, description: 'The textbook.' },
+            nodes: { ...NODES_SCHEMA, required: true, description: 'The stations, in study order.' },
+            note: { type: 'string', description: 'One line of pacing for the draft card.' },
+        },
+        output: jsonOutput(),
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            const list = payloadList(args.nodes);
+            if (list === undefined) {
+                throw new Error(`library_roadmap takes resource and nodes: [{ id, title, chapters: "3-4", points: [{ id, title }] (3–5), goals?, acceptance? }] — ${arrival('nodes', args.nodes)}`);
+            }
+            const argsAny = args;
+            const resourceId = pickString(args.resource, argsAny.book);
+            if (resourceId === undefined)
+                throw new Error(`a path belongs to one textbook — pass resource${textbookList(exec) || ' (shelve the textbook first with library_textbook)'}`);
+            const adjusted = [];
+            const missingPoints = [];
+            const nodes = list.map(node => {
+                const { chapters, also, chapterRanges, covers, kind, gate, points, ...rest } = node;
+                // gate is the v5 spelling; the old kind still parses (practice → acceptance).
+                // Unsaid, every station is a quiz one: its check is the chapter quiz, never a
+                // rubric the learner cannot tell how to meet (10-26) — stray acceptance
+                // lines become goals.
+                const gateValue = typeof gate === 'string' ? gate : kind === 'practice' ? 'acceptance' : typeof kind === 'string' ? kind : 'quiz';
+                if (gateValue === 'quiz' && Array.isArray(rest.acceptance) && rest.acceptance.length > 0) {
+                    const lines = rest.acceptance.flatMap(line => typeof line === 'string' ? [line] : typeof payload(line)?.line === 'string' ? [String(payload(line).line)] : []);
+                    const goals = Array.isArray(rest.goals) ? rest.goals : typeof rest.goals === 'string' ? [rest.goals] : [];
+                    rest.goals = [...goals, ...lines];
+                    delete rest.acceptance;
+                }
+                if (gateValue === 'quiz' && (!Array.isArray(points) || points.length === 0)) {
+                    missingPoints.push(String(rest.id ?? rest.title ?? '?'));
+                }
+                // Points belong to quiz stations; on any other gate they are dropped, not refused.
+                const keepPoints = gateValue === 'quiz' || points === undefined || (Array.isArray(points) && points.length === 0);
+                if (!keepPoints)
+                    adjusted.push(`points dropped on ${String(rest.title ?? rest.id)} — a ${String(gateValue)} station has no quiz; what it checks belongs in ${gateValue === 'acceptance' ? 'acceptance lines' : 'goals'}`);
+                const main = [];
+                const spelled = typeof chapters === 'string' && chapters.trim() !== '' ? chaptersLocator(chapters) : undefined;
+                if (spelled?.rest !== undefined)
+                    adjusted.push(`${String(rest.title ?? rest.id)}: "${spelled.rest}" in chapters is not a row number — kept as a side reference (topic: ${spelled.rest})`);
+                const locator = typeof chapters === 'number' ? String(chapters)
+                    : spelled !== undefined ? spelled.locator
+                        : Array.isArray(chapters) ? chapters.filter(entry => typeof entry === 'number' || typeof entry === 'string').join(',')
+                            : Array.isArray(chapterRanges) ? formatLocator(chapterRanges.flatMap(range => {
+                                const row = payload(range);
+                                return typeof row?.from === 'number' && typeof row.to === 'number' ? [{ from: row.from, to: row.to }] : [];
+                            })) : undefined;
+                if (locator !== undefined && locator !== '')
+                    main.push({ ref: resourceId, locator });
+                const side = [...(Array.isArray(covers) ? covers : []), ...(Array.isArray(also) ? also : typeof also === 'string' ? [also] : []), ...(spelled?.rest === undefined ? [] : [`topic: ${spelled.rest}`])]
+                    .map(cover => normalizeCoverArg(cover) ?? cover);
+                // A station naming neither rows nor references rests on the textbook whole.
+                const all = main.length === 0 && side.length === 0 ? [{ ref: resourceId }] : [...main, ...side];
+                return { ...rest, ...(gateValue === undefined ? {} : { gate: gateValue }), ...(keepPoints && points !== undefined ? { points } : {}), covers: all };
+            });
+            // Every station is checked by its chapter quiz, and the quiz asks its points.
+            if (missingPoints.length > 0) {
+                throw new Error(`every station needs its 3–5 knowledge points (points: [{ id, title }]) — the chapter quiz asks them: ${missingPoints.join(', ')}`);
+            }
+            const projectId = projectOf(argsAny.project, exec, resourceId);
+            const before = unwrap(await service.getProject({ id: projectId }));
+            const replaced = before.project.resources.find(row => row.id === resourceId)?.hasDraft === true;
+            const drafted = unwrap(await service.draftRoadmap({
+                projectId,
+                resourceId,
+                nodes: nodes,
+                ...(typeof argsAny.passRatio === 'number' ? { passRatio: argsAny.passRatio } : {}),
+                ...(typeof args.note === 'string' ? { note: args.note } : {}),
+            }));
+            await autoBind(exec, { projectId, resourceId });
+            const after = unwrap(await service.getProject({ id: projectId }));
+            const textbook = after.project.resources.find(row => row.id === resourceId);
+            return {
+                ok: true,
+                placedOn: `${textbook?.seq ?? '-'}. 《${textbook?.title ?? resourceId}》 (${resourceId})`,
+                stations: drafted.draft.nodes.length,
+                ...(replaced ? { replacedDraft: true } : {}),
+                waitingForAdoption: after.project.resources.filter(row => row.hasDraft).map(row => `${row.seq ?? '-'}. 《${row.title}》 ${row.draftTotal ?? 0} stations`),
+                ...(adjusted.length === 0 ? {} : { adjusted }),
+                next: 'Describe the path to the learner in two lines and ask them to review and adopt it in the sidebar (采用). Then stop: before they adopt it, write no 讲义, teach nothing, set no quiz.',
+            };
+        },
+    });
+}