@remixmate/cli 0.9.64 → 0.9.65

package/dist/cli.js

@@ -21,6 +21,8 @@ import { runExec } from './exec.js';
 import { authStatusLine, runDoctor } from './doctor.js';
 import { padDisplay } from './text.js';
 import { EXIT, SkillError } from './errors.js';
+import { TEMPLATE_VERB, runTemplateCommand } from './template/commands.js';
+import { diagnostic } from './diagnostics.js';
 /** Reserved auth verbs handled before skill dispatch. */
 const AUTH_VERBS = new Set(['login', 'logout', 'whoami']);
 /**
@@ -64,6 +66,11 @@ function printUsage() {
     process.stdout.write('  remixmate project use <prj> [--global]  Bind output to a project (this dir, or globally)\n');
     process.stdout.write('  remixmate project show                Show the current project binding\n');
     process.stdout.write('  remixmate host probe                  Diagnose host detection and take grouping\n');
+    process.stdout.write('  remixmate template init <dir>         Create a video-template project (no login)\n');
+    process.stdout.write('  remixmate template check [name]       Validate templates locally (no login)\n');
+    process.stdout.write('  remixmate template preview <name>     Render a draft preview mp4 remotely\n');
+    process.stdout.write('  remixmate template publish <name>     Publish as your private template\n');
+    process.stdout.write('  remixmate template list               List your private templates\n');
     process.stdout.write('  remixmate <name> [--flag value ...]   Invoke a skill\n');
     process.stdout.write('  remixmate <name> --help               Show skill-specific help\n');
     process.stdout.write('\nAvailable skills:\n');
@@ -155,6 +162,12 @@ async function main() {
     if (argv[0] === HOST_VERB) {
         process.exit(await runHostCommand(argv.slice(1)));
     }
+    if (argv[0] === TEMPLATE_VERB) {
+        const started = performance.now();
+        const code = await runTemplateCommand(argv.slice(1));
+        diagnostic(code, performance.now() - started);
+        process.exit(code);
+    }
     if (argv[0] === 'exec') {
         // Raw argv (not parsed) — everything after `--` belongs to the child command.
         const code = await runExec(argv.slice(1));

package/dist/handlers/index.js

@@ -8,9 +8,11 @@ import { genImage } from './gen-image.js';
 import { genVoice } from './gen-voice.js';
 import { genVideo } from './gen-video.js';
 import { genDigitalHuman } from './gen-digital-human.js';
+import { templateInit } from './template-init.js';
 export const HANDLERS = {
     'gen-image': genImage,
     'gen-voice': genVoice,
     'gen-video': genVideo,
     'gen-digital-human': genDigitalHuman,
+    'template-init': templateInit,
 };

package/dist/handlers/template-init.d.ts

@@ -0,0 +1,10 @@
+/**
+ * template-authoring skill → `remixmate template init`.
+ *
+ * Agent hosts call skills as `remixmate template-authoring --dir X [--force]`;
+ * this handler is a thin adapter so both entry points share one implementation.
+ * Purely local (auth: none): fetches the starter via npm, no ab-api calls.
+ */
+import type { HandlerContext, HandlerInput } from './index.js';
+export declare function templateInit(input: HandlerInput, _ctx: HandlerContext): Promise<void>;
+export default templateInit;

package/dist/handlers/template-init.js

@@ -0,0 +1,21 @@
+/**
+ * template-authoring skill → `remixmate template init`.
+ *
+ * Agent hosts call skills as `remixmate template-authoring --dir X [--force]`;
+ * this handler is a thin adapter so both entry points share one implementation.
+ * Purely local (auth: none): fetches the starter via npm, no ab-api calls.
+ */
+import { EXIT, SkillError } from '../errors.js';
+import { runInit } from '../template/init.js';
+export async function templateInit(input, _ctx) {
+    const dir = typeof input.dir === 'string' ? input.dir.trim() : '';
+    if (!dir)
+        throw new SkillError('❌ 缺少 --dir：模板工程的目标目录', EXIT.USAGE);
+    await runInit({
+        dir,
+        force: input.force === true || input.force === 'true',
+        json: input.json_output === true || input.json === true,
+        skipInstall: input.skip_install === true,
+    });
+}
+export default templateInit;

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.64",
-  "generatedAt": "2026-10-04T11:52:39.175Z",
+  "version": "0.9.65",
+  "generatedAt": "2026-10-05T06:33:09.117Z",
   "skills": [
     {
       "id": "doc-parse",
@@ -932,6 +932,56 @@
         "hidden": []
       }
     },
