mulmoclaude 0.6.2 → 0.6.4

package/server/encore/notifier.ts

@@ -0,0 +1,123 @@
+// Encore-scoped notifier wrapper.
+//
+// Closes over:
+//   - `pluginPkg`: a constant identity string so every Encore-owned
+//     bell entry is tagged uniformly, and `clearForPlugin` can
+//     enforce plugin-scoped clearing.
+//   - lifecycle: every Encore bell entry uses `lifecycle: "action"`
+//     so the host's NotificationBell.vue does NOT auto-clear on
+//     user click — clearing is owned by the LLM (markStepDone /
+//     markTargetSkipped close the underlying step which clears the
+//     bell). The host's `validateActionCoherence` rejects
+//     `action` + `info`, so the wrapper also maps DSL `info` (and
+//     `warning`) severities to host `nudge` at the publish
+//     boundary.
+//
+// Pure passthrough otherwise — no caching, no batching, no other
+// semantics. Tick + handlers import this module rather than
+// reaching for the raw host engine.
+
+import * as engine from "../notifier/engine.js";
+import type { Severity } from "../../src/types/encore-dsl/schema.js";
+
+/** Identity string used as `pluginPkg` on every Encore bell entry.
+ *  Stable across versions; lives next to the apiNamespace ("encore")
+ *  and the tool name ("manageEncore") as part of the plugin's
+ *  identity. */
+export const ENCORE_PLUGIN_PKG = "encore" as const;
+
+export interface PublishArgs {
+  severity: Severity;
+  title: string;
+  body?: string;
+  navigateTarget: string;
+  pluginData?: unknown;
+}
+
+/** Map Encore's DSL-facing severity vocabulary
+ *  (`info | warning | urgent`, picked for clarity in plain-language
+ *  prompts the LLM composes against) to the host notifier's
+ *  vocabulary (`info | nudge | urgent`).
+ *
+ *  We deliberately avoid the host's `info` severity entirely:
+ *  Encore always uses `lifecycle: "action"` so the LLM (not the
+ *  bell) owns when the entry goes away — the user clicks the
+ *  bell, lands in a chat, talks with the LLM, and the LLM calls
+ *  `markStepDone` / `markTargetSkipped` to clear. The host's
+ *  publish-time coherence check rejects `action` + `info`, so we
+ *  map DSL `info` to host `nudge` (the mid-intensity bucket). We
+ *  lose the visual distinction between info and warning at the
+ *  bell level; the LLM still differentiates them in title / body /
+ *  conversation tone. */
+function toHostSeverity(severity: Severity): "nudge" | "urgent" {
+  if (severity === "urgent") return "urgent";
+  return "nudge";
+}
+
+/** Publish an Encore notification. Always emits
+ *  `lifecycle: "action"` so the host's bell does NOT auto-clear on
+ *  click — Encore owns the clear via markStepDone /
+ *  markTargetSkipped. Returns the host-assigned notification id. */
+export async function publish(args: PublishArgs): Promise<{ id: string }> {
+  return engine.publish({
+    pluginPkg: ENCORE_PLUGIN_PKG,
+    severity: toHostSeverity(args.severity),
+    lifecycle: "action",
+    title: args.title,
+    body: args.body,
+    navigateTarget: args.navigateTarget,
+    pluginData: args.pluginData,
+  });
+}
+
+/** In-place update of an Encore notification's presentation —
+ *  same id, same `pluginPkg`, same `lifecycle`, same `createdAt`,
+ *  new severity / title / body. The reconciler's trim path uses
+ *  this to flush DSL-driven content drift (an `amendDefinition`
+ *  edited a `displayName`, the bundle shrunk so the body's member
+ *  count changed, the cadence pushed us into a higher-severity
+ *  phase) without flickering the bell entry through a clear +
+ *  publish — which would litter history with `cleared` records
+ *  and assign a fresh id every time. Mirrors the DSL → host
+ *  vocabulary mapping in `publish` so a phase escalation from
+ *  `info` to `urgent` ends up at host `nudge` → `urgent` rather
+ *  than confusing the validator.
+ *
+ *  No-op on unknown / cross-plugin ids, and on patches that would
+ *  invalidate the entry (e.g. info severity on the action
+ *  lifecycle we always use). Caller treats the failure modes
+ *  uniformly — same isolation property as `clear`. */
+export async function update(
+  entryId: string,
+  patch: {
+    severity?: Severity;
+    title?: string;
+    body?: string;
+  },
+): Promise<void> {
+  await engine.updateForPlugin(ENCORE_PLUGIN_PKG, entryId, {
+    ...(patch.severity !== undefined ? { severity: toHostSeverity(patch.severity) } : {}),
+    ...(patch.title !== undefined ? { title: patch.title } : {}),
+    ...(patch.body !== undefined ? { body: patch.body } : {}),
+  });
+}
+
+/** Clear an Encore notification. No-ops on unknown / cross-plugin
+ *  ids — matches host `clearForPlugin` semantics, plugin can't
+ *  dismiss another plugin's entries. */
+export async function clear(entryId: string): Promise<void> {
+  await engine.clearForPlugin(ENCORE_PLUGIN_PKG, entryId);
+}
+
+/** True iff a live bell with this id still exists in the notifier
+ *  AND belongs to Encore. Used by the reconciler to detect "ghost
+ *  tickets" — a ticket whose bell was dismissed out-of-band by the
+ *  host UI (or wiped by a crashed active.json) so that the next
+ *  tick republishes instead of trusting ticket-existence as proof
+ *  of bell-existence. Cross-plugin entries (theoretically
+ *  impossible since the notifier ids are namespaced, but defense
+ *  in depth) read as not-ours. */
+export async function bellExists(entryId: string): Promise<boolean> {
+  const entry = await engine.get(entryId);
+  return entry !== undefined && entry.pluginPkg === ENCORE_PLUGIN_PKG;
+}

