@lerret/cli 0.1.0

package/src/lerret.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// `lerret` CLI entry point.
+//
+// The `lerret` binary's command surface starts here. Argument parsing uses
+// node's built-in `util.parseArgs` — the architecture's explicit choice, no
+// heavy CLI framework. Recognized subcommands:
+//
+//   lerret dev    [--port <n>] [--folder <path>] [--open | --no-open]
+//   lerret export [path] [--format png|jpg] [--out <dir>] [--flat]
+//
+// Adding a new subcommand is the act of importing one more module and adding
+// an entry to the `SUBCOMMANDS` table below — the usage banner is derived
+// from the same table so the two never drift apart.
+//
+// Exit codes:
+//   0 — success, usage requested (`--help`), or graceful shutdown.
+//   1 — unknown subcommand, malformed flags, or a runtime error.
+//
+// Process model: each subcommand owns its own lifecycle. `dev` starts a
+// long-running Vite server and only resolves on SIGINT/SIGTERM; `export`
+// drives a headless Chromium through Playwright once and exits when the
+// capture run finishes; `--help` and unknown-command paths exit synchronously.
+
+import { realpathSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+
+import { runDev } from './dev.js';
+import { runExport } from './export.js';
+
+/**
+ * The set of recognized subcommands and their entry points. Centralized so the
+ * usage banner and the dispatch loop never drift apart.
+ *
+ * @type {Record<string, { describe: string, run: (argv: string[]) => Promise<number> | number }>}
+ */
+const SUBCOMMANDS = {
+  dev: {
+    describe: 'Run the studio against a `.lerret/` project folder (Vite dev server)',
+    run: runDev,
+  },
+  export: {
+    describe: 'Headlessly render a project (or page/group) to image files',
+    run: runExport,
+  },
+};
+
+/**
+ * Print the top-level usage banner to stdout. Intentionally short — each
+ * subcommand prints its own `--help` flag detail.
+ *
+ * @returns {void}
+ */
+function printUsage() {
+  const lines = [
+    'lerret — the design-canvas CLI',
+    '',
+    'Usage: lerret <command> [options]',
+    '',
+    'Commands:',
+    ...Object.entries(SUBCOMMANDS).map(
+      ([name, { describe }]) => `  ${name.padEnd(8)} ${describe}`,
+    ),
+    '',
+    'Run `lerret <command> --help` for command-specific options.',
+  ];
+  process.stdout.write(lines.join('\n') + '\n');
+}
+
+/**
+ * The CLI's top-level entry. Parses only the very first positional (the
+ * subcommand) and hands the remaining argv to that subcommand. The subcommand
+ * does its own flag parsing — keeping each command's flag surface owned by its
+ * own module, which is what `parseArgs` is designed for.
+ *
+ * @param {string[]} [argv=process.argv.slice(2)]
+ *   The argv slice to parse — defaults to the real process argv, overridable
+ *   for tests.
+ * @returns {Promise<number>}  The exit code.
+ */
+export async function main(argv = process.argv.slice(2)) {
+  // A bare invocation or an explicit help flag prints usage and exits 0.
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    printUsage();
+    return 0;
+  }
+
+  const [command, ...rest] = argv;
+  const handler = SUBCOMMANDS[command];
+
+  if (!handler) {
+    // An unknown subcommand is a usage error — print the banner so the user
+    // can see what is valid, then exit non-zero.
+    process.stderr.write(`lerret: unknown command "${command}"\n\n`);
+    printUsage();
+    return 1;
+  }
+
+  try {
+    const code = await handler.run(rest);
+    return typeof code === 'number' ? code : 0;
+  } catch (err) {
+    // A genuine runtime failure inside a subcommand — surface a short error and
+    // exit non-zero. The subcommand owns its own error UX otherwise.
+    process.stderr.write(`lerret ${command}: ${err && err.message ? err.message : String(err)}\n`);
+    return 1;
+  }
+}
+
+/**
+ * `parseArgs` itself is exported for tests so they can verify the basic
+ * dispatch shape without spinning up `dev`.
+ *
+ * @type {typeof parseArgs}
+ */
+export { parseArgs };
+
+// Only run main() when this file is the process entry. The exported `main`
+// stays callable from tests without firing the real CLI.
+//
+// `process.argv[1]` is the path the user invoked. When installed via a zero-
+// install runner (npx, pnpm dlx, bunx) the path may be a symlink inside the
+// runner's cache, while `import.meta.url` is the physical (real) path. We
+// dereference with `realpathSync` before comparing so all four runners work.
+const invokedDirectly =
+  typeof process !== 'undefined' &&
+  Array.isArray(process.argv) &&
+  typeof process.argv[1] === 'string' &&
+  process.argv[1].length > 0 &&
+  (() => {
+    try {
+      return (
+        import.meta.url ===
+        pathToFileURL(realpathSync(process.argv[1])).href
+      );
+    } catch {
+      return false;
+    }
+  })();
+
+if (invokedDirectly) {
+  main().then((code) => process.exit(code));
+}

