@qui-cli/env 5.0.4 → 5.1.1

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 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.1](https://github.com/battis/qui-cli/compare/env/5.1.0...env/5.1.1) (2026-01-21)
+
+
+### Bug Fixes
+
+* configure 1Password before looking up secret references ([7046af5](https://github.com/battis/qui-cli/commit/7046af55ed2720b7b74bd437f335fe49fa8bc00f))
+
+## [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,36 @@
+import * as Plugin from '@qui-cli/plugin';
+import * as Base from './Base.js';
+import * as Secrets from './Secrets.js';
+export type Configuration = 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;
+};
+export declare class OP implements Base.Plugin {
+    [key: string]: unknown;
+    readonly name = "env.1password";
+    private config;
+    private _client;
+    private getClient;
+    configure(proposal?: Configuration): void;
+    private configureFromEnv;
+    options(): Plugin.Options;
+    init({ values }: Plugin.ExpectedArguments<typeof this.options>): Promise<void>;
+    get({ ref, env }: Base.GetOptions): Promise<string>;
+    isSecretReference: typeof Secrets.isRef;
+    private itemFrom;
+    /** Requires a service account with write privileges */
+    set({ ref, value, env }: Base.SetOptions): Promise<void>;
+}

package/dist/1Password/1Password.js

@@ -0,0 +1,156 @@
+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';
+import * as Secrets from './Secrets.js';
+export class OP {
+    name = 'env.1password';
+    config = {};
+    _client = undefined;
+    async getClient() {
+        if (!this._client) {
+            const spinner = ora('Loading 1Password').start();
+            if (this.config.opItem && !this.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 ${this.config.opAccount ? `--account "${this.config.opAccount}" ` : ''}--reveal --fields credential "${this.config.opItem}"`);
+                    if (stdout.length) {
+                        this.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 (this.config.opToken) {
+                const pkg = await importLocal(path.join(import.meta.dirname, '../../package.json'));
+                this._client = await createClient({
+                    auth: this.config.opToken,
+                    integrationName: pkg
+                        .name.replace(/^(\/|@)/, '')
+                        .replace(/[/@]+/g, '-'),
+                    integrationVersion: pkg.version
+                });
+                spinner.succeed('1Password loaded');
+            }
+            else {
+                spinner.fail();
+                throw new Error('A 1Password service account token was not provided.');
+            }
+        }
+        return this._client;
+    }
+    configure(proposal = {}) {
+        for (const key in proposal) {
+            if (proposal[key] !== undefined) {
+                this.config[key] = proposal[key];
+            }
+        }
+    }
+    configureFromEnv(env) {
+        this.configure({
+            opAccount: env.OP_ACCOUNT,
+            opItem: env.OP_ITEM,
+            opToken: env.OP_TOKEN
+        });
+    }
+    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: this.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: this.config.opItem
+                },
+                opToken: {
+                    description: `1Password service account token; will use environment variable ` +
+                        `${Colors.varName('OP_TOKEN')} if present`,
+                    hint: 'token value',
+                    secret: true,
+                    default: this.config.opToken
+                }
+            }
+        };
+    }
+    async init({ values }) {
+        await this.configure(values);
+    }
+    async get({ ref, env }) {
+        this.configureFromEnv(env);
+        return await (await this.getClient()).secrets.resolve(ref);
+    }
+    isSecretReference = Secrets.isRef;
+    async itemFrom(parts) {
+        const client = await this.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 */
+    async set({ ref, value, env }) {
+        this.configureFromEnv(env);
+        const client = await this.getClient();
+        const parts = Secrets.explodeRef(ref);
+        const item = await this.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/Base.d.ts

@@ -0,0 +1,18 @@
+import { Base } from '@qui-cli/plugin/dist/Plugin.js';
+import { isRef } from './Secrets.js';
+type Environment = Record<string, string>;
+export type GetOptions = {
+    ref: string;
+    env: Environment;
+};
+export type SetOptions = {
+    ref: string;
+    value: string;
+    env: Environment;
+};
+export interface Plugin extends Base {
+    isSecretReference: typeof isRef;
+    get(options: GetOptions): Promise<string | undefined>;
+    set(options: SetOptions): Promise<void>;
+}
+export {};

package/dist/1Password/Base.js

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

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

@@ -0,0 +1,8 @@
+export type Reference = {
+    vault: string;
+    item: string;
+    section?: string;
+    field: string;
+};
+export declare function isRef(value: unknown): boolean;
+export declare function explodeRef(ref: string): Reference;

package/dist/1Password/Secrets.js

@@ -0,0 +1,15 @@
+export function isRef(value) {
+    return (!!value &&
+        value !== null &&
+        typeof value === 'string' &&
+        /^op:\/\//.test(value));
+}
+export function explodeRef(ref) {
+    // eslint-disable-next-line prefer-const
+    let [vault, item, section, field] = ref.replace(/^op:\/\//, '').split('/');
+    if (field === undefined) {
+        field = section;
+        section = '';
+    }
+    return { vault, item, section, field };
+}

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

@@ -0,0 +1,6 @@
+import { Plugin } from './Base.js';
+export declare const OP: {
+    isSecretReference: (value: unknown) => boolean;
+    get?: Plugin['get'];
+    set?: Plugin['set'];
+};

package/dist/1Password/index.js

@@ -0,0 +1,17 @@
+import { register } from '@qui-cli/plugin';
+import { isRef } from './Secrets.js';
+export const OP = {
+    isSecretReference: isRef
+};
+try {
+    await import('@1password/sdk');
+    const opModule = await import('./1Password.js');
+    const plugin = new opModule.OP();
+    OP.set = plugin.set.bind(plugin);
+    OP.get = plugin.get.bind(plugin);
+    await register(plugin);
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+}
+catch (_) {
+    //
+}

package/dist/Env.d.ts

@@ -16,10 +16,10 @@ export type Configuration = Plugin.Configuration & {
     path?: string;
 };
 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 init(): 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 +27,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,31 @@
-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 { OP } from './1Password/index.js';
 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 (config.load) {
         await parse();
     }
 }
-export function init() {
+export async function init() {
     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 +35,61 @@ 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 (OP.isSecretReference(env[key])) {
+            if (OP.get) {
+                return await OP.get({ ref: env[key], env });
+            }
+            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 env = dotenv.config({ path: filePath, quiet: true }).parsed || {};
+    const { [key]: prev } = env;
+    if (ifNotExists === false || !prev) {
+        if (prev && OP.isSecretReference(prev)) {
+            if (OP.set) {
+                await OP.set({ ref: prev, value, env });
+            }
+            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.1",
   "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": {