sidebar-md 0.1.0

package/dist/server/mention-ops.d.ts

@@ -0,0 +1,115 @@
+import { type Mention, type ParseError } from "../shared/markers.js";
+import type { Workspace } from "./workspace.js";
+export type FileMention = Mention & {
+    /** Workspace-relative POSIX path of the file the marker lives in. */
+    file: string;
+    /** ISO timestamp the mention was first observed at runtime. */
+    created_at: string;
+};
+export type MentionCreatedAtMap = Map<string, string>;
+export type ListPendingResult = {
+    mentions: FileMention[];
+    /** Files we attempted to parse, with per-file malformed-marker error counts. */
+    malformedByFile: Map<string, ParseError[]>;
+};
+/**
+ * Walk every file in the workspace glob, parse the markers, and return all
+ * well-formed mentions across files. Malformed markers are skipped from the
+ * returned mentions but their errors are returned per-file so callers can
+ * surface "one stderr warning per file" (spec: Failure Modes / Malformed
+ * markers).
+ *
+ * `firstSeenAt` maps mention id -> ISO timestamp; the caller (the server's
+ * mention-tracker) supplies it so re-scans don't reset created_at.
+ */
+export declare function listMentions(ws: Workspace, firstSeenAt: MentionCreatedAtMap, now?: () => Date): Promise<ListPendingResult>;
+export declare function findMention(ws: Workspace, mentionId: string, firstSeenAt: MentionCreatedAtMap): Promise<FileMention | null>;
+export type CreateMentionInput = {
+    path: string;
+    /** UTF-16 char offset where the target region begins (inclusive). */
+    startOffset: number;
+    /** UTF-16 char offset where the target region ends (exclusive). */
+    endOffset: number;
+    verb: string;
+    instruction: string;
+    /** Resolved human author (caller passes the already-resolved value). */
+    author: string;
+};
+export type CreateMentionResult = {
+    mention: {
+        id: string;
+        file: string;
+        verb: string;
+        author: string;
+        instruction: string;
+        targetContent: string;
+        baseHash: string;
+    };
+    /** The new file content (returned so the caller can broadcast it). */
+    newContent: string;
+    diskHash: string;
+};
+/**
+ * Wrap the target region in a begin/end pair and write the new file to disk.
+ * The id is generated server-side (ADR-0003: the agent never invents an id;
+ * the same rule applies to the editor — the parser-resident state is the
+ * only source of truth for ids).
+ */
+export declare function createMention(ws: Workspace, input: CreateMentionInput): Promise<CreateMentionResult>;
+export type ResolveAction = {
+    type: "replace";
+    content: string;
+} | {
+    type: "annotation";
+    annotation_type: "note" | "suggestion";
+    text: string;
+};
+export type ResolveResult = {
+    kind: "ok";
+    newContent: string;
+} | {
+    kind: "conflict";
+    current_base_hash: string;
+} | {
+    kind: "not-found";
+} | {
+    kind: "orphaned";
+} | {
+    kind: "verb-not-replaceable";
+    verb: string;
+};
+/**
+ * Resolve a mention. Honors ADR-0002: the begin/end pair disappears.
+ *
+ *  - replace: the entire begin/end pair plus the target region is replaced by
+ *    the agent's content. Authorization scope is exactly this region.
+ *  - annotation (note): the mention markers go; the original target prose
+ *    stays in place; a new note annotation wraps that target.
+ *
+ * The caller is responsible for verb-policy enforcement (replace requires the
+ * verb's catalog entry to be in "replace" mode; unknown or "annotation"-mode
+ * verbs are restricted to annotation actions only).
+ */
+export declare function resolveMention(ws: Workspace, mentionId: string, action: ResolveAction, agentBaseHash: string, options: {
+    verbMode: "replace" | "annotation" | "unknown";
+    annotationAuthor: string;
+    firstSeenAt: MentionCreatedAtMap;
+}): Promise<ResolveResult>;
+/**
+ * Cancel an open mention from the editor (right-click "cancel mention"
+ * action). The begin/end pair is removed; the target content stays.
+ */
+export declare function cancelMention(ws: Workspace, mentionId: string, firstSeenAt: MentionCreatedAtMap): Promise<{
+    kind: "ok";
+    newContent: string;
+    file: string;
+} | {
+    kind: "not-found";
+}>;
+/**
+ * Emit one stderr warning per file that has malformed markers (spec: Failure
+ * Modes / Malformed markers — "one warning per affected file, not per
+ * marker"). Used by the listMentions consumer; held here so the wording is
+ * shared across MCP and editor entry points.
+ */
+export declare function warnOnceForMalformed(malformedByFile: Map<string, ParseError[]>): void;

