@tolgamorf/env2op-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tolga O.
+
+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,123 @@
+# env2op
+
+Convert `.env` files to 1Password Secure Notes and generate template files for `op inject` and `op run`.
+
+## Installation
+
+```bash
+# Using bun
+bun add -g @tolgamorf/env2op-cli
+
+# Using npm
+npm install -g @tolgamorf/env2op-cli
+
+# Or run directly with bunx/npx
+bunx @tolgamorf/env2op-cli .env Personal "MyApp"
+```
+
+## Prerequisites
+
+- [1Password CLI](https://1password.com/downloads/command-line/) installed and signed in
+- [Bun](https://bun.sh) runtime (for best performance)
+
+## Usage
+
+```bash
+env2op <env_file> <vault> <item_name> [options]
+```
+
+### Examples
+
+```bash
+# Basic usage - creates a Secure Note and generates .env.tpl
+env2op .env.production Personal "MyApp - Production"
+
+# Preview what would happen without making changes
+env2op .env.production Personal "MyApp" --dry-run
+
+# Store all fields as password type (hidden in 1Password)
+env2op .env.production Personal "MyApp" --secret
+
+# Skip confirmation prompts (useful for scripts/CI)
+env2op .env.production Personal "MyApp" -y
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Preview actions without executing |
+| `--secret` | Store all fields as 'password' type (default: 'text') |
+| `-y, --yes` | Skip confirmation prompts (auto-accept) |
+| `-h, --help` | Show help |
+| `-v, --version` | Show version |
+
+### Overwriting Existing Items
+
+If an item with the same name already exists in the vault, env2op will prompt for confirmation before overwriting. Use `-y` or `--yes` to skip the prompt and auto-accept.
+
+## How It Works
+
+1. **Parses** your `.env` file to extract environment variables
+2. **Creates** a 1Password Secure Note with all variables as fields
+3. **Generates** a `.tpl` template file with `op://` references
+
+## Using the Generated Template
+
+After running env2op, you'll have a `.env.tpl` file with 1Password references:
+
+```bash
+# Inject secrets into a new .env file
+op inject -i .env.tpl -o .env
+
+# Run a command with secrets injected
+op run --env-file .env.tpl -- npm start
+```
+
+## Field Types
+
+By default, all fields are stored as `text` type (visible in 1Password). Use `--secret` to store them as `password` type (hidden by default, revealed on click).
+
+## Example
+
+Given this `.env` file:
+
+```env
+DATABASE_URL=postgres://localhost/myapp
+API_KEY=sk-1234567890
+DEBUG=true
+```
+
+Running:
+
+```bash
+env2op .env Personal "MyApp Secrets"
+```
+
+Creates a 1Password Secure Note with fields:
+- `DATABASE_URL` (text)
+- `API_KEY` (text)
+- `DEBUG` (text)
+
+And generates `.env.tpl`:
+
+```env
+DATABASE_URL=op://Personal/MyApp Secrets/DATABASE_URL
+API_KEY=op://Personal/MyApp Secrets/API_KEY
+DEBUG=op://Personal/MyApp Secrets/DEBUG
+```
+
+## Programmatic Usage
+
+You can also use env2op as a library:
+
+```typescript
+import { parseEnvFile, createSecureNote, generateTemplateContent } from "@tolgamorf/env2op-cli";
+
+const result = parseEnvFile(".env");
+console.log(result.variables);
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,69 @@
+{
+	"name": "@tolgamorf/env2op-cli",
+	"version": "0.1.0",
+	"description": "Convert .env files to 1Password Secure Notes and generate templates for op inject/run",
+	"type": "module",
+	"main": "src/index.ts",
+	"module": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"import": "./src/index.ts",
+			"types": "./src/index.ts"
+		}
+	},
+	"bin": {
+		"env2op": "src/cli.ts"
+	},
+	"files": ["src", "LICENSE", "README.md"],
+	"scripts": {
+		"dev": "bun run src/cli.ts",
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"lint": "bunx biome check .",
+		"lint:fix": "bunx biome check . --write",
+		"format": "bunx biome format --write .",
+		"format:check": "bunx biome format .",
+		"prepublishOnly": "bun run typecheck"
+	},
+	"keywords": [
+		"env",
+		"1password",
+		"op",
+		"cli",
+		"secrets",
+		"environment-variables",
+		"dotenv",
+		"secure-notes",
+		"bun",
+		"op-inject",
+		"op-run",
+		"template"
+	],
+	"author": {
+		"name": "Tolga O.",
+		"url": "https://github.com/tolgamorf"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tolgamorf/env2op-cli.git"
+	},
+	"bugs": {
+		"url": "https://github.com/tolgamorf/env2op-cli/issues"
+	},
+	"homepage": "https://github.com/tolgamorf/env2op-cli#readme",
+	"engines": {
+		"bun": ">=1.0.0"
+	},
+	"dependencies": {
+		"@clack/prompts": "^0.11.0",
+		"picocolors": "^1.1.1"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"typescript": "^5.9.3",
+		"@tsconfig/bun": "^1.0.10",
+		"@biomejs/biome": "^1.9.4"
+	}
+}

package/src/cli.ts

@@ -0,0 +1,117 @@
+#!/usr/bin/env bun
+
+import pc from "picocolors";
+import { runConvert } from "./commands/convert";
+
+const pkg = await import("../package.json");
+const args = process.argv.slice(2);
+
+// Parse arguments
+const flags = new Set<string>();
+const positional: string[] = [];
+
+for (const arg of args) {
+	if (arg.startsWith("--")) {
+		flags.add(arg.slice(2));
+	} else if (arg.startsWith("-")) {
+		// Handle short flags
+		for (const char of arg.slice(1)) {
+			flags.add(char);
+		}
+	} else {
+		positional.push(arg);
+	}
+}
+
+// Check for help/version flags first
+const hasHelp = flags.has("h") || flags.has("help");
+const hasVersion = flags.has("v") || flags.has("version");
+
+if (hasVersion) {
+	console.log(pkg.version);
+	process.exit(0);
+}
+
+if (hasHelp || positional.length === 0) {
+	showHelp();
+	process.exit(0);
+}
+
+if (positional.length < 3) {
+	showMissingArgsError(positional);
+	process.exit(1);
+}
+
+// All positional args present, run the command
+const [envFile, vault, itemName] = positional as [string, string, string];
+await runConvert({
+	envFile,
+	vault,
+	itemName,
+	dryRun: flags.has("dry-run"),
+	secret: flags.has("secret"),
+	yes: flags.has("y") || flags.has("yes"),
+});
+
+function showHelp(): void {
+	const name = pc.bold(pc.cyan("env2op"));
+	const version = pc.dim(`v${pkg.version}`);
+
+	console.log(`
+${name} ${version}
+${pkg.description}
+
+${pc.bold("USAGE")}
+  ${pc.cyan("$")} env2op ${pc.yellow("<env_file>")} ${pc.yellow("<vault>")} ${pc.yellow("<item_name>")} ${pc.dim("[options]")}
+
+${pc.bold("ARGUMENTS")}
+  ${pc.yellow("env_file")}     Path to .env file
+  ${pc.yellow("vault")}        1Password vault name
+  ${pc.yellow("item_name")}    Name for the Secure Note in 1Password
+
+${pc.bold("OPTIONS")}
+  ${pc.cyan("--dry-run")}      Preview actions without executing
+  ${pc.cyan("--secret")}       Store all fields as password type (hidden)
+  ${pc.cyan("-y, --yes")}      Skip confirmation prompts (auto-accept)
+  ${pc.cyan("-h, --help")}     Show this help message
+  ${pc.cyan("-v, --version")}  Show version
+
+${pc.bold("EXAMPLES")}
+  ${pc.dim("# Basic usage")}
+  ${pc.cyan("$")} env2op .env.production Personal "MyApp - Production"
+
+  ${pc.dim("# Preview without making changes")}
+  ${pc.cyan("$")} env2op .env Personal "MyApp" --dry-run
+
+  ${pc.dim("# Store as hidden password fields")}
+  ${pc.cyan("$")} env2op .env Personal "MyApp" --secret
+
+  ${pc.dim("# Skip confirmation prompts (for CI/scripts)")}
+  ${pc.cyan("$")} env2op .env Personal "MyApp" -y
+
+${pc.bold("DOCUMENTATION")}
+  ${pc.dim("https://github.com/tolgamorf/env2op")}
+`);
+}
+
+function showMissingArgsError(provided: string[]): void {
+	const missing: string[] = [];
+
+	if (provided.length < 1) missing.push("env_file");
+	if (provided.length < 2) missing.push("vault");
+	if (provided.length < 3) missing.push("item_name");
+
+	console.log(`
+${pc.red(pc.bold("Error:"))} Missing required arguments
+
+${pc.bold("Usage:")} env2op ${pc.yellow("<env_file>")} ${pc.yellow("<vault>")} ${pc.yellow("<item_name>")} ${pc.dim("[options]")}
+
+${pc.bold("Missing:")}
+${missing.map((arg) => `  ${pc.red("•")} ${pc.yellow(arg)}`).join("\n")}
+
+${pc.bold("Example:")}
+  ${pc.cyan("$")} env2op .env.production Personal "MyApp - Production"
+
+Run ${pc.cyan("env2op --help")} for more information.
+`);
+}

package/src/commands/convert.ts

@@ -0,0 +1,182 @@
+import { basename, dirname, join } from "node:path";
+import * as p from "@clack/prompts";
+import { parseEnvFile, validateParseResult } from "../core/env-parser";
+import {
+	checkOpCli,
+	checkSignedIn,
+	createSecureNote,
+	createVault,
+	deleteItem,
+	itemExists,
+	vaultExists,
+} from "../core/onepassword";
+import {
+	generateTemplateContent,
+	generateUsageInstructions,
+	writeTemplate,
+} from "../core/template-generator";
+import type { ConvertOptions } from "../core/types";
+import { Env2OpError } from "../utils/errors";
+import { logger } from "../utils/logger";
+
+/**
+ * Execute the convert operation
+ */
+export async function runConvert(options: ConvertOptions): Promise<void> {
+	const { envFile, vault, itemName, dryRun, secret, yes } = options;
+
+	// Display intro
+	const pkg = await import("../../package.json");
+	logger.intro("env2op", pkg.version, dryRun);
+
+	try {
+		// Step 1: Parse .env file
+		const parseResult = parseEnvFile(envFile);
+		validateParseResult(parseResult, envFile);
+
+		const { variables } = parseResult;
+
+		logger.success(`Parsed ${basename(envFile)}`);
+		logger.message(
+			`Found ${variables.length} environment variable${variables.length === 1 ? "" : "s"}`,
+		);
+
+		// Show parse errors as warnings
+		for (const error of parseResult.errors) {
+			logger.warn(error);
+		}
+
+		// Step 2: Create 1Password Secure Note
+		if (dryRun) {
+			logger.warn("Would create Secure Note");
+			logger.keyValue("Vault", vault);
+			logger.keyValue("Title", itemName);
+			logger.keyValue("Type", secret ? "password (hidden)" : "text (visible)");
+			logger.keyValue(
+				"Fields",
+				logger.formatFields(variables.map((v) => v.key)),
+			);
+		} else {
+			// Check 1Password CLI before attempting
+			const opInstalled = await checkOpCli();
+			if (!opInstalled) {
+				throw new Env2OpError(
+					"1Password CLI (op) is not installed",
+					"OP_CLI_NOT_INSTALLED",
+					"Install from https://1password.com/downloads/command-line/",
+				);
+			}
+
+			const signedIn = await checkSignedIn();
+			if (!signedIn) {
+				throw new Env2OpError(
+					"Not signed in to 1Password CLI",
+					"OP_NOT_SIGNED_IN",
+					'Run "op signin" to authenticate',
+				);
+			}
+
+			// Check if vault exists
+			const vaultFound = await vaultExists(vault);
+
+			if (!vaultFound) {
+				if (yes) {
+					// Auto-create vault
+					logger.warn(`Vault "${vault}" not found, creating...`);
+					await createVault(vault);
+					logger.success(`Created vault "${vault}"`);
+				} else {
+					// Ask for confirmation to create vault
+					const shouldCreate = await p.confirm({
+						message: `Vault "${vault}" does not exist. Create it?`,
+					});
+
+					if (p.isCancel(shouldCreate) || !shouldCreate) {
+						logger.cancel("Operation cancelled");
+						logger.info('Run "op vault list" to see available vaults');
+						process.exit(0);
+					}
+
+					const spinner = logger.spinner();
+					spinner.start(`Creating vault "${vault}"...`);
+					await createVault(vault);
+					spinner.stop(`Created vault "${vault}"`);
+				}
+			}
+
+			// Check if item already exists
+			const exists = await itemExists(vault, itemName);
+
+			if (exists) {
+				if (yes) {
+					// Auto-accept: delete and recreate
+					logger.warn(`Item "${itemName}" already exists, overwriting...`);
+					await deleteItem(vault, itemName);
+				} else {
+					// Ask for confirmation
+					const shouldOverwrite = await p.confirm({
+						message: `Item "${itemName}" already exists in vault "${vault}". Overwrite?`,
+					});
+
+					if (p.isCancel(shouldOverwrite) || !shouldOverwrite) {
+						logger.cancel("Operation cancelled");
+						process.exit(0);
+					}
+
+					await deleteItem(vault, itemName);
+				}
+			}
+
+			const spinner = logger.spinner();
+			spinner.start("Creating 1Password Secure Note...");
+
+			try {
+				const result = await createSecureNote({
+					vault,
+					title: itemName,
+					fields: variables,
+					secret,
+				});
+
+				spinner.stop(`Created "${result.title}" in vault "${result.vault}"`);
+			} catch (error) {
+				spinner.stop("Failed to create Secure Note");
+				throw error;
+			}
+		}
+
+		// Step 3: Generate template file
+		const templateContent = generateTemplateContent({
+			vault,
+			itemTitle: itemName,
+			variables,
+		});
+
+		const templatePath = join(dirname(envFile), `${basename(envFile)}.tpl`);
+
+		if (dryRun) {
+			logger.warn(`Would generate template: ${templatePath}`);
+		} else {
+			writeTemplate(templateContent, templatePath);
+			logger.success(`Generated template: ${templatePath}`);
+		}
+
+		// Step 4: Show usage instructions
+		if (dryRun) {
+			logger.outro("Dry run complete. No changes made.");
+		} else {
+			const usage = generateUsageInstructions(templatePath);
+			logger.note(usage, "Next steps");
+			logger.outro("Done! Your secrets are now in 1Password");
+		}
+	} catch (error) {
+		if (error instanceof Env2OpError) {
+			logger.error(error.message);
+			if (error.suggestion) {
+				logger.info(`Suggestion: ${error.suggestion}`);
+			}
+			process.exit(1);
+		}
+		throw error;
+	}
+}

package/src/core/env-parser.ts

@@ -0,0 +1,110 @@
+import { existsSync, readFileSync } from "node:fs";
+import { errors } from "../utils/errors";
+import type { EnvVariable, ParseResult } from "./types";
+
+/**
+ * Parse a value from an environment variable line
+ * Handles quoted strings and inline comments
+ */
+function parseValue(raw: string): string {
+	const trimmed = raw.trim();
+
+	// Handle double-quoted values
+	if (trimmed.startsWith('"')) {
+		const endQuote = trimmed.indexOf('"', 1);
+		if (endQuote !== -1) {
+			return trimmed.slice(1, endQuote);
+		}
+	}
+
+	// Handle single-quoted values
+	if (trimmed.startsWith("'")) {
+		const endQuote = trimmed.indexOf("'", 1);
+		if (endQuote !== -1) {
+			return trimmed.slice(1, endQuote);
+		}
+	}
+
+	// Handle unquoted values with potential inline comments
+	// Only treat # as comment if preceded by whitespace
+	const parts = trimmed.split(/\s+#/);
+	return (parts[0] ?? trimmed).trim();
+}
+
+/**
+ * Parse an .env file and extract environment variables
+ *
+ * @param filePath - Path to the .env file
+ * @returns ParseResult containing variables and any errors
+ * @throws Env2OpError if file not found
+ */
+export function parseEnvFile(filePath: string): ParseResult {
+	if (!existsSync(filePath)) {
+		throw errors.envFileNotFound(filePath);
+	}
+
+	const content = readFileSync(filePath, "utf-8");
+	const lines = content.split("\n");
+	const variables: EnvVariable[] = [];
+	const parseErrors: string[] = [];
+	let currentComment = "";
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i] ?? "";
+		const trimmed = line.trim();
+		const lineNumber = i + 1;
+
+		// Skip empty lines (reset comment)
+		if (!trimmed) {
+			currentComment = "";
+			continue;
+		}
+
+		// Capture comments for next variable
+		if (trimmed.startsWith("#")) {
+			currentComment = trimmed.slice(1).trim();
+			continue;
+		}
+
+		// Parse KEY=VALUE
+		// Key must start with letter or underscore, followed by letters, numbers, or underscores
+		const match = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+
+		if (match?.[1]) {
+			const key = match[1];
+			const rawValue = match[2] ?? "";
+			const value = parseValue(rawValue);
+
+			variables.push({
+				key,
+				value,
+				comment: currentComment || undefined,
+				line: lineNumber,
+			});
+
+			currentComment = "";
+		} else if (trimmed.includes("=")) {
+			// Line has = but doesn't match valid key format
+			parseErrors.push(`Line ${lineNumber}: Invalid variable name`);
+		}
+		// Lines without = are silently ignored (could be malformed or intentional)
+	}
+
+	return { variables, errors: parseErrors };
+}
+
+/**
+ * Validate that the parsed result has variables
+ *
+ * @param result - ParseResult from parseEnvFile
+ * @param filePath - Original file path for error message
+ * @throws Env2OpError if no variables found
+ */
+export function validateParseResult(
+	result: ParseResult,
+	filePath: string,
+): void {
+	if (result.variables.length === 0) {
+		throw errors.envFileEmpty(filePath);
+	}
+}

package/src/core/onepassword.ts

@@ -0,0 +1,119 @@
+import { $ } from "bun";
+import { errors } from "../utils/errors";
+import type { CreateItemOptions, CreateItemResult } from "./types";
+
+/**
+ * Check if the 1Password CLI is installed
+ */
+export async function checkOpCli(): Promise<boolean> {
+	try {
+		await $`op --version`.quiet();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Check if user is signed in to 1Password CLI
+ */
+export async function checkSignedIn(): Promise<boolean> {
+	try {
+		await $`op account get`.quiet();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Check if an item exists in a vault
+ */
+export async function itemExists(
+	vault: string,
+	title: string,
+): Promise<boolean> {
+	try {
+		await $`op item get ${title} --vault ${vault}`.quiet();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Delete an item from a vault
+ */
+export async function deleteItem(vault: string, title: string): Promise<void> {
+	try {
+		await $`op item delete ${title} --vault ${vault}`.quiet();
+	} catch (error) {
+		// Item might not exist, that's fine
+	}
+}
+
+/**
+ * Create a Secure Note in 1Password with the given fields
+ * Note: Caller should check for existing items and handle confirmation before calling this
+ */
+export async function createSecureNote(
+	options: CreateItemOptions,
+): Promise<CreateItemResult> {
+	const { vault, title, fields, secret } = options;
+
+	// Build field arguments
+	// Format: key[type]=value
+	const fieldType = secret ? "password" : "text";
+	const fieldArgs = fields.map(
+		({ key, value }) => `${key}[${fieldType}]=${value}`,
+	);
+
+	try {
+		// Build the command arguments array
+		const args = [
+			"item",
+			"create",
+			"--category=Secure Note",
+			`--vault=${vault}`,
+			`--title=${title}`,
+			"--format=json",
+			...fieldArgs,
+		];
+
+		// Execute op command
+		const result = await $`op ${args}`.json();
+
+		return {
+			id: result.id,
+			title: result.title,
+			vault: result.vault?.name ?? vault,
+		};
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw errors.itemCreateFailed(message);
+	}
+}
+
+/**
+ * Check if a vault exists
+ */
+export async function vaultExists(vault: string): Promise<boolean> {
+	try {
+		await $`op vault get ${vault}`.quiet();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Create a new vault
+ */
+export async function createVault(name: string): Promise<void> {
+	try {
+		await $`op vault create ${name}`.quiet();
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw errors.vaultCreateFailed(message);
+	}
+}

package/src/core/template-generator.ts

@@ -0,0 +1,60 @@
+import { writeFileSync } from "node:fs";
+import type { TemplateOptions } from "./types";
+
+/**
+ * Generate op:// reference template content
+ *
+ * Format: KEY=op://vault/item/field
+ *
+ * This template can be used with:
+ * - `op inject -i template.tpl -o .env`
+ * - `op run --env-file template.tpl -- command`
+ */
+export function generateTemplateContent(options: TemplateOptions): string {
+	const { vault, itemTitle, variables } = options;
+
+	const lines: string[] = [
+		"# Generated by env2op",
+		"# https://github.com/tolgamorf/env2op",
+		"#",
+		"# Usage:",
+		`#   op inject -i ${getTemplateName(options)} -o .env`,
+		`#   op run --env-file ${getTemplateName(options)} -- npm start`,
+		"",
+	];
+
+	for (const { key, comment } of variables) {
+		if (comment) {
+			lines.push(`# ${comment}`);
+		}
+		lines.push(`${key}=op://${vault}/${itemTitle}/${key}`);
+	}
+
+	return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Get the template filename based on the source file
+ */
+function getTemplateName(options: TemplateOptions): string {
+	return `${options.itemTitle.toLowerCase().replace(/\s+/g, "-")}.tpl`;
+}
+
+/**
+ * Write template to file
+ */
+export function writeTemplate(content: string, outputPath: string): void {
+	writeFileSync(outputPath, content, "utf-8");
+}
+
+/**
+ * Generate usage instructions for display
+ */
+export function generateUsageInstructions(templatePath: string): string {
+	return [
+		"",
+		"Usage:",
+		`  op inject -i ${templatePath} -o .env`,
+		`  op run --env-file ${templatePath} -- npm start`,
+	].join("\n");
+}

package/src/core/types.ts

@@ -0,0 +1,79 @@
+/**
+ * Represents a single environment variable parsed from a .env file
+ */
+export interface EnvVariable {
+	/** The variable name/key */
+	key: string;
+	/** The variable value */
+	value: string;
+	/** Optional comment from preceding line */
+	comment?: string;
+	/** Line number in source file */
+	line: number;
+}
+
+/**
+ * Result of parsing an .env file
+ */
+export interface ParseResult {
+	/** Successfully parsed variables */
+	variables: EnvVariable[];
+	/** Any parse errors encountered */
+	errors: string[];
+}
+
+/**
+ * Options for creating a 1Password Secure Note
+ */
+export interface CreateItemOptions {
+	/** Vault name */
+	vault: string;
+	/** Item title */
+	title: string;
+	/** Fields to store */
+	fields: EnvVariable[];
+	/** Store as password type (hidden) instead of text (visible) */
+	secret: boolean;
+}
+
+/**
+ * Result of creating a 1Password item
+ */
+export interface CreateItemResult {
+	/** 1Password item ID */
+	id: string;
+	/** Item title */
+	title: string;
+	/** Vault name */
+	vault: string;
+}
+
+/**
+ * Options for the convert command
+ */
+export interface ConvertOptions {
+	/** Path to .env file */
+	envFile: string;
+	/** 1Password vault name */
+	vault: string;
+	/** Secure Note title */
+	itemName: string;
+	/** Preview mode - don't make changes */
+	dryRun: boolean;
+	/** Store all fields as password type */
+	secret: boolean;
+	/** Skip confirmation prompts (auto-accept) */
+	yes: boolean;
+}
+
+/**
+ * Options for template generation
+ */
+export interface TemplateOptions {
+	/** Vault name */
+	vault: string;
+	/** Item title in 1Password */
+	itemTitle: string;
+	/** Variables to include */
+	variables: EnvVariable[];
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+/**
+ * env2op - Convert .env files to 1Password Secure Notes
+ *
+ * This module exports the core functionality for programmatic use.
+ */
+
+// Core types
+export type {
+	EnvVariable,
+	ParseResult,
+	CreateItemOptions,
+	CreateItemResult,
+	ConvertOptions,
+	TemplateOptions,
+} from "./core/types";
+
+// Env parsing
+export { parseEnvFile, validateParseResult } from "./core/env-parser";
+
+// 1Password integration
+export {
+	checkOpCli,
+	checkSignedIn,
+	itemExists,
+	deleteItem,
+	createSecureNote,
+	vaultExists,
+	createVault,
+} from "./core/onepassword";
+
+// Template generation
+export {
+	generateTemplateContent,
+	writeTemplate,
+	generateUsageInstructions,
+} from "./core/template-generator";
+
+// Errors
+export { Env2OpError, ErrorCodes, errors } from "./utils/errors";

package/src/utils/errors.ts

@@ -0,0 +1,95 @@
+/**
+ * Custom error class for env2op with error codes and suggestions
+ */
+export class Env2OpError extends Error {
+	constructor(
+		message: string,
+		public code: ErrorCode,
+		public suggestion?: string,
+	) {
+		super(message);
+		this.name = "Env2OpError";
+	}
+}
+
+/**
+ * Error codes for different failure scenarios
+ */
+export const ErrorCodes = {
+	ENV_FILE_NOT_FOUND: "ENV_FILE_NOT_FOUND",
+	ENV_FILE_EMPTY: "ENV_FILE_EMPTY",
+	OP_CLI_NOT_INSTALLED: "OP_CLI_NOT_INSTALLED",
+	OP_NOT_SIGNED_IN: "OP_NOT_SIGNED_IN",
+	VAULT_NOT_FOUND: "VAULT_NOT_FOUND",
+	VAULT_CREATE_FAILED: "VAULT_CREATE_FAILED",
+	ITEM_EXISTS: "ITEM_EXISTS",
+	ITEM_CREATE_FAILED: "ITEM_CREATE_FAILED",
+	PARSE_ERROR: "PARSE_ERROR",
+} as const;
+
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+/**
+ * Error factory functions for common scenarios
+ */
+export const errors = {
+	envFileNotFound: (path: string) =>
+		new Env2OpError(
+			`File not found: ${path}`,
+			ErrorCodes.ENV_FILE_NOT_FOUND,
+			"Check that the file path is correct",
+		),
+
+	envFileEmpty: (path: string) =>
+		new Env2OpError(
+			`No valid environment variables found in ${path}`,
+			ErrorCodes.ENV_FILE_EMPTY,
+			"Ensure the file contains KEY=value pairs",
+		),
+
+	opCliNotInstalled: () =>
+		new Env2OpError(
+			"1Password CLI (op) is not installed",
+			ErrorCodes.OP_CLI_NOT_INSTALLED,
+			"Install it from https://1password.com/downloads/command-line/",
+		),
+
+	opNotSignedIn: () =>
+		new Env2OpError(
+			"Not signed in to 1Password CLI",
+			ErrorCodes.OP_NOT_SIGNED_IN,
+			'Run "op signin" to authenticate',
+		),
+
+	vaultNotFound: (vault: string) =>
+		new Env2OpError(
+			`Vault not found: ${vault}`,
+			ErrorCodes.VAULT_NOT_FOUND,
+			'Run "op vault list" to see available vaults',
+		),
+
+	vaultCreateFailed: (message: string) =>
+		new Env2OpError(
+			`Failed to create vault: ${message}`,
+			ErrorCodes.VAULT_CREATE_FAILED,
+		),
+
+	itemExists: (title: string, vault: string) =>
+		new Env2OpError(
+			`Item "${title}" already exists in vault "${vault}"`,
+			ErrorCodes.ITEM_EXISTS,
+			"Use default behavior (overwrites) or choose a different item name",
+		),
+
+	itemCreateFailed: (message: string) =>
+		new Env2OpError(
+			`Failed to create 1Password item: ${message}`,
+			ErrorCodes.ITEM_CREATE_FAILED,
+		),
+
+	parseError: (line: number, message: string) =>
+		new Env2OpError(
+			`Parse error at line ${line}: ${message}`,
+			ErrorCodes.PARSE_ERROR,
+		),
+};

package/src/utils/logger.ts

@@ -0,0 +1,144 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+
+/**
+ * Unicode symbols for different message types
+ */
+const symbols = {
+	success: pc.green("\u2713"),
+	error: pc.red("\u2717"),
+	warning: pc.yellow("\u26A0"),
+	info: pc.blue("\u2139"),
+	arrow: pc.cyan("\u2192"),
+	bullet: pc.dim("\u2022"),
+};
+
+/**
+ * Logger utility for formatted CLI output using @clack/prompts
+ */
+export const logger = {
+	/**
+	 * Display CLI intro banner
+	 */
+	intro(name: string, version: string, dryRun = false) {
+		const label = dryRun
+			? pc.bgYellow(pc.black(` ${name} v${version} [DRY RUN] `))
+			: pc.bgCyan(pc.black(` ${name} v${version} `));
+		p.intro(label);
+	},
+
+	/**
+	 * Display section header
+	 */
+	section(title: string) {
+		console.log(`\n${pc.bold(pc.underline(title))}`);
+	},
+
+	/**
+	 * Success message
+	 */
+	success(message: string) {
+		p.log.success(message);
+	},
+
+	/**
+	 * Error message
+	 */
+	error(message: string) {
+		p.log.error(message);
+	},
+
+	/**
+	 * Warning message
+	 */
+	warn(message: string) {
+		p.log.warn(message);
+	},
+
+	/**
+	 * Info message
+	 */
+	info(message: string) {
+		p.log.info(message);
+	},
+
+	/**
+	 * Step in a process
+	 */
+	step(message: string) {
+		p.log.step(message);
+	},
+
+	/**
+	 * Message (neutral)
+	 */
+	message(message: string) {
+		p.log.message(message);
+	},
+
+	/**
+	 * Display key-value pair
+	 */
+	keyValue(key: string, value: string, indent = 2) {
+		console.log(`${" ".repeat(indent)}${pc.dim(key)}: ${pc.cyan(value)}`);
+	},
+
+	/**
+	 * Display list item
+	 */
+	listItem(item: string, indent = 2) {
+		console.log(`${" ".repeat(indent)}${symbols.bullet} ${item}`);
+	},
+
+	/**
+	 * Display arrow item
+	 */
+	arrowItem(item: string, indent = 2) {
+		console.log(`${" ".repeat(indent)}${symbols.arrow} ${item}`);
+	},
+
+	/**
+	 * Display dry run indicator
+	 */
+	dryRun(message: string) {
+		console.log(`${pc.yellow("[DRY RUN]")} ${message}`);
+	},
+
+	/**
+	 * Create a spinner for async operations
+	 */
+	spinner() {
+		return p.spinner();
+	},
+
+	/**
+	 * Display outro message
+	 */
+	outro(message: string) {
+		p.outro(pc.green(message));
+	},
+
+	/**
+	 * Display cancellation message
+	 */
+	cancel(message: string) {
+		p.cancel(message);
+	},
+
+	/**
+	 * Display a note block
+	 */
+	note(message: string, title?: string) {
+		p.note(message, title);
+	},
+
+	/**
+	 * Format a field list for display
+	 */
+	formatFields(fields: string[], max = 3): string {
+		if (fields.length <= max) {
+			return fields.join(", ");
+		}
+		return `${fields.slice(0, max).join(", ")}, ... and ${fields.length - max} more`;
+	},
+};