@tuanhv/op-cli 0.1.0

package/dist/context/metadata.js

@@ -0,0 +1,528 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { halRefId } from "../core/hal.js";
+import { apiGet, apiPost } from "../core/http.js";
+import { halElements } from "../core/paginate.js";
+import { OpCliError } from "../core/errors.js";
+import { ENV_PROFILE_NAME } from "./profile.js";
+function cacheRoot(env) {
+    const root = env.OP_CLI_CACHE_DIR ??
+        (env.HOME !== undefined ? join(env.HOME, ".cache", "op-cli") : undefined);
+    if (root === undefined) {
+        throw new OpCliError("INTERNAL_ERROR");
+    }
+    return root;
+}
+export function metadataPath(env, profile) {
+    const key = profile.name === ENV_PROFILE_NAME
+        ? `env-${createHash("sha1").update(profile.instanceUrl).digest("hex")}`
+        : profile.name;
+    return join(cacheRoot(env), key, "metadata.json");
+}
+export async function readStoredMetadata(env, profile) {
+    try {
+        return JSON.parse(await readFile(metadataPath(env, profile), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function persistMetadata(env, profile, metadata) {
+    const path = metadataPath(env, profile);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(metadata, null, 2)}\n`);
+}
+function asString(value) {
+    return typeof value === "string" ? value : "";
+}
+function asBoolean(value) {
+    return value === true;
+}
+function sortByName(entries) {
+    return [...entries].sort((a, b) => a.name.localeCompare(b.name));
+}
+function toStoredType(element) {
+    return {
+        id: Number(element.id),
+        name: asString(element.name),
+        is_milestone: asBoolean(element.isMilestone),
+    };
+}
+function toStoredStatus(element) {
+    return {
+        id: Number(element.id),
+        name: asString(element.name),
+        is_closed: asBoolean(element.isClosed),
+        is_default: asBoolean(element.isDefault),
+    };
+}
+function toStoredPriority(element) {
+    return {
+        id: Number(element.id),
+        name: asString(element.name),
+        is_default: asBoolean(element.isDefault),
+    };
+}
+function hrefId(value) {
+    const href = asString(value?.href);
+    const match = /(\d+)\/?$/.exec(href);
+    return match === null ? 0 : Number(match[1]);
+}
+function principalKind(element) {
+    switch (asString(element._type)) {
+        case "Group":
+            return "Group";
+        case "PlaceholderUser":
+        case "Placeholder":
+            return "Placeholder";
+        default:
+            return "User";
+    }
+}
+function toStoredMember(element) {
+    const links = (element._links ?? {});
+    const embedded = (element._embedded ?? {});
+    const principal = (embedded.principal ?? {});
+    const principalLink = (links.principal ?? {});
+    const roles = Array.isArray(links.roles) ? links.roles : [];
+    return {
+        membership_id: Number(element.id),
+        user_id: typeof principal.id === "number"
+            ? principal.id
+            : hrefId(principalLink),
+        name: asString(principal.name) || asString(principalLink.title),
+        type: principalKind(principal),
+        roles: roles.map((role) => ({
+            id: hrefId(role),
+            title: asString(role.title),
+        })),
+    };
+}
+function toStoredVersion(element) {
+    return {
+        id: Number(element.id),
+        name: asString(element.name),
+        status: asString(element.status),
+    };
+}
+function toStoredCategory(element) {
+    return {
+        id: Number(element.id),
+        name: asString(element.name),
+    };
+}
+// Above this size an allowed-values list is noise in the store, not a
+// usable dropdown; the field keeps working, just without the list.
+const MAX_ALLOWED_VALUES = 50;
+/**
+ * The selectable values of one schema property, in either shape an
+ * instance uses: full resources under `_embedded.allowedValues`, which is
+ * what the create form returns, or bare links under `_links.allowedValues`,
+ * which is all the schema endpoint ever carries. Anything without a
+ * readable id is dropped rather than resolved to a fabricated one.
+ */
+function allowedOptionsOf(property) {
+    const embedded = (property._embedded ?? {});
+    const resources = Array.isArray(embedded.allowedValues)
+        ? embedded.allowedValues
+        : [];
+    if (resources.length > 0) {
+        return resources.flatMap((value) => {
+            const option = value;
+            const id = Number(option.id);
+            if (!Number.isFinite(id)) {
+                return [];
+            }
+            return [{
+                    id,
+                    // A CustomOption spells its text "value"; every other resource
+                    // spells it "name".
+                    name: asString(option.value ?? option.name),
+                }];
+        });
+    }
+    const links = (property._links ?? {});
+    const values = Array.isArray(links.allowedValues)
+        ? links.allowedValues
+        : [];
+    return values.flatMap((value) => {
+        const link = value;
+        const id = halRefId(typeof link.href === "string" ? link.href : null);
+        return id === null ? [] : [{ id, name: asString(link.title) }];
+    });
+}
+/**
+ * The allowed values of one custom field as humans read them: the names of
+ * a list field's options, or the values the schema listed for any other
+ * kind. A vocabulary longer than MAX_ALLOWED_VALUES teaches nothing in a
+ * table cell, so it renders as nothing.
+ */
+export function customFieldAllowedNames(field) {
+    const names = field.allowed_options === undefined
+        ? field.allowed_values ?? []
+        : field.allowed_options.map((option) => option.name);
+    return names.length > MAX_ALLOWED_VALUES ? [] : names;
+}
+function customFieldEntries(schema) {
+    const fields = [];
+    for (const [key, property] of Object.entries(schema)) {
+        if (!/^customField\d+$/.test(key)) {
+            continue;
+        }
+        // The schema `type` decides input validation downstream; anything
+        // beyond Boolean/User/CustomOption stays unmarked and passes through
+        // as text. A multi-valued field spells its kind "[]Kind".
+        const kind = asString(property.type).toLowerCase();
+        const single = kind.replace(/^\[\]/, "");
+        const isUser = kind === "user";
+        // A user field's allowed values are the project's members, which
+        // meta members already lists; keeping them here would only bloat the
+        // store.
+        const options = isUser ? [] : allowedOptionsOf(property);
+        const isList = single === "customoption";
+        fields.push({
+            key,
+            id: Number(key.slice("customField".length)),
+            name: asString(property.name),
+            ...(property.required === true
+                ? { is_required: true }
+                : {}),
+            ...(!isList && options.length > 0 && options.length <= MAX_ALLOWED_VALUES
+                ? { allowed_values: options.map((option) => option.name) }
+                : {}),
+            ...(kind === "boolean" ? { is_boolean: true } : {}),
+            ...(isUser ? { is_user: true } : {}),
+            ...(isList ? { is_list: true, allowed_options: options } : {}),
+            ...(kind.startsWith("[]") ? { is_multi: true } : {}),
+        });
+    }
+    return fields;
+}
+async function fetchMembers(profile, projectId) {
+    const filters = encodeURIComponent(JSON.stringify([{ project: { operator: "=", values: [String(projectId)] } }]));
+    const members = await fetchVocabulary(profile, `/api/v3/memberships?filters=${filters}`, toStoredMember);
+    return sortByName(members);
+}
+async function fetchVersions(profile, projectId) {
+    const versions = await fetchVocabulary(profile, `/api/v3/projects/${String(projectId)}/versions`, toStoredVersion);
+    return sortByName(versions);
+}
+async function fetchCategories(profile, projectId) {
+    const categories = await fetchVocabulary(profile, `/api/v3/projects/${String(projectId)}/categories`, toStoredCategory);
+    return sortByName(categories);
+}
+// The bare schema endpoint builds its values from TimeEntry.new, so its
+// activity list is never populated. Only the create form (form_embedded)
+// fills the activities that are active in the referenced project; its
+// payload carries linked resources under _links, and the embedded schema
+// lists full activity representations under activity/_embedded/allowedValues.
+async function fetchActivities(profile, projectId) {
+    const form = (await apiPost(profile.instanceUrl, profile.apiKey, "/api/v3/time_entries/form", { _links: { project: { href: `/api/v3/projects/${String(projectId)}` } } }));
+    const formEmbedded = (form._embedded ?? {});
+    const schema = (formEmbedded.schema ?? {});
+    const activity = (schema.activity ?? {});
+    const activityEmbedded = (activity._embedded ?? {});
+    const values = Array.isArray(activityEmbedded.allowedValues)
+        ? activityEmbedded.allowedValues
+        : [];
+    const activities = values.map((option) => ({
+        id: Number(option.id),
+        name: asString(option.name),
+        is_default: option.default === true,
+    }));
+    return sortByName(activities);
+}
+/**
+ * The schema of one project-and-type pair, from the richest source that
+ * answers. The bare schema endpoint names every custom field but leaves a
+ * list field's allowed values empty; only the create form fills them, so
+ * the form is asked first. A caller who may not open a create form still
+ * gets every field, just without the options.
+ */
+async function fetchTypeSchema(profile, projectId, typeId) {
+    try {
+        const form = (await apiPost(profile.instanceUrl, profile.apiKey, `/api/v3/projects/${String(projectId)}/work_packages/form`, { _links: { type: { href: `/api/v3/types/${String(typeId)}` } } }));
+        const embedded = (form._embedded ?? {});
+        const schema = embedded.schema;
+        if (typeof schema === "object" && schema !== null && !Array.isArray(schema)) {
+            return schema;
+        }
+    }
+    catch {
+        // The form is an enrichment, never the only source.
+    }
+    return (await apiGet(profile.instanceUrl, profile.apiKey, `/api/v3/work_packages/schemas/${String(projectId)}-${String(typeId)}`));
+}
+async function fetchCustomFields(profile, projectId) {
+    const typeIds = await fetchVocabulary(profile, `/api/v3/projects/${String(projectId)}/types`, (element) => Number(element.id));
+    const byType = {};
+    for (const typeId of typeIds) {
+        const schema = await fetchTypeSchema(profile, projectId, typeId);
+        byType[String(typeId)] = sortByName(customFieldEntries(schema));
+    }
+    return byType;
+}
+async function fetchVocabulary(profile, path, convert) {
+    const elements = [];
+    for await (const element of halElements((page) => apiGet(profile.instanceUrl, profile.apiKey, page), path)) {
+        elements.push(convert(element));
+    }
+    return elements;
+}
+async function fetchInstanceInfo(profile) {
+    let apiVersion = null;
+    let coreVersion = null;
+    try {
+        const root = (await apiGet(profile.instanceUrl, profile.apiKey, "/api/v3/"));
+        apiVersion = typeof root.apiVersion === "string" ? root.apiVersion : null;
+        coreVersion = typeof root.coreVersion === "string" ? root.coreVersion : null;
+    }
+    catch {
+        // The root probe only enriches the store; stock instances may omit it.
+    }
+    return {
+        url: profile.instanceUrl,
+        api_version: apiVersion,
+        core_version: coreVersion,
+        fetched_at: new Date().toISOString(),
+    };
+}
+async function fetchProjectRef(profile, projectId) {
+    const project = (await apiGet(profile.instanceUrl, profile.apiKey, `/api/v3/projects/${String(projectId)}`));
+    return {
+        id: Number(project.id),
+        identifier: asString(project.identifier),
+        name: asString(project.name),
+    };
+}
+export async function fetchStoredMetadata(profile) {
+    const types = sortByName(await fetchVocabulary(profile, "/api/v3/types", toStoredType));
+    const statuses = sortByName(await fetchVocabulary(profile, "/api/v3/statuses", toStoredStatus));
+    const priorities = sortByName(await fetchVocabulary(profile, "/api/v3/priorities", toStoredPriority));
+    const instance = await fetchInstanceInfo(profile);
+    const project = profile.project === undefined
+        ? undefined
+        : await fetchProjectRef(profile, profile.project);
+    return {
+        types,
+        statuses,
+        priorities,
+        instance,
+        ...(project === undefined ? {} : { project }),
+    };
+}
+export async function loadStoredMetadata(env, profile) {
+    const stored = await readStoredMetadata(env, profile);
+    if (stored !== undefined) {
+        return stored;
+    }
+    const fetched = await fetchStoredMetadata(profile);
+    await persistMetadata(env, profile, fetched);
+    return fetched;
+}
+export async function refreshStoredMetadata(env, profile) {
+    const previous = await readStoredMetadata(env, profile);
+    const next = await fetchStoredMetadata(profile);
+    const previousScoped = previous?.projectScoped ?? {};
+    const projectScoped = {};
+    const dropped = [];
+    for (const projectId of Object.keys(previousScoped)) {
+        try {
+            projectScoped[projectId] = await fetchProjectVocabulary(profile, Number(projectId));
+        }
+        catch (error) {
+            // A project deleted on the instance must not wedge the refresh for
+            // good: drop its stored vocabulary, report it, and keep refreshing
+            // everything else. Any other failure is still the caller's to see.
+            if (!(error instanceof OpCliError && error.code === "NOT_FOUND")) {
+                throw error;
+            }
+            dropped.push({
+                section: "project",
+                kind: "removed",
+                id: Number(projectId),
+                detail: `removed cached vocabulary of project ${projectId}`,
+            });
+        }
+    }
+    await persistMetadata(env, profile, {
+        ...next,
+        ...(Object.keys(projectScoped).length > 0 ? { projectScoped } : {}),
+    });
+    const changes = [
+        ...diffEntries("types", previous?.types, next.types),
+        ...diffEntries("statuses", previous?.statuses, next.statuses),
+        ...diffEntries("priorities", previous?.priorities, next.priorities),
+        ...diffProject(previous?.project, next.project),
+        ...dropped,
+        ...diffInstance(previous?.instance, next.instance),
+    ];
+    for (const projectId of Object.keys(projectScoped)) {
+        changes.push(...diffVocabulary(previousScoped[projectId], projectScoped[projectId]));
+    }
+    return changes;
+}
+export async function fetchProjectVocabulary(profile, projectId) {
+    return {
+        project_id: projectId,
+        fetched_at: new Date().toISOString(),
+        members: await fetchMembers(profile, projectId),
+        versions: await fetchVersions(profile, projectId),
+        categories: await fetchCategories(profile, projectId),
+        activities: await fetchActivities(profile, projectId),
+        custom_fields: await fetchCustomFields(profile, projectId),
+    };
+}
+export async function loadProjectVocabulary(env, profile) {
+    if (profile.project === undefined) {
+        throw new OpCliError("USAGE_ERROR");
+    }
+    return loadProjectVocabularyById(env, profile, profile.project);
+}
+/**
+ * The same cache-and-fetch flow for an explicit project id, used when the
+ * project is not the profile default but a resource's own (a time entry
+ * resolves its activity against the project of its work package).
+ */
+export async function loadProjectVocabularyById(env, profile, projectId) {
+    const stored = await readStoredMetadata(env, profile);
+    const cached = stored?.projectScoped?.[String(projectId)];
+    if (cached !== undefined) {
+        return cached;
+    }
+    const base = stored ?? (await fetchStoredMetadata(profile));
+    const vocabulary = await fetchProjectVocabulary(profile, projectId);
+    await persistMetadata(env, profile, {
+        ...base,
+        projectScoped: {
+            ...base.projectScoped,
+            [String(projectId)]: vocabulary,
+        },
+    });
+    return vocabulary;
+}
+export async function clearStoredMetadata(env, profile) {
+    await rm(metadataPath(env, profile), { force: true });
+}
+function formatValue(value) {
+    if (value === null) {
+        return "null";
+    }
+    return String(value);
+}
+function fieldDiffs(before, after) {
+    const beforeRecord = before;
+    const afterRecord = after;
+    const keys = new Set([
+        ...Object.keys(beforeRecord),
+        ...Object.keys(afterRecord),
+    ]);
+    // Arrays (roles, allowed values) arrive as fresh objects on every fetch;
+    // compare them by value or every refresh would flag them as changed.
+    const sameValue = (before, after) => Array.isArray(before) || Array.isArray(after)
+        ? JSON.stringify(before) === JSON.stringify(after)
+        : Object.is(before, after);
+    const diffs = [];
+    for (const key of keys) {
+        if (!sameValue(beforeRecord[key], afterRecord[key])) {
+            diffs.push(`${key}: ${formatValue(beforeRecord[key])} -> ${formatValue(afterRecord[key])}`);
+        }
+    }
+    return diffs.sort();
+}
+function diffEntries(section, before, after) {
+    const changes = [];
+    const beforeById = new Map((before ?? []).map((entry) => [entry.id, entry]));
+    const afterIds = new Set(after.map((entry) => entry.id));
+    for (const entry of after) {
+        const previous = beforeById.get(entry.id);
+        if (previous === undefined) {
+            changes.push({
+                section,
+                kind: "added",
+                id: entry.id,
+                detail: `added ${entry.name} (${String(entry.id)})`,
+            });
+            continue;
+        }
+        const diffs = fieldDiffs(previous, entry);
+        if (diffs.length > 0) {
+            changes.push({
+                section,
+                kind: "changed",
+                id: entry.id,
+                detail: `${diffs.join("; ")} (${String(entry.id)})`,
+            });
+        }
+    }
+    for (const entry of before ?? []) {
+        if (!afterIds.has(entry.id)) {
+            changes.push({
+                section,
+                kind: "removed",
+                id: entry.id,
+                detail: `removed ${entry.name} (${String(entry.id)})`,
+            });
+        }
+    }
+    return changes;
+}
+function diffProject(before, after) {
+    if (before === undefined && after !== undefined) {
+        return [{
+                section: "project",
+                kind: "added",
+                id: after.id,
+                detail: `added ${after.name} (${String(after.id)})`,
+            }];
+    }
+    if (before !== undefined && after === undefined) {
+        return [{
+                section: "project",
+                kind: "removed",
+                id: before.id,
+                detail: `removed ${before.name} (${String(before.id)})`,
+            }];
+    }
+    if (before === undefined || after === undefined) {
+        return [];
+    }
+    const diffs = fieldDiffs(before, after);
+    return diffs.length === 0
+        ? []
+        : [{ section: "project", kind: "changed", id: after.id, detail: diffs.join("; ") }];
+}
+function diffInstance(before, after) {
+    if (before === undefined) {
+        return [];
+    }
+    const comparable = (info) => ({
+        api_version: info.api_version,
+        core_version: info.core_version,
+    });
+    const diffs = fieldDiffs(comparable(before), comparable(after));
+    return diffs.length === 0
+        ? []
+        : [{ section: "instance", kind: "changed", id: null, detail: diffs.join("; ") }];
+}
+function diffVocabulary(before, after) {
+    if (after === undefined) {
+        return [];
+    }
+    // diffEntries keys on id; members identify by their membership id.
+    const memberEntry = (member) => ({
+        id: member.membership_id,
+        name: member.name,
+        roles: member.roles,
+    });
+    const fields = (vocabulary) => Object.values(vocabulary?.custom_fields ?? {}).flat();
+    return [
+        ...diffEntries("members", before?.members.map(memberEntry), after.members.map(memberEntry)),
+        ...diffEntries("versions", before?.versions, after.versions),
+        ...diffEntries("categories", before?.categories, after.categories),
+        ...diffEntries("activities", before?.activities, after.activities),
+        ...diffEntries("fields", fields(before), fields(after)),
+    ];
+}
+//# sourceMappingURL=metadata.js.map