@knowzai/cli 0.1.0 → 0.3.0

package/dist/lib/login.d.ts

@@ -1,16 +1,32 @@
 import { type CredentialStore, type KnowzConfig, type KeyType } from '@knowzai/core';
-import type { RegisterResult, VerifyResult } from '@knowzai/types';
-export type LoginMode = 'paste' | 'register' | 'self-hosted';
+import type { CreateApiKeyRequest, CreatedApiKey, LoginTokenResult, RegisterResult, RegisterTenantRequest, VerifyResult } from '@knowzai/types';
+export type LoginMode = 'paste' | 'register' | 'self-hosted' | 'sso';
+/**
+ * 13+ attestation the API requires on new-account creation. Mirrors
+ * `AgeEligibilityCopy` on the server and `AGE_ELIGIBILITY_COPY_VERSION` in the
+ * web client — bump together when the copy changes.
+ */
+export declare const AGE_ELIGIBILITY_COPY_VERSION = "age_eligibility.v1";
+export declare const AGE_ELIGIBILITY_SURFACE = "cli_register";
+export declare const AGE_ELIGIBILITY_TEXT = "I confirm I am at least 13 years old. Knowz is not available to people under 13.";
+export declare const AGE_ELIGIBILITY_UNDER_13_MESSAGE = "Knowz is not available to people under 13. No account was created.";
+export interface RegisterInput {
+    name: string;
+    email: string;
+    /**
+     * Required whenever the server does not hand back an API key at registration
+     * (the current contract): the CLI signs in with it and then creates a key.
+     */
+    password?: string;
+    /** The person explicitly confirmed the 13+ attestation. */
+    ageAttested?: boolean;
+}
 export interface LoginInput {
     profile: string;
     apiUrl: string;
     mode: LoginMode;
     key?: string;
-    register?: {
-        name: string;
-        email: string;
-        password?: string;
-    };
+    register?: RegisterInput;
     storeTenantKey?: boolean;
     force?: boolean;
 }
@@ -19,17 +35,47 @@ export interface LoginDeps {
     config: KnowzConfig;
     saveConfig: (cfg: KnowzConfig) => void;
     validateKey: (apiKey: string) => Promise<VerifyResult>;
-    register: (req: {
-        name: string;
-        email: string;
-        password?: string;
-    }) => Promise<RegisterResult>;
+    register: (req: RegisterTenantRequest) => Promise<RegisterResult>;
+    /** Email/password sign-in (`POST /api/v1/users/login`) — yields a bearer token. */
+    signIn: (req: {
+        usernameOrEmail: string;
+        password: string;
+    }) => Promise<LoginTokenResult>;
+    /** Explicit key creation (`POST /api/v1/api-keys`) authenticated with that token. */
+    createApiKey: (req: CreateApiKeyRequest, token: string) => Promise<CreatedApiKey>;
+    /**
+     * Interactive "replace the credentials this profile already holds?" prompt.
+     * Absent means non-interactive (scripts, `--json`, no TTY): a wrong-tenant
+     * overwrite is refused outright and a same-tenant key rotation goes through.
+     */
+    confirmReplace?: (ctx: ReplaceContext) => Promise<boolean>;
+}
+/** Which tenant a profile is bound to, as far as we can name it. */
+export interface TenantRef {
+    id?: string;
+    name?: string;
+}
+/** What `confirmReplace` is being asked about. Never carries a key. */
+export interface ReplaceContext {
+    profile: string;
+    /** True when the incoming key belongs to the tenant the profile already holds. */
+    sameTenant: boolean;
+    current: TenantRef;
+    incoming: TenantRef;
 }
