dsh-quicknote 0.0.0-stage → 0.1.1

package/lib/index.js

@@ -0,0 +1,351 @@
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+// src/shared/constants.ts
+/** Package name; must equal package.json `name` (the client bundle id). */
+const NAME = "dsh-quicknote";
+/** Host JSON API used by the page. */
+const API = "/api/quicknote";
+// src/host/paths.ts
+/** Keep the example's data separate from other plugins. */
+function resolveNotesFile(ctx) {
+	try {
+		const dshHomePath = typeof ctx.get === "function" ? ctx.get("dshHomePath") : void 0;
+		if (typeof dshHomePath === "function") {
+			const dir = dshHomePath("quicknote");
+			if (typeof dir === "string" && dir !== "") return join(dir, "notes.json");
+		}
+	} catch {}
+	const home = (process.env.DSH_HOME ?? "").trim() || join(homedir(), ".dsh");
+	return join(home, "quicknote", "notes.json");
+}
+// src/host/routes.ts
+var HttpError = class extends Error {
+	status;
+	constructor(status, message) {
+		super(message);
+		this.status = status;
+	}
+};
+function json(status, body) {
+	return new Response(`${JSON.stringify(body)}\n`, {
+		status,
+		headers: {
+			"content-type": "application/json; charset=utf-8",
+			"cache-control": "no-store"
+		}
+	});
+}
+async function body(request) {
+	try {
+		const value = await request.json();
+		return value && typeof value === "object" ? value : {};
+	} catch {
+		throw new HttpError(400, "invalid-json");
+	}
+}
+function registerRoutes(ctx, store) {
+	ctx.inject(["connection"], (scope) => {
+		const registry = scope.get("connection")?.fetch;
+		if (typeof registry?.register !== "function") {
+			ctx.logger?.warn?.("dsh-quicknote: no fetch registry; the page will not load notes");
+			return;
+		}
+		const wrap = (handler) => async (request) => {
+			try {
+				return await handler(request);
+			} catch (error) {
+				return json(error instanceof HttpError ? error.status : 500, {
+					ok: false,
+					error: error instanceof HttpError ? error.message : String(error?.message ?? error)
+				});
+			}
+		};
+		const routes = [
+			{
+				path: `${API}/notes`,
+				methods: ["GET"],
+				fetch: wrap(async () => json(200, {
+					ok: true,
+					notes: await store.list()
+				}))
+			},
+			{
+				path: `${API}/notes/create`,
+				methods: ["POST"],
+				fetch: wrap(async (request) => {
+					const input = await body(request);
+					return json(200, {
+						ok: true,
+						note: await store.add(input.text, input.origin)
+					});
+				})
+			},
+			{
+				path: `${API}/notes/update`,
+				methods: ["POST"],
+				fetch: wrap(async (request) => {
+					const input = await body(request);
+					const note = await store.update(input.id, input.done === true);
+					return note ? json(200, {
+						ok: true,
+						note
+					}) : json(404, {
+						ok: false,
+						error: "unknown-note"
+					});
+				})
+			},
+			{
+				path: `${API}/notes/delete`,
+				methods: ["POST"],
+				fetch: wrap(async (request) => json(200, {
+					ok: true,
+					note: await store.remove((await body(request)).id)
+				}))
+			},
+			{
+				path: `${API}/notes/restore`,
+				methods: ["POST"],
+				fetch: wrap(async (request) => {
+					try {
+						return json(200, {
+							ok: true,
+							note: await store.restore((await body(request)).note)
+						});
+					} catch (error) {
+						if (String(error?.message) === "invalid-note") throw new HttpError(400, "invalid-note");
+						throw error;
+					}
+				})
+			}
+		];
+		for (const route of routes) scope.effect(() => registry.register({
+			path: route.path,
+			methods: route.methods,
+			requestBody: "buffered",
+			fetch: route.fetch
+		}), `dsh-quicknote: ${route.path}`);
+	});
+}
+// src/host/store.ts
+const MAX_TEXT = 2e4;
+function parseNote(value) {
+	if (value === null || typeof value !== "object") return null;
+	const raw = value;
+	if (typeof raw.id !== "string" || raw.id === "" || raw.id.length > 128) return null;
+	if (typeof raw.text !== "string") return null;
+	const text = raw.text.trim();
+	if (text === "" || text.length > MAX_TEXT) return null;
+	const createdAt = typeof raw.createdAt === "number" && Number.isFinite(raw.createdAt) ? raw.createdAt : Date.now();
+	const note = {
+		id: raw.id,
+		text,
+		done: raw.done === true,
+		createdAt
+	};
+	const origin = parseOrigin(raw.origin);
+	if (origin) note.origin = origin;
+	return note;
+}
+function parseOrigin(value) {
+	if (value === null || typeof value !== "object") return void 0;
+	const sessionId = String(value.sessionId ?? "");
+	const title = String(value.title ?? "");
+	if (sessionId === "" && title === "") return void 0;
+	return {
+		sessionId,
+		title
+	};
+}
+/** A small durable store: one JSON file, atomic whole-file writes, newest first. */
+function createStore(file) {
+	let cache = null;
+	let tail = Promise.resolve();
+	function serialized(run) {
+		const result = tail.then(run);
+		tail = result.then(() => void 0, () => void 0);
+		return result;
+	}
+	async function load() {
+		if (cache) return cache;
+		try {
+			const parsed = JSON.parse(await readFile(file, "utf8"));
+			cache = Array.isArray(parsed.notes) ? parsed.notes.filter((note) => typeof note === "object" && note !== null && typeof note.id === "string" && typeof note.text === "string" && note.text.trim() !== "") : [];
+		} catch {
+			cache = [];
+		}
+		return cache;
+	}
+	async function save(notes) {
+		await mkdir(dirname(file), { recursive: true });
+		const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+		await writeFile(temporary, `${JSON.stringify({ notes }, null, 2)}\n`, { mode: 384 });
+		await rename(temporary, file);
+		cache = notes;
+	}
+	return {
+		file,
+		list() {
+			return serialized(async () => [...await load()]);
+		},
+		add(text, origin) {
+			return serialized(async () => {
+				const value = String(text ?? "").trim();
+				if (value === "") throw new Error("empty-note");
+				if (value.length > MAX_TEXT) throw new Error("note-too-long");
+				const notes = await load();
+				const createdAt = Math.max(Date.now(), (notes[0]?.createdAt ?? 0) + 1);
+				const note = {
+					id: randomUUID(),
+					text: value,
+					done: false,
+					createdAt
+				};
+				const cleanOrigin = parseOrigin(origin);
+				if (cleanOrigin) note.origin = cleanOrigin;
+				await save([note, ...notes]);
+				return note;
+			});
+		},
+		update(id, done) {
+			return serialized(async () => {
+				const notes = await load();
+				const current = notes.find((note) => note.id === id);
+				if (!current) return null;
+				const updated = {
+					...current,
+					done
+				};
+				await save(notes.map((note) => note.id === id ? updated : note));
+				return updated;
+			});
+		},
+		remove(id) {
+			return serialized(async () => {
+				const notes = await load();
+				const removed = notes.find((note) => note.id === id) ?? null;
+				if (!removed) return null;
+				await save(notes.filter((note) => note.id !== id));
+				return removed;
+			});
+		},
+		restore(value) {
+			return serialized(async () => {
+				const note = parseNote(value);
+				if (!note) throw new Error("invalid-note");
+				const notes = await load();
+				const existing = notes.find((item) => item.id === note.id);
+				if (existing) return existing;
+				const index = notes.findIndex((item) => item.createdAt <= note.createdAt);
+				const next = [...notes];
+				next.splice(index === -1 ? notes.length : index, 0, note);
+				await save(next);
+				return note;
+			});
+		}
+	};
+}
+// src/host/tools.ts
+function textOutput() {
+	return {
+		schema: { type: "string" },
+		render: (_args, value) => [{
+			type: "text",
+			text: String(value)
+		}]
+	};
+}
+function describe(note) {
+	const text = note.text.length > 200 ? `${note.text.slice(0, 200)}…` : note.text;
+	return `- ${note.id} (${note.done ? "done" : "open"}): ${text}`;
+}
+function createTools(store) {
+	return [
+		{
+			name: "quicknote_add",
+			description: "Save one note in the user's Quick Note list. Use it when the user asks to remember or park something for later.",
+			parameters: {
+				type: "object",
+				additionalProperties: false,
+				required: ["text"],
+				properties: { text: {
+					type: "string",
+					description: "The note body."
+				} }
+			},
+			output: textOutput(),
+			async execute(args) {
+				const note = await store.add(args?.text);
+				return `Saved as ${note.id}.\n${describe(note)}`;
+			}
+		},
+		{
+			name: "quicknote_list",
+			description: "List notes in the user's Quick Note list, newest first.",
+			parameters: {
+				type: "object",
+				additionalProperties: false,
+				properties: {}
+			},
+			output: textOutput(),
+			async execute() {
+				const notes = await store.list();
+				return notes.length === 0 ? "The Quick Note list is empty." : `${notes.length} note${notes.length === 1 ? "" : "s"}:\n${notes.map(describe).join("\n")}`;
+			}
+		},
+		{
+			name: "quicknote_done",
+			description: "Mark one Quick Note as done, or reopen it with done=false.",
+			parameters: {
+				type: "object",
+				additionalProperties: false,
+				required: ["id"],
+				properties: {
+					id: { type: "string" },
+					done: { type: "boolean" }
+				}
+			},
+			output: textOutput(),
+			async execute(args) {
+				const note = await store.update(args?.id, args?.done === false ? false : true);
+				return note ? `Note ${note.id} is ${note.done ? "done" : "open"}.` : `No note with id "${args?.id}".`;
+			}
+		},
+		{
+			name: "quicknote_delete",
+			description: "Delete one Quick Note permanently. Only when the user explicitly asks.",
+			parameters: {
+				type: "object",
+				additionalProperties: false,
+				required: ["id"],
+				properties: { id: { type: "string" } }
+			},
+			output: textOutput(),
+			async execute(args) {
+				return await store.remove(args?.id) ? `Deleted ${args?.id}.` : `No note with id "${args?.id}".`;
+			}
+		}
+	];
+}
+// src/host/index.ts
+/**
+* Host half of the Quick Note example: one JSON file, four routes, four tools.
+*
+* @module dsh-quicknote/host
+*/
+const name = NAME;
+function apply(ctx) {
+	const store = createStore(resolveNotesFile(ctx));
+	ctx.effect(() => {
+		store.list().catch((error) => {
+			ctx.logger?.warn?.(`${NAME}: could not read notes: ${String(error)}`);
+		});
+	}, `${NAME}: warm the note store`);
+	registerRoutes(ctx, store);
+	ctx.inject(["tools"], (scope) => {
+		for (const definition of createTools(store)) scope.effect(() => scope.tools.register(definition), `${NAME}: tool ${definition.name}`);
+	});
+}
+export { apply, createStore, name, resolveNotesFile };

