@fluid-app/fluid-cli-theme-dev 0.1.286 → 0.1.287

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.mjs CHANGED
@@ -12224,6 +12224,207 @@ function createCompareCommand(deps = defaultCompareDeps) {
12224
12224
  });
12225
12225
  }
12226
12226
  //#endregion
12227
+ //#region src/theme/branches.ts
12228
+ /**
12229
+ * A production theme's branches: its staging copy inside Fluid, previewed on
12230
+ * the live storefront through a signed link.
12231
+ *
12232
+ * Server contract (Rails, internal):
12233
+ * apps/rails/docs/openapi/internal/theme-branches-v0.yaml
12234
+ *
12235
+ * Writes need the company's MIST_BRANCH_ENVIRONMENTS flag; the server answers
12236
+ * `feature_disabled` otherwise, and callers hide branch features on that
12237
+ * answer rather than reading the flag themselves.
12238
+ */
12239
+ const TERMINAL_OPERATION_STATES = [
12240
+ "succeeded",
12241
+ "failed",
12242
+ "cancelled",
12243
+ "stale"
12244
+ ];
12245
+ /**
12246
+ * A refusal from the branch API. `type` is the server's refusal name
12247
+ * (`feature_disabled`, `stale_revision`, `invalid_publication`…), or null
12248
+ * for a failure that carries none.
12249
+ */
12250
+ var BranchApiError = class extends Error {
12251
+ constructor(message, status, type, details, requestId) {
12252
+ super(message);
12253
+ this.status = status;
12254
+ this.type = type;
12255
+ this.details = details;
12256
+ this.requestId = requestId;
12257
+ this.name = "BranchApiError";
12258
+ }
12259
+ };
12260
+ function refusal(error) {
12261
+ if (!(error instanceof ApiError)) throw error;
12262
+ const envelope = error.body;
12263
+ const details = envelope?.error?.details && typeof envelope.error.details === "object" ? envelope.error.details : {};
12264
+ const message = typeof envelope?.error?.message === "string" ? envelope.error.message : error.message;
12265
+ const type = typeof details["type"] === "string" ? details["type"] : null;
12266
+ throw new BranchApiError(message, error.status, type, details, error.requestId);
12267
+ }
12268
+ async function call(promise) {
12269
+ try {
12270
+ return await promise;
12271
+ } catch (error) {
12272
+ refusal(error);
12273
+ }
12274
+ }
12275
+ const base = (themeId) => `/api/application_themes/${themeId}`;
12276
+ /** A fresh idempotency key for one logical request. */
12277
+ function operationKey(prefix) {
12278
+ return `${prefix}-${randomUUID()}`;
12279
+ }
12280
+ function listBranches(api, themeId) {
12281
+ return call(api.get(`${base(themeId)}/branches`));
12282
+ }
12283
+ function requestStaging(api, themeId, key) {
12284
+ return call(api.request(`${base(themeId)}/branches/staging`, {
12285
+ method: "POST",
12286
+ headers: { "X-Operation-Key": key }
12287
+ }));
12288
+ }
12289
+ async function readOperation(api, themeId, operationId) {
12290
+ return (await call(api.get(`${base(themeId)}/branch-operations/${operationId}`))).operation;
12291
+ }
12292
+ //#endregion
12293
+ //#region src/theme/staging.ts
12294
+ /**
12295
+ * Where a theme's staging branch stands, read from the branch API.
12296
+ */
12297
+ async function readStagingStatus(api, themeId) {
12298
+ const listing = await listBranches(api, themeId);
12299
+ const branch = listing.branches.find((candidate) => candidate.slug === "staging") ?? null;
12300
+ const operationId = listing.staging.operation_id;
12301
+ const operation = operationId ? await readOperation(api, themeId, operationId) : null;
12302
+ return {
12303
+ staging: listing.staging,
12304
+ branch,
12305
+ operation
12306
+ };
12307
+ }
12308
+ /**
12309
+ * Request the staging branch. Staging that already exists or is already
12310
+ * being prepared is not an error: the caller follows it instead.
12311
+ */
12312
+ async function ensureStaging(api, themeId) {
12313
+ try {
12314
+ await requestStaging(api, themeId, operationKey("cli-staging"));
12315
+ } catch (error) {
12316
+ if (!(error instanceof BranchApiError && error.type && ["staging_exists", "operation_in_progress"].includes(error.type))) throw error;
12317
+ }
12318
+ return readStagingStatus(api, themeId);
12319
+ }
12320
+ const isSettled = (operation) => TERMINAL_OPERATION_STATES.includes(operation.state);
12321
+ /** Poll until staging is ready, failed, or the deadline passes. */
12322
+ async function waitForStaging(api, themeId, { timeoutMs = 10 * 6e4, intervalMs = 3e3 } = {}) {
12323
+ const deadline = Date.now() + timeoutMs;
12324
+ for (;;) {
12325
+ const status = await readStagingStatus(api, themeId);
12326
+ const settled = !status.operation || isSettled(status.operation);
12327
+ if (status.branch?.state === "ready" || status.branch?.state === "error" || settled && status.staging.state !== "provisioning") return status;
12328
+ if (Date.now() > deadline) return status;
12329
+ await setTimeout$1(intervalMs);
12330
+ }
12331
+ }
12332
+ /** One line on staging's state, for people. */
12333
+ function describeStaging(status) {
12334
+ const { staging, branch, operation } = status;
12335
+ if (staging.state === "unavailable") return staging.reason === "feature_disabled" ? "Theme staging is not enabled for this company." : "This theme cannot have a staging branch (only draft and live production themes can).";
12336
+ if (branch?.state === "ready") return "Staging is ready.";
12337
+ if (branch?.state === "error") return `Staging failed${operation?.failure ? ` (${operation.failure.type})` : ""}; request it again to resume.`;
12338
+ if (staging.state === "provisioning" || branch?.state === "provisioning") {
12339
+ const progress = operation?.progress;
12340
+ if (!progress?.base_snapshot_recorded) return "Preparing staging…";
12341
+ if (!progress.theme_copied) return "Copying the theme…";
12342
+ return "Finishing staging…";
12343
+ }
12344
+ if (staging.state === "deleting") return "Staging is being removed.";
12345
+ return "No staging yet; request it with `fluid theme staging request`.";
12346
+ }
12347
+ //#endregion
12348
+ //#region src/commands/staging.ts
12349
+ /**
12350
+ * The production theme staging belongs to: --theme, else the theme this
12351
+ * project is bound to in .fluid-theme.json.
12352
+ */
12353
+ function resolveThemeId(opts) {
12354
+ if (opts.theme) {
12355
+ const id = Number(opts.theme);
12356
+ if (!Number.isInteger(id) || id <= 0) throw new Error(`--theme must be a theme ID, got "${opts.theme}".`);
12357
+ return id;
12358
+ }
12359
+ let root = opts.root;
12360
+ if (root === ".") {
12361
+ const workspace = findWorkspace();
12362
+ if (workspace) root = resolveThemeRootFromCwd(workspace) ?? root;
12363
+ }
12364
+ const config = readThemeConfig(root);
12365
+ if (!config) throw new Error("No .fluid-theme.json here. Run `fluid theme pull` to bind this project to a theme, or pass --theme <id>.");
12366
+ return config.themeId;
12367
+ }
12368
+ /** JSON shape Desktop reads; stable across CLI versions. */
12369
+ function stagingJson(status) {
12370
+ return {
12371
+ staging: status.staging,
12372
+ branch: status.branch,
12373
+ operation: status.operation
12374
+ };
12375
+ }
12376
+ async function run(opts, action) {
12377
+ try {
12378
+ await action();
12379
+ } catch (error) {
12380
+ if (opts.json) {
12381
+ const refusal = error instanceof BranchApiError ? {
12382
+ status: error.status,
12383
+ type: error.type,
12384
+ message: error.message,
12385
+ request_id: error.requestId ?? null
12386
+ } : {
12387
+ status: null,
12388
+ type: null,
12389
+ message: error.message,
12390
+ request_id: null
12391
+ };
12392
+ console.log(JSON.stringify({ error: refusal }));
12393
+ console.error(error.message);
12394
+ } else console.error(chalk.red(error.message));
12395
+ process.exitCode = 1;
12396
+ }
12397
+ }
12398
+ function report(status, json) {
12399
+ if (json) {
12400
+ console.log(JSON.stringify(stagingJson(status)));
12401
+ return;
12402
+ }
12403
+ console.log(describeStaging(status));
12404
+ if (status.branch?.preview_url) console.log(`Preview: ${chalk.cyan(status.branch.preview_url)}`);
12405
+ }
12406
+ function withThemeOptions(command) {
12407
+ return command.option("-t, --theme <id>", "Production theme ID (defaults to .fluid-theme.json)").option("--root <path>", "Theme root directory", ".").option("--json", "Emit JSON");
12408
+ }
12409
+ function createStagingCommand() {
12410
+ const status = withThemeOptions(new Command("status").description("Show the theme's staging branch and its preview link")).action((opts) => run(opts, async () => {
12411
+ requireToken();
12412
+ report(await readStagingStatus(createApiClient(), resolveThemeId(opts)), opts.json);
12413
+ }));
12414
+ const request = withThemeOptions(new Command("request").description("Create the theme's staging branch (or follow the one being created)")).action((opts) => run(opts, async () => {
12415
+ requireToken();
12416
+ report(await ensureStaging(createApiClient(), resolveThemeId(opts)), opts.json);
12417
+ }));
12418
+ const wait = withThemeOptions(new Command("wait").description("Wait until staging is ready or has failed")).option("--timeout <seconds>", "Give up after this many seconds", "600").action((opts) => run(opts, async () => {
12419
+ requireToken();
12420
+ const timeoutMs = Number(opts.timeout) * 1e3;
12421
+ const settled = await waitForStaging(createApiClient(), resolveThemeId(opts), { timeoutMs });
12422
+ report(settled, opts.json);
12423
+ if (settled.branch?.state !== "ready") process.exitCode = 1;
12424
+ }));
12425
+ return new Command("staging").description("Use the theme's staging branch, previewed by a signed link (needs branch environments)").addCommand(status).addCommand(request).addCommand(wait);
12426
+ }
12427
+ //#endregion
12227
12428
  //#region src/commands/theme.ts
12228
12429
  function registerThemeCommand(ctx) {
12229
12430
  const cmd = new Command("theme").description("Theme developer workflow — dev server, push, pull, lint, init, skills, crawl, compare");
@@ -12236,6 +12437,7 @@ function registerThemeCommand(ctx) {
12236
12437
  cmd.addCommand(createSkillsCommand());
12237
12438
  cmd.addCommand(createCrawlCommand());
12238
12439
  cmd.addCommand(createCompareCommand());
12440
+ cmd.addCommand(createStagingCommand());
12239
12441
  ctx.program.addCommand(cmd);
12240
12442
  }
12241
12443
  //#endregion