kiriya 0.1.0

package/dist/src/modules/wait/application/wait-url.use-case.js

@@ -0,0 +1,71 @@
+import { done } from "../../../core/domain/command.js";
+import { UsageError } from "../../../core/domain/errors.js";
+import { RawReader } from "../../../core/domain/input-schema.js";
+import { message } from "../../../core/domain/message.js";
+import { failureReason } from "../domain/reasons.js";
+import { parseHttpAddress, readStatuses, readTimeout, statusIsReady, TIMEOUT_OPTION } from "../domain/wait-input.js";
+import { poll } from "./poll.js";
+/** The longest one request may take, so a server that never answers is asked again. */
+export const URL_ATTEMPT_MS = 5_000;
+export const waitUrlSpec = {
+    id: "wait.url",
+    summary: "wait.url.summary",
+    examples: [
+        "kiriya wait url http://localhost:3000/health",
+        "kiriya wait url https://example.com/ready --status 200 --status 204",
+    ],
+    safety: "read",
+    idempotent: true,
+    usesNetwork: true,
+    runsUserCommands: false,
+    // The address can carry any text to a website, as with open.
+    sensitive: true,
+    input: {
+        positionals: [{ name: "url", description: "wait.url.arg.url", required: true, variadic: false }],
+        options: {
+            status: { type: "string", description: "wait.url.option.status", valueName: "<code>", multiple: true },
+            timeout: TIMEOUT_OPTION,
+        },
+        parse(raw) {
+            const reader = new RawReader(raw);
+            const text = reader.positional(0) ?? "";
+            const url = parseHttpAddress(text);
+            if (url === null)
+                throw new UsageError("wait.url.not-http", { url: text });
+            return { url, statuses: readStatuses(reader), timeoutSeconds: readTimeout(reader) };
+        },
+    },
+};
+export class WaitForUrl {
+    network;
+    clock;
+    spec = waitUrlSpec;
+    constructor(network, clock) {
+        this.network = network;
+        this.clock = clock;
+    }
+    async execute(input, context) {
+        const polled = await poll(this.clock, input.timeoutSeconds * 1000, context.signal, async (allowedMs) => {
+            const outcome = await this.network.request(input.url, Math.min(URL_ATTEMPT_MS, allowedMs), context.signal);
+            return { ready: outcome.ok && statusIsReady(outcome.status, input.statuses), value: outcome };
+        });
+        const { last } = polled;
+        const data = {
+            url: input.url,
+            ready: polled.ready,
+            attempts: polled.attempts,
+            waitedMs: polled.waitedMs,
+            status: last.ok ? last.status : null,
+            failure: last.ok ? null : last.failure,
+            code: last.ok ? null : last.code,
+        };
+        if (polled.ready)
+            return done(data);
+        const reason = last.ok
+            ? message("wait.reason.status", { status: last.status })
+            : failureReason(last.failure, new URL(input.url).hostname, last.code);
+        const failure = message("wait.url.timed-out", { url: input.url, seconds: input.timeoutSeconds, reason });
+        return done(data, { failures: [failure] });
+    }
+}
+//# sourceMappingURL=wait-url.use-case.js.map

package/dist/src/modules/wait/domain/reasons.js

@@ -0,0 +1,14 @@
+import { message } from "../../../core/domain/message.js";
+const REASONS = {
+    refused: "wait.reason.refused",
+    timeout: "wait.reason.timeout",
+    "not-found": "wait.reason.not-found",
+    unreachable: "wait.reason.unreachable",
+    tls: "wait.reason.tls",
+    failed: "wait.reason.failed",
+};
+/** Why the last attempt was not ready, worded to end a sentence. */
+export function failureReason(failure, host, code) {
+    return message(REASONS[failure], { host, code: code ?? failure });
+}
+//# sourceMappingURL=reasons.js.map

package/dist/src/modules/wait/domain/wait-input.js

