kiriya 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,38 @@ output shapes are kiriya's public API.
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-04
+
+### Added
+
+- `secrets scan` finds secrets committed into a folder's files: a token whose issuer gives it
+  a recognisable prefix, a PEM private key, a password inside a URL, or a JWT. It exits 1 when
+  anything is found, so a git hook or a CI step needs no output parsing. **A finding never
+  carries the secret** — `ghp_****`, `postgres://me:****@` — because a report that quoted the
+  value would copy it into scrollback and CI logs. Unlike every other command it reads hidden
+  files by default, since `.env` and `.npmrc` are where secrets sit, and it skips dependency
+  folders instead; `--all` scans those too. A line saying `kiriya:allow-secret`, on it or above
+  it, declares one deliberate, which is how test fixtures and documentation stay quiet.
+  Over MCP it needs `mcp.allowWrite`, as `clip paste` does.
+
+  It deliberately does not flag a line that merely assigns something named like a secret.
+  That rule serves `env show`, where the name and the value are already separate, and over
+  source code it is useless: against kiriya itself it matched 42 lines and every one was
+  syntax, such as `if (token === "--")` in the argv parser.
+
+## [0.1.3] - 2026-10-03
+
+### Added
+
+- `self-update` asks npm's registry whether a newer kiriya exists, and installs it with
+  `--apply`. Without `--apply` nothing changes, so it is safe to run just to find out.
+  It names the exact version the registry answered with rather than `latest`, never offers
+  a prerelease, and refuses to run npm over an install npm did not make, such as a source
+  checkout or a future Homebrew tap. It is never offered to AI agents: an agent must not
+  upgrade, mid-session, the tool it is calling.
+- `doctor` ends with a line naming `self-update`. It still reaches no network itself —
+  until now nothing told anyone that a newer version existed at all.
+
 ## [0.1.2] - 2026-09-24
 
 ### Changed

package/README.md

@@ -87,6 +87,8 @@ option, what each does, and whether it can be undone.
 | [`open`](docs/modules/open.md) | Open a file or folder in its default application, or a web address in the browser. |
 | [`port`](docs/modules/port.md) | See which process listens on a TCP port, end it, or find a free port, the same on every OS. |
 | [`proc`](docs/modules/proc.md) | List, find and end processes, and show them as a tree, the same on every OS. |
+| [`secrets`](docs/modules/secrets.md) | Find secrets committed into a folder's files: tokens, private keys and passwords in plain sight. |
+| [`self-update`](docs/modules/self-update.md) | Ask the registry whether a newer kiriya exists, and install it with --apply. |
 | [`sys`](docs/modules/sys.md) | This machine and the developer tools on it, described the same way on every OS. |
 | [`wait`](docs/modules/wait.md) | Wait until a port listens, a web address answers or a file appears, the same way on every OS. |
 <!-- /kiriya:modules -->

package/dist/src/config/modules.js

@@ -13,6 +13,8 @@ import { netModule } from "../modules/net/net.module.js";
 import { openModule } from "../modules/open/open.module.js";
 import { portModule } from "../modules/port/port.module.js";
 import { procModule } from "../modules/proc/proc.module.js";
+import { secretsModule } from "../modules/secrets/secrets.module.js";
+import { selfUpdateModule } from "../modules/self-update/self-update.module.js";
 import { sysModule } from "../modules/sys/sys.module.js";
 import { waitModule } from "../modules/wait/wait.module.js";
 /** Built-in modules, in no particular order; help lists them sorted. Adding a module is one line here. */
@@ -34,5 +36,7 @@ export const BUILT_IN_MODULES = [
     openModule,
     completionModule,
     waitModule,
+    selfUpdateModule,
+    secretsModule,
 ];
 //# sourceMappingURL=modules.js.map

package/dist/src/{modules/files → core}/application/text-files.js

@@ -1,7 +1,7 @@
 import path from "node:path";
