@venn-lang/cli 0.1.0

package/src/commands/run.ts

@@ -0,0 +1,149 @@
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { createNodeHost, createNodeSignals } from "@venn-lang/contracts/node";
+import { createFetchClient } from "@venn-lang/http";
+import { createNodeServer } from "@venn-lang/http/node";
+import type { RunFilter } from "@venn-lang/runtime";
+import { loadEnv, loadManifest } from "../manifest/index.js";
+import type { Reporter, RunTotals } from "../reporters/index.js";
+import { pickReporter, reportProblems } from "../reporters/index.js";
+import { collectSourceFiles } from "../run/collect-files.js";
+import { createNodeModuleIo } from "../run/node-io.js";
+import { createNpmLoader } from "../run/npm-loader.js";
+import { type RunFileOutcome, runFile } from "../run/run-file.js";
+import { createShutdown, installHooks, type Shutdown } from "../shutdown/index.js";
+import { setProgramTitle } from "../title/index.js";
+
+/** Everything `venn run` accepts. */
+export interface RunOptions {
+  file: string;
+  reporter?: string;
+  tags?: string;
+  flow?: string;
+  step?: string;
+  env?: string;
+  bail?: boolean;
+}
+
+/** What one pass over the files needs to carry from start to finish. */
+interface RunPass {
+  files: readonly string[];
+  options: RunOptions;
+  reporter: Reporter;
+  shutdown: Shutdown;
+}
+
+/**
+ * `venn test <file|directory>`: run every matching flow, then report.
+ *
+ * @param options - The file or directory, the reporter, and the filters.
+ * @returns The exit code: whatever a flow's `exit` named, else 0 when nothing
+ * failed, else 1. Also 1 when the path holds no `.vn` file.
+ */
+export async function runCommand(options: RunOptions): Promise<number> {
+  const files = await collectSourceFiles(resolve(options.file));
+  if (files.length === 0) return noFiles(options.file);
+  const reporter = pickReporter(options.reporter);
+  const shutdown = createShutdown();
+  setProgramTitle({ command: "test", target: options.file });
+  installHooks({ signals: createNodeSignals(), shutdown, exit: (code) => process.exit(code) });
+  const totals = await runAll({ files, options, reporter, shutdown });
+  reporter.finish(totals);
+  // A suite that called `exit` named its own verdict, even `exit 0` after a
+  // failure, which is the point of saying it.
+  return totals.exitCode ?? (totals.failed === 0 ? 0 : 1);
+}
+
+async function runAll(pass: RunPass): Promise<RunTotals> {
+  const totals: RunTotals = { passed: 0, failed: 0, files: 0, ms: 0 };
+  const started = Date.now();
+  for (const file of pass.files) {
+    pass.reporter.beginFile(file);
+    await runOne({ pass, file, totals });
+    // `exit` ends the command, not just the file it was called in.
+    if (totals.exitCode !== undefined) break;
+    if (pass.options.bail && totals.failed > 0) break;
+  }
+  totals.ms = Date.now() - started;
+  return totals;
+}
+
+/**
+ * One file, and the servers it started closed with it.
+ *
+ * A suite that leaves a port bound holds it for the whole run, so a hundred
+ * files that serve would end up holding a hundred ports. They are also on the
+ * shutdown list, for the run that ends by signal instead of by finishing.
+ */
+async function runOne(args: { pass: RunPass; file: string; totals: RunTotals }): Promise<void> {
+  const servers = createNodeServer();
+  const forget = args.pass.shutdown.add(() => servers.closeAll());
+  try {
+    tally(args.totals, await runFile(await buildArgs(args.file, args.pass, servers)));
+  } finally {
+    await servers.closeAll();
+    forget();
+  }
+}
+
+function tally(totals: RunTotals, outcome: RunFileOutcome): void {
+  if (outcome.problems.length > 0) {
+    reportProblems(outcome.problems);
+    totals.files += 1;
+    totals.failed += 1;
+    return;
+  }
+  if (outcome.result?.exitCode !== undefined) totals.exitCode = outcome.result.exitCode;
+  const passed = outcome.result?.passed ?? 0;
+  const failed = outcome.result?.failed ?? 0;
+  // A file whose flows were all filtered out is not part of the run.
+  if (passed + failed > 0) totals.files += 1;
+  totals.passed += passed;
+  totals.failed += failed;
+}
+
+async function buildArgs(
+  file: string,
+  pass: RunPass,
+  httpServer: ReturnType<typeof createNodeServer>,
+) {
+  const found = await loadManifest(file);
+  const manifest = found?.manifest;
+  return {
+    source: await readFile(file, "utf8"),
+    uri: file,
+    host: createNodeHost(),
+    sink: pass.reporter.sink,
+    httpClient: createFetchClient(),
+    httpServer,
+    filter: filterOf(pass.options),
+    bail: pass.options.bail,
+    env: await loadEnv({
+      manifest,
+      name: pass.options.env ?? "local",
+      dir: found?.dir ?? dirname(file),
+    }),
+    io: createNodeModuleIo({
+      paths: manifest?.paths ?? {},
+      rootDir: found?.dir ?? dirname(file),
+    }),
+    npm: createNpmLoader({ root: found?.dir ?? dirname(file) }),
+  };
+}
+
+function filterOf(options: RunOptions): RunFilter {
+  return { tags: parseTags(options.tags), flow: options.flow, step: options.step };
+}
+
+function parseTags(tags: string | undefined): readonly string[] | undefined {
+  if (!tags) return undefined;
+  return tags
+    .split(",")
+    .map((tag) => tag.trim())
+    .filter((tag) => tag !== "");
+}
+
+function noFiles(path: string): number {
+  process.stderr.write(`No .vn files found at ${path}\n`);
+  return 1;
+}

