@lotics/cli 0.35.0 → 0.36.1

package/dist/config.d.ts

@@ -1,7 +1,31 @@
+/**
+ * A saved credential for one organization. The credential store keys these by
+ * `org_id`, so registering a second key for the same org updates in place
+ * rather than accumulating duplicates. `workspace_id` remembers the last
+ * workspace used in this org, so switching back lands where you left off.
+ */
+export interface Profile {
+    api_key: string;
+    org_name: string;
+    workspace_id?: string;
+}
+/**
+ * The on-disk config. One schema, two file roles:
+ *
+ * - **Global** (`~/.lotics/config.json`) is the credential store: `profiles`
+ *   (org_id → key) plus the `active_org` pointer, the account `email`, and the
+ *   update-check cache. This is the only place API keys live.
+ * - **Local** (`.lotics/config.json` in a project/worktree) is a pin: an
+ *   `active_org` pointer (+ optional `workspace_id`) whose key is resolved from
+ *   the global store. It holds no key and never needs `profiles`.
+ *
+ * Ephemeral / CI access uses the `LOTICS_API_KEY` env var, not a file.
+ */
 export interface LoticsConfig {
-    api_key?: string;
-    email?: string;
+    profiles?: Record<string, Profile>;
+    active_org?: string;
     workspace_id?: string;
+    email?: string;
     last_update_check?: number;
     latest_version?: string;
 }
