@hiveku-apps/sync 0.3.2 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiveku-apps/sync",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Sync a Hiveku account's memory/rules/skills + coder projects into a local folder, and ship projects (push/deploy/pull-env) from the terminal. Pairs with the Hiveku MCP at core.hiveku.com/mcp so Claude Code can drive Hiveku tools per-folder.",
   "type": "module",
   "license": "MIT",

package/src/projects.mjs

@@ -47,8 +47,37 @@ const RUN_HINTS = {
   'python-lambda': 'python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt',
   expo: 'npm install && npx expo start',
   static: 'npx serve .',
+  // The server's name for a static site is `static-html` (site_create's enum);
+  // `static` above is kept for rows created before that name settled.
+  'static-html': 'npx serve .',
+  external:
+    '# External site: there is no code to run. Manage it from the Hiveku dashboard (Webflow sites: /dashboard/<project id>/webflow) or the webflow_* MCP tools.',
 };
 
+/**
+ * Project types with no code tree to mirror. Mirrors the builder's
+ * NO_LOCAL_CODE_TYPES minus python-lambda, which hiveku-sync still pulls and
+ * ships with the run hint above; folding it in is a separate decision.
+ */
+const EXTERNAL_TYPES = new Set(['external']);
+
+/**
+ * Refuse an external project (a site hosted on Webflow, WordPress or any other
+ * host that Hiveku only tracks) before any file, VCS or deploy call. Accepts a
+ * project_get/sites_list row (`id`) or a projects.json manifest row
+ * (`project_id`); both carry `project_type`, the former `external_platform`.
+ */
+export function refuseExternal(project) {
+  if (!project || !EXTERNAL_TYPES.has(String(project.project_type || '').toLowerCase())) return;
+  const id = project.id || project.project_id;
+  const platform = project.external_platform ? `, platform=${project.external_platform}` : '';
+  throw new Error(
+    `"${project.name || id}" is an external site (project_type=external${platform}). ` +
+      `hiveku-sync mirrors code projects only; edit this site in the Hiveku dashboard ` +
+      `(/dashboard/${id}/webflow for Webflow) or through the webflow_* MCP tools.`,
+  );
+}
+
 export function sha256(content) {
   return createHash('sha256').update(content).digest('hex');
 }
@@ -124,10 +153,21 @@ async function buildLocalManifest(rootDir) {
   return manifest;
 }
 
