@zjaaal/artemis 0.0.0-stage → 0.1.2

package/dist/resolve/resolve.js

@@ -0,0 +1,96 @@
+import { ALIAS_SEPARATOR, FLAG_PREFIX, HELP_WORD, ID_SEPARATOR, GLOBAL_FLAG_TOKENS, SUGGEST_LENGTH_DIVISOR, SUGGEST_MIN_DISTANCE, TERMINATOR } from '../constants.js';
+/** One row of the edit-distance table, from the row above it. */
+function nextRow(previous, char, target, rowNumber) {
+    const row = [rowNumber];
+    target.split('').forEach((targetChar, index) => {
+        const substitution = (previous[index] ?? 0) + (char === targetChar ? 0 : 1);
+        const deletion = (previous[index + 1] ?? 0) + 1;
+        const insertion = (row[index] ?? 0) + 1;
+        row.push(Math.min(substitution, deletion, insertion));
+    });
+    return row;
+}
+function editDistance(a, b) {
+    const firstRow = Array.from({ length: b.length + 1 }, (_, index) => index);
+    const lastRow = a
+        .split('')
+        .reduce((previous, char, index) => nextRow(previous, char, b, index + 1), firstRow);
+    return lastRow[b.length] ?? 0;
+}
+const maxSuggestDistance = (name) => Math.max(SUGGEST_MIN_DISTANCE, Math.floor(name.length / SUGGEST_LENGTH_DIVISOR));
+/** The closest command, topic or alias name, if one is close enough to be a likely typo. */
+export const suggest = (registry, name) => {
+    const names = [
+        ...registry.commands.keys(),
+        ...registry.topics.keys(),
+        ...registry.aliases.keys()
+    ];
+    const [best] = names
+        .map((candidate) => ({ candidate, score: editDistance(name, candidate) }))
+        .sort((a, b) => a.score - b.score);
+    return best && best.score <= maxSuggestDistance(name) ? best.candidate : undefined;
+};
+/** A command by id or by alias. */
+export const findCommand = (registry, id) => {
+    const aliased = registry.aliases.get(id);
+    return registry.commands.get(id) ?? (aliased ? registry.commands.get(aliased) : undefined);
+};
+const isFlagToken = (token) => token.startsWith(FLAG_PREFIX);
+/** The words that can name a command: everything before the first flag. */
+function leadingWords(tokens) {
+    const firstFlag = tokens.findIndex(isFlagToken);
+    return firstFlag === -1 ? tokens : tokens.slice(0, firstFlag);
+}
+// "uve" and "uve help" both show the topic; anything else after a topic is unknown
+const isHelpAfterTopic = (words, length) => length === words.length - 1 && words[length] === HELP_WORD;
+const isTopicOnly = (words, length) => length === words.length || isHelpAfterTopic(words, length);
+function resolveTopic(topic, words, length, tokens) {
+    return isTopicOnly(words, length)
+        ? { kind: 'topic', topic, rest: tokens.slice(length) }
+        : { kind: 'unknown', name: words.slice(0, length + 1).join(ID_SEPARATOR) };
+}
+function matchLongest(registry, tokens, words) {
+    for (let length = words.length; length > 0; length--) {
+        const id = words.slice(0, length).join(ID_SEPARATOR);
+        const command = registry.commands.get(id);
+        const topic = registry.topics.get(id);
+        if (command) {
+            return { kind: 'command', entry: command, rest: tokens.slice(length) };
+        }
+        if (topic) {
+            return resolveTopic(topic, words, length, tokens);
+        }
+    }
+    return undefined;
+}
+/**
+ * Works out which command (or topic) the command line names. Words are matched greedily, so
+ * `uve config set http://x` is the command `uve config set` with `http://x` left as its argument.
+ * `uve:config:set` and declared aliases are accepted as well, and a topic followed by `help` (`uve help`)
+ * shows that topic.
+ */
+export const resolve = (registry, argv) => {
+    const [first, ...others] = argv;
+    if (first === undefined) {
+        return { kind: 'unknown', name: '' };
+    }
+    const aliased = registry.aliases.has(first) ? findCommand(registry, first) : undefined;
+    if (aliased) {
+        return { kind: 'command', entry: aliased, rest: others };
+    }
+    const tokens = first.includes(ALIAS_SEPARATOR)
+        ? [...first.split(ALIAS_SEPARATOR), ...others]
+        : [...argv];
+    const words = leadingWords(tokens);
+    return matchLongest(registry, tokens, words) ?? { kind: 'unknown', name: words[0] ?? first };
+};
+export const isGlobalFlagToken = (token) => GLOBAL_FLAG_TOKENS.includes(token);
+/**
+ * Splits off the flags typed before the command name (`art --json math add 1 2`). They belong to
+ * the run, not to a command; `--` ends them like it ends any flags.
+ */
+export const splitLeadingFlags = (argv) => {
+    const firstWord = argv.findIndex((token) => !isFlagToken(token) || token === TERMINATOR);
+    const end = firstWord === -1 ? argv.length : firstWord;
+    return { leading: argv.slice(0, end), rest: argv.slice(end) };
+};

