animader-cli 0.0.0-stage → 0.1.1

package/src/commands/project.mjs

@@ -0,0 +1,46 @@
+// Shared resolution for the project commands (dev/build/export): the
+// project folder relative to the invocation directory and one validated
+// animader.json reading. Precedence is the config module's own rule — an
+// explicit --seconds wins only after a present config has fully validated,
+// so an override can never conceal malformed JSON or an unsupported version.
+
+import { createNodeIo } from '../../adapters/node-fs.mjs';
+import { projectError } from '../../lib/errors.mjs';
+import { PROJECT_CONFIG_NAME, resolveProjectConfig } from '../config.mjs';
+
+/**
+ * The project folder a project command operates on: the explicit positional,
+ * else the invocation directory itself. No parent search happens here or
+ * anywhere else — a project is where the command is pointed.
+ *
+ * @param {{folder: string|null}} args the parsed command argv
+ * @returns {string}
+ */
+export function commandFolder(args) {
+  return args.folder ?? '.';
+}
+
+/**
+ * Read and resolve animader.json for one command run.
+ *
+ * @param {Object} options
+ * @param {string} options.folder the project folder
+ * @param {string|undefined} options.secondsRaw the raw --seconds value
+ * @param {object} [options.io] the injected filesystem port (statFile, readFile)
+ * @returns {Promise<{seconds: number}>}
+ */
+export async function resolveConfiguredSeconds({ folder, secondsRaw, io }) {
+  const effectiveIo = io ?? createNodeIo();
+  const configPath = `${String(folder).replace(/[\\/]+$/, '')}/${PROJECT_CONFIG_NAME}`;
+  const stats = await effectiveIo.statFile(configPath);
+  if (stats !== null && !stats.isFile) {
+    throw projectError(
+      'config_not_file',
+      `${PROJECT_CONFIG_NAME} is not a regular file in ${folder}`,
+      `Replace ${configPath} with a regular file.`,
+    );
+  }
+  const configBytes = stats === null ? null : await effectiveIo.readFile(configPath);
+  const resolved = await resolveProjectConfig({ folder, configBytes, overrideSeconds: secondsRaw });
+  return { seconds: resolved.seconds };
+}

package/src/config.mjs

