@nuucognition/cli-core 0.0.1-beta.0

package/README.md

@@ -0,0 +1,392 @@
+# @nuucognition/cli-core
+
+Shared CLI infrastructure for the NUU ecosystem. Provides feature flags, configuration, authentication, output formatting, and error handling that all NUU CLIs share.
+
+## Architecture
+
+All NUU CLI state lives under `~/.nuucognition/`:
+
+```
+~/.nuucognition/
+├── auth.json              # Production credentials (shared across all CLIs)
+├── auth.dev.json           # Development credentials
+├── .flint/config.toml      # Flint-specific config
+├── .vessel/config.toml     # Vessel-specific config
+└── .nuu/config.toml        # nuu CLI config
+```
+
+Auth credentials are shared — log in once, all CLIs are authenticated. Per-CLI config (mode, feature overrides) is scoped under `.<cliname>/`.
+
+## Quick Start
+
+```typescript
+import {
+  resolveRuntimeSync,
+  createFeatureRegistry,
+  isFeatureEnabled,
+  createLoginCommand,
+  createLogoutCommand,
+  createWhoamiCommand,
+  CliError,
+  error,
+  success,
+} from "@nuucognition/cli-core"
+import { Command } from "commander"
+
+// 1. Define your features
+const FEATURES = createFeatureRegistry([
+  { id: "init",    tier: "prod", type: "command", description: "Initialize workspace", requiresAuth: false },
+  { id: "sync",    tier: "prod", type: "command", description: "Sync configuration",  requiresAuth: false },
+  { id: "publish", tier: "exp",  type: "command", description: "Publish to registry",  requiresAuth: true },
+  { id: "agent",   tier: "dev",  type: "command", description: "Agent management",     requiresAuth: true },
+])
+
+// 2. Resolve runtime (reads config, checks auth)
+const runtime = resolveRuntimeSync({ cliname: "mycli" })
+const devAvailable = runtime.mode === "dev"
+
+// 3. Wire up auth commands
+const authConfig = {
+  cliname: "mycli",
+  defaultEnv: devAvailable ? "dev" as const : "prod" as const,
+  devAvailable,
+}
+
+const program = new Command()
+  .name("mycli")
+  .version("0.1.0")
+
+program.addCommand(createLoginCommand(authConfig))
+program.addCommand(createLogoutCommand(authConfig))
+program.addCommand(createWhoamiCommand(authConfig))
+
+// 4. Conditionally register feature-gated commands
+if (isFeatureEnabled(FEATURES, "publish", runtime)) {
+  program.addCommand(publishCommand)
+}
+
+await program.parseAsync(process.argv)
+```
+
+## API Reference
+
+### Feature Flags
+
+Three-tier system controlling what's available at runtime.
+
+**Tiers:**
+
+| Tier | Available when |
+|------|---------------|
+| `prod` | Always |
+| `exp` | In `dev` mode, or when explicitly opted in via config or `--enable` flag |
+| `dev` | Only in `dev` mode |
+
+**Registry:**
+
+```typescript
+import { createFeatureRegistry, getFeature, getFeaturesByTier, getCommandFeatures, hasFeature } from "@nuucognition/cli-core"
+
+const registry = createFeatureRegistry([
+  {
+    id: string,              // unique identifier
+    tier: "prod" | "exp" | "dev",
+    type: "command" | "function" | "module",
+    description: string,
+    requiresAuth: boolean,   // gate behind authentication
+    since?: string,          // version introduced
+    graduated?: string,      // version promoted to current tier
+    previousTier?: "dev" | "exp",
+    deprecated?: boolean,
+  },
+])
+
+getFeature(registry, "publish")           // FeatureDefinition | undefined
+getFeaturesByTier(registry, "exp")        // FeatureDefinition[]
+getCommandFeatures(registry)              // all command-type features
+hasFeature(registry, "publish")           // boolean
+```
+
+**Guards:**
+
+```typescript
+import { isFeatureEnabled, requireFeature, checkFeature } from "@nuucognition/cli-core"
+
+// Boolean check — use for conditional registration
+if (isFeatureEnabled(registry, "publish", runtime)) {
+  program.addCommand(publishCommand)
+}
+
+// Throws FeatureNotAvailableError or AuthRequiredError
+requireFeature(registry, "publish", runtime, "mycli")
+
+// Diagnostic — returns detailed availability info
+const check = checkFeature(registry, "publish", runtime)
+// { available, requiredTier, currentMode, experimental, requiresAuth, authenticated, reason? }
+```
+
+### Runtime Resolution
+
+Resolves mode, experimental status, per-feature overrides, and auth state.
+
+```typescript
+import { resolveRuntime, resolveRuntimeSync } from "@nuucognition/cli-core"
+
+// Sync (use at startup for command registration)
+const runtime = resolveRuntimeSync({ cliname: "mycli" })
+
+// Async
+const runtime = await resolveRuntime({ cliname: "mycli" })
+
+// runtime: {
+//   mode: "prod" | "dev",
+//   experimental: boolean,
+//   enabledFeatures: string[],    // from [features] config table
+//   authenticated: boolean,       // usable auth material exists
+// }
+```
+
+**Resolution chain (first match wins):**
+
+- **Mode:** config file `mode` field -> `BUILD_MODE` env -> `"dev"` default
+- **Experimental:** config file `experimental` field -> `false` in prod, `true` in dev
+- **Enabled features:** config file `[features]` table
+- **Authenticated:** checks `~/.nuucognition/auth.json` (or `auth.dev.json`) for a valid session or refresh token
+
+**Mutators:**
+
+```typescript
+import { setMode, resetMode, setExperimental, resetExperimental, setFeatureEnabled, resetFeatureEnabled } from "@nuucognition/cli-core"
+
+const config = { cliname: "mycli" }
+
+await setMode(config, "prod")              // write mode to config.toml
+await resetMode(config)                    // remove mode override
+await setExperimental(config, true)        // enable all exp features
+await setFeatureEnabled(config, "publish", true)  // enable one feature
+await resetFeatureEnabled(config, "publish")      // remove override
+```
+
+### Configuration
+
+Reads TOML config from `~/.nuucognition/.<cliname>/config.toml`.
+
+```typescript
+import { resolveConfig, resolveConfigSync, getConfigPath, ensureConfigDir } from "@nuucognition/cli-core"
+
+const config = resolveConfigSync({ cliname: "mycli" })
+// Reads ~/.nuucognition/.mycli/config.toml, merges with defaults
+
+const config = resolveConfigSync({
+  cliname: "mycli",
+  defaults: { someField: "fallback" },
+})
+
+getConfigPath("mycli")       // ~/.nuucognition/.mycli/config.toml
+await ensureConfigDir("mycli")  // creates dir if missing, returns path
+```
+
+**Config file format:**
+
+```toml
+mode = "prod"
+experimental = false
+
+[features]
+publish = true
+export = true
+```
+
+### Authentication
+
+Browser-based PKCE OAuth flow via Clerk. Credentials stored in `~/.nuucognition/`.
+
+**Credential storage:**
+
+```typescript
+import { loadAuth, loadAuthSync, saveAuth, clearAuth, hasAuth, getNuuDir, ensureNuuDir } from "@nuucognition/cli-core"
+
+// Load credentials
+const creds = await loadAuth("prod")     // NuuCredentials | null
+const creds = loadAuthSync("dev")        // sync variant
+
+// Save (creates ~/.nuucognition/ if needed)
+await saveAuth(creds, "prod")
+
+// Clear (deletes auth file)
+await clearAuth("prod")
+
+// Check if usable auth exists (sync, no network)
+hasAuth("prod")  // true if session valid or refresh token valid
+
+getNuuDir()           // ~/.nuucognition/
+await ensureNuuDir()  // create if missing
+```
+
+**NuuCredentials shape:**
+
+```typescript
+interface NuuCredentials {
+  sessionToken: string       // Clerk JWT
+  userId: string             // Clerk user ID
+  email: string
+  expiresAt: string          // ISO 8601
+  refreshToken?: string      // long-lived refresh token
+  refreshExpiresAt?: string  // ISO 8601
+  activeOrg?: {              // currently selected organisation
+    id: string               // Convex document ID
+    slug: string
+    name: string             // display name
+  }
+}
+```
+
+**Auth validation (load + auto-refresh):**
+
+```typescript
+import { getValidAuth, requireValidAuth } from "@nuucognition/cli-core"
+
+// Returns null if no valid auth (won't throw)
+const creds = await getValidAuth({ accountUrl, authEnv: "dev", cliname: "mycli" }, "dev")
+
+// Throws if not authenticated
+const creds = await requireValidAuth({ accountUrl, authEnv: "prod", cliname: "mycli" })
+```
+
+**Login flow (PKCE):**
+
+```typescript
+import { startLoginFlow, refreshAuth } from "@nuucognition/cli-core"
+
+// Opens browser, waits for callback, exchanges code, saves credentials
+const creds = await startLoginFlow({
+  accountUrl: "https://account.nuucognition.com",  // or "http://localhost:3000" for dev
+  authEnv: "prod",
+  callbackPort: 3847,  // default
+  cliname: "mycli",
+})
+
+// Manual refresh
+const refreshed = await refreshAuth(creds, { accountUrl, cliname: "mycli" })
+```
+
+### Auth Command Factories
+
+Pre-built commander commands for login, logout, whoami.
+
+```typescript
+import { createLoginCommand, createLogoutCommand, createWhoamiCommand } from "@nuucognition/cli-core"
+
+const authConfig = {
+  cliname: "mycli",                    // used in help text and error messages
+  defaultEnv: "prod" as const,        // default auth environment
+  devAvailable: true,                  // adds --dev flag to commands
+  prodAccountUrl?: string,             // override prod account URL
+  devAccountUrl?: string,              // override dev account URL
+  callbackPort?: number,               // override callback port (default 3847)
+}
+
+program.addCommand(createLoginCommand(authConfig))   // mycli login [--dev] [--verbose]
+program.addCommand(createLogoutCommand(authConfig))  // mycli logout [--dev]
+program.addCommand(createWhoamiCommand(authConfig))  // mycli whoami [--dev]
+```
+
+**whoami output:**
+```
+logged-in: user@example.com
+selected-org: NUU Cognition
+```
+
+### Output Helpers
+
+Consistent terminal output formatting using picocolors. Respects `NO_COLOR`.
+
+```typescript
+import { success, error, warn, info, dim, bold } from "@nuucognition/cli-core"
+
+success("Done")          // ✓ Done          (stdout, green)
+error("Failed")          // ✗ Failed        (stderr, red)
+warn("Careful")          // ! Careful       (stderr, yellow)
+info("Note")             // i Note          (stdout, blue)
+
+dim("muted text")        // returns dimmed string
+bold("emphasis")         // returns bold string
+```
+
+### Error Classes
+
+Structured errors with exit codes, error codes, and actionable suggestions.
+
+```typescript
+import { CliError, FeatureNotAvailableError, AuthRequiredError } from "@nuucognition/cli-core"
+
+// General CLI error
+throw new CliError("Config not found", 1, "CONFIG_NOT_FOUND", undefined, [
+  "Run `mycli init` to create a config file.",
+])
+
+// Feature gating errors (thrown by requireFeature)
+throw new FeatureNotAvailableError("publish", "exp", context, "mycli")
+// ✗ Feature 'publish' requires experimental access.
+//   Run `mycli --enable publish` for one invocation
+//   or set `[features].publish = true` in `~/.nuucognition/.mycli/config.toml`.
+
+throw new AuthRequiredError("publish", "mycli")
+// ✗ Feature 'publish' requires authentication.
+//   Run `mycli login` or `nuu login`.
+```
+
+### Environment Variables
+
+Utility for reading scoped env vars. Not used by runtime resolution — available for CLI-specific needs.
+
+```typescript
+import { scopedEnvVar, scopedEnvVarTrue } from "@nuucognition/cli-core"
+
+scopedEnvVar("mycli", "API_URL")     // reads NUU_MYCLI_API_URL
+scopedEnvVarTrue("mycli", "DEBUG")   // reads NUU_MYCLI_DEBUG, returns boolean
+```
+
+## Build Configuration
+
+CLIs using cli-core should bundle it via tsup `noExternal` when in the same monorepo:
+
+```typescript
+// tsup.config.ts
+import { defineConfig } from "tsup"
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm"],
+  target: "node20",
+  clean: true,
+  dts: true,
+  define: {
+    "process.env.BUILD_MODE": '"prod"',
+  },
+  noExternal: ["@nuucognition/cli-core"],
+})
+```
+
+## Types
+
+All types are exported for use in consuming CLIs:
+
+```typescript
+import type {
+  FeatureDefinition,
+  FeatureRegistry,
+  FeatureContext,
+  FeatureCheck,
+  FeatureTier,       // "prod" | "exp" | "dev"
+  FeatureType,       // "command" | "function" | "module"
+  RuntimeMode,       // "prod" | "dev"
+  AuthEnvironment,   // "prod" | "dev"
+  ResolvedRuntime,
+  ModeConfig,
+  ConfigOptions,
+  NuuCredentials,
+  LoginConfig,
+  AuthCommandFactoryConfig,
+} from "@nuucognition/cli-core"
+```