package/src/commands/script.ts

@@ -0,0 +1,127 @@
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { createNodeConsole, createNodeHost, createNodeSignals } from "@venn-lang/contracts/node";
+import { createFetchClient } from "@venn-lang/http";
+import { createNodeServer, type NodeHttpServer } from "@venn-lang/http/node";
+import { envDirOf, loadEnv, loadManifest } from "../manifest/index.js";
+import { createProblemSink, errorLine, reportProblems } from "../reporters/index.js";
+import type { Ending } from "../run/ending.types.js";
+import { exitCodeOf } from "../run/exit-code.js";
+import { createNodeModuleIo } from "../run/node-io.js";
+import { createNpmLoader } from "../run/npm-loader.js";
+import { type RunFileArgs, runFile } from "../run/run-file.js";
+import { shouldLeave } from "../run/should-leave.js";
+import { createShutdown, installHooks, type Shutdown } from "../shutdown/index.js";
+import { setProgramTitle } from "../title/index.js";
+
+/** Everything `venn run` (script mode) accepts. */
+export interface ScriptOptions {
+  file: string;
+  args?: readonly string[];
+  env?: string;
+}
+
+/**
+ * `venn run <file>`: execute the file as a program, its statements in order.
+ *
+ * A program that serves keeps running after the last statement, which is the
+ * point of it, so what it opened is closed on the way out instead: whether the
+ * way out is a signal, a fault, or a crash mid-script.
+ *
+ * @returns The code to leave with, and whether the process should go now.
+ */
+export async function scriptCommand(options: ScriptOptions): Promise<Ending> {
+  const uri = resolve(options.file);
+  const servers = createNodeServer();
+  const shutdown = hooked({ servers, file: uri });
+  try {
+    const outcome = await runFile(await scriptArgs({ options, uri, servers, shutdown }));
+    if (outcome.problems.length > 0) return { code: report(outcome.problems), leave: true };
+    return await ending(exitCodeOf(outcome.result), asked(outcome.result), shutdown);
+  } catch (error) {
+    await shutdown.close();
+    return { code: crashed(error), leave: true };
+  }
+}
+
+/** Whether the program said when to stop, rather than simply running out of lines. */
+function asked(result: { exitCode?: number } | undefined): boolean {
+  return result?.exitCode !== undefined;
+}
+
+/**
+ * Leave, or stay and let the loop decide.
+ *
+ * A program that asked to exit gets what it asked for, but tidily: whatever it
+ * opened is given back first, which is the half `process.exit` on its own skips.
+ * One that merely reached its last line is not asked to stop, because a server
+ * has not finished just because the file has.
+ */
+async function ending(code: number, requested: boolean, shutdown: Shutdown): Promise<Ending> {
+  if (!shouldLeave({ code, requested })) return { code, leave: false };
+  await shutdown.close();
+  return { code, leave: true };
+}
+
+/** Give the process its hooks, its name, and this run's servers to close. */
+function hooked(args: { servers: NodeHttpServer; file: string }): Shutdown {
+  const shutdown = createShutdown();
+  setProgramTitle({ command: "run", target: args.file });
+  shutdown.add(() => args.servers.closeAll());
+  installHooks({ signals: createNodeSignals(), shutdown, exit: (code) => process.exit(code) });
+  return shutdown;
+}
+
+/** Everything a script run needs from the machine: the file, the manifest, the ports. */
+async function scriptArgs(args: {
+  options: ScriptOptions;
+  uri: string;
+  servers: NodeHttpServer;
+  shutdown: Shutdown;
+}): Promise<RunFileArgs> {
+  const { options, uri } = args;
+  const found = await loadManifest(uri);
+  const manifest = found?.manifest;
+  return {
+    source: await readFile(uri, "utf8"),
+    uri,
+    mode: "script",
+    env: await loadEnv({
+      manifest,
+      name: options.env ?? "local",
+      dir: found?.dir ?? envDirOf(uri),
+    }),
+    io: createNodeModuleIo({
+      paths: manifest?.paths ?? {},
+      rootDir: found?.dir ?? dirname(uri),
+    }),
+    npm: createNpmLoader({ root: found?.dir ?? dirname(uri) }),
+    cleanup: args.shutdown,
+    ...nodePorts({ argv: options.args ?? [], servers: args.servers }),
+  };
+}
+
+/** The real implementations behind the ports a script talks through. */
+function nodePorts(args: {
+  argv: readonly string[];
+  servers: NodeHttpServer;
+}): Pick<RunFileArgs, "host" | "sink" | "httpClient" | "httpServer" | "console"> {
+  return {
+    host: createNodeHost(),
+    sink: createProblemSink(),
+    httpClient: createFetchClient(),
+    httpServer: args.servers,
+    console: createNodeConsole({ argv: args.argv }),
+  };
+}
+
+function report(problems: Parameters<typeof reportProblems>[0]): number {
+  reportProblems(problems);
+  return 1;
+}
+
+/** An error thrown mid-script: print it the way the program would see it, then fail. */
+function crashed(error: unknown): number {
+  process.stderr.write(`${errorLine(error)}\n`);
+  return 1;
+}

