@hiveku-apps/sync 0.4.0 → 0.5.0

package/src/knowledge-files.mjs

@@ -0,0 +1,306 @@
+/**
+ * Where `pull` writes each memory entry: filed by its OWNER, the way the
+ * Memory page files it (memory surfaces audit G14).
+ *
+ *   <type folder>/<owner>/<name>.md     an agent's own entry: rules/sales/,
+ *                                       skills/seo/, memory/helpdesk/, ...
+ *   <type folder>/shared/<name>.md      an entry no agent owns: the page's
+ *                                       "Shared with every agent"
+ *
+ * The owner is the `owner` field memory_list returns (the builder's one owner
+ * rule); an older builder that does not return it gets the same rule from
+ * memory-owner.mjs. A Marketing topic is its own owner (rules/seo/,
+ * rules/ppc/), and `marketing` is the Marketing parent.
+ *
+ *   <type folder>/<owner>/not-followed/<name>.md
+ *                                       an entry filed under an owner that no
+ *                                       agent reads, which the Memory page
+ *                                       hides: a rule, skill or note filed for
+ *                                       the chief of staff outside her
+ *                                       `_account:*` rows, an owner that is no
+ *                                       agent (`mini`), a note a department
+ *                                       owns under a name its agent never
+ *                                       reads. memory_list's `placement` says
+ *                                       so (hidden, a reason other than
+ *                                       `system`), or ownedPlacement does.
+ *                                       Kept out of the Codex rules digest and
+ *                                       skill mirror, which read one folder
+ *                                       level only.
+ *
+ * The `_account:*` rows are not an agent's own entries. They are placed the
+ * way the page shows them (memory_list's `placement`, or accountPlacement),
+ * and written read-only, because owners and admins change them on the Memory
+ * page:
+ *
+ *   memory/orchestrator/how-it-works.md   `_account:soul` (the chief of staff's How it works)
+ *   memory/orchestrator/background.md     `_account:claude` (her Background)
+ *   rules/orchestrator/<slug>.md          `_account:_rule:<slug>`
+ *   skills/orchestrator/<slug>.md         `_account:_skill:<slug>`
+ *   memory/orchestrator/<topic>.md        `_account:memory:<topic>` (her notes)
+ *   memory/orchestrator/moved/<topic>.md  the five topics now kept in About your
+ *                                         business: her old copies, each opening
+ *                                         with a line that says where the current
+ *                                         text is
+ *   hiveku-data/account/voice/<name>.md   Voice and pronunciation (About your business)
+ *
+ * Rows the page never shows (internal state, an old `_account:*` shape) are
+ * not written. Pure: it plans the files; pull.mjs writes them.
+ */
+
+import { createHash } from 'node:crypto';
+
+import { accountMemoryDashboardUrl, ACCOUNT_DATA_DIR, ACCOUNT_MEMORY_FILE } from './account-memory.mjs';
+import {
+  SHARED_OWNER,
+  accountPlacement,
+  accountPlacementLabel,
+  isAccountMemoryRow,
+  isAccountScopedRow,
+  isSystemRow,
+  memoryTypeOf,
+  movedTopicHeading,
+  ownedPlacement,
+  ownerOf,
+} from './memory-owner.mjs';
+import { safeSlug, toFrontmatter, TYPE_TO_FOLDER } from './util.mjs';
+
+/** Voice and pronunciation, under About your business (read-only, never uploaded: push leaves hiveku-data/account/ out). */
+export const VOICE_DIR = `${ACCOUNT_DATA_DIR}/voice`;
+
+/** The subfolder of an owner's folder that holds the entries no agent reads (the page hides them). */
+export const NOT_FOLLOWED_DIR = 'not-followed';
+
+/** The page's words for a row it does not show (builder memory-placement.ts NOT_ON_MEMORY_PAGE). */
+const NOT_SHOWN_LABEL = 'Not shown on the Memory page';
+
+/**
+ * The line a moved topic's file opens with: where the topic went, where the
+ * current text is, and that this is the chief of staff's old copy. True
+ * whether or not the topic was copied across yet (the page says which).
+ */
+export function movedTopicPointer(domain) {
+  const heading = movedTopicHeading(domain);
+  const where = heading ? `Moved to About your business, under "${heading}".` : 'Moved to About your business.';
+  return `> ${where} The current text is in \`${ACCOUNT_MEMORY_FILE}\`. This file is the chief of staff's old copy and may be out of date.`;
+}
+
+/** Owners whose name cannot be a folder file under this one (the true owner stays in the front matter). */
+export const OTHER_OWNER_FOLDER = 'other';
+
+/** A lowercase name that is a folder on every system: a letter first, 50 characters at most. */
+const FOLDER_NAME = /^[a-z][a-z0-9_-]{0,49}$/;
+
+/** Names Windows keeps for devices, with or without an extension: no folder or file may use one. */
+const WINDOWS_DEVICE_NAME = /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\..*)?$/i;
+
+/**
+ * File names an agent tool would read as its own instructions: Claude Code
+ * loads a folder's CLAUDE.md when it reads files there, and Codex reads
+ * AGENTS.md. On a case-insensitive disk `claude.md` is that file, so the chief
+ * of staff's Background (`_account:claude`) or a note named `claude` must
+ * never be written under that name.
+ */
+const INSTRUCTION_FILE_NAME = /^(?:claude|agents)(?:\..*)?$/i;
+
+/** Added after the first part of a file name that is kept (the Hiveku plugin's DEVICE_STEM_SUFFIX). */
+const KEPT_NAME_SUFFIX = '-entry';
+
+/** The folder an owner's entries go in: `shared` for no owner. */
+export function ownerFolder(owner) {
+  if (owner === null || owner === undefined || owner === '') return SHARED_OWNER;
+  const clean = String(owner)
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '_')
+    .replace(/^[^a-z]+/, '')
+    .slice(0, 50);
+  return FOLDER_NAME.test(clean) && !WINDOWS_DEVICE_NAME.test(clean) ? clean : OTHER_OWNER_FOLDER;
+}
+
+/** A file name (without `.md`) for an entry name: a slug, never hidden, never a kept name. */
+export function fileStem(name) {
+  const slug = safeSlug(name).replace(/^\.+/, '') || 'unnamed';
+  if (WINDOWS_DEVICE_NAME.test(slug) || INSTRUCTION_FILE_NAME.test(slug)) {
+    return slug.replace(/^[^.]*/, (head) => head + KEPT_NAME_SUFFIX);
+  }
+  return slug;
+}
+
+/** An entry's name: memory_list's `name`, else the domain without its type prefix. */
+function entryName(entry) {
+  if (typeof entry.name === 'string' && entry.name.trim()) return entry.name;
+  return String(entry.domain || '').replace(/^_[^:]+:/, '');
+}
+
+const PLACES = new Set(['agent', 'shared', 'business', 'hidden']);
+
+/** memory_list's `placement`, when the builder returned one in the shape it documents. */
+function builderPlacement(entry) {
+  const p = entry?.placement;
+  if (!p || typeof p !== 'object' || Array.isArray(p) || !PLACES.has(p.where)) return null;
+  if (p.where === 'agent' && (typeof p.agent !== 'string' || typeof p.group !== 'string')) return null;
+  return p;
+}
+
+/** memory_list's `owner`, when the builder returned the field (null is an answer: no owner). */
+function builderOwner(entry) {
+  if (!entry || !Object.prototype.hasOwnProperty.call(entry, 'owner')) return { known: false };
+  const owner = entry.owner;
+  if (owner === null) return { known: true, owner: null };
+  if (typeof owner === 'string') return { known: true, owner: owner.trim().toLowerCase() || null };
+  return { known: false };
+}
+
+/** The Memory page link for an `_account:*` row: memory_list's own, or built like the builder's memoryPageUrl. */
+function accountEditUrl(entry, placement, accountId, appUrl) {
+  if (typeof entry.memory_page_url === 'string' && /^https:\/\//.test(entry.memory_page_url)) return entry.memory_page_url;
+  const page = accountMemoryDashboardUrl(accountId, appUrl);
+  const query = new URLSearchParams();
+  if (placement.where === 'agent' && placement.agent === 'orchestrator') {
+    query.set('agent', 'orchestrator');
+    const item = String(entry.domain || '').trim();
+    if (item && item.length <= 60) query.set('item', item);
+  } else if (placement.where === 'business' && placement.group === 'voice') {
+    query.set('open', 'voice');
+  }
+  const search = query.toString();
+  return search ? `${page}?${search}` : page;
+}
+
+/** The slug of an `_account:*` row after its prefixes: `_account:_rule:x` is `x`. */
+function accountSlug(domain) {
+  return String(domain || '')
+    .trim()
+    .replace(/^_account:/i, '')
+    .replace(/^(?:_rule:|_skill:|_command:|_agent:|memory:)/i, '');
+}
+
+/** Folder, type and name for an `_account:*` row the page shows, or null. */
+function accountTarget(entry, placement) {
+  const slug = accountSlug(entry.domain);
+  if (placement.where === 'business') {
+    return placement.group === 'voice' ? { dir: VOICE_DIR, type: 'memory', name: slug } : null;
+  }
+  if (placement.where === 'hidden') return null;
+  const owner = placement.where === 'shared' ? SHARED_OWNER : ownerFolder(placement.agent);
+  switch (placement.group) {
+    case 'how-it-works':
+      return { dir: `memory/${owner}`, type: 'memory', name: 'how-it-works' };
+    case 'background':
+      return { dir: `memory/${owner}`, type: 'memory', name: 'background' };
+    case 'rules':
+      return { dir: `rules/${owner}`, type: 'rule', name: slug };
+    case 'skills':
+      return { dir: `skills/${owner}`, type: 'skill', name: slug };
+    case 'shortcuts':
+      return { dir: `commands/${owner}`, type: 'command', name: slug };
+    case 'specialists':
+      return { dir: `agents/${owner}`, type: 'agent', name: slug };
+    case 'profile':
+      return { dir: `identity/${owner}`, type: 'identity', name: slug };
+    case 'moved':
+      return { dir: `memory/${owner}/moved`, type: 'memory', name: slug };
+    default:
+      return { dir: `memory/${owner}`, type: 'memory', name: slug };
+  }
+}
+
+function shortHash(text) {
+  return createHash('sha256').update(String(text), 'utf8').digest('hex').slice(0, 6);
+}
+
+/**
+ * Plan every file one pull writes. `entries` is memory_list's `data` (every
+ * account-level row, any type). Returns
+ *   files:   [{ rel, body, readOnly, notFollowed, type, owner, domain }] in domain order
+ *   skipped: { account, system, hidden }  rows deliberately not written
+ *   listed:  every domain the listing returned (moved or skipped rows included)
+ * Two entries whose names reduce to the same file get distinct files: the
+ * later one (in domain order) gets a short hash of its domain.
+ */
+export function planKnowledgeFiles(entries, { accountId = null, appUrl } = {}) {
+  const skipped = { account: 0, system: 0, hidden: 0 };
+  const listed = new Set();
+  const files = [];
+  const taken = new Set();
+  const rows = entries
+    .filter((e) => e && typeof e.domain === 'string' && e.domain.trim())
+    .sort((a, b) => (a.domain < b.domain ? -1 : a.domain > b.domain ? 1 : 0));
+
+  for (const entry of rows) {
+    listed.add(entry.domain);
+    // About your business: written once from account_memory_get (account-memory.mjs).
+    if (isAccountMemoryRow(entry.domain)) {
+      skipped.account += 1;
+      continue;
+    }
+    const placementFromBuilder = builderPlacement(entry);
+    let target;
+    let owner;
+    let shownUnder = typeof placementFromBuilder?.label === 'string' ? placementFromBuilder.label : null;
+    let readOnly = false;
+    let editUrl = null;
+    let notFollowed = false;
+    let pointer = null;
+
+    if (isAccountScopedRow(entry.domain)) {
+      const placement = placementFromBuilder ?? accountPlacement(entry.domain, entry.content);
+      target = accountTarget(entry, placement);
+      if (!target) {
+        skipped.hidden += 1;
+        continue;
+      }
+      owner = placement.where === 'agent' ? placement.agent : null;
+      shownUnder ??= accountPlacementLabel(placement);
+      readOnly = true;
+      editUrl = accountEditUrl(entry, placement, accountId, appUrl);
+      if (placement.where === 'agent' && placement.group === 'moved') pointer = movedTopicPointer(entry.domain);
+    } else {
+      const system = placementFromBuilder
+        ? placementFromBuilder.where === 'hidden' && placementFromBuilder.reason === 'system'
+        : isSystemRow(entry.domain, entry.content);
+      const type = memoryTypeOf(entry.domain);
+      if (system || !type) {
+        skipped.system += 1;
+        continue;
+      }
+      const fromBuilder = builderOwner(entry);
+      owner = fromBuilder.known ? fromBuilder.owner : ownerOf(entry);
+      // Hidden for any other reason: filed under its owner, in the folder no agent reads.
+      const placement = placementFromBuilder ?? ownedPlacement(entry.domain, owner);
+      notFollowed = placement.where === 'hidden';
+      if (notFollowed) shownUnder ??= NOT_SHOWN_LABEL;
+      const dir = `${TYPE_TO_FOLDER[type]}/${ownerFolder(owner)}`;
+      target = { dir: notFollowed ? `${dir}/${NOT_FOLLOWED_DIR}` : dir, type, name: entryName(entry) };
+    }
+
+    let rel = `${target.dir}/${fileStem(target.name)}.md`;
+    if (taken.has(rel.toLowerCase())) rel = `${target.dir}/${fileStem(target.name)}-${shortHash(entry.domain)}.md`;
+    taken.add(rel.toLowerCase());
+
+    const frontmatter = toFrontmatter({
+      id: entry.id,
+      name: entry.name,
+      type: target.type,
+      domain: entry.domain,
+      owner: owner ?? SHARED_OWNER,
+      shown_under: shownUnder ?? undefined,
+      followed_by: notFollowed ? 'no agent' : undefined,
+      read_only: readOnly ? 'true' : undefined,
+      edit_url: editUrl ?? undefined,
+      memory_page_url: !readOnly && typeof entry.memory_page_url === 'string' ? entry.memory_page_url : undefined,
+      project_id: entry.project_id,
+      version: entry.version,
+      updated_at: entry.updated_at,
+    });
+    files.push({
+      rel,
+      body: `${frontmatter}${pointer ? `${pointer}\n\n` : ''}${entry.content ?? ''}`,
+      readOnly,
+      notFollowed,
+      type: target.type,
+      owner: owner ?? null,
+      domain: entry.domain,
+    });
+  }
+  return { files, skipped, listed };
+}