@hiveku-apps/sync 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# @hiveku-apps/sync
+
+Local sync CLI for a Hiveku account. Pairs with the Hiveku MCP server at
+`https://core.hiveku.com/mcp` to:
+
+1. **`hiveku-sync init <slug>`** — scaffold a per-account folder with `.env`,
+   `.mcp.json`, `CLAUDE.md`, and the empty `memory/ rules/ skills/` tree.
+2. **`hiveku-sync pull`** — fetch the account's memory/rules/skills via the
+   `memory_list` MCP tool and write each entry as a Markdown file with
+   YAML frontmatter (name, type, domain, department, version, updated_at).
+
+The goal: open one folder per Hiveku tenant in VS Code with Claude Code,
+and the local `.md` files become the source-of-truth Claude reads. Tools
+are dispatched against the right tenant automatically via the API key
+in `.env`.
+
+## Install
+
+**Option A — npx (no install, recommended for trying it out):**
+
+```bash
+npx @hiveku-apps/sync init <account-slug>
+```
+
+**Option B — global install (faster for repeat use):**
+
+```bash
+npm install -g @hiveku-apps/sync
+hiveku-sync init <account-slug>
+```
+
+**Option C — from source (local dev):**
+
+```bash
+cd hiveku-sync
+npm link            # adds `hiveku-sync` to your PATH
+```
+
+Requires Node 20+.
+
+## Publishing (maintainers)
+
+```bash
+cd hiveku-sync
+# Bump version in package.json
+npm publish --access public
+```
+
+Once published, the UI's "CLI connector" tab in `/dashboard/settings`
+will show the `npx @hiveku-apps/sync init` command automatically.
+
+## Usage
+
+```bash
+# Pick a parent folder for all your account workspaces
+mkdir -p ~/Documents/hiveku-accounts && cd ~/Documents/hiveku-accounts
+
+# Scaffold one account at a time
+hiveku-sync init acme-corp --profile=sales
+hiveku-sync init beta-inc  --profile=marketing
+
+# Paste credentials
+cp acme-corp/.env.example acme-corp/.env
+# Edit acme-corp/.env — set OLYMPUS_API_KEY to a Hiveku MCP key minted
+# from https://app.hiveku.com/<account_id>/dashboard/settings
+
+# Pull memory/rules/skills into local .md files
+cd acme-corp && hiveku-sync pull
+```
+
+Open `~/Documents/hiveku-accounts/hiveku.code-workspace` in VS Code —
+all account folders are listed there.
+
+## Profiles
+
+The `.mcp.json` URL embeds `?profile=<name>` so the MCP server returns a
+narrowed tool list. Available: `full`, `sales`, `marketing`, `helpdesk`,
+`pm`, `dev`. Change `HIVEKU_PROFILE` in `.env` and reload the MCP server
+in your editor to switch.
+
+## Safety
+
+- **Manifest pin** — `.hiveku/manifest.json` records the API key preview.
+  `pull` refuses if `.env` is later swapped to a key from a different
+  account. Delete the manifest to intentionally re-bind.
+- **Atomic writes** — every file is written to `*.tmp` and renamed, so
+  a Ctrl-C mid-sync never leaves partial files.
+- **No deletes in v1** — entries removed in Olympus are *not* deleted
+  from disk; they're listed under `removed_remotely_since_last_sync` in
+  the manifest. Prune manually if you want.
+
+## How writes work
+
+`hiveku-sync` is pull-only. To persist changes back to Olympus, call the
+`memory_create` / `memory_update` / `memory_delete` MCP tools through
+Claude (or whichever LLM you've wired up). Then `hiveku-sync pull` to
+refresh the local copies.

package/bin/hiveku-sync.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+/**
+ * hiveku-sync — Hiveku account folder sync CLI.
+ *
+ * Usage:
+ *   hiveku-sync init <slug> [--profile=<name>]    Scaffold a per-account folder
+ *   hiveku-sync pull [--profile=<name>]           Pull memory/rules/skills locally
+ *   hiveku-sync help
+ */
+
+import { runInit } from '../src/init.mjs';
+import { runPull } from '../src/pull.mjs';
+import {
+  runProjectsList,
+  runPullProject,
+  runProjectStatus,
+  runProjectPush,
+} from '../src/projects.mjs';
+
+function parseFlags(argv) {
+  const positional = [];
+  const flags = {};
+  // Short flags that take a value (next arg is the value, not a new flag).
+  const VALUE_SHORT = new Set(['m']);
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const eq = arg.indexOf('=');
+      if (eq === -1) {
+        flags[arg.slice(2)] = true;
+      } else {
+        flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+      }
+    } else if (arg.startsWith('-') && arg.length > 1) {
+      const key = arg.slice(1);
+      if (VALUE_SHORT.has(key) && i + 1 < argv.length) {
+        flags[key] = argv[i + 1];
+        i += 1;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { positional, flags };
+}
+
+const HELP = `hiveku-sync — sync a Hiveku account into a local Claude Code folder
+
+Memory/rules/skills:
+  init <slug> [--profile=<name>]    Scaffold ./<slug>/ with .env, .mcp.json,
+                                    CLAUDE.md, and the memory/rules/skills tree.
+  pull [--profile=<name>]           Pull memory/rules/skills via MCP into the
+                                    current account folder. Reads OLYMPUS_API_KEY
+                                    and OLYMPUS_BASE_URL from ./.env.
+
+Coder projects:
+  projects                          List the account's coder projects.
+  pull-project <slug-or-id>         Pull a project's source into ./projects/<slug>/.
+                  [--branch=<name>] Records the project mapping in .hiveku/projects.json.
+  status [<slug>] [--json]          Diff local ./projects/<slug>/ vs Hiveku DB.
+                                    cd into the project folder to omit <slug>.
+  push  [<slug>] -m "<message>"     Save+commit changed files to the project's
+                  [--branch=<name>] GitHub branch via MCP (same path as the v3
+                  [--include-deletes] sidebar). Add --include-deletes to commit
+                  [--dry-run]       paths missing locally as deletions.
+
+  help                              Show this message.
+
+Profiles: full, sales, marketing, helpdesk, pm, dev
+`;
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const { positional, flags } = parseFlags(rest);
+
+  switch (cmd) {
+    case 'init': {
+      const slug = positional[0];
+      if (!slug) {
+        console.error('Error: slug required.\n');
+        console.error(HELP);
+        process.exit(1);
+      }
+      const result = await runInit({
+        slug,
+        parentDir: flags['parent'],
+        profile: flags['profile'] || 'full',
+      });
+      console.log(`Initialized ${result.folder}`);
+      console.log(`  profile: ${result.profile}`);
+      console.log(
+        `  next: cp ${result.folder}/.env.example ${result.folder}/.env and paste your OLYMPUS_API_KEY`,
+      );
+      if (result.workspaceAdded) {
+        console.log(`  workspace: added entry to hiveku.code-workspace`);
+      }
+      console.log(`  then: cd ${result.folder} && hiveku-sync pull`);
+      break;
+    }
+    case 'pull': {
+      const summary = await runPull({ profile: flags['profile'] });
+      console.log(`Pulled ${summary.total} entries (profile=${summary.profile}, base=${summary.baseUrl}):`);
+      for (const [type, count] of Object.entries(summary.by_type)) {
+        console.log(`  ${type}: ${count}`);
+      }
+      if (summary.removed_remotely.length > 0) {
+        console.log('\nNote: these files were present in the last sync but are no longer in Olympus:');
+        for (const f of summary.removed_remotely) console.log(`  ${f}`);
+        console.log('They were left on disk. Delete them manually if no longer needed.');
+      }
+      if (summary.errors.length > 0) {
+        console.error('\nErrors:');
+        for (const e of summary.errors) console.error(`  ${e.type}: ${e.message}`);
+        process.exit(2);
+      }
+      break;
+    }
+    case 'projects': {
+      await runProjectsList({ profile: flags['profile'] });
+      break;
+    }
+    case 'pull-project': {
+      const slugOrId = positional[0];
+      if (!slugOrId) {
+        console.error('Error: pull-project requires a project slug or UUID.\n');
+        console.error(HELP);
+        process.exit(1);
+      }
+      await runPullProject({
+        slugOrId,
+        profile: flags['profile'],
+        branch: flags['branch'],
+      });
+      break;
+    }
+    case 'status': {
+      await runProjectStatus({
+        slug: positional[0],
+        profile: flags['profile'],
+        json: !!flags['json'],
+      });
+      break;
+    }
+    case 'push': {
+      // Positional layout: `push [<slug>]`. -m / --message is required.
+      const slug = positional[0];
+      const message = flags['m'] || flags['message'];
+      if (!message) {
+        console.error('Error: push requires -m "<commit message>"\n');
+        console.error(HELP);
+        process.exit(1);
+      }
+      await runProjectPush({
+        slug,
+        message,
+        branch: flags['branch'],
+        profile: flags['profile'],
+        includeDeletes: !!flags['include-deletes'],
+        dryRun: !!flags['dry-run'],
+      });
+      break;
+    }
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      console.log(HELP);
+      break;
+    default:
+      console.error(`Unknown command: ${cmd}\n`);
+      console.error(HELP);
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(`hiveku-sync: ${err.message}`);
+  if (process.env.HIVEKU_SYNC_DEBUG) console.error(err.stack);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@hiveku-apps/sync",
+  "version": "0.1.0",
+  "description": "Sync a Hiveku account's memory/rules/skills + coder projects into a local folder. Pairs with the Hiveku MCP at core.hiveku.com/mcp so Claude Code can drive Hiveku tools per-folder.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Hiveku",
+  "homepage": "https://app.hiveku.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/locus2012/hiveku-sync.git"
+  },
+  "bugs": {
+    "url": "https://github.com/locus2012/hiveku-sync/issues"
+  },
+  "keywords": [
+    "hiveku",
+    "mcp",
+    "claude",
+    "claude-code",
+    "cli",
+    "olympus"
+  ],
+  "bin": {
+    "hiveku-sync": "bin/hiveku-sync.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node bin/hiveku-sync.mjs"
+  }
+}

package/src/init.mjs

@@ -0,0 +1,194 @@
+/**
+ * `hiveku-sync init <slug>` — scaffold a per-account folder with .env.example,
+ * .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.
+ */
+
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+import { writeFileAtomic, safeSlug, TYPE_TO_FOLDER } from './util.mjs';
+
+const VALID_PROFILES = ['full', 'sales', 'marketing', 'helpdesk', 'pm', 'dev'];
+const DEFAULT_BASE_URL = 'https://core.hiveku.com';
+
+function dotenvTemplate({ profile, baseUrl }) {
+  return [
+    '# Hiveku account credentials',
+    '# Mint a key at https://app.hiveku.com/<account_id>/dashboard/settings',
+    '',
+    'OLYMPUS_API_KEY=olp_replace_me',
+    `OLYMPUS_BASE_URL=${baseUrl}`,
+    `HIVEKU_PROFILE=${profile}`,
+    '',
+  ].join('\n');
+}
+
+function mcpJsonTemplate({ profile, baseUrl }) {
+  const url =
+    profile === 'full'
+      ? `${baseUrl}/mcp`
+      : `${baseUrl}/mcp?profile=${encodeURIComponent(profile)}`;
+  return (
+    JSON.stringify(
+      {
+        mcpServers: {
+          hiveku: {
+            type: 'http',
+            url,
+            headers: {
+              Authorization: 'Bearer ${OLYMPUS_API_KEY}',
+            },
+          },
+        },
+      },
+      null,
+      2,
+    ) + '\n'
+  );
+}
+
+function claudeMdTemplate({ slug, profile }) {
+  return `# ${slug} — Hiveku Account Workspace
+
+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
+
+- \`memory/\` — synced memory documents (\`hiveku-sync pull\` writes here)
+- \`rules/\` — synced agent rules
+- \`skills/\` — synced agent skills
+- \`commands/\`, \`agents/\`, \`identity/\` — other memory types
+- \`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
+
+Then run \`hiveku-sync pull\` to refresh the local copies.
+
+## Coder projects (pull / status / push)
+
+Each account has zero or more coder projects (Next.js, Vite, Python Lambda,
+Expo). To work on one locally:
+
+\`\`\`bash
+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.)
+\`\`\`
+
+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):
+
+\`\`\`bash
+hiveku-sync status                          # diff local vs Hiveku DB
+hiveku-sync push -m "fix: header overlap"   # save + commit changed files via MCP
+\`\`\`
+
+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.
+
+## Tenant scope
+
+The API key in \`.env\` is **pinned to one Hiveku account**. You cannot switch
+accounts mid-session — open a different folder instead. Each account is one
+folder; folder boundaries are tenant boundaries.
+
+## Profile
+
+The active tool profile is \`${profile}\`. Change \`HIVEKU_PROFILE\` in \`.env\`
+and reload the MCP server in your editor to switch (\`full\`, \`sales\`,
+\`marketing\`, \`helpdesk\`, \`pm\`, \`dev\`). The coder project tools
+(\`project_*\`) are in the \`dev\` and \`full\` profiles.
+`;
+}
+
+const GITIGNORE_TEMPLATE = ['.env', '.hiveku/', ''].join('\n');
+
+async function appendToWorkspaceFile(workspaceFilePath, folderRelPath) {
+  // Idempotent: if the workspace file exists and already includes the folder, skip.
+  // Otherwise create or update it.
+  let workspace = { folders: [], settings: {} };
+  if (existsSync(workspaceFilePath)) {
+    try {
+      workspace = JSON.parse(await readFile(workspaceFilePath, 'utf8'));
+      if (!Array.isArray(workspace.folders)) workspace.folders = [];
+    } catch {
+      // Corrupt file — back it up rather than overwriting silently.
+      await writeFile(`${workspaceFilePath}.bak`, await readFile(workspaceFilePath));
+      workspace = { folders: [], settings: {} };
+    }
+  }
+  if (workspace.folders.some((f) => f.path === folderRelPath)) return false;
+  workspace.folders.push({ path: folderRelPath });
+  await writeFileAtomic(workspaceFilePath, JSON.stringify(workspace, null, 2) + '\n');
+  return true;
+}
+
+export async function runInit({ slug, parentDir, profile = 'full' }) {
+  if (!slug) throw new Error('slug is required, e.g. hiveku-sync init acme-corp');
+  if (!VALID_PROFILES.includes(profile)) {
+    throw new Error(
+      `Invalid profile '${profile}'. Valid: ${VALID_PROFILES.join(', ')}`,
+    );
+  }
+  const safe = safeSlug(slug);
+  const base = parentDir ? resolve(parentDir) : process.cwd();
+  const folder = join(base, safe);
+
+  if (existsSync(folder)) {
+    throw new Error(
+      `Refusing to init — ${folder} already exists. Pick a different slug or remove it first.`,
+    );
+  }
+
+  await mkdir(folder, { recursive: true });
+  for (const sub of Object.values(TYPE_TO_FOLDER)) {
+    await mkdir(join(folder, sub), { recursive: true });
+  }
+  await mkdir(join(folder, '.hiveku'), { recursive: true });
+
+  await writeFileAtomic(
+    join(folder, '.env.example'),
+    dotenvTemplate({ profile, baseUrl: DEFAULT_BASE_URL }),
+  );
+  await writeFileAtomic(
+    join(folder, '.mcp.json'),
+    mcpJsonTemplate({ profile, baseUrl: DEFAULT_BASE_URL }),
+  );
+  await writeFileAtomic(
+    join(folder, 'CLAUDE.md'),
+    claudeMdTemplate({ slug: safe, profile }),
+  );
+  await writeFileAtomic(join(folder, '.gitignore'), GITIGNORE_TEMPLATE);
+
+  const workspaceAdded = await appendToWorkspaceFile(
+    join(base, 'hiveku.code-workspace'),
+    `./${safe}`,
+  );
+
+  return { folder, slug: safe, profile, workspaceAdded };
+}

package/src/mcp.mjs

@@ -0,0 +1,96 @@
+/**
+ * Minimal MCP JSON-RPC client over Streamable HTTP.
+ * Speaks just enough of the protocol to initialize + call tools.
+ */
+
+const PROTOCOL_VERSION = '2024-11-05';
+
+export class HivekuMcpClient {
+  constructor({ baseUrl, apiKey, profile = 'full' }) {
+    if (!baseUrl) throw new Error('baseUrl required');
+    if (!apiKey) throw new Error('apiKey required (OLYMPUS_API_KEY)');
+    this.baseUrl = baseUrl.replace(/\/+$/, '');
+    this.apiKey = apiKey;
+    this.profile = profile;
+    this.sessionId = null;
+    this.serverInfo = null;
+    this.nextId = 1;
+  }
+
+  get endpoint() {
+    const url = new URL(`${this.baseUrl}/mcp`);
+    if (this.profile && this.profile !== 'full') {
+      url.searchParams.set('profile', this.profile);
+    }
+    return url.toString();
+  }
+
+  async _request(method, params) {
+    const id = this.nextId++;
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+    };
+    if (this.sessionId) headers['Mcp-Session-Id'] = this.sessionId;
+
+    const res = await fetch(this.endpoint, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),
+    });
+
+    const sessionHeader = res.headers.get('mcp-session-id');
+    if (sessionHeader) this.sessionId = sessionHeader;
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(`MCP HTTP ${res.status}: ${text.slice(0, 500)}`);
+    }
+
+    if (res.status === 204) return null;
+
+    const body = await res.json();
+    if (body.error) {
+      throw new Error(`MCP error ${body.error.code}: ${body.error.message}`);
+    }
+    return body.result;
+  }
+
+  async initialize() {
+    const result = await this._request('initialize', {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: 'hiveku-sync', version: '0.1.0' },
+    });
+    this.serverInfo = result?.serverInfo || null;
+    await this._request('notifications/initialized', {}).catch(() => {});
+    return result;
+  }
+
+  async callTool(name, args = {}) {
+    const result = await this._request('tools/call', { name, arguments: args });
+    if (result?.isError) {
+      const text = result.content?.[0]?.text || 'unknown tool error';
+      throw new Error(`Tool ${name} errored: ${text}`);
+    }
+    return result;
+  }
+
+  /**
+   * Convenience wrapper for tools that return one JSON-serialized text block.
+   * Returns the parsed payload or throws if it can't parse.
+   */
+  async callToolJson(name, args = {}) {
+    const result = await this.callTool(name, args);
+    const text = result?.content?.[0]?.text;
+    if (typeof text !== 'string') {
+      throw new Error(`Tool ${name} returned no text content`);
+    }
+    try {
+      return JSON.parse(text);
+    } catch (err) {
+      throw new Error(`Tool ${name} returned non-JSON content: ${text.slice(0, 200)}`);
+    }
+  }
+}

