mindcraft-cli 0.1.2 → 0.1.3

package/README.md

@@ -0,0 +1,252 @@
+# mindcraft-cli
+
+Command-line tools for publishing and versioning Mindcraft projects.
+
+A Mindcraft project is a directory with a `mindcraft.json` manifest (plus the
+files it lists). This CLI publishes such a project to GitHub as a versioned,
+installable release, bumps its version, and turns a `.mindcraft` export from
+the web editor into a project directory you can publish.
+
+## Install and run
+
+Requires Node.js 18 or newer.
+
+Run without installing:
+
+```
+npx mindcraft-cli <command> [arguments]
+```
+
+Or install once and call it directly:
+
+```
+npm install -g mindcraft-cli
+mindcraft <command> [arguments]
+```
+
+Both give you the same `mindcraft` command. Examples below use `mindcraft`;
+substitute `npx mindcraft-cli` if you did not install it.
+
+## Commands at a glance
+
+| Command | What it does |
+|---|---|
+| [`mindcraft publish`](#mindcraft-publish) | Publish a version of a project to its GitHub repository. |
+| [`mindcraft version`](#mindcraft-version) | Increment a project's version in its `mindcraft.json`. |
+| [`mindcraft unpack`](#mindcraft-unpack) | Turn a `.mindcraft` export into a publishable project directory. |
+
+Running `mindcraft` with no command, or an unknown command, prints usage and
+exits non-zero.
+
+`mindcraft --version` (or `-v`) prints this CLI's own version and exits. It is
+separate from the [`version`](#mindcraft-version) command below, which changes
+a project's version.
+
+## Concepts (read once)
+
+- `mindcraft.json` is the project manifest. It carries the project's `version`,
+  its `files` list, its `identity`, and everything else the project comprises.
+- A project's identity is its `<owner>/<repo>` GitHub coordinate, recorded in
+  the manifest's `identity` field. You do not hand-write it: `publish` stamps it
+  from the repository you publish to, and `unpack --coordinate` sets it once.
+- A published version is the project's content at the git tag `v<version>` on
+  its GitHub repository. The manifest version and the tag always match.
+
+---
+
+## `mindcraft publish`
+
+Publish a version of the project to its GitHub repository: commit the project's
+tree, tag it `v<version>`, and push.
+
+```
+mindcraft publish [patch|minor|major] [--dir <path>] [--remote <url>] [--allow-unstable-refs]
+```
+
+### Arguments
+
+| Argument | Meaning |
+|---|---|
+| `patch` \| `minor` \| `major` | Optional. Increment that part of the version before publishing. Omit it only for the very first publish to a repository that has no tags yet, which publishes the manifest's current version as-is. |
+| `--dir <path>` | Project directory. Default: the current directory. |
+| `--remote <url>` | The git remote to publish to. Usually unnecessary (see below). |
+| `--allow-unstable-refs` | Permit dependencies that are unstable for people who install this project: a branch reference, or a pinned version the source does not yet serve. Without this flag, publishing stops and asks you to confirm. |
+
+### How the publish target is chosen
+
+If you do not pass `--remote`, where the project publishes depends on your
+checkout:
+
+- The project directory is the root of its own git checkout: it publishes to
+  that checkout's `origin`.
+- The project lives in a subdirectory of a larger checkout (for example a
+  monorepo), or its checkout has no `origin`: it publishes to the GitHub remote
+  derived from the recorded identity, `https://github.com/<owner>/<repo>.git`.
+- A first publish, before any identity is recorded, targets `origin`.
+
+Pass `--remote <url>` to override this.
+
+### What it does
+
+- Bumps the manifest version (if you named a component) and stamps the
+  manifest's `identity` with the coordinate of the publish remote. It prints a
+  warning if that changes a previously recorded identity (for example when you
+  publish a clone to your own repository -- a fork).
+- Commits the project's tree (its `mindcraft.json` plus the files the manifest
+  lists), tags it `v<version>`, and pushes the branch and tag.
+- Writes the published version and identity back into the project directory's
+  `mindcraft.json` when the tree is published to a derived or explicit remote.
+
+Requires the git working tree to be clean, and Git credentials that can push to
+the target repository. Published repositories are public.
+
+### Examples
+
+First publish, run from inside the project after creating its empty GitHub repo:
+
+```
+mindcraft publish
+```
+
+Cut a routine release (bump the patch version and publish):
+
+```
+mindcraft publish patch
+```
+
+Publish a library kept in a monorepo subdirectory (the remote is derived from
+its recorded identity):
+
+```
+mindcraft publish minor --dir libs/my-widget
+```
+
+Publish to an explicit repository:
+
+```
+mindcraft publish patch --remote https://github.com/acme/my-widget.git
+```
+
+Publish even though a dependency points at a moving branch:
+
+```
+mindcraft publish patch --allow-unstable-refs
+```
+
+---
+
+## `mindcraft version`
+
+Increment the project's version in its `mindcraft.json`, without publishing.
+
+```
+mindcraft version <patch|minor|major> [--dir <path>]
+```
+
+### Arguments
+
+| Argument | Meaning |
+|---|---|
+| `patch` \| `minor` \| `major` | Required. Which part of the version to increment. |
+| `--dir <path>` | Project directory. Default: the current directory. |
+
+### What it does
+
+Reads the project's `mindcraft.json`, increments the version by the named
+component, writes it back, and prints the new version (for example
+`version 1.4.0`).
+
+Use this when you package a target for distribution: bump the version first so
+the built bundle bakes in the new version, then publish the packaged target
+verbatim (no bump at publish time).
+
+### Examples
+
+```
+mindcraft version patch
+mindcraft version minor --dir path/to/project
+```
+
+Fails with `VERSION_MANIFEST_MISSING` if the directory has no `mindcraft.json`,
+or `VERSION_MANIFEST_INVALID` if the manifest cannot be parsed.
+
+---
+
+## `mindcraft unpack`
+
+Turn a `.mindcraft` export (downloaded from the web editor) into a project
+directory on disk that you can then publish.
+
+```
+mindcraft unpack <file.mindcraft> [dir] [--coordinate <owner/repo>] [--force]
+```
+
+### Arguments
+
+| Argument | Meaning |
+|---|---|
+| `<file.mindcraft>` | Required. The exported document to unpack. |
+| `dir` | Target directory. Default: the document's base name, in the current directory. |
+| `--coordinate <owner/repo>` | Record this as the project's published identity in the manifest's `identity` field. |
+| `--force` | Allow unpacking into a directory that is not empty. |
+
+### What it does
+
+Writes the export's embedded manifest as `mindcraft.json` and every file in the
+export to disk. If the manifest declares no `files` list, one is generated
+naming every unpacked file -- including any scratch files that were in the
+exported workspace, so review and prune `mindcraft.json` before publishing.
+Prints how many files were written.
+
+After unpacking, that directory is the canonical project: publish from it, and
+treat re-exporting from the app as an occasional release step, not a live sync.
+
+### Examples
+
+Unpack into a directory named after the file (`./my-project`):
+
+```
+mindcraft unpack my-project.mindcraft
+```
+
+Unpack into a chosen directory and record the project's identity:
+
+```
+mindcraft unpack my-project.mindcraft my-widget --coordinate acme/my-widget
+```
+
+Unpack into the current, non-empty directory:
+
+```
+mindcraft unpack export.mindcraft . --force
+```
+
+---
+
+## Exit codes and output (for scripting and automation)
+
+- Every command returns exit code `0` on success and `1` on failure.
+- Human-readable results go to stdout; errors go to stderr.
+- Failures carry a stable, uppercase error code in the stderr message (for
+  example `VERSION_MANIFEST_MISSING`, `PUBLISH_UNCOMMITTED_CHANGES`,
+  `PUBLISH_UNSTABLE_DEPENDENCIES_UNCONFIRMED`). Match on the code, not the
+  surrounding prose.
+
+## Using this CLI as a tool (for LLMs and agents)
+
+- Invoke exactly one command per call: `mindcraft <command> [arguments]`.
+  Available commands are `publish`, `version`, and `unpack`. `mindcraft
+  --version` reports the tool's own version.
+- All input is positional arguments and flags; the CLI does not read piped
+  stdin. It is safe to run non-interactively.
+- Decide success from the exit code (`0` ok, `1` failed), not from output text.
+  On failure, read stderr and match the uppercase error code.
+- `publish` performs network and git operations (commit, tag, push) against a
+  real GitHub repository and requires push credentials. Do not run it to
+  "test"; it has durable, external side effects. `version` and `unpack` only
+  touch local files.
+- `--dir` defaults to the current working directory for `publish` and
+  `version`. Pass `--dir <path>` explicitly when the working directory is not
+  the project.
+- `publish` will stop and require confirmation if a dependency is unstable for
+  consumers; pass `--allow-unstable-refs` only when that is intended.

package/dist/cli.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Read the `version` field from the package.json at `packageJsonPath`.
+ *
+ * @param packageJsonPath - Filesystem path to a package.json file.
+ * @returns The declared version string, or `0.0.0` when it is absent or not a string.
+ */
+export declare function readCliVersion(packageJsonPath: string): string;
+/**
+ * Format the `--version` line for a build. Appends ` (local)` when the build at
+ * `runningMainPath` is a working copy.
+ *
+ * @param version - The package version string to display.
+ * @param runningMainPath - Path to the running build's entry point.
+ * @returns The version, with a ` (local)` suffix for a working-copy build.
+ */
+export declare function formatCliVersion(version: string, runningMainPath: string): string;
 /**
  * Run the `mindcraft` command line with `argv` (the arguments after the
  * program name). Returns the process exit code.

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAarE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAuBA;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBrE"}

package/dist/cli.js

@@ -1,3 +1,6 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { isLocalBuild } from "./local-redirect.js";
 import { runPublishCommand } from "./publish-command.js";
 import { runUnpackCommand } from "./unpack-command.js";
 import { runVersionCommand } from "./version-command.js";
@@ -7,12 +10,45 @@ commands:
   publish   publish a version of a Mindcraft project to GitHub
   version   increment a Mindcraft project's version in its mindcraft.json
   unpack    convert a .mindcraft export into a publishable project directory
+
+options:
+  -v, --version   print the mindcraft-cli version
 `;
+/** Location of the CLI's own package.json, resolved relative to this module. */
+const OWN_PACKAGE_JSON_URL = new URL("../package.json", import.meta.url);
+/** Location of the running build's entry point, resolved relative to this module. */
+const OWN_MAIN_URL = new URL("main.js", import.meta.url);
+/**
+ * Read the `version` field from the package.json at `packageJsonPath`.
+ *
+ * @param packageJsonPath - Filesystem path to a package.json file.
+ * @returns The declared version string, or `0.0.0` when it is absent or not a string.
+ */
+export function readCliVersion(packageJsonPath) {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    return typeof parsed.version === "string" ? parsed.version : "0.0.0";
+}
+/**
+ * Format the `--version` line for a build. Appends ` (local)` when the build at
+ * `runningMainPath` is a working copy.
+ *
+ * @param version - The package version string to display.
+ * @param runningMainPath - Path to the running build's entry point.
+ * @returns The version, with a ` (local)` suffix for a working-copy build.
+ */
+export function formatCliVersion(version, runningMainPath) {
+    return isLocalBuild(runningMainPath) ? `${version} (local)` : version;
+}
 /**
  * Run the `mindcraft` command line with `argv` (the arguments after the
  * program name). Returns the process exit code.
  */
 export async function runCli(argv) {
+    if (argv.includes("--version") || argv.includes("-v")) {
+        const version = readCliVersion(fileURLToPath(OWN_PACKAGE_JSON_URL));
+        process.stdout.write(`${formatCliVersion(version, fileURLToPath(OWN_MAIN_URL))}\n`);
+        return 0;
+    }
     const [command, ...rest] = argv;
     if (command === "publish") {
         return runPublishCommand(rest);

package/dist/local-redirect.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Locate the built entry point of a local `mindcraft-cli` working copy by
+ * walking up from `startDir`. At each ancestor directory it tests both known
+ * layouts; a candidate qualifies when its `package.json` declares
+ * `name === "mindcraft-cli"` and a `dist/main.js` exists beside it.
+ *
+ * @param startDir - Directory to begin the upward walk from.
+ * @returns Absolute path to the first qualifying candidate's `dist/main.js`, or
+ * undefined when no qualifying candidate exists up to the filesystem root.
+ */
+export declare function findLocalCliMain(startDir: string): string | undefined;
+/** Inputs to {@link shouldRedirect}. */
+export interface ShouldRedirectInput {
+    /** Path to a discovered local build's `dist/main.js`, or undefined when none was found. */
+    localMain: string | undefined;
+    /** Path to the entry point of the build currently executing. */
+    runningMain: string;
+    /** Environment to read the redirect escape hatch and loop-guard from. */
+    env: NodeJS.ProcessEnv;
+}
+/**
+ * Decide whether the running CLI should re-execute a discovered local build.
+ * Returns false when there is no local build, when the redirect is disabled via
+ * {@link NO_REDIRECT_ENV}, when this process is itself a re-exec'd local build
+ * (loop guard via {@link LOCAL_MARKER_ENV}), or when the local build and the
+ * running build are the same file. Both paths are resolved through
+ * `realpathSync` before comparison, so a symlinked global bin still matches the
+ * local build it points at.
+ */
+export declare function shouldRedirect({ localMain, runningMain, env }: ShouldRedirectInput): boolean;
+/**
+ * Report whether the build at `runningMainPath` is a working-copy build. A
+ * working copy keeps `src/` beside `dist/`; a published install ships only
+ * `dist` and `targets.json`, so it has no `src/`. The package root is
+ * `dirname(dirname(runningMainPath))`, i.e. the `.../packages/cli` directory
+ * holding both `dist/` and, in a working copy, `src/`.
+ */
+export declare function isLocalBuild(runningMainPath: string): boolean;
+/**
+ * Re-execute `localMain` as a child of the current Node binary, forwarding
+ * `args` verbatim and inheriting standard streams so pipes and interactive
+ * prompts pass through. The child is marked with {@link LOCAL_MARKER_ENV} to
+ * prevent it from redirecting again.
+ *
+ * @param localMain - Absolute path to the local build's `dist/main.js`.
+ * @param args - Arguments to forward after the program name.
+ * @param baseEnv - Environment to layer the local marker over.
+ * @returns The child's exit code, or `128 + signal number` when it was killed by
+ * a signal.
+ */
+export declare function runLocalBuild(localMain: string, args: readonly string[], baseEnv: NodeJS.ProcessEnv): Promise<number>;
+/**
+ * When the CLI is invoked from within a `mindcraft-lang` checkout (or a repo
+ * embedding it at `external/mindcraft-lang`), transparently re-execute the local
+ * working-copy build in place of the installed one, so a developer exercises
+ * local code by calling `mindcraft` exactly as a user would. Discovery is
+ * anchored at `process.cwd()`.
+ *
+ * This runs local repository code, like `npx` or a project-local `.bin`; the
+ * `name === "mindcraft-cli"` check guards against accidental collision with an
+ * unrelated monorepo that also has a `packages/cli`, and is not a security
+ * boundary against a hostile repository.
+ *
+ * @returns True when a local build was re-executed (in which case
+ * `process.exitCode` has been set from the child); false when the caller should
+ * proceed to run the installed build normally.
+ */
+export declare function maybeRedirectToLocalBuild(): Promise<boolean>;
+//# sourceMappingURL=local-redirect.d.ts.map

package/dist/local-redirect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-redirect.d.ts","sourceRoot":"","sources":["../src/local-redirect.ts"],"names":[],"mappings":"AAwEA;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQrE;AAgBD,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,2FAA2F;IAC3F,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,EAAE,SAAS,EAAE,WAAW,EAAE,GAAG,EAAE,EAAE,mBAAmB,GAAG,OAAO,CAQ5F;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAG7D;AAQD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAWrH;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,OAAO,CAAC,CAiBlE"}

package/dist/local-redirect.js

@@ -0,0 +1,181 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { constants } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/** The `package.json` name a directory must declare to count as a local CLI checkout. */
+const LOCAL_CLI_PACKAGE_NAME = "mindcraft-cli";
+/**
+ * Subdirectories, relative to an ancestor directory, where a local
+ * `mindcraft-cli` package may live: a direct mindcraft-lang checkout keeps it at
+ * `packages/cli`, and a repository embedding the reference checkout keeps it at
+ * `external/mindcraft-lang/packages/cli`.
+ */
+const CLI_SUBPATHS = [
+    path.join("packages", "cli"),
+    path.join("external", "mindcraft-lang", "packages", "cli"),
+];
+/** Environment variable set on a re-exec'd child to break the redirect loop. */
+const LOCAL_MARKER_ENV = "MINDCRAFT_CLI_LOCAL";
+/** Environment variable a developer sets to disable the local-build redirect entirely. */
+const NO_REDIRECT_ENV = "MINDCRAFT_CLI_NO_REDIRECT";
+/** Environment variable that, when set, prints a one-line note naming the local build path. */
+const DEBUG_ENV = "MINDCRAFT_CLI_DEBUG";
+/**
+ * Read a candidate CLI directory's declared name and build presence. Never
+ * throws: a missing or malformed `package.json` yields an undefined name.
+ */
+function inspectCliCandidate(cliDir) {
+    const hasBuild = existsSync(path.join(cliDir, "dist", "main.js"));
+    const packageJsonPath = path.join(cliDir, "package.json");
+    if (!existsSync(packageJsonPath)) {
+        return { name: undefined, hasBuild };
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+        return { name: typeof parsed.name === "string" ? parsed.name : undefined, hasBuild };
+    }
+    catch {
+        return { name: undefined, hasBuild };
+    }
+}
+/**
+ * Yield every candidate `.../packages/cli` directory found by walking from
+ * `startDir` up to the filesystem root, testing both known layouts at each
+ * ancestor.
+ */
+function* ancestorCliDirs(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        for (const subpath of CLI_SUBPATHS) {
+            yield path.join(current, subpath);
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return;
+        }
+        current = parent;
+    }
+}
+/**
+ * Locate the built entry point of a local `mindcraft-cli` working copy by
+ * walking up from `startDir`. At each ancestor directory it tests both known
+ * layouts; a candidate qualifies when its `package.json` declares
+ * `name === "mindcraft-cli"` and a `dist/main.js` exists beside it.
+ *
+ * @param startDir - Directory to begin the upward walk from.
+ * @returns Absolute path to the first qualifying candidate's `dist/main.js`, or
+ * undefined when no qualifying candidate exists up to the filesystem root.
+ */
+export function findLocalCliMain(startDir) {
+    for (const cliDir of ancestorCliDirs(startDir)) {
+        const candidate = inspectCliCandidate(cliDir);
+        if (candidate.name === LOCAL_CLI_PACKAGE_NAME && candidate.hasBuild) {
+            return path.join(cliDir, "dist", "main.js");
+        }
+    }
+    return undefined;
+}
+/**
+ * Report whether a local `mindcraft-cli` checkout exists in the ancestry of
+ * `startDir` but has not been built (no `dist/main.js`).
+ */
+function hasUnbuiltLocalCli(startDir) {
+    for (const cliDir of ancestorCliDirs(startDir)) {
+        const candidate = inspectCliCandidate(cliDir);
+        if (candidate.name === LOCAL_CLI_PACKAGE_NAME && !candidate.hasBuild) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Decide whether the running CLI should re-execute a discovered local build.
+ * Returns false when there is no local build, when the redirect is disabled via
+ * {@link NO_REDIRECT_ENV}, when this process is itself a re-exec'd local build
+ * (loop guard via {@link LOCAL_MARKER_ENV}), or when the local build and the
+ * running build are the same file. Both paths are resolved through
+ * `realpathSync` before comparison, so a symlinked global bin still matches the
+ * local build it points at.
+ */
+export function shouldRedirect({ localMain, runningMain, env }) {
+    if (localMain === undefined) {
+        return false;
+    }
+    if (env[NO_REDIRECT_ENV] !== undefined || env[LOCAL_MARKER_ENV] !== undefined) {
+        return false;
+    }
+    return realpathSync(localMain) !== realpathSync(runningMain);
+}
+/**
+ * Report whether the build at `runningMainPath` is a working-copy build. A
+ * working copy keeps `src/` beside `dist/`; a published install ships only
+ * `dist` and `targets.json`, so it has no `src/`. The package root is
+ * `dirname(dirname(runningMainPath))`, i.e. the `.../packages/cli` directory
+ * holding both `dist/` and, in a working copy, `src/`.
+ */
+export function isLocalBuild(runningMainPath) {
+    const packageRoot = path.dirname(path.dirname(runningMainPath));
+    return existsSync(path.join(packageRoot, "src"));
+}
+/** Map a terminating signal name to the conventional `128 + signal number` exit code. */
+function signalExitCode(signal) {
+    const signalNumber = constants.signals[signal] ?? 0;
+    return 128 + signalNumber;
+}
+/**
+ * Re-execute `localMain` as a child of the current Node binary, forwarding
+ * `args` verbatim and inheriting standard streams so pipes and interactive
+ * prompts pass through. The child is marked with {@link LOCAL_MARKER_ENV} to
+ * prevent it from redirecting again.
+ *
+ * @param localMain - Absolute path to the local build's `dist/main.js`.
+ * @param args - Arguments to forward after the program name.
+ * @param baseEnv - Environment to layer the local marker over.
+ * @returns The child's exit code, or `128 + signal number` when it was killed by
+ * a signal.
+ */
+export function runLocalBuild(localMain, args, baseEnv) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [localMain, ...args], {
+            stdio: "inherit",
+            env: { ...baseEnv, [LOCAL_MARKER_ENV]: "1" },
+        });
+        child.on("error", reject);
+        child.on("exit", (code, signal) => {
+            resolve(signal !== null ? signalExitCode(signal) : (code ?? 0));
+        });
+    });
+}
+/**
+ * When the CLI is invoked from within a `mindcraft-lang` checkout (or a repo
+ * embedding it at `external/mindcraft-lang`), transparently re-execute the local
+ * working-copy build in place of the installed one, so a developer exercises
+ * local code by calling `mindcraft` exactly as a user would. Discovery is
+ * anchored at `process.cwd()`.
+ *
+ * This runs local repository code, like `npx` or a project-local `.bin`; the
+ * `name === "mindcraft-cli"` check guards against accidental collision with an
+ * unrelated monorepo that also has a `packages/cli`, and is not a security
+ * boundary against a hostile repository.
+ *
+ * @returns True when a local build was re-executed (in which case
+ * `process.exitCode` has been set from the child); false when the caller should
+ * proceed to run the installed build normally.
+ */
+export async function maybeRedirectToLocalBuild() {
+    const runningMain = realpathSync(fileURLToPath(new URL("main.js", import.meta.url)));
+    const startDir = process.cwd();
+    const localMain = findLocalCliMain(startDir);
+    if (localMain === undefined || !shouldRedirect({ localMain, runningMain, env: process.env })) {
+        if (localMain === undefined && hasUnbuiltLocalCli(startDir)) {
+            process.stderr.write("mindcraft: local mindcraft-cli found but not built; run npm run build to use it\n");
+        }
+        return false;
+    }
+    if (process.env[DEBUG_ENV] !== undefined) {
+        process.stderr.write(`mindcraft: redirecting to local build at ${localMain}\n`);
+    }
+    process.exitCode = await runLocalBuild(localMain, process.argv.slice(2), process.env);
+    return true;
+}

package/dist/main.js

@@ -1,3 +1,6 @@
 #!/usr/bin/env node
-import { runCli } from "./cli.js";
-process.exitCode = await runCli(process.argv.slice(2));
+import { maybeRedirectToLocalBuild } from "./local-redirect.js";
+if (!(await maybeRedirectToLocalBuild())) {
+    const { runCli } = await import("./cli.js");
+    process.exitCode = await runCli(process.argv.slice(2));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindcraft-cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Command-line tools for Mindcraft projects",
   "license": "MIT",
   "author": "humanapp",