dsh-checklists 0.0.0-stage → 0.3.2

package/lib/types/model.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Pure data model for session-scoped checklists.
+ *
+ * Nothing in this module imports a DSH package: the tree shape, the id
+ * allocation, and the reference resolver are unit-testable without a running
+ * harness.
+ */
+export type ItemState = 'todo' | 'doing' | 'done' | 'blocked';
+export declare const ITEM_STATES: readonly ItemState[];
+export interface ChecklistItem {
+    id: string;
+    text: string;
+    state: ItemState;
+    children: ChecklistItem[];
+}
+export interface Checklist {
+    id: string;
+    title: string;
+    createdAt: string;
+    items: ChecklistItem[];
+}
+export interface SessionDoc {
+    version: 1;
+    sessionId: string;
+    lists: Checklist[];
+}
+export declare function emptyDoc(sessionId: string): SessionDoc;
+/** Mint the next `<prefix>N` identifier that is not already in `used`. */
+export declare function mintId(prefix: string, used: ReadonlySet<string>): string;
+/**
+ * Build an item tree from plain lines.
+ *
+ * A line indented with two leading spaces per level nests under the previous
+ * shallower line. This is the format the model writes, and the format
+ * {@link toLines} round-trips.
+ *
+ * @param lines - item texts, optionally indented.
+ * @param used - id set to extend; pass the ids already present when appending
+ *   to an existing checklist, or ids will collide.
+ * @returns the root items, with ids assigned depth-first.
+ */
+export declare function buildItems(lines: readonly string[], used?: Set<string>): ChecklistItem[];
+/** Render an item tree back to indented lines (inverse of {@link buildItems}). */
+export declare function toLines(items: readonly ChecklistItem[], depth?: number): string[];
+export interface FlatItem {
+    item: ChecklistItem;
+    depth: number;
+}
+/** Depth-first flattening, carrying each item's nesting depth. */
+export declare function flatten(items: readonly ChecklistItem[], depth?: number): FlatItem[];
+export interface ItemCounts {
+    total: number;
+    done: number;
+}
+export declare function countItems(items: readonly ChecklistItem[]): ItemCounts;
+export interface RefHit {
+    list: Checklist;
+    item: ChecklistItem;
+}
+export type RefResult = {
+    kind: 'hit';
+    hit: RefHit;
+} | {
+    kind: 'ambiguous';
+    candidates: RefHit[];
+} | {
+    kind: 'miss';
+};
+/**
+ * Resolve one model-supplied reference against the session's checklists.
+ *
+ * Resolution order: exact id, exact case-insensitive text, unique
+ * case-insensitive prefix. Ambiguity is surfaced rather than guessed: the
+ * model can then pass a list id or the full text.
+ *
+ * @param lists - the session's checklists.
+ * @param ref - a model-supplied item id, text, or prefix.
+ * @param listId - optional checklist id to search within.
+ * @returns the hit, the ambiguity, or a miss.
+ */
+export declare function resolveRef(lists: readonly Checklist[], ref: string, listId?: string): RefResult;
+/** Whether a value is a valid item state. */
+export declare function isItemState(value: unknown): value is ItemState;
+/**
+ * Find a checklist by id or by exact case-insensitive title.
+ *
+ * Ids are what the tools hand out, but a model that just created "Release 2.3"
+ * will often pass the title back; accepting both avoids a pointless round trip.
+ *
+ * @param lists - the session's checklists.
+ * @param ref - a checklist id or its exact title.
+ * @returns the matching checklist, or `undefined`.
+ */
+export declare function findList(lists: readonly Checklist[], ref: string): Checklist | undefined;
+/** Find one item by exact id across every list. */
+export declare function findItemById(lists: readonly Checklist[], id: string): {
+    list: Checklist;
+    item: ChecklistItem;
+} | undefined;
+export interface NextItem {
+    list: Checklist;
+    item: ChecklistItem;
+    /** Ancestor texts, outermost first; empty for a top-level item. */
+    path: string[];
+}
+export interface NextResult {
+    next?: NextItem;
+    /** Items that are not done, across the searched scope. */
+    remaining: number;
+    /** Items currently blocked (their subtrees are skipped). */
+    blocked: number;
+}
+/**
+ * The next item to work on, in depth-first order.
+ *
+ * Rules, in the order they are applied:
+ * - A `done` subtree is skipped entirely.
+ * - A `blocked` subtree is skipped (and counted).
+ * - An item with open children is a container: descend and return its first
+ *   actionable leaf. A section header is never "the next thing to do".
+ * - A leaf is returned as-is.
+ *
+ * @param lists - the checklists to search.
+ * @param listId - optional checklist id to scope the search.
+ * @returns the next item (if any) plus the remaining and blocked counts.
+ */
+export declare function nextItem(lists: readonly Checklist[], listId?: string): NextResult;

package/lib/types/probe.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Client diagnostics channel.
+ *
+ * The client half runs in a browser we cannot attach a debugger to from here.
+ * This endpoint lets it report its own load/registration stages to the host, so
+ * "the tab is not there" can be told apart from "the module never loaded".
+ *
+ * In-memory and bounded: it answers one question and dies with the process.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare const PROBE_ROUTE = "/dsh-checklist/client-probe";
+export interface ProbeReport {
+    at: string;
+    stage: string;
+    detail: string;
+}
+export declare function serveProbe(req: IncomingMessage, res: ServerResponse): void;