package/dist/run/report.d.ts

@@ -0,0 +1,6 @@
+import type { ReportErrorFn } from '../models.js';
+/**
+ * Prints an error the way the run was asked to: a JSON object on stdout under --json, text on
+ * stderr otherwise. Returns the exit code.
+ */
+export declare const reportError: ReportErrorFn;

package/dist/run/report.js

@@ -0,0 +1,51 @@
+import { EXIT_CODE, FAILURE_CODES } from '../constants.js';
+import { isCommandError, isUsageError } from '../errors/errors.js';
+import { messageOf } from '../utils/error-message.js';
+/** The exit code of a tagged error, trusted only when it is a failure code: a failed run never exits 0. */
+const failureCodeOf = (value) => FAILURE_CODES.find((code) => code === value) ?? EXIT_CODE.FAILED;
+/** Splits an error into what the user sees; only a plain error (a bug) carries its stack. */
+function describeError(error) {
+    const isExpected = isCommandError(error);
+    return {
+        message: messageOf(error),
+        hint: isExpected ? error.hint : undefined,
+        usage: isUsageError(error) ? error.usage : undefined,
+        stack: !isExpected && error instanceof Error ? error.stack : undefined,
+        exitCode: isExpected ? failureCodeOf(error.exitCode) : EXIT_CODE.FAILED
+    };
+}
+function toJson(report, commandId) {
+    return JSON.stringify({
+        ok: false,
+        command: commandId ?? null,
+        error: report.message,
+        ...(report.hint ? { hint: report.hint } : {})
+    });
+}
+function toText(report, { style }) {
+    const lines = [`${style.red('Error:')} ${report.message}`];
+    if (report.hint) {
+        lines.push(`${style.yellow('Hint:')} ${report.hint}`);
+    }
+    if (report.usage) {
+        lines.push('', `${style.bold('Usage')}  ${report.usage}`);
+    }
+    if (report.stack) {
+        lines.push('', style.dim(report.stack));
+    }
+    return lines.join('\n');
+}
+/**
+ * Prints an error the way the run was asked to: a JSON object on stdout under --json, text on
+ * stderr otherwise. Returns the exit code.
+ */
+export const reportError = (error, context) => {
+    const report = describeError(error);
+    if (context.json) {
+        context.io.stdout.write(`${toJson(report, context.commandId)}\n`);
+    }
+    else {
+        context.io.stderr.write(`${toText(report, context)}\n`);
+    }
+    return report.exitCode;
+};

package/dist/run/run.d.ts

@@ -0,0 +1,8 @@
+import type { RunCliFn } from '../models.js';
+/**
+ * Runs a command line and resolves to the exit code; it never calls process.exit, so it can be
+ * embedded and tested. Exit codes: 0 success, 1 the command failed, 2 the command line was wrong.
+ * With --json every call prints one object on stdout: `{ ok: true, command, result }` or
+ * `{ ok: false, command, error, hint }`.
+ */
+export declare const run: RunCliFn;

package/dist/run/run.js

