@skillcdn/console 0.3.1 → 0.4.0

package/dist/cli/cli.js

@@ -1,8 +1,8 @@
 import { basename, extname } from "node:path";
 import { parseArgs } from "node:util";
 import { ApiError, createClient, } from "../client.js";
-import { CLIENT_RANGE_HEADER, judgeClient, parseVersion, VERSION_HEADER } from "../compat.js";
-import { addDays, dayOf as dayOfDate, isDay } from "../dates.js";
+import { CLIENT_RANGE_HEADER, CONSOLE_AT_LEAST, consoleRange, formatRange, judgeClient, judgeConsole, parseVersion, VERSION_HEADER, formatVersion as versionText, } from "../compat.js";
+import { addDays, dayOf as dayOfDate, firstDayOfWeek, isDay, weekOf } from "../dates.js";
 import { DEFAULT_PAGE_LIMIT, LIST_LIMIT, MAX_OPTIONS, MIN_OPTIONS } from "../limits.js";
 import { fillRules, RULES_PATH, RULES_TITLE } from "../rules.js";
 import { hostOfLogin, } from "../schemas.js";
@@ -606,10 +606,13 @@ const whoami = async (args, io) => {
     const verdict = command === undefined || server === undefined
         ? undefined
         : judgeClient(command, server).verdict;
+    // The oldest console this command works with (ADR-0038), as it stands within the command's line.
+    const atLeast = io.consoleAtLeast ?? CONSOLE_AT_LEAST;
+    const floor = command === undefined ? atLeast : versionText(consoleRange(command, atLeast).atLeast);
     // A console from before the rule says nothing of itself; the command says so instead.
     const consoleWords = me.console === undefined
         ? "the console does not say its version, so it is older than 0.1.18"
-        : `the console is ${me.console.version} and takes ${me.console.clientRange}`;
+        : `the console is ${me.console.version} and takes ${me.console.clientRange}; this command works with a console from ${floor} on`;
     answer(io, session, {
         ...me,
         console: me.console ?? null,
@@ -673,6 +676,15 @@ const use = async (args, io) => {
     ].join("\n"));
     return EXIT.ok;
 };
+/**
+ * The last day of this week (ADR-0039): the week begins as the workspace says, or, left to the
+ * language, as the person's language has it, else this machine's.
+ */
+async function endOfWeek(io, session, today) {
+    const me = await session.client.me();
+    const language = me.language ?? io.locale ?? "en";
+    return weekOf(today, firstDayOfWeek(language, me.workspace.weekStart ?? "auto")).at(-1) ?? today;
+}
 const tasks = async (args, io) => {
     const { values } = parse(args, {
         state: { type: "string" },
@@ -682,12 +694,13 @@ const tasks = async (args, io) => {
         category: { type: "string" },
         goal: { type: "string" },
         due: { type: "string" },
+        search: { type: "string" },
         archived: { type: "boolean" },
         ...PAGE_OPTIONS,
     }, false);
     const state = stateOf(text(values, "state"));
     if (on(values, "mine") && on(values, "unassigned")) {
-        throw misuse("Say one: --mine for the tasks assigned to you, or --unassigned for those assigned to nobody");
+        throw misuse("Say one: --mine for the tasks you work on, or --unassigned for those nobody works on");
     }
     const page = pageOf(values);
     const session = await open(io, values);
@@ -700,19 +713,22 @@ const tasks = async (args, io) => {
         : due === "overdue"
             ? addDays(today, -1)
             : due === "week"
-                ? addDays(today, 6)
+                ? await endOfWeek(io, session, today)
                 : (dayOf(io, due) ?? undefined);
-    const assignee = on(values, "mine")
-        ? ((await personIdOf(session, "me")) ?? undefined)
-        : undefined;
+    const worker = on(values, "mine") ? ((await personIdOf(session, "me")) ?? undefined) : undefined;
+    const search = text(values, "search")?.trim();
+    if (search === "") {
+        throw misuse("Say what to search for: console tasks --search <words>");
+    }
     const found = await project.tasks({
         ...(state === undefined ? {} : { state }),
         ...(on(values, "open") || due === "overdue" ? { open: true } : {}),
-        ...(assignee === undefined ? {} : { assignee }),
+        ...(worker === undefined ? {} : { worker }),
         ...(on(values, "unassigned") ? { unassigned: true } : {}),
         ...(text(values, "category") === undefined ? {} : { category: text(values, "category") }),
         ...(text(values, "goal") === undefined ? {} : { goal: text(values, "goal") }),
         ...(dueBy === undefined ? {} : { dueBy }),
+        ...(search === undefined ? {} : { q: search }),
         ...(on(values, "archived") ? { archived: true } : {}),
         ...page,
     });
@@ -813,14 +829,41 @@ const skills = async (args, io) => {
     answer(io, session, { ...browsed, read: whole === undefined ? null : bodyOfFolder(whole) }, () => formatSkillBrowse(browsed, whole));
     return EXIT.ok;
 };
+/** The most characters one read of a file asks for: what the console's API allows on one page. */
+const MAX_FILE_LIMIT = 100_000;
+/** A count given as a flag, within its bounds, or nothing; anything else is not understood. */
+function countOf(given, name, bounds) {
+    if (given === undefined) {
+        return undefined;
+    }
+    const count = Number(given);
+    if (!Number.isInteger(count) ||
+        count < bounds.least ||
+        (bounds.most !== undefined && count > bounds.most)) {
+        const range = bounds.most === undefined ? `${bounds.least} or more` : `${bounds.least} to ${bounds.most}`;
+        throw misuse(`Not a number for --${name}, ${range}: ${given}`);
+    }
+    return count;
+}
 const skill = async (args, io) => {
-    const { values, positionals } = parse(args, { file: { type: "string" } });
+    const { values, positionals } = parse(args, {
+        file: { type: "string" },
+        offset: { type: "string" },
+        limit: { type: "string" },
+    });
     const file = text(values, "file");
     // A file is read by its own path from the repository's root; a skill's path beside it would be
     // ignored, which reads as if it mattered, so the two together are not understood.
     if (file !== undefined && positionals.length > 0) {
         throw misuse("Say one: console skill <path of its SKILL.md> for a skill, or console skill --file <path> for a file of the pack.");
     }
+    // A section is a page of a file read as asked (SkillCDN 0.4): the flags mean nothing without one.
+    if (file === undefined &&
+        (text(values, "offset") !== undefined || text(values, "limit") !== undefined)) {
+        throw misuse("--offset and --limit go with --file: console skill --file <path> [--offset <n>] [--limit <n>]");
+    }
+    const offset = countOf(text(values, "offset"), "offset", { least: 0 });
+    const limit = countOf(text(values, "limit"), "limit", { least: 1, most: MAX_FILE_LIMIT });
     const session = await open(io, values);
     const project = await session.project();
     const { listing, summary } = await packOf(project);
@@ -828,6 +871,14 @@ const skill = async (args, io) => {
         answer(io, session, listing, () => formatSkills(listing, io.skillsDir));
         return EXIT.ok;
     }
+    if (file !== undefined && (offset !== undefined || limit !== undefined)) {
+        // One page as asked, the section a search or an outline named; the result says where the
+        // file continues, and asks for nothing.
+        const page = await project.skillFile(file, { offset, limit });
+        const section = page.read === null ? undefined : joinFile([page], summary, limit);
+        answer(io, session, { ...page, read: section === undefined ? null : bodyOfFile(section) }, () => formatSkillFile(page, section));
+        return EXIT.ok;
+    }
     if (file !== undefined) {
         // The file whole, page after page, as the console reads it from the pack.
         const pages = [];
@@ -980,9 +1031,37 @@ const TASK_FIELDS = {
     goal: { type: "string" },
     starts: { type: "string" },
     due: { type: "string" },
-    assignee: { type: "string" },
+    worker: { type: "string", multiple: true },
     parent: { type: "string" },
 };
+/**
+ * The people `--worker` names, each a login or `me`, given again or with commas between for
+ * several, in place of those there were; `none` alone for nobody; nothing when the flag was
+ * not given.
+ */
+async function workerIdsOf(session, given) {
+    if (given.length === 0) {
+        return undefined;
+    }
+    const names = given
+        .flatMap((value) => value.split(","))
+        .map((name) => name.trim())
+        .filter((name) => name.length > 0);
+    if (names.includes("none")) {
+        if (names.length > 1) {
+            throw misuse("Say --worker none alone, for nobody; or the logins of the workers.");
+        }
+        return [];
+    }
+    const ids = [];
+    for (const name of names) {
+        const id = await personIdOf(session, name);
+        if (typeof id === "string" && !ids.includes(id)) {
+            ids.push(id);
+        }
+    }
+    return ids;
+}
 /** What the flags say of a task's fields, as the API takes them; `none` clears a field. */
 async function taskFieldsOf(io, session, project, values) {
     const state = stateOf(text(values, "state"));
@@ -991,7 +1070,7 @@ async function taskFieldsOf(io, session, project, values) {
     const goalId = orNone(text(values, "goal"));
     const startsOn = dayOf(io, text(values, "starts"), true);
     const dueOn = dayOf(io, text(values, "due"), true);
-    const assigneeId = await personIdOf(session, text(values, "assignee"));
+    const workerIds = await workerIdsOf(session, texts(values, "worker"));
     const parent = text(values, "parent");
     const parentId = parent === undefined ? undefined : parent === "none" ? null : (await project.task(parent)).id;
     return {
@@ -1001,7 +1080,7 @@ async function taskFieldsOf(io, session, project, values) {
         ...(goalId === undefined ? {} : { goalId }),
         ...(startsOn === undefined ? {} : { startsOn }),
         ...(dueOn === undefined ? {} : { dueOn }),
-        ...(assigneeId === undefined ? {} : { assigneeId }),
+        ...(workerIds === undefined ? {} : { workerIds }),
         ...(parentId === undefined ? {} : { parentId }),
     };
 }
@@ -1042,7 +1121,7 @@ const editTask = async (args, io) => {
         ...(await taskFieldsOf(io, session, project, values)),
     };
     if (Object.keys(patch).length === 0) {
-        throw misuse("Say what to change: --title, --body, --state, --priority, --category, --goal, --starts, --due, --assignee or --parent; none clears a field.");
+        throw misuse("Say what to change: --title, --body, --state, --priority, --category, --goal, --starts, --due, --worker or --parent; none clears a field.");
     }
     const found = await project.task(ref);
     const changed = await project.updateTask(found.id, patch);
@@ -1308,8 +1387,13 @@ const ask = async (args, io) => {
         file: { type: "string" },
         run: { type: "string" },
         wait: { type: "string" },
+        to: { type: "string" },
     });
     const question = theOne(positionals, 'Say the question: console ask "<question>" --option "<label>" --option "<label>"');
+    const to = text(values, "to");
+    if (to === "none") {
+        throw misuse("Say whom the decision is for: --to <login|me>.");
+    }
     const options = texts(values, "option");
     if (options.length < MIN_OPTIONS || options.length > MAX_OPTIONS) {
         throw misuse(`Give ${MIN_OPTIONS} to ${MAX_OPTIONS} options, one --option each.`);
@@ -1319,18 +1403,49 @@ const ask = async (args, io) => {
     const session = await open(io, values);
     const project = await session.project();
     const runId = await currentRun(project, values);
+    // Whom the decision is for (ADR-0042): the person the agent works for, unless --to names another.
+    const deciderId = await personIdOf(session, to);
     const raised = await project.raiseDecision({
         question,
         options: options.map((label) => ({ label })),
         runId,
         ...(body === undefined ? {} : { body }),
+        ...(typeof deciderId === "string" ? { deciderId } : {}),
     });
     // The id is printed before any waiting, so that a wait cut short loses nothing.
     io.stdout(session.json
         ? `${JSON.stringify(raised, null, 2)}\n`
-        : `Decision ${raised.id} raised on run ${runId}; the run waits for a person.\ndecision id: ${raised.id}\n${formatOptions(raised)}\n`);
+        : `Decision ${raised.id} raised on run ${runId}; the run waits for ${raised.decider.login}.\ndecision id: ${raised.id}\n${formatOptions(raised)}\n`);
     return settle(io, session, project, raised, seconds, true);
 };
+/**
+ * Writes a person's answer on a decision, in their name through the agent (ADR-0021): the
+ * option they chose, or their own words, and a note about it, so that a choice made in chat
+ * or in passing reaches the record the run waits on.
+ */
+const answering = async (args, io) => {
+    const { values, positionals } = parse(args, {
+        option: { type: "string" },
+        own: { type: "string" },
+        note: { type: "string" },
+        file: { type: "string" },
+    });
+    const id = theOne(positionals, 'Say which decision: console answer <id> --option <n>|--own "<answer>" [--note <markdown>|--file <path>]');
+    const option = text(values, "option");
+    const own = text(values, "own");
+    if ((option === undefined) === (own === undefined)) {
+        throw misuse('Say the option chosen, --option <n>, or the person\'s own answer, --own "<words>": one of the two.');
+    }
+    const note = await bodyOf(io, values, text(values, "note"));
+    const session = await open(io, values);
+    const project = await session.project();
+    const answered = await project.answerDecision(id, {
+        ...(own === undefined ? { option } : { own }),
+        ...(note === undefined ? {} : { note }),
+    });
+    answer(io, session, answered, () => formatDecision(answered));
+    return EXIT.ok;
+};
 const decision = async (args, io) => {
     const { values, positionals } = parse(args, {
         wait: { type: "string" },
@@ -1487,20 +1602,33 @@ const restore = async (args, io) => {
     return EXIT.ok;
 };
 const goals = async (args, io) => {
-    const { values } = parse(args, { category: { type: "string" }, state: { type: "string" } }, false);
+    const { values } = parse(args, {
+        category: { type: "string" },
+        state: { type: "string" },
+        search: { type: "string" },
+        ...PAGE_OPTIONS,
+    }, false);
     const state = goalStateOf(text(values, "state"));
     const category = text(values, "category");
+    const search = text(values, "search")?.trim();
+    if (search === "") {
+        throw misuse("Say what to search for: console goals --search <words>");
+    }
+    const page = pageOf(values);
     const session = await open(io, values);
     const project = await session.project();
     const found = await project.goals({
         ...(state === undefined ? {} : { state }),
         ...(category === undefined ? {} : { category }),
+        ...(search === undefined ? {} : { q: search }),
+        ...page,
     });
     answer(io, session, found, () => found.items.length === 0
-        ? state === undefined && category === undefined
+        ? state === undefined && category === undefined && search === undefined
             ? "No goals. An owner sets one: console goal new <title> --due <day>"
             : "No goal matches."
-        : found.items.map(formatGoalLine).join("\n"));
+        : found.items.map(formatGoalLine).join("\n") +
+            formatMore(found.more, page.limit, page.offset));
     return EXIT.ok;
 };
 const GOAL_FIELDS = {
@@ -1579,14 +1707,31 @@ const goal = async (args, io) => {
     return EXIT.ok;
 };
 const decisions = async (args, io) => {
-    const { values } = parse(args, { open: { type: "boolean" }, ...PAGE_OPTIONS }, false);
+    const { values } = parse(args, {
+        open: { type: "boolean" },
+        mine: { type: "boolean" },
+        raised: { type: "boolean" },
+        ...PAGE_OPTIONS,
+    }, false);
     const page = pageOf(values);
     const session = await open(io, values);
+    const open_ = on(values, "open") ? { open: true } : {};
+    if (on(values, "mine") || on(values, "raised")) {
+        // One's own across the projects (ADR-0042), addressed to the person or raised by them for
+        // someone else: the waiting first, each with its project's key.
+        const raised = on(values, "raised");
+        const found = await session.client.myDecisions({ ...open_, raised, ...page });
+        answer(io, session, found, () => found.items.length === 0
+            ? raised
+                ? "No decisions you asked of others."
+                : "No decisions of yours."
+            : found.items
+                .map(({ project, decision }) => `${project.key}  ${formatDecisionLine(decision)}`)
+                .join("\n") + formatMore(found.more, page.limit, page.offset));
+        return EXIT.ok;
+    }
     const project = await session.project();
-    const found = await project.decisions({
-        ...(on(values, "open") ? { open: true } : {}),
-        ...page,
-    });
+    const found = await project.decisions({ ...open_, ...page });
     answer(io, session, found, () => found.items.length === 0
         ? "No decisions."
         : found.items.map(formatDecisionLine).join("\n") +
@@ -2155,6 +2300,7 @@ const COMMANDS = {
     comment,
     file,
     ask,
+    answer: answering,
     decision,
     decisions,
     finish: ending("finished"),
@@ -2238,11 +2384,35 @@ async function noticeVersions(io, seen) {
         shownAt: new Date(now).toISOString(),
     });
 }
+/**
+ * The refusal of a console older than this command works with (ADR-0038), in a console's own
+ * form: a `426` the command reads as it reads the console's, before it acts on anything the
+ * console answered.
+ */
+function consoleRefusal(io, seen) {
+    const command = parseVersion(io.version);
+    const server = parseVersion(seen.version);
+    if (command === undefined || server === undefined) {
+        return undefined;
+    }
+    const { verdict, range } = judgeConsole(server, command, io.consoleAtLeast ?? CONSOLE_AT_LEAST);
+    if (verdict !== "outdated") {
+        return undefined;
+    }
+    return Response.json({
+        error: {
+            code: "console.outdated",
+            message: `This console, ${seen.version}, is older than this command (${io.version}) works with (${formatRange(range)}).`,
+        },
+    }, { status: 426 });
+}
 /** What a refusal of the console is followed by, when there is something to do about it. */
 function hintFor(error, io, seen) {
     switch (error.code) {
         case "client.outdated":
             return `Update the command: ${updateWords(io, seen.version)}\n`;
+        case "console.outdated":
+            return `Install the console's version: ${updateWords(io, seen.version)}; or ask the console's operator to update the console.\n`;
         case "client.too_new":
             return `Install the console's version: ${updateWords(io, seen.version)}; or ask the console's operator to update the console.\n`;
         case "auth.required":
@@ -2317,7 +2487,11 @@ export async function runCli(argv, io) {
             const response = await io.fetch(input, init);
             seen.version = response.headers.get(VERSION_HEADER) ?? seen.version;
             seen.range = response.headers.get(CLIENT_RANGE_HEADER) ?? seen.range;
-            return response;
+            // A console older than this command works with is refused here (ADR-0038); `serve`
+            // carries the pages' own requests, which are not the command's to judge.
+            // A refusal of the console's own is passed on as it is.
+            return ((name === "serve" || response.status === 426 ? undefined : consoleRefusal(io, seen)) ??
+                response);
         },
     };
     try {
@@ -2348,7 +2522,9 @@ export async function runCli(argv, io) {
         }
         if (error instanceof ApiError) {
             io.stderr(`${error.code}: ${error.message}\n${hintFor(error, io, seen)}`);
-            return error.code === "client.outdated" || error.code === "client.too_new"
+            return error.code === "client.outdated" ||
+                error.code === "client.too_new" ||
+                error.code === "console.outdated"
                 ? EXIT.incompatible
                 : EXIT.failed;
         }