@doow/cli 0.1.0

package/dist/esm/index.js

@@ -0,0 +1,15 @@
+export { clearProfileCredentials, deleteProfile, getActiveProfile, getConfigDir, getProfileCredentials, readConfig, readCredentials, setActiveProfile, setProfileCredentials, writeConfig, writeCredentials } from './config/store.js';
+export { getApiUrl, isAgentMode, isCI, isTTY, shouldShowUI } from './config/env.js';
+export { createCredentialStore } from './auth/keyring.js';
+export { executePkceFlow, generatePkcePair } from './auth/pkce.js';
+export { executeDeviceFlow } from './auth/device-flow.js';
+export { authenticateWithApiKey, readTokenFromStdin, resolveAuth, validateApiKey } from './auth/api-key.js';
+export { acquireLock, needsRefresh, refreshToken, releaseLock } from './auth/refresh.js';
+export { canBindLocalhost, detectAuthMethod, executeAutoLogin } from './auth/detect.js';
+
+// @doow/cli library entry point
+// Re-exports for programmatic usage
+const VERSION = '0.1.0';
+
+export { VERSION };
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;;;AAAA;AACA;AAEO,MAAM,OAAO,GAAG;;;;"}

package/dist/mcp.cjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+'use strict';
+
+// MCP server entry point — placeholder for Phase 4 (E45)
+// Will use @modelcontextprotocol/sdk for stdio + Streamable HTTP transport
+console.error('doow mcp server: not yet implemented (Phase 4 — E45)');
+process.exit(1);
+//# sourceMappingURL=mcp.cjs.map

package/dist/mcp.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.cjs","sources":["../src/mcp.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAAA;AACA;AAEA,OAAO,CAAC,KAAK,CAAC,sDAAsD,CAAC;AACrE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;;"}

package/dist/types/index.d.ts

