agentlas 0.9.10 → 1.0.2

package/engine/commands/billing.cjs

@@ -0,0 +1,96 @@
+"use strict";
+/*
+ * billing — 크레딧 잔액 조회: agentlas billing
+ *
+ * 데스크탑 electron/billing.ts 와 같은 엔드포인트를 읽는다:
+ *   GET {web}/api/billing/credits — 두 계좌 정책:
+ *   · 구독 계좌(A): remainingCredits — 월 초기화 + 톱업 + 전송받은 렌트수익. 사용 가능.
+ *   · 렌트수익 계좌(B): earningsCredits — 내 업로드를 남이 빌려 쓸 때만 쌓임.
+ *   · 전송은 B → A 한 방향뿐이며 터미널에는 전송 명령이 없다(데스크탑 전용) —
+ *     조용히 숨기지 않고 help/출력에 명시한다.
+ *
+ * 인증: cloud/hub-client.cjs 의 세션 쿠키. 미로그인/세션 만료는 정직 exit 1 —
+ * 빈 잔액(0)으로 위장 출력하지 않는다(조용한 기본값 안티패턴 금지).
+ */
+const { cloudSessionCookie, fetchHub, webBaseUrl, parseHubJson } = require("../cloud/hub-client.cjs");
+
+function fmtCredits(value) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n.toLocaleString("en-US") : "—";
+}
+
+function usage(ko) {
+  return [
+    ko ? "사용법: agentlas billing" : "Usage: agentlas billing",
+    ko
+      ? "  구독 계좌(A)와 렌트수익 계좌(B) 잔액을 표시합니다."
+      : "  Shows the subscription account (A) and rental-earnings account (B) balances.",
+    ko
+      ? "  참고: 렌트수익(B) → 구독(A) 전송은 Agentlas Desktop 에서만 가능합니다 (터미널 전송 명령 없음)."
+      : "  Note: earnings (B) → subscription (A) transfer is Desktop-only (no transfer command in the terminal).",
+  ].join("\n");
+}
+
+async function run(ctx, args) {
+  const ko = ctx.lang === "ko";
+  if (args.some((a) => a === "--help" || a === "-h" || a === "help")) {
+    ctx.out(usage(ko));
+    return 0;
+  }
+
+  const cookie = await cloudSessionCookie();
+  if (!cookie) {
+    ctx.err(ko
+      ? "로그인이 필요합니다. `agentlas login` 을 먼저 실행하세요."
+      : "Not signed in. Run `agentlas login` first.");
+    return 1;
+  }
+
+  let resp;
+  try {
+    resp = await fetchHub(`${webBaseUrl()}/api/billing/credits`, { headers: { cookie } });
+  } catch (e) {
+    ctx.err((ko ? "크레딧 조회 실패: " : "Failed to fetch credits: ") + ((e && e.message) || e));
+    return 1;
+  }
+  // 401 = 세션 무효 — 데스크탑과 동일하게 미인증으로 강등한다(만료 세션으로 잔액 표시 금지).
+  if (resp.status === 401) {
+    ctx.err(ko
+      ? "세션이 만료되었습니다. `agentlas login` 으로 다시 로그인하세요."
+      : "Session expired. Sign in again with `agentlas login`.");
+    return 1;
+  }
+  if (!resp.ok) {
+    ctx.err((ko ? "크레딧 조회 실패: " : "Failed to fetch credits: ") + `HTTP ${resp.status}`);
+    return 1;
+  }
+
+  let balance;
+  try {
+    balance = parseHubJson(resp, "billing/credits");
+  } catch (e) {
+    ctx.err(String((e && e.message) || e));
+    return 1;
+  }
+  if (!balance || balance.authenticated === false) {
+    ctx.err(ko
+      ? "세션이 유효하지 않습니다. `agentlas login` 으로 다시 로그인하세요."
+      : "Session is not valid. Sign in again with `agentlas login`.");
+    return 1;
+  }
+
+  const a = ctx.ui.accent;
+  const dim = ctx.ui.dim;
+  if (balance.plan) ctx.out(`${ko ? "플랜" : "Plan"}: ${balance.plan}`);
+  ctx.out(`${a(ko ? "구독 계좌 (A)" : "Subscription account (A)")}: ${fmtCredits(balance.remainingCredits)} ${ko ? "크레딧" : "credits"}`);
+  if (balance.limitCredits != null || balance.usedCredits != null) {
+    ctx.out(dim(`  ${ko ? "사용" : "used"}: ${fmtCredits(balance.usedCredits)} / ${ko ? "한도" : "limit"}: ${fmtCredits(balance.limitCredits != null ? balance.limitCredits : balance.planCreditLimit)}${balance.topUpCredits ? `  (+${ko ? "톱업" : "top-up"} ${fmtCredits(balance.topUpCredits)})` : ""}`));
+  }
+  ctx.out(`${a(ko ? "렌트수익 계좌 (B)" : "Rental earnings account (B)")}: ${fmtCredits(balance.earningsCredits)} ${ko ? "크레딧" : "credits"}`);
+  ctx.out(dim(ko
+    ? "B → A 전송은 Agentlas Desktop 에서만 가능합니다 (터미널 전송 명령 없음)."
+    : "B → A transfer is Desktop-only (no transfer command in the terminal)."));
+  return 0;
+}
+
+module.exports = { run };

