@mcut/cli 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,187 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the
+copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other
+entities that control, are controlled by, or are under common control with
+that entity. For the purposes of this definition, "control" means (i) the
+power, direct or indirect, to cause the direction or management of such
+entity, whether by contract or otherwise, or (ii) ownership of fifty percent
+(50%) or more of the outstanding shares, or (iii) beneficial ownership of
+such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation source, and
+configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation
+or translation of a Source form, including but not limited to compiled object
+code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work (an example is provided in the Appendix
+below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form,
+that is based on (or derived from) the Work and for which the editorial
+revisions, annotations, elaborations, or other modifications represent, as a
+whole, an original work of authorship. For the purposes of this License,
+Derivative Works shall not include works that remain separable from, or
+merely link (or bind by name) to the interfaces of, the Work and Derivative
+Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal
+Entity authorized to submit on behalf of the copyright owner. For the
+purposes of this definition, "submitted" means any form of electronic,
+verbal, or written communication sent to the Licensor or its representatives,
+including but not limited to communication on electronic mailing lists,
+source code control systems, and issue tracking systems that are managed by,
+or on behalf of, the Licensor for the purpose of discussing and improving the
+Work, but excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on
+behalf of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
+section) patent license to make, have made, use, offer to sell, sell, import,
+and otherwise transfer the Work, where such license applies only to those
+patent claims licensable by such Contributor that are necessarily infringed
+by their Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You institute
+patent litigation against any entity (including a cross-claim or counterclaim
+in a lawsuit) alleging that the Work or a Contribution incorporated within
+the Work constitutes direct or contributory patent infringement, then any
+patent licenses granted to You under this License for that Work shall
+terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a
+copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from
+the Source form of the Work, excluding those notices that do not pertain to
+any part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution,
+then any Derivative Works that You distribute must include a readable copy of
+the attribution notices contained within such NOTICE file, excluding those
+notices that do not pertain to any part of the Derivative Works, in at least
+one of the following places: within a NOTICE text file distributed as part of
+the Derivative Works; within the Source form or documentation, if provided
+along with the Derivative Works; or, within a display generated by the
+Derivative Works, if and wherever such third-party notices normally appear.
+The contents of the NOTICE file are for informational purposes only and do
+not modify the License. You may add Your own attribution notices within
+Derivative Works that You distribute, alongside or as an addendum to the
+NOTICE text from the Work, provided that such additional attribution notices
+cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may
+provide additional or different license terms and conditions for use,
+reproduction, or distribution of Your modifications, or for any such
+Derivative Works as a whole, provided Your use, reproduction, and
+distribution of the Work otherwise complies with the conditions stated in
+this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein
+shall supersede or modify the terms of any separate license agreement you may
+have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as
+required for reasonable and customary use in describing the origin of the
+Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to
+in writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any
+character arising as a result of this License or out of the use or inability
+to use the Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all other
+commercial damages or losses), even if such Contributor has been advised of
+the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work
+or Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree
+to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "[]" replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification
+within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,11 @@
+# @mcut/cli
+
+Headless command-line tools for mcut project documents.
+
+```sh
+bunx @mcut/cli --help
+```
+
+The CLI can scaffold, validate, summarize, lint, and batch-edit mcut project
+JSON files. Browser-only export remains in `@mcut/media`; this package focuses
+on project document operations that can run in Node-compatible environments.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/cli.js

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+import { a as PLATFORM_PRESETS, c as planSilenceCuts, i as writeProjectFile, l as lintProject, n as readTranscriptFile, o as getPlatformPreset, s as buildCaptionsCommand, t as readProjectFile } from "./io-BcGV4lKK.js";
+import { CommandError, EditorEngine, ProjectFormatError, createProject, listToolDefinitions, summarizeProject } from "@mcut/timeline";
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { parseArgs } from "node:util";
+//#region src/cli.ts
+/**
+* mcut on the command line. Every subcommand operates on a project document
+* (JSON) the way the editor does: parse → dispatch commands → persist. Export
+* stays in the browser (WebCodecs); this tool edits the document.
+*/
+const HELP = `mcut — headless tools for mcut project documents
+
+Usage:
+  mcut new [file] [--preset <id>] [--name <name>] [--force]
+  mcut validate <file> [--strict]
+  mcut summarize <file>
+  mcut apply <file> [commands.json] [--dry-run]      (or pipe commands on stdin)
+  mcut captions <file> --transcript <t.json> [--element <id>] [--style <id>]
+                [--max-chars <n>] [--replace] [--dry-run]
+  mcut silence-cuts <file> --transcript <t.json> --element <id>
+                [--min-gap <ms>] [--padding <ms>] [--keep-ends] [--dry-run]
+  mcut commands [--json] [--name <command>]
+  mcut presets [--json]
+
+Commands:
+  new            Scaffold a project document from a platform preset (default: youtube).
+  validate       Parse + lint a project; exits 1 on errors (--strict: warnings too).
+  summarize      Print the compact textual rendering of a project (read this before editing).
+  apply          Dispatch a JSON command batch (object or array) as one undo step, then save.
+  captions       Add captions from a transcript JSON ({ words: [{ text, startMs, endMs }] }).
+  silence-cuts   Cut transcript silence out of one element (splits + ripple deletes + edge trims).
+  commands       List every editing command; --name prints one command's JSON schema.
+  presets        List platform presets (dimensions, fps, safe areas).
+`;
+var CliError = class extends Error {};
+function fail(message) {
+	throw new CliError(message);
+}
+async function readStdin() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(chunk);
+	return Buffer.concat(chunks).toString("utf8");
+}
+function parseCommandBatch(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		fail("commands input is not valid JSON");
+	}
+	const list = Array.isArray(parsed) ? parsed : [parsed];
+	for (const item of list) if (typeof item !== "object" || item === null || typeof item.type !== "string") fail("each command must be an object with a string \"type\"");
+	return list;
+}
+async function cmdNew(argv) {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		allowPositionals: true,
+		options: {
+			preset: {
+				type: "string",
+				default: "youtube"
+			},
+			name: { type: "string" },
+			force: {
+				type: "boolean",
+				default: false
+			}
+		}
+	});
+	const file = positionals[0] ?? "project.mcut.json";
+	const preset = getPlatformPreset(values.preset);
+	if (!preset) fail(`unknown preset "${values.preset}" (known: ${PLATFORM_PRESETS.map((p) => p.id).join(", ")})`);
+	if (existsSync(file) && !values.force) fail(`${file} already exists (use --force to overwrite)`);
+	await writeProjectFile(file, createProject({
+		name: values.name ?? "Untitled",
+		width: preset.width,
+		height: preset.height,
+		fps: preset.fps
+	}));
+	console.log(`Created ${file} — ${preset.label}, ${preset.width}x${preset.height}@${preset.fps}`);
+}
+async function cmdValidate(argv) {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		allowPositionals: true,
+		options: { strict: {
+			type: "boolean",
+			default: false
+		} }
+	});
+	const file = positionals[0] ?? fail("validate needs a project file");
+	const issues = lintProject(await readProjectFile(file));
+	for (const issue of issues) console.log(`${issue.severity}[${issue.code}]: ${issue.message}`);
+	const errors = issues.filter((i) => i.severity === "error").length;
+	const warnings = issues.length - errors;
+	console.log(issues.length === 0 ? `OK: ${file} is valid` : `${file}: ${errors} error(s), ${warnings} warning(s)`);
+	if (errors > 0 || values.strict && warnings > 0) process.exitCode = 1;
+}
+async function cmdSummarize(argv) {
+	const { positionals } = parseArgs({
+		args: argv,
+		allowPositionals: true,
+		options: {}
+	});
+	const file = positionals[0] ?? fail("summarize needs a project file");
+	console.log(summarizeProject(await readProjectFile(file)));
+}
+async function cmdApply(argv) {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		allowPositionals: true,
+		options: { "dry-run": {
+			type: "boolean",
+			default: false
+		} }
+	});
+	const file = positionals[0] ?? fail("apply needs a project file");
+	const source = positionals[1];
+	const commands = parseCommandBatch(source && source !== "-" ? await readFile(source, "utf8") : await readStdin());
+	const engine = new EditorEngine({ project: await readProjectFile(file) });
+	engine.transact(() => {
+		for (const command of commands) engine.dispatch(command);
+	});
+	if (!values["dry-run"]) await writeProjectFile(file, engine.project);
+	console.log(`${values["dry-run"] ? "(dry run) " : ""}Applied ${commands.length} command(s) to ${file}\n`);
+	console.log(summarizeProject(engine.project));
+}
+async function cmdCaptions(argv) {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		allowPositionals: true,
+		options: {
+			transcript: { type: "string" },
+			element: { type: "string" },
+			style: { type: "string" },
+			"max-chars": { type: "string" },
+			replace: {
+				type: "boolean",
+				default: false
+			},
+			"dry-run": {
+				type: "boolean",
+				default: false
+			}
+		}
+	});
+	const file = positionals[0] ?? fail("captions needs a project file");
+	if (!values.transcript) fail("captions needs --transcript <file>");
+	const project = await readProjectFile(file);
+	const command = buildCaptionsCommand(project, await readTranscriptFile(values.transcript), {
+		...values.element ? { elementId: values.element } : {},
+		...values.style ? { styleId: values.style } : {},
+		...values["max-chars"] ? { maxChars: Number(values["max-chars"]) } : {},
+		replace: values.replace
+	});
+	if (values["dry-run"]) {
+		console.log(JSON.stringify(command, null, 2));
+		return;
+	}
+	const engine = new EditorEngine({ project });
+	engine.dispatch(command);
+	await writeProjectFile(file, engine.project);
+	const count = command.captions.length;
+	console.log(`Added ${count} caption(s) to ${file}\n`);
+	console.log(summarizeProject(engine.project));
+}
+async function cmdSilenceCuts(argv) {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		allowPositionals: true,
+		options: {
+			transcript: { type: "string" },
+			element: { type: "string" },
+			"min-gap": { type: "string" },
+			padding: { type: "string" },
+			"keep-ends": {
+				type: "boolean",
+				default: false
+			},
+			"dry-run": {
+				type: "boolean",
+				default: false
+			}
+		}
+	});
+	const file = positionals[0] ?? fail("silence-cuts needs a project file");
+	if (!values.transcript) fail("silence-cuts needs --transcript <file>");
+	if (!values.element) fail("silence-cuts needs --element <id>");
+	const project = await readProjectFile(file);
+	const transcript = await readTranscriptFile(values.transcript);
+	const plan = planSilenceCuts(project, values.element, transcript, {
+		...values["min-gap"] ? { minGapMs: Number(values["min-gap"]) } : {},
+		...values.padding ? { paddingMs: Number(values.padding) } : {},
+		trimEnds: !values["keep-ends"]
+	});
+	if (plan.silences.length === 0) {
+		console.log("No silences found — nothing to cut.");
+		return;
+	}
+	if (values["dry-run"]) {
+		console.log(JSON.stringify({
+			silences: plan.silences,
+			commands: plan.commands
+		}, null, 2));
+		return;
+	}
+	await writeProjectFile(file, plan.project);
+	console.log(`Cut ${plan.silences.length} silence(s), ${(plan.removedMs / 1e3).toFixed(2)}s removed\n`);
+	console.log(summarizeProject(plan.project));
+}
+async function cmdCommands(argv) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			json: {
+				type: "boolean",
+				default: false
+			},
+			name: { type: "string" }
+		}
+	});
+	const tools = listToolDefinitions();
+	if (values.name) {
+		const tool = tools.find((t) => t.name === values.name);
+		if (!tool) fail(`unknown command "${values.name}"`);
+		console.log(JSON.stringify(tool, null, 2));
+		return;
+	}
+	if (values.json) {
+		console.log(JSON.stringify(tools, null, 2));
+		return;
+	}
+	for (const tool of tools) console.log(`${tool.name} — ${tool.description}`);
+}
+async function cmdPresets(argv) {
+	const { values } = parseArgs({
+		args: argv,
+		options: { json: {
+			type: "boolean",
+			default: false
+		} }
+	});
+	if (values.json) {
+		console.log(JSON.stringify(PLATFORM_PRESETS, null, 2));
+		return;
+	}
+	for (const preset of PLATFORM_PRESETS) console.log(`${preset.id} — ${preset.label}, ${preset.width}x${preset.height}@${preset.fps}`);
+}
+async function main() {
+	const [command, ...rest] = process.argv.slice(2);
+	switch (command) {
+		case "new": return cmdNew(rest);
+		case "validate": return cmdValidate(rest);
+		case "summarize": return cmdSummarize(rest);
+		case "apply": return cmdApply(rest);
+		case "captions": return cmdCaptions(rest);
+		case "silence-cuts": return cmdSilenceCuts(rest);
+		case "commands": return cmdCommands(rest);
+		case "presets": return cmdPresets(rest);
+		case void 0:
+		case "help":
+		case "--help":
+		case "-h":
+			console.log(HELP);
+			return;
+		default: fail(`unknown command "${command}" — run \`mcut help\``);
+	}
+}
+main().catch((error) => {
+	if (error instanceof CommandError || error instanceof ProjectFormatError) console.error(`${error.name} (${error.code}): ${error.message}`);
+	else if (error instanceof CliError) console.error(`mcut: ${error.message}`);
+	else console.error(error instanceof Error ? error.message : String(error));
+	process.exitCode = 1;
+});
+//#endregion
+export {};

