@runa-cmd/create 0.2.0-beta.5 → 0.2.0-beta.7

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @runa-cmd/create
 
+## 0.2.0-beta.7
+
+### Minor Changes
+
+- 4140fe9: The generator's command line follows the rules of a CLI made with Runa. A usage error exits with 2, says what's wrong in its own words, and where the help is:
+
+  ```
+  $ npm create @runa-cmd
+  Missing the name of the project, as in 'npm create @runa-cmd my-tool'.
+  Run 'npm create @runa-cmd -- --help' for usage.
+  ```
+
+  Before, a missing name or an extra argument printed the usage without saying what was wrong, and an unknown option showed Node's text. The README lists its arguments and exit codes, and says that npm reads its own flags first, so `--help` and `--version` go after `--`.
+
+  **Breaking:** `-v` is gone, as in every Runa CLI, where it's left for `--verbose`. Use `--version`.
+
+## 0.2.0-beta.6
+
 ## 0.2.0-beta.5
 
 ### Minor Changes

package/README.md

@@ -13,6 +13,28 @@ Until Runa reaches 1.0, add `@beta`, as above.
 
 It works with pnpm, yarn and bun too, as `pnpm create @runa-cmd@beta my-tool`, and the next steps it prints use the one you ran it with.
 
+## Usage
+
+```
+npm create @runa-cmd <name>
+```
+
+| Argument | What it does |
+|---|---|
+| `<name>` | The folder, the package and the command, as in `my-tool` |
+| `-h`, `--help` | Shows how to use it |
+| `--version` | Shows its version |
+
+npm reads its own flags first: to reach these, put them after `--`, as in `npm create @runa-cmd -- --help`.
+
+| Exit | When |
+|---|---|
+| `0` | The project was created, or it showed the help or the version |
+| `2` | A usage error, with what's wrong: an unknown option, no name or more than one, a name that can't be one, or a folder that already has files |
+| `1` | Something else failed, as a file it couldn't write |
+
+Like any CLI made with Runa, there's no `-v`, which other tools use for `--verbose`.
+
 ## What you get
 
 | File | What it is |

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+export interface CliContext {
+    /** This package's version, for --version */
+    version: string;
+    templateDir: string;
+    /** The core the template was built with */
+    runaVersion: string;
+    cwd: string;
+    /** npm_config_user_agent: the package manager that ran it */
+    userAgent: string | undefined;
+    out: (text: string) => void;
+    err: (text: string) => void;
+}
+/** Runs the generator, and returns its exit code. */
+export declare function main(argv: string[], ctx: CliContext): 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":"AAQA,MAAM,WAAW,UAAU;IAC1B,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5B;AAkDD,qDAAqD;AACrD,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,CA8B5D"}

package/dist/cli.js