package/engine/commands/browser.cjs

@@ -0,0 +1,20 @@
+"use strict";
+/*
+ * browser — 실제 브라우저 실행 하드포인트 (hep-browser 라우트).
+ *
+ * v1 디스패처 매핑 그대로:
+ *   `agentlas browser <url-or-query|sub…>` → cmdHep(["hep-browser", ...rest])
+ *   v1은 browser에 무인자 가드가 없었다(missingArgumentUsage 미포함) —
+ *   무인자도 hep-browser 패스스루로 넘어가 네이티브 usage가 나온다. 보존.
+ */
+const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
+
+async function run(ctx, args) {
+  if (args.some(isHelpToken)) {
+    ctx.out(usageFor("browser", ctx.lang));
+    return 0;
+  }
+  return create(ctx).cmdHep(["hep-browser", ...args]);
+}
+
+module.exports = { run };

package/engine/commands/build.cjs

@@ -0,0 +1,33 @@
+"use strict";
+/*
+ * build — 에이전트/팀 빌드·수리·패키징 (hep-build 라우트).
+ *
+ * v1 디스패처 검증 메모 (legacy-v1-engine-snapshot engine/agentlas.cjs ~13097):
+ *   v1의 `agentlas build`는 hep-build 단순 패스스루가 아니라 터미널 소유
+ *   빌더(terminalAssets.cmdBuild: 시스템 MCP 메타데이터 프리플라이트 → 1회
+ *   동의 → Meta-Agent 실행)로 갔다. 그 프리플라이트/빌더 체인은 engine/mcp/*
+ *   와 빌더 서브시스템 소유라 이 클러스터의 범위 밖이다.
+ *   v2의 이 파일은 v1 도움말이 계약으로 명시한 표면 —
+ *   `build "<request>" … (hep-build)` — 즉 Agentlas OS hep-build 라우트를
+ *   그대로 노출한다. 터미널 소유 MCP-동의 빌더가 v2에 재구축되면 그 모듈이
+ *   이 명령을 대체(또는 선행)해야 한다.
+ *
+ * v1 인자 가드 그대로:
+ *   - help 토큰 → usage 출력, exit 0
+ *   - 무인자   → usage 실패, exit 1 (요청 문자열이 라우터로 새는 것 방지)
+ */
+const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
+
+async function run(ctx, args) {
+  if (args.some(isHelpToken)) {
+    ctx.out(usageFor("build", ctx.lang));
+    return 0;
+  }
+  if (!args.length) {
+    ctx.err("✖ " + usageFor("build", ctx.lang));
+    return 1;
+  }
+  return create(ctx).cmdHep(["hep-build", ...args]);
+}
+
+module.exports = { run };

