s3-storage-cli 0.1.3 → 0.1.4

package/README.md

@@ -12,45 +12,73 @@ Runtime requirement:
 
 - `bun` must be installed because the published CLI executes with Bun
 
+Install without global npm setup:
+
+```bash
+npx s3-storage-cli status
+```
+
 Quick start:
 
 ```bash
+s3-storage setup
 s3-storage status
 ```
 
 Commands:
 
+- `setup` prompts for required scoped config values and saves them for this CLI
 - `status` verifies env, SQLite, and S3 connectivity
 - `list` shows only objects tracked by this CLI
 - `upload` uploads one or more files or directories
 - `delete` removes tracked objects
 - `share` returns a direct public URL or a signed private URL
 
-Required env:
+Scoped config keys used by this CLI:
 
-- `S3_ENDPOINT`
-- `S3_REGION`
-- `S3_ACCESS_KEY_ID`
-- `S3_SECRET_ACCESS_KEY`
-- `S3_BUCKET`
+- `S3_STORAGE_CLI_ENDPOINT`
+- `S3_STORAGE_CLI_REGION`
+- `S3_STORAGE_CLI_ACCESS_KEY_ID`
+- `S3_STORAGE_CLI_SECRET_ACCESS_KEY`
+- `S3_STORAGE_CLI_BUCKET`
 
 Required for full readiness and public sharing:
 
-- `S3_PUBLIC_BASE_URL`
+- `S3_STORAGE_CLI_PUBLIC_BASE_URL`
 
 Optional env:
 
-- `S3_CLI_DB_PATH`
-- `S3_SHARE_TTL_SECONDS`
-- `S3_SESSION_TOKEN`
-- `S3_VIRTUAL_HOSTED_STYLE`
+- `S3_STORAGE_CLI_DB_PATH`
+- `S3_STORAGE_CLI_SHARE_TTL_SECONDS`
+- `S3_STORAGE_CLI_SESSION_TOKEN`
+- `S3_STORAGE_CLI_VIRTUAL_HOSTED_STYLE`
+- `S3_STORAGE_CLI_ENV_PATH`
+
+`setup` writes the required scoped config to the CLI-owned env file under `~/.s3-storage-cli/config.env` by default.
 
 Examples:
 
 ```bash
+s3-storage setup
 s3-storage upload ./file.txt
 s3-storage upload ./assets --public --prefix site
 s3-storage list
 s3-storage share site/assets/logo.png
 s3-storage delete site/assets/logo.png
 ```
+
+## Agent Skill
+
+This repo is also compatible with `skills.sh` style skill installers.
+
+List the skill from GitHub:
+
+```bash
+npx skills add muneebhashone/s3-storage-cli -l
+```
+
+Install the skill:
+
+```bash
+npx skills add muneebhashone/s3-storage-cli --skill s3-storage-cli
+```

package/SKILL.md

@@ -9,24 +9,28 @@ Use this repo's CLI when the task is uploading files to the configured S3-compat
 
 ## Required env
 
-- `S3_ENDPOINT`
-- `S3_REGION`
-- `S3_ACCESS_KEY_ID`
-- `S3_SECRET_ACCESS_KEY`
-- `S3_BUCKET`
+- `S3_STORAGE_CLI_ENDPOINT`
+- `S3_STORAGE_CLI_REGION`
+- `S3_STORAGE_CLI_ACCESS_KEY_ID`
+- `S3_STORAGE_CLI_SECRET_ACCESS_KEY`
+- `S3_STORAGE_CLI_BUCKET`
 
-`S3_PUBLIC_BASE_URL` is required for `status` to report fully ready and for public object sharing.
+`S3_STORAGE_CLI_PUBLIC_BASE_URL` is required for `status` to report fully ready and for public object sharing.
 
 Optional env:
 
