@hiveku-apps/sync 0.3.6 → 0.5.0

package/src/init.mjs

@@ -3,14 +3,19 @@
  * .mcp.json, CLAUDE.md, and the empty memory/rules/skills/ tree. Also appends
  * the folder to the sibling hiveku.code-workspace file if one exists at the
  * parent directory.
+ *
+ * CLAUDE.md is the user's once written, except its folder layout and memory
+ * rules: they sit between markers that `pull` and `codex` refresh
+ * (claude-md.mjs), so a folder an older release made learns the new ones.
  */
 
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { basename, dirname, join, resolve } from 'node:path';
+import { basename, join, resolve } from 'node:path';
 
 import { writeFileAtomic, safeSlug, TYPE_TO_FOLDER, loadDotenv } from './util.mjs';
 import { writeCodexScaffold, preTrustFolder } from './codex.mjs';
+import { claudeMdMemoryRegion, refreshClaudeMd } from './claude-md.mjs';
 
 const VALID_PROFILES = ['full', 'sales', 'marketing', 'helpdesk', 'pm', 'dev'];
 const DEFAULT_BASE_URL = 'https://core.hiveku.com';
@@ -58,45 +63,9 @@ This folder is bound to a single Hiveku account via \`.env\` (\`OLYMPUS_API_KEY\
 The Hiveku MCP server at \`core.hiveku.com/mcp\` is wired up in \`.mcp.json\` and
 exposes the **${profile}** profile of Olympus tools.
 
-## Folder layout
+${claudeMdMemoryRegion()}
 
-- \`memory/\` — synced memory documents (\`hiveku-sync pull\` writes here)
-- \`rules/\` — synced agent rules
-- \`skills/\` — synced agent skills
-- \`commands/\`, \`agents/\`, \`identity/\` — other memory types
-- \`hiveku-data/account/ACCOUNT_MEMORY.md\` — the account memory (the business
-  facts every department agent reads), **read-only**: owners and admins edit it on
-  the Hiveku dashboard under Account memory, and nothing uploads this file
-- \`projects/<slug>/\` — coder project source pulled via \`hiveku-sync pull-project\`
-- \`.hiveku/manifest.json\` — memory last-sync record
-- \`.hiveku/projects.json\` — project ID ↔ folder mapping
-
-When asked about this account, read the local files first — they are the
-authoritative copy of what was in Olympus the last time \`hiveku-sync pull\`
-ran. To pick up edits made elsewhere, run \`hiveku-sync pull\`.
-
-## Memory writes
-
-The local memory files are read-only as far as Olympus is concerned. To persist
-changes (new skill, updated rule, etc.), call the corresponding MCP tool:
-
-- \`memory_create\` / \`memory_update\` — for memory documents, skills, rules,
-  commands, agents, identity entries
-- \`memory_delete\` — to remove an entry
-
-\`memory_update\` replaces the whole entry. Each department's memory is ONE
-document, so read the current one with \`memory_list({ domain })\`, merge your
-change into its full text, and send the whole document. Use \`memory_create\`
-only when none exists; a 409 means one does, so read and merge, never overwrite.
-
-The account memory is the exception: no tool sets it. Read it with
-\`account_memory_get\`, suggest one line with \`account_memory_append\` (an owner
-keeps or removes it), and tell the user that owners and admins edit it on the
-Hiveku dashboard under Account memory.
-
-Then run \`hiveku-sync pull\` to refresh the local copies.
-
-## Coder projects (pull / status / push)
+## Coder projects (pull / push / versions)
 
 Each account has zero or more coder projects (Next.js, Vite, Python Lambda,
 Expo). To work on one locally:
@@ -105,25 +74,54 @@ Expo). To work on one locally:
 hiveku-sync projects                        # list the account's projects
 hiveku-sync pull-project <slug-or-id>       # snapshot into ./projects/<slug>/
 cd projects/<slug>
-# follow the run instructions in RUN.md (npm install && npm run dev for nextjs, etc.)
+# follow the run instructions in .hiveku/RUN.md (npm install && npm run dev for nextjs, etc.)
 \`\`\`
 
-This is **not a git clone** — the local folder is a snapshot. To check whether
-edits are in sync with the Hiveku DB, and to commit changes back to the
-project's connected GitHub branch (same path the v3 sidebar uses):
+This is **not a git clone** — the local folder is a snapshot of **Your site**
+(the project's main source; \`--branch <name>\` pulls a branch instead).
+\`push\` saves your edits to Hiveku and then saves them as ONE **version**, which
+can be rolled back later:
 
 \`\`\`bash
-hiveku-sync status                          # diff local vs Hiveku DB
-hiveku-sync push -m "fix: header overlap"   # save + commit changed files via MCP
+hiveku-sync status                          # diff local vs Hiveku
+hiveku-sync push -m "Updated the pricing section on the Home page"
+hiveku-sync versions                        # the version history, newest first
+hiveku-sync rollback <version id>           # dry run: what going back would change
+hiveku-sync deploy production               # publishing is always its own step
 \`\`\`
 
-You can also ask Claude in this workspace to:
-- "Pull project <slug>"
-- "Show me which files are out of sync with Hiveku"
-- "Commit the changes in projects/<slug> to the dev branch with message '...'"
-
-Claude has the \`project_files_list\`, \`project_file_get\`, \`project_files_status\`,
-and \`project_commit\` MCP tools available under the **${profile}** profile.
+- **Version names are read by the site owner.** Describe what changed for their
+  visitors ("Added a contact form to the About page"): never file paths, file
+  extensions, \`fix:\`-style prefixes or tool names. A version holds everything
+  waiting on Your site, including the Hiveku AI's and the editor's changes, so
+  without \`-m\` push names it from all of that; \`--no-version\` skips it.
+- **One version per change the owner would recognise**: push as often as you
+  like with \`--no-version\`, then save the version once (\`hiveku-sync commit -m "..."\`)
+  before you deploy.
+- **Exit codes:** 0 done; 1 some files did not save, or the push was refused
+  (listed; no version, no deploy); 2 every file IS saved but the version was not
+  (it prints the \`hiveku-sync commit\` that retries it); 3 the files and the
+  version ARE saved and only the deploy failed.
+- **On a branch, someone else may have saved since you pulled.** push then
+  refuses and lists the files that may hold their work: pull again (it replaces
+  your local copies, so keep your edits somewhere first), or \`--force\` to
+  overwrite. A pull moves the files an earlier pull wrote that are not on what
+  it pulls now (another branch's, or deleted on Hiveku) out of the project folder
+  into \`.hiveku/set-aside/\`, so they are never pushed back by mistake.
+- **Rolling back** writes a NEW version equal to the old one, so it can be undone,
+  and it never publishes. Run the dry run, show the owner what it changes, and only
+  after they agree run the \`--apply\` command it prints. Then offer \`deploy\`
+  separately.
+
+Through the MCP tools the same loop is: save (\`project_files_bulk_save\` /
+\`project_file_save\`), verify, then \`project_vcs_commit({ project_id, message })\`
+with **no files** (one version, plain-language name; 409 \`nothing_to_commit\`
+means it is already a version), then \`deploy_site\`.
+\`project_vcs_status\` says whether changes are waiting to be saved as a version;
+\`project_vcs_rollback\` rolls back (dry run by default; applying needs the dry
+run's \`head_commit_id\` as \`expected_head_commit_id\`, and on Your site its
+\`live_fingerprint\` as \`expected_live_fingerprint\`). The \`project_*\` tools come
+with the \`dev\` and \`full\` profiles (this folder uses **${profile}**).
 
 ## When Hiveku itself gets in your way
 
@@ -233,6 +231,9 @@ export async function runInit({ slug, parentDir, profile = 'full', codex = false
  * .codex/config.toml + knowledge→skills). Run from inside the folder, or pass
  * one. Derives the account slug from the folder name and the profile from
  * .env (HIVEKU_PROFILE), and inlines the real OLYMPUS_API_KEY when .env has it.
+ * AGENTS.md sends Codex to CLAUDE.md first, so the part of CLAUDE.md that
+ * hiveku-sync keeps current is refreshed too (claude-md.mjs), after the
+ * scaffold is written: a refused config.toml update changes nothing.
  */
 export async function runCodex({ folder, trust = false } = {}) {
   const target = folder ? resolve(folder) : process.cwd();
@@ -243,5 +244,11 @@ export async function runCodex({ folder, trust = false } = {}) {
   const slug = safeSlug(basename(target));
   const result = await writeCodexScaffold({ folder: target, slug, baseUrl, profile });
   if (trust) result.trust = await preTrustFolder(target);
-  return { folder: target, slug, profile, ...result };
+  let claudeMd;
+  try {
+    claudeMd = await refreshClaudeMd(target);
+  } catch (err) {
+    claudeMd = { status: 'failed', message: err.message };
+  }
+  return { folder: target, slug, profile, ...result, claudeMd };
 }

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 };
+}