@@ -0,0 +1,110 @@
+// The shared animader.json resolution rules: one reader of the authored
+// project config for new/doctor now and dev/build/export later. This module
+// is portable: no `node:` import and no process state — config bytes in, one
+// frozen resolved object out; reading the file and spawning are host work.
+//
+// Rules (plan "Project format and defaults"): the file is animader.json at
+// the project root, format animader-project/1, host settings only (seconds
+// here, never tempo/lanes/length). Precedence is an explicit CLI option over
+// the project config — but a present config validates first, so an override
+// can never hide malformed JSON, an unsupported version or an unknown key.
+//
+// The duration bound, the --seconds wording and the error vocabulary are the
+// package's own lib (contract.mjs, errors.mjs); installed-toolchain plan,
+// stage 1 moved them into the package. The
+// installed-toolchain boundary is plan section 2 and is not in this
+// dispatch.
+
+import { MAX_SECONDS, parseSeconds } from '../lib/contract.mjs';
+import { projectError } from '../lib/errors.mjs';
+
+export const PROJECT_CONFIG_NAME = 'animader.json';
+export const PROJECT_CONFIG_FORMAT = 'animader-project/1';
+
+const CONFIG_KEYS = Object.freeze(['format', 'seconds']);
+const RANGE_WORDS = `a positive number at most ${MAX_SECONDS}`;
+
+const DECODER = new TextDecoder();
+
+function configPath(folder) {
+  return `${String(folder).replace(/[\\/]+$/, '')}/${PROJECT_CONFIG_NAME}`;
+}
+
+function assertConfigSeconds(value, path) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > MAX_SECONDS) {
+    throw projectError(
+      'invalid_config_seconds',
+      `seconds in ${path} must be ${RANGE_WORDS}; got ${JSON.stringify(value) ?? String(value)}`,
+      `Set seconds in ${path} to ${RANGE_WORDS}, for example 8.`,
+    );
+  }
+}
+
+/**
+ * Resolve and validate the authored project config.
+ *
+ * @param {Object} options
+ * @param {string} options.folder the project folder, for file-specific errors
+ * @param {Uint8Array|null|undefined} options.configBytes the raw animader.json
+ *   bytes, or null/undefined when the file is absent
+ * @param {string|number|undefined} [options.overrideSeconds] the explicit CLI
+ *   --seconds value, parsed with the demo's own rules when present
+ * @returns {{seconds: number}} the one resolved object consumers receive
+ */
+export async function resolveProjectConfig({ folder, configBytes, overrideSeconds }) {
+  const path = configPath(folder);
+
+  let document = null;
+  let present = false;
+  if (configBytes !== null && configBytes !== undefined) {
+    present = true;
+    try {
+      document = JSON.parse(DECODER.decode(configBytes));
+    } catch (error) {
+      throw projectError(
+        'invalid_config_json',
+        `${path} is not valid JSON: ${error?.message ?? String(error)}`,
+        `Fix the JSON syntax in ${path}; the file must hold one JSON object.`,
+      );
+    }
+    if (document === null || typeof document !== 'object' || Array.isArray(document)) {
+      throw projectError(
+        'config_not_object',
+        `${path} must contain a JSON object; got ${JSON.stringify(document)}`,
+        `Write one JSON object in ${path}, for example {"format": ${JSON.stringify(PROJECT_CONFIG_FORMAT)}, "seconds": 8}.`,
+      );
+    }
+    if (document.format !== PROJECT_CONFIG_FORMAT) {
+      throw projectError(
+        'unsupported_config_format',
+        `${path} names format ${JSON.stringify(document.format ?? null)}; this tool supports ${PROJECT_CONFIG_FORMAT} only`,
+        `Set "format" to ${JSON.stringify(PROJECT_CONFIG_FORMAT)} in ${path}.`,
+      );
+    }
+    for (const key of Object.keys(document)) {
+      if (!CONFIG_KEYS.includes(key)) {
+        throw projectError(
+          'unknown_config_setting',
+          `${path} has an unknown setting ${JSON.stringify(key)}; the supported settings are ${CONFIG_KEYS.join(', ')}`,
+          `Remove ${JSON.stringify(key)} from ${path}; tempo, lanes and length live in timeline.piece.sjon.`,
+        );
+      }
+    }
+    if (document.seconds !== undefined) assertConfigSeconds(document.seconds, path);
+  }
+
+  // A present config has fully validated by here, so applying the override
+  // now cannot conceal a malformed or unsupported config.
+  if (overrideSeconds !== undefined) {
+    return Object.freeze({ seconds: parseSeconds(overrideSeconds) });
+  }
+  if (!present || document.seconds === undefined) {
+    const where = present ? `${path} does not set seconds` : `${path} is absent`;
+    throw projectError(
+      'missing_seconds',
+      `seconds is missing: ${where}; no host duration is inferred from audio or timeline length`,
+      `Create ${path} with {"format": ${JSON.stringify(PROJECT_CONFIG_FORMAT)}, "seconds": 8}, or pass --seconds <n> for this run.`,
+    );
+  }
+  return Object.freeze({ seconds: document.seconds });
+}

package/src/router.mjs