@@ -0,0 +1,163 @@
+import { createContext } from '../context/context.js';
+import { EXIT_CODE, FLAG_PREFIX, HELP_WORD, ID_SEPARATOR } from '../constants.js';
+import { discover } from '../discover/discover.js';
+import { CommandError, UsageError, isUsageError } from '../errors/errors.js';
+import { commandHelp, manifest, rootHelp, topicHelp, topicManifest, usage } from '../help/help.js';
+import { parse } from '../parse/parse.js';
+import { reportError } from './report.js';
+import { resolveWorld } from './world.js';
+import { findCommand, isGlobalFlagToken, resolve, splitLeadingFlags, suggest } from '../resolve/resolve.js';
+import { jsonRequested } from '../utils/terminator.js';
+const isFlagToken = (token) => token.startsWith(FLAG_PREFIX);
+/** Prints text, or under --json the data wrapped in the success envelope. */
+function print(session, text, data) {
+    const output = session.wantsJson
+        ? JSON.stringify({ ok: true, command: session.state.commandId ?? null, result: data })
+        : text;
+    session.io.stdout.write(`${output}\n`);
+}
+const unknownHint = (bin, registry, name) => {
+    const match = suggest(registry, name);
+    if (match) {
+        return `Did you mean "${match}"?`;
+    }
+    // Inside a topic, point at that topic's list rather than the whole CLI
+    const topic = name.split(ID_SEPARATOR).slice(0, -1).join(ID_SEPARATOR);
+    const listing = registry.topics.has(topic) ? `${bin} ${topic} help` : `${bin} help`;
+    return `Run "${listing}" to see the commands.`;
+};
+const unknownCommand = ({ bin, registry }, name) => new UsageError(`Unknown command "${name}".`, { hint: unknownHint(bin, registry, name) });
+/** A bad call to `ctx.invoke` is the calling command's bug, not a wrong command line: exit 1. */
+function parseNested(session, target, id, argv) {
+    try {
+        const nested = parse(target.definition, argv, usage(session.bin, target));
+        if (nested.global.help) {
+            throw new CommandError(`ctx.invoke("${id}"): --help is not something a command can invoke`, {
+                hint: `Call it with its arguments, or read its help with "${session.bin} help ${id}".`
+            });
+        }
+        return nested;
+    }
+    catch (error) {
+        if (!isUsageError(error)) {
+            throw error;
+        }
+        throw new CommandError(`ctx.invoke("${id}"): ${error.message}`, {
+            hint: error.usage ? `Usage: ${error.usage}` : error.hint,
+            cause: error
+        });
+    }
+}
+/** `ctx.invoke`: runs another command, which inherits --json and --yes from the caller. */
+const createInvoke = (session, caller) => async (id, argv = []) => {
+    const target = findCommand(session.registry, id);
+    if (!target) {
+        throw new CommandError(`ctx.invoke: there is no command "${id}"`);
+    }
+    const nested = parseNested(session, target, id, argv);
+    const global = {
+        ...nested.global,
+        json: nested.global.json || caller.json,
+        yes: nested.global.yes || caller.yes
+    };
+    return execute(session, target, { ...nested, global });
+};
+async function execute(session, entry, parsed) {
+    const ctx = createContext({
+        io: session.io,
+        global: parsed.global,
+        // --json promises exactly one object on stdout, so nothing may prompt there either
+        interactive: session.canPrompt && !parsed.global.yes && !parsed.global.json,
+        style: session.style,
+        registry: session.registry,
+        invoke: createInvoke(session, parsed.global)
+    });
+    return entry.definition.run({ args: parsed.args, flags: parsed.flags, ctx });
+}
+/** The text and the --json data for something that was resolved. */
+function helpFor(session, target) {
+    const { bin, registry, style } = session;
+    const everything = manifest(bin, registry);
+    if (target.kind === 'topic') {
+        return {
+            text: topicHelp(bin, registry, target.topic, style),
+            data: topicManifest(everything, target.topic.id)
+        };
+    }
+    return {
+        text: commandHelp(bin, target.entry, style),
+        data: everything.commands.find((command) => command.id === target.entry.id)
+    };
+}
+function showHelpFor(session, words) {
+    if (!words.length) {
+        session.state.commandId = HELP_WORD;
+        print(session, rootHelp(session.bin, session.registry, session.style), manifest(session.bin, session.registry));
+        return;
+    }
+    const target = resolve(session.registry, words);
+    if (target.kind === 'unknown') {
+        throw unknownCommand(session, target.name);
+    }
+    session.state.commandId = target.kind === 'command' ? target.entry.id : target.topic.id;
+    const { text, data } = helpFor(session, target);
+    print(session, text, data);
+}
+/** Works out what the command line asks for and does it. */
+async function dispatch(session, argv) {
+    const { leading, rest } = splitLeadingFlags(argv);
+    const stray = leading.find((token) => !isGlobalFlagToken(token));
+    if (stray) {
+        throw new UsageError(`Unknown option "${stray}"`, {
+            hint: `Flags go after the command: ${session.bin} <command> ${stray}`
+        });
+    }
+    const [first] = rest;
+    if (first === undefined || first === HELP_WORD) {
+        showHelpFor(session, rest.slice(1).filter((token) => !isFlagToken(token)));
+        return EXIT_CODE.OK;
+    }
+    const target = resolve(session.registry, rest);
+    if (target.kind === 'unknown') {
+        throw unknownCommand(session, target.name);
+    }
+    if (target.kind === 'topic') {
+        showHelpFor(session, target.topic.id.split(ID_SEPARATOR));
+        return EXIT_CODE.OK;
+    }
+    session.state.commandId = target.entry.id;
+    const parsed = parse(target.entry.definition, [...leading, ...target.rest], usage(session.bin, target.entry));
+    if (parsed.global.help) {
+        showHelpFor(session, target.entry.id.split(ID_SEPARATOR));
+        return EXIT_CODE.OK;
+    }
+    const result = await execute(session, target.entry, parsed);
+    if (session.wantsJson) {
+        print(session, '', result ?? null);
+    }
+    return EXIT_CODE.OK;
+}
+/**
+ * Runs a command line and resolves to the exit code; it never calls process.exit, so it can be
+ * embedded and tested. Exit codes: 0 success, 1 the command failed, 2 the command line was wrong.
+ * With --json every call prints one object on stdout: `{ ok: true, command, result }` or
+ * `{ ok: false, command, error, hint }`.
+ */
+export const run = async (argv, options) => {
+    const world = { ...resolveWorld(options), bin: options.bin };
+    const wantsJson = jsonRequested(argv);
+    const state = { commandId: undefined };
+    try {
+        const registry = await discover(options.commandsDir);
+        registry.warnings.forEach((warning) => world.io.stderr.write(`${world.style.yellow('warning:')} ${warning}\n`));
+        return await dispatch({ ...world, registry, wantsJson, state }, argv);
+    }
+    catch (error) {
+        return reportError(error, {
+            io: world.io,
+            style: world.style,
+            json: wantsJson,
+            commandId: state.commandId
+        });
+    }
+};

