crumbtrail 0.1.0

package/dist/cli.d.cts

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+import { R as Recipe, D as DetectResult, P as PackageManager, b as buildPlan, e as executePlan } from './executor-DKDrkhxM.cjs';
+import { Stack } from 'crumbtrail-design-system';
+
+/** Output sink — swappable in tests to capture lines instead of writing stdout. */
+interface Ui {
+    out(line?: string): void;
+    err(line?: string): void;
+    /**
+     * Rewrite a transient single-line status in place (a live "Waiting… 12s"
+     * ticker). TTY-only; calling with no argument clears the line. Callers MUST
+     * clear before the next out()/err() or the lines collide.
+     */
+    status?(line?: string): void;
+}
+/** One row of a `multiSelect` list. */
+interface MultiSelectItem {
+    /** Primary text, e.g. "apps/web". */
+    label: string;
+    /** Trailing detail, e.g. "next" or "already wired — skipping". */
+    hint?: string;
+    /** Whether this row starts checked (drives the empty-input default). */
+    checked: boolean;
+    /**
+     * False for rows we can list but cannot wire (no recipe matched). Rendered
+     * greyed out and rejected if the user names them explicitly — listing them is
+     * how we show the scan wasn't blind to the package.
+     */
+    selectable: boolean;
+}
+/** Prompts the wizard needs — injectable so tests answer without a TTY. */
+interface Prompter {
+    /** Free-text with a default; empty input returns the default. */
+    ask(question: string, def?: string): Promise<string>;
+    /** Yes/no; empty input returns `def`. */
+    confirm(question: string, def?: boolean): Promise<boolean>;
+    /** 1-based numeric choice among labels; empty input returns `def` (0-based). */
+    select(question: string, labels: string[], def?: number): Promise<number>;
+    /**
+     * 1-based multi-choice; returns 0-based indices. Empty input takes the
+     * checked defaults. Number-list based (no raw mode / arrow keys anywhere in
+     * this CLI).
+     */
+    multiSelect(question: string, items: MultiSelectItem[]): Promise<number[]>;
+}
+
+interface LoginOptions {
+    base: string;
+    ui: Ui;
+    noBrowser?: boolean;
+    fetchImpl?: typeof fetch;
+    /** Injected browser opener (tests). */
+    openFn?: (url: string) => boolean | Promise<boolean>;
+    env?: NodeJS.ProcessEnv;
+    /** Device-poll interval override for tests (ms). */
+    pollIntervalMs?: number;
+    /** Browser hand-off deadline in ms (default 5 min); overridable in tests. */
+    browserDeadlineMs?: number;
+}
+/**
+ * Resolve a usable CLI token for `base`: reuse a stored token (validated by a
+ * cheap GET /api/projects, and only if it was minted for THIS endpoint), else
+ * run the login flow and persist the result. A stored token that 401s is
+ * cleared and re-minted.
+ */
+declare function ensureToken(opts: LoginOptions): Promise<string>;
+
+interface Project {
+    id: string;
+    name: string;
+}
+interface ProvisionInput {
+    base: string;
+    token: string;
+    recipe: Recipe;
+    /**
+     * The detected non-JS backend Stack for the `otlp` recipe
+     * (`DetectResult.otlpStack`). When set it OVERRIDES the static
+     * `RECIPE_REGISTRY[recipe].stack` placeholder on the createService call — this
+     * is how the single otlp recipe reports its variable Stack to the service.
+     */
+    stack?: Stack | null;
+    ui: Ui;
+    prompter: Prompter;
+    /** Skip prompts (non-interactive / --yes). */
+    assumeYes: boolean;
+    /** --project <id>: skip creation, attach a service to this project. */
+    projectId?: string;
+    /** Inferred defaults (from detection / package.json / git). */
+    defaultProjectName: string;
+    defaultServiceName: string;
+    fetchImpl?: typeof fetch;
+}
+interface ProvisionResult {
+    projectId: string;
+    projectName: string;
+    serviceId: string;
+    serviceName: string;
+    apiKey: string;
+}
+interface ResolveProjectInput {
+    base: string;
+    token: string;
+    ui: Ui;
+    prompter: Prompter;
+    assumeYes: boolean;
+    projectId?: string;
+    defaultProjectName: string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Resolve the project a service will report to: explicit --project, an
+ * interactive pick among existing projects, or a freshly created one.
+ *
+ * Split out of provisionFlow so the batch installer can resolve ONE project and
+ * then mint many services under it.
+ */
+declare function resolveProject(input: ResolveProjectInput): Promise<Project>;
+interface ProvisionServiceInput {
+    base: string;
+    token: string;
+    projectId: string;
+    recipe: Recipe;
+    /** Detected otlp stack; overrides the registry placeholder. */
+    stack?: Stack | null;
+    serviceName: string;
+    ui: Ui;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Add one service to an already-resolved project and mint its ingest key.
+ * Prompt-free by design: the batch installer names services from detection
+ * rather than asking N times.
+ */
+declare function provisionService(input: ProvisionServiceInput): Promise<{
+    serviceId: string;
+    serviceName: string;
+    apiKey: string;
+}>;
+/**
+ * Resolve a project, add a service to it, and mint the ingest key returned to
+ * the wizard for injection + summary. Composed from resolveProject +
+ * provisionService so the single-package path keeps its exact behavior
+ * (including the interactive "Service name" prompt).
+ */
+declare function provisionFlow(input: ProvisionInput): Promise<ProvisionResult>;
+
+interface IngestPollConfig {
+    /** Delay before the first poll, and the backoff step size. */
+    initialDelayMs: number;
+    /** Upper bound on the per-attempt delay. */
+    maxDelayMs: number;
+    /** Give up (→ "timedout") once cumulative waiting reaches this. */
+    timeoutMs: number;
+}
+
+/**
+ * Push a synthetic marker session through real ingest (start → one event → end)
+ * with the minted key, emulating crumbtrail-core's HttpTransport wire format
+ * (X-Crumbtrail-Auth header, {sessionId, events}). Throws if any leg fails —
+ * that proves the key/endpoint/network are wrong before the user wastes time.
+ */
+declare function syntheticCheck(base: string, apiKey: string, fetchImpl?: typeof fetch): Promise<void>;
+type RealEventOutcome = "found" | "timedout" | "cancelled";
+interface PollRealEventResult {
+    outcome: RealEventOutcome;
+    /** Set when outcome is "found" — the session behind the first real event. */
+    sessionId?: string;
+}
+interface PollRealEventOptions {
+    base: string;
+    token: string;
+    projectId: string;
+    ui: Ui;
+    /**
+     * Ms epoch captured at wizard entry. Only sessions started at/after this count
+     * as "the first real event" — a session from a prior run is ignored.
+     */
+    wizardStart?: number;
+    signal?: AbortSignal;
+    config?: IngestPollConfig;
+    fetchImpl?: typeof fetch;
+    /** Injected delay (tests); defaults to a real, abortable setTimeout. */
+    sleepFn?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * Poll the sessions feed until a real (non-synthetic) session lands, the backoff
+ * budget is exhausted, or the caller aborts (Ctrl-C). The timing policy is the
+ * ported poll.ts state machine. On a TTY, a live elapsed-time status line keeps
+ * a long wait from reading as a hang.
+ */
+declare function pollForRealEvent(opts: PollRealEventOptions): Promise<PollRealEventResult>;
+interface PollServicesOptions extends Omit<PollRealEventOptions, "wizardStart"> {
+    wizardStart?: number;
+    /** The services we just wired and expect events from. */
+    serviceIds: string[];
+    /** Fired once per service, the first time its event lands. */
+    onFound?: (serviceId: string, sessionId: string) => void;
+}
+interface PollServicesResult {
+    /** "found" only when EVERY serviceId reported. */
+    outcome: RealEventOutcome;
+    /** serviceId → sessionId, for however many reported before we stopped. */
+    found: Record<string, string>;
+}
+/**
+ * Poll once for the whole batch until every wired service has reported, the
+ * shared budget is exhausted, or the user aborts. Timeout and cancel both return
+ * whatever arrived — stragglers never block the wizard from finishing, because
+ * the wiring is already done by the time we get here.
+ */
+declare function pollForServices(opts: PollServicesOptions): Promise<PollServicesResult>;
+
+type CandidateSource = "workspace" | "scan";
+type CandidateFlag = "ambiguous" | "otlp" | "likely-library" | "already-wired" | "no-recipe";
+interface ServiceCandidate {
+    /** Absolute path to the service directory. */
+    dir: string;
+    /** package.json name, falling back to the directory basename. */
+    name: string;
+    /** Path relative to the repo root — used for labels and `--only` matching. */
+    relDir: string;
+    source: CandidateSource;
+    /** The real detect() output for this dir, not a synthesized one. */
+    detected: DetectResult;
+    recipe: Recipe | null;
+    flags: CandidateFlag[];
+    /** Pre-checked in the multi-select list. */
+    defaultChecked: boolean;
+    /** False when nothing can be wired here (no recipe matched). */
+    selectable: boolean;
+}
+interface DiscoverDeps {
+    detect?: (cwd: string) => DetectResult;
+    /** True when this dir already depends on a Crumbtrail SDK. */
+    alreadyWired?: (dir: string) => boolean;
+    readDir?: (dir: string) => string[];
+    isDir?: (p: string) => boolean;
+    isFile?: (p: string) => boolean;
+}
+/**
+ * Every service Crumbtrail can see from the repo root: real workspaces first (by
+ * path), then non-JS services found by the conventional-dir scan.
+ */
+declare function discoverServices(root: string, rootResult: DetectResult, overrides?: DiscoverDeps): ServiceCandidate[];
+
+type Command = "wizard" | "login" | "logout" | "help" | "version";
+interface ParsedArgs {
+    command: Command;
+    yes: boolean;
+    project?: string;
+    noBrowser: boolean;
+    skipVerify: boolean;
+    endpoint?: string;
+    /**
+     * Monorepo root only: wire exactly these services (repeatable `--only`,
+     * matched against a service's package name or path). Also the non-interactive
+     * escape hatch — a root run in CI must name its services somehow.
+     */
+    only?: string[];
+    /** Monorepo root only: select every wireable service, no prompt. */
+    all: boolean;
+    /** Non-flag/subcommand leftover — an unknown token triggers usage help. */
+    unknown?: string;
+}
+declare function parseArgs(argv: string[]): ParsedArgs;
+interface InstallSdkInput {
+    cwd: string;
+    packageManager: PackageManager | null;
+    recipe: Recipe;
+    base: string;
+    ui: Ui;
+    /** Injected runner (tests); returns the child exit code. */
+    spawnFn?: (cmd: string, args: string[], cwd: string) => number;
+    /** Injected fetch for the tarball-manifest fallback (tests); defaults to global. */
+    fetchImpl?: typeof fetch;
+}
+interface InstallSdkResult {
+    installed: boolean;
+    packages: string[];
+    note?: string;
+}
+/**
+ * Install the SDK with the detected package manager. If the registry install
+ * fails (e.g. packages not yet public, or a self-hosted endpoint), fall back to
+ * installing the deploy's packed tarballs — discovered via
+ * `GET <base>/install/manifest.json` — so a fresh deploy wires up before the
+ * packages are on npm. Every recipe's SDK (including react-native and tauri, now
+ * packed as optional channels by pack-local.mjs) is resolved by name prefix from
+ * that manifest, so the fallback is uniform. Non-fatal either way, since
+ * injection only writes import statements.
+ */
+declare function installSdk(input: InstallSdkInput): Promise<InstallSdkResult>;
+interface WizardDeps {
+    detect: (cwd: string) => DetectResult;
+    ensureToken: typeof ensureToken;
+    provisionFlow: typeof provisionFlow;
+    installSdk: (input: InstallSdkInput) => Promise<InstallSdkResult>;
+    buildPlan: typeof buildPlan;
+    executePlan: typeof executePlan;
+    syntheticCheck: typeof syntheticCheck;
+    pollForRealEvent: typeof pollForRealEvent;
+    /** Batch path (monorepo root). */
+    discoverServices: typeof discoverServices;
+    resolveProject: typeof resolveProject;
+    provisionService: typeof provisionService;
+    pollForServices: typeof pollForServices;
+    /** Browser opener for the end-of-wizard dashboard hand-off (stub in tests). */
+    openBrowserFn?: (url: string) => Promise<boolean>;
+    ui: Ui;
+    prompter: Prompter;
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    isTTY: boolean;
+    fetchImpl?: typeof fetch;
+}
+declare function defaultDeps(): WizardDeps;
+declare function runWizard(parsed: ParsedArgs, deps: WizardDeps): Promise<number>;
+type ServiceStatus = "wired" | "guidance" | "skipped-already-wired" | "failed";
+interface ServiceOutcome {
+    name: string;
+    relDir: string;
+    recipe: Recipe;
+    status: ServiceStatus;
+    serviceId?: string;
+    apiKey?: string;
+    filesTouched: string[];
+    notes: string[];
+    error?: string;
+    sessionUrl?: string;
+}
+/**
+ * Resolve --only/--all into indices, or null when we should prompt.
+ * Returns a string on a user error (unknown --only value).
+ */
+declare function resolveSelection(parsed: ParsedArgs, candidates: ServiceCandidate[]): {
+    indices: number[];
+} | {
+    error: string;
+} | null;
+interface BatchContext {
+    base: string;
+    wizardStart: number;
+    root: DetectResult;
+}
+/**
+ * The monorepo path: scan → pick → one login → one project → wire each selected
+ * service → one shared wait → summary.
+ *
+ * A failure on one service never sinks the batch (each is try/caught and
+ * recorded), because a half-wired repo with a clear report is strictly better
+ * than an abort that leaves the user guessing which services made it.
+ */
+declare function runBatchWizard(parsed: ParsedArgs, deps: WizardDeps, ctx: BatchContext): Promise<number>;
+declare function runCli(argv: string[], deps?: WizardDeps): Promise<number>;
+declare function isCliEntrypoint(argv1: string | undefined): boolean;
+
+export { type Command, type InstallSdkInput, type InstallSdkResult, type ParsedArgs, type ServiceOutcome, type ServiceStatus, type WizardDeps, defaultDeps, installSdk, isCliEntrypoint, parseArgs, resolveSelection, runBatchWizard, runCli, runWizard };