@vivipilot/cli 0.1.0

package/src/config.ts

@@ -0,0 +1,71 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const DEFAULT_API_URL = "https://vivipilot.com";
+
+export type CliConfig = {
+  apiUrl?: string;
+  apiKey?: string;
+  publicKeys?: Record<string, string>;
+};
+
+export type Env = Record<string, string | undefined>;
+
+function configRoot(env: Env): string {
+  if (env.XDG_CONFIG_HOME) return env.XDG_CONFIG_HOME;
+  if (env.APPDATA) return env.APPDATA;
+  return join(homedir(), ".config");
+}
+
+export function defaultConfigPath(env: Env = process.env): string {
+  return env.VIVIPILOT_CONFIG ?? join(configRoot(env), "vivipilot", "config.json");
+}
+
+function isNotFound(error: unknown): boolean {
+  return typeof error === "object"
+    && error !== null
+    && "code" in error
+    && (error as { code?: string }).code === "ENOENT";
+}
+
+export async function readConfig(path = defaultConfigPath()): Promise<CliConfig> {
+  try {
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as CliConfig : {};
+  } catch (error) {
+    if (isNotFound(error)) return {};
+    throw error;
+  }
+}
+
+export async function writeConfig(config: CliConfig, path = defaultConfigPath()): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+}
+
+export async function deleteConfig(path = defaultConfigPath()): Promise<void> {
+  await rm(path, { force: true });
+}
+
+export function resolveApiUrl(config: CliConfig, env: Env = process.env): string {
+  return (env.VIVIPILOT_API_URL ?? config.apiUrl ?? DEFAULT_API_URL).replace(/\/+$/, "");
+}
+
+export function resolveApiKey(config: CliConfig, env: Env = process.env): string | undefined {
+  const key = env.VIVIPILOT_API_KEY ?? config.apiKey;
+  return key && key.trim().length > 0 ? key.trim() : undefined;
+}
+
+export function resolvePublicKeys(config: CliConfig, env: Env = process.env): Record<string, string> {
+  if (env.VIVIPILOT_MANIFEST_PUBLIC_KEYS) {
+    const parsed = JSON.parse(env.VIVIPILOT_MANIFEST_PUBLIC_KEYS) as unknown;
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed as Record<string, string>;
+  }
+  if (env.VIVIPILOT_MANIFEST_PUBLIC_KEY_ID && env.VIVIPILOT_MANIFEST_PUBLIC_KEY) {
+    return { [env.VIVIPILOT_MANIFEST_PUBLIC_KEY_ID]: env.VIVIPILOT_MANIFEST_PUBLIC_KEY };
+  }
+  return config.publicKeys ?? {};
+}
+

package/src/errors.ts

@@ -0,0 +1,14 @@
+export class CliError extends Error {
+  readonly exitCode: number;
+
+  constructor(message: string, exitCode = 1) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+}
+
+export function isCliError(error: unknown): error is CliError {
+  return error instanceof CliError;
+}
+

package/src/index.ts

@@ -0,0 +1,25 @@
+export { parseArgv, flagBoolean, flagNumber, flagString, type ParsedArgs } from "./args.js";
+export {
+  DEFAULT_API_URL,
+  defaultConfigPath,
+  deleteConfig,
+  readConfig,
+  resolveApiKey,
+  resolveApiUrl,
+  resolvePublicKeys,
+  writeConfig,
+  type CliConfig,
+  type Env,
+} from "./config.js";
+export {
+  VivipilotApiClient,
+  type BalanceResponse,
+  type EstimateRequest,
+  type EstimateResponse,
+  type GenerateRequest,
+  type GenerateResponse,
+  type StatusResponse,
+} from "./api.js";
+export { readManifestFile, verifyManifestFile } from "./manifest.js";
+export { startMcpServer, type McpServerOptions } from "./mcp.js";
+export { CliError, isCliError } from "./errors.js";

