@deskwork/core 0.9.5 → 0.9.6

package/README.md

@@ -0,0 +1,29 @@
+## @deskwork/core
+
+Core lifecycle library for the [deskwork](https://github.com/audiocontrol-org/deskwork) editorial-calendar plugin family. Pure logic with no entry point — config schema, content-tree walker, frontmatter binding, calendar parser, doctor rules, scrapbook resolver, review pipeline.
+
+### Audience
+
+This package exists to back the deskwork Claude Code plugins; it is shared between [`@deskwork/cli`](https://www.npmjs.com/package/@deskwork/cli) and [`@deskwork/studio`](https://www.npmjs.com/package/@deskwork/studio). Direct npm install of `@deskwork/core` into a non-deskwork host is unusual — most adopters install the plugin instead, which `npm install`s this package on first run.
+
+If you want the editorial calendar lifecycle as a Claude Code plugin (the canonical entry point), follow the install instructions at the [marketplace repo](https://github.com/audiocontrol-org/deskwork#install).
+
+### Use cases for direct install
+
+You may want this package directly if you are:
+
+- Writing a tool that walks deskwork-managed content trees (e.g. a custom doctor rule, a static-site renderer, an analytics script).
+- Building a downstream plugin that reuses the calendar parser or frontmatter binding code.
+- Embedding deskwork's lifecycle handlers into a non-Claude-Code surface.
+
+### Subpath exports
+
+The package exposes ~25 subpath exports (`@deskwork/core/calendar`, `@deskwork/core/frontmatter`, `@deskwork/core/content-tree`, `@deskwork/core/doctor`, `@deskwork/core/review`, etc.) — see [`package.json`](./package.json) for the full list.
+
+### Source
+
+Repository: [`audiocontrol-org/deskwork`](https://github.com/audiocontrol-org/deskwork) — monorepo with the package at [`packages/core/`](https://github.com/audiocontrol-org/deskwork/tree/main/packages/core), the CLI at [`packages/cli/`](https://github.com/audiocontrol-org/deskwork/tree/main/packages/cli), and the studio at [`packages/studio/`](https://github.com/audiocontrol-org/deskwork/tree/main/packages/studio). The plugin shells live under [`plugins/`](https://github.com/audiocontrol-org/deskwork/tree/main/plugins).
+
+### License
+
+GPL-3.0-or-later — same as the monorepo. See [`LICENSE`](https://github.com/audiocontrol-org/deskwork/blob/main/LICENSE) for details.

package/dist/doctor/rules/calendar-uuid-missing.ts

@@ -0,0 +1,205 @@
+/**
+ * Rule: calendar-uuid-missing.
+ *
+ * Detection: re-read the calendar markdown from disk and find rows
+ * whose UUID cell is empty or missing. The in-memory parser auto-
+ * backfills missing UUIDs, so the in-context calendar always has ids;
+ * we have to look at the on-disk bytes directly to see what hasn't
+ * been persisted yet.
+ *
+ * Repair: a single calendar write flushes the in-memory backfilled
+ * ids to disk. We read the calendar via `readCalendar` (which assigns
+ * UUIDs in-memory) and call `writeCalendar` to persist them.
+ *
+ * Sibling-relative imports per the project convention.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolveCalendarPath } from '../../paths.ts';
+import { readCalendar, writeCalendar } from '../../calendar.ts';
+import type {
+  DoctorContext,
+  DoctorRule,
+  Finding,
+  RepairPlan,
+  RepairResult,
+} from '../types.ts';
+
+const RULE_ID = 'calendar-uuid-missing';
+
+interface RawRow {
+  /** Slug parsed out of the row, for human-facing messages. */
+  slug: string;
+  /** Stage-table the row belonged to. */
+  stage: string;
+  /** Line number (1-based) in the calendar source. */
+  line: number;
+}
+
+const STAGE_HEADER_RE = /^##\s+(.+)\s*$/;
+
+/**
+ * Walk the calendar markdown line-by-line, find stage tables, and
+ * report rows whose UUID column is empty/missing.
+ *
+ * Tolerant of column ordering: we identify the UUID column index from
+ * the table header (case-insensitive), then check each data row's
+ * cell at that index.
+ */
+function scanRowsMissingUuid(markdown: string): RawRow[] {
+  const lines = markdown.split('\n');
+  const rows: RawRow[] = [];
+
+  let currentStage: string | null = null;
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const stageMatch = line.match(STAGE_HEADER_RE);
+    if (stageMatch) {
+      const name = stageMatch[1].trim();
+      // Only the lifecycle stage tables; Distribution / Shortform
+      // sections aren't entry rows so we skip their tables here.
+      if (name === 'Distribution' || name === 'Shortform Copy') {
+        currentStage = null;
+      } else {
+        currentStage = name;
+      }
+      i++;
+      continue;
+    }
+    if (line.startsWith('|') && currentStage) {
+      // Table found — first row is the header.
+      const headerCells = parseRow(line);
+      const uuidIdx = headerCells.findIndex(
+        (c) => c.trim().toLowerCase() === 'uuid' || c.trim().toLowerCase() === 'id',
+      );
+      const slugIdx = headerCells.findIndex(
+        (c) => c.trim().toLowerCase() === 'slug',
+      );
+      i++;
+      // Optional separator row.
+      if (i < lines.length && /^\|[\s:-]+\|/.test(lines[i])) i++;
+      while (i < lines.length && lines[i].startsWith('|')) {
+        const cells = parseRow(lines[i]);
+        const slug = slugIdx >= 0 ? (cells[slugIdx] ?? '').trim() : '';
+        if (slug) {
+          const uuidCell = uuidIdx >= 0 ? (cells[uuidIdx] ?? '').trim() : '';
+          if (!uuidCell) {
+            rows.push({
+              slug,
+              stage: currentStage,
+              line: i + 1,
+            });
+          }
+        }
+        i++;
+      }
+      continue;
+    }
+    i++;
+  }
+
+  return rows;
+}
+
+function parseRow(line: string): string[] {
+  return line.split('|').slice(1, -1).map((c) => c.trim());
+}
+
+const rule: DoctorRule = {
+  id: RULE_ID,
+  label: 'Calendar rows with missing UUIDs (not yet persisted)',
+
+  async audit(ctx: DoctorContext): Promise<Finding[]> {
+    const calendarPath = resolveCalendarPath(
+      ctx.projectRoot,
+      ctx.config,
+      ctx.site,
+    );
+    if (!existsSync(calendarPath)) return [];
+    let raw: string;
+    try {
+      raw = readFileSync(calendarPath, 'utf-8');
+    } catch {
+      return [];
+    }
+    const rows = scanRowsMissingUuid(raw);
+    if (rows.length === 0) return [];
+    return [
+      {
+        ruleId: RULE_ID,
+        site: ctx.site,
+        severity: 'warning',
+        message: `${rows.length} calendar row(s) have no UUID on disk; in-memory parser will backfill on next write`,
+        details: {
+          calendarPath,
+          rows: rows.map((r) => ({ slug: r.slug, stage: r.stage, line: r.line })),
+        },
+      },
+    ];
+  },
+
+  async plan(ctx: DoctorContext, finding: Finding): Promise<RepairPlan> {
+    const calendarPath = String(finding.details.calendarPath ?? '');
+    if (!calendarPath) {
+      return {
+        kind: 'report-only',
+        finding,
+        reason: 'finding missing calendarPath — re-run audit',
+      };
+    }
+    return {
+      kind: 'apply',
+      finding,
+      summary: `re-write ${calendarPath} so the in-memory backfilled UUIDs land on disk`,
+      payload: { calendarPath, site: ctx.site },
+    };
+  },
+
+  async apply(ctx: DoctorContext, plan: RepairPlan): Promise<RepairResult> {
+    if (plan.kind !== 'apply') {
+      return {
+        finding: plan.finding,
+        applied: false,
+        message: 'plan is not directly appliable; runner should resolve prompt first',
+        skipReason: 'apply-failed',
+      };
+    }
+    const calendarPath = String(plan.payload.calendarPath ?? '');
+    if (!calendarPath) {
+      return {
+        finding: plan.finding,
+        applied: false,
+        message: 'apply payload missing calendarPath',
+        skipReason: 'apply-failed',
+      };
+    }
+    try {
+      // readCalendar populates missing UUIDs in-memory; writeCalendar
+      // flushes the populated calendar back to disk. One round-trip
+      // migrates every row — also true at the call site here.
+      const cal = readCalendar(calendarPath);
+      writeCalendar(calendarPath, cal);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      return {
+        finding: plan.finding,
+        applied: false,
+        message: `failed to re-write calendar: ${reason}`,
+        skipReason: 'apply-failed',
+      };
+    }
+    // Re-read what's now on disk to update the runner's view of
+    // ctx.calendar — though strictly the runner doesn't depend on
+    // it past this point.
+    void ctx;
+    return {
+      finding: plan.finding,
+      applied: true,
+      message: `re-wrote ${calendarPath} with UUIDs populated`,
+      details: { calendarPath },
+    };
+  },
+};
+
+export default rule;

package/dist/doctor/rules/duplicate-id.ts

@@ -0,0 +1,173 @@
+/**
+ * Rule: duplicate-id.
+ *
+ * Audit: more than one file under contentDir claims the same frontmatter
+ * id. The content index reports the byId map keeping only the first
+ * encountered, but byPath records every file. We re-walk byPath grouped
+ * by id and flag any group with > 1 entry.
+ *
+ * Repair: prompt the operator to pick a canonical file; clear the id
+ * from the others. With `--yes`, skip — picking a canonical file is
+ * an editorial decision, not something doctor should default.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { parseFrontmatter, removeFrontmatterPaths } from '../../frontmatter.ts';
+import { resolveContentDir } from '../../paths.ts';
+import type {
+  DoctorContext,
+  DoctorRule,
+  Finding,
+  RepairPlan,
+  RepairResult,
+} from '../types.ts';
+
+const RULE_ID = 'duplicate-id';
+
+/**
+ * Clear the `deskwork.id` field from a markdown file. Returns true when
+ * the field was present and cleared. Issue #38: scoped to the
+ * namespaced key — top-level `id:` belongs to the operator and is left
+ * alone.
+ */
+function clearFrontmatterId(absPath: string): boolean {
+  const raw = readFileSync(absPath, 'utf-8');
+  const { data } = parseFrontmatter(raw);
+  const block = data.deskwork;
+  if (block === undefined || block === null) return false;
+  if (typeof block !== 'object' || Array.isArray(block)) return false;
+  const blockObj = block as Record<string, unknown>;
+  if (!('id' in blockObj)) return false;
+
+  const updated = removeFrontmatterPaths(raw, [['deskwork', 'id']]);
+  if (updated === raw) return false;
+  writeFileSync(absPath, updated, 'utf-8');
+  return true;
+}
+
+interface DuplicateGroup {
+  id: string;
+  /** Absolute paths of every file claiming `id`. */
+  files: string[];
+}
+
+/**
+ * Group `index.byPath` (relPath → uuid) by uuid, return only groups
+ * with more than one file. Caller resolves relative paths against
+ * the site's contentDir to get absolute paths for repair.
+ */
+export function findDuplicateGroups(
+  ctx: DoctorContext,
+): DuplicateGroup[] {
+  const contentDir = resolveContentDir(ctx.projectRoot, ctx.config, ctx.site);
+  const byUuid = new Map<string, string[]>();
+  for (const [relPath, uuid] of ctx.index.byPath) {
+    const abs = join(contentDir, relPath);
+    const list = byUuid.get(uuid);
+    if (list) list.push(abs);
+    else byUuid.set(uuid, [abs]);
+  }
+  const groups: DuplicateGroup[] = [];
+  for (const [uuid, files] of byUuid) {
+    if (files.length > 1) {
+      groups.push({ id: uuid, files: files.slice().sort() });
+    }
+  }
+  return groups;
+}
+
+const rule: DoctorRule = {
+  id: RULE_ID,
+  label: 'Multiple files share the same frontmatter id',
+
+  async audit(ctx: DoctorContext): Promise<Finding[]> {
+    const groups = findDuplicateGroups(ctx);
+    return groups.map((g) => ({
+      ruleId: RULE_ID,
+      site: ctx.site,
+      severity: 'error',
+      message: `id ${g.id} appears in ${g.files.length} files`,
+      details: { entryId: g.id, files: g.files },
+    }));
+  },
+
+  async plan(ctx: DoctorContext, finding: Finding): Promise<RepairPlan> {
+    const rawFiles = finding.details.files;
+    const files: string[] = Array.isArray(rawFiles)
+      ? rawFiles.filter((x): x is string => typeof x === 'string')
+      : [];
+    if (files.length < 2) {
+      return {
+        kind: 'report-only',
+        finding,
+        reason: 'duplicate group has fewer than 2 files — re-run audit',
+      };
+    }
+    return {
+      kind: 'prompt',
+      finding,
+      question: `Multiple files claim id ${finding.details.entryId}. Pick the canonical file; the id will be cleared from the others.`,
+      choices: files.map((abs) => ({
+        id: abs,
+        label: relative(ctx.projectRoot, abs),
+        payload: { canonical: abs, others: files.filter((f) => f !== abs) },
+      })),
+    };
+  },
+
+  async apply(ctx: DoctorContext, plan: RepairPlan): Promise<RepairResult> {
+    if (plan.kind !== 'apply') {
+      return {
+        finding: plan.finding,
+        applied: false,
+        message: 'plan is not directly appliable; runner should resolve prompt first',
+        skipReason: 'apply-failed',
+      };
+    }
+    const canonical = String(plan.payload.canonical ?? '');
+    const othersRaw = plan.payload.others;
+    const others = Array.isArray(othersRaw)
+      ? (othersRaw.filter((x): x is string => typeof x === 'string'))
+      : [];
+    if (!canonical || others.length === 0) {
+      return {
+        finding: plan.finding,
+        applied: false,
+        message: 'apply payload missing canonical or others',
+        skipReason: 'apply-failed',
+      };
+    }
+    const cleared: string[] = [];
+    const failed: string[] = [];
+    for (const abs of others) {
+      try {
+        const changed = clearFrontmatterId(abs);
+        if (changed) cleared.push(abs);
+      } catch {
+        failed.push(abs);
+      }
+    }
+    if (failed.length > 0) {
+      const partial = cleared.length > 0;
+      return {
+        finding: plan.finding,
+        applied: partial,
+        message: `cleared id from ${cleared.length} file(s); failed on ${failed.length}: ${failed.map((p) => relative(ctx.projectRoot, p)).join(', ')}`,
+        // When we cleared at least one file but some failed, treat as
+        // partial success — the `apply-failed` skip reason only fires
+        // when nothing landed on disk.
+        ...(partial ? {} : { skipReason: 'apply-failed' as const }),
+        details: { canonical, cleared, failed },
+      };
+    }
+    return {
+      finding: plan.finding,
+      applied: true,
+      message: `cleared id from ${cleared.length} file(s); canonical: ${relative(ctx.projectRoot, canonical)}`,
+      details: { canonical, cleared },
+    };
+  },
+};
+
+export default rule;

package/dist/doctor/rules/legacy-top-level-id-migration.ts

@@ -0,0 +1,264 @@
+/**
+ * Rule: legacy-top-level-id-migration.
+ *
+ * Issue #38: v0.7.0 / v0.7.1 of deskwork wrote (and read) the calendar
+ * binding key as a top-level `id:` field in frontmatter. Starting in
+ * v0.7.2 the canonical location is `deskwork.id`, scoping the binding
+ * to a `deskwork:` namespace so deskwork doesn't claim the operator's
+ * global keyspace.
+ *
+ * Audit: walk every markdown file under `<contentDir>` and find files
+ * where:
+ *   1. top-level `id:` is present AND its value is a UUID matching a
+ *      calendar entry, AND
+ *   2. `deskwork.id` is NOT present.
+ *
+ * The (1)+(2) conjunction makes the rule idempotent: once a file has
+ * migrated to the namespaced form, it is no longer reported. Files
+ * with a top-level `id:` whose value is NOT a calendar UUID belong to
+ * the operator and are left alone.
+ *
+ * Repair: round-trip-preserving rewrite — add `deskwork.id` with the
+ * old value, remove the top-level `id:`, leave every other byte
+ * untouched. Safe for `--yes` / `--fix=all` mode (clear-and-move with
+ * no editorial decision required).
+ *
+ * Sibling-relative imports per the project convention.
+ */
+
+import { readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { extname, join, relative } from 'node:path';
+import { resolveContentDir } from '../../paths.ts';
+import {
+  parseFrontmatter,
+  removeFrontmatterPaths,
+  updateFrontmatter,
+} from '../../frontmatter.ts';
+import type {
+  DoctorContext,
+  DoctorRule,
+  Finding,
+  RepairPlan,
+  RepairResult,
+} from '../types.ts';
+
+const RULE_ID = 'legacy-top-level-id-migration';
+
+const MARKDOWN_EXTENSIONS: ReadonlySet<string> = new Set([
+  '.md',
+  '.mdx',
+  '.markdown',
+]);
+const SKIP_DIRS: ReadonlySet<string> = new Set([
+  'scrapbook',
+  'node_modules',
+  'dist',
+  '.git',
+]);
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function shouldSkipDir(name: string): boolean {
+  if (name.startsWith('.')) return true;
+  return SKIP_DIRS.has(name.toLowerCase());
+}
+
+function collectMarkdownFiles(dir: string): string[] {
+  const out: string[] = [];
+  visit(dir);
+  out.sort();
+  return out;
+
+  function visit(currentDir: string): void {
+    let names: string[];
+    try {
+      names = readdirSync(currentDir);
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      const abs = join(currentDir, name);
+      let st;
+      try {
+        st = statSync(abs);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) {
+        if (shouldSkipDir(name)) continue;
+        visit(abs);
+        continue;
+      }
+      if (!st.isFile()) continue;
+      if (MARKDOWN_EXTENSIONS.has(extname(name).toLowerCase())) {
+        out.push(abs);
+      }
+    }
+  }
+}
+
+interface LegacyHit {
+  /** Absolute path to the file with a legacy top-level id. */
+  absolutePath: string;
+  /** The UUID value at the top-level id field. */
+  legacyId: string;
+}
+
+/**
+ * Inspect a single file's frontmatter and decide if it qualifies for
+ * migration. The conjunction is strict on purpose:
+ *  - top-level `id:` must be a string AND match the UUID shape
+ *  - that UUID must be present in the calendar (otherwise it isn't
+ *    deskwork's id; it's the operator's)
+ *  - `deskwork.id` must NOT exist (otherwise the file is already on
+ *    the new shape; ignoring leaves the rule idempotent across runs)
+ */
+function classify(
+  absPath: string,
+  calendarIds: ReadonlySet<string>,
+): LegacyHit | null {
+  let parsed;
+  try {
+    parsed = parseFrontmatter(readFileSync(absPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+  const topLevelId = parsed.data.id;
+  if (typeof topLevelId !== 'string') return null;
+  const trimmed = topLevelId.trim();
+  if (trimmed === '' || !UUID_RE.test(trimmed)) return null;
+  if (!calendarIds.has(trimmed)) return null;
+
+  const block = parsed.data.deskwork;
+  if (block !== undefined && block !== null) {
+    if (typeof block === 'object' && !Array.isArray(block)) {
+      const nestedId = (block as Record<string, unknown>).id;
+      if (typeof nestedId === 'string' && nestedId.trim() !== '') {
+        return null;
+      }
+    }
+  }
+  return { absolutePath: absPath, legacyId: trimmed };
+}
+
+/**
+ * Apply the migration to a single file:
+ * 1. Add `deskwork.id` with the old value.
+ * 2. Remove the top-level `id:`.
+ *
+ * Both writes use the round-trip-preserving frontmatter API so every
+ * other byte stays put.
+ */
+export function migrateLegacyTopLevelId(absPath: string, legacyId: string): void {
+  const raw = readFileSync(absPath, 'utf-8');
+  const withDeskwork = updateFrontmatter(raw, { deskwork: { id: legacyId } });
+  const withoutTopLevel = removeFrontmatterPaths(withDeskwork, [['id']]);
+  if (withoutTopLevel === raw) return;
+  writeFileSync(absPath, withoutTopLevel, 'utf-8');
+}
+
+const rule: DoctorRule = {
+  id: RULE_ID,
+  label: 'Frontmatter id at top level should be under `deskwork:` namespace',
+
+  async audit(ctx: DoctorContext): Promise<Finding[]> {
+    const contentDir = resolveContentDir(
+      ctx.projectRoot,
+      ctx.config,
+      ctx.site,
+    );
+    const calendarIds = new Set<string>();
+    for (const e of ctx.calendar.entries) {
+      if (e.id) calendarIds.add(e.id);
+    }
+
+    let files: string[];
+    try {
+      files = collectMarkdownFiles(contentDir);
+    } catch {
+      return [];
+    }
+
+    const findings: Finding[] = [];
+    for (const abs of files) {
+      const hit = classify(abs, calendarIds);
+      if (hit === null) continue;
+      findings.push({
+        ruleId: RULE_ID,
+        site: ctx.site,
+        severity: 'warning',
+        message:
+          `File ${relative(ctx.projectRoot, abs)} has a top-level \`id:\` ` +
+          `that should be migrated under \`deskwork.id\``,
+        details: {
+          absolutePath: abs,
+          legacyId: hit.legacyId,
+        },
+      });
+    }
+    return findings;
+  },
+
+  async plan(_ctx: DoctorContext, finding: Finding): Promise<RepairPlan> {
+    const absPath = String(finding.details.absolutePath ?? '');
+    const legacyId = String(finding.details.legacyId ?? '');
+    if (!absPath || !legacyId) {
+      return {
+        kind: 'report-only',
+        finding,
+        reason: 'finding missing absolutePath or legacyId — re-run audit',
+      };
+    }
+    return {
+      kind: 'apply',
+      finding,
+      summary:
+        `move top-level id ${legacyId} to deskwork.id in ${absPath}`,
+      payload: { absolutePath: absPath, legacyId },
+    };
+  },
+
+  async apply(ctx: DoctorContext, plan: RepairPlan): Promise<RepairResult> {
+    if (plan.kind !== 'apply') {
+      return {
+        finding: plan.finding,
+        applied: false,
+        message:
+          'plan is not directly appliable; runner should resolve prompt first',
+        skipReason: 'apply-failed',
+      };
+    }
+    const absPath = String(plan.payload.absolutePath ?? '');
+    const legacyId = String(plan.payload.legacyId ?? '');
+    if (!absPath || !legacyId) {
+      return {
+        finding: plan.finding,
+        applied: false,
+        message: 'apply payload missing absolutePath or legacyId',
+        skipReason: 'apply-failed',
+      };
+    }
+    try {
+      migrateLegacyTopLevelId(absPath, legacyId);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      return {
+        finding: plan.finding,
+        applied: false,
+        message: `failed to migrate frontmatter id: ${reason}`,
+        skipReason: 'apply-failed',
+      };
+    }
+    return {
+      finding: plan.finding,
+      applied: true,
+      message:
+        `migrated id ${legacyId} from top-level to deskwork.id in ` +
+        relative(ctx.projectRoot, absPath),
+      details: { absolutePath: absPath, legacyId },
+    };
+  },
+};
+
+export default rule;