@remixmate/cli 0.9.13 → 0.9.15

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Process-wide error type and exit-code contract.
+ *
+ * Extracted from http.ts so the auth gateway (auth/ensure.ts) can throw the same
+ * error type without creating an import cycle (http.ts → ensure.ts → http.ts).
+ * `SkillError` is still re-exported from http.ts, so existing imports are unchanged.
+ *
+ * Exit codes are a CONTRACT with hosts (Claude Code / Codex / ab-agent): an agent
+ * reads the code to decide whether to guide the user through authorization, retry
+ * later, or surface a hard failure. Never reuse a code for a different meaning.
+ */
+export declare const EXIT: {
+    /** Success. */
+    readonly OK: 0;
+    /** Generic runtime failure. */
+    readonly ERROR: 1;
+    /** Usage error — unknown skill / unknown option. */
+    readonly USAGE: 2;
+    /** No usable credential, or the credential was rejected. Host should offer to authorize. */
+    readonly NOT_AUTHENTICATED: 4;
+    /** Backend unreachable / timed out. Distinct from 4 so "log in" isn't suggested for an outage. */
+    readonly BACKEND_UNREACHABLE: 5;
+    /** Failed to spawn the underlying interpreter. */
+    readonly SPAWN_FAILED: 127;
+};
+export declare class SkillError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}

package/dist/errors.js

@@ -0,0 +1,33 @@
+/**
+ * Process-wide error type and exit-code contract.
+ *
+ * Extracted from http.ts so the auth gateway (auth/ensure.ts) can throw the same
+ * error type without creating an import cycle (http.ts → ensure.ts → http.ts).
+ * `SkillError` is still re-exported from http.ts, so existing imports are unchanged.
+ *
+ * Exit codes are a CONTRACT with hosts (Claude Code / Codex / ab-agent): an agent
+ * reads the code to decide whether to guide the user through authorization, retry
+ * later, or surface a hard failure. Never reuse a code for a different meaning.
+ */
+export const EXIT = {
+    /** Success. */
+    OK: 0,
+    /** Generic runtime failure. */
+    ERROR: 1,
+    /** Usage error — unknown skill / unknown option. */
+    USAGE: 2,
+    /** No usable credential, or the credential was rejected. Host should offer to authorize. */
+    NOT_AUTHENTICATED: 4,
+    /** Backend unreachable / timed out. Distinct from 4 so "log in" isn't suggested for an outage. */
+    BACKEND_UNREACHABLE: 5,
+    /** Failed to spawn the underlying interpreter. */
+    SPAWN_FAILED: 127,
+};
+export class SkillError extends Error {
+    exitCode;
+    constructor(message, exitCode = EXIT.ERROR) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = 'SkillError';
+    }
+}

package/dist/exec.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `remixmate exec -- <command> [args...]`
+ *
+ * Runs an arbitrary command with the resolved credential injected into its
+ * environment (`PRIV_TOKEN` + `MM_API_BASE_URL`), using the same gateway that
+ * skill dispatch uses.
+ *
+ * This is the general form of the invariant the auth rework establishes: Node
+ * is the only thing that reads the credential store / keychain / device flow,
+ * and every child process receives the result through its environment. Without
+ * it, maintenance scripts that import `registry_loader` directly (e.g.
+ * scripts/test-template-pipeline.py) would have to re-implement credential
+ * lookup — which is exactly the duplication, and the cross-origin token leak,
+ * that was just removed.
+ *
+ * The token is never printed; it only ever reaches the child's environment.
+ */
+export declare function runExec(argv: string[]): Promise<number>;

package/dist/exec.js

