asljs-rq-cli 0.0.0-stage → 0.1.1

package/dist/config.d.ts

@@ -0,0 +1,63 @@
+import { type Folders, Io, type Setting } from 'asljs-rq';
+/**
+ * The environment variables `rq` reads.
+ */
+export declare const ENVIRONMENT_VARIABLES: readonly ["RQ_AI_COMMAND", "RQ_LOG_LEVEL", "RQ_LOG_FILE", "RQ_LOG_FORMAT"];
+/**
+ * The configuration `rq` runs with, as `rq config` prints it.
+ */
+export interface Configuration {
+    version: string;
+    workingDir: string;
+    /**
+     * The `rq.json` in use; `null` when there is none.
+     */
+    configFile: string | null;
+    requirementsDir: Setting;
+    documentsDir: Setting;
+    /**
+     * The command `rq.json` runs on the markdown files a command wrote; `null`
+     * when there is none.
+     */
+    markdownPostProcessing: string | null;
+    /**
+     * The agent of instruction steps and `rq coverage` when `--ai` names none:
+     * `RQ_AI_COMMAND`, or the first installed of `agents`, detected when a
+     * command needs it.
+     */
+    agent: {
+        command: string | null;
+        agents: string[];
+    };
+    log: {
+        level: LogSetting;
+        file: LogSetting;
+        format: LogSetting;
+    };
+    /**
+     * Each variable `rq` reads, and its value; `null` when it is not set.
+     */
+    environment: Record<string, string | null>;
+}
+/**
+ * A log setting and where it comes from: its option, its `RQ_LOG_`
+ * variable, or the default.
+ */
+export interface LogSetting {
+    value: string;
+    source: 'option' | 'environment' | 'default';
+}
+/**
+ * Prints the configuration: the folders and where they come from, the
+ * `rq.json` in use, the agent, the log settings, and the environment
+ * variables `rq` reads. `args` is the command line, for the log options.
+ */
+export declare function execConfig(io: Io, options: {
+    folders: Folders;
+    args: readonly string[];
+    json?: boolean;
+}): Promise<number>;
+/**
+ * The configuration `rq` runs with in the working folder of `io`.
+ */
+export declare function readConfiguration(io: Io, folders: Folders, args: readonly string[]): Promise<Configuration>;

package/dist/config.js

@@ -0,0 +1,78 @@
+import { AI_AGENTS } from 'asljs-agents';
+import { readLoggerOptions } from 'asljs-logging';
+import { findConfig } from 'asljs-mdcli';
+import { CONFIG_FILE } from 'asljs-rq';
+import { createRequire } from 'node:module';
+/**
+ * The environment variables `rq` reads.
+ */
+export const ENVIRONMENT_VARIABLES = ['RQ_AI_COMMAND',
+    'RQ_LOG_LEVEL',
+    'RQ_LOG_FILE',
+    'RQ_LOG_FORMAT'];
+/**
+ * Prints the configuration: the folders and where they come from, the
+ * `rq.json` in use, the agent, the log settings, and the environment
+ * variables `rq` reads. `args` is the command line, for the log options.
+ */
+export async function execConfig(io, options) {
+    const configuration = await readConfiguration(io, options.folders, options.args);
+    io.stdout.write(options.json
+        ? `${JSON.stringify(configuration, null, 2)}\n`
+        : describe(configuration));
+    return 0;
+}
+/**
+ * The configuration `rq` runs with in the working folder of `io`.
+ */
+export async function readConfiguration(io, folders, args) {
+    const found = await findConfig(io.cwd, CONFIG_FILE);
+    const environment = Object.fromEntries(ENVIRONMENT_VARIABLES.map(name => [name,
+        io.env[name] || null]));
+    const overrides = readLoggerOptions(args);
+    const pick = (option, variable, fallback) => option !== undefined
+        ? { value: option,
+            source: 'option' }
+        : environment[variable] !== null
+            ? { value: environment[variable],
+                source: 'environment' }
+            : { value: fallback,
+                source: 'default' };
+    const file = pick(overrides.file, 'RQ_LOG_FILE', 'stdout');
+    return { version: packageVersion(),
+        workingDir: io.cwd,
+        configFile: folders.configFile,
+        requirementsDir: folders.requirementsDir,
+        documentsDir: folders.documentsDir,
+        markdownPostProcessing: found?.config.markdownPostProcessing?.trim()
+            || null,
+        agent: { command: environment.RQ_AI_COMMAND,
+            agents: [...AI_AGENTS] },
+        log: { level: pick(overrides.level, 'RQ_LOG_LEVEL', file.source === 'default'
+                ? 'silent'
+                : 'information'),
+            file,
+            format: pick(overrides.format, 'RQ_LOG_FORMAT', 'auto') },
+        environment };
+}
+function describe(configuration) {
+    const setting = (value) => `${value.value} (${value.source})`;
+    const lines = [`version: ${configuration.version}`,
+        `workingDir: ${configuration.workingDir}`,
+        `configFile: ${configuration.configFile ?? '(none)'}`,
+        `requirementsDir: ${setting(configuration.requirementsDir)}`,
+        `documentsDir: ${setting(configuration.documentsDir)}`,
+        `markdownPostProcessing: ${configuration.markdownPostProcessing ?? '(none)'}`,
+        `agent: ${configuration.agent.command === null
+            ? `the first installed of ${configuration.agent.agents.join(', ')}, detected when needed`
+            : `${configuration.agent.command} (RQ_AI_COMMAND)`}`,
+        `logLevel: ${setting(configuration.log.level)}`,
+        `logFile: ${setting(configuration.log.file)}`,
+        `logFormat: ${setting(configuration.log.format)}`,
+        'environment:',
+        ...Object.entries(configuration.environment).map(([name, value]) => `  ${name}=${value ?? ''}`)];
+    return `${lines.join('\n')}\n`;
+}
+function packageVersion() {
+    return createRequire(import.meta.url)('../package.json').version;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createCli, runCli, type CliState } from './cli.js';
+export { createTools, main as runMcpMain, runMcpServer, SERVER_NAME, serverInfo } from './mcp.js';
+export { execView, type ViewOptions } from './view.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createCli, runCli } from './cli.js';
+export { createTools, main as runMcpMain, runMcpServer, SERVER_NAME, serverInfo } from './mcp.js';
+export { execView } from './view.js';

