@remixmate/cli 0.9.63 → 0.9.65

package/dist/template/init.js

@@ -0,0 +1,115 @@
+/**
+ * `remixmate template init <dir> [--force]` — scaffold a starter project.
+ *
+ * Only Node + npm are required (requirement 3.1): the starter is fetched with
+ * `npm pack` (works with whatever registry/proxy npm is configured for), unpacked
+ * with the system `tar` (bsdtar ships with Windows 10+), then `npm install`ed.
+ * No login is needed (requirement 3.5).
+ */
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { EXIT, SkillError } from '../errors.js';
+import { emitProgress } from '../progress.js';
+import { STARTER_PACKAGE, STARTER_TARBALL_ENV, STARTER_VERSION } from './constants.js';
+import { Output } from './project.js';
+import { runNpm, runProcess } from './proc.js';
+function isNonEmptyDir(dir) {
+    if (!existsSync(dir))
+        return false;
+    if (!statSync(dir).isDirectory()) {
+        throw new SkillError(`❌ ${dir} 已存在且不是目录`, EXIT.USAGE);
+    }
+    return readdirSync(dir).length > 0;
+}
+/** Obtain the starter tarball: local override, else `npm pack` into `tmp`. */
+async function obtainTarball(tmp, out) {
+    const override = (process.env[STARTER_TARBALL_ENV] ?? '').trim();
+    if (override) {
+        const file = path.resolve(override);
+        if (!existsSync(file)) {
+            throw new SkillError(`❌ ${STARTER_TARBALL_ENV} 指向的文件不存在: ${file}`, EXIT.USAGE);
+        }
+        out.info(`使用本地 starter 包: ${file}`);
+        return { file, label: `local:${path.basename(file)}` };
+    }
+    const spec = `${STARTER_PACKAGE}@${STARTER_VERSION}`;
+    out.info(`下载 ${spec} …`);
+    const res = await runNpm(['pack', spec, '--json', '--silent'], { cwd: tmp, stdio: 'pipe' });
+    if (res.code !== 0) {
+        const tail = res.stderr.trim().split('\n').slice(-5).join('\n');
+        throw new SkillError(`❌ npm pack ${spec} 失败（退出码 ${res.code}）。检查网络与 npm registry 配置。\n${tail}`, EXIT.BACKEND_UNREACHABLE);
+    }
+    let file;
+    try {
+        const parsed = JSON.parse(res.stdout);
+        if (parsed[0]?.filename)
+            file = path.join(tmp, parsed[0].filename);
+    }
+    catch {
+        // Older npm without --json support: fall back to whatever .tgz landed in tmp.
+    }
+    file ??= readdirSync(tmp).filter((f) => f.endsWith('.tgz')).map((f) => path.join(tmp, f))[0];
+    if (!file || !existsSync(file))
+        throw new SkillError('❌ npm pack 未产出 tarball');
+    return { file, label: spec };
+}
+export async function runInit(opts) {
+    const out = new Output(Boolean(opts.json));
+    if (!opts.dir)
+        throw new SkillError('❌ 缺少目标目录：remixmate template init <dir>', EXIT.USAGE);
+    const dir = path.resolve(opts.dir);
+    if (isNonEmptyDir(dir) && !opts.force) {
+        throw new SkillError(`❌ 目标目录非空: ${dir}\n   换一个空目录，或确认可以覆盖后加 --force。`, EXIT.USAGE);
+    }
+    const tmp = mkdtempSync(path.join(os.tmpdir(), 'remixmate-starter-'));
+    try {
+        emitProgress({ phase: 'template-init:fetch', progress: 0.1 });
+        const { file, label } = await obtainTarball(tmp, out);
+        emitProgress({ phase: 'template-init:extract', progress: 0.4 });
+        mkdirSync(dir, { recursive: true });
+        // npm tarballs are rooted at `package/` — strip it so files land directly in <dir>.
+        const tar = await runProcess('tar', ['-xzf', file, '-C', dir, '--strip-components=1'], { stdio: 'pipe' });
+        if (tar.code !== 0) {
+            throw new SkillError(`❌ 解压 starter 失败（tar 退出码 ${tar.code}）: ${tar.stderr.trim().slice(0, 300)}`);
+        }
+        let installed = false;
+        if (!opts.skipInstall) {
+            emitProgress({ phase: 'template-init:install', progress: 0.6 });
+            out.info('安装依赖（npm install）…');
+            const inst = await runNpm(['install', '--no-audit', '--no-fund'], { cwd: dir, stdio: 'stderr' });
+            if (inst.code !== 0) {
+                throw new SkillError(`❌ npm install 失败（退出码 ${inst.code}）。工程文件已解压到 ${dir}，修复后在该目录重跑 npm install。`);
+            }
+            installed = true;
+        }
+        emitProgress({ phase: 'template-init:done', progress: 1 });
+        printNextSteps(out, dir, installed);
+        const result = { ok: true, dir, starter: label, installed };
+        out.result({ ...result });
+        return result;
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}
+function printNextSteps(out, dir, installed) {
+    const rel = path.relative(process.cwd(), dir) || '.';
+    out.info('');
+    out.info(`✅ 模板工程已创建: ${dir}`);
+    out.info('');
+    out.info('下一步：');
+    out.info(`  cd ${rel}`);
+    if (!installed)
+        out.info('  npm install');
+    out.info('  npm run dev                          # 打开 Remotion Studio 本地预览');
+    out.info('  remixmate template check <name>      # 本地校验（无需登录）');
+    out.info('  remixmate template preview <name>    # 远程渲染预览 mp4（需登录）');
+    out.info('  remixmate template publish <name>    # 发布为你的私有模板（需登录）');
+    out.info('');
+    out.info('在本地 agent 里使用：');
+    out.info('  Codex / WorkBuddy   在工程目录打开，agent 会读取 AGENTS.md');
+    out.info('  Claude Code         在工程目录打开，agent 会读取 CLAUDE.md（与 AGENTS.md 内容相同）');
+    out.info('  TraeWork            只认项目级 skill：在工程目录执行一次 remixmate install --project');
+    out.info('  其它宿主若还没装 skill：remixmate install');
+}

package/dist/template/list.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `remixmate template list` — the caller's own (non-builtin) templates.
+ *
+ * Uses ab-api `/remotionTemplate/myPage` (the "mine" view: user_id = caller,
+ * is_builtin = 0, not deleted). The builtin filter is re-applied client side
+ * so a backend change can never make this list show platform templates.
+ */
+export interface ListOptions {
+    json?: boolean;
+    token?: string;
+    apiBaseUrl?: string;
+}
+export interface PrivateTemplate {
+    templateKey: string;
+    name: string;
+    lifecycleStatus?: string;
+    coreVersion?: string;
+    updateTime?: string;
+}
+export declare function runList(opts: ListOptions): Promise<{
+    ok: true;
+    templates: PrivateTemplate[];
+}>;

package/dist/template/list.js

@@ -0,0 +1,46 @@
+/**
+ * `remixmate template list` — the caller's own (non-builtin) templates.
+ *
+ * Uses ab-api `/remotionTemplate/myPage` (the "mine" view: user_id = caller,
+ * is_builtin = 0, not deleted). The builtin filter is re-applied client side
+ * so a backend change can never make this list show platform templates.
+ */
+import { mmPost, resolveHttpContext } from '../http.js';
+import { padDisplay } from '../text.js';
+import { Output } from './project.js';
+const PAGE_SIZE = 100;
+const MAX_PAGES = 20;
+export async function runList(opts) {
+    const out = new Output(Boolean(opts.json));
+    const ctx = await resolveHttpContext('template-list', { privateToken: opts.token, apiBaseUrl: opts.apiBaseUrl });
+    const templates = [];
+    for (let current = 1; current <= MAX_PAGES; current++) {
+        const page = await mmPost(ctx, '/remotionTemplate/myPage', { current, pageSize: PAGE_SIZE }, { timeoutMs: 30_000 });
+        const list = page?.list ?? [];
+        for (const t of list) {
+            if (t.isBuiltin === true)
+                continue;
+            templates.push({
+                templateKey: String(t.templateKey ?? ''),
+                name: String(t.name ?? ''),
+                lifecycleStatus: typeof t.lifecycleStatus === 'string' ? t.lifecycleStatus : undefined,
+                coreVersion: typeof t.coreVersion === 'string' && t.coreVersion ? t.coreVersion : undefined,
+                updateTime: typeof t.updateTime === 'string' ? t.updateTime : undefined,
+            });
+        }
+        const total = page?.pager?.total ?? 0;
+        if (list.length < PAGE_SIZE || current * PAGE_SIZE >= total)
+            break;
+    }
+    if (templates.length === 0) {
+        out.info('还没有私有模板。用 remixmate template publish <name> 发布一个。');
+    }
+    else {
+        for (const t of templates) {
+            out.info(`  ${padDisplay(t.templateKey, 32)}${padDisplay(t.name, 24)}${padDisplay(t.lifecycleStatus ?? '', 12)}${t.updateTime ?? ''}`);
+        }
+    }
+    const result = { ok: true, templates };
+    out.result(result);
+    return result;
+}

package/dist/template/preview.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `remixmate template preview <name>` — render a draft mp4 on the real ab-render.
+ *
+ * Ported from template-library `scripts/preview-remote.mjs` (same HTTP contract,
+ * same file-enumeration and sample-props rules). It deliberately does NOT
+ * reimplement the DSL → TemplateBinding pipeline: preview answers "does this
+ * code run in the real renderer"; binding correctness is `render-video`'s job.
+ *
+ * Sample props are contract-driven: they come from the template's own
+ * `dsl-example.json` through the `slotMapping[slot].propExtractors` it declares,
+ * plus two global conventions (scene.customPayload → props.templateData,
+ * dsl.assets → resolvedAssets). Nothing here knows any specific template.
+ */
+export declare const PREVIEW_LIMIT_MESSAGE: string;
+export interface PreviewOptions {
+    name: string;
+    propsJson?: string;
+    durationSec?: number;
+    compositionId?: string;
+    timeoutSec?: number;
+    json?: boolean;
+    token?: string;
+    apiBaseUrl?: string;
+    cwd?: string;
+    /** Poll interval override (tests). */
+    pollIntervalMs?: number;
+}
+type Json = Record<string, any>;
+export declare function collectFiles(root: string, warn?: (m: string) => void): {
+    files: Record<string, string>;
+    bytes: number;
+};
+export interface SampleProps {
+    props: Json | Json[];
+    assets: unknown[];
+    durationSec: number | null;
+    scene?: Json;
+}
+export declare function buildSampleProps(tplDir: string, tpl: Json, compositionId: string, propsJson: string | undefined, warn?: (m: string) => void): SampleProps;
+/** Narration → subtitle segments (exact from items[].atSec, else proportional by sentence). */
+export declare function buildSubtitleSegments(scene: Json | undefined, totalFrames: number): Json[];
+/** Largest even-pixel frame of the given aspect that fits the draft preview limits. */
+export declare function previewDimensions(aspect: string): [number, number];
+export interface PreviewPlan {
+    files: Record<string, string>;
+    inputProps: Json;
+    compositionId: string;
+    totalSeconds: number;
+}
+export declare function buildPreviewPlan(tplDir: string, opts: Pick<PreviewOptions, 'propsJson' | 'durationSec' | 'compositionId'>, warn?: (m: string) => void): PreviewPlan;
+export interface PreviewResult {
+    ok: true;
+    name: string;
+    taskId: string;
+    url: string;
+    compositionId: string;
+    durationSec: number;
+}
+export declare function runPreview(opts: PreviewOptions): Promise<PreviewResult>;
+export {};

package/dist/template/preview.js

@@ -0,0 +1,318 @@
+/**
+ * `remixmate template preview <name>` — render a draft mp4 on the real ab-render.
+ *
+ * Ported from template-library `scripts/preview-remote.mjs` (same HTTP contract,
+ * same file-enumeration and sample-props rules). It deliberately does NOT
+ * reimplement the DSL → TemplateBinding pipeline: preview answers "does this
+ * code run in the real renderer"; binding correctness is `render-video`'s job.
+ *
+ * Sample props are contract-driven: they come from the template's own
+ * `dsl-example.json` through the `slotMapping[slot].propExtractors` it declares,
+ * plus two global conventions (scene.customPayload → props.templateData,
+ * dsl.assets → resolvedAssets). Nothing here knows any specific template.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { EXIT, SkillError } from '../errors.js';
+import { resolveHttpContext } from '../http.js';
+import { emitProgress } from '../progress.js';
+import { IDENTITY_FILE, PREVIEW_MAX_LONG_EDGE, PREVIEW_MAX_SECONDS, PREVIEW_MAX_SHORT_EDGE, } from './constants.js';
+import { runCheck } from './check.js';
+import { Output, readJsonFile, requireProjectRoot, requireTemplateDir, validateTemplateName } from './project.js';
+import { RenderBusinessError, renderPost, resolveRenderBaseUrl } from './render-client.js';
+const FPS = 30;
+const DEFAULT_DURATION_SEC = 5;
+const DEFAULT_TIMEOUT_SEC = 180;
+// Same enumeration rules as preview-remote.mjs.
+const SKIP_DIRS = new Set(['node_modules', 'dist', '__pycache__', '.git']);
+const TEXT_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mts', '.cts', '.json', '.css', '.scss', '.md']);
+const MAX_FILE_BYTES = 512 * 1024;
+const WARN_TOTAL_BYTES = 20 * 1024 * 1024;
+/** Keys must stay in sync with the metadata schema's supportedAspectRatios enum. */
+const ASPECT_RATIOS = {
+    '16:9': [16, 9],
+    '9:16': [9, 16],
+    '1:1': [1, 1],
+    '3:4': [3, 4],
+    '4:3': [4, 3],
+};
+export const PREVIEW_LIMIT_MESSAGE = `草稿预览超出上限：长边 ≤ ${PREVIEW_MAX_LONG_EDGE}px、短边 ≤ ${PREVIEW_MAX_SHORT_EDGE}px、时长 ≤ ${PREVIEW_MAX_SECONDS} 秒。` +
+    '请缩短 --duration-sec，或减少 --props-json 的页数；正式出片用 remixmate render-video，不受此限。';
+// ── files ────────────────────────────────────────────────────────────────────
+export function collectFiles(root, warn = () => { }) {
+    const files = {};
+    let bytes = 0;
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name))
+                    walk(full);
+                continue;
+            }
+            if (!TEXT_EXTS.has(path.extname(entry.name)))
+                continue;
+            if (/\.(test|spec)\./.test(entry.name))
+                continue;
+            // Local publish identity — not template source.
+            if (dir === root && entry.name === IDENTITY_FILE)
+                continue;
+            const size = statSync(full).size;
+            if (size > MAX_FILE_BYTES) {
+                warn(`  ⚠ 跳过超大文件（${(size / 1024).toFixed(0)} KB）：${path.relative(root, full)}`);
+                continue;
+            }
+            bytes += size;
+            files[path.relative(root, full).split(path.sep).join('/')] = readFileSync(full, 'utf8');
+        }
+    };
+    walk(root);
+    return { files, bytes };
+}
+// ── sample props ─────────────────────────────────────────────────────────────
+function applyExtractors(scene, extractors) {
+    const out = {};
+    for (const [propName, spec] of Object.entries(extractors ?? {})) {
+        if (!spec || typeof spec.from !== 'string')
+            continue;
+        const from = spec.from;
+        if (from === 'textLayers') {
+            const layer = (scene.textLayers ?? []).find((l) => l.role === spec.role);
+            if (layer?.content !== undefined)
+                out[propName] = layer.content;
+            continue;
+        }
+        const value = from.split('.').reduce((acc, k) => (acc == null ? acc : acc[k]), scene); // eslint-disable-line @typescript-eslint/no-explicit-any
+        if (value !== undefined)
+            out[propName] = value;
+    }
+    return out;
+}
+export function buildSampleProps(tplDir, tpl, compositionId, propsJson, warn = () => { }) {
+    const examplePath = path.join(tplDir, 'dsl-example.json');
+    const dsl = existsSync(examplePath) ? readJsonFile(examplePath) : null;
+    const assets = Array.isArray(dsl?.assets) ? dsl.assets : [];
+    // --props-json overrides props but keeps the example's asset table: assetRefs
+    // in the override still need something to resolve against.
+    if (propsJson !== undefined) {
+        let props;
+        try {
+            props = JSON.parse(propsJson);
+        }
+        catch (err) {
+            throw new SkillError(`❌ --props-json 解析失败: ${err.message}`, EXIT.USAGE);
+        }
+        return { props, assets, durationSec: null };
+    }
+    const scene = (dsl?.scenes ?? [])[0];
+    if (!scene)
+        return { props: {}, assets, durationSec: null };
+    const slot = (tpl.compositions ?? []).find((c) => c.compositionId === compositionId)?.slot;
+    const extractors = slot ? tpl.slotMapping?.[slot]?.propExtractors : undefined;
+    // Covers render through a dedicated channel and never declare slotMapping.cover.
+    if (slot && slot !== 'cover' && !extractors) {
+        warn(`  ⚠ template.json 的 slotMapping.${slot} 未声明 propExtractors —— 预览将只带 templateData。`);
+    }
+    const props = applyExtractors(scene, extractors);
+    if (scene.customPayload)
+        props.templateData = scene.customPayload;
+    return { props, assets, durationSec: typeof scene.duration === 'number' ? scene.duration : null, scene };
+}
+/** Narration → subtitle segments (exact from items[].atSec, else proportional by sentence). */
+export function buildSubtitleSegments(scene, totalFrames) {
+    const narration = scene?.audio?.narration;
+    if (!narration)
+        return [];
+    const finish = (segs) => segs
+        .filter((s) => s.text)
+        .map((s, i, arr) => ({
+        text: s.text,
+        startFrame: Math.max(0, Math.round(s.startFrame)),
+        endFrame: i === arr.length - 1 ? totalFrames : Math.round(arr[i + 1].startFrame),
+    }))
+        .filter((s) => s.endFrame > s.startFrame);
+    const items = Array.isArray(narration.items) ? narration.items : null;
+    if (items && items.length > 0 && items.some((it) => typeof it?.atSec === 'number')) {
+        let cursor = 0;
+        return finish(items.map((it) => {
+            const at = typeof it?.atSec === 'number' ? it.atSec * FPS : cursor;
+            cursor = at;
+            return { text: it?.text ?? '', startFrame: at };
+        }));
+    }
+    const text = typeof narration.text === 'string' ? narration.text.trim() : '';
+    if (!text)
+        return [];
+    const sentences = text.split(/(?<=[。！？!?])/).map((s) => s.trim()).filter(Boolean);
+    if (sentences.length === 0)
+        return [];
+    const weights = sentences.map((s) => Math.max(1, s.length));
+    const total = weights.reduce((a, b) => a + b, 0);
+    let acc = 0;
+    return finish(sentences.map((s, i) => {
+        const startFrame = (acc / total) * totalFrames;
+        acc += weights[i];
+        return { text: s, startFrame };
+    }));
+}
+/** Largest even-pixel frame of the given aspect that fits the draft preview limits. */
+export function previewDimensions(aspect) {
+    const [aw, ah] = ASPECT_RATIOS[aspect] ?? ASPECT_RATIOS['16:9'];
+    const landscape = aw >= ah;
+    const long = landscape ? aw : ah;
+    const short = landscape ? ah : aw;
+    const scale = Math.min(PREVIEW_MAX_LONG_EDGE / long, PREVIEW_MAX_SHORT_EDGE / short);
+    const even = (n) => Math.floor(n / 2) * 2;
+    const w = even(aw * scale);
+    const h = even(ah * scale);
+    return [w, h];
+}
+export function buildPreviewPlan(tplDir, opts, warn = () => { }) {
+    const tpl = readJsonFile(path.join(tplDir, 'template.json'));
+    const comps = Array.isArray(tpl.compositions) ? tpl.compositions : [];
+    const compositionId = opts.compositionId ?? comps[0]?.compositionId;
+    if (!compositionId)
+        throw new SkillError('❌ template.json 未声明 compositions', EXIT.USAGE);
+    if (opts.compositionId && !comps.some((c) => c.compositionId === compositionId)) {
+        throw new SkillError(`❌ composition "${compositionId}" 不在该模板中。可选: ${comps.map((c) => c.compositionId).join(', ')}`, EXIT.USAGE);
+    }
+    const { files, bytes } = collectFiles(tplDir, warn);
+    if (Object.keys(files).length === 0)
+        throw new SkillError('❌ 模板目录没有可提交的源文件');
+    if (bytes > WARN_TOTAL_BYTES)
+        warn(`  ⚠ 模板总体积 ${(bytes / 1024 / 1024).toFixed(1)} MB，接近 ab-render 的请求上限`);
+    const sample = buildSampleProps(tplDir, tpl, compositionId, opts.propsJson, warn);
+    const aspect = (tpl.supportedAspectRatios ?? [])[0] ?? '16:9';
+    const durationSec = Number(opts.durationSec ?? sample.durationSec ?? tpl.supportedDurations?.min ?? DEFAULT_DURATION_SEC);
+    const [width, height] = previewDimensions(aspect);
+    // An array of props = one page each, chained into a multi-entry timeline.
+    const propsList = Array.isArray(sample.props) ? sample.props : null;
+    const perSceneFrames = Math.max(1, Math.round(durationSec * FPS));
+    const totalFrames = propsList ? perSceneFrames * propsList.length : perSceneFrames;
+    const totalSeconds = totalFrames / FPS;
+    if (totalSeconds > PREVIEW_MAX_SECONDS) {
+        throw new SkillError(`❌ ${PREVIEW_LIMIT_MESSAGE}（本次 ${totalSeconds.toFixed(1)} 秒）`, EXIT.USAGE);
+    }
+    const subtitleSegments = propsList ? [] : buildSubtitleSegments(sample.scene, perSceneFrames);
+    const timeline = (propsList ?? [sample.props]).map((props, i) => {
+        const startFrame = i * perSceneFrames;
+        const endFrame = startFrame + perSceneFrames;
+        return {
+            sceneId: propsList ? `preview-${String(i + 1).padStart(2, '0')}` : 'preview',
+            compositionId,
+            startFrame,
+            endFrame,
+            durationFrames: perSceneFrames,
+            startTime: Number((startFrame / FPS).toFixed(2)),
+            endTime: Number((endFrame / FPS).toFixed(2)),
+            props,
+            layers: [],
+            subtitleSegments,
+            transition: { type: 'none', durationFrames: 0 },
+        };
+    });
+    const inputProps = {
+        timeline,
+        renderConfig: {
+            width,
+            height,
+            fps: FPS,
+            totalFrames,
+            totalDuration: Number(totalSeconds.toFixed(2)),
+            codec: 'h264',
+            crf: 18,
+            outputFormat: 'mp4',
+        },
+        resolvedAssets: sample.assets,
+        globalTypography: tpl.defaultTypography,
+        colorScheme: tpl.defaultColorScheme,
+        motionPreset: tpl.defaultMotionPreset,
+    };
+    return { files, inputProps, compositionId, totalSeconds };
+}
+function isLimitError(err) {
+    return JSON.stringify(err.payload ?? {}).includes('draft_preview_limit_exceeded');
+}
+function printScanIssues(out, err) {
+    const data = err.payload?.data;
+    const issues = data?.issues ?? err.payload?.issues;
+    if (!Array.isArray(issues) || issues.length === 0)
+        return false;
+    out.warn(`\n✗ 被 ab-render 的安全扫描拒绝（${issues.length} 处）：`);
+    for (const i of issues) {
+        out.warn(typeof i === 'string' ? `    · ${i}` : `    · ${i.file}\n      ${i.reason}${i.detail ? `: ${i.detail}` : ''}`);
+    }
+    out.warn('\n  先在本地运行 remixmate template check，它与平台使用同一份安全策略。');
+    return true;
+}
+export async function runPreview(opts) {
+    const out = new Output(Boolean(opts.json));
+    const name = validateTemplateName(opts.name);
+    const root = requireProjectRoot(opts.cwd);
+    const tplDir = requireTemplateDir(root, name);
+    emitProgress({ phase: 'template-preview:check', progress: 0.05 });
+    const checkCode = await runCheck({ name, cwd: root, stdio: opts.json ? 'stderr' : 'inherit' });
+    if (checkCode !== 0) {
+        throw new SkillError(`❌ 本地校验未通过（check 退出码 ${checkCode}），已中止预览。`, checkCode === 2 ? EXIT.USAGE : EXIT.ERROR);
+    }
+    const plan = buildPreviewPlan(tplDir, opts, (m) => out.warn(m));
+    const http = await resolveHttpContext('template-preview', { privateToken: opts.token, apiBaseUrl: opts.apiBaseUrl });
+    const base = resolveRenderBaseUrl();
+    const { width, height } = plan.inputProps.renderConfig;
+    out.info(`模板        ${name}`);
+    out.info(`composition ${plan.compositionId}`);
+    out.info(`画幅        ${width}×${height}  ${plan.totalSeconds.toFixed(1)}s @${FPS}fps`);
+    out.info(`文件        ${Object.keys(plan.files).length} 个`);
+    out.info(`ab-render   ${base}`);
+    const post = (route, body) => renderPost(base, route, body, { token: http.privateToken, skillName: 'template-preview' });
+    let taskId;
+    try {
+        emitProgress({ phase: 'template-preview:submit', progress: 0.1 });
+        const start = await post('/renderDraft', { files: plan.files, inputProps: plan.inputProps, upload: false });
+        if (!start.taskId)
+            throw new SkillError('❌ /renderDraft 未返回 taskId');
+        taskId = start.taskId;
+    }
+    catch (err) {
+        if (err instanceof RenderBusinessError) {
+            if (isLimitError(err))
+                throw new SkillError(`❌ ${PREVIEW_LIMIT_MESSAGE}`, EXIT.ERROR);
+            if (printScanIssues(out, err))
+                throw new SkillError('❌ 预览被安全扫描拒绝', EXIT.ERROR);
+        }
+        throw err;
+    }
+    out.info(`taskId      ${taskId}`);
+    const timeoutSec = opts.timeoutSec ?? DEFAULT_TIMEOUT_SEC;
+    const interval = opts.pollIntervalMs ?? 1500;
+    const deadline = Date.now() + timeoutSec * 1000;
+    let lastStatus = '';
+    for (;;) {
+        if (Date.now() > deadline) {
+            // A timeout doesn't mean the task is gone — it's usually still queued.
+            throw new SkillError(`❌ 轮询超时（${timeoutSec}s），任务 ${taskId} 仍在 ab-render 排队/渲染。\n` +
+                '   加长等待：--timeout-sec 900');
+        }
+        await new Promise((r) => setTimeout(r, interval));
+        const st = await post('/renderDraftStatus', { taskId });
+        if (st.status !== lastStatus) {
+            lastStatus = st.status ?? '';
+            out.info(st.status === 'pending' ? '排队中…（队列前面还有任务）' : `状态: ${st.status}`);
+        }
+        emitProgress({ phase: `template-preview:${st.status ?? 'unknown'}`, progress: 0.1 + 0.9 * (st.progress ?? 0), taskId });
+        if (st.status === 'succeeded') {
+            const url = st.previewUrl?.startsWith('http') ? st.previewUrl : `${base}${st.previewUrl ?? ''}`;
+            out.info(`\n✅ 预览就绪\n  ${url}`);
+            out.info('  临时产物，最长保留 24 小时（服务重启后可能更早失效）。');
+            const result = { ok: true, name, taskId, url, compositionId: plan.compositionId, durationSec: plan.totalSeconds };
+            out.result({ ...result });
+            return result;
+        }
+        if (st.status === 'failed') {
+            const detail = st.error ?? '（无错误详情）';
+            if (detail.includes('draft_preview_limit_exceeded'))
+                throw new SkillError(`❌ ${PREVIEW_LIMIT_MESSAGE}`);
+            throw new SkillError(`❌ 渲染失败: ${detail}`);
+        }
+    }
+}

