elanous 0.2.0 → 0.2.4

package/src/cli/start-cli.ts

@@ -0,0 +1,221 @@
+import { spawn, type SpawnOptions } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+import type { Command } from 'commander';
+import { detectProviders, type DetectedProvider } from '../llm/provider-detect.js';
+import { resolveDaemonEndpoint, type DaemonEndpoint, type ResolveDaemonEndpointOpts } from '../nexus/daemon-endpoint.js';
+import { runBgLaunch } from './bg-launch.js';
+
+export interface StartOptions {
+  gui?: boolean;
+  tui?: boolean;
+  json?: boolean;
+  login?: boolean;
+}
+
+export interface StartState {
+  providers: readonly Pick<DetectedProvider, 'provider' | 'auth' | 'available' | 'rank'>[];
+  tty: boolean;
+  healthy: boolean;
+  discoveryFailed?: boolean;
+}
+
+export type StartStepId = 'detect-llm' | 'login' | 'check-daemon' | 'launch-daemon' | 'open-gui' | 'open-tui';
+export interface StartPlannedStep { id: StartStepId; needed: boolean }
+export interface StartStep { id: StartStepId; status: 'done' | 'skipped' | 'failed'; detail: string }
+export interface StartResult {
+  exitCode: number;
+  steps: StartStep[];
+  llm: 'available' | 'missing' | 'unknown';
+  daemon: 'running' | 'started' | 'failed';
+  surface: 'gui' | 'tui' | 'none';
+}
+
+/** No I/O and no credential values: the same observations always produce the same actions. */
+export function planStart(options: StartOptions, state: StartState): StartPlannedStep[] {
+  const available = state.providers.some((entry) => entry.available && entry.auth !== 'agent-cli');
+  const gui = options.gui === true || options.tui !== true;
+  return [
+    { id: 'detect-llm', needed: true },
+    { id: 'login', needed: !state.discoveryFailed && !available && state.tty && options.json !== true && options.login !== false },
+    { id: 'check-daemon', needed: true },
+    { id: 'launch-daemon', needed: !state.healthy },
+    { id: 'open-gui', needed: gui },
+    { id: 'open-tui', needed: !gui },
+  ];
+}
+
+export interface StartDeps {
+  detect?: () => Promise<DetectedProvider[]>;
+  isTty?: () => boolean;
+  confirmLogin?: () => Promise<boolean>;
+  login?: () => Promise<boolean>;
+  health?: () => Promise<boolean>;
+  launch?: () => Promise<{ exitCode: number }>;
+  openGui?: (url: string) => Promise<boolean>;
+  openTui?: (json: boolean) => Promise<number>;
+  sleep?: (ms: number) => Promise<void>;
+  output?: (line: string) => void;
+  /** Test seam — daemon address. `null` means this universe has no daemon (do not guess a port).
+   *  Called again after a launch so the opened address is the daemon that was just started. */
+  resolveEndpoint?: (opts?: ResolveDaemonEndpointOpts) => DaemonEndpoint | null;
+  /** Test seam — records the health URL actually fetched. */
+  recordHealthUrl?: (url: string) => void;
+}
+
+function child(command: string, args: string[], options: SpawnOptions): Promise<number> {
+  return new Promise((resolve) => {
+    const proc = spawn(command, args, options);
+    proc.once('error', () => resolve(1));
+    proc.once('exit', (code) => resolve(code ?? 1));
+  });
+}
+
+async function confirmLogin(): Promise<boolean> {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try { return /^(y|yes)$/i.test((await rl.question('No LLM login found. Sign in to OpenAI Codex now? [y/N] ')).trim()); }
+  catch { return false; }
+  finally { rl.close(); }
+}
+
+function childArgs(bin: string, ...args: string[]): string[] {
+  return [bin, ...(process.argv.includes('--test') ? ['--test'] : []), ...args];
+}
+
+async function defaultLogin(): Promise<boolean> {
+  const bin = process.argv[1];
+  if (!bin) return false;
+  // Use the existing device-code login rather than handling or printing tokens here.
+  return (await child(process.execPath, childArgs(bin, 'login', 'openai-codex'), { stdio: ['inherit', process.stderr, process.stderr] })) === 0;
+}
+
+async function defaultHealth(deps: StartDeps): Promise<boolean> {
+  const endpoint = (deps.resolveEndpoint ?? resolveDaemonEndpoint)();
+  if (!endpoint) return false;
+  deps.recordHealthUrl?.(endpoint.healthUrl);
+  try {
+    return (await fetch(endpoint.healthUrl, { signal: AbortSignal.timeout(800) })).ok;
+  } catch { return false; }
+}
+
+async function defaultOpenGui(url: string): Promise<boolean> {
+  const platform = process.platform;
+  if (platform !== 'darwin' && platform !== 'linux' && platform !== 'win32') return false;
+  const command = platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  return (await child(command, args, { stdio: 'ignore' })) === 0;
+}
+
+async function defaultOpenTui(json: boolean): Promise<number> {
+  const bin = process.argv[1];
+  return bin ? child(process.execPath, childArgs(bin), { stdio: json ? ['inherit', process.stderr, process.stderr] : 'inherit' }) : 1;
+}
+
+/** Side effects are explicitly injected; only stable, non-secret outcomes reach steps/output. */
+export async function runStart(options: StartOptions = {}, deps: StartDeps = {}): Promise<StartResult> {
+  const output = deps.output ?? console.log;
+  const steps: StartStep[] = [];
+  const record = (id: StartStepId, status: StartStep['status'], detail: string) => steps.push({ id, status, detail });
+  let providers: DetectedProvider[] = [];
+  let discoveryFailed = false;
+  try {
+    providers = await (deps.detect ?? detectProviders)();
+    record('detect-llm', 'done', 'LLM discovery finished');
+  } catch {
+    discoveryFailed = true;
+    record('detect-llm', 'failed', 'LLM discovery failed');
+  }
+  const tty = (deps.isTty ?? (() => process.stdin.isTTY === true))();
+  let healthy = false;
+  const probeHealth = deps.health ?? (() => defaultHealth(deps));
+  try { healthy = await probeHealth(); } catch { /* No health response; try launch. */ }
+  const plan = planStart(options, { providers, tty, healthy, discoveryFailed });
+  let llm: StartResult['llm'] = discoveryFailed ? 'unknown' : providers.some((entry) => entry.available && entry.auth !== 'agent-cli') ? 'available' : 'missing';
+  if (plan.find((entry) => entry.id === 'login')?.needed) {
+    let agreed = false;
+    try { agreed = await (deps.confirmLogin ?? confirmLogin)(); } catch { /* No consent. */ }
+    if (agreed) {
+      try {
+        if (await (deps.login ?? defaultLogin)()) {
+          try {
+            providers = await (deps.detect ?? detectProviders)();
+            llm = providers.some((entry) => entry.available && entry.auth !== 'agent-cli') ? 'available' : 'missing';
+            record('login', llm === 'available' ? 'done' : 'failed', llm === 'available' ? 'LLM login detected' : 'No usable LLM login detected');
+          } catch {
+            llm = 'unknown';
+            record('login', 'failed', 'LLM discovery after login failed');
+          }
+        } else record('login', 'failed', 'LLM login did not complete');
+      } catch { record('login', 'failed', 'LLM login or discovery did not complete'); }
+    } else record('login', 'skipped', 'Login declined');
+  } else record('login', 'skipped', llm === 'available' ? 'LLM already available' : llm === 'unknown' ? 'LLM discovery unavailable; login not offered' : 'Interactive login unavailable');
+  record('check-daemon', healthy ? 'done' : 'failed', healthy ? 'Daemon healthy' : 'Daemon did not respond');
+  let daemon: StartResult['daemon'] = healthy ? 'running' : 'failed';
+  if (plan.find((entry) => entry.id === 'launch-daemon')?.needed) {
+    try {
+      const launch = await (deps.launch ?? (() => runBgLaunch({ forwardArgs: ['--tools', 'webterm'], out: { log: () => {}, error: () => {} } })))();
+      if (launch.exitCode === 0) {
+        const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+        for (let i = 0; i < 40; i++) {
+          try { if (await probeHealth()) { healthy = true; break; } } catch { /* Retry until deadline. */ }
+          if (i < 39) await sleep(250);
+        }
+      }
+      daemon = healthy ? 'started' : 'failed';
+    } catch { daemon = 'failed'; }
+    record('launch-daemon', daemon === 'started' ? 'done' : 'failed', daemon === 'started' ? 'Daemon started and healthy' : 'Daemon launch or readiness failed');
+  } else record('launch-daemon', 'skipped', 'Daemon already healthy');
+
+  let surface: StartResult['surface'] = 'none';
+  const requested = plan.find((entry) => entry.id === 'open-gui')?.needed ? 'open-gui' : 'open-tui';
+  const openUrl = daemon === 'failed' ? null : (deps.resolveEndpoint ?? resolveDaemonEndpoint)()?.pwaUrl ?? null;
+  if (daemon === 'failed') {
+    record('open-gui', 'skipped', 'Daemon unavailable');
+    record('open-tui', 'skipped', 'Daemon unavailable');
+  } else {
+    if (requested === 'open-gui') {
+      if (!openUrl) {
+        record('open-gui', 'failed', 'Daemon address unknown');
+      } else {
+        try {
+          if (await (deps.openGui ?? defaultOpenGui)(openUrl)) surface = 'gui';
+        } catch { /* A browser is optional; retain the URL for manual opening. */ }
+        record('open-gui', surface === 'gui' ? 'done' : 'failed', surface === 'gui' ? `Opened ${openUrl}` : `Open manually: ${openUrl}`);
+      }
+      record('open-tui', 'skipped', 'GUI selected');
+    } else {
+      record('open-gui', 'skipped', 'TUI selected');
+      if (!tty) record('open-tui', 'failed', 'TUI requires a TTY');
+      else {
+        try { if ((await (deps.openTui ?? defaultOpenTui)(options.json === true)) === 0) surface = 'tui'; }
+        catch { /* Exit with a stable diagnostic, not process/credential details. */ }
+        record('open-tui', surface === 'tui' ? 'done' : 'failed', surface === 'tui' ? 'TUI closed' : 'TUI failed');
+      }
+    }
+  }
+  const exitCode = llm === 'unknown' || daemon === 'failed' || steps.some((step) => (step.id === requested) && step.status === 'failed') ? 1 : 0;
+  const result: StartResult = { exitCode, steps, llm, daemon, surface };
+  if (options.json) output(JSON.stringify(result));
+  else {
+    for (const step of steps) output(`${step.status === 'done' ? '✓' : step.status === 'failed' ? '✗' : '–'} ${step.id}: ${step.detail}`);
+    if (llm === 'missing') output('LLM not configured; run `elanous login openai-codex` or `elanous llm detect`.');
+    if (llm === 'unknown') output('LLM status unknown; discovery failed. Run `elanous llm detect` to check configuration.');
+  }
+  return result;
+}
+
+export function registerStartCommand(program: Command, deps: StartDeps = {}): void {
+  program.command('start').description('Discover LLM, ensure Nexus is healthy, and open the GUI or TUI')
+    .option('--gui', 'Open the browser UI (default)')
+    .option('--tui', 'Open the terminal UI instead')
+    .option('--no-login', 'Do not offer interactive LLM login')
+    .option('--json', 'Print one secret-free JSON result')
+    .action(async (options: StartOptions) => {
+      if (options.gui && options.tui) {
+        (deps.output ?? console.log)(options.json ? JSON.stringify({ exitCode: 2, error: '--gui and --tui are mutually exclusive' }) : '--gui and --tui are mutually exclusive');
+        process.exitCode = 2;
+        return;
+      }
+      const result = await runStart(options, deps);
+      if (result.exitCode) process.exitCode = result.exitCode;
+    });
+}