package/src/commands/upgrade.ts

@@ -0,0 +1,86 @@
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { bold, dim } from "../reporters/colors.js";
+import { installSiteOf } from "../upgrade/install-site.js";
+import { isNewer, latestVersion } from "../upgrade/latest-version.js";
+import type { InstallSite, UpgradeOptions } from "../upgrade/upgrade.types.js";
+import { runUpgrade } from "../upgrade/upgrade-command.js";
+import { refusalFor, upgradeCommandFor } from "../upgrade/upgrade-plan.js";
+
+/**
+ * `venn upgrade`: move a global install to the latest published version.
+ *
+ * Nothing is changed without saying what will run and asking first, because a
+ * command that rewrites what is on the machine has to be one the user chose.
+ *
+ * @param version The version running now, compared against the registry.
+ * @returns 0 when already current or the upgrade succeeded, 1 otherwise.
+ */
+export async function upgradeCommand(args: {
+  version: string;
+  options: UpgradeOptions;
+}): Promise<number> {
+  const site = currentSite();
+  const refusal = refusalFor(site);
+  if (refusal) return fail(refusal);
+
+  const latest = await latestVersion();
+  if (!latest) return fail("Could not reach the registry to check for a newer version.");
+
+  if (!isNewer({ current: args.version, candidate: latest })) {
+    process.stdout.write(`venn ${args.version} is already the latest.\n`);
+    return 0;
+  }
+  return upgradeTo({ latest, site, options: args.options, version: args.version });
+}
+
+/**
+ * `fileURLToPath`, not the URL itself: the site is decided by comparing against
+ * the working directory, and "file:///c:/x" never starts with "c:/x", which made
+ * every install inside a project look global.
+ */
+function currentSite(): InstallSite {
+  return installSiteOf({ path: fileURLToPath(import.meta.url), cwd: process.cwd() });
+}
+
+function fail(message: string): number {
+  process.stderr.write(`${message}\n`);
+  return 1;
+}
+
+async function upgradeTo(args: {
+  latest: string;
+  site: InstallSite;
+  options: UpgradeOptions;
+  version: string;
+}): Promise<number> {
+  const command = upgradeCommandFor(args.site.manager)?.join(" ") ?? "";
+  process.stdout.write(`${bold(`venn ${args.version}`)} ${dim("->")} ${bold(args.latest)}\n`);
+  process.stdout.write(`${dim(command)}\n`);
+  if (!(args.options.yes || args.options.dryRun) && !(await confirmed())) {
+    process.stdout.write("Nothing was changed.\n");
+    return 0;
+  }
+  const code = await runUpgrade({ site: args.site, options: args.options });
+  if (code !== 0) process.stderr.write(permissionHelp(command));
+  return code;
+}
+
+async function confirmed(): Promise<boolean> {
+  if (!process.stdin.isTTY) return false;
+  const io = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await io.question("Upgrade now? [y/N] ");
+  io.close();
+  return answer.trim().toLowerCase().startsWith("y");
+}
+
+/** The usual cause of a failed global install, said plainly. */
+function permissionHelp(command: string): string {
+  return [
+    "",
+    "The upgrade did not complete. A global install often needs elevated rights.",
+    `Try running it yourself: ${command}`,
+    `Or install where you own the files: npm config set prefix ~/.npm-global`,
+    "",
+  ].join("\n");
+}