package/dist/mcp.d.ts

@@ -0,0 +1,28 @@
+import { type McpServerInfo, type McpTool } from 'asljs-mcp';
+import { Io } from 'asljs-rq';
+import { Server } from 'node:http';
+import { Readable } from 'node:stream';
+export declare const SERVER_NAME = "asljs-rq";
+/**
+ * The tools of the MCP server: a tool per `rq` command, run as that command
+ * line in `io.cwd`, or in its `workingDir`, with its output as the result.
+ */
+export declare function createTools(io: Io, servers?: Server[]): McpTool[];
+/**
+ * Serves the `rq` commands as MCP tools over a line-delimited JSON-RPC
+ * stream, e.g. standard input and output. Resolves when the input ends,
+ * and closes the servers `view` started.
+ */
+export declare function runMcpServer(io: Io, input: Readable, write: (line: string) => void): Promise<void>;
+/**
+ * The `rq-mcp` executable: serves the tools with a logger provider made
+ * from `--loglevel`, `--logfile`, `--logformat` and the `RQ_LOG_`
+ * variables, and disposes it once the input ends. Standard output carries the
+ * protocol, so a log level without a log file other than stdout throws here,
+ * before the first request is read.
+ */
+export declare function main(args: string[], io: Io, input: Readable, write: (line: string) => void): Promise<void>;
+/**
+ * The name and the version of the installed package.
+ */
+export declare function serverInfo(): McpServerInfo;

package/dist/mcp.js

@@ -0,0 +1,70 @@
+import { createLoggerProvider, readLoggerOptions } from 'asljs-logging';
+import { commandTools, serveLines } from 'asljs-mcp';
+import { getLogger } from 'asljs-rq';
+import { createRequire } from 'node:module';
+import { createCli, runCli } from './cli.js';
+export const SERVER_NAME = 'asljs-rq';
+/**
+ * The tools of the MCP server: a tool per `rq` command, run as that command
+ * line in `io.cwd`, or in its `workingDir`, with its output as the result.
+ */
+export function createTools(io, servers = []) {
+    return commandTools(createCli([], io).cli, async (args) => {
+        let stdout = '';
+        let stderr = '';
+        const exitCode = await runCli(args, { ...io,
+            stdout: { write: (text) => {
+                    stdout += text;
+                } },
+            stderr: { write: (text) => {
+                    stderr += text;
+                } } }, servers);
+        return { exitCode,
+            stdout,
+            stderr };
+    });
+}
+/**
+ * Serves the `rq` commands as MCP tools over a line-delimited JSON-RPC
+ * stream, e.g. standard input and output. Resolves when the input ends,
+ * and closes the servers `view` started.
+ */
+export async function runMcpServer(io, input, write) {
+    const servers = [];
+    try {
+        await serveLines(input, write, createTools(io, servers), serverInfo(), { logger: getLogger(io, 'rq.mcp') });
+    }
+    finally {
+        for (const server of servers) {
+            await new Promise((resolve) => {
+                server.close(resolve);
+                server.closeAllConnections();
+            });
+        }
+    }
+}
+/**
+ * The `rq-mcp` executable: serves the tools with a logger provider made
+ * from `--loglevel`, `--logfile`, `--logformat` and the `RQ_LOG_`
+ * variables, and disposes it once the input ends. Standard output carries the
+ * protocol, so a log level without a log file other than stdout throws here,
+ * before the first request is read.
+ */
+export async function main(args, io, input, write) {
+    const loggerProvider = createLoggerProvider('RQ_LOG_', readLoggerOptions(args), { allowStdout: false });
+    try {
+        await runMcpServer({ ...io,
+            loggerProvider }, input, write);
+    }
+    finally {
+        await loggerProvider.dispose();
+    }
+}
+/**
+ * The name and the version of the installed package.
+ */
+export function serverInfo() {
+    const { version } = createRequire(import.meta.url)('../package.json');
+    return { name: SERVER_NAME,
+        version };
+}