+    {
+      "id": "template-authoring",
+      "toolName": "template_authoring",
+      "tier": "tool",
+      "category": "meta",
+      "title": "Video Template Authoring",
+      "summary": "Start authoring a custom video template locally: scaffolds a starter project (Remotion Studio preview, local validation, remote draft preview, publishing as the user's private template) into the given directory. After this, follow the project's AGENTS.md and use `remixmate template check|preview|publish`. Local-only; requires Node >= 18 and npm.",
+      "triggers": [
+        "做视频模板",
+        "自定义视频模板",
+        "创建模板 / 新建模板 / 自己写一个视频模板",
+        "预览或发布我本地开发的模板",
+        "template authoring",
+        "create video template / build a custom video template",
+        "publish my own Remotion template"
+      ],
+      "entry": {
+        "type": "builtin",
+        "handler": "template-init"
+      },
+      "runtime": "node",
+      "envVars": [
+        "REMIXMATE_STARTER_TARBALL"
+      ],
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "dir": {
+            "type": "string",
+            "description": "Target directory for the new template project (must be empty unless force is set)"
+          },
+          "force": {
+            "type": "boolean",
+            "description": "Allow scaffolding into a non-empty directory (existing files with the same name are overwritten)"
+          }
+        },
+        "required": [
+          "dir"
+        ]
+      },
+      "ui": {
+        "primary": [
+          "dir"
+        ],
+        "advanced": [
+          "force"
+        ],
+        "hidden": []
+      }
+    },
     {
       "id": "template-registry",
       "toolName": "template_registry",

package/dist/template/args.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Strict argv parser for `remixmate template <sub>`.
+ *
+ * Unlike src/argv.ts (which is permissive because skill flags are forwarded to
+ * Python), these subcommands own their whole surface, so an unknown flag or a
+ * stray positional is a usage error (exit 2) rather than something silently
+ * ignored — `publish --nmae X` must not publish under the default name.
+ */
+import { SkillError } from '../errors.js';
+export type FlagKind = 'bool' | 'string';
+export type FlagSpec = Record<string, FlagKind>;
+export interface ParsedTemplateArgs {
+    positionals: string[];
+    /** Keyed by the flag name without dashes, kebab-case preserved (`props-json`). */
+    flags: Record<string, string | boolean>;
+}
+/** Flags every subcommand accepts. */
+export declare const COMMON_FLAGS: FlagSpec;
+export declare function usageError(message: string): SkillError;
+export declare function parseTemplateArgs(argv: string[], spec: FlagSpec, opts: {
+    maxPositionals: number;
+}): ParsedTemplateArgs;
+export declare function flagString(flags: ParsedTemplateArgs['flags'], name: string): string | undefined;
+/** Parse a positive number flag; usage error on anything else. */
+export declare function flagNumber(flags: ParsedTemplateArgs['flags'], name: string): number | undefined;

package/dist/template/args.js

@@ -0,0 +1,69 @@
+/**
+ * Strict argv parser for `remixmate template <sub>`.
+ *
+ * Unlike src/argv.ts (which is permissive because skill flags are forwarded to
+ * Python), these subcommands own their whole surface, so an unknown flag or a
+ * stray positional is a usage error (exit 2) rather than something silently
+ * ignored — `publish --nmae X` must not publish under the default name.
+ */
+import { EXIT, SkillError } from '../errors.js';
+/** Flags every subcommand accepts. */
+export const COMMON_FLAGS = {
+    json: 'bool',
+    help: 'bool',
+    token: 'string',
+    'api-base-url': 'string',
+};
+export function usageError(message) {
+    return new SkillError(`❌ ${message}`, EXIT.USAGE);
+}
+export function parseTemplateArgs(argv, spec, opts) {
+    const all = { ...COMMON_FLAGS, ...spec };
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '-h') {
+            flags.help = true;
+            continue;
+        }
+        if (!token.startsWith('--')) {
+            positionals.push(token);
+            continue;
+        }
+        const eq = token.indexOf('=');
+        const name = token.slice(2, eq > 0 ? eq : undefined);
+        const kind = all[name];
+        if (!kind)
+            throw usageError(`未知参数: --${name}`);
+        if (kind === 'bool') {
+            if (eq > 0)
+                throw usageError(`--${name} 不接受取值`);
+            flags[name] = true;
+            continue;
+        }
+        const value = eq > 0 ? token.slice(eq + 1) : argv[++i];
+        if (value === undefined || (eq < 0 && value.startsWith('--'))) {
+            throw usageError(`--${name} 需要一个取值`);
+        }
+        flags[name] = value;
+    }
+    if (!flags.help && positionals.length > opts.maxPositionals) {
+        throw usageError(`多余的参数: ${positionals.slice(opts.maxPositionals).join(' ')}`);
+    }
+    return { positionals, flags };
+}
+export function flagString(flags, name) {
+    const v = flags[name];
+    return typeof v === 'string' ? v : undefined;
+}
+/** Parse a positive number flag; usage error on anything else. */
+export function flagNumber(flags, name) {
+    const raw = flagString(flags, name);
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        throw usageError(`--${name} 必须是正数，收到 '${raw}'`);
+    return n;
+}