package/dist/template/proc.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Child-process helpers for `remixmate template`.
+ *
+ * Every command is spawned with an argv array — never a shell string — so a
+ * directory or package spec can't be interpreted by a shell. The one exception
+ * is npm on Windows: `npm` is `npm.cmd` there, and since Node's CVE-2024-27980
+ * fix a .cmd can only be spawned with `shell: true`. For that path we only ever
+ * pass fixed tokens or validated package specs (paths travel via `cwd`), and
+ * refuse anything containing shell metacharacters.
+ */
+export interface ProcResult {
+    code: number;
+    /** Captured stdout — only populated when stdout is piped. */
+    stdout: string;
+    stderr: string;
+}
+export interface ProcOptions {
+    cwd?: string;
+    /** 'inherit' streams to the terminal; 'pipe' captures. Default: inherit. */
+    stdio?: 'inherit' | 'pipe' | 'stderr';
+    env?: NodeJS.ProcessEnv;
+    shell?: boolean;
+}
+export declare function runProcess(command: string, args: string[], opts?: ProcOptions): Promise<ProcResult>;
+/** Run npm portably. `args` must be plain tokens; paths go through `cwd`. */
+export declare function runNpm(args: string[], opts?: Omit<ProcOptions, 'shell'>): Promise<ProcResult>;

