create-mostra 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,20 @@
+# create-mostra
+
+Create a [Mostra](https://github.com/mostra-dev/mostra) artifact:
+
+```sh
+npm create mostra@latest my-artifact
+```
+
+The first run downloads Mostra's runtime for your platform (about 200 MB, macOS and Linux),
+checks it against the SHA-256 its release pins, and caches it; later runs reuse it. Mostra runs on
+its own Node.js, so the version you have doesn't matter. Then:
+
+```sh
+npx @mostra/cli verify my-artifact
+npx @mostra/cli publish my-artifact
+```
+
+Every flag after `--` is `mostra new`'s, for example `npm create mostra@latest review -- --title "Q3 review"`.
+
+Part of Mostra, the agent artifact runtime. Apache-2.0.

package/dist/bin.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/bin.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { i as create } from "./src-Db8IadT7.js";
+//#region src/bin.ts
+/** `create-mostra`'s binary: `npm create mostra [dir]` (see `index.ts`). */
+process.stdout.on("error", () => {});
+process.stderr.on("error", () => {});
+const code = await create({
+	args: process.argv.slice(2),
+	cwd: process.cwd(),
+	env: process.env,
+	stdout: (text) => {
+		process.stdout.write(text);
+	},
+	stderr: (text) => {
+		process.stderr.write(text);
+	},
+	terminal: process.stdin.isTTY === true || process.stdout.isTTY === true || process.stderr.isTTY === true
+});
+process.stdout.write("", () => process.exit(code));
+//#endregion
+export {};
+
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","names":[],"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\n/** `create-mostra`'s binary: `npm create mostra [dir]` (see `index.ts`). */\nimport { create } from \"./index.ts\";\n\nprocess.stdout.on(\"error\", () => {});\nprocess.stderr.on(\"error\", () => {});\nconst code = await create({\n  args: process.argv.slice(2),\n  cwd: process.cwd(),\n  env: process.env,\n  stdout: (text) => {\n    process.stdout.write(text);\n  },\n  stderr: (text) => {\n    process.stderr.write(text);\n  },\n  terminal:\n    process.stdin.isTTY === true || process.stdout.isTTY === true || process.stderr.isTTY === true,\n});\nprocess.stdout.write(\"\", () => process.exit(code));\n"],"mappings":";;;;AAIA,QAAQ,OAAO,GAAG,eAAe,CAAC,CAAC;AACnC,QAAQ,OAAO,GAAG,eAAe,CAAC,CAAC;AACnC,MAAM,OAAO,MAAM,OAAO;CACxB,MAAM,QAAQ,KAAK,MAAM,CAAC;CAC1B,KAAK,QAAQ,IAAI;CACjB,KAAK,QAAQ;CACb,SAAS,SAAS;EAChB,QAAQ,OAAO,MAAM,IAAI;CAC3B;CACA,SAAS,SAAS;EAChB,QAAQ,OAAO,MAAM,IAAI;CAC3B;CACA,UACE,QAAQ,MAAM,UAAU,QAAQ,QAAQ,OAAO,UAAU,QAAQ,QAAQ,OAAO,UAAU;AAC9F,CAAC;AACD,QAAQ,OAAO,MAAM,UAAU,QAAQ,KAAK,IAAI,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+//#region src/index.d.ts
+/** The directory an artifact goes into when none is named. */
+export declare const DEFAULT_DIR: string;
+/** What one run does: the `mostra` arguments, and the directory it creates. */
+export interface CreatePlan {
+  /** The arguments for `mostra`: `new <dir>` and the flags passed on. */
+  readonly argv: readonly string[];
+  /** The artifact's directory, absolute. */
+  readonly dir: string;
+  /** Whether `--json` was given: then stdout is exactly the CLI's envelope. */
+  readonly json: boolean;
+  /** Whether to print this package's usage instead. */
+  readonly help: boolean;
+}
+/**
+ * Plans a run from `npm create mostra [dir] -- [flags]`: the first argument that isn't a flag is
+ * the directory (else {@link DEFAULT_DIR}); every flag goes to `mostra new` as given.
+ */
+export declare function plan(args: readonly string[], cwd: string): CreatePlan;
+/** This package's usage. */
+export declare const USAGE: string;
+/** What to run next, for a person; `rel` is the artifact's directory as they'd type it. */
+export declare function nextSteps(rel: string): string;
+/** The `mostra` binary of the `@mostra/cli` this package depends on. */
+export declare function cliBin(): string;
+/** How a run talks to the terminal. */
+export interface CreateIo {
+  /** The arguments after `create-mostra`, as `npm create mostra` passes them. */
+  readonly args: readonly string[];
+  /** The directory relative paths resolve from. */
+  readonly cwd: string;
+  /** The environment the CLI runs with. */
+  readonly env: NodeJS.ProcessEnv;
+  /** Writes to stdout: the usage and the next steps (the CLI writes its own output itself). */
+  readonly stdout: (text: string) => void;
+  /** Writes to stderr: why the CLI couldn't be started. */
+  readonly stderr?: (text: string) => void;
+  /**
+   * Whether a terminal is attached (stdin, stdout or stderr is one). Ctrl-C there signals the
+   * whole foreground process group, the CLI included, so SIGINT isn't passed on: a second one
+   * would cut short a command that stops gracefully on the first (as the CLI's bootstrap does).
+   */
+  readonly terminal?: boolean;
+  /** Finds the `mostra` binary to run; default {@link cliBin}. */
+  readonly cli?: () => string;
+}
+/**
+ * Runs `npm create mostra`: resolves with the exit code, the CLI's own (128 plus the signal's
+ * number when a signal ended it, as a shell reports it). Signals this process gets are passed on
+ * as the CLI's bootstrap passes them.
+ */
+export declare function create(io: CreateIo): Promise<number>;
+//#endregion
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;qBAea;;iBAGI;;WAEN;;WAEA;;WAEA;;WAEA;;;;;;wBAOK,KAAK,yBAAyB,cAAc;;qBAqC/C;;wBAaG,UAAU;;wBAcV;;iBASC;;WAEN;;WAEA;;WAEA,KAAK,OAAO;;WAEZ,SAAS;;WAET,UAAU;;;;;;WAMV;;WAEA;;;;;;;wBA6BW,OAAO,IAAI,WAAW"}

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as nextSteps, i as create, n as USAGE, o as plan, r as cliBin, t as DEFAULT_DIR } from "./src-Db8IadT7.js";
+export { DEFAULT_DIR, USAGE, cliBin, create, nextSteps, plan };