package/dist/run/world.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveWorldFn } from '../models.js';
+/** Works out where output goes, whether to color and whether prompts may show. */
+export declare const resolveWorld: ResolveWorldFn;

package/dist/run/world.js

@@ -0,0 +1,12 @@
+import { DEFAULT_COLOR_ENV } from '../constants.js';
+import { currentProcess } from '../edges/process.js';
+import { createStyle } from '../help/help.js';
+/** Works out where output goes, whether to color and whether prompts may show. */
+export const resolveWorld = (options) => {
+    const system = currentProcess();
+    const io = { stdout: options.stdout ?? system.stdout, stderr: options.stderr ?? system.stderr };
+    const env = options.env ?? system.env;
+    const color = options.color ?? (Boolean(io.stdout.isTTY) && !env[DEFAULT_COLOR_ENV]);
+    const canPrompt = options.interactive ?? (system.stdinIsTTY && system.stdoutIsTTY);
+    return { io, style: createStyle(color), canPrompt };
+};

package/dist/utils/error-code.d.ts

@@ -0,0 +1,3 @@
+import type { ErrorCodeFn } from '../models.js';
+/** The `code` of a Node system error ("ENOENT", "EEXIST", ...), if the error has one. */
+export declare const codeOf: ErrorCodeFn;

package/dist/utils/error-code.js

