@orlan-maker/cli 0.11.0 → 0.12.1

package/README.md

@@ -67,7 +67,8 @@ orlan topics list
 orlan files list [--topic <topic>]
 orlan files add <path> [--at <x,y>] [--topic <topic>]
 orlan files pull <file> [--version <n>] [--pages <n,n> | --since <n>] [--topic <topic>] [--out <path>] [--edit [--shared] [--ttl <time>]]
-orlan files push <file> <path> --changelog "<what changed>" [--answers <n,n>] [--scores <scores.json>] [--base <n>] [--topic <topic>]
+orlan files push <file> <path> --changelog "<what changed>" [--answers <n,n>] [--scores <scores.json>] [--source <folder>] [--base <n>] [--topic <topic>]
+orlan files source <file> [--number <n>] [--out <folder>] [--topic <topic>]
 orlan files rollback <file> --version <n> [--changelog "<why>"] [--topic <topic>]
 orlan comments list [--topic <topic>] [--status open|resolved|all] [--file <file>]
 orlan comment <thread> "<text>" | --file <file> --page <n> [--region <x,y,w,h>] "<text>" | --at <x,y> "<text>" [--topic <topic>]

package/dist/commands.js

@@ -3,7 +3,7 @@
  * arguments and runs one of them.
  */
 import { openAsBlob } from "node:fs";
-import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { hostname } from "node:os";
 import path from "node:path";
 import { agentIds, agentLabels, detectAgent, parseAgent, planOldInstall, skillsDir, } from "./agents.js";
@@ -135,6 +135,12 @@ const shotsHelp = (column) => [
     '[{ "name": "Hook", "start": 0, "end": 4.5 }], in seconds. The review shows the scene list.',
     "Orlan refuses a bad list with shots_invalid, and names the problem.",
 ].map((line, index) => (index === 0 ? "--shots <file>" : "").padEnd(column) + line);
+/** The help of --source (F149), its text from `column` on. */
+const sourceHelp = (column) => [
+    "For a video: its source folder, the hf/ folder of the video skill. Orlan keeps it with the",
+    "version, so a person can change its fields with Quick edit and you render it again. Files and",
+    "folders whose names start with a dot are left out. Orlan refuses a source with GSAP code.",
+].map((line, index) => (index === 0 ? "--source <folder>" : "").padEnd(column) + line);
 /** The help of --scores (F139), its text from `column` on. */
 const scoresHelp = (column) => [
     "The critic scorecard of the version: a JSON file of 1 to 20 scores, for example",
@@ -298,6 +304,33 @@ async function shotsOption(values) {
         throw new OrlanError(`The shot list ${quote(file)} is not JSON.`, "shots_invalid", 'write a JSON array of { "name": text, "start": seconds, "end": seconds }');
     }
 }