package/dist/template/check.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `remixmate template check [name] [--json] [--no-write]`
+ *
+ * Pure orchestration: the validation itself lives in the starter
+ * (`.remixmate/check/index.mjs`, K3), synced from the same schema / security
+ * policy sources the platform uses. The cli never carries its own copy — that
+ * would be the drift requirement 5.2 exists to prevent.
+ */
+import { type ProcOptions } from './proc.js';
+export interface CheckOptions {
+    name?: string;
+    json?: boolean;
+    noWrite?: boolean;
+    cwd?: string;
+    /**
+     * Where the check's stdout goes. Standalone `check` streams it straight
+     * through; preview/publish in --json mode route it to stderr so their own
+     * JSON stays the last stdout line.
+     */
+    stdio?: ProcOptions['stdio'];
+}
+/** Run the starter's check script; resolves to its exit code (0 ok / 1 issues / 2 usage). */
+export declare function runCheck(opts?: CheckOptions): Promise<number>;

package/dist/template/check.js

@@ -0,0 +1,25 @@
+/**
+ * `remixmate template check [name] [--json] [--no-write]`
+ *
+ * Pure orchestration: the validation itself lives in the starter
+ * (`.remixmate/check/index.mjs`, K3), synced from the same schema / security
+ * policy sources the platform uses. The cli never carries its own copy — that
+ * would be the drift requirement 5.2 exists to prevent.
+ */
+import path from 'node:path';
+import { CHECK_ENTRY } from './constants.js';
+import { requireProjectRoot } from './project.js';
+import { runProcess } from './proc.js';
+/** Run the starter's check script; resolves to its exit code (0 ok / 1 issues / 2 usage). */
+export async function runCheck(opts = {}) {
+    const root = requireProjectRoot(opts.cwd);
+    const args = [path.join(root, CHECK_ENTRY)];
+    if (opts.name)
+        args.push(opts.name);
+    if (opts.json)
+        args.push('--json');
+    if (opts.noWrite)
+        args.push('--no-write');
+    const res = await runProcess(process.execPath, args, { cwd: root, stdio: opts.stdio ?? 'inherit' });
+    return res.code;
+}