package/dist/index.d.ts

@@ -0,0 +1,150 @@
+import { Command } from 'commander';
+
+type FeatureTier = "prod" | "exp" | "dev";
+type FeatureType = "command" | "function" | "module";
+type RuntimeMode = "prod" | "dev";
+type AuthEnvironment = RuntimeMode;
+interface FeatureDefinition {
+    id: string;
+    tier: FeatureTier;
+    type: FeatureType;
+    description: string;
+    requiresAuth: boolean;
+    since?: string;
+    graduated?: string;
+    previousTier?: "dev" | "exp";
+    deprecated?: boolean;
+}
+interface FeatureRegistry {
+    readonly features: readonly FeatureDefinition[];
+}
+interface FeatureContext {
+    mode: RuntimeMode;
+    experimental: boolean;
+    enabledFeatures: string[];
+    authenticated: boolean;
+}
+interface FeatureCheck {
+    available: boolean;
+    requiredTier: FeatureTier;
+    currentMode: RuntimeMode;
+    experimental: boolean;
+    requiresAuth: boolean;
+    authenticated: boolean;
+    reason?: string;
+}
+interface ModeConfig {
+    cliname: string;
+}
+interface ResolvedRuntime extends FeatureContext {
+}
+interface ConfigOptions {
+    cliname: string;
+    defaults?: Record<string, unknown>;
+}
+interface NuuCredentials {
+    sessionToken: string;
+    userId: string;
+    email: string;
+    expiresAt: string;
+    refreshToken?: string;
+    refreshExpiresAt?: string;
+    activeOrg?: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+}
+interface LoginConfig {
+    accountUrl: string;
+    authEnv?: AuthEnvironment;
+    callbackPort?: number;
+    cliname?: string;
+}
+declare const NUU_ACCOUNT_URL_PROD = "https://account.nuucognition.com";
+declare const NUU_ACCOUNT_URL_DEV = "http://localhost:3000";
+interface AuthCommandFactoryConfig {
+    cliname?: string;
+    prodAccountUrl?: string;
+    devAccountUrl?: string;
+    defaultEnv?: AuthEnvironment;
+    callbackPort?: number;
+    devAvailable?: boolean;
+}
+declare const TIER_ALIASES: Record<string, FeatureTier>;
+declare function normalizeTier(input: string): FeatureTier | undefined;
+declare function isValidTier(input: string): boolean;
+declare function normalizeRuntimeMode(input: string): RuntimeMode | undefined;
+
+declare function scopedEnvVar(cliname: string, field: string): string | undefined;
+declare function scopedEnvVarTrue(cliname: string, field: string): boolean;
+
+declare function getConfigDir(cliname: string): string;
+declare function getConfigPath(cliname: string): string;
+declare function ensureConfigDir(cliname: string): Promise<string>;
+declare function ensureConfigDirSync(cliname: string): string;
+declare function resolveConfig(options: ConfigOptions): Promise<Record<string, unknown>>;
+declare function resolveConfigSync(options: ConfigOptions): Record<string, unknown>;
+
+declare function createFeatureRegistry(features: FeatureDefinition[]): FeatureRegistry;
+declare function getFeature(registry: FeatureRegistry, id: string): FeatureDefinition | undefined;
+declare function getFeaturesByTier(registry: FeatureRegistry, tier: FeatureTier): FeatureDefinition[];
+declare function getFeaturesByType(registry: FeatureRegistry, type: FeatureType): FeatureDefinition[];
+declare function getCommandFeatures(registry: FeatureRegistry): FeatureDefinition[];
+declare function hasFeature(registry: FeatureRegistry, id: string): boolean;
+
+declare function isTierEnabled(featureTier: "prod" | "exp" | "dev", mode: RuntimeMode): boolean;
+declare function resolveRuntime(config: ModeConfig): Promise<ResolvedRuntime>;
+declare function resolveRuntimeSync(config: ModeConfig): ResolvedRuntime;
+declare function setMode(config: ModeConfig, mode: RuntimeMode): Promise<void>;
+declare function resetMode(config: ModeConfig): Promise<void>;
+declare function setExperimental(config: ModeConfig, enabled: boolean): Promise<void>;
+declare function resetExperimental(config: ModeConfig): Promise<void>;
+declare function setFeatureEnabled(config: ModeConfig, featureId: string, enabled: boolean): Promise<void>;
+declare function resetFeatureEnabled(config: ModeConfig, featureId: string): Promise<void>;
+
+declare function isFeatureEnabled(registry: FeatureRegistry, id: string, context: FeatureContext): boolean;
+declare function requireFeature(registry: FeatureRegistry, id: string, context: FeatureContext, cliname: string): void;
+declare function checkFeature(registry: FeatureRegistry, id: string, context: FeatureContext): FeatureCheck;
+
+declare function setAuthVerbose(enabled: boolean): void;
+declare function getNuuDir(): string;
+declare function ensureNuuDir(): Promise<string>;
+declare function loadAuth(env?: AuthEnvironment): Promise<NuuCredentials | null>;
+declare function loadAuthSync(env?: AuthEnvironment): NuuCredentials | null;
+declare function saveAuth(creds: NuuCredentials, env?: AuthEnvironment): Promise<void>;
+declare function clearAuth(env?: AuthEnvironment): Promise<void>;
+declare function hasAuth(env?: AuthEnvironment): boolean;
+declare function startLoginFlow(config: LoginConfig): Promise<NuuCredentials>;
+declare function refreshAuth(creds: NuuCredentials, config: LoginConfig): Promise<NuuCredentials>;
+declare function getValidAuth(config: LoginConfig, env?: AuthEnvironment): Promise<NuuCredentials | null>;
+declare function requireValidAuth(config: LoginConfig, env?: AuthEnvironment): Promise<NuuCredentials>;
+declare function isAuthExpired(credentials: NuuCredentials): boolean;
+declare function shouldRefreshAuth(credentials: NuuCredentials): boolean;
+
+declare function createLoginCommand(config: AuthCommandFactoryConfig): Command;
+declare function createLogoutCommand(config: AuthCommandFactoryConfig): Command;
+declare function createWhoamiCommand(config: AuthCommandFactoryConfig): Command;
+
+declare function success(message: string): void;
+declare function error(message: string): void;
+declare function warn(message: string): void;
+declare function info(message: string): void;
+declare function dim(message: string): string;
+declare function bold(message: string): string;
+
+declare class CliError extends Error {
+    readonly exitCode: number;
+    readonly code?: string;
+    readonly ref?: string;
+    readonly suggestions?: string[];
+    constructor(message: string, exitCode?: number, code?: string, ref?: string, suggestions?: string[]);
+}
+declare class FeatureNotAvailableError extends CliError {
+    constructor(featureId: string, requiredTier: FeatureTier, context: FeatureContext, cliname: string);
+}
+declare class AuthRequiredError extends CliError {
+    constructor(featureId: string, cliname: string);
+}
+
+export { type AuthCommandFactoryConfig, type AuthEnvironment, AuthRequiredError, CliError, type ConfigOptions, type FeatureCheck, type FeatureContext, type FeatureDefinition, FeatureNotAvailableError, type FeatureRegistry, type FeatureTier, type FeatureType, type LoginConfig, type ModeConfig, NUU_ACCOUNT_URL_DEV, NUU_ACCOUNT_URL_PROD, type NuuCredentials, type ResolvedRuntime, type RuntimeMode, TIER_ALIASES, bold, checkFeature, clearAuth, createFeatureRegistry, createLoginCommand, createLogoutCommand, createWhoamiCommand, dim, ensureConfigDir, ensureConfigDirSync, ensureNuuDir, error, getCommandFeatures, getConfigDir, getConfigPath, getFeature, getFeaturesByTier, getFeaturesByType, getNuuDir, getValidAuth, hasAuth, hasFeature, info, isAuthExpired, isFeatureEnabled, isTierEnabled, isValidTier, loadAuth, loadAuthSync, normalizeRuntimeMode, normalizeTier, refreshAuth, requireFeature, requireValidAuth, resetExperimental, resetFeatureEnabled, resetMode, resolveConfig, resolveConfigSync, resolveRuntime, resolveRuntimeSync, saveAuth, scopedEnvVar, scopedEnvVarTrue, setAuthVerbose, setExperimental, setFeatureEnabled, setMode, shouldRefreshAuth, startLoginFlow, success, warn };