package/src/manifest.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import { bytesToBase64Url, signRenderManifest, type UnsignedVivipilotRenderManifestV1 } from "@vivipilot/render-manifest";
+import { checkRenderEntitlement, assertNotRevoked } from "./manifest.js";
+
+async function createTestKeyPair() {
+  const keyPair = await crypto.subtle.generateKey(
+    { name: "Ed25519" },
+    true,
+    ["sign", "verify"],
+  ) as CryptoKeyPair;
+  return {
+    publicKey: bytesToBase64Url(new Uint8Array(await crypto.subtle.exportKey("raw", keyPair.publicKey))),
+    privateKey: bytesToBase64Url(new Uint8Array(await crypto.subtle.exportKey("pkcs8", keyPair.privateKey))),
+  };
+}
+
+function baseManifest(entitlement: UnsignedVivipilotRenderManifestV1["entitlement"]): UnsignedVivipilotRenderManifestV1 {
+  return {
+    schema: "vivipilot.renderManifest.v1",
+    manifestId: "manifest_123",
+    generationId: "gen_123",
+    userId: "user_123",
+    createdAt: "2026-06-27T10:00:00.000Z",
+    engineVersion: "vivipilot-renderer@0.1.0",
+    entitlement,
+    billing: {
+      creditTransactionId: "txn_123",
+      creditsCharged: 40,
+      idempotencyKey: "idem_123",
+      creditSource: "paid_topup",
+    },
+    render: {
+      engine: "pixi-dw-scene-v1",
+      canvas: { width: 1280, height: 720, fps: 30 },
+      durationFrames: 120,
+      overlays: [],
+    },
+    integrity: {
+      canonicalPayloadHash: "",
+      sceneHash: "b".repeat(64),
+    },
+  };
+}
+
+describe("checkRenderEntitlement", () => {
+  it("allows render within entitlement", async () => {
+    const keys = await createTestKeyPair();
+    const signed = await signRenderManifest(baseManifest({
+      maxResolution: "1080p",
+      watermark: false,
+      commercialUse: true,
+      allowedFormats: ["mp4", "webm"],
+    }), { keyId: "test", privateKey: keys.privateKey });
+
+    const result = checkRenderEntitlement(signed, { format: "mp4", height: 1080 });
+    expect(result.ok).toBe(true);
+  });
+
+  it("rejects render exceeding max resolution", async () => {
+    const keys = await createTestKeyPair();
+    const signed = await signRenderManifest(baseManifest({
+      maxResolution: "720p",
+      watermark: false,
+      commercialUse: true,
+      allowedFormats: ["mp4", "webm"],
+    }), { keyId: "test", privateKey: keys.privateKey });
+
+    const result = checkRenderEntitlement(signed, { height: 1080 });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe("resolution_exceeds_entitlement");
+  });
+
+  it("rejects render with disallowed format", async () => {
+    const keys = await createTestKeyPair();
+    const signed = await signRenderManifest(baseManifest({
+      maxResolution: "1080p",
+      watermark: false,
+      commercialUse: true,
+      allowedFormats: ["mp4", "webm"],
+    }), { keyId: "test", privateKey: keys.privateKey });
+
+    const result = checkRenderEntitlement(signed, { format: "gif" });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe("format_not_allowed");
+  });
+});
+
+describe("assertNotRevoked", () => {
+  it("does not throw when not checked (offline)", () => {
+    expect(() => assertNotRevoked({ revoked: false, checked: false })).not.toThrow();
+    expect(() => assertNotRevoked({ revoked: false, checked: false, error: "http_500" })).not.toThrow();
+  });
+
+  it("does not throw when checked and not revoked", () => {
+    expect(() => assertNotRevoked({ revoked: false, checked: true, revokedAt: null })).not.toThrow();
+  });
+
+  it("throws when checked and revoked", () => {
+    expect(() => assertNotRevoked({ revoked: true, checked: true, revokedAt: 1234 })).toThrow(/revoked/);
+  });
+
+  it("does not throw when revoked but not checked (network failure)", () => {
+    expect(() => assertNotRevoked({ revoked: true, checked: false, error: "timeout" })).not.toThrow();
+  });
+});

package/src/manifest.ts