package/dist/template/commands.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `remixmate template <init|check|preview|publish|list>` dispatcher.
+ *
+ * Exit codes follow the cli contract (errors.ts): 2 usage, 4 credentials,
+ * 5 backend unreachable; `check` propagates the starter script's own code.
+ * With --json a failure also ends stdout with `{"ok":false,...}` so hosts
+ * parsing the last line always get an object.
+ */
+import { type FlagSpec, type ParsedTemplateArgs } from './args.js';
+export declare const TEMPLATE_VERB = "template";
+export declare const TEMPLATE_SUBCOMMANDS: readonly ["init", "check", "preview", "publish", "list"];
+export type TemplateSubcommand = (typeof TEMPLATE_SUBCOMMANDS)[number];
+interface SubSpec {
+    flags: FlagSpec;
+    maxPositionals: number;
+    usage: string;
+}
+export declare const SUB_SPECS: Record<TemplateSubcommand, SubSpec>;
+export declare function templateUsage(): string;
+export declare function parseTemplateCommand(argv: string[]): {
+    sub: TemplateSubcommand | 'help';
+    args: ParsedTemplateArgs;
+};
+export declare function runTemplateCommand(argv: string[]): Promise<number>;
+export {};

package/dist/template/commands.js

@@ -0,0 +1,146 @@
+/**
+ * `remixmate template <init|check|preview|publish|list>` dispatcher.
+ *
+ * Exit codes follow the cli contract (errors.ts): 2 usage, 4 credentials,
+ * 5 backend unreachable; `check` propagates the starter script's own code.
+ * With --json a failure also ends stdout with `{"ok":false,...}` so hosts
+ * parsing the last line always get an object.
+ */
+import { cleanDiagnosticText } from '../diagnostics.js';
+import { EXIT, SkillError } from '../errors.js';
+import { flagNumber, flagString, parseTemplateArgs, usageError } from './args.js';
+import { runCheck } from './check.js';
+import { STARTER_PACKAGE, STARTER_VERSION } from './constants.js';
+import { runInit } from './init.js';
+import { runList } from './list.js';
+import { runPreview } from './preview.js';
+import { runPublish } from './publish.js';
+export const TEMPLATE_VERB = 'template';
+export const TEMPLATE_SUBCOMMANDS = ['init', 'check', 'preview', 'publish', 'list'];
+export const SUB_SPECS = {
+    init: {
+        flags: { force: 'bool', 'skip-install': 'bool' },
+        maxPositionals: 1,
+        usage: 'remixmate template init <dir> [--force] [--skip-install] [--json]\n' +
+            `  从 ${STARTER_PACKAGE}@${STARTER_VERSION} 创建模板工程并安装依赖（无需登录）。\n` +
+            '  目标目录非空时拒绝，除非 --force。--skip-install 只解压不执行 npm install。\n',
+    },
+    check: {
+        flags: { 'no-write': 'bool' },
+        maxPositionals: 1,
+        usage: 'remixmate template check [name] [--json] [--no-write]\n' +
+            '  在模板工程内运行本地校验（类型、schema、安全策略、props 契约、core 导出）。\n' +
+            '  不传 name 校验 templates/ 下全部模板；默认刷新 coreVersion/coreExports，--no-write 只检查。\n',
+    },
+    preview: {
+        flags: { 'props-json': 'string', 'duration-sec': 'string', 'composition-id': 'string', 'timeout-sec': 'string' },
+        maxPositionals: 1,
+        usage: 'remixmate template preview <name> [--props-json JSON] [--duration-sec N] [--composition-id ID] [--timeout-sec N] [--json]\n' +
+            '  先 check，再把模板提交到远程渲染器出预览 mp4（需登录）。\n' +
+            '  样例数据取自模板的 dsl-example.json，可用 --props-json 覆盖（传数组 = 每个元素一页）。\n' +
+            '  预览上限：长边 1280、短边 720、总时长 60 秒。\n',
+    },
+    publish: {
+        flags: { name: 'string', 'dry-run': 'bool' },
+        maxPositionals: 1,
+        usage: 'remixmate template publish <name> [--name <displayName>] [--dry-run] [--json]\n' +
+            '  先 check 与 core 预检，再发布为你的私有模板（需登录）。\n' +
+            '  首次发布生成 templateKey 并写入 templates/<name>/.remixmate.json，之后重复发布即更新。\n',
+    },
+    list: {
+        flags: {},
+        maxPositionals: 0,
+        usage: 'remixmate template list [--json]\n  列出你发布的私有模板（需登录）。\n',
+    },
+};
+export function templateUsage() {
+    return ('Usage: remixmate template <command> [options]\n\n' +
+        'Commands:\n' +
+        '  init <dir>         创建模板工程（无需登录）\n' +
+        '  check [name]       本地校验（无需登录）\n' +
+        '  preview <name>     远程渲染预览 mp4\n' +
+        '  publish <name>     发布为私有模板\n' +
+        '  list               列出我的私有模板\n\n' +
+        'Common options: --json  --token <PrivToken>  --api-base-url <url>\n' +
+        '环境变量：AB_RENDER_URL（渲染服务地址）、REMIXMATE_STARTER_TARBALL（init 使用本地 starter 包）\n' +
+        '运行 remixmate template <command> --help 查看子命令说明。\n');
+}
+export function parseTemplateCommand(argv) {
+    const [sub, ...rest] = argv;
+    if (!sub || sub === '--help' || sub === '-h' || sub === 'help') {
+        return { sub: 'help', args: { positionals: [], flags: {} } };
+    }
+    if (!TEMPLATE_SUBCOMMANDS.includes(sub)) {
+        throw usageError(`未知子命令: template ${sub}（可选：${TEMPLATE_SUBCOMMANDS.join(' | ')}）`);
+    }
+    const spec = SUB_SPECS[sub];
+    return { sub: sub, args: parseTemplateArgs(rest, spec.flags, { maxPositionals: spec.maxPositionals }) };
+}
+async function dispatch(sub, args) {
+    const { flags, positionals } = args;
+    const json = flags.json === true;
+    const token = flagString(flags, 'token');
+    const apiBaseUrl = flagString(flags, 'api-base-url');
+    switch (sub) {
+        case 'init':
+            if (!positionals[0])
+                throw usageError('缺少目标目录：remixmate template init <dir>');
+            await runInit({ dir: positionals[0], force: flags.force === true, json, skipInstall: flags['skip-install'] === true });
+            return EXIT.OK;
+        case 'check':
+            return runCheck({ name: positionals[0], json, noWrite: flags['no-write'] === true });
+        case 'preview':
+            await runPreview({
+                name: positionals[0],
+                propsJson: flagString(flags, 'props-json'),
+                durationSec: flagNumber(flags, 'duration-sec'),
+                compositionId: flagString(flags, 'composition-id'),
+                timeoutSec: flagNumber(flags, 'timeout-sec'),
+                json,
+                token,
+                apiBaseUrl,
+            });
+            return EXIT.OK;
+        case 'publish':
+            await runPublish({
+                name: positionals[0],
+                displayName: flagString(flags, 'name'),
+                dryRun: flags['dry-run'] === true,
+                json,
+                token,
+                apiBaseUrl,
+            });
+            return EXIT.OK;
+        case 'list':
+            await runList({ json, token, apiBaseUrl });
+            return EXIT.OK;
+    }
+}
+export async function runTemplateCommand(argv) {
+    const json = argv.includes('--json');
+    let sub;
+    try {
+        const parsed = parseTemplateCommand(argv);
+        sub = parsed.sub;
+        if (sub === 'help') {
+            process.stdout.write(templateUsage());
+            return EXIT.OK;
+        }
+        if (parsed.args.flags.help) {
+            process.stdout.write('Usage: ' + SUB_SPECS[sub].usage);
+            return EXIT.OK;
+        }
+        return await dispatch(sub, parsed.args);
+    }
+    catch (err) {
+        const code = err instanceof SkillError ? err.exitCode : EXIT.ERROR;
+        const message = err instanceof SkillError ? err.message : `❌ unexpected error: ${err.stack ?? String(err)}`;
+        process.stderr.write(cleanDiagnosticText(message, 8192) + '\n');
+        if (code === EXIT.USAGE && sub && sub !== 'help')
+            process.stderr.write('Usage: ' + SUB_SPECS[sub].usage);
+        if (json) {
+            process.stdout.write(JSON.stringify({ ok: false, exitCode: code, error: cleanDiagnosticText(message.replace(/^❌\s*/, ''), 2048) }) + '\n');
+        }
+        return code;
+    }
+}