package/src/resolve-project.js

@@ -0,0 +1,178 @@
+// resolve-project — project detection and `.lerret/` folder designation.
+//
+// A folder is a valid Lerret project if and only if it directly contains a
+// `.lerret/` subdirectory (FR1) — the same "marker folder" idea as `git`'s
+// `.git/`. Detection walks UP from a starting directory toward the filesystem
+// root, returning the first ancestor that directly contains a `.lerret/`
+// directory (FR43). If no ancestor has one, it reports "no project found" so
+// the caller can fall back to a folder-picker / empty-state (that UI lives in
+// the studio and is out of scope here — this module only branches the decision).
+//
+// IMPORTANT: detection reaches the filesystem ONLY through the `core`
+// `FilesystemAccess` contract — never `node:fs` directly. The Node backend
+// (`createNodeBackend()`) is the CLI-mode implementation. `node:path` is used
+// purely for path arithmetic (walking up, normalizing), which the separation
+// invariant explicitly permits.
+
+import { dirname, resolve } from 'node:path';
+
+import { createNodeBackend } from './fs/node-backend.js';
+
+/**
+ * The reserved marker directory whose presence designates a Lerret project.
+ * @type {string}
+ */
+const LERRET_DIR_NAME = '.lerret';
+
+/**
+ * Successful project-detection result.
+ *
+ * @typedef {object} ProjectFound
+ * @property {true} found
+ *   Discriminant — `true` for a resolved project.
+ * @property {string} projectRoot
+ *   Absolute, normalized path of the folder that directly contains
+ *   `.lerret/`. This is the project root.
+ * @property {string} lerretDir
+ *   Absolute, normalized path of the project's `.lerret/` directory — the
+ *   loader's scan root.
+ */
+
+/**
+ * Unsuccessful project-detection result: no `.lerret/` directory was found in
+ * the start directory or any of its ancestors up to the filesystem root.
+ *
+ * @typedef {object} ProjectNotFound
+ * @property {false} found
+ *   Discriminant — `false` when no project was located.
+ * @property {string} startDir
+ *   Absolute, normalized path the walk started from, for diagnostics and for
+ *   the caller's empty-state / folder-picker fallback.
+ */
+
+/**
+ * The result of {@link resolveProject}: either a found project or a clear
+ * not-found outcome. Callers branch on the `found` discriminant.
+ *
+ * @typedef {ProjectFound | ProjectNotFound} ProjectResolution
+ */
+
+/**
+ * Determine whether a directory directly contains a `.lerret/` subdirectory.
+ *
+ * Goes through the {@link import('@lerret/core').FilesystemAccess} contract.
+ * A `readDir` rejection (e.g. the directory is unreadable, or was removed
+ * mid-walk) is treated as "no `.lerret/` here" rather than an error: the walk
+ * should keep climbing toward the root instead of aborting on one bad
+ * ancestor.
+ *
+ * @param {import('@lerret/core').FilesystemAccess} fs
+ *   The filesystem backend to read through.
+ * @param {string} dirPath
+ *   A forward-slash directory path to inspect.
+ * @returns {Promise<boolean>}
+ *   `true` iff `dirPath` directly contains a `.lerret/` directory.
+ */
+async function hasLerretDir(fs, dirPath) {
+  let entries;
+  try {
+    entries = await fs.readDir(dirPath);
+  } catch {
+    // Unreadable / vanished directory — not a project root we can use. Let
+    // the caller keep walking up rather than failing the whole detection.
+    return false;
+  }
+
+  return entries.some(
+    (entry) => entry.isDirectory && entry.name === LERRET_DIR_NAME,
+  );
+}
+
+/**
+ * Detect the Lerret project containing a starting directory.
+ *
+ * Walks up from `startDir` toward the filesystem root. The first ancestor that
+ * directly contains a `.lerret/` directory is the project root; its `.lerret/`
+ * directory is the loader's scan root (FR43). If no ancestor qualifies, the
+ * walk stops cleanly at the filesystem root and a not-found result is returned
+ * — never an error, never an infinite loop.
+ *
+ * Path handling: `startDir` is resolved to an absolute path first (so a
+ * relative or `.`-style argument works), then normalized to forward slashes so
+ * every path in the result matches the `FilesystemAccess` contract convention.
+ *
+ * @param {string} [startDir=process.cwd()]
+ *   The directory to begin detection from — typically the CLI's working
+ *   directory. Resolved to absolute if relative.
+ * @param {import('@lerret/core').FilesystemAccess} [fs]
+ *   The filesystem backend to detect through. Defaults to a fresh Node backend
+ *   (`createNodeBackend()`), the CLI-mode implementation. Injectable so tests
+ *   and alternate hosts can supply their own backend.
+ * @returns {Promise<ProjectResolution>}
+ *   A {@link ProjectFound} carrying absolute `projectRoot` / `lerretDir`
+ *   paths, or a {@link ProjectNotFound} carrying the absolute `startDir`.
+ */
+export async function resolveProject(
+  startDir = process.cwd(),
+  fs = createNodeBackend(),
+) {
+  // Resolve to an absolute path, then speak the contract's forward-slash
+  // convention so every path we pass to `readDir` — and every path we return
+  // — is normalized identically.
+  const absoluteStart = toLerretPath(resolve(startDir));
+
+  let current = absoluteStart;
+
+  // Walk up one ancestor per iteration. The loop terminates because
+  // `dirname()` strictly shortens the path until it reaches the filesystem
+  // root, where `dirname(root) === root` — the explicit stop condition below.
+  for (;;) {
+    if (await hasLerretDir(fs, current)) {
+      return {
+        found: true,
+        projectRoot: current,
+        lerretDir: joinLerretPath(current, LERRET_DIR_NAME),
+      };
+    }
+
+    const parent = toLerretPath(dirname(current));
+    if (parent === current) {
+      // Reached the filesystem root — `dirname` no longer shortens the path.
+      // Stop cleanly: no `.lerret/` anywhere on the path to the root.
+      break;
+    }
+    current = parent;
+  }
+
+  return { found: false, startDir: absoluteStart };
+}
+
+/**
+ * Normalize an OS path to the forward-slash form the `FilesystemAccess`
+ * contract uses. A near no-op on POSIX hosts; on Windows it bridges `\` to
+ * `/`. A lone drive-root such as `C:\` keeps its trailing separator so it
+ * stays a valid directory path.
+ *
+ * @param {string} osPath An absolute path using native separators.
+ * @returns {string} The same path with forward slashes.
+ */
+function toLerretPath(osPath) {
+  return osPath.replaceAll('\\', '/');
+}
+
+/**
+ * Join a forward-slash directory path and a single child segment, without
+ * reaching for `node:path` join semantics (which would re-introduce native
+ * separators). The directory path is already absolute and normalized.
+ *
+ * @param {string} dirPath A forward-slash directory path.
+ * @param {string} name A single path segment.
+ * @returns {string} The joined forward-slash path.
+ */
+function joinLerretPath(dirPath, name) {
+  // A filesystem root like `/` or `C:/` already ends in a separator; appending
+  // another would produce `//`. Otherwise insert exactly one `/`.
+  return dirPath.endsWith('/') ? `${dirPath}${name}` : `${dirPath}/${name}`;
+}
+
+export { LERRET_DIR_NAME };