kiriya 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -7,6 +7,39 @@ output shapes are kiriya's public API.
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-09-24
+
+### Changed
+
+- An option that takes one of a list of values now declares that list, so an MCP tool
+  offers it as a JSON Schema `enum` instead of naming it only in prose an agent would have
+  to read. Eleven options gained one: `files list --sort`, `files find --type`,
+  `files hash --algo`, `files info --hash`, `files rename --case` and `--only`,
+  `convert case --to`, `convert time --unit`, `gen token --format` and `net dns --type`.
+  Help and the generated reference are unchanged, since a declared list names itself.
+- Tab completion reads the same list, rather than parsing the value name it was displayed
+  under. `docker logs --tail <n|all>` therefore offers nothing instead of offering `n`,
+  which was never a value it took.
+
+## [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;
 }
@@ -78,7 +85,8 @@ function wordmark(context) {
 }
 /** `-i, --ignore-case` or `--to <file>`, as help and the generated docs show an option. */
 export function optionLabel(name, spec) {
-    const value = spec.type === "string" ? ` ${spec.valueName ?? "<value>"}` : "";
+    const named = spec.valueName ?? (spec.choices === undefined ? "<value>" : `<${spec.choices.join("|")}>`);
+    const value = spec.type === "string" ? ` ${named}` : "";
     const short = spec.short === undefined ? "" : `-${spec.short}, `;
     return `${short}--${name}${value}`;
 }
@@ -161,12 +169,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/core/presentation/mcp/tool-definitions.js

@@ -65,13 +65,15 @@ export function inputSchemaOf(commandId, input, translator, access = READING) {
     }
     for (const [name, option] of toolOptions(input, access)) {
         const text = translator.text(message(option.description));
+        // Choices belong in the enum, where a client can act on them, rather than in prose it must read.
         const description = option.valueName === undefined ? text : `${text} ${option.valueName}`;
+        const choices = option.choices === undefined ? {} : { enum: [...option.choices] };
         if (option.type === "boolean")
             claim(name, { type: "boolean", description });
         else if (option.multiple === true)
-            claim(name, { type: "array", items: { type: "string" }, description });
+            claim(name, { type: "array", items: { type: "string", ...choices }, description });
         else
-            claim(name, { type: "string", description });
+            claim(name, { type: "string", ...choices, description });
     }
     return { type: "object", properties, ...(required.length > 0 ? { required } : {}), additionalProperties: false };
 }

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/dist/src/modules/completion/domain/suggest.js

