@skillre/dsh-plugin-sticky-wall 0.0.0-stage → 0.2.2

package/lib/transport.js

@@ -0,0 +1,174 @@
+/**
+ * Host ↔ Client transport: one exact Fetch route inside Connection's fence.
+ *
+ * Connection owns the Host/Origin check, the browser-session authentication and
+ * the Peer scope; this module registers one exact `POST /api/<endpoint>` route
+ * and only has to validate its own envelope and payload. No physical server, no
+ * Express, and no second RPC channel is claimed.
+ *
+ * The wire envelope is the inspected Connection unary shape:
+ * `{ type: 'client-request', rpcId, method, payload }` in and
+ * `{ type: 'server-response', rpcId, result: { ok: true, value } | { ok: false, error } }`
+ * out. A non-owner Peer is rejected by Connection before this handler runs.
+ */
+import { z } from 'zod';
+import { WallError } from './store.js';
+import { COLORS, ENDPOINT, LIMITS, SORTS, WIDTHS, } from './types.js';
+/** Path of the exact route, under the shared `/api` channel. */
+export const EXECUTE_PATH = `/api/${ENDPOINT}`;
+const envelopeSchema = z.object({
+    type: z.literal('client-request'),
+    rpcId: z.string(),
+    method: z.string(),
+    payload: z.unknown(),
+});
+const colorSchema = z.enum(COLORS);
+const sortSchema = z.enum(SORTS);
+const idSchema = z.string().min(1).max(128);
+const idsSchema = z.array(idSchema).min(1).max(LIMITS.bulk);
+/** One card placement; only the shape is validated here.
+ *
+ * The bounds are deliberately NOT enforced with `.min/.max`: a user who drags a
+ * card past the world edge should get a clamped position, not an error toast.
+ * The store clamps with `clampLayout`, which is the single place the policy
+ * lives; rejecting here made that clamp unreachable over RPC. Non-finite values
+ * are still refused, because there is no sensible clamp for NaN or Infinity.
+ */
+const layoutSchema = z
+    .object({
+    x: z.number().finite(),
+    y: z.number().finite(),
+    rotate: z.number().finite(),
+    width: z.enum(WIDTHS),
+})
+    .strict();
+const requestSchema = z.discriminatedUnion('action', [
+    z.object({ action: z.literal('list'), includeArchived: z.boolean().optional(), sort: sortSchema.optional() }).strict(),
+    z
+        .object({
+        action: z.literal('create'),
+        note: z
+            .object({
+            body: z.string().min(1).max(LIMITS.body),
+            title: z.string().max(LIMITS.title).optional(),
+            tags: z.array(z.string().max(LIMITS.tag)).max(LIMITS.tags).optional(),
+            color: colorSchema.optional(),
+            pinned: z.boolean().optional(),
+            layout: layoutSchema.nullable().optional(),
+        })
+            .strict(),
+    })
+        .strict(),
+    z
+        .object({
+        action: z.literal('update'),
+        id: idSchema,
+        patch: z
+            .object({
+            body: z.string().min(1).max(LIMITS.body).optional(),
+            title: z.string().max(LIMITS.title).optional(),
+            tags: z.array(z.string().max(LIMITS.tag)).max(LIMITS.tags).optional(),
+            color: colorSchema.optional(),
+            pinned: z.boolean().optional(),
+            archived: z.boolean().optional(),
+        })
+            .strict(),
+    })
+        .strict(),
+    z.object({ action: z.literal('archive'), ids: idsSchema, archived: z.boolean() }).strict(),
+    z.object({ action: z.literal('delete'), ids: idsSchema }).strict(),
+    z.object({ action: z.literal('clear-archived') }).strict(),
+    z.object({ action: z.literal('move'), id: idSchema, layout: layoutSchema }).strict(),
+    z.object({ action: z.literal('arrange') }).strict(),
+]);
+/** A JSON response with no-store caching; the wall is always live state. */
+function json(body, status = 200) {
+    return Response.json(body, { status, headers: { 'cache-control': 'no-store' } });
+}
+/** One server-response success envelope. */
+function success(rpcId, value) {
+    return json({ type: 'server-response', rpcId, result: { ok: true, value } });
+}
+/** One server-response failure envelope, using a stable plugin-owned code. */
+function failure(rpcId, code, message, details = {}) {
+    return json({ type: 'server-response', rpcId, result: { ok: false, error: { code: `sticky-wall/${code}`, message, details } } });
+}
+/** Recover the correlation id from any body shape so failures stay correlatable. */
+function correlation(body) {
+    return body !== null && typeof body === 'object' && 'rpcId' in body && typeof body.rpcId === 'string' ? body.rpcId : 'invalid-request';
+}
+/** Dispatch one validated request onto the store. */
+async function dispatch(actions, request) {
+    switch (request.action) {
+        case 'list':
+            return { notes: actions.list(request.includeArchived, request.sort) };
+        case 'create':
+            return { action: 'create', changed: [await actions.create(request.note)], removed: [] };
+        case 'update':
+            return { action: 'update', changed: [await actions.update(request.id, request.patch)], removed: [] };
+        case 'archive':
+            return { action: 'archive', changed: await actions.setArchived(request.ids, request.archived), removed: [] };
+        case 'delete':
+            return { action: 'delete', changed: [], removed: await actions.remove(request.ids) };
+        case 'clear-archived':
+            return { action: 'clear-archived', changed: [], removed: await actions.clearArchived() };
+        case 'move':
+            return { action: 'move', changed: [await actions.move(request.id, request.layout)], removed: [] };
+        case 'arrange':
+            return { action: 'arrange', changed: await actions.arrange(), removed: [] };
+    }
+}
+/**
+ * Build the exact route Connection registers; every failure stays inside the
+ * envelope. `ready` resolves the store lazily so a storage-open failure is
+ * reported on the first request instead of at registration time.
+ */
+export function createExecuteRoute(ready) {
+    return {
+        path: EXECUTE_PATH,
+        methods: ['POST'],
+        requestBody: 'buffered',
+        async fetch(request) {
+            if (request.method !== 'POST' || new URL(request.url).pathname !== EXECUTE_PATH)
+                return new Response('not found', { status: 404 });
+            const contentType = request.headers.get('content-type')?.split(';', 1)[0]?.trim().toLowerCase();
+            if (contentType !== 'application/json')
+                return new Response('content type must be application/json', { status: 415 });
+            let body;
+            try {
+                body = await request.json();
+            }
+            catch {
+                if (request.signal.aborted)
+                    return failure(correlation(body), 'cancelled', 'The request was cancelled before dispatch.');
+                return new Response('body is not JSON', { status: 400 });
+            }
+            if (request.signal.aborted)
+                return failure(correlation(body), 'cancelled', 'The request was cancelled before dispatch.');
+            const envelope = envelopeSchema.safeParse(body);
+            if (!envelope.success)
+                return failure(correlation(body), 'bad-request', 'Invalid client-request message.');
+            const message = envelope.data;
+            if (message.method !== ENDPOINT)
+                return failure(message.rpcId, 'bad-request', 'RPC method does not match the sticky-wall endpoint.');
+            const parsed = requestSchema.safeParse(message.payload);
+            if (!parsed.success) {
+                const first = parsed.error.issues[0];
+                return failure(message.rpcId, 'bad-request', first?.message ?? 'Invalid sticky-wall request.', { issues: parsed.error.issues.slice(0, 4) });
+            }
+            try {
+                request.signal.throwIfAborted();
+                return success(message.rpcId, await dispatch(await ready(), parsed.data));
+            }
+            catch (error) {
+                // A WallError is authored for the user; anything else is a Host fault
+                // whose text must not become UI copy (and must not leak backend detail).
+                if (error instanceof WallError)
+                    return failure(correlation(body), error.code, error.message.slice(0, 2000), error.details);
+                if (request.signal.aborted)
+                    return failure(correlation(body), 'cancelled', 'The request was cancelled.');
+                return failure(correlation(body), 'internal', 'The note wall hit an internal error; check the Host log.');
+            }
+        },
+    };
+}