package/src/commands/verify-plugin.ts

@@ -0,0 +1,35 @@
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { PluginDefinition } from "@venn-lang/sdk";
+
+/**
+ * `venn verify-plugin <path>`: import a plugin module, print what it declares,
+ * and check its shape.
+ *
+ * @param args - `path` is the module to import, relative to the working
+ * directory or absolute.
+ * @returns 0 when the plugin names itself and a namespace, 1 when it does not.
+ * @throws Error when the module exports nothing that looks like a plugin.
+ */
+export async function verifyPluginCommand(args: { path: string }): Promise<number> {
+  const plugin = await loadPlugin(args.path);
+  const out = process.stdout;
+  out.write(`Plugin: ${plugin.name} (namespace "${plugin.namespace}")\n`);
+  out.write(`  actions:   ${plugin.actions?.length ?? 0}\n`);
+  out.write(`  matchers:  ${plugin.matchers?.length ?? 0}\n`);
+  out.write(`  resources: ${plugin.resources?.length ?? 0}\n`);
+  const ok = Boolean(plugin.name && plugin.namespace);
+  out.write(ok ? "\n✓ plugin shape is valid\n" : "\n✗ plugin shape is invalid\n");
+  return ok ? 0 : 1;
+}
+
+async function loadPlugin(path: string): Promise<PluginDefinition> {
+  const mod = (await import(pathToFileURL(resolve(path)).href)) as Record<string, unknown>;
+  const plugin = mod.default ?? Object.values(mod).find(isPlugin);
+  if (!isPlugin(plugin)) throw new Error(`No plugin export found in ${path}`);
+  return plugin;
+}
+
+function isPlugin(value: unknown): value is PluginDefinition {
+  return typeof value === "object" && value !== null && "namespace" in value && "name" in value;
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+// @venn-lang/cli: the `venn` binary (process boundary) plus the embeddable runFile.
+// The only package that touches node:* and binds concrete implementations.
+
+export { runCommand, verifyPluginCommand } from "./commands/index.js";
+export { createStdoutSink, reportProblems } from "./reporters/index.js";
+export type { RunFileOutcome } from "./run/run-file.js";
+export { runFile } from "./run/run-file.js";

package/src/manifest/index.ts

@@ -0,0 +1,2 @@
+export { envDirOf, loadEnv } from "./load-env.js";
+export { loadManifest } from "./load-manifest.js";

package/src/manifest/load-env.ts

@@ -0,0 +1,70 @@
+// biome-ignore-all lint/suspicious/noTemplateCurlyInString: ${name} is a placeholder in a dotenv path, not a JavaScript template.
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { dotenvFiles, type Manifest, parseDotenv } from "@venn-lang/contracts";
+
+export interface EnvArgs {
+  manifest: Manifest | undefined;
+  /** The selected environment: `--env staging`, or `local`. */
+  name: string;
+  /** Any file the manifest points at is resolved from here. */
+  dir: string;
+  /** The process environment. Injected so a test can hand over its own. */
+  processEnv?: Record<string, string | undefined>;
+}
+
+/**
+ * Every variable a run can see, lowest precedence first:
+ *
+ *   1. `[env.<name>]` in `venn.toml`, the documented default, committed.
+ *   2. the dotenv files, in the order they are listed.
+ *   3. the real environment the process was started with.
+ *
+ * The real environment wins because that is how CI passes a token in, and a
+ * value set on the command line should never lose to a file in the repository.
+ */
+export async function loadEnv(args: EnvArgs): Promise<Record<string, unknown>> {
+  const declared = { ...(args.manifest?.env[args.name] ?? {}), ...(await readFiles(args)) };
+  const real = overrides(declared, args.processEnv ?? process.env);
+  return { ...declared, ...real, name: args.name };
+}
+
+/**
+ * The real environment overrides what was declared. It does not add to it.
+ *
+ * A shell holds hundreds of entries; letting them all become `env.*` would put
+ * `PATH` and `TEMP` in the editor's completion and let a typo silently read
+ * something from the machine. Declaring a name, in `venn.toml` or a dotenv file
+ * and with any value, is what says "this program reads this". A value that
+ * exists only in CI and is never declared belongs to `secrets.*`, which reads
+ * the environment directly and redacts what it returns.
+ */
+function overrides(
+  declared: Record<string, string>,
+  source: Record<string, string | undefined>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const name of Object.keys(declared)) {
+    const value = source[name];
+    if (value !== undefined) out[name] = value;
+  }
+  return out;
+}
+
+async function readFiles(args: EnvArgs): Promise<Record<string, string>> {
+  const names = dotenvFiles({ configured: args.manifest?.envFiles, name: args.name });
+  const out: Record<string, string> = {};
+  for (const each of names) Object.assign(out, await readOne(resolve(args.dir, each)));
+  return out;
+}
+
+/** A file that is not there is not a problem: most projects have none of them. */
+async function readOne(path: string): Promise<Record<string, string>> {
+  const content = await readFile(path, "utf8").catch(() => undefined);
+  return content === undefined ? {} : parseDotenv(content);
+}
+
+/** Where dotenv files are looked for: the folder holding the flow. */
+export function envDirOf(sourceUri: string): string {
+  return dirname(sourceUri);
+}