package/llms.txt

@@ -0,0 +1,32 @@
+# dsh-quicknote
+
+> Capture a note from the DSH composer, keep it out of the way, and manage the list on one page.
+
+## Install
+
+    dsh plugin --profile <profile> add dsh-quicknote
+
+## Verify
+
+    dsh --profile <profile> --dump-config | grep -A2 "id: dsh-quicknote"
+
+## Develop
+
+    pnpm install
+    pnpm verify
+
+## Read next
+
+- README.md — user guide
+- AGENTS.md — repository rules and invariants
+- src/host/ — Host half
+- src/client/ — browser half
+- tests/ — both suites
+
+## Contracts
+
+- Package: dsh-quicknote
+- Patch row: `dsh-quicknote`
+- Client module id: `dsh-quicknote`
+- Storage: `~/.dsh/quicknote/notes.json`
+- Routes: `/api/quicknote/notes`, `/create`, `/update`, `/delete`, `/restore`

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Quick Note (dsh-quicknote)",
+    "description": "Capture a note, mark it done, keep the list on one page."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "随手记 (dsh-quicknote)",
+    "description": "记下一条笔记，标记完成，在一页里管理。"
+  }
+}

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "dsh-quicknote",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Capture a note from the DSH composer, keep it out of the way, and manage the list on one page.",
+  "license": "MIT",
+  "author": "dsh-kit contributors",
+  "type": "module",
+  "icon": "./icon.svg",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/",
+    "cordis.patch.yml",
+    "icon.svg",
+    "locale/*.json",
+    "README.md",
+    "README.zh.md",
+    "AGENTS.md",
+    "llms.txt",
+    "LICENSE",
+    "CHANGELOG.md",
+    "PUBLISHING.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint src tests scripts",
+    "format": "oxfmt --check src tests scripts",
+    "format:write": "oxfmt src tests scripts",
+    "test": "vitest run",
+    "verify": "oxfmt --check src tests scripts && oxlint src tests scripts && tsc --noEmit && vitest run && tsdown && node scripts/check.mjs && npm pack --dry-run",
+    "prepack": "tsdown"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    },
+    "engines": {
+      "dsh": ">=0.2.1-rc.5"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "@types/react": "^19.3.0",
+    "jsdom": "^30.1.3",
+    "oxfmt": "^0.75.0",
+    "oxlint": "^1.90.0",
+    "react": "^19.3.1",
+    "tsdown": "^0.23.4",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "quicknote",
+    "notes"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dsh-kit/dsh-quicknote.git"
+  },
+  "homepage": "https://dsh-kit.github.io/dsh-quicknote/",
+  "bugs": {
+    "url": "https://github.com/dsh-kit/dsh-quicknote/issues"
+  }
+}