@exposify/cli 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Exposify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,10 @@
-# Temporary Holding Version
+# @exposify/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The framework-neutral engine behind `exposify-express` and `exposify-next`:
+the endpoint checklist, the startup-log question, config + clipboard + verify,
+tool descriptions (`describe`), and `inspect` snapshots. You don't use it
+directly: install an adapter (`@exposify/express`, `@exposify/nestjs`,
+`@exposify/next`) and run its command.
+
+An adapter implements `CliAdapter` (`locate`, `scan`, `configStep`) and its bin
+calls `runCli(process.argv.slice(2), adapter)`.

package/dist/index.d.ts

@@ -0,0 +1,318 @@
+/** A source location in the user's code, from a stack trace. */
+interface CallSite {
+    file: string;
+    line: number;
+}
+type MarkerKind = "exposed" | "hidden" | "described";
+interface ScannedRoute {
+    method: string;
+    path: string;
+    params: string[];
+    /** Set when the route is wrapped in exposed()/hidden()/describe() in code. */
+    marker?: MarkerKind;
+    /** describe()'s own name/description, when given. */
+    describedName?: string;
+    describedText?: string;
+    /** The matching OpenAPI operation's summary/description, from aiReady({ openapi }). */
+    openApiText?: string;
+    /** The tool name it gets (or would get) under the current config. */
+    tool: string;
+    /** deriveDescription()'s text, the fallback an agent sees today. */
+    derived?: string;
+    /** Exposure under the app's current aiReady() options (defaults if none). */
+    exposed: boolean;
+    /** Exposed only when listed in `expose`, even a read (core's RouteInfo.optIn), e.g. a Pages Router method detected in code. */
+    optIn?: boolean;
+    /** "page": an App Router page read as a tool (its HTML, like a browser), not a route handler. */
+    kind?: "page";
+    reason: string;
+    /** The route's own handler (last in its stack) as source text, capped; for `describe`. */
+    source?: string;
+    /** Names of the functions ahead of it on the route (e.g. auth middleware). */
+    middleware?: string[];
+}
+/**
+ * A server-side function agents can call besides routes (Next.js Server
+ * Actions). The adapter works out everything here; the CLI only shows it,
+ * lets the user pick, and checks it.
+ */
+interface ScannedAction {
+    /** The key it's listed under in `aiReady({ actions })`. */
+    configKey: string;
+    /** Where it's defined, e.g. "placeOrder" in app/actions/checkout.ts:12. */
+    export: string;
+    file: string;
+    line: number;
+    /** The tool name it gets (or would get). */
+    tool: string;
+    /** What its tool call is, for the snapshot: "POST /mcp/actions/place_order". */
+    route: string;
+    /**
+     * complete: its input is known from its code and forms; partial: some of
+     * it isn't (see notes); flagged: it looks like sign-in/out, or takes a file.
+     */
+    status: "complete" | "partial" | "flagged";
+    /** One line each: what's unresolved, which forms submit to it, why it's flagged. */
+    notes: string[];
+    /** Set when exposed()/hidden()/describe() in code decides it. */
+    marker?: MarkerKind;
+    exposed: boolean;
+    reason: string;
+    /** Where its hand-written input and the scan disagree. */
+    drift: string[];
+    /** Its `actions` entry to paste, key included: `placeOrder: true,`, or `{ input: { … } }` with TODO lines for the gaps. */
+    stub: string;
+    /** Its source, capped; for `describe`. */
+    source?: string;
+    /** A description set in config or describe(): `describe` leaves it alone. */
+    describedText?: string;
+    /**
+     * An input `describe` can propose: set for an action that's opted in but
+     * whose input the scan can't complete (and isn't written). `status` is
+     * whether exposify.descriptions.json already has an accepted one.
+     */
+    proposal?: {
+        status: "needed" | "current" | "stale";
+        /** The files `request.forms` was read from, project-relative: named when asking before sending. */
+        formFiles?: string[];
+        /** What the service gets (source is masked before sending). */
+        request: {
+            name: string;
+            file: string;
+            source?: string;
+            forms?: string[];
+            fields: Array<{
+                name: string;
+                type: string;
+                required?: boolean;
+                enum?: string[];
+            }>;
+            unresolved: string[];
+        };
+    };
+}
+/** The JSON-safe part of the current aiReady() options. */
+interface CurrentOptions {
+    expose?: string[] | "*";
+    exclude?: string[];
+    startupLog?: boolean;
+    /** The keys listed in `actions` (Server Actions). */
+    actions?: string[];
+    /** Other option keys present (auth, oauth, mounts, ...): kept as-is by the wizard. */
+    otherKeys: string[];
+}
+/** What every adapter's scan reports; adapters extend it with their own facts (e.g. Express's `uses`). */
+interface ScanResult {
+    ok: true;
+    /** Set when the app threw during boot after registering routes; routes up to then are scanned. */
+    crashed?: string;
+    /** Things the adapter couldn't turn into routes, printed after the count, e.g. handlers whose methods weren't detected. */
+    notes?: string[];
+    /** The current aiReady() call, when there is one. */
+    aiReady?: {
+        site?: CallSite;
+        options: CurrentOptions;
+    };
+    routes: ScannedRoute[];
+    /** Server Actions (Next.js), when the framework has them. */
+    actions?: ScannedAction[];
+    /** Printed under the actions when any is exposed or picked, e.g. that middleware path rules don't cover them. */
+    actionsNote?: string;
+    /** Code changes the scan suggests (e.g. moving an inline Server Action into its own file): `setup` prints them, nothing applies them. */
+    suggestions?: Array<{
+        title: string;
+        diff: string;
+    }>;
+    /**
+     * The app's own login, as the adapter found it: with the hosted broker, AI
+     * assistants sign in with it on a form at `/mcp/login` (Connect with no code).
+     */
+    login?: {
+        what: string;
+        fields: string[];
+        others?: string[];
+    };
+}
+interface ScanFailure {
+    ok: false;
+    error: string;
+    /** A one-line suggestion. */
+    fix?: string;
+}
+type ScanMessage<R extends ScanResult = ScanResult> = R | ScanFailure;
+
+interface WizardConfig {
+    expose?: string[] | "*";
+    exclude?: string[];
+    startupLog?: false;
+    /** Server Actions to list in `actions`, by config key; the adapter renders their entries. */
+    actions?: string[];
+}
+interface BuiltConfig {
+    config: WizardConfig;
+    /** Existing glob excludes dropped because they'd hide a ticked route. */
+    droppedGlobs: string[];
+}
+/**
+ * The minimal config for `selected`:
+ * - ticked writes go in `expose` (an explicit list unless `nuclear`), and
+ *   so do ticked opt-in rows, reads included (`expose: "*"` skips those);
+ * - un-ticked reads, and in nuclear mode un-ticked writes too, become
+ *   method-qualified `exclude` entries (they beat `expose`);
+ * - existing glob excludes are kept, since they also cover future routes,
+ *   unless one would hide a route that's now ticked;
+ * - rows with a marker in code are left out: the marker decides them.
+ */
+declare function buildConfig(routes: ScannedRoute[], selected: Set<string>, opts: {
+    nuclear: boolean;
+    startupLog: boolean;
+    current?: CurrentOptions;
+}): BuiltConfig;
+/** Which routes `config` exposes, by core's own policy: used to check buildConfig and to verify a paste. */
+declare function exposedUnder(routes: ScannedRoute[], config: WizardConfig): Set<string>;
+/**
+ * The aiReady() call to paste. `importFrom` adds the import line (the app
+ * doesn't import aiReady yet), from that package.
+ */
+declare function renderConfig(config: WizardConfig, opts: {
+    importFrom?: string;
+    otherKeys?: string[];
+}): string;
+/** The option lines `config` adds to aiReady({ … }), indented two spaces, as `setup` writes them (and `--apply` edits in). */
+declare function renderProps(config: WizardConfig): string[];
+
+/** Where to put the config: what an adapter tells the user in step 3. */
+interface PasteHint {
+    /** Sentences to print, the first one a full instruction. */
+    lines: string[];
+    /** A problem with the current placement, e.g. aiReady after the routers on Express 5. */
+    warning?: string;
+}
+
+/** One file edit, computed ahead of time so setup can say what it would do. */
+interface ApplyPlan {
+    file: string;
+    /** For the prompt: "Replace the aiReady() options in src/server.ts". */
+    summary: string;
+    /** The file as the plan saw it; null when the plan creates it. Writing refuses if it changed since. */
+    before: string | null;
+    after: string;
+}
+/** Either a plan, or why this one can't be applied safely (setup then prints the paste instructions). */
+type ApplyOutcome = {
+    plan: ApplyPlan;
+} | {
+    blocked: string;
+};
+interface ReplaceCallInput {
+    source: string;
+    file: string;
+    /** The call's line, from the scan. */
+    line: number;
+    /** Function names the call may have: ["aiReady"], or ["mountAiReady"] for @exposify/nestjs. */
+    callNames: string[];
+    /** Which argument is the options object (aiReady({ … }) is 0, aiReady(exposify, { … }) is 1). */
+    optionsArg: number;
+    config: WizardConfig;
+    /** Server Actions: config key -> the entry to write, for a key that has none yet (an existing entry is kept as written). */
+    actionEntries?: Record<string, string>;
+    /** An import to make sure is there (e.g. zod, when an action stub uses it). */
+    needsImport?: {
+        from: string;
+        name: string;
+    };
+}
+/**
+ * Rewrites the options of an existing aiReady() call to `config`. Only the
+ * options setup manages (expose, exclude, startupLog, and actions when the
+ * adapter passes entries) are replaced; everything else the user wrote stays.
+ */
+declare function replaceAiReadyOptions(input: ReplaceCallInput): {
+    after: string;
+} | {
+    blocked: string;
+};
+interface InsertCallInput {
+    source: string;
+    file: string;
+    /** The statement to add, e.g. `app.use(aiReady({ … }));`, written for an app variable called `app`. */
+    code: string;
+    importFrom: string;
+    /** Insert above the statement that starts on this line (required on Express 5: aiReady must come before the routers)… */
+    beforeLine?: number;
+    /** …else after the statement that starts on this line. */
+    afterLine?: number;
+    /** The line where the app is created, to learn what the app variable is called. */
+    createdLine?: number;
+}
+/** Adds a new `app.use(aiReady(…))` statement, and its import, to the file that creates the app. */
+declare function insertAiReadyCall(input: InsertCallInput): {
+    after: string;
+} | {
+    blocked: string;
+};
+
+interface AppLocation {
+    /** The file the scan starts from (an entry file, or the app directory). */
+    entry: string;
+    /** The project root: where the descriptions file and snapshot live. */
+    root: string;
+    /** How it was found, e.g. "scripts.dev" or "nest-cli.json". */
+    via: string;
+}
+type AdapterScanOutcome<R extends ScanResult = ScanResult> = {
+    ok: true;
+    result: R;
+} | {
+    ok: false;
+    error: string;
+    fix?: string;
+    output?: string;
+    loader?: string;
+};
+interface ConfigStepInput<R extends ScanResult = ScanResult> {
+    result: R;
+    config: WizardConfig;
+    current?: CurrentOptions;
+    root: string;
+    readLine: (site: CallSite) => string | undefined;
+}
+interface CliAdapter<R extends ScanResult = ScanResult> {
+    /** The command name, e.g. "exposify-express". */
+    bin: string;
+    /** An example for "pass it explicitly", e.g. "src/server.ts". */
+    entryExample: string;
+    /** What `--entry` names, for the usage text, e.g. "The file that creates your Express app". */
+    entryHelp: string;
+    locate(cwd: string, entryFlag?: string): AppLocation | undefined;
+    scan(location: AppLocation, env: Record<string, string>): Promise<AdapterScanOutcome<R>>;
+    /**
+     * Step 3: the code to paste, and where it goes. `apply` is the same change
+     * made in the user's own file (`setup --apply`): a plan, or why it can't be
+     * done safely. Omit it when an adapter can't edit code.
+     */
+    configStep(input: ConfigStepInput<R>): {
+        code: string;
+        hint: PasteHint;
+        apply?: ApplyOutcome;
+    };
+}
+
+/** CI providers set CI (GitHub Actions, GitLab, CircleCI, Buildkite, ...); "false"/"0" opt out. */
+declare function isCiEnv(env: NodeJS.ProcessEnv): boolean;
+/** Runs the CLI for `forAdapter`; resolves to the exit code. */
+declare function runCli<R extends ScanResult>(argv: string[], forAdapter: CliAdapter<R>, cwd?: string): Promise<number>;
+
+declare const routeKey: (r: Pick<ScannedRoute, "method" | "path">) => string;
+declare const isRead: (r: Pick<ScannedRoute, "method">) => boolean;
+/** Rows whose exposure is set in code (exposed()/hidden()/describe()); config can't change them. */
+declare function isLocked(r: Pick<ScannedRoute, "marker">): boolean;
+
+/**
+ * What a description was written from: method, path, params and the
+ * handler's source. A change means the text may no longer be true. Only
+ * staleness uses it; it never decides precedence.
+ */
+declare function signatureFor(route: Pick<ScannedRoute, "method" | "path" | "params" | "source">): string;
+
+export { type AdapterScanOutcome, type AppLocation, type ApplyOutcome, type ApplyPlan, type BuiltConfig, type CallSite, type CliAdapter, type ConfigStepInput, type CurrentOptions, type MarkerKind, type PasteHint, type ScanFailure, type ScanMessage, type ScanResult, type ScannedAction, type ScannedRoute, type WizardConfig, buildConfig, exposedUnder, insertAiReadyCall, isCiEnv, isLocked, isRead, renderConfig, renderProps, replaceAiReadyOptions, routeKey, runCli, signatureFor };