package/dist/template/proc.js

@@ -0,0 +1,43 @@
+/**
+ * Child-process helpers for `remixmate template`.
+ *
+ * Every command is spawned with an argv array — never a shell string — so a
+ * directory or package spec can't be interpreted by a shell. The one exception
+ * is npm on Windows: `npm` is `npm.cmd` there, and since Node's CVE-2024-27980
+ * fix a .cmd can only be spawned with `shell: true`. For that path we only ever
+ * pass fixed tokens or validated package specs (paths travel via `cwd`), and
+ * refuse anything containing shell metacharacters.
+ */
+import { spawn } from 'node:child_process';
+import { EXIT, SkillError } from '../errors.js';
+export function runProcess(command, args, opts = {}) {
+    const mode = opts.stdio ?? 'inherit';
+    // 'stderr' = child output is human progress (npm install chatter), route it
+    // to our stderr so our stdout stays the result/progress protocol.
+    const stdio = mode === 'inherit' ? 'inherit' : mode === 'pipe' ? ['ignore', 'pipe', 'pipe'] : ['ignore', 'pipe', 'inherit'];
+    return new Promise((resolve, reject) => {
+        let stdout = '';
+        let stderr = '';
+        const child = spawn(command, args, { cwd: opts.cwd, stdio, env: opts.env ?? process.env, shell: opts.shell ?? false });
+        child.stdout?.on('data', (d) => {
+            if (mode === 'stderr')
+                process.stderr.write(d);
+            else
+                stdout += d.toString();
+        });
+        child.stderr?.on('data', (d) => (stderr += d.toString()));
+        child.on('error', (err) => reject(new SkillError(`❌ 无法启动 ${command}: ${err.message}`, EXIT.SPAWN_FAILED)));
+        child.on('close', (code, signal) => resolve({ code: signal ? EXIT.ERROR : code ?? EXIT.ERROR, stdout, stderr }));
+    });
+}
+const SAFE_SHELL_ARG = /^[A-Za-z0-9@._/:=+-]+$/;
+/** Run npm portably. `args` must be plain tokens; paths go through `cwd`. */
+export function runNpm(args, opts = {}) {
+    if (process.platform !== 'win32')
+        return runProcess('npm', args, opts);
+    for (const a of args) {
+        if (!SAFE_SHELL_ARG.test(a))
+            throw new SkillError(`❌ 拒绝把不安全的参数交给 npm.cmd: ${a}`);
+    }
+    return runProcess('npm.cmd', args, { ...opts, shell: true });
+}