-- `S3_CLI_DB_PATH`
-- `S3_SHARE_TTL_SECONDS`
-- `S3_SESSION_TOKEN`
-- `S3_VIRTUAL_HOSTED_STYLE`
+- `S3_STORAGE_CLI_DB_PATH`
+- `S3_STORAGE_CLI_SHARE_TTL_SECONDS`
+- `S3_STORAGE_CLI_SESSION_TOKEN`
+- `S3_STORAGE_CLI_VIRTUAL_HOSTED_STYLE`
+- `S3_STORAGE_CLI_ENV_PATH`
+
+The preferred flow is `s3-storage setup`, which prompts for the required scoped values and writes them to the CLI-owned env file.
 
 ## Commands
 
 - Install first with `npm install -g s3-storage-cli`
+- `s3-storage setup`
 - `s3-storage status`
 - `s3-storage list [prefix]`
 - `s3-storage upload <paths...> [--public|--private] [--prefix <remote-prefix>]`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s3-storage-cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Minimal tracked S3 CLI for Bun with list, upload, delete, share, and status commands.",
   "module": "index.ts",
   "type": "module",

package/src/cli.ts

@@ -1,15 +1,21 @@
-import { dirname } from "node:path";
 import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
 import { Catalog } from "./catalog";
 import {
   ensurePublicBaseUrl,
   getReadyEnvKeys,
   inspectEnv,
+  loadScopedEnv,
+  pickScopedEnv,
   requireCoreConfig,
   resolveCatalogPath,
+  resolveConfigEnvPath,
   type AppConfig,
   type EnvMap,
   type Visibility,
+  writeScopedEnvFile,
 } from "./config";
 import { resolveUploadTargets } from "./files";
 import { createDefaultIo, emitEnvCheck, emitError, emitJson, formatTimestamp, type CliIo } from "./output";
@@ -21,13 +27,20 @@ interface ParsedArgs {
   positionals: string[];
 }
 
+interface PromptLike {
+  ask: (question: string, defaultValue?: string) => Promise<string>;
+  close?: () => void | Promise<void>;
+}
+
 interface RunCliOptions {
   catalogPath?: string;
   cwd?: string;
   env?: EnvMap;
+  envFilePath?: string;
   homeDir?: string;
   io?: CliIo;
   now?: () => Date;
+  prompter?: PromptLike;
   storageFactory?: (config: AppConfig) => StorageClient;
 }
 
@@ -37,9 +50,22 @@ interface StatusCheckResult {
   ok: boolean;
 }
 