-import { walk } from "../../../core/application/walk.js";
-import { KiriyaError } from "../../../core/domain/errors.js";
-import { globToRegExp } from "../../../core/domain/glob.js";
+import { walk } from "./walk.js";
+import { KiriyaError } from "../domain/errors.js";
+import { globToRegExp } from "../domain/glob.js";
 import { decodeText, MAX_TEXT_BYTES } from "../domain/text-encoding.js";
 /** A text file, or null when it is binary, larger than MAX_TEXT_BYTES, or unreadable. */
 export async function readTextFile(fileSystem, content, target) {
@@ -35,7 +35,10 @@ export async function selectFiles(fileSystem, paths, selection) {
             files.push(target);
         }
         else if (stat?.kind === "directory") {
-            for await (const entry of walk(fileSystem, target, { all: selection.all })) {
+            const options = selection.skipDirectories === undefined
+                ? { all: selection.all }
+                : { all: selection.all, skipDirectories: selection.skipDirectories };
+            for await (const entry of walk(fileSystem, target, options)) {
                 if (entry.kind === "file" && keep(entry.name, entry.rel))
                     files.push(entry.path);
             }

package/dist/src/core/domain/secrets.js

@@ -1,7 +1,7 @@
 import { splitWords } from "./text-case.js";
 const SECRET_ASSIGNMENT = /(pass(word)?|pwd|secret|token|api[-_]?key)\s*[=:]/i;
 const PRIVATE_KEY = /-----BEGIN [A-Z ]*PRIVATE KEY-----/;
-/** `scheme://user:password@host`. */
+/** `scheme://user:password@host`. kiriya:allow-secret */
 const URL_CREDENTIALS = /[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/@]+@/i;
 /** A JSON Web Token: two base64url JSON parts, then the signature. */
 const JWT = /eyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\./;
@@ -15,6 +15,57 @@ export function looksSecret(value) {
         JWT.test(value) ||
         PREFIXED_TOKEN.test(value.trim()));
 }
+export const SECRET_KINDS = ["private-key", "url-credentials", "jwt", "token"];
+/**
+ * Patterns that identify a secret by its own shape, for finding one inside a line of a file.
+ *
+ * `SECRET_ASSIGNMENT` is deliberately not here. It serves `looksSecret`, which judges a whole
+ * value where the name and the value are already separate, and it is useless over source code:
+ * run against kiriya itself it matched 42 lines and every one was wrong — `if (token === "--")`
+ * in the argv parser, `decodeJwt(token: string)`, `readonly secret: Uint8Array`. A scanner that
+ * cries wolf 42 times gets turned off, so it scans only for what cannot be mistaken for syntax.
+ */
+const SCANNED = [
+    { kind: "private-key", pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/g },
+    { kind: "url-credentials", pattern: /[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/@]+@/gi },
+    { kind: "jwt", pattern: /eyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]*/g },
+    {
+        kind: "token",
+        pattern: /(?:(?:ghp|gho|ghu|ghs|ghr)_|github_pat_|glpat-|xox[abprs]-|npm_|sk-)[A-Za-z0-9_-]{16,}|AKIA[0-9A-Z]{16}/g,
+    },
+];
+/** Every secret in one piece of text, earliest first, without overlaps. */
+export function findSecrets(text) {
+    const found = [];
+    const taken = [];
+    for (const { kind, pattern } of SCANNED) {
+        for (const match of text.matchAll(pattern)) {
+            const start = match.index;
+            const end = start + match[0].length;
+            if (taken.some((range) => start < range.end && end > range.start))
+                continue;
+            taken.push({ start, end });
+            found.push({ kind, start, length: match[0].length });
+        }
+    }
+    return found.sort((a, b) => a.start - b.start);
+}
+/**
+ * What may be printed about a match: enough to recognise whose secret it is, never enough to
+ * use it. A finding that carried the value would copy it into scrollback, CI logs and issue
+ * comments, which is the opposite of the point.
+ */
+export function redactSecret(text, match) {
+    const value = text.slice(match.start, match.start + match.length);
+    // The marker line is not itself secret, and it is what tells you what you are looking at.
+    if (match.kind === "private-key")
+        return value;
+    const prefix = /^(?:(?:ghp|gho|ghu|ghs|ghr)_|github_pat_|glpat-|xox[abprs]-|npm_|sk-|AKIA|eyJ)/.exec(value);
+    if (prefix !== null)
+        return `${prefix[0]}****`;
+    const scheme = /^[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:/i.exec(value);
+    return scheme === null ? "****" : `${scheme[0]}****@`;
+}
 const SECRET_WORDS = new Set([
     "password",
     "passwd",

package/dist/src/core/infrastructure/node/node-network.adapter.js

@@ -141,6 +141,61 @@ export class NodeNetworkAdapter {
             outgoing.end();
         });
     }
+    fetchText(url, timeoutMs, maxBytes, signal) {
+        if (signal.aborted)
+            return Promise.reject(new InterruptedError("core.error.interrupted"));
+        return new Promise((resolve, reject) => {
+            const started = performance.now();
+            const elapsed = () => Math.round(performance.now() - started);
+            const target = new URL(url);
+            const send = target.protocol === "https:" ? httpsRequest : httpRequest;
+            const outgoing = send(target, {
+                method: "GET",
+                headers: { "user-agent": "kiriya", accept: "application/json" },
+            });
+            let settled = false;
+            const settle = (outcome) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                signal.removeEventListener("abort", onAbort);
+                outgoing.destroy();
+                if (outcome === null)
+                    reject(new InterruptedError("core.error.interrupted"));
+                else
+                    resolve(outcome);
+            };
+            const onAbort = () => settle(null);
+            const timer = setTimeout(() => settle({ ok: false, failure: "timeout", status: null, code: null, ms: elapsed() }), timeoutMs);
+            signal.addEventListener("abort", onAbort, { once: true });
+            outgoing.once("response", (response) => {
+                const status = response.statusCode ?? 0;
+                const chunks = [];
+                let size = 0;
+                response.on("data", (chunk) => {
+                    size += chunk.length;
+                    // Stop at the limit instead of holding whatever the other end decides to send.
+                    if (size > maxBytes) {
+                        response.destroy();
+                        settle({ ok: false, failure: "too-large", status, code: null, ms: elapsed() });
+                        return;
+                    }
+                    chunks.push(chunk);
+                });
+                response.once("end", () => settle({ ok: true, status, body: Buffer.concat(chunks).toString("utf8"), ms: elapsed() }));
+                response.once("error", (error) => {
+                    const code = errorCode(error);
+                    settle({ ok: false, failure: httpFailure(code), status, code, ms: elapsed() });
+                });
+            });
+            outgoing.on("error", (error) => {
+                const code = errorCode(error);
+                settle({ ok: false, failure: httpFailure(code), status: null, code, ms: elapsed() });
+            });
+            outgoing.end();
+        });
+    }
     async lookup(name) {
         try {
             const found = await systemLookup(name, { all: true });

package/dist/src/core/infrastructure/platform/windows/windows-trash.adapter.js

@@ -45,6 +45,42 @@ for ($i = 0; $i -lt $paths.Length; $i++) {
   } catch { "error|$i|$($_.Exception.Message)" }
 }
 `;
+/**
+ * What the script's output means, separate from running it. Constrained Language Mode needs a
+ * WDAC or AppLocker policy to reproduce, which no test machine has, so that branch is reached
+ * here instead of being left to a machine nobody has.
+ */
+export function readTrashResult(stdout, stderr, paths) {
+    const lines = stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line !== "");
+    const mode = lines.find((line) => line.startsWith("mode|"))?.slice(5) ?? "unknown";
+    if (mode !== "FullLanguage")
+        throw new CapabilityUnavailableError("core.trash.windows.language-mode", { mode });
+    const byIndex = new Map();
+    for (const line of lines) {
+        const [status, indexText, ...rest] = line.split("|");
+        if (indexText === undefined || !/^[0-9]+$/.test(indexText))
+            continue;
+        const index = Number(indexText);
+        const path = paths[index] ?? "";
+        if (status === "ok")
+            byIndex.set(index, { path, ok: true });
+        else if (status === "network")
+            byIndex.set(index, { path, ok: false, reason: message("core.trash.windows.network") });
+        else if (status === "drive") {
+            byIndex.set(index, { path, ok: false, reason: message("core.trash.windows.drive", { drive: rest.join("|") }) });
+        }
+        else
+            byIndex.set(index, { path, ok: false, reason: message("core.trash.failed", { detail: rest.join("|") }) });
+    }
+    return paths.map((path, index) => byIndex.get(index) ?? {
+        path,
+        ok: false,
+        reason: message("core.trash.failed", { detail: stderr.trim().split(/\r?\n/)[0] ?? "no result" }),
+    });
+}
 export class WindowsTrashAdapter {
     location = "core.trash.location.recycle-bin";
     async send(paths) {
@@ -52,35 +88,7 @@ export class WindowsTrashAdapter {
             env: { KIRIYA_TRASH_PATHS: paths.join(NEWLINE) },
             timeoutMs: 10 * 60_000,
         });
-        const lines = result.stdout
-            .split(/\r?\n/)
-            .map((line) => line.trim())
-            .filter((line) => line !== "");
-        const mode = lines.find((line) => line.startsWith("mode|"))?.slice(5) ?? "unknown";
-        if (mode !== "FullLanguage")
-            throw new CapabilityUnavailableError("core.trash.windows.language-mode", { mode });
-        const byIndex = new Map();
-        for (const line of lines) {
-            const [status, indexText, ...rest] = line.split("|");
-            if (indexText === undefined || !/^[0-9]+$/.test(indexText))
-                continue;
-            const index = Number(indexText);
-            const path = paths[index] ?? "";
-            if (status === "ok")
-                byIndex.set(index, { path, ok: true });
-            else if (status === "network")
-                byIndex.set(index, { path, ok: false, reason: message("core.trash.windows.network") });
-            else if (status === "drive") {
-                byIndex.set(index, { path, ok: false, reason: message("core.trash.windows.drive", { drive: rest.join("|") }) });
-            }
-            else
-                byIndex.set(index, { path, ok: false, reason: message("core.trash.failed", { detail: rest.join("|") }) });
-        }
-        return paths.map((path, index) => byIndex.get(index) ?? {
-            path,
-            ok: false,
-            reason: message("core.trash.failed", { detail: result.stderr.trim().split(/\r?\n/)[0] ?? "no result" }),
-        });
+        return readTrashResult(result.stdout, result.stderr, paths);
     }
 }
 //# sourceMappingURL=windows-trash.adapter.js.map

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

@@ -390,6 +390,7 @@ export const en = {
     "doctor.status.warn": "warn",
     "doctor.status.fail": "fail",
     "doctor.check.kiriya": "{version}",
+    "doctor.newer": "doctor asks no network. Run kiriya self-update to see whether a newer version is out.",
     "doctor.check.node": "{version}",
     "doctor.check.node-old": "Node.js {version} is older than {minimum}, the oldest release kiriya supports",
     "doctor.check.os": "{os}",
@@ -666,6 +667,43 @@ export const en = {
     "wait.file.gone": "{path} is gone, after {seconds} s",
     "wait.file.timed-out": "{path} did not appear within {seconds} s",
     "wait.file.still-there": "{path} was still there after {seconds} s",
+    "secrets.summary": "Find secrets committed into a folder's files: tokens, private keys and passwords in plain sight",
+    "secrets.about": "Reads the files under a folder and reports anything that looks like a secret: a token " +
+        "whose issuer gives it a recognisable prefix, a private key, a password in a URL, a JWT, " +
+        "or a line that assigns one. It uses the same judgement as the rest of kiriya, so what " +
+        "env show hides and config set refuses is what this finds. Nothing is sent anywhere and " +
+        "nothing changes. A finding never carries the secret itself, only enough to recognise it, " +
+        "because a report that quoted it would copy it into scrollback and CI logs. Exits 1 when " +
+        "anything is found, so a hook or a CI step needs no output parsing. A line saying " +
+        "kiriya:allow-secret, on it or above it, declares that one deliberate.",
+    "secrets.scan.summary": "Scan a folder's files for tokens, private keys and passwords, without printing them",
+    "secrets.scan.arg.paths": "Folders or files to scan; the current folder by default",
+    "secrets.scan.option.all": "Also look inside dependency folders such as node_modules; hidden files are read either way",
+    "secrets.scan.option.limit": "Stop after this many findings; 500 by default",
+    "secrets.scan.clean": "No secrets found in {checked} file(s)",
+    "secrets.scan.counted": "{count} finding(s) in {checked} file(s)",
+    "secrets.scan.found": "{count} possible secret(s) found",
+    "secrets.scan.allowed": "{count} marked deliberate with kiriya:allow-secret",
+    "secrets.scan.truncated": "The list stopped at --limit; there may be more.",
+    "secrets.scan.how-allow": "A line with kiriya:allow-secret on it, or above it, is left alone.",
+    "self-update.summary": "Ask the registry whether a newer kiriya exists, and install it with --apply",
+    "self-update.about": "Asks npm's registry which version it serves as latest and compares it with this one. " +
+        "Without --apply it changes nothing, so it is safe to run just to find out. With --apply " +
+        "it installs the newer version with npm, and refuses when npm was not what installed " +
+        "kiriya in the first place. This is the only command that reaches the network for a " +
+        "reason other than the one you asked for, which is why it has to be run on purpose: " +
+        "nothing in kiriya checks for updates by itself. A prerelease is never offered.",
+    "self-update.option.apply": "Install the newer version; without it nothing changes",
+    "self-update.current": "kiriya {version} is the newest version",
+    "self-update.available": "kiriya {latest} is out; this is {installed}",
+    "self-update.how-apply": "Run kiriya self-update --apply to install it.",
+    "self-update.how-elsewhere": "npm did not install this kiriya, so update it the way you installed it, to {latest}.",
+    "self-update.applied": "Updated to kiriya {version}",
+    "self-update.unreachable": "The registry could not be reached ({failure}), so the newest version is unknown",
+    "self-update.unreadable": "The registry answered {status}, which does not say which version is latest",
+    "self-update.not-npm": "kiriya {latest} is out, but npm did not install this one, so npm will not replace it",
+    "self-update.no-npm": "npm is not on PATH, so the newer version cannot be installed",
+    "self-update.failed": "npm could not install the newer version (exit code {code}): {detail}",
     "core.processes.failed": "{program} could not list processes (exit code {code}): {detail}",
     "core.processes.unreadable": "Processes could not be read from {source}: {detail}",
     "core.ports.failed": "{program} could not list listening ports (exit code {code}): {detail}",

package/dist/src/main.js

@@ -5,6 +5,7 @@
  */
 import { readFileSync } from "node:fs";
 import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { BUILT_IN_MODULES } from "./config/modules.js";
 import { CommandRegistry } from "./core/application/command-registry.js";
 import { pluginEntries } from "./core/application/config-values.js";
@@ -124,7 +125,12 @@ const ports = {
     protectedPaths: new PathGuard(environment),
     config,
     plugins,
-    runtime: { kiriyaVersion: version, nodeVersion: process.version },
+    runtime: {
+        kiriyaVersion: version,
+        nodeVersion: process.version,
+        // dist/src/main.js, so two levels up is the folder holding package.json.
+        installDirectory: fileURLToPath(new URL("../../", import.meta.url)),
+    },
 };
 for (const module of BUILT_IN_MODULES)
     registry.register(module, ports);

package/dist/src/modules/doctor/presentation/doctor.view.js

@@ -16,6 +16,9 @@ export const doctorView = (output, format) => {
         const status = format.text(message(STATUS_KEYS[check.status])).padEnd(statusWidth);
         return `  ${paint(check.status, status, format)}  ${check.name.padEnd(nameWidth)}  ${format.text(check.detail)}`;
     });
+    // doctor reaches no network, so it cannot know whether this version is behind. It says where
+    // to find out instead, because nothing else told anyone that a newer kiriya exists.
+    lines.push("", format.dim(format.text(message("doctor.newer"))));
     if (output.plugins.length > 0) {
         lines.push("", format.bold(format.text(message("doctor.plugins"))));
         const idWidth = Math.max(...output.plugins.map((plugin) => plugin.id.length));

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

@@ -5,7 +5,7 @@ import { NotFoundError, UsageError } from "../../../core/domain/errors.js";
 import { RawReader } from "../../../core/domain/input-schema.js";
 import { message } from "../../../core/domain/message.js";
 import { byCodePoint } from "../../../core/domain/names.js";
-import { readTextFile } from "./text-files.js";
+import { readTextFile } from "../../../core/application/text-files.js";
 export const compareSpec = {
     id: "files.compare",
     summary: "files.compare.summary",

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

@@ -3,7 +3,7 @@ import { done } from "../../../core/domain/command.js";
 import { NotFoundError } from "../../../core/domain/errors.js";
 import { RawReader } from "../../../core/domain/input-schema.js";
 import { globToRegExp } from "../../../core/domain/glob.js";
-import { parseExtensions } from "../domain/filters.js";
+import { parseExtensions } from "../../../core/domain/filters.js";
 import { parseSize, parseTime } from "../domain/values.js";
 import { walk } from "../../../core/application/walk.js";
 export const FIND_TYPES = ["file", "dir"];

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

@@ -3,8 +3,8 @@ import { done } from "../../../core/domain/command.js";
 import { NotFoundError, OperationFailedError, UsageError } from "../../../core/domain/errors.js";
 import { RawReader } from "../../../core/domain/input-schema.js";
 import { formatBytes } from "../../../core/domain/values/bytes.js";
-import { MAX_TEXT_BYTES, splitLines } from "../domain/text-encoding.js";
-import { readTextFile } from "./text-files.js";
+import { MAX_TEXT_BYTES, splitLines } from "../../../core/domain/text-encoding.js";
+import { readTextFile } from "../../../core/application/text-files.js";
 export const readSpec = {
     id: "files.read",
     summary: "files.read.summary",

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

@@ -4,9 +4,9 @@ import { done, preview } from "../../../core/domain/command.js";
 import { KiriyaError, UsageError } from "../../../core/domain/errors.js";
 import { RawReader } from "../../../core/domain/input-schema.js";
 import { message } from "../../../core/domain/message.js";
-import { parseExtensions } from "../domain/filters.js";
-import { encodeText, escapeRegExp } from "../domain/text-encoding.js";
-import { readTextFile, selectFiles } from "./text-files.js";
+import { parseExtensions } from "../../../core/domain/filters.js";
+import { encodeText, escapeRegExp } from "../../../core/domain/text-encoding.js";
+import { readTextFile, selectFiles } from "../../../core/application/text-files.js";
 /** Changed lines shown per file. */
 const SAMPLE_LINES = 3;
 export const replaceSpec = {

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

@@ -2,9 +2,9 @@ import { expandPaths } from "../../../core/application/paths.js";
 import { done } from "../../../core/domain/command.js";
 import { UsageError } from "../../../core/domain/errors.js";
 import { RawReader } from "../../../core/domain/input-schema.js";
-import { parseExtensions } from "../domain/filters.js";
-import { escapeRegExp } from "../domain/text-encoding.js";
-import { readTextFile, selectFiles } from "./text-files.js";
+import { parseExtensions } from "../../../core/domain/filters.js";
+import { escapeRegExp } from "../../../core/domain/text-encoding.js";
+import { readTextFile, selectFiles } from "../../../core/application/text-files.js";
 /** Longer matching lines are cut here, so one minified file cannot flood the terminal. */
 const LINE_LIMIT = 240;
 export const grepSpec = {

package/dist/src/modules/secrets/application/scan-secrets.use-case.js

@@ -0,0 +1,108 @@
+import { DEPENDENCY_DIRECTORIES } from "../../../config/dependency-directories.js";
+import { expandPaths } from "../../../core/application/paths.js";
+import { readTextFile, selectFiles } from "../../../core/application/text-files.js";
+import { done } from "../../../core/domain/command.js";
+import { RawReader } from "../../../core/domain/input-schema.js";
+import { message } from "../../../core/domain/message.js";
+import { parseExtensions } from "../../../core/domain/filters.js";
+import { findSecrets, redactSecret } from "../../../core/domain/secrets.js";
+import { splitLines } from "../../../core/domain/text-encoding.js";
+import { isAllowed } from "../domain/allow-marker.js";
+export const scanSpec = {
+    id: "secrets.scan",
+    summary: "secrets.scan.summary",
+    examples: ["kiriya secrets scan", "kiriya secrets scan src --ext .ts", "kiriya secrets scan --json"],
+    safety: "read",
+    idempotent: true,
+    // Nothing is sent anywhere, which is most of why anyone would use it.
+    usesNetwork: false,
+    runsUserCommands: false,
+    // The findings point straight at secrets, as `proc list --full` and `clip paste` do.
+    sensitive: true,
+    input: {
+        positionals: [
+            { name: "paths", description: "secrets.scan.arg.paths", required: false, variadic: true, path: true },
+        ],
+        options: {
+            ext: { type: "string", description: "files.option.ext", valueName: "<extensions>", multiple: true },
+            name: { type: "string", description: "files.option.name", valueName: "<glob>" },
+            all: { type: "boolean", description: "secrets.scan.option.all" },
+            limit: { type: "string", description: "secrets.scan.option.limit", valueName: "<n>" },
+        },
+        parse(raw) {
+            const reader = new RawReader(raw);
+            return {
+                paths: reader.positionalsFrom(0),
+                extensions: parseExtensions(reader.strings("ext")),
+                name: reader.string("name"),
+                all: reader.flag("all"),
+                limit: reader.positiveInteger("limit", 500),
+            };
+        },
+    },
+};
+export class ScanSecrets {
+    fileSystem;
+    content;
+    spec = scanSpec;
+    constructor(fileSystem, content) {
+        this.fileSystem = fileSystem;
+        this.content = content;
+    }
+    async execute(input, context) {
+        const targets = input.paths.length === 0 ? ["."] : input.paths;
+        // Hidden files are where secrets live — .env, .npmrc, .git-credentials — so unlike the rest
+        // of kiriya this walks them by default, and keeps dependency folders out instead. --all
+        // drops that guard for someone who really does want to scan what they installed.
+        const roots = await expandPaths(this.fileSystem, targets, context.cwd, true);
+        const files = await selectFiles(this.fileSystem, roots, {
+            all: true,
+            extensions: input.extensions,
+            name: input.name,
+            ...(input.all ? {} : { skipDirectories: DEPENDENCY_DIRECTORIES }),
+        });
+        const findings = [];
+        let checked = 0;
+        let skipped = 0;
+        let allowed = 0;
+        let truncated = false;
+        for (const file of files) {
+            const text = await readTextFile(this.fileSystem, this.content, file);
+            if (text === null) {
+                skipped += 1;
+                continue;
+            }
+            checked += 1;
+            const lines = splitLines(text.text);
+            for (const [index, line] of lines.entries()) {
+                for (const match of findSecrets(line)) {
+                    if (isAllowed(lines, index)) {
+                        allowed += 1;
+                        continue;
+                    }
+                    if (findings.length >= input.limit) {
+                        truncated = true;
+                        break;
+                    }
+                    findings.push({
+                        path: file,
+                        line: index + 1,
+                        column: match.start + 1,
+                        kind: match.kind,
+                        sample: redactSecret(line, match),
+                    });
+                }
+                if (truncated)
+                    break;
+            }
+            if (truncated)
+                break;
+        }
+        const data = { findings, checked, skipped, allowed, truncated };
+        // Found means exit 1, so a hook or a CI step needs no output parsing, as files compare does.
+        if (findings.length === 0)
+            return done(data);
+        return done(data, { failures: [message("secrets.scan.found", { count: findings.length })] });
+    }
+}
+//# sourceMappingURL=scan-secrets.use-case.js.map

package/dist/src/modules/secrets/domain/allow-marker.js

@@ -0,0 +1,23 @@
+/**
+ * A line may say that the secret on it is deliberate, which test fixtures and documentation
+ * need: a scanner whose first run on its own repository is all false positives gets turned
+ * off and never run again. The marker sits next to what it excuses and shows up in review,
+ * which an ignore file in a corner does not.
+ */
+const MARKER = /kiriya:allow-secret/;
+/**
+ * Whether the secret on this line was declared deliberate: by a marker on the line, or on
+ * either neighbour.
+ *
+ * The line below counts because a formatter moves trailing comments. Prettier, which this
+ * repository runs, reflowed `for (… "-----BEGIN RSA PRIVATE KEY-----"]) { // kiriya:allow-secret`
+ * onto the next line and silently unmarked the fixture. A marker a formatter can move is no
+ * marker, so both neighbours count.
+ */
+export function isAllowed(lines, index) {
+    return [index - 1, index, index + 1].some((at) => {
+        const line = lines[at];
+        return line !== undefined && MARKER.test(line);
+    });
+}
+//# sourceMappingURL=allow-marker.js.map

package/dist/src/modules/secrets/presentation/secrets.view.js

@@ -0,0 +1,29 @@
+import { message } from "../../../core/domain/message.js";
+/** Longer samples are cut here, so a minified line cannot flood the terminal. */
+const SAMPLE_LIMIT = 60;
+export const scanView = (output, format) => {
+    if (output.findings.length === 0) {
+        const clean = message("secrets.scan.clean", { checked: output.checked });
+        const lines = [format.green(format.text(clean))];
+        if (output.allowed > 0)
+            lines.push(format.dim(format.text(message("secrets.scan.allowed", { count: output.allowed }))));
+        return lines;
+    }
+    const kindWidth = Math.max(...output.findings.map((finding) => finding.kind.length));
+    const places = output.findings.map((finding) => `${format.path(finding.path)}:${finding.line}:${finding.column}`);
+    const placeWidth = Math.max(...places.map((place) => place.length));
+    const lines = output.findings.map((finding, index) => {
+        const place = (places[index] ?? "").padEnd(placeWidth);
+        const sample = finding.sample.length > SAMPLE_LIMIT ? `${finding.sample.slice(0, SAMPLE_LIMIT)}…` : finding.sample;
+        return `  ${format.yellow(place)}  ${finding.kind.padEnd(kindWidth)}  ${sample}`;
+    });
+    lines.push("", format.text(message("secrets.scan.counted", { count: output.findings.length, checked: output.checked })));
+    if (output.allowed > 0)
+        lines.push(format.dim(format.text(message("secrets.scan.allowed", { count: output.allowed }))));
+    if (output.truncated)
+        lines.push(format.dim(format.text(message("secrets.scan.truncated"))));
+    // Say how to excuse one, because a fixture flagged with no way out is why scanners get turned off.
+    lines.push(format.dim(format.text(message("secrets.scan.how-allow"))));
+    return lines;
+};
+//# sourceMappingURL=secrets.view.js.map

package/dist/src/modules/secrets/secrets.module.js

@@ -0,0 +1,13 @@
+import { ScanSecrets } from "./application/scan-secrets.use-case.js";
+import { scanView } from "./presentation/secrets.view.js";
+export const secretsModule = {
+    id: "secrets",
+    summary: "secrets.summary",
+    about: "secrets.about",
+    examples: ["kiriya secrets scan", "kiriya secrets scan src --ext ts,js", "kiriya secrets scan --json"],
+    guide: "https://github.com/SatPaingOo/kiriya/blob/main/docs/modules/secrets.md",
+    register(registrar, ports) {
+        registrar.add(new ScanSecrets(ports.fileSystem, ports.fileContent), scanView);
+    },
+};
+//# sourceMappingURL=secrets.module.js.map

package/dist/src/modules/self-update/application/update-self.use-case.js

@@ -0,0 +1,86 @@
+import { done } from "../../../core/domain/command.js";
+import { CapabilityUnavailableError } from "../../../core/domain/errors.js";
+import { RawReader } from "../../../core/domain/input-schema.js";
+import { message } from "../../../core/domain/message.js";
+import { installSource } from "../domain/install-source.js";
+import { compareVersions, parseVersion, readLatestVersion } from "../domain/versions.js";
+/** The registry entry for the version npm serves as `latest`. */
+export const LATEST_URL = "https://registry.npmjs.org/kiriya/latest";
+/** Long enough for a slow network, short enough that nobody waits on a broken one. */
+export const ASK_TIMEOUT_MS = 10_000;
+/** That endpoint answers a few kilobytes; a body past this is something else. */
+export const MAX_BODY_BYTES = 262_144;
+/** An npm install over a slow network outlasts the runner's default minute. */
+export const INSTALL_TIMEOUT_MS = 300_000;
+export const selfUpdateSpec = {
+    id: "self-update",
+    summary: "self-update.summary",
+    examples: ["kiriya self-update", "kiriya self-update --apply", "kiriya self-update --json"],
+    // It replaces an installed program, which a reinstall puts back.
+    safety: "write",
+    idempotent: true,
+    usesNetwork: true,
+    runsUserCommands: false,
+    // An agent must never upgrade, mid-session, the tool it is calling.
+    terminalOnly: true,
+    input: {
+        positionals: [],
+        options: {
+            apply: { type: "boolean", description: "self-update.option.apply" },
+        },
+        parse(raw) {
+            const reader = new RawReader(raw);
+            return { apply: reader.flag("apply") };
+        },
+    },
+};
+export class UpdateSelf {
+    network;
+    processRunner;
+    runtime;
+    spec = selfUpdateSpec;
+    constructor(network, processRunner, runtime) {
+        this.network = network;
+        this.processRunner = processRunner;
+        this.runtime = runtime;
+    }
+    async execute(input, context) {
+        const installed = this.runtime.kiriyaVersion;
+        const source = installSource(this.runtime.installDirectory);
+        const outcome = await this.network.fetchText(LATEST_URL, ASK_TIMEOUT_MS, MAX_BODY_BYTES, context.signal);
+        if (!outcome.ok) {
+            const data = { installed, latest: null, newer: false, source, applied: false };
+            return done(data, { failures: [message("self-update.unreachable", { failure: outcome.failure })] });
+        }
+        const latest = outcome.status === 200 ? readLatestVersion(outcome.body) : null;
+        if (latest === null) {
+            const data = { installed, latest: null, newer: false, source, applied: false };
+            return done(data, { failures: [message("self-update.unreadable", { status: outcome.status })] });
+        }
+        const here = parseVersion(installed);
+        const there = parseVersion(latest);
+        const newer = here !== null && there !== null && compareVersions(there, here) > 0;
+        const base = { installed, latest, newer, source };
+        if (!newer || !input.apply)
+            return done({ ...base, applied: false });
+        // Only npm put kiriya here, so only npm is asked to replace it.
+        if (source !== "npm") {
+            return done({ ...base, applied: false }, { failures: [message("self-update.not-npm", { latest })] });
+        }
+        const npm = await this.processRunner.find("npm");
+        if (npm === null)
+            throw new CapabilityUnavailableError("self-update.no-npm");
+        const result = await this.processRunner.run(npm, ["install", "--global", `kiriya@${latest}`], {
+            signal: context.signal,
+            // An install over a slow network outlasts the default minute.
+            timeoutMs: INSTALL_TIMEOUT_MS,
+            // Shown as it arrives, because this is the one command that can take a while.
+            onOutput: (text, stream) => context.passthrough.write(text, stream),
+        });
+        if (result.code !== 0) {
+            return done({ ...base, applied: false }, { failures: [message("self-update.failed", { code: result.code, detail: result.stderr.trim() })] });
+        }
+        return done({ ...base, applied: true });
+    }
+}
+//# sourceMappingURL=update-self.use-case.js.map

package/dist/src/modules/self-update/domain/install-source.js

@@ -0,0 +1,17 @@
+/** How this kiriya got onto the machine, which decides whether it may run a package manager. */
+export const INSTALL_SOURCES = ["npm", "elsewhere"];
+/**
+ * `npm` when kiriya's own files sit inside a `node_modules/kiriya` folder, which is where npm
+ * puts a package and nowhere else puts anything. A source checkout linked with `npm link`
+ * resolves to the repository instead, and a future Homebrew tap or single file would too, so
+ * both read as `elsewhere` and self-update refuses to run npm over them.
+ */
+export function installSource(installDirectory) {
+    const parts = installDirectory.replace(/\\/g, "/").split("/").filter(Boolean);
+    for (let index = 0; index + 1 < parts.length; index += 1) {
+        if (parts[index] === "node_modules" && parts[index + 1] === "kiriya")
+            return "npm";
+    }
+    return "elsewhere";
+}
+//# sourceMappingURL=install-source.js.map

package/dist/src/modules/self-update/domain/versions.js

@@ -0,0 +1,52 @@
+/** Comparing two released versions, and reading the newest one out of what a registry answers. */
+const PATTERN = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+export function parseVersion(text) {
+    const match = PATTERN.exec(text.trim());
+    if (match === null)
+        return null;
+    const [, major, minor, patch, prerelease] = match;
+    return {
+        major: Number(major),
+        minor: Number(minor),
+        patch: Number(patch),
+        prerelease: prerelease ?? null,
+    };
+}
+/**
+ * Negative when `a` is older, positive when newer, zero when the same. A prerelease is older
+ * than the release it leads to, which is all kiriya needs: it never offers one as an upgrade.
+ */
+export function compareVersions(a, b) {
+    for (const part of ["major", "minor", "patch"]) {
+        if (a[part] !== b[part])
+            return a[part] - b[part];
+    }
+    if (a.prerelease === b.prerelease)
+        return 0;
+    if (a.prerelease === null)
+        return 1;
+    if (b.prerelease === null)
+        return -1;
+    return a.prerelease < b.prerelease ? -1 : 1;
+}
+/**
+ * The version the registry calls `latest`, from the body of
+ * `https://registry.npmjs.org/<name>/latest`. null when the body is not what that endpoint
+ * answers, so a proxy returning a login page is a failure rather than a version.
+ */
+export function readLatestVersion(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const version = parsed.version;
+    if (typeof version !== "string")
+        return null;
+    return parseVersion(version) === null ? null : version;
+}
+//# sourceMappingURL=versions.js.map

package/dist/src/modules/self-update/presentation/self-update.view.js

@@ -0,0 +1,19 @@
+import { message } from "../../../core/domain/message.js";
+/** A version that could not be read arrives as a failure, so this prints nothing for it. */
+export const selfUpdateView = (output, format) => {
+    if (output.latest === null)
+        return [];
+    if (output.applied) {
+        return [format.green(format.text(message("self-update.applied", { version: output.latest })))];
+    }
+    if (!output.newer) {
+        return [format.text(message("self-update.current", { version: output.installed }))];
+    }
+    const found = format.text(message("self-update.available", { installed: output.installed, latest: output.latest }));
+    // Say what to type next, because finding out is the whole point of running this.
+    const next = output.source === "npm"
+        ? message("self-update.how-apply")
+        : message("self-update.how-elsewhere", { latest: output.latest });
+    return [format.green(found), format.dim(format.text(next))];
+};
+//# sourceMappingURL=self-update.view.js.map

package/dist/src/modules/self-update/self-update.module.js

@@ -0,0 +1,13 @@
+import { UpdateSelf } from "./application/update-self.use-case.js";
+import { selfUpdateView } from "./presentation/self-update.view.js";
+export const selfUpdateModule = {
+    id: "self-update",
+    summary: "self-update.summary",
+    about: "self-update.about",
+    // A module that is one command shows that command's examples, as doctor does.
+    guide: "https://github.com/SatPaingOo/kiriya/blob/main/docs/modules/self-update.md",
+    register(registrar, ports) {
+        registrar.add(new UpdateSelf(ports.network, ports.processRunner, ports.runtime), selfUpdateView);
+    },
+};
+//# sourceMappingURL=self-update.module.js.map

package/package.json

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