@easysociable/cli 0.1.8 → 0.1.10

package/README.md

@@ -21,27 +21,48 @@ Default install does **not** include `easysociable-content`. Add it when you wan
 
 ```bash
 easysociable install --skills content,template,slideshow --yes
-easysociable engine init --root /workspace --yes
-easysociable engine serve --engine /workspace/Content Engine --no-open
 ```
 
-Then tell the Agent to follow `Content Engine/CLAUDE.md`. The starter includes
-separate `products/` (owned offers) and `recommendations/` (third-party review
-subjects) libraries; neither is a substitute for `needs/`.
+**Preferred:** clone the public core:
+
+```bash
+git clone https://github.com/murphywuwu/content-engine.git
+cd content-engine
+python3 workbench/build.py
+python3 workbench/serve.py --no-open
+```
+
+See https://github.com/murphywuwu/content-engine (LAYOUT.md, migrate-split-vault.py).
+
+**Optional:** `easysociable engine init --root … --yes` clones that repo into
+`Content Engine/` (never overwrites an existing engine).
+
+Then tell the Agent to follow `CLAUDE.md`. The core includes separate
+`products/` (owned offers) and `recommendations/` (third-party review subjects);
+neither is a substitute for `needs/`.
 
 Lazy-auth guidance lives in the package at `skills/ONBOARDING.md`.
 
 ## Content Engine
 
+Core methodology lives in the **public GitHub repo**, not inside this CLI
+tarball. `engine serve` / `build` do **not** overwrite local workbench files
+unless you pass `--sync-workbench` (pulls from the public core checkout /
+`CONTENT_ENGINE_CORE`).
+
 | Command | Purpose |
 |---------|---------|
-| `easysociable engine init [--root] [--yes] [--serve]` | Scaffold starter (never overwrites) |
-| `easysociable engine serve [--engine] [--no-open]` | Sync workbench runtime from CLI, rebuild, start on `:8765` |
-| `easysociable engine build [--engine]` | Sync workbench runtime from CLI, then rebuild `workbench/index.html` |
+| `easysociable engine init [--root] [--yes] [--serve]` | Clone public core into `Content Engine/` (no overwrite) |
+| `easysociable engine update [--engine] [--yes]` | Sync core rules from the public template; preview first, apply with `--yes`. Never touches vault data |
+| `easysociable engine serve [--engine] [--no-open] [--sync-workbench]` | Rebuild + start on `:8765` |
+| `easysociable engine build [--engine] [--sync-workbench]` | Rebuild `workbench/index.html` |
 | `easysociable engine detect` | Find engines under search roots |
-| `easysociable engine validate --root …` | Starter completeness |
+| `easysociable engine validate --root …` | Core marker completeness |
 | `easysociable engine validate --run …` | Run / pack checks before render |
 
+Optional `engine.json` field `vault_root` (default `"."`) points data at a
+separate vault; see the public LAYOUT.md.
+
 The Workbench exposes Products and Recommendations as separate read-only
 indexes. Topics can cite either one without forcing a product connection.
 

package/dist/easysociable.js

