Skip to content

Write HTML. Render video. Built for agents.

14.0 KB
Raw Blame
import { join, posix, relative, resolve } from "node:path";
import { failCommand, setCommandExitCode } from "../utils/commandResult.js";
import { existsSync } from "node:fs";
import { defineCommand } from "citty";
import * as clack from "@clack/prompts";

import type { Example } from "./_examples.js";
import { c } from "../ui/colors.js";
import {
  definitiveEntryMismatchComposition,
  hasDefinitiveEntryMismatch,
  lintProject,
} from "../utils/lintProject.js";
import { formatLintStartupMessage } from "../utils/lintFormat.js";
import { envCredentialVar } from "../auth/resolver.js";
import {
  buildPublishFileMap,
  publishProjectArchive,
  resolvePublishCredential,
  zipPublishFileMap,
} from "../utils/publishProject.js";
import { bakeMediaProxies } from "../utils/publishProxyBake.js";
import type { ResolvedCredential } from "../auth/resolver.js";
import { resolveAutoProxy } from "../utils/projectConfig.js";
import {
  ensureProjectId,
  readProjectLink,
  readTeamProject,
  writeTeamProject,
} from "../utils/projectLink.js";

export const examples: Example[] = [
  ["Publish the current project privately to a stable URL", "hyperframes publish"],
  ["Publish a specific directory", "hyperframes publish ./my-video"],
  ["Make the claimed project public to anyone", "hyperframes publish --public"],
  ["Update an existing published project in place", "hyperframes publish --update <url|id>"],
  ["Publish to a shared team space", "hyperframes publish --space <space-id>"],
  ["Skip the consent prompt (scripts)", "hyperframes publish --yes"],
  ["Skip baking H.264 proxies for browser-hostile video codecs", "hyperframes publish --no-proxy"],
  ["Show full lint findings instead of the summary line", "hyperframes publish --lint-verbose"],
];

