@tuanhv/op-cli 0.1.0

package/NOTICE

@@ -0,0 +1,15 @@
+NOTICE
+======
+
+op-cli is an independent, community-developed command-line tool. It is not
+affiliated with, endorsed by, sponsored by, or connected to OpenProject GmbH
+in any way.
+
+"OpenProject" is a trademark of OpenProject GmbH. This project makes no use
+of OpenProject branding, logos, or other trademarks. References to
+OpenProject in the documentation and command output describe
+interoperability with the OpenProject REST API only; they are nominative
+references to that product, not claims of association.
+
+op-cli is released under the MIT license; see the "license" field of
+package.json.

package/README.md

@@ -0,0 +1,108 @@
+# op-cli
+
+> **Not affiliated with OpenProject GmbH.** op-cli is an independent,
+> community-developed command-line tool. It is not affiliated with, endorsed
+> by, or connected to OpenProject GmbH in any way, and it makes no use of
+> OpenProject branding or logos. "OpenProject" is a trademark of OpenProject
+> GmbH; this tool only speaks the REST API of the OpenProject application you
+> already run. See the NOTICE file for the full statement.
+>
+> **Early release.** This is version 0.1.0 of a young tool. The command
+> surface may still change between releases; pin your version if that
+> matters to you.
+
+A resolving CLI for OpenProject: every flag accepts a human name or an id,
+and the tool turns names into ids itself. Errors carry stable `[CODE]`
+markers so both humans and agents can react to them programmatically.
+
+## Requirements
+
+- Node.js 20 or newer.
+- An OpenProject instance running v13 or later (API v3).
+
+## From install to first useful command
+
+```sh
+npm install -g @tuanhv/op-cli
+op-cli auth login        # prompts for URL and API key; needs an interactive terminal
+op-cli wp list --open    # list open work packages of your instance
+```
+
+Prefer environment variables over a stored profile? Export
+`OPENPROJECT_URL` and `OPENPROJECT_API_KEY` instead of running
+`op-cli auth login`; every command picks them up automatically.
+
+Run any command with `--help` for its full reference. Useful starting
+points beyond the quickstart:
+
+```sh
+op-cli wp create "Fix login bug" --type Bug --priority High
+op-cli time log 42 --hours 1h30m --activity Development
+op-cli project member add web alice Manager   # join members so assignment works
+op-cli project list --search web
+op-cli doctor            # diagnose connectivity, credentials, versions
+```
+
+## Things worth knowing
+
+- **Errors are a closed set.** Every failure prints a stable code on stderr,
+  such as `[CONFLICT]` or `[PROFILE_NOT_FOUND]`, with exit codes 0 through 7.
+  Run `op-cli doctor` when something does not work.
+- **A project in context narrows listings.** `--project`, or a profile's
+  default project, scopes `wp list`, `wp count`, `time list`, and
+  `time report` to that project and its subprojects. Without one, those
+  four commands report instance-wide.
+- **Deletion is guarded.** Deleting a project is irreversible: `wp delete`,
+  `time delete`, and `project delete` all require an explicit `--yes`.
+  `user delete` is not offered at all; there is no workaround by design.
+- **JSON records follow the API, `--fields` narrows them.** `--json` emits
+  the flattened OpenProject record, so an instance's own custom fields show
+  up without a CLI release; pass `--fields id,subject,status` on any
+  record-returning command to keep only what you read. With `--all` a
+  listing streams NDJSON, one record per line, not an array.
+- **Profiles beat the environment only when named.** An explicit
+  `--profile <name>` uses that profile's own instance URL and API key, even
+  when `OPENPROJECT_URL` / `OPENPROJECT_API_KEY` are exported; without the
+  flag the environment wins over the active profile. A command served by the
+  environment reports itself as the profile `env`.
+- **`project copy` copies properties only** (description, visibility, and
+  parent). It does not copy work packages, members, or wiki pages.
+- **No escape hatch by design.** If a command is missing there is no raw
+  HTTP passthrough; report the gap instead of working around the tool.
+
+## Companion skill
+
+`skills/op-cli/SKILL.md` packages this CLI's workflows as a coding-agent
+skill. It ships in this repository, not in the npm package; to install
+it, clone the repo and copy that directory into your agent's skills folder:
+
+```sh
+cp -R skills/op-cli ~/.claude/skills/op-cli
+```
+
+## The Python predecessor
+
+op-cli is a TypeScript rewrite of an earlier Python-based OpenProject skill.
+That archived implementation lives on the `feature/openproject-skill` branch
+of [claude-plugin](https://github.com/hoangvantuan/claude-plugin/tree/feature/openproject-skill).
+It is kept unmerged as historical documentation of API quirks and field
+mappings; do not build on it.
+
+## Development
+
+```sh
+npm run build   # compile src/ to dist/
+npm test        # unit tests over fixtures from a real instance
+npm run lint
+scripts/smoke.sh  # REQUIRED gate before publishing
+```
+
+`scripts/smoke.sh` exercises a real create, update, time log, and delete
+lifecycle against a scratch project on a live instance configured through
+`OPENPROJECT_URL` and `OPENPROJECT_API_KEY`. It fails loudly at the first
+broken step. There are no automated integration tests by design; this
+script is the regression net for real write paths before every publish.
+
+## License
+
+MIT. See the NOTICE file for the trademark statement.

package/dist/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { createNodeIo } from "./io/node-io.js";
+import { run } from "./run.js";
+const result = await run(process.argv.slice(2), process.env, createNodeIo());
+process.stdout.write(result.stdout);
+process.stderr.write(result.stderr);
+process.exitCode = result.exitCode;
+//# sourceMappingURL=bin.js.map

package/dist/commands/doctor.js

@@ -0,0 +1,135 @@
+import { OpCliError } from "../core/errors.js";
+import { apiGet, authenticate } from "../core/http.js";
+import { renderTable } from "../output/table.js";
+// The CLI speaks OpenProject API v3; the documented minimum core release is
+// v13 (PLAN.md row "Phiên bản OpenProject cũ"). An instance older than v13
+// still works partially, so it only warns; a non-v3 API cannot work at all,
+// so it fails with its own catalogue code.
+const MINIMUM_CORE_MAJOR = 13;
+function toRootInfo(root) {
+    const element = typeof root === "object" && root !== null
+        ? root
+        : {};
+    return {
+        apiVersion: typeof element.apiVersion === "string" ? element.apiVersion : null,
+        coreVersion: typeof element.coreVersion === "string" ? element.coreVersion : null,
+    };
+}
+function majorOf(version) {
+    const match = /^(\d+)/.exec(version.trim());
+    const major = match?.[1];
+    return major === undefined ? undefined : Number.parseInt(major, 10);
+}
+function errorCodeOf(error) {
+    return error instanceof OpCliError ? error.code : "INTERNAL_ERROR";
+}
+function versionSummary(info) {
+    if (info.apiVersion === null && info.coreVersion === null) {
+        return "api unknown, core unknown (stock instances may omit this)";
+    }
+    return `api ${info.apiVersion ?? "unknown"}, core ${info.coreVersion ?? "unknown"}`;
+}
+export function registerDoctorCommand(parent, runtime) {
+    parent
+        .description("Diagnose connectivity, credentials, permissions, and versions")
+        .option("--json", "emit a JSON object")
+        .option("--profile <name>", "diagnose this profile instead of the active one")
+        .action(async (options) => {
+        runtime.setJsonMode(options.json === true);
+        const profile = await runtime.resolve({ profile: options.profile });
+        const checks = [];
+        let failureCode;
+        const recordFailure = (check, detail, code) => {
+            checks.push({ check, status: "fail", detail });
+            failureCode = failureCode ?? code;
+        };
+        const skip = (name) => {
+            checks.push({
+                check: name,
+                status: "skipped",
+                detail: "not attempted: an earlier check failed",
+            });
+        };
+        let info = { apiVersion: null, coreVersion: null };
+        try {
+            info = toRootInfo(await apiGet(profile.instanceUrl, profile.apiKey, "/api/v3/"));
+            checks.push({
+                check: "connectivity",
+                status: "pass",
+                detail: `reached ${profile.instanceUrl}`,
+            });
+        }
+        catch (error) {
+            recordFailure("connectivity", `could not reach ${profile.instanceUrl} (${errorCodeOf(error)})`, errorCodeOf(error));
+        }
+        if (failureCode !== undefined) {
+            skip("credentials");
+        }
+        else {
+            try {
+                const user = await authenticate(profile.instanceUrl, profile.apiKey);
+                checks.push({
+                    check: "credentials",
+                    status: "pass",
+                    detail: `authenticated as ${user.login}`,
+                });
+            }
+            catch (error) {
+                recordFailure("credentials", "could not verify credentials", errorCodeOf(error));
+            }
+        }
+        if (failureCode !== undefined) {
+            skip("permissions");
+        }
+        else {
+            try {
+                await apiGet(profile.instanceUrl, profile.apiKey, "/api/v3/projects?pageSize=1");
+                checks.push({
+                    check: "permissions",
+                    status: "pass",
+                    detail: "can list projects",
+                });
+            }
+            catch (error) {
+                recordFailure("permissions", "cannot list projects", errorCodeOf(error));
+            }
+        }
+        if (failureCode !== undefined) {
+            skip("versions");
+        }
+        else {
+            const apiMajor = info.apiVersion !== null ? majorOf(info.apiVersion) : undefined;
+            const coreMajor = info.coreVersion !== null ? majorOf(info.coreVersion) : undefined;
+            if (apiMajor !== undefined && apiMajor !== 3) {
+                recordFailure("versions", `API ${info.apiVersion} is not supported`, "UNSUPPORTED_VERSION");
+            }
+            else if (coreMajor !== undefined && coreMajor < MINIMUM_CORE_MAJOR) {
+                checks.push({
+                    check: "versions",
+                    status: "warn",
+                    detail: `core ${info.coreVersion} is below the minimum supported v13`,
+                });
+            }
+            else {
+                checks.push({
+                    check: "versions",
+                    status: "pass",
+                    detail: versionSummary(info),
+                });
+            }
+        }
+        if (options.json === true) {
+            runtime.write(`${JSON.stringify({ ok: failureCode === undefined, checks })}\n`);
+        }
+        else {
+            runtime.write(renderTable(["CHECK", "STATUS", "DETAIL"], checks.map((check) => [check.check, check.status, check.detail])));
+            for (const warning of checks.filter((check) => check.status === "warn")) {
+                runtime.write(`warning: ${warning.check}: ${warning.detail}\n`);
+            }
+        }
+        if (failureCode !== undefined) {
+            throw new OpCliError(failureCode);
+        }
+    });
+}
+//# sourceMappingURL=doctor.js.map

package/dist/commands/meta.js

@@ -0,0 +1,283 @@
+import { clearStoredMetadata, customFieldAllowedNames, loadProjectVocabulary, loadStoredMetadata, readStoredMetadata, refreshStoredMetadata, } from "../context/metadata.js";
+import { parseOptionalId } from "../context/profile.js";
+import { defineLookupCommand, } from "../core/define.js";
+import { renderTable } from "../output/table.js";
+function star(value) {
+    return value === true ? "*" : "";
+}
+const projectOption = {
+    flag: "--project <id>",
+    description: "override the profile default project",
+};
+const typeLookup = {
+    name: "types",
+    description: "List the work package types of the instance",
+    select: (metadata) => metadata.types,
+    columns: [
+        { title: "ID", cell: (entry) => String(entry.id) },
+        { title: "NAME", cell: (entry) => entry.name },
+        { title: "MILESTONE", cell: (entry) => star(entry.is_milestone) },
+    ],
+};
+const statusLookup = {
+    name: "statuses",
+    description: "List the work package statuses of the instance",
+    select: (metadata) => metadata.statuses,
+    columns: [
+        { title: "ID", cell: (entry) => String(entry.id) },
+        { title: "NAME", cell: (entry) => entry.name },
+        { title: "CLOSED", cell: (entry) => star(entry.is_closed) },
+        { title: "DEFAULT", cell: (entry) => star(entry.is_default) },
+    ],
+    filters: [
+        {
+            flag: "--open",
+            description: "only statuses that are not closed",
+            keep: (entry) => !entry.is_closed,
+        },
+        {
+            flag: "--closed",
+            description: "only closed statuses",
+            keep: (entry) => entry.is_closed,
+        },
+    ],
+};
+const priorityLookup = {
+    name: "priorities",
+    description: "List the work package priorities of the instance",
+    select: (metadata) => metadata.priorities,
+    columns: [
+        { title: "ID", cell: (entry) => String(entry.id) },
+        { title: "NAME", cell: (entry) => entry.name },
+        { title: "DEFAULT", cell: (entry) => star(entry.is_default) },
+    ],
+};
+const memberLookup = {
+    name: "members",
+    description: "List the members of the active project",
+    select: (vocabulary) => vocabulary.members,
+    options: [projectOption],
+    columns: [
+        { title: "ID", cell: (entry) => String(entry.user_id) },
+        { title: "NAME", cell: (entry) => entry.name },
+        { title: "TYPE", cell: (entry) => entry.type },
+        {
+            title: "ROLES",
+            cell: (entry) => entry.roles.map((role) => role.title).join(", "),
+        },
+    ],
+};
+const versionLookup = {
+    name: "versions",
+    description: "List the versions of the active project",
+    select: (vocabulary) => vocabulary.versions,
+    options: [projectOption],
+    columns: [
+        { title: "ID", cell: (entry) => String(entry.id) },
+        { title: "NAME", cell: (entry) => entry.name },
+        { title: "STATUS", cell: (entry) => entry.status },
+    ],
+};
+const categoryLookup = {
+    name: "categories",
+    description: "List the categories of the active project",
+    select: (vocabulary) => vocabulary.categories,
+    options: [projectOption],
+    columns: [
+        { title: "ID", cell: (entry) => String(entry.id) },
+        { title: "NAME", cell: (entry) => entry.name },
+    ],
+};
+/**
+ * One row per custom field, however many work package types carry it.
+ * `custom_fields` is stored keyed by type id, so flattening it repeats a
+ * shared field once per type; a custom field is defined once for the
+ * instance, so those copies differ only in which type exposes them and
+ * that difference belongs in the TYPES column, not in extra rows.
+ *
+ * The `wp create` resolver keeps reading the per-type map directly: there
+ * a shared name repeated across types is exactly what makes it ambiguous.
+ */
+function uniqueFields(data) {
+    const typeName = new Map(data.metadata.types.map((entry) => [String(entry.id), entry.name]));
+    const byKey = new Map();
+    for (const [typeId, fields] of Object.entries(data.vocabulary.custom_fields)) {
+        const owner = typeName.get(typeId) ?? typeId;
+        for (const field of fields) {
+            const existing = byKey.get(field.key);
+            if (existing === undefined) {
+                byKey.set(field.key, { field, types: [owner] });
+                continue;
+            }
+            if (!existing.types.includes(owner)) {
+                existing.types.push(owner);
+            }
+        }
+    }
+    return [...byKey.values()]
+        .map((entry) => ({ ...entry.field, types: entry.types }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+const fieldLookup = {
+    name: "fields",
+    description: "List the custom fields of the active project",
+    select: uniqueFields,
+    options: [projectOption],
+    columns: [
+        { title: "ID", cell: (entry) => String(entry.id) },
+        { title: "NAME", cell: (entry) => entry.name },
+        { title: "KEY", cell: (entry) => entry.key },
+        { title: "TYPES", cell: (entry) => entry.types.join(", ") },
+        {
+            title: "ALLOWED VALUES",
+            cell: (entry) => customFieldAllowedNames(entry).join(", "),
+        },
+    ],
+};
+const activityLookup = {
+    name: "activities",
+    description: "List the time entry activities of the active project",
+    select: (vocabulary) => vocabulary.activities,
+    options: [projectOption],
+    columns: [
+        { title: "ID", cell: (entry) => String(entry.id) },
+        { title: "NAME", cell: (entry) => entry.name },
+        { title: "DEFAULT", cell: (entry) => star(entry.is_default) },
+    ],
+};
+function registerShow(parent, runtime) {
+    const command = parent
+        .command("show")
+        .description("Show the stored metadata of the active profile")
+        .option("--json", "emit a JSON object");
+    command.action(async (options) => {
+        runtime.setJsonMode(options.json === true);
+        const profile = await runtime.resolve();
+        const stored = await readStoredMetadata(runtime.env, profile);
+        if (stored === undefined) {
+            runtime.write(options.json === true
+                ? "null\n"
+                : "No metadata stored yet.\nRun op-cli meta types to load it.\n");
+            return;
+        }
+        if (options.json === true) {
+            runtime.write(`${JSON.stringify(stored)}\n`);
+            return;
+        }
+        runtime.write(renderTable(["KEY", "VALUE"], [
+            ["profile", profile.name],
+            ["instance", stored.instance.url],
+            ["api_version", stored.instance.api_version ?? ""],
+            ["core_version", stored.instance.core_version ?? ""],
+            ["fetched_at", stored.instance.fetched_at],
+            ["project", formatProjectRef(stored)],
+            ["types", String(stored.types.length)],
+            ["statuses", String(stored.statuses.length)],
+            ["priorities", String(stored.priorities.length)],
+        ]));
+    });
+}
+function formatProjectRef(stored) {
+    return stored.project === undefined
+        ? ""
+        : `${String(stored.project.id)} (${stored.project.identifier})`;
+}
+function registerRefresh(parent, runtime) {
+    const command = parent
+        .command("refresh")
+        .description("Re-fetch the stored metadata and report what changed")
+        .option("--json", "emit a JSON object");
+    command.action(async (options) => {
+        runtime.setJsonMode(options.json === true);
+        const profile = await runtime.resolve();
+        const changes = await refreshStoredMetadata(runtime.env, profile);
+        if (options.json === true) {
+            runtime.write(`${JSON.stringify({
+                profile: profile.name,
+                instance: profile.instanceUrl,
+                changes,
+            })}\n`);
+            return;
+        }
+        runtime.write(`Refreshing metadata for profile ${profile.name} at ${profile.instanceUrl}.\n`);
+        writeChangeLines(runtime.write, changes);
+        runtime.write(changes.length > 0 ? "Metadata updated.\n" : "No changes.\n");
+    });
+}
+function writeChangeLines(write, changes) {
+    let index = 0;
+    while (index < changes.length) {
+        const section = changes[index]?.section;
+        const details = [];
+        while (index < changes.length && changes[index]?.section === section) {
+            const detail = changes[index]?.detail;
+            if (detail !== undefined) {
+                details.push(detail);
+            }
+            index += 1;
+        }
+        write(`${String(section)}: ${details.join("; ")}\n`);
+    }
+}
+function registerClear(parent, runtime) {
+    parent
+        .command("clear")
+        .description("Delete the stored metadata of the active profile")
+        .action(async () => {
+        const profile = await runtime.resolve();
+        await clearStoredMetadata(runtime.env, profile);
+        runtime.write(`Cleared stored metadata for profile ${profile.name}.\n`);
+    });
+}
+function addLookup(parent, runtime, spec, load) {
+    parent.addCommand(defineLookupCommand(spec, {
+        load,
+        write: runtime.write,
+        setJsonMode: runtime.setJsonMode,
+    }));
+}
+function instanceLoad(runtime) {
+    return async () => loadStoredMetadata(runtime.env, await runtime.resolve());
+}
+/** The active profile under this run's --project override, if any. */
+async function projectProfile(runtime, options) {
+    const raw = options.project;
+    return runtime.resolve({
+        project: parseOptionalId(typeof raw === "string" ? raw : undefined),
+    });
+}
+function projectLoad(runtime) {
+    return async (options) => loadProjectVocabulary(runtime.env, await projectProfile(runtime, options));
+}
+/**
+ * The fields lookup needs the instance types too, to name them. Instance
+ * metadata is loaded first because the vocabulary is stored inside it, so
+ * an empty cache is filled by one fetch of each rather than two.
+ */
+function fieldLoad(runtime) {
+    return async (options) => {
+        const profile = await projectProfile(runtime, options);
+        const metadata = await loadStoredMetadata(runtime.env, profile);
+        return {
+            metadata,
+            vocabulary: await loadProjectVocabulary(runtime.env, profile),
+        };
+    };
+}
+export function registerMetaCommands(parent, runtime) {
+    // Eight read-only lookups, one declaration each.
+    const instance = instanceLoad(runtime);
+    const project = projectLoad(runtime);
+    addLookup(parent, runtime, typeLookup, instance);
+    addLookup(parent, runtime, statusLookup, instance);
+    addLookup(parent, runtime, priorityLookup, instance);
+    addLookup(parent, runtime, memberLookup, project);
+    addLookup(parent, runtime, versionLookup, project);
+    addLookup(parent, runtime, categoryLookup, project);
+    addLookup(parent, runtime, fieldLookup, fieldLoad(runtime));
+    addLookup(parent, runtime, activityLookup, project);
+    registerShow(parent, runtime);
+    registerRefresh(parent, runtime);
+    registerClear(parent, runtime);
+}
+//# sourceMappingURL=meta.js.map