@@ -0,0 +1,47 @@
+/**
+ * `remixmate exec -- <command> [args...]`
+ *
+ * Runs an arbitrary command with the resolved credential injected into its
+ * environment (`PRIV_TOKEN` + `MM_API_BASE_URL`), using the same gateway that
+ * skill dispatch uses.
+ *
+ * This is the general form of the invariant the auth rework establishes: Node
+ * is the only thing that reads the credential store / keychain / device flow,
+ * and every child process receives the result through its environment. Without
+ * it, maintenance scripts that import `registry_loader` directly (e.g.
+ * scripts/test-template-pipeline.py) would have to re-implement credential
+ * lookup — which is exactly the duplication, and the cross-origin token leak,
+ * that was just removed.
+ *
+ * The token is never printed; it only ever reaches the child's environment.
+ */
+import { spawn } from 'node:child_process';
+import { parseArgv } from './argv.js';
+import { EXIT } from './errors.js';
+import { authChildEnv, ensureAuth } from './auth/ensure.js';
+const USAGE = 'Usage: remixmate exec [--api-base-url URL] [--token TOKEN] -- <command> [args...]\n';
+export async function runExec(argv) {
+    const separator = argv.indexOf('--');
+    if (separator === -1 || separator === argv.length - 1) {
+        process.stderr.write(`❌ exec 需要一个 \`--\` 分隔符与要执行的命令。\n${USAGE}`);
+        return EXIT.USAGE;
+    }
+    const flags = parseArgv(argv.slice(0, separator));
+    const [command, ...args] = argv.slice(separator + 1);
+    const auth = await ensureAuth({
+        mode: 'required',
+        apiBaseUrl: typeof flags.api_base_url === 'string' ? flags.api_base_url : undefined,
+        flagToken: typeof flags.token === 'string' ? flags.token : undefined,
+    });
+    return await new Promise((resolve) => {
+        const proc = spawn(command, args, {
+            stdio: 'inherit',
+            env: { ...process.env, ...authChildEnv(auth) },
+        });
+        proc.on('exit', (code, signal) => resolve(signal ? EXIT.ERROR : code ?? EXIT.ERROR));
+        proc.on('error', (err) => {
+            process.stderr.write(`❌ failed to spawn ${command}: ${err.message}\n`);
+            resolve(EXIT.SPAWN_FAILED);
+        });
+    });
+}

package/dist/handlers/gen-digital-human.js

