@ai-agent-tools/picgen 0.1.0-alpha.3 → 0.1.0-alpha.4

package/README.md

@@ -91,6 +91,14 @@ OPENAI_API_KEY=...
 GEMINI_API_KEY=...
 ```
 
+For non-technical users, `picgen setup` can save API keys for you in:
+
+```text
+~/.picgen/.env
+```
+
+PicGen loads this managed env file automatically. Shell environment variables take priority, and a project `.env` can override the managed file for local testing.
+
 You can start from the included example:
 
 ```bash

package/dist/cli.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import "dotenv/config";
 import { Command } from "commander";
 
 // src/commands/create.ts
@@ -1055,7 +1054,7 @@ import { homedir as homedir2 } from "os";
 
 // src/version.ts
 var PACKAGE_NAME = "@ai-agent-tools/picgen";
-var VERSION = "0.1.0-alpha.3";
+var VERSION = "0.1.0-alpha.4";
 
 // src/commands/update.ts
 var UPDATE_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
@@ -1525,7 +1524,7 @@ function formatQuickstart() {
     "  npm install -g @ai-agent-tools/picgen",
     "",
     "Configure:",
-    "  picgen setup",
+    "  picgen setup  # can save provider API keys for you",
     "  picgen doctor --json",
     "",
     "Preview before spending quota:",
@@ -1538,10 +1537,11 @@ function formatQuickstart() {
     '  picgen create --dry-run --reference ./reference.png "\u57FA\u4E8E\u53C2\u8003\u56FE\u751F\u6210\u4E00\u5F20\u54C1\u724C\u6D77\u62A5"',
     "",
     "Agent prompt:",
-    "  \u8BF7\u5B89\u88C5\u5E76\u4F53\u9A8C @ai-agent-tools/picgen\uFF1A\u5168\u5C40\u5B89\u88C5 npm install -g @ai-agent-tools/picgen\uFF0C\u8FD0\u884C picgen setup \u914D\u7F6E\uFF0C\u7136\u540E\u5148 dry-run \u9884\u89C8\uFF0C\u518D\u786E\u8BA4\u751F\u6210\u4E00\u5F20\u6D4B\u8BD5\u56FE\u3002\u5982\u679C\u6211\u8981\u7528\u53C2\u8003\u56FE\uFF0C\u8BF7\u4F7F\u7528 --reference <\u56FE\u7247\u8DEF\u5F84>\u3002",
+    "  \u8BF7\u5B89\u88C5\u5E76\u4F53\u9A8C @ai-agent-tools/picgen\uFF1A\u5168\u5C40\u5B89\u88C5 npm install -g @ai-agent-tools/picgen\uFF0C\u8FD0\u884C picgen setup \u5F15\u5BFC\u6211\u914D\u7F6E provider \u548C API key\uFF0C\u7136\u540E\u5148 dry-run \u9884\u89C8\uFF0C\u518D\u786E\u8BA4\u751F\u6210\u4E00\u5F20\u6D4B\u8BD5\u56FE\u3002\u5982\u679C\u6211\u8981\u7528\u53C2\u8003\u56FE\uFF0C\u8BF7\u4F7F\u7528 --reference <\u56FE\u7247\u8DEF\u5F84>\u3002",
     "",
     "Notes:",
     "  - Provider host URLs should not include /v1 or /v1beta.",
+    "  - picgen setup can store API keys in ~/.picgen/.env.",
     "  - Agent workflows should dry-run before real generation.",
     "  - Generated images are saved locally; do not paste base64 into chat.",
     "  - First-user rollout checklist: docs/release-alpha.md"
@@ -1549,7 +1549,62 @@ function formatQuickstart() {
 }
 
 // src/commands/setup.ts
-import { confirm as confirm2, input as input2, select as select2 } from "@inquirer/prompts";
+import { confirm as confirm2, input as input2, password, select as select2 } from "@inquirer/prompts";
+
+// src/config/env.ts
+import { chmod, mkdir as mkdir4, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
+import { existsSync } from "fs";
+import { dirname as dirname3, join as join5, resolve as resolve2 } from "path";
+import { homedir as homedir3 } from "os";
+import { parse } from "dotenv";
+function getManagedEnvPath() {
+  return process.env.PICGEN_ENV_PATH ?? join5(homedir3(), ".picgen", ".env");
+}
+async function loadPicgenEnv() {
+  const shellEnv = new Set(Object.keys(process.env));
+  await loadEnvFile(getManagedEnvPath(), shellEnv, false);
+  await loadEnvFile(resolve2(process.cwd(), ".env"), shellEnv, true);
+}
+async function saveManagedEnvVar(name, value) {
+  const path = getManagedEnvPath();
+  const current = await readManagedEnvFile(path);
+  const next = {
+    ...current,
+    [name]: value
+  };
+  await mkdir4(dirname3(path), { recursive: true });
+  await writeFile4(path, stringifyEnv(next), "utf8");
+  await chmod(path, 384);
+  process.env[name] = value;
+  return path;
+}
+async function loadEnvFile(path, shellEnv, overrideManagedValues) {
+  if (!existsSync(path)) return;
+  const parsed = parse(await readFile4(path, "utf8"));
+  for (const [name, value] of Object.entries(parsed)) {
+    if (shellEnv.has(name)) continue;
+    if (!overrideManagedValues && process.env[name] !== void 0) continue;
+    process.env[name] = value;
+  }
+}
+async function readManagedEnvFile(path) {
+  try {
+    return parse(await readFile4(path, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw error;
+  }
+}
+function stringifyEnv(values) {
+  return `${Object.entries(values).map(([name, value]) => `${name}=${quoteEnvValue(value)}`).join("\n")}
+`;
+}
+function quoteEnvValue(value) {
+  if (/^[A-Za-z0-9_./:@+-]+$/.test(value)) return value;
+  return JSON.stringify(value);
+}
+
+// src/commands/setup.ts
 async function runSetup() {
   await ensureConfig();
   console.log(`PicGen config: ${getConfigPath()}`);
@@ -1564,6 +1619,7 @@ async function runSetup() {
         { name: "Quick add a common provider/channel", value: "quick-add" },
         { name: "Choose default provider/channel", value: "provider" },
         { name: "Choose generation preference", value: "mode" },
+        { name: "Configure API key", value: "key" },
         { name: "Test a provider", value: "test" },
         { name: "Advanced: add a custom provider/channel", value: "add" },
         { name: "Finish setup", value: "done" }
@@ -1575,6 +1631,8 @@ async function runSetup() {
       await chooseDefaultProvider();
     } else if (action === "mode") {
       await chooseDefaultMode();
+    } else if (action === "key") {
+      await chooseProviderKeyToConfigure();
     } else if (action === "test") {
       await chooseProviderToTest();
     } else if (action === "add") {
@@ -1593,7 +1651,7 @@ async function printSetupSummary() {
   for (const [providerName, provider2] of Object.entries(config.providers)) {
     const preference = providerName === config.routing.default_provider ? "default" : config.routing.fallback_providers.includes(providerName) ? "fallback" : "manual";
     console.log(
-      `- ${providerName}: ${provider2.enabled ? "enabled" : "disabled"}, ${preference}, ${providerLabel(provider2)}, capabilities=${provider2.capabilities.join(",")}`
+      `- ${providerName}: ${provider2.enabled ? "enabled" : "disabled"}, ${preference}, ${providerLabel(provider2)}, key=${provider2.api_key_env}${process.env[provider2.api_key_env] ? " set" : " missing"}, capabilities=${provider2.capabilities.join(",")}`
     );
   }
 }
@@ -1641,6 +1699,18 @@ async function chooseProviderToTest() {
   if (result.model) console.log(`Model: ${result.model}`);
   if (result.http_status) console.log(`HTTP status: ${result.http_status}`);
 }
+async function chooseProviderKeyToConfigure() {
+  const config = await loadConfig();
+  const name = await select2({
+    message: "Choose the provider key to configure",
+    default: config.routing.default_provider,
+    choices: Object.entries(config.providers).map(([providerName, provider2]) => ({
+      name: `${providerName} (${provider2.api_key_env}${process.env[provider2.api_key_env] ? ", currently set" : ", missing"})`,
+      value: providerName
+    }))
+  });
+  await configureProviderApiKey(config.providers[name]);
+}
 async function quickAddProvider() {
   const config = await loadConfig();
   const template = await select2({
@@ -1700,7 +1770,27 @@ async function quickAddProvider() {
   }
   await saveConfig(config);
   console.log(`Added provider: ${name}`);
-  console.log(`Set ${apiKeyEnv} in your shell or .env before testing this provider.`);
+  await configureProviderApiKey(provider2);
+}
+async function configureProviderApiKey(provider2) {
+  if (process.env[provider2.api_key_env]) {
+    const replace = await confirm2({
+      message: `${provider2.api_key_env} is already available. Replace the saved PicGen key?`,
+      default: false
+    });
+    if (!replace) return;
+  }
+  const value = await password({
+    message: `Paste API key for ${provider2.api_key_env} (leave empty to skip)`,
+    mask: "*"
+  });
+  if (!value.trim()) {
+    console.log(`Skipped API key. You can configure it later with picgen setup.`);
+    return;
+  }
+  const path = await saveManagedEnvVar(provider2.api_key_env, value.trim());
+  console.log(`Saved ${provider2.api_key_env} to ${path}`);
+  console.log(`PicGen loads this file automatically. Advanced users can override it with shell env vars or a project .env.`);
 }
 function quickProviderDefaults(template) {
   switch (template) {
@@ -1765,6 +1855,7 @@ function modeLabel(modeName) {
 }
 
 // src/cli.ts
+await loadPicgenEnv();
 var program = new Command();
 program.name("picgen").description("Lightweight image generation connector for AI agents.").version(VERSION);
 program.command("setup").description("Run the interactive PicGen setup wizard.").action(runSetup);

package/docs/release-alpha.md

@@ -40,7 +40,17 @@ https://generativelanguage.googleapis.com
 
 Do not include `/v1` or `/v1beta`.
 
-4. Set API keys in the shell or a local `.env` file:
+4. Configure API keys:
+
+For non-technical users, prefer `picgen setup`. It can save provider API keys in PicGen's managed env file:
+
+```text
+~/.picgen/.env
+```
+
+PicGen loads this file automatically.
+
+Advanced users can still use shell environment variables or a local project `.env`:
 
 ```bash
 cp .env.example .env

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-agent-tools/picgen",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.4",
   "description": "A lightweight image generation connector for AI agents.",
   "type": "module",
   "bin": {

package/skills/picgen/SKILL.md

@@ -20,7 +20,7 @@ Never silently spend user quota. Do not send full conversation context to provid
 ## Workflow
 
 1. Run `picgen doctor --json` to check configuration.
-2. If no usable provider is configured, guide the user to run `picgen setup`.
+2. If no usable provider is configured, guide the user to run `picgen setup`. The setup wizard can configure providers and save API keys for non-technical users.
 3. Choose a preset from the user's intent, such as `poster`, `product-shot`, or `social-cover`.
 4. Run `picgen create --dry-run --preset <preset> "<prompt>"`.
 5. Present the dry-run as a user-facing generation preview. Do not expose `dry-run` as a technical term unless useful.
@@ -75,7 +75,7 @@ PicGen redacts generated image payloads and Gemini thought signatures from metad
 
 If `doctor` reports no usable provider, ask the user to run `picgen setup`.
 
-If an API key is missing, name the required environment variable.
+If an API key is missing, guide the user to run `picgen setup` and choose `Configure API key`. Name the required environment variable only when useful for debugging.
 
 If a provider is disabled, suggest enabling it or using a one-off provider override.