lecoffre 0.1.0 → 0.2.0

package/README.md

@@ -2,23 +2,52 @@
 
 > [!WARNING]
 > This project is a work in progress. Expect breaking changes.
-> Variables are currently stored in a plain JSON file. 1Password integration is planned as the default storage backend.
 
 Per-project environment variable manager for the shell.
 
 Store, load and unload environment variables by project and environment, directly in your current shell session.
 
+## Prerequisites
+
+- Node.js 24 or later
+- [1Password CLI (`op`)](https://developer.1password.com/docs/cli/get-started/) installed and signed in
+
 ## Installation
 
 ```sh
 npm install -g lecoffre
 ```
 
-Requires Node.js 24 or later.
+## Storage
+
+By default, lecoffre uses **1Password** as its storage backend. Variables are stored as Secure Notes inside a dedicated `lecoffre` vault.
+
+> [!NOTE]
+> When importing variables, field values are briefly visible in the process argument list (`/proc/<pid>/cmdline`). This is a limitation of the 1Password CLI, which does not support reading field values from stdin when spawned as a child process.
+
+To get started, initialize the vault:
+
+```sh
+lecoffre init
+```
+
+### Alternative: JSON file storage
+
+> [!CAUTION]
+> This storage backend is **not secure**. Variables are stored in plain text on disk.
+
+For development or environments without 1Password, set the `LECOFFRE_STORAGE_PATH` environment variable to use a local JSON file instead:
+
+```sh
+export LECOFFRE_STORAGE_PATH=/tmp/lecoffre.json
+```
 
 ## Quick start
 
 ```sh
+# Initialize the storage backend
+lecoffre init
+
 # Import variables from a .env file
 lecoffre import < .env
 
@@ -31,6 +60,10 @@ eval "$(lecoffre unload)"
 
 ## Commands
 
+### `lecoffre init`
+
+Initialize the storage backend. For 1Password, this creates the `lecoffre` vault if it doesn't exist.
+
 ### `lecoffre list [project]`
 
 List all projects and their environments. When a project name is given, list only the environments for that project.

package/bin/lecoffre.ts

@@ -3,6 +3,7 @@
 import { parse } from "@bomb.sh/args";
 import packageJson from "../package.json" with { type: "json" };
 import { importCommand } from "../src/commands/import.command.ts";
+import { initCommand } from "../src/commands/init.command.ts";
 import { listCommand } from "../src/commands/list.command.ts";
 import { loadCommand } from "../src/commands/load.command.ts";
 import { unloadCommand } from "../src/commands/unload.command.ts";
@@ -16,6 +17,7 @@ import {
 
 const { name } = packageJson;
 const commands: Record<string, AnyCommandDefinition> = {
+  init: initCommand,
   list: listCommand,
   load: loadCommand,
   unload: unloadCommand,

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "lecoffre",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Work in progress CLI project.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hsablonniere/lecoffre"
+  },
   "bin": {
     "lecoffre": "./bin/lecoffre.ts"
   },
   "files": [
     "bin",
+    "src",
     "README.md",
     "LICENSE"
   ],
@@ -25,10 +30,6 @@
     "oxlint": "^1.48.0",
     "vitest": "^4.0.18"
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/hsablonniere/lecoffre"
-  },
   "engines": {
     "node": ">=24"
   },

package/src/commands/import.command.ts

@@ -0,0 +1,101 @@
+import { basename } from "node:path";
+import { realpath } from "node:fs/promises";
+import { parseEnv } from "node:util";
+import { z } from "zod";
+import { defineCommand } from "../lib/define-command.ts";
+import { defineOption } from "../lib/define-option.ts";
+import { getStorage } from "../lib/get-storage.ts";
+import { environmentOption } from "../options/environment.option.ts";
+import { projectOption } from "../options/project.option.ts";
+import { ProjectNotFoundError } from "../lib/storage.ts";
+
+export const importCommand = defineCommand({
+  description: "Import variables from stdin (.env format)",
+  options: {
+    project: projectOption,
+    environment: environmentOption,
+    merge: defineOption({
+      name: "merge",
+      schema: z.boolean().default(false),
+      description: "Merge with existing variables instead of replacing",
+      aliases: ["m"],
+    }),
+  },
+  async handler(options) {
+    const storage = getStorage();
+    const project = options.project ?? basename(await realpath(process.cwd()));
+
+    const input = await readStdin();
+    const newVars = parseEnv(input) as Record<string, string>;
+
+    let existingVars: Record<string, string>;
+    try {
+      const projectData = await storage.getProject(project);
+      existingVars = projectData[options.environment] ?? {};
+    } catch (error) {
+      if (error instanceof ProjectNotFoundError) {
+        existingVars = {};
+      } else {
+        throw error;
+      }
+    }
+
+    const added: Array<string> = [];
+    const updated: Array<string> = [];
+    const removed: Array<string> = [];
+
+    if (options.merge) {
+      // Merge mode: add/overwrite without clearing
+      for (const key of Object.keys(newVars)) {
+        if (key in existingVars) {
+          if (existingVars[key] !== newVars[key]) {
+            updated.push(key);
+          }
+        } else {
+          added.push(key);
+        }
+      }
+      await storage.setVariables(project, options.environment, { ...existingVars, ...newVars });
+    } else {
+      // Replace mode: clear then set
+      for (const key of Object.keys(newVars)) {
+        if (key in existingVars) {
+          if (existingVars[key] !== newVars[key]) {
+            updated.push(key);
+          }
+        } else {
+          added.push(key);
+        }
+      }
+      for (const key of Object.keys(existingVars)) {
+        if (!(key in newVars)) {
+          removed.push(key);
+        }
+      }
+      await storage.setVariables(project, options.environment, newVars);
+    }
+
+    for (const key of added) {
+      console.error(`+ ${key} (added)`);
+    }
+    for (const key of updated) {
+      console.error(`~ ${key} (updated)`);
+    }
+    for (const key of removed) {
+      console.error(`- ${key} (removed)`);
+    }
+
+    const totalVars = Object.keys(newVars).length;
+    console.error(
+      `Imported ${totalVars} variable${totalVars !== 1 ? "s" : ""} into ${project} [${options.environment}]`,
+    );
+  },
+});
+
+async function readStdin(): Promise<string> {
+  const chunks: Array<Buffer> = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}

package/src/commands/init.command.ts

@@ -0,0 +1,11 @@
+import { defineCommand } from "../lib/define-command.ts";
+import { getStorage } from "../lib/get-storage.ts";
+
+export const initCommand = defineCommand({
+  description: "Initialize the storage backend",
+  async handler() {
+    const storage = getStorage();
+    await storage.init();
+    console.log("Storage initialized.");
+  },
+});

package/src/commands/list.command.ts

@@ -0,0 +1,47 @@
+import { defineCommand } from "../lib/define-command.ts";
+import { getStorage } from "../lib/get-storage.ts";
+import { projectOption } from "../options/project.option.ts";
+import { ProjectNotFoundError } from "../lib/storage.ts";
+
+export const listCommand = defineCommand({
+  description: "List projects and their environments",
+  options: {
+    project: projectOption,
+  },
+  async handler(options) {
+    const storage = getStorage();
+
+    if (options.project !== undefined) {
+      let projectData: Record<string, Record<string, string>>;
+      try {
+        projectData = await storage.getProject(options.project);
+      } catch (error) {
+        if (error instanceof ProjectNotFoundError) {
+          throw new Error(`Project not found: ${options.project}`);
+        }
+        throw error;
+      }
+      for (const [env, vars] of Object.entries(projectData)) {
+        const count = Object.keys(vars).length;
+        console.log(`${env} (${count} variable${count !== 1 ? "s" : ""})`);
+      }
+      return;
+    }
+
+    const projects = await storage.getProjects();
+
+    if (projects.length === 0) {
+      console.log("No projects found.");
+      return;
+    }
+
+    for (const p of projects) {
+      console.log(p);
+      const projectData = await storage.getProject(p);
+      for (const [env, vars] of Object.entries(projectData)) {
+        const count = Object.keys(vars).length;
+        console.log(`  ${env} (${count} variable${count !== 1 ? "s" : ""})`);
+      }
+    }
+  },
+});

package/src/commands/load.command.ts

@@ -0,0 +1,32 @@
+import { basename } from "node:path";
+import { realpath } from "node:fs/promises";
+import { defineCommand } from "../lib/define-command.ts";
+import { getStorage } from "../lib/get-storage.ts";
+import { detectShell, formatVariables } from "../lib/shell.ts";
+import { EnvironmentNotFoundError } from "../lib/storage.ts";
+import { environmentOption } from "../options/environment.option.ts";
+import { projectOption } from "../options/project.option.ts";
+
+export const loadCommand = defineCommand({
+  description: "Load variables into the current shell environment",
+  options: {
+    project: projectOption,
+    environment: environmentOption,
+  },
+  async handler(options) {
+    const storage = getStorage();
+    const project = options.project ?? basename(await realpath(process.cwd()));
+
+    const projectData = await storage.getProject(project);
+    const vars = projectData[options.environment];
+    if (vars === undefined) {
+      throw new EnvironmentNotFoundError(project, options.environment);
+    }
+
+    const shell = detectShell();
+    const output = formatVariables(shell, vars);
+    if (output !== "") {
+      console.log(output);
+    }
+  },
+});

package/src/commands/unload.command.ts

@@ -0,0 +1,32 @@
+import { basename } from "node:path";
+import { realpath } from "node:fs/promises";
+import { defineCommand } from "../lib/define-command.ts";
+import { getStorage } from "../lib/get-storage.ts";
+import { detectShell, formatUnsetVariables } from "../lib/shell.ts";
+import { EnvironmentNotFoundError } from "../lib/storage.ts";
+import { environmentOption } from "../options/environment.option.ts";
+import { projectOption } from "../options/project.option.ts";
+
+export const unloadCommand = defineCommand({
+  description: "Unload variables from the current shell environment",
+  options: {
+    project: projectOption,
+    environment: environmentOption,
+  },
+  async handler(options) {
+    const storage = getStorage();
+    const project = options.project ?? basename(await realpath(process.cwd()));
+
+    const projectData = await storage.getProject(project);
+    const vars = projectData[options.environment];
+    if (vars === undefined) {
+      throw new EnvironmentNotFoundError(project, options.environment);
+    }
+
+    const shell = detectShell();
+    const output = formatUnsetVariables(shell, Object.keys(vars));
+    if (output !== "") {
+      console.log(output);
+    }
+  },
+});

package/src/lib/define-argument.ts

@@ -0,0 +1,13 @@
+import type { z } from "zod";
+
+export interface ArgumentDefinition<S extends z.ZodType = z.ZodType> {
+  schema: S;
+  description: string;
+  placeholder: string;
+}
+
+export function defineArgument<S extends z.ZodType>(
+  definition: ArgumentDefinition<S>,
+): ArgumentDefinition<S> {
+  return definition;
+}

package/src/lib/define-command.ts

@@ -0,0 +1,43 @@
+import type { z } from "zod";
+import type { ArgumentDefinition } from "./define-argument.ts";
+import type { OptionDefinition } from "./define-option.ts";
+
+type OptionsRecord = Record<string, OptionDefinition>;
+type ArgumentsArray = readonly ArgumentDefinition[];
+
+type InferOptionsType<O> = O extends OptionsRecord
+  ? { [K in keyof O]: z.infer<O[K]["schema"]> }
+  : Record<string, never>;
+
+type InferArgsType<A extends ArgumentsArray> = {
+  [K in keyof A]: A[K] extends ArgumentDefinition ? z.infer<A[K]["schema"]> : never;
+};
+
+type CommandHandler<O, A> = A extends ArgumentsArray
+  ? (options: InferOptionsType<O>, ...args: InferArgsType<A>) => void | Promise<void>
+  : (options: InferOptionsType<O>) => void | Promise<void>;
+
+export interface CommandDefinition<
+  O extends OptionsRecord | undefined = OptionsRecord,
+  A extends ArgumentsArray | undefined = ArgumentsArray,
+> {
+  description: string;
+  options?: O | undefined;
+  args?: A | undefined;
+  handler: CommandHandler<O, A>;
+}
+
+/** Type-erased command definition for use in registries. */
+export interface AnyCommandDefinition {
+  description: string;
+  options?: OptionsRecord | undefined;
+  args?: ArgumentsArray | undefined;
+  handler: (options: any, ...args: any[]) => void | Promise<void>;
+}
+
+export function defineCommand<
+  O extends OptionsRecord | undefined = undefined,
+  A extends ArgumentsArray | undefined = undefined,
+>(definition: CommandDefinition<O, A>): CommandDefinition<O, A> {
+  return definition;
+}

package/src/lib/define-option.ts

@@ -0,0 +1,15 @@
+import type { z } from "zod";
+
+export interface OptionDefinition<S extends z.ZodType = z.ZodType> {
+  name: string;
+  schema: S;
+  description: string;
+  aliases?: Array<string>;
+  placeholder?: string;
+}
+
+export function defineOption<S extends z.ZodType>(
+  definition: OptionDefinition<S>,
+): OptionDefinition<S> {
+  return definition;
+}

package/src/lib/format.ts

@@ -0,0 +1,108 @@
+import { styleText } from "node:util";
+import type { z } from "zod";
+import type { ArgumentDefinition } from "./define-argument.ts";
+import type { AnyCommandDefinition } from "./define-command.ts";
+import type { OptionDefinition } from "./define-option.ts";
+import { getDefault, isBoolean, isRequired } from "./zod-utils.ts";
+
+export function formatGlobalHelp(toolName: string, commands: Record<string, AnyCommandDefinition>) {
+  const names = Object.keys(commands);
+
+  const sections: Array<string> = [styleText("bold", "USAGE"), `  ${toolName} <command> [options]`];
+
+  if (names.length > 0) {
+    const longest = Math.max(...names.map((n) => n.length));
+    const commandList = names
+      .map((name) => `  ${name.padEnd(longest)}  ${commands[name]!.description}`)
+      .join("\n");
+    sections.push("", styleText("bold", "COMMANDS"), commandList);
+  }
+
+  return sections.join("\n");
+}
+
+export function formatCommandHelp(
+  toolName: string,
+  commandName: string,
+  command: AnyCommandDefinition,
+) {
+  const sections: Array<string> = [
+    styleText("bold", "USAGE"),
+    formatUsageLine(toolName, commandName, command),
+  ];
+
+  const argList = formatArgList(command.args ?? []);
+  if (argList !== null) {
+    sections.push("", styleText("bold", "ARGUMENTS"), argList);
+  }
+
+  const optionList = formatOptionList(command.options ?? {});
+  if (optionList !== null) {
+    sections.push("", styleText("bold", "OPTIONS"), optionList);
+  }
+
+  return sections.join("\n");
+}
+
+function formatUsageLine(toolName: string, commandName: string, command: AnyCommandDefinition) {
+  const argPlaceholders = (command.args ?? []).map((a) => `<${a.placeholder}>`).join(" ");
+  const parts = [toolName, commandName];
+  if (argPlaceholders !== "") parts.push(argPlaceholders);
+  parts.push("[options]");
+  return `  ${parts.join(" ")}`;
+}
+
+function formatArgList(args: readonly ArgumentDefinition[]) {
+  if (args.length === 0) return null;
+
+  const lines = args.map((arg) => ({
+    left: `  ${arg.placeholder}`,
+    description: formatArgDescription(arg.description, arg.schema),
+  }));
+
+  const longest = Math.max(...lines.map((l) => l.left.length));
+  return lines.map((l) => `${l.left.padEnd(longest)}  ${l.description}`).join("\n");
+}
+
+function formatOptionList(options: Record<string, OptionDefinition>) {
+  const entries = Object.values(options);
+  if (entries.length === 0) return null;
+
+  const aliasPrefixes = entries.map((opt) => {
+    const aliases = opt.aliases ?? [];
+    return aliases.length > 0 ? aliases.map((a) => `-${a}`).join(", ") + ", " : "";
+  });
+  const longestAlias = Math.max(...aliasPrefixes.map((p) => p.length));
+
+  const lines = entries.map((opt, i) => {
+    const aliasPrefix = aliasPrefixes[i]!.padStart(longestAlias);
+    const placeholder = opt.placeholder ?? opt.name;
+    const flag = isBoolean(opt.schema) ? `--${opt.name}` : `--${opt.name} <${placeholder}>`;
+    return {
+      left: `  ${aliasPrefix}${flag}`,
+      description: formatDescription(opt.description, opt.schema),
+    };
+  });
+
+  const longest = Math.max(...lines.map((l) => l.left.length));
+  return lines.map((l) => `${l.left.padEnd(longest)}  ${l.description}`).join("\n");
+}
+
+function formatArgDescription(description: string, schema: z.ZodType): string {
+  const defaultValue = getDefault(schema);
+  if (defaultValue !== undefined) return `${description} (default: ${String(defaultValue)})`;
+  return isRequired(schema) ? description : `${description} (optional)`;
+}
+
+function formatDescription(description: string, schema: z.ZodType): string {
+  if (isRequired(schema)) return `${description} (required)`;
+  const defaultValue = getDefault(schema);
+  return defaultValue === undefined
+    ? description
+    : `${description} (default: ${String(defaultValue)})`;
+}
+
+export function formatErrors(errors: Array<string>) {
+  const errorLines = errors.map((e) => `  ${e}`).join("\n");
+  return `${styleText("bold", "ERRORS")}\n${errorLines}`;
+}

package/src/lib/get-storage.ts

@@ -0,0 +1,11 @@
+import { JsonStorage } from "./json-storage.ts";
+import { OnePasswordStorage } from "./one-password-storage.ts";
+import type { Storage } from "./storage.ts";
+
+export function getStorage(): Storage {
+  const storagePath = process.env.LECOFFRE_STORAGE_PATH;
+  if (storagePath !== undefined) {
+    return new JsonStorage(storagePath);
+  }
+  return new OnePasswordStorage();
+}

package/src/lib/json-storage.ts

@@ -0,0 +1,74 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { ProjectNotFoundError, Storage } from "./storage.ts";
+
+type StoreData = Record<string, Record<string, Record<string, string>>>;
+
+export class JsonStorage extends Storage {
+  private readonly filePath: string;
+
+  constructor(filePath: string) {
+    super();
+    this.filePath = filePath;
+  }
+
+  private async read(): Promise<StoreData> {
+    try {
+      const content = await readFile(this.filePath, "utf-8");
+      return JSON.parse(content) as StoreData;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        return {};
+      }
+      throw error;
+    }
+  }
+
+  private async write(data: StoreData): Promise<void> {
+    await writeFile(this.filePath, JSON.stringify(data, null, 2) + "\n");
+  }
+
+  async getProjects(): Promise<Array<string>> {
+    const data = await this.read();
+    return Object.keys(data);
+  }
+
+  async getProject(project: string): Promise<Record<string, Record<string, string>>> {
+    const data = await this.read();
+    const projectData = data[project];
+    if (projectData === undefined) {
+      throw new ProjectNotFoundError(project);
+    }
+    return Object.fromEntries(Object.entries(projectData).map(([env, vars]) => [env, { ...vars }]));
+  }
+
+  async init(): Promise<void> {
+    // No initialization needed for JSON storage
+  }
+
+  async setVariables(project: string, env: string, vars: Record<string, string>): Promise<void> {
+    const data = await this.read();
+    if (data[project] === undefined) {
+      data[project] = {};
+    }
+    data[project][env] = vars;
+    await this.write(data);
+  }
+
+  async deleteEnvironment(project: string, env: string): Promise<void> {
+    const data = await this.read();
+    const projectData = data[project];
+    if (projectData !== undefined) {
+      delete projectData[env];
+      if (Object.keys(projectData).length === 0) {
+        delete data[project];
+      }
+      await this.write(data);
+    }
+  }
+
+  async deleteProject(project: string): Promise<void> {
+    const data = await this.read();
+    delete data[project];
+    await this.write(data);
+  }
+}

package/src/lib/one-password-storage.ts

@@ -0,0 +1,233 @@
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import { ProjectNotFoundError, Storage, StorageNotInitializedError } from "./storage.ts";
+
+interface OpItemSummary {
+  id: string;
+  title: string;
+  category: string;
+}
+
+interface OpField {
+  id: string;
+  label: string;
+  value: string;
+  type: string;
+  section?: { id: string; label: string };
+  purpose?: string;
+}
+
+interface OpItemDetail {
+  id: string;
+  title: string;
+  fields: Array<OpField>;
+}
+
+interface ExecError {
+  stderr?: string;
+}
+
+function hasStderr(error: unknown): error is ExecError {
+  return typeof error === "object" && error !== null && "stderr" in error;
+}
+
+function getStderr(error: unknown): string {
+  return hasStderr(error) ? (error.stderr?.trim() ?? "") : "";
+}
+
+function isItemNotFound(error: unknown): boolean {
+  return /isn't an item/i.test(getStderr(error));
+}
+
+function isVaultNotFound(error: unknown): boolean {
+  return /isn't a vault/i.test(getStderr(error));
+}
+
+const execFile = promisify(execFileCb);
+
+async function execOp(...args: Array<string>): Promise<string> {
+  try {
+    const { stdout } = await execFile("op", args);
+    return stdout;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error(
+        "1Password CLI (op) is not installed. See https://developer.1password.com/docs/cli/get-started/",
+      );
+    }
+    throw error;
+  }
+}
+
+const VAULT = "lecoffre";
+
+export class OnePasswordStorage extends Storage {
+  private readonly vault: string;
+
+  constructor(vault: string = VAULT) {
+    super();
+    this.vault = vault;
+  }
+
+  private rethrow(error: unknown): never {
+    if (isVaultNotFound(error)) {
+      throw new StorageNotInitializedError(
+        `Vault "${this.vault}" not found. Run "lecoffre init" to create it.`,
+      );
+    }
+    const stderr = getStderr(error);
+    if (stderr !== "") {
+      throw new Error(stderr);
+    }
+    throw error;
+  }
+
+  async init(): Promise<void> {
+    try {
+      await execOp("vault", "get", this.vault, "--format", "json");
+    } catch (error) {
+      if (isVaultNotFound(error)) {
+        await execOp("vault", "create", this.vault);
+        return;
+      }
+      throw error;
+    }
+  }
+
+  private async getItem(project: string): Promise<OpItemDetail | null> {
+    try {
+      const stdout = await execOp(
+        "item",
+        "get",
+        project,
+        "--vault",
+        this.vault,
+        "--format",
+        "json",
+      );
+      return JSON.parse(stdout) as OpItemDetail;
+    } catch (error) {
+      if (isItemNotFound(error)) return null;
+      return this.rethrow(error);
+    }
+  }
+
+  /**
+   * Return only user-defined fields. 1Password items include system fields
+   * (e.g. "notesPlain") that have a `purpose` property set. User-created
+   * fields never have `purpose`, so we use that to distinguish them.
+   */
+  private getUserFields(fields: Array<OpField>): Array<OpField> {
+    return fields.filter(
+      (field) => field.purpose === undefined && field.section?.label !== undefined,
+    );
+  }
+
+  async getProjects(): Promise<Array<string>> {
+    try {
+      const stdout = await execOp("item", "list", "--vault", this.vault, "--format", "json");
+      const items = JSON.parse(stdout) as Array<OpItemSummary>;
+      return items.map((item) => item.title);
+    } catch (error) {
+      return this.rethrow(error);
+    }
+  }
+
+  async getProject(project: string): Promise<Record<string, Record<string, string>>> {
+    const item = await this.getItem(project);
+    if (item === null) {
+      throw new ProjectNotFoundError(project);
+    }
+
+    const envs: Record<string, Record<string, string>> = {};
+    for (const field of this.getUserFields(item.fields)) {
+      const sectionLabel = field.section?.label;
+      if (sectionLabel !== undefined) {
+        envs[sectionLabel] ??= {};
+        envs[sectionLabel][field.label] = field.value;
+      }
+    }
+    return envs;
+  }
+
+  // Note: field values are passed as process arguments and are briefly visible
+  // in /proc/<pid>/cmdline. The 1Password CLI does not support reading field
+  // values from stdin when spawned as a child process (only shell pipes work).
+  async setVariables(project: string, env: string, vars: Record<string, string>): Promise<void> {
+    const item = await this.getItem(project);
+
+    if (item === null) {
+      const fieldAssignments = Object.entries(vars).map(
+        ([key, value]) => `${env}.${key}[concealed]=${value}`,
+      );
+      await execOp(
+        "item",
+        "create",
+        "--vault",
+        this.vault,
+        "--category",
+        "Secure Note",
+        "--title",
+        project,
+        ...fieldAssignments,
+      );
+      return;
+    }
+
+    const operations: Array<string> = [];
+
+    for (const field of this.getUserFields(item.fields)) {
+      if (field.section?.label === env) {
+        operations.push(`${env}.${field.label}[delete]`);
+      }
+    }
+
+    for (const [key, value] of Object.entries(vars)) {
+      operations.push(`${env}.${key}[concealed]=${value}`);
+    }
+
+    if (operations.length > 0) {
+      await execOp("item", "edit", project, "--vault", this.vault, ...operations);
+    }
+  }
+
+  async deleteEnvironment(project: string, env: string): Promise<void> {
+    const item = await this.getItem(project);
+    if (item === null) {
+      return;
+    }
+
+    const userFields = this.getUserFields(item.fields);
+    const sections = new Set<string>();
+    const fieldsToDelete: Array<string> = [];
+
+    for (const field of userFields) {
+      if (field.section?.label !== undefined) {
+        sections.add(field.section.label);
+      }
+      if (field.section?.label === env) {
+        fieldsToDelete.push(`${env}.${field.label}[delete]`);
+      }
+    }
+
+    if (fieldsToDelete.length === 0) {
+      return;
+    }
+
+    if (sections.size <= 1 && sections.has(env)) {
+      await execOp("item", "delete", project, "--vault", this.vault);
+      return;
+    }
+
+    await execOp("item", "edit", project, "--vault", this.vault, ...fieldsToDelete);
+  }
+
+  async deleteProject(project: string): Promise<void> {
+    try {
+      await execOp("item", "delete", project, "--vault", this.vault);
+    } catch (error) {
+      if (isItemNotFound(error)) return;
+      this.rethrow(error);
+    }
+  }
+}

package/src/lib/parse-command.ts

@@ -0,0 +1,108 @@
+import { parse } from "@bomb.sh/args";
+import { ZodError } from "zod";
+import type { AnyCommandDefinition } from "./define-command.ts";
+import type { OptionDefinition } from "./define-option.ts";
+import { isBoolean } from "./zod-utils.ts";
+
+export class CommandValidationError extends Error {
+  errors: Array<string>;
+
+  constructor(errors: Array<string>) {
+    super(errors.join("\n"));
+    this.errors = errors;
+  }
+}
+
+export class CommandHelpRequested extends Error {
+  constructor() {
+    super("Help requested");
+  }
+}
+
+export function parseCommand(
+  argv: Array<string>,
+  command: AnyCommandDefinition,
+): { options: Record<string, unknown>; args: Array<unknown> } {
+  const commandOptions = command.options ?? {};
+  const commandArgs = command.args ?? [];
+
+  const parseOpts = buildParseOptions(commandOptions);
+  const raw = parse(argv, parseOpts);
+
+  if (raw["help"]) {
+    throw new CommandHelpRequested();
+  }
+
+  const errors: Array<string> = [];
+
+  const options: Record<string, unknown> = {};
+  for (const [key, opt] of Object.entries(commandOptions)) {
+    const rawValue = raw[opt.name] as unknown;
+    try {
+      if (rawValue !== undefined) {
+        options[key] = opt.schema.parse(rawValue);
+      } else {
+        options[key] = opt.schema.parse(undefined);
+      }
+    } catch (error) {
+      if (error instanceof ZodError) {
+        for (const issue of error.issues) {
+          errors.push(`option "--${opt.name}": ${issue.message}`);
+        }
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  const args: Array<unknown> = [];
+  for (let i = 0; i < commandArgs.length; i++) {
+    const argDef = commandArgs[i]!;
+    const rawValue = raw._[i];
+    try {
+      if (rawValue !== undefined) {
+        args.push(argDef.schema.parse(String(rawValue)));
+      } else {
+        args.push(argDef.schema.parse(undefined));
+      }
+    } catch (error) {
+      if (error instanceof ZodError) {
+        for (const issue of error.issues) {
+          errors.push(`argument <${argDef.placeholder}>: ${issue.message}`);
+        }
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new CommandValidationError(errors);
+  }
+
+  return { options, args };
+}
+
+function buildParseOptions(options: Record<string, OptionDefinition>) {
+  const boolean: Array<string> = [];
+  const string: Array<string> = [];
+  const alias: Record<string, string> = {};
+
+  for (const opt of Object.values(options)) {
+    if (isBoolean(opt.schema)) {
+      boolean.push(opt.name);
+    } else {
+      string.push(opt.name);
+    }
+    if (opt.aliases !== undefined) {
+      for (const a of opt.aliases) {
+        alias[a] = opt.name;
+      }
+    }
+  }
+
+  boolean.push("help");
+  alias["h"] = "help";
+
+  return { boolean, string, alias };
+}

package/src/lib/shell.ts

@@ -0,0 +1,52 @@
+import { execFileSync } from "node:child_process";
+import { basename } from "node:path";
+
+const SUPPORTED_SHELLS = ["bash", "zsh", "fish"] as const;
+
+export type ShellName = (typeof SUPPORTED_SHELLS)[number];
+
+function isSupportedShell(name: string): name is ShellName {
+  return (SUPPORTED_SHELLS as ReadonlyArray<string>).includes(name);
+}
+
+export function detectShell(): ShellName {
+  const name = basename(
+    execFileSync("ps", ["-p", String(process.ppid), "-o", "comm="], { encoding: "utf-8" }).trim(),
+  );
+  if (isSupportedShell(name)) {
+    return name;
+  }
+  throw new Error(`Unsupported shell: ${name}`);
+}
+
+export function formatVariables(shell: ShellName, vars: Record<string, string>): string {
+  const lines = Object.entries(vars).map(([key, value]) => formatSingleVariable(shell, key, value));
+  return lines.join("\n");
+}
+
+function formatSingleVariable(shell: ShellName, key: string, value: string): string {
+  if (shell === "fish") {
+    return `set -gx ${key} '${escapeSingleQuotes(value, "fish")}'`;
+  }
+  return `export ${key}='${escapeSingleQuotes(value, "posix")}'`;
+}
+
+export function formatUnsetVariables(shell: ShellName, keys: Array<string>): string {
+  const lines = keys.map((key) => formatSingleUnsetVariable(shell, key));
+  return lines.join("\n");
+}
+
+function formatSingleUnsetVariable(shell: ShellName, key: string): string {
+  if (shell === "fish") {
+    return `set -e ${key}`;
+  }
+  return `unset ${key}`;
+}
+
+function escapeSingleQuotes(value: string, mode: "posix" | "fish"): string {
+  if (mode === "fish") {
+    return value.replaceAll("\\", "\\\\").replaceAll("'", "\\'");
+  }
+  // In POSIX shells: end quote, escaped quote, restart quote
+  return value.replaceAll("'", "'\\''");
+}

package/src/lib/storage.ts

@@ -0,0 +1,37 @@
+export class ProjectNotFoundError extends Error {
+  readonly project: string;
+
+  constructor(project: string) {
+    super(`Project not found: ${project}`);
+    this.name = "ProjectNotFoundError";
+    this.project = project;
+  }
+}
+
+export class EnvironmentNotFoundError extends Error {
+  readonly project: string;
+  readonly environment: string;
+
+  constructor(project: string, environment: string) {
+    super(`Environment not found: ${environment}`);
+    this.name = "EnvironmentNotFoundError";
+    this.project = project;
+    this.environment = environment;
+  }
+}
+
+export class StorageNotInitializedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StorageNotInitializedError";
+  }
+}
+
+export abstract class Storage {
+  abstract init(): Promise<void>;
+  abstract getProjects(): Promise<Array<string>>;
+  abstract getProject(project: string): Promise<Record<string, Record<string, string>>>;
+  abstract setVariables(project: string, env: string, vars: Record<string, string>): Promise<void>;
+  abstract deleteEnvironment(project: string, env: string): Promise<void>;
+  abstract deleteProject(project: string): Promise<void>;
+}

package/src/lib/zod-utils.ts

@@ -0,0 +1,50 @@
+import type { z } from "zod";
+
+interface ZodDef {
+  type?: string;
+  innerType?: z.ZodType;
+  defaultValue?: unknown;
+  in?: z.ZodType;
+}
+
+function getDef(schema: z.ZodType): ZodDef {
+  return (schema as unknown as { _zod: { def: ZodDef } })._zod.def;
+}
+
+export function isBoolean(schema: z.ZodType): boolean {
+  const def = getDef(schema);
+  if (def.type === "boolean") return true;
+  if (def.type === "default" || def.type === "optional" || def.type === "nullable") {
+    if (def.innerType !== undefined) return isBoolean(def.innerType);
+  }
+  return false;
+}
+
+export function isRequired(schema: z.ZodType): boolean {
+  const def = getDef(schema);
+  if (def.type === "default" || def.type === "optional" || def.type === "nullable") {
+    return false;
+  }
+  if (def.type === "pipe" && def.in !== undefined) {
+    return isRequired(def.in);
+  }
+  return true;
+}
+
+export function getDefault(schema: z.ZodType): unknown {
+  let current: z.ZodType | undefined = schema;
+  while (current !== undefined) {
+    const def = getDef(current);
+    if (def.type === "default") return def.defaultValue;
+    if (def.type === "optional" || def.type === "nullable") {
+      current = def.innerType;
+      continue;
+    }
+    if (def.type === "pipe") {
+      current = def.in;
+      continue;
+    }
+    break;
+  }
+  return undefined;
+}

package/src/options/environment.option.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { defineOption } from "../lib/define-option.ts";
+
+export const environmentOption = defineOption({
+  name: "environment",
+  schema: z.string().default("default"),
+  description: "Environment name",
+  aliases: ["e"],
+  placeholder: "env",
+});

package/src/options/project.option.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { defineOption } from "../lib/define-option.ts";
+
+export const projectOption = defineOption({
+  name: "project",
+  schema: z
+    .string()
+    .refine((val) => !val.startsWith("-"), { message: 'must not start with "-"' })
+    .optional(),
+  description: "Project name",
+  aliases: ["p"],
+  placeholder: "name",
+});