kiriya 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -7,6 +7,25 @@ output shapes are kiriya's public API.
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-09-24
+
+### Changed
+
+- A usage error inside a command that was found now points at that command's help, so
+  `Missing argument: sources` is followed by `Run kiriya files copy --help to see what it
+  takes.` A spelling suggestion, being the more useful hint, still takes precedence.
+- `kiriya help <module>` lists each command's option names under it, so a module's whole
+  surface can be read at once instead of one command at a time. The short forms, the
+  values and the descriptions stay in the command's own help. The readme now shows the
+  three steps help goes through, which nothing pointed out before.
+
+### Fixed
+
+- The readme and the getting started page said kiriya was not on npm and walked people
+  through building it from source. Both now install it with `npm install --global kiriya`.
+  Since npm keeps the readme it was given at publish time, 0.1.0's page carried the wrong
+  instructions until this release replaced them.
+
 ## [0.1.0] - 2026-09-23
 
 The first release.

package/README.md

@@ -10,36 +10,61 @@ show a plan first, deletions go to the trash, and nothing that cannot be undone
 until you type a confirmation. AI agents can use the same commands over MCP, under the same
 rules.
 
-> **Status:** in development and not yet published to npm. Every module below is built and
-> tested in CI on Windows, Linux and macOS, with Node.js 22, 24 and the current release.
-
 ## Install
 