package/engine/commands/call.cjs

@@ -0,0 +1,24 @@
+"use strict";
+/*
+ * call — 지정한 Hub/Cloud 에이전트 호출·준비 (hep-call 라우트).
+ *
+ * v1 디스패처 매핑 그대로:
+ *   `agentlas call "a,b" "<맥락>"` → cmdHep(["hep-call", ...rest])
+ *   무인자 → usage 실패 exit 1 (missingArgumentUsage 가드 — 슬러그 없는
+ *   호출이 자연어 라우팅으로 새는 것 방지).
+ */
+const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
+
+async function run(ctx, args) {
+  if (args.some(isHelpToken)) {
+    ctx.out(usageFor("call", ctx.lang));
+    return 0;
+  }
+  if (!args.length) {
+    ctx.err("✖ " + usageFor("call", ctx.lang));
+    return 1;
+  }
+  return create(ctx).cmdHep(["hep-call", ...args]);
+}
+
+module.exports = { run };

package/engine/commands/career-graph.cjs

@@ -0,0 +1,51 @@
+"use strict";
+/*
+ * career-graph — 커리어 그래프 상태/소스 등록 + 인덱스 실행 위임 (v1 cmdCareerGraph 포팅).
+ *
+ * ingest|query|verify|trace|public-card 는 파생 인덱스 실행이며 Agentlas OS /
+ * Hephaestus 런타임(career_graph 파이썬 모듈)이 소유한다 — 런타임이 있으면
+ * 그대로 위임 실행하고, 없으면 정직 정지(대신 계산하는 척 금지).
+ */
+const { runCareerGraphCli } = require("../project/career-graph.cjs");
+const { resolveCoreRuntimeRoot, resolvePython, spawnCoreModule } = require("../agentlas-core-harness.cjs");
+
+const INDEX_SUBCOMMANDS = new Set(["ingest", "query", "verify", "trace", "public-card"]);
+
+async function run(ctx, args) {
+  const sub = String((args && args[0]) || "status");
+  if (INDEX_SUBCOMMANDS.has(sub)) {
+    const coreRoot = resolveCoreRuntimeRoot();
+    if (!coreRoot || !resolvePython()) {
+      ctx.err(ctx.lang === "ko"
+        ? "Career Graph 인덱스 실행은 Agentlas OS / Hephaestus 런타임이 필요합니다 (~/.agentlas/runtime/current). 런타임 없이 결과를 지어내지 않습니다."
+        : "Career Graph index execution requires the Agentlas OS / Hephaestus runtime (~/.agentlas/runtime/current). No runtime — no fabricated result.");
+      return 1;
+    }
+    const graphArgs = args.slice();
+    if (!graphArgs.includes("--project")) graphArgs.push("--project", process.cwd());
+    const child = spawnCoreModule("career_graph", graphArgs, { cwd: process.cwd(), stdio: "inherit" }, coreRoot);
+    if (!child) {
+      ctx.err("Agentlas Core runtime or Python 3.9+ is unavailable.");
+      return 1;
+    }
+    return await new Promise((resolve) => {
+      child.on("error", (e) => { ctx.err(String((e && e.message) || e)); resolve(1); });
+      child.on("close", (code) => resolve(code == null ? 1 : code));
+    });
+  }
+  try {
+    const lines = runCareerGraphCli(args, {
+      cwd: process.cwd(),
+      projectPath: process.cwd(),
+      lang: ctx.lang,
+      notify: (line) => ctx.out(line),
+    });
+    for (const line of lines) ctx.out(line);
+    return 0;
+  } catch (e) {
+    ctx.err(String((e && e.message) || e));
+    return 1;
+  }
+}
+
+module.exports = { run };

