animader-cli 0.0.0-stage → 0.1.1

package/src/commands/doctor.mjs

@@ -0,0 +1,348 @@
+// The `animader doctor` command: host checks (node against the package
+// engines, platform and architecture, and the artifacts the dev command
+// needs in this source workspace) and, with a folder, the shared
+// animader.json resolution plus the demo's real project inspection. Every
+// failed check prints its problem and an actionable remedy, naming the file
+// it belongs to. Doctor never claims WebGPU, audio decoding or playback:
+// those need a real browser test, and its own output says so.
+//
+// Contributor-mode artifact paths default to the workspace roots
+// (toolchain/prepare.mjs) and demo/vendor, exactly what the dev command
+// uses in contributor mode. Installed mode (stage 2 of the
+// installed-toolchain plan) resolves them through the toolchain descriptor.
+
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import pkg from '../../package.json' with { type: 'json' };
+import { createNodeIo } from '../../adapters/node-fs.mjs';
+import { inspectProject } from '../../lib/contract.mjs';
+import { DemoError, projectError, usageError } from '../../lib/errors.mjs';
+import { resolveToolchain } from '../toolchain.mjs';
+import { PROJECT_CONFIG_FORMAT, PROJECT_CONFIG_NAME, resolveProjectConfig } from '../config.mjs';
+
+// Contributor-workspace defaults for doctor's artifact checks: the vendored
+// runtime under the checkout's demo/ and the package's own player page.
+// Installed mode (stage 2 of the installed-toolchain plan) replaces these
+// with the toolchain descriptor's package-resolved artifacts.
+const REPO_ROOT = fileURLToPath(new URL('../../../../', import.meta.url));
+const PKG_ROOT = fileURLToPath(new URL('../../', import.meta.url));
+
+const INSPECTED_INPUTS_SUMMARY = 'program.sjon, timeline.piece.sjon, exactly one recognized soundtrack, out/ usable';
+
+/**
+ * Parse the `animader doctor` argv without touching the filesystem.
+ *
+ * @param {string[]} argv
+ * @returns {{help: boolean, folder: string|null, secondsRaw: string|undefined}}
+ */
+export function parseDoctorArgv(argv) {
+  if (!Array.isArray(argv)) {
+    throw usageError('invalid_argv', 'the CLI adapter must pass an argument array', 'Call animader doctor [folder] [--seconds S]');
+  }
+
+  let folder = null;
+  let secondsRaw;
+  let help = false;
+  let endOptions = false;
+
+  for (let index = 0; index < argv.length; index++) {
+    const argument = String(argv[index]);
+    if (!endOptions && argument === '--') {
+      endOptions = true;
+      continue;
+    }
+    if (!endOptions && (argument === '--help' || argument === '-h')) {
+      help = true;
+      continue;
+    }
+    if (!endOptions && argument.startsWith('--')) {
+      const equals = argument.indexOf('=');
+      const name = equals === -1 ? argument : argument.slice(0, equals);
+      const inline = equals === -1 ? undefined : argument.slice(equals + 1);
+      if (name === '--seconds') {
+        if (inline !== undefined) {
+          secondsRaw = inline;
+        } else {
+          if (index + 1 >= argv.length) {
+            throw usageError('missing_option_value', `${name} needs a value`, 'Pass --seconds <n>, for example --seconds 8');
+          }
+          index++;
+          secondsRaw = String(argv[index]);
+        }
+      } else {
+        throw usageError(
+          'unknown_option',
+          `unknown option ${name}`,
+          'The supported options are --seconds and --help; use --help for usage.',
+        );
+      }
+      continue;
+    }
+    if (!endOptions && argument.startsWith('-') && argument !== '-') {
+      throw usageError(
+        'unknown_option',
+        `unknown option ${argument}`,
+        'The supported options are --seconds and --help; use --help for usage.',
+      );
+    }
+    if (folder !== null) {
+      throw usageError('extra_argument', `extra folder argument ${JSON.stringify(argument)}`, 'Pass at most one project folder');
+    }
+    folder = argument;
+  }
+
+  return { help, folder, secondsRaw };
+}
+
+export function doctorUsageText() {
+  return [
+    'animader doctor — report host and project health',
+    '',
+    'Usage:',
+    '  animader doctor [folder] [--seconds S]',
+    '',
+    'Without a folder, doctor checks the host: the node version against the',
+    "package engines, the platform and architecture, and whether the",
+    'artifacts the dev command needs are present in this source workspace.',
+    'With a folder, it also resolves animader.json and inspects the real',
+    'project inputs.',
+    '',
+    'Options:',
+    '  --seconds S   explicit host duration for a project whose config does',
+    '                not set one (precedence over animader.json)',
+    '  -h, --help    this text',
+    '',
+    'Doctor never claims WebGPU, audio decoding or playback: those need a',
+    'real browser test.',
+  ].join('\n');
+}
+
+function versionTriple(text, pattern) {
+  const match = pattern.exec(String(text).trim());
+  if (!match) return null;
+  // A range's absent minor/patch (`>=22`) means zero, not NaN: Number(undefined)
+  // is NaN, and any comparison against NaN is false, which made doctor reject
+  // exactly the versions the range admits.
+  return [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)];
+}
+
+/**
+ * Compare a node version against an engines range. Understands the
+ * `>=major[.minor[.patch]]` form this package ships. Returns true, false,
+ * or null when either side is not comparable.
+ */
+export function satisfiesNodeRange(nodeVersion, range) {
+  const floor = versionTriple(range, /^>=(\d+)(?:\.(\d+))?(?:\.(\d+))?$/);
+  const current = versionTriple(nodeVersion, /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  if (!floor || !current) return null;
+  for (let index = 0; index < 3; index++) {
+    if (current[index] !== floor[index]) return current[index] > floor[index];
+  }
+  return true;
+}
+
+async function statIsFile(io, path) {
+  const stats = await io.statFile(path);
+  return stats !== null && stats.isFile;
+}
+
+/**
+ * Run `animader doctor`. Prints one line per check (`ok: …`), a `fail: …`
+ * line plus an indented remedy for each failed check, and always closes
+ * with the browser-boundary note. Throws the named `doctor_failed` project
+ * error when any check failed, so the process exits non-zero.
+ *
+ * @param {string[]} argv
+ * @param {{out: (line: string) => void, io?: object, env?: object,
+ *          nodeVersion?: string, platform?: string, arch?: string,
+ *          engines?: object, pnginePath?: string, vendorProvenance?: string,
+ *          vendorRoot?: string, playerIndex?: string, toolchain?: object}} context
+ */
+export async function run(argv, context) {
+  const args = parseDoctorArgv(argv);
+  if (args.help) {
+    context.out(doctorUsageText());
+    return;
+  }
+
+  const io = context.io ?? createNodeIo();
+  const out = context.out;
+  const env = context.env ?? process.env;
+  const nodeVersion = context.nodeVersion ?? process.version;
+  const platform = context.platform ?? process.platform;
+  const arch = context.arch ?? process.arch;
+  const engines = context.engines ?? pkg.engines ?? {};
+  const toolchain = context.toolchain ?? await resolveToolchain({ env });
+  const pnginePath = context.pnginePath ?? toolchain.pngine.cli;
+  const vendorProvenance = context.vendorProvenance
+    ?? join(context.vendorRoot ?? join(REPO_ROOT, 'demo', 'vendor'), 'provenance.json');
+  const playerIndex = context.playerIndex ?? join(PKG_ROOT, 'player', 'index.html');
+
+  const results = [];
+  const check = (ok, text, remedy) => results.push({ ok, text, remedy });
+
+  // --- host checks -------------------------------------------------------
+  const satisfied = satisfiesNodeRange(nodeVersion, engines.node);
+  if (satisfied === null) {
+    check(
+      false,
+      `node ${nodeVersion} cannot be compared against engines node ${JSON.stringify(engines.node ?? null)}`,
+      `Set engines.node to a ">=major[.minor[.patch]]" range this doctor understands; ${JSON.stringify(engines.node ?? null)} is not one.`,
+    );
+  } else if (satisfied) {
+    check(true, `node ${nodeVersion} satisfies engines node ${JSON.stringify(engines.node)}`);
+  } else {
+    check(
+      false,
+      `node ${nodeVersion} does not satisfy engines node ${JSON.stringify(engines.node)}`,
+      'Use Node 22 or newer; the supported baseline is the CLI package\'s engines field.',
+    );
+  }
+  check(
+    true,
+    toolchain.mode === 'installed'
+      ? `platform ${platform} on ${arch} (installed toolchain target ${toolchain.target.os}-${toolchain.target.arch})`
+      : `platform ${platform} on ${arch} (the release matrix is a release-time gate, not a contributor-mode one)`,
+  );
+
+  // The toolchain identity and its artifacts. Contributor mode checks the
+  // workspace's own files (the pngine CLI path, the prepared bundle, the
+  // package's player page); installed mode resolves every artifact through
+  // the toolchain descriptor and verifies it against the release manifest,
+  // so a missing or tampered dependency names the package to install.
+  check(true, `toolchain ${toolchain.identity}`);
+  if (toolchain.mode === 'installed') {
+    try {
+      const verified = await toolchain.verifyRuntime();
+      check(true, `installed runtime verified: ${verified.files.length} files, digest ${verified.digest}`);
+    } catch (error) {
+      check(false, error.message, error.remedy);
+    }
+    try {
+      const tools = await toolchain.verifyTools();
+      for (const row of tools.tools) {
+        check(true, `${row.name} present at ${row.path} (${row.bytes} bytes, sha256 ${row.sha256})`);
+      }
+    } catch (error) {
+      check(false, error.message, error.remedy);
+    }
+    try {
+      const esbuild = toolchain.esbuild.require();
+      const pinned = toolchain.versions.esbuild;
+      if (typeof esbuild.version === 'string' && pinned !== null && esbuild.version !== pinned) {
+        check(
+          false,
+          `esbuild ${esbuild.version} is installed but the release manifest pins ${pinned}`,
+          'Reinstall animader-cli so its pinned esbuild dependency is installed exactly.',
+        );
+      } else {
+        check(true, `esbuild ${esbuild.version} matches the pinned ${pinned ?? esbuild.version}`);
+      }
+    } catch (error) {
+      check(false, error.message, error.remedy);
+    }
+  } else {
+    if (await statIsFile(io, pnginePath)) {
+      check(true, `pngine CLI present at ${pnginePath}`);
+    } else {
+      check(
+        false,
+        `pngine CLI not found at ${pnginePath}`,
+        'Build pngine in its checkout or point PNGINE at the binary; the dev command needs it.',
+      );
+    }
+
+    if (await statIsFile(io, vendorProvenance)) {
+      check(true, `prepared runtime bundle present at ${vendorProvenance}`);
+    } else {
+      check(
+        false,
+        `prepared runtime bundle not found at ${vendorProvenance}`,
+        'Run node demo/prepare.mjs to fill demo/vendor from the built producers.',
+      );
+    }
+  }
+
+  if (await statIsFile(io, playerIndex)) {
+    check(true, `player page present at ${playerIndex}`);
+  } else {
+    check(
+      false,
+      `player page not found at ${playerIndex}`,
+      'Restore the tracked demo/player page files; the dev server serves them.',
+    );
+  }
+
+  // --- project checks ----------------------------------------------------
+  if (args.folder !== null && args.folder !== '') {
+    const folder = args.folder;
+    let stats = null;
+    try {
+      stats = await io.statFile(folder);
+    } catch (error) {
+      check(false, `could not inspect the project folder ${folder}: ${error?.message ?? String(error)}`, 'Check the folder path and its permissions.');
+    }
+    if (stats === null) {
+      check(false, `the project folder does not exist: ${folder}`, 'Pass the folder that holds the project files (created by animader new).');
+    } else if (!stats.isDirectory) {
+      check(false, `the project folder is not a directory: ${folder}`, 'Pass the project folder itself, not a file.');
+    } else {
+      const configPath = `${String(folder).replace(/[\\/]+$/, '')}/${PROJECT_CONFIG_NAME}`;
+      const configStats = await io.statFile(configPath);
+      if (configStats !== null && !configStats.isFile) {
+        check(false, `${PROJECT_CONFIG_NAME} is not a regular file in ${folder}`, `Replace ${configPath} with a regular file.`);
+      } else {
+        let configBytes = null;
+        if (configStats !== null) {
+          try {
+            configBytes = await io.readFile(configPath);
+          } catch (error) {
+            check(false, `could not read ${configPath}: ${error?.message ?? String(error)}`, 'Check the file\'s permissions.');
+          }
+        }
+        if (configBytes !== null || configStats === null) {
+          try {
+            const resolved = await resolveProjectConfig({ folder, configBytes, overrideSeconds: args.secondsRaw });
+            check(
+              true,
+              configStats !== null
+                ? `${PROJECT_CONFIG_NAME} resolves: ${PROJECT_CONFIG_FORMAT}, seconds ${resolved.seconds}`
+                : `${PROJECT_CONFIG_NAME} is absent; --seconds ${resolved.seconds} supplies the host duration`,
+            );
+          } catch (error) {
+            check(false, error.message, error.remedy);
+          }
+        }
+      }
+
+      try {
+        await inspectProject({ folder, io });
+        check(true, `project inputs (${INSPECTED_INPUTS_SUMMARY})`);
+      } catch (error) {
+        if (error instanceof DemoError && error.remedy) check(false, error.message, error.remedy);
+        else check(false, `could not inspect ${folder}: ${error?.message ?? String(error)}`, 'Check the folder\'s permissions and contents.');
+      }
+    }
+  }
+
+  // --- output and verdict -------------------------------------------------
+  for (const result of results) {
+    if (result.ok) {
+      out(`ok: ${result.text}`);
+    } else {
+      out(`fail: ${result.text}`);
+      if (result.remedy) out(`  remedy: ${result.remedy}`);
+    }
+  }
+  out('note: WebGPU, audio decoding and playback are not checked here; they need a real browser test.');
+
+  const failures = results.filter((result) => !result.ok).length;
+  if (failures > 0) {
+    throw projectError(
+      'doctor_failed',
+      `${failures} of ${results.length} checks failed`,
+      'Fix the failing checks above and run animader doctor again.',
+    );
+  }
+}

package/src/commands/export.mjs

@@ -0,0 +1,158 @@
+// The `animader export` command: its argv grammar and path rules. The work
+// is the demo's real export operation (runExport): inspect the project,
+// resolve --out from the invocation directory, refuse outputs that alias
+// authored inputs, and run the staged release export over the real
+// producers. The output folder must be fresh; there is no --force.
+//
+// The export operation is the package's own adapters/export-run.mjs
+// (installed-toolchain plan, stage 1).
+
+import { createNodeIo } from '../../adapters/node-fs.mjs';
+import { usageError } from '../../lib/errors.mjs';
+import { runExport } from '../../adapters/export-run.mjs';
+import { resolveToolchain } from '../toolchain.mjs';
+import { commandFolder, resolveConfiguredSeconds } from './project.mjs';
+
+/**
+ * Parse the `animader export` argv without touching the filesystem.
+ *
+ * @param {string[]} argv
+ * @returns {{help: boolean, folder: string|null, secondsRaw: string|undefined,
+ *            out: string|null}}
+ */
+export function parseExportCommandArgv(argv) {
+  if (!Array.isArray(argv)) {
+    throw usageError('invalid_argv', 'the CLI adapter must pass an argument array', 'Call animader export [folder] --out OUT [--seconds S]');
+  }
+
+  let folder = null;
+  let secondsRaw;
+  let out = null;
+  let help = false;
+  let endOptions = false;
+
+  for (let index = 0; index < argv.length; index++) {
+    const argument = String(argv[index]);
+    if (!endOptions && argument === '--') {
+      endOptions = true;
+      continue;
+    }
+    if (!endOptions && (argument === '--help' || argument === '-h')) {
+      help = true;
+      continue;
+    }
+    if (!endOptions && argument.startsWith('--')) {
+      const equals = argument.indexOf('=');
+      const name = equals === -1 ? argument : argument.slice(0, equals);
+      const inline = equals === -1 ? undefined : argument.slice(equals + 1);
+      const takeValue = () => {
+        if (inline !== undefined) return inline;
+        if (index + 1 >= argv.length) {
+          throw usageError('missing_option_value', `${name} needs a value`, `Pass ${name} <value>`);
+        }
+        index++;
+        return String(argv[index]);
+      };
+      if (name === '--seconds') {
+        secondsRaw = takeValue();
+      } else if (name === '--out') {
+        out = takeValue();
+      } else {
+        throw usageError(
+          'unknown_option',
+          `unknown option ${name}`,
+          'The supported options are --out, --seconds and --help; an existing target is refused.',
+        );
+      }
+      continue;
+    }
+    if (!endOptions && argument.startsWith('-') && argument !== '-') {
+      throw usageError(
+        'unknown_option',
+        `unknown option ${argument}`,
+        'The supported options are --out, --seconds and --help; an existing target is refused.',
+      );
+    }
+    if (folder !== null) {
+      throw usageError('extra_argument', `extra folder argument ${JSON.stringify(argument)}`, 'Pass at most one project folder');
+    }
+    folder = argument;
+  }
+
+  if (help) {
+    return { help: true, folder, secondsRaw, out };
+  }
+  if (out === null || out === '') {
+    throw usageError('missing_out', '--out is required', 'Pass the release folder, for example --out dist');
+  }
+  return { help: false, folder, secondsRaw, out };
+}
+
+export function exportCommandUsageText() {
+  return [
+    'animader export — write a standalone release to a fresh output folder',
+    '',
+    'Usage:',
+    '  animader export [folder] --out OUT [--seconds S]',
+    '',
+    'The folder is the project folder relative to the invocation directory',
+    '(default: the current directory; parent folders are never searched).',
+    'A relative --out resolves from the invocation directory, not from the',
+    'project: `animader export ./my-demo --out ./release` writes ./release.',
+    'The resolved output path is printed.',
+    '',
+    'The output folder must not exist (including a symlink); this slice has',
+    'no --force and never overwrites. The release is staged beside OUT and',
+    'one rename publishes it; an existing OUT.next staging path is refused,',
+    'never deleted. Outputs that alias authored project files (the project',
+    'folder itself, its parents, or paths inside authored folders) are',
+    'refused.',
+    '',
+    'Options:',
+    '  --out OUT     required release folder; it must not exist',
+    `  --seconds S   explicit host duration, a positive number at most 600`,
+    '                (wins over animader.json only after it validates)',
+    '  -h, --help    this text',
+    '',
+    'A successful export also writes a detached OUT.size.json beside OUT.',
+  ].join('\n');
+}
+
+/**
+ * Run `animader export` through the demo's export operation. The context may
+ * inject `producer` (the whole release producer) or `producers` (the build
+ * stage ports inside prepareRelease) for tests; the default is the real
+ * vendored producer chain, which fails loudly where the prepared runtime is
+ * absent.
+ *
+ * @param {string[]} argv
+ * @param {{out: (line: string) => void, err: (line: string) => void,
+ *          io?: object, producer?: object, producers?: object,
+ *          toolchain?: object}} context
+ */
+export async function run(argv, context) {
+  const args = parseExportCommandArgv(argv);
+  if (args.help) {
+    context.out(exportCommandUsageText());
+    return;
+  }
+
+  const folder = commandFolder(args);
+  const { seconds } = await resolveConfiguredSeconds({
+    folder,
+    secondsRaw: args.secondsRaw,
+    io: context.io ?? createNodeIo(),
+  });
+
+  await runExport({
+    folder,
+    seconds,
+    out: args.out,
+    title: 'animader export',
+    say: context.out,
+    warn: context.err,
+    producer: context.producer,
+    producers: context.producers,
+    toolchain: context.toolchain ?? await resolveToolchain(),
+  });
+}

package/src/commands/new.mjs

@@ -0,0 +1,164 @@
+// The `animader new` command: its argv grammar and short success output.
+// The creation decisions (starter registry, emptiness refusal, atomic
+// per-file writes, partial-write honesty) are the demo's portable
+// lib/new.mjs; symlink resolution and the starter-source refusal are the
+// demo's target adapter. There is no server and no package installation as
+// a side effect.
+//
+// The starter sources and portable creation decisions are the package's own
+// lib/new.mjs and starters/ (installed-toolchain plan, stage 1).
+
+import { fileURLToPath } from 'node:url';
+
+import { createNodeIo } from '../../adapters/node-fs.mjs';
+import { refuseStarterSource, resolveTargetFolder } from '../../adapters/target.mjs';
+import { PROJECT_FILES } from '../../lib/contract.mjs';
+import { usageError } from '../../lib/errors.mjs';
+import { STARTER_NAMES, createProject, shellQuote } from '../../lib/new.mjs';
+
+const DEFAULT_STARTER = 'circle';
+
+function starterList() {
+  return STARTER_NAMES.join(', ');
+}
+
+/**
+ * Parse the `animader new` argv without touching the filesystem. The
+ * grammar matches the demo's `new`, with circle as the default starter.
+ *
+ * @param {string[]} argv
+ * @returns {{help: boolean, folder: string|null, starter: string}}
+ */
+export function parseNewCommandArgv(argv) {
+  if (!Array.isArray(argv)) {
+    throw usageError('invalid_argv', 'the CLI adapter must pass an argument array', 'Call animader new <folder> [--starter circle|ember]');
+  }
+
+  let folder = null;
+  let starter = DEFAULT_STARTER;
+  let help = false;
+  let endOptions = false;
+
+  for (let index = 0; index < argv.length; index++) {
+    const argument = String(argv[index]);
+    if (!endOptions && argument === '--') {
+      endOptions = true;
+      continue;
+    }
+    if (!endOptions && (argument === '--help' || argument === '-h')) {
+      help = true;
+      continue;
+    }
+    if (!endOptions && argument.startsWith('--')) {
+      const equals = argument.indexOf('=');
+      const name = equals === -1 ? argument : argument.slice(0, equals);
+      const inline = equals === -1 ? undefined : argument.slice(equals + 1);
+      if (name === '--starter') {
+        if (inline !== undefined) {
+          starter = inline;
+        } else {
+          if (index + 1 >= argv.length) {
+            throw usageError('missing_option_value', `${name} needs a value`, `Pass ${name} ${starterList()}`);
+          }
+          index++;
+          starter = String(argv[index]);
+        }
+      } else {
+        throw usageError(
+          'unknown_option',
+          `unknown option ${name}`,
+          `The supported option is --starter (available: ${starterList()}); use --help for usage.`,
+        );
+      }
+      continue;
+    }
+    if (!endOptions && argument.startsWith('-') && argument !== '-') {
+      throw usageError(
+        'unknown_option',
+        `unknown option ${argument}`,
+        `The supported option is --starter (available: ${starterList()}); use --help for usage.`,
+      );
+    }
+    if (folder !== null) {
+      throw usageError('extra_argument', `extra folder argument ${JSON.stringify(argument)}`, 'Pass exactly one project folder');
+    }
+    folder = argument;
+  }
+
+  if (help) return { help: true, folder, starter };
+  if (folder === null || folder === '') {
+    throw usageError(
+      'missing_folder',
+      'exactly one project folder is required',
+      'Run: animader new <folder> [--starter circle|ember]',
+    );
+  }
+  if (!STARTER_NAMES.includes(starter)) {
+    throw usageError(
+      'unknown_starter',
+      `unknown starter ${JSON.stringify(starter)}`,
+      `Available starters: ${starterList()}`,
+    );
+  }
+  return { help: false, folder, starter };
+}
+
+export function newCommandUsageText() {
+  return [
+    'animader new — create an editable project from a tracked starter',
+    '',
+    'Usage:',
+    '  animader new <folder> [--starter circle|ember]',
+    '',
+    'The folder must not exist, or must be an empty directory. The default',
+    'starter is circle: one circle kernel, an eight-second path with beat',
+    'pulses, a complete timeline and the labeled test tone. The ember',
+    'starter stays available explicitly.',
+    '',
+    'Files:',
+    `  ${PROJECT_FILES.program}`,
+    `  ${PROJECT_FILES.timeline}`,
+    '  animader.json',
+    '  kernels/circle.wgsl',
+    `  ${PROJECT_FILES.soundtrack}   generated 8.0 s labeled test tone; replace with your audio`,
+    '  .gitignore',
+    '  README.md',
+    '',
+    'Options:',
+    `  --starter NAME   starter to copy (default: circle; available: ${starterList()})`,
+    "  --               end options; the next argument is the folder even if it starts with '-'",
+    '  -h, --help       this text',
+    '',
+    'A folder symlink is followed. A target inside the tracked starter',
+    'source is refused.',
+  ].join('\n');
+}
+
+/**
+ * Run `animader new`. Short success output only: the created location, the
+ * working next command, and the first file to edit. Hashes and tool
+ * details stay in diagnostics, not creation output.
+ *
+ * @param {string[]} argv
+ * @param {{out: (line: string) => void, io?: object}} context
+ */
+export async function run(argv, context) {
+  const args = parseNewCommandArgv(argv);
+  if (args.help) {
+    context.out(newCommandUsageText());
+    return;
+  }
+
+  const folder = await resolveTargetFolder(args.folder);
+  await refuseStarterSource(folder, args.starter);
+
+  const result = await createProject({
+    folder,
+    starter: args.starter,
+    io: context.io ?? createNodeIo(),
+  });
+
+  context.out(`created: ${result.folder} (${result.starter} starter)`);
+  context.out(`next: animader dev ${shellQuote(result.folder)}`);
+  context.out(`first file to edit: ${PROJECT_FILES.program} (README.md explains the three authored files)`);
+}