transloadit 4.7.4 → 4.7.6

package/dist/cli/commands/assemblies.js

@@ -1,11 +1,12 @@
+import { randomUUID } from 'node:crypto';
 import EventEmitter from 'node:events';
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 import process from 'node:process';
+import { Writable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { setTimeout as delay } from 'node:timers/promises';
-import tty from 'node:tty';
 import { promisify } from 'node:util';
 import { Command, Option } from 'clipanion';
 import got from 'got';
@@ -14,12 +15,33 @@ import * as t from 'typanion';
 import { z } from 'zod';
 import { formatLintIssue } from "../../alphalib/assembly-linter.lang.en.js";
 import { tryCatch } from "../../alphalib/tryCatch.js";
-import { stepsSchema } from "../../alphalib/types/template.js";
+import { ensureUniqueCounterValue } from "../../ensureUniqueCounter.js";
 import { lintAssemblyInstructions } from "../../lintAssemblyInstructions.js";
 import { lintingExamples } from "../docs/assemblyLintingExamples.js";
-import { createReadStream, formatAPIError, readCliInput, streamToBuffer } from "../helpers.js";
+import { concurrencyOption, deleteAfterProcessingOption, inputPathsOption, printUrlsOption, recursiveOption, reprocessStaleOption, singleAssemblyOption, validateSharedFileProcessingOptions, watchOption, } from "../fileProcessingOptions.js";
+import { formatAPIError, readCliInput } from "../helpers.js";
+import { normalizeAssemblyResults } from "../resultFiles.js";
+import { collectNormalizedResultUrlRows, printResultUrls } from "../resultUrls.js";
+import { readStepsInputFile } from "../stepsInput.js";
 import { ensureError, isErrnoException } from "../types.js";
 import { AuthenticatedCommand, UnauthenticatedCommand } from "./BaseCommand.js";
+function parseTemplateFieldAssignments(output, fields) {
+    if (fields == null || fields.length === 0) {
+        return undefined;
+    }
+    const fieldsMap = {};
+    for (const field of fields) {
+        const eqIndex = field.indexOf('=');
+        if (eqIndex === -1) {
+            output.error(`invalid argument for --field: '${field}'`);
+            return undefined;
+        }
+        const key = field.slice(0, eqIndex);
+        const value = field.slice(eqIndex + 1);
+        fieldsMap[key] = value;
+    }
+    return fieldsMap;
+}
 const AssemblySchema = z.object({
     id: z.string(),
 });
@@ -84,13 +106,7 @@ export { deleteAssemblies as delete };
 export async function replay(output, client, { fields, reparse, steps, notify_url, assemblies }) {
     if (steps) {
         try {
-            const buf = await streamToBuffer(createReadStream(steps));
-            const parsed = JSON.parse(buf.toString());
-            const validated = stepsSchema.safeParse(parsed);
-            if (!validated.success) {
-                throw new Error(`Invalid steps format: ${validated.error.message}`);
-            }
-            await apiCall(validated.data);
+            await apiCall(await readStepsInputFile(steps));
         }
         catch (err) {
             const error = ensureError(err);
@@ -106,7 +122,6 @@ export async function replay(output, client, { fields, reparse, steps, notify_ur
                 reparse_template: reparse ? 1 : 0,
                 fields,
                 notify_url,
-                // Steps (validated) is assignable to StepsInput at runtime; cast for TS
                 steps: stepsOverride,
             }));
             if (err) {
@@ -221,12 +236,42 @@ async function myStat(stdioStream, filepath) {
     }
     return await fsp.stat(filepath);
 }
+function getJobInputPath(filepath) {
+    const normalizedFile = path.normalize(filepath);
+    if (normalizedFile === '-') {
+        return stdinWithPath.path;
+    }
+    return normalizedFile;
+}
+function createInputUploadStream(filepath) {
+    const instream = fs.createReadStream(filepath);
+    // Attach a no-op error handler to prevent unhandled errors if stream is destroyed
+    // before being consumed (e.g., due to output collision detection)
+    instream.on('error', () => { });
+    return instream;
+}
+function createOutputPlan(pathname, mtime) {
+    if (pathname == null) {
+        return {
+            mtime,
+        };
+    }
+    return {
+        mtime,
+        path: pathname,
+    };
+}
+async function createExistingPathOutputPlan(outputPath) {
+    if (outputPath == null) {
+        return createOutputPlan(undefined, new Date(0));
+    }
+    const [, stats] = await tryCatch(fsp.stat(outputPath));
+    return createOutputPlan(outputPath, stats?.mtime ?? new Date(0));
+}
 function dirProvider(output) {
     return async (inpath, indir = process.cwd()) => {
-        // Inputless assemblies can still write into a directory, but output paths are derived from
-        // assembly results rather than an input file path (handled later).
         if (inpath == null) {
-            return null;
+            return await createExistingPathOutputPlan(output);
         }
         if (inpath === '-') {
             throw new Error('You must provide an input to output to a directory');
@@ -234,37 +279,229 @@ function dirProvider(output) {
         let relpath = path.relative(indir, inpath);
         relpath = relpath.replace(/^(\.\.\/)+/, '');
         const outpath = path.join(output, relpath);
-        const outdir = path.dirname(outpath);
-        await fsp.mkdir(outdir, { recursive: true });
-        const [, stats] = await tryCatch(fsp.stat(outpath));
-        const mtime = stats?.mtime ?? new Date(0);
-        const outstream = fs.createWriteStream(outpath);
-        // Attach a no-op error handler to prevent unhandled errors if stream is destroyed
-        // before being consumed (e.g., due to output collision detection)
-        outstream.on('error', () => { });
-        outstream.mtime = mtime;
-        return outstream;
+        return await createExistingPathOutputPlan(outpath);
     };
 }
 function fileProvider(output) {
-    const dirExistsP = fsp.mkdir(path.dirname(output), { recursive: true });
     return async (_inpath) => {
-        await dirExistsP;
-        if (output === '-')
-            return process.stdout;
-        const [, stats] = await tryCatch(fsp.stat(output));
-        const mtime = stats?.mtime ?? new Date(0);
-        const outstream = fs.createWriteStream(output);
-        // Attach a no-op error handler to prevent unhandled errors if stream is destroyed
-        // before being consumed (e.g., due to output collision detection)
-        outstream.on('error', () => { });
-        outstream.mtime = mtime;
-        return outstream;
+        if (output === '-') {
+            return await createExistingPathOutputPlan(undefined);
+        }
+        return await createExistingPathOutputPlan(output);
     };
 }
 function nullProvider() {
     return async (_inpath) => null;
 }
+async function downloadResultToFile(resultUrl, outPath, signal) {
+    await fsp.mkdir(path.dirname(outPath), { recursive: true });
+    const tempPath = path.join(path.dirname(outPath), `.${path.basename(outPath)}.${randomUUID()}.tmp`);
+    const outStream = fs.createWriteStream(tempPath);
+    outStream.on('error', () => { });
+    const [dlErr] = await tryCatch(pipeline(got.stream(resultUrl, { signal }), outStream));
+    if (dlErr) {
+        await fsp.rm(tempPath, { force: true });
+        throw dlErr;
+    }
+    await fsp.rename(tempPath, outPath);
+}
+async function downloadResultToStdout(resultUrl, signal) {
+    const stdoutStream = new Writable({
+        write(chunk, _encoding, callback) {
+            let settled = false;
+            const finish = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                process.stdout.off('drain', onDrain);
+                process.stdout.off('error', onError);
+                callback(err ?? undefined);
+            };
+            const onDrain = () => finish();
+            const onError = (err) => finish(err);
+            process.stdout.once('error', onError);
+            try {
+                if (process.stdout.write(chunk)) {
+                    finish();
+                    return;
+                }
+                process.stdout.once('drain', onDrain);
+            }
+            catch (err) {
+                finish(ensureError(err));
+            }
+        },
+        final(callback) {
+            callback();
+        },
+    });
+    await pipeline(got.stream(resultUrl, { signal }), stdoutStream);
+}
+function sanitizeResultName(value) {
+    const base = path.basename(value);
+    return base.replaceAll('\\', '_').replaceAll('/', '_').replaceAll('\u0000', '');
+}
+async function ensureUniquePath(targetPath, reservedPaths) {
+    const parsed = path.parse(targetPath);
+    return await ensureUniqueCounterValue({
+        initialValue: targetPath,
+        isTaken: async (candidate) => {
+            if (reservedPaths.has(candidate)) {
+                return true;
+            }
+            const [statErr] = await tryCatch(fsp.stat(candidate));
+            return statErr == null;
+        },
+        reserve: (candidate) => {
+            reservedPaths.add(candidate);
+        },
+        nextValue: (counter) => path.join(parsed.dir, `${parsed.name}__${counter}${parsed.ext}`),
+        scope: reservedPaths,
+    });
+}
+function getResultFileName(file) {
+    return sanitizeResultName(file.name);
+}
+const STALE_OUTPUT_GRACE_MS = 1000;
+function isMeaningfullyNewer(newer, older) {
+    return newer.getTime() - older.getTime() > STALE_OUTPUT_GRACE_MS;
+}
+async function buildDirectoryDownloadTargets({ allFiles, baseDir, groupByStep, reservedPaths, }) {
+    await fsp.mkdir(baseDir, { recursive: true });
+    const targets = [];
+    for (const resultFile of allFiles) {
+        const targetDir = groupByStep ? path.join(baseDir, resultFile.stepName) : baseDir;
+        await fsp.mkdir(targetDir, { recursive: true });
+        targets.push({
+            resultUrl: resultFile.url,
+            targetPath: await ensureUniquePath(path.join(targetDir, getResultFileName(resultFile)), reservedPaths),
+        });
+    }
+    return targets;
+}
+function getSingleResultDownloadTarget(allFiles, targetPath) {
+    const first = allFiles[0];
+    const resultUrl = first?.url ?? null;
+    if (resultUrl == null) {
+        return [];
+    }
+    return [{ resultUrl, targetPath }];
+}
+async function resolveResultDownloadTargets({ hasDirectoryInput, inPath, inputs, normalizedResults, outputMode, outputPath, outputRoot, outputRootIsDirectory, reservedPaths, singleAssembly, }) {
+    const { allFiles, entries } = normalizedResults;
+    const shouldGroupByInput = !singleAssembly && inPath != null && (hasDirectoryInput || inputs.length > 1);
+    const resolveDirectoryBaseDir = () => {
+        if (!shouldGroupByInput || inPath == null) {
+            return outputRoot;
+        }
+        if (hasDirectoryInput && outputPath != null) {
+            const mappedRelative = path.relative(outputRoot, outputPath);
+            const mappedDir = path.dirname(mappedRelative);
+            const mappedStem = path.parse(mappedRelative).name;
+            return path.join(outputRoot, mappedDir === '.' ? '' : mappedDir, mappedStem);
+        }
+        return path.join(outputRoot, path.parse(path.basename(inPath)).name);
+    };
+    if (!outputRootIsDirectory) {
+        if (allFiles.length > 1) {
+            if (outputPath == null) {
+                throw new Error('stdout can only receive a single result file');
+            }
+            throw new Error('file outputs can only receive a single result file');
+        }
+        return getSingleResultDownloadTarget(allFiles, outputPath);
+    }
+    if (singleAssembly) {
+        return await buildDirectoryDownloadTargets({
+            allFiles,
+            baseDir: outputRoot,
+            groupByStep: false,
+            reservedPaths,
+        });
+    }
+    if (outputMode === 'directory' || outputPath == null || inPath == null) {
+        return await buildDirectoryDownloadTargets({
+            allFiles,
+            baseDir: resolveDirectoryBaseDir(),
+            groupByStep: entries.length > 1,
+            reservedPaths,
+        });
+    }
+    if (allFiles.length === 1) {
+        return getSingleResultDownloadTarget(allFiles, outputPath);
+    }
+    return await buildDirectoryDownloadTargets({
+        allFiles,
+        baseDir: path.join(path.dirname(outputPath), path.parse(outputPath).name),
+        groupByStep: true,
+        reservedPaths,
+    });
+}
+async function shouldSkipStaleOutput({ inputPaths, outputPath, outputPlanMtime, outputRootIsDirectory, reprocessStale, singleInputReference = 'output-plan', }) {
+    if (reprocessStale || outputPath == null || outputRootIsDirectory) {
+        return false;
+    }
+    if (inputPaths.length === 0 || inputPaths.some((inputPath) => inputPath === stdinWithPath.path)) {
+        return false;
+    }
+    const [outputErr, outputStat] = await tryCatch(fsp.stat(outputPath));
+    if (outputErr != null || outputStat == null) {
+        return false;
+    }
+    if (inputPaths.length === 1) {
+        if (singleInputReference === 'output-plan') {
+            return isMeaningfullyNewer(outputStat.mtime, outputPlanMtime);
+        }
+        const [inputErr, inputStat] = await tryCatch(fsp.stat(inputPaths[0]));
+        if (inputErr != null || inputStat == null) {
+            return false;
+        }
+        return isMeaningfullyNewer(outputStat.mtime, inputStat.mtime);
+    }
+    const inputStats = await Promise.all(inputPaths.map(async (inputPath) => {
+        const [inputErr, inputStat] = await tryCatch(fsp.stat(inputPath));
+        if (inputErr != null || inputStat == null) {
+            return null;
+        }
+        return inputStat;
+    }));
+    if (inputStats.some((inputStat) => inputStat == null)) {
+        return false;
+    }
+    return inputStats.every((inputStat) => {
+        return inputStat != null && isMeaningfullyNewer(outputStat.mtime, inputStat.mtime);
+    });
+}
+async function materializeAssemblyResults({ abortSignal, hasDirectoryInput, inPath, inputs, normalizedResults, outputMode, outputPath, outputRoot, outputRootIsDirectory, outputctl, reservedPaths, singleAssembly, }) {
+    if (outputRoot == null) {
+        return;
+    }
+    const targets = await resolveResultDownloadTargets({
+        hasDirectoryInput,
+        inPath,
+        inputs,
+        normalizedResults,
+        outputMode,
+        outputPath,
+        outputRoot,
+        outputRootIsDirectory,
+        reservedPaths,
+        singleAssembly,
+    });
+    for (const { resultUrl, targetPath } of targets) {
+        outputctl.debug('DOWNLOADING');
+        const [dlErr] = await tryCatch(targetPath == null
+            ? downloadResultToStdout(resultUrl, abortSignal)
+            : downloadResultToFile(resultUrl, targetPath, abortSignal));
+        if (dlErr) {
+            if (dlErr.name === 'AbortError') {
+                continue;
+            }
+            outputctl.error(dlErr.message);
+            throw dlErr;
+        }
+    }
+}
 class MyEventEmitter extends EventEmitter {
     hasEnded;
     constructor() {
@@ -282,34 +519,38 @@ class MyEventEmitter extends EventEmitter {
     }
 }
 class ReaddirJobEmitter extends MyEventEmitter {
-    constructor({ dir, streamRegistry, recursive, outstreamProvider, topdir = dir, }) {
+    constructor({ dir, recursive, outputPlanProvider, topdir = dir }) {
         super();
         process.nextTick(() => {
-            this.processDirectory({ dir, streamRegistry, recursive, outstreamProvider, topdir }).catch((err) => {
+            this.processDirectory({
+                dir,
+                recursive,
+                outputPlanProvider,
+                topdir,
+            }).catch((err) => {
                 this.emit('error', err);
             });
         });
     }
-    async processDirectory({ dir, streamRegistry, recursive, outstreamProvider, topdir, }) {
+    async processDirectory({ dir, recursive, outputPlanProvider, topdir, }) {
         const files = await fsp.readdir(dir);
         const pendingOperations = [];
         for (const filename of files) {
             const file = path.normalize(path.join(dir, filename));
-            pendingOperations.push(this.processFile({ file, streamRegistry, recursive, outstreamProvider, topdir }));
+            pendingOperations.push(this.processFile({ file, recursive, outputPlanProvider, topdir }));
         }
         await Promise.all(pendingOperations);
         this.emit('end');
     }
-    async processFile({ file, streamRegistry, recursive = false, outstreamProvider, topdir, }) {
+    async processFile({ file, recursive = false, outputPlanProvider, topdir, }) {
         const stats = await fsp.stat(file);
         if (stats.isDirectory()) {
             if (recursive) {
                 await new Promise((resolve, reject) => {
                     const subdirEmitter = new ReaddirJobEmitter({
                         dir: file,
-                        streamRegistry,
                         recursive,
-                        outstreamProvider,
+                        outputPlanProvider,
                         topdir,
                     });
                     subdirEmitter.on('job', (job) => this.emit('job', job));
@@ -319,62 +560,46 @@ class ReaddirJobEmitter extends MyEventEmitter {
             }
         }
         else {
-            const existing = streamRegistry[file];
-            if (existing)
-                existing.end();
-            const outstream = await outstreamProvider(file, topdir);
-            streamRegistry[file] = outstream ?? undefined;
-            const instream = fs.createReadStream(file);
-            // Attach a no-op error handler to prevent unhandled errors if stream is destroyed
-            // before being consumed (e.g., due to output collision detection)
-            instream.on('error', () => { });
-            this.emit('job', { in: instream, out: outstream });
+            const outputPlan = await outputPlanProvider(file, topdir);
+            this.emit('job', { inputPath: getJobInputPath(file), out: outputPlan });
         }
     }
 }
 class SingleJobEmitter extends MyEventEmitter {
-    constructor({ file, streamRegistry, outstreamProvider }) {
+    constructor({ file, outputPlanProvider }) {
         super();
         const normalizedFile = path.normalize(file);
-        const existing = streamRegistry[normalizedFile];
-        if (existing)
-            existing.end();
-        outstreamProvider(normalizedFile).then((outstream) => {
-            streamRegistry[normalizedFile] = outstream ?? undefined;
-            let instream;
-            if (normalizedFile === '-') {
-                if (tty.isatty(process.stdin.fd)) {
-                    instream = null;
-                }
-                else {
-                    instream = process.stdin;
-                }
-            }
-            else {
-                instream = fs.createReadStream(normalizedFile);
-                // Attach a no-op error handler to prevent unhandled errors if stream is destroyed
-                // before being consumed (e.g., due to output collision detection)
-                instream.on('error', () => { });
-            }
+        outputPlanProvider(normalizedFile)
+            .then((outputPlan) => {
             process.nextTick(() => {
-                this.emit('job', { in: instream, out: outstream });
+                this.emit('job', { inputPath: getJobInputPath(normalizedFile), out: outputPlan });
                 this.emit('end');
             });
+        })
+            .catch((err) => {
+            process.nextTick(() => {
+                this.emit('error', ensureError(err));
+            });
         });
     }
 }
 class InputlessJobEmitter extends MyEventEmitter {
-    constructor({ outstreamProvider, }) {
+    constructor({ outputPlanProvider }) {
         super();
         process.nextTick(() => {
-            outstreamProvider(null).then((outstream) => {
+            outputPlanProvider(null)
+                .then((outputPlan) => {
                 try {
-                    this.emit('job', { in: null, out: outstream });
+                    this.emit('job', { inputPath: null, out: outputPlan });
                 }
                 catch (err) {
-                    this.emit('error', err);
+                    this.emit('error', ensureError(err));
+                    return;
                 }
                 this.emit('end');
+            })
+                .catch((err) => {
+                this.emit('error', ensureError(err));
             });
         });
     }
@@ -387,9 +612,9 @@ class NullJobEmitter extends MyEventEmitter {
 }
 class WatchJobEmitter extends MyEventEmitter {
     watcher = null;
-    constructor({ file, streamRegistry, recursive, outstreamProvider }) {
+    constructor({ file, recursive, outputPlanProvider }) {
         super();
-        this.init({ file, streamRegistry, recursive, outstreamProvider }).catch((err) => {
+        this.init({ file, recursive, outputPlanProvider }).catch((err) => {
             this.emit('error', err);
         });
         // Clean up watcher on process exit signals
@@ -404,7 +629,7 @@ class WatchJobEmitter extends MyEventEmitter {
             this.watcher = null;
         }
     }
-    async init({ file, streamRegistry, recursive, outstreamProvider, }) {
+    async init({ file, recursive, outputPlanProvider, }) {
         const stats = await fsp.stat(file);
         const topdir = stats.isDirectory() ? file : undefined;
         const watchFn = await getNodeWatch();
@@ -416,25 +641,21 @@ class WatchJobEmitter extends MyEventEmitter {
         this.watcher.on('close', () => this.emit('end'));
         this.watcher.on('change', (_evt, filename) => {
             const normalizedFile = path.normalize(filename);
-            this.handleChange(normalizedFile, topdir, streamRegistry, outstreamProvider).catch((err) => {
+            this.handleChange(normalizedFile, topdir, outputPlanProvider).catch((err) => {
                 this.emit('error', err);
             });
         });
     }
-    async handleChange(normalizedFile, topdir, streamRegistry, outstreamProvider) {
+    async handleChange(normalizedFile, topdir, outputPlanProvider) {
         const stats = await fsp.stat(normalizedFile);
         if (stats.isDirectory())
             return;
-        const existing = streamRegistry[normalizedFile];
-        if (existing)
-            existing.end();
-        const outstream = await outstreamProvider(normalizedFile, topdir);
-        streamRegistry[normalizedFile] = outstream ?? undefined;
-        const instream = fs.createReadStream(normalizedFile);
-        // Attach a no-op error handler to prevent unhandled errors if stream is destroyed
-        // before being consumed (e.g., due to output collision detection)
-        instream.on('error', () => { });
-        this.emit('job', { in: instream, out: outstream });
+        const outputPlan = await outputPlanProvider(normalizedFile, topdir);
+        this.emit('job', {
+            inputPath: getJobInputPath(normalizedFile),
+            out: outputPlan,
+            watchEvent: true,
+        });
     }
 }
 class MergedJobEmitter extends MyEventEmitter {
@@ -484,12 +705,20 @@ function detectConflicts(jobEmitter) {
     jobEmitter.on('end', () => emitter.emit('end'));
     jobEmitter.on('error', (err) => emitter.emit('error', err));
     jobEmitter.on('job', (job) => {
-        if (job.in == null || job.out == null) {
+        if (job.watchEvent) {
             emitter.emit('job', job);
             return;
         }
-        const inPath = job.in.path;
+        if (job.inputPath == null || job.out == null) {
+            emitter.emit('job', job);
+            return;
+        }
+        const inPath = job.inputPath;
         const outPath = job.out.path;
+        if (outPath == null) {
+            emitter.emit('job', job);
+            return;
+        }
         if (Object.hasOwn(outfileAssociations, outPath) && outfileAssociations[outPath] !== inPath) {
             emitter.emit('error', new Error(`Output collision between '${inPath}' and '${outfileAssociations[outPath]}'`));
         }
@@ -506,11 +735,11 @@ function dismissStaleJobs(jobEmitter) {
     jobEmitter.on('end', () => Promise.all(pendingChecks).then(() => emitter.emit('end')));
     jobEmitter.on('error', (err) => emitter.emit('error', err));
     jobEmitter.on('job', (job) => {
-        if (job.in == null || job.out == null) {
+        if (job.inputPath == null || job.out == null) {
             emitter.emit('job', job);
             return;
         }
-        const inPath = job.in.path;
+        const inPath = job.inputPath;
         const checkPromise = fsp
             .stat(inPath)
             .then((stats) => {
@@ -526,30 +755,49 @@ function dismissStaleJobs(jobEmitter) {
     });
     return emitter;
 }
-function makeJobEmitter(inputs, { recursive, outstreamProvider, streamRegistry, watch: watchOption, reprocessStale, }) {
+function passthroughJobs(jobEmitter) {
+    const emitter = new MyEventEmitter();
+    jobEmitter.on('end', () => emitter.emit('end'));
+    jobEmitter.on('error', (err) => emitter.emit('error', err));
+    jobEmitter.on('job', (job) => emitter.emit('job', job));
+    return emitter;
+}
+function makeJobEmitter(inputs, { allowOutputCollisions, recursive, outputPlanProvider, singleAssembly, watch: watchOption, reprocessStale, }) {
     const emitter = new EventEmitter();
     const emitterFns = [];
     const watcherFns = [];
     async function processInputs() {
         for (const input of inputs) {
             if (input === '-') {
-                emitterFns.push(() => new SingleJobEmitter({ file: input, outstreamProvider, streamRegistry }));
+                emitterFns.push(() => new SingleJobEmitter({ file: input, outputPlanProvider }));
                 watcherFns.push(() => new NullJobEmitter());
             }
             else {
                 const stats = await fsp.stat(input);
                 if (stats.isDirectory()) {
-                    emitterFns.push(() => new ReaddirJobEmitter({ dir: input, recursive, outstreamProvider, streamRegistry }));
-                    watcherFns.push(() => new WatchJobEmitter({ file: input, recursive, outstreamProvider, streamRegistry }));
+                    emitterFns.push(() => new ReaddirJobEmitter({
+                        dir: input,
+                        recursive,
+                        outputPlanProvider,
+                    }));
+                    watcherFns.push(() => new WatchJobEmitter({
+                        file: input,
+                        recursive,
+                        outputPlanProvider,
+                    }));
                 }
                 else {
-                    emitterFns.push(() => new SingleJobEmitter({ file: input, outstreamProvider, streamRegistry }));
-                    watcherFns.push(() => new WatchJobEmitter({ file: input, recursive, outstreamProvider, streamRegistry }));
+                    emitterFns.push(() => new SingleJobEmitter({ file: input, outputPlanProvider }));
+                    watcherFns.push(() => new WatchJobEmitter({
+                        file: input,
+                        recursive,
+                        outputPlanProvider,
+                    }));
                 }
             }
         }
         if (inputs.length === 0) {
-            emitterFns.push(() => new InputlessJobEmitter({ outstreamProvider, streamRegistry }));
+            emitterFns.push(() => new InputlessJobEmitter({ outputPlanProvider }));
         }
         startEmitting();
     }
@@ -565,38 +813,24 @@ function makeJobEmitter(inputs, { recursive, outstreamProvider, streamRegistry,
     processInputs().catch((err) => {
         emitter.emit('error', err);
     });
-    const stalefilter = reprocessStale ? (x) => x : dismissStaleJobs;
-    return stalefilter(detectConflicts(emitter));
+    const conflictFilter = allowOutputCollisions ? passthroughJobs : detectConflicts;
+    const staleFilter = reprocessStale || singleAssembly ? passthroughJobs : dismissStaleJobs;
+    return staleFilter(conflictFilter(emitter));
 }
 const DEFAULT_CONCURRENCY = 5;
 // --- Main assembly create function ---
-export async function create(outputctl, client, { steps, template, fields, watch: watchOption, recursive, inputs, output, del, reprocessStale, singleAssembly, concurrency = DEFAULT_CONCURRENCY, }) {
+export async function create(outputctl, client, { steps, stepsData, template, fields, outputMode, watch: watchOption, recursive, inputs, output, del, reprocessStale, singleAssembly, concurrency = DEFAULT_CONCURRENCY, }) {
     // Quick fix for https://github.com/transloadit/transloadify/issues/13
     // Only default to stdout when output is undefined (not provided), not when explicitly null
     let resolvedOutput = output;
     if (resolvedOutput === undefined && !process.stdout.isTTY)
         resolvedOutput = '-';
     // Read steps file async before entering the Promise constructor
-    // We use StepsInput (the input type) rather than Steps (the transformed output type)
+    // We use StepsInput (the input type) rather than the transformed output type
     // to avoid zod adding default values that the API may reject
-    let stepsData;
+    let effectiveStepsData = stepsData;
     if (steps) {
-        const stepsContent = await fsp.readFile(steps, 'utf8');
-        const parsed = JSON.parse(stepsContent);
-        // Basic structural validation: must be an object with step names as keys
-        if (parsed == null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-            throw new Error('Invalid steps format: expected an object with step names as keys');
-        }
-        // Validate each step has a robot field
-        for (const [stepName, step] of Object.entries(parsed)) {
-            if (step == null || typeof step !== 'object' || Array.isArray(step)) {
-                throw new Error(`Invalid steps format: step '${stepName}' must be an object`);
-            }
-            if (!('robot' in step) || typeof step.robot !== 'string') {
-                throw new Error(`Invalid steps format: step '${stepName}' must have a 'robot' string property`);
-            }
-        }
-        stepsData = parsed;
+        effectiveStepsData = await readStepsInputFile(steps);
     }
     // Determine output stat async before entering the Promise constructor
     let outstat;
@@ -604,8 +838,17 @@ export async function create(outputctl, client, { steps, template, fields, watch
         const [err, stat] = await tryCatch(myStat(process.stdout, resolvedOutput));
         if (err && (!isErrnoException(err) || err.code !== 'ENOENT'))
             throw err;
-        outstat = stat ?? { isDirectory: () => false };
-        if (!outstat.isDirectory() && inputs.length !== 0) {
+        outstat =
+            stat ??
+                {
+                    isDirectory: () => outputMode === 'directory',
+                };
+        if (outputMode === 'directory' && stat != null && !stat.isDirectory()) {
+            const msg = 'Output must be a directory for this command';
+            outputctl.error(msg);
+            throw new Error(msg);
+        }
+        if (!outstat.isDirectory() && inputs.length !== 0 && !singleAssembly) {
             const firstInput = inputs[0];
             if (firstInput) {
                 const firstInputStat = await myStat(process.stdin, firstInput);
@@ -617,276 +860,223 @@ export async function create(outputctl, client, { steps, template, fields, watch
             }
         }
     }
+    const inputStats = await Promise.all(inputs.map(async (input) => {
+        if (input === '-')
+            return null;
+        return await myStat(process.stdin, input);
+    }));
+    const hasDirectoryInput = inputStats.some((stat) => stat?.isDirectory() === true);
     return new Promise((resolve, reject) => {
-        const params = (stepsData ? { steps: stepsData } : { template_id: template });
+        const params = (effectiveStepsData
+            ? { steps: effectiveStepsData }
+            : { template_id: template });
         if (fields) {
             params.fields = fields;
         }
-        const outstreamProvider = resolvedOutput == null
+        const outputPlanProvider = resolvedOutput == null
             ? nullProvider()
             : outstat?.isDirectory()
                 ? dirProvider(resolvedOutput)
                 : fileProvider(resolvedOutput);
-        const streamRegistry = {};
         const emitter = makeJobEmitter(inputs, {
+            allowOutputCollisions: singleAssembly,
+            outputPlanProvider,
             recursive,
             watch: watchOption,
-            outstreamProvider,
-            streamRegistry,
+            singleAssembly,
             reprocessStale,
         });
         // Use p-queue for concurrency management
         const queue = new PQueue({ concurrency });
         const results = [];
+        const resultUrls = [];
+        const reservedResultPaths = new Set();
+        const latestWatchJobTokenByOutputPath = new Map();
         let hasFailures = false;
+        let nextWatchJobToken = 0;
         // AbortController to cancel all in-flight createAssembly calls when an error occurs
         const abortController = new AbortController();
-        // Helper to process a single assembly job
-        async function processAssemblyJob(inPath, outPath, outMtime) {
-            outputctl.debug(`PROCESSING JOB ${inPath ?? 'null'} ${outPath ?? 'null'}`);
-            // Create fresh streams for this job
-            const inStream = inPath ? fs.createReadStream(inPath) : null;
-            inStream?.on('error', () => { });
-            let superceded = false;
-            // When writing to a file path (non-directory output), we treat finish as a supersede signal.
-            // Directory-output multi-download mode does not use a single shared outstream.
-            const markSupersededOnFinish = (stream) => {
-                stream.on('finish', () => {
-                    superceded = true;
-                });
-            };
+        const outputRootIsDirectory = Boolean(resolvedOutput != null && outstat?.isDirectory());
+        function reserveWatchJobToken(outputPath) {
+            if (!watchOption || outputPath == null) {
+                return null;
+            }
+            const token = ++nextWatchJobToken;
+            latestWatchJobTokenByOutputPath.set(outputPath, token);
+            return token;
+        }
+        function isSupersededWatchJob(outputPath, token) {
+            if (!watchOption || outputPath == null || token == null) {
+                return false;
+            }
+            return latestWatchJobTokenByOutputPath.get(outputPath) !== token;
+        }
+        function createAssemblyOptions({ files, uploads, } = {}) {
             const createOptions = {
                 params,
                 signal: abortController.signal,
             };
-            if (inStream != null) {
-                createOptions.uploads = { in: inStream };
+            if (files != null && Object.keys(files).length > 0) {
+                createOptions.files = files;
+            }
+            if (uploads != null && Object.keys(uploads).length > 0) {
+                createOptions.uploads = uploads;
             }
+            return createOptions;
+        }
+        async function awaitCompletedAssembly(createOptions) {
             const result = await client.createAssembly(createOptions);
-            if (superceded)
-                return undefined;
             const assemblyId = result.assembly_id;
             if (!assemblyId)
                 throw new Error('No assembly_id in result');
             const assembly = await client.awaitAssemblyCompletion(assemblyId, {
                 signal: abortController.signal,
-                onPoll: () => {
-                    if (superceded)
-                        return false;
-                    return true;
-                },
+                onPoll: () => true,
                 onAssemblyProgress: (status) => {
                     outputctl.debug(`Assembly status: ${status.ok}`);
                 },
             });
-            if (superceded)
-                return undefined;
             if (assembly.error || (assembly.ok && assembly.ok !== 'ASSEMBLY_COMPLETED')) {
                 const msg = `Assembly failed: ${assembly.error || assembly.message} (Status: ${assembly.ok})`;
                 outputctl.error(msg);
                 throw new Error(msg);
             }
+            return { assembly, assemblyId };
+        }
+        async function executeAssemblyLifecycle({ createOptions, inPath, inputPaths, outputPlan, outputToken, singleAssemblyMode, }) {
+            outputctl.debug(`PROCESSING JOB ${inPath ?? 'null'} ${outputPlan?.path ?? 'null'}`);
+            const { assembly, assemblyId } = await awaitCompletedAssembly(createOptions);
             if (!assembly.results)
                 throw new Error('No results in assembly');
-            const outIsDirectory = Boolean(resolvedOutput != null && outstat?.isDirectory());
-            const entries = Object.entries(assembly.results);
-            const allFiles = [];
-            for (const [stepName, stepResults] of entries) {
-                for (const file of stepResults) {
-                    allFiles.push({ stepName, file });
-                }
+            const normalizedResults = normalizeAssemblyResults(assembly.results);
+            if (isSupersededWatchJob(outputPlan?.path ?? null, outputToken)) {
+                outputctl.debug(`SKIPPED SUPERSEDED WATCH RESULT ${inPath ?? 'null'} ${outputPlan?.path ?? 'null'}`);
+                return assembly;
             }
-            const getFileUrl = (file) => file.ssl_url ?? file.url ?? null;
-            const sanitizeName = (value) => {
-                const base = path.basename(value);
-                return base.replaceAll('\\', '_').replaceAll('/', '_').replaceAll('\u0000', '');
-            };
-            const ensureUniquePath = async (targetPath) => {
-                const parsed = path.parse(targetPath);
-                let candidate = targetPath;
-                let counter = 1;
-                while (true) {
-                    const [statErr] = await tryCatch(fsp.stat(candidate));
-                    if (statErr)
-                        return candidate;
-                    candidate = path.join(parsed.dir, `${parsed.name}__${counter}${parsed.ext}`);
-                    counter += 1;
-                }
-            };
-            if (resolvedOutput != null && !superceded) {
-                // Directory output:
-                // - For single-result, input-backed jobs, preserve existing behavior (write to mapped file path).
-                // - Otherwise (multi-result or inputless), download all results into a directory structure.
-                if (outIsDirectory && (inPath == null || allFiles.length !== 1 || outPath == null)) {
-                    let baseDir = resolvedOutput;
-                    if (inPath != null) {
-                        let relpath = path.relative(process.cwd(), inPath);
-                        relpath = relpath.replace(/^(\.\.\/)+/, '');
-                        baseDir = path.join(resolvedOutput, path.dirname(relpath), path.parse(relpath).name);
-                    }
-                    await fsp.mkdir(baseDir, { recursive: true });
-                    for (const { stepName, file } of allFiles) {
-                        const resultUrl = getFileUrl(file);
-                        if (!resultUrl)
-                            continue;
-                        const stepDir = path.join(baseDir, stepName);
-                        await fsp.mkdir(stepDir, { recursive: true });
-                        const rawName = file.name ??
-                            (file.basename && file.ext ? `${file.basename}.${file.ext}` : undefined) ??
-                            `${stepName}_result`;
-                        const safeName = sanitizeName(rawName);
-                        const targetPath = await ensureUniquePath(path.join(stepDir, safeName));
-                        outputctl.debug('DOWNLOADING');
-                        const outStream = fs.createWriteStream(targetPath);
-                        outStream.on('error', () => { });
-                        const [dlErr] = await tryCatch(pipeline(got.stream(resultUrl, { signal: abortController.signal }), outStream));
-                        if (dlErr) {
-                            if (dlErr.name === 'AbortError')
-                                continue;
-                            outputctl.error(dlErr.message);
-                            throw dlErr;
-                        }
-                    }
-                }
-                else if (!outIsDirectory && outPath != null) {
-                    const first = allFiles[0];
-                    const resultUrl = first ? getFileUrl(first.file) : null;
-                    if (resultUrl) {
-                        outputctl.debug('DOWNLOADING');
-                        const outStream = fs.createWriteStream(outPath);
-                        outStream.on('error', () => { });
-                        outStream.mtime = outMtime;
-                        markSupersededOnFinish(outStream);
-                        const [dlErr] = await tryCatch(pipeline(got.stream(resultUrl, { signal: abortController.signal }), outStream));
-                        if (dlErr) {
-                            if (dlErr.name !== 'AbortError') {
-                                outputctl.error(dlErr.message);
-                                throw dlErr;
-                            }
-                        }
-                    }
-                }
-                else if (outIsDirectory && outPath != null) {
-                    // Single-result, input-backed job: preserve existing file mapping in outdir.
-                    const first = allFiles[0];
-                    const resultUrl = first ? getFileUrl(first.file) : null;
-                    if (resultUrl) {
-                        outputctl.debug('DOWNLOADING');
-                        const outStream = fs.createWriteStream(outPath);
-                        outStream.on('error', () => { });
-                        outStream.mtime = outMtime;
-                        markSupersededOnFinish(outStream);
-                        const [dlErr] = await tryCatch(pipeline(got.stream(resultUrl, { signal: abortController.signal }), outStream));
-                        if (dlErr) {
-                            if (dlErr.name !== 'AbortError') {
-                                outputctl.error(dlErr.message);
-                                throw dlErr;
-                            }
-                        }
+            if (!singleAssemblyMode &&
+                !watchOption &&
+                (await shouldSkipStaleOutput({
+                    inputPaths,
+                    outputPath: outputPlan?.path ?? null,
+                    outputPlanMtime: outputPlan?.mtime ?? new Date(0),
+                    outputRootIsDirectory,
+                    reprocessStale,
+                }))) {
+                outputctl.debug(`SKIPPED STALE RESULT ${inPath ?? 'null'} ${outputPlan?.path ?? 'null'}`);
+                return assembly;
+            }
+            resultUrls.push(...collectNormalizedResultUrlRows({ assemblyId, normalizedResults }));
+            await materializeAssemblyResults({
+                abortSignal: abortController.signal,
+                hasDirectoryInput: singleAssemblyMode ? false : hasDirectoryInput,
+                inPath,
+                inputs: inputPaths,
+                normalizedResults,
+                outputMode,
+                outputPath: outputPlan?.path ?? null,
+                outputRoot: resolvedOutput ?? null,
+                outputRootIsDirectory,
+                outputctl,
+                reservedPaths: reservedResultPaths,
+                singleAssembly: singleAssemblyMode,
+            });
+            outputctl.debug(`COMPLETED ${inPath ?? 'null'} ${outputPlan?.path ?? 'null'}`);
+            if (del) {
+                for (const inputPath of inputPaths) {
+                    if (inputPath === stdinWithPath.path) {
+                        continue;
                     }
+                    await fsp.unlink(inputPath);
                 }
             }
-            outputctl.debug(`COMPLETED ${inPath ?? 'null'} ${outPath ?? 'null'}`);
-            if (del && inPath) {
-                await fsp.unlink(inPath);
-            }
             return assembly;
         }
-        if (singleAssembly) {
-            // Single-assembly mode: collect file paths, then create one assembly with all inputs
-            // We close streams immediately to avoid exhausting file descriptors with many files
+        // Helper to process a single assembly job
+        async function processAssemblyJob(inPath, outputPlan, outputToken) {
+            const files = inPath != null && inPath !== stdinWithPath.path
+                ? {
+                    in: inPath,
+                }
+                : undefined;
+            const uploads = inPath === stdinWithPath.path
+                ? {
+                    in: createInputUploadStream(inPath),
+                }
+                : undefined;
+            return await executeAssemblyLifecycle({
+                createOptions: createAssemblyOptions({ files, uploads }),
+                inPath,
+                inputPaths: inPath == null ? [] : [inPath],
+                outputPlan,
+                outputToken,
+            });
+        }
+        function handleEmitterError(err) {
+            abortController.abort();
+            queue.clear();
+            outputctl.error(err);
+            reject(err);
+        }
+        function runSingleAssemblyEmitter() {
             const collectedPaths = [];
+            let inputlessOutputPlan = null;
             emitter.on('job', (job) => {
-                if (job.in != null) {
-                    const inPath = job.in.path;
+                if (job.inputPath != null) {
+                    const inPath = job.inputPath;
                     outputctl.debug(`COLLECTING JOB ${inPath}`);
                     collectedPaths.push(inPath);
-                    job.in.destroy();
-                    outputctl.debug(`STREAM CLOSED ${inPath}`);
+                    return;
                 }
-            });
-            emitter.on('error', (err) => {
-                abortController.abort();
-                queue.clear();
-                outputctl.error(err);
-                reject(err);
+                inputlessOutputPlan = job.out ?? null;
             });
             emitter.on('end', async () => {
-                if (collectedPaths.length === 0) {
-                    resolve({ results: [], hasFailures: false });
+                if (await shouldSkipStaleOutput({
+                    inputPaths: collectedPaths,
+                    outputPath: resolvedOutput ?? null,
+                    outputPlanMtime: new Date(0),
+                    outputRootIsDirectory,
+                    reprocessStale,
+                    singleInputReference: 'input',
+                })) {
+                    outputctl.debug(`SKIPPED STALE SINGLE ASSEMBLY ${resolvedOutput ?? 'null'}`);
+                    resolve({ resultUrls, results: [], hasFailures: false });
                     return;
                 }
-                // Build uploads object, creating fresh streams for each file
+                // Preserve original basenames/extensions for filesystem uploads so the backend
+                // can infer types like Markdown correctly.
+                const files = {};
                 const uploads = {};
                 const inputPaths = [];
                 for (const inPath of collectedPaths) {
                     const basename = path.basename(inPath);
-                    let key = basename;
-                    let counter = 1;
-                    while (key in uploads) {
-                        key = `${path.parse(basename).name}_${counter}${path.parse(basename).ext}`;
-                        counter++;
+                    const collection = inPath === stdinWithPath.path ? uploads : files;
+                    const key = await ensureUniqueCounterValue({
+                        initialValue: basename,
+                        isTaken: (candidate) => candidate in collection,
+                        nextValue: (counter) => `${path.parse(basename).name}_${counter}${path.parse(basename).ext}`,
+                        reserve: () => { },
+                        scope: collection,
+                    });
+                    if (inPath === stdinWithPath.path) {
+                        uploads[key] = createInputUploadStream(inPath);
+                    }
+                    else {
+                        files[key] = inPath;
                     }
-                    uploads[key] = fs.createReadStream(inPath);
                     inputPaths.push(inPath);
                 }
-                outputctl.debug(`Creating single assembly with ${Object.keys(uploads).length} files`);
+                outputctl.debug(`Creating single assembly with ${Object.keys(files).length + Object.keys(uploads).length} files`);
                 try {
                     const assembly = await queue.add(async () => {
-                        const createOptions = {
-                            params,
-                            signal: abortController.signal,
-                        };
-                        if (Object.keys(uploads).length > 0) {
-                            createOptions.uploads = uploads;
-                        }
-                        const result = await client.createAssembly(createOptions);
-                        const assemblyId = result.assembly_id;
-                        if (!assemblyId)
-                            throw new Error('No assembly_id in result');
-                        const asm = await client.awaitAssemblyCompletion(assemblyId, {
-                            signal: abortController.signal,
-                            onAssemblyProgress: (status) => {
-                                outputctl.debug(`Assembly status: ${status.ok}`);
-                            },
+                        return await executeAssemblyLifecycle({
+                            createOptions: createAssemblyOptions({ files, uploads }),
+                            inPath: null,
+                            inputPaths,
+                            outputPlan: inputlessOutputPlan ??
+                                (resolvedOutput == null ? null : createOutputPlan(resolvedOutput, new Date(0))),
+                            outputToken: null,
+                            singleAssemblyMode: true,
                         });
-                        if (asm.error || (asm.ok && asm.ok !== 'ASSEMBLY_COMPLETED')) {
-                            const msg = `Assembly failed: ${asm.error || asm.message} (Status: ${asm.ok})`;
-                            outputctl.error(msg);
-                            throw new Error(msg);
-                        }
-                        // Download all results
-                        if (asm.results && resolvedOutput != null) {
-                            for (const [stepName, stepResults] of Object.entries(asm.results)) {
-                                for (const stepResult of stepResults) {
-                                    const resultUrl = stepResult.ssl_url ?? stepResult.url;
-                                    if (!resultUrl)
-                                        continue;
-                                    let outPath;
-                                    if (outstat?.isDirectory()) {
-                                        outPath = path.join(resolvedOutput, stepResult.name || `${stepName}_result`);
-                                    }
-                                    else {
-                                        outPath = resolvedOutput;
-                                    }
-                                    outputctl.debug(`DOWNLOADING ${stepResult.name} to ${outPath}`);
-                                    const [dlErr] = await tryCatch(pipeline(got.stream(resultUrl, { signal: abortController.signal }), fs.createWriteStream(outPath)));
-                                    if (dlErr) {
-                                        if (dlErr.name === 'AbortError')
-                                            continue;
-                                        outputctl.error(dlErr.message);
-                                        throw dlErr;
-                                    }
-                                }
-                            }
-                        }
-                        // Delete input files if requested
-                        if (del) {
-                            for (const inPath of inputPaths) {
-                                await fsp.unlink(inPath);
-                            }
-                        }
-                        return asm;
                     });
                     results.push(assembly);
                 }
@@ -894,30 +1084,18 @@ export async function create(outputctl, client, { steps, template, fields, watch
                     hasFailures = true;
                     outputctl.error(err);
                 }
-                resolve({ results, hasFailures });
+                resolve({ resultUrls, results, hasFailures });
             });
         }
-        else {
-            // Default mode: one assembly per file with p-queue concurrency limiting
+        function runPerFileEmitter() {
             emitter.on('job', (job) => {
-                const inPath = job.in
-                    ? (job.in.path ?? null)
-                    : null;
-                const outPath = job.out?.path ?? null;
-                const outMtime = job.out?.mtime;
-                outputctl.debug(`GOT JOB ${inPath ?? 'null'} ${outPath ?? 'null'}`);
-                // Close the original streams immediately - we'll create fresh ones when processing
-                if (job.in != null) {
-                    ;
-                    job.in.destroy();
-                }
-                if (job.out != null) {
-                    job.out.destroy();
-                }
-                // Add job to queue - p-queue handles concurrency automatically
+                const inPath = job.inputPath;
+                const outputPlan = job.out;
+                const outputToken = reserveWatchJobToken(outputPlan?.path ?? null);
+                outputctl.debug(`GOT JOB ${inPath ?? 'null'} ${outputPlan?.path ?? 'null'}`);
                 queue
                     .add(async () => {
-                    const result = await processAssemblyJob(inPath, outPath, outMtime);
+                    const result = await processAssemblyJob(inPath, outputPlan, outputToken);
                     if (result !== undefined) {
                         results.push(result);
                     }
@@ -927,18 +1105,18 @@ export async function create(outputctl, client, { steps, template, fields, watch
                     outputctl.error(err);
                 });
             });
-            emitter.on('error', (err) => {
-                abortController.abort();
-                queue.clear();
-                outputctl.error(err);
-                reject(err);
-            });
             emitter.on('end', async () => {
-                // Wait for all queued jobs to complete
                 await queue.onIdle();
-                resolve({ results, hasFailures });
+                resolve({ resultUrls, results, hasFailures });
             });
         }
+        emitter.on('error', handleEmitterError);
+        if (singleAssembly) {
+            runSingleAssemblyEmitter();
+        }
+        else {
+            runPerFileEmitter();
+        }
     });
 }
 // --- Command classes ---
@@ -977,34 +1155,20 @@ export class AssembliesCreateCommand extends AuthenticatedCommand {
     template = Option.String('--template,-t', {
         description: 'Specify a template to use for these assemblies',
     });
-    inputs = Option.Array('--input,-i', {
-        description: 'Provide an input file or a directory',
-    });
+    inputs = inputPathsOption();
     outputPath = Option.String('--output,-o', {
         description: 'Specify an output file or directory',
     });
     fields = Option.Array('--field,-f', {
         description: 'Set a template field (KEY=VAL)',
     });
-    watch = Option.Boolean('--watch,-w', false, {
-        description: 'Watch inputs for changes',
-    });
-    recursive = Option.Boolean('--recursive,-r', false, {
-        description: 'Enumerate input directories recursively',
-    });
-    deleteAfterProcessing = Option.Boolean('--delete-after-processing,-d', false, {
-        description: 'Delete input files after they are processed',
-    });
-    reprocessStale = Option.Boolean('--reprocess-stale', false, {
-        description: 'Process inputs even if output is newer',
-    });
-    singleAssembly = Option.Boolean('--single-assembly', false, {
-        description: 'Pass all input files to a single assembly instead of one assembly per file',
-    });
-    concurrency = Option.String('--concurrency,-c', {
-        description: 'Maximum number of concurrent assemblies (default: 5)',
-        validator: t.isNumber(),
-    });
+    watch = watchOption();
+    recursive = recursiveOption();
+    deleteAfterProcessing = deleteAfterProcessingOption();
+    reprocessStale = reprocessStaleOption();
+    singleAssembly = singleAssemblyOption();
+    concurrency = concurrencyOption();
+    printUrls = printUrlsOption();
     async run() {
         if (!this.steps && !this.template) {
             this.output.error('assemblies create requires exactly one of either --steps or --template');
@@ -1015,34 +1179,29 @@ export class AssembliesCreateCommand extends AuthenticatedCommand {
             return 1;
         }
         const inputList = this.inputs ?? [];
-        if (inputList.length === 0 && this.watch) {
-            this.output.error('assemblies create --watch requires at least one input');
-            return 1;
-        }
         // Default to stdin only for `--steps` mode (common "pipe a file into a one-off assembly" use case).
         // For `--template` mode, templates may be inputless or use /http/import, so stdin should be explicit (`--input -`).
         if (this.steps && inputList.length === 0 && !process.stdin.isTTY) {
             inputList.push('-');
         }
-        const fieldsMap = {};
-        for (const field of this.fields ?? []) {
-            const eqIndex = field.indexOf('=');
-            if (eqIndex === -1) {
-                this.output.error(`invalid argument for --field: '${field}'`);
-                return 1;
-            }
-            const key = field.slice(0, eqIndex);
-            const value = field.slice(eqIndex + 1);
-            fieldsMap[key] = value;
+        const fieldsMap = parseTemplateFieldAssignments(this.output, this.fields);
+        if (this.fields != null && fieldsMap == null) {
+            return 1;
         }
-        if (this.singleAssembly && this.watch) {
-            this.output.error('--single-assembly cannot be used with --watch');
+        const sharedValidationError = validateSharedFileProcessingOptions({
+            explicitInputCount: this.inputs?.length ?? 0,
+            singleAssembly: this.singleAssembly,
+            watch: this.watch,
+            watchRequiresInputsMessage: 'assemblies create --watch requires at least one input',
+        });
+        if (sharedValidationError != null) {
+            this.output.error(sharedValidationError);
             return 1;
         }
-        const { hasFailures } = await create(this.output, this.client, {
+        const { hasFailures, resultUrls } = await create(this.output, this.client, {
             steps: this.steps,
             template: this.template,
-            fields: fieldsMap,
+            fields: fieldsMap ?? {},
             watch: this.watch,
             recursive: this.recursive,
             inputs: inputList,
@@ -1050,8 +1209,11 @@ export class AssembliesCreateCommand extends AuthenticatedCommand {
             del: this.deleteAfterProcessing,
             reprocessStale: this.reprocessStale,
             singleAssembly: this.singleAssembly,
-            concurrency: this.concurrency,
+            concurrency: this.concurrency == null ? undefined : Number(this.concurrency),
         });
+        if (this.printUrls) {
+            printResultUrls(this.output, resultUrls);
+        }
         return hasFailures ? 1 : undefined;
     }
 }
@@ -1176,19 +1338,12 @@ export class AssembliesReplayCommand extends AuthenticatedCommand {
     });
     assemblyIds = Option.Rest({ required: 1 });
     async run() {
-        const fieldsMap = {};
-        for (const field of this.fields ?? []) {
-            const eqIndex = field.indexOf('=');
-            if (eqIndex === -1) {
-                this.output.error(`invalid argument for --field: '${field}'`);
-                return 1;
-            }
-            const key = field.slice(0, eqIndex);
-            const value = field.slice(eqIndex + 1);
-            fieldsMap[key] = value;
+        const fieldsMap = parseTemplateFieldAssignments(this.output, this.fields);
+        if (this.fields != null && fieldsMap == null) {
+            return 1;
         }
         await replay(this.output, this.client, {
-            fields: fieldsMap,
+            fields: fieldsMap ?? {},
             reparse: this.reparseTemplate,
             steps: this.steps,
             notify_url: this.notifyUrl,