package/src/projects.mjs

@@ -0,0 +1,435 @@
+/**
+ * `hiveku-sync` project commands — pull a Hiveku coder project into
+ * ./projects/<slug>/, show diff vs remote, and commit edits back via MCP.
+ *
+ * No native git clone. The MCP server handles GitHub commits via the
+ * account's installed GitHub App — same code path as the v3 editor sidebar.
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile, stat } from 'node:fs/promises';
+import { dirname, join, relative, sep } from 'node:path';
+
+import { HivekuMcpClient } from './mcp.mjs';
+import {
+  loadDotenv,
+  readEnv,
+  safeSlug,
+  writeFileAtomic,
+  readJson,
+} from './util.mjs';
+
+const PROJECTS_DIR = 'projects';
+const PROJECTS_MANIFEST = '.hiveku/projects.json';
+
+const IGNORE_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '.next',
+  '.turbo',
+  '.cache',
+  'dist',
+  'build',
+  '.expo',
+  '.vercel',
+  '.fly',
+  '.hiveku',
+]);
+
+const RUN_HINTS = {
+  nextjs: 'npm install && npm run dev   # Next.js dev server',
+  vite: 'npm install && npm run dev   # Vite dev server',
+  'react-app': 'npm install && npm run dev',
+  'python-lambda': 'python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt',
+  expo: 'npm install && npx expo start',
+  static: 'npx serve .',
+};
+
+function sha256(content) {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+async function clientFromCwd({ profileOverride } = {}) {
+  const baseDir = process.cwd();
+  const dotenv = await loadDotenv(join(baseDir, '.env'));
+  const apiKey = readEnv(process.env, dotenv, 'OLYMPUS_API_KEY');
+  const baseUrl = readEnv(process.env, dotenv, 'OLYMPUS_BASE_URL', 'https://core.hiveku.com');
+  const profile =
+    profileOverride || readEnv(process.env, dotenv, 'HIVEKU_PROFILE', 'full');
+  if (!apiKey) {
+    throw new Error(
+      `OLYMPUS_API_KEY not set. Add it to ${join(baseDir, '.env')} or export it.`,
+    );
+  }
+  const client = new HivekuMcpClient({ baseUrl, apiKey, profile });
+  await client.initialize();
+  return { client, baseDir, baseUrl, profile };
+}
+
+async function listAllRemoteFiles(client, projectId) {
+  const all = [];
+  let page = 1;
+  const limit = 500;
+  while (true) {
+    const result = await client.callToolJson('project_files_list', {
+      project_id: projectId,
+      page,
+      limit,
+    });
+    const batch = result?.data || [];
+    all.push(...batch);
+    const totalPages = result?.pagination?.total_pages ?? 1;
+    if (page >= totalPages || batch.length === 0) break;
+    page += 1;
+  }
+  return all;
+}
+
+async function walkLocalFiles(rootDir) {
+  const out = [];
+  async function recurse(dir) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      if (IGNORE_DIRS.has(entry.name)) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await recurse(full);
+      } else if (entry.isFile()) {
+        out.push(full);
+      }
+    }
+  }
+  await recurse(rootDir);
+  return out;
+}
+
+async function buildLocalManifest(rootDir) {
+  const files = await walkLocalFiles(rootDir);
+  const manifest = [];
+  for (const abs of files) {
+    const rel = relative(rootDir, abs).split(sep).join('/');
+    const buf = await readFile(abs);
+    manifest.push({ path: rel, sha256: sha256(buf.toString('utf8')) });
+  }
+  return manifest;
+}
+
+function runHintForProjectType(type) {
+  return RUN_HINTS[type] || `# Unknown project_type "${type}". Inspect package.json/requirements.txt to find the dev command.`;
+}
+
+async function readProjectsManifest(baseDir) {
+  const data = await readJson(join(baseDir, PROJECTS_MANIFEST));
+  return data && typeof data === 'object' ? data : { projects: {} };
+}
+
+async function writeProjectsManifest(baseDir, manifest) {
+  await writeFileAtomic(join(baseDir, PROJECTS_MANIFEST), JSON.stringify(manifest, null, 2));
+}
+
+async function resolveProject(client, slugOrId) {
+  // Accept either UUID (use directly) or slug (look up via list_projects).
+  const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (UUID_RE.test(slugOrId)) {
+    const result = await client.callToolJson('get_project', { project_id: slugOrId });
+    return result?.data || result;
+  }
+  const result = await client.callToolJson('list_projects', { search: slugOrId });
+  const list = result?.data || [];
+  const match =
+    list.find((p) => p.slug === slugOrId) ||
+    list.find((p) => p.name?.toLowerCase() === slugOrId.toLowerCase()) ||
+    list[0];
+  if (!match) {
+    throw new Error(`No project found matching "${slugOrId}"`);
+  }
+  return match;
+}
+
+export async function runProjectsList({ profile } = {}) {
+  const { client } = await clientFromCwd({ profileOverride: profile });
+  const result = await client.callToolJson('list_projects', {});
+  const list = result?.data || [];
+  if (list.length === 0) {
+    console.log('No projects on this account.');
+    return;
+  }
+  console.log(`${list.length} project${list.length !== 1 ? 's' : ''}:\n`);
+  for (const p of list) {
+    const type = p.project_type || '?';
+    const slug = p.slug || p.name || p.id;
+    console.log(`  ${slug.padEnd(32)} ${type.padEnd(14)} ${p.id}`);
+  }
+}
+
+export async function runPullProject({ slugOrId, profile, branch }) {
+  if (!slugOrId) throw new Error('Provide a project slug or UUID');
+  const { client, baseDir } = await clientFromCwd({ profileOverride: profile });
+  const project = await resolveProject(client, slugOrId);
+  const projectId = project.id;
+  const localSlug = safeSlug(project.slug || project.name || projectId);
+  const dest = join(baseDir, PROJECTS_DIR, localSlug);
+
+  console.log(`Pulling ${project.name || project.slug || projectId} (type=${project.project_type || '?'})`);
+  console.log(`  Project ID: ${projectId}`);
+  console.log(`  Destination: ${dest}`);
+
+  const files = await listAllRemoteFiles(client, projectId);
+  if (files.length === 0) {
+    console.log('  No files to pull (project is empty).');
+  }
+
+  let written = 0;
+  let skipped = 0;
+  for (const fileMeta of files) {
+    const result = await client.callToolJson('project_file_get', {
+      project_id: projectId,
+      file_path: fileMeta.file_path,
+    });
+    const fileBody = result?.file || result?.data?.file || result?.data;
+    if (!fileBody || typeof fileBody.file_content !== 'string') {
+      skipped += 1;
+      continue;
+    }
+    let contentBuf;
+    if (fileBody.file_content.startsWith('__BINARY_BASE64__')) {
+      contentBuf = Buffer.from(
+        fileBody.file_content.substring('__BINARY_BASE64__'.length),
+        'base64',
+      );
+    } else {
+      contentBuf = Buffer.from(fileBody.file_content, 'utf8');
+    }
+    const outPath = join(dest, fileMeta.file_path);
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFileAtomic(outPath, contentBuf);
+    written += 1;
+  }
+
+  // Drop a RUN.md keyed off project_type so the user knows how to start it.
+  const runMd = [
+    `# ${project.name || project.slug || projectId}`,
+    '',
+    `Project type: \`${project.project_type || 'unknown'}\``,
+    `Hiveku project id: \`${projectId}\``,
+    branch ? `Tracking branch: \`${branch}\`` : '',
+    '',
+    '## Run locally',
+    '',
+    '```bash',
+    runHintForProjectType(project.project_type),
+    '```',
+    '',
+    '## Commit changes back',
+    '',
+    'This folder is NOT a git clone — it\'s a snapshot. Use the Hiveku MCP `project_commit` tool',
+    'to write edits back to the project\'s GitHub branch (same path the v3 sidebar uses).',
+    '',
+    'From this folder:',
+    '',
+    '```bash',
+    `hiveku-sync status   # diff local vs remote`,
+    `hiveku-sync push -m "your message"   # save + commit changed files via MCP`,
+    '```',
+    '',
+    'Or ask Claude in this workspace to commit the changed files for you.',
+    '',
+  ]
+    .filter((line) => line !== undefined)
+    .join('\n');
+  await writeFileAtomic(join(dest, 'RUN.md'), runMd);
+
+  // Persist project metadata so status/push know which project this folder maps to.
+  const manifest = await readProjectsManifest(baseDir);
+  manifest.projects = manifest.projects || {};
+  manifest.projects[localSlug] = {
+    project_id: projectId,
+    name: project.name || project.slug || localSlug,
+    project_type: project.project_type || null,
+    branch: branch || null,
+    last_pull_at: new Date().toISOString(),
+  };
+  await writeProjectsManifest(baseDir, manifest);
+
+  console.log(`  Wrote ${written} file${written !== 1 ? 's' : ''}${skipped ? ` (${skipped} skipped — no content)` : ''}`);
+  console.log(`  Run hints in ${join(dest, 'RUN.md')}`);
+  return { dest, written, skipped, projectId, slug: localSlug };
+}
+
+async function findProjectFolder({ slug, baseDir }) {
+  // Allow status/push to be called from inside ./projects/<slug>/, ./<slug>/,
+  // or the account root with an explicit slug arg.
+  const manifest = await readProjectsManifest(baseDir);
+  const known = manifest.projects || {};
+
+  if (slug) {
+    if (known[slug]) return { slug, info: known[slug], folder: join(baseDir, PROJECTS_DIR, slug) };
+    throw new Error(`Unknown project slug "${slug}". Run \`hiveku-sync projects\` to list, or pull-project first.`);
+  }
+
+  // Try to auto-detect from cwd.
+  const cwd = process.cwd();
+  const projectsRoot = join(baseDir, PROJECTS_DIR);
+  if (cwd.startsWith(projectsRoot + sep)) {
+    const rel = relative(projectsRoot, cwd).split(sep)[0];
+    if (known[rel]) return { slug: rel, info: known[rel], folder: join(projectsRoot, rel) };
+  }
+  throw new Error(
+    'Could not determine which project. cd into ./projects/<slug>/ or pass an explicit slug.',
+  );
+}
+
+function summarizeDiff(diff) {
+  return {
+    changed: diff.changed?.length || 0,
+    only_local: diff.only_local?.length || 0,
+    only_remote: diff.only_remote?.length || 0,
+    same: diff.same_count || 0,
+  };
+}
+
+export async function runProjectStatus({ slug, profile, json = false }) {
+  // Resolve baseDir as the account folder. If we're inside ./projects/<x>/,
+  // walk up two levels. Otherwise treat cwd as the account folder.
+  const cwd = process.cwd();
+  const projectsIdx = cwd.indexOf(`${sep}${PROJECTS_DIR}${sep}`);
+  const baseDir =
+    projectsIdx > -1 ? cwd.slice(0, projectsIdx) : cwd;
+
+  const { client } = await clientFromCwd({ profileOverride: profile });
+  const { slug: resolvedSlug, info, folder } = await findProjectFolder({ slug, baseDir });
+
+  if (!existsSync(folder)) {
+    throw new Error(`Project folder ${folder} doesn't exist — run pull-project first.`);
+  }
+
+  const localManifest = await buildLocalManifest(folder);
+  const diff = (await client.callToolJson('project_files_status', {
+    project_id: info.project_id,
+    local: localManifest,
+  })).data;
+
+  if (json) {
+    console.log(JSON.stringify({ slug: resolvedSlug, project_id: info.project_id, ...diff }, null, 2));
+    return diff;
+  }
+
+  const sum = summarizeDiff(diff);
+  console.log(`Project: ${resolvedSlug}  (${info.project_id})`);
+  console.log(`  changed:     ${sum.changed}`);
+  console.log(`  only_local:  ${sum.only_local}`);
+  console.log(`  only_remote: ${sum.only_remote}`);
+  console.log(`  unchanged:   ${sum.same}`);
+  if (sum.changed > 0) {
+    console.log('\nChanged files:');
+    for (const f of diff.changed.slice(0, 20)) console.log(`  M  ${f.path}`);
+    if (diff.changed.length > 20) console.log(`  ... and ${diff.changed.length - 20} more`);
+  }
+  if (sum.only_local > 0) {
+    console.log('\nLocal-only (will be added on push):');
+    for (const f of diff.only_local.slice(0, 20)) console.log(`  +  ${f.path}`);
+    if (diff.only_local.length > 20) console.log(`  ... and ${diff.only_local.length - 20} more`);
+  }
+  if (sum.only_remote > 0) {
+    console.log('\nRemote-only (deleted locally or never pulled — pass --include-deletes to push to commit deletions):');
+    for (const f of diff.only_remote.slice(0, 20)) console.log(`  -  ${f.path}`);
+    if (diff.only_remote.length > 20) console.log(`  ... and ${diff.only_remote.length - 20} more`);
+  }
+  return diff;
+}
+
+export async function runProjectPush({
+  slug,
+  message,
+  branch,
+  profile,
+  includeDeletes = false,
+  dryRun = false,
+}) {
+  if (!message || !message.trim()) {
+    throw new Error('Provide a commit message via -m "..."');
+  }
+
+  const cwd = process.cwd();
+  const projectsIdx = cwd.indexOf(`${sep}${PROJECTS_DIR}${sep}`);
+  const baseDir = projectsIdx > -1 ? cwd.slice(0, projectsIdx) : cwd;
+
+  const { client } = await clientFromCwd({ profileOverride: profile });
+  const { slug: resolvedSlug, info, folder } = await findProjectFolder({ slug, baseDir });
+
+  if (!existsSync(folder)) {
+    throw new Error(`Project folder ${folder} doesn't exist — run pull-project first.`);
+  }
+
+  const localManifest = await buildLocalManifest(folder);
+  const diff = (await client.callToolJson('project_files_status', {
+    project_id: info.project_id,
+    local: localManifest,
+  })).data;
+
+  const toCommit = [
+    ...(diff.changed || []).map((c) => c.path),
+    ...(diff.only_local || []).map((c) => c.path),
+  ];
+  const toDelete = includeDeletes ? (diff.only_remote || []).map((c) => c.path) : [];
+
+  if (toCommit.length === 0 && toDelete.length === 0) {
+    console.log('Nothing to commit — local is in sync with remote.');
+    return { skipped: true };
+  }
+
+  // Load file contents from disk for everything we're committing.
+  const files = [];
+  for (const path of toCommit) {
+    const abs = join(folder, path);
+    let content;
+    let encoding = 'utf-8';
+    const data = await readFile(abs);
+    // Detect text-vs-binary: try utf-8 round-trip, fall back to base64 on
+    // replacement chars (matches the heuristic the builder editor uses).
+    const asUtf8 = data.toString('utf8');
+    if (asUtf8.includes('�')) {
+      content = data.toString('base64');
+      encoding = 'base64';
+    } else {
+      content = asUtf8;
+    }
+    files.push({ path, content, encoding });
+  }
+
+  if (dryRun) {
+    console.log(`[dry run] would commit ${files.length} file${files.length !== 1 ? 's' : ''} and delete ${toDelete.length}.`);
+    return { dryRun: true, files: files.map((f) => f.path), deletedFiles: toDelete };
+  }
+
+  console.log(`Committing ${files.length} file${files.length !== 1 ? 's' : ''}${toDelete.length ? ` + ${toDelete.length} deletion${toDelete.length !== 1 ? 's' : ''}` : ''}…`);
+  const result = await client.callToolJson('project_commit', {
+    project_id: info.project_id,
+    message: message.trim(),
+    branch: branch || info.branch || undefined,
+    files,
+    deletedFiles: toDelete.length > 0 ? toDelete : undefined,
+  });
+  const data = result?.data || result;
+  console.log(`  ✓ commit_sha: ${data?.commit_sha || '(none)'}`);
+  console.log(`  branch:      ${data?.branch || '(default)'}`);
+
+  // Update last_push timestamp in the manifest.
+  const manifest = await readProjectsManifest(baseDir);
+  manifest.projects = manifest.projects || {};
+  manifest.projects[resolvedSlug] = {
+    ...(manifest.projects[resolvedSlug] || { project_id: info.project_id }),
+    last_push_at: new Date().toISOString(),
+    last_commit_sha: data?.commit_sha || null,
+  };
+  await writeProjectsManifest(baseDir, manifest);
+
+  return data;
+}

package/src/pull.mjs

@@ -0,0 +1,140 @@
+/**
+ * `hiveku-sync pull` — fetches memory/rules/skills via the MCP memory_list tool
+ * and writes them as local .md files under the current folder.
+ *
+ * Safety: refuses to overwrite when the .env API key no longer matches the
+ * manifest's recorded key preview (prevents pulling Account A's data into a
+ * folder previously synced for Account B — the 2026-05-11 cross-tenant bug
+ * class).
+ */
+
+import { join } from 'node:path';
+
+import { HivekuMcpClient } from './mcp.mjs';
+import {
+  loadDotenv,
+  readEnv,
+  safeSlug,
+  writeFileAtomic,
+  readJson,
+  toFrontmatter,
+  extractDepartmentTag,
+  TYPE_TO_FOLDER,
+  SUPPORTED_TYPES,
+} from './util.mjs';
+
+const MANIFEST_PATH = '.hiveku/manifest.json';
+
+function keyPreview(apiKey) {
+  return apiKey.slice(0, 10);
+}
+
+async function fetchType(client, type) {
+  const result = await client.callToolJson('memory_list', { type });
+  if (!result?.data || !Array.isArray(result.data)) {
+    throw new Error(`memory_list(${type}) returned unexpected shape`);
+  }
+  return result.data;
+}
+
+function entryFilename(entry) {
+  const name = entry.name || entry.domain.replace(/^_[^:]+:/, '');
+  return `${safeSlug(name)}.md`;
+}
+
+function renderEntry(entry, type) {
+  const body = entry.content ?? '';
+  const department = extractDepartmentTag(body);
+  const frontmatter = toFrontmatter({
+    id: entry.id,
+    name: entry.name,
+    type,
+    domain: entry.domain,
+    department,
+    project_id: entry.project_id,
+    version: entry.version,
+    updated_at: entry.updated_at,
+  });
+  return `${frontmatter}${body}`;
+}
+
+export async function runPull({ baseDir = process.cwd(), profile } = {}) {
+  const envPath = join(baseDir, '.env');
+  const dotenv = await loadDotenv(envPath);
+  const apiKey = readEnv(process.env, dotenv, 'OLYMPUS_API_KEY');
+  const baseUrl = readEnv(
+    process.env,
+    dotenv,
+    'OLYMPUS_BASE_URL',
+    'https://core.hiveku.com',
+  );
+  const activeProfile = profile || readEnv(process.env, dotenv, 'HIVEKU_PROFILE', 'full');
+
+  if (!apiKey) {
+    throw new Error(
+      `OLYMPUS_API_KEY not set. Add it to ${envPath} or export it before running.`,
+    );
+  }
+
+  // Manifest pin: refuse if the key changed under us.
+  const manifestPath = join(baseDir, MANIFEST_PATH);
+  const manifest = await readJson(manifestPath);
+  if (manifest?.api_key_preview && manifest.api_key_preview !== keyPreview(apiKey)) {
+    throw new Error(
+      `Refusing to pull — API key in .env (preview ${keyPreview(apiKey)}) does not match ` +
+        `the manifest at ${manifestPath} (preview ${manifest.api_key_preview}). ` +
+        `If you really meant to re-bind this folder to a different account, delete ` +
+        `${manifestPath} first.`,
+    );
+  }
+
+  const client = new HivekuMcpClient({ baseUrl, apiKey, profile: activeProfile });
+  await client.initialize();
+
+  const summary = { total: 0, by_type: {}, errors: [] };
+  const writtenFiles = new Set();
+
+  for (const type of SUPPORTED_TYPES) {
+    const folder = TYPE_TO_FOLDER[type];
+    let entries;
+    try {
+      entries = await fetchType(client, type);
+    } catch (err) {
+      summary.errors.push({ type, message: err.message });
+      continue;
+    }
+    summary.by_type[type] = entries.length;
+    summary.total += entries.length;
+
+    for (const entry of entries) {
+      const filename = entryFilename(entry);
+      const fullPath = join(baseDir, folder, filename);
+      await writeFileAtomic(fullPath, renderEntry(entry, type));
+      writtenFiles.add(`${folder}/${filename}`);
+    }
+  }
+
+  // v1: don't delete stale files; just record them in the manifest so the
+  // user can prune manually if they want. Avoids losing local edits.
+  const previouslySeen = new Set(manifest?.files ?? []);
+  const removedRemotely = [...previouslySeen].filter((f) => !writtenFiles.has(f));
+
+  await writeFileAtomic(
+    manifestPath,
+    JSON.stringify(
+      {
+        api_key_preview: keyPreview(apiKey),
+        base_url: baseUrl,
+        profile: activeProfile,
+        last_sync_at: new Date().toISOString(),
+        counts: summary.by_type,
+        files: [...writtenFiles].sort(),
+        removed_remotely_since_last_sync: removedRemotely,
+      },
+      null,
+      2,
+    ),
+  );
+
+  return { ...summary, removed_remotely: removedRemotely, profile: activeProfile, baseUrl };
+}