package/server/encore/obligation.ts

@@ -0,0 +1,25 @@
+// Helpers for the obligation `index.md` file (DSL frontmatter +
+// free-form body). Symmetric with cycle.ts's parse/serialize.
+
+import { parseEncoreFrontmatter, serializeEncoreFrontmatter } from "./yaml-fm.js";
+import { EncoreDslInput, type EncoreDsl } from "../../src/types/encore-dsl/schema.js";
+
+/** Parse an obligation's index.md raw markdown into (dsl, body).
+ *  Re-runs the Zod validator so a hand-edited / corrupted file
+ *  surfaces as a parse error rather than passing garbage downstream. */
+export function parseIndexFile(raw: string): { dsl: EncoreDsl; body: string } {
+  const parsed = parseEncoreFrontmatter(raw);
+  if (!parsed.hasHeader) {
+    throw new Error("obligation index.md: missing YAML frontmatter");
+  }
+  const dsl = EncoreDslInput.parse(parsed.meta);
+  return { dsl, body: parsed.body };
+}
+
+/** Serialize a DSL + body back to markdown. The DSL's
+ *  `EncoreDslInput.parse` output preserves all declared fields
+ *  including the server-generated `id` and `createdAt`, so this is
+ *  a straight YAML dump. */
+export function serializeIndexFile(dsl: EncoreDsl, body: string): string {
+  return serializeEncoreFrontmatter(dsl as unknown as Record<string, unknown>, body);
+}

package/server/encore/paths.ts

@@ -0,0 +1,78 @@
+// Workspace-relative path helpers for the Encore plugin. Pure
+// string composition — no fs here; the io layer joins these with
+// WORKSPACE_PATHS.encore to get absolute paths.
+//
+// Layout under data/plugins/encore/:
+//
+//   obligations/<obligationId>/index.md      ← DSL + free-form body
+//   obligations/<obligationId>/<cycleId>.md  ← per-cycle state + body
+//   tickets/<pendingId>.json                 ← live-bell tickets (chat-on-mount)
+//
+// `obligationId` and `cycleId` flow through the kebab-id validator
+// upstream (DSL schema) and the cadence id formatter — never raw
+// user input, so the path-traversal hardening accounting-io.ts
+// needs is unnecessary here. We still keep a safety assertion at
+// each join to catch any future regression.
+
+import path from "node:path";
+
+const SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+
+function assertSafeSegment(label: string, value: string): void {
+  if (!SAFE_SEGMENT.test(value)) {
+    throw new Error(`encore: invalid ${label} ${JSON.stringify(value)} (must match ${SAFE_SEGMENT.source})`);
+  }
+}
+
+export const OBLIGATIONS_DIRNAME = "obligations";
+export const TICKETS_DIRNAME = "tickets";
+
+/** "obligations" — relative to the plugin root. */
+export function obligationsDir(): string {
+  return OBLIGATIONS_DIRNAME;
+}
+
+/** "obligations/<id>" — directory holding index.md + cycle files. */
+export function obligationDir(obligationId: string): string {
+  assertSafeSegment("obligationId", obligationId);
+  return path.join(OBLIGATIONS_DIRNAME, obligationId);
+}
+
+/** "obligations/<id>/index.md" — the DSL document. */
+export function obligationIndexPath(obligationId: string): string {
+  return path.join(obligationDir(obligationId), "index.md");
+}
+
+/** "obligations/<id>/<cycleId>.md" — the per-cycle state file. */
+export function cycleFilePath(obligationId: string, cycleId: string): string {
+  assertSafeSegment("cycleId", cycleId);
+  return path.join(obligationDir(obligationId), `${cycleId}.md`);
+}
+
+/** "tickets/<pendingId>.json" — the live-bell ticket (carries the
+ *  seed prompt for chat-on-mount, the severity baseline for
+ *  escalation diff, and the chatSessionId binding once the user
+ *  has clicked the bell at least once). */
+export function ticketPath(pendingId: string): string {
+  assertSafeSegment("pendingId", pendingId);
+  return path.join(TICKETS_DIRNAME, `${pendingId}.json`);
+}
+
+/** Slugify a display name into a kebab-case id. Deterministic,
+ *  ASCII-only, safe for use as a filesystem segment. Used by setup
+ *  to generate an obligation id from the user-supplied
+ *  displayName. */
+export function slugify(displayName: string): string {
+  const slug = displayName
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[̀-ͯ]/g, "") // strip diacritics
+    .replace(/[^a-z0-9]+/g, "-") // collapse non-alphanumerics
+    .replace(/^-/, "") // trim leading dash (only one possible: collapse-step above guarantees no consecutive dashes)
+    .replace(/-$/, ""); // trim trailing dash
+  if (!slug) return "obligation";
+  // Slug must start with a letter (KEBAB regex in schema). If the
+  // first char ended up as a digit, prefix "o-".
+  if (!/^[a-z]/.test(slug)) return `o-${slug}`;
+  return slug;
+}