@tuanhv/op-cli 0.1.0 → 0.2.0

package/dist/commands/wp.js

@@ -5,7 +5,8 @@ import { flattenHalRecord, isFlatLink } from "../core/hal.js";
 import { apiDelete, apiGet, apiPost, apiPatchRaw, apiPostRaw, authenticate, } from "../core/http.js";
 import { allPageSize, DEFAULT_PAGE_SIZE, halElements, parsePageSize, withPageSize, } from "../core/paginate.js";
 import { explicitCustomFieldKey, isIdForm, matchByName, rankByCloseness, resolveName, } from "../context/resolve.js";
-import { parseOptionalId, } from "../context/profile.js";
+import { parseProjectOverride, } from "../context/profile.js";
+import { resolveProjectRef } from "../context/projectref.js";
 import { loadProjectVocabulary, loadStoredMetadata, refreshStoredMetadata, } from "../context/metadata.js";
 import { formatCell, renderTable } from "../output/table.js";
 // Canonical row order for a single-record table; every other key of the
@@ -93,7 +94,7 @@ async function openProfile(runtime, options) {
     runtime.setJsonMode(options.json === true);
     return runtime.resolve({
         profile: options.profile,
-        project: parseOptionalId(options.project),
+        project: parseProjectOverride(options.project),
     });
 }
 function collectValue(value, previous) {
@@ -114,10 +115,12 @@ function addFilterFlags(command) {
         .option("--priority <name>", "priority name or id; repeat to OR values", collectValue, [])
         .option("--parent <reference>", "parent work package id or exact subject", collectValue, [])
         .option("--updated-after <value>", "today, yesterday, days back such as 7d, or YYYY-MM-DD")
+        .option("--created-after <value>", "only work packages created since; same date forms as --updated-after")
+        .option("--search <text>", "substring matched against work package subjects")
         .option("--open", "shorthand for every open status")
         .option("--closed", "shorthand for every closed status")
         .option("--profile <name>", "use this profile for this command only")
-        .option("--project <id>", "override the profile default project");
+        .option("--project <name-or-id>", "override the profile default project");
 }
 function rawListFlags(options) {
     return {
@@ -130,6 +133,8 @@ function rawListFlags(options) {
         priorities: options.priority,
         parents: options.parent,
         updatedAfter: options.updatedAfter,
+        createdAfter: options.createdAfter,
+        search: options.search,
         open: options.open,
         closed: options.closed,
     };
@@ -155,7 +160,7 @@ function projectSource(runtime, profile, flag, label, select, memo) {
         label,
         load: async () => {
             if (profile.project === undefined) {
-                throw new OpCliError("USAGE_ERROR", `--${flag} needs a project to look names up in.`, "pass --project <id> or set a default project on the profile.");
+                throw new OpCliError("USAGE_ERROR", `--${flag} needs a project to look names up in.`, "pass --project <name-or-id> or set a default project on the profile.");
             }
             return select(await (memo === undefined
                 ? loadProjectVocabulary(runtime.env, profile)
@@ -380,10 +385,10 @@ async function runBulkCreate(runtime, subjectArg, options) {
     }
     const profile = await runtime.resolve({
         profile: options.profile,
-        project: parseOptionalId(options.project),
+        project: parseProjectOverride(options.project),
     });
     if (profile.project === undefined) {
-        throw new OpCliError("USAGE_ERROR", "wp create needs a project to create the work package in.", "pass --project <id> or set a default project on the profile.");
+        throw new OpCliError("USAGE_ERROR", "wp create needs a project to create the work package in.", "pass --project <name-or-id> or set a default project on the profile.");
     }
     const memo = newResolutionMemo(runtime, profile);
     const dryRun = options.dryRun === true;
@@ -474,7 +479,7 @@ function customFieldRows(metadata, vocabulary) {
 }
 async function resolveFieldDefinition(runtime, profile, rawName, memo) {
     if (profile.project === undefined) {
-        throw new OpCliError("USAGE_ERROR", "--field needs a project to look field names up in.", "pass --project <id> or set a default project on the profile.");
+        throw new OpCliError("USAGE_ERROR", "--field needs a project to look field names up in.", "pass --project <name-or-id> or set a default project on the profile.");
     }
     const metadata = memo === undefined
         ? loadStoredMetadata(runtime.env, profile)
@@ -918,6 +923,12 @@ async function resolveListFlags(runtime, profile, options) {
     if (options.updatedAfter !== undefined && options.updatedAfter !== "") {
         flags.updatedAfter = options.updatedAfter;
     }
+    if (options.createdAfter !== undefined && options.createdAfter !== "") {
+        flags.createdAfter = options.createdAfter;
+    }
+    if (options.search !== undefined && options.search !== "") {
+        flags.search = options.search;
+    }
     return { ...flags, open: options.open, closed: options.closed };
 }
 function workPackagesPath(filters) {
@@ -1041,6 +1052,7 @@ export const HISTORY_COLUMNS = [
     { title: "KIND", field: "kind" },
     { title: "AUTHOR", field: "user" },
     { title: "COMMENT", field: "comment" },
+    { title: "DETAILS", field: "details" },
     { title: "CREATED", field: "createdAt" },
 ];
 export const RELATION_COLUMNS = [
@@ -1095,6 +1107,11 @@ function linkIdOf(link) {
  * survives flattening because flattenHalRecord drops _type from records.
  * The formattable `comment` collapses to its raw text so the one name
  * means one thing wherever an activity is rendered.
+ *
+ * `details` carries the audit half the comment never could: the changes
+ * behind a system activity, one instance-spelled sentence per attribute
+ * ("Status changed from New to In progress"). A comment activity changed
+ * nothing, so its details render empty rather than absent.
  */
 export function activityRow(element) {
     const resource = element;
@@ -1108,9 +1125,28 @@ export function activityRow(element) {
         kind,
         user: record.user,
         comment: typeof comment?.raw === "string" ? comment.raw : "",
+        details: activityDetails(record.details),
         createdAt: record.createdAt,
     };
 }
+/**
+ * The changes of one activity as a single line: each detail arrives as the
+ * instance already spells it, so joining the raw texts keeps the summary
+ * honest in every locale instead of re-deriving it from values the API
+ * does not hand back. Details without raw text contribute nothing.
+ */
+function activityDetails(details) {
+    if (!Array.isArray(details)) {
+        return "";
+    }
+    return details
+        .map((detail) => {
+        const raw = detail?.raw;
+        return typeof raw === "string" ? raw : "";
+    })
+        .filter((text) => text !== "")
+        .join("; ");
+}
 /**
  * The key set of an activityRow output, so `wp comment` can refuse a bad
  * --fields before it writes. Taken FROM the row builder rather than
@@ -1225,7 +1261,7 @@ export function registerWpCommands(wp, runtime) {
         buildWpFilters(rawListFlags(options), new Date());
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         const now = new Date();
         const limit = parsePageSize(options.limit);
@@ -1268,7 +1304,7 @@ export function registerWpCommands(wp, runtime) {
         buildWpFilters(rawListFlags(options), new Date());
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         const filters = buildWpFilters(await resolveListFlags(runtime, profile, options), new Date());
         const body = (await apiGet(profile.instanceUrl, profile.apiKey, `${workPackagesPath(filters)}&pageSize=1`));
@@ -1283,13 +1319,13 @@ export function registerWpCommands(wp, runtime) {
         .option("--json", "emit a flat JSON record")
         .option("--fields <list>", "comma-separated columns to show")
         .option("--profile <name>", "use this profile for this command only")
-        .option("--project <id>", "override the profile default project")
+        .option("--project <name-or-id>", "override the profile default project")
         .action(async (reference, options) => {
         runtime.setJsonMode(options.json === true);
         requireWpId(reference);
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         const record = flattenHalRecord(await apiGet(profile.instanceUrl, profile.apiKey, `/api/v3/work_packages/${reference}`));
         renderRecord(runtime, options, record);
@@ -1315,7 +1351,7 @@ export function registerWpCommands(wp, runtime) {
         .option("--json", "emit a flat JSON record")
         .option("--fields <list>", "comma-separated columns to show")
         .option("--profile <name>", "use this profile for this command only")
-        .option("--project <id>", "override the profile default project")
+        .option("--project <name-or-id>", "override the profile default project")
         .action(async (subject, options) => {
         if (options.stdin === true) {
             await runBulkCreate(runtime, subject, options);
@@ -1333,10 +1369,10 @@ export function registerWpCommands(wp, runtime) {
         }
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         if (profile.project === undefined) {
-            throw new OpCliError("USAGE_ERROR", "wp create needs a project to create the work package in.", "pass --project <id> or set a default project on the profile.");
+            throw new OpCliError("USAGE_ERROR", "wp create needs a project to create the work package in.", "pass --project <name-or-id> or set a default project on the profile.");
         }
         const { payload, refs } = await prepareCreatePayload(runtime, profile, subject, options);
         const body = await submitCreate(runtime, profile, payload, refs);
@@ -1360,7 +1396,7 @@ export function registerWpCommands(wp, runtime) {
         .option("--json", "emit a flat JSON record")
         .option("--fields <list>", "comma-separated columns to show")
         .option("--profile <name>", "use this profile for this command only")
-        .option("--project <id>", "override the profile default project")
+        .option("--project <name-or-id>", "override the profile default project")
         .action(async (reference, options) => {
         runtime.setJsonMode(options.json === true);
         requireWpId(reference);
@@ -1379,7 +1415,7 @@ export function registerWpCommands(wp, runtime) {
         }
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         const path = `/api/v3/work_packages/${reference}`;
         // The optimistic-locking read: everything below compares against
@@ -1419,27 +1455,120 @@ export function registerWpCommands(wp, runtime) {
         const updated = flattenHalRecord(response.body);
         renderRecord(runtime, options, updated);
     });
+    // -------------------------------------------------------------------------
+    // wp move
+    wp.command("move")
+        .description("Move one work package to another project")
+        .argument("<id>")
+        .argument("<project>", "target project, by id, identifier, or name")
+        .option("--json", "emit a flat JSON record")
+        .option("--fields <list>", "comma-separated columns to show")
+        .option("--profile <name>", "use this profile for this command only")
+        .option("--project <name-or-id>", "override the profile default project")
+        .action(async (reference, projectRef, options) => {
+        runtime.setJsonMode(options.json === true);
+        requireWpId(reference);
+        const profile = await openProfile(runtime, options);
+        const target = await resolveProjectRef((query) => apiGet(profile.instanceUrl, profile.apiKey, query), projectRef);
+        const path = `/api/v3/work_packages/${reference}`;
+        // The optimistic-locking read: the payload below carries its
+        // lockVersion, and the refusal path names the project it came from.
+        const before = await apiGet(profile.instanceUrl, profile.apiKey, path);
+        const flatBefore = flattenHalRecord(before);
+        // A bad --fields name is refused while the work package is still
+        // untouched.
+        selectedFields(options.fields, flatBefore);
+        const currentProjectId = isFlatLink(flatBefore.project)
+            ? flatBefore.project.id
+            : null;
+        if (currentProjectId === target.id) {
+            throw new OpCliError("USAGE_ERROR", `work package ${reference} is already in project ${target.name} (${String(target.id)}).`, "pass a different project to move it to.");
+        }
+        const payload = {
+            lockVersion: lockVersionOf(before),
+            _links: { project: { href: `/api/v3/projects/${String(target.id)}` } },
+        };
+        let response = await patchWp(profile, reference, payload);
+        if (response.status === 409) {
+            // Same race rule as wp update, but project-centric: the generic
+            // checker skips `project` on purpose, so the comparison here is
+            // explicit. A concurrent edit elsewhere is absorbed by one retry
+            // with the fresh lockVersion; a concurrent move is never
+            // overwritten, and a move that already landed exactly where this
+            // one aimed is reported as done.
+            const after = await apiGet(profile.instanceUrl, profile.apiKey, path);
+            const flatAfter = flattenHalRecord(after);
+            const afterProjectId = isFlatLink(flatAfter.project)
+                ? flatAfter.project.id
+                : null;
+            if (afterProjectId === target.id) {
+                renderRecord(runtime, options, flatAfter);
+                return;
+            }
+            if (afterProjectId !== currentProjectId) {
+                throw new OpCliError("CONFLICT", `the work package was moved while this move ran: it is now in project ${String(afterProjectId)}.`, "read the current project, decide again, and repeat the move.", { moved_to: afterProjectId });
+            }
+            payload.lockVersion = lockVersionOf(after);
+            response = await patchWp(profile, reference, payload);
+        }
+        if (response.status >= 400) {
+            // A move the instance refuses is usually a type the target
+            // project does not offer; writeRejection quotes the instance's
+            // own explanation.
+            throw writeRejection(response.status, response.body, "move");
+        }
+        const moved = flattenHalRecord(response.body);
+        renderRecord(runtime, options, moved);
+    });
     // ---------------------------------------------------------------------------
     // wp delete
+    /**
+     * How many work packages the server would cascade-delete beside this
+     * one: every descendant, children and deeper, matched by the ancestor
+     * filter. Undefined when the instance will not say; a read that fails
+     * must not block a confirmed deletion, and the DELETE below stays the
+     * authority on what actually happened.
+     */
+    const countDescendants = async (profile, id) => {
+        try {
+            const page = (await apiGet(profile.instanceUrl, profile.apiKey, `${workPackagesPath([{ name: "ancestor", operator: "=", values: [id] }])}&pageSize=1`));
+            return typeof page.total === "number" ? page.total : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
     wp.command("delete")
         .description("Delete one work package after explicit confirmation")
         .argument("<id>")
         .option("--yes", "confirm the deletion")
         .option("--profile <name>", "use this profile for this command only")
-        .option("--project <id>", "override the profile default project")
+        .option("--project <name-or-id>", "override the profile default project")
         .action(async (reference, options) => {
-        // The guard fires before any resolution or traffic: without --yes
-        // nothing is read, nothing is sent, with or without a terminal.
-        if (options.yes !== true) {
-            throw new OpCliError("USAGE_ERROR", `wp delete refuses to remove work package ${reference} without confirmation.`, "repeat the command with --yes to confirm the deletion.");
-        }
         requireWpId(reference);
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
+        // Without --yes the only traffic is the descendant read: the
+        // refusal names what the cascade would destroy, but no write ever
+        // leaves without the flag, terminal or not.
+        const descendants = await countDescendants(profile, reference);
+        if (options.yes !== true) {
+            throw new OpCliError("USAGE_ERROR", `wp delete refuses to remove work package ${reference} without confirmation.`
+                + (descendants !== undefined && descendants > 0
+                    ? ` Work package ${reference} has ${descendants} `
+                        + `${descendants === 1 ? "descendant" : "descendants"};`
+                        + " they are deleted with it."
+                    : ""), "repeat the command with --yes to confirm the deletion.");
+        }
         await apiDelete(profile.instanceUrl, profile.apiKey, `/api/v3/work_packages/${reference}`);
-        runtime.write(`Deleted work package ${reference}.\n`);
+        runtime.write(`Deleted work package ${reference}`
+            + (descendants !== undefined && descendants > 0
+                ? ` and its ${descendants} `
+                    + `${descendants === 1 ? "descendant" : "descendants"}`
+                : "")
+            + ".\n");
     });
     // ---------------------------------------------------------------------------
     // Discussion, history, relations, schema
@@ -1448,7 +1577,7 @@ export function registerWpCommands(wp, runtime) {
             const profile = await runtime.resolve({
                 profile: typeof options.profile === "string" ? options.profile : undefined,
                 project: typeof options.project === "string"
-                    ? parseOptionalId(options.project)
+                    ? parseProjectOverride(options.project)
                     : undefined,
             });
             return (path) => apiGet(profile.instanceUrl, profile.apiKey, path);
@@ -1484,7 +1613,7 @@ export function registerWpCommands(wp, runtime) {
         json: "--json",
         fields: "--fields <list>",
         profile: "--profile <name>",
-        project: "--project <id>",
+        project: "--project <name-or-id>",
     };
     wp.command("comment")
         .description("Add a comment to one work package")

package/dist/context/metadata.js

@@ -376,7 +376,7 @@ export async function fetchProjectVocabulary(profile, projectId) {
 }
 export async function loadProjectVocabulary(env, profile) {
     if (profile.project === undefined) {
-        throw new OpCliError("USAGE_ERROR");
+        throw new OpCliError("USAGE_ERROR", "the lookup needs a project to read its vocabulary from.", "pass --project <id> or set a default project on the profile.");
     }
     return loadProjectVocabularyById(env, profile, profile.project);
 }

package/dist/context/profile.js

@@ -1,16 +1,25 @@
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { OpCliError } from "../core/errors.js";
+import { isIdForm } from "./resolve.js";
+import { resolveProjectOverride } from "./projectref.js";
 export const LOGIN_PROFILE = "default";
+/**
+ * The directory profiles live in, when one can be located at all:
+ * OP_CLI_CONFIG_DIR wins, then ~/.config/op-cli. Optional features
+ * (the update notice cache) use this to silence themselves when no
+ * directory exists; writes go through writableConfigDirectory instead.
+ */
+export function configDirectory(env) {
+    return env.OP_CLI_CONFIG_DIR
+        ?? (env.HOME !== undefined ? join(env.HOME, ".config", "op-cli") : undefined);
+}
 function writableConfigDirectory(env) {
-    if (env.OP_CLI_CONFIG_DIR) {
-        return env.OP_CLI_CONFIG_DIR;
-    }
-    const home = env.HOME;
-    if (!home) {
+    const directory = configDirectory(env);
+    if (directory === undefined) {
         throw new OpCliError("USAGE_ERROR");
     }
-    return join(home, ".config", "op-cli");
+    return directory;
 }
 async function readStored(env) {
     const directory = env.OP_CLI_CONFIG_DIR ??
@@ -151,6 +160,20 @@ export function parseOptionalId(raw) {
     }
     return value;
 }
+/**
+ * The parsed `--project` value: digit forms validate as ids through
+ * parseOptionalId above, anything else stays a string for the instance
+ * to resolve by identifier or name (#34).
+ */
+export function parseProjectOverride(raw) {
+    if (raw === undefined || raw === "") {
+        return undefined;
+    }
+    if (typeof raw === "number") {
+        return raw;
+    }
+    return isIdForm(raw) ? parseOptionalId(raw) : raw;
+}
 export async function resolveProfile(env, overrides = {}) {
     const state = await readStored(env);
     const explicitName = firstDefined(overrides.profile, env.OP_CLI_PROFILE);
@@ -189,13 +212,18 @@ export async function resolveProfile(env, overrides = {}) {
         name !== undefined &&
         instanceUrl === entry.url.replace(/\/+$/, "") &&
         apiKey === secret;
+    // A project named on the flag or in OP_CLI_PROJECT resolves against
+    // the instance before the profile is handed on, so every consumer
+    // sees a numeric id; numeric overrides keep the no-traffic fast path.
+    const override = firstDefined(parseProjectOverride(overrides.project), parseProjectOverride(env.OP_CLI_PROJECT));
+    const project = typeof override === "string"
+        ? await resolveProjectOverride(instanceUrl, apiKey, override)
+        : (override ?? entry?.project);
     return {
         name: claimsProfile ? name : ENV_PROFILE_NAME,
         instanceUrl,
         apiKey,
-        project: overrides.project ??
-            parseOptionalId(env.OP_CLI_PROJECT) ??
-            entry?.project,
+        project,
     };
 }
 // Resolves the active profile identity without requiring credentials, for

package/dist/context/projectref.js

@@ -0,0 +1,84 @@
+import { apiGet } from "../core/http.js";
+import { OpCliError } from "../core/errors.js";
+import { DEFAULT_PAGE_SIZE, halElements, withPageSize, } from "../core/paginate.js";
+import { isIdForm, rankByCloseness } from "./resolve.js";
+export function hitOf(element) {
+    const candidate = element;
+    return typeof candidate.id === "number"
+        && typeof candidate.identifier === "string"
+        && typeof candidate.name === "string"
+        ? { id: candidate.id, identifier: candidate.identifier, name: candidate.name }
+        : undefined;
+}
+export const PROJECTS_COLLECTION = "/api/v3/projects";
+/**
+ * Every visible project, page by page in server order. Resolution walks
+ * instead of filtering server-side because the exact-match filter set
+ * differs between instance versions; the collection endpoint does not.
+ */
+export async function walkProjects(getPage) {
+    const hits = [];
+    for await (const element of halElements(getPage, withPageSize(PROJECTS_COLLECTION, DEFAULT_PAGE_SIZE))) {
+        const hit = hitOf(element);
+        if (hit !== undefined) {
+            hits.push(hit);
+        }
+    }
+    return hits;
+}
+function missingProjectError(raw, known) {
+    return new OpCliError("NOT_FOUND", `project "${raw}" not found.`, known.length > 0
+        ? `known projects, closest first: ${rankByCloseness(raw, known).slice(0, 6).join(", ")}.`
+        : "check the spelling or list projects with op-cli project list.");
+}
+/**
+ * Resolve one reference that may be an id, an identifier, or a name.
+ * All-digits means an id and is fetched directly. Anything else matches
+ * identifier and name exactly across every visible project; one distinct
+ * match wins, several distinct projects fail loudly instead of guessing.
+ */
+export async function resolveProjectRef(getPage, raw) {
+    if (isIdForm(raw)) {
+        try {
+            const hit = hitOf(await getPage(`${PROJECTS_COLLECTION}/${raw}`));
+            if (hit !== undefined) {
+                return hit;
+            }
+            throw new OpCliError("NOT_FOUND", `project "${raw}" not found.`, "check the id; run op-cli project list to see what is visible.");
+        }
+        catch (error) {
+            if (error instanceof OpCliError && error.code === "USAGE_ERROR") {
+                throw error;
+            }
+            if (error instanceof OpCliError && error.code === "NOT_FOUND") {
+                throw new OpCliError("NOT_FOUND", `project "${raw}" not found.`, "check the id; run op-cli project list to see what is visible.");
+            }
+            throw error;
+        }
+    }
+    const all = await walkProjects(getPage);
+    const matches = all.filter((hit) => hit.identifier === raw || hit.name === raw);
+    const distinct = [...new Map(matches.map((hit) => [hit.id, hit])).values()];
+    if (distinct.length === 1) {
+        return distinct[0];
+    }
+    if (distinct.length > 1) {
+        const listed = distinct.map((hit) => `${String(hit.id)} (${hit.name})`).join(", ");
+        throw new OpCliError("USAGE_ERROR", `project "${raw}" is ambiguous. Candidates: ${listed}.`, "repeat the value as the explicit id of one candidate.");
+    }
+    throw missingProjectError(raw, all.flatMap((hit) => [hit.identifier, hit.name]));
+}
+/**
+ * The project half of a resolved profile: a numeric id passes through
+ * untouched, a name or identifier resolves against the instance (#34).
+ * Callers hand this the parsed `--project` value or OP_CLI_PROJECT, so
+ * the fast path costs no traffic and only a name pays for the walk.
+ */
+export async function resolveProjectOverride(instanceUrl, apiKey, override) {
+    if (typeof override === "number") {
+        return override;
+    }
+    const hit = await resolveProjectRef((path) => apiGet(instanceUrl, apiKey, path), override);
+    return hit.id;
+}
+//# sourceMappingURL=projectref.js.map

package/dist/core/define.js

@@ -99,7 +99,7 @@ export function defineCollectionCommand(spec, runtime) {
         .option("--limit <n>", "maximum number of results to show")
         .option("--all", "fetch every page instead of one limited page")
         .option("--profile <name>", "use this profile for this command only")
-        .option("--project <id>", "override the profile default project");
+        .option("--project <name-or-id>", "override the profile default project");
     command.action(async (reference, options) => {
         runtime.setJsonMode(options.json === true);
         // Flag misuse is refused before any traffic.

package/dist/core/filters.js

@@ -21,17 +21,14 @@ function daysAgo(now, days) {
     return new Date(now.getFullYear(), now.getMonth(), now.getDate() - days);
 }
 /**
- * Turn the raw `--updated-after` input into the local date the window
- * opens at: today, yesterday, N days ago, or an explicit date. The
- * upper bound is deliberately left open (#24): the API reads a closed
- * one as the start of that day, so every change made during the
- * closing day would drop out. Callers emit `<>d [date, ""]`.
+ * The shared grammar of every window date flag: today, yesterday, N
+ * days back, or an explicit date, all in local time. `flag` names the
+ * flag in the error messages.
  */
-export function sinceDate(raw, now) {
+function parseWindowDate(raw, now, flag) {
     const token = raw.trim().toLowerCase();
-    const today = isoDate(now);
     if (token === "today") {
-        return today;
+        return isoDate(now);
     }
     if (token === "yesterday") {
         return isoDate(daysAgo(now, 1));
@@ -45,14 +42,30 @@ export function sinceDate(raw, now) {
     }
     if (/^\d{4}-\d{2}-\d{2}$/.test(token)) {
         if (!isCalendarDate(token)) {
-            throw new OpCliError("USAGE_ERROR", `"${raw}" is not a real date.`, `--updated-after accepts ${DATE_FORMS}.`);
-        }
-        if (token > today) {
-            throw new OpCliError("USAGE_ERROR", `"${raw}" is in the future.`, "--updated-after needs a date up to today.");
+            throw new OpCliError("USAGE_ERROR", `"${raw}" is not a real date.`, `${flag} accepts ${DATE_FORMS}.`);
         }
         return token;
     }
-    throw new OpCliError("USAGE_ERROR", `cannot read "${raw}" as an updated-after value.`, `--updated-after accepts ${DATE_FORMS}.`);
+    throw new OpCliError("USAGE_ERROR", `cannot read "${raw}" as a ${flag.slice(2)} value.`, `${flag} accepts ${DATE_FORMS}.`);
+}
+/**
+ * The date a window opens at. The future check keeps the opening
+ * anchored in the past (#24 grammar).
+ */
+export function sinceDate(raw, now, flag = "--updated-after") {
+    const token = parseWindowDate(raw, now, flag);
+    if (/^\d{4}-\d{2}-\d{2}$/.test(token) && token > isoDate(now)) {
+        throw new OpCliError("USAGE_ERROR", `"${raw}" is in the future.`, `${flag} needs a date up to today.`);
+    }
+    return token;
+}
+/**
+ * The `--to` input of `time list` / `time report`. Same grammar, but a
+ * future end is let through: a period such as `--from 2026-08-01 --to
+ * 2026-08-31` stays valid while only part of it has happened.
+ */
+export function untilDate(raw, now, flag = "--to") {
+    return parseWindowDate(raw, now, flag);
 }
 function unique(values) {
     return [...new Set(values)];
@@ -108,6 +121,23 @@ export function buildWpFilters(flags, now) {
     if ((flags.parents ?? []).length > 0) {
         filters.push({ name: "parent", operator: "=", values: unique(flags.parents) });
     }
+    if (flags.search !== undefined) {
+        if (flags.search.trim() === "") {
+            throw new OpCliError("USAGE_ERROR", "--search needs text to match against subjects.", "pass a substring, e.g. --search login.");
+        }
+        // The only substring clause: `~` is the API's contains operator,
+        // matched server-side so case and diacritics follow the instance.
+        filters.push({ name: "subject", operator: "~", values: [flags.search.trim()] });
+    }
+    if (flags.createdAfter !== undefined) {
+        const since = sinceDate(flags.createdAfter, now, "--created-after");
+        filters.push({
+            name: "created_at",
+            operator: "<>d",
+            // Open upper bound, same reason as updated_at (#24).
+            values: [since, ""],
+        });
+    }
     if (flags.updatedAfter !== undefined) {
         const since = sinceDate(flags.updatedAfter, now);
         filters.push({

package/dist/io/node-io.js

@@ -1,3 +1,5 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
 import { createInterface } from "node:readline/promises";
 import { StringDecoder } from "node:string_decoder";
 import { OpCliError } from "../core/errors.js";
@@ -9,8 +11,9 @@ const ENV_HINT = "set OPENPROJECT_URL and OPENPROJECT_API_KEY in the environment
  * read through a raw-mode byte loop that never forwards keystrokes to
  * the output stream.
  */
-export function createNodeIo(input = process.stdin, output = process.stdout) {
+export function createNodeIo(input = process.stdin, output = process.stdout, errorOutput = process.stderr) {
     const stdinIsTTY = input.isTTY === true;
+    const stderrIsTTY = errorOutput.isTTY === true;
     // Executor form on purpose: Promise.withResolvers needs ES2024, and the
     // published engines field still supports Node 20.
     const askLine = (message) => new Promise((resolve, reject) => {
@@ -76,6 +79,7 @@ export function createNodeIo(input = process.stdin, output = process.stdout) {
     };
     return {
         stdinIsTTY,
+        stderrIsTTY,
         prompt: (message, secret) => (secret ? readSecret(message) : askLine(message)),
         readStdin: async () => {
             const chunks = [];
@@ -84,6 +88,24 @@ export function createNodeIo(input = process.stdin, output = process.stdout) {
             }
             return Buffer.concat(chunks).toString("utf8");
         },
+        // 127 is the shell's "command not found": a spawn that never started
+        // and a child killed by a signal both collapse onto ordinary exit
+        // codes, so callers cannot mistake them for a hanging success.
+        runExternal: (file, args) => new Promise((resolve) => {
+            const child = spawn(file, [...args], { stdio: "inherit" });
+            child.once("error", () => resolve(127));
+            child.once("close", (code) => resolve(code ?? 1));
+        }),
+        captureExternal: (file, args) => new Promise((resolve) => {
+            const child = spawn(file, [...args], { stdio: ["ignore", "pipe", "ignore"] });
+            let captured = "";
+            child.stdout.setEncoding("utf8");
+            child.stdout.on("data", (chunk) => {
+                captured += chunk;
+            });
+            child.once("error", () => resolve(undefined));
+            child.once("close", (code) => resolve(code === 0 ? captured : undefined));
+        }),
     };
 }
 //# sourceMappingURL=node-io.js.map