package/src/util.mjs

@@ -0,0 +1,105 @@
+/**
+ * Shared helpers for hiveku-sync.
+ */
+
+import { readFile, writeFile, rename, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/** Parse a .env file into a plain object. Strips quotes, ignores comments. */
+export async function loadDotenv(envPath) {
+  if (!existsSync(envPath)) return {};
+  const raw = await readFile(envPath, 'utf8');
+  const out = {};
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+/** Resolve required env value from process.env first, then a parsed .env map. */
+export function readEnv(processEnv, dotenv, key, fallback) {
+  return processEnv[key] ?? dotenv[key] ?? fallback;
+}
+
+/** Make a filesystem-safe filename slug from an arbitrary string. */
+export function safeSlug(name) {
+  return (
+    String(name || 'unnamed')
+      .toLowerCase()
+      .replace(/[^a-z0-9._-]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .slice(0, 100) || 'unnamed'
+  );
+}
+
+/** Atomic write — write to <path>.tmp then rename. */
+export async function writeFileAtomic(path, contents) {
+  await mkdir(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp`;
+  await writeFile(tmp, contents, 'utf8');
+  await rename(tmp, path);
+}
+
+/** Read JSON file or return null on missing/parse error. */
+export async function readJson(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** YAML frontmatter encoder for scalar fields. */
+export function toFrontmatter(fields) {
+  const lines = ['---'];
+  for (const [k, v] of Object.entries(fields)) {
+    if (v === undefined || v === null) continue;
+    const s = String(v).replace(/"/g, '\\"');
+    lines.push(`${k}: "${s}"`);
+  }
+  lines.push('---', '');
+  return lines.join('\n');
+}
+
+/** Map memory `type` → folder name. */
+export const TYPE_TO_FOLDER = {
+  memory: 'memory',
+  rule: 'rules',
+  skill: 'skills',
+  command: 'commands',
+  agent: 'agents',
+  identity: 'identity',
+};
+
+export const SUPPORTED_TYPES = Object.keys(TYPE_TO_FOLDER);
+
+/** Extract a department tag from content. Looks for HTML or YAML markers. */
+export function extractDepartmentTag(content) {
+  if (!content) return null;
+  const htmlMatch = content.match(/<!--\s*department:\s*([a-z0-9_-]+)\s*-->/i);
+  if (htmlMatch) return htmlMatch[1];
+  const yamlMatch = content.match(/^department:\s*["']?([a-z0-9_-]+)["']?\s*$/im);
+  if (yamlMatch) return yamlMatch[1];
+  return null;
+}
+
+/** Resolve account base directory (default: ./). */
+export function defaultBaseDir(cwd = process.cwd()) {
+  return cwd;
+}
+
+export { join };