package/dist/index.d.ts

@@ -0,0 +1,128 @@
+import { AnyCommand, Project } from "@mcut/timeline";
+import { TranscriptResult } from "@mcut/transcription";
+import { z } from "zod";
+
+//#region src/lint.d.ts
+/**
+ * Things `parseProject` cannot reject (it validates shape, not cross-entity
+ * invariants) but that make a project render wrong or export badly. Commands
+ * maintain these invariants; hand-edited or generated JSON may not.
+ */
+interface LintIssue {
+  severity: 'error' | 'warning';
+  code: string;
+  message: string;
+}
+declare function lintProject(project: Project): LintIssue[];
+//#endregion
+//#region src/silence.d.ts
+interface SilenceCutOptions {
+  /** Word gaps shorter than this are speech rhythm, not silence. Default 600. */
+  minGapMs?: number;
+  /** Breathing room kept on each side of a cut. Default 120. */
+  paddingMs?: number;
+  /** Speech chunks shorter than this merge into the surrounding cut. Default 250. */
+  minKeepMs?: number;
+  /** Also cut silence before the first and after the last word. Default true. */
+  trimEnds?: boolean;
+}
+/** A window of source-media time (same clock as the transcript). */
+interface SilenceWindow {
+  startMs: number;
+  endMs: number;
+}
+interface SilenceCutPlan {
+  /** The cuts, in source-media time, padding already applied. */
+  silences: SilenceWindow[];
+  /** Every command dispatched, in order — replayable on the input project. */
+  commands: AnyCommand[];
+  removedMs: number;
+  /** The project with all cuts applied. */
+  project: Project;
+}
+/**
+ * Plan and apply silence cuts on one video/audio element from its transcript.
+ *
+ * Word timings are source-media times, so the element must play at 1x (no
+ * timeMap). Interior and leading silences become split + rippleDelete (later
+ * clips on the track shift left — cutting leading silence replaces the
+ * element id with a fresh one); trailing silence becomes a trim. Cuts are
+ * applied last-to-first so earlier timeline positions stay valid throughout.
+ */
+declare function planSilenceCuts(project: Project, elementId: string, transcript: TranscriptResult, options?: SilenceCutOptions): SilenceCutPlan;
+//#endregion
+//#region src/captions.d.ts
+interface CaptionsCommandOptions {
+  /**
+   * Scope the transcript to one video/audio element: caption only the source
+   * span the clip actually plays, positioned at the clip's timeline location.
+   * Without it the transcript is applied from timeline 0.
+   */
+  elementId?: string;
+  /** A preset id from CAPTION_STYLE_PRESETS (classic, karaoke, spotlight, ...). */
+  styleId?: string;
+  maxChars?: number;
+  maxGapMs?: number;
+  /** Clear existing captions on the target track first. */
+  replace?: boolean;
+}
+/**
+ * Build an `applyCaptions` command from a transcript, with element scoping
+ * and named style presets resolved. Dispatch the result (or hand it to an
+ * agent) — this does not mutate the project.
+ */
+declare function buildCaptionsCommand(project: Project, transcript: TranscriptResult, options?: CaptionsCommandOptions): AnyCommand;
+//#endregion
+//#region src/presets.d.ts
+/**
+ * Platform delivery presets: the project geometry an agent (or human) should
+ * start from for a given destination. Data, not code — the skill's
+ * `platform-presets.json` asset and `mcut new --preset` both read this list.
+ */
+interface PlatformPreset {
+  id: string;
+  label: string;
+  width: number;
+  height: number;
+  fps: number;
+  /**
+   * Fractions of frame height covered by platform chrome (usernames,
+   * captions UI, action rails). Keep text and faces out of these bands.
+   */
+  safeArea: {
+    top: number;
+    bottom: number;
+  };
+  notes: string;
+}
+declare const PLATFORM_PRESETS: PlatformPreset[];
+declare function getPlatformPreset(id: string): PlatformPreset | undefined;
+//#endregion
+//#region src/io.d.ts
+declare function readProjectFile(path: string): Promise<Project>;
+declare function writeProjectFile(path: string, project: Project): Promise<void>;
+/**
+ * Lenient validation for transcript JSON (providers normalize to
+ * TranscriptResult, but hand-made files often carry only `words`).
+ */
+declare const transcriptSchema: z.ZodObject<{
+  text: z.ZodDefault<z.ZodString>;
+  language: z.ZodOptional<z.ZodString>;
+  durationMs: z.ZodOptional<z.ZodNumber>;
+  words: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    text: z.ZodString;
+    startMs: z.ZodNumber;
+    endMs: z.ZodNumber;
+    confidence: z.ZodOptional<z.ZodNumber>;
+    speaker: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  segments: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    text: z.ZodString;
+    startMs: z.ZodNumber;
+    endMs: z.ZodNumber;
+    speaker: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+}, z.core.$strip>;
+declare function readTranscriptFile(path: string): Promise<TranscriptResult>;
+//#endregion
+export { type CaptionsCommandOptions, type LintIssue, PLATFORM_PRESETS, type PlatformPreset, type SilenceCutOptions, type SilenceCutPlan, type SilenceWindow, buildCaptionsCommand, getPlatformPreset, lintProject, planSilenceCuts, readProjectFile, readTranscriptFile, transcriptSchema, writeProjectFile };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as PLATFORM_PRESETS, c as planSilenceCuts, i as writeProjectFile, l as lintProject, n as readTranscriptFile, o as getPlatformPreset, r as transcriptSchema, s as buildCaptionsCommand, t as readProjectFile } from "./io-BcGV4lKK.js";
+export { PLATFORM_PRESETS, buildCaptionsCommand, getPlatformPreset, lintProject, planSilenceCuts, readProjectFile, readTranscriptFile, transcriptSchema, writeProjectFile };