package/lib/types.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Wire and storage vocabulary shared by the Host and Client halves.
+ *
+ * Everything here is plain, lossless JSON: the Host and the Client live in
+ * different runtimes and only these shapes cross the Connection RPC boundary.
+ * Both halves are compiled from this file, so the Client bundle carries the
+ * same literals without importing Host code.
+ */
+/** RPC endpoint path under the shared `/api` channel. */
+export declare const ENDPOINT = "skillre-sticky-wall/execute";
+/** Sidebar panel id, main panel key, and locale namespace. */
+export declare const PANEL_ID = "skillre-sticky-wall";
+export declare const LOCALE_NAMESPACE = "skillreStickyWall";
+/** Storage domain name; the per-record layout gives one file per note. */
+export declare const DOMAIN_NAME = "skillre_sticky_wall";
+export declare const DOMAIN_VERSION = 1;
+/** Hard limits, enforced on both halves so a bad payload never reaches storage. */
+export declare const LIMITS: Readonly<{
+    /** One note's body, in characters. */
+    body: 4000;
+    /** One note's title, in characters. */
+    title: 120;
+    /** A note's free-form tag list. */
+    tags: 8;
+    /** One tag, in characters. */
+    tag: 32;
+    /** Live (non-archived) notes a wall may hold. */
+    notes: 400;
+    /** Note ids accepted in one request. */
+    bulk: 200;
+}>;
+/** Pastel note colors the wall offers; the Client renders them as literal hex. */
+export declare const COLORS: readonly ["yellow", "pink", "green", "blue", "purple", "orange"];
+export type NoteColor = (typeof COLORS)[number];
+/** Sort orders the wall exposes. */
+export declare const SORTS: readonly ["pinned", "created", "updated"];
+export type NoteSort = (typeof SORTS)[number];
+/**
+ * Card width presets.
+ *
+ * A free canvas looks dead when every card is the same width, so the wall keeps
+ * three sizes. They are presets rather than arbitrary pixels: the card's text
+ * metrics, the auto-arrange packing and the drag handles all assume a known
+ * width, and a preset keeps the stored layout small and legible.
+ */
+export declare const WIDTHS: readonly ["sm", "md", "lg"];
+export type NoteWidth = (typeof WIDTHS)[number];
+/** Rendered card width for each preset, in world pixels at zoom 1. */
+export declare const WIDTH_PX: Readonly<Record<NoteWidth, number>>;
+/** Bounds of the free canvas: a note may sit anywhere inside this square. */
+export declare const LAYOUT_LIMITS: Readonly<{
+    /** Absolute value of x and y, in world pixels. */
+    coord: 20000;
+    /** Absolute rotation, in degrees. */
+    rotate: 12;
+}>;
+/**
+ * Where one note sits on the free canvas.
+ *
+ * `null` on a note means "never placed": the Client derives a stable preview
+ * position from the note id so a wall written before the canvas existed still
+ * opens as a scattered wall instead of a single stack. Dragging or arranging
+ * writes a real layout, so the Host stays the only owner of the arrangement.
+ */
+export interface NoteLayout {
+    /** World x of the card's top-left corner, in pixels at zoom 1. */
+    x: number;
+    /** World y of the card's top-left corner, in pixels at zoom 1. */
+    y: number;
+    /** Rotation in degrees, clamped to {@link LAYOUT_LIMITS.rotate}. */
+    rotate: number;
+    /** Card width preset. */
+    width: NoteWidth;
+}
+/** One sticky note as stored and as sent over the wire. */
+export interface Note {
+    /** Stable id; `crypto.randomUUID()` for locally created notes. */
+    id: string;
+    /** Optional short heading; the body alone is enough for a quick capture. */
+    title: string;
+    /** The note text. Never empty for a live note. Markdown is rendered, not stored away. */
+    body: string;
+    /** Normalized lowercase tags, deduplicated, at most {@link LIMITS.tags}. */
+    tags: string[];
+    /** Pastel key from {@link COLORS}. */
+    color: NoteColor;
+    /** Pinned notes sort first and survive `archive` sweeps. */
+    pinned: boolean;
+    /** Archived notes are kept but hidden by the default wall. */
+    archived: boolean;
+    /** ISO-8601 creation time. */
+    createdAt: string;
+    /** ISO-8601 last-write time. Moving a card does not bump this. */
+    updatedAt: string;
+    /** Free-canvas placement, or `null` for a note the user never positioned. */
+    layout: NoteLayout | null;
+}
+/** The complete wall state a Client renders. */
+export interface WallSnapshot {
+    notes: Note[];
+    /** Schema marker so a Client never renders an unknown future shape. */
+    domain: {
+        name: string;
+        version: number;
+    };
+}
+/** Request kinds accepted by the Host endpoint. */
+export type WallRequest = {
+    action: 'list';
+    includeArchived?: boolean;
+    sort?: NoteSort;
+} | {
+    action: 'create';
+    note: NoteInput;
+} | {
+    action: 'update';
+    id: string;
+    patch: NotePatch;
+} | {
+    action: 'archive';
+    ids: string[];
+    archived: boolean;
+} | {
+    action: 'delete';
+    ids: string[];
+} | {
+    action: 'clear-archived';
+} | {
+    action: 'move';
+    id: string;
+    layout: NoteLayout;
+} | {
+    action: 'arrange';
+};
+/** The fields a Client may submit when creating a note. */
+export interface NoteInput {
+    body: string;
+    title?: string;
+    tags?: string[];
+    color?: NoteColor;
+    pinned?: boolean;
+    layout?: NoteLayout | null;
+}
+/** The fields a Client may change on an existing note. */
+export interface NotePatch {
+    body?: string;
+    title?: string;
+    tags?: string[];
+    color?: NoteColor;
+    pinned?: boolean;
+    archived?: boolean;
+}
+/** One endpoint outcome, mirroring the Connection RPC result envelope. */
+export type WallResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        details: Record<string, unknown>;
+    };
+};
+/** Result of one mutation, echoed back so the Client can reconcile in place. */
+export interface MutationResult {
+    action: string;
+    /** Every note the mutation created or changed, in its post-write state. */
+    changed: Note[];
+    /** Ids the mutation removed. */
+    removed: string[];
+}