@@ -1,7 +1,11 @@
-/** The values an option lists in its value name, such as `<hex|base64|base64url>`. */
+/**
+ * The values an option takes, when it takes only a list of them. It reads the list the
+ * command declares, rather than parsing the value name it is displayed under, so an option
+ * whose value name merely looks like a list — `--tail <n|all>`, a number or a word — offers
+ * nothing instead of offering `n`.
+ */
 export function optionChoices(option) {
-    const match = /^<([a-z0-9-]+(?:\|[a-z0-9-]+)+)>$/.exec(option.valueName ?? "");
-    return match?.[1]?.split("|") ?? [];
+    return option.choices === undefined ? [] : [...option.choices];
 }
 function ownCommand(module) {
     return module.commands.find((command) => command.verb === "");

package/dist/src/modules/convert/application/convert-case.use-case.js

@@ -11,7 +11,7 @@ export const caseSpec = {
     input: {
         positionals: [valuePositional],
         options: {
-            to: { type: "string", description: "convert.case.option.to", valueName: `<${TEXT_CASES.join("|")}>` },
+            to: { type: "string", description: "convert.case.option.to", choices: TEXT_CASES },
             file: fileOption,
         },
         parse(raw) {

package/dist/src/modules/convert/application/convert-time.use-case.js

@@ -16,7 +16,7 @@ export const timeSpec = {
     idempotent: false,
     input: {
         positionals: [{ name: "value", description: "convert.time.arg.value", required: false, variadic: false }],
-        options: { unit: { type: "string", description: "convert.time.option.unit", valueName: "<auto|seconds|ms>" } },
+        options: { unit: { type: "string", description: "convert.time.option.unit", choices: EPOCH_UNITS } },
         parse(raw) {
             const reader = new RawReader(raw);
             return { value: reader.positional(0), unit: reader.choice("unit", EPOCH_UNITS, "auto") };

package/dist/src/modules/files/application/find-files.use-case.js

@@ -26,7 +26,7 @@ export const findSpec = {
         options: {
             name: { type: "string", description: "files.find.option.name", valueName: "<glob>" },
             ext: { type: "string", description: "files.find.option.ext", valueName: "<extensions>", multiple: true },
-            type: { type: "string", description: "files.find.option.type", valueName: "<file|dir>" },
+            type: { type: "string", description: "files.find.option.type", choices: FIND_TYPES },
             larger: { type: "string", description: "files.find.option.larger", valueName: "<size>" },
             smaller: { type: "string", description: "files.find.option.smaller", valueName: "<size>" },
             newer: { type: "string", description: "files.find.option.newer", valueName: "<time>" },

package/dist/src/modules/files/application/hash-files.use-case.js

@@ -19,7 +19,7 @@ export const hashSpec = {
     input: {
         positionals: [{ name: "paths", description: "files.hash.arg.paths", required: true, variadic: true, path: true }],
         options: {
-            algo: { type: "string", description: "files.hash.option.algo", valueName: `<${HASH_ALGORITHMS.join("|")}>` },
+            algo: { type: "string", description: "files.hash.option.algo", choices: HASH_ALGORITHMS },
             check: { type: "string", description: "files.hash.option.check", valueName: "<hex>" },
         },
         parse(raw) {

package/dist/src/modules/files/application/list-entries.use-case.js

@@ -16,7 +16,7 @@ export const listSpec = {
         positionals: [{ name: "path", description: "files.list.arg.path", required: false, variadic: false, path: true }],
         options: {
             all: { type: "boolean", description: "files.option.all" },
-            sort: { type: "string", description: "files.list.option.sort", valueName: "<name|size|time>" },
+            sort: { type: "string", description: "files.list.option.sort", choices: LIST_SORTS },
             reverse: { type: "boolean", description: "files.list.option.reverse" },
         },
         parse(raw) {

package/dist/src/modules/files/application/rename-paths.use-case.js

@@ -27,11 +27,11 @@ export const renameSpec = {
             { name: "paths", description: "files.rename.arg.paths", required: false, variadic: true, path: true },
         ],
         options: {
-            case: { type: "string", description: "files.rename.option.case", valueName: `<${CASE_STYLES.join("|")}>` },
+            case: { type: "string", description: "files.rename.option.case", choices: CASE_STYLES },
             find: { type: "string", description: "files.rename.option.find", valueName: "<text>" },
             with: { type: "string", description: "files.rename.option.with", valueName: "<text>" },
             recursive: { type: "boolean", description: "files.rename.option.recursive" },
-            only: { type: "string", description: "files.rename.option.only", valueName: "<files|dirs>" },
+            only: { type: "string", description: "files.rename.option.only", choices: ONLY },
             apply: { type: "boolean", description: "files.rename.option.apply" },
             yes: { type: "boolean", description: "files.rename.option.yes", short: "y", terminalOnly: true },
         },

package/dist/src/modules/files/application/show-info.use-case.js

@@ -28,7 +28,7 @@ export const infoSpec = {
     input: {
         positionals: [{ name: "paths", description: "files.info.arg.paths", required: true, variadic: true, path: true }],
         options: {
-            hash: { type: "string", description: "files.info.option.hash", valueName: `<${HASH_ALGORITHMS.join("|")}>` },
+            hash: { type: "string", description: "files.info.option.hash", choices: HASH_ALGORITHMS },
         },
         parse(raw) {
             const reader = new RawReader(raw);

package/dist/src/modules/gen/application/generate-tokens.use-case.js

@@ -11,7 +11,7 @@ export const tokenSpec = {
         positionals: [],
         options: {
             bytes: { type: "string", description: "gen.token.option.bytes", valueName: "<n>" },
-            format: { type: "string", description: "gen.token.option.format", valueName: "<hex|base64|base64url>" },
+            format: { type: "string", description: "gen.token.option.format", choices: TOKEN_FORMATS },
             count: countOption,
         },
         parse(raw) {

package/dist/src/modules/net/application/lookup-name.use-case.js

@@ -16,7 +16,7 @@ export const dnsSpec = {
     input: {
         positionals: [{ name: "name", description: "net.dns.arg.name", required: true, variadic: false }],
         options: {
-            type: { type: "string", description: "net.dns.option.type", valueName: `<${LOOKUP_TYPES.join("|")}>` },
+            type: { type: "string", description: "net.dns.option.type", choices: LOOKUP_TYPES },
         },
         parse(raw) {
             const reader = new RawReader(raw);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiriya",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",