@@ -0,0 +1,149 @@
+// The `animader` command table and top-level argv grammar. This module is the
+// seam the later dev/build/export commands slot into: one row here registers a
+// command, and nothing else in the router changes. Parse decisions live here;
+// each command owns its own argv grammar; the bin maps thrown DemoErrors to
+// their exit codes and error:/remedy: lines.
+//
+// The error vocabulary is the package's own lib/errors.mjs (installed-toolchain
+// plan, stage 1). Stage 2 replaces the contributor-workspace toolchain
+// identity below with the installed, versioned toolchain descriptor.
+
+import { usageError } from '../lib/errors.mjs';
+
+/**
+ * The contributor-workspace identity printed by --version. An installed
+ * package (installed-toolchain plan, stage 2) prints the manifest's tested
+ * combination instead: see toolchainIdentity() in src/toolchain.mjs.
+ */
+export const TOOLCHAIN_IDENTITY = 'source workspace (contributor mode)';
+
+// Rows resolve their command module lazily, so a command lands in this
+// dispatch without a router rewrite; each loader returns { run }.
+const COMMANDS = [
+  {
+    name: 'new',
+    summary: 'create an editable project from a tracked starter',
+    load: () => import('./commands/new.mjs'),
+  },
+  {
+    name: 'dev',
+    summary: 'serve a project on loopback, watch edits and reload the page',
+    load: () => import('./commands/dev.mjs'),
+  },
+  {
+    name: 'build',
+    summary: 'run the full build (bake, pack, host audit) into out/',
+    load: () => import('./commands/build.mjs'),
+  },
+  {
+    name: 'export',
+    summary: 'write a standalone release to a fresh --out folder',
+    load: () => import('./commands/export.mjs'),
+  },
+  {
+    name: 'doctor',
+    summary: 'report host and project health, each problem with a remedy',
+    load: () => import('./commands/doctor.mjs'),
+  },
+];
+
+const COMMAND_NAMES = Object.freeze(COMMANDS.map((command) => command.name));
+
+function commandList() {
+  return COMMAND_NAMES.join(', ');
+}
+
+/**
+ * Parse the top-level argv without touching the filesystem. Global options
+ * are only global before the command name; after it, tokens belong to the
+ * command's own grammar.
+ *
+ * @param {string[]} argv
+ * @returns {{kind: 'help'} | {kind: 'version'} | {kind: 'command', name: string, argv: string[]}}
+ */
+export function parseRouterArgv(argv) {
+  if (!Array.isArray(argv)) {
+    throw usageError('invalid_argv', 'the CLI adapter must pass an argument array', 'Call the animader bin with process.argv.slice(2)');
+  }
+
+  for (let index = 0; index < argv.length; index++) {
+    const argument = String(argv[index]);
+    if (argument === '--help' || argument === '-h') return { kind: 'help' };
+    if (argument === '--version') return { kind: 'version' };
+    if (argument.startsWith('-')) {
+      throw usageError(
+        'unknown_option',
+        `unknown option ${argument}`,
+        `The top-level options are --help and --version; run animader --help for the command list`,
+      );
+    }
+    const row = COMMANDS.find((command) => command.name === argument);
+    if (!row) {
+      throw usageError(
+        'unknown_command',
+        `unknown command ${JSON.stringify(argument)}`,
+        `Run animader --help for the command list (available: ${commandList()})`,
+      );
+    }
+    return { kind: 'command', name: row.name, argv: argv.slice(index + 1).map(String) };
+  }
+
+  throw usageError(
+    'missing_command',
+    'a command is required',
+    `Run animader --help for the command list (available: ${commandList()})`,
+  );
+}
+
+export function routerUsageText() {
+  return [
+    'animader — create, check and run Animader projects',
+    '',
+    'Usage:',
+    '  animader <command> [arguments]',
+    '',
+    'Commands:',
+    ...COMMANDS.map((command) => `  animader ${command.name.padEnd(8)} ${command.summary}`),
+    '',
+    'Options:',
+    '  --help, -h     this text',
+    '  --version      print the CLI version and the toolchain identity',
+    '',
+    "Run `animader <command> --help` for that command's options.",
+  ].join('\n');
+}
+
+/** The two --version lines: the CLI version and one toolchain identity. */
+export function versionLines({ version, identity = TOOLCHAIN_IDENTITY }) {
+  return [
+    `animader-cli ${version}`,
+    `toolchain: ${identity}`,
+  ];
+}
+
+/**
+ * Dispatch parsed argv: print help/version through the context, or load and
+ * run the named command. The context carries everything host-shaped:
+ * `version`, `out`/`err` line writers, the filesystem `io`, and `env`.
+ *
+ * @param {string[]} argv
+ * @param {{version: string, out: (line: string) => void, err: (line: string) => void,
+ *          io: object, env: object}} context
+ */
+export async function runRouter(argv, context) {
+  const parsed = parseRouterArgv(argv);
+  if (parsed.kind === 'help') {
+    context.out(routerUsageText());
+    return parsed;
+  }
+  if (parsed.kind === 'version') {
+    const { toolchainIdentity } = await import('./toolchain.mjs');
+    const identity = context.identity ?? await toolchainIdentity({ env: context.env });
+    for (const line of versionLines({ version: context.version, identity })) context.out(line);
+    return parsed;
+  }
+  const row = COMMANDS.find((command) => command.name === parsed.name);
+  const command = await row.load();
+  await command.run(parsed.argv, context);
+  return parsed;
+}