+/**
+ * --source of files add and files push (F149): the files of a video's source folder, as one JSON bundle
+ * { format: "orlan-video-source", files: { path: base64 } }. Names that start with a dot (hf/.hyperframes,
+ * .DS_Store) and node_modules are left out. Orlan checks the source.
+ */
+async function sourceOption(values) {
+    const folder = values.source;
+    if (typeof folder !== "string")
+        return undefined;
+    const entries = await readdir(folder, { recursive: true, withFileTypes: true }).catch(() => {
+        throw new OrlanError(`Cannot read the source folder ${quote(folder)}.`, "source_invalid", "check the path of --source");
+    });
+    const files = {};
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const full = path.join(entry.parentPath, entry.name);
+        const relative = path.relative(folder, full).split(path.sep).join("/");
+        if (relative.split("/").some((part) => part.startsWith(".") || part === "node_modules"))
+            continue;
+        files[relative] = (await readFile(full)).toString("base64");
+    }
+    if (!files["index.html"]) {
+        throw new OrlanError(`The source folder ${quote(folder)} has no index.html.`, "source_invalid", "give the hf folder of the video project: --source hf");
+    }
+    return new Blob([JSON.stringify({ format: "orlan-video-source", files })], { type: "application/json" });
+}
 /** --scores of files add and files push (F139): the JSON of the scorecard file. Orlan checks the scores. */
 async function scoresOption(values) {
     const file = values.scores;
@@ -759,7 +792,7 @@ export const commands = {
         }),
     },
     "files add": {
-        usage: "orlan files add <path>... [--carousel [--name <name>]] [--at <x,y>] [--shots <shots.json>] [--scores <scores.json>] [--topic <topic> | --new-topic <name>] [--agent <id>] [--json]",
+        usage: "orlan files add <path>... [--carousel [--name <name>]] [--at <x,y>] [--shots <shots.json>] [--scores <scores.json>] [--source <folder>] [--topic <topic> | --new-topic <name>] [--agent <id>] [--json]",
         summary: "Post a local file as a new file on a topic, and put it on the board.",
         details: [
             "One request sends the file and places it on the board, right of the other items. The server",
@@ -773,6 +806,7 @@ export const commands = {
             "                 place. `orlan board` shows where the items are.",
             ...shotsHelp(17),
             ...scoresHelp(17),
+            ...sourceHelp(17),
             "--topic <topic>  The topic id or its name. Default: the topic open in Orlan now, else the one used last.",
             ...NEW_TOPIC_HELP,
             AGENT_TOKEN_HELP,
@@ -786,6 +820,7 @@ export const commands = {
             at: { type: "string" },
             shots: { type: "string" },
             scores: { type: "string" },
+            source: { type: "string" },
             carousel: { type: "boolean" },
             name: { type: "string" },
         },
@@ -803,6 +838,10 @@ export const commands = {
             if (values.carousel && shots.shots !== undefined) {
                 throw new OrlanError("--shots goes with a video, not with --carousel.", "shots_invalid", "leave out --shots");
             }
+            if (values.carousel && values.source !== undefined) {
+                throw new OrlanError("--source goes with a video, not with --carousel.", "source_invalid", "leave out --source");
+            }
+            const source = await sourceOption(values);
             const { topicId, newTopic } = await writeTopic(api, values, io);
             const madeTopic = newTopic ? { newTopic } : {};
             if (values.carousel) {
@@ -837,12 +876,17 @@ export const commands = {
                         `${slides.map((slide) => path.basename(slide)).join(", ")}. It is on the board.`,
                 ], doneStep("comments on the file"));
             }
-            if (at || shots.shots !== undefined || scores.scores !== undefined) {
-                // A place on the board, a shot list or a scorecard: the file goes up first, then the post places it.
+            if (at || shots.shots !== undefined || scores.scores !== undefined || source) {
+                // A place on the board, a shot list, a scorecard or a source: the file goes up first, then the post
+                // places it.
                 const uploadId = await api.upload(await openAsBlob(filePath), {
                     topic: topicId,
                     name: path.basename(filePath),
                 });
+                // The source goes up as its own upload, with the name of the video: it has the limit of a video.
+                const sourceId = source
+                    ? await api.upload(source, { topic: topicId, name: path.basename(filePath) }, "the source")
+                    : undefined;
                 const posted = await api.call("post", {
                     topicId,
                     name: path.basename(filePath),
@@ -850,6 +894,7 @@ export const commands = {
                     ...(at ? { position: { x: at[0], y: at[1] } } : {}),
                     ...shots,
                     ...scores,
+                    ...(sourceId ? { source: sourceId } : {}),
                 });
                 return finish(io, values, {
                     file: { id: posted.file.id, name: posted.file.name, version: posted.posted.number },
@@ -859,6 +904,7 @@ export const commands = {
                     `Added ${quote(posted.file.name)} as file ${posted.file.id}, v${posted.posted.number}. It is on the ` +
                         `board${at ? ` at ${at.join(",")}, or at the nearest free place` : ""}; its pages render now.`,
                     ...(shots.shots !== undefined ? ["Its shot list shows as the scene list of the video."] : []),
+                    ...(sourceId ? ["Its source is in Orlan: people can change its fields with Quick edit."] : []),
                 ], doneStep("comments on the file"));
             }
             const { nextStep, ...answer } = await api.postFile("/api/agent/files", { name: path.basename(filePath), topic: topicId }, await openAsBlob(filePath), "the new file");
@@ -962,7 +1008,7 @@ export const commands = {
         }),
     },
     "files push": {
-        usage: 'orlan files push <file> <path>... --changelog "<what changed>" [--answers <n,n>] [--base <n>] [--shots <shots.json>] [--scores <scores.json>] [--topic <topic>] [--agent <id>] [--json]',
+        usage: 'orlan files push <file> <path>... --changelog "<what changed>" [--answers <n,n>] [--base <n>] [--shots <shots.json>] [--scores <scores.json>] [--source <folder>] [--topic <topic>] [--agent <id>] [--json]',
         summary: "Post a local file as a new version of a file.",
         details: [
             "Two requests: one sends the file, one posts it with the changelog. It must be the same type of",
@@ -978,6 +1024,7 @@ export const commands = {
             "--base <n>          The version you edited, for example 4 or v4. Default: the version your `pull --edit` got.",
             ...shotsHelp(20),
             ...scoresHelp(20),
+            ...sourceHelp(20),
             "--topic <topic>     The topic of a file name, when two topics have a file with that name.",
             AGENT_TOKEN_HELP,
             JSON_HELP,
@@ -990,6 +1037,7 @@ export const commands = {
             topic: { type: "string" },
             shots: { type: "string" },
             scores: { type: "string" },
+            source: { type: "string" },
             answers: { type: "string" },
         },
         positionals: [2, CAROUSEL_SLIDES_MAX + 1],
@@ -1002,6 +1050,7 @@ export const commands = {
             const shots = await shotsOption(values);
             const scores = await scoresOption(values);
             const answers = answersOption(values);
+            const source = await sourceOption(values);
             // Several paths are the slides of a new carousel version (F136), in the order of their names.
             const uploadIds = [];
             for (const filePath of filePaths.length > 1 ? slideOrder(filePaths) : filePaths) {
@@ -1019,12 +1068,81 @@ export const commands = {
                 ...shots,
                 ...scores,
                 ...answers,
+                ...(source
+                    ? {
+                        source: await api.upload(source, { file: fileRef, topic: values.topic }, "the source"),
+                    }
+                    : {}),
             });
             return finish(io, values, { file: { id: posted.file.id, name: posted.file.name }, version: posted.posted.number }, [
                 `Posted version ${posted.posted.number} of ${quote(posted.file.name)}. It waits for a person to make it current.`,
             ], doneStep("comments on the version"));
         }),
     },
+    "files source": {
+        usage: "orlan files source <file> [--number <n>] [--out <folder>] [--topic <topic>] [--agent <id>] [--json]",
+        summary: "Pull the source of a video into a folder, to render it again.",
+        details: [
+            "The source is the hf/ folder that went up with `files push --source`. A person changes its fields",
+            "with Quick edit in Orlan: that saves a new source, which waits for your render. Pull it, render",
+            "it with the video skill, and push the mp4 with --source as the next version.",
+            "",
+            "<file>             The file id, or its name where it is unique on the topic.",
+            "--number <n>       A source number. Default: the newest source.",
+            "--out <folder>     The folder to write it into. Default: hf. Files of the source replace the ones",
+            "                   there; other files stay.",
+            "--topic <topic>    The topic of a file name, when two topics have a file with that name.",
+            AGENT_TOKEN_HELP,
+            JSON_HELP,
+        ],
+        options: {
+            ...agentOption,
+            ...jsonOption,
+            number: { type: "string" },
+            out: { type: "string" },
+            topic: { type: "string" },
+        },
+        positionals: [1, 1],
+        run: (values, [fileRef], io) => withAgent(values, async (api) => {
+            const number = typeof values.number === "string" ? values.number.replace(/^#/, "") : undefined;
+            if (number !== undefined && !/^[1-9]\d*$/.test(number)) {
+                throw new OrlanError("--number is a source number, for example 2.", undefined, "leave out --number for the newest");
+            }
+            const found = await api.call("get_file", {
+                artifactId: fileRef,
+                ...topicInput(values),
+                pageImages: "none",
+            });
+            const source = await api.get(`/api/artifacts/${found.file.id}/source/files`, { number }, "the source");
+            const out = typeof values.out === "string" ? values.out : "hf";
+            const root = path.resolve(out);
+            for (const [name, base64] of Object.entries(source.files)) {
+                const target = path.resolve(root, name);
+                // Orlan checks the paths of a source; the CLI writes nothing outside the folder all the same.
+                if (!target.startsWith(`${root}${path.sep}`))
+                    throw new OrlanError(`The source has a bad path ${quote(name)}.`);
+                await mkdir(path.dirname(target), { recursive: true });
+                await writeFile(target, Buffer.from(base64, "base64"));
+            }
+            const count = Object.keys(source.files).length;
+            const waits = source.versionNumber === null;
+            return finish(io, values, {
+                file: { id: found.file.id, name: found.file.name },
+                source: source.number,
+                version: source.versionNumber,
+                changes: source.changes,
+                saved: out,
+                files: count,
+            }, [
+                `Saved source ${source.number} of ${quote(found.file.name)} to ${quote(out)}: ${count} file${count === 1 ? "" : "s"}.`,
+                waits
+                    ? `It waits for a render. Changed in Quick edit: ${source.changes.join("; ") || "nothing named"}.`
+                    : `Version ${source.versionNumber} was rendered from it.`,
+            ], waits
+                ? `render it (node video.mjs audio, then node video.mjs render), then orlan files push ${found.file.id} renders/<video>.mp4 --source ${out} --changelog "Rendered source ${source.number}"`
+                : doneStep());
+        }),
+    },
     "files rollback": {
         usage: 'orlan files rollback <file> --version <n> [--changelog "<why>"] [--topic <topic>] [--agent <id>] [--json]',
         summary: "Post an older version of a file again, as its newest version.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orlan-maker/cli",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "The orlan command: connect Claude Code, Codex, Cursor or OpenCode to Orlan with a token and skills, and work with its topics, files and comments from the terminal.",
   "license": "MIT",
   "type": "module",

package/skills/orlan-versions/SKILL.md

@@ -38,6 +38,12 @@ description: Get a file from Orlan and post a new version of it with a changelog
   critic round. People see it read only in the review and in Compare, with the change from the version
   before. Orlan refuses a bad scorecard with `scores_invalid` and names the problem. `orlan files list`
   shows the total of the newest scored version; `orlan comments list` shows "answered in v<n>".
+- `--source hf` on `files add` or `files push` of a video - its source folder (the hf/ folder of the
+  video skill). Orlan keeps it with the version. A person changes its fields (scene text, images, colors,
+  scene lengths) with Quick edit in Orlan. That saves a new source, and a comment asks you to render it.
+  Orlan refuses a source with GSAP code with `source_invalid`.
+- `orlan files source <file> [--out hf]` - saves the newest source of a video into the folder. When it
+  waits for a render, render it and push the mp4 with `--source hf` as the next version.
 - `orlan files rollback <file> --version 3 --changelog "<why>"` - posts an older version again, as the
   newest version. It waits for a person to make it current, as a push does.
 - `<file>` is the file id or the file name, and `<topic>` the topic id or its name. When a name is on two