package/engine/commands/cd.cjs

@@ -0,0 +1,22 @@
+"use strict";
+/* cd — 에이전트의 로컬 폴더 경로만 출력 (읽기 전용; cd "$(agentlas cd <agent>)" 용). */
+const { findAgent } = require("../agents/registry.cjs");
+const { agentFolder } = require("../agents/files.cjs");
+
+function run(ctx, args) {
+  const ko = ctx.lang === "ko";
+  if (!args[0]) {
+    ctx.err(ko ? "사용법: agentlas cd <agent>" : "Usage: agentlas cd <agent>");
+    return 1;
+  }
+  const agent = findAgent(ctx.db(), args[0]);
+  if (!agent) {
+    ctx.err((ko ? "에이전트를 찾을 수 없음: " : "agent not found: ") + args[0]);
+    return 1;
+  }
+  // 경로 조회 전용 — cd "$(agentlas cd seo)" 가 소스 패키지를 변형/재분류하면 안 된다.
+  ctx.out(agentFolder(agent));
+  return 0;
+}
+
+module.exports = { run };

package/engine/commands/chat.cjs

@@ -0,0 +1,12 @@
+"use strict";
+/* chat — 에이전트 지정 REPL 진입 별칭: agentlas chat <agent> (= agentlas <agent>) */
+function run(ctx, args) {
+  const ko = ctx.lang === "ko";
+  if (!args[0]) {
+    ctx.err(ko ? "사용법: agentlas chat <agent>" : "Usage: agentlas chat <agent>");
+    return 1;
+  }
+  const { startRepl } = require("../ui/repl.cjs");
+  return startRepl(ctx, { agent: args[0] });
+}
+module.exports = { run };

package/engine/commands/chats.cjs

@@ -0,0 +1,28 @@
+"use strict";
+/* chats [n] — 최근 대화 목록 (공유 DB, 데스크탑과 동일 데이터). */
+
+function run(ctx, args) {
+  const n = Math.max(1, Math.min(100, Number(args[0]) || 15));
+  const db = ctx.db();
+  if (!ctx.tableExists(db, "chats")) {
+    ctx.out(ctx.lang === "en" ? "No chats yet." : "대화가 아직 없습니다.");
+    return 0;
+  }
+  const rows = db.prepare(
+    `SELECT c.id, c.title, c.updated_at, a.slug AS agent_slug
+       FROM chats c LEFT JOIN installed_agents a ON a.id = c.agent_id
+      WHERE c.archived_at IS NULL AND (c.kind IS NULL OR c.kind = 'user')
+      ORDER BY c.updated_at DESC LIMIT ?`,
+  ).all(n);
+  if (!rows.length) {
+    ctx.out(ctx.lang === "en" ? "No chats yet." : "대화가 아직 없습니다.");
+    return 0;
+  }
+  for (const r of rows) {
+    const when = String(r.updated_at || "").replace("T", " ").slice(0, 16);
+    ctx.out(`  ${ctx.ui.dim(when)}  ${ctx.ui.accent((r.agent_slug || "?").padEnd(20))} ${r.title}`);
+  }
+  return 0;
+}
+
+module.exports = { run };

package/engine/commands/cloud.cjs

@@ -0,0 +1,17 @@
+"use strict";
+/*
+ * cloud — `agentlas cloud <sub> …`: Agent Cloud 자산 표면.
+ * 기능 로직은 전부 cloud-assets/ 에 있다. 여기서는 위임 + 오류 → ctx.err + 1.
+ */
+const { runCloud } = require("../cloud-assets/commands.cjs");
+
+async function run(ctx, args) {
+  try {
+    return await runCloud(ctx, args);
+  } catch (e) {
+    ctx.err(String((e && e.message) || e));
+    return 1;
+  }
+}
+
+module.exports = { run };

