@tuanhv/op-cli 0.1.1 → 0.2.1

package/dist/commands/time.js

@@ -1,12 +1,12 @@
 import { PAGED_JSON_HELP } from "../core/define.js";
 import { isoToHours, parseDuration } from "../core/duration.js";
 import { OpCliError, writeRefusal } from "../core/errors.js";
-import { filtersQuery, isoDate, sinceDate } from "../core/filters.js";
+import { filtersQuery, isoDate, sinceDate, untilDate, } from "../core/filters.js";
 import { flattenHalRecord, formattableRaw, isFlatLink, toFormattable, } from "../core/hal.js";
 import { apiDelete, apiGet, apiPatchRaw, apiPostRaw, authenticate, } from "../core/http.js";
 import { allPageSize, halElements, parsePageSize, withPageSize } from "../core/paginate.js";
 import { isIdForm, rankByCloseness, resolveName, } from "../context/resolve.js";
-import { parseOptionalId, } from "../context/profile.js";
+import { parseProjectOverride, } from "../context/profile.js";
 import { loadProjectVocabulary, loadProjectVocabularyById, refreshStoredMetadata, } from "../context/metadata.js";
 import { formatCell, renderTable } from "../output/table.js";
 // One flat row per time entry; the work package sits on every row so a
@@ -113,8 +113,13 @@ function splitList(raws) {
  * `project` leads when a project is in context: there is no
  * project-scoped time-entry collection to address instead, so the clause
  * is the only way `--project` reaches the query at all (#19).
+ *
+ * `from`/`to` bound `spent_on`, a pure date column: the API's `<>d`
+ * includes BOTH bound dates (verified against a live instance on
+ * 2026-08-24; the #24 half-open rule is a timestamp-column behaviour,
+ * not this one). An open end is spelled "".
  */
-function buildTimeFilters(project, wps, users, from, now) {
+function buildTimeFilters(project, wps, users, from, to, now) {
     const filters = [];
     if (project !== undefined) {
         filters.push({ name: "project", operator: "=", values: [String(project)] });
@@ -126,16 +131,34 @@ function buildTimeFilters(project, wps, users, from, now) {
     if (users.length > 0) {
         filters.push({ name: "user_id", operator: "=", values: [...users] });
     }
-    if (from !== undefined) {
-        // Same date grammar as --updated-after on `wp list`, applied to
-        // spent_on instead, open upper bound included (#24).
-        const since = sinceDate(from, now);
+    if (from !== undefined && to !== undefined) {
+        const since = sinceDate(from, now, "--from");
+        const until = untilDate(to, now);
+        if (until < since) {
+            throw new OpCliError("USAGE_ERROR", `--to ${until} is before --from ${since}.`, "pass the end of the period after its start.");
+        }
+        filters.push({
+            name: "spent_on",
+            operator: "<>d",
+            values: [since, until],
+        });
+    }
+    else if (from !== undefined) {
+        const since = sinceDate(from, now, "--from");
         filters.push({
             name: "spent_on",
             operator: "<>d",
+            // The empty upper bound keeps the window open-ended.
             values: [since, ""],
         });
     }
+    else if (to !== undefined) {
+        filters.push({
+            name: "spent_on",
+            operator: "<>d",
+            values: ["", untilDate(to, now)],
+        });
+    }
     return filters;
 }
 function membersSource(env, profile) {
@@ -143,7 +166,7 @@ function membersSource(env, profile) {
         label: "user",
         load: async () => {
             if (profile.project === undefined) {
-                throw new OpCliError("USAGE_ERROR", "--user needs a project to look member names up in.", "pass --project <id> or set a default project on the profile.");
+                throw new OpCliError("USAGE_ERROR", "--user needs a project to look member names up in.", "pass --project <name-or-id> or set a default project on the profile.");
             }
             const select = (vocabulary) => vocabulary.members.map((member) => ({
                 name: member.name,
@@ -286,12 +309,12 @@ export function registerTimeCommands(time, runtime) {
         .argument("<id>", "work package id")
         .requiredOption("--hours <value>", "decimal hours such as 1.5, a compound form such as 1h30m, "
         + "or an ISO 8601 duration such as PT1H30M")
-        .option("--activity <name-or-id>", "activity of the project, by name or id")
+        .requiredOption("--activity <name-or-id>", "activity of the project, by name or id")
         .option("--spent-on <date>", "calendar date the hours were spent, YYYY-MM-DD; defaults to today")
         .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);
         requireId(reference, "work package");
@@ -303,7 +326,7 @@ export function registerTimeCommands(time, runtime) {
             : requireIsoDate(options.spentOn);
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         // The activity vocabulary hangs off the project the work package
         // belongs to, not off the profile default.
@@ -312,15 +335,13 @@ export function registerTimeCommands(time, runtime) {
         if (projectId === null) {
             throw new OpCliError("API_ERROR", `work package ${reference} carries no project link.`, "check the work package on the instance.");
         }
-        const activityHref = options.activity === undefined
-            ? undefined
-            : await resolveActivityHref(runtime, profile, projectId, options.activity);
+        const activityHref = await resolveActivityHref(runtime, profile, projectId, options.activity);
         const response = await postEntry(profile, {
             hours: duration.iso,
             spentOn,
             _links: {
                 workPackage: { href: `/api/v3/work_packages/${reference}` },
-                ...(activityHref === undefined ? {} : { activity: { href: activityHref } }),
+                activity: { href: activityHref },
             },
         });
         if (response.status < 200
@@ -336,11 +357,12 @@ export function registerTimeCommands(time, runtime) {
         .option("--wp <id>", "work package id; repeat or comma-separate to OR values", collectValue, [])
         .option("--user <name>", "user name, id, or me; repeat to OR values", collectValue, [])
         .option("--from <date>", "today, yesterday, days back such as 7d, or YYYY-MM-DD")
+        .option("--to <date>", "close the period on this day, inclusive; same date forms")
         .option("--json", PAGED_JSON_HELP)
         .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")
         .action(async (options) => {
         runtime.setJsonMode(options.json === true);
         // Refuse impossible input before any traffic or resolution.
@@ -350,10 +372,10 @@ export function registerTimeCommands(time, runtime) {
         }
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         const users = await resolveUserValues(runtime.env, profile, splitList(options.user ?? []));
-        const filters = buildTimeFilters(profile.project, wps, users, options.from, new Date());
+        const filters = buildTimeFilters(profile.project, wps, users, options.from, options.to, new Date());
         const limit = parsePageSize(options.limit);
         const getPage = (path) => apiGet(profile.instanceUrl, profile.apiKey, path);
         // --all sizes pages by the instance's advertised maximum; --limit
@@ -394,13 +416,13 @@ export function registerTimeCommands(time, 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);
         requireId(reference, "time entry");
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         const record = timeEntryRecord(await apiGet(profile.instanceUrl, profile.apiKey, `/api/v3/time_entries/${reference}`));
         renderRecord(runtime, options, record);
@@ -416,7 +438,7 @@ export function registerTimeCommands(time, 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);
         requireId(reference, "time entry");
@@ -436,7 +458,7 @@ export function registerTimeCommands(time, runtime) {
         }
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         const payload = {};
         if (hours !== undefined) {
@@ -475,7 +497,7 @@ export function registerTimeCommands(time, runtime) {
         .argument("<id>", "time entry 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.
@@ -485,7 +507,7 @@ export function registerTimeCommands(time, runtime) {
         requireId(reference, "time entry");
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         await deleteEntry(profile, reference);
         runtime.write(`Deleted time entry ${reference}.\n`);
@@ -495,9 +517,10 @@ export function registerTimeCommands(time, runtime) {
         .option("--wp <id>", "work package id; repeat or comma-separate to OR values", collectValue, [])
         .option("--user <name>", "user name, id, or me; repeat to OR values", collectValue, [])
         .option("--from <date>", "today, yesterday, days back such as 7d, or YYYY-MM-DD")
+        .option("--to <date>", "close the period on this day, inclusive; same date forms")
         .option("--json", "emit a flat JSON array of per-work-package groups")
         .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 (options) => {
         runtime.setJsonMode(options.json === true);
         // Refuse impossible input before any traffic or resolution.
@@ -507,10 +530,10 @@ export function registerTimeCommands(time, runtime) {
         }
         const profile = await runtime.resolve({
             profile: options.profile,
-            project: parseOptionalId(options.project),
+            project: parseProjectOverride(options.project),
         });
         const users = await resolveUserValues(runtime.env, profile, splitList(options.user ?? []));
-        const filters = buildTimeFilters(profile.project, wps, users, options.from, new Date());
+        const filters = buildTimeFilters(profile.project, wps, users, options.from, options.to, new Date());
         // A total is only honest over the whole filtered set, so report
         // always walks every page; there is no --limit to half-count by.
         const startPath = withPageSize(`/api/v3/time_entries?filters=${filtersQuery(filters)}`, parsePageSize(undefined));

package/dist/commands/update.js

@@ -0,0 +1,199 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { configDirectory } from "../context/profile.js";
+import { OpCliError } from "../core/errors.js";
+import { cliVersion } from "./version.js";
+const PACKAGE_SPEC = "@tuanhv/op-cli@latest";
+// Scoped package names must escape the slash for a registry path segment.
+const REGISTRY_URL = "https://registry.npmjs.org/@tuanhv%2Fop-cli/latest";
+// The bare name `npm ls -g` answers ownership with: exit 0 exactly when
+// npm's global tree holds the package.
+const PACKAGE_NAME = "@tuanhv/op-cli";
+// The notice is a convenience, never a delay: its lookup gets a budget far
+// below the API's own, and every failure path stays silent.
+const NOTICE_TIMEOUT_MS = 1_500;
+const NOTICE_TTL_MS = 24 * 60 * 60 * 1000;
+function isHomebrewPath(path) {
+    // `npm prefix -g` reports the bare prefix ("/opt/homebrew"), while a
+    // resolved binary lands deeper ("/opt/homebrew/bin/op-cli"); the
+    // substring catches both without claiming plain /usr/local, which a
+    // stock Node install shares with Intel Homebrew.
+    return path.includes("/opt/homebrew")
+        || path.includes("/Cellar/")
+        || path.includes("/usr/local/Homebrew");
+}
+// An install another manager owns would be overwritten by npm today and
+// reverted by that manager's next upgrade, so the exact command is
+// printed for the human to run instead. Ownership is asked of npm
+// itself: `npm ls -g` exits 0 exactly when npm's global tree holds the
+// package, so a Homebrew-built Node with an npm -g install stays npm's.
+// A Homebrew *prefix* only names Node's installer; treating it as the
+// package's manager misroutes every npm -g install on such a Node.
+// Homebrew is claimed only when npm does not own the package and the
+// binary or prefix lands inside a Homebrew tree.
+async function detectManagingInstall(runtime) {
+    const capture = runtime.captureExternal;
+    if (capture === undefined) {
+        return undefined;
+    }
+    const prefix = (await capture("npm", ["prefix", "-g"]))?.trim() ?? "";
+    if (prefix.includes("volta")) {
+        return { label: "Volta", command: `volta install ${PACKAGE_SPEC}` };
+    }
+    const bin = (await capture("which", ["op-cli"]))?.trim() ?? "";
+    if (bin.includes("volta")) {
+        return { label: "Volta", command: `volta install ${PACKAGE_SPEC}` };
+    }
+    // The exit code is the answer; the listing text itself is not read.
+    const ownedByNpm = await capture("npm", ["ls", "-g", PACKAGE_NAME]);
+    if (ownedByNpm !== undefined) {
+        return undefined;
+    }
+    if (isHomebrewPath(bin) || isHomebrewPath(prefix)) {
+        return { label: "Homebrew", command: "brew upgrade op-cli" };
+    }
+    return undefined;
+}
+export function registerUpdateCommand(parent, runtime) {
+    parent.action(async () => {
+        const managed = await detectManagingInstall(runtime);
+        if (managed !== undefined) {
+            runtime.write(`${managed.label} manages this install. Run instead:\n  ${managed.command}\n`);
+            return;
+        }
+        if (runtime.runExternal === undefined) {
+            throw new OpCliError("INTERNAL_ERROR");
+        }
+        const code = await runtime.runExternal("npm", ["install", "-g", PACKAGE_SPEC]);
+        if (code !== 0) {
+            runtime.writeErr(`The installer exited with code ${code}.\n`);
+            runtime.setExitCode(code);
+        }
+    });
+}
+function noticeCachePath(env) {
+    const directory = configDirectory(env);
+    return directory === undefined ? undefined : join(directory, "update-check.json");
+}
+async function readNoticeCache(env) {
+    const path = noticeCachePath(env);
+    if (path === undefined) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        return typeof parsed.checkedAt === "number" && typeof parsed.latest === "string"
+            ? { checkedAt: parsed.checkedAt, latest: parsed.latest }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeNoticeCache(env, cache) {
+    const path = noticeCachePath(env);
+    if (path === undefined) {
+        return;
+    }
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, `${JSON.stringify(cache, null, 2)}\n`);
+    }
+    catch {
+        // A read-only config directory must never fail the command over a hint.
+    }
+}
+async function fetchLatestRelease() {
+    try {
+        const response = await fetch(REGISTRY_URL, {
+            headers: { accept: "application/json" },
+            signal: AbortSignal.timeout(NOTICE_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            return undefined;
+        }
+        const body = await response.json();
+        return typeof body.version === "string" ? body.version : undefined;
+    }
+    catch {
+        // Unreachable registry means no notice, not an error.
+        return undefined;
+    }
+}
+function releaseSegments(version) {
+    const core = version.split("+")[0]?.split("-")[0];
+    const parts = core?.split(".") ?? [];
+    const segments = [];
+    for (const part of parts) {
+        if (!/^\d+$/.test(part)) {
+            return undefined;
+        }
+        segments.push(Number(part));
+    }
+    return segments.length > 0 ? segments : undefined;
+}
+// Only a numerically newer release is news; anything else (older, equal,
+// or unparsable) stays quiet so the notice never cries wolf.
+function isNewerRelease(latest, running) {
+    const candidate = releaseSegments(latest);
+    const current = releaseSegments(running);
+    if (candidate === undefined || current === undefined) {
+        return false;
+    }
+    const depth = Math.max(candidate.length, current.length);
+    for (let index = 0; index < depth; index += 1) {
+        const left = candidate[index] ?? 0;
+        const right = current[index] ?? 0;
+        if (left !== right) {
+            return left > right;
+        }
+    }
+    return false;
+}
+async function resolveNoticeLine(env) {
+    const running = await cliVersion();
+    if (running === "unknown") {
+        return undefined;
+    }
+    const now = Date.now();
+    let latest;
+    const cached = await readNoticeCache(env);
+    if (cached !== undefined && now - cached.checkedAt < NOTICE_TTL_MS) {
+        latest = cached.latest;
+    }
+    else {
+        latest = await fetchLatestRelease();
+        if (latest !== undefined) {
+            // Only a successful lookup refreshes the stamp: an unreachable
+            // registry retries on the next command instead of waiting a day.
+            await writeNoticeCache(env, { checkedAt: now, latest });
+        }
+    }
+    if (latest === undefined || !isNewerRelease(latest, running)) {
+        return undefined;
+    }
+    return `op-cli ${latest} available (running ${running}); run op-cli update\n`;
+}
+// Commands whose own story already answers "which version": the notice
+// would only repeat them, and --version must stay offline by contract.
+const NOTICE_EXEMPT = ["update", "--version", "--help", "-h"];
+/**
+ * Starts the new-version notice and resolves with its single stderr line,
+ * or undefined when now is not the time for one. Gating is the contract
+ * from issue #38: scripted use (stderr not a TTY) never pays for a lookup,
+ * OP_CLI_NO_UPDATE_CHECK=1 opts out entirely, and every failure inside
+ * stays silent. The promise never rejects.
+ */
+export function startVersionNotice(argv, env, io) {
+    if (env.OP_CLI_NO_UPDATE_CHECK === "1") {
+        return Promise.resolve(undefined);
+    }
+    if (io.stderrIsTTY !== true) {
+        return Promise.resolve(undefined);
+    }
+    if (NOTICE_EXEMPT.includes(argv[0] ?? "")) {
+        return Promise.resolve(undefined);
+    }
+    return resolveNoticeLine(env);
+}
+//# sourceMappingURL=update.js.map

package/dist/commands/version.js

@@ -2,7 +2,7 @@ import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { readStoredMetadata } from "../context/metadata.js";
 import { peekActiveProfile } from "../context/profile.js";
-async function cliVersion() {
+export async function cliVersion() {
     try {
         const raw = await readFile(fileURLToPath(new URL("../../package.json", import.meta.url)), "utf8");
         const pkg = JSON.parse(raw);