@theholocron/holocron-plugin-1password 2.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Newton Koumantzelis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# `@theholocron/holocron-plugin-1password`
+
+1Password plugin for [Holocron](../cli). Implements the **required**
+`vault` capability via shell-out to the `op` CLI
+(https://developer.1password.com/docs/cli).
+
+## Why shell-out, not REST
+
+1Password's "REST API" is the **Connect server** — a Docker container
+you have to run yourself (or pay for the cloud-hosted version). For a
+solo / small-team workflow, that's overkill. The `op` CLI is what every
+developer already has installed and uses for hand-debugging anyway, so:
+
+- **Local dev:** developer's signed-in `op` CLI (biometric unlock via
+  the desktop app)
+- **CI:** `OP_SERVICE_ACCOUNT_TOKEN` env var; `op` auto-detects it
+- **Either way:** same binary, same commands, same code path
+
+The plugin's job is just to drive the CLI; auth handling is the CLI's.
+
+## Prerequisite
+
+The `op` binary must be on PATH. Install:
+
+```bash
+brew install 1password-cli   # macOS
+# or follow https://developer.1password.com/docs/cli/get-started
+```
+
+The plugin throws a clear error at construction time if `op` isn't
+found.
+
+## Config
+
+```jsonc
+{
+  "providers": {
+    "vault": ["1password", {
+      "vault": "rando",                                    // 1P vault name
+      "account": "ABCDEFGHIJKLMNOPQRSTUVWXYZ"              // optional: 1P account UUID
+    }]
+  }
+}
+```
+
+- `vault` (required) — the 1Password vault name items live in.
+- `account` (optional) — 1P account UUID. Passes `--account <UUID>` on
+  every `op` call so the integration targets a specific account even
+  when the developer has multiple signed in (e.g., work + personal).
+  Find via `op account list`.
+
+## What's implemented
+
+| Method                 | What it does                                                                   |
+| ---------------------- | ------------------------------------------------------------------------------ |
+| `read(reference)`      | `op read <reference>` — resolves `op://Vault/Item/field`. `--no-newline`.      |
+| `write(reference, v)`  | Probe + `op item edit` if exists, else `op item create --category=API Credential`. |
+| `list()`               | `op item list --vault=<vault> --format=json` — names of items in the vault.    |
+| `environments()`       | `op environment list --format=json` — names of 1P Environments.                |
+| `readEnvironment(id)`  | `op environment read <id>` — parses KEY=VALUE lines into a record.             |
+| `whoami()` (via doctor)| `op whoami --format=json` — tolerates the JSON-shape drift across CLI versions and auth modes. |
+
+## Status
+
+**v0.0.0 — first port.** Ports `rando-id/rando.id`
+`adapters/op-cli.ts`. The stdio shape (`['inherit', 'pipe', 'pipe']`)
+is critical: it gives `op` a TTY signal so it can fire the desktop
+biometric unlock dialog when running locally. CI runs see no TTY and
+fall back to whatever auth mode the env var configures.

package/dist/index.d.mts