@@ -0,0 +1,7 @@
+/** The `code` of a Node system error ("ENOENT", "EEXIST", ...), if the error has one. */
+export const codeOf = (error) => {
+    if (!(error instanceof Error) || !('code' in error)) {
+        return undefined;
+    }
+    return typeof error.code === 'string' ? error.code : undefined;
+};

package/dist/utils/error-message.d.ts

@@ -0,0 +1,3 @@
+import type { MessageOfFn } from '../models.js';
+/** The message of whatever was thrown: an Error's message, or the value as text. */
+export declare const messageOf: MessageOfFn;

package/dist/utils/error-message.js

@@ -0,0 +1,2 @@
+/** The message of whatever was thrown: an Error's message, or the value as text. */
+export const messageOf = (error) => error instanceof Error ? error.message : String(error);

package/dist/utils/is-record.d.ts

@@ -0,0 +1,3 @@
+import type { IsRecordFn } from '../models.js';
+/** A plain object: not null, not an array. */
+export declare const isRecord: IsRecordFn;

package/dist/utils/is-record.js

@@ -0,0 +1,2 @@
+/** A plain object: not null, not an array. */
+export const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);

package/dist/utils/tag.d.ts

@@ -0,0 +1,3 @@
+import type { IsTaggedFn } from '../models.js';
+/** Whether a value carries a `Symbol.for` tag, which survives two copies of the package being loaded. */
+export declare const hasTag: IsTaggedFn;

package/dist/utils/tag.js

@@ -0,0 +1,8 @@
+/** Whether a value carries a `Symbol.for` tag, which survives two copies of the package being loaded. */
+export const hasTag = (value, tag) => {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const found = Reflect.get(value, tag);
+    return Boolean(found);
+};

package/dist/utils/terminator.d.ts

@@ -0,0 +1,5 @@
+import type { BeforeTerminatorFn, JsonRequestedFn } from '../models.js';
+/** The words before `--`: after it everything is a plain argument, never a flag. */
+export declare const beforeTerminator: BeforeTerminatorFn;
+/** Whether the command line asks for `--json`. After `--` it is a plain argument, so it does not count. */
+export declare const jsonRequested: JsonRequestedFn;

package/dist/utils/terminator.js

@@ -0,0 +1,8 @@
+import { JSON_FLAG, TERMINATOR } from '../constants.js';
+/** The words before `--`: after it everything is a plain argument, never a flag. */
+export const beforeTerminator = (argv) => {
+    const end = argv.indexOf(TERMINATOR);
+    return argv.slice(0, end === -1 ? argv.length : end);
+};
+/** Whether the command line asks for `--json`. After `--` it is a plain argument, so it does not count. */
+export const jsonRequested = (argv) => beforeTerminator(argv).includes(JSON_FLAG);

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@zjaaal/artemis",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Drop one file in a folder and get a CLI command. A command framework agents can write and read.",
+  "type": "module",
+  "packageManager": "pnpm@10.34.7",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "art": "dist/cli/main.js",
+    "artemis": "dist/cli/main.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./worktrees": {
+      "types": "./dist/kits/worktrees/index.d.ts",
+      "import": "./dist/kits/worktrees/index.js"
+    },
+    "./terminal": {
+      "types": "./dist/kits/terminal/index.d.ts",
+      "import": "./dist/kits/terminal/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "import": "./dist/cli/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zJaaal/artemis.git"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:all": "tsc --noEmit && eslint . && prettier --check . && vitest run",
+    "check-exports": "node scripts/check-exports.mjs",
+    "check-lock": "node scripts/check-lock.mjs",
+    "check-bin": "node scripts/check-bin.mjs"
+  },
+  "dependencies": {
+    "prompts": "2.4.2"
+  },
+  "peerDependencies": {
+    "@types/prompts": "^2.4.9"
+  },
+  "peerDependenciesMeta": {
+    "@types/prompts": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "22.20.5",
+    "@types/prompts": "2.4.9",
+    "@vitest/eslint-plugin": "1.6.27",
+    "eslint": "9.39.5",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-prettier": "5.5.7",
+    "prettier": "3.9.10",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.72.0",
+    "vitest": "4.1.12"
+  }
+}