package/src/cli/stdout-flush.ts

@@ -0,0 +1,8 @@
+// Preserve the intake JSON newline rule while waiting for the stream's write callback.
+export async function writeStdoutFully(text: string): Promise<void> {
+  await new Promise<void>((resolve) => { process.stdout.write(text.endsWith('\n') ? text : `${text}\n`, () => resolve()); });
+}
+
+export async function writeStderrFully(text: string): Promise<void> {
+  await new Promise<void>((resolve) => { process.stderr.write(text.endsWith('\n') ? text : `${text}\n`, () => resolve()); });
+}

package/src/cli/storage-cli.ts

@@ -0,0 +1,334 @@
+import type { Command } from 'commander';
+import { execFile } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
+import type { CliBinDeps } from '../storage/cli-bin.js';
+import {
+  createObjectStore,
+  readRawConfig,
+  resolveBucket,
+  resolveStorageConfig,
+  type ObjectStore,
+  type RunFn,
+  type StorageConfig,
+  type StorageProvider,
+} from '../storage/object-store.js';
+import {
+  detectStorageProviders,
+  type StorageCommandResult,
+  type StorageDetectDeps,
+  type StorageProviderDetect,
+} from '../storage/storage-detect.js';
+
+export interface StorageDetectOptions {
+  json?: boolean;
+}
+
+export interface StorageDetectCliDeps {
+  detect?: (deps: StorageDetectDeps) => Promise<StorageProviderDetect[]>;
+  currentProvider?: () => string;
+  output?: (line: string) => void;
+  /** 테스트가 가짜 run 을 주입한다. 없으면 실제 자식 프로세스. */
+  run?: StorageDetectDeps['run'];
+  which?: StorageDetectDeps['which'];
+  platform?: NodeJS.Platform;
+  home?: string;
+  localWritable?: boolean;
+}
+
+export interface StorageDetectCliResult {
+  providers: StorageProviderDetect[];
+  current: string;
+}
+
+const DETECT_TIMEOUT_MS = 8000;
+
+/** 자식 프로세스 한 번. 시간 초과·실행 불가는 timedOut — 로그인 안 됨이 아니다. */
+export function execStorageCommand(bin: string, args: string[], opts: { timeoutMs: number }): Promise<StorageCommandResult> {
+  return new Promise((resolve) => {
+    execFile(bin, args, {
+      timeout: opts.timeoutMs || DETECT_TIMEOUT_MS,
+      maxBuffer: 1024 * 1024,
+      env: process.env,
+      windowsHide: true,
+    }, (error, stdout, stderr) => {
+      const errno = (error as NodeJS.ErrnoException | null)?.code;
+      const timedOut = errno === 'ETIMEDOUT' || /timed out/i.test(error?.message ?? '');
+      const status = (error as (NodeJS.ErrnoException & { status?: number }) | null)?.status;
+      const code = typeof status === 'number' ? status : error ? (timedOut ? 124 : 1) : 0;
+      resolve({
+        code,
+        stdout: typeof stdout === 'string' ? stdout : '',
+        stderr: typeof stderr === 'string' ? stderr : '',
+        ...(timedOut || errno === 'ENOENT' ? { timedOut: true } : {}),
+      });
+    });
+  });
+}
+
+function readCurrentProvider(): string {
+  try {
+    const raw = JSON.parse(readFileSync(join(getElanousConfigDir(), 'config.json'), 'utf8')) as {
+      storage?: { provider?: unknown };
+    };
+    const value = raw?.storage?.provider;
+    return typeof value === 'string' && value.trim() ? value.trim() : 'local';
+  } catch {
+    return 'local';
+  }
+}
+
+function mark(row: StorageProviderDetect): string {
+  if (row.provider !== 'local' && row.cli.path === null) return '✖';
+  if (row.signedIn === true) return '✅';
+  return '⚪';
+}
+
+function statusWords(row: StorageProviderDetect): string {
+  if (row.provider === 'local') return row.signedIn === true ? '사용 가능' : '확인 불가';
+  if (row.cli.path === null) return '없음';
+  if (row.signedIn === true) return '로그인됨';
+  if (row.signedIn === false) return '설치됨·로그인 안 됨';
+  return '설치됨·로그인 모름';
+}
+
+export function formatStorageDetectLine(row: StorageProviderDetect): string {
+  const account = row.account ? ` · ${row.account}` : '';
+  const project = row.project ? ` · ${row.project}` : '';
+  const buckets = row.bucketCount !== null ? ` · buckets ${row.bucketCount}` : '';
+  const hint = row.hint ? ` · ${row.hint}` : '';
+  return `${mark(row)} ${row.provider}  ${statusWords(row)}${account}${project}${buckets}${hint}`;
+}
+
+export async function runStorageDetect(
+  options: StorageDetectOptions = {},
+  deps: StorageDetectCliDeps = {},
+): Promise<StorageDetectCliResult> {
+  const output = deps.output ?? console.log;
+  const detect = deps.detect ?? detectStorageProviders;
+  const providers = await detect({
+    run: deps.run ?? execStorageCommand,
+    ...(deps.which ? { which: deps.which } : {}),
+    ...(deps.platform ? { platform: deps.platform } : {}),
+    ...(deps.home ? { home: deps.home } : {}),
+    ...(deps.localWritable !== undefined ? { localWritable: deps.localWritable } : {}),
+  });
+  const current = (deps.currentProvider ?? readCurrentProvider)();
+  const result: StorageDetectCliResult = { providers, current };
+  if (options.json) {
+    output(JSON.stringify(result));
+    return result;
+  }
+  for (const row of providers) output(formatStorageDetectLine(row));
+  output(`지금 설정: storage.provider = ${current}`);
+  return result;
+}
+
+export function registerStorageDetectCommand(program: Command): void {
+  const storage = program.command('storage').description('저장소 공급자');
+  storage.command('detect')
+    .description('이 기계의 클라우드 CLI 와 로그인 계정·기본 프로젝트를 값 노출 없이 보여 준다')
+    .option('--json', 'JSON 출력')
+    .action(async (opts: StorageDetectOptions) => {
+      await runStorageDetect(opts);
+    });
+  storage.command('put')
+    .description('파일 하나를 올리거나 로컬 폴더에 놓는다')
+    .argument('<file>', '올릴 파일')
+    .option('--key <key>', '객체 키')
+    .option('--public', '공개 버킷에 올린다')
+    .option('--local-dir <dir>', 'local 일 때 복사할 폴더')
+    .option('--json', 'JSON 출력')
+    .action(async (file: string, opts: StoragePutOptions) => {
+      const code = await runStoragePut(file, opts);
+      if (code !== 0) process.exitCode = code;
+    });
+}
+
+export interface StoragePutOptions {
+  key?: string;
+  public?: boolean;
+  localDir?: string;
+  json?: boolean;
+}
+
+export type StoragePutResult =
+  | { kind: 'path'; path: string; provider: StorageProvider }
+  | { kind: 'url'; url: string; provider: StorageProvider }
+  | { kind: 'object'; uri: string; provider: StorageProvider };
+
+export interface StoragePutCliDeps {
+  configDir?: string;
+  readConfig?: (configDir: string) => StorageConfig;
+  store?: ObjectStore;
+  /** store 를 안 줄 때 createObjectStore 에 넘긴다. 가짜 CLI 경로. */
+  cliBin?: CliBinDeps;
+  run?: RunFn;
+  output?: (line: string) => void;
+  error?: (line: string) => void;
+  now?: () => Date;
+  copyFile?: (src: string, dest: string) => void;
+  exists?: (path: string) => boolean;
+  readFile?: (path: string) => Buffer;
+  mkdir?: (path: string) => void;
+}
+
+function defaultReadConfig(configDir: string): StorageConfig {
+  return resolveStorageConfig(readRawConfig(join(configDir, 'config.json')));
+}
+
+function ymd(date: Date): string {
+  const y = date.getUTCFullYear();
+  const m = String(date.getUTCMonth() + 1).padStart(2, '0');
+  const d = String(date.getUTCDate()).padStart(2, '0');
+  return `${y}-${m}-${d}`;
+}
+
+function safeName(file: string): string {
+  const name = basename(file).replace(/[/\\]/g, '');
+  return name.length > 0 ? name : 'file';
+}
+
+/** 같은 이름이 있고 내용이 다르면 -1, -2 … 를 붙인다. 같으면 그 경로. */
+export function uniqueCopyName(
+  dir: string,
+  fileName: string,
+  sourceBytes: Buffer,
+  exists: (path: string) => boolean,
+  readFile: (path: string) => Buffer,
+): string {
+  const dot = fileName.lastIndexOf('.');
+  const stem = dot > 0 ? fileName.slice(0, dot) : fileName;
+  const ext = dot > 0 ? fileName.slice(dot) : '';
+  const candidate = (n: number) => (n === 0 ? fileName : `${stem}-${n}${ext}`);
+  for (let n = 0; n < 10_000; n += 1) {
+    const path = join(dir, candidate(n));
+    if (!exists(path)) return path;
+    try {
+      if (readFile(path).equals(sourceBytes)) return path;
+    } catch { /* 읽기 실패면 다음 번호 */ }
+  }
+  throw new Error('이름 충돌을 풀 수 없다');
+}
+
+/** `--public` 은 공개 버킷 URL. 키의 공개 기능 여부와 무관하다(버킷이 공개다). */
+function publicUrlFor(cfg: StorageConfig, key: string): string {
+  const encoded = key.split('/').map(encodeURIComponent).join('/');
+  const bucket = cfg.publicBucket;
+  if (cfg.provider === 's3') return `https://${bucket}.s3.amazonaws.com/${encoded}`;
+  if (cfg.provider === 'r2') return `https://${bucket}.${cfg.r2?.accountId ?? ''}.r2.cloudflarestorage.com/${encoded}`;
+  if (cfg.provider === 'gcs') return `https://storage.googleapis.com/${bucket}/${encoded}`;
+  if (cfg.provider === 'azure') return `https://${cfg.azure?.account ?? ''}.blob.core.windows.net/${bucket}/${encoded}`;
+  return encoded;
+}
+
+function objectUri(cfg: StorageConfig, bucket: string, key: string): string {
+  if (cfg.provider === 'gcs') return `gs://${bucket}/${key}`;
+  if (cfg.provider === 's3' || cfg.provider === 'r2') return `s3://${bucket}/${key}`;
+  if (cfg.provider === 'azure') {
+    const account = cfg.azure?.account ?? '';
+    return `https://${account}.blob.core.windows.net/${bucket}/${key}`;
+  }
+  return `${bucket}/${key}`;
+}
+
+function failLine(message: string): string {
+  return message.replace(/[A-Za-z0-9+/]{20,}={0,2}/g, '[redacted]');
+}
+
+/** 파일 하나를 올리거나 놓는다. 0 = 성공 · 1 = 실패 · 2 = 공개 버킷 없음. 빈 설정은 원격 CLI 를 부르지 않는다. */
+export async function runStoragePut(
+  file: string,
+  options: StoragePutOptions = {},
+  deps: StoragePutCliDeps = {},
+): Promise<number> {
+  const output = deps.output ?? console.log;
+  const error = deps.error ?? console.error;
+  const exists = deps.exists ?? existsSync;
+  const readFile = deps.readFile ?? ((path: string) => readFileSync(path));
+  const copyFile = deps.copyFile ?? ((src: string, dest: string) => { copyFileSync(src, dest); });
+  const mkdir = deps.mkdir ?? ((path: string) => { mkdirSync(path, { recursive: true }); });
+  const now = deps.now ?? (() => new Date());
+
+  if (!exists(file)) {
+    error(`파일이 없다: ${file}`);
+    return 1;
+  }
+
+  let cfg: StorageConfig;
+  try {
+    cfg = deps.readConfig
+      ? deps.readConfig(deps.configDir ?? getElanousConfigDir())
+      : defaultReadConfig(deps.configDir ?? getElanousConfigDir());
+  } catch (e) {
+    error(failLine(e instanceof Error ? e.message : String(e)));
+    return 1;
+  }
+
+  const name = safeName(file);
+  const explicitKey = options.key?.replace(/^\/+|\/+$/g, '') ?? '';
+  const publicFlag = options.public === true;
+
+  if (cfg.provider === 'local') {
+    let dest: string;
+    if (options.localDir) {
+      try {
+        mkdir(options.localDir);
+        dest = uniqueCopyName(options.localDir, name, readFile(file), exists, readFile);
+        copyFile(file, dest);
+      } catch (e) {
+        error(failLine(e instanceof Error ? e.message : String(e)));
+        return 1;
+      }
+    } else {
+      const key = explicitKey || name;
+      const store = deps.store ?? createObjectStore(cfg, {
+        ...(deps.run ? { run: deps.run } : {}),
+        ...(deps.cliBin ? { cliBin: deps.cliBin } : {}),
+      });
+      try {
+        store.put(key, file);
+      } catch (e) {
+        error(failLine(e instanceof Error ? e.message : String(e)));
+        return 1;
+      }
+      const { bucket } = resolveBucket(cfg, key);
+      const clean = key.split('/').filter((s) => s && s !== '.' && s !== '..').join('/');
+      dest = join(cfg.localDir, bucket, clean);
+    }
+    const result: StoragePutResult = { kind: 'path', path: dest, provider: 'local' };
+    output(options.json ? JSON.stringify(result) : dest);
+    return 0;
+  }
+
+  if (publicFlag && !cfg.publicBucket) {
+    error('storage.publicBucket 이 설정되지 않았다');
+    return 2;
+  }
+
+  const key = explicitKey || `${cfg.prefix || 'monad'}/uploads/${ymd(now())}/${name}`;
+  const store = deps.store ?? createObjectStore(cfg, {
+    ...(deps.run ? { run: deps.run } : {}),
+    ...(deps.cliBin ? { cliBin: deps.cliBin } : {}),
+  });
+  try {
+    store.put(key, file, publicFlag ? { public: true } : undefined);
+  } catch (e) {
+    error(failLine(e instanceof Error ? e.message : String(e)));
+    return 1;
+  }
+
+  if (publicFlag) {
+    const url = publicUrlFor(cfg, key);
+    const result: StoragePutResult = { kind: 'url', url, provider: cfg.provider };
+    output(options.json ? JSON.stringify(result) : url);
+    return 0;
+  }
+
+  const { bucket } = resolveBucket(cfg, key);
+  const uri = objectUri(cfg, bucket, key);
+  const result: StoragePutResult = { kind: 'object', uri, provider: cfg.provider };
+  output(options.json ? JSON.stringify(result) : uri);
+  return 0;
+}