@@ -0,0 +1,126 @@
+import { readFile } from "node:fs/promises";
+import {
+  verifyRenderManifest,
+  type RenderManifestResolution,
+  type RenderManifestVerificationResult,
+  type VivipilotRenderManifestV1,
+} from "@vivipilot/render-manifest";
+import { type CliConfig, type Env, resolveApiUrl, resolveApiKey, resolvePublicKeys } from "./config.js";
+import { CliError } from "./errors.js";
+
+export async function readManifestFile(path: string): Promise<unknown> {
+  return JSON.parse(await readFile(path, "utf8")) as unknown;
+}
+
+export async function verifyManifestFile(path: string, config: CliConfig, env: Env = process.env): Promise<RenderManifestVerificationResult> {
+  const manifest = await readManifestFile(path);
+  return verifyRenderManifest(manifest, {
+    publicKeys: resolvePublicKeys(config, env),
+  });
+}
+
+/**
+ * Best-effort online revocation check. Calls
+ * `GET /api/v1/manifests/{manifestId}/revocation`. Returns `revoked: false`
+ * when the network is unavailable or the endpoint errors — the offline
+ * cryptographic signature verification remains authoritative.
+ *
+ * Pass `apiKey` to authenticate the request. When no key is configured the
+ * check is skipped (offline mode).
+ */
+export async function checkManifestRevocationOnline(
+  manifest: VivipilotRenderManifestV1,
+  config: CliConfig,
+  env: Env = process.env,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ revoked: boolean; revokedAt: number | null; checked: boolean; error?: string }> {
+  const apiKey = resolveApiKey(config, env);
+  if (!apiKey) return { revoked: false, revokedAt: null, checked: false, error: "no_api_key" };
+
+  const apiUrl = resolveApiUrl(config, env);
+  const url = `${apiUrl}/api/v1/manifests/${encodeURIComponent(manifest.manifestId)}/revocation`;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 5_000);
+  try {
+    const response = await fetchImpl(url, {
+      headers: { authorization: `Bearer ${apiKey}` },
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      return { revoked: false, revokedAt: null, checked: false, error: `http_${response.status}` };
+    }
+    const payload = await response.json() as { revoked?: boolean; revokedAt?: number | null };
+    return {
+      revoked: payload.revoked === true,
+      revokedAt: payload.revokedAt ?? null,
+      checked: true,
+    };
+  } catch (error) {
+    return {
+      revoked: false,
+      revokedAt: null,
+      checked: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function assertNotRevoked(result: { revoked: boolean; checked: boolean; revokedAt?: number | null; error?: string }): void {
+  if (result.checked && result.revoked) {
+    throw new CliError(`Manifest has been revoked server-side${result.revokedAt ? ` at ${new Date(result.revokedAt).toISOString()}` : ""}. Generate a new manifest with \`vivipilot generate\`.`, 1);
+  }
+}
+
+const RESOLUTION_HEIGHT_CEILINGS: Record<RenderManifestResolution, number> = {
+  "720p": 720,
+  "1080p": 1080,
+  "2k": 1440,
+  "4k": 2160,
+};
+
+export type RenderEntitlementRequest = {
+  format?: "mp4" | "webm" | "gif" | "mov";
+  width?: number;
+  height?: number;
+};
+
+export type RenderEntitlementViolation = {
+  ok: false;
+  reason: "resolution_exceeds_entitlement" | "format_not_allowed";
+  message: string;
+};
+
+export type RenderEntitlementResult =
+  | { ok: true }
+  | RenderEntitlementViolation;
+
+export function checkRenderEntitlement(
+  manifest: VivipilotRenderManifestV1,
+  request: RenderEntitlementRequest,
+): RenderEntitlementResult {
+  const maxCeiling = RESOLUTION_HEIGHT_CEILINGS[manifest.entitlement.maxResolution];
+  const requestedHeight = request.height ?? manifest.render.canvas.height;
+  if (requestedHeight > maxCeiling) {
+    return {
+      ok: false,
+      reason: "resolution_exceeds_entitlement",
+      message: `Requested height ${requestedHeight}px exceeds the manifest entitlement (${manifest.entitlement.maxResolution}, max ${maxCeiling}px). Top up or generate a higher-entitlement manifest.`,
+    };
+  }
+
+  if (request.format && Array.isArray(manifest.entitlement.allowedFormats) && manifest.entitlement.allowedFormats.length > 0) {
+    if (!manifest.entitlement.allowedFormats.includes(request.format)) {
+      return {
+        ok: false,
+        reason: "format_not_allowed",
+        message: `Format ${request.format} is not allowed by this manifest entitlement. Allowed: ${manifest.entitlement.allowedFormats.join(", ")}.`,
+      };
+    }
+  }
+
+  return { ok: true };
+}
+
+

package/src/mcp.test.ts

@@ -0,0 +1,48 @@
+import { PassThrough } from "node:stream";
+import { describe, expect, it } from "vitest";
+import { startMcpServer } from "./mcp.js";
+
+function jsonRpc(id: number, method: string, params?: unknown): string {
+  return `${JSON.stringify({ jsonrpc: "2.0", id, method, ...(params === undefined ? {} : { params }) })}\n`;
+}
+
+describe("mcp stdio server", () => {
+  it("responds to initialize and lists Vivipilot tools", async () => {
+    const stdin = new PassThrough();
+    const stdout = new PassThrough();
+    const stderr = new PassThrough();
+    const chunks: Buffer[] = [];
+    stdout.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+
+    const server = startMcpServer({
+      config: {},
+      env: {},
+      stdin,
+      stdout,
+      stderr,
+    });
+
+    stdin.write(jsonRpc(1, "initialize", { protocolVersion: "2025-06-18" }));
+    stdin.write(jsonRpc(2, "tools/list"));
+    stdin.end();
+    await server;
+
+    const responses = Buffer.concat(chunks)
+      .toString("utf8")
+      .trim()
+      .split("\n")
+      .map((line) => JSON.parse(line) as any);
+
+    expect(responses[0].id).toBe(1);
+    expect(responses[0].result.serverInfo.name).toBe("vivipilot");
+    expect(responses[1].id).toBe(2);
+    expect(responses[1].result.tools.map((tool: any) => tool.name)).toEqual([
+      "vivipilot_get_balance",
+      "vivipilot_estimate_motion_layout",
+      "vivipilot_generate_motion_layout",
+      "vivipilot_verify_manifest",
+      "vivipilot_render_video",
+      "vivipilot_get_generation_status",
+    ]);
+  });
+});