package/src/manifest/load-manifest.ts

@@ -0,0 +1,42 @@
+import { dirname, resolve } from "node:path";
+import type { Manifest } from "@venn-lang/contracts";
+import { createNodeFs } from "@venn-lang/contracts/node";
+import { findProject, isInside, normalise, type Package, type Project } from "@venn-lang/project";
+
+export interface LoadedManifest {
+  manifest: Manifest;
+  /**
+   * The directory the settings are anchored to.
+   *
+   * Carried because a `[paths]` alias is written relative to the project, not
+   * to the folder the `.vn` file happens to sit in: a member of a workspace
+   * reads the aliases its root declared.
+   */
+  dir: string;
+}
+
+/**
+ * The manifest that governs a `.vn` file.
+ *
+ * Found by walking up to the project the file belongs to, rather than by
+ * reading whatever happens to sit in the same folder. That is what makes a
+ * command work from anywhere: `venn test packages/api/src/login.vn` sees the
+ * same environments and aliases as running it from inside `packages/api`.
+ *
+ * Undefined when nothing governs the file: living outside a project is normal.
+ */
+export async function loadManifest(sourceUri: string): Promise<LoadedManifest | undefined> {
+  const file = normalise(resolve(sourceUri));
+  const { project } = await findProject({ fs: createNodeFs(), from: normalise(dirname(file)) });
+  if (!project) return undefined;
+  const owner = owningPackage(project, file);
+  if (owner) return { manifest: owner.manifest, dir: owner.dir };
+  return { manifest: project.rootManifest, dir: project.root };
+}
+
+/** The innermost member holding this file: the one whose settings are nearest. */
+function owningPackage(project: Project, file: string): Package | undefined {
+  return [...project.packages]
+    .filter((one) => isInside(file, one.dir))
+    .sort((a, b) => b.dir.length - a.dir.length)[0];
+}

package/src/project/command-targets.ts

