mindcraft-cli 0.1.2

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Run the `mindcraft` command line with `argv` (the arguments after the
+ * program name). Returns the process exit code.
+ */
+export declare function runCli(argv: readonly string[]): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +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"}

package/dist/cli.js

@@ -0,0 +1,28 @@
+import { runPublishCommand } from "./publish-command.js";
+import { runUnpackCommand } from "./unpack-command.js";
+import { runVersionCommand } from "./version-command.js";
+const CLI_USAGE = `usage: mindcraft <command> [arguments]
+
+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
+`;
+/**
+ * Run the `mindcraft` command line with `argv` (the arguments after the
+ * program name). Returns the process exit code.
+ */
+export async function runCli(argv) {
+    const [command, ...rest] = argv;
+    if (command === "publish") {
+        return runPublishCommand(rest);
+    }
+    if (command === "version") {
+        return runVersionCommand(rest);
+    }
+    if (command === "unpack") {
+        return runUnpackCommand(rest);
+    }
+    process.stderr.write(command === undefined ? CLI_USAGE : `mindcraft: unknown command "${command}"\n${CLI_USAGE}`);
+    return 1;
+}

package/dist/git.d.ts

@@ -0,0 +1,15 @@
+/** Error thrown when a git command exits with a nonzero status. */
+export declare class GitCommandError extends Error {
+    constructor(args: readonly string[], stderr: string);
+}
+/**
+ * Run a git command in `cwd` and return its stdout. Throws
+ * {@link GitCommandError} when git exits with a nonzero status.
+ */
+export declare function git(cwd: string, ...args: string[]): Promise<string>;
+/**
+ * Run a git command in `cwd` and return its stdout, or `undefined` when git
+ * exits with a nonzero status.
+ */
+export declare function tryGit(cwd: string, ...args: string[]): Promise<string | undefined>;
+//# sourceMappingURL=git.d.ts.map

package/dist/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAEA,mEAAmE;AACnE,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM;CAIpD;AAED;;;GAGG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAUnE;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CASxF"}

package/dist/git.js

