@khorsheed/dsh-library 0.0.0-stage → 0.1.0

package/lib/types/types.js

@@ -0,0 +1,159 @@
+/**
+ * The library's domain vocabulary: projects, resources, roadmaps, nodes,
+ * assessments, attempts, photo pages, knowledge cards and session bindings.
+ * Everything here is plain serializable data — the store (`store.ts`)
+ * persists exactly these shapes under `$DSH_HOME/state/dsh-library/`, and the
+ * Remote face (`remote.ts`) and the model tools (`tool-definition.ts`) both
+ * speak them.
+ *
+ * The shapes follow the proposal `2026-10-16-library-v5-model` (v5: the
+ * six-layer core — Project → Resource → Roadmap → Node → Assessment →
+ * Attempt, with Card / Page / Event as the trace layer):
+ *
+ * - a RESOURCE is anything on the project's shelf. Its `toc` is the
+ *   thick/thin switch: a resource WITH a contents (a book, a course with
+ *   episodes) can carry a roadmap, be covered by chapter, be quizzed and be
+ *   photographed; one without is a thin link (an article, a video, a tool)
+ *   that only enters a path whole. Nothing is ever uploaded — a thick
+ *   resource registers title, kind and a contents the coach verified on the
+ *   web (or took from a photo);
+ * - a ROADMAP belongs to exactly one thick resource — a TEXTBOOK (proposal
+ *   `2026-10-19-library-book-paths`: the project carries no path of its
+ *   own). Textbooks sit on the shelf in study order (`seq`), and come from
+ *   the learner, from the coach's pick, or from the coach's own pen
+ *   (`origin`). A node draws on COVERS in one shape — `{ ref, locator? }`,
+ *   where ref is a resource id, a bare url, or `topic:…` (plain coached
+ *   teaching) and locator counts contents rows ("1-5,7"); the path's own
+ *   textbook is the main cover, anything else rides along as a side
+ *   reference. A path need not cover the whole contents. The coach writes DRAFTS, the
+ *   learner adopts one, and the adopted path's state machine has three edges
+ *   only (`locked → current → done`);
+ * - a NODE's `gate` says how it completes: `quiz` (an assessed quiz at the
+ *   pass ratio), `acceptance` (a hands-on station — the learner submits
+ *   evidence, the coach judges one verdict per rubric line), `read` (an
+ *   optional side stop that 「读完」 completes and never gates);
+ * - an ASSESSMENT is the graded thing: `quiz` carries questions, `practice`
+ *   carries a station's materialized rubric (stable line ids; a line may
+ *   reference another assessment that machine-checks it). Hung on a node, on
+ *   a resource (a book-level paper), or on nothing (free practice). A
+ *   station's paper history chains by `supersededBy`;
+ * - an ATTEMPT is one graded sitting and names only its `assessmentId` (a
+ *   verdict's `task` is a question id or a rubric line id, so rewording never
+ *   orphans history);
+ * - a PAGE is one photographed page of a thick resource: its recognized text
+ *   plus the learner's marks;
+ * - a CARD (知识卡片) is the learner's own memory: a word or a concept met in a
+ *   photo, asked about in a chat, or missed in an assessment — one card per
+ *   thing, sources stacked, with a weakness score (0–3) beside its Leitner
+ *   mastery;
+ * - an EVENT is the append-only audit trail.
+ *
+ * @module @khorsheed/dsh-library/types
+ */
+/** The state-root directory name under `$DSH_HOME/state`. */
+export const STATE_ROOT_SEGMENT = 'dsh-library';
+/**
+ * The on-disk schema version of `state.json`. v1 (uploaded books, project
+ * roadmaps, the vocab book) was never deployed; a v1 root reads as empty. v2
+ * roots (per-book roadmaps with `chapterRanges`) and v3/v4 roots (the
+ * book/resource split, cover unions, quiz entities) all read tolerantly —
+ * every normalize* function reads the old shapes — and rewrite to v5 on their
+ * next write. There is no offline migration pass.
+ */
+export const LIBRARY_STATE_VERSION = 5;
+/** The Leitner intervals in days, indexed by box (box 5 reuses the last rung). */
+export const LEITNER_INTERVAL_DAYS = [1, 2, 4, 7, 15];
+/** The highest Leitner box. */
+export const MAX_BOX = 5;
+/** The highest weakness score (three bars in the UI). */
+export const MAX_WEAKNESS = 3;
+/** The default node pass threshold (an assessment ratio at or above it completes the node). */
+export const DEFAULT_PASS_RATIO = 0.8;
+/** The preset project colors (the sidebar maps each to a light and a dark tone). */
+export const LIBRARY_COLORS = ['ember', 'amber', 'moss', 'teal', 'sky', 'indigo', 'plum', 'rose'];
+/** The preset project icons. */
+export const LIBRARY_ICONS = ['globe', 'brain', 'book', 'flask', 'atom', 'leaf', 'pen', 'music', 'scale', 'chart', 'code', 'compass'];
+/** A template's default look, until the learner picks another. */
+export const TEMPLATE_LOOK = {
+    language: { color: 'ember', icon: 'globe' },
+    subject: { color: 'indigo', icon: 'brain' },
+    custom: { color: 'teal', icon: 'compass' },
+};
+/**
+ * Where a shelf entry came from: `learner` — the learner's own (a book they
+ * hold, a link they handed over); `picked` — an existing book / course / link
+ * the coach chose; `authored` — a textbook the coach wrote itself (its
+ * contents are the coach's own outline, its 讲义 are the text). Legacy
+ * `addedBy` reads as learner / picked.
+ */
+export const LIBRARY_RESOURCE_ORIGINS = ['learner', 'picked', 'authored'];
+/** What a shelf entry IS: the shape of the thing it is or points at. */
+export const LIBRARY_RESOURCE_KINDS = ['book', 'article', 'video', 'repo', 'tool', 'course', 'hardware'];
+/** Whether a resource is thick (routable, coverable by chapter, quizzable, photographable). */
+export function isThickResource(resource) {
+    return resource.toc !== undefined && resource.toc.length > 0;
+}
+/**
+ * The locator's text form: comma-joined spans ("1-5,7,9-12" — a one-row span
+ * is the bare number). Contents-row spans are what cover locators count.
+ */
+export function formatLocator(ranges) {
+    return ranges.map(range => range.from === range.to ? String(range.from) : `${range.from}-${range.to}`).join(',');
+}
+/** Parse a locator ("1-5,7") into spans; bad segments drop out. */
+export function parseLocator(locator) {
+    return locator.split(',').flatMap(segment => {
+        const match = /^\s*(\d+)\s*(?:[-–—]\s*(\d+)\s*)?$/.exec(segment);
+        if (match === null)
+            return [];
+        const from = Number.parseInt(match[1], 10);
+        const to = match[2] === undefined ? from : Number.parseInt(match[2], 10);
+        return from >= 1 && to >= from ? [{ from, to }] : [];
+    });
+}
+/** Discriminate a cover by its ref's form (a resource id resolves against the shelf). */
+export function coverKind(cover) {
+    if (cover.ref.startsWith('topic:'))
+        return 'topic';
+    if (/^https?:\/\//.test(cover.ref))
+        return 'url';
+    return 'resource';
+}
+/** A topic cover's teaching text (the ref minus its `topic:` prefix). */
+export function coverTopic(cover) {
+    return cover.ref.startsWith('topic:') ? cover.ref.slice('topic:'.length) : undefined;
+}
+/** An acceptance station's rubric: its acceptance lines with stable positional ids (L1, L2, …). */
+export function acceptanceLines(node) {
+    return (node.acceptance ?? []).map((entry, index) => typeof entry === 'string'
+        ? { id: `L${index + 1}`, line: entry }
+        : { id: `L${index + 1}`, line: entry.line, ...(entry.ref === undefined ? {} : { ref: entry.ref }) });
+}
+/** The event vocabulary, for tests and for writers who must not invent types. */
+export const LIBRARY_EVENT_TYPES = [
+    'resource.added',
+    'roadmap.drafted',
+    'roadmap.adopted',
+    'page.recorded',
+    'cards.recorded',
+    'card.edited',
+    'quiz.created',
+    'attempt.assessed',
+    'node.completed',
+    'node.unlocked',
+    'node.noted',
+    'point.changed',
+];
+/* ------------------------------------------------------------- id minting */
+/** Ids become path segments — keep them inside a safe alphabet (mission rule). */
+export const LIBRARY_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Whether an id is usable as a path segment. */
+export function isLibraryId(id) {
+    return LIBRARY_ID_PATTERN.test(id);
+}
+/** A native fs failure's message, with its code, for the wire. */
+export function libraryErrorMessage(error) {
+    const code = error?.code;
+    const message = error instanceof Error ? error.message : String(error);
+    return code === undefined ? message : `${code}: ${message}`;
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Library",
+    "description": "Project-organized deep reading: book ingestion, roadmaps, a vocab book and graded quizzes."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "图书馆",
+    "description": "按项目组织的精读学习：书籍摄入、路线图、词书与测验判题。"
+  }
+}