package/lib/types/route.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Read-only HTTP endpoint for the sidebar.
+ *
+ * Same-origin, GET only, one query parameter. The store validates the session
+ * id (it becomes a file name), so a crafted `session` cannot escape the storage
+ * directory; anything invalid answers 400 rather than throwing.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { ChecklistStore } from './store.js';
+export declare const STATE_ROUTE = "/dsh-checklist/state";
+export declare const ITEM_ROUTE = "/dsh-checklist/item";
+/**
+ * Serve one session's checklist state.
+ *
+ * @param req - the incoming request.
+ * @param res - the response to write.
+ * @param store - the session store.
+ */
+export declare function serveState(req: IncomingMessage, res: ServerResponse, store: ChecklistStore): Promise<void>;
+/**
+ * Apply one text edit from the sidebar.
+ *
+ * This is the only write path outside the agent, so it is deliberately narrow:
+ * one item, by exact id, with an optional `expectedText` guard. When the guard
+ * does not match, the answer is 409 rather than a silent overwrite — the client
+ * re-reads and the user retries.
+ *
+ * @param req - the incoming request; must be POST.
+ * @param res - the response to write.
+ * @param store - the session store.
+ */
+export declare function serveItemUpdate(req: IncomingMessage, res: ServerResponse, store: ChecklistStore): Promise<void>;

package/lib/types/state.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The public JSON shape the sidebar reads.
+ *
+ * Deliberately separate from the stored document: the client gets no `version`
+ * field, no future internals, and nothing it could mistake for a write channel.
+ */
+import { type SessionDoc } from './model.js';
+export interface PublicItem {
+    id: string;
+    text: string;
+    state: string;
+    children: PublicItem[];
+}
+export interface PublicList {
+    id: string;
+    title: string;
+    createdAt: string;
+    items: PublicItem[];
+}
+export interface PublicCounts {
+    lists: number;
+    total: number;
+    done: number;
+}
+export interface PublicState {
+    sessionId: string;
+    lists: PublicList[];
+    counts: PublicCounts;
+}
+export declare function toPublicState(doc: SessionDoc): PublicState;

package/lib/types/store.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Durable per-session checklist storage.
+ *
+ * Layout under the DSH home directory:
+ *
+ *   $DSH_HOME/storages/dsh-checklist/
+ *   ├─ sessions/<sessionId>.json   one document per session
+ *   └─ templates.json              reusable, cross-session templates
+ *
+ * The store keeps an in-process cache because the system-prompt digest is
+ * rendered synchronously, while disk access is not. Writes are serialized per
+ * session and land atomically (temp file + rename), so two concurrent tool
+ * calls cannot interleave into a torn document.
+ */
+import { type SessionDoc } from './model.js';
+/** Resolve the DSH home directory (env override wins). */
+export declare function resolveDshHome(env?: NodeJS.ProcessEnv): string;
+export declare class ChecklistStore {
+    readonly root: string;
+    private readonly cache;
+    private readonly chains;
+    private readonly inflight;
+    constructor(root?: string);
+    /** The synchronous view used by the prompt digest; `undefined` until primed. */
+    peek(sessionId: string): SessionDoc | undefined;
+    /** Load one session (cache first, then disk). */
+    prime(sessionId: string): Promise<SessionDoc>;
+    /**
+     * Apply one mutation to a session and persist it.
+     *
+     * The mutator receives a fresh clone, so a throw leaves the cached document
+     * untouched. Calls for one session are serialized.
+     */
+    update<T>(sessionId: string, mutate: (doc: SessionDoc) => T | Promise<T>): Promise<T>;
+    readTemplates(): Promise<Record<string, string[]>>;
+    writeTemplates(templates: Record<string, string[]>): Promise<void>;
+    /** Delete session files untouched for `maxAgeDays`. Returns the count removed. */
+    prune(maxAgeDays: number): Promise<number>;
+    private templatesFile;
+    private fileFor;
+    private read;
+    private write;
+}

package/lib/types/tools.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The write surface: five tools the agent uses to keep the checklist current.
+ *
+ * Only the agent writes. There is no client write path, so the host document is
+ * the single source of truth and the sidebar (phase 2) is a read-only mirror.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ChecklistStore } from './store.js';
+export interface ToolsConfig {
+    maxItemsPerList?: number;
+    templates?: Record<string, string[]>;
+}
+export declare function registerChecklistTools(ctx: Context, store: ChecklistStore, config?: ToolsConfig): void;

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "dsh-checklists",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.2",
+  "description": "Session-scoped checklists for DeepSeek Harness: the agent tracks work as a tree, the model always sees a compact digest, and a read-only sidebar tab mirrors it.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./client/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "client",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "license": "MIT",
+  "author": "manny333",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manny333/dsh-checklists.git"
+  },
+  "homepage": "https://github.com/manny333/dsh-checklists#readme",
+  "bugs": {
+    "url": "https://github.com/manny333/dsh-checklists/issues"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "checklist",
+    "cordis",
+    "agent"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-sidebar-right"
+      ]
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "test": "vitest run",
+    "smoke": "node scripts/smoke.mjs",
+    "prepack": "npm run build",
+    "check": "npm run typecheck && npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-host-webserver": ">=0.1.0-rc.1 <0.3.0",
+    "@deepseek-ai/dsh-system-prompt": ">=0.1.0-rc.1 <0.3.0",
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.1 <0.3.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.7-rc.2",
+    "@types/node": "^22.20.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0"
+  }
+}