melchizedek-agents 1.1.0 → 1.3.0

package/dist/lib/onboarding.d.ts

@@ -0,0 +1,135 @@
+/**
+ * lib/onboarding.ts — the authentication levels and their startup guides.
+ *
+ * WHY this file exists:
+ *   A newcomer arrives with something: no key, one provider's key, several, a
+ *   gateway key, a cloud account, a server to put in front of other people,
+ *   a ChatGPT plan on their own machine (Sign in with ChatGPT, ADR 0126), or
+ *   a Claude.ai / Gemini CLI / Codex CLI sign-in. Each of those is a
+ *   different first ten minutes. This module names those levels once, from
+ *   what the engine actually supports (lib/models/providerMap.ts,
+ *   endpoints.ts, gateway.ts, the A2A server's identity modes and the OAuth
+ *   grant setup), and renders one startup guide per level. The
+ *   `melchizedek-setup` menu prints these guides and ONBOARDING.md is
+ *   generated from the same function, so the two cannot drift
+ *   (tests/onboarding.test.ts holds them equal).
+ *
+ * DETECTION IS THE DOCTOR'S:
+ *   `detectLevels` reads a DoctorResult (lib/doctor.ts: the providers line,
+ *   the gateway, the cloud endpoints, the serving and OAuth lines). It never
+ *   reads a key itself, so `--auto` cannot disagree with the doctor.
+ *
+ * WHAT IT NEVER DOES:
+ *   print a value. Guides carry variable NAMES and SHAPES; detection carries
+ *   names and set/unset. Writing `.env` (writeEnvForLevel) copies
+ *   `.env.example`, leaves every chosen name blank, refuses to overwrite an
+ *   existing file, and refuses unless `git check-ignore` says `.env` is
+ *   ignored (secrets-hygiene).
+ */
+import type { DoctorResult, Tier } from './doctor.ts';
+export type LevelId = 'local' | 'one-provider' | 'several-providers' | 'gateway' | 'cloud-platform' | 'byok' | 'caller-tokens' | 'oauth-grants' | 'chatgpt-signin' | 'subscription-signin';
+/** How a command is spelled: in a project that installed the package, or in a clone of the repository. */
+export type CommandForm = 'package' | 'clone';
+export interface EnvLine {
+    name: string;
+    /** The shape of the value, never a value. */
+    shape: string;
+    /** What setting it does. */
+    purpose: string;
+}
+export interface Level {
+    id: LevelId;
+    /** The menu line: what the user has. */
+    menu: string;
+    title: string;
+    summary: string;
+    env: EnvLine[];
+    /** What the doctor shows when this level is set up. */
+    confirm: string;
+    /** Shipped syndicates that run at this level, rendered by `shippedFor`. */
+    runs: (shipped: ShippedIndex) => string[];
+    first: Record<CommandForm, string[]>;
+    notes: string[];
+    /** The onboarding skill a coding agent follows for this level. */
+    skill: string;
+    /** False for an entry that is not a way to run the engine (the unsupported subscription sign-ins). */
+    detectable: boolean;
+}
+/** Shipped templates and examples by the tier their models imply, and which declare an OAuth grant. */
+export interface ShippedIndex {
+    byTier: Partial<Record<Tier, string[]>>;
+    withGrants: string[];
+    /** Files that carry a commented-out `oauth2:` grant to start from. */
+    grantExamples: string[];
+    templates: string[];
+}
+/** The package (or clone) root: the directory holding config/agents/syndicate.schema.json. */
+export declare function packageRoot(from?: string): string;
+/**
+ * Index the shipped templates and examples by tier, using the doctor's own
+ * diagnosis (lib/doctor.ts `diagnoseSyndicate`: the tier the models imply,
+ * and the OAuth grants the tools declare). The tier does not depend on the
+ * environment, so the index is the same wherever it is computed.
+ */
+export declare function shippedIndex(root?: string): ShippedIndex;
+export declare const LEVELS: readonly Level[];
+export declare function levelById(id: string): Level | undefined;
+/** Every variable name the guides mention. */
+export declare function guideEnvNames(): string[];
+/** One level's startup guide, as Markdown (the terminal prints the same text). */
+export declare function renderGuide(level: Level, form: CommandForm, shipped?: ShippedIndex): string;
+/** The menu: one numbered line per level. */
+export declare function renderMenu(): string;
+/** ONBOARDING.md, generated in full from the levels (package spelling). */
+export declare function renderOnboardingDoc(shipped?: ShippedIndex): string;
+export interface LevelDetection {
+    id: LevelId;
+    detected: boolean;
+    /** Names and set/unset only. */
+    evidence: string;
+    /** The doctor's problems for this level, by variable name. */
+    problems: string[];
+}
+/**
+ * Which levels the environment is set up for, read from the doctor's result.
+ * Local is always available (whether Ollama is running is not checked).
+ */
+export declare function detectLevels(result: DoctorResult): LevelDetection[];
+/** The highest detected level (the last in menu order). */
+export declare function highestLevel(detections: LevelDetection[]): Level;
+/** `--auto`: what the environment has (names only), then the guide for the highest level. */
+export declare function renderAuto(result: DoctorResult, form: CommandForm, shipped?: ShippedIndex): string;
+export type EnvWriteResult = {
+    status: 'written';
+    path: string;
+    added: string[];
+} | {
+    status: 'exists';
+    path: string;
+} | {
+    status: 'not-ignored';
+    path: string;
+    reason: string;
+} | {
+    status: 'no-template';
+    path: string;
+};
+/** True when git confirms `.env` in `cwd` is ignored (exit 0 from `git check-ignore`). */
+export declare function gitIgnoresEnv(cwd: string): {
+    ignored: boolean;
+    reason: string;
+};
+/**
+ * Create `.env` from `.env.example` for a level: the template verbatim, then
+ * every name the level lists that the template does not already assign, left
+ * blank. Never overwrites, never writes a value, and refuses unless git
+ * confirms `.env` is ignored. The file is created mode 600.
+ */
+export declare function writeEnvForLevel(level: Level, opts?: {
+    cwd?: string;
+    root?: string;
+    checkIgnored?: (cwd: string) => {
+        ignored: boolean;
+        reason: string;
+    };
+}): EnvWriteResult;