@@ -91,6 +91,7 @@ export async function genDigitalHuman(input, ctxIn) {
     const ctx = await resolveHttpContext(ctxIn.skillName, {
         apiBaseUrl: input.api_base_url,
         privateToken: input.priv_token,
+        preflightToken: ctxIn.auth?.token,
     });
     // ── Mode 1: list avatars ────────────────────────────────────────────────
     if (isTrue(input.list_avatars)) {

package/dist/handlers/gen-image.js

@@ -90,6 +90,7 @@ export async function genImage(input, ctxIn) {
     const ctx = await resolveHttpContext(ctxIn.skillName, {
         apiBaseUrl,
         privateToken: input.priv_token,
+        preflightToken: ctxIn.auth?.token,
     });
     emitProgress({ phase: 'gen-image:request', model, size, n });
     const data = await mmPost(ctx, '/model/genImg', payload, { timeoutMs: 120_000 });

package/dist/handlers/gen-video.js

@@ -85,6 +85,7 @@ export async function genVideo(input, ctxIn) {
     const ctx = await resolveHttpContext(ctxIn.skillName, {
         apiBaseUrl,
         privateToken: input.priv_token,
+        preflightToken: ctxIn.auth?.token,
     });
     const payload = {
         model,

package/dist/handlers/gen-voice.js

@@ -56,6 +56,7 @@ export async function genVoice(input, ctxIn) {
         const ctx = await resolveHttpContext(ctxIn.skillName, {
             apiBaseUrl: input.api_base_url,
             privateToken: input.priv_token,
+            preflightToken: ctxIn.auth?.token,
         });
         return listVoicesRemote(ctx);
     }
@@ -74,6 +75,7 @@ export async function genVoice(input, ctxIn) {
     const ctx = await resolveHttpContext(ctxIn.skillName, {
         apiBaseUrl,
         privateToken: input.priv_token,
+        preflightToken: ctxIn.auth?.token,
     });
     emitProgress({ phase: 'gen-voice:request', voiceId, speed });
     const data = await mmPost(ctx, '/tool/tts', { provider: voice.provider, text, voiceSetting: { voiceId, speed }, outputFormat: 'url' }, { timeoutMs: 120_000 });

package/dist/handlers/index.d.ts

@@ -4,10 +4,17 @@
  * Only `entry.type` in ('http' | 'builtin') uses this registry; python
  * skills go through spawn() in runner.ts and bypass handlers entirely.
  */
+import type { AuthPreflight } from '../auth/ensure.js';
 export type HandlerInput = Record<string, unknown>;
 export interface HandlerContext {
     /** ISO-style skill name from the registry (e.g. `gen-image`). Used for x-invoke-skill. */
     skillName: string;
+    /**
+     * Credential resolved by the dispatcher's preflight (runner.ts). Handlers pass
+     * `auth.token` into resolveHttpContext so the device flow can't run twice for
+     * a single invocation.
+     */
+    auth?: AuthPreflight;
 }
 export type SkillHandler = (input: HandlerInput, ctx: HandlerContext) => Promise<void>;
 export declare const HANDLERS: Record<string, SkillHandler>;

package/dist/http.d.ts

@@ -15,13 +15,19 @@
  * Base URL resolution:
  *   1. opts.apiBaseUrl                  — caller override
  *   2. process.env.MM_API_BASE_URL      — process env (point at local/staging here)
- *   3. https://api.remixmate.com/api    — production default (zero-config)
+ *   3. process.env.MM_BACKEND_API_URL   — ab-agent's convention (back-compat)
+ *   4. https://api.remixmate.com/api    — production default (zero-config)
+ */
+import { type Billing } from './billing.js';
+export { SkillError, EXIT } from './errors.js';
+/**
+ * Resolve the ab-api base URL the same way for authenticated and device-flow calls.
+ *
+ * `MM_BACKEND_API_URL` is honored because several Python skills already fall back
+ * to it (registry_loader, render_job_client, _vod_polling). Since runner.ts now
+ * injects the resolved base URL into those child processes, leaving it out here
+ * would let a prod default silently override an ab-agent-injected backend.
  */
-export declare class SkillError extends Error {
-    readonly exitCode: number;
-    constructor(message: string, exitCode?: number);
-}
-/** Resolve the ab-api base URL the same way for authenticated and device-flow calls. */
 export declare function resolveApiBaseUrl(flag?: string): string;
 export interface HttpContext {
     apiBaseUrl: string;
@@ -33,11 +39,19 @@ export interface HttpContext {
 export declare function resolveHttpContext(skillName: string, opts?: {
     apiBaseUrl?: string;
     privateToken?: string;
+    /**
+     * Token already resolved by the dispatcher's auth preflight (runner.ts).
+     * Reusing it avoids a second credential-store read — and, more importantly,
+     * a second device-flow attempt — per skill invocation.
+     */
+    preflightToken?: string;
 }): Promise<HttpContext>;
 export interface MmResponse<T = unknown> {
     code: number;
     msg?: string;
     data?: T;
+    /** Present only on responses that charged credits — see billing.ts. */
+    billing?: Billing;
 }
 /**
  * POST JSON to ab-api and return the parsed business payload.

package/dist/http.js

@@ -15,26 +15,37 @@
  * Base URL resolution:
  *   1. opts.apiBaseUrl                  — caller override
  *   2. process.env.MM_API_BASE_URL      — process env (point at local/staging here)
- *   3. https://api.remixmate.com/api    — production default (zero-config)
+ *   3. process.env.MM_BACKEND_API_URL   — ab-agent's convention (back-compat)
+ *   4. https://api.remixmate.com/api    — production default (zero-config)
  */
+import { recordBilling } from './billing.js';
 import { resolvePrivToken, NOT_AUTHENTICATED_HINT } from './auth/resolve.js';
 import { attemptAutoLogin } from './auth/auto-login.js';
+import { EXIT, SkillError } from './errors.js';
 const DEFAULT_API_BASE_URL = 'https://api.remixmate.com/api';
-export class SkillError extends Error {
-    exitCode;
-    constructor(message, exitCode = 1) {
-        super(message);
-        this.exitCode = exitCode;
-        this.name = 'SkillError';
-    }
-}
-/** Resolve the ab-api base URL the same way for authenticated and device-flow calls. */
+// Re-exported so the many `import { SkillError } from '../http.js'` call sites
+// stay valid; the definition moved to errors.ts to break an import cycle with
+// the auth gateway (see errors.ts).
+export { SkillError, EXIT } from './errors.js';
+/**
+ * Resolve the ab-api base URL the same way for authenticated and device-flow calls.
+ *
+ * `MM_BACKEND_API_URL` is honored because several Python skills already fall back
+ * to it (registry_loader, render_job_client, _vod_polling). Since runner.ts now
+ * injects the resolved base URL into those child processes, leaving it out here
+ * would let a prod default silently override an ab-agent-injected backend.
+ */
 export function resolveApiBaseUrl(flag) {
-    return (flag ?? process.env.MM_API_BASE_URL ?? DEFAULT_API_BASE_URL).replace(/\/+$/, '');
+    const fromEnv = (process.env.MM_API_BASE_URL ?? '').trim() || (process.env.MM_BACKEND_API_URL ?? '').trim();
+    return ((flag ?? '').trim() || fromEnv || DEFAULT_API_BASE_URL).replace(/\/+$/, '');
 }
 export async function resolveHttpContext(skillName, opts = {}) {
     const apiBaseUrl = resolveApiBaseUrl(opts.apiBaseUrl);
-    let resolved = await resolvePrivToken({ flag: opts.privateToken, apiBaseUrl });
+    // An explicit --token flag still wins over the preflight result.
+    let resolved = await resolvePrivToken({
+        flag: opts.privateToken ?? opts.preflightToken,
+        apiBaseUrl,
+    });
     // Only when flag/env/store are all empty do we try automatic browser auth.
     // attemptAutoLogin self-gates (cloud env / headless / disabled → returns null
     // immediately), so the env-injected path never reaches it (zero regression).
@@ -42,7 +53,7 @@ export async function resolveHttpContext(skillName, opts = {}) {
         resolved = await attemptAutoLogin(apiBaseUrl);
     }
     if (!resolved) {
-        throw new SkillError(NOT_AUTHENTICATED_HINT);
+        throw new SkillError(NOT_AUTHENTICATED_HINT, EXIT.NOT_AUTHENTICATED);
     }
     return {
         apiBaseUrl,
@@ -83,15 +94,24 @@ export async function mmPost(ctx, pathOrUrl, body, opts = {}) {
     }
     catch (err) {
         if (err instanceof Error && err.name === 'AbortError') {
-            throw new SkillError(`❌ request timed out: ${url}`);
+            throw new SkillError(`❌ request timed out: ${url}`, EXIT.BACKEND_UNREACHABLE);
         }
-        throw new SkillError(`❌ network error: ${err.message}`);
+        throw new SkillError(`❌ network error: ${err.message}`, EXIT.BACKEND_UNREACHABLE);
     }
     finally {
         clearTimeout(timeout);
     }
     const text = await resp.text();
     if (!resp.ok) {
+        // 401/403 is not a generic API failure — it means the credential is missing,
+        // expired or revoked. Surfacing it as such (with exit code 4) is what lets a
+        // host offer to re-authorize instead of reporting an opaque backend error.
+        if (resp.status === 401 || resp.status === 403) {
+            throw new SkillError(`${NOT_AUTHENTICATED_HINT}\n   （后端返回 HTTP ${resp.status}）`, EXIT.NOT_AUTHENTICATED);
+        }
+        if (resp.status >= 500) {
+            throw new SkillError(`❌ API request failed (HTTP ${resp.status}): ${text}`, EXIT.BACKEND_UNREACHABLE);
+        }
         throw new SkillError(`❌ API request failed (HTTP ${resp.status}): ${text}`);
     }
     let parsed;
@@ -101,7 +121,15 @@ export async function mmPost(ctx, pathOrUrl, body, opts = {}) {
     catch {
         throw new SkillError(`❌ failed to parse response, body is not JSON: ${text.slice(0, 200)}`);
     }
+    // Before the code check: a charged response is always code=0 today, but a
+    // partial-failure envelope that still billed must not lose its billing line.
+    recordBilling(parsed.billing);
     if (parsed.code !== 0) {
+        // ab-api reports auth failures in the envelope (HTTP 200 + code=401), so the
+        // business-code path needs the same 401 → "re-authorize" mapping as above.
+        if (parsed.code === 401 || parsed.code === 403) {
+            throw new SkillError(`${NOT_AUTHENTICATED_HINT}\n   （后端返回 code=${parsed.code}${parsed.msg ? `: ${parsed.msg}` : ''}）`, EXIT.NOT_AUTHENTICATED);
+        }
         throw new SkillError(`❌ API returned a business error: ${parsed.msg ?? 'unknown error'} (code=${parsed.code})`);
     }
     return parsed.data ?? undefined;

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.13",
-  "generatedAt": "2026-08-12T07:37:17.101Z",
+  "version": "0.9.15",
+  "generatedAt": "2026-08-14T08:23:17.130Z",
   "skills": [
     {
       "id": "export-jianying",

package/dist/registry.d.ts

@@ -5,15 +5,17 @@
  * the build-time manifest generator and smoke test). A record that fails
  * validation is skipped with a warning rather than crashing the whole CLI.
  */
-import { type SkillEntry } from './skill-schema.js';
+import { type SkillAuthMode, type SkillEntry } from './skill-schema.js';
 export declare const SKILLS_DIR: string;
-export type { SkillEntry } from './skill-schema.js';
+export type { SkillEntry, SkillAuthMode } from './skill-schema.js';
 export interface SkillDef {
     name: string;
     toolName: string;
     description: string;
     parameters: Record<string, unknown>;
     entry: SkillEntry;
+    /** Authorization requirement enforced by the dispatcher before invocation. */
+    auth: SkillAuthMode;
     skillDir: string;
     /** Absolute path to the python entry script (only when entry.type === 'python'). */
     scriptAbsolutePath?: string;

package/dist/registry.js

@@ -8,7 +8,7 @@
 import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { normalizeEntry, validateSkillJson, } from './skill-schema.js';
+import { normalizeEntry, resolveAuthMode, validateSkillJson, } from './skill-schema.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export const SKILLS_DIR = path.resolve(__dirname, '..', 'skills');
 function loadOne(skillDir) {
@@ -37,6 +37,7 @@ function loadOne(skillDir) {
         description: raw.description,
         parameters: raw.parameters ?? {},
         entry,
+        auth: resolveAuthMode(raw),
         skillDir,
     };
     if (entry.type === 'python') {

package/dist/runner.d.ts

@@ -3,6 +3,10 @@
  *   - spawn `python3 <scriptAbsolutePath> --flag value ...` (entry.type === 'python')
  *   - call a TS handler from handlers/ (entry.type === 'http' | 'builtin')
  *
+ * Authorization happens HERE, once, before either path — see auth/ensure.ts for
+ * why. Python children receive the resolved credential through their environment
+ * and never read the credential store themselves.
+ *
  * Resolves to the child process's exit code so cli.ts can propagate it.
  */
 import type { ParsedArgs } from './argv.js';

package/dist/runner.js

@@ -3,26 +3,44 @@
  *   - spawn `python3 <scriptAbsolutePath> --flag value ...` (entry.type === 'python')
  *   - call a TS handler from handlers/ (entry.type === 'http' | 'builtin')
  *
+ * Authorization happens HERE, once, before either path — see auth/ensure.ts for
+ * why. Python children receive the resolved credential through their environment
+ * and never read the credential store themselves.
+ *
  * Resolves to the child process's exit code so cli.ts can propagate it.
  */
 import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { findSkill, SKILLS_DIR } from './registry.js';
 import { HANDLERS } from './handlers/index.js';
-import { SkillError } from './http.js';
+import { EXIT, SkillError } from './errors.js';
+import { authChildEnv, ensureAuth } from './auth/ensure.js';
+import { emitBillingFooter } from './billing.js';
+/** Read the token override accepted by both the TS handlers and the Python skills. */
+function tokenFlag(args) {
+    const value = args.token ?? args.priv_token;
+    return typeof value === 'string' ? value : undefined;
+}
 export async function runSkill(skillName, opts) {
     const skill = findSkill(skillName, opts.baseDir ?? SKILLS_DIR);
     if (!skill) {
         process.stderr.write(`❌ skill not found: ${skillName}\n`);
-        return 2;
+        return EXIT.USAGE;
     }
     try {
+        const auth = await ensureAuth({
+            mode: skill.auth,
+            apiBaseUrl: typeof opts.parsedArgs.api_base_url === 'string' ? opts.parsedArgs.api_base_url : undefined,
+            flagToken: tokenFlag(opts.parsedArgs),
+        });
         switch (skill.entry.type) {
             case 'python':
-                return await runPython(skill, opts.rawArgs);
+                // Python children talk to ab-api themselves and print their own billing
+                // footer; nothing was charged through this process.
+                return await runPython(skill, opts.rawArgs, auth);
             case 'http':
             case 'builtin':
-                return await runHandler(skill, opts.parsedArgs);
+                return await runHandler(skill, opts.parsedArgs, auth);
         }
     }
     catch (err) {
@@ -31,10 +49,16 @@ export async function runSkill(skillName, opts) {
             return err.exitCode;
         }
         process.stderr.write(`❌ unexpected error: ${err.message}\n`);
-        return 1;
+        return EXIT.ERROR;
+    }
+    finally {
+        // In `finally` because a run can fail *after* a billed step (e.g. the image
+        // generated and was charged, then the upload timed out) — spend gets
+        // reported either way. No-ops when nothing was charged.
+        emitBillingFooter();
     }
 }
-async function runPython(skill, rawArgs) {
+async function runPython(skill, rawArgs, auth) {
     if (!skill.scriptAbsolutePath) {
         throw new SkillError(`skill ${skill.name} has entry.type=python but no scriptAbsolutePath`);
     }
@@ -43,21 +67,21 @@ async function runPython(skill, rawArgs) {
         const proc = spawn('python3', [skill.scriptAbsolutePath, ...rawArgs], {
             cwd,
             stdio: 'inherit',
-            env: { ...process.env, PYTHONUNBUFFERED: '1' },
+            env: { ...process.env, ...authChildEnv(auth), PYTHONUNBUFFERED: '1' },
         });
-        proc.on('exit', (code) => resolve(code ?? 1));
+        proc.on('exit', (code) => resolve(code ?? EXIT.ERROR));
         proc.on('error', (err) => {
             process.stderr.write(`❌ failed to spawn python3: ${err.message}\n`);
-            resolve(127);
+            resolve(EXIT.SPAWN_FAILED);
         });
     });
 }
-async function runHandler(skill, args) {
+async function runHandler(skill, args, auth) {
     const handlerKey = skill.entry.handler;
     const handler = HANDLERS[handlerKey];
     if (!handler) {
         throw new SkillError(`handler not registered: ${handlerKey} (skill ${skill.name})`);
     }
-    await handler(args, { skillName: skill.name });
-    return 0;
+    await handler(args, { skillName: skill.name, auth });
+    return EXIT.OK;
 }

package/dist/skill-schema.d.ts

@@ -38,6 +38,14 @@ export type SkillEntry = {
  */
 export type SkillCategory = 'authoring' | 'consuming' | 'asset' | 'meta';
 export declare const CATEGORY_VALUES: readonly ["authoring", "consuming", "asset", "meta"];
+/**
+ * Authorization requirement — consumed by the dispatcher's auth preflight.
+ * Semantics are documented on `AuthMode` in src/auth/ensure.ts (kept there so
+ * the runtime behavior and its description live together); this file only owns
+ * the literal values and their validation.
+ */
+export type SkillAuthMode = 'required' | 'optional' | 'none';
+export declare const AUTH_VALUES: readonly ["required", "optional", "none"];
 export interface RawSkillJson {
     name: string;
     toolName: string;
@@ -45,11 +53,22 @@ export interface RawSkillJson {
     title?: string;
     tier?: string;
     category?: SkillCategory;
+    auth?: SkillAuthMode;
     parameters?: Record<string, unknown>;
     scriptPath?: string;
     entry?: SkillEntry;
     envVars?: string[];
 }
+/**
+ * Resolve a skill's auth mode, defaulting for records that predate the field.
+ *
+ * The default is derived from `envVars` rather than hardcoded to `'required'`:
+ * a skill that never declared PRIV_TOKEN cannot possibly need a credential, and
+ * defaulting it to `required` would make a purely local skill (web-screenshot)
+ * pop a browser. Every skill shipped in this package declares `auth` explicitly,
+ * so this only covers externally supplied skill dirs (SKILL_BASE_DIR).
+ */
+export declare function resolveAuthMode(raw: Pick<RawSkillJson, 'auth' | 'envVars'>): SkillAuthMode;
 export declare const TIER_VALUES: readonly ["atomic", "orchestration", "tool"];
 export declare const REQUIRED_SKILL_JSON_FIELDS: readonly ["name", "tier", "title", "description"];
 /**

package/dist/skill-schema.js

@@ -12,6 +12,21 @@
  * the build treats them as fatal.
  */
 export const CATEGORY_VALUES = ['authoring', 'consuming', 'asset', 'meta'];
+export const AUTH_VALUES = ['required', 'optional', 'none'];
+/**
+ * Resolve a skill's auth mode, defaulting for records that predate the field.
+ *
+ * The default is derived from `envVars` rather than hardcoded to `'required'`:
+ * a skill that never declared PRIV_TOKEN cannot possibly need a credential, and
+ * defaulting it to `required` would make a purely local skill (web-screenshot)
+ * pop a browser. Every skill shipped in this package declares `auth` explicitly,
+ * so this only covers externally supplied skill dirs (SKILL_BASE_DIR).
+ */
+export function resolveAuthMode(raw) {
+    if (raw.auth)
+        return raw.auth;
+    return raw.envVars?.includes('PRIV_TOKEN') ? 'required' : 'none';
+}
 export const TIER_VALUES = ['atomic', 'orchestration', 'tool'];
 export const REQUIRED_SKILL_JSON_FIELDS = ['name', 'tier', 'title', 'description'];
 /**
@@ -43,6 +58,9 @@ export function validateSkillJson(raw, skillId) {
     if (raw.category != null && !CATEGORY_VALUES.includes(raw.category)) {
         errors.push(`skill.json.category must be one of ${CATEGORY_VALUES.join(' | ')}, got '${raw.category}'`);
     }
+    if (raw.auth != null && !AUTH_VALUES.includes(raw.auth)) {
+        errors.push(`skill.json.auth must be one of ${AUTH_VALUES.join(' | ')}, got '${raw.auth}'`);
+    }
     if (raw.name && raw.name !== skillId) {
         errors.push(`skill.json.name='${raw.name}' does not match directory name '${skillId}'`);
     }

package/dist/text.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Terminal text helpers shared by the human-facing commands.
+ */
+/**
+ * Pad to a target terminal width. CJK characters occupy two columns but count as
+ * one code unit, so String.padEnd misaligns any column that contains them.
+ */
+export declare function padDisplay(text: string, width: number): string;

package/dist/text.js

@@ -0,0 +1,15 @@
+/**
+ * Terminal text helpers shared by the human-facing commands.
+ */
+// Ranges covering the CJK / fullwidth blocks the CLI's Chinese output uses.
+const WIDE = /[ᄀ-ᅟ⺀-䳿一-鿿가-힣豈-﫿︰-﹏＀-｠￠-￦]/;
+/**
+ * Pad to a target terminal width. CJK characters occupy two columns but count as
+ * one code unit, so String.padEnd misaligns any column that contains them.
+ */
+export function padDisplay(text, width) {
+    let cols = 0;
+    for (const ch of text)
+        cols += WIDE.test(ch) ? 2 : 1;
+    return text + ' '.repeat(Math.max(1, width - cols));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.13",
+  "version": "0.9.15",
   "description": "AI media generation skills for Claude Code / Codex — 12 skills covering image, video, voice, digital human, web screenshot, web recording, script, template registry, rendering, Jianying export, and video deconstruction.",
   "type": "module",
   "main": "dist/index.js",
@@ -21,7 +21,7 @@
     "smoke": "node scripts/smoke.mjs",
     "test:cli": "npm run build && node --test test/*.test.mjs",
     "test:validators": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-validators.py",
-    "test:template-pipeline": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-template-pipeline.py",
+    "test:template-pipeline": "PYTHONDONTWRITEBYTECODE=1 node dist/cli.js exec -- python3 scripts/test-template-pipeline.py",
     "test:props-contract": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-props-contract.py",
     "test:render-plan": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-plan-snapshot.py",
     "test:render-plan:update": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-plan-snapshot.py --update",

package/skills/export-jianying/skill.json

@@ -5,6 +5,7 @@
   "category": "consuming",
   "title": "Jianying (CapCut) Draft Export",
   "description": "Jianying (CapCut) draft export: package asset URLs into a draft ZIP that Jianying can import. Supports automatic conversion from a RenderPlan.",
+  "auth": "required",
   "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "AGENT_NAME"],
   "scriptPath": "scripts/gen_jianying_draft.py",
   "parameters": {

package/skills/gen-digital-human/SKILL.md

@@ -175,6 +175,18 @@ remixmate gen-digital-human --check-status --generation-id 123
 - Keep individual jobs under ~500 characters.
 - Tone and style of the script affect the perceived voice.
 
+## Credits
+
+Every run charges credits. The CLI prints a footer on stdout when it does:
+
+```
+💳 Charged 31 credits · balance 1,240
+```
+
+Relay it to the user whenever it appears — it is the only signal they get about what a
+generation cost, and the balance is the only warning before a run fails with
+`insufficient_credits`. Do not drop it from your summary.
+
 ## Error handling
 
 - **401** / **token missing** (non-OpenClaw): set `PRIV_TOKEN`.