@@ -32639,10 +32639,12 @@ function resolveDefaultSkillsSource(moduleUrl) {
 import { spawn, spawnSync } from "child_process";
 import {
   copyFileSync,
+  cpSync,
   existsSync as existsSync3,
   mkdirSync as mkdirSync2,
   readdirSync,
   readFileSync as readFileSync2,
+  rmSync,
   statSync,
   writeFileSync as writeFileSync2
 } from "fs";
@@ -32652,29 +32654,61 @@ import { basename, dirname as dirname3, join as join3, resolve } from "path";
 var ENGINE_ROOT_NAME = "Content Engine";
 var WORKBENCH_PORT = 8765;
 var WORKBENCH_URL = `http://127.0.0.1:${WORKBENCH_PORT}/workbench/`;
-var WORKBENCH_FILES = ["template.html", "build.py", "serve.py"];
-function contentEnginePackageRoot(moduleUrl) {
-  const pkg = cliPackageRoot(moduleUrl);
-  const bundled = join3(pkg, "content-engine");
-  if (existsSync3(join3(bundled, "starter")))
-    return bundled;
-  const sibling = join3(pkg, "content-engine");
-  if (existsSync3(join3(sibling, "starter")))
-    return sibling;
-  return bundled;
-}
-function starterDir(moduleUrl) {
-  return join3(contentEnginePackageRoot(moduleUrl), "starter");
-}
-function workbenchSrc(moduleUrl) {
-  return join3(contentEnginePackageRoot(moduleUrl), "workbench");
-}
-function scriptsDir(moduleUrl) {
-  return join3(contentEnginePackageRoot(moduleUrl), "scripts");
-}
+var CONTENT_ENGINE_REPO = "https://github.com/murphywuwu/content-engine.git";
+var WORKBENCH_FILES = ["template.html", "build.py", "serve.py", "roots.py"];
+var REQUIRED_RELATIVE = [
+  "CLAUDE.md",
+  "engine.json",
+  "LAYOUT.md",
+  "workbench/build.py",
+  "workbench/serve.py",
+  "workbench/template.html",
+  "workbench/roots.py",
+  "needs/_index.md",
+  "topics/_index.md",
+  "runs/_index.md",
+  "profiles/_index.md"
+];
 function isDir(path) {
   return existsSync3(path) && statSync(path).isDirectory();
 }
+function scriptsDir(moduleUrl) {
+  return join3(cliPackageRoot(moduleUrl), "scripts", "engine");
+}
+function contentEngineRepoUrl() {
+  return (process.env.CONTENT_ENGINE_REPO || CONTENT_ENGINE_REPO).trim() || CONTENT_ENGINE_REPO;
+}
+function ensureCoreCheckout({ update = false } = {}) {
+  const local = (process.env.CONTENT_ENGINE_CORE || "").trim();
+  if (local) {
+    const abs = resolve(local);
+    if (!existsSync3(join3(abs, "CLAUDE.md")))
+      throw new Error(`CONTENT_ENGINE_CORE=${abs} is missing CLAUDE.md`);
+    return abs;
+  }
+  const cache = join3(homedir2(), ".cache", "easysociable", "content-engine");
+  const marker = join3(cache, "CLAUDE.md");
+  if (existsSync3(marker) && !update)
+    return cache;
+  mkdirSync2(dirname3(cache), { recursive: true });
+  if (existsSync3(marker) && update) {
+    const pull = spawnSync("git", ["-C", cache, "pull", "--ff-only"], { encoding: "utf8" });
+    if (pull.status !== 0) {
+      rmSync(cache, { recursive: true, force: true });
+    } else {
+      return cache;
+    }
+  }
+  if (existsSync3(cache))
+    rmSync(cache, { recursive: true, force: true });
+  const clone3 = spawnSync("git", ["clone", "--depth", "1", contentEngineRepoUrl(), cache], { encoding: "utf8" });
+  if (clone3.status !== 0 || !existsSync3(marker)) {
+    throw new Error(
+      `Failed to clone Content Engine core from ${contentEngineRepoUrl()}. ${clone3.stderr || clone3.stdout || ""}`.trim()
+    );
+  }
+  return cache;
+}
 function isEngine(path) {
   return isDir(path) && existsSync3(join3(path, "CLAUDE.md")) && isDir(join3(path, "runs"));
 }
@@ -32684,62 +32718,10 @@ function resolveEngine(rootOrEngine) {
     return absolute;
   return join3(absolute, ENGINE_ROOT_NAME);
 }
-function walkFiles(dir) {
-  const out = [];
-  if (!existsSync3(dir))
-    return out;
-  for (const name of readdirSync(dir)) {
-    if (name === ".DS_Store")
-      continue;
-    const path = join3(dir, name);
-    if (statSync(path).isDirectory())
-      out.push(...walkFiles(path));
-    else
-      out.push(path);
-  }
-  return out;
-}
-function engineJson() {
-  return `${JSON.stringify({
-    schemaVersion: "content-engine.v1",
-    locale: "en",
-    root: ENGINE_ROOT_NAME,
-    paths: {
-      runs: "runs",
-      exports: "exports",
-      topics: "topics",
-      needs: "needs",
-      hits: "hits",
-      products: "products",
-      recommendations: "recommendations",
-      swipe: "swipe",
-      profiles: "profiles",
-      inbox: "inbox",
-      accounts: "accounts",
-      raw: "raw",
-      published: "published",
-      wiki: "wiki",
-      platforms: "platforms",
-      workbench: "workbench"
-    }
-  }, null, 2)}
-`;
-}
-function starterFiles(moduleUrl) {
-  const root = starterDir(moduleUrl);
-  const files = {};
-  for (const path of walkFiles(root)) {
-    const relativePath = path.slice(root.length + 1).split("\\").join("/");
-    files[relativePath] = readFileSync2(path, "utf8");
-  }
-  files["engine.json"] = engineJson();
-  return files;
-}
-function inventory(engine, moduleUrl) {
-  const files = starterFiles(moduleUrl);
+function inventory(engine, _moduleUrl) {
   const missing = [];
   const existing = [];
-  for (const relative of Object.keys(files)) {
+  for (const relative of REQUIRED_RELATIVE) {
     const path = join3(engine, relative);
     (existsSync3(path) ? existing : missing).push(relative);
   }
@@ -32747,6 +32729,7 @@ function inventory(engine, moduleUrl) {
     engine,
     engineExists: isDir(engine),
     rootName: ENGINE_ROOT_NAME,
+    repo: contentEngineRepoUrl(),
     missing,
     existing,
     starterComplete: missing.length === 0
@@ -32855,7 +32838,7 @@ function validateEngine(rootOrEngine, moduleUrl, { strict = false, requireKnowle
     if (!result.engineExists)
       errors.push("Content Engine/ folder does not exist");
     else if (result.missing.length > 0)
-      errors.push(`Starter incomplete: ${result.missing.length} file(s) missing (use engine init --yes to add only missing files)`);
+      errors.push(`Engine incomplete: ${result.missing.length} file(s) missing (clone ${contentEngineRepoUrl()} or run engine init --yes)`);
   }
   const knowledge = requireKnowledge ? checkKnowledge(engine) : void 0;
   if (knowledge && !knowledge.valid)
@@ -32866,20 +32849,31 @@ function python3Bin() {
   const result = spawnSync("python3", ["--version"], { encoding: "utf8" });
   return result.status === 0 ? "python3" : "";
 }
-function ensureWorkbench(engine, moduleUrl, { update = false } = {}) {
+function wantWorkbenchSync(explicit) {
+  if (explicit === true)
+    return true;
+  if (explicit === false)
+    return false;
+  const env = (process.env.EASYSOCIABLE_SYNC_WORKBENCH || "").trim().toLowerCase();
+  return env === "1" || env === "true" || env === "yes";
+}
+function ensureWorkbench(engine, _moduleUrl, { update = false } = {}) {
   const destDir = join3(engine, "workbench");
   mkdirSync2(destDir, { recursive: true });
   const copied = [];
   const updated = [];
   const skipped = [];
-  const src = workbenchSrc(moduleUrl);
+  const needFetch = update || WORKBENCH_FILES.some((name) => !existsSync3(join3(destDir, name)));
+  const srcRoot = needFetch ? join3(ensureCoreCheckout({ update }), "workbench") : "";
   for (const name of WORKBENCH_FILES) {
     const dest = join3(destDir, name);
-    const from = join3(src, name);
     if (existsSync3(dest) && !update) {
       skipped.push(name);
       continue;
     }
+    const from = join3(srcRoot, name);
+    if (!existsSync3(from))
+      throw new Error(`Missing ${name} in Content Engine core checkout`);
     const existed = existsSync3(dest);
     copyFileSync(from, dest);
     if (existed)
@@ -32895,7 +32889,7 @@ function buildWorkbench(engine) {
     return { ok: false, code: "PYTHON3_REQUIRED", message: "python3 is required for the workbench. Install Python 3 and retry." };
   const script = join3(engine, "workbench", "build.py");
   if (!existsSync3(script))
-    return { ok: false, code: "WORKBENCH_MISSING", message: "workbench/build.py is missing. Re-run easysociable engine init --yes." };
+    return { ok: false, code: "WORKBENCH_MISSING", message: `workbench/build.py is missing. Clone ${contentEngineRepoUrl()} or run engine init --yes.` };
   const result = spawnSync(python, [script], { encoding: "utf8", cwd: engine });
   if (result.status !== 0)
     return { ok: false, code: "WORKBENCH_BUILD_FAILED", message: result.stderr.trim() || result.stdout.trim() || "workbench build failed" };
@@ -32915,11 +32909,15 @@ function openUrl(url2) {
   const args = process.platform === "win32" ? ["/c", "start", url2] : [url2];
   spawn(command, args, { stdio: "ignore", detached: true }).unref();
 }
-async function startWorkbench(engine, moduleUrl, { noOpen = false } = {}) {
+async function startWorkbench(engine, moduleUrl, {
+  noOpen = false,
+  syncWorkbench = false
+} = {}) {
   const python = python3Bin();
   if (!python)
     return { ok: false, code: "PYTHON3_REQUIRED", message: "python3 is required for the workbench. Install Python 3 and retry." };
-  ensureWorkbench(engine, moduleUrl, { update: true });
+  const sync = wantWorkbenchSync(syncWorkbench || void 0);
+  ensureWorkbench(engine, moduleUrl, { update: sync });
   const built = buildWorkbench(engine);
   if (!built.ok)
     return built;
@@ -32947,7 +32945,7 @@ async function initEngine(rootOrEngine, moduleUrl, {
     return {
       ...preview,
       action: "preview",
-      next: "Review missing files and re-run with --yes"
+      next: isEngine(engine) ? "Engine already present; nothing to do" : `Re-run with --yes to git clone ${contentEngineRepoUrl()} into this path (or clone manually)`
     };
   }
   const parent = resolve(engine, "..");
@@ -32961,15 +32959,24 @@ async function initEngine(rootOrEngine, moduleUrl, {
       created: []
     };
   }
-  mkdirSync2(engine, { recursive: true });
-  const report = inventory(engine, moduleUrl);
   const created = [];
-  const files = starterFiles(moduleUrl);
-  for (const relative of report.missing) {
-    const path = join3(engine, relative);
-    mkdirSync2(dirname3(path), { recursive: true });
-    writeFileSync2(path, files[relative], { encoding: "utf8", flag: "wx" });
-    created.push(relative);
+  if (isEngine(engine)) {
+  } else if (existsSync3(engine) && readdirSync(engine).filter((n) => n !== ".DS_Store").length > 0) {
+    return {
+      ...validateEngine(engine, moduleUrl),
+      created,
+      action: "applied",
+      valid: false,
+      code: "ENGINE_DIR_DIRTY",
+      errors: [`${engine} exists but is not a Content Engine. Remove it or clone ${contentEngineRepoUrl()} into an empty path.`]
+    };
+  } else {
+    const core = ensureCoreCheckout();
+    if (existsSync3(engine))
+      rmSync(engine, { recursive: true, force: true });
+    cpSync(core, engine, { recursive: true });
+    rmSync(join3(engine, ".git"), { recursive: true, force: true });
+    created.push("CLAUDE.md", "engine.json", "workbench/", "(cloned public core)");
   }
   const workbench = ensureWorkbench(engine, moduleUrl);
   const python = python3Bin();
@@ -32981,7 +32988,7 @@ async function initEngine(rootOrEngine, moduleUrl, {
       action: "applied",
       valid: false,
       code: "PYTHON3_REQUIRED",
-      errors: ["python3 is required for the workbench. Install Python 3 and retry. Starter files were written; workbench was not started."]
+      errors: ["python3 is required for the workbench. Install Python 3 and retry."]
     };
   }
   const built = buildWorkbench(engine);
@@ -32992,7 +32999,123 @@ async function initEngine(rootOrEngine, moduleUrl, {
     workbench,
     workbenchBuild: built,
     workbenchStart: started,
-    action: "applied"
+    action: "applied",
+    source: contentEngineRepoUrl()
+  };
+}
+var CORE_REFRESH_FILES = /* @__PURE__ */ new Set(["CLAUDE.md", "LAYOUT.md", "topics/scoring.md"]);
+var CORE_ADD_ONLY_FILES = /* @__PURE__ */ new Set(["media/_index.md", "media/README.md", "profiles/default/brand.md"]);
+function classifyCoreFile(rel) {
+  const parts = rel.split("/");
+  if (parts[0] === ".git")
+    return "skip";
+  if (CORE_ADD_ONLY_FILES.has(rel))
+    return "add";
+  if (CORE_REFRESH_FILES.has(rel))
+    return "refresh";
+  if (parts[0] === "workbench")
+    return "refresh";
+  if (parts[0] === "platforms" && rel.endsWith(".md"))
+    return "refresh";
+  if (basename(rel) === "_template.md" || parts.includes("_template"))
+    return "refresh";
+  return "skip";
+}
+function walkCoreFiles(core, relDir = "") {
+  const out = [];
+  const absDir = join3(core, relDir);
+  if (!isDir(absDir))
+    return out;
+  for (const name of readdirSync(absDir)) {
+    if (name === ".git" || name === ".DS_Store")
+      continue;
+    const rel = relDir ? `${relDir}/${name}` : name;
+    if (isDir(join3(core, rel)))
+      out.push(...walkCoreFiles(core, rel));
+    else
+      out.push(rel);
+  }
+  return out;
+}
+function mergeEngineJson(engine, core) {
+  const engPath = join3(engine, "engine.json");
+  const corePath = join3(core, "engine.json");
+  if (!existsSync3(engPath) || !existsSync3(corePath))
+    return [];
+  let eng;
+  let cor;
+  try {
+    eng = JSON.parse(readFileSync2(engPath, "utf8"));
+    cor = JSON.parse(readFileSync2(corePath, "utf8"));
+  } catch {
+    return [];
+  }
+  const engPaths = eng.paths ?? (eng.paths = {});
+  const corPaths = cor.paths ?? {};
+  const added = [];
+  for (const [key, value] of Object.entries(corPaths)) {
+    if (!(key in engPaths)) {
+      engPaths[key] = value;
+      added.push(`paths.${key}`);
+    }
+  }
+  if (added.length)
+    writeFileSync2(engPath, `${JSON.stringify(eng, null, 2)}
+`);
+  return added;
+}
+function updateEngine(rootOrEngine, moduleUrl, { yes = false } = {}) {
+  const engine = resolveEngine(rootOrEngine);
+  if (!isEngine(engine)) {
+    return {
+      engine,
+      action: "preview",
+      valid: false,
+      code: "NOT_AN_ENGINE",
+      errors: [`${engine} is not a Content Engine. Run engine init first, or pass --engine <path>.`]
+    };
+  }
+  const core = ensureCoreCheckout({ update: true });
+  const refresh = [];
+  const add = [];
+  for (const rel of walkCoreFiles(core)) {
+    const cls = classifyCoreFile(rel);
+    if (cls === "refresh")
+      refresh.push(rel);
+    else if (cls === "add" && !existsSync3(join3(engine, rel)))
+      add.push(rel);
+  }
+  if (!yes) {
+    return {
+      engine,
+      action: "preview",
+      source: contentEngineRepoUrl(),
+      willRefresh: refresh,
+      willAdd: add,
+      next: "Re-run with --yes to apply. Vault data (profiles, needs, runs, media files) is never touched."
+    };
+  }
+  const copy = (list) => {
+    for (const rel of list) {
+      const dest = join3(engine, rel);
+      mkdirSync2(dirname3(dest), { recursive: true });
+      copyFileSync(join3(core, rel), dest);
+    }
+    return list;
+  };
+  const refreshed = copy(refresh);
+  const added = copy(add);
+  const enginePaths = mergeEngineJson(engine, core);
+  const workbenchBuild = buildWorkbench(engine);
+  return {
+    ...validateEngine(engine, moduleUrl),
+    engine,
+    action: "applied",
+    source: contentEngineRepoUrl(),
+    refreshed,
+    added,
+    enginePaths,
+    workbenchBuild
   };
 }
 function detectEngines() {
@@ -33230,7 +33353,7 @@ function buildV1Cli() {
     const command = args.at(-1);
     print({ action: "detect", engines: detectEngines() }, commandWantsJson(command));
   });
-  jsonOption(engine.command("init").description("Scaffold Content Engine starter files (never overwrites existing)").option("--root <path>", "Parent directory or Content Engine path", defaultEngineRoot()).option("--yes", "Write missing starter files").option("--serve", "Also start the workbench server").option("--no-open", "Do not open a browser when starting the workbench")).action(async (...args) => {
+  jsonOption(engine.command("init").description("Clone public Content Engine core into Content Engine/ (never overwrites an existing engine). Prefer: git clone https://github.com/murphywuwu/content-engine.git").option("--root <path>", "Parent directory or Content Engine path", defaultEngineRoot()).option("--yes", "Clone core into place").option("--serve", "Also start the workbench server").option("--no-open", "Do not open a browser when starting the workbench")).action(async (...args) => {
     const command = args.at(-1);
     const opts = command.opts();
     const result = await initEngine(String(opts.root), CLI_MODULE_URL, {
@@ -33280,25 +33403,38 @@ function buildV1Cli() {
     if (!report.valid)
       throw new Error(report.errors[0] ?? "engine validate failed");
   });
-  jsonOption(engine.command("serve").description("Sync workbench runtime from CLI, rebuild, start on :8765").option("--engine <path>", "Content Engine path or parent", defaultEngineRoot()).option("--no-open", "Do not open a browser")).action(async (...args) => {
+  jsonOption(engine.command("serve").description("Rebuild workbench and start on :8765 (does not overwrite local workbench unless --sync-workbench)").option("--engine <path>", "Content Engine path or parent", defaultEngineRoot()).option("--no-open", "Do not open a browser").option("--sync-workbench", "Refresh workbench runtime files from the CLI package")).action(async (...args) => {
     const command = args.at(-1);
     const opts = command.opts();
     const enginePath = resolveEngine(String(opts.engine));
-    const started = await startWorkbench(enginePath, CLI_MODULE_URL, { noOpen: opts.noOpen === true });
+    const started = await startWorkbench(enginePath, CLI_MODULE_URL, {
+      noOpen: opts.noOpen === true,
+      syncWorkbench: opts.syncWorkbench === true
+    });
     print({ action: "serve", engine: enginePath, ...started }, commandWantsJson(command));
     if (!started.ok)
       throw new Error("message" in started ? String(started.message) : "engine serve failed");
   });
-  jsonOption(engine.command("build").description("Sync workbench runtime from CLI, then rebuild workbench/index.html").option("--engine <path>", "Content Engine path or parent", defaultEngineRoot())).action((...args) => {
+  jsonOption(engine.command("build").description("Rebuild workbench/index.html (does not overwrite local workbench unless --sync-workbench)").option("--engine <path>", "Content Engine path or parent", defaultEngineRoot()).option("--sync-workbench", "Refresh workbench runtime files from the CLI package")).action((...args) => {
     const command = args.at(-1);
     const opts = command.opts();
     const enginePath = resolveEngine(String(opts.engine));
-    const workbench = ensureWorkbench(enginePath, CLI_MODULE_URL, { update: true });
+    const sync = wantWorkbenchSync(opts.syncWorkbench === true ? true : void 0);
+    const workbench = ensureWorkbench(enginePath, CLI_MODULE_URL, { update: sync });
     const built = buildWorkbench(enginePath);
-    print({ action: "build", engine: enginePath, workbench, ...built }, commandWantsJson(command));
+    print({ action: "build", engine: enginePath, workbench, syncWorkbench: sync, ...built }, commandWantsJson(command));
     if (!built.ok)
       throw new Error(built.message);
   });
+  jsonOption(engine.command("update").description("Sync core rules from the template (CLAUDE.md, workbench, platforms, templates) and add new scaffolds; never touches your vault data. Preview first; apply with --yes.").option("--engine <path>", "Content Engine path or parent", defaultEngineRoot()).option("--yes", "Apply the update (default is a dry-run preview)")).action((...args) => {
+    const command = args.at(-1);
+    const opts = command.opts();
+    const result = updateEngine(String(opts.engine), CLI_MODULE_URL, { yes: opts.yes === true });
+    print(result, commandWantsJson(command));
+    const code = result.code;
+    if (code)
+      throw new Error(result.errors?.[0] ?? code);
+  });
   const auth = program.command("auth").description("Manage the shared EasySociable credential");
   jsonOption(auth.command("status").description("Show authentication status")).action(async (...args) => {
     const command = args.at(-1);