package/src/cli/tailscale-serve.ts

@@ -34,7 +34,7 @@ import { execFile } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 
-import { probeTailscale, type TailscaleProbe } from '../nexus/onboarding/tailscale-probe.js';
+import { probeTailscale, tailscaleExecEnv, type TailscaleProbe } from '../nexus/onboarding/tailscale-probe.js';
 
 export type TailscaleServeMode =
   | { kind: 'https-443' }
@@ -53,12 +53,9 @@ export interface TailscaleServeOpts {
   upstreamPort: number;
   /** Path component of the surfaced URL (default `/app/showroom/`). */
   urlPath?: string;
-  /** Whether to wrap `tailscale serve` invocations in `sudo -n`.
-   *  - Default `true` — required for `tls-terminated-tcp` mode on
-   *    macOS (binds a Tailscale-daemon-mediated TCP listener).
-   *  - Pass `false` for `https-443` legacy `pwa share enable` flow,
-   *    where the GUI Tailscale CLI typically handles permissions
-   *    interactively without sudo (matches pre-lift behavior). */
+  /** Mutation privilege policy: by default try without sudo, then retry
+   *  once with `sudo -n` only on a permission error. `true` uses sudo
+   *  immediately; `false` runs without sudo and never retries. */
   useSudo?: boolean;
   /** Test seam — replace `probeTailscale`. */
   probeFn?: () => Promise<TailscaleProbe>;
@@ -217,13 +214,10 @@ function buildDefaultServeCmd(useSudo: boolean): (
   args: readonly string[],
 ) => Promise<{ exitCode: number; stdout: string; stderr: string }> {
   return (binary, args) => new Promise((resolve) => {
-    // tls-terminated-tcp mode requires sudo on macOS; legacy
-    // https-443 mode usually works without sudo (the GUI Tailscale
-    // CLI handles privileged binds interactively). Caller chooses via
-    // `useSudo`.
+    // sudo 는 환경을 지우므로 `env TAILSCALE_BE_CLI=1` 로 넘긴다(tailscaleExecEnv 설명 참조).
     const cmd = useSudo ? 'sudo' : binary;
-    const argv = useSudo ? ['-n', binary, ...args] : [...args];
-    execFile(cmd, argv, { timeout: 15000 }, (err, stdout, stderr) => {
+    const argv = useSudo ? ['-n', 'env', 'TAILSCALE_BE_CLI=1', binary, ...args] : [...args];
+    execFile(cmd, argv, { timeout: 15000, env: tailscaleExecEnv() }, (err, stdout, stderr) => {
       if (!err) {
         resolve({ exitCode: 0, stdout: String(stdout ?? ''), stderr: String(stderr ?? '') });
         return;
@@ -235,7 +229,7 @@ function buildDefaultServeCmd(useSudo: boolean): (
       resolve({
         exitCode: code,
         stdout: String(stdout ?? ''),
-        stderr: String(stderr ?? (err as Error).message ?? ''),
+        stderr: String(stderr || (err as Error).message || ''),
       });
     });
   });
@@ -246,6 +240,29 @@ function isSudoFailure(res: { exitCode: number; stderr: string }): boolean {
   return /password is required|a password is required|sudo:.*password/i.test(res.stderr);
 }
 
+function isPermissionFailure(res: { exitCode: number; stderr: string }): boolean {
+  return res.exitCode !== 0
+    && /permission denied|operation not permitted|access denied|requires? (?:root|sudo|administrator)|must (?:be root|run as root)|EACCES|EPERM/i.test(res.stderr);
+}
+
+function mutationServeCmd(opts: Pick<TailscaleServeOpts, 'useSudo' | 'serveCmdFn'>): (
+  binary: string,
+  args: readonly string[],
+) => Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  const serveCmdFn = opts.serveCmdFn;
+  const direct = serveCmdFn ?? buildDefaultServeCmd(false);
+  const sudo = serveCmdFn
+    ? (binary: string, args: readonly string[]) => serveCmdFn('sudo', ['-n', binary, ...args])
+    : buildDefaultServeCmd(true);
+  return async (binary, args) => {
+    if (opts.useSudo === true) return sudo(binary, args);
+    const result = await direct(binary, args);
+    return opts.useSudo === undefined && isPermissionFailure(result)
+      ? sudo(binary, args)
+      : result;
+  };
+}
+
 /** Build the `tailscale serve …` argv for the chosen mode. */
 function mountArgs(mode: TailscaleServeMode, upstreamPort: number): string[] {
   if (mode.kind === 'https-443') {
@@ -295,8 +312,7 @@ export async function mountTailscaleServe(
   const hostname = probe.magicDnsHost ?? probe.hostname ?? null;
   if (!hostname) return { ok: false, url: null, reason: 'magic-dns-unknown' };
   const binary = probe.binary ?? 'tailscale';
-  const useSudo = opts.useSudo !== false;
-  const serveCmd = opts.serveCmdFn ?? buildDefaultServeCmd(useSudo);
+  const serveCmd = mutationServeCmd(opts);
   const urlPath = opts.urlPath ?? DEFAULT_URL_PATH;
 
   // Singleton swap — when state describes a different mode/port,
@@ -385,8 +401,7 @@ export async function unmountTailscaleServe(
     return { ok: false, reason: 'tailscale-missing' };
   }
   const binary = probe.binary ?? 'tailscale';
-  const useSudo = opts.useSudo !== false;
-  const serveCmd = opts.serveCmdFn ?? buildDefaultServeCmd(useSudo);
+  const serveCmd = mutationServeCmd(opts);
   const offRes = await serveCmd(binary, unmountArgs(mode));
   if (offRes.exitCode !== 0) {
     if (isSudoFailure(offRes)) {
@@ -545,7 +560,7 @@ export async function cleanGhostTailscaleServe(
   // Do not reuse unmountTailscaleServe here: its legacy lifecycle contract
   // uses `serve reset`, which would remove unrelated live mappings. This
   // preflight has a stricter contract and turns off only the verified port.
-  const offRes = await serveCmd(binary, ['serve', '--tls-terminated-tcp', String(opts.port), 'off']);
+  const offRes = await mutationServeCmd(opts)(binary, ['serve', '--tls-terminated-tcp', String(opts.port), 'off']);
   if (offRes.exitCode !== 0) {
     return {
       ok: false,