package/dist/server/mention-ops.js

@@ -0,0 +1,202 @@
+import { existsSync, statSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import fastGlob from "fast-glob";
+import { computeMentionBaseHash, formatAnnotationBegin, formatAnnotationEnd, formatMentionBegin, formatMentionEnd, parseMarkers, sanitizeAttribute, } from "../shared/markers.js";
+import { generateMentionId, generateNoteId } from "./marker-ids.js";
+import { resolveHumanAuthor } from "./author.js";
+import { log } from "./log.js";
+const SCAN_IGNORE = ["**/.git/**", "**/node_modules/**", "**/dist/**", "**/.sidebar/**"];
+/**
+ * Walk every file in the workspace glob, parse the markers, and return all
+ * well-formed mentions across files. Malformed markers are skipped from the
+ * returned mentions but their errors are returned per-file so callers can
+ * surface "one stderr warning per file" (spec: Failure Modes / Malformed
+ * markers).
+ *
+ * `firstSeenAt` maps mention id -> ISO timestamp; the caller (the server's
+ * mention-tracker) supplies it so re-scans don't reset created_at.
+ */
+export async function listMentions(ws, firstSeenAt, now = () => new Date()) {
+    const files = await fastGlob(ws.innerGlob, {
+        cwd: ws.root,
+        onlyFiles: true,
+        dot: false,
+        followSymbolicLinks: false,
+        ignore: SCAN_IGNORE,
+    });
+    files.sort();
+    const out = [];
+    const malformedByFile = new Map();
+    for (const rel of files) {
+        let text;
+        try {
+            text = await readFile(ws.toAbs(rel), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const parsed = parseMarkers(text);
+        if (parsed.errors.length > 0)
+            malformedByFile.set(rel, parsed.errors);
+        for (const m of parsed.mentions) {
+            let createdAt = firstSeenAt.get(m.id);
+            if (!createdAt) {
+                createdAt = now().toISOString();
+                firstSeenAt.set(m.id, createdAt);
+            }
+            out.push({ ...m, file: rel, created_at: createdAt });
+        }
+    }
+    return { mentions: out, malformedByFile };
+}
+export async function findMention(ws, mentionId, firstSeenAt) {
+    const result = await listMentions(ws, firstSeenAt);
+    return result.mentions.find((m) => m.id === mentionId) ?? null;
+}
+/**
+ * Wrap the target region in a begin/end pair and write the new file to disk.
+ * The id is generated server-side (ADR-0003: the agent never invents an id;
+ * the same rule applies to the editor — the parser-resident state is the
+ * only source of truth for ids).
+ */
+export async function createMention(ws, input) {
+    const abs = ws.toAbs(input.path);
+    const original = await readFile(abs, "utf8");
+    if (input.startOffset < 0 ||
+        input.endOffset > original.length ||
+        input.startOffset > input.endOffset) {
+        throw new Error(`createMention: invalid offsets [${input.startOffset}, ${input.endOffset}] for file length ${original.length}`);
+    }
+    const before = original.slice(0, input.startOffset);
+    const target = original.slice(input.startOffset, input.endOffset);
+    const after = original.slice(input.endOffset);
+    // Mention markers occupy full lines. Insert a newline before the begin
+    // marker if the cut isn't at a line boundary, and after the end marker
+    // if the cut isn't at the start of a line.
+    const beginPrefix = before.length > 0 && !before.endsWith("\n") ? "\n" : "";
+    const endSuffix = after.length > 0 && !after.startsWith("\n") ? "\n" : "";
+    // The target region itself should end in a newline so the end marker sits
+    // on its own line; if the user selected a partial line, normalize.
+    const normalizedTarget = target.length === 0 || target.endsWith("\n") ? target : `${target}\n`;
+    const id = generateMentionId();
+    const begin = formatMentionBegin({
+        id,
+        verb: input.verb,
+        origin: "human",
+        author: input.author,
+        instruction: input.instruction,
+    });
+    const end = formatMentionEnd(id);
+    const newContent = `${before}${beginPrefix}${begin}\n${normalizedTarget}${end}${endSuffix}${after}`;
+    await writeFile(abs, newContent, "utf8");
+    return {
+        mention: {
+            id,
+            file: input.path,
+            verb: input.verb,
+            author: sanitizeAttribute(input.author),
+            instruction: input.instruction,
+            targetContent: normalizedTarget,
+            baseHash: computeMentionBaseHash(normalizedTarget),
+        },
+        newContent,
+        diskHash: "",
+    };
+}
+/**
+ * Resolve a mention. Honors ADR-0002: the begin/end pair disappears.
+ *
+ *  - replace: the entire begin/end pair plus the target region is replaced by
+ *    the agent's content. Authorization scope is exactly this region.
+ *  - annotation (note): the mention markers go; the original target prose
+ *    stays in place; a new note annotation wraps that target.
+ *
+ * The caller is responsible for verb-policy enforcement (replace requires the
+ * verb's catalog entry to be in "replace" mode; unknown or "annotation"-mode
+ * verbs are restricted to annotation actions only).
+ */
+export async function resolveMention(ws, mentionId, action, agentBaseHash, options) {
+    // Re-scan to find the mention. We need a fresh parse so we can refuse on
+    // base_hash mismatch.
+    const result = await listMentions(ws, options.firstSeenAt);
+    const target = result.mentions.find((m) => m.id === mentionId);
+    if (!target)
+        return { kind: "not-found" };
+    if (target.orphan)
+        return { kind: "orphaned" };
+    if (target.baseHash !== agentBaseHash) {
+        return { kind: "conflict", current_base_hash: target.baseHash };
+    }
+    if (action.type === "replace") {
+        if (options.verbMode !== "replace") {
+            return { kind: "verb-not-replaceable", verb: target.verb };
+        }
+        const abs = ws.toAbs(target.file);
+        const original = await readFile(abs, "utf8");
+        const replacement = ensureTrailingNewline(action.content);
+        const newContent = original.slice(0, target.beginLineStart) + replacement + original.slice(target.endLineEnd);
+        await writeFile(abs, newContent, "utf8");
+        return { kind: "ok", newContent };
+    }
+    // Annotation resolution. Only the `note` flavor is reachable here; the
+    // MCP layer rejects `suggestion` before we run (slice 5 contract). The
+    // mention markers are stripped; the original target content stays; a fresh
+    // note annotation pair wraps the same region.
+    if (action.annotation_type !== "note") {
+        return { kind: "verb-not-replaceable", verb: target.verb };
+    }
+    const noteId = generateNoteId();
+    const noteBegin = formatAnnotationBegin({
+        type: "note",
+        id: noteId,
+        author: options.annotationAuthor,
+        instruction: action.text,
+    });
+    const noteEnd = formatAnnotationEnd(noteId);
+    const abs = ws.toAbs(target.file);
+    const original = await readFile(abs, "utf8");
+    const replacement = `${noteBegin}\n${target.targetContent}${noteEnd}\n`;
+    const newContent = original.slice(0, target.beginLineStart) + replacement + original.slice(target.endLineEnd);
+    await writeFile(abs, newContent, "utf8");
+    return { kind: "ok", newContent };
+}
+/**
+ * Cancel an open mention from the editor (right-click "cancel mention"
+ * action). The begin/end pair is removed; the target content stays.
+ */
+export async function cancelMention(ws, mentionId, firstSeenAt) {
+    const result = await listMentions(ws, firstSeenAt);
+    const target = result.mentions.find((m) => m.id === mentionId);
+    if (!target)
+        return { kind: "not-found" };
+    const abs = ws.toAbs(target.file);
+    const original = await readFile(abs, "utf8");
+    const newContent = original.slice(0, target.beginLineStart) +
+        target.targetContent +
+        original.slice(target.endLineEnd);
+    await writeFile(abs, newContent, "utf8");
+    return { kind: "ok", newContent, file: target.file };
+}
+function ensureTrailingNewline(s) {
+    return s.endsWith("\n") ? s : `${s}\n`;
+}
+/**
+ * Emit one stderr warning per file that has malformed markers (spec: Failure
+ * Modes / Malformed markers — "one warning per affected file, not per
+ * marker"). Used by the listMentions consumer; held here so the wording is
+ * shared across MCP and editor entry points.
+ */
+export function warnOnceForMalformed(malformedByFile) {
+    for (const [file, errors] of malformedByFile) {
+        const kinds = Array.from(new Set(errors.map((e) => e.kind))).join(",");
+        log.warn(`malformed sidebar markers in ${file} (${errors.length} defect(s): ${kinds})`);
+    }
+}
+// `existsSync` / `statSync` aren't used here but the editor's CodeMirror
+// integration imports them transitively via @codemirror modules. Re-export
+// nothing; this comment exists to flag the dependency awareness for future
+// maintainers.
+void existsSync;
+void statSync;
+void resolveHumanAuthor;
+//# sourceMappingURL=mention-ops.js.map

package/dist/server/mention-ops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mention-ops.js","sourceRoot":"","sources":["../../src/server/mention-ops.ts"],"names":[],"mappings":"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"}

package/dist/server/mention-store.d.ts

@@ -0,0 +1,123 @@
+export type ClaimRecord = {
+    mentionId: string;
+    agentName: string;
+    claimedAt: number;
+};
+export type RecentEvent = {
+    id: number;
+    kind: "mention-created";
+    mention_id: string;
+    file: string;
+    verb: string;
+    origin: "human" | "agent";
+    author: string;
+    at: string;
+} | {
+    id: number;
+    kind: "mention-claimed";
+    mention_id: string;
+    file: string;
+    agent: string;
+    at: string;
+} | {
+    id: number;
+    kind: "mention-released";
+    mention_id: string;
+    file: string;
+    agent: string;
+    reason: string;
+    at: string;
+} | {
+    id: number;
+    kind: "mention-resolved";
+    mention_id: string;
+    file: string;
+    agent: string;
+    resolution: "replace" | "annotation";
+    at: string;
+} | {
+    id: number;
+    kind: "mention-cancelled";
+    mention_id: string;
+    file: string;
+    at: string;
+} | {
+    id: number;
+    kind: "file-edited";
+    file: string;
+    author: string;
+    at: string;
+} | {
+    id: number;
+    kind: "annotation-created";
+    annotation_id: string;
+    file: string;
+    annotation_type: "note" | "suggestion";
+    author: string;
+    at: string;
+} | {
+    id: number;
+    kind: "annotation-removed";
+    annotation_id: string;
+    file: string;
+    annotation_type: "note" | "suggestion";
+    author: string;
+    at: string;
+} | {
+    id: number;
+    kind: "suggestion-accepted";
+    annotation_id: string;
+    file: string;
+    author: string;
+    at: string;
+} | {
+    id: number;
+    kind: "suggestion-rejected";
+    annotation_id: string;
+    file: string;
+    author: string;
+    at: string;
+};
+export type ConnectedAgent = {
+    name: string;
+    connectedAt: number;
+};
+export type RecentEventInput = Omit<Extract<RecentEvent, {
+    kind: "mention-created";
+}>, "id"> | Omit<Extract<RecentEvent, {
+    kind: "mention-claimed";
+}>, "id"> | Omit<Extract<RecentEvent, {
+    kind: "mention-released";
+}>, "id"> | Omit<Extract<RecentEvent, {
+    kind: "mention-resolved";
+}>, "id"> | Omit<Extract<RecentEvent, {
+    kind: "mention-cancelled";
+}>, "id"> | Omit<Extract<RecentEvent, {
+    kind: "file-edited";
+}>, "id"> | Omit<Extract<RecentEvent, {
+    kind: "annotation-created";
+}>, "id"> | Omit<Extract<RecentEvent, {
+    kind: "annotation-removed";
+}>, "id"> | Omit<Extract<RecentEvent, {
+    kind: "suggestion-accepted";
+}>, "id"> | Omit<Extract<RecentEvent, {
+    kind: "suggestion-rejected";
+}>, "id">;
+export type MentionStore = {
+    claim: (mentionId: string, agentName: string) => {
+        ok: true;
+    } | {
+        ok: false;
+        heldBy: string;
+    };
+    release: (mentionId: string) => ClaimRecord | null;
+    claimOf: (mentionId: string) => ClaimRecord | null;
+    /** All current claims, snapshot. */
+    claims: () => ClaimRecord[];
+    recordEvent: (e: RecentEventInput) => RecentEvent;
+    recentEvents: (since?: number) => RecentEvent[];
+    registerAgent: (name: string) => () => void;
+    connectedAgents: () => ConnectedAgent[];
+    onChange: (fn: () => void) => () => void;
+};
+export declare function createMentionStore(now?: () => number): MentionStore;

package/dist/server/mention-store.js

@@ -0,0 +1,91 @@
+// In-memory state layer for slice 4. Holds:
+//
+//   - mention claims (the transient in-progress state for each open mention,
+//     plus the claiming client's identity for conflict reporting)
+//   - the recent-changes ring buffer (last 50 events, monotonic id cursor)
+//   - connected MCP clients (for the status drawer)
+//
+// State is process-local and resets on restart. Persistence is out of scope
+// for V1 (spec: Architecture / In-memory state layer).
+const RING_CAPACITY = 50;
+export function createMentionStore(now = Date.now) {
+    const claims = new Map();
+    const ring = [];
+    let nextEventId = 1;
+    const agents = new Map();
+    // Multiple connections from one client get a "-2", "-3" suffix while
+    // simultaneous; we track per-name counts.
+    const nameUseCounts = new Map();
+    const changeListeners = new Set();
+    const notify = () => {
+        for (const fn of changeListeners) {
+            try {
+                fn();
+            }
+            catch {
+                /* listener errors should not break the store */
+            }
+        }
+    };
+    return {
+        claim(mentionId, agentName) {
+            const existing = claims.get(mentionId);
+            if (existing)
+                return { ok: false, heldBy: existing.agentName };
+            claims.set(mentionId, { mentionId, agentName, claimedAt: now() });
+            notify();
+            return { ok: true };
+        },
+        release(mentionId) {
+            const cur = claims.get(mentionId);
+            if (!cur)
+                return null;
+            claims.delete(mentionId);
+            notify();
+            return cur;
+        },
+        claimOf(mentionId) {
+            return claims.get(mentionId) ?? null;
+        },
+        claims() {
+            return Array.from(claims.values());
+        },
+        recordEvent(partial) {
+            const event = { ...partial, id: nextEventId++ };
+            ring.push(event);
+            if (ring.length > RING_CAPACITY)
+                ring.shift();
+            notify();
+            return event;
+        },
+        recentEvents(since) {
+            if (since === undefined || since === null)
+                return ring.slice();
+            return ring.filter((e) => e.id > since);
+        },
+        registerAgent(name) {
+            const count = (nameUseCounts.get(name) ?? 0) + 1;
+            nameUseCounts.set(name, count);
+            const effective = count === 1 ? name : `${name}-${count}`;
+            agents.set(effective, { name: effective, connectedAt: now() });
+            notify();
+            return () => {
+                agents.delete(effective);
+                const c = (nameUseCounts.get(name) ?? 0) - 1;
+                if (c <= 0)
+                    nameUseCounts.delete(name);
+                else
+                    nameUseCounts.set(name, c);
+                notify();
+            };
+        },
+        connectedAgents() {
+            return Array.from(agents.values()).sort((a, b) => a.connectedAt - b.connectedAt);
+        },
+        onChange(fn) {
+            changeListeners.add(fn);
+            return () => changeListeners.delete(fn);
+        },
+    };
+}
+//# sourceMappingURL=mention-store.js.map

package/dist/server/mention-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mention-store.js","sourceRoot":"","sources":["../../src/server/mention-store.ts"],"names":[],"mappings":"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"}

package/dist/server/runtime-check.d.ts

@@ -0,0 +1 @@
+export declare function assertNodeVersion(version: string): void;

package/dist/server/runtime-check.js

@@ -0,0 +1,10 @@
+// Per ADR-0008, sidebar targets Node 20 LTS or later. Older runtimes refuse
+// to start with a clear error rather than failing on a missing API later.
+export function assertNodeVersion(version) {
+    const match = version.match(/^v?(\d+)/);
+    const major = match ? Number.parseInt(match[1], 10) : Number.NaN;
+    if (!Number.isFinite(major) || major < 20) {
+        throw new Error(`sidebar requires Node 20 or newer (got ${version}). Update Node and try again.`);
+    }
+}
+//# sourceMappingURL=runtime-check.js.map

package/dist/server/runtime-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-check.js","sourceRoot":"","sources":["../../src/server/runtime-check.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,0EAA0E;AAC1E,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;IACjE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,EAAE,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,0CAA0C,OAAO,+BAA+B,CACjF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/server/server.d.ts

@@ -0,0 +1,28 @@
+import { type AnnotationCreatedAtMap } from "./annotation-ops.js";
+import { type DirtyBufferTracker } from "./dirty-buffer.js";
+import { type MentionCreatedAtMap } from "./mention-ops.js";
+import { type MentionStore } from "./mention-store.js";
+import type { VerbCatalog } from "./verbs/index.js";
+import { type Workspace } from "./workspace.js";
+export type ServerHandle = {
+    url: string;
+    port: number;
+    workspace: Workspace;
+    dirtyBuffers: DirtyBufferTracker;
+    mentionStore: MentionStore;
+    mentionCreatedAt: MentionCreatedAtMap;
+    annotationCreatedAt: AnnotationCreatedAtMap;
+    verbCatalog: VerbCatalog;
+    close: () => Promise<void>;
+};
+export type StartOptions = {
+    workspace: Workspace;
+    /** 0 = let the OS pick a free port. */
+    port: number;
+    host?: string;
+    /** Absolute path to the built SPA, or null when running unbuilt. */
+    staticRoot?: string | null;
+    /** Verb catalog assembled from built-ins + custom config. */
+    verbCatalog: VerbCatalog;
+};
+export declare function startServer(opts: StartOptions): Promise<ServerHandle>;