package/engine/commands/connect.cjs

@@ -0,0 +1,20 @@
+"use strict";
+/*
+ * connect — Telegram 등 플랫폼 연결 (hep-connect 라우트).
+ *
+ * v1 디스패처 매핑 그대로:
+ *   `agentlas connect <sub…>` → cmdHep(["hep-connect", ...rest])
+ *   무인자 connect는 v1에서 fail이 아니라 usage 안내 후 exit 0이었다
+ *   (topLevelCommandUsage("connect") 특례) — 그대로 보존.
+ */
+const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
+
+async function run(ctx, args) {
+  if (args.some(isHelpToken) || !args.length) {
+    ctx.out(usageFor("connect", ctx.lang));
+    return 0;
+  }
+  return create(ctx).cmdHep(["hep-connect", ...args]);
+}
+
+module.exports = { run };

package/engine/commands/context.cjs

@@ -0,0 +1,66 @@
+"use strict";
+/*
+ * context — 의존성 컨텍스트 맵 패스스루 (v1 monolith 13224–13234 포팅).
+ *
+ * refresh|locate|refs|slice|impact|verify 를 Agentlas Core 런타임
+ * (agentlas_cloud context …)에 그대로 넘긴다. v1은 Hephaestus parity 셸을 거쳤지만
+ * 최종 실행 주체는 같은 Core CLI다 (engine/agentlas-core-harness.cjs 가 스폰).
+ *
+ * 정직 정지: Core 런타임(또는 Python 3.9+)이 없으면 가짜 맵을 만들지 않고
+ * 무엇이 없는지 보고하며 exit 1 한다.
+ */
+const { projectCwd } = require("../project/paths.cjs");
+const { ensureTerminalProjectForExecutionCli } = require("../project/state.cjs");
+const {
+  CONTEXT_MAP_MIN_CORE_VERSION,
+  resolveCoreRuntimeRoot,
+  resolvePython,
+  spawnCoreModule,
+} = require("../agentlas-core-harness.cjs");
+
+const CONTEXT_SUBCOMMANDS = new Set(["refresh", "locate", "refs", "slice", "impact", "verify"]);
+
+function usage(ctx) {
+  ctx.err("Usage: agentlas context <refresh|locate|refs|slice|impact|verify> [args…] [--project <path>]");
+  return 1;
+}
+
+async function run(ctx, args) {
+  if (!args[0]) return usage(ctx);
+  if (!CONTEXT_SUBCOMMANDS.has(String(args[0]))) return usage(ctx);
+  const cwd = projectCwd();
+  // 수동 검사만 — context 명령은 프로젝트를 초기화하지 않는다 (0.9.10 경계).
+  ensureTerminalProjectForExecutionCli(ctx.db(), cwd, "read", "terminal-context");
+
+  const coreRoot = resolveCoreRuntimeRoot(null, [], { minVersion: CONTEXT_MAP_MIN_CORE_VERSION });
+  if (!coreRoot) {
+    // 정직 정지: 맵을 지어내지 않는다.
+    ctx.err(ctx.lang === "ko"
+      ? `Agentlas Core 런타임(≥ ${CONTEXT_MAP_MIN_CORE_VERSION})을 찾지 못했습니다. 컨텍스트 맵은 Core가 소유하므로 여기서 대신 만들지 않습니다.`
+      : `Agentlas Core runtime (>= ${CONTEXT_MAP_MIN_CORE_VERSION}) was not found. The context map is owned by Core; this command will not fabricate one.`);
+    ctx.err(ctx.lang === "ko"
+      ? "설치: Agentlas Desktop 최신 버전 또는 `hephaestus` 런타임(~/.agentlas/runtime/current)을 설치하세요."
+      : "Install the latest Agentlas Desktop or the `hephaestus` runtime (~/.agentlas/runtime/current), then retry.");
+    return 1;
+  }
+  if (!resolvePython()) {
+    ctx.err(ctx.lang === "ko"
+      ? "Python 3.9+ 를 찾지 못했습니다. Core 컨텍스트 맵 실행에 필요합니다."
+      : "Python 3.9+ was not found; it is required to run the Core context map.");
+    return 1;
+  }
+
+  const contextArgs = args.slice();
+  if (!contextArgs.includes("--project")) contextArgs.push("--project", cwd);
+  const child = spawnCoreModule("agentlas_cloud", ["context", ...contextArgs], { cwd, stdio: "inherit" }, coreRoot);
+  if (!child) {
+    ctx.err("Agentlas Core runtime or Python 3.9+ is unavailable.");
+    return 1;
+  }
+  return await new Promise((resolve) => {
+    child.on("error", (e) => { ctx.err(String((e && e.message) || e)); resolve(1); });
+    child.on("close", (code) => resolve(code == null ? 1 : code));
+  });
+}
+
+module.exports = { run, CONTEXT_SUBCOMMANDS };