@@ -0,0 +1,83 @@
+import { spawnSync } from "node:child_process";
+import { Vault } from "@theholocron/cli";
+
+//#region src/auth.d.ts
+declare class AuthError extends Error {
+  name: string;
+}
+interface VerifyInput {
+  /** Override the spawn function in tests. */
+  spawn?: typeof spawnSync;
+  /** Path to the op binary. Defaults to "op". */
+  binary?: string;
+}
+declare function verifyOpInstalled(input?: VerifyInput): void;
+//#endregion
+//#region src/shell.d.ts
+interface OpResult {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+}
+interface OpShellOptions {
+  /** Override the spawn function in tests. */
+  spawn?: typeof spawnSync;
+  /** Path to the op binary. Defaults to "op". */
+  binary?: string;
+  /** 1Password account UUID. When set, passed as `--account` on every call. */
+  account?: string;
+}
+interface RunOptions {
+  /** Skip `--account` injection for commands that operate above the account level (e.g., `account list`). */
+  skipAccount?: boolean;
+}
+declare class OpShell {
+  private readonly spawnImpl;
+  readonly binary: string;
+  readonly account?: string;
+  constructor(opts?: OpShellOptions);
+  /** Run `op <args>`, returning a uniform result. */
+  run(args: string[], opts?: RunOptions): OpResult;
+  /** Run + throw if non-zero. Mirrors REST clients' `request<T>` ergonomic. */
+  runOrThrow(args: string[], context: string, opts?: RunOptions): string;
+}
+//#endregion
+//#region src/capabilities/vault.d.ts
+interface OpVaultOptions {
+  /** 1P vault name items live in. Required — list/write default here. */
+  vault: string;
+}
+declare class OpVault implements Vault {
+  private readonly shell;
+  readonly key: "vault";
+  readonly providerName = "1password";
+  private readonly vaultName;
+  constructor(shell: OpShell, opts: OpVaultOptions);
+  read(reference: string): Promise<string>;
+  write(reference: string, value: string): Promise<void>;
+  list(): Promise<string[]>;
+  environments(): Promise<string[]>;
+  readEnvironment(environmentId: string): Promise<Record<string, string>>;
+}
+//#endregion
+//#region src/index.d.ts
+interface OpPluginOptions extends VerifyInput {
+  /** 1P vault name items live in. Required. */
+  vault: string;
+  /** Optional 1P account UUID; passed as `--account` on every op call. */
+  account?: string;
+}
+interface PluginContext {
+  options: OpPluginOptions;
+  shell: OpShell;
+}
+declare function createContext(options: OpPluginOptions): PluginContext;
+declare function vault(ctx: PluginContext): Vault;
+declare function createPlugin(options: OpPluginOptions): {
+  name: string;
+  capabilities: {
+    vault: () => Vault;
+  };
+};
+//#endregion
+export { AuthError, OpPluginOptions, OpShell, OpVault, PluginContext, VerifyInput, createContext, createPlugin, vault, verifyOpInstalled };

package/dist/index.mjs

