@qui-cli/env 5.0.4 → 5.1.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [5.1.0](https://github.com/battis/qui-cli/compare/env/5.0.4...env/5.1.0) (2026-01-19)
+
+
+### Features
+
+* support 1Password secret references if @1password/sdk (and 1Password) installed ([ed4570c](https://github.com/battis/qui-cli/commit/ed4570cd5cf19ae34fc03f6b88b01f0ebf72e72d))
+
+
+### Bug Fixes
+
+* detect missing 1Password CLI ([3c306ba](https://github.com/battis/qui-cli/commit/3c306ba7e37394948666f96b1ad728e8abc65a4e)), closes [#81](https://github.com/battis/qui-cli/issues/81)
+
 ## [5.0.4](https://github.com/battis/qui-cli/compare/env/5.0.3...env/5.0.4) (2026-01-18)
 
 

package/README.md

@@ -31,7 +31,19 @@ Any plugin that depends on this plugin can assume that the `.env` file environem
 
 ### 1Password integration
 
-For 1Password integration supporting secret references in `.env`, use [@qui-cli/env-1password](https://npmjs.com/package/@qui-cli/env-1password) in place of this package.
+To access 1Password secret references stored in the environment, install the optional peer dependency [@1password/sdk](https://www.npmjs.com/package/@1password/sdk). For full integration, also install the [1Password CLI](https://developer.1password.com/docs/cli/) which will allow you to look up a [1Password service account](https://developer.1password.com/docs/service-accounts/security/) token by identifier.
+
+The configuration options `opToken`, `opItem`, and `opAccount` may all be passed as command-line options. For example:
+
+```sh
+example --opToken "$(op item get ServiceAccountToken)"
+```
+
+If the [1Password CLI tool](https://developer.1password.com/docs/cli) is installed, then `opItem` and `opAccount` can be used:
+
+```sh
+example --opAccount example.1password.com --opitem "My Token Identifier"
+```
 
 ## Configuration
 
@@ -55,9 +67,25 @@ Whether or not to load the `.env` file into `process.env` immediately. Defaults
 
 Path to desired `.env` file relative to `root`. Defaults to `'.env'`;
 
+### 1Password configuration
+
+If 1Password secret references are stored in the environment, a 1Password service account token is required to access the secret values.
+
+#### `opToken`
+
+1Password service account token; will use environment variable `OP_TOKEN` if present
+
+#### `opItem`
+
+Name or ID of the 1Password API Credential item storing the 1Password service account token; will use environment variable `OP_ITEM` if present. Requires the [1Password CLI tool](https://developer.1password.com/docs/cli).
+
+#### `opAccount`
+
+1Password account to use (if signed into multiple); will use environment variable `OP_ACCOUNT` if present
+
 ## Options
 
-`Env` adds no user-configurable command line options.
+When the optional peer dependency [@1password/sdk](https://www.npmjs.com/package/@1password/sdk) is installed, `Env` exposes `opAccount`, `opItem`, and `opToken` as command-line options.
 
 ## Initialization
 

package/dist/1Password/1Password.d.ts

@@ -0,0 +1,12 @@
+import * as Plugin from '@qui-cli/plugin';
+import { OPConfiguration } from './Configuration.js';
+export declare const name = "1password support";
+export declare function configure(proposal?: OPConfiguration): Promise<void>;
+export declare function options(): Plugin.Options;
+export declare function init({ values }: Plugin.ExpectedArguments<typeof options>): Promise<void>;
+export declare function get(ref: string): Promise<string>;
+/** Requires a service account with write privileges */
+export declare function set({ ref, value }: {
+    ref: string;
+    value: string;
+}): Promise<void>;

package/dist/1Password/1Password.js

@@ -0,0 +1,157 @@
+import { createClient } from '@1password/sdk';
+import { importLocal } from '@battis/import-package-json';
+import { Colors } from '@qui-cli/colors';
+import { Log } from '@qui-cli/log';
+import { Shell } from '@qui-cli/shell';
+import path from 'node:path';
+import ora from 'ora';
+export const name = '1password support';
+const config = {};
+let _client = undefined;
+async function getClient() {
+    if (!_client) {
+        const spinner = ora('Loading 1Password').start();
+        if (config.opItem && !config.opToken) {
+            const silent = Shell.isSilent();
+            const showCommands = Shell.commandsShown();
+            const logging = Shell.isLogging();
+            Shell.configure({ silent: true, showCommands: false, logging: false });
+            if (/(\d+\.)+\d/.test(Shell.exec('op -v').stdout)) {
+                const { stdout, stderr } = Shell.exec(`op item get ${config.opAccount ? `--account "${config.opAccount}" ` : ''}--reveal --fields credential "${config.opItem}"`);
+                if (stdout.length) {
+                    config.opToken = stdout.trim();
+                }
+                else {
+                    Log.fatal(stderr);
+                    process.exit(1);
+                }
+            }
+            else {
+                throw new Error(`Looking up a 1Password service account token by item identifier requires the 1Password CLI (${Colors.url('https://developer.1password.com/docs/cli')}).`);
+            }
+            Shell.configure({ silent, showCommands, logging });
+        }
+        if (config.opToken) {
+            const pkg = await importLocal(path.join(import.meta.dirname, '../../package.json'));
+            _client = await createClient({
+                auth: config.opToken,
+                integrationName: pkg
+                    .name.replace(/^(\/|@)/, '')
+                    .replace(/[/@]+/g, '-'),
+                integrationVersion: pkg.version
+            });
+            spinner.succeed('1Password loaded');
+        }
+        else {
+            const message = 'A 1Password service account token was not provided.';
+            spinner.fail(message);
+            throw new Error('A 1Password service account token was not provided.');
+        }
+    }
+    return _client;
+}
+export async function configure(proposal = {}) {
+    for (const key in proposal) {
+        if (proposal[key] !== undefined) {
+            config[key] = proposal[key];
+        }
+    }
+}
+export function options() {
+    return {
+        man: [
+            {
+                level: 1,
+                text: '1Password environment integration'
+            },
+            {
+                text: `If 1Password secret references are stored in the environment, a ` +
+                    `1Password service account token is required to access the secret ` +
+                    `values.`
+            }
+        ],
+        opt: {
+            opAccount: {
+                description: `1Password account to use (if signed into multiple); will use ` +
+                    `environment variable ${Colors.varName('OP_ACCOUNT')} if present`,
+                hint: 'example.1password.com',
+                default: config.opAccount
+            },
+            opItem: {
+                description: `Name or ID of the 1Password API Credential item storing the ` +
+                    `1Password service account token; will use environment variable ` +
+                    `${Colors.varName('OP_ITEM')} if present. Requires the 1Password ` +
+                    `CLI tool (${Colors.url('https://developer.1password.com/docs/cli')})`,
+                hint: '1Password unique identifier',
+                default: config.opItem
+            },
+            opToken: {
+                description: `1Password service account token; will use environment variable ` +
+                    `${Colors.varName('OP_TOKEN')} if present`,
+                hint: 'token value',
+                secret: true,
+                default: config.opToken
+            }
+        }
+    };
+}
+export async function init({ values }) {
+    const { opAccount = process.env.OP_ACCOUNT, opItem = process.env.OP_ITEM, opToken = process.env.OP_TOKEN } = values;
+    await configure({ ...values, opAccount, opItem, opToken });
+}
+export async function get(ref) {
+    const client = await getClient();
+    return await client.secrets.resolve(ref);
+}
+function explodeSecretReference(secretReference) {
+    // eslint-disable-next-line prefer-const
+    let [vault, item, section, field] = secretReference
+        .replace(/^op:\/\//, '')
+        .split('/');
+    if (field === undefined) {
+        field = section;
+        section = '';
+    }
+    return { vault, item, section, field };
+}
+async function itemFrom(parts) {
+    const client = await getClient();
+    const vault = (await client.vaults.list())
+        .filter((vault) => vault.title == parts.vault)
+        .shift();
+    if (vault) {
+        const item = (await client.items.list(vault.id))
+            .filter((item) => item.title === parts.item || item.id === parts.item)
+            .shift();
+        if (item) {
+            return await client.items.get(vault.id, item.id);
+        }
+    }
+}
+/** Requires a service account with write privileges */
+export async function set({ ref, value }) {
+    const client = await getClient();
+    const parts = explodeSecretReference(ref);
+    const item = await itemFrom(parts);
+    if (item) {
+        const updated = {
+            ...item,
+            fields: item.fields.map((field) => {
+                const section = item.sections.find((s) => s.id === field.sectionId);
+                if (parts.field === field.title || parts.field === field.id) {
+                    if ((!parts.section &&
+                        (field.sectionId === '' || field.sectionId === 'add more')) ||
+                        parts.section === section?.title ||
+                        parts.section === section?.id) {
+                        return { ...field, value };
+                    }
+                }
+                return field;
+            })
+        };
+        await client.items.put(updated);
+    }
+    else {
+        throw new Error('1Password item could not be found');
+    }
+}

package/dist/1Password/Configuration.d.ts

@@ -0,0 +1,18 @@
+import * as Plugin from '@qui-cli/plugin';
+export type OPConfiguration = Plugin.Configuration & {
+    /**
+     * 1Password service account token; will use the environment variable OP_TOKEN
+     * if present
+     */
+    opToken?: string;
+    /**
+     * Name or ID of the 1Password API Credential item storing the 1Password
+     * service account token; will use environment variable OP_ITEM if present
+     */
+    opItem?: string;
+    /**
+     * 1Password account to use (if signed into multiple); will use environment
+     * variable OP_ACCOUNT if present
+     */
+    opAccount?: string;
+};

package/dist/1Password/Configuration.js

@@ -0,0 +1 @@
+export {};

package/dist/1Password/index.d.ts

@@ -0,0 +1,3 @@
+export * from './1Password.js';
+export * from './Configuration.js';
+export * from './isSecretReference.js';

package/dist/1Password/index.js

@@ -0,0 +1,3 @@
+export * from './1Password.js';
+export * from './Configuration.js';
+export * from './isSecretReference.js';

package/dist/1Password/isSecretReference.d.ts

@@ -0,0 +1 @@
+export declare function isSecretReference(value: unknown): unknown;

package/dist/1Password/isSecretReference.js

@@ -0,0 +1,6 @@
+export function isSecretReference(value) {
+    return (value &&
+        value !== null &&
+        typeof value === 'string' &&
+        /^op:\/\//.test(value));
+}

package/dist/Env.d.ts

@@ -1,5 +1,6 @@
 import * as Plugin from '@qui-cli/plugin';
 import dotenv from 'dotenv';
+import { OPConfiguration } from './1Password/Configuration.js';
 export type Configuration = Plugin.Configuration & {
     /**
      * Optional root for calculating relative paths to `.env` files. If undefined,
@@ -14,12 +15,13 @@ export type Configuration = Plugin.Configuration & {
     load?: boolean;
     /** Path to desired `.env` file relative to `root`. Defaults to `'.env'`; */
     path?: string;
-};
+} & OPConfiguration;
 export declare const name = "env";
-export declare function configure(config?: Configuration): Promise<void>;
-export declare function init(): void;
+export declare function configure(proposal?: Configuration): Promise<void>;
+export declare function options(): Promise<Plugin.Options>;
+export declare function init(args: Plugin.ExpectedArguments<typeof options>): Promise<void>;
 export type ParsedResult = dotenv.DotenvParseOutput;
-export declare function parse(file?: string): Promise<ParsedResult>;
+export declare function parse(file?: string | undefined): Promise<ParsedResult>;
 export type GetOptions = {
     key: string;
     file?: string;
@@ -27,10 +29,15 @@ export type GetOptions = {
 export declare function get({ key, file }: GetOptions): Promise<string | undefined>;
 export declare function exists({ key, file }: GetOptions): Promise<boolean>;
 export type SetOptions = {
+    /** Name of environment variable to set */
     key: string;
+    /** Value to set */
     value: string;
+    /** Path to the .env file */
     file?: string;
+    /** A comment included in the .env file above the variable */
     comment?: string;
+    /** Only set key=value if key is not already set */
     ifNotExists?: boolean;
 };
 export declare function set({ key, value, file, comment, ifNotExists }: SetOptions): Promise<void>;

package/dist/Env.js

@@ -1,25 +1,59 @@
-import * as Plugin from '@qui-cli/plugin';
 import { Root } from '@qui-cli/root';
 import dotenv from 'dotenv';
 import fs from 'node:fs';
 import path from 'node:path';
+import { isSecretReference } from './1Password/isSecretReference.js';
+let OP = undefined;
+try {
+    await import('@1password/sdk');
+    OP = await import('./1Password/index.js');
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+}
+catch (_) {
+    // @1password/sdk not present
+}
 export const name = 'env';
-let root = undefined;
-let load = true;
-let pathToEnv = '.env';
-export async function configure(config = {}) {
-    root = Plugin.hydrate(config.root, root);
-    load = Plugin.hydrate(config.load, load);
-    pathToEnv = Plugin.hydrate(config.path, pathToEnv);
-    if (load) {
+const config = {
+    load: true,
+    path: '.env'
+};
+export async function configure(proposal = {}) {
+    for (const key in proposal) {
+        if (proposal[key] !== undefined) {
+            config[key] = proposal[key];
+        }
+    }
+    if (OP?.configure) {
+        OP.configure({
+            opAccount: config.opAccount,
+            opItem: config.opItem,
+            opToken: config.opToken
+        });
+    }
+    if (config.load) {
         await parse();
     }
 }
-export function init() {
+export async function options() {
+    if (OP?.options) {
+        return await OP.options();
+    }
+    else {
+        return {};
+    }
+}
+export async function init(args) {
+    if (OP?.init) {
+        await OP.init(args);
+    }
+    await configure(args.values);
     parse();
 }
-export async function parse(file = pathToEnv) {
-    const filePath = path.resolve(root || Root.path(), typeof file === 'string' ? file : '.env');
+function toFilePath(file = '.env') {
+    return path.resolve(config.root || Root.path(), file);
+}
+export async function parse(file = config.path) {
+    const filePath = toFilePath(file);
     if (fs.existsSync(filePath)) {
         const env = dotenv.config({ path: filePath, quiet: true });
         if (env.error) {
@@ -29,40 +63,60 @@ export async function parse(file = pathToEnv) {
     }
     return {};
 }
-export async function get({ key, file = pathToEnv }) {
-    if (fs.existsSync(path.resolve(root || Root.path(), file))) {
-        return (await parse(file))[key];
+export async function get({ key, file = config.path || '.env' }) {
+    if (fs.existsSync(toFilePath(file))) {
+        const env = await parse(file);
+        if (isSecretReference(env[key])) {
+            if (OP?.get) {
+                return OP?.get(env[key]);
+            }
+            else {
+                throw new Error(`Attempt to read environment variable ${key} that is a 1Password secret reference without @1password/sdk installed.`);
+            }
+        }
+        return env[key];
     }
     return undefined;
 }
-export async function exists({ key, file = pathToEnv }) {
-    if (fs.existsSync(path.resolve(root || Root.path(), file))) {
+export async function exists({ key, file = config.path }) {
+    if (fs.existsSync(toFilePath(file))) {
         return !!(await parse(file))[key];
     }
     return false;
 }
-export async function set({ key, value, file = pathToEnv, comment, ifNotExists = false }) {
-    const filePath = path.resolve(root || Root.path(), file);
-    if (ifNotExists === false || false === (await exists({ key, file }))) {
-        let env = '';
-        if (fs.existsSync(filePath)) {
-            env = fs.readFileSync(filePath).toString();
-        }
-        const pattern = new RegExp(`^${key}=.*$`, 'm');
-        if (/[\s=]/.test(value)) {
-            value = `"${value}"`;
-        }
-        if (pattern.test(env)) {
-            env = env.replace(pattern, `${key}=${value}`);
+export async function set({ key, value, file = config.path, comment, ifNotExists = false }) {
+    const filePath = toFilePath(file);
+    const { [key]: prev } = dotenv.config({ path: filePath, quiet: true }).parsed || {};
+    if (ifNotExists === false || !prev) {
+        if (prev && isSecretReference(prev)) {
+            if (OP?.set) {
+                OP.set({ ref: prev, value });
+            }
+            else {
+                throw new Error(`Attmept to update environment variable ${key} that is a 1Password secret reference without installing @1password/sdk`);
+            }
         }
         else {
-            env = `${env.trim()}\n${comment ? `\n# ${comment}\n` : ''}${key}=${value}\n`;
+            let env = '';
+            if (fs.existsSync(filePath)) {
+                env = fs.readFileSync(filePath).toString();
+            }
+            const pattern = new RegExp(`^${key}=.*$`, 'm');
+            if (/[\s=]/.test(value)) {
+                value = `"${value}"`;
+            }
+            if (pattern.test(env)) {
+                env = env.replace(pattern, `${key}=${value}`);
+            }
+            else {
+                env = `${env.trim()}\n${comment ? `\n# ${comment}\n` : ''}${key}=${value}\n`;
+            }
+            fs.writeFileSync(filePath, env);
         }
-        fs.writeFileSync(filePath, env);
     }
 }
-export async function remove({ key, file = pathToEnv, comment }) {
-    const filePath = path.resolve(root || Root.path(), file);
+export async function remove({ key, file = config.path || '.env', comment }) {
+    const filePath = path.resolve(config.root || Root.path(), file);
     if (fs.existsSync(filePath)) {
         const env = fs.readFileSync(filePath).toString();
         const pattern = new RegExp(`${key}=.*\\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qui-cli/env",
-  "version": "5.0.4",
+  "version": "5.1.0",
   "description": "@qui-cli Plugin: Standardized environment configuration",
   "homepage": "https://github.com/battis/qui-cli/tree/main/packages/env#readme",
   "repository": {
@@ -17,23 +17,36 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "dependencies": {
-    "@1password/sdk": "^0.3.1",
     "@battis/import-package-json": "^0.1.7",
-    "dotenv": "^17.2.3"
+    "dotenv": "^17.2.3",
+    "ora": "^9.0.0"
   },
   "devDependencies": {
+    "@1password/sdk": "^0.3.1",
     "@tsconfig/node24": "^24.0.4",
     "@types/node": "^24.10.9",
     "commit-and-tag-version": "^12.6.1",
     "del-cli": "^7.0.0",
     "npm-run-all": "^4.1.5",
     "typescript": "^5.9.3",
+    "@qui-cli/log": "4.0.3",
+    "@qui-cli/plugin": "4.1.0",
+    "@qui-cli/colors": "3.2.3",
     "@qui-cli/root": "3.1.0",
-    "@qui-cli/plugin": "4.1.0"
+    "@qui-cli/shell": "3.1.2"
   },
   "peerDependencies": {
+    "@1password/sdk": "0.3.x",
+    "@qui-cli/colors": ">=3",
+    "@qui-cli/log": ">=3",
     "@qui-cli/plugin": ">=3",
-    "@qui-cli/root": ">=3"
+    "@qui-cli/root": ">=3",
+    "@qui-cli/shell": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "@1password/sdk": {
+      "optional": true
+    }
   },
   "target": "node",
   "scripts": {