package/dist/io-BcGV4lKK.js

@@ -0,0 +1,328 @@
+import { CAPTION_STYLE_PRESETS, EditorEngine, MIN_ELEMENT_DURATION_MS, createElementId, getElementLocation, getProjectDurationMs, parseProject } from "@mcut/timeline";
+import { buildApplyCaptionsCommand } from "@mcut/transcription";
+import { readFile, writeFile } from "node:fs/promises";
+import { z } from "zod";
+//#region src/lint.ts
+function lintProject(project) {
+	const issues = [];
+	const error = (code, message) => issues.push({
+		severity: "error",
+		code,
+		message
+	});
+	const warn = (code, message) => issues.push({
+		severity: "warning",
+		code,
+		message
+	});
+	const linkCounts = /* @__PURE__ */ new Map();
+	for (const track of project.tracks) {
+		if (track.elements.length === 0) warn("empty-track", `track "${track.name}" (${track.id}) has no elements`);
+		const sorted = [...track.elements].sort((a, b) => a.startMs - b.startMs);
+		for (let i = 0; i < sorted.length; i++) {
+			const element = sorted[i];
+			const next = sorted[i + 1];
+			if (next && next.startMs < element.startMs + element.durationMs) error("overlap", `elements "${element.id}" and "${next.id}" overlap on track "${track.name}" (${element.startMs}–${element.startMs + element.durationMs}ms vs ${next.startMs}ms)`);
+			lintElement(project, track, element, sorted, i, {
+				error,
+				warn
+			});
+			if (element.linkId) linkCounts.set(element.linkId, (linkCounts.get(element.linkId) ?? 0) + 1);
+		}
+	}
+	for (const [linkId, count] of linkCounts) if (count < 2) warn("broken-link", `linkId "${linkId}" is held by a single element (its partner was removed)`);
+	if (getProjectDurationMs(project) === 0) warn("empty-project", "project has no content (duration 0ms)");
+	return issues;
+}
+function lintElement(project, track, element, sorted, index, { error, warn }) {
+	if ("assetId" in element && !project.assets[element.assetId]) error("missing-asset", `element "${element.id}" references missing asset "${element.assetId}"`);
+	if ("keyframes" in element && element.keyframes) {
+		for (const [property, keyframes] of Object.entries(element.keyframes)) for (const keyframe of keyframes ?? []) if (keyframe.timeMs > element.durationMs) warn("keyframe-out-of-range", `element "${element.id}" has a ${property} keyframe at ${keyframe.timeMs}ms, beyond its ${element.durationMs}ms duration (it will never be reached)`);
+	}
+	if ("transition" in element && element.transition) {
+		const next = sorted[index + 1];
+		if (!next || next.startMs !== element.startMs + element.durationMs) warn("transition-without-neighbor", `element "${element.id}" has a transition but no exactly-adjacent next clip on track "${track.name}" (transitions need a butt cut)`);
+	}
+	if (element.type === "caption" && element.text.trim() === "") warn("empty-caption", `caption "${element.id}" has no text`);
+	if (element.type === "multicam") {
+		if (element.angles.length === 0 || element.angles[0].atMs !== 0) error("multicam-first-angle", `multicam "${element.id}" must have an angle cut at 0ms`);
+		for (const angle of element.angles) {
+			if (!project.layouts.some((layout) => layout.id === angle.layoutId)) error("missing-layout", `multicam "${element.id}" cuts to unknown layout "${angle.layoutId}" at ${angle.atMs}ms`);
+			if (angle.atMs >= element.durationMs) warn("angle-beyond-end", `multicam "${element.id}" has an angle cut at ${angle.atMs}ms, at or beyond its ${element.durationMs}ms duration`);
+		}
+		for (const source of element.sources) if (!project.assets[source.assetId]) error("missing-asset", `multicam "${element.id}" source "${source.key}" references missing asset "${source.assetId}"`);
+		if (element.audioSource !== void 0 && !element.sources.some((source) => source.key === element.audioSource)) error("missing-audio-source", `multicam "${element.id}" plays audio from unknown source "${element.audioSource}"`);
+	}
+}
+//#endregion
+//#region src/silence.ts
+/**
+* Plan and apply silence cuts on one video/audio element from its transcript.
+*
+* Word timings are source-media times, so the element must play at 1x (no
+* timeMap). Interior and leading silences become split + rippleDelete (later
+* clips on the track shift left — cutting leading silence replaces the
+* element id with a fresh one); trailing silence becomes a trim. Cuts are
+* applied last-to-first so earlier timeline positions stay valid throughout.
+*/
+function planSilenceCuts(project, elementId, transcript, options = {}) {
+	const minGapMs = options.minGapMs ?? 600;
+	const paddingMs = options.paddingMs ?? 120;
+	const minKeepMs = Math.max(options.minKeepMs ?? 250, MIN_ELEMENT_DURATION_MS);
+	const trimEnds = options.trimEnds ?? true;
+	const location = getElementLocation(project, elementId);
+	if (!location) throw new Error(`no element "${elementId}" in project`);
+	const element = location.element;
+	if (element.type !== "video" && element.type !== "audio") throw new Error(`silence cuts apply to video/audio elements, not "${element.type}"`);
+	if (element.timeMap) throw new Error(`element "${elementId}" has a time remap; silence cuts require 1x playback (clear it with setTimeMap null first)`);
+	const windowStart = element.trimStartMs;
+	const windowEnd = element.trimStartMs + element.durationMs;
+	const words = transcript.words.filter((word) => word.endMs > windowStart && word.startMs < windowEnd).sort((a, b) => a.startMs - b.startMs);
+	if (words.length === 0) throw new Error(`transcript has no words inside the element's source window (${windowStart}–${windowEnd}ms) — cutting everything is never what you want`);
+	const silences = findSilences(words, windowStart, windowEnd, {
+		minGapMs,
+		paddingMs,
+		minKeepMs,
+		trimEnds
+	});
+	const engine = new EditorEngine({ project });
+	const commands = [];
+	const dispatch = (command) => {
+		engine.dispatch(command);
+		commands.push(command);
+	};
+	const current = () => {
+		const found = getElementLocation(engine.project, elementId);
+		if (!found || found.element.type !== "video" && found.element.type !== "audio") throw new Error(`element "${elementId}" disappeared mid-plan`);
+		return found.element;
+	};
+	for (const silence of [...silences].reverse()) {
+		const el = current();
+		const toTimeline = (sourceMs) => el.startMs + (sourceMs - el.trimStartMs);
+		if (silence.endMs >= windowEnd) dispatch({
+			type: "trimElement",
+			elementId,
+			durationMs: toTimeline(silence.startMs) - el.startMs
+		});
+		else if (silence.startMs <= windowStart) {
+			dispatch({
+				type: "splitElement",
+				elementId,
+				atMs: toTimeline(silence.endMs),
+				rightElementId: createElementId()
+			});
+			dispatch({
+				type: "rippleDelete",
+				elementIds: [elementId]
+			});
+		} else {
+			dispatch({
+				type: "splitElement",
+				elementId,
+				atMs: toTimeline(silence.endMs)
+			});
+			dispatch({
+				type: "splitElement",
+				elementId,
+				atMs: toTimeline(silence.startMs)
+			});
+			const middle = engine.project.tracks.find((t) => t.elements.some((e) => e.id === elementId)).elements.find((e) => e.id !== elementId && e.startMs === toTimeline(silence.startMs));
+			if (!middle) throw new Error(`lost the silence chunk at ${silence.startMs}ms after splitting`);
+			dispatch({
+				type: "rippleDelete",
+				elementIds: [middle.id]
+			});
+		}
+	}
+	return {
+		silences,
+		commands,
+		removedMs: silences.reduce((sum, s) => sum + (s.endMs - s.startMs), 0),
+		project: engine.project
+	};
+}
+function findSilences(words, windowStart, windowEnd, { minGapMs, paddingMs, minKeepMs, trimEnds }) {
+	const raw = [];
+	const first = words[0];
+	if (trimEnds && first.startMs - windowStart > minGapMs) raw.push({
+		startMs: windowStart,
+		endMs: first.startMs - paddingMs
+	});
+	for (let i = 0; i < words.length - 1; i++) {
+		const gapStart = words[i].endMs;
+		const gapEnd = words[i + 1].startMs;
+		if (gapEnd - gapStart > minGapMs) raw.push({
+			startMs: gapStart + paddingMs,
+			endMs: gapEnd - paddingMs
+		});
+	}
+	const last = words[words.length - 1];
+	if (trimEnds && windowEnd - last.endMs > minGapMs) raw.push({
+		startMs: last.endMs + paddingMs,
+		endMs: windowEnd
+	});
+	const clamped = raw.map((s) => ({
+		startMs: Math.round(Math.max(s.startMs, windowStart)),
+		endMs: Math.round(Math.min(s.endMs, windowEnd))
+	})).filter((s) => s.endMs - s.startMs >= MIN_ELEMENT_DURATION_MS);
+	const merged = [];
+	for (const silence of clamped) {
+		const previous = merged[merged.length - 1];
+		if (previous && silence.startMs - previous.endMs < minKeepMs) previous.endMs = silence.endMs;
+		else merged.push({ ...silence });
+	}
+	if (merged.some((s) => s.startMs <= windowStart && s.endMs >= windowEnd)) throw new Error("silence cut would remove the entire element — check the transcript timing");
+	return merged;
+}
+//#endregion
+//#region src/captions.ts
+/**
+* Build an `applyCaptions` command from a transcript, with element scoping
+* and named style presets resolved. Dispatch the result (or hand it to an
+* agent) — this does not mutate the project.
+*/
+function buildCaptionsCommand(project, transcript, options = {}) {
+	let style;
+	if (options.styleId) {
+		const preset = CAPTION_STYLE_PRESETS.find((p) => p.id === options.styleId);
+		if (!preset) {
+			const known = CAPTION_STYLE_PRESETS.map((p) => p.id).join(", ");
+			throw new Error(`unknown caption style "${options.styleId}" (known: ${known})`);
+		}
+		style = preset.style;
+	}
+	let scope = {};
+	if (options.elementId) {
+		const location = getElementLocation(project, options.elementId);
+		if (!location) throw new Error(`no element "${options.elementId}" in project`);
+		const element = location.element;
+		if (element.type !== "video" && element.type !== "audio") throw new Error(`captions scope to video/audio elements, not "${element.type}"`);
+		if (element.timeMap) throw new Error(`element "${options.elementId}" has a time remap; transcript times will not line up`);
+		scope = {
+			timeOffsetMs: element.startMs,
+			sourceStartMs: element.trimStartMs,
+			sourceEndMs: element.trimStartMs + element.durationMs
+		};
+	}
+	return buildApplyCaptionsCommand(transcript, {
+		...scope,
+		...style ? { style } : {},
+		...options.maxChars !== void 0 ? { maxChars: options.maxChars } : {},
+		...options.maxGapMs !== void 0 ? { maxGapMs: options.maxGapMs } : {},
+		...options.replace !== void 0 ? { replace: options.replace } : {}
+	});
+}
+//#endregion
+//#region src/presets.ts
+const PLATFORM_PRESETS = [
+	{
+		id: "youtube",
+		label: "YouTube (16:9)",
+		width: 1920,
+		height: 1080,
+		fps: 30,
+		safeArea: {
+			top: 0,
+			bottom: .08
+		},
+		notes: "Standard horizontal video. The bottom ~8% is covered by the scrubber on hover; avoid parking captions or lower thirds at the very bottom edge."
+	},
+	{
+		id: "youtube-4k",
+		label: "YouTube 4K (16:9)",
+		width: 3840,
+		height: 2160,
+		fps: 30,
+		safeArea: {
+			top: 0,
+			bottom: .08
+		},
+		notes: "As youtube, at UHD. Use for screen-recording-heavy content where text must stay crisp."
+	},
+	{
+		id: "shorts",
+		label: "YouTube Shorts (9:16)",
+		width: 1080,
+		height: 1920,
+		fps: 30,
+		safeArea: {
+			top: .1,
+			bottom: .25
+		},
+		notes: "Vertical, 60s max (3min allowed, 60s favored). Title/channel chrome overlays the top 10%; like/comment rail and description cover the bottom 25%. Center captions in the middle band."
+	},
+	{
+		id: "tiktok",
+		label: "TikTok (9:16)",
+		width: 1080,
+		height: 1920,
+		fps: 30,
+		safeArea: {
+			top: .1,
+			bottom: .25
+		},
+		notes: "Vertical. Hook in the first 1–2s; 21–34s is the engagement sweet spot. Keep captions and faces inside the middle band — the right rail and bottom description bar overlap the frame."
+	},
+	{
+		id: "reels",
+		label: "Instagram Reels (9:16)",
+		width: 1080,
+		height: 1920,
+		fps: 30,
+		safeArea: {
+			top: .1,
+			bottom: .25
+		},
+		notes: "Vertical, 90s max. The feed crops a 4:5 preview from the center — keep the subject centered vertically so the crop still works."
+	},
+	{
+		id: "square",
+		label: "Square (1:1)",
+		width: 1080,
+		height: 1080,
+		fps: 30,
+		safeArea: {
+			top: 0,
+			bottom: .1
+		},
+		notes: "Feed-neutral square. Works on LinkedIn and X timelines without cropping."
+	}
+];
+function getPlatformPreset(id) {
+	return PLATFORM_PRESETS.find((preset) => preset.id === id);
+}
+//#endregion
+//#region src/io.ts
+async function readProjectFile(path) {
+	return parseProject(JSON.parse(await readFile(path, "utf8")));
+}
+async function writeProjectFile(path, project) {
+	await writeFile(path, `${JSON.stringify(project, null, 2)}\n`, "utf8");
+}
+/**
+* Lenient validation for transcript JSON (providers normalize to
+* TranscriptResult, but hand-made files often carry only `words`).
+*/
+const transcriptSchema = z.object({
+	text: z.string().default(""),
+	language: z.string().optional(),
+	durationMs: z.number().optional(),
+	words: z.array(z.object({
+		text: z.string(),
+		startMs: z.number(),
+		endMs: z.number(),
+		confidence: z.number().optional(),
+		speaker: z.string().optional()
+	})).default([]),
+	segments: z.array(z.object({
+		text: z.string(),
+		startMs: z.number(),
+		endMs: z.number(),
+		speaker: z.string().optional()
+	})).default([])
+});
+async function readTranscriptFile(path) {
+	return transcriptSchema.parse(JSON.parse(await readFile(path, "utf8")));
+}
+//#endregion
+export { PLATFORM_PRESETS as a, planSilenceCuts as c, writeProjectFile as i, lintProject as l, readTranscriptFile as n, getPlatformPreset as o, transcriptSchema as r, buildCaptionsCommand as s, readProjectFile as t };

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@mcut/cli",
+  "version": "0.1.0-alpha.0",
+  "description": "mcut on the command line: scaffold, validate, summarize, and batch-edit project documents headlessly",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "mcut": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch --no-clean",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mattppal/mcut.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@mcut/timeline": "0.1.0-alpha.0",
+    "@mcut/transcription": "0.1.0-alpha.0",
+    "zod": "4.4.3"
+  },
+  "author": "Matt Palmer",
+  "homepage": "https://github.com/mattppal/mcut/tree/main/packages/cli#readme",
+  "bugs": {
+    "url": "https://github.com/mattppal/mcut/issues"
+  },
+  "keywords": [
+    "mcut",
+    "video",
+    "video-editing",
+    "timeline",
+    "typescript",
+    "cli",
+    "headless"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  }
+}