@@ -0,0 +1,241 @@
+import { spawnSync } from "node:child_process";
+import { ProviderApiError } from "@theholocron/cli";
+//#region src/auth.ts
+/**
+* 1Password plugin "auth" is just verifying the `op` binary is on
+* PATH — the CLI handles its own auth (keychain biometric unlock for
+* local dev, OP_SERVICE_ACCOUNT_TOKEN for CI).
+*
+* No `resolveToken()` like the REST plugins; instead, `verifyOpInstalled`
+* runs a fast `op --version` check. `createPlugin` calls it eagerly so
+* a missing binary fails fast and clearly, not as a mystery error when
+* the first `vault.read()` happens later.
+*/
+var AuthError = class extends Error {
+	name = "AuthError";
+};
+function verifyOpInstalled(input = {}) {
+	const spawnImpl = input.spawn ?? spawnSync;
+	const binary = input.binary ?? "op";
+	const result = spawnImpl(binary, ["--version"], {
+		encoding: "utf-8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	if (result.error) throw new AuthError(`1Password CLI (\`${binary}\`) not found on PATH. Install via \`brew install 1password-cli\` or see https://developer.1password.com/docs/cli/get-started.`);
+	if (result.status !== 0) throw new AuthError(`\`${binary} --version\` failed: ${(result.stderr ?? "").trim() || `exit ${result.status ?? "?"}`}`);
+}
+//#endregion
+//#region src/capabilities/vault.ts
+/**
+* `vault` capability for 1Password.
+*
+* Shells out to the `op` CLI for every operation. Reference format
+* is 1P's native `op://Vault/Item/field` URI.
+*
+* Write semantics: 1P doesn't have an upsert. We probe `op item get`
+* first; if it returns 0 the item exists and we `op item edit`,
+* otherwise we `op item create --category=API Credential`. The
+* fallback gives us an idempotent create-or-update without us
+* parsing edit's stderr to detect "not found".
+*/
+var OpVault = class {
+	shell;
+	key = "vault";
+	providerName = "1password";
+	vaultName;
+	constructor(shell, opts) {
+		this.shell = shell;
+		if (!opts.vault) throw new Error("OpVault requires `vault` (1P vault name) in options");
+		this.vaultName = opts.vault;
+	}
+	async read(reference) {
+		return this.shell.runOrThrow([
+			"read",
+			reference,
+			"--no-newline"
+		], `read ${reference}`);
+	}
+	async write(reference, value) {
+		const parsed = parseReference(reference);
+		if (this.shell.run([
+			"item",
+			"get",
+			parsed.item,
+			`--vault=${parsed.vault}`,
+			"--format=json"
+		]).ok) {
+			this.shell.runOrThrow([
+				"item",
+				"edit",
+				parsed.item,
+				`--vault=${parsed.vault}`,
+				`${parsed.field}=${value}`
+			], `item edit ${parsed.item}`);
+			return;
+		}
+		this.shell.runOrThrow([
+			"item",
+			"create",
+			`--title=${parsed.item}`,
+			`--vault=${parsed.vault}`,
+			"--category=API Credential",
+			`${parsed.field}=${value}`
+		], `item create ${parsed.item}`);
+	}
+	async list() {
+		const stdout = this.shell.runOrThrow([
+			"item",
+			"list",
+			`--vault=${this.vaultName}`,
+			"--format=json"
+		], `item list --vault=${this.vaultName}`);
+		if (!stdout) return [];
+		return JSON.parse(stdout).map((i) => i.title);
+	}
+	async environments() {
+		const stdout = this.shell.runOrThrow([
+			"environment",
+			"list",
+			"--format=json"
+		], "environment list");
+		if (!stdout) return [];
+		return JSON.parse(stdout).map((e) => e.name);
+	}
+	async readEnvironment(environmentId) {
+		return parseEnvironmentDump(this.shell.runOrThrow([
+			"environment",
+			"read",
+			environmentId
+		], `environment read ${environmentId}`));
+	}
+};
+/**
+* Parse `op://Vault/Item/field` into its parts. Throws when the
+* shape doesn't match — surfacing bad inputs at the boundary keeps
+* downstream `op item edit/create` from emitting cryptic errors.
+*/
+function parseReference(reference) {
+	if (!reference.startsWith("op://")) throw new ProviderApiError(`1Password references must start with "op://": got "${reference}"`, 400, void 0);
+	const parts = reference.slice(5).split("/");
+	if (parts.length < 3) throw new ProviderApiError(`1Password reference "${reference}" missing parts; expected op://Vault/Item/field`, 400, void 0);
+	const [vault, item, ...fieldParts] = parts;
+	return {
+		vault,
+		item,
+		field: fieldParts.join("/")
+	};
+}
+/**
+* Parse `op environment read`'s stdout (KEY=VALUE per line) into a
+* record. Skips blank lines + `# comment` lines. Per-line format is
+* intentionally minimal — no quoting, no escaping; if a value contains
+* a literal newline, that's a problem for the underlying environment,
+* not this parser.
+*/
+function parseEnvironmentDump(stdout) {
+	const out = {};
+	for (const line of stdout.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		const eq = trimmed.indexOf("=");
+		if (eq < 0) continue;
+		const key = trimmed.slice(0, eq);
+		out[key] = trimmed.slice(eq + 1);
+	}
+	return out;
+}
+//#endregion
+//#region src/shell.ts
+/**
+* Thin wrapper around `spawnSync` for `op` CLI shell-outs.
+*
+* Equivalent to the REST clients elsewhere in the monorepo, but for
+* the CLI-transport path. Provides:
+*
+*  - Uniform `OpResult` shape (`ok`, `stdout`, `stderr`) so capability
+*    methods don't repeat the exit-code + decoding boilerplate
+*  - Optional `--account <UUID>` injection on every call so a single
+*    OpShell instance is scoped to one 1P account even when the user
+*    has multiple accounts signed in (work + personal)
+*  - The critical stdio shape: `['inherit', 'pipe', 'pipe']`.
+*    Inheriting stdin gives `op` a TTY signal so it can fire the
+*    desktop biometric unlock dialog locally. CI runs see no TTY and
+*    use whichever auth mode the env vars configure (service account
+*    token). Default spawnSync stdio of `['pipe','pipe','pipe']` would
+*    suppress biometric unlock and return "not signed in" instead.
+*/
+var OpShell = class {
+	spawnImpl;
+	binary;
+	account;
+	constructor(opts = {}) {
+		this.spawnImpl = opts.spawn ?? spawnSync;
+		this.binary = opts.binary ?? "op";
+		if (opts.account !== void 0) this.account = opts.account;
+	}
+	/** Run `op <args>`, returning a uniform result. */
+	run(args, opts = {}) {
+		const fullArgs = this.account && !opts.skipAccount ? [
+			"--account",
+			this.account,
+			...args
+		] : args;
+		const out = this.spawnImpl(this.binary, fullArgs, {
+			encoding: "utf-8",
+			stdio: [
+				"inherit",
+				"pipe",
+				"pipe"
+			]
+		});
+		if (out.error) return {
+			ok: false,
+			stdout: "",
+			stderr: out.error.message
+		};
+		return {
+			ok: out.status === 0,
+			stdout: (out.stdout ?? "").trim(),
+			stderr: (out.stderr ?? "").trim()
+		};
+	}
+	/** Run + throw if non-zero. Mirrors REST clients' `request<T>` ergonomic. */
+	runOrThrow(args, context, opts = {}) {
+		const result = this.run(args, opts);
+		if (!result.ok) throw new ProviderApiError(`1Password ${context} failed: ${result.stderr || "no stderr"}`, 0, result.stderr);
+		return result.stdout;
+	}
+};
+//#endregion
+//#region src/index.ts
+function createContext(options) {
+	if (!options.vault) throw new Error("@theholocron/holocron-plugin-1password requires `vault` in options");
+	const verifyOpts = {};
+	if (options.spawn !== void 0) verifyOpts.spawn = options.spawn;
+	if (options.binary !== void 0) verifyOpts.binary = options.binary;
+	verifyOpInstalled(verifyOpts);
+	const shellOpts = {};
+	if (options.spawn !== void 0) shellOpts.spawn = options.spawn;
+	if (options.binary !== void 0) shellOpts.binary = options.binary;
+	if (options.account !== void 0) shellOpts.account = options.account;
+	return {
+		options,
+		shell: new OpShell(shellOpts)
+	};
+}
+function vault(ctx) {
+	return new OpVault(ctx.shell, { vault: ctx.options.vault });
+}
+function createPlugin(options) {
+	const ctx = createContext(options);
+	return {
+		name: "@theholocron/holocron-plugin-1password",
+		capabilities: { vault: () => vault(ctx) }
+	};
+}
+//#endregion
+export { AuthError, OpShell, OpVault, createContext, createPlugin, vault, verifyOpInstalled };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@theholocron/holocron-plugin-1password",
+  "version": "2.0.0-alpha.0",
+  "description": "Holocron plugin for 1Password. Implements the vault capability via shell-out to the `op` CLI (https://developer.1password.com/docs/cli).",
+  "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-1password#readme",
+  "bugs": "https://github.com/theholocron/holocron/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/holocron.git",
+    "directory": "packages/holocron-plugin-1password"
+  },
+  "license": "MIT",
+  "author": "Newton Koumantzelis",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "peerDependencies": {
+    "@theholocron/cli": "2.0.0-alpha.0"
+  },
+  "devDependencies": {
+    "@theholocron/tsconfig": "^4.1.0",
+    "@tsconfig/node-lts": "^24.0.0",
+    "@vitest/coverage-v8": "^3.2.6",
+    "eslint": "^9.36.0",
+    "globals": "^16.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.6",
+    "tsdown": "^0.22.3",
+    "@theholocron/cli": "2.0.0-alpha.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "types": "./dist/index.d.mts"
+}