@@ -0,0 +1,369 @@
+/**
+ * Profile — one named context (org + API endpoint)
+ */
+interface Profile {
+    name: string;
+    apiUrl?: string;
+    organizationId?: string;
+    email?: string;
+}
+/**
+ * Top-level config stored in ~/.doow/config.json
+ */
+interface DoowConfig {
+    activeProfile: string;
+    profiles: Record<string, Profile>;
+}
+/**
+ * Stored credentials for a single profile (tokens / API key)
+ */
+interface ProfileCredentials {
+    accessToken?: string;
+    refreshToken?: string;
+    /** ISO-8601 datetime string */
+    expiresAt?: string;
+    apiKey?: string;
+}
+/**
+ * Top-level credentials stored in ~/.doow/credentials.json
+ */
+interface Credentials {
+    profiles: Record<string, ProfileCredentials>;
+}
+
+/**
+ * Returns the Doow config directory path.
+ * Prefers $DOOW_CONFIG_DIR when set; falls back to ~/.doow.
+ * Creates the directory (mode 0o700) if it does not yet exist.
+ */
+declare function getConfigDir(): Promise<string>;
+/** Reads ~/.doow/config.json. Returns the default config if the file is absent. */
+declare function readConfig(): Promise<DoowConfig>;
+/** Writes ~/.doow/config.json atomically with 0o600 perms. */
+declare function writeConfig(config: DoowConfig): Promise<void>;
+/** Reads ~/.doow/credentials.json. Returns empty credentials if absent. */
+declare function readCredentials(): Promise<Credentials>;
+/** Writes ~/.doow/credentials.json atomically with 0o600 perms. */
+declare function writeCredentials(creds: Credentials): Promise<void>;
+/** Returns the currently active Profile object. */
+declare function getActiveProfile(): Promise<Profile>;
+/** Sets the active profile name and persists config. Throws if the profile doesn't exist. */
+declare function setActiveProfile(name: string): Promise<void>;
+/**
+ * Returns credentials for the given profile name.
+ * Defaults to the currently active profile if name is omitted.
+ */
+declare function getProfileCredentials(profileName?: string): Promise<ProfileCredentials | undefined>;
+/** Stores credentials for the given profile, merging with existing. */
+declare function setProfileCredentials(profileName: string, creds: ProfileCredentials): Promise<void>;
+/** Removes all credentials for the given profile. */
+declare function clearProfileCredentials(profileName: string): Promise<void>;
+/**
+ * Deletes a profile from config + credentials.
+ * Throws if the profile is currently active — caller must switch first.
+ */
+declare function deleteProfile(name: string): Promise<void>;
+
+/** True when stdout is an interactive terminal. */
+declare function isTTY(): boolean;
+/** True when running inside a CI environment (any common CI sets $CI). */
+declare function isCI(): boolean;
+/**
+ * True when the CLI is invoked by an automated agent rather than a human.
+ * Detected via $DOOW_AGENT_MODE env var or the --agent CLI flag (which
+ * Commander stores on the global options object as `process.env` is the
+ * canonical signal here — Commander integration is wired up in cli.ts).
+ */
+declare function isAgentMode(): boolean;
+/**
+ * True when interactive UI (spinners, prompts, color) should be shown.
+ * Requires a real TTY, no CI env, and not running in agent mode.
+ */
+declare function shouldShowUI(): boolean;
+/**
+ * Resolve the API base URL.
+ * Precedence: profile.apiUrl → $DOOW_API_URL → hardcoded default.
+ */
+declare function getApiUrl(profile?: Profile): string;
+
+interface CredentialStore {
+    get(profileName: string): Promise<ProfileCredentials | undefined>;
+    set(profileName: string, creds: ProfileCredentials): Promise<void>;
+    clear(profileName: string): Promise<void>;
+    backend(): 'keyring' | 'file';
+}
+/**
+ * Creates a CredentialStore backed by the system keyring when available,
+ * falling back to file storage silently when keytar is not installed or
+ * the system keyring does not respond within 3 seconds.
+ *
+ * Call this once at startup and reuse the returned instance.
+ */
+declare function createCredentialStore(): Promise<CredentialStore>;
+
+/**
+ * pkce.ts
+ *
+ * OAuth 2.0 PKCE (RFC 7636) interactive login flow for the Doow CLI.
+ *
+ * Steps:
+ *  1. Generate PKCE code_verifier + code_challenge
+ *  2. Generate CSRF state token
+ *  3. Start a localhost HTTP server on a random port
+ *  4. Open browser to the authorize URL
+ *  5. Wait for the OAuth callback (120 s default timeout)
+ *  6. Exchange authorization code for tokens
+ *  7. Store tokens via CredentialStore
+ *  8. Close server and return result
+ */
+
+interface PkceFlowOptions {
+    apiUrl?: string;
+    profileName?: string;
+    credentialStore?: CredentialStore;
+    /** Milliseconds. Default 120_000 (2 minutes). */
+    timeout?: number;
+}
+interface PkceFlowResult {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: string;
+}
+/**
+ * Generates a PKCE code_verifier and code_challenge pair.
+ * - code_verifier: 32 random bytes, base64url-encoded (43 chars)
+ * - code_challenge: SHA-256 of verifier, base64url-encoded
+ */
+declare function generatePkcePair(): {
+    codeVerifier: string;
+    codeChallenge: string;
+};
+/**
+ * Executes the full PKCE browser-based OAuth 2.0 login flow.
+ *
+ * Opens the system browser to the Doow authorize endpoint, waits for the
+ * localhost callback, exchanges the authorization code for tokens, and
+ * persists the tokens via the credential store.
+ */
+declare function executePkceFlow(options?: PkceFlowOptions): Promise<PkceFlowResult>;
+
+/**
+ * device-flow.ts
+ *
+ * RFC 8628 OAuth 2.0 Device Authorization flow for headless/SSH/container
+ * environments where a browser cannot be opened on the same machine.
+ *
+ * Steps:
+ *   1. POST /v1/auth/device/authorize  → get device_code + user_code
+ *   2. Display verification URI + user_code on stderr
+ *   3. Optionally open the browser (best-effort)
+ *   4. Poll POST /v1/auth/device/token until granted or expired
+ *   5. Store tokens in the credential store
+ */
+
+interface DeviceFlowOptions {
+    apiUrl?: string;
+    profileName?: string;
+    credentialStore?: CredentialStore;
+    /**
+     * Injectable URL opener — defaults to the `open` npm package.
+     * Provide a custom function in tests to avoid spawning a real browser process.
+     */
+    openUrl?: (url: string) => Promise<unknown>;
+}
+interface DeviceFlowResult {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: string;
+}
+/**
+ * Execute the RFC 8628 device authorization flow.
+ *
+ * All user-facing output goes to stderr so stdout stays clean for piping.
+ *
+ * @throws {Error} if authorization fails or the device code expires.
+ */
+declare function executeDeviceFlow(options?: DeviceFlowOptions): Promise<DeviceFlowResult>;
+
+/**
+ * api-key.ts
+ *
+ * PAT (Personal Access Token) authentication for CI/scripting contexts.
+ *
+ * Provides:
+ *   - validateApiKey     — pure format check (dak_ prefix, length ≥ 20)
+ *   - authenticateWithApiKey — store key + optionally verify against API
+ *   - readTokenFromStdin — read a piped token from stdin
+ *   - resolveAuth        — precedence chain: flag > env > stdin > stored > none
+ */
+
+interface ApiKeyAuthOptions {
+    key: string;
+    apiUrl?: string;
+    profileName?: string;
+    credentialStore?: CredentialStore;
+    /** default true — hit capabilities endpoint to confirm key works */
+    verify?: boolean;
+}
+interface ApiKeyAuthResult {
+    apiKey: string;
+    verified: boolean;
+}
+interface ResolveAuthOptions {
+    /** --api-key flag value */
+    apiKeyFlag?: string;
+    /** --token-stdin flag */
+    tokenStdin?: boolean;
+    profileName?: string;
+    credentialStore?: CredentialStore;
+}
+interface ResolvedAuth {
+    type: 'api-key' | 'oauth-token' | 'none';
+    /** the bearer token (api key or access token) */
+    token?: string;
+    /** human-readable source: '--api-key flag', 'DOOW_API_KEY env', 'stdin', 'stored profile' */
+    source: string;
+    /** true if stored token is expired (expiresAt < now + 60s buffer) */
+    needsRefresh?: boolean;
+}
+/**
+ * Returns true if key starts with 'dak_' (case-sensitive) and is at least
+ * 20 characters total. Pure function — no network call.
+ */
+declare function validateApiKey(key: string): boolean;
+/**
+ * Validates the key format, stores it in the credential store, and optionally
+ * verifies it works by hitting GET /v1/auth/capabilities.
+ *
+ * @throws {Error} if the key does not have the dak_ prefix
+ * @throws {Error} if verify is true and the capabilities request fails
+ */
+declare function authenticateWithApiKey(options: ApiKeyAuthOptions): Promise<ApiKeyAuthResult>;
+/**
+ * Reads a token from piped stdin input.
+ *
+ * @throws {Error} if stdin is a TTY (not piped)
+ * @throws {Error} if the resulting string is empty after trim
+ */
+declare function readTokenFromStdin(): Promise<string>;
+/**
+ * Resolves the active auth context by walking the precedence chain:
+ *   --api-key flag > DOOW_API_KEY env > --token-stdin > stored profile > none
+ */
+declare function resolveAuth(options?: ResolveAuthOptions): Promise<ResolvedAuth>;
+
+interface RefreshOptions {
+    apiUrl?: string;
+    profileName?: string;
+    credentialStore?: CredentialStore;
+}
+interface RefreshResult {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: string;
+    /** false if another process already refreshed before we could */
+    wasRefreshed: boolean;
+}
+interface LockHandle {
+    lockPath: string;
+    release(): Promise<void>;
+}
+/**
+ * Returns true when the credential token needs a refresh:
+ * - no expiresAt present, OR
+ * - token expires within the 60-second buffer window
+ *
+ * Pure function — no I/O.
+ */
+declare function needsRefresh(creds: ProfileCredentials): boolean;
+/**
+ * Acquires an exclusive per-profile lock file.
+ *
+ * Uses O_EXCL (writeFile flag:'wx') for atomic exclusive creation.
+ * If a lock exists, checks staleness (>60s or dead PID) and cleans up if stale.
+ * Retries up to 10 times with 500ms back-off before throwing.
+ */
+declare function acquireLock(profileName: string): Promise<LockHandle>;
+/**
+ * Releases a previously acquired lock handle. Best-effort — never throws.
+ */
+declare function releaseLock(handle: LockHandle): Promise<void>;
+/**
+ * Performs a transparent token refresh with double-checked locking.
+ *
+ * 1. Acquires a per-profile lockfile
+ * 2. Re-reads credentials — another process may have already refreshed
+ * 3. If tokens are still fresh, skips the network call (wasRefreshed: false)
+ * 4. Otherwise calls POST /v1/auth/refresh and stores the new tokens
+ * 5. Always releases the lock in a finally block
+ *
+ * Throws with a user-friendly message if the session has expired.
+ */
+declare function refreshToken(options?: RefreshOptions): Promise<RefreshResult>;
+
+/**
+ * detect.ts
+ *
+ * S122 — Auth auto-detection for the Doow CLI.
+ *
+ * Determines whether to use PKCE, device, or API-key authentication based on
+ * the current runtime environment, then executes the appropriate flow.
+ *
+ * Detection order:
+ *   1. --api-key provided + valid format   → api-key
+ *   2. --device flag                       → device
+ *   3. Running inside CI ($CI set)         → device
+ *   4. Non-interactive stdout (!isTTY)     → device
+ *   5. Can bind 127.0.0.1 on a free port   → pkce
+ *   6. Fallback                            → device
+ */
+
+type AuthMethod = 'pkce' | 'device' | 'api-key';
+interface DetectOptions {
+    /** --device flag: force device flow even in interactive environments */
+    forceDevice?: boolean;
+    /** --api-key flag value */
+    apiKey?: string;
+}
+interface AutoLoginOptions {
+    forceDevice?: boolean;
+    apiKey?: string;
+    apiUrl?: string;
+    profileName?: string;
+    credentialStore?: CredentialStore;
+    /** PKCE callback timeout in ms. Default: 120_000 */
+    timeout?: number;
+}
+interface LoginResult {
+    method: AuthMethod;
+    accessToken?: string;
+    refreshToken?: string;
+    expiresAt?: string;
+    apiKey?: string;
+}
+/**
+ * Tests whether the process can bind a TCP server on 127.0.0.1 using an
+ * OS-assigned ephemeral port. The server is closed immediately on success.
+ *
+ * Returns true  → PKCE callback server will work.
+ * Returns false → Network stack can't bind (containers with restricted network
+ *                 policies, permission denied, etc.) — use device flow instead.
+ */
+declare function canBindLocalhost(): Promise<boolean>;
+/**
+ * Returns the best authentication method for the current environment.
+ */
+declare function detectAuthMethod(options?: DetectOptions): Promise<AuthMethod>;
+/**
+ * The main login orchestrator.
+ *
+ * 1. Detects the best auth method.
+ * 2. Executes the corresponding flow.
+ * 3. If PKCE fails with a server bind error, automatically retries with device flow.
+ */
+declare function executeAutoLogin(options?: AutoLoginOptions): Promise<LoginResult>;
+
+declare const VERSION = "0.1.0";
+
+export { VERSION, acquireLock, authenticateWithApiKey, canBindLocalhost, clearProfileCredentials, createCredentialStore, deleteProfile, detectAuthMethod, executeAutoLogin, executeDeviceFlow, executePkceFlow, generatePkcePair, getActiveProfile, getApiUrl, getConfigDir, getProfileCredentials, isAgentMode, isCI, isTTY, needsRefresh, readConfig, readCredentials, readTokenFromStdin, refreshToken, releaseLock, resolveAuth, setActiveProfile, setProfileCredentials, shouldShowUI, validateApiKey, writeConfig, writeCredentials };
+export type { ApiKeyAuthOptions, ApiKeyAuthResult, AuthMethod, AutoLoginOptions, CredentialStore, Credentials, DetectOptions, DeviceFlowOptions, DeviceFlowResult, DoowConfig, LockHandle, LoginResult, PkceFlowOptions, PkceFlowResult, Profile, ProfileCredentials, RefreshOptions, RefreshResult, ResolveAuthOptions, ResolvedAuth };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@doow/cli",
+  "version": "0.1.0",
+  "description": "Doow CLI — manage SaaS spend from your terminal and coding agents",
+  "license": "MIT",
+  "author": "Doow",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "bin": {
+    "doow": "./dist/cli.cjs"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rollup -c rollup.config.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^12.1.0",
+    "open": "^10.1.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^25.0.8",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^15.3.1",
+    "@rollup/plugin-replace": "^5.0.7",
+    "@rollup/plugin-typescript": "^11.1.6",
+    "rollup": "^4.60.2",
+    "rollup-plugin-dts": "^6.4.1",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3",
+    "vitest": "^1.6.1"
+  },
+  "optionalDependencies": {
+    "keytar": "^7.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "doow",
+    "cli",
+    "saas",
+    "spend",
+    "mcp"
+  ]
+}