package/dist/view-script.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The part of the diagram the window shows, in diagram coordinates: the SVG's
+ * `viewBox`.
+ */
+export interface ViewBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+/**
+ * The view box zoomed by a wheel turn of `deltaY` around `point`, which stays
+ * where it is on the screen: a turn down, a positive `deltaY`, zooms out.
+ *
+ * Its source is sent to the browser as part of the index page, so it uses
+ * nothing but its arguments.
+ */
+export declare function zoomAt(box: ViewBox, point: Point, deltaY: number): ViewBox;
+/**
+ * The view box moved so that `grabbed`, the diagram point where a drag
+ * started, is under the pointer, now over `point`.
+ *
+ * Its source is sent to the browser as part of the index page, so it uses
+ * nothing but its arguments.
+ */
+export declare function panTo(box: ViewBox, grabbed: Point, point: Point): ViewBox;
+/**
+ * Whether pressing `button` on `target` starts a pan: the main button on
+ * empty space, not on a node or a link, so that a click on a node still opens
+ * its document.
+ *
+ * Its source is sent to the browser as part of the index page, so it uses
+ * nothing but its arguments.
+ */
+export declare function startsPan(button: number, target: {
+    closest(selector: string): unknown;
+}): boolean;

package/dist/view-script.js

@@ -0,0 +1,39 @@
+/**
+ * The view box zoomed by a wheel turn of `deltaY` around `point`, which stays
+ * where it is on the screen: a turn down, a positive `deltaY`, zooms out.
+ *
+ * Its source is sent to the browser as part of the index page, so it uses
+ * nothing but its arguments.
+ */
+export function zoomAt(box, point, deltaY) {
+    const factor = Math.exp(deltaY * 0.0015);
+    return { x: point.x - (point.x - box.x) * factor,
+        y: point.y - (point.y - box.y) * factor,
+        width: box.width * factor,
+        height: box.height * factor };
+}
+/**
+ * The view box moved so that `grabbed`, the diagram point where a drag
+ * started, is under the pointer, now over `point`.
+ *
+ * Its source is sent to the browser as part of the index page, so it uses
+ * nothing but its arguments.
+ */
+export function panTo(box, grabbed, point) {
+    return { x: box.x - (point.x - grabbed.x),
+        y: box.y - (point.y - grabbed.y),
+        width: box.width,
+        height: box.height };
+}
+/**
+ * Whether pressing `button` on `target` starts a pan: the main button on
+ * empty space, not on a node or a link, so that a click on a node still opens
+ * its document.
+ *
+ * Its source is sent to the browser as part of the index page, so it uses
+ * nothing but its arguments.
+ */
+export function startsPan(button, target) {
+    return button === 0
+        && !target.closest('.node, a');
+}

package/dist/view.d.ts

@@ -0,0 +1,39 @@
+import { type PostReply } from 'asljs-mdcli';
+import { Io } from 'asljs-rq';
+import { Server } from 'node:http';
+export { DEFAULT_PORT } from 'asljs-mdcli';
+export interface ViewOptions {
+    /**
+     * The requirement file or folder to view, relative to the working
+     * directory, or an id or `.md` name; the requirements folder when absent.
+     */
+    target?: string;
+    /**
+     * The port to listen on, exactly; 0 picks a free one. When absent, the
+     * first free port from `DEFAULT_PORT` on.
+     */
+    port?: number;
+    host?: string;
+}
+/**
+ * The body of a rendered document: a requirement or test starts with its
+ * full path, which a click copies; any other document is its text alone.
+ */
+export declare function renderDocument(file: string): Promise<string>;
+/**
+ * Saves what the editor of a requirement or test sends to the document at
+ * the URL's path in `folder`: its title and its text, unless the document
+ * changed since the editor opened it; the ids of the requirements folder in
+ * the text become links. Then the document is post-processed, as after a
+ * command.
+ */
+export declare function saveDocument(io: Io, folder: string, url: URL, body: unknown): Promise<PostReply>;
+/**
+ * Starts a web server for a requirement file or folder. It serves the
+ * documents folder, or the folder of the graph when none is given, which must
+ * contain the graph's folder. `/` shows the graph, whose nodes open the
+ * documents; a `.md` file of the served folder is shown rendered and any other
+ * file as it is, so a document a requirement links to opens wherever it is in
+ * the folder. The graph is reloaded on every request for `/`.
+ */
+export declare function execView(io: Io, options: ViewOptions): Promise<Server>;