+const SETUP_QUESTIONS: Array<{ key: string; label: string }> = [
+  { key: "S3_STORAGE_CLI_ENDPOINT", label: "S3 endpoint URL" },
+  { key: "S3_STORAGE_CLI_REGION", label: "S3 region" },
+  { key: "S3_STORAGE_CLI_ACCESS_KEY_ID", label: "Access key ID" },
+  { key: "S3_STORAGE_CLI_SECRET_ACCESS_KEY", label: "Secret access key" },
+  { key: "S3_STORAGE_CLI_BUCKET", label: "Bucket name" },
+  { key: "S3_STORAGE_CLI_PUBLIC_BASE_URL", label: "Public base URL" },
+] as const;
+
 export async function runCli(argv: string[], options: RunCliOptions = {}): Promise<number> {
   const io = options.io ?? createDefaultIo();
-  const env = options.env ?? process.env;
+  const processEnv = options.env ?? process.env;
+  const env = await loadScopedEnv(processEnv, {
+    envFilePath: options.envFilePath,
+    homeDir: options.homeDir,
+  });
   const cwd = options.cwd ?? process.cwd();
   const now = options.now ?? (() => new Date());
   const storageFactory = options.storageFactory ?? ((config: AppConfig) => new BunStorageClient(config));
@@ -52,15 +78,30 @@ export async function runCli(argv: string[], options: RunCliOptions = {}): Promi
     }
 
     switch (parsed.command) {
+      case "setup":
+        return await runSetup(parsed, {
+          env,
+          envFilePath: options.envFilePath,
+          homeDir: options.homeDir,
+          io,
+          prompter: options.prompter,
+        });
       case "list":
       case "ls":
-        return await runList(parsed, { catalogPath: options.catalogPath, env, homeDir: options.homeDir, io });
+        return await runList(parsed, {
+          catalogPath: options.catalogPath,
+          env,
+          envFilePath: options.envFilePath,
+          homeDir: options.homeDir,
+          io,
+        });
       case "upload":
       case "up":
         return await runUpload(parsed, {
           catalogPath: options.catalogPath,
           cwd,
           env,
+          envFilePath: options.envFilePath,
           homeDir: options.homeDir,
           io,
           now,
@@ -71,6 +112,7 @@ export async function runCli(argv: string[], options: RunCliOptions = {}): Promi
         return await runDelete(parsed, {
           catalogPath: options.catalogPath,
           env,
+          envFilePath: options.envFilePath,
           homeDir: options.homeDir,
           io,
           now,
@@ -81,6 +123,7 @@ export async function runCli(argv: string[], options: RunCliOptions = {}): Promi
         return await runShare(parsed, {
           catalogPath: options.catalogPath,
           env,
+          envFilePath: options.envFilePath,
           homeDir: options.homeDir,
           io,
           storageFactory,
@@ -90,6 +133,7 @@ export async function runCli(argv: string[], options: RunCliOptions = {}): Promi
         return await runStatus(parsed, {
           catalogPath: options.catalogPath,
           env,
+          envFilePath: options.envFilePath,
           homeDir: options.homeDir,
           io,
           storageFactory,
@@ -103,9 +147,54 @@ export async function runCli(argv: string[], options: RunCliOptions = {}): Promi
   }
 }
 
+async function runSetup(
+  parsed: ParsedArgs,
+  options: {
+    env: EnvMap;
+    envFilePath?: string;
+    homeDir?: string;
+    io: CliIo;
+    prompter?: PromptLike;
+  },
+): Promise<number> {
+  if (parsed.positionals.length > 0) {
+    throw new Error("setup does not accept positional arguments");
+  }
+
+  const envFilePath = options.envFilePath ?? resolveConfigEnvPath(options.env, options.homeDir);
+  await mkdir(dirname(envFilePath), { recursive: true });
+
+  const prompter = options.prompter ?? createPrompter();
+  const nextEnv = {
+    ...pickScopedEnv(options.env),
+  };
+
+  try {
+    for (const question of SETUP_QUESTIONS) {
+      const answer = await promptRequiredValue(prompter, question.label, nextEnv[question.key]);
+      nextEnv[question.key] = answer;
+    }
+  } finally {
+    await prompter.close?.();
+  }
+
+  await writeScopedEnvFile(envFilePath, nextEnv);
+
+  if (parsed.flags.json) {
+    emitJson(options.io, {
+      envFilePath,
+      savedKeys: SETUP_QUESTIONS.map((question) => question.key),
+    });
+    return 0;
+  }
+
+  options.io.stdout(`saved\t${envFilePath}`);
+  return 0;
+}
+
 async function runList(
   parsed: ParsedArgs,
-  options: { catalogPath?: string; env: EnvMap; homeDir?: string; io: CliIo },
+  options: { catalogPath?: string; env: EnvMap; envFilePath?: string; homeDir?: string; io: CliIo },
 ): Promise<number> {
   if (parsed.positionals.length > 1) {
     throw new Error("list accepts at most one prefix");
@@ -113,6 +202,7 @@ async function runList(
 
   const config = requireCoreConfig(options.env, {
     catalogPath: options.catalogPath,
+    envFilePath: options.envFilePath,
     homeDir: options.homeDir,
   });
 
@@ -141,6 +231,7 @@ async function runUpload(
     catalogPath?: string;
     cwd: string;
     env: EnvMap;
+    envFilePath?: string;
     homeDir?: string;
     io: CliIo;
     now: () => Date;
@@ -151,6 +242,7 @@ async function runUpload(
   const prefix = readOptionalStringFlag(parsed.flags, "prefix");
   const config = requireCoreConfig(options.env, {
     catalogPath: options.catalogPath,
+    envFilePath: options.envFilePath,
     homeDir: options.homeDir,
   });
 
@@ -208,6 +300,7 @@ async function runDelete(
   options: {
     catalogPath?: string;
     env: EnvMap;
+    envFilePath?: string;
     homeDir?: string;
     io: CliIo;
     now: () => Date;
@@ -220,6 +313,7 @@ async function runDelete(
 
   const config = requireCoreConfig(options.env, {
     catalogPath: options.catalogPath,
+    envFilePath: options.envFilePath,
     homeDir: options.homeDir,
   });
   const storage = options.storageFactory(config);
@@ -271,6 +365,7 @@ async function runShare(
   options: {
     catalogPath?: string;
     env: EnvMap;
+    envFilePath?: string;
     homeDir?: string;
     io: CliIo;
     storageFactory: (config: AppConfig) => StorageClient;
@@ -282,6 +377,7 @@ async function runShare(
 
   const config = requireCoreConfig(options.env, {
     catalogPath: options.catalogPath,
+    envFilePath: options.envFilePath,
     homeDir: options.homeDir,
   });
   const catalog = new Catalog(config.catalogPath);
@@ -322,6 +418,7 @@ async function runStatus(
   options: {
     catalogPath?: string;
     env: EnvMap;
+    envFilePath?: string;
     homeDir?: string;
     io: CliIo;
     storageFactory: (config: AppConfig) => StorageClient;
@@ -369,6 +466,7 @@ async function runStatus(
   try {
     config = requireCoreConfig(options.env, {
       catalogPath: options.catalogPath,
+      envFilePath: options.envFilePath,
       homeDir: options.homeDir,
     });
   } catch (error) {
@@ -505,8 +603,30 @@ function readOptionalPositiveIntegerFlag(
   return parsed;
 }
 
+async function promptRequiredValue(prompt: PromptLike, label: string, defaultValue?: string): Promise<string> {
+  while (true) {
+    const answer = (await prompt.ask(label, defaultValue)).trim();
+    if (answer) {
+      return answer;
+    }
+  }
+}
+
+function createPrompter(): PromptLike {
+  const readline = createInterface({ input, output });
+  return {
+    ask: async (question: string, defaultValue?: string) => {
+      const suffix = defaultValue ? ` [${defaultValue}]` : "";
+      const answer = await readline.question(`${question}${suffix}: `);
+      return answer.trim() || defaultValue || "";
+    },
+    close: () => readline.close(),
+  };
+}
+
 function printHelp(io: CliIo): void {
   io.stdout("s3-storage-cli");
+  io.stdout("setup [--json]");
   io.stdout("status [--json]");
   io.stdout("list|ls [prefix] [--json]");
   io.stdout("upload|up <paths...> [--public|--private] [--prefix <remote-prefix>] [--json]");

package/src/config.ts

@@ -1,3 +1,4 @@
+import { readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -10,6 +11,7 @@ export interface AppConfig {
   bucket: string;
   catalogPath: string;
   endpoint: string;
+  envFilePath: string;
   publicBaseUrl?: string;
   region: string;
   secretAccessKey: string;
@@ -26,19 +28,33 @@ export interface EnvCheck {
 }
 
 const CORE_ENV_KEYS = [
-  "S3_ENDPOINT",
-  "S3_REGION",
-  "S3_ACCESS_KEY_ID",
-  "S3_SECRET_ACCESS_KEY",
-  "S3_BUCKET",
+  "S3_STORAGE_CLI_ENDPOINT",
+  "S3_STORAGE_CLI_REGION",
+  "S3_STORAGE_CLI_ACCESS_KEY_ID",
+  "S3_STORAGE_CLI_SECRET_ACCESS_KEY",
+  "S3_STORAGE_CLI_BUCKET",
 ] as const;
 
-const READY_ENV_KEYS = [...CORE_ENV_KEYS, "S3_PUBLIC_BASE_URL"] as const;
+const READY_ENV_KEYS = [...CORE_ENV_KEYS, "S3_STORAGE_CLI_PUBLIC_BASE_URL"] as const;
+
+const OPTIONAL_SCOPED_ENV_KEYS = [
+  "S3_STORAGE_CLI_SESSION_TOKEN",
+  "S3_STORAGE_CLI_SHARE_TTL_SECONDS",
+  "S3_STORAGE_CLI_VIRTUAL_HOSTED_STYLE",
+  "S3_STORAGE_CLI_DB_PATH",
+  "S3_STORAGE_CLI_ENV_PATH",
+] as const;
+
+const ALL_SCOPED_ENV_KEYS = [...READY_ENV_KEYS, ...OPTIONAL_SCOPED_ENV_KEYS] as const;
 
 export function getReadyEnvKeys(): readonly string[] {
   return READY_ENV_KEYS;
 }
 
+export function getScopedEnvKeys(): readonly string[] {
+  return ALL_SCOPED_ENV_KEYS;
+}
+
 export function inspectEnv(env: EnvMap): EnvCheck[] {
   return READY_ENV_KEYS.map((key) => {
     const value = env[key];
@@ -57,7 +73,7 @@ export function getMissingCoreEnvKeys(env: EnvMap): string[] {
 
 export function requireCoreConfig(
   env: EnvMap,
-  options: { homeDir?: string; catalogPath?: string } = {},
+  options: { homeDir?: string; catalogPath?: string; envFilePath?: string } = {},
 ): AppConfig {
   const missing = getMissingCoreEnvKeys(env);
   if (missing.length > 0) {
@@ -65,21 +81,26 @@ export function requireCoreConfig(
   }
 
   return {
-    accessKeyId: env.S3_ACCESS_KEY_ID!.trim(),
-    bucket: env.S3_BUCKET!.trim(),
+    accessKeyId: env.S3_STORAGE_CLI_ACCESS_KEY_ID!.trim(),
+    bucket: env.S3_STORAGE_CLI_BUCKET!.trim(),
     catalogPath: options.catalogPath ?? resolveCatalogPath(env, options.homeDir),
-    endpoint: env.S3_ENDPOINT!.trim(),
-    publicBaseUrl: env.S3_PUBLIC_BASE_URL?.trim() || undefined,
-    region: env.S3_REGION!.trim(),
-    secretAccessKey: env.S3_SECRET_ACCESS_KEY!.trim(),
-    sessionToken: env.S3_SESSION_TOKEN?.trim() || undefined,
-    shareTtlSeconds: parsePositiveInteger(env.S3_SHARE_TTL_SECONDS, 3600, "S3_SHARE_TTL_SECONDS"),
-    virtualHostedStyle: parseBoolean(env.S3_VIRTUAL_HOSTED_STYLE, false),
+    endpoint: env.S3_STORAGE_CLI_ENDPOINT!.trim(),
+    envFilePath: options.envFilePath ?? resolveConfigEnvPath(env, options.homeDir),
+    publicBaseUrl: env.S3_STORAGE_CLI_PUBLIC_BASE_URL?.trim() || undefined,
+    region: env.S3_STORAGE_CLI_REGION!.trim(),
+    secretAccessKey: env.S3_STORAGE_CLI_SECRET_ACCESS_KEY!.trim(),
+    sessionToken: env.S3_STORAGE_CLI_SESSION_TOKEN?.trim() || undefined,
+    shareTtlSeconds: parsePositiveInteger(
+      env.S3_STORAGE_CLI_SHARE_TTL_SECONDS,
+      3600,
+      "S3_STORAGE_CLI_SHARE_TTL_SECONDS",
+    ),
+    virtualHostedStyle: parseBoolean(env.S3_STORAGE_CLI_VIRTUAL_HOSTED_STYLE, false),
   };
 }
 
 export function resolveCatalogPath(env: EnvMap, customHomeDir?: string): string {
-  const override = env.S3_CLI_DB_PATH?.trim();
+  const override = env.S3_STORAGE_CLI_DB_PATH?.trim();
   if (override) {
     return override;
   }
@@ -87,14 +108,115 @@ export function resolveCatalogPath(env: EnvMap, customHomeDir?: string): string
   return join(customHomeDir ?? homedir(), ".s3-storage-cli", "catalog.sqlite");
 }
 
+export function resolveConfigEnvPath(env: EnvMap, customHomeDir?: string): string {
+  const override = env.S3_STORAGE_CLI_ENV_PATH?.trim();
+  if (override) {
+    return override;
+  }
+
+  return join(customHomeDir ?? homedir(), ".s3-storage-cli", "config.env");
+}
+
+export async function loadScopedEnv(
+  processEnv: EnvMap,
+  options: { envFilePath?: string; homeDir?: string } = {},
+): Promise<EnvMap> {
+  const envFilePath = options.envFilePath ?? resolveConfigEnvPath(processEnv, options.homeDir);
+  const fileEnv = await readScopedEnvFile(envFilePath);
+
+  return {
+    ...fileEnv,
+    ...processEnv,
+  };
+}
+
+export async function readScopedEnvFile(envFilePath: string): Promise<EnvMap> {
+  try {
+    const content = await readFile(envFilePath, "utf8");
+    return parseEnvFile(content);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return {};
+    }
+
+    throw error;
+  }
+}
+
+export async function writeScopedEnvFile(envFilePath: string, values: EnvMap): Promise<void> {
+  const lines = [
+    "# s3-storage-cli scoped configuration",
+    ...ALL_SCOPED_ENV_KEYS.flatMap((key) => {
+      const value = values[key];
+      if (!value?.trim()) {
+        return [];
+      }
+
+      return [`${key}=${JSON.stringify(value.trim())}`];
+    }),
+    "",
+  ];
+
+  await writeFile(envFilePath, lines.join("\n"), "utf8");
+}
+
+export function pickScopedEnv(env: EnvMap): EnvMap {
+  const result: EnvMap = {};
+  for (const key of ALL_SCOPED_ENV_KEYS) {
+    const value = env[key];
+    if (value !== undefined) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
 export function ensurePublicBaseUrl(config: AppConfig): string {
   if (!config.publicBaseUrl) {
-    throw new Error("missing env S3_PUBLIC_BASE_URL");
+    throw new Error("missing env S3_STORAGE_CLI_PUBLIC_BASE_URL");
   }
 
   return config.publicBaseUrl;
 }
 
+function parseEnvFile(content: string): EnvMap {
+  const env: EnvMap = {};
+
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+
+    const separatorIndex = line.indexOf("=");
+    if (separatorIndex <= 0) {
+      continue;
+    }
+
+    const key = line.slice(0, separatorIndex).trim();
+    const rawValue = line.slice(separatorIndex + 1).trim();
+    if (!key) {
+      continue;
+    }
+
+    env[key] = parseEnvValue(rawValue);
+  }
+
+  return env;
+}
+
+function parseEnvValue(value: string): string {
+  if (value.startsWith("\"") && value.endsWith("\"")) {
+    try {
+      return JSON.parse(value) as string;
+    } catch {
+      return value.slice(1, -1);
+    }
+  }
+
+  return value;
+}
+
 function parsePositiveInteger(raw: string | undefined, fallback: number, key: string): number {
   if (!raw?.trim()) {
     return fallback;