+/** "Alex Space (0f0…)"-style label: name when the server gave us one, else the id. */
+export declare function tenantLabel(ref: TenantRef | undefined): string;
 export interface LoginResult {
     profile: string;
     keyType?: KeyType;
     tenantId?: string;
+    /** Display name of the tenant, when the server reported one. */
+    tenantName?: string;
     email?: string;
+    /** True when the key was minted explicitly after registering (the normal path). */
+    createdApiKey?: boolean;
+    /** True when the profile already held a key for this same tenant (rotation). */
+    alreadyRegistered?: boolean;
 }
 /**
  * Verify-on-login, persist-after-verify (S-N3-6). Never returns or logs the key.

package/dist/lib/login.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../src/lib/login.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,OAAO,EACb,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnE,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,aAAa,CAAC;AAE7D,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,eAAe,CAAC;IACvB,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,IAAI,CAAC;IACvC,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACvD,QAAQ,EAAE,CAAC,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;CAChG;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAsD3F"}
+{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../src/lib/login.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,OAAO,EACb,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAEV,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,YAAY,EACb,MAAM,gBAAgB,CAAC;AAGxB,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,aAAa,GAAG,KAAK,CAAC;AAErE;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,uBAAuB,CAAC;AACjE,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AACtD,eAAO,MAAM,oBAAoB,qFACmD,CAAC;AACrF,eAAO,MAAM,gCAAgC,uEACyB,CAAC;AAEvE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,eAAe,CAAC;IACvB,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,IAAI,CAAC;IACvC,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACvD,QAAQ,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mFAAmF;IACnF,MAAM,EAAE,CAAC,GAAG,EAAE;QAAE,eAAe,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC1F,qFAAqF;IACrF,YAAY,EAAE,CAAC,GAAG,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAClF;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5D;AAED,oEAAoE;AACpE,MAAM,WAAW,SAAS;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,SAAS,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,GAAG,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAK9D;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAkHD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAwG3F"}

package/dist/lib/login.js

@@ -1,4 +1,118 @@
-import { KnowzError, ExitCode, enforceTls, validateKeyFormat, keyType, } from '@knowzai/core';
+import { KnowzError, ExitCode, enforceTls, registerSecret, validateKeyFormat, keyType, } from '@knowzai/core';
+import { quoteArg } from './claude-hooks.js';
+/**
+ * 13+ attestation the API requires on new-account creation. Mirrors
+ * `AgeEligibilityCopy` on the server and `AGE_ELIGIBILITY_COPY_VERSION` in the
+ * web client — bump together when the copy changes.
+ */
+export const AGE_ELIGIBILITY_COPY_VERSION = 'age_eligibility.v1';
+export const AGE_ELIGIBILITY_SURFACE = 'cli_register';
+export const AGE_ELIGIBILITY_TEXT = 'I confirm I am at least 13 years old. Knowz is not available to people under 13.';
+export const AGE_ELIGIBILITY_UNDER_13_MESSAGE = 'Knowz is not available to people under 13. No account was created.';
+/** "Alex Space (0f0…)"-style label: name when the server gave us one, else the id. */
+export function tenantLabel(ref) {
+    const name = ref?.name?.trim();
+    const id = ref?.id?.trim();
+    if (name && id)
+        return `${name} (${id})`;
+    return name || id || 'an unknown tenant';
+}
+/** Label the key carries in the workspace's key list, so it is recognizable there. */
+function apiKeyName(profile) {
+    return `knowz CLI (${profile})`;
+}
+/**
+ * Register, then obtain a real API key. Registration no longer returns one
+ * (#661: `PersonalApiKey` is documented as always null), so the CLI signs in
+ * with the password and calls `POST /api/v1/api-keys`. A legacy build that
+ * still mints keys is honored as-is — no second key is created.
+ */
+async function keyForRegistration(input, deps, reg) {
+    const wantTenantKey = Boolean(input.storeTenantKey);
+    const res = await deps
+        .register({
+        name: reg.name,
+        email: reg.email,
+        ...(reg.password === undefined ? {} : { password: reg.password }),
+        // Only sent when the person actually attested — never auto-checked.
+        ...(reg.ageAttested
+            ? {
+                ageEligibilityAttested: true,
+                ageEligibilityCopyVersion: AGE_ELIGIBILITY_COPY_VERSION,
+                ageEligibilitySurface: AGE_ELIGIBILITY_SURFACE,
+            }
+            : {}),
+    })
+        .catch((e) => {
+        // The server enforces the 13+ gate; point at the flag that satisfies it.
+        const text = e instanceof Error ? e.message : String(e);
+        if (!reg.ageAttested && /at least 13|age confirmation|AGE_ELIGIBILITY/i.test(text)) {
+            throw new KnowzError(`${text} Pass --age-13-plus to confirm.`, ExitCode.Usage);
+        }
+        throw e;
+    });
+    const legacy = wantTenantKey ? res.apiKey : res.userApiKey;
+    if (legacy && validateKeyFormat(legacy.trim()).ok) {
+        return { key: legacy.trim(), created: false, tenantId: res.tenantId, userId: res.userId };
+    }
+    // No usable key in the response → sign in (or reuse a token the register
+    // endpoint issued) and create one explicitly.
+    let token = res.token;
+    let tenantId = res.tenantId;
+    let userId = res.userId;
+    if (!token) {
+        if (!reg.password) {
+            throw new KnowzError('Registration does not return an API key any more; the CLI has to sign in and create one. ' +
+                'Re-run with --password (it is also the password for the web app).', ExitCode.Usage);
+        }
+        const session = await deps.signIn({ usernameOrEmail: reg.email, password: reg.password });
+        token = session.token;
+        tenantId = session.tenantId || tenantId;
+        userId = session.userId ?? userId;
+    }
+    registerSecret(token);
+    const wanted = wantTenantKey ? 'tenant' : 'user';
+    const created = await deps.createApiKey({ name: apiKeyName(input.profile), keyType: wanted }, token);
+    const key = created.key?.trim();
+    if (!key) {
+        throw new KnowzError('Creating an API key after registration failed: the server returned no key.', ExitCode.Auth);
+    }
+    const fmt = validateKeyFormat(key);
+    if (!fmt.ok) {
+        throw new KnowzError(`Creating an API key after registration failed: ${fmt.reason}`, ExitCode.Auth);
+    }
+    return { key, created: true, tenantId, userId };
+}
+/**
+ * Best-effort display name for the tenant a profile is already bound to. The
+ * stored key is the only thing that knows it, so we re-validate it — but a
+ * revoked/offline key must not turn an explanatory message into a failure, so
+ * every error degrades to "no name" and the caller falls back to the id.
+ */
+async function storedTenantName(storedKey, storedTenantId, deps) {
+    try {
+        const v = await deps.validateKey(storedKey);
+        if (!v.isValid)
+            return undefined;
+        // Guard against a stale binding: only trust the name if it is this tenant.
+        if (storedTenantId && v.tenant?.id && v.tenant.id !== storedTenantId)
+            return undefined;
+        return v.tenant?.name;
+    }
+    catch {
+        return undefined;
+    }
+}
+function sameApiUrl(left, right) {
+    if (!left)
+        return false;
+    try {
+        return new URL(left).href.replace(/\/+$/u, '') === new URL(right).href.replace(/\/+$/u, '');
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Verify-on-login, persist-after-verify (S-N3-6). Never returns or logs the key.
  * Throws KnowzError(Auth) on rejected credentials, KnowzError(Usage) on bad
@@ -9,14 +123,22 @@ export async function performLogin(input, deps) {
     let key;
     let verify;
     let email;
+    let createdApiKey = false;
+    if (input.mode === 'sso') {
+        throw new KnowzError('SSO login must mint a key before persist', ExitCode.Usage);
+    }
     if (input.mode === 'register') {
         if (!input.register?.email || !input.register?.name) {
             throw new KnowzError('register requires --email and --name', ExitCode.Usage);
         }
-        const res = await deps.register(input.register);
-        key = input.storeTenantKey ? res.apiKey : res.userApiKey;
+        const reg = await keyForRegistration(input, deps, input.register);
+        key = reg.key;
+        createdApiKey = reg.created;
         email = input.register.email;
-        verify = { isValid: true, tenant: { id: res.tenantId }, user: { id: '', email } };
+        // The key was just issued by an authenticated call, so it needs no second
+        // round-trip to validate — re-verifying would also fail on a tenant that
+        // starts in the Pending activation state.
+        verify = { isValid: true, tenant: { id: reg.tenantId ?? '' }, user: { id: reg.userId ?? '', email } };
     }
     else {
         if (!input.key)
@@ -31,26 +153,62 @@ export async function performLogin(input, deps) {
         }
         email = verify.user?.email;
     }
-    // Wrong-tenant overwrite guard (S-N3-6).
+    registerSecret(key);
+    // Already-registered guard (S-N3-6, #669). A profile that already holds a key
+    // is never silently re-pointed: a different tenant is refused without --force,
+    // and even a same-tenant rotation asks first when there is someone to ask.
     const existing = await deps.store.getSecret(input.profile);
-    if (existing && !input.force) {
-        const existingTenant = deps.config.profiles[input.profile]?.tenantId;
-        const newTenant = verify.tenant?.id;
-        if (existingTenant && newTenant && existingTenant !== newTenant) {
-            throw new KnowzError(`Profile '${input.profile}' already holds credentials for a different tenant. Pass --force to overwrite.`, ExitCode.Usage);
+    const existingTenantId = deps.config.profiles[input.profile]?.tenantId;
+    const incoming = { id: verify.tenant?.id, name: verify.tenant?.name };
+    const sameTenant = Boolean(existing && existingTenantId && incoming.id && existingTenantId === incoming.id);
+    const differentTenant = Boolean(existing && existingTenantId && incoming.id && existingTenantId !== incoming.id);
+    // Without a prompt, a same-tenant rotation needs no decision and no explanation,
+    // so it must not pay for the extra round-trip the tenant name costs.
+    const needsDecision = !input.force && (sameTenant || differentTenant) && (Boolean(deps.confirmReplace) || differentTenant);
+    if (needsDecision) {
+        // Only now is a name worth a round-trip: we are about to talk to a human.
+        const storedApiUrl = deps.config.profiles[input.profile]?.apiUrl;
+        const current = {
+            id: existingTenantId,
+            name: sameApiUrl(storedApiUrl, input.apiUrl)
+                ? await storedTenantName(existing, existingTenantId, deps)
+                : undefined,
+        };
+        const ctx = { profile: input.profile, sameTenant, current, incoming };
+        const confirmed = deps.confirmReplace
+            ? await deps.confirmReplace(ctx)
+            : // No prompt available: rotating the same tenant's key is safe, moving the
+                // profile to another tenant is not.
+                sameTenant;
+        if (!confirmed) {
+            const quotedProfile = quoteArg(input.profile);
+            throw new KnowzError(differentTenant
+                ? `Profile '${input.profile}' is already registered to tenant ${tenantLabel(current)}. ` +
+                    `The key you provided belongs to tenant ${tenantLabel(incoming)}. ` +
+                    `Nothing was changed. To replace it, re-run: knowz login --profile ${quotedProfile} --force`
+                : `Profile '${input.profile}' is already registered to tenant ${tenantLabel(current)}. ` +
+                    `The stored key was left unchanged. To replace it, re-run: knowz login --profile ${quotedProfile} --force`, ExitCode.Usage);
         }
     }
     await deps.store.setSecret(input.profile, key);
     const prev = deps.config.profiles[input.profile];
     deps.config.profiles[input.profile] = {
         apiUrl: input.apiUrl,
-        tenantId: verify.tenant?.id ?? prev?.tenantId,
+        tenantId: verify.tenant?.id || prev?.tenantId,
         email: email ?? prev?.email,
         label: prev?.label,
         defaultVaultId: prev?.defaultVaultId,
     };
     deps.config.activeProfile = input.profile;
     deps.saveConfig(deps.config);
-    return { profile: input.profile, keyType: keyType(key), tenantId: verify.tenant?.id, email };
+    return {
+        profile: input.profile,
+        keyType: keyType(key),
+        tenantId: verify.tenant?.id || undefined,
+        ...(verify.tenant?.name ? { tenantName: verify.tenant.name } : {}),
+        email,
+        ...(createdApiKey ? { createdApiKey: true } : {}),
+        ...(sameTenant ? { alreadyRegistered: true } : {}),
+    };
 }
 //# sourceMappingURL=login.js.map

package/dist/lib/login.js.map

@@ -1 +1 @@
-{"version":3,"file":"login.js","sourceRoot":"","sources":["../../src/lib/login.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"login.js","sourceRoot":"","sources":["../../src/lib/login.ts"],"names":[],"mappings":"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"}

package/dist/lib/onboarding.d.ts

@@ -0,0 +1,56 @@
+/**
+ * First-run onboarding + the client-side auth gate.
+ *
+ * Two problems this module owns:
+ *
+ *  1. A freshly installed CLI had no idea whether you were signed in. Every
+ *     cloud command built an *anonymous* api-client, fired the request, and let
+ *     the server answer 401. That is a slow, confusing "it let me do it and
+ *     then it didn't" experience — and in an interactive terminal there was
+ *     nothing telling the user that `knowz login` even exists.
+ *  2. Nothing ever offered to sign you in. Login was buried at
+ *     Settings → Authentication → Log in.
+ *
+ * The decision logic lives here as pure functions so it is unit-testable
+ * without a TTY, a keychain, or a network. `base-command.ts` and `menu.ts` are
+ * the only IO shells that consume it.
+ */
+/** Everything the gate needs to know about the current invocation. */
+export interface AuthGateContext {
+    /** A credential is present for the resolved profile. */
+    authenticated: boolean;
+    /** Both stdin and stdout are TTYs — we may prompt. */
+    interactive: boolean;
+    /** `--json` was passed: output must stay a single machine-readable document. */
+    jsonMode: boolean;
+}
+/**
+ * What a command needing the cloud API should do.
+ * - `proceed` — a credential exists, carry on.
+ * - `prompt`  — interactive human terminal: offer guided login inline, then retry.
+ * - `fail`    — script/CI/`--json`: never block on stdin, fail fast with exit 3.
+ */
+export type AuthGateDecision = 'proceed' | 'prompt' | 'fail';
+export declare function decideAuthGate(ctx: AuthGateContext): AuthGateDecision;
+/** True when both standard streams are a terminal, i.e. a human is watching. */
+export declare function isInteractiveTty(streams?: {
+    stdin?: unknown;
+    stdout?: unknown;
+}): boolean;
+/**
+ * The message shown when we cannot (or must not) prompt. It names the profile
+ * and backend deliberately: the single most common support question is "why is
+ * my data missing", and the answer is almost always that the CLI is pointed at
+ * a different estate than the user assumed.
+ */
+export declare function notAuthenticatedMessage(profile: string, apiUrl: string): string;
+/** The inline offer shown in an interactive terminal before the guided login. */
+export declare function loginInvitation(profile: string, apiUrl: string): string;
+/**
+ * Whether the interactive shell should open onboarding instead of the normal
+ * menu. Kept separate from `decideAuthGate` because the menu tolerates an
+ * anonymous session (you must be able to reach "Log in" without being logged
+ * in) — it just shouldn't *start* there silently on a fresh install.
+ */
+export declare function shouldOnboard(ctx: AuthGateContext): boolean;
+//# sourceMappingURL=onboarding.d.ts.map

package/dist/lib/onboarding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.d.ts","sourceRoot":"","sources":["../../src/lib/onboarding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,aAAa,EAAE,OAAO,CAAC;IACvB,sDAAsD;IACtD,WAAW,EAAE,OAAO,CAAC;IACrB,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE7D,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,gBAAgB,CAIrE;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAY,GAAG,OAAO,CAGlG;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAW/E;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQvE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAE3D"}

package/dist/lib/onboarding.js

@@ -0,0 +1,67 @@
+/**
+ * First-run onboarding + the client-side auth gate.
+ *
+ * Two problems this module owns:
+ *
+ *  1. A freshly installed CLI had no idea whether you were signed in. Every
+ *     cloud command built an *anonymous* api-client, fired the request, and let
+ *     the server answer 401. That is a slow, confusing "it let me do it and
+ *     then it didn't" experience — and in an interactive terminal there was
+ *     nothing telling the user that `knowz login` even exists.
+ *  2. Nothing ever offered to sign you in. Login was buried at
+ *     Settings → Authentication → Log in.
+ *
+ * The decision logic lives here as pure functions so it is unit-testable
+ * without a TTY, a keychain, or a network. `base-command.ts` and `menu.ts` are
+ * the only IO shells that consume it.
+ */
+export function decideAuthGate(ctx) {
+    if (ctx.authenticated)
+        return 'proceed';
+    if (ctx.jsonMode || !ctx.interactive)
+        return 'fail';
+    return 'prompt';
+}
+/** True when both standard streams are a terminal, i.e. a human is watching. */
+export function isInteractiveTty(streams = process) {
+    const s = streams;
+    return Boolean(s.stdin?.isTTY) && Boolean(s.stdout?.isTTY);
+}
+/**
+ * The message shown when we cannot (or must not) prompt. It names the profile
+ * and backend deliberately: the single most common support question is "why is
+ * my data missing", and the answer is almost always that the CLI is pointed at
+ * a different estate than the user assumed.
+ */
+export function notAuthenticatedMessage(profile, apiUrl) {
+    let host = apiUrl;
+    try {
+        host = new URL(apiUrl).host;
+    }
+    catch {
+        /* keep the raw string when it isn't a URL */
+    }
+    return (`Not signed in — profile '${profile}' (${host}) has no stored API key. ` +
+        `Run \`knowz login\` to sign in, register, or connect a self-hosted instance.`);
+}
+/** The inline offer shown in an interactive terminal before the guided login. */
+export function loginInvitation(profile, apiUrl) {
+    let host = apiUrl;
+    try {
+        host = new URL(apiUrl).host;
+    }
+    catch {
+        /* keep the raw string when it isn't a URL */
+    }
+    return `You're not signed in yet (profile '${profile}' → ${host}). Let's fix that.`;
+}
+/**
+ * Whether the interactive shell should open onboarding instead of the normal
+ * menu. Kept separate from `decideAuthGate` because the menu tolerates an
+ * anonymous session (you must be able to reach "Log in" without being logged
+ * in) — it just shouldn't *start* there silently on a fresh install.
+ */
+export function shouldOnboard(ctx) {
+    return !ctx.authenticated && ctx.interactive && !ctx.jsonMode;
+}
+//# sourceMappingURL=onboarding.js.map

package/dist/lib/onboarding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.js","sourceRoot":"","sources":["../../src/lib/onboarding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAoBH,MAAM,UAAU,cAAc,CAAC,GAAoB;IACjD,IAAI,GAAG,CAAC,aAAa;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,GAAG,CAAC,QAAQ,IAAI,CAAC,GAAG,CAAC,WAAW;QAAE,OAAO,MAAM,CAAC;IACpD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,gBAAgB,CAAC,UAAiD,OAAO;IACvF,MAAM,CAAC,GAAG,OAAwE,CAAC;IACnF,OAAO,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAe,EAAE,MAAc;IACrE,IAAI,IAAI,GAAG,MAAM,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,6CAA6C;IAC/C,CAAC;IACD,OAAO,CACL,4BAA4B,OAAO,MAAM,IAAI,2BAA2B;QACxE,8EAA8E,CAC/E,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,MAAc;IAC7D,IAAI,IAAI,GAAG,MAAM,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,6CAA6C;IAC/C,CAAC;IACD,OAAO,sCAAsC,OAAO,OAAO,IAAI,oBAAoB,CAAC;AACtF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,GAAoB;IAChD,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,GAAG,CAAC,WAAW,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC;AAChE,CAAC"}

package/dist/lib/peer-command.d.ts

@@ -0,0 +1,51 @@
+import { type KnowzApiClient, type FederationPeer, type FederationSyncOptionsInput } from '@knowzai/api-client';
+import { BaseCommand, type GlobalFlags } from '../base-command.js';
+export interface PeerGlobalFlags extends GlobalFlags {
+    email?: string;
+}
+/**
+ * Shared shell for every `knowz peer` command (CLI_InstanceTransfer R8):
+ * builds a per-invocation Bearer-token client via `users/login` — the
+ * federation plane is JWT-only, the stored API key cannot reach it — and
+ * decorates federation refusals with actionable hints (R10). The credential
+ * store keeps holding ONLY the API key; the password/token never persist.
+ */
+export declare abstract class PeerCommand extends BaseCommand {
+    static readonly peerAuthFlags: {
+        email: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    protected peerInteractive(): boolean;
+    /** Bearer-token client for the active profile (R8). */
+    protected peerApiClient(flags: PeerGlobalFlags): Promise<KnowzApiClient>;
+    /** Attach the R10 follow-up hint to federation refusals, then rethrow. */
+    protected withFederationHints<T>(fn: () => Promise<T>): Promise<T>;
+    /** Resolve `<peerRef>` (GUID or slug) to the peer row. */
+    protected resolvePeer(client: KnowzApiClient, ref: string): Promise<FederationPeer>;
+    /** Source + preflight the peer credential (R9). */
+    protected resolveKeyInput(keyFlag: string | undefined): Promise<string>;
+    /** Compact human rendering for a peer row. */
+    protected describePeer(peer: FederationPeer): string;
+    /**
+     * Shared `peer pull` / `peer push` body (R12): 202 + runId; `--wait` polls
+     * every 2 s to a terminal status; exit 0 ONLY on Succeeded/NoOp — the server
+     * status is trusted, never re-interpreted.
+     */
+    protected enqueueSyncRun(direction: 'pull' | 'push', input: {
+        client: KnowzApiClient;
+        peerRef: string;
+        vaultLinkId: string;
+        options: FederationSyncOptionsInput;
+        wait: boolean;
+        timeoutSeconds: number;
+    }): Promise<unknown>;
+}
+/** Flag set shared by `peer pull` and `peer push`. */
+export declare const syncRunFlags: {
+    link: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    since: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'skip-re-enrichment': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    'max-file-mb': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    wait: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    timeout: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+};
+//# sourceMappingURL=peer-command.d.ts.map

package/dist/lib/peer-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-command.d.ts","sourceRoot":"","sources":["../../src/lib/peer-command.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,0BAA0B,EAChC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAanE,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,8BAAsB,WAAY,SAAQ,WAAW;IACnD,MAAM,CAAC,QAAQ,CAAC,aAAa;;MAI3B;IAEF,SAAS,CAAC,eAAe,IAAI,OAAO;IAIpC,uDAAuD;cACvC,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAuB9E,0EAA0E;cAC1D,mBAAmB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAUxE,0DAA0D;IAC1D,SAAS,CAAC,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAInF,mDAAmD;IACnD,SAAS,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAUvE,8CAA8C;IAC9C,SAAS,CAAC,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM;IAMpD;;;;OAIG;cACa,cAAc,CAC5B,SAAS,EAAE,MAAM,GAAG,MAAM,EAC1B,KAAK,EAAE;QACL,MAAM,EAAE,cAAc,CAAC;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,0BAA0B,CAAC;QACpC,IAAI,EAAE,OAAO,CAAC;QACd,cAAc,EAAE,MAAM,CAAC;KACxB,GACA,OAAO,CAAC,OAAO,CAAC;CA4BpB;AAED,sDAAsD;AACtD,eAAO,MAAM,YAAY;;;;;;;CAOxB,CAAC"}