@vertexvis/plm-cli 0.1.3

package/README.md

@@ -0,0 +1,373 @@
+# vertex-plm-cli
+
+**Vertex PLM CLI Utilities**
+
+A cross-platform CLI for interacting with **Vertex PLM** services and workflows. Built with **Node.js + TypeScript** using the [oclif](https://oclif.io) framework.
+
+Commands available:
+
+- `configure` — manage credentials and service hosts via a local config file
+- `set-overwrite` — set overwrite policy for a part revision and all related parts
+- `view-part` — look up a registered part revision
+- `view-part-jobs` — view PLM kernel jobs for a part revision
+- `view-part-structure` — view the instance tree (BOM) for a part revision
+
+---
+
+## Requirements
+
+- Node.js >= 16.0.0
+- Yarn
+
+---
+
+## Quick Start (Dev)
+
+Install dependencies:
+
+```bash
+yarn
+```
+
+Build (compile TypeScript to `lib/`):
+
+```bash
+yarn build
+```
+
+Run the CLI:
+
+```bash
+./bin/run --help
+```
+
+Or link it globally so it's available as `vertex-plm`:
+
+```bash
+yarn link
+vertex-plm --help
+```
+
+---
+
+## Configuration
+
+This CLI requires the following environment variables (or stored config values):
+
+| Variable | Purpose |
+|---|---|
+| `VERTEX_CLIENT_ID` | Vertex Platform OAuth2 client ID |
+| `VERTEX_CLIENT_SECRET` | Vertex Platform OAuth2 client secret |
+| `VERTEX_API_HOST` | Vertex Platform API base URL (e.g. `https://api.vertexvis.com`) |
+| `VERTEX_PLM_HOST` | Vertex PLM Integration Service base URL |
+| `VERTEX_PLM_API_KEY` | Vertex PLM Integration Service API key |
+
+### How config works
+
+On startup, the CLI loads:
+
+1. **Environment variables already in your shell / CI** (highest priority)
+2. Config file at `~/.vertex-plm/config.json` (fallback)
+
+Config file values only populate `process.env.*` if the env var is not already set. This means you can safely override stored config in CI:
+
+```bash
+VERTEX_PLM_API_KEY="ci-key" vertex-plm view-part-structure P123 A
+```
+
+### Configure (interactive)
+
+Prompts for each value; leave blank to keep the current stored value:
+
+```bash
+vertex-plm configure --interactive
+```
+
+### Configure (flags)
+
+Set any subset of values directly:
+
+```bash
+vertex-plm configure \
+  --VERTEX_API_HOST https://api.vertexvis.com \
+  --VERTEX_PLM_HOST https://plm.example.com \
+  --VERTEX_CLIENT_ID "abc" \
+  --VERTEX_CLIENT_SECRET "super-secret" \
+  --VERTEX_PLM_API_KEY "plm-key"
+```
+
+### Show config
+
+```bash
+vertex-plm configure --show
+```
+
+Secrets are redacted in output:
+
+```json
+{
+  "VERTEX_CLIENT_ID": "abc",
+  "VERTEX_CLIENT_SECRET": "********",
+  "VERTEX_API_HOST": "https://api.vertexvis.com",
+  "VERTEX_PLM_HOST": "https://plm.example.com",
+  "VERTEX_PLM_API_KEY": "********"
+}
+```
+
+### Unset keys
+
+```bash
+vertex-plm configure --unset VERTEX_PLM_API_KEY VERTEX_CLIENT_SECRET
+```
+
+### Reset config
+
+Deletes the config file entirely:
+
+```bash
+vertex-plm configure --reset
+```
+
+### Config file location
+
+```
+~/.vertex-plm/config.json
+```
+
+---
+
+## Commands
+
+### `set-overwrite`
+
+Sets the overwrite policy in the PLM Integration Service for the given part revision and **all related part revisions** found in the Vertex Platform instance tree.
+
+**Usage**
+```bash
+vertex-plm set-overwrite <plm-part-id> <plm-revision-id> [plm-iteration-id]
+```
+
+**Examples**
+```bash
+vertex-plm set-overwrite P123 A
+vertex-plm set-overwrite P123 A 7
+```
+
+---
+
+### `view-part`
+
+Looks up a registered part revision in the PLM Integration Service and its corresponding entry in the Vertex Platform. If not found in the PLM service, falls back to searching the Vertex Platform directly.
+
+**Usage**
+```bash
+vertex-plm view-part <plm-part-id> <plm-revision-id> [plm-iteration-id]
+```
+
+**Examples**
+```bash
+vertex-plm view-part P123 A
+vertex-plm view-part P123 A 7
+```
+
+---
+
+### `view-part-jobs`
+
+Displays PLM kernel jobs associated with a registered part revision.
+
+**Usage**
+```bash
+vertex-plm view-part-jobs <plm-part-id> <plm-revision-id> [plm-iteration-id]
+```
+
+**Examples**
+```bash
+vertex-plm view-part-jobs P123 A
+vertex-plm view-part-jobs P123 A 7
+```
+
+---
+
+### `view-part-structure`
+
+Fetches and displays the full part revision instance tree (BOM hierarchy) from the Vertex Platform for the given PLM part revision.
+
+**Usage**
+```bash
+vertex-plm view-part-structure <plm-part-id> <plm-revision-id> [plm-iteration-id]
+```
+
+**Examples**
+```bash
+vertex-plm view-part-structure P123 A
+vertex-plm view-part-structure P123 A 7
+```
+
+---
+
+## Development
+
+### Project structure
+
+```
+src/
+  index.ts                       # oclif entrypoint (re-exports run)
+  commands/
+    configure.ts                 # config file management
+    set-overwrite.ts             # set-overwrite command
+    view-part.ts                 # view-part command
+    view-part-jobs.ts            # view-part-jobs command
+    view-part-structure.ts       # view-part-structure command
+  lib/
+    args.ts                      # shared arg parsing/types
+    base.ts                      # BaseCommand (loads config on init)
+    config.ts                    # config file load/save/env injection
+    prompt.ts                    # interactive prompts (secrets masked)
+    plm-api/                     # PLM Integration Service client
+    vertex-api/                  # Vertex Platform API client
+    tree/                        # generic tree structure for BOM traversal
+```
+
+### Running tests
+
+```bash
+yarn test
+```
+
+### Lint and format
+
+```bash
+yarn lint
+yarn format
+```
+
+### Pre-commit checks
+
+```bash
+yarn pre-commit
+```
+
+This runs lint and format together.
+
+---
+
+## Contributing
+
+1. Clone and install:
+
+```bash
+git clone <repo-url>
+cd vertex-plm-cli
+yarn
+```
+
+2. Make changes in `src/`. Keep `BaseCommand` as the base for all commands — it handles config loading automatically.
+
+3. Build and verify:
+
+```bash
+yarn build
+./bin/run --help
+./bin/run --version
+```
+
+4. A good PR should include:
+   - A clear description of what changed and why
+   - Example command usage
+   - Updates to this README if behavior changes
+
+---
+
+## Release Process
+
+This project uses [semantic versioning](https://semver.org): `MAJOR.MINOR.PATCH`.
+
+### 1) Bump the version
+
+```bash
+npm version patch   # or minor / major
+```
+
+This updates `package.json` and runs `git add package.json` (via the `version` script).
+
+### 2) Build and verify
+
+```bash
+yarn build
+./bin/run --version
+./bin/run --help
+```
+
+### 3) Commit and tag
+
+If not auto-committed by `npm version`:
+
+```bash
+git commit -m "chore(release): vX.Y.Z"
+git tag vX.Y.Z
+```
+
+### 4) Push
+
+```bash
+git push origin main
+git push origin vX.Y.Z
+```
+
+### 5) Create a GitHub Release
+
+1. Go to **Releases** → **Draft a new release**
+2. Select the tag `vX.Y.Z`
+3. Add release notes summarizing changes
+
+---
+
+## Troubleshooting
+
+### `vertex-plm: command not found`
+
+If developing locally without linking:
+
+```bash
+./bin/run --help
+```
+
+Or link globally:
+
+```bash
+yarn link
+vertex-plm --help
+```
+
+### Config isn't being applied
+
+```bash
+vertex-plm configure --show
+```
+
+Remember: environment variables override config file values at runtime.
+
+### Host validation errors
+
+`VERTEX_API_HOST` and `VERTEX_PLM_HOST` must be valid URLs:
+
+✅ Valid:
+- `https://api.vertexvis.com`
+- `http://localhost:3000`
+
+❌ Invalid:
+- `api.vertexvis.com` (missing protocol)
+- `vertex-plm-host` (not a URL)
+
+---
+
+## Security Notes
+
+The config file stores secrets (client secret + API key) as plain JSON in your home directory. Prefer environment variables in CI and shared environments. Treat `~/.vertex-plm/config.json` as sensitive.
+
+---
+
+## License
+
+Internal / TBD.

package/bin/run

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+require('@oclif/command').run()
+.then(require('@oclif/command/flush'))
+.catch(require('@oclif/errors/handle'))

package/bin/run.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\run" %*

package/lib/commands/configure.d.ts

@@ -0,0 +1,30 @@
+import { flags } from '@oclif/command';
+import BaseCommand from '../lib/base';
+export interface ConfigureInput {
+    VERTEX_CLIENT_ID?: string;
+    VERTEX_CLIENT_SECRET?: string;
+    VERTEX_API_HOST?: string;
+    VERTEX_PLM_HOST?: string;
+    VERTEX_PLM_API_KEY?: string;
+    show?: boolean;
+    interactive?: boolean;
+    reset?: boolean;
+    unset?: string[];
+}
+export declare function configureFn(input: ConfigureInput): Promise<void>;
+export default class Configure extends BaseCommand {
+    static description: string;
+    static flags: {
+        VERTEX_CLIENT_ID: flags.IOptionFlag<string | undefined>;
+        VERTEX_CLIENT_SECRET: flags.IOptionFlag<string | undefined>;
+        VERTEX_API_HOST: flags.IOptionFlag<string | undefined>;
+        VERTEX_PLM_HOST: flags.IOptionFlag<string | undefined>;
+        VERTEX_PLM_API_KEY: flags.IOptionFlag<string | undefined>;
+        interactive: import("@oclif/parser/lib/flags").IBooleanFlag<boolean>;
+        unset: flags.IOptionFlag<string[]>;
+        reset: import("@oclif/parser/lib/flags").IBooleanFlag<boolean>;
+        show: import("@oclif/parser/lib/flags").IBooleanFlag<boolean>;
+        help: import("@oclif/parser/lib/flags").IBooleanFlag<void>;
+    };
+    run(): Promise<void>;
+}

package/lib/commands/configure.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureFn = void 0;
+const tslib_1 = require("tslib");
+const command_1 = require("@oclif/command");
+const base_1 = (0, tslib_1.__importDefault)(require("../lib/base"));
+const config_1 = require("../lib/config");
+const prompt_1 = require("../lib/prompt");
+function requireNonEmptyString(v, name) {
+    if (typeof v !== 'string' || v.trim().length === 0) {
+        throw new Error(`${name} must be a non-empty string`);
+    }
+}
+function validateHostUrl(value, name) {
+    let u;
+    try {
+        u = new URL(value);
+    }
+    catch (_a) {
+        throw new Error(`${name} must be a valid URL (e.g. https://example.com)`);
+    }
+    if (u.protocol !== 'https:' && u.protocol !== 'http:') {
+        throw new Error(`${name} must start with http:// or https://`);
+    }
+}
+function normalizeKey(k) {
+    const upper = k.trim().toUpperCase();
+    return config_1.CONFIG_KEYS.includes(upper)
+        ? upper
+        : undefined;
+}
+function applyFlagValues(existing, input) {
+    const merged = Object.assign({}, existing);
+    for (const k of config_1.CONFIG_KEYS) {
+        const v = input[k];
+        if (v === null || v === undefined)
+            continue;
+        requireNonEmptyString(v, k);
+        merged[k] = v;
+    }
+    if (merged.VERTEX_API_HOST)
+        validateHostUrl(merged.VERTEX_API_HOST, 'VERTEX_API_HOST');
+    if (merged.VERTEX_PLM_HOST)
+        validateHostUrl(merged.VERTEX_PLM_HOST, 'VERTEX_PLM_HOST');
+    return merged;
+}
+async function applyInteractive(existing, merged) {
+    // Capture all current values before any awaits to avoid require-atomic-updates
+    const existingApiHost = merged.VERTEX_API_HOST;
+    const existingPlmHost = merged.VERTEX_PLM_HOST;
+    const existingClientId = merged.VERTEX_CLIENT_ID;
+    const existingClientSecret = merged.VERTEX_CLIENT_SECRET;
+    const existingPlmKey = merged.VERTEX_PLM_API_KEY;
+    const result = Object.assign({}, merged);
+    const wantApiHost = existingApiHost !== null && existingApiHost !== void 0 ? existingApiHost : (await (0, prompt_1.promptText)('VERTEX_API_HOST', existingApiHost));
+    if (wantApiHost) {
+        requireNonEmptyString(wantApiHost, 'VERTEX_API_HOST');
+        validateHostUrl(wantApiHost, 'VERTEX_API_HOST');
+        result.VERTEX_API_HOST = wantApiHost;
+    }
+    const wantPlmHost = existingPlmHost !== null && existingPlmHost !== void 0 ? existingPlmHost : (await (0, prompt_1.promptText)('VERTEX_PLM_HOST', existingPlmHost));
+    if (wantPlmHost) {
+        requireNonEmptyString(wantPlmHost, 'VERTEX_PLM_HOST');
+        validateHostUrl(wantPlmHost, 'VERTEX_PLM_HOST');
+        result.VERTEX_PLM_HOST = wantPlmHost;
+    }
+    const wantClientId = existingClientId !== null && existingClientId !== void 0 ? existingClientId : (await (0, prompt_1.promptText)('VERTEX_CLIENT_ID', existingClientId));
+    if (wantClientId) {
+        requireNonEmptyString(wantClientId, 'VERTEX_CLIENT_ID');
+        result.VERTEX_CLIENT_ID = wantClientId;
+    }
+    const wantClientSecret = existingClientSecret !== null && existingClientSecret !== void 0 ? existingClientSecret : (await (0, prompt_1.promptSecret)('VERTEX_CLIENT_SECRET', Boolean(existing.VERTEX_CLIENT_SECRET)));
+    if (wantClientSecret) {
+        requireNonEmptyString(wantClientSecret, 'VERTEX_CLIENT_SECRET');
+        result.VERTEX_CLIENT_SECRET = wantClientSecret;
+    }
+    const wantPlmKey = existingPlmKey !== null && existingPlmKey !== void 0 ? existingPlmKey : (await (0, prompt_1.promptSecret)('VERTEX_PLM_API_KEY', Boolean(existing.VERTEX_PLM_API_KEY)));
+    if (wantPlmKey) {
+        requireNonEmptyString(wantPlmKey, 'VERTEX_PLM_API_KEY');
+        result.VERTEX_PLM_API_KEY = wantPlmKey;
+    }
+    return result;
+}
+function inputIsEmpty(input) {
+    const flagValues = config_1.CONFIG_KEYS.map((k) => input[k]);
+    const hasFlagValues = flagValues.some((v) => v !== null && v !== undefined);
+    const hasUnsets = input.unset !== null && input.unset !== undefined && input.unset.length > 0;
+    return (!hasFlagValues &&
+        !hasUnsets &&
+        !input.reset &&
+        !input.show &&
+        !input.interactive);
+}
+function existingIsEmpty(existing) {
+    return config_1.CONFIG_KEYS.every((k) => !(k in existing));
+}
+async function configureFn(input) {
+    var _a;
+    const existing = await (0, config_1.readConfig)();
+    if (input.reset) {
+        await (0, config_1.deleteConfigFile)();
+        console.log(`Config reset (deleted): ${(0, config_1.getConfigPath)()}`);
+        return;
+    }
+    if (input.show) {
+        console.log(JSON.stringify((0, config_1.redactConfig)(existing), null, 2));
+        console.log(`Path: ${(0, config_1.getConfigPath)()}`);
+        return;
+    }
+    let merged = Object.assign({}, existing);
+    if ((_a = input.unset) === null || _a === void 0 ? void 0 : _a.length) {
+        for (const raw of input.unset) {
+            const key = normalizeKey(raw);
+            if (!key)
+                throw new Error(`Unknown key to unset: ${raw}. Valid: ${config_1.CONFIG_KEYS.join(', ')}`);
+            delete merged[key];
+        }
+    }
+    merged = applyFlagValues(existing, Object.assign({}, input));
+    if (input.interactive || (inputIsEmpty(input) && existingIsEmpty(existing))) {
+        merged = await applyInteractive(existing, merged);
+    }
+    await (0, config_1.writeConfig)(merged);
+    console.log(`Saved config to ${(0, config_1.getConfigPath)()}:`);
+    console.log(JSON.stringify((0, config_1.redactConfig)(merged), null, 2));
+}
+exports.configureFn = configureFn;
+class Configure extends base_1.default {
+    async run() {
+        const { flags: f } = this.parse(Configure);
+        await configureFn({
+            VERTEX_CLIENT_ID: f.VERTEX_CLIENT_ID,
+            VERTEX_CLIENT_SECRET: f.VERTEX_CLIENT_SECRET,
+            VERTEX_API_HOST: f.VERTEX_API_HOST,
+            VERTEX_PLM_HOST: f.VERTEX_PLM_HOST,
+            VERTEX_PLM_API_KEY: f.VERTEX_PLM_API_KEY,
+            interactive: f.interactive,
+            unset: f.unset,
+            reset: f.reset,
+            show: f.show,
+        });
+    }
+}
+exports.default = Configure;
+Configure.description = `Manage config at ${(0, config_1.getConfigPath)()} (env vars override config at runtime)`;
+Configure.flags = Object.assign(Object.assign({}, base_1.default.flags), { VERTEX_CLIENT_ID: command_1.flags.string({ description: 'Vertex client id' }), VERTEX_CLIENT_SECRET: command_1.flags.string({ description: 'Vertex client secret' }), VERTEX_API_HOST: command_1.flags.string({
+        description: 'Vertex API host (e.g. https://api.example.com)',
+    }), VERTEX_PLM_HOST: command_1.flags.string({
+        description: 'Vertex PLM host (e.g. https://plm.example.com)',
+    }), VERTEX_PLM_API_KEY: command_1.flags.string({ description: 'Vertex PLM API key' }), interactive: command_1.flags.boolean({
+        description: 'Prompt for missing values (leave blank to keep current)',
+        default: false,
+    }), unset: command_1.flags.string({
+        multiple: true,
+        description: 'Unset one or more config keys',
+    }), reset: command_1.flags.boolean({
+        description: 'Delete config file and reset all values',
+        default: false,
+    }), show: command_1.flags.boolean({
+        description: 'Show current config (secrets redacted)',
+        default: false,
+    }) });

package/lib/commands/set-overwrite.d.ts

@@ -0,0 +1,13 @@
+import BaseCommand from '../lib/base';
+export default class SetOverwrite extends BaseCommand {
+    static description: string;
+    static args: {
+        name: string;
+        required: boolean;
+        description: string;
+    }[];
+    static flags: {
+        help: import("@oclif/parser/lib/flags").IBooleanFlag<void>;
+    };
+    run(): Promise<void>;
+}

package/lib/commands/set-overwrite.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const args_1 = require("../lib/args");
+const base_1 = (0, tslib_1.__importDefault)(require("../lib/base"));
+const plm_api_1 = require("../lib/plm-api");
+const vertex_api_1 = require("../lib/vertex-api");
+class SetOverwrite extends base_1.default {
+    async run() {
+        const { args } = this.parse(SetOverwrite);
+        const ids = (0, args_1.parsePlmIds)({
+            plmPartId: args.plmPartId,
+            plmRevisionId: args.plmRevisionId,
+            plmIterationId: args.plmIterationId,
+        });
+        console.log('Applying overwrite policy for the following IDs and any instance children:');
+        console.log(JSON.stringify(ids, null, 2));
+        const registeredPart = await (0, plm_api_1.findRegisteredPartRevision)({
+            partId: ids.plmPartId,
+            partRevisionId: ids.plmRevisionId,
+            iterationId: ids.plmIterationId,
+        });
+        if (registeredPart === null) {
+            console.log('Part revision not found in PLM.');
+            return;
+        }
+        console.log('Found registered part revision in PLM:');
+        console.log(JSON.stringify(registeredPart, null, 2));
+        console.log('Fetching related part revision structure data from the platform...');
+        const partRevisions = await (0, vertex_api_1.getUniquePartRevisionsForInstanceTree)(registeredPart.vertexPartRevisionId);
+        console.log(`Found total of ${partRevisions.length} unique related part revisions in the platform.`);
+        await Promise.all(partRevisions.map(async (pr) => {
+            const suppliedPartId = pr.part.attributes.suppliedId;
+            const suppliedRevisionId = pr.partRevision.attributes.suppliedId;
+            if (!suppliedPartId || !suppliedRevisionId) {
+                console.warn(`Skipping part revision with missing supplied IDs. [Part: ${suppliedPartId}, Revision: ${suppliedRevisionId}]`);
+                return;
+            }
+            const partToOverwrite = await (0, plm_api_1.findRegisteredPartRevision)({
+                partId: suppliedPartId,
+                partRevisionId: suppliedRevisionId,
+            });
+            if (partToOverwrite === null || partToOverwrite === undefined) {
+                console.warn(`Registered part revision not found in PLM for referenced part revision. [Part: ${pr.part.attributes.suppliedId}, Revision: ${pr.partRevision.attributes.suppliedId}]`);
+            }
+            else {
+                console.log(`Setting Part Revision to Overwrite. [Part: ${pr.part.attributes.suppliedId}, Revision: ${pr.partRevision.attributes.suppliedId}, RPR: ${partToOverwrite.id}]`);
+                await (0, plm_api_1.setOverwritePolicy)({
+                    registeredPartRevisionId: partToOverwrite.id,
+                });
+            }
+        }));
+        console.log(`Completed setting all related part revisions to overwrite. (${partRevisions.length} revisions processed.)`);
+    }
+}
+exports.default = SetOverwrite;
+SetOverwrite.description = 'Set overwrite flag for a given part revision';
+SetOverwrite.args = [
+    {
+        name: 'plmPartId',
+        required: true,
+        description: 'PLM part ID (string)',
+    },
+    {
+        name: 'plmRevisionId',
+        required: true,
+        description: 'PLM revision ID (string)',
+    },
+    {
+        name: 'plmIterationId',
+        required: false,
+        description: 'PLM iteration ID (string, optional)',
+    },
+];
+SetOverwrite.flags = Object.assign({}, base_1.default.flags);

package/lib/commands/view-part-jobs.d.ts

@@ -0,0 +1,13 @@
+import BaseCommand from '../lib/base';
+export default class ViewPartJobs extends BaseCommand {
+    static description: string;
+    static args: {
+        name: string;
+        required: boolean;
+        description: string;
+    }[];
+    static flags: {
+        help: import("@oclif/parser/lib/flags").IBooleanFlag<void>;
+    };
+    run(): Promise<void>;
+}