package/package.json

@@ -1,6 +1,138 @@
 {
   "name": "@khorsheed/dsh-library",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Library and learning engine: project-organized close reading of registered books (no upload) — a per-book roadmap the coach drafts and the learner adopts, photographed pages whose marks become knowledge cards, cards that dedupe and track weakness, two-axis quizzes (what they target × what they rest on) and verdict-led unlocking — a Typert Remote data face, a right-Sidebar page tab, and the ./tool composition entry (library_read + one library_<noun> tool per write + library_assess) for agent presets",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types.js"
+    },
+    "./tool": {
+      "types": "./lib/types/tool.d.ts",
+      "default": "./lib/tool.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./typert": {
+      "types": "./lib/typert.host.d.ts",
+      "default": "./lib/typert.host.js"
+    },
+    "./remote": {
+      "types": "./lib/typert.remote-client.d.ts",
+      "default": "./lib/typert.remote-client.js"
+    },
+    "./src/*": "./src/*",
+    "./locale/*.json": "./locale/*.json",
+    "./tool/locale/*.json": "./locale/*.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "lib/typert.host.d.ts",
+    "lib/typert.host.js",
+    "lib/typert.remote-client.d.ts",
+    "lib/typert.remote-client.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "CHANGELOG.md"
+  ],
+  "license": "MIT",
+  "engines": {
+    "dsh": ">=0.1.7-rc.1 <0.3.0-0"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-session": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": "^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-agent": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-api-remotes": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-locale": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-primitives": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-session": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-sidebar-right": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-slots": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
+    "@deepseek-ai/schemastery": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "cordis",
+    "library",
+    "learning",
+    "reading",
+    "epub",
+    "vocab",
+    "quiz",
+    "sidebar"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-primitives",
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
+        "@deepseek-ai/dsh-client-ui-session",
+        "@deepseek-ai/dsh-client-ui-slots"
+      ],
+      "platform": "web"
+    },
+    "compat": {
+      "minHost": "0.1.7-rc.1",
+      "notes": "A page-type right-Sidebar tab (minted kind `library`) over a Typert Remote data face, plus the `./tool` composition entry (library_read / library_write / library_assess, the coaching prompt section and a per-turn bound-context line via systemPrompt.context) an agent preset names. Books are registered, never uploaded: the coach verifies the edition's contents on the web; nothing is parsed. State is plain `node:fs` under `$DSH_HOME/state/dsh-library` (atomic temp+rename, per-project lock, append-only JSONL ledgers) — never `ctx.fs`, the session-fenced sandbox (the reader precedent). Session bindings (project / book) are keyed by the calling agent's session id. The tab type self-hides on the preset-composition criterion (the canvas double check: root rows ∪ the current session's preset rows, `@khorsheed/dsh-library/tool`), fail-open on every unreadable path. Photos go through the probed `attachments` service (saveImage for sidebar uploads; readImage only for pages the project recorded), degrading to `unavailable` without it. The tool row's optional hideSections / denyTools quiet a focused preset's scope through scoped prompt sections and tools.restrict, skipping any name the composition does not hold.",
+      "verifiedHost": "0.2.1-rc.1"
+    }
+  }
 }