package/lib/types.js

@@ -0,0 +1,64 @@
+/**
+ * Wire and storage vocabulary shared by the Host and Client halves.
+ *
+ * Everything here is plain, lossless JSON: the Host and the Client live in
+ * different runtimes and only these shapes cross the Connection RPC boundary.
+ * Both halves are compiled from this file, so the Client bundle carries the
+ * same literals without importing Host code.
+ */
+/** RPC endpoint path under the shared `/api` channel. */
+export const ENDPOINT = 'skillre-sticky-wall/execute';
+/** Sidebar panel id, main panel key, and locale namespace. */
+export const PANEL_ID = 'skillre-sticky-wall';
+export const LOCALE_NAMESPACE = 'skillreStickyWall';
+/** Storage domain name; the per-record layout gives one file per note. */
+export const DOMAIN_NAME = 'skillre_sticky_wall';
+export const DOMAIN_VERSION = 1;
+/** Hard limits, enforced on both halves so a bad payload never reaches storage. */
+export const LIMITS = Object.freeze({
+    /** One note's body, in characters. */
+    body: 4000,
+    /** One note's title, in characters. */
+    title: 120,
+    /** A note's free-form tag list. */
+    tags: 8,
+    /** One tag, in characters. */
+    tag: 32,
+    /** Live (non-archived) notes a wall may hold. */
+    notes: 400,
+    /** Note ids accepted in one request. */
+    bulk: 200,
+});
+/** Pastel note colors the wall offers; the Client renders them as literal hex. */
+export const COLORS = Object.freeze([
+    'yellow',
+    'pink',
+    'green',
+    'blue',
+    'purple',
+    'orange',
+]);
+/** Sort orders the wall exposes. */
+export const SORTS = Object.freeze(['pinned', 'created', 'updated']);
+/**
+ * Card width presets.
+ *
+ * A free canvas looks dead when every card is the same width, so the wall keeps
+ * three sizes. They are presets rather than arbitrary pixels: the card's text
+ * metrics, the auto-arrange packing and the drag handles all assume a known
+ * width, and a preset keeps the stored layout small and legible.
+ */
+export const WIDTHS = Object.freeze(['sm', 'md', 'lg']);
+/** Rendered card width for each preset, in world pixels at zoom 1. */
+export const WIDTH_PX = Object.freeze({
+    sm: 178,
+    md: 222,
+    lg: 276,
+});
+/** Bounds of the free canvas: a note may sit anywhere inside this square. */
+export const LAYOUT_LIMITS = Object.freeze({
+    /** Absolute value of x and y, in world pixels. */
+    coord: 20_000,
+    /** Absolute rotation, in degrees. */
+    rotate: 12,
+});