package/dist/template/project.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Starter-project discovery, template identity (K4) and the shared output helper.
+ */
+/** Walk up from `start` to the directory holding `.remixmate/check/index.mjs`. */
+export declare function findProjectRoot(start?: string): string | null;
+export declare function requireProjectRoot(start?: string): string;
+/** A template name is a single directory under templates/ — never a path. */
+export declare function validateTemplateName(name: string | undefined): string;
+export declare function requireTemplateDir(root: string, name: string): string;
+export declare function readJsonFile<T = Record<string, unknown>>(file: string): T;
+export interface TemplateIdentity {
+    templateKey: string;
+    version: number;
+}
+/** kebab-case slug of a directory name; falls back to `template` when nothing survives. */
+export declare function kebabSlug(input: string): string;
+/** First-publish key: `my-<slug>-<6 hex>`. */
+export declare function generateTemplateKey(dirName: string, hex?: string): string;
+export declare function readIdentity(templateDir: string): TemplateIdentity | null;
+/** Stable key: the identity file wins, so renaming the directory never forks a template. */
+export declare function resolveTemplateKey(templateDir: string): {
+    templateKey: string;
+    existing: boolean;
+};
+export declare function writeIdentity(templateDir: string, identity: TemplateIdentity): void;
+/**
+ * Human text goes to stdout by default. With --json it moves to stderr so the
+ * last stdout line is the JSON result (progress lines still go to stdout —
+ * hosts parse them by their `__progress__` marker).
+ */
+export declare class Output {
+    readonly json: boolean;
+    constructor(json: boolean);
+    info(line?: string): void;
+    warn(line: string): void;
+    result(obj: Record<string, unknown>): void;
+}