@@ -0,0 +1,53 @@
+import { createNodeFs } from "@venn-lang/contracts/node";
+import { type BuildTarget, join, type Package } from "@venn-lang/project";
+
+const TESTS_DIR = "tests";
+
+/**
+ * Where a package's test suite lives.
+ *
+ * `tests/` and nothing else. Running everything in the package instead would
+ * sweep up `src/main.vn`, a program rather than a suite, and report a run
+ * nobody asked for. A package with no `tests/` contributes nothing, which is
+ * the truth about it rather than a failure.
+ */
+export async function testPaths(packages: readonly Package[]): Promise<string[]> {
+  const fs = createNodeFs();
+  const found: string[] = [];
+  for (const one of packages) {
+    const dir = join(one.dir, TESTS_DIR);
+    if (await fs.exists(dir)) found.push(dir);
+  }
+  return found;
+}
+
+/** Every `.vn` a package owns: what `check` and `fmt` act on. */
+export function sourcePaths(packages: readonly Package[]): string[] {
+  return packages.map((one) => one.dir);
+}
+
+/**
+ * The program `venn run` means when it is given no file.
+ *
+ * One `bin` is unambiguous. Several is a question only the author can answer,
+ * so it is asked rather than guessed: picking the first would be a coin toss
+ * that looks like a decision.
+ */
+export function binTarget(args: {
+  packages: readonly Package[];
+  name?: string;
+}): { path: string } | { ambiguous: readonly string[] } | undefined {
+  const bins = args.packages.flatMap((one) =>
+    one.targets.filter(isBin).map((target) => ({ target, dir: one.dir })),
+  );
+  const wanted = args.name ? bins.filter((one) => one.target.name === args.name) : bins;
+  if (wanted.length === 1 && wanted[0]) {
+    return { path: join(wanted[0].dir, wanted[0].target.path) };
+  }
+  if (wanted.length === 0) return undefined;
+  return { ambiguous: wanted.map((one) => one.target.name) };
+}
+
+function isBin(target: BuildTarget): boolean {
+  return target.kind === "bin";
+}

package/src/project/index.ts

@@ -0,0 +1,9 @@
+export { binTarget, sourcePaths, testPaths } from "./command-targets.js";
+export { type CommandKind, resolveTargets } from "./resolve-targets.js";
+export {
+  type SelectArgs,
+  type Selection,
+  selectPackages,
+  unknownPackage,
+} from "./select-packages.js";
+export { targetsOrExit, worst } from "./targets-or-exit.js";

package/src/project/resolve-targets.ts

@@ -0,0 +1,70 @@
+import { binTarget, sourcePaths, testPaths } from "./command-targets.js";
+import { selectPackages, unknownPackage } from "./select-packages.js";
+
+/** What a command was pointed at, once the project has had its say. */
+export interface ResolvedTargets {
+  paths: readonly string[];
+  /** What to print and stop for, when the request cannot be answered. */
+  problem?: string;
+}
+
+export type CommandKind = "test" | "check" | "run";
+
+/**
+ * The paths a command acts on: the one it was given, or the ones the project
+ * says it means.
+ *
+ * An explicit path always wins and is never second-guessed: `venn test
+ * examples/` tests `examples/`, project or no project. Everything else is the
+ * workspace answering the question the bare command asked.
+ */
+export async function resolveTargets(args: {
+  kind: CommandKind;
+  target?: string;
+  packageName?: string;
+  binName?: string;
+  cwd: string;
+}): Promise<ResolvedTargets> {
+  if (args.target) return { paths: [args.target] };
+  const selection = await selectPackages({ from: args.cwd, packageName: args.packageName });
+  if (!selection) return { paths: [], problem: NO_PROJECT };
+  if (args.packageName && selection.packages.length === 0) {
+    return { paths: [], problem: unknownPackage(selection.project, args.packageName) };
+  }
+  return forKind({ ...args, selection });
+}
+
+const NO_PROJECT =
+  "VN2101 · no venn.toml here, or in any folder above it.\n" +
+  "  give a path, or start a project with `venn init`\n";
+
+async function forKind(args: {
+  kind: CommandKind;
+  binName?: string;
+  selection: Awaited<ReturnType<typeof selectPackages>>;
+}): Promise<ResolvedTargets> {
+  const packages = args.selection?.packages ?? [];
+  if (args.kind === "check") return { paths: sourcePaths(packages) };
+  if (args.kind === "test") return testTargets(await testPaths(packages));
+  return runTarget(packages, args.binName);
+}
+
+function testTargets(paths: readonly string[]): ResolvedTargets {
+  if (paths.length > 0) return { paths };
+  return { paths: [], problem: "no `tests/` directory in the packages selected.\n" };
+}
+
+function runTarget(
+  packages: Parameters<typeof binTarget>[0]["packages"],
+  name?: string,
+): ResolvedTargets {
+  const found = binTarget({ packages, name });
+  if (!found) return { paths: [], problem: "no program to run here — expected `src/main.vn`.\n" };
+  if ("ambiguous" in found) {
+    return {
+      paths: [],
+      problem: `several programs here. Pick one: --bin ${found.ambiguous.join(" | --bin ")}\n`,
+    };
+  }
+  return { paths: [found.path] };
+}