mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* feat(cli): define every command through one factory and test them all as an agent Every command now comes from defineCommand in utils/defineCommand.ts. A lint rule bans importing defineCommand from citty anywhere else, and a new contract test walks the command registry in cli.ts, checks each command was built by the factory, and runs it the way a coding agent does: no terminal, stdin closed, CI=1, CLAUDECODE=1 and a home folder of its own. Usage errors now exit 2: unknown flags, extra positionals, and citty's own parse errors (missing argument, bad value, unknown or missing subcommand). An unknown flag names the help command instead of printing nothing else. isUnattended() in utils/attendedTerminal.ts is the one answer to "can a person respond here". It is true without a TTY on stdin or stdout, under CI (any value except "false" or "0"), when the existing agent detection finds an agent, or with HYPERFRAMES_AGENT=1. Color is off when it is true. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * test(cli): spawn preview in the agent-mode test only when the studio packages are built From source, preview refuses to load until the studio workspace packages are built, and the CLI test jobs do not build them. preview is still checked for being defined with the shared factory. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(cli): count only agent-run shells as unattended, and exit 2 for missing arguments isUnattended() used the telemetry fingerprint detectAgentRuntime(), which also matches a person typing in Cursor's or Windsurf's terminal (TERM_PROGRAM) and any Replit shell (REPL_ID, REPLIT_USER). It now uses isAgentDriven(), which keeps only markers an agent sets on the shells it runs: CURSOR_AGENT counts, TERM_PROGRAM=cursor, TERM_PROGRAM=windsurf and the Replit variables do not. The hand-written argument checks in lambda, cloudrun, lambda policies, capture, remove-background, init (--resolution), tts (--lang) and cloud render (--idempotency-key, --dry-run) exited 1. They are usage errors and now exit 2. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
229 lines
7.7 KiB
TypeScript
229 lines
7.7 KiB
TypeScript
/**
|
|
* `hyperframes figma component <ref>` — Phase 3: node tree → editable HTML
|
|
* component with the §7.1 binding pass, per-node rasterize fallback via
|
|
* Phase-1 asset import, packaged as a registry item.
|
|
*/
|
|
|
|
import { defineCommand } from "../../utils/defineCommand.js";
|
|
import {
|
|
createFigmaClient,
|
|
FigmaClientError,
|
|
nodeToHtml,
|
|
parseFigmaRef,
|
|
readBindings,
|
|
resolveBindings,
|
|
slugify,
|
|
type BindingSite,
|
|
type FigmaClient,
|
|
type NodeToHtmlResult,
|
|
type RasterizeRequest,
|
|
} from "@hyperframes/core/figma";
|
|
import { existsSync, mkdirSync, writeFileSync } from "node:fs";
|
|
import { join, relative } from "node:path";
|
|
|
|
function escapeAttr(value: string): string {
|
|
return value
|
|
.replace(/&/g, "&")
|
|
.replace(/</g, "<")
|
|
.replace(/>/g, ">")
|
|
.replace(/"/g, """);
|
|
}
|
|
import { runAssetImport, type AssetImportResult } from "./asset.js";
|
|
import { downloadRender } from "./download.js";
|
|
import { withFigmaErrors } from "./cliError.js";
|
|
|
|
export interface ComponentImportDeps {
|
|
projectDir: string;
|
|
client: FigmaClient;
|
|
download: (url: string) => Promise<Uint8Array>;
|
|
/** override the component name — figma variant frames are often all named
|
|
* "Platform=Desktop", which would slug-collide across imports */
|
|
name?: string;
|
|
}
|
|
|
|
export interface ComponentImportResult {
|
|
name: string;
|
|
htmlPath: string;
|
|
unresolved: BindingSite[];
|
|
rasterized: RasterizeRequest[];
|
|
/** node ids figma refused to render as svg AND png — placeholders shipped without src */
|
|
failedRasterize: string[];
|
|
}
|
|
|
|
export async function runComponentImport(
|
|
refInput: string,
|
|
deps: ComponentImportDeps,
|
|
): Promise<ComponentImportResult> {
|
|
const ref = parseFigmaRef(refInput);
|
|
if (!ref.nodeId) throw new Error(`ref "${refInput}" has no node id`);
|
|
|
|
const tree = await deps.client.nodeTree(ref);
|
|
const bindings = resolveBindings(tree, readBindings(deps.projectDir));
|
|
const mapped = nodeToHtml(tree, bindings, { rootName: deps.name });
|
|
|
|
const name = slugify(deps.name ?? tree.name);
|
|
const componentDir = join(deps.projectDir, "compositions", "components", name);
|
|
if (existsSync(componentDir))
|
|
console.warn(
|
|
`component dir compositions/components/${name} already exists — overwriting (rename the figma frame for a separate import)`,
|
|
);
|
|
mkdirSync(componentDir, { recursive: true });
|
|
|
|
const { html, frozenAssets, failedRasterize } = await rasterizeFallback(
|
|
mapped,
|
|
ref.fileKey,
|
|
componentDir,
|
|
deps,
|
|
);
|
|
|
|
const htmlFile = join(componentDir, `${name}.html`);
|
|
writeFileSync(htmlFile, html + "\n");
|
|
|
|
const registryItem = {
|
|
name,
|
|
type: "hyperframes:component",
|
|
description: `Imported from figma ${ref.fileKey}/${ref.nodeId}`,
|
|
files: [
|
|
{
|
|
path: `${name}.html`,
|
|
target: `compositions/components/${name}/${name}.html`,
|
|
type: "hyperframes:snippet",
|
|
},
|
|
// The paths the frozen files ACTUALLY landed at (image_NNN.svg), which
|
|
// is also what the emitted HTML references — not the slug names.
|
|
...frozenAssets.map((p) => ({
|
|
path: p.split("/").pop() ?? p,
|
|
target: p.replaceAll("\\", "/"),
|
|
type: "hyperframes:asset",
|
|
})),
|
|
],
|
|
};
|
|
writeFileSync(
|
|
join(componentDir, "registry-item.json"),
|
|
JSON.stringify(registryItem, null, 2) + "\n",
|
|
);
|
|
|
|
return {
|
|
name,
|
|
htmlPath: relative(deps.projectDir, htmlFile),
|
|
unresolved: bindings.unresolved,
|
|
rasterized: mapped.rasterize,
|
|
failedRasterize,
|
|
};
|
|
}
|
|
|
|
interface RasterizeOutcome {
|
|
html: string;
|
|
frozenAssets: string[];
|
|
failedRasterize: string[];
|
|
}
|
|
|
|
/**
|
|
* Rasterize fallback: export each unmappable node via Phase 1 and point the
|
|
* placeholder img at the frozen file (path relative to the component). figma
|
|
* sometimes refuses to render a node (nested instances commonly fail as svg)
|
|
* — retry once as png, then skip THAT node and keep the import: one
|
|
* unrenderable node must not abort the whole component. Skipped placeholders
|
|
* keep their data-figma-rasterize marker (no src) so the gap is visible.
|
|
*/
|
|
async function rasterizeFallback(
|
|
mapped: NodeToHtmlResult,
|
|
fileKey: string,
|
|
componentDir: string,
|
|
deps: ComponentImportDeps,
|
|
): Promise<RasterizeOutcome> {
|
|
let html = mapped.html;
|
|
const frozenAssets: string[] = [];
|
|
const failedRasterize: string[] = [];
|
|
for (const req of mapped.rasterize) {
|
|
const asset = await renderWithPngRetry(fileKey, req, deps);
|
|
if (asset === null) {
|
|
failedRasterize.push(req.nodeId);
|
|
console.warn(
|
|
`could not render node ${req.nodeId} ("${req.name}") as svg or png — leaving its placeholder without src`,
|
|
);
|
|
continue;
|
|
}
|
|
frozenAssets.push(asset.record.path);
|
|
// src is a URL — always forward slashes, even when relative() yields
|
|
// windows separators.
|
|
const srcRel = relative(componentDir, join(deps.projectDir, asset.record.path)).replaceAll(
|
|
"\\",
|
|
"/",
|
|
);
|
|
// The search key must match the EMITTED (html-escaped) node id, and
|
|
// replaceAll covers the same node appearing twice in the tree.
|
|
const emittedId = escapeAttr(req.nodeId);
|
|
html = html.replaceAll(
|
|
`data-figma-rasterize="${emittedId}" `,
|
|
`data-figma-rasterize="${emittedId}" src="${escapeAttr(srcRel)}" `,
|
|
);
|
|
}
|
|
return { html, frozenAssets, failedRasterize };
|
|
}
|
|
|
|
async function renderWithPngRetry(
|
|
fileKey: string,
|
|
req: RasterizeRequest,
|
|
deps: ComponentImportDeps,
|
|
): Promise<AssetImportResult | null> {
|
|
for (const format of ["svg", "png"] as const) {
|
|
try {
|
|
return await runAssetImport(
|
|
`${fileKey}:${req.nodeId}`,
|
|
{ format, description: req.name },
|
|
{ projectDir: deps.projectDir, client: deps.client, download: deps.download },
|
|
);
|
|
} catch (err) {
|
|
if (!(err instanceof FigmaClientError) || err.code !== "RENDER_FAILED") throw err;
|
|
}
|
|
}
|
|
return null;
|
|
}
|
|
|
|
export default defineCommand({
|
|
meta: { name: "component", description: "Import a figma frame as an editable HTML component" },
|
|
args: {
|
|
ref: { type: "positional", description: "figma URL or fileKey:nodeId", required: true },
|
|
name: {
|
|
type: "string",
|
|
description: "component name override (variant frames often share a name and would collide)",
|
|
},
|
|
dir: { type: "string", description: "project directory", default: "." },
|
|
},
|
|
async run({ args }) {
|
|
await withFigmaErrors("figma:component", async () => {
|
|
const t0 = Date.now();
|
|
const client = createFigmaClient({ token: process.env.FIGMA_TOKEN ?? "" });
|
|
const result = await runComponentImport(args.ref, {
|
|
projectDir: args.dir,
|
|
client,
|
|
download: downloadRender,
|
|
name: args.name,
|
|
});
|
|
console.log(`imported component "${result.name}" → ${result.htmlPath}`);
|
|
if (result.rasterized.length > 0) {
|
|
const ok = result.rasterized.length - result.failedRasterize.length;
|
|
console.log(
|
|
result.failedRasterize.length > 0
|
|
? `rasterized ${ok}/${result.rasterized.length} node(s) via asset export — ${result.failedRasterize.length} skipped (unrenderable; placeholders have no src)`
|
|
: `rasterized ${result.rasterized.length} node(s) via asset export`,
|
|
);
|
|
}
|
|
if (result.unresolved.length > 0) {
|
|
console.log(
|
|
`${result.unresolved.length} binding(s) reference tokens not yet imported — colors baked as literals (flagged data-figma-unresolved). Run \`hyperframes figma tokens\` on the source/library file, then re-import to link them.`,
|
|
);
|
|
}
|
|
const { trackFigmaImport } = await import("../../telemetry/index.js");
|
|
trackFigmaImport({
|
|
phase: "component",
|
|
unresolvedBindings: result.unresolved.length,
|
|
rasterizedNodes: result.rasterized.length,
|
|
rasterizeFailures: result.failedRasterize.length,
|
|
durationMs: Date.now() - t0,
|
|
});
|
|
});
|
|
},
|
|
});
|