/** Extract a project id from a published URL (with or without scheme, query, or hash) or accept a bare id. */
export function parseUpdateTarget(value: string): string {
  const trimmed = value.trim();
  // Pull the id straight out of a `/p/<id>` path — works for full URLs, scheme-less URLs
  // (which `new URL` rejects), and links carrying `?query`/`#hash`.
  const pathMatch = trimmed.match(/\/p\/([^/?#]+)/);
  if (pathMatch?.[1]) return pathMatch[1];
  try {
    const segment = new URL(trimmed).pathname.split("/").filter(Boolean).pop();
    if (segment) return segment;
  } catch {
    // Not a URL — treat as a bare id.
  }
  return trimmed;
}

export default defineCommand({
  meta: {
    name: "publish",
    description: "Upload the project to a stable URL (private by default)",
  },
  args: {
    dir: { type: "positional", description: "Project directory", required: false },
    yes: {
      type: "boolean",
      alias: "y",
      description: "Skip the publish confirmation prompt",
      default: false,
    },
    public: {
      type: "boolean",
      description: "Make the claimed project public to anyone, not just the claimer",
      default: false,
    },
    update: {
      type: "string",
      description: "Update an existing published project in place (its URL or id)",
    },
    space: {
      type: "string",
      description: "Publish into a shared team space (its id) so teammates update one link",
    },
    proxy: {
      type: "boolean",
      description:
        "Bake H.264 proxies for browser-hostile video codecs (e.g. HEVC) into the published archive. Default: on, unless disabled via hyperframes.json media.autoProxy. Pass --no-proxy to skip.",
    },
    "lint-verbose": {
      type: "boolean",
      description: "Show full lint findings before publishing (default: a one-line summary)",
      default: false,
    },
  },
  async run({ args }) {
    const rawArg = args.dir;
    const dir = resolve(rawArg ?? ".");
    const indexPath = join(dir, "index.html");
    if (existsSync(indexPath)) {
      const lintResult = await lintProject(dir);
      const definitiveEntryMismatch = hasDefinitiveEntryMismatch(lintResult);
      if (lintResult.totalErrors > 0 || lintResult.totalWarnings > 0) {
        console.log();
        const verbose = Boolean(args["lint-verbose"]) || definitiveEntryMismatch;
        for (const line of formatLintStartupMessage(
          lintResult,
          verbose ? { kind: "verbose" } : { kind: "summary" },
        ))
          console.log(line);
        console.log();
      }
      if (definitiveEntryMismatch) {
        const candidate = definitiveEntryMismatchComposition(lintResult);
        console.log(c.error("  Aborting publish because the default index.html entry is blank."));
        if (candidate && posix.basename(candidate) === "index.html") {
          const candidateDir = posix.dirname(candidate);
          const target = `<project>/${candidateDir}`;
          console.log(
            c.dim(
              `  Move or mount the authored file, or publish its directory directly: hyperframes publish ${target}. Only use the directory form when its assets are self-contained under that directory; otherwise mount it from the project root.`,
            ),
          );
        } else if (candidate) {
          console.log(
            c.dim(
              `  Move or mount ${candidate} as a project index.html before publishing; publish accepts project directories, not individual HTML files.`,
            ),
          );
        }
        console.log();
        failCommand();
      }
    }

    if (args.yes !== true) {
      console.log();
      if (args.public === true) {
        console.log(
          `  ${c.bold("hyperframes publish uploads this project and requests public visibility at a stable URL.")}`,
        );
        console.log(`  ${c.dim("Anyone with the URL can open a claimed public project.")}`);
      } else {
        console.log(
          `  ${c.bold("hyperframes publish uploads this project privately to a stable URL.")}`,
        );
        console.log(
          `  ${c.dim("Viewing requires authentication and access. Pass --public to allow anyone with the URL.")}`,
        );
      }
      console.log();
      const approved = await clack.confirm({ message: "Publish this project?" });
      if (clack.isCancel(approved) || approved !== true) {
        console.log();
        console.log(`  ${c.dim("Aborted.")}`);
        console.log();
        return;
      }
    }

    const updateTarget =
      typeof args.update === "string" && args.update.trim()
        ? parseUpdateTarget(args.update)
        : undefined;
    const spaceOverride =
      typeof args.space === "string" && args.space.trim() ? args.space.trim() : undefined;

    // Resolved once and passed to the upload: a second lookup after the bake could fall back
    // from an expired login to a saved API key and silently drop --update / --space.
    let credential: ResolvedCredential | null;
    try {
      credential = await resolvePublishCredential();
    } catch (err: unknown) {
      console.error();
      console.error(`  ${(err as Error).message}`);
      console.error();
      setCommandExitCode(1);
      return;
    }

    // --update / --space only take effect for a login (an API-key publish is never owned).
    // Fail loudly rather than silently minting a fresh URL.
    if (updateTarget || spaceOverride) {
      if (credential?.type !== "oauth") {
        const flag = updateTarget ? "--update" : "--space";
        const envKey = credential && envCredentialVar(credential.source);
        console.log();
        console.log(
          `  ${c.error(
            !credential
              ? `${flag} requires authentication. Run 'hyperframes auth login' first.`
              : envKey
                ? `${flag} requires a login; ${envKey} cannot own a project. Unset it and run 'hyperframes auth login'.`
                : `${flag} requires a login; an API key cannot own a project. Run 'hyperframes auth login'.`,
          )}`,
        );
        console.log();
        setCommandExitCode(1);
        return;
      }
    }

    const committedTeam = readTeamProject(dir);
    // Stable id: explicit --update wins, else the committed team id, else this machine's stored/minted id.
    const requestedProjectId = updateTarget ?? committedTeam?.projectId ?? ensureProjectId(dir);
    // Team space: explicit --space wins, else the committed space id, else the personal space.
    const spaceId = spaceOverride ?? committedTeam?.spaceId;

    // Continuity cue: if this directory was published before, show where it lives so the
    // user knows a re-publish updates that same link (when logged in).
    const priorLink = readProjectLink(dir);
    if (priorLink?.url) {
      console.log();
      console.log(`  ${c.dim(`Previously published at ${priorLink.url}`)}`);
    }

    clack.intro(c.bold("hyperframes publish"));
    const publishSpinner = clack.spinner();
    publishSpinner.start("Preparing project...");

    try {
      // Resolution order (per hyperframes.json's `media.autoProxy`): an
      // explicit --proxy/--no-proxy flag wins in either direction, else the
      // committed config, else on by default.
      const proxyFlagValue = typeof args.proxy === "boolean" ? args.proxy : undefined;
      const autoProxy = resolveAutoProxy(dir, proxyFlagValue);
      const fileMap = buildPublishFileMap(dir);
      let proxyBakeManifest: Awaited<ReturnType<typeof bakeMediaProxies>> | undefined;
      if (autoProxy) {
        proxyBakeManifest = await bakeMediaProxies(dir, fileMap);
      }
      const archive = zipPublishFileMap(fileMap);
      publishSpinner.message("Uploading project...");

      const published = await publishProjectArchive(dir, {
        public: args.public === true,
        projectId: requestedProjectId,
        spaceId,
        archive,
        credential,
      });
      publishSpinner.stop(c.success("Project published"));

      console.log();
      console.log(`  ${c.dim("Project")}              ${c.accent(published.title)}`);
      console.log(`  ${c.dim("Files")}                ${String(published.fileCount)}`);
      if (proxyBakeManifest) {
        console.log(
          `  ${c.dim("Proxies")}              ${String(proxyBakeManifest.proxied.length)} baked`,
        );
        if (proxyBakeManifest.skippedAlpha.length > 0) {
          console.log(
            `  ${c.dim("Proxy note")}           ${String(proxyBakeManifest.skippedAlpha.length)} alpha source(s) kept original`,
          );
        }
      }

      if (published.claimed) {
        // The server returns the same id on an in-place update, a fresh id on create.
        const updatedInPlace = published.projectId === requestedProjectId;
        console.log(`  ${c.dim("URL")}                  ${c.accent(published.url)}`);
        // The CLI only ever states what it ASKED for: no response field carries the project's
        // actual visibility. A re-publish without --public sends no visibility at all, so the
        // server keeps whatever the project already had — saying "Private" there would claim
        // a state we neither requested nor observed.
        const requestedVisibility =
          args.public === true
            ? "Public — anyone with the URL"
            : updatedInPlace
              ? "Unchanged — keeps this project's current setting"
              : "Private — authentication and access required";
        console.log(`  ${c.dim("Requested visibility")} ${c.accent(requestedVisibility)}`);
        console.log(
          `  ${c.dim("Status")}               ${c.accent(updatedInPlace ? "Updated existing project" : "Created new project")}`,
        );
        if (args.public !== true) {
          console.log(
            `  ${c.dim("Tip")}                  ${c.dim("Re-publish with --public to allow anyone with the URL.")}`,
          );
        }
        // Warn whenever we aimed at a KNOWN existing project (an explicit --update target or
        // a committed team id) but the server created a fresh one instead — so a teammate
        // whose space doesn't own the committed project doesn't silently lose the shared link.
        if ((updateTarget || committedTeam) && !updatedInPlace) {
          const targetDesc = updateTarget ? "The requested project" : "The committed team project";
          console.log();
          console.log(
            `  ${c.dim(`${targetDesc} was not updated (not found, or your space can't access it); a new project was created above instead.`)}`,
          );
        }
        // Persist a committable descriptor so a team converges on this link. This is a
        // convenience: wrap it so a read-only project dir can't turn a successful publish
        // into a "Publish failed" (the outer catch owns publish failures only).
        if (
          committedTeam === null ||
          (spaceId !== undefined && committedTeam.spaceId !== spaceId)
        ) {
          try {
            const file = writeTeamProject(dir, { projectId: published.projectId, spaceId });
            console.log();
            console.log(
              `  ${c.dim(`Wrote ${relative(dir, file) || file} — commit it so your team publishes to this link.`)}`,
            );
          } catch {
            // Convenience file only; never shadow a successful publish with a local write failure.
          }
        }
        console.log();
      } else {
        const claimUrl = new URL(published.url);
        claimUrl.searchParams.set("claim_token", published.claimToken);
        console.log(`  ${c.dim("Claim URL")}  ${c.accent(claimUrl.toString())}`);
        console.log(`  ${c.dim("Access")}     ${c.accent("Sign in required to claim")}`);
        console.log();
        console.log(
          `  ${c.dim("Open the claim URL on hyperframes.dev, sign in, and claim the project to continue editing.")}`,
        );
        console.log();
        const visibilityTip =
          args.public === true
            ? "--public applies to the claimed project; this claim URL still requires sign-in."
            : "Run 'hyperframes auth login' first for a stable link you can re-publish to; add --public to allow signed-out viewing.";
        console.log(`  ${c.dim(`Tip: ${visibilityTip}`)}`);
        console.log();
      }
      return;
    } catch (err: unknown) {
      publishSpinner.stop(c.error("Publish failed"));
      console.error();
      console.error(`  ${(err as Error).message}`);
      console.error();
      setCommandExitCode(1);
      return;
    }
  },
});