@@ -0,0 +1,50 @@
+import { UsageError } from "../../../core/domain/errors.js";
+import { parseTarget } from "../../../core/domain/targets.js";
+export const DEFAULT_TIMEOUT_SECONDS = 60;
+export const MAX_TIMEOUT_SECONDS = 3_600;
+export const TIMEOUT_OPTION = {
+    type: "string",
+    description: "wait.option.timeout",
+    valueName: "<seconds>",
+};
+/** --timeout in whole seconds: 60 by default, and at most an hour. */
+export function readTimeout(reader) {
+    const seconds = reader.positiveInteger("timeout", DEFAULT_TIMEOUT_SECONDS);
+    if (seconds > MAX_TIMEOUT_SECONDS)
+        throw new UsageError("wait.timeout-range", { max: MAX_TIMEOUT_SECONDS });
+    return seconds;
+}
+/** A port on this machine, such as 5432, or what net check takes: host:port, [IPv6]:port or a URL; null for anything else. */
+export function parsePortTarget(text) {
+    const value = text.trim();
+    if (!/^\d+$/.test(value))
+        return parseTarget(value);
+    const port = Number(value);
+    return value.length <= 5 && port >= 1 && port <= 65_535 ? { host: "localhost", port } : null;
+}
+/** An http or https address as the URL parser writes it; null for anything else. */
+export function parseHttpAddress(text) {
+    let url;
+    try {
+        url = new URL(text.trim());
+    }
+    catch {
+        return null;
+    }
+    return (url.protocol === "http:" || url.protocol === "https:") && url.hostname !== "" ? url.href : null;
+}
+/** The statuses --status names, each a code from 100 to 599. */
+export function readStatuses(reader) {
+    return reader.strings("status").map((value) => {
+        const status = Number(value);
+        if (!/^\d{3}$/.test(value) || status < 100 || status > 599) {
+            throw new UsageError("wait.url.bad-status", { value });
+        }
+        return status;
+    });
+}
+/** Any 2xx status is ready, unless --status names the statuses that are. */
+export function statusIsReady(status, wanted) {
+    return wanted.length === 0 ? status >= 200 && status < 300 : wanted.includes(status);
+}
+//# sourceMappingURL=wait-input.js.map

package/dist/src/modules/wait/presentation/wait.views.js

@@ -0,0 +1,31 @@
+import { message } from "../../../core/domain/message.js";
+import { formatTarget } from "../../../core/domain/targets.js";
+/** Seconds with one decimal, such as 3.5. */
+const seconds = (ms) => (ms / 1000).toFixed(1);
+// A wait that ran out of time arrives as a failure, so each view prints a line only when it is ready.
+export const portView = (output, format) => {
+    if (!output.ready)
+        return [];
+    const target = formatTarget(output);
+    const line = output.gone
+        ? message("wait.port.closed", { target, seconds: seconds(output.waitedMs) })
+        : message("wait.port.listening", {
+            target,
+            address: output.address ?? output.host,
+            seconds: seconds(output.waitedMs),
+        });
+    return [format.green(format.text(line))];
+};
+export const urlView = (output, format) => {
+    if (!output.ready || output.status === null)
+        return [];
+    const line = message("wait.url.ready", { url: output.url, status: output.status, seconds: seconds(output.waitedMs) });
+    return [format.green(format.text(line))];
+};
+export const fileView = (output, format) => {
+    if (!output.ready)
+        return [];
+    const params = { path: format.path(output.path), seconds: seconds(output.waitedMs) };
+    return [format.green(format.text(message(output.gone ? "wait.file.gone" : "wait.file.exists", params)))];
+};
+//# sourceMappingURL=wait.views.js.map

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

@@ -0,0 +1,21 @@
+import { WaitForFile } from "./application/wait-file.use-case.js";
+import { WaitForPort } from "./application/wait-port.use-case.js";
+import { WaitForUrl } from "./application/wait-url.use-case.js";
+import { fileView, portView, urlView } from "./presentation/wait.views.js";
+export const waitModule = {
+    id: "wait",
+    summary: "wait.summary",
+    about: "wait.about",
+    examples: [
+        "kiriya wait port 5432",
+        "kiriya wait url http://localhost:3000/health",
+        "kiriya wait file dist/app.js --timeout 120",
+    ],
+    guide: "https://github.com/SatPaingOo/kiriya/blob/main/docs/modules/wait.md",
+    register(registrar, ports) {
+        registrar.add(new WaitForPort(ports.network, ports.clock), portView);
+        registrar.add(new WaitForUrl(ports.network, ports.clock), urlView);
+        registrar.add(new WaitForFile(ports.fileSystem, ports.clock), fileView);
+    },
+};
+//# sourceMappingURL=wait.module.js.map

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "kiriya",
+  "version": "0.1.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",
+  "author": "Sat Paing Oo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SatPaingOo/kiriya.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SatPaingOo/kiriya/issues"
+  },
+  "homepage": "https://github.com/SatPaingOo/kiriya#readme",
+  "keywords": [
+    "cli",
+    "developer-tools",
+    "cross-platform",
+    "toolbox",
+    "windows",
+    "linux",
+    "macos"
+  ],
+  "type": "module",
+  "bin": {
+    "kiriya": "dist/src/main.js"
+  },
+  "files": [
+    "dist/src",
+    "!dist/src/**/*.map",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22.13"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "docs": "npm run build && node dist/tools/docs.js",
+    "test": "npm run build && node dist/tools/check-boundaries.js && node --test \"dist/tests/**/*.test.js\"",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@modelcontextprotocol/client": "^2.0.0",
+    "@types/node": "^22.20.2",
+    "eslint": "^10.10.0",
+    "prettier": "^3.9.6",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.70.0"
+  }
+}