package/dist/template/constants.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Contract constants for `remixmate template` (design §11 K1 / K5 / K6).
+ *
+ * STARTER_VERSION pins the exact starter release this cli was tested against.
+ * Bumping it is a deliberate cli release, never a range — `init` must produce
+ * the same project on every machine for a given cli version.
+ */
+export declare const STARTER_PACKAGE = "@remixmate/template-starter";
+export declare const STARTER_VERSION = "0.1.0";
+/** Local tarball override (testing a starter before it is published). */
+export declare const STARTER_TARBALL_ENV = "REMIXMATE_STARTER_TARBALL";
+/** Marker file that identifies a starter project root (K3). */
+export declare const CHECK_ENTRY = ".remixmate/check/index.mjs";
+/** Per-template identity file written by publish (K4). */
+export declare const IDENTITY_FILE = ".remixmate.json";
+export declare const DEFAULT_RENDER_BASE_URL = "https://api-render.remixmate.ai";
+/** Draft preview limits enforced by ab-render /renderDraft (K5). */
+export declare const PREVIEW_MAX_LONG_EDGE = 1280;
+export declare const PREVIEW_MAX_SHORT_EDGE = 720;
+export declare const PREVIEW_MAX_SECONDS = 60;
+/**
+ * Same list as template-library `publish-private.mjs` TAR_EXCLUDES. `dsl-example.json`
+ * is deliberately kept: it is the reference DSL the registry ships with the template.
+ */
+export declare const TAR_EXCLUDES: readonly string[];

