appilot-mcp 0.1.1 → 0.3.0

package/dist/scaffold.d.ts

@@ -10,8 +10,23 @@
  * integration a developer must write in their own backend, it is
  * security-critical, and getting it wrong is invisible until an auth edge case
  * shows up in production.
+ *
+ * Everything returned here has to COMPILE. Three of the six framework outputs
+ * did not typecheck under `strict` when the 2026-09-07 audit ran them through
+ * `tsc`, and the relay, the piece a developer is least able to review, was the
+ * file that failed. `test/scaffoldTypecheck.test.ts` now compiles every output
+ * against the workspace sources of `appilot` and `appilot-server`.
+ */
+/**
+ * The frameworks with a first-class relay, plus `other`.
+ *
+ * `appilot-server` is a Node package, so a Django, Rails or PHP host cannot use
+ * it. That is not a reason to answer a raw Zod enum dump: the exchange is one
+ * authenticated HTTPS call, and `other` returns it as curl plus a Python and a
+ * Ruby handler.
  */
-export type Framework = 'next' | 'express' | 'fastify' | 'hono' | 'remix' | 'sveltekit';
+export declare const SCAFFOLD_FRAMEWORKS: readonly ["next", "express", "fastify", "hono", "remix", "sveltekit", "other"];
+export type Framework = (typeof SCAFFOLD_FRAMEWORKS)[number];
 export interface ScaffoldFile {
     /** Suggested path, relative to the repository root. The agent may move it. */
     path: string;
@@ -34,4 +49,98 @@ interface ScaffoldOptions {
     idNamespace?: string;
 }
 export declare function scaffoldIntegration(options: ScaffoldOptions): ScaffoldResult;
+/**
+ * `scaffold_agent_first`: the four pieces one capability needs, together.
+ *
+ * `scaffoldIntegration` above returns the integration. It does not return the
+ * shape of an agent-first application, and the two are not the same thing. A
+ * capability that a user can complete through the assistant alone is four
+ * artifacts that have to agree with each other: the way the agent calls the
+ * backend, the way the page acts in the user's own session, the procedure the
+ * agent follows in the interface, and the meaning behind it.
+ *
+ * The split between the last two is the rule that is easiest to state and
+ * easiest to break. The Action Plan is the procedure. Knowledge carries meaning.
+ * A step-by-step knowledge article is a procedure in the wrong place, and it
+ * teaches the agent to author steps instead of adopting the plan that already
+ * exists. Emitting both halves correctly is how a scaffold teaches that once.
+ *
+ * Everything emitted here is in the shape the API accepts, and
+ * `test/scaffoldAgentFirst.test.ts` proves it by running the output through the
+ * shared action-plan schemas and through the health contract. The previous
+ * version emitted `{ title, steps: [{ text }] }` sections and a `form_values`
+ * entry with no `fields`, so the tool meant to make an app agent-first produced
+ * a plan `create_entity` rejected and `runHealthContract` crashed on.
+ */
+export interface AgentFirstScaffold {
+    capability: string;
+    shape: CapabilityShape;
+    /** Ready for `create_entity({ kind: 'tool' })`, minus the credential. Null for a page-only capability. */
+    tool: Record<string, unknown> | null;
+    /** Ready for `create_entity({ kind: 'action_plan' })` once the control ids exist. Null when the capability has no in-page procedure. */
+    actionPlan: Record<string, unknown> | null;
+    /** Ready for `create_entity({ kind: 'knowledge' })`. */
+    knowledge: Record<string, unknown>;
+    files: ScaffoldFile[];
+    order: string[];
+    notes: string[];
+}
+/**
+ * What the capability does to the app, which decides whether a plan makes sense
+ * and what its steps are.
+ *
+ * `create` is a form the user fills and submits. `navigate` takes them to a
+ * place. `read` answers a question, and it gets NO action plan: a plan whose
+ * only step opens a screen does nothing, and the health contract says so. The
+ * scaffold used to emit the open/fill/submit template for all three, so asking
+ * it for "Show a booking" produced a plan that filled a form nobody had.
+ */
+export type CapabilityShape = 'create' | 'navigate' | 'read';
+interface AgentFirstOptions {
+    /** What the user is trying to do, in their words. */
+    capability: string;
+    /** Short English slug, used for the tool name and the plan id. */
+    slug: string;
+    appId: number | null;
+    /**
+     * The host endpoint the agent should reach, as a PATH on the host origin.
+     * The executor rejects an absolute URL: a server-side tool call is proxied
+     * to the app's own origin, never to an arbitrary host.
+     */
+    endpoint?: {
+        method: string;
+        path: string;
+    } | null;
+    /** True when the operation is UI-coupled and belongs in the page instead. */
+    clientSide?: boolean;
+    /** What the capability does. Defaults to `create`. */
+    shape?: CapabilityShape;
+    /** Where the plan's steps run. Defaults to `/`. */
+    viewPath?: string;
+}
+export declare function scaffoldAgentFirst(options: AgentFirstOptions): AgentFirstScaffold;
+export interface IntegrationSnippet {
+    apiUrl: string | null;
+    scriptTag: string;
+    bootSnippet: string;
+    tokenEndpointHint: string;
+    publicEnvName: string;
+    notes: string[];
+}
+/**
+ * The script tag and the boot call for an app that is already provisioned.
+ *
+ * `create_app` returns these, and returning them was the only way to get them,
+ * so a developer who had lost the snippet re-ran a provisioning write to read
+ * one line of HTML. They are composed from the connection and the key, so this
+ * is pure: it calls nothing and needs no scope. The shape matches what the
+ * backend's own `buildIntegration` returns, deliberately, so a curl caller and
+ * an agent read the same thing.
+ */
+export declare function integrationSnippet(options: {
+    widgetScriptUrl: string;
+    apiUrl?: string | null;
+    widgetKey?: string | null;
+    framework?: Framework;
+}): IntegrationSnippet;
 export {};