package/dist/src-Db8IadT7.js

@@ -0,0 +1,163 @@
+import { createRequire } from "node:module";
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { constants } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+//#region src/index.ts
+/**
+* `create-mostra`, what `npm create mostra` runs (RT-01). It creates an artifact with `mostra new`
+* through the `@mostra/cli` it depends on, so the first run also installs the runtime bundle that
+* release pins (the CLI's bootstrap), then says what to run next. It adds no behavior of its own:
+* every flag but its own is the CLI's, and its exit code is the CLI's.
+*
+* @packageDocumentation
+*/
+/** The directory an artifact goes into when none is named. */
+const DEFAULT_DIR = "my-artifact";
+/**
+* Plans a run from `npm create mostra [dir] -- [flags]`: the first argument that isn't a flag is
+* the directory (else {@link DEFAULT_DIR}); every flag goes to `mostra new` as given.
+*/
+function plan(args, cwd) {
+	let dir;
+	const flags = [];
+	for (let index = 0; index < args.length; index++) {
+		const arg = args[index];
+		if (arg === "--") continue;
+		if (arg.startsWith("-")) {
+			flags.push(arg);
+			const next = args[index + 1];
+			if (!arg.includes("=") && VALUED.has(arg) && next !== void 0) {
+				flags.push(next);
+				index++;
+			}
+		} else if (dir === void 0) dir = arg;
+		else flags.push(arg);
+	}
+	const chosen = dir ?? "my-artifact";
+	return {
+		argv: [
+			"new",
+			chosen,
+			...flags
+		],
+		dir: resolve(cwd, chosen),
+		json: flags.includes("--json"),
+		help: flags.includes("--help") || flags.includes("-h")
+	};
+}
+/** `mostra new`'s flags (and the global ones) that take a value. */
+const VALUED = /* @__PURE__ */ new Set([
+	"--title",
+	"--template",
+	"--request-id",
+	"--home",
+	"--cwd",
+	"--timeout"
+]);
+/** This package's usage. */
+const USAGE = `Create a Mostra artifact.
+
+Usage: npm create mostra@latest [dir] -- [--title <text>] [--json]
+
+  dir       The directory to create it in; it must be empty or not exist. Default: ${DEFAULT_DIR}
+  --title   The artifact's title. Default: the directory's name.
+  --json    Print only mostra's JSON envelope on stdout.
+
+The first run downloads Mostra's runtime (about 200 MB), checks it and caches it; later runs reuse it.
+Every flag is mostra new's: npx @mostra/cli new --help lists them.
+`;
+/** What to run next, for a person; `rel` is the artifact's directory as they'd type it. */
+function nextSteps(rel) {
+	const at = rel.includes(" ") ? JSON.stringify(rel) : rel;
+	return `
+Next:
+  edit ${at}/index.tsx                     ordinary React; the agent writes it
+  npx @mostra/cli verify ${at}             build it, render it and check it
+  npx @mostra/cli publish ${at}            publish a version and print its link
+  npm install --global @mostra/cli         for a plain \`mostra\` command
+
+Docs: npx @mostra/cli docs
+`;
+}
+/** The `mostra` binary of the `@mostra/cli` this package depends on. */
+function cliBin() {
+	const manifestPath = createRequire(import.meta.url).resolve("@mostra/cli/package.json");
+	const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+	if (!manifest.bin?.mostra) throw new Error("@mostra/cli declares no mostra binary.");
+	return join(dirname(manifestPath), manifest.bin.mostra);
+}
+/**
+* The one diagnostic this package writes itself: the CLI it depends on couldn't be started, so
+* nothing of it (nor of `@mostra/protocol`, which it may not import) can describe the failure.
+* The fields are the catalog entry's (`MOSTRA_ENV_RUNTIME_MISSING`, exit 3).
+*/
+function cliMissing(io, json, why) {
+	const message = `create-mostra couldn't start the mostra CLI it depends on (${why}). Install it again: npm create mostra@latest.`;
+	io.stderr?.(`create-mostra: ${message}\n`);
+	if (json) {
+		const error = {
+			code: "MOSTRA_ENV_RUNTIME_MISSING",
+			severity: "error",
+			phase: "host",
+			message,
+			docs: "https://mostra-dev.github.io/mostra/errors/MOSTRA_ENV_RUNTIME_MISSING"
+		};
+		io.stdout(`${JSON.stringify({
+			ok: false,
+			error,
+			warnings: []
+		})}\n`);
+	}
+	return 3;
+}
+/**
+* Runs `npm create mostra`: resolves with the exit code, the CLI's own (128 plus the signal's
+* number when a signal ended it, as a shell reports it). Signals this process gets are passed on
+* as the CLI's bootstrap passes them.
+*/
+async function create(io) {
+	const run = plan(io.args, io.cwd);
+	if (run.help) {
+		io.stdout(USAGE);
+		return 0;
+	}
+	let bin;
+	try {
+		bin = (io.cli ?? cliBin)();
+	} catch (error) {
+		return cliMissing(io, run.json, error instanceof Error ? error.message : String(error));
+	}
+	const code = await new Promise((done) => {
+		const child = spawn(process.execPath, [bin, ...run.argv], {
+			cwd: io.cwd,
+			env: io.env,
+			stdio: "inherit"
+		});
+		const forward = (signal) => {
+			if (signal === "SIGINT" && io.terminal) return;
+			child.kill(signal);
+		};
+		const signals = [
+			"SIGINT",
+			"SIGTERM",
+			"SIGHUP"
+		];
+		for (const signal of signals) process.on(signal, forward);
+		let settled = false;
+		const settle = (exit) => {
+			if (settled) return;
+			settled = true;
+			for (const signal of signals) process.off(signal, forward);
+			done(exit);
+		};
+		child.on("error", (error) => settle(cliMissing(io, run.json, error.message)));
+		child.on("exit", (exit, signal) => settle(exit ?? 128 + (signal ? constants.signals[signal] ?? 0 : 0)));
+	});
+	if (code === 0 && !run.json) io.stdout(nextSteps(relative(io.cwd, run.dir) || "."));
+	return code;
+}
+//#endregion
+export { nextSteps as a, create as i, USAGE as n, plan as o, cliBin as r, DEFAULT_DIR as t };
+
+//# sourceMappingURL=src-Db8IadT7.js.map