-function runHintForProjectType(type) {
+export function runHintForProjectType(type) {
   return RUN_HINTS[type] || `# Unknown project_type "${type}". Inspect package.json/requirements.txt to find the dev command.`;
 }
 
+/**
+ * The MCP client and account folder an entry point works with. Tests inject
+ * `client` (a fake with callToolJson) and `baseDir`; the CLI passes neither and
+ * gets the .env-configured client with cwd as the account folder.
+ */
+async function resolveClient({ client, profile, baseDir } = {}) {
+  if (client) return { client, baseDir: baseDir || process.cwd() };
+  const resolved = await clientFromCwd({ profileOverride: profile });
+  return { client: resolved.client, baseDir: baseDir || resolved.baseDir };
+}
+
 export async function readProjectsManifest(baseDir) {
   const data = await readJson(join(baseDir, PROJECTS_MANIFEST));
   return data && typeof data === 'object' ? data : { projects: {} };
@@ -137,45 +177,202 @@ export async function writeProjectsManifest(baseDir, manifest) {
   await writeFileAtomic(join(baseDir, PROJECTS_MANIFEST), JSON.stringify(manifest, null, 2));
 }
 
-export 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 UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+// sites_list and list_projects both cap `limit` at 100 server-side.
+const LIST_PAGE_LIMIT = 100;
+
+/**
+ * Two id spaces, two tool families (S2, confirmed live 2026-09-10):
+ *
+ *   website_projects  — the code this CLI pulls, pushes and deploys.
+ *                       Read with `project_get` (one) and `sites_list` (all).
+ *   pm_projects       — project-MANAGEMENT rows (tasks, owners, status), with
+ *                       project_type seo|ppc|marketing|website|... and their
+ *                       own ids. Read with `get_project` and `list_projects`.
+ *                       A PM row may point at a website project through
+ *                       `website_project_id` / `linked_site`.
+ *
+ * Until 0.3.3 resolveProject used the PM tools for both shapes: a website
+ * UUID got get_project's 404 back as the "project", and a slug got a PM row
+ * whose id then 404'd on every file call and whose project_type "website"
+ * stamped an "Unknown project_type" RUN.md. Every lookup below lands on a
+ * website_projects row, which carries the project_type and external_platform
+ * that refuseExternal reads.
+ */
+
+/** Does this error (thrown or returned) mean the row does not exist, as opposed to any other failure? */
+function isNotFoundText(text) {
+  return /"status"\s*:\s*404\b|\bproject not found\b|Olympus API returned 404\b/i.test(String(text || ''));
+}
+
+/**
+ * One lookup call that answers null for "no such row" instead of throwing.
+ * The MCP proxy flags an upstream 404 with isError, which callTool turns into
+ * a thrown Error carrying the status; older servers handed the error body
+ * back as a completed call with no `data`. Both read as null here. Anything
+ * else (network, auth, 500) still throws.
+ */
+async function lookupRow(client, toolName, args) {
+  let body;
+  try {
+    body = await client.callToolJson(toolName, args);
+  } catch (err) {
+    if (isNotFoundText(err?.message)) return null;
+    throw err;
+  }
+  const row = body && typeof body === 'object' && body.data && typeof body.data === 'object' && !Array.isArray(body.data)
+    ? body.data
+    : null;
+  if (row && row.id) return row;
+  if (body && typeof body === 'object' && body.error !== undefined) {
+    if (body.status === 404 || isNotFoundText(body.error)) return null;
+    throw new Error(`Tool ${toolName} failed: ${body.error}`);
+  }
+  return null;
+}
+
+/** Every row of a paginated list tool (sites_list, list_projects), walking `pagination.total_pages`. */
+async function listAllRows(client, toolName) {
+  const rows = [];
+  let page = 1;
+  while (true) {
+    const result = await client.callToolJson(toolName, { page, limit: LIST_PAGE_LIMIT });
+    const batch = Array.isArray(result?.data) ? result.data : [];
+    rows.push(...batch);
+    const totalPages = result?.pagination?.total_pages ?? 1;
+    if (page >= totalPages || batch.length === 0) break;
+    page += 1;
+  }
+  return rows;
+}
+
+/** The website project a PM row points at, if any. */
+function linkedWebsiteId(pmRow) {
+  if (!pmRow) return null;
+  return pmRow.website_project_id || pmRow.linked_site?.id || null;
+}
+
+const PROJECTS_HINT = 'Run `hiveku-sync projects` to list the website projects on this account.';
+
+async function resolveProjectByUuid(client, projectId) {
+  const website = await lookupRow(client, 'project_get', { project_id: projectId });
+  if (website) return website;
+
+  // Not a website id. It may be the PM project that tracks one.
+  const pmRow = await lookupRow(client, 'get_project', { project_id: projectId });
+  const linkedId = linkedWebsiteId(pmRow);
+  if (linkedId) {
+    const linked = await lookupRow(client, 'project_get', { project_id: linkedId });
+    if (linked) return linked;
+    throw new Error(
+      `${projectId} is the PM project "${pmRow.name || projectId}" (pm_projects), which links website project ${linkedId}, ` +
+        `but project_get finds no website project with that id. ${PROJECTS_HINT}`,
+    );
   }
-  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}"`);
+  if (pmRow) {
+    throw new Error(
+      `${projectId} is the PM project "${pmRow.name || projectId}" (pm_projects, the id space of get_project / list_projects) ` +
+        `and it links no website project. hiveku-sync pulls code from website projects ` +
+        `(website_projects, the id space of project_get / sites_list). ${PROJECTS_HINT}`,
+    );
   }
-  return match;
+  throw new Error(
+    `No project with id ${projectId}: it is neither a website project (website_projects, the id space of ` +
+      `project_get / sites_list) nor a PM project (pm_projects, the id space of get_project / list_projects). ${PROJECTS_HINT}`,
+  );
+}
+
+/**
+ * Match a slug against website rows: exact subdomain, then exact name
+ * (case-insensitive), then the name slugified the way pull-project names the
+ * local folder, so the folder name under ./projects/ resolves too.
+ */
+function matchSiteRow(rows, slug) {
+  const lower = slug.toLowerCase();
+  const slugified = safeSlug(slug);
+  return (
+    rows.find((row) => String(row.subdomain || '').toLowerCase() === lower) ||
+    rows.find((row) => String(row.name || '').toLowerCase() === lower) ||
+    rows.find((row) => safeSlug(row.name) === slugified) ||
+    null
+  );
+}
+
+function matchPmRow(rows, slug) {
+  const lower = slug.toLowerCase();
+  return (
+    rows.find((row) => String(row.slug || '').toLowerCase() === lower) ||
+    rows.find((row) => String(row.name || '').toLowerCase() === lower) ||
+    null
+  );
+}
+
+async function resolveProjectBySlug(client, slug) {
+  const sites = await listAllRows(client, 'sites_list');
+  const site = matchSiteRow(sites, slug);
+  if (site) return site;
+
+  // Fall back to the PM project of that slug/name and follow its link.
+  const pmRows = await listAllRows(client, 'list_projects');
+  const pmRow = matchPmRow(pmRows, slug);
+  const linkedId = linkedWebsiteId(pmRow);
+  if (linkedId) {
+    const linked = await lookupRow(client, 'project_get', { project_id: linkedId });
+    if (linked) return linked;
+    throw new Error(
+      `"${slug}" is the PM project "${pmRow.name || slug}" (pm_projects), which links website project ${linkedId}, ` +
+        `but project_get finds no website project with that id. ${PROJECTS_HINT}`,
+    );
+  }
+  if (pmRow) {
+    throw new Error(
+      `"${slug}" is the PM project "${pmRow.name || slug}" (pm_projects) and it links no website project. ` +
+        `hiveku-sync pulls code from website projects (website_projects, sites_list). ${PROJECTS_HINT}`,
+    );
+  }
+  throw new Error(
+    `No website project matching "${slug}": nothing in sites_list has that subdomain or name, and no PM project ` +
+      `(list_projects) with that slug or name links a website project. ${PROJECTS_HINT}`,
+  );
+}
+
+/**
+ * Resolve a website project (website_projects row) from a UUID or a slug.
+ * A UUID is tried as a website id (project_get) and then as a PM id
+ * (get_project → website_project_id → project_get). A slug is matched against
+ * sites_list (subdomain, then name) and then against list_projects
+ * (slug, then name) → its linked website project. The row returned always
+ * carries project_type and external_platform for refuseExternal.
+ */
+export async function resolveProject(client, slugOrId) {
+  if (UUID_RE.test(slugOrId)) return resolveProjectByUuid(client, slugOrId);
+  return resolveProjectBySlug(client, slugOrId);
 }
 
-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.');
+export async function runProjectsList({ profile, client: injectedClient } = {}) {
+  const { client } = await resolveClient({ client: injectedClient, profile });
+  const sites = await listAllRows(client, 'sites_list');
+  if (sites.length === 0) {
+    console.log('No website 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}`);
+  console.log(`${sites.length} website project${sites.length !== 1 ? 's' : ''}:\n`);
+  for (const site of sites) {
+    const type = site.project_type || '?';
+    const handle = site.subdomain || site.name || site.id;
+    const nameColumn = site.name && site.name !== handle ? `  ${site.name}` : '';
+    console.log(`  ${handle.padEnd(32)} ${type.padEnd(14)} ${site.id}${nameColumn}`);
   }
 }
 
-export async function runPullProject({ slugOrId, profile, branch }) {
+export async function runPullProject({ slugOrId, profile, branch, client: injectedClient, baseDir: baseDirOverride }) {
   if (!slugOrId) throw new Error('Provide a project slug or UUID');
-  const { client, baseDir } = await clientFromCwd({ profileOverride: profile });
+  const { client, baseDir } = await resolveClient({ client: injectedClient, profile, baseDir: baseDirOverride });
   const project = await resolveProject(client, slugOrId);
+  // An external site has no file tree: the pull would write nothing and stamp
+  // a RUN.md that says "unknown project type". Refuse before the first file call.
+  refuseExternal(project);
   const projectId = project.id;
   const localSlug = safeSlug(project.slug || project.name || projectId);
   const dest = join(baseDir, PROJECTS_DIR, localSlug);
@@ -259,6 +456,7 @@ export async function runPullProject({ slugOrId, profile, branch }) {
     project_id: projectId,
     name: project.name || project.slug || localSlug,
     project_type: project.project_type || null,
+    external_platform: project.external_platform || null,
     branch: branch || null,
     last_pull_at: new Date().toISOString(),
   };
@@ -301,16 +499,17 @@ function summarizeDiff(diff) {
   };
 }
 
-export async function runProjectStatus({ slug, profile, json = false }) {
+export async function runProjectStatus({ slug, profile, json = false, client: injectedClient, baseDir: baseDirOverride }) {
   // 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 =
+  const detectedBaseDir =
     projectsIdx > -1 ? cwd.slice(0, projectsIdx) : cwd;
 
-  const { client } = await clientFromCwd({ profileOverride: profile });
+  const { client, baseDir } = await resolveClient({ client: injectedClient, profile, baseDir: baseDirOverride || detectedBaseDir });
   const { slug: resolvedSlug, info, folder } = await findProjectFolder({ slug, baseDir });
+  refuseExternal(info);
 
   if (!existsSync(folder)) {
     throw new Error(`Project folder ${folder} doesn't exist — run pull-project first.`);
@@ -387,6 +586,8 @@ export async function runProjectPush({
   profile,
   includeDeletes = false,
   dryRun = false,
+  client: injectedClient,
+  baseDir: baseDirOverride,
 }) {
   if (!message || !message.trim()) {
     throw new Error('Provide a commit message via -m "..."');
@@ -394,10 +595,11 @@ export async function runProjectPush({
 
   const cwd = process.cwd();
   const projectsIdx = cwd.indexOf(`${sep}${PROJECTS_DIR}${sep}`);
-  const baseDir = projectsIdx > -1 ? cwd.slice(0, projectsIdx) : cwd;
+  const detectedBaseDir = projectsIdx > -1 ? cwd.slice(0, projectsIdx) : cwd;
 
-  const { client } = await clientFromCwd({ profileOverride: profile });
+  const { client, baseDir } = await resolveClient({ client: injectedClient, profile, baseDir: baseDirOverride || detectedBaseDir });
   const { slug: resolvedSlug, info, folder } = await findProjectFolder({ slug, baseDir });
+  refuseExternal(info);
 
   if (!existsSync(folder)) {
     throw new Error(`Project folder ${folder} doesn't exist — run pull-project first.`);

package/src/push.mjs

@@ -28,6 +28,7 @@ import { join, relative, sep } from 'node:path';
 import {
   clientFromCwd,
   findProjectFolder,
+  refuseExternal,
   resolveProject,
   walkLocalFiles,
   readProjectsManifest,
@@ -225,10 +226,13 @@ export async function computePushPlan({ client, projectId, folder, includeDelete
 
 // Thin CLI wrapper: resolve the MCP client + project folder from cwd, then run
 // the (fully testable) orchestration in pushProject.
-export async function runPush({ slug, profile, ...opts } = {}) {
-  const baseDir = resolveBaseDir();
-  const { client } = await clientFromCwd({ profileOverride: profile });
+export async function runPush({ slug, profile, client: injectedClient, baseDir: baseDirOverride, ...opts } = {}) {
+  const baseDir = baseDirOverride || resolveBaseDir();
+  const client = injectedClient || (await clientFromCwd({ profileOverride: profile })).client;
   const { slug: resolvedSlug, info, folder } = await findProjectFolder({ slug, baseDir });
+  // An external site (Webflow, WordPress, any tracked host) has no deploy
+  // source to push to; refuse before the diff.
+  refuseExternal(info);
   if (!existsSync(folder)) {
     throw new Error(`Project folder ${folder} doesn't exist — run pull-project first.`);
   }
@@ -500,22 +504,32 @@ async function runDeployFor({ client, projectId, slug, environment, wait }) {
   return { deployment_id: deploymentId, environment: env, status: last, waited: true, ok: false };
 }
 
-export async function runDeploy({ slugOrId, environment, wait = false, profile }) {
+export async function runDeploy({ slugOrId, environment, wait = false, profile, client: injectedClient, baseDir: baseDirOverride }) {
   if (!environment) throw new Error('Usage: hiveku-sync deploy <development|staging|production> [<slug>] [--wait]');
-  const baseDir = resolveBaseDir();
-  const { client } = await clientFromCwd({ profileOverride: profile });
+  const baseDir = baseDirOverride || resolveBaseDir();
+  const client = injectedClient || (await clientFromCwd({ profileOverride: profile })).client;
 
   // Resolve project: prefer the pulled-folder manifest (slug), else treat the
-  // arg as a slug/UUID via list_projects.
+  // arg as a slug/UUID via resolveProject (project_get / sites_list, the
+  // website_projects id space - not the PM tools). Either way an external site has
+  // nothing to deploy (deploy_site 400s on project_type external) - refuse
+  // with the pointer to where it IS managed.
   let projectId;
   let slug = slugOrId;
+  let found;
   try {
-    const { slug: s, info } = await findProjectFolder({ slug: slugOrId, baseDir });
-    projectId = info.project_id;
-    slug = s;
+    found = await findProjectFolder({ slug: slugOrId, baseDir });
   } catch {
+    found = null;
+  }
+  if (found) {
+    refuseExternal(found.info);
+    projectId = found.info.project_id;
+    slug = found.slug;
+  } else {
     if (!slugOrId) throw new Error('No project folder detected — pass a project slug or UUID: hiveku-sync deploy <env> <slug>');
     const project = await resolveProject(client, slugOrId);
+    refuseExternal(project);
     projectId = project.id;
     slug = project.slug || project.name || project.id;
   }
@@ -587,8 +601,12 @@ export async function runPullEnv({ slug, profile, target = 'development' } = {})
 
   const res = (await client.callToolJson('project_secrets_list', { project_id: projectId })).data;
   const secrets = res?.secrets || {};
+  // Variables marked sensitive are write-only on the platform: the server OMITS them
+  // from `secrets` and lists their names here. Without saying so, the .env file below
+  // would be silently incomplete and the user would go debugging a phantom.
+  const sensitiveKeys = Array.isArray(res?.sensitive_keys) ? res.sensitive_keys : [];
   const count = Object.keys(secrets).length;
-  if (count === 0) {
+  if (count === 0 && sensitiveKeys.length === 0) {
     console.log(`No secrets set on ${resolvedSlug}. Nothing to write.`);
     return { written: 0 };
   }
@@ -614,5 +632,12 @@ export async function runPullEnv({ slug, profile, target = 'development' } = {})
   }
 
   console.log(`Wrote ${Object.keys(resolved).length} var${Object.keys(resolved).length !== 1 ? 's' : ''} → ${outName} (tier: ${tier}, from ${count} secret${count !== 1 ? 's' : ''}).`);
-  return { written: Object.keys(resolved).length, path: outPath, tier };
+  if (sensitiveKeys.length > 0) {
+    const names = sensitiveKeys.slice().sort();
+    console.log(
+      `Skipped ${names.length} sensitive var${names.length !== 1 ? 's' : ''}: ${names.join(', ')}.`,
+    );
+    console.log('These are write-only on Hiveku and cannot be read back. Set them by hand if your local build needs them.');
+  }
+  return { written: Object.keys(resolved).length, skippedSensitive: sensitiveKeys, path: outPath, tier };
 }