@@ -0,0 +1,39 @@
+import { execFile } from "node:child_process";
+/** Error thrown when a git command exits with a nonzero status. */
+export class GitCommandError extends Error {
+    constructor(args, stderr) {
+        super(`git ${args.join(" ")} failed: ${stderr.trim()}`);
+        this.name = "GitCommandError";
+    }
+}
+/**
+ * Run a git command in `cwd` and return its stdout. Throws
+ * {@link GitCommandError} when git exits with a nonzero status.
+ */
+export function git(cwd, ...args) {
+    return new Promise((resolve, reject) => {
+        execFile("git", args, { cwd, maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => {
+            if (error) {
+                reject(new GitCommandError(args, stderr || error.message));
+            }
+            else {
+                resolve(stdout);
+            }
+        });
+    });
+}
+/**
+ * Run a git command in `cwd` and return its stdout, or `undefined` when git
+ * exits with a nonzero status.
+ */
+export async function tryGit(cwd, ...args) {
+    try {
+        return await git(cwd, ...args);
+    }
+    catch (error) {
+        if (error instanceof GitCommandError) {
+            return undefined;
+        }
+        throw error;
+    }
+}

package/dist/main.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":""}

package/dist/main.js

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

package/dist/publish-command.d.ts

@@ -0,0 +1,54 @@
+/** Stable identifiers for publish command failures beyond the engine's refusals. */
+export declare const PublishCommandErrorCode: {
+    readonly WRITE_BACK_FAILED: "PUBLISH_WRITE_BACK_FAILED";
+};
+/** Union of all {@link PublishCommandErrorCode} values. */
+export type PublishCommandErrorCode = (typeof PublishCommandErrorCode)[keyof typeof PublishCommandErrorCode];
+/** Inputs {@link resolvePublishTarget} decides the publish target from. */
+export interface PublishTargetInput {
+    /** Value of `--remote`, or `undefined` when the flag is absent. */
+    readonly explicitRemote: string | undefined;
+    /**
+     * The `<owner>/<repo>` identity recorded in the project's manifest, or
+     * `undefined` when the manifest records none, is missing, or is invalid.
+     */
+    readonly identity: string | undefined;
+    /**
+     * `true` when the project directory is the repository root of its git
+     * checkout; `false` for a subdirectory of a checkout, or a directory that is
+     * not in a git checkout at all.
+     */
+    readonly isCheckoutRoot: boolean;
+    /** `true` when the project's git checkout has an `origin` remote. */
+    readonly hasOrigin: boolean;
+}
+/** Where a publish records its version, and how the target repository is reached. */
+export type PublishTarget = {
+    readonly mode: "in-place";
+} | {
+    readonly mode: "constructed";
+    readonly remote: string;
+};
+/**
+ * Decide where a publish records its version:
+ * - `--remote` given: constructed mode to that URL.
+ * - no `--remote`, a standalone project (the project directory is the
+ *   repository root of a checkout that has an origin): in-place mode on
+ *   origin, whatever identity the manifest records.
+ * - no `--remote` and not a standalone project (a subdirectory of a checkout,
+ *   or no origin), with a recorded identity: constructed mode to the GitHub
+ *   remote derived from the identity, `https://github.com/<owner>/<repo>.git`.
+ * - no `--remote`, not a standalone project, and no recorded identity:
+ *   in-place mode on origin.
+ *
+ * Always returns a target and does not validate that it can publish; a missing
+ * manifest, an unusable origin, or an identity that cannot be stamped is
+ * refused by the publish the chosen target dispatches to.
+ */
+export declare function resolvePublishTarget(input: PublishTargetInput): PublishTarget;
+/**
+ * Run `mindcraft publish` with the arguments following the subcommand name.
+ * Returns the process exit code.
+ */
+export declare function runPublishCommand(args: readonly string[]): Promise<number>;
+//# sourceMappingURL=publish-command.d.ts.map

package/dist/publish-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-command.d.ts","sourceRoot":"","sources":["../src/publish-command.ts"],"names":[],"mappings":"AA4DA,oFAAoF;AACpF,eAAO,MAAM,uBAAuB;;CAE1B,CAAC;AAEX,2DAA2D;AAC3D,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,OAAO,uBAAuB,CAAC,CAAC;AAkD7G,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,qFAAqF;AACrF,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,CAW7E;AAoMD;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAoDhF"}

package/dist/publish-command.js

@@ -0,0 +1,360 @@
+import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { createJsDelivrExtensionTransport, deriveCoordinateFromRemoteUrl, ExtensionPublishErrorCode, githubRemoteUrlForCoordinate, MINDCRAFT_JSON_PATH, parseProjectContentManifest, publishExtensionVersion, serializeProjectContentManifest, } from "@mindcraft-lang/app-host";
+import { GitCommandError, git, tryGit } from "./git.js";
+const PUBLISH_USAGE = `usage: mindcraft publish [patch|minor|major] [--dir <path>] [--remote <url>] [--allow-unstable-refs]
+
+Publishes a version of the Mindcraft project in --dir (default: the current
+directory). Run from inside an already-published project's folder, no flags are
+needed: the current directory supplies --dir, and the project's git checkout
+supplies the remote. With a version bump, the manifest version is incremented;
+without one, the manifest's current version is published as-is, which is valid
+only as a first publish to a repository that has no tags. Every publish stamps
+the published manifest's identity field with the <owner>/<repo> coordinate of
+the publish remote; a warning is printed when the stamp changes a previously
+recorded identity.
+
+Without --remote, the publish target depends on where the project sits in its
+git checkout. A standalone project, whose directory is the repository root of
+its checkout, publishes to the checkout's origin: it is committed, tagged
+v<version>, and the branch and tag are pushed to origin. A project kept in a
+subdirectory of its checkout (for example inside a monorepo), or one whose
+checkout has no origin, publishes to the GitHub remote derived from the
+manifest's recorded identity, https://github.com/<owner>/<repo>.git. A first
+publish, whose manifest records no identity yet, targets origin.
+
+With --remote, or when the remote is derived from the identity, the project's
+published tree (mindcraft.json plus its manifest-listed files) is committed to
+that remote's default branch and tagged v<version>, and the published version
+and identity are written back to the project directory's mindcraft.json.
+
+  --dir <path>     project directory (default: current directory)
+  --remote <url>   git remote to publish the project tree to; without it a
+                   standalone checkout publishes to its origin, and a
+                   subdirectory project publishes to the GitHub remote derived
+                   from the recorded identity
+  --allow-unstable-refs
+                   allow dependencies that are unstable for consumers: a
+                   branch reference, or a pinned version the fetch source
+                   does not yet serve
+`;
+/** Stable identifiers for publish command failures beyond the engine's refusals. */
+export const PublishCommandErrorCode = {
+    WRITE_BACK_FAILED: "PUBLISH_WRITE_BACK_FAILED",
+};
+const VERSION_BUMPS = ["patch", "minor", "major"];
+function isVersionBump(value) {
+    return VERSION_BUMPS.includes(value);
+}
+function parsePublishArguments(args) {
+    let bump;
+    let dir = process.cwd();
+    let remote;
+    let allowUnstableRefs = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--allow-unstable-refs") {
+            allowUnstableRefs = true;
+        }
+        else if (arg === "--dir" || arg === "--remote") {
+            const value = args[i + 1];
+            if (value === undefined) {
+                return `${arg} requires a value`;
+            }
+            i++;
+            if (arg === "--dir") {
+                dir = path.resolve(value);
+            }
+            else {
+                remote = value;
+            }
+        }
+        else if (isVersionBump(arg)) {
+            if (bump !== undefined) {
+                return `unexpected argument "${arg}"`;
+            }
+            bump = arg;
+        }
+        else {
+            return `unexpected argument "${arg}"`;
+        }
+    }
+    return { bump, dir, remote, allowUnstableRefs };
+}
+/**
+ * Decide where a publish records its version:
+ * - `--remote` given: constructed mode to that URL.
+ * - no `--remote`, a standalone project (the project directory is the
+ *   repository root of a checkout that has an origin): in-place mode on
+ *   origin, whatever identity the manifest records.
+ * - no `--remote` and not a standalone project (a subdirectory of a checkout,
+ *   or no origin), with a recorded identity: constructed mode to the GitHub
+ *   remote derived from the identity, `https://github.com/<owner>/<repo>.git`.
+ * - no `--remote`, not a standalone project, and no recorded identity:
+ *   in-place mode on origin.
+ *
+ * Always returns a target and does not validate that it can publish; a missing
+ * manifest, an unusable origin, or an identity that cannot be stamped is
+ * refused by the publish the chosen target dispatches to.
+ */
+export function resolvePublishTarget(input) {
+    if (input.explicitRemote !== undefined) {
+        return { mode: "constructed", remote: input.explicitRemote };
+    }
+    if (input.isCheckoutRoot && input.hasOrigin) {
+        return { mode: "in-place" };
+    }
+    if (input.identity !== undefined) {
+        return { mode: "constructed", remote: githubRemoteUrlForCoordinate(input.identity) };
+    }
+    return { mode: "in-place" };
+}
+function isFileNotFound(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+/**
+ * Read the `<owner>/<repo>` identity recorded in the project's `mindcraft.json`.
+ * Returns `undefined` when the directory has no manifest, its manifest does not
+ * parse, or it records no identity; a missing or invalid manifest is reported
+ * by the publish itself.
+ */
+async function readRecordedIdentity(dir) {
+    let manifestText;
+    try {
+        manifestText = await readFile(path.join(dir, MINDCRAFT_JSON_PATH), "utf8");
+    }
+    catch (error) {
+        if (isFileNotFound(error))
+            return undefined;
+        throw error;
+    }
+    const parsed = parseProjectContentManifest(manifestText);
+    return parsed.ok ? parsed.manifest.identity : undefined;
+}
+/**
+ * A publish content source over a project directory: the manifest is
+ * `<dir>/mindcraft.json`, and listed files resolve relative to `dir`. Paths
+ * that resolve outside `dir` read as absent.
+ */
+function directoryContentSource(dir) {
+    const root = path.resolve(dir);
+    return {
+        readManifest: async () => {
+            try {
+                return await readFile(path.join(root, MINDCRAFT_JSON_PATH), "utf8");
+            }
+            catch (error) {
+                if (isFileNotFound(error))
+                    return undefined;
+                throw error;
+            }
+        },
+        readFile: async (filePath) => {
+            const resolved = path.resolve(root, filePath);
+            const relative = path.relative(root, resolved);
+            if (relative.startsWith("..") || path.isAbsolute(relative)) {
+                return undefined;
+            }
+            try {
+                return new Uint8Array(await readFile(resolved));
+            }
+            catch (error) {
+                if (isFileNotFound(error))
+                    return undefined;
+                throw error;
+            }
+        },
+    };
+}
+async function writePublishFiles(root, files) {
+    for (const file of files) {
+        const target = path.join(root, file.path);
+        await mkdir(path.dirname(target), { recursive: true });
+        await writeFile(target, file.content);
+    }
+}
+/**
+ * A publish backend over a git checkout whose repository root is `dir`: the
+ * repository's own history defines the published content. Applying a publish
+ * writes the publish files into the checkout, commits them, tags, and pushes
+ * the current branch and the tag to `origin`.
+ */
+function checkoutPublishBackend(dir) {
+    return {
+        isClean: async () => (await git(dir, "status", "--porcelain")).trim() === "",
+        tagExists: async (tag) => {
+            if ((await tryGit(dir, "rev-parse", "--verify", `refs/tags/${tag}`)) !== undefined) {
+                return true;
+            }
+            const remoteTag = await git(dir, "ls-remote", "--tags", "origin", `refs/tags/${tag}`);
+            return remoteTag.trim() !== "";
+        },
+        hasAnyTags: async () => {
+            if ((await git(dir, "tag", "--list")).trim() !== "") {
+                return true;
+            }
+            return (await git(dir, "ls-remote", "--tags", "origin")).trim() !== "";
+        },
+        readHeadManifest: () => tryGit(dir, "show", `HEAD:${MINDCRAFT_JSON_PATH}`),
+        apply: async ({ tag, files }) => {
+            await writePublishFiles(dir, files);
+            await git(dir, "add", "--", ...files.map((file) => file.path));
+            // An as-is publish can leave the tree identical to head; the tag alone
+            // records the publish then.
+            if ((await tryGit(dir, "diff", "--cached", "--quiet")) === undefined) {
+                await git(dir, "commit", "-m", tag);
+            }
+            await git(dir, "tag", tag);
+            await git(dir, "push", "origin", "HEAD", `refs/tags/${tag}`);
+        },
+    };
+}
+/**
+ * A dependency pin probe over the public content CDN: a pin is published
+ * exactly when the CDN serves the repository's `mindcraft.json` at it.
+ */
+function cdnPinProbe() {
+    const transport = createJsDelivrExtensionTransport();
+    return async (owner, repo, pin) => {
+        const result = await transport.fetchFile(owner, repo, pin, MINDCRAFT_JSON_PATH);
+        return result.ok;
+    };
+}
+/**
+ * Publish the checkout at `dir` in place: bump, commit, tag, and push on the
+ * repository the directory itself is a checkout of. The stamped identity
+ * coordinate derives from the checkout's `origin` remote URL.
+ */
+async function publishInCheckout(options) {
+    const originUrl = (await tryGit(options.dir, "remote", "get-url", "origin"))?.trim();
+    return publishExtensionVersion({
+        bump: options.bump,
+        coordinate: originUrl === undefined ? undefined : deriveCoordinateFromRemoteUrl(originUrl),
+        confirmUnstableDependencies: options.allowUnstableRefs,
+        isPinPublished: cdnPinProbe(),
+        source: directoryContentSource(options.dir),
+        backend: checkoutPublishBackend(options.dir),
+    });
+}
+/**
+ * Publish the project directory's manifest-described tree to `remote` through
+ * a temporary clone: the clone's working tree is replaced with the publish
+ * files, committed to the remote's default branch, tagged, and pushed. The
+ * stamped identity coordinate derives from the `remote` URL.
+ */
+async function publishToRemote(options, remote) {
+    const scratch = await mkdtemp(path.join(tmpdir(), "mindcraft-publish-"));
+    try {
+        const clone = path.join(scratch, "repo");
+        await git(scratch, "clone", "--quiet", remote, clone);
+        const branch = (await git(clone, "symbolic-ref", "--short", "HEAD")).trim();
+        const backend = {
+            isClean: async () => true,
+            tagExists: async (tag) => (await tryGit(clone, "rev-parse", "--verify", `refs/tags/${tag}`)) !== undefined,
+            hasAnyTags: async () => (await git(clone, "tag", "--list")).trim() !== "",
+            readHeadManifest: async () => {
+                try {
+                    return await readFile(path.join(clone, MINDCRAFT_JSON_PATH), "utf8");
+                }
+                catch (error) {
+                    if (isFileNotFound(error))
+                        return undefined;
+                    throw error;
+                }
+            },
+            apply: async ({ tag, files }) => {
+                for (const entry of await readdir(clone)) {
+                    if (entry === ".git")
+                        continue;
+                    await rm(path.join(clone, entry), { recursive: true, force: true });
+                }
+                await writePublishFiles(clone, files);
+                await git(clone, "add", "--all");
+                await git(clone, "commit", "-m", tag);
+                await git(clone, "tag", tag);
+                await git(clone, "push", "--quiet", "origin", branch, `refs/tags/${tag}`);
+            },
+        };
+        return await publishExtensionVersion({
+            bump: options.bump,
+            coordinate: deriveCoordinateFromRemoteUrl(remote),
+            confirmUnstableDependencies: options.allowUnstableRefs,
+            isPinPublished: cdnPinProbe(),
+            source: directoryContentSource(options.dir),
+            backend,
+        });
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+/**
+ * Write a successful publish's version and stamped identity into the source
+ * directory's `mindcraft.json` through the manifest serializer, leaving every
+ * other field as parsed. Throws when the manifest cannot be read, parsed, or
+ * written.
+ */
+async function writeBackPublishedManifest(dir, version, identity) {
+    const manifestPath = path.join(dir, MINDCRAFT_JSON_PATH);
+    const parsed = parseProjectContentManifest(await readFile(manifestPath, "utf8"));
+    if (!parsed.ok) {
+        throw new Error(`${manifestPath} is no longer a valid content manifest`);
+    }
+    await writeFile(manifestPath, serializeProjectContentManifest({ ...parsed.manifest, version, identity }));
+}
+/**
+ * Run `mindcraft publish` with the arguments following the subcommand name.
+ * Returns the process exit code.
+ */
+export async function runPublishCommand(args) {
+    const parsed = parsePublishArguments(args);
+    if (typeof parsed === "string") {
+        process.stderr.write(`mindcraft publish: ${parsed}\n${PUBLISH_USAGE}`);
+        return 1;
+    }
+    try {
+        const originUrl = (await tryGit(parsed.dir, "remote", "get-url", "origin"))?.trim();
+        // --show-prefix is the project directory's path relative to its checkout's
+        // repository root: empty at the root, and absent outside any checkout.
+        const checkoutPrefix = (await tryGit(parsed.dir, "rev-parse", "--show-prefix"))?.trim();
+        const target = resolvePublishTarget({
+            explicitRemote: parsed.remote,
+            identity: await readRecordedIdentity(parsed.dir),
+            isCheckoutRoot: checkoutPrefix === "",
+            hasOrigin: originUrl !== undefined,
+        });
+        const result = target.mode === "constructed" ? await publishToRemote(parsed, target.remote) : await publishInCheckout(parsed);
+        if (!result.ok) {
+            process.stderr.write(`mindcraft publish: ${result.error.code}: ${result.error.message}\n`);
+            if (result.error.code === ExtensionPublishErrorCode.UNSTABLE_DEPENDENCIES_UNCONFIRMED) {
+                process.stderr.write("Pass --allow-unstable-refs to publish anyway.\n");
+            }
+            return 1;
+        }
+        if (result.previousIdentity !== undefined) {
+            process.stderr.write(`warning: identity changed: ${result.previousIdentity} -> ${result.identity}\n`);
+        }
+        if (target.mode === "constructed") {
+            try {
+                await writeBackPublishedManifest(parsed.dir, result.version, result.identity);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                process.stderr.write(`mindcraft publish: ${PublishCommandErrorCode.WRITE_BACK_FAILED}: version ${result.version} was ` +
+                    `published (tag ${result.tag}), but writing it back to ${path.join(parsed.dir, MINDCRAFT_JSON_PATH)} ` +
+                    `failed: ${message}\n`);
+                return 1;
+            }
+        }
+        process.stdout.write(`published ${result.version} (tag ${result.tag})\n`);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof GitCommandError) {
+            process.stderr.write(`mindcraft publish: ${error.message}\n`);
+            return 1;
+        }
+        throw error;
+    }
+}

package/dist/target-registry.d.ts

@@ -0,0 +1,87 @@
+import type { ExtensionCatalogDocumentError, ExtensionCatalogDocumentWarning } from "@mindcraft-lang/app-host";
+/** Stable identifiers for target registry failures. */
+export declare const TargetRegistryErrorCode: {
+    /** The bundled registry file could not be read from disk. */
+    readonly REGISTRY_UNREADABLE: "TARGET_REGISTRY_UNREADABLE";
+    /** The registry content did not validate as a clean catalog document. */
+    readonly REGISTRY_PARSE_FAILED: "TARGET_REGISTRY_PARSE_FAILED";
+    /** A requested coordinate is not present in the registry. */
+    readonly UNKNOWN_TARGET_COORDINATE: "TARGET_REGISTRY_UNKNOWN_COORDINATE";
+};
+/** Union of all {@link TargetRegistryErrorCode} values. */
+export type TargetRegistryErrorCode = (typeof TargetRegistryErrorCode)[keyof typeof TargetRegistryErrorCode];
+/**
+ * Failure raised by {@link loadTargetRegistry}, {@link parseTargetRegistry},
+ * and {@link TargetRegistry.resolve}. Match on {@link code}; the message is
+ * secondary human context.
+ */
+export declare class TargetRegistryError extends Error {
+    /** Stable machine-readable failure code. */
+    readonly code: TargetRegistryErrorCode;
+    /** Parser errors that rejected the document, when {@link code} is `REGISTRY_PARSE_FAILED`. */
+    readonly parseErrors: readonly ExtensionCatalogDocumentError[];
+    /** Parser warnings treated as failures, when {@link code} is `REGISTRY_PARSE_FAILED`. */
+    readonly parseWarnings: readonly ExtensionCatalogDocumentWarning[];
+    /**
+     * @param code - Stable failure code.
+     * @param message - Human-readable failure context.
+     * @param details - Parser diagnostics carried for a parse failure.
+     */
+    constructor(code: TargetRegistryErrorCode, message: string, details?: {
+        readonly parseErrors?: readonly ExtensionCatalogDocumentError[];
+        readonly parseWarnings?: readonly ExtensionCatalogDocumentWarning[];
+    });
+}
+/** One published target the CLI can resolve to its pinned content. */
+export interface TargetRegistryEntry {
+    /** The target's `<owner>/<repo>` coordinate. */
+    readonly coordinate: string;
+    /** Display name shown for the target. */
+    readonly name: string;
+    /** Published version the pin corresponds to. */
+    readonly version: string;
+    /** Description shown for the target. */
+    readonly description: string;
+    /** Pinned reference `gh:<coordinate>@<full 40-character commit SHA>`. */
+    readonly ref: string;
+}
+/**
+ * The set of targets the CLI ships, each pinned to exact content. Construct one
+ * with {@link loadTargetRegistry} or {@link parseTargetRegistry}.
+ */
+export declare class TargetRegistry {
+    /** The registry's entries, in document order. */
+    readonly entries: readonly TargetRegistryEntry[];
+    /** @param entries - Validated registry entries in document order. */
+    constructor(entries: readonly TargetRegistryEntry[]);
+    /**
+     * Resolve a target coordinate to its pinned reference string.
+     *
+     * @param coordinate - An `<owner>/<repo>` target coordinate.
+     * @returns The entry's `gh:<coordinate>@<sha>` pin.
+     * @throws {TargetRegistryError} With code `UNKNOWN_TARGET_COORDINATE` when the
+     * coordinate is not in the registry.
+     */
+    resolve(coordinate: string): string;
+}
+/**
+ * Build a {@link TargetRegistry} from catalog document text. Any parser error
+ * or warning is a failure: an unknown-kind entry the catalog parser skips with
+ * a warning would silently vanish, so a warning rejects the whole document.
+ *
+ * @param content - JSON text of a `mindcraft.catalog/1` document.
+ * @throws {TargetRegistryError} With code `REGISTRY_PARSE_FAILED` when the
+ * content does not validate cleanly.
+ */
+export declare function parseTargetRegistry(content: string): TargetRegistry;
+/**
+ * Load the registry bundled with the CLI. The file is read relative to this
+ * module, so resolution is identical whether the CLI runs from npm, from the
+ * built `dist/`, or from `src/` in development, and does not depend on the
+ * caller's working directory.
+ *
+ * @throws {TargetRegistryError} With code `REGISTRY_UNREADABLE` when the file
+ * cannot be read, or `REGISTRY_PARSE_FAILED` when it does not validate cleanly.
+ */
+export declare function loadTargetRegistry(): TargetRegistry;
+//# sourceMappingURL=target-registry.d.ts.map

package/dist/target-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-registry.d.ts","sourceRoot":"","sources":["../src/target-registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,6BAA6B,EAAE,+BAA+B,EAAE,MAAM,0BAA0B,CAAC;AAG/G,uDAAuD;AACvD,eAAO,MAAM,uBAAuB;IAClC,6DAA6D;;IAE7D,yEAAyE;;IAEzE,6DAA6D;;CAErD,CAAC;AAEX,2DAA2D;AAC3D,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,OAAO,uBAAuB,CAAC,CAAC;AAE7G;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,8FAA8F;IAC9F,QAAQ,CAAC,WAAW,EAAE,SAAS,6BAA6B,EAAE,CAAC;IAC/D,yFAAyF;IACzF,QAAQ,CAAC,aAAa,EAAE,SAAS,+BAA+B,EAAE,CAAC;IAEnE;;;;OAIG;gBAED,IAAI,EAAE,uBAAuB,EAC7B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,6BAA6B,EAAE,CAAC;QAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,+BAA+B,EAAE,CAAC;KACrE;CAQJ;AAED,sEAAsE;AACtE,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wCAAwC;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,qBAAa,cAAc;IACzB,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAEjD,qEAAqE;gBACzD,OAAO,EAAE,SAAS,mBAAmB,EAAE;IAInD;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;CAUpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAwBnE;AAKD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,cAAc,CAWnD"}

package/dist/target-registry.js

@@ -0,0 +1,110 @@
+import { readFileSync } from "node:fs";
+import { parseExtensionCatalogDocument } from "@mindcraft-lang/app-host";
+/** Stable identifiers for target registry failures. */
+export const TargetRegistryErrorCode = {
+    /** The bundled registry file could not be read from disk. */
+    REGISTRY_UNREADABLE: "TARGET_REGISTRY_UNREADABLE",
+    /** The registry content did not validate as a clean catalog document. */
+    REGISTRY_PARSE_FAILED: "TARGET_REGISTRY_PARSE_FAILED",
+    /** A requested coordinate is not present in the registry. */
+    UNKNOWN_TARGET_COORDINATE: "TARGET_REGISTRY_UNKNOWN_COORDINATE",
+};
+/**
+ * Failure raised by {@link loadTargetRegistry}, {@link parseTargetRegistry},
+ * and {@link TargetRegistry.resolve}. Match on {@link code}; the message is
+ * secondary human context.
+ */
+export class TargetRegistryError extends Error {
+    /** Stable machine-readable failure code. */
+    code;
+    /** Parser errors that rejected the document, when {@link code} is `REGISTRY_PARSE_FAILED`. */
+    parseErrors;
+    /** Parser warnings treated as failures, when {@link code} is `REGISTRY_PARSE_FAILED`. */
+    parseWarnings;
+    /**
+     * @param code - Stable failure code.
+     * @param message - Human-readable failure context.
+     * @param details - Parser diagnostics carried for a parse failure.
+     */
+    constructor(code, message, details) {
+        super(message);
+        this.name = "TargetRegistryError";
+        this.code = code;
+        this.parseErrors = details?.parseErrors ?? [];
+        this.parseWarnings = details?.parseWarnings ?? [];
+    }
+}
+/**
+ * The set of targets the CLI ships, each pinned to exact content. Construct one
+ * with {@link loadTargetRegistry} or {@link parseTargetRegistry}.
+ */
+export class TargetRegistry {
+    /** The registry's entries, in document order. */
+    entries;
+    /** @param entries - Validated registry entries in document order. */
+    constructor(entries) {
+        this.entries = entries;
+    }
+    /**
+     * Resolve a target coordinate to its pinned reference string.
+     *
+     * @param coordinate - An `<owner>/<repo>` target coordinate.
+     * @returns The entry's `gh:<coordinate>@<sha>` pin.
+     * @throws {TargetRegistryError} With code `UNKNOWN_TARGET_COORDINATE` when the
+     * coordinate is not in the registry.
+     */
+    resolve(coordinate) {
+        const entry = this.entries.find((candidate) => candidate.coordinate === coordinate);
+        if (entry === undefined) {
+            throw new TargetRegistryError(TargetRegistryErrorCode.UNKNOWN_TARGET_COORDINATE, `No target "${coordinate}" is in the registry.`);
+        }
+        return entry.ref;
+    }
+}
+/**
+ * Build a {@link TargetRegistry} from catalog document text. Any parser error
+ * or warning is a failure: an unknown-kind entry the catalog parser skips with
+ * a warning would silently vanish, so a warning rejects the whole document.
+ *
+ * @param content - JSON text of a `mindcraft.catalog/1` document.
+ * @throws {TargetRegistryError} With code `REGISTRY_PARSE_FAILED` when the
+ * content does not validate cleanly.
+ */
+export function parseTargetRegistry(content) {
+    const result = parseExtensionCatalogDocument(content);
+    if (!result.ok) {
+        throw new TargetRegistryError(TargetRegistryErrorCode.REGISTRY_PARSE_FAILED, "Target registry document did not validate.", { parseErrors: result.errors });
+    }
+    if (result.warnings.length > 0) {
+        throw new TargetRegistryError(TargetRegistryErrorCode.REGISTRY_PARSE_FAILED, "Target registry document produced warnings, which are not accepted.", { parseWarnings: result.warnings });
+    }
+    const entries = result.document.entries.map((entry) => ({
+        coordinate: entry.coordinate,
+        name: entry.name,
+        version: entry.version,
+        description: entry.description,
+        ref: entry.ref,
+    }));
+    return new TargetRegistry(entries);
+}
+/** Location of the bundled registry file, resolved relative to this module. */
+const REGISTRY_FILE_URL = new URL("../targets.json", import.meta.url);
+/**
+ * Load the registry bundled with the CLI. The file is read relative to this
+ * module, so resolution is identical whether the CLI runs from npm, from the
+ * built `dist/`, or from `src/` in development, and does not depend on the
+ * caller's working directory.
+ *
+ * @throws {TargetRegistryError} With code `REGISTRY_UNREADABLE` when the file
+ * cannot be read, or `REGISTRY_PARSE_FAILED` when it does not validate cleanly.
+ */
+export function loadTargetRegistry() {
+    let content;
+    try {
+        content = readFileSync(REGISTRY_FILE_URL, "utf8");
+    }
+    catch {
+        throw new TargetRegistryError(TargetRegistryErrorCode.REGISTRY_UNREADABLE, `Could not read the target registry at ${REGISTRY_FILE_URL.pathname}.`);
+    }
+    return parseTargetRegistry(content);
+}

package/dist/unpack-command.d.ts

@@ -0,0 +1,15 @@
+/** Stable identifiers for unpack refusals. */
+export declare const UnpackErrorCode: {
+    readonly DOCUMENT_MISSING: "UNPACK_DOCUMENT_MISSING";
+    readonly DOCUMENT_INVALID: "UNPACK_DOCUMENT_INVALID";
+    readonly INVALID_COORDINATE: "UNPACK_INVALID_COORDINATE";
+    readonly TARGET_DIR_NOT_EMPTY: "UNPACK_TARGET_DIR_NOT_EMPTY";
+};
+/** Union of all {@link UnpackErrorCode} values. */
+export type UnpackErrorCode = (typeof UnpackErrorCode)[keyof typeof UnpackErrorCode];
+/**
+ * Run `mindcraft unpack` with the arguments following the subcommand name.
+ * Returns the process exit code.
+ */
+export declare function runUnpackCommand(args: readonly string[]): Promise<number>;
+//# sourceMappingURL=unpack-command.d.ts.map

package/dist/unpack-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unpack-command.d.ts","sourceRoot":"","sources":["../src/unpack-command.ts"],"names":[],"mappings":"AA6BA,8CAA8C;AAC9C,eAAO,MAAM,eAAe;;;;;CAKlB,CAAC;AAEX,mDAAmD;AACnD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AA0HrF;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAqE/E"}

package/dist/unpack-command.js

@@ -0,0 +1,178 @@
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { isExtensionCoordinate, MINDCRAFT_JSON_PATH, serializeProjectContentManifest, validateProjectContentManifest, } from "@mindcraft-lang/app-host";
+import { parseMindcraftProjectDocument } from "@mindcraft-lang/service-api";
+const UNPACK_USAGE = `usage: mindcraft unpack <file.mindcraft> [dir] [--coordinate <owner/repo>] [--force]
+
+Converts a .mindcraft export document into a publishable project directory:
+the document's embedded manifest is written as mindcraft.json and every file
+in its contents is written to disk. A manifest that declares no files list
+gets one naming every unpacked file, including scratch files that happened to
+be in the exported workspace; prune mindcraft.json before publishing. After
+this graduation the repository is the canonical project -- re-exporting from
+the app is a release ritual, not a sync.
+
+  dir                          target directory (default: the document's base
+                               name, in the current directory)
+  --coordinate <owner/repo>    record the project's own published identity in
+                               the manifest's identity field
+  --force                      unpack into a non-empty target directory
+`;
+/** Stable identifiers for unpack refusals. */
+export const UnpackErrorCode = {
+    DOCUMENT_MISSING: "UNPACK_DOCUMENT_MISSING",
+    DOCUMENT_INVALID: "UNPACK_DOCUMENT_INVALID",
+    INVALID_COORDINATE: "UNPACK_INVALID_COORDINATE",
+    TARGET_DIR_NOT_EMPTY: "UNPACK_TARGET_DIR_NOT_EMPTY",
+};
+function parseUnpackArguments(args) {
+    const positional = [];
+    let coordinate;
+    let force = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--force") {
+            force = true;
+        }
+        else if (arg === "--coordinate") {
+            const value = args[i + 1];
+            if (value === undefined) {
+                return `${arg} requires a value`;
+            }
+            i++;
+            coordinate = value;
+        }
+        else if (arg.startsWith("--")) {
+            return `unexpected argument "${arg}"`;
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    if (positional.length === 0) {
+        return "expected a .mindcraft document to unpack";
+    }
+    if (positional.length > 2) {
+        return `unexpected argument "${positional[2]}"`;
+    }
+    const file = path.resolve(positional[0]);
+    const dir = positional[1] !== undefined
+        ? path.resolve(positional[1])
+        : path.resolve(path.basename(positional[0], path.extname(positional[0])));
+    return { file, dir, coordinate, force };
+}
+/**
+ * Assemble the published-repo tree from a validated document: the document's
+ * contents plus its embedded manifest, with the identity recorded when a
+ * coordinate is given and a files list synthesized from the contents when the
+ * manifest declares none.
+ */
+function buildUnpackedTree(document, coordinate) {
+    const validated = validateProjectContentManifest(document.manifest);
+    if (!validated.ok) {
+        const details = validated.errors.map((error) => `${error.code} at ${error.path}: ${error.message}`).join(" ");
+        return {
+            code: UnpackErrorCode.DOCUMENT_INVALID,
+            message: `The document's embedded manifest is not a valid content manifest. ${details}`,
+        };
+    }
+    const files = Object.entries(document.contents)
+        .filter(([filePath]) => filePath !== MINDCRAFT_JSON_PATH)
+        .map(([filePath, content]) => ({ path: filePath, content }));
+    const declaredFilesList = validated.manifest.files !== undefined;
+    const manifest = {
+        ...validated.manifest,
+        ...(coordinate !== undefined ? { identity: coordinate } : {}),
+        ...(declaredFilesList ? {} : { files: files.map((file) => file.path) }),
+    };
+    return { manifestText: serializeProjectContentManifest(manifest), files, declaredFilesList };
+}
+function isRefusal(value) {
+    return "code" in value;
+}
+/** Refuse an unusable target: an existing non-directory, or a non-empty directory without `force`. */
+async function checkTargetDir(dir, force) {
+    let info;
+    try {
+        info = await stat(dir);
+    }
+    catch {
+        return undefined;
+    }
+    if (!info.isDirectory()) {
+        return {
+            code: UnpackErrorCode.TARGET_DIR_NOT_EMPTY,
+            message: `Target "${dir}" exists and is not a directory.`,
+        };
+    }
+    if (!force && (await readdir(dir)).length > 0) {
+        return {
+            code: UnpackErrorCode.TARGET_DIR_NOT_EMPTY,
+            message: `Target directory "${dir}" is not empty; pass --force to unpack into it anyway.`,
+        };
+    }
+    return undefined;
+}
+/**
+ * Run `mindcraft unpack` with the arguments following the subcommand name.
+ * Returns the process exit code.
+ */
+export async function runUnpackCommand(args) {
+    const parsed = parseUnpackArguments(args);
+    if (typeof parsed === "string") {
+        process.stderr.write(`mindcraft unpack: ${parsed}\n${UNPACK_USAGE}`);
+        return 1;
+    }
+    const refuse = (refusal) => {
+        process.stderr.write(`mindcraft unpack: ${refusal.code}: ${refusal.message}\n`);
+        return 1;
+    };
+    if (parsed.coordinate !== undefined && !isExtensionCoordinate(parsed.coordinate)) {
+        return refuse({
+            code: UnpackErrorCode.INVALID_COORDINATE,
+            message: `--coordinate must be "<owner>/<repo>", got "${parsed.coordinate}".`,
+        });
+    }
+    let text;
+    try {
+        text = await readFile(parsed.file, "utf8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return refuse({
+            code: UnpackErrorCode.DOCUMENT_MISSING,
+            message: `Cannot read "${parsed.file}": ${message}`,
+        });
+    }
+    const documentResult = parseMindcraftProjectDocument(text);
+    if (!documentResult.ok) {
+        const details = documentResult.errors.map((error) => `${error.code} at ${error.path}: ${error.message}`).join(" ");
+        return refuse({
+            code: UnpackErrorCode.DOCUMENT_INVALID,
+            message: `"${parsed.file}" is not a valid .mindcraft project document. ${details}`,
+        });
+    }
+    const tree = buildUnpackedTree(documentResult.document, parsed.coordinate);
+    if (isRefusal(tree)) {
+        return refuse(tree);
+    }
+    const targetRefusal = await checkTargetDir(parsed.dir, parsed.force);
+    if (targetRefusal !== undefined) {
+        return refuse(targetRefusal);
+    }
+    await mkdir(parsed.dir, { recursive: true });
+    for (const file of tree.files) {
+        const target = path.join(parsed.dir, file.path);
+        await mkdir(path.dirname(target), { recursive: true });
+        await writeFile(target, file.content, "utf8");
+    }
+    await writeFile(path.join(parsed.dir, MINDCRAFT_JSON_PATH), tree.manifestText, "utf8");
+    process.stdout.write(`unpacked ${tree.files.length} project files and ${MINDCRAFT_JSON_PATH} into ${parsed.dir}\n`);
+    if (!tree.declaredFilesList && tree.files.length > 0) {
+        process.stdout.write("note: the manifest's files list names everything the export carried, including scratch\n" +
+            "files; prune mindcraft.json before publishing.\n");
+    }
+    process.stdout.write("The unpacked repository is now the canonical project; re-exporting from the app is a\n" +
+        "release ritual, not a sync.\n");
+    return 0;
+}

package/dist/version-command.d.ts

@@ -0,0 +1,15 @@
+/** Stable identifiers for version command failures. */
+export declare const VersionCommandErrorCode: {
+    readonly MANIFEST_MISSING: "VERSION_MANIFEST_MISSING";
+    readonly MANIFEST_INVALID: "VERSION_MANIFEST_INVALID";
+};
+/** Union of all {@link VersionCommandErrorCode} values. */
+export type VersionCommandErrorCode = (typeof VersionCommandErrorCode)[keyof typeof VersionCommandErrorCode];
+/**
+ * Run `mindcraft version` with the arguments following the subcommand name:
+ * read the project's `mindcraft.json`, increment its version by the named
+ * component through the shared bump engine, and write it back. Returns the
+ * process exit code.
+ */
+export declare function runVersionCommand(args: readonly string[]): Promise<number>;
+//# sourceMappingURL=version-command.d.ts.map

package/dist/version-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-command.d.ts","sourceRoot":"","sources":["../src/version-command.ts"],"names":[],"mappings":"AAoBA,uDAAuD;AACvD,eAAO,MAAM,uBAAuB;;;CAG1B,CAAC;AAEX,2DAA2D;AAC3D,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,OAAO,uBAAuB,CAAC,CAAC;AA+C7G;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAmChF"}

package/dist/version-command.js

@@ -0,0 +1,88 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { bumpVersion, MINDCRAFT_JSON_PATH, parseProjectContentManifest, serializeProjectContentManifest, } from "@mindcraft-lang/app-host";
+const VERSION_USAGE = `usage: mindcraft version <patch|minor|major> [--dir <path>]
+
+Increments the version of the Mindcraft project in --dir (default: the current
+directory) by the named component and writes it back to the project's
+mindcraft.json. Run this before packaging a target so the built bundle is baked
+at the new version; the target is then published verbatim, without a bump.
+
+  --dir <path>     project directory (default: current directory)
+`;
+/** Stable identifiers for version command failures. */
+export const VersionCommandErrorCode = {
+    MANIFEST_MISSING: "VERSION_MANIFEST_MISSING",
+    MANIFEST_INVALID: "VERSION_MANIFEST_INVALID",
+};
+const VERSION_BUMPS = ["patch", "minor", "major"];
+function isVersionBump(value) {
+    return VERSION_BUMPS.includes(value);
+}
+function parseVersionArguments(args) {
+    let bump;
+    let dir = process.cwd();
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--dir") {
+            const value = args[i + 1];
+            if (value === undefined) {
+                return `${arg} requires a value`;
+            }
+            i++;
+            dir = path.resolve(value);
+        }
+        else if (isVersionBump(arg)) {
+            if (bump !== undefined) {
+                return `unexpected argument "${arg}"`;
+            }
+            bump = arg;
+        }
+        else {
+            return `unexpected argument "${arg}"`;
+        }
+    }
+    if (bump === undefined) {
+        return "a version component (patch, minor, or major) is required";
+    }
+    return { bump, dir };
+}
+function isFileNotFound(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+/**
+ * Run `mindcraft version` with the arguments following the subcommand name:
+ * read the project's `mindcraft.json`, increment its version by the named
+ * component through the shared bump engine, and write it back. Returns the
+ * process exit code.
+ */
+export async function runVersionCommand(args) {
+    const parsed = parseVersionArguments(args);
+    if (typeof parsed === "string") {
+        process.stderr.write(`mindcraft version: ${parsed}\n${VERSION_USAGE}`);
+        return 1;
+    }
+    const manifestPath = path.join(parsed.dir, MINDCRAFT_JSON_PATH);
+    let manifestText;
+    try {
+        manifestText = await readFile(manifestPath, "utf8");
+    }
+    catch (error) {
+        if (isFileNotFound(error)) {
+            process.stderr.write(`mindcraft version: ${VersionCommandErrorCode.MANIFEST_MISSING}: ${manifestPath} does not exist.\n`);
+            return 1;
+        }
+        throw error;
+    }
+    const parseResult = parseProjectContentManifest(manifestText);
+    if (!parseResult.ok) {
+        const details = parseResult.errors.map((error) => `${error.code} at ${error.path}: ${error.message}`).join(" ");
+        process.stderr.write(`mindcraft version: ${VersionCommandErrorCode.MANIFEST_INVALID}: ${manifestPath} is not a valid ` +
+            `content manifest. ${details}\n`);
+        return 1;
+    }
+    const next = bumpVersion(parseResult.manifest.version, parsed.bump);
+    await writeFile(manifestPath, serializeProjectContentManifest({ ...parseResult.manifest, version: next }));
+    process.stdout.write(`version ${next}\n`);
+    return 0;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "mindcraft-cli",
+  "version": "0.1.2",
+  "description": "Command-line tools for Mindcraft projects",
+  "license": "MIT",
+  "author": "humanapp",
+  "type": "module",
+  "files": [
+    "dist",
+    "targets.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "mindcraft": "dist/main.js"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "build:prod": "tsc --build tsconfig.prod.json",
+    "clean": "tsc --build --clean",
+    "watch": "tsc --build --watch",
+    "lint:only": "biome lint ./src",
+    "check:only": "biome check ./src",
+    "format:only": "biome format ./src",
+    "lint": "biome lint ./src --write",
+    "check": "biome check ./src --write",
+    "format": "biome format ./src --write",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.spec.json",
+    "pretest": "npm run build:prod",
+    "test": "tsx --tsconfig tsconfig.spec.json --test $(find src -name '*.spec.ts')",
+    "release:patch": "node ../../scripts/release.js patch",
+    "release:minor": "node ../../scripts/release.js minor",
+    "release:major": "node ../../scripts/release.js major"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.15",
+    "@types/node": "^25.3.0",
+    "tsx": "^4.21.0",
+    "typescript": "~5.9.3"
+  },
+  "dependencies": {
+    "@mindcraft-lang/app-host": "^0.2.2",
+    "@mindcraft-lang/service-api": "^0.2.1"
+  }
+}

package/targets.json

@@ -0,0 +1,14 @@
+{
+  "format": "mindcraft.catalog/1",
+  "entries": [
+    {
+      "kind": "target",
+      "coordinate": "mindcraft-lang/trg-microbit-v2",
+      "ref": "gh:mindcraft-lang/trg-microbit-v2@c6cfc18d88a6c475be7af63cd6529480d444d8e4",
+      "name": "micro:bit v2",
+      "version": "0.7.0",
+      "description": "Program the BBC micro:bit (v2) with Mindcraft.",
+      "alias": "microbit-v2"
+    }
+  ]
+}