package/locale/en.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "Sticky Wall",
+    "description": "A free-canvas note board in the DSH sidebar: drag cards into place, tidy them, and write Markdown.",
+    "detail": "docs/DETAIL.md"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "便签墙",
+    "description": "DSH 侧栏便签墙：随手记灵感与临时工作，拖动摆放、自动整理，正文支持 Markdown。",
+    "detail": "docs/DETAIL.zh.md"
+  }
+}

package/package.json

@@ -1,6 +1,118 @@
 {
   "name": "@skillre/dsh-plugin-sticky-wall",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.2",
+  "description": "便签墙：DSH 侧栏的自由画布便签板，可拖动摆放、一键整理，正文按 Markdown 渲染",
+  "icon": "./icon.svg",
+  "type": "module",
+  "license": "MIT",
+  "author": "skillre",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0",
+    "dsh": ">=0.2.2-rc.1 <0.3.0"
+  },
+  "packageManager": "npm@11.12.1",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./compatibility.json": "./compatibility.json",
+    "./locale/*.json": "./locale/*.json",
+    "./package.json": "./package.json",
+    "./client": {
+      "browser": "./lib/client.js",
+      "default": "./lib/client.js"
+    }
+  },
+  "files": [
+    "lib/",
+    "cordis.patch.yml",
+    "compatibility.json",
+    "locale/*.json",
+    "icon.svg",
+    "docs/DETAIL.md",
+    "docs/DETAIL.zh.md",
+    "docs/preview.svg",
+    "docs/preview.zh.svg",
+    "docs/PREVIEW.md",
+    "README.md",
+    "README.en.md",
+    "UNINSTALL.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/skillre/dsh-plugin-sticky-wall.git"
+  },
+  "bugs": {
+    "url": "https://github.com/skillre/dsh-plugin-sticky-wall/issues"
+  },
+  "homepage": "https://github.com/skillre/dsh-plugin-sticky-wall#readme",
+  "keywords": [
+    "deepseek-harness",
+    "dsh-plugin",
+    "cordis",
+    "sticky-notes",
+    "notes",
+    "便签"
+  ],
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-connection"
+      ]
+    }
+  },
+  "scripts": {
+    "clean": "node scripts/clean.mjs",
+    "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/build-client.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "test": "npm run build:client && vitest run",
+    "pack:check": "npm run build && publint && npm pack --dry-run --json --ignore-scripts",
+    "check": "npm run preview:check && npm run typecheck && npm test && npm run check:lib && npm run pack:check",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release:prepare": "node scripts/prepare-release.mjs",
+    "prepack": "npm run build",
+    "build:client": "node scripts/build-client.mjs",
+    "test:integration": "node scripts/verify-isolated.mjs",
+    "test:market": "node scripts/verify-market-install.mjs",
+    "check:lib": "npm run build && node scripts/verify-lib-committed.mjs",
+    "preview:check": "node scripts/preview.mjs check"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.1.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^3.0.2",
+    "@deepseek-ai/cordis": "4.1.0",
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^24.13.3",
+    "@types/react": "~18.3.31",
+    "esbuild": "^0.25.0",
+    "jsdom": "^25.0.1",
+    "publint": "^0.3.24",
+    "react": "18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.8"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.19.0",
+    "zod": "^4.6.7"
+  }
+}