package/dist/src-Db8IadT7.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"src-Db8IadT7.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * `create-mostra`, what `npm create mostra` runs (RT-01). It creates an artifact with `mostra new`\n * through the `@mostra/cli` it depends on, so the first run also installs the runtime bundle that\n * release pins (the CLI's bootstrap), then says what to run next. It adds no behavior of its own:\n * every flag but its own is the CLI's, and its exit code is the CLI's.\n *\n * @packageDocumentation\n */\nimport { spawn } from \"node:child_process\";\nimport { readFileSync } from \"node:fs\";\nimport { createRequire } from \"node:module\";\nimport { constants } from \"node:os\";\nimport { dirname, join, relative, resolve } from \"node:path\";\n\n/** The directory an artifact goes into when none is named. */\nexport const DEFAULT_DIR: string = \"my-artifact\";\n\n/** What one run does: the `mostra` arguments, and the directory it creates. */\nexport interface CreatePlan {\n  /** The arguments for `mostra`: `new <dir>` and the flags passed on. */\n  readonly argv: readonly string[];\n  /** The artifact's directory, absolute. */\n  readonly dir: string;\n  /** Whether `--json` was given: then stdout is exactly the CLI's envelope. */\n  readonly json: boolean;\n  /** Whether to print this package's usage instead. */\n  readonly help: boolean;\n}\n\n/**\n * Plans a run from `npm create mostra [dir] -- [flags]`: the first argument that isn't a flag is\n * the directory (else {@link DEFAULT_DIR}); every flag goes to `mostra new` as given.\n */\nexport function plan(args: readonly string[], cwd: string): CreatePlan {\n  let dir: string | undefined;\n  const flags: string[] = [];\n  for (let index = 0; index < args.length; index++) {\n    const arg = args[index] as string;\n    if (arg === \"--\") continue;\n    if (arg.startsWith(\"-\")) {\n      flags.push(arg);\n      // A flag with a value in the next argument: `--title \"Q3 review\"`.\n      const next = args[index + 1];\n      if (!arg.includes(\"=\") && VALUED.has(arg) && next !== undefined) {\n        flags.push(next);\n        index++;\n      }\n    } else if (dir === undefined) dir = arg;\n    else flags.push(arg);\n  }\n  const chosen = dir ?? DEFAULT_DIR;\n  return {\n    argv: [\"new\", chosen, ...flags],\n    dir: resolve(cwd, chosen),\n    json: flags.includes(\"--json\"),\n    help: flags.includes(\"--help\") || flags.includes(\"-h\"),\n  };\n}\n\n/** `mostra new`'s flags (and the global ones) that take a value. */\nconst VALUED: ReadonlySet<string> = new Set([\n  \"--title\",\n  \"--template\",\n  \"--request-id\",\n  \"--home\",\n  \"--cwd\",\n  \"--timeout\",\n]);\n\n/** This package's usage. */\nexport const USAGE: string = `Create a Mostra artifact.\n\nUsage: npm create mostra@latest [dir] -- [--title <text>] [--json]\n\n  dir       The directory to create it in; it must be empty or not exist. Default: ${DEFAULT_DIR}\n  --title   The artifact's title. Default: the directory's name.\n  --json    Print only mostra's JSON envelope on stdout.\n\nThe first run downloads Mostra's runtime (about 200 MB), checks it and caches it; later runs reuse it.\nEvery flag is mostra new's: npx @mostra/cli new --help lists them.\n`;\n\n/** What to run next, for a person; `rel` is the artifact's directory as they'd type it. */\nexport function nextSteps(rel: string): string {\n  const at = rel.includes(\" \") ? JSON.stringify(rel) : rel;\n  return `\nNext:\n  edit ${at}/index.tsx                     ordinary React; the agent writes it\n  npx @mostra/cli verify ${at}             build it, render it and check it\n  npx @mostra/cli publish ${at}            publish a version and print its link\n  npm install --global @mostra/cli         for a plain \\`mostra\\` command\n\nDocs: npx @mostra/cli docs\n`;\n}\n\n/** The `mostra` binary of the `@mostra/cli` this package depends on. */\nexport function cliBin(): string {\n  const require = createRequire(import.meta.url);\n  const manifestPath = require.resolve(\"@mostra/cli/package.json\");\n  const manifest = JSON.parse(readFileSync(manifestPath, \"utf8\")) as { bin?: { mostra?: string } };\n  if (!manifest.bin?.mostra) throw new Error(\"@mostra/cli declares no mostra binary.\");\n  return join(dirname(manifestPath), manifest.bin.mostra);\n}\n\n/** How a run talks to the terminal. */\nexport interface CreateIo {\n  /** The arguments after `create-mostra`, as `npm create mostra` passes them. */\n  readonly args: readonly string[];\n  /** The directory relative paths resolve from. */\n  readonly cwd: string;\n  /** The environment the CLI runs with. */\n  readonly env: NodeJS.ProcessEnv;\n  /** Writes to stdout: the usage and the next steps (the CLI writes its own output itself). */\n  readonly stdout: (text: string) => void;\n  /** Writes to stderr: why the CLI couldn't be started. */\n  readonly stderr?: (text: string) => void;\n  /**\n   * Whether a terminal is attached (stdin, stdout or stderr is one). Ctrl-C there signals the\n   * whole foreground process group, the CLI included, so SIGINT isn't passed on: a second one\n   * would cut short a command that stops gracefully on the first (as the CLI's bootstrap does).\n   */\n  readonly terminal?: boolean;\n  /** Finds the `mostra` binary to run; default {@link cliBin}. */\n  readonly cli?: () => string;\n}\n\n/**\n * The one diagnostic this package writes itself: the CLI it depends on couldn't be started, so\n * nothing of it (nor of `@mostra/protocol`, which it may not import) can describe the failure.\n * The fields are the catalog entry's (`MOSTRA_ENV_RUNTIME_MISSING`, exit 3).\n */\nfunction cliMissing(io: CreateIo, json: boolean, why: string): number {\n  const message = `create-mostra couldn't start the mostra CLI it depends on (${why}). Install it again: npm create mostra@latest.`;\n  io.stderr?.(`create-mostra: ${message}\\n`);\n  if (json) {\n    const error = {\n      code: \"MOSTRA_ENV_RUNTIME_MISSING\",\n      severity: \"error\",\n      phase: \"host\",\n      message,\n      docs: \"https://mostra-dev.github.io/mostra/errors/MOSTRA_ENV_RUNTIME_MISSING\",\n    };\n    io.stdout(`${JSON.stringify({ ok: false, error, warnings: [] })}\\n`);\n  }\n  return 3;\n}\n\n/**\n * Runs `npm create mostra`: resolves with the exit code, the CLI's own (128 plus the signal's\n * number when a signal ended it, as a shell reports it). Signals this process gets are passed on\n * as the CLI's bootstrap passes them.\n */\nexport async function create(io: CreateIo): Promise<number> {\n  const run = plan(io.args, io.cwd);\n  if (run.help) {\n    io.stdout(USAGE);\n    return 0;\n  }\n  let bin: string;\n  try {\n    bin = (io.cli ?? cliBin)();\n  } catch (error) {\n    return cliMissing(io, run.json, error instanceof Error ? error.message : String(error));\n  }\n  const code = await new Promise<number>((done) => {\n    const child = spawn(process.execPath, [bin, ...run.argv], {\n      cwd: io.cwd,\n      env: io.env,\n      stdio: \"inherit\",\n    });\n    const forward = (signal: NodeJS.Signals): void => {\n      if (signal === \"SIGINT\" && io.terminal) return; // the CLI got the terminal's own\n      child.kill(signal);\n    };\n    const signals: NodeJS.Signals[] = [\"SIGINT\", \"SIGTERM\", \"SIGHUP\"];\n    for (const signal of signals) process.on(signal, forward);\n    let settled = false;\n    const settle = (exit: number): void => {\n      if (settled) return;\n      settled = true;\n      for (const signal of signals) process.off(signal, forward);\n      done(exit);\n    };\n    child.on(\"error\", (error) => settle(cliMissing(io, run.json, error.message)));\n    child.on(\"exit\", (exit, signal) =>\n      settle(exit ?? 128 + (signal ? (constants.signals[signal] ?? 0) : 0)),\n    );\n  });\n  if (code === 0 && !run.json) io.stdout(nextSteps(relative(io.cwd, run.dir) || \".\"));\n  return code;\n}\n"],"mappings":";;;;;;;;;;;;;;;AAeA,MAAa,cAAsB;;;;;AAkBnC,SAAgB,KAAK,MAAyB,KAAyB;CACrE,IAAI;CACJ,MAAM,QAAkB,CAAC;CACzB,KAAK,IAAI,QAAQ,GAAG,QAAQ,KAAK,QAAQ,SAAS;EAChD,MAAM,MAAM,KAAK;EACjB,IAAI,QAAQ,MAAM;EAClB,IAAI,IAAI,WAAW,GAAG,GAAG;GACvB,MAAM,KAAK,GAAG;GAEd,MAAM,OAAO,KAAK,QAAQ;GAC1B,IAAI,CAAC,IAAI,SAAS,GAAG,KAAK,OAAO,IAAI,GAAG,KAAK,SAAS,KAAA,GAAW;IAC/D,MAAM,KAAK,IAAI;IACf;GACF;EACF,OAAO,IAAI,QAAQ,KAAA,GAAW,MAAM;OAC/B,MAAM,KAAK,GAAG;CACrB;CACA,MAAM,SAAS,OAAA;CACf,OAAO;EACL,MAAM;GAAC;GAAO;GAAQ,GAAG;EAAK;EAC9B,KAAK,QAAQ,KAAK,MAAM;EACxB,MAAM,MAAM,SAAS,QAAQ;EAC7B,MAAM,MAAM,SAAS,QAAQ,KAAK,MAAM,SAAS,IAAI;CACvD;AACF;;AAGA,MAAM,yBAA8B,IAAI,IAAI;CAC1C;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;;AAGD,MAAa,QAAgB;;;;qFAIwD,YAAY;;;;;;;;AASjG,SAAgB,UAAU,KAAqB;CAC7C,MAAM,KAAK,IAAI,SAAS,GAAG,IAAI,KAAK,UAAU,GAAG,IAAI;CACrD,OAAO;;SAEA,GAAG;2BACe,GAAG;4BACF,GAAG;;;;;AAK/B;;AAGA,SAAgB,SAAiB;CAE/B,MAAM,eADU,cAAc,YAAY,GACf,CAAC,CAAC,QAAQ,0BAA0B;CAC/D,MAAM,WAAW,KAAK,MAAM,aAAa,cAAc,MAAM,CAAC;CAC9D,IAAI,CAAC,SAAS,KAAK,QAAQ,MAAM,IAAI,MAAM,wCAAwC;CACnF,OAAO,KAAK,QAAQ,YAAY,GAAG,SAAS,IAAI,MAAM;AACxD;;;;;;AA6BA,SAAS,WAAW,IAAc,MAAe,KAAqB;CACpE,MAAM,UAAU,8DAA8D,IAAI;CAClF,GAAG,SAAS,kBAAkB,QAAQ,GAAG;CACzC,IAAI,MAAM;EACR,MAAM,QAAQ;GACZ,MAAM;GACN,UAAU;GACV,OAAO;GACP;GACA,MAAM;EACR;EACA,GAAG,OAAO,GAAG,KAAK,UAAU;GAAE,IAAI;GAAO;GAAO,UAAU,CAAC;EAAE,CAAC,EAAE,GAAG;CACrE;CACA,OAAO;AACT;;;;;;AAOA,eAAsB,OAAO,IAA+B;CAC1D,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG,GAAG;CAChC,IAAI,IAAI,MAAM;EACZ,GAAG,OAAO,KAAK;EACf,OAAO;CACT;CACA,IAAI;CACJ,IAAI;EACF,OAAO,GAAG,OAAO,OAAA,CAAQ;CAC3B,SAAS,OAAO;EACd,OAAO,WAAW,IAAI,IAAI,MAAM,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,CAAC;CACxF;CACA,MAAM,OAAO,MAAM,IAAI,SAAiB,SAAS;EAC/C,MAAM,QAAQ,MAAM,QAAQ,UAAU,CAAC,KAAK,GAAG,IAAI,IAAI,GAAG;GACxD,KAAK,GAAG;GACR,KAAK,GAAG;GACR,OAAO;EACT,CAAC;EACD,MAAM,WAAW,WAAiC;GAChD,IAAI,WAAW,YAAY,GAAG,UAAU;GACxC,MAAM,KAAK,MAAM;EACnB;EACA,MAAM,UAA4B;GAAC;GAAU;GAAW;EAAQ;EAChE,KAAK,MAAM,UAAU,SAAS,QAAQ,GAAG,QAAQ,OAAO;EACxD,IAAI,UAAU;EACd,MAAM,UAAU,SAAuB;GACrC,IAAI,SAAS;GACb,UAAU;GACV,KAAK,MAAM,UAAU,SAAS,QAAQ,IAAI,QAAQ,OAAO;GACzD,KAAK,IAAI;EACX;EACA,MAAM,GAAG,UAAU,UAAU,OAAO,WAAW,IAAI,IAAI,MAAM,MAAM,OAAO,CAAC,CAAC;EAC5E,MAAM,GAAG,SAAS,MAAM,WACtB,OAAO,QAAQ,OAAO,SAAU,UAAU,QAAQ,WAAW,IAAK,EAAE,CACtE;CACF,CAAC;CACD,IAAI,SAAS,KAAK,CAAC,IAAI,MAAM,GAAG,OAAO,UAAU,SAAS,GAAG,KAAK,IAAI,GAAG,KAAK,GAAG,CAAC;CAClF,OAAO;AACT"}

