@easysociable/cli 0.1.2 → 0.1.3

package/dist/easysociable.js

@@ -15357,7 +15357,7 @@ function parseBrand(payload) {
 function parseBrandList(payload) {
   return parseDataEnvelope(payload, external_exports.array(brandSchema));
 }
-var FORBIDDEN_PUBLIC_KEYS, templatePlatformSchema, canvasPresetSchema, pageRoleSchema, contentFamilySchema, contentArchetypeSchema, densityLevelSchema, visualStyleSchema, imageRoleSchema, slotSummarySchema, selectionMetadataSchema, selectionMetadataDraftSchema, listTemplatesQuerySchema, templateSummarySchema, publicTemplateSlotTypeSchema, publicTemplateSlotSchema, templateDetailSchema, templateSelectionSchema, presentationIntentSchema, renderSlotValueSchema, renderJobRequestSchema, legacyRenderJobRequestSchema, renderJobStatusSchema, renderCaptureHintSchema, renderJobViewSchema, renderPreviewMaterializationSchema, renderSelectionSummarySchema, renderManifestSchema, templateAuthoringCanvasSchema, templateAuthoringProvenanceSchema, templateImageModeSchema, templateImageNodeSchema, authoringImageNodeSchema, authoringIconNodeSchema, templateAuthoringSourceSchema, themeContrastEntrySchema, themePaletteSchema, themeTokensSchema, themeSummarySchema, themeDetailSchema, gradientTextSafeZoneSchema, gradientStopSchema, gradientSummarySchema, gradientDetailSchema, listGradientsQuerySchema, templateSurfaceKindSchema, templateSurfacePreviewSchema, templateImageProviderSchema, templateImageRightsStatusSchema, templateImageProvenanceSchema, importTemplateImageFileSchema, importTemplateImageInputSchema, importTemplateImageBodySchema, createRenderAssetInputSchema, renderAssetReferenceSchema, iconStyleSchema, templateIconLicenseSchema, searchTemplateIconsRequestSchema, templateIconCandidateSchema, getTemplateIconRequestSchema, templateIconProvenanceSchema, templateIconAssetReferenceSchema, templateIconErrorCodeSchema, templateImageReferenceSchema, themeCreateInputSchema, draftThemeInputSchema, createTemplateDraftInputSchema, updateTemplateDraftInputSchema, templateAuthoringDraftSchema, DEFAULT_AUTHORING_STUDIO_BASE_URL, templatePrincipalErrorSchema, slideshowPlatformCaps, slideshowPlatformSchema, slideshowRunStatusSchema, publicSlotValueSchema, contentPackPageSchema, contentPackSchema, slideshowRunPageSchema, brandProfilePreferenceSchema, brandProfileSchema, createBrandProfileInputSchema, updateBrandProfileInputSchema, brandTypographySchema, brandColorsSchema, brandSchema, createBrandInputSchema, updateBrandInputSchema, slideshowRunSummarySchema, slideshowRunSchema, createSlideshowRunInputSchema, updateSlideshowRunInputSchema, renderSlideshowRunInputSchema, listSlideshowRunsQuerySchema;
+var FORBIDDEN_PUBLIC_KEYS, templatePlatformSchema, canvasPresetSchema, pageRoleSchema, contentFamilySchema, contentArchetypeSchema, densityLevelSchema, visualStyleSchema, imageRoleSchema, slotSummarySchema, selectionMetadataSchema, selectionMetadataDraftSchema, listTemplatesQuerySchema, templateSummarySchema, publicTemplateSlotTypeSchema, publicTemplateSlotSchema, templateDetailSchema, templateSelectionSchema, presentationIntentSchema, renderSlotValueSchema, renderJobRequestSchema, legacyRenderJobRequestSchema, renderJobStatusSchema, renderCaptureHintSchema, renderJobViewSchema, renderPreviewMaterializationSchema, renderSelectionSummarySchema, renderManifestSchema, templateAuthoringCanvasSchema, templateAuthoringProvenanceSchema, templateImageModeSchema, templateImageNodeSchema, authoringImageNodeSchema, authoringIconNodeSchema, templateAuthoringSourceSchema, themeContrastEntrySchema, themePaletteSchema, themeTokensSchema, themeSummarySchema, themeDetailSchema, gradientTextSafeZoneSchema, gradientStopSchema, gradientSummarySchema, gradientDetailSchema, listGradientsQuerySchema, templateSurfaceKindSchema, templateSurfacePreviewSchema, templateImageProviderSchema, templateImageRightsStatusSchema, templateImageProvenanceSchema, importTemplateImageFileSchema, importTemplateImageInputSchema, importTemplateImageBodySchema, createRenderAssetInputSchema, renderAssetReferenceSchema, iconStyleSchema, templateIconLicenseSchema, searchTemplateIconsRequestSchema, templateIconCandidateSchema, getTemplateIconRequestSchema, templateIconProvenanceSchema, templateIconAssetReferenceSchema, templateIconErrorCodeSchema, templateImageReferenceSchema, themeCreateInputSchema, draftThemeInputSchema, createTemplateDraftInputSchema, updateTemplateDraftInputSchema, authoringDraftVariantSchema, templateAuthoringDraftSchema, DEFAULT_AUTHORING_STUDIO_BASE_URL, templatePrincipalErrorSchema, slideshowPlatformCaps, slideshowPlatformSchema, slideshowRunStatusSchema, publicSlotValueSchema, contentPackPageSchema, contentPackSchema, slideshowRunPageSchema, brandProfilePreferenceSchema, brandProfileSchema, createBrandProfileInputSchema, updateBrandProfileInputSchema, brandTypographySchema, brandColorsSchema, brandSchema, createBrandInputSchema, updateBrandInputSchema, slideshowRunSummarySchema, slideshowRunSchema, createSlideshowRunInputSchema, updateSlideshowRunInputSchema, renderSlideshowRunInputSchema, listSlideshowRunsQuerySchema;
 var init_src = __esm({
   "../../packages/template-public-contracts/src/index.ts"() {
     "use strict";
@@ -15487,8 +15487,8 @@ var init_src = __esm({
       notFor: external_exports.array(external_exports.string()).min(1).max(3).optional(),
       selectionHints: external_exports.string().optional(),
       visualStyle: visualStyleSchema.optional(),
-      defaultThemeId: external_exports.string().optional(),
-      compatibleThemeIds: external_exports.array(external_exports.string()).optional(),
+      // ADR-0033: published selection metadata must not bind a Theme.
+      // Runtime appearance comes from Brand themeSnapshot at fill/render.
       locale: external_exports.enum(["zh-CN", "en", "bilingual"]).optional(),
       exampleFilledPreviewUrl: external_exports.string().url().optional(),
       // P2
@@ -15630,7 +15630,11 @@ var init_src = __esm({
     }).strict();
     renderSelectionSummarySchema = external_exports.object({
       templateId: external_exports.string().min(1),
-      themeId: external_exports.string().min(1),
+      /**
+       * Optional audit id for the tokens used (Brand snapshot / preview fallback).
+       * Not a Template→Theme publish binding (ADR-0033).
+       */
+      themeId: external_exports.string().min(1).optional(),
       role: external_exports.string().min(1),
       canvas: external_exports.object({
         width: external_exports.number().int().positive(),
@@ -15999,23 +16003,18 @@ var init_src = __esm({
       tokens: themeTokensSchema
     }).strict();
     draftThemeInputSchema = external_exports.object({
+      /** @deprecated TemplateTheme retired — ignored; use create.tokens or tokens. */
       themeId: external_exports.string().min(1).optional(),
-      /** With themeId: fork a new Theme when tokens differ (never mutate shared themes). */
+      /** Preferred: write these onto LayoutFamily.preview_tokens. */
       tokens: themeTokensSchema.optional(),
       create: themeCreateInputSchema.optional()
     }).strict().refine(
       (value) => {
-        const hasId = Boolean(value.themeId);
         const hasCreate = Boolean(value.create);
-        if (hasId && hasCreate)
-          return false;
-        if (!hasId && !hasCreate)
-          return false;
-        if (value.tokens && !hasId)
-          return false;
-        return true;
+        const hasTokens = Boolean(value.tokens);
+        return hasCreate || hasTokens;
       },
-      { message: "theme must provide themeId (optionally with tokens) or create" }
+      { message: "theme must provide create.tokens or tokens for Family.preview_tokens" }
     );
     createTemplateDraftInputSchema = external_exports.object({
       name: external_exports.string().min(1),
@@ -16035,12 +16034,28 @@ var init_src = __esm({
       theme: draftThemeInputSchema.optional(),
       selectionMetadata: selectionMetadataDraftSchema.optional()
     }).strict();
+    authoringDraftVariantSchema = external_exports.object({
+      pageId: external_exports.string(),
+      familyRole: external_exports.enum(["master", "variant"]),
+      canvasPreset: external_exports.string().nullable().optional(),
+      canvas: external_exports.object({
+        width: external_exports.number(),
+        height: external_exports.number()
+      }),
+      platforms: external_exports.array(external_exports.string())
+    }).strict();
     templateAuthoringDraftSchema = external_exports.object({
       id: external_exports.string(),
       /** Equals draft id — drafts are folded into TemplatePage. */
       templateId: external_exports.string().optional(),
       /** Soft theme preview reference; tokens are not stored on the draft. */
       themeId: external_exports.string().optional(),
+      /** Alias of themeId after Layout Family / Theme unbind. */
+      previewThemeId: external_exports.string().nullable().optional(),
+      familyId: external_exports.string().optional(),
+      familyRole: external_exports.enum(["master", "variant"]).optional(),
+      variants: external_exports.array(authoringDraftVariantSchema).optional(),
+      intendedPlatforms: external_exports.array(external_exports.string()).optional(),
       name: external_exports.string(),
       status: external_exports.enum(["draft", "validated", "published", "archived", "trashed"]),
       revision: external_exports.number().int().positive().optional(),
@@ -16273,7 +16288,7 @@ function isRetryableStatus(status) {
   return status === 429 || status === 502 || status === 503 || status === 504;
 }
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 var TemplateGatewayError, TemplateGatewayClient;
 var init_client = __esm({
@@ -16449,6 +16464,25 @@ var init_client = __esm({
           this.options.authoringStudioBaseUrl
         );
       }
+      async getTemplateFamily(familyId) {
+        const response = await this.request("GET", `/v1/template-families/${encodeURIComponent(familyId)}`);
+        this.throwIfError(response.status, response.json);
+        return response.json.data ?? response.json;
+      }
+      async deriveTemplateFamily(familyId, body = {}) {
+        const response = await this.request(
+          "POST",
+          `/v1/template-families/${encodeURIComponent(familyId)}/derive`,
+          body
+        );
+        this.throwIfError(response.status, response.json);
+        return response.json.data ?? response.json;
+      }
+      async migrateLegacyTemplateFamilies() {
+        const response = await this.request("POST", "/v1/template-families/migrate-legacy", {});
+        this.throwIfError(response.status, response.json);
+        return response.json.data;
+      }
       async updateDraft(draftId, body) {
         const input = parseUpdateTemplateDraftInput(body);
         const response = await this.request("PUT", `/v1/template-drafts/${encodeURIComponent(draftId)}`, input);
@@ -23418,7 +23452,7 @@ var init_protocol = __esm({
               return;
             }
             const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1e3;
-            await new Promise((resolve) => setTimeout(resolve, pollInterval));
+            await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
             options?.signal?.throwIfAborted();
           }
         } catch (error52) {
@@ -23435,7 +23469,7 @@ var init_protocol = __esm({
        */
       request(request, resultSchema, options) {
         const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
-        return new Promise((resolve, reject) => {
+        return new Promise((resolve2, reject) => {
           const earlyReject = (error52) => {
             reject(error52);
           };
@@ -23513,7 +23547,7 @@ var init_protocol = __esm({
               if (!parseResult.success) {
                 reject(parseResult.error);
               } else {
-                resolve(parseResult.data);
+                resolve2(parseResult.data);
               }
             } catch (error52) {
               reject(error52);
@@ -23774,12 +23808,12 @@ var init_protocol = __esm({
           }
         } catch {
         }
-        return new Promise((resolve, reject) => {
+        return new Promise((resolve2, reject) => {
           if (signal.aborted) {
             reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
             return;
           }
-          const timeoutId = setTimeout(resolve, interval);
+          const timeoutId = setTimeout(resolve2, interval);
           signal.addEventListener("abort", () => {
             clearTimeout(timeoutId);
             reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
@@ -26806,7 +26840,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve.call(this, root, ref);
+      let _sch = resolve2.call(this, root, ref);
       if (_sch === void 0) {
         const schema = (_a3 = root.localRefs) === null || _a3 === void 0 ? void 0 : _a3[ref];
         const { schemaId } = this.opts;
@@ -26833,7 +26867,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve(root, ref) {
+    function resolve2(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -27408,7 +27442,7 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve(baseURI, relativeURI, options) {
+    function resolve2(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const resolved = resolveComponent(parse5(baseURI, schemelessOptions), parse5(relativeURI, schemelessOptions), schemelessOptions, true);
       schemelessOptions.skipEscape = true;
@@ -27635,7 +27669,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve,
+      resolve: resolve2,
       resolveComponent,
       equal,
       serialize,
@@ -31534,12 +31568,12 @@ var init_stdio2 = __esm({
         this.onclose?.();
       }
       send(message) {
-        return new Promise((resolve) => {
+        return new Promise((resolve2) => {
           const json2 = serializeMessage(message);
           if (this._stdout.write(json2)) {
-            resolve();
+            resolve2();
           } else {
-            this._stdout.once("drain", resolve);
+            this._stdout.once("drain", resolve2);
           }
         });
       }
@@ -31610,8 +31644,8 @@ async function serveStdioMcp(options) {
   await waitForStdioServerClose(server, process.stdin);
 }
 async function waitForStdioServerClose(server, stdin = process.stdin) {
-  await new Promise((resolve) => {
-    server.onclose = () => resolve();
+  await new Promise((resolve2) => {
+    server.onclose = () => resolve2();
     if (stdin.readableEnded || stdin.destroyed) {
       void server.close().catch(() => void 0);
       return;
@@ -32453,10 +32487,10 @@ var init_v1_mcp = __esm({
 // src/v1-cli.ts
 init_src2();
 import { cp, mkdtemp, readFile, rename as rename2, rm, writeFile, mkdir, chmod, copyFile } from "fs/promises";
-import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync3, statSync as statSync2 } from "fs";
 import { createHash } from "crypto";
-import { homedir as homedir2, tmpdir } from "os";
-import { join as join3 } from "path";
+import { homedir as homedir3, tmpdir } from "os";
+import { join as join4 } from "path";
 import { Command } from "commander";
 
 // src/runtime/mcp-hosts.ts
@@ -32581,24 +32615,330 @@ function resolveDefaultSkillsSource(moduleUrl) {
   return bundled;
 }
 
+// src/engine.ts
+import { spawn, spawnSync } from "child_process";
+import {
+  copyFileSync,
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync2,
+  readdirSync,
+  readFileSync as readFileSync2,
+  statSync,
+  writeFileSync as writeFileSync2
+} from "fs";
+import net from "net";
+import { homedir as homedir2 } from "os";
+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");
+}
+function isDir(path) {
+  return existsSync3(path) && statSync(path).isDirectory();
+}
+function isEngine(path) {
+  return isDir(path) && existsSync3(join3(path, "CLAUDE.md")) && isDir(join3(path, "runs"));
+}
+function resolveEngine(rootOrEngine) {
+  const absolute = resolve(rootOrEngine);
+  if (isEngine(absolute) || basename(absolute) === ENGINE_ROOT_NAME)
+    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",
+      discovery: "discovery",
+      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);
+  const missing = [];
+  const existing = [];
+  for (const relative of Object.keys(files)) {
+    const path = join3(engine, relative);
+    (existsSync3(path) ? existing : missing).push(relative);
+  }
+  return {
+    engine,
+    engineExists: isDir(engine),
+    rootName: ENGINE_ROOT_NAME,
+    missing,
+    existing,
+    starterComplete: missing.length === 0
+  };
+}
+function validateEngine(rootOrEngine, moduleUrl, { strict = false } = {}) {
+  const engine = resolveEngine(rootOrEngine);
+  const parent = resolve(engine, "..");
+  const errors = [];
+  if (!existsSync3(parent) || !statSync(parent).isDirectory()) {
+    errors.push("Parent directory does not exist");
+    return { ...inventory(engine, moduleUrl), valid: false, errors, created: [] };
+  }
+  const result = inventory(engine, moduleUrl);
+  if (existsSync3(engine) && !isDir(engine))
+    errors.push("Content Engine exists but is not a directory");
+  if (strict) {
+    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)`);
+  }
+  return { ...result, valid: errors.length === 0, errors, created: [] };
+}
+function python3Bin() {
+  const result = spawnSync("python3", ["--version"], { encoding: "utf8" });
+  return result.status === 0 ? "python3" : "";
+}
+function ensureWorkbench(engine, moduleUrl) {
+  const destDir = join3(engine, "workbench");
+  mkdirSync2(destDir, { recursive: true });
+  const copied = [];
+  const skipped = [];
+  const src = workbenchSrc(moduleUrl);
+  for (const name of WORKBENCH_FILES) {
+    const dest = join3(destDir, name);
+    if (existsSync3(dest)) {
+      skipped.push(name);
+      continue;
+    }
+    copyFileSync(join3(src, name), dest);
+    copied.push(name);
+  }
+  return { destDir, copied, skipped };
+}
+function buildWorkbench(engine) {
+  const python = python3Bin();
+  if (!python)
+    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." };
+  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" };
+  return { ok: true, message: result.stdout.trim() };
+}
+function portInUse(port = WORKBENCH_PORT) {
+  return new Promise((resolvePort) => {
+    const socket = net.connect({ port, host: "127.0.0.1" }, () => {
+      socket.end();
+      resolvePort(true);
+    });
+    socket.on("error", () => resolvePort(false));
+  });
+}
+function openUrl(url2) {
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", url2] : [url2];
+  spawn(command, args, { stdio: "ignore", detached: true }).unref();
+}
+async function startWorkbench(engine, moduleUrl, { noOpen = 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);
+  const built = buildWorkbench(engine);
+  if (!built.ok)
+    return built;
+  const url2 = WORKBENCH_URL;
+  if (await portInUse()) {
+    if (!noOpen && process.env.EASYSOCIABLE_NO_OPEN !== "true")
+      openUrl(url2);
+    return { ok: true, alreadyRunning: true, url: url2, build: built.message };
+  }
+  const args = [join3(engine, "workbench", "serve.py")];
+  if (noOpen)
+    args.push("--no-open");
+  const child = spawn(python, args, { cwd: engine, detached: true, stdio: "ignore" });
+  child.unref();
+  return { ok: true, alreadyRunning: false, url: url2, pid: child.pid, build: built.message };
+}
+async function initEngine(rootOrEngine, moduleUrl, {
+  yes = false,
+  noOpen = false,
+  serve = false
+} = {}) {
+  const engine = resolveEngine(rootOrEngine);
+  if (!yes) {
+    const preview = validateEngine(engine, moduleUrl);
+    return {
+      ...preview,
+      action: "preview",
+      next: "Review missing files and re-run with --yes"
+    };
+  }
+  const parent = resolve(engine, "..");
+  if (!existsSync3(parent) || !statSync(parent).isDirectory()) {
+    return {
+      engine,
+      action: "applied",
+      valid: false,
+      code: "PARENT_MISSING",
+      errors: ["Parent directory does not exist"],
+      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);
+  }
+  const workbench = ensureWorkbench(engine, moduleUrl);
+  const python = python3Bin();
+  if (!python) {
+    return {
+      ...validateEngine(engine, moduleUrl),
+      created,
+      workbench,
+      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."]
+    };
+  }
+  const built = buildWorkbench(engine);
+  const started = serve ? await startWorkbench(engine, moduleUrl, { noOpen }) : { skipped: true, build: built };
+  return {
+    ...validateEngine(engine, moduleUrl),
+    created,
+    workbench,
+    workbenchBuild: built,
+    workbenchStart: started,
+    action: "applied"
+  };
+}
+function detectEngines() {
+  const extra = (process.env.EASYSOCIABLE_ENGINE_SEARCH_ROOTS || "").split(process.platform === "win32" ? ";" : ":").map((item) => item.trim()).filter(Boolean);
+  const home = homedir2();
+  const roots = [...extra, join3(home, "Documents"), home];
+  const found = [];
+  for (const root of roots) {
+    if (!isDir(root))
+      continue;
+    const direct = join3(root, ENGINE_ROOT_NAME);
+    if (isEngine(direct) || isDir(direct))
+      found.push(direct);
+    try {
+      for (const name of readdirSync(root)) {
+        const child = join3(root, name, ENGINE_ROOT_NAME);
+        if (isDir(child))
+          found.push(child);
+      }
+    } catch {
+      continue;
+    }
+  }
+  return [...new Set(found)];
+}
+function validateRun(moduleUrl, args) {
+  const script = join3(scriptsDir(moduleUrl), "validate-run.mjs");
+  if (!existsSync3(script))
+    throw new Error(`Missing validate-run script at ${script}`);
+  const argv = ["--run", args.run];
+  if (args.requirePack)
+    argv.push("--require-pack");
+  if (args.requireExport)
+    argv.push("--require-export");
+  if (args.exportDir)
+    argv.push("--export", args.exportDir);
+  if (args.requirePageTemplateId)
+    argv.push("--require-page-template-id");
+  if (args.json !== false)
+    argv.push("--json");
+  const result = spawnSync(process.execPath, [script, ...argv], { encoding: "utf8" });
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout,
+    stderr: result.stderr
+  };
+}
+
 // src/v1-cli.ts
 var CLI_MODULE_URL = import.meta.url;
 function readCliVersion() {
   try {
-    const pkg = JSON.parse(readFileSync2(join3(cliPackageRoot(CLI_MODULE_URL), "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync3(join4(cliPackageRoot(CLI_MODULE_URL), "package.json"), "utf8"));
     return typeof pkg.version === "string" && pkg.version ? pkg.version : "0.0.0";
   } catch {
     return "0.0.0";
   }
 }
-var credentialPath = join3(homedir2(), ".config", "easysociable", "credentials.json");
+var credentialPath = join4(homedir3(), ".config", "easysociable", "credentials.json");
 function resolveInstallSkillIds(options) {
   return parseInstallSkills(typeof options.skills === "string" ? options.skills : void 0);
 }
 function readStoredCredentials() {
   try {
-    if (!existsSync3(credentialPath)) return null;
-    const parsed = JSON.parse(readFileSync2(credentialPath, "utf8"));
+    if (!existsSync4(credentialPath)) return null;
+    const parsed = JSON.parse(readFileSync3(credentialPath, "utf8"));
     if (typeof parsed.apiKey !== "string" || typeof parsed.baseUrl !== "string") return null;
     return { apiKey: parsed.apiKey, baseUrl: parsed.baseUrl };
   } catch {
@@ -32606,7 +32946,7 @@ function readStoredCredentials() {
   }
 }
 async function writeStoredCredentials(credentials) {
-  await mkdir(join3(homedir2(), ".config", "easysociable"), { recursive: true, mode: 448 });
+  await mkdir(join4(homedir3(), ".config", "easysociable"), { recursive: true, mode: 448 });
   await writeFile(credentialPath, `${JSON.stringify(credentials, null, 2)}
 `, { mode: 384 });
   await chmod(credentialPath, 384);
@@ -32622,6 +32962,13 @@ function print(value, json2) {
   else process.stdout.write(`${JSON.stringify(value, null, 2)}
 `);
 }
+function commandWantsJson(command) {
+  const local = command.opts();
+  if (local.json === true)
+    return true;
+  const withGlobals = typeof command.optsWithGlobals === "function" ? command.optsWithGlobals() : {};
+  return withGlobals.json === true;
+}
 function clientFromEnv() {
   const stored = readStoredCredentials();
   const allowEnv = process.env.EASYSOCIABLE_ALLOW_ENV_CREDENTIALS === "true";
@@ -32638,8 +32985,16 @@ function clientFromEnv() {
 function jsonOption(command) {
   return command.option("--json", "Emit a JSON envelope");
 }
+function defaultEngineRoot() {
+  try {
+    if (existsSync4("/workspace") && statSync2("/workspace").isDirectory())
+      return "/workspace";
+  } catch {
+  }
+  return process.cwd();
+}
 function installHome(options) {
-  return typeof options.home === "string" && options.home ? String(options.home) : homedir2();
+  return typeof options.home === "string" && options.home ? String(options.home) : homedir3();
 }
 function installSource(options) {
   if (typeof options.source === "string" && options.source)
@@ -32650,17 +33005,17 @@ function installSource(options) {
 }
 function detectedHosts(home) {
   const candidates = [
-    { host: "codex", dir: join3(home, ".codex") },
-    { host: "claude", dir: join3(home, ".claude") }
+    { host: "codex", dir: join4(home, ".codex") },
+    { host: "claude", dir: join4(home, ".claude") }
   ];
-  return candidates.filter((item) => existsSync3(item.dir)).map((item) => ({ host: item.host, configPath: join3(item.dir, "mcp.json"), skillsPath: join3(item.dir, "skills") }));
+  return candidates.filter((item) => existsSync4(item.dir)).map((item) => ({ host: item.host, configPath: join4(item.dir, "mcp.json"), skillsPath: join4(item.dir, "skills") }));
 }
 async function planInstallation(options) {
   const home = installHome(options);
   const source = installSource(options);
   const hosts = detectedHosts(home);
   const skillNames = resolveInstallSkillIds(options);
-  const missingSkills = skillNames.filter((name) => !existsSync3(join3(source, name)));
+  const missingSkills = skillNames.filter((name) => !existsSync4(join4(source, name)));
   return {
     source,
     home,
@@ -32669,7 +33024,7 @@ async function planInstallation(options) {
     missingSkills,
     changes: hosts.flatMap((host) => [
       `merge ${host.configPath} with one easysociable MCP registration`,
-      ...skillNames.map((name) => `install ${join3(host.skillsPath, name)}`)
+      ...skillNames.map((name) => `install ${join4(host.skillsPath, name)}`)
     ])
   };
 }
@@ -32685,7 +33040,7 @@ async function applyInstallation(options) {
   const backupSuffix = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
   const backups = [];
   for (const host of detectedHosts(String(plan.home))) {
-    if (existsSync3(host.configPath)) {
+    if (existsSync4(host.configPath)) {
       const backupPath = `${host.configPath}.bak.${backupSuffix}`;
       await copyFile(host.configPath, backupPath);
       backups.push(backupPath);
@@ -32693,12 +33048,12 @@ async function applyInstallation(options) {
     await installHostConfig({ host: host.host, dataDir: "", configPath: host.configPath });
     await mkdir(host.skillsPath, { recursive: true, mode: 448 });
     for (const skill of resolveInstallSkillIds(options))
-      await cp(join3(String(plan.source), skill), join3(host.skillsPath, skill), { recursive: true, force: false, errorOnExist: false });
+      await cp(join4(String(plan.source), skill), join4(host.skillsPath, skill), { recursive: true, force: false, errorOnExist: false });
   }
   return { ...plan, applied: true, backups };
 }
 async function readJsonArgument(value) {
-  if (existsSync3(value))
+  if (existsSync4(value))
     return JSON.parse(await readFile(value, "utf8"));
   return JSON.parse(value);
 }
@@ -32736,7 +33091,7 @@ async function exportManifest(client, jobId, output) {
   const job = await client.getRenderJob(jobId);
   if (job.status !== "completed" || !job.manifest)
     throw new Error(`Render job ${jobId} is not completed or has no manifest`);
-  const staging = await mkdtemp(join3(tmpdir(), "easysociable-export-"));
+  const staging = await mkdtemp(join4(tmpdir(), "easysociable-export-"));
   try {
     for (const [index, artifact] of job.manifest.artifacts.entries()) {
       const response = await fetch(artifact.url);
@@ -32744,9 +33099,9 @@ async function exportManifest(client, jobId, output) {
       const bytes = Buffer.from(await response.arrayBuffer());
       const checksum = createHash("sha256").update(bytes).digest("hex");
       if (checksum !== artifact.sha256) throw new Error(`Artifact checksum mismatch for page ${index + 1}`);
-      await writeFile(join3(staging, `${String(index + 1).padStart(2, "0")}.png`), bytes);
+      await writeFile(join4(staging, `${String(index + 1).padStart(2, "0")}.png`), bytes);
     }
-    await writeFile(join3(staging, "manifest.json"), `${JSON.stringify(job.manifest, null, 2)}
+    await writeFile(join4(staging, "manifest.json"), `${JSON.stringify(job.manifest, null, 2)}
 `);
     await rm(output, { recursive: true, force: true });
     await rename2(staging, output);
@@ -32758,7 +33113,7 @@ async function exportManifest(client, jobId, output) {
 }
 async function exportSlideshowRun(client, runId, output) {
   const manifest = await client.getSlideshowRunManifest(runId);
-  const staging = await mkdtemp(join3(tmpdir(), "easysociable-slideshow-export-"));
+  const staging = await mkdtemp(join4(tmpdir(), "easysociable-slideshow-export-"));
   try {
     const pages = [];
     for (const artifact of manifest.artifacts) {
@@ -32768,7 +33123,7 @@ async function exportSlideshowRun(client, runId, output) {
         throw new Error(`Artifact checksum mismatch for page ${artifact.pageIndex + 1}`);
       const role = artifact.role || `page${artifact.pageIndex}`;
       const fileName = `${String(artifact.pageIndex + 1).padStart(2, "0")}-${role}.png`;
-      await writeFile(join3(staging, fileName), bytes);
+      await writeFile(join4(staging, fileName), bytes);
       pages.push({
         pageIndex: artifact.pageIndex,
         role,
@@ -32785,7 +33140,7 @@ async function exportSlideshowRun(client, runId, output) {
       deckJobId: manifest.deckJobId,
       pages
     };
-    await writeFile(join3(staging, "manifest.json"), `${JSON.stringify(localManifest, null, 2)}
+    await writeFile(join4(staging, "manifest.json"), `${JSON.stringify(localManifest, null, 2)}
 `);
     await rm(output, { recursive: true, force: true });
     await rename2(staging, output);
@@ -32821,6 +33176,73 @@ function buildV1Cli() {
     const result = opts.yes === true ? await applyInstallation(opts) : { ...plan, applied: false, next: "Review changes and re-run with --yes" };
     print(result, Boolean(opts.json));
   });
+  const engine = program.command("engine").description("Create and operate a local Content Engine + workbench");
+  jsonOption(engine.command("detect").description("Find Content Engine folders under search roots")).action((...args) => {
+    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) => {
+    const command = args.at(-1);
+    const opts = command.opts();
+    const result = await initEngine(String(opts.root), CLI_MODULE_URL, {
+      yes: opts.yes === true,
+      noOpen: opts.noOpen === true,
+      serve: opts.serve === true
+    });
+    print(result, commandWantsJson(command));
+    if (opts.yes === true && (result.valid === false || result.code)) {
+      const errors = result.errors;
+      throw new Error(errors?.[0] ?? result.code ?? "engine init failed");
+    }
+  });
+  jsonOption(engine.command("validate").description("Validate engine starter completeness or a run folder").option("--root <path>", "Parent directory or Content Engine path").option("--run <path>", "Run directory to validate").option("--require-pack", "Require pack-*.json on the run").option("--require-export", "Require export directory").option("--export <path>", "Export directory for --require-export")).action((...args) => {
+    const command = args.at(-1);
+    const opts = command.opts();
+    if (opts.run) {
+      const result = validateRun(CLI_MODULE_URL, {
+        run: String(opts.run),
+        requirePack: opts.requirePack === true,
+        requireExport: opts.requireExport === true,
+        exportDir: opts.export ? String(opts.export) : void 0,
+        json: true
+      });
+      if (result.stdout)
+        process.stdout.write(result.stdout.endsWith("\n") ? result.stdout : `${result.stdout}
+`);
+      if (result.status !== 0)
+        throw new Error(result.stderr.trim() || "engine validate --run failed");
+      return;
+    }
+    if (!opts.root)
+      throw new Error("Pass --root <path> or --run <path>.");
+    const report = validateEngine(String(opts.root), CLI_MODULE_URL, { strict: true });
+    print({ ...report, action: "validated" }, commandWantsJson(command));
+    if (!report.valid)
+      throw new Error(report.errors[0] ?? "engine validate failed");
+  });
+  jsonOption(engine.command("serve").description("Build and start the workbench on :8765").option("--engine <path>", "Content Engine path or parent", defaultEngineRoot()).option("--no-open", "Do not open a browser")).action(async (...args) => {
+    const command = args.at(-1);
+    const opts = command.opts();
+    const enginePath = resolveEngine(String(opts.engine));
+    ensureWorkbench(enginePath, CLI_MODULE_URL);
+    const built = buildWorkbench(enginePath);
+    if (!built.ok)
+      throw new Error(built.message);
+    const started = await startWorkbench(enginePath, CLI_MODULE_URL, { noOpen: opts.noOpen === 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("Rebuild workbench/index.html from markdown indexes").option("--engine <path>", "Content Engine path or parent", defaultEngineRoot())).action((...args) => {
+    const command = args.at(-1);
+    const opts = command.opts();
+    const enginePath = resolveEngine(String(opts.engine));
+    ensureWorkbench(enginePath, CLI_MODULE_URL);
+    const built = buildWorkbench(enginePath);
+    print({ action: "build", engine: enginePath, ...built }, commandWantsJson(command));
+    if (!built.ok)
+      throw new Error(built.message);
+  });
   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);
@@ -32860,6 +33282,13 @@ function buildV1Cli() {
   jsonOption(templates.command("archive").requiredOption("--id <id>")).action(withClient(async (client, opts) => client.archiveDraft(String(opts.id))));
   jsonOption(templates.command("restore").requiredOption("--id <id>")).action(withClient(async (client, opts) => client.restoreDraft(String(opts.id))));
   jsonOption(templates.command("delete").requiredOption("--id <id>")).action(withClient(async (client, opts) => client.deleteDraft(String(opts.id))));
+  const families = templates.command("families").description("Layout Family (multi-platform template identity)");
+  jsonOption(families.command("get").requiredOption("--id <id>")).action(withClient(async (client, opts) => client.getTemplateFamily(String(opts.id))));
+  jsonOption(families.command("derive").requiredOption("--id <id>").option("--presets <list>", "Comma-separated presets e.g. 4:5,9:16")).action(withClient(async (client, opts) => {
+    const presets = typeof opts.presets === "string" && opts.presets.trim() ? String(opts.presets).split(",").map((item) => item.trim()).filter(Boolean) : void 0;
+    return client.deriveTemplateFamily(String(opts.id), { presets });
+  }));
+  jsonOption(families.command("migrate-legacy").description("Wrap pages missing familyId into single-variant families")).action(withClient(async (client) => client.migrateLegacyTemplateFamilies()));
   const icons = program.command("icons").description("Search the internal safe icon catalog");
   jsonOption(icons.command("search").requiredOption("--query <query>")).action(withClient(async (client, opts) => client.searchIcons({ query: String(opts.query) })));
   jsonOption(icons.command("get").requiredOption("--id <id>").requiredOption("--idempotency-key <key>")).action(withClient(async (client, opts) => client.getIcon({ iconId: String(opts.id), idempotencyKey: String(opts.idempotencyKey) })));