package/engine/commands/creds.cjs

@@ -0,0 +1,203 @@
+"use strict";
+/*
+ * creds — 프로젝트 자격증명 저장 (v1 cmdCreds/cmdCredsFile 11210–11368 포팅).
+ *
+ * 계약:
+ *  - 값은 .env / credentials.env(0600) / (Electron 한정) keychain vault 에만 저장.
+ *    soul memory와 local-credentials.map.json 에는 사실(env 이름·상대경로)만 남긴다.
+ *  - keytar는 Electron 런타임에서만 사용한다. standalone Node에서 서명 없는
+ *    keytar 호출은 macOS 키체인에 막혀 무한 대기하고 process.exit로도 안 죽는다
+ *    (v1 실사고) — 절대 우회하지 않는다.
+ *  - 비밀 값은 어떤 경로로도 stdout/stderr에 출력하지 않는다.
+ */
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { userDataDir } = require("../core/paths.cjs");
+const { loadArch } = require("../core/db.cjs");
+const { activeProjectPath } = require("../project/state.cjs");
+const { upsertEnvLine } = require("../project/env-file.cjs");
+const {
+  localCredentialConfigCli,
+  ensureLocalCredentialStoreCli,
+  ensureSoulCredentialIndexCli,
+  upsertLocalCredentialMapCli,
+  projectScopedGlobalEnvKeyCli,
+  safeCredentialDestRelCli,
+} = require("../project/credentials.cjs");
+
+// 데스크탑과 공유하는 키체인 서비스/키 접두어 (v1 상수 그대로).
+const SERVICE = "com.agentlas.desktop";
+const ENV_PREFIX = "env:";
+
+function isElectronRuntime() {
+  return !!(process.versions && process.versions.electron);
+}
+function readKeytar() {
+  try {
+    return require("keytar");
+  } catch {
+    return null;
+  }
+}
+
+function parseCredFlags(args) {
+  const f = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a && a.startsWith("--")) {
+      const next = args[i + 1];
+      if (next !== undefined && !String(next).startsWith("--")) {
+        f[a.slice(2)] = next;
+        i++;
+      } else {
+        f[a.slice(2)] = true;
+      }
+    }
+  }
+  return f;
+}
+
+// `agentlas creds file`은 일반 CLI 명령이므로 상대경로 기준은 사용자가 명령을 실행한
+// 셸 cwd다. 런타임 격리용 agent-cwd를 쓰면 실제 프로젝트 파일을 조용히 못 찾는다.
+function resolveCredentialSourcePath(source, cwd) {
+  return path.resolve(cwd || process.cwd(), source);
+}
+
+async function cmdCredsFile(ctx, args) {
+  const fail = (msg) => { ctx.err(msg); return 1; };
+  const f = parseCredFlags(args);
+  const source = typeof f.source === "string" ? f.source : typeof f.path === "string" ? f.path : "";
+  if (!source) return fail("usage: agentlas creds file --source <path> [--provider <name>] [--env <ENV_NAME>] [--dest <relative-path>] [--project <path>] [--force]");
+  const project = typeof f.project === "string" && f.project ? f.project : activeProjectPath(ctx.db());
+  if (!project) return fail("creds file requires a project path");
+  const provider = typeof f.provider === "string" && f.provider ? f.provider : "credential_file";
+  const envKey = typeof f.env === "string" && f.env ? f.env.trim() : "";
+  if (envKey && !/^[A-Z][A-Z0-9_]*$/.test(envKey)) return fail("credential env name must look like ENV_NAME");
+
+  const arch = loadArch();
+  const cfg = localCredentialConfigCli(arch);
+  const projectName = path.basename(project) || "Project";
+  ensureLocalCredentialStoreCli(project, projectName, arch);
+  ensureSoulCredentialIndexCli(project, projectName, arch);
+
+  const sourceAbs = resolveCredentialSourcePath(source);
+  let stat;
+  try { stat = fs.statSync(sourceAbs); } catch { return fail(`credential source not found: ${source}`); }
+  if (!stat.isFile()) return fail(`credential source is not a file: ${source}`);
+
+  const base = path.basename(sourceAbs);
+  const lower = base.toLowerCase();
+  const defaultDir = lower.includes("google-services") || lower.includes("googleservice-info")
+    ? cfg.credentialsDir
+    : cfg.signingDir;
+  let destRel;
+  try {
+    destRel = safeCredentialDestRelCli(
+      typeof f.dest === "string" && f.dest ? f.dest : path.join(defaultDir, base),
+    );
+  } catch (e) {
+    return fail(String((e && e.message) || e));
+  }
+  const destAbs = path.join(project, destRel);
+  if (!path.resolve(destAbs).startsWith(path.resolve(project) + path.sep)) {
+    return fail("credential destination must stay inside the project");
+  }
+  if (fs.existsSync(destAbs) && !f.force) return fail(`credential destination already exists: ${destRel} (use --force to replace)`);
+
+  fs.mkdirSync(path.dirname(destAbs), { recursive: true });
+  fs.copyFileSync(sourceAbs, destAbs);
+  try { fs.chmodSync(destAbs, 0o600); } catch { /* best-effort */ }
+
+  const targets = [destRel];
+  if (envKey) {
+    try { upsertEnvLine(path.join(project, ".env"), envKey, destRel); targets.push("project .env"); }
+    catch (e) { ctx.err(".env write failed: " + e.message); }
+    const scopedKey = projectScopedGlobalEnvKeyCli(project, envKey);
+    try { upsertEnvLine(path.join(userDataDir(), "credentials.env"), scopedKey, destAbs); targets.push("global project env"); } catch { /* best-effort */ }
+    try { upsertEnvLine(path.join(os.homedir(), ".agentlas", "credentials.env"), scopedKey, destAbs); } catch { /* best-effort */ }
+  }
+
+  upsertLocalCredentialMapCli(project, projectName, arch, {
+    id: typeof f.id === "string" && f.id ? f.id : `${provider}:${envKey || destRel}`,
+    provider,
+    env: envKey ? [envKey] : [],
+    localFiles: [destRel],
+    owner: "project",
+    valueMaterialized: true,
+    storage: envKey ? ["project_file", "project_env", "global_project_env"] : ["project_file"],
+    requiredFor: typeof f.requiredFor === "string" && f.requiredFor ? [f.requiredFor] : [],
+    staleCheck: typeof f.staleCheck === "string" && f.staleCheck ? f.staleCheck : "Validate access before release or deploy.",
+  });
+
+  ctx.out(`✓ saved credential file for ${provider} — ${targets.join(", ")}.`);
+  return 0;
+}
+
+async function run(ctx, args) {
+  const fail = (msg) => { ctx.err(msg); return 1; };
+  const sub = args[0];
+  if (sub === "file") return cmdCredsFile(ctx, args.slice(1));
+  if (sub !== "save") {
+    return fail('usage: agentlas creds save --provider <name> --key <ENV_NAME> --value <value> [--project <path>] OR agentlas creds file --source <path> [--env <ENV_NAME>]');
+  }
+  const f = parseCredFlags(args.slice(1));
+  const key = typeof f.key === "string" ? f.key.trim() : "";
+  const value = f.value === undefined || f.value === true ? "" : String(f.value);
+  if (!key || !value) return fail("creds save requires --key and --value");
+  const provider = typeof f.provider === "string" && f.provider ? f.provider : key;
+  const project = typeof f.project === "string" && f.project ? f.project : activeProjectPath(ctx.db());
+  const targets = [];
+  const arch = loadArch();
+  const projectName = project ? path.basename(project) || "Project" : "Project";
+  if (project) {
+    ensureLocalCredentialStoreCli(project, projectName, arch);
+    ensureSoulCredentialIndexCli(project, projectName, arch);
+  }
+
+  // 1) keychain vault — project-scoped when a project is active.
+  // standalone(비-Electron)에서는 키체인 쓰기가 프롬프트로 멈출 수 있어 건너뛴다;
+  // 값은 아래 .env/credentials.env 파일에 저장되므로 런타임 주입에 지장 없다.
+  const keytar = isElectronRuntime() ? readKeytar() : null;
+  if (keytar) {
+    const vaultKey = project ? projectScopedGlobalEnvKeyCli(project, key) : key;
+    try { await keytar.setPassword(SERVICE, ENV_PREFIX + vaultKey, value); targets.push(project ? "project vault" : "vault"); }
+    catch (e) { ctx.err("vault save failed: " + e.message); }
+  }
+  // 2) 프로젝트 .env (평문)
+  if (project) {
+    try { upsertEnvLine(path.join(project, ".env"), key, value); targets.push("project .env"); }
+    catch (e) { ctx.err(".env write failed: " + e.message); }
+    // 3) 프로젝트 메모리 노트 (.agentlas/project-soul-memory.md) — 값 자체는 .env/vault에, 여기엔 사실만
+    try {
+      const soulDir = path.join(project, ".agentlas");
+      fs.mkdirSync(soulDir, { recursive: true });
+      fs.appendFileSync(
+        path.join(soulDir, "project-soul-memory.md"),
+        `\n- Connected ${provider}: ${key} saved in local credential store during first setup.\n`,
+        "utf8",
+      );
+    } catch { /* best-effort */ }
+    try {
+      upsertLocalCredentialMapCli(project, projectName, arch, {
+        id: `${provider}:${key}`,
+        provider,
+        env: [key],
+        localFiles: [],
+        owner: "project",
+        valueMaterialized: true,
+        storage: ["project_env", "project_vault", "global_project_env"],
+        staleCheck: "Validate access before release or deploy.",
+      });
+    } catch { /* best-effort */ }
+  }
+  // 4) 전역 로컬 env — 프로젝트가 있으면 프로젝트 이름이 붙은 키로 저장
+  const globalKey = project ? projectScopedGlobalEnvKeyCli(project, key) : key;
+  try { upsertEnvLine(path.join(userDataDir(), "credentials.env"), globalKey, value); targets.push(project ? "global project env" : "global memory"); } catch { /* best-effort */ }
+  try { upsertEnvLine(path.join(os.homedir(), ".agentlas", "credentials.env"), globalKey, value); } catch { /* best-effort */ }
+
+  ctx.out(`✓ connected ${provider} — saved ${key} to ${targets.join(", ") || "(nowhere — check keytar)"}.`);
+  return 0;
+}
+
+module.exports = { run, resolveCredentialSourcePath };