@@ -9,30 +33,92 @@ export interface LoticsConfig {
  * Where a config operation reads from or writes to.
  *
  * - `"auto"` — walk up from the current working directory; the first ancestor
- *   containing `.lotics/config.json` wins, else the global `~/.lotics`. This
- *   lets a project or worktree pin its own account and workspace, and keeps
- *   resolution stable when commands run from a subdirectory.
+ *   containing `.lotics/config.json` wins, else the global `~/.lotics`.
  * - `"local"` — `.lotics/config.json` directly under the current working
- *   directory. Used to bootstrap a per-directory config (`lotics auth --local`)
- *   before any local file exists for `"auto"` to discover.
+ *   directory. Used to pin the current directory exactly (`--local`), with no
+ *   walk and no inheriting an ancestor's config.
  */
 export type ConfigScope = "auto" | "local";
 export declare function loadConfig(scope?: ConfigScope): LoticsConfig | null;
 export declare function saveConfig(config: LoticsConfig, scope?: ConfigScope): void;
 export declare function deleteConfig(scope?: ConfigScope): void;
 export declare function getConfigPath(scope?: ConfigScope): string;
+/** The global credential store (`~/.lotics/config.json`), regardless of cwd. */
+export declare function loadGlobalConfig(): LoticsConfig | null;
+export declare function saveGlobalConfig(config: LoticsConfig): void;
 /**
- * Check for a newer CLI version. Synchronous — prints a warning to stderr
- * if the cached latest version is newer than current. Kicks off a background
- * fetch if the cache is stale (result is written to config for next run).
+ * The local pin governing the current directory, or null if there isn't one.
+ * Walks up like `"auto"`, but returns null when the walk lands on the global
+ * file — so callers can treat "no local pin" distinctly from "global store".
  */
-export declare function checkForUpdate(currentVersion: string): void;
+export declare function loadLocalConfig(): LoticsConfig | null;
 /**
- * Resolve API key from flags, env vars, or config file.
- * Priority: flag > env > config file.
+ * Find a profile by org id (exact) or org name (case-insensitive). Throws if a
+ * name is ambiguous across profiles — the caller must use the id. Returns null
+ * when nothing matches.
  */
-export declare function resolveAuth(flags: {
-    apiKey?: string;
-}): {
+export declare function resolveProfileByNameOrId(profiles: Record<string, Profile>, nameOrId: string): [string, Profile] | null;
+export type ContextSource = "flag" | "env_key" | "env_org" | "local_pointer" | "global_profile";
+export interface ResolvedContext {
     apiKey: string;
+    workspaceId?: string;
+    orgId?: string;
+    orgName?: string;
+    source: ContextSource;
+}
+/**
+ * Resolve the effective `(apiKey, workspaceId)` for a command, plus where they
+ * came from. Precedence (highest first):
+ *
+ *   1. `--api-key` flag
+ *   2. `LOTICS_API_KEY` env
+ *   3. `LOTICS_ORG` env (name|id → global profile)
+ *   4. local `.lotics/config.json` `active_org` pointer (key from global store)
+ *   5. global `active_org` profile
+ *
+ * `--workspace` flag and `LOTICS_WORKSPACE` env override the workspace at every
+ * level. Throws (fails loud) when a pin names an org with no saved credential —
+ * never silently falls back to a different org.
+ */
+export declare function resolveContext(flags: {
+    apiKey?: string;
+    workspace?: string;
+}): ResolvedContext | null;
+/**
+ * Add or update a profile in the global store. Does not change which org is
+ * active — the caller decides that via `setActiveOrg`. Preserves the profile's
+ * remembered workspace when the caller doesn't supply a fresh one. Writes only
+ * the known fields, so any stray top-level keys in an older file are dropped.
+ */
+export declare function upsertProfile(orgId: string, fields: {
+    api_key: string;
+    org_name: string;
+    workspace_id?: string;
+}): void;
+/** Remove a profile. If it was active, the active pointer moves to any other. */
+export declare function removeProfile(orgId: string): void;
+/**
+ * Set the active org at the requested scope. `"global"` changes the default
+ * for every directory that isn't pinned; `"local"` writes a pointer into the
+ * current directory's `.lotics/config.json`.
+ */
+export declare function setActiveOrg(orgId: string, scope: "global" | "local"): void;
+/**
+ * Persist the selected workspace into whichever scope is active: a local pin
+ * if the current directory has one, else the active org's global profile.
+ * Returns the scope written, or null when there's nowhere persistent to write
+ * it (credentials came from `--api-key`/`LOTICS_API_KEY`, with no saved
+ * profile) — the caller decides whether that's an error or an in-memory-only
+ * selection.
+ */
+export declare function setSelectedWorkspace(workspaceId: string): {
+    scope: "local" | "global";
+    orgId?: string;
 } | null;
+/**
+ * Check for a newer CLI version. Synchronous — prints a warning to stderr
+ * if the cached latest version is newer than current. Kicks off a background
+ * fetch if the cache is stale (result is written to the global config for next
+ * run — the update cadence is a machine-global concern, not per-directory).
+ */
+export declare function checkForUpdate(currentVersion: string): void;

package/dist/config.js

@@ -1,6 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+function globalConfigFile() {
+    return path.join(os.homedir(), ".lotics", "config.json");
+}
 /**
  * Resolve the config file for a scope.
  *
@@ -24,25 +27,33 @@ function configFileForScope(scope) {
         }
         dir = parent;
     }
-    return path.join(os.homedir(), ".lotics", "config.json");
+    return globalConfigFile();
 }
-export function loadConfig(scope = "auto") {
+function readConfigFile(file) {
     try {
-        const raw = fs.readFileSync(configFileForScope(scope), "utf-8");
+        const raw = fs.readFileSync(file, "utf-8");
         return JSON.parse(raw);
     }
     catch {
         return null;
     }
 }
-export function saveConfig(config, scope = "auto") {
-    const file = configFileForScope(scope);
-    // The config file holds an API key — keep it owner-only. `mode` on
-    // writeFileSync applies only when the file is created, so chmod after to
-    // also tighten a config written before this protection existed.
+function writeConfigFile(file, config) {
+    // The config file holds API keys — keep it owner-only, and write atomically
+    // (temp file + rename) so a concurrent reader never sees a half-written store
+    // and a crash mid-write can't truncate the existing one. `mode` on
+    // writeFileSync only applies on create, so chmod the temp before the rename.
     fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-    fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
-    fs.chmodSync(file, 0o600);
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, file);
+}
+export function loadConfig(scope = "auto") {
+    return readConfigFile(configFileForScope(scope));
+}
+export function saveConfig(config, scope = "auto") {
+    writeConfigFile(configFileForScope(scope), config);
 }
 export function deleteConfig(scope = "auto") {
     try {
@@ -55,14 +66,203 @@ export function deleteConfig(scope = "auto") {
 export function getConfigPath(scope = "auto") {
     return configFileForScope(scope);
 }
+/** The global credential store (`~/.lotics/config.json`), regardless of cwd. */
+export function loadGlobalConfig() {
+    return readConfigFile(globalConfigFile());
+}
+export function saveGlobalConfig(config) {
+    writeConfigFile(globalConfigFile(), config);
+}
+/**
+ * The local pin governing the current directory, or null if there isn't one.
+ * Walks up like `"auto"`, but returns null when the walk lands on the global
+ * file — so callers can treat "no local pin" distinctly from "global store".
+ */
+export function loadLocalConfig() {
+    const file = configFileForScope("auto");
+    if (file === globalConfigFile())
+        return null;
+    return readConfigFile(file);
+}
+/**
+ * Find a profile by org id (exact) or org name (case-insensitive). Throws if a
+ * name is ambiguous across profiles — the caller must use the id. Returns null
+ * when nothing matches.
+ */
+export function resolveProfileByNameOrId(profiles, nameOrId) {
+    const byId = profiles[nameOrId];
+    if (byId)
+        return [nameOrId, byId];
+    const matches = Object.entries(profiles).filter(([, p]) => p.org_name.toLowerCase() === nameOrId.toLowerCase());
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1) {
+        throw new Error(`"${nameOrId}" matches multiple saved orgs: ${matches.map(([id]) => id).join(", ")}. Use the org id.`);
+    }
+    return null;
+}
+/**
+ * Resolve the effective `(apiKey, workspaceId)` for a command, plus where they
+ * came from. Precedence (highest first):
+ *
+ *   1. `--api-key` flag
+ *   2. `LOTICS_API_KEY` env
+ *   3. `LOTICS_ORG` env (name|id → global profile)
+ *   4. local `.lotics/config.json` `active_org` pointer (key from global store)
+ *   5. global `active_org` profile
+ *
+ * `--workspace` flag and `LOTICS_WORKSPACE` env override the workspace at every
+ * level. Throws (fails loud) when a pin names an org with no saved credential —
+ * never silently falls back to a different org.
+ */
+export function resolveContext(flags) {
+    const envKey = process.env.LOTICS_API_KEY;
+    const envOrg = process.env.LOTICS_ORG;
+    const envWorkspace = process.env.LOTICS_WORKSPACE;
+    const wsOverride = flags.workspace ?? envWorkspace;
+    if (flags.apiKey) {
+        return { apiKey: flags.apiKey, workspaceId: wsOverride, source: "flag" };
+    }
+    if (envKey) {
+        return { apiKey: envKey, workspaceId: wsOverride, source: "env_key" };
+    }
+    const global = loadGlobalConfig();
+    const profiles = global?.profiles ?? {};
+    if (envOrg) {
+        const resolved = resolveProfileByNameOrId(profiles, envOrg);
+        if (!resolved) {
+            throw new Error(`LOTICS_ORG="${envOrg}" matches no saved credential. Run "lotics org" to list, or "lotics auth api-key <key>" to add one.`);
+        }
+        const [orgId, profile] = resolved;
+        return {
+            apiKey: profile.api_key,
+            orgId,
+            orgName: profile.org_name,
+            workspaceId: wsOverride ?? profile.workspace_id,
+            source: "env_org",
+        };
+    }
+    const local = loadLocalConfig();
+    if (local?.active_org) {
+        const profile = profiles[local.active_org];
+        if (!profile) {
+            throw new Error(`This directory is pinned to org "${local.active_org}" (.lotics/config.json) but no saved credential exists for it. Run "lotics auth api-key <key>" while authenticated to that org.`);
+        }
+        return {
+            apiKey: profile.api_key,
+            orgId: local.active_org,
+            orgName: profile.org_name,
+            workspaceId: wsOverride ?? local.workspace_id ?? profile.workspace_id,
+            source: "local_pointer",
+        };
+    }
+    // A local file carrying an inline key is the obsolete self-contained format —
+    // reject it loudly rather than silently falling through to the global active
+    // org (which would run this directory against the wrong organization).
+    if (local && "api_key" in local) {
+        throw new Error(`This directory's .lotics/config.json uses the old self-contained format (inline key), which is no longer supported. Re-pin with "lotics auth api-key <key> --local" (or "lotics org use <name|id> --local").`);
+    }
+    if (global?.active_org) {
+        const profile = profiles[global.active_org];
+        if (!profile) {
+            throw new Error(`Active org "${global.active_org}" has no saved credential. Run "lotics org use <name|id>" to pick one, or "lotics auth api-key <key>".`);
+        }
+        return {
+            apiKey: profile.api_key,
+            orgId: global.active_org,
+            orgName: profile.org_name,
+            workspaceId: wsOverride ?? profile.workspace_id,
+            source: "global_profile",
+        };
+    }
+    return null;
+}
+// --- Credential store mutators (always target the global store) ------------
+/**
+ * Add or update a profile in the global store. Does not change which org is
+ * active — the caller decides that via `setActiveOrg`. Preserves the profile's
+ * remembered workspace when the caller doesn't supply a fresh one. Writes only
+ * the known fields, so any stray top-level keys in an older file are dropped.
+ */
+export function upsertProfile(orgId, fields) {
+    const config = loadGlobalConfig() ?? {};
+    const existing = config.profiles?.[orgId];
+    const profile = {
+        api_key: fields.api_key,
+        org_name: fields.org_name,
+        workspace_id: fields.workspace_id ?? existing?.workspace_id,
+    };
+    saveGlobalConfig({
+        profiles: { ...config.profiles, [orgId]: profile },
+        active_org: config.active_org,
+        email: config.email,
+        last_update_check: config.last_update_check,
+        latest_version: config.latest_version,
+    });
+}
+/** Remove a profile. If it was active, the active pointer moves to any other. */
+export function removeProfile(orgId) {
+    const config = loadGlobalConfig();
+    if (!config?.profiles?.[orgId])
+        return;
+    const { [orgId]: _removed, ...rest } = config.profiles;
+    const remaining = Object.keys(rest);
+    saveGlobalConfig({
+        ...config,
+        profiles: rest,
+        active_org: config.active_org === orgId ? remaining[0] : config.active_org,
+    });
+}
+/**
+ * Set the active org at the requested scope. `"global"` changes the default
+ * for every directory that isn't pinned; `"local"` writes a pointer into the
+ * current directory's `.lotics/config.json`.
+ */
+export function setActiveOrg(orgId, scope) {
+    if (scope === "local") {
+        // Write a clean pointer — dropping any stale fields from an older local
+        // file. Workspace resets to the org's remembered default (the profile's).
+        saveConfig({ active_org: orgId }, "local");
+        return;
+    }
+    const config = loadGlobalConfig() ?? {};
+    saveGlobalConfig({ ...config, active_org: orgId });
+}
+/**
+ * Persist the selected workspace into whichever scope is active: a local pin
+ * if the current directory has one, else the active org's global profile.
+ * Returns the scope written, or null when there's nowhere persistent to write
+ * it (credentials came from `--api-key`/`LOTICS_API_KEY`, with no saved
+ * profile) — the caller decides whether that's an error or an in-memory-only
+ * selection.
+ */
+export function setSelectedWorkspace(workspaceId) {
+    const local = loadLocalConfig();
+    if (local?.active_org) {
+        saveConfig({ ...local, workspace_id: workspaceId }, "auto");
+        return { scope: "local", orgId: local.active_org };
+    }
+    const config = loadGlobalConfig() ?? {};
+    const orgId = config.active_org;
+    const profile = orgId ? config.profiles?.[orgId] : undefined;
+    if (!orgId || !profile) {
+        return null;
+    }
+    saveGlobalConfig({
+        ...config,
+        profiles: { ...config.profiles, [orgId]: { ...profile, workspace_id: workspaceId } },
+    });
+    return { scope: "global", orgId };
+}
 const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
 /**
  * Check for a newer CLI version. Synchronous — prints a warning to stderr
  * if the cached latest version is newer than current. Kicks off a background
- * fetch if the cache is stale (result is written to config for next run).
+ * fetch if the cache is stale (result is written to the global config for next
+ * run — the update cadence is a machine-global concern, not per-directory).
  */
 export function checkForUpdate(currentVersion) {
-    const config = loadConfig();
+    const config = loadGlobalConfig();
     const lastCheck = config?.last_update_check ?? 0;
     if (Date.now() - lastCheck < UPDATE_CHECK_INTERVAL_MS) {
         if (config?.latest_version && config.latest_version !== currentVersion) {
@@ -74,8 +274,8 @@ export function checkForUpdate(currentVersion) {
     fetchLatestVersion().then((latest) => {
         if (!latest)
             return;
-        const existing = loadConfig() ?? {};
-        saveConfig({ ...existing, last_update_check: Date.now(), latest_version: latest });
+        const existing = loadGlobalConfig() ?? {};
+        saveGlobalConfig({ ...existing, last_update_check: Date.now(), latest_version: latest });
     }).catch(() => { });
 }
 async function fetchLatestVersion() {
@@ -113,14 +313,3 @@ function printUpdateWarning(current, latest) {
     console.error(`\nUpdate available: ${current} → ${latest}`);
     console.error(`Run: npm i -g @lotics/cli\n`);
 }
-/**
- * Resolve API key from flags, env vars, or config file.
- * Priority: flag > env > config file.
- */
-export function resolveAuth(flags) {
-    const config = loadConfig();
-    const apiKey = flags.apiKey ?? process.env.LOTICS_API_KEY ?? config?.api_key;
-    if (!apiKey)
-        return null;
-    return { apiKey };
-}