@@ -0,0 +1,86 @@
+/**
+ * The command line of `npm create @runa-cmd`, with Runa's rules and without
+ * Runa: --help, -h and --version, no -v (ADR-0021), and exit 2 on a usage
+ * error, saying what's wrong and where the help is (T-239).
+ */
+import { parseArgs } from 'node:util';
+import { CreateError, createProject, nextSteps } from './create.js';
+const USAGE = `Create a CLI made with Runa.
+
+Usage: npm create @runa-cmd <name>
+
+  <name>          The folder, the package and the command, as in my-tool
+  -h, --help      Show this
+  --version       Show the version`;
+/** npm reads its own flags first: these only reach the generator after -- */
+const HINT = "Run 'npm create @runa-cmd -- --help' for usage.";
+const OPTIONS = { help: { type: 'boolean', short: 'h' }, version: { type: 'boolean' } };
+class UsageError extends Error {
+}
+/** What was asked for, or why it can't be read, in our words and not parseArgs'. */
+function read(argv) {
+    const { tokens } = parseArgs({
+        args: argv,
+        options: OPTIONS,
+        allowPositionals: true,
+        strict: false,
+        tokens: true,
+    });
+    const asked = { help: false, version: false };
+    const names = [];
+    for (const token of tokens) {
+        if (token.kind === 'positional')
+            names.push(token.value);
+        if (token.kind !== 'option')
+            continue;
+        if (!(token.name in OPTIONS))
+            throw new UsageError(`Unknown option '${token.rawName}'.`);
+        if (token.value !== undefined)
+            throw new UsageError(`Option '--${token.name}' takes no value.`);
+        asked[token.name] = true;
+    }
+    if (asked.help || asked.version)
+        return { ...asked, name: '' };
+    const [name, extra] = names;
+    if (name === undefined) {
+        throw new UsageError("Missing the name of the project, as in 'npm create @runa-cmd my-tool'.");
+    }
+    if (extra !== undefined) {
+        throw new UsageError(`Unexpected argument '${extra}': the name is a single word, as in 'my-tool'.`);
+    }
+    return { ...asked, name };
+}
+/** Runs the generator, and returns its exit code. */
+export function main(argv, ctx) {
+    let args;
+    try {
+        args = read(argv);
+    }
+    catch (error) {
+        if (!(error instanceof UsageError))
+            throw error;
+        ctx.err(`${error.message}\n${HINT}`);
+        return 2;
+    }
+    if (args.help) {
+        ctx.out(USAGE);
+        return 0;
+    }
+    if (args.version) {
+        ctx.out(ctx.version);
+        return 0;
+    }
+    try {
+        const { templateDir, runaVersion, cwd } = ctx;
+        createProject({ name: args.name, cwd, templateDir, runaVersion });
+    }
+    catch (error) {
+        if (!(error instanceof CreateError))
+            throw error;
+        ctx.err(error.message);
+        return 2;
+    }
+    ctx.out(nextSteps(args.name, ctx.userAgent));
+    return 0;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAepE,MAAM,KAAK,GAAG;;;;;;mCAMqB,CAAC;AAEpC,6EAA6E;AAC7E,MAAM,IAAI,GAAG,iDAAiD,CAAC;AAE/D,MAAM,OAAO,GAAG,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAW,CAAC;AAEjG,MAAM,UAAW,SAAQ,KAAK;CAAG;AAEjC,oFAAoF;AACpF,SAAS,IAAI,CAAC,IAAc;IAC3B,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;QAC5B,IAAI,EAAE,IAAI;QACV,OAAO,EAAE,OAAO;QAChB,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE,KAAK;QACb,MAAM,EAAE,IAAI;KACZ,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9C,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACzD,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;YAAE,SAAS;QACtC,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,OAAO,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,mBAAmB,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;QACzF,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;YAAE,MAAM,IAAI,UAAU,CAAC,aAAa,KAAK,CAAC,IAAI,mBAAmB,CAAC,CAAC;QAChG,KAAK,CAAC,KAAK,CAAC,IAA0B,CAAC,GAAG,IAAI,CAAC;IAChD,CAAC;IAED,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO;QAAE,OAAO,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IAC/D,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC;IAC5B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,UAAU,CAAC,wEAAwE,CAAC,CAAC;IAChG,CAAC;IACD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,UAAU,CACnB,wBAAwB,KAAK,gDAAgD,CAC7E,CAAC;IACH,CAAC;IACD,OAAO,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,IAAI,CAAC,IAAc,EAAE,GAAe;IACnD,IAAI,IAA6B,CAAC;IAClC,IAAI,CAAC;QACJ,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,CAAC,CAAC,KAAK,YAAY,UAAU,CAAC;YAAE,MAAM,KAAK,CAAC;QAChD,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC,CAAC;QACrC,OAAO,CAAC,CAAC;IACV,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACf,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACf,OAAO,CAAC,CAAC;IACV,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAClB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACrB,OAAO,CAAC,CAAC;IACV,CAAC;IAED,IAAI,CAAC;QACJ,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC;QAC9C,aAAa,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC;IACnE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,CAAC,CAAC,KAAK,YAAY,WAAW,CAAC;YAAE,MAAM,KAAK,CAAC;QACjD,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACvB,OAAO,CAAC,CAAC;IACV,CAAC;IAED,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;IAC7C,OAAO,CAAC,CAAC;AACV,CAAC"}

package/dist/index.js

@@ -3,66 +3,26 @@
  * @runa-cmd/create — `npm create @runa-cmd my-tool`
  *
  * No dependencies, Runa included: `npm create` downloads this every time, and
- * it should take a moment, not Zod.
+ * it should take a moment, not Zod. The command line is in cli.ts, so tests
+ * can run it without a process.
  */
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { parseArgs } from 'node:util';
-import { CreateError, createProject, nextSteps } from './create.js';
+import { main } from './cli.js';
 const root = join(dirname(fileURLToPath(import.meta.url)), '..');
 const templateDir = join(root, 'template');
 const readJson = (path) => JSON.parse(readFileSync(path, 'utf8'));
 const { version } = readJson(join(root, 'package.json'));
 // The core this was built with, which isn't always this package's version
 const runaVersion = readJson(join(templateDir, 'runa.json')).core;
-const USAGE = `Create a CLI made with Runa.
-
-Usage: npm create @runa-cmd <name>
-
-  <name>          The folder, the package and the command, as in my-tool
-  -h, --help      Show this
-  -v, --version   Show the version`;
-function main() {
-    let parsed;
-    try {
-        parsed = parseArgs({
-            allowPositionals: true,
-            options: {
-                help: { type: 'boolean', short: 'h' },
-                version: { type: 'boolean', short: 'v' },
-            },
-        });
-    }
-    catch (error) {
-        console.error(`${error.message}\n\n${USAGE}`);
-        return 2;
-    }
-    const { values, positionals } = parsed;
-    if (values.help) {
-        console.log(USAGE);
-        return 0;
-    }
-    if (values.version) {
-        console.log(version);
-        return 0;
-    }
-    const [name, ...extra] = positionals;
-    if (!name || extra.length > 0) {
-        console.error(USAGE);
-        return 2;
-    }
-    try {
-        createProject({ name, cwd: process.cwd(), templateDir, runaVersion });
-    }
-    catch (error) {
-        if (!(error instanceof CreateError))
-            throw error;
-        console.error(error.message);
-        return 2;
-    }
-    console.log(nextSteps(name, process.env.npm_config_user_agent));
-    return 0;
-}
-process.exitCode = main();
+process.exitCode = main(process.argv.slice(2), {
+    version,
+    templateDir,
+    runaVersion,
+    cwd: process.cwd(),
+    userAgent: process.env.npm_config_user_agent,
+    out: (text) => console.log(text),
+    err: (text) => console.error(text),
+});
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAEhC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AACjE,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AAC3C,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;AAC1E,MAAM,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC;AACzD,0EAA0E;AAC1E,MAAM,WAAW,GAAW,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC;AAE1E,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IAC9C,OAAO;IACP,WAAW;IACX,WAAW;IACX,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;IAClB,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,qBAAqB;IAC5C,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;IAChC,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;CAClC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runa-cmd/create",
-  "version": "0.2.0-beta.5",
+  "version": "0.2.0-beta.7",
   "description": "Create a CLI made with Runa: npm create @runa-cmd my-tool",
   "license": "MIT",
   "type": "module",
@@ -39,11 +39,11 @@
     "@types/node": "^24.19.2",
     "typescript": "^7.0.2",
     "zod": "^4.6.7",
-    "@runa-cmd/core": "0.2.0-beta.5"
+    "@runa-cmd/core": "0.2.0-beta.7"
   },
   "scripts": {
     "build": "tsc && node scripts/copy-template.mjs",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
     "test": "vitest run --dir src",
     "lint": "biome check .",
     "clean": "rm -rf dist template"

package/template/runa.json

@@ -1 +1 @@
-{"core":"0.2.0-beta.5"}
+{"core":"0.2.0-beta.7"}