asljs-rq-cli 0.0.0-stage → 0.1.1

package/LICENSE.md

@@ -0,0 +1,20 @@
+# LICENSE
+
+Copyright (c) 2026 Alexandrite Software Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,220 @@
-# Temporary Holding Version
+# rq
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Part of [Alexandrite Software Library][#1] - a set of high-quality, performant
+> JavaScript libraries and tools for everyday use.
+
+AI-assisted markdown-based requirements management: AI skills to manage and
+verify them, tools for structural modification and reporting, presentation apps
+to manage requirement graphs visually.
+
+## Overview
+
+A requirement is a markdown file with a statement about the system. A big
+requirement is decomposed into smaller ones, and each requirement links to the
+requirements and tests that implement it. A test is a markdown file with steps
+that show a requirement holds: deterministic, reproducible commands. The results
+of each run are kept apart, in `.rq/E<n> <slug>.md` execution files that also
+record the git commit, branch and changed files.
+
+The links form a directed graph with no cycles: the requirements are a strict
+hierarchy, each with one parent, and a test may be linked from several
+requirements. A requirement nothing links to is a root, and there may be
+several. A requirement passes when every test and requirement it links to
+passes, by the results they record, and holds when its statements are also fully
+covered by them.
+
+- Commands add, link, unlink, move and remove requirements and tests, and log
+  results, keeping every link valid, the graph free of cycles and each
+  requirement with one parent; others list a requirement's links, its backlinks,
+  or the whole graph as JSON.
+- `rq check [path]` checks the structure; `rq test <target>...` runs the tests
+  of requirements, tests, ids such as `R10` or folders, with `--recurse` those
+  below them too, records the run in an execution file and reports each result;
+  test steps are shell commands, JavaScript or .NET tests, or instructions an AI
+  agent carries out. Each test and requirement keeps its latest result in its
+  `## Status` section; a failed test fails every requirement above it.
+- `rq coverage <target>...` asks an AI agent whether each requirement's
+  sub-requirements and tests fully cover it, and records the verdict.
+- `rq view [path]` serves the graph as a clickable diagram, each border coloured
+  by the result and drawn solid, dashed or dotted by the coverage, and each
+  document of the documents folder rendered as HTML, including documents outside
+  the requirements folder that the requirements link to.
+- `rq agents` prints the formats and the rules every change keeps, for an AI
+  agent that edits the files without `rq`.
+- `rq config` prints the folders, `rq.json`, the agent and the log settings, and
+  where each comes from.
+- The [skills][SK] tell an AI agent how to decompose requirements, write tests,
+  close the coverage gaps `rq coverage` describes in each requirement's `##
+  Coverage` section, and update the related requirements after a change: it
+  writes the text, and changes the structure with the commands.
+
+The model and the commands themselves are functions of the [rq library][RQL].
+This package is the `rq` command, the `rq-mcp` server and `rq view` over them;
+an application that wants the functions without a command line imports
+`asljs-rq` instead.
+
+## Scope
+
+- Requirements and tests are plain markdown files, kept with the code.
+- The graph holds requirements, `R<n> <name>.md`, and tests, `T<n> <name>.md`,
+  and nothing else; its edges are the links in each requirement's `##
+  Implementation` list. Other documents are not part of the graph, though `rq
+  remove` and `rq move` fix the links to what they remove or move in every `.md`
+  file of the documents folder.
+- `rq.json` or `--requirements-dir` and `--documents-dir` set where the
+  requirements are and where every document is; by default both are the working
+  folder.
+- Steps run in order, in the test's folder, until the first that fails. An
+  instruction step needs an AI agent, `claude` or `copilot`; the first one
+  installed is used unless `--ai` names one.
+- The view loads Mermaid from a CDN to draw the diagram; the documents and their
+  links work without it.
+
+## Installation
+
+```bash
+npm install asljs-rq-cli
+```
+
+## Usage
+
+Every command takes `--loglevel <level>`, `--logfile <target>` and `--logformat
+<format>`, or `RQ_LOG_LEVEL`, `RQ_LOG_FILE` and `RQ_LOG_FORMAT`, to log what it
+does, e.g. `--loglevel debug --logfile stderr`; nothing is logged without them.
+
+Build the graph with the commands, and write the statements, descriptions and
+steps as text:
+
+```bash
+npx rq add requirement "requirements/R1 Export.md" "CSV export"   --statement "The report exports as CSV."
+npx rq add test "requirements/R1 Export.md" "PDF export"   --description "The PDF export test produces a valid PDF."   --step 'npm test -- --test-name-pattern="PDF export"'
+```
+
+The parent, `requirements/R1 Export.md`, now lists them:
+
+```markdown
+# R1 Export
+
+The application exports a report as CSV and as PDF.
+
+## Implementation
+
+- [R2 CSV export](<R2 CSV export.md>)
+- [T1 PDF export](<tests/T1 PDF export.md>)
+```
+
+Query the structure:
+
+```bash
+npx rq links "requirements/R1 Export.md" --json
+npx rq backlinks "requirements/tests/T1 PDF export.md"
+npx rq tojson requirements
+```
+
+Check it, then run the test:
+
+```bash
+npx rq check requirements
+npx rq test requirements
+```
+
+```text
+PASS     requirements/tests/T1 PDF export.md - 1 step
+FAIL     requirements/R1 Export.md - 1 of 2 links failed: R2 CSV export: links to no requirement or test
+FAIL     requirements/R2 CSV export.md - links to no requirement or test
+Results  .rq/E1 requirements.md
+```
+
+The execution file records the run and the working directory, then each test:
+
+````markdown
+# E1 requirements
+
+- Date: 2026-10-08T09:30:00.000Z
+- Command: `rq test requirements`
+- Result: PASS - 1 of 1 tests passed
+- Commit: 3f2a9c1d0b8e7f6a5c4d3e2f1a0b9c8d7e6f5a4b
+- Branch: main
+- Changed files: none
+
+## T1 PDF export
+
+- File: <requirements/tests/T1 PDF export.md>
+- Result: PASS - 1 step
+
+```text
+[step 1] Step 1
+$ npm test -- --test-name-pattern="PDF export"
+...
+```
+````
+
+Run a single requirement and everything below it by id, from any folder:
+
+```bash
+npx rq test R1 --recurse --working-dir path/to/project
+```
+
+Browse the graph and the documents:
+
+```bash
+npx rq view requirements --port 8080
+```
+
+With `rq.json` at the project root, the commands default to the requirements
+folder, and the view serves the whole project:
+
+```json
+{
+  "requirementsDir": "requirements",
+  "documentsDir": "."
+}
+```
+
+```bash
+npx rq view
+npx rq config
+```
+
+## Further reading
+
+- [Requirement files][RF] - the formats of requirements, tests, `## Status`
+  sections and execution files, and the rules every change keeps.
+- [Requirements][RM] - how `rq` reads and writes them, and how the graph is
+  built.
+- [Querying the graph][QG] and [Changing the graph][CG] - the structural
+  commands.
+- [rq check][CK], [rq test][TS], [rq coverage][CV], [rq view][VW] and
+  [rq config][CF] - checking, testing, checking coverage, viewing and the
+  configuration.
+- [rq agents][AG] - the instructions for an AI agent that edits the files
+  without `rq`.
+- [rq-mcp][MC] - the MCP server with a tool per command.
+- [Skills][SK] - the AI skills for managing requirements.
+
+Questions and bugs: [asljs/issues][IS].
+
+## Related packages
+
+- [rq library][RQL] - the requirements model and the commands as functions.
+- `asljs-part` defines project artefacts in markdown and checks them with rules.
+
+## License
+
+MIT
+
+[#1]: https://github.com/AlexandriteSoftware/asljs
+[AG]: <docs/rq agents.md>
+[CF]: <docs/rq config.md>
+[CG]: <docs/Changing the graph.md>
+[CK]: <docs/rq check.md>
+[CV]: <docs/rq coverage.md>
+[IS]: https://github.com/AlexandriteSoftware/asljs/issues
+[MC]: docs/rq-mcp.md
+[QG]: <docs/Querying the graph.md>
+[RF]: <../../libs/rq/docs/Requirement files.md>
+[RM]: ../../libs/rq/docs/Requirements.md
+[RQL]: ../../libs/rq/README.md
+[SK]: skills
+[TS]: <docs/rq test.md>
+[VW]: <docs/rq view.md>

package/bin/rq-mcp.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+import { main }
+  from '../dist/mcp.js';
+
+main(
+  process.argv.slice(2),
+  { cwd: process.cwd(),
+    env: process.env,
+    stdout: process.stderr,
+    stderr: process.stderr },
+  process.stdin,
+  line => process.stdout.write(line))
+  .catch(
+    error => {
+      console.error(
+        error instanceof Error
+          ? error.message
+          : String(error));
+
+      process.exitCode = 1;
+    });

package/bin/rq.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+import { main }
+  from '../dist/cli.js';
+
+process.exitCode =
+  await main(
+    process.argv.slice(2),
+    { cwd: process.cwd(),
+      env: process.env,
+      stdout: process.stdout,
+      stderr: process.stderr });

package/dist/cli.d.ts

@@ -0,0 +1,38 @@
+import { type Folders, Io } from 'asljs-rq';
+import { Command } from 'commander';
+import { Server } from 'node:http';
+/**
+ * What a run of the command line leaves: its exit code, and the Io of the
+ * command, with `--working-dir`, `--requirements-dir` and
+ * `--documents-dir` applied.
+ */
+export interface CliState {
+    exitCode: number;
+    io: Io;
+    /**
+     * The folders of the command and where they come from; `null` before a
+     * command runs.
+     */
+    folders: Folders | null;
+}
+/**
+ * The `rq` command line, not yet run: the program, and the state its
+ * actions set.
+ */
+export declare function createCli(args: string[], io: Io, servers?: Server[]): {
+    cli: Command;
+    state: CliState;
+};
+/**
+ * Runs the `rq` command line and returns the exit code. `rq view`
+ * returns once the server listens, and adds it to `servers`; it serves until
+ * whoever passed `servers` closes it.
+ */
+export declare function runCli(args: string[], io: Io, servers?: Server[]): Promise<number>;
+/**
+ * The `rq` executable: runs the command line with a logger provider made
+ * from `--loglevel`, `--logfile`, `--logformat` and the `RQ_LOG_`
+ * variables, and disposes it before it returns the exit code. A server that
+ * `view` started serves until SIGINT or SIGTERM first.
+ */
+export declare function main(args: string[], io: Io): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,315 @@
+import { AI_AGENTS, parseAgentSpec } from 'asljs-agents';
+import { createLoggerProvider, readLoggerOptions } from 'asljs-logging';
+import { postProcess, takeWritten, untilStopped } from 'asljs-mdcli';
+import { execAdd, execAgents, execBacklinks, execCheck, execCoverage, execLink, execLinks, execList, execLog, execMove, execRemove, execTest, execToJson, execUnlink, getLogger, resolveFolders } from 'asljs-rq';
+import { Command, CommanderError } from 'commander';
+import path from 'node:path';
+import { execConfig } from './config.js';
+import { execView } from './view.js';
+const WORKING_DIR = 'The folder to work in: paths resolve against it, rq.json is looked for from it up, and its .rq folder holds the results; the current directory by default';
+const REQUIREMENTS_DIR = 'The folder of the requirements: the default path, and where ids and .md names are searched for; requirementsDir of rq.json, else the working folder';
+const DOCUMENTS_DIR = 'The folder of every document, containing the requirements folder: what view serves, and where backlinks and links to rewrite are searched for; documentsDir of rq.json, else the requirements folder';
+/**
+ * The `rq` command line, not yet run: the program, and the state its
+ * actions set.
+ */
+export function createCli(args, io, servers = []) {
+    const state = { exitCode: 0,
+        io,
+        folders: null };
+    const command = ['rq',
+        ...args.map(arg => /^[\w./:=@+-]+$/.test(arg)
+            ? arg
+            : JSON.stringify(arg))]
+        .join(' ');
+    const cli = new Command();
+    cli.name('rq')
+        .description('AI-assisted requirements management: test and view requirements and tests written in markdown.')
+        .helpCommand(false)
+        .configureOutput({ writeOut: value => io.stdout.write(value),
+        writeErr: value => io.stderr.write(value) })
+        .exitOverride()
+        .option('--loglevel <level>', 'Log level: trace, debug, information, warning, error')
+        .option('--logfile <target>', 'Where logs go: a file path, stdout or stderr')
+        .option('--logformat <format>', 'Log format: auto, json, text or pretty')
+        .hook('preAction', async (_cli, action) => {
+        const options = action.opts();
+        const cwd = options.workingDir === undefined
+            ? io.cwd
+            : path.resolve(io.cwd, options.workingDir);
+        state.folders =
+            await resolveFolders(cwd, options);
+        // A folder left to its default stays unset, so that a command can
+        // tell it from one that was given; `view` serves the folder of its
+        // path then.
+        const given = (setting) => setting.source === 'default'
+            ? undefined
+            : setting.value;
+        state.io =
+            { ...io,
+                cwd,
+                requirementsDir: given(state.folders.requirementsDir),
+                documentsDir: given(state.folders.documentsDir) };
+    });
+    cli.command('test')
+        .description('Run the tests of requirements and tests, record the results in .rq/E<n> <slug>.md, and report their results')
+        .argument('<targets...>', 'Requirement or test files, folders, .md names, or ids such as R10 or T12')
+        .option('--recurse', 'Also run the tests of every requirement below a requirement target')
+        .option('--name <slug>', 'The slug of the results file; the targets by default')
+        .option('--ai [agent]', `The AI agent and model, [${AI_AGENTS.join('|')}][:<model>], e.g. claude:fable, for instruction steps; the first installed agent by default`)
+        .action(async (targets, options) => {
+        state.exitCode =
+            await execTest(state.io, { targets,
+                recurse: options.recurse,
+                name: options.name,
+                command,
+                ai: options.ai === undefined
+                    ? undefined
+                    : parseAgentSpec(options.ai) });
+    });
+    cli.command('coverage')
+        .description('Ask an AI agent whether the sub-requirements and tests of each requirement fully cover it, and record the verdict in its Status')
+        .argument('<targets...>', 'Requirement files, folders, .md names, or ids such as R10')
+        .option('--recurse', 'Also check every requirement below a requirement target')
+        .option('--ai [agent]', `The AI agent and model, [${AI_AGENTS.join('|')}][:<model>], e.g. claude:fable; the first installed agent by default`)
+        .action(async (targets, options) => {
+        state.exitCode =
+            await execCoverage(state.io, { targets,
+                recurse: options.recurse,
+                ai: options.ai === undefined
+                    ? undefined
+                    : parseAgentSpec(options.ai) });
+    });
+    cli.command('view')
+        .description('Serve the requirements graph and the rendered documents over HTTP')
+        .argument('[path]', 'A requirement file, or a folder of requirements; the requirements folder by default')
+        .option('--port <port>', 'Port to listen on, exactly; 0 picks a free one. By default the first free port from 3000 on')
+        .action(async (target, options) => {
+        const port = options.port === undefined
+            ? undefined
+            : Number(options.port);
+        if (port !== undefined
+            && (!Number.isInteger(port)
+                || port < 0
+                || port > 65535)) {
+            throw new Error(`Invalid port: ${options.port}`);
+        }
+        servers.push(await execView(state.io, { target,
+            port }));
+    });
+    cli.command('check')
+        .description('Check the structure of the graph and its documents without running anything')
+        .argument('[path]', 'A requirement file, or a folder of requirements; the requirements folder by default')
+        .action(async (target) => {
+        state.exitCode =
+            await execCheck(state.io, { target });
+    });
+    cli.command('list')
+        .description('List the requirements and tests of the graph, from the roots down')
+        .argument('[path]', 'A requirement file, or a folder of requirements; the requirements folder by default')
+        .option('--json', 'Print JSON')
+        .action(async (target, options) => {
+        state.exitCode =
+            await execList(state.io, { target,
+                json: options.json });
+    });
+    cli.command('links')
+        .description('List the requirements and tests a requirement links to')
+        .argument('<file>', 'A requirement')
+        .option('--json', 'Print JSON')
+        .action(async (file, options) => {
+        state.exitCode =
+            await execLinks(state.io, { file,
+                json: options.json });
+    });
+    cli.command('backlinks')
+        .description('List the requirements that link to a requirement or a test')
+        .argument('<file>', 'A requirement or a test')
+        .option('--json', 'Print JSON')
+        .action(async (file, options) => {
+        state.exitCode =
+            await execBacklinks(state.io, { file,
+                json: options.json });
+    });
+    cli.command('tojson')
+        .description('Print the graph as JSON with the structural fields, the result and the coverage of every document')
+        .argument('[path]', 'A requirement file, or a folder of requirements; the requirements folder by default')
+        .action(async (target) => {
+        state.exitCode =
+            await execToJson(state.io, { target });
+    });
+    cli.command('agents')
+        .description('Print instructions for an AI agent that edits the requirement files directly: their formats and the rules every change keeps')
+        .action(async () => {
+        state.exitCode =
+            await execAgents(state.io);
+    });
+    cli.command('config')
+        .description('Print the configuration: the folders and where they come from, rq.json, the AI agent, logging, and the environment variables')
+        .option('--json', 'Print JSON')
+        .action(async (options) => {
+        state.exitCode =
+            await execConfig(state.io, { folders: state.folders,
+                args,
+                json: options.json });
+    });
+    const add = cli.command('add')
+        .description('Create a requirement or a test and link it from a requirement');
+    add.command('requirement')
+        .description('Create R<n> <name>.md next to the parent and link it from the parent')
+        .argument('<parent>', 'The requirement it implements')
+        .argument('<name>', 'The name after the id')
+        .option('--statement <text>', 'The statement of the requirement')
+        .option('--path <file>', 'The path of the new document, instead of R<n> <name>.md')
+        .action(async (parent, name, options) => {
+        state.exitCode =
+            await execAdd(state.io, { kind: 'requirement',
+                parent,
+                name,
+                body: options.statement,
+                path: options.path });
+    });
+    add.command('test')
+        .description('Create tests/T<n> <name>.md next to the parent and link it from the parent')
+        .argument('<parent>', 'The requirement it shows to hold')
+        .argument('<name>', 'The name after the id')
+        .option('--description <text>', 'What the test shows')
+        .option('--step <command>', 'A shell step running the command; repeat for several', collect, [])
+        .option('--path <file>', 'The path of the new document, instead of tests/T<n> <name>.md')
+        .action(async (parent, name, options) => {
+        state.exitCode =
+            await execAdd(state.io, { kind: 'test',
+                parent,
+                name,
+                body: options.description,
+                steps: options.step,
+                path: options.path });
+    });
+    cli.command('link')
+        .description('Link an existing requirement or test from a requirement')
+        .argument('<parent>', 'The requirement')
+        .argument('<child>', 'The requirement or test that implements it')
+        .action(async (parent, child) => {
+        state.exitCode =
+            await execLink(state.io, { parent,
+                child });
+    });
+    cli.command('unlink')
+        .description('Remove the links from a requirement to a requirement or test')
+        .argument('<parent>', 'The requirement')
+        .argument('<child>', 'The requirement or test it links to')
+        .action(async (parent, child) => {
+        state.exitCode =
+            await execUnlink(state.io, { parent,
+                child });
+    });
+    cli.command('remove')
+        .description('Delete a requirement or a test and the links to it')
+        .argument('<file>', 'A requirement or a test')
+        .option('--recursive', 'Also delete what it links to that nothing else links to')
+        .action(async (file, options) => {
+        state.exitCode =
+            await execRemove(state.io, { file,
+                recursive: options.recursive });
+    });
+    cli.command('move')
+        .description('Move or rename a requirement or a test and rewrite the links to it')
+        .argument('<file>', 'A requirement or a test')
+        .argument('<destination>', 'The new path, or a folder to move it into')
+        .action(async (file, destination) => {
+        state.exitCode =
+            await execMove(state.io, { file,
+                destination });
+    });
+    cli.command('log')
+        .description('Record a result established another way in .rq/E<n> <test>.md')
+        .argument('<test>', 'A test file, .md name or id, e.g. T12')
+        .requiredOption('--result <result>', 'PASS or FAIL')
+        .option('--note <text>', 'A short note')
+        .option('--time <time>', 'The time in ISO 8601; now by default')
+        .action(async (file, options) => {
+        state.exitCode =
+            await execLog(state.io, { file,
+                result: options.result,
+                note: options.note,
+                time: options.time,
+                command });
+    });
+    for (const command of [...cli.commands,
+        ...add.commands]) {
+        if (command !== add) {
+            command.option('--working-dir <folder>', WORKING_DIR)
+                .option('--requirements-dir <folder>', REQUIREMENTS_DIR)
+                .option('--documents-dir <folder>', DOCUMENTS_DIR);
+        }
+    }
+    return { cli,
+        state };
+}
+/**
+ * Runs the `rq` command line and returns the exit code. `rq view`
+ * returns once the server listens, and adds it to `servers`; it serves until
+ * whoever passed `servers` closes it.
+ */
+export async function runCli(args, io, servers = []) {
+    const { cli, state } = createCli(args, io, servers);
+    if (args.length === 0) {
+        cli.outputHelp();
+        return 0;
+    }
+    const logger = getLogger(io, 'rq');
+    logger.debug({ args }, 'command started');
+    takeWritten();
+    try {
+        await cli.parseAsync(args, { from: 'user' });
+    }
+    catch (error) {
+        if (error instanceof CommanderError) {
+            return error.exitCode;
+        }
+        io.stderr.write(`${error instanceof Error
+            ? error.message
+            : String(error)}\n`);
+        state.exitCode = 1;
+    }
+    try {
+        const processed = await postProcess({ ...state.io,
+            logger: getLogger(state.io, 'rq.post-process') }, takeWritten(), 'rq.json');
+        logger.debug({ exitCode: state.exitCode,
+            postProcessing: processed }, 'command finished');
+        return state.exitCode === 0
+            ? processed
+            : state.exitCode;
+    }
+    catch (error) {
+        io.stderr.write(`${error instanceof Error
+            ? error.message
+            : String(error)}\n`);
+        return 1;
+    }
+}
+function collect(value, previous) {
+    return [...previous,
+        value];
+}
+/**
+ * The `rq` executable: runs the command line with a logger provider made
+ * from `--loglevel`, `--logfile`, `--logformat` and the `RQ_LOG_`
+ * variables, and disposes it before it returns the exit code. A server that
+ * `view` started serves until SIGINT or SIGTERM first.
+ */
+export async function main(args, io) {
+    const loggerProvider = createLoggerProvider('RQ_LOG_', readLoggerOptions(args));
+    const servers = [];
+    try {
+        const exitCode = await runCli(args, { ...io,
+            loggerProvider }, servers);
+        for (const server of servers) {
+            await untilStopped(server);
+        }
+        return exitCode;
+    }
+    finally {
+        await loggerProvider.dispose();
+    }
+}