package/dist/template/constants.js

@@ -0,0 +1,32 @@
+/**
+ * Contract constants for `remixmate template` (design §11 K1 / K5 / K6).
+ *
+ * STARTER_VERSION pins the exact starter release this cli was tested against.
+ * Bumping it is a deliberate cli release, never a range — `init` must produce
+ * the same project on every machine for a given cli version.
+ */
+export const STARTER_PACKAGE = '@remixmate/template-starter';
+export const STARTER_VERSION = '0.1.0';
+/** Local tarball override (testing a starter before it is published). */
+export const STARTER_TARBALL_ENV = 'REMIXMATE_STARTER_TARBALL';
+/** Marker file that identifies a starter project root (K3). */
+export const CHECK_ENTRY = '.remixmate/check/index.mjs';
+/** Per-template identity file written by publish (K4). */
+export const IDENTITY_FILE = '.remixmate.json';
+export const DEFAULT_RENDER_BASE_URL = 'https://api-render.remixmate.ai';
+/** Draft preview limits enforced by ab-render /renderDraft (K5). */
+export const PREVIEW_MAX_LONG_EDGE = 1280;
+export const PREVIEW_MAX_SHORT_EDGE = 720;
+export const PREVIEW_MAX_SECONDS = 60;
+/**
+ * Same list as template-library `publish-private.mjs` TAR_EXCLUDES. `dsl-example.json`
+ * is deliberately kept: it is the reference DSL the registry ships with the template.
+ */
+export const TAR_EXCLUDES = [
+    '__pycache__',
+    'node_modules',
+    'dist',
+    '.DS_Store',
+    '*.test.*',
+    '*.spec.*',
+];

package/dist/template/init.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `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).
+ */
+export interface InitOptions {
+    dir: string;
+    force?: boolean;
+    json?: boolean;
+    /** Skip `npm install` (offline tests, or users who want to pick their own installer). */
+    skipInstall?: boolean;
+}
+export interface InitResult {
+    ok: true;
+    dir: string;
+    starter: string;
+    installed: boolean;
+}
+export declare function runInit(opts: InitOptions): Promise<InitResult>;

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');
+}