-kiriya needs [Node.js](https://nodejs.org/) 22.13 or later. Until its first release, build
-it from source:
+kiriya needs [Node.js](https://nodejs.org/) 22.13 or later.
+
+```bash
+npm install --global kiriya
+```
+
+Then check what this machine gives it:
 
 ```bash
-git clone https://github.com/SatPaingOo/kiriya.git
-cd kiriya
-npm ci
-npm run build
-npm link
+kiriya doctor
 ```
 
-[Getting started](docs/getting-started.md) takes it from there.
+Every release is published from CI with [provenance](https://docs.npmjs.com/generating-provenance-statements),
+so `npm audit signatures` can show which workflow built the copy you installed. Every module
+below is tested on Windows, Linux and macOS with Node.js 22, 24 and the current release.
+
+[Getting started](docs/getting-started.md) takes it from there, and
+[CONTRIBUTING.md](CONTRIBUTING.md) covers building from source.
 
 ## Quick start
 
 ```bash
 kiriya doctor                                   # what this machine offers kiriya
-kiriya --help                                   # every module
-kiriya help port                                # one module, with examples
 kiriya port who 3000                            # which process holds port 3000
 kiriya files find --name "*.log" --older 30d    # the same search in every shell
 kiriya files delete dist --dry-run              # the plan, before anything changes
 kiriya git status ~/code --json                 # every repository under a folder, as JSON
 ```
 
+## Finding your way
+
+Help goes three steps deep, and each step names the next, so nothing has to be guessed.
+
+```bash
+kiriya --help              # the modules, and the options every command accepts
+kiriya help files          # one module: its commands, and what each one takes
+kiriya help files delete   # one command: its arguments, options and examples
+```
+
+`kiriya files delete --help` says the same as that third line. The middle step lists each
+command's option names underneath it, so a module's whole surface fits on one screen:
+
+```text
+Commands
+  delete   Send files and folders to the trash, or remove them for good with --permanent
+           --permanent --dry-run --yes --confirm --all
+  find     Find files and folders by name, extension, type, size, age or emptiness
+           --name --ext --type --larger --smaller --newer --older --empty --all --limit
+```
+
+Every module also has a guide below with a full reference: every command, argument and
+option, what each does, and whether it can be undone.
+
 ## Modules
 
 <!-- kiriya:modules -->

package/dist/src/core/presentation/cli/cli-application.js

@@ -19,6 +19,24 @@ const EXIT_CODES = {
     interrupted: 130,
 };
 const verbsOf = (module) => [...module.commands.keys()].filter((verb) => verb !== "");
+/**
+ * A usage error raised inside a command that was found says what is wrong with the arguments
+ * but not what the command takes, so point at its help. An error that already carries a hint,
+ * such as a spelling suggestion, keeps the one it has.
+ */
+function withCommandHint(id, parse) {
+    try {
+        return parse();
+    }
+    catch (error) {
+        if (!(error instanceof UsageError) || error.detail.params["hint"] !== undefined)
+            throw error;
+        throw new UsageError(error.detail.key, {
+            ...error.detail.params,
+            hint: message("core.usage.see-help", { command: `kiriya ${id.split(".").join(" ")} --help` }),
+        });
+    }
+}
 /** The command line: finds the command, runs it, prints its result, and maps errors to exit codes once. */
 export class CliApplication {
     deps;
@@ -61,7 +79,7 @@ export class CliApplication {
             if (flags.help)
                 return this.print(this.deps.stdout, commandHelp(module, entry, help));
             const { spec } = entry.command;
-            const input = spec.input.parse(parseCommandArguments(spec.input, args));
+            const input = withCommandHint(spec.id, () => spec.input.parse(parseCommandArguments(spec.input, args)));
             const controller = new AbortController();
             const interrupt = () => controller.abort();
             process.once("SIGINT", interrupt);

package/dist/src/core/presentation/cli/help.js

@@ -30,6 +30,13 @@ function table(rows, options = {}) {
         lines.push(`  ${name}${padding}  ${wrapped[0] ?? ""}`);
         for (const line of wrapped.slice(1))
             lines.push(`${" ".repeat(start)}${line}`);
+        const note = options.note?.(left);
+        if (note !== undefined && note !== "") {
+            const noteLines = options.width === undefined ? [note] : wrap(note, Math.max(20, options.width - start));
+            for (const line of noteLines) {
+                lines.push(`${" ".repeat(start)}${options.paintNote === undefined ? line : options.paintNote(line)}`);
+            }
+        }
     }
     return lines;
 }
@@ -161,12 +168,23 @@ export function moduleHelp(module, context) {
     const commands = [...module.commands.values()]
         .filter((entry) => entry.verb !== "")
         .sort((a, b) => (a.verb < b.verb ? -1 : a.verb > b.verb ? 1 : 0));
+    // What each command takes, so its options can be seen here rather than one command at a time.
+    // Long forms only: the short ones, the values and the descriptions belong in the command's own help.
+    const options = new Map(commands.map((entry) => {
+        const names = Object.keys(entry.command.spec.input.options);
+        return [entry.verb, names.length === 0 ? undefined : names.map((name) => `--${name}`).join(" ")];
+    }));
     return [
         `${style.bold(`kiriya ${module.id}`)} — ${translator.text(message(module.summary))}`,
         ...aboutLines(module, context),
         "",
         style.bold(translator.text(message("core.help.commands"))),
-        ...table(commands.map((entry) => [entry.verb, translator.text(message(entry.command.spec.summary))]), { width: context.width, paint: (verb) => style.green(verb) }),
+        ...table(commands.map((entry) => [entry.verb, translator.text(message(entry.command.spec.summary))]), {
+            width: context.width,
+            paint: (verb) => style.green(verb),
+            note: (verb) => options.get(verb),
+            paintNote: (line) => style.dim(line),
+        }),
         ...exampleLines(module.examples, context),
         "",
         ...guideLines(module, context),

package/dist/src/i18n/locales/en.js

@@ -24,6 +24,7 @@ export const en = {
     "core.usage.unknown-module": "Unknown module: {name}",
     "core.usage.unknown-command": "Unknown command: {module} {name}",
     "core.usage.did-you-mean": "Did you mean {suggestion}?",
+    "core.usage.see-help": "Run {command} to see what it takes.",
     "core.usage.bad-arguments": "{detail}",
     "core.usage.unknown-option": "Unknown option: {option}",
     "core.usage.takes-no-value": "--{option} does not take a value",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiriya",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "One command-line toolbox for everyday developer work that behaves the same on Windows, Linux and macOS.",
   "mcpName": "io.github.SatPaingOo/kiriya",
   "license": "MIT",