package/package.json

@@ -1,24 +1,62 @@
 {
   "name": "create-mostra",
-  "version": "0.0.1",
-  "description": "Create a Mostra artifact. Placeholder: the real starter ships with the first Mostra release.",
+  "version": "0.1.0",
+  "description": "npm create mostra: create a Mostra artifact, installing the Mostra runtime on first use.",
   "license": "Apache-2.0",
-  "bin": {
-    "create-mostra": "index.js"
+  "author": "The Mostra Authors",
+  "homepage": "https://github.com/mostra-dev/mostra/tree/main/packages/create-mostra#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mostra-dev/mostra.git",
+    "directory": "packages/create-mostra"
+  },
+  "bugs": "https://github.com/mostra-dev/mostra/issues",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "@mostra/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
-    "index.js",
-    "LICENSE"
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
   ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mostra-dev/mostra.git"
+  "engines": {
+    "node": ">=22.19"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@mostra/cli": "0.1.0"
+  },
+  "devDependencies": {
+    "@mostra/tools": "0.0.0",
+    "@types/node": "24.19.1",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  },
+  "bin": {
+    "create-mostra": "./dist/bin.js"
   },
-  "homepage": "https://github.com/mostra-dev/mostra",
   "keywords": [
     "mostra",
-    "agents",
-    "artifacts",
-    "react"
-  ]
-}
+    "create",
+    "agent",
+    "artifact"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -b",
+    "test": "vitest run --project unit",
+    "api": "mostra-tools api",
+    "test:integration": "vitest run --project integration"
+  }
+}

package/src/bin.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/** `create-mostra`'s binary: `npm create mostra [dir]` (see `index.ts`). */
+import { create } from "./index.ts";
+
+process.stdout.on("error", () => {});
+process.stderr.on("error", () => {});
+const code = await create({
+  args: process.argv.slice(2),
+  cwd: process.cwd(),
+  env: process.env,
+  stdout: (text) => {
+    process.stdout.write(text);
+  },
+  stderr: (text) => {
+    process.stderr.write(text);
+  },
+  terminal:
+    process.stdin.isTTY === true || process.stdout.isTTY === true || process.stderr.isTTY === true,
+});
+process.stdout.write("", () => process.exit(code));

package/src/index.ts

@@ -0,0 +1,192 @@
+/**
+ * `create-mostra`, what `npm create mostra` runs (RT-01). It creates an artifact with `mostra new`
+ * through the `@mostra/cli` it depends on, so the first run also installs the runtime bundle that
+ * release pins (the CLI's bootstrap), then says what to run next. It adds no behavior of its own:
+ * every flag but its own is the CLI's, and its exit code is the CLI's.
+ *
+ * @packageDocumentation
+ */
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { constants } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+
+/** The directory an artifact goes into when none is named. */
+export const DEFAULT_DIR: string = "my-artifact";
+
+/** What one run does: the `mostra` arguments, and the directory it creates. */
+export interface CreatePlan {
+  /** The arguments for `mostra`: `new <dir>` and the flags passed on. */
+  readonly argv: readonly string[];
+  /** The artifact's directory, absolute. */
+  readonly dir: string;
+  /** Whether `--json` was given: then stdout is exactly the CLI's envelope. */
+  readonly json: boolean;
+  /** Whether to print this package's usage instead. */
+  readonly help: boolean;
+}
+
+/**
+ * Plans a run from `npm create mostra [dir] -- [flags]`: the first argument that isn't a flag is
+ * the directory (else {@link DEFAULT_DIR}); every flag goes to `mostra new` as given.
+ */
+export function plan(args: readonly string[], cwd: string): CreatePlan {
+  let dir: string | undefined;
+  const flags: string[] = [];
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index] as string;
+    if (arg === "--") continue;
+    if (arg.startsWith("-")) {
+      flags.push(arg);
+      // A flag with a value in the next argument: `--title "Q3 review"`.
+      const next = args[index + 1];
+      if (!arg.includes("=") && VALUED.has(arg) && next !== undefined) {
+        flags.push(next);
+        index++;
+      }
+    } else if (dir === undefined) dir = arg;
+    else flags.push(arg);
+  }
+  const chosen = dir ?? DEFAULT_DIR;
+  return {
+    argv: ["new", chosen, ...flags],
+    dir: resolve(cwd, chosen),
+    json: flags.includes("--json"),
+    help: flags.includes("--help") || flags.includes("-h"),
+  };
+}
+
+/** `mostra new`'s flags (and the global ones) that take a value. */
+const VALUED: ReadonlySet<string> = new Set([
+  "--title",
+  "--template",
+  "--request-id",
+  "--home",
+  "--cwd",
+  "--timeout",
+]);
+
+/** This package's usage. */
+export const USAGE: string = `Create a Mostra artifact.
+
+Usage: npm create mostra@latest [dir] -- [--title <text>] [--json]
+
+  dir       The directory to create it in; it must be empty or not exist. Default: ${DEFAULT_DIR}
+  --title   The artifact's title. Default: the directory's name.
+  --json    Print only mostra's JSON envelope on stdout.
+
+The first run downloads Mostra's runtime (about 200 MB), checks it and caches it; later runs reuse it.
+Every flag is mostra new's: npx @mostra/cli new --help lists them.
+`;
+
+/** What to run next, for a person; `rel` is the artifact's directory as they'd type it. */
+export function nextSteps(rel: string): string {
+  const at = rel.includes(" ") ? JSON.stringify(rel) : rel;
+  return `
+Next:
+  edit ${at}/index.tsx                     ordinary React; the agent writes it
+  npx @mostra/cli verify ${at}             build it, render it and check it
+  npx @mostra/cli publish ${at}            publish a version and print its link
+  npm install --global @mostra/cli         for a plain \`mostra\` command
+
+Docs: npx @mostra/cli docs
+`;
+}
+
+/** The `mostra` binary of the `@mostra/cli` this package depends on. */
+export function cliBin(): string {
+  const require = createRequire(import.meta.url);
+  const manifestPath = require.resolve("@mostra/cli/package.json");
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as { bin?: { mostra?: string } };
+  if (!manifest.bin?.mostra) throw new Error("@mostra/cli declares no mostra binary.");
+  return join(dirname(manifestPath), manifest.bin.mostra);
+}
+
+/** How a run talks to the terminal. */
+export interface CreateIo {
+  /** The arguments after `create-mostra`, as `npm create mostra` passes them. */
+  readonly args: readonly string[];
+  /** The directory relative paths resolve from. */
+  readonly cwd: string;
+  /** The environment the CLI runs with. */
+  readonly env: NodeJS.ProcessEnv;
+  /** Writes to stdout: the usage and the next steps (the CLI writes its own output itself). */
+  readonly stdout: (text: string) => void;
+  /** Writes to stderr: why the CLI couldn't be started. */
+  readonly stderr?: (text: string) => void;
+  /**
+   * Whether a terminal is attached (stdin, stdout or stderr is one). Ctrl-C there signals the
+   * whole foreground process group, the CLI included, so SIGINT isn't passed on: a second one
+   * would cut short a command that stops gracefully on the first (as the CLI's bootstrap does).
+   */
+  readonly terminal?: boolean;
+  /** Finds the `mostra` binary to run; default {@link cliBin}. */
+  readonly cli?: () => string;
+}
+
+/**
+ * The one diagnostic this package writes itself: the CLI it depends on couldn't be started, so
+ * nothing of it (nor of `@mostra/protocol`, which it may not import) can describe the failure.
+ * The fields are the catalog entry's (`MOSTRA_ENV_RUNTIME_MISSING`, exit 3).
+ */
+function cliMissing(io: CreateIo, json: boolean, why: string): number {
+  const message = `create-mostra couldn't start the mostra CLI it depends on (${why}). Install it again: npm create mostra@latest.`;
+  io.stderr?.(`create-mostra: ${message}\n`);
+  if (json) {
+    const error = {
+      code: "MOSTRA_ENV_RUNTIME_MISSING",
+      severity: "error",
+      phase: "host",
+      message,
+      docs: "https://mostra-dev.github.io/mostra/errors/MOSTRA_ENV_RUNTIME_MISSING",
+    };
+    io.stdout(`${JSON.stringify({ ok: false, error, warnings: [] })}\n`);
+  }
+  return 3;
+}
+
+/**
+ * Runs `npm create mostra`: resolves with the exit code, the CLI's own (128 plus the signal's
+ * number when a signal ended it, as a shell reports it). Signals this process gets are passed on
+ * as the CLI's bootstrap passes them.
+ */
+export async function create(io: CreateIo): Promise<number> {
+  const run = plan(io.args, io.cwd);
+  if (run.help) {
+    io.stdout(USAGE);
+    return 0;
+  }
+  let bin: string;
+  try {
+    bin = (io.cli ?? cliBin)();
+  } catch (error) {
+    return cliMissing(io, run.json, error instanceof Error ? error.message : String(error));
+  }
+  const code = await new Promise<number>((done) => {
+    const child = spawn(process.execPath, [bin, ...run.argv], {
+      cwd: io.cwd,
+      env: io.env,
+      stdio: "inherit",
+    });
+    const forward = (signal: NodeJS.Signals): void => {
+      if (signal === "SIGINT" && io.terminal) return; // the CLI got the terminal's own
+      child.kill(signal);
+    };
+    const signals: NodeJS.Signals[] = ["SIGINT", "SIGTERM", "SIGHUP"];
+    for (const signal of signals) process.on(signal, forward);
+    let settled = false;
+    const settle = (exit: number): void => {
+      if (settled) return;
+      settled = true;
+      for (const signal of signals) process.off(signal, forward);
+      done(exit);
+    };
+    child.on("error", (error) => settle(cliMissing(io, run.json, error.message)));
+    child.on("exit", (exit, signal) =>
+      settle(exit ?? 128 + (signal ? (constants.signals[signal] ?? 0) : 0)),
+    );
+  });
+  if (code === 0 && !run.json) io.stdout(nextSteps(relative(io.cwd, run.dir) || "."));
+  return code;
+}